@tikoci/quickchr 0.5.2 → 0.5.3

package/DESIGN.md

@@ -1176,3 +1176,39 @@ before acting, and uses shared stopped-state cleanup without recursively taking
 the non-reentrant stop lock. It confirms QEMU exit before clearing the PID or
 releasing named-network membership. Lock wait, hard-stop escalation and final
 exit verification are separate bounded phases outside the guest grace budget.
+
+## Frozen boot + continue (#214)
+
+Some lab workflows must touch the guest before RouterOS init runs. The driver:
+CHR's `:beep` speaker driver is skipped when CPUID reports a hypervisor, and
+patching the 2-byte gate in guest RAM via gdbstub before sys2 init unlocks
+PC-speaker capture for acoustic testing (verified on CHR 7.25, QEMU 11.1.2).
+`start --frozen` boots held at reset (`-S`) with a gdbstub; `quickchr continue`
+resumes. The RAM patch itself stays in the harness, not quickchr.
+
+The gdbstub is a unix socket (`-gdb unix:<machineDir>/gdb.sock,server=on,
+wait=off`), not `-s` (TCP :1234): no port bookkeeping, no parallel-VM
+collisions. `wait=off` is required so the spawn never blocks waiting for a
+client. Measured: `info status` reads `paused (prelaunch)`; gdb attaches with
+the CPU at the reset vector `0xfff0`. POSIX-first by scope — a Windows TCP
+fallback (e.g. `portBase+9`) is parked as a follow-up, and the integration test
+is gated off win32 until it lands.
+
+`frozen` is per-boot intent, like `--no-wait`, not persisted config: stopping
+clears the marker and a later plain `start` boots normally. `status` stays
+`"running"` while frozen — without a third status value — so `isMachineRunning()`,
+`stop`/`remove` (host-side SIGTERM works on frozen QEMU unchanged), and the
+`--all` filters keep working untouched. A never-continued frozen machine can
+never produce `BOOT_TIMEOUT`, by construction: the boot wait is skipped
+entirely, and `start` returns after the spawn early-exit check.
+
+`continue` is one existing primitive — `monitorCommand("cont")` — plus the
+promise `start` makes: REST-ready by default, `--no-wait` to return
+immediately, `--timeout-extra` extending the resume wait like `start`. It
+checks `info status` first, so a guest gdb already resumed just clears the
+marker (idempotent); a QEMU-level `cont` error throws `PROCESS_FAILED` before
+the marker is touched (same `/^error/i` contract as savevm/loadvm); a dead pid
+is `MACHINE_STOPPED`; a wait that never reaches REST is a genuine
+`BOOT_TIMEOUT` with `preserve-existing` cleanup. Deliberately out: no frozen-specific hint on `exec`/`get` failures,
+and no `savevm` refusal on prelaunch VMs (snapshot is already tricky business;
+QEMU accepts or errors on its own).

package/MANUAL.md

@@ -167,6 +167,7 @@ directory, downloads the RouterOS image (cached), and writes
 | `--no-winbox` | false | Exclude WinBox port |
 | `--no-api-ssl` | false | Exclude API-SSL port |
 | `--port-base <n>` | auto from 9100 | First port of the 10-port block |
+| `--qemu-arg <arg>` | — | Extra QEMU argv element, repeatable (space form only). Recorded and reused every boot. See Extra QEMU arguments below. |
 
 `--vmnet-shared` and `--vmnet-bridge <iface>` have been removed. Use
 `--add-network shared` and `--add-network bridged:<iface>`; either old spelling is
@@ -194,7 +195,9 @@ Additional flags:
 | `--fg` / `--foreground` (alias `--no-bg`, `--no-background`) | Serial console on stdio |
 | `--bg` / `--background` | **Deprecated, does nothing.** Background is the default, and the flag never made `start` return early — it only ever chose where the serial console went. Prints a warning; use `--no-wait` |
 | `--timeout-extra <s>` / `-T <s>` | Add extra seconds to computed boot timeout |
-| `--dry-run` | Print resolved options and QEMU command, exit |
+| `--dry-run` | Print the resolved start options as JSON (including `qemuArgs`/`frozen`) and exit — not the final QEMU argv |
+| `--qemu-arg <arg>` | Extra QEMU argv element, repeatable (space form only). Recorded when creating; on an existing machine it replaces recorded args for this boot only. Refused with `--all`. |
+| `--frozen` | Boot frozen at reset (`-S`) with a gdbstub; resume with `continue`. Refused with `--fg`, provisioning, and `--all` |
 
 After `--no-wait`, readiness is yours. centrs (0.1.8+) waits for it in one command:
 
