@tikoci/quickchr 0.4.6 → 0.4.8

package/DESIGN.md

@@ -62,6 +62,41 @@ Modules (src/lib/)      ← qemu, images, versions, network, state, ...
 
     **Escape hatch.** Because the fallback is unconditional, `--accel <auto|tcg|hvf|kvm>` (and the `accel` setting / `QUICKCHR_ACCEL` env var) forces the accelerator verbatim and bypasses detection — so a fixed future image can be tested on HVF without a code change, and so forcing TCG stays possible for debugging elsewhere. `--accel hvf` on an arm64 guest still prints the panic caveat rather than silently obeying. This complements, and does not replace, the reactive respawn-once net in #8. Covered by `test/unit/platform.test.ts`. → [#97](https://github.com/tikoci/quickchr/issues/97)
 
+11. **A download is bounded by whether it is *moving*, not by a flat total** — `src/lib/download.ts` is the one download path for both `images.ts` and `packages.ts`. Before it, each caller had its own bound and they disagreed: images aborted at a flat `120_000` per attempt with three retries, packages had **no** deadline and **no** retries, so its only bound was whatever the calling test imposed.
+
+    A total-duration deadline cannot distinguish *slow* from *stuck*. It fires on a healthy transfer whose only sin is being large, and the retry path then re-downloads from zero — one slow transfer becomes three.
+
+    **The deadline sat inside the natural variance of a healthy transfer, which is why it was intermittent.** Measured locally 2026-07-31 against `download.mikrotik.com` — same 52.2 MB `all_packages-arm64-7.22.1.zip`, same link, same client, four consecutive attempts:
+
+    | attempt | elapsed | throughput | under the old flat 120 s? |
+    |---|---|---|---|
+    | 1 | 118.4 s | 0.421 MB/s | yes, by 1.6 s |
+    | 2 | 94.2 s | 0.528 MB/s | yes |
+    | 3 | **123.5 s** | 0.403 MB/s | **no — aborted** |
+    | 4 | 82.2 s | 0.606 MB/s | yes |
+
+    All four completed. **One in four exceeded the deadline**, and a fifth attempt through the new streaming path measured 129.4 s (0.385 MB/s) — so the range on one ordinary link is 82–129 s against a 120 s bound. The deadline was inside the distribution, and an unchanged healthy download therefore passed or failed on link jitter alone.
+
+    That is a sharper statement of the defect than a clean abort would have been, and it is why CI saw "both images needed two retries" *sometimes* rather than always. CI's cold ~0.35 MB/s (→ ~149 s) sits **below** this whole local range, which is why a hosted runner hit it far more reliably than this laptop does — run 30606079288, and B7's local suite where `provisioning.test.ts` spent 619 s of 992 s downloading with zero QEMU processes alive.
+
+    ⚠️ **Do not restate this as "the old code always aborted that download."** An earlier draft of this entry said so on the strength of a single 129.4 s measurement; the next attempt completed in 101.5 s and disproved it as a general claim. One measurement of an intermittent is a signal, not a fact — the same rule the CI program runs on.
+
+    **Two deadlines, and the failure says which fired.** Neither alone is sufficient: stall detection alone would let a transfer trickling at one byte per second run forever, and a size-derived budget alone cannot fail a wedge quickly.
+    - **Stall** (`DOWNLOAD_STALL_MS`, 30 s) — reset on every received chunk. Bounds *silence*, so a moving transfer is never aborted for being slow.
+    - **Transfer budget** — `DOWNLOAD_BUDGET_BASE_MS` (30 s for connect/TLS/headers) plus `content-length ÷ COLD_DOWNLOAD_FLOOR_BYTES_PER_S`, a **floor** throughput of 120 000 B/s ≈ ⅓ of the slowest cold transfer ever measured. The 52.2 MB zip gets 465 s. When the server sends no `content-length` the stated `DOWNLOAD_NO_LENGTH_BUDGET_MS` (15 min) applies and the outcome says so — verified that `download.mikrotik.com` *does* send it on both image and package artifacts, so the size-derived budget is the production path.
+
+    **Retry policy follows from that split.** `DOWNLOAD_STALLED` is retriable — a wedged socket usually moves on the next attempt. `DOWNLOAD_TOO_SLOW` is **terminal on purpose**: the budget is already ~3× the slowest throughput on record, so retrying re-downloads from zero on a link measured slower than the floor, which is the exact behavior this decision removes. It is a signal that the floor is wrong (or the link genuinely is), not something to paper over with another attempt.
+
+    **The floor constant has one home.** It lives here and `test/integration/timeouts.ts` re-exports it; `coldDownloadTestTimeout()` is *derived from* `transferBudgetMs()` rather than recomputing it, which makes one of #106's partial orders (`download deadline < test timeout`) structural instead of coincidental. Two constants asked not to drift are how they drift.
+
+    **Streaming also bounds memory, which the old path did not.** `await response.arrayBuffer()` held the entire artifact in RAM before writing it — 52.2 MB for the largest. Measured: a `Bun.file().writer()` sink writing 40 MiB in 1 MiB chunks keeps the file growing on disk in lockstep with flat RSS (22 MB throughout), so the transient allocation is gone. Recorded as a side effect, **not** as a claim about #76 — a 52 MB transient is not a plausible cause of a runner losing communication, and B8a/B8b should not treat this as having changed that picture.
+
+    **Partial transfers cannot poison the cache.** Downloads stream to a **per-call** `<dest>.<pid>-<uuid>.part` and are renamed only after a verified transfer. Per-call, not a fixed `<dest>.part`, because both callers guard only with `existsSync(destPath)` — two concurrent downloads of one artifact (two `quickchr start`s, parallel tests) would otherwise interleave writes into one file, publish the corrupt result, and delete each other's in-flight file. The unique suffix removes the collision without deduplicating the work; coalescing concurrent downloads needs a lock at both call sites and is a larger change.
+
+    Verification is two checks, because either alone leaves a hole: bytes received must equal `content-length` **when one was sent**, and a **zero-byte body is always a failure** regardless of framing. The second exists because Bun's fetch hands back an *unknown-length* response for a malformed `content-length` — measured against a raw stub, `4096.5` and `-5` are passed through as headers but deliver 0 bytes, while a blank value is stripped to `null` — and an unknown-length response has no length to verify against. Without it the empty file would be renamed into the cache and served as a complete artifact forever. No artifact quickchr downloads is empty, so this costs nothing. Both callers gate on `existsSync(zipPath)`, so a truncated file left at the destination would be served as a complete cached artifact forever. Resuming with a `Range` request would be better than either deadline (MikroTik sends `accept-ranges: bytes`) and is deliberately out of scope — this decision bounds and classifies a transfer, it does not change the transport. Covered by `test/unit/download.test.ts`. → [#116](https://github.com/tikoci/quickchr/issues/116)
+
+    ⚠️ **Testing note.** `Bun.serve` **drops an explicit `content-length` when the body is a `ReadableStream`** and frames the response `transfer-encoding: chunked`, so a stub built on it cannot exercise the size-derived budget at all — every response looks unknown-length. The anchor tests use a raw `Bun.listen` HTTP stub for that reason.
+
 ## Port Layout
 
 | Offset | Service    | Guest Port |
