@tikoci/centrs 0.1.6 → 0.1.7

package/src/devices.ts

@@ -1,4 +1,5 @@
-import { mkdir, open } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { link, mkdir, open, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import type {
@@ -79,6 +80,10 @@ export interface DevicesListItem {
 	user: string;
 	cdbRecordIndex: number;
 	source?: string;
+	/** `identity=` / `mac=` / `ip=` comment lookup keys — the names `<router>` resolves by (issue #378). */
+	identity?: string;
+	mac?: string;
+	ip?: string;
 	sources?: Record<string, SettingSource>;
 	/** GPS location, parsed from the `lat`/`lon`/`altitude`/`altitude-type` comment facts (issue #146). */
 	location?: DeviceLocation;
@@ -102,6 +107,7 @@ export interface DevicesGroupSummary {
 }
 
 export type DevicesCommand =
+	| "init"
 	| "list"
 	| "show"
 	| "groups"
@@ -223,22 +229,106 @@ function isAlreadyExistsError(cause: unknown): boolean {
 
 /**
  * Create an empty open CDB at `path` without clobbering an existing file.
- * Uses an exclusive-create open (`wx`) so a concurrent writer's CDB is never
- * overwritten; the caller treats EEXIST as "another process created it".
- * Mode `0o600` keeps the CDB (device credentials) unreadable by other local
- * users instead of falling back to the process umask default.
+ * The bytes are written to a private temp file first and then hard-linked
+ * into place: `link` fails with EEXIST instead of replacing, and `path` never
+ * exists half-written, so a concurrent creator that loses the race reads a
+ * complete CDB (#382 review). Returns false when `link` found a CDB already
+ * there (another process created it). Only `link`'s EEXIST means that: a
+ * recursive `mkdir` also reports EEXIST when a path component is a regular
+ * file. Mode `0o600` keeps the CDB (device credentials) unreadable by other
+ * local users instead of falling back to the process umask default.
  */
-async function createEmptyCdbNoClobber(path: string): Promise<void> {
+async function createEmptyCdbNoClobber(path: string): Promise<boolean> {
 	await mkdir(dirname(path), { recursive: true });
-	const handle = await open(path, "wx", 0o600);
+	const tempPath = `${path}.init.${randomUUID()}`;
+	const handle = await open(tempPath, "wx", 0o600);
 	try {
-		await handle.write(encodeOpenWinBoxCdb([]));
-		await handle.sync();
+		try {
+			await handle.chmod(0o600);
+			await handle.write(encodeOpenWinBoxCdb([]));
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+		await link(tempPath, path);
+		return true;
+	} catch (error) {
+		if (isAlreadyExistsError(error)) {
+			return false;
+		}
+		throw error;
 	} finally {
-		await handle.close();
+		await unlink(tempPath);
 	}
 }
 
+export interface DevicesInitData {
+	cdbFile: string;
+	/** False when a readable CDB was already there; nothing was written. */
+	created: boolean;
+	recordCount: number;
+}
+
+/**
+ * `devices init` (#376): create an empty open CDB at the resolved path, the
+ * explicit counterpart of the default path's first-run auto-create. Never
+ * clobbers: like `git init`, re-running on an existing, readable CDB succeeds
+ * with a `cdb/file-exists` warning and writes nothing, so a workspace bootstrap
+ * script can run it unconditionally. An existing file that does not load
+ * (not a CDB, or encrypted without a password) fails with the load error.
+ */
+export async function initCdb(
+	options: LoadCdbOptions,
+): Promise<CentrsSuccessEnvelope<DevicesInitData, DevicesOperationMeta>> {
+	const settings = resolveDevicesSettings(options);
+	const cdbFile = settings.cdbFile.value;
+	const existingResult = async () => {
+		const existing = await loadCdb(options);
+		return {
+			ok: true as const,
+			data: { cdbFile, created: false, recordCount: existing.entries.length },
+			warnings: [
+				...existing.warnings,
+				{
+					code: "cdb/file-exists",
+					message: `A CDB already exists at ${cdbFile} (${existing.entries.length} record(s)); nothing was written.`,
+				},
+			],
+			tips: [],
+			meta: devicesMeta("init", settings),
+		};
+	};
+	// Check first: an existing CDB in a read-only directory is still an
+	// idempotent success, although no temp file could be created beside it.
+	// A `false` from the create covers a creator that wins the race after this.
+	if (await Bun.file(cdbFile).exists()) {
+		return existingResult();
+	}
+	let created: boolean;
+	try {
+		created = await createEmptyCdbNoClobber(cdbFile);
+	} catch (cause) {
+		throw new CentrsError({
+			code: "cdb/create-failed",
+			summary: `Could not create a CDB at ${cdbFile}.`,
+			remediation:
+				"Check that the directory is writable, or pass --cdb-file PATH to a writable location.",
+			context: { cdbFile },
+			cause,
+		});
+	}
+	if (!created) {
+		return existingResult();
+	}
+	return {
+		ok: true,
+		data: { cdbFile, created: true, recordCount: 0 },
+		warnings: [],
+		tips: [],
+		meta: devicesMeta("init", settings),
+	};
+}
+
 export async function loadCdb(options: LoadCdbOptions): Promise<LoadedCdb> {
 	const settings = resolveDevicesSettings(options);
 	const warnings: DevicesWarning[] = [];
@@ -250,33 +340,33 @@ export async function loadCdb(options: LoadCdbOptions): Promise<LoadedCdb> {
 		// `devices`/identity commands work out of the box. An explicit missing
 		// path stays an error (typo protection).
 		if (settings.cdbFile.source.kind === "default") {
+			// `false` means another process won the race and created the CDB
+			// after our existence check; that file is authoritative, so fall
+			// through and read it instead of erroring.
+			let created: boolean;
 			try {
-				await createEmptyCdbNoClobber(settings.cdbFile.value);
+				created = await createEmptyCdbNoClobber(settings.cdbFile.value);
+			} catch (cause) {
+				throw new CentrsError({
+					code: "cdb/not-found",
+					summary: `CDB file not found and could not be created: ${settings.cdbFile.value}`,
+					remediation:
+						"Check directory permissions for ~/.config/tikoci, or pass --cdb-file PATH to a writable location.",
+					context: { cdbFile: settings.cdbFile.value },
+					cause,
+				});
+			}
+			if (created) {
 				warnings.push({
 					code: "cdb/created",
 					message: `No CDB found at the default path; created an empty CDB at ${settings.cdbFile.value}.`,
 				});
-			} catch (cause) {
-				// EEXIST means another process won the race and created the CDB
-				// between our existence check and the exclusive open — that file
-				// is authoritative; fall through and read it instead of erroring.
-				if (!isAlreadyExistsError(cause)) {
-					throw new CentrsError({
-						code: "cdb/not-found",
-						summary: `CDB file not found and could not be created: ${settings.cdbFile.value}`,
-						remediation:
-							"Check directory permissions for ~/.config/tikoci, or pass --cdb-file PATH to a writable location.",
-						context: { cdbFile: settings.cdbFile.value },
-						cause,
-					});
-				}
 			}
 		} else {
 			throw new CentrsError({
 				code: "cdb/not-found",
 				summary: `CDB file not found: ${settings.cdbFile.value}`,
-				remediation:
-					"Pass --cdb-file PATH, set CENTRS_CDB_FILE, or place a CDB at ~/.config/tikoci/winbox.cdb.",
+				remediation: `To start a new CDB there, run \`centrs devices init --cdb-file ${settings.cdbFile.value}\`. Otherwise check the path; an explicit --cdb-file or CENTRS_CDB_FILE is never created implicitly.`,
 				context: { cdbFile: settings.cdbFile.value },
 			});
 		}
@@ -752,6 +842,18 @@ function entryToListItem(
 			key: `record:${cdbRecordIndex}:source`,
 		};
 	}
+	for (const key of commentKvLookupKeys) {
+		const value = parsed.lookups[key];
+		// Same non-blank rule as `entryRouterKeys`: never advertise a key that
+		// does not resolve.
+		if (value !== undefined && value.trim().length > 0) {
+			item[key] = value;
+			sources[key] = {
+				kind: "comment-kv",
+				key: `record:${cdbRecordIndex}:${key}`,
+			};
+		}
+	}
 	const location = deviceLocation(parseRawCommentFacts(entry.comment));
 	if (location !== undefined) {
 		item.location = location;
@@ -1753,6 +1855,15 @@ function renderText(envelope: DevicesEnvelope<unknown>): string {
 	}
 
 	switch (envelope.meta.operation?.command) {
+		case "init": {
+			const data = envelope.data as DevicesInitData;
+			lines.push(
+				data.created
+					? `created ${data.cdbFile}`
+					: `exists ${data.cdbFile} (${data.recordCount} record(s))`,
+			);
+			break;
+		}
 		case "list":
 			renderListText(lines, envelope.data as readonly DevicesListItem[]);
 			break;
@@ -1828,12 +1939,15 @@ function renderListText(
 		lines.push("(no entries)");
 		return;
 	}
-	lines.push(["INDEX", "TARGET", "TYPE", "USER", "GROUP"].join("\t"));
+	lines.push(
+		["INDEX", "TARGET", "IDENTITY", "TYPE", "USER", "GROUP"].join("\t"),
+	);
 	for (const item of items) {
 		lines.push(
 			[
 				String(item.cdbRecordIndex),
 				item.target,
+				item.identity || "-",
 				item.recordTypeName,
 				item.user || "-",
 				item.group || "-",

package/src/execute-fanout.ts

@@ -15,7 +15,7 @@
  *   - A `--default` / `__default__` member is guarded from being dialed as the
  *     literal hostname `"__default__"` — it fails that one target deterministically
  *     with `target/unresolved`.
- *   - A **write-shaped** command (add/set/remove) is confirmed ONCE up front
+ *   - A **write-shaped** command is confirmed ONCE up front
  *     (`--yes`), never per target; without `--yes` the error names the blast radius
  *     (how many routers). Write-ness is target-independent (`canonicalizeExecuteCommand`).
  */

package/src/execute.ts

@@ -17,7 +17,7 @@ import {
 	isWriteShaped,
 } from "./core/execute-command.ts";
 import { inspectArgumentNames, pathTokens } from "./core/inspect.ts";
-import { mapRouterOsError } from "./core/routeros-errors.ts";
+import { mapRouterOsResultError } from "./core/routeros-errors.ts";
 import { routerOsStringLiteral } from "./core/routeros-string.ts";
 import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
@@ -892,7 +892,16 @@ async function runSyntaxGate(
 	resolved: ResolvedExecuteRequest,
 	backend: ProtocolAdapter,
 ): Promise<void> {
-	const script = `:put [:parse ${routerOsStringLiteral(resolved.command)}]`;
+	await validateRouterOsScript(resolved.command, backend, resolved.via.value);
+}
+
+/** Shared live `:parse` stage for every surface that carries a CLI string. */
+export async function validateRouterOsScript(
+	command: string,
+	backend: ProtocolAdapter,
+	via: RouterOsProtocol,
+): Promise<void> {
+	const script = `:put [:parse ${routerOsStringLiteral(command)}]`;
 	try {
 		// GH#230: `:parse` never throws (CHR 7.23.3). The diagnostic rides the
 		// success value's text — over REST/native the `ret` field (HTTP 200 /
@@ -901,7 +910,7 @@ async function runSyntaxGate(
 		// Read the return and classify it: one `:parse` covers syntax and the
 		// unknown-attribute (name-level) gate.
 		const result = await backend.execute({ path: "", command: "", script });
-		classifyParseResult(result.ret ?? "", resolved.command, resolved.via.value);
+		classifyParseResult(result.ret ?? "", command, via);
 	} catch (error) {
 		// The preflight is a syntax gate, but `backend.execute` also surfaces
 		// connection and authentication failures (login happens lazily here).
@@ -925,9 +934,9 @@ async function runSyntaxGate(
 			remediation:
 				"Fix the RouterOS CLI syntax, especially quotes and bracketed expressions, then retry.",
 			context: {
-				command: resolved.command,
+				command,
 				validationSource: ":put [:parse ...]",
-				via: resolved.via.value,
+				via,
 			},
 			...(position ? { position } : {}),
 			cause: error,
@@ -1298,52 +1307,14 @@ function routerOsFailureFromResult(
 	result: ProtocolExecuteResult,
 	via: RouterOsProtocol,
 ): CentrsError | undefined {
-	const candidates = [
-		result.ret,
-		...result.records.flatMap((record) => [
-			record["detail"],
-			record["message"],
-			record["failure"],
-			record["error"],
-			record["ret"],
-		]),
-	].filter((value): value is string => typeof value === "string");
-	const failure = candidates.find((candidate) =>
-		isRouterOsFailureString(candidate),
-	);
-	return failure
-		? mapRouterOsError(failure, {
-				transport:
-					via === "rest-api" || via === "mac-telnet" || via === "ssh"
-						? via
-						: "native-api",
-				context: { via },
-			})
-		: undefined;
-}
-
-function isRouterOsFailureString(value: string): boolean {
-	const trimmed = value.trim();
-	// REST/native fault strings (unchanged).
-	if (
-		/^(failure:|error:)|unknown parameter|invalid value|session closed|\(:error; line \d+\)/i.test(
-			trimmed,
-		)
-	) {
-		return true;
-	}
-	// Console (mac-telnet) error forms. `ret` here is ordinary stdout (every
-	// mac-telnet command and REST `/execute`), so anchor to the grounded RouterOS
-	// error *shapes* — the `(line N column M)` source location for parse rejections
-	// — rather than bare phrases, so `:put "syntax error"` is not misread as a
-	// failure.
-	return (
-		/(?:^|\n)\s*(?:bad parameter \S+|syntax error)\b[^\n]*\(line \d+ column \d+\)/i.test(
-			trimmed,
-		) ||
-		/(?:^|\n)\s*bad command name\b/i.test(trimmed) ||
-		/(?:^|\n)\s*expected end of command\b/i.test(trimmed)
-	);
+	if (typeof result.ret !== "string") return undefined;
+	return mapRouterOsResultError(result.ret, {
+		transport:
+			via === "rest-api" || via === "mac-telnet" || via === "ssh"
+				? via
+				: "native-api",
+		context: { via },
+	});
 }
 
 function applyMaxResultsBudget(

package/src/explain/catalog.ts

@@ -9,7 +9,7 @@
  * Union of two first-order sources (#228):
  *
  * 1. MikroTik's published CLI Reference (`https://manual.mikrotik.com/docs/cli-reference/`),
- *    1,053 pages, 1,060 entries — first-order about the definition
+ *    1,055 pages, 1,062 entries — first-order about the definition
  *    structs and their build-time gates. Since #285 every page is a leaf whose
  *    slug is the CLI path, so no spelling has to be rewritten to be looked up.
  * 2. 6 pinned restraml `/console/inspect` trees
@@ -19,14 +19,14 @@
  * | ---- | ---- | -------- | ----- |
  * | `7.10.2/extra/inspect.json` | x86 | 7.10.2 | 29,086 |
  * | `7.16/extra/inspect.json` | x86 | 7.16 | 34,876 |
- * | `7.24.2/extra/deep-inspect.x86.json` | x86 | 7.24.2 | 41,345 |
- * | `7.24.2/extra/deep-inspect.arm64.json` | arm64 | 7.24.2 | 42,691 |
- * | `7.25beta3/extra/deep-inspect.x86.json` | x86 | 7.25beta3 | 41,798 |
- * | `7.25beta3/extra/deep-inspect.arm64.json` | arm64 | 7.25beta3 | 43,148 |
+ * | `7.24.4/extra/deep-inspect.x86.json` | x86 | 7.24.4 | 41,345 |
+ * | `7.24.4/extra/deep-inspect.arm64.json` | arm64 | 7.24.4 | 42,691 |
+ * | `7.25beta5/extra/deep-inspect.x86.json` | x86 | 7.25beta5 | 41,794 |
+ * | `7.25beta5/extra/deep-inspect.arm64.json` | arm64 | 7.25beta5 | 43,150 |
  *
  * | Kind | Total | `both` | `inspect` | `published` |
  * | ---- | ----- | ------ | --------- | ----------- |
- * | `menu` | 554 | 443 | 67 | 44 |
+ * | `menu` | 554 | 445 | 65 | 44 |
  * | `command` | 450 | 409 | 0 | 41 |
  * | `settings` | 116 | 107 | 0 | 9 |
  *
@@ -285,7 +285,7 @@ const ROWS = `
 /interface/ethernet/poe/monitor|command|published|||(poe or poe-in)
 /interface/ethernet/poe/power-cycle|command|published|||(poe or poe-in)
 /interface/ethernet/poe/settings|settings|published|||(poe or poe-in) and poesettings
-/interface/ethernet/pon|menu|inspect
+/interface/ethernet/pon|menu|both
 /interface/ethernet/reset-counters|command|both
 /interface/ethernet/reset-mac-address|command|both
 /interface/ethernet/switch|menu|both
@@ -744,7 +744,7 @@ const ROWS = `
 /ip/ssh|settings|both
 /ip/ssh/export-host-key|command|both
 /ip/ssh/import-host-key|command|both
-/ip/ssh/known-hosts|menu|inspect
+/ip/ssh/known-hosts|menu|both
 /ip/ssh/regenerate-host-key|command|both
 /ip/tftp|menu|both
 /ip/tftp/settings|settings|both

package/src/explain/menus.ts

@@ -12,10 +12,10 @@
  * | ---- | ---- | -------- | ----- | ---------- |
  * | `7.10.2/extra/inspect.json` | x86 | 7.10.2 | 29,086 | 458 |
  * | `7.16/extra/inspect.json` | x86 | 7.16 | 34,876 | 522 |
- * | `7.24.2/extra/deep-inspect.x86.json` | x86 | 7.24.2 | 41,345 | 554 |
- * | `7.24.2/extra/deep-inspect.arm64.json` | arm64 | 7.24.2 | 42,691 | 575 |
- * | `7.25beta3/extra/deep-inspect.x86.json` | x86 | 7.25beta3 | 41,798 | 557 |
- * | `7.25beta3/extra/deep-inspect.arm64.json` | arm64 | 7.25beta3 | 43,148 | 578 |
+ * | `7.24.4/extra/deep-inspect.x86.json` | x86 | 7.24.4 | 41,345 | 554 |
+ * | `7.24.4/extra/deep-inspect.arm64.json` | arm64 | 7.24.4 | 42,691 | 575 |
+ * | `7.25beta5/extra/deep-inspect.x86.json` | x86 | 7.25beta5 | 41,794 | 557 |
+ * | `7.25beta5/extra/deep-inspect.arm64.json` | arm64 | 7.25beta5 | 43,150 | 578 |
  *
  * Zero node-type conflicts across those trees — no `dir`↔`cmd` flip across
  * 4 versions or across architectures — which is what makes the union

package/src/index.ts

@@ -203,6 +203,7 @@ export {
 	type DevicesCommand,
 	type DevicesEnvelope,
 	type DevicesGroupSummary,
+	type DevicesInitData,
 	type DevicesListItem,
 	type DevicesMutationData,
 	type DevicesMutationEnvelope,
@@ -215,6 +216,7 @@ export {
 	defaultCdbPath,
 	devicesOutputFormats,
 	editInteractiveOnlyError,
+	initCdb,
 	type LoadCdbOptions,
 	type LoadedCdb,
 	listDevices,

package/src/mcp/tools.ts

@@ -352,7 +352,7 @@ export const executeInputShape = {
 		.boolean()
 		.optional()
 		.describe(
-			"Required true for write-shaped commands (add/set/remove). Reads ignore it.",
+			"Required true for write-shaped commands, including selector/positional and non-CRUD mutations. Reads ignore it.",
 		),
 	via: z.string().optional().describe("Override transport."),
 	timeout: z

package/src/protocols/adapter.ts

@@ -152,6 +152,14 @@ export interface ProtocolListenOptions {
 	 * after the follow is established, instead of a blind timer.
 	 */
 	onListening?: () => void;
+	/**
+	 * How long to wait for RouterOS to acknowledge `/cancel` after `signal`
+	 * aborts before ending the listen locally. Native API defaults to the
+	 * adapter's `timeoutMs`, the same bound as any other reply wait.
+	 */
+	cancelGraceMs?: number;
+	/** Fired when that wait expires without the router's acknowledgement. */
+	onCancelUnacknowledged?: () => void;
 }
 
 /**
@@ -733,7 +741,10 @@ class NativeApiAdapter implements ProtocolAdapter {
 			command.proplist = request.proplist;
 		}
 		const session = await this.connect();
-		for await (const reply of session.listen(command, options)) {
+		for await (const reply of session.listen(command, {
+			...options,
+			cancelGraceMs: options.cancelGraceMs ?? this.config.timeoutMs,
+		})) {
 			// Each `!re` becomes a rest-style record (string values; `.dead` preserved).
 			yield { ...reply.attributes };
 		}

package/src/protocols/mac-telnet-console.ts

@@ -627,14 +627,16 @@ export function parseScriptFor(cli: string): string {
  *      with RouterOS's position suffix. All 425 corpus rows of this shape are
  *      the entire return; none appear embedded. Requiring both line-start and
  *      the `(line N column M)` suffix is what separates a real verdict from
- *      echoed body text.
+ *      echoed body text. The pinned 7.23.5/7.24.2/7.25beta3 captures add no
+ *      new heads beyond `syntax error`, `expected …` and `missing …`
+ *      (`missing closing brace`, `missing value for where`; GH#375).
  */
 const WRAPPED_BAD_PARAMETER = /\(evl\s+bad parameter\s+(\S+)/i;
 const WRAPPED_BAD_COMMAND = /\(<%%\s*bad command name\b/i;
 const BARE_BAD_PARAMETER =
 	/^[ \t]*bad parameter\s+(\S+)[^\n]*\(line \d+ column \d+\)/im;
 const BARE_SYNTAX =
-	/^[ \t]*(?:syntax error|bad command name|expected [a-z]+(?: [a-z]+)*)[^\n]*\(line \d+ column \d+\)/im;
+	/^[ \t]*(?:syntax error|bad command name|(?:expected|missing) [a-z]+(?: [a-z]+)*)[^\n]*\(line \d+ column \d+\)/im;
 
 /**
  * Classify the printed value of `:put [:parse "<cli>"]`. Grounded on CHR 7.23.3
@@ -646,8 +648,8 @@ const BARE_SYNTAX =
  * RouterOS emits them (see the grammar note above): wrapped as
  * `(evl bad parameter <name> (line N column M) /path)` /
  * `(<%% bad command name <name> (line N column M) a;b;c)`, or bare and
- * line-initial as `expected … (line N column M)` / `syntax error (line N column
- * M)`. A single `:parse` covers both the syntax and the unknown-attribute
+ * line-initial as `expected … (line N column M)` / `missing … (line N column
+ * M)` / `syntax error (line N column M)`. A single `:parse` covers both the syntax and the unknown-attribute
  * (name-level) gate on every transport — REST and native API expose the same text
  * in the `ret` value (HTTP 200 / `as-string`), the console transports print it.
  *

package/src/protocols/native-api.ts

@@ -635,10 +635,21 @@ export class NativeApiSession {
 	 *   trap/`!done` are not awaited) and the generator returns.
 	 * A non-`interrupted` trap (e.g. a bad path) or `!fatal`/transport closure
 	 * throws. CHR-grounded (7.23.1): see `commands/api/AGENTS.md`.
+	 *
+	 * After an abort, `cancelGraceMs` bounds the wait for that acknowledgement: a
+	 * peer that never answers `/cancel` would otherwise hold the generator open
+	 * forever (#385). On expiry the generator ends without the router's
+	 * `!done` and `onCancelUnacknowledged` fires, so the caller can close the
+	 * session and report that the stop was local, not acknowledged.
 	 */
 	async *listen(
 		command: NativeApiCommand,
-		options: { signal?: AbortSignal; onListening?: () => void } = {},
+		options: {
+			signal?: AbortSignal;
+			onListening?: () => void;
+			cancelGraceMs?: number;
+			onCancelUnacknowledged?: () => void;
+		} = {},
 	): AsyncGenerator<ApiReply, void, void> {
 		if (this.closed) {
 			throw (
@@ -702,10 +713,24 @@ export class NativeApiSession {
 		// can act on a real barrier rather than a blind timer.
 		options.onListening?.();
 
-		const onAbort = (): void => this.cancel(tag);
+		let graceTimer: ReturnType<typeof setTimeout> | undefined;
+		const onAbort = (): void => {
+			this.cancel(tag);
+			if (options.cancelGraceMs === undefined) return;
+			graceTimer = setTimeout(() => {
+				if (ended) return;
+				// Stop routing this tag and drop anything queued: a peer that ignores
+				// `/cancel` but keeps sending frames must not keep the loop draining.
+				this.subscriptions.delete(tag);
+				queue.length = 0;
+				ended = true;
+				options.onCancelUnacknowledged?.();
+				signalWake();
+			}, options.cancelGraceMs);
+		};
 		if (options.signal) {
 			if (options.signal.aborted) {
-				this.cancel(tag);
+				onAbort();
 			} else {
 				options.signal.addEventListener("abort", onAbort, { once: true });
 			}
@@ -738,6 +763,7 @@ export class NativeApiSession {
 				throw this.trapToError(command.command, trap);
 			}
 		} finally {
+			clearTimeout(graceTimer);
 			options.signal?.removeEventListener("abort", onAbort);
 			this.subscriptions.delete(tag);
 			// Consumer broke out early (e.g. --count reached): tell the router to stop.

package/src/resolver/target.ts

@@ -428,20 +428,40 @@ export function resolveAuth(
 }
 
 export function parseHostCandidate(value: string): URL {
-	if (/^https?:\/\//i.test(value)) {
-		const url = new URL(value);
-		if (url.pathname !== "/" && url.pathname !== "") {
-			throw new CentrsError({
-				code: "input/invalid-target",
-				summary: `Target URL must not include a path. Received: ${value}`,
-				remediation:
-					"Pass only the RouterOS host or base URL, then provide the RouterOS menu path as the second positional argument.",
-			});
-		}
-		return url;
+	const hasScheme = /^https?:\/\//i.test(value);
+	let url: URL;
+	try {
+		url = new URL(hasScheme ? value : `http://${value}`);
+	} catch (cause) {
+		throw invalidTargetError(value, cause);
 	}
+	if (hasScheme && url.pathname !== "/" && url.pathname !== "") {
+		throw new CentrsError({
+			code: "input/invalid-target",
+			summary: `Target URL must not include a path. Received: ${value}`,
+			remediation:
+				"Pass only the RouterOS host or base URL, then provide the RouterOS menu path as the second positional argument.",
+		});
+	}
+	return url;
+}
 
-	return new URL(`http://${value}`);
+/**
+ * A `<router>` that is not a CDB handle and does not parse as a host (#381).
+ * `quickchr:NAME` is the likely guess for a quickchr VM, so it names the flag.
+ */
+function invalidTargetError(value: string, cause: unknown): CentrsError {
+	const quickchrGuess = /^quickchr:(.+)$/i.exec(value)?.[1];
+	return new CentrsError({
+		code: "input/invalid-target",
+		summary: `Target is not a known device or a valid host: ${value}`,
+		remediation:
+			quickchrGuess !== undefined
+				? `Select a quickchr VM with the flag: \`--quickchr ${quickchrGuess}\` (there is no \`quickchr:\` target prefix).`
+				: "Pass a CDB target or identity (see `centrs devices list`), an IP or hostname with optional `:port`, or an `http(s)://host[:port]` base URL.",
+		context: { target: value },
+		cause,
+	});
 }
 
 function readPort(parsedUrl: URL, scheme: "http" | "https"): number {