Harden AgentFanout worker dispatch routing

.github/pull_request_template.md

@@ -8,6 +8,19 @@
 - [ ] `python3 -m py_compile scripts/route.py tests/run_tests.py`
 - [ ] `scripts/github-preflight.sh`
 
+## Public Release Gate
+
+For maintainer-originated or synced GitHub-facing changes:
+
+- [ ] Local source PR/review completed before this GitHub-facing update.
+- [ ] Full security audit completed on the local PR/diff.
+- [ ] Audit result documented with reviewer, date, commit/PR reference, findings, remediation, and pass/fail status.
+- [ ] No GitHub branch, pull request, tag, release, or public export was created or updated before the local gate passed.
+
+For external contributor PRs:
+
+- [ ] Maintainer will complete the local source review gate before merge or release.
+
 ## Safety Checklist
 
 - [ ] Does not delegate MCP/private tools to workers.

CONTRIBUTING.md

@@ -36,6 +36,26 @@ AgentFanout's core safety model is intentional:
 
 Worker prompts must stay small, scoped, and free of private-tool context, automatic memory, secrets, callback hooks, and voice/notification instructions.
 
+## Public Release Gate
+
+AgentFanout is public-facing. Maintainer-originated GitHub-facing changes must pass the local source review gate before any GitHub branch, pull request, tag, release, or public export is created or updated.
+
+Before GitHub-facing activity, maintainers must:
+
+1. Prepare the change in the canonical local source repository.
+2. Review the change through the local source PR/review process.
+3. Complete the full security audit on that local PR/diff.
+4. Document the audit result with reviewer, date, commit/PR reference, findings, remediation, and pass/fail status.
+5. Confirm the gate passed before creating or updating any GitHub-facing artifact.
+
+The full security audit must include the local checks above, secret and credential review, private infrastructure reference review, unsafe worker delegation review, public-claim accuracy review, dependency and supply-chain review when dependencies or CI actions change, and prompt/data-exfiltration review for routing, worker, validator, or provider changes.
+
+Emergency bypass is allowed only for urgent public security fixes approved by the maintainer. The bypass reason must be documented before GitHub action, and the local audit must be completed within 24 hours.
+
+Premature GitHub publication is treated as a release incident: stop further GitHub activity, assess exposure, revert or yank if needed, complete the audit, document findings, and add a prevention note before resuming public work.
+
+External contributors do not need to complete the local source audit infrastructure themselves. Maintainers complete this gate before merge or release. See the checklist in [.github/pull_request_template.md](.github/pull_request_template.md) for the required verification and release-gate attestations.
+
 ## Pull Requests
 
 Open a pull request with:

README.md

@@ -16,23 +16,32 @@ The diagrams show the intended orchestration flow. Worker launch is performed by
 
 AgentFanout is `v0.1.0`. It is a portable skill/policy layer and deterministic advisory router, not a standalone dispatch harness. It is designed to be embedded into agent runtimes that already have a worker mechanism, such as Codex subagents, Claude agents, MiniMax wrappers, local LLM runners, or future provider adapters.
 
