c76c27a2

docs: Ctrl-\ w in the key table, and why the wall is a child process

a73x 2026-08-19 17:17

Commit message

docs: Ctrl-\ w in the key table, and why the wall is a child process

README.md

Old		New
@@ -39,6 +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	\| `Shift+PageUp` / `Shift+PageDown` \| scrollback (any other key returns to live) \|	43	\| `Shift+PageUp` / `Shift+PageDown` \| scrollback (any other key returns to live) \|
43		44
44	`mux` again reattaches — full TUI screens included. Kill the client with	45	`mux` again reattaches — full TUI screens included. Kill the client with
@@ -139,6 +140,9 @@ cursor), attached the way `muxa` attaches — no size claim, so watching
139	never resizes anyone. `q` or `Ctrl-\` leaves. To type into a session,	140	never resizes anyone. `q` or `Ctrl-\` leaves. To type into a session,
140	attach to it: `mux HOST --session b`.	141	attach to it: `mux HOST --session b`.
141		142
		143	The same wall, from inside a session: `Ctrl-\` `w` shows every session on
		144	the daemon you are attached to, and `q` puts you back where you were.
		145
142	## Everything else	146	## Everything else
143		147
144	```sh	148	```sh

docs/decisions.md

+pick — write `.detach`, return `.switch_to` — is one path. The intent is spent
+on arrival whichever name it picks, which is what keeps an unasked-for reply
+harmless.
+**The wall reached from inside a session is a CHILD PROCESS, not a call.**
+`Ctrl-\ w` asks the daemon the same `sessions_req` question the switching
+chords ask, then spawns `/proc/self/exe wall SPELLING...` with stdio inherited
+and waits for it. The reason is wallview's teardown: it detaches its per-tile
+pump threads and calls `exit(0)` rather than joining them, because a tile
+blocked in `readFrame` is not joinable and the window between the last paint
+and process death must contain no free. That is correct for a process whose
+whole job is the wall, and unusable inside a client that has to survive the
+wall and go back to a session — in-process, leaving the wall would end the
+session with it. As a child, the existing teardown is right by construction and
+none of it had to change. What the child paints over is repaired by the
+re-attach that follows, which asks for a fresh snapshot the way every attach
+does; the child also restores the termios and the alternate screen it found,
+and the re-attach re-establishes both regardless.
+Two consequences fall out of that shape. The reply arm now reads an optional
+ACTION out of `sessions_reply` rather than an optional NAME — a wall ends the
+run without naming a session to go to — and the whole payload has to travel by
+value, like `SessionName` and for the same reason: the frame is freed before
+the child is spawned. The carrier is sized from this client's own bound on how
+many stripes it will show, deliberately not from the daemon's `max_sessions`,
+which the client cannot watch change; a reply too long for it shows no wall
+rather than a wall that silently omits sessions.
+**`--via` has no wall.** The wall grammar spells a socket, a host, and a
+`quic://` endpoint, and has no form at all for "an arbitrary command's stdio" —
+so for a `--via` target there is no spelling to write down and nothing to hand
+the child. That is refused where it is discovered, with one line, and the
+client re-attaches to the session the chord was typed in: the same shape a
+refused switch already had, because the fact is the same one — nothing failed,
+and there is somewhere to go back to.
+**A chord waits 2s, because an old daemon answers by saying nothing.** A daemon
+that predates `sessions_req` (0x0c) does not refuse the frame — its dispatch
+ends in `else => {}`, so the question is dropped and the connection stays
+perfectly healthy. An intent with no deadline then outlives the universe: it
+stays armed for the rest of the session, every later `Ctrl-\ c/n/p/w` is a
+silent no-op, and nothing in the picture suggests the daemon rather than the
+keyboard. So the intent carries an expiry, which is the whole reason it is a
+struct and not the bare enum. 2s is far longer than any round trip a switch is
+usable over and short enough that the keystroke is still in the user's head
+when the answer arrives; the poll's 100ms cap is what makes the deadline
+reachable at all, since the case being caught is exactly a daemon gone quiet.
+Expiry is self-clearing, so one silence is reported once rather than on every
+poll for the rest of the session.
+It is reported as a corner banner, `[no session list: upgrade muxd]`, not on
+stderr: the terminal is in raw mode on the alternate screen, and a print there
+lands mid-grid with no newline discipline. `[reconnecting]` already sits in
+that corner and is read the same way — it survives until the next full repaint
+paints over it, which is the right lifetime for a marker the user has to
+actually notice. ASCII only, because the banner is placed by byte length.
+A reconnect CLEARS the pending chord instead of expiring it. The two are
+different facts: an expiry means the daemon heard nothing and the user is owed
+an explanation, while a reconnect means the daemon that was asked no longer
+has the question — the user presses the chord again rather than being switched
+by a reply that outlived its connection. And the silence already has an
+explanation they have been shown, since the reconnect painted its own banner.
+Reporting both would put two markers in one corner about one event.

src/client.zig

Old		New
@@ -7,8 +7,10 @@
7	//! Keybinding layer: Ctrl-\ (0x1c) is a command prefix in a live session —	7	//! Keybinding layer: Ctrl-\ (0x1c) is a command prefix in a live session —
8	//! `Ctrl-\ d` or `Ctrl-\ Ctrl-\` detaches, `Ctrl-\ c` creates a new session	8	//! `Ctrl-\ d` or `Ctrl-\ Ctrl-\` detaches, `Ctrl-\ c` creates a new session
9	//! and switches to it in place, `Ctrl-\ n` / `Ctrl-\ p` step to the next or	9	//! and switches to it in place, `Ctrl-\ n` / `Ctrl-\ p` step to the next or
10	//! previous session in the daemon's list. While dialling or reconnecting	10	//! previous session in the daemon's list, `Ctrl-\ w` shows them all as a
11	//! there is no session to command and a bare Ctrl-\ still aborts.	11	//! read-only wall (a `mux wall` child on this terminal) and returns here
		12	//! when it leaves. While dialling or reconnecting there is no session to
		13	//! command and a bare Ctrl-\ still aborts.
12	const std = @import("std");	14	const std = @import("std");
13	const Engine = @import("engine").Engine;	15	const Engine = @import("engine").Engine;
14	const Replica = @import("replica").Replica;	16	const Replica = @import("replica").Replica;