multi-agent-orca

Multi-Agent Orca

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

1. Applicable boundaries and side effects

Use this Skill when:

• Advancing two or more locally independent tasks with independent boundaries that can be accepted separately.
• Independent worktrees, branches, sessions, quota lanes, or long tasks that can be taken over manually are needed.
• 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 sessions, multiple workers, a 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), fast desired (15-45 minutes/card measured), ample host quota. 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/limit already hit (subagents share quota with the host; when the limit is hit, all in-flight work is wiped out), large batches of long tasks in parallel, model diversity needed (lane switching uses the user's API quota), tasks where the host session may be interrupted.
  • Mixed-use discipline is channel-independent: conflict control with serialization within the same file domain and parallelism across different file domains applies to all channels.

This Skill may create Git/Orca worktrees, branches, Session Context, terminals, tmux sessions, and supervised Run/Task/Dispatch. It does not automatically install dependencies, nor does it by itself expand push, merge, release, or external scheduling authorization. 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 authorize 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-lived feature/integration branches and fixed worktrees must declare long-lived and be retained. Fail closed when facts are unknown, identity drifts, or the lifecycle is not settled. Supervised cleanup must obtain the exact Run from Session Context and, per worker-list --run <run> --limit 100 , fully traverse the opaque cursor to uniquely locate the Dispatch; if pre-pagination, identity, or results cannot be proven, stop before release, terminal, worktree, and branch mutation.reclaimable After release, the same complete query must still be re-executed; if the post-result cannot be proven, release may have occurred, but terminal, worktree, or branch mutation must not continue. For a single legacy worker that has been confirmed merged but did not go through standard closeout, you may use post-merge-cleanup.sh to perform strict dry-run/execute cleanup; it does not replace standard closeout and must not be used for batch scanning.

2. Mode selection

Mode	When to choose	Completion authority
Orca supervised	The user requires supervision, waiting for results, DAG, ask/reply, or decision gate; the Agent can be recognized by Orca	worker_done → Delivery, then PM acceptance and settlement
Orca terminal-managed	The whitelist backend does not use 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 directories never overlap	checkpoint + real artifacts, PM acceptance
Same-host subagent	Prefer over independent workers for small-to-medium quality-sensitive cards, rapid iteration rounds, and when quota is ample (see the channel selection criteria above); no independent process/branch overhead	Host decides (recommended: RESULT four-section self-report)
Remote node (SSH bridge)	When a second machine is needed to scale concurrency (independent key pool) or to offload local CPU/memory, the PM dispatches via spawn-worker-remote.sh to personal config remote_nodes declared nodes; the full gate set holds locally on the node side, 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 (three completion proofs, not relying on cross-machine Orca receipts)

MiniMax's short task exec In terminal-managed, the startup command reads the full input, does not wait for the TUI, and does not send the task again; long-running tasks still use the interactive CLI. Long-running tasks that have selected ZCode use the configured native supervised launch bridge by default, see Native Orca contract。

Backend and mode selection, configuration sources, and the single next action are all uniformly defined by dispatch profile contract definition. ZCode auto rejects before resource side effects when bridge configuration is missing; legacy explicit native parameters are retained, and the generic compatibility entry must pass --dispatch-profile orca-generic, direct connection remains --no-orca-mode. The profile is the dispatch plan; real 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 fake completion.

3. Pre-dispatch contract and gates

3.1 First complete task modeling

The PM completes the following before any worker side effects:

1. Read project rules and the complete task card, determine goals, non-goals, allowed/forbidden files, verification commands, and completion conditions.
2. Group by root cause, dependency chain, and file scope; parallelize only when scopes are orthogonal, acceptance is independent, and there are no shared lock files/schema/migrations.
3. For each worker specify branch,branch_lifecycle, integration target/base, worktree, session, role, backend/profile/model, provider slot, and resource owner.
4. A normal worker defaults to ephemeral-worker; only long-term capability/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. Read from python3 scripts/dispatch-value-gate.py --describe-policy the current default values 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 shared active inventory already tallied by the PM, the evidence, and the smaller project cap; judge by adding existing workers and this wave's candidates. When an old contract provides no inventory, it only proves this wave's count is legal and cannot be used to claim there are still slots machine-wide. Machine memory slots are a separate gate and cannot replace worker inventory or override cross-project agreements.
6. Validation commands default to scoped: single spec / targeted cases / --bail 1 early stop; full-package complete suites (full test/build chain) do not enter the worker self-validation contract, full validation is single-in-flight (cross-project mutual exclusion), and the default home is a serial re-run at PM closeout. This clause constrains the validation category, not the number of workers (see §5 validation load discipline).
7. Fix one_wave or continuous: when a human requests continuous dispatch/review after return before proceeding/not to be prompted every round, do not default to a single wave. Before continuous-mode dispatch, verify the sole monitored original PM, original task source, formal configuration and cadence, and read PM continuation contract; the explicitly continuous Wave entry is mechanically checked, while other modes are explicitly checked by the PM. Only a master-control heartbeat, a promise to set it later, or a 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; any non-zero exit must not be skipped:

1. Dispatch value gate: the candidate wave uses templates/dispatch-value-gate.example.json isomorphic contract, run python3 scripts/dispatch-value-gate.py <spec.json>. Accept implementation、reusable_verification, merge_gatebound to a named PR/head, and business_artifactwith a business purpose, source, precise artifacts and item-by-item criteria. Research, design, documents and reports are accepted by business artifact; maintenance docs with no clear consumer, placeholder investigations and pure-format wave expansion are still rejected.
2. Delivery value back gate: run worker-value-postflight.pywith the same spec; engineering delivery checks the real diff, declared assets, validation commands and the 40-character immutable head; business delivery reads the real files in a Git or non-Git directory and binds the contract, source and file fingerprint into the same delivery identity.
3. Role-separation acceptance gate: non-trivial implementation is completed by an implementer and reviewer in different dispatch/session, run review-acceptance-gate.py. Self-review, delivery identity drift, missing binding evidence, failed validation or uncleared blockers are all rejected; business artifacts must also be checked item by item for content and source by a different author, and a file hash does not prove the content is correct.
4. Failure recovery gate: first classify with acceptance-recovery.py .internal_recoverable fix within budget and re-review independently;external_dependency、safety_unknown or budget exhaustion is required before parking. A docs-only acceptance fix for an already-named PR can only go through the very narrow preflight/postflight channel of acceptance-repair-gate.py .

When committed engineering validation needs to be recorded automatically, you may follow theengineering evidence collection contractand use the optional collection/check entry; it only generates the original delivery back-gate evidence and continues to retain independent review and real completion verification.

Fields, commands, exception enums, reviewer evidence budgets and recovery semantics are read uniformly from references/18-dispatch-acceptance-contracts.md; do not create a separate classification table in the project prompt or another script.

3.3 Runtime security gate

• spawn-worker.sh Identify the real PM harness from the full process ancestor chain, and intersect it with the nested-layer allowlist. Unknown, conflicting or unprovable hosts fail closed;--pm-harness only makes a consistency declaration and cannot escalate privileges.--base-ref Only reference names (main、origin/main、refs/heads/x , etc.) are accepted, not bare shas — 40-hex (and 7–40 character pure hexadecimal values that Git resolves as a commit rather than a reference name) will, before any worktree/provider/terminal side effects, be rejected with SPAWN_WORKER_BASE_REF_MUST_BE_REF: <值> and exit, avoiding a later deadlock in pm-cleanup-worker between INTEGRATION_TARGET_MISMATCH(argument=main vs metadata=sha) and PR_BASE_MISMATCH(expected=sha vs actual=main).Character class is case-sensitive: the guard also recognizes [0-9a-fA-F], uppercase shas (e.g. 96A304DF…) and mixed-case shas 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 a compatible ZCode app-server driver (zcode). CodeBuddy PM can still only dispatch itself, and the existing authorization for ZCode PM still only includes Claude/Codex; adding worker support does not add PM hosts. The QoderWork backend and old aliases have been removed, and the old bundled CLI symlink must not be treated as Qoder CN. The Hermes host is still identified by install-path signature; a bare word is not evidence.
• First-time onboarding of a pre-built worktree only accepts an explicit borrowing contract, a new Session, authorization from the original owner, and on-site proof that there is no writer; the default occupied branch/path gate remains rejecting, and borrowed long-lived trees and branches must not be deleted by failure/closeout. Read references/31-borrowed-existing-worktree.md; 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 match the verified project. On failure, only clean up resources whose ownership can be precisely proven; the PM must not use this as an opportunity to directly implement business logic.
• Workers only modify allowed paths. By default, a reviewer may only write to its own Session Context; fixing a branch under review must explicitly --review-repair-grant <授权来源>, and any config/*.local.yaml is not writable.
• Shell enforces two strategies depending on 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 block recognized install 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 strategy; Claude auto is not a mechanical sandbox for Shell file write scope or arbitrary program side effects, and the PM must still check 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 an exact --allow-install-command and an auditable authorization source. Orca repo Setup is an earlier independent stage, is skipped by default, and must not reuse this authorization.
• Failure continuation of an already-closed ZCode original Session is handled perNamed recovery entry 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 restore failure history via ready-reset.
• The Supervised completion channel is bound to the authority receipt from PM launch, and after worker-start freezes the Dispatch identity and capability digest; before sending worker_done re-verify 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 native available execution permission per the authorized task: ZCode CLI defaults to --mode yolo, MiniMax batch defaults to --permission full; an explicitly narrower mode remains in effect. MiniMax long-running tasks keep the interactive CLI, with permissions configured and verified per optional CLI contract , and not substituted with batch parameters. Host approval, business scope, account login, and orchestration admission are independent boundaries and are not cancelled by worker mode.
• Worker default execution permission (v2.22.0, user decision 2026-09-06): workers are isolated in a dedicated branch worktree, push+PR is the necessary delivery path, security classes are relaxed per "segmented validation" — a pipeline/;/&& compound command is 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 like ls/grep/cat/jq/sort,node --version version queries); redirects are limited to /dev/null and the temp directory (reject .. 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 four identity items (--git-expected-name/--git-expected-email/--git-integration-base/--git-push-remote) are 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 alternative to bare push, not the only path.
• Deletion of tracked files is a separate 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; scope globs, subsequent reauthorize --allow-cmd、-r/-f/--cached, multiple paths, directories/gitlinks, pathspecs, Shell expansion, and compound commands must not expand permission. 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 , the spawn call must also pass --verification-contract <spec.json> --verification-task-id <ID>; without a file contract pass --verify-cmditem by item. Commands enter the authority receipt, METADATA, and allowed_shell_commandsverbatim as complete strings and must not be split by cd <subdir> && <verify>. Under the Claude auto policy, this list is still the mandatory command for delivery acceptance, not the sole source of execution permission for ordinary Bash.
• When requiring Worker self-verification pass --require-verification, or in the project .claude/orchestration.config.json set verification.required: true. Must fail before terminal/Task/Dispatch/task injection 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. Business contract explicitly acceptance_mode: content_review use an empty command array and perform an independent content review, without automatic discovery of unrelated tests; if it conflicts with explicit --require-verification , 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. Existing Node/Make discovery is unchanged; Python only injects when the root manifest and root tests/ are both present, inject 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 , without recursive guessing. 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

Based on the running CLI's guide and --help .spawn-worker.sh only when the current PROJECT_DIR can be precisely parsed as the same Orca worktree/repo does it enter Orca;--no-orca-mode explicitly uses 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 a successful receipt. Do not let concurrent spawns each create/rebind a Run, and do not send the full prompt again after tasks are injected 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 re-create Tasks/rebind the Run. A single Worker may prepare the Run after quota/mem pass and before creating the lease/worktree/terminal; if there is no reliable sender, reject. When old context lacks runtime, only positively re-verify the current binding and explicitly state that historical continuity is unverified; existing runtime drift cannot be bypassed; still use Orca consumer fencing as the final judgment.

For the full manifest, Terminal-managed, Dispatch self-check, cold-start recovery, settle, and metadata contract reads 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 is retained in the contract payload. The send receipt must bind the Orca message ID of the same Dispatch relay and the full request digest; success only proves durably_enqueued. Read-only inspection uses inbox（check --peek), all top-level and payload identity/type aliases that appear must be consistent; structured messages must have precise provenance, and native correlation messages without payload must simultaneously provide thread+correlation filters and precisely match the worker sender, coordinator recipient, Run, and native correlation thread. Visibility of related messages does not prove execution of reply, consumption, start of execution, or completion of the business. Status hierarchy, allowlists, idempotency fingerprints, and sensitive payload rejection rules are read uniformly from references/14-pm-orchestrate.md, do not create another chat layer or use terminal prompts instead of Orca messages.

When a Worker needs the PM to answer, use the live preamble's ask; after timeout, cancel, or disconnection, only use 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 at most 50 complete FIFO Deliveries returned; the same batch is replayed before ack; only after completing question reply, escalation handling, worker_done business acceptance, and terminal ownership item by item may the exact Delivery be acked. 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 having processed the next batch. The Worker, before new files, after each scoped test, and worker_done before executing non-peek check --terminal <live worker handle>, after processing the whole batch acks only that Worker Delivery with the same handle, and continues draining subsequent batches;send success or inbox --peek visibility does not prove the Worker has processed.consumer_fenced indicates the consumer generation/process identity has been replaced,dispatch_inactive indicates the original Dispatch has been settled, stopped, or is no longer active; if either appears, stop immediately, and must not retry check or send worker_done. The mandatory prefix and Shell gate jointly reject impersonating processing with --peek/--all/--unread ; 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. In supervised mode, 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 completes ask/resume, natural checkpoint receipt, final receipt, minimal implementation, scoped verification, authorized file commit, and the unique Session Context RESULT; review-only/no-change does not create empty commits.spawn-worker.sh injects the absolute WORKER_SESSION_CONTEXTin all legitimate backend startup paths, independent of whether installation/scope guard is enabled; a legitimate prompt_only_degraded worker without allow-paths can also locate it. This value is used only for locating; it does not grant installation/Shell/scope permissions, nor does it pass off degradation as hook activity. The Worker checks in its own process that this value and all non-empty legacy guard bindings (SCOPE_GUARD_SESSION_ROOT、WORKER_INSTALL_AUTH_FILE parent directory) are spelled consistently and the directory exists; only after all checks succeed is the path adopted; if all are missing or any is relative/conflicting/unavailable, refer to the PM, do not guess the repository root, and do not modify authority. Legacy invocations can still be located by legacy guard bindings. The prefix does not expand installation, Shell, or push/PR permissions; for auxiliary commands and the .venv opt-in flow see references/02-runtime-dependencies.md。

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

field and checkpoint reading references/03-checkpoint-files.md. In supervised mode STATUS is only for auxiliary observation; the completion authority remains worker_done → Delivery。

5. Inspection, Intervention, and Continuous Advancement

Inspect by 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 work, blockage, boundary violation, or verification failure is found, preferentially send a narrow correction to the original worker; when independent review is needed, assign a separate 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 explicitly authorizes it and the policy is fixed in the project task source. L1 current-session advancement reads references/15-wave-autopilot.md; the 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 sources, or provider leases alone as a persistent controller.

After the Worker returns, the original PM pins the artifacts/head, a separate context reviews independently, and the same original Task writes back, then either fixes along the original issue or advances to the next named legitimate item; responsibility for this wave 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, and distinguish monitoring configuration, formal automatic triggering, and the full automated business cycle; checking that configuration passes does not sign off automated self-healing, see continuation evidence level。

When cross-project checking whether an Orca Worker is stuck idle due to 429/usage limit, run scripts/orca_rate_limit_recovery.py --manifest <私有清单>; by default read-only, only with explicit --execute for high-confidence RATE_LIMIT_IDLE send a single fixed 'continue' through the terminal input channel. tmux, single-keyword/stale tail, ungrouped identities, and uncertain states 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: multiple workers' long output exhausted the in-session node process V8 heap FatalProcessOutOfMemory → SIGABRT, and the PM's periodic re-pull formed a crash loop and at one point triggered a forced restart of the whole machine).spawn-worker.sh Since 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 disabled), so the worker exits itself when it hits the limit rather than dragging down the system. When PM inspection finds a worker node OOM (exit code 134 / SIGABRT / logs containing FatalProcessOutOfMemory / a new node OOM report in the system crash report directory (DiagnosticReports) with a matching timestamp): do not immediately re-pull the same task; wait at least until the next inspection round and globally decrement concurrency by 1, and before re-pulling you must rerun the memory budget precheck (probe detects on-site at every spawn and does not cache; if quota is insufficient, queue according to PARKED_FOR_MEMORY , and do not bypass); after 2 consecutive OOMs on the same task, stop re-pulling, park it, and report to the user—this usually means the task itself produces excessively long output (full log aggregation, very large test runs), and the task side needs to reduce output or split it, rather than retrying harder.

Physical memory budget queueing (mem budget lane)：spawn-worker.sh before any worktree/terminal/lease/dispatch side effects, run scripts/mem_budget_probe.py, converting on-site 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 whole gate). If quota is insufficient or detection is unreadable, spawn is rejected 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. On 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 a single worker's bleeding point; this gate manages the aggregate commitment and also covers non-node runtimes that cannot rely on a heap cap. For data sources, budget derivation, pressure tightening, and the queueing state machine, see references/22-mem-budget-lane.md。

Named task resource profile: for controlled tasks that genuinely have task measurement/scope and the 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 full MiniMax worker still requires at least 3 GiB, a single writer, and a 20-second stability window, and the actual Node heap cap does not equal the RSS limit. Without a profile, the old defaults are retained; a profile cannot be allowed through with budget 0 or an old snapshot. For fields and independent source/identity rechecks, see resource contract。

Verification load discipline (verification lane): constraint validation category; does not constrain worker count. Worker self-verification defaults to scoped (single spec / targeted cases / --bail 1); full suites are single-in-flight and mutually exclusive across projects—when a worker genuinely needs to run a full suite on site, first probe for existing full test processes (e.g., pgrep -fl 'vitest|pytest|jest|go test'); if exclusive ownership cannot be confirmed, back off and wait or switch to scoped. Probing is a best-effort on-site signal; no cross-project lock file is created—better to under-concur than to misconcur; the full re-run at PM closeout is naturally serial and is the default home for full verification. Verification output must always be redirected to log files, bringing back only a bounded tail (e.g., tail -50) to the terminal/session—unbounded long-output flooding is exactly the feeding tube for session-side node runtime OOM. When PM inspection finds system load spiking and multiple workers running verification simultaneously, correct to staggered queuing (wait for in-flight verification to finish before releasing the next batch) rather than cutting worker count. This discipline is complementary to the single-process heap ceiling and physical memory lane: the heap ceiling governs single-process bleed points, the mem lane governs the total commitment, and this discipline governs the concurrency category and output volume of verification execution (in the 2026-09-05/06 incident, all three were missing their last link: concurrent full self-verification simultaneously created load spikes and oversized output).

6. Acceptance, Git delivery, and resource closeout

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

PM completes in order:

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

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: clean up only when exact PR head/base, expected tip, delivery commit, clean worktree, and settled lifecycle all agree.
• Supervised lifecycle must first perform a full paginated pre-check using the Run/Dispatch in metadata; only released, or precisely settleable reclaimable / retained external proceed to subsequent cleanup. Any missing page, cursor loop, duplicate/missing Dispatch, cross-Run row, or read failure retains terminal, worktree, and branch.
• long-lived, or the source branch equals the integration target: keep the remote ref, the local ref, and the pinned worktree, and output RETAINED_WITH_REASON reason=long-lived-branch。
• The invocation parameters 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 failures continue to be handled as an independent debt, without re-running push/merge; omitting CLEANUP_PENDING and then claiming full closure constitutes a Hard Fail.

The Git lifecycle and batch stale-branch cleanup are handled by the "branch cleanup" entry of the git-workflow Skill; that Skill loads its own cleanup reference on demand.

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 support; CodeBuddy, Qoder CN, and Qwen 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 because of balance, model capability, sharing a name with the PM, or insufficient primary quota; nor may they be written into the quota tier_policy default chain.harness-backend-policy.json The dispatch_selection ofhosts 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 policy is written to .claude/orchestration.config.json; personal configuration may select a backend only within the harness whitelist.

When quota_aware_routing is enabled, before dispatching a task you must run route_suggest.pywith a fresh summary; if 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 is only routed for tasks that have passed the value gate; it cannot generate quota-burn work. Model and lane decisions read references/01-model-selection-matrix.md and references/17-model-capability-profile.md. The producer of the summary contract is not restricted; the zcode lane can use scripts/quota_summary_zcode.py to merge the real observations of the local zcode-quota monitor into the summary (updating only the zcode lane, not rewriting generated_at of other lanes, and not touching credentials); for the data flow and merge semantics read references/21-zcode-quota-producer.md. For the ZCode CLI driver's startup binding, configuration isolation, and evidence boundaries 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's /ui/api/quota aggregation endpoint and merge-write them (updating only these four lanes and keeping the other lanes as-is; qw's daily 100 expire the same day, and lobster campaign sub-items are near expiry → the lane record carries remaining_total / credit_items, and before dispatching simple batch tasks the PM should first check the near-expiry sub-items and consume the credits that expire that day before they expire); for 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 use its entry to obtain fresh accounts and scheduling results. When not enabled, do not invoke it; when enabled but the Skill is missing, observation fails, or it requires waiting, suspend that backend. For invocation and stop boundaries see references/29-local-account-routing-skill.md. The 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 spawn has mechanically bound an account.

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

System dependencies: Bash 4+, Git, jq, Python 3; PR audit/closure require gh; tmux is only needed for the fallback path; the Orca path requires a running Orca runtime and a version-matched CLI. Each backend also requires its corresponding local CLI; the explicit task memory profile additionally requires an installed native Node and the corresponding CLI, and when missing, it refuses and reports the dependency without auto-installing. Check command:

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

8. Read the map on demand

Current problem	Read
User-specified remote ZCode GUI author direct-send docs/engineering PR (author safe-push + unique draft PR, PM read-only verification)	references/38-zcode-gui-remote-pr.md
Standard quick 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	references/05-legal-domain-patterns.md、12-issue-grouping.md
Concurrency anomalies: symptoms, facts and recovery entry points	references/10-parallel-lessons.md
Common parameters for Claude/Codex and routing to guides for other backends	references/06-agent-cli-reference.md
CodeBuddy startup, permission waiting and session continuation	references/08-codebuddy-cli-worker.md
Legacy ZCode old diagnostics pointers	references/09-zcode-cli-worker.md
Agent Teams troubleshooting	references/11-agent-teams-troubleshooting.md
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
Summary production pipeline for 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, unique writer and borrow-and-retain	references/31-borrowed-existing-worktree.md
ZCode CLI native Orca supervised, trusted single-use environment bridge and interactive continuation	references/30-zcode-native-orca.md
BigModel plan authentication, model switching and measured boundaries for the standalone ZCode CLI	references/28-zcode-cli-bigmodel-coding-plan.md
Qwen Office native tools and bundled coding CLI, account boundaries	references/27-qwenwork-cli-worker.md
Startup binding, config isolation and security verification for the ZCode CLI driver	references/24-zcode-driver-safety.md
Production pipelines and near-expiry scheduling for 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-time observation (READY still requires PM acceptance, no formal Orca supervision)	references/zcode-gui-monitor-adapter.md、references/zcode-gui-observe.md; for combined validation see references/zcode-gui-evidence-pipeline.md
Validation chunked transfer and Git bundle consumer of the GUI delivery trio	references/zcode-gui-artifacts.md
Validation 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. references retain only reusable operations and current interface contracts; task plans, to-dos, per-round acceptance, and on-site evidence indexes are written back to the original TASKS card, important trade-offs go to DECISIONS, and no runtime reference is added for a single task.

9. Hard Fail

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

• The user requests PM/worker orchestration, or the PM directly writes business code when startup gates have not passed.
• 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.
• Dispatch-value, post-delivery, role-separation, or failure-recovery gates have not been passed; an unauthorized reviewer writes out of bounds; or a PM exception delivery is counted as a regular delivery.
• Before PR create/push/merge, the uniqueness and frozen-fact audit has not passed, or mutations are blindly retried when the result is uncertain.
• Services/listeners started by the 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; accidentally deleting long-lived branches or integration targets; failing to record one of the three resource end states after delivery.
• Injecting based only on a single 429 keyword, a stale tail, or idle status; sending "continue" to a terminal that is not identity-bound, not writable, not Orca, or still retrying; claiming WAKE_ACCEPTED as quota or business recovery.
• Forging or replaying dispatch receipts during remote node dispatch, 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); fallback to local when the node is unreachable (rc=65) must be a brand-new local spawn going through the full gates, not reuse of remote context.
• A remote worker's completion may not be claimed from a single ssh signal: all three completion proofs must be collected (STATUS.json final state + PR exists + PR-fingerprint acceptance); in M0, supervised mode running on a remote node is always NOT_VERIFIED.

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

Name migration and compatibility

Since 3.0.0, use multi-agent-orca. For installation migration, first run python3 scripts/skill-name-migration.py plan --source NEW_SOURCE --old-link OLD_INSTALL_LINK --owner OWNER --manifest PRIVATE_MANIFEST, check the manifest, then sequentially apply / verify; to revoke the newly added links from this run, use rollback. The script depends only on the Python standard library, the default plan does not modify installation entry points, and the manifest is saved outside the repository or in a local archive.

Old directory skills/multi-agent-orchestration/ has been fully retired and deleted per user decision (3.0.1): historical archives and private config have been merged into this directory, and the old name remains only in wire schema literals (multi-agent-orchestration.*.v1）、MAO_*/MULTI_AGENT_ORCHESTRATION_PERSONAL_CONFIG Environment variables and ~/.local/state/multi-agent-orchestration/ continue to be compatible in the state directory, without creating a second state tree. All legacy absolute-path consumers must switch to this entry point; if in-flight tasks still reference old paths, migrate them before dispatching. Private configuration does not enter the release package.