c64627bc

docs: record the wall freeze and the single-target terminal client

a73x 2026-09-05 19:42

Commit message

docs: record the wall freeze and the single-target terminal client

Decision 2026-09-05, issue 94ed7dfd: the terminal wall retires once muxg
covers it and mux becomes one session per invocation; mux web stays and
takes the layout file. Frozen to bug fixes until the seven GUI gap issues
land.

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

CLAUDE.md

Old		New
@@ -5,6 +5,23 @@ carries its grid as cells and the client copies them into a grid of its own.
5	Attach = one snapshot, then row deltas. Zig; Linux and Apple-silicon macOS;	5	Attach = one snapshot, then row deltas. Zig; Linux and Apple-silicon macOS;
6	prototype.	6	prototype.
7		7
		8	## Sprint delivery
		9
		10	When the user requests sprint delivery, read and follow
		11	[the shared skill](docs/skills/sprint-delivery/SKILL.md). Use this repository copy
		12	for mux work; no personal skill installation is required. Ordinary isolated
		13	edits do not require the sprint workflow.
		14
		15	## The wall is frozen (2026-09-05)
		16
		17	The terminal wall — tiles, rails, chords, the layout tree and file, the
		18	pane grade, the picker — retires once the native client covers it, and
		19	`mux [TARGET]` becomes one session per invocation with no picker. Until
		20	every gate in issue `94ed7dfd` lands (macOS `muxg` first), the wall takes
		21	BUG FIXES ONLY: no new wall features, no new wall invariants. `mux web`
		22	stays and will own the layout file. Rationale and the file list are in
		23	`docs/decisions.md` under that date.
		24
