Proxy error on webview open: race condition with dev server startup

[7tg]

Description

When running plannotator review (or plannotator annotate) over SSH Remote, the VSCode webview opens with a "proxy error" because the cookie proxy attempts to connect to the upstream dev server before it's fully listening.

Steps to Reproduce

1. Connect to a remote machine via VSCode SSH Remote
2. Run plannotator review from an integrated terminal (or via Claude Code skill)
3. The plan builds, the dev server starts, and open-in-vscode triggers the webview
4. The webview panel opens but shows "proxy error"

Expected Behavior

The webview should load the plannotator UI without errors.

Actual Behavior

The cookie proxy in the extension (cookie-proxy.ts) forwards the request to the upstream dev server, but the server isn't ready yet. The proxyReq.on("error") handler fires and returns a 502 with "proxy error".

Workaround: Reloading the webview via Developer: Reload Webviews or re-opening via Plannotator: Open URL in Editor works once the dev server is up.

Root Cause

In extension.cjs, openInPanel immediately creates the proxy and opens the webview as soon as the IPC server receives the URL. However, the plannotator CLI calls openBrowser(url) right after starting the dev server — there's no guarantee the server is accepting connections by the time the proxy forwards the first request.

Suggested Fix

Add a short retry/backoff in the cookie proxy when the upstream connection fails, e.g.:

• Retry the upstream request 2-3 times with a small delay (200-500ms) before returning 502
• Or have the webview auto-reload after a brief delay if it receives a proxy error

Environment

• OS: Linux (Ubuntu, remote via SSH)
• VSCode: 1.109.2 (SSH Remote)
• Extension version: 0.5.1
• plannotator CLI: ELF binary (latest)

[7tg]

Fix implemented

Two issues were identified and fixed:

1. Proxy race condition (original issue)

Belt-and-suspenders approach:

• Cookie proxy retry (cookie-proxy.ts): Buffers request body upfront, retries up to 3 times with exponential backoff (200/400/800ms) on connection errors before returning 502
• Webview auto-reload (panel-manager.ts): Injected script sends postMessage("plannotator-ready") on successful load. Wrapper page starts a 3-second timer — if no ready signal received, reloads the iframe once (max 1 reload to prevent loops)

2. Webview not opening at all in SSH Remote sessions (discovered during testing)

Root cause: handleServerReady() only called openBrowser() in remote sessions if PLANNOTATOR_BROWSER env var was set. VS Code's environmentVariableCollection injects this into terminal shells, but background processes spawned by Claude Code don't inherit terminal env vars — so the review server process never had PLANNOTATOR_BROWSER, and openBrowser() was never called.

Fix — file-based IPC registry:

• Extension writes its IPC port to ~/.plannotator/vscode-ipc.json keyed by workspace path on activation, removes it on deactivation
• openBrowser() (browser.ts) falls back to reading the IPC registry and hitting the extension's IPC endpoint directly when shell-based open fails
• handleServerReady() (shared-handlers.ts) now always calls openBrowser() regardless of remote status, since the IPC fallback handles the remote case
• Multiple VS Code windows are handled correctly via workspace-path-scoped entries with longest-prefix matching

Files changed

• apps/vscode-extension/src/cookie-proxy.ts — retry + postMessage signal
• apps/vscode-extension/src/panel-manager.ts — auto-reload fallback
• apps/vscode-extension/src/extension.ts — IPC registry write/cleanup
• packages/server/browser.ts — IPC registry fallback in openBrowser
• packages/server/shared-handlers.ts — always call openBrowser in handleServerReady

Extension bumped to v0.5.2.