+## Public Release Gate
+
+AgentFanout is public-facing. Maintainer-originated GitHub-facing changes are treated as release work, not scratch-pad updates. Maintainers must complete the local source review gate and full security audit described in [Release Process](docs/release-process.md) before creating or updating any GitHub-facing branch, pull request, tag, release, or public export.
+
 ## Table of Contents
 
 - [Execution Model](#execution-model)
+- [Public Release Gate](#public-release-gate)
 - [Who This Is For](#who-this-is-for)
 - [What It Does](#what-it-does)
 - [What This Is Not](#what-this-is-not)
 - [Quickstart](#quickstart)
 - [Deterministic Router](#deterministic-router)
 - [Safety Model](#safety-model)
+- [Release Process](docs/release-process.md)
 - [FAQ](#faq)
 
 ## Execution Model
 
 - **Skill Mode:** The host agent uses AgentFanout instructions to decompose, delegate, validate, and integrate work.
-- **Router Mode:** `scripts/route.py` returns advisory JSON and sanitization output. It does not launch workers.
+- **Worker-First Mode:** Broad investigations, repo searches, infrastructure research, and multi-surface debugging should launch scoped workers before the main session starts collecting evidence.
+- **Router Mode:** `scripts/route.py` returns advisory JSON, dispatch requirements, and sanitization output. It does not launch workers by itself.
 - **Harness Mode:** A standalone dispatcher is possible future infrastructure. It is not currently shipped.
 
+If `scripts/route.py` reports `dispatch.status=launch_required`, the host runtime should launch workers using its native mechanism before substantive main-session research. While workers run, the main session should coordinate, wait, validate, and integrate rather than duplicate the workers' SSH diagnostics, filesystem sweeps, repo-wide search, or substantive research. If no worker mechanism is available, hosts should surface `fanout_blocked` rather than silently falling back to main-session-only work.
+
 ## Who This Is For
 
 AgentFanout is for people building or operating agent workflows that need:
@@ -92,7 +101,7 @@ python3 scripts/route.py --sanitize "prompt text"
 
 ## Deterministic Router
 
-`scripts/route.py` classifies a request, checks hard gates, selects a provider preference, estimates useful fanout, returns a worker capsule, and reports validator requirements.
+`scripts/route.py` classifies a request, checks hard gates, selects a provider preference, estimates useful fanout, returns a worker capsule, reports dispatch requirements, and reports validator requirements.
 
 Example output shape:
 
@@ -105,14 +114,21 @@ Example output shape:
     "executor": {
       "role": "explorer",
       "provider": "MiniMax",
-      "model_selector": "minimax-fast",
+      "model_selector": "minimax-latest",
       "reasoning_effort": "low"
     }
   },
   "fanout": {
     "policy": "automatic_guarded",
     "planned_workers": 20
   },
+  "dispatch": {
+    "status": "launch_required",
+    "main_session_policy": "coordinate_wait_integrate",
+    "launch_before_main_research": true,
+    "main_session_may_duplicate_worker_research": false,
+    "fallback_allowed": false
+  },
   "validator": {
     "required": true
   }
@@ -132,6 +148,8 @@ The router also checks `$PAI_DIR/skills/MiniMax/Tools/MiniMaxExec.ts` or `$PAI_H
 
 Readiness flags and file checks are routing hints. They do not perform live endpoint probing, key validation, or health checks.
 
+MiniMax highspeed is not assumed. AgentFanout uses the default supported MiniMax selector unless the host runtime has verified that the active token plan supports highspeed mode.
+
 ## Safety Model
 
 The main session always owns:
@@ -146,6 +164,8 @@ Suspicious credential-shaped prompts remain main-session-only even when they do
 
 Workers receive only bounded task packets. They must return results to the main session and must not contact notification hooks, voice systems, webhooks, or callback URLs.
 
+Read-only research workers may use scoped read-only retrieval and diagnostics when assigned by the host: repo/file reads, filesystem search, runtime-approved knowledge-base retrieval, public web or docs research, read-only SSH diagnostics, and read-only database queries where configured. That read-only scope does not include private-account side effects, secrets, git mutations, destructive actions, or final synthesis.
+
 ## Commands
 
 Only exact full-line `AgentFanout ...` commands mutate session state:
@@ -203,6 +223,13 @@ The host runtime launches workers using its native mechanism, such as Codex suba
 
 </details>
 
+<details>
+<summary>What happens if AgentFanout wants workers but none are available?</summary>
+
+The route should surface `fanout_blocked`. The host should report that worker launch is unavailable instead of letting the main session quietly perform the whole broad investigation.
+
+</details>
+
 <details>
 <summary>What does <code>route.py</code> actually do?</summary>
 

SECURITY.md

@@ -14,6 +14,23 @@ Security reports should focus on:
 
 Open a private security advisory on GitHub if available. If advisories are unavailable, open a minimal issue that describes the impact without including secrets, credentials, private infrastructure details, or exploit payloads that would cause harm if copied.
 
+## Public Release Gate
+
+AgentFanout is public-facing. Maintainer-originated GitHub-facing changes must pass a local source review and full security audit before any GitHub branch, pull request, tag, release, or public export is created or updated.
+
+The audit must cover:
+
+- tests, compile checks, and `scripts/github-preflight.sh`
+- secrets, credentials, and credential-shaped examples
+- private infrastructure references
+- unsafe worker delegation or privilege expansion
+- callback, webhook, voice, TTS, and notification leakage
+- public-claim accuracy in documentation
+- dependency and supply-chain changes when dependencies or CI actions change
+- prompt/data-exfiltration paths for routing, worker, validator, or provider changes
+
+Any emergency bypass for urgent public security fixes must be explicitly approved by the maintainer, documented before GitHub action, and followed by the local audit within 24 hours.
+
 ## Design Commitments
 
 AgentFanout is designed so the main session remains the security boundary. Workers and validators should receive only bounded task packets, no private account tools, no secrets, no automatic memory, no git-state authority, and no final synthesis authority. Secret hard gates include explicit secret wording and common credential-shaped syntax such as bearer headers, API-key prefixes, access-key assignments, JWT-like values, private key blocks, and password-bearing DSNs.

SKILL.md

@@ -13,6 +13,8 @@ AgentFanout is not injected into session startup. It loads through compact skill
 
 The main session remains the orchestrator, security boundary, and final integrator.
 
+For broad investigation, repo search, infrastructure research, and multi-surface debugging, the main session must dispatch workers before doing substantive research when a worker mechanism is available. After dispatch, the main session coordinates, waits, validates, and integrates; it must not duplicate the workers' SSH diagnostics, filesystem sweeps, repo-wide search, or substantive research while workers are running. If no worker mechanism is available, report `fanout_blocked` instead of silently doing all research in the main session.
+
 It may use host-runtime worker mechanisms for bounded helpers when available, but it must keep these responsibilities in the main session:
 
 - MCP/tool work: memory, calendar, email, chat, browser automation, workspace tools, private search, or any other private/tool-backed system.
@@ -23,6 +25,8 @@ It may use host-runtime worker mechanisms for bounded helpers when available, bu
 
 ## Activation workflow
 
+Do not perform repo-wide, vault-wide, or home-directory searches to rediscover AgentFanout before routing. Once this skill is selected, use this skill directory directly, read only the minimal referenced files needed, and run `scripts/route.py` before any broad search or substantive research.
+
 1. Classify and route with `scripts/route.py`, `workflows/Route.md`, and `references/Routing.md`.
 2. Apply lazy-loading rules from `references/LazyExecution.md`.
 3. Shape minimal worker identities with `references/AgentCapsules.md`.
@@ -56,6 +60,8 @@ Fanout is automatic and guarded. AgentFanout chooses the useful number of worker
 
 Every delegated worker receives a minimal specialist capsule by default. Do not load automatic memory, relationship history, full Agents context, full CodexAgent context, voice metadata, or private MCP context into worker prompts.
 
+Research workers may use scoped read-only tools when explicitly assigned: repo/file reads, filesystem search, runtime-approved knowledge-base retrieval, public web or docs research, read-only SSH diagnostics, and read-only database queries where the environment already permits them. They must not perform private-account side effects, write state, touch secrets, mutate git state, perform destructive actions, or own final synthesis.
+
 Load full Agents tooling only for named, custom, personality-heavy, trait-heavy, or user-requested specialist composition beyond the compact capsule.
 
 ## Approval-to-execution
@@ -75,6 +81,12 @@ fanout:
   policy: automatic_guarded
   planned_workers: <number>
   rationale: <why this count is useful>
+dispatch:
+  status: launch_required|fanout_blocked|not_required
+  main_session_policy: coordinate_wait_integrate|report_block|handle_directly
+  launch_before_main_research: true|false
+  main_session_may_duplicate_worker_research: false
+  fallback_allowed: true|false
 executor:
   role: main|explorer|worker|external-worker|local-worker
   provider: current|codex|claude|local-llm|minimax|future
@@ -100,6 +112,8 @@ Do not delegate merely because this skill is active. Stay main-session-only when
 - The task is destructive or irreversible.
 - The expected orchestration overhead exceeds savings.
 
+If delegation is useful but all worker providers are unavailable, stop and surface the block. Do not treat that state as permission for the orchestrator to consume the full research context itself.
+
 ## Built-in deterministic helper
 
 Use `scripts/route.py` for dry-run routing checks, prompt sanitization checks, and fixture tests. The script is advisory; the main session still owns final judgment.

adapters/Codex.md

@@ -23,6 +23,14 @@ model_selectors:
   frontier: current-frontier
 ```
 
+## Native Codex selector mapping
+
+When `scripts/route.py` returns `current-fast-mini`, the host must pass an explicit mini/fast model override to native Codex worker launch. Do not omit the model override and let the runtime default to the main-session/frontier model. Resolve the selector to the lowest-cost currently available Codex mini or fast model, use the routed `reasoning_effort`, and record the resolved model in the worker launch summary.
+
+Before spawning a Codex worker, validate that the native launch parameters satisfy `runtime_launch.codex_native.cost_tier` and `must_pass_model_override`. If the host cannot satisfy a required cheap/mini override, report `fanout_blocked` or route to another provider instead of silently launching the default stronger model.
+
+`current-balanced` may use the runtime's balanced default. `current-frontier` should use the strongest current Codex model only when high-effort routing requested it.
+
 ## Launch patterns
 
 - Explorer: read-only prompt, no writes, return evidence.
@@ -49,9 +57,14 @@ allowed_writes: []
 forbidden: [mcp, secrets, git-state-change, destructive-action, final-synthesis]
 model_selector: <selector>
 reasoning_effort: low|medium|high|xhigh
+runtime_launch:
+  codex_native:
+    cost_tier: cheap
+    required_model_capability: mini_or_fast
+    must_pass_model_override: true
 output_contract: <summary/evidence/patch/validator verdict>
 ```
 
 ## Notes
 
-Use provider-native non-interactive execution when available. Keep sandbox/approval settings explicit for automation. The adapter resolves selectors to current Codex-supported models; the core never hardcodes names.
+Use provider-native non-interactive execution when available. Keep sandbox/approval settings explicit for automation. The adapter resolves selectors to current Codex-supported models; the core exposes selector capabilities and does not publish model names as policy.

adapters/MiniMax.md

@@ -19,10 +19,12 @@ supportsTools: API-dependent
 supportsFileEditing: false unless wrapped by an edit harness
 supportsReasoningEffort: provider-dependent
 model_selectors:
-  cheap: minimax-fast
+  default: minimax-latest
   balanced: minimax-latest
 ```
 
+Do not use `minimax-fast` or pass `MiniMaxExec --fast` unless the runtime has explicitly verified that the current MiniMax token plan supports `MiniMax-M2.7-highspeed`. In this environment the token plan does not support highspeed, so AgentFanout routes MiniMax workers to the default supported model selector.
+
 ## Routing rule
 
 When MiniMax workers are used, validators are required unless the output is purely disposable ideation.
@@ -49,7 +51,7 @@ MiniMax workers must not receive:
 ```yaml
 role: external-worker
 scope: <bounded data/files/claim>
-model_selector: minimax-fast|minimax-latest
+model_selector: minimax-latest
 reasoning_effort: low|medium|high
 output_contract: <summary/evidence/patch instructions>
 validator_required: true

docs/release-process.md

@@ -0,0 +1,72 @@
+# Release Process
+
+AgentFanout is public-facing. Maintainer-originated GitHub-facing changes are release work and must pass the local source review gate before any GitHub branch, pull request, tag, release, or public export is created or updated.
+
+## Public Release Gate
+
+Required order:
+
+1. Prepare the change in the canonical local source repository.
+2. Review the change through the local source PR/review process.
+3. Complete the full security audit on the local PR/diff.
+4. Document the audit result with reviewer, date, commit/PR reference, findings, remediation, and pass/fail status.
+5. Create or update GitHub-facing artifacts only after the gate passes.
+
+Agents and automation must stop before GitHub-facing activity if they cannot verify the local review and audit reference.
+
+## Full Security Audit
+
+The audit must include:
+
+- `python3 tests/run_tests.py`
+- `python3 -m py_compile scripts/route.py tests/run_tests.py`
+- `scripts/github-preflight.sh`
+- secrets, credentials, and credential-shaped examples
+- private infrastructure references
+- unsafe worker delegation or privilege expansion
+- callback, webhook, voice, TTS, and notification leakage
+- public-claim accuracy in README, docs, examples, release notes, and security policy
+- dependency and supply-chain review when dependencies, CI actions, scripts, or packaging change
+- prompt/data-exfiltration review for routing, worker, validator, or provider changes
+
+Minimum audit record:
+
+```yaml
+date: YYYY-MM-DD
+reviewer: maintainer-or-reviewer
+local_review_ref: local-source-pr-or-commit
+github_target: branch-pr-release-or-export
+commands:
+  - python3 tests/run_tests.py
+  - python3 -m py_compile scripts/route.py tests/run_tests.py
+  - scripts/github-preflight.sh
+findings: []
+remediation: []
+result: pass|fail
+```
+
+## Exceptions
+
+Emergency bypass is allowed only for urgent public security fixes approved by the maintainer.
+
+Before GitHub action, document:
+
+- why the normal local gate cannot run first
+- who approved the bypass
+- what public exposure the fix addresses
+- when the follow-up local audit will run
+
+The local audit must be completed within 24 hours after the emergency GitHub action.
+
+## Violations
+
+Premature GitHub publication is a high-severity release incident.
+
+Response:
+
+1. Stop further GitHub activity.
+2. Assess what was exposed.
+3. Revert, close, or yank the public artifact if needed.
+4. Run the full security audit.
+5. Document findings, remediation, and prevention.
+6. Resume public work only after the incident is recorded and the gate passes.