@@ -102,7 +137,10 @@ Current consumers are all first-party tikoci projects (centrs, donny, restraml),
 │       ├── serial.sock        # Serial console
 │       ├── qga.sock           # QGA (x86 only)
 │       ├── qemu.pid           # PID file
-│       └── qemu.log           # Output log
+│       ├── qemu.log           # Output log
+│       └── serial.log         # Serial console tee (only with QUICKCHR_SERIAL_LOG=1)
+└── failures/                  # Boot-failure reports (see below)
+    └── boot-failure-<machine>-<iso8601>.json
 ```
 
 **Global settings** live separately, under the XDG **config** tier (not the data tree
@@ -139,6 +177,14 @@ See MANUAL.md's CLI reference and environment-variables sections for the full su
 Full artifact map, dispatch recipes, and failure-diagnosis guide live in
 `.github/instructions/ci.instructions.md` — this section is the high-level rationale only.
 
+**The toolchain is part of the repository (#148).** `.bun-version` pins the exact Bun that
+CI, integration and release all install, enforced by `scripts/check-bun-pin.ts` in
+`bun run check`. Before this, `setup-bun` was called with no version anywhere, so the tested
+runtime could change between two identical commits — and did: a six-week gap with no `ci.yml`
+runs spanned the Bun 1.4.0 release, and the next PR inherited a 1.3.14 → 1.4.2 jump as if it
+were its own regression. Anything that can turn the build red is a dependency and belongs in
+a reviewable diff; "whatever is newest at run time" is not a version.
+
 **The 2026-07 refactor (#29)** replaced the organically-grown scheme (integration on every
 PR push, three parallel copies of the runner logic, `continue-on-error` green-washing)
 with a layered design:
@@ -170,7 +216,9 @@ with a layered design:
 - **`release.yml`** — one-click publish from committed release state: freshness gate
   (no suite re-run — main is kept continuously release-able) + `package.json` version
   with a matching non-empty CHANGELOG section → tag + GitHub Release + `npm publish
-  --provenance` (odd minor → `next`, even → `latest`). CI never bumps versions or pushes
+  --provenance` (odd minor → `next`, even → `latest`; a stable release is then also
+  tagged `next`, since there is no separately maintained pre-release line and `next`
+  must not point at something older than `latest`). CI never bumps versions or pushes
   to protected `main`.
 - **`ros-versions.yml`** — daily: new RouterOS versions (per channel) with no linux-x86
   record in `ci-data/tested-versions.json` ride the `routeros-targets` matrix of a
@@ -189,6 +237,33 @@ incidentally; crediting those suppressed the scheduler for versions no full suit
 targeted). The per-run files are the source of truth; `ci-metrics refold` rebuilds the
 rollup after fold-logic changes.
 
