feat(server): peer re-elects to host when its host dies

[chrischall]

Problem

The concentrator role (host vs peer) is elected once, in FetchproxyServer.doConnect() via electRole() (a 127.0.0.1:37149 bind race). After that, ensureConnected() short-circuits forever on the live handle. A peer dials the host's WebSocket — but peer.ts only used ws 'close' to reject the first-ready gate; it never told FetchproxyServer the host vanished. So when the host process died, the peer was stranded as a peer permanently: every subsequent verb call reused the dead handle and failed with peer WS closed before ready, even though the port was now free and it could trivially become the new host.

Observed in the field: a Claude Desktop app held the bridge host (fetch-only); a second, byte-delivery-capable MCP came up as a peer. Killing the desktop host freed the port, but the peer stayed stuck with no way to recover short of a full MCP process restart.

Fix — lazy teardown + re-election

• peer.ts: expose onClose(), fired from the existing ws.once('close') handler (mirrors the onRenegotiate/onPendingPair callback pattern). Intent-agnostic — fires on any close.
• ws-server.ts: on the peer's onClose, tear down the stranded handle and reset role so the next verb call re-elects via electRole() — becoming the new host on a freed port, or a peer of whoever grabbed it. A closing flag (latched in close(), re-armed in doConnect()) distinguishes an intentional shutdown from host death; it's latched across the async WS-close window rather than reset in close()'s tail to avoid a race.
• host.ts: close() now also closes the electRole HTTP server. wss.close() does not close an externally-provided server, so the port stayed bound until process exit — a leaked listener, and the blocker for a same-process re-election.

Lazy (re-elect on next call) was chosen over eager/background self-heal and capped-retry variants: it matches the existing lazy-connect philosophy and needs the least code. Eager self-heal and dial-retry-on-host-mid-restart are noted as future work in the design spec.

Tests (TDD)

• peer.test.ts: onClose fires when the host WS closes.
• integration/reconnect.test.ts: a stranded peer re-elects to host on the next call after its host dies; an intentional peer.close() does not re-elect (closing guard).

Full server package suite green (360 tests); whole repo green (762, excluding stale local worktree copies). npm run build clean across all workspaces.

Design spec: docs/superpowers/specs/2026-06-03-peer-rehost-on-host-loss-design.md.

🤖 Generated with Claude Code

[claude]

Claude finished @chrischall's task in 6m 47s —— View job

---

PR Review

• Read CLAUDE.md conventions
• Read PR diff and changed files
• Review for correctness, edge cases, conventions
• Check test coverage
• Post findings

---

Verdict: pass — no 🔴 Important findings. Two 🟡 nits (inline).

The fix is well-reasoned and correctly implemented. Here's the analysis:

Correctness of the closing flag + peerHandle === null guard

The two-guard approach at ws-server.ts:1103 is sound. close() sets peerHandle = null synchronously (no await between the peerHandle.close() call and the null assignment), so any delayed close event from the torn-down socket always sees a null peerHandle. The closing flag provides a fast path for the same synchronous window, and doConnect() re-arms it only after it holds the new handle — so the guard is always accurate.

host.ts HTTP server close

The leak fix (opts.httpServer.close() inside the wss.close() callback, host.ts:341) is exactly right. wss.close() stops accepting new upgrades but does not close the underlying http.Server, leaving the port bound — a same-process re-election would fail with EADDRINUSE without this. The callback nesting preserves the shutdown order (WS clients drained first, port released second).

Test coverage

Both new scenarios are covered: stranded-peer → re-elects to host, and intentional close() → does not re-elect. The peer.test.ts unit test directly verifies the onClose callback fires on WS close. The integration tests use the real electRole() bind race on isolated ports (41090/41091), consistent with the existing integration suite's pattern.

console.* discipline

No console.log/console.debug/console.info introduced — the new code paths are silent, as required by CLAUDE.md.

🟡 Nits (inline):

1. ws-server.ts:1105 — rejectAllPending() without a custom reason emits "extension disconnected" when the actual cause is host process death; misleads diagnostics. View →
2. docs/superpowers/specs/…:5 — spec status still says "pending implementation"; should be updated to reflect this PR. View →

[claude]

🟡 Nit — misleading default error message

rejectAllPending() is called without a custom reason here, so callers receive "extension disconnected" — but the actual cause is that the upstream host process died, not an extension event. This makes it harder to distinguish a peer-loss failure from a genuine extension disconnect in logs/tool errors.

Suggested change

	this.rejectAllPending();
	this.rejectAllPending('fetchproxy host process died — peer re-electing');

[claude]

🟡 Nit — stale status

This spec is landing in the same PR as the implementation, so the status should reflect that.

Suggested change

	**Status:** approved (design), pending implementation
	**Status:** implemented (PR #100)