[brennanb2025]

ELI5

If you created a worktree in the first moments after launching Orca (Claude as default agent, structured native chat on), you got a terminal-backed surface instead of the structured Claude Chat. The app hadn't yet asked the local runtime what it supports, and it treated "haven't asked yet" as "not supported". Now it asks at renderer boot, ungated, so the answer is already there by the time any launch route is decided.

Why

readLocalRuntimeCapabilitiesOrUnknown() returns null until something writes the module-level capability cache, and resolveStructuredNativeChatSupport maps null to blocker runtime-capability-unknown. A creation submitted in that window silently degrades from structured-native-chat to legacy-native-chat — a terminal-backed surface instead of the structured chat.

The root cause was never the readers. It was that the cache's only writer — refreshLocalRuntimeCapabilities() inside useLocalStructuredSessionTabsSync — sat behind workspaceSessionReady && terminalStartupRestorationReady && experimentalStructuredNativeChat. None of those has anything to do with what the local host can do. runtime:getStatus is a synchronous in-memory handler in main, registered before the window loads, so the answer was available from the first millisecond and was being withheld for seconds.

What Changed

One production change, plus the primitive it calls.

app-shell/use-app-startup-hydration.ts starts the capability probe ungated as the first statement of the renderer boot effect, before every await in the startup chain. That removes the mechanism rather than guarding it: the answer no longer depends on unrelated readiness flags, and every reader — including lib/agent-launch-route-input.ts, which main introduced as "the one place that gathers what a launch route decision needs" and which still reads the cache synchronously — now sees a populated cache.

runtime/local-runtime-capabilities.ts gains ensureLocalRuntimeCapabilities(): returns the cached set, or awaits the deduplicated probe when no answer has landed. The probe call is also wrapped so a missing/broken preload bridge rejects into the existing catch instead of throwing synchronously out of a non-async function, and setLocalRuntimeCapabilitiesForTests accepts null so tests can model the unprobed state. A failed probe still leaves the cache null (unknown), never [] (unsupported).

Note on scope after merging main

This branch originally also awaited the probe at four creation-flow call sites as a backstop. main has since centralised route-input construction into lib/agent-launch-route-input.ts, and the composer paths now delegate to a synchronous planAgentSessionLaunch. Those per-call-site awaits no longer have a call site to live in, so the merge drops them and takes main's shape; the four route tests this branch added were deleted with them, since they pinned resolution at sites that no longer resolve. main's own agent-launch-route-input.test.ts already covers the null capability case centrally. The boot probe is unaffected by that refactor and is what carries the fix.

Making the centralised path async instead would ripple through planAgentSessionLaunch into launchAgentInNewTab, which is synchronous with 11 production callers — not worth it when boot hydration already covers them.

Linked Issue

Refs #19154 — deliberately not a closing reference.

This PR fixes a real, separate defect: the launch-route degradation described in that issue's opening paragraph (a create in the first moments after launch degrades from structured-native-chat to legacy-native-chat, a terminal-backed surface instead of the structured chat). It does not fix the issue's headline defect, which is the one in its title and its "Why it happens" section: a structured Claude chat session that can never be closed, because eviction fails at stop-provider-child.

That defect is still live on main and is untouched here. Its chain, verified against current code:

• claude-child-exit-proof-ladder.ts:40 returns true only when input.exited() && tree.treeVerdict === 'exited'.
• The descendant snapshot is armed lazily, on the child's first stderr byte (claude-stream-json-connection.ts:146-161) — the SDK's stdout/message stream does not arm it.
• A session that dies before emitting stderr therefore latches treeVerdict: 'unverifiable' permanently (claude-agent-sdk-exit-proof.ts:121,143-148), which is pinned as intended by a currently-passing test.
• stop-provider-child then throws provider child exit was not proven on every retry (structured-agent-session-eviction.ts:47-59), producing the exact error string in the report.
• Nothing self-heals it: the unexpected-exit lifecycle is published only on a successful tree proof, the lease renewer's dead-owner branch is gated on runtimeKind: 'tui', and restart reconciliation is gated on unreconciled, which is false for a record admitted in-process.

The root cause there is that eviction conflates unverifiable ("we could not find out") with proven-live. agent-session-acquisition-failure-settlement.ts:17-20 already models the correct third answer for the sibling acquisition path — root exit observed first-hand, descendants not verifiable — so the fix is a consistency fix against existing architecture, and it is main-process only. Tracked as separate follow-up work.

Correction to an earlier note in this body: PR #19155 did target that headline defect, not "the wrong bug". Closing it was still the right call — it failed its own rendered-Electron QA and its store-only lease-renewer commit introduced an unclosable tab that plain main did not have — but its eviction and close-verdict commits are the right shape and should be salvaged rather than lost.

Testing

