@tikoci/quickchr 0.5.0 → 0.5.1

package/src/lib/quickchr.ts

@@ -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;
@@ -3067,14 +3097,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,
 		});

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);
+}

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;
+		}
+	}
+}