411b6c25

docs: the wall file is attach history now

a73x 2026-08-20 00:50

Commit message

docs: the wall file is attach history now

decisions.md records the calls phase 2 had to make concretely: why the
write seam sits inside client.attach's loop rather than in mux_main, why
the rule is enforced by placement instead of a size or tty check, why the
tile is written after the dial and taken back on a refused switch, what
"atomic" does and does not claim, and the staleness gap left open on
purpose (a running wall or hub does not see another process's add until
it restarts). README's wall section and both key tables gain `x`.

README.md

Old		New
@@ -40,6 +40,12 @@ Inside a session:
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 wall (`j`/`k` select, `Enter` zooms, `q` comes back) \|	42	\| `Ctrl-\` `w` \| show every session as a wall (`j`/`k` select, `Enter` zooms, `q` comes back) \|
		43
		44	The wall `Ctrl-\` `w` opens is a real wall, so `x` in it edits the saved
		45	wall file like any other — the tiles it lists are spelled exactly as the
		46	recorded lines, so forgetting one there forgets it everywhere. The session
		47	keeps running either way.
		48
43	\| `Shift+PageUp` / `Shift+PageDown` \| scrollback, a screen at a time (any other key returns to live) \|	49	\| `Shift+PageUp` / `Shift+PageDown` \| scrollback, a screen at a time (any other key returns to live) \|
44	\| mouse wheel \| scrollback, three rows a notch (arrow keys to a full-screen app) \|	50	\| mouse wheel \| scrollback, three rows a notch (arrow keys to a full-screen app) \|
45		51
@@ -135,7 +141,7 @@ there is no unauthenticated mode to fall back to.
135		141
136	```sh	142	```sh
137	muxweb # restores the wall you left; opens on 127.0.0.1:7681	143	muxweb # restores the wall you left; opens on 127.0.0.1:7681
138	muxweb HOST quic://OTHER --sock /tmp/s.sock#b # ...or state it, which replaces the saved wall	144	muxweb HOST quic://OTHER --sock /tmp/s.sock#b # ...or state it: shows these, ADDS them to the saved wall
139	```	145	```
140		146
141	Each tile is a live session, dialed the way `mux` dials it — the same	147	Each tile is a live session, dialed the way `mux` dials it — the same
@@ -159,8 +165,38 @@ The same wall, without a browser:
159	mux wall # the saved wall, as stripes in this terminal	165	mux wall # the saved wall, as stripes in this terminal
160	mux wall HOST '--sock /tmp/s.sock#b' # ...or state it (one spelling per argument)	166	mux wall HOST '--sock /tmp/s.sock#b' # ...or state it (one spelling per argument)
161	mux wall HOST --sock /tmp/s.sock#b # ...`--sock PATH` unquoted works too, as in muxweb	167	mux wall HOST --sock /tmp/s.sock#b # ...`--sock PATH` unquoted works too, as in muxweb
		168	mux wall add HOST'#build' # put a tile on the saved wall without attaching
		169	mux wall rm HOST'#build' # take one off (the session keeps running)
162	```	170	```
163		171
		172	`add` and `rm` are subcommands, so they claim the first argument: a tile
		173	spelled literally `add` or `rm` has to reach the wall some other way (the
		174	`Ctrl-\` chords, `muxweb`, or an editor on the file). Naming neither a
		175	target nor a spelling is a usage error, not an empty edit.
		176
		177	The wall is your attach history. Every `mux` attach writes its own tile
		178	to that file, so a bare `mux` leaves `--sock <default>#0` behind and
		179	`mux HOST --session build` leaves `HOST#build` — as does every session you
		180	reach with `Ctrl-\` `c`/`n`/`p`, because visiting a session is attaching to
		181	it. Tiles are deduped by spelling, byte for byte: the same session reached
		182	as `HOST#build` and as `quic://HOST#build` is two tiles, deliberately.
		183	`muxa` never adds one (it attaches at 0×0 and claims nothing), and neither
		184	do the wall's own stripes. Writing the file is best effort — if it cannot be
		185	written you get one warning line and the attach happens anyway.
		186
		187	`mux wall add`/`rm` are the same edit without an attach: file operations
		188	only, so neither dials, and `rm` never touches the session. A wall or hub
		189	that is already running does not notice the change until you reopen it.
		190	`rm` is also the repair tool: it is the one command that reads the file
		191	leniently, so a line you hand-edited into something no longer legal can be
		192	removed (and every other line survives it byte for byte) instead of
		193	wedging every command that touches the wall.
		194
		195	`muxweb TILE...` ADDS its tiles to that file rather than replacing it —
		196	naming a wall on the command line changes what this run shows, not what
		197	you have recorded. Forgetting stays explicit: the page's `×`, the wall's
		198	`x`, `mux wall rm`.
		199
