@tikoci/quickchr 0.4.8 → 0.5.1

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:**
 
@@ -68,31 +72,40 @@ by the user (or their AI agent) using `quickchr` as a building block.
 
 ### Install quickchr
 
-The first GitHub release is **0.1.1** — pre-release per the changelog's
-odd/even policy. Not yet on npm.
+Install the stable npm channel:
 
 ```bash
-# Library
-bun add github:tikoci/quickchr
+bun install -g @tikoci/quickchr
+bun add @tikoci/quickchr
+```
 
-# CLI from source (until npm publish)
-git clone https://github.com/tikoci/quickchr
-cd quickchr
-bun install
-bun run dev -- doctor
+For prerelease QA, use `@next` for the current candidate or, after publication,
+`@0.5.1` to pin this candidate. A release is published to `next` first and promoted
+to `latest` once QA passes; `next` is never older than `latest`. The quickchr package
+channel is independent of `--channel`, which selects a RouterOS firmware channel.
+
+```bash
+bun install -g @tikoci/quickchr@0.5.1
+bun add @tikoci/quickchr@0.5.1
+quickchr --version
 ```
 
-Once `0.2.0` is published to npm:
+To run an unpublished checkout:
 
 ```bash
-bun install -g @tikoci/quickchr
+git clone https://github.com/tikoci/quickchr
+cd quickchr
+bun install
+bun run dev -- doctor
 ```
 
 ### `quickchr doctor`
 
 Reports prerequisite status, accelerator availability, image cache
 size, machine count, free disk space, and shell-completion install
-state. Exit code is `0` when no checks return `error` (warnings are OK).
+state. The disk check measures the data dir's filesystem and warns when free
+space is under `storage-reserve` + 2 GiB. Exit code is `0` when no checks return
+`error` (warnings are OK).
 
 ```bash
 quickchr doctor              # human-readable
@@ -146,6 +159,7 @@ directory, downloads the RouterOS image (cached), and writes
 | `--device-mode <m>` | — | `rose`, `advanced`, `basic`, `home`, `auto`, `skip`, ≥ 7.20.8 |
 | `--device-mode-enable <f,...>` | — | Repeatable, comma-separated |
 | `--device-mode-disable <f,...>` | — | Repeatable, comma-separated |
+| `--no-device-mode` | — | Skip device-mode provisioning entirely |
 | `--add-network <spec>` | `user` | See §7. Repeatable. |
 | `--no-network` | false | Headless, no NICs |
 | `--no-winbox` | false | Exclude WinBox port |
@@ -159,20 +173,36 @@ 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.
+
+When `<name>` matches no machine (a typo, or one removed earlier), `start` creates a
+factory CHR under that name and says so: `<name> created and started`, or
+`created — not waiting for RouterOS` with `--no-wait`. A machine that already
+existed, including one made by `add`, prints `started`.
 
 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. `--secure-login` is resolved per machine: one that has never booted creates the managed login; one that already booted accepts it as a no-op only if it already has one, and is refused otherwise. With `--no-wait`, a never-booted machine refuses it (provisioning needs the wait). Machines start one at a time, so a refusal stops the batch after the earlier machines have started |
+| `--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 |
-| `--install-deps` | Auto-install missing host deps (calls package manager) |
+| `--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` |
 | `--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 |
@@ -188,9 +218,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`)
 
@@ -207,10 +302,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
 
@@ -238,6 +340,9 @@ machine as a directory to delete rather than state to load.
 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
@@ -303,7 +408,8 @@ the Library API reference.
 #### `exec <name> <command> [--via=auto|rest|qga|console|ssh] [--user u] [--password p] [--timeout=ms]`
 
 Run a RouterOS CLI command. See §12 for transport details and JSON
-output trick.
+output trick. Exit 0 means the command was delivered, not that RouterOS
+accepted it — see §12 "Exit status" for the pass/fail route.
 
 #### `console <name>`
 
