@tikoci/quickchr 0.4.8 → 0.5.1

package/src/lib/completions.ts

@@ -328,7 +328,7 @@ _quickchr() {
         cword=${D}COMP_CWORD
     }
 
-    local commands="add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help"
+    local commands="add start stop shutdown list ls status inspect env get set remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help"
 
     if [[ ${D}cword -eq 1 ]]; then
         COMPREPLY=( $(compgen -W "${D}commands" -- "${D}cur") )
@@ -337,12 +337,12 @@ _quickchr() {
 
     local cmd="${D}{words[1]}"
     case "${D}cmd" in
-        start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env)
+        start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env|get|set)
             local machines
             machines=$(quickchr completions --machines 2>/dev/null)
             COMPREPLY=( $(compgen -W "${D}machines" -- "${D}cur") )
             ;;
-        stop)
+        stop|shutdown)
             local machines
             machines=$(quickchr completions --running 2>/dev/null)
             [[ -z "${D}machines" ]] && machines=$(quickchr completions --machines 2>/dev/null)
@@ -387,12 +387,15 @@ _quickchr() {
             local commands=(
                 'add:Create a new CHR machine (without starting)'
                 'start:Start or restart a CHR instance'
-                'stop:Stop instance(s)'
+                'stop:Power cut instance(s)'
+                'shutdown:Request guest shutdown'
                 'list:List all instances'
                 'ls:List all instances (alias)'
                 'status:Detailed status'
                 'inspect:Print running machine descriptor'
                 'env:Print subprocess environment'
+                'get:Show live machine config (license, device-mode, admin)'
+                'set:Change a booted machine (license, device-mode)'
                 'remove:Remove instance(s) and disk'
                 'rm:Remove instance(s) (alias)'
                 'clean:Reset instance disk to fresh image'
@@ -418,12 +421,12 @@ _quickchr() {
         args)
             local cmd="${D}{words[2]}"
             case ${D}cmd in
-                start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env)
+                start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env|get|set)
                     local machines
                     machines=(${D}{(f)"${D}(quickchr completions --machines 2>/dev/null)"})
                     _describe 'machine' machines
                     ;;
