@tikoci/quickchr 0.5.0 → 0.5.2

package/src/lib/images.ts

@@ -2,7 +2,7 @@
  * Image download, ZIP extraction, and cache management.
  */
 
-import { existsSync, copyFileSync, mkdtempSync, readdirSync, renameSync, rmSync, unlinkSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, rmSync, unlinkSync, utimesSync } from "node:fs";
 import { join, basename } from "node:path";
 import type { Arch } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
@@ -11,7 +11,18 @@ import { downloadToFile } from "./download.ts";
 import { getCacheDir, ensureDir } from "./state.ts";
 import { createLogger, type ProgressLogger } from "./log.ts";
 import { extractZip } from "./zip.ts";
-import { assertSufficientQuickchrStorage } from "./storage.ts";
+import { admitStorage, STORAGE_ESTIMATES } from "./storage.ts";
+import { renameWithRetry } from "./rename.ts";
+
+/** A cache hit is a use: bump the mtime so automatic eviction counts the entry as
+ *  recently used while this operation reads it (#199). Best-effort: a read-only cache
+ *  still works. */
+export function touchCacheEntry(path: string): void {
+	try {
+		const now = new Date();
+		utimesSync(path, now, now);
+	} catch { /* read-only cache */ }
+}
 
 function finalizeExtractedImage(zipPath: string, imgPath: string): string {
 	if (existsSync(imgPath) && existsSync(zipPath)) {
@@ -118,7 +129,7 @@ export async function extractImage(
 		if (!(await isUsableCachedImage(extractedPath))) {
 			throw new QuickCHRError("PROCESS_FAILED", `Extracted CHR image is incomplete or invalid: ${expected}`);
 		}
-		renameSync(extractedPath, imgPath);
+		renameWithRetry(extractedPath, imgPath);
 	} finally {
 		rmSync(tempDir, { recursive: true, force: true });
 	}
@@ -138,21 +149,29 @@ export async function ensureCachedImage(
 	if (await isUsableCachedImage(imgPath)) {
 		const log = logger ?? createLogger();
 		log.status(`  Using cached image: ${chrImageBasename(version, arch)}`);
+		touchCacheEntry(imgPath);
 		return imgPath;
 	}
 	if (existsSync(imgPath)) unlinkSync(imgPath);
-	assertSufficientQuickchrStorage(`cache CHR ${version} (${arch})`);
-	const zipPath = await downloadImage(version, arch, cacheDir, logger);
-	const extractedImgPath = await extractImage(zipPath, cacheDir, logger);
-	return finalizeExtractedImage(zipPath, extractedImgPath);
-}
-
-/** Copy a cached image to a machine's working directory as disk.img. */
-export function copyImageToMachine(cachedImgPath: string, machineDir: string): string {
-	ensureDir(machineDir);
-	const dest = join(machineDir, "disk.img");
-	copyFileSync(cachedImgPath, dest);
-	return dest;
+	const log = logger ?? createLogger();
+	const base = chrImageBasename(version, arch);
+	const lease = admitStorage(
+		`cache CHR ${version} (${arch})`,
+		{
+			parts: [{ label: "image download", bytes: STORAGE_ESTIMATES.imageDownload, path: cache }],
+			protectVersions: [version],
+			pins: [`${base}.img`, `${base}.img.zip`],
+			cacheDir: cache,
+		},
+		{ logger: (message: string) => log.status(message) },
+	);
+	try {
+		const zipPath = await downloadImage(version, arch, cacheDir, logger);
+		const extractedImgPath = await extractImage(zipPath, cacheDir, logger);
+		return finalizeExtractedImage(zipPath, extractedImgPath);
+	} finally {
+		lease.release();
+	}
 }
 
 /** List cached images. */

package/src/lib/lock.ts

@@ -65,7 +65,8 @@ export type LockOperation =
 	| "remove"
 	| "device-mode"
 	| "remove-orphan"
-	| "allocate";
+	| "allocate"
+	| "storage";
 
 /** Resources a machine creation has claimed but not yet persisted in `machine.json`.
  *  Carried in the creator's machine lock, so it lives exactly as long as the create

package/src/lib/packages.ts

@@ -2,7 +2,7 @@
  * Extra package download and installation for CHR instances.
  */
 
-import { existsSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs";
 import { join, basename } from "node:path";
 import { QuickCHRError, type Arch } from "./types.ts";
 import { packagesDownloadUrl } from "./versions.ts";
@@ -12,6 +12,10 @@ import { createLogger, type ProgressLogger } from "./log.ts";
 import { restPost } from "./rest.ts";
 import { scpPush } from "./scp.ts";
 import { extractZip } from "./zip.ts";
+import { renameWithRetry } from "./rename.ts";
+import { admitStorage, STORAGE_ESTIMATES } from "./storage.ts";
+import { touchCacheEntry } from "./images.ts";
+import { pinCacheEntries } from "./storage-lease.ts";
 
 const PACKAGE_CACHE_MANIFEST = ".quickchr-complete.json";
 
@@ -76,50 +80,65 @@ export async function downloadPackages(
 	if (await isCompletePackageCache(version, arch, cache)) {
 		const log = logger ?? createLogger();
 		log.status(`  Using cached packages: ${version} (${arch})`);
+		touchCacheEntry(zipPath);
 		return extractDir;
 	}
 
-	// Download if needed. Same bounded path as the image download (#116) — this
-	// call site previously had neither a deadline nor retries, so its only bound
-	// was whatever the calling test happened to impose.
-	if (!existsSync(zipPath)) {
-		const log = logger ?? createLogger();
-		log.status(`Downloading packages for ${version} (${arch})...`);
-		log.status(`  ${url}`);
-		await downloadToFile(url, zipPath, { logger: log });
-	}
-
-	// Extract into a sibling directory, record the exact complete set, then
-	// rename it into place. A killed extraction can never look like a cache hit.
-	const tempDir = mkdtempSync(join(cache, ".quickchr-packages-"));
+	const lease = admitStorage(
+		`cache packages ${version} (${arch})`,
+		{
+			parts: [{ label: "packages download", bytes: STORAGE_ESTIMATES.packagesDownload, path: cache }],
+			protectVersions: [version],
+			pins: [`packages-${arch}-${version}`],
+			cacheDir: cache,
+		},
+		{ logger: (message: string) => (logger ?? createLogger()).status(message) },
+	);
 	try {
-		extractZip(zipPath, tempDir);
-		const packages = packageFiles(tempDir);
-		if (packages.length === 0) {
-			throw new Error(`No non-empty .npk files found in ${zipName}`);
+		// Download if needed. Same bounded path as the image download (#116) — this
+		// call site previously had neither a deadline nor retries, so its only bound
+		// was whatever the calling test happened to impose.
+		if (!existsSync(zipPath)) {
+			const log = logger ?? createLogger();
+			log.status(`Downloading packages for ${version} (${arch})...`);
+			log.status(`  ${url}`);
+			await downloadToFile(url, zipPath, { logger: log });
 		}
-		const manifest: PackageCacheManifest = {
-			version,
-			arch,
-			archiveSize: statSync(zipPath).size,
-			packages,
-		};
-		await Bun.write(join(tempDir, PACKAGE_CACHE_MANIFEST), `${JSON.stringify(manifest, null, "\t")}\n`);
-		if (existsSync(extractDir)) rmSync(extractDir, { recursive: true, force: true });
-		renameSync(tempDir, extractDir);
-	} catch (error) {
-		rmSync(tempDir, { recursive: true, force: true });
-		if (error instanceof Error && error.message.startsWith("No non-empty")) {
-			throw new QuickCHRError("PROCESS_FAILED", error.message);
+
+		// Extract into a sibling directory, record the exact complete set, then
+		// rename it into place. A killed extraction can never look like a cache hit.
+		const tempDir = mkdtempSync(join(cache, ".quickchr-packages-"));
+		try {
+			extractZip(zipPath, tempDir);
+			const packages = packageFiles(tempDir);
+			if (packages.length === 0) {
+				throw new Error(`No non-empty .npk files found in ${zipName}`);
+			}
+			const manifest: PackageCacheManifest = {
+				version,
+				arch,
+				archiveSize: statSync(zipPath).size,
+				packages,
+			};
+			await Bun.write(join(tempDir, PACKAGE_CACHE_MANIFEST), `${JSON.stringify(manifest, null, "\t")}\n`);
+			if (existsSync(extractDir)) rmSync(extractDir, { recursive: true, force: true });
+			renameWithRetry(tempDir, extractDir);
+		} catch (error) {
+			rmSync(tempDir, { recursive: true, force: true });
+			if (error instanceof Error && error.message.startsWith("No non-empty")) {
+				throw new QuickCHRError("PROCESS_FAILED", error.message);
+			}
+			throw error;
 		}
-		throw error;
-	}
 
-	if (!(await isCompletePackageCache(version, arch, cache))) {
-		throw new QuickCHRError(
-			"PROCESS_FAILED",
-			`Package cache verification failed for ${version} (${arch})`,
-		);
+		if (!(await isCompletePackageCache(version, arch, cache))) {
+			throw new QuickCHRError(
+				"PROCESS_FAILED",
+				`Package cache verification failed for ${version} (${arch})`,
+			);
+		}
+	} finally {
+		lease.release();
 	}
 
 	return extractDir;
@@ -225,8 +244,15 @@ export async function downloadAndListPackages(
 	version: string,
 	arch: Arch,
 ): Promise<string[]> {
-	const extractDir = await downloadPackages(version, arch);
-	return listAvailablePackages(extractDir);
+	// Pinned through the listing: once downloadPackages() returns, nothing else stops a
+	// concurrent eviction from removing the extraction mid-read.
+	const pin = pinCacheEntries(`list packages ${version} (${arch})`, [`packages-${arch}-${version}`]);
+	try {
+		const extractDir = await downloadPackages(version, arch);
+		return listAvailablePackages(extractDir);
+	} finally {
+		pin.release();
+	}
 }
 
 /** Download all packages and install every one of them. Useful for API schema generation.

package/src/lib/platform.ts

@@ -3,7 +3,7 @@
  */
 
 import { existsSync, readdirSync, statSync } from "node:fs";
-import type { AccelMode, EfiFirmwarePaths, HostInterface, PackageManager, PlatformInfo, SocketVmnetInfo } from "./types.ts";
+import type { AccelMode, EfiFirmwarePaths, HostInterface, PackageManager, PlatformInfo, SocketVmnetInfo, DoctorCheck } from "./types.ts";
 import { QuickCHRError as QError, parseAccelMode } from "./types.ts";
 // settings-file.ts, not settings.ts: the latter's graph (cache → state → network
 // → platform) is a cycle that would load eagerly on every CLI start.
@@ -590,3 +590,15 @@ export function resolveInterfaceAlias(
 		`No interface found for alias '${alias}' — run 'quickchr doctor' to see available interfaces`,
 	);
 }
+
+/** Compare the running Bun against the same pin CI installs. */
+export async function bunRuntimeCheck(version = Bun.version): Promise<DoctorCheck> {
+	const pin = (await Bun.file(new URL("../../.bun-version", import.meta.url)).text()).trim();
+	// Runtimes predating the Semver API are also older than the tested pin.
+	const older = typeof Bun.semver?.order !== "function" || Bun.semver.order(version, pin) < 0;
+	return {
+		label: "Bun runtime",
+		status: older ? "warn" : "ok",
+		detail: `bun ${version}; tested with Bun ${pin}${older ? ` — upgrade to ${pin} or newer` : ""}`,
+	};
+}

package/src/lib/quickchr.ts

@@ -30,7 +30,7 @@ import type {
 import { QuickCHRError, ARCHES, CHANNELS, SERVICE_IDS, QUICKCHR_DESCRIPTOR_VERSION, HOST_GATEWAY_IP, PORTS_PER_BLOCK } from "./types.ts";
 import { assertValidResourceName, assertPathSafeName, shellQuote } from "./names.ts";
 import packageJson from "../../package.json";
-import { detectPlatform, requireQemu, requireFirmware, getQemuVersion, getQemuInstallHint, isCrossArchEmulation, accelTimeoutFactor, detectAccel, accelNote, resolveAccelOverrideWithSource, accelSourceLabel, findQemuImg, qgaKvmWarning, detectSocketVmnet, isSocketVmnetDaemonRunning, findCommandOnPath } from "./platform.ts";
+import { bunRuntimeCheck, detectPlatform, requireQemu, requireFirmware, getQemuVersion, getQemuInstallHint, isCrossArchEmulation, accelTimeoutFactor, detectAccel, accelNote, resolveAccelOverrideWithSource, accelSourceLabel, findQemuImg, qgaKvmWarning, detectSocketVmnet, isSocketVmnetDaemonRunning, findCommandOnPath } from "./platform.ts";
 import {
 	resolveVersion,
 	isValidVersion,
@@ -62,11 +62,11 @@ import {
 	getDataDir,
 	appendBootLog,
 } from "./state.ts";
-import { ensureCachedImage, copyImageToMachine, listCachedImages } from "./images.ts";
+import { ensureCachedImage, listCachedImages } from "./images.ts";
 import { autoPruneIfOverCap } from "./cache.ts";
 import { resolveSetting } from "./settings.ts";
 import { buildQemuArgs, spawnQemu, stopQemu, cleanupQemuSockets, waitForBoot, waitForApiReady, readinessProbeFor, extractWrapper, type QemuLaunchConfig } from "./qemu.ts";
-import { cleanDiskFiles, ensureConfiguredDisks, normalizeDiskOptions, parseSnapshotList, listSnapshots, formatDiskSize } from "./disk.ts";
+import { bootDiskFormatOf, bootDiskPath, cleanDiskFiles, ensureConfiguredDisks, normalizeDiskOptions, writeBootDisk, parseSnapshotList, listSnapshots, formatDiskSize } from "./disk.ts";
 import { monitorCommand, serialStreams, qgaCommand, channelEndpoint, channelFileExists, channelPath } from "./channels.ts";
 import { captureBootFailure, newBootProbeStats, preserveOnFailure, type BootFailureReport, type BootProbeStats, type FailureTrigger } from "./diagnostics.ts";
 import { installPackages, installAllPackages, downloadAndListPackages, downloadPackages, findPackageFile, uploadPackages } from "./packages.ts";
@@ -103,8 +103,9 @@ import {
 import type { LicenseOptions } from "./types.ts";
 import type { GuestExec } from "./guest-snapshot.ts";
 import { toChrPorts } from "./network.ts";
-import { assertSufficientQuickchrStorage, formatQuickchrUsage, getQuickchrStorageReport } from "./storage.ts";
-import { existsSync, rmSync, copyFileSync } from "node:fs";
+import { admitStorage, estimateMachineCreation, formatQuickchrUsage, getQuickchrStorageReport } from "./storage.ts";
+import { pinCacheEntries } from "./storage-lease.ts";
+import { existsSync, rmSync } from "node:fs";
 import { acquireLock, acquireLockNow, allocationLockPath, legacyMachineLockPath, listReservations, machineLockPath, type HeldLock, type LockOperation } from "./lock.ts";
 import { join } from "node:path";
 
@@ -373,19 +374,15 @@ async function resetGuestToFactory(state: MachineState): Promise<void> {
 	if (!existsSync(imgPath)) {
 		throw new QuickCHRError("MACHINE_NOT_FOUND", `Cached image not found: ${imgPath}`);
 	}
-	const destPath = join(state.machineDir, "disk.img");
-	copyFileSync(imgPath, destPath);
-
-	// Clean up disk files (boot.qcow2, extra disks)
+	// Drop boot.qcow2 and the extra disks, then rebuild the boot disk from the cache.
+	// A raw disk.img is replaced atomically. On a qcow2 machine, disk.img is the unused
+	// raw copy machines created before 0.5.1 kept: the new boot.qcow2 is converted from
+	// the cache, so the copy goes too (#199).
+	const format = bootDiskFormatOf(state);
 	cleanDiskFiles(state.machineDir);
-
-	// Re-prepare disks if the machine had disk customizations
-	await ensureConfiguredDisks(
-		state.machineDir,
-		state.bootSize,
-		state.extraDisks,
-		state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw"),
-	);
+	await writeBootDisk(state.machineDir, imgPath, format, state.bootSize);
+	if (format === "qcow2") rmSync(join(state.machineDir, "disk.img"), { force: true });
+	await ensureConfiguredDisks(state.machineDir, state.bootSize, state.extraDisks, format, { booted: false });
 
 	deleteInstanceCredentials(state.name);
 	// The managed keypair authenticated to the account factory reset erased,
@@ -1001,21 +998,28 @@ function createInstance(state: MachineState): ChrInstance {
 			const names = typeof packages === "string" ? [packages] : packages;
 			if (names.length === 0) return [];
 
-			const extractDir = await downloadPackages(state.version, state.arch);
+			// A booted machine no longer holds its package cache in use, so pin it until the
+			// upload is done: a concurrent eviction must not remove it mid-read.
+			const pin = pinCacheEntries(`install packages on ${state.name}`, [`packages-${state.arch}-${state.version}`]);
 			const packagePaths: string[] = [];
 			const installed: string[] = [];
-			for (const pkg of names) {
-				const pkgPath = findPackageFile(extractDir, pkg);
-				if (!pkgPath) {
-					console.warn(`Package "${pkg}" not found in all_packages for ${state.version} (${state.arch})`);
-					continue;
+			try {
+				const extractDir = await downloadPackages(state.version, state.arch);
+				for (const pkg of names) {
+					const pkgPath = findPackageFile(extractDir, pkg);
+					if (!pkgPath) {
+						console.warn(`Package "${pkg}" not found in all_packages for ${state.version} (${state.arch})`);
+						continue;
+					}
+					packagePaths.push(pkgPath);
+					installed.push(pkg);
 				}
-				packagePaths.push(pkgPath);
-				installed.push(pkg);
-			}
-			if (packagePaths.length === 0) return [];
+				if (packagePaths.length === 0) return [];
 
-			await uploadPackages(packagePaths, ports.ssh);
+				await uploadPackages(packagePaths, ports.ssh);
+			} finally {
+				pin.release();
+			}
 
 			// Reboot to activate packages
 			let rebootAuth: string;
@@ -1119,7 +1123,7 @@ function createInstance(state: MachineState): ChrInstance {
 
 		snapshot: {
 			async list(): Promise<SnapshotInfo[]> {
-				const format = state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw");
+				const format = bootDiskFormatOf(state);
 				if (format !== "qcow2") return [];
 
 				// Try monitor first (works on running machines, gives live state)
@@ -1131,7 +1135,7 @@ function createInstance(state: MachineState): ChrInstance {
 				}
 
 				// Fall back to qemu-img info (works on stopped machines too)
-				const bootPath = join(state.machineDir, "boot.qcow2");
+				const bootPath = bootDiskPath(state.machineDir, "qcow2");
 				if (existsSync(bootPath)) {
 					return listSnapshots(bootPath);
 				}
@@ -1139,7 +1143,7 @@ function createInstance(state: MachineState): ChrInstance {
 			},
 
 			async save(name?: string): Promise<SnapshotInfo> {
-				const format = state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw");
+				const format = bootDiskFormatOf(state);
 				if (format !== "qcow2") {
 					throw new QuickCHRError("STATE_ERROR", "Snapshots require a qcow2 boot disk. Recreate with bootDiskFormat: \"qcow2\".");
 				}
@@ -1176,7 +1180,7 @@ function createInstance(state: MachineState): ChrInstance {
 			},
 
 			async load(name: string): Promise<void> {
-				const format = state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw");
+				const format = bootDiskFormatOf(state);
 				if (format !== "qcow2") {
 					throw new QuickCHRError("STATE_ERROR", "Snapshots require a qcow2 boot disk.");
 				}
@@ -1202,7 +1206,7 @@ function createInstance(state: MachineState): ChrInstance {
 			},
 
 			async delete(name: string): Promise<void> {
-				const format = state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw");
+				const format = bootDiskFormatOf(state);
 				if (format !== "qcow2") {
 					throw new QuickCHRError("STATE_ERROR", "Snapshots require a qcow2 boot disk.");
 				}
@@ -1584,7 +1588,8 @@ async function buildLaunchConfigFromState(state: MachineState): Promise<QemuLaun
 		state.machineDir,
 		state.bootSize,
 		state.extraDisks,
-		state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw"),
+		bootDiskFormatOf(state),
+		{ booted: true },
 	);
 	const platform = await detectPlatform();
 	const hostfwd = buildHostfwdString(state.ports);
@@ -2029,16 +2034,28 @@ export class QuickCHR {
 		}
 
 		const machineDir = getMachineDir(name);
-		assertSufficientQuickchrStorage(`prepare CHR ${name}`);
-		const { lock, portBase, ports, networks } = await claimNewMachine(name, "add", opts);
+		// Held until machine.json is saved: it reserves the boot disk's bytes and pins the
+		// image against a concurrent eviction (storage-lease.ts).
+		const storageLease = admitStorage(
+			`prepare CHR ${name}`,
+			estimateMachineCreation({ version, arch, packages: !!(opts.installAllPackages || opts.packages?.length) }),
+		);
+		let claimed: Awaited<ReturnType<typeof claimNewMachine>>;
+		try {
+			claimed = await claimNewMachine(name, "add", opts);
+		} catch (err) {
+			storageLease.release();
+			throw err;
+		}
+		const { lock, portBase, ports, networks } = claimed;
 		try {
 			const cachedImg = await ensureCachedImage(version, arch);
-			copyImageToMachine(cachedImg, machineDir);
 			const diskArtifacts = await ensureConfiguredDisks(
 				machineDir,
 				diskOpts.bootSize,
 				diskOpts.extraDisks,
 				diskOpts.bootDiskFormat,
+				{ booted: false, factoryImage: async () => cachedImg },
 			);
 
 			const state: MachineState = {
@@ -2083,6 +2100,7 @@ export class QuickCHR {
 			throw err;
 		} finally {
 			lock.release();
+			storageLease.release();
 		}
 	}
 
@@ -2282,7 +2300,13 @@ export class QuickCHR {
 		}
 
 		const machineDir = getMachineDir(name);
-		assertSufficientQuickchrStorage(`start CHR ${name}`);
+		// Held until machine.json is saved — after the spawn, or in the foreground once
+		// QEMU exits — and released on failure: see add().
+		const storageLease = admitStorage(
+			`start CHR ${name}`,
+			estimateMachineCreation({ version, arch, packages: !!(opts.installAllPackages || opts.packages?.length) }),
+			{ logger: logger ? (message: string) => logger.status(message) : undefined },
+		);
 		const dirCreatedHere = !existsSync(machineDir);
 
 		const background = opts.background ?? true;
@@ -2301,11 +2325,14 @@ export class QuickCHR {
 			opts.secureLogin === true
 		);
 
-		const { lock, portBase, ports, networks: networkConfigs } = await claimNewMachine(
-			name,
-			!background && !hasProvisioning ? "foreground" : "start",
-			opts,
-		);
+		let claimed: Awaited<ReturnType<typeof claimNewMachine>>;
+		try {
+			claimed = await claimNewMachine(name, !background && !hasProvisioning ? "foreground" : "start", opts);
+		} catch (err) {
+			storageLease.release();
+			throw err;
+		}
+		const { lock, portBase, ports, networks: networkConfigs } = claimed;
 		// Endpoints are claimed before QEMU is spawned, because resolution needs to know
 		// which end this machine holds. A launch that fails before its state is persisted
 		// has no instance lifecycle to release them later, so a failed start would leave a
@@ -2316,14 +2343,14 @@ export class QuickCHR {
 
 		// Download and prepare image
 		const cachedImg = await ensureCachedImage(version, arch, undefined, logger);
-		copyImageToMachine(cachedImg, machineDir);
 
-		// Prepare disks (boot resize + extra disks)
+		// Build the boot disk from the cache (resized if asked) and any extra disks
 		const diskArtifacts = await ensureConfiguredDisks(
 			machineDir,
 			diskOpts.bootSize,
 			diskOpts.extraDisks,
 			diskOpts.bootDiskFormat,
+			{ booted: false, factoryImage: async () => cachedImg },
 		);
 		const bootDisk = diskArtifacts.bootDisk;
 		const extraDiskConfigs = diskArtifacts.extraDisks;
@@ -2414,6 +2441,7 @@ export class QuickCHR {
 
 		saveMachine(state);
 		unpersistedSocketClaim = undefined;
+		storageLease.release();
 
 		const instance = createInstance(state);
 		if (opts.wait === false) return instance;
@@ -2539,6 +2567,7 @@ export class QuickCHR {
 			throw err;
 		} finally {
 			lock.release();
+			storageLease.release();
 		}
 	}
 
@@ -2743,16 +2772,17 @@ export class QuickCHR {
 			hasProvisioning = false;
 		}
 
-		const diskPath = join(state.machineDir, "disk.img");
-		if (!existsSync(diskPath)) {
-			throw new QuickCHRError("MACHINE_NOT_FOUND", `Disk image not found for "${state.name}"`);
-		}
-
+		// Checks the disk this machine boots from — a qcow2 machine needs only boot.qcow2
+		// (#200) — and refuses, rather than rebuilds, a booted machine's missing disk.
 		const diskArtifacts = await ensureConfiguredDisks(
 			state.machineDir,
 			state.bootSize,
 			state.extraDisks,
-			state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw"),
+			bootDiskFormatOf(state),
+			{
+				booted: !isProvisioningWindowOpen(state),
+				factoryImage: () => ensureCachedImage(state.version, state.arch, undefined, logger),
+			},
 		);
 		const bootDisk = diskArtifacts.bootDisk;
 		const extraDiskConfigs = diskArtifacts.extraDisks;
@@ -2967,12 +2997,7 @@ export class QuickCHR {
 	static async doctor(): Promise<DoctorResult> {
 		const checks: DoctorResult["checks"] = [];
 
-		// Bun version
-		checks.push({
-			label: "Bun runtime",
-			status: "ok",
-			detail: `bun ${Bun.version}`,
-		});
+		checks.push(await bunRuntimeCheck());
 
 		// QEMU for each arch
 		for (const arch of ARCHES) {
@@ -3067,14 +3092,14 @@ export class QuickCHR {
 			detail: `${machines.length} instance${machines.length !== 1 ? "s" : ""} (${running} running, ${formatDiskSize(storage.machinesBytes)} on disk)`,
 		});
 
-		let storageDetail = `${storage.path}: ${formatDiskSize(storage.freeBytes)} free; ${formatQuickchrUsage(storage)}`;
+		let storageDetail = `${storage.statPath}: ${formatDiskSize(storage.freeBytes)} free; ${formatQuickchrUsage(storage)}`;
 		if (storage.status === "error") {
-			storageDetail += ` — below required minimum ${formatDiskSize(storage.recommendedFreeBytes)}`;
+			storageDetail += ` — below the ${formatDiskSize(storage.reserveBytes)} reserve: new machines and image downloads are refused (after evicting what the cache can spare)`;
 		} else if (storage.status === "warn") {
 			storageDetail += ` — low headroom (target ${formatDiskSize(storage.warningFreeBytes)} free)`;
 		}
 		checks.push({
-			label: storage.label === ".local" ? "Storage (.local)" : "Storage",
+			label: "Storage",
 			status: storage.status,
 			detail: storageDetail,
 		});
@@ -3095,7 +3120,7 @@ export class QuickCHR {
 			});
 		}
 
-		// qemu-img (optional, for disk resize and extra disks)
+		// qemu-img (default qcow2 creation and disk features)
 		const qemuImgPath = findQemuImg();
 		if (qemuImgPath) {
 			checks.push({
@@ -3107,7 +3132,7 @@ export class QuickCHR {
 			checks.push({
 				label: "qemu-img",
 				status: "warn",
-				detail: `not found — required for --boot-size and --add-disk (${getQemuInstallHint()})`,
+				detail: `not found — required for default qcow2 creation, setup, --boot-size and --add-disk (${getQemuInstallHint()})`,
 			});
 		}
 

package/src/lib/rename.ts

@@ -0,0 +1,41 @@
+/**
+ * Publish-by-rename that survives Windows' transient sharing violations.
+ */
+
+import { renameSync } from "node:fs";
+
+/** Codes Windows returns while another process (Defender, the Search indexer) still
+ *  holds a handle on a file it is scanning — typically one we just wrote. */
+const TRANSIENT_WINDOWS_CODES = new Set(["EPERM", "EACCES", "EBUSY"]);
+const RETRY_DELAYS_MS = [25, 50, 100, 200, 400, 800];
+
+/**
+ * `renameSync`, retried on Windows while the failure looks like a sharing violation
+ * (#202). Every quickchr publish writes a temp file or directory and renames it into
+ * place, which is exactly when a scanner has the fresh file open. libuv does not retry
+ * this case. The budget is bounded (about 1.6 s); after it, the last error is thrown
+ * unchanged. Elsewhere this is a plain `renameSync`.
+ */
+export function renameWithRetry(
+	from: string,
+	to: string,
+	opts: { platform?: NodeJS.Platform; rename?: (from: string, to: string) => void; sleep?: (ms: number) => void } = {},
+): void {
+	const rename = opts.rename ?? renameSync;
+	if ((opts.platform ?? process.platform) !== "win32") {
+		rename(from, to);
+		return;
+	}
+	const sleep = opts.sleep ?? Bun.sleepSync;
+	for (const delay of RETRY_DELAYS_MS) {
+		try {
+			rename(from, to);
+			return;
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (!code || !TRANSIENT_WINDOWS_CODES.has(code)) throw error;
+			sleep(delay);
+		}
+	}
+	rename(from, to);
+}