@@ -328,11 +434,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`)
 
@@ -372,7 +510,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
@@ -444,6 +582,64 @@ appended directly to `$GITHUB_OUTPUT`.
 `--json` intentionally emits one JSON object for programmatic parsing; use the
 default output form when writing step outputs directly.
 
+`cache list [--json]` shows each cache entry with its version, arch, size, age
+(time since it was cached or last used) and whether it is in use. Entries are:
+
+- **images** (`chr-<ver>[-arm64].img`, and a `.img.zip` not yet extracted). An
+  image is **in use** while any machine, running or stopped, was created from
+  that version and arch: `clean` and a failed first boot rebuild from it.
+- **package archives** (`packages-<arch>-<ver>`): the `all_packages` ZIP and its
+  extraction, sized and deleted together, since the extraction is only a cache
+  hit while its ZIP is there. In use while a machine that asks for packages has
+  not finished its first boot.
+- **partial** entries: an interrupted download (`*.<pid>-<id>.part`) or
+  extraction (`.quickchr-image-*`, `.quickchr-packages-*`). In use while the
+  process that wrote it is alive (an extraction: for 30 minutes after its last
+  write). `prune` removes stale ones before anything else.
+
+`cache list --json` prints one object per entry, including `kind` (`image`, `image-zip`,
+`packages` or `partial`) and `paths` (every file deleting the entry removes).
+Files in the cache that quickchr did not write are reported as "Other files"
+and never deleted. `prune` and `clear` never delete an in-use entry.
+
+```bash
+quickchr cache list
+quickchr cache prune --older-than 7.22 --dry-run   # versions below 7.22
+quickchr cache prune --max-age 30d                 # not used for more than 30 days
+quickchr cache prune --max-size 2G                 # oldest versions first, until <= 2 GiB
+quickchr cache clear --all                         # every entry not in use
+```
+
+`prune` needs at least one of `--older-than <ver>`, `--max-age <dur>` or
+`--max-size <size>`, and applies them in that order when combined. `--max-size`
+evicts the oldest RouterOS version first (oldest cache time breaks ties) until
+the total, in-use entries included, fits. Durations are `<N>(s|m|h|d|w)`; sizes
+are `<N>(K|M|G|T)` with an optional `i`/`B`, read as IEC binary. `--dry-run`
+lists what `prune` or `clear` would delete without deleting it. `clear` refuses
+without `--all`. A delete that fails is listed on stderr, is not counted as
+freed, and makes the command exit 1. A cache hit counts as a use, so `--max-age`
+measures time since an entry was last used.
+
+Separately, a successful `start` prunes to the `cache-max-size` setting (default
+`2G`; see `settings` below). That automatic prune, and the one below, skip any
+entry used in the last 30 minutes, which another create may be reading.
+
+**Disk space.** Creating a machine (`add`, or `start` with a new name) and
+filling the cache (an image or package download) are admitted when each
+filesystem the operation writes to has room for what it writes there plus the
+`storage-reserve` setting (default `2G`), less what other quickchr operations
+in progress have already claimed. The estimate is the boot disk
+(192 MiB), plus an image download (256 MiB) and a package download (192 MiB)
+when those are not cached yet, so a cold create needs about 2.6 GiB free and a
+warm one about 2.2 GiB. When there is not enough, quickchr first evicts what the
+cache can spare on that filesystem (oldest version first; never entries a
+machine or an operation in progress needs, nor recently used ones), measures
+again until there is room or nothing more can go, and only then refuses with `INSUFFICIENT_DISK_SPACE`,
+naming the free space, what it needed, what it evicted and what it kept.
+Restarting an existing machine, `stop`, `remove` and read-only commands are
+never gated. The estimate covers creation, not a guest that later fills its
+disk: extra disks and `--boot-size` are sparse and grow as the guest writes.
+
 #### `settings [print|get|set|reset] [key] [value] [--json]`
 
 Manage quickchr's own global preferences — repeated flags/defaults that
@@ -460,6 +656,7 @@ Precedence per key (highest wins): CLI flag > `QUICKCHR_<KEY>` env var >
 | `default-arch` | `add`/`start`'s `--arch`, wizard's arch prompt | `arm64`\|`x86`\|`auto` | `auto` (host native) |
 | `accel` | `add`/`start`'s `--accel`; every `detectAccel()` call in the run | `auto`\|`tcg`\|`hvf`\|`kvm` | `auto` (detect) |
 | `cache-max-size` | Auto-prune cap applied after each successful `start` | size string (e.g. `2G`, `512M`) | `2G` |
+| `storage-reserve` | Free space creating a machine or filling the cache must leave, beyond what it writes | size string | `2G` |
 | `timeout-extra` | `start`'s `--timeout-extra`/`-T` when omitted | non-negative integer seconds | `0` |
 | `secure-login` | `add`/`start`'s `--secure-login` when neither `--secure-login` nor `--no-secure-login` is passed | boolean | `unset` (reported as `(unset)` — see note) |
 
@@ -478,7 +675,7 @@ the wizard's own recommended "managed login" highlighted). Giving it a real
 the setting resolves to exactly `true`.
 
 ```bash