pnpm tc clean. Bare oxlint exit 0. pnpm run check:code-quality:changed: 0 findings across 4 changed files (code quality, casting, type-aware, React Doctor, casting-safety). Targeted sweep at the merged head: 6 files / 95 tests passed (app-startup-routing, local-runtime-capabilities, agent-launch-route-input, agent-session-launch-plan, folder-workspace-composer-submit, full-creation-execution).

Ablation, re-proven at the merged head. Removing the single boot-probe line fails exactly one test — app-startup-routing.test.ts "probes local runtime capabilities before any startup gate can hold the answer back" (1 failed | 26 passed) — and restoring it returns 27 passed. The pin is position-sensitive, not merely presence-sensitive: moving the call inside the effect's void (async () => { chain also reddens it.

Note the pin is a source-order ratchet, the established pattern for this file (no test in the repo renders useAppStartupHydration). It catches deletion and repositioning; it does not execute the effect.

Visual Proof

Rendered Electron QA on an isolated dev instance, hidden renderer over CDP, settings matching the incident report. Measured in the running app, varying only hostCapabilities: probed list (74 caps, includes agent-session.structured.v1) → structured-native-chat; null → legacy-native-chat; [] → legacy-native-chat.

Cold reload under 12x CPU throttling, sampling in-page — the capability cache is populated 13.9s in, while workspaceSessionReady lands at 28.3s and terminalStartupRestorationReady at 29.8s. The cache beats the gates by ~15.9s; before this change those gates were the only trigger for its sole writer, so every create in that window resolved against null.

A cold create driven through the real create-worktree dialog with both gates verifiably false at submit landed on activeTabType: "agent-session" — Claude Chat focused, Setup beside it and unfocused.

Full runs, screenshots and limitations are in the PR comments.

Not validated

• No ablation against main in the live Electron rig — that would mean editing production source in the checkout under test. The pre-fix populate time is inferred from the code (the tabs-sync is the only other writer, gated behind those same flags), not measured.

• The rendered-Electron evidence was captured at 0b11f4d257, before this merge. The merge changes which files carry the fix but not the boot probe itself, which is byte-identical; it is not a re-measurement.

• Renderer reload gives a fresh renderer JS context with a warm main process, so true first-launch main-process latency is not modelled.

• Windows/Linux/SSH unexercised. The change is renderer-only and host-agnostic; remote creates short-circuit on remote-execution-host before the capability check.

• I manually tested these changes locally

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

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

Renderer-only; no IPC or wire shape change; runtime:getStatus is an existing local channel. Performance: one extra local IPC per renderer boot to a synchronous in-memory handler, deduplicated across StrictMode's double effect invoke onto a single in-flight promise. No polling, no per-render IPC.

Checklist

• This PR is small and focused
• I explained what changed and why (including ELI5)

[pullfrog]

✅ No new issues found.

Reviewed changes

• ensureLocalRuntimeCapabilities() — new async reader in local-runtime-capabilities.ts that returns the cached capability set or awaits the deduplicated probe when no answer has landed, returning null only after a genuinely failed probe.
• Probe starts inside the promise chain — refreshLocalRuntimeCapabilities now kicks off getStatus() one microtask in, so a broken preload bridge rejects into the existing catch rather than throwing synchronously out of the ??= expression.
• Three creation-submit call sites await the probe — quick-creation-execution.ts, full-creation-execution.ts, and folder-workspace-composer-submit.ts pass await ensureLocalRuntimeCapabilities() instead of the possibly-null synchronous read; QuickCreationExecutionInput is exported for the new test.
• Tests — route-before-hydration tests for all three submit paths plus ensureLocalRuntimeCapabilities unit tests, with null support added to setLocalRuntimeCapabilitiesForTests.

The concurrency model checks out: the probe dedupes through refreshPromise, remote/WSL/SSH launches still short-circuit on remote-execution-host before the capability answer matters, and a failed probe degrades to legacy exactly as before. The tests assert concrete route values (structured-native-chat / legacy-native-chat) and providesInitialSurface, so they fail if the await is reverted.

ℹ️ Remaining pre-hydration readers stay unchanged

The four other readLocalRuntimeCapabilitiesOrUnknown() call sites — launch-agent-in-new-tab, launch-work-item-direct-route-preparation, onboarding-folder-agent-startup, and ai-vault-session-resume-in-chat-workspace — keep the same latent unknown-window behavior. That's a defensible scope line since none is the worktree-creation defect from #19154, but it may be worth a follow-up issue to confirm none of them can be triggered pre-hydration in practice.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: ec91d3d6-89e1-4de6-aa37-da97aefff7f1

📥 Commits

Reviewing files that changed from the base of the PR and between 5655523 and ad75db7.

📒 Files selected for processing (2)

• src/renderer/src/hooks/composer-state/full-creation-execution.test.ts
• src/renderer/src/hooks/composer-state/quick-creation-execution.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

