ba2f646a

docs: decide one read per readiness, and the seal after the last rollback

a73x 2026-08-27 13:22

Commit message

docs: decide one read per readiness, and the seal after the last rollback

docs/decisions.md

+alone found two defects the full suite could not: the leak sweep's
+vacuous-green guard was keyed to daemon one's capture, and two socket names
+were declared in the wrong group.
+## 2026-08-27 — the daemon reads a frame in one read, and seals what an upgrade adopted
+**One peer that stopped mid-frame parked the whole daemon.** Found on a live
+wall: `muxd stats` came back rc=124, and the daemon's stack said
+`unix_stream_read_generic` — one client had written part of a frame and gone
+quiet, and `proto.readFrame`'s loop was still waiting for the rest, with every
+other session's output, every await and every attach behind it. Killing that
+one client freed everything instantly. One byte on a fresh daemon reproduces
+it. The daemon side now does exactly one `read()` per readiness into a
+per-connection buffer and peels whole frames off it with `protocol.delimitFrame`
+through a single `Server.takeFrame`; a short read is just a buffer that is not
+a frame yet. Observers gained the same buffer, and promotion moves it with the
+fd, because the write that carries an attach usually carries the next frame
+behind it.
+**The client keeps its blocking read on purpose.** There, one thread owns one
+transport and has nothing else to do while a frame is in flight, so blocking
+until the frame is whole is the correct shape — the entry on `Conn.awaitFrameFd`
+already argues that half, and this changes nothing about it. The rule is about
+who is multiplexed, not about which read is safer.
+**What is still blocking on the daemon, and why it is filed rather than fixed.**
+Observer replies go out through `writeFrame` on the raw fd. Only
+`debug_dump --vt` can plausibly exceed the ~200 KiB socket send buffer, and only
+for a local peer that asks and then stops reading. Real, small, and not the
+thing that was wedging walls.
+**An upgrade adopted fds and never put the flag back.** `execUpgrade` clears
+`FD_CLOEXEC` on the listener, the QUIC socket, every pty master, every agent
+listener and the manifest memfd so they survive the exec. Nothing re-set it, so
+every shell spawned after an upgrade inherited the lot: the listener on fd 3,
+an agent socket on 5, a pty master, and one `memfd:mux-upgrade` per survived
+upgrade — and that memfd carries the QUIC key bytes. `Server.sealAdoptedFds`
+now re-seals them, and the memfd is closed rather than sealed, having been read.
+**The seal is placed after the last rollback exit, not in `initFromManifest`.**
+Rollback re-execs the OLD binary with those same fds, and a sealed fd does not
+cross that exec; the first placement broke the rollback e2e leg with a panic.
+So the call lives in `resumeRun`, past the point where rollback can still fire.
+The witness asks the OS, not the daemon: `/proc` for the post-exec shell's fd
+table (`socket:`, `memfd:`, `/dev/ptmx`) and the daemon's own for
+`memfd:mux-upgrade`. The QUIC socket's seal is unpinned — no e2e daemon in that
+leg runs `--quic`; filed.