mirror of
https://github.com/stablyai/orca.git
synced 2026-11-17 11:24:37 +00:00
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:
Generated
+1
@@ -142,6 +142,7 @@
|
||||
"ce9a81cb2e6bbb8487107d2e088bf9fd6e0ba71ebc6bcc1929f827fde65fec6b",
|
||||
"d37fa68601e6b383146976baf4ac28b1ecc8acef808394e9cede434a08be82ce",
|
||||
"d6490454f5a2814e98bb3848f05574beb81b7c5111295efd8c1d26c8b16bee4a",
|
||||
"d9ac622844f5d94c02e01d663833a04bd7db522b59385ac92ec5ab5e7cb017b3",
|
||||
"e3b81f4d713f97a65a35ca5db0606939cebfdaade3daf1d709a76df1c869fd8a",
|
||||
"e4aa2bde868fdb45f905189361ab09e613ea9d83875ba7e951b6f3addfb58c75",
|
||||
"e72ecaf625b4a839189e8f13717b0c5b7a309fc82c9ed0dbfb8e861e31a2124a",
|
||||
|
||||
+155
-177
@@ -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
@@ -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
|
||||
|
||||
@@ -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
Reference in New Issue
Block a user