@tikoci/quickchr 0.4.5 → 0.4.7

package/src/lib/quickchr.ts

@@ -26,7 +26,7 @@ import type {
 } from "./types.ts";
 import { QuickCHRError, ARCHES, CHANNELS, SERVICE_IDS, QUICKCHR_DESCRIPTOR_VERSION } from "./types.ts";
 import packageJson from "../../package.json";
-import { detectPlatform, requireQemu, requireFirmware, getQemuVersion, getQemuInstallHint, isCrossArchEmulation, accelTimeoutFactor, detectAccel, findQemuImg, qgaKvmWarning, detectSocketVmnet, isSocketVmnetDaemonRunning, findCommandOnPath } from "./platform.ts";
+import { detectPlatform, requireQemu, requireFirmware, getQemuVersion, getQemuInstallHint, isCrossArchEmulation, accelTimeoutFactor, detectAccel, accelNote, resolveAccelOverrideWithSource, accelSourceLabel, findQemuImg, qgaKvmWarning, detectSocketVmnet, isSocketVmnetDaemonRunning, findCommandOnPath } from "./platform.ts";
 import {
 	resolveVersion,
 	isValidVersion,
@@ -56,7 +56,8 @@ import { autoPruneIfOverCap } from "./cache.ts";
 import { resolveSetting } from "./settings.ts";
 import { buildQemuArgs, spawnQemu, stopQemu, cleanupQemuSockets, waitForBoot, extractWrapper, type QemuLaunchConfig } from "./qemu.ts";
 import { cleanDiskFiles, ensureConfiguredDisks, normalizeDiskOptions, parseSnapshotList, listSnapshots, formatDiskSize } from "./disk.ts";
-import { monitorCommand, serialStreams, qgaCommand, channelEndpoint } from "./channels.ts";
+import { monitorCommand, serialStreams, qgaCommand, channelEndpoint, channelFileExists, channelPath } from "./channels.ts";
+import { captureBootFailure, newBootProbeStats, type BootFailureReport, type BootProbeStats, type FailureTrigger } from "./diagnostics.ts";
 import { installPackages, installAllPackages, downloadAndListPackages, downloadPackages, findPackageFile, uploadPackages } from "./packages.ts";
 import { provision } from "./provision.ts";
 import { renewLicense, getLicenseInfo } from "./license.ts";
@@ -65,7 +66,7 @@ import { scpPush, scpPull } from "./scp.ts";
 import { deleteInstanceCredentials, credentialStorageLabel, getStoredCredentials, getInstanceCredentials, STORED_IN_SECRETS_PASSWORD } from "./credentials.ts";
 import { restExecute } from "./exec.ts";
 import { qgaExec } from "./qga.ts";
-import { consoleExec } from "./console.ts";
+import { consoleExec, CONSOLE_LOGIN_COST_MS } from "./console.ts";
 import { restRequest, restGet, restPost } from "./rest.ts";
 import { createNamedSocket, getNamedSocket, addSocketMember, removeSocketMember } from "./socket-registry.ts";
 import { createLogger, type ProgressLogger } from "./log.ts";
@@ -79,6 +80,7 @@ import {
 	waitForDeviceModeApi,
 } from "./device-mode.ts";
 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, readdirSync, rmSync, copyFileSync, writeFileSync, unlinkSync, openSync, writeSync, closeSync, readFileSync } from "node:fs";
