@tikoci/quickchr 0.4.8 → 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:**
 
@@ -159,20 +163,32 @@ 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 |
@@ -188,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`)
 
@@ -207,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
 
@@ -238,6 +326,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
@@ -328,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>]`
+
+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.
 
-Currently exposes a small surface for in-place changes (e.g.,
-`set <name> license …`). The `set/get` architecture is still being
-designed; expect additions.
+| 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 +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
@@ -497,7 +620,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 +675,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 +740,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 +757,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
@@ -687,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 |
@@ -843,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
@@ -1011,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
@@ -1026,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
@@ -1059,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.
 
@@ -1095,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`.
 
 ---
 
@@ -1136,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.
 
@@ -1154,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`)
 
@@ -1196,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) |
@@ -1366,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
 
@@ -1410,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 |
@@ -1424,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` |
@@ -1433,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
 

package/README.md

@@ -2,9 +2,9 @@
 
 > **Experimental** — quickchr is under active development. Most testing has been on
 > macOS (Apple Silicon + Intel), with CI on Linux (x86_64 + aarch64). Windows support
-> is early-stage: unit tests pass on `windows-latest` CI, but integration tests
-> (running a real CHR via QEMU for Windows) are not yet automated. Expect rough edges
-> on Windows — bug reports welcome.
+> is early-stage: unit tests pass on `windows-latest` CI, and a weekly sweep boots a real
+> CHR on Windows (TCG, anchor smoke subset only). Expect rough edges on Windows — bug
+> reports welcome.
 
 CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU.
 
@@ -158,6 +158,11 @@ quickchr remove my-chr
 quickchr doctor
 ```
 
+`quickchr stop <name>` terminates QEMU (a power cut). For an explicit guest
+shutdown request, use `quickchr shutdown <name> [--timeout <seconds>]` (default
+10 seconds, or `QUICKCHR_SHUTDOWN_TIMEOUT`). It waits for QEMU to exit and clearly
+reports a forced power cut if the guest does not stop within the grace budget.
+
 ### Create / Start Options
 
 | Flag | Description | Default |
@@ -172,8 +177,9 @@ quickchr doctor
 | `--boot-size <size>` | Resize boot disk (e.g., 512M, 2G). Requires `qemu-img`. | |
 | `--add-disk <size>` | Attach an extra blank qcow2 disk. Repeatable. Requires `qemu-img`. | |
 | `--forward <spec>` | Add or pin a QEMU SLiRP hostfwd mapping. Repeatable. | |
-| `--bg` / `--background` | Run in background (default) | true |
+| `--no-wait` | Return once QEMU is running; readiness is up to the caller. Not with provisioning flags or `--fg` | |
 | `--fg` / `--foreground` | Run in foreground — serial console on stdio | |
+| `--bg` / `--background` | **Deprecated, does nothing** — background is already the default. Warns; use `--no-wait` to return early | |
 | `--add-package <pkg>` | Extra package to install (repeatable) | |
 | `--install-all-packages` | Install all packages from `all_packages.zip` | |
 | `--add-user <user:pass>` | Create a user after boot | |
@@ -204,7 +210,7 @@ quickchr separates **boot-only** machine management from **post-boot provisionin
 
 | Feature | Minimum RouterOS | Notes |
 |---------|------------------|-------|
-| Boot / start / stop | Any RouterOS 7.x | Boot-only path; no post-boot RouterOS mutations |
+| Boot / start / stop | Any RouterOS 7.x; RouterOS 6 on x86 (best-effort) | Boot-only path; no post-boot RouterOS mutations. 6.x has no REST: readiness is a native-API login, and provisioning is refused — see MANUAL "RouterOS 6 (boot-only)" |
 | Disk resize / extra disks / disk inspection | Any RouterOS 7.x | Requires host `qemu-img`; QEMU-local only |
 | Network attachment / port mappings | Any RouterOS 7.x | QEMU networking setup; not provisioning |
 | Managed login / custom user / disable-admin | 7.20.8+ | Post-boot provisioning |
@@ -359,7 +365,8 @@ const result = await chr.exec("/system/resource/print");
 console.log(result);
 
 // Stop (or remove)
-await chr.stop();
+await chr.stop(); // power cut for normal teardown
+// Alternatively, replace stop() above with: await chr.shutdown({ timeoutMs: 10_000 });
 await chr.remove();
 
 console.log(chr.state.bootDiskFormat); // "qcow2"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/quickchr",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",

package/src/cli/flags.ts

@@ -24,13 +24,27 @@ const CREATE_FLAGS = [
 
 /** `start` also boots, so it owns the run-time flags on top of the create set. */
 const START_ONLY_FLAGS = [
-	"all", "dry-run", "background", "bg", "fg", "foreground",
+	"all", "dry-run", "wait", "background", "bg", "fg", "foreground",
 	"install-deps", "timeout-extra",
 	"license-level", "license-account", "license-password",
 ] as const;
 
+/** `set` applies a change to a machine that has already booted, so it takes the
+ *  post-boot subset of the provisioning flags plus `--license`'s credential flags.
+ *
+ *  It is listed here for the **valueless** check, not for strictness: `set` still
+ *  tolerates an unknown flag like every other non-creating command. The check that
+ *  matters is arity — `quickchr set lab --device-mode` with no value parses as a
+ *  boolean and would otherwise reach "Nothing to set", which blames the user for the
+ *  wrong thing. */
+const SET_ONLY_FLAGS = [
+	"name", "license", "level", "account", "password",
+	"device-mode", "device-mode-enable", "device-mode-disable",
+] as const;
+
 export const ADD_FLAGS: readonly string[] = CREATE_FLAGS;
 export const START_FLAGS: readonly string[] = [...CREATE_FLAGS, ...START_ONLY_FLAGS];
+export const SET_FLAGS: readonly string[] = SET_ONLY_FLAGS;
 
 /** Every flag that takes a value, across every command — `parseFlags`'s arity table.
  *