fix(browser): stop bridge token divergence (atomic write + host-only + reload)

[stephane-segning]

Stacked on #55 (base = claude/browser-bad-token-hardening). Merge #55 first, then retarget this to main. The diff here is #57-only.

What

Fixes the bug we diagnosed live: the extension sends the current token but a long-lived host (an IDE-embedded OpenCode) keeps rejecting it as bad_token.

Root cause

Every instance wrote bridge.json with a non-atomic writeFileSync at load. When the desktop app boots many instances at once, one can read the file mid-write (torn/empty), fall through to generate a fresh token in resolveSharedToken, and overwrite the shared one — orphaning the already-running host, which resolves its token once at boot and never re-reads. Confirmed in a real log: bridge.json held c856e1cf… while the running host still checked against ea9cdad6…, so every handshake (with the correct file token) was rejected.

Fix — three layers

1. Atomic writeBridgeFile — per-writer pid+uuid temp then rename (+ unlink on failure). A reader can never catch a torn write, so no spurious regenerate. (Same lesson as fix(oauth2): per-writer temp file for model-sync cache (concurrent-boot ENOENT) #54.)
2. Host-only write — writeBridgeFile moved into the onHost path instead of running unconditionally at load, and it never clobbers a token the file already carries. A guest that resolved a fresh token on a transient miss can no longer overwrite the live host's token; the file stays the single source of truth.
3. Host reloads on mismatch — on a bad-token handshake the broker re-reads bridge.json (injected reloadToken dep) and adopts a rotated token (logs browser_bridge_token_reloaded), then re-checks the handshake. So a rotation reaches a running host within the extension's retry window — no process kill needed (the exact thing that bit us: rotating the file did nothing while the old host lived).

Tests / docs

• token-file: atomic concurrent-write test (no .tmp leftovers, last writer wins).
• broker: adopts a rotated token on mismatch; still rejects when the reload doesn't match either.
• Updated the opencode.test.ts token-file mock (new readBridgeFile export).
• docs/browser.md troubleshooting row (host now auto-reloads; restart is the older-build fallback) + CHANGELOG.md.

Full pre-push gate green (browser 119 tests, 91% stmts — every coverage threshold met).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[gemini-code-assist]

Code Review

This pull request addresses bridge token divergence issues by implementing atomic writes for bridge.json and enabling long-lived hosts to auto-reload rotated tokens on handshake mismatches. Additionally, token writing and advertising are restricted to the host instance. A review comment points out a critical bug in advertiseToken where port changes and explicit tokens are ignored because the code only checks for the existence of a shared token before writing. A suggestion is provided to check if the existing port or token has changed before skipping the write.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

⚠️ Critical Bug: Port Changes and Explicit Tokens are Ignored / Stale Tokens Logged

The current implementation of advertiseToken checks if (!shared) before writing the token to bridge.json. This introduces several critical issues:

1. Port Changes are Ignored: If bridge.json already exists with a token (e.g., from a previous run on port 4517), shared will be truthy. If the host is restarted on a different port (e.g., 4518), writeBridgeFile is never called. Thus, bridge.json is never updated with the new port, breaking discovery for guest adapters (like the MCP server) which will continue trying to connect to the old port.
2. Explicit Tokens are Ignored: If the user configures an explicit token, it will not be written to bridge.json if a token already exists. Furthermore, on a handshake mismatch, the broker's reloadToken will read the stale token from bridge.json and overwrite the explicit token, completely ignoring the user's explicit configuration.
3. Stale Token Logging: When the port or token changes, shared ?? token will evaluate to the stale shared token from the file, logging an incorrect token that mismatches the actual running broker's token.

Solution

We should only skip writing if the file already exists and matches both the current port and token. Otherwise, we must write the updated port and token to bridge.json to keep it as the single source of truth. Additionally, ensure that connection tokens or critical initialization logs are emitted dynamically on every transition to active/host mode rather than only once during initial startup.

Suggested change

	const advertiseToken = () => {
	const shared = readBridgeFile()?.token;
	if (!shared) {
	writeBridgeFile(options.port, token);
	}
	if (source !== "explicit") {
	logger.info("browser_bridge_token", { paste_into_extension: token, source, mode: "host" });
	logger.info("browser_bridge_token", {
	paste_into_extension: shared ?? token,
	source,
	mode: "host"
	});
	}
	};
	const advertiseToken = () => {
	const existing = readBridgeFile();
	if (!existing || existing.port !== options.port || existing.token !== token) {
	writeBridgeFile(options.port, token);
	}
	if (source !== "explicit") {
	logger.info("browser_bridge_token", {
	paste_into_extension: token,
	source,
	mode: "host"
	});
	}
	};

References

1. Ensure that connection tokens or critical initialization logs are emitted dynamically on every transition to active/host mode (such as during re-election or failover), rather than only once during initial startup.

[stephane-segning]

Addressed the Gemini high-priority finding on advertiseToken — it was a real regression I introduced. Fixes:

• The host now writes bridge.json whenever the file does not match its (port, token) (not just when some token exists), so a port change stays in sync and an explicit operator token overwrites a stale generated one.
• reloadToken is disabled for an explicit token, so a file value can never override a pinned secret.
• Logs the host's real token, not the stale file value.
• Added regression tests (port-change rewrite, explicit-over-stale, no-op when matching).

Rebased onto the updated #55.