@tikoci/quickchr 0.4.6 → 0.4.8

package/src/lib/cache-api.ts

@@ -0,0 +1,146 @@
+/** Public cache operations for CI consumers and the quickchr CLI. */
+
+import { join } from "node:path";
+import { ensureCachedImage, isUsableCachedImage } from "./images.ts";
+import type { ProgressLogger } from "./log.ts";
+import { getCacheDir } from "./state.ts";
+import { ARCHES, CHANNELS, QuickCHRError, type Arch, type Channel } from "./types.ts";
+import { chrImageBasename, isValidVersion, resolveVersion } from "./versions.ts";
+
+export const CACHE_VERSION_UNRESOLVED = "unresolved";
+const CACHE_VERSION_MAX_LENGTH = 32;
+
+export interface CacheTargetOptions {
+	/** Resolve this RouterOS channel. Mutually exclusive with `version`. */
+	channel?: Channel;
+	/** Use this concrete RouterOS version without a network resolution request. */
+	version?: string;
+	/** Override the cache directory. Defaults to quickchr's platform-correct cache. */
+	cacheDir?: string;
+	/** CHR architecture. `auto` and omission select the Bun process architecture. */
+	arch?: Arch | "auto";
+}
+
+export interface CacheKeyResult {
+	dir: string;
+	/** Concrete RouterOS version, or `unresolved` when channel resolution is offline. */
+	version: string;
+	arch: Arch;
+}
+
+export interface CacheAddOptions extends CacheTargetOptions {
+	logger?: ProgressLogger;
+}
+
+export interface CacheAddResult extends CacheKeyResult {
+	path: string;
+	cacheHit: boolean;
+}
+
+export type CacheVersionResolver = (channel: Channel) => Promise<string>;
+
+function validateTarget(options: CacheTargetOptions): { channel?: Channel; version?: string } {
+	if (options.channel !== undefined && options.version !== undefined) {
+		throw new QuickCHRError("INVALID_VERSION", "Choose either a RouterOS channel or a concrete version, not both");
+	}
+	if (options.channel !== undefined && !(CHANNELS as readonly string[]).includes(options.channel)) {
+		throw new QuickCHRError(
+			"INVALID_VERSION",
+			`Invalid RouterOS channel "${options.channel}" — expected one of ${CHANNELS.join(", ")}`,
+		);
+	}
+	if (options.version !== undefined && !isValidVersion(options.version)) {
+		throw new QuickCHRError("INVALID_VERSION", `Invalid RouterOS version: ${options.version}`);
+	}
+	return { channel: options.channel, version: options.version };
+}
+
+async function concreteVersion(
+	options: CacheTargetOptions,
+	resolver: CacheVersionResolver,
+): Promise<{ channel?: Channel; version: string }> {
+	const target = validateTarget(options);
+	if (target.version !== undefined) return { version: target.version };
+	const channel = target.channel ?? "stable";
+	const version = await resolver(channel);
+	if (!isValidVersion(version)) {
+		throw new QuickCHRError(
+			"INVALID_VERSION",
+			`Unexpected version "${version}" resolved for channel "${channel}"`,
+		);
+	}
+	return { channel, version };
+}
+
+function concreteArch(arch: Arch | "auto" | undefined): Arch {
+	if (arch === undefined || arch === "auto") return process.arch === "arm64" ? "arm64" : "x86";
+	if (!(ARCHES as readonly string[]).includes(arch)) {
+		throw new QuickCHRError("INVALID_ARCH", `Invalid architecture "${arch}" — expected one of ${ARCHES.join(", ")}, auto`);
+	}
+	return arch;
+}
+
+/**
+ * Return quickchr's cache directory and the concrete version for a CI key.
+ *
+ * An explicit version is validated and returned without a network call. A
+ * channel resolution failure degrades to the stable `unresolved` sentinel so
+ * cache lookup cannot make an otherwise useful offline job fail.
+ */
+export async function cacheKey(
+	options: CacheTargetOptions = {},
+	resolver: CacheVersionResolver = resolveVersion,
+): Promise<CacheKeyResult> {
+	const target = validateTarget(options);
+	const dir = options.cacheDir ?? getCacheDir();
+	const arch = concreteArch(options.arch);
+	if (target.version !== undefined) {
+		return {
+			dir,
+			version: target.version.length <= CACHE_VERSION_MAX_LENGTH ? target.version : CACHE_VERSION_UNRESOLVED,
+			arch,
+		};
+	}
+	try {
+		const resolved = await concreteVersion(options, resolver);
+		return {
+			dir,
+			version: resolved.version.length <= CACHE_VERSION_MAX_LENGTH ? resolved.version : CACHE_VERSION_UNRESOLVED,
+			arch,
+		};
+	} catch (error) {
+		if (error instanceof QuickCHRError && error.code === "DOWNLOAD_FAILED") {
+			return { dir, version: CACHE_VERSION_UNRESOLVED, arch };
+		}
+		throw error;
+	}
+}
+
+/** Resolve and cache one CHR image without creating or booting a machine. */
+export async function cacheAdd(
+	options: CacheAddOptions = {},
+	resolver: CacheVersionResolver = resolveVersion,
+): Promise<CacheAddResult> {
+	const resolved = await concreteVersion(options, resolver);
+	if (resolved.version.length > CACHE_VERSION_MAX_LENGTH) {
+		throw new QuickCHRError("INVALID_VERSION", `RouterOS version is too long: ${resolved.version}`);
+	}
+	const arch = concreteArch(options.arch);
+	const dir = options.cacheDir ?? getCacheDir();
+	const expectedPath = join(dir, `${chrImageBasename(resolved.version, arch)}.img`);
+	const cacheHit = await isUsableCachedImage(expectedPath);
+
+	try {
+		const path = await ensureCachedImage(resolved.version, arch, dir, options.logger);
+		return { dir, version: resolved.version, arch, path, cacheHit };
+	} catch (error) {
+		if (resolved.channel && error instanceof QuickCHRError) {
+			throw new QuickCHRError(
+				error.code,
+				`Failed to cache channel "${resolved.channel}" -> ${resolved.version} (${arch}): ${error.message}`,
+				error.installHint,
+			);
+		}
+		throw error;
+	}
+}

