@tikoci/quickchr 0.4.8 → 0.5.1

package/src/lib/storage.ts

@@ -1,41 +1,81 @@
 /**
- * Storage health and usage helpers for quickchr-managed files.
+ * Storage admission and usage helpers for quickchr-managed files.
+ *
+ * An operation that writes is admitted when each filesystem it writes to has room for
+ * what the operation itself will write there (its estimated peak) plus the configured
+ * host reserve. When one does not, eligible cache entries are evicted first and free
+ * space is measured again; only then is the operation refused (#199).
  */
 
-import { existsSync, lstatSync, readdirSync, statfsSync } from "node:fs";
+import { existsSync, statfsSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { type CacheEntry, countEntries, describePrune, type PruneResult, pruneCacheUnderLock, RECENT_USE_MS } from "./cache.ts";
+import { createLease, filesystemOf, liveLeases, type StorageLease, withStorageLock } from "./storage-lease.ts";
 import { formatDiskSize } from "./disk.ts";
-import { getCacheDir, getDataDir, getMachinesDir } from "./state.ts";
-import { QuickCHRError } from "./types.ts";
+import { resolveSetting } from "./settings.ts";
+import { directorySize, getCacheDir, getDataDir, getMachinesDir } from "./state.ts";
+import { chrImageBasename } from "./versions.ts";
+import { type Arch, QuickCHRError } from "./types.ts";
 
-export const QUICKCHR_MIN_FREE_BYTES = 10 * 1024 ** 3;
-export const QUICKCHR_WARN_FREE_BYTES = 20 * 1024 ** 3;
+const MiB = 1024 ** 2;
+
+/**
+ * Peak new bytes per stage, rounded up from one host's measurements (#199, macOS x86,
+ * CHR 7.20–7.26): a 128 MiB extracted image from a ~45 MiB ZIP, a qcow2 boot disk of
+ * ~50 MiB after first boot (never more than the raw image it is converted from), and
+ * 29–52 MiB package archives that extract to about their own size. Estimates, not
+ * bounds: they are what admission charges, and the reserve absorbs the error.
+ */
+export const STORAGE_ESTIMATES = {
+	/** Image ZIP plus its extraction, which coexist until the ZIP is removed. */
+	imageDownload: 256 * MiB,
+	/** A raw copy or a qcow2 conversion of the image, plus first-boot writes. */
+	bootDisk: 192 * MiB,
+	/** The all-packages archive plus its extraction; both are kept. */
+	packagesDownload: 192 * MiB,
+} as const;
+
+/** doctor warns while free space is under the reserve plus this much. */
+const WARN_MARGIN_BYTES = 2 * 1024 ** 3;
 
 export interface QuickchrStorageReport {
-	label: ".local" | "data dir";
+	/** The data dir: where the cache and machines are written. */
 	path: string;
+	/** The nearest existing directory to `path`, whose filesystem is measured. */
 	statPath: string;
 	freeBytes: number;
 	quickchrBytes: number;
 	cacheBytes: number;
 	machinesBytes: number;
 	otherBytes: number;
-	recommendedFreeBytes: number;
+	reserveBytes: number;
 	warningFreeBytes: number;
 	status: "ok" | "warn" | "error";
 }
 
-function resolveStorageRoot(): { label: QuickchrStorageReport["label"]; path: string } {
-	if (process.env.QUICKCHR_DATA_DIR || process.platform === "win32") {
-		return { label: "data dir", path: getDataDir() };
-	}
-
-	const home = process.env.HOME || process.env.USERPROFILE || "";
-	if (!home) {
-		return { label: "data dir", path: getDataDir() };
-	}
+/** One stage of an operation's writes. */
+export interface StoragePart {
+	/** For the refusal message, e.g. "boot disk". */
+	label: string;
+	/** Estimated peak new bytes. */
+	bytes: number;
+	/** Where they are written: the part is checked on that path's filesystem. */
+	path: string;
+	/** Reserve the bytes in the operation's lease (the default). False for a stage that
+	 *  admits and reserves for itself when it runs, such as a download a create will
+	 *  trigger: checked now, so the create refuses early, but not held twice. */
+	hold?: boolean;
+}
 
-	return { label: ".local", path: join(home, ".local") };
+/** What an operation is about to write and read, for admission. */
+export interface StorageNeed {
+	parts: StoragePart[];
+	/** Versions the operation reads from the cache: reclamation never evicts them. */
+	protectVersions?: string[];
+	/** Cache entries the operation reads; pinned in its lease. */
+	pins?: string[];
+	/** The cache reclamation evicts from. Default: the data dir's cache. */
+	cacheDir?: string;
 }
 
 function nearestExistingPath(path: string): string {
@@ -48,30 +88,6 @@ function nearestExistingPath(path: string): string {
 	return current;
 }
 
-function directorySize(path: string): number {
-	if (!existsSync(path)) return 0;
-
-	const stat = lstatSync(path);
-	if (!stat.isDirectory()) {
-		return stat.size;
-	}
-
-	let total = 0;
-	for (const entry of readdirSync(path, { withFileTypes: true })) {
-		const fullPath = join(path, entry.name);
-		if (entry.isDirectory()) {
-			total += directorySize(fullPath);
-		} else {
-			try {
-				total += lstatSync(fullPath).size;
-			} catch {
-				// Skip entries that can't be stat'd (e.g. Windows named pipes throw EACCES)
-			}
-		}
-	}
-	return total;
-}
-
 function freeBytesForPath(path: string): number {
 	if (process.platform !== "win32") {
 		const result = Bun.spawnSync(["df", "-kP", path], {
@@ -95,15 +111,23 @@ function freeBytesForPath(path: string): number {
 	return fsStats.bavail * (fsStats.bsize || 4096);
 }
 
+/** The free-space measurement and filesystem identity, as an object so tests can
+ *  replace them (a unit test cannot mount a second filesystem). */
+export const storageProbe = { freeBytes: freeBytesForPath, filesystem: filesystemOf };
+
+/** The configured host reserve: the `storage-reserve` setting (default 2 GiB). */
+export function resolveStorageReserve(): number {
+	return resolveSetting("storage-reserve").value as number;
+}
+
 export function getQuickchrStorageReport(
-	recommendedFreeBytes: number = QUICKCHR_MIN_FREE_BYTES,
-	warningFreeBytes: number = QUICKCHR_WARN_FREE_BYTES,
+	reserveBytes: number = resolveStorageReserve(),
+	warningFreeBytes: number = reserveBytes + WARN_MARGIN_BYTES,
 ): QuickchrStorageReport {
-	const storageRoot = resolveStorageRoot();
-	const statPath = nearestExistingPath(storageRoot.path);
-	const freeBytes = freeBytesForPath(statPath);
-
 	const dataDir = getDataDir();
+	const statPath = nearestExistingPath(dataDir);
+	const freeBytes = storageProbe.freeBytes(statPath);
+
 	const cacheBytes = directorySize(getCacheDir());
 	const machinesBytes = directorySize(getMachinesDir());
 	const dataDirBytes = directorySize(dataDir);
@@ -111,22 +135,21 @@ export function getQuickchrStorageReport(
 	const otherBytes = Math.max(0, dataDirBytes - cacheBytes - machinesBytes);
 
 	let status: QuickchrStorageReport["status"] = "ok";
-	if (freeBytes < recommendedFreeBytes) {
+	if (freeBytes < reserveBytes) {
 		status = "error";
 	} else if (freeBytes < warningFreeBytes) {
 		status = "warn";
 	}
 
 	return {
-		label: storageRoot.label,
-		path: storageRoot.path,
+		path: dataDir,
 		statPath,
 		freeBytes,
 		quickchrBytes,
 		cacheBytes,
 		machinesBytes,
 		otherBytes,
-		recommendedFreeBytes,
+		reserveBytes,
 		warningFreeBytes,
 		status,
 	};
@@ -143,21 +166,155 @@ export function formatQuickchrUsage(report: QuickchrStorageReport): string {
 	return `quickchr uses ${formatDiskSize(report.quickchrBytes)} (${parts.join(", ")})`;
 }
 
-export function assertSufficientQuickchrStorage(
-	action: string,
-	minimumFreeBytes: number = QUICKCHR_MIN_FREE_BYTES,
-): QuickchrStorageReport {
-	const report = getQuickchrStorageReport(
-		minimumFreeBytes,
-		Math.max(QUICKCHR_WARN_FREE_BYTES, minimumFreeBytes),
-	);
+/** What creating a machine will write: its boot disk, plus the image and package
+ *  downloads it still needs. Extra disks are sparse qcow2 and start near zero.
+ *  Only the boot disk is held in the create's lease: each download admits and
+ *  reserves for itself when it runs, so holding it here would count it twice. */
+export function estimateMachineCreation(opts: { version: string; arch: Arch; packages: boolean }): StorageNeed {
+	const cache = getCacheDir();
+	const image = chrImageBasename(opts.version, opts.arch);
+	const parts: StoragePart[] = [{ label: "boot disk", bytes: STORAGE_ESTIMATES.bootDisk, path: getMachinesDir() }];
+	if (!existsSync(join(cache, `${image}.img`))) {
+		parts.push({ label: "image download", bytes: STORAGE_ESTIMATES.imageDownload, path: cache, hold: false });
+	}
+	if (opts.packages && !existsSync(join(cache, `packages-${opts.arch}-${opts.version}`))) {
+		parts.push({ label: "packages download", bytes: STORAGE_ESTIMATES.packagesDownload, path: cache, hold: false });
+	}
+	return { parts, protectVersions: [opts.version], pins: [`${image}.img`, `${image}.img.zip`] };
+}
+
+interface FilesystemGroup {
+	dev: number;
+	statPath: string;
+	parts: StoragePart[];
+	bytes: number;
+}
 
-	if (report.freeBytes < minimumFreeBytes) {
-		throw new QuickCHRError(
-			"INSUFFICIENT_DISK_SPACE",
-			`Not enough free space to ${action} in ${report.path}: ${formatDiskSize(report.freeBytes)} available, need at least ${formatDiskSize(minimumFreeBytes)}. ${formatQuickchrUsage(report)}.`,
-		);
+function groupByFilesystem(parts: StoragePart[]): FilesystemGroup[] {
+	const groups = new Map<number, FilesystemGroup>();
+	for (const part of parts.length > 0 ? parts : [{ label: "", bytes: 0, path: getDataDir() }]) {
+		const { dev, statPath } = storageProbe.filesystem(part.path);
+		const group = groups.get(dev) ?? { dev, statPath, parts: [], bytes: 0 };
+		if (part.label) group.parts.push(part);
+		group.bytes += part.bytes;
+		groups.set(dev, group);
 	}
+	return [...groups.values()];
+}
+
+/**
+ * Admit an operation, or throw `INSUFFICIENT_DISK_SPACE`. Returns a lease the caller
+ * releases once its writes are done (see storage-lease.ts).
+ *
+ * Each filesystem the operation writes to is checked on its own: free space, less
+ * what other in-flight operations have reserved there, must cover that filesystem's
+ * parts plus the reserve. When it does not, and the cache being reclaimed lives on that
+ * filesystem, eligible entries are evicted (oldest version first; never in-use, pinned,
+ * protected or recently used ones) and free space is measured again — repeatedly,
+ * because logical sizes are no proof of room (sparse files, APFS clones), until the
+ * measurement admits or nothing more can be evicted. When everything eligible could
+ * not cover the shortage, nothing is evicted.
+ *
+ * The check and the lease are made under the storage lock, so two creators cannot
+ * spend the same free bytes, and an eviction cannot remove what this operation pins.
+ */
+export function admitStorage(
+	action: string,
+	need: StorageNeed = { parts: [] },
+	opts: { reclaim?: boolean; logger?: (message: string) => void } = {},
+): StorageLease {
+	return withStorageLock(() => {
+		const reserveBytes = resolveStorageReserve();
+		const leases = liveLeases();
+		const pins = new Set([...leases.flatMap((lease) => lease.pins), ...(need.pins ?? [])]);
+		const cacheDir = need.cacheDir ?? getCacheDir();
+		const cacheDev = storageProbe.filesystem(cacheDir).dev;
 
-	return report;
+		for (const group of groupByFilesystem(need.parts)) {
+			const reservedByOthers = leases
+				.flatMap((lease) => lease.reservations)
+				.filter((r) => r.dev === group.dev)
+				.reduce((sum, r) => sum + r.bytes, 0);
+			const measure = () => storageProbe.freeBytes(group.statPath) - reservedByOthers;
+			const required = group.bytes + reserveBytes;
+			let free = measure();
+			if (free >= required) continue;
+
+			const reclaim = opts.reclaim !== false && cacheDev === group.dev;
+			const evicted: CacheEntry[] = [];
+			const failed: PruneResult["failed"] = [];
+			let kept: PruneResult | undefined;
+			let wouldNotCover = false;
+			if (reclaim) {
+				const policy = { cacheDir, protectVersions: need.protectVersions, skipRecentMs: RECENT_USE_MS };
+				// Evicting cannot close a gap larger than everything eligible: refuse with the
+				// cache intact rather than empty it for nothing.
+				kept = pruneCacheUnderLock({ ...policy, reclaimBytes: required - free, dryRun: true }, pins);
+				wouldNotCover = kept.freedBytes < required - free;
+				while (!wouldNotCover && free < required) {
+					const pass = pruneCacheUnderLock({
+						...policy,
+						reclaimBytes: required - free,
+						skipEntries: failed.map((f) => f.entry.basename),
+					}, pins);
+					for (const line of describePrune(pass)) opts.logger?.(line);
+					evicted.push(...pass.evicted);
+					failed.push(...pass.failed);
+					kept = pass;
+					free = measure();
+					if (pass.evicted.length === 0) break;
+				}
+				if (free >= required) continue;
+			}
+
+			throw insufficientSpace(action, group, { free, required, reserveBytes, reservedByOthers, reclaimed: kept && { evicted, failed, kept, wouldNotCover } });
+		}
+
+		const reservations = groupByFilesystem(need.parts.filter((part) => part.hold !== false))
+			.filter((group) => group.bytes > 0)
+			.map((group) => ({ dev: group.dev, bytes: group.bytes }));
+		if (reservations.length === 0 && (need.pins ?? []).length === 0) return { record: { pid: process.pid, at: "", action, pins: [], reservations: [] }, release() {} };
+		return createLease(action, need.pins ?? [], reservations);
+	});
+}
+
+function insufficientSpace(
+	action: string,
+	group: FilesystemGroup,
+	facts: {
+		free: number;
+		required: number;
+		reserveBytes: number;
+		reservedByOthers: number;
+		reclaimed?: { evicted: CacheEntry[]; failed: PruneResult["failed"]; kept: PruneResult; wouldNotCover: boolean };
+	},
+): QuickCHRError {
+	const detail = group.parts.map((part) => `${part.label} ${formatDiskSize(part.bytes)}`).join(" + ");
+	const needs = detail ? `${detail} + ${formatDiskSize(facts.reserveBytes)} reserve` : `${formatDiskSize(facts.reserveBytes)} reserve`;
+	const available = facts.reservedByOthers > 0
+		? `${formatDiskSize(facts.free)} available after ${formatDiskSize(facts.reservedByOthers)} held by other operations in progress`
+		: `${formatDiskSize(facts.free)} available`;
+	const sentences = [
+		`Not enough free space to ${action} in ${group.statPath}: ${available}, need ${formatDiskSize(facts.required)} (${needs}), ${formatDiskSize(facts.required - facts.free)} short.`,
+	];
+	const r = facts.reclaimed;
+	if (r) {
+		const freed = r.evicted.reduce((sum, e) => sum + e.sizeBytes, 0);
+		let line = r.wouldNotCover
+			? r.kept.evicted.length > 0
+				? `The cache could spare only ${formatDiskSize(r.kept.freedBytes)} (${countEntries(r.kept.evicted.length)}), not enough, so nothing was evicted.`
+				: "Nothing in the cache could be evicted."
+			: `Evicted ${countEntries(r.evicted.length)} from the cache (${formatDiskSize(freed)}) first.`;
+		if (r.failed.length > 0) line += ` ${r.failed.length} delete(s) failed.`;
+		const keptBytes = r.kept.kept
+			.filter((e) => r.kept.reasons[e.basename] !== "kept")
+			.reduce((sum, e) => sum + e.sizeBytes, 0);
+		if (keptBytes > 0) line += ` ${formatDiskSize(keptBytes)} is kept: in use by a machine or an operation in progress, needed by this operation, or used in the last ${RECENT_USE_MS / 60_000} minutes.`;
+		sentences.push(line);
+	}
+	return new QuickCHRError(
+		"INSUFFICIENT_DISK_SPACE",
+		sentences.join(" "),
+		"Free space on that filesystem, remove machines you no longer need, or lower the reserve with 'quickchr settings set storage-reserve <size>' (QUICKCHR_STORAGE_RESERVE).",
+	);
 }

package/src/lib/types.ts

@@ -234,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[];
@@ -250,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
@@ -272,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. */
@@ -298,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. */
@@ -315,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.
@@ -329,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;
@@ -376,7 +432,8 @@ export interface StartOptions {
 	 *  networks: ["user", { type: "socket-connect", port: hostTcpServerPort }]
 	 */
 	networks?: NetworkSpecifier[];
-	/** Install OS-level dependencies (QEMU, firmware) automatically if missing. */
+	/** @deprecated Ignored — nothing ever read it, so it never installed anything (#193).
+	 *  `quickchr doctor` lists missing host dependencies. To be removed in a later minor. */
 	installDeps?: boolean;
 	/** Print QEMU command and config without actually starting the VM. */
 	dryRun?: boolean;
@@ -560,6 +617,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.
  *
@@ -568,7 +639,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;
@@ -606,20 +679,12 @@ export interface ChrInstance {
 	 *  await instance.exec(`/tool/sniffer/set streaming-server=${instance.hostGatewayIp}:37008`);
 	 */
 	hostGatewayIp: string;
-	/** @deprecated Renamed to {@link ChrInstance.hostGatewayIp} — the value was never
-	 *  TZSP-specific, it is the host as seen from inside the guest and carries any
-	 *  guest→host UDP (remote syslog, NetFlow, a plain socket). The old name led
-	 *  readers to assume a sniffer-only primitive.
-	 *
-	 *  Still populated with the identical value, and will be removed no earlier than
-	 *  the next minor. Migration is a rename at the call site — nothing else changes. */
-	tzspGatewayIp: 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>;
@@ -641,7 +706,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(). */
@@ -671,7 +741,8 @@ export interface ChrInstance {
 	 *  **Soft errors.** Some RouterOS commands return HTTP 200 with an error
 	 *  string in `output` (e.g. `/dude/agent/add` may resolve OK with
 	 *  `"doAdd Agent not implemented"`). `exec()` does not parse output for these
-	 *  patterns — inspect `result.output` if you need to assert success.
+	 *  patterns — inspect `result.output` if you need to assert success. For a
+	 *  pass/fail result, use `centrs execute --quickchr <name> --yes <command>`.
 	 */
 	exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
 	/** Apply or renew a CHR trial license.
@@ -838,6 +909,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"
@@ -873,7 +951,15 @@ export interface ExecOptions {
 	timeout?: number;
 }
 
-/** Result of a ChrInstance.exec() call. */
+/** Result of a ChrInstance.exec() call.
+ *
+ *  A resolved `exec()` means the command was **delivered**, not that RouterOS
+ *  accepted it. `/rest/execute` answers HTTP 200 with the rejection text (e.g.
+ *  `failure: invalid user name`) in the same envelope as a success, so there is no
+ *  failure field here, and quickchr does not pattern-match RouterOS error text
+ *  (#142). For a pass/fail result, run the command through
+ *  `centrs execute --quickchr <name> --yes <command>`, which validates it first and
+ *  exits non-zero on a rejection (`--yes` confirms a write command outside a TTY). */
 export interface ExecResult {
 	/** Command output as a string (or parsed JSON when output="json"). */
 	output: 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(