feat(connect): honor BU_CDP_WS env var in session.connect()

[Alezander9]

Why

Eval harnesses and CI need to hand the agent a preconfigured browser without burying the WS URL in the prompt. The pre-port Python harness honored BU_CDP_WS for exactly this; v0.1.0 lost it during the TS port. Re-adopting the same convention.

What

When session.connect() is called with no args, check BU_CDP_WS (and alias BU_CDP_URL) before the OS scan:

async connect(opts: ConnectOptions = {}): Promise<void> {
  const timeoutMs = opts.timeoutMs ?? 5_000
  if (opts.wsUrl || opts.profileDir) { /* unchanged */ }
  const envWsUrl = process.env.BU_CDP_WS ?? process.env.BU_CDP_URL
  if (envWsUrl) {
    await this.openWs(envWsUrl, timeoutMs)
    return
  }
  /* unchanged OS scan */
}

Explicit { wsUrl } / { profileDir } calls ignore the env var. If the env var is set but the endpoint is unreachable, the error surfaces rather than silently falling through to OS scan — matches Python harness PR #300, which closed exactly that hole (was billing for a cloud browser while silently using a local Chrome).

Scope

• packages/bcode-browser/src/cdp/session.ts — ~5 line addition in connect(), doc-comment expanded to spell out the precedence.
• packages/bcode-browser/skills/BROWSER.md — one-paragraph note under "Connecting".
• packages/bcode-browser/test/connect-env.test.ts — 4 tests covering: BU_CDP_WS path, BU_CDP_URL alias, explicit-opts-override-env, fail-fast on stale env URL. Uses a tiny Bun.serve WS upgrade endpoint; no Chrome needed.

+117 lines, mostly the new test file.

Verified

• bun typecheck clean from packages/bcode-browser/ and from repo root (filtered turbo run).
• bun test from packages/bcode-browser/: 12 pass + 5 chrome-gated skip (was 8 + 5; +4 from this PR).

Eval team usage

export BU_CDP_WS=ws://path-to-preconfigured-browser/devtools/browser/<uuid>
bcode --prompt "do the eval task"

The agent's natural snippet await session.connect() lands on the eval browser. No prompt boilerplate, no skill changes per-eval, no risk of the model picking a different browser.

[cubic-dev-ai]

No issues found across 3 files