5ccc50b8

docs: the session list stops hiding under wire stats

a73x 2026-08-23 12:05

Commit message

docs: the session list stops hiding under wire stats

"Which sessions are alive?" had no answer in this file. The only documented
way to see the daemon's sessions was `Ctrl-\ w`, which needs an attached
client — precisely what you do not have when the table is full and `mux` is
refusing you. The capability existed the whole time: `muxd stats` is a
one-shot query that attaches nothing and names every live session with its
client count. It was filed under "Everything else" as "wire stats: deltas vs
snapshot bytes, attached clients", which reads as a performance counter and
gets skipped by anyone hunting a lost session.

Found by spending a lost-session triage reconstructing the session table from
/proc and per-name muxa probes, then discovering `muxd stats` answers it in
one line.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

README.md

Old		New
@@ -120,6 +120,11 @@ wrap at the ends, and `mux --session NAME` attaches to any of them by name
120	(creating it if there is room). With only one session open `n` and `p` do	120	(creating it if there is room). With only one session open `n` and `p` do
121	nothing — there is nowhere to step to.	121	nothing — there is nowhere to step to.
122		122
		123	To see which sessions are alive without attaching to one, ask the daemon:
		124	`muxd stats` names every live session with the number of clients watching it.
		125	That is the question to ask when `mux` will not let you in — four sessions is
		126	the table, and a fifth name has nowhere to go.
		127
123	Every session shell is told where it lives: `$MUX_SOCK` is the daemon's	128	Every session shell is told where it lives: `$MUX_SOCK` is the daemon's
124	socket path and `$MUX_SESSION` is the session's name. Scripts and prompts	129	socket path and `$MUX_SESSION` is the session's name. Scripts and prompts
125	can read them, and `mux` reads them to refuse attaching to the very session	130	can read them, and `mux` reads them to refuse attaching to the very session
@@ -365,7 +370,7 @@ the daemon you are attached to, and `q` puts you back where you were.
365		370
366	```sh	371	```sh
367	muxd dump [--vt] # debug: print the authoritative grid (what the screen should be)	372	muxd dump [--vt] # debug: print the authoritative grid (what the screen should be)
368	muxd stats # wire stats: deltas vs snapshot bytes, attached clients	373	muxd stats # live sessions by name + clients each; wire stats (deltas vs snapshot bytes)
369	make bench # typing-workload byte-ratio measurement	374	make bench # typing-workload byte-ratio measurement
370	```	375	```
371		376