Orca orchestration proposal

Strong primitives. Little magic. No orchestration product inside the product.

Orca should make it intuitive for a coordinating agent to start workers, communicate, wait, observe output, and recover safely. Orca supplies dependable building blocks; the agent decides the orchestration strategy.

CLI and runtime only agent-directed multi-server capable explicit effects no commit tracking

The test for the design is simple: after reading a few examples, an agent should be able to predict what every command creates, reuses, blocks on, and returns.

What we learned

The current problems are coordination problems, not missing product surfaces.

The research found real reliability gaps, but the earlier proposal responded by adding a scheduler, integration subsystem, dashboard, and large control-plane model. Those additions would make the common agent workflow harder to understand.

Current

Lifecycle mail arrives through prompt injection

Messages persist, but coordinator delivery may wait for the agent to pause. If it keeps polling or working, messages can collect and flood the editable input after a manual interruption.

Needed

A structured, blocking inbox call

Typed worker lifecycle messages return from a pending tool request or the next explicit read. Routine lifecycle delivery never writes into the coordinator's prompt.

Current

Starting a worker is assembled from low-level pieces

Creating a worktree may already create a terminal, but an agent can miss that and create another terminal before launching the worker.

Needed

One composed start operation with full topology and setup choices

The operation composes existing worktree, setup, terminal, and agent creation and returns exactly which resources it created or reused.

Current

Terminal scrollback is treated as agent history

Full-screen TUIs can redraw or discard the useful conversation, making terminal reads incomplete or misleading.

Implemented

Exact structured output with a truthful fallback

Orca reuses its pane-scoped hook association to read a supported Codex, Claude, OpenClaude, or Grok transcript. When it cannot prove that source, it returns labeled bounded terminal output instead of guessing a session.

Current

Results are mostly worker assertions

Orca verifies that the active dispatch reported worker_done, but the summary, changed files, tests, and report path come from the worker.

Needed

Be explicit about what Orca observed

Keep lifecycle authority separate from worker-reported content. Do not add commit, test, merge, or integration tracking merely to make the report appear stronger.

Design rules

Reliability should live underneath a small interface.

Strong primitives have narrow, testable contracts. They do not need to expose every mechanism used to make the contract safe.

The coordinator owns strategy

The agent chooses decomposition, ordering, parallelism, placement, review, and when to wait. Orca does not schedule ready tasks automatically.

Every effect is visible

Responses say which connected server, worktree, setup, terminal, execution host, and agent were created or reused. Defaults are reported, not hidden.

Simple default, explicit escape hatch

The common path needs few arguments and preserves worktree/setup choices. Uncommon custom launches stay on the existing low-level commands instead of bloating start.

Observation is honest

Orca distinguishes observed process state from worker-reported claims and labels the source of transcript or terminal output.

Remote ambiguity stays ambiguous

A disconnect after a remote mutation returns outcome_unknown. Orca does not silently repeat a command that may have succeeded.

Safety is not orchestration policy

Stable identity, stale-worker fencing, and owner routing prevent corruption. They do not choose what work should happen next.

A feature belongs in the core only if it makes an existing primitive safer or clearer. Tracking extra domain facts—commits, merges, budgets, priorities, or organizational roles—is not automatically a stronger primitive.

Primitive 1 · Scope and identity

Four public concepts, each with one job.

A Run prevents unrelated coordination efforts from mixing. Tasks describe work, Dispatches authorize workers, and Messages communicate. Existing worktree and terminal resources remain independently usable.

Run

A lightweight namespace and stable coordinator mailbox. It never schedules work.

Task

A durable description, status, and optional dependencies. Creating it starts nothing.

Dispatch

One supervised worker assignment and its current lifecycle authority.

Message

Durable communication or a typed lifecycle report returned through the inbox.

Persisted worker state	Task state and allowed next action
`starting` / `ready`	Task is dispatched; only show, read, message, or stop may act on it.
`start_unknown`	Task is blocked; recover the same request receipt, inspect, stop, or abandon.
`failed`	Confirmed start failure and authenticated worker failure both leave Task failed. Either permits an explicit `--retry-of` replacement.
`succeeded`	Task is completed; create a follow-up Task rather than retrying it.
`stopping` / `stop_unknown`	Task is blocked and lifecycle authority is fenced; inspect termination or explicitly abandon before replacement.
`stopped` / `abandoned`	Task is blocked and permits an explicit `--retry-of` replacement.

Run operation	Exact effect
`run-create`	Creates a run and stable coordinator mailbox on the coordinator's selected Orca server—its Run home—then binds the current coordinator terminal as its active consumer.
`run-use --id run_123`	Explicitly binds or rebinds the current terminal to that run. Rebinding fences the prior consumer generation and cancels its waiter. A terminal has at most one active run binding.
`run-current` / `run-list` / `run-show`	Reports bindings and state without changing tasks, workers, or mail.

Run IDs stay out of the common path

A command resolves the run only from explicit --run or the current terminal binding—never from a worktree or an “exactly one candidate” guess. Commands return the resolved Run or runId where it is needed for later control; agents do not carry a separate resolution-mode field.

Low-level commands remain run-free

Ordinary worktree, terminal, and full-handoff commands do not create or require a Run. Runs exist only for supervised coordination that needs durable grouping.

One home, workers anywhere

A Run has one home server that owns its tasks and inbox. A Dispatch may point to a worker on any connected Orca server; Orca relays that worker's messages back to the home automatically.

ELI5: a Run is a folder label plus a return address. It keeps one coordination effort's tasks and mail together and gives workers on your Mac or Windows server the same stable place to reply. Create or select it once, then ordinary orchestration commands inherit it. It does not create resources, choose workers, schedule tasks, or group projects.

If a supervised command has neither --run nor a terminal binding, return run_required with exact run-create and run-use examples. Never silently create or infer a Run.

V1 does not archive or delete Runs. run-list and run-show keep old coordination state inspectable; retention administration waits for a demonstrated clutter or storage problem instead of complicating the common lifecycle now.

Canonical command	Compatibility decision
`run-create/list/show/use/current`	New lightweight scope commands. They never decompose or schedule tasks.
`task-create/list/update`	Keep the current flat command names and add Run association.
`dispatch`	Keep as the low-level binding to an exact existing terminal.
`worker-start/show/read/stop/abandon`	New composed supervised-worker operations.
`send/ask/reply/check`	Keep and strengthen the current message operations.
Current scheduler-like `orchestration run --spec`	Must be removed or renamed in Phase 0 before `run-*` can ship. It is not an alias for a lightweight Run and is not part of this scheduler-free design.

