@tikoci/quickchr 0.4.7 → 0.5.0

package/src/lib/state.ts

@@ -2,11 +2,12 @@
  * Machine state persistence — JSON files in ~/.local/share/quickchr/machines/.
  */
 
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync, statSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, rmSync, statSync } from "node:fs";
 import { join, } from "node:path";
 import type { MachineState, } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
 import { networkModeToConfigs } from "./network.ts";
+import { assertPathSafeName, isPathSafeName } from "./names.ts";
 
 /** Get the quickchr data directory root. Override with QUICKCHR_DATA_DIR env var. */
 export function getDataDir(): string {
@@ -91,12 +92,72 @@ export function saveMachine(state: MachineState): void {
 	writeFileSync(machineJsonPath(state.name), JSON.stringify(state, null, "\t") + "\n");
 }
 
-/** Load machine state from disk. Returns undefined if not found. */
+/** The fields every caller dereferences without guarding, with the `typeof` each must
+ *  answer. Deliberately not a schema: it is the set that turns a bad file into a crash
+ *  somewhere else, which is the thing being prevented. `cpu`/`mem` are absent because a
+ *  missing one prints oddly rather than throwing, and a narrow check cannot wrongly
+ *  condemn a machine that works today. `networks` is absent because `loadMachine()`
+ *  migrates it just below.
+ *
+ *  Every field listed here has been required on `MachineState` since the commit that
+ *  introduced it (5cfe052), so no `machine.json` any version of quickchr wrote can be
+ *  condemned by this check — which is the thing that would make it worse than the bug
+ *  it fixes. */
+const REQUIRED_STATE_FIELDS: ReadonlyArray<[keyof MachineState, "string" | "number" | "object"]> = [
+	["name", "string"],
+	["version", "string"],
+	["arch", "string"],
+	["status", "string"],
+	["machineDir", "string"],
+	["portBase", "number"],
+	["ports", "object"],
+	["packages", "object"],
+];
+
+/** Why `parsed` is not usable as a `MachineState`, or `undefined` when it is.
+ *
+ *  Parsing successfully is not the same as being state. `{"name":"lab"}` parses, and
+ *  `JSON.parse` is happy with `null` and `[]` too; casting any of them to `MachineState`
+ *  only moves the failure — `{"name":"lab"}` reached `formatPorts(m.ports)` and aborted
+ *  `quickchr list` exactly as an unparseable file used to (#165). */
+function stateShapeProblem(parsed: unknown): string | undefined {
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return "not a JSON object";
+	}
+	const record = parsed as Record<string, unknown>;
+	const bad = REQUIRED_STATE_FIELDS
+		.filter(([key, kind]) => typeof record[key] !== kind || record[key] === null)
+		.map(([key]) => key);
+	return bad.length > 0 ? `missing or invalid: ${bad.join(", ")}` : undefined;
+}
+
+/** Load machine state from disk. Returns undefined if not found.
+ *
+ *  Throws `STATE_ERROR` when the file is there but unusable. A targeted lookup by name
+ *  has to fail: the caller named *this* machine, and answering `undefined` would report
+ *  a machine that exists on disk as one that never did. `loadAllMachines()` is the
+ *  enumeration and takes the other policy — see `tryLoadMachine()` (#165). */
 export function loadMachine(name: string): MachineState | undefined {
 	const path = machineJsonPath(name);
 	if (!existsSync(path)) return undefined;
-	const data = readFileSync(path, "utf-8");
-	const state = JSON.parse(data) as MachineState;
+	let state: MachineState;
+	try {
+		state = JSON.parse(readFileSync(path, "utf-8")) as MachineState;
+	} catch (e) {
+		throw new QuickCHRError(
+			"STATE_ERROR",
+			`Machine "${name}" has an unreadable machine.json (${e instanceof Error ? e.message : String(e)})`,
+			`Inspect ${path}, or clear the machine with 'quickchr remove ${name}'`,
+		);
+	}
+	const shapeProblem = stateShapeProblem(state);
+	if (shapeProblem) {
+		throw new QuickCHRError(
+			"STATE_ERROR",
+			`Machine "${name}" has an unreadable machine.json (${shapeProblem})`,
+			`Inspect ${path}, or clear the machine with 'quickchr remove ${name}'`,
+		);
+	}
 	// Migrate legacy `network` field → `networks` array
 	if (!state.networks && (state as unknown as Record<string, unknown>).network) {
 		const legacy = (state as unknown as Record<string, unknown>).network as MachineState["networks"][0]["specifier"] | "user" | "vmnet-shared" | { type: "vmnet-bridge"; iface: string };
@@ -107,7 +168,33 @@ export function loadMachine(name: string): MachineState | undefined {
 	return state;
 }
 
-/** Load all machine states. */
+/** The three things a machine directory can turn out to be.
+ *
+ *  `loadMachine()` collapses `missing` and `unreadable` into "undefined or throw", which
+ *  is the right contract for a lookup and the wrong one for an enumeration. This keeps
+ *  them apart so each caller can pick (#165). Internal for now: promoting it to public
+ *  API is a rename if #58 lands. */
+type MachineLoad =
+	| { status: "ok"; state: MachineState }
+	| { status: "missing" }
+	| { status: "unreadable"; error: string };
+
+/** `loadMachine()` without the throw. */
+function tryLoadMachine(name: string): MachineLoad {
+	try {
+		const state = loadMachine(name);
+		return state ? { status: "ok", state } : { status: "missing" };
+	} catch (e) {
+		return { status: "unreadable", error: e instanceof Error ? e.message : String(e) };
+	}
+}
+
+/** Load all machine states, skipping directories with no usable `machine.json`.
+ *
+ *  An enumeration is best-effort across many: one corrupt file used to abort the whole
+ *  listing, which loses the state of every healthy machine as well. Nothing is hidden by
+ *  the skip — `listUnreadableMachines()` names what was left out, and `quickchr list`
+ *  shows it as a row (#165). */
 export function loadAllMachines(): MachineState[] {
 	const dir = getMachinesDir();
 	if (!existsSync(dir)) return [];
@@ -117,13 +204,27 @@ export function loadAllMachines(): MachineState[] {
 
 	for (const entry of entries) {
 		if (!entry.isDirectory()) continue;
-		const state = loadMachine(entry.name);
-		if (state) machines.push(state);
+		const loaded = tryLoadMachine(entry.name);
+		if (loaded.status === "ok") machines.push(loaded.state);
 	}
 
 	return machines;
 }
 
+/** Every machine directory whose `machine.json` exists but cannot be read.
+ *
+ *  Distinct from `listOrphanMachineDirs()`, which also counts a directory with no
+ *  `machine.json` at all — a create that never finished. This one is a machine that did
+ *  exist and whose state went bad, so it still holds a disk image worth naming. */
+export function listUnreadableMachines(): Array<{ name: string; error: string }> {
+	const out: Array<{ name: string; error: string }> = [];
+	for (const name of listMachineNames()) {
+		const loaded = tryLoadMachine(name);
+		if (loaded.status === "unreadable") out.push({ name, error: loaded.error });
+	}
+	return out;
+}
+
 /** Get all existing machine names. */
 export function listMachineNames(): string[] {
 	const dir = getMachinesDir();
@@ -133,20 +234,122 @@ export function listMachineNames(): string[] {
 		.map((e) => e.name);
 }
 
+/** True when `name` has a machine directory but no readable `machine.json` — a create
+ *  that did not finish. `list` cannot show it and `start` cannot boot it, but
+ *  `listMachineNames()` (directory-based) still counts it, so it blocks re-add (#155). */
+export function isOrphanMachineDir(name: string): boolean {
+	// A traversal name resolves to a directory that exists and holds no machine.json —
+	// the data dir itself, for ".." — so the path check has to come first or the
+	// predicate answers "orphan" about something that is not a machine directory.
+	if (!isPathSafeName(name)) return false;
+	const dir = getMachineDir(name);
+	if (!existsSync(dir)) return false;
+	return !isReadableMachine(name);
+}
+
+/** Every machine directory with no readable `machine.json`. */
+export function listOrphanMachineDirs(): string[] {
+	return listMachineNames().filter((name) => !isReadableMachine(name));
+}
+
+/** A truncated or corrupt `machine.json` is as unusable as a missing one, and both make
+ *  the directory an orphan. */
+function isReadableMachine(name: string): boolean {
+	return tryLoadMachine(name).status === "ok";
+}
+
 /** Get all port bases currently in use by existing machines. */
 export function getUsedPortBases(): number[] {
 	return loadAllMachines().map((m) => m.portBase);
 }
 
+/** Every NIC MAC currently assigned across all machines.
+ *  Passed to `assignMacs()` so a new machine cannot be handed an address another
+ *  machine already presents on a shared L2 segment (#154). */
+export function getUsedMacs(): Set<string> {
+	const macs = new Set<string>();
+	for (const m of loadAllMachines()) {
+		for (const n of m.networks ?? []) {
+			if (n.mac) macs.add(n.mac);
+		}
+	}
+	return macs;
+}
+
 /** Delete a machine and all its files. */
 export function removeMachine(name: string): void {
+	// This is an `rmSync(..., { recursive: true })`; the name must never be able to
+	// point outside machines/<name>/.
+	assertPathSafeName(name, "machine");
 	const dir = getMachineDir(name);
 	if (!existsSync(dir)) {
 		throw new QuickCHRError("MACHINE_NOT_FOUND", `Machine "${name}" not found`);
 	}
-	rmSync(dir, { recursive: true, force: true });
+	// Out of `machines/` in one step, then deleted. A recursive delete in place removes
+	// entries one by one, so there is a window where the machine lock (`.lock/`, inside
+	// the directory) is gone while the directory is not, and a waiter or a same-named
+	// create could take a fresh lock in a directory that is being deleted. After the
+	// rename the name is simply free.
+	//
+	// There is no in-place fallback, because it would reopen exactly that window. A
+	// rename can fail briefly while a scanner or indexer holds a handle (Windows refuses
+	// to rename a directory with one open), so it is retried. If it still fails, the
+	// directory is left alone and the failure is reported.
+	const trashDir = join(getDataDir(), ".removing");
+	const trash = join(trashDir, `${name}.${process.pid}.${crypto.randomUUID()}`);
+	ensureDir(trashDir);
+	sweepAbandonedRemovals(trashDir);
+	for (let attempt = 1; ; attempt++) {
+		try {
+			renameSync(dir, trash);
+			break;
+		} catch (e) {
+			if (attempt >= REMOVE_RENAME_ATTEMPTS) {
+				throw new QuickCHRError(
+					"STATE_ERROR",
+					`Could not remove machine "${name}": moving ${dir} aside failed (${(e as Error).message}). ` +
+					`The directory was left in place — close anything using it and run 'quickchr remove ${name}' again.`,
+				);
+			}
+			Bun.sleepSync(REMOVE_RENAME_RETRY_MS);
+		}
+	}
+	// The name is already free, so a failed delete does not fail the removal. The
+	// files stay under `.removing/` and the next removal sweeps them.
+	try {
+		rmSync(trash, { recursive: true, force: true });
+	} catch (e) {
+		console.warn(`Warning: machine "${name}" is removed, but deleting its files at ${trash} failed (${(e as Error).message}). The next 'quickchr remove' retries it, or delete that directory by hand.`);
+	}
 }
 
+/** Delete what earlier removals moved aside and did not finish deleting: a delete that
+ *  failed, or a process that stopped after its rename. Each entry is
+ *  `<name>.<pid>.<uuid>`. One whose pid is alive in another process is still being
+ *  deleted, so it is left alone. Best effort: a failure here never fails a removal. */
+function sweepAbandonedRemovals(trashDir: string): void {
+	let entries: string[];
+	try { entries = readdirSync(trashDir); } catch { return; }
+	for (const entry of entries) {
+		const pid = Number(entry.split(".").at(-2));
+		if (!Number.isInteger(pid) || pid <= 0) continue;
+		if (pid !== process.pid) {
+			try {
+				process.kill(pid, 0);
+				continue; // still being deleted by that process
+			} catch (e) {
+				if ((e as NodeJS.ErrnoException).code === "EPERM") continue;
+			}
+		}
+		try { rmSync(join(trashDir, entry), { recursive: true, force: true }); } catch { /* next time */ }
+	}
+}
+
+/** How long `removeMachine()` keeps trying to move a directory aside: about 2 s in
+ *  all, enough for a scanner to let go of a handle. */
+const REMOVE_RENAME_ATTEMPTS = 10;
+const REMOVE_RENAME_RETRY_MS = 200;
+
 /** Update the status of a machine. */
 export function updateMachineStatus(
 	name: string,

package/src/lib/types.ts

@@ -55,13 +55,14 @@ export type NetworkMode =
  * - **Host needs to see guest L2 frames** (MNDP, MAC-Telnet, raw Ethernet,
  *   broadcasts) → `{type:"socket-connect", port}` against a host TCP server
  *   (rootless, cross-platform; recipe in `docs/mndp.md`).
- * - **L2 link between two VMs** → `{type:"socket", name}` (named pair) or
- *   `socket-listen`/`socket-connect`/`socket-mcast` (low-level).
+ * - **L2 link between two VMs** → `{type:"socket", name}`, a named link whose
+ *   transport (`dgram`, `listen-connect`, `mcast`) is fixed when the name is created;
+ *   or `socket-listen`/`socket-connect`/`socket-mcast` for a raw netdev.
  * - **Real LAN / DHCP-from-host presence** → `"shared"` or `{type:"bridged", iface}`
  *   (rootless via socket_vmnet on macOS / pre-created TAP on Linux).
  *
  * Note: receiving guest-*originated* UDP (e.g. a guest replying to `10.0.2.2`)
- * needs no extra NIC and no forward — see {@link ChrInstance.tzspGatewayIp}.
+ * needs no extra NIC and no forward — see {@link ChrInstance.hostGatewayIp}.
  */
 export type NetworkSpecifier =
 	/** SLIRP user-mode NAT + `hostfwd` port mapping. Management default; the only
@@ -106,6 +107,12 @@ export interface NetworkConfig {
 	specifier: NetworkSpecifier;
 	/** QEMU netdev id (net0, net1, ...). */
 	id: string;
+	/** Locally-administered MAC, assigned at creation and persisted so it survives
+	 *  restart. Without it QEMU hands every guest the same default sequence and two
+	 *  machines on one L2 segment collide — see `deriveMac` in `network.ts` (#154).
+	 *  Never reassigned: changing it on a booted machine orphans RouterOS's interface
+	 *  identity. Absent on machines created before #154, which keep QEMU's defaults. */
+	mac?: string;
 	/** Resolved QEMU args (populated at launch time, not persisted). */
 	resolved?: ResolvedNetwork;
 }
@@ -170,6 +177,11 @@ export const SERVICE_NAMES = Object.keys(SERVICE_PORTS) as ServiceName[];
 export const PORTS_PER_BLOCK = 10;
 export const DEFAULT_PORT_BASE = 9100;
 
+/** QEMU user-mode (SLIRP) gateway — the host's address as seen from inside a guest.
+ *  Fixed by QEMU's built-in 10.0.2.0/24 user network; surfaced on a running instance
+ *  as {@link ChrInstance.hostGatewayIp}. */
+export const HOST_GATEWAY_IP = "10.0.2.2";
+
 /**
  * TCP endpoint for QEMU IPC channels on Windows.
  * Used instead of named pipes when QEMU's Winsock bind() can't handle \\.\pipe\ paths.
@@ -222,7 +234,8 @@ export interface MachineConfig {
 	deviceMode?: DeviceModeOptions;
 	user?: { name: string; password: string };
 	disableAdmin?: boolean;
-	/** Create a 'quickchr' managed account with a generated password.  Defaults to true. */
+	/** Managed-login intent, recorded at `add()`/`start()`. Same rule as
+	 *  {@link StartOptions.secureLogin}: only an explicit `true` creates the account. */
 	secureLogin?: boolean;
 	portBase: number;
 	excludePorts: ServiceName[];
@@ -238,6 +251,34 @@ export interface MachineConfig {
 	bootDiskFormat?: BootDiskFormat;
 }
 
+/** One provisioning step, as recorded on {@link ProvisioningRecord.steps}. */
+export type ProvisioningStep =
+	| "packages"
+	| "deviceMode"
+	| "license"
+	| "user"
+	| "disableAdmin"
+	| "secureLogin";
+
+/**
+ * What provisioning actually landed on the *current* guest disk (#176).
+ *
+ * Absent means the guest has never been provisioned. `clean()` clears it along with
+ * the disk, which is what reopens the provisioning window — `lastStartedAt` cannot
+ * carry this, because it records that QEMU was launched, not that the guest was
+ * configured, and the two come apart at every `clean()`.
+ */
+export interface ProvisioningRecord {
+	/** ISO timestamp of the last time quickchr applied provisioning to this disk —
+	 *  a first-boot run, or a post-boot step such as `setDeviceMode()`. */
+	at: string;
+	/** Steps that have run on this disk, accumulated: a first-boot run stamps the set
+	 *  it applied, and a post-boot step adds itself. Not a full inventory of the guest —
+	 *  a step absent here was not applied *by quickchr*, which is a weaker claim than
+	 *  "not present". */
+	steps: ProvisioningStep[];
+}
+
 /**
  * Facts about the SSH keypair quickchr generated and installed for its managed
  * user during provisioning. Persisted on {@link MachineState} so consumers (the
@@ -260,7 +301,14 @@ export interface ManagedSshKey {
 
 export interface MachineState extends MachineConfig {
 	createdAt: string;
+	/** Last QEMU spawn. Stamped before the guest is known to have booted, so it says
+	 *  nothing about whether the guest was configured — see {@link provisioning}.
+	 *  Cleared by `clean()`, which replaces the disk that boot belonged to. */
 	lastStartedAt?: string;
+	/** Provisioning that landed on the current disk, if any (#176). */
+	provisioning?: ProvisioningRecord;
+	/** Last `clean()`, which reset the disk to the factory image. */
+	cleanedAt?: string;
 	status: "stopped" | "running" | "error";
 	pid?: number;
 	/** Path to the machine directory. */
@@ -286,7 +334,8 @@ export interface MachineState extends MachineConfig {
  * requires SCP upload + reboot cycle, typically 60–120s extra on native acceleration).
  */
 export interface StartOptions {
-	/** RouterOS version to use (e.g. "7.22.1"). Mutually exclusive with `channel`.
+	/** RouterOS version to use (e.g. "7.22.1"). Takes precedence over `channel`:
+	 *  passing both uses `version` and warns that `channel` was ignored.
 	 *  As a convenience, a channel name (e.g. "long-term") is also accepted here and
 	 *  resolves the same as `channel: "long-term"` — but this emits a warning, since
 	 *  `channel` is the self-documenting field for that case. */
@@ -303,12 +352,27 @@ export interface StartOptions {
 	cpu?: number;
 	/** Memory in MiB. Default: 512 (1024 for cross-arch TCG emulation). */
 	mem?: number;
-	/** Run QEMU in background (true, default) or foreground with serial console on stdio (false). */
+	/** Run QEMU in background (true, default) or foreground with serial console on stdio (false).
+	 *  This only decides where the serial console goes — it never made `start()` return
+	 *  sooner. That is {@link StartOptions.wait}. */
 	background?: boolean;
+	/** Wait for the guest to become ready before resolving (true, default). `false`
+	 *  resolves as soon as QEMU is confirmed running — past `spawnQemu`'s early-exit
+	 *  check, with state and ports persisted — and leaves readiness to the caller, e.g.
+	 *  `centrs retrieve --quickchr <name> /system/resource --wait 5m` (#159).
+	 *
+	 *  Provisioning runs against the booted guest, so it cannot be combined with
+	 *  `wait: false` — including first-boot options `add()` recorded. Both are refused
+	 *  (`INVALID_ARGUMENT`) rather than silently skipped, as is `background: false`,
+	 *  which blocks on the serial console regardless. */
+	wait?: boolean;
 	/** Extra packages to install after boot.
 	 *  This is quickchr provisioning, so it is validated/tested on RouterOS 7.20.8+ only. */
 	packages?: string[];
 	/** Install all packages from the all_packages ZIP (overrides packages[]).
+	 *  On the first start of an `add()`-created machine, leaving this unset keeps what
+	 *  `add()` recorded; an explicit `false` overrides it. The same holds for
+	 *  `disableAdmin` and `secureLogin`.
 	 *  This is quickchr provisioning, so it is validated/tested on RouterOS 7.20.8+ only. */
 	installAllPackages?: boolean;
 	/** Create a user after boot.
@@ -317,8 +381,12 @@ export interface StartOptions {
 	/** Disable the default admin account after boot.
 	 *  This is quickchr provisioning, so it is validated/tested on RouterOS 7.20.8+ only. */
 	disableAdmin?: boolean;
-	/** Create a 'quickchr' managed account with a generated password.  Defaults to true.
-	 *  Set to false to keep admin with no password (exec still works).
+	/** Create a 'quickchr' managed account with a generated password. **Only an explicit
+	 *  `true` does this.** Unset and `false` are the same: the machine keeps the factory
+	 *  `admin` login with an empty password (exec still works). The CLI resolves the
+	 *  `secure-login` setting into this field, so it can be `true` without the flag.
+	 *  This is the one statement of the rule — `MachineState.secureLogin` and
+	 *  `provision()` point here.
 	 *  Enabling the managed login path is quickchr provisioning, so it is validated/tested
 	 *  on RouterOS 7.20.8+ only. */
 	secureLogin?: boolean;
@@ -341,7 +409,7 @@ export interface StartOptions {
 	 *  {@link lookupGuestPort} resolve guest port + proto for common service names.
 	 *
 	 *  For *receiving* guest-originated UDP (no forward needed), see
-	 *  {@link ChrInstance.tzspGatewayIp} and `docs/networking-recipes.md`.
+	 *  {@link ChrInstance.hostGatewayIp} and `docs/networking-recipes.md`.
 	 *  @example
 	 *  extraPorts: [{ name: "snmp", host: 9161, guest: 161, proto: "udp" }]
 	 *  @example
@@ -548,6 +616,20 @@ export interface ChrLoadSample {
 	memUsedMb: number;
 }
 
+/** Options for an explicit guest shutdown. Library values do not read environment settings. */
+export interface ShutdownOptions {
+	/** Guest request + exit-wait budget in milliseconds (default 10,000).
+	 * Lock acquisition and hard-stop escalation have separate bounded waits. */
+	timeoutMs?: number;
+}
+
+export interface ShutdownResult {
+	/** Observed guest exit is not a guarantee of application/storage durability. */
+	outcome: "guest-exited" | "forced" | "already-stopped";
+	/** Request failure can accompany successful guest exit (HTTP 400 interrupted). */
+	requestError?: string;
+}
+
 /**
  * Runtime handle for a CHR virtual machine.
  *
@@ -556,7 +638,9 @@ export interface ChrLoadSample {
  * snapshots, licensing, and lifecycle management.
  *
  * After `QuickCHR.start()` resolves, the instance is REST-ready — all requested
- * provisioning (packages, license, device-mode, user creation) has completed.
+ * provisioning (packages, license, device-mode, user creation) has completed —
+ * unless it was started with `wait: false`, or is a RouterOS 6 guest (no REST:
+ * `rest()` and REST `exec()` throw `REST_UNAVAILABLE`).
  */
 export interface ChrInstance {
 	name: string;
@@ -591,15 +675,15 @@ export interface ChrInstance {
 	 *  `docs/networking-recipes.md`, `examples/udp-gateway/`.
 	 *  @example
 	 *  // RouterOS TZSP sniffer streaming to the host:
-	 *  await instance.exec(`/tool/sniffer/set streaming-server=${instance.tzspGatewayIp}:37008`);
+	 *  await instance.exec(`/tool/sniffer/set streaming-server=${instance.hostGatewayIp}:37008`);
 	 */
-	tzspGatewayIp: string;
+	hostGatewayIp: string;
 
-	/** Check or wait for REST API readiness.
-	 *  After `QuickCHR.start()` with provisioning options (installAllPackages, license, etc.),
-	 *  the returned instance is already REST-reachable — this returns immediately.
-	 *  Call this only when starting without provisioning, or as a safety check after a manual stop/restart. */
-	/** @param stats Optional out-param; each REST readiness probe is classified
+	/** Check or wait for readiness — REST, or a native-API login on RouterOS 6 (#182).
+	 *  After `QuickCHR.start()` the returned instance is already ready, so this returns
+	 *  immediately. Call it after `start({ wait: false })`, or as a safety check after a
+	 *  manual stop/restart. */
+	/** @param stats Optional out-param; each REST or native-API readiness probe is classified
 	 *  into it (see diagnostics.ts BootProbeStats) so a failed wait can explain
 	 *  whether the forwarded port ever answered. */
 	waitForBoot(timeoutMs?: number, stats?: BootProbeStats): Promise<boolean>;
@@ -621,7 +705,12 @@ export interface ChrInstance {
 	 *  }, 30_000);
 	 */
 	waitFor(condition: () => Promise<boolean>, timeoutMs?: number): Promise<boolean>;
+	/** Power cut: terminate QEMU with SIGTERM, then SIGKILL if needed.
+	 * Pending guest configuration may be lost. Use shutdown() to request guest shutdown. */
 	stop(): Promise<void>;
+	/** Request /system/shutdown once over REST, wait for QEMU exit, then hard-stop
+	 * if needed. Reports forced fallback explicitly; preserves disks and credentials. */
+	shutdown(options?: ShutdownOptions): Promise<ShutdownResult>;
 	remove(): Promise<void>;
 	clean(): Promise<void>;
 	/** Stop and permanently delete this instance (disk + state). Equivalent to stop() then remove(). */
@@ -805,6 +894,10 @@ export type ErrorCode =
 	| "INVALID_VERSION"
 	| "INVALID_ARCH"
 	| "INVALID_NAME"
+	// A flag or argument the CLI cannot honour as written — a removed flag name, or a
+	// value it will not accept. Distinct from INVALID_SETTING_VALUE, which is about a
+	// stored setting rather than what was typed.
+	| "INVALID_ARGUMENT"
 	| "INVALID_DISK_SIZE"
 	| "MACHINE_LOCKED"
 	| "EXEC_FAILED"
@@ -814,6 +907,13 @@ export type ErrorCode =
 	| "INVALID_NETWORK"
 	| "INVALID_FORWARD_SPEC"
 	| "PROVISIONING_VERSION_UNSUPPORTED"
+	// A provisioning option handed to a machine whose provisioning window has closed:
+	// the guest has booted, so quickchr cannot assume it still holds the default
+	// configuration provisioning expects. Never silently dropped (#176).
+	| "PROVISIONING_WINDOW_CLOSED"
+	// An operation that needs the REST API, on a guest that has none — RouterOS 6, a
+	// boot-only target (#182). Thrown up front instead of letting the request time out.
+	| "REST_UNAVAILABLE"
 	| "INSUFFICIENT_DISK_SPACE"
 	| "STATE_ERROR"
 	| "INVALID_SIZE_STRING"

package/src/lib/versions.ts

@@ -35,6 +35,11 @@ export const ROUTEROS_COMPATIBILITY_MATRIX: RouterOsCompatibilityRow[] = [
 		minimumVersion: "any RouterOS 7.x",
 		notes: "QEMU networking setup before or during boot.",
 	},
+	{
+		feature: "Boot / start / stop on RouterOS 6",
+		minimumVersion: "6.x (x86 only)",
+		notes: "Best-effort boot-only target for v6→v7 migration testing (#182). CLI only; readiness is a native-API login; no provisioning, no REST operations.",
+	},
 	{
 		feature: "Managed login, custom user, disable-admin",
 		minimumVersion: MIN_PROVISION_VERSION,
@@ -242,12 +247,61 @@ export function isProvisioningSupportedVersion(
 	return compareRouterOsVersion(version, minimumVersion) >= 0;
 }
 
+/**
+ * RouterOS 6 is a best-effort **boot-only** target (#182): quickchr downloads, boots and
+ * tracks a 6.x CHR, and does nothing else to it. It exists so a tool driving a v6→v7
+ * migration (tikoci/centrs#386) has a disposable 6.x router to test against — it is not
+ * RouterOS 6 support. CLI only: the wizard does not offer it.
+ *
+ * 6.x has no REST API, so readiness is a native-API `/login` (see `readinessProbeFor()`
+ * in qemu.ts), every provisioning step is refused, and anything that reads or writes
+ * through REST fails with `REST_UNAVAILABLE` rather than timing out.
+ */
+export function isRouterOs6(version: string): boolean {
+	return /^6\./.test(version);
+}
+
+export const ROUTEROS6_BOOT_ONLY =
+	"RouterOS 6 is a best-effort boot-only target: quickchr downloads, boots and tracks it, and runs no provisioning or REST operations on it.";
+
+/** MikroTik publishes RouterOS 6 CHR images for x86 only — `chr-6.49.23-arm64.img.zip`
+ *  is a 404 (checked 2026-10-21). Refused before the download that would say so less
+ *  clearly. */
+export function assertRouterOs6Arch(version: string, arch: Arch): void {
+	if (!isRouterOs6(version) || arch === "x86") return;
+	throw new QuickCHRError(
+		"INVALID_ARCH",
+		`RouterOS ${version} has no ${arch} CHR image — MikroTik publishes RouterOS 6 CHR for x86 only. Pass --arch x86 (arch: "x86").`,
+	);
+}
+
+/** Refuse an operation that needs REST on a guest that cannot have it. The message
+ *  leads with "RouterOS 6: not available" so a caller scanning for the reason finds it
+ *  first, and names the transport that does work. */
+export function assertRestAvailable(machine: { name: string; version: string }, operation: string): void {
+	if (!isRouterOs6(machine.version)) return;
+	throw new QuickCHRError(
+		"REST_UNAVAILABLE",
+		`RouterOS 6: not available — ${operation} uses the REST API, which RouterOS ${machine.version} does not have. ` +
+		`${ROUTEROS6_BOOT_ONLY} Reach it over the native API instead, e.g. ` +
+		`centrs retrieve --quickchr ${machine.name} /system/resource --via native-api --no-validate ` +
+		"(centrs validates against the 7.x command tree, so a 6.x read skips it)",
+	);
+}
+
 /** Guard provisioning operations to reduce version-dependent failure modes. */
 export function assertProvisioningSupportedVersion(
 	version: string,
 	operation: string,
 	minimumVersion = MIN_PROVISION_VERSION,
 ): void {
+	if (isRouterOs6(version)) {
+		throw new QuickCHRError(
+			"PROVISIONING_VERSION_UNSUPPORTED",
+			`Cannot ${operation} on RouterOS ${version}. ${ROUTEROS6_BOOT_ONLY}`,
+			`Drop the provisioning options to boot ${version} as it ships, or use RouterOS ${minimumVersion}+ for ${PROVISIONING_FEATURE_SUMMARY}.`,
+		);
+	}
 	if (isProvisioningSupportedVersion(version, minimumVersion)) return;
 
 	throw new QuickCHRError(