feat(orchestration): tell each agent its own orchestration address

[brennanb2025]

	Files	Added	Deleted	Net
Test	10	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​570	$\color{#cf222e}{\Huge{\mathbf{−}}}$​11	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​559
Prod	39	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​477	$\color{#cf222e}{\Huge{\mathbf{−}}}$​144	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​333

ELI5

Every agent Orca runs now knows its own orchestration address, and so does the user.

• orca status --json gains a caller field. Orca's host fills it in from the identity already in the agent's environment. A chat gets session:<id>; a terminal agent gets its terminal handle.
• The orchestration guide and orca --help say what that address is and how to use it. A chat coordinator is told to start its workers and end its turn, instead of blocking in check --wait. Orca wakes it when results arrive.
• A dispatched worker's instructions now say its own address. A chat worker is also told how its coordinator reaches it, and gets commands that work in its own shell.
• A chat's right-click menu gains Copy Orchestration Address. It copies session:<id>, so a user can hand that address to another agent. The existing Copy Session ID is unchanged and still copies the provider's id.

Merge order

Last PR of the structured-chat orchestration stack. Merge in this order: #22522 → #22555 → #22568 → #22631 → this PR. The PR base is brennanb2025/d4-coordinator-delivery (head 6abb9d9f1f).

What works end to end

Proven live in the running app, on an isolated dev profile under ORCA_BACKGROUND_LAUNCH=1, driven over CDP with a hidden window.

Claude: a real structured Claude chat ran "$ORCA_CLI_COMMAND" status --json and got back caller: { kind: "session", address: "session:claude_c69e…", live: true }. It then loaded the guide with "$ORCA_CLI_COMMAND" skills get orchestration and was asked to supervise one worker by following the guide's chat-coordinator section. With no further user input, it:

1. created a Run;
2. started a structured Claude worker;
3. ended its turn, citing the guide ("not to block on check --wait");
4. received Orca's pointer turn;
5. ran a check with no --wait and processed the worker_done;
6. released the worker;
7. acknowledged the delivery with --ack;
8. confirmed that no terminals needed a decision (--terminal-state reclaimable).

The worker's journal shows the new preamble: Your orchestration address is: session:ad834dda-…, the coordinator's session: address, and every command written as "$ORCA_CLI_COMMAND" orchestration …. The worker sent worker_done with exactly that command.

Codex: a real structured Codex chat ran the same status --json and got caller.address = session:codex_e234…. The same run also shows why the guide names ORCA_CLI_COMMAND. In Codex's shell, command -v orca resolved to the user's global /usr/local/bin/orca, while "$ORCA_CLI_COMMAND" was this app's CLI. The full Codex coordinator loop was proven in #22631; it was not re-run here.

Terminal agent: orca status --json in an Orca terminal reported caller: { kind: "terminal", address: "term_d338…", live: true }. That is the same handle as its ORCA_TERMINAL_HANDLE.

Menu: the chat's context menu shows Copy Orchestration Address. Selecting it put session:claude_c69e8529_0241_438c_b5e3_2764dc07c72d on the clipboard and showed the "Orchestration address copied" toast. The rig saved the clipboard first and restored it afterwards.

What Changed

1. orca status --json reports the caller's address, as the host resolved it

• A new read-only RPC, orchestration.callerShow, takes no params. It answers from what the dispatch entry already resolved:
  • a session claim goes through refactor(orchestration): resolve every caller to one orchestration actor #22555's resolver, like every orchestration verb, and returns { kind: 'session', address: 'session:<id>', sessionId, live: true };
  • otherwise the envelope's terminal evidence is checked with the existing resolveTerminalIdentity probe, which returns { kind: 'terminal', address, live };
  • with neither, it returns null.
• A structured worker's address is session:<id>, not its structworker_ handle. The worker also keeps its handle, but session:<id> is the one address that reaches every kind of session (feat(orchestration): deliver worker results to a structured chat coordinator #22631).
• orca status calls it only when the runtime is reachable and the process carries an identity. Nothing names the caller in params: the CLI's orchestration envelope carries ORCA_AGENT_SESSION_ID and the terminal evidence, exactly as it does for every verb.
• A session the host refuses is reported as { kind: 'session', sessionId, live: false, refusal: { code, message } }. The codes are the existing session_caller_* codes (not live, provider id, host boundary, unknown).
• If the host predates the method, caller is left out, so a missing field means "not resolved". caller: null means "this process has no orchestration identity".
• The text output gains a caller: line.

2. The orchestration guide, its references, and the shared skill stub

The always-loaded kernel (skill-guides/orchestration.md) stays within its 202-line budget. It gains five lines, and the detail lives in the references it already routes to.

• Kernel:
  • one bullet: your address is caller.address in ORCA status --json (session:<id> in a chat, your handle in a terminal); never name another agent with --from/--terminal;
  • a consuming check no longer tells every caller to name itself with --terminal <handle>, the instruction shape behind fix(orchestration): stop the sender-terminal refusal recommending another pane's handle #21097. It takes its caller from the environment in a chat or Orca terminal; elsewhere you pass your own --terminal <handle>. A worker uses its preamble's own check command;
  • one line: a chat coordinator ends its turn instead of check --wait, and the coordinator-loop reference is routed for chat coordination.
• references/coordinator-loop.md: the chat-coordinator loop. Start the wave and end the turn. On each turn Orca starts for new mail, run the check that turn names, without --wait. Process it, --ack, and end the turn again. After /clear, Orca moves the Runs to the new session (feat(orchestration): deliver worker results to a structured chat coordinator #22631).
• references/messaging-and-gates.md:
  • session:<id> addresses;
  • what caller live: false and null mean;
  • the Copy Orchestration Address action;
  • /clear gives a new address, and a send to the old one is refused with the new one named;
  • the same check caller rule.
• Shared skill stub (skill-stubs/_shared/cli-resolution.md): the only place allowed to describe CLI resolution. Its ORCA_CLI_COMMAND sentence said "for managed WSL sessions"; it now also covers chat sessions whose login shells (Codex's among them) can put a different orca first on PATH, and gives both forms: "$ORCA_CLI_COMMAND" in a POSIX shell (Git Bash included), & $env:ORCA_CLI_COMMAND in PowerShell. Regenerated with the repo's generators:
  • the 8 skills/*/SKILL.md projections;
  • src/cli/bundled-skill-guides.ts;
  • resources/skills/current-manifest.json and the unreleased rows of snapshot-registry.json.

3. orca --help and the CLI specs

• The help footer says where an agent's address comes from and how to run ORCA_CLI_COMMAND in both shell families.
• The status spec notes the caller field.
• run-use, run-current and check stop describing the caller as a terminal.

4. The worker preamble

• Your coordinator's terminal handle is: becomes Your coordinator's address is:, because a coordinator may be a chat.
• Every preamble states the worker's own address. For a terminal worker that is its handle.
• A structured worker is told:
  • that it is session:<id>;
  • that its coordinator reaches it there or at dispatch:<id>;
  • that mail arriving while it is idle starts a new turn;
  • that its commands invoke the CLI through ORCA_CLI_COMMAND.
• The invocation comes from feat(orchestration): deliver worker results to a structured chat coordinator #22631's structuredSessionCliInvocation({ platform, provider }), the same rendering the pointer turn uses. A Codex worker on Windows gets & $env:ORCA_CLI_COMMAND; everyone else gets "$ORCA_CLI_COMMAND". This replaces orca-dev/orca, which a login shell can resolve to a different Orca.
• The mode-parity test still requires the two modes' preambles to be byte-identical, except for the worker's own address and the CLI invocation. So verbs, flags and sections cannot diverge between modes.

5. Copy Orchestration Address

• It sits in the structured chat's context menu:
  • in a chat tab, last, after a separator;
  • in a chat inside a terminal pane, beside the existing ID actions, just above Copy Session ID.
• It copies session:<id>, derived with the shared actor codec (formatOrchestrationActor), and toasts success or failure.
• Copy Session ID is untouched.
• Strings are in en.json and hand-added to es, fr, ja, ko and zh.

Why

The mechanism: Orca already resolves a caller's identity on the host, once, at the dispatch entry (#22555). The agent just had no way to see the answer. So the agents guessed, and the old guide told them to pass --terminal <handle>, which is how #21097 happened. callerShow returns the result of that same resolution rather than adding a second resolver. Putting it in orca status, which the guide's supervised loop already runs first, means a coordinator that follows the guide sees its address with no new step.

Alternatives rejected:

• Put caller into status.get. status.get is the runtime-readiness probe. It is called without an orchestration envelope (the 1s local probe, the contract check, remote status), and the session resolver only runs for orchestration.* requests. Every readiness probe would pay a session-record read, and a refused session would turn a readiness check into an error.
• Echo ORCA_AGENT_SESSION_ID from the CLI. That does not prove the host will act as that session (a released lease, a provider id, another host), and the brief requires the answer to be host-resolved.
• Put the literal id in each chat's system prompt. That changes every chat's prompt; a pointer to the verb is enough, and it is what the guide now does.
• Relabel Copy Session ID. In Orca's UI, "Session ID" already means the provider's id (terminal panes, AI Vault), so the new action gets a distinct label instead.

Deviations, stated plainly:

• The preamble and pointer name the CLI by its environment variable, not by a literal path. Quoting a path with spaces differs across shells; the variable form is one string per shell family.
• A terminal agent's caller.live: false reports a stale handle and does not remint it. The coordinator verbs remint through ORCA_PANE_KEY; status only reports.

Linked Issue

None — part of the structured chat status/orchestration program. Stacked on #22631.

Visual Proof

Live dev app, hidden window, CDP screenshots.

Chat context menu: before / after

Before (base)	After

After selecting it (the clipboard held session:claude_c69e8529_0241_438c_b5e3_2764dc07c72d):

orca status --json caller, from a Claude chat, a Codex chat and a terminal agent

A Claude chat coordinating one worker by following the guide: it ends its turn, receives the pointer turn, checks without waiting, releases the worker and acks

The "before" shot is the same running app with this PR's three renderer files set back to the base commit (vite HMR), then restored.

Testing

• I manually tested these changes locally (live Electron run; see "What works end to end")
• Automated tests added/updated

New tests

• orchestration-caller-show.test.ts runs through the real dispatcher and session-caller harness:
  • a chat answers session:<id> even when it carries a terminal view's pane evidence;
  • a structured worker answers session:<id>, not its handle;
  • a released lease, a provider id (whose refusal names the Orca id) and a paired client are each refused with the existing codes;
  • a terminal handle is answered live or not live through the identity probe;
  • no identity answers null.
• status-caller.test.ts runs the real orca status handler and the real CLI client over a real Unix socket:
  • the request carries the session id in the envelope and no params;
  • the host's answer is printed in JSON and as text;
  • a PTY handle is sent as evidence;
  • a refusal is reported as live: false;
  • an older host leaves caller out;
  • no identity means no request.
• preamble.test.ts:
  • a terminal worker's address is its handle;
  • a structured worker gets session:<id> and the reach sentence;
  • in both the POSIX and the PowerShell form, every command in the fence starts with the invocation, dev mode included.
• deliver-worker-dispatch-preamble.test.ts:
  • a structured worker's preamble is built from its own session id;
  • a Codex worker on Windows gets & $env:ORCA_CLI_COMMAND and a Claude worker gets "$ORCA_CLI_COMMAND";
  • a terminal worker keeps bare orca.
• use-native-chat-context-menu.test.tsx:
  • the action copies session:<id> in both mount modes;
  • it sits beside Copy Session ID under its own label;
  • it is absent without an address;
  • a failed copy toasts an error, not success.
• Updated: the method population counts (41 → 42) in the session-caller and run registry tests; the preamble snapshot; and the mode-parity test, as described in §4.

Ablations: 12 mechanisms, each deleted or neutralized. Each replacement was asserted to match exactly once, run against the 6 reachable test files (61 tests), then restored from HEAD. All were re-run at this head, and every one went red:

Ablated	Red
Host: a session caller is not answered	2
Host: the terminal handle is not probed	1
CLI: status never resolves the caller	4
CLI: a session refusal is not reported	1
CLI: asks the host with no identity	1
Preamble: a structured worker keeps the bare CLI	5
Preamble: no structured address section	5
Delivery: the structured session is not passed to the preamble	3
Delivery: the invocation ignores the provider (Codex on Windows)	1
Menu: item missing in a chat tab	2
Menu: item missing in a terminal pane	2
Menu: a failed copy toasts success	1

The first run of "invocation ignores the provider" was green, because the suite ran only on macOS, where both providers render the same form. A test that stubs process.platform to win32 was added, and the ablation then went red.

Guide-contract pins (in config/scripts), each ablated by restoring the old text in the kernel:

• the old worker line check --terminal <your_handle>: 4 red;
• the old check caller sentence: 3 red;
• an ORCA_CLI_COMMAND line restated in the kernel: 4 red.

The address that the structured chat component passes to the menu (NativeChatStructuredSession) has no unit test. It is proven live: the before shot drops it, and the after shot copies the real session id.

The config/scripts guide-contract tests are green at this head: the guide keeps the ORCA placeholder (executable resolution lives in the shared skill stub, whose text now covers chat sessions as well as WSL), the kernel stays inside its line budget, and the caller pins assert the new environment-resolved contract.

Suites (env -u ORCA_STRUCTURED_SESSION -u ORCA_AGENT_SESSION_ID … npx vitest run --config config/vitest.config.ts): config/scripts, src/cli, src/main/runtime/orchestration, src/main/runtime/rpc, src/renderer/src/components/native-chat, the actor codec and the coordinator-mail integration suite ran at this head: 1,001 files / 9,480 tests, 9,153 passed, 321 skipped, 6 failed. None of the 6 comes from this PR:

• Two pass in isolation (a load-sensitive run): build-native-for-platform and orchestration-all-start-versions-migration.
• Three fail identically on a clean export of the base, and need a real pnpm install or shell environment: patched-dependencies-frozen-install (×2) and skill-recipe-shell.
• One is the keepalive subprocess test; see Notes.

Checks

• pnpm tc:node, tc:cli and tc:web are clean.
• check:code-quality:changed: 0 findings. A full pnpm exec oxlint reports 0 errors, and oxfmt --check is clean on the changed files.
• verify:bundled-skill-guides, verify:skill-bundle-manifest, verify:rpc-params-catalog and the four verify:localization-* gates pass.
• pnpm-lock.yaml is absent from the range. No documentation files are added; every guide, reference, stub and skill file edited is already tracked.

AI Disclosure

Review

• A new RPC method for status rather than a field on status.get; see Why.
• A structured worker's reported address is session:<id>, although its sends still carry --from <structworker handle>, which the host maps to the same session.
• The preamble text changed for terminal workers too: the coordinator line and a new address line.

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

• Wire: one new RPC method, no new fields on existing methods and no stream opcode.
  • New CLI, older host: method_not_found, so caller is left out.
  • Older CLI, new host: the method is never called.
  • caller is an optional field in CLI output only.
• Paired / remote (--environment): a session claim from a paired client is refused by refactor(orchestration): resolve every caller to one orchestration actor #22555. status then reports the refusal (session_caller_host_boundary) instead of an address. A terminal handle from another host probes as not live.
• SSH: the SSH passthrough strips the session id (feat(orchestration): let a structured chat run orchestration as itself #22568). A remote shell's status therefore reports its terminal handle, or null.
• WSL: a WSL-stamped session claim is refused as another host, and reported as such.
• Folder workspaces: the rig ran in a plain folder repo. The address carries no workspace.
• Mobile: no mobile code changed. The method is not on the mobile allowlist. Mobile tests were not run.
• Performance: status makes one extra RPC, and only when the process carries an identity. For a session it costs one record read. Resolving the caller may bring up the agent-session host, so the callerShow call runs under its own 10s budget instead of the 1s readiness probe's; a process with no identity, or an unreachable runtime, never pays it.
• Keepalive subprocess test (not from this PR): orchestration-cli-subprocess.test.ts is skipped unless a built out/cli exists. On this machine its keepalive case fails (check answers stable_pane_required for its term_nobody caller). It fails even with a freshly built CLI under env -i, keeping only HOME, PATH and TMPDIR, and it fails identically on a clean export of feat(orchestration): deliver worker results to a structured chat coordinator #22631's head 6abb9d9f1f. The review of this PR ran it 3/3 green in another shell and attributed my failure to the test spreading process.env into the spawned CLI. My env -i run does not support that explanation, so the cause is machine-specific and still unknown. It is not tied to this branch.

Not verified

• An evicted Claude coordinator is not woken by mail within the same app run. Live, a hidden Claude chat was evicted about 50s after its turn. Mail to it then logged [orchestration] could not wake a structured session for its mail { error: 'provider close unproven' }, and no pointer turn arrived. The feat(orchestration): deliver worker results to a structured chat coordinator #22631 implementer traced it to the Claude adapter on main: the adapter keeps an evicted session indexed when it cannot prove the provider closed, so every later resume fails. It is reported to the orchestrator and is not changed here. After an app restart, the pending mail was delivered on restore, and the chat ran the guide's loop (check, reply, --ack). Codex and non-evicted coordinators are not affected.
• The chat-in-a-terminal-pane mount of the menu action was covered only by unit tests. The live shots are the chat-tab mount.
• The Codex coordinator loop was not re-run under the new guide. Codex was proven here only for status; the full loop was proven in feat(orchestration): deliver worker results to a structured chat coordinator #22631.
• The PowerShell form (& $env:ORCA_CLI_COMMAND) is unit-tested only. There is no Windows host.
• Linux, WSL, SSH, packaged builds and mobile were not run. All runs were on macOS dev.

[pullfrog]

✅ No new issues found.

Reviewed changes

• orca status --json reports caller — new read-only orchestration.callerShow RPC answers from the dispatch entry's resolved session (session:<id>, live: true) or probes the envelope's terminal handle, else null; CLI maps session refusals to {live:false, refusal} and omits the field on an older host.
• Worker preamble names the worker's own address — terminal handle, or session:<id> plus a reach sentence for a structured worker, whose commands now invoke "$ORCA_CLI_COMMAND" / & $env:ORCA_CLI_COMMAND instead of orca-dev/orca.
• Guide, help text, and bundled skill guide — "Your address" section, a non-waiting chat-coordinator loop, and the ORCA_CLI_COMMAND forms; run-use/run-current/check summaries de-terminalized.
• Copy Orchestration Address menu action — copies session:<id> from a structured chat in both mounts, with success/failure toasts and translations in six locales.

I verified the host handler's context members (orchestrationCaller.actor/sessionId, orchestrationCompatibilityEvidence) are populated for every orchestration.* session claim, that the refusal codes the CLI keys on match the ones the resolver emits, that no production parser depends on the relabelled coordinator line, and that the bundled guide is regenerated in sync. The changed suites (preamble, deliver-worker-dispatch-preamble, status-caller, orchestration-caller-show) pass locally (48 tests). Wire changes are additive and the mode-parity normalizer is not vacuous.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

The branch was rebased since the prior pullfrog review (47e84abbdaf6, 6 commits). The only commit new this run is e1c897b980, a guide-contract fix plus regenerated artifacts:

• Moved ORCA_CLI_COMMAND resolution into the shared skill stub — the invocation guidance left the always-loaded orchestration kernel for skill-stubs/_shared/cli-resolution.md, which now covers chat sessions beside WSL and gives the POSIX and PowerShell forms; every skills/*/SKILL.md projection, both skill bundle manifests, and src/cli/bundled-skill-guides.ts were regenerated.
• Relocated the chat-coordinator loop and address details to references — references/coordinator-loop.md now owns the non-waiting loop and /clear note, references/messaging-and-gates.md the address details, while the kernel keeps one pointer line each for the caller's address, the environment-resolved check caller, and the chat coordinator (kernel measured at 201 lines, budget 202).
• Repinned the kernel contract tests — asserts the environment-resolved check caller and Never name another agent with --from/--terminal, requires the preamble's own check command, and rejects the old check --terminal <your_handle> shape from #21097.

I read the full raw diff end to end. Production source is untouched by e1c897b980; the change is documentation, test contracts, and regenerated artifacts. config/scripts/orchestration-skill-guidance.test.mjs passes (29/29), and pnpm verify:bundled-skill-guides, verify:skill-bundle-manifest, and verify:rpc-params-catalog all exit 0 at this head, so the regenerated block is in sync. No threads from the prior review needed retiring.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}