@tikoci/quickchr 0.5.1 → 0.5.3

package/src/lib/qemu.ts

@@ -38,6 +38,13 @@ export interface QemuLaunchConfig {
 	 * can be used for both QEMU args and boot timeout calculation.
 	 */
 	accel?: string;
+	/** Extra argv elements (`StartOptions.qemuArgs`), appended verbatim after
+	 *  quickchr's own args. Ordering is load-bearing: last-wins on conflicts. */
+	qemuArgs?: string[];
+	/** Hold the guest at reset (`-S`) with a gdbstub on `<machineDir>/gdb.sock`
+	 *  (`start --frozen`). Unix socket, `server=on,wait=off` so the spawn never
+	 *  blocks waiting for a client. */
+	frozen?: boolean;
 }
 
 /** Build the full QEMU command-line arguments array. */
@@ -136,6 +143,15 @@ export async function buildQemuArgs(config: QemuLaunchConfig): Promise<string[]>
 	// Serial, monitor, QGA channels
 	buildChannelArgs(args, arch, machineDir, background, portBase);
 
+	// Frozen boot (#214): hold at reset with a gdbstub. Before the passthrough
+	// below, which is always last.
+	if (config.frozen) {
+		args.push("-S", "-gdb", `unix:${join(machineDir, "gdb.sock")},server=on,wait=off`);
+	}
+
+	// Lab escape hatch (#213): verbatim passthrough, always last so it wins conflicts.
+	if (config.qemuArgs) args.push(...config.qemuArgs);
+
 	return args;
 }
 
@@ -471,8 +487,17 @@ export async function spawnQemu(
 
 	const pid = proc.pid;
 	writeFileSync(pidPath, String(pid));
-	await proc.exited;
+	const exitCode = await proc.exited;
 	try { unlinkSync(pidPath); } catch { /* ignore */ }
+	// A bad argv element (e.g. --qemu-arg) fails fast here with a QEMU error on
+	// the terminal — but without this check the caller reports a clean stop.
+	// Only a numeric non-zero code throws: a signal kill (null) is a user quit.
+	if (typeof exitCode === "number" && exitCode !== 0) {
+		throw new QuickCHRError(
+			"SPAWN_FAILED",
+			`QEMU exited with status ${exitCode} — see the QEMU error output above (often a bad --qemu-arg value).`,
+		);
+	}
 	return { pid };
 }
 
@@ -505,11 +530,13 @@ export async function stopQemu(pid: number): Promise<boolean> {
 	return true;
 }
 