164	Watching is read-only: each stripe is a live session (label bar + the rows	200	Watching is read-only: each stripe is a live session (label bar + the rows
165	around its cursor), attached the way `muxa` attaches — no size claim, so	201	around its cursor), attached the way `muxa` attaches — no size claim, so
166	watching never resizes anyone. The stripes are cut once, from the terminal's	202	watching never resizes anyone. The stripes are cut once, from the terminal's
@@ -174,6 +210,7 @@ Zoomed out (the wall):
174	\| `j` / `k` (or `n` / `p`) \| select the next / previous stripe, wrapping \|	210	\| `j` / `k` (or `n` / `p`) \| select the next / previous stripe, wrapping \|
175	\| `1`-`9` \| select that stripe, counting from the top \|	211	\| `1`-`9` \| select that stripe, counting from the top \|
176	\| `Enter` \| zoom the selected stripe — type into that session \|	212	\| `Enter` \| zoom the selected stripe — type into that session \|
		213	\| `x` \| forget the selected tile (off the wall file; the session keeps running) \|
177	\| `q` (or `Ctrl-\`) \| leave the wall \|	214	\| `q` (or `Ctrl-\`) \| leave the wall \|
178		215
179	Zoomed in (one session, full screen):	216	Zoomed in (one session, full screen):
@@ -201,6 +238,11 @@ reflows when you look away.
201	Typed input at a zoomed tile is predicted locally, as in a plain client.	238	Typed input at a zoomed tile is predicted locally, as in a plain client.
202	The mouse is not: a zoomed tile is keyboard-only for now.	239	The mouse is not: a zoomed tile is keyboard-only for now.
203		240
		241	`x` forgets the selected tile: its line leaves the wall file, its stripe
		242	leaves the screen, and the remaining stripes are re-cut over the space.
		243	Forgetting is never killing — the session goes on running and `mux` reaches
		244	it again by name. Forget them all and the wall says so.
		245
204	The same wall, from inside a session: `Ctrl-\` `w` shows every session on	246	The same wall, from inside a session: `Ctrl-\` `w` shows every session on
205	the daemon you are attached to, and `q` puts you back where you were.	247	the daemon you are attached to, and `q` puts you back where you were.
206		248

docs/decisions.md

+and the grep could never have matched. Renamed to `wallmute`, every letter of
+which the wall swallows, and re-checked under the mutation before being
+believed.
+## 2026-08-20 (the wall is the home screen, phase 2: attach adds, `x` forgets)
+Spec: `docs/superpowers/specs/2026-08-19-wall-home-screen-design.md`. Phase 2 of
+three: the wall file becomes attach history. Phase 3 converges `client.zig`'s
+session loop with the wall.
+**The write seam is inside `client.attach`'s loop, not in `mux_main`.** The
+spec's rule is mechanical — any `mux` attach that CLAIMS the grid (attaches at
+nonzero size) writes its tile — and the argv layer cannot honour it, because
+`Ctrl-\ c`/`n`/`p` re-dial full-size from inside `attach`'s own `while (true)`
+and never come back through `main`. A seam up there would record the session
+the user started at and none of the ones they actually visited, which is the
+opposite of "the wall grows by the truth". So `client.zig` grew a `wall`
+import (layer 2 ← layer 1) and one call per turn of the loop.
+**The rule is enforced by WHERE the call sits, not by a size check.** There is
+no `if (cols > 0)` and deliberately no tty check. `client.attach` is the only
+grid-claiming attach path in the tree — it attaches at the tty's size, or at
+×24 when stdin is a pipe, never at zero — while the two passive attachers
+never reach it: `muxa` does not link the module at all, and `wallview`'s tile
+pumps build their own `Transport`. A tty check would additionally have excluded
+the `ptyclient` fixture, which the spec explicitly wants included (tests run
+under an isolated `XDG_STATE_HOME`). "muxa attaches at 0×0" stops being a
+sentence in CLAUDE.md and becomes an e2e leg: `muxa send` drives the same
+session and the wall file's sha256 does not move, anchored on a marker the
+agent actually landed so a muxa that did nothing cannot pass by doing nothing.
+**Recorded when the first STATE arrives, not when the dial succeeds.** The
+first version wrote the tile straight after `Transport.open` and argued that a
+transport coming up is the strongest "this attach is real" signal available
+before the first snapshot. It is not a signal at all: the daemon can still
+refuse (its session table is full at four), and the case analysis that followed
+from the wrong seam was wrong in the way case analyses are — it enumerated the
+refusal it could see. A SWITCH's refusal returns `.refused`, which has somewhere
+to fall back to and so a place to undo the write; a FIRST attach refused
+identically returns `.{ .exit = 1 }` and left the line stranded, a tile naming a
+session that never existed. Review reproduced it: a daemon at `max_sessions`,
+`mux --session PHANTOM`, rc 1 and a `#PHANTOM` line on the wall. The
+`session(...) catch |err|` path had the same hole.
+So the seam moved inside `session()`, keyed on `rep.state_since_attach` — the
+daemon's own answer to "did this attach land", and the very flag BOTH refusal
+paths read to decide there was none. A refusal now cannot record, on any path,
+present or future, without anyone having to keep an enumeration exhaustive; and
+with nothing recorded there is nothing to take back, so `unrecordTile` is
+deleted rather than fixed. The reason the old seam existed survives untouched:
+the snapshot is milliseconds behind the dial, so a `mux wall` in another
+terminal still shows the session you are attached to WHILE you are attached to
+it. A reconnect clears the flag and it turns true again, so the write is latched
+per `session()` run — dedup would make the second one a no-op, but a resync
+should not pay a read-modify-write to find that out.
+The general lesson, third time in this file: **when a write has a "was this
+real" question attached to it, key it on the flag the code already uses to
+answer that question, rather than on a proxy plus a list of exceptions.** The
+proxy is what needs the list.
+**Dedup is byte-exact on the spelling, never on identity.** The same session
+reached as `HOST#S` and as `quic://…#S` is two tiles, deliberately: identity
+dedup would need an endpoint handshake the wall does not have and the spec does
+not want. The default session records as `#0`, the RESOLVED name, not the empty
+wire name the attach frame carries — a wall line must be a spelling a user
+could type back.
+**Best effort, one warning, never a failure.** An unwritable wall file (a
+directory in its place, a read-only state home) costs one line on stderr and
+nothing else: the attach happens, the session is usable, the exit code is
+untouched. The warning is latched per `attach()` call rather than per write,
+because a chord loop visits N sessions and a wall file that cannot be written
+cannot be written for any of them — repeating the sentence would scroll a
+working session for a record nobody is reading. `--via` records nothing at all
+and says nothing: the wall grammar has no form for "an arbitrary command's
+stdio", the same refusal `Ctrl-\ w` already makes.
+**`muxweb TILE...` adds; it no longer overwrites.** Argv used to be saved with
+`wall.save`, replacing the file with whatever this run was told to show — which
+was defensible while the file meant "the last wall muxweb was given". It stopped
+meaning that the moment attaches started writing to it: one `muxweb HOST` would
+have silently erased every tile every `mux` had recorded, and the erasure would
+look like a feature ("argv overrides"). Argv still overrides the VIEW — the run
+shows the tiles it named and only those — but each is now `wall.record`ed,
+deduped, and nothing is removed. Forgetting stays explicit: the page's `×`, the
+wall's `x`, `mux wall rm`. The e2e assertion INVERTED rather than moving: it
+used to fail on `argv appended to the wall instead of replacing it`, and now
+fails if the pre-existing line does not survive. Both halves are asserted,
+because the "argv reached the file" grep alone passes on an overwrite.
+**Removal reads the file leniently; growing it does not.** `load` refuses a wall
+holding a line that no longer parses, which is right — silently dropping a tile
+the user wrote down is worse than making them fix it — but when every path went
+through `load`, one hand-edited line made the file unrepairable by the tool that
+owns it, including the command whose entire job is removing a line. So `forget`
+(and therefore `mux wall rm` and `x`) reads with `loadLines`, which applies no
+grammar: it can delete the broken line, and it writes every line it did not
+match back byte for byte. `record` and `Wall.add` keep refusing — growing a wall
+whose existing content is not understood would re-save garbage as though it had
+been read.
+**`mux wall add`/`rm` build the whole edit in memory and save once.** The doc
+comment promised validate-all-before-write, and the per-spelling `record`/`forget`
+loop made that a half-truth: a bad line was caught before anything moved, but an
+IO error on the third of four arguments left the first two applied. One
+in-memory pass, one atomic rename. `rm` still reports each absent spelling and
+exits non-zero while removing the ones that were there — the report is about the
+argument, not a reason to abandon the others.
+**Atomicity is writer-vs-reader, and the staleness gap is left open.** Every
+mutation goes through `wall.save`'s temp-file-plus-rename in the same directory,
+so the browser hub reading concurrently never sees half a file. Two writers
+resolve as last-rename-wins, which is what a single user's state file deserves.
+What is NOT solved, deliberately: a `mux wall` or `muxweb` that is ALREADY
+RUNNING reads the file once at startup and does not notice a line another
+process adds. The file is state, not a channel; a change feed (inotify, a hub
+verb, a poll) is real work for a case the model does not need yet — you see the
+new tile the next time you open the wall.
+**`x` is an ordered removal that never speaks to the daemon.** The line leaves
+the file (`orderedRemove`, so the survivors keep the positions `1`-`9` jump to),
+the tile's pump returns — which closes its transport and frees the daemon slot —
+and the stripes are re-cut over what is left. Nothing else is sent: "remove is
+detach", the dynamic-wall doctrine, now with a leg that proves it (`muxa
+status` still answers for the forgotten session, and its marker is still in the
+grid). A tile that came from `mux wall`'s own command line and was never in the
+file is forgotten from the VIEW just the same, silently — the file had nothing
+to remove and the screen is the answer either way.
+**Forgotten tiles become holes; nothing is compacted.** The pump threads hold
+`*Tile` pointers for the wall's whole life, so the array cannot shrink. The two
+pure chord tables therefore take a `present: []const bool` instead of a count:
+`j`/`k` step over holes, the digits renumber with the BARS the eye can actually
+see, and `Ctrl-\ l` aimed at a forgotten tile unzooms — which is exactly the
+fallback phase 1's comment predicted for "a tile that has since been forgotten".
+The `gone` flag is also read inside `paintModeLocked`, under `paint_mu`: without
+it a pump already past its own check could paint a stale stripe onto rows that
+have just changed owner.
+**An empty wall says so.** Forget the last tile and the terminal would
+otherwise be blank with no cursor, which reads as hung — phase 1's dead-zoom
+lesson, second occurrence. One line, cursor shown, naming the state and the way
+out.
+**`mux wall add`/`rm` are file operations only.** They do not dial, resolve a
+key or spawn ssh, which is what makes them safe in a script. `add` validates
+every spelling through the one grammar BEFORE writing any of them — a refused
+line should not leave the earlier ones half-applied — and adds the one refusal
+that belongs to the transport rather than the grammar (a `sun_path` too long to
+bind), because add time is the only moment the user is still looking at what
+they typed. `rm` of a spelling that is not on the wall says so and exits
+non-zero: a script that thinks it cleaned up a tile should learn it was spelled
+differently. The price of the subcommand is that a tile spelled literally `add`
+can no longer be `mux wall`'s first argument.
+**Two independent pumps, two consecutive expects, one coin flip.** The `x` leg
+first expected BOTH tiles' markers in a row. Tiles are threads; `expect` consumes
+forward; whichever stripe painted second left the other's marker behind the
+cursor, and verb 2 spent its whole 20s budget waiting for bytes that had already
+gone past. It passed twice here and failed twice on the reviewer's box, which is
+the only interesting fact about it — a green run proved the scheduler, not the
+code. Every other two-tile ptyclient leg in this suite expects exactly ONE
+marker and then `settle`s, and that is not a style: it is the only pattern that
+is a fact about the program rather than about thread order. Fixed to match.
+Three mutations, to check the new legs have teeth. Making `wall.record` always
+append fails the dedup leg at `a second attach to the same session made 2
+lines`. Putting the seam back at dial time fails the phantom-tile leg, which is
+the regression test for the case review found. Making `muxa`'s `attachZero`
+record a tile like a human attach fails the byte-identical leg at `muxa attached
+at 0x0 and still wrote a tile`. That one is worth a note on how it was read: on
+its first run the same mutation's extra file I/O also pushed the CLI-wall
+block's 5s injection expect past its budget, and the suite stopped THERE, before
+reaching the leg under test — a kill that proves the mutation is detectable
+without proving which assertion detects it. Re-run after the review fixes it
+died on its own leg. A mutation that fails the suite somewhere is not a mutation
+that fails the leg you aimed it at; when the two differ, say so and go get the
+targeted answer (here, `muxa send` against a hashed wall file, standalone). No
+mutation was needed for `x`:
+the leg asserts a line count, a surviving spelling and a session that still
+answers, and no two of those can be satisfied by the same accident.