fix(omp): publish genuine idle title at session startup

[nnnnoel]

ELI5

Orca waits until OMP is ready before giving it a task. The managed title extension previously announced readiness only after a turn finished, but a fresh worker had not received its first task yet. This change lets a genuinely idle startup announce readiness immediately, without treating busy or nested sessions as ready.

What Changed

• The generated session_start handler now receives the extension context and skips non-UI contexts and subagents.
• After existing timer/prompt cleanup, it reuses stopAnimation(ctx) to publish the existing rest title only when ctx.isIdle() positively reports idle.
• Behavior regressions execute generated extension code in the existing VM harness: idle root startup, OMP running with either omp or legacy pi generator kind, busy/sub/RPC exclusion, and subsequent start/end transitions.
• The managed extension identity and updater behavior remain unchanged. Existing inline lifecycle rationale explains why readiness must precede the first turn.

Why

Orca 1.4.219 with OMP 18.5.0 on macOS arm64 can still time out at agent_readiness before initial task delivery. Its installed positive idle-title path needs the managed rest title, while session_start previously only cleared state. Increasing the timeout cannot create a missing transition.

This fixes the producer rather than broadening readiness evidence or generating a fake completed turn. No readiness timeout, activity/completion status hook, process-exit semantics, model/thinking settings, or platform-specific path is changed. Missing isIdle support does not fabricate idle readiness.

Related history: #24068 and #24295. Open #24196 addresses broader status/readiness behavior but does not change these titlebar generator/test files; this PR stays at the missing managed title lifecycle boundary.

Linked Issue

Fixes #25052

Visual Proof

Before/after actual OMP 18.5.0 startup evidence (terminal title/automation behavior, no Electron layout change). Each session used the generated extension in an isolated CLI invocation, had no first user turn, and exited after a short startup probe. Both contexts were genuinely idle:

Before

STARTUP_PROBE {"kind":"main","hasUI":true,"idle":true}

No generated rest-title publication occurred before exit.

After

STARTUP_PROBE {"kind":"main","hasUI":true,"idle":true}
TITLE_PROBE {"title":"π - omp-startup-idle-title"}

Separately, the equivalent temporary local mitigation let an actual installed supervised worker reach ready / input_accepted in 6.36 seconds and execute real worktree commands. That confirms the reported installed failure path; it is not presented as an end-to-end test of an upstream Electron build.

Testing

• Agent-run local manual smoke with genuine OMP startup/session/UI APIs, before and after generated-source snapshots.
• Automated behavioral regressions added.

ORCA_BACKGROUND_LAUNCH=1 pnpm test src/main/pi/titlebar-extension-source.test.ts src/main/pi/titlebar-extension-service.test.ts
pnpm tc:node
pnpm exec oxlint src/main/pi/titlebar-extension-source.ts src/main/pi/titlebar-extension-source.test.ts

Results: 2 files / 88 tests passed, node typecheck passed, changed-file lint passed. Repository precommit oxlint/react-doctor/oxfmt checks also passed.

The isolated genuine startup smoke used:

env ORCA_PANE_KEY=startup-probe ORCA_BACKGROUND_LAUNCH=1 omp --no-session --no-extensions --no-skills --no-rules --no-tools --no-lsp --extension /tmp/orca-startup-title-before.ts
env ORCA_PANE_KEY=startup-probe ORCA_BACKGROUND_LAUNCH=1 omp --no-session --no-extensions --no-skills --no-rules --no-tools --no-lsp --extension /tmp/orca-startup-title-after.ts

Probe extensions were throwaway snapshots of generated code with startup-context/title logging and a 500ms exit timer; removed afterward. The installed extension and app were not changed by these runs. Unrelated existing MCP connection warnings appeared in both startups; no model request was made.

Exercised on macOS arm64. Windows/SSH, genuine concurrent subagent/RPC subprocesses, full Electron build, full repository suite, and a supervised launch against a rebuilt upstream app were not exercised; busy/sub/RPC boundaries were checked with generated-source execution. Existing session replacement, prompt cleanup, pending-end, settle, compaction, shutdown, and ownership regressions remain passing.