ID	Who normally carries it
`runId`	The terminal binding carries it; agents pass it only to override context.
`taskId`	The coordinator uses it for dependencies and worker start.
`dispatchId`	Receipts and worker preambles carry it; show, read, stop, abandon, retry, and lifecycle reports use it.
`deliveryId`	The current mailbox consumer carries only its last unacknowledged delivery.
`messageId` / `threadId`	`reply` takes a message ID and infers its thread. Agents do not manage a separate question identifier.
Resource IDs	Receipt data until an agent explicitly reads, stops, or reuses that resource.
RPC request ID	The client transport creates it automatically. Agents only echo the returned retry token after an unknown outcome; they never invent one.

orca orchestration run-create --objective "Improve message delivery"
# → run_123, bound to this coordinator terminal
orca orchestration task-create --spec "Audit message delivery"
# → task_a, runId run_123 (bound)
orca orchestration worker-start --task task_a --worktree current --agent codex
orca orchestration check --wait --timeout-ms 60000

Primitive 2 · Supervised worker start

One request, predictable behavior for every topology.

worker-start is one synchronous composition of existing worktree, setup, terminal, and dispatch operations. It is not a background executor, external transaction, or placement engine. The coordinator chooses the topology; Orca returns only after the composition is ready, failed, or honestly unknown.

Topology	Default terminal behavior	Setup behavior
Current worktree	Create one fresh agent terminal. Never reuse the coordinator terminal or an arbitrary idle terminal. Reuse requires explicit `--terminal`.	`not_applicable`; do not rerun setup or configured tabs.
Named existing worktree	Create one fresh agent terminal; reuse only an explicitly selected terminal.	`not_applicable`; creation-time setup is not replayed.
New child worktree	Use agent-first worktree creation and reuse its returned agent terminal. Never create a second shell/agent terminal.	Default to `run`. Setup and agent launch start side by side unless the repository explicitly uses `wait-for-setup`. `skip` or `inherit` must be explicit.
New top-level worktree	Same agent-first behavior, with top-level Orca lineage.	Same setup default: run a configured hook; use an explicit escape hatch only for a concrete reason.

Worktree option parity means pass-through

The exact repository selector, name, base branch, child/top-level lineage, setup, and display/comment metadata are validated and passed to the existing worktree primitive. --on already chooses the connected Orca server, so V1 does not add a second project/host placement vocabulary to worker-start; agents may use low-level worktree create when that convenience selector is important.

Choose a connected server only when needed

The default is the Run home. Use --on windows (a saved Orca environment name or ID) only to place a worker on another connected server. V1 resource IDs are server-scoped, so every remote existing worktree or terminal also requires --on. Orca never guesses an owner from a same-looking ID and echoes the resolved server name in the receipt.

Agent selection is honest

When creating a terminal, V1 requires an explicit --agent that resolves through Orca's configured launcher before any effect. Composed start does not promise custom model, environment, or arbitrary command arguments that agent-first worktree creation cannot actually pass through.

Setup is the safe default

For every new worktree, omitted --setup resolves to run. If a setup hook exists, Orca launches it; if none exists, the receipt says not_configured. Preserve the repository's existing setupAgentStartupPolicy: its default is start-immediately, so setup does not delay agent launch or task delivery. Only an explicit wait-for-setup policy gates the agent. An agent may choose skip or inherit only for a specific reason it states in its work log. Orca trusts that judgment and adds no approval gate.

Supervised means lifecycle injection

Task and dispatch input is delivered only after agent readiness. Ordinary worktree/terminal commands remain the full-handoff path without lifecycle duties.

worker-start --on windows is deliberately different from Orca's existing global --environment windows. --on keeps the command and Task on the bound Run home while selecting only the worker server. The global flag still means “send this whole CLI command to that environment” and must not silently change meaning.

Validate conflicts before effects: --terminal requires a current or named existing worktree and cannot combine with --agent, setup, or new-worktree creation options. New worktrees require a name and accept only options supported by the selected underlying worktree command. Custom agent argv stays on the explicit low-level worktree create → terminal create --command → dispatch path, but that two-step path is legal only with start-immediately; it cannot preserve an explicit wait-for-setup policy because the later terminal is not the creation-time startup. Use an agent-first configured launcher or stop and ask rather than bypassing that policy. current always means the coordinator's current worktree on the Run home and cannot combine with remote --on. A remote existing worker needs an exact worktree/terminal selector or an explicit server so same-looking resources are never guessed. Every resolved default includes its source. Discover a remote selector with an explicit read-only command such as orca --environment windows worktree list --json, then copy the returned opaque worktree ID into worker-start --on windows.

Placement/federation error	Meaning
`server_required`	The selected runtime cannot provide connected-server orchestration.
`worktree_not_found_on_server`	The exact worktree does not exist on the selected worker server.
`terminal_worktree_mismatch`	The exact terminal is not owned by the selected worktree.
`resource_server_mismatch`	A worker-server receipt names a different Dispatch or authenticated Run home; Orca never adopts that attachment.
`agent_unconfigured`	The requested launcher is unavailable; no worktree or terminal was created.

Task acceptance	Worker-start effect
First start	Requires a ready Task with no current Dispatch. The runtime creates the Dispatch and moves the Task to dispatched in one local transaction before running the composed effects.
Replacement attempt	Requires `--retry-of` naming the Task's current failed, stopped, or abandoned Dispatch while the Task is failed or blocked. Start creates the next Dispatch generation and moves the Task back to dispatched atomically; the agent never performs a preparatory `task-update`.
Anything else	Return `task_not_startable` naming the rejected Task/Dispatch and perform no worker effects. Completed work gets a new follow-up Task; an unknown or nonterminal Dispatch must first be inspected, stopped, or abandoned.

ready has one testable meaning: the selected agent terminal reached tui-idle, the local or remote Dispatch attachment is durable, and the lifecycle preamble plus task input was accepted. Under the default start-immediately policy, setup may still be running and its exact state is returned in the receipt; its outcome never gates readiness, even if failure is observed before the agent reaches tui-idle. Under an explicit wait-for-setup repository policy, setup must complete successfully before agent launch and task injection. Agent-first worktree creation launches without the task prompt so Orca can establish authority before injection. The effective timeout and startup policy are echoed in every receipt. A successful gated receipt reports setup succeeded. A confirmed setup spawn/script failure reports failed before task input, while a timeout may honestly retain running rather than inventing a failure.

Underneath the call, one transaction creates a starting Dispatch, moves the Task, and records the retry request before effects. Orca journals each irreversible stage and resource receipt before advancing. Restart recovery can therefore prove no-effect, return a durable remote result, or remain honestly outcome_unknown. A pending accepted start retains its Dispatch ID, so repeating the exact request after restart returns that ID and its worker-show command instead of inviting a second start. Orca does not resume unfinished orchestration stages in the background; a setup process intentionally launched under start-immediately may continue exactly as its receipt states.

