[brennanb2025]

	Files	Added	Deleted	Net
Test	13	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​542	$\color{#cf222e}{\Huge{\mathbf{−}}}$​285	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​257
Prod	37	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​463	$\color{#cf222e}{\Huge{\mathbf{−}}}$​271	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​192

ELI5

When you click an AI button such as "Fix checks", Orca asks the background service (the "host") to plan the agent's command. Until now the host also started its own terminal for the agent and the window then adopted it. That terminal started at a fixed 40×120 and was resized about 0.4 s later. Now the host only plans the command, and the tab's own terminal starts it at the tab's size, the same way a "+" tab starts its command.

What Changed

The problem. An AI button's tab was one whose terminal the host spawned and the window adopted afterwards, unlike a "+" tab, whose own terminal starts its command. On main the host's terminal started at 40×120 and was resized to the tab about 0.4 s later. In 3 of 8 launches in live QA the shell saw that resize. The agent itself usually started at the right size, because the shell types its command after the resize.

What you'll see differently.

• An AI button's terminal starts at the tab's size instead of at 40×120 followed by a resize. Live QA saw no visible reflow from the old resize; one observation after a window reload showed the agent itself starting at 40×120 on main.
• Under the hood, these tabs now open exactly like "+": no hand-over from a host terminal, so no reveal, and the phone sees them through ordinary tab sync. Live QA saw no visible difference in either: no flash on either build at the frame rate it could capture, and the phone already received the tab through tab sync on main. Whether the tab now answers the terminal's start-up queries while it opens was not measured.
• A failed AI-button launch again keeps its tab and says why inside it ("The agent couldn't start." with Copy prompt, or "Couldn't confirm the agent started."). This ends the temporary corner notices from AI buttons stop writing a launch record #28209, which is on main (de9caf1).
• Intended, as "+" already does: a click whose tab never mounts, or is closed before its terminal starts, starts nothing until the tab's terminal mounts. A reload before the tab's terminal starts drops that click and its prompt.
• Intended telemetry change: an AI button whose agent fails to spawn now counts one agent_error, as a "+" tab's failed spawn does. Before, it counted none.

Temporary:

• Workspaces that run on another machine keep their current route. SSH projects that aren't converted to a managed server take "+"'s route, as approved. Paired servers and managed SSH servers keep the host's agent.launch on their own server. Moving them onto the same path needs a capability that remote servers advertise, which doesn't exist yet.
• An OpenCode tab with a model picked keeps main's host route: the host starts its terminal and the tab attaches to it. No action on this machine makes such a tab today (a model reaches a terminal launch only through the CLI, the phone or a paired server, which all start on the host), so moving it would change code nobody reaches. Follow-up: fold it into the tab's own launch once a local producer of model options exists.

Kept from main (the host's runtime rule, #27692): the tab's terminal runs the agent in the same place, and with the same command, as the host planned it on main. AI buttons get the same runtime answer as "+" and the host. For example, in a repo on a \\wsl$ share the agent runs inside WSL with its command written for Linux, as "+" and the host already do, even when that repo is saved as running on the Windows host (as on main); in a repo set to run in WSL it runs in that distro. The planner decides the shell once, and the tab's terminal uses that shell, so the command is always written for the shell it is typed into.

Disabled agents are refused exactly as on main. A missing working folder fails as on main rather than starting at the workspace root. Nothing changes for "+" tabs, OpenCode tabs with a model picked, typed-prompt tabs, the phone's own launches, the CLI, or chats.

Mechanism.

• The window makes the tab at the click, as before, and queues the launch request (agent, workspace, arguments, model, source) on the tab, as "+" queues its command. The tab's terminal sends it with its own spawn.
• Inside that spawn, once the pane is reserved and before anything else runs, main plans the command with the same planner every host launch uses, then runs it as it runs any pane's command. A spawn that reattaches a live agent skips this. No launch record is written; nothing reads one for these tabs (see AI buttons stop writing a launch record #28209).
• The plan carries its runtime (where the agent runs and in which shell); the tab's terminal starts in that shell, as the host's own launch does. The Qoder executable is resolved once, by the planner, for that runtime.
• The agent gets the same launch token and agent identity on its terminal as the host's own launch gave it, so orchestration callers, hook evidence and title-based presence keep working.
• Every way the spawn ends finishes the launch: started (the tab is an ordinary terminal), failed before the provider was asked (the tab says why), failed after (the tab says it couldn't confirm), or closed by the user (nothing starts; an agent that did start is stopped).
• The AI button's prompt is still pasted by the window once the agent is ready, and only after this tab's spawn says the agent started there. A refusal, failure, close (by the user or not) or the workspace's removal means no paste and no second notice.
• Deleted: the window's spawn hold and the host-side hand-over for these tabs.

Why

Starting the plan in the tab's own terminal, rather than the host spawning a terminal and handing it over, is what starts it at the tab's size and puts AI buttons on the one path "+" already uses; it is also the common pattern for desktop terminals. One planner means the window and the host can't build different commands for the same click. The alternative, keeping the host's terminal and fixing its size separately, keeps a second way to start a tab's agent and a hand-over between them.

Linked Issue

Part of the launch-convergence plan. Based on main. #28209 (AI buttons stop writing a launch record) merged as de9caf1; its temporary changes end with this PR, so this PR should land before the next release cut.

Visual Proof

Live QA on hidden macOS test windows with real Claude; the images are from 8a80da2, before the final runtime change, which the smoke run on this head repeats. The full results are in the status comment.

Testing

• I manually tested these changes locally (live QA, see Visual Proof and the status comment)

• Automated tests added/updated

• One start, at the pane's size. A pane's own launch plans once and spawns the planned command once, at the pane's size, and reports that it started (pty-agent-pane-launch.test.ts).

• Runtime. The tab's terminal runs the shell of the plan's runtime, as the host's launch does, and the planner never gets the tab's inferred shell (pty-agent-pane-launch.test.ts); the planner's own runtime and quoting cases are main's (runtime-agent-terminal-startup.test.ts).

• Identity and joins. The agent's terminal carries its launch token and agent; two spawns of one pane start one agent; a remount of a pane whose agent survived attaches to it and never plans again (pty-agent-pane-launch.test.ts, pty-agent-launch-pane-attach.test.ts).

• Failures. A plan failure starts no shell and the tab says why; a lost provider answer reads "couldn't confirm"; a close while planning starts nothing (pty-agent-pane-launch.test.ts).

• OpenCode tabs with a model. Main's own tests pass untouched (ipc-pty-opencode-model.test.ts).

• Paste gate. The window pastes only after this tab's spawn says the agent started, never after a refusal, failure or close (agent-launch-pane-start.test.ts, launch-agent-new-tab-host-route*.test.ts, pty-transport-connect-spawn.test.ts). The tab's spawn answers with the PTY it started the agent in, and the prompt goes only to that PTY: a split made while the agent starts, whose shell binds first, never receives it (launch-agent-new-tab-host-route-readiness.test.ts). Readiness is watched on every split's terminal as it binds, before its startup output drains, so the launch pane's own ready signal is never missed even when a split bound first (launch-agent-new-tab-host-route-readiness.test.ts); a launch has no 8 s spawn deadline, so a pane that starts late still gets its prompt exactly once, and one that fails never does (agent-paste-draft-readiness-budget.test.ts). Other callers keep main's timing.

• Callers. Every AI-button caller queues the launch on its tab, in its group, with its working directory and source (agent-launch-caller-*.test.ts, launch-agent-in-new-tab.test.ts).

• Verified: tc:node, tc:web, the changed-code quality check, oxlint and the layout-writer check pass; every test file that directly imports a changed module, plus the launch-parity, race and runtime suites (550 files), passes on this head. One local failure is not from this PR: orca-runtime-agent-session-operation "shapes the launch for the route it resolved" fails on plain main on macOS too.

Covered or hidden window. Since #28351 (on main), a tab's terminal doesn't wait for its grid to settle while Orca's window is hidden or covered. An AI button clicked just before Orca is covered starts its agent at once, at the tab's size, and the agent answers the prompt while the window is still covered, as on main (live QA in Visual Proof above). Its prompt waits for the tab's terminal to say it started, with no 8 s spawn deadline, so a slow start never loses the prompt (agent-paste-draft-readiness-budget.test.ts). Not re-measured on Windows since #28351.

Known, not fixed here (same on main):

• With Claude disabled, an AI button that defaults to Claude silently launches the next enabled agent (OpenCode in QA) instead of refusing or saying so.
• When the agent's command can't run (for example, it isn't executable), the AI button's prompt is pasted into the plain shell, with no notice.

Size

Measured with git diff --numstat <base> HEAD -- src, TypeScript only; test files count as tests and locale JSON on its own. Against main (after #28209): production +180, tests +269 (the shared launch test harness counts as tests), locale strings 0. Where it goes (comments included):

• spawn-agent-launch.ts +128: the launch planned inside the reserved spawn, with the shared planner; Qoder resolved once; the launch token; the missing-folder parity.
• spawn-agent-launch-end.ts +81: finishing the launch on every way the spawn ends (started, failed before or after the provider was asked, closed by the user), with no record.
• agent-launch-pane-start.ts +30: the paste gate, answered by this tab's own spawn, and ended by a close or the workspace's removal (+9 in the close and purge paths).
• Shared helper +7: the launch token (also used by the host's own launch).
• The planner's runtime +5: kept on the pane's launch (never taken from the window's request), used for the terminal's shell, and the spawn's second Qoder lookup skipped for these tabs.
• Prompt delivery +17: each split's terminal is watched as it binds; the prompt waits for the tab's own start answer, which names the PTY its agent started in, and is written only there, never to another split's shell (agent-paste-draft.ts; the answer's type change is one-for-one in the close, purge, verdict and connect paths).
• Offsets: the window's spawn hold deleted (−57), the window's launch call −68, the prompt route −30.

AI Disclosure

Review

Agent skill upstream boundary

• Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

Ensure no issues in: Security, Cross-platoform support (Linux, Windows, Mac), Remote SSH, Mobile, general backwards compatibility, performance

• SSH and paired servers: unchanged routes (see Temporary above).
• Windows / WSL / POSIX: the planner picks the runtime and shell once (the host's rule from Host plans agent launches with the window's runtime rule and one runtime fact (C1) #27692), and the tab's terminal uses that same shell, so the command is quoted for the shell it is typed into. The tab's own shell is one the window inferred, not one the user asked for, so it isn't sent to the planner as a request, as the host's launch never sent one; sending it made the planner refuse a \\wsl$ repo set to the Windows host.
• Mixed versions: the new launch field rides only the window-to-its-own-main spawn call, which always ships together; nothing a paired client and host exchange changes.

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)

[brennanb2025]

Status: ready for review. Head f4938433cca, based on main. #28209 merged as de9caf1366a; this PR ends its temporary changes. Main includes #28351 (a startup terminal no longer waits while Orca's window is hidden) and #27692 (the host plans agent launches with one runtime answer per workspace).

Reviews.

• Round 1: three fresh reviewers (correctness, architecture, size). They found 1 P2 (AI-button tabs lost the agent's launch token) and 9 P3s. All fixed.
• Round 2: a fresh full review found 1 P2: a prompt was lost when a pane started more than 8 s after the click. Fixed.
• Rounds 3-5 checked only the changes.
  • Round 3 found a P2: the prompt could reach a split's shell that bound first. Fixed.
  • Round 4 found a P2: the launch pane's own ready output could be missed. Fixed.
  • Round 5 was clean.
• Round 6 (a fresh Codex review of the commit that moves onto Host plans agent launches with the window's runtime rule and one runtime fact (C1) #27692's planner) found no issue in that commit. It found one P2 left over from this PR's earlier change:
  • The window had been sending the tab's inferred shell to the planner as if the user had asked for it. In a \\wsl$ repo saved as running on the Windows host, the planner then refused the launch, while main's AI button started it in WSL.
  • Fixed in that commit: the tab's inferred shell is no longer sent. A test pins it and fails without the fix.
• Leftovers, deferred: two stale comments.

Syncs with main. Two syncs with main, approved by the lane owner, plus one rebase after #28209 merged that dropped #28209's commits (all 7 commits of this PR unchanged in git range-diff):

• The first picked up Start a startup terminal while Orca's window is hidden instead of waiting for it to be shown #28351.
• The second picked up Host plans agent launches with the window's runtime rule and one runtime fact (C1) #27692, which removed the planner method this PR called. One fix commit moves the AI-button pane onto the new planner:
  • The pane's terminal runs the shell of the plan's runtime, as the host's own launch does.
  • Qoder is resolved once.
  • The tab's inferred shell is no longer sent to the planner.

Size against main: production +180, tests +269.

Checks on this head.

• tc:node, tc:web and the focus-read ratchet pass.
• Every test file that imports a changed module passes, plus the launch-parity, race and runtime suites: 550 files. The one exception is orca-runtime-agent-session-operation "shapes the launch for the route it resolved", which also fails on plain main on macOS.
• orca-ci-checks passes every check but one. The one failure is the local bun typecheck runner: bun can't find its check script on this machine, which is unrelated to the diff. The tsc typechecks above pass, and CI runs its own typecheck.
• CI: green on f4938433cca (23 pass, 0 fail, including the ready-only jobs). The first run had three failures in code this PR doesn't touch, which passed on a re-run of the failed jobs: a Windows file-permission race test (28 samples where it needs more than 50), and two SSH and Codex command tests that timed out and pass locally. Merge state CLEAN; no unresolved review threads.

Live QA (hidden macOS test windows, real Claude, Codex driver, Orca's own home isolated, real agent configs hash-checked and unchanged).

• On 334fe69941a (same patches as this head; smoke run, one fresh rig per attempt):
  • AI button "Explain changes" with the window covered 24-28 ms after the click (2 of 2): the terminal and Claude start about 100-116 ms after the click while still covered. The prompt is pasted once and answered while covered, and there is no toast. A third attempt, covered later (96 ms), gave the same result.
  • Uncovered: Claude starts at the tab's size (58×135, and stty size in the same tab agrees). The prompt is pasted once and submitted.
  • The AI-button tab runs the same shell as a "+" tab in the same rig (/bin/zsh, Default Shell unset).
• On 8a80da25d71 (before the planner change), with the window covered within 25 ms of the click:
  • AI button "Explain changes" (2 of 2): the terminal and Claude start 73-80 ms after the click while still covered. The prompt is pasted once and answered while covered, with no toast. Main does the same.
  • "+" > Claude (2 of 2): starts within 58 ms while covered, with no toast. Main does the same.
  • Claude starts at the tab's size (58×135). The prompt was pasted exactly once and submitted in 3 of 3 launches.
• On earlier heads of this change (before the round 2-5 prompt-delivery fixes; not rerun since):
  • AI-button terminals start at the tab's size; main started them at 40×120 and resized.
  • A failed AI button keeps its tab and shows "The agent couldn't start." with Copy prompt, the same as main.
  • Clicking then switching workspace away and back gives one agent per click.
  • Clicking then closing the tab starts nothing (intended, as "+").
  • A reload right after the click drops it, as "+" does (intended).
  • A live agent survives a restart.
  • The phone sees the tab through tab sync.
  • With the launch record store unreadable, the AI button still starts; main dropped the click silently.

Not verified.

• Windows and WSL live: the \\wsl$ and WSL-runtime cases are traced in code only. The AI-button pane now runs the same shell and WSL distro as the host's launch of that agent, and the planner's own runtime and quoting cases are covered by main's tests.
• A visible Windows window.
• An OpenCode tab with a model picked: no desktop action creates one.
• A pane registration that returns early: no user action triggers it.
• A possible sub-200 ms flash: the capture frame rate is too low to show one.
• SSH and paired-server routes, which are unchanged.

[coderabbitai]

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: 0fc07231-c83e-4a49-82db-615c753cf5e2

📥 Commits

Reviewing files that changed from the base of the PR and between 3d89071 and f493843.

📒 Files selected for processing: 50

• src/main/agent-launch/agent-launch-token.ts
• src/main/ipc/pty-agent-launch-pane-attach.test.ts
• src/main/ipc/pty-agent-pane-launch.test.ts
• src/main/ipc/pty/ipc/spawn-agent-launch-end.ts
• src/main/ipc/pty/ipc/spawn-agent-launch.ts
• src/main/ipc/pty/ipc/spawn-commit.ts
• src/main/ipc/pty/ipc/spawn-execute.ts
• src/main/ipc/pty/ipc/spawn-preflight.ts
• src/main/ipc/pty/ipc/spawn-qoder-command.ts
• src/main/ipc/pty/ipc/spawn-run.ts
• src/main/ipc/pty/ipc/spawn-state.ts
• src/main/ipc/pty/ipc/spawn-types.ts
• src/main/runtime/orca-runtime-create-terminal.ts
• src/main/runtime/orca-runtime.ts
• src/preload/api/pty-api.ts
• src/preload/api/pty-bridge-session-control.ts
• src/renderer/src/components/terminal-pane/ipc-pty-connect.ts
• src/renderer/src/components/terminal-pane/ipc-pty-spawn-request.ts
• src/renderer/src/components/terminal-pane/pty-connection-types.ts
• src/renderer/src/components/terminal-pane/pty-connection/hidden-startup-renderer-query.ts
• src/renderer/src/components/terminal-pane/pty-connection/pane-transport-options.ts
• src/renderer/src/components/terminal-pane/pty-connection/pty-resize-geometry.ts
• src/renderer/src/components/terminal-pane/pty-transport-connect-spawn.test.ts
• src/renderer/src/components/terminal-pane/pty-transport-types.ts
• src/renderer/src/hooks/ipc-events/terminal-presentation-ipc-bridge.ts
• src/renderer/src/hooks/useIpcEvents-agent-launch-closed-tab.test.ts
• src/renderer/src/lib/agent-launch-caller-permissions.test.ts
• src/renderer/src/lib/agent-launch-caller-placement.test.ts
• src/renderer/src/lib/agent-launch-funnel-test-harness.ts
• src/renderer/src/lib/agent-launch-pane-closes.ts
• src/renderer/src/lib/agent-launch-pane-spawn-hold.test.ts
• src/renderer/src/lib/agent-launch-pane-spawn-hold.ts
• src/renderer/src/lib/agent-launch-pane-start.test.ts
• src/renderer/src/lib/agent-launch-pane-start.ts
• src/renderer/src/lib/agent-launch-pane-verdict-application.ts
• src/renderer/src/lib/agent-launch-prompt-delivery.ts
• src/renderer/src/lib/agent-launch-tab-publication.test.ts
• src/renderer/src/lib/agent-launch-through-host.test.ts
• src/renderer/src/lib/agent-launch-through-host.ts
• src/renderer/src/lib/agent-paste-draft-readiness-budget.test.ts
• src/renderer/src/lib/agent-paste-draft.ts
• src/renderer/src/lib/launch-agent-in-new-tab.ts
• src/renderer/src/lib/launch-agent-new-tab-host-route-readiness.test.ts
• src/renderer/src/lib/launch-agent-new-tab-host-route.test.ts
• src/renderer/src/lib/launch-agent-new-tab-host-route.ts
• src/renderer/src/lib/launch-agent-tab-prompt-paste.ts
• src/renderer/src/store/slices/worktrees/teardown/worktree-purge-state.ts
• src/renderer/src/store/terminals/terminal-state.ts
• src/renderer/src/store/terminals/terminal-tab-close.ts
• src/shared/agent-pane-launch-request.ts

💤 Files with no reviewable changes: 3

• src/renderer/src/lib/agent-launch-pane-spawn-hold.test.ts
• src/renderer/src/hooks/ipc-events/terminal-presentation-ipc-bridge.ts
• src/renderer/src/lib/agent-launch-pane-spawn-hold.ts

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

📝 Walkthrough

The renderer now queues agent launch requests with pane startup and forwards them through PTY IPC. The main process validates and plans these requests, spawns the planned agent, and reports launch outcomes. The renderer tracks the pane’s startup result and uses the resulting PTY ID to direct prompt delivery. Pane closure and other termination paths settle pending startup results.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to f4938

The reviewed launch and failure paths show no issue that needs fixing before merge. Complete the normal checks before merging.

Pre-merge checks: 3 · 2

Failed checks: 2 warnings

Check name	Status	Explanation	Resolution
Title check		The title correctly describes AI-button launches, but it incorrectly states that OpenCode-model tabs start agents in their own terminal. The description says those tabs retain the host route.	Change the title to focus on the actual change, for example: "AI-button launches start agents in their own terminal".
Docstring Coverage		Docstring coverage is 35.85% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 53 functions across 47 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 3 passed

Check name	Status	Explanation
Description check		The description is detailed and covers the required explanation, scope, rationale, linked issue, visual proof, testing, compatibility notes, and checklist. The AI Disclosure and Review sections are em…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

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