AI Disclosure

Implementation and coordination used OMP with openai-codex/gpt-6.1-sol, medium thinking. A separate read-only OMP worker reviewed correctness. No model/thinking overrides were supplied for these workers; no project-specific .omp directory exists in this checkout.

Review

Small generator lifecycle change; readiness safety guards and generated behavior tests are the primary review surface. The local user-owned workaround is intentionally not part of this PR and remains temporary until a release carrying the managed generator fix is installed.

Agent skill upstream boundary

• Not applicable: no upstream skill-installer source, registry, path table, fixture, or documentation is copied or translated.

Notes

No credentials, wire changes, new dependencies, or platform-specific code. Uses existing title-generation/painter behavior. No activity/completion report is emitted at startup.

Additional observed boundary: a separate installed supervised review worker returned ready / input_accepted, but its task remained in the composer as a collapsed draft after startup. An explicit extra Enter submitted that existing draft and started work. This proves that accepted input is not proof of a first turn; it does not distinguish early editor readiness from paste/Enter ordering. The independent review approves only the missing idle-title producer transition, not end-to-end first-prompt delivery. This PR does not claim to repair that submission boundary.

The published @oh-my-pi/pi-coding-agent@18.5.0 source package was also inspected: interactive-mode.ts installs key/submit handlers (2172–2173), starts/adopts the composer (2228–2235), marks initialized and renders (2273–2277), then initializes hooks (2339–2340); extension-ui-controller.ts emits session_start at321–324. Its prepaint lease enables input on adoption. This establishes source-level input setup before the hook, but does not provide a captured paste/Enter timing trace for that stalled draft. Exact-version package provenance: https://registry.npmjs.org/@oh-my-pi/pi-coding-agent/18.5.0.

Checklist

• This PR is small and focused
• I explained what changed and why
• Before/after actual terminal behavior captured above; no app layout change
• Self-reviewed for correctness, security, and performance
• Cross-platform and SSH/remote impact considered; unexercised platforms explicitly stated
• Full pnpm lint, pnpm typecheck, pnpm test, and pnpm build (CI to cover); targeted tests/node typecheck/lint passed locally

[pullfrog]

Important

The new startup π - <session> - <cwd> title is accepted by the tui-idle explicit-idle lane with no quiescence and without a trustworthy screen, while OMP's native startup π > title is deliberately held back. A first-run OMP setup wizard can therefore be bypassed. Detail inline.

Reviewed changes

• Startup idle title — session_start now reads the hook context, skips non-UI and subagent sessions, and calls stopAnimation(ctx) when ctx.isIdle() is true, so an idle root startup publishes the managed rest title before the first turn.
• Behavioral tests — the VM harness gained hasUI/agent.kind; a positive startup-idle test covers both omp and pi generator kinds and their agent_start/agent_end transitions, and a negative test pins the busy/sub/RPC exclusions.

The change is focused and the guard logic is correct: @oh-my-pi/pi-coding-agent@18.5.0's ExtensionContext does expose hasUI, isIdle(), and agent.kind (main/sub), and the managed extension is rewritten on every PTY spawn, so no updater change is needed. The one concern is how the readiness engine consumes the newly-published title.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

The new startup publication lands in the generic explicit-idle lane rather than OMP's guarded π > lane. The readiness engine accepts π - <session> - <cwd> with no quiescence and no screen requirement (readScreenInputVeto returning null does not veto), so a supervised first-run startup can settle on this title before or while the setup wizard opens and type the first task into it.

Technical details

# Startup `π -` title weakens the OMP setup-wizard guard