-/** Remove the listening unix-socket files QEMU binds (monitor/serial/qga).
+/** Remove the listening unix-socket files QEMU binds (monitor/serial/qga/gdb).
  *  A SIGKILLed QEMU leaves these behind; a respawn with `server=on` then fails
- *  to bind ("Address already in use"). Call before re-spawning into the same dir. */
+ *  to bind ("Address already in use"). Call before re-spawning into the same dir.
+ *  `gdb.sock` is included: a stale one from a frozen boot would otherwise linger
+ *  after stop and refuse a harness attach on a later non-frozen boot. */
 export function cleanupQemuSockets(machineDir: string): void {
-	for (const sock of ["monitor.sock", "serial.sock", "qga.sock"]) {
+	for (const sock of ["monitor.sock", "serial.sock", "qga.sock", "gdb.sock"]) {
 		const path = join(machineDir, sock);
 		try {
 			if (existsSync(path)) unlinkSync(path);

package/src/lib/quickchr.ts

@@ -7,6 +7,7 @@ import type {
 	Channel,
 	ChrInstance,
 	ChrLoadSample,
+	ContinueOptions,
 	CustomForward,
 	Descriptor,
 	DeviceModeOptions,
@@ -30,7 +31,7 @@ import type {
 import { QuickCHRError, ARCHES, CHANNELS, SERVICE_IDS, QUICKCHR_DESCRIPTOR_VERSION, HOST_GATEWAY_IP, PORTS_PER_BLOCK } from "./types.ts";
 import { assertValidResourceName, assertPathSafeName, shellQuote } from "./names.ts";
 import packageJson from "../../package.json";
-import { detectPlatform, requireQemu, requireFirmware, getQemuVersion, getQemuInstallHint, isCrossArchEmulation, accelTimeoutFactor, detectAccel, accelNote, resolveAccelOverrideWithSource, accelSourceLabel, findQemuImg, qgaKvmWarning, detectSocketVmnet, isSocketVmnetDaemonRunning, findCommandOnPath } from "./platform.ts";
+import { bunRuntimeCheck, detectPlatform, requireQemu, requireFirmware, getQemuVersion, getQemuInstallHint, isCrossArchEmulation, accelTimeoutFactor, detectAccel, accelNote, resolveAccelOverrideWithSource, accelSourceLabel, findQemuImg, qgaKvmWarning, detectSocketVmnet, isSocketVmnetDaemonRunning, findCommandOnPath } from "./platform.ts";
 import {
 	resolveVersion,
 	isValidVersion,
@@ -211,6 +212,18 @@ function describeProvisioningOperation(opts: Parameters<typeof listProvisioningM
 	return `use ${PROVISIONING_FEATURE_LABEL} (${joinHumanList(operations)})`;
 }
 
+/** Per-boot launch intent for `_launchExisting`: session `qemuArgs` and `frozen`
+ *  when given, used for the spawn but never persisted.
+ *  Absent (`undefined`) means "not given", and only absent falls through to what
+ *  `add` recorded — the same rule as `pendingProvisioningFor` (#185): an empty
+ *  array is not an instruction to drop the stored args. */
+function sessionLaunch(opts: StartOptions): { qemuArgs?: string[]; frozen?: boolean } | undefined {
+	const launch: { qemuArgs?: string[]; frozen?: boolean } = {};
+	if (opts.qemuArgs?.length) launch.qemuArgs = [...opts.qemuArgs];
+	if (opts.frozen) launch.frozen = true;
+	return launch.qemuArgs || launch.frozen ? launch : undefined;
+}
+
 /** `wait: false` returns before the guest has booted, and provisioning needs a booted
  *  guest — so the pair is refused by name rather than the provisioning silently
  *  skipped (#159). `machine` is set when the provisioning is first-boot intent that
@@ -227,6 +240,20 @@ function assertWaitAllowsProvisioning(opts: StartOptions, operation: string, mac
 	);
 }
 
+/** `frozen` returns before the guest has booted, like `wait: false` — and
+ *  provisioning needs a booted guest, so the pair is refused by name (#214). */
+function assertFrozenAllowsProvisioning(opts: StartOptions, operation: string, machine?: string): void {
+	if (!opts.frozen) return;
+	const source = machine
+		? `machine "${machine}" has first-boot provisioning recorded by 'add' (${operation})`
+		: `provisioning was requested (${operation})`;
+	throw new QuickCHRError(
+		"INVALID_ARGUMENT",
+		`--frozen (frozen: true) cannot be combined with provisioning: ${source}, and provisioning runs against the booted guest, so a frozen start cannot provision it. ` +
+		"Drop --frozen for this first boot — later starts can use it.",
+	);
+}
+
 // --- Socket registry lifecycle helpers ---
 
 function getSocketNamedNetworks(state: MachineState): string[] {
@@ -456,15 +483,104 @@ async function stopUnderLock(state: MachineState): Promise<void> {
 /** Persist stopped state and release endpoints. Caller holds the lifecycle lock. */
 function finalizeStoppedState(state: MachineState): void {
 	unregisterSocketMembers(state);
-	// Update persisted state
+	// A frozen marker belongs to a live QEMU held at reset — a stopped machine
+	// holds nothing, so the flag goes with the pid (#214).
 	const current = loadMachine(state.name);
 	if (current) {
 		current.status = "stopped";
 		current.pid = undefined;
+		current.frozen = undefined;
 		saveMachine(current);
 	}
 	state.status = "stopped";
 	state.pid = undefined;
+	state.frozen = undefined;
+}
+
+/** Drop the frozen marker after a resume, in state and on disk. Dual-write like
+ *  the provisioning record: the caller's handle and the next reader agree. */
+function clearFrozenMarker(state: MachineState): void {
+	const current = loadMachine(state.name);
+	if (current) {
+		current.frozen = undefined;
+		saveMachine(current);
+	}
+	state.frozen = undefined;
+}
+
+/** Best-effort QEMU argv for a continue-timeout forensics report: rebuilt from
+ *  stored state. `wasFrozen` is the marker as it stood before this resume — the
+ *  marker is already cleared by the time a timeout is captured, and only a truly
+ *  frozen spawn carried `-S`/`-gdb`. A session `--qemu-arg` override from that
+ *  start is not reflected — the report is context, and the override was
+ *  deliberately never persisted. */
+async function launchedQemuArgsForReport(state: MachineState, wasFrozen: boolean): Promise<string[]> {
+	try {
+		return await buildQemuArgs({ ...(await buildLaunchConfigFromState(state)), frozen: wasFrozen });
+	} catch {
+		return [];
+	}
+}
+
+/** The body of `continue()`, for a caller that already holds the machine lock. */
+async function continueUnderLock(state: MachineState, wait: boolean, timeoutExtra?: number): Promise<void> {
+	const pid = state.pid;
+	if (!pid || !isMachineRunning(state)) {
+		// Leave clean state behind: the marker belonged to a QEMU that is gone.
+		finalizeStoppedState(state);
+		throw new QuickCHRError(
+			"MACHINE_STOPPED",
+			`Machine "${state.name}" is not running — nothing to continue.`,
+		);
+	}
+	// Idempotent: gdb (or an earlier continue) may have resumed the guest already.
+	const status = await monitorCommand(state.machineDir, "info status", undefined, state.portBase);
+	if (!status.includes("running")) {
+		const contOut = await monitorCommand(state.machineDir, "cont", undefined, state.portBase);
+		// A QEMU-level `cont` error is the answer, not a cue to wait: the guest
+		// never resumed, so the marker stays and no boot wait is burned. Same
+		// /^error/i contract as savevm/loadvm/delvm.
+		if (/^error[:\s]/i.test(contOut)) {
+			throw new QuickCHRError("PROCESS_FAILED", `continue failed: ${contOut.trim() || "(empty)"}`);
+		}
+	}
+	const wasFrozen = state.frozen === true;
+	clearFrozenMarker(state);
+	if (!wait) return;
+
+	const instance = createInstance(state);
+	// The frozen launch's accelerator when recorded: detectAccel() prefers the
+	// current process's override, which may differ from the launch's.
+	const accel = state.lastAccel ?? await detectAccel(state.arch);
+	const bootTimeout = defaultBootTimeout(state.arch, undefined, accel) + (timeoutExtra ?? 0);
+	const probe = newBootProbeStats();
+	if (await instance.waitForBoot(bootTimeout, probe)) return;
+
+	const guest = bootFailureGuestExec(state);
+	const failure = await captureBootFailure({
+		name: state.name,
+		machineDir: state.machineDir,
+		arch: state.arch,
+		accel,
+		bootTimeoutMs: bootTimeout,
+		pid,
+		httpPort: toChrPorts(state.ports).http,
+		portBase: state.portBase,
+		qemuArgs: await launchedQemuArgsForReport(state, wasFrozen),
+		probe,
+		phase: "continue",
+		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}) after continue.` +
+		await cleanupAfterBootFailure(instance, state.name, failure, { kind: "preserve-existing" }) +
+		`\n${failure.summary}`,
+	);
 }
 
 /** The body of `remove()`, for a caller that already holds the machine lock. The lock
@@ -521,6 +637,7 @@ async function cleanUnderLock(state: MachineState): Promise<void> {
 	if (current) {
 		current.status = "stopped";
 		current.pid = undefined;
+		current.frozen = undefined;
 		current.user = undefined;
 		current.managedSshKey = undefined;
 		current.disableAdmin = undefined;
@@ -532,6 +649,7 @@ async function cleanUnderLock(state: MachineState): Promise<void> {
 	}
 	state.status = "stopped";
 	state.pid = undefined;
+	state.frozen = undefined;
 	state.user = undefined;
 	state.managedSshKey = undefined;
 	state.disableAdmin = undefined;
@@ -770,6 +888,10 @@ function createInstance(state: MachineState): ChrInstance {
 			});
 		},
 
+		async continue(options?: ContinueOptions): Promise<void> {
+			await withMachineLock(state, "continue", () => continueUnderLock(state, options?.wait ?? true, options?.timeoutExtra));
+		},
+
 		async remove(): Promise<void> {
 			await withMachineLock(state, "remove", () => removeUnderLock(state));
 		},
@@ -1575,6 +1697,9 @@ async function hardRebootMachine(
 	state.pid = pid;
 	state.status = "running";
 	state.lastStartedAt = new Date().toISOString();
+	// A power-cycle always boots normally: the replacement QEMU carries no -S,
+	// so a frozen marker from before must not survive it.
+	state.frozen = undefined;
 	saveMachine(state);
 
 	return method;
@@ -1609,6 +1734,7 @@ async function buildLaunchConfigFromState(state: MachineState): Promise<QemuLaun
 		networks: resolvedNetworks,
 		background: true,
 		portBase: state.portBase,
+		qemuArgs: state.qemuArgs,
 	};
 }
 
@@ -2078,6 +2204,7 @@ export class QuickCHR {
 				bootSize: diskOpts.bootSize,
 				extraDisks: diskOpts.extraDisks,
 				bootDiskFormat: diskArtifacts.bootDisk.format,
+				qemuArgs: opts.qemuArgs?.length ? [...opts.qemuArgs] : undefined,
 				createdAt: new Date().toISOString(),
 				status: "stopped",
 				machineDir,
@@ -2108,8 +2235,9 @@ export class QuickCHR {
 	 * Start a new or existing CHR instance.
 	 *
 	 * The returned {@link ChrInstance} is REST-ready: all provisioning (packages, license,
-	 * device-mode, user) has completed before this promise resolves. Two exceptions:
-	 * `wait: false` resolves once QEMU is running and leaves readiness to the caller, and
+	 * device-mode, user) has completed before this promise resolves. Three exceptions:
+	 * `wait: false` resolves once QEMU is running and leaves readiness to the caller,
+	 * `frozen: true` additionally holds the guest at reset for `continue()`, and
 	 * a RouterOS 6 guest (boot-only, no REST) is ready when its native API answers a login.
 	 * Callers do not need to call {@link ChrInstance.waitForBoot} again unless they have
 	 * stopped and restarted the instance manually. Disk options (`bootSize`, `extraDisks`)
@@ -2131,6 +2259,13 @@ export class QuickCHR {
 			);
 		}
 
+		if (opts.frozen && opts.background === false) {
+			throw new QuickCHRError(
+				"INVALID_ARGUMENT",
+				"--frozen (frozen: true) cannot be combined with --fg (background: false): a frozen start holds the guest at reset for gdb and a later continue, and a foreground start holds the serial console until QEMU exits instead.",
+			);
+		}
+
 		const logger = createLogger(opts.onProgress);
 
 		// Before any download or disk work: a named socket whose two ends are already
@@ -2176,6 +2311,7 @@ export class QuickCHR {
 		if (hasProvisioningMutations(mutations)) {
 			assertProvisioningSupportedVersion(version, describeProvisioningOperation(mutations));
 			assertWaitAllowsProvisioning(opts, describeProvisioningOperation(mutations));
+			assertFrozenAllowsProvisioning(opts, describeProvisioningOperation(mutations));
 		}
 
 		// Resolve architecture
@@ -2254,13 +2390,14 @@ export class QuickCHR {
 					};
 					assertProvisioningSupportedVersion(existing.version, describeProvisioningOperation(pendingMutations));
 					assertWaitAllowsProvisioning(opts, describeProvisioningOperation(pendingMutations), existing.name);
+					assertFrozenAllowsProvisioning(opts, describeProvisioningOperation(pendingMutations), existing.name);
 					requireHostFor(existing.arch);
-					return QuickCHR._launchExisting(existing, opts.background ?? true, pendingOpts, logger);
+					return QuickCHR._launchExisting(existing, opts.background ?? true, pendingOpts, logger, opts.wait ?? true, sessionLaunch(opts));
 				}
 			}
 			// Exists but stopped — restart it
 			requireHostFor(existing.arch);
-			return QuickCHR._launchExisting(existing, opts.background ?? true, undefined, logger, opts.wait ?? true);
+			return QuickCHR._launchExisting(existing, opts.background ?? true, undefined, logger, opts.wait ?? true, sessionLaunch(opts));
 		}
 
 		assertRouterOs6Arch(version, arch);
@@ -2292,6 +2429,7 @@ export class QuickCHR {
 				bootSize: diskOpts.bootSize,
 				extraDisks: diskOpts.extraDisks,
 				bootDiskFormat: diskOpts.bootDiskFormat,
+				qemuArgs: opts.qemuArgs?.length ? [...opts.qemuArgs] : undefined,
 				createdAt: new Date().toISOString(),
 				status: "stopped",
 				machineDir,
@@ -2384,6 +2522,7 @@ export class QuickCHR {
 			bootSize: diskOpts.bootSize,
 			extraDisks: diskOpts.extraDisks,
 			bootDiskFormat: bootDisk.format,
+			qemuArgs: opts.qemuArgs?.length ? [...opts.qemuArgs] : undefined,
 			createdAt: new Date().toISOString(),
 			status: "running",
 			machineDir,
@@ -2415,6 +2554,8 @@ export class QuickCHR {
 			background: spawnInBackground,
 			portBase: state.portBase,
 			accel,
+			qemuArgs: state.qemuArgs,
+			frozen: opts.frozen,
 		};
 
 		const qemuArgs = await buildQemuArgs(launchConfig);
@@ -2438,12 +2579,21 @@ export class QuickCHR {
 
 		state.pid = pid;
 		state.lastStartedAt = new Date().toISOString();
+		// Frozen skips the boot wait entirely and returns after the spawn
+		// early-exit check — by construction it can never produce BOOT_TIMEOUT.
+		// It also skips the post-boot lastAccel recording below, so record the
+		// launch accelerator here for continue()'s resume timeout.
+		if (opts.frozen) {
+			state.frozen = true;
+			state.lastAccel = accel;
+		}
 
 		saveMachine(state);
 		unpersistedSocketClaim = undefined;
 		storageLease.release();
 
 		const instance = createInstance(state);
+		if (opts.frozen) return instance;
 		if (opts.wait === false) return instance;
 
 		const bootTimeout = defaultBootTimeout(arch, opts.installAllPackages, accel) + (opts.timeoutExtra ?? 0);
@@ -2717,7 +2867,11 @@ export class QuickCHR {
 		recordProvisioning(machineState, applied);
 	}
 
-	/** Re-launch an existing stopped machine. */
+	/** Re-launch an existing stopped machine.
+	 *
+	 *  `launch` carries per-boot intent that is used for this spawn but never
+	 *  persisted: session `qemuArgs` replace the stored ones for that boot, and
+	 *  `frozen` holds the guest at reset for a later `continue()`. */
 	static async _launchExisting(
 		state: MachineState,
 		background: boolean,
@@ -2732,6 +2886,7 @@ export class QuickCHR {
 		},
 		logger?: ProgressLogger,
 		wait = true,
+		launch?: { qemuArgs?: string[]; frozen?: boolean },
 	): Promise<ChrInstance> {
 		const wantsProvisioning = (opts: typeof provisioningOpts) => !!(
 			opts && (
@@ -2812,6 +2967,9 @@ export class QuickCHR {
 		unpersistedSocketClaim = state;
 		reportSocketTransports(state, logger ?? createLogger());
 
+		// Session passthrough replaces stored args for this boot only — never written
+		// back to state, so the next plain start reuses what `add` recorded (#213).
+		const effectiveQemuArgs = launch?.qemuArgs?.length ? launch.qemuArgs : state.qemuArgs;
 		const launchConfig: QemuLaunchConfig = {
 			arch: state.arch,
 			machineDir: state.machineDir,
@@ -2824,6 +2982,8 @@ export class QuickCHR {
 			background: spawnBackground,
 			portBase: state.portBase,
 			accel,
+			qemuArgs: effectiveQemuArgs,
+			frozen: launch?.frozen,
 		};
 
 		const qemuArgs = await buildQemuArgs(launchConfig);
@@ -2845,10 +3005,18 @@ export class QuickCHR {
 		state.pid = pid;
 		state.status = "running";
 		state.lastStartedAt = new Date().toISOString();
+		// The marker describes this spawn, not the machine: a relaunch that is
+		// not frozen must not inherit a stale one (e.g. a kill -9'd frozen
+		// machine rebooted normally still listing as frozen).
+		state.frozen = launch?.frozen ? true : undefined;
+		// Frozen returns before the post-boot lastAccel recording below, so a
+		// frozen relaunch records the launch accelerator for continue().
+		if (launch?.frozen) state.lastAccel = accel;
 		saveMachine(state);
 		unpersistedSocketClaim = undefined;
 
 		const instance = createInstance(state);
+		if (launch?.frozen) return instance;
 		if (!wait) return instance;
 
 		// Always wait for boot in background mode — start() promises "REST-ready".
@@ -2939,6 +3107,7 @@ export class QuickCHR {
 		if (state.status === "running" && !isMachineRunning(state)) {
 			state.status = "stopped";
 			state.pid = undefined;
+			state.frozen = undefined;
 			saveMachine(state);
 		}
 
@@ -2997,12 +3166,7 @@ export class QuickCHR {
 	static async doctor(): Promise<DoctorResult> {
 		const checks: DoctorResult["checks"] = [];
 
-		// Bun version
-		checks.push({
-			label: "Bun runtime",
-			status: "ok",
-			detail: `bun ${Bun.version}`,
-		});
+		checks.push(await bunRuntimeCheck());
 
 		// QEMU for each arch
 		for (const arch of ARCHES) {
@@ -3125,7 +3289,7 @@ export class QuickCHR {
 			});
 		}
 
-		// qemu-img (optional, for disk resize and extra disks)
+		// qemu-img (default qcow2 creation and disk features)
 		const qemuImgPath = findQemuImg();
 		if (qemuImgPath) {
 			checks.push({
@@ -3137,7 +3301,7 @@ export class QuickCHR {
 			checks.push({
 				label: "qemu-img",
 				status: "warn",
-				detail: `not found — required for --boot-size and --add-disk (${getQemuInstallHint()})`,
+				detail: `not found — required for default qcow2 creation, setup, --boot-size and --add-disk (${getQemuInstallHint()})`,
 			});
 		}
 

package/src/lib/state.ts

@@ -386,6 +386,7 @@ export function refreshAllStatuses(): MachineState[] {
 		if (m.status === "running" && !isMachineRunning(m)) {
 			m.status = "stopped";
 			m.pid = undefined;
+			m.frozen = undefined;
 			saveMachine(m);
 		}
 	}

package/src/lib/types.ts

@@ -249,6 +249,10 @@ export interface MachineConfig {
 	extraDisks?: string[];
 	/** Format of the boot disk — raw by default, qcow2 when resized. */
 	bootDiskFormat?: BootDiskFormat;
+	/** Extra QEMU argv elements recorded by `add --qemu-arg`, reused on every boot
+	 *  unless a `start` call passes its own `qemuArgs` for that session (session
+	 *  replaces stored for that boot). Appended verbatim after quickchr's own args. */
+	qemuArgs?: string[];
 }
 
 /** One provisioning step, as recorded on {@link ProvisioningRecord.steps}. */
@@ -311,6 +315,11 @@ export interface MachineState extends MachineConfig {
 	cleanedAt?: string;
 	status: "stopped" | "running" | "error";
 	pid?: number;
+	/** Live marker: QEMU was started with `frozen: true` (`start --frozen`) and is
+	 *  held at reset (`-S`), awaiting `continue()`. Per-boot intent like
+	 *  `wait: false`, not persisted config — stopping clears it, and a later
+	 *  plain `start` boots normally. `status` stays `"running"` while frozen. */
+	frozen?: boolean;
 	/** Path to the machine directory. */
 	machineDir: string;
 	/** Accelerator resolved for the most recent boot ("kvm" | "hvf" | "tcg"). */
@@ -457,10 +466,31 @@ export interface StartOptions {
 	/** Extra milliseconds added to the computed boot timeout.
 	 *  Useful on slow hosts where `defaultBootTimeout` underestimates actual boot time. */
 	timeoutExtra?: number;
+	/** Extra QEMU argv elements, one array entry per argv element, appended verbatim
+	 *  (no splitting, no validation) after quickchr's own args.
+	 *
+	 *  On `add()` this is recorded to `machine.json` and reused every boot. On
+	 *  `start()` of an existing machine it applies to that session only: when both
+	 *  stored and session args exist, the session value replaces the stored one for
+	 *  that boot (predictable; avoids duplicate-ID errors like two `-audiodev`
+	 *  with the same id). When `start()` creates the machine, the value is both
+	 *  used for that boot and recorded, like every other creation option.
+	 *
+	 *  Ordering is load-bearing: passthrough goes last, so conflicting QEMU options
+	 *  resolve last-wins (e.g. a duplicate `-M pc,...` merges over quickchr's `-M pc`).
+	 *  A bad element surfaces as `SPAWN_FAILED` with the QEMU log tail. */
+	qemuArgs?: string[];
 	/** Progress callback for status messages during start.
 	 *  If not provided, messages go to console.log.
 	 *  Debug-level messages (prefixed [debug]) are only emitted when QUICKCHR_DEBUG=1. */
 	onProgress?: (message: string) => void;
+	/** Boot frozen at reset (`-S`) with a gdbstub on `<machineDir>/gdb.sock`,
+	 *  for harnesses that must touch the guest before RouterOS init runs (e.g.
+	 *  RAM patching via gdb). Skips the boot wait entirely and resolves after
+	 *  the spawn early-exit check, like `wait: false` — resume with
+	 *  `continue()`. Refused with provisioning and with `background: false`.
+	 *  Per-boot intent: never persisted, so a later plain `start` boots normally. */
+	frozen?: boolean;
 }
 
 // --- Instance (runtime handle) ---
@@ -631,6 +661,18 @@ export interface ShutdownResult {
 	requestError?: string;
 }
 
+/** Options for {@link ChrInstance.continue}. */
+export interface ContinueOptions {
+	/** Wait for REST-ready before resolving (true, default), mirroring `start()`'s
+	 *  promise. `false` returns right after the monitor `cont`, leaving readiness
+	 *  to the caller. A wait that never reaches REST is a genuine `BOOT_TIMEOUT`. */
+	wait?: boolean;
+	/** Extra milliseconds added to the computed boot timeout — the same knob as
+	 *  `StartOptions.timeoutExtra`, for slow hosts where the default underestimates
+	 *  the resume-to-ready time. */
+	timeoutExtra?: number;
+}
+
 /**
  * Runtime handle for a CHR virtual machine.
  *
@@ -640,7 +682,7 @@ export interface ShutdownResult {
  *
  * After `QuickCHR.start()` resolves, the instance is REST-ready — all requested
  * provisioning (packages, license, device-mode, user creation) has completed —
- * unless it was started with `wait: false`, or is a RouterOS 6 guest (no REST:
+ * unless it was started with `wait: false` or `frozen: true`, or is a RouterOS 6 guest (no REST:
  * `rest()` and REST `exec()` throw `REST_UNAVAILABLE`).
  */
 export interface ChrInstance {
@@ -712,6 +754,11 @@ export interface ChrInstance {
 	/** Request /system/shutdown once over REST, wait for QEMU exit, then hard-stop
 	 * if needed. Reports forced fallback explicitly; preserves disks and credentials. */
 	shutdown(options?: ShutdownOptions): Promise<ShutdownResult>;
+	/** Resume a machine started with `frozen: true` (`start --frozen`): one monitor
+	 *  `cont`, then REST-ready by default. Idempotent — when the guest is already
+	 *  running (e.g. gdb continued it) this just clears the frozen marker. Throws
+	 *  `MACHINE_STOPPED` when QEMU is gone. */
+	continue(options?: ContinueOptions): Promise<void>;
 	remove(): Promise<void>;
 	clean(): Promise<void>;
 	/** Stop and permanently delete this instance (disk + state). Equivalent to stop() then remove(). */