Port Registrar: browser agent + Chrome extension migration + origin allowlist

[TalZaccai]

Depends on PR 2 (code agent migration). Branched off talzacc/code-and-localview-migration and must merge after it. Reuses the discoverPort() helper, the registrar SDK, and the async-start/close pattern proven there.

Why

PR 2 migrated the code agent and proved the discovery handshake against an in-repo VS Code extension. The browser agent is the second concrete migration and exercises a meaningfully different consumer shape:

• The Chrome / Edge extension is out-of-process and distributed separately — discovery has to work from a service worker (MV3) over isomorphic-ws, not Node ws.
• A single browser-agent server has two simultaneous client populations — the extension(s) and the Electron shell's inline browser — sharing one session id; the lifecycle / refcount accounting differs from code's per-schema model.
• The Electron shell is the most-used host, so the BROWSER_WEBSOCKET_PORT escape hatch matters more for debugging than CODE_WEBSOCKET_PORT did.

This PR also closes a design gap that PR 2 quietly skipped: per design §4.2, every per-agent listener migrated to the PortRegistrar must Origin-gate WebSocket upgrades to keep an OS-assigned ephemeral port from being dialed by arbitrary web pages on the same host. Both the browser AND the code agent get the gate in this PR.

What this PR changes

browser agent server: async start + close + Origin gate

AgentWebSocketServer is now an async start(port = 0) factory rather than a constructor. It resolves only after the listening event so the OS-assigned port is readable synchronously via .port, and rejects on EADDRINUSE under fixed-port overrides instead of swallowing the error in a permanent error listener. close() now awaits server.close() and proactively closes all tracked client sockets first, so a rapid disable → re-enable cycle under BROWSER_WEBSOCKET_PORT rebinds cleanly.

The new verifyClient callback applies isAllowedAgentOrigin() to every upgrade request before the connection event fires. Allowed: chrome-extension://*, moz-extension://*, http(s)://localhost(:port), http(s)://127.0.0.1(:port), and absent / null Origin (Node ws clients don't send one; the bridge binds loopback so this is OS-restricted). Anything else gets HTTP 403.

code agent: Origin parity