package/src/lib/channels.ts

@@ -15,6 +15,7 @@ import type { Arch, ChannelTcpEndpoint, QgaCommand } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
 import { qgaProbe, qgaRawCommand } from "./qga.ts";
 import { qgaKvmWarning } from "./platform.ts";
+import { newMonitorPhaseTimings, summarizeMonitorPhases } from "./diagnostics.ts";
 
 /**
  * Resolve the IPC path for a QEMU channel (monitor, serial, qga).
@@ -87,9 +88,19 @@ export async function monitorCommand(
 	const endpoint = channelEndpoint(machineDir, "monitor", portBase);
 
 	return new Promise((resolve, reject) => {
+		// Per-phase timings so a timeout says *where* the round-trip stalled rather
+		// than just that it did (#80). Only read on the timeout path — a successful
+		// command pays nothing but a few Date.now() calls.
+		const started = Date.now();
+		const phases = newMonitorPhaseTimings();
+		const since = () => Date.now() - started;
+
 		const timeout = setTimeout(() => {
 			socket.destroy();
-			reject(new QuickCHRError("BOOT_TIMEOUT", "Monitor command timed out"));
+			reject(new QuickCHRError(
+				"BOOT_TIMEOUT",
+				`Monitor command timed out after ${timeoutMs}ms: "${command}" — ${summarizeMonitorPhases(phases)}`,
+			));
 		}, timeoutMs);
 
 		let buffer = "";
@@ -99,13 +110,20 @@ export async function monitorCommand(
 			? connect({ path: endpoint })
 			: connect(endpoint.port, endpoint.host);
 
+		socket.on("connect", () => { phases.connectedAtMs = since(); });
+
 		socket.on("data", (data) => {
+			phases.bytesReceived += data.length;
+			phases.firstByteAtMs ??= since();
+			if (sentCommand) phases.responseFirstByteAtMs ??= since();
 			buffer += data.toString();
 			// Wait for the (qemu) prompt before sending command
 			if (!sentCommand && buffer.includes("(qemu)")) {
 				sentCommand = true;
+				phases.promptAtMs = since();
 				buffer = "";
 				socket.write(command + "\n");
+				phases.commandWrittenAtMs = since();
 			} else if (sentCommand && buffer.includes("(qemu)")) {
 				// Got response — strip the prompt, the command echo, and ANSI noise
 				clearTimeout(timeout);
@@ -122,7 +140,10 @@ export async function monitorCommand(
 			if (sentCommand) {
 				resolve(cleanMonitorResponse(buffer.replace(/\(qemu\)\s*/g, "")));
 			} else {
-				reject(new QuickCHRError("MACHINE_STOPPED", "Monitor socket closed before command could be sent"));
+				reject(new QuickCHRError(
+					"MACHINE_STOPPED",
+					`Monitor socket closed before command could be sent — ${summarizeMonitorPhases(phases)}`,
+				));
 			}
 		});
 