+**What survives losing a runner (#76, #77)**: measured on run
+[30665449265](https://github.com/tikoci/quickchr/actions/runs/30665449265), whose three
+`macos-x86` legs stopped communicating mid-suite. This is the constraint every
+lost-runner instrument has to be designed around, so it is recorded rather than
+re-derived:
+
+| Evidence | Survives? |
+| --- | --- |
+| Uploaded artifacts | **No** — `if: always()` steps never run |
+| The archived job log | **No** — the blob returns `BlobNotFound`, even though a *normally failing* leg in the same run keeps its full log. Failure preserves the log; runner loss destroys it |
+| The jobs API step ledger | **Yes** — the test step stays `in_progress` with a start time, later steps `pending`, and the job carries a `completed_at` |
+| A check run PATCHed during the leg | **Yes** — it is server-side the moment it is written, and stays un-closed |
+
+So a progress marker has to be *pushed out of the runner as it goes*; nothing collected
+at the end can work. That is what `ci-leg-checkpoint.ts` (per-file check-run updates) and
+`ci-leg-ledger.ts` (planned-vs-completed reconciliation into `ci-data/attempted-legs.json`)
+implement. The ledger is a **separate file from `tested-versions.json` by decision**: the
+version scheduler reads that file as a presence test, so recording an aborted run there
+would make the version look tested and silently stop rescheduling it.
+
+The same run also pins down #76's shape: the three legs died **62.0 / 64.1 / 65.0 minutes
+into their own jobs**, staggered with their own start times across 14 minutes of
+wall-clock. So the boundary is per-job elapsed, not a shared external event and not a
+round 60-minute constant. Read `completed_at` as an **upper bound** on the wedge — it is
+when the service gave up on a silent runner, and the interval between the runner going
+quiet and that verdict is uncharacterized.
+
 **Merge policy**: squash-only, PR title → main commit subject (write PR titles as
 conventional commits), PR body → commit body, branches auto-delete. Review threads must
 be resolved before merge (`required_conversation_resolution`) and automated reviews must
@@ -204,6 +279,174 @@ merges (`continue-on-error: true`). Thresholds are overridable via dispatch inpu
 - `{integration|main|sweep}-logs-<platform>` — bun test output + timing + metrics.ndjson +
   machine.json + qemu.log (7 days); durable timing lives on the `ci-data` branch
 
+### Boot-Failure Forensics (`src/lib/diagnostics.ts`)
+
+Discovered constraint from the `ci:slow-platform-flake` series (#76 #79 #80 #91):
+**a failure that cleans up after itself is unfixable.** Both `BOOT_TIMEOUT` paths
+used to `stop()` + `remove()` the machine and embed `qemu.log.slice(-1200)`, which
+on every recorded CI failure contained nothing but the cleanup SIGTERM. Four rules
+came out of that:
+
+1. **`waitForBoot()` classifies, it does not just return `false`.** A boot that
+   never becomes REST-ready is several different bugs wearing the same error:
+   `refused` = QEMU never bound the port (host-side); `probe-timeout` = it bound
+   and nothing behind it answered (guest-side); `reset`/`wrong-body` = the guest
+   answered and RouterOS is still settling (the #69 shape). Collapsing all of
+   them to a boolean is why #79 stayed open across two full CI runs. The tally
+   rides on an optional `BootProbeStats` out-param, so normal boots pay nothing.
+
+   **Do not read a live host port as "the guest is up."** Under the default
+   `user` (slirp) network mode QEMU's hostfwd `listen()`s for the process's whole
+   lifetime and accepts before it tries to reach the guest. Verified locally
+   (2026-07-27) by starting CHR with `mem: 32`: 72/72 probes `probe-timeout`,
+   `hostfwd: accepting`, `info status: running`, empty `serial.log`. So
+   `refused` is much rarer than intuition suggests, and `probe-timeout` — not
+   `refused` — is the ordinary signature of a guest that never booted.
+
+2. **The report is written outside the machine directory**, to
+   `<dataDir>/failures/`. Every integration test wraps its body in
+   `finally { cleanupMachine(name) }` → `remove()`, which deletes the machine
+   dir. A report written next to `qemu.log` is gone before CI can upload it,
+   *regardless* of `QUICKCHR_PRESERVE_ON_FAILURE`. The report therefore embeds
+   log contents rather than pointing at them, and stands alone.
+
+3. **`QUICKCHR_SERIAL_LOG=1` is opt-in, and must stay opt-in.** It adds
+   `logfile=` to the serial chardev, which is the only way to see what RouterOS
+   printed on a boot that never reaches REST — the socket chardev keeps no
+   history, so connecting *after* the failure shows nothing. But serial-console
+   provisioning types the generated user password in cleartext, so the log is
+   secret-bearing. CI turns it on because CI passwords are per-run throwaways.
+
+4. **Timeouts report where they stalled.** `monitorCommand()` records
+   connect → first byte → prompt → command written → response first byte, and
+   renders them into the timeout message. "Monitor command timed out" alone
+   cannot distinguish #80's hypotheses (monitor never greeted us vs. QEMU took
+   the command and went quiet); the phase line can, at the cost of a few
+   `Date.now()` calls on the success path.
+
+Two more came out of #105/#106, once the reports above proved only *that* #79's
+boot went silent:
+
+5. **Evidence has to localize, so the capture is layered by invasiveness.**
+   Host-side per-port classification from `info usernet` (read-only, always on)
+   → read-only guest snapshot over the serial console, which stays reachable
+   while REST is dead (on whenever a serial channel exists) → the counting-rule
+   probe, which writes a mangle rule into the guest and is therefore opt-in via
+   `QUICKCHR_DEEP_BOOT_DIAGNOSTICS=1` and skipped under
+   `QUICKCHR_PRESERVE_ON_FAILURE=1`. Each layer answers a question the one
+   before it cannot: `SYN_SENT` proves a silent drop but not *whose*; only a
+   counter inside the guest separates "RouterOS dropped it" from "it never
+   arrived". The RouterOS-side details (why mangle `passthrough` and not a
+   filter `accept`, why conntrack cannot answer this) live in
+   `provisioning.instructions.md`; the `info usernet` reading in
+   `qemu.instructions.md`.
+
+   The same secrecy rule as (3) applies one level up: guest payloads go to the
+   JSON report, and only credential-free shapes — row counts, booleans, a
+   verdict — reach the thrown error, which CI echoes into public job logs.
+
+6. **A timeout that outlives the forensics is not optional.** Integration tests
+   hardcoding `300_000` against a 480 s same-arch TCG budget meant bun killed
+   the test before `waitForBoot()` gave up, so the capture above never ran —
+   four #79 reproductions arrived bare for exactly this reason. Tests derive
+   their timeout from `defaultBootTimeout()` plus `BOOT_FORENSICS_BUDGET_MS`
+   (`test/integration/timeouts.ts`), and a unit test asserts the invariant
+   across every arch/accel combination. Note this is alignment, not tuning: the
+   4× same-arch TCG factor is still ~11× the measured 44 s worst case, and
+   cutting it needs its own measurement of the package-install and device-mode
+   paths (#106).
+
+Corollary for CI cache keys: `actions/cache` only saves when the primary key
+*missed*, so the concrete resolved RouterOS version belongs in the key (#91).
+The writable owner must prefetch and verify a declared image-and-package
+manifest before saving; saving opportunistic test byproducts makes a red or
+lost suite permanently cold, while saving only images makes immutable entries
+permanently package-incomplete. Acquisition is therefore a named pre-test step,
+restore-key extras are reconciled away before save so auto-prune cannot evict
+fixed fixtures later, and a manifest change bumps the cache-key generation.
+Raw images must have in-bounds DOS partition extents; package directories are
+published atomically with an exact filename/size manifest. Tests boot the same
+concrete pin named by the immutable key rather than resolving the channel again
+(#144).
+
+7. **The boot probe can break the service it is waiting for.** `restGet()`
+   implements its deadline as `req.destroy()` — a mid-flight TCP teardown. On
+   its own that is harmless. But an aborted request **followed by a completed
+   one** corrupts RouterOS `www`: the guest then resets incoming connections,
+   and a surviving connection is answered with the status computed for the
+   *aborted* request. An `admin:` probe carrying a valid empty password comes
+   back `401`. `waitForBoot()` emits exactly that pattern — overrun a probe,
+   then succeed on the next one 2 s later.
+
+   Reproduced deterministically on RouterOS 7.21.5, x86/HVF **and** arm64
+   cross-arch TCG, with `curl` in a separate process confirming it is
+   guest-side rather than a Bun `node:http` artifact
+   (`test/lab/www-abort-damage/`). Two consequences for design: a slow-but-alive
+   REST layer must be **waited for** rather than aborted, and backing off after
+   consecutive aborts matters because it is the abort/complete *alternation*,
+   not the abort count, that does the damage. It also means a REST status
+   received after any timeout in the same conversation cannot be trusted to
+   belong to the request that received it — the #69 surface.
+
+   Bounds, so this is not over-read: locally `www` recovers in 1.3–2.4 s, so the
+   *permanent* wedge in #79's CI forensics is **not** reproduced, and neither is
+   whatever made CI's very first probe exceed 3 s — locally a failed login
+   answers in ~125 ms even at `cpu-load: 100`. Both remain open, and the entry
+   point to the CI failure is still the unexplained one.
+
+8. **Readiness is not the end of the evidence.** Items 1–7 all instrument a boot
+   that never became REST-ready. #69 is the other shape: the machine boots, it
+   passes `waitForBoot()`, and a *later* request is reset — so every instrument
+   above was skipped and the failure arrived as one line of `ECONNRESET`.
+   `captureRunningFailure()` (`quickchr.ts`) runs the same instrument set against
+   a machine that is still up, and does not stop, remove, or otherwise touch it —
+   the caller owns the lifecycle and may well keep testing against it.
+
+   What that capture has to add is a `trigger` (`FailureTrigger` in
+   `diagnostics.ts`): the failed operation, the error with its `code`/`errno`,
+   `sinceReadyMs`, and the credential transition that preceded it. Without it the
+   report is a healthy machine with no statement of what broke — a boot-failure
+   report explains itself through `restProbe`, and here `restProbe` is null. The
+   transition is **stated by the caller, never inferred**: the capture can see
+   the auth header, but "who this request authenticates as" and "what just
+   changed on the guest" are different facts, and only the caller knows the
+   second. An absent field reads as "not recorded", which is true; a guessed one
+   would send the next reader down a path nobody actually took.
+
+   The two report kinds share one directory and one 20-file cap, which is why
+   pruning orders by the timestamp *inside* the filename rather than by the
+   filename: whole-name sort was chronological only while every report carried
+   one prefix, and would now rank every `post-readiness-failure-` above every
+   `boot-failure-`, deleting the newest of one kind to keep the oldest of the
+   other.
+
+   Building that capture surfaced a defect in the instrument it reuses. The
+   guest snapshot's per-query budget was sized on the ~0.3 s cost of a command on
+   an already-open console session, which left the **~11.4 s serial login**
+   unbudgeted — and `bootFailureGuestExec()` then *divided* that budget across
+   credential candidates, so no attempt could finish logging in. No credential was
+   ever marked working, every later query repeated the same split, and the
+   snapshot spent its full 60 s to report `consoleReachable: false` about a guest
+   answering serial in 10 ms. It read as a broken console, which is why it went
+   unnoticed on the boot path: there the guest usually *is* unreachable, so the
+   wrong answer looked right. Queries now carry a login allowance until one of
+   them answers (`GUEST_LOGIN_ALLOWANCE_MS`), with the per-candidate floor raised
+   to the measured login cost; the 60 s snapshot budget and the 180 s forensics budget
+   are unchanged, so no test timeout moves. Locally this took a capture from
+   61.1 s / 0 of 7 queries to 14.4 s / 7 of 7.
+
+   The general rule, since it is not obvious from the numbers: a console budget
+   has two parts that differ by ~40×, and only one of them is a round-trip.
+   `provisioning.instructions.md` has the phase-by-phase measurements.
+
+   Test-side, the same finding forces a single REST client:
+   `test/integration/chr-rest.ts` is the only way integration tests reach CHR.
+   Tests previously used Bun `fetch()` and, in one file, a hand-rolled `node:http`
+   copy of `restGet` — two extra connection-reuse policies that made "client or
+   guest?" unanswerable on every reset. Collapsing them is **confound removal,
+   not a fix**: run 30507484030 reset through `restGet` too, and
+   `test/lab/bun-pool/` never reproduced the pooling bug it was built to catch.
+
 ## Design Principles
 
 ### Scope Boundary — QEMU Expert, Not Orchestrator
@@ -230,6 +473,48 @@ The `default-route-distance=2` ensures the shared route is backup — SLiRP ethe
 
 **TCG hazard:** SLiRP half-open connections (TCP connect succeeds, data never flows) burn the full per-probe HTTP timeout in `waitForBoot`. Under cross-arch TCG where TCP round-trips are slow, this compounds badly. Lab: `test/lab/slirp-hostfwd/`.
 
+#### NIC MAC Addresses — Stable Per Machine, Assigned Once
+
+QEMU's default NIC address is `52:54:00:12:34:56`, incremented per NIC **within** a
+guest. NIC index *N* therefore holds the same address in *every* guest. That is
+harmless while machines only have `user` NICs (each SLiRP netdev is its own
+namespace and nothing is shared), and fatal the moment two machines share an L2
+segment — a named socket, a `socket:listen`/`socket:connect` pair, a TAP, or a
+RouterOS bridge on a hub VM. Forwarding then half-works, and every instinct points
+at RouterOS or the overlay rather than at the launcher (#154).
+
+quickchr assigns each NIC a locally-administered address: `02:` (bit 1 set =
+locally administered, bit 0 clear = unicast, so it can never collide with a
+vendor-assigned address) followed by five octets of a SHA-256 over the machine
+name, NIC index and a collision salt. Deriving rather than randomizing means a lab
+rebuilt under the same machine names presents the same addresses. The address is
+persisted in `machine.json` and `deriveMac()` is consulted only when a NIC has
+none, so a later change to the derivation cannot move an existing machine's
+addresses.
+
+**Assigned at creation only — never backfilled onto an existing machine.**
+RouterOS ties its persisted interface identity to the MAC. Change it and the guest
+treats the NIC as new: the `ether1` holding the DHCP client is orphaned, no address
+is obtained, and hostfwd accepts on the host side while every guest SYN is dropped
+— the same half-open signature as the SLiRP/ether1 hazard above, from a different
+cause.
+
+Grounded by A/B against a live CHR (7.24.2 x86, HVF), same machine and same disk:
+
+| MAC | Result |
+|---|---|
+| original | boots, REST ready |
+| changed | boot fails — 36 probe-timeouts over 178 s, all forwarded ports `dropped` |
+| restored | boots, REST ready |
+
+So a machine created before MACs existed keeps QEMU's defaults for its lifetime and
+must be recreated to get a stable address. Silently rewriting a working lab's L2
+identity on upgrade would be the worse trade.
+
+`deviceArgs()` in `network.ts` is the single place a `-device virtio-net-pci` is
+emitted; `qemu.ts`'s fallback path builds its own `-netdev` strings but calls into
+it, so a NIC cannot reach QEMU without its address.
+
 #### Host-Side L2 Capture (MNDP, MAC-Telnet)
 
 A caller can receive the guest's raw Layer-2 frames — RouterOS MNDP (UDP/5678
@@ -252,7 +537,7 @@ capture on any platform. Evidence: `test/lab/mndp/REPORT.md`.
 The dual of `hostfwd`: SLIRP's gateway `10.0.2.2` *is* the host from inside the
 guest, so guest-originated UDP to `10.0.2.2:<port>` reaches a host socket bound on
 loopback `<port>` with **no forward and no extra NIC**. This generalizes the TZSP
-path (`tzspGatewayIp`/`captureInterface`) — it is not TZSP-specific and reaches an
+path (`hostGatewayIp`/`captureInterface`) — it is not TZSP-specific and reaches an
 ordinary bound socket, not just a `tshark`/pcap capture. The host socket **must be
 unconnected**: SLIRP re-emits from a rewritten loopback source
 (`127.0.0.1:<ephemeral>`), which a `connect()`-ed socket would filter. This closed
@@ -313,6 +598,21 @@ Provisioning via REST API is preferred (simple HTTP calls). Serial console provi
 
 **Credential resolution** (`src/lib/auth.ts`): Priority order is (1) explicit `--user`/`--password` override, (2) provisioned user from `machine.json` (`state.user`), (3) CHR default `admin:` (empty password). Both `exec()` and `rest()` on ChrInstance use this.
 
+**`machine.json` holds two kinds of fact, and `clean()` is where they diverge.**
+Some fields describe the *guest* — what accounts exist on the disk right now:
+`user`, `managedSshKey`, `disableAdmin`, and the per-instance entry in the secret
+store. Others are *intent* — what to apply the next time provisioning runs:
+`packages`, `deviceMode`, `secureLogin`. `clean()` replaces the disk with a fresh
+image, so every guest fact it recorded is false the moment it returns, and nothing
+restores them: a post-`clean()` `start()` reaches `_launchExisting(…, undefined)`
+because `lastStartedAt` is set, so the erased account is never recreated. `clean()`
+therefore clears the guest facts (and deletes the managed keypair under
+`<machineDir>/ssh/`) and keeps the intent. Without that, credential resolution
+kept preferring `state.user` and authenticated every REST call, exec, and SCP as a
+user RouterOS had deleted — the confound removed ahead of #79's QEMU-version
+experiment. Priority (3) above is what a cleaned machine must land on, and it is
+the truth of a fresh CHR image: `admin` with an empty password.
+
 Output formatting via `--json` flag. RouterOS trick for structured output: wrap commands in `[:serialize to=json [<routeros-cmd>]]` to get JSON from any CLI command. For REST-to-CLI mapping, see tikoci/restraml `lookup.html`.
 
 ### Examples Philosophy
@@ -352,6 +652,307 @@ the CLI/library surface is tracked in
 
 A recurring lesson from downstream agents (donny, centrs, restraml): the friction is usually **finding** an existing capability, not a missing one. Issue #18 (centrs) nearly rebuilt UDP forwarding, `socket-connect` L2, and the guest→host gateway — all of which already existed — because the only way to choose among them was reading `src/lib/network.ts`. Rule: **every CLI-documented capability also needs a library-facing, by-goal surface** — JSDoc at the call site, a by-goal recipe (`docs/networking-recipes.md`), and coverage in the `routeros-quickchr` skill — or agents won't find it. Connection handoff for harnesses goes through `ChrInstance.descriptor()` / `quickchr inspect` / `quickchr env` (credential-bearing by design), never by reading `machine.json`. The structured, versioned **descriptor v1** contract that centrs consumes for `--quickchr` targets — its shape, per-service semantics, scope boundaries, and staged implementation plan — is specified in [`docs/centrs-interface.md`](./docs/centrs-interface.md) (issue [#71](https://github.com/tikoci/quickchr/issues/71)).
 
+### Tips — pointing at the better path without becoming chrome
+
+`quickchr exec` is a raw `/rest/execute` pipe: whatever the caller types is what RouterOS is asked to run, and quickchr has no opinion about whether the command is well-formed. centrs does — it checks a command's shape against the device's own command tree before running it and has per-path help — so `centrs --quickchr <name> <command>` is the better path for anything more than a one-liner. An agent that does not know this reads quickchr's source to find out, which is the discoverability failure described above, one layer up.
+
+The answer is a **tip**: one dim line, at the moment the better path applies. Three rules keep tips from turning into noise (`src/cli/tips.ts`):
+
+1. **stderr, always.** stdout is the command's result and must stay parseable — `quickchr inspect --json | jq` cannot be made to filter advice out of its own input.
+2. **A tip names a next command or a better-suited tool.** It never restates what just happened, and never appears where the command already said the thing.
+3. **Suppressible via `QUICKCHR_NO_TIPS=1`, and not gated on TTY.** The audience for "you probably wanted X" is agents and first-time users, and both usually run without one.
+
+### A mistyped or failed command leaves no state
+
+Three CLI defects reported from one external agent's 3-CHR lab were the same defect: quickchr turned a mistake into durable state and then could not describe it.
+
+- `--help` reached subcommands as an ordinary argument, so `add --help` created a machine and `networks sockets create --help` persisted a socket named `--help`. Help is now answered in the dispatcher, before dispatch, so a new subcommand cannot miss the guard.
+- An unrecognised flag on `add`/`start` was inert, so a typo downloaded 43 MB and created a machine. Those two commands — the ones that create machines — now check their flags against a registry (`src/cli/flags.ts`) first. The read-only commands stay tolerant.
+- A failure between `ensureDir()` and `saveMachine()` stranded a directory that `list` could not show, `remove` would not delete, and `add` still refused to reuse. `add` now cleans up after itself, and — because a SIGKILL still can strand one — `remove` clears a directory with no readable `machine.json`, `MACHINE_EXISTS` distinguishes the two cases, and `doctor` names `quickchr remove`, not `rm -rf`.
+
+The rule the three share: **clearing quickchr's own mess must never require knowing that the data dir exists.** A recovery step whose only form is `rm -rf ~/.local/share/quickchr/machines/<name>` is not a recovery step; it is a leak of an internal layout into the user's hands. The same rule is why machine and socket names are validated before anything is written — both become a path segment, so "what names are legal" is a storage-layout question the user should never have to answer.
+
+### A flag's arity is declared, not guessed
+
+`parseFlags` had one rule for two jobs: *if the next argument does not start with `--`, consume it as this flag's value.* That is right for `--version 7.24.3` and wrong for every boolean flag, which then eats the following positional — `quickchr start --vmnet-shared lab` set `vmnet-shared="lab"` and lost the machine name (#164). Arity now comes from `VALUE_FLAGS` in `src/cli/flags.ts`; a flag absent from that table is boolean and leaves the next argument alone. A typo is boolean too, which is why a misspelled `--version` followed by `lab` can now be reported as an unknown flag *with* the machine name intact, instead of silently consuming it.
+
+The audit matters as much as the table. `--vmnet-shared` was found by accident while fixing something else, and the only way to find its siblings was to re-read every `flag()` call site by eye. `test/unit/cli-flag-arity.test.ts` scans the CLI source for every flag read and cross-checks each name against the registry in both directions — so the next flag cannot skip the table by being forgotten, and nobody has to do that reading again. Writing it paid for itself immediately: the first version scanned only the `flag()`/`flagBool()` helpers, pronounced the registry complete, and missed three `cache prune` flags read straight off the object (`flags["older-than"]`), which the arity change had already broken. An audit is only as wide as the ways the code actually reads a flag.
+
+`--vmnet-shared` / `--vmnet-bridge <iface>` were removed rather than repaired: they were special cases for one network type that `--add-network` already expresses in general, both were already documented as deprecated aliases, and nothing generated them. A removed name is still recognized and errors with its replacement — deleting it outright would leave the flag "unknown", and for the tolerant read-only commands, ignored again. `vmnet-shared` is simultaneously the removed flag, QEMU's own netdev name, and a legacy `machine.json` value; only the first went, and a test pins the other two because the collision makes over-deletion easy.
+
+### An enumeration and a lookup fail differently
+
+`loadMachine()` parsed `machine.json` with no guard, so one corrupt file — a `saveMachine()` that died mid-write — threw a raw `SyntaxError` out of `quickchr list` and destroyed the state of every healthy machine alongside it (#165). One policy was being applied to two contracts:
+
+- **`get(name)` is a targeted lookup.** You named *that* machine, it is corrupt, and answering `null` would report a directory that exists as one that never did. It still throws — now `STATE_ERROR` naming the file and `quickchr remove <name>`, rather than a parse trace.
+- **`list()` is an enumeration** — best-effort across many. One bad entry aborting it is the enumeration failing at its own job, and it costs more signal than it keeps.
+
+Skipping alone would have traded a loud failure for a quiet one: a machine that was there yesterday just disappears, which is the shape of trouble that does *not* look like trouble. So the unreadable entry keeps its place in `list` as a row — marked, named, with the remedy attached — because it still holds a disk image and `list` is where anyone looks first. Deferring it to `doctor` assumes you already suspect something. Exit stays 0: the listing succeeded, and a non-zero exit would punish the working machines and break every script piping `list`.
+
+"Unreadable" is not the same as "unparseable", and review caught the first version confusing them: it guarded `JSON.parse` and rejected primitives and arrays, so `{"name":"lab3"}` was still cast to `MachineState`, still enumerated, and still reached `formatPorts(m.ports)` — `Object.entries(undefined)`, the same wholesale abort with a different stack. `loadMachine()` now checks the fields callers dereference unguarded (`REQUIRED_STATE_FIELDS`). That list is deliberately not a schema: it is the set that turns a bad file into a crash somewhere else, and every field in it has been required on `MachineState` since the commit that introduced the type, so it cannot condemn state any version of quickchr wrote. `cpu`/`mem` are left out precisely because a missing one prints oddly rather than throwing.
+
+Internally this is a three-way `tryLoadMachine()` (`ok` / `missing` / `unreadable`) that `loadMachine()` still collapses into "undefined or throw". Keeping the discriminated result unexported is the small diff; promoting it to public API is a rename if #58 lands.
+
+### A named socket says what it is
+
+An external agent's 3-CHR lab brought up two CHRs on `--add-network socket::skylab-mir`,
+got interfaces up, addresses assigned, and 100% packet loss with no error anywhere. It
+found the cause by opening `machine.json`: the link was UDP multicast, and the sandbox
+denied the send.
+
+The lab re-ran the question against its own VM on 2026-09-20, which turned the original
+hand-wave ("the sandbox blocks UDP") into something exact — and narrower:
+
+- The host is **Linux** (Ubuntu 24.04, seccomp-bpf active, `NoNewPrivs=1`, four filters).
+  `iptables` and `nft` are empty, so no firewall is involved. **This lab was never on
+  macOS**, which is why its finding is independent of the macOS defect below.
+- The denied call is **an unconnected `sendto()`/`sendmsg()` on an `AF_INET` `SOCK_DGRAM`
+  socket**, returning `EPERM` — strace-confirmed. Not "UDP". A `connect()`-ed UDP socket's
+  `send()` passes the filter, as does TCP, as does `AF_UNIX` `SOCK_DGRAM`.
+- `socket()`, `bind()` and `IP_ADD_MEMBERSHIP` all succeed; only the send is refused. So
+  the group joins cleanly and then silently carries nothing.
+- Loopback multicast fails **independently** of internet egress: `sendto()` to
+  `230.0.0.1:4000` gets the same `EPERM` as `sendto()` to `8.8.8.8:53`. It is not an
+  egress-only policy, which was the intuition that had to be tested rather than assumed.
+
+That maps onto one line of QEMU, which is why `mcast` died there and `dgram` did not
+(`net/socket.c`, `net_socket_receive_dgram()`):
+
+```c
+ret = RETRY_ON_EINTR(
+    s->dgram_dst.sin_family != AF_UNIX ?
+        sendto(s->fd, buf, size, 0, (struct sockaddr *)&s->dgram_dst, sizeof(s->dgram_dst)) :
+        send(s->fd, buf, size, 0)
+);
+```
+
+`mcast` takes the `AF_INET` branch — the exact call the filter denies. `dgram` over unix
+takes `send()`. `EPERM` is neither `EINTR` nor `EAGAIN`, so the frame is dropped and
+nothing is logged: the 100% loss, mechanically.
+
+One thing the lab explicitly withdrew: the failed 7.24.4 image downloads in the same
+session were **TCP egress-proxy stalls**, not UDP. Do not cite them as evidence here.
+
+Three separate defects converged on that one silence.
+
+1. **The only transport the CLI could reach was the one that fails silently.**
+   `createNamedSocket()` defaulted to `mcast`, and `networks sockets create` had no flag
+   to pick anything else.
+2. **`listen-connect`, the alternative the registry already modelled, had never worked.**
+   The role came from `entry.members.length === 0` at resolve time, but
+   `registerSocketMembers()` runs *before* `resolveAllNetworks()`, so the starting
+   machine had always added itself by then. `isFirst` was never true; every member
+   resolved to `connect=`; nobody ever listened.
+3. **Nothing printed the transport.** `start` did not name it, and `format.ts` tested
+   `s.type === "socket-named"` while the parser emits `{ type: "socket" }`, so `list`
+   and `info` fell through to `JSON.stringify` for every named socket.
+
+#### What the transports actually do
+
+Measured on QEMU 11.1.1, macOS Intel, CHR 7.24.4, rather than reasoned about — except
+the `listen-connect` column, measured later on `windows-x86`/TCG, CHR 7.24.4 (see below):
+
+| | `mcast` | `listen-connect` | `dgram` over unix |
+|---|---|---|---|
+| start order | any | listener first | **either end first** |
+| frames verified | broken on macOS | ICMP both ways | ICMP both ways, plus MNDP and IPv6 ND |
+| host ports | a multicast group | a TCP port | none |
+| send call | unconnected `sendto()`, `AF_INET` | TCP `send()` | `send()`, `AF_UNIX` |
+| machines | any number | 2 | 2 |
+| where a failure lives | host kernel / sandbox policy | quickchr's own registry | quickchr's own registry |
+
+`listen-connect` read `(was unreachable)` in that row until #172. It is the Windows
+default, so it is the one transport whose first end-to-end proof had to come from CI:
+run [35545697945](https://github.com/tikoci/quickchr/actions/runs/35545697945) created
+the link with no `--mode` at all, started slot 0 and slot 1 in that order, and pinged
+both ways over it. The QEMU side of the pair is not exotic — `network-mac.test.ts` had
+long covered the raw `socket-listen`/`socket-connect` specifiers on Windows — but the
+named-socket path around it (persisted mode, slot roles, auto-allocated port) had never
+been exercised on a real boot anywhere.
+
+The decisive point is not "TCP works on macOS" — it is **which silence quickchr can
+see.** A TCP pair does not fail loudly either: `connect=` to a dead port runs on with
+no error, no log and no exit, never retries when the listener appears later, and
+`listen=` accepts exactly one peer while leaving the listening socket open, so a third
+member's connect succeeds at the kernel level and receives nothing. But those failures
+are member count and endpoint occupancy, which are already persisted. A multicast
+failure lives in the host kernel, and no amount of bookkeeping can see it.
+
+#### The decision
+
+**A named socket defaults to `dgram` on macOS and Linux, and `listen-connect` on
+Windows** (AF_UNIX there has no `SOCK_DGRAM`). `mcast` stays first-class as the only
+N-way segment, and says at create time that it fails silently.
+
+The resolved default is **persisted at creation, never re-derived**. A
+`networks/<name>.json` states the transport it was made with, so one specifier never
+silently means two things — the objection that ruled out a platform-sniffing default
+in the first place.
+
+Two dgram failure modes the design has to own, both found by probing rather than
+reading:
+
+- **A duplicate `local.path` silently steals the link.** A second QEMU unlinks the
+  first's socket and binds its own: the inode changes, both processes stay alive, and
+  neither logs anything. This is why a third machine is a refusal rather than a
+  warning, and why endpoints are claimed before QEMU is spawned.
+- **`sun_path` is 104 bytes.** Checked at create time so the error names the data dir,
+  instead of arriving later as `UNIX socket path '...' is too long` against a path the
+  caller never chose.
+
+Claiming an endpoint is a cross-process read-modify-write, so it takes a **registry
+lock** and re-reads from disk inside it. Without one, `quickchr start a & quickchr start
+b &` — the shape the field report actually used — has both machines read `[null, null]`,
+both take slot 0, and the second write win: both QEMUs get the same `local.path`, and
+the duplicate-path theft above does the rest. A two-process repro lost an endpoint on
+12 of 12 rounds. Entries are also written with write-then-rename, because a truncating
+write let a concurrent reader see invalid JSON and report the socket as missing.
+
+The lock itself had the same class of bug on its first cut: a waiter that found the
+lock file created but not yet written to judged it stale and deleted it, so two
+processes believed they held it. A lock file whose pid is unreadable is now given a
+grace period before it counts as abandoned, which still reclaims a crashed holder.
+
+Endpoints are held in **numbered slots** rather than derived from live membership.
+Slot 0 is the listener (`listen-connect`) or endpoint A (`dgram`); the first machine
+to start has to name its peer's path before that peer exists, and a slot is the only
+thing both ends can agree on in advance. It also fixes (2) properly: a listener that
+stops and restarts comes back as the listener instead of demoting itself to a second
+connector.
+
+A consequence worth stating, because it is easy to document wrongly: the roles are
+fixed when the two machines *first* join, so `listen-connect` still has a start order
+afterwards — the listening machine must be up before the connecting one, since
+`connect=` fails silently and never retries. `dgram` has no ordering constraint at any
+point. A claim is also released if the launch that made it never reaches persisted
+state, so a start that fails after claiming an endpoint does not leave a link occupied
+by a machine that is not running. The invariant is the plain one — **a machine that is
+not running holds no endpoint** — and every path that reaches "stopped" has to honour
+it, including the two that do not go through `stop()`: a foreground run whose QEMU has
+exited, and `clean()`.
+
+The registry needs a second, wider lock as well. Automatic port allocation is
+`max(existing ports) + 1`, which reads *every* entry, so the per-entry lock does not
+help when the contenders are different names — three `mcast` links created at once all
+took port 4000 (15 of 15 rounds), silently collapsing three segments into one group.
+The registry-wide lock is always taken *inside* the per-entry one, so the order is
+fixed and two holders cannot deadlock.
+
+The lock alone is not enough, though: allocation also has to *see* the current
+registry. `listNamedSockets()` seeds itself from the in-memory cache and only reads
+disk for names it does not already hold, so a cached entry whose on-disk port has
+changed is never re-read — and the next allocation hands out a port that is taken.
+Reading only from disk is not the fix either, because that cache exists to work around
+Bun returning stale data from a read that follows a write on Windows. The two sources
+go stale in opposite directions, so allocation takes the **union** of both: it can only
+over-estimate the maximum, which wastes a port number, where trusting either one alone
+under-estimates it and collides.
+
+The acceptance bar, and the reason the visibility work is not cosmetic: **nothing about
+a named socket should require opening a file under the data dir.** Every place the
+field report had to read `machine.json` is a place quickchr knew the answer and did not
+print it. The same reasoning applies to the CLI's own options — a `--group` that cannot
+apply is an error rather than a silently dropped argument.
+
+#### Still open
+
+`dgram` and `listen-connect` both cap at two machines, and `mcast` — the N-way answer —
+is broken on macOS. **quickchr still has no 3-node rootless L2 segment on macOS.** That
+was true before this change; it is now explicit rather than presenting as a RouterOS
+fault. Tracked in #167.
+
+The in-repo alternative is a frame-repeating hub, and since `start` returns and `--bg` is
+not a detach (#159), there is no process to host one — a hub is a daemon, and "no daemon"
+is a standing design decision. So the work goes into making `mcast` usable instead, via
+two independent defects.
+
+**Ours:** quickchr never passes `localaddr=`, so `net_socket_mcast_create()` falls back to
+`imr_interface = INADDR_ANY` and sets no `IP_MULTICAST_IF`. The group therefore rides the
+host's default multicast interface rather than loopback. `IP_MULTICAST_LOOP` governs local
+delivery, not scoping. A `dgram` link cannot leave the filesystem; an `mcast` one does.
+The consequence — two people on one LAN using the default group joining each other's
+segments — is **a reading of the code plus the lab's `netstat -gn`, not a demonstrated
+two-host repro**; #167 step 1 is the probe that settles it.
+
+**Upstream:** `net_socket_mcast_create()` sets only `SO_REUSEADDR`, on a stated assumption
+that this suffices to share a multicast port — true on Linux, false on BSD/macOS, which
+require `SO_REUSEPORT` on every such socket. Still that way on QEMU master
+`c1c18d1e640b64292859ce9f30f3c344edfb0294` (2026-09-19). `test/lab/mndp/REPORT.md`
+isolates it to QEMU's side: the host joined on every interface *with* `SO_REUSEPORT` and
+still received nothing, and two CHRs on one group never discovered each other.
+
+**The two are independent, and it matters.** The macOS defect is a *delivery* failure —
+the send succeeds, only one socket receives. The Linux sandbox defect is a *permission*
+failure — the send never happens. They were found in different environments by different
+labs, neither reproduces the other, and fixing either leaves the other intact. Reading
+"mcast is broken" as one story is how the sandbox finding ended up attached to a macOS
+issue in the first place.
+
+**`mcast` stays opt-in either way.** Fixing both removes specific causes of silent failure,
+but neither overturns the asymmetry that chose the `dgram` default — and the sandbox lab is
+itself the cleanest evidence for that default, since `dgram` carried frames in the exact
+environment where `mcast` could not send at all.
+
+The precise form of the asymmetry, corrected: it is **not** that mcast failures are
+undetectable. An active probe at create or start time — one unconnected `sendto()` to a
+loopback group — catches the whole permission class cheaply, including the one that
+actually bit (#169). What a probe cannot catch is the *delivery* class: `SO_REUSEPORT`,
+a downstream firewall, a VPN capturing the group, or another host already on it. The
+durable difference is that a pair transport's misconfiguration is endpoint occupancy —
+persisted, visible, and refused before spawn — whereas every mcast failure mode needs
+an active measurement, and some are not reachable by one at all.
+
+Nor is `mcast` the simpler mechanism it first appears: it removes slots, roles and start
+order, but trades them for group and port allocation, which is where the
+three-links-one-port collapse above came from — and a group collision merges segments
+silently where a slot collision refuses.
+
+One correction on the record, since the earlier draft of this section got it backwards.
+The external lab's sandbox report was marked *unverified*, with the guess that it probably
+only restricted internet-bound UDP. Both halves were wrong: the block is real, it is at the
+syscall, and loopback multicast fails independently of egress. The lesson is the one this
+section already argues elsewhere — the answer came from running the commands on the actual
+host, not from reasoning about what a sandbox is likely to permit.
+
+### Background is not detachment, and `--bg` never claimed to be
+
+`spawnQemu()` backgrounds QEMU and calls `unref()`. That is enough for the parent to
+*exit* — QEMU is adopted by init/launchd and runs on — and it was read as detachment for
+as long as nobody sent a signal. It leaves QEMU in the caller's process group, so anything
+addressed to the group takes the VM with it: Ctrl-C in the terminal, a shell `timeout`, a
+CI step teardown, an agent harness killing a command it thinks is stuck. The external lab
+that hit this worked around it by wrapping every start in `nohup` (#159).
+
+Windows had the right spawn for the wrong-looking reason. A Job Object terminates
+everything inside it when the parent goes, and `Bun.spawn().unref()` does not escape one,
+so that branch already used `node:child_process` with `detached: true` — and carried a
+comment describing precisely the hazard the POSIX branch was exposed to. The two platforms
+fail differently (a Job Object on parent *exit*; a process group on a *signal*), which is
+why the asymmetry survived review: the Windows comment reads as Windows trivia rather than
+as the general rule. It is the general rule, and `detached: true` is now set on both.
+
+The *spawner* still differs, and deliberately. POSIX uses `Bun.spawn`, per the repo's
+Bun-first rule, with its `detached` verified here on Bun 1.4.2 rather than taken from the
+documentation — `test/unit/posix-detach.test.ts` is that verification. Windows keeps
+`node:child_process`, because its Job Object escape is load-bearing and can only be
+demonstrated on Windows. Bun documents `detached` as `UV_PROCESS_DETACHED` there, which
+would probably collapse the two branches into one; that is a change to make from a Windows
+reproduction, not from a doc claim. The first draft of this fix did unify them on
+`node:child_process`, which review correctly called out as reaching for Node where Bun has
+the API — the unification was the easy half, and the wrong half to keep.
+
+Detaching does not weaken cleanup, because nothing that sweeps QEMU sweeps by group —
+`scripts/ci-file-watchdog.ts` and the integration workflow both kill by process name. That
+is worth stating rather than assuming: "the child outlives its parent's signal" and "a
+wedged run leaks VMs" would otherwise look like the same change.
+
+The naming half is not fixed and should not be fixed quietly. `--bg` is already the
+default and only ever meant "serial console goes to a log file instead of stdio" — it does
+not make `start` return early, because `start` waits for REST readiness by contract. Both
+an external agent and the maintainer believed it bought them something. The honest repair
+is a separate `--no-wait` that opts out of the wait, not a redefinition of `--bg` that
+would change what existing scripts get; #159 holds that half.
+
 ### Out of Scope (decided)
 
 Explicitly rejected, with rationale, so they aren't re-proposed: