[Bug]: worker-start --worktree new-child --agent injects the task before the agent TUI is ready, and settles it as success

[omarshibli]

Operating system

macOS

Orca version

1.4.177

Details

Short summary:
orca orchestration worker-start --worktree new-child --agent <x> writes the task prompt into the agent's PTY before the freshly launched agent TUI can accept a submit. The prompt lands in the composer but is never submitted, so the worker sits idle forever holding a fully typed prompt. The call returns ok: true with state: "ready" and stage: "input_accepted", so the coordinator believes the work started.

This is the same root cause as #13439, but it is not the same case, and the fix suggested there cannot be applied here:

• [Bug]:Orca pasted the preamble while Codex was still loading the MCP; the terminal recorded the text, but Codex did not submit it as a user message. #13439 reports it for Codex and attributes part of it to Codex CLI < 0.145.0. This reproduces with Claude Code, so a Codex-side fix does not cover it.
• The fix suggested in [Bug]:Orca pasted the preamble while Codex was still loading the MCP; the terminal recorded the text, but Codex did not submit it as a user message. #13439 is to call terminal create → terminal wait --for tui-idle → terminal send yourself. The composed worker-start --worktree new-child --agent path exposes no seam to insert that wait. There is no --wait-for-tui-idle flag, and the worktree, the agent launch, and the dispatch all happen inside one call.
• That composed path is what the orchestration guide presents as the Preferred Supervised Worker Loop, so following the guide produces silently stalled workers.

What happened?

Two workers were started ten seconds apart, each into a new child worktree, on a repo whose setup hook runs a package install:

04:38:31  orca orchestration worker-start --task <A> --worktree new-child --name <a> --agent claude --model opus --setup run
04:38:42  orca orchestration worker-start --task <B> --worktree new-child --name <b> --agent claude --model opus --setup run

Both returned success:

{ "state": "ready", "stage": "input_accepted", "timeoutMs": 60000,
  "setup": { "state": "running", "startupPolicy": "start-immediately" },
  "effects": [ { "kind": "worktree", "action": "created_child" },
               { "kind": "terminal", "role": "agent", "action": "reused_agent_terminal" } ] }

Both agents then sat at Context 0% with the entire prompt visible in the composer, unsubmitted. worker-show reported status: dispatched, state: ready, last_heartbeat_at: null for both. Nothing was lost or truncated — each worktree's agent session file shows the complete Orca preamble plus the task spec as a single user message. Only the submit was missing.

Sending one byte to each agent terminal started them immediately:

orca terminal send --terminal <agentHandle> --text "" --enter

Evidence that this is a startup race, not a size or content problem

1. The sessions began exactly when the manual Enter was sent, roughly 4.5 minutes after dispatch:

   worker	dispatched_at	first message in agent session	gap
   A	04:38:32	04:43:02.839	4m 30s
   B	04:38:42	04:43:38.053	4m 56s

2. dispatched_at is one second after the command was issued, so no readiness wait happened at all. An agent CLI cannot boot, load MCP servers and skills, and render a composer in one second.

3. Prompt size is not the variable. Scanning every Orca-dispatched worker session on this machine (82 sessions, identified by the injected preamble) shows prompts up to 12,635 characters / 217 lines that dispatched fine. The two failures were 8,363 and 9,998 characters, mid-range.

4. Natural experiment across those 82 dispatches: worker-start --worktree new-child --agent was used exactly twice — both in this incident, both failed. Every successful dispatch in the history used an explicit readiness gate:

   orca terminal create ... --command 'claude --model opus'
   orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000
   orca orchestration dispatch --task <t> --to <handle> --inject
   

   Prior worker-start uses were always bound to an already-idle existing terminal via --terminal <handle>, never to a newly created agent.

5. --model opus is not implicated: prior successful runs also launched claude --model opus, just behind the readiness gate.

Concurrent setup likely worsens the race but is not the mechanism. With --setup run and startupPolicy: start-immediately, setup ran in its own terminal and finished at 04:38:58 (A) and 04:39:25 (B), both after the injection, competing for CPU during agent boot.

How can we reproduce it?

