4e6962dd

Merge branch 'feat/agent-surface'

a73x 2026-08-14 05:04

Commit message

Merge branch 'feat/agent-surface'

# Conflicts:
#	build.zig
#	docs/decisions.md

README.md

Old		New
@@ -102,6 +102,16 @@ muxd stats # wire stats: deltas vs snapshot bytes, attached clients
102	make bench # typing-workload byte-ratio measurement	102	make bench # typing-workload byte-ratio measurement
103	```	103	```
104		104
		105	`muxa` is the agent-facing client — verbs `status`, `capture`, `send`,
		106	`run`, `await`, one JSON object each, against a local socket or
		107	`--quic HOST`. `muxa run "make test"` sends the command line, waits for the
		108	shell to return it, and prints the exit code with the output rows; no
		109	polling and no sleeps, because the daemon holds the wait. It attaches at
		110	0×0 so it never resizes the session a human is using, and every reply names
		111	the `mechanism` that answered — an exit code is real only under `marks`
		112	(OSC 133 shell integration, injected at spawn), absent under the `pgid` and
		113	`settle` fallbacks.
		114
105	Multiple clients may attach to one session; the grid follows the most	115	Multiple clients may attach to one session; the grid follows the most
106	recently active client — typing, attaching, or resizing claims it (latest	116	recently active client — typing, attaching, or resizing claims it (latest
107	wins). A session survives logout (this assumes systemd-logind's default	117	wins). A session survives logout (this assumes systemd-logind's default

build.zig

Old		New
@@ -197,6 +197,30 @@ pub fn build(b: *std.Build) void {
197	delta_mod.addImport("engine", engine_mod);	197	delta_mod.addImport("engine", engine_mod);
198	delta_mod.addImport("protocol", protocol_mod);	198	delta_mod.addImport("protocol", protocol_mod);
199		199
		200	// The session's command state machine: MarkEvents in, transitions out.
		201	// Engine plus protocol and nothing else, same shape as delta_mod — pure,
		202	// socket-free, and its own tests drive it with no daemon in sight.
		203	const cmd_mod = b.createModule(.{
		204	.root_source_file = b.path("src/cmd.zig"),
		205	.target = target,
		206	.optimize = optimize,
		207	});
		208	cmd_mod.addImport("engine", engine_mod);
		209	cmd_mod.addImport("protocol", protocol_mod);
		210
		211	// Shell integration: the OSC 133 mark scripts and what a spawn must add
		212	// to hand them to a shell. Near-leaf on purpose — it writes files and
		213	// reads the environment, and knows nothing of ptys, servers or the
		214	// protocol, so its tests need no daemon and no socket. The one import
		215	// is xdg, for the private-directory policy the shim directory shares
		216	// with the key file's parent; xdg is itself a leaf, so no cycle.
		217	const shellint_mod = b.createModule(.{
		218	.root_source_file = b.path("src/shellint.zig"),
		219	.target = target,
		220	.optimize = optimize,
		221	});
		222	shellint_mod.addImport("xdg", xdg_mod);
		223
200	// The replay core: snapshot/delta application and the resume	224	// The replay core: snapshot/delta application and the resume
201	// coordinates, shared by the CLI client, the wasm core, and the	225	// coordinates, shared by the CLI client, the wasm core, and the
202	// server's test fixtures. Engine plus protocol and nothing else, and	226	// server's test fixtures. Engine plus protocol and nothing else, and
@@ -248,6 +272,8 @@ pub fn build(b: *std.Build) void {
248	server_mod.addImport("pty", pty_mod);	272	server_mod.addImport("pty", pty_mod);
249	server_mod.addImport("protocol", protocol_mod);	273	server_mod.addImport("protocol", protocol_mod);
250	server_mod.addImport("delta", delta_mod);	274	server_mod.addImport("delta", delta_mod);
		275	server_mod.addImport("cmd", cmd_mod);
		276	server_mod.addImport("shellint", shellint_mod);
251	server_mod.addImport("replica", replica_mod);	277	server_mod.addImport("replica", replica_mod);
252	server_mod.addImport("sockpath", sockpath_mod);	278	server_mod.addImport("sockpath", sockpath_mod);
253	// Both: the listener it owns, and the vocabulary it names directly	279	// Both: the listener it owns, and the vocabulary it names directly
@@ -306,6 +332,7 @@ pub fn build(b: *std.Build) void {
306	client_mod.addImport("replica", replica_mod);	332	client_mod.addImport("replica", replica_mod);
307	client_mod.addImport("testtmp", testtmp_mod);	333	client_mod.addImport("testtmp", testtmp_mod);
308	client_mod.addImport("quic_client", quic_client_mod);	334	client_mod.addImport("quic_client", quic_client_mod);
		335	client_mod.addImport("quic", quic_mod);
309	// The client is the only thing that predicts: the overlay is a local	336	// The client is the only thing that predicts: the overlay is a local
310	// display decision and never becomes state anybody else can see.	337	// display decision and never becomes state anybody else can see.
311	client_mod.addImport("predict", predict_mod);	338	client_mod.addImport("predict", predict_mod);
@@ -389,6 +416,7 @@ pub fn build(b: *std.Build) void {
389	});	416	});
390	exe_mod.addImport("server", server_mod);	417	exe_mod.addImport("server", server_mod);
391	exe_mod.addImport("protocol", protocol_mod);	418	exe_mod.addImport("protocol", protocol_mod);
		419	exe_mod.addImport("cmd", cmd_mod);
392	exe_mod.addImport("proxy", proxy_mod);	420	exe_mod.addImport("proxy", proxy_mod);
393	// The daemon entrypoint loads the key and constructs the listener, so it	421	// The daemon entrypoint loads the key and constructs the listener, so it
394	// needs the modules directly rather than through the server.	422	// needs the modules directly rather than through the server.
@@ -415,6 +443,24 @@ pub fn build(b: *std.Build) void {
415	linkQuic(b, exe, quic);	443	linkQuic(b, exe, quic);
416	b.installArtifact(exe);	444	b.installArtifact(exe);
417		445
		446	// The agent-facing client. It speaks frames and owns no terminal, which
		447	// is the whole point — it attaches at 0x0 and never claims the grid.
		448	// The transport modules are the CLI client's, minus everything that
		449	// renders: `quic_client` for the remote arm and `xdg` for the one
		450	// key-resolution rule all three binaries obey. Deliberately still no
		451	// engine and no replica — muxa has nothing to draw.
		452	const muxa_mod = b.createModule(.{
		453	.root_source_file = b.path("src/muxa.zig"),
		454	.target = target,
		455	.optimize = optimize,
		456	.link_libc = true,
		457	});
		458	muxa_mod.addImport("protocol", protocol_mod);
		459	muxa_mod.addImport("sockpath", sockpath_mod);
		460	muxa_mod.addImport("quic_client", quic_client_mod);
		461	muxa_mod.addImport("quic", quic_mod);
		462	muxa_mod.addImport("xdg", xdg_mod);
		463
418	const mux_exe = b.addExecutable(.{ .name = "mux", .root_module = mux_mod });	464	const mux_exe = b.addExecutable(.{ .name = "mux", .root_module = mux_mod });
419	mux_exe.use_llvm = true;	465	mux_exe.use_llvm = true;
420	mux_exe.use_lld = true;	466	mux_exe.use_lld = true;
@@ -422,6 +468,13 @@ pub fn build(b: *std.Build) void {
422	linkQuic(b, mux_exe, quic);	468	linkQuic(b, mux_exe, quic);
423	b.installArtifact(mux_exe);	469	b.installArtifact(mux_exe);
424		470
		471	const muxa_exe = b.addExecutable(.{ .name = "muxa", .root_module = muxa_mod });
		472	muxa_exe.use_llvm = true;
		473	muxa_exe.use_lld = true;
		474	// The agent client dials remote daemons now, so it carries the stack too.
		475	linkQuic(b, muxa_exe, quic);
		476	b.installArtifact(muxa_exe);
		477
425	const rawmode_exe = b.addExecutable(.{ .name = "rawmode", .root_module = rawmode_mod });	478	const rawmode_exe = b.addExecutable(.{ .name = "rawmode", .root_module = rawmode_mod });
426	rawmode_exe.use_llvm = true;	479	rawmode_exe.use_llvm = true;
427	rawmode_exe.use_lld = true;	480	rawmode_exe.use_lld = true;
@@ -524,11 +577,11 @@ pub fn build(b: *std.Build) void {
524	b.installArtifact(webhub_exe);	577	b.installArtifact(webhub_exe);
525		578
526	const test_step = b.step("test", "Run unit tests");	579	const test_step = b.step("test", "Run unit tests");
527	// delta_mod and sockpath_mod sit BEFORE server_mod, deliberately: their	580	// delta_mod, cmd_mod, shellint_mod and sockpath_mod sit BEFORE server_mod,
528	// tests are seconds-long and socket-free, while a regression in either	581	// deliberately: their tests are seconds-long and socket-free, while a
529	// can wedge a server test that waits on a client forever — and a wedged	582	// regression in any of them can wedge a server test that waits on a
530	// step prints nothing at all. Failing first is what makes the catch	583	// client forever — and a wedged step prints nothing at all. Failing
531	// legible.	584	// first is what makes the catch legible.
532	//	585	//
533	// mux_mod and exe_mod are executable roots, but they carry the argument	586	// mux_mod and exe_mod are executable roots, but they carry the argument
534	// parsers, and a test that is never built is not a test. exe_mod's	587	// parsers, and a test that is never built is not a test. exe_mod's
@@ -539,7 +592,7 @@ pub fn build(b: *std.Build) void {
539	// script_mod leads for the same order-is-legibility reason: its tests	592	// script_mod leads for the same order-is-legibility reason: its tests
540	// are instant and allocation-only, and the escape pins they carry are	593	// are instant and allocation-only, and the escape pins they carry are
541	// the ones both fixtures inherit.	594	// the ones both fixtures inherit.
542	for ([_]*std.Build.Module{ script_mod, protocol_mod, engine_mod, pty_mod, delta_mod, replica_mod, keymap_mod, webhub_mod, sockpath_mod, server_mod, client_mod, proxy_mod, mux_mod, quic_mod, quic_server_mod, exe_mod, testtmp_mod, quic_client_mod, predict_mod, rawmode_mod, delaypipe_mod, xdg_mod, spawn_mod, handoff_mod, paint_mod, render_mod, ptyclient_mod, webhub_main_mod, wsclient_mod }) \|mod\| {	595	for ([_]*std.Build.Module{ script_mod, protocol_mod, engine_mod, pty_mod, delta_mod, cmd_mod, shellint_mod, replica_mod, keymap_mod, webhub_mod, sockpath_mod, muxa_mod, server_mod, client_mod, proxy_mod, mux_mod, quic_mod, quic_server_mod, exe_mod, testtmp_mod, quic_client_mod, predict_mod, rawmode_mod, delaypipe_mod, xdg_mod, spawn_mod, handoff_mod, paint_mod, render_mod, ptyclient_mod, webhub_main_mod, wsclient_mod }) \|mod\| {
543	const t = b.addTest(.{ .root_module = mod });	596	const t = b.addTest(.{ .root_module = mod });
544	t.use_llvm = true;	597	t.use_llvm = true;
545	t.use_lld = true;	598	t.use_lld = true;
@@ -552,7 +605,7 @@ pub fn build(b: *std.Build) void {
552	if (mod == server_mod or mod == quic_mod or mod == quic_server_mod or	605	if (mod == server_mod or mod == quic_mod or mod == quic_server_mod or
553	mod == exe_mod or mod == client_mod or mod == mux_mod or	606	mod == exe_mod or mod == client_mod or mod == mux_mod or
554	mod == quic_client_mod or mod == webhub_mod or	607	mod == quic_client_mod or mod == webhub_mod or
555	mod == webhub_main_mod) linkQuic(b, t, quic);	608	mod == muxa_mod or mod == webhub_main_mod) linkQuic(b, t, quic);
556	test_step.dependOn(&b.addRunArtifact(t).step);	609	test_step.dependOn(&b.addRunArtifact(t).step);
557	}	610	}
558		611
@@ -597,6 +650,19 @@ pub fn build(b: *std.Build) void {
597	const e2e_step = b.step("e2e", "Run end-to-end test");	650	const e2e_step = b.step("e2e", "Run end-to-end test");
598	e2e_step.dependOn(&e2e.step);	651	e2e_step.dependOn(&e2e.step);
599		652
		653	// The agent surface gets a step of its own rather than a place in e2e:
		654	// its nine scenarios spend ~51s mostly waiting on real idle timeouts and
		655	// a 20s quiet await, which is a cost the paint-and-convergence suite
		656	// should not have to carry on every run. A step is what makes it a gate
		657	// at all — M7's rule, paid for twice: an end-to-end property that only
		658	// runs when somebody types the script is the shape a regression ships
		659	// through.
		660	const agent = b.addSystemCommand(&.{"test/agent.sh"});
		661	agent.addArtifactArg(exe);
		662	agent.addArtifactArg(muxa_exe);
		663	const agent_step = b.step("agent", "Run the agent-surface end-to-end suite");
		664	agent_step.dependOn(&agent.step);
		665
600	const soak = b.addSystemCommand(&.{"test/soak.sh"});	666	const soak = b.addSystemCommand(&.{"test/soak.sh"});
601	soak.addArtifactArg(exe);	667	soak.addArtifactArg(exe);
602	soak.addArtifactArg(mux_exe);	668	soak.addArtifactArg(mux_exe);

docs/decisions.md

+handTarget() seam so mux_main's idle_ms threading gets a pin;
+verify.js's wall-attach sequence covers the shell's call set but the
+page's boot stays browser-only (the banked headless item).
+## 2026-08-13 (agent surface — native LLM integration)
+Twelve tasks, shipped the same day as M17: OSC 133 command boundaries in
+the daemon, three new frame pairs, and `muxa`, a fourth binary that speaks
+JSON to an agent's shell tool. An agent now *knows* when a command
+returned, with its exit code and its output span, locally or over QUIC —
+the thing `tmux send-keys` + `capture-pane` structurally cannot say. The
+spec is `docs/superpowers/specs/2026-08-13-agent-surface-design.md`; what
+follows is what the implementation decided, which is not always what the
+spec guessed.
+**Output spans are rows, not seqs — and rows are locators, not anchors.**
+The tracker's `seq` is a viewport delta generation: a whole command's
+output can share one, and a row loses its seq the moment it scrolls into
+history. So a mark records the absolute screen row (`historyRows() +
+cursor.y`) at mark time and output recovery is the existing
+`fetch_scrollback`, unchanged. The honesty is on the field, not in prose:
+`Engine.MarkEvent.row` says that pruning past `max_scrollback` shifts the
+origin (a command longer than the scrollback can leave `end_row <
+start_row`), that resize reflow renumbers history, and that alt-screen
+marks live in a coordinate space where `historyRows()` is 0. Point a human
+at output with it; never key durable state on it.
+**An await is answered from a persisted snapshot, never from live tracker
+state.** Real shell integration emits `D;code` and `A` in one burst, so
+both fold in a single pty read and the phase is back to `at_prompt` before
+any await ever looks. A gate on `cmd.phase == .returned` therefore loses
+deterministically — it was written that way first, and the test that
+caught it drives a real shell rather than a hand-built mark sequence.
+`last_return` is the fix and the one owner: stamped at the `D`, carrying
+the exit code, the span AND the seq that qualifies it, so the answer and
+the reason it qualifies are the same record and no later reading of live
+state can drift out from under it. It also answers correctly once the
+*next* command is already running, which is the general rule worth
+keeping: **an await asks about a past event; live state describes now.**
+**OSC 133 interception wraps the dependency's handler rather than patching
+it.** ghostty-vt already parses semantic prompts including the `err` code,
+but its stock handler drops the code and exposes no callback. `vt.Stream(H)`
+is generic over the handler, so `MuxHandler` intercepts `.semantic_prompt`
+and forwards every other action verbatim: terminal state stays identical,
+the pinned dep stays unmodified, and there is no byte-stream scanning
+anywhere. The engine's hardcoded `vt.TerminalStream` became
+`vt.Stream(MuxHandler)` and nothing else moved.
+**Awaits resolve at the run loop's 100ms tick, with no deadline folding
+into poll.** The spec expected settle/timeout/pgid deadlines to fold into
+`wait_ms` the way QUIC's `timeoutMs` does. They do not need to: nothing in
+`checkAwaits` blocks, the granularity bound is the tick the daemon already
+beats at, and an agent's cheapest verb costs a round trip anyway. The pass
+sits after every arm that can move the session on — so it sees this pump's
+marks, pgid and silence — and *before* the QUIC `drainAll`, because a
+resolved await queues a frame and `drainAll` is what puts it on the wire.
+The other order costs every remote await a whole extra poll cycle.
+**Session death is an answer on the lifecycle verbs and an error on the
+rest.** `muxa run` and `muxa await` print
+`{"reason":"session_ended","exit_code":N}` and exit 0 — a command that
+killed its own shell answered the question that was asked. `status`,
+`capture` and `send` have no answer to give, so they print the house's
+`{"error":…,"detail":…,"exit_code":…}` shape and exit 1. **Field note that
+cost a test:** `send`'s ack round-trip reliably WINS the race against a pty
+death, so `send` cannot be relied on to report a session that is dying —
+the next call is what sees it. That is a property of the ordering, not a
+flake.
+**`--timeout` is the daemon's window; the client adds bounded grace.** The
+daemon's clock starts when it reads the request, so a client that waits
+exactly `--timeout` always loses the race to the reply and reports a
+timeout the daemon never had. The grace is `min(30s, max(2s, 4 ×
+connect_ms))`: flat 2s over a unix socket, RTT-derived over QUIC from the
+one measurement the client already has (its own handshake), capped so a
+handshake that took a minute cannot buy a minute of grace. The cost is
+named because agents budget wall clock: a `--timeout N` wait can overshoot
+N by the grace window.
+**Reconnect is at-most-once for the wire and exactly-never for input.**
+One redial per process, on `ConnectionLost` and on nothing else (a
+`SendStalled` peer is still there and has already spent the flush bound
+proving it). What is re-sent is the attach and the `await_req` with the
+ORIGINAL `since_seq` — idempotent by construction, and the reason a return
+that landed inside the gap is answered instead of missed — and never
+`run`'s input. A command line lost with the connection surfaces as an
+honest timeout, not as `make deploy` running twice: **a wait may be
+repeated because asking twice changes nothing; an input may not, because it
+changes everything.** A redial that fails is recorded rather than
+swallowed, so the verb reports both halves — `connection lost; reconnect
+failed: <err>` — and a second tear after a spent redial says so in its own
+words.
+**`settled` means output went quiet, not that the process exited.** The
+settle and pgid resolutions carry `exit_code: null` and a `phase` derived
+from marks, which on a markless shell reads `at_prompt` — the tracker
+never saw a `C`, so it is telling the truth about what it knows. Only
+`mechanism == "marks"` carries a trustworthy exit code, which is why every
+reply names its mechanism. An agent that reads `exit_code` without reading
+`mechanism` is reading a guess.
+### Field limitations, shipped knowingly
+- **zsh under the `ZDOTDIR` shim never sources `~/.zshenv`.** zsh looks for
+  `.zshenv` under `$ZDOTDIR`, and the shim directory has none. The `.zshrc`
+  is handed back (the common case); a `.zshenv` shim that restores
+  `ZDOTDIR` the way ghostty's does is the roadmap fix.
+- **The bash shim's DEBUG trap displaces a user's own DEBUG trap** —
+  silently, and that is bash-preexec, atuin and iTerm2's integration. The
+  roadmap fix is coexistence via bash-preexec detection. Two limits of the
+  membership guard that keeps `PROMPT_COMMAND`'s own members from being
+  counted as commands: a typed command textually identical to a
+  `PROMPT_COMMAND` member loses its marks (degrading to pgid/settle, not to
+  a wrong answer), and a compound string member (`a; b`) can re-arm the
+  guard. Arrays — bash 5.1's default and what the shim prefers — are exact.
+- **A SIGKILLed daemon orphans its `mux-shellint-{pid}` directory.**
+  Bounded and per-pid, cleaned on every ordinary exit; a startup sweep of
+  dead-pid directories is the roadmap item. `prepare()` failing is degraded
+  and never fatal: the session runs on pgid and settle, and says so on
+  stderr, because refusing to start a daemon over an optional enhancement
+  would invert the module's premise.
+- **`muxa` has no idle-timeout flag, by design.** It takes
+  `quic.default_idle_ms` and lets `--timeout` be the only bound on a wait;
+  `muxd`, `mux` and `muxweb` keep `--quic-idle-ms`.
+### Deferred, and named so the deferral reads as a choice
+The spec's non-goals stand: **no MCP server** (a wrapper over `muxa` needs
+no protocol change, so it can be layered whenever someone wants it), **no
+read-only or capability-scoped auth** (one key is still full control, which
+is the same posture every other transport has), **no input attribution**
+(an attached human cannot tell which keystrokes were the agent's), **no
+semantic event subscriptions** beyond the `cmd_state` push, and no
+single-shot `muxa drive` (`send` + `await` + `capture` composes it). Added
+by the reviews: the `.zshenv` shim, bash-preexec coexistence, and the
+shim-directory startup sweep.
+**`capture --diff-since` was promised and not built, and this is the
+record.** The spec names it three times — the verb list, the TUI-driving
+composition ("`send` + `status` + `capture --diff-since`"), and the testing
+plan — and execution dropped it with no code and no deferral written
+anywhere; the whole-branch review is the only reason it is written down
+now. `muxa capture` ships as the whole grid, `--vt` or plain. What a future
+one owes is more than the flag: `status_reply`'s `seq` carries the RETURN
+WATERMARK (`last_return`'s seq, 0 when nothing has returned this session),
+which is exactly what an await's `since_seq` wants and useless as the SEQ a
+diff quotes — after this milestone the live stream seq is on no reply an
+agent can read. So `--diff-since` needs a protocol field of its own, and
+must not be built by re-reading a field that already means something else.
+**Two smaller narrowings against the spec, recorded rather than left to be
+rediscovered.** (1) The **fish** injection arm is unit-tested only:
+`prepare` writes `fish/vendor_conf.d` and prepends `XDG_DATA_DIRS`, and
+that is pinned, but no test anywhere runs fish — there is none on this box.
+zsh and bash are both driven live against a real session. (2) The spec's
+**version-skew test** — `muxa status` against an old-protocol daemon
+reports the structured error — was not written. The behaviour is real and
+not unpinned (a daemon that drops the frame and a daemon that never answers
+are the same wait and the same `{"error":"status: no reply"}`, which the
+dead-daemon paths do exercise), but the named fixture, an actual old
+binary, does not exist.
+**Paid in a separate commit, and only after the e2e pinned the spellings:**
+`parseQuicAddr`/`resolveHost` now live in `quic.zig` as one owner for the
+dial-address grammar, taking an allocator (`client.zig`'s copy hardcoded
+`std.heap.page_allocator`, so the fold is also a fix). A human typing
+`mux quic://HOST:PORT` and an agent typing `muxa --quic HOST:PORT` were
+parsing the same grammar through two copies, which is how one flag becomes
+two dialects.

docs/roadmap.md

+this file at each milestone close and whenever the queue reorders; the
+queue's order is set by the user, not by this file.
+**Now:** M1–M15 and M17 complete, plus the agent surface; published as a
+Linux tarball, tagged through `v0.0.1-5`; in
+field trial on real VMs, and the trial is now producing the queue.
+Trial feedback outranks everything below — what actually hurts in use is
+better data than any of this ranking, and the proof is that the three
+by the headless browser-boot automation ("the page never ran" was the
+milestone's defining defect), are listed there.
+## Agent surface — native LLM integration — complete
+Shipped 2026-08-13 (ac9373f..cbd7007 + close-out), twelve tasks. An agent
+driving a mux session now *knows* when a command returned, with its exit
+code and the rows its output occupies, over a unix socket or over QUIC —
+which is the signal `tmux send-keys` + `capture-pane` structurally cannot
+give and the reason this exists. What shipped: OSC 133 marks injected at
+spawn (`shellint.zig` — zsh `ZDOTDIR` shim, bash `--init-file`, fish
+`vendor_conf.d`), a mux-owned ghostty-vt stream handler that surfaces them
+as row-stamped events, a pure command state machine (`cmd.zig`), three
+frame pairs (`cmd_state`, `await_req`/`await_reply`,
+`status_req`/`status_reply`) that ride `muxd proxy` untouched, server-held
+awaits with a pgid edge and a settle floor under the marks path, and
+`muxa` — a fourth binary, five verbs, one JSON object per verb, attaching
+at 0×0 so an agent never claims the human's grid. e2e is `test/agent.sh`,
+**9 scenarios**, including a QUIC tear healed mid-await with the command
+proven to have run exactly once. The decisions worth reading before
+touching it are in decisions.md: rows are locators and not anchors, an
+await is answered from `last_return` and never from live tracker state,
+and only `mechanism == "marks"` carries a real exit code.
+**Field limitations, shipped knowingly** (each is a roadmap item, none is a
+blocker):
+- **zsh loses `~/.zshenv`** under the `ZDOTDIR` shim — the shim directory
+  has none. A ghostty-style `.zshenv` shim is the fix.
+- **The bash shim's DEBUG trap displaces the user's**, silently: that is
+  bash-preexec, atuin and iTerm2. Coexistence via bash-preexec detection is
+  the fix. Two membership-guard limits stand meanwhile: a typed command
+  textually identical to a `PROMPT_COMMAND` member loses its marks
+  (degrading to pgid/settle), and a compound string member (`a; b`) can
+  re-arm the guard — arrays, the modern default, are exact.
+- **A SIGKILLed daemon orphans its `mux-shellint-{pid}` directory**; a
+  startup sweep of dead-pid directories is owed. Injection failing is
+  always degraded and never fatal.
+- **`--timeout N` can overshoot N** by the client's grace window (2s over a
+  socket, up to 30s over a slow QUIC handshake): an agent budgeting wall
+  clock must add it.
+- **`muxa` has no idle-timeout flag**, deliberately — `--timeout` is the
+  only bound on a wait.
+**Deferred, and named** (the spec's non-goals plus what review added): an
+MCP server wrapping `muxa`; read-only or capability-scoped auth (one key =
+full control still); input attribution; semantic event subscriptions
+beyond the `cmd_state` push; `muxa drive` as single-shot sugar; the
+`.zshenv` shim; bash-preexec coexistence; the shim-directory startup
+sweep. The `parseQuicAddr`/`resolveHost` dedup that review endorsed is
+**paid**, not deferred — one owner in `quic.zig`, landed after the e2e had
+pinned the spellings.
+**Dropped in execution, not decided — the one item here that nobody chose:**
+`muxa capture --diff-since SEQ`. The spec promises it three times and no
+code was written; the whole-branch review found it. A future one needs a
+protocol field of its own for the live stream seq, because `status_reply`'s
+seq now carries the return watermark — right for awaits, wrong for a diff
+to quote (decisions.md). Two coverage narrowings ride with it: the **fish**
+injection arm is unit-tested only (no fish on this box; zsh and bash are
+driven live), and the spec's **version-skew fixture** was never built (the
+behaviour is pinned through the dead-daemon paths, an old binary is not).
+And `muxa capture` is **the one verb with no automated coverage at all** —
+`test/agent.sh` drives run, await, send and status; capture is where
+`--diff-since` would land, so the test and the flag are owed together.
+## M16 candidates — and still outranked by trial feedback
+What remains is what was ranked behind M13 and M14 and survived M15,

docs/superpowers/plans/2026-08-13-agent-surface.md

@@ @@ -0,0 +1,1953 @@ @@
+# Agent Surface Implementation Plan
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+**Goal:** Native LLM/agent integration for mux: OSC 133 command boundaries with exit codes, server-side await, structured status, and a standalone `muxa` binary speaking unix socket and QUIC.
+**Architecture:** The daemon's ghostty-vt stream is wrapped in a mux-owned handler that intercepts semantic-prompt (OSC 133) actions and queues mark events (engine = mechanism). The server folds those events into a per-session command state machine, pushes `cmd_state`, and holds `await_req` open server-side with pgid/settle fallbacks (server = policy). Shell integration is injected at spawn because muxd forks the shell itself. `muxa` is a new thin client binary emitting JSON.
+**Tech Stack:** Zig 0.15.2 (pinned: `~/Downloads/zig-x86_64-linux-0.15.2/zig`, LLVM+LLD — see docs/decisions.md), ghostty-vt vendored dep, existing `protocol.zig` frame style.
+**Spec:** `docs/superpowers/specs/2026-08-13-agent-surface-design.md` — read it first.
+> **Status (2026-08-13, all twelve tasks shipped):** this file is the
+> historical execution record — what was planned and in what order — and it
+> is deliberately not updated to match what landed. Where the two disagree,
+> the code and `docs/decisions.md` are the truth. The divergences worth
+> knowing before reading below: `returned_seq` was deleted in favour of one
+> owner, `last_return`, which carries the watermark inside the answer;
+> `checkAwaits` runs before the QUIC `drainAll` at the end of the pump, not
+> after it; `muxa status` nests the cursor in its JSON; and the bash shim's
+> final shape (array-aware `PROMPT_COMMAND`, membership guard, trap
+> installed last) postdates the text in Task 7.
+**Conventions for every task:**
+- `ZIG=~/Downloads/zig-x86_64-linux-0.15.2/zig` — run from the worktree root (`.worktrees/agent-surface`).
+- Full suite: `$ZIG build test`. It must pass before every commit.
+- House doctrine: pinned regression tests go BEFORE any test the same hang could wedge (see MEMORY: a wedged zig test step prints nothing).
+- Commit messages follow the repo style: lowercase type prefix, sentence explaining the why. Every commit ends with the `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>` trailer.
+---
+## File structure (locked in)
+| File | Responsibility |
+|---|---|
+| `src/protocol.zig` (modify) | New MsgTypes + `CmdState`/`AwaitReq`/`StatusReply` encode/decode. Wire format only. |
+| `src/engine.zig` (modify) | `MuxHandler` wrapping the stock ghostty handler; queues `MarkEvent`s with rows. No policy. |
+| `src/cmd.zig` (create) | Pure command state machine: MarkEvents in, transitions out. No I/O. |
+| `src/pty.zig` (modify) | `fgPgid()` (TIOCGPGRP on the master) + optional child env pairs for injection. |
+| `src/shellint.zig` (create) | Shell detection, shim/script file creation, env pairs. No daemon knowledge. |
+| `src/server.zig` (modify) | Integration: drain mark events, stamp seq, push `cmd_state`, hold awaits, answer `status_req`. |
+| `src/main.zig` (modify) | Injection wiring + `MUX_SHELL_INTEGRATION` opt-out for `muxd run`/`start`. |
+| `src/muxa.zig` (create) | Standalone agent binary: verbs `status`/`capture`/`send`/`run`/`await`, JSON out, unix+QUIC. |
+| `test/agent.sh` (create) | Binary-level e2e: shell session marks, TUI ephemeral session, QUIC. |
+| `build.zig` (modify) | `muxa` executable + module wiring + `cmd`/`shellint` test steps. |
+---
+### Task 1: Protocol frames (`cmd_state`, `await_req`/`await_reply`, `status_req`/`status_reply`)
+**Files:**
+- Modify: `src/protocol.zig`
+- [ ] **Step 1: Write the failing tests** — append to `src/protocol.zig`:
+```zig
+test "cmd_state encode/decode round trip and golden bytes" {
+    const s = CmdState{
+        .phase = .returned,
+        .mechanism = .marks,
+        .exit_code = 1,
+        .start_row = 80,
+        .end_row = 92,
+        .seq = 258,
+    };
+    const buf = encodeCmdState(s);
+    try std.testing.expectEqualSlices(u8, &[_]u8{
+, // phase returned
+, // mechanism marks
+, // has_exit
+, // exit_code
+x50, 0, 0, 0, // start_row 80
+x5C, 0, 0, 0, // end_row 92
+x02, 0x01, 0, 0, 0, 0, 0, 0, // seq 258
+    }, &buf);
+    const back = try decodeCmdState(&buf);
+    try std.testing.expectEqual(s, back);
+}
+test "cmd_state with no exit code round-trips null, not zero" {
+    const s = CmdState{ .phase = .running, .mechanism = .pgid, .exit_code = null, .start_row = 5, .end_row = 0, .seq = 9 };
+    const back = try decodeCmdState(&encodeCmdState(s));
+    try std.testing.expectEqual(@as(?u8, null), back.exit_code);
+}
+test "cmd_state rejects wrong length and unknown enum bytes" {
+    try std.testing.expectError(error.BadPayload, decodeCmdState(&[_]u8{0} ** (cmd_state_len - 1)));
+    try std.testing.expectError(error.BadPayload, decodeCmdState(&[_]u8{0} ** (cmd_state_len + 1)));
+    var bad = encodeCmdState(.{ .phase = .at_prompt, .mechanism = .settle, .exit_code = null, .start_row = 0, .end_row = 0, .seq = 0 });
+    bad[0] = 9; // phase out of range
+    try std.testing.expectError(error.BadPayload, decodeCmdState(&bad));
+    bad[0] = 0;
+    bad[1] = 9; // mechanism out of range
+    try std.testing.expectError(error.BadPayload, decodeCmdState(&bad));
+}
+test "await_req encode/decode round trip" {
+    const r = try decodeAwaitReq(&encodeAwaitReq(.{ .since_seq = 77, .settle_ms = 500, .timeout_ms = 30_000 }));
+    try std.testing.expectEqual(@as(u64, 77), r.since_seq);
+    try std.testing.expectEqual(@as(u32, 500), r.settle_ms);
+    try std.testing.expectEqual(@as(u32, 30_000), r.timeout_ms);
+    try std.testing.expectError(error.BadPayload, decodeAwaitReq(&[_]u8{0} ** 15));
+}
+test "await_reply is a CmdState plus a reason byte" {
+    const s = CmdState{ .phase = .returned, .mechanism = .settle, .exit_code = null, .start_row = 0, .end_row = 3, .seq = 4 };
+    const buf = encodeAwaitReply(s, .settled);
+    try std.testing.expectEqual(@as(usize, await_reply_len), buf.len);
+    const back = try decodeAwaitReply(&buf);
+    try std.testing.expectEqual(AwaitReason.settled, back.reason);
+    try std.testing.expectEqual(s, back.state);
+    var bad = buf;
+    bad[cmd_state_len] = 9;
+    try std.testing.expectError(error.BadPayload, decodeAwaitReply(&bad));
+}
+test "status_reply encode/decode round trip" {
+    const s = StatusReply{
+        .cols = 120,
+        .rows = 40,
+        .cursor_x = 3,
+        .cursor_y = 5,
+        .history_rows = 77,
+        .alt_screen = true,
+        .mode = .{ .icanon = true, .echo = true },
+        .cmd = .{ .phase = .at_prompt, .mechanism = .marks, .exit_code = 0, .start_row = 1, .end_row = 2, .seq = 6 },
+    };
+    const back = try decodeStatusReply(&encodeStatusReply(s));
+    try std.testing.expectEqual(s, back);
+    try std.testing.expectError(error.BadPayload, decodeStatusReply(&[_]u8{0} ** (status_reply_len - 1)));
+}
+```
+- [ ] **Step 2: Run to verify failure**
+Run: `$ZIG build test 2>&1 | tail -5`
+Expected: compile error — `CmdState` not defined.
+- [ ] **Step 3: Implement.** In the `MsgType` enum, add after `endpoint_req = 0x08`:
+```zig
+    await_req = 0x09, // payload: u64 LE since_seq, u32 LE settle_ms, u32 LE timeout_ms
+    status_req = 0x0a, // payload: empty
+```
+and after `endpoint_reply = 0x89` (the 0x83 hole stays untouched — it is historical):
+```zig
+    cmd_state = 0x8a, // payload: CmdState (see encodeCmdState); pushed on marks-regime transitions
+    await_reply = 0x8b, // payload: CmdState ++ 1 byte AwaitReason
+    status_reply = 0x8c, // payload: StatusReply (see encodeStatusReply)
+```
+Then add below `decodeEndpointReply` (house style: explicit encode/decode over fixed LE buffers):
+```zig
+/// Where the command-boundary signal came from, weakest-last. `marks` is the
+/// only mechanism that can carry an exit code; consumers must check it
+/// before trusting one.
+pub const Mechanism = enum(u8) { marks = 0, pgid = 1, settle = 2 };
+pub const CmdPhase = enum(u8) { at_prompt = 0, running = 1, returned = 2 };
+/// One snapshot of the session's command state machine. Rows are absolute
+/// screen-space rows (0 = oldest retained history row) — meaningless while
+/// the alt screen is active, and shifted once the scrollback ring prunes,
+/// so spans should be fetched promptly. `seq` is the delta-tracker seq
+/// stamped after the post-feed update (await ordering, nothing else).
+pub const CmdState = struct {
+    phase: CmdPhase,
+    mechanism: Mechanism,
+    exit_code: ?u8,
+    start_row: u32,
+    end_row: u32,
+    seq: u64,
+};
+pub const cmd_state_len = 20;
+pub fn encodeCmdState(s: CmdState) [cmd_state_len]u8 {
+    var buf: [cmd_state_len]u8 = undefined;
+    buf[0] = @intFromEnum(s.phase);
+    buf[1] = @intFromEnum(s.mechanism);
+    buf[2] = @intFromBool(s.exit_code != null);
+    buf[3] = s.exit_code orelse 0;
+    std.mem.writeInt(u32, buf[4..8], s.start_row, .little);
+    std.mem.writeInt(u32, buf[8..12], s.end_row, .little);
+    std.mem.writeInt(u64, buf[12..20], s.seq, .little);
+    return buf;
+}
+fn enumFromByte(comptime E: type, b: u8) !E {
+    return std.meta.intToEnum(E, b) catch error.BadPayload;
+}
+pub fn decodeCmdState(payload: []const u8) !CmdState {
+    if (payload.len != cmd_state_len) return error.BadPayload;
+    return .{
+        .phase = try enumFromByte(CmdPhase, payload[0]),
+        .mechanism = try enumFromByte(Mechanism, payload[1]),
+        .exit_code = if (payload[2] != 0) payload[3] else null,
+        .start_row = std.mem.readInt(u32, payload[4..8], .little),
+        .end_row = std.mem.readInt(u32, payload[8..12], .little),
+        .seq = std.mem.readInt(u64, payload[12..20], .little),
+    };
+}
+pub const AwaitReq = struct { since_seq: u64, settle_ms: u32, timeout_ms: u32 };
+pub const await_req_len = 16;
+pub fn encodeAwaitReq(r: AwaitReq) [await_req_len]u8 {
+    var buf: [await_req_len]u8 = undefined;
+    std.mem.writeInt(u64, buf[0..8], r.since_seq, .little);
+    std.mem.writeInt(u32, buf[8..12], r.settle_ms, .little);
+    std.mem.writeInt(u32, buf[12..16], r.timeout_ms, .little);
+    return buf;
+}
+pub fn decodeAwaitReq(payload: []const u8) !AwaitReq {
+    if (payload.len != await_req_len) return error.BadPayload;
+    return .{
+        .since_seq = std.mem.readInt(u64, payload[0..8], .little),
+        .settle_ms = std.mem.readInt(u32, payload[8..12], .little),
+        .timeout_ms = std.mem.readInt(u32, payload[12..16], .little),
+    };
+}
+pub const AwaitReason = enum(u8) { returned = 0, settled = 1, timeout = 2 };
+pub const await_reply_len = cmd_state_len + 1;
+pub fn encodeAwaitReply(s: CmdState, reason: AwaitReason) [await_reply_len]u8 {
+    var buf: [await_reply_len]u8 = undefined;
+    buf[0..cmd_state_len].* = encodeCmdState(s);
+    buf[cmd_state_len] = @intFromEnum(reason);
+    return buf;
+}
+pub const AwaitReply = struct { state: CmdState, reason: AwaitReason };
+pub fn decodeAwaitReply(payload: []const u8) !AwaitReply {
+    if (payload.len != await_reply_len) return error.BadPayload;
+    return .{
+        .state = try decodeCmdState(payload[0..cmd_state_len]),
+        .reason = try enumFromByte(AwaitReason, payload[cmd_state_len]),
+    };
+}
+/// One structured snapshot for `muxa status`. The grid facts a driving
+/// agent needs before deciding how to interact: size, cursor, whether a
+/// TUI holds the screen, who echoes keystrokes, and the command state.
+pub const StatusReply = struct {
+    cols: u16,
+    rows: u16,
+    cursor_x: u16,
+    cursor_y: u16,
+    history_rows: u32,
+    alt_screen: bool,
+    mode: PtyModeFlags,
+    cmd: CmdState,
+};
+pub const status_reply_len = 14 + cmd_state_len;
+pub fn encodeStatusReply(s: StatusReply) [status_reply_len]u8 {
+    var buf: [status_reply_len]u8 = undefined;
+    std.mem.writeInt(u16, buf[0..2], s.cols, .little);
+    std.mem.writeInt(u16, buf[2..4], s.rows, .little);
+    std.mem.writeInt(u16, buf[4..6], s.cursor_x, .little);
+    std.mem.writeInt(u16, buf[6..8], s.cursor_y, .little);
+    std.mem.writeInt(u32, buf[8..12], s.history_rows, .little);
+    buf[12] = @intFromBool(s.alt_screen);
+    buf[13] = @bitCast(s.mode);
+    buf[14..].* = encodeCmdState(s.cmd);
+    return buf;
+}
+pub fn decodeStatusReply(payload: []const u8) !StatusReply {
+    if (payload.len != status_reply_len) return error.BadPayload;
+    return .{
+        .cols = std.mem.readInt(u16, payload[0..2], .little),
+        .rows = std.mem.readInt(u16, payload[2..4], .little),
+        .cursor_x = std.mem.readInt(u16, payload[4..6], .little),
+        .cursor_y = std.mem.readInt(u16, payload[6..8], .little),
+        .history_rows = std.mem.readInt(u32, payload[8..12], .little),
+        .alt_screen = payload[12] != 0,
+        .mode = try decodePtyMode(payload[13..14]),
+        .cmd = try decodeCmdState(payload[14..]),
+    };
+}
+```
+Note: `decodePtyMode` takes a slice; passing `payload[13..14]` reuses its length check. If the compiler wants `payload[14..]` as `*const [cmd_state_len]u8` for `decodeCmdState`, pass `payload[14..][0..cmd_state_len]`.
+- [ ] **Step 4: Run tests**
+Run: `$ZIG build test 2>&1 | tail -5`
+Expected: PASS (exit 0, no failures reported).
+- [ ] **Step 5: Commit**
+```bash
+git add src/protocol.zig
+git commit -m "feat(protocol): cmd_state, await, and status frames for the agent surface"
+```
+---
+### Task 2: `Pty.fgPgid` — the kernel's foreground answer
+**Files:**
+- Modify: `src/pty.zig`
+- [ ] **Step 1: Write the failing test** — append to `src/pty.zig`:
+```zig
+test "Pty: fgPgid tracks the foreground job" {
+    const alloc = std.testing.allocator;
+    var pty = try Pty.spawn(.{ .cols = 80, .rows = 24, .shell = "/bin/sh" });
+    defer pty.deinit();
+    // Prove the shell is up before asking anything of the pgid.
+    _ = try std.posix.write(pty.master, "printf 'ready-%s\\n' PGID\n");
+    var ready = try readUntil(alloc, &pty, "ready-PGID", 5000);
+    defer ready.deinit(alloc);
+    try std.testing.expect(std.mem.indexOf(u8, ready.items, "ready-PGID") != null);
+    // At the prompt, the foreground pgid is the shell's own process group.
+    // sh is the session leader post-forkpty, so its pgid == its pid.
+    try std.testing.expectEqual(pty.child, try pty.fgPgid());
+    // A foreground job moves the fg pgid off the shell... eventually: an
+    // interactive sh creates a new process group for the job. Poll for the
+    // change rather than racing it.
+    _ = try std.posix.write(pty.master, "sleep 2\n");
+    var moved = false;
+    var waited_ms: u64 = 0;
+    while (waited_ms < 3000) : (waited_ms += 50) {
+        if (try pty.fgPgid() != pty.child) {
+            moved = true;
+            break;
+        }
+        std.Thread.sleep(50 * std.time.ns_per_ms);
+    }
+    // Dash and busybox sh run foreground jobs in the shell's own group when
+    // job control is off (non-interactive stdin heuristics differ), so a
+    // never-moved pgid is a legal outcome for the fallback design — but on
+    // a pty, POSIX shells enable job control. Assert movement; if this
+    // flakes on some /bin/sh, relax to a log + skip, not a green lie.
+    try std.testing.expect(moved);
+    // ...and returns to the shell when the job ends.
+    waited_ms = 0;
+    while (waited_ms < 5000) : (waited_ms += 100) {
+        if (try pty.fgPgid() == pty.child) break;
+        std.Thread.sleep(100 * std.time.ns_per_ms);
+    }
+    try std.testing.expectEqual(pty.child, try pty.fgPgid());
+}
+```
+- [ ] **Step 2: Run to verify failure**
+Run: `$ZIG build test 2>&1 | tail -5`
+Expected: compile error — `fgPgid` not defined.
+- [ ] **Step 3: Implement** — add to `Pty` after `mode()`:
+```zig
+    /// The foreground process group of the session, read off the master
+    /// with TIOCGPGRP. When it equals `child` (the shell, session leader
+    /// post-forkpty), no foreground job is running — the kernel's own
+    /// "the command returned", available with zero shell cooperation.
+    /// No exit code and no output span; that is what marks are for.
+    pub fn fgPgid(self: *const Pty) !std.posix.pid_t {
+        var pgid: c.pid_t = 0;
+        if (c.ioctl(self.master, c.TIOCGPGRP, &pgid) < 0) return error.IoctlFailed;
+        return @intCast(pgid);
+    }
+```
+(`c` already cImports `sys/ioctl.h`; TIOCGPGRP comes with it via termios/ioctls. If the compile misses `c.pid_t`, use `c_int` for the local.)
+- [ ] **Step 4: Run tests**
+Run: `$ZIG build test 2>&1 | tail -5`
+Expected: PASS.
+- [ ] **Step 5: Commit**
+```bash
+git add src/pty.zig
+git commit -m "feat(pty): fgPgid reads the foreground job off the master"
+```
+---
+### Task 3: Engine — `MuxHandler` wrapper, mark events with rows
+**Files:**
+- Modify: `src/engine.zig`
+Background (verified against the vendored dep, `~/.cache/zig/p/ghostty-1.3.2-dev-5UdBC7VOBgVv0iA*/src/terminal/`): ghostty-vt parses OSC 133 into a `semantic_prompt` action whose value has `.action` (enum incl. `fresh_line_new_prompt`='A', `end_input_start_output`='C', `end_command`='D') and `readOption(.exit_code)` → `?i32`. The stock `Handler.vt` forwards it to `terminal.semanticPrompt` and drops the code. `vt.Stream(H)` is generic over the handler (exported as `vt.Stream`); the handler needs `deinit` and a `vt(comptime action, value)` method.
+- [ ] **Step 1: Write the failing tests** — append to `src/engine.zig`:
+```zig
+test "Engine: OSC 133 marks surface as events with rows and exit codes" {
+    const alloc = std.testing.allocator;
+    var e = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer e.deinit();
+    e.feed("$ "); // a prompt on row 0
+    e.feed("\x1b]133;C\x07"); // command starts
+    e.feed("output line\r\n");
+    e.feed("\x1b]133;D;1\x07"); // command returns, exit 1
+    e.feed("\x1b]133;A\x07"); // next prompt
+    const evs = e.markEvents();
+    try std.testing.expectEqual(@as(usize, 3), evs.len);
+    try std.testing.expectEqual(Engine.MarkEvent.Kind.command_start, evs[0].kind);
+    try std.testing.expectEqual(@as(u32, 0), evs[0].row);
+    try std.testing.expectEqual(@as(?u8, null), evs[0].exit_code);
+    try std.testing.expectEqual(Engine.MarkEvent.Kind.command_end, evs[1].kind);
+    try std.testing.expectEqual(@as(u32, 1), evs[1].row); // cursor moved past the output line
+    try std.testing.expectEqual(@as(?u8, 1), evs[1].exit_code);
+    try std.testing.expectEqual(Engine.MarkEvent.Kind.prompt_start, evs[2].kind);
+    e.clearMarkEvents();
+    try std.testing.expectEqual(@as(usize, 0), e.markEvents().len);
+}
+test "Engine: mark rows are absolute screen rows, not viewport rows" {
+    const alloc = std.testing.allocator;
+    var e = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer e.deinit();
+    // Scroll 100 lines into history, then mark: the row must include them.
+    var i: usize = 1;
+    while (i <= 100) : (i += 1) {
+        var line: [32]u8 = undefined;
+        e.feed(std.fmt.bufPrint(&line, "line-{d}\r\n", .{i}) catch unreachable);
+    }
+    const hist = e.historyRows(); // 77 per the historyRows test
+    e.feed("\x1b]133;C\x07");
+    const evs = e.markEvents();
+    try std.testing.expectEqual(@as(usize, 1), evs.len);
+    try std.testing.expectEqual(hist + e.cursorPos().y, evs[0].row);
+}
+test "Engine: a D mark with no exit code yields a null code" {
+    const alloc = std.testing.allocator;
+    var e = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer e.deinit();
+    e.feed("\x1b]133;C\x07\x1b]133;D\x07");
+    const evs = e.markEvents();
+    try std.testing.expectEqual(@as(usize, 2), evs.len);
+    try std.testing.expectEqual(@as(?u8, null), evs[1].exit_code);
+}
+test "Engine: non-133 OSC and the ignored 133 subcommands emit no events" {
+    const alloc = std.testing.allocator;
+    var e = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer e.deinit();
+    e.feed("\x1b]0;a title\x07"); // OSC 0, not semantic
+    e.feed("\x1b]133;B\x07\x1b]133;P\x07\x1b]133;L\x07"); // B/P/L: not ours
+    try std.testing.expectEqual(@as(usize, 0), e.markEvents().len);
+}
+```
+- [ ] **Step 2: Run to verify failure**
+Run: `$ZIG build test 2>&1 | tail -5`
+Expected: compile error — `markEvents` not defined.
+- [ ] **Step 3: Implement.** In `src/engine.zig`:
+Replace the `stream: vt.TerminalStream` field declaration with:
+```zig
+    stream: MuxStream,
+```
+Add above the `Engine` struct:
+```zig
+/// The stock ghostty-vt handler forwards OSC 133 into the terminal and
+/// drops the exit code on the floor; there is no semantic-prompt callback
+/// in its Effects. So mux brings its own handler: intercept the one action
+/// we care about, forward everything (including that one) to the stock
+/// handler so terminal state stays identical.
+pub const MuxHandler = struct {
+    inner: vt.TerminalStream.Handler,
+    pub fn deinit(self: *MuxHandler) void {
+        self.inner.deinit();
+    }
+    pub fn vt(
+        self: *MuxHandler,
+        comptime action: vt.StreamAction.Tag,
+        value: vt.StreamAction.Value(action),
+    ) void {
+        if (comptime action == .semantic_prompt) self.onSemanticPrompt(value);
+        self.inner.vt(action, value);
+    }
+    fn engineOf(self: *MuxHandler) *Engine {
+        const stream_ptr: *MuxStream = @fieldParentPtr("handler", self);
+        return @alignCast(@fieldParentPtr("stream", stream_ptr));
+    }
+    fn onSemanticPrompt(self: *MuxHandler, value: anytype) void {
+        const kind: Engine.MarkEvent.Kind = switch (value.action) {
+            .fresh_line_new_prompt => .prompt_start, // 'A'
+            .end_input_start_output => .command_start, // 'C'
+            .end_command => .command_end, // 'D'
+            else => return, // L/N/P/B/I: prompt furniture, not boundaries
+        };
+        const eng = self.engineOf();
+        const exit_code: ?u8 = if (kind == .command_end)
+            if (value.readOption(.exit_code)) |code|
+                @intCast(@as(u32, @bitCast(code)) & 0xff)
+            else
+                null
+        else
+            null;
+        eng.mark_events.append(eng.alloc, .{
+            .kind = kind,
+            .row = eng.historyRows() + eng.cursorPos().y,
+            .exit_code = exit_code,
+        }) catch {};
+    }
+};
+pub const MuxStream = vt.Stream(MuxHandler);
+```
+In `Engine`, add the field and the event type:
+```zig
+    /// OSC 133 mark events observed since the last clear. Drained by the
+    /// server after each feed, exactly like pty_out.
+    mark_events: std.ArrayList(MarkEvent),
+    pub const MarkEvent = struct {
+        pub const Kind = enum(u8) { prompt_start, command_start, command_end };
+        kind: Kind,
+        /// Absolute screen-space row (historyRows + cursor.y) at mark time.
+        row: u32,
+        /// Only ever set on command_end, and only when the mark carried one.
+        exit_code: ?u8,
+    };
+```
+In `init`, add `.mark_events = .empty,` to the struct literal, and replace the two stream lines with:
+```zig
+        self.stream = .initAlloc(alloc, .{ .inner = .{ .terminal = &self.term } });
+        self.stream.handler.inner.effects.write_pty = &onWritePty;
+```
+In `deinit`, add `self.mark_events.deinit(self.alloc);` alongside `pty_out`.
+Add the accessors next to `ptyOutput`/`clearPtyOutput`:
+```zig
+    pub fn markEvents(self: *const Engine) []const MarkEvent {
+        return self.mark_events.items;
+    }
+    pub fn clearMarkEvents(self: *Engine) void {
+        self.mark_events.clearRetainingCapacity();
+    }
+```
+Update `onWritePty` — the callback now receives the inner handler:
+```zig
+    fn onWritePty(handler: *vt.TerminalStream.Handler, data: [:0]const u8) void {
+        const mh: *MuxHandler = @fieldParentPtr("inner", handler);
+        const stream_ptr: *MuxStream = @fieldParentPtr("handler", mh);
+        // @alignCast for wasm32 — same reasoning as before this change.
+        const self: *Engine = @alignCast(@fieldParentPtr("stream", stream_ptr));
+        self.pty_out.appendSlice(self.alloc, data) catch {};
+    }
+```
+Compile notes for the executor: (a) `vt.StreamAction` is exported by the dep's `lib_vt.zig`; if `StreamAction.Tag`/`Value` names differ, mirror the stock handler's signature in `stream_terminal.zig` (`Action.Tag`, `Action.Value(action)`) via `vt.TerminalStream.Action`. (b) The exit code option is `i32`; shells send 0–255 and 128+signal, so the `& 0xff` clamp matches the existing `exit_status` frame's clamp. (c) The wasm build (`src/wasm_core.zig`) links the same engine module — run `$ZIG build` (not just test) to catch a wasm-side breakage; the reviewer's alignment note in `onWritePty` is exactly the wasm case.
+- [ ] **Step 4: Run tests and full build**
+Run: `$ZIG build test 2>&1 | tail -5 && $ZIG build 2>&1 | tail -3`
+Expected: both PASS (the second builds the wasm core too).
+- [ ] **Step 5: Commit**
+```bash
+git add src/engine.zig
+git commit -m "feat(engine): mux-owned stream handler surfaces OSC 133 marks as row-stamped events"
+```
+---
+### Task 4: `src/cmd.zig` — the pure command state machine
+**Files:**
+- Create: `src/cmd.zig`
+- Modify: `build.zig` (module + test wiring)
+- [ ] **Step 1: Write the file with failing tests.** Create `src/cmd.zig`:
+```zig
+//! The session's command state machine: MarkEvents in, transitions out.
+//! Pure — no I/O, no clock, no seq. The server stamps seqs and decides who
+//! hears about a transition; this module only decides what the marks mean.
+//! Trust rule (spec): a D only counts if it closes a seen C; stray marks
+//! reset to at_prompt rather than being believed.
+const std = @import("std");
+const proto = @import("protocol");
+const Engine = @import("engine").Engine;
+pub const Tracker = struct {
+    phase: proto.CmdPhase = .at_prompt,
+    /// Sticky: once any C has been seen, this session speaks marks and the
+    /// pgid fallback stops being consulted while a command is open.
+    marks_seen: bool = false,
+    start_row: u32 = 0,
+    end_row: u32 = 0,
+    exit_code: ?u8 = null,
+    pub const Transition = enum { running, returned, reset };
+    pub fn apply(self: *Tracker, ev: Engine.MarkEvent) ?Transition {
+        switch (ev.kind) {
+            .command_start => {
+                self.marks_seen = true;
+                self.phase = .running;
+                self.start_row = ev.row;
+                self.exit_code = null;
+                return .running;
+            },
+            .command_end => {
+                if (self.phase != .running) {
+                    // A D with no open C: a nested program echoing marks it
+                    // has no business emitting. Reset, believe nothing.
+                    self.phase = .at_prompt;
+                    return .reset;
+                }
+                self.phase = .returned;
+                self.end_row = ev.row;
+                self.exit_code = ev.exit_code;
+                return .returned;
+            },
+            .prompt_start => {
+                // 'A' after a return is the prompt redrawing: back to rest.
+                // 'A' mid-run (Ctrl-C redraw) also lands here — the shell
+                // is telling us the command is over even without a D.
+                if (self.phase == .running) {
+                    self.phase = .returned;
+                    self.end_row = ev.row;
+                    self.exit_code = null; // interrupted: no honest code
+                    return .returned;
+                }
+                self.phase = .at_prompt;
+                return null;
+            },
+        }
+    }
+    /// True while marks say a command is open — the window in which the
+    /// pgid fallback must NOT race the marks to a verdict.
+    pub fn marksOpen(self: *const Tracker) bool {
+        return self.marks_seen and self.phase == .running;
+    }
+};
+test "C then D is running then returned, with rows and code" {
+    var t = Tracker{};
+    try std.testing.expectEqual(@as(?Tracker.Transition, .running), t.apply(.{ .kind = .command_start, .row = 10, .exit_code = null }));
+    try std.testing.expectEqual(proto.CmdPhase.running, t.phase);
+    try std.testing.expectEqual(@as(?Tracker.Transition, .returned), t.apply(.{ .kind = .command_end, .row = 14, .exit_code = 1 }));
+    try std.testing.expectEqual(proto.CmdPhase.returned, t.phase);
+    try std.testing.expectEqual(@as(u32, 10), t.start_row);
+    try std.testing.expectEqual(@as(u32, 14), t.end_row);
+    try std.testing.expectEqual(@as(?u8, 1), t.exit_code);
+}
+test "a stray D resets and is not believed" {
+    var t = Tracker{};
+    try std.testing.expectEqual(@as(?Tracker.Transition, .reset), t.apply(.{ .kind = .command_end, .row = 3, .exit_code = 0 }));
+    try std.testing.expectEqual(proto.CmdPhase.at_prompt, t.phase);
+    try std.testing.expectEqual(@as(?u8, null), t.exit_code);
+}
+test "A closes an open command without a code (Ctrl-C at a prompt redraw)" {
+    var t = Tracker{};
+    _ = t.apply(.{ .kind = .command_start, .row = 5, .exit_code = null });
+    try std.testing.expectEqual(@as(?Tracker.Transition, .returned), t.apply(.{ .kind = .prompt_start, .row = 6, .exit_code = null }));
+    try std.testing.expectEqual(@as(?u8, null), t.exit_code);
+    try std.testing.expectEqual(proto.CmdPhase.returned, t.phase);
+    // The next A settles back to rest with no transition.
+    try std.testing.expectEqual(@as(?Tracker.Transition, null), t.apply(.{ .kind = .prompt_start, .row = 6, .exit_code = null }));
+    try std.testing.expectEqual(proto.CmdPhase.at_prompt, t.phase);
+}
+test "marksOpen guards the pgid race window" {
+    var t = Tracker{};
+    try std.testing.expect(!t.marksOpen());
+    _ = t.apply(.{ .kind = .command_start, .row = 0, .exit_code = null });
+    try std.testing.expect(t.marksOpen());
+    _ = t.apply(.{ .kind = .command_end, .row = 1, .exit_code = 0 });
+    try std.testing.expect(!t.marksOpen());
+    // Sticky across the next prompt: the session still speaks marks.
+    _ = t.apply(.{ .kind = .prompt_start, .row = 1, .exit_code = null });
+    try std.testing.expect(t.marks_seen);
+}
+test "back-to-back commands: second C reopens cleanly" {
+    var t = Tracker{};
+    _ = t.apply(.{ .kind = .command_start, .row = 0, .exit_code = null });
+    _ = t.apply(.{ .kind = .command_end, .row = 2, .exit_code = 0 });
+    try std.testing.expectEqual(@as(?Tracker.Transition, .running), t.apply(.{ .kind = .command_start, .row = 3, .exit_code = null }));
+    try std.testing.expectEqual(@as(u32, 3), t.start_row);
+    try std.testing.expectEqual(@as(?u8, null), t.exit_code);
+}
+```
+- [ ] **Step 2: Wire the module in `build.zig`.** Find where `delta_mod` is created (grep `delta_mod`) and mirror it: create `cmd_mod` from `src/cmd.zig` with imports `protocol` and `engine`; add `exe_mod.addImport("cmd", cmd_mod);` next to the server's other imports (the server module imports it in Task 5 — adding the import now is harmless); add a test step for it exactly where `delta` tests are registered (grep for the existing `addTest`/test-step pattern and copy it; ORDER: put the cmd test registration BEFORE the server/e2e tests per house doctrine — a wedged later test must not hide this one).
+- [ ] **Step 3: Run tests**
+Run: `$ZIG build test 2>&1 | tail -5`
+Expected: PASS, with the new cmd tests included.
+- [ ] **Step 4: Commit**
+```bash
+git add src/cmd.zig build.zig
+git commit -m "feat(cmd): pure command state machine over OSC 133 mark events"
+```
+---
+### Task 5: Server integration — drain events, stamp seq, push `cmd_state`, answer `status_req`
+**Files:**
+- Modify: `src/server.zig`
+The server's existing test harness (in-file tests around lines 2300–4400 drive `pumpOnce` with fake clients over socketpairs — read two of them first and copy their setup pattern exactly).
+- [ ] **Step 1: Write failing tests** in `src/server.zig`'s test section, using the harness pattern found there (a started `Server` on a temp sock path, a connected client fd that attaches, `srv.pumpOnce(0)` driven in a loop). The behaviors to pin:
+```zig
+// Test A: feeding marks through the pty produces a cmd_state push.
+// - write "\x1b]133;C\x07" then "\x1b]133;D;0\x07" into the pty slave side
+//   (the harness's existing way of making session output — grep for how
+//   existing tests inject pty bytes; several do it via the spawned shell,
+//   the cleanest is the harness that uses /bin/cat as the shell and writes
+//   through the master's slave pair).
+// - pump until the attached client's fd yields a frame of type .cmd_state
+//   with phase running, then one with phase returned and exit_code 0.
+// - assert the returned frame's seq is > the running frame's seq is NOT
+//   required (same feed can share a seq); assert returned.seq >= running.seq
+//   and returned.seq <= srv.tracker.seq (stamped after the post-feed update).
+// Test B: status_req round-trips on an attached client AND on an observer.
+// - client sends .status_req, reads .status_reply; decode; assert cols/rows
+//   match the attach size, alt_screen false, cmd.phase at_prompt initially.
+// - a fresh un-attached connection (observer) sends .status_req and gets a
+//   .status_reply via blocking writeFrame, same as stats_req does.
+```
+Write these as real Zig tests by copying the harness helpers the neighboring tests use (the executor has the file in front of them; the helpers already exist — do not invent new scaffolding).
+- [ ] **Step 2: Run to verify failure**
+Run: `$ZIG build test 2>&1 | tail -5`
+Expected: FAIL — no `.cmd_state` frame arrives / `.status_req` is ignored (falls into `else => {}`).
+- [ ] **Step 3: Implement.** In `src/server.zig`:
+Add imports/fields:
+```zig
+const cmdmod = @import("cmd");
+```
+In `Server` struct, next to `tracker`:
+```zig
+    /// The session's command state machine (OSC 133). Seq-stamped copies of
+    /// its transitions are what cmd_state/await_reply/status_reply carry.
+    cmd: cmdmod.Tracker = .{},
+    /// tracker.seq at the moment of the last `returned` transition —
+    /// "a return happened at or before this seq". Awaits compare their
+    /// since_seq against this.
+    returned_seq: u64 = 0,
+```
+In `pumpOnce`, immediately after the `self.sendUpdate();` line inside the pty-read arm, add:
+```zig
+                self.drainMarkEvents();
+```
+Add the method (near `sendUpdate`):
+```zig
+    /// Fold the engine's OSC 133 events into the command tracker and tell
+    /// attached clients about transitions. Runs after sendUpdate so
+    /// tracker.seq already covers the same pty chunk — the off-by-one the
+    /// spec pins (seq sampled post-feed).
+    fn drainMarkEvents(self: *Server) void {
+        for (self.eng.markEvents()) |ev| {
+            const tr = self.cmd.apply(ev) orelse continue;
+            if (tr == .returned) self.returned_seq = self.tracker.seq;
+            if (tr == .reset) continue; // believed nothing, tell no one
+            const payload = proto.encodeCmdState(self.cmdState(.marks));
+            for (0..max_clients) |i| {
+                _ = self.queueFrame(i, .cmd_state, &payload);
+            }
+        }
+        self.eng.clearMarkEvents();
+    }
+    /// The current command state as a wire struct. `mechanism` is the
+    /// caller's claim about how the verdict was reached: marks pushes say
+    /// .marks; await resolutions say what actually resolved them.
+    fn cmdState(self: *Server, mechanism: proto.Mechanism) proto.CmdState {
+        return .{
+            .phase = self.cmd.phase,
+            .mechanism = mechanism,
+            .exit_code = self.cmd.exit_code,
+            .start_row = self.cmd.start_row,
+            .end_row = self.cmd.end_row,
+            .seq = self.returned_seq,
+        };
+    }
+    fn buildStatusReply(self: *Server) proto.StatusReply {
+        const cur = self.eng.cursorPos();
+        return .{
+            .cols = self.colsNow(),
+            .rows = self.rowsNow(),
+            .cursor_x = cur.x,
+            .cursor_y = cur.y,
+            .history_rows = self.eng.historyRows(),
+            .alt_screen = self.eng.onAltScreen(),
+            .mode = self.readPtyMode() orelse .{ .icanon = true, .echo = true },
+            .cmd = self.cmdState(if (self.cmd.marks_seen) .marks else .pgid),
+        };
+    }
+```
+In `handleFrame`'s switch (attached clients), add before `else => {}`:
+```zig
+            .status_req => {
+                const payload = proto.encodeStatusReply(self.buildStatusReply());
+                _ = self.queueFrame(i, .status_reply, &payload);
+            },
+```
+In `serviceObserver`'s switch, add before `else => {}` (blocking reply, same rationale as the stats/endpoint observer arms):
+```zig
+            .status_req => {
+                const payload = proto.encodeStatusReply(self.buildStatusReply());
+                proto.writeFrame(fd, .status_reply, &payload) catch self.dropObserver(i);
+            },
+```
+- [ ] **Step 4: Run tests**
+Run: `$ZIG build test 2>&1 | tail -5`
+Expected: PASS.
+- [ ] **Step 5: Commit**
+```bash
+git add src/server.zig
+git commit -m "feat(server): command tracker integration — cmd_state pushes and status_req"
+```
+---
+### Task 6: Server awaits — `await_req` held open with marks/pgid/settle resolution
+**Files:**
+- Modify: `src/server.zig`
+- [ ] **Step 1: Write failing tests** (same harness pattern as Task 5):
+```zig
+// Test A (marks): client attaches, sends .await_req{since_seq = srv.tracker.seq,
+// settle_ms = 0, timeout_ms = 5000}. Pump. No reply yet. Feed
+// "\x1b]133;C\x07out\r\n\x1b]133;D;3\x07" through the pty. Pump until the
+// client reads .await_reply; decode; assert reason .returned, exit_code 3,
+// mechanism .marks.
+// Test B (immediate answer): after Test A's return, a second .await_req with
+// since_seq = 0 (older than returned_seq) is answered on the SAME pump —
+// the reconnect-idempotency contract.
+// Test C (settle): with a shell that emits no marks (/bin/cat harness),
+// send .await_req{since_seq = current, settle_ms = 200, timeout_ms = 5000};
+// write "quiet\r\n" into the pty; pump for ~600ms of wall time; assert
+// .await_reply arrives with reason .settled, mechanism .settle, null exit.
+// Test D (timeout): .await_req{settle_ms = 0, timeout_ms = 150} against a
+// silent session; pump ~500ms; assert reason .timeout.
+// Test E (pgid): /bin/sh harness without integration. Send input "sleep 1\n"
+// via .input, then .await_req{since_seq = current, settle_ms = 0,
+// timeout_ms = 10_000}. Pump; assert .await_reply reason .returned,
+// mechanism .pgid, exit_code null, within ~3s.
+```
+- [ ] **Step 2: Run to verify failure**
+Run: `$ZIG build test 2>&1 | tail -5`
+Expected: FAIL — await_req falls into `else => {}`, no reply ever comes (tests bound their pumping, so they fail rather than hang).
+- [ ] **Step 3: Implement.** In `ClientSlot`, add:
+```zig
+    /// An await_req held open. At most one per client: a second one
+    /// replaces the first (the client is a serial CLI; queueing two would
+    /// be inventing a use case).
+    await_state: ?AwaitState = null,
+```
+Add near `ClientSlot`:
+```zig
+const AwaitState = struct {
+    since_seq: u64,
+    settle_ms: u32,
+    timeout_ms: u32,
+    /// milliTimestamp at acceptance; timeout measures from here.
+    started_ms: i64,
+    /// pgid fallback edge detector: set once the fg pgid has been seen off
+    /// the shell, so "back on the shell" means returned, not never-left.
+    saw_busy: bool = false,
+};
+```
+In `Server`, add a field (next to `mode_sent`):
+```zig
+    /// milliTimestamp of the last byte the pty produced; the settle floor.
+    last_pty_ms: i64 = 0,
+```
+In `pumpOnce`, in the pty-read arm (where `n > 0`), add `self.last_pty_ms = std.time.milliTimestamp();` before `self.eng.feed(...)`. At the end of `pumpOnce`, just before `return null;`, add `self.checkAwaits();`.
+In `handleFrame`, add:
+```zig
+            .await_req => {
+                const req = proto.decodeAwaitReq(frame.payload) catch return;
+                if (self.clients[i] == null) return;
+                self.clients[i].?.await_state = .{
+                    .since_seq = req.since_seq,
+                    .settle_ms = req.settle_ms,
+                    .timeout_ms = req.timeout_ms,
+                    .started_ms = std.time.milliTimestamp(),
+                };
+                // A return that already happened answers immediately —
+                // this is what makes a reconnect re-issue safe.
+                self.checkAwaits();
+            },
+```
+Add the resolution method:
+```zig
+    /// Resolve any awaits that can be answered this pump. Granularity is
+    /// the run loop's 100ms tick — nothing here blocks, and no deadline
+    /// folding into poll is needed at that resolution.
+    fn checkAwaits(self: *Server) void {
+        const now = std.time.milliTimestamp();
+        for (0..max_clients) |i| {
+            if (self.clients[i] == null) continue;
+            const a = &(self.clients[i].?.await_state orelse continue);
+            // 1. Marks: a return newer than since_seq answers with the
+            //    full story. Strictly greater: since_seq is "what I have".
+            if (self.cmd.phase == .returned and self.returned_seq > a.since_seq) {
+                self.answerAwait(i, self.cmdState(.marks), .returned);
+                continue;
+            }
+            // 2. pgid: only when marks do not hold the floor. The shell is
+            //    the session leader, so its pid is the resting pgid.
+            if (!self.cmd.marksOpen()) {
+                if (self.pty.fgPgid()) |pg| {
+                    if (pg != self.pty.child) {
+                        a.saw_busy = true;
+                    } else if (a.saw_busy) {
+                        var st = self.cmdState(.pgid);
+                        st.phase = .returned;
+                        st.exit_code = null;
+                        st.seq = self.tracker.seq;
+                        self.answerAwait(i, st, .returned);
+                        continue;
+                    }
+                } else |_| {}
+            }
+            // 3. Settle: output silence, if the caller asked for a floor.
+            if (a.settle_ms > 0 and self.last_pty_ms > 0 and
+                now - self.last_pty_ms >= a.settle_ms and
+                now - a.started_ms >= a.settle_ms)
+            {
+                var st = self.cmdState(.settle);
+                st.exit_code = null;
+                st.seq = self.tracker.seq;
+                self.answerAwait(i, st, .settled);
+                continue;
+            }
+            // 4. Timeout: the bound the client set on the whole wait.
+            if (a.timeout_ms > 0 and now - a.started_ms >= a.timeout_ms) {
+                var st = self.cmdState(if (self.cmd.marks_seen) .marks else .pgid);
+                st.seq = self.tracker.seq;
+                self.answerAwait(i, st, .timeout);
+            }
+        }
+    }
+    fn answerAwait(self: *Server, i: usize, st: proto.CmdState, reason: proto.AwaitReason) void {
+        if (self.clients[i] == null) return;
+        self.clients[i].?.await_state = null;
+        const payload = proto.encodeAwaitReply(st, reason);
+        _ = self.queueFrame(i, .await_reply, &payload);
+    }
+```
+Note on the optional-pointer idiom in `checkAwaits`: `&(x orelse continue)` does not produce a pointer into the optional in Zig — write it as:
+```zig
+            const slot = &self.clients[i].?;
+            if (slot.await_state == null) continue;
+            const a = &slot.await_state.?;
+```
+- [ ] **Step 4: Run tests**
+Run: `$ZIG build test 2>&1 | tail -5`
+Expected: PASS. The settle/pgid tests take a few wall-clock seconds; that is the test, not a hang — but keep each bounded under 15s.
+- [ ] **Step 5: Commit**
+```bash
+git add src/server.zig
+git commit -m "feat(server): server-side awaits — marks first, pgid edge, settle floor, timeout bound"
+```
+---
+### Task 7: Shell integration — scripts, shims, spawn-time injection
+**Files:**
+- Create: `src/shellint.zig`
+- Modify: `src/pty.zig` (child env pairs), `src/server.zig` (Options + spawn), `src/main.zig` (opt-out wiring)
+- Modify: `build.zig` (module + tests)
+- [ ] **Step 1: Create `src/shellint.zig` with its tests.** The scripts are marks-only — the OSC 133 subset mux consumes, derived from ghostty's shell-integration approach (guarded D so a bare first prompt emits no code, BASH_COMMAND guard so the DEBUG trap skips the prompt hook itself):
+```zig
+//! Shell integration: OSC 133 marks injected at spawn. muxd forks the
+//! session shell itself, so injection is env + argv at spawn time — no
+//! rc-file edits, ever. Detection is by shell basename; unknown shells get
+//! nothing and the session runs on the pgid/settle fallbacks.
+const std = @import("std");
+pub const zsh_zshrc =
+    \\# mux shell integration (zsh): OSC 133 marks. Sourced via a ZDOTDIR
+    \\# shim; restores the user's ZDOTDIR (or unsets it) then runs their rc.
+    \\if [[ -n "$MUX_ORIG_ZDOTDIR" ]]; then
+    \\  export ZDOTDIR="$MUX_ORIG_ZDOTDIR"
+    \\  unset MUX_ORIG_ZDOTDIR
+    \\else
+    \\  unset ZDOTDIR
+    \\fi
+    \\[[ -f "${ZDOTDIR:-$HOME}/.zshrc" ]] && source "${ZDOTDIR:-$HOME}/.zshrc"
+    \\autoload -Uz add-zsh-hook
+    \\_mux_preexec() { _mux_ran=1; printf '\e]133;C\a'; }
+    \\_mux_precmd() {
+    \\  local code=$?
+    \\  [[ -n "$_mux_ran" ]] && printf '\e]133;D;%s\a' "$code"
+    \\  _mux_ran=""
+    \\  printf '\e]133;A\a'
+    \\}
+    \\add-zsh-hook preexec _mux_preexec
+    \\add-zsh-hook precmd _mux_precmd
+    \\
+;
+pub const bash_init =
+    \\# mux shell integration (bash): OSC 133 marks. Passed via --init-file;
+    \\# sources the user's normal rc first so their config still runs.
+    \\[[ -f "$HOME/.bashrc" ]] && source "$HOME/.bashrc"
+    \\_mux_ran=""
+    \\_mux_preexec() {
+    \\  [[ -n "$COMP_LINE" ]] && return
+    \\  [[ "$BASH_COMMAND" == _mux_precmd* ]] && return
+    \\  _mux_ran=1
+    \\  printf '\e]133;C\a'
+    \\}
+    \\_mux_precmd() {
+    \\  local code=$?
+    \\  [[ -n "$_mux_ran" ]] && printf '\e]133;D;%s\a' "$code"
+    \\  _mux_ran=""
+    \\  printf '\e]133;A\a'
+    \\}
+    \\trap '_mux_preexec' DEBUG
+    \\PROMPT_COMMAND="_mux_precmd${PROMPT_COMMAND:+;$PROMPT_COMMAND}"
+    \\
+;
+pub const fish_conf =
+    \\# mux shell integration (fish): OSC 133 marks, via vendor_conf.d.
+    \\function _mux_preexec --on-event fish_preexec
+    \\    printf '\e]133;C\a'
+    \\end
+    \\function _mux_postexec --on-event fish_postexec
+    \\    printf '\e]133;D;%s\a' $status
+    \\end
+    \\function _mux_prompt --on-event fish_prompt
+    \\    printf '\e]133;A\a'
+    \\end
+    \\
+;
+pub const Kind = enum { zsh, bash, fish, other };
+pub fn detect(shell_path: []const u8) Kind {
+    const base = std.fs.path.basename(shell_path);
+    if (std.mem.eql(u8, base, "zsh")) return .zsh;
+    if (std.mem.eql(u8, base, "bash")) return .bash;
+    if (std.mem.eql(u8, base, "fish")) return .fish;
+    return .other;
+}
+pub const EnvPair = struct { key: [:0]const u8, value: [:0]const u8 };
+/// Everything the spawn needs: the argv to exec and env pairs to set in
+/// the child. `dir` must outlive the spawn (paths point into it).
+pub const Injection = struct {
+    /// Extra argv AFTER the shell path (bash --init-file <shim>); empty
+    /// for env-only injections (zsh, fish) and for .other.
+    extra_argv: []const [:0]const u8,
+    env: []const EnvPair,
+};
+/// Prepare shim files under `dir` (created private, 0700) for `shell_path`
+/// and return what spawn must add. All returned slices are allocated from
+/// `arena` — hand it an arena that lives as long as the daemon.
+pub fn prepare(
+    arena: std.mem.Allocator,
+    dir: []const u8,
+    shell_path: []const u8,
+) !Injection {
+    switch (detect(shell_path)) {
+        .zsh => {
+            try std.fs.cwd().makePath(dir);
+            const rc_path = try std.fs.path.join(arena, &.{ dir, ".zshrc" });
+            try writeFilePrivate(rc_path, zsh_zshrc);
+            var env: std.ArrayList(EnvPair) = .empty;
+            const dir_z = try arena.dupeZ(u8, dir);
+            try env.append(arena, .{ .key = "ZDOTDIR", .value = dir_z });
+            // Only when the daemon itself carried one: exporting an empty
+            // ZDOTDIR would break zsh's fallback to $HOME (spec footnote).
+            if (std.posix.getenv("ZDOTDIR")) |orig| {
+                try env.append(arena, .{
+                    .key = "MUX_ORIG_ZDOTDIR",
+                    .value = try arena.dupeZ(u8, orig),
+                });
+            }
+            return .{ .extra_argv = &.{}, .env = try env.toOwnedSlice(arena) };
+        },
+        .bash => {
+            try std.fs.cwd().makePath(dir);
+            const init_path = try std.fs.path.join(arena, &.{ dir, "bash-init.sh" });
+            try writeFilePrivate(init_path, bash_init);
+            const init_z = try arena.dupeZ(u8, init_path);
+            const argv = try arena.alloc([:0]const u8, 2);
+            argv[0] = "--init-file";
+            argv[1] = init_z;
+            return .{ .extra_argv = argv, .env = &.{} };
+        },
+        .fish => {
+            const vendor = try std.fs.path.join(arena, &.{ dir, "fish", "vendor_conf.d" });
+            try std.fs.cwd().makePath(vendor);
+            const conf_path = try std.fs.path.join(arena, &.{ vendor, "mux.fish" });
+            try writeFilePrivate(conf_path, fish_conf);
+            const orig = std.posix.getenv("XDG_DATA_DIRS") orelse "/usr/local/share:/usr/share";
+            const merged = try std.fmt.allocPrintSentinel(arena, "{s}:{s}", .{ dir, orig }, 0);
+            return .{
+                .extra_argv = &.{},
+                .env = &.{.{ .key = "XDG_DATA_DIRS", .value = merged }},
+            };
+        },
+        .other => return .{ .extra_argv = &.{}, .env = &.{} },
+    }
+}
+fn writeFilePrivate(path: []const u8, contents: []const u8) !void {
+    const f = try std.fs.cwd().createFile(path, .{ .mode = 0o600 });
+    defer f.close();
+    try f.writeAll(contents);
+}
+test "detect goes by basename" {
+    try std.testing.expectEqual(Kind.zsh, detect("/usr/bin/zsh"));
+    try std.testing.expectEqual(Kind.bash, detect("/bin/bash"));
+    try std.testing.expectEqual(Kind.fish, detect("/opt/homebrew/bin/fish"));
+    try std.testing.expectEqual(Kind.other, detect("/bin/sh"));
+    try std.testing.expectEqual(Kind.other, detect("/usr/bin/nu"));
+}
+test "prepare zsh writes the shim and sets ZDOTDIR" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dir = try tmp.dir.realpathAlloc(arena, ".");
+    const inj = try prepare(arena, dir, "/usr/bin/zsh");
+    try std.testing.expectEqual(@as(usize, 0), inj.extra_argv.len);
+    try std.testing.expect(inj.env.len >= 1);
+    try std.testing.expectEqualStrings("ZDOTDIR", inj.env[0].key);
+    const rc = try tmp.dir.readFileAlloc(arena, ".zshrc", 64 * 1024);
+    try std.testing.expect(std.mem.indexOf(u8, rc, "133;D;%s") != null);
+    try std.testing.expect(std.mem.indexOf(u8, rc, "add-zsh-hook") != null);
+}
+test "prepare bash returns --init-file argv" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dir = try tmp.dir.realpathAlloc(arena, ".");
+    const inj = try prepare(arena, dir, "/bin/bash");
+    try std.testing.expectEqual(@as(usize, 2), inj.extra_argv.len);
+    try std.testing.expectEqualStrings("--init-file", inj.extra_argv[0]);
+    const script = try std.fs.cwd().readFileAlloc(arena, inj.extra_argv[1], 64 * 1024);
+    try std.testing.expect(std.mem.indexOf(u8, script, "PROMPT_COMMAND") != null);
+    try std.testing.expect(std.mem.indexOf(u8, script, "trap '_mux_preexec' DEBUG") != null);
+}
+test "prepare other injects nothing" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+    const inj = try prepare(arena, "/nonexistent-never-created", "/bin/sh");
+    try std.testing.expectEqual(@as(usize, 0), inj.extra_argv.len);
+    try std.testing.expectEqual(@as(usize, 0), inj.env.len);
+}
+```
+(API check for the executor: `allocPrintSentinel` is the 0.15 name for sentinel-terminated allocPrint; if absent, use `std.fmt.allocPrintZ`. `readFileAlloc` argument order changed across 0.15 — follow whatever `src/xdg.zig` or neighboring code uses.)
+- [ ] **Step 2: Extend `Pty` for env pairs.** In `src/pty.zig`, add to `SpawnArgvOptions`:
+```zig
+        /// Set in the child between fork and exec, after TERM. Injection's
+        /// door: the daemon's env is the only source of a child's env.
+        env: []const struct { key: [:0]const u8, value: [:0]const u8 } = &.{},
+```
+and in the child block, right after the TERM `setenv`:
+```zig
+            for (opts.env) |kv| _ = c.setenv(kv.key.ptr, kv.value.ptr, 1);
+```
+Add a test pinning it:
+```zig
+test "Pty: spawnArgv env pairs reach the child" {
+    var argv = [_:null]?[*:0]const u8{ "/bin/sh", "-c", "printf 'env-%s' \"$MUX_T\"" };
+    var pty = try Pty.spawnArgv(.{
+        .cols = 80,
+        .rows = 24,
+        .argv = &argv,
+        .env = &.{.{ .key = "MUX_T", .value = "ok" }},
+    });
+    defer pty.deinit();
+    var out = try readUntil(std.testing.allocator, &pty, "env-ok", 5000);
+    defer out.deinit(std.testing.allocator);
+    try std.testing.expect(std.mem.indexOf(u8, out.items, "env-ok") != null);
+}
+```
+- [ ] **Step 3: Wire into the daemon.** In `src/server.zig`:
+- `Server.Options` gains `shell_integration: bool = true`.
+- In `Server.init`, replace the plain `Pty.spawn` with: when `opts.shell_integration`, build the shim dir path `{dirname(sock_path)}/mux-shellint-{pid}` (the sock dir is already private, runtime-appropriate, and per-user; pid keeps two daemons apart), call `shellint.prepare` with an arena owned by the Server (add a `shellint_arena: std.heap.ArenaAllocator` field, deinit'd in `deinit`, plus a `shellint_dir: ?[]const u8` field so `deinit` can `std.fs.cwd().deleteTree` it best-effort), assemble argv `[shell] ++ extra_argv` as `[*:null]` and call `Pty.spawnArgv` with the env pairs. `.other` injections are empty — the call is then equivalent to today's spawn.
+- In `src/main.zig`'s `run` path, thread the option: `shell_integration` is true unless the daemon's env says `MUX_SHELL_INTEGRATION=0` (`std.posix.getenv`) — the spec is explicit that the opt-out is read from the daemon's env.
+- `build.zig`: create `shellint_mod`, import into `server` deps and `exe_mod`; register its tests BEFORE server tests.
+- [ ] **Step 4: End-to-end injection test** (in `src/server.zig` tests, guarded): spawn a real Server with `shell = "/bin/bash"` (skip with `error.SkipZigTest` if `/bin/bash` is absent), attach a fake client, write `"true\n"` via `.input`, pump, and assert a `.cmd_state` frame with phase `.returned` and exit_code 0 arrives within 10s of pumping. This proves marks flow end-to-end: injection → bash → pty → engine → tracker → wire. Repeat for zsh if `/usr/bin/zsh` exists (skip otherwise).
+- [ ] **Step 5: Run tests**
+Run: `$ZIG build test 2>&1 | tail -5`
+Expected: PASS (bash test live on this box; zsh/fish arms skip where absent).
+- [ ] **Step 6: Commit**
+```bash
+git add src/shellint.zig src/pty.zig src/server.zig src/main.zig build.zig
+git commit -m "feat(shellint): OSC 133 marks injected at spawn — ZDOTDIR shim, --init-file, vendor_conf.d"
+```
+---
+### Task 8: `muxa` skeleton — arg parsing, unix transport, `status` and `capture`
+**Files:**
+- Create: `src/muxa.zig`
+- Modify: `build.zig`
+- [ ] **Step 1: Create `src/muxa.zig`.** Structure (complete file; JSON is hand-escaped — no std.json dependency to fight 0.15 API drift over):
+```zig
+//! muxa: the agent-facing mux client. Every verb prints one JSON object on
+//! stdout and exits 0 on success; failures print {"error": "..."} and exit
+//! nonzero. Attaches at 0x0 always — an agent must never claim the grid
+//! out from under the human's size (load-bearing spec rule).
+const std = @import("std");
+const proto = @import("protocol");
+const usage =
+    \\usage: muxa <verb> [--sock PATH] [--settle MS] [--timeout MS] [--vt] [args]
+    \\verbs:
+    \\  status              session snapshot as JSON
+    \\  capture             current grid as text (--vt for styled)
+    \\  send BYTES          raw bytes to the pty (C-style escapes: \n \r \t \e \xNN)
+    \\  run CMDLINE         send CMDLINE + newline, await return, report exit/output
+    \\  await               wait for the current/next command to return
+    \\
+;
+const Opts = struct {
+    verb: enum { status, capture, send, run, @"await" },
+    sock: ?[]const u8 = null,
+    settle_ms: u32 = 0,
+    timeout_ms: u32 = 30_000,
+    vt: bool = false,
+    arg: ?[]const u8 = null,
+};
+fn parseArgs(args: []const [:0]const u8) ?Opts {
+    if (args.len < 2) return null;
+    const verb = std.meta.stringToEnum(@FieldType(Opts, "verb"), args[1]) orelse return null;
+    var o: Opts = .{ .verb = verb };
+    var i: usize = 2;
+    while (i < args.len) : (i += 1) {
+        const a = args[i];
+        if (std.mem.eql(u8, a, "--sock")) {
+            i += 1;
+            if (i >= args.len) return null;
+            o.sock = args[i];
+        } else if (std.mem.eql(u8, a, "--settle")) {
+            i += 1;
+            if (i >= args.len) return null;
+            o.settle_ms = std.fmt.parseInt(u32, args[i], 10) catch return null;
+        } else if (std.mem.eql(u8, a, "--timeout")) {
+            i += 1;
+            if (i >= args.len) return null;
+            o.timeout_ms = std.fmt.parseInt(u32, args[i], 10) catch return null;
+        } else if (std.mem.eql(u8, a, "--vt")) {
+            o.vt = true;
+        } else if (o.arg == null and a.len > 0 and a[0] != '-') {
+            o.arg = a;
+        } else return null;
+    }
+    return o;
+}
+/// JSON string escape, the six mandatory escapes + control bytes as \u00XX.
+fn jsonEscape(writer: anytype, s: []const u8) !void {
+    try writer.writeByte('"');
+    for (s) |b| switch (b) {
+        '"' => try writer.writeAll("\\\""),
+        '\\' => try writer.writeAll("\\\\"),
+        '\n' => try writer.writeAll("\\n"),
+        '\r' => try writer.writeAll("\\r"),
+        '\t' => try writer.writeAll("\\t"),
+x00...0x08, 0x0b, 0x0c, 0x0e...0x1f => try writer.print("\\u{x:0>4}", .{b}),
+        else => try writer.writeByte(b),
+    };
+    try writer.writeByte('"');
+}
+test "jsonEscape pins the escapes" {
+    var buf: [128]u8 = undefined;
+    var fbs = std.io.fixedBufferStream(&buf);
+    try jsonEscape(fbs.writer(), "a\"b\\c\nd\x1be");
+    try std.testing.expectEqualStrings("\"a\\\"b\\\\c\\nd\\u001be\"", fbs.getWritten());
+}
+/// Decode C-style escapes for `send`. Caller frees.
+fn decodeEscapes(alloc: std.mem.Allocator, s: []const u8) ![]u8 {
+    var out: std.ArrayList(u8) = .empty;
+    errdefer out.deinit(alloc);
+    var i: usize = 0;
+    while (i < s.len) : (i += 1) {
+        if (s[i] != '\\' or i + 1 >= s.len) {
+            try out.append(alloc, s[i]);
+            continue;
+        }
+        i += 1;
+        switch (s[i]) {
+            'n' => try out.append(alloc, '\n'),
+            'r' => try out.append(alloc, '\r'),
+            't' => try out.append(alloc, '\t'),
+            'e' => try out.append(alloc, 0x1b),
+            '\\' => try out.append(alloc, '\\'),
+            'x' => {
+                if (i + 2 >= s.len) return error.BadEscape;
+                try out.append(alloc, try std.fmt.parseInt(u8, s[i + 1 .. i + 3], 16));
+                i += 2;
+            },
+            else => return error.BadEscape,
+        }
+    }
+    return out.toOwnedSlice(alloc);
+}
+test "decodeEscapes covers the sequences send needs" {
+    const alloc = std.testing.allocator;
+    const got = try decodeEscapes(alloc, "q\\n\\e[A\\x03");
+    defer alloc.free(got);
+    try std.testing.expectEqualSlices(u8, "q\n\x1b[A\x03", got);
+    try std.testing.expectError(error.BadEscape, decodeEscapes(alloc, "\\q"));
+}
+test "parseArgs verbs and flags" {
+    const a1 = [_][:0]const u8{ "muxa", "status" };
+    try std.testing.expectEqual(@FieldType(Opts, "verb").status, parseArgs(&a1).?.verb);
+    const a2 = [_][:0]const u8{ "muxa", "run", "--timeout", "5000", "make test" };
+    const o2 = parseArgs(&a2).?;
+    try std.testing.expectEqual(@as(u32, 5000), o2.timeout_ms);
+    try std.testing.expectEqualStrings("make test", o2.arg.?);
+    const a3 = [_][:0]const u8{ "muxa", "bogus" };
+    try std.testing.expectEqual(@as(?Opts, null), parseArgs(&a3));
+}
+```
+Then the connection + main. Unix transport first (QUIC is Task 10):
+```zig
+const Conn = struct {
+    fd: std.posix.fd_t,
+    fn open(sock_path: []const u8) !Conn {
+        const addr = try std.net.Address.initUnix(sock_path);
+        const s = try std.net.connectUnixSocket(sock_path);
+        _ = addr;
+        return .{ .fd = s.handle };
+    }
+    fn close(self: *Conn) void {
+        std.posix.close(self.fd);
+    }
+    fn sendFrame(self: *Conn, t: proto.MsgType, payload: []const u8) !void {
+        try proto.writeFrame(self.fd, t, payload);
+    }
+    /// Read frames until one of type `want` arrives (snapshots, deltas and
+    /// pushes stream past an attached client; skip what we did not ask
+    /// for). Bounded by `deadline_ms` wall time via poll.
+    fn awaitFrame(
+        self: *Conn,
+        alloc: std.mem.Allocator,
+        want: proto.MsgType,
+        deadline_ms: i64,
+    ) !proto.Frame {
+        while (true) {
+            const now = std.time.milliTimestamp();
+            if (now >= deadline_ms) return error.Timeout;
+            var fds = [_]std.posix.pollfd{
+                .{ .fd = self.fd, .events = std.posix.POLL.IN, .revents = 0 },
+            };
+            const n = try std.posix.poll(&fds, @intCast(@min(deadline_ms - now, 250)));
+            if (n == 0) continue;
+            const frame = try proto.readFrame(alloc, self.fd) orelse return error.DaemonGone;
+            if (frame.type == want) return frame;
+            frame.deinit(alloc);
+        }
+    }
+};
+fn fail(msg: []const u8, detail: []const u8) u8 {
+    const err = std.fs.File.stderr();
+    _ = err;
+    var buf: [512]u8 = undefined;
+    var fbs = std.io.fixedBufferStream(&buf);
+    const w = fbs.writer();
+    w.writeAll("{\"error\":") catch {};
+    jsonEscape(w, msg) catch {};
+    if (detail.len > 0) {
+        w.writeAll(",\"detail\":") catch {};
+        jsonEscape(w, detail) catch {};
+    }
+    w.writeAll("}\n") catch {};
+    std.fs.File.stdout().writeAll(fbs.getWritten()) catch {};
+    return 1;
+}
+pub fn main() !u8 {
+    var arena_state = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+    defer arena_state.deinit();
+    const alloc = arena_state.allocator();
+    const args = try std.process.argsAlloc(alloc);
+    const o = parseArgs(args) orelse {
+        std.fs.File.stderr().writeAll(usage) catch {};
+        return 2;
+    };
+    const sock_path = o.sock orelse blk: {
+        if (std.posix.getenv("XDG_RUNTIME_DIR")) |dir|
+            break :blk try std.fmt.allocPrint(alloc, "{s}/muxd.sock", .{dir});
+        break :blk try std.fmt.allocPrint(alloc, "/tmp/muxd-{d}.sock", .{std.os.linux.getuid()});
+    };
+    var conn = Conn.open(sock_path) catch
+        return fail("cannot connect", sock_path);
+    defer conn.close();
+    const deadline = std.time.milliTimestamp() + o.timeout_ms;
+    return switch (o.verb) {
+        .status => verbStatus(alloc, &conn, deadline),
+        .capture => verbCapture(alloc, &conn, o.vt, deadline),
+        .send => verbSend(alloc, &conn, o.arg orelse return fail("send needs BYTES", "")),
+        .run => verbRun(alloc, &conn, o, deadline),
+        .@"await" => verbAwait(alloc, &conn, o, deadline),
+    };
+}
+fn verbStatus(alloc: std.mem.Allocator, conn: *Conn, deadline: i64) u8 {
+    conn.sendFrame(.status_req, "") catch return fail("send failed", "");
+    const frame = conn.awaitFrame(alloc, .status_reply, deadline) catch
+        return fail("no reply — daemon too old or hung", "");
+    defer frame.deinit(alloc);
+    const s = proto.decodeStatusReply(frame.payload) catch return fail("bad status_reply", "");
+    printStatus(s) catch return 1;
+    return 0;
+}
+fn printStatus(s: proto.StatusReply) !void {
+    var buf: [512]u8 = undefined;
+    var fbs = std.io.fixedBufferStream(&buf);
+    const w = fbs.writer();
+    try w.print(
+        "{{\"cols\":{d},\"rows\":{d},\"cursor_x\":{d},\"cursor_y\":{d}," ++
+            "\"history_rows\":{d},\"alt_screen\":{},\"icanon\":{},\"echo\":{}," ++
+            "\"cmd\":{{\"phase\":\"{s}\",\"mechanism\":\"{s}\",\"exit_code\":",
+        .{
+            s.cols,              s.rows,          s.cursor_x,
+            s.cursor_y,          s.history_rows,  s.alt_screen,
+            s.mode.icanon,       s.mode.echo,
+            @tagName(s.cmd.phase), @tagName(s.cmd.mechanism),
+        },
+    );
+    if (s.cmd.exit_code) |c| try w.print("{d}", .{c}) else try w.writeAll("null");
+    try w.print(
+        ",\"start_row\":{d},\"end_row\":{d},\"seq\":{d}}}}}\n",
+        .{ s.cmd.start_row, s.cmd.end_row, s.cmd.seq },
+    );
+    try std.fs.File.stdout().writeAll(fbs.getWritten());
+}
+fn verbCapture(alloc: std.mem.Allocator, conn: *Conn, vt: bool, deadline: i64) u8 {
+    conn.sendFrame(.debug_dump, &.{@intFromBool(vt)}) catch return fail("send failed", "");
+    const frame = conn.awaitFrame(alloc, .dump_reply, deadline) catch
+        return fail("no reply — daemon too old or hung", "");
+    defer frame.deinit(alloc);
+    var out: std.ArrayList(u8) = .empty;
+    defer out.deinit(alloc);
+    const w = out.writer(alloc);
+    w.writeAll("{\"grid\":") catch return 1;
+    jsonEscape(w, frame.payload) catch return 1;
+    w.writeAll("}\n") catch return 1;
+    std.fs.File.stdout().writeAll(out.items) catch return 1;
+    return 0;
+}
+fn attachZero(conn: *Conn) !void {
+    // cols=rows=0: applySize refuses <2, the slot stays 0x0, claimGrid
+    // reads that as "makes no claim" — the human's grid never moves.
+    try conn.sendFrame(.attach, &proto.encodeAttach(0, 0, 0, 0));
+}
+fn verbSend(alloc: std.mem.Allocator, conn: *Conn, arg: []const u8) u8 {
+    const bytes = decodeEscapes(alloc, arg) catch return fail("bad escape in BYTES", arg);
+    defer alloc.free(bytes);
+    attachZero(conn) catch return fail("attach failed", "");
+    conn.sendFrame(.input, bytes) catch return fail("send failed", "");
+    conn.sendFrame(.detach, "") catch {};
+    std.fs.File.stdout().writeAll("{\"sent\":true}\n") catch return 1;
+    return 0;
+}
+```
+`verbRun`/`verbAwait` are Task 9 — for this task, stub them honestly:
+```zig
+fn verbRun(alloc: std.mem.Allocator, conn: *Conn, o: Opts, deadline: i64) u8 {
+    _ = alloc;
+    _ = conn;
+    _ = o;
+    _ = deadline;
+    return fail("run: not implemented yet", "");
+}
+fn verbAwait(alloc: std.mem.Allocator, conn: *Conn, o: Opts, deadline: i64) u8 {
+    _ = alloc;
+    _ = conn;
+    _ = o;
+    _ = deadline;
+    return fail("await: not implemented yet", "");
+}
+```
+(0.15 I/O note for the executor: `std.fs.File.stdout()` / `.stderr()` and `std.io.fixedBufferStream` — follow whatever `src/main.zig` uses for its printing if these names differ; the repo compiles against 0.15.2, so its own idiom is the API truth.)
+- [ ] **Step 2: Wire the binary in `build.zig`** next to `mux_exe`: `muxa_mod` (root `src/muxa.zig`, imports `protocol`), `b.addExecutable(.{ .name = "muxa", .root_module = muxa_mod })`, `use_llvm`/`use_lld` true, `b.installArtifact`. Register `muxa_mod` tests before the e2e tests.
+- [ ] **Step 3: Run unit tests, then a live smoke.**
+Run: `$ZIG build test 2>&1 | tail -5` — expected PASS.
+Live smoke:
+```bash
+$ZIG build
+SOCK=/tmp/muxa-smoke-$$.sock
+./zig-out/bin/muxd start --sock $SOCK
+sleep 0.5
+./zig-out/bin/muxa status --sock $SOCK
+./zig-out/bin/muxa capture --sock $SOCK
+./zig-out/bin/muxa send 'echo hi\n' --sock $SOCK
+sleep 0.5
+./zig-out/bin/muxa capture --sock $SOCK   # grid JSON must contain "hi"
+./zig-out/bin/muxd stop --sock $SOCK
+```
+Expected: valid single-line JSON from each verb; the second capture contains `hi`.
+- [ ] **Step 4: Commit**
+```bash
+git add src/muxa.zig build.zig
+git commit -m "feat(muxa): agent client skeleton — status, capture, send over the unix socket"
+```
+---
+### Task 9: `muxa run` and `muxa await`
+**Files:**
+- Modify: `src/muxa.zig`
+- [ ] **Step 1: Implement `verbAwait` and `verbRun`** (replace the stubs):
+```zig
+fn doAwait(
+    alloc: std.mem.Allocator,
+    conn: *Conn,
+    o: Opts,
+    since_seq: u64,
+    deadline: i64,
+) !proto.AwaitReply {
+    try conn.sendFrame(.await_req, &proto.encodeAwaitReq(.{
+        .since_seq = since_seq,
+        .settle_ms = o.settle_ms,
+        .timeout_ms = o.timeout_ms,
+    }));
+    const frame = try conn.awaitFrame(alloc, .await_reply, deadline);
+    defer frame.deinit(alloc);
+    return try proto.decodeAwaitReply(frame.payload);
+}
+fn currentSeq(alloc: std.mem.Allocator, conn: *Conn, deadline: i64) !u64 {
+    try conn.sendFrame(.status_req, "");
+    const frame = try conn.awaitFrame(alloc, .status_reply, deadline);
+    defer frame.deinit(alloc);
+    const s = try proto.decodeStatusReply(frame.payload);
+    return s.cmd.seq;
+}
+fn printAwaitReply(r: proto.AwaitReply, output: ?[]const u8, duration_ms: i64) !void {
+    var out: std.ArrayList(u8) = .empty;
+    var alloc_state = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+    defer alloc_state.deinit();
+    const alloc = alloc_state.allocator();
+    defer out.deinit(alloc);
+    const w = out.writer(alloc);
+    try w.print(
+        "{{\"reason\":\"{s}\",\"phase\":\"{s}\",\"mechanism\":\"{s}\",\"exit_code\":",
+        .{ @tagName(r.reason), @tagName(r.state.phase), @tagName(r.state.mechanism) },
+    );
+    if (r.state.exit_code) |c| try w.print("{d}", .{c}) else try w.writeAll("null");
+    try w.print(
+        ",\"start_row\":{d},\"end_row\":{d},\"duration_ms\":{d}",
+        .{ r.state.start_row, r.state.end_row, duration_ms },
+    );
+    if (output) |text| {
+        try w.writeAll(",\"output\":");
+        try jsonEscape(w, text);
+    }
+    try w.writeAll("}\n");
+    try std.fs.File.stdout().writeAll(out.items);
+}
+fn verbAwait(alloc: std.mem.Allocator, conn: *Conn, o: Opts, deadline: i64) u8 {
+    attachZero(conn) catch return fail("attach failed", "");
+    const started = std.time.milliTimestamp();
+    const since = currentSeq(alloc, conn, deadline) catch
+        return fail("no reply — daemon too old or hung", "");
+    const r = doAwait(alloc, conn, o, since, deadline) catch
+        return fail("no reply — daemon too old or hung", "");
+    printAwaitReply(r, null, std.time.milliTimestamp() - started) catch return 1;
+    return if (r.reason == .timeout) 3 else 0;
+}
+/// Fetch the output span [start_row, end_row) as plain rows. Only valid in
+/// the marks regime; other mechanisms have no honest span (spec).
+fn fetchSpan(
+    alloc: std.mem.Allocator,
+    conn: *Conn,
+    start_row: u32,
+    end_row: u32,
+    deadline: i64,
+) ![]const u8 {
+    if (end_row <= start_row) return "";
+    const count: u16 = @intCast(@min(end_row - start_row, std.math.maxInt(u16)));
+    try conn.sendFrame(.fetch_scrollback, &proto.encodeScrollbackReq(start_row, count));
+    const frame = try conn.awaitFrame(alloc, .scrollback_chunk, deadline);
+    defer frame.deinit(alloc);
+    if (frame.payload.len < 6) return error.BadPayload;
+    // Styled rows follow the 6-byte echo of the request; strip SGR down to
+    // text so the agent gets what a human read, not escape soup.
+    return stripSgr(alloc, frame.payload[6..]);
+}
+/// Remove ESC-[...m/ESC-]...BEL/ESC-\ sequences, keep text and newlines.
+fn stripSgr(alloc: std.mem.Allocator, styled: []const u8) ![]const u8 {
+    var out: std.ArrayList(u8) = .empty;
+    errdefer out.deinit(alloc);
+    var i: usize = 0;
+    while (i < styled.len) {
+        const b = styled[i];
+        if (b == 0x1b and i + 1 < styled.len) {
+            const kind = styled[i + 1];
+            if (kind == '[') {
+                i += 2;
+                while (i < styled.len and !isCsiFinal(styled[i])) i += 1;
+                i += 1; // the final byte
+                continue;
+            } else if (kind == ']') {
+                i += 2;
+                while (i < styled.len and styled[i] != 0x07) : (i += 1) {
+                    if (styled[i] == 0x1b and i + 1 < styled.len and styled[i + 1] == '\\') {
+                        i += 1;
+                        break;
+                    }
+                }
+                i += 1;
+                continue;
+            }
+            i += 2;
+            continue;
+        }
+        try out.append(alloc, b);
+        i += 1;
+    }
+    return out.toOwnedSlice(alloc);
+}
+fn isCsiFinal(b: u8) bool {
+    return b >= 0x40 and b <= 0x7e;
+}
+test "stripSgr leaves text, drops SGR and OSC" {
+    const alloc = std.testing.allocator;
+    const got = try stripSgr(alloc, "\x1b[0m\x1b[1;31mred\x1b[0m ok\n\x1b]0;title\x07plain");
+    defer alloc.free(got);
+    try std.testing.expectEqualStrings("red ok\nplain", got);
+}
+fn verbRun(alloc: std.mem.Allocator, conn: *Conn, o: Opts, deadline: i64) u8 {
+    const cmdline = o.arg orelse return fail("run needs CMDLINE", "");
+    attachZero(conn) catch return fail("attach failed", "");
+    const started = std.time.milliTimestamp();
+    const since = currentSeq(alloc, conn, deadline) catch
+        return fail("no reply — daemon too old or hung", "");
+    const line = std.fmt.allocPrint(alloc, "{s}\n", .{cmdline}) catch return 1;
+    defer alloc.free(line);
+    conn.sendFrame(.input, line) catch return fail("send failed", "");
+    const r = doAwait(alloc, conn, o, since, deadline) catch
+        return fail("no reply — daemon too old or hung", "");
+    // Output span only in the marks regime — pgid/settle have no rows.
+    var output: ?[]const u8 = null;
+    if (r.state.mechanism == .marks and r.reason == .returned) {
+        output = fetchSpan(alloc, conn, r.state.start_row, r.state.end_row, deadline) catch null;
+    }
+    defer if (output) |text| if (text.len > 0) alloc.free(text);
+    printAwaitReply(r, output, std.time.milliTimestamp() - started) catch return 1;
+    return if (r.reason == .timeout) 3 else 0;
+}
+```
+Executor note on `run`'s default settle: an agent calling `run` against a marks-less session with `--settle 0` would ride to the timeout. That is per spec (settle is opt-in), and `status` tells the agent which regime it is in first. Do not silently default settle on.
+- [ ] **Step 2: Run unit tests + live smoke**
+Run: `$ZIG build test 2>&1 | tail -5` — PASS.
+```bash
+$ZIG build
+SOCK=/tmp/muxa-run-$$.sock
+MUX_SHELL_INTEGRATION=1 ./zig-out/bin/muxd start --sock $SOCK --shell /bin/bash
+sleep 1
+./zig-out/bin/muxa run 'false' --sock $SOCK       # {"reason":"returned",...,"exit_code":1,...,"mechanism":"marks"}
+./zig-out/bin/muxa run 'echo span-test' --sock $SOCK   # output contains "span-test"
+./zig-out/bin/muxa await --settle 300 --sock $SOCK # settles quickly at an idle prompt... reason "settled"
+./zig-out/bin/muxd stop --sock $SOCK
+```
+Expected: exit codes and mechanisms as annotated.
+- [ ] **Step 3: Commit**
+```bash
+git add src/muxa.zig
+git commit -m "feat(muxa): run and await — exit codes over marks, spans from scrollback"
+```
+---
+### Task 10: `muxa` over QUIC
+**Files:**
+- Modify: `src/muxa.zig`, `build.zig`
+- [ ] **Step 1: Extend `Conn` to a tagged union** over the existing socket arm and a QUIC arm using `quic_client.Client` (`connect/send/pump/pollFd/inbound/consume/isReady` — a cleanly reusable API; do NOT borrow `client.zig`'s reconnect loop, which is entangled with the attach replica). Add flags `--quic HOST:PORT` and `--key PATH` to `parseArgs` (key resolution via `xdg.resolveKeyPath`/`pickKey` exactly as `src/main.zig` does — copy its order: `--key` > `$MUX_KEY_FILE` > XDG default). The QUIC arm's `sendFrame` wraps `proto.appendFrame` into a buffer then `client.send`; `awaitFrame` pumps + polls `pollFd` with the same deadline discipline, delimiting frames out of `inbound()` with `proto.frame_header_len` exactly the way `server.zig`'s `pushInbound` does (copy that loop). On `error.ConnectionLost` mid-await: reconnect once, re-attach 0x0, re-issue the await with the ORIGINAL `since_seq` (the idempotency contract), and continue the deadline — not reset it.
+- [ ] **Step 2: build.zig**: add `quic_client` + `xdg` + `quic` imports to `muxa_mod`, and `linkQuic(b, muxa_exe, quic)` like `mux_exe` has.
+- [ ] **Step 3: Live QUIC smoke**
+```bash
+$ZIG build
+KEYDIR=$(mktemp -d)
+MUX_KEY_FILE=$KEYDIR/key ./zig-out/bin/muxd keygen 2>/dev/null || ./zig-out/bin/muxd keygen
+SOCK=/tmp/muxa-quic-$$.sock
+./zig-out/bin/muxd start --sock $SOCK --quic 127.0.0.1:14433 --shell /bin/bash
+sleep 1
+./zig-out/bin/muxa run 'echo quic-ok' --quic 127.0.0.1:14433
+./zig-out/bin/muxd stop --sock $SOCK
+```
+Expected: the run JSON reports exit 0 and output containing `quic-ok`. (Key path plumbing: use whatever `muxd keygen` wrote — check `muxd keygen`'s output line for the path and pass `--key` if the default resolution does not find it.)
+- [ ] **Step 4: Run full suite, commit**
+```bash
+$ZIG build test 2>&1 | tail -5
+git add src/muxa.zig build.zig
+git commit -m "feat(muxa): QUIC transport — same verbs, remote daemons, one reconnect re-issue"
+```
+---
+### Task 11: End-to-end script — shell marks, ephemeral TUI, version-skew honesty
+**Files:**
+- Create: `test/agent.sh` (executable)
+- [ ] **Step 1: Write `test/agent.sh`** modeled on `test/e2e.sh`'s conventions (read its header first: how it finds binaries, traps cleanup, counts failures). Scenarios, each against `./zig-out/bin`:
+. **Marks session**: `muxd start --sock $S --shell /bin/bash` → `muxa run 'exit 3'`-style checks: `run 'true'` exit_code 0, `run 'false'` exit_code 1, `run 'echo out-$$'` output contains the marker, mechanism `marks` on all three.
+. **Ephemeral TUI (the spec's field specimen)**: `muxd start --sock $S -- <TUI>` — use `vi` if present else `less /etc/hostname`: `muxa status` shows `alt_screen true` and mechanism not `marks`; `muxa send 'q'` (or `:q\n` for vi); then `muxa status` fails with connection refused OR the daemon exits — assert the session ended and `muxa` printed a JSON error object, not a stack trace. (Note: `muxd start`'s `--` argv support — if `muxd start` cannot take an argv today, spawn via `--shell /usr/bin/vi`; the shell flag execs any binary, which is exactly what `Pty.spawn` does with it.)
+. **Settle**: `run 'sleep 1' --settle 300 --timeout 10000` against `--shell /bin/sh` (no marks): reason `settled` or `returned` (pgid may win the race — both are honest; assert NOT `timeout`).
+. **Alt-screen guard**: in the TUI session, `muxa run 'true' --timeout 1500` must come back reason `timeout` (exit 3) rather than fabricating a return.
+- [ ] **Step 2: Run it**
+```bash
+$ZIG build && bash test/agent.sh
+```
+Expected: all scenarios green, script exits 0.
+- [ ] **Step 3: Commit**
+```bash
+git add test/agent.sh
+git commit -m "test(agent): e2e — marks exit codes, ephemeral TUI drive, settle vs timeout honesty"
+```
+---
+### Task 12: Docs and close-out
+**Files:**
+- Modify: `docs/roadmap.md` (agent surface entry: shipped, what is deferred — MCP wrapper, scoped auth, input attribution, event subscriptions)
+- Modify: `docs/decisions.md` (three decisions worth recording: rows-not-seqs for spans; the MuxHandler wrap instead of patching the dep; awaits at 100ms tick granularity instead of poll folding)
+- Modify: `README.md` if it lists binaries (add `muxa` one-liner)
+- [ ] **Step 1: Write the entries** — follow each file's existing voice and format; state what was deliberately NOT built and why (the spec's Non-goals section is the source).
+- [ ] **Step 2: Full suite + build one last time**
+```bash
+$ZIG build test 2>&1 | tail -5 && $ZIG build 2>&1 | tail -3 && bash test/agent.sh
+```
+Expected: everything green.
+- [ ] **Step 3: Commit**
+```bash
+git add docs/roadmap.md docs/decisions.md README.md
+git commit -m "docs: agent surface shipped — decisions recorded, deferrals named"
+```
+---
+## Plan self-review notes (already applied)
+- **Spec coverage**: injection (T7), interception (T3), state machine (T4), cmd_state/status (T1/T5), awaits with all three mechanisms + since_seq idempotency (T6), muxa verbs incl. 0x0 attach (T8/T9), QUIC + own reconnect loop (T10), ephemeral TUI as first-class (T11), version-skew timeout-is-the-detection (muxa's "no reply — daemon too old or hung", T8), docs (T12). Alt-screen row caveat is enforced by T11 scenario 4 rather than a row check — rows are simply absent outside marks.
+- **Known soft spots the executor must resolve against the live code, not guess**: the server test harness helpers (T5/T6 — copy neighbors), 0.15 stdout/ArrayList-writer idioms in muxa (follow `src/main.zig`), `muxd start -- argv` support in T11 (fallback given inline).
+- **Type consistency**: `proto.CmdState`/`CmdPhase`/`Mechanism` defined once in T1 and used by that name in T4–T9; `Engine.MarkEvent` defined in T3, consumed in T4/T5; `AwaitState` lives only in server.zig.

docs/superpowers/specs/2026-08-13-agent-surface-design.md

@@ @@ -0,0 +1,242 @@ @@
+# Agent surface: native LLM integration for mux
+**Date:** 2026-08-13
+**Status:** approved (design), pending implementation plan
+**Branch:** feat/agent-surface
+## Problem
+LLM agents drive terminals today by shelling out to `tmux send-keys` /
+`capture-pane`: blind polling, arbitrary sleeps, no signal for "the command
+returned", no exit codes, no mode awareness, full-screen captures on every
+poll. mux owns the PTY and runs an authoritative server-side ghostty-vt
+emulator, so it can hand an agent the signals tmux structurally cannot:
+command boundaries with exit codes, wait-for-return semantics, structured
+screen state, and token-efficient diffs — locally and over QUIC.
+Goal: an agent (Claude via Bash, or any LLM harness) drives interactive
+programs in a mux session and *knows* when a program has returned, with its
+exit code, without polling or guessing.
+## Non-goals (v1)
+- No MCP server. Agents drive the standalone CLI via their shell tool; an
+  MCP wrapper can be layered later without protocol changes.
+- No read-only / scoped auth. The existing model stands: unix socket gated
+  by filesystem permissions, QUIC by the shared PSK key, one key = full
+  control. A capability-scoped or observer-only role is a noted follow-up.
+- No multi-session listing or management. One daemon = one session stands.
+- No semantic event *subscriptions* beyond `cmd_state` push (no "prompt
+  detected" pub/sub surface).
+## Design
+Three components: command-boundary detection in the daemon, three new
+protocol frame pairs, and a standalone agent binary `muxa`.
+### 1. Command-boundary detection (daemon-side)
+**Shell integration, auto-injected.** muxd forks the session shell itself,
+so it injects OSC 133 integration at spawn with no rc-file edits:
+- zsh: point `ZDOTDIR` at a mux-owned shim directory whose `.zshrc` sources
+  the integration, restores the user's original `ZDOTDIR`, then sources the
+  user's real `.zshrc`.
+- bash: launch with `--init-file <shim>`; the shim sources the user's normal
+  startup files first, then the integration.
+- fish: prepend a mux directory to `XDG_DATA_DIRS`; fish auto-sources
+  `fish/vendor_conf.d/*.fish`.
+Scripts are vendored from ghostty's shell-integration (battle-tested against
+multi-line prompts, Ctrl-C at an empty prompt, prompt redraws), trimmed to
+the OSC 133 marks mux consumes. Opt-out: `MUX_SHELL_INTEGRATION=0`,
+necessarily read from the *daemon's* environment (the daemon sets the
+child's env). Detection is by basename of the shell being exec'd (from
+`--shell`/`$SHELL`; mux execs the shell directly, no login `-` prefix, so
+bash `--init-file` is safe); unknown shells get no injection and rely on
+fallbacks. Two mechanics: `Pty.spawn` builds a one-element argv today —
+injection extends it via the existing `spawnArgv`; and "restore the user's
+original `ZDOTDIR`" means the shim exports the `ZDOTDIR` captured at spawn
+if one was set, else *unsets* it — a daemon started from ssh/scripts often
+carries no user `ZDOTDIR` at all, and exporting an empty one would break
+zsh's fallback to `$HOME`.
+**Mark interception.** ghostty-vt already parses OSC 133 including the
+`err` exit code, but its stock `stream_terminal.Handler` discards the code
+and exposes no semantic-prompt callback. The mechanism: `vt.Stream(H)` is
+generic over the handler, so mux defines its own handler that wraps the
+stock one, intercepts `.semantic_prompt` in `vt()`, and forwards everything
+else — no byte-stream scanning, no dep patch. The engine's hardcoded
+`vt.TerminalStream` becomes `vt.Stream(MuxHandler)`. The handler drives a
+per-session command state machine:
+    at_prompt --(133;C, record start_row)--> running
+    running --(133;D;code, record end_row)--> returned(code)
+    returned --(133;A or 133;C)--> at_prompt / running
+**Output spans are rows, not seqs.** The codebase's `seq` is a viewport
+delta generation (bumped once per diff pass over the viewport), not a byte
+or row offset — a whole command's output can share one seq, and rows lose
+their seq once scrolled into history. So marks record absolute screen-space
+rows (`historyRows() + cursor.y` at mark time), and output recovery is the
+existing `fetch_scrollback` (start row + count), unchanged. Caveats stated
+plainly: row spans are meaningless while the alt screen is active, and row
+indices shift once the scrollback ring prunes — consumers should fetch
+spans promptly after `returned`. `seq` is still used, but only for await
+ordering ("a return at seq >= since_seq"), defined as the tracker seq
+after the post-feed update so it can't be off-by-one against the rows of
+the same PTY chunk.
+**Fallback stack.** The daemon always knows its detection regime and reports
+it in every reply:
+. `marks` — OSC 133 seen recently: exit codes + exact output spans.
+. `pgid` — no marks (nested ssh, docker exec, unknown shell): the daemon
+   polls `tcgetpgrp` on the PTY master only while an await is outstanding;
+   fg pgid returning to the shell's pgid means the foreground job returned.
+   No exit code, no exact span.
+. `settle` — last resort: no output for N ms (N from the await request).
+Regime selection: marks are trusted if the current command was opened by a
+`133;C`; otherwise pgid; settle only if explicitly requested as a floor or
+pgid is unavailable.
+### 2. Protocol additions
+Three frame pairs on the existing non-exhaustive `MsgType` enum(u8) — they
+transit `muxd proxy` untouched (`proxy` is genuinely frame-agnostic), and
+old clients tolerate an unexpected push. Values: client→daemon `await_req`
+x09, `status_req` 0x0a; daemon→client `cmd_state` 0x8a, `await_reply`
+x8b, `status_reply` 0x8c (leaving the existing 0x83 hole alone). Payloads
+follow house style: explicit `encode*/decode*` helpers over fixed
+little-endian buffers, `packed struct(u8)` only for flag bytes.
+- `cmd_state` (daemon→client, pushed): emitted on every state-machine
+  transition to attached clients. Carries: state (running | returned),
+  exit code (when known), start_row/end_row, seq at transition, detection
+  mechanism. Pushes exist only in the marks regime — pgid/settle
+  transitions are observed only while an await is outstanding and surface
+  via `await_reply`.
+- `await_req` (client→daemon) / `await_reply` (daemon→client): "wake me
+  when a command returns after `since_seq`; if `settle_ms` is nonzero,
+  also resolve after that much output silence." If a return already
+  happened past `since_seq`, the daemon replies immediately — this is
+  what makes re-issuing an await after a reconnect safe. The daemon holds
+  the await server-side — no client polling, identical behaviour over
+  unix socket and QUIC. Awaits fit the existing single poll pump without
+  blocking: their deadlines (settle, timeout, pgid poll cadence) fold into
+  the loop's `wait_ms` computation the same way the QUIC `timeoutMs`
+  already does. Reply carries the same payload as `cmd_state` plus a
+  reason (returned | settled | timeout).
+- `status_req` / `status_reply`: one structured snapshot — cols/rows,
+  cursor position, alt-screen flag, pty_mode bits (icanon/echo), current
+  command state, detection regime, current stream seq.
+Attach, input, resize, snapshot, delta are unchanged; an agent is a normal
+attached client — with one load-bearing rule: **`muxa` attaches with
+cols=rows=0**. Attaching at a real size would claim the grid and resize the
+human's session, and every `input` frame re-claims at the sender's size.
+The 0x0 escape hatch already exists (`applySize` refuses cols<2, and a 0x0
+slot "makes no claim" in `claimGrid`); the spec makes it a contract.
+Multiple outstanding awaits (e.g. agent + test harness) are each answered.
+### 3. `muxa` — standalone agent binary
+A separate binary in this repo, reusing `protocol.zig`, `quic_client.zig`,
+and `xdg.zig` key resolution. Same connection flags as `mux`: `--sock PATH`,
+`quic://host:port` targets, `--key` / `$MUX_KEY_FILE` / XDG default.
+Remote-over-QUIC is in scope from day one; every verb works identically
+against a local socket and a WAN daemon.
+All verbs print a single JSON object on stdout; exit code 0 on success,
+nonzero with a JSON error object on failure.
+- `muxa run "make test"` — flagship. Sends the command line (plus newline),
+  awaits return, prints `{exit_code, output, mechanism, duration_ms,
+  start_row, end_row}`. `--settle N` sets the fallback floor; `--timeout N`
+  bounds the wait (nonzero exit, state reported, on expiry).
+- `muxa send "keys"` — raw bytes to the PTY (escapes for control keys),
+  no waiting. The TUI-driving path.
+- `muxa capture [--diff-since SEQ] [--vt]` — current grid as text (or with
+  SGR), or the delta rows since SEQ with the new seq. Token-efficient
+  re-reads for TUI driving.
+- `muxa status` — the status_reply as JSON.
+- `muxa await [--settle N] [--timeout N]` — wait without sending, for
+  commands typed by a human or another agent.
+TUI driving composes `send` + `status` (alt-screen flag answers "am I in a
+TUI") + `capture --diff-since`. `run` is for shell command lines only; its
+JSON reports `mechanism` so the agent knows whether `exit_code` is real
+(`marks`) or absent (`pgid` / `settle`).
+### Ephemeral sessions (first-class use case)
+Agents often want a throwaway session, not an attachment to a standing one:
+spawn a TUI fresh, poke it, read the screen, quit, tear down. (Field
+specimen: a Claude session hand-rolled a Python `pty.fork` driver with
+sleep-based drains writing raw VT bytes to a file — a worse muxd in 30
+lines.) The workflow composes from existing verbs and is blessed and tested
+as such, not given new machinery:
+    muxd start --sock <tmp> -- <program>   # throwaway daemon
+    muxa send/await/capture ...            # drive it
+    muxd stop --sock <tmp>                 # reap it
+Against a session whose root process is a TUI rather than a shell, no marks
+ever appear: the regime is pgid/settle from frame one, `status` says so,
+and the program quitting surfaces as the existing `exit_status` frame —
+`muxa` verbs report it as a structured "session ended" result rather than a
+transport error. A single-shot `muxa drive -- CMD` wrapper is deferred; the
+composition covers it.
+## Error handling
+- Daemon without the new frames (version skew): old daemons silently drop
+  unknown frames, so there is no faster signal than the client-side
+  timeout — the timeout *is* the detection, and `muxa` reports it as a
+  structured "no reply — daemon too old or hung" error. (House doctrine is
+  lockstep binaries, not wire compatibility; this is a courtesy error, not
+  a compat promise.)
+- Injection failure (shim unwritable, unknown shell): session starts
+  normally without marks; regime degrades to pgid and `status` says so.
+- Marks from a lying/nested program: the state machine only trusts `133;D`
+  that closes a seen `133;C`; stray marks reset to at_prompt.
+- QUIC drop mid-await: `muxa` carries its own small reconnect loop over
+  `quic_client.Client` (whose connect/send/pump API is cleanly reusable;
+  the *existing* reconnect path is entangled with the attach client's
+  replica/raw-terminal loop and is not reused). An await outstanding
+  across a reconnect is re-issued with the original `since_seq`, so a
+  return that landed during the gap is answered immediately, not missed.
+## Testing
+House fixture style (`test/wsclient.zig` precedent):
+- State-machine unit tests: scripted byte streams with OSC 133 marks
+  (normal exit, signal death 128+n, Ctrl-C at empty prompt, nested/stray
+  marks, interleaved output).
+- Injection tests per shell: spawn zsh/bash/fish under the daemon, assert
+  marks appear and user rc still runs (PATH/prompt sentinel).
+- Fallback tests: shell with integration disabled — `run` resolves via
+  pgid; raw `cat` session — resolves via settle.
+- `muxa` end-to-end over unix socket: `run` returns real exit codes
+  (`true`/`false`/`sleep`), `capture --diff-since` matches `expectgrid`
+  fixtures.
+- One QUIC end-to-end: `muxa run` against a daemon on `quic://127.0.0.1`.
+- Ephemeral TUI end-to-end: `muxd start -- <tui fixture>`, `muxa send` a
+  key, `await --settle`, `capture` asserts the rendered grid, quit,
+  `muxa` reports session ended via exit_status.
+- Version-skew test: `muxa status` against an old-protocol daemon reports
+  the structured error.
+Per house doctrine, pinned regression tests go before any test the same
+hang could wedge.
+## Follow-ups (explicitly deferred)
+- MCP server wrapping `muxa` semantics.
+- Read-only / capability-scoped auth (observer role for watching agents).
+- Input attribution (marking agent-injected input so attached humans can
+  see who typed).
+- Semantic event subscriptions (prompt-detected, alt-screen-entered) for
+  observer agents.

src/client.zig

Old		New
@@ -11,6 +11,7 @@ const Replica = @import("replica").Replica;
11	const proto = @import("protocol");	11	const proto = @import("protocol");
12	const TmpDir = @import("testtmp").TmpDir;	12	const TmpDir = @import("testtmp").TmpDir;
13	const quic_client = @import("quic_client");	13	const quic_client = @import("quic_client");
		14	const quic = @import("quic");
14	const predict = @import("predict");	15	const predict = @import("predict");
15	const handoff = @import("handoff");	16	const handoff = @import("handoff");
16	// Named `paint_mod` because paintOverlay holds a local ArrayList called	17	// Named `paint_mod` because paintOverlay holds a local ArrayList called
@@ -257,7 +258,7 @@ pub const Transport = struct {
257	.hand => \|h\| return openHandoff(alloc, h, carry, abort_fd),	258	.hand => \|h\| return openHandoff(alloc, h, carry, abort_fd),
258	.quic => \|q\| {	259	.quic => \|q\| {
259	const key = try quic_client.Key.load(q.key_path);	260	const key = try quic_client.Key.load(q.key_path);
260	const addr = try parseQuicAddr(q.host_port);	261	const addr = try quic.parseAddr(alloc, q.host_port);
261	return quicTransport(alloc, addr, key, q.idle_ms, q.deadline_ms, carry, abort_fd);	262	return quicTransport(alloc, addr, key, q.idle_ms, q.deadline_ms, carry, abort_fd);
262	},	263	},
263	.via => \|cmd\| return pipeTransport(try spawnPipe(alloc, cmd)),	264	.via => \|cmd\| return pipeTransport(try spawnPipe(alloc, cmd)),
@@ -372,7 +373,7 @@ pub const Transport = struct {
372	carry: ?*std.ArrayList(u8),	373	carry: ?*std.ArrayList(u8),
373	abort_fd: std.posix.fd_t,	374	abort_fd: std.posix.fd_t,
374	) !Transport {	375	) !Transport {
375	const addr = try resolveHost(handoff.dialHost(h.host), ep.port);	376	const addr = try quic.resolveHost(alloc, handoff.dialHost(h.host), ep.port);
376	const key = quic_client.Key{ .bytes = ep.key };	377	const key = quic_client.Key{ .bytes = ep.key };
377	return quicTransport(alloc, addr, key, h.idle_ms, h.deadline_ms, carry, abort_fd);	378	return quicTransport(alloc, addr, key, h.idle_ms, h.deadline_ms, carry, abort_fd);
378	}	379	}
@@ -677,43 +678,6 @@ fn readAnnounceAbortable(
677	}	678	}
678	}	679	}
679		680
680	/// `HOST:PORT` for a `quic://` target. Literal addresses only on the muxd
681	/// side because a bind address that resolves to several is a question; here
682	/// a NAME is exactly what a user types, so this one does resolve.
683	fn parseQuicAddr(host_port: []const u8) !std.net.Address {
684	// `[::1]` — bracketed, portless: the brackets say where the address
685	// stops, so the port can default.
686	if (host_port.len >= 2 and host_port[0] == '[' and host_port[host_port.len - 1] == ']')
687	return resolveHost(host_port[1 .. host_port.len - 1], quic_client.default_port);
688	const colon = std.mem.lastIndexOfScalar(u8, host_port, ':') orelse
689	return resolveHost(host_port, quic_client.default_port);
690	var host = host_port[0..colon];
691	const port_s = host_port[colon + 1 ..];
692	// `[::1]:4433` — brackets are how an IPv6 literal says where it stops.
693	if (host.len >= 2 and host[0] == '[' and host[host.len - 1] == ']') {
694	host = host[1 .. host.len - 1];
695	} else if (std.mem.indexOfScalar(u8, host, ':') != null) {
696	// Unbracketed and full of colons: an IPv6 literal missing its
697	// brackets, which would otherwise have its last group taken as a
698	// port. Refused rather than guessed at.
699	return error.MalformedAddress;
700	}
701	const port = std.fmt.parseInt(u16, port_s, 10) catch return error.MalformedAddress;
702	return resolveHost(host, port);
703	}
704
705	/// A host that is already known to be unambiguous, plus the port it goes
706	/// with: literal if it parses as one, resolved if it does not.
707	fn resolveHost(host: []const u8, port: u16) !std.net.Address {
708	if (host.len == 0) return error.MalformedAddress;
709	if (std.net.Address.parseIp(host, port)) \|addr\| return addr else \|_\| {}
710	// Not a literal: resolve it. A remote host is normally a name.
711	const list = try std.net.getAddressList(std.heap.page_allocator, host, port);
712	defer list.deinit();
713	if (list.addrs.len == 0) return error.UnknownHostName;
714	return list.addrs[0];
715	}
716
717	/// Whether a failed handoff failed at the announce — meaning ssh itself	681	/// Whether a failed handoff failed at the announce — meaning ssh itself
718	/// worked and what came back was not the line we needed — rather than	682	/// worked and what came back was not the line we needed — rather than
719	/// before it.	683	/// before it.
@@ -2360,21 +2324,6 @@ test "drainStdinForQuit: closed stdin still paces the retry instead of spinning"
2360	try std.testing.expect(elapsed_ms >= 150);	2324	try std.testing.expect(elapsed_ms >= 150);
2361	}	2325	}
2362		2326
2363	test "parseQuicAddr: no port means 4433, explicit port wins" {
2364	// 4433 spelled out, not `quic_client.default_port`: asserting against
2365	// the constant the code under test reads would hold for any value, so
2366	// it could never catch the number changing — and this is precisely the
2367	// number the daemon must agree with.
2368	const d = try parseQuicAddr("127.0.0.1");
2369	try std.testing.expectEqual(@as(u16, 4433), d.getPort());
2370	const e = try parseQuicAddr("127.0.0.1:9");
2371	try std.testing.expectEqual(@as(u16, 9), e.getPort());
2372	const b = try parseQuicAddr("[::1]");
2373	try std.testing.expectEqual(@as(u16, 4433), b.getPort());
2374	// Unbracketed IPv6 stays ambiguous and refused, with or without ports.
2375	try std.testing.expectError(error.MalformedAddress, parseQuicAddr("fe80::1:4433"));
2376	}
2377
2378	test "lostMsg: only a --via transport that never connected gets the new wording" {	2327	test "lostMsg: only a --via transport that never connected gets the new wording" {
2379	// The case the message exists for: a command that failed to start. It	2328	// The case the message exists for: a command that failed to start. It
2380	// names what happened and guesses no cause — ssh's own stderr passes	2329	// names what happened and guesses no cause — ssh's own stderr passes

src/cmd.zig

@@ @@ -0,0 +1,153 @@ @@
+//! The session's command state machine: MarkEvents in, transitions out.
+//! Pure — no I/O, no clock, no seq. The server stamps seqs and decides who
+//! hears about a transition; this module only decides what the marks mean.
+//! Trust rule (spec): a D only counts if it closes a seen C; a stray D
+//! resets to at_prompt rather than being believed. A nested C is believed
+//! wholesale — latest wins, no attempt to detect the nesting — and a stray
+//! A at idle is a no-op.
+const std = @import("std");
+const proto = @import("protocol");
+const Engine = @import("engine").Engine;
+pub const Tracker = struct {
+    phase: proto.CmdPhase = .at_prompt,
+    /// Sticky: once any C has been seen, this session speaks marks and the
+    /// pgid fallback stops being consulted while a command is open.
+    marks_seen: bool = false,
+    start_row: u32 = 0,
+    end_row: u32 = 0,
+    exit_code: ?u8 = null,
+    /// `.reset` means the tracker forcibly settled to `at_prompt`; it is a
+    /// state change to observe, never a transition to broadcast.
+    pub const Transition = enum { running, returned, reset };
+    pub fn apply(self: *Tracker, ev: Engine.MarkEvent) ?Transition {
+        switch (ev.kind) {
+            .command_start => {
+                self.marks_seen = true;
+                self.phase = .running;
+                self.start_row = ev.row;
+                // The new command has not ended, so it has no end row — and
+                // the PREVIOUS command's would be a lie about this one,
+                // read as a span running backwards (end < start) by anyone
+                // who fetched it mid-run. Collapsing it to the start row
+                // says what is true under the end<=start convention: the
+                // span is empty until a D closes it.
+                self.end_row = ev.row;
+                self.exit_code = null;
+                return .running;
+            },
+            .command_end => {
+                if (self.phase != .running) {
+                    // A D with no open C: a nested program echoing marks it
+                    // has no business emitting. Reset, believe nothing.
+                    self.phase = .at_prompt;
+                    return .reset;
+                }
+                self.phase = .returned;
+                self.end_row = ev.row;
+                self.exit_code = ev.exit_code;
+                return .returned;
+            },
+            .prompt_start => {
+                // 'A' after a return is the prompt redrawing: back to rest.
+                // 'A' mid-run (Ctrl-C redraw) also lands here — the shell
+                // is telling us the command is over even without a D.
+                if (self.phase == .running) {
+                    self.phase = .returned;
+                    self.end_row = ev.row;
+                    self.exit_code = null; // interrupted: no honest code
+                    return .returned;
+                }
+                self.phase = .at_prompt;
+                return null;
+            },
+        }
+    }
+    /// True while marks say a command is open — the window in which the
+    /// pgid fallback must NOT race the marks to a verdict.
+    pub fn marksOpen(self: *const Tracker) bool {
+        return self.marks_seen and self.phase == .running;
+    }
+};
+test "C then D is running then returned, with rows and code" {
+    var t = Tracker{};
+    try std.testing.expectEqual(@as(?Tracker.Transition, .running), t.apply(.{ .kind = .command_start, .row = 10, .exit_code = null }));
+    try std.testing.expectEqual(proto.CmdPhase.running, t.phase);
+    try std.testing.expectEqual(@as(?Tracker.Transition, .returned), t.apply(.{ .kind = .command_end, .row = 14, .exit_code = 1 }));
+    try std.testing.expectEqual(proto.CmdPhase.returned, t.phase);
+    try std.testing.expectEqual(@as(u32, 10), t.start_row);
+    try std.testing.expectEqual(@as(u32, 14), t.end_row);
+    try std.testing.expectEqual(@as(?u8, 1), t.exit_code);
+}
+test "a stray D resets and is not believed" {
+    var t = Tracker{};
+    try std.testing.expectEqual(@as(?Tracker.Transition, .reset), t.apply(.{ .kind = .command_end, .row = 3, .exit_code = 0 }));
+    try std.testing.expectEqual(proto.CmdPhase.at_prompt, t.phase);
+    try std.testing.expectEqual(@as(?u8, null), t.exit_code);
+}
+test "A closes an open command without a code (Ctrl-C at a prompt redraw)" {
+    var t = Tracker{};
+    _ = t.apply(.{ .kind = .command_start, .row = 5, .exit_code = null });
+    try std.testing.expectEqual(@as(?Tracker.Transition, .returned), t.apply(.{ .kind = .prompt_start, .row = 6, .exit_code = null }));
+    try std.testing.expectEqual(@as(?u8, null), t.exit_code);
+    try std.testing.expectEqual(proto.CmdPhase.returned, t.phase);
+    try std.testing.expectEqual(@as(u32, 6), t.end_row);
+    // The next A settles back to rest with no transition.
+    try std.testing.expectEqual(@as(?Tracker.Transition, null), t.apply(.{ .kind = .prompt_start, .row = 6, .exit_code = null }));
+    try std.testing.expectEqual(proto.CmdPhase.at_prompt, t.phase);
+}
+test "marksOpen guards the pgid race window" {
+    var t = Tracker{};
+    try std.testing.expect(!t.marksOpen());
+    _ = t.apply(.{ .kind = .command_start, .row = 0, .exit_code = null });
+    try std.testing.expect(t.marksOpen());
+    _ = t.apply(.{ .kind = .command_end, .row = 1, .exit_code = 0 });
+    try std.testing.expect(!t.marksOpen());
+    // Sticky across the next prompt: the session still speaks marks.
+    _ = t.apply(.{ .kind = .prompt_start, .row = 1, .exit_code = null });
+    try std.testing.expect(t.marks_seen);
+}
+test "back-to-back commands: second C reopens cleanly" {
+    var t = Tracker{};
+    _ = t.apply(.{ .kind = .command_start, .row = 0, .exit_code = null });
+    _ = t.apply(.{ .kind = .command_end, .row = 2, .exit_code = 0 });
+    try std.testing.expectEqual(@as(?Tracker.Transition, .running), t.apply(.{ .kind = .command_start, .row = 4, .exit_code = null }));
+    try std.testing.expectEqual(@as(u32, 4), t.start_row);
+    try std.testing.expectEqual(@as(?u8, null), t.exit_code);
+    // Nothing of the finished command survives into the running one. The
+    // end row especially: left at 2 it would describe a span ending BEFORE
+    // it starts, which is what a mid-command status_reply hands an agent.
+    // Equal rows are the empty span every consumer already reads as "no
+    // output yet".
+    try std.testing.expectEqual(@as(u32, 4), t.end_row);
+    try std.testing.expect(t.end_row <= t.start_row);
+}
+test "a nested C while running is believed wholesale: latest wins" {
+    var t = Tracker{};
+    _ = t.apply(.{ .kind = .command_start, .row = 5, .exit_code = null });
+    try std.testing.expectEqual(@as(?Tracker.Transition, .running), t.apply(.{ .kind = .command_start, .row = 9, .exit_code = null }));
+    try std.testing.expectEqual(@as(u32, 9), t.start_row);
+    try std.testing.expectEqual(@as(?u8, null), t.exit_code);
+}
+test "a stray D after a completed command resets phase but never absorbs its payload" {
+    var t = Tracker{};
+    _ = t.apply(.{ .kind = .command_start, .row = 0, .exit_code = null });
+    _ = t.apply(.{ .kind = .command_end, .row = 2, .exit_code = 1 });
+    try std.testing.expectEqual(@as(?Tracker.Transition, .reset), t.apply(.{ .kind = .command_end, .row = 9, .exit_code = 7 }));
+    try std.testing.expectEqual(proto.CmdPhase.at_prompt, t.phase);
+    // The stray's row and exit code never land: the finished command's
+    // fields are left exactly as the real D set them.
+    try std.testing.expectEqual(@as(?u8, 1), t.exit_code);
+    try std.testing.expectEqual(@as(u32, 0), t.start_row);
+    try std.testing.expectEqual(@as(u32, 2), t.end_row);
+}

src/engine.zig

@@ @@ -3,14 +3,95 @@ @@
+const std = @import("std");
+const vt = @import("ghostty-vt");
+/// MuxHandler's own `vt` method shadows the `vt` import inside its body,
+/// so the dep types it names are spelled through these aliases.
+const StockHandler = vt.TerminalStream.Handler;
+const StreamAction = vt.StreamAction;
+/// The stock ghostty-vt handler forwards OSC 133 into the terminal and
+/// drops the exit code on the floor; there is no semantic-prompt callback
+/// in its Effects. So mux brings its own handler: intercept the one action
+/// we care about, forward everything (including that one) to the stock
+/// handler so terminal state stays identical.
+pub const MuxHandler = struct {
+    inner: StockHandler,
+    pub fn deinit(self: *MuxHandler) void {
+        self.inner.deinit();
+    }
+    pub fn vt(
+        self: *MuxHandler,
+        comptime action: StreamAction.Tag,
+        value: StreamAction.Value(action),
+    ) void {
+        if (comptime action == .semantic_prompt) self.onSemanticPrompt(value);
+        self.inner.vt(action, value);
+    }
+    fn engineOf(self: *MuxHandler) *Engine {
+        const stream_ptr: *MuxStream = @fieldParentPtr("handler", self);
+        // @alignCast for wasm32, for the reason spelled out on onWritePty.
+        return @alignCast(@fieldParentPtr("stream", stream_ptr));
+    }
+    fn onSemanticPrompt(
+        self: *MuxHandler,
+        value: StreamAction.Value(.semantic_prompt),
+    ) void {
+        const kind: Engine.MarkEvent.Kind = switch (value.action) {
+            .fresh_line_new_prompt => .prompt_start, // 'A'
+            .end_input_start_output => .command_start, // 'C'
+            .end_command => .command_end, // 'D'
+            else => return, // L/N/P/B/I: prompt furniture, not boundaries
+        };
+        const eng = self.engineOf();
+        // Only `D` carries a code, and even then only when the shell put one
+        // in the mark; everything else has none to read.
+        const raw = if (kind == .command_end) value.readOption(.exit_code) else null;
+        // Masked to the low byte, which is what waitpid would have reported:
+        // a shell is free to spell `D;300`, and truncating is the same answer
+        // the kernel gives rather than a refusal to parse.
+        const exit_code: ?u8 = if (raw) |code| @intCast(@as(u32, @bitCast(code)) & 0xff) else null;
+        // Load-bearing catch: under OOM we drop the mark rather than fail
+        // the feed. A dropped mark costs precision, not correctness —
+        // await falls back to pgid/settle when no boundary arrives.
+        eng.mark_events.append(eng.alloc, .{
+            .kind = kind,
+            .row = eng.historyRows() + eng.cursorPos().y,
+            .exit_code = exit_code,
+        }) catch {};
+    }
+};
+pub const MuxStream = vt.Stream(MuxHandler);
+pub const Engine = struct {
+    alloc: std.mem.Allocator,
+    term: vt.Terminal,
+    stream: MuxStream,
+    /// Response bytes the terminal wants written back to the PTY
+    /// (cursor position reports, device attributes, ...). Owner drains
+    /// via ptyOutput()/clearPtyOutput().
+    pty_out: std.ArrayList(u8),
+    /// OSC 133 mark events observed since the last clear. Drained by the
+    /// server after each feed, exactly like pty_out.
+    mark_events: std.ArrayList(MarkEvent),
+    pub const MarkEvent = struct {
+        pub const Kind = enum(u8) { prompt_start, command_start, command_end };
+        kind: Kind,
+        /// Absolute screen-space row (historyRows + cursor.y) at mark time.
+        /// Best-effort locator, not a durable anchor: pruning past
+        /// max_scrollback shifts the origin (a command longer than the
+        /// scrollback can even leave end_row < start_row), resize reflow
+        /// renumbers history, and alt-screen marks live in a different
+        /// coordinate space entirely (historyRows() is 0 there). Use it to
+        /// point a human at output, never to key durable state.
+        row: u32,
+        /// Only ever set on command_end, and only when the mark carried one.
+        exit_code: ?u8,
+    };
+    pub const Options = struct {
+        cols: u16,
@@ @@ -33,16 +114,18 @@ pub const Engine = struct { @@
+            }),
+            .stream = undefined,
+            .pty_out = .empty,
+            .mark_events = .empty,
+        };
+        errdefer self.term.deinit(alloc);
+        self.stream = .initAlloc(alloc, .{ .inner = .{ .terminal = &self.term } });
+        self.stream.handler.inner.effects.write_pty = &onWritePty;
+        return self;
+    pub fn deinit(self: *Engine) void {
+        self.pty_out.deinit(self.alloc);
+        self.mark_events.deinit(self.alloc);
+        self.stream.deinit();
+        self.term.deinit(self.alloc);
+        self.alloc.destroy(self);
@@ @@ -60,6 +143,14 @@ pub const Engine = struct { @@
+        self.pty_out.clearRetainingCapacity();
+    pub fn markEvents(self: *const Engine) []const MarkEvent {
+        return self.mark_events.items;
+    }
+    pub fn clearMarkEvents(self: *Engine) void {
+        self.mark_events.clearRetainingCapacity();
+    }
+    /// Visible screen as plain UTF-8 text. Caller frees.
+    pub fn dumpPlain(self: *Engine, alloc: std.mem.Allocator) ![]const u8 {
+        return self.term.plainString(alloc);
@@ @@ -224,7 +315,8 @@ pub const Engine = struct { @@
+    fn onWritePty(handler: *vt.TerminalStream.Handler, data: [:0]const u8) void {
+        const mh: *MuxHandler = @fieldParentPtr("inner", handler);
+        const stream_ptr: *MuxStream = @fieldParentPtr("handler", mh);
+        // The @alignCast is for wasm32, where pointers default to 4-byte
+        // alignment while Engine needs 8. Sound: the parent really is
+        // 8-aligned — every Engine comes from alloc.create (init's
@@ @@ -490,3 +582,112 @@ test "Engine: resize" { @@
+    defer e.deinit();
+    try e.resize(120, 40);
+test "Engine: OSC 133 marks surface as events with rows and exit codes" {
+    const alloc = std.testing.allocator;
+    var e = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer e.deinit();
+    e.feed("$ "); // a prompt on row 0
+    e.feed("\x1b]133;C\x07"); // command starts
+    e.feed("output line\r\n");
+    e.feed("\x1b]133;D;1\x07"); // command returns, exit 1
+    e.feed("\x1b]133;A\x07"); // next prompt
+    const evs = e.markEvents();
+    try std.testing.expectEqual(@as(usize, 3), evs.len);
+    try std.testing.expectEqual(Engine.MarkEvent.Kind.command_start, evs[0].kind);
+    try std.testing.expectEqual(@as(u32, 0), evs[0].row);
+    try std.testing.expectEqual(@as(?u8, null), evs[0].exit_code);
+    try std.testing.expectEqual(Engine.MarkEvent.Kind.command_end, evs[1].kind);
+    try std.testing.expectEqual(@as(u32, 1), evs[1].row); // cursor moved past the output line
+    try std.testing.expectEqual(@as(?u8, 1), evs[1].exit_code);
+    try std.testing.expectEqual(Engine.MarkEvent.Kind.prompt_start, evs[2].kind);
+    e.clearMarkEvents();
+    try std.testing.expectEqual(@as(usize, 0), e.markEvents().len);
+}
+test "Engine: mark rows are absolute screen rows, not viewport rows" {
+    const alloc = std.testing.allocator;
+    var e = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer e.deinit();
+    // Scroll 100 lines into history, then mark: the row must include them.
+    var i: usize = 1;
+    while (i <= 100) : (i += 1) {
+        var line: [32]u8 = undefined;
+        e.feed(std.fmt.bufPrint(&line, "line-{d}\r\n", .{i}) catch unreachable);
+    }
+    const hist = e.historyRows(); // 77 per the historyRows test
+    e.feed("\x1b]133;C\x07");
+    const evs = e.markEvents();
+    try std.testing.expectEqual(@as(usize, 1), evs.len);
+    try std.testing.expectEqual(hist + e.cursorPos().y, evs[0].row);
+}
+test "Engine: a D mark with no exit code yields a null code" {
+    const alloc = std.testing.allocator;
+    var e = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer e.deinit();
+    e.feed("\x1b]133;C\x07\x1b]133;D\x07");
+    const evs = e.markEvents();
+    try std.testing.expectEqual(@as(usize, 2), evs.len);
+    try std.testing.expectEqual(@as(?u8, null), evs[1].exit_code);
+}
+test "Engine: intercepting a mark still forwards it to the stock handler" {
+    const alloc = std.testing.allocator;
+    var e = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer e.deinit();
+    // The row the cursor sits on carries no prompt state yet.
+    try std.testing.expectEqual(
+        vt.page.Row.SemanticPrompt.none,
+        e.term.screens.active.cursor.page_row.semantic_prompt,
+    );
+    e.feed("\x1b]133;A\x07");
+    // MuxHandler.vt must forward every action it intercepts: the stock
+    // handler is what runs Terminal.semanticPrompt, and that is what marks
+    // the cursor's row as a prompt row. Swallowing the action instead of
+    // forwarding it leaves this .none while the event still lands.
+    try std.testing.expectEqual(
+        vt.page.Row.SemanticPrompt.prompt,
+        e.term.screens.active.cursor.page_row.semantic_prompt,
+    );
+    try std.testing.expectEqual(@as(usize, 1), e.markEvents().len);
+}
+test "Engine: exit codes truncate to a byte and malformed ones are null" {
+    const alloc = std.testing.allocator;
+    var e = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer e.deinit();
+    // The mark's exit code is whatever i32 the shell wrote, and PTY bytes
+    // are attacker-influenced: without the mask, 256 is a Debug-mode
+    // @intCast panic rather than a wrapped byte.
+    e.feed("\x1b]133;C\x07\x1b]133;D;256\x07");
+    try std.testing.expectEqual(@as(?u8, 0), e.markEvents()[1].exit_code);
+    e.clearMarkEvents();
+    e.feed("\x1b]133;C\x07\x1b]133;D;-1\x07");
+    try std.testing.expectEqual(@as(?u8, 255), e.markEvents()[1].exit_code);
+    e.clearMarkEvents();
+    e.feed("\x1b]133;C\x07\x1b]133;D;notanumber\x07");
+    try std.testing.expectEqual(@as(?u8, null), e.markEvents()[1].exit_code);
+}
+test "Engine: non-133 OSC and the ignored 133 subcommands emit no events" {
+    const alloc = std.testing.allocator;
+    var e = try Engine.init(alloc, .{ .cols = 80, .rows = 24 });
+    defer e.deinit();
+    e.feed("\x1b]0;a title\x07"); // OSC 0, not semantic
+    e.feed("\x1b]133;B\x07\x1b]133;P\x07\x1b]133;L\x07"); // B/P/L: not ours
+    try std.testing.expectEqual(@as(usize, 0), e.markEvents().len);
+}

src/main.zig

Old		New
@@ -293,7 +293,7 @@ pub fn main() !u8 {
293	const sock_path = if (o.sock) \|s\|	293	const sock_path = if (o.sock) \|s\|
294	try alloc.dupe(u8, s)	294	try alloc.dupe(u8, s)
295	else	295	else
296	try defaultSockPath(alloc);	296	try sockpath.defaultSockPath(alloc);
297	defer alloc.free(sock_path);	297	defer alloc.free(sock_path);
298		298
299	// The sun_path bound (sockpath.max_sun_path). Checked here, once,	299	// The sun_path bound (sockpath.max_sun_path). Checked here, once,
@@ -436,11 +436,22 @@ fn run(alloc: std.mem.Allocator, o: Opts, sock_path: []const u8) !u8 {
436	try alloc.dupeZ(u8, std.posix.getenv("SHELL") orelse "/bin/sh");	436	try alloc.dupeZ(u8, std.posix.getenv("SHELL") orelse "/bin/sh");
437	defer alloc.free(shell_z);	437	defer alloc.free(shell_z);
438		438
		439	// Read from the DAEMON's environment, necessarily: muxd forks the
		440	// session shell, so by the time anyone could pass a flag through a
		441	// client the shell has been running for a while. `MUX_SHELL_INTEGRATION=0`
		442	// and nothing else — any other value, including unset, means on.
		443	const shell_integration = !std.mem.eql(
		444	u8,
		445	std.posix.getenv("MUX_SHELL_INTEGRATION") orelse "",
		446	"0",
		447	);
		448
439	var srv = Server.init(alloc, .{	449	var srv = Server.init(alloc, .{
440	.sock_path = sock_path,	450	.sock_path = sock_path,
441	.shell = shell_z,	451	.shell = shell_z,
442	.cols = o.cols,	452	.cols = o.cols,
443	.rows = o.rows,	453	.rows = o.rows,
		454	.shell_integration = shell_integration,
444	}) catch \|err\| switch (err) {	455	}) catch \|err\| switch (err) {
445	// All of these mean "that path is not ours to take", and all	456	// All of these mean "that path is not ours to take", and all
446	// are ordinary operator mistakes rather than daemon bugs: say	457	// are ordinary operator mistakes rather than daemon bugs: say
@@ -476,13 +487,6 @@ fn run(alloc: std.mem.Allocator, o: Opts, sock_path: []const u8) !u8 {
476	return try srv.run();	487	return try srv.run();
477	}	488	}
478		489
479	pub fn defaultSockPath(alloc: std.mem.Allocator) ![]const u8 {
480	if (std.posix.getenv("XDG_RUNTIME_DIR")) \|dir\| {
481	return std.fmt.allocPrint(alloc, "{s}/muxd.sock", .{dir});
482	}
483	return std.fmt.allocPrint(alloc, "/tmp/muxd-{d}.sock", .{std.os.linux.getuid()});
484	}
485
486	/// Ask once, print the first reply of the type asked for, exit. `dump` and	490	/// Ask once, print the first reply of the type asked for, exit. `dump` and
487	/// `stats` are this same round-trip and differed only in the verb they	491	/// `stats` are this same round-trip and differed only in the verb they
488	/// name, the frame they send and the frame they wait for.	492	/// name, the frame they send and the frame they wait for.

src/muxa.zig

@@ @@ -0,0 +1,1574 @@ @@
+//! muxa: the agent-facing mux client. Every verb prints one JSON object on
+//! stdout and exits 0 on success; failures print {"error": "..."} and exit
+//! nonzero. Attaches at 0x0 always — an agent must never claim the grid
+//! out from under the human's size (load-bearing spec rule).
+const std = @import("std");
+const proto = @import("protocol");
+const sockpath = @import("sockpath");
+const quic_client = @import("quic_client");
+const quic = @import("quic");
+const xdg = @import("xdg");
+const usage =
+    \\usage: muxa <verb> [--sock PATH | --quic HOST[:PORT] [--key PATH]]
+    \\                   [--settle MS] [--timeout MS] [--vt] [args]
+    \\verbs:
+    \\  status              session snapshot as JSON
+    \\  capture             current grid as text (--vt for styled)
+    \\  send BYTES          raw bytes to the pty (C-style escapes: \n \r \t \e \xNN)
+    \\  run CMDLINE         send CMDLINE + newline, await return, report exit/output
+    \\  await               wait for the current/next command to return
+    \\
+;
+const Opts = struct {
+    verb: enum { status, capture, send, run, @"await" },
+    sock: ?[]const u8 = null,
+    /// `HOST[:PORT]` of a remote daemon's QUIC listener. The verbs are
+    /// identical over it — same frames, same JSON — which is the whole
+    /// claim: an agent driving a session over a WAN types one more flag.
+    quic: ?[]const u8 = null,
+    /// `--key PATH`, the highest-priority spelling of the QUIC key. Null
+    /// does NOT mean "no key": `$MUX_KEY_FILE` and the XDG default are
+    /// still to be tried, and neither is parse's to look at (xdg.pickKey
+    /// and xdg.resolveKeyPath own that order, as they do for muxd and mux).
+    key: ?[]const u8 = null,
+    settle_ms: u32 = 0,
+    // Never 0 by default: the daemon reads a 0 timeout on await_req as "no
+    // bound at all" (documented on AwaitReq), so a muxa that defaulted to 0
+    // would turn every await into an unbounded wait.
+    timeout_ms: u32 = 30_000,
+    vt: bool = false,
+    arg: ?[]const u8 = null,
+};
+fn parseArgs(args: []const [:0]const u8) ?Opts {
+    if (args.len < 2) return null;
+    const verb = std.meta.stringToEnum(@FieldType(Opts, "verb"), args[1]) orelse return null;
+    var o: Opts = .{ .verb = verb };
+    var i: usize = 2;
+    // Everything after a bare `--` is the positional argument, whatever it
+    // looks like. Agents send byte-strings for their own reasons, and
+    // `muxa send -- '-n foo\n'` must reach the pty rather than be read as
+    // a flag this binary does not have.
+    var end_of_flags = false;
+    while (i < args.len) : (i += 1) {
+        const a = args[i];
+        if (end_of_flags) {
+            if (o.arg != null) return null;
+            o.arg = a;
+        } else if (std.mem.eql(u8, a, "--")) {
+            end_of_flags = true;
+        } else if (std.mem.eql(u8, a, "--sock")) {
+            i += 1;
+            if (i >= args.len) return null;
+            o.sock = args[i];
+        } else if (std.mem.eql(u8, a, "--quic")) {
+            i += 1;
+            if (i >= args.len) return null;
+            o.quic = args[i];
+        } else if (std.mem.eql(u8, a, "--key")) {
+            i += 1;
+            if (i >= args.len) return null;
+            o.key = args[i];
+        } else if (std.mem.eql(u8, a, "--settle")) {
+            i += 1;
+            if (i >= args.len) return null;
+            o.settle_ms = std.fmt.parseInt(u32, args[i], 10) catch return null;
+        } else if (std.mem.eql(u8, a, "--timeout")) {
+            i += 1;
+            if (i >= args.len) return null;
+            o.timeout_ms = std.fmt.parseInt(u32, args[i], 10) catch return null;
+        } else if (std.mem.eql(u8, a, "--vt")) {
+            o.vt = true;
+        } else if (o.arg == null and a.len > 0 and a[0] != '-') {
+            o.arg = a;
+        } else return null;
+    }
+    // Name ONE transport. A `--sock` silently ignored beside a `--quic`
+    // would send an agent's frames somewhere other than the socket it
+    // named, and the two answers differ — this is the mistake `mux`
+    // refuses as `.conflict` for the same reason.
+    if (o.quic != null and o.sock != null) return null;
+    // A key with nothing to authenticate to, refused exactly where muxd
+    // refuses it: there is no reading of `--key` without `--quic` that
+    // makes it sensible, and the unix socket has no key at all.
+    if (o.key != null and o.quic == null) return null;
+    return o;
+}
+/// JSON string escape, the six mandatory escapes + control bytes as \u00XX.
+fn jsonEscape(writer: anytype, s: []const u8) !void {
+    try writer.writeByte('"');
+    for (s) |b| switch (b) {
+        '"' => try writer.writeAll("\\\""),
+        '\\' => try writer.writeAll("\\\\"),
+        '\n' => try writer.writeAll("\\n"),
+        '\r' => try writer.writeAll("\\r"),
+        '\t' => try writer.writeAll("\\t"),
+x00...0x08, 0x0b, 0x0c, 0x0e...0x1f => try writer.print("\\u{x:0>4}", .{b}),
+        else => try writer.writeByte(b),
+    };
+    try writer.writeByte('"');
+}
+test "jsonEscape pins the escapes" {
+    var buf: [128]u8 = undefined;
+    var fbs = std.io.fixedBufferStream(&buf);
+    try jsonEscape(fbs.writer(), "a\"b\\c\nd\x1be");
+    try std.testing.expectEqualStrings("\"a\\\"b\\\\c\\nd\\u001be\"", fbs.getWritten());
+}
+/// Decode C-style escapes for `send`. Caller frees.
+fn decodeEscapes(alloc: std.mem.Allocator, s: []const u8) ![]u8 {
+    var out: std.ArrayList(u8) = .empty;
+    errdefer out.deinit(alloc);
+    var i: usize = 0;
+    while (i < s.len) : (i += 1) {
+        if (s[i] != '\\') {
+            try out.append(alloc, s[i]);
+            continue;
+        }
+        // A backslash with nothing after it is an unfinished escape, and it
+        // is refused like any other one we cannot read (\q). Passing it
+        // through as a literal would be the single case where a typo in an
+        // escape reaches the pty instead of being reported.
+        if (i + 1 >= s.len) return error.BadEscape;
+        i += 1;
+        switch (s[i]) {
+            'n' => try out.append(alloc, '\n'),
+            'r' => try out.append(alloc, '\r'),
+            't' => try out.append(alloc, '\t'),
+            'e' => try out.append(alloc, 0x1b),
+            '\\' => try out.append(alloc, '\\'),
+            'x' => {
+                if (i + 2 >= s.len) return error.BadEscape;
+                try out.append(alloc, try std.fmt.parseInt(u8, s[i + 1 .. i + 3], 16));
+                i += 2;
+            },
+            else => return error.BadEscape,
+        }
+    }
+    return out.toOwnedSlice(alloc);
+}
+test "decodeEscapes covers the sequences send needs" {
+    const alloc = std.testing.allocator;
+    const got = try decodeEscapes(alloc, "q\\n\\e[A\\x03");
+    defer alloc.free(got);
+    try std.testing.expectEqualSlices(u8, "q\n\x1b[A\x03", got);
+    try std.testing.expectError(error.BadEscape, decodeEscapes(alloc, "\\q"));
+    // A dangling backslash is an escape the caller did not finish writing,
+    // and it is refused rather than passed through as a literal.
+    try std.testing.expectError(error.BadEscape, decodeEscapes(alloc, "ok\\"));
+}
+test "parseArgs verbs and flags" {
+    const a1 = [_][:0]const u8{ "muxa", "status" };
+    try std.testing.expectEqual(@FieldType(Opts, "verb").status, parseArgs(&a1).?.verb);
+    const a2 = [_][:0]const u8{ "muxa", "run", "--timeout", "5000", "make test" };
+    const o2 = parseArgs(&a2).?;
+    try std.testing.expectEqual(@as(u32, 5000), o2.timeout_ms);
+    try std.testing.expectEqualStrings("make test", o2.arg.?);
+    const a3 = [_][:0]const u8{ "muxa", "bogus" };
+    try std.testing.expectEqual(@as(?Opts, null), parseArgs(&a3));
+}
+test "parseArgs: -- hands the rest to the verb, flags and all" {
+    // Without the end-of-flags marker this is an unknown flag and the whole
+    // invocation is refused — the exact shape an agent sends when a key
+    // sequence starts with a dash.
+    const dashed = [_][:0]const u8{ "muxa", "send", "-n foo" };
+    try std.testing.expectEqual(@as(?Opts, null), parseArgs(&dashed));
+    const a = [_][:0]const u8{ "muxa", "send", "--settle", "50", "--", "-n foo" };
+    const o = parseArgs(&a).?;
+    try std.testing.expectEqual(@as(u32, 50), o.settle_ms);
+    try std.testing.expectEqualStrings("-n foo", o.arg.?);
+    // Past the marker, a flag spelling is just text — and a second
+    // positional is still one too many.
+    const flagish = [_][:0]const u8{ "muxa", "run", "--", "--timeout" };
+    try std.testing.expectEqualStrings("--timeout", parseArgs(&flagish).?.arg.?);
+    const two = [_][:0]const u8{ "muxa", "run", "--", "a", "b" };
+    try std.testing.expectEqual(@as(?Opts, null), parseArgs(&two));
+}
+test "parseArgs: --quic and --key, and the pairs that make no sense" {
+    const q = [_][:0]const u8{ "muxa", "status", "--quic", "10.0.0.2:4433" };
+    const oq = parseArgs(&q).?;
+    try std.testing.expectEqualStrings("10.0.0.2:4433", oq.quic.?);
+    // Not naming a key is not an error here: MUX_KEY_FILE and the XDG
+    // default are still to be tried, and parse may look at neither.
+    try std.testing.expectEqual(@as(?[]const u8, null), oq.key);
+    const k = [_][:0]const u8{ "muxa", "run", "--quic", "box:4433", "--key", "/k", "make test" };
+    const ok = parseArgs(&k).?;
+    try std.testing.expectEqualStrings("box:4433", ok.quic.?);
+    try std.testing.expectEqualStrings("/k", ok.key.?);
+    try std.testing.expectEqualStrings("make test", ok.arg.?);
+    // A flag at the end of argv with no value is refused, like every other
+    // value-taking flag this parser has.
+    const dangling_q = [_][:0]const u8{ "muxa", "status", "--quic" };
+    try std.testing.expectEqual(@as(?Opts, null), parseArgs(&dangling_q));
+    const dangling_k = [_][:0]const u8{ "muxa", "status", "--quic", "b:1", "--key" };
+    try std.testing.expectEqual(@as(?Opts, null), parseArgs(&dangling_k));
+    // Two transports named at once: which one an agent's frames went to
+    // would be this parser's private business, and it is not entitled to
+    // one — the same refusal `mux` spells as `.conflict`.
+    const both = [_][:0]const u8{ "muxa", "status", "--sock", "/tmp/s", "--quic", "b:1" };
+    try std.testing.expectEqual(@as(?Opts, null), parseArgs(&both));
+    // A key with nothing to authenticate to, refused exactly where muxd
+    // refuses it.
+    const lonely_key = [_][:0]const u8{ "muxa", "status", "--key", "/k" };
+    try std.testing.expectEqual(@as(?Opts, null), parseArgs(&lonely_key));
+    // Neither named is the ordinary local case and stays silent.
+    const neither = [_][:0]const u8{ "muxa", "status" };
+    try std.testing.expectEqual(@as(?[]const u8, null), parseArgs(&neither).?.quic);
+}
+/// A live QUIC connection plus everything a REDIAL of it needs. The dial
+/// coordinates are kept rather than re-derived because the reconnect below
+/// happens mid-verb, long after argv and the key file have been read: a
+/// second resolution could pick a different key (the file having been
+/// rotated under us) and would then fail the handshake for a reason that
+/// has nothing to do with why the first connection died.
+const Quic = struct {
+    cl: *quic_client.Client,
+    addr: std.net.Address,
+    key: quic_client.Key,
+    idle_ms: u32,
+    /// Wall-clock milliseconds the FIRST handshake took, which is this
+    /// client's only measurement of how far away the daemon is. `graceMs`
+    /// turns it into the await grace window; see there.
+    connect_ms: i64,
+    /// The one reconnect, spent or not. It lives HERE rather than on Conn
+    /// because only this arm can reconnect: a socket Conn carrying a
+    /// `reconnected` flag would be a field with no reachable true, and the
+    /// guard reading it would be re-establishing in code what the type can
+    /// state outright. (`session_exit` stays on Conn for the mirror
+    /// reason: both arms genuinely set it.)
+    reconnected: bool = false,
+};
+const Conn = struct {
+    /// Which transport carries the frames. The verbs above this line are
+    /// written once and know nothing about the difference — that is the
+    /// claim `--quic` makes, and this union is where it is kept.
+    link: union(enum) {
+        fd: std.posix.fd_t,
+        quic: Quic,
+    },
+    /// The allocator the transport itself works with: the QUIC arm's frame
+    /// staging and its redials. Distinct from the `alloc` awaitFrame takes,
+    /// which owns the frame handed BACK to the caller — one process, one
+    /// arena, so they are the same allocator today and separate in the
+    /// signature because they answer to different owners.
+    alloc: std.mem.Allocator,
+    /// The code from the `exit_status` frame that ended a wait, set the
+    /// moment awaitFrame returns error.SessionExited. The frame is the
+    /// session's last word and carries the only copy of the code, so it is
+    /// captured here rather than thrown away with the frame; callers read
+    /// it to turn the error into an answer.
+    session_exit: ?u8 = null,
+    /// Why the reconnect could not be made, set the moment a redial fails
+    /// — and set for the same reason `session_exit` is: the error that
+    /// ends the verb is `ConnectionLost`, which is the story's beginning,
+    /// while THIS is how it finished. An agent told only
+    /// `QuicHandshakeFailed` goes and checks its key; an agent told
+    /// `connection lost; reconnect failed: QuicHandshakeFailed` knows the
+    /// path tore mid-wait and the redial could not complete.
+    ///
+    /// An `@errorName`, so this borrows a static string and owns no
+    /// storage. See `waitFailDetail`, which composes the line.
+    reconnect_failure: ?[]const u8 = null,
+    fn open(alloc: std.mem.Allocator, sock_path: []const u8) !Conn {
+        const s = try std.net.connectUnixSocket(sock_path);
+        return .{ .link = .{ .fd = s.handle }, .alloc = alloc };
+    }
+    /// Dial a daemon's QUIC listener and wait out the handshake before
+    /// returning. The wait is not optional and not the caller's: `connect`
+    /// only creates state — the first flight has not been answered — and a
+    /// `send` on a connection with no stream yet accepts zero bytes and
+    /// says so by returning 0, which would surface as a frame that
+    /// silently never left. Same reason client.zig's quicTransport waits.
+    fn openQuic(
+        alloc: std.mem.Allocator,
+        addr: std.net.Address,
+        key: quic_client.Key,
+        idle_ms: u32,
+        deadline_ms: i64,
+    ) !Conn {
+        const started = std.time.milliTimestamp();
+        const cl = try quic_client.Client.connect(alloc, addr, key, idle_ms);
+        errdefer cl.deinit();
+        try waitReady(cl, deadline_ms);
+        return .{
+            .link = .{ .quic = .{
+                .cl = cl,
+                .addr = addr,
+                .key = key,
+                .idle_ms = idle_ms,
+                .connect_ms = elapsed(started),
+            } },
+            .alloc = alloc,
+        };
+    }
+    fn close(self: *Conn) void {
+        switch (self.link) {
+            .fd => |fd| std.posix.close(fd),
+            .quic => |q| q.cl.deinit(),
+        }
+    }
+    /// How much longer than the daemon this client waits for an await,
+    /// which over a network is a function of how far away the daemon is.
+    ///
+    /// The unix arm keeps the flat 2s (see await_grace_ms). The QUIC arm
+    /// adds nothing until four round trips of its own handshake exceed
+    /// that, which on a LAN or loopback is never and on a 200ms link is
+    /// most of a second: the daemon's timeout window opens when it READS
+    /// the request, a whole flight after this process started counting,
+    /// and closes a flight before the reply lands. Four, not two, because
+    /// the request and the reply are not the only flights in the trip —
+    /// the daemon may be settling a command when the timeout fires.
+    ///
+    /// Capped, because `connect_ms` is bounded only by the handshake wait:
+    /// a connection that took fifteen seconds to come up would otherwise
+    /// buy a minute of grace, and past this cap we are no longer waiting
+    /// for the daemon's answer but for a network that has already shown it
+    /// cannot carry one.
+    fn graceMs(self: *const Conn) i64 {
+        return switch (self.link) {
+            .fd => await_grace_ms,
+            .quic => |q| @min(grace_cap_ms, @max(await_grace_ms, 4 * q.connect_ms)),
+        };
+    }
+    /// `deadline_ms` is the caller's own bound, the same one it will wait
+    /// for the answer under. The socket arm ignores it — a local write
+    /// either takes the bytes or fails — and the QUIC arm gives it
+    /// precedence over `send_flush_ms`, so a verb asked for a 100ms answer
+    /// cannot spend five seconds getting its question out.
+    fn sendFrame(self: *Conn, t: proto.MsgType, payload: []const u8, deadline_ms: i64) !void {
+        switch (self.link) {
+            .fd => |fd| try proto.writeFrame(fd, t, payload),
+            .quic => try self.sendFrameQuic(t, payload, deadline_ms),
+        }
+    }
+    /// The frame's wire bytes into the egress ring, all of them.
+    ///
+    /// `send` takes what fits and reports how much (a bounded ring: the
+    /// caller holds the backlog), so a short take is not a failure and not
+    /// ignorable either — the tail is offered again once acks have made
+    /// room. muxa's frames are a handful of bytes against a 256KB ring, so
+    /// this loop is expected never to turn twice; it is here because the
+    /// alternative to looping is a frame that leaves half-written, which
+    /// the peer reads as a corrupt stream rather than as an error.
+    ///
+    /// Bounded by whichever comes first, the caller's deadline or
+    /// `send_flush_ms`: the caller's, so a send cannot overshoot the answer
+    /// it is part of, and the flush cap so that an UNBOUNDED caller
+    /// (`--timeout 0`) still cannot wait here forever.
+    fn sendFrameQuic(
+        self: *Conn,
+        t: proto.MsgType,
+        payload: []const u8,
+        deadline_ms: i64,
+    ) !void {
+        var buf: std.ArrayList(u8) = .empty;
+        defer buf.deinit(self.alloc);
+        try proto.appendFrame(&buf, self.alloc, t, payload);
+        const q = &self.link.quic;
+        const deadline = @min(deadline_ms, std.time.milliTimestamp() + send_flush_ms);
+        var off: usize = 0;
+        while (off < buf.items.len) {
+            if (q.cl.dead) return error.ConnectionLost;
+            off += q.cl.send(buf.items[off..]);
+            if (off == buf.items.len) return;
+            if (std.time.milliTimestamp() >= deadline) return error.SendStalled;
+            // The ring is full: only the peer's acks can empty it, and they
+            // arrive through pump. Polling first keeps this from spinning.
+            var fds = [_]std.posix.pollfd{
+                .{ .fd = q.cl.pollFd(), .events = std.posix.POLL.IN, .revents = 0 },
+            };
+            _ = std.posix.poll(&fds, q.cl.timeoutMs(50)) catch return error.ConnectionLost;
+            q.cl.pump();
+        }
+    }
+    /// Read frames until one of type `want` arrives (snapshots, deltas and
+    /// pushes stream past an attached client; skip what we did not ask
+    /// for). Bounded by `deadline_ms` wall time via poll.
+    ///
+    /// `exit_status` is the one skipped frame that ends the wait instead:
+    /// the reply we are waiting for is never coming, and the reason is an
+    /// answer — the session ran its last command — not a transport
+    /// failure. Callers get error.SessionExited plus `session_exit`.
+    ///
+    /// The returned frame is allocated from this Conn's own allocator, so
+    /// `frame.deinit` takes that one. Every caller was already passing it —
+    /// there is one allocator in this process — and asking for it made the
+    /// pairing look like a choice.
+    fn awaitFrame(self: *Conn, want: proto.MsgType, deadline_ms: i64) !proto.Frame {
+        return switch (self.link) {
+            .fd => self.awaitFrameFd(self.alloc, want, deadline_ms),
+            .quic => self.awaitFrameQuic(self.alloc, want, deadline_ms),
+        };
+    }
+    /// Debt, deliberately retained on THIS arm: only the wait is
+    /// deadline-bounded, not the read. Once poll says a frame has begun,
+    /// readFrame's readExact blocks until the whole payload lands, so a
+    /// peer that stalls mid-frame outlives the deadline. That is harmless
+    /// over a local socket, where the daemon writes whole frames at once
+    /// and a stall means a daemon that has stopped running rather than a
+    /// path that has stopped delivering — and buying it off would mean a
+    /// second partial-frame buffer for a case that cannot happen here.
+    /// The QUIC arm below, where a network IS under the transport, does
+    /// not have the luxury and does not take it.
+    fn awaitFrameFd(
+        self: *Conn,
+        alloc: std.mem.Allocator,
+        want: proto.MsgType,
+        deadline_ms: i64,
+    ) !proto.Frame {
+        const fd = self.link.fd;
+        while (true) {
+            const now = std.time.milliTimestamp();
+            if (now >= deadline_ms) return error.Timeout;
+            var fds = [_]std.posix.pollfd{
+                .{ .fd = fd, .events = std.posix.POLL.IN, .revents = 0 },
+            };
+            const n = try std.posix.poll(&fds, @intCast(@min(deadline_ms - now, 250)));
+            if (n == 0) continue;
+            const frame = try proto.readFrame(alloc, fd) orelse return error.DaemonGone;
+            if (frame.type == want) return frame;
+            defer frame.deinit(alloc);
+            if (frame.type == .exit_status) {
+                // A daemon that spelled the frame without a code still ends
+                // the session; null is the honest code, not 0.
+                self.session_exit = if (frame.payload.len >= 1) frame.payload[0] else null;
+                return error.SessionExited;
+            }
+        }
+    }
+    /// The same wait with a network under it, and the difference is that
+    /// NOTHING here blocks on the transport: a datagram carries whatever
+    /// arrived, whole frames or a third of one, so the frames are
+    /// delimited out of the client's inbound buffer and a partial tail
+    /// simply stays there until the rest lands. A daemon that stops
+    /// mid-frame costs this loop the deadline it was given and not a
+    /// second more.
+    ///
+    /// Every buffered frame is taken before the next poll — a datagram
+    /// routinely carries several, and the reply may be the second — and
+    /// `dead` is checked only once the buffer is empty, so bytes that
+    /// arrived before the connection died are still delivered.
+    fn awaitFrameQuic(
+        self: *Conn,
+        alloc: std.mem.Allocator,
+        want: proto.MsgType,
+        deadline_ms: i64,
+    ) !proto.Frame {
+        const q = &self.link.quic;
+        while (true) {
+            q.cl.pump();
+            while (try frameFrom(alloc, q.cl.inbound())) |got| {
+                q.cl.consume(got.consumed);
+                if (got.frame.type == want) return got.frame;
+                defer got.frame.deinit(alloc);
+                if (got.frame.type == .exit_status) {
+                    self.session_exit = if (got.frame.payload.len >= 1) got.frame.payload[0] else null;
+                    return error.SessionExited;
+                }
+            }
+            // Not `DaemonGone`: over a network the difference between "the
+            // daemon exited" and "the path to it went away" is not ours to
+            // claim, and the reconnect above only fires on this one.
+            if (q.cl.dead) return error.ConnectionLost;
+            const now = std.time.milliTimestamp();
+            if (now >= deadline_ms) return error.Timeout;
+            var fds = [_]std.posix.pollfd{
+                .{ .fd = q.cl.pollFd(), .events = std.posix.POLL.IN, .revents = 0 },
+            };
+            // Through timeoutMs, so ngtcp2's own timers — loss detection
+            // and, on a quiet await, the keepalive that keeps the idle
+            // timeout from firing under us — are serviced on schedule
+            // rather than whenever the daemon happens to say something.
+            const cap: i32 = @intCast(@min(deadline_ms - now, 250));
+            _ = std.posix.poll(&fds, q.cl.timeoutMs(cap)) catch return error.ConnectionLost;
+        }
+    }
+    /// Redial the same coordinates and hand the connection over. The old
+    /// client is torn down only once the new one is up, so a redial that
+    /// fails leaves this Conn holding a live (if dead-ended) client rather
+    /// than a freed one — `close` runs either way.
+    ///
+    /// `connect_ms` deliberately keeps the FIRST handshake's measurement
+    /// rather than taking this one's. Nothing reads `graceMs` after this
+    /// point — the await it belongs to already has its deadline, and the
+    /// re-issue continues that same deadline — so refreshing it would be
+    /// bookkeeping with no reader, and the reader it might one day have
+    /// wants the distance to the daemon, not the cost of a redial made
+    /// while the path was still coming back.
+    fn reconnect(self: *Conn, deadline_ms: i64) !void {
+        const q = &self.link.quic;
+        const cl = try quic_client.Client.connect(self.alloc, q.addr, q.key, q.idle_ms);
+        errdefer cl.deinit();
+        try waitReady(cl, deadline_ms);
+        q.cl.deinit();
+        q.cl = cl;
+        q.reconnected = true;
+    }
+};
+/// One OWNED frame delimited out of `buf`, and how many bytes of it that
+/// took. The arithmetic is `proto.delimitFrame`'s — the same walk the
+/// daemon does over the same wire from the other end — and what this adds
+/// is the copy: the caller consumes the bytes out of the client's inbound
+/// buffer immediately, so a payload still pointing into it would be a
+/// slice into memory about to be shifted.
+fn frameFrom(
+    alloc: std.mem.Allocator,
+    buf: []const u8,
+) !?struct { frame: proto.Frame, consumed: usize } {
+    const d = try proto.delimitFrame(buf) orelse return null;
+    const payload = try alloc.alloc(u8, d.payload.len);
+    errdefer alloc.free(payload);
+    @memcpy(payload, d.payload);
+    return .{
+        .frame = .{ .type = d.type, .payload = payload },
+        .consumed = d.consumed,
+    };
+}
+test "frameFrom: a partial tail is not a frame and not an error" {
+    const alloc = std.testing.allocator;
+    // Nothing, and less than a header: the two shapes a datagram that
+    // carried the start of a frame leaves behind.
+    try std.testing.expect(try frameFrom(alloc, "") == null);
+    try std.testing.expect(try frameFrom(alloc, &[_]u8{ 0x0a, 1, 0 }) == null);
+    // A whole header whose payload is still in flight. This is the case a
+    // blocking read would have sat on: the length is known, the bytes are
+    // not here, and the answer is to wait rather than to read.
+    const partial = [_]u8{ @intFromEnum(proto.MsgType.input), 4, 0, 0, 0, 'a', 'b' };
+    try std.testing.expect(try frameFrom(alloc, &partial) == null);
+    // The same bytes, completed.
+    const whole = [_]u8{ @intFromEnum(proto.MsgType.input), 4, 0, 0, 0, 'a', 'b', 'c', 'd' };
+    const got = (try frameFrom(alloc, &whole)).?;
+    defer got.frame.deinit(alloc);
+    try std.testing.expectEqual(proto.MsgType.input, got.frame.type);
+    try std.testing.expectEqualStrings("abcd", got.frame.payload);
+    try std.testing.expectEqual(@as(usize, 9), got.consumed);
+}
+test "frameFrom: two frames in one buffer, walked by consumed" {
+    const alloc = std.testing.allocator;
+    // What a single datagram routinely carries: the push we skip and the
+    // reply we asked for. A walk that stopped after one would leave the
+    // answer sitting in the buffer while the deadline ran out.
+    var buf: std.ArrayList(u8) = .empty;
+    defer buf.deinit(alloc);
+    try proto.appendFrame(&buf, alloc, .pty_mode, &[_]u8{0});
+    try proto.appendFrame(&buf, alloc, .status_reply, "xy");
+    const first = (try frameFrom(alloc, buf.items)).?;
+    defer first.frame.deinit(alloc);
+    try std.testing.expectEqual(proto.MsgType.pty_mode, first.frame.type);
+    const second = (try frameFrom(alloc, buf.items[first.consumed..])).?;
+    defer second.frame.deinit(alloc);
+    try std.testing.expectEqual(proto.MsgType.status_reply, second.frame.type);
+    try std.testing.expectEqualStrings("xy", second.frame.payload);
+    try std.testing.expectEqual(buf.items.len, first.consumed + second.consumed);
+    // An empty payload is a frame like any other — `status_req` and
+    // `detach` are nothing else — and must not read as "nothing yet".
+    var empty: std.ArrayList(u8) = .empty;
+    defer empty.deinit(alloc);
+    try proto.appendFrame(&empty, alloc, .detach, "");
+    const none = (try frameFrom(alloc, empty.items)).?;
+    defer none.frame.deinit(alloc);
+    try std.testing.expectEqual(@as(usize, proto.frame_header_len), none.consumed);
+}
+test "frameFrom: a length no frame can carry is refused, not allocated" {
+    const alloc = std.testing.allocator;
+    // The peer chose this number. Reading on would mean allocating against
+    // it; the daemon's own walk refuses the same bound the same way.
+    var hdr: [proto.frame_header_len]u8 = undefined;
+    hdr[0] = @intFromEnum(proto.MsgType.input);
+    std.mem.writeInt(u32, hdr[1..5], proto.max_payload + 1, .little);
+    try std.testing.expectError(error.FrameTooLarge, frameFrom(alloc, &hdr));
+}
+test "graceMs: flat over a socket, RTT-derived over QUIC, and capped" {
+    const alloc = std.testing.allocator;
+    const local = Conn{ .link = .{ .fd = -1 }, .alloc = alloc };
+    try std.testing.expectEqual(@as(i64, 2_000), local.graceMs());
+    // The derivation is 4x the handshake, and it only ever WIDENS the
+    // window: a loopback or LAN daemon keeps the flat 2s.
+    // No client: the window is a function of the measurement, not of the
+    // connection, and nothing here may touch one.
+    var far = Conn{
+        .link = .{ .quic = .{
+            .cl = undefined,
+            .addr = undefined,
+            .key = undefined,
+            .idle_ms = 0,
+            .connect_ms = 1,
+        } },
+        .alloc = alloc,
+    };
+    try std.testing.expectEqual(@as(i64, 2_000), far.graceMs());
+    // A 300ms handshake — a real intercontinental link — buys 1.2s, which
+    // is still under the floor, so the first number that moves it is a
+    // handshake past half a second.
+    far.link.quic.connect_ms = 300;
+    try std.testing.expectEqual(@as(i64, 2_000), far.graceMs());
+    far.link.quic.connect_ms = 900;
+    try std.testing.expectEqual(@as(i64, 3_600), far.graceMs());
+    // And it stops widening: past the cap we are no longer waiting on a
+    // daemon, we are waiting on a network that has already failed to carry
+    // an answer.
+    far.link.quic.connect_ms = 60_000;
+    try std.testing.expectEqual(@as(i64, 30_000), far.graceMs());
+}
+/// Drive a fresh connection until it can carry bytes, or give up.
+///
+/// A refused port ends this early — quic_client turns the ICMP unreachable
+/// into `dead` — so the common mistake (no daemon on that port) costs
+/// milliseconds. A blackholed one produces no error at all, and there the
+/// deadline is the only thing that ends the wait; even an unbounded one
+/// (`--timeout 0`) terminates, because the connection's own idle timeout
+/// kills it after `idle_ms`.
+fn waitReady(cl: *quic_client.Client, deadline_ms: i64) !void {
+    while (true) {
+        cl.pump();
+        if (cl.isReady()) return;
+        if (cl.dead) return error.QuicHandshakeFailed;
+        const now = std.time.milliTimestamp();
+        if (now >= deadline_ms) return error.Timeout;
+        var fds = [_]std.posix.pollfd{
+            .{ .fd = cl.pollFd(), .events = std.posix.POLL.IN, .revents = 0 },
+        };
+        const cap: i32 = @intCast(@min(deadline_ms - now, 50));
+        _ = std.posix.poll(&fds, cl.timeoutMs(cap)) catch return error.QuicHandshakeFailed;
+    }
+}
+test "reconnect: redials the same coordinates, and a dead port is a fast no" {
+    const alloc = std.testing.allocator;
+    // 127.0.0.1:1, where nothing listens: the refusal is REAL — an ICMP
+    // unreachable comes back and quic_client acts on it — which is what
+    // lets this exercise the whole redial path (dial, handshake wait,
+    // verdict) in a couple of loopback round trips instead of a timeout.
+    const addr = try std.net.Address.parseIp("127.0.0.1", 1);
+    const key: quic_client.Key = .{ .bytes = [_]u8{7} ** quic_client.key_len };
+    // The dial that stands in for the connection this client had before
+    // the network went away. It dies for the same reason the redial will,
+    // which is fine: what is under test is what `reconnect` DOES, and it
+    // does the same thing to a connection that died at second 30.
+    const deadline = std.time.milliTimestamp() + 2_000;
+    var conn = Conn{
+        .link = .{ .quic = .{
+            .cl = try quic_client.Client.connect(alloc, addr, key, 1_000),
+            .addr = addr,
+            .key = key,
+            .idle_ms = 1_000,
+            .connect_ms = 0,
+        } },
+        .alloc = alloc,
+    };
+    defer conn.close();
+    const t0 = std.time.milliTimestamp();
+    if (conn.reconnect(deadline)) |_| {
+        // Nothing listens there; a redial that reported success would mean
+        // the handshake wait had stopped being a wait for a handshake.
+        return error.TestUnexpectedResult;
+    } else |redial| {
+        try std.testing.expectEqual(error.QuicHandshakeFailed, redial);
+        // The bookkeeping awaitReissuing does, done here with the real
+        // error the real redial produced, so the sentence below is the one
+        // an agent gets rather than one this test made up.
+        conn.reconnect_failure = @errorName(redial);
+    }
+    // Fast, because the port refused rather than went quiet. A redial that
+    // swallowed the refusal would spend the whole 2s here — and in the
+    // field it would spend the agent's remaining deadline.
+    try std.testing.expect(std.time.milliTimestamp() - t0 < 1_000);
+    // The whole story, in the order it happened: the wait died because the
+    // path tore, and it stayed dead because the redial could not complete.
+    // An agent told only the second half goes and checks its key.
+    var buf: [128]u8 = undefined;
+    try std.testing.expectEqualStrings(
+        "connection lost; reconnect failed: QuicHandshakeFailed",
+        waitFailDetail(&buf, &conn, error.ConnectionLost),
+    );
+    // A redial that failed is not a reconnect spent — but it is also not a
+    // Conn holding a freed client: the old one is torn down only once a
+    // new one is up, so the close above is safe on this path.
+    try std.testing.expect(!conn.link.quic.reconnected);
+}
+test "waitFailDetail: only a lost connection gets a sentence; the rest keep their names" {
+    const alloc = std.testing.allocator;
+    var buf: [128]u8 = undefined;
+    // Every other failure is untouched — the socket arm's reports must
+    // read exactly as they did before there was a QUIC arm.
+    const local = Conn{ .link = .{ .fd = -1 }, .alloc = alloc };
+    try std.testing.expectEqualStrings("Timeout", waitFailDetail(&buf, &local, error.Timeout));
+    try std.testing.expectEqualStrings("DaemonGone", waitFailDetail(&buf, &local, error.DaemonGone));
+    // A tear with the one reconnect still unspent (nothing tried yet).
+    var far = Conn{
+        .link = .{ .quic = .{
+            .cl = undefined,
+            .addr = undefined,
+            .key = undefined,
+            .idle_ms = 0,
+            .connect_ms = 0,
+        } },
+        .alloc = alloc,
+    };
+    try std.testing.expectEqualStrings("connection lost", waitFailDetail(&buf, &far, error.ConnectionLost));
+    // A tear AFTER a reconnect that worked: the second one inside a single
+    // wait, which is a different thing to be told than the first — the
+    // client did reconnect, and the path tore again anyway.
+    far.link.quic.reconnected = true;
+    try std.testing.expectEqualStrings(
+        "connection lost again, after the one reconnect",
+        waitFailDetail(&buf, &far, error.ConnectionLost),
+    );
+    // A buffer too small to hold the composed line drops the reason rather
+    // than the finding: the detail is the agent's only account of this.
+    far.reconnect_failure = "QuicHandshakeFailed";
+    var tiny: [8]u8 = undefined;
+    try std.testing.expectEqualStrings(
+        "connection lost; reconnect failed",
+        waitFailDetail(&tiny, &far, error.ConnectionLost),
+    );
+}
+test "awaitFrame ends a wait on exit_status, keeping the code" {
+    const alloc = std.testing.allocator;
+    // A pipe stands in for the daemon: awaitFrame polls and reads an fd and
+    // asks nothing else of it.
+    const pipe = try std.posix.pipe();
+    defer std.posix.close(pipe[0]);
+    defer std.posix.close(pipe[1]);
+    var conn = Conn{ .link = .{ .fd = pipe[0] }, .alloc = alloc };
+    // A push to skip on the way, then the session's last word. The reply
+    // this wait asked for is never coming, and the code is the answer.
+    try proto.writeFrame(pipe[1], .pty_mode, &[_]u8{0});
+    try proto.writeFrame(pipe[1], .exit_status, &[_]u8{5});
+    try std.testing.expectError(
+        error.SessionExited,
+        conn.awaitFrame(.status_reply, std.time.milliTimestamp() + 2000),
+    );
+    try std.testing.expectEqual(@as(?u8, 5), conn.session_exit);
+    // ...and it is spelled as a session ending, not as a command's code.
+    var out: std.ArrayList(u8) = .empty;
+    defer out.deinit(alloc);
+    try printSessionEnded(out.writer(alloc), conn.session_exit, 42);
+    try std.testing.expectEqualStrings(
+        "{\"reason\":\"session_ended\",\"exit_code\":5,\"duration_ms\":42}\n",
+        out.items,
+    );
+}
+/// Every failure exit goes through here, so stdout carries one JSON object
+/// whatever went wrong — a driving agent parses the same shape on both
+/// paths instead of switching on exit code first.
+fn fail(msg: []const u8, detail: []const u8) u8 {
+    var buf: [2048]u8 = undefined;
+    var fbs = std.io.fixedBufferStream(&buf);
+    writeError(fbs.writer(), msg, detail) catch {
+        // The message did not fit. Still JSON, still one line.
+        proto.writeAllFd(std.posix.STDOUT_FILENO, "{\"error\":\"failure too long to report\"}\n") catch {};
+        return 1;
+    };
+    proto.writeAllFd(std.posix.STDOUT_FILENO, fbs.getWritten()) catch {};
+    return 1;
+}
+/// `fail` for a message whose verb prefix is only known at runtime, which
+/// is every failure in the shared await/run pipeline. Produces exactly the
+/// `"<verb>: <what>"` the two verbs printed when they were written out
+/// separately; a message too long to prefix falls back to the unprefixed
+/// one rather than losing the failure.
+fn failAs(who: []const u8, msg: []const u8, detail: []const u8) u8 {
+    var buf: [256]u8 = undefined;
+    const joined = std.fmt.bufPrint(&buf, "{s}: {s}", .{ who, msg }) catch msg;
+    return fail(joined, detail);
+}
+fn writeError(writer: anytype, msg: []const u8, detail: []const u8) !void {
+    try writer.writeAll("{\"error\":");
+    try jsonEscape(writer, msg);
+    try writer.writeAll(",\"detail\":");
+    try jsonEscape(writer, detail);
+    try writer.writeAll("}\n");
+}
+/// The wall-clock instant a round trip gives up at. `--timeout 0` means
+/// "no bound at all" everywhere else in this protocol (AwaitReq spells it
+/// out), so it means that here too — the alternative reading, a deadline
+/// already in the past, would make `--timeout 0` fail instantly instead of
+/// waiting forever, which is the opposite of what it asks for.
+fn deadlineFor(timeout_ms: u32) i64 {
+    if (timeout_ms == 0) return std.math.maxInt(i64);
+    return std.time.milliTimestamp() + timeout_ms;
+}
+/// The session ended under us: JSON, like every other outcome, but on the
+/// failure path — the verb that asked (status, capture, send) has no answer
+/// to give. `run` and `await` do have one and print it themselves.
+fn failSessionEnded(code: ?u8) u8 {
+    var buf: [192]u8 = undefined;
+    var fbs = std.io.fixedBufferStream(&buf);
+    writeSessionEndedError(fbs.writer(), code) catch return 1;
+    proto.writeAllFd(std.posix.STDOUT_FILENO, fbs.getWritten()) catch {};
+    return 1;
+}
+/// `detail` is here because every other failure has one: an agent that
+/// reads `.detail` on any exit-1 must never meet a missing key, and one
+/// verb quietly dropping it is exactly the shape a driver hits in the
+/// field and not in a test. `exit_code` is the machine field; the detail
+/// says the same thing in the prose the other failures use.
+fn writeSessionEndedError(writer: anytype, code: ?u8) !void {
+    try writer.writeAll("{\"error\":\"session ended\",\"detail\":");
+    if (code) |c| {
+        var buf: [40]u8 = undefined;
+        try jsonEscape(writer, try std.fmt.bufPrint(&buf, "shell exited with {d}", .{c}));
+    } else {
+        try jsonEscape(writer, "shell exited without reporting a code");
+    }
+    try writer.writeAll(",\"exit_code\":");
+    try writeExitCode(writer, code);
+    try writer.writeAll("}\n");
+}
+test "the session-ended failure keeps the error+detail shape every failure has" {
+    var buf: [192]u8 = undefined;
+    var fbs = std.io.fixedBufferStream(&buf);
+    try writeSessionEndedError(fbs.writer(), 5);
+    try std.testing.expectEqualStrings(
+        "{\"error\":\"session ended\",\"detail\":\"shell exited with 5\",\"exit_code\":5}\n",
+        fbs.getWritten(),
+    );
+    // No code is still a detail, never a missing key.
+    var none = std.io.fixedBufferStream(&buf);
+    try writeSessionEndedError(none.writer(), null);
+    try std.testing.expect(std.mem.indexOf(u8, none.getWritten(), "\"detail\":\"shell exited without") != null);
+    try std.testing.expect(std.mem.indexOf(u8, none.getWritten(), "\"exit_code\":null") != null);
+}
+pub fn main() !u8 {
+    var arena_state = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+    defer arena_state.deinit();
+    const alloc = arena_state.allocator();
+    const args = try std.process.argsAlloc(alloc);
+    const o = parseArgs(args) orelse {
+        // Usage is diagnostic, so it goes to stderr: stdout stays strictly
+        // one JSON object per invocation, even on the argument-error path.
+        proto.writeAllFd(std.posix.STDERR_FILENO, usage) catch {};
+        return 2;
+    };
+    // Started BEFORE the connect, not after: over QUIC the handshake is
+    // part of the round trip the caller bounded, and a `--timeout` that
+    // began counting only once the connection was up would promise
+    // something different on the two transports. Over a unix socket the
+    // connect is a syscall, so this moves the instant by microseconds.
+    const deadline = deadlineFor(o.timeout_ms);
+    if (o.quic) |host_port| {
+        var conn = switch (openQuicConn(alloc, o, host_port, deadline)) {
+            .conn => |c| c,
+            .exit => |code| return code,
+        };
+        defer conn.close();
+        return dispatch(alloc, &conn, o, deadline);
+    }
+    const sock_path = if (o.sock) |s| s else try sockpath.defaultSockPath(alloc);
+    // Refused by name, before connecting: connect would bounce a too-long
+    // path off the kernel with a generic error, and the path is the whole
+    // story. Every binary owes this check in its own words (sockpath).
+    if (sock_path.len > sockpath.max_sun_path) {
+        var buf: [64]u8 = undefined;
+        const detail = std.fmt.bufPrint(
+            &buf,
+            "{d} bytes, max {d}",
+            .{ sock_path.len, sockpath.max_sun_path },
+        ) catch "too long";
+        return fail("socket path too long", detail);
+    }
+    var conn = Conn.open(alloc, sock_path) catch |e| {
+        // The path goes in the detail: a muxa pointed at the wrong socket
+        // is this binary's likeliest field failure, and an agent reading
+        // "FileNotFound" alone cannot tell which path it was that missed.
+        var buf: [256]u8 = undefined;
+        const detail = std.fmt.bufPrint(&buf, "{s}: {s}", .{ sock_path, @errorName(e) }) catch
+            @errorName(e);
+        return fail("cannot connect to the daemon", detail);
+    };
+    defer conn.close();
+    return dispatch(alloc, &conn, o, deadline);
+}
+/// The verbs, once. Both transports arrive here with a Conn and nothing
+/// else that distinguishes them, which is the property `--quic` is selling.
+fn dispatch(alloc: std.mem.Allocator, conn: *Conn, o: Opts, deadline: i64) !u8 {
+    return switch (o.verb) {
+        .status => verbStatus(alloc, conn, deadline),
+        .capture => verbCapture(alloc, conn, o.vt, deadline),
+        .send => verbSend(alloc, conn, o.arg, deadline),
+        // The one thing `run` needs that `await` does not, checked here so
+        // the shared pipeline below can read `cmdline == null` as "this is
+        // an await" rather than as "a run that was spelled wrong".
+        .run => if (o.arg) |cmdline|
+            awaitVerb(alloc, conn, o, deadline, cmdline)
+        else
+            fail("run: needs CMDLINE", ""),
+        .@"await" => awaitVerb(alloc, conn, o, deadline, null),
+    };
+}
+/// A QUIC transport, or the exit code standing in for the reason there is
+/// not one. Every refusal here goes through `fail`, so a dial that never
+/// happened prints the same one-JSON-object-on-stdout shape as a verb that
+/// ran — an agent parses one thing whatever went wrong.
+const Opened = union(enum) { conn: Conn, exit: u8 };
+fn openQuicConn(
+    alloc: std.mem.Allocator,
+    o: Opts,
+    host_port: []const u8,
+    deadline: i64,
+) Opened {
+    // `--key`, then `$MUX_KEY_FILE`, then the XDG default if it exists.
+    // The order is not spelled here on purpose: xdg owns it, muxd and mux
+    // read it from the same two functions, and a third copy is how two
+    // binaries end up authenticating with different keys.
+    const res = xdg.resolveKeyPath(alloc, xdg.pickKey(o.key, std.posix.getenv("MUX_KEY_FILE"))) catch |e|
+        return .{ .exit = fail("quic: cannot resolve a key path", @errorName(e)) };
+    const key_path = switch (res) {
+        .given, .default => |p| p,
+        // The path is the detail because it is the actionable half: the
+        // agent (or the human reading its log) needs to know which file
+        // `muxd keygen` was supposed to have written.
+        .missing => |p| return .{ .exit = fail(
+            "quic: no key: pass --key, set MUX_KEY_FILE, or run `muxd keygen`",
+            p,
+        ) },
+    };
+    const key = quic_client.Key.load(key_path) catch |e| {
+        // The daemon's words for a key the daemon would also refuse —
+        // including the group/other-readable refusal, which this binary
+        // gets for free by loading the key the same way.
+        var buf: [quic_client.key_refusal_len]u8 = undefined;
+        return .{ .exit = fail("quic: unusable key", quic_client.keyRefusalBody(&buf, e, key_path)) };
+    };
+    const addr = quic.parseAddr(alloc, host_port) catch |e| {
+        var buf: [512]u8 = undefined;
+        const detail = std.fmt.bufPrint(&buf, "{s}: {s}", .{ host_port, @errorName(e) }) catch
+            @errorName(e);
+        return .{ .exit = fail("quic: cannot read HOST:PORT", detail) };
+    };
+    const conn = Conn.openQuic(alloc, addr, key, quic_client.default_idle_ms, deadline) catch |e| {
+        var buf: [512]u8 = undefined;
+        const detail = std.fmt.bufPrint(&buf, "{s}: {s}", .{ host_port, @errorName(e) }) catch
+            @errorName(e);
+        return .{ .exit = fail("cannot connect to the daemon", detail) };
+    };
+    return .{ .conn = conn };
+}
+fn verbStatus(alloc: std.mem.Allocator, conn: *Conn, deadline: i64) !u8 {
+    conn.sendFrame(.status_req, "", deadline) catch |e| return fail("status: send failed", @errorName(e));
+    const frame = conn.awaitFrame(.status_reply, deadline) catch |e| switch (e) {
+        error.SessionExited => return failSessionEnded(conn.session_exit),
+        else => return fail("status: no reply", @errorName(e)),
+    };
+    defer frame.deinit(alloc);
+    const st = proto.decodeStatusReply(frame.payload) catch |e|
+        return fail("status: bad reply", @errorName(e));
+    var out: std.ArrayList(u8) = .empty;
+    defer out.deinit(alloc);
+    try printStatus(out.writer(alloc), st);
+    proto.writeAllFd(std.posix.STDOUT_FILENO, out.items) catch {};
+    return 0;
+}
+/// A command that has not returned — or one whose mechanism cannot know a
+/// code — has no exit code, and JSON null is the honest spelling: 0 would
+/// read as "succeeded".
+fn writeExitCode(writer: anytype, code: ?u8) !void {
+    if (code) |c| {
+        try writer.print("{d}", .{c});
+    } else {
+        try writer.writeAll("null");
+    }
+}
+/// The five CmdState fields `status` and `await`/`run` both publish, in the
+/// one order both have always used. Written as a bare fragment — no braces,
+/// no leading or trailing comma — because the two verbs nest it
+/// differently: `status` puts it inside a `"cmd"` object and follows it
+/// with the seq, while `await` inlines it at the top level and follows it
+/// with the duration. Each verb keeps its own envelope; what they stopped
+/// keeping is a second spelling of the fields inside it.
+fn writeCmdFields(writer: anytype, st: proto.CmdState) !void {
+    try writer.writeAll("\"phase\":");
+    try jsonEscape(writer, @tagName(st.phase));
+    try writer.writeAll(",\"mechanism\":");
+    try jsonEscape(writer, @tagName(st.mechanism));
+    try writer.writeAll(",\"exit_code\":");
+    try writeExitCode(writer, st.exit_code);
+    try writer.print(",\"start_row\":{d},\"end_row\":{d}", .{ st.start_row, st.end_row });
+}
+fn printStatus(writer: anytype, st: proto.StatusReply) !void {
+    try writer.print(
+        "{{\"cols\":{d},\"rows\":{d},\"cursor\":{{\"x\":{d},\"y\":{d}}}," ++
+            "\"history_rows\":{d},\"alt_screen\":{},\"icanon\":{},\"echo\":{},\"cmd\":{{",
+        .{ st.cols, st.rows, st.cursor_x, st.cursor_y, st.history_rows, st.alt_screen, st.mode.icanon, st.mode.echo },
+    );
+    try writeCmdFields(writer, st.cmd);
+    // The watermark, and only `status` carries it: this is the number an
+    // agent feeds back as `since_seq`, which is why `await` does not print
+    // one (see proto.CmdState.seq).
+    try writer.print(",\"seq\":{d}}}}}\n", .{st.cmd.seq});
+}
+test "printStatus spells a pending exit code as JSON null" {
+    var buf: [512]u8 = undefined;
+    var fbs = std.io.fixedBufferStream(&buf);
+    try printStatus(fbs.writer(), .{
+        .cols = 80,
+        .rows = 24,
+        .cursor_x = 1,
+        .cursor_y = 2,
+        .history_rows = 7,
+        .alt_screen = false,
+        .mode = .{ .icanon = true, .echo = true },
+        .cmd = .{ .phase = .running, .mechanism = .marks, .exit_code = null, .start_row = 3, .end_row = 4, .seq = 9 },
+    });
+    // The whole object, byte for byte, not a handful of substrings: this is
+    // muxa's published contract with an agent's JSON parser, and the fields
+    // it shares with `await` are written by a helper both verbs call — a
+    // pin on the parts cannot see a comma or a nesting level move.
+    try std.testing.expectEqualStrings(
+        "{\"cols\":80,\"rows\":24,\"cursor\":{\"x\":1,\"y\":2},\"history_rows\":7," ++
+            "\"alt_screen\":false,\"icanon\":true,\"echo\":true," ++
+            "\"cmd\":{\"phase\":\"running\",\"mechanism\":\"marks\",\"exit_code\":null," ++
+            "\"start_row\":3,\"end_row\":4,\"seq\":9}}\n",
+        fbs.getWritten(),
+    );
+}
+fn verbCapture(alloc: std.mem.Allocator, conn: *Conn, vt: bool, deadline: i64) !u8 {
+    const payload = [_]u8{if (vt) 1 else 0};
+    conn.sendFrame(.debug_dump, &payload, deadline) catch |e| return fail("capture: send failed", @errorName(e));
+    const frame = conn.awaitFrame(.dump_reply, deadline) catch |e| switch (e) {
+        error.SessionExited => return failSessionEnded(conn.session_exit),
+        else => return fail("capture: no reply", @errorName(e)),
+    };
+    defer frame.deinit(alloc);
+    var out: std.ArrayList(u8) = .empty;
+    defer out.deinit(alloc);
+    const writer = out.writer(alloc);
+    try writer.writeAll("{\"grid\":");
+    try jsonEscape(writer, frame.payload);
+    try writer.writeAll("}\n");
+    proto.writeAllFd(std.posix.STDOUT_FILENO, out.items) catch {};
+    return 0;
+}
+/// Join the session claiming NO grid. applySize refuses anything under 2,
+/// so the slot stays 0x0 and makes no claim in claimGrid: the human's
+/// terminal must never be resized because an agent connected.
+fn attachZero(conn: *Conn, deadline: i64) !void {
+    try conn.sendFrame(.attach, &proto.encodeAttach(0, 0, 0, 0), deadline);
+}
+fn verbSend(alloc: std.mem.Allocator, conn: *Conn, arg: ?[]const u8, deadline: i64) !u8 {
+    const spec = arg orelse return fail("send: needs BYTES", "");
+    const bytes = decodeEscapes(alloc, spec) catch |e| return fail("send: bad escape", @errorName(e));
+    defer alloc.free(bytes);
+    attachZero(conn, deadline) catch |e| return fail("send: attach failed", @errorName(e));
+    conn.sendFrame(.input, bytes, deadline) catch |e| return fail("send: input failed", @errorName(e));
+    // Write-and-close LOSES the input, and not as a rare race: attaching
+    // queues a snapshot, and the daemon flushes a client's pending bytes
+    // BEFORE it reads that client (server.zig's poll arm). Closing straight
+    // after the write means the flush hits EPIPE, the daemon drops us, and
+    // the input frame is discarded still unread. Measured: closing at once
+    // never lands, while any delay or drain always does.
+    //
+    // So the round trip is the acknowledgement. Frames are served in stream
+    // order, so a status_reply is proof the daemon has already read PAST the
+    // input frame and fed it to the pty; awaitFrame skips the snapshot and
+    // the pushes on the way, which is what keeps the socket drained enough
+    // for that flush to succeed. Nothing is done with the reply — its
+    // arrival is the whole content.
+    conn.sendFrame(.status_req, "", deadline) catch |e| return fail("send: ack request failed", @errorName(e));
+    const ack = conn.awaitFrame(.status_reply, deadline) catch |e| switch (e) {
+        // The bytes we sent ended the session (`exit\n`). Reported as the
+        // session's death rather than as "sent", because this verb's answer
+        // is about the send and there is no longer a session to have sent
+        // to — an agent that wants the death to be an ANSWER runs `run`.
+        error.SessionExited => return failSessionEnded(conn.session_exit),
+        else => return fail("send: daemon never acknowledged the input", @errorName(e)),
+    };
+    ack.deinit(alloc);
+    conn.sendFrame(.detach, "", deadline) catch |e| return fail("send: detach failed", @errorName(e));
+    proto.writeAllFd(std.posix.STDOUT_FILENO, "{\"sent\":true}\n") catch {};
+    return 0;
+}
+/// How much longer than the daemon this client is willing to wait.
+///
+/// Load-bearing: the daemon starts its own `timeout_ms` window when it
+/// READS the await_req, which is already later than the instant this
+/// process started counting. Waiting exactly `timeout_ms` here would lose
+/// that race every single time, and every timeout would surface as
+/// `{"error":"await: no reply"}` instead of the structured
+/// `{"reason":"timeout"}` with exit 3 that the agent is meant to read.
+const await_grace_ms = 2_000;
+/// The ceiling on the QUIC arm's derived grace (Conn.graceMs), and the
+/// reason it has one is that `connect_ms` has no bound of its own worth
+/// multiplying by four.
+const grace_cap_ms = 30_000;
+/// How long `sendFrameQuic` will keep offering a frame's tail to a full
+/// egress ring before giving up on it. Reaching this means the peer has
+/// stopped acknowledging 256KB of backlog, which is a dead connection
+/// wearing a different hat — but a bound is what keeps it from being an
+/// unbounded wait inside a call that has no deadline of its own.
+const send_flush_ms = 5_000;
+/// The span fetch gets its own window rather than the tail of the run's: a
+/// command that returned in the last millisecond of `--timeout` still has a
+/// transcript worth having, and this round trip is a local read that either
+/// answers promptly or is not coming.
+const span_fetch_ms = 2_000;
+/// Ask to be told when the session next comes to rest, and wait for it.
+fn doAwait(
+    alloc: std.mem.Allocator,
+    conn: *Conn,
+    o: Opts,
+    since_seq: u64,
+    deadline: i64,
+) !proto.AwaitReply {
+    try conn.sendFrame(.await_req, &proto.encodeAwaitReq(.{
+        .since_seq = since_seq,
+        .settle_ms = o.settle_ms,
+        .timeout_ms = o.timeout_ms,
+    }), deadline);
+    const frame = try conn.awaitFrame(.await_reply, deadline);
+    defer frame.deinit(alloc);
+    return try proto.decodeAwaitReply(frame.payload);
+}
+/// The await, plus the ONE reconnect this client is willing to spend on it.
+///
+/// A wait is the only round trip long enough for a network to die under —
+/// a status round trip is over in a millisecond, a `run` on a build is not
+/// — and losing it costs an agent the whole command it was watching, so
+/// this is the one place a transport failure is retried rather than
+/// reported. What makes the retry safe rather than a second command is
+/// `since_seq`: the request is a question about a watermark ("tell me
+/// about a return newer than this"), so re-asking it after a reconnect is
+/// the SAME question and the daemon answers it identically whether or not
+/// it saw the first one. The server's own tests pin that idempotency.
+///
+/// Three things are deliberately not reset:
+///
+///   * the deadline, which is the caller's whole bound and continues
+///     across the reconnect — a redial that ate four seconds has spent
+///     four seconds of the wait, not bought a fresh one;
+///   * `since_seq`, for the reason above — re-reading the watermark from
+///     the new connection would move it past a return that had happened
+///     while we were disconnected, and the await would then sit waiting
+///     for one that already went by;
+///   * the attach, which IS re-sent, at 0x0 like every other attach this
+///     binary makes: the daemon dropped our old client slot with the
+///     connection and would have no session to answer about otherwise.
+///
+/// Once, and once per process rather than per await: a loop here would be
+/// a client that hides a daemon that is gone, and the agent driving it
+/// asked a question that deserves an answer within the deadline it named.
+///
+/// What is re-sent is the attach and the await_req, and NOTHING else —
+/// specifically never `run`'s input. That is what keeps this at-most-once
+/// rather than at-least-once: if the command line was lost with the
+/// connection, the re-issued await finds no return, and the agent is told
+/// `timeout` — which is true and checkable — instead of the shell running
+/// `make deploy` a second time because a client decided to be helpful.
+/// A wait may be repeated because asking twice changes nothing; an input
+/// may not, because it changes everything.
+///
+/// `ConnectionLost` is the ONLY error that reconnects, and the asymmetry
+/// with `SendStalled` is deliberate. A stall means the peer is still there
+/// but has stopped acknowledging a quarter-megabyte of backlog — it has
+/// already spent the flush bound proving that, and at muxa's frame sizes
+/// it is very nearly unreachable — so a redial would be a second guess
+/// about a connection that never said it was gone.
+///
+/// A redial that fails does not swallow the reason: it is recorded on the
+/// Conn and `ConnectionLost` is re-raised, so the verb reports what went
+/// wrong FIRST (the path tore) and what went wrong second (the redial),
+/// rather than only the second. See `Conn.reconnect_failure`.
+fn awaitReissuing(
+    alloc: std.mem.Allocator,
+    conn: *Conn,
+    o: Opts,
+    since_seq: u64,
+    deadline: i64,
+) !proto.AwaitReply {
+    return doAwait(alloc, conn, o, since_seq, deadline) catch |e| switch (e) {
+        error.ConnectionLost => {
+            if (conn.link != .quic or conn.link.quic.reconnected) return e;
+            conn.reconnect(deadline) catch |redial| {
+                conn.reconnect_failure = @errorName(redial);
+                return e;
+            };
+            // The attach is part of the reconnect, not a separate step: a
+            // daemon that lost our connection lost the client slot with
+            // it, so an await_req arriving unattached asks about nothing.
+            // A failure here is still the reconnect failing.
+            attachZero(conn, deadline) catch |reattach| {
+                conn.reconnect_failure = @errorName(reattach);
+                return e;
+            };
+            return doAwait(alloc, conn, o, since_seq, deadline);
+        },
+        else => e,
+    };
+}
+/// What a wait that ended without a reply says past the verb's own
+/// "no reply". Every error but one is its own name, exactly as before —
+/// the socket arm's failures are untouched — because `ConnectionLost` is
+/// the only one whose name is half the story.
+///
+/// The three endings a lost connection has, and they are worth telling
+/// apart: the redial failed (why), the redial had already been spent (so
+/// this is the second tear of the same wait), or nothing tried to redial.
+fn waitFailDetail(buf: []u8, conn: *const Conn, e: anyerror) []const u8 {
+    if (e != error.ConnectionLost) return @errorName(e);
+    if (conn.reconnect_failure) |why| {
+        return std.fmt.bufPrint(buf, "connection lost; reconnect failed: {s}", .{why}) catch
+            "connection lost; reconnect failed";
+    }
+    const spent = switch (conn.link) {
+        .quic => |q| q.reconnected,
+        .fd => false,
+    };
+    if (spent) return "connection lost again, after the one reconnect";
+    return "connection lost";
+}
+/// The session's RETURN WATERMARK: the seq of the last command return, 0 if
+/// none. Handed straight to `since_seq`, where it means "only a return
+/// newer than this may answer me".
+fn currentSeq(alloc: std.mem.Allocator, conn: *Conn, deadline: i64) !u64 {
+    try conn.sendFrame(.status_req, "", deadline);
+    const frame = try conn.awaitFrame(.status_reply, deadline);
+    defer frame.deinit(alloc);
+    const s = try proto.decodeStatusReply(frame.payload);
+    return s.cmd.seq;
+}
+/// Strip the styling out of scrollback rows: an agent reading `output`
+/// wants what the command printed, not how it was coloured.
+///
+/// CSI (ESC [ … final byte) and OSC (ESC ] … BEL or ST) go, as does any
+/// other two-byte escape; text and newlines stay. Deliberately not a VT
+/// parser — these rows come from our own formatter, which emits SGR and
+/// nothing more exotic. Caller frees.
+fn stripSgr(alloc: std.mem.Allocator, s: []const u8) ![]u8 {
+    var out: std.ArrayList(u8) = .empty;
+    errdefer out.deinit(alloc);
+    var i: usize = 0;
+    while (i < s.len) {
+        if (s[i] != 0x1b or i + 1 >= s.len) {
+            try out.append(alloc, s[i]);
+            i += 1;
+            continue;
+        }
+        switch (s[i + 1]) {
+            '[' => {
+                i += 2;
+                // Parameter and intermediate bytes, then one final byte in
+                // 0x40..0x7e that ends the sequence.
+                while (i < s.len and (s[i] < 0x40 or s[i] > 0x7e)) i += 1;
+                if (i < s.len) i += 1;
+            },
+            ']' => {
+                i += 2;
+                while (i < s.len) : (i += 1) {
+                    if (s[i] == 0x07) {
+                        i += 1;
+                        break;
+                    }
+                    if (s[i] == 0x1b and i + 1 < s.len and s[i + 1] == '\\') {
+                        i += 2;
+                        break;
+                    }
+                }
+            },
+            // ESC 7, ESC M and friends: two bytes, both dropped.
+            else => i += 2,
+        }
+    }
+    return out.toOwnedSlice(alloc);
+}
+test "stripSgr leaves text, drops SGR and OSC" {
+    const alloc = std.testing.allocator;
+    const got = try stripSgr(alloc, "\x1b[0m\x1b[1;31mred\x1b[0m ok\n\x1b]0;title\x07plain");
+    defer alloc.free(got);
+    try std.testing.expectEqualStrings("red ok\nplain", got);
+}
+/// The rows a command occupied, as plain text. `end_row` is the row the D
+/// mark landed on — the prompt redraw — so the span is [start_row, end_row)
+/// and an end at or before the start is simply no output.
+///
+/// Rows are absolute screen rows and best-effort by construction (see
+/// MarkEvent.row): the alt screen and scrollback pruning can invalidate
+/// them between the reply and this fetch. Every failure mode here is
+/// therefore a null output, never a failed run — the exit code is the
+/// answer, and the transcript is the bonus.
+fn fetchSpan(
+    alloc: std.mem.Allocator,
+    conn: *Conn,
+    start_row: u32,
+    end_row: u32,
+    deadline: i64,
+) !?[]u8 {
+    if (end_row <= start_row) return null;
+    const count: u16 = @intCast(@min(end_row - start_row, std.math.maxInt(u16)));
+    try conn.sendFrame(.fetch_scrollback, &proto.encodeScrollbackReq(start_row, count), deadline);
+    const frame = try conn.awaitFrame(.scrollback_chunk, deadline);
+    defer frame.deinit(alloc);
+    // The chunk leads with the request it answers; the rows follow.
+    if (frame.payload.len <= 6) return null;
+    return try stripSgr(alloc, frame.payload[6..]);
+}
+/// One JSON object: what ended the wait, what the session's command state
+/// was when it ended, and how long we waited. `output` is present only when
+/// there is a transcript to give — an absent key and an empty string are
+/// different answers.
+fn printAwaitReply(
+    writer: anytype,
+    r: proto.AwaitReply,
+    output: ?[]const u8,
+    duration_ms: i64,
+) !void {
+    try writer.writeAll("{\"reason\":");
+    try jsonEscape(writer, @tagName(r.reason));
+    try writer.writeAll(",");
+    try writeCmdFields(writer, r.state);
+    try writer.print(",\"duration_ms\":{d}", .{duration_ms});
+    if (output) |text| {
+        try writer.writeAll(",\"output\":");
+        try jsonEscape(writer, text);
+    }
+    try writer.writeAll("}\n");
+}
+test "printAwaitReply omits output when there is none and spells a missing code null" {
+    const alloc = std.testing.allocator;
+    const r: proto.AwaitReply = .{
+        .state = .{
+            .phase = .returned,
+            .mechanism = .settle,
+            .exit_code = null,
+            .start_row = 3,
+            .end_row = 9,
+            .seq = 12,
+        },
+        .reason = .settled,
+    };
+    var bare: std.ArrayList(u8) = .empty;
+    defer bare.deinit(alloc);
+    try printAwaitReply(bare.writer(alloc), r, null, 250);
+    try std.testing.expectEqualStrings(
+        "{\"reason\":\"settled\",\"phase\":\"returned\",\"mechanism\":\"settle\"," ++
+            "\"exit_code\":null,\"start_row\":3,\"end_row\":9,\"duration_ms\":250}\n",
+        bare.items,
+    );
+    var with: std.ArrayList(u8) = .empty;
+    defer with.deinit(alloc);
+    try printAwaitReply(with.writer(alloc), r, "a\nb", 250);
+    try std.testing.expect(std.mem.indexOf(u8, with.items, "\"output\":\"a\\nb\"") != null);
+}
+/// The session ran its last command. An ANSWER for `run` and `await` — the
+/// command is over and this is how — so it prints on stdout and exits 0,
+/// unlike the other verbs, which have nothing to report and fail.
+fn printSessionEnded(writer: anytype, code: ?u8, duration_ms: i64) !void {
+    try writer.writeAll("{\"reason\":\"session_ended\",\"exit_code\":");
+    try writeExitCode(writer, code);
+    try writer.print(",\"duration_ms\":{d}}}\n", .{duration_ms});
+}
+/// Print an await outcome and choose the exit code for it. A timeout is the
+/// only nonzero one: the agent asked a question and got "still running",
+/// which is a distinct thing to branch on, while `returned` and `settled`
+/// are both answers — including a command that returned nonzero, whose
+/// failure is in `exit_code`, not in muxa's.
+fn reportAwait(
+    alloc: std.mem.Allocator,
+    r: proto.AwaitReply,
+    output: ?[]const u8,
+    duration_ms: i64,
+) !u8 {
+    var out: std.ArrayList(u8) = .empty;
+    defer out.deinit(alloc);
+    try printAwaitReply(out.writer(alloc), r, output, duration_ms);
+    proto.writeAllFd(std.posix.STDOUT_FILENO, out.items) catch {};
+    return if (r.reason == .timeout) 3 else 0;
+}
+fn reportSessionEnded(alloc: std.mem.Allocator, code: ?u8, duration_ms: i64) !u8 {
+    var out: std.ArrayList(u8) = .empty;
+    defer out.deinit(alloc);
+    try printSessionEnded(out.writer(alloc), code, duration_ms);
+    proto.writeAllFd(std.posix.STDOUT_FILENO, out.items) catch {};
+    return 0;
+}
+/// `await` and `run` are one pipeline: attach claiming no grid, read the
+/// watermark, wait for the session to come to rest, report. `run` is that
+/// pipeline with a command line put in — the line is sent between the
+/// watermark and the wait, and the marks span is fetched at the end — so
+/// `cmdline` being non-null IS the difference between the two verbs, and
+/// they are written once rather than twice with the middle diverging.
+fn awaitVerb(
+    alloc: std.mem.Allocator,
+    conn: *Conn,
+    o: Opts,
+    deadline: i64,
+    cmdline: ?[]const u8,
+) !u8 {
+    // Every error string this function can print names the verb the user
+    // typed, because "attach failed" from the wrong verb sends an agent
+    // looking in the wrong place.
+    const who = if (cmdline == null) "await" else "run";
+    const started = std.time.milliTimestamp();
+    attachZero(conn, deadline) catch |e| return failAs(who, "attach failed", @errorName(e));
+    // BEFORE the input, not after: the watermark has to be the one this
+    // command must beat. Read afterwards, a command fast enough to return
+    // between the two would have already moved the seq past a value we
+    // never recorded, and the await would sit waiting for a return that
+    // had happened.
+    const since = currentSeq(alloc, conn, deadline) catch |e| switch (e) {
+        error.SessionExited => return reportSessionEnded(alloc, conn.session_exit, elapsed(started)),
+        else => return failAs(who, "status failed", @errorName(e)),
+    };
+    if (cmdline) |cmd| {
+        // The cmdline goes to the pty verbatim — escapes are `send`'s
+        // business — plus the newline that submits it. No ack round-trip is
+        // needed the way `send` needs one: the await_req that follows is
+        // itself the read that proves the daemon got past this frame, and
+        // this process stays connected until the reply lands.
+        const line = std.fmt.allocPrint(alloc, "{s}\n", .{cmd}) catch |e|
+            return failAs(who, "cannot build the command line", @errorName(e));
+        defer alloc.free(line);
+        conn.sendFrame(.input, line, deadline) catch |e|
+            return failAs(who, "input failed", @errorName(e));
+    }
+    const r = awaitReissuing(alloc, conn, o, since, awaitDeadline(o, conn)) catch |e| switch (e) {
+        error.SessionExited => return reportSessionEnded(alloc, conn.session_exit, elapsed(started)),
+        else => {
+            var detail: [128]u8 = undefined;
+            return failAs(who, "no reply", waitFailDetail(&detail, conn, e));
+        },
+    };
+    // Only the marks regime knows where the command's rows are; pgid and
+    // settle answer WHEN, never WHERE, and a span from them would be a
+    // guess dressed as a transcript. `await` never fetches one at all: it
+    // did not start the command, so the span it would name is not its own.
+    var output: ?[]u8 = null;
+    defer if (output) |text| alloc.free(text);
+    if (cmdline != null and r.state.mechanism == .marks and r.reason == .returned) {
+        output = fetchSpan(
+            alloc,
+            conn,
+            r.state.start_row,
+            r.state.end_row,
+            @max(deadline, deadlineFor(span_fetch_ms)),
+        ) catch null;
+    }
+    return reportAwait(alloc, r, output, elapsed(started));
+}
+fn elapsed(started: i64) i64 {
+    return std.time.milliTimestamp() - started;
+}
+/// This client's deadline for the await itself — the daemon's own bound
+/// plus the grace window (see await_grace_ms and Conn.graceMs, which is
+/// where the transport gets to widen it). An unbounded request stays
+/// unbounded here too.
+fn awaitDeadline(o: Opts, conn: *const Conn) i64 {
+    if (o.timeout_ms == 0) return std.math.maxInt(i64);
+    return std.time.milliTimestamp() + o.timeout_ms + conn.graceMs();
+}

src/protocol.zig

@@ @@ -18,6 +18,8 @@ pub const MsgType = enum(u8) { @@
+    stats_req = 0x06, // payload: empty
+    stop_req = 0x07, // payload: empty; daemon shuts down as if signalled
+    endpoint_req = 0x08, // payload: empty; asks for the QUIC port, binding a listener lazily if needed
+    await_req = 0x09, // payload: u64 LE since_seq, u32 LE settle_ms, u32 LE timeout_ms; either duration 0 = that mechanism off
+    status_req = 0x0a, // payload: empty
+    debug_dump = 0x7f, // payload: 1 byte: 0 = plain, 1 = vt
+    // daemon -> client
+    snapshot = 0x81, // payload: SnapshotPrefix ++ full-state vt dump
@@ @@ -30,6 +32,9 @@ pub const MsgType = enum(u8) { @@
+    delta = 0x87, // payload: see DeltaHeader + rows
+    pty_mode = 0x88, // payload: 1 byte flags: bit0 icanon, bit1 echo
+    endpoint_reply = 0x89, // payload: u16 LE port; 0 = no listener could be produced (reason in daemon log)
+    cmd_state = 0x8a, // payload: CmdState (see encodeCmdState); pushed on marks-regime transitions
+    await_reply = 0x8b, // payload: CmdState ++ 1 byte AwaitReason
+    status_reply = 0x8c, // payload: StatusReply (see encodeStatusReply)
+    dump_reply = 0xff, // payload: requested dump bytes
+    _,
+};
@@ @@ -51,6 +56,44 @@ pub const Frame = struct { @@
+};
+/// One frame's boundaries inside a buffer somebody else filled. `payload`
+/// BORROWS from that buffer and is valid only until it is written to or
+/// shifted, which is why this type is separate from `Frame`: the callers
+/// that need to keep a payload copy it out themselves, and the ones that
+/// only need to read it never allocate at all.
+pub const Delimited = struct {
+    type: MsgType,
+    payload: []const u8,
+    /// Header plus payload — what the caller must drop off the front of
+    /// its buffer before looking for the next frame.
+    consumed: usize,
+};
+/// Delimit the frame at the front of `buf`, without copying.
+///
+/// Null means the tail is still partial — a header that has not all
+/// arrived, or a payload still in flight — which is the ordinary state of
+/// a byte stream and never an error. `error.FrameTooLarge` means a length
+/// no frame can legitimately carry: the stream is not what we think it is,
+/// and reading on would size an allocation from a number the peer chose.
+///
+/// Pure, and takes a plain slice rather than any connection, so both ends
+/// of the wire delimit with the same arithmetic and it can be exercised
+/// against a canned buffer. The type byte is read through a non-exhaustive
+/// enum on purpose: an unknown message type is the peer's business to have
+/// sent and the caller's to ignore, not a reason to refuse the stream.
+pub fn delimitFrame(buf: []const u8) !?Delimited {
+    if (buf.len < frame_header_len) return null;
+    const len = std.mem.readInt(u32, buf[1..5], .little);
+    if (len > max_payload) return error.FrameTooLarge;
+    if (buf.len < frame_header_len + len) return null;
+    return .{
+        .type = @enumFromInt(buf[0]),
+        .payload = buf[frame_header_len..][0..len],
+        .consumed = frame_header_len + len,
+    };
+}
+pub fn writeFrame(fd: std.posix.fd_t, t: MsgType, payload: []const u8) !void {
+    var hdr: [5]u8 = undefined;
+    hdr[0] = @intFromEnum(t);
@@ @@ -161,6 +204,177 @@ pub fn decodeEndpointReply(payload: []const u8) !u16 { @@
+    return std.mem.readInt(u16, payload[0..2], .little);
+/// Where the command-boundary signal came from, weakest-last. `marks` is the
+/// only mechanism that can carry an exit code; consumers must check it
+/// before trusting one.
+pub const Mechanism = enum(u8) { marks = 0, pgid = 1, settle = 2 };
+pub const CmdPhase = enum(u8) { at_prompt = 0, running = 1, returned = 2 };
+/// One snapshot of the session's command state machine. Rows are absolute
+/// screen-space rows (0 = oldest retained history row) — meaningless while
+/// the alt screen is active, and shifted once the scrollback ring prunes,
+/// so spans should be fetched promptly.
+pub const CmdState = struct {
+    phase: CmdPhase,
+    mechanism: Mechanism,
+    exit_code: ?u8,
+    start_row: u32,
+    end_row: u32,
+    /// Two different numbers travel in this field, and which one it is
+    /// depends on the frame carrying it:
+    ///
+    ///   * In `status_reply` and in the `cmd_state` pushes the marks stream
+    ///     produces, it is the RETURN WATERMARK — the seq stamped when a
+    ///     command last returned, 0 if none has this session. This is the
+    ///     series `AwaitReq.since_seq` is compared against.
+    ///   * In an `await_reply` resolved by anything other than marks (the
+    ///     pgid, settle and timeout fallbacks), it is instead the delta
+    ///     tracker's CURRENT seq — a grid-content ordering, so the answer
+    ///     can be placed against the deltas the client holds.
+    ///
+    /// So: an agent must take its next `since_seq` from a status or marks
+    /// reply, never from a fallback one. Feeding a tracker seq back as a
+    /// watermark compares across two series, and a client that did it would
+    /// wait out its next await for a return that had already happened.
+    ///
+    /// OPEN DESIGN NOTE, recorded rather than acted on: it is not settled
+    /// that the fallback arms should stamp anything into this field, since
+    /// they have no return to watermark. Making them send the watermark
+    /// instead would collapse the two meanings into one — and would change
+    /// the bytes on the wire, so it is a protocol decision, not a cleanup.
+    seq: u64,
+};
+pub const cmd_state_len = 20;
+pub fn encodeCmdState(s: CmdState) [cmd_state_len]u8 {
+    var buf: [cmd_state_len]u8 = undefined;
+    buf[0] = @intFromEnum(s.phase);
+    buf[1] = @intFromEnum(s.mechanism);
+    buf[2] = @intFromBool(s.exit_code != null);
+    buf[3] = s.exit_code orelse 0;
+    std.mem.writeInt(u32, buf[4..8], s.start_row, .little);
+    std.mem.writeInt(u32, buf[8..12], s.end_row, .little);
+    std.mem.writeInt(u64, buf[12..20], s.seq, .little);
+    return buf;
+}
+fn enumFromByte(comptime E: type, b: u8) !E {
+    return std.meta.intToEnum(E, b) catch error.BadPayload;
+}
+pub fn decodeCmdState(payload: []const u8) !CmdState {
+    if (payload.len != cmd_state_len) return error.BadPayload;
+    return .{
+        .phase = try enumFromByte(CmdPhase, payload[0]),
+        .mechanism = try enumFromByte(Mechanism, payload[1]),
+        // byte 2 is a presence flag, not a bool-strict 0/1 check: any
+        // nonzero value reads as "present" deliberately, so a peer that
+        // ever widens what it writes there doesn't silently lose the code.
+        .exit_code = if (payload[2] != 0) payload[3] else null,
+        .start_row = std.mem.readInt(u32, payload[4..8], .little),
+        .end_row = std.mem.readInt(u32, payload[8..12], .little),
+        .seq = std.mem.readInt(u64, payload[12..20], .little),
+    };
+}
+/// A request to be told when the session next returns to rest.
+///
+/// `since_seq` is what the caller already knows about: only a return strictly
+/// newer than it may answer, which is what makes re-issuing after a dropped
+/// connection safe rather than a second wait.
+///
+/// Both durations treat 0 as "off", not as "immediately": `settle_ms = 0`
+/// declines the output-silence mechanism altogether, and `timeout_ms = 0` is
+/// an await with no deadline, ending only when marks, the pgid edge or settle
+/// end it. A caller that wants to poll rather than wait asks for a small
+/// timeout, never a zero one.
+pub const AwaitReq = struct { since_seq: u64, settle_ms: u32, timeout_ms: u32 };
+pub const await_req_len = 16;
+pub fn encodeAwaitReq(r: AwaitReq) [await_req_len]u8 {
+    var buf: [await_req_len]u8 = undefined;
+    std.mem.writeInt(u64, buf[0..8], r.since_seq, .little);
+    std.mem.writeInt(u32, buf[8..12], r.settle_ms, .little);
+    std.mem.writeInt(u32, buf[12..16], r.timeout_ms, .little);
+    return buf;
+}
+pub fn decodeAwaitReq(payload: []const u8) !AwaitReq {
+    if (payload.len != await_req_len) return error.BadPayload;
+    return .{
+        .since_seq = std.mem.readInt(u64, payload[0..8], .little),
+        .settle_ms = std.mem.readInt(u32, payload[8..12], .little),
+        .timeout_ms = std.mem.readInt(u32, payload[12..16], .little),
+    };
+}
+pub const AwaitReason = enum(u8) { returned = 0, settled = 1, timeout = 2 };
+pub const await_reply_len = cmd_state_len + 1;
+pub fn encodeAwaitReply(s: CmdState, reason: AwaitReason) [await_reply_len]u8 {
+    var buf: [await_reply_len]u8 = undefined;
+    buf[0..cmd_state_len].* = encodeCmdState(s);
+    buf[cmd_state_len] = @intFromEnum(reason);
+    return buf;
+}
+pub const AwaitReply = struct { state: CmdState, reason: AwaitReason };
+pub fn decodeAwaitReply(payload: []const u8) !AwaitReply {
+    if (payload.len != await_reply_len) return error.BadPayload;
+    return .{
+        .state = try decodeCmdState(payload[0..cmd_state_len]),
+        .reason = try enumFromByte(AwaitReason, payload[cmd_state_len]),
+    };
+}
+/// One structured snapshot for `muxa status`. The grid facts a driving
+/// agent needs before deciding how to interact: size, cursor, whether a
+/// TUI holds the screen, who echoes keystrokes, and the command state.
+pub const StatusReply = struct {
+    cols: u16,
+    rows: u16,
+    cursor_x: u16,
+    cursor_y: u16,
+    history_rows: u32,
+    alt_screen: bool,
+    mode: PtyModeFlags,
+    cmd: CmdState,
+};
+pub const status_reply_len = 14 + cmd_state_len;
+pub fn encodeStatusReply(s: StatusReply) [status_reply_len]u8 {
+    var buf: [status_reply_len]u8 = undefined;
+    std.mem.writeInt(u16, buf[0..2], s.cols, .little);
+    std.mem.writeInt(u16, buf[2..4], s.rows, .little);
+    std.mem.writeInt(u16, buf[4..6], s.cursor_x, .little);
+    std.mem.writeInt(u16, buf[6..8], s.cursor_y, .little);
+    std.mem.writeInt(u32, buf[8..12], s.history_rows, .little);
+    buf[12] = @intFromBool(s.alt_screen);
+    buf[13] = @bitCast(s.mode);
+    buf[14..][0..cmd_state_len].* = encodeCmdState(s.cmd);
+    return buf;
+}
+pub fn decodeStatusReply(payload: []const u8) !StatusReply {
+    if (payload.len != status_reply_len) return error.BadPayload;
+    return .{
+        .cols = std.mem.readInt(u16, payload[0..2], .little),
+        .rows = std.mem.readInt(u16, payload[2..4], .little),
+        .cursor_x = std.mem.readInt(u16, payload[4..6], .little),
+        .cursor_y = std.mem.readInt(u16, payload[6..8], .little),
+        .history_rows = std.mem.readInt(u32, payload[8..12], .little),
+        .alt_screen = payload[12] != 0,
+        .mode = try decodePtyMode(payload[13..14]),
+        .cmd = try decodeCmdState(payload[14..][0..cmd_state_len]),
+    };
+}
+/// The two line-discipline bits that decide who is going to echo a
+/// keystroke, and therefore whether a client may echo it early. Read off the
+/// session's pty by the daemon and shipped verbatim: the client is told what
@@ @@ -763,3 +977,120 @@ test "endpoint frames match golden bytes" { @@
+x89, 0x02, 0x00, 0x00, 0x00, 0xCA, 0xA8,
+    }, buf.items);
+test "cmd_state encode/decode round trip and golden bytes" {
+    const s = CmdState{
+        .phase = .returned,
+        .mechanism = .marks,
+        .exit_code = 1,
+        .start_row = 80,
+        .end_row = 92,
+        .seq = 258,
+    };
+    const buf = encodeCmdState(s);
+    try std.testing.expectEqualSlices(u8, &[_]u8{
+, // phase returned
+, // mechanism marks
+, // has_exit
+, // exit_code
+x50, 0, 0, 0, // start_row 80
+x5C, 0, 0, 0, // end_row 92
+x02, 0x01, 0, 0, 0, 0, 0, 0, // seq 258
+    }, &buf);
+    const back = try decodeCmdState(&buf);
+    try std.testing.expectEqual(s, back);
+}
+test "cmd_state with no exit code round-trips null, not zero" {
+    const s = CmdState{ .phase = .running, .mechanism = .pgid, .exit_code = null, .start_row = 5, .end_row = 0, .seq = 9 };
+    const buf = encodeCmdState(s);
+    // No exit code means byte 3 is unused, but it still goes out as a clean
+    // zero rather than whatever the encoder happened to have lying around.
+    try std.testing.expectEqualSlices(u8, &.{ 0, 0 }, buf[2..4]);
+    const back = try decodeCmdState(&buf);
+    try std.testing.expectEqual(@as(?u8, null), back.exit_code);
+}
+test "cmd_state rejects wrong length and unknown enum bytes" {
+    try std.testing.expectError(error.BadPayload, decodeCmdState(&[_]u8{0} ** (cmd_state_len - 1)));
+    try std.testing.expectError(error.BadPayload, decodeCmdState(&[_]u8{0} ** (cmd_state_len + 1)));
+    var bad = encodeCmdState(.{ .phase = .at_prompt, .mechanism = .settle, .exit_code = null, .start_row = 0, .end_row = 0, .seq = 0 });
+    bad[0] = 9; // phase out of range
+    try std.testing.expectError(error.BadPayload, decodeCmdState(&bad));
+    bad[0] = 0;
+    bad[1] = 9; // mechanism out of range
+    try std.testing.expectError(error.BadPayload, decodeCmdState(&bad));
+}
+test "await_req encode/decode round trip" {
+    const r = try decodeAwaitReq(&encodeAwaitReq(.{ .since_seq = 77, .settle_ms = 500, .timeout_ms = 30_000 }));
+    try std.testing.expectEqual(@as(u64, 77), r.since_seq);
+    try std.testing.expectEqual(@as(u32, 500), r.settle_ms);
+    try std.testing.expectEqual(@as(u32, 30_000), r.timeout_ms);
+    try std.testing.expectError(error.BadPayload, decodeAwaitReq(&[_]u8{0} ** 15));
+}
+test "encodeAwaitReq golden bytes" {
+    try std.testing.expectEqualSlices(u8, &[_]u8{
+x02, 0x01, 0, 0, 0, 0, 0, 0, // since_seq 258
+xF4, 0x01, 0, 0, // settle_ms 500
+x30, 0x75, 0, 0, // timeout_ms 30000
+    }, &encodeAwaitReq(.{ .since_seq = 258, .settle_ms = 500, .timeout_ms = 30_000 }));
+}
+test "await_reply is a CmdState plus a reason byte" {
+    const s = CmdState{ .phase = .returned, .mechanism = .settle, .exit_code = null, .start_row = 0, .end_row = 3, .seq = 4 };
+    const buf = encodeAwaitReply(s, .settled);
+    try std.testing.expectEqual(@as(usize, await_reply_len), buf.len);
+    const back = try decodeAwaitReply(&buf);
+    try std.testing.expectEqual(AwaitReason.settled, back.reason);
+    try std.testing.expectEqual(s, back.state);
+    try std.testing.expectError(error.BadPayload, decodeAwaitReply(&[_]u8{0} ** (await_reply_len - 1)));
+    try std.testing.expectError(error.BadPayload, decodeAwaitReply(&[_]u8{0} ** (await_reply_len + 1)));
+    var bad = buf;
+    bad[cmd_state_len] = 9;
+    try std.testing.expectError(error.BadPayload, decodeAwaitReply(&bad));
+}
+test "status_reply encode/decode round trip" {
+    const s = StatusReply{
+        .cols = 120,
+        .rows = 40,
+        .cursor_x = 3,
+        .cursor_y = 5,
+        .history_rows = 77,
+        .alt_screen = true,
+        .mode = .{ .icanon = true, .echo = true },
+        .cmd = .{ .phase = .at_prompt, .mechanism = .marks, .exit_code = 0, .start_row = 1, .end_row = 2, .seq = 6 },
+    };
+    const back = try decodeStatusReply(&encodeStatusReply(s));
+    try std.testing.expectEqual(s, back);
+    try std.testing.expectError(error.BadPayload, decodeStatusReply(&[_]u8{0} ** (status_reply_len - 1)));
+    try std.testing.expectError(error.BadPayload, decodeStatusReply(&[_]u8{0} ** (status_reply_len + 1)));
+}
+test "encodeStatusReply pins the 14-byte prefix layout" {
+    const s = StatusReply{
+        .cols = 120,
+        .rows = 40,
+        .cursor_x = 3,
+        .cursor_y = 5,
+        .history_rows = 77,
+        .alt_screen = true,
+        .mode = .{ .icanon = true, .echo = true },
+        .cmd = .{ .phase = .at_prompt, .mechanism = .marks, .exit_code = 0, .start_row = 1, .end_row = 2, .seq = 6 },
+    };
+    const buf = encodeStatusReply(s);
+    try std.testing.expectEqual(@as(usize, status_reply_len), buf.len);
+    // The trailing CmdState is already golden-tested via encodeCmdState;
+    // pinning the 14-byte prefix plus total length is enough here.
+    try std.testing.expectEqualSlices(u8, &[_]u8{
+x78, 0x00, // cols 120
+x28, 0x00, // rows 40
+x03, 0x00, // cursor_x 3
+x05, 0x00, // cursor_y 5
+x4D, 0x00, 0x00, 0x00, // history_rows 77
+, // alt_screen
+b11, // mode: icanon + echo
+    }, buf[0..14]);
+}

src/pty.zig

Old		New
@@ -24,6 +24,13 @@ pub const Pty = struct {
24	return spawnArgv(.{ .cols = opts.cols, .rows = opts.rows, .argv = &argv });	24	return spawnArgv(.{ .cols = opts.cols, .rows = opts.rows, .argv = &argv });
25	}	25	}
26		26
		27	/// One variable to set in the child. Spelled here rather than imported
		28	/// so this module stays a leaf: a pty knows how to hand a child an
		29	/// environment, and deliberately does not know that shell integration
		30	/// is what currently wants one. The daemon maps its own pairs onto
		31	/// these — one loop, and the layering stays the right way up.
		32	pub const EnvPair = struct { key: [:0]const u8, value: [:0]const u8 };
		33
27	pub const SpawnArgvOptions = struct {	34	pub const SpawnArgvOptions = struct {
28	cols: u16,	35	cols: u16,
29	rows: u16,	36	rows: u16,
@@ -34,6 +41,9 @@ pub const Pty = struct {
34	/// The e2e fixture uses this to keep predict stats out of the	41	/// The e2e fixture uses this to keep predict stats out of the
35	/// capture, matching the suite's `.err` sibling convention.	42	/// capture, matching the suite's `.err` sibling convention.
36	stderr_fd: ?std.posix.fd_t = null,	43	stderr_fd: ?std.posix.fd_t = null,
		44	/// Set in the child between fork and exec, after TERM. Injection's
		45	/// door: the daemon's env is the only source of a child's env.
		46	env: []const EnvPair = &.{},
37	};	47	};
38		48
39	/// The one child-setup path: everything that has to be true of a process	49	/// The one child-setup path: everything that has to be true of a process
@@ -60,6 +70,20 @@ pub const Pty = struct {
60	// Child. xterm-256color: ghostty-vt understands more, but this	70	// Child. xterm-256color: ghostty-vt understands more, but this
61	// terminfo exists everywhere the shell will look.	71	// terminfo exists everywhere the shell will look.
62	_ = c.setenv("TERM", "xterm-256color", 1);	72	_ = c.setenv("TERM", "xterm-256color", 1);
		73	// After TERM so a caller could override it, and before the
		74	// signal work so the environment is settled whatever follows.
		75	//
		76	// Overwrite (1), and that is a contract rather than a detail:
		77	// the daemon's own value for a name it was handed is not the
		78	// one it means the child to see, and — because this is a loop
		79	// over an ordered slice — a LATER pair beats an earlier one for
		80	// the same key. That is what lets Server.Options.extra_env
		81	// override a variable the shell-integration injection set,
		82	// which is exactly how the integration tests point HOME at a
		83	// temp directory. The rule was pinned only by that usage; it is
		84	// spelled out here so a reorder of the slice cannot quietly
		85	// invert it.
		86	for (opts.env) \|kv\| _ = c.setenv(kv.key.ptr, kv.value.ptr, 1);
63		87
64	// Ctrl-C must work in the session, and without this it does not.	88	// Ctrl-C must work in the session, and without this it does not.
65	// A non-interactive shell sets SIGINT and SIGQUIT to SIG_IGN for	89	// A non-interactive shell sets SIGINT and SIGQUIT to SIG_IGN for
@@ -118,6 +142,17 @@ pub const Pty = struct {
118	return .{ .icanon = t.lflag.ICANON, .echo = t.lflag.ECHO };	142	return .{ .icanon = t.lflag.ICANON, .echo = t.lflag.ECHO };
119	}	143	}
120		144
		145	/// The foreground process group of the session, read off the master
		146	/// with TIOCGPGRP. When it equals `child` (the shell, session leader
		147	/// post-forkpty), no foreground job is running — the kernel's own
		148	/// "the command returned", available with zero shell cooperation.
		149	/// No exit code and no output span; that is what marks are for.
		150	pub fn fgPgid(self: *const Pty) !std.posix.pid_t {
		151	var pgid: c.pid_t = 0;
		152	if (c.ioctl(self.master, c.TIOCGPGRP, &pgid) < 0) return error.IoctlFailed;
		153	return @intCast(pgid);
		154	}
		155
121	pub fn resize(self: *Pty, cols: u16, rows: u16) !void {	156	pub fn resize(self: *Pty, cols: u16, rows: u16) !void {
122	var ws: c.struct_winsize = .{	157	var ws: c.struct_winsize = .{
123	.ws_row = rows,	158	.ws_row = rows,
@@ -348,6 +383,26 @@ test "Pty: spawnArgv applies the requested winsize" {
348	try std.testing.expect(std.mem.indexOf(u8, out.items, "31 101") != null);	383	try std.testing.expect(std.mem.indexOf(u8, out.items, "31 101") != null);
349	}	384	}
350		385
		386	test "Pty: spawnArgv env pairs reach the child" {
		387	// The child prints the variable rather than being asked about it: an
		388	// exported name that the exec'd process cannot read is the failure
		389	// this guards, so the assertion has to come from inside the child.
		390	var argv = [_:null]?[*:0]const u8{ "/bin/sh", "-c", "printf 'env-%s' \"$MUX_T\"" };
		391	var pty = try Pty.spawnArgv(.{
		392	.cols = 80,
		393	.rows = 24,
		394	.argv = &argv,
		395	.env = &.{.{ .key = "MUX_T", .value = "ok" }},
		396	});
		397	defer pty.deinit();
		398
		399	var out = try readUntil(std.testing.allocator, &pty, "env-ok", 5000);
		400	defer out.deinit(std.testing.allocator);
		401	// "env-" alone would appear for an unset variable too, which is exactly
		402	// the broken case; the value is what makes this an assertion.
		403	try std.testing.expect(std.mem.indexOf(u8, out.items, "env-ok") != null);
		404	}
		405
351	test "Pty: spawnArgv redirects stderr off the pty when asked" {	406	test "Pty: spawnArgv redirects stderr off the pty when asked" {
352	const pipe = try std.posix.pipe();	407	const pipe = try std.posix.pipe();
353	defer std.posix.close(pipe[0]);	408	defer std.posix.close(pipe[0]);
@@ -373,3 +428,47 @@ test "Pty: spawnArgv redirects stderr off the pty when asked" {
373	const n = try std.posix.read(pipe[0], &errbuf);	428	const n = try std.posix.read(pipe[0], &errbuf);
374	try std.testing.expect(std.mem.indexOf(u8, errbuf[0..n], "to-err") != null);	429	try std.testing.expect(std.mem.indexOf(u8, errbuf[0..n], "to-err") != null);
375	}	430	}
		431
		432	test "Pty: fgPgid tracks the foreground job" {
		433	const alloc = std.testing.allocator;
		434	var pty = try Pty.spawn(.{ .cols = 80, .rows = 24, .shell = "/bin/sh" });
		435	defer pty.deinit();
		436
		437	// Prove the shell is up before asking anything of the pgid.
		438	_ = try std.posix.write(pty.master, "printf 'ready-%s\\n' PGID\n");
		439	var ready = try readUntil(alloc, &pty, "ready-PGID", 5000);
		440	defer ready.deinit(alloc);
		441	try std.testing.expect(std.mem.indexOf(u8, ready.items, "ready-PGID") != null);
		442
		443	// At the prompt, the foreground pgid is the shell's own process group.
		444	// sh is the session leader post-forkpty, so its pgid == its pid.
		445	try std.testing.expectEqual(pty.child, try pty.fgPgid());
		446
		447	// A foreground job moves the fg pgid off the shell... eventually: an
		448	// interactive sh creates a new process group for the job. Poll for the
		449	// change rather than racing it.
		450	_ = try std.posix.write(pty.master, "sleep 2\n");
		451	var moved = false;
		452	var waited_ms: u64 = 0;
		453	while (waited_ms < 3000) : (waited_ms += 50) {
		454	if (try pty.fgPgid() != pty.child) {
		455	moved = true;
		456	break;
		457	}
		458	std.Thread.sleep(50 * std.time.ns_per_ms);
		459	}
		460	// Dash and busybox sh run foreground jobs in the shell's own group when
		461	// job control is off (non-interactive stdin heuristics differ), so a
		462	// never-moved pgid is a legal outcome for the fallback design — but on
		463	// a pty, POSIX shells enable job control. Assert movement; if this
		464	// flakes on some /bin/sh, relax to a log + skip, not a green lie.
		465	try std.testing.expect(moved);
		466
		467	// ...and returns to the shell when the job ends.
		468	waited_ms = 0;
		469	while (waited_ms < 5000) : (waited_ms += 100) {
		470	if (try pty.fgPgid() == pty.child) break;
		471	std.Thread.sleep(100 * std.time.ns_per_ms);
		472	}
		473	try std.testing.expectEqual(pty.child, try pty.fgPgid());
		474	}

src/quic.zig

@@ @@ -39,9 +39,13 @@ pub const default_port: u16 = 4433; @@
+/// gone. Long enough that a quiet terminal is not a suspicious one, short
+/// enough that a client which has genuinely vanished stops being served
+/// within a few seconds of keepalives failing — keepalives run at a third
+/// of it, so an idle session is never the thing that trips it.
+/// `--quic-idle-ms` tunes it on the three binaries that dial or listen for
+/// a human — `muxd`, `mux`, `muxweb` — because the reconnect tests need
+/// death declared on a schedule they can wait for. `muxa` deliberately has
+/// no such flag and always takes this default: an agent's wait is bounded
+/// by `--timeout` already, and a second knob over the same wait is one
+/// more thing for a driver to get wrong.
+///
+/// Here for the same reason as `default_port`: two copies of a number both
+/// binaries default to are two numbers, and they drift in silence.
+pub const alpn = "\x03mux";
+// ---------------------------------------------------------------------------
+// The dial address grammar
+// ---------------------------------------------------------------------------
+/// `HOST[:PORT]`, as a client types it: `mux quic://HOST:PORT` and
+/// `muxa --quic HOST:PORT` accept exactly these spellings, brackets and
+/// all. One owner for the same reason `default_port` has one — an agent
+/// and a human pointing at the same daemon must be able to type the same
+/// thing, and two copies of a grammar drift into two dialects of one flag.
+///
+/// A name is resolved rather than refused: unlike muxd's `--quic`, which
+/// names an address to BIND, this one names a box to reach, and a box is
+/// normally spelled with a name.
+pub fn parseAddr(alloc: std.mem.Allocator, host_port: []const u8) !std.net.Address {
+    // `[::1]` — bracketed and portless: the brackets say where the address
+    // stops, so the port can default.
+    if (host_port.len >= 2 and host_port[0] == '[' and host_port[host_port.len - 1] == ']')
+        return resolveHost(alloc, host_port[1 .. host_port.len - 1], default_port);
+    const colon = std.mem.lastIndexOfScalar(u8, host_port, ':') orelse
+        return resolveHost(alloc, host_port, default_port);
+    var host = host_port[0..colon];
+    const port_s = host_port[colon + 1 ..];
+    // `[::1]:4433` — brackets are how an IPv6 literal says where it stops.
+    if (host.len >= 2 and host[0] == '[' and host[host.len - 1] == ']') {
+        host = host[1 .. host.len - 1];
+    } else if (std.mem.indexOfScalar(u8, host, ':') != null) {
+        // Unbracketed and full of colons: an IPv6 literal missing its
+        // brackets, which would otherwise have its last group taken as a
+        // port. Refused rather than guessed at.
+        return error.MalformedAddress;
+    }
+    const port = std.fmt.parseInt(u16, port_s, 10) catch return error.MalformedAddress;
+    return resolveHost(alloc, host, port);
+}
+/// A host that is already known to be unambiguous, plus the port it goes
+/// with: literal if it parses as one, resolved if it does not.
+pub fn resolveHost(alloc: std.mem.Allocator, host: []const u8, port: u16) !std.net.Address {
+    if (host.len == 0) return error.MalformedAddress;
+    if (std.net.Address.parseIp(host, port)) |addr| return addr else |_| {}
+    // Not a literal: resolve it. A remote host is normally a name.
+    const list = try std.net.getAddressList(alloc, host, port);
+    defer list.deinit();
+    if (list.addrs.len == 0) return error.UnknownHostName;
+    return list.addrs[0];
+}
+test "parseAddr: literals, brackets, and the spellings that are refused" {
+    const alloc = std.testing.allocator;
+    // Literals only here: a name would send this test to a resolver, and
+    // what it answered would depend on the machine running it.
+    try std.testing.expectEqual(
+        @as(u16, 4433),
+        (try parseAddr(alloc, "127.0.0.1:4433")).getPort(),
+    );
+    try std.testing.expectEqual(@as(u16, 9), (try parseAddr(alloc, "127.0.0.1:9")).getPort());
+    // An omitted port means mux's own. Spelled out rather than written
+    // `default_port`, because comparing the parse's answer against the
+    // constant the parse reads would hold for any value and say nothing
+    // about the port — and this is the number the daemon at the other end
+    // has to agree on.
+    try std.testing.expectEqual(@as(u16, 4433), (try parseAddr(alloc, "10.0.0.2")).getPort());
+    const six = try parseAddr(alloc, "[::1]:9999");
+    try std.testing.expectEqual(@as(u16, 9999), six.getPort());
+    try std.testing.expect(six.any.family == std.posix.AF.INET6);
+    // Bracketed and portless: the brackets say where the address stops, so
+    // the port can default.
+    try std.testing.expectEqual(@as(u16, 4433), (try parseAddr(alloc, "[::1]")).getPort());
+    // An unbracketed IPv6 literal would have its last group read as a
+    // port. Refused rather than guessed at — the same refusal muxd's
+    // splitHostPort makes about its bind address.
+    try std.testing.expectError(error.MalformedAddress, parseAddr(alloc, "fe80::1:4433"));
+    try std.testing.expectError(error.MalformedAddress, parseAddr(alloc, "127.0.0.1:"));
+    try std.testing.expectError(error.MalformedAddress, parseAddr(alloc, "127.0.0.1:99999"));
+    try std.testing.expectError(error.MalformedAddress, parseAddr(alloc, ""));
+    try std.testing.expectError(error.MalformedAddress, parseAddr(alloc, ":4433"));
+}
+// ---------------------------------------------------------------------------
+// The pre-shared key
+// ---------------------------------------------------------------------------

src/server.zig

@@ @@ -10,6 +10,8 @@ const Engine = @import("engine").Engine; @@
+const Pty = @import("pty").Pty;
+const proto = @import("protocol");
+const DeltaTracker = @import("delta").DeltaTracker;
+const cmdmod = @import("cmd");
+const shellint = @import("shellint");
+// Test-only consumer (applyFrame): the tests replay daemon frames through
+// the production client's replay core rather than a hand-rolled twin.
+const replica_mod = @import("replica");
@@ @@ -212,6 +214,30 @@ const ClientSlot = struct { @@
+    /// Server.pending_cap; a peer that stops reading gets dropped, never
+    /// waited on — one slow WAN client must not stall the session.
+    pending: std.ArrayList(u8) = .empty,
+    /// An await_req held open. At most one per client: a second one
+    /// replaces the first (the client is a serial CLI; queueing two would
+    /// be inventing a use case).
+    await_state: ?AwaitState = null,
+};
+/// One client's outstanding await: the request as asked, plus the two pieces
+/// of state resolving it needs to carry across pumps.
+const AwaitState = struct {
+    since_seq: u64,
+    settle_ms: u32,
+    timeout_ms: u32,
+    /// milliTimestamp at acceptance; timeout measures from here.
+    started_ms: i64,
+    /// pgid fallback edge detector: set once the fg pgid has been seen off
+    /// the shell, so "back on the shell" means returned, not never-left.
+    ///
+    /// Note what this does NOT distinguish: an await issued while some
+    /// earlier command was already running answers on that command's tail,
+    /// not on a command the client started. That is still honest against
+    /// what the pgid can actually claim — "a foreground job has returned
+    /// since you asked" — and the null exit code keeps it from being read
+    /// as more. A client that needs "the command I started" needs marks.
+    saw_busy: bool = false,
+};
+pub const Server = struct {
@@ @@ -266,6 +292,39 @@ pub const Server = struct { @@
+    mode_sent: ?proto.PtyModeFlags = null,
+    /// Row-level change tracking behind the delta stream.
+    tracker: DeltaTracker = .{},
+    /// The session's command state machine (OSC 133). Seq-stamped copies of
+    /// its transitions are what cmd_state/await_reply/status_reply carry.
+    cmd: cmdmod.Tracker = .{},
+    /// The last completed command, frozen as it stood the moment it
+    /// returned, and the one owner of the return watermark: `.seq` is
+    /// tracker.seq as of that return, so "a return happened at or before
+    /// this seq" and "here is what it was" are one fact rather than two
+    /// fields that have to be kept in step. Null until a command returns,
+    /// which is what every reader spells as a watermark of 0.
+    ///
+    /// It exists because an await answers a question about a PAST event, and
+    /// the live tracker stops being able to describe that event almost
+    /// immediately. A real integrated shell emits `D;code` and the next
+    /// prompt's `A` in a single precmd write, so both fold into the tracker
+    /// before any await is looked at: phase is already back to `at_prompt`,
+    /// and the following command's `C` then clears the exit code outright.
+    /// Answering from live state therefore lost the verdict a fraction of a
+    /// pump after earning it — fast commands rode to their timeout, slow
+    /// ones degraded to pgid and threw the exit code away.
+    last_return: ?proto.CmdState = null,
+    /// milliTimestamp of the last byte the pty produced; the settle floor.
+    /// 0 means the session has never said anything, which no amount of
+    /// elapsed silence should be read as a command having finished.
+    last_pty_ms: i64 = 0,
+    /// Holds every string the shell-integration injection handed the spawn:
+    /// the shim directory's path, the argv, the env pairs. An arena because
+    /// they are allocated once, in init, and freed once, together.
+    shellint_arena: std.heap.ArenaAllocator,
+    /// The shim directory to remove at teardown, or null when nothing was
+    /// written — integration off, or a shell this daemon has no scripts for.
+    /// Distinct from "the arena is empty": only a directory that exists is
+    /// one we are responsible for deleting.
+    shellint_dir: ?[]const u8 = null,
+    stats: Stats = .{},
+    pub const Options = struct {
@@ @@ -273,6 +332,19 @@ pub const Server = struct { @@
+        shell: [:0]const u8,
+        cols: u16 = 80,
+        rows: u16 = 24,
+        /// Inject the OSC 133 mark scripts into the session shell. On by
+        /// default: marks are what make an exit code knowable, and every
+        /// fallback below them is a guess. `muxd run` turns it off for
+        /// `MUX_SHELL_INTEGRATION=0`, and a shell shellint has no scripts
+        /// for is unaffected either way.
+        shell_integration: bool = true,
+        /// Extra variables for the session shell, set after the injection's
+        /// own so a caller can override one. The shell-integration tests
+        /// point HOME at a temp directory with it: a shim that sources the
+        /// box's real rc files is a test whose verdict depends on whose box
+        /// it ran on, and this feature's whole job is to be right about
+        /// shells it did not configure.
+        extra_env: []const Pty.EnvPair = &.{},
+    };
+    pub fn init(alloc: std.mem.Allocator, opts: Options) !Server {
@@ @@ -283,7 +355,19 @@ pub const Server = struct { @@
+        const eng = try Engine.init(alloc, .{ .cols = opts.cols, .rows = opts.rows });
+        errdefer eng.deinit();
+        // Shell integration, decided and written before the fork: whatever
+        // the child is going to be told has to exist on disk by the time it
+        // execs, and a failure here is still cheap — no process yet.
+        var shellint_arena = std.heap.ArenaAllocator.init(alloc);
+        errdefer shellint_arena.deinit();
+        const plan = try prepareSpawn(shellint_arena.allocator(), opts);
+        var pty = try Pty.spawnArgv(.{
+            .cols = opts.cols,
+            .rows = opts.rows,
+            .argv = plan.argv,
+            .env = plan.env,
+        });
+        errdefer pty.deinit();
+        // Random rather than a counter or a timestamp: nothing on disk
@@ @@ -303,9 +387,61 @@ pub const Server = struct { @@
+            .sock_path = opts.sock_path,
+            .path_id = path_id,
+            .epoch = epoch,
+            .shellint_arena = shellint_arena,
+            .shellint_dir = plan.shellint_dir,
+        };
+    /// What `Pty.spawnArgv` has to be handed, once shell integration has
+    /// had its say. Every slice points into the arena `prepareSpawn` was
+    /// given, which must outlive the spawn — spawnArgv reads all of it in
+    /// the child, after the fork.
+    const SpawnPlan = struct {
+        argv: [*:null]const ?[*:0]const u8,
+        env: []const Pty.EnvPair,
+        /// Straight from the injection: the shim directory to delete at
+        /// teardown, or null when nothing was written.
+        shellint_dir: ?[]const u8,
+    };
+    /// Turn the session options into that plan. Split out of `init` because
+    /// it is the one part of starting a daemon that is neither the engine,
+    /// the pty nor the listener, and inlining it buried those three.
+    fn prepareSpawn(a: std.mem.Allocator, opts: Options) !SpawnPlan {
+        // Beside the socket: that directory is already private, already
+        // runtime-appropriate and already per-user, which is three
+        // properties the shims need and none of them are ours to re-derive.
+        // What the directory under it is CALLED, whether one was created,
+        // and what to say when the attempt fails are all shellint's —
+        // `install` reports the directory it made, so nothing here has to
+        // re-derive from the shell what that call already knew.
+        const injection: shellint.Injection = if (opts.shell_integration)
+            shellint.install(a, std.fs.path.dirname(opts.sock_path) orelse ".", opts.shell)
+        else
+            shellint.no_injection;
+        // shellint speaks its own EnvPair so it can stay a leaf, and so can
+        // pty; the daemon is the one place that knows about both, so the
+        // mapping lives here.
+        const env = try a.alloc(Pty.EnvPair, injection.env.len + opts.extra_env.len);
+        for (injection.env, env[0..injection.env.len]) |src, *dst| {
+            dst.* = .{ .key = src.key, .value = src.value };
+        }
+        // Last, so setenv's overwrite makes the caller's spelling the one
+        // the child sees (see the loop in Pty.spawnArgv).
+        @memcpy(env[injection.env.len..], opts.extra_env);
+        // argv is the shell plus whatever the injection adds, null-terminated
+        // for execve. With no extra argv and no env this is byte-identical to
+        // the old `Pty.spawn` call, which is what keeps a /bin/sh session
+        // exactly the session it was before shell integration existed.
+        const argv = try a.allocSentinel(?[*:0]const u8, 1 + injection.extra_argv.len, null);
+        argv[0] = opts.shell.ptr;
+        for (injection.extra_argv, argv[1..]) |src, *dst| dst.* = src.ptr;
+        return .{ .argv = argv.ptr, .env = env, .shellint_dir = injection.dir };
+    }
+    pub fn deinit(self: *Server) void {
+        for (&self.clients) |*slot| {
+            if (slot.*) |*c| {
@@ @@ -354,6 +490,12 @@ pub const Server = struct { @@
+        self.tracker.deinit(self.alloc);
+        self.pty.deinit();
+        // After the pty, so the shell is gone before the files it was
+        // reading are: a shim removed out from under a live shell would be
+        // a session that half-sourced its own integration. Best-effort —
+        // a daemon that cannot tidy /tmp must still exit.
+        if (self.shellint_dir) |dir| std.fs.cwd().deleteTree(dir) catch {};
+        self.shellint_arena.deinit();
+        self.eng.deinit();
@@ @@ -427,6 +569,10 @@ pub const Server = struct { @@
+            var buf: [64 * 1024]u8 = undefined;
+            const n = std.posix.read(self.pty.master, &buf) catch 0;
+            if (n > 0) {
+                // Stamped on arrival, before anything is made of the bytes:
+                // the settle floor measures silence on the wire, not how
+                // long the engine took to digest what broke it.
+                self.last_pty_ms = std.time.milliTimestamp();
+                self.eng.feed(buf[0..n]);
+                const resp = self.eng.ptyOutput();
+                if (resp.len > 0) {
@@ @@ -434,6 +580,7 @@ pub const Server = struct { @@
+                    self.eng.clearPtyOutput();
+                self.sendUpdate();
+                self.drainMarkEvents();
@@ @@ -473,6 +620,14 @@ pub const Server = struct { @@
+        // After every arm that can move the session on, so an await sees the
+        // marks, the pgid and the output silence that this pump produced
+        // rather than last pump's — and before the QUIC drain below, because
+        // an await resolving here queues a frame and drainAll is what puts a
+        // QUIC client's queued bytes on the wire. The other order would cost
+        // every remote await a whole extra poll cycle.
+        self.checkAwaits();
+        // Last, and deliberately at the very end of the pump: the listener's
+        // send only QUEUES now (draining from inside an ngtcp2 callback is
+        // the defect that change exists to remove), so this is where a QUIC
@@ @@ -939,6 +1094,27 @@ pub const Server = struct { @@
+        _ = self.queueFrame(i, .pty_mode, &proto.encodePtyMode(flags));
+    /// Tell one client the command state it arrived too late to witness.
+    /// Same gap sendPtyModeTo closes, one level up: cmd_state is only ever
+    /// pushed on a transition, so a client attaching between two commands
+    /// would otherwise know nothing until the next one happened.
+    ///
+    /// Gated on marks_seen, which keeps the rule that a cmd_state push means
+    /// a mark was read and never that a heuristic guessed — a session that
+    /// has never spoken marks has nothing honest to say here, and says
+    /// nothing. (`muxa status` is the way to ask about such a session; it
+    /// reports the regime rather than claiming a transition.)
+    ///
+    /// Sent after the resync rather than before it, which is the opposite of
+    /// sendPtyModeTo's ordering and for the same underlying reason: start_row
+    /// and end_row point into the grid, so the client must already hold the
+    /// grid they point into. Mode bits describe how to read bytes that have
+    /// not arrived yet; rows describe bytes that have.
+    fn sendCmdStateTo(self: *Server, i: usize) void {
+        if (!self.cmd.marks_seen) return;
+        _ = self.queueFrame(i, .cmd_state, &proto.encodeCmdState(self.cmdState(.marks)));
+    }
+    fn hasClients(self: *const Server) bool {
+        for (self.clients) |slot| {
+            if (slot != null) return true;
@@ @@ -1014,30 +1190,27 @@ pub const Server = struct { @@
+        while (true) {
+            if (self.clients[i] == null) return; // a handler dropped it
+            // Same walk as the client's, out of proto: a length the peer
+            // chose is gated there, and a partial tail is null rather than
+            // an error. What differs is the verdict on a bad length — this
+            // side has a connection it can drop, and does.
+            const d = proto.delimitFrame(self.clients[i].?.inbound.items) catch {
+                self.dropClient(i);
+                return;
+            } orelse return; // header or payload still coming
+            // Copied out before handling: a handler may queue sends, and
+            // anything that touches this slot could reallocate `inbound`
+            // underneath a slice into it.
+            const payload = self.alloc.alloc(u8, d.payload.len) catch {
+                self.dropClient(i);
+                return;
+            };
+            defer self.alloc.free(payload);
+            @memcpy(payload, d.payload);
+            const frame: proto.Frame = .{ .type = d.type, .payload = payload };
+            const consumed = d.consumed;
+            const slot = &self.clients[i].?;
+            const rest = slot.inbound.items.len - consumed;
+            std.mem.copyForwards(u8, slot.inbound.items[0..rest], slot.inbound.items[consumed..]);
@@ @@ -1073,6 +1246,7 @@ pub const Server = struct { @@
+                // holding grid content it has no mode for.
+                self.sendPtyModeTo(i);
+                self.sendResync(i, req.have_seq, req.have_epoch, size_changed and applied);
+                self.sendCmdStateTo(i);
+            },
+            .resize => {
+                // Latest wins: whoever resized last sets the grid, and the
@@ @@ -1150,10 +1324,128 @@ pub const Server = struct { @@
+                defer self.alloc.free(dump);
+                _ = self.queueFrame(i, .dump_reply, dump);
+            },
+            .status_req => {
+                const payload = proto.encodeStatusReply(self.buildStatusReply());
+                _ = self.queueFrame(i, .status_reply, &payload);
+            },
+            .await_req => {
+                const req = proto.decodeAwaitReq(frame.payload) catch return;
+                if (self.clients[i] == null) return;
+                self.clients[i].?.await_state = .{
+                    .since_seq = req.since_seq,
+                    .settle_ms = req.settle_ms,
+                    .timeout_ms = req.timeout_ms,
+                    .started_ms = std.time.milliTimestamp(),
+                };
+                // A return that already happened answers immediately — this
+                // is what makes a reconnect re-issue safe. The request is
+                // answered inside this pump either way, since the pump-end
+                // pass runs after frame handling; this call keeps that true
+                // independent of pump-end ordering.
+                self.checkAwaits();
+            },
+            else => {},
+    /// Resolve any awaits that can be answered this pump. Granularity is
+    /// the run loop's 100ms tick — nothing here blocks, and no deadline
+    /// folding into poll is needed at that resolution.
+    fn checkAwaits(self: *Server) void {
+        const now = std.time.milliTimestamp();
+        // One ioctl for the whole pump, not one per waiting client: the
+        // foreground process group is a property of the pty, so every client
+        // in this loop would read the same number back. Null covers both
+        // "marks hold the floor, so nobody asked" — the probe is skipped
+        // entirely then, exactly as before — and "the ioctl failed", which
+        // has always been silently ignored. What stays per-client is
+        // `saw_busy`: the transition each await is watching for is its own.
+        const fg_pgid: ?std.posix.pid_t = if (self.cmd.marksOpen())
+            null
+        else
+            self.pty.fgPgid() catch null;
+        for (0..max_clients) |i| {
+            if (self.clients[i] == null) continue;
+            const slot = &self.clients[i].?;
+            if (slot.await_state == null) continue;
+            const a = &slot.await_state.?;
+            // 1. Marks: a return newer than since_seq answers with the full
+            //    story. Strictly greater: since_seq is "what I have".
+            //
+            //    The watermark alone decides, and it is the snapshot's own
+            //    seq — the answer and the reason it qualifies are the same
+            //    record, so no reading of live tracker state can drift out
+            //    from under this test. Gating on
+            //    `cmd.phase == .returned` here was a defect: the shell's own
+            //    `D;code`+`A` burst lands in one pty read, so phase is back
+            //    to at_prompt before this line ever runs. Keying on the
+            //    watermark also answers correctly once the NEXT command is
+            //    already running — the client asked what had returned since
+            //    its seq, not what is happening now.
+            if (self.last_return) |st| {
+                if (st.seq > a.since_seq) {
+                    self.answerAwait(i, st, .returned);
+                    continue;
+                }
+            }
+            // 2. pgid: only when marks do not hold the floor (folded into
+            //    fg_pgid above). The shell is the session leader, so its pid
+            //    is the resting pgid.
+            if (fg_pgid) |pg| {
+                if (pg != self.pty.child) {
+                    a.saw_busy = true;
+                } else if (a.saw_busy) {
+                    // The pgid went out and came back: something ran and is
+                    // over. WHAT its code was, this mechanism cannot say.
+                    const st = self.fallbackState(.pgid, .{
+                        .phase = .returned,
+                        .clear_exit_code = true,
+                    });
+                    self.answerAwait(i, st, .returned);
+                    continue;
+                }
+            }
+            // 3. Settle: output silence, if the caller asked for a floor.
+            if (a.settle_ms > 0 and self.last_pty_ms > 0 and
+                now - self.last_pty_ms >= a.settle_ms and
+                now - a.started_ms >= a.settle_ms)
+            {
+                // Phase is left as the session's own: silence says the
+                // output stopped, never that a command returned.
+                const st = self.fallbackState(.settle, .{ .clear_exit_code = true });
+                self.answerAwait(i, st, .settled);
+                continue;
+            }
+            // 4. Timeout: the bound the client set on the whole wait. 0 is
+            //    not a zero-length deadline but the absence of one — such an
+            //    await ends only when marks, the pgid or settle end it.
+            if (a.timeout_ms > 0 and now - a.started_ms >= a.timeout_ms) {
+                // Nothing is overridden but the seq: a timeout reports the
+                // session exactly as it stands, mid-command and all, and on
+                // a marks session that includes an exit code still standing
+                // from the command before this one.
+                const st = self.fallbackState(
+                    if (self.cmd.marks_seen) .marks else .pgid,
+                    .{},
+                );
+                self.answerAwait(i, st, .timeout);
+                continue;
+            }
+        }
+    }
+    fn answerAwait(self: *Server, i: usize, st: proto.CmdState, reason: proto.AwaitReason) void {
+        if (self.clients[i] == null) return;
+        self.clients[i].?.await_state = null;
+        const payload = proto.encodeAwaitReply(st, reason);
+        _ = self.queueFrame(i, .await_reply, &payload);
+    }
+    fn serviceObserver(self: *Server, i: usize) void {
+        const fd = self.observers[i].?;
+        const frame = proto.readFrame(self.alloc, fd) catch {
@@ @@ -1197,6 +1489,7 @@ pub const Server = struct { @@
+                // refused one: the size differs but the grid never moved,
+                // so there is nothing to repaint anyone else for.
+                self.sendResync(slot, sz.have_seq, sz.have_epoch, size_changed and applied);
+                self.sendCmdStateTo(slot);
+            },
+            .debug_dump => self.replyDumpObserver(fd, frame.payload) catch self.dropObserver(i),
+            .stats_req => self.replyStatsObserver(fd) catch self.dropObserver(i),
@@ @@ -1209,6 +1502,13 @@ pub const Server = struct { @@
+                const payload = proto.encodeEndpointReply(self.endpointPort());
+                proto.writeFrame(fd, .endpoint_reply, &payload) catch self.dropObserver(i);
+            },
+            // Where `muxa status` actually lands: it asks and exits without
+            // ever attaching. Blocking reply for the same reason the stats
+            // and endpoint arms use one — an observer has no send queue.
+            .status_req => {
+                const payload = proto.encodeStatusReply(self.buildStatusReply());
+                proto.writeFrame(fd, .status_reply, &payload) catch self.dropObserver(i);
+            },
+            else => {},
@@ @@ -1344,6 +1644,114 @@ pub const Server = struct { @@
+    /// Fold the engine's OSC 133 events into the command tracker and tell
+    /// attached clients about transitions. Runs after sendUpdate so
+    /// tracker.seq already covers the same pty chunk — the off-by-one the
+    /// spec pins (seq sampled post-feed).
+    ///
+    /// The pump's pty-read arm is the only caller, so marks produced by a
+    /// test that feeds the engine directly (srv.eng.feed) sit pending until
+    /// a read arm runs — they are not lost, but they are not folded yet.
+    fn drainMarkEvents(self: *Server) void {
+        for (self.eng.markEvents()) |ev| {
+            const tr = self.cmd.apply(ev) orelse continue;
+            if (tr == .returned) {
+                // Copied out of the tracker while it still describes this
+                // command — the `A` that ends the burst is usually the very
+                // next event in this same loop, and the next command's `C`
+                // clears the exit code outright.
+                self.last_return = .{
+                    .phase = .returned,
+                    .mechanism = .marks,
+                    .exit_code = self.cmd.exit_code,
+                    .start_row = self.cmd.start_row,
+                    .end_row = self.cmd.end_row,
+                    .seq = self.tracker.seq,
+                };
+            }
+            if (tr == .reset) continue; // believed nothing, tell no one
+            const payload = proto.encodeCmdState(self.cmdState(.marks));
+            for (0..max_clients) |i| {
+                _ = self.queueFrame(i, .cmd_state, &payload);
+            }
+        }
+        self.eng.clearMarkEvents();
+    }
+    /// The current command state as a wire struct. `mechanism` is the
+    /// caller's claim about how the verdict was reached: marks pushes say
+    /// .marks; await resolutions say what actually resolved them.
+    fn cmdState(self: *Server, mechanism: proto.Mechanism) proto.CmdState {
+        return .{
+            .phase = self.cmd.phase,
+            .mechanism = mechanism,
+            .exit_code = self.cmd.exit_code,
+            .start_row = self.cmd.start_row,
+            .end_row = self.cmd.end_row,
+            // The return watermark, read off its one owner. Absent means no
+            // command has returned this session, which is exactly what 0
+            // has always meant on the wire.
+            .seq = if (self.last_return) |lr| lr.seq else 0,
+        };
+    }
+    /// The state an await resolved by something OTHER than the marks stream
+    /// answers with: `cmdState` for the live picture, then the overrides
+    /// that mechanism is entitled to make. One owner for all of them,
+    /// because the three fallback arms in `checkAwaits` differ only in
+    /// which overrides they take, and hand-patching the struct at each site
+    /// made a set of deliberate differences look like three drifting copies.
+    ///
+    /// The seq override is unconditional and is the subtle one: it replaces
+    /// cmdState's RETURN watermark with the delta tracker's current seq.
+    /// That is deliberate — it orders the reply against the grid content
+    /// the client has, which is what a fallback answer is actually about —
+    /// and it is why proto.CmdState.seq documents two meanings. A client
+    /// that took its next `since_seq` from here would be using a number
+    /// from the wrong series; see that doc comment for the rule and for the
+    /// open question of whether these arms should move the watermark at all.
+    ///
+    /// `phase` and `clear_exit_code` default to leaving what cmdState built:
+    /// a mechanism overrides only what it can actually claim to know.
+    fn fallbackState(
+        self: *Server,
+        mechanism: proto.Mechanism,
+        overrides: struct {
+            phase: ?proto.CmdPhase = null,
+            clear_exit_code: bool = false,
+        },
+    ) proto.CmdState {
+        var st = self.cmdState(mechanism);
+        if (overrides.phase) |p| st.phase = p;
+        // Only marks can know a code (proto.Mechanism says so); a fallback
+        // that passed one through would be attributing the PREVIOUS
+        // command's verdict to this one.
+        if (overrides.clear_exit_code) st.exit_code = null;
+        st.seq = self.tracker.seq;
+        return st;
+    }
+    fn buildStatusReply(self: *Server) proto.StatusReply {
+        const cur = self.eng.cursorPos();
+        return .{
+            .cols = self.colsNow(),
+            .rows = self.rowsNow(),
+            .cursor_x = cur.x,
+            .cursor_y = cur.y,
+            .history_rows = self.eng.historyRows(),
+            .alt_screen = self.eng.onAltScreen(),
+            // Live read, then the last one that worked, then a default. The
+            // middle term is the one worth having: mode_sent is refreshed
+            // from a real tcgetattr every pump, so if this read is the one
+            // that fails there is a remembered truth to report instead of a
+            // fabricated "canonical and echoing" that may be the opposite of
+            // what the session is doing.
+            .mode = self.readPtyMode() orelse
+                (self.mode_sent orelse .{ .icanon = true, .echo = true }),
+            .cmd = self.cmdState(if (self.cmd.marks_seen) .marks else .pgid),
+        };
+    }
+    /// The snapshot payload for the grid as it stands: the fixed prefix ++
+    /// full-state dump. Caller owns the result. Reads tracker.seq, so it
+    /// must be called after the rebuild that stamps it.
+    // resolution is never reached — all-null env would otherwise return 0.
+    try std.testing.expectEqual(port, srv.endpointPortFrom(null, null, null));
+test "Server: OSC 133 marks reach attached clients as cmd_state pushes" {
+    const alloc = std.testing.allocator;
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    const dir_path = tmp.path();
+    const sock_path = try std.fmt.allocPrint(alloc, "{s}/marks.sock", .{dir_path});
+    defer alloc.free(sock_path);
+    // A scripted session rather than an interactive shell, for the same
+    // reason the pty-mode test uses one: an interactive shell emits marks
+    // only once somebody has installed shell integration into it, and then
+    // emits them continuously. This child emits one mark when told to and
+    // none otherwise, so "which push came from which mark" is not a guess.
+    // It ends on a blocking read so deinit's SIGTERM lands on the shell
+    // itself and leaves nothing running behind the test.
+    try tmp.dir.writeFile(.{
+        .sub_path = "marks.sh",
+        .data =
+        \\#!/bin/sh
+        \\read -r start
+        \\printf '\033]133;C\007'
+        \\read -r second
+        \\printf '\033]133;D;0\007'
+        \\read -r stop
+        \\
+        ,
+        .flags = .{ .mode = 0o755 },
+    });
+    const script = try std.fmt.allocPrintSentinel(alloc, "{s}/marks.sh", .{dir_path}, 0);
+    defer alloc.free(script);
+    var srv = try Server.init(alloc, .{ .sock_path = sock_path, .shell = script });
+    defer srv.deinit();
+    const c = try std.net.connectUnixSocket(sock_path);
+    defer c.close();
+    try proto.writeFrame(c.handle, .attach, &proto.encodeAttach(80, 24, 0, 0));
+    // Release the script into its C. The keystroke is echoed by the line
+    // discipline, so this pty chunk carries grid content as well as the
+    // mark — which is the point: the push has to survive sharing a read
+    // with ordinary output.
+    try proto.writeFrame(c.handle, .input, "go\n");
+    const f1 = (try awaitFrame(alloc, &srv, c.handle, .cmd_state, 500)) orelse
+        return error.NoRunningPush;
+    defer f1.deinit(alloc);
+    const running = try proto.decodeCmdState(f1.payload);
+    try std.testing.expectEqual(proto.CmdPhase.running, running.phase);
+    // Marks are the only mechanism that ever pushes: a push means a mark was
+    // read, never that a heuristic guessed.
+    try std.testing.expectEqual(proto.Mechanism.marks, running.mechanism);
+    // And into its D, which closes the command with a code.
+    try proto.writeFrame(c.handle, .input, "go\n");
+    const f2 = (try awaitFrame(alloc, &srv, c.handle, .cmd_state, 500)) orelse
+        return error.NoReturnedPush;
+    defer f2.deinit(alloc);
+    const returned = try proto.decodeCmdState(f2.payload);
+    try std.testing.expectEqual(proto.CmdPhase.returned, returned.phase);
+    try std.testing.expectEqual(proto.Mechanism.marks, returned.mechanism);
+    try std.testing.expectEqual(@as(?u8, 0), returned.exit_code);
+    // The seq field is a last-return watermark, not a stamp on the frame
+    // carrying it: it answers "a return happened at or before this seq".
+    // So the running push of the first command this session ever ran says
+    // 0 — nothing has returned yet — and a consumer reading it as "when
+    // this command started" would be reading about a different event.
+    try std.testing.expectEqual(@as(u64, 0), running.seq);
+    // The return moves the watermark to the tracker as sampled after the
+    // update for its own pty chunk, so it covers the command's own output.
+    // Ordering only: a C and a D arriving in one read legitimately share a
+    // seq, so this is >= and not >, and the upper bound is the tracker as
+    // it stands now.
+    try std.testing.expect(returned.seq >= running.seq);
+    try std.testing.expect(returned.seq <= srv.tracker.seq);
+    try std.testing.expect(returned.seq > 0);
+}
+// ---------------------------------------------------------------------------
+// Shell integration, end to end. Everything above this line proves the daemon
+// can read marks; these two prove a real shell EMITS them, which is the only
+// version of the claim that matters in a session. The chain under test is
+// injection -> shell -> pty -> engine -> tracker -> wire, and no part of it is
+// stubbed.
+// ---------------------------------------------------------------------------
+/// Pump for `budget_ms` and report whether any `returned` push turned up.
+/// The absence half of the phantom-mark assertions: a session that has been
+/// told to run nothing must claim nothing returned.
+fn anyReturnWithin(
+    alloc: std.mem.Allocator,
+    srv: *Server,
+    fd: std.posix.fd_t,
+    budget_ms: i64,
+) !?proto.CmdState {
+    const deadline = std.time.milliTimestamp() + budget_ms;
+    while (std.time.milliTimestamp() < deadline) {
+        _ = try srv.pumpOnce(5);
+        var pfd = [_]std.posix.pollfd{
+            .{ .fd = fd, .events = std.posix.POLL.IN, .revents = 0 },
+        };
+        if ((std.posix.poll(&pfd, 1) catch 0) == 0) continue;
+        const frame = (try proto.readFrame(alloc, fd)) orelse return null;
+        defer frame.deinit(alloc);
+        if (frame.type != .cmd_state) continue;
+        const st = try proto.decodeCmdState(frame.payload);
+        if (st.phase == .returned) return st;
+    }
+    return null;
+}
+/// Pump until the session's grid contains `needle`. The liveness half: an
+/// assertion that no mark arrived is worthless against a shell that never
+/// started, so every absence check below waits for the shell to say hello
+/// on the grid first.
+fn awaitGridText(
+    alloc: std.mem.Allocator,
+    srv: *Server,
+    needle: []const u8,
+    budget_ms: i64,
+) !bool {
+    const deadline = std.time.milliTimestamp() + budget_ms;
+    while (std.time.milliTimestamp() < deadline) {
+        _ = try srv.pumpOnce(5);
+        const grid = try srv.eng.dumpPlain(alloc);
+        defer alloc.free(grid);
+        if (std.mem.indexOf(u8, grid, needle) != null) return true;
+    }
+    return false;
+}
+/// A session whose HOME is a directory this test wrote, so the verdict does
+/// not depend on whose rc files the box carries. The rc it plants is not
+/// empty: it adds a PROMPT_COMMAND member of its own, which is the shape
+/// that broke the bash shim (a member firing the DEBUG trap on every idle
+/// prompt cycle), and an unmistakable PS1 to wait on.
+const IntegratedSession = struct {
+    tmp: TmpDir,
+    home: [:0]const u8,
+    sock_path: []const u8,
+    srv: Server,
+    conn: std.net.Stream,
+    const prompt = "MUXPROMPT>";
+    fn start(alloc: std.mem.Allocator, shell: [:0]const u8, tag: []const u8, rc: []const u8) !*IntegratedSession {
+        const self = try alloc.create(IntegratedSession);
+        errdefer alloc.destroy(self);
+        self.tmp = try TmpDir.make();
+        errdefer self.tmp.cleanup();
+        try self.tmp.dir.makePath("home");
+        var home_dir = try self.tmp.dir.openDir("home", .{});
+        defer home_dir.close();
+        try home_dir.writeFile(.{ .sub_path = rcName(shell), .data = rc });
+        self.home = try std.fmt.allocPrintSentinel(alloc, "{s}/home", .{self.tmp.path()}, 0);
+        errdefer alloc.free(self.home);
+        self.sock_path = try std.fmt.allocPrint(alloc, "{s}/{s}.sock", .{ self.tmp.path(), tag });
+        errdefer alloc.free(self.sock_path);
+        self.srv = try Server.init(alloc, .{
+            .sock_path = self.sock_path,
+            .shell = shell,
+            .extra_env = &.{
+                .{ .key = "HOME", .value = self.home },
+                // Emptied, and that is not cosmetic. shellint.prepare copies
+                // the DAEMON's ZDOTDIR into MUX_ORIG_ZDOTDIR, and here the
+                // daemon is the test runner — so on a box whose runner has
+                // ZDOTDIR set, the zsh shim would restore it and source THAT
+                // .zshrc, sailing straight past the HOME planted above. The
+                // shim reads an empty value as "there was none" and falls
+                // back to $HOME, which is the hermetic answer. extra_env is
+                // applied after the injection's own pairs, so this wins.
+                .{ .key = "MUX_ORIG_ZDOTDIR", .value = "" },
+            },
+        });
+        errdefer self.srv.deinit();
+        // The shim really was written where the daemon says it was. Without
+        // this, a missing directory would present as "no marks ever arrived"
+        // and the timeout would never say why.
+        try std.testing.expect(self.srv.shellint_dir != null);
+        try std.fs.cwd().access(self.srv.shellint_dir.?, .{});
+        self.conn = try std.net.connectUnixSocket(self.sock_path);
+        errdefer self.conn.close();
+        try proto.writeFrame(self.conn.handle, .attach, &proto.encodeAttach(80, 24, 0, 0));
+        return self;
+    }
+    fn rcName(shell: [:0]const u8) []const u8 {
+        return if (shellint.detect(shell) == .zsh) ".zshrc" else ".bashrc";
+    }
+    fn deinit(self: *IntegratedSession, alloc: std.mem.Allocator) void {
+        self.conn.close();
+        self.srv.deinit();
+        alloc.free(self.sock_path);
+        alloc.free(self.home);
+        self.tmp.cleanup();
+        alloc.destroy(self);
+    }
+};
+/// The bash rc a real box hands the shim: Arch's /etc/bash.bashrc appends a
+/// PROMPT_COMMAND member under any xterm* TERM, and muxd sets exactly that.
+/// This plants the same shape explicitly rather than relying on the system
+/// file being there, so the test states its own premise.
+const bash_rc_with_prompt_member =
+    \\PS1='MUXPROMPT>'
+    \\PROMPT_COMMAND+=(': mux-test-member')
+    \\
+;
+test "Server: bash emits one mark pair per command, and none at an idle prompt" {
+    const alloc = std.testing.allocator;
+    std.fs.cwd().access("/bin/bash", .{}) catch return error.SkipZigTest;
+    const s = try IntegratedSession.start(alloc, "/bin/bash", "bash", bash_rc_with_prompt_member);
+    defer s.deinit(alloc);
+    // Wait for the first prompt, so what follows is an assertion about a
+    // live shell rather than about a slow one.
+    try std.testing.expect(try awaitGridText(alloc, &s.srv, IntegratedSession.prompt, 10_000));
+    // NOTHING has been asked to run, so nothing may claim to have returned.
+    //
+    // This is the regression that shipped: the DEBUG trap was armed one line
+    // before the PROMPT_COMMAND assignment, so it fired ON that assignment
+    // and the very first prompt reported `D;0` for a command that never
+    // existed. Measured on a real bash before the fix, the session opened
+    // {C:PROMPT_COMMAND=...}{D;0}{A} — and the earlier version of this test
+    // was satisfied by that phantom rather than by the command it sent.
+    if (try anyReturnWithin(alloc, &s.srv, s.conn.handle, 400)) |ghost| {
+        std.debug.print("phantom return at the opening prompt: {any}\n", .{ghost});
+        return error.PhantomReturnBeforeAnyCommand;
+    }
+    // Now a real command, with a code no fallback could invent. `false`
+    // rather than `true`: an exit code of 1 cannot be confused with the 0
+    // that a phantom D carries.
+    try proto.writeFrame(s.conn.handle, .input, "false\n");
+    const st = (try anyReturnWithin(alloc, &s.srv, s.conn.handle, 10_000)) orelse
+        return error.NoReturnedPush;
+    try std.testing.expectEqual(proto.Mechanism.marks, st.mechanism);
+    try std.testing.expectEqual(@as(?u8, 1), st.exit_code);
+    // A bare Enter runs PROMPT_COMMAND again and no command at all. Its
+    // members fire the DEBUG trap, and before the membership check they
+    // re-armed the shim — so an untouched prompt reported a successful
+    // command on every cycle. Three Enters produced four phantom `D;0`s on
+    // a real bash; the correct answer is none.
+    try proto.writeFrame(s.conn.handle, .input, "\n\n\n");
+    if (try anyReturnWithin(alloc, &s.srv, s.conn.handle, 600)) |ghost| {
+        std.debug.print("phantom return at an idle prompt: {any}\n", .{ghost});
+        return error.PhantomReturnAtIdlePrompt;
+    }
+}
+/// zsh's equivalent premise: a precmd hook of the user's own, registered
+/// BEFORE mux's — the shim sources the user's rc first, so theirs is first
+/// in precmd_functions and runs first.
+///
+/// It returns 3 deliberately. A hook returning 0 would prove nothing: the
+/// commands under test exit 0 or 1, and a shim reading the wrong $? would
+/// still look right half the time. 3 is a value only the hook can produce,
+/// so the reported code names its own source. (zsh hands each precmd hook
+/// the original command's status rather than the previous hook's, which is
+/// what makes mux's reading safe; measured on this box before it was
+/// asserted here.)
+const zsh_rc_with_precmd_hook =
+    \\PS1='MUXPROMPT>'
+    \\autoload -Uz add-zsh-hook
+    \\_user_precmd() { return 3 }
+    \\add-zsh-hook precmd _user_precmd
+    \\
+;
+test "Server: zsh emits one mark pair per command, and none at an idle prompt" {
+    const alloc = std.testing.allocator;
+    // Both spellings, because the box that has zsh does not always agree
+    // with the box that had it last.
+    const shell: [:0]const u8 = blk: {
+        for ([_][:0]const u8{ "/usr/bin/zsh", "/bin/zsh" }) |p| {
+            std.fs.cwd().access(p, .{}) catch continue;
+            break :blk p;
+        }
+        return error.SkipZigTest;
+    };
+    const s = try IntegratedSession.start(alloc, shell, "zsh", zsh_rc_with_precmd_hook);
+    defer s.deinit(alloc);
+    try std.testing.expect(try awaitGridText(alloc, &s.srv, IntegratedSession.prompt, 10_000));
+    // The guarded D earns its keep here: zsh's precmd runs at the opening
+    // prompt too, and without the `_mux_ran` guard it would report a return
+    // before the session had run anything.
+    if (try anyReturnWithin(alloc, &s.srv, s.conn.handle, 400)) |ghost| {
+        std.debug.print("phantom return at the opening prompt: {any}\n", .{ghost});
+        return error.PhantomReturnBeforeAnyCommand;
+    }
+    try proto.writeFrame(s.conn.handle, .input, "false\n");
+    const st = (try anyReturnWithin(alloc, &s.srv, s.conn.handle, 10_000)) orelse
+        return error.NoReturnedPush;
+    try std.testing.expectEqual(proto.Mechanism.marks, st.mechanism);
+    // 1, not 0: mux's precmd reads $? before the user's hook can overwrite
+    // it, which is the property the shim's hook ordering exists to keep.
+    try std.testing.expectEqual(@as(?u8, 1), st.exit_code);
+    try proto.writeFrame(s.conn.handle, .input, "\n\n\n");
+    if (try anyReturnWithin(alloc, &s.srv, s.conn.handle, 600)) |ghost| {
+        std.debug.print("phantom return at an idle prompt: {any}\n", .{ghost});
+        return error.PhantomReturnAtIdlePrompt;
+    }
+}
+test "Server: the shim directory is private, and teardown takes it with it" {
+    const alloc = std.testing.allocator;
+    std.fs.cwd().access("/bin/bash", .{}) catch return error.SkipZigTest;
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    const sock_path = try std.fmt.allocPrint(alloc, "{s}/shim.sock", .{tmp.path()});
+    defer alloc.free(sock_path);
+    // Copied out of the server's arena before deinit frees it: the whole
+    // point of this test is to ask a question after the server is gone.
+    var dir_buf: [256]u8 = undefined;
+    var dir: []const u8 = undefined;
+    {
+        var srv = try Server.init(alloc, .{ .sock_path = sock_path, .shell = "/bin/bash" });
+        defer srv.deinit();
+        dir = try std.fmt.bufPrint(&dir_buf, "{s}", .{srv.shellint_dir.?});
+        // Beside the socket, not somewhere world-readable: the file the
+        // session shell is about to source is a file that runs code as this
+        // user, so 0700 on the directory is part of the contract.
+        try std.testing.expectEqualStrings(std.fs.path.dirname(sock_path).?, std.fs.path.dirname(dir).?);
+        var d = try std.fs.cwd().openDir(dir, .{ .iterate = true });
+        defer d.close();
+        const st = try d.stat();
+        try std.testing.expectEqual(@as(u32, 0o700), @as(u32, @intCast(st.mode & 0o777)));
+    }
+    // A daemon that left its shims behind would litter the runtime directory
+    // once per session, and nothing else in the system would ever notice.
+    try std.testing.expectError(error.FileNotFound, std.fs.cwd().access(dir, .{}));
+}
+test "Server: a shim directory that cannot be created costs the marks, not the session" {
+    const alloc = std.testing.allocator;
+    std.fs.cwd().access("/bin/bash", .{}) catch return error.SkipZigTest;
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    const sock_path = try std.fmt.allocPrint(alloc, "{s}/degrade.sock", .{tmp.path()});
+    defer alloc.free(sock_path);
+    // Plant a regular FILE exactly where init will want its shim directory.
+    // The path is knowable in advance because init names it after the
+    // daemon's pid, and in a test the daemon IS this process — which is also
+    // the realistic field version of this: a SIGKILLed daemon leaves an entry
+    // behind and a later daemon draws the same pid.
+    const planted = try std.fmt.allocPrint(
+        alloc,
+        "{s}/mux-shellint-{d}",
+        .{ tmp.path(), std.os.linux.getpid() },
+    );
+    defer alloc.free(planted);
+    try std.fs.cwd().writeFile(.{ .sub_path = planted, .data = "not a directory" });
+    // The daemon still starts. This is the whole claim: marks are an
+    // enhancement, and a session that cannot have them is still a session.
+    // (init prints one line to stderr on the way past; that is the point of
+    // it not being silent.)
+    // Scoped so deinit runs before the survival check below.
+    {
+        var srv = try Server.init(alloc, .{ .sock_path = sock_path, .shell = "/bin/bash" });
+        defer srv.deinit();
+        // Nothing to tear down later, because nothing was created.
+        try std.testing.expectEqual(@as(?[]const u8, null), srv.shellint_dir);
+        // ...and the session actually works. A daemon that starts and then
+        // cannot answer would satisfy every assertion above.
+        const c = try std.net.connectUnixSocket(sock_path);
+        defer c.close();
+        try proto.writeFrame(c.handle, .attach, &proto.encodeAttach(80, 24, 0, 0));
+        try proto.writeFrame(c.handle, .status_req, "");
+        const f = (try awaitFrame(alloc, &srv, c.handle, .status_reply, 400)) orelse
+            return error.NoStatusReply;
+        defer f.deinit(alloc);
+        const st = try proto.decodeStatusReply(f.payload);
+        try std.testing.expectEqual(@as(u16, 80), st.cols);
+        // pgid, not marks: the session is honestly running on the fallbacks.
+        try std.testing.expectEqual(proto.Mechanism.pgid, st.cmd.mechanism);
+    }
+    // The planted file is still there. Teardown deletes the shim tree by
+    // path, so a version that recorded the directory even when prepare
+    // failed would delete something this daemon never created — and in the
+    // field that path belongs to whatever else drew the pid.
+    const kept = try std.fs.cwd().readFileAlloc(alloc, planted, 64);
+    defer alloc.free(kept);
+    try std.testing.expectEqualStrings("not a directory", kept);
+}
+test "Server: an unknown shell is not injected into at all — no directory, no shim" {
+    const alloc = std.testing.allocator;
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    const sock_path = try std.fmt.allocPrint(alloc, "{s}/plain.sock", .{tmp.path()});
+    defer alloc.free(sock_path);
+    // Integration is ON, and /bin/sh still gets nothing: this is what keeps
+    // every other test in this file describing the session it always did.
+    var srv = try Server.init(alloc, .{ .sock_path = sock_path, .shell = "/bin/sh" });
+    defer srv.deinit();
+    try std.testing.expectEqual(@as(?[]const u8, null), srv.shellint_dir);
+    // Nothing was written beside the socket either — the absence is on disk,
+    // not merely in a field the teardown consults.
+    var d = try std.fs.cwd().openDir(tmp.path(), .{ .iterate = true });
+    defer d.close();
+    var it = d.iterate();
+    while (try it.next()) |entry| {
+        try std.testing.expect(!std.mem.startsWith(u8, entry.name, "mux-shellint-"));
+    }
+}
+test "Server: status_req is answered on an attached client and on a bare observer" {
+    const alloc = std.testing.allocator;
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    const dir_path = tmp.path();
+    const sock_path = try std.fmt.allocPrint(alloc, "{s}/status.sock", .{dir_path});
+    defer alloc.free(sock_path);
+    // /bin/cat: a session that produces no output of its own, so nothing
+    // moves the state these assertions describe.
+    var srv = try Server.init(alloc, .{ .sock_path = sock_path, .shell = "/bin/cat" });
+    defer srv.deinit();
+    const c = try std.net.connectUnixSocket(sock_path);
+    defer c.close();
+    try proto.writeFrame(c.handle, .attach, &proto.encodeAttach(80, 24, 0, 0));
+    try proto.writeFrame(c.handle, .status_req, "");
+    const f = (try awaitFrame(alloc, &srv, c.handle, .status_reply, 400)) orelse
+        return error.NoAttachedStatusReply;
+    defer f.deinit(alloc);
+    const st = try proto.decodeStatusReply(f.payload);
+    try std.testing.expectEqual(@as(u16, 80), st.cols);
+    try std.testing.expectEqual(@as(u16, 24), st.rows);
+    try std.testing.expect(!st.alt_screen);
+    try std.testing.expectEqual(proto.CmdPhase.at_prompt, st.cmd.phase);
+    // No C has ever been seen on this session, so the reply reports the
+    // regime it is actually in — pgid, not marks. That field is a report of
+    // which mechanism would decide, not a claim that one just did.
+    try std.testing.expectEqual(proto.Mechanism.pgid, st.cmd.mechanism);
+    // `muxa status` never attaches, so the observer arm is the load-bearing
+    // one — same reasoning as endpoint_req's, and the same failure if it is
+    // missing: the frame falls into `else => {}` and the caller hangs.
+    const obs = try std.net.connectUnixSocket(sock_path);
+    defer obs.close();
+    try proto.writeFrame(obs.handle, .status_req, "");
+    const f2 = (try awaitFrame(alloc, &srv, obs.handle, .status_reply, 400)) orelse
+        return error.NoObserverStatusReply;
+    defer f2.deinit(alloc);
+    const st2 = try proto.decodeStatusReply(f2.payload);
+    try std.testing.expectEqual(@as(u16, 80), st2.cols);
+    try std.testing.expectEqual(@as(u16, 24), st2.rows);
+    try std.testing.expectEqual(proto.CmdPhase.at_prompt, st2.cmd.phase);
+}
+// ---------------------------------------------------------------------------
+// Awaits: a request the daemon holds open until something answers it.
+//
+// Every test below asserts the REASON an await ended, never how long it took.
+// Latency here is the run loop's sampling granularity crossed with whatever
+// else the machine is doing, so a test that pinned it would be pinning the
+// box. The iteration budgets are outer bounds — generous enough that a loaded
+// box does not read as a regression, finite so a regression fails by name
+// instead of hanging the suite.
+// ---------------------------------------------------------------------------
+/// Read frames already sitting on `fd` — deliberately without pumping — until
+/// one of `want` turns up or the socket goes quiet. This is the "did the
+/// daemon answer inside that one pump" observable: an answer that needs
+/// another pump to appear reads as absent here, which is the distinction the
+/// immediate-answer test exists to make.
+fn readQueued(alloc: std.mem.Allocator, fd: std.posix.fd_t, want: proto.MsgType) !?proto.Frame {
+    var guard: usize = 0;
+    while (guard < 16) : (guard += 1) {
+        var pfd = [_]std.posix.pollfd{
+            .{ .fd = fd, .events = std.posix.POLL.IN, .revents = 0 },
+        };
+        if ((std.posix.poll(&pfd, 1) catch 0) == 0) return null;
+        const frame = (try proto.readFrame(alloc, fd)) orelse return null;
+        if (frame.type == want) return frame;
+        frame.deinit(alloc);
+    }
+    return null;
+}
+test "Server: an await is held open, answered by a mark, and re-answered immediately after" {
+    const alloc = std.testing.allocator;
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    const dir_path = tmp.path();
+    const sock_path = try std.fmt.allocPrint(alloc, "{s}/awaitmark.sock", .{dir_path});
+    defer alloc.free(sock_path);
+    // Script-gated for the same reason the cmd_state push test is: the child
+    // emits its marks when told to and never before, so there is a moment at
+    // which "no reply yet" is a claim worth making. Against a real integrated
+    // shell there would not be.
+    //
+    // The burst is the whole point of its shape. Real integration writes
+    // `D;code` and the next prompt's `A` together from precmd, so both fold
+    // into the tracker inside one pty read and the phase is back at at_prompt
+    // before any await is examined. An earlier version of this test stopped
+    // at the D and passed against an implementation that could only answer in
+    // the sliver between the two — which is to say, never, in production.
+    try tmp.dir.writeFile(.{
+        .sub_path = "await.sh",
+        .data =
+        \\#!/bin/sh
+        \\read -r go
+        \\printf '\033]133;C\007out\r\n\033]133;D;3\007\033]133;A\007'
+        \\read -r stop
+        \\
+        ,
+        .flags = .{ .mode = 0o755 },
+    });
+    const script = try std.fmt.allocPrintSentinel(alloc, "{s}/await.sh", .{dir_path}, 0);
+    defer alloc.free(script);
+    var srv = try Server.init(alloc, .{ .sock_path = sock_path, .shell = script });
+    defer srv.deinit();
+    const c = try std.net.connectUnixSocket(sock_path);
+    defer c.close();
+    try proto.writeFrame(c.handle, .attach, &proto.encodeAttach(80, 24, 0, 0));
+    // since_seq is "what I already know about": only a return NEWER than this
+    // may answer. Nothing has returned on this session at all.
+    try proto.writeFrame(c.handle, .await_req, &proto.encodeAwaitReq(.{
+        .since_seq = srv.tracker.seq,
+        .settle_ms = 0,
+        .timeout_ms = 5000,
+    }));
+    // Held open: no mark has landed, no settle floor was asked for, the
+    // timeout is seconds away, and this shell never moves its fg pgid. There
+    // is nothing that may honestly answer yet, so nothing must.
+    if (try awaitFrame(alloc, &srv, c.handle, .await_reply, 40)) |early| {
+        early.deinit(alloc);
+        return error.AwaitAnsweredBeforeAnythingHappened;
+    }
+    // Release the script into its C-output-D. All three land in one pty read,
+    // so the await resolves in the same pump that pushed the transitions.
+    try proto.writeFrame(c.handle, .input, "go\n");
+    const f = (try awaitFrame(alloc, &srv, c.handle, .await_reply, 500)) orelse
+        return error.NoAwaitReplyFromMark;
+    defer f.deinit(alloc);
+    const rep = try proto.decodeAwaitReply(f.payload);
+    try std.testing.expectEqual(proto.AwaitReason.returned, rep.reason);
+    try std.testing.expectEqual(proto.CmdPhase.returned, rep.state.phase);
+    // Marks won the race, and only marks carry a code.
+    try std.testing.expectEqual(proto.Mechanism.marks, rep.state.mechanism);
+    try std.testing.expectEqual(@as(?u8, 3), rep.state.exit_code);
+    // Reconnect idempotency, asked after the burst's A has already landed and
+    // put the session back at a prompt: an agent whose answer died with its
+    // connection re-asks with the seq it last held. That return has already
+    // happened, so the daemon must not make it wait for a second one — it
+    // answers inline, in the very pump that read the request. Reading without
+    // pumping again is what makes "inline" the thing being asserted, and the
+    // window in which this can be answered is the rest of the session rather
+    // than the sliver between a D and the A that follows it.
+    try proto.writeFrame(c.handle, .await_req, &proto.encodeAwaitReq(.{
+        .since_seq = 0,
+        .settle_ms = 0,
+        .timeout_ms = 5000,
+    }));
+    _ = try srv.pumpOnce(5);
+    const f2 = (try readQueued(alloc, c.handle, .await_reply)) orelse
+        return error.AwaitNotAnsweredOnTheSamePump;
+    defer f2.deinit(alloc);
+    const rep2 = try proto.decodeAwaitReply(f2.payload);
+    try std.testing.expectEqual(proto.AwaitReason.returned, rep2.reason);
+    try std.testing.expectEqual(proto.Mechanism.marks, rep2.state.mechanism);
+    try std.testing.expectEqual(@as(?u8, 3), rep2.state.exit_code);
+    // And a client attaching only now is told the state it could not have
+    // witnessed, rather than learning nothing until the next transition.
+    // That state is the LIVE one, which after the burst's A really is
+    // at_prompt — a push describes where the session is, and the session is
+    // at a prompt. The exit code is what carries the news, and it is the one
+    // a fresh session could not produce: null is what an untouched tracker
+    // reports, so 3 here means this push came from the command that ran.
+    const late = try std.net.connectUnixSocket(sock_path);
+    defer late.close();
+    try proto.writeFrame(late.handle, .attach, &proto.encodeAttach(80, 24, 0, 0));
+    const f3 = (try awaitFrame(alloc, &srv, late.handle, .cmd_state, 200)) orelse
+        return error.NoCmdStateOnAttach;
+    defer f3.deinit(alloc);
+    const st3 = try proto.decodeCmdState(f3.payload);
+    try std.testing.expectEqual(proto.CmdPhase.at_prompt, st3.phase);
+    try std.testing.expectEqual(@as(?u8, 3), st3.exit_code);
+}
+test "Server: a return is still answerable once the next command is running" {
+    const alloc = std.testing.allocator;
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    const dir_path = tmp.path();
+    const sock_path = try std.fmt.allocPrint(alloc, "{s}/awaitnext.sock", .{dir_path});
+    defer alloc.free(sock_path);
+    // One command that finishes with code 3 and redraws its prompt, then a
+    // second that starts and stays running. The live tracker is describing
+    // the second command by the time the await is asked — running, no exit
+    // code, a different start row — so anything answered out of it would be
+    // answering about the wrong command.
+    try tmp.dir.writeFile(.{
+        .sub_path = "next.sh",
+        .data =
+        \\#!/bin/sh
+        \\read -r first
+        \\printf '\033]133;C\007out\r\n\033]133;D;3\007\033]133;A\007'
+        \\read -r second
+        \\printf '\033]133;C\007working\r\n'
+        \\read -r stop
+        \\
+        ,
+        .flags = .{ .mode = 0o755 },
+    });
+    const script = try std.fmt.allocPrintSentinel(alloc, "{s}/next.sh", .{dir_path}, 0);
+    defer alloc.free(script);
+    var srv = try Server.init(alloc, .{ .sock_path = sock_path, .shell = script });
+    defer srv.deinit();
+    const c = try std.net.connectUnixSocket(sock_path);
+    defer c.close();
+    try proto.writeFrame(c.handle, .attach, &proto.encodeAttach(80, 24, 0, 0));
+    // Run the first command to completion, then start the second and wait
+    // until the daemon has actually seen it open.
+    try proto.writeFrame(c.handle, .input, "go\n");
+    try proto.writeFrame(c.handle, .input, "go\n");
+    var spun: usize = 0;
+    while (spun < 500 and srv.cmd.phase != .running) : (spun += 1) {
+        _ = try srv.pumpOnce(5);
+    }
+    try std.testing.expectEqual(proto.CmdPhase.running, srv.cmd.phase);
+    // Now ask about everything since the beginning of time. The honest answer
+    // is the FIRST command's return — the client asked what had returned
+    // since its seq, not what the session is doing at this instant.
+    try proto.writeFrame(c.handle, .await_req, &proto.encodeAwaitReq(.{
+        .since_seq = 0,
+        .settle_ms = 0,
+        .timeout_ms = 5000,
+    }));
+    const f = (try awaitFrame(alloc, &srv, c.handle, .await_reply, 200)) orelse
+        return error.NoAwaitReplyWhileNextCommandRuns;
+    defer f.deinit(alloc);
+    const rep = try proto.decodeAwaitReply(f.payload);
+    try std.testing.expectEqual(proto.AwaitReason.returned, rep.reason);
+    try std.testing.expectEqual(proto.Mechanism.marks, rep.state.mechanism);
+    try std.testing.expectEqual(proto.CmdPhase.returned, rep.state.phase);
+    // The snapshot's code, not the running command's absent one.
+    try std.testing.expectEqual(@as(?u8, 3), rep.state.exit_code);
+    // And the live tracker really has moved on, so the assertions above came
+    // from the snapshot and could not have come from reading it.
+    try std.testing.expectEqual(proto.CmdPhase.running, srv.cmd.phase);
+    try std.testing.expectEqual(@as(?u8, null), srv.cmd.exit_code);
+}
+test "Server: an await with a settle floor is answered by output going quiet" {
+    const alloc = std.testing.allocator;
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    const sock_path = try std.fmt.allocPrint(alloc, "{s}/settle.sock", .{tmp.path()});
+    defer alloc.free(sock_path);
+    // /bin/cat echoes once and then says nothing, which is the exact shape
+    // settle exists for: no shell integration, no job leaving the shell's
+    // process group, and so no evidence available beyond "it stopped
+    // talking".
+    var srv = try Server.init(alloc, .{ .sock_path = sock_path, .shell = "/bin/cat" });
+    defer srv.deinit();
+    const c = try std.net.connectUnixSocket(sock_path);
+    defer c.close();
+    try proto.writeFrame(c.handle, .attach, &proto.encodeAttach(80, 24, 0, 0));
+    try proto.writeFrame(c.handle, .await_req, &proto.encodeAwaitReq(.{
+        .since_seq = srv.tracker.seq,
+        .settle_ms = 200,
+        .timeout_ms = 5000,
+    }));
+    try proto.writeFrame(c.handle, .input, "quiet\r\n");
+    // Budget ~1.2s of wall clock against a 200ms floor and a 5s timeout, so
+    // the only reason that can legally arrive in the window is the settle.
+    const f = (try awaitFrame(alloc, &srv, c.handle, .await_reply, 200)) orelse
+        return error.NoSettleReply;
+    defer f.deinit(alloc);
+    const rep = try proto.decodeAwaitReply(f.payload);
+    try std.testing.expectEqual(proto.AwaitReason.settled, rep.reason);
+    try std.testing.expectEqual(proto.Mechanism.settle, rep.state.mechanism);
+    // Silence is evidence that something finished, never evidence of how.
+    try std.testing.expectEqual(@as(?u8, null), rep.state.exit_code);
+    // Deliberately the live phase, not a manufactured `.returned`: settle
+    // never learned that a command ran, so it has no standing to claim one
+    // returned. The reason field carries the verdict; the phase keeps
+    // reporting what the session is actually known to be doing.
+    try std.testing.expectEqual(proto.CmdPhase.at_prompt, rep.state.phase);
+}
+test "Server: an await with nothing to answer it ends at the bound the caller set" {
+    const alloc = std.testing.allocator;
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    const sock_path = try std.fmt.allocPrint(alloc, "{s}/timeout.sock", .{tmp.path()});
+    defer alloc.free(sock_path);
+    var srv = try Server.init(alloc, .{ .sock_path = sock_path, .shell = "/bin/cat" });
+    defer srv.deinit();
+    const c = try std.net.connectUnixSocket(sock_path);
+    defer c.close();
+    try proto.writeFrame(c.handle, .attach, &proto.encodeAttach(80, 24, 0, 0));
+    // Nothing is typed at this session, no settle floor is asked for and no
+    // mark will ever come: the timeout is the only thing left that can end
+    // this wait, which is the point.
+    try proto.writeFrame(c.handle, .await_req, &proto.encodeAwaitReq(.{
+        .since_seq = srv.tracker.seq,
+        .settle_ms = 0,
+        .timeout_ms = 150,
+    }));
+    const f = (try awaitFrame(alloc, &srv, c.handle, .await_reply, 120)) orelse
+        return error.NoTimeoutReply;
+    defer f.deinit(alloc);
+    const rep = try proto.decodeAwaitReply(f.payload);
+    try std.testing.expectEqual(proto.AwaitReason.timeout, rep.reason);
+    // A timed-out await still reports which regime the session is in, the
+    // same claim status_reply makes: this one has never spoken marks.
+    try std.testing.expectEqual(proto.Mechanism.pgid, rep.state.mechanism);
+    try std.testing.expectEqual(proto.CmdPhase.at_prompt, rep.state.phase);
+}
+test "Server: without shell integration a foreground job's end is caught by the pgid edge" {
+    const alloc = std.testing.allocator;
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    const sock_path = try std.fmt.allocPrint(alloc, "{s}/pgid.sock", .{tmp.path()});
+    defer alloc.free(sock_path);
+    // A real interactive /bin/sh with no integration installed. No mark will
+    // ever arrive, so the only evidence that a command ran and finished is
+    // that the terminal's foreground process group left the shell and came
+    // back — see the fgPgid test in pty.zig for that same movement observed
+    // directly.
+    var srv = try Server.init(alloc, .{ .sock_path = sock_path, .shell = "/bin/sh" });
+    defer srv.deinit();
+    const c = try std.net.connectUnixSocket(sock_path);
+    defer c.close();
+    try proto.writeFrame(c.handle, .attach, &proto.encodeAttach(80, 24, 0, 0));
+    // sleep 2, not sleep 1: the edge has to SEE the pgid off the shell before
+    // "back on the shell" can mean anything, so the busy window must be wide
+    // enough to sample. A job too short to observe is one the settle floor is
+    // for, not this.
+    try proto.writeFrame(c.handle, .input, "sleep 2\n");
+    try proto.writeFrame(c.handle, .await_req, &proto.encodeAwaitReq(.{
+        .since_seq = srv.tracker.seq,
+        .settle_ms = 0,
+        .timeout_ms = 10_000,
+    }));
+    // ~9s of budget for a 2s job: bounded, and slack enough that a loaded box
+    // does not read as a regression.
+    const f = (try awaitFrame(alloc, &srv, c.handle, .await_reply, 1500)) orelse
+        return error.NoPgidReply;
+    defer f.deinit(alloc);
+    const rep = try proto.decodeAwaitReply(f.payload);
+    try std.testing.expectEqual(proto.AwaitReason.returned, rep.reason);
+    try std.testing.expectEqual(proto.Mechanism.pgid, rep.state.mechanism);
+    try std.testing.expectEqual(proto.CmdPhase.returned, rep.state.phase);
+    // The pgid can say THAT a command ended, never with what code — no mark
+    // carried one, and inventing a 0 here would be the whole failure mode
+    // this mechanism has to avoid.
+    try std.testing.expectEqual(@as(?u8, null), rep.state.exit_code);
+}

src/shellint.zig

@@ @@ -0,0 +1,475 @@ @@
+//! Shell integration: OSC 133 marks injected at spawn. muxd forks the
+//! session shell itself, so injection is env + argv at spawn time — no
+//! rc-file edits, ever. Detection is by shell basename; unknown shells get
+//! nothing and the session runs on the pgid/settle fallbacks.
+const std = @import("std");
+const xdg = @import("xdg");
+/// The precmd hook, character for character the same in zsh and bash: both
+/// shells spell `$?`, `local` and `printf` alike, and the mark it emits is
+/// the protocol's, not either shell's. Spliced into both scripts below
+/// rather than written twice — two copies of the hook that decides whether
+/// a command's exit code is knowable is two places for that decision to
+/// drift, and a drift would be silent in exactly one shell.
+///
+/// `local code=$?` is the FIRST line for a reason that outlives any edit:
+/// $? is clobbered by the next command to run, and every line added above
+/// this one would be that command.
+const precmd_fn =
+    \\_mux_precmd() {
+    \\  local code=$?
+    \\  [[ -n "$_mux_ran" ]] && printf '\e]133;D;%s\a' "$code"
+    \\  _mux_ran=""
+    \\  printf '\e]133;A\a'
+    \\}
+    \\
+;
+/// Pointing ZDOTDIR at the shim silently costs the user their ~/.zshenv:
+/// zsh looks for .zshenv under $ZDOTDIR, and the shim directory has none,
+/// so a config kept there (PATH edits, and anything else zsh is expected to
+/// read for non-interactive shells too) stops being read for the session.
+/// The .zshrc is handed back below, which is the common case; a .zshenv
+/// shim that restores ZDOTDIR the way ghostty's does is the roadmap fix.
+pub const zsh_zshrc =
+    \\# mux shell integration (zsh): OSC 133 marks. Sourced via a ZDOTDIR
+    \\# shim; restores the user's ZDOTDIR (or unsets it) then runs their rc.
+    \\if [[ -n "$MUX_ORIG_ZDOTDIR" ]]; then
+    \\  export ZDOTDIR="$MUX_ORIG_ZDOTDIR"
+    \\  unset MUX_ORIG_ZDOTDIR
+    \\else
+    \\  unset ZDOTDIR
+    \\fi
+    \\[[ -f "${ZDOTDIR:-$HOME}/.zshrc" ]] && source "${ZDOTDIR:-$HOME}/.zshrc"
+    \\autoload -Uz add-zsh-hook
+    \\_mux_preexec() { _mux_ran=1; printf '\e]133;C\a'; }
+    \\
+++ precmd_fn ++
+    \\add-zsh-hook preexec _mux_preexec
+    \\add-zsh-hook precmd _mux_precmd
+    \\
+;
+/// The DEBUG trap here silently REPLACES any DEBUG trap the session already
+/// had — bash-preexec, atuin and iTerm2's integration each install one, and
+/// bash allows exactly one. mux wins and the other goes quiet, with no
+/// diagnostic anywhere. Coexisting by detecting bash-preexec and registering
+/// with it instead is a roadmap item, not a thing this version does.
+pub const bash_init =
+    \\# mux shell integration (bash): OSC 133 marks. Passed via --init-file;
+    \\# sources the user's normal rc first so their config still runs.
+    \\[[ -f "$HOME/.bashrc" ]] && source "$HOME/.bashrc"
+    \\_mux_ran=""
+    \\_mux_preexec() {
+    \\  [[ -n "$COMP_LINE" ]] && return
+    \\  [[ "$BASH_COMMAND" == _mux_precmd* ]] && return
+    \\  # PROMPT_COMMAND's own members run between the command and the next
+    \\  # prompt, and the DEBUG trap fires for every one of them. Counting
+    \\  # them as commands re-arms _mux_ran on every idle cycle, so the next
+    \\  # prompt reports `D;0` for a command nobody ran — which is how a
+    \\  # session on this box reported a successful command roughly once a
+    \\  # second while sitting at an untouched prompt.
+    \\  #
+    \\  # Membership is bash-preexec's check and is exact. "${PROMPT_COMMAND[@]}"
+    \\  # deliberately covers both spellings: a scalar expands as the single
+    \\  # word it is, so this needs no type test and, unlike `declare -p`, no
+    \\  # subshell in a path that runs before every command. A member that is
+    \\  # itself compound (`a; b`) fires DEBUG once per simple command and so
+    \\  # will not match, and a typed command whose text is character-for-
+    \\  # character a member gets suppressed. Both are bash-preexec's
+    \\  # limitations too, and both are quieter than the bug they replace.
+    \\  local _mux_c
+    \\  for _mux_c in "${PROMPT_COMMAND[@]}"; do
+    \\    [[ "$BASH_COMMAND" == "$_mux_c" ]] && return
+    \\  done
+    \\  _mux_ran=1
+    \\  printf '\e]133;C\a'
+    \\}
+    \\
+++ precmd_fn ++
+    \\# Prepended, never appended: _mux_precmd has to see the command's own
+    \\# $?, and any member running ahead of it would have overwritten it.
+    \\#
+    \\# Type-aware because bash 5.1 made PROMPT_COMMAND an array and the
+    \\# distributions took it up — Arch's /etc/bash.bashrc appends one under
+    \\# any xterm* TERM, which is exactly what muxd sets. A string assignment
+    \\# onto an array lands on element 0 and folds a member into a compound,
+    \\# which is precisely the shape the membership check above cannot match.
+    \\if [[ "$(declare -p PROMPT_COMMAND 2>/dev/null)" == "declare -a"* ]]; then
+    \\  PROMPT_COMMAND=(_mux_precmd "${PROMPT_COMMAND[@]}")
+    \\else
+    \\  PROMPT_COMMAND="_mux_precmd${PROMPT_COMMAND:+;$PROMPT_COMMAND}"
+    \\fi
+    \\# LAST, and the ordering is load-bearing rather than tidy: a trap armed
+    \\# before the assignment above fires ON that assignment, so _mux_ran was
+    \\# already set when the first prompt ran and every session opened by
+    \\# reporting a command that never ran. Measured, not reasoned about —
+    \\# {C:PROMPT_COMMAND=...}{D;0}{A} was the first thing bash ever said.
+    \\trap '_mux_preexec' DEBUG
+    \\
+;
+pub const fish_conf =
+    \\# mux shell integration (fish): OSC 133 marks, via vendor_conf.d.
+    \\function _mux_preexec --on-event fish_preexec
+    \\    printf '\e]133;C\a'
+    \\end
+    \\function _mux_postexec --on-event fish_postexec
+    \\    printf '\e]133;D;%s\a' $status
+    \\end
+    \\function _mux_prompt --on-event fish_prompt
+    \\    printf '\e]133;A\a'
+    \\end
+    \\
+;
+pub const Kind = enum { zsh, bash, fish, other };
+pub fn detect(shell_path: []const u8) Kind {
+    const base = std.fs.path.basename(shell_path);
+    if (std.mem.eql(u8, base, "zsh")) return .zsh;
+    if (std.mem.eql(u8, base, "bash")) return .bash;
+    if (std.mem.eql(u8, base, "fish")) return .fish;
+    return .other;
+}
+pub const EnvPair = struct { key: [:0]const u8, value: [:0]const u8 };
+/// Everything the spawn needs: the argv to exec and env pairs to set in
+/// the child. The shim directory must outlive the spawn (paths point into
+/// it).
+pub const Injection = struct {
+    /// Extra argv AFTER the shell path (bash --init-file <shim>); empty
+    /// for env-only injections (zsh, fish) and for .other.
+    extra_argv: []const [:0]const u8,
+    env: []const EnvPair,
+    /// The shim directory, set EXACTLY when this call created one — an
+    /// unknown shell writes nothing and reports null. The caller deletes
+    /// it at teardown, so a path reported here that was never created
+    /// would be a cleanup claiming work it did not do, and a path created
+    /// but not reported would be litter left in the runtime directory.
+    /// Reported from the one place that knows, rather than re-derived by
+    /// the caller from a second `detect` of the same shell.
+    dir: ?[]const u8 = null,
+};
+/// The empty injection: what a shell with no scripts gets, and what a
+/// failed `install` degrades to. Nothing to exec, nothing to export,
+/// nothing on disk to remove.
+pub const no_injection: Injection = .{ .extra_argv = &.{}, .env = &.{}, .dir = null };
+/// Prepare the shim under `parent_dir` and hand back what the spawn must
+/// add, degrading to `no_injection` rather than failing.
+///
+/// Degraded, never fatal. A session without marks is a working session —
+/// it runs on the pgid and settle fallbacks, which is what every unknown
+/// shell does — so refusing to start the daemon over an optional
+/// enhancement would invert this module's premise. Said out loud, because
+/// a silent fallback here would look exactly like a shell that ignores
+/// its rc.
+///
+/// The `mux-shellint-<pid>` naming lives here rather than at the call
+/// site: it is the same fact as what `prepare` writes and what the
+/// returned `dir` promises to delete, and the pid is what keeps two
+/// daemons sharing one runtime directory out of each other's shims.
+pub fn install(
+    arena: std.mem.Allocator,
+    parent_dir: []const u8,
+    shell_path: []const u8,
+) Injection {
+    const dir = std.fmt.allocPrint(
+        arena,
+        "{s}/mux-shellint-{d}",
+        .{ parent_dir, std.os.linux.getpid() },
+    ) catch {
+        std.debug.print(
+            "muxd: shell integration unavailable (out of memory naming the shim " ++
+                "directory under {s}); the session runs without command marks\n",
+            .{parent_dir},
+        );
+        return no_injection;
+    };
+    return prepare(arena, dir, shell_path) catch |err| {
+        std.debug.print(
+            "muxd: shell integration unavailable ({s}: {t}); " ++
+                "the session runs without command marks\n",
+            .{ dir, err },
+        );
+        return no_injection;
+    };
+}
+/// Prepare shim files under `dir` (created private, 0700) for `shell_path`
+/// and return what spawn must add. All returned slices are allocated from
+/// `arena` — hand it an arena that lives as long as the daemon.
+///
+/// `install` is what the daemon calls; this stays public for the tests,
+/// which need to name their own directory.
+pub fn prepare(
+    arena: std.mem.Allocator,
+    dir: []const u8,
+    shell_path: []const u8,
+) !Injection {
+    switch (detect(shell_path)) {
+        .zsh => {
+            try xdg.makePrivateDir(dir);
+            const rc_path = try std.fs.path.join(arena, &.{ dir, ".zshrc" });
+            try writeFilePrivate(rc_path, zsh_zshrc);
+            var env: std.ArrayList(EnvPair) = .empty;
+            const dir_z = try arena.dupeZ(u8, dir);
+            try env.append(arena, .{ .key = "ZDOTDIR", .value = dir_z });
+            // Only when the daemon itself carried one: exporting an empty
+            // ZDOTDIR would break zsh's fallback to $HOME (spec footnote).
+            if (std.posix.getenv("ZDOTDIR")) |orig| {
+                try env.append(arena, .{
+                    .key = "MUX_ORIG_ZDOTDIR",
+                    .value = try arena.dupeZ(u8, orig),
+                });
+            }
+            return .{ .extra_argv = &.{}, .env = try env.toOwnedSlice(arena), .dir = dir };
+        },
+        .bash => {
+            try xdg.makePrivateDir(dir);
+            const init_path = try std.fs.path.join(arena, &.{ dir, "bash-init.sh" });
+            try writeFilePrivate(init_path, bash_init);
+            const init_z = try arena.dupeZ(u8, init_path);
+            const argv = try arena.alloc([:0]const u8, 2);
+            argv[0] = "--init-file";
+            argv[1] = init_z;
+            return .{ .extra_argv = argv, .env = &.{}, .dir = dir };
+        },
+        .fish => {
+            const vendor = try std.fs.path.join(arena, &.{ dir, "fish", "vendor_conf.d" });
+            try xdg.makePrivateDir(vendor);
+            const conf_path = try std.fs.path.join(arena, &.{ vendor, "mux.fish" });
+            try writeFilePrivate(conf_path, fish_conf);
+            const orig = std.posix.getenv("XDG_DATA_DIRS") orelse "/usr/local/share:/usr/share";
+            const merged = try std.fmt.allocPrintSentinel(arena, "{s}:{s}", .{ dir, orig }, 0);
+            return .{
+                .extra_argv = &.{},
+                .env = try arena.dupe(EnvPair, &.{.{ .key = "XDG_DATA_DIRS", .value = merged }}),
+                // The vendor directory nests UNDER `dir`, and `dir` is what
+                // teardown removes: deleting the leaf would leave the two
+                // directories above it behind.
+                .dir = dir,
+            };
+        },
+        .other => return no_injection,
+    }
+}
+/// The shim's contents are 0600 either way; the 0700 on the directory is
+/// what keeps it from publishing that this daemon exists and what it named
+/// its files — the same reason, and now the same code, as the key file's
+/// parent (see xdg.makePrivateDir).
+fn writeFilePrivate(path: []const u8, contents: []const u8) !void {
+    const f = try std.fs.cwd().createFile(path, .{ .mode = 0o600 });
+    defer f.close();
+    try f.writeAll(contents);
+}
+test "detect goes by basename" {
+    try std.testing.expectEqual(Kind.zsh, detect("/usr/bin/zsh"));
+    try std.testing.expectEqual(Kind.zsh, detect("zsh"));
+    try std.testing.expectEqual(Kind.bash, detect("/bin/bash"));
+    try std.testing.expectEqual(Kind.fish, detect("/usr/local/bin/fish"));
+    // The fallbacks: a POSIX sh and anything exotic get no injection at
+    // all, and the session runs on pgid + settle exactly as before.
+    try std.testing.expectEqual(Kind.other, detect("/bin/sh"));
+    try std.testing.expectEqual(Kind.other, detect("/usr/bin/nu"));
+    // Only the last component decides. A "bash" directory on the way there
+    // must not make a dash session look like a bash one and get handed a
+    // --init-file it does not understand.
+    try std.testing.expectEqual(Kind.other, detect("/opt/bash/bin/dash"));
+}
+/// The three prepare tests all want a real, writable, disposable directory
+/// and the string naming it. No socket is bound here, so std's tmpDir (and
+/// its long .zig-cache path) is fine — testtmp exists for sun_path, which
+/// this module never touches.
+const TmpPath = struct {
+    tmp: std.testing.TmpDir,
+    dir: []const u8,
+    fn make() !TmpPath {
+        var tmp = std.testing.tmpDir(.{});
+        errdefer tmp.cleanup();
+        const dir = try tmp.dir.realpathAlloc(std.testing.allocator, ".");
+        return .{ .tmp = tmp, .dir = dir };
+    }
+    fn deinit(self: *TmpPath) void {
+        std.testing.allocator.free(self.dir);
+        self.tmp.cleanup();
+    }
+};
+test "prepare zsh writes the shim and sets ZDOTDIR" {
+    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena.deinit();
+    var t = try TmpPath.make();
+    defer t.deinit();
+    const shim = try std.fs.path.join(arena.allocator(), &.{ t.dir, "shim" });
+    const inj = try prepare(arena.allocator(), shim, "/usr/bin/zsh");
+    // zsh is an env-only injection: the shell is exec'd with no extra argv
+    // and finds the shim because ZDOTDIR points at it.
+    try std.testing.expectEqual(@as(usize, 0), inj.extra_argv.len);
+    try std.testing.expect(inj.env.len >= 1);
+    try std.testing.expectEqualStrings("ZDOTDIR", inj.env[0].key);
+    try std.testing.expectEqualStrings(shim, inj.env[0].value);
+    // A directory was created, so it is reported — this is the value the
+    // daemon deletes at teardown, and nothing else tells it what to delete.
+    try std.testing.expectEqualStrings(shim, inj.dir.?);
+    // ZDOTDIR names the directory; the file zsh will source is the .zshrc
+    // inside it, which is the artifact worth asserting on.
+    const rc_path = try std.fs.path.join(arena.allocator(), &.{ inj.env[0].value, ".zshrc" });
+    const rc = try std.fs.cwd().readFileAlloc(std.testing.allocator, rc_path, 8192);
+    defer std.testing.allocator.free(rc);
+    // The two halves that make it work: the D mark carries the exit code,
+    // and the hooks are actually registered.
+    try std.testing.expect(std.mem.indexOf(u8, rc, "133;D;%s") != null);
+    try std.testing.expect(std.mem.indexOf(u8, rc, "add-zsh-hook") != null);
+    // ...and the shim hands control back to the user's own rc, which is the
+    // difference between integration and hijacking their shell.
+    try std.testing.expect(std.mem.indexOf(u8, rc, ".zshrc\"") != null);
+}
+test "prepare bash returns --init-file argv" {
+    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena.deinit();
+    var t = try TmpPath.make();
+    defer t.deinit();
+    const shim = try std.fs.path.join(arena.allocator(), &.{ t.dir, "shim" });
+    const inj = try prepare(arena.allocator(), shim, "/bin/bash");
+    // bash has no ZDOTDIR equivalent, so the shim arrives on the command
+    // line instead — and nothing goes into the environment.
+    try std.testing.expectEqual(@as(usize, 2), inj.extra_argv.len);
+    try std.testing.expectEqualStrings("--init-file", inj.extra_argv[0]);
+    try std.testing.expectEqual(@as(usize, 0), inj.env.len);
+    try std.testing.expectEqualStrings(shim, inj.dir.?);
+    const script = try std.fs.cwd().readFileAlloc(std.testing.allocator, inj.extra_argv[1], 8192);
+    defer std.testing.allocator.free(script);
+    try std.testing.expect(std.mem.indexOf(u8, script, "PROMPT_COMMAND") != null);
+    try std.testing.expect(std.mem.indexOf(u8, script, "trap '_mux_preexec' DEBUG") != null);
+    // --init-file REPLACES ~/.bashrc, so the shim sourcing it is what keeps
+    // the user's shell theirs. Its absence would be silent.
+    try std.testing.expect(std.mem.indexOf(u8, script, "$HOME/.bashrc") != null);
+}
+test "prepare fish writes vendor_conf.d and prepends to XDG_DATA_DIRS" {
+    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena.deinit();
+    var t = try TmpPath.make();
+    defer t.deinit();
+    // No fish binary needed: what `prepare` owes fish is a file at the path
+    // fish looks in and a data dir pointing there, and both are checkable
+    // on any box. The e2e that needs the real shell skips where it is absent.
+    const shim = try std.fs.path.join(arena.allocator(), &.{ t.dir, "shim" });
+    const inj = try prepare(arena.allocator(), shim, "/usr/bin/fish");
+    try std.testing.expectEqual(@as(usize, 0), inj.extra_argv.len);
+    try std.testing.expectEqual(@as(usize, 1), inj.env.len);
+    try std.testing.expectEqualStrings("XDG_DATA_DIRS", inj.env[0].key);
+    // The shim root, not the vendor directory nested inside it: teardown
+    // removes what it is given, and the leaf would strand two levels.
+    try std.testing.expectEqualStrings(shim, inj.dir.?);
+    // Prepended, not replaced: fish still has to find its own completions
+    // and functions, so clobbering the list would break the shell to
+    // integrate with it.
+    try std.testing.expect(std.mem.startsWith(u8, inj.env[0].value, shim));
+    try std.testing.expect(inj.env[0].value.len > shim.len + 1);
+    try std.testing.expectEqual(@as(u8, ':'), inj.env[0].value[shim.len]);
+    // fish reads vendor_conf.d from `$XDG_DATA_DIRS/fish/vendor_conf.d`, so
+    // the nesting under the shim directory is the part that has to be right.
+    const conf_path = try std.fs.path.join(
+        arena.allocator(),
+        &.{ shim, "fish", "vendor_conf.d", "mux.fish" },
+    );
+    const conf = try std.fs.cwd().readFileAlloc(std.testing.allocator, conf_path, 8192);
+    defer std.testing.allocator.free(conf);
+    try std.testing.expect(std.mem.indexOf(u8, conf, "--on-event fish_preexec") != null);
+    try std.testing.expect(std.mem.indexOf(u8, conf, "--on-event fish_postexec") != null);
+    try std.testing.expect(std.mem.indexOf(u8, conf, "133;D;%s") != null);
+}
+test "prepare other injects nothing" {
+    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena.deinit();
+    var t = try TmpPath.make();
+    defer t.deinit();
+    const shim = try std.fs.path.join(arena.allocator(), &.{ t.dir, "shim" });
+    const inj = try prepare(arena.allocator(), shim, "/bin/sh");
+    try std.testing.expectEqual(@as(usize, 0), inj.extra_argv.len);
+    try std.testing.expectEqual(@as(usize, 0), inj.env.len);
+    // Not merely empty: an unknown shell must leave no trace on disk, so a
+    // /bin/sh session is byte-identical to one from before this module.
+    try std.testing.expectError(error.FileNotFound, std.fs.cwd().access(shim, .{}));
+    // And it says so, which is the half teardown reads: a reported path
+    // here would have the daemon delete-tree a directory nothing created.
+    try std.testing.expectEqual(@as(?[]const u8, null), inj.dir);
+}
+test "install names the shim directory after the daemon and degrades in place" {
+    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena.deinit();
+    var t = try TmpPath.make();
+    defer t.deinit();
+    // The naming rule, asserted where it now lives: the caller hands over a
+    // parent and gets back a per-pid directory under it, which is what keeps
+    // two daemons sharing one runtime directory out of each other's shims.
+    const inj = install(arena.allocator(), t.dir, "/bin/bash");
+    var want: [512]u8 = undefined;
+    const expect = try std.fmt.bufPrint(
+        &want,
+        "{s}/mux-shellint-{d}",
+        .{ t.dir, std.os.linux.getpid() },
+    );
+    try std.testing.expectEqualStrings(expect, inj.dir.?);
+    try std.fs.cwd().access(expect, .{});
+    // An unwritable parent is the degraded path, and it is NOT an error: a
+    // session without marks still runs, so `install` returns the empty
+    // injection and the daemon starts. (The diagnostic goes to stderr; what
+    // is asserted here is that nothing propagates and nothing is claimed.)
+    const blocked = try std.fs.path.join(arena.allocator(), &.{ t.dir, "file-not-a-dir" });
+    const f = try std.fs.cwd().createFile(blocked, .{});
+    f.close();
+    const degraded = install(arena.allocator(), blocked, "/bin/bash");
+    try std.testing.expectEqual(@as(usize, 0), degraded.extra_argv.len);
+    try std.testing.expectEqual(@as(usize, 0), degraded.env.len);
+    try std.testing.expectEqual(@as(?[]const u8, null), degraded.dir);
+}
+test "prepare zsh: the shim directory is 0700 and the rc file 0600" {
+    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena.deinit();
+    var t = try TmpPath.make();
+    defer t.deinit();
+    const shim = try std.fs.path.join(arena.allocator(), &.{ t.dir, "shim" });
+    _ = try prepare(arena.allocator(), shim, "/usr/bin/zsh");
+    // makePath alone leaves 0755. What lands here is a file the session
+    // shell sources — anyone who can write it can run code as this user —
+    // so the permissions are part of the contract, not decoration.
+    var d = try std.fs.cwd().openDir(shim, .{ .iterate = true });
+    defer d.close();
+    const dst = try d.stat();
+    try std.testing.expectEqual(@as(u32, 0o700), @as(u32, @intCast(dst.mode & 0o777)));
+    const rc_path = try std.fs.path.join(arena.allocator(), &.{ shim, ".zshrc" });
+    const f = try std.fs.cwd().openFile(rc_path, .{});
+    defer f.close();
+    const fst = try f.stat();
+    try std.testing.expectEqual(@as(u32, 0o600), @as(u32, @intCast(fst.mode & 0o777)));
+}

src/sockpath.zig

Old		New
@@ -15,6 +15,17 @@ const std = @import("std");
15	/// the kernel's and belongs in one place, the wording is theirs.	15	/// the kernel's and belongs in one place, the wording is theirs.
16	pub const max_sun_path = 107;	16	pub const max_sun_path = 107;
17		17
		18	/// Where a binary looks when nobody named a socket. The default path is
		19	/// part of a socket path's identity too: it is what makes two binaries
		20	/// started with no `--sock` land on the SAME daemon, so it lives here with
		21	/// the bound rather than once per binary.
		22	pub fn defaultSockPath(alloc: std.mem.Allocator) ![]const u8 {
		23	if (std.posix.getenv("XDG_RUNTIME_DIR")) \|dir\| {
		24	return std.fmt.allocPrint(alloc, "{s}/muxd.sock", .{dir});
		25	}
		26	return std.fmt.allocPrint(alloc, "/tmp/muxd-{d}.sock", .{std.os.linux.getuid()});
		27	}
		28
18	/// A socket file's identity at the moment it was bound, so teardown can	29	/// A socket file's identity at the moment it was bound, so teardown can
19	/// tell our socket from one that replaced it.	30	/// tell our socket from one that replaced it.
20	///	31	///

src/webhub.zig

Old		New
@@ -508,6 +508,12 @@ fn dialLoop(
508	/// bytes JSON cannot carry raw in a string plus control chars; labels	508	/// bytes JSON cannot carry raw in a string plus control chars; labels
509	/// are argv (hosts, paths), not hostile input, but a path with a quote	509	/// are argv (hosts, paths), not hostile input, but a path with a quote
510	/// in it must not break the page.	510	/// in it must not break the page.
		511	///
		512	/// Deliberately NOT muxa's jsonEscape, though the two look alike: this one
		513	/// sends every control byte to `\u00XX` (one rule, no table to get wrong)
		514	/// while muxa spells the short forms `\n`, `\r`, `\t`. Both are valid JSON
		515	/// and parse identically, but the bytes differ, and each is pinned by its
		516	/// own test. Sharing one would rewrite one side's output for no gain.
511	pub fn tilesJson(alloc: std.mem.Allocator, labels: []const []const u8) ![]u8 {	517	pub fn tilesJson(alloc: std.mem.Allocator, labels: []const []const u8) ![]u8 {
512	var out: std.ArrayList(u8) = .empty;	518	var out: std.ArrayList(u8) = .empty;
513	errdefer out.deinit(alloc);	519	errdefer out.deinit(alloc);

src/xdg.zig

Old		New
@@ -105,20 +105,19 @@ pub fn hostCachePathFrom(
105	return std.fmt.allocPrint(alloc, "{s}/.cache/mux/hosts/{s}", .{ h, host });	105	return std.fmt.allocPrint(alloc, "{s}/.cache/mux/hosts/{s}", .{ h, host });
106	}	106	}
107		107
108	/// Create `path`'s parent directories and tighten the immediate parent to	108	/// Create `dir` and everything above it, then tighten `dir` itself to
109	/// 0700. Both files this project writes under a home directory — the key	109	/// 0700. Every directory this project creates to hold something private —
110	/// and the handoff cache — hold a credential and want exactly this, so the	110	/// the key file's parent, the handoff cache's, and the shell-integration
111	/// policy and the reason it is subtle live here rather than in two copies.	111	/// shim directory — wants exactly this, so the policy and the two subtle
112	/// A `path` with no directory component is a no-op.	112	/// parts of it live here rather than in a copy per caller.
113	pub fn makePrivateParent(path: []const u8) !void {	113	pub fn makePrivateDir(dir: []const u8) !void {
114	const dir = std.fs.path.dirname(path) orelse return;
115	try std.fs.cwd().makePath(dir);	114	try std.fs.cwd().makePath(dir);
116	// makePath leaves 0755, which does not expose the file's contents —	115	// makePath leaves 0755, which does not expose a contained file's
117	// that is 0600 — but does expose that it exists and what it is called.	116	// contents — that is 0600 — but does expose that it exists and what it
118	// ssh's answer for the analogous directory is 0700 and there is no	117	// is called. ssh's answer for the analogous directory is 0700 and
119	// reason to be looser. Only the LAST component is tightened: the	118	// there is no reason to be looser. Only THIS component is tightened:
120	// parents on the way (`~`, `~/.config`) are the user's own business	119	// the parents on the way (`~`, `~/.config`, the runtime directory) are
121	// and are not ours to re-permission.	120	// the user's own business and are not ours to re-permission.
122	// `.iterate = true` is not optional here: Dir.chmod fchmods the	121	// `.iterate = true` is not optional here: Dir.chmod fchmods the
123	// directory's own fd, and without it the fd is opened O_PATH, which	122	// directory's own fd, and without it the fd is opened O_PATH, which
124	// fchmod refuses.	123	// fchmod refuses.
@@ -127,6 +126,13 @@ pub fn makePrivateParent(path: []const u8) !void {
127	try d.chmod(0o700);	126	try d.chmod(0o700);
128	}	127	}
129		128
		129	/// The same, for callers holding the path of the FILE that is going to
		130	/// live there. A `path` with no directory component is a no-op.
		131	pub fn makePrivateParent(path: []const u8) !void {
		132	const dir = std.fs.path.dirname(path) orelse return;
		133	try makePrivateDir(dir);
		134	}
		135
130	/// 32 random bytes at `path`, mode 0600, parent directories created and	136	/// 32 random bytes at `path`, mode 0600, parent directories created and
131	/// the immediate parent tightened to 0700.	137	/// the immediate parent tightened to 0700.
132	/// Refuses to overwrite: rotation is `rm` + `keygen`, deliberate on both	138	/// Refuses to overwrite: rotation is `rm` + `keygen`, deliberate on both

test/agent.sh

@@ @@ -0,0 +1,746 @@ @@
+#!/bin/sh
+# End-to-end for the agent surface: muxd daemon + muxa client, binary level.
+# Every verb muxa has prints one JSON object, so every assertion here is made
+# against a PARSED object rather than a grep of the line — a field that got
+# renamed, or a number that became a string, is a failure this suite can see.
+#
+# Unlike test/e2e.sh this one does NOT exit on the first failure: each
+# scenario is bounded on its own and reports PASS/FAIL/SKIP, and the suite
+# exits nonzero at the end if any failed. A run that finds two defects should
+# report two, not the first one and a silence.
+set -u
+# Binaries: the two under test, defaulting to the build output next to this
+# script's repo. Positional overrides keep e2e.sh's convention for a caller
+# (build.zig, a packaging check) that wants to name them explicitly.
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+MUXD="${1:-$ROOT/zig-out/bin/muxd}"
+MUXA="${2:-$ROOT/zig-out/bin/muxa}"
+[ -x "$MUXD" ] || { echo "agent FAIL: no muxd at $MUXD (run: zig build)"; exit 1; }
+[ -x "$MUXA" ] || { echo "agent FAIL: no muxa at $MUXA (run: zig build)"; exit 1; }
+# The two tools every scenario needs, checked here rather than per-scenario
+# because a box without them cannot run ANY of this: python3 parses every
+# assertion (see jget) and builds the relay, and `timeout` is what makes a hung
+# muxa a failure instead of a wedged suite. Missing either is a refusal to run,
+# not a skip — nine SKIP lines and exit 0 would be this suite reporting success
+# for work it did not do.
+for _tool in python3 timeout; do
+    command -v "$_tool" >/dev/null 2>&1 ||
+        { echo "agent FAIL: no $_tool — this suite cannot assert or bound anything without it"; exit 1; }
+done
+# One directory for everything this run writes: sockets, keys, captures, the
+# relay, the TUI's HOME. Removed by the trap, so a failing run leaves nothing
+# behind but its output.
+TMP="${TMPDIR:-/tmp}/mux-agent-$$"
+mkdir -p "$TMP" || exit 1
+# Hermetic homes, for e2e.sh's reasons: the key-bearing scenarios must see OUR
+# key and never the developer's ~/.config/mux/key, and $SHELL is read the same
+# way — a daemon started without --shell would otherwise run the operator's
+# login shell and its whole rc on the session under test.
+XDG_CONFIG_HOME="$TMP/cfg"
+XDG_STATE_HOME="$TMP/state"
+XDG_CACHE_HOME="$TMP/cache"
+export XDG_CONFIG_HOME XDG_STATE_HOME XDG_CACHE_HOME
+SHELL=/bin/sh
+export SHELL
+# muxa reads MUX_KEY_FILE BEFORE the default key path, so an operator who
+# happens to have one exported would silently change which key every QUIC
+# scenario below presents — and they would still pass, against the wrong key.
+unset MUX_KEY_FILE
+# Unix-socket daemons, one per scenario that owns its session's shell.
+SOCK_MARKS="$TMP/marks.sock"
+SOCK_TUI="$TMP/tui.sock"
+SOCK_SETTLE="$TMP/settle.sock"
+# QUIC daemons: the one behind the tearable relay, and the one the quiet-await
+# scenario dials directly (it must keep the DEFAULT idle timeout, which is the
+# very thing it is pinning, so it cannot share the reduced-idle daemon).
+SOCK_TEAR="$TMP/tear.sock"
+SOCK_QUIET="$TMP/quiet.sock"
+# Ports in a band of their own so a concurrent test/e2e.sh (11000..46000, in
+# 5000-wide slots) cannot collide, and per-run so two agent suites can overlap.
+# All four are ports we BIND, which is what makes the ephemeral range safe here.
+PORT_TEAR=$((51000 + ($$ % 900)))
+PORT_RELAY=$((52000 + ($$ % 900)))
+PORT_QUIET=$((53000 + ($$ % 900)))
+PORT_SINK=$((54000 + ($$ % 900)))
+KEY="$TMP/key"
+RELAY="$TMP/relay.py"
+RELAY_LOG="$TMP/relay.log"
+SINK_LOG="$TMP/sink.log"
+# The relay's two control files. Creating one is the tear; the relay removes it
+# and narrates what it did, so the log is evidence rather than the test's own
+# claim about what it asked for.
+CTL_FLOW="$TMP/ctl.flow"
+CTL_ALL="$TMP/ctl.all"
+TUISH="$TMP/tui.sh"
+# Every pid the trap may have to kill, declared before the trap is installed:
+# under `set -u` a bare $VAR the trap reads would abort the trap itself on a
+# failure that happened before the assignment, and the tmpdir would survive.
+D_MARKS=""
+D_TUI=""
+D_SETTLE=""
+D_TEAR=""
+D_QUIET=""
+RELAY_PID=""
+SINK_PID=""
+CLI_PID=""
+cleanup() {
+    # Every pid this run started, including the ones already dead: a kill that
+    # finds nothing is not a problem here, which is why the status of each one
+    # is discarded rather than tested. The `return 0` at the bottom is the load-
+    # bearing part — without it the trap would exit with the status of whatever
+    # ran last, and a cleanup that fired on a PASSING run could fail the suite.
+    for p in "$D_MARKS" "$D_TUI" "$D_SETTLE" "$D_TEAR" "$D_QUIET" \
+             "$RELAY_PID" "$SINK_PID" "$CLI_PID"; do
+        [ -n "$p" ] && kill "$p" 2>/dev/null
+    done
+    # ...and by socket, for the window between `muxd start`'s fork and the
+    # up-line this script reads its pid from. `muxd stop` on a path nobody
+    # serves is a no-op. These must precede the rm -rf: unlinking the sockets
+    # first would leave a live daemon nothing could reach by path.
+    for s in "$SOCK_MARKS" "$SOCK_TUI" "$SOCK_SETTLE" "$SOCK_TEAR" "$SOCK_QUIET"; do
+        [ -S "$s" ] && "$MUXD" stop --sock "$s" >/dev/null 2>&1
+    done
+    rm -rf "$TMP"
+    return 0
+}
+trap 'cleanup' EXIT INT TERM
+PASSES=0
+FAILS=0
+SKIPS=0
+pass() { PASSES=$((PASSES + 1)); echo "agent PASS: $1"; }
+fail() { FAILS=$((FAILS + 1)); echo "agent FAIL: $1"; }
+skip() { SKIPS=$((SKIPS + 1)); echo "agent SKIP: $1"; }
+# The reason a scenario function gave for stopping. Set by `why`, read by the
+# caller: a scenario reports ONE line, and this is how the first failed
+# assertion inside it gets into that line.
+#
+# It also reaps the scenario's in-flight client, because this is the ONLY path
+# out of a QUIC scenario that skips the `wait` below it. Without this a failing
+# tear scenario leaves a muxa still awaiting on the relay, and the scenario
+# after it counts that stranger's flows as its own — one failure would read as
+# two, and the second one would be fiction.
+WHY=""
+why() {
+    WHY="$1"
+    [ -n "$CLI_PID" ] && kill "$CLI_PID" 2>/dev/null
+    CLI_PID=""
+    return 1
+}
+# Run a scenario function: 0 passes, 1 fails with $WHY, 2 skips with $WHY.
+# One line per scenario, which is what makes the count pin at the bottom mean
+# "every scenario ran" rather than "some number of assertions ran".
+run_scenario() {
+    _name="$1"
+    shift
+    WHY=""
+    "$@"
+    case $? in
+) pass "$_name" ;;
+) skip "$_name: $WHY" ;;
+        *) fail "$_name: $WHY" ;;
+    esac
+}
+# One field out of a JSON object, re-encoded as JSON: `null`, `true`, `0`, and
+# `"marks"` WITH its quotes. The quotes are the point. muxa's contract is a
+# typed one — exit_code is a number, alt_screen a boolean, mechanism a string —
+# and a `str(v)` here would print all three the same way, so a daemon that
+# started spelling exit_code as "0" or alt_screen as "true" would sail past
+# every assertion below. Re-encoding makes the type part of the comparison, and
+# the cost is that string expectations at the call sites carry their quotes too.
+#
+# The three sentinels cannot collide with any of that: a field whose value were
+# literally the text `<missing>` re-encodes to `"<missing>"`, quotes and all. A
+# muxa that printed a stack trace fails as `<unparseable>`, not as a mismatch.
+jget() {
+    python3 - "$1" "$2" <<'PY'
+import json, sys
+try:
+    obj = json.load(open(sys.argv[1]))
+except Exception:
+    print("<unparseable>"); raise SystemExit(0)
+if not isinstance(obj, dict):
+    print("<not-an-object>"); raise SystemExit(0)
+if sys.argv[2] not in obj:
+    print("<missing>"); raise SystemExit(0)
+print(json.dumps(obj[sys.argv[2]]))
+PY
+}
+# want FILE FIELD VALUE — assert one field, naming the whole body on a miss so
+# a wrong answer is read in context rather than alone. VALUE is JSON: bare for
+# null/true/false/numbers, quoted for strings.
+want() {
+    _got=$(jget "$1" "$2")
+    [ "$_got" = "$3" ] && return 0
+    why "$2=$_got, want $3 [$(tr -d '\n' < "$1")]"
+}
+# Wait until PATTERN shows up in FILE. Keyed off the process's own output
+# rather than a fixed sleep, e2e.sh's convention.
+wait_for() {
+    _i=0
+    while [ "$_i" -lt $((${3:-10} * 20)) ]; do
+        [ -f "$1" ] && grep -q "$2" "$1" 2>/dev/null && return 0
+        sleep 0.05
+        _i=$((_i + 1))
+    done
+    return 1
+}
+# Start a detached daemon and hand back the pid IT reported. Never a pid this
+# script guessed from a process name: the suite kills what it started, and a
+# name match can only ever name a bystander.
+start_daemon() {
+    _log="$1"
+    shift
+    "$MUXD" start "$@" >"$_log" 2>&1
+    sed -n 's/^up .*pid=\([0-9]*\).*/\1/p' "$_log" | head -1
+}
+# Poll until muxa can answer on a socket: the session's shell has to have been
+# exec'd and the daemon's listener accepted before any assertion means
+# anything, and how long that takes is the box's business, not a constant here.
+wait_ready() {
+    _i=0
+    while [ "$_i" -lt 100 ]; do
+        "$MUXA" status --sock "$1" --timeout 1000 >/dev/null 2>&1 && return 0
+        sleep 0.05
+        _i=$((_i + 1))
+    done
+    return 1
+}
+# start_ready PIDVAR LOG SOCK ARGS... — bring a daemon up and wait for it to
+# answer, storing its pid in the named variable and calling `why` with the
+# whole story if either half fails. The bring-up is identical in every scenario
+# that needs a plain daemon, and a scenario that got only PART of it right — a
+# pid but no readiness wait — would fail later, somewhere else, as a flake.
+#
+# PIDVAR is set the INSTANT the pid is known, before the readiness wait and
+# whatever that wait decides. That ordering is the load-bearing part: a daemon
+# that came up and then never answered is still a daemon this run started, and
+# a version that only assigned on success would leave it running past cleanup.
+#
+# The two scenarios that do NOT use this (the TUI and the QUIC tear) want a
+# daemon that failed to come up to be a stashed message rather than an
+# immediate return, and folding that in would cost more than it saves.
+start_ready() {
+    _var="$1"
+    _log="$2"
+    _sock="$3"
+    shift 3
+    eval "$_var=\$(start_daemon \"\$_log\" \"\$@\")"
+    eval "_pid=\$$_var"
+    [ -n "$_pid" ] || why "daemon never printed an up-line [$(cat "$_log")]" || return 1
+    wait_ready "$_sock" || why "daemon never answered on $_sock" || return 1
+    return 0
+}
+now_ms() { python3 -c 'import time; print(int(time.time() * 1000))'; }
+echo "agent: ports ${PORT_TEAR}/${PORT_RELAY}/${PORT_QUIET}/${PORT_SINK}, tmp $TMP"
+# --- 1: marks. A shell with OSC 133 injected knows its own exit codes -------
+# The only mechanism that can report an exit code at all, so all three
+# assertions here are really one: `mechanism=marks` is what makes the number
+# in `exit_code` the command's rather than a guess.
+scen_marks() {
+    [ -x /bin/bash ] || { WHY="no /bin/bash to inject marks into"; return 2; }
+    start_ready D_MARKS "$TMP/marks.log" "$SOCK_MARKS" --sock "$SOCK_MARKS" --shell /bin/bash || return 1
+    timeout 20 "$MUXA" run --sock "$SOCK_MARKS" --timeout 8000 'true' >"$TMP/m1" 2>&1
+    _rc=$?
+    [ "$_rc" -eq 0 ] || why "run 'true' exited $_rc [$(tr -d '\n' < "$TMP/m1")]" || return 1
+    want "$TMP/m1" reason '"returned"' || return 1
+    want "$TMP/m1" mechanism '"marks"' || return 1
+    want "$TMP/m1" exit_code 0 || return 1
+    timeout 20 "$MUXA" run --sock "$SOCK_MARKS" --timeout 8000 'false' >"$TMP/m2" 2>&1
+    want "$TMP/m2" reason '"returned"' || return 1
+    want "$TMP/m2" mechanism '"marks"' || return 1
+    # The command failed; muxa did not. A nonzero exit_code is an ANSWER, and
+    # an agent that branches on muxa's own status must not see it as an error.
+    want "$TMP/m2" exit_code 1 || return 1
+    # A marker the session's shell cannot expand differently than we spell it,
+    # and one that is unique per run so a stale grid can never satisfy it.
+    _mark="out-$$"
+    timeout 20 "$MUXA" run --sock "$SOCK_MARKS" --timeout 8000 "echo $_mark" >"$TMP/m3" 2>&1
+    want "$TMP/m3" reason '"returned"' || return 1
+    want "$TMP/m3" mechanism '"marks"' || return 1
+    want "$TMP/m3" exit_code 0 || return 1
+    # Exactly the output, not "contains": the span between the two marks is
+    # the command's transcript, and a prompt or an echoed command line leaking
+    # into it is the bug this equality is here to catch.
+    want "$TMP/m3" output "\"$_mark\"" || return 1
+    "$MUXD" stop --sock "$SOCK_MARKS" >/dev/null 2>&1
+    D_MARKS=""
+    return 0
+}
+run_scenario "marks: exit codes and output come back from a bash session" scen_marks
+# --- The ephemeral TUI, which two scenarios share --------------------------
+# The spec's field specimen: a daemon whose session is not a shell at all but a
+# throwaway full-screen program. `muxd start` has no `--` argv, and --shell
+# execs whatever path it is given, so a one-line wrapper carries the argument.
+# HOME points into the tmpdir for e2e.sh's $SHELL reason: ~/.lesskey and
+# ~/.vimrc are arbitrary code on the session under test.
+#
+# The outcome splits three ways, and the split is the point: no TUI on the box
+# is the environment's business and skips, but a TUI that is here and whose
+# daemon did not come up is a DEFECT and must fail. Blanking D_TUI for both
+# would report a broken muxd as a skip — and would also lose the pid, orphaning
+# a daemon that is merely unresponsive rather than dead.
+TUI_BIN=""
+TUI_QUIT=""
+TUI_SKIP=""
+TUI_FAIL=""
+TUI_OK=""
+if command -v vi >/dev/null 2>&1; then
+    TUI_BIN=$(command -v vi)
+    TUI_QUIT=':q!\n'
+elif command -v less >/dev/null 2>&1; then
+    TUI_BIN=$(command -v less)
+    TUI_QUIT='q'
+fi
+if [ -z "$TUI_BIN" ]; then
+    TUI_SKIP="neither vi nor less on this box"
+else
+    mkdir -p "$TMP/home"
+    # Single-quoted in the generated script, both of them: $TMP contains $$ and
+    # is usually tame, but a TMPDIR with a space in it would otherwise split
+    # HOME in half and hand `exec` an argument it never meant to have.
+    {
+        echo '#!/bin/sh'
+        echo "HOME='$TMP/home'; export HOME"
+        # less reads its own switches out of the environment; a developer with
+        # -F exported would make the session exit before it was ever driven.
+        echo 'LESS=; export LESS'
+        echo 'unset LESSOPEN LESSCLOSE'
+        echo "exec '$TUI_BIN' /etc/hostname"
+    } > "$TUISH"
+    chmod +x "$TUISH"
+    # D_TUI keeps the pid whatever happens next, so cleanup can always reach a
+    # daemon that came up but never answered.
+    D_TUI=$(start_daemon "$TMP/tui.log" --sock "$SOCK_TUI" --shell "$TUISH")
+    if [ -z "$D_TUI" ]; then
+        TUI_FAIL="the TUI daemon printed no up-line [$(tr -d '\n' < "$TMP/tui.log")]"
+    elif wait_ready "$SOCK_TUI"; then
+        TUI_OK=1
+    else
+        TUI_FAIL="the TUI daemon (pid $D_TUI) never answered on $SOCK_TUI"
+    fi
+fi
+# The gate both TUI scenarios open with: 1 for a defect, 2 for a box that has
+# no TUI to drive. `return $?` propagates whichever it was.
+tui_gate() {
+    [ -z "$TUI_FAIL" ] || { WHY="$TUI_FAIL"; return 1; }
+    [ -n "$TUI_OK" ] || { WHY="$TUI_SKIP"; return 2; }
+    return 0
+}
+# --- 2: the alt-screen guard ------------------------------------------------
+# Ordered before the drive below because that one ENDS this session. Nothing
+# on a full-screen program's grid can mean "the command returned" — there are
+# no marks, no prompt, and no rows to attribute — so the honest answer to
+# `run` is that the wait timed out. A fabricated `returned` here would be the
+# worst failure in the surface: an agent would read an exit code that no
+# command ever produced.
+scen_altguard() {
+    tui_gate || return $?
+    timeout 20 "$MUXA" run --sock "$SOCK_TUI" --timeout 1500 'true' >"$TMP/g1" 2>&1
+    _rc=$?
+    want "$TMP/g1" reason '"timeout"' || return 1
+    # Exit 3 is the whole point of having a code for it: `returned` and
+    # `settled` are answers and exit 0, a timeout is a question still open.
+    [ "$_rc" -eq 3 ] || why "exit $_rc, want 3 [$(tr -d '\n' < "$TMP/g1")]" || return 1
+    return 0
+}
+run_scenario "alt-screen: run times out rather than fabricating a return" scen_altguard
+# --- 3: the ephemeral TUI, driven and quit ---------------------------------
+scen_tui() {
+    tui_gate || return $?
+    timeout 20 "$MUXA" status --sock "$SOCK_TUI" --timeout 5000 >"$TMP/t1" 2>&1
+    want "$TMP/t1" alt_screen true || return 1
+    # Marks are a shell's doing. A program that is not a shell cannot have
+    # them, and claiming otherwise is what scenario 2 would then read.
+    _mech=$(jget "$TMP/t1" mechanism)
+    [ "$_mech" != '"marks"' ] || why "mechanism=marks on a TUI that no shell started" || return 1
+    timeout 10 "$MUXA" send --sock "$SOCK_TUI" -- "$TUI_QUIT" >"$TMP/t2" 2>&1
+    want "$TMP/t2" sent true || return 1
+    # The session ended: the pid the daemon reported for itself is gone. Not
+    # the socket, which is unlinked a moment before the process is actually
+    # down — only a pid can answer this.
+    _i=0
+    while kill -0 "$D_TUI" 2>/dev/null; do
+        _i=$((_i + 1))
+        [ "$_i" -lt 100 ] || why "the TUI quit but its daemon (pid $D_TUI) is still up 5s later" || return 1
+        sleep 0.05
+    done
+    D_TUI=""
+    # ...and the next call against the corpse is a JSON OBJECT, which is the
+    # contract an agent depends on: there is no reply muxa can give that an
+    # agent has to parse as prose, and no path here that panics.
+    timeout 10 "$MUXA" status --sock "$SOCK_TUI" --timeout 2000 >"$TMP/t3" 2>&1
+    _rc=$?
+    [ "$_rc" -ne 0 ] || why "status against a dead daemon exited 0 [$(tr -d '\n' < "$TMP/t3")]" || return 1
+    _err=$(jget "$TMP/t3" error)
+    case "$_err" in
+        "<unparseable>"|"<missing>"|"<not-an-object>")
+            why "no JSON error object after the session ended: [$(tr -d '\n' < "$TMP/t3")]" || return 1 ;;
+    esac
+    # A panic prints a trace and an error message; the grep is what tells the
+    # two apart when the object above happens to parse anyway.
+    ! grep -qi 'panic\|segmentation\|\.zig:[0-9]' "$TMP/t3" ||
+        why "a stack trace, not an error object: [$(cat "$TMP/t3")]" || return 1
+    return 0
+}
+run_scenario "ephemeral TUI: alt_screen seen, quit driven, death reported as JSON" scen_tui
+# --- 4: settle, on a shell with no marks -----------------------------------
+# `settled` and `returned` are BOTH honest here and which one arrives is a
+# race: --settle 300 accepts 300ms of quiet as the end of the command, and the
+# pgid probe sees the foreground group go back to the shell at the second the
+# sleep exits. What must never come back is `timeout` — the client asked a
+# question a markless session can answer two different ways, and "I don't
+# know" is not one of them.
+scen_settle() {
+    start_ready D_SETTLE "$TMP/settle.log" "$SOCK_SETTLE" --sock "$SOCK_SETTLE" --shell /bin/sh || return 1
+    timeout 20 "$MUXA" run --sock "$SOCK_SETTLE" --settle 300 --timeout 10000 'sleep 1' >"$TMP/s1" 2>&1
+    _rc=$?
+    [ "$_rc" -eq 0 ] || why "run exited $_rc [$(tr -d '\n' < "$TMP/s1")]" || return 1
+    _reason=$(jget "$TMP/s1" reason)
+    case "$_reason" in
+        '"settled"'|'"returned"') ;;
+        *) why "reason=$_reason, want \"settled\" or \"returned\" [$(tr -d '\n' < "$TMP/s1")]" || return 1 ;;
+    esac
+    # No marks means no exit code, and muxa says so with a null rather than a
+    # zero — an agent must never read "it worked" out of a mechanism that
+    # cannot know.
+    want "$TMP/s1" exit_code null || return 1
+    "$MUXD" stop --sock "$SOCK_SETTLE" >/dev/null 2>&1
+    D_SETTLE=""
+    return 0
+}
+run_scenario "settle: a markless sleep returns an answer, never a timeout" scen_settle
+# --- The QUIC half ----------------------------------------------------------
+# Everything below needs a key, a daemon holding a UDP port, and — for the two
+# tear scenarios — a path this suite can break on purpose WITHOUT root. The
+# relay is that path: a UDP forwarder in front of the daemon's port, which
+# muxa dials instead. Tearing is a control file, not a signal and not a kill,
+# because the flow has to keep being ABSORBED after it breaks: a relay that
+# died would have the kernel answer with ICMP port-unreachable, and a refusal
+# is the fast path, not the loss this is modelling.
+#
+# The tear blackholes the flow it is told about and keeps forwarding NEW ones.
+# That is exactly a path that went away and a client that came back on another
+# one, and it is what makes the heal deterministic: no timing window to hit,
+# because the redial's fresh source port is never the torn one.
+cat > "$RELAY" <<'PY'
+import os, socket, select, sys
+listen_port, target_port, ctl_flow, ctl_all = int(sys.argv[1]), int(sys.argv[2]), sys.argv[3], sys.argv[4]
+front = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+front.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+front.bind(("127.0.0.1", listen_port))
+backs, owner, blocked, block_all = {}, {}, set(), False
+sys.stderr.write("relay up %d -> %d\n" % (listen_port, target_port)); sys.stderr.flush()
+while True:
+    if os.path.exists(ctl_flow):
+        blocked |= set(backs.keys()); os.remove(ctl_flow)
+        sys.stderr.write("relay: tore %d flow(s)\n" % len(blocked)); sys.stderr.flush()
+    if os.path.exists(ctl_all):
+        block_all = True; os.remove(ctl_all)
+        sys.stderr.write("relay: blackholed everything\n"); sys.stderr.flush()
+    ready, _, _ = select.select([front] + list(backs.values()), [], [], 0.05)
+    for s in ready:
+        if s is front:
+            data, addr = front.recvfrom(65535)
+            if block_all or addr in blocked:
+                continue
+            b = backs.get(addr)
+            if b is None:
+                b = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+                b.connect(("127.0.0.1", target_port))
+                backs[addr], owner[b.fileno()] = b, addr
+                sys.stderr.write("relay: flow %d\n" % len(backs)); sys.stderr.flush()
+            try:
+                b.send(data)
+            except OSError:
+                pass
+        else:
+            try:
+                data = s.recv(65535)
+            except OSError:
+                continue
+            addr = owner.get(s.fileno())
+            if addr is not None and not block_all and addr not in blocked:
+                front.sendto(data, addr)
+PY
+# Every way this setup can go wrong is a DEFECT, and every one of them fails
+# rather than skips. There is no environmental escape hatch left at this point:
+# python3 and `timeout` were made hard prerequisites at the top of the file, so
+# what remains — keygen refusing, the key not landing where keygen said it did,
+# the QUIC daemon not coming up, the relay not binding — is either muxd
+# misbehaving or this box handing out a port twice. A skip here would be the
+# one door in the suite wide enough for a real regression to walk through
+# wearing green: `muxd --quic` breaking outright would have reported "4 passed,
+# 5 skipped" and exited 0, which is CI saying yes to a broken binary.
+QUIC_FAIL=""
+if ! "$MUXD" keygen >"$TMP/keygen.log" 2>&1; then
+    QUIC_FAIL="muxd keygen failed [$(tr -d '\n' < "$TMP/keygen.log")]"
+elif ! cp "$XDG_CONFIG_HOME/mux/key" "$KEY" 2>/dev/null; then
+    QUIC_FAIL="keygen wrote no key where it said it did [$(tr -d '\n' < "$TMP/keygen.log")]"
+fi
+if [ -z "$QUIC_FAIL" ]; then
+    # The reduced idle is the schedule the tear scenarios wait for. It is a
+    # transport parameter, so the NEGOTIATED value is the min of the two ends
+    # and this daemon's 4s governs both — muxa has no idle flag of its own,
+    # and waiting out its 15s default twice would be most of this suite's
+    # runtime. The quiet-await scenario below deliberately does not use it.
+    D_TEAR=$(start_daemon "$TMP/tear.log" --sock "$SOCK_TEAR" --shell /bin/bash \
+        --quic "127.0.0.1:$PORT_TEAR" --key "$KEY" --quic-idle-ms 4000)
+    if [ -z "$D_TEAR" ]; then
+        QUIC_FAIL="the QUIC daemon printed no up-line [$(tr -d '\n' < "$TMP/tear.log")]"
+    elif ! wait_ready "$SOCK_TEAR"; then
+        QUIC_FAIL="the QUIC daemon (pid $D_TEAR) never answered on $SOCK_TEAR"
+    fi
+fi
+if [ -z "$QUIC_FAIL" ]; then
+    python3 "$RELAY" "$PORT_RELAY" "$PORT_TEAR" "$CTL_FLOW" "$CTL_ALL" >"$RELAY_LOG" 2>&1 &
+    RELAY_PID=$!
+    wait_for "$RELAY_LOG" "relay up" 5 || QUIC_FAIL="the relay never bound $PORT_RELAY [$(tr -d '\n' < "$RELAY_LOG")]"
+fi
+# The gate every QUIC scenario opens with. One outcome only — there is nothing
+# left here that a box could legitimately be excused from.
+quic_gate() {
+    [ -z "$QUIC_FAIL" ] || { WHY="$QUIC_FAIL"; return 1; }
+    return 0
+}
+# --- 5: a tear mid-await heals, and the command still ran exactly once ------
+# The two claims an agent's whole reconnect story rests on. The reply that
+# arrives after the heal carries the ORIGINAL command's return — muxa re-issued
+# its await from the watermark it already held, so the daemon answered about
+# the same command rather than starting a new wait — and the command ran once,
+# which is the no-input-resend rule: a client that re-sent its cmdline on
+# reconnect would have run it twice, and on anything but `sleep` that is a
+# second deploy, not a second read.
+scen_tear_heal() {
+    quic_gate || return $?
+    _tally="$TMP/tally"
+    rm -f "$_tally"
+    # Counted in the FILESYSTEM, not in the grid: a grid count would also see
+    # the echoed command line, and a wrapped row would make it a guess.
+    timeout 40 "$MUXA" run --quic "127.0.0.1:$PORT_RELAY" --key "$KEY" --timeout 25000 \
+        "sleep 12; echo ran >> $_tally" >"$TMP/q1" 2>&1 &
+    CLI_PID=$!
+    # Tear once the await is genuinely in flight — proved by the relay having
+    # opened the flow, not by a sleep that hopes it has.
+    wait_for "$RELAY_LOG" "relay: flow 1" 10 || why "the client never reached the relay [$(cat "$RELAY_LOG")]" || return 1
+    sleep 1
+    : > "$CTL_FLOW"
+    wait_for "$RELAY_LOG" "relay: tore" 5 || why "the relay never acted on the tear [$(cat "$RELAY_LOG")]" || return 1
+    wait "$CLI_PID"
+    _rc=$?
+    CLI_PID=""
+    [ "$_rc" -eq 0 ] || why "run exited $_rc after the heal [$(tr -d '\n' < "$TMP/q1")]" || return 1
+    want "$TMP/q1" reason '"returned"' || return 1
+    want "$TMP/q1" mechanism '"marks"' || return 1
+    want "$TMP/q1" exit_code 0 || return 1
+    # A second flow through the relay is the reconnect, observed from outside
+    # muxa. Without it the reply could only mean the tear never landed, and
+    # this scenario would be asserting nothing at all.
+    grep -q "relay: flow 2" "$RELAY_LOG" ||
+        why "no second flow: the reply came back without a redial [$(cat "$RELAY_LOG")]" || return 1
+    _ran=$(wc -l < "$_tally" 2>/dev/null || echo 0)
+    [ "$_ran" -eq 1 ] || why "the command ran $_ran time(s), want exactly 1" || return 1
+    return 0
+}
+run_scenario "quic: a tear mid-await heals, and the command ran exactly once" scen_tear_heal
+# --- 6: a tear with nothing to come back to is fatal, and says so ----------
+# The reconnect is spent once. When the redial cannot complete, the failure an
+# agent reads must be the WHOLE story: the wait died because the path tore, and
+# it stayed dead because the redial could not finish. An agent told only
+# `Timeout` goes and checks its own command; an agent told `connection lost;
+# reconnect failed: Timeout` knows to check the network.
+scen_tear_fatal() {
+    quic_gate || return $?
+    # A hang is the failure mode here, so the deadline is asserted twice: the
+    # outer `timeout` makes one impossible to sit through, and the wall clock
+    # below makes one impossible to pass with.
+    # The flow number this client will be given, read off the log rather than
+    # assumed: a scenario above that failed before its redial would leave a
+    # different count, and a hardcoded 3 would then wait for a flow that never
+    # comes and report THAT as this scenario's failure.
+    _flow=$(( $(grep -c "relay: flow" "$RELAY_LOG") + 1 ))
+    _t0=$(now_ms)
+    timeout 30 "$MUXA" run --quic "127.0.0.1:$PORT_RELAY" --key "$KEY" --timeout 12000 \
+        'sleep 20' >"$TMP/q2" 2>&1 &
+    CLI_PID=$!
+    wait_for "$RELAY_LOG" "relay: flow $_flow" 10 || why "the client never opened a new flow [$(cat "$RELAY_LOG")]" || return 1
+    sleep 1
+    : > "$CTL_ALL"
+    wait_for "$RELAY_LOG" "blackholed" 5 || why "the relay never blackholed [$(cat "$RELAY_LOG")]" || return 1
+    wait "$CLI_PID"
+    _rc=$?
+    CLI_PID=""
+    _spent=$(( $(now_ms) - _t0 ))
+    [ "$_rc" -ne 0 ] || why "run exited 0 with the path gone [$(tr -d '\n' < "$TMP/q2")]" || return 1
+    [ "$_rc" -ne 124 ] || why "muxa hung past the outer 30s bound" || return 1
+    # --timeout plus muxa's 2s grace over the daemon's own window, plus room
+    # for the box. Anything near 30s means the deadline was not honoured.
+    [ "$_spent" -lt 20000 ] || why "took ${_spent}ms for a 12000ms timeout" || return 1
+    # The COMPOSED narrative, not merely a prefix of it. muxa has three endings
+    # for a lost connection and only one of them is honest here: this client
+    # redialled and the redial could not complete. A bare `connection lost`
+    # means nothing tried to redial, and `connection lost again, after the one
+    # reconnect` means the redial was already spent — both would be regressions
+    # in this setup, and a `"connection lost"*` glob would pass for either.
+    _detail=$(jget "$TMP/q2" detail)
+    case "$_detail" in
+        '"connection lost; reconnect failed: '*) ;;
+        *) why "detail=$_detail, want '\"connection lost; reconnect failed: ...' [$(tr -d '\n' < "$TMP/q2")]" || return 1 ;;
+    esac
+    return 0
+}
+run_scenario "quic: a tear with no path back fails with the whole story" scen_tear_fatal
+# --- 7: a quiet await outlives the idle timeout ----------------------------
+# A DIFFERENT daemon, with the default 15s idle: the connection has to be kept
+# alive by keepalives across a wait during which neither end has anything to
+# say. The failure this pins is a timeout at ~15s reported as a lost
+# connection — an agent would go looking for a network fault that never
+# happened, and the honest answer (still running) would have been one field.
+scen_keepalive() {
+    quic_gate || return $?
+    start_ready D_QUIET "$TMP/quiet.log" "$SOCK_QUIET" --sock "$SOCK_QUIET" --shell /bin/bash \
+        --quic "127.0.0.1:$PORT_QUIET" --key "$KEY" || return 1
+    timeout 40 "$MUXA" await --quic "127.0.0.1:$PORT_QUIET" --key "$KEY" --timeout 20000 >"$TMP/q3" 2>&1
+    _rc=$?
+    [ "$_rc" -eq 3 ] || why "await exited $_rc, want 3 [$(tr -d '\n' < "$TMP/q3")]" || return 1
+    want "$TMP/q3" reason '"timeout"' || return 1
+    # The number is the assertion: 15000 would be the idle timeout wearing a
+    # timeout's clothes, and only a duration past it proves the keepalives ran.
+    _dur=$(jget "$TMP/q3" duration_ms)
+    [ "$_dur" -ge 18000 ] 2>/dev/null ||
+        why "duration_ms=$_dur — the wait did not survive the 15s idle timeout" || return 1
+    "$MUXD" stop --sock "$SOCK_QUIET" >/dev/null 2>&1
+    D_QUIET=""
+    return 0
+}
+run_scenario "quic: a quiet 20s await outlives the 15s idle timeout" scen_keepalive
+# --- 8: the session's death beats the connection's ------------------------
+# Both ends of this race end the wait, and only one of them is the truth. The
+# shell exited 5; the connection then closed BECAUSE it did. Reporting the
+# close is reporting the consequence and losing the cause, and the exit code
+# is the one thing the agent came for.
+#
+# Coupling worth naming: this dials the tear daemon DIRECTLY, but it is the
+# third scenario to drive that one bash session — 5 and 6 reached it through
+# the relay. Scenario 6 leaves a `sleep 20` running there whether it passes or
+# fails: killing the client does not kill what the session was already typed.
+# What covers it is scenario 7, which spends 20s of its own in between, so the
+# sleep is long finished before `exit 5` is ever sent. If 7 itself fails fast
+# that margin narrows, hence the 12s bound rather than a snug one — the queued
+# `exit 5` still lands, just late. Never a hang either way: the outer `timeout`
+# is the backstop.
+#
+# Not given its own daemon because the session's death IS the assertion — this
+# scenario destroys what it runs on, so it goes last among the three regardless.
+scen_session_exit() {
+    quic_gate || return $?
+    timeout 30 "$MUXA" run --quic "127.0.0.1:$PORT_TEAR" --key "$KEY" --timeout 12000 \
+        'exit 5' >"$TMP/q4" 2>&1
+    _rc=$?
+    # An ANSWER, not a failure: the command is over and this is how.
+    [ "$_rc" -eq 0 ] || why "run exited $_rc [$(tr -d '\n' < "$TMP/q4")]" || return 1
+    want "$TMP/q4" reason '"session_ended"' || return 1
+    want "$TMP/q4" exit_code 5 || return 1
+    return 0
+}
+run_scenario "quic: a session that exits 5 reports 5, not a lost connection" scen_session_exit
+# The tear daemon's session is gone with it; drop the pid so cleanup does not
+# chase one, and let the socket backstop cover the rest.
+D_TEAR=""
+# --- 9: a destination that swallows still honours --timeout ----------------
+# Not a refusal: a never-listening port answers with ICMP and muxa fails
+# instantly, which proves nothing about the deadline. A UDP listener that reads
+# and never replies makes the HANDSHAKE hang, and the only thing that can end
+# it is muxa's own clock.
+scen_blackhole() {
+    quic_gate || return $?
+    # The relay, blackholing from birth: its control file exists before it
+    # starts, so it swallows the first packet it ever sees.
+    : > "$TMP/sink.all"
+    python3 "$RELAY" "$PORT_SINK" "$PORT_TEAR" "$TMP/sink.flow" "$TMP/sink.all" >"$SINK_LOG" 2>&1 &
+    SINK_PID=$!
+    wait_for "$SINK_LOG" "relay up" 5 || why "the sink never bound $PORT_SINK [$(cat "$SINK_LOG")]" || return 1
+    _t0=$(now_ms)
+    timeout 20 "$MUXA" status --quic "127.0.0.1:$PORT_SINK" --key "$KEY" --timeout 2000 >"$TMP/q5" 2>&1
+    _rc=$?
+    _spent=$(( $(now_ms) - _t0 ))
+    kill "$SINK_PID" 2>/dev/null
+    SINK_PID=""
+    [ "$_rc" -ne 0 ] || why "status exited 0 against a blackhole [$(tr -d '\n' < "$TMP/q5")]" || return 1
+    [ "$_rc" -ne 124 ] || why "muxa hung past the outer 20s bound" || return 1
+    # The ceiling that must NOT be hit is the 15s handshake idle timeout: a
+    # muxa that ignored --timeout would land there, and this bound is under it
+    # by enough that only the flag can explain the number.
+    [ "$_spent" -lt 6000 ] || why "took ${_spent}ms for a 2000ms timeout — the flag was not honoured" || return 1
+    _err=$(jget "$TMP/q5" error)
+    case "$_err" in
+        "<unparseable>"|"<missing>"|"<not-an-object>")
+            why "no JSON error object [$(tr -d '\n' < "$TMP/q5")]" || return 1 ;;
+    esac
+    return 0
+}
+run_scenario "quic: a blackholed destination fails on --timeout, not on the idle ceiling" scen_blackhole
+# The count, pinned against a literal for e2e.sh's reason: a scenario that
+# silently stops running is the failure mode no assertion inside it can catch.
+TOTAL=$((PASSES + FAILS + SKIPS))
+if [ "$TOTAL" -ne 9 ]; then
+    echo "agent FAIL: $TOTAL scenarios reported, want 9 — one did not run"
+    FAILS=$((FAILS + 1))
+fi
+echo "agent: $PASSES passed, $FAILS failed, $SKIPS skipped"
+[ "$FAILS" -eq 0 ] || exit 1
+exit 0