14b06705

docs: the wall's keys in the README, and why zooming is a real attach

a73x 2026-08-19 17:17

Commit message

docs: the wall's keys in the README, and why zooming is a real attach

The wall had one documented key (`q`); it now has four, so the README
says what they do. decisions.md records why `Enter` spawns a client
instead of forwarding keystrokes down a tile — typing through a 0x0
attach would fork the latest-wins rule — plus why the selection lives
under the paint mutex and why coming back needs a generation counter.

README.md

Old		New
@@ -39,7 +39,7 @@ Inside a session:
39	\| `Ctrl-\` `d` (or `Ctrl-\` `Ctrl-\`) \| detach (session keeps running) \|	39	\| `Ctrl-\` `d` (or `Ctrl-\` `Ctrl-\`) \| detach (session keeps running) \|
40	\| `Ctrl-\` `c` \| create a session and switch to it (the old one keeps running) \|	40	\| `Ctrl-\` `c` \| create a session and switch to it (the old one keeps running) \|
41	\| `Ctrl-\` `n` / `Ctrl-\` `p` \| switch to the next / previous session, wrapping \|	41	\| `Ctrl-\` `n` / `Ctrl-\` `p` \| switch to the next / previous session, wrapping \|
42	\| `Ctrl-\` `w` \| show every session as a read-only wall; `q` comes back \|	42	\| `Ctrl-\` `w` \| show every session as a wall (`j`/`k` select, `Enter` types, `q` comes back) \|
43	\| `Shift+PageUp` / `Shift+PageDown` \| scrollback (any other key returns to live) \|	43	\| `Shift+PageUp` / `Shift+PageDown` \| scrollback (any other key returns to live) \|
44		44
45	`mux` again reattaches — full TUI screens included. Kill the client with	45	`mux` again reattaches — full TUI screens included. Kill the client with
@@ -148,10 +148,24 @@ mux wall HOST '--sock /tmp/s.sock#b' # ...or state it (one spelling per argume
148	mux wall HOST --sock /tmp/s.sock#b # ...`--sock PATH` unquoted works too, as in muxweb	148	mux wall HOST --sock /tmp/s.sock#b # ...`--sock PATH` unquoted works too, as in muxweb
149	```	149	```
150		150
151	Read-only: each stripe is a live session (label bar + the rows around its	151	Watching is read-only: each stripe is a live session (label bar + the rows
152	cursor), attached the way `muxa` attaches — no size claim, so watching	152	around its cursor), attached the way `muxa` attaches — no size claim, so
153	never resizes anyone. `q` or `Ctrl-\` leaves. To type into a session,	153	watching never resizes anyone. The stripes are cut once, from the terminal's
154	attach to it: `mux HOST --session b`.	154	size when the wall opened, so resizing that terminal while the wall is up
		155	misplaces them until you leave and reopen it.
		156
		157	\| Key \| Effect \|
		158	\|---\|---\|
		159	\| `j` / `k` (or `n` / `p`) \| select the next / previous stripe, wrapping \|
		160	\| `1`-`9` \| select that stripe, counting from the top \|
		161	\| `Enter` \| type into the selected session; `Ctrl-\` `d` comes back \|
		162	\| `q` (or `Ctrl-\`) \| leave the wall \|
		163
		164	The selected stripe's label bar carries a `>` marker. `Enter` zooms it:
		165	the wall hands the terminal to an ordinary `mux` attached to that session,
		166	so typing is a full-size client claiming the grid — never a tile, which
		167	stays 0×0 and passive. `Ctrl-\` `d` detaches that client and the wall
		168	comes back, current.
155		169
156	The same wall, from inside a session: `Ctrl-\` `w` shows every session on	170	The same wall, from inside a session: `Ctrl-\` `w` shows every session on
157	the daemon you are attached to, and `q` puts you back where you were.	171	the daemon you are attached to, and `q` puts you back where you were.

docs/decisions.md

+columns wide there, because every assertion greps a MESSAGE out of a grid
+dump and a grid wraps — at 80 the wall refusal, whose length follows `$TMPDIR`,
+split mid-sentence and a correct refusal read as a missing one.
+**The wall's zoom is a real attach, and that is the whole design.** `Enter` on
+the selected stripe spawns an ordinary `mux` on this terminal, waits for it, and
+takes the terminal back when it detaches. The obvious alternative — forward
+keystrokes down the selected tile's transport — forks the latest-wins rule at
+its root: a tile attaches 0×0 precisely so it can never claim the grid, and a
+client that types is exactly a client that must claim it, so a typing tile is
+either a 0×0 client claiming a grid (a rule with an exception is a rule nobody
+can reason about) or a session being typed at by a client whose size the daemon
+was told to ignore. Spawning keeps both halves honest: the wall stays an
+observer, and interaction claims the grid the legitimate way. It is `Ctrl-\ w`
+read backwards — that spawns a wall from a client, this spawns a client from a
+wall — and the same argument settles it, that a process boundary is what makes
+"the terminal belongs to exactly one of you" true by construction.
+The selection is under the paint mutex, not atomic. It is read while a label bar
+is being drawn, and the bars are drawn by the pump threads: an atomic read would
+let a bar paint the marker the selection had when its frame arrived, so a wall
+could show two markers, or none, for as long as nothing else painted. One
+keystroke moves it and repaints both bars under one hold, so the marker is
+single-valued in every frame the terminal ever shows.
+Coming back needs a lever, because a correct replica is not a painted screen.
+Holding `paint_mu` for the child's whole life does more than stop the stripes
+painting over it: a pump blocks ON the mutex at the first frame it would paint
+and stops reading its socket there, so the pumps do NOT keep replicating behind
+the zoom — each one stalls a frame in and the wall is as far behind as the zoom
+was long. So the zoom bumps a generation counter on the way out and each pump
+repaints when its own last-painted generation lags — checked on the poll
+timeout, so a stripe is back within ~100ms whether or not its session ever
+speaks again. Between the two, the wall returns current: the backlog every pump
+drains once it is released, and the generation bump for the sessions that said
+nothing at all. A tile still inside its reconnect backoff is the one gap: it
+repaints when it next narrates a state, which is the same moment it would have
+had anything true to say.
+The tail of blocked pumps is a drop, and it is accepted rather than fixed. A
+tile that stops reading accumulates queue on the daemon side, and past
+`pending_cap` (8 MiB) the daemon drops that client — so a chatty session under
+a long zoom loses its tile, which reconnects and re-attaches from a snapshot,
+re-running the whole ssh→QUIC handshake for a `.hand` or `.quic` target. The
+alternative is a pump that keeps reading and applying while it may not paint,
+which is a second buffering path through the replica for the sake of a case
+that already self-heals; and the cap itself is not negotiable, since it is the
+only thing bounding what one wedged client can cost the daemon in memory. The
+visible cost is a stripe reading `[reconnecting]` for a moment after a long
+zoom, which is what a stripe that fell behind should say.
+A failed zoom is said on the label bar, not on stderr — the alternate screen the
+wall re-enters would eat the line — and never propagated: a spawn that did not
+work out is not a reason to end the wall the user is still standing in. The
+`--via` case is `unreachable` rather than an error, because the wall grammar has
+no `--via` spelling to parse: no tile can hold that target, and pretending
+otherwise would add an error path nothing can reach.