@tikoci/quickchr 0.4.6 → 0.4.8

package/src/lib/names.ts

@@ -0,0 +1,72 @@
+/**
+ * Resource-name validation — machine names and named-socket names.
+ *
+ * Both become a path segment under the data dir (`machines/<name>/`,
+ * `networks/<name>.json`), so a name is not free text: it has to be safe to join
+ * onto a path and safe to type back into a command. A name starting with `-`
+ * also reads as a flag everywhere it is echoed (`quickchr remove --help`), which
+ * is how `networks sockets create --help` persisted a socket called `--help` (#156).
+ */
+
+import { QuickCHRError } from "./types.ts";
+
+/** Letters, digits, dot, underscore, hyphen — the charset already produced by
+ *  `generateMachineName()` (e.g. `7.24.4-x86-1`), minus anything a shell or a
+ *  path would reinterpret. */
+const VALID_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+const MAX_NAME_LENGTH = 64;
+
+/** Throw `INVALID_NAME` unless `name` is safe as both a path segment and a CLI argument.
+ *  `kind` names the resource in the message ("machine", "named socket"). */
+export function assertValidResourceName(name: string, kind: string): void {
+	const reject = (why: string) => {
+		throw new QuickCHRError("INVALID_NAME", `Invalid ${kind} name "${name}" — ${why}`);
+	};
+
+	if (name.length === 0) reject("names cannot be empty");
+	if (name.startsWith("-")) reject(`names cannot start with "-" (it would be read as a flag)`);
+	if (name.length > MAX_NAME_LENGTH) reject(`names are limited to ${MAX_NAME_LENGTH} characters`);
+	if (!VALID_NAME.test(name)) {
+		reject("names may contain only letters, digits, dot, underscore and hyphen, and must start with a letter or digit");
+	}
+}
+
+/** The weaker rule that applies to a name being *used*, not created.
+ *
+ *  `assertValidResourceName()` cannot guard a lookup or a delete: machines created
+ *  under the older, looser rules have to stay addressable. But a name still becomes a
+ *  path segment, and `join(machinesDir, name)` happily normalizes `..` into the data
+ *  directory itself — so `removeOrphan("..")` would `rmSync` every machine, the cache
+ *  and the socket registry. This is the minimum that stops that while passing every
+ *  name a real machine can have. */
+export function isPathSafeName(name: string): boolean {
+	if (name.length === 0) return false;
+	if (name === "." || name === "..") return false;
+	if (name.includes("/") || name.includes("\0")) return false;
+	// `\` is a path separator on Windows and an ordinary filename character on POSIX.
+	// Rejecting it everywhere would strand a machine named `lab\old` under the older,
+	// looser creation rules: `list` still shows it, so `remove` has to still clear it.
+	if (process.platform === "win32" && name.includes("\\")) return false;
+	return true;
+}
+
+/** Throwing form of {@link isPathSafeName}, for the paths that delete. */
+export function assertPathSafeName(name: string, kind: string): void {
+	if (!isPathSafeName(name)) {
+		throw new QuickCHRError(
+			"INVALID_NAME",
+			`Invalid ${kind} name ${JSON.stringify(name)} — a name cannot be empty, "." or "..", or contain a path separator`,
+		);
+	}
+}
+
+/** Non-throwing form, for callers that want to branch rather than fail. */
+export function isValidResourceName(name: string): boolean {
+	try {
+		assertValidResourceName(name, "resource");
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/lib/net.ts

@@ -19,7 +19,9 @@
  * error), we retry by resolving the A record against a public DNS server
  * directly (~10 ms), bypassing the host's resolv.conf, and connecting to the
  * IPv4 literal with the `Host` header and TLS SNI preserved so certificate
- * validation still passes.
+ * validation still passes. If that attempt fails too, both failures are reported
+ * together as a `ResilientFetchError` — the fallback's own error names only an IP
+ * literal, which on its own reads as a host nobody configured.
  *
  * Only connection-class failures trigger the fallback; HTTP responses (incl.
  * 5xx) and aborts (`AbortError`, e.g. from `AbortSignal.timeout`) pass through
@@ -32,6 +34,49 @@ import { promises as dns } from "node:dns";
 const PUBLIC_DNS_SERVERS = ["1.1.1.1", "8.8.8.8", "1.0.0.1"];
 const DNS_TIMEOUT_MS = 3000;
 
+/** `CODE: message` when the error carries a code, else just the message. */
+function describeError(err: unknown): string {
+	if (!err || typeof err !== "object") return String(err);
+	const e = err as { name?: string; message?: string; code?: string; cause?: { code?: string } };
+	const code = e.code ?? e.cause?.code;
+	const label = code ?? e.name;
+	const message = e.message ?? String(err);
+	return label ? `${label}: ${message}` : message;
+}
+
+/**
+ * Both transports failed: the direct fetch with a connection-class error, and
+ * then the public-DNS/IPv4 fallback too.
+ *
+ * It exists because the fallback's own error is unreadable on its own — it names
+ * an IP literal nobody configured and no hostname, so a log cannot distinguish
+ * "the system resolver was broken" from "the host refused us" from "public DNS
+ * handed back a bad address" (#121). The message carries the URL, both failures,
+ * and which address the fallback tried; the direct failure is also the `cause`.
+ */
+export class ResilientFetchError extends Error {
+	/** The hostname both transports were aiming at. */
+	readonly host: string;
+	/** The IPv4 literal the fallback connected to, from public DNS. */
+	readonly address: string;
+	/** The fallback transport's failure. The direct attempt's is `cause`. */
+	readonly fallbackError: unknown;
+
+	constructor(url: string, address: string, directError: unknown, fallbackError: unknown) {
+		const host = new URL(url).hostname;
+		super(
+			`Fetch failed for ${url} on both transports: ` +
+				`system resolver — ${describeError(directError)}; ` +
+				`public DNS (${PUBLIC_DNS_SERVERS.join(", ")}) → ${address} — ${describeError(fallbackError)}`,
+			{ cause: directError },
+		);
+		this.name = "ResilientFetchError";
+		this.host = host;
+		this.address = address;
+		this.fallbackError = fallbackError;
+	}
+}
+
 /**
  * True for the connection-class failures raised when a socket cannot be opened
  * (e.g. IPv4 blocked on an IPv6-only network, or Bun's `errno: 0`
@@ -39,9 +84,14 @@ const DNS_TIMEOUT_MS = 3000;
  * the standard connect errors. Excludes `AbortError` (aborts/`AbortSignal`
  * timeouts) and HTTP-level outcomes (those carry a Response and never throw
  * here). Used to decide whether to fall back from the normal fetch to the
- * public-DNS IPv4 attempt.
+ * public-DNS IPv4 attempt, and by callers deciding whether a failure is worth
+ * another attempt.
  */
 export function isConnectionFailure(err: unknown): boolean {
+	// Connection-class by construction: fetchResilient raises this only after a
+	// direct failure that already passed this test. Callers retrying on a
+	// connection failure must keep retrying once the fallback also fails.
+	if (err instanceof ResilientFetchError) return true;
 	if (!err || typeof err !== "object") return false;
 	const e = err as { name?: string; code?: string; errno?: number; cause?: { code?: string } };
 	if (e.name === "AbortError") return false;
@@ -142,6 +192,12 @@ export async function fetchResilient(url: string, init?: BunFetchRequestInit): P
 		const address = await resolveIpv4(new URL(url).hostname);
 		// Public DNS can't help (unreachable / no answer) — surface the original failure.
 		if (address === undefined) throw err;
-		return fetchOverIpv4(url, address, init);
+		try {
+			return await fetchOverIpv4(url, address, init);
+		} catch (fallbackErr) {
+			// Never let the fallback's error stand alone: it names only an IP literal,
+			// which is the one thing the reader cannot map back to what was attempted.
+			throw new ResilientFetchError(url, address, err, fallbackErr);
+		}
 	}
 }