## Affected sites
- `src/main/pi/titlebar-extension-source.ts:258` — publishes the managed rest title at `session_start` when `ctx.isIdle()`.
- `src/main/runtime/tui-idle-evidence.ts:294` — `hasExplicitIdleTitle` returns READY_STRONG for `π -` with no age check.
- `src/main/runtime/tui-idle-evidence.ts:313-319` — the OMP-only `π >` lane that DOES require `TUI_IDLE_QUIESCENCE_MS` (3000ms) plus a screen read clear of the wizard.
- `src/main/runtime/terminal-wait-detection.ts:24-30` and `src/main/runtime/agent-state-rules/pi.json:5-11` — the `^π - ` anchor classifies the managed title as explicit idle.
- `src/main/runtime/screen-input-veto.ts:16-22` — the veto is `null` with no trustworthy screen, and `evaluateTuiIdle` only blocks on `true`.
- `src/main/runtime/omp-readiness-transcripts.test.ts:195-213` — asserts `π -` needs no screen because "A post-turn title cannot come from setup".

## Required outcome
- A startup `π -` title must not settle `tui-idle` before OMP's setup wizard can be ruled out. Either hold a `π -` title observed at `session_start` to the same age+screen requirement as `π >`, or establish with a captured transcript that the extension's `session_start` always runs after the wizard's alternate-screen paint.

## Suggested approach
- Add a readiness-level regression: a first-run `omp-18-setup` transcript with a startup `π - capture-cwd` and no trustworthy screen (`size: null`) must not settle; then make the fix satisfy it.

## Open questions for the human
- Does OMP 18.5.0 emit `session_start` only after the first-run wizard has painted the alternate screen on macOS? The readiness comments state OMP paints its idle title before the wizard, so the ordering is the crux.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

🧰 Additional context used

📚 Code guidelines (1)

AGENTS.md — auto-discovered

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: 250b6d9e-ac1e-4d91-ba5e-0bf3afdb03ab

📥 Commits

Reviewing files that changed from the base of the PR and between 1dc6157 and 8e880a0.

📒 Files selected for processing (2)

• src/main/pi/titlebar-extension-source.test.ts
• src/main/pi/titlebar-extension-source.ts

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

---

📝 Walkthrough

Walkthrough

The session-start handler now skips contexts with no UI or a subagent kind. For other contexts, it clears owned timers and resets prompt state. If the context reports that the agent is idle, the handler stops the title animation. New tests cover idle main UI startup, subsequent agent start and end events, and contexts that do not publish a startup title.

Priority: ➖ Normal

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 8e880

The change publishes the idle title for eligible sessions without a demonstrated regression. It is mergeable after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 8e880

Startup readiness remains conditional on confirmed idleness, with nested and non-interactive sessions excluded. No new access or privilege path was identified, but cleanup across changes in session context is not fully established.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The inspected change directly affects title publication through the existing session UI in an Orca pane. It adds no command execution, credential access, or capability grant in the changed handler. Broader consequences of downstream readiness consumption were not established by the supplied production evidence.

Trust Boundaries and Controls

• observed — Extension registration remains gated by ORCA_PANE_KEY. Startup additionally excludes contexts explicitly marked non-UI or subagent and requires positive idle evidence before publication. The new test harness fields simulate those contexts; they do not create production entrypoints or authority.

Resilience and Maintainability Implications

• observed — Existing controls retire a prior owner on replacement, suppress disposed handlers, and clear owned timers when title construction or writing fails. Settlement and shutdown retain their cleanup paths. These controls are counterevidence to unrestricted stale-owner publication, not proof that every context transition is covered.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: publishing the idle title at session startup.
Description check	✅ Passed	The description covers the required sections, links the issue, explains the change and rationale, and provides visual evidence and testing details. It also identifies untested areas and limitations.
Linked Issues check	✅ Passed	[#25052] The generated session_start handler now receives ctx, skips explicit no-UI and subagent contexts, and publishes the existing idle title only when ctx.isIdle() returns true. Added genera…
Out of Scope Changes check	✅ Passed	The changes are limited to the managed title-extension generator and its behavioral tests. Both changes directly support [#25052]. No unrelated change is present in the reviewed diff.

• Fix all pre-merge checks with AI

• Autopilot · 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.}