fix(browser): name the CloakBrowser session cap instead of "target closed" (#225)

[Agnik47]

Addresses the error-mapping half of #225 (suggested fix 2).

Cause

On CloakBrowser's free tier a second concurrent profile exits with code 76. Playwright surfaces the dead target as Target page, context or browser has been closed, which is also what an externally closed browser, a crash, and a never-started browser all produce. Nothing in the repo matched exit code 76, so the licensing cap arrived as a generic navigation failure:

error:
  code: COMMAND_EXEC
  message: "Pre-navigation to https://x.com failed: page.goto: Target page, context or browser has been closed"

The reporter traced the daemon, profile multiplexing, and CDP end to end before finding the cap — the message pointed nowhere.

Fix

Two mappings onto the BrowserConnectError / 'profile-disconnected' kind that already exists for this:

• Launch: launchProfileRuntime checks the launch failure for exit code 76 first and reports the session limit and CLOAKBROWSER_LICENSE_KEY.
• Navigation: when a navigation still fails with a closed-context error after the existing one-shot invalidate-and-retry, the raw error is replaced with one naming the profile that disconnected. The Playwright text is kept in the message, so the cause is not lost.

Another live profile is the one cause that can actually be checked, so it picks the hint rather than being asserted blindly:

• another profile up → the free-tier one-browser-at-a-time cap, and how to lift it;
• alone → webcmd daemon restart, and WEBCMD_WINDOW=foreground on macOS.

Deliberately unchanged: the retry ladder itself, non-closed navigation failures (still rethrown by identity), and the page-creation paths — newPage/getPage acquisition still reject with the raw text that existing tests pin.

Not fixed here

Suggested fix 1, the macOS background open -g -n instance being sudden-terminated by LaunchServices, is a CloakBrowser/macOS problem I cannot reproduce or verify on Windows. This PR only makes its symptom legible: a browser that dies on its own now reports a disconnect with a restart hint instead of a navigation error.

Tests

src/browser/runtime/local-cloak/session-manager.test.ts:

• a launch rejecting with Process exited with code 76 produces BROWSER_CONNECT / profile-disconnected, names the license key, and preserves the original text;
• with a peer profile alive, a repeatedly closed navigation on actor names peer and the one-browser-at-a-time cap (the issue's concurrent-profile repro);
• with no other profile alive, the same failure does not blame concurrency and points at daemon restart;
• net::ERR_NAME_NOT_RESOLVED is still rejected by identity, with no extra launch.

npx vitest run --project unit src/browser — 47 files, 752 passed, 2 skipped. npm run typecheck and npm run check:typed-error-lint clean.

[github-actions]

🔴 Documentation update likely missing — high confidence

The automated review found 2 likely missing documentation updates.

Findings

1. DOCS — Launching a CloakBrowser profile now maps exit code 76 to a session-cap error that tells users to close the other profile or set CLOAKBROWSER_LICENSE_KEY.
   • Changed: src/browser/runtime/local-cloak/session-manager.ts
   • Evidence: throw this.sessionCapError(profileId, err);
   • Suggested update: docs/cli-reference.mdx
   • Why: The troubleshooting and browser-selection sections explain daemon restarts and sessions, but they do not mention CloakBrowser's free-tier one-browser cap, exit code 76, or the license-key hint that now appears on launch failure.
2. DOCS — A repeated closed-context navigation failure now becomes a browser-disconnected error with a restart hint, and on CloakBrowser can also point to another live profile holding the one-browser cap.
   • Changed: src/browser/runtime/local-cloak/session-manager.ts
   • Evidence: if (attempt !== 0) throw this.browserDisconnectedError(profileId, error);
   • Suggested update: docs/cli-reference.mdx
   • Why: The docs describe generic session and daemon recovery, but they do not document that closed-context navigation after retry is now reported as profile disconnection with either a concurrency hint or `webcmd daemon restart` / `WEBCMD_WINDOW=foreground` guidance.

This review is advisory and does not block merging.

[ankitranjan7]

Thanks for the fix and the regression tests — merged!