Agent creation flows now await ensureLocalRuntimeCapabilities() before selecting a launch route. The runtime module probes the host when no cached result exists, preserves null after probe failure, and copies test values defensively. Folder-workspace, full-creation, quick-creation, and direct work-item flows use the ensured result. Tests cover structured and legacy route selection, runtime probing, initial surface activation, cancellation during probing, direct launch preparation, and structured-launch settlement.

Merge Risk: ⚪ Minimal · up to ad75d

Creation flows now wait for local runtime capabilities before choosing structured chat or the legacy terminal route, preventing early launches from incorrectly falling back while preserving fallback behavior when probing fails. The current change is ready to merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise, specific, and accurately describes the primary change: waiting for runtime capability hydration before resolving the creation launch route.
Description check	✅ Passed	The description is mostly complete and covers the ELI5 summary, changes, rationale, linked issue, visual proof, testing, platform limitations, notes, and checklist items. It omits explicit Review and …

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

---

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: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 04a77ec2-b815-45e7-81af-418a8cea55df

📥 Commits

Reviewing files that changed from the base of the PR and between aac38d6 and 6189409.

📒 Files selected for processing (8)

• src/renderer/src/components/sidebar/folder-workspace-composer-submit-launch-route.test.ts
• src/renderer/src/components/sidebar/folder-workspace-composer-submit.ts
• src/renderer/src/hooks/composer-state/full-creation-execution.test.ts
• src/renderer/src/hooks/composer-state/full-creation-execution.ts
• src/renderer/src/hooks/composer-state/quick-creation-execution.test.ts
• src/renderer/src/hooks/composer-state/quick-creation-execution.ts
• src/renderer/src/runtime/local-runtime-capabilities.test.ts
• src/renderer/src/runtime/local-runtime-capabilities.ts

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

[coderabbitai]

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Guard cancellation after capability hydration. NewWorkspaceComposerModal.handleDismiss marks the submission cancelled, but submitFolderWorkspaceCreate does not recheck that state after await ensureLocalRuntimeCapabilities(). A dismissal while window.api.runtime.getStatus() is pending can therefore continue through route resolution, createFolderWorkspace, and workspace launch. Pass the cancellation predicate into this helper and return through a cancellation result immediately after the await. Ensure the orchestration layer does not report that cancellation as a creation failure.

[brennanb2025]

Review status

Full review loop completed at fabcf84a84 (independent same-model review pass, start/end readiness checklists, precedent check). Verdict: PASS — ready pending the Electron UI validation pass.

What the review confirmed

• Root cause and mechanism: launch-route decisions read a module-local capability cache whose population was gated behind workspaceSessionReady && terminalStartupRestorationReady, so a pre-hydration create read "not asked yet" as "unsupported" and silently degraded to legacy. For the async creation flows the change removes that mechanism (they await the single-flight probe and can no longer observe "not asked yet"); a genuinely failed probe still degrades to legacy, which is the right failure posture.
• The design is the standard shape for this problem: an ensure-style async accessor over a deduplicated cached-promise probe, awaited at the decision site, with the in-flight promise dropped after settling so a transient failure retries on the next decision instead of being cached forever. The probe is one IPC round-trip to a synchronous main-process handler, so the new awaits cannot hang beyond IPC itself; on a warm renderer they are a no-op microtask.
• No new reentrancy: all three composer submit paths already had real awaits before route resolution, and the folder submit is guarded by its orchestration's creating flag. Nothing read after the new awaits is re-read store state.
• Concurrency in local-runtime-capabilities.ts is sound (shared in-flight promise for concurrent creates; finally reset; broken-bridge sync throw now rejects into the existing degrade path).

Added during review (fabcf84a84): the work-item direct launch (lib/launch-work-item-direct-route-preparation.ts) is the fourth creation-flow route owner and already async, so it now awaits the probe too, with its own route-before-hydration test. It was live only for submit-after-ready (fix-checks) launches — draft-delivery launches hit the draft-prompt blocker before the capability check.

Validation

• 6 test files (the 4 touched + agent-launch-routing.test.ts + caller census): 34 passed, plus the new work-item test.
• Ablations at the final head: with each call site reverted alone, its route-before-hydration test fails on the behavioral assertion (route degrades / probe never fires) and passes restored; same for the new work-item test.
• pnpm tc clean; changed-code quality gate 0 findings (incl. type-aware + React Doctor); lockfile untouched.

Remaining gaps / follow-up

• The module still exposes sync capability readers for launch funnels that cannot await (launch-agent-in-new-tab.ts:216, onboarding-folder-agent-startup.ts:138, ai-vault-session-resume-in-chat-workspace.ts:52). Their pre-hydration consequence is a legacy chat in an existing workspace or a briefly hidden affordance — not the creation-flow bare-terminal defect — and converting those funnels to async is the durable fix for the residual window. Tracked as follow-up on Structured Claude chat session can never be closed: eviction fails at stop-provider-child #19154; an eager startup warm probe was considered and deliberately left out of this PR (it shrinks that window but doesn't remove it, and adds an untested startup behavior change).
• Live Electron UI validation pass is queued separately; true cold-app-launch end-to-end and Windows/Linux/SSH remain unexercised (renderer-only, host-agnostic change; remote hosts short-circuit before the capability check).