With start-immediately, the start receipt carries the latest observed setup state. Only a setup state change after that receipt updates worker-show and emits a typed notice; setup never rewrites Dispatch readiness or decides whether the worker should stop. With explicit wait-for-setup, setup failure is a start failure before task input is sent.

orca orchestration worker-start --task task_a --worktree new-child --name message-audit --agent codex --setup run

# Returns when the worker is ready, start failed, or the outcome is unknown.
# Coordinators can issue independent start calls in parallel.

# "result" excerpt from --json
{
  "runId": "run_123",
  "taskId": "task_a",
  "dispatchId": "dispatch_7",
  "state": "ready",
  "stage": "input_accepted",
  "setup": {
    "requested": "run",
    "effective": "run",
    "source": "explicit_request",
    "hookFound": true,
    "startupPolicy": "start-immediately",
    "state": "running"
  },
  "timeoutMs": 60000,
  "effects": [
    { "kind": "worktree", "action": "created_child", "id": "worktree_9" },
    { "kind": "terminal", "role": "setup", "action": "created", "id": "term_setup_11", "tabId": "tab_2", "leafId": "leaf_1" },
    { "kind": "setup", "action": "run", "requested": "run", "effective": "run", "source": "explicit_request", "hookFound": true, "startupPolicy": "start-immediately", "state": "running", "terminalId": "term_setup_11" },
    { "kind": "terminal", "role": "agent", "action": "reused_agent_terminal", "id": "term_12" },
    { "kind": "terminal", "role": "configured_tab", "action": "created", "id": "term_13", "tabId": "tab_3", "leafId": "leaf_1" },
    { "kind": "dispatch_input", "role": "agent", "id": "term_12", "state": "accepted" }
  ],
  "residualResources": [],
  "mutation": { "requestId": "req_7", "replayed": false }
}

Receipts enumerate every created or reused terminal with a role—agent, setup, or each configured terminal (including each tab/split pane), with exact tab and leaf identity when available. Setup may be reported running only after its exact PTY spawn receipt is durable. These role-tagged effects are also the authoritative residual-resource list used by restart inspection and failure recovery.

Start state	Meaning and next action
`ready`	Agent is ready and lifecycle input was accepted. The return receipt contains every created or reused effect; no separate startup notice is required.
`failed`	Return the failed stage, last error, residual resources, Task/Dispatch state, and the durable mutation receipt. The composition itself has returned, but any surviving setup, terminal, or agent process is listed honestly as a residual resource; Orca never implies that failure cleaned it up. The coordinator chooses the matching recovery branch below.
`outcome_unknown`	The connection failed after an effect may have happened. Return the operation stage, `mutation.requestId`, durable effects/residuals, and exact `worker-show`/`worker-abandon` commands. A replacement is rejected until inspection proves it safe or the coordinator explicitly abandons the old Dispatch.

Unknown-start recovery	Exact contract
Query and reconcile	`worker-show --dispatch dispatch_7` routes from the Run home to the owning worker server and execution host. If its durable receipt proves the original worker became ready, failed, or stopped, the home reconciles that same Dispatch; no separate adopt operation exists.
Safe retry	`--retry-of dispatch_7` links a new attempt but does not silently reuse prior placement. The coordinator repeats an explicit valid topology and agent/terminal choice, which may deliberately differ from the old attempt. A new Dispatch is allowed only after the prior one is failed, stopped, abandoned, or reconciled as no-effect. While it remains unknown, return `task_not_startable` without mutation.
Explicit stop	`worker-stop --dispatch dispatch_7` may fence a `ready` or `start_unknown` Dispatch. The owning server closes a terminal only when its durable attachment still matches the exact pane and process incarnation. Unattached, missing, exited, or identity-changed workers become `stop_unknown` with no process action. If the remote server durably stopped the exact worker but its response was lost, a later `worker-show` reconciles that authoritative stopped receipt.
Explicit abandon	`worker-abandon --dispatch dispatch_7` fences future lifecycle mutations from that Dispatch and records every possibly-live resource. It sends no remote command, claims no process stopped, deletes nothing, and warns that a concurrent worker may remain. The coordinator may then start a replacement. Abandoning an older superseded Dispatch is a no-op and cannot block or rewrite the replacement Task.

The Dispatch ID is the worker identity. Do not add another agent-facing start ID. Every mutating CLI result includes one opaque mutation.requestId for recovering that exact request after a lost response; agents never invent it. A transport failure exposes the same value as orchestrationRequestId in its error recovery data. Semantic retry explicitly names the prior Dispatch ID and never replays an unknown effect. After a remote start, show, read, stop, abandon, and message routing use the Dispatch receipt; the agent does not repeat --on for those controls or carry server IDs. A replacement worker-start is a new placement decision and names its target again.

Transport retry and semantic retry are different. If the response itself was lost, reissue the identical mutation with --retry-request req_7 to recover its durable receipt; a changed canonical payload returns request_mismatch. Once that receipt says outcome_unknown, inspect by Dispatch ID instead of replaying it repeatedly. --retry-of dispatch_7 creates a new worker attempt only after the old attempt is safe to replace.

Primitives 3 and 4 · Message and wait

Structured mail is inbox-only, durable, and explicitly consumed.

The inbox is an agent API, not product UI and not terminal input. It strengthens Orca's existing message store and check --wait; it does not add an Event subsystem or a second orchestration engine.

send, ask, reply, completion, heartbeat, and runtime notices only persist structured state and wake a pending tool waiter. Only explicit dispatch --inject and terminal send may modify terminal input. From an active Dispatch, lifecycle send and ask default to that Dispatch's owning Run mailbox. “Sent” means durably accepted—not pasted, observed, or acted upon.

`run:run_123`

The stable coordinator mailbox stored with that Run in the Orca runtime.

`dispatch:dispatch_7`

The exact supervised worker generation, independent of terminal handle changes.

V1 deliberately has no task: message recipient. Use the Run for guidance that survives reassignment and the exact Dispatch for attempt-specific control. This avoids a hidden acceptance-time retargeting rule.

Orca authenticates lifecycle reports automatically. The worker supplies only the Task and Dispatch IDs injected in its preamble; it never supplies Run, runtime, host, terminal, capability, or attestation IDs. At injection, Orca gives the managed pane a narrow unforgeable Dispatch capability through its CLI bridge. The worker server verifies that capability and its local pane; the Run home accepts the relayed report only from the pinned paired peer for that Dispatch. Stop, abandon, or replacement revokes it. Other reports remain stale history and cannot change Task state. This is lifecycle integrity, not a general permission system.

