[nwparker]

	Files	Added	Deleted	Net
Test	5	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​36	$\color{#cf222e}{\Huge{\mathbf{−}}}$​4	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​32
Prod	4	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​46	$\color{#cf222e}{\Huge{\mathbf{−}}}$​10	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​36

ELI5

With Chat UI on, orca orchestration worker-start --agent antigravity started picking a chat worker in 1.4.230. An Antigravity chat needs a separate runtime that Orca downloads, and you can only start that download from a chat tab. A worker has no chat tab, so the start just failed, even though the agy CLI was installed and had worked the day before. Now, when that runtime is missing, the worker starts in a terminal using the agent's own CLI, as it did in 1.4.229. The receipt says why.

Root cause

• decideAgentLaunchMode → resolveAgentLaunchModeOnHost asks getStructuredAgentSessionCreateSupport. That check covers location and CLI version, but not whether the managed chat program exists. So structured / user_default was chosen.
• The ACP start then fails pre-spawn: src/main/acp/acp-structured-launch-preparation.ts throws AgentSessionPreSpawnError(..., { reason: 'runtimeNotInstalled' }) when the resolved command is still the bare agy_acp_server.par. Antigravity's spec declares managedRuntime: ANTIGRAVITY_ACP_RUNTIME (src/main/acp/acp-launch-specs.ts, pinned 1.3.0 in src/main/antigravity/antigravity-acp-runtime.ts). Startup never installs it, by design (feat(acp): chat agents can declare a managed runtime that a start runs but never installs #28460).
• The worker placement surfaces structured create failures rather than downgrading them, so the dispatch failed at terminal_create.

What changed

• getStructuredAgentSessionCreateSupport(worktree, agent, { requireInstalledChatProgram }): when asked, it reuses the existing host-health chat-program probe (observeChatProgram in structured-agent-availability.ts, the same code that publishes chatProgram: 'installable' to clients). If the agent's Orca-managed chat program isn't installed, it answers { supported: false, reason: 'chat-program' }. Only agents that declare an installable chat program (today, Antigravity) are probed.
• Launch-mode host settlement (orchestration workers, plus agent.launch from CLI, mobile, automations, and external conversations) passes the option. It maps the answer to a new receipt reason, chat_runtime_not_installed:
  • default chat → terminal: "Your default is a structured chat session, but its chat runtime isn't installed on this host (install it from a new chat tab in Orca); started a terminal agent worker instead."
  • explicit --surface chat → agent_launch_surface_unavailable: "Antigravity can't open as a chat here because its chat runtime isn't installed on this host (install it from a new chat tab in Orca). Start it in a terminal instead."
• The agentSession.createSupport RPC (desktop chat tabs) does not pass the option, so desktop still offers the in-chat install card.

How verified

Real headless repro in an isolated dev Orca: orca-dev serve with an isolated HOME and profile, Chat UI seeded on, no managed runtime, ORCA_BACKGROUND_LAUNCH=1.

• origin/main (4b05f13): worker-start --agent antigravity --worktree current → state: failed, failedStage: terminal_create, lastError: "Antigravity isn't installed on the computer running this chat...", mode: structured / user_default. This matches the issue exactly.
• this branch: same command → mode: terminal, preferred: structured, reason: chat_runtime_not_installed, and a terminal agent was created. agy started and showed its own first-run folder-trust prompt, which the readiness wait reported as agent-trust-workspace. That prompt is agy's own and unrelated to this fix.
• this branch: orca agent launch --agent antigravity --surface chat → refused with the clear message above.
• Regression test in orchestration-worker-start-registered-agent.test.ts. It fails without the fix.
• pnpm tc, 344 test files under agent-launch/rpc methods/automations/session-tabs passing, check:code-quality:changed clean.

Risk

• Small, server-side only. Clients and older servers are unaffected: the new reason is a plain string in the receipt, and nothing parses it as a strict enum.
• The extra probe runs only for agents with a managed chat program. It reuses the cached host shell environment.
• If the probe can't tell (unknown), behaviour is unchanged: it goes structured.
• Windows/WSL/remote: location checks already refuse there before this probe runs.

Fixes #30973

[coderabbitai]

Walkthrough

Structured-session support can now check whether the chat program is installed. When it needs installation, host launch handling maps the support failure to chat_runtime_not_installed. The worker test verifies fallback to terminal mode while keeping structured mode preferred.

Priority: Normal

Severity of issue fixed: Medium

Merge Risk: Moderate · up to 71d4d

An explicit chat launch can create a workspace and start a terminal worker instead of refusing the request. Correct that behavior before merging unless the deviation is explicitly accepted.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

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

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title names the main change: Antigravity workers start in a terminal when the chat runtime is not installed. It uses the conventional fix(scope) prefix and matches the linked issue #30973 and the …
Description check		The description follows the template well. It has an ELI5 section, root cause, what changed, verification steps, risk notes, and a 'Fixes #30973' link. The 'What Changed' content states the before and…
Linked Issues check		Issue #30973 requires a working terminal launch when the managed Antigravity chat runtime is absent, a distinct runtime error, and no false structured-start receipt. `src/main/agent-launch/agent-launc…
Out of Scope Changes check		The production changes stay within issue #30973. They add the installed chat-program probe, host launch settlement, the new receipt reason, and explicit-chat refusal. The modified tests update affecte…

Full details: Title check

Explanation

The title names the main change: Antigravity workers start in a terminal when the chat runtime is not installed. It uses the conventional fix(scope) prefix and matches the linked issue #30973 and the diff. At 97 characters it is long, but it is still a single clear sentence.

Full details: Description check

Explanation

The description follows the template well. It has an ELI5 section, root cause, what changed, verification steps, risk notes, and a 'Fixes #30973' link. The 'What Changed' content states the before and after and the mechanism. Gaps: the Visual Proof section is missing; it is required for behavior changes and no before/after is attached, though the author gives terminal output as text. The Testing checkboxes are not ticked, and the AI Disclosure, Review, and Agent skill upstream boundary sections are blank or unchecked. The Checklist is not ticked. These are minor, so the description is mostly complete.

Full details: Linked Issues check

Explanation

Issue #30973 requires a working terminal launch when the managed Antigravity chat runtime is absent, a distinct runtime error, and no false structured-start receipt. src/main/agent-launch/agent-launch-mode.ts requests requireInstalledChatProgram: true for headless host settlement and maps chat-program to chat_runtime_not_installed. Default structured launches downgrade to terminal mode. Explicit chat launches raise AgentLaunchSurfaceUnavailableError with an install instruction. src/main/runtime/session-tabs/structured-session-create-support.ts applies the probe only when requested, so desktop chat tabs retain the install flow. The added orchestration regression test covers terminal fallback. The reported type-check and focused test results provide additional verification.`

Full details: Out of Scope Changes check

Explanation

The production changes stay within issue #30973. They add the installed chat-program probe, host launch settlement, the new receipt reason, and explicit-chat refusal. The modified tests update affected support-call expectations and add the worker fallback regression case. No unrelated feature or behavior is demonstrated.

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

[coderabbitai]

Actionable comments posted: 1

---

Review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 79578085-d906-4bfd-9d30-490654791625

Commits

Reviewing files that changed from the base of the PR and between ced9a3d and 71d4de7.

Files selected for processing: 9

• src/main/agent-launch/agent-launch-mode.ts
• src/main/runtime/rpc/methods/agent-launch-floating-workspace.test.ts
• src/main/runtime/rpc/methods/orchestration-worker-start-registered-agent.test.ts
• src/main/runtime/rpc/methods/orchestration-worker-support-unknown.test.ts
• src/main/runtime/rpc/methods/orchestration/worker/worker-start-launch-executor-parity.test.ts
• src/main/runtime/session-tabs/structured-session-create-support.ts
• src/main/runtime/structured-agent-availability.ts
• src/main/runtime/structured-agent-session-support-probe.test.ts
• src/shared/agent-launch-intent.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.

[coderabbitai]

Major · Functional Correctness · Heavy lift

🔎 Supported by static analysis

Script executed:

#!/bin/bash
# Inspect create-target handling and the phase passed to host mode resolution.
rg -n -C 6 '\bresolveAgentLaunchModeOnHost\s*\(|phase: .created-workspace.|create-folder-workspace|create-worktree' src/main/agent-launch src/main/runtime/rpc/methods

Repository: stablyai/orca

Length of output: 41536

---

Script executed:

set -o pipefail
printf '%s\n' '--- changed diff ---'
git diff 4b05f1377e8c5b6e79ae801382b5e6a9895fa1cf 71d4de7dac06df7c379c3f22375b3badfdd3703f -- src/main/agent-launch/agent-launch-mode.ts src/main/agent-launch/agent-launch-executor.ts src/shared/agent-launch-intent.ts
printf '%s\n' '--- explicit surface references ---'
rg -n -C 5 -F -- 'surface: ' src/main/agent-launch src/main/runtime/rpc/methods src/shared | head -240
printf '%s\n' '--- resolver and executor blocks ---'
sed -n '1,340p' src/main/agent-launch/agent-launch-mode.ts
sed -n '1,250p' src/main/agent-launch/agent-launch-executor.ts

Repository: stablyai/orca

Length of output: 41834

---

Script executed:

set -o pipefail
git diff 4b05f1377e8c5b6e79ae801382b5e6a9895fa1cf 71d4de7dac06df7c379c3f22375b3badfdd3703f -- src/main/agent-launch/agent-launch-mode.ts src/main/agent-launch/agent-launch-executor.ts src/shared/agent-launch-intent.ts
printf '%s\n' '--- explicit surface references ---'
rg -n -C 5 -F -- 'surface: ' src/main/agent-launch src/main/runtime/rpc/methods src/shared || test "$?" -eq 1
printf '%s\n' '--- mode resolver ---'
sed -n '1,340p' src/main/agent-launch/agent-launch-mode.ts
printf '%s\n' '--- executor ---'
sed -n '1,280p' src/main/agent-launch/agent-launch-executor.ts

Repository: stablyai/orca

Length of output: 41753

---

Refuse explicit chat launches that create a workspace.

surface: 'chat' supports both create-worktree and create-folder-workspace targets. The executor creates the workspace before it settles host support with phase: 'created-workspace'. When the chat runtime is missing, this phase downgrades the launch to a terminal because refusal applies only to before-effects.

Check the chat runtime before workspace creation, or refuse the explicit chat launch after creation and recover the workspace.