[pullfrog]

✅ No new issues found.

Reviewed changes

• Work-item direct launch route now awaits the probe — prepareDirectWorkItemAgentLaunch passes await ensureLocalRuntimeCapabilities() instead of the possibly-null synchronous read, closing the fourth creation-flow route owner called out in the prior review.
• New route-before-hydration test — launch-work-item-direct-route-preparation.test.ts asserts getStatus is probed and structuredLaunch resolves true; reverting the await makes both assertions fail, so it's real coverage rather than theatre.

The test mocks getExecutionHostIdForWorktree to 'local' (necessary because the call site resolves it directly from a minimal store) and exercises the real resolveAgentLaunchRoute, and submit-after-ready correctly skips the draft-prompt blocker that would short-circuit the capability check. The three remaining sync readers stay unchanged as documented follow-ups on #19154.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

ℹ️ No blocking issues — one minor comment inline about a now-stale test comment.

Reviewed changes

• Probe starts synchronously again — refreshLocalRuntimeCapabilities now dispatches getStatus() through a new startLocalRuntimeCapabilityProbe() helper that calls the bridge synchronously and converts a broken-bridge throw into a rejection, replacing the microtask-deferred start so callers that overlap the probe with their own RPC see it in flight on return.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[brennanb2025]

Rendered Electron QA — true cold launches

Tested the current PR head 0b9aa09e8bc4d4b72234b49e9d729312aab501e6 (including the synchronous probe-initiation follow-up) with a fresh Electron process for each cold run. The dev instance used task-owned profiles under /tmp/orca-qa-19819-*-t97, renderer 127.0.0.1:5241, CDP 127.0.0.1:9401, and ORCA_BACKGROUND_LAUNCH=1; before trusting the captures I observed that the attached CDP target URL, app identity, and store repo/worktree belonged to this checkout and the task-owned test repo.

The profile matched the incident settings: Claude default agent, native chat + open-in-chat + structured native chat enabled, Claude args --dangerously-skip-permissions, setup launch mode new-tab, and a committed setup script. Each creation was exercised through the real create-worktree dialog as soon as the UI permitted, without reloads or CPU throttling. Times below are milliseconds from the Create click; “record” is first appearance in that run's agent-sessions/agent-sessions.json.

Run	Capability cache at click	Resolved route / ms	Record	Setup tab	Structured tab	Chat focused	Completed surface	Persistent bare terminal seeded / focused
Cold 1 (shakedown)	loaded	structured-native-chat / 22	not observed¹	not instrumented	2147	2150	2299	not instrumented
Cold 2 (shakedown)	not observed²	structured-native-chat / 13	783	not instrumented	1724	1729	1950	not instrumented
Cold 3	loaded	structured-native-chat / 11	317	272	801	804	945	no / no
Cold 4	loaded	structured-native-chat / 9	297	255	753	755	896	no / no
Cold 5	loaded	structured-native-chat / 11	415	344	902	904	994	no / no
Cold 6	loaded	structured-native-chat / 27	702	597	1590	1595	1811	no / no
Cold 7	loaded	structured-native-chat / 10	637	510	1659	1664	1885	no / no
Warm control	loaded	structured-native-chat / 7	310	241	710	713	777	no / no

¹ The first shakedown's record watcher targeted the wrong profile path, so record appearance was not observed.
² The second shakedown's cache observer errored while summarizing the returned non-null array, so cache state is unobserved for that run.

What I observed

• In all five fully instrumented cold launches and the warm control, pendingWorktreeCreations resolved agentLaunchRoute to structured-native-chat.
• Their first focused post-creation surface was Claude Chat. The only terminal seeded was the separately named, unfocused Setup tab; there was no persistent bare terminal and no terminal ever took focus.
• The committed setup command completed in each of the five fully instrumented cold profiles, confirmed by the orca-qa-19819-setup-complete marker in its terminal-history checkpoint.
• All five fully instrumented cold runs had 74 runtime capabilities, including agent-session.structured.v1, already loaded at the Create click. Therefore 0/5 attempts landed inside the pre-hydration window. I did not observe the awaited-probe path directly and am not inferring its behavior from these runs.
• No cold launch degraded to legacy-native-chat.

Result: the true-cold pass condition was observed on every fully instrumented attempt—structured-native-chat, Claude Chat initially focused, and no focused bare terminal—with the important limitation that the UI was not usable quickly enough to catch a pre-hydration capability cache.

Cold launch (Claude Chat focused, Setup separate and unfocused)

