[innocarpe]

🧑‍🤝‍🧑 Impact & ELI5

1) What's broken today (ELI5).
Automation often does:

terminal create (Claude)
  → terminal wait --for tui-idle
  → orchestration dispatch --inject

When Claude is slow to start, tui-idle can say “ready!” after a few quiet seconds before Claude has published any agent-status signal. The inject call still returns injected: true (it only proves PTY write), but Claude never consumes the prompt. The worker sits empty until a human/coordinator re-sends.

This is a Claude recurrence of the class of readiness false-positives around #7748 / #7758, adjacent to Grok readiness reports, with incident evidence in #9976.

2) What this PR does (ELI5).
If Orca launched a known agent on that terminal (launchAgent set, e.g. Claude), we no longer treat “quiet non-shell process for 3s” as idle. We wait for real readiness signals: agent status, ready-prompt body evidence, or an explicit idle OSC title.

Anonymous/ad-hoc non-shell TUIs without launchAgent still use the old quiescence fallback (needed for agents that never publish status).

3) Tradeoffs / regressions — honest answer.

Concern	Assessment
Claude / Codex / Grok launched via --agent / launchAgent	Safer. Slow cold start no longer false-idles. Wait may take longer until first status/ready evidence (correct).
Ad-hoc createTerminal without launchAgent (e.g. bare codex command)	Unchanged — still allows quiet non-shell quiescence (existing test).
Already-idle agents with OSC idle / ready prompt	Unchanged — those paths resolve immediately as before.
Timeout for stuck agents	Callers already pass --timeout-ms; if Claude never starts, wait times out instead of lying with satisfied: true.

No CLI API change, no UI change.

---

Summary

