fa0eb22a

docs: M10 record and roadmap close — cleared on the real box

a73x 2026-08-09 15:48

Commit message

docs: M10 record and roadmap close — cleared on the real box

Kill criterion evidence, five defect writeups with the assert-the-
literal rule, accepted gaps with rationale, and the two banked stages
(attach auto-start, ssh->QUIC handoff) promoted to the head of the
trial-friction tier with their sketches referenced.

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

docs/decisions.md

+  It still fails structurally on fast links; the form that fixes it is now
+  standard and written down.
+## 2026-08-09 (M10 — QUIC ergonomics)
+**Verdict: cleared, on the real box.** The whole QUIC story is four
+commands — `muxd keygen`; one ssh line placing the key; `ssh HOST 'muxd
+start --quic 0.0.0.0'`; `mux quic://HOST` — with no port or key path
+typed anywhere and the trust posture unchanged (32-byte PSK, permissive
+files refused, no unauthenticated mode). Kill criterion held on the LAN
+box from a clean slate: the commands as written landed a session on the
+first attach; a marker survived full ssh logout (the spawning session
+died while daemon pid 8829 lived on — noting the box had `Linger=yes`,
+which governs `systemd --user` and not a setsid daemon, so
+`KillUserProcesses` at its default `no` is the operative mechanism and
+the one the README's survival sentence claims); ten attach/detach
+cycles never
+started a second daemon (enumeration matched the tracked up-line pid
+exactly); the `start` rerun no-op'd with exit 0; `dump` carried the
+marker. Spec: superpowers/specs/2026-08-09-m10-quic-ergonomics-design.md
+(re-cut mid-design from "daemon auto-start" when the user pointed at the
+lower-hanging fruit; the auto-start and ssh→QUIC-handoff stages are
+banked there with full sketches).
+Shipped: `muxd keygen` (0600 key in a 0700 dir, refusal is atomic at the
+syscall and leaves bytes untouched); default key path
+`$XDG_CONFIG_HOME/mux/key` with resolution `--key` > `MUX_KEY_FILE` >
+default-if-present on BOTH binaries (`pickKey` pure and unit-pinned, its
+call site pinned separately by e2e — see the third gate below; the
+daemon reading the env var is new); default port 4433 both parsers,
+single constant in quic_server.zig; `muxd start` (probe → fork/setsid →
+poll; already-running is a no-op exit 0; failure names the log;
+`~/.local/state/mux/muxd.log` truncated per spawn); honest `--via`
+failure (`lostMsg`: new wording iff `via != null` and no frame ever
+arrived — for any other transport it would be a different lie);
+`--version` on both binaries from one build.zig constant; systemd fully
+deleted (contrib/ units, `LISTEN_FDS` socket activation — verified
+working same-day before removal, this commit range is the resurrection
+reference — and `owns_sock_file`, whose dev/ino teardown check stays and
+is still mutation-covered both ways).
+**Defects found and fixed en route:**
+- **`muxd start` panicked (exit 134) whenever its child died young** —
+  the poll loop's second `waitpid(NOHANG)` after its own reap gets
+  ECHILD, which the stdlib maps to `unreachable`. Fired on exactly the
+  first-run mistake the failure line exists for (`--quic` before the key
+  was placed); neither test layer covered a dying child (the unit stub
+  slept forever, every e2e start succeeded). Fixed 9bd43fc: a pid owes
+  exactly one reap; pinned at both layers by a stub that exits
+  immediately.
+- **Three plan mutation gates could not fail.** The port tests asserted
+  `expectEqual(quic.default_port, …)` — the constant against itself, a
+  tautology that stayed green under mutation; the race scenario typed
+  its marker *after* the race through the same socket path, so a stolen
+  socket answered indistinguishably; and the key-resolution order,
+  swapped at its CALL SITE (`envKey() orelse o.key` in `run()`),
+  passed both layers while a live daemon authenticated with the wrong
+  key — until 144f6af the daemon's env path had zero automated coverage
+  anywhere. Two rules now standing. First: **assert the literal, never
+  the constant the code under test reads** — the shape is a defect
+  whenever the constant is a contract with something outside the
+  process (a second binary, a user), fine when private. Second, and the
+  likelier to recur in a codebase that rightly extracts for
+  testability: **a pure function's unit test pins the function, not its
+  call site** — extraction can move the risk into the argument list
+  rather than removing it (`pickKey`'s three parameters are all
+  `?[]const u8`, so a swap compiles silently), and the extraction needs
+  its own end-to-end pin where it is called. Replaced with literal
+  pins, a head-on stolen-socket e2e, and the call-site key scenario.
+- **Third instance of cross-binary drift**: two independent 15_000
+  idle-ms constants, each self-asserted only. Single-sourced beside
+  `default_port` and pinned by literal (abae058).
+- **Two silent-side-effect test bugs**: the keygen refusal test re-read
+  through a kept fd (follows the inode — an unlink-and-replace of the
+  credential passed); and the spawn test truncated the developer's real
+  `muxd.log` (post-`muxd start`, that is a live daemon's log NUL-holed
+  by `make test`). Both proven by control before and after fixing
+  (ce7a921, 35ae0b2).
+- **`std.posix.exit` in a fork child under link_libc is exit(3)** —
+  atexit handlers plus the *parent's* inherited stdio buffers flushed
+  twice. `exit_group` is the only safe child exit (7b4208f).
+- **M9 burst flake, 1-in-3 under load (review runs at 715f71b)**:
+  `confirmed 5` was exact-equality on a timing-dependent counter; the
+  M9 WAN record itself shows the counter legitimately short (churn
+  flush, `abandoned=1`). Now `>= 4` via a separate `want_stat_ge`
+  helper — separate so weakening a *correctness* counter (contradicted,
+  expired: still exact) never becomes a habit. Four consecutive green
+  suites after (implementer's Task 10 runs at d587aa2), plus the
+  reviewer's two at the same commit.
+**Accepted, with rationale in place:** the e2e start scenarios leak a
+daemon if they fail inside the two assertions between spawn and pid
+capture (closing it would mean parsing the pid before asserting the
+lines that prove it is there); `muxd start --version` is an unknown
+argument (`--version` is recognized at argv[1] only — a command, not a
+flag, and with `keygen`/`start` present that stays a rule, not an
+exception).
+**Banked by M10:** attach auto-start (`muxd proxy`/local `mux` call the
+spawn helper; unix-socket only; silence stays meaningful) and the
+ssh→QUIC handoff (`muxd endpoint` prints port+key over ssh; client-side
+cache with a ~2s attach deadline; the coordination ssh stays alive as
+the fallback proxy; key belongs to the host-user on disk, outliving
+daemons — restarts invalidate only cached ports; rotation = delete +
+restart; measure the wrong-key failure mode before trusting any
+deadline number) — both fully sketched in the spec. Also banked: an
+absolute-plus-relative bound pattern where a guard's threshold is
+derived from a path it does not bound (the `refuse` helper carries the
+worked example); a decision on `quic://[NAME]` — the portless-bracket
+branch now DNS-resolves any bracketed string where it was refused
+before M10, a behavior that fell out of the IPv6 handling rather than
+being chosen; and a Zig plan-writing trap that bit twice: an inferred
+error set silently loses a member when its only `return error.X` is
+removed (breaking distant switch arms), and an error *set* return like
+`execveZ`'s cannot be `_ =` discarded.
+Provenance worth keeping honest: the 0700 key directory (b405645) and
+the cross-binary version-drift e2e pin (a33238a) were review findings
+that amended the spec mid-milestone, not design foresight.
+Process note for the record: subagent pipeline as in M9 (implementer +
+reviewer in isolated worktrees, mutations written first). The reviewer
+re-fired mutations independently every round and found the waitpid HIGH
+the suite was structurally blind to; the implementer twice refused to
+tick a mutation checkbox that could not fire and said so instead of
+proceeding. One review round was NOT-APPROVED; everything else landed
+without rework cycles.
+## Open (owed by later milestones)
+- Scrollback retention *tuning*. The policy itself was decided in M1 and

docs/roadmap.md

Old		New
@@ -5,9 +5,9 @@ The forward view, one item per line, ranked. History and evidence live in
5	this file at each milestone close and whenever the queue reorders; the	5	this file at each milestone close and whenever the queue reorders; the
6	queue's order is set by the user, not by this file.	6	queue's order is set by the user, not by this file.
7		7
8	Now: `v0.0.1-1` tagged; M1–M9 complete; in field trial on real VMs.	8	Now: M1–M10 complete; `v0.0.1-2` published as a Linux tarball; in
9	Trial feedback outranks everything below — what actually hurts in use is	9	field trial on real VMs. Trial feedback outranks everything below —
10	better data than any of this ranking.	10	what actually hurts in use is better data than any of this ranking.
11		11
12	## M9 — prediction (speculative local echo) — complete	12	## M9 — prediction (speculative local echo) — complete
13		13
@@ -31,11 +31,33 @@ failure found ngtcp2 being re-entered on every QUIC exchange —
31	constant, with a rare consequence — which is fixed and, unusually, was	31	constant, with a rare consequence — which is fixed and, unusually, was
32	proven so by a mutation that fired immediately.	32	proven so by a mutation that fired immediately.
33		33
		34	## M10 — QUIC ergonomics — complete
		35
		36	Verdict: cleared on the real box. The whole QUIC story is four
		37	commands — `muxd keygen`, one ssh line placing the key, `ssh HOST 'muxd
		38	start --quic 0.0.0.0'`, `mux quic://HOST` — no port or key path typed
		39	anywhere, trust posture unchanged. Kill criterion held on the LAN box:
		40	first-attach success from a clean slate, a marker surviving full ssh
		41	logout, ten attach/detach cycles with exactly one daemon counted by
		42	tracked pid (decisions.md, M10). systemd is deleted, not deferred: the
		43	contrib/ units and `LISTEN_FDS` activation are gone, with the removal
		44	commit as the resurrection reference. En route: a panic on `muxd
		45	start`'s own first-run-mistake path, two plan mutation gates that could
		46	not fail, and a third cross-binary constant drift — all fixed, all with
		47	the rule recorded ("assert the literal, never the constant the code
		48	under test reads").
		49
34	## Trial friction, likely next — and still outranked by trial feedback	50	## Trial friction, likely next — and still outranked by trial feedback
35		51
36	- Daemon lifecycle: attach does not auto-start `muxd run`; no install	52	- Attach auto-start: `muxd proxy` and local `mux` call the spawn
37	script; systemd user units exist in `contrib/` but are not the deployed	53	helper `muxd start` already uses, so `mux user@host` works on a box
38	recipe. First annoyance any trial hits.	54	where nothing is running. Sketched in the M10 spec; the helper is
		55	built and shipping.
		56	- ssh→QUIC handoff: `muxd endpoint` prints port+key over ssh;
		57	client caches both, tries QUIC first under a ~2s deadline, and the
		58	coordination ssh stays alive as the fallback proxy. Full sketch —
		59	including the key-outlives-the-daemon model and the stale-cache
		60	invariant — in the M10 spec's context section.
39	- First-backoff tuning: a reconnect after a tear can pay a 200ms–2s	61	- First-backoff tuning: a reconnect after a tear can pay a 200ms–2s
40	backoff step; measured ~4x win available on fast links, ~2x on slow	62	backoff step; measured ~4x win available on fast links, ~2x on slow
41	(decisions.md, M7).	63	(decisions.md, M7).