A federated worker omits --to and --run; its authenticated Dispatch already identifies the only valid Run home. Explicit targets are rejected instead of being silently ignored or redirected.

One Run home

The coordinator's server stores the authoritative Run, tasks, inbox ordering, and acknowledgments. Worker servers do not replicate the Run database or elect a new home.

Remote mail waits safely

A worker server durably retains messages for its remote Dispatch until the Run home imports and acknowledges them. Replies wait at the home until the worker server reconnects. This is a narrow relay queue, not a replicated global inbox.

Coordinator

Run home ↔ worker server

Worker

Starts every independent worker

Persists home record and remote attachment

Works concurrently

Calls check --wait only when no local work remains

Returns the outstanding batch or registers one waiter

Continues independently

Pending tool call is blocked

Durably relays question, failure, or completion

Reports one typed lifecycle message

Receives a structured batch

Persists and returns one opaque Delivery ID

No coordinator prompt injection

Processes every message, then acknowledges and waits

Atomically ack → check → register

May continue, stop, or receive a reply

check --wait always targets the Run home and fans in mail from every active remote Dispatch. One disconnected worker server does not block local or other-server messages. Imported relay items are idempotent by their authenticated Dispatch and source sequence, then follow the same FIFO delivery and acknowledgment rules as local mail.

orca orchestration check --wait --timeout-ms 60000
# → returns delivery_81 with an ordered message batch

# Process every message and start newly-ready work.
orca orchestration check --ack delivery_81 --wait --timeout-ms 60000

# "result" excerpt from --json
{
  "runId": "run_123",
  "deliveryId": "delivery_81",
  "messages": [
    {
      "id": "msg_481",
      "run_id": "run_123",
      "from_handle": "dispatch:dispatch_7",
      "to_handle": "run:run_123",
      "subject": "Review complete",
      "type": "worker_done",
      "payload": "{\"taskId\":\"task_a\",\"dispatchId\":\"dispatch_7\",\"outcome\":\"succeeded\"}",
      "read": 0
    }
  ],
  "count": 1,
  "replayed": false,
  "acknowledged": null,
  "timedOut": false,
  "cancelled": false,
  "connectionLost": false
}

Inbox rule	V1 contract
Ordering and size	FIFO by mailbox sequence, bounded to 50 messages per delivery.
Outstanding batch	One per mailbox. Until acknowledged, return the same Delivery ID and batch; newer mail waits behind it.
Acknowledgment	Whole-batch and idempotent. Repeating an acknowledged Delivery ID returns the recorded result and does not consume newer mail. A Delivery is bound to the consumer generation that received it; a fenced coordinator gets `consumer_fenced` and cannot consume the replacement's mail. The same current-consumer check applies to coordinator replies and other mailbox mutations.
Waiters	One active actionable waiter per mailbox. A second returns `waiter_exists`; it never races to consume the batch.
Crash safety	Receiving a batch never marks it consumed. Unacknowledged mail survives client, mailbox-consumer, and runtime restart.
Atomic continuation	`check --ack delivery_81 --wait` commits ack, checks queued mail, then registers the waiter as one runtime operation.

History modes do not consume

check --peek, --all, and type-filtered history reads are read-only debugging surfaces. Legacy consume-on-check behavior is deprecated. Rename local formatting flag check --inject so it cannot imply delivery.

Timeouts are typed checkpoints

Wait returns timedOut, cancelled, or connectionLost distinctly. None means worker failure, none consumes mail, and transport keepalive output is not a worker heartbeat.

Actionable check, acknowledgment, and wait never create separate filtered deliveries. A type filter may decide when a waiter wakes, but the returned Delivery is always the oldest full FIFO batch, including earlier nonmatching mail. History modes may filter freely because they do not consume.

Lifecycle input	Atomic state effect at message acceptance
Authenticated active Dispatch reports `worker_done outcome=succeeded`	Set Dispatch settled/succeeded and Task completed.
Authenticated active Dispatch reports `worker_done outcome=failed`	Set Dispatch settled/failed and Task failed. Coordinator chooses recovery.
Stale or foreign Dispatch report	Persist as stale history; do not change current Task or Dispatch state.
Malformed lifecycle report	Reject the transition and return the missing or invalid field.
`worker-start` returns `failed`	Set Dispatch and Task failed with an explicit recovery reason.
Confirmed `worker-stop`	Set Dispatch stopped and Task blocked; never claim task completion.
`worker-stop` accepted, termination unknown	Fence lifecycle authority, set Dispatch `stop_unknown` and Task blocked, and retain the process/terminal in `residualResources` as possibly live. A new start remains unsafe until inspection confirms termination or the coordinator explicitly abandons with the concurrent-worker warning.
Confirmed `worker-abandon`	Set Dispatch abandoned and Task blocked, fence its later reports, and retain possibly-live resource IDs; never claim process termination.

Inbox acknowledgment confirms recipient consumption only. Lifecycle reconciliation happens once, atomically, when the Run home imports an authenticated message. Every terminal Dispatch transition is a home-side transactional compare-and-set: the first committed completion, stop fence, or abandon wins; later conflicting input is retained only as stale history.

Question state	Ask/reply behavior
`pending`	`ask` from an active Dispatch defaults to its owning Run mailbox. The first reply from the current authenticated Run consumer generation records the answer at the Run home, relays it to the exact worker server, and wakes the local asking call.
`answered`	The pending `ask` or an explicit resume by the original Dispatch returns the recorded answer. Repeating the same reply is harmless; a later different answer conflicts.
Wait timed out or client disconnected	Return the original question message ID and an exact `ask --resume msg_question_7` command without closing or duplicating the question. Resume is allowed only for the original Dispatch. There is no separate Question ID or durable expiry/deadline state machine.
Acceptance response was lost	Retry the identical `ask` with its returned transport retry receipt to recover the original message ID. A changed question conflicts; a blind new ask is never the recovery path.
Dispatch stopped or abandoned	The Run home atomically closes its pending questions, wakes local or resumed waits with `dispatch_inactive`, and rejects later replies.

Question threads are message primitives, not task gates. Use message type question; its target-side delivery follows normal inbox acknowledgment, while the answer lives only on durable thread state. Keep separately managed task gates outside this proposal.

# Worker: target defaults to the owning Run mailbox.
orca orchestration ask --question "Should I preserve the legacy format?" --json
# → question message msg_question_7
# After a disconnect/timeout: orca orchestration ask --resume msg_question_7 --json

# Coordinator: reply to the returned message ID.
orca orchestration reply --id msg_question_7 --body "Yes; preserve it." --json

Blocking is a coordinator decision. The runtime must make waiting race-free, but it must not decide that the agent has exhausted all parallelizable work.

