dc0a1f75

docs: simplify-round record; tools/collect.sh — the bundle in one go

a73x 2026-08-13 15:26

Commit message

docs: simplify-round record; tools/collect.sh — the bundle in one go

Five Importants found post-approval, all in the coverage gaps; the
declined-simplifications list so they stay declined; the pipeline-
exit-code doctrine from the re-review's near-miss. collect.sh gathers
versions, key FINGERPRINTS (never bytes), daemon logs, stats, hub
tiles, and per-box state over ssh into one pasteable bundle — the
M17 key-drift hunt, mechanized. First run against the live estate
found the field-trial wall had died unnoticed, which is the point.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/decisions.md

+client aborts the QUIC dial mid-handshake — probes must hold stdin
+open and detach with 0x1c, or rc=1 "did not answer" lies about the
+network.
+### M17 simplify round (2026-08-13, post-field-verdict)
+Three fresh-eyes reviewers (hub / core+shell / test+build) over the
+shipped milestone, then three sequential fix batches, each re-reviewed
+by its finder before push. Five Importants survived three prior review
+rounds, and every one clustered where the coverage wasn't: the hub's
+drain gating (buffered browser bytes invisible to poll — fixed by
+draining unconditionally, which also made the drain unit-testable for
+the first time), the badge state machine living in the DOM (now a
+status field with terminal-state precedence; revive-on-applied-frame
+is what makes a restarted session reappear on the wall), macOS metaKey,
+the wsclient stand-in re-attaching at the authoritative grid (the
+passivity contract's own fixture violating it, latently), and marker
+polls that had lost their asserts in copy-editing.
+Line-count honesty, recorded because both the fixer and the reviewer
+converged on it: the drainBrowser dedup was NOT a line win (+7 code
+lines after paying for the seam) — it was a one-owner win whose new
+seam produced the stranded-bytes pin at all. Estimates priced bodies;
+seams cost signatures.
+Declined simplifications, so nobody re-proposes them: sharing the
+fixtures' verb loops (three shared names, zero shared actions — an
+abstraction tax); merging the native/wasm build blocks (comment-per-
+module is the file's organizing style; no drift existed); merging
+pump/dialLoop (three concerns interleaved to save lines the two
+extractions already saved); std.json for /tiles (it emits invalid-UTF8
+slices as integer arrays — argv labels would change shape); the M13
+stop scenarios keep their spelled-out teardowns (muxd stop is their
+subject; a pin must not flow through machinery other tests can
+pressure into loosening).
+Process doctrine, banked from the re-review's own near-miss: `make
+test 2>&1 | tail` reports TAIL's exit code — a green claim over a
+failing build. Capture status before piping. The companion of
+"legible catches depend on test order": a catch that prints is
+worthless if the harness reads the wrong exit.
+Owed cheaply later, filed as observations not blockers: a
+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).

tools/collect.sh

@@ @@ -0,0 +1,103 @@ @@
+#!/bin/sh
+# One-shot diagnostic bundle: everything mux knows how to say about
+# itself, in one text stream, ordered for reading by a human or a model.
+#
+#   tools/collect.sh [--sock PATH]... [--host SSHHOST]... [--hub PORT] [--log-lines N]
+#
+# Collects: binary versions, the local daemon log, `muxd stats` per
+# --sock, the hub's /tiles if --hub names a port, and per --host (over
+# ssh): version, stats, log tail, key FINGERPRINT. Key material itself
+# is never read — fingerprints are what a key-drift diagnosis needs,
+# and were what the M17 field trial had to assemble by hand.
+#
+# Screen contents are NOT collected: `muxd dump` shows whatever the
+# session shows, and a diagnostic bundle should be safe to paste.
+set -u
+LINES=100
+SOCKS=""; HOSTS=""; HUB=""
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --sock) SOCKS="$SOCKS $2"; shift 2 ;;
+        --host) HOSTS="$HOSTS $2"; shift 2 ;;
+        --hub)  HUB="$2"; shift 2 ;;
+        --log-lines) LINES="$2"; shift 2 ;;
+        *) echo "usage: collect.sh [--sock PATH]... [--host SSHHOST]... [--hub PORT] [--log-lines N]" >&2
+           exit 2 ;;
+    esac
+done
+section() { printf '\n===== %s =====\n' "$1"; }
+# Every line of the bundle is stamped once, up top: the logs themselves
+# carry no timestamps (a known gap, on the roadmap), so the collection
+# instant is the only clock the bundle has.
+printf 'mux diagnostic bundle: %s on %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$(uname -n)"
+section "versions (local)"
+for b in muxd mux muxweb; do
+    p=$(command -v "$b" 2>/dev/null) || { echo "$b: not on PATH"; continue; }
+    printf '%s: %s (%s)\n' "$b" "$("$p" --version 2>&1)" "$p"
+done
+section "local key fingerprint"
+KEY="${MUX_KEY_FILE:-$HOME/.config/mux/key}"
+if [ -f "$KEY" ]; then
+    printf '%s  %s (%s bytes)\n' "$(sha256sum "$KEY" | cut -c1-16)" "$KEY" "$(wc -c < "$KEY")"
+else
+    echo "no key at $KEY"
+fi
+section "local daemon log (last $LINES lines)"
+LOG="${XDG_STATE_HOME:-$HOME/.local/state}/mux/muxd.log"
+if [ -f "$LOG" ]; then
+    printf '%s (%s bytes)\n' "$LOG" "$(wc -c < "$LOG")"
+    tail -n "$LINES" "$LOG"
+else
+    echo "no log at $LOG (a foreground daemon logs to its own stderr)"
+fi
+section "local daemons (observed, not claimed)"
+pgrep -a muxd 2>/dev/null || echo "no muxd processes"
+pgrep -a muxweb 2>/dev/null || echo "no muxweb processes"
+for s in $SOCKS; do
+    section "stats: $s"
+    muxd stats --sock "$s" 2>&1
+done
+if [ -n "$HUB" ]; then
+    section "hub on 127.0.0.1:$HUB"
+    if command -v curl >/dev/null 2>&1; then
+        printf 'tiles: '; curl -sf "http://127.0.0.1:$HUB/tiles" 2>&1 || echo "(no answer)"
+        printf '\n'
+    else
+        echo "curl not available; skipped"
+    fi
+fi
+for h in $HOSTS; do
+    section "box: $h"
+    # One ssh round trip per box, everything in one remote shell. BatchMode
+    # so an interactive prompt fails fast instead of hanging the bundle.
+    ssh -o BatchMode=yes -o ConnectTimeout=10 "$h" '
+        printf "version: %s\n" "$(muxd --version 2>&1)"
+        k=~/.config/mux/key
+        if [ -f "$k" ]; then
+            printf "key: %s  %s\n" "$(sha256sum "$k" | cut -c1-16)" "$k"
+        else
+            echo "key: none"
+        fi
+        pgrep -a muxd 2>/dev/null || echo "no muxd processes"
+        echo "stats: $(muxd stats 2>&1)"
+        l=${XDG_STATE_HOME:-$HOME/.local/state}/mux/muxd.log
+        if [ -f "$l" ]; then
+            printf "log %s (%s bytes), last '"$LINES"' lines:\n" "$l" "$(wc -c < "$l")"
+            tail -n '"$LINES"' "$l"
+        else
+            echo "no log at $l"
+        fi
+    ' 2>&1 || echo "(ssh to $h failed)"
+done
+section "end of bundle"