[Jinwoo-H]

	Files	Added	Deleted	Net
Test	1	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​22	0	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​22
Prod	1	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​4	$\color{#cf222e}{\Huge{\mathbf{−}}}$​2	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​2

ELI5

You start orca serve yourself and pair a desktop with it. If you run orca open-url before any desktop is showing that server's pages, the command fails, as it should. But the error it gives tells you to go change an SSH-host setting, which this server doesn't have. This PR brings back the error that tells you what to actually do: open a browser tab for this server on a paired desktop.

What Changed

• Before: on a server you started yourself, orca open-url with no desktop showing its pages failed with desktop_browser_bridge_unavailable. The message was "open this host's SSH settings, turn on 'Allow this host's orca CLI to control Orca'".
• After: the same case fails with browser_host_unavailable: "No paired Orca desktop is hosting browser pages for this server. On a desktop paired with it, open a browser tab in one of this server's workspaces, then retry." This is the behaviour fix(orcad): orca open-url opens the page on the paired desktop #30782 designed for this path.
• Mechanism:
  • orcad has a "desktop browser bridge" that forwards its CLI's browser commands to a desktop. A desktop opts into it per SSH host.
  • Every orcad switched the bridge on at startup (orcad-lifecycle.ts), including ones a user started.
  • Since fix(ssh): orca open-url on a managed SSH host opens the page on the desktop through the browser bridge #30849, browser.openUrl also goes through the bridge, so with no desktop attached the bridge's refusal answered first.
  • The bridge is now switched on only for a client's managed launch, the servers a desktop starts on an SSH host. Orcad detects that through ORCA_ORCAD_MANAGED_ACTIVATION_ROOT, which only a managed launch sets.
  • A server you started never has a desktop that can opt in, so its CLI's browser commands take the paired-desktop path again.
• Unchanged: managed SSH hosts, which keep the bridge and its message.
• Cause: fix(ssh): orca open-url on a managed SSH host opens the page on the desktop through the browser bridge #30849 added the bridge path for open-url. That change is correct on managed SSH hosts; this PR only narrows where the bridge is switched on.

Why

• Why the startup switch: whether a desktop can opt into this host's bridge is a property of how the server was launched, so the one switch at startup is the right place to decide. Every desktop able to attach the bridge (added 10-15, fix(ssh): agents on a managed SSH host can drive the desktop Orca browser again, behind the per-host switch #29384) already sets the managed-launch variable (added 10-07), so no old desktop loses the bridge.
• Alternative considered: special-casing open-url inside the bridge route. That would leave every other browser command on a user-started server with the same wrong advice.

Linked Issue

Found during the terminal-layout headless work (track H). No issue.

Visual Proof

N/A for UI. This is CLI output. With no desktop hosting pages, orca open-url prints:

Before:

"code": "desktop_browser_bridge_unavailable",
"message": "No Orca desktop is sharing its browser with this host. On your desktop, open this host's SSH settings, turn on \"Allow this host's orca CLI to control Orca\", and keep the host connected. ..."

After:

"code": "browser_host_unavailable",
"message": "No paired Orca desktop is hosting browser pages for this server. On a desktop paired with it, open a browser tab in one of this server's workspaces, then retry. ..."

Testing

• I manually tested these changes locally

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

• Unit: orcad-lifecycle-host.test.ts checks that the bridge is on for a managed launch and off for a user-started server, and off after stop. The user-started case fails on base and passes on head.

• e2e: tests/e2e/orcad-serve-open-url-on-desktop.spec.ts, which fix(orcad): orca open-url opens the page on the paired desktop #30782 added and which expects browser_host_unavailable. Run on macOS, hidden, with ORCA_E2E_ORCAD_SERVE=1:

  • On base it fails at that check, with desktop_browser_bridge_unavailable.
  • On head it passes twice, including the rest of the flow: the desktop pairs and the page opens in it.
  • PR CI doesn't run this spec, which is how it went stale.

• pnpm tc, check:code-quality:changed, type-aware oxlint, the layout-writer ratchet, and the bridge and orcad unit suites pass.

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

• SSH: managed SSH hosts are unchanged.
• Managed WSL hosts: also launched as managed, so they keep the bridge as before. This PR doesn't change them.
• Compatibility: no wire change. The environment variable already exists.
• Platforms: no platform-specific code.

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)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 2 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 0953b8d9-ac03-4f06-99a4-17070486dad0

📥 Commits

Reviewing files that changed from the base of the PR and between a2e0f20 and e2c9614.

📒 Files selected for processing: 2

• src/main/orcad/orcad-lifecycle-host.test.ts
• src/main/orcad/orcad-lifecycle.ts

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