7c2b4725

docs: M17 close-out record; a recovered tile clears its stuck badge

a73x 2026-08-13 13:02

Commit message

docs: M17 close-out record; a recovered tile clears its stuck badge

The final re-review's one Minor, taken as the lead's chore: a frame
that applies cleanly is the recovery the terminal replay state was
waiting for, so replaySucceeded clears replayDead and the stuck badge
— previously the badge lied about a working tile and sendAttach stayed
gated until the socket happened to reopen. decisions.md M17 carries
the passivity contract, the amended proxy thesis, the std WebSocket
hazards, the headFrame overflow lesson (pin wire-length bounds at the
type boundary), the page-never-ran record, the deliberate v1 stances,
and the banked follow-ups; roadmap marks M17 code-complete with the
kill criterion explicitly owed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/decisions.md

+Process note: both issues closed through `git collab` with sha-naming
+comments — the tracker's first full lifecycle.
+## M17 — web client (browser wall of devices)
+Shipped 2026-08-13 as 04861b7..002d1f7 plus this close-out: muxweb (the
+hub), replica.zig (the replay core, extracted and finally unit-tested),
+keymap.zig, the wasm core (ghostty-vt on wasm32-freestanding, 345KB),
+the web shell, wsclient (the scripted browser stand-in), and three e2e
+scenarios (suite now 23 scenarios / 35 convergence points). Kill
+criterion (the live wall of three devices) still owed — the milestone
+is code-complete, not field-complete, until it runs.
+**The passivity contract: wall tiles attach at 1×1.** The spec's
+original "browser attaches at the tile's cols×rows" would have failed
+its own kill criterion — any attach at a differing size moves the
+shared grid and repaints every client. The daemon already contained the
+mechanism: applySize refuses cols<2/rows<2, the refused attacher gets a
+unicast snapshot carrying the true grid, its slot stays 0×0, and
+claimGrid refuses it on every keystroke thereafter. Permanent
+passivity, zero daemon changes, pinned by a hub-free e2e scenario so
+the contract outlives the hub.
+**The proxy thesis, amended for message-delimited transports.** The
+hub parses the 5-byte frame header in both directions — WebSocket is
+message-delimited, the daemon socket is a byte stream, and re-framing
+requires knowing where frames end. It still never parses payloads.
+"Frame-agnostic" was a property of byte-pipe transports, not of pumps
+in general.
+**std.http's WebSocket server, and the two hazards it hands you.**
+respondWebSocket does the RFC 6455 accept-key work, but (1) it does
+NOT check Origin — that gate is ours, before upgrade, exact origins
+only — and (2) readSmallMessage BLOCKS mid-message and silently
+swallows pongs and loops (std Server.zig: `.pong => continue`), so a
+pump that polls must gate every read on a complete-frame check over
+the reader's buffered bytes (headFrame), and must consume pongs
+itself: handing a buffered pong to readSmallMessage re-enters the
+blocking hazard by construction. One buffer bounds both max HTTP
+header and max inbound message (64 KiB; browser pastes chunk at 32 KiB
+under it, wrapped ONCE via paste_begin/end).
+**headFrame's capacity check is load-bearing twice.** Beyond refusing
+oversize messages, `.too_big` before the buffer fills is what keeps
+fillMore off std's defaultRebase assert (`buffer.len - seek >=
+capacity`), which panics on a full unreclaimable buffer. And the check
+itself was the milestone's one Critical regression: `off + payload_len`
+with a wire-controlled u64 overflows — 14 bytes panicked the hub in
+Debug and wrapped to a permanent hang in ReleaseFast. The pin that
+covers it now fails BOTH ways (panic in Debug, wrong verdict in
+ReleaseFast); a Debug-only pin would have left the release wrap
+unguarded. Lesson: bounds involving wire-declared lengths get pinned
+at the TYPE boundary, not just the capacity edge.
+**"The page never ran."** WebAssembly.instantiate is shape-polymorphic:
+bytes yield {module, instance}, a compiled Module yields a bare
+Instance. The shell destructured the wrong shape, every tile died on an
+unread promise rejection, and verify.js — which feeds bytes — stayed
+green. Found only because the fix round added the missing .catch and
+then drove the real page under headless Chrome. verify.js now pins
+both shapes, but the residual stands: nothing automated boots the page,
+so the shell's use of the contract is still uncovered. The named
+follow-up, highest value in this milestone: automate the headless
+browser boot. The general lesson repeated itself precisely — defects
+clustered in the one layer with no tests.
+**Process record.** The execution fork could not spawn subagents, so
+Tasks 1–10 shipped with NO reviews; the post-hoc pair found 1 Critical
++ 5 Important, all in the untested JS layer, and the two fix rounds
+added (then caught) one Critical of their own. Review-after-the-fact
+worked, but the Critical-per-round rate says reviews belong in the
+loop, not after it.
+**Deliberate v1 stances, recorded so they read as chosen:** bracketed
+paste is unconditional (the replica cannot see DECSET 2004 — pty_mode
+carries icanon/echo only; extending it is a daemon protocol change,
+deferred); {"state":"gone"} is in the control vocabulary but never
+emitted (the browser derives gone from ws.onclose; kept for the day
+the hub gives up); a slow browser stalls only its own tile's thread;
+a mid-paste socket death leaves the application in paste mode (the end
+marker cannot transit a dead socket; state lives beyond the pty);
+after unzoom a tile keeps the grid the zoom claimed (unzoom sends
+nothing, per spec); snapshots cannot exceed the 256 KiB staging cap in
+practice because Engine.dumpState is viewport-only by design.
+**Banked by M17:** the headless boot automation (above); a keyboard
+route out of zoom (the shade ring is mouse-only; Escape belongs to the
+application); automated coverage for the 30/60/90s dead-leg timing (the
+pong path is covered every e2e run — with the caveat that the pin
+catches framing regressions loudly but a swallowing regression only
+probabilistically; the timing itself is reasoned, not observed);
+GONE_AFTER_FAILURES bounds two different counters (socket opens,
+replay attempts) and the name no longer says so; per-tab daemon slots
+(N tiles × M tabs = N×M attaches against max_clients=8) — half-open
+pressure the M16 reaping-policy item now also covers.

docs/roadmap.md

+classes and `keyRefusalBody` all got their **first** pins
+(decisions.md, M15, which carries the tables and the failure lines).
+## M17 — web client: a wall of devices in a browser — code-complete
+Shipped 2026-08-13 (04861b7..002d1f7 + close-out). **Field verdict
+owed**: the kill criterion — three real devices live in one page, zoom
+the LAN tile, vim/type/scroll, the CLI client never glitches, pull the
+network and watch the tile recover — has not run yet, and the milestone
+is not *complete* until it has.
+What shipped: `muxweb` (localhost-only hub; tiles are argv in mux's own
+TARGET spellings; one WebSocket per tile; std.http's upgrade with the
+Origin gate ours), `replica.zig` (the replay core extracted from
+`session()` and unit-tested for the first time), `keymap.zig`,
+`mux_core.wasm` (ghostty-vt on wasm32-freestanding, 345KB, flat
+damage-hinted viewport ABI, verify.js wired into `make test`), the
+canvas shell (1×1 passive wall tiles — the daemon's degenerate-size
+refusal is the passivity mechanism, pinned hub-free; zoomed-only
+input; IME; once-wrapped chunked paste), and `wsclient` (a scripted
+replica client speaking RFC 6455). Suite grew 20/33 → **23 scenarios /
+convergence points**, units 255 → 285, plus 76 wasm-ABI assertions.
+The process record is in decisions.md M17: no in-loop reviews ran (the
+execution fork could not spawn subagents); the post-hoc pair found
+Critical + 5 Important, every one in the untested JS layer, and the
+fix rounds added-then-caught a Critical of their own (the headFrame
+u64 overflow — 14 bytes could panic the hub). Banked follow-ups, led
+by the headless browser-boot automation ("the page never ran" was the
+milestone's defining defect), are listed there.
+## M16 candidates — and still outranked by trial feedback
+What remains is what was ranked behind M13 and M14 and survived M15,

web/mux.js

Old		New
@@ -192,6 +192,12 @@ class Tile {
192	replaySucceeded() {	192	replaySucceeded() {
193	this.replayFailures = 0;	193	this.replayFailures = 0;
194	this.replayBackoffMs = 0;	194	this.replayBackoffMs = 0;
		195	// A frame that applies cleanly is the recovery the terminal state was
		196	// waiting for (e.g. the session shrank and its snapshot fits again) —
		197	// clear the give-up flag or the badge lies about a working tile and
		198	// sendAttach stays gated off a tile that no longer deserves it.
		199	this.replayDead = false;
		200	if (this.badgeIs('stuck')) this.setBadge('up', 'up');
195	}	201	}
196		202
197	// The core is unusable — re-init and re-attach from nothing. Everything	203	// The core is unusable — re-init and re-attach from nothing. Everything