Worker observation

Read a supervised worker by Dispatch, regardless of server.

worker-read --dispatch resolves the worker server and exact process from the Dispatch receipt. Its default auto source returns the exact hook-reported Codex, Claude, OpenClaude, or Grok transcript when Orca can prove that association; otherwise it returns bounded, explicitly labeled terminal output. Agents never choose a server, provider session ID, or transcript path, and task authority never comes from transcript prose.

Default path

Automatic exact selection

--source auto uses a proven supported transcript and falls back to the existing bounded terminal reader with a typed reason such as session_not_reported or remote_capability_unavailable.

Explicit policy

Transcript or terminal

--source transcript requires exact structured output and returns a typed error rather than falling back. --source terminal always uses the retained terminal snapshot.

orca orchestration worker-read --dispatch dispatch_7 --source auto --limit 100 --json

# Exact transcript result for a worker on the saved environment named windows
{
  "dispatchId": "dispatch_7",
  "source": "transcript",
  "sourceIdentity": "opaque-source-fingerprint",
  "provider": "codex",
  "server": { "environmentId": "env_windows", "name": "windows" },
  "remoteRuntimeEpoch": "runtime_epoch_2",
  "transcript": {
    "messages": [ ... ],
    "nextCursor": "opaque-next-cursor",
    "limited": false,
    "returnedMessageCount": 12
  },
  "cursor": "opaque-next-cursor",
  "status": { "worker": "ready", "terminal": "running" },
  "fallbackReason": null,
  "warnings": []
}

# Continue from the returned top-level opaque cursor.
orca orchestration worker-read --dispatch dispatch_7 \
  --cursor opaque-next-cursor --limit 100 --json

Source-pinned continuation

The returned cursor pins the Dispatch, process, source kind, and opaque source identity. auto selects only on the first page. If the process or provider session changes, Orca returns worker_identity_changed or source_changed.

Narrow provider readers

Structured reading reuses the existing bounded native transcript decoders only for exact Codex, Claude, OpenClaude, and Grok associations. Other providers and mixed-version peers retain terminal fallback; no resume, live-stream control, or universal transcript framework is added.

Every response labels source, sourceIdentity, cursor, status, fallback reason, and bounded warnings. Terminal fallback preserves the existing terminal fields and accepts legacy numeric cursors; new cursors are opaque and never expose a transcript path. The worker-owning server performs the read, and neither local nor federated selection may guess “latest session in this directory.”

Orca can say	Orca cannot infer
The active dispatch sent a completion report.	The implementation is correct.
The managed process exited with a particular code.	The reported tests actually passed unless Orca ran them itself.
A later exact-session adapter resolved these structured entries.	The transcript describes the complete repository state.
The worker reported files, summary, and report path.	Those files are exhaustive or the work has been integrated.

Implementation appendix · agents may skip this section

Hidden guarantees for one Run home and many worker servers.

A coordinator on one Orca server must be able to supervise workers on another—for example, a Run on a Mac with Dispatches on both that Mac and a connected Windows server. The minimum federation contract routes commands and durably relays messages; it does not replicate the Run or add scheduling policy.

Agent rule: choose a remote worker once with --on. After that, keep the Dispatch ID and follow the returned inspection commands. Reuse mutation.requestId only to recover the same request after a lost response. Peer identity, sequencing, capabilities, and relay acknowledgments below are Orca implementation details—not fields agents choose or copy.

Internal fact	V1 contract	What agents see
Run home	The server where `run-create` executes owns the only authoritative Run database: tasks, Dispatch state, inbox order, dedupe receipts, and consumer generation.	The terminal binding routes ordinary commands home; no Run-home ID is typed.
Connected environment	The Run home stores its existing saved environment ID/name and authenticated pairing for each worker server. Each Dispatch pins the authenticated peer fingerprint captured at attachment, so re-pairing the saved environment to a different server cannot retarget existing work. That relationship survives the same remote server process restarting; the observed `runtimeId` remains only an epoch.	`--on windows` when placement is explicit; receipts echo the name.
Remote Dispatch attachment	Before prompt injection, the worker server persists a verifier for the opaque Dispatch capability, pinned Run-home peer identity, stable local pane and process incarnation, effect receipts, and relay cursors. Credential material is stored through current-user protected storage, not plaintext in a general Run row. The worker server does not receive a copy of the Run DAG.	Nothing extra; the worker receives only Task and Dispatch IDs.
Caller pane	Each server's native, WSL, or SSH CLI bridge attaches the minted Dispatch capability outside user parameters. The worker server verifies capability, pane, and process incarnation; the Run home verifies the pinned authenticated peer and Dispatch on relay import.	Orca authenticates lifecycle reports automatically.

Home-bound coordination

run-use/current, Task changes, check/ack, and replies go to the Run home. Workers never choose or mutate the home, and there is no automatic home failover.

Server-owned resources

The selected worker server owns its worktree, terminal, process, and any nested native/WSL/SSH/relay host. The Run home stores opaque receipts and routes show, read, stop, and retry back to that owner.

Durable relay, not replication

Worker-to-home lifecycle mail and home-to-worker replies remain queued at their source until the destination imports and acknowledges them. Each item has a stable ID, so reconnects are at-least-once on the wire and once in each inbox.

Home-initiated connection

The Run home uses the same saved, authenticated environment connection already used for remote RPC. It subscribes or pulls by cursor; the Windows server does not need a separate pairing back to the Mac or a publicly reachable callback.

Dispatch generations

Replacing a worker creates a new Dispatch ID; that ID is the generation. A report from an older Dispatch or different pane remains history and cannot change current Task state. There is no second agent-visible generation number.

Idempotent control operations

Before effects, both home and worker server durably record authenticated peer, request ID, canonical payload hash, operation state, and receipt. Identical concurrent or later attempts join or return that record; a changed payload returns request_mismatch. Receipts expose the opaque retry ID needed after an unknown outcome.

Typed unknown outcome

If a remote effect may have happened but Orca cannot prove it, return one outcome_unknown shape with stage, mutation request ID, durable effects/residuals, and exact inspection commands.

Stop and replace

Stop first commits one home-side compare-and-set that fences new lifecycle changes, blocks the Task, and closes pending questions, then best-effort stops only the supervised agent process/terminal. If completion already won, stop returns already_settled; if stop won, later completion is stale history. Orca never deletes the worktree, setup output, or unrelated configured tabs.

