@tikoci/quickchr 0.5.0 → 0.5.2

package/src/lib/settings.ts

@@ -17,7 +17,7 @@ import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, renameSync, u
 import { basename, dirname, join } from "node:path";
 import { ARCHES, CHANNELS, QuickCHRError, parseAccelMode } from "./types.ts";
 import type { AccelMode, Channel } from "./types.ts";
-import { parseSizeString, DEFAULT_CACHE_MAX_BYTES } from "./cache.ts";
+import { parseSizeString, DEFAULT_CACHE_MAX_BYTES, DEFAULT_STORAGE_RESERVE_BYTES } from "./cache.ts";
 import { loadSettingsFileDefaults, readSettingsFileLines, settingsFilePath } from "./settings-file.ts";
 
 // The quickchr.env file tier lives in the leaf module settings-file.ts (see its
@@ -56,12 +56,14 @@ function parseArchSetting(raw: string): SettingsValue {
 	return raw;
 }
 
-function parseCacheMaxSize(raw: string): SettingsValue {
-	try {
-		return parseSizeString(raw);
-	} catch (e) {
-		throw new QuickCHRError("INVALID_SETTING_VALUE", `Invalid value "${raw}" for cache-max-size — ${e instanceof Error ? e.message : String(e)}`);
-	}
+function sizeSetting(attr: string): (raw: string) => SettingsValue {
+	return (raw) => {
+		try {
+			return parseSizeString(raw);
+		} catch (e) {
+			throw new QuickCHRError("INVALID_SETTING_VALUE", `Invalid value "${raw}" for ${attr} — ${e instanceof Error ? e.message : String(e)}`);
+		}
+	};
 }
 
 /** Shared with the CLI's own `--timeout-extra`/`-T` flag validation (cmdStart in
@@ -112,7 +114,16 @@ export const SETTINGS_KEYS: readonly SettingsKeyDef[] = [
 		attr: "cache-max-size",
 		envKey: "QUICKCHR_CACHE_MAX_SIZE",
 		builtinDefault: DEFAULT_CACHE_MAX_BYTES,
-		parse: parseCacheMaxSize,
+		parse: sizeSetting("cache-max-size"),
+		serialize: (v) => String(v),
+	},
+	{
+		// Free space creating a machine or filling the cache must leave on the data
+		// dir's filesystem, on top of what the operation itself writes (#199).
+		attr: "storage-reserve",
+		envKey: "QUICKCHR_STORAGE_RESERVE",
+		builtinDefault: DEFAULT_STORAGE_RESERVE_BYTES,
+		parse: sizeSetting("storage-reserve"),
 		serialize: (v) => String(v),
 	},
 	{
@@ -123,7 +134,7 @@ export const SETTINGS_KEYS: readonly SettingsKeyDef[] = [
 		serialize: (v) => String(v),
 	},
 	{
-		// No builtinDefault: unlike the other 5 keys, the wizard needs to distinguish
+		// No builtinDefault: unlike the other keys, the wizard needs to distinguish
 		// "not configured" from "explicitly false" (src/cli/wizard.ts's userChoice
 		// initialValue only pre-highlights "admin" when the setting is concretely
 		// false) — a builtinDefault here would collapse that distinction and always

package/src/lib/state.ts

@@ -2,7 +2,7 @@
  * Machine state persistence — JSON files in ~/.local/share/quickchr/machines/.
  */
 
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, rmSync, statSync } from "node:fs";
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, rmSync, statSync } from "node:fs";
 import { join, } from "node:path";
 import type { MachineState, } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
@@ -415,3 +415,28 @@ export function pruneCache(maxAgeDays: number = 30): number {
 
 	return removed;
 }
+
+/** Logical size of a file, or of everything under a directory. */
+export 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;
+}

package/src/lib/storage-lease.ts