package/src/lib/completions.ts

@@ -328,7 +328,7 @@ _quickchr() {
         cword=${D}COMP_CWORD
     }
 
-    local commands="add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor settings setup completions version help"
+    local commands="add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help"
 
     if [[ ${D}cword -eq 1 ]]; then
         COMPREPLY=( $(compgen -W "${D}commands" -- "${D}cur") )
@@ -352,6 +352,10 @@ _quickchr() {
             local opts="--install --uninstall --status --dry-run --shell"
             COMPREPLY=( $(compgen -W "${D}opts" -- "${D}cur") )
             ;;
+        cache)
+            local opts="add key list prune clear"
+            COMPREPLY=( $(compgen -W "${D}opts" -- "${D}cur") )
+            ;;
         help)
             COMPREPLY=( $(compgen -W "${D}commands" -- "${D}cur") )
             ;;
@@ -401,6 +405,7 @@ _quickchr() {
                 'snap:Manage snapshots (alias)'
                 'networks:Network discovery and socket management'
                 'net:Network discovery (alias)'
+                'cache:Prefetch and manage downloaded CHR images'
                 'doctor:Check prerequisites'
                 'settings:Manage global quickchr settings'
                 'setup:Interactive setup wizard'
@@ -434,8 +439,12 @@ _quickchr() {
                     )
                     _describe 'option' opts
                     ;;
+                cache)
+                    local subcommands=(add key list prune clear)
+                    _describe 'cache subcommand' subcommands
+                    ;;
                 help)
-                    local commands=(add start stop list status inspect env remove clean console exec qga license disk snapshot networks doctor settings setup completions version)
+                    local commands=(add start stop list status inspect env remove clean console exec qga license disk snapshot networks cache doctor settings setup completions version)
                     _describe 'command' commands
                     ;;
             esac
@@ -451,7 +460,7 @@ function generateFishCompletion(): string {
 	return `# quickchr fish completion
 # Generated by quickchr. Fish auto-loads files from ~/.config/fish/completions/.
 
-set -l quickchr_commands add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor settings setup completions version help
+set -l quickchr_commands add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help
 
 # Disable file completions globally for quickchr
 complete -c quickchr -f
@@ -489,6 +498,8 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "snapshot snap" -d "Manage snapshots"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "networks net" -d "Network discovery and socket management"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "cache"       -d "Prefetch and manage downloaded CHR images"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "doctor"      -d "Check prerequisites"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
@@ -518,5 +529,8 @@ complete -c quickchr -n "__fish_seen_subcommand_from completions" -l uninstall -
 complete -c quickchr -n "__fish_seen_subcommand_from completions" -l status    -d "Show install status"
 complete -c quickchr -n "__fish_seen_subcommand_from completions" -l dry-run   -d "Show what would happen"
 complete -c quickchr -n "__fish_seen_subcommand_from completions" -l shell     -d "Specify shell" -a "bash zsh fish"
+
+# cache subcommands
+complete -c quickchr -n "__fish_seen_subcommand_from cache" -a "add key list prune clear" -d "cache subcommand"
 `;
 }

