@tikoci/quickchr 0.4.2 → 0.4.3

package/src/lib/channels.ts

@@ -54,7 +54,22 @@ export function channelFileExists(path: string): boolean {
 	return existsSync(path);
 }
 
-/** Send a command to the QEMU monitor and return the response. */
+/** Strip ANSI escapes and the monitor's per-character command echo, leaving
+ *  just the response body. The echo hid real errors from callers: QEMU renders
+ *  the typed command as incremental `cmd\x1b[K\x1b[D…` fragments before the
+ *  first newline, so an `Error: …` response never appeared at string start and
+ *  `savevm`/`loadvm` failures were silently swallowed (#31). */
+export function cleanMonitorResponse(raw: string): string {
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escapes are the point
+	const noAnsi = raw.replace(/\u001b\[[0-9;]*[A-Za-z]/g, "");
+	const lines = noAnsi.split(/\r?\n/);
+	// Everything before the first newline is the echoed command; the response
+	// (possibly multi-line, possibly empty) follows.
+	return lines.slice(1).join("\n").trim();
+}
+
+/** Send a command to the QEMU monitor and return the cleaned response
+ *  (command echo and ANSI control sequences stripped — see cleanMonitorResponse). */
 export async function monitorCommand(
 	machineDir: string,
 	command: string,
@@ -92,9 +107,9 @@ export async function monitorCommand(
 				buffer = "";
 				socket.write(command + "\n");
 			} else if (sentCommand && buffer.includes("(qemu)")) {
-				// Got response — strip the prompt
+				// Got response — strip the prompt, the command echo, and ANSI noise
 				clearTimeout(timeout);
-				const response = buffer.replace(/\(qemu\)\s*/g, "").trim();
+				const response = cleanMonitorResponse(buffer.replace(/\(qemu\)\s*/g, ""));
 				socket.destroy();
 				resolve(response);
 			}
@@ -105,7 +120,7 @@ export async function monitorCommand(
 		socket.on("close", () => {
 			clearTimeout(timeout);
 			if (sentCommand) {
-				resolve(buffer.replace(/\(qemu\)\s*/g, "").trim());
+				resolve(cleanMonitorResponse(buffer.replace(/\(qemu\)\s*/g, "")));
 			} else {
 				reject(new QuickCHRError("MACHINE_STOPPED", "Monitor socket closed before command could be sent"));
 			}

package/src/lib/completions.ts

@@ -328,7 +328,7 @@ _quickchr() {
         cword=${D}COMP_CWORD
     }
 
-    local commands="add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor setup completions version help"
+    local commands="add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor settings setup completions version help"
 
     if [[ ${D}cword -eq 1 ]]; then
         COMPREPLY=( $(compgen -W "${D}commands" -- "${D}cur") )
@@ -402,6 +402,7 @@ _quickchr() {
                 'networks:Network discovery and socket management'
                 'net:Network discovery (alias)'
                 'doctor:Check prerequisites'
+                'settings:Manage global quickchr settings'
                 'setup:Interactive setup wizard'
                 'completions:Manage shell completions'
                 'version:Show version info'
@@ -434,7 +435,7 @@ _quickchr() {
                     _describe 'option' opts
                     ;;
                 help)
-                    local commands=(add start stop list status inspect env remove clean console exec qga license disk snapshot networks doctor setup completions version)
+                    local commands=(add start stop list status inspect env remove clean console exec qga license disk snapshot networks doctor settings setup completions version)
                     _describe 'command' commands
                     ;;
             esac
@@ -450,7 +451,7 @@ function generateFishCompletion(): string {
 	return `# quickchr fish completion
 # Generated by quickchr. Fish auto-loads files from ~/.config/fish/completions/.
 
-set -l quickchr_commands add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor setup completions version help
+set -l quickchr_commands add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor settings setup completions version help
 
 # Disable file completions globally for quickchr
 complete -c quickchr -f
@@ -490,6 +491,8 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "networks net" -d "Network discovery and socket management"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "doctor"      -d "Check prerequisites"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "settings"    -d "Manage global quickchr settings"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "setup"       -d "Interactive setup wizard"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\

package/src/lib/disk.ts

@@ -260,8 +260,11 @@ export function parseSnapshotList(monitorOutput: string): SnapshotInfo[] {
 		// Match snapshot data lines: ID, TAG, VM SIZE, DATE (YYYY-MM-DD HH:MM:SS), VM CLOCK, ICOUNT
 		// Example: "--      test              113 MiB 2026-04-14 00:47:19  0000:01:17.163         --"
 		// Example: "1       snap1             113 MiB 2026-04-14 00:47:19  0000:01:17.163         --"
+		// VM CLOCK hour width varies by QEMU version (2-digit on 8.x runners,
+		// 4-digit on 11.x brew builds) and the ICOUNT column may be absent —
+		// accept both so list() doesn't silently return [] on older QEMU.
 		const match = line.match(
-			/^\s*(\S+)\s+(\S+)\s+(\d+(?:\.\d+)?\s*(?:[KMGT]i?B|bytes?))\s+(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2})\s+(\d{4}:\d{2}:\d{2}\.\d+)\s+(\S+)/i,
+			/^\s*(\S+)\s+(\S+)\s+(\d+(?:\.\d+)?\s*(?:[KMGT]i?B|bytes?))\s+(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2})\s+(\d{2,4}:\d{2}:\d{2}\.\d+)(?:\s+(\S+))?/i,
 		);
 		if (!match) continue;
 
@@ -274,7 +277,7 @@ export function parseSnapshotList(monitorOutput: string): SnapshotInfo[] {
 			vmStateSize: parseVmSize(vmSizeStr),
 			date: dateStr.replace(" ", "T") + "Z",
 			vmClock: vmClock,
-			icount: icountStr === "--" ? undefined : Number(icountStr),
+			icount: icountStr && icountStr !== "--" ? Number(icountStr) : undefined,
 		});
 	}
 

package/src/lib/forward-spec.ts

@@ -1,7 +1,9 @@
 /**
- * Parse a CLI `--forward` spec into a `PortMapping`.
+ * Parse a CLI `--forward` spec into one or more `PortMapping`s.
  *
- * Grammar: `name[:host[:guest]][/proto]`
+ * Two grammars share this file:
+ *
+ * **Single port** — `parseForwardSpec`, grammar `name[:host[:guest]][/proto]`:
  *
  * - `name` — required. If it matches a key/alias in `WELL_KNOWN_GUEST_PORTS`,
  *   missing `guest` and `proto` are filled from the registry. The original
@@ -14,7 +16,16 @@
  * - `proto` — optional. Defaults from registry, else `tcp`. Must be `tcp` or
  *   `udp`.
  *
- * Throws `QuickCHRError("INVALID_FORWARD_SPEC", ...)` with the original spec
+ * **Port range** — `expandForwardSpec`, grammar
+ * `name:hostStart-hostEnd[:guestStart-guestEnd][/proto]`. Expands to one
+ * `PortMapping` per port (QEMU `hostfwd` has no native range — each port needs
+ * its own directive). Useful for L3 peer protocols with dynamic data ports
+ * (e.g. RouterOS bandwidth-test allocates UDP ports at runtime). See the rules
+ * on `expandForwardSpec` below. `expandForwardSpec` is the range-aware entry
+ * point and delegates to `parseForwardSpec` for non-range specs, so callers can
+ * always use `expandForwardSpec` (the CLI does).
+ *
+ * Both throw `QuickCHRError("INVALID_FORWARD_SPEC", ...)` with the original spec
  * embedded in the message on any parse error.
  */
 
@@ -90,3 +101,129 @@ export function parseForwardSpec(spec: string): PortMapping {
 
 	return { name, host, guest, proto };
 }
+
+/** Max ports a single range `--forward` may span, bounding the generated
+ *  `hostfwd` string (one directive per port). */
+export const FORWARD_RANGE_MAX = 64;
+
+function parseRange(
+	spec: string,
+	raw: string,
+	label: string,
+): { start: number; end: number } {
+	const dash = raw.indexOf("-");
+	const startRaw = raw.slice(0, dash);
+	const endRaw = raw.slice(dash + 1);
+	const start = parsePort(spec, startRaw, `${label} range start`, false);
+	const end = parsePort(spec, endRaw, `${label} range end`, false);
+	if (end < start) {
+		fail(spec, `${label} range end ${end} is below start ${start}`);
+	}
+	return { start, end };
+}
+
+/**
+ * Range-aware front door for `--forward` specs. Returns a `PortMapping[]`.
+ *
+ * For a single-port spec (no `-` in the host/guest segment) this returns
+ * `[parseForwardSpec(spec)]` unchanged. For a range spec
+ * `name:hostStart-hostEnd[:guestStart-guestEnd][/proto]` it expands to one
+ * `PortMapping` per port, named `\`${name}-${hostPort}\`` so each is a distinct
+ * key in the machine's port map.
+ *
+ * Range rules:
+ * - **Host range is required** — ranges are not auto-allocated. The per-instance
+ *   port block (10 ports) can't guarantee a contiguous run, so range host ports
+ *   must be explicit. They are then collision-checked like any explicit
+ *   `extraPorts` host (`validateExplicitExtraPorts`).
+ * - **Guest range is optional** — defaults to the same numbers as the host
+ *   range. When given it must be the **same length** as the host range.
+ * - **`proto`** defaults from the `WELL_KNOWN_GUEST_PORTS` registry (by `name`),
+ *   else `tcp`; an explicit `/proto` suffix wins.
+ * - Reversed ranges (end < start) and spans over {@link FORWARD_RANGE_MAX} ports
+ *   throw `INVALID_FORWARD_SPEC`.
+ *
+ * @example
+ * expandForwardSpec("btest:9200-9202:2000-2002/udp");
+ * // → [{name:"btest-9200",host:9200,guest:2000,proto:"udp"}, … 9201/2001, 9202/2002]
+ * @example
+ * expandForwardSpec("smb"); // single port → [{name:"smb",host:0,guest:445,proto:"tcp"}]
+ */
+export function expandForwardSpec(spec: string): PortMapping[] {
+	if (!spec?.trim()) {
+		throw new QuickCHRError("INVALID_FORWARD_SPEC", "Empty --forward spec");
+	}
+	const trimmed = spec.trim();
+
+	// Split off /proto suffix (so a range's "-" can't be confused with anything).
+	let body = trimmed;
+	let protoStr: string | undefined;
+	const slash = trimmed.lastIndexOf("/");
+	if (slash !== -1) {
+		body = trimmed.slice(0, slash);
+		protoStr = trimmed.slice(slash + 1).toLowerCase();
+		if (protoStr !== "tcp" && protoStr !== "udp") {
+			fail(spec, `protocol must be "tcp" or "udp", got "${protoStr}"`);
+		}
+	}
+
+	const parts = body.split(":");
+	const hasRange = Boolean(parts[1]?.includes("-") || parts[2]?.includes("-"));
+	if (!hasRange) {
+		return [parseForwardSpec(spec)];
+	}
+
+	if (parts.length > 3) {
+		fail(spec, `too many ":" segments (expected name:hostStart-hostEnd[:guestStart-guestEnd])`);
+	}
+	const name = parts[0]?.trim() ?? "";
+	if (!name) {
+		fail(spec, "name is required");
+	}
+
+	const hostSegment = parts[1];
+	if (!hostSegment?.includes("-")) {
+		fail(
+			spec,
+			"a range --forward requires an explicit host range (e.g. 9200-9210); ranges are not auto-allocated",
+		);
+	}
+	const hostRange = parseRange(spec, hostSegment, "host");
+
+	const guestSegment = parts[2];
+	let guestRange: { start: number; end: number };
+	if (guestSegment !== undefined && guestSegment !== "") {
+		if (!guestSegment.includes("-")) {
+			fail(
+				spec,
+				`guest segment "${guestSegment}" must be a range matching the host range (e.g. 2000-2010), not a single port`,
+			);
+		}
+		guestRange = parseRange(spec, guestSegment, "guest");
+	} else {
+		// guest range omitted → default to the host range's port numbers
+		guestRange = { start: hostRange.start, end: hostRange.end };
+	}
+
+	const hostCount = hostRange.end - hostRange.start + 1;
+	const guestCount = guestRange.end - guestRange.start + 1;
+	if (hostCount !== guestCount) {
+		fail(
+			spec,
+			`host range (${hostCount} ports) and guest range (${guestCount} ports) must be the same length`,
+		);
+	}
+	if (hostCount > FORWARD_RANGE_MAX) {
+		fail(spec, `range spans ${hostCount} ports, exceeding the ${FORWARD_RANGE_MAX}-port cap`);
+	}
+
+	const known = lookupGuestPort(name);
+	const proto: "tcp" | "udp" = (protoStr as "tcp" | "udp" | undefined) ?? known?.proto ?? "tcp";
+
+	const mappings: PortMapping[] = [];
+	for (let i = 0; i < hostCount; i++) {
+		const host = hostRange.start + i;
+		mappings.push({ name: `${name}-${host}`, host, guest: guestRange.start + i, proto });
+	}
+	return mappings;
+}

package/src/lib/paths.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared filesystem paths for quickchr's config-tier (XDG_CONFIG-like) files.
+ */
+
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/** ~/.config/quickchr — used by secrets.ts (credential fallback files) and
+ *  settings.ts (quickchr.env). Single source of truth so those modules never
+ *  drift on the HOME/USERPROFILE fallback chain. */
+export function quickchrConfigDir(): string {
+	return join(process.env.HOME ?? process.env.USERPROFILE ?? homedir(), ".config", "quickchr");
+}

package/src/lib/provision.ts

@@ -364,14 +364,12 @@ export async function provision(
 	// Try REST provisioning. When machineDir is provided, use a shorter timeout
 	// so the console fallback can engage sooner if REST isn't available.
 	const restTimeout = machineDir ? 30_000 : 60_000;
-	let usedConsolePath = false;
 	try {
 		await waitForRest(httpPort, restTimeout);
 	} catch (e) {
 		if (machineDir) {
 			log.warn("REST API unavailable — falling back to serial console provisioning");
 			const result = await consoleProvision(machineDir, machineName, effectiveUser, !!shouldDisableAdmin, logger, portBase);
-			usedConsolePath = true;
 			// After console provisioning the machine is booted; REST comes up shortly.
 			// Attempt SSH key install for the managed quickchr user — non-fatal if REST is still unavailable.
 			if (secureLogin && !user && effectiveUser) {
@@ -387,35 +385,35 @@ export async function provision(
 		throw e;
 	}
 
-	if (!usedConsolePath) {
-		if (effectiveUser) {
-			await createUser(httpPort, effectiveUser.name, effectiveUser.password);
-			// Persist to secret store so resolveAuth() picks it up
-			saveInstanceCredentials(machineName, effectiveUser.name, effectiveUser.password);
-		}
+	// REST provisioning path. The console fallback above always returns early,
+	// so reaching here means REST came up and we provision over it.
+	if (effectiveUser) {
+		await createUser(httpPort, effectiveUser.name, effectiveUser.password);
+		// Persist to secret store so resolveAuth() picks it up
+		saveInstanceCredentials(machineName, effectiveUser.name, effectiveUser.password);
+	}
 
-		if (secureLogin && !user && effectiveUser && machineDir) {
-			// Brief pause so RouterOS propagates the new user to all subsystems
-			// (including the SSH key store) before we attempt key installation.
-			await Bun.sleep(1000);
-			try {
-				await installSshKey(httpPort, effectiveUser.name, machineName, machineDir, portBase);
-			} catch (e) {
-				log.warn(`SSH key install failed (SSH transport will fall back to password): ${e}`);
-			}
+	if (secureLogin && !user && effectiveUser && machineDir) {
+		// Brief pause so RouterOS propagates the new user to all subsystems
+		// (including the SSH key store) before we attempt key installation.
+		await Bun.sleep(1000);
+		try {
+			await installSshKey(httpPort, effectiveUser.name, machineName, machineDir, portBase);
+		} catch (e) {
+			log.warn(`SSH key install failed (SSH transport will fall back to password): ${e}`);
 		}
+	}
 
-		if (shouldDisableAdmin) {
-			if (!effectiveUser) {
-				log.warn("Warning: disabling admin without creating another user — you may lose access");
-			}
-			// Pass the new user's auth for verification — after disabling admin,
-			// admin creds may stop working for REST queries.
-			const verifyAuth = effectiveUser
-				? `Basic ${btoa(`${effectiveUser.name}:${effectiveUser.password}`)}`
-				: undefined;
-			await disableAdmin(httpPort, verifyAuth);
+	if (shouldDisableAdmin) {
+		if (!effectiveUser) {
+			log.warn("Warning: disabling admin without creating another user — you may lose access");
 		}
+		// Pass the new user's auth for verification — after disabling admin,
+		// admin creds may stop working for REST queries.
+		const verifyAuth = effectiveUser
+			? `Basic ${btoa(`${effectiveUser.name}:${effectiveUser.password}`)}`
+			: undefined;
+		await disableAdmin(httpPort, verifyAuth);
 	}
 
 	return { user: effectiveUser };

package/src/lib/qemu.ts

@@ -9,7 +9,7 @@ import { existsSync, writeFileSync, readFileSync, copyFileSync, statSync, openSy
 import { join } from "node:path";
 import type { Arch, BootDiskFormat, MachineState, NetworkMode, NetworkConfig, PortMapping } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
-import { detectAccel, requireQemu, requireFirmware } from "./platform.ts";
+import { detectAccel, requireQemu, requireFirmware, requireQemuImg } from "./platform.ts";
 import { buildHostfwdString } from "./network.ts";
 import { ensureDir } from "./state.ts";
 import { restGet } from "./rest.ts";
@@ -80,16 +80,19 @@ export async function buildQemuArgs(config: QemuLaunchConfig): Promise<string[]>
 	// UEFI firmware (arm64 only)
 	if (arch === "arm64") {
 		const fw = requireFirmware();
-		const varsPath = join(machineDir, "efi-vars.fd");
-
-		// Copy and size-match the vars file if not already done
+		// The per-machine EFI vars pflash is qcow2, NOT raw: QEMU refuses
+		// savevm/loadvm while any writable block device is non-qcow2 ("Device
+		// 'pflash1' is writable but does not support snapshots"), which made
+		// snapshots impossible on arm64 (#31). Legacy raw efi-vars.fd machines
+		// are converted in place, preserving their NVRAM state.
+		const varsPath = join(machineDir, "efi-vars.qcow2");
 		if (!existsSync(varsPath)) {
-			prepareEfiVars(fw.code, fw.vars, varsPath);
+			await prepareEfiVars(fw.code, fw.vars, varsPath, join(machineDir, "efi-vars.fd"));
 		}
 
 		args.push(
 			"-drive", `if=pflash,format=raw,readonly=on,unit=0,file=${fw.code}`,
-			"-drive", `if=pflash,format=raw,unit=1,file=${varsPath}`,
+			"-drive", `if=pflash,format=qcow2,unit=1,file=${varsPath}`,
 		);
 	}
 
@@ -248,26 +251,53 @@ function buildChannelArgs(
 	}
 }
 
-/** Copy and size-match EFI vars file to match code ROM size. */
-function prepareEfiVars(codePath: string, varsTemplatePath: string, destPath: string): void {
+/** Build the per-machine qcow2 EFI vars pflash: start from the legacy raw
+ *  vars file if the machine has one (preserves NVRAM state), else from the
+ *  firmware template; size-match to the code ROM; convert raw → qcow2 so
+ *  savevm/loadvm work (see the pflash comment at the call site / #31). */
+async function prepareEfiVars(codePath: string, varsTemplatePath: string, destPath: string, legacyRawPath: string): Promise<void> {
 	ensureDir(join(destPath, ".."));
-	copyFileSync(varsTemplatePath, destPath);
 
-	// pflash units must be identical size — pad/truncate vars to match code
+	// Stage the raw image (legacy per-machine file wins over the template).
+	const rawStage = `${destPath}.raw-stage`;
+	copyFileSync(existsSync(legacyRawPath) ? legacyRawPath : varsTemplatePath, rawStage);
+
+	// pflash units must be identical size — pad/truncate vars to match code.
+	// truncateSync extends with zero bytes when target is larger.
 	const codeSize = statSync(codePath).size;
-	const varsSize = statSync(destPath).size;
+	try {
+		if (statSync(rawStage).size !== codeSize) truncateSync(rawStage, codeSize);
+	} catch (e) {
+		try { unlinkSync(rawStage); } catch { /* best effort */ }
+		throw new QuickCHRError(
+			"PROCESS_FAILED",
+			`Failed to size-match EFI vars: ${e instanceof Error ? e.message : String(e)}`,
+		);
+	}
 
-	if (varsSize !== codeSize) {
-		// Pad or truncate vars to match code ROM size — truncateSync extends with
-		// zero bytes when target is larger, and truncates when smaller.
-		try {
-			truncateSync(destPath, codeSize);
-		} catch (e) {
-			throw new QuickCHRError(
-				"PROCESS_FAILED",
-				`Failed to size-match EFI vars: ${e instanceof Error ? e.message : String(e)}`,
-			);
-		}
+	const qemuImg = requireQemuImg();
+	const conversion = Bun.spawn([qemuImg, "convert", "-f", "raw", "-O", "qcow2", rawStage, destPath], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const exitCode = await conversion.exited;
+	const [stderr, stdout] = await Promise.all([
+		new Response(conversion.stderr).text(),
+		new Response(conversion.stdout).text(),
+	]);
+	try { unlinkSync(rawStage); } catch { /* best effort */ }
+	if (exitCode !== 0) {
+		// A failed convert can leave a partial destPath behind — remove it so the
+		// next launch regenerates instead of booting (and re-failing on) the stub.
+		try { unlinkSync(destPath); } catch { /* best effort */ }
+		throw new QuickCHRError(
+			"PROCESS_FAILED",
+			`qemu-img convert of EFI vars failed: ${stderr.trim() || stdout.trim() || `exit ${exitCode}`}`,
+		);
+	}
+	// Legacy raw file is superseded — remove so nothing boots the stale copy.
+	if (existsSync(legacyRawPath)) {
+		try { unlinkSync(legacyRawPath); } catch { /* best effort */ }
 	}
 }
 

package/src/lib/quickchr.ts

@@ -43,9 +43,11 @@ import {
 	ensureDir,
 	getCacheDir,
 	getDataDir,
+	appendBootLog,
 } from "./state.ts";
 import { ensureCachedImage, copyImageToMachine, listCachedImages } from "./images.ts";
 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";
@@ -343,6 +345,12 @@ function createInstance(state: MachineState): ChrInstance {
 			if (state.pid && isMachineRunning(state)) {
 				await stopQemu(state.pid);
 			}
+			// NOTE: clean() deliberately does NOT delete efi-vars.fd. On the arm64 `virt`
+			// machine that file stores UEFI boot order (Boot0000 -> first virtio-blk-pci
+			// disk), not OS state; wiping it forces a full device scan (~480s) on the next
+			// boot. The fresh disk re-copy below is a sufficient factory reset. Regression
+			// anchor: the "clean() resets disk to factory defaults" arm64 integration test
+			// (120s reboot wait would blow past 480s if the wipe were reintroduced).
 			// Re-copy fresh image from cache
 			const imgPath = join(getCacheDir(), `chr-${state.version}${state.arch === "arm64" ? "-arm64" : ""}.img`);
 			if (!existsSync(imgPath)) {
@@ -362,10 +370,6 @@ function createInstance(state: MachineState): ChrInstance {
 				state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw"),
 			);
 
-			// Remove EFI vars to force re-creation
-			const efiVars = join(state.machineDir, "efi-vars.fd");
-			if (existsSync(efiVars)) rmSync(efiVars);
-
 			// Clean up stored instance credentials (re-provisioned on next start)
 			deleteInstanceCredentials(state.name);
 
@@ -699,15 +703,26 @@ function createInstance(state: MachineState): ChrInstance {
 					throw new QuickCHRError("PROCESS_FAILED", `savevm failed: ${out.trim()}`);
 				}
 
-				// Read back the snapshot list to return the new entry
+				// Read back the snapshot list — the new entry MUST be there. A
+				// fabricated fallback here once masked savevm failing outright on
+				// arm64 (#31): the example printed a snapshot that never existed.
 				const snaps = await this.list();
-				return snaps.find((s) => s.name === snapName) ?? {
-					id: "0",
-					name: snapName,
-					vmStateSize: 0,
-					date: new Date().toISOString(),
-					vmClock: "0000:00:00.000",
-				};
+				const created = snaps.find((s) => s.name === snapName);
+				if (!created) {
+					// Self-grounding error: include the raw monitor listing so a CI
+					// failure carries the evidence (QEMU output formats vary by version
+					// and a parse gap here looks identical to a real savevm failure).
+					let rawList = "(unavailable)";
+					try {
+						rawList = await monitorCommand(state.machineDir, "info snapshots", undefined, state.portBase);
+					} catch { /* keep placeholder */ }
+					throw new QuickCHRError(
+						"PROCESS_FAILED",
+						`savevm reported no error but snapshot "${snapName}" is absent from the parsed list — ` +
+							`treat as failed. savevm said: "${out.trim() || "(empty)"}"; raw 'info snapshots': "${rawList}"`,
+					);
+				}
+				return created;
 			},
 
 			async load(name: string): Promise<void> {
@@ -721,6 +736,17 @@ function createInstance(state: MachineState): ChrInstance {
 
 				const out = await monitorCommand(state.machineDir, `loadvm ${name}`, undefined, state.portBase);
 				if (/^error[:\s]/i.test(out)) {
+					// A failed loadvm leaves the VM in "paused (restore-vm)" — resume
+					// it so the guest isn't wedged (REST dead) on top of the error.
+					try {
+						await monitorCommand(state.machineDir, "cont", undefined, state.portBase);
+					} catch (contErr) {
+						// Best effort — the throw below is the real signal, but a failed
+						// resume means the VM may still be paused; say so.
+						console.warn(
+							`quickchr: 'cont' after failed loadvm also failed (${contErr instanceof Error ? contErr.message : String(contErr)}) — machine "${state.name}" may be paused`,
+						);
+					}
 					throw new QuickCHRError("PROCESS_FAILED", `loadvm failed: ${out.trim()}`);
 				}
 			},
@@ -1235,7 +1261,7 @@ export class QuickCHR {
 					user: opts.user ?? existing.user,
 					disableAdmin: opts.disableAdmin ?? existing.disableAdmin,
 					license: opts.license,
-					secureLogin: opts.secureLogin,
+					secureLogin: opts.secureLogin ?? existing.secureLogin,
 				};
 				const hasPending = !!(
 					pendingOpts.installAllPackages ||
@@ -1243,7 +1269,8 @@ export class QuickCHR {
 					pendingOpts.deviceMode ||
 					pendingOpts.user ||
 					pendingOpts.disableAdmin ||
-					pendingOpts.license
+					pendingOpts.license ||
+					pendingOpts.secureLogin === true
 				);
 				if (hasPending) {
 					return QuickCHR._launchExisting(existing, opts.background ?? true, pendingOpts, logger);
@@ -1402,6 +1429,7 @@ export class QuickCHR {
 
 		const qemuArgs = await buildQemuArgs(launchConfig);
 		const wrapper = extractWrapper(resolvedNetworks);
+		const bootStart = Date.now();
 		let { pid } = await spawnQemu(qemuArgs, machineDir, spawnInBackground, wrapper);
 
 		// Foreground (no provisioning): spawnQemu blocks until QEMU exits
@@ -1458,6 +1486,24 @@ export class QuickCHR {
 			);
 		}
 
+		// Record boot timing (cumulative from first spawn, incl. the respawn-once
+		// path) — in machine.json for `list`/`get` and in the boot-history log.
+		// Side-band metrics must never fail a boot that succeeded.
+		state.lastAccel = accel;
+		state.lastBootMs = Date.now() - bootStart;
+		saveMachine(state);
+		try {
+			appendBootLog({
+				ts: new Date().toISOString(),
+				name,
+				version,
+				arch,
+				accel,
+				bootMs: state.lastBootMs,
+				host: process.platform,
+			});
+		} catch { /* never propagate */ }
+
 		if (hasProvisioning) {
 			await QuickCHR._provisionInstance(instance, state, {
 				installAllPackages: opts.installAllPackages,
@@ -1684,6 +1730,7 @@ export class QuickCHR {
 
 		const qemuArgs = await buildQemuArgs(launchConfig);
 		const wrapper = extractWrapper(resolvedNetworks);
+		const bootStart = Date.now();
 		const { pid } = await spawnQemu(qemuArgs, state.machineDir, spawnBackground, wrapper);
 
 		// Foreground without provisioning: spawnQemu blocks until QEMU exits
@@ -1720,12 +1767,32 @@ export class QuickCHR {
 			);
 		}
 
+		// Record boot timing — mirrors start(); side-band, never fails the boot.
+		state.lastAccel = accel;
+		state.lastBootMs = Date.now() - bootStart;
+		saveMachine(state);
+		try {
+			appendBootLog({
+				ts: new Date().toISOString(),
+				name: state.name,
+				version: state.version,
+				arch: state.arch,
+				accel,
+				bootMs: state.lastBootMs,
+				host: process.platform,
+			});
+		} catch { /* never propagate */ }
+
 		if (hasProvisioning && provisioningOpts) {
 			await QuickCHR._provisionInstance(instance, state, provisioningOpts, launchConfig, logger);
 		}
 
 		try {
-			autoPruneIfOverCap({ logger: logger ? (msg) => logger.status(msg) : undefined, protectVersions: [state.version] });
+			autoPruneIfOverCap({
+				logger: logger ? (msg) => logger.status(msg) : undefined,
+				protectVersions: [state.version],
+				maxSizeBytes: resolveSetting("cache-max-size").value as number | undefined,
+			});
 		} catch { /* never propagate */ }
 
 		return instance;
@@ -1777,7 +1844,7 @@ export class QuickCHR {
 					detail: ver ?? "found (version unknown)",
 				});
 			} catch (_e) {
-				const hint = getQemuInstallHint() ?? "Install QEMU";
+				const hint = getQemuInstallHint();
 				checks.push({
 					label: qemuName,
 					status: arch === hostArchToChr() ? "error" : "warn",