@tikoci/quickchr 0.4.8 → 0.5.0

package/src/cli/wizard.ts

@@ -81,6 +81,11 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 				if (!/^\d+\.\d+(\.\d+)?(beta\d+|rc\d+)?$/.test(v)) {
 					return "Invalid version format";
 				}
+				// RouterOS 6 is a CLI-only boot target (#182) — the wizard offers
+				// provisioning at every step, none of which 6.x can take.
+				if (/^6\./.test(v)) {
+					return "RouterOS 6 is boot-only and not offered here — use: quickchr add --version <6.x> --arch x86";
+				}
 			},
 		});
 		if (clack.isCancel(ver)) { clack.cancel("Cancelled."); process.exit(0); }
@@ -557,7 +562,8 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 	const background = await clack.select({
 		message: "Run mode:",
 		options: [
-			{ value: true, label: "Background", hint: "returns immediately" },
+			// Not "returns immediately": a background start waits for RouterOS to be ready (#159).
+			{ value: true, label: "Background", hint: "console logged; returns when RouterOS is ready" },
 			{ value: false, label: "Foreground", hint: "serial console on stdio" },
 		],
 		initialValue: true,
@@ -566,8 +572,10 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 
 	// 11. Confirm
 	const opts: StartOptions = {
+		// The channel has already been resolved into `version` above; passing both reads
+		// to start() as a caller asking for two releases.
 		version,
-		channel,
+		channel: version ? undefined : channel,
 		arch,
 		name: name || undefined,
 		cpu: Number(cpu),

package/src/index.ts

@@ -64,6 +64,8 @@ export type {
 	ServiceEndpoint,
 	ServiceName,
 	SnapshotInfo,
+	ShutdownOptions,
+	ShutdownResult,
 	SshServiceEndpoint,
 	StartOptions,
 } from "./lib/types.ts";

package/src/lib/api-login.ts

@@ -0,0 +1,138 @@
+/**
+ * Native API (`/login` on guest port 8728) as a readiness signal.
+ *
+ * Built for RouterOS 6, which has no REST API, so the REST probe can never succeed
+ * against it — the field report behind #182 watched a 6.49 guest answer www, ssh and
+ * api from 15 s in, then get removed at 180 s for not answering `/rest`. It is written
+ * as a general alternative to the REST probe rather than a v6 special case: a 7.x
+ * guest with REST disabled is the same problem.
+ *
+ * Only the post-6.43 plain login is spoken (`=name=` + `=password=` in one sentence).
+ * Grounded against CHR 6.49.23 under HVF, 2026-10-21:
+ *
+ * - `admin` / empty password → `!done`, as one 7-byte reply.
+ * - wrong user or password → `!trap =message=invalid user name or password (6)`
+ *   followed by `!done`, in the same read.
+ *
+ * Either answer means the API service is up, the way a REST 401 does — the probe is a
+ * readiness check, not a credential check.
+ */
+
+import { connect } from "node:net";
+
+/** Encode one API word length (RouterOS API "length" prefix, 1–5 bytes). */
+export function encodeApiLength(length: number): Uint8Array {
+	if (length < 0x80) return Uint8Array.of(length);
+	if (length < 0x4000) return Uint8Array.of((length >> 8) | 0x80, length & 0xff);
+	if (length < 0x200000) return Uint8Array.of((length >> 16) | 0xc0, (length >> 8) & 0xff, length & 0xff);
+	if (length < 0x10000000) {
+		return Uint8Array.of((length >>> 24) | 0xe0, (length >> 16) & 0xff, (length >> 8) & 0xff, length & 0xff);
+	}
+	return Uint8Array.of(0xf0, (length >>> 24) & 0xff, (length >> 16) & 0xff, (length >> 8) & 0xff, length & 0xff);
+}
+
+/** A sentence is its words, each length-prefixed, then a zero-length word. */
+export function encodeApiSentence(words: string[]): Uint8Array {
+	const encoder = new TextEncoder();
+	const parts: Uint8Array[] = [];
+	for (const word of words) {
+		const bytes = encoder.encode(word);
+		parts.push(encodeApiLength(bytes.length), bytes);
+	}
+	parts.push(Uint8Array.of(0));
+	const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+}
+
+/** Decode a length prefix at `offset`. `null` when the buffer ends inside it. */
+function decodeApiLength(buf: Uint8Array, offset: number): { length: number; size: number } | null {
+	const first = buf[offset];
+	if (first === undefined) return null;
+	const size = (first & 0x80) === 0 ? 1
+		: (first & 0xc0) === 0x80 ? 2
+		: (first & 0xe0) === 0xc0 ? 3
+		: (first & 0xf0) === 0xe0 ? 4
+		: 5;
+	if (offset + size > buf.length) return null;
+	let length = size === 5 ? 0 : first & (0xff >> size);
+	for (let i = 1; i < size; i++) length = length * 256 + (buf[offset + i] ?? 0);
+	return { length, size };
+}
+
+/** Every complete sentence in `buf`; a trailing partial sentence is left out. */
+export function parseApiSentences(buf: Uint8Array): string[][] {
+	const decoder = new TextDecoder();
+	const sentences: string[][] = [];
+	let words: string[] = [];
+	let offset = 0;
+	while (offset < buf.length) {
+		const prefix = decodeApiLength(buf, offset);
+		if (!prefix || offset + prefix.size + prefix.length > buf.length) break;
+		offset += prefix.size;
+		if (prefix.length === 0) {
+			sentences.push(words);
+			words = [];
+			continue;
+		}
+		words.push(decoder.decode(buf.subarray(offset, offset + prefix.length)));
+		offset += prefix.length;
+	}
+	return sentences;
+}
+
+export type ApiLoginResult =
+	/** `!done` with no `!trap` — logged in. */
+	| { outcome: "done" }
+	/** `!trap` then `!done` — the service answered and refused the credentials. */
+	| { outcome: "trap"; message: string }
+	/** `!fatal` — the service answered and closed the session (e.g. too many sessions). */
+	| { outcome: "fatal"; message: string };
+
+/** What the reply sentences say, once a `!done` or `!fatal` has arrived. `null` while
+ *  the login is still unanswered. */
+export function classifyLoginReply(sentences: string[][]): ApiLoginResult | null {
+	const messageOf = (sentence: string[]) =>
+		sentence.find((w) => w.startsWith("=message="))?.slice("=message=".length) ?? sentence.slice(1).join(" ");
+	const fatal = sentences.find((s) => s[0] === "!fatal");
+	if (fatal) return { outcome: "fatal", message: messageOf(fatal) };
+	if (!sentences.some((s) => s[0] === "!done")) return null;
+	const trap = sentences.find((s) => s[0] === "!trap");
+	return trap ? { outcome: "trap", message: messageOf(trap) } : { outcome: "done" };
+}
+
+/** One `/login` round trip on `127.0.0.1:<port>`. Rejects on a socket error, on a close
+ *  before the reply completes ("closed before reply"), and on the deadline
+ *  ("apiLogin timeout") — the shapes `classifyProbeError()` sorts into outcomes. */
+export function apiLogin(port: number, user: string, password: string, timeoutMs = 3000): Promise<ApiLoginResult> {
+	return new Promise((resolve, reject) => {
+		const socket = connect(port, "127.0.0.1");
+		let received = new Uint8Array(0);
+		let settled = false;
+		const finish = (fn: () => void) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			socket.destroy();
+			fn();
+		};
+		const timer = setTimeout(() => finish(() => reject(new Error("apiLogin timeout"))), timeoutMs);
+		socket.on("connect", () => {
+			socket.write(encodeApiSentence(["/login", `=name=${user}`, `=password=${password}`]));
+		});
+		socket.on("data", (chunk: Uint8Array) => {
+			const next = new Uint8Array(received.length + chunk.length);
+			next.set(received);
+			next.set(chunk, received.length);
+			received = next;
+			const result = classifyLoginReply(parseApiSentences(received));
+			if (result) finish(() => resolve(result));
+		});
+		socket.on("error", (err) => finish(() => reject(err)));
+		socket.on("close", () => finish(() => reject(new Error("closed before reply"))));
+	});
+}

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 cache doctor settings setup completions version help"
+    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"
 
     if [[ ${D}cword -eq 1 ]]; then
         COMPREPLY=( $(compgen -W "${D}commands" -- "${D}cur") )
@@ -337,12 +337,12 @@ _quickchr() {
 
     local cmd="${D}{words[1]}"
     case "${D}cmd" in
-        start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env)
+        start|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") )
             ;;
-        stop)
+        stop|shutdown)
             local machines
             machines=$(quickchr completions --running 2>/dev/null)
             [[ -z "${D}machines" ]] && machines=$(quickchr completions --machines 2>/dev/null)