package/src/lib/console.ts

@@ -27,6 +27,31 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 /** Interval for polling the buffer in waitFor(). */
 const POLL_INTERVAL_MS = 250;
 
+/**
+ * What one *fresh* serial login costs, for callers that must budget for it.
+ *
+ * A login is not a round-trip — it is dominated by RouterOS, not by us.
+ * Measured 2026-07-31 on 7.23.2 / x86 / HVF with a raw socket and timestamped
+ * receives (tikoci/quickchr#69, bite B10 of #110):
+ *
+ *   banner → `Login:`              10–25 ms
+ *   username → `Password:`         54–56 ms
+ *   password → license `[Y/n]:`    **10,184 ms**   ← the whole cost
+ *   full fresh `consoleExec()`     11,364 / 11,360 ms
+ *   `consoleExec()` on an already-open session   306 ms
+ *
+ * So a budget sized on the ~0.3 s round-trip figure is ~40× short of what the
+ * first call needs, and a caller that divides such a budget across credential
+ * candidates can never complete even one. That is exactly what made
+ * `captureGuestSnapshot()` report `consoleReachable: false` against provably
+ * healthy guests. Anything that logs in must budget from this constant, not
+ * from the round-trip cost.
+ *
+ * 15 s is the measured 11.4 s plus ~30% margin; TCG and cross-arch guests are
+ * slower still, which is why callers stack it rather than treat it as a cap.
+ */
+export const CONSOLE_LOGIN_COST_MS = 15_000;
+
 /** Pre-prompt pattern: the "] > " suffix is version-proof since it
  *  covers [admin@MikroTik] > , [admin@CHR] > , and any custom identity. */
 const PROMPT_PATTERN = "] > ";