@@ -218,6 +221,62 @@ When `--fg` is combined with provisioning options, quickchr boots
 foreground with stdio attached. This is observable as a brief stop in
 machine state.
 
+**Extra QEMU arguments (`--qemu-arg`).** One argv element per occurrence,
+appended verbatim (no splitting, no validation) after quickchr's own args.
+Use the space form: `--qemu-arg=x` overwrites instead of accumulating, so
+mixing space and `=` forms keeps only the `=` values. Values beginning with
+`--` need the `--qemu-arg=<arg>` form (one element per flag).
+
+Passthrough runs with your privileges and is replayed every boot: it can
+touch any path you can (`-drive`, `-audiodev`) or open QEMU-side listeners,
+so treat recorded args like config you own. A bad recorded arg fails every
+start; recover with a session override (`start <name> --qemu-arg …`) and then
+persist the fix with `set <name> --qemu-arg …` (or `--clear-qemu-args`) while
+stopped.
+Ordering is load-bearing — passthrough goes last, so a conflicting option
+resolves last-wins (a duplicate `-M pc,...` merges over quickchr's `-M pc`;
+measured on QEMU 11.1.2). A bad element surfaces as `SPAWN_FAILED` with the
+QEMU log tail. Lab escape hatch for QEMU surface quickchr does not model —
+e.g. capturing the CHR PC speaker (x86 only) to a WAV file:
+
+```sh
+quickchr start beep-lab --version 7.25 --arch x86 \
+  --qemu-arg -M --qemu-arg pc,pcspk-audiodev=cap \
+  --qemu-arg -audiodev --qemu-arg wav,id=cap,path=$PWD/cap.wav
+# cap.wav is created at spawn (0 bytes while running); QEMU flushes the
+# 44-byte RIFF header on exit. Capturing actual beeps also needs the
+# --frozen RAM-patch workflow below: stock CHR skips :beep under a
+# hypervisor, so an unpatched guest never emits audio.
+```
+
+#### `continue <name> [--no-wait] [--timeout-extra <s>]`
+
+Resume a machine started with `start --frozen` (held at reset with a
+gdbstub). Sends one monitor `cont`, then waits for RouterOS to become
+ready — the same promise `start` makes. `--no-wait` returns right after
+resuming; `--timeout-extra`/`-T` extends the resume timeout like `start`. Idempotent: when the guest is already running (e.g. gdb
+continued it), this just clears the frozen marker. A machine that never
+reaches readiness is a `BOOT_TIMEOUT`; it is stopped and preserved.
+
+`--frozen` exists for harnesses that must touch the guest before RouterOS
+init runs — e.g. patching guest RAM via gdb, then resuming:
+
+```sh
+quickchr start beep-lab --version 7.25 --arch x86 --frozen
+# frozen at reset; gdb at <machineDir>/gdb.sock (see 'quickchr list beep-lab')
+gdb -ex "target remote /path/to/machines/beep-lab/gdb.sock" \
+    -ex "set *(char *)0xADDR = 0x.." -ex detach -ex quit
+quickchr continue beep-lab
+# resumed, REST-ready
+```
+
+Frozen is per-boot intent, not config: `stop` clears it and a later plain
+`start` boots normally. `list` marks frozen machines (`(frozen)` in the
+table, a `Frozen:` line plus the gdb socket path in the detail view).
+Note the vocabulary overlap: this `frozen` (QEMU held at reset) is a
+different domain from QGA `fsfreeze-status` (guest filesystems frozen for
+snapshots).
+
 #### `stop [name | --all]`
 
 Power cut: sends SIGTERM to QEMU, waits up to 5 seconds, then SIGKILL if
@@ -322,7 +381,10 @@ repeat the original command rather than to run a bare `start`.
 
 Without a name: tabular summary of every machine. With a name: detailed
 view including credentials and connection tips. `--json` for
-machine-readable output.
+machine-readable output. A machine held by `start --frozen` shows
+`(frozen)` in the table and a `Frozen:` line with its gdb socket path in
+the detail view; single-machine `--json` carries `frozen` (and the recorded
+`qemuArgs`) alongside the other fields.
 
 A machine whose `machine.json` cannot be read — unreadable on disk, not valid JSON, or
 valid JSON that is not usable machine state — still appears, as a row marked
@@ -449,6 +511,8 @@ flags that were asked for so it can be run as given.
 | `--device-mode <m>` | `rose`, `advanced`, `basic`, `home`, `auto`. |
 | `--device-mode-enable <f,…>` | Set one or more device-mode flags to yes. Repeatable, comma-separated. |
 | `--device-mode-disable <f,…>` | Set one or more to no. |
