@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/cli/eval.ts

@@ -2,10 +2,10 @@ import { resolve } from "node:path";
 import { InvalidIdError } from "../core/safe-id.js";
 import { clioDataDir } from "../core/xdg.js";
 import { loadEvalArtifactV4, writeEvalArtifactV4 } from "../domains/eval/artifacts/store.js";
-import { compareEvalArtifactsV4, renderEvalComparisonV4 } from "../domains/eval/compare/compare.js";
-import { evaluateGate, renderGateFailure } from "../domains/eval/compare/gates.js";
+import { compareEvalArtifactsV4 } from "../domains/eval/compare/compare.js";
+import { evaluateGate, renderGateFailure, renderInformationalBudget } from "../domains/eval/compare/gates.js";
 import { loadThresholds } from "../domains/eval/compare/thresholds.js";
-
+import { type EvalComparisonReportFormat, renderEvalComparisonReportV1 } from "../domains/eval/reports/comparison.js";
 import { renderEvalJsonReportV4 } from "../domains/eval/reports/json.js";
 import { renderEvalJunitReportV4 } from "../domains/eval/reports/junit.js";
 import { renderEvalMarkdownReportV4 } from "../domains/eval/reports/markdown.js";
@@ -22,11 +22,18 @@ const HELP = `clio-coder eval <command>
 
 Commands:
   clio-coder eval validate --suite <suite.yaml>
-  clio-coder eval run --suite <suite.yaml> [--target <id>] [--model <id>] [--out <path>] [--clio-coder-entry <path>]
-  clio-coder eval run --task-file <tasks.yaml> [--repeat <n>] [--out <path>] [--clio-coder-entry <path>]
+	  clio-coder eval run --suite <suite.yaml> [--trials <n>] [--target <id>] [--model <id>] [--out <path>] [--clio-coder-entry <path>]
+	  clio-coder eval run --task-file <tasks.yaml> [--repeat <n>] [--out <path>] [--clio-coder-entry <path>]
   clio-coder eval report <evalId> --format text|json|md|swe-jsonl|junit
-  clio-coder eval compare <baselineEvalId> <candidateEvalId>
+	  clio-coder eval compare <baselineEvalId> <candidateEvalId> [--metric <name>] [--format text|json|md|junit] [--allow-config-drift]
   clio-coder eval gate <candidateEvalId> --baseline <baselineEvalId> [--thresholds <file>]
+  clio-coder eval inventory --json
+
+inventory is the fixed machine-readable read a GUI host may run. Unlike report
+and compare it names no eval id, so the process it starts cannot be steered to a
+different report or a wider window. It carries each stored report's identity,
+provenance, serving facts, accounting, and per-scenario outcomes, and none of
+the runner attachments a report holds.
 `;
 
 type EvalCommand = "validate" | "run" | "report" | "compare" | "gate";
@@ -37,6 +44,7 @@ interface ParsedEvalArgs {
 	suite?: string;
 	taskFile?: string;
 	repeat: number;
+	trials?: number;
 	target?: string;
 	model?: string;
 	out?: string;
@@ -44,13 +52,21 @@ interface ParsedEvalArgs {
 	evalId?: string;
 	format: EvalReportFormat;
 	compareIds: string[];
+	metric?: string;
+	allowConfigDrift: boolean;
 	baseline?: string;
 	thresholds?: string;
 	help: boolean;
 }
 
 function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
-	const parsed: ParsedEvalArgs = { repeat: 1, compareIds: [], format: "text", help: false };
+	const parsed: ParsedEvalArgs = {
+		repeat: 1,
+		compareIds: [],
+		format: "text",
+		allowConfigDrift: false,
+		help: false,
+	};
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === undefined) continue;
@@ -110,6 +126,11 @@ function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
 				index += 1;
 				continue;
 			}