package/src/lib/network.ts

@@ -20,7 +20,13 @@ import {
 	SERVICE_PORTS,
 	QuickCHRError,
 } from "./types.ts";
-import { getNamedSocket } from "./socket-registry.ts";
+import {
+	getNamedSocket,
+	getSocketSlot,
+	socketEndpointPath,
+	type SocketEntry,
+} from "./socket-registry.ts";
+import { assertValidResourceName } from "./names.ts";
 import { resolveInterfaceAlias, isSocketVmnetDaemonRunning } from "./platform.ts";
 
 /** Allocate a port block for a new instance, avoiding conflicts with existing machines. */
@@ -329,6 +335,9 @@ function parseSocketSpecifier(input: string): NetworkSpecifier {
 				"socket:: requires a link name (e.g. socket::mylink)",
 			);
 		}
+		// start() auto-creates a registry entry (and a networks/<name>.json file) for an
+		// unknown name, so the specifier is the other door into createNamedSocket().
+		assertValidResourceName(name, "named socket");
 		return { type: "socket", name };
 	}
 
@@ -388,6 +397,80 @@ export function resolveStartNetworks(
 	return [{ specifier: "user", id: "net0" }];
 }
 
+/** Derive a stable MAC for one NIC of one machine.
+ *
+ * QEMU's default is `52:54:00:12:34:56` incremented per NIC **within** a guest, so
+ * NIC index *N* holds the same address in *every* guest. Harmless while machines
+ * only have `user` NICs (separate SLIRP namespaces), fatal the moment two share an
+ * L2 segment — a named socket, a listen/connect pair, a TAP, or a RouterOS bridge
+ * on a hub VM. Forwarding then breaks in ways that look like a RouterOS or overlay
+ * defect rather than a launcher one (#154).
+ *
+ * The first octet is `0x02`: locally administered (bit 1 set) and unicast (bit 0
+ * clear), so these never collide with a vendor-assigned address. The remaining five
+ * octets come from a SHA-256 of the machine name, NIC index and `salt`, which makes
+ * the address reproducible for a given name instead of random per boot — the same
+ * lab rebuilt under the same names presents the same addresses.
+ */
+export function deriveMac(name: string, index: number, salt = 0): string {
+	const digest = new Bun.CryptoHasher("sha256")
+		.update(`${name}\u0000${index}\u0000${salt}`)
+		.digest();
+	// Five octets after the fixed `02`, so a NIC's address is 48 bits total.
+	const octets = Array.from(digest.subarray(0, 5), (o) =>
+		o.toString(16).padStart(2, "0"),
+	);
+	return ["02", ...octets].join(":");
+}
+
+/** Assign a MAC to every NIC that lacks one, avoiding `taken`.
+ *
+ * Mutates and returns `networks`. Idempotent: a NIC that already has a MAC keeps it,
+ * so a machine's addresses are fixed at creation and survive restart, a re-resolve on
+ * a different platform, and any later change to {@link deriveMac} itself.
+ *
+ * **Call this only where a machine is created.** Changing a MAC on a machine that has
+ * already booted breaks it: RouterOS ties its persisted interface identity to the
+ * address, so a new one orphans the `ether1` holding the DHCP client and the guest
+ * comes up with no IP. Verified by A/B on a live CHR — see DESIGN.md, "NIC MAC
+ * Addresses". Machines created before #154 keep QEMU's defaults and must be recreated.
+ *
+ * A SHA-256 collision across five octets is vanishingly unlikely, but `taken` makes
+ * the guarantee structural rather than probabilistic — a duplicate here is the exact
+ * silent-L2 failure this exists to prevent, so it is worth not leaving to odds.
+ *
+ * `taken` is a snapshot, so two concurrent creations can each miss the other. That
+ * only changes an outcome when the two would otherwise have collided — i.e. on top
+ * of that 2^-40 event — but the window is real. It is the same read-then-write
+ * window the port allocator has on the adjacent line (`getUsedPortBases()` →
+ * `findAvailablePortBlock()` → `saveMachine()`), where it fires routinely and
+ * breaks starts outright: #140. Both allocators want one lock around
+ * read-allocate-persist; adding a second, MAC-only lock here would leave the
+ * frequent half of the race unfixed while implying it was handled.
+ */
+export function assignMacs(
+	name: string,
+	networks: NetworkConfig[],
+	taken: ReadonlySet<string> = new Set(),
+): NetworkConfig[] {
+	const used = new Set(taken);
+	for (const n of networks) {
+		if (n.mac) used.add(n.mac);
+	}
+	networks.forEach((n, i) => {
+		if (n.mac) return;
+		let salt = 0;
+		let mac = deriveMac(name, i, salt);
+		while (used.has(mac)) {
+			salt++;
+			mac = deriveMac(name, i, salt);
+		}
+		used.add(mac);
+		n.mac = mac;
+	});
+	return networks;
+}
+
 /** Returns true when at least one network uses QEMU user-mode (hostfwd) networking.
  *  Only user-mode networks forward localhost ports — shared/bridged/tap/socket networks
  *  assign a DHCP address that is not reachable from host localhost. */