@@ -387,12 +387,15 @@ _quickchr() {
             local commands=(
                 'add:Create a new CHR machine (without starting)'
                 'start:Start or restart a CHR instance'
-                'stop:Stop instance(s)'
+                'stop:Power cut instance(s)'
+                'shutdown:Request guest shutdown'
                 'list:List all instances'
                 'ls:List all instances (alias)'
                 'status:Detailed status'
                 'inspect:Print running machine descriptor'
                 'env:Print subprocess environment'
+                'get:Show live machine config (license, device-mode, admin)'
+                'set:Change a booted machine (license, device-mode)'
                 'remove:Remove instance(s) and disk'
                 'rm:Remove instance(s) (alias)'
                 'clean:Reset instance disk to fresh image'
@@ -418,12 +421,12 @@ _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)
+                start|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
                     ;;
-                stop)
+                stop|shutdown)
                     local machines
                     machines=(${D}{(f)"${D}(quickchr completions --running 2>/dev/null)"})
                     (( ${D}{#machines} == 0 )) && machines=(${D}{(f)"${D}(quickchr completions --machines 2>/dev/null)"})
@@ -444,7 +447,7 @@ _quickchr() {
                     _describe 'cache subcommand' subcommands
                     ;;
                 help)
-                    local commands=(add start stop list status inspect env remove clean console exec qga license disk snapshot networks cache doctor settings setup completions version)
+                    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)
                     _describe 'command' commands
                     ;;
             esac
@@ -460,7 +463,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 cache doctor settings setup completions version help
+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
 
 # Disable file completions globally for quickchr
 complete -c quickchr -f
@@ -471,7 +474,9 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
 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 "stop"        -d "Stop instance(s)"
+    -a "stop"        -d "Power cut instance(s)"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "shutdown"    -d "Request guest shutdown"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "list ls"     -d "List all instances"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
@@ -491,6 +496,10 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "qga"         -d "Guest agent command"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "get"         -d "Show live machine config (license, device-mode, admin)"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \
+    -a "set"         -d "Change a booted machine (license, device-mode)"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \
     -a "license"     -d "Apply/renew CHR trial license"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "disk"        -d "Show disk details"
@@ -514,12 +523,12 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "help"        -d "Show help"
 
 # Machine name completions for commands that take a running machine
-complete -c quickchr -n "__fish_seen_subcommand_from stop" \\
+complete -c quickchr -n "__fish_seen_subcommand_from stop shutdown" \\
     -a "(quickchr completions --running 2>/dev/null; or quickchr completions --machines 2>/dev/null)" \\
     -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" \\
+complete -c quickchr -n "__fish_seen_subcommand_from start 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/device-mode.ts

@@ -4,6 +4,7 @@
 
 import type { DeviceModeOptions } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
+import { shellQuote } from "./names.ts";
 import { restGet, restPost } from "./rest.ts";
 
 export const KNOWN_DEVICE_MODES = ["home", "advanced", "basic", "rose"] as const;
@@ -63,6 +64,26 @@ function normalizeFeatureList(list: string[] | undefined): string[] {
 	return [...new Set(values)];
 }
 
+/** Keys `/system/device-mode` reports that are not feature flags. `mode` is the
+ *  device-mode itself; the rest are status RouterOS keeps alongside it. */
+export const DEVICE_MODE_NON_FEATURE_KEYS: ReadonlySet<string> = new Set([
+	"mode",
+	"allowed-versions",
+	"attempt-count",
+	"flagged",
+	"flagging-enabled",
+]);
+
+/** Is this feature on, as RouterOS reports it?
+ *
+ *  RouterOS answers `/system/device-mode` with **strings**: `"container": "true"`, not
+ *  `true`. A reader that tests `value === true` therefore finds nothing enabled, ever —
+ *  which is what `quickchr get <name> device-mode` did, printing a bare mode and no
+ *  feature line however many were on. Normalize before deciding. */
+export function isDeviceModeFeatureEnabled(value: unknown): boolean {
+	return toYesNo(value) === "yes";
+}
+
 function toYesNo(value: unknown): string {
 	if (typeof value === "boolean") return value ? "yes" : "no";
 	if (typeof value === "number") return value > 0 ? "yes" : "no";
@@ -148,20 +169,61 @@ export function formatDeviceModeSelection(options: ResolvedDeviceModeOptions): s
 	return parts.join(" ");
 }
 
-/** Wait until the device-mode REST endpoint is reachable with default admin auth. */
-export async function waitForDeviceModeApi(httpPort: number, timeoutMs: number = 60_000): Promise<void> {
-	const auth = `Basic ${btoa("admin:")}`;
+/** Factory credentials — `admin` with no password, as a fresh CHR ships.
+ *
+ *  The right auth for device-mode during *first-boot* provisioning, where it runs
+ *  before any account has been created, and the wrong auth afterwards: a machine
+ *  provisioned with `--disable-admin` answers 401. Post-boot callers resolve the
+ *  machine's own credentials instead — see `applyDeviceMode`. */
+export const FACTORY_AUTH_HEADER = `Basic ${btoa("admin:")}`;
+
+/** Is this response body actually `/system/device-mode`, and not the post-boot race?
+ *
+ *  RouterOS can answer a non-resource endpoint with resource-shaped or otherwise wrong
+ *  data for a short window after boot — `provisioning.instructions.md` documents this
+ *  for exactly this endpoint, and `readDeviceMode()` carries a guard for it. A 2xx is
+ *  therefore not proof the endpoint is ready; a body with `mode` in it is. */
+function isDeviceModeBody(body: string): boolean {
+	let data: unknown;
+	try { data = JSON.parse(body); } catch { return false; }
+	const record = Array.isArray(data) ? data[0] : data;
+	if (!record || typeof record !== "object") return false;
+	const keys = record as Record<string, unknown>;
+	if ("board-name" in keys || "architecture-name" in keys) return false;
+	return "mode" in keys;
+}
+
+/** Wait until the device-mode REST endpoint is reachable **and answering with
+ *  device-mode data**.
+ *
+ *  Returning on a bare 2xx was a race the next line then paid for: `readDeviceMode()`
+ *  rejects a resource-shaped body outright, so a guest that came back mid-race failed
+ *  the whole operation instead of being waited out for one more second. This is the
+ *  poll-until-the-keys-are-there pattern `provisioning.instructions.md` prescribes for
+ *  every non-resource endpoint, applied where the waiting already happens.
+ *
+ *  `auth` defaults to factory admin, which is what a guest being provisioned for the
+ *  first time has. A machine past that point needs its own credentials passed in. */
+export async function waitForDeviceModeApi(
+	httpPort: number,
+	timeoutMs: number = 60_000,
+	auth: string = FACTORY_AUTH_HEADER,
+): Promise<void> {
 	const deadline = Date.now() + timeoutMs;
+	let lastBody = "";
 	while (Date.now() < deadline) {
 		try {
-			const { status } = await restGet(
+			const { status, body } = await restGet(
 				`http://127.0.0.1:${httpPort}/rest/system/device-mode`,
 				auth,
 				3000,
 			);
 
 			if (status >= 200 && status < 300) {
-				return;
+				if (isDeviceModeBody(body)) return;
+				// Answering, but not with device-mode yet — keep waiting rather than
+				// handing the caller a body it will throw on.
+				lastBody = body;
 			}
 
 			if (status === 401) {
@@ -176,7 +238,11 @@ export async function waitForDeviceModeApi(httpPort: number, timeoutMs: number =
 		await Bun.sleep(1000);
 	}
 
-	throw new QuickCHRError("BOOT_TIMEOUT", `Device-mode API did not become ready on port ${httpPort}`);
+	throw new QuickCHRError(
+		"BOOT_TIMEOUT",
+		`Device-mode API did not become ready on port ${httpPort}` +
+		(lastBody ? ` (last response was not device-mode data: ${lastBody.slice(0, 200)})` : ""),
+	);
 }
 
 /**
@@ -189,7 +255,11 @@ export async function waitForDeviceModeApi(httpPort: number, timeoutMs: number =
  * Uses restPost (node:http + agent:false) to bypass Bun's connection pool.
  * The 300s timeout is a safety limit — the caller is expected to kill QEMU well before then.
  */
-export function startDeviceModeUpdate(httpPort: number, options: ResolvedDeviceModeOptions): Promise<{ status: number; body: string }> {
+export function startDeviceModeUpdate(
+	httpPort: number,
+	options: ResolvedDeviceModeOptions,
+	auth: string = FACTORY_AUTH_HEADER,
+): Promise<{ status: number; body: string }> {
 	if (!shouldApplyDeviceMode(options)) {
 		return Promise.resolve({ status: 200, body: "" });
 	}
@@ -200,7 +270,6 @@ export function startDeviceModeUpdate(httpPort: number, options: ResolvedDeviceM
 		payload[name] = value;
 	}
 
-	const auth = `Basic ${btoa("admin:")}`;
 	return restPost(
 		`http://127.0.0.1:${httpPort}/rest/system/device-mode/update`,
 		auth,
@@ -209,8 +278,10 @@ export function startDeviceModeUpdate(httpPort: number, options: ResolvedDeviceM
 	);
 }
 
-export async function readDeviceMode(httpPort: number): Promise<Record<string, string>> {
-	const auth = `Basic ${btoa("admin:")}`;
+export async function readDeviceMode(
+	httpPort: number,
+	auth: string = FACTORY_AUTH_HEADER,
+): Promise<Record<string, string>> {
 	const { status, body } = await restGet(
 		`http://127.0.0.1:${httpPort}/rest/system/device-mode`,
 		auth,
@@ -281,3 +352,71 @@ export function verifyDeviceMode(
 		actual,
 	};
 }
+
+/** The `quickchr set` flags that would reproduce this selection, shell-quoted.
+ *
+ *  Rendered from the *resolved* options, not the raw ones, so the command it prints
+ *  is the command that was actually going to run — `mode: "auto"` comes out as the
+ *  `rose` it resolves to rather than as an alias the reader has to expand.
+ *
+ *  Quoted because `resolveDeviceModeOptions()` deliberately passes unknown modes and
+ *  features through for forward compatibility (it warns, RouterOS validates), so a
+ *  value with a space or a `;` in it reaches this function intact. Unquoted, the
+ *  advertised command would silently become a different command. Ordinary values are
+ *  returned unquoted, so the common case still reads like something a person typed. */
+export function formatDeviceModeFlags(options: ResolvedDeviceModeOptions): string {
+	if (options.skip) return "";
+	const parts: string[] = [];
+	if (options.mode) parts.push(`--device-mode ${shellQuote(options.mode)}`);
+	const enable = Object.entries(options.features).filter(([, v]) => v === "yes").map(([k]) => k);
+	const disable = Object.entries(options.features).filter(([, v]) => v === "no").map(([k]) => k);
+	if (enable.length > 0) parts.push(`--device-mode-enable ${shellQuote(enable.sort().join(","))}`);
+	if (disable.length > 0) parts.push(`--device-mode-disable ${shellQuote(disable.sort().join(","))}`);
+	return parts.join(" ");
+}
+
+/** What a device-mode update would change, read against the guest's current record.
+ *
+ *  Only the differences — a change that costs a power cycle should say which settings
+ *  it is buying, and `expected == actual` rows are noise. Empty means nothing would
+ *  move, which is the caller's cue that no power cycle is needed. */
+export function describeDeviceModeChange(
+	options: ResolvedDeviceModeOptions,
+	actual: Record<string, string>,
+): string[] {
+	// `verifyDeviceMode` stays the single judge of what counts as a mismatch — only the
+	// key is read back out of its message, and the values come from the maps it returns.
+	const { expected, mismatches } = verifyDeviceMode(options, actual);
+	const changed = new Set(mismatches.map((mismatch) => mismatch.split(":")[0]));
+	return Object.entries(expected)
+		.filter(([key]) => changed.has(key))
+		.map(([key, want]) => `${key}: ${actual[key] ?? "(unset)"} -> ${want}`);
+}
+
+/** Fold an applied device-mode selection into what `machine.json` already records.
+ *
+ *  `setDeviceMode()` used to overwrite `state.deviceMode` with the request, so
+ *  `set <name> --device-mode-enable container` on a machine provisioned with
+ *  `ipsec=yes` left the record claiming ipsec had never been asked for. The guest
+ *  still had it: device-mode updates are cumulative, and only the settings named in
+ *  a request move. The record has to be cumulative too, or it describes a machine
+ *  that does not exist — and `classifyProvisioningRequest()` reads it. */
+export function mergeDeviceModeOptions(
+	current: DeviceModeOptions | undefined,
+	applied: ResolvedDeviceModeOptions,
+): DeviceModeOptions {
+	if (applied.skip) return current ?? {};
+	const enable = new Set(normalizeFeatureList(current?.enable));
+	const disable = new Set(normalizeFeatureList(current?.disable));
+	for (const [feature, value] of Object.entries(applied.features)) {
+		// A feature only ever sits on one side: the newest instruction for it wins.
+		enable.delete(feature);
+		disable.delete(feature);
+		(value === "yes" ? enable : disable).add(feature);
+	}
+	return {
+		mode: applied.mode ?? current?.mode,
+		enable: enable.size > 0 ? [...enable].sort() : undefined,
+		disable: disable.size > 0 ? [...disable].sort() : undefined,
+	};
+}

package/src/lib/diagnostics.ts

@@ -54,18 +54,22 @@ export type BootProbeOutcome =
 	| "reset"
 	/** Connect or response exceeded the per-probe budget — socket hung. */
 	| "probe-timeout"
-	/** 401/403 — REST answered; auth layer is up. */
+	/** 401/403 from REST, or a login `!trap` from the native API — the service
+	 *  answered and refused the credentials; its auth layer is up. */
 	| "unauthorized"
 	/** 2xx but not the expected `board-name` singleton — REST still initializing. */
 	| "wrong-body"
 	/** Any other HTTP status. */
 	| "http-error"
-	/** 2xx with the expected body. */
+	/** 2xx with the expected body, or a native-API login `!done`. */
 	| "ready"
 	/** Anything unclassified — `detail` carries the raw text. */
 	| "other";
 
 export interface BootProbeStats {
+	/** Which readiness probe ran — REST by default, the native-API login for a guest
+	 *  without REST (#182). Absent means REST. */
+	kind?: "rest" | "api";
 	/** Total probe attempts made. */
 	attempts: number;
 	/** Attempt count per outcome. */
@@ -90,9 +94,11 @@ export function classifyProbeError(err: unknown): { outcome: BootProbeOutcome; d
 	const message = err instanceof Error ? err.message : String(err);
 	if (code === "ECONNREFUSED") return { outcome: "refused", detail: code };
 	if (code === "ECONNRESET" || code === "EPIPE") return { outcome: "reset", detail: code };
-	if (code === "ETIMEDOUT" || message.includes("restGet timeout")) {
+	if (code === "ETIMEDOUT" || message.includes("restGet timeout") || message.includes("apiLogin timeout")) {
 		return { outcome: "probe-timeout", detail: code ?? "probe deadline" };
 	}
+	// apiLogin(): slirp accepted, then the guest side closed before any reply.
+	if (message === "closed before reply") return { outcome: "reset", detail: message };
 	return { outcome: "other", detail: code ? `${code}: ${message}` : message };
 }
 
@@ -123,9 +129,10 @@ export function summarizeBootProbe(stats: BootProbeStats): string {
 		.sort((a, b) => b[1] - a[1])
 		.map(([k, v]) => `${k}=${v}`)
 		.join(" ");
+	const answer = stats.kind === "api" ? "API reply" : "HTTP response";
 	const reachedHttp = stats.firstHttpAtMs === null
-		? "forwarded port never produced an HTTP response"
-		: `first HTTP response at ${Math.round(stats.firstHttpAtMs / 1000)}s`;
+		? `forwarded port never produced an ${answer}`
+		: `first ${answer} at ${Math.round(stats.firstHttpAtMs / 1000)}s`;
 	const last = stats.last
 		? `last: ${stats.last.outcome}${stats.last.detail ? ` (${stats.last.detail})` : ""} at ${Math.round(stats.last.atMs / 1000)}s`
 		: "";
@@ -673,7 +680,7 @@ export async function captureBootFailure(ctx: BootFailureContext): Promise<BootF
 			lines.push(`Preceding credential transition: ${ctx.trigger.credentialTransition}`);
 		}
 	}
-	if (ctx.probe) lines.push(`REST probe: ${summarizeBootProbe(ctx.probe)}`);
+	if (ctx.probe) lines.push(`${ctx.probe.kind === "api" ? "API login" : "REST"} probe: ${summarizeBootProbe(ctx.probe)}`);
 	lines.push(`QEMU process: ${record.host.qemuProcess}`);
 	if (record.hostfwd) lines.push(`hostfwd 127.0.0.1:${record.hostfwd.port}: ${record.hostfwd.tcpConnect}`);
 	if (forwardProbe) lines.push(`slirp per-port: ${forwardProbe.summary}`);