[nwparker]

	Files	Added	Deleted	Net
Test	11	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​773	$\color{#cf222e}{\Huge{\mathbf{−}}}$​16	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​757
Prod	15	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​759	$\color{#cf222e}{\Huge{\mathbf{−}}}$​150	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​609

ELI5

When Orca runs as a server (orca serve) and a desktop is paired with it, orca open-url on the server should open the page in that desktop's Orca browser. On the default server runtime (orcad) it failed with "Browser automation is unavailable on this host." It now opens the page on the paired desktop, as it did before orcad became the default.

What Changed

Before: on a paired orca serve running orcad, orca open-url --url … failed with browser_unavailable. The only workaround was ORCA_SERVE_RUNTIME=electron.

After: orca open-url opens the page in the paired desktop's browser, inside the server's workspace. Its network goes through the server, so http://localhost:3000 on the server works. If no desktop is hosting pages for the server yet, it refuses with browser_host_unavailable and says what to do: open a browser tab in one of the server's workspaces on a paired, up-to-date desktop.

Mechanism:

• Server (orcad). orcad sent every browser command to a local browser engine (an Electron sidecar or Chromium). With no engine, every command failed. A page hosted on a desktop never needs that engine: it lives in this runtime's own lease and page registries, which orcad already had. orcad now handles these commands itself, with or without an engine:

  • open-url
  • creating a tab placed on a desktop
  • with no engine, the CLI's tab create, and tab list/current/show/switch/close

  The creation code is one Electron-free module, browser-client-page-opening.ts, and the Electron runtime now uses it too.

• Capability. orcad now advertises browser.clientHost.v1 from that registry (the new clientHostingWithoutEngine factory option), so its health no longer depends on the engine. Report browser placement support from the installed provider #26559 had withdrawn the capability because creation failed; creation now works.

• Desktop. A desktop only places a tab on the runtime for a host that streams pages (browser.screencast.v1). It now also does this for a runtime that advertises full client hosting. That makes tabs in a paired orcad workspace desktop-hosted, which attaches the lease open-url needs. Managed SSH deployments are excluded: they keep their SSH-routed desktop tabs and the desktop browser bridge. "Reopen on server" is hidden for a runtime known to have no browser of its own.

• With an engine. Tab commands see one list: engine tabs first, then desktop-hosted pages. One selection rule decides which tab is current, and it matches the page that workspace automation without --page already drives.

Why

There were two ways to show a server's page on a desktop:

1. The desktop browser bridge, which drives the desktop's own tabs. It is built for managed SSH and refuses any host whose tabs are not routed through SSH. On a paired server it would either refuse, or let the server browse from the desktop's own network (its localhost and LAN). It would also open localhost on the wrong machine.
2. Client-hosted pages. The page renders on the desktop, the server owns it, and its network is tunnelled through the server. This is the Electron runtime's existing mechanism, and what worked in 1.4.224.

I chose 2. It is safe on any network and correct for a server's localhost, and it reuses the existing lease, tunnel and automation routing with no new protocol.

Reference check: a mature remote editor forwards its server CLI's "open URL" to the attached client over an allowlisted channel, and the client opens it with port tunnelling. This is the same shape as option 2. Review rounds 2–5 kept finding places where the engine and the page registry disagreed about which tab was "current". After round 3 the design was reworked to give that one owner: one logical tab list and one selection rule (yieldClientPageSelection), matching the dispatcher's existing routing. This was simpler than patching each finding.

Wire compatibility. Nothing new goes on the wire; every capability string already exists.

• New orcad, old desktop: the desktop never attaches a lease, so open-url returns the clearer browser_host_unavailable.
• Old orcad, new desktop: no browser.clientHost.v1, so the desktop behaves as before.
• Managed SSH desktops are unchanged.

Linked Issue

Fixes #30731

Visual Proof

Desktop (background-launched, hidden) after orca open-url was run against an isolated orcad orca serve. The page was served on the server's loopback and rendered in the desktop's browser tab, placed on the client:

Linux server (real host), macOS desktop. An isolated orcad orca serve with no browser engine ran on a real Linux host. A paired desktop reached it through an SSH port forward, launched in the background. The page was served only on the Linux host's 127.0.0.1:46732, which the Mac cannot reach directly. It rendered in the desktop's tab, so its network went through the server:

macOS, local e2e (tests/e2e/orcad-serve-open-url-on-desktop.spec.ts):

Before (main): orca open-url returns browser_unavailable, "Browser automation is unavailable on this host." The issue reproduces on 1.4.230.

Testing

• I manually tested these changes locally
• Automated tests added/updated, or explained why not below

Fail on main, pass here:

• src/main/orcad/orcad-client-hosted-browser.test.ts: open-url and tab commands with no engine, the refusal text, paired versus CLI placement, the engine-plus-desktop list and selection, and close by index or current.
• Capability status with an engine-free factory: browser-capabilities-part-02.spec.ts.
• Desktop placement policy: client-creation-action-policy.test.ts.
• "Reopen on server" hidden without a server browser: client-hosted-browser-unavailable-notice.test.tsx.
• Composition parity: both runtimes install a factory that hosts desktop pages.

E2E:

• tests/e2e/orcad-serve-open-url-on-desktop.spec.ts, a real orcad orca serve with a paired, background-launched desktop, verified locally on macOS (ORCA_E2E_ORCAD_SERVE=1):
  1. Before a desktop hosts pages, open-url returns browser_host_unavailable with guidance.
  2. After the desktop opens a tab in the server's workspace, open-url succeeds.
  3. The desktop renders the page with client placement, and tab list shows it.
• tests/e2e/ssh-orcad-browser-capabilities.spec.ts (Docker lane): updated. A managed SSH orcad now advertises client hosting truthfully, but its desktop keeps SSH-routed tabs, so open-url refuses browser_host_unavailable.

Live on Linux (real host, isolated):

• Setup:
  • orcad was built from this branch in a throwaway /tmp directory on the Linux host. That host has no Orca install, so there was no engine, as in the report.
  • It ran with its own HOME and ORCA_USER_DATA on a free loopback port, reached from the Mac through ssh -L. Nothing outside the temp directory was touched, and everything was removed afterwards.
  • The remote status advertised browser.clientHost.v1.
• Before the desktop hosted a tab: orca open-url (on the Linux host) returned browser_host_unavailable with the guidance text.
• After the desktop opened a tab in the server's workspace:
  • orca open-url --url http://127.0.0.1:46732/ succeeded.
  • The page rendered on the Mac desktop with placement: client.
  • orca tab list on the server listed it as active.
• Only verified in tests: Windows hosts, and the Docker managed-SSH e2e (CI).

Static checks: the full static-analysis job ran locally (lint, code-quality gates, every ratchet), with typecheck for node and web.

Review

Codex (GPT-6.1 sol, high) and Opus reviewed the change across nine Codex rounds. The final Codex round and the final Opus pass found nothing. Every earlier finding was fixed:

• tab list/show/switch/close failed on an engine-free host.
• A paired "server" create was being sent to the desktop.
• An implicit close, or a close by index, could target the wrong tab.
• Selection could drift when engine tabs and desktop pages both exist.
• An engine-free host could report a "current" tab that automation would not use.
• A failing "Reopen on server" was offered by a host with no browser of its own.
• The engine's per-workspace current tab was lost.
• The unscoped current tab did not match unscoped automation.
• Retained pages could not be listed or closed after their desktop left.

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

• Two desktops hosting at once: open-url refuses browser_host_ambiguous, as the existing lease selection already does. Picking the desktop that owns the caller's terminal is a follow-up.
• Lease timing: the desktop attaches its lease when it opens a client-hosted tab, not on connect. This is the same as Electron orca serve today.
• Flaky status probe: if the desktop's status probe fails, a new tab falls back to server placement, which an engine-free orcad refuses with browser_unavailable.
• Profiles: orcad has no profile registry, so desktop-hosted pages use the default profile, and any other profile is refused as invalid_argument.

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]

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: f1f6ee7f-f87a-413c-88b8-3504fc85e9db

📥 Commits

Reviewing files that changed from the base of the PR and between 59a9da2 and a3cd947.

📒 Files selected for processing: 26

• config/scripts/ci-e2e-job-selection.test.mjs
• config/scripts/pr-e2e-source-routing.mjs
• src/main/orcad/electron-serve-browser-process.test.ts
• src/main/orcad/external-chromium-browser-process.test.ts
• src/main/orcad/orcad-browser-startup.test.ts
• src/main/orcad/orcad-browser-startup.ts
• src/main/orcad/orcad-client-hosted-browser.test.ts
• src/main/orcad/orcad-client-page-commands.ts
• src/main/runtime/browser/browser-client-page-close.ts
• src/main/runtime/browser/browser-client-page-opening.ts
• src/main/runtime/browser/browser-client-page-queries.ts
• src/main/runtime/browser/browser-commands.ts
• src/main/runtime/browser/browser-tab-close.ts
• src/main/runtime/browser/browser-tab-creation.ts
• src/main/runtime/construction/runtime-composition-parity.test.ts
• src/main/runtime/desktop-browser-bridge/desktop-browser-bridge-route.ts
• src/main/runtime/orca-runtime-tests/browser-capabilities-part-02.spec.ts
• src/main/runtime/runtime-browser-commands-factory.ts
• src/main/runtime/session-graph/session-graph-authority.ts
• src/renderer/src/components/browser-pane/client-hosted-browser-unavailable-notice.test.tsx
• src/renderer/src/components/browser-pane/client-hosted-browser-unavailable-notice.tsx
• src/renderer/src/lib/client-creation-action-policy.test.ts
• src/renderer/src/lib/client-creation-action-policy.ts
• src/renderer/src/lib/workspace-browser-tab-open.ts
• tests/e2e/orcad-serve-open-url-on-desktop.spec.ts
• tests/e2e/ssh-orcad-browser-capabilities.spec.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 change adds client-hosted browser page creation and tab operations for paired desktops. Orcad routes browser commands to client pages when appropriate and can advertise client hosting without an available browser engine. Renderer policies now account for desktop-hosted pages. Tests cover command routing, capability reporting, renderer behavior, and an end-to-end URL-opening flow.

Priority: ➖ Normal

Estimated code review effort:

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to a3cd9

The paired-desktop URL-opening change is mergeable after normal checks; no actionable blocker was established.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 45.24% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 42 functions across 26 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 clearly and concisely describes the primary change: making orca open-url open pages on a paired desktop.
Description check		The description is complete and follows the repository template. It explains the user impact, mechanism, rationale, linked issue, visual proof, testing, compatibility considerations, review notes, and…
Linked Issues check		Issue #30731 requires orca open-url on a paired orca serve using orcad to open the URL in the paired desktop. The implementation adds openBrowserUrlOnClient and orcadClientPageCommand paths …
Out of Scope Changes check		The changes remain connected to issue #30731. The new page-opening, page-query, close, capability, routing, and desktop-placement code supports client-hosted pages for the affected orcad flow. The t…

Full details: Description check

Explanation

The description is complete and follows the repository template. It explains the user impact, mechanism, rationale, linked issue, visual proof, testing, compatibility considerations, review notes, and checklist status.

Full details: Linked Issues check

Explanation

Issue #30731 requires orca open-url on a paired orca serve using orcad to open the URL in the paired desktop. The implementation adds openBrowserUrlOnClient and orcadClientPageCommand paths that create a client-hosted page without a local engine. The page uses the server workspace and server network execution host. The implementation returns browser_host_unavailable with guidance when no paired page host exists. The E2E test covers refusal before hosting, success after the desktop opens a tab, client placement, server loopback rendering, and CLI tab listing. Unit tests cover engine-free commands and capability advertisement.

Full details: Out of Scope Changes check

Explanation

The changes remain connected to issue #30731. The new page-opening, page-query, close, capability, routing, and desktop-placement code supports client-hosted pages for the affected orcad flow. The tab-list and selection changes support consistent CLI behavior after open-url creates a page. The policy and managed-SSH tests preserve the distinction between paired client hosting and SSH-routed tabs. Configuration changes select the related E2E coverage. No unrelated product behavior is demonstrated.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 2

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks: 💡

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