-quickchr settings print                       # all 6 keys, resolved value + source
+quickchr settings print                       # all 7 keys, resolved value + source
 quickchr settings set default-channel testing # write one key to quickchr.env
 quickchr settings get default-arch            # print one key's resolved value
 quickchr settings reset default-channel       # delete one managed line
@@ -486,7 +683,7 @@ quickchr settings reset                       # clear all managed lines
 ```
 
 Credentials (`--add-user`, `MIKROTIK_WEB_ACCOUNT`/`MIKROTIK_WEB_PASSWORD`) are
-never stored here — `settings` only manages the 6 keys above, and does not
+never stored here — `settings` only manages the 7 keys above, and does not
 mutate any machine's `machine.json`.
 
 ### Global behavior
@@ -497,7 +694,7 @@ 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 |
@@ -552,10 +749,29 @@ 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
@@ -598,7 +814,7 @@ throws `INVALID_NAME` for a name that is not a usable path segment.
 |---|---|---|
 | Identity | `name`, `state`, `ports`, `restUrl`, `sshPort`, `portBase` | Static metadata persisted in `machine.json` |
 | 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()`, `remove()`, `clean()`, `destroy()` | Boot readiness, custom polling, teardown |
+| 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 |
@@ -615,11 +831,11 @@ interface ChrInstance {
   portBase: number;           // start of this instance's reserved port block
   captureInterface: string;   // "lo0" on macOS, "any" on Linux — for TZSP capture
   hostGatewayIp: string;      // "10.0.2.2" — the host, as seen from inside the guest
-  tzspGatewayIp: string;      // deprecated alias for hostGatewayIp (#26)
 
   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
@@ -682,13 +898,14 @@ redact before logging or attaching to bug reports.
 | Field | Type | Default | Notes |
 |---|---|---|---|
 | `name` | string | auto | Must not start with `-` |
-| `version` | string | — | Mutually exclusive with `channel` |
+| `version` | string | — | Wins over `channel`: passing both warns and uses `version` |
 | `channel` | Channel | `"stable"` | |
 | `arch` | `"arm64" \| "x86"` | host | |
 | `cpu` | number | `1` | |
 | `mem` | number | `512` (1024 cross-arch TCG) | MiB |
-| `background` | boolean | `true` | |
-| `bootDiskFormat` | `"raw" \| "qcow2"` | `"raw"` (auto-`qcow2` if `bootSize`) | |
+| `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`) | The CLI always passes a format, defaulting to `qcow2`; the `"raw"` default applies to library callers only |
 | `bootSize` | string | — | e.g., `"512M"`, `"2G"`. Needs `qemu-img` |
 | `extraDisks` | string[] | `[]` | Each entry is a size string |
 | `networks` | NetworkSpecifier[] | `["user"]` | See §7 |
@@ -702,7 +919,7 @@ redact before logging or attaching to bug reports.
 | `secureLogin` | boolean | `false` | **`true` is the explicit trigger** for managed-account creation |
 | `license` | `LicenseInput` | — | `"p1"` / `"p10"` / `"unlimited"` or `LicenseOptions` |
 | `deviceMode` | `DeviceModeOptions` | — | `{mode?, enable?[], disable?[]}` |
-| `installDeps` | boolean | — | Auto-install missing OS deps |
+| `installDeps` | boolean | — | **Deprecated, ignored.** Never installed anything; run `quickchr doctor` for install hints |
 | `dryRun` | boolean | `false` | Print QEMU command and exit |
 | `timeoutExtra` | number | `0` | Extra **milliseconds** added to boot timeout |
 | `onProgress` | `(msg) => void` | `console.log` | `[debug]` lines only when `QUICKCHR_DEBUG=1` |