Federated relay rule	Exact contract
Worker send acceptance	Success means the worker server durably stored the authenticated message in that Dispatch's outbound relay. The worker may finish even while the Run home is offline.
Home import and lifecycle	The Run home stores the message and applies any valid lifecycle transition in one transaction before acknowledging it to the worker server. Until import, the authoritative Task honestly remains dispatched.
Replies and control mail	The Run home durably queues them for the exact remote Dispatch; the worker server stores them before acknowledging the home and waking a local waiter.
Ordering and duplicates	Each direction uses a scoped key of pinned peer, Dispatch ID, direction, and a monotonic source sequence, plus a 128-bit-or-stronger message ID. A receiver imports only the next contiguous sequence, buffers gaps, and acknowledges only the highest contiguous commit. The home assigns normal inbox order at import, without pretending simultaneous servers have a global clock.
Bounded storage	Enforce per-message byte limits and per-Dispatch pending item/byte quotas, coalesce heartbeats, and reserve space for one terminal lifecycle report. A full relay returns `relay_quota_exceeded`; V1 adds no dead-letter or retention workflow.

Remote edge	V1 behavior
Worker server unavailable before send	Return `remote_runtime_unavailable` before creating a Dispatch or any remote effect. No remote Dispatch attachment exists, so the caller may retry normally after reconnecting.
Connection lost after send	Return `outcome_unknown`, `mutation.requestId`, last durable stage, and exact inspection commands. Repeating the request ID returns the worker server's original receipt or accepts it once; it never duplicates an effect.
Run-home restart	Run state, dedupe receipts, and unacknowledged mail survive. The process runtime ID is only an epoch. Reconnect resumes relay cursors for every active remote Dispatch; if the coordinator pane cannot be safely reminted, `run-use` explicitly rebinds it.
Saved environment re-paired or removed	If its authenticated peer fingerprint differs from the Dispatch attachment, return `peer_changed` with no effect; never adopt the replacement server. Removing an environment with a nonterminal Dispatch retains a routing tombstone for inspection and abandon rather than erasing ownership evidence.
Servers disconnected after start	The worker may continue. Its server retains lifecycle mail and questions while replies remain queued at the home. Silence is not failure, no worker is automatically replaced, and other servers continue delivering normally.
Worker-server restart	Remote Dispatch attachments, effect receipts, and unacknowledged relay items survive. The process runtime ID may change; the Run home routes by its saved environment relationship and pinned peer. `worker-show` reports running only when the stable pane and process incarnation match; it never adopts a same-looking pane or newly launched process.
Mixed server versions	Before effects, both servers must advertise one aggregate `orchestrationFederationV1` contract. Missing support returns `capability_unsupported`; it never silently degrades to prompt injection, terminal scraping, or consume-on-read mail. The worker-side mutation revalidates the pinned peer and advertised protocol recorded for the operation, closing the probe-to-effect race.
Structured worker output	The worker-owning server reads an exact hook-reported Codex, Claude, OpenClaude, or Grok transcript when supported. If the additive federated read method is absent, `auto` returns bounded terminal output labeled with `remote_capability_unavailable`; `transcript` returns `transcript_required`.

Capability checks cover only the new federation contracts, not every platform or host feature. Existing worktree, setup, terminal, Git, WSL, SSH, and relay primitives keep their proven compatibility behavior; optional, truthfully labeled observation may degrade.

Mechanism	Why it stays	Why it is not a scheduler
Server ownership	Prevents commands from acting on a same-looking resource on the wrong host.	The agent chooses `--on`; the owner only determines routing.
Dispatch identity	Prevents stale workers from overwriting current task state.	It does not retry, replace, or start anything automatically.
Unknown outcome	Prevents duplicate remote effects after a disconnect.	The receipt gives last durable stage and inspection command; the coordinator chooses inspect, reconcile, retry, or abandon.

Safety may reject stale, wrong-pane, or wrong-server control-plane mutations. It does not police worker filesystem access, invent new work, choose a worker, or decide that waiting is the coordinator's best next action.

Agent ergonomics

The skill should be a cookbook, not a second help page.

orca --help already owns syntax and exhaustive flags. The skill should teach judgment: which topology to choose, how to preserve parallelism, what the command returns, and what not to create afterward.

Parallel fan-out

Start every independent task first. Only then call check --wait.

Shared-worktree review

Use the current worktree when sharing its exact state is useful.

Independent writers

Create separate worktrees when a concrete checkout conflict calls for isolation.

Ask and reply

Use a threaded question; continue other work while only that worker is blocked.

Read a full-screen agent

Use worker-read --dispatch; Orca routes to the owning server.

Replace safely

Inspect the stop result before deciding where to start a replacement.

Move out of the skill

Complete command and flag catalogs
Internal database and delivery terminology
Provider-specific internals before the common path
Large decision trees for features Orca does not implement

Every recipe must say

When the pattern is appropriate
What the command creates or reuses
Whether setup runs; if not, the concrete reason
How and when results return
The common misuse to avoid

Current Orca · parallel workers in the current worktree

Creates two fresh agent terminals; setup does not run. Create both tasks and both terminals before waiting for readiness, then dispatch both before blocking. The coordinator keeps checking until both expected Dispatches settle; one batch is not assumed to contain both completions. Misuse: waiting for worker A before starting B.

orca orchestration task-create --spec "Audit message semantics" --json
orca orchestration task-create --spec "Audit transcript adapters" --json
orca terminal create --worktree active --title message-audit --command codex --json
orca terminal create --worktree active --title transcript-audit --command codex --json
orca terminal wait --terminal term_a --for tui-idle --timeout-ms 60000 --json
orca terminal wait --terminal term_b --for tui-idle --timeout-ms 60000 --json
orca orchestration dispatch --task task_a --to term_a --inject --json
orca orchestration dispatch --task task_b --to term_b --inject --json

# Repeat until task_a and task_b are both settled; process every returned message.
orca orchestration check --wait --timeout-ms 60000 --json

Proposed Orca · same fan-out with composed worker start

Creates one bound Run and two fresh terminals in the existing worktree. Setup is not_applicable. Each start returns ready, failed, or outcome_unknown; independent calls may be issued in parallel. Worker results arrive through the inbox. Misuse: creating another terminal after start.

orca orchestration run-create --objective "Improve orchestration ergonomics" --json
orca orchestration task-create --spec "Audit message semantics" --json
orca orchestration task-create --spec "Audit transcript adapters" --json

# Concurrent tool call A
orca orchestration worker-start --task task_a --worktree current --agent codex --json

# Concurrent tool call B
orca orchestration worker-start --task task_b --worktree current --agent codex --json

# After both start calls return, loop; do not assume two waits or one batch is enough.
# Repeat process → ack → wait until both Dispatches are settled.
orca orchestration check --wait --timeout-ms 60000 --json
orca orchestration check --ack delivery_81 --wait --timeout-ms 60000 --json