-                stop)
+                stop|shutdown)
                     local machines
                     machines=(${D}{(f)"${D}(quickchr completions --running 2>/dev/null)"})
                     (( ${D}{#machines} == 0 )) && machines=(${D}{(f)"${D}(quickchr completions --machines 2>/dev/null)"})
@@ -444,7 +447,7 @@ _quickchr() {
                     _describe 'cache subcommand' subcommands
                     ;;
                 help)
-                    local commands=(add start stop list status inspect env remove clean console exec qga license disk snapshot networks cache doctor settings setup completions version)
+                    local commands=(add start stop shutdown list status inspect env get set remove clean console exec qga license disk snapshot networks cache doctor settings setup completions version)
                     _describe 'command' commands
                     ;;
             esac
@@ -460,7 +463,7 @@ function generateFishCompletion(): string {
 	return `# quickchr fish completion
 # Generated by quickchr. Fish auto-loads files from ~/.config/fish/completions/.
 
-set -l quickchr_commands add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help
+set -l quickchr_commands add start stop shutdown list ls status inspect env get set remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help
 
 # Disable file completions globally for quickchr
 complete -c quickchr -f
@@ -471,7 +474,9 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "start"       -d "Start or restart a CHR instance"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
-    -a "stop"        -d "Stop instance(s)"
+    -a "stop"        -d "Power cut instance(s)"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "shutdown"    -d "Request guest shutdown"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "list ls"     -d "List all instances"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
@@ -491,6 +496,10 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "qga"         -d "Guest agent command"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "get"         -d "Show live machine config (license, device-mode, admin)"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \
+    -a "set"         -d "Change a booted machine (license, device-mode)"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \
     -a "license"     -d "Apply/renew CHR trial license"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "disk"        -d "Show disk details"
@@ -514,12 +523,12 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "help"        -d "Show help"
 
 # Machine name completions for commands that take a running machine
-complete -c quickchr -n "__fish_seen_subcommand_from stop" \\
+complete -c quickchr -n "__fish_seen_subcommand_from stop shutdown" \\
     -a "(quickchr completions --running 2>/dev/null; or quickchr completions --machines 2>/dev/null)" \\
     -d "machine"
 
 # Machine name completions for commands that take any machine
-complete -c quickchr -n "__fish_seen_subcommand_from start remove rm clean console exec qga license disk snapshot snap status inspect env" \\
+complete -c quickchr -n "__fish_seen_subcommand_from start remove rm clean console exec qga license disk snapshot snap status inspect env get set" \\
     -a "(quickchr completions --machines 2>/dev/null)" \\
     -d "machine"
 

package/src/lib/device-mode.ts

@@ -4,6 +4,7 @@
 
 import type { DeviceModeOptions } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
+import { shellQuote } from "./names.ts";
 import { restGet, restPost } from "./rest.ts";
 
 export const KNOWN_DEVICE_MODES = ["home", "advanced", "basic", "rose"] as const;
@@ -63,6 +64,26 @@ function normalizeFeatureList(list: string[] | undefined): string[] {
 	return [...new Set(values)];
 }
 
+/** Keys `/system/device-mode` reports that are not feature flags. `mode` is the
+ *  device-mode itself; the rest are status RouterOS keeps alongside it. */
+export const DEVICE_MODE_NON_FEATURE_KEYS: ReadonlySet<string> = new Set([
+	"mode",
+	"allowed-versions",
+	"attempt-count",
+	"flagged",
+	"flagging-enabled",
+]);
+
+/** Is this feature on, as RouterOS reports it?
+ *
+ *  RouterOS answers `/system/device-mode` with **strings**: `"container": "true"`, not
+ *  `true`. A reader that tests `value === true` therefore finds nothing enabled, ever —
+ *  which is what `quickchr get <name> device-mode` did, printing a bare mode and no
+ *  feature line however many were on. Normalize before deciding. */
+export function isDeviceModeFeatureEnabled(value: unknown): boolean {
+	return toYesNo(value) === "yes";
+}
+
 function toYesNo(value: unknown): string {
 	if (typeof value === "boolean") return value ? "yes" : "no";
 	if (typeof value === "number") return value > 0 ? "yes" : "no";
@@ -148,20 +169,61 @@ export function formatDeviceModeSelection(options: ResolvedDeviceModeOptions): s
 	return parts.join(" ");
 }
 
-/** Wait until the device-mode REST endpoint is reachable with default admin auth. */
-export async function waitForDeviceModeApi(httpPort: number, timeoutMs: number = 60_000): Promise<void> {
-	const auth = `Basic ${btoa("admin:")}`;
+/** Factory credentials — `admin` with no password, as a fresh CHR ships.
+ *
+ *  The right auth for device-mode during *first-boot* provisioning, where it runs
+ *  before any account has been created, and the wrong auth afterwards: a machine
+ *  provisioned with `--disable-admin` answers 401. Post-boot callers resolve the
+ *  machine's own credentials instead — see `applyDeviceMode`. */
+export const FACTORY_AUTH_HEADER = `Basic ${btoa("admin:")}`;
+
+/** Is this response body actually `/system/device-mode`, and not the post-boot race?
+ *
+ *  RouterOS can answer a non-resource endpoint with resource-shaped or otherwise wrong
+ *  data for a short window after boot — `provisioning.instructions.md` documents this
+ *  for exactly this endpoint, and `readDeviceMode()` carries a guard for it. A 2xx is
+ *  therefore not proof the endpoint is ready; a body with `mode` in it is. */
+function isDeviceModeBody(body: string): boolean {
+	let data: unknown;
+	try { data = JSON.parse(body); } catch { return false; }
+	const record = Array.isArray(data) ? data[0] : data;
+	if (!record || typeof record !== "object") return false;
+	const keys = record as Record<string, unknown>;
+	if ("board-name" in keys || "architecture-name" in keys) return false;
+	return "mode" in keys;
+}
+
+/** Wait until the device-mode REST endpoint is reachable **and answering with
+ *  device-mode data**.
+ *
+ *  Returning on a bare 2xx was a race the next line then paid for: `readDeviceMode()`
+ *  rejects a resource-shaped body outright, so a guest that came back mid-race failed
+ *  the whole operation instead of being waited out for one more second. This is the
+ *  poll-until-the-keys-are-there pattern `provisioning.instructions.md` prescribes for
+ *  every non-resource endpoint, applied where the waiting already happens.
+ *
+ *  `auth` defaults to factory admin, which is what a guest being provisioned for the
+ *  first time has. A machine past that point needs its own credentials passed in. */
+export async function waitForDeviceModeApi(
+	httpPort: number,
+	timeoutMs: number = 60_000,
+	auth: string = FACTORY_AUTH_HEADER,
+): Promise<void> {
 	const deadline = Date.now() + timeoutMs;
+	let lastBody = "";
 	while (Date.now() < deadline) {
 		try {
-			const { status } = await restGet(
+			const { status, body } = await restGet(
 				`http://127.0.0.1:${httpPort}/rest/system/device-mode`,
 				auth,
 				3000,
 			);
 
 			if (status >= 200 && status < 300) {
-				return;
+				if (isDeviceModeBody(body)) return;
+				// Answering, but not with device-mode yet — keep waiting rather than
+				// handing the caller a body it will throw on.
+				lastBody = body;
 			}
 
 			if (status === 401) {
@@ -176,7 +238,11 @@ export async function waitForDeviceModeApi(httpPort: number, timeoutMs: number =
 		await Bun.sleep(1000);
 	}
 
-	throw new QuickCHRError("BOOT_TIMEOUT", `Device-mode API did not become ready on port ${httpPort}`);
+	throw new QuickCHRError(
+		"BOOT_TIMEOUT",
+		`Device-mode API did not become ready on port ${httpPort}` +
+		(lastBody ? ` (last response was not device-mode data: ${lastBody.slice(0, 200)})` : ""),
+	);
 }
 
 /**
@@ -189,7 +255,11 @@ export async function waitForDeviceModeApi(httpPort: number, timeoutMs: number =
  * Uses restPost (node:http + agent:false) to bypass Bun's connection pool.
  * The 300s timeout is a safety limit — the caller is expected to kill QEMU well before then.
  */
-export function startDeviceModeUpdate(httpPort: number, options: ResolvedDeviceModeOptions): Promise<{ status: number; body: string }> {
+export function startDeviceModeUpdate(
+	httpPort: number,
+	options: ResolvedDeviceModeOptions,
+	auth: string = FACTORY_AUTH_HEADER,
+): Promise<{ status: number; body: string }> {
 	if (!shouldApplyDeviceMode(options)) {
 		return Promise.resolve({ status: 200, body: "" });
 	}
@@ -200,7 +270,6 @@ export function startDeviceModeUpdate(httpPort: number, options: ResolvedDeviceM
 		payload[name] = value;
 	}
 
-	const auth = `Basic ${btoa("admin:")}`;
 	return restPost(
 		`http://127.0.0.1:${httpPort}/rest/system/device-mode/update`,
 		auth,
@@ -209,8 +278,10 @@ export function startDeviceModeUpdate(httpPort: number, options: ResolvedDeviceM
 	);
 }
 
-export async function readDeviceMode(httpPort: number): Promise<Record<string, string>> {
-	const auth = `Basic ${btoa("admin:")}`;
+export async function readDeviceMode(
+	httpPort: number,
+	auth: string = FACTORY_AUTH_HEADER,
+): Promise<Record<string, string>> {
 	const { status, body } = await restGet(
 		`http://127.0.0.1:${httpPort}/rest/system/device-mode`,
 		auth,
@@ -281,3 +352,71 @@ export function verifyDeviceMode(
 		actual,
 	};
 }
+
+/** The `quickchr set` flags that would reproduce this selection, shell-quoted.
+ *
+ *  Rendered from the *resolved* options, not the raw ones, so the command it prints
+ *  is the command that was actually going to run — `mode: "auto"` comes out as the
+ *  `rose` it resolves to rather than as an alias the reader has to expand.
+ *
+ *  Quoted because `resolveDeviceModeOptions()` deliberately passes unknown modes and
+ *  features through for forward compatibility (it warns, RouterOS validates), so a
+ *  value with a space or a `;` in it reaches this function intact. Unquoted, the
+ *  advertised command would silently become a different command. Ordinary values are
+ *  returned unquoted, so the common case still reads like something a person typed. */
+export function formatDeviceModeFlags(options: ResolvedDeviceModeOptions): string {
+	if (options.skip) return "";
+	const parts: string[] = [];
+	if (options.mode) parts.push(`--device-mode ${shellQuote(options.mode)}`);
+	const enable = Object.entries(options.features).filter(([, v]) => v === "yes").map(([k]) => k);
+	const disable = Object.entries(options.features).filter(([, v]) => v === "no").map(([k]) => k);
+	if (enable.length > 0) parts.push(`--device-mode-enable ${shellQuote(enable.sort().join(","))}`);
+	if (disable.length > 0) parts.push(`--device-mode-disable ${shellQuote(disable.sort().join(","))}`);
+	return parts.join(" ");
+}
+
+/** What a device-mode update would change, read against the guest's current record.
+ *
+ *  Only the differences — a change that costs a power cycle should say which settings
+ *  it is buying, and `expected == actual` rows are noise. Empty means nothing would
+ *  move, which is the caller's cue that no power cycle is needed. */
+export function describeDeviceModeChange(
+	options: ResolvedDeviceModeOptions,
+	actual: Record<string, string>,
+): string[] {
+	// `verifyDeviceMode` stays the single judge of what counts as a mismatch — only the
+	// key is read back out of its message, and the values come from the maps it returns.
+	const { expected, mismatches } = verifyDeviceMode(options, actual);
+	const changed = new Set(mismatches.map((mismatch) => mismatch.split(":")[0]));
+	return Object.entries(expected)
+		.filter(([key]) => changed.has(key))
+		.map(([key, want]) => `${key}: ${actual[key] ?? "(unset)"} -> ${want}`);
+}
+
+/** Fold an applied device-mode selection into what `machine.json` already records.
+ *
+ *  `setDeviceMode()` used to overwrite `state.deviceMode` with the request, so
+ *  `set <name> --device-mode-enable container` on a machine provisioned with
+ *  `ipsec=yes` left the record claiming ipsec had never been asked for. The guest
+ *  still had it: device-mode updates are cumulative, and only the settings named in
+ *  a request move. The record has to be cumulative too, or it describes a machine
+ *  that does not exist — and `classifyProvisioningRequest()` reads it. */
+export function mergeDeviceModeOptions(
+	current: DeviceModeOptions | undefined,
+	applied: ResolvedDeviceModeOptions,
+): DeviceModeOptions {
+	if (applied.skip) return current ?? {};
+	const enable = new Set(normalizeFeatureList(current?.enable));
+	const disable = new Set(normalizeFeatureList(current?.disable));
+	for (const [feature, value] of Object.entries(applied.features)) {
+		// A feature only ever sits on one side: the newest instruction for it wins.
+		enable.delete(feature);
+		disable.delete(feature);
+		(value === "yes" ? enable : disable).add(feature);
+	}
+	return {
+		mode: applied.mode ?? current?.mode,
+		enable: enable.size > 0 ? [...enable].sort() : undefined,
+		disable: disable.size > 0 ? [...disable].sort() : undefined,
+	};
+}

package/src/lib/diagnostics.ts

@@ -54,18 +54,22 @@ export type BootProbeOutcome =
 	| "reset"
 	/** Connect or response exceeded the per-probe budget — socket hung. */
 	| "probe-timeout"
-	/** 401/403 — REST answered; auth layer is up. */
+	/** 401/403 from REST, or a login `!trap` from the native API — the service
+	 *  answered and refused the credentials; its auth layer is up. */
 	| "unauthorized"
 	/** 2xx but not the expected `board-name` singleton — REST still initializing. */
 	| "wrong-body"
 	/** Any other HTTP status. */
 	| "http-error"
-	/** 2xx with the expected body. */
+	/** 2xx with the expected body, or a native-API login `!done`. */
 	| "ready"
 	/** Anything unclassified — `detail` carries the raw text. */
 	| "other";
 
 export interface BootProbeStats {
+	/** Which readiness probe ran — REST by default, the native-API login for a guest
+	 *  without REST (#182). Absent means REST. */
+	kind?: "rest" | "api";
 	/** Total probe attempts made. */
 	attempts: number;
 	/** Attempt count per outcome. */
@@ -90,9 +94,11 @@ export function classifyProbeError(err: unknown): { outcome: BootProbeOutcome; d
 	const message = err instanceof Error ? err.message : String(err);
 	if (code === "ECONNREFUSED") return { outcome: "refused", detail: code };
 	if (code === "ECONNRESET" || code === "EPIPE") return { outcome: "reset", detail: code };
-	if (code === "ETIMEDOUT" || message.includes("restGet timeout")) {
+	if (code === "ETIMEDOUT" || message.includes("restGet timeout") || message.includes("apiLogin timeout")) {
 		return { outcome: "probe-timeout", detail: code ?? "probe deadline" };
 	}
+	// apiLogin(): slirp accepted, then the guest side closed before any reply.
+	if (message === "closed before reply") return { outcome: "reset", detail: message };
 	return { outcome: "other", detail: code ? `${code}: ${message}` : message };
 }
 
@@ -123,9 +129,10 @@ export function summarizeBootProbe(stats: BootProbeStats): string {
 		.sort((a, b) => b[1] - a[1])
 		.map(([k, v]) => `${k}=${v}`)
 		.join(" ");
+	const answer = stats.kind === "api" ? "API reply" : "HTTP response";
 	const reachedHttp = stats.firstHttpAtMs === null
-		? "forwarded port never produced an HTTP response"
-		: `first HTTP response at ${Math.round(stats.firstHttpAtMs / 1000)}s`;
+		? `forwarded port never produced an ${answer}`
+		: `first ${answer} at ${Math.round(stats.firstHttpAtMs / 1000)}s`;
 	const last = stats.last
 		? `last: ${stats.last.outcome}${stats.last.detail ? ` (${stats.last.detail})` : ""} at ${Math.round(stats.last.atMs / 1000)}s`
 		: "";
@@ -673,7 +680,7 @@ export async function captureBootFailure(ctx: BootFailureContext): Promise<BootF
 			lines.push(`Preceding credential transition: ${ctx.trigger.credentialTransition}`);
 		}
 	}
-	if (ctx.probe) lines.push(`REST probe: ${summarizeBootProbe(ctx.probe)}`);
+	if (ctx.probe) lines.push(`${ctx.probe.kind === "api" ? "API login" : "REST"} probe: ${summarizeBootProbe(ctx.probe)}`);
 	lines.push(`QEMU process: ${record.host.qemuProcess}`);
 	if (record.hostfwd) lines.push(`hostfwd 127.0.0.1:${record.hostfwd.port}: ${record.hostfwd.tcpConnect}`);
 	if (forwardProbe) lines.push(`slirp per-port: ${forwardProbe.summary}`);

package/src/lib/disk.ts

@@ -12,11 +12,12 @@
  *  - {@link formatSnapshotTable} — render snapshot list as a human-readable ANSI table
  */
 
-import { join } from "node:path";
-import { existsSync, unlinkSync } from "node:fs";
+import { basename, join } from "node:path";
+import { copyFileSync, existsSync, rmSync, unlinkSync } from "node:fs";
 import type { BootDiskFormat, SnapshotInfo } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
 import { requireQemuImg } from "./platform.ts";
+import { renameWithRetry } from "./rename.ts";
 
 const DISK_SIZE_RE = /^\d+[KMGT]?$/i;
 
@@ -25,6 +26,8 @@ export interface DiskInfo {
 	virtualSize: number;
 	actualSize: number;
 	filename: string;
+	/** Set when the image depends on another file (a qcow2 backing chain). */
+	backingFilename?: string;
 }
 
 /** True when a disk size string is valid for qemu-img (e.g. 512M, 1G, 2048). */
@@ -139,34 +142,58 @@ export async function getDiskInfo(path: string): Promise<DiskInfo> {
 		virtualSize: info["virtual-size"],
 		actualSize: info["actual-size"],
 		filename: info.filename,
+		backingFilename: info["backing-filename"],
 	};
 }
 
+/** The boot format a machine record implies. Records from before `bootDiskFormat`
+ *  existed only had `bootSize`, which always meant qcow2. */
+export function bootDiskFormatOf(state: { bootDiskFormat?: BootDiskFormat; bootSize?: string }): BootDiskFormat {
+	return state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw");
+}
+
+/** Where a machine's boot disk lives: `disk.img` for raw, `boot.qcow2` for qcow2. */
+export function bootDiskPath(machineDir: string, format: BootDiskFormat): string {
+	return join(machineDir, format === "qcow2" ? "boot.qcow2" : "disk.img");
+}
+
 /**
- * Prepare the boot disk for a machine.
- * If bootSize is specified, converts the raw disk.img to boot.qcow2 and resizes it.
- * Otherwise returns the raw disk.img as-is.
+ * Write a machine's boot disk from a factory raw image, replacing any existing one.
+ *
+ * The disk is built under a `.tmp` name and renamed into place only once complete, so
+ * an interrupted copy or conversion never leaves a file the next start would accept.
+ * qcow2 is converted straight from `sourceImg` (normally the shared cache image) and
+ * checked to be standalone: no machine-local raw copy is kept, and no guest disk
+ * depends on the cache through a backing chain.
  */
-export async function prepareBootDisk(
+export async function writeBootDisk(
 	machineDir: string,
+	sourceImg: string,
+	format: BootDiskFormat,
 	bootSize?: string,
-	bootDiskFormat?: BootDiskFormat,
 ): Promise<{ path: string; format: BootDiskFormat }> {
-	const format: BootDiskFormat = bootDiskFormat ?? (bootSize ? "qcow2" : "raw");
-	const rawPath = join(machineDir, "disk.img");
-
-	if (format === "raw") {
-		return { path: rawPath, format: "raw" };
-	}
-
-	const qcow2Path = join(machineDir, "boot.qcow2");
-	if (!existsSync(qcow2Path)) {
-		await convertRawToQcow2(rawPath, qcow2Path);
-	}
-	if (bootSize) {
-		await resizeQcow2(qcow2Path, bootSize);
+	const path = bootDiskPath(machineDir, format);
+	const tmpPath = `${path}.tmp`;
+	rmSync(tmpPath, { force: true });
+	try {
+		if (format === "raw") {
+			copyFileSync(sourceImg, tmpPath);
+		} else {
+			await convertRawToQcow2(sourceImg, tmpPath);
+			if (bootSize) await resizeQcow2(tmpPath, bootSize);
+			const info = await getDiskInfo(tmpPath);
+			if (info.format !== "qcow2" || info.backingFilename) {
+				throw new QuickCHRError(
+					"PROCESS_FAILED",
+					`Converted boot disk is not a standalone qcow2 (format=${info.format}${info.backingFilename ? `, backing=${info.backingFilename}` : ""})`,
+				);
+			}
+		}
+		renameWithRetry(tmpPath, path);
+	} finally {
+		rmSync(tmpPath, { force: true });
 	}
-	return { path: qcow2Path, format: "qcow2" };
+	return { path, format };
 }
 
 /**
@@ -186,24 +213,53 @@ export async function prepareExtraDisks(
 	return results;
 }
 
-/** Ensure disk artifacts referenced by machine state exist on disk.
- *  Used both for new-machine creation and to heal older add()-created states
- *  that predate eager disk materialization. */
+export interface DiskSources {
+	/** True once the guest has booted. Its disks then hold guest state, so a missing one
+	 *  is an error: rebuilding it from the factory image would quietly reset the router. */
+	booted: boolean;
+	/** The factory raw image a missing boot disk of a never-booted machine is built from.
+	 *  Called only when it is needed. */
+	factoryImage?: () => Promise<string>;
+}
+
+function missingDiskError(machineDir: string, path: string): QuickCHRError {
+	const name = basename(machineDir);
+	return new QuickCHRError(
+		"MACHINE_NOT_FOUND",
+		`Disk image not found for "${name}": ${path}. The machine has booted before, so quickchr will not rebuild it from the factory image — that would silently reset the router. Restore the file, or run 'quickchr clean ${name}' to reset it to factory.`,
+	);
+}
+
+/** Resolve the disks a machine record calls for, creating any that a never-booted
+ *  machine is still missing. New machines, and older add()-created states that predate
+ *  eager disk materialization, are built here; a booted machine's disks never are.
+ *
+ *  A qcow2 machine needs only `boot.qcow2`. Machines created before 0.5.1 also hold a
+ *  `disk.img`; it is unused once `boot.qcow2` exists, and is the conversion source for a
+ *  legacy never-booted state that has no `boot.qcow2` yet. */
 export async function ensureConfiguredDisks(
 	machineDir: string,
-	bootSize?: string,
-	extraDiskSizes?: string[],
-	bootDiskFormat?: BootDiskFormat,
+	bootSize: string | undefined,
+	extraDiskSizes: string[] | undefined,
+	bootDiskFormat: BootDiskFormat,
+	sources: DiskSources,
 ): Promise<{
 	bootDisk: { path: string; format: BootDiskFormat };
 	extraDisks?: { path: string; format: "qcow2" }[];
 }> {
-	const format: BootDiskFormat = bootDiskFormat ?? (bootSize ? "qcow2" : "raw");
-	const bootDisk = format === "raw"
-		? { path: join(machineDir, "disk.img"), format: "raw" as const }
-		: (existsSync(join(machineDir, "boot.qcow2"))
-			? { path: join(machineDir, "boot.qcow2"), format: "qcow2" as const }
-			: await prepareBootDisk(machineDir, bootSize, "qcow2"));
+	const bootPath = bootDiskPath(machineDir, bootDiskFormat);
+	let bootDisk = { path: bootPath, format: bootDiskFormat };
+	if (!existsSync(bootPath)) {
+		if (sources.booted) throw missingDiskError(machineDir, bootPath);
+		const legacyRaw = join(machineDir, "disk.img");
+		const source = bootDiskFormat === "qcow2" && existsSync(legacyRaw)
+			? legacyRaw
+			: await sources.factoryImage?.();
+		if (!source) {
+			throw new QuickCHRError("MACHINE_NOT_FOUND", `Disk image not found for "${basename(machineDir)}": ${bootPath}`);
+		}
+		bootDisk = await writeBootDisk(machineDir, source, bootDiskFormat, bootSize);
+	}
 
 	let extraDisks: { path: string; format: "qcow2" }[] | undefined;
 	if (extraDiskSizes && extraDiskSizes.length > 0) {
@@ -211,6 +267,7 @@ export async function ensureConfiguredDisks(
 		for (let i = 0; i < extraDiskSizes.length; i++) {
 			const diskPath = join(machineDir, `disk${i + 1}.qcow2`);
 			if (!existsSync(diskPath)) {
+				if (sources.booted) throw missingDiskError(machineDir, diskPath);
 				await createQcow2Disk(diskPath, extraDiskSizes[i] as string);
 			}
 			extraDisks.push({ path: diskPath, format: "qcow2" });

package/src/lib/download.ts

@@ -46,11 +46,12 @@
  * a transfer; it does not change the transport).
  */
 
-import { unlinkSync, existsSync, renameSync } from "node:fs";
+import { unlinkSync, existsSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { QuickCHRError } from "./types.ts";
 import { fetchResilient } from "./net.ts";
 import { createLogger, type ProgressLogger } from "./log.ts";
+import { renameWithRetry } from "./rename.ts";
 
 /**
  * Throughput to assume when budgeting a COLD download from MikroTik, in bytes
@@ -257,7 +258,7 @@ export async function downloadToFile(
 			// so this is a same-filesystem move and the artifact appears at its final
 			// path atomically. Copying would re-write every byte (52 MB for the
 			// largest artifact) for no benefit.
-			renameSync(partPath, destPath);
+			renameWithRetry(partPath, destPath);
 			log.status(`  Saved (${describeTransfer(outcome)})`);
 			return outcome;
 		} catch (e) {