@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/cli/trace-inspect.ts

@@ -0,0 +1,252 @@
+/**
+ * Fixed machine-readable projection of recent durable trace runs and phases.
+ *
+ * `trace runs --json` is an operator-directed terminal surface: it takes a
+ * database path and a limit, and it emits `SELECT *`, which includes the
+ * request text the operator typed. The GUI cannot reuse that transport. This
+ * command accepts no identifier, path, or limit, opens only the default trace
+ * database, selects a bounded newest-first window itself, and emits accounting
+ * facts with no prompt text, no free-form description or error, and no path.
+ *
+ * It is deliberately a separate read from `fleet inspect --json` even though
+ * both are keyed by run id. The ledger and the trace database are different
+ * durable stores with different failure modes: an installation that never
+ * enabled tracing has no trace database at all, and that must be an empty
+ * answer here rather than a failure of the run journal.
+ */
+
+import { existsSync } from "node:fs";
+import { clioStatePath } from "../core/xdg.js";
+import { TraceReader, traceDatabasePath } from "../domains/observability/trace-store.js";
+import { sanitizeCallTargetText } from "../domains/safety/call-target.js";
+import { truncateToWidth } from "../engine/tui-primitives.js";
+
+export const TRACE_INSPECT_MAX_RUNS = 8;
+export const TRACE_INSPECT_MAX_PHASES = 16;
+export const TRACE_INSPECT_MAX_EVENT_KINDS = 12;
+export const TRACE_INSPECT_MAX_PROCESS_KINDS = 8;
+
+const IDENTITY_WIDTH = 128;
+const STATUS_WIDTH = 64;
+
+export interface TraceInspectPhase {
+	readonly name: string;
+	readonly kind: string;
+	readonly owner: string;
+	readonly status: string;
+	readonly attempt: number;
+	readonly retries: number;
+	/** Whether the phase recorded an error, without the error text itself. */
+	readonly failed: boolean;
+	readonly elapsedMs: number | null;
+	readonly totalTokens: number | null;
+	readonly totalCostUsd: number | null;
+}
+
+/**
+ * What a run's events were, in aggregate.
+ *
+ * Deliberately shapes and not rows. A trace event carries `payload_json` and a
+ * free-form name, which are the class of value this boundary keeps host-side,
+ * so the tail itself stays in the terminal and what crosses is how many events
+ * of each kind there were and the span they cover. The counts come out of SQL,
+ * so the payloads are not read on the way to counting them.
+ */
+export interface TraceInspectEvents {
+	readonly total: number;
+	readonly firstAt: string | null;
+	readonly lastAt: string | null;
+	readonly kinds: readonly { readonly kind: string; readonly count: number }[];
+	readonly kindsTruncated: boolean;
+}
+
+/**
+ * What a run's child processes were, in aggregate.
+ *
+ * Same rule, applied harder: a process row carries the command line, the pid,
+ * and the host. None of that is needed to say a run spawned four workers and
+ * one is still alive, and none of it crosses.
+ */
+export interface TraceInspectProcesses {
+	readonly total: number;
+	readonly running: number;
+	readonly kinds: readonly { readonly kind: string; readonly total: number; readonly running: number }[];
+	readonly kindsTruncated: boolean;
+}
+
+export interface TraceInspectRun {
+	readonly runId: string;
+	readonly agent: string;
+	readonly target: string;
+	readonly model: string;
+	readonly runtime: string;
+	readonly node: string | null;
+	readonly status: string;
+	readonly startedAt: string;
+	readonly elapsedMs: number | null;
+	readonly totalTokens: number | null;
+	readonly totalCostUsd: number | null;
+	readonly phases: readonly TraceInspectPhase[];
+	readonly phasesTruncated: boolean;
+	readonly events: TraceInspectEvents;
+	readonly processes: TraceInspectProcesses;
+}
+
+export interface TraceInspectSnapshot {
+	readonly version: 1;
+	readonly generatedAt: string;
+	/**
+	 * False when this installation has no trace database. That is the ordinary
+	 * state of an installation that never enabled tracing, and it has to stay
+	 * distinguishable from a database that exists and holds no runs.
+	 */
+	readonly available: boolean;
+	readonly runs: readonly TraceInspectRun[];
+	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));
+}
+
+function nullableBounded(value: string | null, width: number): string | null {
+	return value === null ? null : bounded(value, width);
+}
+
+/** A finite non-negative count, or null when the store recorded none. */
+function tally(value: number | null): number | null {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.trunc(value) : null;
+}
+
+/** A finite non-negative cost, or null. Kept as a number so the GUI formats it. */
+function cost(value: number | null): number | null {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+/**
+ * Wall time between two stamps. Null rather than zero when either is missing or
+ * unparseable, because "still running" and "took no time" are different facts.
+ */
+function elapsed(startedAt: string | null, endedAt: string | null): number | null {
+	if (startedAt === null || endedAt === null) return null;
+	const start = Date.parse(startedAt);
+	const end = Date.parse(endedAt);
+	if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
+	return Math.max(0, end - start);
+}
+
+function eventSummary(reader: TraceReader, runId: string): TraceInspectEvents {
+	const span = reader.eventSpan(runId);
+	const all = reader.eventKindCounts(runId);
+	const visible = all.slice(0, TRACE_INSPECT_MAX_EVENT_KINDS);
+	return {
+		total: tally(span.total) ?? 0,
+		firstAt: span.firstAt,
+		lastAt: span.lastAt,
+		kinds: visible.map((entry) => ({ kind: bounded(entry.type, STATUS_WIDTH), count: tally(entry.count) ?? 0 })),
+		kindsTruncated: all.length > visible.length,
+	};
+}
+
+function processSummary(reader: TraceReader, runId: string): TraceInspectProcesses {
+	const all = reader.processKindCounts(runId);
+	const visible = all.slice(0, TRACE_INSPECT_MAX_PROCESS_KINDS);
+	return {
+		total: all.reduce((sum, entry) => sum + (tally(entry.total) ?? 0), 0),
+		running: all.reduce((sum, entry) => sum + (tally(entry.running) ?? 0), 0),
+		kinds: visible.map((entry) => ({
+			kind: bounded(entry.kind, STATUS_WIDTH),
+			total: tally(entry.total) ?? 0,
+			running: tally(entry.running) ?? 0,
+		})),
+		kindsTruncated: all.length > visible.length,
+	};
+}
+
+/** Pure payload builder, exported so the fixed contract is testable without subprocess capture. */
+export function traceInspectSnapshot(
+	now: () => number = Date.now,
+	databasePath: string = traceDatabasePath(clioStatePath()),
+): TraceInspectSnapshot {
+	const generatedAt = new Date(now()).toISOString();
+	if (!existsSync(databasePath)) {
+		return { version: 1, generatedAt, available: false, runs: [], truncated: false };
+	}
+	let reader: TraceReader;
+	try {
+		reader = new TraceReader(databasePath);
+	} catch {
+		// A database that exists but will not open is not an empty installation,
+		// and it is not this command's job to diagnose it. Report it as present
+		// with nothing readable rather than inventing either extreme.
+		return { version: 1, generatedAt, available: true, runs: [], truncated: false };
+	}
+	try {
+		const selected = reader.runs(TRACE_INSPECT_MAX_RUNS + 1);
+		const window = selected.slice(0, TRACE_INSPECT_MAX_RUNS);
+		const runs = window.map((row): TraceInspectRun => {
+			const allPhases = reader.phases(row.run_id);
+			const visible = allPhases.slice(0, TRACE_INSPECT_MAX_PHASES);
+			return {
+				runId: bounded(row.run_id, IDENTITY_WIDTH),
+				agent: bounded(row.agent, IDENTITY_WIDTH),
+				target: bounded(row.target, IDENTITY_WIDTH),
+				model: bounded(row.model, IDENTITY_WIDTH),
+				runtime: bounded(row.runtime, IDENTITY_WIDTH),
+				node: nullableBounded(row.node, IDENTITY_WIDTH),
+				status: bounded(row.status, STATUS_WIDTH),
+				startedAt: row.started_at,
+				elapsedMs: elapsed(row.started_at, row.ended_at),
+				totalTokens: tally(row.total_tokens),
+				totalCostUsd: cost(row.total_cost_usd),
+				phases: visible.map(
+					(phase): TraceInspectPhase => ({
+						name: bounded(phase.name, IDENTITY_WIDTH),
+						kind: bounded(phase.kind, STATUS_WIDTH),
+						owner: bounded(phase.owner, IDENTITY_WIDTH),
+						status: bounded(phase.status, STATUS_WIDTH),
+						attempt: tally(phase.attempt) ?? 0,
+						retries: tally(phase.retries) ?? 0,
+						// The error text can quote a path, a URL, or a model reply, so only
+						// the fact that one was recorded crosses.
+						failed: phase.error !== null && phase.error !== "",
+						elapsedMs: elapsed(phase.started_at, phase.ended_at),
+						totalTokens: tally(phase.total_tokens),
+						totalCostUsd: cost(phase.total_cost_usd),
+					}),
+				),
+				phasesTruncated: allPhases.length > visible.length,
+				events: eventSummary(reader, row.run_id),
+				processes: processSummary(reader, row.run_id),
+			};
+		});
+		return {
+			version: 1,
+			generatedAt,
+			available: true,
+			runs,
+			truncated: selected.length > window.length,
+		};
+	} finally {
+		reader.close();
+	}
+}
+
+/**
+ * `clio-coder trace inspect --json`, and nothing else.
+ *
+ * `fixed` is false as soon as the caller supplied a database, a limit, a follow,
+ * or any other positional. The whole point of this command is that its argv is
+ * not a surface: a GUI host can invoke it and be certain the process it started
+ * cannot be steered into reading a different file or a wider window.
+ */
+export function runTraceInspect(fixed: boolean): number {
+	if (!fixed) {
+		process.stderr.write("clio-coder trace inspect: usage: clio-coder trace inspect --json\n");
+		return 2;
+	}
+	process.stdout.write(`${JSON.stringify(traceInspectSnapshot(), null, 2)}\n`);
+	return 0;
+}

package/src/cli/trace.ts

@@ -15,9 +15,11 @@ import {
 	TraceStore,
 	traceDatabasePath,
 } from "../domains/observability/trace-store.js";
+import { runTraceInspect } from "./trace-inspect.js";
 
 const HELP = `Usage:
   clio-coder trace runs [--db PATH] [--limit N] [--json]
+  clio-coder trace inspect --json         a fixed bounded window with no request text
   clio-coder trace phases <runId> [--db PATH]
   clio-coder trace tail <runId> [--follow] [--db PATH]
   clio-coder trace procs <runId> [--db PATH]
@@ -32,6 +34,9 @@ CLIO_CODER_TRACE_RETENTION_DAYS or CLIO_CODER_TRACE_MAX_BYTES to change the auto
 policy; prune flags override those values for one command.
 `;
 
+/** Rows `trace runs` shows when the operator names no limit. */
+const DEFAULT_TRACE_LIMIT = 50;
+
 interface ParsedTraceArgs {
 	positional: string[];
 	db: string;
@@ -50,7 +55,7 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 	let db = traceDatabasePath(clioStatePath());
 	let dbExplicit = false;
 	let follow = false;
-	let limit = 50;
+	let limit = DEFAULT_TRACE_LIMIT;
 	let port = 0;
 	let json = false;
 	let maxAgeDays: number | undefined;
@@ -91,7 +96,7 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 }
 
 /** Every subcommand `trace` answers to. Anything else is a usage error. */
-const TRACE_COMMANDS = new Set(["runs", "phases", "tail", "procs", "prune", "sql", "ui"]);
+const TRACE_COMMANDS = new Set(["runs", "inspect", "phases", "tail", "procs", "prune", "sql", "ui"]);
 
 /** The subcommands whose first positional is a run id. */
 const TRACE_COMMANDS_NEEDING_RUN_ID = new Set(["phases", "tail", "procs"]);
@@ -147,6 +152,22 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 
 	if (command === "ui") return runTraceUi(parsed.db, parsed.port);
 
+	// `inspect` answers ahead of the no-database courtesy below, because its
+	// answer to a state tree nothing has written to is a JSON snapshot saying
+	// the trace database is unavailable, not a sentence on stdout.
+	if (command === "inspect") {
+		return runTraceInspect(
+			parsed.positional.length === 1 &&
+				parsed.json &&
+				!parsed.dbExplicit &&
+				!parsed.follow &&
+				parsed.limit === DEFAULT_TRACE_LIMIT &&
+				parsed.port === 0 &&
+				parsed.maxAgeDays === undefined &&
+				parsed.maxBytes === undefined,
+		);
+	}
+
 	// A database that was never written is the empty state, not a failure. Handing
 	// the absent path to node:sqlite produced "unable to open database file",
 	// which named neither the file nor a next step, and loading the module leaked

package/src/cli/verifiers-inspect.ts

@@ -0,0 +1,347 @@
+/**
+ * Fixed machine-readable projection of this project's verification checks.
+ *
+ * `verifiers discover` renders an authoring preview and `verifiers validate`
+ * prints one sentence, so neither is a transport a GUI host can invoke. This
+ * command takes no identifier and no flag beyond `--json`, writes nothing, and
+ * runs no check: `verifiers dry-run` executes the production verify path and is
+ * a deliberate operator action, not something a browser refresh should trigger.
+ *
+ * What crosses is the shape of the check plane: which checks exist, where each
+ * was declared, which toolchain it drives, whether its argv is fixed, and
+ * whether the project catalog parses at all.
+ *
+ * What does not cross is the argv itself. A catalog check's `command` is an
+ * exact argument vector whose entries the schema permits to be absolute paths,
+ * so no width of projection makes it safe, and the executable is therefore
+ * classified against a closed set of toolchains rather than quoted. That is the
+ * same call trace event payloads and process command lines got: count and
+ * classify instead of projecting less. The declared `cwd`, the source file
+ * path, and every discovery diagnostic stay host-side for the same reason.
+ */
+
+import { isProjectVerifierCheckId } from "../core/verification-scripts.js";
+import {
+	type AuthoringCheck,
+	discoverVerifierAuthoring,
+	type VerifierProposalAuthority,
+	type VerifierSignalKind,
+} from "../tools/verify/authoring.js";
+import { loadProjectVerifierCatalog, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH } from "../tools/verify/catalog.js";
+
+/** Wire bound on the emitted check list, independent of the catalog's own 128-check cap. */
+export const MAX_VERIFIERS_INSPECT_CHECKS = 64;
+
+const TAG_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+const REJECTION_LOCATION_PATTERN = /^(root|checks\[\d{1,3}\])(\.[a-zA-Z]{1,32}(\[\d{1,3}\])?)?$/;
+
+/**
+ * Where a check was declared, and therefore how much of it the operator wrote.
+ *
+ * The domain's own `AuthoringCheck.state` also carries `manual`, which only the
+ * interactive authoring flow mints. Discovery cannot produce it, so it is not in
+ * this set: carrying a value this read can never emit would state a distinction
+ * it never establishes.
+ */
+export const VERIFIER_ORIGINS = ["package-script", "catalog", "proposed"] as const;
+export type VerifierOrigin = (typeof VERIFIER_ORIGINS)[number];
+
+/**
+ * The toolchain a check drives, classified from `command[0]`.
+ *
+ * The catalog schema already guarantees the executable is a single token and
+ * refuses every shell, so this is a classification over a constrained value
+ * rather than a redaction of an arbitrary one. `other` is a real answer: the
+ * operator still learns a check exists and how it is bound, just not which
+ * program outside this list it starts.
+ */
+export const VERIFIER_RUNNERS = [
+	"npm",
+	"pnpm",
+	"yarn",
+	"bun",
+	"deno",
+	"node",
+	"cargo",
+	"go",
+	"make",
+	"just",
+	"cmake",
+	"ctest",
+	"ninja",
+	"python",
+	"pytest",
+	"uv",
+	"tox",
+	"nox",
+	"dotnet",
+	"gradle",
+	"maven",
+	"rake",
+	"swift",
+	"other",
+] as const;
+export type VerifierRunner = (typeof VERIFIER_RUNNERS)[number];
+
+const RUNNER_ALIASES = new Map<string, VerifierRunner>([
+	["python3", "python"],
+	["python2", "python"],
+	["py", "python"],
+	["mvn", "maven"],
+	["gradlew", "gradle"],
+	["mvnw", "maven"],
+	["npx", "npm"],
+	["pnpx", "pnpm"],
+	["go-test", "go"],
+]);
+
+/** Why discovery could not enumerate the check plane at all. */
+export const VERIFIER_BLOCKS = ["catalog-rejected", "id-collision", "unclassified"] as const;
+export type VerifierBlock = (typeof VERIFIER_BLOCKS)[number];
+
+/**
+ * Why the production parser refused the project catalog.
+ *
+ * The parser's diagnostics quote the offending value, the workspace path, and
+ * the schema cap that was passed, so the sentence itself never crosses. The
+ * classification says what went wrong and `rejectedAt` says where, which is the
+ * pair an operator needs to find the line without being handed its contents.
+ */
+export const VERIFIER_REJECTIONS = [
+	"unreadable",
+	"invalid-yaml",
+	"unsupported-version",
+	"unknown-field",
+	"missing-field",
+	"duplicate-id",
+	"shell-command",
+	"too-large",
+	"invalid-cwd",
+	"invalid-value",
+	"unclassified",
+] as const;
+export type VerifierRejection = (typeof VERIFIER_REJECTIONS)[number];
+
+export interface VerifiersInspectCheck {
+	readonly id: string;
+	readonly description: string;
+	readonly origin: VerifierOrigin;
+	/** The declaration the harness read this check out of. */
+	readonly signal: VerifierSignalKind;
+	readonly authority: VerifierProposalAuthority;
+	/** The toolchain `command[0]` starts. The arguments themselves stay host-side. */
+	readonly runner: VerifierRunner;
+	/** How many arguments follow the executable, so an operator can see a bare invocation from a long one. */
+	readonly argumentCount: number;
+	/** True when the check runs at the repository root. A subdirectory's name does not cross. */
+	readonly runsAtRepositoryRoot: boolean;
+	/**
+	 * True when verify fixes argv, cwd, and timeout through safe-exec.
+	 *
+	 * A package-script check runs npm with the declared script name and may
+	 * accept explicit extra argv, so it is the one origin whose effective
+	 * command is not pinned by the declaration. That is a trust difference and
+	 * the reason this is reported rather than left to be inferred.
+	 */
+	readonly argvFixed: boolean;
+	readonly timeoutMs: number;
+	readonly tags: readonly string[];
+}
+
+export interface VerifiersInspectSnapshot {
+	readonly version: 1;
+	readonly generatedAt: string;
+	/** Whether the project catalog file exists at all. Its path stays host-side. */
+	readonly catalogPresent: boolean;
+	/** Whether the production parser accepted it; null when there is nothing to parse. */
+	readonly catalogValid: boolean | null;
+	readonly rejection: VerifierRejection | null;
+	/** The schema location the rejection named, such as `checks[3].command[0]`. */
+	readonly rejectedAt: string | null;
+	/** Whether the check plane could be enumerated. */
+	readonly discovery: "complete" | "blocked";
+	readonly blockedBy: VerifierBlock | null;
+	readonly checks: readonly VerifiersInspectCheck[];
+	readonly checksTruncated: boolean;
+	/** How many discovery diagnostics were raised. Each one quotes a path, so the text stays host-side. */
+	readonly diagnosticCount: number;
+}
+
+/**
+ * A codepoint scan rather than a regex, because the whole point is the control
+ * range and a character class over it is exactly what a linter refuses.
+ */
+function hasControlCharacter(value: string): boolean {
+	for (const character of value) {
+		const code = character.codePointAt(0) ?? 0;
+		if (code <= 0x1f || code === 0x7f) return true;
+	}
+	return false;
+}
+
+function runnerOf(executable: string | undefined): VerifierRunner {
+	if (executable === undefined) return "other";
+	const separator = Math.max(executable.lastIndexOf("/"), executable.lastIndexOf("\\"));
+	const base = executable
+		.slice(separator + 1)
+		.toLowerCase()
+		.replace(/\.(exe|cmd|bat|ps1)$/u, "");
+	const alias = RUNNER_ALIASES.get(base);
+	if (alias !== undefined) return alias;
+	return (VERIFIER_RUNNERS as ReadonlyArray<string>).includes(base) ? (base as VerifierRunner) : "other";
+}
+
+function rejectionMessage(reason: string): string {
+	const prefix = `${PROJECT_VERIFIER_CATALOG_RELATIVE_PATH}: `;
+	return reason.startsWith(prefix) ? reason.slice(prefix.length) : reason;
+}
+
+function rejectionLocation(message: string): string | null {
+	const match = /^(?:root|checks\[\d{1,3}\])(?:\.[a-zA-Z]{1,32}(?:\[\d{1,3}\])?)?/u.exec(message);
+	const candidate = match?.[0];
+	if (candidate === undefined) return null;
+	return REJECTION_LOCATION_PATTERN.test(candidate) ? candidate : null;
+}
+
+/**
+ * Classify the parser's sentence instead of quoting it.
+ *
+ * The order is the discriminating one, not the declaration one: a cap failure
+ * is a cap failure wherever it happened, and the cwd bucket is guarded on the
+ * location so a NUL byte in an argv entry does not read as a bad directory.
+ */
+function classifyRejection(reason: string): { rejection: VerifierRejection; rejectedAt: string | null } {
+	const message = rejectionMessage(reason);
+	const rejectedAt = rejectionLocation(message);
+	const has = (fragment: string): boolean => message.includes(fragment);
+	const rejection: VerifierRejection = has("invalid YAML")
+		? "invalid-yaml"
+		: has("cannot read catalog") || has("must be a regular file") || has("must resolve inside the workspace root")
+			? "unreadable"
+			: has("unsupported version")
+				? "unsupported-version"
+				: has("has unknown field(s)")
+					? "unknown-field"
+					: has(" is required")
+						? "missing-field"
+						: has("duplicates '") || has("contains duplicate tag")
+							? "duplicate-id"
+							: has("may not invoke shell executable") ||
+									has("must be one executable token") ||
+									has("shell command strings are not allowed")
+								? "shell-command"
+								: has("exceeds the")
+									? "too-large"
+									: rejectedAt?.endsWith(".cwd") === true
+										? "invalid-cwd"
+										: has("must be") || has("must match") || has("must not contain") || has("uses reserved")
+											? "invalid-value"
+											: "unclassified";
+	return { rejection, rejectedAt };
+}
+
+function classifyBlock(reason: string): VerifierBlock {
+	if (reason.includes(`${PROJECT_VERIFIER_CATALOG_RELATIVE_PATH}: `)) return "catalog-rejected";
+	if (reason.includes("duplicate declared check id ")) return "id-collision";
+	return "unclassified";
+}
+
+/**
+ * Re-enforce the shapes the catalog schema already guarantees.
+ *
+ * The ids and tags reaching here came through the production parser, so this is
+ * belt and braces rather than the first line of defence. It is worth the lines
+ * because a package.json script name is not held to the catalog's id rule, and
+ * because whatever wrote the declaration, the strings that cross carry no path,
+ * quote, space, or control byte.
+ */
+function projectCheck(check: AuthoringCheck): VerifiersInspectCheck | null {
+	// `manual` is only minted inside the interactive authoring flow, so a check
+	// carrying it here means this read was handed a draft rather than a discovery.
+	if (check.state === "manual") return null;
+	if (!isProjectVerifierCheckId(check.id) || check.id.length > 64) return null;
+	if (check.description.trim() !== check.description || check.description.length === 0) return null;
+	if (hasControlCharacter(check.description) || check.description.length > 512) return null;
+	const tags = check.tags.filter((tag) => TAG_PATTERN.test(tag) && tag.length <= 32);
+	if (tags.length !== check.tags.length) return null;
+	const origin: VerifierOrigin =
+		check.state === "active" ? "package-script" : check.state === "existing" ? "catalog" : "proposed";
+	return {
+		id: check.id,
+		description: check.description,
+		origin,
+		signal: check.provenance.kind,
+		authority: check.provenance.authority,
+		runner: runnerOf(check.command[0]),
+		argumentCount: Math.max(check.command.length - 1, 0),
+		runsAtRepositoryRoot: check.cwd === ".",
+		argvFixed: origin !== "package-script",
+		timeoutMs: check.timeoutMs,
+		tags,
+	};
+}
+
+const ORIGIN_RANK: Record<VerifierOrigin, number> = { "package-script": 0, catalog: 1, proposed: 2 };
+
+export function verifiersInspectSnapshot(
+	now: () => number = Date.now,
+	workspaceRoot: string = process.cwd(),
+): VerifiersInspectSnapshot {
+	const generatedAt = new Date(now()).toISOString();
+	// The catalog is loaded on its own rather than inferred from discovery,
+	// because discovery also fails on an id collision between package.json and
+	// the catalog, and "your catalog is broken" and "two declarations claim the
+	// same id" are different operator states with different repairs.
+	const catalog = loadProjectVerifierCatalog(workspaceRoot);
+	const catalogPresent = catalog.ok ? catalog.source !== null : true;
+	const classified = catalog.ok ? null : classifyRejection(catalog.reason);
+	const discovery = discoverVerifierAuthoring(workspaceRoot);
+	const base = {
+		version: 1,
+		generatedAt,
+		catalogPresent,
+		catalogValid: catalog.ok ? (catalog.source === null ? null : true) : false,
+		rejection: classified?.rejection ?? null,
+		rejectedAt: classified?.rejectedAt ?? null,
+	} as const;
+	if (!discovery.ok) {
+		return {
+			...base,
+			discovery: "blocked",
+			blockedBy: classifyBlock(discovery.reason),
+			checks: [],
+			checksTruncated: false,
+			diagnosticCount: 0,
+		};
+	}
+	const projected = [...discovery.activeChecks, ...discovery.existingChecks, ...discovery.proposals]
+		.map(projectCheck)
+		.filter((check): check is VerifiersInspectCheck => check !== null)
+		.sort((left, right) =>
+			ORIGIN_RANK[left.origin] !== ORIGIN_RANK[right.origin]
+				? ORIGIN_RANK[left.origin] - ORIGIN_RANK[right.origin]
+				: left.id < right.id
+					? -1
+					: left.id > right.id
+						? 1
+						: 0,
+		);
+	const checks = projected.slice(0, MAX_VERIFIERS_INSPECT_CHECKS);
+	return {
+		...base,
+		discovery: "complete",
+		blockedBy: null,
+		checks,
+		checksTruncated: checks.length < projected.length,
+		diagnosticCount: discovery.diagnostics.length,
+	};
+}
+
+export function runVerifiersInspect(args: ReadonlyArray<string>): number {
+	if (args.length !== 1 || args[0] !== "--json") {
+		process.stderr.write("clio-coder verifiers inspect: usage: clio-coder verifiers inspect --json\n");
+		return 2;
+	}
+	process.stdout.write(`${JSON.stringify(verifiersInspectSnapshot(), null, 2)}\n`);
+	return 0;
+}

package/src/cli/verifiers.ts

@@ -9,11 +9,13 @@ import {
 import { loadProjectVerifierCatalog, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH } from "../tools/verify/catalog.js";
 import { verifyTool } from "../tools/verify/index.js";
 import { printError, printOk } from "./argv.js";
+import { runVerifiersInspect } from "./verifiers-inspect.js";
 
 const HELP = `Project verifier authoring
 
 Usage:
   clio-coder verifiers discover
+  clio-coder verifiers inspect --json
   clio-coder verifiers author [--exclude <id>] [--rename <old>=<new>] [--dry-run <id>] [--yes]
   clio-coder verifiers validate
   clio-coder verifiers dry-run <id>
@@ -30,6 +32,10 @@ Fields:
 Discovery and every preview are read-only. Mutating commands write only with
 --yes after printing the exact argv, cwd, timeout, tags, source provenance, and
 effective execution authority. dry-run invokes the production verify path.
+
+inspect is the fixed machine-readable read a GUI host may run. It takes no other
+argument, runs no check, and carries no argv, cwd, source path, or diagnostic
+text: the toolchain each check drives is classified, and the arguments stay here.
 `;
 
 const VALUE_OPTIONS = new Set([
@@ -282,6 +288,9 @@ function validateCommand(): number {
 }
 
 export async function runVerifiersCommand(argv: string[]): Promise<number> {
+	// Routed before the authoring parser so the fixed read stays exactly fixed. No
+	// authoring flag can reach it, and no flag it does not name can be spent on it.
+	if (argv[0] === "inspect") return runVerifiersInspect(argv.slice(1));
 	const parsed = parseAuthoringArgs(argv);
 	if (parsed.error !== undefined) {
 		printError(parsed.error);