@@ -843,10 +1060,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
@@ -1011,6 +1261,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
@@ -1018,15 +1269,15 @@ $XDG_DATA_HOME/quickchr/  (defaults to ~/.local/share/quickchr/)
 ├── machines/
 │   └── <name>/
 │       ├── machine.json         Persisted MachineState
-│       ├── disk.img | disk.qcow2
-│       ├── extra-disk-*.qcow2
+│       ├── boot.qcow2 | disk.img  boot disk: qcow2 (CLI default) or raw — one, not both
+│       ├── disk<N>.qcow2        extra disks
 │       ├── efi-vars.fd          arm64 only (UEFI vars)
 │       ├── monitor.sock         QEMU monitor
 │       ├── serial.sock          serial console
 │       ├── 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
@@ -1047,7 +1298,7 @@ var list.
 ├── cache\
 ├── machines\<name>\
 │   ├── machine.json
-│   ├── disk.img
+│   ├── boot.qcow2 | disk.img
 │   ├── monitor (named pipe handle, no on-disk file)
 │   └── …
 └── …
@@ -1059,11 +1310,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.
 
@@ -1095,8 +1346,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`.
 
 ---
 
@@ -1136,8 +1389,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.
 
@@ -1154,7 +1411,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`)
 
@@ -1186,7 +1444,7 @@ managed via `quickchr settings get|set|print|reset` (§3, Meta). Atomic writes
 preserve every other line (comments, blank lines, foreign vars) byte-for-byte.
 `reset <key>` deletes the line entirely rather than blanking it, since a blank
 `KEY=` line is still "set" to a bash-sourced file. Never stores credentials —
-the 6 managed keys are all structural preferences, not secrets.
+the 7 managed keys are all structural preferences, not secrets.
 
 ### Environment variables consumed
 
@@ -1196,13 +1454,15 @@ 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_STORAGE_RESERVE` | `settings.ts` — env tier for the `storage-reserve` 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) |
@@ -1251,6 +1511,29 @@ funnel through the same transport selector.
 > (see [`docs/centrs-interface.md`](./docs/centrs-interface.md)) — it never reads
 > `machine.json`, and neither should you.
 
+### Exit status
+
+`quickchr exec` exits 0 when the command was **delivered**, not when RouterOS
+accepted it. `/rest/execute` returns HTTP 200 with the rejection text in the same
+envelope as a success, so a refused command looks like this:
+
+```console
+$ quickchr exec my-chr "/user/add name=-2 group=read password=x"; echo "rc=$?"
+failure: invalid user name (/user/add; line 1)
+rc=0
+```
+
+The library is the same: `chr.exec()` resolves, and `ExecResult` has no failure
+field. quickchr does not pattern-match RouterOS error text, whose wording changes
+between versions (#142). When a script needs a pass/fail exit code, run the
+command through centrs, which validates it first and exits non-zero on a rejection.
+A write command needs `--yes` outside a TTY; without it centrs refuses with
+`usage/confirmation-required` (also exit 1) and sends nothing:
+
+```bash
+centrs execute --quickchr my-chr --yes "/user/add name=-2 group=read password=x"
+```
+
 ### Transports
 
 | `--via` | Source | Notes |
@@ -1366,7 +1649,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
 
@@ -1410,13 +1699,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_NOT_FOUND` | name not in `machines/`, or a booted machine's disk file is missing | `quickchr list`; for a missing disk, restore it or `quickchr clean <name>` |
 | `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 |
@@ -1424,8 +1713,10 @@ 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 |
-| `INSUFFICIENT_DISK_SPACE` | host data dir full | free space or move via `QUICKCHR_DATA_DIR` |
+| `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` | data dir's filesystem has less than the operation's estimate plus `storage-reserve`, even after evicting what the cache could spare | free space, remove machines, lower `storage-reserve`, 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` |
 | `INVALID_SETTING_KEY` | `settings get`/`set`/`reset` received an unrecognized key | `quickchr settings print` to see the managed keys |
@@ -1433,10 +1724,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