@@ -120,50 +145,130 @@ async function waitFor(
 }
 
 /**
- * Wait for the LAST occurrence of `pattern` at or after `searchFrom` in the
- * buffer, determined by buffer stability.
+ * Ceiling on the quiet period the fallback prompt terminator waits for.
+ *
+ * This is no longer the normal way a command reply ends — {@link makeSentinel}
+ * is — so it is sized for safety rather than speed, and does not need to scale
+ * with the accelerator. The old flat 150 ms *was* the normal path, and that is
+ * exactly what let a prompt **redraw** terminate a slow large reply (#109): the
+ * two biggest guest-snapshot queries came back empty on a loaded TCG guest while
+ * every small one succeeded.
+ */
+const FALLBACK_PROMPT_STABLE_MS = 2_000;
+
+/** Floor, so a very small `timeoutMs` cannot reduce the window to nothing. */
+const MIN_PROMPT_STABLE_MS = 250;
+
+/**
+ * The quiet period to require before the fallback prompt may terminate a reply.
+ *
+ * Derived from the caller's budget rather than fixed: a caller passing less than
+ * ~2 s would otherwise never reach the fallback at all, and an unframed but
+ * *complete* reply would surface as a `BOOT_TIMEOUT` instead of `framed: false`.
+ * A small fraction leaves the rest of the budget for the reply itself. The
+ * window is only a secondary guard now — {@link isTrailingPrompt} already
+ * rejects a redraw structurally, whatever the timing.
+ */
+function promptStableWindow(timeoutMs: number): number {
+	return Math.min(FALLBACK_PROMPT_STABLE_MS, Math.max(MIN_PROMPT_STABLE_MS, Math.floor(timeoutMs / 8)));
+}
+
+/** True when `pattern` at `idx` is the last meaningful thing in the buffer.
+ *
+ * The redraw that broke #109 is "prompt + repainted command", so the redraw
+ * prompt always has the command text after it. Requiring the prompt to sit at
+ * the end of the buffer therefore rejects a redraw outright, independently of
+ * any timing window. Trailing ANSI and whitespace are ignored — RouterOS paints
+ * the prompt with color codes and terminal queries around it. */
+function isTrailingPrompt(buffer: string, idx: number, pattern: string): boolean {
+	return stripAnsi(buffer.slice(idx + pattern.length)).trim() === "";
+}
+
+/** How a command's reply ended. */
+type ReplyEnd =
+	/** The sentinel arrived — the reply is complete by construction. */
+	| { kind: "sentinel"; index: number }
+	/** No sentinel; a trailing, stable prompt terminated it instead. */
+	| { kind: "prompt"; index: number };
+
+/**
+ * Build the end-of-reply sentinel.
+ *
+ * The marker is assembled **in the guest** from three string literals, so the
+ * echoed command line contains the expression but never the contiguous marker
+ * text. That is what makes "the marker appeared" mean "the payload is complete"
+ * rather than "the command was echoed".
+ *
+ * It is sent as a **separate console line**, not chained with `;`. Measured on
+ * 7.21.5: `/bogus print; :put ("QC" . "END" . "e1")` prints the syntax error and
+ * **never runs the second statement**, and the same holds for a runtime error
+ * (`/ip/address add address=nonsense; …`). A `;` chain would therefore lose the
+ * terminator on exactly the replies that carry an error message. Two `\r`-
+ * terminated lines are two separate console inputs, so the second one still runs.
+ */
+function makeSentinel(): { command: string; marker: string; nonce: string } {
+	const nonce = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+	return {
+		command: `:put ("QCHR" . "${nonce}" . "END")`,
+		marker: `QCHR${nonce}END`,
+		nonce,
+	};
+}
+
+/**
+ * Wait for a command's reply to end — by sentinel, or failing that by a prompt
+ * that is both trailing and stable.
+ *
+ * Both terminators are watched in **one** loop on purpose. Waiting out the
+ * sentinel first and only then starting a prompt wait would spend the entire
+ * budget before the fallback got a chance, turning every unframed reply into a
+ * timeout instead of a slower success.
  *
- * RouterOS's VT100 terminal redraws the prompt+command line during execution,
- * so the first "] > " after the command is just the redraw, not the output prompt.
- * We wait until no new data arrives for `stableMs` milliseconds, then return
- * the position of the LAST occurrence of `pattern`.
+ * Returns null if neither terminator arrives in time.
  */
