@iowarp/clio-coder 0.4.3 → 0.4.5

package/src/domains/eval/verifiers/integrity.ts

@@ -0,0 +1,39 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+export class EvalGraderIntegrityError extends Error {}
+
+/** Explicit dependencies avoid guessing executable paths from arbitrary shell commands. */
+export async function protectGraderFiles(cwd: string, files: readonly string[]): Promise<() => Promise<void>> {
+	const paths = files.map((file) => {
+		const path = resolve(cwd, file);
+		const rel = relative(cwd, path);
+		if (isAbsolute(file) || rel === ".." || rel.startsWith(`..${sep}`))
+			throw new EvalGraderIntegrityError(`grader dependency escapes workspace: ${file}`);
+		return path;
+	});
+	const fingerprint = async (path: string) => {
+		// Do not follow a replacement symlink to content chosen outside the fixture.
+		let current = path;
+		while (current !== resolve(cwd)) {
+			if ((await lstat(current)).isSymbolicLink())
+				throw new EvalGraderIntegrityError(`grader dependency is a symlink: ${path}`);
+			current = resolve(current, "..");
+		}
+		return createHash("sha256")
+			.update(await readFile(path))
+			.digest("hex");
+	};
+	const hashes = await Promise.all(paths.map(fingerprint));
+	return async () => {
+		for (const [index, path] of paths.entries()) {
+			try {
+				if ((await fingerprint(path)) === hashes[index]) continue;
+			} catch {
+				/* Missing, unreadable, and replaced dependencies all invalidate grading. */
+			}
+			throw new EvalGraderIntegrityError(`grader dependency changed during trial: ${relative(cwd, path)}`);
+		}
+	};
+}

package/src/domains/eval/verifiers/patch.ts