CodeAgentWebSocketServer gets the same gate with a code-agent-specific allowlist (vscode-webview://, vscode-file://, vscode-resource:// plus loopback / absent Origin). The two originAllowlist files are deliberately duplicated rather than shared — different scheme prefixes per agent, ~30 LOC each, and a shared module would force every agent that opens a port to depend on a new common package.

Handler lifecycle: refcounted shared server, idempotent cleanup

browserActionHandler.mts no longer constructs the server at module load. It now mirrors PR 2's pattern: module-scoped sharedBrowserServer, sharedStartingPromise, sharedClosingPromise, sharedBrowserRefCount, with an ensureSharedBrowserServer() that serializes concurrent enables and waits for any in-flight close before re-binding (matters under fixed-port override; with port = 0 the OS would just hand out a different port).

The browser agent's lifecycle differs from code's in two ways worth flagging for reviewers:

1. Per-session refcount, not per-schema — updateBrowserContext early-returns for non-browser schemas, so refcount accounting tracks agentContext.browserSchemaEnabled (always 0 or 1 per session) rather than enabled.size.
2. Two cleanup paths converge on one helper — the prior code only released its session registration in closeBrowserContext, leaking on the disable path. This PR funnels both updateAgentContext(false, ...) and closeBrowserContext through cleanupBrowserSession(), which is idempotent: if browserSchemaEnabled is already false, it bails without touching shared state.

BROWSER_WEBSOCKET_PORT is the new escape hatch (mirrors CODE_WEBSOCKET_PORT); malformed values fall back to OS-assigned with a debug log rather than crashing.

Chrome extension: discovery-then-connect

extension/serviceWorker/websocket.ts now does the same dance the Coda extension does in PR 2:

1. Read agentServerHost from chrome.storage.sync (default ws://localhost:8999/).
2. Call discoverPort("browser", "default", { url: agentServerHost }) against the agent-server's discovery channel.
3. Construct the browser-agent URL by reusing the agent-server host and substituting the discovered port.
4. On unreachable or not-registered, return undefined and let the 5s reconnect loop retry. No hardcoded fallback — same call the user made for PR 2 (this is a research project, no lingering external clients to maintain back-compat for).

Three pre-existing extension bugs are fixed in the same patch since they directly block the new flow:

• Settings cache never invalidated — the module-level settings cache was loaded once and never refreshed, so a user changing agentServerHost saw the old endpoint until the service worker restarted. Cache removed; settings re-read on every createWebSocket.
• Reconnect timer leak — reconnectWebSocket() scheduled a fresh setInterval on every call, and the onclose handler called it unconditionally, so flapping connectivity stacked timers indefinitely. Now guarded by a module-level singleton.
• Options page rejected blank input — the WebSocket-host field rejected empty strings, so users couldn't say "use the default". Now blank means "use AGENT_SERVER_DEFAULT_URL".

The setting itself is renamed websocketHost → agentServerHost to match the dispatcher path (dispatcherConnection.ts already used this key) and reflect that the user now configures the agent-server URL, not the per-agent port.

Validation

• pnpm --filter browser-typeagent build — green (full agent + extension + Vite client builds).
• pnpm --filter agent-sdk --filter agent-rpc --filter agent-dispatcher --filter browser-typeagent build — green (post-fix rebuild across all touched packages).
• pnpm --filter code-agent build && pnpm --filter code-agent test — green (18/18 still pass).
• pnpm --filter agent-dispatcher test — 669/669 pass, including agentReadiness.spec.js and sessionContext.spec.js.
• pnpm --filter browser-typeagent test:local — 253/254 pass. The one failure is a pre-existing flake in contentDownloader.test.ts ("invalid URL gracefully" timing out at 5s); the file isn't touched by this PR (last edited in bbcb8f30).
• New / updated unit tests:
  • agentWebSocketServer.test.ts — 28 tests. Exercises async start, close closing tracked clients first, and the Origin allowlist (covers chrome-extension://, http://localhost:8081, absent Origin, and rejection of https://evil.example.com).
  • websocket.test.ts — 5 tests. Covers discoverPort-driven endpoint resolution and asserts only one setInterval is scheduled across repeated reconnectWebSocket() calls (the singleton fix).
• Manual smoke test against the pr-3-manual-tests.md checklist confirmed end-to-end after both fixes: extension auto-discovers the port, @browser open a new tab to bing.com dispatches without manual @config agent refresh browser, and getWebFlowsForDomain round-trips successfully through the SW ↔ agent webAgent proxy.

Reading order for reviewers

This PR is two commits (the follow-up commit is intentionally separate to keep the smoke-test fixes reviewable in isolation). Suggested reading order:

1. agents/browser/src/agent/{agentWebSocketServer,originAllowlist}.mts + tests — the server-side primitives (async start/close, Origin gate). Identical structure to the PR 2 CodeAgentWebSocketServer.
2. agents/browser/src/agent/{browserActionHandler,browserActions}.mts — the lifecycle wiring. The interesting bits are ensureSharedBrowserServer / cleanupBrowserSession and the convergence of the disable + close paths. Also contains the localHostPort = 0 reset and the notifyReadinessChanged() calls in the WS lifecycle callbacks.
3. agents/code/src/{codeAgentWebSocketServer,originAllowlist}.ts — Origin parity for the code agent (small).
4. agents/browser/src/extension/serviceWorker/{websocket,storage,index}.ts + views/options.{ts,html} — the extension consumer. Demonstrates discoverPort() from MV3 and the three bug fixes (cache, reconnect singleton, blank-input).
5. agentSdk/src/agentInterface.ts + dispatcher/src/execute/sessionContext.ts + agentRpc/src/{types,client,server}.ts — the new notifyReadinessChanged() API and its in-process + RPC plumbing. Mirrors the existing reloadAgentSchema() pattern.

Follow-up PRs

PR	Scope
4	Migrate visualStudio host webview
5	Migrate onboarding-scaffolder + tighten originAllowlist on agentServer