+			if (arg === "--trials") {
+				parsed.trials = positiveInteger(requiredValue(args, index, "--trials"), "--trials");
+				index += 1;
+				continue;
+			}
 			throw new Error(`unknown eval run argument: ${arg}`);
 		}
 		if (parsed.command === "report") {
@@ -125,6 +146,20 @@ function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
 			throw new Error(`unexpected eval report argument: ${arg}`);
 		}
 		if (parsed.command === "compare") {
+			if (arg === "--format") {
+				parsed.format = comparisonFormat(requiredValue(args, index, "--format"));
+				index += 1;
+				continue;
+			}
+			if (arg === "--metric") {
+				parsed.metric = requiredValue(args, index, "--metric");
+				index += 1;
+				continue;
+			}
+			if (arg === "--allow-config-drift") {
+				parsed.allowConfigDrift = true;
+				continue;
+			}
 			if (!arg.startsWith("-")) {
 				parsed.compareIds.push(arg);
 				continue;
@@ -166,6 +201,12 @@ function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
 }
 
 export async function runEvalCommand(args: ReadonlyArray<string>): Promise<number> {
+	// Routed before the shared parser so the fixed read stays exactly fixed: no
+	// eval flag can reach it, and no flag it does not name can be spent on it.
+	if (args[0] === "inventory") {
+		const { runEvalInventory } = await import("./eval-inventory.js");
+		return runEvalInventory(args.slice(1));
+	}
 	let parsed: ParsedEvalArgs;
 	try {
 		parsed = parseEvalArgs(args);
@@ -202,15 +243,21 @@ async function runEvalRun(parsed: ParsedEvalArgs): Promise<number> {
 		const loaded =
 			parsed.suite !== undefined
 				? await loadEvalSuiteFile(parsed.suite)
-				: await loadV1TaskFileAsSuite(parsed.taskFile ?? "", parsed.repeat);
+				: await loadV1TaskFileAsSuite(parsed.taskFile ?? "", parsed.trials ?? parsed.repeat);
 		const resolveOptions: { target?: string; model?: string } = {};
 		if (parsed.target !== undefined) resolveOptions.target = parsed.target;
 		if (parsed.model !== undefined) resolveOptions.model = parsed.model;
-		const suite = resolveSuiteForRun(loaded.suite, resolveOptions);
+		const suite = resolveSuiteForRun(loaded.suite, {
+			...resolveOptions,
+			...(parsed.trials ? { trials: parsed.trials } : {}),
+		});
 		// Runner commands execute with cwd inside prepared eval workspaces, so a
 		// relative --clio-coder-entry must be pinned to the invoking directory here.
 		const clioEntry = resolve(parsed.clioEntry ?? process.argv[1] ?? "dist/cli/index.js");
-		const artifact = await runEvalSuiteV2({ ...loaded, suite }, { clioEntry });
+		const artifact = await runEvalSuiteV2(
+			{ ...loaded, suite },
+			{ clioEntry, freshWorkspaces: parsed.trials !== undefined },
+		);
 		const artifactPath = await writeEvalArtifactV4(clioDataDir(), artifact, parsed.out);
 		process.stdout.write(`${renderEvalTextReportV4(artifact)}artifact: ${artifactPath}\n`);
 		// A suite that declares thresholds is gated by them here, on the artifact
@@ -221,6 +268,10 @@ async function runEvalRun(parsed: ParsedEvalArgs): Promise<number> {
 			process.stdout.write(`gate: fail (${gate.failures.length} threshold failure)\n`);
 			for (const failure of gate.failures) process.stdout.write(renderGateFailure(failure));
 		}
+		if (gate !== null && gate.informational.length > 0) {
+			process.stdout.write(`informational budgets: ${gate.informational.length} notice\n`);
+			for (const finding of gate.informational) process.stdout.write(renderInformationalBudget(finding));
+		}
 		return artifact.summary.failed === 0 && (gate === null || gate.pass) ? 0 : 1;
 	} catch (error) {
 		return handleEvalLoadError(error, 1);
@@ -246,8 +297,12 @@ async function runEvalCompareCommand(parsed: ParsedEvalArgs): Promise<number> {
 		const dataDir = clioDataDir();
 		const baseline = await loadEvalArtifactV4(dataDir, baselineEvalId);
 		const candidate = await loadEvalArtifactV4(dataDir, candidateEvalId);
-		process.stdout.write(renderEvalComparisonV4(compareEvalArtifactsV4(baseline, candidate)));
-		return 0;
+		const summary = compareEvalArtifactsV4(baseline, candidate, {
+			allowConfigDrift: parsed.allowConfigDrift,
+			...(parsed.metric === undefined ? {} : { metric: parsed.metric }),
+		});
+		process.stdout.write(renderEvalComparisonReportV1(summary, parsed.format as EvalComparisonReportFormat));
+		return summary.hardGate.pass ? 0 : 1;
 	} catch (error) {
 		printError(error instanceof Error ? error.message : String(error));
 		return error instanceof InvalidIdError ? 2 : 1;
@@ -258,18 +313,35 @@ async function runEvalGateCommand(parsed: ParsedEvalArgs): Promise<number> {
 	try {
 		const dataDir = clioDataDir();
 		const candidate = await loadEvalArtifactV4(dataDir, parsed.evalId ?? "");
-		await loadEvalArtifactV4(dataDir, parsed.baseline ?? "");
+		const baseline = await loadEvalArtifactV4(dataDir, parsed.baseline ?? "");
 		const thresholds =
 			parsed.thresholds === undefined
-				? { fail: [{ metric: "result.pass", op: "eq" as const, value: false }] }
+				? { fail: [{ metric: "result.pass", op: "eq" as const, value: false }], informational: [] }
 				: loadThresholds(parsed.thresholds);
 		const gate = evaluateGate(candidate, thresholds);
-		if (gate.pass) {
+		const comparison = compareEvalArtifactsV4(baseline, candidate);
+		if (gate.informational.length > 0) {
+			process.stdout.write(`informational budgets: ${gate.informational.length} notice\n`);
+			for (const finding of gate.informational) process.stdout.write(renderInformationalBudget(finding));
+		}
+		if (gate.pass && comparison.hardGate.pass) {
 			process.stdout.write("gate: pass\n");
 			return 0;
 		}
-		process.stdout.write(`gate: fail (${gate.failures.length} threshold failure)\n`);
+		const failureCount =
+			gate.failures.length + comparison.hardGate.failures.length + comparison.hardGate.envelopeFailures.length;
+		process.stdout.write(`gate: fail (${failureCount} hard failure)\n`);
 		for (const failure of gate.failures) process.stdout.write(renderGateFailure(failure));
+		for (const failure of comparison.hardGate.failures) {
+			process.stdout.write(
+				`  ${failure.metric} [${failure.scenarioId}:${failure.role}:${failure.target.id}/${failure.target.model ?? "none"}]: ${failure.change} (hard behavioral gate)\n`,
+			);
+		}
+		for (const failure of comparison.hardGate.envelopeFailures) {
+			process.stdout.write(
+				`  execution envelope [${failure.scenarioId}:${failure.role}:${failure.target.id}/${failure.target.model ?? "none"}]: incomparable fields ${failure.fields.join(", ")}\n`,
+			);
+		}
 		return 1;
 	} catch (error) {
 		printError(error instanceof Error ? error.message : String(error));
@@ -313,3 +385,8 @@ function reportFormat(value: string): EvalReportFormat {
 	if (value === "text" || value === "json" || value === "md" || value === "swe-jsonl" || value === "junit") return value;
 	throw new Error("--format must be text, json, md, swe-jsonl, or junit");
 }
+
+function comparisonFormat(value: string): EvalComparisonReportFormat {
+	if (value === "text" || value === "json" || value === "md" || value === "junit") return value;
+	throw new Error("eval compare --format must be text, json, md, or junit");
+}

package/src/cli/evidence-detail.ts

@@ -0,0 +1,88 @@
+/**
+ * Fixed machine-readable projection of one evidence bundle's trust record.
+ *
+ * `evidence inspect <id>` prints an operator record that quotes the task text,
+ * the bundle's file list, and per-finding prose. This is the same bundle read
+ * down to the one thing a GUI can carry safely and usefully: which runs the
+ * bundle covers, what verdict each run earned, and which axis produced it.
+ *
+ * Every value here comes from a closed vocabulary. The axis names, the axis
+ * states, and the verdicts are all enumerations the harness owns, so there is
+ * no free-form text on this surface at all, which is what lets it answer the
+ * question the inventory raises without reopening the boundary the inventory
+ * closed.
+ *
+ * Unlike the other fixed reads this one takes an identifier, because an
+ * operator names the bundle. The GUI host may only pass back an id it served
+ * inside its current bounded window; see `apps/workbench/artifact-allowlist.ts`.
+ */
+
+import { clioDataDir } from "../core/xdg.js";
+import {
+	inspectEvidence,
+	TRUST_STATUS_AXES,
+	type TrustStatusAxis,
+	type TrustVerdict,
+	trustVerdict,
+} from "../domains/evidence/index.js";
+
+export const EVIDENCE_DETAIL_MAX_RUNS = 16;
+
+export interface EvidenceDetailRun {
+	readonly runId: string;
+	readonly verdict: TrustVerdict;
+	/** Every axis, always all six, so an absent axis is stated rather than missing. */
+	readonly axes: Readonly<Record<TrustStatusAxis, string>>;
+}
+
+export interface EvidenceDetailSnapshot {
+	readonly version: 1;
+	readonly generatedAt: string;
+	readonly evidenceId: string;
+	readonly sourceKind: "run" | "session" | "eval";
+	/** False when the bundle predates the canonical trust projection. */
+	readonly canonical: boolean;
+	readonly runs: readonly EvidenceDetailRun[];
+	readonly runsTruncated: boolean;
+}
+
+export async function evidenceDetailSnapshot(
+	evidenceId: string,
+	now: () => number = Date.now,
+	dataDir: string = clioDataDir(),
+): Promise<EvidenceDetailSnapshot> {
+	const inspected = await inspectEvidence(dataDir, evidenceId);
+	const all = inspected.trustStatus.runs;
+	const window = all.slice(0, EVIDENCE_DETAIL_MAX_RUNS);
+	return {
+		version: 1,
+		generatedAt: new Date(now()).toISOString(),
+		evidenceId: inspected.overview.evidenceId,
+		sourceKind: inspected.overview.source.kind,
+		canonical: inspected.trustStatus.projection === "canonical",
+		runs: window.map(
+			(run): EvidenceDetailRun => ({
+				runId: run.runId,
+				verdict: trustVerdict(run.status),
+				axes: Object.fromEntries(TRUST_STATUS_AXES.map((axis) => [axis, run.status[axis].state])) as Record<
+					TrustStatusAxis,
+					string
+				>,
+			}),
+		),
+		runsTruncated: all.length > window.length,
+	};
+}
+
+/**
+ * `clio-coder evidence inspect <id> --json`.
+ *
+ * The id is the only argument, and the caller supplies it. A GUI host is bound
+ * by its own allowlist rather than by this command, because an operator typing
+ * an id at a terminal is naming something on their own machine, which is a
+ * different act from a browser frame naming it.
+ */
+export async function runEvidenceDetail(evidenceId: string): Promise<number> {
+	process.stdout.write(`${JSON.stringify(await evidenceDetailSnapshot(evidenceId), null, 2)}\n`);
+	return 0;
+}

package/src/cli/evidence-inventory.ts

@@ -0,0 +1,183 @@
+/**
+ * Fixed machine-readable projection of recent evidence artifacts.
+ *
+ * `evidence list` is an operator table and `evidence inspect <id>` needs an id,
+ * so neither is a transport a GUI host can invoke blind. This command accepts
+ * no identifier, path, or limit, selects a bounded newest-first window itself,
+ * and emits provenance, tags, totals, and a trust verdict.
+ *
+ * An overview carries the working directories the runs executed in, the task
+ * text the operator typed, and the file names inside the bundle. None of that
+ * appears here. What does is the shape of the artifact and how far it can be
+ * trusted, which is what an operator picks a bundle by.
+ */
+
+import { clioDataDir } from "../core/xdg.js";
+import {
+	EVIDENCE_TAGS,
+	type EvidenceOverview,
+	type EvidenceTag,
+	listEvidenceOverviews,
+	loadEvidenceTrustStatus,
+	type TrustVerdict,
+	trustVerdict,
+} from "../domains/evidence/index.js";
+import { sanitizeCallTargetText } from "../domains/safety/call-target.js";
+import { truncateToWidth } from "../engine/tui-primitives.js";
+
+export const EVIDENCE_INVENTORY_MAX_ARTIFACTS = 12;
+export const EVIDENCE_INVENTORY_MAX_IDS = 8;
+
+const IDENTITY_WIDTH = 128;
+
+/**
+ * Worst verdict first.
+ *
+ * An artifact covering several runs is only as trustworthy as its weakest run,
+ * so the fold takes the worst rather than the newest or the most common. A
+ * `compromised` run inside an otherwise clean bundle is the fact the operator
+ * needs, and averaging it away would be the one summary worth not printing.
+ */
+const VERDICT_SEVERITY: ReadonlyArray<TrustVerdict> = ["compromised", "unverified", "unknown", "grounded", "reviewed"];
+
+export interface EvidenceInventoryArtifact {
+	readonly evidenceId: string;
+	readonly sourceKind: "run" | "session" | "eval";
+	readonly generatedAt: string;
+	readonly startedAt: string | null;
+	readonly endedAt: string | null;
+	readonly runIds: readonly string[];
+	readonly runIdsTruncated: boolean;
+	readonly agentIds: readonly string[];
+	readonly statuses: readonly string[];
+	readonly tags: readonly EvidenceTag[];
+	readonly totals: Readonly<{
+		runs: number;
+		receipts: number;
+		toolCalls: number;
+		toolErrors: number;
+		blockedToolCalls: number;
+		protectedArtifacts: number;
+		tokens: number;
+		costUsd: number;
+		wallTimeMs: number;
+	}>;
+	/** Secret-shaped values the builder replaced across the bundle's exports. */
+	readonly redactionCount: number;
+	readonly trust: Readonly<{
+		verdict: TrustVerdict;
+		/** Runs whose canonical trust status the bundle actually recorded. */
+		runsCovered: number;
+		/** True when the bundle predates the canonical trust projection. */
+		historical: boolean;
+	}>;
+}
+
+export interface EvidenceInventorySnapshot {
+	readonly version: 1;
+	readonly generatedAt: string;
+	readonly artifacts: readonly EvidenceInventoryArtifact[];
+	readonly truncated: boolean;
+}
+
+function bounded(value: string, width: number): string {
+	const sanitized = sanitizeCallTargetText(value);
+	if (sanitized.length === 0) return "unavailable";
+	return sanitizeCallTargetText(truncateToWidth(sanitized, width, "…", false));
+}
+
+/** Distinct, sanitized, bounded, in first-seen order. */
+function identities(values: ReadonlyArray<string>): string[] {
+	const seen: string[] = [];
+	for (const value of values) {
+		const text = bounded(value, IDENTITY_WIDTH);
+		if (!seen.includes(text)) seen.push(text);
+		if (seen.length >= EVIDENCE_INVENTORY_MAX_IDS) break;
+	}
+	return seen;
+}
+
+function tally(value: number | undefined): number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.trunc(value) : 0;
+}
+
+function amount(value: number | undefined): number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+/** Newest generation first. An unparseable stamp sorts oldest rather than throwing. */
+function byNewest(a: EvidenceOverview, b: EvidenceOverview): number {
+	return (Date.parse(b.generatedAt) || 0) - (Date.parse(a.generatedAt) || 0);
+}
+
+export async function evidenceInventorySnapshot(
+	now: () => number = Date.now,
+	dataDir: string = clioDataDir(),
+): Promise<EvidenceInventorySnapshot> {
+	const all = (await listEvidenceOverviews(dataDir)).sort(byNewest);
+	const window = all.slice(0, EVIDENCE_INVENTORY_MAX_ARTIFACTS);
+	const artifacts: EvidenceInventoryArtifact[] = [];
+	for (const overview of window) {
+		// One unreadable trust file costs that artifact its verdict, never the
+		// whole inventory: the bundle itself is still the thing being listed.
+		let verdict: TrustVerdict = "unknown";
+		let runsCovered = 0;
+		let historical = true;
+		try {
+			const status = await loadEvidenceTrustStatus(dataDir, overview.evidenceId);
+			historical = status.projection !== "canonical";
+			runsCovered = status.runs.length;
+			const verdicts = status.runs.map((run) => trustVerdict(run.status));
+			verdict = VERDICT_SEVERITY.find((candidate) => verdicts.includes(candidate)) ?? "unknown";
+		} catch {
+			verdict = "unknown";
+		}
+		artifacts.push({
+			evidenceId: bounded(overview.evidenceId, IDENTITY_WIDTH),
+			sourceKind: overview.source.kind,
+			generatedAt: overview.generatedAt,
+			startedAt: overview.startedAt,
+			endedAt: overview.endedAt,
+			runIds: identities(overview.runIds),
+			runIdsTruncated: overview.runIds.length > EVIDENCE_INVENTORY_MAX_IDS,
+			agentIds: identities(overview.agentIds),
+			statuses: identities(overview.statuses),
+			tags: overview.tags.filter((tag) => EVIDENCE_TAGS.includes(tag)),
+			totals: {
+				runs: tally(overview.totals.runs),
+				receipts: tally(overview.totals.receipts),
+				toolCalls: tally(overview.totals.toolCalls),
+				toolErrors: tally(overview.totals.toolErrors),
+				blockedToolCalls: tally(overview.totals.blockedToolCalls),
+				protectedArtifacts: tally(overview.totals.protectedArtifacts),
+				tokens: tally(overview.totals.tokens),
+				costUsd: amount(overview.totals.costUsd),
+				wallTimeMs: tally(overview.totals.wallTimeMs),
+			},
+			redactionCount: tally(overview.redactionCount),
+			trust: { verdict, runsCovered, historical },
+		});
+	}
+	return {
+		version: 1,
+		generatedAt: new Date(now()).toISOString(),
+		artifacts,
+		truncated: all.length > window.length,
+	};
+}
+
+/**
+ * `clio-coder evidence inventory --json`, and nothing else.
+ *
+ * `fixed` is false as soon as the caller supplied an id or any other argument.
+ * A GUI host invokes this knowing the process it started cannot be steered into
+ * reading a different bundle or a wider window.
+ */
+export async function runEvidenceInventory(fixed: boolean): Promise<number> {
+	if (!fixed) {
+		process.stderr.write("clio-coder evidence inventory: usage: clio-coder evidence inventory --json\n");
+		return 2;
+	}
+	process.stdout.write(`${JSON.stringify(await evidenceInventorySnapshot(), null, 2)}\n`);
+	return 0;
+}

package/src/cli/evidence.ts

@@ -12,21 +12,25 @@ import {
 	loadEvidenceRunProvenance,
 	provenanceTranscriptLines,
 } from "../domains/evidence/index.js";
+import { runEvidenceDetail } from "./evidence-detail.js";
+import { runEvidenceInventory } from "./evidence-inventory.js";
 import { printError, printNote, printOk } from "./shared.js";
 
 const HELP = `clio-coder evidence build --run <runId>
 clio-coder evidence build --session <sessionId>
 clio-coder evidence build --eval <evalId>
-clio-coder evidence inspect <evidenceId>
+clio-coder evidence inspect <evidenceId> [--json]
 clio-coder evidence list
+clio-coder evidence inventory --json
 
 Build or inspect deterministic Clio evidence artifacts.
 `;
 
-type EvidenceCommand = "build" | "inspect" | "list";
+type EvidenceCommand = "build" | "inspect" | "list" | "inventory";
 
 interface ParsedEvidenceArgs {
 	command?: EvidenceCommand;
+	json: boolean;
 	runId?: string;
 	sessionId?: string;
 	evalId?: string;
@@ -35,7 +39,7 @@ interface ParsedEvidenceArgs {
 }
 
 function parseEvidenceArgs(args: ReadonlyArray<string>): ParsedEvidenceArgs {
-	const parsed: ParsedEvidenceArgs = { help: false };
+	const parsed: ParsedEvidenceArgs = { help: false, json: false };
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === undefined) continue;
@@ -44,12 +48,22 @@ function parseEvidenceArgs(args: ReadonlyArray<string>): ParsedEvidenceArgs {
 			continue;
 		}
 		if (parsed.command === undefined) {
-			if (arg === "build" || arg === "inspect" || arg === "list") {
+			if (arg === "build" || arg === "inspect" || arg === "list" || arg === "inventory") {
 				parsed.command = arg;
 				continue;
 			}
 			throw new Error(`unknown evidence command: ${arg}`);
 		}
+		// `inventory` is the fixed read a GUI host may invoke. Its argv is not a
+		// surface, so anything past the one required flag is a usage error rather
+		// than something to ignore.
+		if (parsed.command === "inventory") {
+			if (arg === "--json" && !parsed.json) {
+				parsed.json = true;
+				continue;
+			}
+			throw new Error("inventory accepts only --json");
+		}
 		if (parsed.command === "build") {
 			if (arg === "--run") {
 				const value = args[index + 1];
@@ -74,6 +88,10 @@ function parseEvidenceArgs(args: ReadonlyArray<string>): ParsedEvidenceArgs {
 			}
 			throw new Error(`unknown evidence build argument: ${arg}`);
 		}
+		if (parsed.command === "inspect" && arg === "--json" && !parsed.json) {
+			parsed.json = true;
+			continue;
+		}
 		if (parsed.command === "inspect" && parsed.evidenceId === undefined) {
 			if (arg.startsWith("-")) throw new Error("inspect requires an evidence id");
 			parsed.evidenceId = arg;
@@ -103,6 +121,11 @@ function parseEvidenceArgs(args: ReadonlyArray<string>): ParsedEvidenceArgs {
 	) {
 		throw new Error("list does not accept extra arguments");
 	}
+	// The GUI read is only fixed if `--json` is required rather than defaulted:
+	// a bare `evidence inventory` must not quietly print something else.
+	if (parsed.command === "inventory" && !parsed.json) {
+		throw new Error("inventory requires --json");
+	}
 	return parsed;
 }
 
@@ -159,6 +182,7 @@ export async function runEvidenceCommand(args: ReadonlyArray<string>): Promise<n
 				printError("inspect requires an evidence id");
 				return 2;
 			}
+			if (parsed.json) return runEvidenceDetail(evidenceId);
 			const inspected = await inspectEvidence(dataDir, evidenceId);
 			const provenance = await loadEvidenceRunProvenance(dataDir, evidenceId);
 			renderEvidence(inspected, provenance);
@@ -168,7 +192,8 @@ export async function runEvidenceCommand(args: ReadonlyArray<string>): Promise<n
 			renderEvidenceList(await listEvidenceOverviews(dataDir));
 			return 0;
 		}
-		printError("evidence requires build, inspect, or list");
+		if (parsed.command === "inventory") return runEvidenceInventory(parsed.json);
+		printError("evidence requires build, inspect, list, or inventory");
 		return 2;
 	} catch (error) {
 		printError(error instanceof Error ? error.message : String(error));

package/src/cli/extensions.ts

@@ -91,6 +91,7 @@ function resourceSummary(extension: InstalledExtension): string {
 }
 
 function stateLabel(extension: InstalledExtension): string {
+	if (!extension.compatible) return "incompatible";
 	if (!extension.enabled) return "disabled";
 	if (!extension.effective) return `shadowed:${extension.overriddenBy ?? "higher"}`;
 	return "active";
@@ -143,7 +144,10 @@ export function runExtensionsCommand(argv: ReadonlyArray<string>): number {
 		case "list": {
 			const items = listInstalledExtensions(process.cwd(), { ...scopeOptions, all: parsed.all });
 			if (parsed.json) process.stdout.write(`${JSON.stringify({ extensions: items }, null, 2)}\n`);
-			else printList(items);
+			else {
+				printList(items);
+				for (const item of items) printDiagnostics(item.diagnostics);
+			}
 			return 0;
 		}
 		case "discover": {

package/src/cli/fleet-decisions.ts

@@ -0,0 +1,69 @@
+/**
+ * Fixed machine-readable projection of durable coordinator gate decisions.
+ *
+ * A review or compete gate seals an integrity-covered artifact linking the
+ * decider receipt to every subject receipt, and nothing in the operator surface
+ * reads them: `fleet view` shows a run, not the verdict a gate reached about
+ * it. This command accepts no identifier, group, or limit, selects a bounded
+ * newest-first window itself, and emits the shape of each decision.
+ *
+ * It is a separate command from `fleet inspect --json` rather than another
+ * field on it, on the same reasoning the trace read used. The decisions live in
+ * their own directory with their own failure mode, and an installation that has
+ * never run a gate has no directory at all, so folding the read in would turn a
+ * missing directory into a failure of the run journal.
+ */
+
+import {
+	GATE_TOPOLOGY_MAX_DECISIONS,
+	GATE_TOPOLOGY_MAX_SUBJECTS,
+	type GateDecisionReason,
+	type GateTopologyDecision,
+	gateTopology,
+} from "../domains/dispatch/gate-topology.js";
+
+export {
+	GATE_TOPOLOGY_MAX_DECISIONS as FLEET_DECISIONS_MAX,
+	GATE_TOPOLOGY_MAX_SUBJECTS as FLEET_DECISIONS_MAX_SUBJECTS,
+};
+
+export interface FleetDecisionsSnapshot {
+	readonly version: 1;
+	readonly generatedAt: string;
+	readonly available: boolean;
+	readonly decisions: readonly GateTopologyDecision[];
+	readonly truncated: boolean;
+	readonly unverifiable: number;
+}
+
+export type { GateDecisionReason, GateTopologyDecision };
+
+/**
+ * Pure command payload builder, exported so the fixed CLI contract is testable
+ * without subprocess output capture.
+ *
+ * `available` separates an installation that has never run a gate from one
+ * whose gates all aged out of the scan. Both report no decisions and they are
+ * different operator states, so the flag is reported rather than inferred from
+ * an empty list.
+ */
+export function fleetDecisionsSnapshot(now: () => number = Date.now): FleetDecisionsSnapshot {
+	const topology = gateTopology();
+	return {
+		version: 1,
+		generatedAt: new Date(now()).toISOString(),
+		available: topology.present,
+		decisions: topology.decisions,
+		truncated: topology.truncated,
+		unverifiable: topology.unverifiable,
+	};
+}
+
+export function runFleetDecisions(args: ReadonlyArray<string>): number {
+	if (args.length !== 1 || args[0] !== "--json") {
+		process.stderr.write("clio-coder fleet decisions: usage: clio-coder fleet decisions --json\n");
+		return 2;
+	}
+	process.stdout.write(`${JSON.stringify(fleetDecisionsSnapshot(), null, 2)}\n`);
+	return 0;
+}