@@ -400,10 +483,26 @@ export function hasUserModeNetwork(networks: NetworkConfig[]): boolean {
 export interface ResolutionContext {
 	platform: PlatformInfo;
 	socketVmnet?: SocketVmnetInfo;
+	/** Machine being resolved. A named socket's endpoint role is per-machine, so the
+	 *  resolver needs to know who is asking; absent for callers that only want the
+	 *  shape of a specifier (dry runs, unit tests over the non-socket modes). */
+	machine?: string;
+	/** QEMU version string, when the caller knows it. `-netdev dgram` landed in 7.2;
+	 *  an unknown version does not block, because refusing to run on a QEMU we merely
+	 *  failed to parse is worse than the error the spawn would give. */
+	qemuVersion?: string;
 }
 
-function deviceArgs(id: string): string[] {
-	return ["-device", `virtio-net-pci,netdev=${id}`];
+/** `-device` for one NIC — the **only** place a NIC device is emitted.
+ *
+ *  Takes the whole {@link NetworkConfig} rather than an id so a caller physically
+ *  cannot emit a NIC without its MAC. `qemu.ts`'s fallback path builds its own
+ *  `-netdev` strings but shares this, so both paths carry the address; every guest
+ *  would otherwise get QEMU's default `52:54:00:12:34:56` sequence and two machines
+ *  bridged onto one L2 segment would collide (#154). */
+export function deviceArgs(config: NetworkConfig): string[] {
+	const mac = config.mac ? `,mac=${config.mac}` : "";
+	return ["-device", `virtio-net-pci,netdev=${config.id}${mac}`];
 }
 
 function resolveUser(
@@ -416,7 +515,7 @@ function resolveUser(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", netdevValue,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -438,7 +537,7 @@ function resolveShared(
 			return {
 				qemuNetdevArgs: [
 					"-netdev", `socket,id=${config.id},fd=3`,
-					...deviceArgs(config.id),
+					...deviceArgs(config),
 				],
 				wrapper: [svn.client, svn.sharedSocket],
 			};
@@ -446,7 +545,7 @@ function resolveShared(
 		return {
 			qemuNetdevArgs: [
 				"-netdev", `vmnet-shared,id=${config.id}`,
-				...deviceArgs(config.id),
+				...deviceArgs(config),
 			],
 			downgraded: {
 				from: "shared (socket_vmnet)",
@@ -473,7 +572,7 @@ function resolveVmnetShared(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", `vmnet-shared,id=${config.id}`,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -498,7 +597,7 @@ function resolveBridged(
 			return {
 				qemuNetdevArgs: [
 					"-netdev", `socket,id=${config.id},fd=3`,
-					...deviceArgs(config.id),
+					...deviceArgs(config),
 				],
 				wrapper: [svn.client, bridgeSocket],
 			};
@@ -506,7 +605,7 @@ function resolveBridged(
 		return {
 			qemuNetdevArgs: [
 				"-netdev", `vmnet-bridged,id=${config.id},ifname=${resolved}`,
-				...deviceArgs(config.id),
+				...deviceArgs(config),
 			],
 			downgraded: {
 				from: `bridged:${iface} (socket_vmnet)`,
@@ -534,14 +633,45 @@ function resolveVmnetBridged(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", `vmnet-bridged,id=${config.id},ifname=${iface}`,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
 
+/** One-line description of the transport a named socket resolved to, for the line
+ *  `start` prints and for `list`/`info`. The acceptance bar for #158's visibility
+ *  work is that nothing about a named socket requires opening a file under the data
+ *  dir, and this is what makes that true. */
+export function describeSocketTransport(entry: SocketEntry, slot?: number): string {
+	switch (entry.mode) {
+		case "mcast":
+			return `UDP multicast ${entry.mcastGroup}:${entry.port} (N-way)`;
+		case "listen-connect":
+			if (slot === undefined) return `TCP pair on 127.0.0.1:${entry.port}`;
+			return slot === 0
+				? `TCP 127.0.0.1:${entry.port} (listening)`
+				: `TCP 127.0.0.1:${entry.port} (connecting)`;
+		case "dgram": {
+			// Unoccupied: name the pair once rather than printing the directory twice.
+			if (slot === undefined) {
+				return `unix datagram ${socketEndpointPath(entry.name, 0).replace(/\.0\.sock$/, ".{0,1}.sock")}`;
+			}
+			const peer = slot === 0 ? 1 : 0;
+			return `unix datagram ${socketEndpointPath(entry.name, slot)} -> ${socketEndpointPath(entry.name, peer)}`;
+		}
+	}
+}
+
+/** `-netdev dgram` was added in QEMU 7.2. */
+export function qemuSupportsDgram(version: string): boolean {
+	const [major = 0, minor = 0] = version.split(".").map((p) => Number.parseInt(p, 10) || 0);
+	return major > 7 || (major === 7 && minor >= 2);
+}
+
 function resolveSocketNamed(
 	config: NetworkConfig,
 	name: string,
+	ctx: ResolutionContext,
 ): ResolvedNetwork {
 	const entry = getNamedSocket(name);
 	if (!entry) {
@@ -554,18 +684,60 @@ function resolveSocketNamed(
 		return {
 			qemuNetdevArgs: [
 				"-netdev", `socket,id=${config.id},mcast=${entry.mcastGroup}:${entry.port}`,
-				...deviceArgs(config.id),
+				...deviceArgs(config),
+			],
+		};
+	}
+
+	// Two-member modes carry a role. It comes from the persisted slot, claimed when the
+	// machine joined, so a listener that stops and restarts comes back as the listener
+	// instead of silently demoting itself to a second connector.
+	const slot = ctx.machine ? getSocketSlot(entry, ctx.machine) : undefined;
+	if (slot === undefined) {
+		const held = entry.endpoints?.filter((m): m is string => m !== null) ?? [];
+		const who = held.length > 0 ? held.join(" and ") : "no machine";
+		throw new QuickCHRError(
+			"NETWORK_UNAVAILABLE",
+			ctx.machine
+				? `Machine "${ctx.machine}" holds no endpoint on named socket "${name}" — it is a ${entry.mode} link, and its two ends are held by ${who}.`
+				: `Named socket "${name}" is a ${entry.mode} link, so resolving it needs the machine's name (its endpoint role is per-machine). Pass 'machine' in the resolution context.`,
+		);
+	}
+
+	if (entry.mode === "dgram") {
+		// Windows first: it cannot have this transport at any QEMU version.
+		if (ctx.platform.os === "win32") {
+			throw new QuickCHRError(
+				"NETWORK_UNAVAILABLE",
+				`Named socket "${name}" is a unix-datagram link, which Windows cannot provide (AF_UNIX has no SOCK_DGRAM). ` +
+				`Recreate it with 'quickchr networks sockets create ${name} --mode listen-connect'.`,
+			);
+		}
+		if (ctx.qemuVersion && !qemuSupportsDgram(ctx.qemuVersion)) {
+			throw new QuickCHRError(
+				"NETWORK_UNAVAILABLE",
+				`Named socket "${name}" is a unix-datagram link, which needs QEMU 7.2 or newer (found ${ctx.qemuVersion}). ` +
+				`Upgrade QEMU, or recreate the socket with 'quickchr networks sockets create ${name} --mode listen-connect'.`,
+			);
+		}
+		const local = socketEndpointPath(name, slot);
+		const remote = socketEndpointPath(name, slot === 0 ? 1 : 0);
+		return {
+			qemuNetdevArgs: [
+				"-netdev",
+				`dgram,id=${config.id},local.type=unix,local.path=${local},remote.type=unix,remote.path=${remote}`,
+				...deviceArgs(config),
 			],
 		};
 	}
-	const isFirst = entry.members.length === 0;
-	const netdevArg = isFirst
+
+	const netdevArg = slot === 0
 		? `socket,id=${config.id},listen=:${entry.port}`
 		: `socket,id=${config.id},connect=127.0.0.1:${entry.port}`;
 	return {
 		qemuNetdevArgs: [
 			"-netdev", netdevArg,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -577,7 +749,7 @@ function resolveSocketListen(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", `socket,id=${config.id},listen=:${port}`,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -589,7 +761,7 @@ function resolveSocketConnect(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", `socket,id=${config.id},connect=127.0.0.1:${port}`,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -602,7 +774,7 @@ function resolveSocketMcast(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", `socket,id=${config.id},mcast=${group}:${port}`,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -621,7 +793,7 @@ function resolveTap(
 	return {
 		qemuNetdevArgs: [
 			"-netdev", `tap,id=${config.id},ifname=${ifname},script=no,downscript=no`,
-			...deviceArgs(config.id),
+			...deviceArgs(config),
 		],
 	};
 }
@@ -650,7 +822,7 @@ export function resolveNetworkConfig(
 				resolved = resolveVmnetBridged(config, spec.iface, ctx);
 				break;
 			case "socket":
-				resolved = resolveSocketNamed(config, spec.name);
+				resolved = resolveSocketNamed(config, spec.name, ctx);
 				break;
 			case "socket-listen":
 				resolved = resolveSocketListen(config, spec.port);

package/src/lib/packages.ts

@@ -2,18 +2,62 @@
  * Extra package download and installation for CHR instances.
  */
 
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { join, basename } from "node:path";
-import type { Arch } from "./types.ts";
-import { QuickCHRError } from "./types.ts";
+import { QuickCHRError, type Arch } from "./types.ts";
 import { packagesDownloadUrl } from "./versions.ts";
-import { fetchResilient } from "./net.ts";
+import { downloadToFile } from "./download.ts";
 import { getCacheDir, ensureDir } from "./state.ts";
 import { createLogger, type ProgressLogger } from "./log.ts";
 import { restPost } from "./rest.ts";
 import { scpPush } from "./scp.ts";
 import { extractZip } from "./zip.ts";
 
+const PACKAGE_CACHE_MANIFEST = ".quickchr-complete.json";
+
+interface PackageCacheManifest {
+	version: string;
+	arch: Arch;
+	archiveSize: number;
+	packages: Array<{ name: string; size: number }>;
+}
+
+function packageFiles(extractDir: string): Array<{ name: string; size: number }> {
+	try {
+		return readdirSync(extractDir)
+			.filter((name) => name.endsWith(".npk"))
+			.map((name) => ({ name, size: statSync(join(extractDir, name)).size }))
+			.filter((entry) => entry.size > 0)
+			.sort((a, b) => a.name.localeCompare(b.name));
+	} catch {
+		return [];
+	}
+}
+
+/** Verify the archive and every package recorded after atomic extraction. */
+export async function isCompletePackageCache(
+	version: string,
+	arch: Arch,
+	cacheDir?: string,
+): Promise<boolean> {
+	const cache = cacheDir ?? getCacheDir();
+	const zipPath = join(cache, `all_packages-${arch}-${version}.zip`);
+	const extractDir = join(cache, `packages-${arch}-${version}`);
+	try {
+		const archiveSize = statSync(zipPath).size;
+		if (archiveSize <= 0) return false;
+		const manifest = await Bun.file(join(extractDir, PACKAGE_CACHE_MANIFEST)).json() as PackageCacheManifest;
+		const packages = packageFiles(extractDir);
+		return manifest.version === version &&
+			manifest.arch === arch &&
+			manifest.archiveSize === archiveSize &&
+			packages.length > 0 &&
+			JSON.stringify(manifest.packages) === JSON.stringify(packages);
+	} catch {
+		return false;
+	}
+}
+
 /** Download and extract the all-packages ZIP for a version/arch. Returns the extract dir. */
 export async function downloadPackages(
 	version: string,
@@ -29,30 +73,54 @@ export async function downloadPackages(
 	const zipPath = join(cache, zipName);
 	const extractDir = join(cache, `packages-${arch}-${version}`);
 
-	if (existsSync(extractDir)) {
+	if (await isCompletePackageCache(version, arch, cache)) {
 		const log = logger ?? createLogger();
 		log.status(`  Using cached packages: ${version} (${arch})`);
 		return extractDir;
 	}
 
-	// Download if needed
+	// Download if needed. Same bounded path as the image download (#116) — this
+	// call site previously had neither a deadline nor retries, so its only bound
+	// was whatever the calling test happened to impose.
 	if (!existsSync(zipPath)) {
 		const log = logger ?? createLogger();
 		log.status(`Downloading packages for ${version} (${arch})...`);
-		const response = await fetchResilient(url);
-		if (!response.ok) {
-			throw new QuickCHRError(
-				"DOWNLOAD_FAILED",
-				`Failed to download packages: HTTP ${response.status} for ${url}`,
-			);
+		log.status(`  ${url}`);
+		await downloadToFile(url, zipPath, { logger: log });
+	}
+
+	// Extract into a sibling directory, record the exact complete set, then
+	// rename it into place. A killed extraction can never look like a cache hit.
+	const tempDir = mkdtempSync(join(cache, ".quickchr-packages-"));
+	try {
+		extractZip(zipPath, tempDir);
+		const packages = packageFiles(tempDir);
+		if (packages.length === 0) {
+			throw new Error(`No non-empty .npk files found in ${zipName}`);
 		}
-		const buf = await response.arrayBuffer();
-		await Bun.write(zipPath, buf);
+		const manifest: PackageCacheManifest = {
+			version,
+			arch,
+			archiveSize: statSync(zipPath).size,
+			packages,
+		};
+		await Bun.write(join(tempDir, PACKAGE_CACHE_MANIFEST), `${JSON.stringify(manifest, null, "\t")}\n`);
+		if (existsSync(extractDir)) rmSync(extractDir, { recursive: true, force: true });
+		renameSync(tempDir, extractDir);
+	} catch (error) {
+		rmSync(tempDir, { recursive: true, force: true });
+		if (error instanceof Error && error.message.startsWith("No non-empty")) {
+			throw new QuickCHRError("PROCESS_FAILED", error.message);
+		}
+		throw error;
 	}
 
-	// Extract
-	ensureDir(extractDir);
-	extractZip(zipPath, extractDir);
+	if (!(await isCompletePackageCache(version, arch, cache))) {
+		throw new QuickCHRError(
+			"PROCESS_FAILED",
+			`Package cache verification failed for ${version} (${arch})`,
+		);
+	}
 
 	return extractDir;
 }