@tikoci/quickchr 0.4.8 → 0.5.1

package/src/cli/wizard.ts

@@ -81,6 +81,11 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 				if (!/^\d+\.\d+(\.\d+)?(beta\d+|rc\d+)?$/.test(v)) {
 					return "Invalid version format";
 				}
+				// RouterOS 6 is a CLI-only boot target (#182) — the wizard offers
+				// provisioning at every step, none of which 6.x can take.
+				if (/^6\./.test(v)) {
+					return "RouterOS 6 is boot-only and not offered here — use: quickchr add --version <6.x> --arch x86";
+				}
 			},
 		});
 		if (clack.isCancel(ver)) { clack.cancel("Cancelled."); process.exit(0); }
@@ -557,7 +562,8 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 	const background = await clack.select({
 		message: "Run mode:",
 		options: [
-			{ value: true, label: "Background", hint: "returns immediately" },
+			// Not "returns immediately": a background start waits for RouterOS to be ready (#159).
+			{ value: true, label: "Background", hint: "console logged; returns when RouterOS is ready" },
 			{ value: false, label: "Foreground", hint: "serial console on stdio" },
 		],
 		initialValue: true,
@@ -566,8 +572,10 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 
 	// 11. Confirm
 	const opts: StartOptions = {
+		// The channel has already been resolved into `version` above; passing both reads
+		// to start() as a caller asking for two releases.
 		version,
-		channel,
+		channel: version ? undefined : channel,
 		arch,
 		name: name || undefined,
 		cpu: Number(cpu),

package/src/index.ts

@@ -64,6 +64,8 @@ export type {
 	ServiceEndpoint,
 	ServiceName,
 	SnapshotInfo,
+	ShutdownOptions,
+	ShutdownResult,
 	SshServiceEndpoint,
 	StartOptions,
 } from "./lib/types.ts";

package/src/lib/api-login.ts

@@ -0,0 +1,138 @@
+/**
+ * Native API (`/login` on guest port 8728) as a readiness signal.
+ *
+ * Built for RouterOS 6, which has no REST API, so the REST probe can never succeed
+ * against it — the field report behind #182 watched a 6.49 guest answer www, ssh and
+ * api from 15 s in, then get removed at 180 s for not answering `/rest`. It is written
+ * as a general alternative to the REST probe rather than a v6 special case: a 7.x
+ * guest with REST disabled is the same problem.
+ *
+ * Only the post-6.43 plain login is spoken (`=name=` + `=password=` in one sentence).
+ * Grounded against CHR 6.49.23 under HVF, 2026-10-21:
+ *
+ * - `admin` / empty password → `!done`, as one 7-byte reply.
+ * - wrong user or password → `!trap =message=invalid user name or password (6)`
+ *   followed by `!done`, in the same read.
+ *
+ * Either answer means the API service is up, the way a REST 401 does — the probe is a
+ * readiness check, not a credential check.
+ */
+
+import { connect } from "node:net";
+
+/** Encode one API word length (RouterOS API "length" prefix, 1–5 bytes). */
+export function encodeApiLength(length: number): Uint8Array {
+	if (length < 0x80) return Uint8Array.of(length);
+	if (length < 0x4000) return Uint8Array.of((length >> 8) | 0x80, length & 0xff);
+	if (length < 0x200000) return Uint8Array.of((length >> 16) | 0xc0, (length >> 8) & 0xff, length & 0xff);
+	if (length < 0x10000000) {
+		return Uint8Array.of((length >>> 24) | 0xe0, (length >> 16) & 0xff, (length >> 8) & 0xff, length & 0xff);
+	}
+	return Uint8Array.of(0xf0, (length >>> 24) & 0xff, (length >> 16) & 0xff, (length >> 8) & 0xff, length & 0xff);
+}
+
+/** A sentence is its words, each length-prefixed, then a zero-length word. */
+export function encodeApiSentence(words: string[]): Uint8Array {
+	const encoder = new TextEncoder();
+	const parts: Uint8Array[] = [];
+	for (const word of words) {
+		const bytes = encoder.encode(word);
+		parts.push(encodeApiLength(bytes.length), bytes);
+	}
+	parts.push(Uint8Array.of(0));
+	const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+}
+
+/** Decode a length prefix at `offset`. `null` when the buffer ends inside it. */
+function decodeApiLength(buf: Uint8Array, offset: number): { length: number; size: number } | null {
+	const first = buf[offset];
+	if (first === undefined) return null;
+	const size = (first & 0x80) === 0 ? 1
+		: (first & 0xc0) === 0x80 ? 2
+		: (first & 0xe0) === 0xc0 ? 3
+		: (first & 0xf0) === 0xe0 ? 4
+		: 5;
+	if (offset + size > buf.length) return null;
+	let length = size === 5 ? 0 : first & (0xff >> size);
+	for (let i = 1; i < size; i++) length = length * 256 + (buf[offset + i] ?? 0);
+	return { length, size };
+}
+
+/** Every complete sentence in `buf`; a trailing partial sentence is left out. */
+export function parseApiSentences(buf: Uint8Array): string[][] {
+	const decoder = new TextDecoder();
+	const sentences: string[][] = [];
+	let words: string[] = [];
+	let offset = 0;
+	while (offset < buf.length) {
+		const prefix = decodeApiLength(buf, offset);
+		if (!prefix || offset + prefix.size + prefix.length > buf.length) break;
+		offset += prefix.size;
+		if (prefix.length === 0) {
+			sentences.push(words);
+			words = [];
+			continue;
+		}
+		words.push(decoder.decode(buf.subarray(offset, offset + prefix.length)));
+		offset += prefix.length;
+	}
+	return sentences;
+}
+
+export type ApiLoginResult =
+	/** `!done` with no `!trap` — logged in. */
+	| { outcome: "done" }
+	/** `!trap` then `!done` — the service answered and refused the credentials. */
+	| { outcome: "trap"; message: string }
+	/** `!fatal` — the service answered and closed the session (e.g. too many sessions). */
+	| { outcome: "fatal"; message: string };
+
+/** What the reply sentences say, once a `!done` or `!fatal` has arrived. `null` while
+ *  the login is still unanswered. */
+export function classifyLoginReply(sentences: string[][]): ApiLoginResult | null {
+	const messageOf = (sentence: string[]) =>
+		sentence.find((w) => w.startsWith("=message="))?.slice("=message=".length) ?? sentence.slice(1).join(" ");
+	const fatal = sentences.find((s) => s[0] === "!fatal");
+	if (fatal) return { outcome: "fatal", message: messageOf(fatal) };
+	if (!sentences.some((s) => s[0] === "!done")) return null;
+	const trap = sentences.find((s) => s[0] === "!trap");
+	return trap ? { outcome: "trap", message: messageOf(trap) } : { outcome: "done" };
+}
+
+/** One `/login` round trip on `127.0.0.1:<port>`. Rejects on a socket error, on a close
+ *  before the reply completes ("closed before reply"), and on the deadline
+ *  ("apiLogin timeout") — the shapes `classifyProbeError()` sorts into outcomes. */
+export function apiLogin(port: number, user: string, password: string, timeoutMs = 3000): Promise<ApiLoginResult> {
+	return new Promise((resolve, reject) => {
+		const socket = connect(port, "127.0.0.1");
+		let received = new Uint8Array(0);
+		let settled = false;
+		const finish = (fn: () => void) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			socket.destroy();
+			fn();
+		};
+		const timer = setTimeout(() => finish(() => reject(new Error("apiLogin timeout"))), timeoutMs);
+		socket.on("connect", () => {
+			socket.write(encodeApiSentence(["/login", `=name=${user}`, `=password=${password}`]));
+		});
+		socket.on("data", (chunk: Uint8Array) => {
+			const next = new Uint8Array(received.length + chunk.length);
+			next.set(received);
+			next.set(chunk, received.length);
+			received = next;
+			const result = classifyLoginReply(parseApiSentences(received));
+			if (result) finish(() => resolve(result));
+		});
+		socket.on("error", (err) => finish(() => reject(err)));
+		socket.on("close", () => finish(() => reject(new Error("closed before reply"))));
+	});
+}

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