multi-agent-orchestration

Multi-Agent Orchestration

Use the current main session as the PM to decompose, dispatch, inspect, accept, and close out multiple local Agents. Daily worktree and terminal/session are preferably managed by Orca; use tmux only when Orca is unavailable, the user explicitly requests it, or a compatible path needs to be reproduced. Do not mistakenly write "opened a terminal" as "established a supervised task".

1. Applicable boundaries and side effects

Use this Skill:

• Advance two or more local tasks with independent boundaries and separate acceptance simultaneously.
• Requires independent worktree, branch, session, quota lane, or long tasks that can be manually taken over.
• The PM needs to read worker progress, correct deviations, wait for structured completion events, and close out uniformly.
• The user explicitly requests Orca, tmux, independent session, multiple workers, PM/orchestrator, or Wave Autopilot.

Do not use:

• A single short task, one-off Q&A, or a single-file modification with no parallel value.
• Pure task source, owner, and dependency status synchronization: follow the project task source rules; do not extend them in this Skill.
• branch/commit/push/PR/merge/conflict rules: use git-workflow。
• Channel selection (subagent vs independent worker) is a parallel decision, not a fallback downgrade：
  • Host subagent preferred: small-to-medium task cards (single card ≤1h of work), quality-sensitive (pixel/numeric-level verification), wanting speed (measured 15-45 minutes/card), ample host quota. Empirical evidence (Fathom 2026-09-24, eight cards 082-093): all green with zero rework, zero whitelist overreach, near-zero operational cost.
  • Independent worker preferred: host quota tight/already hit the limit (subagent and host share quota; when the limit is hit, all in-flight tasks are wiped out), large-batch long-task parallelism, need for model diversity (lane switching uses the user's API quota), tasks where the host session may be interrupted.
  • Mixed-use discipline is channel-independent: conflict control of serial within the same file domain and parallel across different file domains applies to all channels.

This Skill may create Git/Orca worktree, branch, Session Context, terminal, tmux session, and supervised Run/Task/Dispatch. It does not automatically install dependencies, nor does it expand push, merge, release, or external scheduling authorization on its own. Orca worktree creation always uses --setup skip: repo Setup occurs before this Skill writes Session Context and the mechanical gate,inherit/run will reject with ORCA_SETUP_REQUIRES_PRELAUNCH_AUTH_CONTRACT before resource creation;--allow-install-command only authorizes the worker phase after the gate is in place, and cannot retroactively approve Setup. Real provider configuration and backups must not enter Git, logs, or deliverables.

After successful delivery,pm-closeout.sh by default cleans up the one-off worker's remote head, worktree, and local branch; long-term feature/integration branches and fixed worktrees must declare long-lived and be retained. Fail closed when facts are unknown, identity has drifted, or the lifecycle is not settled. Supervised cleanup must obtain the exact Run from Session Context, and uniquely locate the Dispatch by fully traversing the opaque cursor according to worker-list --run <run> --limit 100 ; when preceding pagination, identity, or results cannot be proven, stop before release, terminal, worktree, and branch mutation.reclaimable After release, the same complete query must be re-executed; if the post-condition result cannot be proven, the release may have occurred, but terminal, worktree, or branch mutation must not continue. For a single legacy worker that has already been confirmed merged but did not go through the standard closeout, you may use post-merge-cleanup.sh to perform a strict dry-run/execute cleanup; it does not replace the standard closeout, nor may it be used for batch scanning.

2. Mode Selection

Mode	When to Choose	Completion Authority
Orca supervised	The user requires supervision, waiting for results, a DAG, ask/reply, or a decision gate; the Agent can be recognized by Orca	worker_done → Delivery, then acceptance and settlement by the PM
Orca terminal-managed	The whitelisted backend does not adopt supervised, or the CLI can only be managed by an external terminal	terminal output + checkpoint + real artifacts, PM acceptance
tmux worktree	Orca is unavailable, the user specifies tmux, or compatibility regression	checkpoint + Git/tests/artifacts, PM acceptance
tmux lightweight	The user explicitly does not want a worktree, or the target is non-Git and the directories will never overlap	checkpoint + real artifacts, PM acceptance
Same-host subagent	Small-to-medium quality-sensitive cards, rapid iteration rounds, preferred over an independent worker when quota is plentiful (see the channel selection criteria above); no independent process/branch overhead	Determined by the host (a four-part RESULT self-report is recommended)
Remote node (SSH bridge)	When a second machine is needed to scale concurrency (an independent key pool) or to offload local CPU/memory, the PM dispatches via spawn-worker-remote.sh to a node declared in personal config remote_nodes ; the full set of node-side gates is established locally, and the worker reads the node's own env/key (references/25-remote-node-dispatch.md）	STATUS.json terminal state + branch push/PR existence + PM-side PR-fingerprint acceptance (the three completion proofs, not relying on a cross-machine Orca receipt)

MiniMax's short tasks exec in terminal-managed mode have their complete input read by the startup command, without waiting for the TUI and without sending the task again; long-running tasks still use the interactive CLI. Long-running tasks that have chosen ZCode use the configured native supervised startup bridge by default, see Native Orca Contract。

Backend and mode selection, configuration sources, and the single follow-up action are uniformly defined by the Dispatch Profile Contract . ZCode auto rejects before resource side effects when the bridge configuration is missing; the old explicit native parameter is retained, and the generic compatibility entry point must pass --dispatch-profile orca-generic, direct connection remains --no-orca-mode. The profile is the dispatch plan; actual permissions, start, completion, and resource status continue to come from native receipts.

The same worker can have only one control mode. terminal-managed has no Task/Dispatch and must not require worker_done; supervised must have a live Task/Dispatch, and must not use STATUS, UI cards, TUI idle, heartbeat, or timeout to impersonate completion.

3. Pre-Dispatch Contract and Gates

3.1 Complete Task Modeling First

The PM completes the following before any worker side effects:

1. Read the project rules and the complete task card, and determine the goals, non-goals, allowed/forbidden files, verification commands, and completion conditions.
2. Group by root cause, dependency chain, and file scope; parallelize only when the scopes are orthogonal, acceptance is independent, and there are no shared lock files/schemas/migrations.
3. Specify for each worker the branch,branch_lifecycle, integration target/base, worktree, session, role, backend/profile/model, provider slot, and resource owner.
4. Regular workers default to ephemeral-worker; only long-term functionality/integration baselines explicitly declared in the project task contract use --branch-lifecycle long-lived. The source branch lifecycle and the merge target are two fields and must not be conflated.
5. From python3 scripts/dispatch-value-gate.py --describe-policy read the current defaults for concurrency and pending-acceptance PR backpressure; projects may tighten them, and exploration windows must be explicitly authorized and time-limited. The dispatch contract uses capacity to bind the PM's already-inventoried shared active inventory, evidence, and the smaller project cap; existing workers and this wave's candidates are added together for judgment. When an old contract does not provide inventory, it only proves that this wave's count is legal, and cannot be used to claim there are still slots available machine-wide. Machine memory slots are a separate gate and cannot replace worker inventory or override cross-project agreements.
6. Verification commands default to scoped: single spec / targeted cases / --bail 1 early stop; full-package full suites (full test/build chain) do not enter the worker self-verification contract, full verification is single in flight (cross-project mutual exclusion), and the default destination is a serial rerun when the PM closes out. This clause constrains the verification category, not the number of workers (see §5 verification load discipline).
7. Fixed one_wave or continuous: when a human requests continuous dispatch/return-then-review-before-proceeding/not being prompted every round, do not default to a single wave. Before dispatching in continuous mode, verify the sole monitored original PM, original task source, official configuration and period, and read PM continuation contract; the Wave entry point mechanically checks explicit continuous, and other modes are explicitly checked by the PM. Only a master-control heartbeat, a promise to set it up later, or recovery after manual prompting do not prove an automatic closed loop.

Issue grouping reads references/12-issue-grouping.md; concurrency boundaries and real incidents read references/10-parallel-lessons.md。

3.2 Mandatory gate order

The following four gates are executed by stage, and any non-zero exit must not be skipped:

1. Dispatch value gate: the candidate wave adopts templates/dispatch-value-gate.example.json isomorphic contracts, runs python3 scripts/dispatch-value-gate.py <spec.json>. Accept implementation、reusable_verification, merge_gatebound to named PR/head, and business_artifactwith a business purpose, source, precise artifacts, and item-by-item criteria. Research, design, documentation, and reports are accepted based on business artifacts; maintenance documentation without clear consumption, placeholder investigations, and purely formatting-based wave expansion are still rejected.
2. Delivery value post-gate: run worker-value-postflight.pywith the same spec, engineering delivery verifies the real diff, declared assets, verification commands, and the 40-character immutable head; business delivery reads the real files in the Git or non-Git directory, binding the contract, source, and file fingerprint as the same delivery identity.
3. Role-separated acceptance gate: non-trivial implementations are completed by implementers and reviewers in different dispatch/session, run review-acceptance-gate.py. Self-review, delivery identity drift, missing binding evidence, failed verification, or unresolved blockers are all rejected; business artifacts must also have their content and source checked item by item by a different author, and file hashes are not used to prove content correctness.
4. Failure recovery gate: first classify with acceptance-recovery.py .internal_recoverable Fix within budget and re-review independently;external_dependency、safety_unknown only park when or the budget is exhausted. Docs-only acceptance fixes for an already named PR may only go through the extremely narrow preflight/postflight channel of acceptance-repair-gate.py .

When automated recording of submitted engineering verification is needed, it may be done according toengineering evidence collection contractuse the optional collection/check entry point; it only generates the original delivery post-gate evidence and continues to preserve independent review and real completion verification.

Fields, command, exception enums, reviewer evidence budget, and recovery semantics are read from a unified references/18-dispatch-acceptance-contracts.md; do not create another set of classification tables in the project prompt or other scripts.

3.3 Runtime safety gate

• spawn-worker.sh Identify the real PM harness from the complete process ancestor chain, and intersect it with the nesting-layer allowlist. Unknown, conflicting, or unprovable hosts fail closed;--pm-harness only makes a consistency declaration and cannot escalate privileges.--base-ref Only accept ref names (main、origin/main、refs/heads/x , etc.), and do not accept bare sha—40-hex (as well as 7–40 digit pure hexadecimal that git resolves as a commit rather than a ref name) will, before any worktree/provider/terminal side effect, be rejected with SPAWN_WORKER_BASE_REF_MUST_BE_REF: <值> and exit, avoiding a subsequent pm-cleanup-worker deadlock between INTEGRATION_TARGET_MISMATCH(argument=main vs metadata=sha) and PR_BASE_MISMATCH(expected=sha vs actual=main).character classes are case-sensitive: the guard also recognizes [0-9a-fA-F], uppercase sha (such as 96A304DF…) and mixed-case sha are all rejected via the sha path; when a branch name happens to be in uppercase hex form and actually exists (refs/heads/<v> case-sensitive lookup), it is still allowed as a real ref.
• The worker capability allowlist for Claude Code/Codex/Hermes PM is determined by config/harness-backend-policy.json : it supports Claude Code, Codex, CodeBuddy, standalone Qoder CN CLI (qoder-cn), Qianwen Office bundled coding CLI (qwenwork-cn), standalone ZCode CLI (zcode-cli）、MiniMax Code CLI（minimax-code), and compatible ZCode app-server driver (zcode). CodeBuddy PM can still only dispatch itself, and ZCode PM's existing authorization still only includes Claude/Codex; adding worker support does not add a PM host. The QoderWork backend and old aliases have been removed, and the old bundled CLI symlink cannot be treated as Qoder CN. The Hermes host is still identified by installation path signature, and a bare word is not evidence.
• The first connection to a pre-created worktree only accepts an explicit borrowing contract, a new Session, authorization from the original owner, and proof that there is no writer on site; the default occupied branch/path gate remains a rejection, and borrowing a long-lived tree and branch cannot be deleted by failure/closure. Read references/31-borrowed-existing-worktree.md, and do not forge recovery metadata.
• After the worktree is written to disk and before any terminal/Task/worker-start/task injection, it must be proven that the directory, expected branch, and HEAD are consistent; the Orca repoId must be consistent with the verified project. On failure, only clean up resources whose ownership can be precisely proven, and the PM must not use this as an opportunity to directly implement business logic.
• A Worker only modifies allowed paths. A reviewer by default may only write to its own Session Context; fixing the branch under review requires explicit --review-repair-grant <授权来源>, and any config/*.local.yaml is not writable.
• Shell executes two policies according to the backend and startup mode: when Claude Code's local hook is in effect and the startup command explicitly uses --permission-mode auto , ordinary Bash is handed to Claude Code's auto classifier and user settings; the orchestration hook continues to intercept recognized installation commands, protected Git operations directly and via common Shell wrappers, the Orca protocol, and restricted tracked deletions. Other backends and Claude Code non-auto mode continue to use the exact allowed_shell_commands。execution_authority.shell_policy fixed selected policy; Claude auto is not a mechanical sandbox for the Shell file write scope or arbitrary program side effects, and the PM must still verify the real diff and external side effects. A verification command does not equal installation authorization; installation-type commands can pass the orchestration gate only with exact --allow-install-command and an auditable authorization source. Orca repo Setup is an earlier independent stage and is skipped by default; this authorization cannot be reused.
• Failure continuation for a closed ZCode original Session followsNamed recovery entries and known identity gaps: first prove exit/old cap revocation, restore the exact Session with empty input and verify the model, then retry the same failed Task once and adopt the real receipt;reauthorizeonly for provably live targets; do not use ready-reset to recover failed history.
• The Supervised completion channel binds the authority receipt from PM startup, and after worker-start freezes the Dispatch identity and capability digest; before sending worker_done recheck live runtime/process/run. Do not rewrite the receipt or bypass completion validation with a Shell allowlist; on the first ORCA_COMPLETION_AUTHORITY_INVALID stop and report to the PM. For fields and manual register migration see references/13-orca-cli-worker.md §5。
• New isolated workers use the highest natively available execution privilege according to the authorized task: ZCode CLI defaults to --mode yolo, MiniMax batch defaults to --permission full; explicitly narrower modes remain in effect. MiniMax long-horizon tasks keep the interactive CLI, with privileges configured and verified per the optional CLI contract , not substituted by batch parameters. Host approval, business scope, account login, and orchestration admission are independent boundaries and are not cancelled by worker mode.
• Worker default execution privileges (v2.22.0, user decision 2026-09-06): workers are isolated in a dedicated branch worktree, push+PR is the necessary delivery path, and security classes are relaxed per "segmented validation" — pipelines/;/&& compound commands are allowed as a whole when every segment is a safe read or safe delivery command (git status/diff/log/show/fetch/add/commit/push/rebase, gh pr create/view, filters such as ls/grep/cat/jq/sort,node --version -type version queries); redirection is limited to /dev/null and temporary directories (rejecting .. traversal). Still fail-closed: force push (--force/-f/--force-with-lease), push to main/master, remote deletion (git push origin :branch）、--mirror/--tags, subshells, input redirection, command substitution,gh api/gh repo sync, install-type commands. The identity four-piece set (--git-expected-name/--git-expected-email/--git-integration-base/--git-push-remote) is still recommended for PR delivery tasks: the bound safe-push verifies the full commit chain from the remote PR base to HEAD and then pushes by immutable OID; it is a hardened replacement for bare push, not the only path.
• Deleting tracked files is an independent high-risk class, judged before the ordinary Shell allowlist. Only a hook-enabled worker may run git rm -- <一个 canonical repo-relative tracked file>from the receipt-bound worktree root, and that exact path must be written into the immutable allowed_write_pathsat spawn time; scope globs, subsequent reauthorize --allow-cmd、-r/-f/--cached, multiple paths, directories/gitlinks, pathspecs, Shell expansion, and compound commands cannot expand the privilege. Codex/ZCode's prompt_only_degraded only provides hints and cannot claim mechanical deletion protection; see references/02-runtime-dependencies.md §6。
• When the dispatch value contract has declared verification_commands , calling spawn must also pass --verification-contract <spec.json> --verification-task-id <ID>; with no file contract, pass --verify-cmdone by one. The command enters the authority receipt, METADATA, and allowed_shell_commandsverbatim as a complete string; do not split cd <subdir> && <verify>. Under the Claude auto policy, this list is still the mandatory command for delivery acceptance, not the sole source of execution privilege for ordinary Bash.
• When requiring Worker self-verification, pass --require-verification, or in the project .claude/orchestration.config.json set verification.required: true. When the command parses as empty, the contract task is not unique, the worker type is undeclared, the configuration is malformed, there are duplicates/whitespace, U+0000, or install-type commands, it must fail before terminal/Task/Dispatch/task injection. When the business contract explicitly acceptance_mode: content_review When using an empty command array and conducting a separate content review, do not automatically discover unrelated tests; with explicit --require-verification conflict, reject. For business that requires real command verification, use verifier。
• The verification command accepts only one authoritative source: when there is no file contract, use --verify-cmd; otherwise use the dispatch value contract; the two are mutually exclusive. Only when neither is provided, read the project configuration, then fall back to bounded discovery in the root directory. Node/Make existing discovery remains unchanged; Python only injects when both the root manifest and the root tests/ exist python3 -m unittest discover -s tests -v. Nested Python/other subprojects must explicitly write the full command in the project configuration verification.by_worker_type , do not recursively guess. Dependency behavior reads references/02-runtime-dependencies.md。

4. Orca-first execution

4.1 Each new session first reads the runtime contract

orca skills get orca-cli
orca skills get orchestration   # supervised / DAG / ask-reply 时
orca status --json

The running CLI's guide and --help shall prevail.spawn-worker.sh Only when the current PROJECT_DIR can be precisely parsed as the same Orca worktree/repo, enter Orca;--no-orca-mode explicitly go through tmux.

4.2 Wave preparation barrier

A multi-worker supervised Wave must first write the manifest once, create one Run and pre-create all Tasks, and only start in parallel after the receipt succeeds. Do not let concurrent spawns each create/rebind a Run, and do not send the full prompt again after injecting tasks in worker-start .

bash scripts/orca-wave-prepare.sh --manifest /tmp/wave.json --from "$PM_TERMINAL" --receipt /tmp/wave-receipt.json
WAVE_RUNTIME_ID=$(jq -er '._meta.runtimeId' /tmp/wave-receipt.json)

bash scripts/spawn-worker.sh \
  --project "$PROJECT" --branch feat/worker-a --session worker-a \
  --branch-lifecycle ephemeral-worker --worker-backend claude-code \
  --verification-contract /tmp/dispatch-spec.json --verification-task-id TASK-A \
  --command "$AGENT_COMMAND" --orca-supervised \
  --orca-run-id "$RUN_ID" --orca-coordinator-handle "$COORDINATOR_HANDLE" \
  --orca-runtime-id "$WAVE_RUNTIME_ID" \
  --orca-task-id "$TASK_A_ID"

PM_TERMINAL must be a terminal handle that explicitly belongs to this round's PM, not guessed from UI focus. A new Wave programmatically passes the receipt's _meta.runtimeId into --orca-runtime-id; sender, terminal liveness, and Run/coordinator are jointly verified before creating Worker resources, and a pre-created Wave does not repeatedly create a Task/rebind a Run. A single Worker may prepare the Run after quota/mem pass and before creating a new lease/worktree/terminal; if there is no reliable sender, reject. When the old context lacks runtime, it can only positively re-verify the current binding and explicitly state that historical continuity is unverified; existing runtime drift cannot be bypassed; the final judgment still relies on Orca consumer fencing.

Complete manifest, Terminal-managed, Dispatch self-check, cold-start recovery, settle, and metadata contracts are read at references/13-orca-cli-worker.md. The PM's read/show/send/wait/reply/release/ack/settle/pr-audit/closeout commands read references/14-pm-orchestrate.md。

For important cross-session requests, use pm-orchestrate.sh send --message-contract: first use worker-show to re-verify the exact Run/Task/Dispatch/worker, then fix the sender, business thread, correlation, expected action, and evidence refs; the Orca native thread carries the correlation, so that a native reply without payload can still inherit a verifiable correlation identifier, while the business thread remains in the contract payload. The send receipt must bind the same Dispatch relay's Orca message ID and the complete request digest; success only proves durably_enqueued. Read-only inspection uses inbox（check --peek), all occurring top-level and payload identity/type aliases must be consistent; structured messages must have exact provenance, and native correlation messages without payload must simultaneously provide a thread+correlation filter and exactly match the worker sender, coordinator recipient, Run, and native correlation thread. Visibility of related messages does not prove that replywas executed, consumed, started execution, or completed business. State hierarchy, whitelist, idempotency fingerprint, and sensitive payload rejection rules are uniformly read from references/14-pm-orchestrate.md, do not create another chat layer or use terminal prompt in place of Orca messages.

When a Worker needs the PM to answer, use the live preamble's ask; after timeout, cancel, or disconnect, only follow the original message ID --resume, do not resend a new question, and do not escalate an ordinary ask into a decision gate. The PM's wait Classify receipts in the order of up to 50 complete FIFO Deliveries returned, and replay the same batch before ack; only after completing question reply, escalation handling, worker_done business acceptance, and terminal ownership item by item, ack the exact Delivery. If the ack receipt also delivers the next batch, processing must continue according to the receipt; confirming the previous batch must not be mistaken for the next batch having been processed. The Worker, before a new file, after each scoped test, and worker_done executes a non-peek check --terminal <live worker handle>, and after processing the entire batch only acks that Worker Delivery with the same handle, and continues draining subsequent batches;send success or inbox --peek visibility neither proves that the Worker has processed.consumer_fenced indicates that the consumer generation/process identity has been replaced,dispatch_inactive indicates that the original Dispatch has settled, stopped, or is no longer active; if either appears, stop immediately, do not retry check or send worker_done. The mandatory prefix and Shell gate together reject using --peek/--all/--unread to impersonate processing; the Worker's scoped ack cannot specify the coordinator handle, nor does it grant reply, release, stop, or Task mutation.

4.3 Worker Prompt and Session Context

Use templates/worker-prompt.md, at minimum specifying: task card, scope, prohibitions, verification commands, completion protocol, branch lifecycle, integration target, resource owner, installation authorization, and Git identity. For supervised, worker-start is the only task injector; long prompts may be placed in WORKER_PROMPT.md, and the terminal only sends a short Read instruction.

The common prefix of the actual Task spec fills in ask/resume, natural checkpoint receipt, final receipt, minimal implementation, scoped verification, authorized file commit, and unique Session Context RESULT; review-only/no-change does not create an empty commit.spawn-worker.sh injects the absolute WORKER_SESSION_CONTEXTinto all legitimate backend startup paths, without depending on whether installation/scope guard is enabled; a worker with a legitimate prompt_only_degraded and no allow-paths can also locate it. This value is used only for locating; it does not grant installation/Shell/scope permissions, and does not pass off a degraded hook as active. The Worker checks in its own process that this value and all non-empty old guard bindings (SCOPE_GUARD_SESSION_ROOT、WORKER_INSTALL_AUTH_FILE parent directory) have consistent spelling and that the directory exists; only after all checks succeed is the path adopted; if all are missing, or any one is relative/conflicting/unusable, escalate to PM, do not guess the repository root, and do not modify authority. Old calls can still be located by old guard bindings. The prefix does not expand installation, Shell, or push/PR permissions; for auxiliary commands and the .venv opt-in process, see references/02-runtime-dependencies.md。

<worktree>/.claude/agent-sessions/<session>/
├── METADATA.json
├── STATUS.json
├── RESULT.md
├── PATCH_SUMMARY.md
└── WORKER_PROMPT.md

Fields and checkpoint read references/03-checkpoint-files.md. In supervised, STATUS is only for observational assistance; the completion authority is still worker_done → Delivery。

5. Inspection, Intervention, and Continuous Advancement

Inspect according to evidence priority:

1. supervised：Delivery、worker-show、worker-read。
2. terminal-managed：terminal read + checkpoint。
3. tmux：checkpoint、Git status/log、bounded capture-pane。
4. All modes ultimately check the real diff, tests, artifacts, and PR status.

When off-topic, blocked, out-of-bounds, or verification failure is found, prioritize sending narrow corrective guidance to the original worker; when independent review is needed, assign another reviewer. Runtime liveness and business progress must be judged separately: output/cursor/CPU advancement only proves liveness; files, commits, tests, and artifacts prove business progress. When observation is uncertain, do not automatically Esc, Ctrl+C, stop, release, or batch kill by process name.

Wave Autopilot is enabled only after the user has explicitly authorized it and the policy is fixed in the project task source. L1 current session advancement reads references/15-wave-autopilot.md; cross-session L2 controller and the not-yet-implemented L3 scheduler boundary read references/16-autopilot-durability.md. Do not describe session cron, Markdown task source, or provider lease alone as a persistent controller.

After the Worker returns, the original PM pins the artifact/head, a different context reviews it independently, and the same original Task writes it back; then proceed along the original problem to fix it or advance to a named legitimate next item. This wave of responsibility cannot end at 'dispatched/author done/handed off.' A single card's budget/dependency parking does not stop other independent READY items. Record the source of manual nudges/recoveries, distinguishing monitoring configuration, formal automatic triggers, and the complete automatic business cycle; configuration checks passing does not sign off automatic self-healing. For details see Continuation evidence level。

When checking across projects whether an Orca Worker is stopped at idle due to 429/usage limit, run scripts/orca_rate_limit_recovery.py --manifest <私有清单>; by default read-only, only with explicit --execute does it send a single fixed 'continue' to high-confidence RATE_LIMIT_IDLE through the terminal input channel. tmux, single-keyword/stale tail, ungrouped identity, and uncertain status are never handled;WAKE_ACCEPTED does not equal quota recovery or business continuation. For the full manifest, state machine, staggering, idempotency, TOCTOU, and exit-code reading see references/20-orca-rate-limit-recovery.md。

Worker node OOM identification and backoff(2026-09-05 incident: long output from multiple workers exhausted the V8 heap of the node process within the session FatalProcessOutOfMemory → SIGABRT, and the PM periodically respawning formed a crash loop and once triggered a forced reboot of the entire machine).spawn-worker.sh Starting from v2.20.0, by default worker sessions are injected with NODE_OPTIONS=--max-old-space-size=2048（SPAWN_WORKER_NODE_MAX_OLD_SPACE_MB=0 can be turned off), and a worker exits by itself when it hits the limit instead of dragging down the system. When PM inspection finds a worker node OOM (exit code 134 / SIGABRT / logs containing FatalProcessOutOfMemory / a node OOM report newly added in the system crash report directory (DiagnosticReports) with matching time): the same task must not be immediately respawned, wait at least until the next inspection round and globally reduce concurrency by 1, and before respawning the memory budget precheck must be rerun (the probe probes on-site on every spawn, no caching; if quota is insufficient, queue according to PARKED_FOR_MEMORY , do not bypass); after the same task OOMs 2 consecutive times, stop respawning, park it, and report to the user—this usually means the task itself produces excessively long output (full log aggregation, extra-large test runs), requiring the task side to reduce output or split, rather than retrying harder.

Physical memory budget queue (mem budget lane)：spawn-worker.sh Run scripts/mem_budget_probe.pybefore any worktree/terminal/lease/dispatch side effects, converting currently available physical memory into dispatchable quota according to the per-worker budget (default 3 GiB;SPAWN_WORKER_MEM_BUDGET_BYTES adjustable,=0 explicitly disables the entire gate). When quota is insufficient or probing is unreadable, spawn rejects with dedicated exit code 4, outputting SPAWN_WORKER_MEM_BUDGET_DENIED and available/budget/gap diagnostics; if allowed, leave a SPAWN_WORKER_MEM_BUDGET: available=… budget=… slots=… ledger line in the PM log. Upon receiving this rejection, the PM must not busy-wait or switch to manual spawn: this inspection round records the task as PARKED_FOR_MEMORY and retains the probe output, and the next inspection round retries; if the same task has insufficient quota for 3 consecutive rounds, formally park it and report to the user (with probe JSON). The single-process heap cap (v2.20.0) manages the bleeding point of a single worker, while this gate manages the total additive commitment and also covers non-node runtimes that cannot rely on a heap cap. For the data source, budget derivation, pressure tightening, and queuing state machine see references/22-mem-budget-lane.md。

Named task resource profile: for controlled tasks that genuinely have task measurement/scope and an original PM serial contract, you may explicitly set SPAWN_WORKER_MEMORY_TASK_PROFILE. Light Node, existing Codex host followup, and limited MiniMax CLI use the same multi-signal observation gate; a MiniMax whole worker still requires at least 3 GiB, single writer, 20-second stability window, and the actual Node heap cap is not equal to the RSS limit. Without a profile, retain the old default; a profile cannot be allowed through with budget 0 or an old snapshot. For fields and independent source/identity recheck see Resource contract。

Verification workload discipline (verification lane): Constraint validation category, does not constrain the number of workers. Worker self-validation defaults to scoped (single spec / targeted cases / --bail 1); a full suite has a single in-flight instance and is mutually exclusive across projects—when a worker genuinely needs to run a full suite on-site, first probe for existing full-suite test processes (such as pgrep -fl 'vitest|pytest|jest|go test'), and if exclusivity cannot be confirmed, back off and wait or switch to scoped. Probing is a best-effort on-site signal; do not create cross-project lock files—better less concurrency than erroneous concurrency; the full-suite rerun during PM closeout is naturally serial and is the default destination for full validation. Validation output must always be redirected to a log file, bringing back only a bounded tail (such as tail -50) to the terminal/session—unbounded scrolling of long output is precisely the feeding tube for session-side node runtime OOM. When PM inspection finds system load spiking and multiple workers running validation simultaneously, correct it to staggered queuing (wait for the in-flight validation to finish before releasing the next batch), do not cut the number of workers. This discipline is complementary to the single-process heap ceiling and physical memory lane: the heap ceiling governs single-process bleeding points, the mem lane governs the total commitment, and this discipline governs the concurrency category and output volume of validation execution (in the 2026-09-05/06 incident, the three were missing this last link: concurrent full self-validation simultaneously created load spikes and extremely long output).

6. Acceptance, Git delivery, and resource closeout

Long-duration supervised runs use the references/23-runtime-settlement.md read-only evidence adapter to verify runtime identity, logical final state, terminal, provider lease, and Delivery.pm-orchestrate.sh reconcile --snapshot ... --output ... only recomputes already-captured evidence; exit code 0 does not equal complete=true. Missing evidence and contradictory states must remain unsettled, and must be re-observed after an authorized owner performs the listed recovery actions.

PM completes in order:

1. Read the complete Delivery, the actual diff, and worker evidence; run validation matching the artifact type. GUI/Web/desktop changes must launch the real entry point for representative interaction.
2. Verify allowed files, sensitive files, installation authorization, Git identity, commit/head, PR scope, and that services/ports/subprocesses started by the task have been closed out by the owner.
3. supervised workers reuse/release/retain first, then ack; when still alive but the completion was missed, send a structured reminder first, and only use settle。
4. when the user or project has authorized external Git writes, use the pm-closeout.sh PR-first flow. PR uniqueness, frozen head/diff/check/review, two-phase mutation receipt, Monorepo integration path, and uncertain-result recovery are uniformly governed by references/14-pm-orchestrate.md .
5. Obtain the final resource state immediately after delivery confirmation; do not leave cleanup to PM memory.
6. STATUS=done(or the PR has merged) but the process is still alive—including cross-session leftovers—must trigger closeout or escalation in the current inspection round: closeout via the owner channel / release terminal / settle lifecycle, and if it cannot be handled, report the specific lingering objects to the user. Lingering processes continuously squeeze the physical memory dispatch quota (references/22-mem-budget-lane.md); without closeout, directly compress the next wave of dispatchable worker count.

bash scripts/pm-cleanup-worker.sh \
  --project "$PROJECT" --worktree "$WT" --branch feat/worker-a --session worker-a \
  --branch-lifecycle ephemeral-worker --integration-target integration/feature-a \
  --pr "$PR" --expected-tip "$WORKER_TIP" \
  --delivery-mode remote-pr --delivery-commit "$MERGE_COMMIT"
# 手工接管时先预览，再以同一精确参数加 --execute；pm-closeout 成功路径默认自动执行。

Cleanup must distinguish source branch lifecycle from merge target:

• ephemeral-worker: only clean up when exact PR head/base, expected tip, delivery commit, clean worktree, and settled lifecycle are all consistent.
• supervised lifecycle must first perform a complete paginated pre-check using the Run/Dispatch in metadata; only released, or those that can be precisely settled, reclaimable / retained external enter subsequent cleanup. Any missing page, cursor loop, duplicate/missing Dispatch, cross-Run row, or read failure preserves the terminal, worktree, and branch.
• long-lived, or the source branch equals the integration target: keep the remote ref, local ref, and pinned worktree, output RETAINED_WITH_REASON reason=long-lived-branch。
• The invocation arguments must not downgrade the metadata's long-lived ; when a short-lived Worker is merged into a long-lived branch, only clean up the Worker head, never clean up the integration target.
• The result only allows CLEANED、RETAINED_WITH_REASON、CLEANUP_PENDING. After delivery is confirmed, cleanup failure continues to be handled as an independent debt, without re-running push/merge; omitting CLEANUP_PENDING and then claiming a fully closed loop constitutes a Hard Fail.

Git lifecycle and batch stale branch cleanup are handled by the "branch cleanup" entry of the git-workflow Skill; this Skill loads its own cleanup reference as needed.

7. Backend, quota, and dependencies

First distinguish support from daily routing: the daily worker pool keeps Claude Code/Codex and their existing provider routing. ZCode CLI and MiniMax Code CLI are key optional supports, CodeBuddy, Qoder CN, and Qianwen Office are on-demand compatible; these backends (including the legacy zcode driver) are dispatched only when the user explicitly specifies them. They must not be selected automatically due to balance, model capability, sharing a name with the PM, or insufficient main quota; nor may they be written into the quota tier_policy default chain.harness-backend-policy.json 's dispatch_selection is the PM selection contract,hosts only determines invocation permission, not priority.

Within the daily pool, prefer the same host as the PM by default, and cross tools only when quota, model capability, or the user explicitly requires it. Personal preferences are written to the ignored config/orchestration-personal.json, project policies are written to .claude/orchestration.config.json; personal configuration can only select backends within the harness whitelist.

When quota_aware_routing is enabled, before dispatching an order you must run route_suggest.pywith a fresh summary; when the summary is missing, stale, the lane is below the stop line, the provider is unhealthy, or it is unmapped,quota_preflight.py refuses before any side effects. An explicit override must carry the authorization source and be written into the receipt. Quota only routes tasks that have already passed the value gate, and cannot generate quota-burn work. Model and lane judgments read references/01-model-selection-matrix.md and references/17-model-capability-profile.md. The producer of the summary contract is not limited; the zcode lane can use scripts/quota_summary_zcode.py to merge and write in the real observations of the local zcode-quota monitor (only updating the zcode lane, not rewriting the generated_at of other lanes, and not touching credentials), and the data flow and merge semantics read references/21-zcode-quota-producer.md. The ZCode CLI driver's startup binding, configuration isolation, and evidence boundary read references/24-zcode-driver-safety.md. The four credit lanes of the sub2api gateway (qwenworkai / lobsterai / autoclaw / codebuddy) can use scripts/quota_summary_sub2api.py to pull from the gateway /ui/api/quota aggregation endpoint and merge and write (only updating these four lanes, keeping the remaining lanes as-is; qw daily 100 expires the same day, lobster campaign sub-items are near expiry → lane records carry remaining_total / credit_items, the PM should check the near-expiry sub-items before dispatching simple batch tasks, and consume the same-day expiring credits before they expire), and the data flow and lane definitions read references/24-sub2api-quota-producer.md。

When account-level scheduling is needed, read the personal configuration account_routing. Only when enabled=true, the selected backend has been explicitly specified by the user, and it is included in backends , read the local skill_path/SKILL.md and obtain fresh accounts and scheduling results according to its entry. When not enabled, do not call it; when enabled but the Skill is missing, observation fails, or it requires waiting, pause that backend. For invocation and stop boundaries, see references/29-local-account-routing-skill.md. A public Skill only provides the invocation contract; account/card rules and private data remain in the local Skill; this invocation is a PM workflow and cannot claim that the spawn has been mechanically bound to an account.

Standard startup parameters, version check, and permission boundary reading for a standalone CLI references/26-optional-cli-backends.md; reading the native tool entry point and bundled coding entry point of Qianwen Office references/27-qwenwork-cli-worker.md. Reading the version, trusted environment bridge, explicit enablement, and continuation contract of native Orca supervised startup for ZCode CLI references/30-zcode-native-orca.md; when MiniMax Code is explicitly selected, Orca terminal-managed is required by default; only when both are passed --no-orca-mode does it go through direct-connect tmux, and an unreachable Orca or lightweight must not implicitly fall back. Other optional backends temporarily go through terminal-managed or tmux; supervised is not declared verified without real lifecycle acceptance. The orchestration hooks of ZCode CLI/MiniMax Code/Qoder CN/Qianwen bundled coding are not yet integrated, and dispatch must be explicit --allow-prompt-only-install-guard "<授权来源>"; prompt-only is not a mechanical scope/installation guard and does not automatically expand installation or Git permissions.

System dependencies: Bash 4+, Git, jq, Python 3; PR auditing/finalization requires gh; tmux is only needed for the fallback path; the Orca path requires a running Orca runtime and a version-matched CLI. Per backend, the corresponding local CLI is also required; an explicit task memory profile additionally requires an installed native Node and the corresponding CLI; if missing, it refuses and reports the dependency, without automatic installation. Check command:

bash scripts/check-dependencies.sh --backend claude-code --backend codex --check-gh

8. Read the map as needed

Current issue	Read
User-specified remote ZCode GUI author direct-send documentation/engineering PR (author safe-push + sole draft PR, PM read-only verification)	references/38-zcode-gui-remote-pr.md
Standard fast dispatch (Claude Code + GLM/MiniMax + Orca, regular worker three steps)	references/00-fast-dispatch-runbook.md
Model, provider, execution mode	references/01-model-selection-matrix.md、references/17-model-capability-profile.md
Dependencies, checkpoint, Sentinel	references/02-runtime-dependencies.md、03-checkpoint-files.md、04-sentinel-design.md
Legal task splitting, Issue grouping, concurrency incidents	references/05-legal-domain-patterns.md、10-parallel-lessons.md、12-issue-grouping.md
Agent Teams troubleshooting, CLI backend	references/06-agent-cli-reference.md—11-agent-teams-troubleshooting.md the corresponding backend in
Orca worker and PM operations	references/13-orca-cli-worker.md、14-pm-orchestrate.md
Autopilot	references/15-wave-autopilot.md、16-autopilot-durability.md
Dispatch, delivery, review, and fix contract	references/18-dispatch-acceptance-contracts.md
Orca Worker 429 batch inspection and staggered wake-up	references/20-orca-rate-limit-recovery.md
the summary production pipeline of the zcode quota lane	references/21-zcode-quota-producer.md
Standalone ZCode CLI, MiniMax Code, Qoder CN, and on-demand dispatch	references/26-optional-cli-backends.md
First onboarding of a pre-built long-lived worktree, sole writer, and borrow retention	references/31-borrowed-existing-worktree.md
Native Orca supervised ZCode CLI, trusted one-shot environment bridge, and interactive continuation	references/30-zcode-native-orca.md
BigModel subscription authentication, model switching, and measured boundaries of the standalone ZCode CLI	references/28-zcode-cli-bigmodel-coding-plan.md
Qianwen Office native tools and bundled coding CLI, account boundaries	references/27-qwenwork-cli-worker.md
Startup binding, configuration isolation, and security verification of the ZCode CLI driver	references/24-zcode-driver-safety.md
Production pipeline and near-expiry scheduling of the four sub2api credit lanes (qw/lobster/autoclaw/codebuddy)	references/24-sub2api-quota-producer.md
Physical memory budget lane and dispatch queuing	references/22-mem-budget-lane.md
Remote node Worker dispatch (SSH bridge + one-time receipt + capacity/baseline gate)	references/25-remote-node-dispatch.md
Invocation boundaries of the optional local account scheduling Skill	references/29-local-account-routing-skill.md
Read-only verification of ZCode session/turn/final assistant completion evidence (GUI task monitoring direction, not a real-time liveness authority)	references/zcode-session-evidence.md; run scripts/zcode-session-evidence.py(Python 3.9+ standard library)
Read-only GUI monitoring status and one-shot observation (READY still requires PM acceptance, no formal Orca supervision)	references/zcode-gui-monitor-adapter.md、references/zcode-gui-observe.md; for combined verification see references/zcode-gui-evidence-pipeline.md
Chunked transfer verification and Git bundle consumer for the GUI delivery trio	references/zcode-gui-artifacts.md
Verification after modifying this Skill	references/19-maintainer-validation.md

Do not load all references at once; read only the files required for the current stage and backend.

9. Hard Fail

If any of the following situations occurs, stop dispatching, accepting, merging, or cleaning up, and retain reviewable evidence:

• The user requests PM/worker orchestration, the startup gate has not passed, and the PM directly writes business code.
• The worker cwd/worktree/branch/repo/head does not match the target, or the host/backend identity cannot be proven.
• Real provider settings, tokens, backups, or other sensitive information enter Git, logs, or packaged artifacts.
• Unauthorized installation, global environment writes, raw push, out-of-scope modifications, or treating verify as installation authorization.
• A supervised worker has no live Task/Dispatch, or uses STATUS/Sentinel/idle/timeout in place of worker_done and settlement.
• Claiming business completion based only on worker self-reports, static lint, a single UI state, or evidence not bound to head.
• Failing the dispatch value, post-delivery, role separation, or failure recovery gates; an unauthorized reviewer writing out of bounds, or counting a PM exceptional delivery as a regular delivery.
• Before PR create/push/merge, failing the uniqueness and frozen facts audit, or blindly retrying a mutation when the result is uncertain.
• Services/listeners started by a worker have no owner and zero net increment evidence, or processes are killed in bulk by process name.
• Cleaning up active/unknown/release pending workers; mistakenly deleting long-lived branches or integration targets; after delivery, failing to record one of the three resource end states.
• Injecting based only on a single 429 keyword, stale tail, or idle state; sending "continue" to a terminal whose identity is unbound, that is not writable, that is not Orca, or that is still retrying; treating WAKE_ACCEPTED as quota or business recovery.
• When dispatching to a remote node, forging or replaying a dispatch receipt, bypassing node-side gates (receipt one-time + TTL + enabled switch cannot be bypassed), or arbitrarily falling back to local dispatch when the node rejects capacity (PARKED_FOR_REMOTE_CAPACITY); falling back to local when the node is unreachable (rc=65) must be a brand-new local spawn going through the full set of gates, not reuse of the remote context.
• Claiming completion of a remote worker based only on a single ssh signal: all three completion proofs must be collected (STATUS.json end state + PR existence + PR-fingerprint acceptance); supervised mode running on a remote node is always NOT_VERIFIED at M0.

After modifying this Skill, follow references/19-maintainer-validation.md to run the affected tests and the full regression. Only by actually starting a supported Agent and observing worker_done → Delivery → release/精确外部终端结算 → ackcan the supervised path for that backend be marked as verified; other backends must not be inferred by analogy.