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

package/src/api.ts

@@ -16,6 +16,13 @@
  */
 
 import { assertNotCmrDashboardPath, cmrRunScriptWarnings } from "./core/cmr.ts";
+import {
+	type CmrFleetRead,
+	cmrFleetCommand,
+	cmrFleetGate,
+	cmrFleetReadable,
+	readCmrFleet,
+} from "./core/cmr-fleet.ts";
 import type {
 	CentrsEnvelope,
 	CentrsErrorEnvelope,
@@ -24,6 +31,7 @@ import type {
 	SettingSource as CoreSettingSource,
 	EnvelopeValidationMeta,
 	EnvelopeValidationStage,
+	StreamLineEnvelope,
 	Tip,
 	ValidationTrace,
 	Warning,
@@ -80,6 +88,7 @@ import {
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
+	redactTargetInput,
 	resolveAuth,
 	resolveBooleanSetting,
 	resolveCdb,
@@ -213,19 +222,24 @@ export type ApiStreamStopReason =
 	| "transport-error";
 
 /**
- * Per-line marker on `--stream` NDJSON output: a leading `notice`, one wire
- * reply, or the terminating summary. A `notice` (`data: null`, not counted)
- * comes first only when the request has advice in `tips` — what RouterOS will
- * not report for it — so even a watch that never gets a reply sees it. A frame's `reply` is `re` (a row; `data` is the row) or
- * `empty` (RouterOS `!empty`: zero rows; `data` is `null`). `afterStop` marks a
- * reply that arrived after centrs stopped the stream locally, such as the
- * `!empty` a cancelled listen sends; it is not evidence of an empty table.
+ * Per-line marker on `--stream` NDJSON output: the leading `started`, one wire
+ * reply, or the terminating summary. `started` (`data: null`, not counted)
+ * comes first on every stream that passed its preflight: it carries the full
+ * meta and any advice in `tips` — what RouterOS will not report for the
+ * request — so even a watch that never gets a reply sees both (#473). A frame
+ * carries only its `meta.operation`. Its `reply` is `re` (a row; `data` is the
+ * row) or `empty` (RouterOS `!empty`: zero rows; `data` is `null`), and
+ * `observedAt` is when centrs received it (host clock, ISO 8601; a slow reader
+ * does not move it). `afterStop` marks a reply that arrived after centrs
+ * stopped the stream locally, such as the `!empty` a cancelled listen sends;
+ * it is not evidence of an empty table.
  */
 export type ApiStreamMeta =
-	| { kind: "notice" }
+	| { kind: "started" }
 	| {
 			kind: "frame";
 			index: number;
+			observedAt: string;
 			reply: "re" | "empty";
 			afterStop?: true;
 	  }
@@ -265,6 +279,15 @@ export interface ApiOperationMeta {
 }
 
 export type ApiEnvelope = CentrsEnvelope<unknown, ApiOperationMeta>;
+/** A `--stream` frame line: only its own `meta.operation` (#473). */
+export type ApiStreamFrameEnvelope = StreamLineEnvelope<
+	unknown,
+	Pick<ApiOperationMeta, "kind" | "objectCount"> & {
+		stream: Extract<ApiStreamMeta, { kind: "frame" }>;
+	}
+>;
+/** One `--stream` line: a full envelope (`started`, `summary`, error) or a frame. */
+export type ApiStreamLine = ApiEnvelope | ApiStreamFrameEnvelope;
 export type ApiSuccessEnvelope = CentrsSuccessEnvelope<
 	unknown,
 	ApiOperationMeta
@@ -311,6 +334,8 @@ export interface ResolvedApiRequest {
 	yes: boolean;
 	verbose: boolean;
 	warnings: readonly Warning[];
+	/** A CMR fleet command's reach, read before the write gate (#453). */
+	cmrFleet?: CmrFleetRead;
 }
 
 export async function api(
@@ -342,6 +367,7 @@ export async function apiEnvelope(
 	const trace: ValidationTrace = {};
 	try {
 		resolved = await resolveApiRequest(request, env);
+		resolved = await withCmrFleetScope(resolved);
 		await assertApiWriteConfirmed(request, resolved);
 		return await runResolvedApi(resolved, trace);
 	} catch (error) {
@@ -447,10 +473,11 @@ function apiRouterOsFailureFromResult(
 }
 
 /**
- * The `--stream` path: an async generator yielding one {@link ApiEnvelope} per
- * native reply (`!re` row or `!empty`) to the literal command, then a
- * terminating summary envelope (`data` = {@link ApiStreamSummary}). It never
- * rewrites the command; a `<menu>/listen` endpoint is how to follow changes.
+ * The `--stream` path: an async generator yielding a full-meta `started` line,
+ * one {@link ApiStreamFrameEnvelope} per native reply (`!re` row or `!empty`)
+ * to the literal command, then a terminating summary envelope (`data` =
+ * {@link ApiStreamSummary}). It never rewrites the command; a `<menu>/listen`
+ * endpoint is how to follow changes.
  * Streaming is native-api only — a `rest-api` (or otherwise unresolved)
  * transport yields a single error envelope. `--count`/`--duration` and
  * `externalSignal` (Ctrl-C) bound it. Errors before the first frame
@@ -464,7 +491,7 @@ export async function* apiStream(
 	env: Record<string, string | undefined> = Bun.env,
 	externalSignal?: AbortSignal,
 	onListening?: () => void,
-): AsyncGenerator<ApiEnvelope, void, void> {
+): AsyncGenerator<ApiStreamLine, void, void> {
 	// `apiStream` is inherently the streaming surface, so force `stream` on the
 	// request: otherwise a caller that omits it would resolve `via` to the
 	// rest-api default and be rejected. An explicit `--via rest-api` still
@@ -473,6 +500,7 @@ export async function* apiStream(
 	let resolved: ResolvedApiRequest | undefined;
 	try {
 		resolved = await resolveApiRequest(streamRequest, env);
+		resolved = await withCmrFleetScope(resolved);
 		await assertApiWriteConfirmed(streamRequest, resolved);
 		if (resolved.via.value !== "native-api") {
 			throw new CentrsError({
@@ -497,16 +525,18 @@ async function* streamResolvedApi(
 	request: ResolvedApiRequest,
 	externalSignal?: AbortSignal,
 	onListening?: () => void,
-): AsyncGenerator<ApiEnvelope, void, void> {
+): AsyncGenerator<ApiStreamLine, void, void> {
 	const backend = adapterForResolved(request);
 
 	let resolved = request;
 	let validation: EnvelopeValidationMeta;
+	let validationTips: Tip[] = [];
 	const trace: ValidationTrace = {};
 	try {
 		if (resolved.validate.value) {
 			const result = await validateApiRequest(resolved, backend, trace);
 			validation = result.validation;
+			validationTips = result.tips;
 			// The boolean probe below runs after the gate passed (GH#435).
 			trace.validation = validation;
 			resolved = await withQueryBooleans(resolved, backend, result.queryMenu);
@@ -519,9 +549,27 @@ async function* streamResolvedApi(
 		return;
 	}
 
-	// Request-shape advice is known before the first reply: deliver it first,
-	// and keep it on whichever terminal summary follows (#409 review).
-	const tips = streamTips(resolved);
+	// Request-shape advice is known before the first reply: deliver it on
+	// `started`, and keep it on whichever terminal summary follows (#409 review).
+	// The gate's own tips are the same advice the one-shot path returns.
+	const tips = [...validationTips, ...streamTips(resolved)];
+	// Arrival times in wire order, stamped by the synchronous reply tap: the
+	// session queues replies, so a slow reader must not move them. Read by a
+	// head index, not `shift()`, which is O(n) per frame on a backlog.
+	const arrivals: number[] = [];
+	let arrivalsHead = 0;
+	const nextArrival = (): number => {
+		const at = arrivals[arrivalsHead] ?? Date.now();
+		arrivalsHead += 1;
+		if (arrivalsHead >= arrivals.length) {
+			arrivals.length = 0;
+			arrivalsHead = 0;
+		} else if (arrivalsHead >= 1024 && arrivalsHead * 2 >= arrivals.length) {
+			arrivals.splice(0, arrivalsHead);
+			arrivalsHead = 0;
+		}
+		return at;
+	};
 	const controller = new AbortController();
 	const startedAt = Date.now();
 	const counts = { frames: 0, rows: 0, empty: 0 };
@@ -562,14 +610,17 @@ async function* streamResolvedApi(
 	}
 
 	try {
-		// A consumer may return immediately after this notice; keep it inside
+		// A consumer may return immediately after this line; keep it inside
 		// the session cleanup scope, just like every wire reply.
-		if (tips.length > 0) {
-			yield streamNoticeEnvelope(resolved, validation, tips);
-		}
+		yield streamStartedEnvelope(resolved, validation, tips);
 		const protocolRequest = buildProtocolApiRequest(resolved);
 		for await (const reply of backend.stream(protocolRequest, {
 			signal: controller.signal,
+			onReply: (tapped) => {
+				if (tapped.type === "re" || tapped.type === "empty") {
+					arrivals.push(Date.now());
+				}
+			},
 			onListening: () => {
 				trace.dispatched = true;
 				onListening?.();
@@ -585,7 +636,7 @@ async function* streamResolvedApi(
 			counts.frames += 1;
 			if (reply.type === "empty") counts.empty += 1;
 			else counts.rows += 1;
-			yield streamFrameEnvelope(resolved, validation, reply, counts.frames);
+			yield streamFrameEnvelope(reply, counts.frames, nextArrival());
 			// `--count` counts rows only: an empty tick must never use up the
 			// count before the data it is waiting for arrives.
 			if (
@@ -638,29 +689,39 @@ async function* streamResolvedApi(
 }
 
 function streamFrameEnvelope(
-	resolved: ResolvedApiRequest,
-	validation: EnvelopeValidationMeta,
 	reply: ProtocolStreamReply,
 	index: number,
-): ApiSuccessEnvelope {
+	observedAt: number,
+): ApiStreamFrameEnvelope {
 	const data = reply.type === "empty" ? null : reply.attributes;
-	const meta = metaFromResolved(resolved, validation, data);
-	meta.operation.stream = {
-		kind: "frame",
-		index,
-		reply: reply.type,
-		...(reply.afterStop ? { afterStop: true as const } : {}),
+	return {
+		ok: true,
+		data,
+		warnings: [],
+		tips: [],
+		meta: {
+			operation: {
+				kind: "api",
+				objectCount: countResultObjects(data),
+				stream: {
+					kind: "frame",
+					index,
+					observedAt: new Date(observedAt).toISOString(),
+					reply: reply.type,
+					...(reply.afterStop ? { afterStop: true as const } : {}),
+				},
+			},
+		},
 	};
-	return { ok: true, data, warnings: [], tips: [], meta };
 }
 
-function streamNoticeEnvelope(
+function streamStartedEnvelope(
 	resolved: ResolvedApiRequest,
 	validation: EnvelopeValidationMeta,
 	tips: Tip[],
 ): ApiSuccessEnvelope {
 	const meta = metaFromResolved(resolved, validation, null);
-	meta.operation.stream = { kind: "notice" };
+	meta.operation.stream = { kind: "started" };
 	return { ok: true, data: null, warnings: [], tips, meta };
 }
 
@@ -1092,8 +1153,9 @@ export function mapMethodToVerb(method: ApiMethod): ApiVerb {
 }
 
 /**
- * Read-only **iff** the method is `GET`, or the terminal path verb is
- * `print`/`get`/`listen`. Everything else is a write needing confirmation. Keyed
+ * Read-only **iff** the method is `GET`, the terminal path verb is
+ * `print`/`get`/`listen`, or it is a POST to exactly `/console/inspect`. Everything
+ * else is a write needing confirmation. Keyed
  * on the verb/method, not the wire HTTP method — a `POST …/print` paged read does
  * not prompt; `--listen` never relaxes the gate (a streaming-but-mutating
  * `/system/license/renew` still confirms). See `commands/api/README.md`.
@@ -1102,6 +1164,13 @@ export function isApiMutating(method: ApiMethod, path: string): boolean {
 	if (method === "GET") {
 		return false;
 	}
+	// `/console/inspect` describes the command tree and parses input; it never
+	// runs it, so a POST to it (the only way to pass `request=`) is a read
+	// (#458). POST and the exact path only: PUT/PATCH/DELETE map to
+	// add/set/remove, and an abbreviation stays a write.
+	if (method === "POST" && pathTokens(path).join("/") === "console/inspect") {
+		return false;
+	}
 	const terminal = pathTokens(path).at(-1);
 	if (terminal === "print" || terminal === "get" || terminal === "listen") {
 		return false;
@@ -1505,9 +1574,18 @@ async function assertApiWriteConfirmed(
 	if (!isApiMutating(resolved.method, resolved.path) || resolved.yes) {
 		return;
 	}
+	const fleet = resolved.cmrFleet
+		? cmrFleetGate(
+				resolved.cmrFleet,
+				resolved.target.identity ??
+					resolved.target.input ??
+					resolved.target.host,
+			)
+		: undefined;
 	if (request.stdinIsTty ?? process.stdin.isTTY) {
 		const confirmed = await (request.confirm ?? promptForWriteConfirmation)(
-			`Run mutating ${resolved.method} ${resolved.path} over ${resolved.via.value}? Type yes to continue: `,
+			fleet?.prompt ??
+				`Run mutating ${resolved.method} ${resolved.path} over ${resolved.via.value}? Type yes to continue: `,
 		);
 		if (confirmed) {
 			return;
@@ -1515,7 +1593,9 @@ async function assertApiWriteConfirmed(
 	}
 	throw new CentrsError({
 		code: "usage/confirmation-required",
-		summary: `A mutating ${resolved.method} ${resolved.path} request requires explicit confirmation.`,
+		summary:
+			fleet?.summary ??
+			`A mutating ${resolved.method} ${resolved.path} request requires explicit confirmation.`,
 		remediation:
 			"Pass `--yes` in non-interactive automation, or answer `yes` at the TTY prompt after reviewing the request.",
 		context: {
@@ -1523,10 +1603,61 @@ async function assertApiWriteConfirmed(
 			path: resolved.path,
 			method: resolved.method,
 			via: resolved.via.value,
+			...fleet?.context,
 		},
 	});
 }
 
+/**
+ * #453: a mutating CMR fleet request (`POST /cmr/device/reboot`, `PUT
+ * /cmr/vlan`) 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`. A `PUT`,
+ * `PATCH` or `DELETE` is the menu's `add`, `set` or `remove`; the `*id` is its
+ * `numbers`.
+ */
+async function withCmrFleetScope(
+	resolved: ResolvedApiRequest,
+): Promise<ResolvedApiRequest> {
+	if (resolved.scriptMode || !isApiMutating(resolved.method, resolved.path)) {
+		return resolved;
+	}
+	const command = cmrFleetCommand(
+		resolved.verb === "run"
+			? resolved.path
+			: `${resolved.path}/${resolved.verb}`,
+		resolved.id === undefined
+			? resolved.body
+			: { ...resolved.body, numbers: resolved.id },
+	);
+	if (!command || !cmrFleetReadable(resolved.via.value)) return resolved;
+	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();
+	}
+}
+
 function assertStreamCapability(resolved: ResolvedApiRequest): void {
 	if (!resolved.stream) {
 		return;
@@ -1545,7 +1676,7 @@ function assertStreamCapability(resolved: ResolvedApiRequest): void {
 		summary:
 			"`--stream` yields incremental replies instead of a one-shot `api` result.",
 		remediation:
-			"Consume the stream via `apiStream()` (library) or `centrs api … --stream` (CLI); both yield an NDJSON envelope per reply frame plus a final summary.",
+			"Consume the stream via `apiStream()` (library) or `centrs api … --stream` (CLI); both yield a `started` line, a line per reply frame, then a final summary.",
 		context: { via: resolved.via.value, capability: "stream" },
 	});
 }
@@ -1689,7 +1820,7 @@ export function buildApiErrorEnvelope(
 		warnings: [],
 		tips: [],
 		meta: {
-			target: { input: request.targetInput },
+			target: { input: redactTargetInput(request.targetInput) },
 			via: requestedVia,
 			settings: {},
 			operation: {
@@ -1930,7 +2061,7 @@ export function renderApiEnvelope(
 			return toYaml(envelope);
 		case "text":
 			return envelope.ok
-				? renderApiSuccessText(envelope, options)
+				? renderApiSuccessText(envelope)
 				: formatCentrsErrorText(envelope.error, options);
 		default:
 			return exhaustiveFormat(format);
@@ -1942,11 +2073,12 @@ export function renderApiEnvelope(
  * object per line) for both `json` and `yaml`, and a concise human row for
  * `text`. `yaml` deliberately falls back to NDJSON here — YAML's multi-line
  * document form is incompatible with line-delimited streaming. Unlike
- * {@link renderApiEnvelope} this never pretty-prints — every frame and the
- * summary are one line each, so a consumer can read the stream line by line.
+ * {@link renderApiEnvelope} this never pretty-prints — `started`, every frame
+ * and the summary are one line each, so a consumer can read the stream line
+ * by line. In text, a `started` line without tips renders as an empty string.
  */
 export function renderApiStreamLine(
-	envelope: ApiEnvelope,
+	envelope: ApiStreamLine,
 	format: ApiOutputFormat,
 	options: { raw?: boolean; verbose?: boolean } = {},
 ): string {
@@ -1969,13 +2101,15 @@ export function renderApiStreamLine(
 	return JSON.stringify(envelope);
 }
 
-function renderApiStreamFrameText(envelope: ApiSuccessEnvelope): string {
+function renderApiStreamFrameText(
+	envelope: Exclude<ApiStreamLine, ApiErrorEnvelope>,
+): string {
 	const stream = envelope.meta.operation?.stream;
 	if (stream?.kind === "summary") {
 		const empty = stream.empty > 0 ? `, ${stream.empty} empty` : "";
 		return `— ${stream.stopReason}: ${stream.rows} row(s)${empty} in ${stream.durationMs}ms`;
 	}
-	if (stream?.kind === "notice") {
+	if (stream?.kind === "started") {
 		return envelope.tips
 			.map((tip) => `tip: ${tip.message}${tip.fix ? ` ${tip.fix}` : ""}`)
 			.join("\n");
@@ -2003,24 +2137,24 @@ function rawErrorPayload(
 	return payload;
 }
 
-function renderApiSuccessText(
-	envelope: ApiSuccessEnvelope,
-	options: { verbose?: boolean },
-): string {
-	const lines: string[] = [];
-	if (options.verbose) {
-		lines.push(`via: ${envelope.meta.via}`);
-		if (envelope.meta.validation?.source) {
-			lines.push(`validation: ${envelope.meta.validation.source}`);
-		}
-		lines.push("");
+/** Text mode renders only the data; the CLI writes the rest to stderr (#470). */
+function renderApiSuccessText(envelope: ApiSuccessEnvelope): string {
+	return typeof envelope.data === "string"
+		? envelope.data
+		: JSON.stringify(envelope.data, null, 2);
+}
+
+/**
+ * The `--verbose` header of a text-mode api result (stderr, #470); none for a
+ * failure before resolution (`via: null`).
+ */
+export function apiVerboseLines(envelope: ApiEnvelope): string[] {
+	if (envelope.meta.via === null) return [];
+	const lines = [`via: ${envelope.meta.via}`];
+	if (envelope.meta.validation?.source) {
+		lines.push(`validation: ${envelope.meta.validation.source}`);
 	}
-	lines.push(
-		typeof envelope.data === "string"
-			? envelope.data
-			: JSON.stringify(envelope.data, null, 2),
-	);
-	return lines.join("\n");
+	return lines;
 }
 
 export function validateApiRequestShape(request: ApiRequest): void {
@@ -2115,11 +2249,17 @@ export function apiRequestSummaryFromRequest(
 		validate: summarizedValidate(request),
 		raw: request.raw ?? false,
 		format: resolveErrorFormat(request, env),
-		query: summaryQuery(request),
-		proplist: buildApiProplist(request),
+		// Empty lists are omitted, as in the resolved summary, so a fan-out
+		// target's request compares equal to the outer one (#461).
+		query: nonEmpty(summaryQuery(request)),
+		proplist: nonEmpty(buildApiProplist(request)),
 	};
 }
 
+function nonEmpty(list: string[] | undefined): string[] | undefined {
+	return list && list.length > 0 ? list : undefined;
+}
+
 /** {@link buildApiQuery} for an error summary, which must not throw on the expression it reports. */
 function summaryQuery(request: ApiRequest): string[] | undefined {
 	try {

package/src/btest.ts

@@ -37,7 +37,12 @@ import {
 	handleBtestServerConnection,
 	runBtestClientSession,
 } from "./protocols/btest-session.ts";
-import { resolveAuth, resolveCdb, resolveTarget } from "./resolver/index.ts";
+import {
+	redactTargetInput,
+	resolveAuth,
+	resolveCdb,
+	resolveTarget,
+} from "./resolver/index.ts";
 
 export { BTEST_PORT, BTEST_UDP_PORT_START };
 
@@ -424,7 +429,7 @@ function buildClientErrorEnvelope(
 			target: {
 				...(request.host !== undefined ? { host: request.host } : {}),
 				...(request.targetInput !== undefined
-					? { input: request.targetInput }
+					? { input: redactTargetInput(request.targetInput) }
 					: {}),
 				port: operation.controlPort,
 			},

package/src/cli/api.ts

@@ -4,6 +4,7 @@ import {
 	apiEnvelope,
 	apiOutputFormats,
 	apiStream,
+	apiVerboseLines,
 	buildApiErrorEnvelope,
 	normalizeApiEndpoint,
 	removedListenError,
@@ -26,6 +27,8 @@ import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
+	printTextHeader,
+	printTextNotes,
 	renderCommandHelp,
 	unknownFlagError,
 } from "./common.ts";
@@ -106,7 +109,7 @@ export const apiCommand: CliCommandMetadata = {
 		{
 			flag: "--stream",
 			description:
-				"Stream the command's native replies (`!re` rows and `!empty`) as NDJSON, then a summary envelope. Never changes the command: a GET streams one print. To follow changes, request `<menu>/listen`, which implies it.",
+				"Stream the command's native replies (`!re` rows and `!empty`) as NDJSON: a `started` line, a line per reply, then a summary envelope. Never changes the command: a GET streams one print. To follow changes, request `<menu>/listen`, which implies it.",
 		},
 		{
 			flag: "--count",
@@ -190,7 +193,7 @@ export const apiCommand: CliCommandMetadata = {
 		},
 		{
 			flag: "--verbose",
-			description: "Include additional context in text output.",
+			description: "Include additional context in text output, on stderr.",
 		},
 	],
 };
@@ -542,16 +545,22 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 			)?.request?.format ??
 			parsed.format ??
 			"json";
+		// `--raw` is a bare payload by contract; `--json` carries the notes.
+		const text = resolvedFormat === "text" && !parsed.raw;
+		if (text && parsed.verbose) {
+			printTextHeader(apiVerboseLines(envelope));
+		}
 		const rendered = renderApiEnvelope(envelope, resolvedFormat, {
 			raw: parsed.raw,
 			verbose: parsed.verbose,
 		});
 		if (envelope.ok) {
 			console.log(rendered);
-			return 0;
+		} else {
+			console.error(rendered);
 		}
-		console.error(rendered);
-		return 1;
+		if (text) printTextNotes(envelope);
+		return envelope.ok ? 0 : 1;
 	} catch (error) {
 		const format = inferApiFormat(args, parsed);
 		const tips = isMissingTargetError(error)
@@ -566,7 +575,6 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 			// missing `--input` file) instead of falling back to plain text.
 			const envelope = withTips(buildApiErrorEnvelope(parsed, error), tips);
 			console.error(
-				// codeql[js/clear-text-logging] CLI catch-block error render. No secret logged: envelope stores only passwordProvided (boolean) and target.input (router, not the password).
 				renderApiEnvelope(envelope, format, {
 					raw: true,
 					verbose: parsed.verbose ?? false,
@@ -578,14 +586,12 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 				tips,
 			);
 			console.error(
-				// codeql[js/clear-text-logging] CLI catch-block error render. No secret logged: envelope stores only passwordProvided (boolean) and target.input (router, not the password).
 				renderApiEnvelope(envelope, format, {
 					verbose: parsed?.verbose ?? false,
 				}),
 			);
 		} else {
 			console.error(
-				// codeql[js/clear-text-logging] CLI catch-block error render. No secret logged: envelope stores only passwordProvided (boolean) and target.input (router, not the password).
 				formatCentrsErrorText(
 					asCentrsError(error, {
 						code: "input/invalid-command",
@@ -659,7 +665,6 @@ async function runApiFanoutCli(
 			Bun.env,
 		);
 		console.error(
-			// codeql[js/clear-text-logging] Fan-out CLI catch-block error render — twin of #80/#81. No secret logged: the error envelope's request summary, selection and target carry no auth fields; serializeCentrsError holds only code/summary/remediation/context.
 			renderApiFanoutEnvelope(envelope, format, {
 				verbose: parsed.verbose ?? false,
 			}),
@@ -679,8 +684,9 @@ function endpointInfersListen(endpoint: string): boolean {
 
 /**
  * Emit all structured stream outcomes on stdout. Any failure sets exit 1,
- * including a terminal error after successful rows. Raw mode retains its
- * stderr error contract; Ctrl-C requests bounded cancellation.
+ * including a terminal error after successful rows. Text puts only frame rows
+ * on stdout; raw mode retains its stderr error contract; Ctrl-C requests
+ * bounded cancellation.
  */
 async function runApiStreamCli(
 	parsed: ApiCliArgs,
@@ -697,17 +703,25 @@ async function runApiStreamCli(
 			Bun.env,
 			controller.signal,
 		)) {
-			// `--raw` is bare payloads only; a notice has none.
-			if (parsed.raw && envelope.meta.operation?.stream?.kind === "notice")
-				continue;
+			const kind = envelope.ok
+				? envelope.meta.operation?.stream?.kind
+				: undefined;
+			// `--raw` is bare payloads only; `started` has none.
+			if (parsed.raw && kind === "started") continue;
 			const line = renderApiStreamLine(envelope, format, {
 				raw: parsed.raw,
 				verbose: parsed.verbose,
 			});
-			if (envelope.ok || !parsed.raw) {
+			if (parsed.raw) {
+				if (envelope.ok) console.log(line);
+				else console.error(line);
+			} else if (format !== "text" || kind === "frame") {
 				console.log(line);
 			} else {
-				console.error(line);
+				// Text stdout is data (#470, #473): status lines, tips, warnings
+				// and errors go to stderr. `started` renders its own tips.
+				if (line) console.error(line);
+				printTextNotes({ warnings: envelope.warnings, tips: [] });
 			}
 			if (!envelope.ok) exitCode = 1;
 		}