@tikoci/centrs 0.1.9-next.0 → 0.1.9-next.22

package/src/execute-cmr.ts

@@ -39,9 +39,21 @@
  *   - `freeze-frame-interval=20ms` brings a trivial call from ~1 s to ~25 ms;
  *     `strategy`/`fail-policy` are pinned and `order` is never sent (it adds
  *     `pending` and policy-`skipped` statuses).
+ *   - The caller's policy is not checked against the script (#456):
+ *     `run-script` needs only `read` + `api` on the controller login, and a
+ *     `!write !reboot` login wrote to and rebooted clients, the controller's
+ *     own row included. The write gate here is the only one; a write run by
+ *     such a login carries `cmr/caller-policy-not-enforced`.
  */
 
-import { assertNotCmrDashboardIl, CMR_RUN_SCRIPT_PATH } from "./core/cmr.ts";
+import {
+	assertNotCmrDashboardIl,
+	CMR_RUN_SCRIPT_PATH,
+	CMR_SCRIPT_POLICIES,
+	type CmrCallerPolicy,
+	cmrCallerPolicyWarning,
+	readCmrCallerPolicy,
+} from "./core/cmr.ts";
 import type {
 	CentrsErrorEnvelope,
 	CentrsSuccessEnvelope,
@@ -55,6 +67,7 @@ import type {
 import { notReachedReason } from "./core/envelope.ts";
 import { isWriteShaped } from "./core/execute-command.ts";
 import {
+	buildFanoutEnvelope,
 	NOT_SENT_TRANSPORT_CODES,
 	resolveFanoutConcurrency,
 	runBoundedPool,
@@ -94,7 +107,7 @@ import {
 	type RouterOsProtocol,
 } from "./protocols/index.ts";
 import { classifyParseResult } from "./protocols/mac-telnet-console.ts";
-import { toCoreSource } from "./resolver/index.ts";
+import { redactTargetInput, toCoreSource } from "./resolver/index.ts";
 
 /** The device-stage validator identity for a CMR client. */
 export const CMR_VALIDATION_SOURCE = ":put [:parse ...] via cmr run-script";
@@ -184,6 +197,8 @@ export interface CmrController {
 	devices(): Promise<CmrDevice[]>;
 	/** Explain a missing `/cmr/device`; each read is best effort. */
 	absence?(): Promise<CmrAbsence>;
+	/** The login's own group policy; `undefined` when it cannot be read. */
+	callerPolicy?(): Promise<CmrCallerPolicy | undefined>;
 	runScript(
 		call: CmrScriptCall,
 		signal: AbortSignal,
@@ -204,6 +219,8 @@ export interface ExecuteCmrOperationMeta {
 	concurrency: number;
 	summary: FanoutSummary;
 	request: ExecuteRequestSummary;
+	/** Hoisted from the members: every member runs under the controller login. */
+	auth?: { username?: string; passwordProvided: boolean };
 	cmr: {
 		labels: string;
 		/** `/cmr/device` rows considered. */
@@ -279,6 +296,7 @@ export async function executeCmr(
 	);
 	const nonce = (internals.nonce ?? defaultNonce)();
 
+	const warnings: Warning[] = [...resolved.warnings];
 	try {
 		// 1. Inventory and per-row preflight (membership + client validation).
 		const before = await readInventoryBeforeDispatch(controller, signal);
@@ -332,24 +350,23 @@ export async function executeCmr(
 		before.forEach((device, index) => {
 			const outcome = preflight[index];
 			if (!outcome?.selected || !outcome.row) return;
-			members.push(
-				judgePreflight(
-					device,
-					outcome,
-					resolved,
-					controllerName,
-					offline,
-					nonce,
-				),
-			);
+			members.push(judgePreflight(device, outcome, resolved, offline, nonce));
 		});
-		const warnings: Warning[] = [...resolved.warnings];
 		if (members.length === 0) {
-			warnings.push({
-				code: "cmr/empty-selection",
-				message: `No CMR device on the controller matches \`${labels}\`. Labels are case-sensitive and RouterOS accepts unknown ones silently.`,
-				context: { labels, inventory: before.length },
-			});
+			const message = `No CMR device on the controller matches \`${labels}\`. Labels are case-sensitive and RouterOS accepts unknown ones silently.`;
+			const context = { labels, inventory: before.length };
+			// #460: RouterOS refuses an empty selection (`no devices selected`);
+			// a write here must not exit 0 on a mistyped label.
+			if (write) {
+				throw new CentrsError({
+					code: "cmr/empty-selection",
+					summary: `${message} Nothing ran: a write-shaped command must select at least one client.`,
+					remediation:
+						"Check the labels with `centrs retrieve <controller> /cmr/device` (`labels`, `auto-labels`), then re-run. A read over the same labels succeeds with a warning instead.",
+					context: { ...context, write: true },
+				});
+			}
+			warnings.push({ code: "cmr/empty-selection", message, context });
 		}
 
 		// 2. Bind: a member whose `ids` changed since S1 was validated as another key.
@@ -361,7 +378,6 @@ export async function executeCmr(
 				member.result = memberError(
 					member,
 					resolved,
-					controllerName,
 					notDispatched(
 						"cmr/membership-changed",
 						`CMR device ${member.device.id} (${member.device.identity}) changed or left the inventory between validation and dispatch.`,
@@ -371,9 +387,14 @@ export async function executeCmr(
 			}
 		}
 
-		// 3. One write gate, naming the blast radius.
+		// 3. One write gate, naming the blast radius. The login's policy is read
+		// once, best effort: a failed read only loses the warning.
 		const runnable = members.filter((m) => !m.result);
 		if (write && runnable.length > 0) {
+			const caller = await controller.callerPolicy?.().catch(() => undefined);
+			const notEnforced =
+				caller && cmrCallerPolicyWarning(caller, CMR_SCRIPT_POLICIES);
+			if (notEnforced) warnings.push(notEnforced);
 			await confirmCmrWrite(
 				request,
 				signal,
@@ -381,6 +402,7 @@ export async function executeCmr(
 				controllerName,
 				runnable.length,
 				members.length - runnable.length,
+				notEnforced,
 			);
 		}
 
@@ -427,47 +449,56 @@ export async function executeCmr(
 						? "bound"
 						: "drifted";
 			member.result = applyMemberBudget(
-				judgeDispatch(member, outcome, resolved, controllerName, binding),
+				judgeDispatch(member, outcome, resolved, binding),
 				member,
 				resolved,
-				controllerName,
 			);
 		}
 
 		const targets = members.map(
 			(member) =>
-				member.result ??
-				memberError(member, resolved, controllerName, internalUndecided()),
+				member.result ?? memberError(member, resolved, internalUndecided()),
 		);
 		const summary = summarizeFanout(targets);
-		return {
-			ok: true,
-			data: { summary, targets },
+		return buildFanoutEnvelope<
+			unknown,
+			ExecuteOperationMeta,
+			ExecuteCmrOperationMeta
+		>({
+			summary,
+			targets,
 			warnings,
-			tips: [],
-			meta: {
-				target: controllerTargetMeta(resolved),
-				via,
-				settings: settingsMeta(resolved),
-				operation: {
-					kind: "cmr",
-					concurrency,
-					summary,
-					request: requestSummary(resolved),
-					cmr: {
-						labels,
-						inventory: before.length,
-						selected: members.length,
-						dispatched: sentCount,
-					},
+			settings: settingsMeta(resolved),
+			via,
+			target: controllerTargetMeta(resolved),
+			operation: {
+				kind: "cmr",
+				concurrency,
+				summary,
+				request: requestSummary(resolved),
+				cmr: {
+					labels,
+					inventory: before.length,
+					selected: members.length,
+					dispatched: sentCount,
 				},
 			},
-		};
+		});
+	} catch (error) {
+		// An outer error keeps the warnings gathered before it, such as
+		// `cmr/caller-policy-not-enforced` on a refused confirmation.
+		if (error instanceof CentrsError && warnings.length > 0) {
+			OUTER_ERROR_WARNINGS.set(error, [...warnings]);
+		}
+		throw error;
 	} finally {
 		await controller.close();
 	}
 }
 
+/** Warnings an outer `executeCmr` error carried; read by {@link buildExecuteCmrErrorEnvelope}. */
+const OUTER_ERROR_WARNINGS = new WeakMap<CentrsError, Warning[]>();
+
 // ---------------------------------------------------------------------------
 // Preflight and dispatch judgement
 // ---------------------------------------------------------------------------
@@ -476,7 +507,6 @@ function judgePreflight(
 	device: CmrDevice,
 	outcome: CmrScriptOutcome,
 	resolved: ResolvedExecuteRequest,
-	controllerName: string,
 	offline: OfflineGateResult | undefined,
 	nonce: string,
 ): Member {
@@ -496,7 +526,6 @@ function judgePreflight(
 		member.result = memberError(
 			member,
 			resolved,
-			controllerName,
 			disconnectedError(device, row),
 		);
 		return member;
@@ -510,7 +539,6 @@ function judgePreflight(
 		member.result = memberError(
 			member,
 			resolved,
-			controllerName,
 			notDispatched(
 				"cmr/validation-incomplete",
 				`The validation result from CMR device ${device.identity} was incomplete (${why}), so the command was not sent to it.`,
@@ -540,7 +568,7 @@ function judgePreflight(
 	} catch (error) {
 		const rejected = error as CentrsError;
 		member.validation = deviceRejected(resolved, offline, rejected);
-		member.result = memberError(member, resolved, controllerName, rejected);
+		member.result = memberError(member, resolved, rejected);
 		return member;
 	}
 	// Positive evidence: every accepted `:parse` return seen (structured,
@@ -555,7 +583,6 @@ function judgeDispatch(
 	member: Member,
 	outcome: CmrScriptOutcome,
 	resolved: ResolvedExecuteRequest,
-	controllerName: string,
 	binding: "bound" | "drifted" | "unverified",
 ): ExecuteEnvelope {
 	const device = member.device;
@@ -563,7 +590,6 @@ function judgeDispatch(
 		return memberError(
 			member,
 			resolved,
-			controllerName,
 			notDispatched(
 				"cmr/membership-changed",
 				`CMR device ${device.identity} no longer matched the labels at dispatch, so the command was not sent to it.`,
@@ -573,21 +599,11 @@ function judgeDispatch(
 	}
 	const row = outcome.row;
 	if (!outcome.sent && !(row && FINAL_STATUSES.has(row.status))) {
-		return memberError(
-			member,
-			resolved,
-			controllerName,
-			outcome.error ?? cancelledError(),
-		);
+		return memberError(member, resolved, outcome.error ?? cancelledError());
 	}
 	// CMR itself declined to send: nothing ran, whichever client this was.
 	if (row?.status === "skipped") {
-		return memberError(
-			member,
-			resolved,
-			controllerName,
-			disconnectedError(device, row),
-		);
+		return memberError(member, resolved, disconnectedError(device, row));
 	}
 	// A sent call whose member cannot be re-bound after dispatch (its `ids`
 	// changed, or S3 was not read) has no attributable result.
@@ -595,7 +611,6 @@ function judgeDispatch(
 		return memberError(
 			member,
 			resolved,
-			controllerName,
 			unknownOutcome(
 				device,
 				undefined,
@@ -610,7 +625,6 @@ function judgeDispatch(
 		return memberError(
 			member,
 			resolved,
-			controllerName,
 			unknownOutcome(device, outcome.error, row),
 		);
 	}
@@ -619,7 +633,6 @@ function judgeDispatch(
 			return memberError(
 				member,
 				resolved,
-				controllerName,
 				unknownOutcome(device, undefined, row),
 			);
 		}
@@ -629,7 +642,6 @@ function judgeDispatch(
 			return memberError(
 				member,
 				resolved,
-				controllerName,
 				new CentrsError({
 					code: "cmr/policy-denied",
 					summary: `${device.identity} refused a statement: CMR runs scripts with only the read, write, test and reboot policies (\`${denied[0].trim()}\`). Any statements before it already ran.`,
@@ -646,7 +658,6 @@ function judgeDispatch(
 		return memberError(
 			member,
 			resolved,
-			controllerName,
 			mapRouterOsError(row.output.trim(), {
 				transport:
 					resolved.via.value === "rest-api" ? "rest-api" : "native-api",
@@ -669,7 +680,7 @@ function judgeDispatch(
 		warnings,
 		tips: [],
 		meta: {
-			...memberMeta(member, resolved, controllerName),
+			...memberMeta(member, resolved),
 			...(clipped
 				? {
 						truncated: {
@@ -692,7 +703,6 @@ function applyMemberBudget(
 	envelope: ExecuteEnvelope,
 	member: Member,
 	resolved: ResolvedExecuteRequest,
-	controllerName: string,
 ): ExecuteEnvelope {
 	const budget = resolved.maxResultsBytes?.value;
 	if (!budget || !envelope.ok) return envelope;
@@ -707,7 +717,6 @@ function applyMemberBudget(
 	return memberError(
 		member,
 		resolved,
-		controllerName,
 		new CentrsError({
 			code: "input/max-results-exceeded",
 			summary: `The command ran on ${device.identity}, but its result (${requiredBytes} bytes) exceeded the requested ${budget}-byte budget, so it is not returned.`,
@@ -942,7 +951,6 @@ async function noCmrError(
 function memberError(
 	member: Member,
 	resolved: ResolvedExecuteRequest,
-	controllerName: string,
 	error: CentrsError,
 ): ExecuteEnvelope {
 	return {
@@ -950,21 +958,19 @@ function memberError(
 		error: serializeCentrsError(error),
 		warnings: [],
 		tips: [],
-		meta: memberMeta(member, resolved, controllerName),
+		meta: memberMeta(member, resolved),
 	};
 }
 
 function memberMeta(
 	member: Member,
 	resolved: ResolvedExecuteRequest,
-	controllerName: string,
 ): ExecuteEnvelope["meta"] {
 	const device = member.device;
 	const target: EnvelopeTargetMeta = {
 		input: device.identity,
 		identity: device.identity,
 		cmr: {
-			controller: controllerName,
 			id: device.id,
 			deviceKey: device.ids.split("/")[0] || undefined,
 			address: device.address,
@@ -1106,9 +1112,11 @@ async function confirmCmrWrite(
 	controllerName: string,
 	runnable: number,
 	excluded: number,
+	notEnforced: Warning | undefined,
 ): Promise<void> {
 	if (resolved.yes) return;
 	const scope = `${runnable} CMR client(s) via controller ${controllerName}${excluded > 0 ? ` (${excluded} excluded)` : ""}`;
+	const policyNote = notEnforced ? ` ${notEnforced.message}` : "";
 	if (request.stdinIsTty ?? process.stdin.isTTY) {
 		// The prompt reads stdin and cannot see `signal`, so race it: a cancel at
 		// the prompt returns here and the dispatch loop reports every member
@@ -1119,7 +1127,7 @@ async function confirmCmrWrite(
 		});
 		const confirmed = await Promise.race([
 			(request.confirm ?? promptForWriteConfirmation)(
-				`Run write-shaped \`${resolved.command}\` on ${scope}? Type yes to continue: `,
+				`Run write-shaped \`${resolved.command}\` on ${scope}?${policyNote} Type yes to continue: `,
 			),
 			cancelled,
 		]);
@@ -1127,7 +1135,7 @@ async function confirmCmrWrite(
 	}
 	throw new CentrsError({
 		code: "usage/confirmation-required",
-		summary: `A write-shaped \`${resolved.command}\` would run on ${scope} and needs explicit confirmation.`,
+		summary: `A write-shaped \`${resolved.command}\` would run on ${scope} and needs explicit confirmation.${policyNote}`,
 		remediation:
 			"Pass `--yes` after reviewing the selection, or answer `yes` at the TTY prompt. Clients that failed validation are never sent the command.",
 		context: {
@@ -1135,6 +1143,7 @@ async function confirmCmrWrite(
 			routers: runnable,
 			excluded,
 			controller: controllerName,
+			...(notEnforced ? { callerPolicy: notEnforced.context } : {}),
 		},
 	});
 }
@@ -1205,6 +1214,10 @@ function adapterController(
 				controllerAddress: client?.["controller-address"] || undefined,
 			};
 		},
+		callerPolicy: () =>
+			resolved.auth.username
+				? readCmrCallerPolicy(shared, resolved.auth.username)
+				: Promise.resolve(undefined),
 		close: () => shared.close(),
 	};
 }
@@ -1357,9 +1370,13 @@ export function buildExecuteCmrErrorEnvelope(
 	return {
 		ok: false,
 		error: serializeCentrsError(centrsError),
-		warnings: [],
+		warnings: OUTER_ERROR_WARNINGS.get(centrsError) ?? [],
 		tips: [],
-		meta: { target: { input: request.targetInput }, via, settings: {} },
+		meta: {
+			target: { input: redactTargetInput(request.targetInput) },
+			via,
+			settings: {},
+		},
 	};
 }
 

package/src/execute-fanout.ts

@@ -60,9 +60,11 @@ import {
 } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
+	emptyWriteSelectionError,
 	expandSelection,
 	isDefaultRecordTarget,
 	loadEnvFileDefaults,
+	redactTargetInput,
 	type SelectionExpansion,
 	type SelectionMember,
 	type SelectionResolveInput,
@@ -85,6 +87,8 @@ export interface ExecuteFanoutOperationMeta {
 	concurrency: number;
 	summary: FanoutSummary;
 	request: ExecuteRequestSummary;
+	/** Hoisted from the targets when every target used the same login (#461). */
+	auth?: { username?: string; passwordProvided: boolean };
 	selection: ExecuteSelectionSummary;
 }
 
@@ -125,7 +129,7 @@ function summarizeSelection(
 		where: selection.where.map((clause) => `${clause.key}=${clause.value}`),
 		all: selection.all,
 		default: selection.default,
-		positionals: selection.positionals,
+		positionals: selection.positionals.map((value) => redactTargetInput(value)),
 		quickchr: selection.quickchr,
 	};
 }
@@ -225,6 +229,12 @@ export async function executeFanout(
 	const concurrency = resolveFanoutConcurrency(options.concurrency, via);
 
 	if (expansion.empty) {
+		if (global.summary.write) {
+			throw emptyWriteSelectionError(
+				expansion,
+				`\`${global.summary.command}\``,
+			);
+		}
 		return executeFanoutEnvelope({
 			selection: selectionSummary,
 			concurrency,

package/src/execute.ts

@@ -4,6 +4,13 @@ import {
 	cmrRunScriptWarnings,
 	cmrScriptWarnings,
 } from "./core/cmr.ts";
+import {
+	type CmrFleetRead,
+	cmrFleetCommand,
+	cmrFleetGate,
+	cmrFleetReadable,
+	readCmrFleet,
+} from "./core/cmr-fleet.ts";
 import type {
 	CentrsEnvelope,
 	CentrsErrorEnvelope,
@@ -65,6 +72,7 @@ import {
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
+	redactTargetInput,
 	resolveAuth,
 	resolveBooleanSetting,
 	resolveCdb,
@@ -171,6 +179,8 @@ export interface ResolvedExecuteRequest {
 	yes: boolean;
 	verbose: boolean;
 	warnings: readonly Warning[];
+	/** A CMR fleet command's reach, read before the write gate (#453). */
+	cmrFleet?: CmrFleetRead;
 }
 
 export async function execute(
@@ -202,6 +212,7 @@ export async function executeEnvelope(
 	const trace: ValidationTrace = {};
 	try {
 		resolved = await resolveExecuteRequest(request, env);
+		resolved = await withCmrFleetScope(resolved);
 		await assertWriteConfirmed(request, resolved);
 		return await runResolvedExecute(resolved, trace);
 	} catch (error) {
@@ -573,7 +584,7 @@ export function buildExecuteErrorEnvelope(
 		warnings: [],
 		tips: [],
 		meta: {
-			target: { input: request.targetInput },
+			target: { input: redactTargetInput(request.targetInput) },
 			via: requestedVia,
 			settings: {},
 			operation: {
@@ -798,7 +809,7 @@ export function renderExecuteEnvelope(
 			return toYaml(envelope);
 		case "text":
 			return envelope.ok
-				? renderExecuteSuccessText(envelope, options)
+				? renderExecuteSuccessText(envelope)
 				: formatCentrsErrorText(envelope.error, options);
 		default:
 			return exhaustiveOutputFormat(format);
@@ -1074,9 +1085,13 @@ async function assertWriteConfirmed(
 	if (!isWriteShaped(resolved.canonical) || resolved.yes) {
 		return;
 	}
+	const fleet = resolved.cmrFleet
+		? cmrFleetGate(resolved.cmrFleet, targetName(resolved))
+		: undefined;
 	if (request.stdinIsTty ?? process.stdin.isTTY) {
 		const confirmed = await (request.confirm ?? promptForWriteConfirmation)(
-			`Run write-shaped RouterOS command over ${resolved.via.value}? Type yes to continue: `,
+			fleet?.prompt ??
+				`Run write-shaped RouterOS command over ${resolved.via.value}? Type yes to continue: `,
 		);
 		if (confirmed) {
 			return;
@@ -1085,6 +1100,7 @@ async function assertWriteConfirmed(
 	throw new CentrsError({
 		code: "usage/confirmation-required",
 		summary:
+			fleet?.summary ??
 			"Write-shaped RouterOS execute commands require explicit confirmation.",
 		remediation:
 			"Pass `--yes` in non-interactive automation, or answer `yes` at the TTY prompt after reviewing the command.",
@@ -1093,10 +1109,75 @@ async function assertWriteConfirmed(
 			path: resolved.canonical.path,
 			verb: resolved.canonical.verb,
 			via: resolved.via.value,
+			...fleet?.context,
 		},
 	});
 }
 
+function targetName(resolved: ResolvedExecuteRequest): string {
+	return (
+		resolved.target.identity ?? resolved.target.input ?? resolved.target.host
+	);
+}
+
+/**
+ * #453: a write-shaped CMR fleet command (`/cmr/device/reboot labels=all`) is
+ * one request to the controller that acts on every device it selects. Read
+ * the controller's inventory before the gate so the gate names that reach,
+ * and add the fleet warnings, with or without `--yes`. Structured input only:
+ * a script's selectors (`[find …]`, positionals) are not resolved.
+ */
+async function withCmrFleetScope(
+	resolved: ResolvedExecuteRequest,
+): Promise<ResolvedExecuteRequest> {
+	const { canonical } = resolved;
+	if (canonical.mode !== "structured" || !isWriteShaped(canonical)) {
+		return resolved;
+	}
+	const command = cmrFleetCommand(
+		`${canonical.path}/${canonical.verb}`,
+		canonical.attributes,
+	);
+	if (!command) return resolved;
+	if (!cmrFleetReadable(resolved.via.value)) {
+		return {
+			...resolved,
+			cmrFleet: {
+				scope: {
+					command: command.command,
+					unresolved: `${resolved.via.value} has no structured read`,
+				},
+				warnings: [],
+			},
+		};
+	}
+	const adapter = createProtocolAdapter({
+		protocol: resolved.via.value,
+		host: resolved.target.host,
+		port: resolved.target.port,
+		tls: resolved.target.tls,
+		baseUrl: resolved.target.baseUrl,
+		username: resolved.auth.username,
+		password: resolved.auth.password,
+		timeoutMs: resolved.timeoutMs.value,
+		insecure: resolved.insecure.value,
+	});
+	try {
+		const cmrFleet = await readCmrFleet(
+			command,
+			adapter,
+			resolved.auth.username,
+		);
+		return {
+			...resolved,
+			cmrFleet,
+			warnings: [...resolved.warnings, ...cmrFleet.warnings],
+		};
+	} finally {
+		await adapter.close();
+	}
+}
+
 export async function promptForWriteConfirmation(
 	prompt: string,
 ): Promise<boolean> {
@@ -1450,27 +1531,28 @@ function applyMaxResultsBudget(
 	return envelope;
 }
 
-function renderExecuteSuccessText(
-	envelope: ExecuteSuccessEnvelope,
-	options: { verbose?: boolean },
-): string {
-	const lines: string[] = [];
-	if (options.verbose) {
-		lines.push(
-			`target: ${envelope.meta.target.input ?? envelope.meta.target.host}`,
-		);
-		lines.push(`via: ${envelope.meta.via}`);
-		if (envelope.meta.validation?.source) {
-			lines.push(`validation: ${envelope.meta.validation.source}`);
-		}
-		lines.push("");
-	}
-	if (typeof envelope.data === "string") {
-		lines.push(envelope.data);
-	} else {
-		lines.push(JSON.stringify(envelope.data, null, 2));
+/** Text mode renders only the data; the CLI writes the rest to stderr (#470). */
+function renderExecuteSuccessText(envelope: ExecuteSuccessEnvelope): string {
+	return typeof envelope.data === "string"
+		? envelope.data
+		: JSON.stringify(envelope.data, null, 2);
+}
+
+/**
+ * The `--verbose` header of a text-mode execute result (stderr, #470). A
+ * failure after resolution still names its target; one before has no
+ * transport (`via: null`) and no header.
+ */
+export function executeVerboseLines(envelope: ExecuteEnvelope): string[] {
+	if (envelope.meta.via === null) return [];
+	const lines = [
+		`target: ${envelope.meta.target.input ?? envelope.meta.target.host}`,
+		`via: ${envelope.meta.via}`,
+	];
+	if (envelope.meta.validation?.source) {
+		lines.push(`validation: ${envelope.meta.validation.source}`);
 	}
-	return lines.join("\n");
+	return lines;
 }
 
 function syntaxCause(error: unknown): unknown {