@@ -1,4 +1,43 @@
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync, readlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+type FileBaseline = Map<string, { hash: string; bytes: number }>;
+const baselines = new Map<string, FileBaseline>();
+
+/** Held by the harness process so a runner cannot rewrite its own baseline. */
+export function recordPatchBaseline(cwd: string): void {
+	baselines.set(resolve(cwd), snapshotFiles(cwd));
+}
+
+export function forgetPatchBaseline(cwd: string): void {
+	baselines.delete(resolve(cwd));
+}
+
+function snapshotFiles(cwd: string): FileBaseline {
+	const files: FileBaseline = new Map();
+	function walk(dir: string, prefix: string): void {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			if (entry.name === ".git") continue;
+			const path = join(dir, entry.name);
+			const relative = prefix + entry.name;
+			if (entry.isDirectory()) walk(path, `${relative}/`);
+			else if (entry.isFile() || entry.isSymbolicLink()) {
+				const bytes = entry.isSymbolicLink() ? Buffer.from(readlinkSync(path)) : readFileSync(path);
+				files.set(relative, {
+					hash: createHash("sha256")
+						.update(entry.isSymbolicLink() ? "link:" : "file:")
+						.update(bytes)
+						.digest("hex"),
+					bytes: bytes.length,
+				});
+			}
+		}
+	}
+	walk(cwd, "");
+	return files;
+}
 
 export interface PatchMetrics {
 	bytes: number;
@@ -6,9 +45,26 @@ export interface PatchMetrics {
 	testFilesModified: number;
 }
 
-export function collectPatchMetrics(cwd: string): PatchMetrics {
+export function collectPatchMetrics(cwd: string): PatchMetrics | null {
+	const baseline = baselines.get(resolve(cwd));
+	if (baseline !== undefined) {
+		const current = snapshotFiles(cwd);
+		const changed = [...new Set([...baseline.keys(), ...current.keys()])].filter(
+			(path) => baseline.get(path)?.hash !== current.get(path)?.hash,
+		);
+		return {
+			// For hash baselines this is changed file content bytes, including deleted
+			// content, rather than a textual Git diff (which cannot represent all files).
+			bytes: changed.reduce((sum, path) => sum + (current.get(path)?.bytes ?? baseline.get(path)?.bytes ?? 0), 0),
+			filesChanged: changed.length,
+			testFilesModified: changed.filter((file) => /(^|\/)(test|tests|spec|__tests__)(\/|$)|\.(test|spec)\./.test(file))
+				.length,
+		};
+	}
+
 	const diff = spawnSync("git", ["diff", "--", "."], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
-	const text = diff.status === 0 && typeof diff.stdout === "string" ? diff.stdout : "";
+	if (diff.status !== 0 || typeof diff.stdout !== "string") return null;
+	const text = diff.stdout;
 	const files = text
 		.split(/\r?\n/)
 		.filter((line) => line.startsWith("diff --git "))

package/src/domains/eval/workspaces/temp-copy.ts

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { relative, resolve } from "node:path";
 import { promisify } from "node:util";
 import type { EvalWorkspaceV2 } from "../schema/suite.js";
+import { forgetPatchBaseline, recordPatchBaseline } from "../verifiers/patch.js";
 import type { PreparedEvalWorkspace } from "./local.js";
 
 const execFileAsync = promisify(execFile);
@@ -42,9 +43,11 @@ export async function prepareTempCopyWorkspace(
 			recursive: true,
 			filter: (path) => shouldCopy(relative(source, path), excludes, selection),
 		});
+		recordPatchBaseline(dest);
 		return {
 			dir: dest,
 			cleanup: async () => {
+				forgetPatchBaseline(dest);
 				await rm(dest, { recursive: true, force: true });
 			},
 		};

package/src/domains/evidence/build.ts

@@ -12,6 +12,8 @@ import type {
 } from "../dispatch/index.js";
 import { type ExecutionRole, isExecutionRole, readGateDecisionArtifactsForRunIds } from "../dispatch/index.js";
 import { detectValidationCommand } from "../safety/protected-artifacts.js";
+import { foldDecisionBoard } from "../session/decision-board.js";
+import { type DecisionLedgerEntry, decisionRef } from "../session/entries.js";
 import {
 	type AuditJsonRow,
 	type BashExecutionEntry,
@@ -23,6 +25,7 @@ import {
 	readSessionEntriesForId,
 	type SessionEntry,
 } from "../session/index.js";
+import { filterEntriesToActivePath } from "../session/tree/active-path.js";
 import { attributeEvidenceFailure } from "./failure-attribution.js";
 import { renderEvidenceFindingsMarkdown } from "./findings-markdown.js";
 import { compareCodepoints as compareStrings } from "./ordering.js";
@@ -37,6 +40,7 @@ import {
 	type EvidenceAuditLinkedRow,
 	type EvidenceBuildResult,
 	type EvidenceCleanTraceRow,
+	type EvidenceDecision,
 	type EvidenceFinding,
 	type EvidenceGateDecisionsFile,
 	type EvidenceLinkConfidence,
@@ -94,6 +98,7 @@ interface LinkedSessionEntry {
 }
 
 interface SessionLinkResult {
+	decisionBoards: Map<string, DecisionLedgerEntry[]>;
 	entries: LinkedSessionEntry[];
 	attemptedSessionIds: string[];
 	missingSessionIds: string[];
@@ -163,7 +168,10 @@ export async function buildEvidence(options: BuildEvidenceOptions): Promise<Evid
 		gateDecisions: gateDecisions.decisions,
 		validationEvidence,
 	});
-	const findings = buildFindings(runSources, trustStatusRaw, sessionLinks, auditLinks, protectedArtifactsRaw);
+	const decisionLinks = resolveReceiptDecisions(runSources, sessionLinks);
+	const rawFindings = buildFindings(runSources, trustStatusRaw, sessionLinks, auditLinks, protectedArtifactsRaw);
+	for (const row of decisionLinks.findings)
+		rawFindings.push({ ...row, id: `finding-${String(rawFindings.length + 1).padStart(3, "0")}` });
 	// Export-boundary redaction (cold path): secret-shaped values are scrubbed
 	// from everything the bundle serializes: envelopes, receipts (including
 	// delegation toolCallLog arguments), tool-event previews, audit rows,
@@ -171,6 +179,7 @@ export async function buildEvidence(options: BuildEvidenceOptions): Promise<Evid
 	// session files are untouched; the bundle is the boundary, and the
 	// overview's redactionCount keeps the bundle honest about its filtering.
 	const tally = createRedactionTally();
+	const findings = redactSecretsDeep(rawFindings, tally);
 	const redactedRunSources: EvidenceRunSource[] = runSources.map((item) => ({
 		...item,
 		envelope: redactSecretsDeep(item.envelope, tally),
@@ -187,18 +196,21 @@ export async function buildEvidence(options: BuildEvidenceOptions): Promise<Evid
 	};
 	const protectedArtifacts = redactSecretsDeep(protectedArtifactsRaw, tally);
 	const trustStatus = redactSecretsDeep(trustStatusRaw, tally);
-	const overview = buildOverview(
-		evidenceId,
-		source,
-		redactedRunSources,
-		findings,
-		sessionLinks,
-		redactedAuditLinks,
-		redactedToolEvents,
-		protectedArtifacts,
-	);
+	const overview: EvidenceOverview = {
+		...buildOverview(
+			evidenceId,
+			source,
+			redactedRunSources,
+			findings,
+			sessionLinks,
+			redactedAuditLinks,
+			redactedToolEvents,
+			protectedArtifacts,
+		),
+		decisions: redactSecretsDeep(decisionLinks.decisions, tally),
+	};
 	const transcript = redactSecretsText(
-		renderTranscript(overview, redactedRunSources, sessionLinks, trustStatusRaw),
+		renderTranscript(overview, redactedRunSources, sessionLinks, trustStatusRaw, findings),
 		tally,
 	);
 	const finalOverview: EvidenceOverview = { ...overview, redactionCount: tally.count };
@@ -215,7 +227,17 @@ export async function buildEvidence(options: BuildEvidenceOptions): Promise<Evid
 		protectedArtifacts,
 		transcript,
 	);
-	return { evidenceId, directory, overview: finalOverview, findings, trustStatus };
+	return {
+		evidenceId,
+		directory,
+		overview: finalOverview,
+		findings,
+		trustStatus,
+		ungroundedClaims: runSources.reduce((total, source) => {
+			const grounding = authenticatedReceipt(source)?.validationGrounding;
+			return total + (grounding === undefined ? 0 : Math.max(0, grounding.claimed - grounding.grounded));
+		}, 0),
+	};
 }
 
 function buildOverview(
@@ -229,7 +251,10 @@ function buildOverview(
 	protectedArtifacts: EvidenceProtectedArtifactsFile,
 ): EvidenceOverview {
 	const envelopes = runSources.map((item) => item.envelope);
-	const receipts = runSources.flatMap((item) => (item.receipt === null ? [] : [item.receipt]));
+	const receipts = runSources.flatMap((item) => {
+		const receipt = authenticatedReceipt(item);
+		return receipt === null ? [] : [receipt];
+	});
 	const toolStats = receipts.flatMap((receipt) => receipt.toolStats);
 	const runIds = envelopes.map((envelope) => envelope.id).sort(compareStrings);
 	const sessionIds = uniqueStrings(
@@ -619,7 +644,7 @@ async function writeEvidenceFiles(
 	await writeJson(join(directory, "overview.json"), overview);
 	await writeFile(
 		join(directory, "transcript.md"),
-		transcript ?? renderTranscript(overview, runSources, sessionLinks, trustStatus),
+		transcript ?? renderTranscript(overview, runSources, sessionLinks, trustStatus, findings),
 		"utf8",
 	);
 	await writeJsonl(join(directory, "trace.raw.jsonl"), rawTraceRows(runSources));
@@ -736,6 +761,7 @@ async function linkSessionEntries(
 	const attemptedSessionIds = sourceSessionIds(source, runSources);
 	const windows = attributionWindows(ledger, runSources, attemptedSessionIds);
 	const result: SessionLinkResult = {
+		decisionBoards: new Map(),
 		entries: [],
 		attemptedSessionIds,
 		missingSessionIds: [],
@@ -748,6 +774,7 @@ async function linkSessionEntries(
 			continue;
 		}
 		result.readErrors.push(...read.errors);
+		result.decisionBoards.set(sessionId, foldDecisionBoard(filterEntriesToActivePath(read.entries, read.leafTurnId)));
 		for (const entry of read.entries) {
 			const link = linkSessionEntry(entry, windows);
 			if (source.kind === "run" && !linkCoversRun(link, source.runId)) continue;
@@ -1280,6 +1307,7 @@ function renderTranscript(
 	runSources: ReadonlyArray<EvidenceRunSource>,
 	sessionLinks: SessionLinkResult,
 	trustStatus: EvidenceTrustStatusFile,
+	findings: ReadonlyArray<EvidenceFinding>,
 ): string {
 	const trustByRun = new Map(trustStatus.runs.map((entry) => [entry.runId, entry.status]));
 	const lines = [
@@ -1306,6 +1334,21 @@ function renderTranscript(
 			}
 		}
 	}
+	const decisionFindings = findings.filter(
+		(row) => row.tag === "context-provenance" && row.message.startsWith("Decision ref "),
+	);
+	if (decisionFindings.length > 0) {
+		lines.push("", "## Decision provenance");
+		for (const row of decisionFindings) lines.push(`- [${row.severity}] ${row.runId}: ${row.message}`);
+		for (const decision of overview.decisions ?? []) {
+			lines.push(
+				`\n### ${decision.ref} (run ${decision.runId}, session ${decision.sessionId})`,
+				"```json",
+				JSON.stringify(decision.record, null, 2),
+				"```",
+			);
+		}
+	}
 	if (sessionLinks.entries.length > 0) {
 		lines.push("", "## Linked Session Transcript");
 		for (const linked of sessionLinks.entries) {
@@ -1430,11 +1473,13 @@ function renderSessionTranscriptEntry(linked: LinkedSessionEntry): string[] {
 				const label = decision.label === undefined ? "" : ` label=${previewUnknown(decision.label)}`;
 				const sourceQuestion =
 					decision.source_question === undefined ? "" : ` sourceQuestion=${previewUnknown(decision.source_question)}`;
-				const revision = decision.revisedAt === undefined ? "" : ` revisedAt=${decision.revisedAt} revisionSource=operator`;
+				const revisionSource = decision.revisionSource ?? "unknown";
+				const revision =
+					decision.revisedAt === undefined ? "" : ` revisedAt=${decision.revisedAt} revisionSource=${revisionSource}`;
 				const correction =
 					decision.correction === undefined
 						? ""
-						: ` correctionSource=operator correction=${previewUnknown(decision.correction)}`;
+						: ` correctionSource=${revisionSource} correction=${previewUnknown(decision.correction)}`;
 				return `  decision key=${decision.key} status=${decision.status} decidedAt=${decision.decidedAt}${revision}${label}${sourceQuestion} value=${previewUnknown(decision.value)}${correction}`;
 			}),
 		];
@@ -1577,6 +1622,7 @@ function parseRunEnvelope(value: unknown, source: string): RunEnvelope {
 	// tampered. The validated reads below still gate the fields evidence uses.
 	return {
 		...(value as Partial<RunEnvelope>),
+		version: 1,
 		id: readString(value, source, "id"),
 		agentId: readString(value, source, "agentId"),
 		executionRole: readExecutionRole(value, source),
@@ -1874,3 +1920,46 @@ function sanitizeEvidenceId(value: string): string {
 	const clean = value.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
 	return clean.length === 0 ? "unknown" : clean;
 }
+
+/** Receipt refs authenticate the link, while the session ledger supplies the recorded argument. */
+function resolveReceiptDecisions(
+	runSources: ReadonlyArray<EvidenceRunSource>,
+	sessions: SessionLinkResult,
+): {
+	decisions: EvidenceDecision[];
+	findings: EvidenceFinding[];
+} {
+	const decisions: EvidenceDecision[] = [];
+	const findings: EvidenceFinding[] = [];
+	for (const source of runSources) {
+		const receipt = authenticatedReceipt(source);
+		if (!receipt?.decisionRefs?.length) continue;
+		const sessionId = receipt.sessionId;
+		const board = sessionId === null ? [] : (sessions.decisionBoards.get(sessionId) ?? []);
+		const records = new Map(
+			board.flatMap((entry) =>
+				entry.decisions.map(
+					(record) =>
+						[
+							decisionRef(entry.interviewId, record.key),
+							{ ...record, source: record.source ?? (entry.origin === "agent" ? ("agent" as const) : ("operator" as const)) },
+						] as const,
+				),
+			),
+		);
+		for (const ref of new Set(receipt.decisionRefs)) {
+			const record = records.get(ref);
+			if (record && sessionId !== null) decisions.push({ runId: receipt.runId, sessionId, ref, record });
+			findings.push(
+				finding(
+					findings.length,
+					record ? "info" : "warn",
+					"context-provenance",
+					receipt.runId,
+					`Decision ref ${ref} ${record ? "resolved" : "does not resolve"} on session ${sessionId ?? "(unlinked)"} active path`,
+				),
+			);
+		}
+	}
+	return { decisions, findings };
+}

package/src/domains/evidence/detail.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 "./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,
+	};
+}

package/src/domains/evidence/eval.ts

@@ -9,6 +9,7 @@ import { renderEvidenceFindingsMarkdown } from "./findings-markdown.js";
 import { compareCodepoints as compareStrings } from "./ordering.js";
 import { buildEvidenceTrustStatusFile } from "./run-trust.js";
 import { evidenceDirectory, findingsFile } from "./store.js";
+import { inspectRunReceiptTrustStatus } from "./trust-status.js";
 import {
 	EVIDENCE_VERSION,
 	type EvidenceAuditLinkedRow,
@@ -107,7 +108,18 @@ export async function buildEvalEvidence(options: BuildEvalEvidenceOptions): Prom
 		gateDecisions,
 		trustStatus,
 	);
-	return { evidenceId, directory, overview, findings, trustStatus };
+	return {
+		evidenceId,
+		directory,
+		overview,
+		findings,
+		trustStatus,
+		ungroundedClaims: linkedRuns.runSources.reduce((total, source) => {
+			if (!inspectRunReceiptTrustStatus(source.receipt, source.envelope).integrity.ok) return total;
+			const grounding = source.receipt?.validationGrounding;
+			return total + (grounding === undefined ? 0 : Math.max(0, grounding.claimed - grounding.grounded));
+		}, 0),
+	};
 }
 
 export function evalEvidenceId(evalId: string): string {

package/src/domains/evidence/finish-contract-map.ts

@@ -7,7 +7,7 @@ import type { EvidenceTag } from "./types.js";
  *
  * The forensic layer (`evidence/build.ts`) speaks the canonical 23-tag
  * `EVIDENCE_TAGS` vocabulary over durable artifacts. The live layer
- * (`safety/finish-contract.ts`) speaks a 3-kind in-loop vocabulary
+ * (`safety/finish-contract.ts`) speaks a 4-kind in-loop vocabulary
  * (`FinishContractEvidenceKind`) over the last ~80 session entries. They are
  * the same accountability concept observed at two depths.
  *
@@ -29,11 +29,15 @@ import type { EvidenceTag } from "./types.js";
  *   - dispatch_receipt: a passed dispatch receipt, whose forensic concerns are
  *     `receipt-integrity` (the receipt verifies) and `session-linked` (the run
  *     is linked to its session).
+ *   - limitation: a successful `limitation` tool receipt, which the forensic
+ *     layer records as the `completion-evidence` info row for a run that
+ *     finished limited instead of evidenced.
  */
 export const FINISH_CONTRACT_EVIDENCE_TAGS: Record<FinishContractEvidenceKind, readonly EvidenceTag[]> = {
 	validation_command: ["no-validation", "proxy-validation"],
 	protected_artifact: ["protected-artifact"],
 	dispatch_receipt: ["receipt-integrity", "session-linked"],
+	limitation: ["completion-evidence"],
 } as const;
 
 /** The canonical tags a single live finish-contract kind projects onto. */

package/src/domains/evidence/inventory.ts

@@ -0,0 +1,167 @@
+/**
+ * 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 { truncateToWidth } from "../../engine/tui-primitives.js";
+import { sanitizeCallTargetText } from "../safety/call-target.js";
+import {
+	EVIDENCE_TAGS,
+	type EvidenceOverview,
+	type EvidenceTag,
+	listEvidenceOverviews,
+	loadEvidenceTrustStatus,
+	type TrustVerdict,
+	trustVerdict,
+} from "./index.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,
+	};
+}