@tikoci/quickchr 0.4.7 → 0.5.0

package/MANUAL.md

@@ -41,6 +41,10 @@ by the user (or their AI agent) using `quickchr` as a building block.
 - ❌ Multi-router topology orchestration, test-matrix runners,
   configuration-as-code DSLs. Use `examples/` as references and compose
   yourself.
+- ⚠️ **RouterOS 6** is a best-effort, boot-only target (x86, CLI only): quickchr
+  downloads, boots and tracks a 6.x CHR, and does nothing else to it. It exists so
+  v6→v7 migration tooling has a disposable 6.x router to test against — it is not
+  RouterOS 6 support. See [RouterOS 6](#routeros-6-boot-only) below.
 
 **Two ways to use it:**
 
@@ -152,26 +156,39 @@ directory, downloads the RouterOS image (cached), and writes
 | `--no-api-ssl` | false | Exclude API-SSL port |
 | `--port-base <n>` | auto from 9100 | First port of the 10-port block |
 
-`--vmnet-shared` and `--vmnet-bridge <iface>` are deprecated aliases for
-`--add-network shared` / `--add-network bridged:<iface>`.
+`--vmnet-shared` and `--vmnet-bridge <iface>` have been removed. Use
+`--add-network shared` and `--add-network bridged:<iface>`; either old spelling is
+an error naming its replacement, not a silently ignored flag.
 
 #### `start [name]`
 
 Boot a stopped machine, or create-and-boot in one command. Blocks until
-REST is ready (background mode, default), or attaches QEMU stdio to your
-terminal (`--fg`). Accepts the same provisioning flags as `add`.
+RouterOS is ready (REST answers; on 6.x, a native-API login), or attaches QEMU
+stdio to your terminal (`--fg`). Accepts the same provisioning flags as `add`.
+QEMU runs detached in its own session either way, so it survives a signal to the
+shell that started it.
 
 Additional flags:
 
 | Flag | Notes |
 |---|---|
-| `--all` | Start every stopped machine in background |
-| `--bg` / `--background` | (default) detach QEMU; return after boot |
+| `--all` | Start every stopped machine in background; accepts readiness, acceleration, timeout and secure-login options only. Other options are refused rather than ignored |
+| `--no-wait` | Return as soon as QEMU is running (past the 1.5 s early-exit check), with state and ports persisted; do not wait for RouterOS. Refused with any provisioning flag, including first-boot options `add` recorded, and with `--fg` |
 | `--fg` / `--foreground` (alias `--no-bg`, `--no-background`) | Serial console on stdio |
+| `--bg` / `--background` | **Deprecated, does nothing.** Background is the default, and the flag never made `start` return early — it only ever chose where the serial console went. Prints a warning; use `--no-wait` |
 | `--install-deps` | Auto-install missing host deps (calls package manager) |
 | `--timeout-extra <s>` / `-T <s>` | Add extra seconds to computed boot timeout |
 | `--dry-run` | Print resolved options and QEMU command, exit |
 
+After `--no-wait`, readiness is yours. centrs (0.1.8+) waits for it in one command:
+
+```sh
+quickchr start lab --no-wait
+centrs retrieve --quickchr lab /system/resource --wait 5m
+# RouterOS 6: centrs validates against the 7.x command tree, so skip validation
+centrs retrieve --quickchr lab6 /system/resource --via native-api --no-validate --wait 5m
+```
+
 Foreground mode shortcuts (QEMU mux):
 
 | Key | Action |
@@ -187,9 +204,74 @@ machine state.
 
 #### `stop [name | --all]`
 
-Graceful shutdown via QEMU monitor. Updates `state.status = "stopped"`
-and unregisters socket-named networks. Listing-mode if no name and not
-`--all`.
+Power cut: sends SIGTERM to QEMU, waits up to 5 seconds, then SIGKILL if
+needed. This does not request a guest shutdown; pending RouterOS changes
+may be lost. Updates `state.status = "stopped"` and unregisters socket-named
+networks. Listing-mode if no name and not `--all`.
+
+Use `stop` for normal teardown and device-mode power-cycle confirmation.
+Use `shutdown` when the caller wants to request a guest shutdown first.
+
+#### `shutdown <name> [--timeout <seconds>]`
+
+Sends `/system/shutdown` once through REST, independently waits for QEMU to
+exit, then falls back to a power cut if it remains running. Default grace
+budget: **10 seconds**. `--timeout` takes positive integer seconds and
+overrides `QUICKCHR_SHUTDOWN_TIMEOUT`. Neither changes the boot timeout.
+The maximum is 2,147,483 seconds (the HTTP timer's limit).
+
+```bash
+quickchr shutdown lab
+quickchr shutdown lab --timeout 20
+QUICKCHR_SHUTDOWN_TIMEOUT=20 quickchr shutdown lab
+```
+
+The CLI reports `guest exited`, `already stopped`, or **forced power cut —
+guest shutdown not confirmed**. Forced fallback exits successfully if QEMU
+is confirmed gone; invalid input, lock failure, or inability to stop QEMU
+is an error. Disks, credentials and restart configuration survive.
+
+The guest request and exit observation share one grace budget. Lifecycle
+lock acquisition, the existing SIGTERM/SIGKILL escalation, and final exit
+verification have separate bounded waits. A 10-second grace budget does
+not bound the entire CLI invocation to 10 seconds.
+
+An HTTP error does not establish failure: on CHR 7.24.5, both x86/HVF and
+arm64/TCG returned HTTP 400 `interrupted`, then exited. Shutdown uses
+process exit as its completion signal. Observed exit does not guarantee
+application or storage durability. Unavailable REST (including RouterOS 6),
+failed authentication and a guest that does not halt all use the same
+explicit hard-stop fallback; no console/QGA/ACPI replay is attempted.
+
+```ts
+const result = await chr.shutdown({ timeoutMs: 20_000 });
+// outcome: "guest-exited" | "forced" | "already-stopped"
+// requestError can accompany guest-exited (e.g. HTTP 400 interrupted).
+console.log(result.outcome);
+```
+
+Library `timeoutMs` values are positive integer milliseconds, maximum
+2,147,483,647, with a 10,000 ms default. Library callers supply options
+explicitly; the CLI environment override is not read by `shutdown()`.
+
+For consumers of an older quickchr version, the manual workaround needs
+both request-error handling and independent exit observation:
+
+```ts
+const pid = chr.state.pid;
+if (pid) {
+  try { await chr.exec("/system/shutdown", { via: "rest", timeout: 10_000 }); }
+  catch { /* HTTP 400 interrupted may accompany successful guest shutdown. */ }
+  const exited = await chr.waitFor(async () => {
+    try { process.kill(pid, 0); return false; } catch { return true; }
+  }, 10_000);
+  if (!exited) console.warn("Guest shutdown not confirmed; forcing a power cut");
+}
+await chr.stop(); // reconcile state/network membership, or hard-stop if still alive
+```
+
+This older-version workaround has separate request and wait budgets;
+`shutdown()` provides one shared budget and structured fallback reporting.
 
 #### `remove [name | --all]` (alias `rm`)
 
@@ -206,10 +288,17 @@ flag. The next `start` therefore logs in as factory `admin` with an empty
 password. EFI vars are deliberately **kept** (they store boot order, not
 guest state; wiping them costs an arm64 device rescan).
 
-`clean` does not re-provision: the boot options in `machine.json`
-(`packages`, `deviceMode`, `secureLogin`) are re-applied only on a machine
-that has never started, so a cleaned machine comes back factory-fresh. Pass
-the provisioning flags again, or `remove` and re-create, to get them back.
+`clean` itself never provisions — it only resets the disk. What it does do is
+**reopen the provisioning window** (#176), so the *next* `start` re-applies the
+provisioning intent `machine.json` still holds: `packages`, `deviceMode`,
+`secureLogin`. Budget for that start accordingly; it costs what a first boot costs,
+not what a restart costs.
+
+What does **not** come back on its own is anything `clean` had to clear because it
+described the erased guest rather than an intent — `user`, `disableAdmin`,
+`licenseLevel` — and any option from a request that was *refused*, since a refused
+request is never persisted. Pass those flags again, which is why the refusal says to
+repeat the original command rather than to run a bare `start`.
 
 ### Inspection
 
@@ -219,11 +308,27 @@ Without a name: tabular summary of every machine. With a name: detailed
 view including credentials and connection tips. `--json` for
 machine-readable output.
 
+A machine whose `machine.json` cannot be read — unreadable on disk, not valid JSON, or
+valid JSON that is not usable machine state — still appears, as a row marked
+`unreadable` followed by `quickchr remove <name>`. A `saveMachine()` interrupted by a
+disk-full or a power loss is the usual cause. The listing exits 0: it succeeded, and the
+broken entry is named rather than silently dropped. In `--json` that entry is
+`{"name": …, "status": "unreadable", "error": …}` with no machine fields.
+
+Naming that machine in a command that has to *use* its state — `list <name>`, `stop`,
+`clean`, `env` — fails with `STATE_ERROR` naming the file, because a lookup you asked
+for by name is not an enumeration. `quickchr remove <name>` is the exception, and has to
+be: it is the command whose job is to clear that state, so it treats an unreadable
+machine as a directory to delete rather than state to load.
+
 #### `get <name> [license | device-mode | admin] [--json]`
 
 Live REST query. Hits the running CHR and returns the requested group
 (or all if no group specified). Requires the machine to be running.
 
+`device-mode` lists the mode plus every feature RouterOS reports, split into
+enabled and disabled — the read-back for `quickchr set <name> --device-mode…`.
+
 #### `inspect <name> [--json]`
 
 Stable, versioned (`descriptorVersion: 1`) connection descriptor for a
@@ -265,8 +370,9 @@ Tail the per-machine `qemu.log`. `--follow` streams new output;
 
 `networks` enumerates host interfaces and their alias resolution
 (`wifi`, `ethernet`, `auto`). `networks sockets` lists registered
-named L2 sockets; `networks sockets create <name>` reserves a port for a
-new tunnel.
+named L2 sockets and the transport each one uses; `networks sockets create <name>`
+registers a new link, taking `--mode` to pick that transport (the default needs no
+port at all).
 
 #### `version [--json]`
 
@@ -313,11 +419,43 @@ Apply or renew a CHR trial license on a running instance. Resolves
 MikroTik.com credentials from `--license-account`/`--license-password`,
 the env vars, or the secret store. Requires RouterOS ≥ 7.20.8.
 
-#### `set <name> <subcommand>`
+#### `set <name> [--license | --device-mode <m>] [--device-mode-enable <f>] [--device-mode-disable <f>]`
 
-Currently exposes a small surface for in-place changes (e.g.,
-`set <name> license …`). The `set/get` architecture is still being
-designed; expect additions.
+Change a property on a machine that has **already booted** — the post-boot half
+of the provisioning flags. `add`/`start` apply them at first boot; `set` applies
+them now. It is the route `PROVISIONING_WINDOW_CLOSED` names, printed with the
+flags that were asked for so it can be run as given.
+
+| flag | what it does |
+|---|---|
+| `--license` | Apply or renew a CHR trial license (§ `license` above for credential resolution). |
+| `--device-mode <m>` | `rose`, `advanced`, `basic`, `home`, `auto`. |
+| `--device-mode-enable <f,…>` | Set one or more device-mode flags to yes. Repeatable, comma-separated. |
+| `--device-mode-disable <f,…>` | Set one or more to no. |
+
+**Device-mode restarts the machine.** RouterOS only applies a device-mode change
+across a power cycle, and quickchr owns the power button — which is why this lives
+here rather than in a tool that reaches a router over the network: the same request
+issued from inside the guest never returns, because it is waiting for a power cycle
+it cannot perform on itself. quickchr prints every setting that will move before it
+restarts, and skips the restart entirely when the guest already matches.
+
+Naming a feature without a mode resolves the mode to `rose` — so
+`set lab --device-mode-enable container` moves `mode` as well. That move is printed
+before it happens, not discovered afterwards.
+
+Preconditions: the machine must be **running** and have a **user-mode NIC**
+(device-mode is applied over localhost REST), on RouterOS ≥ 7.20.8. Each is a
+named refusal rather than a timeout.
+
+The change is folded into `machine.json` rather than overwriting it — device-mode
+updates move only the settings they name, so the record stays cumulative — and
+recorded in `provisioning.steps`, which makes a later `start` passing the same
+device-mode a recognised no-op instead of a refusal.
+
+**Not available here:** `--add-user`, `--disable-admin`, `--secure-login`. Those
+rewrite working config rather than unlock a capability, and they are the steps that
+drift; their route stays `quickchr clean <name>` followed by the original command.
 
 #### `snapshot <name> <list | save [snapname] | load <snapname> | delete <snapname>>` (alias `snap`)
 
@@ -357,7 +495,7 @@ another machine, view status, or quit.
 | 9 | Extra blank disks (repeatable) | none | `--add-disk` |
 | 10 | Additional networks (macOS/Linux) | user-mode only | `--add-network` |
 | 11 | Provisioning (packages, device-mode, user, license) | optional | various |
-| 12 | Run mode: background / foreground | background | `--bg` / `--fg` |
+| 12 | Run mode: background / foreground | background | (default) / `--fg` |
 | 13 | Final confirmation | — | — |
 
 Steps 7–9 are skipped when `qemu-img` is absent (a warning is shown). Step 10
@@ -392,6 +530,43 @@ shell completions if not yet configured.
 
 Print or install shell completions. With no arg, detects current shell.
 
+#### `cache [add|key|list|prune|clear]`
+
+Manage downloaded CHR images. `cache add` resolves and downloads an image only;
+it does not check QEMU, create a machine, or boot RouterOS. A cache hit is an
+idempotent success.
+
+```bash
+quickchr cache add --channel stable --arch x86
+quickchr cache add --version 7.24.4 --arch arm64 --json
+quickchr cache key --channel stable --arch x86
+# dir=/Users/me/.local/share/quickchr/cache
+# version=7.24.4
+# arch=x86
+quickchr cache key --version 7.24.4 --arch x86 --json
+# {"dir":".../quickchr/cache","version":"7.24.4","arch":"x86"}
+```
+
+`--channel` and `--version` are mutually exclusive. When neither is supplied,
+`default-channel` applies; both subcommands use `default-arch`. A pinned
+version makes no network request in `cache key`. If channel resolution is
+offline, `cache key` prints the stable `unresolved` sentinel and exits 0 so a CI
+cache lookup cannot red the job; `cache add` fails because it cannot download an
+unknown image. Without `--json`, `cache key` emits `key=value` lines that can be
+appended directly to `$GITHUB_OUTPUT`.
+
+```yaml
+- id: chr-cache
+  run: quickchr cache key --channel stable --arch x86 >> "$GITHUB_OUTPUT"
+- uses: actions/cache/restore@v5
+  with:
+    path: ${{ steps.chr-cache.outputs.dir }}
+    key: chr-${{ runner.os }}-${{ steps.chr-cache.outputs.version }}
+```
+
+`--json` intentionally emits one JSON object for programmatic parsing; use the
+default output form when writing step outputs directly.
+
 #### `settings [print|get|set|reset] [key] [value] [--json]`
 
 Manage quickchr's own global preferences — repeated flags/defaults that
@@ -445,10 +620,11 @@ mutate any machine's `machine.json`.
 | `QUICKCHR_NO_PROMPT` | Force non-interactive mode (skips all wizards) |
 | `QUICKCHR_DEBUG` | Emit `[debug]` lines from the progress logger |
 | `QUICKCHR_INTEGRATION` | Required to run `test/integration/` |
-| `QUICKCHR_PRESERVE_ON_FAILURE` | `=1` keeps the machine directory after a boot timeout instead of removing it (QEMU is still stopped) |
+| `QUICKCHR_PRESERVE_ON_FAILURE` | `=1` skips removal/reset after a first-boot timeout or failed first-boot provisioning run (QEMU is still stopped). Previously booted machines always survive a restart timeout |
 | `QUICKCHR_SERIAL_LOG` | `=1` tees the guest serial console to `<machineDir>/serial.log`. **Secret-bearing** — serial provisioning types the generated password in cleartext |
 | `QUICKCHR_DEEP_BOOT_DIAGNOSTICS` | `=1` lets a boot-timeout capture write to the guest (a mangle counting rule + host probes) to localize a silent packet drop. Skipped when `QUICKCHR_PRESERVE_ON_FAILURE=1` |
 | `MIKROTIK_WEB_ACCOUNT`, `MIKROTIK_WEB_PASSWORD` | License credentials fallback |
+| `QUICKCHR_NO_TIPS` | `=1` suppresses the dim `tip:` lines quickchr prints on stderr |
 | `NO_COLOR` | Disable ANSI styling |
 
 `--json` is honored on `list`, `status`, `get`, `env`, `snapshot`, and a
@@ -456,6 +632,26 @@ few others; `inspect` is always JSON and accepts `--json` for parity. Check
 `quickchr help <command>`. Errors are caught at the top level and exit `1`
 with a `[code] message` line plus the install hint when present.
 
+**Help.** `--help` / `-h` on any subcommand prints that subcommand's help, exits `0`,
+and touches no state — including `quickchr add --help`, which is a machine-creating
+command. Anything after a bare `--` is your payload and is never scanned for flags:
+
+```bash
+quickchr exec my-chr -- ":put [/system/resource/get version]"
+```
+
+**Unknown flags.** `add` and `start` reject a flag they do not know rather than
+ignoring it, and suggest the closest match. The read-only commands still tolerate
+stray arguments.
+
+**Names.** Machine and named-socket names may contain letters, digits, `.`, `_`
+and `-`, must start with a letter or digit, and are capped at 64 characters. Both
+become a directory or file name under the data dir (§8).
+
+**Tips.** quickchr prints an occasional one-line `tip:` on **stderr** pointing at a
+better-suited command or tool. They never go to stdout, so piping `--json` output is
+unaffected. `QUICKCHR_NO_TIPS=1` turns them off.
+
 ---
 
 ## 4. Library API reference
@@ -471,15 +667,37 @@ QuickCHR.start(opts?: StartOptions): Promise<ChrInstance>
 QuickCHR.add(opts?: StartOptions): Promise<MachineState>
 QuickCHR.list(): MachineState[]
 QuickCHR.get(name: string): ChrInstance | null
+QuickCHR.listUnreadable(): Array<{ name: string; error: string }>
+QuickCHR.listOrphans(): string[]
+QuickCHR.removeOrphan(name: string): boolean
 QuickCHR.doctor(): Promise<DoctorResult>
 QuickCHR.resolveVersion(channel: Channel): Promise<string>
 ```
 
 `start()` creates the machine if needed, downloads the image, allocates
-a port block, spawns QEMU, waits for REST readiness, and runs all
-provisioning steps before returning. It auto-cleans the machine if boot
-times out (calls `stop()` then `remove()`). It acquires `start-lock` to
-serialize concurrent starts of the same machine.
+a port block, spawns QEMU, waits for readiness (REST on 7.x, a native-API
+`/login` on RouterOS 6), and runs all provisioning steps before returning.
+With `wait: false` (`--no-wait`) it returns once QEMU is running and leaves
+readiness to the caller; provisioning options are refused in that mode.
+On a boot timeout it stops QEMU, then removes a machine this call created,
+resets an existing never-booted machine to its factory disk, and preserves a
+previously booted one — see [Auto-cleanup on boot timeout](#auto-cleanup-on-boot-timeout).
+
+**Concurrency.** Machines may be created and started in parallel, from one
+`Promise.all` or from separate processes. Each creation chooses its port
+block and NIC MACs under a data-dir-wide allocation lock and reserves them
+until `machine.json` is written, so concurrent auto-allocated machines never
+share a block. An explicit `portBase` is never moved: one that overlaps
+another machine's block fails with `PORT_CONFLICT`. Per machine, every
+lifecycle operation takes the machine lock (`machines/<name>/.lock/`):
+
+- `stop()`, `clean()` and `remove()` **wait** for an operation already in
+  progress (up to the machine's boot timeout), then act on the state it left.
+- A second `start()` of the same machine, `setDeviceMode()` and removing a
+  leftover directory **fail at once** with `MACHINE_LOCKED`, naming the
+  operation, pid and age of the holder.
+- A machine running in the **foreground** holds the lock until its VM exits.
+  Nothing waits for it. Quit it from its console.
 
 `add()` is the same minus the QEMU spawn — useful when you want to
 materialize a machine and start it later (or hand the config to another
@@ -489,6 +707,31 @@ process).
 loads `machine.json`, refreshes PID liveness, and returns a runtime
 handle. `list()` is `get()` for everything in `machines/`.
 
+`listOrphans()` / `removeOrphan()` cover the gap between the two: a directory under
+`machines/` with no readable `machine.json`, left by a create that a crash or a
+SIGKILL interrupted. It still occupies the name, so `add()` refuses it, but no
+machine answers to it.
+
+How `get()` and `list()` behave depends on *why* the state is unreadable, and the
+two differ — a targeted lookup fails, an enumeration does not:
+
+| State | `get(name)` | `list()` |
+|---|---|---|
+| `machine.json` missing | `null` | omits it |
+| `machine.json` present but unreadable (read error, invalid JSON, or valid JSON that is not machine state) | **throws** `STATE_ERROR`, naming the file and `quickchr remove <name>` | skips it; `listUnreadable()` names it, and `quickchr list` shows it as a row |
+
+`listUnreadable()` returns `{ name, error }` for every machine in the second row — the
+file is present but cannot be turned into state, whether because the read failed, the
+JSON is invalid, or the parsed value is not a machine — so nothing is dropped without
+being reported somewhere. A
+directory with *no* `machine.json` is not in it; that is a create that never finished,
+and `listOrphans()` covers it.
+
+`listOrphans()` and `removeOrphan()` treat both the same — unreadable is unreadable —
+so `quickchr remove <name>` clears either. `removeOrphan()` returns `false` for a real
+machine (use `get(name)?.remove()` for those) and for a name that does not exist, and
+throws `INVALID_NAME` for a name that is not a usable path segment.
+
 ### `ChrInstance`
 
 **At a glance** — every method on a running instance:
@@ -496,8 +739,8 @@ handle. `list()` is `get()` for everything in `machines/`.
 | Group | Member | Purpose |
 |---|---|---|
 | Identity | `name`, `state`, `ports`, `restUrl`, `sshPort`, `portBase` | Static metadata persisted in `machine.json` |
-| Capture | `captureInterface`, `tzspGatewayIp` | Platform-correct values for TZSP capture (`tshark -i …`) and RouterOS streaming target |
-| Lifecycle | `waitForBoot()`, `waitFor(fn, ms?)`, `stop()`, `remove()`, `clean()`, `destroy()` | Boot readiness, custom polling, teardown |
+| Capture | `captureInterface`, `hostGatewayIp` | Platform-correct values for TZSP capture (`tshark -i …`) and the guest→host address any UDP emitter targets |
+| Lifecycle | `waitForBoot()`, `waitFor(fn, ms?)`, `stop()`, `shutdown(opts?)`, `remove()`, `clean()`, `destroy()` | Boot readiness, custom polling, power-cut or guest-shutdown teardown |
 | Comms | `rest()`, `exec()`, `monitor()`, `serial()`, `qga()` | REST, RouterOS CLI, QEMU monitor, serial console, QGA (x86 only) |
 | Provisioning | `license()`, `setDeviceMode()`, `availablePackages()`, `installPackage()` | Post-boot configuration |
 | Files | `upload()`, `download()` | SCP transfer to/from the CHR |
@@ -513,11 +756,12 @@ interface ChrInstance {
   sshPort: number;
   portBase: number;           // start of this instance's reserved port block
   captureInterface: string;   // "lo0" on macOS, "any" on Linux — for TZSP capture
-  tzspGatewayIp: string;      // "10.0.2.2" — QEMU slirp host gateway
+  hostGatewayIp: string;      // "10.0.2.2" — the host, as seen from inside the guest
 
   waitForBoot(timeoutMs?: number): Promise<boolean>;
   waitFor(condition: () => Promise<boolean>, timeoutMs?: number): Promise<boolean>;
-  stop(): Promise<void>;
+  stop(): Promise<void>;      // power cut: SIGTERM, then SIGKILL
+  shutdown(opts?: ShutdownOptions): Promise<ShutdownResult>; // /system/shutdown, bounded fallback
   remove(): Promise<void>;
   clean(): Promise<void>;
   destroy(): Promise<void>;   // stop + remove
@@ -585,7 +829,8 @@ redact before logging or attaching to bug reports.
 | `arch` | `"arm64" \| "x86"` | host | |
 | `cpu` | number | `1` | |
 | `mem` | number | `512` (1024 cross-arch TCG) | MiB |
-| `background` | boolean | `true` | |
+| `background` | boolean | `true` | Where the serial console goes — not whether `start()` waits |
+| `wait` | boolean | `true` | `false` resolves once QEMU is running and leaves readiness to the caller (`instance.waitForBoot()`); refused with provisioning or `background: false` (`INVALID_ARGUMENT`) |
 | `bootDiskFormat` | `"raw" \| "qcow2"` | `"raw"` (auto-`qcow2` if `bootSize`) | |
 | `bootSize` | string | — | e.g., `"512M"`, `"2G"`. Needs `qemu-img` |
 | `extraDisks` | string[] | `[]` | Each entry is a size string |
@@ -643,7 +888,7 @@ const chr = await QuickCHR.start({
 ```
 
 To **receive** UDP a guest sends, no forward is needed — bind an *unconnected*
-host socket and have the guest send to `chr.tzspGatewayIp` (`10.0.2.2`); see
+host socket and have the guest send to `chr.hostGatewayIp` (`10.0.2.2`); see
 [`docs/networking-recipes.md`](docs/networking-recipes.md) §2 and
 [`examples/udp-gateway/`](examples/udp-gateway/).
 
@@ -684,6 +929,24 @@ The entry also re-exports the lower-level version helpers for pre-flight checks:
 `isProvisioningSupportedVersion` (validate a version against the provisioning floor
 before calling `start()`).
 
+### Cache helpers
+
+`cacheKey()` and `cacheAdd()` are the library equivalents of the CLI cache
+subcommands:
+
+```ts
+import { cacheAdd, cacheKey, CACHE_VERSION_UNRESOLVED } from "@tikoci/quickchr";
+
+const { dir, version, arch } = await cacheKey({ channel: "stable", arch: "x86" });
+if (version !== CACHE_VERSION_UNRESOLVED) {
+  await cacheAdd({ version, arch });
+}
+```
+
+`cacheKey({ version })` validates the pin without resolving a channel.
+`cacheAdd()` returns `{ dir, version, arch, path, cacheHit }`; it only downloads
+and extracts the image and never creates or boots a machine.
+
 ---
 
 ## 5. Provisioning pipeline
@@ -723,10 +986,43 @@ port mappings work on any 7.x.
    Disabling admin **does not** lock the REST API — RouterOS's `expired`
    flag only gates CLI/SSH/Winbox login, not REST.
 
-Each step is independent. A failure in step N stops further steps but
-does not roll back N–1. Re-running `start` re-applies pending
-provisioning from `machine.json` only if the machine had not been fully
-provisioned previously.
+A failure in any step fails the whole first boot, and quickchr rolls it back
+rather than leave a half-provisioned guest: a machine `start` created in that
+call is removed (as a boot timeout removes it), and a machine created by `add`
+has its disk reset to the factory image and `machine.json` restored to what
+`add` recorded. Either way the retry is **the same command again**. With
+`QUICKCHR_PRESERVE_ON_FAILURE=1` the half-provisioned machine is kept, stopped,
+for inspection — `quickchr clean <name>` then resets it.
+
+On the first `start` of a machine created by `add`, a provisioning option you
+leave out keeps what `add` recorded, and an explicit negation
+(`--no-install-all-packages`, `--no-disable-admin`, `--no-secure-login`,
+`--no-device-mode`) overrides it.
+
+**The provisioning window closes at the machine's first boot** — not at
+`add`. A machine created with no provisioning options can still take them
+on its first `start`, which is where they are applied from `machine.json`.
+After that boot the guest may hold configuration quickchr did not put
+there, so provisioning cannot run against it: an option passed anyway is
+**refused**, never ignored, with `PROVISIONING_WINDOW_CLOSED` naming where
+the change can still be made. An option `machine.json` already records is
+reported as already applied rather than failing, so passing the same flags
+on every start is fine.
+
+Routes that still work after the window has closed:
+
+| change | route |
+|---|---|
+| license | `quickchr set <name> --license` |
+| device-mode | `quickchr set <name> --device-mode…` / `instance.setDeviceMode()` (power-cycles the VM) |
+| packages | `instance.installPackage()` (library; reboots the guest) |
+| anything else | `quickchr clean <name>` resets the disk to the factory image and reopens the window, at first-boot cost |
+
+`clean()` retains provisioning *intent* — packages, device-mode, managed login — so the
+next `start` re-applies those on its own. It clears `user`, `disableAdmin` and
+`licenseLevel`, which are facts about the erased guest rather than intent, and a refused
+request is never persisted. **Repeat the original command after the reset** rather than
+a bare `quickchr start <name>`, or those options are silently left out.
 
 **Always read back what we wrote.** This catches version-specific drift
 in REST responses and surfaces actionable errors instead of silent
@@ -810,7 +1106,7 @@ Picking among the specifiers/forwards by *goal* — full guide with recipes in
 |---|---|---|---|---|
 | `user` | SLiRP user-mode NAT, hostfwd port mapping | no | no | via hostfwd ports only |
 | `socket::<name>` | L2 socket pair between two VMs sharing the name | no | yes | no |
-| `socket-listen:<port>` / `socket-connect:<port>` / `socket-mcast:<group>:<port>` | low-level QEMU socket netdevs | no | yes | no |
+| `socket:listen:<port>` / `socket:connect:<port>` / `socket:mcast:<group>:<port>` | low-level QEMU socket netdevs | no | yes | no |
 | `shared` | NAT'd L3 with DHCP from the host | yes (or `socket_vmnet` rootless) | yes | yes |
 | `bridged:<iface>` | L2 bridged onto host iface | yes (or `socket_vmnet` rootless) | yes | yes |
 | `tap:<iface>` | pre-created TAP, no quickchr setup | depends | yes | yes |
@@ -821,15 +1117,64 @@ Resolution chains:
 - **`shared`** on macOS: socket_vmnet daemon → vmnet-shared (root-only QEMU). On Linux: pre-created TAP owned by the user, else root-created TAP+bridge.
 - **`bridged:<iface>`** on macOS: socket_vmnet bridged → vmnet-bridged (root). On Linux: TAP attached to a bridge containing the named iface.
 
+> The table lists the strings the **CLI** takes. The library's equivalents are the
+> `NetworkSpecifier` type names, which are spelled with a dash rather than a colon:
+> `socket:listen:5000` on the command line is `{ type: "socket-listen", port: 5000 }`
+> in TypeScript.
+
 ### Named L2 sockets
 
-`quickchr networks sockets create lab-sw1` reserves a port and stores
-metadata in `<dataDir>/networks/lab-sw1.json`. Two machines using
-`--add-network socket::lab-sw1` form an L2 tunnel: the first to start
-listens on the port; the second connects.
+`quickchr networks sockets create lab-sw1` registers a link in
+`<dataDir>/networks/lab-sw1.json`, and two machines using
+`--add-network socket::lab-sw1` join it. A link carries a **transport**, fixed when
+the name is created and printed by `start`, `networks sockets` and `create` itself —
+you never have to open a file under the data dir to find out what your link is.
+
+| `--mode` | Transport | Machines | Start order | Notes |
+|---|---|---|---|---|
+| `dgram` (default on macOS/Linux) | a pair of unix datagram sockets | 2 | either first | no host port, no UDP syscalls; needs QEMU 7.2+ |
+| `listen-connect` (default on Windows) | TCP pair on loopback | 2 | the listening end first | the first machine to *join* takes the listening end and keeps it; a connector never retries, so start that machine first |
+| `mcast` | UDP multicast on `230.0.0.1` | any number | any | the only N-way segment — **and the only one that fails silently** |
+
+`mcast` is worth the warning it prints at create time. Three separate hazards, all with
+the same signature — interfaces up, addresses assigned, 100% packet loss, nothing logged:
+
+- **It does not deliver on macOS.** QEMU's multicast socket omits `SO_REUSEPORT`, which
+  macOS/BSD require before two sockets on one group both receive.
+- **It is refused where unconnected UDP sends are blocked** — seccomp-filtered sandboxes
+  and some CI containers, including on Linux. The group still joins cleanly; only the
+  send is denied.
+- **It is not confined to your machine.** quickchr does not pass `localaddr=`, so the
+  group rides the host's default multicast interface rather than loopback. Another
+  machine on your LAN using the same group joins your segment.
+
+Use it when you genuinely need more than two machines on one segment, give it a group of
+its own, and check the link before you trust it. For two machines, `dgram` is both
+confined to the filesystem and able to refuse a bad configuration up front.
+
+The two-machine modes hold their ends in named slots, so a machine that stops and
+starts again comes back on the same end. That is what makes a restart safe, and it is
+also why `listen-connect` has a start order at all: the roles are fixed when the two
+machines first join, and from then on the listening end has to be running before the
+connecting one starts, because QEMU's `connect=` fails silently and never retries.
+`dgram` has no such constraint — either end may start first, every time. A third machine is refused, with a pointer
+to `--mode mcast`:
+
+```console
+$ quickchr start --name chr3 --add-network socket::lab-sw1
+Error [NETWORK_UNAVAILABLE]: Named socket "lab-sw1" is a dgram link and carries 2
+machines; chr1 and chr2 already hold both ends. Stop one of them, or create an N-way
+segment with 'quickchr networks sockets create <name> --mode mcast'.
+```
+
+quickchr unregisters socket members on `stop`/`remove`/`clean`, which frees the end
+for another machine. `networks sockets remove` refuses a link that still has members —
+removing it unlinks the endpoint sockets, which would kill a running link without
+saying so.
 
-quickchr unregisters socket members on `stop`/`remove`/`clean` so port
-allocation can recycle.
+Joining a link takes a registry lock, so `quickchr start a & quickchr start b &` is
+safe: without it both machines claim the same endpoint and are handed the same socket
+path.
 
 For platform internals (vmnet quirks, TAP creation, bridged-mode
 restrictions, half-open SLiRP under TCG), see `docs/networking.md`.
@@ -842,6 +1187,7 @@ restrictions, half-open SLiRP under TCG), see `docs/networking.md`.
 
 ```text
 $XDG_DATA_HOME/quickchr/  (defaults to ~/.local/share/quickchr/)
+├── .allocate.lock/              held while a new machine picks its ports/MACs
 ├── cache/                       Downloaded RouterOS images
 │   ├── chr-7.22.1.img.zip
 │   ├── chr-7.22.1.img
@@ -857,7 +1203,7 @@ $XDG_DATA_HOME/quickchr/  (defaults to ~/.local/share/quickchr/)
 │       ├── qga.sock             QGA (x86 only)
 │       ├── qemu.pid
 │       ├── qemu.log
-│       ├── start-lock           start serialization
+│       ├── .lock/               lifecycle lock + in-flight port/MAC reservation
 │       └── ssh/id_ed25519[.pub] SSH key (if managed user provisioned)
 └── networks/                     Named L2 socket reservations
     └── <name>.json
@@ -890,11 +1236,11 @@ is unset.
 ### Credentials (separate from data dir)
 
 - **Per-instance CHR credentials**: file in the user config dir
-  (`~/.config/quickchr/secrets.json` on POSIX; not the OS keychain — a
+  (`~/.config/quickchr/com.quickchr.instance.json`; not the OS keychain — a
   Keychain dialog hangs in non-TTY contexts like tests and CI).
 - **MikroTik.com web account** (for license operations): tries
   `Bun.secrets` (OS keychain) when interactive, falls back to the same
-  config-file store otherwise.
+  config-file store otherwise (`~/.config/quickchr/com.quickchr.mikrotik-web.json`).
 
 Both honor explicit CLI flags / env vars first.
 
@@ -926,8 +1272,10 @@ If an extra mapping reuses a built-in service name such as `winbox`, it
 pins/replaces that service's host port rather than creating a second
 `ports.winbox` entry.
 
-If port `9100` is in use, the next instance gets `9110`, etc. Manual
-override via `--port-base`.
+If port `9100` is in use, the next instance gets `9110`, etc. Concurrent
+creations get distinct blocks (see **Concurrency** under [Static methods on `QuickCHR`](#static-methods-on-quickchr)).
+Manual override via `--port-base`, which is never remapped: a base that
+overlaps another machine's block is a `PORT_CONFLICT`.
 
 ---
 
@@ -967,8 +1315,12 @@ Native (HVF/KVM): factor ~1 → 120s base.
 Cross-arch TCG: factor ~15 → up to 1800s.
 Package install adds a 2× multiplier (extra reboot cycle).
 
-If boot times out, the machine is **automatically stopped + removed**.
-Use `--timeout-extra` to add a buffer if you know your host is slow, or
+If boot times out, QEMU is stopped. A previously booted machine is **preserved**
+with its disks, credentials and configuration; retry with `quickchr start <name>`
+or explicitly remove it. A machine created by this `start()` is removed, and an
+existing never-booted machine is reset to its factory disk and pre-launch record.
+`QUICKCHR_PRESERVE_ON_FAILURE=1` skips removal/reset for those first-boot cases.
+See the [cleanup table](#auto-cleanup-on-boot-timeout) for all three cases. Use `--timeout-extra` to add a buffer if you know your host is slow, or
 persist a default via `quickchr settings set timeout-extra <seconds>` so
 every `start` picks it up without repeating the flag.
 
@@ -985,7 +1337,8 @@ against:
 - Accidental credential leakage in commits, CI logs, CLI output.
 
 We **don't** protect against same-user code reading
-`secrets.json`, `ps`-visible CLI args, or memory inspection.
+the `~/.config/quickchr/*.json` credential files, `ps`-visible CLI args, or memory
+inspection.
 
 ### Auth resolution (`resolveAuth`)
 
@@ -1027,13 +1380,14 @@ the 6 managed keys are all structural preferences, not secrets.
 | `QUICKCHR_NO_PROMPT` | CLI dispatcher — forces non-interactive mode |
 | `QUICKCHR_DEBUG` | progress logger — emits `[debug]` lines |
 | `QUICKCHR_INTEGRATION` | `bun:test` gate for `test/integration/` |
-| `QUICKCHR_PRESERVE_ON_FAILURE` | `quickchr.ts` — skip `remove()` on `BOOT_TIMEOUT` so the machine dir survives for diagnosis |
+| `QUICKCHR_PRESERVE_ON_FAILURE` | `quickchr.ts` — skip `remove()` on `BOOT_TIMEOUT`, and the rollback of a failed provisioning run, so the machine dir survives for diagnosis |
 | `QUICKCHR_SERIAL_LOG` | `qemu.ts` — adds `logfile=` to the serial chardev (writes cleartext provisioning passwords) |
 | `QUICKCHR_DEEP_BOOT_DIAGNOSTICS` | `guest-snapshot.ts` — allows the guest-mutating counting-rule probe during boot-failure capture |
 | `QUICKCHR_DEFAULT_CHANNEL` | `settings.ts` — env tier for the `default-channel` setting |
 | `QUICKCHR_DEFAULT_ARCH` | `settings.ts` — env tier for the `default-arch` setting |
 | `QUICKCHR_ACCEL` | `settings.ts` / `platform.ts` — env tier for the `accel` setting; forces `-accel` and bypasses detection |
 | `QUICKCHR_CACHE_MAX_SIZE` | `settings.ts` — env tier for the `cache-max-size` setting |
+| `QUICKCHR_SHUTDOWN_TIMEOUT` | CLI `shutdown` grace budget in positive integer seconds; default 10, overridden by `--timeout` |
 | `QUICKCHR_TIMEOUT_EXTRA` | `settings.ts` — env tier for the `timeout-extra` setting |
 | `QUICKCHR_SECURE_LOGIN` | `settings.ts` — env tier for the `secure-login` setting |
 | `MIKROTIK_WEB_ACCOUNT` | license-renewal account (fallback) |
@@ -1066,6 +1420,22 @@ derived Basic auth header. Do not commit or publicly log these values.
 `quickchr exec <name> <command>` and `chr.exec(command, opts)` both
 funnel through the same transport selector.
 
+> **`exec` does not validate your command.** It is a pipe: whatever you pass is what
+> RouterOS is asked to run, and a malformed command comes back as RouterOS's own
+> rejection. For anything beyond a one-liner, use
+> [centrs](https://github.com/tikoci/centrs), which checks a command against the
+> device's own command tree *before* running it and has per-path help:
+>
+> ```bash
+> centrs retrieve --quickchr my-chr /system/resource   # read state
+> centrs execute  --quickchr my-chr <command>          # read/write command
+> centrs explain  <command>                            # analyze without running
+> ```
+>
+> centrs resolves the machine's live connection facts through `quickchr inspect`
+> (see [`docs/centrs-interface.md`](./docs/centrs-interface.md)) — it never reads
+> `machine.json`, and neither should you.
+
 ### Transports
 
 | `--via` | Source | Notes |
@@ -1181,7 +1551,13 @@ stored instance credentials, `state.user`, the managed SSH keypair under
 `<machineDir>/ssh/`, and `disableAdmin` — because the accounts they named
 went with the disk. The machine comes back as a factory CHR: `admin` with
 an empty password, which is what `rest()`, `exec()`, and `inspect` resolve
-to afterwards. Nothing is re-provisioned automatically.
+to afterwards.
+
+`clean()` performs no provisioning of its own, but it does reopen the provisioning
+window: the next `start` re-applies the retained intent (`packages`, `deviceMode`,
+`secureLogin`) as a first boot would. The credential facts above are cleared rather
+than retained, so an explicit `--add-user` / `--disable-admin` — and anything from a
+request that was refused, which is never persisted — has to be passed again.
 
 ### Snapshots
 
@@ -1225,13 +1601,13 @@ present, then exits `1`.
 | `MISSING_FIRMWARE` | edk2 UEFI firmware not installed (arm64) | install `qemu-efi-aarch64` / `edk2-aarch64` |
 | `MISSING_UNZIP` | image extraction needs `unzip` | install OS package |
 | `PORT_CONFLICT` | no free 10-port block | stop a machine or set `--port-base` |
-| `BOOT_TIMEOUT` | CHR didn't respond within timeout | check `qemu.log`; under TCG, raise `--timeout-extra`; machine is **auto-removed** |
+| `BOOT_TIMEOUT` | CHR didn't respond within timeout | check `qemu.log`; under TCG, raise `--timeout-extra`; previously booted machines are **preserved**; new machines are removed, existing first boots reset, unless `QUICKCHR_PRESERVE_ON_FAILURE=1` |
 | `DOWNLOAD_FAILED` | image fetch failed | retry; check connectivity to MikroTik download server |
 | `INVALID_VERSION` / `INVALID_ARCH` / `INVALID_NAME` / `INVALID_DISK_SIZE` | argument parse | fix the value |
 | `MACHINE_EXISTS` | name already in `machines/` | choose another name or `QuickCHR.get(name)` |
 | `MACHINE_NOT_FOUND` | name not in `machines/` | `quickchr list` |
 | `MACHINE_RUNNING` / `MACHINE_STOPPED` | wrong lifecycle state | `start` or `stop` first |
-| `MACHINE_LOCKED` | another `start` in progress | wait or pick another name |
+| `MACHINE_LOCKED` | another operation holds the machine (the message names it, its pid and age) | wait for it; a `foreground` holder must be quit from its console |
 | `EXEC_FAILED` | RouterOS rejected the command (auth, syntax) | check creds, command syntax |
 | `PROCESS_FAILED` | QEMU spawn / reboot / verify failed | check `qemu.log`, host resources |
 | `SPAWN_FAILED` | exec/spawn of host binary failed | check binary exists + executable |
@@ -1239,7 +1615,9 @@ present, then exits `1`.
 | `QGA_TIMEOUT` | QGA daemon unreachable | KVM-only; not on macOS HVF or TCG |
 | `NETWORK_UNAVAILABLE` | provisioning needs `user` NIC, none present | add `--add-network user` |
 | `INVALID_NETWORK` | unknown alias / unresolvable iface / dead socket daemon | `quickchr networks` |
-| `PROVISIONING_VERSION_UNSUPPORTED` | provisioning option on RouterOS < 7.20.8 | use `--channel long-term` or pin a `7.20.8+` version |
+| `PROVISIONING_VERSION_UNSUPPORTED` | provisioning option on RouterOS < 7.20.8 (including any 6.x) | use `--channel long-term` or pin a `7.20.8+` version |
+| `REST_UNAVAILABLE` | REST operation (`exec`, `get`, `rest()`) on a RouterOS 6 machine | use the native API — `centrs … --via native-api --no-validate` |
+| `INVALID_ARGUMENT` | a flag combination quickchr will not honour — e.g. `--no-wait` with provisioning | drop one of the two |
 | `INSUFFICIENT_DISK_SPACE` | host data dir full | free space or move via `QUICKCHR_DATA_DIR` |
 | `STATE_ERROR` | snapshot on raw boot disk | recreate with `--boot-disk-format=qcow2` |
 | `INVALID_SIZE_STRING` | invalid cache/settings size string | use size syntax like `512M`, `2G`, or `1.5G` |
@@ -1248,10 +1626,44 @@ present, then exits `1`.
 
 ### Auto-cleanup on boot timeout
 
-If `start()` hits `BOOT_TIMEOUT`, quickchr automatically calls
-`stop()` then `remove()` on the failing instance. You'll see a
-diagnostic and the machine will be gone from `quickchr list`. This
-prevents orphan disks accumulating across attempts.
+If `start()` hits `BOOT_TIMEOUT`, quickchr stops the failing instance and then:
+
+| Machine at launch entry | Timeout cleanup | Recovery |
+| --- | --- | --- |
+| Created by this `start()` call | Remove automatically | Repeat the original command |
+| Existing, never booted, provisioning window open | Reset factory disk and restore the pre-launch record, window open | `quickchr start <name>` |
+| Existing, provisioning window already closed | Preserve disks, credentials and persistent configuration; clear PID and release socket memberships | `quickchr start <name>`, or explicit `quickchr remove <name>` |
+
+`QUICKCHR_PRESERVE_ON_FAILURE=1` skips removal/reset for the first two cases and
+keeps the machine as it failed. Previously booted machines survive without the
+flag, including older records whose only boot-history marker is `lastStartedAt`.
+The diagnostic report is written outside the machine directory before cleanup;
+QEMU logs in a preserved machine also remain available. A configured guest does
+not need `clean` to retry: that command deliberately erases its configuration.
+
+### RouterOS 6 (boot-only)
+
+A best-effort target for v6→v7 migration testing (tikoci/centrs#386), CLI only —
+the setup wizard does not offer it.
+
+```sh
+quickchr add --name lab6 --version 6.49.23 --arch x86
+quickchr start lab6
+centrs retrieve --quickchr lab6 /system/resource --via native-api --no-validate
+```
+
+- **x86 only.** MikroTik publishes no arm64 CHR for 6.x; `--arch arm64` is refused
+  before download (`INVALID_ARCH`).
+- **Readiness is a native-API `/login`** on guest port 8728 (two consecutive
+  answers), since 6.x has no REST. A 6.49.23 guest is ready in ~25 s under HVF.
+- **No provisioning.** Every provisioning flag, and the post-boot `set` routes, are
+  refused before download where possible (`PROVISIONING_VERSION_UNSUPPORTED`). The
+  `secure-login` setting is a default, not a request, so it does not apply to 6.x.
+- **No REST.** `exec` (REST/auto transport), `get`'s live groups and
+  `ChrInstance.rest()` fail with `REST_UNAVAILABLE` rather than time out.
+  `inspect` reports `rest-api` unavailable and `native-api` available.
+- `list`, `inspect`, `stop`, `remove` and `start --no-wait` work as for 7.x
+  (checked live on 6.49.23).
 
 ### Where to look