+| `--qemu-arg <arg>` | Replace the recorded QEMU passthrough args (repeatable, space-form only). Stopped only; takes effect on the next start. |
+| `--clear-qemu-args` | Drop the recorded QEMU passthrough args. Stopped only. |
 
 **Device-mode restarts the machine.** RouterOS only applies a device-mode change
 across a power cycle, and quickchr owns the power button — which is why this lives
@@ -819,7 +883,7 @@ throws `INVALID_NAME` for a name that is not a usable path segment.
 |---|---|---|
 | Identity | `name`, `state`, `ports`, `restUrl`, `sshPort`, `portBase` | Static metadata persisted in `machine.json` |
 | Capture | `captureInterface`, `hostGatewayIp` | Platform-correct values for TZSP capture (`tshark -i …`) and the guest→host address any UDP emitter targets |
-| Lifecycle | `waitForBoot()`, `waitFor(fn, ms?)`, `stop()`, `shutdown(opts?)`, `remove()`, `clean()`, `destroy()` | Boot readiness, custom polling, power-cut or guest-shutdown teardown |
+| Lifecycle | `waitForBoot()`, `waitFor(fn, ms?)`, `stop()`, `shutdown(opts?)`, `continue(opts?)`, `remove()`, `clean()`, `destroy()` | Boot readiness, custom polling, power-cut or guest-shutdown teardown, frozen resume |
 | Comms | `rest()`, `exec()`, `monitor()`, `serial()`, `qga()` | REST, RouterOS CLI, QEMU monitor, serial console, QGA (x86 only) |
 | Provisioning | `license()`, `setDeviceMode()`, `availablePackages()`, `installPackage()` | Post-boot configuration |
 | Files | `upload()`, `download()` | SCP transfer to/from the CHR |