@@ -0,0 +1,169 @@
+/**
+ * Cross-process coordination between storage admission, cache readers and cache
+ * eviction (#199, Codex review of #203).
+ *
+ * One data-dir-wide lock, held only for the length of a check-and-record or an
+ * eviction pass: never across a download or a boot. Under it, an operation records a
+ * **lease** — a file naming the cache entries it is about to read (pins) and the bytes
+ * it is about to write (reservations, per filesystem). Eviction runs under the same
+ * lock and skips pinned entries; admission subtracts other live leases' reservations
+ * from measured free space. A pin is recorded before the reader checks the entry
+ * exists, so an eviction either sees the pin or has already finished — and then the
+ * reader finds the entry gone and fetches it again.
+ *
+ * A lease lives exactly as long as its operation: released when the operation's
+ * writes are done (or its machine.json, which protects the image from then on, is
+ * saved), and ignored and deleted once its pid is dead. While an operation is still
+ * writing, its reservation and the bytes already written are both counted — a
+ * deliberate over-estimate for the length of one create.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { acquireLockNow, type HeldLock } from "./lock.ts";
+import { ensureDir, getDataDir } from "./state.ts";
+import { renameWithRetry } from "./rename.ts";
+import { QuickCHRError } from "./types.ts";
+
+/** Bytes an in-flight operation will write to one filesystem, by `stat().dev`. */
+export interface StorageReservation {
+	dev: number;
+	bytes: number;
+}
+
+export interface LeaseRecord {
+	pid: number;
+	at: string;
+	/** What the operation is, for diagnostics. */
+	action: string;
+	/** Cache entry names (as `cacheInventory` gives them) that must not be evicted. */
+	pins: string[];
+	reservations: StorageReservation[];
+}
+
+export interface StorageLease {
+	readonly record: LeaseRecord;
+	/** Idempotent. */
+	release(): void;
+}
+
+const LOCK_WAIT_MS = 30_000;
+const LOCK_POLL_MS = 25;
+
+export function storageLockPath(): string {
+	return join(getDataDir(), ".storage.lock");
+}
+
+function leaseDir(): string {
+	return join(getDataDir(), ".storage-leases");
+}
+
+export function isPidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/** Run `fn` holding the storage lock. Synchronous: holders keep it for milliseconds
+ *  (a check, or one eviction pass), so a short spin is simpler than making every
+ *  caller async. The lock is not reentrant: `fn` must not take it again. */
+export function withStorageLock<T>(fn: () => T): T {
+	ensureDir(getDataDir());
+	const deadline = Date.now() + LOCK_WAIT_MS;
+	let lock: HeldLock | undefined;
+	for (;;) {
+		try {
+			lock = acquireLockNow(storageLockPath(), "storage", { subject: "The storage lock" });
+			break;
+		} catch (error) {
+			if (!(error instanceof QuickCHRError) || error.code !== "MACHINE_LOCKED" || Date.now() >= deadline) throw error;
+			Bun.sleepSync(LOCK_POLL_MS);
+		}
+	}
+	try {
+		return fn();
+	} finally {
+		lock.release();
+	}
+}
+
+/** Every live lease. Leases of dead processes are deleted. Call under the lock. */
+export function liveLeases(): LeaseRecord[] {
+	let names: string[];
+	try {
+		names = readdirSync(leaseDir());
+	} catch {
+		return [];
+	}
+	const live: LeaseRecord[] = [];
+	for (const name of names) {
+		if (!name.endsWith(".json")) continue;
+		const path = join(leaseDir(), name);
+		try {
+			const record = JSON.parse(readFileSync(path, "utf8")) as LeaseRecord;
+			if (isPidAlive(record.pid)) {
+				live.push(record);
+				continue;
+			}
+		} catch { /* unreadable: a writer died mid-write — files are renamed into place */ }
+		rmSync(path, { force: true });
+	}
+	return live;
+}
+
+/** Pins of live leases, read without the lock (for `cache list`'s IN-USE column). */
+export function pinnedEntries(): Set<string> {
+	const pins = new Set<string>();
+	try {
+		for (const name of readdirSync(leaseDir())) {
+			if (!name.endsWith(".json")) continue;
+			try {
+				const record = JSON.parse(readFileSync(join(leaseDir(), name), "utf8")) as LeaseRecord;
+				if (isPidAlive(record.pid)) for (const pin of record.pins) pins.add(pin);
+			} catch { /* being written or removed */ }
+		}
+	} catch { /* no leases */ }
+	return pins;
+}
+
+/** Record a lease. Call under the lock, after the checks it stands for. */
+export function createLease(action: string, pins: string[], reservations: StorageReservation[]): StorageLease {
+	const record: LeaseRecord = { pid: process.pid, at: new Date().toISOString(), action, pins, reservations };
+	mkdirSync(leaseDir(), { recursive: true });
+	const path = join(leaseDir(), `${process.pid}-${crypto.randomUUID()}.json`);
+	writeFileSync(`${path}.tmp`, JSON.stringify(record));
+	renameWithRetry(`${path}.tmp`, path);
+	let released = false;
+	return {
+		record,
+		release() {
+			if (released) return;
+			released = true;
+			rmSync(path, { force: true });
+		},
+	};
+}
+
+/** Pin cache entries for the length of a read that is not otherwise protected (a
+ *  running machine installing packages). Release when done. */
+export function pinCacheEntries(action: string, pins: string[]): StorageLease {
+	return withStorageLock(() => createLease(action, pins, []));
+}
+
+/** The filesystem a path is (or will be) written on: `stat().dev` of its nearest
+ *  existing ancestor, and that ancestor. */
+export function filesystemOf(path: string): { dev: number; statPath: string } {
+	let current = path || ".";
+	for (;;) {
+		try {
+			return { dev: statSync(current).dev, statPath: current };
+		} catch {
+			const parent = dirname(current);
+			if (parent === current) return { dev: statSync(".").dev, statPath: "." };
+			current = parent;
+		}
+	}
+}

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

@@ -432,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;
@@ -740,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.
@@ -949,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;