Merge orchestration-guide-rewrite into integration; fold auto-ack, auto-release, one-step start and mid-turn wake into the rewritten guide

This commit is contained in:
Jinwoo-H
2026-10-28 13:36:33 -04:00
13 changed files with 445 additions and 425 deletions
+1
View File
@@ -142,6 +142,7 @@
"ce9a81cb2e6bbb8487107d2e088bf9fd6e0ba71ebc6bcc1929f827fde65fec6b",
"d37fa68601e6b383146976baf4ac28b1ecc8acef808394e9cede434a08be82ce",
"d6490454f5a2814e98bb3848f05574beb81b7c5111295efd8c1d26c8b16bee4a",
"d9ac622844f5d94c02e01d663833a04bd7db522b59385ac92ec5ab5e7cb017b3",
"e3b81f4d713f97a65a35ca5db0606939cebfdaade3daf1d709a76df1c869fd8a",
"e4aa2bde868fdb45f905189361ab09e613ea9d83875ba7e951b6f3addfb58c75",
"e72ecaf625b4a839189e8f13717b0c5b7a309fc82c9ed0dbfb8e861e31a2124a",
+155 -177
View File
@@ -13,214 +13,192 @@ description: >-
# Orca orchestration
Orchestration is Orca's structured coordination layer. It records who owns work,
which attempt is authoritative, and when supervised work has settled.
You (the coordinator) start worker agents through Orca and end your turn; Orca
normally wakes you when a worker reports back. Terms:
## Outcome
- **Run**: your inbox for one goal. Workers report to it.
- **Task**: one piece of work. **Dispatch**: one attempt at a Task by one worker.
- **Settled**: Orca recorded an outcome for the attempt, usually from the
worker's `worker_done` (succeeded or failed); a stop, abandon, or failed start
also settles it.
**Result:** every in-scope Task has one explicit outcome and every settled worker
terminal has a next owner or cleanup decision. **Next consumer:** the user who
requested supervision. **Done:** all expected Dispatches have settled, every
delivered message was processed, each settled worker was
reused, explicitly retained, or released, and the turn ends only when the report
to that user names, per Task, its outcome, the evidence behind it, and any
unresolved blocker.
## Your role
**Safe failure:** preserve work and authority and report the state as unknown or
`unverifiable`. Only positive proof of exit authorizes stop, abandon, or retry,
and only an accepted settlement authorizes release. Every other observation,
absence included, is a checkpoint.
| Situation | Role | What to do |
| -------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------- |
| The user asks for another agent's result back ("have Codex review this and report"), supervision, a task DAG, or ask/reply | Coordinator | Follow the main recipe below |
| Your prompt has a live preamble with Task and Dispatch IDs | Dispatched worker | Follow the preamble and "If you are a dispatched worker" below |
| The user asks to hand work off or start another agent or worktree, and wants no result back | Handoff owner | Use the `orca-cli` skill; create no Run, Task, or Dispatch |
| A message carries a legacy authority label | Compatibility | Load `references/legacy-contract-migration.md` before changing any state |
| None of the above | Ordinary agent | Send no lifecycle messages; use `orca-cli` for terminal and worktree work |
## Classify the role
Choosing a model or effort does not make a handoff supervised: `orca-cli`'s
`worktree create --agent` and `agent launch` take `--model` and `--effort` too.
| Current context | Role | Route |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------ |
| The user explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use a decision gate, or manage ask/reply | Coordinator | Use the supervised loop below |
| The current prompt contains a live injected preamble with Task and Dispatch IDs | Dispatched worker | Follow the preamble and the worker obligations below |
| The user asks to hand off ownership or start another agent/worktree without supervision | Handoff owner | Use `orca-cli`; create no Run, Task, or Dispatch and do not monitor completion |
| A message carries a legacy authority label | Compatibility operator | Load the legacy contract reference before any lifecycle mutation |
| No live preamble and no explicit supervision | Ordinary terminal agent | Do not emit lifecycle messages; use `orca-cli` for terminal/worktree work |
## Main recipe
Model or effort selection does not make a handoff supervised: `orca-cli`'s
`worktree create --agent` and `agent launch` take `--model` and `--effort`, and
open a chat or a terminal per the user's Chat UI setting, as `worker-start` does.
Never substitute a non-Orca subagent tool when Orca orchestration provenance was
requested.
## Authority and safety floor
- A Run is a durable namespace and coordinator inbox; it does not schedule or
place workers. A Task is work. A Dispatch is one authoritative Task attempt.
- Lifecycle authority comes from the active Dispatch, not a terminal title,
copied ID, old database row, provider transcript, or visible pane.
- Workers use the exact executable, handle, Task ID, and Dispatch ID in the live
preamble, plus any other flag it carries. Never reconstruct, translate, or
broaden those arguments.
- After remote start, address the worker by Dispatch ID. The execution host owns
process, filesystem, transcript, stop, and cleanup facts. Preserve the verdicts
`live` / `unverifiable` / `exited`; contact loss is not process death.
- Liveness is layered: `worker-list`'s `projection.liveness` is the fleet verdict
for the agent; `worker-show`'s `observation.status` is PTY liveness only. A live
terminal can still hold a dead or stuck agent.
- Folder workspaces are valid; never require Git or assume a worktree.
- Clients and remote servers update independently. Treat unknown optional fields
as absent. A new stream operation requires advertised capability because old
decoders may silently drop unknown opcodes. Never fall back to local execution
when remote authority or capability is unproven.
- Use the executable you used to run `skills get` for the entire run. In the
examples below, replace `ORCA` with it; do not create a shell variable or run
`ORCA` literally. If it fails, report that exact error instead of switching.
- `ORCA status --json` shows your Orca session ID as `caller.orcaSessionId` when you have one.
- A successful `orchestration send` proves durable enqueue; its wake or nudge is
best-effort attention only and does not prove the recipient read or accepted it.
## Worker obligations
The injected preamble is authoritative. A dispatched worker must:
1. Do only the current Task and use the preamble's `ask` command for a blocking
coordinator question. Never open a local question TUI the coordinator cannot
answer. Resume the same message ID after an ask timeout.
2. Send heartbeats only at the cadence in the preamble. A heartbeat proves
liveness, not completion. If a background loop sends them, restart it if it
expires mid-task, and stop it before `worker_done`.
3. Read coordinator follow-ups at each natural checkpoint — before starting a
new file, after a test run — and once more immediately before `worker_done`:
`ORCA orchestration check --terminal <your_handle> --json`.
Each `check` marks the batch it returns handled; repeat until `count` is 0.
Only if a batch lacks `"deliveryAcknowledged": true` (an older Orca), ack its
`deliveryId` with `--ack`. If a `check` reply was lost, rerun it with the
`--retry-request <id>` it printed; after lost context, read handled mail with
`ORCA orchestration inbox --terminal dispatch:<dispatch_id> --limit 50 --full --json`.
4. Send `worker_done` exactly once, from the dispatched terminal, with a
three-sentence executive summary, both lifecycle IDs, and explicit
`--outcome succeeded` or `--outcome failed`. Never encode failure only in prose.
5. Append `--files-modified` and `--report-path` only with real values when
applicable. After `worker_done`, end the dispatched turn and idle; do not poll
or start new work.
A direct user instruction after completion starts new user-owned work and takes
precedence over the idle rule. Do not reuse the settled lifecycle IDs.
## Canonical supervised loop
Confirm the runtime and start the full independent wave before waiting.
`worker-start --spec` creates the Task and its attempt in one call; with no Run
bound, it also creates one bound to you (an older Orca refuses instead; then
`run-create` first). Its receipt's `run` names the Run it created or joined; if
that is an earlier goal's Run, `run-create` first:
`ORCA` below stands for the executable you used to run `skills get`. Type that
executable in its place; do not create a shell variable or run `ORCA`
literally. If it fails, report its exact error; never switch to another one.
```text
ORCA status --json
ORCA orchestration worker-start --spec "<worker A task>" --worktree current --agent codex --json
ORCA orchestration worker-start --spec "<worker B task>" --worktree current --agent claude --json
ORCA orchestration check --wait --types "worker_done,escalation,question" --timeout-ms 900000 --json
ORCA orchestration worker-start --spec "<task>" --worktree current --agent claude --json
```
After a restart, resume your own Run with `run-use --id <run_id>`. A worker
cannot bind the Run it works for or an ancestor, and cannot use
`--takeover-legacy`; an already-bound no-op remains allowed. When its
coordinator directs a handoff, a replacement worker may resume a separate Run
with plain `run-use`.
- With no Run bound to you, `worker-start` creates one and binds it; its
receipt's `run` names the Run it created or joined. If that is an earlier
goal's Run, or the Orca is older and refuses with `run_required`, run
`ORCA orchestration run-create --objective "<goal>" --json` first.
- `--worktree current` runs the worker in your workspace; an exact workspace
selector runs it in another existing one. Placement goes on `worker-start`;
`run-create` takes none.
- Create a new workspace only when the user asks for one, or sharing a checkout
would conflict (for example, the change belongs to a project you are not
in). Pass the project with `--repo`; `ORCA repo list --json` gives its id.
Without `--repo`, Orca uses the repository of the Orca-managed Git worktree
you are in, and fails if there is none:
`ORCA orchestration worker-start --spec "<task>" --worktree new-top-level --repo id:<repoId> --name <short-name> --agent claude --json`
- `--agent` takes a configured agent id such as `claude` or `codex`; use the
one the user asked for. Add `--model` only when the user named one.
- Start every independent worker before you stop. One `worker-start --spec`
call creates the Task and its Dispatch.
- If `worker-start` exits non-zero, do not run it again. Read `failedStage`
and `residualResources` in its output, then load
`references/recovery-and-cleanup.md`.
If `worker-start` exits non-zero, do not relaunch. Read the receipt's
`failedStage` and `residualResources`, then load
`references/recovery-and-cleanup.md`.
Then tell the user what you started and **end your turn**, unless you need to
wait inside this turn (below).
Use `run-create --objective "<objective>"`, then `task-create` plus
`worker-start --task <task_id>`, for planned fan-out with dependencies or a
retry of a known Task. Use dependencies only for real ordering
and prefer parallel waves over chains deeper than three or four steps; nested
workers obey the depth limit, and a new Run does not reset the caller's depth.
A dispatched worker starts its own helpers with `worker-start --spec` on the Run
it works for, without `run-create`; the helpers report to that worker.
- Do not poll: no sleep loops, watch scripts, scheduled wakeups, or repeated
`check --peek` or `worker-list` calls. A plain `check` takes the mail it
returns, so a script that runs one hides it from you; scripts that only watch
must use `--peek`.
- To steer a running worker, use
`ORCA orchestration send --to dispatch:<dispatch_id> --subject "<topic>" --body "<guidance>"`;
never type into its terminal.
- Let `worker-start` create a worker's workspace; never make its checkout
yourself.
A consuming `check` names its caller with `--terminal <handle>`, never `--from`;
omit it inside the coordinator's own Orca terminal. It returns the bound Run's
oldest FIFO Delivery and marks it handled; `--ack` is still accepted but not
needed. Process every message: reply to questions, validate each `worker_done`
against the expected active Dispatch, and decide each settled terminal's next
owner before the next `check`:
## When Orca wakes you
When a worker reports, Orca sends you a new message: "You have N orchestration
messages. Run `orca orchestration check --run <run_id>`." In a terminal it is
typed in for you, even mid-turn (it queues like any typed input); in a chat it
arrives as a user message. Run the command it names:
```text
ORCA orchestration reply --id <message_id> --body "<answer>" --json
ORCA orchestration worker-release --dispatch <dispatch_id> --json
ORCA orchestration check --wait --types "worker_done,escalation,question" --timeout-ms 900000 --json
ORCA orchestration check --run <run_id> --json
```
If a `check` reply was lost, rerun it with the `--retry-request <id>` it printed.
If you lost context, read the handled mail with
`ORCA orchestration inbox --terminal run:<run_id> --limit 50 --full --json`.
Scripts that only watch the inbox must use `--peek`.
- Each `check` marks the mail it returns as handled; run it again until
`count` is 0. Only an older Orca, whose reply lacks
`"deliveryAcknowledged": true`, needs `--ack <delivery_id>` on the next check.
- Answer each `question` with
`ORCA orchestration reply --id <message_id> --body "<answer>" --json`.
- Check each `worker_done` against the Dispatch you expect.
- If a `check` reply was lost, rerun it with the `--retry-request <id>` it
printed. If you lost context, read handled mail with
`ORCA orchestration inbox --terminal run:<run_id> --limit 50 --full --json`.
- Tell the user the result, or end your turn again while workers are still
running. A quiet inbox proves neither progress nor failure.
Keep waiting until every expected Dispatch settles. A timeout or empty result is
a checkpoint, not a failure. Do not stop, retry, release, or launch a duplicate
editor without the positive proof `## Outcome` requires.
**Waiting inside one turn.** Only when the user needs the result before your
turn ends, or you run outside an Orca terminal or chat, block instead. Keep the
timeout under your tool-call limit (540000 ms suits a 10-minute limit).
Outside your own Orca terminal or chat, add `--terminal <handle>`:
After three consecutive empty waits, stop waiting blindly and enumerate with
`ORCA orchestration worker-list --include-remote --json` (defaults to the bound
Run; `--run <run_id>` overrides; the receipt's `scope` names which), acting on
each row's `projection.attention` categories, `projection.attention.requiresAction`, and literal `projection.nextAction` argv.
Rows come newest first and page at 100: while `page.hasMore`, follow `page.nextCursor` with `--cursor <value>`.
A `none` `nextAction` has no argv to run: read `liveness.reason` and keep waiting
with `check --wait`. Absence never earns an argv; settlement and pending work still do.
Leave the wait only on positive proof the agent stopped: `exited` liveness, the
worker's own observation of process exit, or a transcript whose final agent turn
sent no `worker_done`. Then load `references/recovery-and-cleanup.md` and choose
`worker-stop` or `worker-abandon` explicitly. `unverifiable` is absence,
including when `worker-show` reports `agentWait` null. Absence never authorizes
stop, abandon, retry, or release; keep waiting or inspect.
```text
ORCA orchestration check --run <run_id> --wait --types "worker_done,escalation,question" --timeout-ms 540000 --json
```
`worker-start` is the normal path, composing placement, terminal readiness,
prompt injection, and supervised resource ownership. `dispatch --inject` leaves
an operator-created process unsupervised and is only for an expressiveness gap.
A timeout is a checkpoint, not a failure: wait again, or end the turn. After
three empty waits in a row, inspect the workers with
`references/recovery-and-cleanup.md`. After a restart, resume your Run with
`ORCA orchestration run-use --id <run_id> --json`.
## Task-spec contract
## Task spec
Every Task spec must be self-contained and name:
Make each Task spec self-contained:
- **Target:** the files, component, or environment in scope.
- **Change:** the concrete result to produce.
- **Constraints:** invariants, compatibility rules, and do-not-touch boundaries.
- **Ownership:** what this worker may edit and any coordination boundary.
- **Observable acceptance:** the test, output, or evidence that proves completion.
- **Constraints:** rules to keep, and what not to touch.
- **Ownership:** what this worker may edit.
- **Acceptance:** the test, output, or evidence that proves it is done.
## Completion accounting
A review-only worker's `worker_done` lets you summarize its findings, not edit
files yourself. Send fixes to a worker unless the user gave them to you.
After an accepted success or failure report, immediately do exactly one:
## Completion
1. Reuse the same proven agent terminal for an immediate follow-up Dispatch.
2. Record user-requested retention with `worker-retain`.
3. Run `worker-release`.
A valid `worker_done` settles its Task; do not follow it with `task-update`.
Orca releases a finished terminal worker about 2 minutes after its
`worker_done` (`autoReleaseAt` in `worker-list`). Before then, if you want it:
Release is post-settlement cleanup, not cancellation. Only an accepted
settlement authorizes it; no other observation does. If release is uncertain,
follow its exact recovery receipt and never substitute `terminal close`.
- give it a follow-up (`references/coordinator-loop.md`), or
- keep it with `ORCA orchestration worker-retain --dispatch <dispatch_id> --json`.
A valid `worker_done` settles the Task and Dispatch automatically; do not follow
it with `task-update --status completed`. Enumerate the terminals still owing a
decision with `worker-list --run <run_id> --terminal-state reclaimable --json`,
and do not end the coordinator turn until it returns none.
Release a chat worker, or a worker on an older Orca, yourself with
`worker-release --dispatch <dispatch_id>`. Release is cleanup after
settlement, never cancellation. You are done when every Dispatch you started has
settled, all mail is handled, and you have told the user, per Task, the outcome,
its evidence, and any open blocker.
## Conditional references
## Safety floor
This compact guide is sufficient for the normal local loop. At an action gate
below, run `ORCA skills get orchestration --reference references/<file>.md` and
read only that document; `--references` lists the names. If the CLI rejects
`--reference`, run `ORCA skills get orchestration --full` once instead: it
returns this exact kernel and every reference, so read only the named one. If an
older CLI rejects `--full`, keep this kernel's safety floor, use that command's
`--help`, and never guess newer flags.
- Stop or abandon a worker only on positive proof that its agent stopped.
Retry only a proven failed or stopped attempt. Release only after it
settled. Silence, a timeout, or an
`unverifiable` reading proves nothing: keep waiting or inspect.
- Lifecycle authority comes from the active Dispatch, not copied IDs, old
records, titles, or transcripts.
- Liveness verdicts are `live`, `unverifiable`, or `exited`. Losing contact
with a remote host is `unverifiable`, not death.
- Folder workspaces are valid workspaces; never require Git there.
- Use one executable for the whole Run.
- A successful `send` means the message is stored; waking the recipient is
best-effort and does not prove it was read.
- Never replace Orca workers with another subagent tool when the user asked
for Orca orchestration.
| Action gate | Bundled reference |
| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Expanded DAG waves, launch model/effort, same-terminal reuse, or review ownership | `references/coordinator-loop.md` |
| You are a dispatched worker and the live preamble does not answer your question, or `check` returned an error | `references/worker-contract.md` |
| New worktree, exact workspace, SSH, WSL, or connected-server placement | `references/placement-and-remote.md` |
| Inbox recovery, follow-up messages, group addresses, or decision gates | `references/messaging-and-gates.md` |
| Failed/stopped/unknown attempts, retry, stop, abandon, retain, or uncertain release | `references/recovery-and-cleanup.md` |
| Custom argv or terminal topology that `worker-start` cannot express | `references/low-level-topology.md` |
| Any legacy label, adopted Run, compatibility receipt, or takeover | `references/legacy-contract-migration.md` |
## If you are a dispatched worker
Retired scheduler commands are not aliases for Run creation. Recovery commands
must provide their exact next action; follow it with the same selected executable.
Your prompt (the preamble) carries your Task ID, Dispatch ID, and exact
commands. It is authoritative: copy its commands and flags, never rebuild them.
1. Do only your Task, yourself: start no subagents or helper workers unless
your Task or preamble says to. For a question the coordinator must answer, use the
preamble's `ask` command, never a local prompt. After an `ask` timeout,
resume the same message ID.
2. Send heartbeats only at the preamble's cadence. Stop any heartbeat loop
before `worker_done`.
3. At natural checkpoints and right before `worker_done`, read coordinator
mail with `ORCA orchestration check --terminal <your_handle> --json` until
`count` is 0. Each `check` marks what it returns as handled (an older Orca
without `"deliveryAcknowledged": true` needs `--ack <delivery_id>`).
4. Send `worker_done` once, from your own terminal or chat: three
sentences (what changed, what you found, what remains), both IDs, and
`--outcome succeeded` or `--outcome failed`. Add `--files-modified` and
`--report-path` only with real values. If it fails or its result is
unknown, follow the recovery it prints; you are done only when it confirms.
5. Then end your turn and idle (a bare-shell worker exits, as its preamble
says). A later direct user instruction is new work;
do not reuse the settled IDs.
## References
Load a reference only when its situation applies:
`ORCA skills get orchestration --reference references/<file>.md`
(`--references` lists them). If the CLI rejects `--reference`, run
`ORCA skills get orchestration --full` once and read only the named section.
If it rejects `--full` too, use `--help` and never guess newer flags.
| Situation | Reference |
| --------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Task DAGs and dependencies, model/effort, reusing a settled worker, or who owns post-review fixes | `references/coordinator-loop.md` |
| You are a worker and the preamble does not answer your question, or `check` errored | `references/worker-contract.md` |
| Child or exact workspaces, folder workspaces, SSH, WSL, or a connected Orca server | `references/placement-and-remote.md` |
| Batch replay, follow-ups to one worker, group addresses, or decision gates | `references/messaging-and-gates.md` |
| A failed, stopped, silent, or unknown worker; retry, stop, abandon, retain, or an uncertain release | `references/recovery-and-cleanup.md` |
| Custom argv or terminal layout that `worker-start` cannot express | `references/low-level-topology.md` |
| A legacy label, adopted Run, compatibility receipt, or takeover | `references/legacy-contract-migration.md` |
@@ -1,19 +1,27 @@
# Coordinator loop
Load this reference for expanded DAG waves, per-invocation launch preferences,
same-terminal reuse, or review ownership. The compact guide remains the source
of truth for the loop order and completion boundary.
same-terminal reuse, or review ownership. The main guide remains the source of
truth for the loop order and when you are done.
## Ready waves
Create independent Tasks before the first wait. Encode only real dependencies,
then use the ready view as external memory:
Create independent Tasks before you end your first turn. Encode only real
dependencies, prefer parallel waves over chains deeper than three or four steps,
and use the ready view as external memory. Start a planned Task with `--task`,
choosing placement as the main guide describes; workers editing the same files
in parallel need separate workspaces. A retry also needs `--retry-of` (see
`references/recovery-and-cleanup.md`):
```text
ORCA orchestration task-create --spec "<dependent work>" --deps <json_array> --json
ORCA orchestration task-list --ready --brief --json
ORCA orchestration worker-start --task <task_id> --worktree current --agent codex --json
```
For a new worktree, use the placement recipe in the main guide, including
`--name`.
`--brief` collapses whitespace and caps echoed specs at 160 characters;
`spec_truncated` identifies shortened rows. Omit it when full specs are needed or
when an older CLI rejects the flag. A nested worker must respect
@@ -85,3 +85,6 @@ Never take over while the original coordinator is actively coordinating.
Do not launch a replacement editor merely because Orca updated or authority is
unclear. Keep the original worker as the only editor until a stable handoff
point, then use a fresh current Dispatch in a conflict-free placement.
Retired scheduler commands are not aliases for Run creation. Recovery commands
must provide their exact next action; follow it with the same executable.
@@ -27,8 +27,15 @@ that batch over unfiltered.
`--peek` and `--all` are read-only inspection, not progress through the
coordinator inbox. Scripts that only watch the inbox must use `--peek`.
An empty wait or timeout is a checkpoint. Continue rolling waits until every
expected Dispatch settles. Heartbeat or visible activity means alive, not done.
Inside an Orca terminal or chat, new Run mail normally wakes the coordinator
with a pointer to `check --run <run_id>`, so it may end its turn between
batches. The wake is best-effort: a Claude coordinator can stay marked working
while an agent-teams teammate is running, or is believed to be, and then gets
no wake. Use an explicit `check` or a bounded wait when the wake is
unavailable. A
caller that waits instead treats an empty wait or timeout as a checkpoint and
keeps each wait under its tool-call limit. Heartbeat or visible activity means
alive, not done.
## Addresses
@@ -38,9 +45,10 @@ Use a stable Dispatch address for attempt-specific coordinator guidance:
ORCA orchestration send --to dispatch:<dispatch_id> --subject "Follow-up" --body "<guidance>" --json
```
Do not substitute a remote terminal handle. Omit `--from` for ordinary
coordinator calls; a dispatched worker instead copies the exact `--from` and
other arguments in its preamble. `check` is the exception: it identifies
Do not substitute a remote terminal handle. `ORCA status --json` shows your
own Orca session ID as `caller.orcaSessionId` when you have one. Omit `--from`
for ordinary coordinator calls; a dispatched worker instead copies the exact
`--from` and other arguments in its preamble. `check` is the exception: it identifies
its caller with `--terminal`, never `--from`.
Group addresses include `@all`, `@idle`, `@claude`, `@codex`, `@opencode`,
@@ -14,13 +14,17 @@ sharing unsafe.
# Current workspace; setup is not rerun.
ORCA orchestration worker-start --task <task_id> --worktree current --agent codex --json
# Stacked child worktree.
# Stacked child of the current worktree.
ORCA orchestration worker-start --task <task_id> --worktree new-child --name <name> --agent codex --setup run --json
# Independent top-level worktree.
ORCA orchestration worker-start --task <task_id> --worktree new-top-level --name <name> --agent codex --setup run --json
# Independent top-level worktree. --repo is required when you are not inside that project.
ORCA orchestration worker-start --task <task_id> --worktree new-top-level --repo id:<repoId> --name <name> --agent codex --setup run --json
```
`--worktree` takes workspace placement on `worker-start` only; `run-create`
takes no placement. `new-child`, and `new-top-level` without `--repo`, need the
caller to be inside a Git worktree Orca manages.
Current and exact existing workspaces create a fresh terminal unless
`--terminal` is explicit. Folder workspaces are first-class; do not invoke Git
or require worktree lineage when the selected workspace is a folder.
@@ -67,8 +71,8 @@ ORCA orchestration worker-list --run <run_id> --include-remote --json
`worker-list` reads local fleet state only; enumerate remote workers with
`--include-remote` or every one of them reads `unverifiable`. Scope every list
with `--run <run_id>`: unscoped, it reports every Dispatch this runtime has
recorded, and the workers you are waiting on are lost in that history.
with `--run <run_id>`. Without it, the CLI uses the caller's bound Run, or all
Runs if no binding resolves; read `scope` in the receipt.
## Execution-host and mixed-version floor
@@ -3,6 +3,9 @@
Load this reference only after a failed/stopped/unknown attempt, explicit retry
decision, stop/abandon request, retention request, or uncertain release.
When evidence is missing, preserve work and authority and report the state as
unknown or `unverifiable`.
| Proven state | Safe action |
| ----------------------- | ------------------------------------------------------------------ |
| `ready` or active | Keep waiting; optionally read bounded output |
@@ -25,8 +28,9 @@ ORCA orchestration worker-read --dispatch <dispatch_id> --limit 50 --json
`worker-list` is the enumerating command and the authority on agent liveness:
each row carries `projection.liveness`, `projection.attention.categories`,
`projection.attention.requiresAction`, and a literal `projection.nextAction`
argv to run. Always scope it with `--run <run_id>`; an unscoped list reports
every Dispatch this runtime has ever recorded and buries the live ones.
argv to run. Always scope it with `--run <run_id>`. Without it, the CLI uses the
caller's bound Run, or all Runs if no binding resolves; read `scope` in the
receipt.
`worker-show`'s `observation.status` is PTY liveness only, so a `live` terminal
whose agent died at a trust prompt still reads `live` there.
@@ -51,9 +55,9 @@ verdict. Rows come newest first and past 100 the response pages, so follow
## Stall needs positive evidence
Leave the wait only on positive proof the agent stopped: `exited` liveness, the
worker's own observation of process exit, or a transcript whose final agent turn
sent no `worker_done`. Only then choose `worker-stop` or `worker-abandon`.
Choose `worker-stop` or `worker-abandon` only on positive proof the agent
stopped: `exited` liveness, the worker's own observation of process exit, or a
transcript whose final agent turn sent no `worker_done`.
`unverifiable` is always absence — `missing_status`, `stale_status`,
`restored_unconfirmed`, or a remote worker with no connection — and a null
@@ -100,12 +104,12 @@ long and, on timeout, returns the input-accepted receipt without resending.
as the exact recovery text. Older hosts may omit `data`, so treat every field as
optional.
| Code | Meaning | Recovery |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `task_not_found` | No Task with that id, or not in the bound Run (`data.taskId`, `data.runId`) | Check `task-list --json`; create the Task with `task-create` if it does not exist |
| `task_not_startable` | Task cannot start now: not `ready`, or invalid `--retry-of` (`data.status`, `data.unmetDependencies`, `data.retryOf`) | Wait for running dependencies with `check --wait`; retry or unblock failed ones; inspect `dispatch-show` if already dispatched |
| `inject_rejected` | `--inject` refused because no recognized agent runs in the target (`data.terminal`, `data.reason`) | Start a recognized agent there or pick another terminal; or dispatch without `--inject` and use `terminal send` |
| `runtime_error` | Any other failure, including a target terminal that already owns an active Dispatch | Read the message, inspect state, and do not retry unchanged |
| Code | Meaning | Recovery |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `task_not_found` | No Task with that id, or not in the bound Run (`data.taskId`, `data.runId`) | Check `task-list --json`; create the Task with `task-create` if it does not exist |
| `task_not_startable` | Task cannot start now: not `ready`, or invalid `--retry-of` (`data.status`, `data.unmetDependencies`, `data.retryOf`) | Wait for running dependencies to report; retry or unblock failed ones; inspect `dispatch-show` if already dispatched |
| `inject_rejected` | `--inject` refused because no recognized agent runs in the target (`data.terminal`, `data.reason`) | Start a recognized agent there or pick another terminal; or dispatch without `--inject` and use `terminal send` |
| `runtime_error` | Any other failure, including a target terminal that already owns an active Dispatch | Read the message, inspect state, and do not retry unchanged |
## Retry, stop, and abandon
@@ -57,7 +57,7 @@ Only if a batch lacks `"deliveryAcknowledged": true` (an older Orca), ack its
`--retry-request <id>` it printed; after lost context, read handled mail with
`ORCA orchestration inbox --terminal dispatch:<dispatch_id> --limit 50 --full --json`.
Do not use `run-use` to check your Dispatch's mail or bind the Run you work for.
Do not use `run-use` to check your Dispatch's mail or bind the Run you work for or any ancestor Run.
You may resume a separate Run when your coordinator directs a handoff, but you
cannot use `--takeover-legacy`. Plain `check` returns your Dispatch's mail
unless you are coordinating a Run; report to your coordinator with `send`.
@@ -71,8 +71,9 @@ party's terminal (a coordinator or another worker); run it from your own termina
## Helper workers
When the preamble has a SUB-DISPATCH section, start helpers on your own
Dispatch's Run. Do not `run-create` or `run-use` for them.
Follow the preamble's SUB-DISPATCH section. For helpers on your own
Dispatch's Run, use the commands below, without `run-create` or `run-use`; a
remote preamble may instead tell you to create your own Run.
```text
ORCA orchestration worker-start --from <worker_handle> --spec "<sub-task>" --worktree current --agent <agent> --json
@@ -80,8 +81,9 @@ ORCA orchestration reply --from <worker_handle> --id <message_id> --body "<answe
```
Their questions, escalations, and `worker_done` arrive in your own `check`, next
to your coordinator's mail. Answer their questions with `reply`, and wait for
every helper's `worker_done` before sending yours. After you settle, a helper
to your coordinator's mail. Answer their questions with `reply`, and wait until
every helper has settled (`worker_done`, a failed start, stop, or abandon)
before sending yours; name any that failed. After you settle, a helper
still running reports to your coordinator's Run.
## Escalation
@@ -105,7 +107,7 @@ paths. Do not send documentation placeholders as metadata.
ORCA orchestration send --from <worker_handle> --type worker_done --subject "<short status>" --body "<three sentences: work, findings, remaining>" --task-id <task_id> --dispatch-id <dispatch_id> --outcome succeeded
```
After `worker_done`, end the dispatched turn and idle. Do not poll, close your
own terminal, or begin unrelated work. A later direct user instruction is new
After `worker_done`, end the dispatched turn and idle (a bare-shell worker
exits, as its preamble says). Do not poll or begin unrelated work. A later direct user instruction is new
user-owned work and must not reuse settled lifecycle IDs; a supervised follow-up
arrives with a fresh preamble and Task block.
+216 -209
View File
@@ -2348,217 +2348,195 @@ const ORCHESTRATION_MARKDOWN = [
"",
"# Orca orchestration",
"",
"Orchestration is Orca's structured coordination layer. It records who owns work,",
"which attempt is authoritative, and when supervised work has settled.",
"You (the coordinator) start worker agents through Orca and end your turn; Orca",
"normally wakes you when a worker reports back. Terms:",
"",
"## Outcome",
"- **Run**: your inbox for one goal. Workers report to it.",
"- **Task**: one piece of work. **Dispatch**: one attempt at a Task by one worker.",
"- **Settled**: Orca recorded an outcome for the attempt, usually from the",
" worker's `worker_done` (succeeded or failed); a stop, abandon, or failed start",
" also settles it.",
"",
"**Result:** every in-scope Task has one explicit outcome and every settled worker",
"terminal has a next owner or cleanup decision. **Next consumer:** the user who",
"requested supervision. **Done:** all expected Dispatches have settled, every",
"delivered message was processed, each settled worker was",
"reused, explicitly retained, or released, and the turn ends only when the report",
"to that user names, per Task, its outcome, the evidence behind it, and any",
"unresolved blocker.",
"## Your role",
"",
"**Safe failure:** preserve work and authority and report the state as unknown or",
"`unverifiable`. Only positive proof of exit authorizes stop, abandon, or retry,",
"and only an accepted settlement authorizes release. Every other observation,",
"absence included, is a checkpoint.",
"| Situation | Role | What to do |",
"| -------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------- |",
"| The user asks for another agent's result back (\"have Codex review this and report\"), supervision, a task DAG, or ask/reply | Coordinator | Follow the main recipe below |",
"| Your prompt has a live preamble with Task and Dispatch IDs | Dispatched worker | Follow the preamble and \"If you are a dispatched worker\" below |",
"| The user asks to hand work off or start another agent or worktree, and wants no result back | Handoff owner | Use the `orca-cli` skill; create no Run, Task, or Dispatch |",
"| A message carries a legacy authority label | Compatibility | Load `references/legacy-contract-migration.md` before changing any state |",
"| None of the above | Ordinary agent | Send no lifecycle messages; use `orca-cli` for terminal and worktree work |",
"",
"## Classify the role",
"Choosing a model or effort does not make a handoff supervised: `orca-cli`'s",
"`worktree create --agent` and `agent launch` take `--model` and `--effort` too.",
"",
"| Current context | Role | Route |",
"| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------ |",
"| The user explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use a decision gate, or manage ask/reply | Coordinator | Use the supervised loop below |",
"| The current prompt contains a live injected preamble with Task and Dispatch IDs | Dispatched worker | Follow the preamble and the worker obligations below |",
"| The user asks to hand off ownership or start another agent/worktree without supervision | Handoff owner | Use `orca-cli`; create no Run, Task, or Dispatch and do not monitor completion |",
"| A message carries a legacy authority label | Compatibility operator | Load the legacy contract reference before any lifecycle mutation |",
"| No live preamble and no explicit supervision | Ordinary terminal agent | Do not emit lifecycle messages; use `orca-cli` for terminal/worktree work |",
"## Main recipe",
"",
"Model or effort selection does not make a handoff supervised: `orca-cli`'s",
"`worktree create --agent` and `agent launch` take `--model` and `--effort`, and",
"open a chat or a terminal per the user's Chat UI setting, as `worker-start` does.",
"Never substitute a non-Orca subagent tool when Orca orchestration provenance was",
"requested.",
"",
"## Authority and safety floor",
"",
"- A Run is a durable namespace and coordinator inbox; it does not schedule or",
" place workers. A Task is work. A Dispatch is one authoritative Task attempt.",
"- Lifecycle authority comes from the active Dispatch, not a terminal title,",
" copied ID, old database row, provider transcript, or visible pane.",
"- Workers use the exact executable, handle, Task ID, and Dispatch ID in the live",
" preamble, plus any other flag it carries. Never reconstruct, translate, or",
" broaden those arguments.",
"- After remote start, address the worker by Dispatch ID. The execution host owns",
" process, filesystem, transcript, stop, and cleanup facts. Preserve the verdicts",
" `live` / `unverifiable` / `exited`; contact loss is not process death.",
"- Liveness is layered: `worker-list`'s `projection.liveness` is the fleet verdict",
" for the agent; `worker-show`'s `observation.status` is PTY liveness only. A live",
" terminal can still hold a dead or stuck agent.",
"- Folder workspaces are valid; never require Git or assume a worktree.",
"- Clients and remote servers update independently. Treat unknown optional fields",
" as absent. A new stream operation requires advertised capability because old",
" decoders may silently drop unknown opcodes. Never fall back to local execution",
" when remote authority or capability is unproven.",
"- Use the executable you used to run `skills get` for the entire run. In the",
" examples below, replace `ORCA` with it; do not create a shell variable or run",
" `ORCA` literally. If it fails, report that exact error instead of switching.",
"- `ORCA status --json` shows your Orca session ID as `caller.orcaSessionId` when you have one.",
"- A successful `orchestration send` proves durable enqueue; its wake or nudge is",
" best-effort attention only and does not prove the recipient read or accepted it.",
"",
"## Worker obligations",
"",
"The injected preamble is authoritative. A dispatched worker must:",
"",
"1. Do only the current Task and use the preamble's `ask` command for a blocking",
" coordinator question. Never open a local question TUI the coordinator cannot",
" answer. Resume the same message ID after an ask timeout.",
"2. Send heartbeats only at the cadence in the preamble. A heartbeat proves",
" liveness, not completion. If a background loop sends them, restart it if it",
" expires mid-task, and stop it before `worker_done`.",
"3. Read coordinator follow-ups at each natural checkpoint — before starting a",
" new file, after a test run — and once more immediately before `worker_done`:",
" `ORCA orchestration check --terminal <your_handle> --json`.",
" Each `check` marks the batch it returns handled; repeat until `count` is 0.",
" Only if a batch lacks `\"deliveryAcknowledged\": true` (an older Orca), ack its",
" `deliveryId` with `--ack`. If a `check` reply was lost, rerun it with the",
" `--retry-request <id>` it printed; after lost context, read handled mail with",
" `ORCA orchestration inbox --terminal dispatch:<dispatch_id> --limit 50 --full --json`.",
"4. Send `worker_done` exactly once, from the dispatched terminal, with a",
" three-sentence executive summary, both lifecycle IDs, and explicit",
" `--outcome succeeded` or `--outcome failed`. Never encode failure only in prose.",
"5. Append `--files-modified` and `--report-path` only with real values when",
" applicable. After `worker_done`, end the dispatched turn and idle; do not poll",
" or start new work.",
"",
"A direct user instruction after completion starts new user-owned work and takes",
"precedence over the idle rule. Do not reuse the settled lifecycle IDs.",
"",
"## Canonical supervised loop",
"",
"Confirm the runtime and start the full independent wave before waiting.",
"`worker-start --spec` creates the Task and its attempt in one call; with no Run",
"bound, it also creates one bound to you (an older Orca refuses instead; then",
"`run-create` first). Its receipt's `run` names the Run it created or joined; if",
"that is an earlier goal's Run, `run-create` first:",
"`ORCA` below stands for the executable you used to run `skills get`. Type that",
"executable in its place; do not create a shell variable or run `ORCA`",
"literally. If it fails, report its exact error; never switch to another one.",
"",
"```text",
"ORCA status --json",
"ORCA orchestration worker-start --spec \"<worker A task>\" --worktree current --agent codex --json",
"ORCA orchestration worker-start --spec \"<worker B task>\" --worktree current --agent claude --json",
"ORCA orchestration check --wait --types \"worker_done,escalation,question\" --timeout-ms 900000 --json",
"ORCA orchestration worker-start --spec \"<task>\" --worktree current --agent claude --json",
"```",
"",
"After a restart, resume your own Run with `run-use --id <run_id>`. A worker",
"cannot bind the Run it works for or an ancestor, and cannot use",
"`--takeover-legacy`; an already-bound no-op remains allowed. When its",
"coordinator directs a handoff, a replacement worker may resume a separate Run",
"with plain `run-use`.",
"- With no Run bound to you, `worker-start` creates one and binds it; its",
" receipt's `run` names the Run it created or joined. If that is an earlier",
" goal's Run, or the Orca is older and refuses with `run_required`, run",
" `ORCA orchestration run-create --objective \"<goal>\" --json` first.",
"- `--worktree current` runs the worker in your workspace; an exact workspace",
" selector runs it in another existing one. Placement goes on `worker-start`;",
" `run-create` takes none.",
"- Create a new workspace only when the user asks for one, or sharing a checkout",
" would conflict (for example, the change belongs to a project you are not",
" in). Pass the project with `--repo`; `ORCA repo list --json` gives its id.",
" Without `--repo`, Orca uses the repository of the Orca-managed Git worktree",
" you are in, and fails if there is none:",
" `ORCA orchestration worker-start --spec \"<task>\" --worktree new-top-level --repo id:<repoId> --name <short-name> --agent claude --json`",
"- `--agent` takes a configured agent id such as `claude` or `codex`; use the",
" one the user asked for. Add `--model` only when the user named one.",
"- Start every independent worker before you stop. One `worker-start --spec`",
" call creates the Task and its Dispatch.",
"- If `worker-start` exits non-zero, do not run it again. Read `failedStage`",
" and `residualResources` in its output, then load",
" `references/recovery-and-cleanup.md`.",
"",
"If `worker-start` exits non-zero, do not relaunch. Read the receipt's",
"`failedStage` and `residualResources`, then load",
"`references/recovery-and-cleanup.md`.",
"Then tell the user what you started and **end your turn**, unless you need to",
"wait inside this turn (below).",
"",
"Use `run-create --objective \"<objective>\"`, then `task-create` plus",
"`worker-start --task <task_id>`, for planned fan-out with dependencies or a",
"retry of a known Task. Use dependencies only for real ordering",
"and prefer parallel waves over chains deeper than three or four steps; nested",
"workers obey the depth limit, and a new Run does not reset the caller's depth.",
"A dispatched worker starts its own helpers with `worker-start --spec` on the Run",
"it works for, without `run-create`; the helpers report to that worker.",
"- Do not poll: no sleep loops, watch scripts, scheduled wakeups, or repeated",
" `check --peek` or `worker-list` calls. A plain `check` takes the mail it",
" returns, so a script that runs one hides it from you; scripts that only watch",
" must use `--peek`.",
"- To steer a running worker, use",
" `ORCA orchestration send --to dispatch:<dispatch_id> --subject \"<topic>\" --body \"<guidance>\"`;",
" never type into its terminal.",
"- Let `worker-start` create a worker's workspace; never make its checkout",
" yourself.",
"",
"A consuming `check` names its caller with `--terminal <handle>`, never `--from`;",
"omit it inside the coordinator's own Orca terminal. It returns the bound Run's",
"oldest FIFO Delivery and marks it handled; `--ack` is still accepted but not",
"needed. Process every message: reply to questions, validate each `worker_done`",
"against the expected active Dispatch, and decide each settled terminal's next",
"owner before the next `check`:",
"## When Orca wakes you",
"",
"When a worker reports, Orca sends you a new message: \"You have N orchestration",
"messages. Run `orca orchestration check --run <run_id>`.\" In a terminal it is",
"typed in for you, even mid-turn (it queues like any typed input); in a chat it",
"arrives as a user message. Run the command it names:",
"",
"```text",
"ORCA orchestration reply --id <message_id> --body \"<answer>\" --json",
"ORCA orchestration worker-release --dispatch <dispatch_id> --json",
"ORCA orchestration check --wait --types \"worker_done,escalation,question\" --timeout-ms 900000 --json",
"ORCA orchestration check --run <run_id> --json",
"```",
"",
"If a `check` reply was lost, rerun it with the `--retry-request <id>` it printed.",
"If you lost context, read the handled mail with",
"`ORCA orchestration inbox --terminal run:<run_id> --limit 50 --full --json`.",
"Scripts that only watch the inbox must use `--peek`.",
"- Each `check` marks the mail it returns as handled; run it again until",
" `count` is 0. Only an older Orca, whose reply lacks",
" `\"deliveryAcknowledged\": true`, needs `--ack <delivery_id>` on the next check.",
"- Answer each `question` with",
" `ORCA orchestration reply --id <message_id> --body \"<answer>\" --json`.",
"- Check each `worker_done` against the Dispatch you expect.",
"- If a `check` reply was lost, rerun it with the `--retry-request <id>` it",
" printed. If you lost context, read handled mail with",
" `ORCA orchestration inbox --terminal run:<run_id> --limit 50 --full --json`.",
"- Tell the user the result, or end your turn again while workers are still",
" running. A quiet inbox proves neither progress nor failure.",
"",
"Keep waiting until every expected Dispatch settles. A timeout or empty result is",
"a checkpoint, not a failure. Do not stop, retry, release, or launch a duplicate",
"editor without the positive proof `## Outcome` requires.",
"**Waiting inside one turn.** Only when the user needs the result before your",
"turn ends, or you run outside an Orca terminal or chat, block instead. Keep the",
"timeout under your tool-call limit (540000 ms suits a 10-minute limit).",
"Outside your own Orca terminal or chat, add `--terminal <handle>`:",
"",
"After three consecutive empty waits, stop waiting blindly and enumerate with",
"`ORCA orchestration worker-list --include-remote --json` (defaults to the bound",
"Run; `--run <run_id>` overrides; the receipt's `scope` names which), acting on",
"each row's `projection.attention` categories, `projection.attention.requiresAction`, and literal `projection.nextAction` argv.",
"Rows come newest first and page at 100: while `page.hasMore`, follow `page.nextCursor` with `--cursor <value>`.",
"A `none` `nextAction` has no argv to run: read `liveness.reason` and keep waiting",
"with `check --wait`. Absence never earns an argv; settlement and pending work still do.",
"Leave the wait only on positive proof the agent stopped: `exited` liveness, the",
"worker's own observation of process exit, or a transcript whose final agent turn",
"sent no `worker_done`. Then load `references/recovery-and-cleanup.md` and choose",
"`worker-stop` or `worker-abandon` explicitly. `unverifiable` is absence,",
"including when `worker-show` reports `agentWait` null. Absence never authorizes",
"stop, abandon, retry, or release; keep waiting or inspect.",
"```text",
"ORCA orchestration check --run <run_id> --wait --types \"worker_done,escalation,question\" --timeout-ms 540000 --json",
"```",
"",
"`worker-start` is the normal path, composing placement, terminal readiness,",
"prompt injection, and supervised resource ownership. `dispatch --inject` leaves",
"an operator-created process unsupervised and is only for an expressiveness gap.",
"A timeout is a checkpoint, not a failure: wait again, or end the turn. After",
"three empty waits in a row, inspect the workers with",
"`references/recovery-and-cleanup.md`. After a restart, resume your Run with",
"`ORCA orchestration run-use --id <run_id> --json`.",
"",
"## Task-spec contract",
"## Task spec",
"",
"Every Task spec must be self-contained and name:",
"Make each Task spec self-contained:",
"",
"- **Target:** the files, component, or environment in scope.",
"- **Change:** the concrete result to produce.",
"- **Constraints:** invariants, compatibility rules, and do-not-touch boundaries.",
"- **Ownership:** what this worker may edit and any coordination boundary.",
"- **Observable acceptance:** the test, output, or evidence that proves completion.",
"- **Constraints:** rules to keep, and what not to touch.",
"- **Ownership:** what this worker may edit.",
"- **Acceptance:** the test, output, or evidence that proves it is done.",
"",
"## Completion accounting",
"A review-only worker's `worker_done` lets you summarize its findings, not edit",
"files yourself. Send fixes to a worker unless the user gave them to you.",
"",
"After an accepted success or failure report, immediately do exactly one:",
"## Completion",
"",
"1. Reuse the same proven agent terminal for an immediate follow-up Dispatch.",
"2. Record user-requested retention with `worker-retain`.",
"3. Run `worker-release`.",
"A valid `worker_done` settles its Task; do not follow it with `task-update`.",
"Orca releases a finished terminal worker about 2 minutes after its",
"`worker_done` (`autoReleaseAt` in `worker-list`). Before then, if you want it:",
"",
"Release is post-settlement cleanup, not cancellation. Only an accepted",
"settlement authorizes it; no other observation does. If release is uncertain,",
"follow its exact recovery receipt and never substitute `terminal close`.",
"- give it a follow-up (`references/coordinator-loop.md`), or",
"- keep it with `ORCA orchestration worker-retain --dispatch <dispatch_id> --json`.",
"",
"A valid `worker_done` settles the Task and Dispatch automatically; do not follow",
"it with `task-update --status completed`. Enumerate the terminals still owing a",
"decision with `worker-list --run <run_id> --terminal-state reclaimable --json`,",
"and do not end the coordinator turn until it returns none.",
"Release a chat worker, or a worker on an older Orca, yourself with",
"`worker-release --dispatch <dispatch_id>`. Release is cleanup after",
"settlement, never cancellation. You are done when every Dispatch you started has",
"settled, all mail is handled, and you have told the user, per Task, the outcome,",
"its evidence, and any open blocker.",
"",
"## Conditional references",
"## Safety floor",
"",
"This compact guide is sufficient for the normal local loop. At an action gate",
"below, run `ORCA skills get orchestration --reference references/<file>.md` and",
"read only that document; `--references` lists the names. If the CLI rejects",
"`--reference`, run `ORCA skills get orchestration --full` once instead: it",
"returns this exact kernel and every reference, so read only the named one. If an",
"older CLI rejects `--full`, keep this kernel's safety floor, use that command's",
"`--help`, and never guess newer flags.",
"- Stop or abandon a worker only on positive proof that its agent stopped.",
" Retry only a proven failed or stopped attempt. Release only after it",
" settled. Silence, a timeout, or an",
" `unverifiable` reading proves nothing: keep waiting or inspect.",
"- Lifecycle authority comes from the active Dispatch, not copied IDs, old",
" records, titles, or transcripts.",
"- Liveness verdicts are `live`, `unverifiable`, or `exited`. Losing contact",
" with a remote host is `unverifiable`, not death.",
"- Folder workspaces are valid workspaces; never require Git there.",
"- Use one executable for the whole Run.",
"- A successful `send` means the message is stored; waking the recipient is",
" best-effort and does not prove it was read.",
"- Never replace Orca workers with another subagent tool when the user asked",
" for Orca orchestration.",
"",
"| Action gate | Bundled reference |",
"| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |",
"| Expanded DAG waves, launch model/effort, same-terminal reuse, or review ownership | `references/coordinator-loop.md` |",
"| You are a dispatched worker and the live preamble does not answer your question, or `check` returned an error | `references/worker-contract.md` |",
"| New worktree, exact workspace, SSH, WSL, or connected-server placement | `references/placement-and-remote.md` |",
"| Inbox recovery, follow-up messages, group addresses, or decision gates | `references/messaging-and-gates.md` |",
"| Failed/stopped/unknown attempts, retry, stop, abandon, retain, or uncertain release | `references/recovery-and-cleanup.md` |",
"| Custom argv or terminal topology that `worker-start` cannot express | `references/low-level-topology.md` |",
"| Any legacy label, adopted Run, compatibility receipt, or takeover | `references/legacy-contract-migration.md` |",
"## If you are a dispatched worker",
"",
"Retired scheduler commands are not aliases for Run creation. Recovery commands",
"must provide their exact next action; follow it with the same selected executable.",
"Your prompt (the preamble) carries your Task ID, Dispatch ID, and exact",
"commands. It is authoritative: copy its commands and flags, never rebuild them.",
"",
"1. Do only your Task, yourself: start no subagents or helper workers unless",
" your Task or preamble says to. For a question the coordinator must answer, use the",
" preamble's `ask` command, never a local prompt. After an `ask` timeout,",
" resume the same message ID.",
"2. Send heartbeats only at the preamble's cadence. Stop any heartbeat loop",
" before `worker_done`.",
"3. At natural checkpoints and right before `worker_done`, read coordinator",
" mail with `ORCA orchestration check --terminal <your_handle> --json` until",
" `count` is 0. Each `check` marks what it returns as handled (an older Orca",
" without `\"deliveryAcknowledged\": true` needs `--ack <delivery_id>`).",
"4. Send `worker_done` once, from your own terminal or chat: three",
" sentences (what changed, what you found, what remains), both IDs, and",
" `--outcome succeeded` or `--outcome failed`. Add `--files-modified` and",
" `--report-path` only with real values. If it fails or its result is",
" unknown, follow the recovery it prints; you are done only when it confirms.",
"5. Then end your turn and idle (a bare-shell worker exits, as its preamble",
" says). A later direct user instruction is new work;",
" do not reuse the settled IDs.",
"",
"## References",
"",
"Load a reference only when its situation applies:",
"`ORCA skills get orchestration --reference references/<file>.md`",
"(`--references` lists them). If the CLI rejects `--reference`, run",
"`ORCA skills get orchestration --full` once and read only the named section.",
"If it rejects `--full` too, use `--help` and never guess newer flags.",
"",
"| Situation | Reference |",
"| --------------------------------------------------------------------------------------------------- | ----------------------------------------- |",
"| Task DAGs and dependencies, model/effort, reusing a settled worker, or who owns post-review fixes | `references/coordinator-loop.md` |",
"| You are a worker and the preamble does not answer your question, or `check` errored | `references/worker-contract.md` |",
"| Child or exact workspaces, folder workspaces, SSH, WSL, or a connected Orca server | `references/placement-and-remote.md` |",
"| Batch replay, follow-ups to one worker, group addresses, or decision gates | `references/messaging-and-gates.md` |",
"| A failed, stopped, silent, or unknown worker; retry, stop, abandon, retain, or an uncertain release | `references/recovery-and-cleanup.md` |",
"| Custom argv or terminal layout that `worker-start` cannot express | `references/low-level-topology.md` |",
"| A legacy label, adopted Run, compatibility receipt, or takeover | `references/legacy-contract-migration.md` |",
"",
].join('\n')
@@ -2567,19 +2545,27 @@ const ORCHESTRATION_COORDINATOR_LOOP_REFERENCE_MARKDOWN = [
"# Coordinator loop",
"",
"Load this reference for expanded DAG waves, per-invocation launch preferences,",
"same-terminal reuse, or review ownership. The compact guide remains the source",
"of truth for the loop order and completion boundary.",
"same-terminal reuse, or review ownership. The main guide remains the source of",
"truth for the loop order and when you are done.",
"",
"## Ready waves",
"",
"Create independent Tasks before the first wait. Encode only real dependencies,",
"then use the ready view as external memory:",
"Create independent Tasks before you end your first turn. Encode only real",
"dependencies, prefer parallel waves over chains deeper than three or four steps,",
"and use the ready view as external memory. Start a planned Task with `--task`,",
"choosing placement as the main guide describes; workers editing the same files",
"in parallel need separate workspaces. A retry also needs `--retry-of` (see",
"`references/recovery-and-cleanup.md`):",
"",
"```text",
"ORCA orchestration task-create --spec \"<dependent work>\" --deps <json_array> --json",
"ORCA orchestration task-list --ready --brief --json",
"ORCA orchestration worker-start --task <task_id> --worktree current --agent codex --json",
"```",
"",
"For a new worktree, use the placement recipe in the main guide, including",
"`--name`.",
"",
"`--brief` collapses whitespace and caps echoed specs at 160 characters;",
"`spec_truncated` identifies shortened rows. Omit it when full specs are needed or",
"when an older CLI rejects the flag. A nested worker must respect",
@@ -2724,6 +2710,9 @@ const ORCHESTRATION_LEGACY_CONTRACT_MIGRATION_REFERENCE_MARKDOWN = [
"unclear. Keep the original worker as the only editor until a stable handoff",
"point, then use a fresh current Dispatch in a conflict-free placement.",
"",
"Retired scheduler commands are not aliases for Run creation. Recovery commands",
"must provide their exact next action; follow it with the same executable.",
"",
].join('\n')
// oxfmt-ignore
@@ -2788,8 +2777,15 @@ const ORCHESTRATION_MESSAGING_AND_GATES_REFERENCE_MARKDOWN = [
"`--peek` and `--all` are read-only inspection, not progress through the",
"coordinator inbox. Scripts that only watch the inbox must use `--peek`.",
"",
"An empty wait or timeout is a checkpoint. Continue rolling waits until every",
"expected Dispatch settles. Heartbeat or visible activity means alive, not done.",
"Inside an Orca terminal or chat, new Run mail normally wakes the coordinator",
"with a pointer to `check --run <run_id>`, so it may end its turn between",
"batches. The wake is best-effort: a Claude coordinator can stay marked working",
"while an agent-teams teammate is running, or is believed to be, and then gets",
"no wake. Use an explicit `check` or a bounded wait when the wake is",
"unavailable. A",
"caller that waits instead treats an empty wait or timeout as a checkpoint and",
"keeps each wait under its tool-call limit. Heartbeat or visible activity means",
"alive, not done.",
"",
"## Addresses",
"",
@@ -2799,9 +2795,10 @@ const ORCHESTRATION_MESSAGING_AND_GATES_REFERENCE_MARKDOWN = [
"ORCA orchestration send --to dispatch:<dispatch_id> --subject \"Follow-up\" --body \"<guidance>\" --json",
"```",
"",
"Do not substitute a remote terminal handle. Omit `--from` for ordinary",
"coordinator calls; a dispatched worker instead copies the exact `--from` and",
"other arguments in its preamble. `check` is the exception: it identifies",
"Do not substitute a remote terminal handle. `ORCA status --json` shows your",
"own Orca session ID as `caller.orcaSessionId` when you have one. Omit `--from`",
"for ordinary coordinator calls; a dispatched worker instead copies the exact",
"`--from` and other arguments in its preamble. `check` is the exception: it identifies",
"its caller with `--terminal`, never `--from`.",
"",
"Group addresses include `@all`, `@idle`, `@claude`, `@codex`, `@opencode`,",
@@ -2857,13 +2854,17 @@ const ORCHESTRATION_PLACEMENT_AND_REMOTE_REFERENCE_MARKDOWN = [
"# Current workspace; setup is not rerun.",
"ORCA orchestration worker-start --task <task_id> --worktree current --agent codex --json",
"",
"# Stacked child worktree.",
"# Stacked child of the current worktree.",
"ORCA orchestration worker-start --task <task_id> --worktree new-child --name <name> --agent codex --setup run --json",
"",
"# Independent top-level worktree.",
"ORCA orchestration worker-start --task <task_id> --worktree new-top-level --name <name> --agent codex --setup run --json",
"# Independent top-level worktree. --repo is required when you are not inside that project.",
"ORCA orchestration worker-start --task <task_id> --worktree new-top-level --repo id:<repoId> --name <name> --agent codex --setup run --json",
"```",
"",
"`--worktree` takes workspace placement on `worker-start` only; `run-create`",
"takes no placement. `new-child`, and `new-top-level` without `--repo`, need the",
"caller to be inside a Git worktree Orca manages.",
"",
"Current and exact existing workspaces create a fresh terminal unless",
"`--terminal` is explicit. Folder workspaces are first-class; do not invoke Git",
"or require worktree lineage when the selected workspace is a folder.",
@@ -2910,8 +2911,8 @@ const ORCHESTRATION_PLACEMENT_AND_REMOTE_REFERENCE_MARKDOWN = [
"",
"`worker-list` reads local fleet state only; enumerate remote workers with",
"`--include-remote` or every one of them reads `unverifiable`. Scope every list",
"with `--run <run_id>`: unscoped, it reports every Dispatch this runtime has",
"recorded, and the workers you are waiting on are lost in that history.",
"with `--run <run_id>`. Without it, the CLI uses the caller's bound Run, or all",
"Runs if no binding resolves; read `scope` in the receipt.",
"",
"## Execution-host and mixed-version floor",
"",
@@ -2941,6 +2942,9 @@ const ORCHESTRATION_RECOVERY_AND_CLEANUP_REFERENCE_MARKDOWN = [
"Load this reference only after a failed/stopped/unknown attempt, explicit retry",
"decision, stop/abandon request, retention request, or uncertain release.",
"",
"When evidence is missing, preserve work and authority and report the state as",
"unknown or `unverifiable`.",
"",
"| Proven state | Safe action |",
"| ----------------------- | ------------------------------------------------------------------ |",
"| `ready` or active | Keep waiting; optionally read bounded output |",
@@ -2963,8 +2967,9 @@ const ORCHESTRATION_RECOVERY_AND_CLEANUP_REFERENCE_MARKDOWN = [
"`worker-list` is the enumerating command and the authority on agent liveness:",
"each row carries `projection.liveness`, `projection.attention.categories`,",
"`projection.attention.requiresAction`, and a literal `projection.nextAction`",
"argv to run. Always scope it with `--run <run_id>`; an unscoped list reports",
"every Dispatch this runtime has ever recorded and buries the live ones.",
"argv to run. Always scope it with `--run <run_id>`. Without it, the CLI uses the",
"caller's bound Run, or all Runs if no binding resolves; read `scope` in the",
"receipt.",
"`worker-show`'s `observation.status` is PTY liveness only, so a `live` terminal",
"whose agent died at a trust prompt still reads `live` there.",
"",
@@ -2989,9 +2994,9 @@ const ORCHESTRATION_RECOVERY_AND_CLEANUP_REFERENCE_MARKDOWN = [
"",
"## Stall needs positive evidence",
"",
"Leave the wait only on positive proof the agent stopped: `exited` liveness, the",
"worker's own observation of process exit, or a transcript whose final agent turn",
"sent no `worker_done`. Only then choose `worker-stop` or `worker-abandon`.",
"Choose `worker-stop` or `worker-abandon` only on positive proof the agent",
"stopped: `exited` liveness, the worker's own observation of process exit, or a",
"transcript whose final agent turn sent no `worker_done`.",
"",
"`unverifiable` is always absence — `missing_status`, `stale_status`,",
"`restored_unconfirmed`, or a remote worker with no connection — and a null",
@@ -3038,12 +3043,12 @@ const ORCHESTRATION_RECOVERY_AND_CLEANUP_REFERENCE_MARKDOWN = [
"as the exact recovery text. Older hosts may omit `data`, so treat every field as",
"optional.",
"",
"| Code | Meaning | Recovery |",
"| -------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |",
"| `task_not_found` | No Task with that id, or not in the bound Run (`data.taskId`, `data.runId`) | Check `task-list --json`; create the Task with `task-create` if it does not exist |",
"| `task_not_startable` | Task cannot start now: not `ready`, or invalid `--retry-of` (`data.status`, `data.unmetDependencies`, `data.retryOf`) | Wait for running dependencies with `check --wait`; retry or unblock failed ones; inspect `dispatch-show` if already dispatched |",
"| `inject_rejected` | `--inject` refused because no recognized agent runs in the target (`data.terminal`, `data.reason`) | Start a recognized agent there or pick another terminal; or dispatch without `--inject` and use `terminal send` |",
"| `runtime_error` | Any other failure, including a target terminal that already owns an active Dispatch | Read the message, inspect state, and do not retry unchanged |",
"| Code | Meaning | Recovery |",
"| -------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |",
"| `task_not_found` | No Task with that id, or not in the bound Run (`data.taskId`, `data.runId`) | Check `task-list --json`; create the Task with `task-create` if it does not exist |",
"| `task_not_startable` | Task cannot start now: not `ready`, or invalid `--retry-of` (`data.status`, `data.unmetDependencies`, `data.retryOf`) | Wait for running dependencies to report; retry or unblock failed ones; inspect `dispatch-show` if already dispatched |",
"| `inject_rejected` | `--inject` refused because no recognized agent runs in the target (`data.terminal`, `data.reason`) | Start a recognized agent there or pick another terminal; or dispatch without `--inject` and use `terminal send` |",
"| `runtime_error` | Any other failure, including a target terminal that already owns an active Dispatch | Read the message, inspect state, and do not retry unchanged |",
"",
"## Retry, stop, and abandon",
"",
@@ -3186,7 +3191,7 @@ const ORCHESTRATION_WORKER_CONTRACT_REFERENCE_MARKDOWN = [
"`--retry-request <id>` it printed; after lost context, read handled mail with",
"`ORCA orchestration inbox --terminal dispatch:<dispatch_id> --limit 50 --full --json`.",
"",
"Do not use `run-use` to check your Dispatch's mail or bind the Run you work for.",
"Do not use `run-use` to check your Dispatch's mail or bind the Run you work for or any ancestor Run.",
"You may resume a separate Run when your coordinator directs a handoff, but you",
"cannot use `--takeover-legacy`. Plain `check` returns your Dispatch's mail",
"unless you are coordinating a Run; report to your coordinator with `send`.",
@@ -3200,8 +3205,9 @@ const ORCHESTRATION_WORKER_CONTRACT_REFERENCE_MARKDOWN = [
"",
"## Helper workers",
"",
"When the preamble has a SUB-DISPATCH section, start helpers on your own",
"Dispatch's Run. Do not `run-create` or `run-use` for them.",
"Follow the preamble's SUB-DISPATCH section. For helpers on your own",
"Dispatch's Run, use the commands below, without `run-create` or `run-use`; a",
"remote preamble may instead tell you to create your own Run.",
"",
"```text",
"ORCA orchestration worker-start --from <worker_handle> --spec \"<sub-task>\" --worktree current --agent <agent> --json",
@@ -3209,8 +3215,9 @@ const ORCHESTRATION_WORKER_CONTRACT_REFERENCE_MARKDOWN = [
"```",
"",
"Their questions, escalations, and `worker_done` arrive in your own `check`, next",
"to your coordinator's mail. Answer their questions with `reply`, and wait for",
"every helper's `worker_done` before sending yours. After you settle, a helper",
"to your coordinator's mail. Answer their questions with `reply`, and wait until",
"every helper has settled (`worker_done`, a failed start, stop, or abandon)",
"before sending yours; name any that failed. After you settle, a helper",
"still running reports to your coordinator's Run.",
"",
"## Escalation",
@@ -3234,8 +3241,8 @@ const ORCHESTRATION_WORKER_CONTRACT_REFERENCE_MARKDOWN = [
"ORCA orchestration send --from <worker_handle> --type worker_done --subject \"<short status>\" --body \"<three sentences: work, findings, remaining>\" --task-id <task_id> --dispatch-id <dispatch_id> --outcome succeeded",
"```",
"",
"After `worker_done`, end the dispatched turn and idle. Do not poll, close your",
"own terminal, or begin unrelated work. A later direct user instruction is new",
"After `worker_done`, end the dispatched turn and idle (a bare-shell worker",
"exits, as its preamble says). Do not poll or begin unrelated work. A later direct user instruction is new",
"user-owned work and must not reuse settled lifecycle IDs; a supervised follow-up",
"arrives with a fresh preamble and Task block.",
"",
@@ -127,7 +127,7 @@ it.skipIf(skip)(
timeoutMs: 15_000
})
expect(skill.code, skill.stderr).toBe(0)
expect(skill.stdout).toContain('Worker obligations')
expect(skill.stdout).toContain('If you are a dispatched worker')
const version = await runProcess({
program: childEnv.ORCA_CLI_COMMAND!,
args: ['--version'],
@@ -22,7 +22,8 @@ Don't post to Slack, GitHub, or other channels during the run; report through th
# only when you produced a durable report. Always pass real values; do not
# send the example placeholders literally.
#
# Send worker_done exactly once. Use --outcome succeeded when the
# Send worker_done once. If it fails or its result is unknown, follow the
# recovery it prints; you are done only when it confirms. Use --outcome succeeded when the
# requested work is done, or replace it with --outcome failed when it is not.
# Never encode failure only in prose and never silently exit.
# Include BOTH taskId and dispatchId in the payload so a late completion
@@ -112,7 +113,8 @@ Don't post to Slack, GitHub, or other channels during the run; report through th
# only when you produced a durable report. Always pass real values; do not
# send the example placeholders literally.
#
# Send worker_done exactly once. Use --outcome succeeded when the
# Send worker_done once. If it fails or its result is unknown, follow the
# recovery it prints; you are done only when it confirms. Use --outcome succeeded when the
# requested work is done, or replace it with --outcome failed when it is not.
# Never encode failure only in prose and never silently exit.
# Include BOTH taskId and dispatchId in the payload so a late completion
+6 -3
View File
@@ -98,7 +98,8 @@ Don't post to Slack, GitHub, or other channels during the run; report through th
# only when you produced a durable report. Always pass real values; do not
# send the example placeholders literally.
#
# Send worker_done exactly once. Use --outcome succeeded when the
# Send worker_done once. If it fails or its result is unknown, follow the
# recovery it prints; you are done only when it confirms. Use --outcome succeeded when the
# requested work is done, or replace it with --outcome failed when it is not.
# Never encode failure only in prose and never silently exit.
# Include BOTH taskId and dispatchId in the payload so a late completion
@@ -231,7 +232,8 @@ report to you: their questions, escalations, and worker_done arrive in your own
${cli} orchestration reply --from ${workerHandle} --id <message_id> --body "<answer>"
\`\`\`
Wait for every helper's worker_done before reporting your own. Nesting is
Wait until every helper has settled (worker_done, a failed start, stop, or
abandon) before reporting your own, and name any that failed. Nesting is
capped; your helpers may not be able to start helpers of their own.
---`
@@ -249,7 +251,8 @@ You may dispatch sub-workers for this task. Create your own Run first, then:
${cli} orchestration worker-start --task <task_id> --worktree current --agent <agent> --json
\`\`\`
Wait for every sub-worker's worker_done before reporting your own. Nesting is
Wait until every sub-worker has settled (worker_done, a failed start, stop, or
abandon) before reporting your own, and name any that failed. Nesting is
capped; your sub-workers may not be able to dispatch further.
---`
File diff suppressed because one or more lines are too long