[Other]: Orchestration loop roadmap — decisions, dependencies and acceptance

[Tauri-EPO]

Goal

A coordinator runs a multi-worker Task DAG (implement → review/gate → fix round) from durable Orca state, without routine heartbeats spending its turns, and every settled worker ends with an explicit owner or cleanup disposition. An idle turn, a process exit and a successful Task are three different facts. Loss of contact is unverifiable, never a death, and never permission to start a second editor.

Scope: Claude, Codex and Cursor workers; local Windows host; folder or git-worktree workspaces.

Reviewed 2026-10-02. upstream/main de8bffe240 · latest release v1.4.218 (2026-09-30); no v1.4.208 tag; tag v1.4.213 has no published release, its content first shipped in v1.4.214 · merged, in no tag: #23982, #23994, #23983, #23984.

The loop

Each gap in Uncovered ends with its state. [ready] has an anchor or a PR, listed under Ready to resolve. [D#] needs that decision. [waits …] needs a merge or a release. No tag means no owner yet.

Step	On main	Uncovered
1. Plan. Bind the Run; record Tasks, dependencies, ownership, placement, review/gate Tasks	Placement reference placement-and-remote.md (#16904, v1.4.199) · one launch-feasibility policy, no silent PTY downgrade (#19431, v1.4.200) · typed refusal codes with data.nextSteps (#18902, v1.4.198)	Review/gate Tasks exist only as guide advice, so an implementation report can pass for the objective
2. Start. One authoritative attempt; intended agent present; prompt receipt recorded	Prompt stages, --wait-submit, --retry-request (#16904, v1.4.199) · swallowed Enter reported, never resent (#14962, v1.4.187) · worker-start readiness on an observed turn start, else start_unknown with capability kept (#19423, v1.4.200) · custody row from terminal creation (#19608, v1.4.200) · preamble fenced (#18718, v1.4.198) · large pastes kept (#17718, v1.4.194) · foreground confirmed before downgrade (#18238, v1.4.196) · tui-idle evidence ranked: a name-only title needs quiescence, the agent's own idle report vetoes (#20155, v1.4.203) · launch prompt delivered by the host, not typed by the client (#21155, v1.4.207) · a typed request line ahead of the pasted brief, so Claude follows it (#22582, v1.4.214) · Codex readiness read from the live screen, its startup screen and dialogs waited out (#23475, #23765, v1.4.217; #23745, #23805, v1.4.218)	Hook-less provider gets ready on write acceptance while the paste sits unsubmitted; Cursor 2/2 on v1.4.199–200 (#14505, #17741); Cursor terminal send bypasses the render gate and the settlement allowlist (#20695) [ready] · a paste stopped before Enter revokes worker authority [ready] · a retry pastes onto the leftovers of the previous prompt (#15976) [ready] · unobserved turn-start receipt says the input was submitted, and the trailing Enter can be lost under load with no retry (#21445) [ready] · --retry-of without --worktree starts the retry in the coordinator's worktree (#21442) [ready] · worker-start reports failed/agent_readiness while setup.state is still running under wait-for-setup (#21512) · under wait-for-setup a Claude worker gets ready or turn_start_unobserved with an empty composer (#22649) · preamble re-injected in full on every dispatch (#20395) · terminal create --command never infers launchAgent (#17291) [ready] · prompt lands in a bare shell when the agent is absent (#17943) [ready] · failed Codex readiness respawns in a loop (#19768) · local RPC drops timeoutMs/signal (#19660)
3. Observe. Bounded fleet read plus durable mailbox events	worker-list with liveness/attention/nextAction (#16904) · pointers committed before wake, replayed after restart (#16904) · lineage across restart (#19121, v1.4.199) · federated mail under the Run (#19542) and unbound mail under run_unbound (#19696), v1.4.199 · structured-session status in worktree ps (#19217, v1.4.200) · @ groups scoped to the sender's Run (#19783, v1.4.201) · agent activity shown before the workspace is activated (#20398, v1.4.202) · delivery eligibility derived from unread messages, so an older heartbeat batch no longer hides a completion (#19837, v1.4.204) · worker-list newest first, a truncated page warned in the receipt (#21523, v1.4.207) · Dispatch mail and replies follow the lead's current Run (#23325, v1.4.217)	No heartbeat freshness on the row (#15951) [ready] · dispatch-show answers for another Run (#14898, #15952) [ready] · Run-mailbox mail invisible to inbox --terminal, delivered_at null until ack (#19844) [ready] · task-list --brief carries every completed result in full (#20701) [ready]
4. Decide. Continue, answer, inspect, notify, or wake an idle coordinator	Human waits on the row (#15261, v1.4.187) · finished_unverified + requiresAction (#16904) · pointer submitted while working (#17470, v1.4.195) · attempted Enter revalidated, not resent (#19911, v1.4.201) · a navigation Escape never retires a turn; only the provider hook does (#20149, v1.4.203) · delivery reads ranked idle evidence, so an idle→idle ready title reaches delivery and a silent pane can settle (#20578, v1.4.205) · an auto-reviewed Codex approval no longer reads as Needs You (#21389, v1.4.207) · worker results reach a structured-chat coordinator (#22631, v1.4.218)	Routine heartbeats wake the coordinator (#14910, #23890) [D3] · nothing wakes an idle coordinator with ready work (#15185) [D3] · pointer can land in a human draft (#14832, #11242, #18478, #22651) [D3] · pointer plus Enter answers a Claude AskUserQuestion because delivery reads only the title-derived idle, never the hook's waiting state (#21745) [D3] · send to a Dispatch blocked on ask succeeds without answering it, and no receipt points at reply --id (#21443) [ready] · no read-only wedged classification, no bounded nudge (#15273 → #14897) [D4] · Cursor pointer typed, never submitted (#19760) [ready]
5. Review and gate. Process a valid report, run the gate, hold context while a verdict is pending	worker_done/escalation validated against the exact process Orca started plus a caller-pane fence; the capability token is no longer minted or checked (#23982, #23994, unreleased) · a worker_done retried while the runtime is briefly unreachable (#23984, unreleased) · worker-retain --dispatch (#16904) · Task re-open under stopping refused (#19551, v1.4.199) · guide: outcome_unknown → inspect → worker-stop/worker-abandon	invalid capability rejects the escalation too (#15222, #13364) [waits release] · capability lost after the worker's context compacts, worker_done and heartbeats rejected (#20565) [waits release] · rejection never names the current Dispatch (#15972) [ready] · a valid worker_done sent during readiness confirmation gets rejected (#19737)
6. Account. Reuse, retain or release with ownership proof; reconcile the DAG; next wave	Ownership table, worker-release, failed-start receipt names the release command (#16904) · no resume fence, retention only via worker-retain (#19544, v1.4.199) · worker-stop re-issue on a stranded row (#19551) · release without web layout state (#16842, v1.4.192) · mobile takeover fences release (#19337, v1.4.200) · early takeover kept (#19608, v1.4.200) · a stale worker handle found again from the recorded process identity, so stop and release end the process (#23583, v1.4.217) · worker-abandon settles every unsettled worker and records who did it (#23983, unreleased)	A worker that exits while Orca is closed gets settled by a guess, over SSH by the client's copy of the listing [waits #19665] · worker-stop vs exit callback → dispatch_inactive (#19738) [waits #19665] · federated handle expires while the process lives [waits #19416] · release accepts a contradictory federated receipt (#19276) · child worktrees never removed (#18411) [ready] · hidden-worktree terminals dropped after restart (#15227) [ready] · no coordinator-side force release of a Dispatch that will never settle (#20566) [waits release] · worker-abandon leaves the agent alive and no orchestration verb closes it afterwards (#21441) [ready]

Ready to resolve

"mine" = Tauri-EPO.

Item	Step	Next action
#15951 → #15963 heartbeat freshness on worker-list (mine)	3	Rebased 2026-10-02; review
#20701 → #24845 task-list --brief completed results (mine)	3	Review; mergeable
#14898 + #15952 caller identity on dispatch-show	3	Small fix, no PR yet
#15972 name the current Dispatch in a lifecycle rejection	5	Small fix, no PR yet
#15313 orphaned state in text output	2	Small fix, no PR yet
#20695 Cursor terminal send outside the render gate (mine)	2	Fix scoped in the issue; no PR yet
#20532 keep authority after a partial paste	2	Rebase; conflicting
#17291 → #18020 infer launchAgent (mine)	2	Rewrite host-side so Settings defaults still apply; reproduce on v1.4.218 first
#17403 per-flag help (mine)	2	Rebased 2026-10-02; complements #24194
#17943 → #18069 refuse an unavailable agent	2	Review; mergeable
#19760 → #19761 Cursor pointer gets the delayed Enter	4	Rebase; conflicting
#19844 → #19890 inbox --terminal includes the Run mailbox	3	Rebase; conflicting
#18411 → #19404 child-worktree cleanup (docs)	6	Rebase; conflicting
#19161 check --peek/--all cannot drain (docs)	3	Review; mergeable
#19162 warn on a record-only dispatch	2	Rebase; conflicting; then evaluate against #14809 / #15945
#15227 → #15431 hidden-worktree terminals after restart	6	Retest on v1.4.218 (needs an app restart)
#21445 → #21453 unobserved input not reported as submitted	2	Review; mergeable; covers the receipt text, not the lost Enter
#21442 → #21454 refuse --retry-of without placement	2	Rebase; conflicting
#21443 → #21455 warn when send cannot answer a pending ask	4	Review; mergeable
#21441 → #21469 no worker-release hint after abandon	6	Review; mergeable; the abandoned agent still runs
#15976 → #24245 a retry does not paste onto composer leftovers	2	Review; mergeable
Retest on v1.4.218 (mine to run): #17741, #15920, #19737, #19768, #22649	2, 5	Fresh reproduction attempt

Needs a decision

Suggested answers are the map author's.

ID	Question	Suggested answer	Blocked items
D0	Support matrix and budgets	Start with the scope above; set response and wake budgets before the workflow check	none
D3	Which events wake the coordinator, and through which channel	A recorded heartbeat is state, not wake mail; questions, gates, rejections and Run quiescence discoverable by check; dedupe wakes. Merged so far in that direction: #19783, #19911, #19837 (eligibility from unread messages; a heartbeat still earns a pointer). Fourth channel proposed on this issue on 2026-09-11: deliver the wake through the provider's idle hook (Claude Stop) instead of typing a pointer, PTY pointer as fallback. Proposed on #14910 on 2026-09-19: close the heartbeat row where recordHeartbeat persists it, so no delivery lane types a pointer; not a type gate, since a rejected heartbeat keeps its type and must still surface	#15173 (mine, rebased 2026-10-02), #15185, #11279 (conflicting), #12953 phase 2, #14832, #16822 (#23424, conflicting), #21745 (#21880, conflicting), #22651, #23890
D4	Nudge	Read-only classification first; bounded reminders only after the input guard; a nudge never settles a Task. #19423 chose a loud outcome_unknown for the boot case	#15273, then #14897
D6	Missing worker_done	An explicit recovery/inspection obligation; exit, idle and commit presence never mean success	#19070, #15265

Decided

Question	Answer	Ruled out
D1 Receipt contract	#16904 (v1.4.199), #19423 (v1.4.200), #20155 (v1.4.203). Open corner: hook-less providers (#20695)	Resend Enter on a swallowed prompt (#18022) · readiness from a write receipt · a second verdict surface on terminal send (#15274, #18523) · per-resource reclaim commands on every receipt (#15949)
D2 Fleet read	worker-list (#16904)	Fleet echo from run mutations (#14891, #14892)
D7 Placement	#16904, #19431	Private placement ladder with PTY downgrade · custody backfill after a failed start (#19278 → #19608)
Pointer recovery	#19911 (v1.4.201)	Blanket-clear and resend staged pointers on PTY retirement (#19644)
D5 Gate retention	worker-retain --dispatch (#16904), resume fence removed (#19544)	Settled-worker resume fence (#17445, #17651) · a gate-hold policy beside it (#15641)
Worker report authority	#23982, #23994 (unreleased): the exact process Orca started plus a caller-pane fence	A capability token in the worker's prompt · re-injecting a preamble with a fresh capability (#21534) · authenticating by the capability alone (#22653)
Exit evidence	#19665 (open, maintainer, conflicting since 2026-09-10)	Second exit ledger plus probe RPC (#19347)

Waiting on a merge or release

Waits for	Items
Next release after v1.4.218	#23982 / #23994 → #15222, #13364, #20565; #23984 → #22156; #23983 → #20566
A turn-start signal for hook-less providers	The turnStart: unsupported → ready branch of #19423 (#14505)
#19665 (conflicting)	#19738, #13852
#19416 (draft)	Federated handle expiry
#19818 / #19815 (one conflicting)	Guide sequence as a blocking e2e; #19816 cross-version federation; #19817 shipped-schema DBs
Authors' remainder against main	#18196, #18208, #14900, #18042, #18156, #15265, #15272, #14751, #10020, #11048, #19937

Shipped

Release	Loop-relevant PRs
v1.4.218 (2026-09-30)	#23745 Codex startup screen and dialogs waited out · #23805 busy Codex 0.150–0.157 no longer tui-idle · #23933 setup-gated Codex launches without the shared server · #22568 / #22631 structured chat as coordinator
v1.4.217 (2026-09-29)	#23325 Dispatch mail follows the lead's current Run · #23475 / #23765 Codex readiness from the live screen · #23583 stale worker handles reaped by process identity
v1.4.214 (2026-09-26; carries the unpublished v1.4.213 tag)	#22582 typed request ahead of the pasted brief · #22555 one orchestration party per Orca session id
v1.4.207 (2026-09-22)	#21523 worker-list newest first, truncated page warned · #21389 auto-reviewed Codex approval not Needs You · #21097 sender-terminal refusal names the right handle · #21155 launch prompt delivered from the host
v1.4.206 (2026-09-20)	#20717 / #20718 canonical agent-status store and child-work contract · #20724 awaiting-input row for a question tool
v1.4.205 (2026-09-17)	#20578 ranked idle evidence reaches mailbox delivery, a silent pane can settle · #20664 registered pane key required for structured workers · #20716 legacy status ingress behind one admission point
v1.4.204 (2026-09-16)	#19837 delivery eligibility from unread messages · #20531 run-identity types for agent status rows · #20559 timed-out workspace hook reported unverifiable
v1.4.203 (2026-09-15; carries the unpublished v1.4.202 tag)	#20155 tui-idle evidence ranked · #20149 Escape never retires a turn · #20398 agent activity before activation · #20139 restart-stranded send decided against provider history
v1.4.201 (2026-09-13)	#19783 @ groups scoped to the Run · #19911 attempted Enter revalidated · #19749 agent-neutral startup-block reasons
v1.4.200 (2026-09-11)	#19423 readiness on observed turn start · #19431 launch feasibility · #19608 custody from creation · #19337 mobile takeover fence · #19217 structured status in worktree ps
v1.4.199 (2026-09-09)	#16904 durable workflows, guide, federation · #19121 lineage across restart · #19542 / #19696 / #19689 Run and unbound mail · #19551 re-open guard, stop re-issue · #19544 resume fence withdrawn · #19390
v1.4.198	#18902 typed refusal codes · #18718 preamble fence · #18683
v1.4.197	#17967 unverifiable process loss reported as lost
v1.4.196	#17487 invalid send types explained · #18238 foreground confirmed
v1.4.195	#17470 pointer while working · #16919 CLI recovery, guide defects
v1.4.194	#17718 large pastes · #16743 stripped task deps
v1.4.192	#16590 delivered prompts not stalled · #16300 slow worker-start · #16842 release without layout state
v1.4.191	#16419 / #16563 Windows PTY liveness
v1.4.190	#15569 adopted tui-idle recovery
v1.4.188	#14971 SSH execution boundary · #15304 · #15470 proven exit before retiring a lease · #15563
v1.4.187	#14961 · #14962 prompt submission verified · #14964 · #14706 · #15105 unsupervised lanes · #15235 · #15244 · #15261 human waits · #15351 · #15380 terminal read --screen
v1.4.186	#12988 mail pointers · #13717 · #14332 pointer retry
Unreleased	#23982 / #23994 worker reports without a capability token · #23983 worker-abandon settles and records who · #23984 worker_done retried through a short outage

Done when

• On a released build, within the scope above:
  • three independent workers, a dependent review gate and one fix round settle with every Task and worker accounted for;
  • a question and a page of heartbeats stay inside the wake budget;
  • a restart before acknowledgment recovers the same request with no duplicate worker or input;
  • a missing worker_done and idle-coordinator ready work each surface once;
  • nothing marks a Task successful on idle, exit or commit presence alone.
• Every decision above is resolved or explicitly deferred.
• Remaining limitations are documented on their own issues.

[innocarpe]

Acknowledged — treating this as tracking only, no extra work from the map.

#11279 remains the “delivery that interrupts a person” lane for #14832. It stays scoped to deferring mailbox-pointer / push-on-idle delivery while the focused window has typed in that PTY in the last 5s (plus the reservedTypes retry union and the 500ms Enter-skip reschedule). I am not taking any of the other links on this map.

[thomas-landry]

agent_prompt_stalled kills the Dispatch. Six seconds after dispatch it's failed with the capability revoked:

"id": "ctx_8e203c66db1d",
"capability_hash": "3203f9a6a744820995d0307342cd1f8e59c8e98c623a828c0567e1e001421e4a",
"capability_revoked_at": "2026-08-23 03:58:43",
"status": "failed",
"last_failure": "agent_prompt_stalled",
"dispatched_at": "2026-08-23 03:58:37",

macOS 15, v1.4.188, Grok, first dispatch --inject into a fresh agent. The verdict was wrong the way #15976 describes. terminal read --screen shows the preamble in the composer twice, and one bare Enter ran it fine.

So #15976 gets you the dead worker from #15222 on a first dispatch. No retry-of, nothing done wrong. I didn't test the rejection itself, only the revocation.

[nakedsleepwalker]

Tracking add: Grok on 1.4.190 still false-stalls and loses lifecycle (#16902). The injected worker preamble now tells agents to IGNORE dispatch_capability_invalid (#16903), so the supervised check --wait --types worker_done loop cannot close even when the work is done.

[electro56435]

D3: the wake can run on the harness hook Orca already installs

Measured on 1.4.200, macOS, local Run. Related to my #12536, whose residual became #12953 ("inject a pointer, not the payload").

Every wake option listed under D3 writes to the PTY. There is a fourth path that does not, and Orca already owns it.

Orca occupies the idle slot and returns nothing

Orca installs hooks on four Claude Code events: PermissionRequest, PreToolUse, Stop, UserPromptSubmit. The Stop entry dispatches to ~/.orca/agent-hooks/claude-hook.sh.

That script is 67 lines. Line 2 is:

printf "{}\n"

Unconditional, before it reads stdin. It then spools or POSTs the payload to http://127.0.0.1:${ORCA_AGENT_HOOK_PORT}/hook/claude and exits 0.

Stop fires at the exact moment a coordinator goes idle. That is the same moment mailbox-pointer-delivery.ts waits for. Orca is already there, and it answers with an empty decision.

The slot carries a payload today

A second Stop hook in the same settings array returns a decision with a reason. That text reaches the agent as a system block and starts a new turn. No line lands in the user's terminal, and no Enter is synthesized.

This removes both defects that block D3:

• No PTY write, so a pointer cannot land in a human draft ([Bug]: orchestration mail pointer still auto-submits into a prompt the user is typing in #14832, [Bug]: Orchestration push-on-idle delivery still clobbers in-progress user input, and auto-submits it when no coordinator run is registered (v1.4.159) #11242, Expose composer occupancy (recent human input / non-empty draft) and refuse agent prompts while a human is typing #18478).
• No synthesized Enter, so the guard in orca-runtime.ts stays intact.

Reproduction of the current behaviour

On 1.4.200, coordinator bound to a Run, one supervised Claude worker via worker-start. The worker sent a heartbeat with phase: reviewing. The coordinator was idle. Orca typed the pointer into the pane:

You have 1 orchestration message. Run `orca orchestration check --run run_xxxxxxxxxxxx`.

That reproduces #16822 on 1.4.200, filed against 1.4.184 with no comments.

Request

Add a fourth option to D3: deliver at the harness idle event through the existing agent-hook, with the pointer as fallback for a harness with no hook. The D3 suggested answer tunes how often the pointer fires. Hook delivery retires the pointer for every harness Orca already instruments.

The printf "{}\n" on line 2 of claude-hook.sh is the whole change surface for Claude Code.