Fix audit findings: reconnect watchdog, DO alarm contention, state-machine guards, registry bounding (v1.2.0)

[adewale]

What

Fixes the 16 defects surfaced by a full-system audit — a client-side reconnect watchdog that ejected players after any network blip, four Durable Object lifecycle bugs (alarm clobbering, room leaks, a match-reset exploit, unbounded registry growth), and a follow-up pass aligning the worker with Cloudflare's published DO best practices (RPC, alarm error boundary, hibernation-friendly heartbeats, waitUntil, region threading).

Why

No filed issue — these came from an internal audit of the system and the assumptions beneath it ("audit the seams, not the cores"). The bugs clustered at the boundaries the unit tests mock away: the WebSocket lifecycle, the single DO alarm, and the matchmaker's storage backing. Full audit trail in Lessons_learned.md §21–22 and CHANGELOG.md 1.2.0. The two worst, with reproduction sketches:

1. Every mid-game reconnect ended in permanent ejection. useGameConnection's watchdog measured staleness from the last pong only; onopen never refreshed it. Repro: play, drop the network >5s, let the client reconnect → 30s later the watchdog closes the healthy socket (clean close → server removes the player → rejoin token now invalid → fresh join rejected with game_in_progress). Affects both frontends (TUI re-exports the hook).
2. Any WS upgrade froze a live room for 5s. A DO has one alarm and setAlarm overwrites; ensureUnauthenticatedSocketAlarm set now+5s on every upgrade, clobbering the pending 33ms tick. Repro: reconnect (or open wss://…/room/CODE/ws?rejoin=1 with just a room code) against a playing room → the whole room's loop stalls ~5s; repeat every <5s for an indefinite freeze.

How

Test-first (red → green) throughout, with correctness-by-construction over spot patches:

Finding	Fix
Watchdog kills reconnects	Liveness is an explicit mark set on both socket-open and pong (client-core/src/connection/liveness.ts) — the reset can't be forgotten
Alarm clobber / freeze DoS	scheduleWakeNoLaterThan min-merges via getAlarm() (Cloudflare's "Multiple Events, Single Alarm" pattern)
game_over room leak	PLAYER_LEAVE permitted out of game_over; rooms drain to 0 and cleanup() unregisters
ready mid-match reset exploit	ready/unready/checkStartConditions status-guarded to the lobby (matches the PBT hardening start_solo/join already had)
Registry grows to the 128 KiB KV ceiling	/find sweeps all stale rooms (not just openRooms), game_over registrations drop, MAX_TRACKED_ROOMS cap refuses new rooms (503)
createRoom ignored failures	Register-first with init-failure compensation; honest 503s, no phantom/orphan rooms
Cloudflare-idioms pass	Matchmaker exposes typed RPC (fetch kept only for the WS upgrade, which needs a 101); alarm() error boundary with backoff + bounded give-up; setWebSocketAutoResponse answers heartbeat pings without waking the DO (reap reconciles liveness from getWebSocketAutoResponseTimestamp since auto-responses bypass webSocketMessage); fireAndForget protected by ctx.waitUntil; region threaded explicitly (RPC context + x-vaders-region header) replacing the isolate-invisible CF_REGION global
CI build failures (2)	(a) The one error-level biome diagnostic (lint/a11y/useSemanticElements) fixed: the departure toast's <div role="status"> is now a semantic <output>, with getByRole('status') pinned in its test. (b) A latent flaky PBT the lint fix unmasked: the LaunchScreen menu-sound oracle counted keys linearly and missed that Enter on JOIN ROOM enters join mode (where menu keys are silent) — CI's seed found ['2','ArrowDown','Enter','ArrowUp']. The component was correct; the oracle now models the handler (joinMode + selectedIndex), asserts full call-sequence identity, and the counterexample is pinned as a deterministic regression case (model verified at 1500 fresh-seed runs)
Smaller fixes	Symmetric player bounds (PLAYER_MAX_X 112→116; left-edge formula on a center coordinate left 4 dead columns); WS hook warns on malformed/unknown messages instead of swallowing; buildWsUrl uses the URL parser; TUI startup probe and MusicManager share one audio-player resolver; TUI default server URL matches the launcher; rejoin_sessions cleared on cleanup

Deliberately deferred (captured in docs/TODO.md with rationale): sharding the global-singleton Matchmaker and moving the registry to per-room SQLite rows — both need a storage/topology migration; the cap + sweep bounds the blast radius until then.

Testing

• New/modified tests pass — ~40 new tests across the five packages (unit, integration-style against the real hook/DO classes, and PBT harness updates)
• Tests fail when fix is reverted (regression guard) — verified explicitly for the headline fix: removed the one-line markAlive on onopen, connection-reconnect.test.tsx went red, restored it, green. The reducer/GameRoom guards were written red-first against the unfixed code, and the flaky-PBT fix was reproduced red on CI's exact seed/path before the oracle was corrected
• Full test suite passes (no regressions) — shared 259, client-core 348, client 796, worker 555, web 650 (+1 pre-existing skip); typechecks clean in all packages
• Manual testing completed — the alarm-clobber and reconnect-flap sequences were reproduced step-by-step in the GameRoom/hook test harnesses (mock WS + fake timers) before fixing; both-directions tests confirm the watchdog still closes genuinely dead sockets and known messages don't warn

CI is green on the head commit (cf659ad): Lint/Type Check/Test ✅, Build ✅, Spritesheet ✅ (E2E runs on push-to-main only, by design).

Risk

• Breadth: 41 files, +2k/−350. It's one concern (audit-findings hardening) but it touches the connection hook, the DO alarm path, and the matchmaker — the multiplayer-critical core. Mitigation: every change is individually regression-guarded, and the cross-frontend contract tests + PBT invariant suites all pass unchanged.
• Behavior changes to note: ready is now ignored outside the lobby (clients only ever sent it there); pong.serverTime is optional (verified no client reads it); registry capacity can return a new matchmaker_full 503 (saturation PBT updated to accept it); PLAYER_MAX_X widens reachable play by 4 columns; the departure toast renders as <output> instead of <div role="status"> (identical semantics and layout).
• Lint: the repo's 600+ biome warnings remain (out of scope); the single error-level diagnostic that failed CI is fixed in this PR, so bun run lint exits 0.
• Merge state: rebased onto main (f408fcc, the co-op balance/doc fixes from Balance co-op lives, wipe timings, and grid sizes #8) — linear history, no merge commits. The README version-badge conflict was resolved to 1.2.0 to match this branch's package.json.

https://claude.ai/code/session_01GS6cvaEYkJxvKXgZsmeD78