[brennanb2025]

	Files	Added	Deleted	Net
Test	11	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​450	$\color{#cf222e}{\Huge{\mathbf{−}}}$​58	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​392
Prod	55	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​1309	$\color{#cf222e}{\Huge{\mathbf{−}}}$​130	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​1179

ELI5

When a chat that coordinates workers stopped at the wrong moment, the workers' reports kept arriving but nothing ever woke the chat to read them. The workers couldn't tell either: run-show said the coordinator was "null", which looks the same whether the coordinator is a live chat or is gone. Now the next report wakes the chat, and run-show and send tell a worker whether its coordinator can actually read mail.

What Changed

What the user saw (Run run_afb61cba2e2d, Brennan's batch of 21 Linear issues, 10-14):

• A native chat coordinated the Run. At 23:50:35 UTC it ran orca orchestration check, which handed it a batch of 50 messages. Two seconds later Orca shut down mid-turn, and the chat never acknowledged the batch.
• Over the next 5 hours, 39 more messages arrived for the coordinator and none were ever pointed to it. They included worker_done reports (STA-10383 draft PR 28890, STA-10473, PR 28818), escalations ("Parent coordinator unavailable for required round-three answer", "Blocked: Brennan round-three decision pending") and go/no-go questions. The chat sat idle the whole time.
• Workers had no way to know. run-show --json printed coordinator_handle: null, which is normal for a chat coordinator, so a working coordinator and a gone one looked the same. One worker (STA-10535) then sent its question to an unrelated session that had happened to message it last.

Why it happened. A coordinator reads its mail with check, which hands it a batch it must acknowledge on its next check. Until then the batch counts as "outstanding". Both wake paths (a nudge typed into a terminal, or a turn sent into a chat) skip a mailbox with an outstanding batch, on the assumption that the coordinator is still working through it. Nothing ever checked that assumption:

• A chat whose turn ended before acknowledging can only acknowledge in a later turn.
• For a chat, the only thing that starts a later turn is the nudge this rule was suppressing.
• So the batch stayed outstanding forever and silenced every later report. The coordinator's Run binding was correct the whole time: it named a chat that mail would have started.

The same rule also strands a chat that is idle but still alive: if it ends a turn without acknowledging, no new report wakes it. That didn't happen in this incident, because the coordinator ran back-to-back turns until it died.

After:

• Wake (structured-mailbox-pointer-delivery.ts): an outstanding batch blocks a nudge only while the chat's agent is actually working. That is read off the host's current-work projection, the same one the chat view uses, so a turn killed with Orca reads as not working. When the turn has ended, a new report wakes the chat (starting its agent if it is at rest). Its next check replays the old batch, as it already did.
• run-show: now returns a coordinator field, computed on each call and never stored: { address, status: live | exited | unverifiable, reason? }, or null when no coordinator is bound.
  • The text output gets a matching coordinator: line.
  • A chat at rest reads live, because mail starts it. A chat the user closed reads exited (The chat was closed.).
• send: a message into a Run whose coordinator is exited or unbound still queues, but the result now carries the existing recipient_unreachable warning. The warning tells the worker the message waits unread and to tell the user rather than pick another recipient. An unverifiable coordinator stays quiet, because losing sight of a coordinator is not evidence it is gone.

Why

The common pattern for a parent agent whose children report back is that a "the parent will pick this up itself" claim lasts only as long as the turn that made it. Once that turn is cut, the child's report wakes the parent with a new turn. Here that claim was a database row with no turn attached, so a dead turn kept it alive. Scoping the row to a working turn removes this whole class (killed, stopped, or simply ended without acknowledging) instead of special-casing Orca restarts.

Alternatives considered:

• Fence outstanding batches when a session exits. This depends on an exit event that a crash may never deliver.
• Record which process holds each batch. This needs a schema change. The host already derives "is this agent working", so storing a second copy of that fact isn't needed.

Differences from the common pattern:

• Intended: Orca keeps fetch-and-acknowledge mailboxes. In the common pattern, a report is the parent's next turn. Here workers and coordinators on terminals, chats and other hosts all read through check, and acknowledging protects a batch whose reader dies mid-read. Only the "still holding it" claim changes.
• Intended: mail to a chat the user closed is kept and the sender is warned. In the common pattern, a report to an archived parent is dropped. Here the mail is still there if the user reopens that chat or another coordinator takes over the Run.
• Temporary: a batch fetched by a turn that then died is re-pointed only when the next report arrives or the chat runs another turn. Live workers heartbeat every 5 minutes, so this covers a running Run. A final report that was already inside the dead batch still waits for the user's next message. Follow-up: point such a batch once when its turn ends.
• Temporary: terminal coordinators keep the old rule. A terminal pointer is staged and then released if a batch is outstanding, and that release can't yet tell an old batch from one fetched in the meantime. Follow-up: apply the same working-turn rule there.

Found in the same incident, fixed separately: a worker in this Run ran run-use on its own parent Run three times (19:48, 20:31 and 23:24 UTC), each time silently taking the coordinator binding away from the real coordinator. Two more workers did the same in other Runs that night. That is a different structural fact (any caller can bind any Run, including the Run it works for), so it gets its own PR.

Linked Issue

None (maintainer; diagnosed from the live orchestration database, read-only).

Visual Proof

N/A: no rendered UI change. The CLI run-show text gains one coordinator: line.

Testing

• I manually tested these changes locally

• Automated tests added/updated, or explained why not below

• New flow test in structured-chat-coordinator-mail.test.ts, on the in-process runtime, host and fake provider rig:

  1. The coordinator checks, then its agent stops before acknowledging.
  2. The next worker report starts the chat, and its check replays the held batch.
  3. run-show reads live. After the user closes the chat it reads exited, and a worker's send carries recipient_unreachable.

• With the wake change reverted, the test fails: the chat is never started (expected 1 to be 2 connections). With it, the test passes.

• Focused Node vitest on macOS: 1,217 tests across 107 files under rpc/methods/orchestration, the orchestration session suites, the structured-chat coordinator suites, structured mailbox delivery and agent-facing parity; plus 194 tests across 22 files of the CLI orchestration handlers. All pass.

• Not run locally: typecheck and full lint (CI covers them). Not exercised: a real Orca app, SSH and Windows. The change reads only the local chat host's own projection, and the terminal and SSH paths are unchanged.

Review

Agent skill upstream boundary

• Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

• Wire: coordinator on orchestration.runShow is a new optional field, so old CLIs ignore it and a new CLI prints nothing extra against an old runtime. The send warning reuses an existing code. No schema change.
• SSH and remote: a terminal coordinator on a host Orca can't see reads unverifiable and raises no warning.
• Performance: one record lookup per run-show and per send into a run: mailbox.

Author: @BrennanKB5

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

[Jinwoo-H]

Closing in favour of #33639, which merged on 10-25 and covers this case. When a coordinator ends its turn holding an unacknowledged batch, it now gets one notice at the turn edge, naming the held delivery and the exact check --ack command, in both native chat and terminals. Thanks for the original idea here; it shaped that fix.