feat(browser): drive the running Arc by attaching, never launch a duplicate (PHNX-2399)

[muqsitnawaz]

What & why

agents browser on macOS launched a second Arc window/instance instead of driving the user's existing Arc — and could not reliably drive Arc at all. Arc is single-instance: relaunching the Arc binary with a fresh --user-data-dir doesn't start a second debuggable process — macOS routes the launch to the already-open Arc (started with no debug port), yielding a stray window and no CDP endpoint.

This makes an Arc profile attach to the running Arc, and fail loud when that Arc has no debuggable endpoint — it never silently spawns a duplicate.

Closes PHNX-2399.

Behavior change

• Attach, never launch (drivers/local.ts). For browser === 'arc', connectLocal no longer falls through to launchBrowser. It attaches to the running Arc's CDP endpoint, or throws arcAttachRequiredError — which names the profile, the port, and the one relaunch that fixes it:

  Arc is not exposing a CDP endpoint on cdp://127.0.0.1:9222 for profile "work".
  Arc is single-instance — agents browser attaches to your RUNNING Arc and never
  launches a second one … Quit Arc, then relaunch it with remote debugging:
    open -a Arc --args --remote-debugging-port=9222
  

• Select a Space (browser.ts). --target-filter (url:/title:) is now accepted for --browser arc, not just --electron. Arc does not expose Spaces as separate CDP contexts, so you bind the profile to a tab that lives in the Space you want; navigate reuses that tab in place (never hijacks a page you're reading).
• Fail clearly for the one CDP-only op (service.ts). Opening a brand-new tab (Target.createTarget) crashes Arc, so tab-creating verbs fail with an accurate, actionable error. The old message wrongly claimed Arc "exposes no CDP page targets" — it exposes them and honors Page.navigate; only tab creation is unsupported.
• Viewer message corrected (open-url.ts). Arc still falls back to the OS browser for anything a human reads, because showing a page needs its own fresh tab.
• Docs (docs/browser.md, new Arc — attach to your running window section) + CHANGELOG.

Verification

Live end-to-end against a real Arc is macOS-only and requires the operator to relaunch Arc with a debug port, so it can't run in CI or on this Linux worker. The real attach contract is unit-tested (the fail-loud path runs against a real socket, exactly like the existing #43 test), and the full browser suite passes:

$ npx vitest run src/lib/browser src/commands/browser.edit.test.ts src/commands/browser.use.test.ts src/lib/open-url.test.ts
 Test Files  35 passed | 1 skipped (36)
      Tests  595 passed | 1 skipped (596)

New tests: drivers/local.test.ts — Arc fails loud (never launches) both when nothing serves CDP on the port and when a non-CDP listener holds it; arcAttachRequiredError names profile/port/relaunch. Updated service.test.ts assertions to the accurate messages.

Follow-up

• Companion fleet-guidance update (phnx-labs/.agents skills/browser/browser-use.md) to teach the attach model — linked separately.
• Name-based Space switching would need Arc's AppleScript surface (out of scope; CDP has no Space concept).

🤖 Generated with Claude Code

[muqsitnawaz]

Non-author review (code-reviewer subagent — prix-cloud paused, #1767)

Verdict: APPROVE (clear to merge)

First pass found two BLOCKERS, both now fixed in bfb7275b1 and re-verified by re-tracing
the real runtime path (start() → navigate() → pickReusableTargetWithoutCreate()):

• BLOCKER feat(rotate): replace rotate with balanced (weighted random) #1 — --target-filter was accepted/stored for Arc but never consulted at
  drive time (a lying capability). pickReusableTargetWithoutCreate (service.ts:778-816)
  now parses conn.targetFilter and scopes the reusable-tab set to the url:/title:
  substring, refusing (returns undefined) when nothing matches rather than borrowing an
  unrelated tab — the same contract pickWindowTarget already held for Electron. Covered by
  a bound url:target-filter selects the matching Space tab, never an unrelated one and
  refuses rather than borrowing an unrelated tab when the filter matches nothing
  (service.test.ts:1195-1233), built on realistic multi-tab CDP target lists.

• BLOCKER feat(secrets): move bundle storage from YAML to Keychain (iCloud-syncable) #2 — the documented navigate --profile arc --url … first-use flow threw on a
  task-less profile. start()'s implicit-navigate branch (service.ts:669-684) now routes
  Arc through this.navigate(...) exactly like Electron, so the first call attaches to a
  reusable tab instead of hitting createPageTarget's refusal. The retained
  start with a url throws the clear error and never creates a target test still passes
  (empty target list → genuine fail-loud preserved, zero Target.createTarget), and the new
  start({url}) on a task-less Arc profile ATTACHES to a reusable tab reproduces the docs' step 3.

The stale browserType doc comment (earlier NICE) is corrected too. Required Tests / test
green; full src/lib/browser/ suite 567 passed. No remaining findings.