1. Use a repo with a setup hook that takes tens of seconds (for example a package install) and an agent whose startup loads MCP servers.
2. orca orchestration run-create --objective "..." then orca orchestration task-create --spec "...".
3. orca orchestration worker-start --task <id> --worktree new-child --name <n> --agent claude --model opus --setup run --json.
4. Observe the receipt says state: ready, stage: input_accepted.
5. orca orchestration worker-read --dispatch <id> reports fallbackReason: "transcript_missing", and the terminal shows the whole prompt in the composer at Context 0%. No heartbeat ever arrives.

Suggested fix

1. Gate readiness inside worker-start when it launches a new agent: wait for tui-idle (or the agent's own session/turn-start event) before injecting, and then send the prompt and the submit together.
2. Fix the receipt semantics. stage: "input_accepted" currently means "bytes were written to the PTY", but the guide presents ready as the signal to proceed. Either report a distinct stage for "submitted and a turn started", or do not settle the call as success until a turn is observed.
3. On timeout, keep the prompt pending and report the failure rather than settling as ready. If text is already in the composer, retry only the submit, never the body — resending would create two user turns.
4. Until 1–3 land, either add a --wait-for-tui-idle style flag to worker-start, or change the guide's Preferred Supervised Worker Loop to the split form below, since the currently documented one-call form has no way to avoid the race.

Workaround

Split the composed call so the readiness gate can be inserted, and never trust input_accepted alone:

orca worktree create --name <n> --parent-worktree active --agent claude --model opus --setup run
orca terminal wait --terminal <agentHandle> --for tui-idle --timeout-ms 120000
orca orchestration worker-start --task <id> --terminal <agentHandle>

To verify a worker actually started, orca orchestration worker-read --dispatch <id> should report a real transcript (fallbackReason: null). transcript_missing plus Context 0% means the prompt is loaded but never ran.

[omarshibli]

Correction: the readiness gate does exist — I was wrong about the mechanism

I read the source after filing this, and one claim in the original report is wrong. Correcting it here so nobody chases the wrong lead.

Wrong: "no readiness wait happened at all" and "worker-start has no seam for a tui-idle wait."

worker-start does wait, and fails closed if the wait is not satisfied — src/main/runtime/rpc/methods/orchestration-workers.ts:197:

failedStage = 'agent_readiness'
const wait = await runtime.waitForTerminal(terminalHandle, {
  condition: 'tui-idle',
  timeoutMs: params.timeoutMs ?? 60_000
})

The observable symptoms in the original report still stand — the prompt sits unsubmitted in the composer, no heartbeat ever arrives, and the call settles as state: "ready". But the cause is different, more specific, and more fixable than "the wait is missing."

Code references are against 158212b8b3 (v1.4.178-rc.2).

The real mechanism — two independent defects

1. tui-idle is satisfied by the agent's first OSC title, not by input readiness

src/shared/agent-title-status.ts:178 treats a title of ✳ … as idle, and src/main/runtime/orca-runtime.ts:17434 resolves the waiter immediately when lastAgentStatus === 'idle'.

Claude Code emits that title as soon as its TUI paints — before MCP servers and skills finish loading. So the gate is satisfied about a second after spawn, which matches the observed dispatched_at being one second after the command was issued.

Note that the prompt-shape fallback isKnownReadyPromptPreview (orca-runtime.ts:36759 → findKnownReadyPromptIndex:36801) only covers Codex, Antigravity and Cursor. Claude has no prompt-shape corroboration, so the title is the only evidence, and it is emitted too early.

2. The submit is blind, open-loop and fixed-delay

src/main/runtime/orca-runtime.ts:17284–17318:

// bracketed paste, written in chunks
await new Promise((resolve) => setTimeout(resolve, AGENT_PROMPT_SUBMIT_DELAY_MS))  // 500 ms on macOS
const suffixWrote = this.ptyController?.write(ptyId, AGENT_PROMPT_SUBMIT) ?? false  // '\r'

There is no re-check before the \r and no confirmation after it. src/shared/agent-prompt-injection.ts:10 already documents this exact failure mode for another platform:

// Why: ConPTY renders long bracketed pastes more slowly; an early Enter leaves the task in the agent input buffer.

That is what happens here on macOS. TERMINAL_INPUT_CHUNK_MAX_BYTES is 16 KB (src/shared/terminal-input.ts:7), so a ~10 KB prompt is a single PTY write — the transfer is instant, but the agent's ingest and reflow of ~130 lines, while it is still loading MCP servers and while --setup run is installing packages in a sibling terminal, exceeds 500 ms. The \r lands mid-ingest and is swallowed. The body stays in the composer, exactly as the comment above predicts.

This also explains the size-independence noted in the original report: prompts of 12,635 characters dispatched fine on a warm agent, while 8,363 failed on a cold one. The variable is ingest time under load, not payload size.

git log src/shared/agent-prompt-injection.ts shows this has been patched open-loop before — #7758 "Fix orchestration agent prompt injection" introduced the delay, and Windows later needed 3× the macOS value. A larger constant narrows the window; it does not close it.

The asymmetry: a guarded send already exists, but orchestration does not use it

sendPromptWithGuardedPasteAndEnter in src/renderer/src/lib/active-agent-note-send.ts:167 does the right thing:

step	renderer (active-agent-note-send.ts:167)	orchestration (orca-runtime.ts:17273)
before paste	requireAgentStatus: 'sendable'	none
delay	50 ms (POST_PASTE_SUBMIT_DELAY_MS)	500 ms
before Enter	re-checks readiness, returns partial-submit-failed (:220–228)	none
Enter	sent with requireAgentStatus: 'sendable' (:243)	blind ptyController.write
outcome	distinct partial-submit-failed state	always accepted: true

The attended path, where a human would notice a stuck composer, is guarded. The unattended orchestration path, where nobody is watching, is blind — and it is the one that silently strands supervised workers.

Revised suggested fix

1. Reuse the guarded submit for orchestration (orca-runtime.ts:17273). Thread the terminal handle into writeTerminalAgentPrompt, re-check getTerminalAgentStatus after the paste delay, and only then write \r. Then confirm: poll briefly for the agent to leave idle. If it is still idle with the body in the composer, retry only the \r, never the body — resending the body creates two user turns. If it never registers, throw so worker-start fails at dispatch_input instead of settling ready.

2. Do not let a first idle title gate a newly created agent (orchestration-workers.ts:196). When Orca created the terminal in the same call (terminalOwnership: 'created'), require settled evidence — a hook-reported explicit status, or the idle title holding for a debounce window — instead of the first ✳. Terminals passed in with --terminal <handle>, which are already live, are unaffected.

3. Stop reporting unverified success. sendTerminalAgentPrompt counts AGENT_PROMPT_SUBMIT in bytesWritten (orca-runtime.ts:16715) although the submit is a separate, unverified write, and returns accepted: true unconditionally. Add a submitted flag, and a stage distinct from input_accepted, so ready means "a turn started" rather than "bytes reached the PTY".

4. Watchdog. monitorWorkerSetup already runs after dispatch. If no turn starts within a bounded window and the composer still holds the prompt, re-send a lone \r once and record it. This alone would have auto-recovered both stalled workers in this report.

5. Stopgap only: scale the delay by payload size and by whether the terminal was created in the same call. One line, but still open-loop.

Items 1 and 3 make the failure impossible rather than unlikely; the rest are defense in depth.

The workaround in the original report still holds, and now the reason is clear: creating the terminal first and waiting separately gives the agent seconds of extra boot time before the paste, which is why every historical dispatch that used the split form succeeded.

[AmethystLiang]

thanks for reporting. looking into it

[omarshibli]

Hey, i've attempted to fix it here #13637
Please review, let me if the direction valid and i can make follow ups as needed.

[AmethystLiang]

This is fixed on main via #14342 (fix(orchestration): wait for Claude composer render).

We usually ship a desktop/mobile release within 48 hours of a merge. This landed on 2026-08-13, so it should appear in the next release (or may already be out if that merge is more than ~48h old). Please update to the latest Orca and comment here if you still see it after updating.

The Claude inject path now waits for composer render + output quiescence before the single Enter, instead of treating a PTY write as input_accepted. Codex / MCP-boot races remain on #13439; Windows corroboration of the pre-fix Claude failure is on #13821.