@@ -412,11 +414,11 @@ function createInstance(state: MachineState): ChrInstance {
 		captureInterface: process.platform === "darwin" ? "lo0" : "any",
 		tzspGatewayIp: "10.0.2.2",
 
-		async waitForBoot(timeoutMs?: number): Promise<boolean> {
+		async waitForBoot(timeoutMs?: number, stats?: BootProbeStats): Promise<boolean> {
 			// Use resolved credentials so waitForBoot can validate the response body
 			// on authenticated machines (post-provisioning, post-install reboots).
 			const auth = resolveAuth(state);
-			return waitForBoot(ports.http, timeoutMs, auth.header);
+			return waitForBoot(ports.http, timeoutMs, auth.header, stats);
 		},
 
 		async waitFor(condition: () => Promise<boolean>, timeoutMs = 30_000): Promise<boolean> {
@@ -487,18 +489,43 @@ function createInstance(state: MachineState): ChrInstance {
 				state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw"),
 			);
 
-			// Clean up stored instance credentials (re-provisioned on next start)
+			// Every guest-side credential went with the old disk, so the credential
+			// facts in machine.json now describe a machine that no longer exists.
+			// Nothing re-provisions them either: a post-clean() start() takes the
+			// `_launchExisting(…, undefined)` path (lastStartedAt is set), so the
+			// erased account is never recreated. Left in place, `resolveAuth()` /
+			// `resolveCreds()` prefer `state.user` and authenticate every REST call,
+			// exec, and SCP as a deleted user — the confound #79 removes here.
+			// Clearing them restores the documented fallback: factory `admin` with an
+			// empty password, which is what a fresh CHR image actually answers to
+			// (anchored by the "clean() resets disk to factory defaults" integration
+			// test). `disableAdmin` goes with them because it is read as a live fact
+			// about the guest (buildDescriptor's `disableAdminLockout`) and a fresh
+			// image has admin enabled again. Provisioning *intent* — packages,
+			// deviceMode, secureLogin — is not guest state and survives.
 			deleteInstanceCredentials(state.name);
+			// The managed keypair authenticated to the account factory reset erased,
+			// so it is dead credential material sitting in the machine dir. Removing
+			// it also keeps a future re-provision viable: `ssh-keygen -f <path>` on an
+			// existing file exits 1 with "already exists" rather than overwriting
+			// (verified locally), so a leftover key would break `installSshKey()`.
+			rmSync(join(state.machineDir, "ssh"), { recursive: true, force: true });
 
 			// Update state
 			const current = loadMachine(state.name);
 			if (current) {
 				current.status = "stopped";
 				current.pid = undefined;
+				current.user = undefined;
+				current.managedSshKey = undefined;
+				current.disableAdmin = undefined;
 				saveMachine(current);
 			}
 			state.status = "stopped";
 			state.pid = undefined;
+			state.user = undefined;
+			state.managedSshKey = undefined;
+			state.disableAdmin = undefined;
 		},
 
 		async monitor(command: string): Promise<string> {
@@ -950,6 +977,183 @@ async function waitForPidExit(pid: number, timeoutMs: number): Promise<boolean>
 	return false;
 }
 
+/** Where boot-failure reports land: `<dataDir>/failures/`, deliberately outside
+ *  any machine directory so `remove()` — which every integration test calls from
+ *  its `finally` — cannot delete the evidence it was written to explain (#79). */
+function bootFailureReportDir(): string {
+	return join(getDataDir(), "failures");
+}
+
+/**
+ * How long one credential candidate gets inside a single guest-exec call.
+ *
+ * `timeoutMs` is a budget for the whole call, not per attempt: `captureGuestSnapshot()`
+ * sizes its own budget assuming one exec costs at most what it passed in, so N
+ * candidates × the full timeout would spend the snapshot's entire budget on the
+ * first query. Untried candidates therefore share it, and once a credential is
+ * known to work it gets all of it — which is every query after the first.
+ *
+ * The floor is {@link CONSOLE_LOGIN_COST_MS} rather than a round number, because
+ * a share below the cost of a login cannot succeed **by construction** — and a
+ * candidate that can never succeed also never becomes the working one, so every
+ * later query repeats the same doomed division. The floor used to be 5 s against
+ * a measured 11.4 s login, which is why forensics reported "console unreachable"
+ * for guests that were answering serial in 10 ms (#69). A share this large is
+ * affordable only because `captureGuestSnapshot()` adds a login allowance to its
+ * query budget until the console answers; see `GUEST_LOGIN_ALLOWANCE_MS`.
+ *
+ * Exported for tests: this is the arithmetic the #69/B10 fix turns on, and it is
+ * otherwise reachable only through a live serial socket.
+ */
+export function credentialShareMs(timeoutMs: number, candidateCount: number, haveWorking: boolean): number {
+	if (haveWorking) return timeoutMs;
+	return Math.max(CONSOLE_LOGIN_COST_MS, Math.floor(timeoutMs / Math.max(1, candidateCount)));
+}
+
+/** Serial-console executor for boot forensics, or null when there is no serial
+ *  channel to talk to (foreground runs, or QEMU never got far enough).
+ *
+ *  Which account works depends on how far the failed boot got: a machine that
+ *  timed out before provisioning — and any machine after `clean()` — is factory
+ *  fresh and answers only to `admin` with an empty password, while a relaunch of
+ *  an already-provisioned machine needs its stored credentials. Rather than
+ *  guess, candidates are tried in order and the first that reaches a prompt is
+ *  reused for the rest of the snapshot. */
+function bootFailureGuestExec(state: MachineState): { exec: GuestExec; users: string[] } | null {
+	if (!channelFileExists(channelPath(state.machineDir, "serial"))) return null;
+
+	// Order matters only for speed — a wrong candidate costs a ~15 s login timeout
+	// before the next is tried. Stored credentials are the strongest evidence the
+	// machine is provisioned (provisioning stores them on success), so they lead;
+	// factory admin comes next because a cleaned machine has neither (`clean()`
+	// clears both the stored credentials and `state.user`), leaving `state.user`
+	// as the weakest case: a user configured on the machine but never provisioned
+	// onto the guest.
+	const candidates: { user: string; password: string }[] = [];
+	// Guarded even though secrets.ts already swallows unreadable/corrupt stores:
+	// this runs on the BOOT_TIMEOUT path *before* captureBootFailure(), so
+	// anything thrown here would replace the forensics report with an unrelated
+	// error — the exact failure mode the diagnostics modules exist to avoid.
+	let stored: { user: string; password: string } | null = null;
+	try {
+		stored = getInstanceCredentials(state.name);
+	} catch { /* no stored credentials — fall through to the other candidates */ }
+	if (stored) candidates.push(stored);
+	candidates.push({ user: "admin", password: "" });
+	if (state.user && state.user.name !== "admin" && state.user.password !== STORED_IN_SECRETS_PASSWORD) {
+		candidates.push({ user: state.user.name, password: state.user.password });
+	}
+
+	let working: { user: string; password: string } | undefined;
+	const exec: GuestExec = async (command, timeoutMs) => {
+		const order = working ? [working, ...candidates.filter((c) => c !== working)] : candidates;
+		const deadline = Date.now() + timeoutMs;
+		const share = credentialShareMs(timeoutMs, order.length, working !== undefined);
+		let lastError: unknown = new Error("no credential candidates");
+		for (const cred of order) {
+			const remaining = deadline - Date.now();
+			if (remaining <= 0) break;
+			try {
+				const { output, framed } = await consoleExec(
+					state.machineDir, command, cred.user, cred.password, Math.min(share, remaining), state.portBase,
+				);
+				working = cred;
+				return { output, framed };
+			} catch (e) {
+				lastError = e;
+			}
+		}
+		throw lastError instanceof Error ? lastError : new Error(String(lastError));
+	};
+
+	return { exec, users: candidates.map((c) => c.user) };
+}
+
+/**
+ * Capture the boot-failure evidence set for a machine that is **already
+ * running** — a request that failed after the machine was declared REST-ready.
+ *
+ * Same instruments as the BOOT_TIMEOUT path (guest snapshot, per-port slirp
+ * classification, monitor state, QEMU liveness, embedded logs), because #69's
+ * one-line `ECONNRESET` has never been enough to say whether the reset came from
+ * the client, RouterOS `www`, or slirp — and every one of those instruments
+ * answers a different part of that. What it does *not* share is the boot
+ * budget's excuse for the machine looking healthy: {@link FailureTrigger} is
+ * required here, so the report always records which request died and what
+ * changed just before it.
+ *
+ * Does not stop, remove, or otherwise touch the machine — the caller owns its
+ * lifecycle and may well want to keep testing against it. Never throws;
+ * `captureBootFailure()` swallows its own failures.
+ *
+ * One trace it does leave, and the reason that matters more here than on the
+ * boot path: the guest snapshot logs in over the serial console, and a RouterOS
+ * console login survives the host socket closing. A boot-timeout capture is
+ * followed by `stop()`/`remove()`, so nothing outlives it; here the machine
+ * keeps running. Harmless — `consoleExec()` `/quit`s a session belonging to a
+ * different user before it logs in — but a later console interaction on this
+ * machine starts from an already-logged-in prompt, not a `Login:` one.
+ */
+export async function captureRunningFailure(
+	state: MachineState,
+	phase: string,
+	trigger: FailureTrigger,
+): Promise<BootFailureReport> {
+	// Approximate, and labelled as such in the field docs: lastStartedAt is
+	// stamped at spawn and lastBootMs measured from just before it, so their sum
+	// is REST-ready to within the few ms between those two statements. Both are
+	// absent on a machine that never completed a timed boot, in which case the
+	// field is simply omitted rather than guessed at.
+	const readyAt = state.lastStartedAt !== undefined && state.lastBootMs !== undefined
+		? Date.parse(state.lastStartedAt) + state.lastBootMs
+		: undefined;
+	const guest = bootFailureGuestExec(state);
+	return await captureBootFailure({
+		name: state.name,
+		machineDir: state.machineDir,
+		arch: state.arch,
+		accel: state.lastAccel ?? "unknown",
+		pid: state.pid,
+		httpPort: state.ports.http?.host,
+		portBase: state.portBase,
+		phase,
+		trigger: {
+			...trigger,
+			sinceReadyMs: trigger.sinceReadyMs
+				?? (readyAt !== undefined && Number.isFinite(readyAt) ? Date.now() - readyAt : undefined),
+		},
+		reportDir: bootFailureReportDir(),
+		monitorQuery: (cmd) => monitorCommand(state.machineDir, cmd, 3000, state.portBase),
+		forwards: Object.values(state.ports),
+		guestExec: guest?.exec,
+		guestUser: guest?.users.join(" → "),
+	});
+}
+
+/** Tear down a machine that failed to boot, and describe what was done.
+ *
+ *  Default is full cleanup — a failed `start()` must not leave a half-dead
+ *  machine behind for the next call to trip over. QUICKCHR_PRESERVE_ON_FAILURE=1
+ *  inverts that for **local** debugging: the QEMU process is still stopped (it is
+ *  wedged, and its port block must be released), but the machine directory
+ *  survives so it can be inspected by hand.
+ *
+ *  Evidence does not depend on that flag, and CI deliberately does not set it —
+ *  `captureBootFailure()` has already written its report outside the machine dir
+ *  with qemu.log and serial.log embedded, so cleanup cannot destroy it (#79). */
+async function cleanupAfterBootFailure(
+	instance: ChrInstance,
+	name: string,
+	failure: BootFailureReport,
+): Promise<string> {
+	try { await instance.stop(); } catch { /* ignore */ }
+	if (failure.preserved) {
+		return ` Machine "${name}" was preserved for diagnosis (QUICKCHR_PRESERVE_ON_FAILURE=1) — remove it with \`quickchr remove ${name}\`.`;
+	}
+	try { await instance.remove(); } catch { /* ignore */ }
+	return ` Machine "${name}" has been cleaned up automatically.`;
+}
+
 /** Wait for CHR to boot with periodic progress status updates every 20s. */
 async function waitForBootWithProgress(
 	instance: ChrInstance,
@@ -1526,6 +1730,8 @@ export class QuickCHR {
 		// Build QEMU args and spawn
 		const platform = await detectPlatform();
 		const accel = await detectAccel(arch);
+		const note = accelNote(arch, accel);
+		if (note) logger.warn(note);
 		registerSocketMembers(state);
 		const hostfwd = buildHostfwdString(state.ports);
 		const resolvedNetworks = resolveAllNetworks(state.networks, { platform }, hostfwd);
@@ -1567,7 +1773,8 @@ export class QuickCHR {
 		const bootTimeout = defaultBootTimeout(arch, opts.installAllPackages, accel) + (opts.timeoutExtra ?? 0);
 
 		// Always wait for boot in background mode — the JSDoc promises "REST-ready".
-		let booted = await instance.waitForBoot(bootTimeout);
+		const probe = newBootProbeStats();
+		let booted = await instance.waitForBoot(bootTimeout, probe);
 
 		// Hardware-accelerated runners (nested-KVM on CI, HVF on virtualized macOS
 		// runners) occasionally produce a single QEMU process that boots but never
@@ -1584,22 +1791,35 @@ export class QuickCHR {
 			({ pid } = await spawnQemu(qemuArgs, machineDir, spawnInBackground, wrapper));
 			state.pid = pid;
 			saveMachine(state);
-			booted = await instance.waitForBoot(bootTimeout);
+			booted = await instance.waitForBoot(bootTimeout, probe);
 		}
 
 		if (!booted) {
-			let qemuLogTail = "";
-			try {
-				const logPath = join(machineDir, "qemu.log");
-				if (existsSync(logPath)) qemuLogTail = `\nqemu.log:\n${readFileSync(logPath, "utf-8").slice(-1200)}`;
-			} catch { /* ignore */ }
-			try { await instance.stop(); } catch { /* ignore */ }
-			try { await instance.remove(); } catch { /* ignore */ }
+			const guest = bootFailureGuestExec(state);
+			const failure = await captureBootFailure({
+				name,
+				machineDir,
+				arch,
+				accel,
+				bootTimeoutMs: bootTimeout,
+				pid,
+				httpPort: instance.ports.http,
+				portBase: state.portBase,
+				qemuArgs,
+				probe,
+				phase: "start",
+				reportDir: bootFailureReportDir(),
+				monitorQuery: (cmd) => monitorCommand(machineDir, cmd, 3000, state.portBase),
+				forwards: Object.values(state.ports),
+				guestExec: guest?.exec,
+				guestUser: guest?.users.join(" → "),
+			});
 			throw new QuickCHRError(
 				"BOOT_TIMEOUT",
 				`CHR did not respond within ${bootTimeout / 1000}s (accel=${accel})` +
 				(hasProvisioning ? " — provisioning could not run." : ".") +
-				` Machine "${name}" has been cleaned up automatically.${qemuLogTail}`,
+				await cleanupAfterBootFailure(instance, name, failure) +
+				`\n${failure.summary}`,
 			);
 		}
 
@@ -1838,6 +2058,8 @@ export class QuickCHR {
 
 		const platform = await detectPlatform();
 		const accel = await detectAccel(state.arch);
+		const note = accelNote(state.arch, accel);
+		if (note) (logger ?? createLogger()).warn(note);
 		registerSocketMembers(state);
 		const hostfwd = buildHostfwdString(state.ports);
 		const resolvedNetworks = resolveAllNetworks(state.networks, { platform }, hostfwd);
@@ -1878,20 +2100,34 @@ export class QuickCHR {
 
 		// Always wait for boot in background mode — start() promises "REST-ready".
 		const bootTimeout = defaultBootTimeout(state.arch, provisioningOpts?.installAllPackages, accel);
-		const booted = await instance.waitForBoot(bootTimeout);
+		const probe = newBootProbeStats();
+		const booted = await instance.waitForBoot(bootTimeout, probe);
 		if (!booted) {
-			let qemuLogTail = "";
-			try {
-				const logPath = join(state.machineDir, "qemu.log");
-				if (existsSync(logPath)) qemuLogTail = `\nqemu.log:\n${readFileSync(logPath, "utf-8").slice(-1200)}`;
-			} catch { /* ignore */ }
-			try { await instance.stop(); } catch { /* ignore */ }
-			try { await instance.remove(); } catch { /* ignore */ }
+			const guest = bootFailureGuestExec(state);
+			const failure = await captureBootFailure({
+				name: state.name,
+				machineDir: state.machineDir,
+				arch: state.arch,
+				accel,
+				bootTimeoutMs: bootTimeout,
+				pid,
+				httpPort: instance.ports.http,
+				portBase: state.portBase,
+				qemuArgs,
+				probe,
+				phase: "_launchExisting",
+				reportDir: bootFailureReportDir(),
+				monitorQuery: (cmd) => monitorCommand(state.machineDir, cmd, 3000, state.portBase),
+				forwards: Object.values(state.ports),
+				guestExec: guest?.exec,
+				guestUser: guest?.users.join(" → "),
+			});
 			throw new QuickCHRError(
 				"BOOT_TIMEOUT",
 				`CHR did not respond within ${bootTimeout / 1000}s (accel=${accel})` +
 				(hasProvisioning ? " — provisioning could not run." : ".") +
-				` Machine "${state.name}" has been cleaned up automatically.${qemuLogTail}`,
+				await cleanupAfterBootFailure(instance, state.name, failure) +
+				`\n${failure.summary}`,
 			);
 		}
 
@@ -2001,10 +2237,14 @@ export class QuickCHR {
 		try {
 			const platform = await detectPlatform();
 			if (platform.accelAvailable.length > 0) {
+				// Under an override, accelAvailable is just the forced mode for every
+				// arch — say so, or the row reads as a capability report it isn't.
+				const { mode: forced, source } = resolveAccelOverrideWithSource();
+				const suffix = forced === "auto" ? "" : ` — configured override via ${accelSourceLabel(source)}`;
 				checks.push({
 					label: "Acceleration",
 					status: "ok",
-					detail: `${platform.accelAvailable.join(", ")} (host: ${platform.hostArch})`,
+					detail: `${platform.accelAvailable.join(", ")} (host: ${platform.hostArch})${suffix}`,
 				});
 			} else {
 				checks.push({

package/src/lib/settings-file.ts

@@ -0,0 +1,52 @@
+/**
+ * The `quickchr.env` file tier of the settings system — path, raw read, and
+ * dotenv-style parse.
+ *
+ * Split out of settings.ts as a **leaf** module (node:fs + paths.ts only) so
+ * platform.ts can resolve the `accel` override's file tier without pulling in
+ * settings.ts's transitive graph (settings → cache → state → network →
+ * platform). That cycle loads eagerly at CLI startup and measurably slows every
+ * `quickchr` invocation. settings.ts re-exports everything here, so this split
+ * is invisible to callers.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { quickchrConfigDir } from "./paths.ts";
+
+export const SETTINGS_FILE_NAME = "quickchr.env";
+
+/** ~/.config/quickchr/quickchr.env */
+export function settingsFilePath(): string {
+	return join(quickchrConfigDir(), SETTINGS_FILE_NAME);
+}
+
+/** Raw non-empty lines, in file order. [] if the file doesn't exist. */
+export function readSettingsFileLines(): string[] {
+	const path = settingsFilePath();
+	if (!existsSync(path)) return [];
+	const text = readFileSync(path, "utf-8");
+	const lines = text.split("\n");
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return lines;
+}
+
+/** Parse QUICKCHR_*=value lines into a flat map. Blank/comment lines ignored; later dup wins. */
+export function parseSettingsFileLines(lines: readonly string[]): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const rawLine of lines) {
+		const line = rawLine.trim();
+		if (line.length === 0 || line.startsWith("#")) continue;
+		const eq = line.indexOf("=");
+		if (eq <= 0) continue;
+		const key = line.slice(0, eq).trim();
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+		result[key] = line.slice(eq + 1).trim();
+	}
+	return result;
+}
+
+/** The `file` tier every resolver call reads. {} when the file is absent. */
+export function loadSettingsFileDefaults(): Record<string, string> {
+	return parseSettingsFileLines(readSettingsFileLines());
+}

package/src/lib/settings.ts

@@ -13,12 +13,16 @@
  * input resolution, never per-machine config.
  */
 
-import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, fsyncSync } from "node:fs";
+import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync, fsyncSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { ARCHES, CHANNELS, QuickCHRError } from "./types.ts";
-import type { Channel } from "./types.ts";
+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 { quickchrConfigDir } from "./paths.ts";
+import { loadSettingsFileDefaults, readSettingsFileLines, settingsFilePath } from "./settings-file.ts";
+
+// The quickchr.env file tier lives in the leaf module settings-file.ts (see its
+// header for why); re-exported here so settings.ts stays the single public entry.
+export { SETTINGS_FILE_NAME, loadSettingsFileDefaults, parseSettingsFileLines, readSettingsFileLines, settingsFilePath } from "./settings-file.ts";
 
 export type SettingsValue = string | number | boolean;
 export type SettingsSource = "env" | "file" | "default";
@@ -93,6 +97,17 @@ export const SETTINGS_KEYS: readonly SettingsKeyDef[] = [
 		parse: parseArchSetting,
 		serialize: (v) => String(v),
 	},
+	{
+		// "auto" = let detectAccel() choose, including its platform fallbacks
+		// (notably arm64-on-Apple-Silicon → TCG, see DESIGN.md #10). Any other
+		// value is passed to QEMU verbatim and skips detection entirely — the
+		// escape hatch for testing HVF against a future AArch64-only arm64 image.
+		attr: "accel",
+		envKey: "QUICKCHR_ACCEL",
+		builtinDefault: "auto" satisfies AccelMode,
+		parse: (raw) => parseAccelMode(raw),
+		serialize: (v) => String(v),
+	},
 	{
 		attr: "cache-max-size",
 		envKey: "QUICKCHR_CACHE_MAX_SIZE",
@@ -108,7 +123,7 @@ export const SETTINGS_KEYS: readonly SettingsKeyDef[] = [
 		serialize: (v) => String(v),
 	},
 	{
-		// No builtinDefault: unlike the other 4 keys, the wizard needs to distinguish
+		// No builtinDefault: unlike the other 5 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
@@ -123,13 +138,6 @@ export const SETTINGS_KEYS: readonly SettingsKeyDef[] = [
 	},
 ];
 
-export const SETTINGS_FILE_NAME = "quickchr.env";
-
-/** ~/.config/quickchr/quickchr.env */
-export function settingsFilePath(): string {
-	return join(quickchrConfigDir(), SETTINGS_FILE_NAME);
-}
-
 /** Accepts "default-channel" | "QUICKCHR_DEFAULT_CHANNEL" | "DEFAULT_CHANNEL" | "default_channel". */
 export function lookupSettingsKey(input: string): SettingsKeyDef | undefined {
 	let name = input.trim();
@@ -150,36 +158,6 @@ function unknownKeyError(input: string): QuickCHRError {
 
 // --- File IO ---
 
-/** Raw non-empty lines, in file order. [] if the file doesn't exist. */
-export function readSettingsFileLines(): string[] {
-	const path = settingsFilePath();
-	if (!existsSync(path)) return [];
-	const text = readFileSync(path, "utf-8");
-	const lines = text.split("\n");
-	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
-	return lines;
-}
-
-/** Parse QUICKCHR_*=value lines into a flat map. Blank/comment lines ignored; later dup wins. */
-export function parseSettingsFileLines(lines: readonly string[]): Record<string, string> {
-	const result: Record<string, string> = {};
-	for (const rawLine of lines) {
-		const line = rawLine.trim();
-		if (line.length === 0 || line.startsWith("#")) continue;
-		const eq = line.indexOf("=");
-		if (eq <= 0) continue;
-		const key = line.slice(0, eq).trim();
-		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
-		result[key] = line.slice(eq + 1).trim();
-	}
-	return result;
-}
-
-/** The `file` tier every resolver call reads. {} when the file is absent. */
-export function loadSettingsFileDefaults(): Record<string, string> {
-	return parseSettingsFileLines(readSettingsFileLines());
-}
-
 function lineEnvKey(line: string): string | undefined {
 	const trimmed = line.trim();
 	if (trimmed.length === 0 || trimmed.startsWith("#")) return undefined;

package/src/lib/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { ProgressLogger } from "./log.ts";
+import type { BootProbeStats } from "./diagnostics.ts";
 
 // --- Version & Architecture ---
 
@@ -13,6 +14,28 @@ export const CHANNELS: readonly Channel[] = Object.freeze(["stable", "long-term"
 export type Arch = "arm64" | "x86";
 export const ARCHES: Arch[] = ["arm64", "x86"];
 
+// --- Acceleration ---
+
+/**
+ * QEMU accelerator selection. "auto" means detectAccel() picks, including its
+ * platform safety fallbacks; the other three force `-accel <mode>` verbatim and
+ * bypass detection entirely (see DESIGN.md #10).
+ */
+export type AccelMode = "auto" | "tcg" | "hvf" | "kvm";
+export const ACCEL_MODES: readonly AccelMode[] = Object.freeze(["auto", "tcg", "hvf", "kvm"] as AccelMode[]);
+
+/** Validate an accelerator name from a CLI flag, env var, or settings file. */
+export function parseAccelMode(raw: string): AccelMode {
+	const v = raw.trim().toLowerCase();
+	if (!(ACCEL_MODES as readonly string[]).includes(v)) {
+		throw new QuickCHRError(
+			"INVALID_SETTING_VALUE",
+			`Invalid value "${raw}" for accel — must be one of ${ACCEL_MODES.join(", ")}`,
+		);
+	}
+	return v as AccelMode;
+}
+
 // --- Networking ---
 
 /** @deprecated Use NetworkSpecifier instead. Kept for backward compatibility with old machine.json files. */
@@ -576,7 +599,10 @@ export interface ChrInstance {
 	 *  After `QuickCHR.start()` with provisioning options (installAllPackages, license, etc.),
 	 *  the returned instance is already REST-reachable — this returns immediately.
 	 *  Call this only when starting without provisioning, or as a safety check after a manual stop/restart. */
-	waitForBoot(timeoutMs?: number): Promise<boolean>;
+	/** @param stats Optional out-param; each REST readiness probe is classified
+	 *  into it (see diagnostics.ts BootProbeStats) so a failed wait can explain
+	 *  whether the forwarded port ever answered. */
+	waitForBoot(timeoutMs?: number, stats?: BootProbeStats): Promise<boolean>;
 	/** Poll a condition until it returns true or the timeout elapses.
 	 *  Retries every 2 s, swallowing errors from the condition function.
 	 *  Returns `true` when the condition passes, `false` on timeout.
@@ -762,6 +788,16 @@ export type ErrorCode =
 	| "QGA_UNSUPPORTED"
 	| "QGA_TIMEOUT"
 	| "DOWNLOAD_FAILED"
+	// A transfer that received nothing for DOWNLOAD_STALL_MS. Retriable, and
+	// retried before this surfaces — a wedged socket usually moves on the next
+	// attempt (#116).
+	| "DOWNLOAD_STALLED"
+	// A transfer that kept moving but could not finish inside a budget derived
+	// from its content-length and COLD_DOWNLOAD_FLOOR_BYTES_PER_S. Terminal on
+	// purpose: retrying re-downloads from zero on a link already measured slower
+	// than the floor, which is the "one slow transfer becomes three" behavior
+	// #116 exists to remove.
+	| "DOWNLOAD_TOO_SLOW"
 	| "MACHINE_EXISTS"
 	| "MACHINE_NOT_FOUND"
 	| "MACHINE_RUNNING"