@tikoci/centrs 0.1.9-next.23 → 0.1.9-next.27

package/src/protocols/adapter.ts

@@ -14,6 +14,7 @@
  * protocol data.
  */
 
+import { assertRestRequestPath } from "../core/menu-path.ts";
 import { mapRouterOsError } from "../core/routeros-errors.ts";
 import { CentrsError } from "../errors.ts";
 import { formatEndpoint } from "./endpoint.ts";
@@ -235,10 +236,10 @@ export interface ProtocolAdapter {
 	readonly protocol: RouterOsProtocol;
 	/** Capability flags describing what this adapter supports. */
 	readonly capabilities: ProtocolAdapterCapabilities;
-	/** `/console/inspect` probe (`request=child` or `request=completion`). */
-	/** `/console/inspect`; `input` is the CLI-text form (`request=completion input=…`). */
+	/** `/console/inspect` discovery, completion, syntax help or byte highlight. */
+	/** `input` is CLI text for completion or highlight. */
 	inspect(
-		request: "child" | "completion",
+		request: "child" | "completion" | "highlight" | "syntax",
 		path: string,
 		input?: string,
 	): Promise<unknown[]>;
@@ -309,7 +310,7 @@ class RestAdapter implements ProtocolAdapter {
 	}
 
 	async inspect(
-		request: "child" | "completion",
+		request: "child" | "completion" | "highlight" | "syntax",
 		path: string,
 		input?: string,
 	): Promise<unknown[]> {
@@ -562,7 +563,13 @@ class RestAdapter implements ProtocolAdapter {
 			);
 			const data = parseResponseBody(text);
 			if (!response.ok) {
-				throw this.mapHttpFailure(response.status, text, data, path);
+				throw this.mapHttpFailure(
+					response.status,
+					text,
+					data,
+					path,
+					response.headers,
+				);
 			}
 
 			return { status: response.status, text, data };
@@ -581,19 +588,54 @@ class RestAdapter implements ProtocolAdapter {
 		text: string,
 		data: unknown,
 		path: string,
+		headers: Headers,
 	): CentrsError {
 		const { protocol, host, port } = this.config;
 		if (status === 401 || status === 403) {
+			if (!isRouterOsAuthReply(status, data, headers)) {
+				return new CentrsError({
+					code: "transport/edge-auth-failed",
+					summary: `An HTTP layer in front of RouterOS at ${formatEndpoint(host, port)} refused the request (HTTP ${status}); RouterOS did not answer it.`,
+					remediation:
+						"An auth proxy, tunnel edge, or WAF wants its own credentials, and centrs sends only RouterOS Basic auth. Point `--host` at an address that reaches RouterOS directly, or at a local proxy that authenticates to that layer for you. Changing the RouterOS username or password will not help.",
+					context: {
+						via: protocol,
+						host,
+						port,
+						path,
+						status,
+						...edgeEvidence(headers),
+					},
+					causeData: data ?? text,
+				});
+			}
 			return new CentrsError({
 				code: "transport/auth-failed",
 				summary: `RouterOS rejected the REST credentials for ${formatEndpoint(host, port)}.`,
 				remediation:
-					"Check `--username` / `--password` or the matching `CENTRS_*` environment variables, and confirm the user has RouterOS REST access.",
+					"Check `--username` / `--password` or the matching `CENTRS_*` environment variables. RouterOS answers the same 401 when the user's group lacks the `rest-api` policy or the user's `address` excludes this client.",
 				context: { via: protocol, host, port, path, status },
 				causeData: data ?? text,
 			});
 		}
 
+		const detail = isPlainObject(data)
+			? readRecordString(data, "detail")
+			: undefined;
+		if (detail !== undefined) {
+			// RouterOS reports a policy refusal as HTTP 500 with a `(9)` detail.
+			// It is a deterministic router answer, not a dropped connection, so it
+			// must not reach the 5xx retry path below.
+			const mapped = mapRouterOsError(detail, {
+				transport: "rest-api",
+				httpStatus: status,
+				context: { via: protocol, host, port, path, status },
+			});
+			if (mapped.code === "routeros/permission-denied") {
+				return mapped;
+			}
+		}
+
 		if (status >= 500 && status <= 599) {
 			// A 5xx is a transient server/connection drop (RouterOS REST under
 			// fanout load drops a fraction of parallel POSTs). Classify it as a
@@ -610,9 +652,6 @@ class RestAdapter implements ProtocolAdapter {
 			});
 		}
 
-		const detail = isPlainObject(data)
-			? readRecordString(data, "detail")
-			: undefined;
 		const rawRouterOsError = detail ?? text;
 		return mapRouterOsError(rawRouterOsError, {
 			transport: "rest-api",
@@ -750,7 +789,7 @@ class NativeApiAdapter implements ProtocolAdapter {
 	}
 
 	async inspect(
-		request: "child" | "completion",
+		request: "child" | "completion" | "highlight" | "syntax",
 		path: string,
 		input?: string,
 	): Promise<unknown[]> {
@@ -1298,6 +1337,7 @@ function repliesToRecords(
 }
 
 function joinRestUrl(baseUrl: string, path: string): string {
+	assertRestRequestPath(path);
 	const normalizedPath = path.startsWith("/") ? path : `/${path}`;
 	return `${baseUrl}${normalizedPath}`;
 }
@@ -1360,6 +1400,46 @@ function collectTransportSignalsInto(
 	}
 }
 
+/**
+ * True when a REST 401/403 reply has RouterOS's own shape. RouterOS answers
+ * every auth refusal (wrong password, no `rest-api` policy, `address`
+ * mismatch) with a JSON body `{"error":401,...}`, adding
+ * `WWW-Authenticate: Basic` only when no credentials were sent. Measured on
+ * CHR 7.12.1, 7.16.2, 7.23.8, 7.25, 7.26beta1 and 7.26beta3. Any other body,
+ * or a challenge for another scheme (Cloudflare Access sends `Bearer`), came
+ * from a layer in front of RouterOS. A `cf-ray` header alone proves nothing:
+ * a tunnel passes RouterOS's own 401 through with it.
+ */
+function isRouterOsAuthReply(
+	status: number,
+	data: unknown,
+	headers: Headers,
+): boolean {
+	const challenge = headers.get("www-authenticate");
+	if (challenge !== null && !/^\s*basic\b/i.test(challenge)) {
+		return false;
+	}
+	return isPlainObject(data) && data["error"] === status;
+}
+
+/** Non-secret header facts that show which layer refused a request. */
+function edgeEvidence(headers: Headers): {
+	challengeScheme?: string;
+	server?: string;
+	contentType?: string;
+	cfRay?: "present";
+} {
+	const evidence: ReturnType<typeof edgeEvidence> = {};
+	const scheme = headers.get("www-authenticate")?.trim().split(/\s+/)[0];
+	if (scheme) evidence.challengeScheme = scheme;
+	const server = headers.get("server");
+	if (server) evidence.server = server;
+	const contentType = headers.get("content-type");
+	if (contentType) evidence.contentType = contentType;
+	if (headers.has("cf-ray")) evidence.cfRay = "present";
+	return evidence;
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/protocols/btest-session.ts

@@ -72,7 +72,6 @@ import {
 } from "./btest.ts";
 import {
 	bytesToBigIntBE,
-	type EcSrp5Shared,
 	ecSrp5ClientConfirm,
 	ecSrp5ClientShared,
 	ecSrp5Id,
@@ -677,13 +676,11 @@ async function runClientEcSrp5(
 
 	const challenge = parseServerChallenge(await readAuthFrame(channel));
 	const validator = ecSrp5Id(username, password, challenge.salt);
-	const shared = btestShared(
-		ecSrp5ClientShared(
-			keypair.privateKey,
-			challenge.serverPublicKey,
-			keypair.publicKey,
-			validator,
-		),
+	const shared = ecSrp5ClientShared(
+		keypair.privateKey,
+		challenge.serverPublicKey,
+		keypair.publicKey,
+		validator,
 	);
 	const clientCc = ecSrp5ClientConfirm(shared);
 	await channel.write(encodeConfirmation(clientCc));
@@ -785,13 +782,11 @@ async function runServerEcSrp5(
 	);
 	await channel.write(encodeServerChallenge(serverPublicKey, salt));
 
-	const shared = btestShared(
-		ecSrp5ServerShared(
-			keypair.privateKey,
-			validatorScalar,
-			hello.publicKey,
-			serverPublicKey,
-		),
+	const shared = ecSrp5ServerShared(
+		keypair.privateKey,
+		validatorScalar,
+		hello.publicKey,
+		serverPublicKey,
 	);
 	const clientCc = await readAuthFrame(channel);
 	const expectedCc = ecSrp5ClientConfirm(shared);
@@ -804,21 +799,6 @@ async function runServerEcSrp5(
 	return hello.username;
 }
 
-/**
- * The shared secret as btest hashes it: `z` without its leading zero bytes
- * (OpenSSL `BN_bn2bin`), where MAC-Telnet's `mtwei.c` pads it to 32
- * (`BN_bn2binpad`), so the shared math in `ec-srp5.ts` keeps 32 bytes.
- *
- * Grounded on CHR 7.24.5 `/tool/bandwidth-server`: over 800 client handshakes,
- * every one whose `z` began with 0x00 (9) failed with the padded form and no
- * other did. Stripped, 600 of 600 verified, 4 of them with a leading zero.
- */
-export function btestShared(shared: EcSrp5Shared): EcSrp5Shared {
-	let start = 0;
-	while (start < shared.z.length - 1 && shared.z[start] === 0) start++;
-	return start === 0 ? shared : { j: shared.j, z: shared.z.subarray(start) };
-}
-
 function ecSrp5RandomSalt(): Uint8Array {
 	return crypto.getRandomValues(new Uint8Array(16));
 }

package/src/protocols/ec-srp5.ts

@@ -16,9 +16,14 @@
  * (`haakonnessjoen/MAC-Telnet`, © Yandex 2022), cross-checked against the WinBox
  * EC-SRP5 reference (`Lab/winbox-terminal-protocol`) and `tikoci/m2ir`'s
  * `winbox-ipc/ec-srp5-handshake.yaml` (derived from MarginResearch's PoC). The
- * curve constants, point encoding, identity hash, and proof derivation match all
- * three, and the proof is accepted by real RouterOS over the MAC-Telnet L2
- * harness.
+ * curve constants, point encoding and identity hash match all three.
+ *
+ * The hash inputs do not: `mtwei.c` pads the REDP1 loop seed and shared `z` to
+ * 32 bytes (`BN_bn2binpad`), but RouterOS hashes them minimal-length (#565).
+ * Grounded in `libucrypto.so` 6.49.23/7.25 and live CHR A/B runs over WinBox,
+ * btest and MAC-Telnet, where the padded proof is rejected whenever the two
+ * forms differ. Public-key X and the REDP1 input stay fixed at 32 bytes.
+ * Reference vectors and provenance live in `test/fixtures/ec-srp5.json`.
  */
 
 import { createHash, randomBytes } from "node:crypto";
@@ -131,6 +136,11 @@ export function bigIntToBytesBE(value: bigint, length: number): Uint8Array {
 	return out;
 }
 
+/** Minimal unsigned big-endian hash input; retain one byte for zero. */
+function bigIntToBytesMinimal(value: bigint): Uint8Array {
+	return bigIntToBytesBE(value, Math.ceil(value.toString(16).length / 2));
+}
+
 export function sha256(...chunks: readonly Uint8Array[]): Uint8Array {
 	const hash = createHash("sha256");
 	for (const chunk of chunks) hash.update(chunk);
@@ -297,18 +307,18 @@ export function ecSrp5Id(
 export function redp1(montgomeryX: Uint8Array, parity: number): Point {
 	let seed = bytesToBigIntBE(sha256(montgomeryX));
 	for (;;) {
-		const candidate = sha256(bigIntToBytesBE(seed, 32));
+		const candidate = sha256(bigIntToBytesMinimal(seed));
 		const xWeier = mod(bytesToBigIntBE(candidate) + M2W, P);
 		const point = liftX(xWeier, parity);
 		if (point !== null) return point;
-		seed = mod(seed + 1n, 1n << 256n);
+		seed += 1n;
 	}
 }
 
 /**
  * Shared-secret material `(j, z)` common to both EC-SRP5 roles.
  *   j = SHA256(clientMontX ‖ serverMontX)  (the two 32-byte Montgomery Xs)
- *   z = Montgomery-X of the agreed shared point
+ *   z = minimal-length big-endian Montgomery-X of the agreed shared point
  * The confirmation codes are derived from these (see {@link ecSrp5ClientConfirm}
  * / {@link ecSrp5ServerConfirm}).
  */
@@ -360,14 +370,13 @@ export function ecSrp5ClientShared(
 			remediation: "The peer key may be invalid; confirm the device.",
 		});
 	}
-	const z = bigIntToBytesBE(mod(pt.x + W2M, P), 32);
+	const z = bigIntToBytesMinimal(mod(pt.x + W2M, P));
 	return { j, z };
 }
 
 /**
  * Compute the 32-byte EC-SRP5 **client** authentication proof
- * (`mtwei_docrypto`): `SHA256(j ‖ z)`. Unchanged in bytes from the original
- * `mtwei.c` port — MAC-Telnet's MTWEI uses this directly.
+ * (`mtwei_docrypto`): `SHA256(j ‖ z)`. MAC-Telnet's MTWEI uses this directly.
  */
 export function ecSrp5ClientProof(
 	privateKey: bigint,
@@ -445,7 +454,7 @@ export function ecSrp5ServerShared(
 			remediation: "The peer key may be invalid; confirm the client.",
 		});
 	}
-	const z = bigIntToBytesBE(mod(pt.x + W2M, P), 32);
+	const z = bigIntToBytesMinimal(mod(pt.x + W2M, P));
 	return { j, z };
 }
 

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

@@ -6,8 +6,8 @@
  * layer drives the RouterOS console the way a terminal would and reconstructs
  * the "screen", then strips the echoed command and the trailing prompt.
  *
- * Everything here is grounded on stock CHR 7.23.1 (probes in `.scratch/`,
- * captured while wiring `execute / mac-telnet`):
+ * Everything here is grounded on stock CHR 7.23.1 (lab probes, history —
+ * captured while wiring `execute / mac-telnet` in PR #15, a9f1cbf):
  *
  *   - **Terminal-size probe at login.** The console emits a multi-step ANSI
  *     cursor probe: `ESC[9999B`/`ESC[9999C` (move to find the edges), `ESC[H`,

package/src/protocols/mac-telnet.ts

@@ -546,6 +546,39 @@ async function egressAddressFor(
 	});
 }
 
+/**
+ * Pure egress-MAC selection over an injected interface list: the decision
+ * {@link resolveEgressMac} makes, without touching the host's NICs, so unit
+ * tests can pin it with stubbed interfaces instead of depending on the
+ * runner's network setup.
+ *
+ * A broadcast host owns no route: `connect()` to one reports local
+ * `0.0.0.0`, so match it to the interface whose directed broadcast it is
+ * instead. Without this, an explicit `--host <broadcast>` falls back to a
+ * synthetic source MAC, which RouterOS's mac-server silently ignores
+ * (orca 2026-10-26: 30s login timeout vs 7.26beta3 hardware despite
+ * mac-server=all and proven L2 adjacency; CHR answers synthetic MACs, so
+ * the integration suite stayed green). The limited `255.255.255.255`
+ * belongs to no one interface and still falls through to undefined — the
+ * default-broadcast path sprays discovery instead. On a tie (two NICs on
+ * one subnet sharing a broadcast) the first match wins, which may not be
+ * the route's pick; the discovery spray remains the way to probe every NIC.
+ */
+export function selectEgressMac(
+	host: string,
+	interfaces: readonly BroadcastInterface[],
+	localAddr: string | undefined,
+): MacAddress | undefined {
+	const owner = interfaces.find((ifc) => ifc.broadcast === host);
+	if (owner !== undefined) {
+		return owner.mac;
+	}
+	if (!localAddr || localAddr === "0.0.0.0") {
+		return undefined;
+	}
+	return interfaces.find((ifc) => ifc.address === localAddr)?.mac;
+}
+
 /**
  * Resolve the **real MAC of the interface that egresses toward `host:port`**, for
  * use as the in-packet source MAC.
@@ -561,16 +594,11 @@ export async function resolveEgressMac(
 	host: string,
 	port: number,
 ): Promise<MacAddress | undefined> {
-	const localAddr = await egressAddressFor(host, port);
-	if (!localAddr) {
-		return undefined;
-	}
-	for (const ifc of listBroadcastInterfaces()) {
-		if (ifc.address === localAddr) {
-			return ifc.mac;
-		}
-	}
-	return undefined;
+	return selectEgressMac(
+		host,
+		listBroadcastInterfaces(),
+		await egressAddressFor(host, port),
+	);
 }
 
 /** Which interface (source MAC + delivery host) reaches a target over MAC-Telnet. */

package/src/protocols/native-api.ts

@@ -345,19 +345,20 @@ export function readAttribute(
 /**
  * Classify a native-API `!trap` as an authentication failure.
  *
- * Auth failures surface on `/login` (bad credentials) or on any command when
- * the session is not authorized, so the trap message is matched rather than
- * relying on the command word alone. The strings are grounded on live RouterOS
- * CHR output: "invalid user name or password", "could not authenticate -
- * radius timeout", "not logged in", "access denied". Misclassifying these as a
- * syntax/validation error was the reported `execute` bug.
+ * Only the login exchange (`/login`) can fail authentication: a trap there
+ * means bad credentials (or a dead RADIUS backend), whatever its text —
+ * grounded on live RouterOS CHR output ("invalid user name or password",
+ * "could not authenticate - radius timeout"). Traps from any later sentence
+ * are RouterOS command answers and classify under `routeros/*` regardless of
+ * text: matching login-like words on every command misreported `/user/add
+ * name=-2` ("invalid user name") as an auth failure though login had succeeded
+ * (#540), while REST mapped the same string to `routeros/command-failed`.
  */
-export function isNativeAuthFailure(command: string, message: string): boolean {
-	return (
-		/not logged in|access denied|invalid user|could not authenticate|authentication failed|radius (?:timeout|error)|bad password|password|\blogin\b|\buser\b/i.test(
-			message,
-		) || command === "/login"
-	);
+export function isNativeAuthFailure(
+	command: string,
+	_message: string,
+): boolean {
+	return command === "/login";
 }
 
 /**

package/src/resolver/cdb.ts

@@ -137,6 +137,44 @@ export interface CdbResolveInput {
 	targetInput?: string;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/**
+	 * `--match` record selector (`user=<name>`, `target=<addr>`, or a record
+	 * type such as `ipUser`) for a `<router>` several CDB records share — the
+	 * same selector `devices show --match` takes (#583). Given a `match`, the
+	 * call must resolve a CDB record: no CDB, a literal host, or a
+	 * `__default__`-only fallback fails `identity/no-match` instead of
+	 * ignoring the selector.
+	 */
+	match?: string;
+}
+
+/**
+ * `--match` picks one CDB record for one `<router>`; a fan-out selection
+ * already visits every selected record. Shared by every command's fan-out
+ * entry so the flag is never silently ignored (#583).
+ */
+export function assertNoMatchInFanout(match: string | undefined): void {
+	if (match === undefined) {
+		return;
+	}
+	throw new CentrsError({
+		code: "usage/conflicting-flags",
+		summary:
+			"`--match` selects one CDB record for a single `<router>`; it cannot be combined with a fan-out selection.",
+		remediation:
+			"Drop `--match`, or target the one router positionally: `<router> --match user=<name>`. A fan-out already visits every selected record.",
+		context: { flag: "--match", match },
+	});
+}
+
+function matchWithoutRecord(input: CdbResolveInput, reason: string): never {
+	throw new CentrsError({
+		code: "identity/no-match",
+		summary: `--match "${input.match}" needs a CDB record for "${input.targetInput ?? ""}", but ${reason}.`,
+		remediation:
+			"Run `centrs devices list` to see the saved records and their users, then pass the `<router>` they are saved under with --match, or drop --match for an ad-hoc host.",
+		context: { target: input.targetInput, match: input.match },
+	});
 }
 
 function warningFromDevices(warning: DevicesWarning): ResolverWarning {
@@ -164,6 +202,9 @@ export async function resolveCdb(
 	config: Record<string, string | undefined> = {},
 ): Promise<CdbResolution | undefined> {
 	if (!input.targetInput) {
+		if (input.match !== undefined) {
+			matchWithoutRecord(input, "no `<router>` was given");
+		}
 		return undefined;
 	}
 	// Before any lookup: a CDB miss echoes the target it was given (#478).
@@ -186,6 +227,9 @@ export async function resolveCdb(
 		env[ENV_CDB_PASSWORD] !== undefined ||
 		config[ENV_CDB_FILE] !== undefined;
 	if (!explicitCdb && !(await Bun.file(settings.cdbFile.value).exists())) {
+		if (input.match !== undefined) {
+			matchWithoutRecord(input, "no CDB file is in play");
+		}
 		return undefined;
 	}
 
@@ -201,7 +245,8 @@ export async function resolveCdb(
 		if (
 			!explicitCdb &&
 			error instanceof CentrsError &&
-			error.code === "cdb/not-found"
+			error.code === "cdb/not-found" &&
+			input.match === undefined
 		) {
 			return undefined;
 		}
@@ -211,7 +256,11 @@ export async function resolveCdb(
 	const defaults = findDefaultCreds(cdb);
 
 	try {
-		const envelope = showDevice({ cdb, target: input.targetInput });
+		const envelope = showDevice({
+			cdb,
+			target: input.targetInput,
+			match: input.match,
+		});
 		const entry = envelope.data.entry;
 		const warnings: ResolverWarning[] =
 			envelope.warnings.map(warningFromDevices);
@@ -236,6 +285,13 @@ export async function resolveCdb(
 		if (redactTargetInput(input.targetInput) !== input.targetInput) {
 			assertNoTargetCredentials(input.targetInput);
 		}
+		if (
+			error instanceof CentrsError &&
+			error.code === "cdb/not-found-target" &&
+			input.match !== undefined
+		) {
+			matchWithoutRecord(input, "no CDB record matches it");
+		}
 		if (error instanceof CentrsError && error.code === "cdb/not-found-target") {
 			// A `__default__` record supplies fallback credentials even when the
 			// target has no record of its own. On the CLI/API this fills creds for

package/src/resolver/index.ts

@@ -19,6 +19,7 @@
  */
 
 export {
+	assertNoMatchInFanout,
 	type CdbGroupExpansion,
 	type CdbGroupResolveInput,
 	type CdbGroupTarget,

package/src/resolver/quickchr-provider.ts

@@ -347,10 +347,15 @@ export function assertNoQuickchrOverrideConflict(
 		username?: string;
 		password?: string;
 		sshKey?: string;
+		/** `--match` picks a CDB record; a quickchr target has none (#583). */
+		match?: string;
 	},
 	machine: string,
 ): void {
 	const conflicts: string[] = [];
+	if (request.match !== undefined) {
+		conflicts.push("--match");
+	}
 	if (request.host !== undefined) {
 		conflicts.push("--host");
 	}

package/src/resolver/selection.ts

@@ -309,6 +309,17 @@ export async function expandSelection(
 				}
 				continue;
 			}
+			// The devices remediation names `--match`, which a fan-out refuses
+			// (it picks one record for one `<router>`, #583).
+			if (error instanceof CentrsError && error.code === "identity/ambiguous") {
+				throw new CentrsError({
+					code: error.code,
+					summary: error.summary,
+					remediation: `In a fan-out each positional must name one CDB record. Run "${positional}" on its own with --match user=<name>, --match target=<addr>, or --match <record-type>, or select the records with --group / --where instead.`,
+					context: error.context,
+					cause: error,
+				});
+			}
 			throw error;
 		}
 	}

package/src/retrieve-fanout.ts

@@ -56,6 +56,7 @@ import {
 } from "./errors.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
+	assertNoMatchInFanout,
 	expandSelection,
 	isDefaultRecordTarget,
 	loadEnvFileDefaults,
@@ -203,6 +204,7 @@ export async function retrieveFanout(
 	internals: RetrieveFanoutInternals = {},
 	options: RetrieveFanoutOptions = {},
 ): Promise<RetrieveFanoutEnvelope> {
+	assertNoMatchInFanout(request.match);
 	if (request.wait !== undefined)
 		throw new CentrsError({
 			code: "usage/fanout-not-supported",

package/src/retrieve-follow.ts

@@ -27,6 +27,7 @@ import {
 import {
 	buildRetrieveErrorEnvelope,
 	buildRetrieveErrorEnvelopeFromResolved,
+	notReachedValidationMeta,
 	type ResolvedRetrieveRequest,
 	type RetrieveFollowCounts,
 	type RetrieveFollowLine,
@@ -176,7 +177,7 @@ export async function* retrieveFollow(
 	if (options.signal?.aborted) {
 		yield interruptedSummary(
 			resolved,
-			{ enabled: resolved.validate.value, result: "skipped" },
+			notReachedValidationMeta(resolved, "interrupted"),
 			startedAt,
 		);
 		return;

package/src/retrieve-sample.ts

@@ -16,6 +16,7 @@ import {
 	buildRetrieveErrorEnvelope,
 	buildRetrieveErrorEnvelopeFromResolved,
 	executeRetrieve,
+	notReachedValidationMeta,
 	type ResolvedRetrieveRequest,
 	type RetrieveRequest,
 	type RetrieveSampleStopReason,
@@ -85,7 +86,7 @@ export async function* retrieveSample(
 	if (options.signal?.aborted) {
 		yield summaryEnvelope(
 			resolved,
-			{ enabled: resolved.validate.value, result: "skipped" },
+			notReachedValidationMeta(resolved, "interrupted"),
 			{ stopReason: "interrupted", samples: 0 },
 			startedAt,
 		);

package/src/retrieve-wait.ts

@@ -1,4 +1,5 @@
 /** Bounded readiness/condition reads; the router evaluates the shared predicate. */
+import type { EnvelopeValidationMeta } from "./core/envelope.ts";
 import { parseQueries, queryErrorForFlag } from "./core/query.ts";
 import { CentrsError } from "./errors.ts";
 import {
@@ -17,6 +18,7 @@ import {
 	type RetrieveRequest,
 	type RetrieveWaitMeta,
 	resolveRetrieveRequest,
+	stoppedBeforeGateAnswer,
 	validateRetrieveRead,
 } from "./retrieve.ts";
 
@@ -72,6 +74,9 @@ export async function retrieveWait(
 	let observations = 0;
 	let backend: ProtocolAdapter | undefined;
 	let prepared: Awaited<ReturnType<typeof validateRetrieveRead>> | undefined;
+	// A retry drops `prepared` with its backend, but a gate that passed once
+	// stays passed: a later failure that is not a gate answer keeps it (#537).
+	let settled: EnvelopeValidationMeta | undefined;
 	let lastError: unknown;
 	const meta = (
 		stopReason: RetrieveWaitMeta["stopReason"],
@@ -105,12 +110,10 @@ export async function retrieveWait(
 		)
 			error = queryErrorForFlag(error, "--until");
 		const envelope = buildRetrieveErrorEnvelopeFromResolved(resolved, error);
-		if (prepared) envelope.meta.validation = prepared.validation;
-		else if (attempts === 0)
-			envelope.meta.validation = {
-				enabled: resolved.validate.value,
-				result: "skipped",
-			};
+		const validation =
+			prepared?.validation ??
+			(stoppedBeforeGateAnswer(envelope.error.code) ? settled : undefined);
+		if (validation) envelope.meta.validation = validation;
 		if (envelope.meta.operation) envelope.meta.operation.wait = meta(reason);
 		return envelope;
 	};
@@ -151,6 +154,7 @@ export async function retrieveWait(
 					signal: controller.signal,
 				});
 				prepared ??= await validateRetrieveRead(observationRequest, backend);
+				settled = prepared.validation;
 				if (
 					settings.untilEmpty &&
 					(prepared.inspection?.singleton ??