@@ -841,6 +905,7 @@ interface ChrInstance {
   waitFor(condition: () => Promise<boolean>, timeoutMs?: number): Promise<boolean>;
   stop(): Promise<void>;      // power cut: SIGTERM, then SIGKILL
   shutdown(opts?: ShutdownOptions): Promise<ShutdownResult>; // /system/shutdown, bounded fallback
+  continue(opts?: ContinueOptions): Promise<void>; // resume a frozen start, REST-ready by default
   remove(): Promise<void>;
   clean(): Promise<void>;
   destroy(): Promise<void>;   // stop + remove
@@ -927,6 +992,8 @@ redact before logging or attaching to bug reports.
 | `installDeps` | boolean | — | **Deprecated, ignored.** Never installed anything; run `quickchr doctor` for install hints |
 | `dryRun` | boolean | `false` | Print QEMU command and exit |
 | `timeoutExtra` | number | `0` | Extra **milliseconds** added to boot timeout |
+| `qemuArgs` | string[] | — | Extra QEMU argv elements, one entry each, appended verbatim last. Recorded by `add()`; a `start()` value replaces stored args for that boot only |
+| `frozen` | boolean | `false` | Boot frozen at reset with a gdbstub; resume with `continue()`. Refused with provisioning or `background: false` |
 | `onProgress` | `(msg) => void` | `console.log` | `[debug]` lines only when `QUICKCHR_DEBUG=1` |
 
 Provisioning fields trigger a version check at the top of `start()` /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/quickchr",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",

package/src/cli/flags.ts

@@ -20,12 +20,13 @@ const CREATE_FLAGS = [
 	"boot-disk-format", "boot-size", "add-disk",
 	"device-mode", "device-mode-enable", "device-mode-disable",
 	"add-user", "disable-admin", "secure-login",
+	"qemu-arg",
 ] as const;
 
 /** `start` also boots, so it owns the run-time flags on top of the create set. */
 const START_ONLY_FLAGS = [
 	"all", "dry-run", "wait", "background", "bg", "fg", "foreground",
-	"timeout-extra",
+	"timeout-extra", "frozen",
 	"license-level", "license-account", "license-password",
 ] as const;
 
@@ -40,6 +41,7 @@ const START_ONLY_FLAGS = [
 const SET_ONLY_FLAGS = [
 	"name", "license", "level", "account", "password",
 	"device-mode", "device-mode-enable", "device-mode-disable",
+	"qemu-arg", "clear-qemu-args",
 ] as const;
 
 export const ADD_FLAGS: readonly string[] = CREATE_FLAGS;
@@ -78,6 +80,7 @@ export const VALUE_FLAGS: ReadonlySet<string> = new Set([
 	"device-mode", "device-mode-enable", "device-mode-disable",
 	"add-user", "timeout-extra",
 	"license-level", "license-account", "license-password",
+	"qemu-arg",
 	// exec / qga / console
 	"via", "user", "password", "timeout", "path", "data", "script",
 	// set --license

package/src/cli/index.ts

@@ -4,6 +4,7 @@
  */
 
 import type { StartOptions, Arch, Channel, DeviceModeOptions, ServiceName, NetworkSpecifier } from "../lib/types.ts";
+import { join } from "node:path";
 import { parseNetworkSpecifier } from "../lib/network.ts";
 import { expandForwardSpec } from "../lib/forward-spec.ts";
 import { ADD_FLAGS, REMOVED_FLAGS, SET_FLAGS, START_FLAGS, VALUE_FLAGS, unknownFlags, unknownFlagMessage, valuelessFlags, valuelessFlagMessage } from "./flags.ts";
@@ -337,6 +338,9 @@ async function main() {
 			case "start":
 				await cmdStart(args.slice(1));
 				break;
+			case "continue":
+				await cmdContinue(args.slice(1));
+				break;
 			case "stop":
 				await cmdStop(args.slice(1));
 				break;
@@ -732,6 +736,7 @@ async function cmdAdd(argv: string[]) {
 		bootSize: flag(flags, "boot-size"),
 		extraDisks: flagList(flags, "add-disk").length > 0 ? flagList(flags, "add-disk") : undefined,
 		extraPorts: flagList(flags, "forward").flatMap(expandForwardSpec),
+		qemuArgs: flagList(flags, "qemu-arg").length > 0 ? flagList(flags, "qemu-arg") : undefined,
 	};
 
 	opts.deviceMode = deviceModeFromFlags(flags);
@@ -1362,15 +1367,16 @@ async function cmdSetup() {
 
 /** Whether the `secure-login` *setting* reaches this start. The setting is a default,
  *  not a request, so it stays out of every start that cannot provision: a closed
- *  window, a `--no-wait` start (#159), and a RouterOS 6 machine (#182). Otherwise a
- *  user with `secure-login=true` configured could never use either. An explicit
- *  `--secure-login` is still passed through, and refused by name. */
+ *  window, a `--no-wait` start (#159), a `--frozen` start (#214), and a RouterOS 6
+ *  machine (#182). Otherwise a user with `secure-login=true` configured could never
+ *  use any of them. An explicit `--secure-login` is still passed through, and
+ *  refused by name. */
 export function secureLoginSettingApplies(
 	flags: Record<string, string | boolean | string[]>,
 	windowOpen: boolean,
 	version: string | undefined,
 ): boolean {
-	return windowOpen && flags.wait !== false && !isRouterOs6(version ?? "");
+	return windowOpen && flags.wait !== false && flags.frozen !== true && !isRouterOs6(version ?? "");
 }
 
 /** `--bg` never did what it reads as (#159): background is the default, and the flag
@@ -1482,6 +1488,7 @@ export async function cmdStart(argv: string[]) {
 		extraPorts: flagList(flags, "forward").flatMap(expandForwardSpec),
 		dryRun: flagBool(flags, "dry-run"),
 		timeoutExtra: await resolveTimeoutExtraMs(flags),
+		qemuArgs: flagList(flags, "qemu-arg").length > 0 ? flagList(flags, "qemu-arg") : undefined,
 	};
 
 	opts.deviceMode = deviceModeFromFlags(flags);
@@ -1525,6 +1532,7 @@ export async function cmdStart(argv: string[]) {
 		));
 	}
 	opts.wait = wait;
+	opts.frozen = flagBool(flags, "frozen") || undefined;
 
 	// Background default: true. Explicitly foreground only with --fg / --foreground / --no-background / --no-bg.
 	// `--bg` / `--background` are accepted and change nothing (see warnDeprecatedBackgroundFlag).
@@ -1541,8 +1549,9 @@ export async function cmdStart(argv: string[]) {
 	}
 
 	// --fg on already-running machine: attach to its serial console.
-	// `--fg --no-wait` skips both foreground blocks so start() refuses the pair before any I/O.
-	if (!opts.background && opts.wait !== false && opts.name) {
+	// `--fg --no-wait` and `--fg --frozen` skip both foreground blocks so start()
+	// refuses the pair before any I/O.
+	if (!opts.background && opts.wait !== false && !opts.frozen && opts.name) {
 		const runningMachine = QuickCHR.list().find((m) => m.name === opts.name && m.status === "running");
 		if (runningMachine) {
 			await attachSerial(runningMachine.name, runningMachine.machineDir);
@@ -1550,7 +1559,7 @@ export async function cmdStart(argv: string[]) {
 		}
 	}
 
-	if (!opts.background && opts.wait !== false) {
+	if (!opts.background && opts.wait !== false && !opts.frozen) {
 		const wantsDeviceMode = !!opts.deviceMode && !["skip", "none", "off", "disabled"].includes((opts.deviceMode.mode ?? "auto").toLowerCase());
 		const hasProv = !!(
 			opts.installAllPackages ||
@@ -1571,7 +1580,12 @@ export async function cmdStart(argv: string[]) {
 
 	const instance = await QuickCHR.start(opts);
 
-	if (!opts.background) {
+	// The marker describes the machine, not the request: --frozen on an
+	// already-running normal machine returns that handle unfrozen.
+	if (instance.state.frozen) {
+		console.log(`${statusIcon("running")} ${bold(instance.name)} frozen at reset — patch RAM, then ${bold(`quickchr continue ${instance.name}`)}`);
+		console.log(`  GDB:     ${dim(join(instance.state.machineDir, "gdb.sock"))}`);
+	} else if (!opts.background) {
 		console.log(`\n${bold(instance.name)} session ended`);
 		console.log(`  ${dim("Tip: resume session")}   quickchr start ${instance.name} --fg`);
 		console.log(`  ${dim("Tip: run background")}   quickchr start ${instance.name}`);
@@ -1597,6 +1611,39 @@ export async function cmdStart(argv: string[]) {
 	}
 }
 
+export async function cmdContinue(argv: string[]) {
+	const { flags, positional } = parseFlags(argv);
+	applyTimeoutExtraShortFlag(argv, flags, positional);
+	const invalid = unknownFlags(flags, ["wait", "timeout-extra"]);
+	if (invalid.length) throw new QuickCHRError("INVALID_ARGUMENT", "continue accepts only <name>, --no-wait and --timeout-extra <s>");
+	const name = positional[0];
+	if (!name || positional.length !== 1) throw new QuickCHRError("INVALID_ARGUMENT", "Usage: quickchr continue <name> [--no-wait] [--timeout-extra <s>]");
+	const { QuickCHR } = await import("../lib/quickchr.ts");
+	const { machineNotFoundMessage } = await import("./format.ts");
+	const instance = QuickCHR.get(name);
+	if (!instance) {
+		console.error(machineNotFoundMessage(name));
+		process.exit(1);
+	}
+	const wait = flags.wait !== false;
+	const timeoutExtra = await resolveTimeoutExtraMs(flags);
+	await instance.continue({ wait, timeoutExtra });
+	const { statusIcon, bold, link, resolveDisplayCredentials, formatRestUrl, formatSshCommand } = await import("./format.ts");
+	if (!wait) {
+		console.log(`${statusIcon("running")} ${bold(name)} resumed — not waiting for RouterOS (--no-wait)`);
+		printReadinessTip(name, instance.state.version);
+		return;
+	}
+	const creds = await resolveDisplayCredentials(instance.state);
+	console.log(`${statusIcon("running")} ${bold(name)} resumed`);
+	if (isRouterOs6(instance.state.version)) {
+		console.log(`  API:     127.0.0.1:${instance.ports.api}`);
+	} else {
+		console.log(`  REST:    ${link(formatRestUrl(instance.ports.http, creds.user, creds.password))}`);
+	}
+	console.log(`  SSH:     ${formatSshCommand(creds.user, instance.sshPort)}`);
+}
+
 async function cmdShutdown(argv: string[]) {
 	const { flags, positional } = parseFlags(argv);
 	const invalid = unknownFlags(flags, ["timeout"]);
@@ -1691,6 +1738,8 @@ async function cmdList(argv: string[] = []) {
 				networks: s.networks,
 				ports: s.ports,
 				pid: s.pid ?? null,
+				frozen: s.frozen ?? false,
+				qemuArgs: s.qemuArgs ?? [],
 				packages: s.packages,
 				machineDir: s.machineDir,
 				createdAt: s.createdAt,
@@ -1706,6 +1755,10 @@ async function cmdList(argv: string[] = []) {
 		console.log(`  Network:    ${formatNetworks(s.networks)}`);
 		console.log(`  Ports:      ${formatPorts(s.ports)}`);
 		console.log(`  Status:     ${s.status}${s.pid ? ` (PID ${s.pid})` : ""}`);
+		if (s.frozen) {
+			console.log(`  Frozen:     yes — awaiting quickchr continue`);
+			console.log(`  GDB:        ${dim(join(s.machineDir, "gdb.sock"))}`);
+		}
 		console.log(`  Created:    ${new Date(s.createdAt).toLocaleString()}`);
 		if (s.lastStartedAt) console.log(`  Started:    ${new Date(s.lastStartedAt).toLocaleString()}`);
 		if (s.packages.length > 0) console.log(`  Packages:   ${s.packages.join(", ")}`);
@@ -1715,6 +1768,7 @@ async function cmdList(argv: string[] = []) {
 		if (s.status === "running") {
 			const creds = await resolveDisplayCredentials(s);
 			console.log();
+			if (s.frozen) console.log(`  ${dim(`(endpoints answer after 'quickchr continue ${s.name}')`)}`);
 			console.log(`  REST:       ${link(formatRestUrl(instance.ports.http, creds.user, creds.password))}`);
 			console.log(`  WinBox:     127.0.0.1:${instance.ports.winbox}`);
 			console.log(`  SSH:        ${formatSshCommand(creds.user, instance.sshPort)}`);
@@ -1760,7 +1814,7 @@ async function cmdList(argv: string[] = []) {
 	const headers = ["", "Name", "Version", "Arch", "Network", "Ports", "PID"];
 	const rows = machines.map((m) => [
 		statusIcon(m.status),
-		m.name,
+		m.frozen ? `${m.name} (frozen)` : m.name,
 		m.version,
 		m.arch,
 		formatNetworks(m.networks ?? []),
@@ -2149,7 +2203,7 @@ async function cmdSet(argv: string[]) {
 	// --license` printed a usage error while `quickchr license --name lab` worked.
 	const name = positional[0] ?? flag(flags, "name");
 
-	const usage = "Usage: quickchr set <name> [--license [--level=p1|p10|unlimited]] [--device-mode <mode>] [--device-mode-enable <features>] [--device-mode-disable <features>]";
+	const usage = "Usage: quickchr set <name> [--license [--level=p1|p10|unlimited]] [--device-mode <mode>] [--device-mode-enable <features>] [--device-mode-disable <features>] [--qemu-arg <arg>] [--clear-qemu-args]";
 	if (!name) {
 		console.error(usage);
 		process.exit(1);
@@ -2171,12 +2225,22 @@ async function cmdSet(argv: string[]) {
 
 	const wantsLicense = flagBool(flags, "license");
 	const deviceMode = deviceModeFromFlags(flags);
+	const qemuArgs = flagList(flags, "qemu-arg");
+	const clearQemuArgs = flagBool(flags, "clear-qemu-args");
+	const wantsQemuArgs = qemuArgs.length > 0 || clearQemuArgs;
+	if (qemuArgs.length > 0 && clearQemuArgs) {
+		throw new QuickCHRError("INVALID_ARGUMENT", "--qemu-arg and --clear-qemu-args conflict: --qemu-arg already replaces the recorded args wholesale");
+	}
 
-	if (!wantsLicense && !deviceMode) {
-		console.error("Nothing to set. Available flags: --license, --device-mode, --device-mode-enable, --device-mode-disable");
+	if (!wantsLicense && !deviceMode && !wantsQemuArgs) {
+		console.error("Nothing to set. Available flags: --license, --device-mode, --device-mode-enable, --device-mode-disable, --qemu-arg, --clear-qemu-args");
 		process.exit(1);
 	}
 
+	// Recorded args first: they need a stopped machine, and failing fast here
+	// keeps a running-machine refusal from racing a device-mode power cycle.
+	if (wantsQemuArgs) await applyQemuArgsChange(name, qemuArgs, clearQemuArgs);
+
 	// Device-mode first: it power-cycles the guest, and a license applied beforehand
 	// would be read back across a reboot it did not expect.
 	if (deviceMode) await applyDeviceModeChange(name, deviceMode);
@@ -2186,6 +2250,43 @@ async function cmdSet(argv: string[]) {
 	}
 }
 
+/** `set <name> --qemu-arg…` — the recovery route for recorded passthrough.
+ *
+ *  Boot config, not provisioning: it takes effect on the next start, so the
+ *  machine must be stopped — accepting it on a running machine would promise a
+ *  change that cannot happen until reboot. Replaces the recorded args wholesale
+ *  (one element per flag, like `add`); `--clear-qemu-args` drops them. A bad
+ *  recorded arg otherwise fails every start until `machine.json` is hand-edited;
+ *  this is the supported way back. */
+async function applyQemuArgsChange(name: string, qemuArgs: string[], clear: boolean) {
+	const { QuickCHR } = await import("../lib/quickchr.ts");
+	const { bold, machineNotFoundMessage } = await import("./format.ts");
+	const { loadMachine, saveMachine } = await import("../lib/state.ts");
+
+	const instance = QuickCHR.get(name);
+	if (!instance) {
+		console.error(machineNotFoundMessage(name));
+		process.exit(1);
+	}
+	if (instance.state.status === "running") {
+		console.error(`Machine "${name}" is running — stop it first: qemuArgs apply at boot, so 'set' only records them on a stopped machine.`);
+		process.exit(1);
+	}
+	const current = loadMachine(name);
+	if (!current) {
+		console.error(machineNotFoundMessage(name));
+		process.exit(1);
+	}
+	current.qemuArgs = clear ? undefined : [...qemuArgs];
+	saveMachine(current);
+	instance.state.qemuArgs = current.qemuArgs;
+	if (clear) {
+		console.log(`Cleared recorded QEMU args on ${bold(name)} — the next start boots without passthrough.`);
+	} else {
+		console.log(`Recorded QEMU args on ${bold(name)}: ${qemuArgs.join(" ")}`);
+	}
+}
+
 /** `set <name> --device-mode…` — the post-boot route the refusal names.
  *
  *  Device-mode needs a **power cycle**: RouterOS will not apply it otherwise, and
@@ -3179,6 +3280,7 @@ Commands:
   setup                   Interactive setup wizard (TTY only)
   add [options]           Create a new CHR machine (without starting)
   start [<name>|options]  Start or restart a CHR instance
+  continue <name>         Resume a machine started with --frozen
   stop [<name>|--all]     Power cut — print list if no name
   shutdown <name>         Request guest shutdown, then bounded hard-stop fallback
   list [<name>] [--json]  List all instances, or detail for one
@@ -3269,6 +3371,10 @@ Options:
   --add-network <spec>  Add a network NIC (repeatable). Specs: user, shared, bridged:<if>,
                         socket::<name>, tap:<if>. Default: single user NIC.
   --no-network          Start with no NICs (headless)
+  --qemu-arg <arg>      Extra QEMU argv element, appended verbatim after quickchr's
+                        own args (repeatable, space-form only: one element per
+                        flag). Recorded here and reused every boot; a start-time
+                        value replaces it for that boot only.
 
 Provisioning flags apply on the machine's first boot — whether they are given
 here or on that first 'start'. After the guest has booted, a flag the machine already
@@ -3346,6 +3452,8 @@ Options:
                         (plus the deprecated no-op --bg / --background); any other
                         option is refused rather than ignored
   --no-wait             Return once QEMU is running; do not wait for RouterOS (not with --fg)
+  --frozen              Boot frozen at reset (-S) with a gdbstub on <machineDir>/gdb.sock;
+                        resume with 'quickchr continue' (not with --fg, --all or provisioning)
   --fg / --foreground   Run in foreground — serial console on stdio
   --bg / --background   Deprecated, does nothing: background is already the default
   --version <ver>       RouterOS version (e.g., 7.22.1)
@@ -3386,6 +3494,10 @@ Options:
   --no-device-mode      Skip device-mode provisioning entirely
   --timeout-extra <s>, -T <s>  Add extra seconds to the auto-computed boot timeout
   --dry-run             Print what would run without starting
+  --qemu-arg <arg>      Extra QEMU argv element, appended verbatim after quickchr's
+                        own args (repeatable, space-form only: one element per
+                        flag). Recorded when creating; on an existing machine it
+                        replaces recorded args for this boot only.
 
 Provisioning flags (packages, login, device-mode, license) apply only on a machine's
 first boot. On a machine that has booted, a flag the machine already has (same
@@ -3394,6 +3506,22 @@ naming where the change can still be made — often 'quickchr set <name>'. Only
 'quickchr clean <name>' if you mean it: it resets the disk to factory, erasing the
 guest's configuration, and reopens the first-boot window.`);
 			break;
+		case "continue":
+			console.log(`quickchr continue <name> [--no-wait] [--timeout-extra <s>]
+
+Resume a machine started with 'start --frozen' (held at reset with a gdbstub
+on <machineDir>/gdb.sock). Sends one monitor 'cont', then waits for RouterOS
+to become ready — the same promise 'start' makes.
+
+  <name>      Name of a frozen (or otherwise paused) running machine.
+  --no-wait   Return right after resuming; do not wait for RouterOS.
+  --timeout-extra <s>, -T <s>
+              Add extra seconds to the auto-computed resume timeout.
+
+Resuming is idempotent: when the guest is already running (e.g. gdb continued
+it), this just clears the frozen marker. A wait that never reaches readiness
+is a BOOT_TIMEOUT; the machine is stopped and preserved.`);
+			break;
 		case "stop":
 			console.log(`quickchr stop [<name>] [--all]
 
@@ -3545,6 +3673,10 @@ Flags:
   --device-mode <m>   Set device-mode: rose|advanced|basic|home|auto
   --device-mode-enable <f>   Set one or more device-mode flags to yes (e.g. container)
   --device-mode-disable <f>  Set one or more device-mode flags to no
+  --qemu-arg <arg>    Replace the recorded QEMU passthrough args (repeatable,
+                      space-form only). The machine must be stopped; takes
+                      effect on the next start.
+  --clear-qemu-args   Drop the recorded QEMU passthrough args. Stopped only.
 
 Device-mode notes:
   RouterOS only applies device-mode across a power cycle, so 'set' restarts the

package/src/index.ts

@@ -32,6 +32,7 @@ export type {
 	Channel,
 	ChrInstance,
 	ChrPorts,
+	ContinueOptions,
 	CustomForward,
 	Descriptor,
 	DeviceModeOptions,

package/src/lib/completions.ts

@@ -328,7 +328,7 @@ _quickchr() {
         cword=${D}COMP_CWORD
     }
 
-    local commands="add start stop shutdown list ls status inspect env get set remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help"
+    local commands="add start continue stop shutdown list ls status inspect env get set remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help"
 
     if [[ ${D}cword -eq 1 ]]; then
         COMPREPLY=( $(compgen -W "${D}commands" -- "${D}cur") )
@@ -337,7 +337,7 @@ _quickchr() {
 
     local cmd="${D}{words[1]}"
     case "${D}cmd" in
-        start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env|get|set)
+        start|continue|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env|get|set)
             local machines
             machines=$(quickchr completions --machines 2>/dev/null)
             COMPREPLY=( $(compgen -W "${D}machines" -- "${D}cur") )
@@ -387,6 +387,7 @@ _quickchr() {
             local commands=(
                 'add:Create a new CHR machine (without starting)'
                 'start:Start or restart a CHR instance'
+                'continue:Resume a machine started with --frozen'
                 'stop:Power cut instance(s)'
                 'shutdown:Request guest shutdown'
                 'list:List all instances'
@@ -421,7 +422,7 @@ _quickchr() {
         args)
             local cmd="${D}{words[2]}"
             case ${D}cmd in
-                start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env|get|set)
+                start|continue|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env|get|set)
                     local machines
                     machines=(${D}{(f)"${D}(quickchr completions --machines 2>/dev/null)"})
                     _describe 'machine' machines
@@ -447,7 +448,7 @@ _quickchr() {
                     _describe 'cache subcommand' subcommands
                     ;;
                 help)
-                    local commands=(add start stop shutdown list status inspect env get set remove clean console exec qga license disk snapshot networks cache doctor settings setup completions version)
+                    local commands=(add start continue stop shutdown list status inspect env get set remove clean console exec qga license disk snapshot networks cache doctor settings setup completions version)
                     _describe 'command' commands
                     ;;
             esac
@@ -463,7 +464,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 shutdown list ls status inspect env get set remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help
+set -l quickchr_commands add start continue stop shutdown list ls status inspect env get set remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help
 
 # Disable file completions globally for quickchr
 complete -c quickchr -f
@@ -473,6 +474,8 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "add"         -d "Create a new CHR machine"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "start"       -d "Start or restart a CHR instance"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "continue"    -d "Resume a machine started with --frozen"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "stop"        -d "Power cut instance(s)"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
@@ -528,7 +531,7 @@ complete -c quickchr -n "__fish_seen_subcommand_from stop shutdown" \\
     -d "machine"
 
 # Machine name completions for commands that take any machine
-complete -c quickchr -n "__fish_seen_subcommand_from start remove rm clean console exec qga license disk snapshot snap status inspect env get set" \\
+complete -c quickchr -n "__fish_seen_subcommand_from start continue remove rm clean console exec qga license disk snapshot snap status inspect env get set" \\
     -a "(quickchr completions --machines 2>/dev/null)" \\
     -d "machine"
 

package/src/lib/lock.ts

@@ -61,6 +61,7 @@ export type LockOperation =
 	| "foreground"
 	| "stop"
 	| "shutdown"
+	| "continue"
 	| "clean"
 	| "remove"
 	| "device-mode"

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,
@@ -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);
 		}
 

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(). */