Summary

• in Cloud API V4 only, automatically connect browser_execute to the run-start BU_CDP_WS and attach its existing page before the first snippet
• bootstrap exactly once per logical BrowserCode session, including across timeout-driven Session replacement
• never reconnect automatically after a dropped socket or timeout, so a run that explicitly switched browsers cannot silently return to its original browser
• make explicit browser switches retire the prior socket and clear its target attachment instead of leaking the old socket and retaining a stale session ID
• keep local and eval BU_CDP_WS flows explicit and preserve explicit wsUrl or profileDir connections
• make no-argument connect() idempotent for compatibility with the current Cloud prompt during rollout

Root cause

Cloud V4 starts a fresh bcode process for each user run while the AgentCore runtime and remote browser can remain alive. The fresh process has no in-memory WebSocket or target attachment, so a direct Page.navigate fails with Not connected even though the browser and page are alive. In staging session 12d6be06-d2f9-426a-9821-80a85e9cac8b, the first SAP navigation failed exactly this way and succeeded immediately after an explicit connect plus use.

The runtime now owns only the safe invariant: a fresh V4 process attaches its run-start browser once. Recovery remains deliberate because BU_CDP_WS does not change when an agent creates and switches to another browser during a run.

The deeper reconnect audit also found that explicit connect({ wsUrl }) replaced Session.ws without closing the prior socket or clearing activeSessionId. A command on the new socket could therefore carry a target session ID created by the old browser. Explicit replacement is now atomic from the Session perspective: pending old calls fail, the old socket is retired, stale messages are ignored, and target attachment is cleared.

Compatibility

• V4_RUN_ID plus BU_CDP_WS or BU_CDP_URL: one initial automatic connect and target attachment
• BU_CDP_WS or BU_CDP_URL without V4_RUN_ID: unchanged explicit flow for evals and local harnesses
• dropped socket, browser_execute timeout, or explicit alternate browser: no automatic fallback to the run-start endpoint
• failed initial bootstrap: error surfaces once, then an explicit replacement wsUrl remains usable
• explicit browser switch: old socket and target attachment are retired; the caller must re-list targets and attach on the new socket

Tests

• packages/bcode-browser: 33 passed, 8 existing live-browser skips, 0 failed
• focused changed-file lint: 0 errors (the repository-wide lint still has one unrelated existing UI error)
• package and root filtered typechecks: 16/16 passed with Bun 1.3.14
• native compiled binary build and version smoke test passed with Bun 1.3.14
• focused coverage for direct Page.navigate, idempotent compatibility, concurrent bootstrap, dropped sockets, timeout replacement, eval/local isolation, failed bootstrap recovery, and explicit browser switching with stale-target retirement