fix(connect): honor timeoutMs on profileDir poll; re-rank Way 2 docs (Chrome 147 DevToolsActivePort regression)

[Alezander9]

Summary

Two independent fact-check reports (macOS Chrome 147.0.7727.138, Windows Chrome 147.0.7727.139) revealed the same Chrome 147 behavior change: DevToolsActivePort is not written when Chrome is launched with a custom --user-data-dir. Our docs led with session.connect({ profileDir }) for Way 2, which now ENOENTs on every Chrome 147+. The /json/version -> wsUrl route still works on every Chrome version that supports remote debugging.

This PR re-ranks the Way 2 docs to lead with what works, fixes the visible timeoutMs bug the testers spotted, and absorbs the smaller doc nits.

Changes

session.ts — real bug fix:

• readDevToolsActivePort now honors the caller's timeoutMs instead of a hardcoded 30 s deadline. The Mac tester passed timeoutMs: 5000, the error said "after 30s" — that mismatch is gone.
• Error message now reports the polled path, actual elapsed time, the timeout asked for, and a hint to fall back to /json/version. Per the Mac tester's ask: future agents debugging this can catch the bug from the message alone.

skills/BROWSER.md:

• Way 2 now leads with fetch("http://127.0.0.1:9222/json/version") -> webSocketDebuggerUrl -> session.connect({ wsUrl }). { profileDir } is demoted to "older Chrome / chrome://inspect Way 1 path" with an explicit note that Chrome 147+ doesn't write the file under custom --user-data-dir.
• Replaced the /tmp/bcode-chrome example with ./.bcode/way2-chrome and noted any writable path works.
• Added Way 2 troubleshooting bullets: (a) "DevTools listening on …" prints before the bind succeeds and is not a readiness signal (port collisions log success then exit); (b) Windows: launching while another Chrome is running silently no-ops the debug flags; (c) { profileDir } ENOENT on Chrome 147+.

skills/cloud-browser.md / Way 3 example in BROWSER.md:

• Noted the resolved URL is wss://, the provision endpoint returns 201, and surfaced the extra response fields — particularly timeoutAt (lifecycle) and recordingUrl (playback).

What we're NOT changing

Way 1 (user's existing profile via chrome://inspect) is unaffected on every reported platform. The DevToolsActivePort reads on Way 1 work fine because the user-data-dir is Chrome's platform default — Chrome only suppresses the file on custom dirs.

Verification

• Typecheck clean (@browser-use/bcode-browser, full root filtered).
• connect-env.test.ts, skills.test.ts pass.
• No source-level breakage; signature change is internal (readDevToolsActivePort -> takes timeoutMs; resolveWsUrl -> takes timeoutMs). Public Session.connect() signature unchanged.

Sources

• Mac fact-check report and Windows fact-check report from thread C0ADZBZHW2V. Both confirm the Chrome 147 DevToolsActivePort regression and the listed doc nits.

[cubic-dev-ai]

No issues found across 3 files