Mac coordinator + Windows worker · one Run across connected servers

The Run and inbox stay on the Mac. The first worker uses the Mac's current worktree; the second creates a top-level worktree on the saved windows Orca environment. Both report into the same inbox, including after a temporary disconnect. Misuse: creating a second Run on Windows or asking the worker to carry server/Run-home IDs.

# On the Mac coordinator
orca orchestration run-create --objective "Audit both platforms" --json
orca orchestration task-create --spec "Audit macOS behavior" --json
orca orchestration task-create --spec "Audit Windows behavior" --json

# Read-only discovery happens against Windows; copy the opaque repo/worktree IDs returned.
orca --environment windows worktree list --json

# Issue these as independent concurrent tool calls, not as one sequential shell script.
orca orchestration worker-start --task task_mac --worktree current --agent codex --json
orca orchestration worker-start --task task_windows --on windows --worktree new-top-level --repo id:<windows-repo-id> --name windows-audit --agent codex --setup run --json

# One home wait fans in local and Windows messages. Repeat until both Dispatches settle.
orca orchestration check --wait --timeout-ms 60000 --json
orca orchestration check --ack delivery_81 --wait --timeout-ms 60000 --json

# Attempt-specific guidance uses the stable Dispatch, never the remote terminal handle.
orca orchestration send --to dispatch:dispatch_windows --subject "Follow-up" \
  --body "Run the additional Windows-only check." --json

Worker completion · success and failure are explicit

The injected preamble supplies the only Task and Dispatch IDs a worker copies. Orca supplies its Dispatch capability automatically; the worker never supplies Run, runtime, host, terminal, capability, or attestation IDs. Misuse: reporting failure as a successful completion or inventing IDs from terminal history.

# Success
orca orchestration send --type worker_done --subject "Review complete" \
  --body "Audited the requested behavior. Found two issues and changed no files. Nothing remains." \
  --task-id "<taskId from current preamble>" \
  --dispatch-id "<dispatchId from current preamble>" \
  --outcome succeeded --json

# Failure
orca orchestration send --type worker_done --subject "Review failed" \
  --body "Could not read the required fixture. No findings are reliable. The fixture must be restored before retrying." \
  --task-id "<taskId from current preamble>" \
  --dispatch-id "<dispatchId from current preamble>" \
  --outcome failed --json

Worker question · ask defaults to its Run

An active worker asks its owning coordinator without carrying a Run ID. The coordinator replies to the returned message ID while other work continues. Misuse: creating a task gate or a second Question ID for a simple reply.

# Worker
orca orchestration ask --question "Should I preserve the legacy format?" --json

# If acceptance may have happened but the response was lost, repeat the identical command with
# the orchestrationRequestId reported by the CLI as --retry-request.
orca orchestration ask --question "Should I preserve the legacy format?" --retry-request req_ask7 --json

# If a server disconnect timed out the wait, resume with the returned message ID.
orca orchestration ask --resume msg_question_7 --json

# Coordinator, after receiving msg_question_7
orca orchestration reply --id msg_question_7 --body "Yes; preserve it." --json

New child or top-level worktree · reuse the returned agent terminal

New worktrees run configured setup by default. Agent-first creation returns the only worker terminal; configured extra tabs remain intentional. Use skip or inherit only for a concrete stated reason. Misuse: adding a second agent terminal because the startup receipt was not inspected.

orca orchestration worker-start --task task_a --worktree new-child --name message-audit --agent codex --setup run --json
orca orchestration worker-show --dispatch dispatch_7 --json

orca orchestration worker-start --task task_b --worktree new-top-level --name transcript-audit --agent claude --setup run --json

# Escape hatch: this task audits the pristine fixture, and setup would mutate that fixture.
orca orchestration worker-start --task task_fixture --worktree new-top-level --name fixture-only --agent codex --setup skip --json

Intentional existing-terminal reuse

Reuses exactly the selected terminal and runs no setup. The terminal must belong to the chosen worktree. Misuse: treating “an idle terminal somewhere” as equivalent.

# Local existing worktree; copy the exact opaque IDs from worktree/terminal list.
orca orchestration worker-start --task task_a --worktree 'id:<full-worktree-id>' --terminal term_12 --json

# Remote existing worktree; --on is mandatory because V1 IDs are server-scoped.
orca --environment windows worktree list --json
orca orchestration worker-start --task task_b --on windows --worktree 'id:<full-windows-worktree-id>' --agent codex --json

Remote uncertainty · branch on what inspection proves

An unknown start or stop is inspected by Dispatch ID; nothing is replayed merely because a connection failed. Misuse: treating show → stop → abandon → retry as an unconditional recovery sequence.

# First recover the receipt for the exact request; this cannot create a second effect.
orca orchestration worker-start --task task_a --worktree new-child --name message-audit --agent codex --setup run --retry-request req_7 --json

# Then inspect the Dispatch if the outcome is still unknown.
orca orchestration worker-show --dispatch dispatch_7 --json

# If ready: keep the worker and wait for its result.
# If failed or stopped: start an explicit replacement, repeating the intended placement.
orca orchestration worker-start --task task_a --retry-of dispatch_7 --worktree current --agent codex --json

# If still unknown: stop and inspect again, or explicitly accept the warning and abandon.
orca orchestration worker-stop --dispatch dispatch_7 --json
orca orchestration worker-show --dispatch dispatch_7 --json
orca orchestration worker-abandon --dispatch dispatch_7 --json

Restart recovery · home and worker server are independent

A Run-home restart preserves the Run, retry receipts, and the same unacknowledged Delivery; run-use is needed only when Orca cannot safely remint the previous coordinator pane. A worker-server restart preserves its Dispatch attachment and relay queue but does not pretend the agent process survived. Misuse: starting a replacement merely because a runtime ID changed.

# Home restart: rebind only if run-current says this pane is unbound.
orca orchestration run-current --json
orca orchestration run-use --id run_123 --json
orca orchestration check --wait --timeout-ms 60000 --json
# → returns the same outstanding delivery_81 until it is acknowledged

# Worker-server restart: inspect the persisted attachment and exact process incarnation.
orca orchestration worker-show --dispatch dispatch_7 --json
# running/ready → keep waiting; gone/failed → explicit retry-of; unknown → inspect or stop/abandon.

The skill must say that check --wait returns a batch. Process every message before acknowledging it.

Scenario tests matter more than keyword checks

Reuse the terminal returned by worktree creation.
Start three independent workers before waiting.
Omit runId only when the coordinator terminal is explicitly bound.
Use current-worktree collaborators without unnecessary worktrees.
Fence an old consumer's acknowledgment after run-use rebinds.
Import duplicated and out-of-order relay frames only in contiguous order.