Warm control

[pullfrog]

✅ No new issues found.

Reviewed changes

• Boot-time capability hydration — use-app-startup-hydration.ts now calls void ensureLocalRuntimeCapabilities() ungated at the top of the boot effect, so the local capability answer is normally cached before any launch route resolves — including the three synchronous readers that cannot await.
• Cancel-recheck in the full-create route — full-creation-execution.ts hoists the probe into const hostCapabilities before the cancel gate and re-checks isSubmissionCancelled() after the await, closing the gap where a cancelled submit could proceed past the awaited probe.
• Source-order regression test — app-startup-routing.test.ts pins the probe ahead of the boot chain and outside its gates, matching the existing readSource ordering-test convention in that file.
• Unit-test cleanup and coverage — local-runtime-capabilities.test.ts drops the stale microtask-yield comment (prior feedback) and adds re-probe-after-failure, missing-bridge, and concurrent-caller-coalescing cases for ensureLocalRuntimeCapabilities.

The boot-time probe is sound: ensureLocalRuntimeCapabilities never rejects (the probe's failure is swallowed into null inside refreshLocalRuntimeCapabilities), it starts the getStatus() IPC synchronously on invocation, and it dedupes against the structured-session-tabs sync through refreshPromise — so StrictMode remounts and a racing hydration sync don't double-probe.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

• Cancel-gate regression tests — full-creation-execution.test.ts and quick-creation-execution.test.ts each gain a "does not create when the composer is dismissed while the probe is still pending" test that holds the getStatus probe open on a deferred promise, flips isSubmissionCancelled() mid-probe, then asserts no worktree is created. quick-creation-execution.test.ts also gains a local deferred<T>() helper to drive it.

Both tests are real coverage, not theatre. The full-create test targets the hoisted const hostCapabilities / post-await re-check in full-creation-execution.ts:136-139, and the quick-create test targets the existing cancel gate at quick-creation-execution.ts:264 that sits after the await ensureLocalRuntimeCapabilities() at line 208 — removing either gate makes the corresponding createWorktree / runBackgroundWorktreeCreation assertion fail. Verified both files pass locally (6 tests), matching the ablation table in the PR body.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

• Folder-create cancel window closed — folder-submit-orchestration.ts now awaits ensureLocalRuntimeCapabilities() into hostCapabilities above its isSubmissionCancelled() gate, so a composer dismissal during the probe returns before createFolderWorkspace can run. This resolves the CodeRabbit concern about submitFolderWorkspaceCreate rechecking cancellation after hydration.
• Pre-resolved capabilities threaded through — submitFolderWorkspaceCreate gains an optional hostCapabilities param; it awaits the probe only when the param is omitted (undefined vs null correctly distinguishes "not provided" from "probe failed → unknown"). The single production caller passes the hoisted value, so no suspension remains between the gate and createFolderWorkspace.
• Coverage — new folder-submit-orchestration.test.ts (dismiss-during-probe, plus capability pass-through) and a "uses pre-resolved capabilities without probing again" case in folder-workspace-composer-submit-launch-route.test.ts. All 4 new/changed tests pass, and the dismiss test holds the probe open on a deferred promise, so it fails if the gate is removed.

The hoist restores the invariant that nothing awaits between the final cancel check and workspace creation, and the null/undefined split keeps the degraded legacy route correct after a genuinely failed probe.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

• hostCapabilities made required on submitFolderWorkspaceCreate — the optional parameter and its inline await ensureLocalRuntimeCapabilities() fallback are removed, so the function now runs straight through to createFolderWorkspace with no suspension of its own, and the type forces a caller that gates on cancellation to resolve capabilities above its gate. The single production caller in folder-submit-orchestration.ts already passes the hoisted value.
• Launch-route test reframed around pre-resolved capabilities — the folder launch-route test now pins the "degrades to legacy when the handed-in capabilities are unknown" contract (the bridge holds the structured capability, so only the handed-in null can produce the legacy outcome) and the "uses pre-resolved capabilities without probing again" contract, both asserted via getStatus not being called.
• Non-route call-site tests hand in null explicitly — folder-workspace-composer-submit.test.ts routes through a submitWithUnknownCapabilities helper, matching the prior behavior where the unset bridge made the inline probe resolve to null anyway.

The required-param contract is a clean close of the footgun the optional fallback left open: a future caller without a cancel gate can no longer silently re-probe inline and reopen the window the folder hoist had just closed. Verified the three changed test files (28 tests) and pnpm tc pass against this head.

ℹ️ PR body now overstates the folder parameter

The "What Changed" section still describes hostCapabilities as optional ("a caller without a cancel gate keeps the inline probe"). This commit makes it required and deletes the inline probe, so that sentence is stale and worth a one-line edit before merge.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[brennanb2025]

Rendered Electron UI validation (macOS) — cold-window create

Tested SHA f4920644321608c8420749db1ea7ecf8c172fd79 (this PR's head). Isolated dev instance, own fresh user-data profile, ORCA_BACKGROUND_LAUNCH=1, driven entirely over CDP/Playwright against a hidden renderer. Settings per the bug report: defaultTuiAgent=claude, experimentalNativeChat, openAgentTabsInChatByDefault, experimentalStructuredNativeChat all on, agentDefaultArgs.claude=--dangerously-skip-permissions, setupScriptLaunchMode=new-tab, against a fixture repo with a committed orca.yaml setup script.

The cold window was reproduced by reloading the renderer under CDP CPU throttling and driving the real "New workspace" composer entirely in-page (a CDP round trip under throttle is seconds wide and would push the submit past the gates). An in-page recorder installed via addInitScript samples the gate state, so the pre-hydration claim does not depend on screenshot timing.

Mechanism, measured live in the running renderer

Calling the app's own resolveAgentLaunchRoute with this profile's real settings, varying only hostCapabilities:

hostCapabilities	resolved agentLaunchRoute
probed list (74 caps)	structured-native-chat
null ("not asked yet")	legacy-native-chat
[]	legacy-native-chat

So null does degrade the route. Note for the description: under these settings the degraded route is legacy-native-chat (terminal-backed chat), not terminal-tui.

Cold-window passes (submit landed with both hydration gates false)

run	throttle	in-page timeline at submit	outcome
coldB	12x	caps +8.1s, create clicked +18.2s, workspaceSessionReady=false, terminalStartupRestorationReady=false	active tab contentType: agent-session, label Claude Chat
coldC	16x	caps +20.9s, create clicked +41.9s, both gates false	active tab agent-session, Claude Chat
coldD	16x	caps +12.3s, create clicked +22.1s, both gates false	active tab agent-session, Claude Chat

Cold pass (coldB, 12x): worktree created with the submit recorded at workspaceSessionReady=false / terminalStartupRestorationReady=false — the focused tab is the structured Claude Chat surface, not a terminal.

Cold pass (coldC, 16x): second independent cold-window create, same result — structured Claude Chat tab focused.

Cold pass (coldB): frame captured while the create was in flight during early boot — sidebar shows "coldB — Creating worktree…" with no tabs mounted yet.

Awaited backstop

before-caps could not be reached: the ungated boot probe cached capabilities before the composer had even rendered on every attempt, which is the fix working as intended. To exercise the backstop anyway, the renderer cache was forced back to null through the module's own setLocalRuntimeCapabilitiesForTests(null) hook and a normal create was driven with hostCapabilities verified null at click time. The awaited ensureLocalRuntimeCapabilities() re-probed and the create still routed to structured chat.

Backstop: cached capabilities forced to null immediately before submit — the create still lands on the structured Claude Chat tab.

Warm sanity pass

Warm pass (warmE, no throttle): both hydration gates true at submit (+2.1s), structured Claude Chat tab focused. Ordinary path unaffected. Two further unthrottled-at-submit creates (coldF, coldG) behaved identically.

Gaps

• No ablation against main. This run only shows the branch behaving correctly; it does not directly film the old failure, since that would have meant modifying production source. The resolveAgentLaunchRoute table above is the closest live evidence of the mechanism.
• No screenshot is captured provably inside the pre-hydration window. Under CPU throttling a CDP screenshot takes long enough that the gates flip during the capture, so the pre-hydration evidence is the in-page recorded timeline rather than the image. The images show the resulting tab.
• Renderer-only cold boot: the reload gives the renderer a fresh JS context while the main process stays warm, so the real first-launch main-process latency is not modelled.

[brennanb2025]

Review session status — 5 review loops + rendered Electron validation

Final head 0b11f4d257. Gates green at that SHA: pnpm tc exit 0, bare oxlint exit 0, check:code-quality:changed 0 findings across 15 files (code quality, type-aware, React Doctor), touched-file tests 8 files / 73 passed. CI verified per-SHA rather than via a bare "0 pending": 17 ran and succeeded, 11 correctly change-detection skipped, 0 pending, 0 mismatched head_sha. MERGEABLE / CLEAN; 8 behind main with zero file overlap against main's 8 commits.

The approach was superseded, not just reviewed

The PR originally awaited a lazy capability probe at four creation-flow call sites. That was a per-call-site guard, not a fix: the cache's only writer sat behind workspaceSessionReady && terminalStartupRestorationReady && experimentalStructuredNativeChat, none of which has anything to do with what the local host can do — and runtime:getStatus is a synchronous in-memory main handler registered before the window loads, so the answer was available from the first millisecond and was being withheld for seconds. Three of the seven readers are synchronous and could never adopt the guard.

The fix now starts the probe ungated at renderer boot, which collapses the unknown window for all seven readers. The four awaits remain as a narrow backstop.

Two defects found during review, both fixed

Inserting an await between a cancel gate and an irreversible side effect. Found on the git-worktree path, fixed, then found still open on the folder path — which this PR body had itself asserted was "the same defect" without anyone checking. At main, submitFolderWorkspaceCreate ran straight from its caller's isSubmissionCancelled() gate to createFolderWorkspace with no suspension of its own; the inline probe inserted a full IPC round-trip in between, so a composer dismissed mid-probe still created the workspace and launched an agent.

Because that class recurred twice, hostCapabilities is now a required parameter rather than an optional one documented by a comment. exactOptionalPropertyTypes is off and the caller census pins a different function, so nothing else would have caught a future caller that forgot it. A type-level ablation confirms it: the omitting caller compiles clean without the change and fails TS2741 with it. Runtime at the single production caller is unchanged.

A subsequent loop swept every await this PR inserted plus their upstream callers for a third instance and found none.

Rendered Electron validation at f492064432

Three cold-window creates submitted with both hydration gates verifiably false (in-page recorder via addInitScript, not screenshot timing) all resolved to structured-native-chat with a Claude Chat tab focused. Warm pass unaffected. Live mechanism check in the running renderer, varying only hostCapabilities: probed list → structured-native-chat; null → legacy-native-chat; [] → legacy-native-chat. Details and screenshots in the preceding comment.

Notably, the awaited backstop turned out to be unreachable via the cold path — the boot probe cached capabilities before the composer had even rendered, every time. That is the fix working, but it means the backstop was exercised separately through the module's test hook rather than by the cold path.

Honest gaps

• No screenshot provably captured inside the pre-hydration window: under CPU throttling the CDP capture itself takes long enough that the gates flip mid-capture. The pre-hydration proof is the in-page timeline; the images show the resulting tab.
• No ablation against main in the live rig (it would have required modifying production source).
• Renderer reload gives a fresh renderer JS context but a warm main process, so true first-launch main-process latency is not modelled.
• The folder-path cancel fix is covered by hook-level tests and ablation, not a live dismissal-during-probe run.
• The boot-probe wiring is pinned by a source-order ratchet that asserts position but does not execute the effect.
• Three synchronous readers remain structurally unfixed and now depend on the boot probe having landed. The window is one local IPC round-trip from the first renderer effect — practically unreachable by a human click, but not closed by construction.
• Four creation paths now carry an unbounded suspension point. Deliberate: a deadline would fire precisely under main-process contention, which is the repro condition, and would reinstate the bug. In-repo precedent leaves the same local getStatus() unbounded while bounding remote RPCs at 15s.
• Windows/Linux/SSH unexercised — renderer-only and host-agnostic; remote creates short-circuit on remote-execution-host before the capability check.

Issue linkage — please note

Fixes #19154 was changed to Refs #19154. That issue's headline defect is a different bug: a structured Claude chat session that can never be closed, because eviction fails at stop-provider-child. That defect is still live on main, verified link-by-link and untouched here. Merging this as a closing reference would have closed the issue with the titled bug still shipping. The body documents the full chain for follow-up.

[brennanb2025]

Rendered Electron QA at the final head 0b11f4d257 — run directly, not delegated

Isolated dev instance from the pr19819-electron-qa worktree at 0b11f4d257, fresh user-data profile, ORCA_BACKGROUND_LAUNCH=1, renderer 127.0.0.1:5241, CDP 127.0.0.1:9401. Before trusting anything I confirmed the attached instance was this checkout (devRepoRoot: .../pr19819-electron-qa) and that the running renderer served branch code — use-app-startup-hydration.ts contains void ensureLocalRuntimeCapabilities(), and folder-workspace-composer-submit.ts no longer contains preResolvedHostCapabilities (the required-parameter commit is live). Settings matched the incident report: Claude default agent, native chat + open-in-chat + structured native chat on, Claude args --dangerously-skip-permissions, setup mode new-tab, fixture repo with a committed setup script.

1. The mechanism, measured in the running renderer

Calling the app's own resolveAgentLaunchRoute with this profile's real settings, varying only hostCapabilities:

hostCapabilities	resolved route
probed list (74 caps, includes agent-session.structured.v1)	structured-native-chat
null (not asked yet)	legacy-native-chat
[]	legacy-native-chat

So an unhydrated cache is exactly what degrades the route, and the degraded route is legacy-native-chat — a terminal-backed surface.

2. The boot probe beats the hydration gates — quantified

Cold reload under 12× CPU throttling, sampling the capability cache and both gates in-page:

event	ms after reload
capability cache populated	13,937
workspaceSessionReady	28,291
terminalStartupRestorationReady	29,793

The cache was populated 15.9 s before the gates. That gap is the whole point: those gates were previously the only trigger for the cache's sole writer, so before this change every create in that window resolved against null and degraded. The window is now closed by construction rather than narrowed.

3. A cold-window create through the real dialog

Create driven in-page (a CDP round trip under throttle is seconds wide and would miss the window), through the actual create-worktree dialog — open, fill, submit:

• gates at submit: workspaceSessionReady: false, terminalStartupRestorationReady: false — genuinely pre-hydration
• capability cache at submit: populated (the boot probe had already landed)
• resulting focused surface: activeTabType: "agent-session"

Claude Chat focused for coldself-160972, with Setup beside it and unfocused — the structured surface, not a terminal.

What this does and does not establish

Establishes: the degradation mechanism is real and reproduces on demand (null → legacy-native-chat); the boot probe populates the cache well before the gates that used to gate it; and a create submitted with both gates false lands on the structured chat surface at the final head.

Does not establish:

• No ablation against main in this rig — that would mean editing production source in the checkout under test. The pre-fix populate time is inferred from the code (the tabs-sync is the only other writer and is gated behind those same flags), not measured here.
• The awaited backstop was not exercised by the cold path — the boot probe won every time, so the await at the four call sites never had a null cache to wait on. That is the fix working, but it means the backstop's own behaviour is covered by unit tests rather than by this run.
• Renderer-only cold boot. Reload gives a fresh renderer JS context with a warm main process, so true first-launch main-process latency is not modelled.
• One earlier warm create in this session landed on a terminal surface while I was still configuring the profile (settings applied post-boot, first-run setup-script trust prompt outstanding). I did not chase it down, so I am reporting it rather than omitting it; the clean cold run above was taken after the profile was fully configured.

Note for anyone reproducing this: a first-run "Run setup script from <repo>?" trust prompt blocks worktree creation and stalls automation silently — the create simply never starts, with no error. Grant it once with "Always trust".

[pullfrog]

ℹ️ No code defects found — the boot-hydration fix survives the merge intact, and all retained tests plus pnpm tc:web pass. One note on the merge's scope reduction and a stale doc line below.

Reviewed changes

Reviewed the delta since the last pullfrog review (0b11f4d → 43bb27b, a merge of origin/main), which substantially narrowed the PR.

• Merge absorbed main's planAgentSessionLaunch refactor — main replaced the per-call-site resolveAgentLaunchRoute usage with the synchronous planAgentSessionLaunch / buildAgentLaunchRouteInput path, so the branch's four creation-flow await ensureLocalRuntimeCapabilities() call sites, the folder hostCapabilities parameter, and their tests are no longer in the diff.
• Boot probe retained — use-app-startup-hydration.ts still starts void ensureLocalRuntimeCapabilities() first and ungated, and local-runtime-capabilities.ts keeps ensureLocalRuntimeCapabilities / startLocalRuntimeCapabilityProbe, so the module-level capability cache is warmed on mount for the synchronous route readers.
• Tests retained — the five ensureLocalRuntimeCapabilities cases in local-runtime-capabilities.test.ts and the source-order ratchet in app-startup-routing.test.ts (38 tests pass; pnpm tc:web clean).

ℹ️ Merge reduced the PR's scope but the description still describes the removed changes

The net diff is now 4 files (was 15). The PR body's "What Changed" section, its ablation table, and the "folder-path cancel fix" narrative all describe the four creation-flow awaits and the required hostCapabilities parameter that the merge dropped — they no longer exist in the code being merged, so a reader is told the PR covers the folder cancel window and a residual-window backstop it does not.

Technical details

# PR description no longer matches the diff

## Affected sites
- `src/renderer/src/lib/agent-session-launch-plan.ts:116` — `planAgentSessionLaunch` is synchronous; it resolves the route through `buildAgentLaunchRouteInput`.
- `src/renderer/src/lib/agent-launch-route-input.ts:123` — capabilities are read synchronously via `readLocalRuntimeCapabilitiesOrUnknown()`.
- PR body "What Changed" / "Ablations" — describes `quick-creation-execution.ts`, `full-creation-execution.ts`, `folder-workspace-composer-submit.ts`, `launch-work-item-direct-route-preparation.ts`, `folder-submit-orchestration.ts`, and their tests, none of which appear in the diff.

## Required outcome
- Confirm boot-hydration-only scope is intended (it still fixes #19154 because the probe lands before any user-driven create).
- Update the body so it describes the diff that will actually be merged; otherwise the folder cancel-window and residual-window coverage claims mislead reviewers/mergers.

## Open questions for the human
- Is the plan to re-introduce the route-decision backstop against main's synchronous planner (which would require making it await-capable), or is boot hydration the accepted end state?

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

This backstop no longer exists after the merge: planAgentSessionLaunch is synchronous and reads the cache through readLocalRuntimeCapabilitiesOrUnknown(), so nothing awaits ensureLocalRuntimeCapabilities() at a route decision. The comment still presents an awaiting call site as covering the residual window and re-probing after failure — reword it so it doesn't imply a live caller.