@tikoci/quickchr 0.5.0 → 0.5.1

package/src/cli/index.ts

@@ -1390,7 +1390,13 @@ function printReadinessTip(name: string, version: string): void {
 	tip(`wait for readiness with: centrs retrieve --quickchr ${name} /system/resource${via} --wait 5m`);
 }
 
-async function cmdStart(argv: string[]) {
+/** Single-target start's status word: a machine this call created says so (#194). */
+function startStatusLine(created: boolean, noWait: boolean): string {
+	if (noWait) return `${created ? "created" : "launched"} — not waiting for RouterOS (--no-wait)`;
+	return created ? "created and started" : "started";
+}
+
+export async function cmdStart(argv: string[]) {
 	const { flags, positional } = parseFlags(argv);
 	applyTimeoutExtraShortFlag(argv, flags, positional);
 	rejectUnknownFlags(flags, START_FLAGS, "start");
@@ -1474,7 +1480,6 @@ async function cmdStart(argv: string[]) {
 		bootSize: flag(flags, "boot-size"),
 		extraDisks: flagList(flags, "add-disk").length > 0 ? flagList(flags, "add-disk") : undefined,
 		extraPorts: flagList(flags, "forward").flatMap(expandForwardSpec),
-		installDeps: flagBool(flags, "install-deps"),
 		dryRun: flagBool(flags, "dry-run"),
 		timeoutExtra: await resolveTimeoutExtraMs(flags),
 	};
@@ -1505,10 +1510,10 @@ async function cmdStart(argv: string[]) {
 	}
 
 	opts.disableAdmin = flagOptionalBool(flags, "disable-admin");
+	// No name, or a name no machine has: this call creates the machine (#194).
+	const target = opts.name ? QuickCHR.get(opts.name) : null;
 	{
-		const { QuickCHR } = await import("../lib/quickchr.ts");
 		const { isProvisioningWindowOpen } = await import("../lib/provisioning-window.ts");
-		const target = opts.name ? QuickCHR.get(opts.name) : null;
 		// No machine yet, or one that was added and never booted: still a first boot,
 		// so the setting applies. Only a closed window suppresses it — otherwise a
 		// plain `quickchr start <booted-name>` would ask to provision a booted guest
@@ -1573,7 +1578,7 @@ async function cmdStart(argv: string[]) {
 	} else {
 		const creds = await resolveDisplayCredentials(instance.state);
 		const v6 = isRouterOs6(instance.state.version);
-		console.log(`${statusIcon("running")} ${bold(instance.name)} ${opts.wait === false ? "launched — not waiting for RouterOS (--no-wait)" : "started"}`);
+		console.log(`${statusIcon("running")} ${bold(instance.name)} ${startStatusLine(!target, opts.wait === false)}`);
 		console.log(`  Version: ${instance.state.version} (${instance.state.arch})${v6 ? `  ${dim("boot-only: no REST, no provisioning")}` : ""}`);
 		console.log(`  Network: ${formatNetworks(instance.state.networks ?? [])}`);
 		console.log(`  Ports:   ${formatPorts(instance.state.ports)}`);
@@ -2236,7 +2241,7 @@ async function cmdDisk(argv: string[]) {
 
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { bold, dim, machineNotFoundMessage } = await import("./format.ts");
-	const { getDiskInfo } = await import("../lib/disk.ts");
+	const { bootDiskFormatOf, bootDiskPath, getDiskInfo } = await import("../lib/disk.ts");
 	const { join } = await import("node:path");
 	const { existsSync } = await import("node:fs");
 	const { findQemuImg } = await import("../lib/platform.ts");
@@ -2259,10 +2264,8 @@ async function cmdDisk(argv: string[]) {
 	console.log(bold(`Disks for ${name}\n`));
 
 	// Boot disk
-	const bootPath = state.bootDiskFormat === "qcow2"
-		? join(state.machineDir, "boot.qcow2")
-		: join(state.machineDir, "disk.img");
-	const bootFormat = state.bootDiskFormat ?? "raw";
+	const bootFormat = bootDiskFormatOf(state);
+	const bootPath = bootDiskPath(state.machineDir, bootFormat);
 
 	if (qemuImg && existsSync(bootPath)) {
 		try {
@@ -2835,7 +2838,7 @@ async function cmdCache(argv: string[]) {
 		return;
 	}
 
-	const { listCacheEntries, pruneCache, parseSizeString, formatSizeBytes } = await import("../lib/cache.ts");
+	const { cacheInventory, countEntries, pruneCache, parseSizeString, formatSizeBytes } = await import("../lib/cache.ts");
 
 	const parseDuration = (s: string): number => {
 		const m = s.match(/^(\d+(?:\.\d+)?)([smhdw])$/);
@@ -2847,6 +2850,11 @@ async function cmdCache(argv: string[]) {
 	};
 	const parseSize = parseSizeString;
 	const formatSize = formatSizeBytes;
+	const printFailedDeletes = (failed: Array<{ entry: { basename: string }; error: string }>) => {
+		if (failed.length === 0) return;
+		console.error(`Could not delete ${countEntries(failed.length)} (kept, not counted as freed):`);
+		for (const { entry, error } of failed) console.error(`  - ${entry.basename}: ${error}`);
+	};
 	const formatAge = (ms: number): string => {
 		const s = Math.floor(ms / 1000);
 		if (s < 60) return `${s}s`;
@@ -2897,13 +2905,14 @@ async function cmdCache(argv: string[]) {
 		}
 		case "list":
 		case "ls": {
-			const entries = listCacheEntries();
+			const { entries, unmanagedBytes } = cacheInventory();
 			if (flags.json === true) {
 				console.log(JSON.stringify(entries, null, 2));
 				return;
 			}
 			if (entries.length === 0) {
-				console.log("No cached images.");
+				console.log("No cache entries.");
+				if (unmanagedBytes > 0) console.log(`Other files: ${formatSize(unmanagedBytes)} (not written by quickchr; never pruned)`);
 				return;
 			}
 			const now = Date.now();
@@ -2930,7 +2939,8 @@ async function cmdCache(argv: string[]) {
 				);
 			}
 			const total = entries.reduce((s, e) => s + e.sizeBytes, 0);
-			console.log(`\nTotal: ${entries.length} image(s), ${formatSize(total)}`);
+			console.log(`\nTotal: ${countEntries(entries.length)}, ${formatSize(total)}`);
+			if (unmanagedBytes > 0) console.log(`Other files: ${formatSize(unmanagedBytes)} (not written by quickchr; never pruned)`);
 			break;
 		}
 		case "prune": {
@@ -2944,29 +2954,33 @@ async function cmdCache(argv: string[]) {
 			}
 			const result = pruneCache(opts);
 			const verb = opts.dryRun ? "Would evict" : "Evicted";
-			if (result.evicted.length === 0) {
+			if (result.evicted.length === 0 && result.failed.length === 0) {
 				console.log("Nothing to evict.");
-			} else {
-				console.log(`${verb} ${result.evicted.length} image(s):`);
+			} else if (result.evicted.length > 0) {
+				console.log(`${verb} ${countEntries(result.evicted.length)}:`);
 				for (const e of result.evicted) {
 					const reason = result.reasons[e.basename] ?? "policy";
 					console.log(`  - ${e.basename} (${formatSize(e.sizeBytes)}) — ${reason}`);
 				}
-				console.log(`Freed: ${formatSize(result.freedBytes)}`);
+				console.log(`${opts.dryRun ? "Would free" : "Freed"}: ${formatSize(result.freedBytes)}`);
 			}
+			printFailedDeletes(result.failed);
+			if (result.failed.length > 0) process.exitCode = 1;
 			break;
 		}
 		case "clear": {
 			if (flags.all !== true) {
-				console.error("cache clear: refuses without --all (deletes all non-in-use cached images)");
+				console.error("cache clear: refuses without --all (deletes all non-in-use cache entries)");
 				process.exit(1);
 			}
 			const result = pruneCache({ maxSizeBytes: 0, dryRun: flags["dry-run"] === true });
 			const verb = flags["dry-run"] === true ? "Would delete" : "Deleted";
-			console.log(`${verb} ${result.evicted.length} image(s), freed ${formatSize(result.freedBytes)}`);
+			console.log(`${verb} ${countEntries(result.evicted.length)}, ${flags["dry-run"] === true ? "would free" : "freed"} ${formatSize(result.freedBytes)}`);
+			printFailedDeletes(result.failed);
+			if (result.failed.length > 0) process.exitCode = 1;
 			if (result.kept.some((e) => e.inUse)) {
 				const inUse = result.kept.filter((e) => e.inUse);
-				console.log(`Kept ${inUse.length} in-use image(s):`);
+				console.log(`Kept ${inUse.length} in-use cache ${inUse.length === 1 ? "entry" : "entries"}:`);
 				for (const e of inUse) console.log(`  - ${e.basename}`);
 			}
 			break;
@@ -2992,7 +3006,7 @@ async function cmdSettings(argv: string[]) {
 
 	const displayValue = (key: string, value: unknown): string => {
 		if (value === undefined) return "(unset)";
-		if (key === "cache-max-size" && typeof value === "number") return formatSizeBytes(value);
+		if ((key === "cache-max-size" || key === "storage-reserve") && typeof value === "number") return formatSizeBytes(value);
 		if (key === "timeout-extra" && typeof value === "number") return `${value}s`;
 		return String(value);
 	};
@@ -3079,7 +3093,7 @@ async function cmdDoctor(argv: string[] = []) {
 	const staleImages = await findStaleCacheImages();
 	if (staleImages.length > 0) {
 		const longTerm = staleImages[0]?.olderThan;
-		console.log(`Note: ${staleImages.length} cached image(s) older than current long-term (${longTerm}):`);
+		console.log(`Note: ${staleImages.length} cache item(s) older than current long-term (${longTerm}):`);
 		for (const e of staleImages) console.log(`  - ${e.basename} (${e.version})`);
 		console.log("  Hint: 'quickchr cache prune --older-than " + longTerm + "' to evict them.");
 		console.log();
@@ -3174,6 +3188,7 @@ Commands:
   console <name>          Attach to serial console of a running instance
   exec <name> <command>   Run a RouterOS CLI command on a running instance
                           (raw /rest/execute — see 'quickchr exec --help' for centrs)
+  qga <name> <operation>  Query the QEMU Guest Agent (x86 only)
   remove [<name>|--all]   Remove instance(s) and disk
   clean [<name>|--all]    Reset instance disk to fresh image
   get <name> [group]      Show machine config (license, device-mode, admin)
@@ -3182,7 +3197,7 @@ Commands:
   disk <name>             Show disk details for an instance
   snapshot <name> [cmd]   Manage snapshots (list/save/load/delete)
   networks                Network discovery & socket management
-  cache [add|key|list|prune|clear] Manage cached CHR images
+  cache [add|key|list|prune|clear] Manage cached CHR images and packages
   settings [print|get|set|reset]  Manage quickchr's own global settings (quickchr.env)
   completions             Manage shell completions (Tab completion)
   logs <name>             Tail the QEMU log for an instance
@@ -3292,6 +3307,13 @@ Examples:
   quickchr exec my-chr ":put [:serialize to=json [/ip/address/print]]"
   quickchr exec my-chr "/log/info message=hello"
 
+Exit status:
+  0 means the command was delivered, not that RouterOS accepted it. A rejected
+  command (e.g. "failure: invalid user name") still exits 0, with
+  RouterOS's message as the output. For a pass/fail exit code, use centrs
+  (a write command needs --yes when not run at a TTY):
+    centrs execute --quickchr <name> --yes <command>
+
 ${CENTRS_SEE_ALSO}`);
 			break;
 		case "start":
@@ -3606,7 +3628,9 @@ Options:
 		case "cache":
 			console.log(`quickchr cache <add|key|list|prune|clear> [options]
 
-Manage cached CHR images in the data dir cache directory.
+Manage cached CHR images and package archives in the data dir cache directory.
+An all-packages archive and its extraction are one entry; an interrupted download
+is a partial entry. Files quickchr did not write are reported, never deleted.
 
 Subcommands:
   add [--channel <ch> | --version <ver>] [--arch <arch>] [--json]
@@ -3614,14 +3638,16 @@ Subcommands:
   key [--channel <ch> | --version <ver>] [--arch <arch>] [--json]
                                       Print cache directory, resolved version, and architecture for CI.
                                       Without --json, output is GITHUB_OUTPUT-compatible key=value lines.
-  list [--json]                       List cached images (basename, version, arch, size, age, in-use).
-  prune [options]                     Evict cached images per policy. Never evicts in-use images.
-    --older-than <ver>                Evict images with version < <ver>.
-    --max-age <dur>                   Evict images older than duration (e.g. 7d, 24h).
-    --max-size <size>                 Evict oldest-version images until total size <= <size>.
+  list [--json]                       List cache entries (basename, version, arch, size, age, in-use).
+  prune [options]                     Evict cache entries per policy. Never evicts in-use entries.
+    --older-than <ver>                Evict entries with version < <ver>.
+    --max-age <dur>                   Evict entries not used for longer than duration (e.g. 7d, 24h).
+    --max-size <size>                 Evict entries until total size <= <size>: partial downloads
+                                      first, then oldest RouterOS version.
     --dry-run                         Show what would be evicted without deleting.
-  clear --all                         Delete all non-in-use cached images.
+  clear --all                         Delete all non-in-use cache entries.
 
+A failed delete is listed on stderr, is not counted as freed, and exits 1.
 Duration: <N>(s|m|h|d|w)   Size: <N>(K|M|G|T)[i][B] (case-insensitive, IEC binary).
 
 Default auto-prune cap: 2 GiB — override via 'quickchr settings set cache-max-size <size>'
@@ -3641,6 +3667,8 @@ Managed keys:
                     auto|tcg|hvf|kvm (default: auto = detect)
   cache-max-size    Auto-prune cap applied after each successful start.
                     Size string (e.g. 2G, 512M). (default: 2G)
+  storage-reserve   Free space creating a machine or filling the cache must
+                    leave, beyond what it writes. Size string. (default: 2G)
   timeout-extra     Default for 'start's --timeout-extra/-T when omitted.
                     Non-negative integer seconds. (default: 0)
   secure-login      Default for 'add'/'start's --secure-login when neither

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