-async function waitForFinalPrompt(
+async function waitForReplyEnd(
 	session: ConsoleSessionState,
+	marker: string,
 	pattern: string,
 	searchFrom: number,
 	timeoutMs: number,
-	stableMs = 150,
-): Promise<number> {
+	stableMs = promptStableWindow(timeoutMs),
+): Promise<ReplyEnd | null> {
 	const FAST_POLL = 50;
 	const deadline = Date.now() + timeoutMs;
 	let lastGrowthAt = Date.now();
 	let lastLen = session.buffer.length;
-	let lastPromptAt = -1;
 
-	while (Date.now() < deadline) {
+	const trailingPrompt = (): number => {
+		const candidate = session.buffer.lastIndexOf(pattern);
+		if (candidate < searchFrom) return -1;
+		return isTrailingPrompt(session.buffer, candidate, pattern) ? candidate : -1;
+	};
+
+	for (;;) {
+		const sentinelAt = session.buffer.indexOf(marker, searchFrom);
+		if (sentinelAt >= 0) {
+			session.matchOffset = sentinelAt + marker.length;
+			return { kind: "sentinel", index: sentinelAt };
+		}
+
 		const currentLen = session.buffer.length;
 		if (currentLen > lastLen) {
 			lastLen = currentLen;
 			lastGrowthAt = Date.now();
-			const candidate = session.buffer.lastIndexOf(pattern);
-			if (candidate >= searchFrom) lastPromptAt = candidate;
-		}
-
-		if (lastPromptAt >= 0 && Date.now() - lastGrowthAt >= stableMs) {
-			session.matchOffset = lastPromptAt + pattern.length;
-			return lastPromptAt;
 		}
 
-		if (session.streamDone) {
-			if (lastPromptAt >= 0)
-				session.matchOffset = lastPromptAt + pattern.length;
-			return lastPromptAt;
+		const promptAt = trailingPrompt();
+		const quiet = Date.now() - lastGrowthAt >= stableMs;
+		if (promptAt >= 0 && (quiet || session.streamDone)) {
+			session.matchOffset = promptAt + pattern.length;
+			return { kind: "prompt", index: promptAt };
 		}
+		if (session.streamDone) return null;
+		if (Date.now() >= deadline) return null;
 
 		await Bun.sleep(FAST_POLL);
 	}
-	return -1;
 }
 
 /**
@@ -315,12 +420,70 @@ async function handlePostLogin(
 	return false;
 }
 
+/**
+ * Reduce the raw post-command console text to just the command's output.
+ *
+ * Measured shape of a RouterOS 7.21.5 serial reply (x86/HVF, QEMU 11.0.3):
+ *
+ * ```text
+ * <cmd>\r[admin@MikroTik] > <cmd>\r\n   echo — ONE physical line, bare-\r redraws
+ * \r<output>\r\n                        output, wrapped at the terminal width
+ * \r\r\r\r[admin@MikroTik] >     \r[admin@MikroTik] > <sentinel echo>\r\n
+ * \rQCHR…END\r\n                        the sentinel; the caller cuts before it
+ * ```
+ *
+ * Two structural rules do the work, and neither relies on matching the command
+ * text throughout — a long command is **horizontally scrolled** in the redraw
+ * (`<ss=nonsense; :put (…)`), so its opening characters are not present there:
+ *
+ *  - the sentinel echo carries this call's `nonce`, and shares a physical line
+ *    with the prompt redraw ahead of it, so dropping nonce-bearing lines removes
+ *    both at once;
+ *  - the command echo is the first physical line, and is dropped only when it
+ *    actually looks like one (it carries a prompt redraw, or starts with the
+ *    command) — so a reply with no echo cannot lose its first output line.
+ */
+export function extractOutput(raw: string, command: string, nonce?: string): string {
+	const lines = stripAnsi(raw)
+		.split(/\r?\n/)
+		.filter((l) => nonce === undefined || !l.includes(nonce));
+
+	const cmdPrefix = command.trim().slice(0, 24);
+	const first = lines[0];
+	let startIdx =
+		first !== undefined &&
+		(first.includes(PROMPT_PATTERN) || (cmdPrefix !== "" && first.trimStart().startsWith(cmdPrefix)))
+			? 1
+			: 0;
+	while (startIdx < lines.length && (lines[startIdx] ?? "").trim() === "") startIdx++;
+
+	// Trailing prompt fragments and blank lines are the redraw after the reply.
+	let endIdx = lines.length;
+	for (let i = lines.length - 1; i >= startIdx; i--) {
+		const trimmed = (lines[i] ?? "").trim();
+		if (trimmed === "" || trimmed.endsWith(PROMPT_PATTERN.trim())) endIdx = i;
+		else break;
+	}
+
+	return lines.slice(startIdx, endIdx).join("\n").trim();
+}
+
+/** Result of one console command.
+ *
+ * `framed` says the reply was delimited by the end-of-reply sentinel — i.e. the
+ * reader saw the whole reply. When it is false the reply was terminated by the
+ * fallback prompt heuristic instead, so an empty `output` means "could not frame
+ * the reply", not "the guest printed nothing" (#109). */
+export interface ConsoleExecResult {
+	output: string;
+	framed: boolean;
+}
+
 /**
  * Execute a RouterOS CLI command over the serial console.
  *
- * Connects to serial socket, ensures the session is logged in,
- * sends the command, and captures output between the command echo
- * and the next prompt.
+ * Connects to serial socket, ensures the session is logged in, sends the command
+ * followed by an end-of-reply sentinel, and captures the output between them.
  *
  * @param machineDir  Machine directory containing serial.sock
  * @param command     RouterOS CLI command to execute
@@ -335,7 +498,7 @@ export async function consoleExec(
 	password: string = "",
 	timeoutMs: number = DEFAULT_TIMEOUT_MS,
 	portBase?: number,
-): Promise<{ output: string }> {
+): Promise<ConsoleExecResult> {
 	const session = openSession(machineDir, portBase);
 
 	try {
@@ -367,62 +530,30 @@ export async function consoleExec(
 		// pre-buffered "] > " from ANSI codes or OSC title sequences RouterOS emits.
 		session.matchOffset = Math.max(session.matchOffset, preCommandOffset);
 
-		// Send command
-		write(session, `${command}\r`);
+		// Send the command and the end-of-reply sentinel as two console lines in one
+		// write. The sentinel is what terminates the reply; the prompt is only a
+		// fallback (see makeSentinel / waitForReplyEnd).
+		const sentinel = makeSentinel();
+		write(session, `${command}\r${sentinel.command}\r`);
 
-		// Wait for the FINAL prompt after the command completes.
-		// RouterOS VT100 redraws the prompt+command line during execution, so the
-		// first "] > " is a redraw, not the output prompt. waitForFinalPrompt uses
-		// buffer stability (no new data for 150ms) to identify the last prompt.
-		const promptFound = await waitForFinalPrompt(session, PROMPT_PATTERN, preCommandOffset, timeoutMs);
-		if (promptFound < 0) {
+		const end = await waitForReplyEnd(session, sentinel.marker, PROMPT_PATTERN, preCommandOffset, timeoutMs);
+		if (end === null) {
 			throw new QuickCHRError(
 				"BOOT_TIMEOUT",
-				`Console exec: no prompt after command (timed out after ${timeoutMs}ms)`,
+				`Console exec: no end-of-reply sentinel and no prompt after command (timed out after ${timeoutMs}ms)`,
 			);
 		}
+		const framed = end.kind === "sentinel";
 
-		// Extract output: everything between our command and the next prompt.
-		// promptFound points at "] > " — back up to the newline before the prompt
-		// line so we don't include the "[admin@...] > " prefix in output.
-		const lastNewline = session.buffer.lastIndexOf("\n", promptFound);
-		const sliceEnd = lastNewline >= preCommandOffset ? lastNewline : promptFound;
-		const rawOutput = session.buffer.slice(preCommandOffset, sliceEnd);
-
-		// Clean up: strip ANSI, strip the command echo line, trim
-		const cleaned = stripAnsi(rawOutput);
-		const lines = cleaned.split(/\r?\n/);
-
-		// First non-empty line(s) are the command echo — skip them.
-		// The echo repeats back what we typed.
-		let startIdx = 0;
-		for (let i = 0; i < lines.length; i++) {
-			const line = lines[i];
-			if (!line) continue;
-			const trimmed = line.trim();
-			// Skip echo lines that contain our command text
-			if (trimmed.includes(command.trim()) || trimmed === "") {
-				startIdx = i + 1;
-			} else {
-				break;
-			}
-		}
+		// Cut back to the newline that starts the terminator's own line, so neither
+		// the marker nor the "[admin@…] > " prefix lands in the output.
+		const lineStart = session.buffer.lastIndexOf("\n", end.index);
+		const sliceEnd = lineStart >= preCommandOffset ? lineStart : end.index;
 
-		// Also strip trailing prompt fragments and empty lines
-		let endIdx = lines.length;
-		for (let i = lines.length - 1; i >= startIdx; i--) {
-			const line = lines[i];
-			if (!line) continue;
-			const trimmed = line.trim();
-			if (trimmed === "" || trimmed.endsWith(PROMPT_PATTERN.trim())) {
-				endIdx = i;
-			} else {
-				break;
-			}
-		}
+		const rawOutput = session.buffer.slice(preCommandOffset, sliceEnd);
 
-		const output = lines.slice(startIdx, endIdx).join("\n").trim();
-		return { output };
+		const output = extractOutput(rawOutput, command, sentinel.nonce);
+		return { output, framed };
 	} finally {
 		session.socket.destroy();
 	}