@tikoci/quickchr 0.5.0 → 0.5.2

package/src/lib/cache.ts

@@ -1,20 +1,27 @@
 /**
- * Cache retention policy for downloaded CHR images.
+ * Cache retention policy for downloaded CHR images and package archives.
  *
- * - Default cap: 2 GB total cache size (size-based eviction).
+ * - Default cap: 2 GB total cache size (size-based eviction), counting images, package
+ *   archives with their extractions, and interrupted downloads.
  * - Eviction order: oldest RouterOS version first, mtime tiebreaker.
  * - Never evicts an image referenced by any machine (running or stopped).
  * - Callers can pin extra versions via `protectVersions` (e.g. current long-term).
  */
 
-import { existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { getCacheDir, loadAllMachines } from "./state.ts";
+import { directorySize, getCacheDir, loadAllMachines } from "./state.ts";
+import { isPidAlive, liveLeases, pinnedEntries, withStorageLock } from "./storage-lease.ts";
 import { chrImageBasename, compareRouterOsVersion, isValidVersion } from "./versions.ts";
 import { QuickCHRError, type Arch } from "./types.ts";
 
 export const DEFAULT_CACHE_MAX_BYTES = 2 * 1024 * 1024 * 1024;
 
+/** Free space quickchr keeps on the data dir's filesystem beyond what an operation
+ *  writes — the `storage-reserve` setting's default. Lives here beside the cache cap
+ *  so settings.ts can read both without importing storage.ts (which imports settings). */
+export const DEFAULT_STORAGE_RESERVE_BYTES = 2 * 1024 * 1024 * 1024;
+
 /** Parse a human size string (NK/NM/NG/NT, IEC binary, case-insensitive) to bytes. */
 export function parseSizeString(s: string): number {
 	const m = s.match(/^(\d+(?:\.\d+)?)([KMGT]?)i?B?$/i);
@@ -25,6 +32,11 @@ export function parseSizeString(s: string): number {
 	return Math.floor(n * (mult[unit] ?? 1));
 }
 
+/** "1 entry" / "3 entries". */
+export function countEntries(n: number): string {
+	return `${n} ${n === 1 ? "entry" : "entries"}`;
+}
+
 /** Format a byte count as a human size (IEC binary), matching cache list's display. */
 export function formatSizeBytes(b: number): string {
 	if (b >= 1024 ** 3) return `${(b / 1024 ** 3).toFixed(2)} GiB`;
@@ -33,34 +45,72 @@ export function formatSizeBytes(b: number): string {
 	return `${b} B`;
 }
 
+/** What a cache entry is. `packages` is one archive + its extraction, counted and
+ *  deleted together: the extraction is only a cache hit while the archive it was
+ *  made from is still there. `partial` is an interrupted download or extraction. */
+export type CacheEntryKind = "image" | "image-zip" | "packages" | "partial";
+
 export interface CacheEntry {
+	/** The entry's main file or directory. */
 	path: string;
+	/** Everything deleting this entry removes. */
+	paths: string[];
 	basename: string;
+	kind: CacheEntryKind;
 	version: string;
 	arch: Arch | "unknown";
 	sizeBytes: number;
+	/** Last write, or last use: a cache hit touches the image or package archive. */
 	mtimeMs: number;
 	inUse: boolean;
 }
 
+export interface CacheInventory {
+	entries: CacheEntry[];
+	/** Bytes in files quickchr did not write. Listed, never deleted. */
+	unmanagedBytes: number;
+}
+
 export interface PruneOptions {
 	cacheDir?: string;
 	maxSizeBytes?: number;
 	maxAgeMs?: number;
 	olderThan?: string;
 	protectVersions?: string[];
+	/** Evict eligible entries, oldest version first, until this many bytes are gone. */
+	reclaimBytes?: number;
+	/** Keep entries written or used this recently. Pins are what protect a reader; this
+	 *  also spares what a just-finished `cache add` fetched for a later process. */
+	skipRecentMs?: number;
+	/** Leave these entries alone (a reclaim loop's earlier failed deletes). */
+	skipEntries?: string[];
 	dryRun?: boolean;
 }
 
 export interface PruneResult {
 	evicted: CacheEntry[];
 	kept: CacheEntry[];
+	/** Entries chosen for eviction whose delete failed. Neither evicted nor kept, and not
+	 *  counted in `freedBytes`. */
+	failed: Array<{ entry: CacheEntry; error: string }>;
+	/** Logical size of what was deleted. Not a measured change in free space: sparse
+	 *  files, clones and concurrent writers all make the two differ. */
 	freedBytes: number;
 	reasons: Record<string, string>;
 }
 
+/** Anything an automatic eviction leaves alone because another operation may be using
+ *  it right now — a create converting from the image, a first boot installing packages. */
+export const RECENT_USE_MS = 30 * 60 * 1000;
+
 /** Parse a cached file basename into version + arch. Returns "unknown" parts when unparseable. */
 export function parseCacheBasename(basename: string): { version: string; arch: Arch | "unknown" } {
+	const packages = basename.match(/^(?:all_)?packages-(x86|arm64)-(.+?)(?:\.zip)?$/);
+	if (packages) {
+		const version = packages[2] ?? "unknown";
+		return { version: isValidVersion(version) ? version : "unknown", arch: packages[1] as Arch };
+	}
+
 	// Strip recognized cache extensions (.img, .img.zip).
 	let stem = basename;
 	if (stem.endsWith(".img.zip")) stem = stem.slice(0, -".img.zip".length);
@@ -76,6 +126,9 @@ export function parseCacheBasename(basename: string): { version: string; arch: A
 	return { version, arch };
 }
 
+/** Cache names machines still need. Every machine keeps its factory image: `clean` and a
+ *  failed first boot's rollback rebuild from it. A machine keeps its package cache only
+ *  until its first-boot provisioning is stamped done. */
 function inUseSet(): Set<string> {
 	const set = new Set<string>();
 	let machines: ReturnType<typeof loadAllMachines>;
@@ -88,16 +141,24 @@ function inUseSet(): Set<string> {
 		if (!m.version || !m.arch) continue;
 		set.add(`${chrImageBasename(m.version, m.arch)}.img`);
 		set.add(`${chrImageBasename(m.version, m.arch)}.img.zip`);
+		const wantsPackages = m.installAllPackages === true || (m.packages?.length ?? 0) > 0;
+		if (wantsPackages && !m.provisioning) set.add(`packages-${m.arch}-${m.version}`);
 	}
 	return set;
 }
 
-/** List cache entries with parsed metadata and in-use status. */
-export function listCacheEntries(cacheDir?: string): CacheEntry[] {
+/** Inventory the cache: every entry quickchr manages, plus the bytes it does not.
+ *  An entry is in use when a machine needs it or a live operation has pinned it. */
+export function cacheInventory(cacheDir?: string, pins: Set<string> = pinnedEntries()): CacheInventory {
 	const dir = cacheDir ?? getCacheDir();
-	if (!existsSync(dir)) return [];
+	if (!existsSync(dir)) return { entries: [], unmanagedBytes: 0 };
 	const used = inUseSet();
-	const out: CacheEntry[] = [];
+	for (const pin of pins) used.add(pin);
+	const now = Date.now();
+	const entries: CacheEntry[] = [];
+	const packageGroups = new Map<string, CacheEntry>();
+	let unmanagedBytes = 0;
+
 	for (const name of readdirSync(dir)) {
 		const full = join(dir, name);
 		let stat: ReturnType<typeof statSync>;
@@ -106,20 +167,94 @@ export function listCacheEntries(cacheDir?: string): CacheEntry[] {
 		} catch {
 			continue;
 		}
-		if (!stat.isFile()) continue;
-		if (!name.endsWith(".img") && !name.endsWith(".img.zip")) continue;
+		const sizeBytes = stat.isDirectory() ? directorySize(full) : stat.size;
+
+		// Only exact quickchr names are managed: `all_packages-<arch>-<ver>.zip` (a file)
+		// and `packages-<arch>-<ver>` (a directory), with a real RouterOS version.
+		const packages = name.match(/^(all_)?packages-(x86|arm64)-(.+?)(\.zip)?$/);
+		const isPackageArtifact = packages !== null && isValidVersion(packages[3] ?? "") &&
+			(packages[1] && packages[4] ? stat.isFile() : !packages[1] && !packages[4] && stat.isDirectory());
+		if (packages && isPackageArtifact) {
+			const key = `packages-${packages[2]}-${packages[3]}`;
+			const group = packageGroups.get(key);
+			if (group) {
+				group.paths.push(full);
+				group.sizeBytes += sizeBytes;
+				group.mtimeMs = Math.max(group.mtimeMs, stat.mtimeMs);
+			} else {
+				const { version, arch } = parseCacheBasename(key);
+				packageGroups.set(key, {
+					path: join(dir, key),
+					paths: [full],
+					basename: key,
+					kind: "packages",
+					version,
+					arch,
+					sizeBytes,
+					mtimeMs: stat.mtimeMs,
+					inUse: used.has(key),
+				});
+			}
+			continue;
+		}
+
+		// `<target>.<pid>-<id>.part` (download.ts) is live while its writer is.
+		// `.quickchr-image-*` / `.quickchr-packages-*` extraction dirs have no owner
+		// recorded, so they count as live for RECENT_USE_MS after their last write.
+		const part = name.match(/^(.+)\.(\d+)-[0-9a-f]+\.part$/);
+		const extraction = stat.isDirectory() && (name.startsWith(".quickchr-image-") || name.startsWith(".quickchr-packages-"));
+		if ((part && isManagedDownloadTarget(part[1] ?? "")) || extraction) {
+			const { version, arch } = parseCacheBasename(part?.[1] ?? name);
+			entries.push({
+				path: full,
+				paths: [full],
+				basename: name,
+				kind: "partial",
+				version,
+				arch,
+				sizeBytes,
+				mtimeMs: stat.mtimeMs,
+				inUse: part ? isPidAlive(Number(part[2])) : now - stat.mtimeMs < RECENT_USE_MS,
+			});
+			continue;
+		}
+
+		const kind: CacheEntryKind | undefined = !stat.isFile()
+			? undefined
+			: name.endsWith(".img.zip") ? "image-zip" : name.endsWith(".img") ? "image" : undefined;
 		const { version, arch } = parseCacheBasename(name);
-		out.push({
+		if (!kind || version === "unknown") {
+			unmanagedBytes += sizeBytes;
+			continue;
+		}
+		entries.push({
 			path: full,
+			paths: [full],
 			basename: name,
+			kind,
 			version,
 			arch,
-			sizeBytes: stat.size,
+			sizeBytes,
 			mtimeMs: stat.mtimeMs,
 			inUse: used.has(name),
 		});
 	}
-	return out;
+
+	entries.push(...packageGroups.values());
+	return { entries, unmanagedBytes };
+}
+
+/** True for the files download.ts writes into the cache: an image ZIP or an
+ *  all-packages ZIP, with a real RouterOS version. Anything else is not ours. */
+function isManagedDownloadTarget(name: string): boolean {
+	if (name.endsWith(".img.zip")) return parseCacheBasename(name).version !== "unknown";
+	const packages = name.match(/^all_packages-(x86|arm64)-(.+)\.zip$/);
+	return packages !== null && isValidVersion(packages[2] ?? "");
+}
+
+/** List cache entries with parsed metadata and in-use status. */
+export function listCacheEntries(cacheDir?: string): CacheEntry[] {
+	return cacheInventory(cacheDir).entries;
 }
 
 function compareVersionsSafe(a: string, b: string): number {
@@ -140,11 +275,24 @@ function compareVersionsSafe(a: string, b: string): number {
  *   - `maxSizeBytes`: total bytes exceed cap
  *   - `maxAgeMs`: any entry older than threshold
  *   - `olderThan`: any entry's parsed version older than threshold
+ *   - `reclaimBytes`: evict until this many bytes are gone
  *
- * In-use entries and `protectVersions` entries are never evicted.
+ * In-use entries, `protectVersions` entries and (with `skipRecentMs`) recently used
+ * entries are never evicted. Interrupted downloads go first, then oldest version.
  */
 export function pruneCache(opts: PruneOptions = {}): PruneResult {
-	const entries = listCacheEntries(opts.cacheDir);
+	// A dry run deletes nothing, so it reads the pins without taking the lock.
+	return opts.dryRun ? pruneCacheUnderLock(opts, pinnedEntries()) : withStorageLock(() => pruneCacheUnderLock(opts));
+}
+
+/** `pruneCache` for a caller already holding the storage lock (storage.ts admission).
+ *  Entries pinned by a live lease count as in use. */
+export function pruneCacheUnderLock(
+	opts: PruneOptions = {},
+	pins: Set<string> = new Set(liveLeases().flatMap((lease) => lease.pins)),
+): PruneResult {
+	const entries = cacheInventory(opts.cacheDir, pins).entries;
+	const skip = new Set(opts.skipEntries ?? []);
 	const protect = new Set(opts.protectVersions ?? []);
 	const dryRun = opts.dryRun ?? false;
 	const now = Date.now();
@@ -152,6 +300,7 @@ export function pruneCache(opts: PruneOptions = {}): PruneResult {
 	const reasons: Record<string, string> = {};
 	const evicted: CacheEntry[] = [];
 	const kept: CacheEntry[] = [];
+	const failed: PruneResult["failed"] = [];
 
 	const protectedEntries: CacheEntry[] = [];
 	const candidates: CacheEntry[] = [];
@@ -159,27 +308,44 @@ export function pruneCache(opts: PruneOptions = {}): PruneResult {
 	for (const e of entries) {
 		if (e.inUse) {
 			protectedEntries.push(e);
-			continue;
-		}
-		if (protect.has(e.version)) {
+			reasons[e.basename] = e.kind === "partial" ? "in progress" : "in use";
+		} else if (protect.has(e.version)) {
 			protectedEntries.push(e);
-			continue;
+			reasons[e.basename] = `protected (version ${e.version})`;
+		} else if (skip.has(e.basename)) {
+			protectedEntries.push(e);
+			reasons[e.basename] = "skipped";
+		} else if (opts.skipRecentMs !== undefined && now - e.mtimeMs < opts.skipRecentMs) {
+			protectedEntries.push(e);
+			reasons[e.basename] = "used recently";
+		} else {
+			candidates.push(e);
 		}
-		candidates.push(e);
 	}
 
 	candidates.sort((a, b) => {
+		const partial = Number(b.kind === "partial") - Number(a.kind === "partial");
+		if (partial !== 0) return partial;
 		const v = compareVersionsSafe(a.version, b.version);
 		if (v !== 0) return v;
 		return a.mtimeMs - b.mtimeMs;
 	});
 
-	const evict = (e: CacheEntry, reason: string) => {
-		evicted.push(e);
-		reasons[e.basename] = reason;
+	/** True when the entry is gone (or, in a dry run, would be). */
+	const evict = (e: CacheEntry, reason: string): boolean => {
 		if (!dryRun) {
-			try { unlinkSync(e.path); } catch { /* best-effort */ }
+			try {
+				for (const path of e.paths) rmSync(path, { recursive: true, force: true });
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				failed.push({ entry: e, error: message });
+				reasons[e.basename] = `delete failed: ${message}`;
+				return false;
+			}
 		}
+		evicted.push(e);
+		reasons[e.basename] = reason;
+		return true;
 	};
 
 	const remaining: CacheEntry[] = [];
@@ -212,31 +378,34 @@ export function pruneCache(opts: PruneOptions = {}): PruneResult {
 	}
 
 	const keptSoFar: CacheEntry[] = [...remainingAfterAge];
+	const totalSize = (es: CacheEntry[]) => es.reduce((s, x) => s + x.sizeBytes, 0);
 
 	if (opts.maxSizeBytes !== undefined) {
 		const cap = opts.maxSizeBytes;
-		const totalSize = (es: CacheEntry[]) => es.reduce((s, x) => s + x.sizeBytes, 0);
-		let total = totalSize(protectedEntries) + totalSize(keptSoFar);
+		let total = totalSize(protectedEntries) + totalSize(keptSoFar) + totalSize(failed.map((f) => f.entry));
 		while (total > cap && keptSoFar.length > 0) {
 			const victim = keptSoFar.shift();
 			if (!victim) break;
-			evict(victim, `size cap ${cap} exceeded (oldest version)`);
-			total -= victim.sizeBytes;
+			if (evict(victim, `size cap ${formatSizeBytes(cap)} exceeded (oldest version)`)) total -= victim.sizeBytes;
 		}
 	}
 
-	for (const e of protectedEntries) {
-		kept.push(e);
-		if (e.inUse) reasons[e.basename] ??= "in use";
-		else reasons[e.basename] ??= `protected (version ${e.version})`;
+	if (opts.reclaimBytes !== undefined) {
+		const target = opts.reclaimBytes;
+		while (totalSize(evicted) < target && keptSoFar.length > 0) {
+			const victim = keptSoFar.shift();
+			if (!victim) break;
+			evict(victim, `reclaimed for space (oldest version)`);
+		}
 	}
+
+	for (const e of protectedEntries) kept.push(e);
 	for (const e of keptSoFar) {
 		kept.push(e);
 		reasons[e.basename] ??= "kept";
 	}
 
-	const freedBytes = evicted.reduce((s, e) => s + e.sizeBytes, 0);
-	return { evicted, kept, freedBytes, reasons };
+	return { evicted, kept, failed, freedBytes: totalSize(evicted), reasons };
 }
 
 /**
@@ -249,21 +418,34 @@ export function autoPruneIfOverCap(opts: { logger?: (msg: string) => void; cache
 		const entries = listCacheEntries(opts.cacheDir);
 		const total = entries.reduce((s, e) => s + e.sizeBytes, 0);
 		if (total <= cap) {
-			return { evicted: [], kept: entries, freedBytes: 0, reasons: {} };
+			return { evicted: [], kept: entries, failed: [], freedBytes: 0, reasons: {} };
 		}
 		const result = pruneCache({
 			cacheDir: opts.cacheDir,
 			maxSizeBytes: cap,
 			protectVersions: opts.protectVersions,
+			skipRecentMs: RECENT_USE_MS,
 		});
-		if (opts.logger && result.evicted.length > 0) {
-			opts.logger(`cache: evicted ${result.evicted.length} image(s), freed ${(result.freedBytes / 1024 / 1024).toFixed(1)} MiB`);
+		if (opts.logger) {
+			for (const line of describePrune(result)) opts.logger(line);
 		}
 		return result;
 	} catch (e) {
 		if (opts.logger) {
 			opts.logger(`cache: auto-prune skipped: ${e instanceof Error ? e.message : String(e)}`);
 		}
-		return { evicted: [], kept: [], freedBytes: 0, reasons: {} };
+		return { evicted: [], kept: [], failed: [], freedBytes: 0, reasons: {} };
+	}
+}
+
+/** One-line log summary of an eviction, naming what went, plus one line per failure. */
+export function describePrune(result: PruneResult): string[] {
+	const lines: string[] = [];
+	if (result.evicted.length > 0) {
+		lines.push(`cache: evicted ${result.evicted.map((e) => e.basename).join(", ")} — freed ${formatSizeBytes(result.freedBytes)}`);
+	}
+	for (const { entry, error } of result.failed) {
+		lines.push(`cache: could not delete ${entry.basename}: ${error}`);
 	}
+	return lines;
 }

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) {