[brennanb2025]

	Files	Added	Deleted	Net
Test	9	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​362	$\color{#cf222e}{\Huge{\mathbf{−}}}$​22	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​340
Prod	26	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​489	$\color{#cf222e}{\Huge{\mathbf{−}}}$​36	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​453

ELI5

An agent that Orca hands a task to (a "worker") sometimes needs helpers of its own, for example a review loop that wants two reviewers. Orca refused to let the worker start them on the Run it was working for. The only way around it was for the worker to start a whole new Run of its own, and doing that silently moved the worker's inbox, so messages from the agent that gave it the task stopped arriving where the worker was looking. Now a worker starts helpers as itself, the helpers report back to it, and its inbox never moves.

What Changed

The problem

• On 10-15 a review worker (dispatch ctx_cd859ba985d0, Run run_0c6e0ad8ad5b) ran orca orchestration worker-start --run run_0c6e0ad8ad5b --from <itself> --parent <its task> --agent codex ... and got consumer_fenced: worker-start requires the coordinator terminal currently bound to the Task Run. No helper was created and the review of Chat: dropped files hold Send until they're attached #29173 finished incomplete.
• The worker's instructions said "Create your own Run first" (run-create). That makes the worker the coordinator of a new Run, and Orca then delivers everything addressed to the worker into that new Run's mailbox. Reading the old Run (check --run <old>) returns consumer_fenced. On 10-15 a watcher that hid that error missed about an hour of the coordinator's mail; on 10-14 several workers then ran run-use on the Run they worked for and took it away from its real coordinator (Stop workers from taking over the Run they work for #29008).
• Why it happened: the Run's coordinator seat was the only source of two separate things, the right to start workers and where a party's mail is delivered. A worker could only delegate by taking a seat, and taking a seat moved its inbox. The same coupling is behind several open fixes in this area (Stop workers from taking over the Run they work for #29008, fix(orchestration): require explicit replacement of a bound Run #28922, fix(orchestration): let the owning Run address a Dispatch after its assignee binds a child Run #24974, fix(orchestration): link worker-created sub-Runs #16784).

What changes for agents and the people supervising them

• A worker with an active task can run worker-start --spec ... --agent <agent> on the Run it works for. The helper's task appears in that Run, under the worker's task, and records which worker started it.
• The helper's worker_done, heartbeats, escalations, status messages and questions (ask) go to the worker that started it, and the worker reads them with its normal check. It answers a helper's question with reply. The Run's coordinator does not get this traffic.
• The worker's own inbox never moves: its coordinator's mail keeps arriving in the same check, and run-current still shows no Run for it.
• When the worker finishes or is stopped, the reports in its mailbox that it never read (worker_done, escalations and status messages) and any question it never answered move to the Run's coordinator, which is woken for them. Heartbeats stay behind: liveness is already recorded on the helper's task, so an old heartbeat is not work for the coordinator. Helpers that keep running after that report to the coordinator.
• The worker instructions now show worker-start and reply for helpers instead of run-create. Remote workers (started with --on) keep the old run-create instructions; see Notes.
• No UI change.

Mechanism

• One rule, dispatchReportMailbox: a task's reports go to the task that started it while that one is still active in the same Run, otherwise to the Run. It reads the existing creator_dispatch_id on each task attempt and is evaluated on every send, so nothing is stored and nothing has to be cleaned up. Used by send (report types only), ask, the unexpected-exit escalation and the setup-finished notice.
• worker-start authority (resolveWorkerStartRun): the Run's coordinator, as before (it takes precedence), or a worker on an active task, resolved by the same lookup that stamps the helper's creator, so who may start a helper and where it reports always agree. The creator is checked again inside the transaction that reserves the helper, so a worker that finished in between creates nothing.
• Limits for workers: helpers are fresh agents on this host (--terminal and --on are refused for workers, so a worker can't take over another agent's pane or start a helper that can't report back); --task only for a task whose latest attempt was the worker's own helper (a retry), never the coordinator's tasks. The existing depth limit applies unchanged.
• Answering: reply from the worker whose task a question was addressed to answers it from that task, checked against the task's current attempt inside the answer transaction. The Run's coordinator can still answer any question in its Run.
• Handing back: every path that settles a task already calls closeQuestionsForDispatch; it now first moves the settled task's unread helper reports and unanswered helper questions to the Run's mailbox.

Why

• This removes the coupling instead of adding another guard around it: a worker never needs a coordinator seat to delegate, so it never has an inbox to lose. The common pattern is the same: the delegating agent acts as itself, each child records its parent, and the child's results go to the parent's own unchanged inbox.
• Everything is derived from rows that already exist (creator_dispatch_id, task status), so there is no new saved field and nothing that can strand.
• Alternative considered: keep "a worker creates its own Run" and patch the messages and routing around it. That is the path the open PRs above take, one guard each, and it keeps a worker in two roles at once.
• Differences from the common pattern, labelled:
  • Intended: helpers live in the same Run as their creator, so the Run's coordinator still sees them in worker-list. Orca's Run is the unit a coordinator supervises.
  • Intended: when the creator is gone, its helpers report to the Run's coordinator instead of being dropped. Orca has a coordinator above the worker; dropping a helper's result would be worse.
  • Temporary: remote workers (--on) keep the old own-Run path, because their reports travel through the Run's home host to the Run mailbox. Follow-up: STA-10701.
  • Temporary: a worker can still run-create (old prompts and skills do it), and that still moves its inbox. Retiring it is a product call, listed in STA-10701.

Linked Issue

Linear: STA-10701

Related, not closed by this PR: #29008 and #29006 (open drafts in the same area; this PR is based on main and does not depend on them). #29006 also changes mail delivery in message-inbox.ts, mailbox-pointer-stage.ts and structured-mailbox-pointer-delivery.ts, which this PR touches too (it scopes the "delivered" mark to the mailbox that received the mail), so whichever lands second needs a real merge of those files and a fresh CI run, #28922, #24974, #16784.

Current-head validation (2026-10-22)

Reviewed head: f2b0fc8c6a91e0d6d83c7dc3381ca4677e42bb6c, after merging main and updating formatting. Independent checks of worker authority, dispatch identity/depth, mailbox delivery, pending questions, settlement recovery and replay found no proven semantic conflict. The import conflict keeps the helper-authority path and main's relocated request schema. #29006 remains open and its delivery redesign is absent from this head.

This is an orchestration/CLI PR: the review policy requires integration tests running the real CLI (qa=tests). On Windows low spec, 43 actual source CLI commands ran against this head's production RPC server/runtime and on-disk database; two named suites passed all six tests. They exercised helper creation on the same Run, scope/depth refusals, reports and questions in the creator's ordinary inbox, replies, coordinator follow-ups, helper completion before and after creator settlement, mailbox replay, stop-window and rollback recovery, and database close/reopen recovery. Automated agent launch/readiness fixtures were used; this is not current-head rendered-app or real-provider QA. The earlier macOS real-agent screenshots below remain evidence for 39ceaf3db5c only.

The full PR workflow passed on the current head, including static analysis, typecheck, unit tests and cross-version wire compatibility. The supplemental WSL workflow also passed after retrying an Ubuntu distro-import setup timeout; no code change was needed. No new code change was needed. The dedicated performance pass covered all six review questions from source; large-backlog latency and live cross-platform resource use were not measured.

Visual Proof

Real runtime QA on macOS (hidden test copies of origin/main and this PR at 39ceaf3db5c, same fixture repo with its setup script and default tabs, a real Grok agent as the worker and helper, throwaway homes; real hook config hashes unchanged).

Flow	main	this PR
Worker starts a helper on the Run it works for (no run-create)	Refused with consumer_fenced, no helper	Helper starts on the same Run; the worker is still bound to no Run of its own
Helper's worker_done	n/a	Arrives in the worker's own plain check and is acknowledged there
Coordinator's follow-up to the worker	Reaches the worker	Still reaches the same worker's plain check
Worker reports done	Last	Last, after both deliveries were acknowledged
Tabs and focus	Server tab stays selected when the worker tab opens	Server tab stays selected when the worker and helper tabs open; windows stay hidden and unfocused

main: one worker tab, worker finished	this PR: worker and helper tabs, helper finished

Not exercised live (checked from source and covered by the flow tests): the three-level hand-back when a middle worker finishes with a helper's question unanswered, and the older own-Run launch path. The branch build showed a first-use "Search every agent session" introduction on its fresh profile; that comes from the main merge, not this PR.

Testing

• I manually tested these changes locally

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

• New structured-chat-worker-helpers.test.ts, one flow on the chat coordinator rig: a dispatched chat worker passes worker-start authority on the Run it works for; its helper's escalation and question arrive in the worker's own check; the worker's reply unblocks the helper's ask; the coordinator's mailbox stays empty and the worker is still bound to no Run; after the worker acknowledges and finishes, a later helper escalation and the helper's worker_done reach the coordinator. Fails with the send routing reverted.

• Updated the preamble pins for the new SUB-DISPATCH text.

• Focused Node vitest on macOS: the orchestration messaging, worker, federation and DB suites plus the runtime mailbox specs, in two runs (79 files / 880 tests and 120 files / 952 tests), all passing. Typecheck and lint are left to CI.

AI Disclosure

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

• Mixed versions: no RPC field or stored column changes. An older CLI talking to a new host gains the ability with the flags it already sends. The instructions a worker sees are generated by the host that runs it, so a new preamble never meets an old host.
• SSH and remote: remote workers are unchanged (old instructions; --on refused for workers). Nothing here treats loss of contact as a finished task; the hand-back runs only when a task actually settles on its own host.
• What may surprise a user: the Run's coordinator sees helpers in worker-list and as subtasks of the worker's task. A coordinator's group sends (@all) reach helpers too, since they are live tasks of the Run. If a worker finishes before reading what its helpers sent, the coordinator receives those messages.

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)

[brennanb2025]

Workers previously had to create a new Run to start helpers, which moved their inbox and made coordinator follow-ups difficult to receive. This PR lets a local dispatched worker start helpers under its current work and receive their reports without changing inboxes.

The two earlier recovery defects have been addressed on 640232c, and fresh independent verification is pending. Unanswered helper questions (including ones already read) and unread completion, escalation and status messages now move together to the Run when their creator settles; the same transfer covers messages sent during a stop. Delivery state is reset, old deliveries are fenced, and the new owner is notified after the transaction commits. Recovery uses the recipient mailbox and Run, so a status message does not need a payload.

The required three-model design panel and fresh plan check completed before implementation. The source trace covers rollback, committed-row revalidation, existing restart recovery, replay attention and mailbox-scoped late delivery stamps. Saved-data host downgrades remain outside the supported contract; no RPC parameter, stream opcode or stored-column change was introduced. Remote workers keep their existing launch and relay path.

Update for head 39ceaf3db5c. Fresh independent delivery, lifecycle and readiness reviews ran on 640232c. Lifecycle and readiness found no new P0-P2 and agree both earlier recovery defects are fixed. Delivery found one P2: replaying the same worker_done request did not re-wake the Run, because the executor overwrote the receipt's stored replay targets. 39ceaf3 removes that stored augmentation and derives the Run's targets at replay time from its current unread reports and pending questions, only for a Dispatch that started same-Run helpers; it notifies only and never re-settles or inserts messages. A focused review of that commit found no P0-P2 (two P3 notes: a replay may also wake for unrelated unread Run mail it was owed anyway, and the failed-first-wake replay path is traced but not separately tested).

Verified: the full PR workflow 38995786372 passed on this exact head, including static analysis, typecheck, all unit-test shards and the final PR checks passed gate. Real runtime QA on macOS with a real Grok agent (main vs this head, results and screenshots in the PR description) passed the core flow: main refuses a worker's direct helper; this head keeps worker and helper on one Run, delivers the helper's completion and the coordinator's follow-up to the worker's own check, and the worker finishes last. The three-level hand-back and the older own-Run path were checked from source and the flow tests, not live. The PR description now says exactly what moves to the Run (reports and unanswered questions, not heartbeats) and that #29006 touches the same delivery files. The bot thread about heartbeats was answered and resolved under the panel ruling. Generation and process-incarnation concerns without concrete failing inputs remain deferred; local-only helper scope and legacy own-Run nesting remain temporary boundaries tracked in STA-10701.

For Brennan's review

Human judgment points are the intended shared Run fallback when a creator settles and the temporary remote-helper exclusion; no new product decision is requested. #29006 changes the same delivery files, so whichever lands second needs a real merge and a fresh CI run.

---

Main-sync update: f2b0fc8c6a91e0d6d83c7dc3381ca4677e42bb6c. Independent authority and mailbox/recovery/readiness checks found no proven P0–P2 semantic conflicts or new unexpected behavior. The import conflict retains worker authority and main's shared request schema. Main's receipt imports and explicit remote-attachment projections preserve the paths the PR uses; removed dead delivery code does not bypass the live mailbox paths. The five-file formatter update changes layout only. The dedicated performance pass traced admission, notification ownership, synchronous storage, backlog scale, execution host and cleanup; large-backlog latency and live cross-platform performance were not measured.

Current-head integration validation passed on Windows low spec: 43 real source CLI commands against the production RPC server/runtime and on-disk database, with two named suites passing all six tests. Coverage includes helper creation, same-Run parentage/depth, scope refusals, report/question delivery and replies, coordinator follow-ups, completion before and after creator settlement, acknowledgement replay, pending-question/payload-free report hand-back, stop-window/rollback recovery, and database reopen. Agent launch/readiness use automated fixtures; no current-head real-agent or rendered-app claim is made. The orchestration/CLI QA requirement is covered by these tests. The earlier macOS real-agent QA and screenshots remain evidence only for the previous head.

The full PR workflow passed on this exact head. One supplemental WSL job timed out during Ubuntu distro import, before dependencies or Orca tests; the same stage timed out on main, the workflow is unchanged here, and other distro jobs passed. The failed-jobs-only retry passed, including Ubuntu distro import and both Orca WSL phases. Review and integration validation are complete on this head, with no new code changes needed.

Non-product observations: existing Vite configuration warnings and an install notice for an unapproved browser skill did not block the integration tests; no approval/install of that skill was performed. Initial diagnostic attempts needed fixture identity and durable result logging corrections. Final command logs, runner/process identities and a zero-survivor check are saved privately; initial short-lived install/test subprocess identity recording was incomplete. Real configuration hashes remained unchanged and the QA slot and terminals were released.

For Brennan's review

The intended behavior is that helpers remain visible to the Run coordinator and receive Run-wide group sends, and a surviving coordinator receives eligible mail after the creator finishes. The temporary remote-helper boundary is described above. Existing main-versus-branch screenshots in the PR body show the prior-head core flow; they are historical evidence. #29006 is still open and changes overlapping delivery paths: whichever lands second requires a merge review and fresh checks.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 6c46ad91-380c-4a33-8c4f-2b8239f63201

📥 Commits

Reviewing files that changed from the base of the PR and between 640232c and 39ceaf3.

📒 Files selected for processing: 3

• src/main/runtime/orchestration/db/messages/helper-mailbox-hand-back.ts
• src/main/runtime/rpc/methods/orchestration/messaging/send-methods.ts
• src/main/runtime/structured-chat-worker-helpers.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.

📝 Walkthrough

Workers can start helpers on the same Run, with startup authorization tied to the active creator Dispatch. Helper questions and reports can route to that creator, and the creator can answer helper questions. Delivery updates now match both message IDs and mailbox handles. When a Dispatch settles, eligible helper messages move to the Run, with notifications handled after transaction completion or replay.

Priority: ➖ Normal

Merge Risk: ⚪ Minimal · up to 39cea

This change lets workers start helpers on their Run and hands unread helper mail back to the coordinator when they settle. No actionable merge-blocking risk is established from the supplied context.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 44.44% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 36 functions across 31 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Title check		The title "fix(orchestration): let a worker start helpers on the Run it works for" matches the main change: a dispatched worker can now start helper workers on its Run without creating a new Run or mo…
Description check		The pull request description is complete and follows the required template. It includes the problem, user-facing changes, mechanism, rationale, linked issue, visual proof, testing details, scope notes…

Full details: Title check

Explanation

The title "fix(orchestration): let a worker start helpers on the Run it works for" matches the main change: a dispatched worker can now start helper workers on its Run without creating a new Run or moving its inbox. The changeset implements worker-start authority (resolveWorkerStartRun, assertHelperStartScope), routes helper reports and questions to the creator dispatch, and adds hand-back on settlement. The title names the primary behavior change, but it omits the inbox-routing and hand-back parts. That is acceptable because a title need not cover every detail.

Full details: Description check

Explanation

The pull request description is complete and follows the required template. It includes the problem, user-facing changes, mechanism, rationale, linked issue, visual proof, testing details, scope notes, and checklist. The unchecked local command item is adequately covered by the reported CI results. The AI Disclosure and Review sections are empty, but they are not critical omissions for this check.

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments: 1

skill-guides/orchestration/references/worker-contract.md: 1

56-69: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Document the unresolved hand-back gap for helper questions.

Line 69 says a helper still running after you settle reports to the coordinator's Run. The PR comments report that an unanswered helper question moves to the Run mailbox without waking the coordinator. The helper can stay blocked.

The guide tells workers to wait for every helper's worker_done before settling. That rule limits the exposure. It does not remove it for stop or failure settlement. Fix the recovery defect in question-threads.ts. Until then, do not describe hand-back as reliable.

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: e8a83e09-a702-4f37-8365-a7cf77c936cc

📥 Commits

Reviewing files that changed from the base of the PR and between dd3bbf6 and 0523592.

📒 Files selected for processing: 36

• skill-guides/orchestration.md
• skill-guides/orchestration/references/coordinator-loop.md
• skill-guides/orchestration/references/messaging-and-gates.md
• skill-guides/orchestration/references/worker-contract.md
• src/cli/bundled-skill-guides.ts
• src/main/runtime/orca-runtime-test-orchestration-messages.spec.ts
• src/main/runtime/orchestration/db-message-timestamp.test.ts
• src/main/runtime/orchestration/db-messages.test.ts
• src/main/runtime/orchestration/db-undelivered-mailboxes.test.ts
• src/main/runtime/orchestration/db/messages/helper-mailbox-hand-back.ts
• src/main/runtime/orchestration/db/messages/message-inbox.ts
• src/main/runtime/orchestration/db/orchestration-db.ts
• src/main/runtime/orchestration/db/questions/question-threads.ts
• src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-start.ts
• src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-stop.ts
• src/main/runtime/orchestration/dispatch-report-mailbox.ts
• src/main/runtime/orchestration/mailbox-pointer-stage.ts
• src/main/runtime/orchestration/message-batch-atomicity.test.ts
• src/main/runtime/orchestration/preamble.test.ts
• src/main/runtime/orchestration/preamble.ts
• src/main/runtime/orchestration/structured-mailbox-pointer-delivery.test.ts
• src/main/runtime/orchestration/structured-mailbox-pointer-delivery.ts
• src/main/runtime/rpc/methods/orchestration/federation/federation.ts
• src/main/runtime/rpc/methods/orchestration/messaging/ask-methods.ts
• src/main/runtime/rpc/methods/orchestration/messaging/check.test.ts
• src/main/runtime/rpc/methods/orchestration/messaging/helper-question-answerer.ts
• src/main/runtime/rpc/methods/orchestration/messaging/message-methods.ts
• src/main/runtime/rpc/methods/orchestration/messaging/send-methods.ts
• src/main/runtime/rpc/methods/orchestration/messaging/send-point-to-point.ts
• src/main/runtime/rpc/methods/orchestration/worker/local-worker-start.ts
• src/main/runtime/rpc/methods/orchestration/worker/worker-start-authority.ts
• src/main/runtime/rpc/methods/orchestration/worker/worker-topology.ts
• src/main/runtime/rpc/methods/orchestration/worker/workers.ts
• src/main/runtime/structured-chat-worker-helpers.test.ts
• src/main/runtime/terminal/layout/terminal-resize-listeners.ts
• src/main/runtime/workspaces/persisted-surfaces/automation-operations.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.