Never treat a worker report as verified integration.
Never replay terminal input after unknown acceptance.
Page terminal output by Dispatch; use a session source only when exact.
Inspect an ambiguous remote stop before choosing the next action.
Let the first committed stop/completion transition win transactionally.
Reject a re-paired peer and never adopt a same-looking restarted process.

Complexity audit

Keep only the machinery required by Orca's concrete failure modes.

Every retained primitive below addresses a failure Orca can reproduce today. Broader policy and product layers remain out of scope until a simpler primitive proves insufficient in real use.

Observed Orca need	Keep	Deliberately defer
Lifecycle messages can be lost, injected into prompts, or consumed before a caller receives them.	Durable typed mail, explicit acknowledgment, and race-free blocking waits.	Dead-letter workflows, priority schedulers, watchdog policy, or a second queue product.
Terminal scrollback is not always the best available source, but session identity can be ambiguous.	Terminal output as the baseline and an optional exact, source-pinned adapter.	A universal session ontology, resume layer, or global provider exclusivity.
Remote acceptance, process exit, and worker claims provide different levels of evidence.	Explicit lifecycle, fenced replacement, and typed unknown-outcome handling.	Automatic retry, inferred success, rollback, or generalized recovery policy.
A Run home must coordinate workers across restarts and connected Orca servers.	Stable Run, Task, and Dispatch identity with authenticated server relay.	Role simulation, worker scoring, organization models, or integration queues.

Tests prove the contract

Scenario tests must demonstrate durable messages, authenticated relay, lifecycle fencing, and truthful recovery. Design analogy is never a substitute for an Orca-local executable contract.

Complexity requires local evidence

A generalized scheduler, fairness policy, dead-letter workflow, or integration system should be proposed only after Orca users demonstrate that the simpler primitives cannot solve a recurring problem.

Implementation order

Each phase should remove one concrete source of agent confusion.

There is no UI phase. Each runtime change ships with a version-matched example and a misuse test so the skill and behavior cannot drift apart.

Phase 0

Rewrite the orchestration skill as recipes

Teach correct fan-out, current versus new worktree selection, startup terminal reuse, --setup run for new worktrees unless the agent states a concrete reason to skip or inherit, while preserving the existing start-immediately default, current batch behavior, and blocking only after useful parallel work is exhausted. Correct the one-message claim and document today's delivery limits. Rename or remove the existing scheduler-like orchestration run --spec command before the lightweight run-* vocabulary can ship.

Phase 1

Run mailbox, truthful completion, and crash-safe consumption

Add explicit Run-home binding, stable logical recipients, strict inbox-only structured mail, succeeded/failed worker outcomes, one outstanding FIFO batch, explicit acknowledgment, typed timeout results, ask/reply state, a narrow runtime-minted Dispatch capability carried by the CLI bridge, and resume-by-message-ID after a disconnected ask. Migrate existing global rows to one unbound inspect-only legacy Run; do not infer bindings. Do not add separate Question IDs or expiry policy.

Phase 2

Local synchronous worker start and control

On the Run home, compose existing worktree, setup, terminal, and dispatch primitives with setup-run as the new-worktree default, a durable request/stage receipt, side-by-side setup/agent startup by default, startup-terminal reuse, exact readiness, and Dispatch-routed show/read/stop/abandon. Prove current, existing, child, top-level, failure, restart, and unknown-outcome behavior before adding a network boundary. Do not add a background provisioning executor.

Phase 3

Connected-server Dispatch and relay

Extend the same primitives with saved-environment placement, pinned peer identity, remote Dispatch attachments, paired-server calls, and bounded bidirectional relay with contiguous cursors and idempotent acknowledgment. Validate Mac-home/Windows- worker and Windows-home/Mac-worker completion, question/reply, read, stop, either-side restart, re-pairing, disconnect, and mixed versions—without Run replication, failover, or scheduling.

Phase 4

Exact structured worker output

Reuse Orca's existing pane-scoped hook association and bounded Codex/Claude/OpenClaude/Grok transcript decoders. Add auto|transcript|terminal selection, path-free source identity, opaque source-pinned paging, and labeled terminal fallback without adding provider control or a universal transcript layer.

Success looks like

Agents start all independent work before waiting.
Lifecycle messages never flood editable coordinator input.
One Run can supervise Mac and Windows workers through one home inbox.
Remote completion and replies survive either server temporarily disconnecting.
No delivery is consumed before explicit acknowledgment.
Failed worker reports set failed—not completed—and remain worker assertions.
Worker start never reports a resource created before it exists.
Full-screen agent output remains readable when an adapter supports it.
Stale, wrong-pane, or wrong-server workers cannot mutate current task state.

Complexity budget

No new concept without a common recipe that needs it.
No automatic action whose trigger an agent cannot explain.
No provider field that an adapter cannot actually observe.
No hidden default omitted from the operation receipt.
No control-plane fact derived from untrusted transcript prose.
No future feature included merely to keep the architecture open-ended.

Explicit boundaries

What this proposal intentionally does not build.

These are not hidden later phases. They require separate evidence and a separate proposal if Orca eventually needs them.

No product UI

No dashboard or run/task view
No global inbox, badges, or queue screen
No coordinator chat surface
No task DAG visualization
No changes to existing Orca UI behavior

No scheduler

No automatic task dispatch or placement
No capacity vectors or resource classes
No fairness, priority aging, or global queue
No pause, resume, or drain controls
No automatic retry based on silence

No integration subsystem

No commit or branch tracking
No automatic merge or landing
No target-ref locking
No independent verification of worker claims
No cross-run work lineage model

No speculative framework

No organization charts, roles, or worker profiles
No universal provider transcript schema
No dead-letter or poison-message workflow
No generalized continuation/checkpoint protocol
No project hierarchy above lightweight runs
No replicated Run database, leader election, or automatic home failover

Could Orca add these things later?

Yes, but strong primitives do not need speculative abstractions for them today. A future feature should compose the same start, message, wait, read, stop, identity, and ownership contracts. It should justify its own concepts from observed Orca use.

Does removing commit tracking make worker results less trustworthy?

It makes the contract more honest. Today Orca verifies who is authorized to report a result, not that every claim inside the result is true. A coordinator may explicitly ask another worker to review or run validation. That is agent-directed orchestration, not an implicit integration subsystem.

What about connecting multiple Orca runtime servers?

It is a core requirement. A Run stays authoritative on one home server while remote Dispatches execute on saved connected environments such as a Windows machine. Authenticated routing plus a small durable relay carries lifecycle mail and replies across disconnects. This intentionally stops short of a global cluster: no Run replication, leader election, automatic failover, distributed scheduler, or lease manager is required.