8	## Toolchain (pinned — system zig will NOT build this)	25	## Toolchain (pinned — system zig will NOT build this)
9		26
10	```sh	27	```sh
@@ -30,7 +47,7 @@ make mac xos # macOS journeys (test/mac.sh); the cross-OS gate
30	make provision-mac # clone, boot and key a macOS guest on a tart host and	47	make provision-mac # clone, boot and key a macOS guest on a tart host and
31	# print one line; `eval "$(test/provision-mac.sh)"`	48	# print one line; `eval "$(test/provision-mac.sh)"`
32	# is how MAC_BOX gets set. --down takes it away.	49	# is how MAC_BOX gets set. --down takes it away.
33	make install # the one user binary -> ~/.local/bin, ReleaseSafe	50	make install # mux + muxg -> ~/.local/bin, ReleaseSafe; needs native libraries
34	# MUX_TARGET follows the HOST: a Mac installs a Mac	51	# MUX_TARGET follows the HOST: a Mac installs a Mac
35	# binary, because that is the only one it can link	52	# binary, because that is the only one it can link
36	make release release-mac # one tarball per OS into dist/, cut on that OS;	53	make release release-mac # one tarball per OS into dist/, cut on that OS;
@@ -123,7 +140,7 @@ independent of terminal wall policy and persistence. Rule 9 confines SDL to `src
123	entry `src/cli/muxg.zig` may also use it. Everything else in the painter is	140	entry `src/cli/muxg.zig` may also use it. Everything else in the painter is
124	unit-tested without opening a window.	141	unit-tested without opening a window.
125		142
126	The default product and install remain ONE binary, `mux`, and the first word	143	The default development build produces `mux`, and the first word
127	picks a mode: `mux d` the daemon,	144	picks a mode: `mux d` the daemon,
128	`mux a` the agent surface (JSON verbs), `mux web` the browser hub, and no	145	`mux a` the agent surface (JSON verbs), `mux web` the browser hub, and no
129	letter at all the client. There is NO alias: a word that is not a mode is a	146	letter at all the client. There is NO alias: a word that is not a mode is a
@@ -134,9 +151,11 @@ daemon); `agent` stays a row of its own so muxa's suite can fail on its
134	own. Test fixtures in `test/`:	151	own. Test fixtures in `test/`:
135	`ptyclient` (real client on a real pty), `wsclient` (browser stand-in),	152	`ptyclient` (real client on a real pty), `wsclient` (browser stand-in),
136	`rawmode`, `delaypipe`, `render` — those stay separate binaries.	153	`rawmode`, `delaypipe`, `render` — those stay separate binaries.
137	The opt-in second product binary is `muxg`, a dynamically linked window on	154	The second product binary is `muxg`, a dynamically linked window on native
138	native session panes; it is built only by the native steps and is never installed by	155	session panes. `make install` and `make release` build both binaries in
139	`make install` or included in `ci`.	156	ReleaseSafe; `make native` builds the GUI for development. The GUI remains
		157	outside `ci`. On Linux, `mux` stays static musl while `muxg` uses the host's
		158	native target and system GUI libraries, which are not bundled in the release.
140		159
141	## Invariants — do not break, they are load-bearing	160	## Invariants — do not break, they are load-bearing
142		161

docs/decisions.md

@@ @@ -9340,3 +9340,46 @@ narrows the window. Pinned by the observer-burst test in @@
+`server_test_attach.zig`: eight connects with no frame behind them, exactly
+four held after twenty pumps, and all eight seated and served once the
+frames arrive.
+## 2026-09-05 — the terminal wall retires; `mux` becomes one session per invocation
+Decided with the native client (`muxg`) in hand, recorded as issue
+`94ed7dfd`.
+**The TUI keeps one of its two jobs.** It is the only client that runs
+where there is no window — over ssh, inside mosh, on a headless box, as
+the piped `mux` a script reads an exit code from — and it is the pty the
+e2e harness grades the daemon through, so it stays a product. What it
+loses is the wall: tiles, rails, the split and resize chords, the layout
+tree and the layout file, the once-a-second pane grade, the two-level
+picker, focus, and relocating mouse reports into wall coordinates. The
+native tiling design (2026-09-05) chose its own workspace and persistence
+and refused to migrate the wall, so there were two walls and the browser
+hub's grade made a third copy; the 2026-09-04 layout loss and the top two
+backlog items were all wall-file problems.
+**The shape after.** `mux [TARGET]` is strictly one session per
+invocation: no picker, no tiles. It keeps the pump and redial, prediction,
+the askpass popup, `-A`, mouse passthrough, drag select, scroll mode, the
+end two-step on its own connection, the ssh handoff to QUIC, and the exit
+code. `mux web` stays — it is the only phone and tablet surface — and
+inherits ownership of `client.layout`, the layout file and the host grade,
+since it is their only remaining consumer; `wall_host.planHostDiff` and
+`webhub.applyList` collapse to the hub's copy. Dying with the wall:
+`wallview.zig` (most), `wall_layout.zig`, `wall_picker.zig`, the wall parts
+of `interact.zig` and `wall_host.zig`, the six `wall_test_*.zig`, e2e groups
+_wallcli, 09_hosts, 12_panes, 13_birth and the tile legs of 06_web, and
+the wall invariants in CLAUDE.md. Backlog that closes with it: 32d168d1,
+the seed half of 55ca6e6d, 2fc534d6, 05fc3090, 7b04a2ac, 68d4700e, most of
+e3548ab1.
+**Until then the wall is FROZEN: bug fixes only, no new wall features.**
+Nothing is deleted before the GUI covers what the wall covers today, each
+gap an issue: `d61fdc4c` muxg on macOS (a Mac has no client but the TUI —
+nothing builds or runs the GUI there, though the Mac release recipe names
+it), `8b16e26b` mouse selection and scroll wheel, `50ca9ba5` agent
+forwarding per pane, `f3cf5785` ssh prompts through an askpass popup,
+`fb4a0ee4` prediction overlay, `0b725c82` ending a session (the GUI can
+detach and sends no `end_req`), `08ff372f` release bundling (the tarball
+ships a dynamic `muxg` with none of its libraries and no message naming
+the missing one).