Bug: Slow Claude startup lets terminal wait --for tui-idle succeed before the first agent-status signal; subsequent orchestration dispatch --inject acknowledges the write but Claude never sees the prompt (#9976).

Root cause: Fallback poll in waitForTerminal / start*TuiIdleFallbackPoll:

lastAgentStatus === null
  && foreground is non-shell
  && quiet for TUI_IDLE_QUIESCENCE_MS (~3s)
  → resolve tui-idle

Claude is non-shell and can be quiet during cold start while still not ready.

Fix: Gate that quiescence path on launchAgent == null:

• launchAgent set (Claude/Codex/… agent-first create) → do not idle on bare quiet; require status / ready prompt / explicit idle title.
• launchAgent unset → keep existing quiescence for title-less/ad-hoc agents.

Applies to both leaf and PTY fallback polls.

Fixes #9976

---

Evidence

Automated

pnpm exec vitest run --config config/vitest.config.ts \
  src/main/runtime/orca-runtime.test.ts \
  -t "quiet background PTY|launchAgent-backed"

3/3 passed

Test	Asserts
resolves tui-idle for quiet background PTY agents without OSC titles	Existing: no launchAgent, non-shell quiet → still idle (no regression)
does not resolve tui-idle via quiet non-shell foreground for launchAgent-backed terminals before status	New: launchAgent: 'claude', quiet startup → timeout
still resolves tui-idle for launchAgent-backed terminals once agent status is idle	New: Claude idle OSC (✳) → satisfied

Manual / incident mapping (#9976)

Observation	How this fix addresses it
First agent_start arrived after inject	Wait would no longer complete before status when launchAgent is set
Only 1 of 4 concurrent Claudes failed	Only that one crossed quiescence before status; others got signals in time
Later terminal send worked	TUI was eventually ready — readiness signal was late, not missing forever

Code map

Location	Change
startTuiIdleFallbackPoll	Skip quiescence when leaf’s PTY has launchAgent
startPtyTuiIdleFallbackPoll	Skip quiescence when pty.launchAgent set
orca-runtime.test.ts	Regression + positive control

---

ELI5

Orca used to assume “Claude process is running and quiet for a few seconds” means “ready for the next command.” Sometimes Claude was still waking up. Now, when Orca itself launched Claude as an agent, it waits for Claude to actually signal readiness instead of guessing from silence.

---

User-regression-tradeoffs

• Intended: longer waits / honest timeouts for agent-first Claude (etc.) cold starts instead of false success.
• Preserved: quiescence for non-agent-first / unknown TUIs without status.
• Orchestration scripts: should already use generous --timeout-ms; behavior becomes more correct, not weaker.

---

Checklist notes (CONTRIBUTING / AGENTS)

Area	Notes
Cross-platform	Runtime wait path only; no OS branches.
SSH / remote	Same PTY launchAgent + status model on remote hosts.
Agents	Any launchAgent-tagged create (Claude, Codex, Grok, …).
Git / providers	N/A
Performance	One map lookup for leaf PTY launchAgent; no extra IPC when skipping.
UI	None.
Security	None.
Tests	Regression + existing quiescence test still green.

---

Test plan

• Existing quiet-without-OSC test still passes
• launchAgent + quiet startup does not idle
• launchAgent + idle OSC does idle
• Optional multi-Claude orchestration smoke by reporter

---

Out of scope

• Changing inject to require “prompt consumed” (larger orchestration contract)
• Grok background-task HUD idle (terminal wait tui-idle reports success while Grok background task is still active #9905 / PR fix(runtime): do not treat Grok background tasks as tui-idle #9929) — complementary, separate
• Raising TUI_IDLE_QUIESCENCE_MS globally

---

AI code-review summary

1. Cross-platform — OK
2. SSH/remote — uses existing launchAgent on PTY records
3. Agents — gated on launchAgent; ad-hoc paths preserved
4. Performance — trivial
5. UI — N/A
6. Security — N/A
7. Correctness — false-positive readiness is worse than a timeout; tests lock both sides

---

Made for reliable multi-Claude orchestration 🐋

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 32de4bd4-f033-41ce-b3fe-25d9c5e3f304

📥 Commits

Reviewing files that changed from the base of the PR and between 0a0df3a6439a5eb45bbfdb861b1a4dff7ba01059 and b61a4266993855fefaeb32ecb742bcdf9435c8c7.

📒 Files selected for processing (1)

• src/main/runtime/orca-runtime.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/main/runtime/orca-runtime.test.ts

---

📝 Walkthrough

Walkthrough

Tightened tui-idle detection so launchAgent-backed terminals do not resolve as idle during cold start without agent-status evidence. Added tests for quiet startup timeout, delayed Claude trust-screen blocking, and successful resolution after an idle OSC title.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR fixes the readiness false-positive and adds tests, but does not address prompt confirmation, lease release, or telemetry required by [#9976].	Implement the remaining dispatch safeguards and correlated telemetry, or update [#9976] to record this PR as a partial fix.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the launchAgent cold-start tui-idle fix.
Description check	✅ Passed	The description explains the bug, fix, tests, tradeoffs, security, platform impact, and scope with sufficient detail.
Out of Scope Changes check	✅ Passed	The changes stay within the linked issue by updating runtime readiness guards and adding focused regression tests without unrelated UI or API work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

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.}

[innocarpe]

Sync update (0a0df3a643)

Follow-up for #9976: rebased onto upstream/main at 34f2a62 and added deterministic coverage for a Claude launchAgent cold start where the trust gate appears after the quiet period. The wait now reports the blocked trust prompt instead of being satisfied by generic quiescence. Validation: 1,079 runtime tests passed with 1 skipped; targeted launchAgent/trust-gate tests passed; oxlint and oxfmt passed. This keeps #10020 focused on the readiness race; Claude trust preflight remains a separate product decision.

• Commit: 0a0df3a6439a5eb45bbfdb861b1a4dff7ba01059
• Upstream: fix(runtime): skip tui-idle quiescence for launchAgent cold starts #10020
• Fork portfolio: [upstream #10020] fix(runtime): skip tui-idle quiescence for launchAgent cold starts innocarpe/orca#4

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 880893f1-9555-4823-8247-4add24811093

📥 Commits

Reviewing files that changed from the base of the PR and between 34f2a62 and 0a0df3a6439a5eb45bbfdb861b1a4dff7ba01059.

📒 Files selected for processing (2)

• src/main/runtime/orca-runtime.test.ts
• src/main/runtime/orca-runtime.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/main/runtime/orca-runtime.ts