Start agent browsers on demand and close unused ones (GODM-30)

[danielehrhardt]

What does this change?

GODM-30: Godmode started Chrome windows it didn't need and left them running.

Why it happened

• Every run launched the agent's Chromium before Claude even started (browserMcpServer → launchBrowser), even runs that never open a website: a one-line "reply hi" chat, condition checks, delegations. A headed window then stayed open for 15 minutes. An orchestrator delegating to a workspace agent opened one window per profile, i.e. two windows for one request.
• On macOS the browser is started through LaunchServices, so it isn't a child of the core. When the core was killed (a forced quit, a crash, the test suite), its Chrome stayed open. The next start adopted it but kept it for the full keep-alive.

What changes (built on the per-run endpoint from GODM-28)

• On-demand launch. browserMcpServer no longer launches the browser. The run's endpoint (proxy.ts) starts it when browser-use first asks for /json/version, on its first browser tool call. Runs that never browse never start a browser. A missing Chrome is still checked up front, so the "Browser tools are unavailable" notice still appears.
• Leftovers close at startup. A browser adopted from an earlier core closes right away unless something still uses it (another CDP client attached, a focused window, a live-view watcher).
• Shorter idle close. The default keepAliveMinutes goes from 15 to 5. Users who already saved browser settings keep their stored value.
• Launch problems are visible. browser-use can't recover within a run when its connect fails, or takes longer than its 15 s timeout. When that happens, the run now gets a warning that says why.
• The idle sweep won't close a browser that was just handed to a run.
• The settings copy now says browsers start on demand.

How was it tested?

• pnpm typecheck passes, and bun test in packages/core passes: 699 pass, 0 fail.
• GODMODE_E2E=1 bun test test/browser-mcp.e2e.test.ts passes with the real browser-use 0.13.10 server:
  • no browser runs after tools/list; one runs after browser_navigate;
  • the parallel two-chat test passes.
• New integration tests in cdp-integration.test.ts, against a real Chrome:
  • the browser starts only on the endpoint's /json/version
  • a leftover browser is closed at startup
  • a failed start is reported to the run
• Manually on macOS, with a real core and Claude:
  • A tool-free chat started no Chrome.
  • A browsing chat started exactly one window.
  • After kill -9 of the core, the next start closed the leftover Chrome.
  • With the profile blocked by another Chrome, the chat showed the warning.

Checklist

• pnpm typecheck and pnpm test pass
• cargo clippy / cargo test pass (if apps/desktop/src-tauri changed): not changed
• API changes are reflected in packages/shared and apps/desktop/src/lib/api.ts: no API change
• No secrets, tokens or personal data in code, fixtures, logs or screenshots
• Docs updated where behaviour changed (docs/ARCHITECTURE.md → Browser, "On demand")