@iowarp/clio-coder 0.3.7 → 0.3.9

package/src/cli/evidence.ts

@@ -1,16 +1,18 @@
 import { InvalidIdError } from "../core/safe-id.js";
 import { clioDataDir, clioStateDir } from "../core/xdg.js";
-import type { CanonicalTrustStatus, EvidenceOverview, EvidenceRunProvenance } from "../domains/evidence/index.js";
+import type { EvidenceOverview, EvidenceRunProvenance } from "../domains/evidence/index.js";
 import {
 	buildEvalEvidence,
 	buildEvidence,
 	EvidenceNotFoundError,
+	formatTrustAxes,
+	formatTrustSummary,
 	inspectEvidence,
 	listEvidenceOverviews,
 	loadEvidenceRunProvenance,
 	provenanceTranscriptLines,
 } from "../domains/evidence/index.js";
-import { printError, printOk } from "./shared.js";
+import { printError, printNote, printOk } from "./shared.js";
 
 const HELP = `clio-coder evidence build --run <runId>
 clio-coder evidence build --session <sessionId>
@@ -137,15 +139,19 @@ export async function runEvidenceCommand(args: ReadonlyArray<string>): Promise<n
 			// but the verdict line and exit code must not say ok over a receipt
 			// that failed integrity verification.
 			const integrityFailures = result.findings.filter((entry) => entry.tag === "receipt-integrity");
-			if (integrityFailures.length > 0) {
-				process.stdout.write(`wrote ${result.evidenceId} ${result.directory}\n`);
-				for (const failure of integrityFailures) {
-					printError(`${failure.runId !== null ? `run ${failure.runId}: ` : ""}${failure.message}`);
-				}
-				return 1;
+			// A retired seal is the expected state of every run that predates an
+			// integrity bump: the receipt is set aside unread, as a missing one
+			// is, so it is a note beside the verdict and leaves the exit code alone.
+			const retiredSeals = result.findings.filter((entry) => entry.tag === "receipt-retired");
+			if (integrityFailures.length > 0) process.stdout.write(`wrote ${result.evidenceId} ${result.directory}\n`);
+			else printOk(`wrote ${result.evidenceId} ${result.directory}`);
+			for (const entry of retiredSeals) {
+				printNote(`${entry.runId !== null ? `run ${entry.runId}: ` : ""}${entry.message}`);
 			}
-			printOk(`wrote ${result.evidenceId} ${result.directory}`);
-			return 0;
+			for (const failure of integrityFailures) {
+				printError(`${failure.runId !== null ? `run ${failure.runId}: ` : ""}${failure.message}`);
+			}
+			return integrityFailures.length > 0 ? 1 : 0;
 		}
 		if (parsed.command === "inspect") {
 			const evidenceId = parsed.evidenceId;
@@ -191,30 +197,29 @@ function renderEvidence(
 	if (trustStatus.projection === "historical_format") {
 		process.stdout.write("trust status: unavailable (historical bundle without canonical projection)\n");
 	} else {
+		// The compact projection answers the trust questions; the canonical axis
+		// line beneath it is the drill-down, in the same form the dispatch tool
+		// and monitor print.
 		for (const run of trustStatus.runs) {
-			process.stdout.write(`trust ${run.runId}: ${formatTrustStatus(run.status)}\n`);
+			process.stdout.write(`trust ${run.runId}: ${formatTrustSummary(run.status)}\n`);
+			process.stdout.write(`  ${formatTrustAxes(run.status)}\n`);
 		}
 	}
-	// Provenance is printed only for runs whose receipts carry it, so a legacy
-	// bundle prints nothing new here.
+	// Provenance is the detail behind the projection, never a second reading
+	// of it: each run's block is gated on that run's canonical status, so a
+	// receipt the projection withheld (a broken or retired seal) prints no
+	// autonomy value here, and a run whose block would be empty prints no
+	// header. A historical bundle has no projection and admits no axis detail.
+	const statusByRun = new Map(trustStatus.runs.map((entry) => [entry.runId, entry.status]));
 	for (const { runId, view } of provenance) {
+		const lines = provenanceTranscriptLines(view, statusByRun.get(runId));
+		if (lines.length === 0) continue;
 		process.stdout.write(`provenance ${runId}:\n`);
-		for (const line of provenanceTranscriptLines(view)) process.stdout.write(`  ${line}\n`);
+		for (const line of lines) process.stdout.write(`  ${line}\n`);
 	}
 	process.stdout.write(`files: ${formatList(overview.files)}\n`);
 }
 
-function formatTrustStatus(status: CanonicalTrustStatus): string {
-	return [
-		`artifactIntegrity=${status.artifactIntegrity.state}`,
-		`validationGrounding=${status.validationGrounding.state}`,
-		`independentReview=${status.independentReview.state}`,
-		`contextProvenance=${status.contextProvenance.state}`,
-		`autonomyEnforcement=${status.autonomyEnforcement.state}`,
-		`completionEvidence=${status.completionEvidence.state}`,
-	].join(" ");
-}
-
 function renderEvidenceList(overviews: ReadonlyArray<EvidenceOverview>): void {
 	process.stdout.write(`${overviews.length} evidence artifacts\n`);
 	if (overviews.length === 0) return;

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-preflight.ts

@@ -1,7 +1,4 @@
-import { join } from "node:path";
 import { readSettings } from "../core/config.js";
-import { resolvePackageRoot } from "../core/package-root.js";
-import { clioConfigDir } from "../core/xdg.js";
 import {
 	type FleetCommandRegistry,
 	type FleetContract,
@@ -9,7 +6,7 @@ import {
 	loadFleetContract,
 	renderFleetPrompt,
 } from "../domains/agents/index.js";
-import { type AgentRecipeDiagnostic, loadRecipesFromDir, mergeRecipes } from "../domains/agents/registry.js";
+import { discoverAgentRecipes } from "../domains/agents/registry.js";
 import { type AgentSpec, normalizeAgentSpec } from "../domains/agents/spec.js";
 import type { ExecutionPlan } from "../domains/dispatch/execution-plan.js";
 import { requestExecutionRole, withAttemptRole } from "../domains/dispatch/execution-role.js";
@@ -23,14 +20,7 @@ export interface FleetPreflightResult {
 }
 
 function discoverSpecs(cwd: string): AgentSpec[] {
-	const diagnostics: AgentRecipeDiagnostic[] = [];
-	const builtin = loadRecipesFromDir(
-		{ dir: join(resolvePackageRoot(), "src", "domains", "agents", "builtins"), source: "builtin" },
-		diagnostics,
-	);
-	const user = loadRecipesFromDir({ dir: join(clioConfigDir(), "agents"), source: "user" }, diagnostics);
-	const project = loadRecipesFromDir({ dir: join(cwd, ".clio-coder", "agents"), source: "project" }, diagnostics);
-	return mergeRecipes(builtin, user, project).map(normalizeAgentSpec);
+	return discoverAgentRecipes(cwd).map(normalizeAgentSpec);
 }
 
 export function inspectFleet(name: string, vars?: Readonly<Record<string, string>>): FleetPreflightResult {

package/src/cli/fleet.ts

@@ -47,8 +47,8 @@ import {
 	type RunToolBudgetEnvelope,
 } from "../domains/dispatch/budget-envelope.js";
 import { type CapacityDrain, capacityDrain, setCapacityDraining } from "../domains/dispatch/capacity-lease.js";
-import type { DispatchContract } from "../domains/dispatch/contract.js";
-import type { ExecutionPlan } from "../domains/dispatch/execution-plan.js";
+import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
+import { bindExecutionPlanEndpoints, type ExecutionPlan } from "../domains/dispatch/execution-plan.js";
 import { agentRoleFactsResolver, requestExecutionRole, withAttemptRole } from "../domains/dispatch/execution-role.js";
 import { compileFleetExecutionPlan } from "../domains/dispatch/fleet-plan.js";
 import {
@@ -67,7 +67,7 @@ import { ensureClioState, LifecycleDomainModule } from "../domains/lifecycle/ind
 import { MiddlewareDomainModule } from "../domains/middleware/index.js";
 import { ObservabilityDomainModule } from "../domains/observability/index.js";
 import { createPromptsDomainModule } from "../domains/prompts/index.js";
-import { ProvidersDomainModule } from "../domains/providers/index.js";
+import { foregroundStreamUsage, ProvidersDomainModule } from "../domains/providers/index.js";
 import { ResourcesDomainModule } from "../domains/resources/index.js";
 import type { SafetyContract } from "../domains/safety/contract.js";
 import { SafetyDomainModule } from "../domains/safety/index.js";
@@ -372,6 +372,35 @@ async function runFleet(args: ReadonlyArray<string>): Promise<number> {
 		await loaded.stop();
 		return fail(err instanceof Error ? err.message : String(err));
 	}
+	if (dispatch.preview !== undefined) {
+		try {
+			const foreground = foregroundStreamUsage();
+			const bindings: Record<string, { key: string; limit: number; foregroundHeld?: number } | undefined> = {};
+			for (const step of plan.steps) {
+				if (step.kind === "code") continue;
+				const request: DispatchRequest = {
+					agentId: step.agentId,
+					executionRole: step.executionRole,
+					task: step.task,
+					...(step.scope === "readonly" ? { autonomy: "read-only" as const } : {}),
+					...(step.target !== undefined ? { target: step.target } : {}),
+					...(step.profile !== undefined ? { workerProfile: step.profile } : {}),
+				};
+				const endpoint = dispatch.preview(request).endpoint;
+				if (endpoint === undefined) continue;
+				const foregroundHeld = foreground[endpoint.key] ?? 0;
+				bindings[step.id] = {
+					key: endpoint.key,
+					limit: endpoint.limit,
+					...(foregroundHeld > 0 ? { foregroundHeld } : {}),
+				};
+			}
+			plan = bindExecutionPlanEndpoints(plan, bindings);
+		} catch (err) {
+			await loaded.stop();
+			return fail(`route preflight failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
 	try {
 		preflightWriteBoundaries(plan, process.cwd());
 	} catch (err) {

package/src/cli/shared.ts

@@ -15,6 +15,7 @@ export {
 	parseFlags,
 	printError,
 	printHeader,
+	printNote,
 	printOk,
 } from "./argv.js";
 

package/src/cli/targets.ts

@@ -14,6 +14,7 @@ import { ConfigDomainModule } from "../domains/config/index.js";
 import { ensureClioState } from "../domains/lifecycle/index.js";
 import type { ProvidersContract, TargetStatus } from "../domains/providers/contract.js";
 import {
+	endpointCapacityForStatus,
 	isDispatchEligibleRuntime,
 	isOrchestratorEligibleRuntime,
 	ProvidersDomainModule,
@@ -24,7 +25,7 @@ import type { CapabilityFlags } from "../domains/providers/types/capability-flag
 import type { RuntimeTier } from "../domains/providers/types/runtime-descriptor.js";
 import { runConfigureCommand, runTargetRemove, runTargetRename } from "./configure.js";
 import { printError, printOk } from "./shared.js";
-import { column, terminalColumns, truncate } from "./text-layout.js";
+import { column, terminalColumns, truncate, wrapPlain } from "./text-layout.js";
 
 const HEADER: ReadonlyArray<string> = ["id", "tier", "runtime", "auth", "url", "model", "health", "caps", "notes"];
 type ProviderOutputTier = RuntimeTier | "unknown";
@@ -805,9 +806,11 @@ export interface TargetTableRow {
 	health: string;
 	caps: string;
 	notes: string;
+	/** Full degraded-health reason, kept separately so a narrow table can repeat it below the row. */
+	diagnostic?: string;
 }
 
-type TargetTableColumn = keyof TargetTableRow;
+type TargetTableColumn = Exclude<keyof TargetTableRow, "diagnostic">;
 type TargetTableWidths = Record<TargetTableColumn, number>;
 
 const TABLE_COLUMNS: ReadonlyArray<TargetTableColumn> = [
@@ -918,20 +921,35 @@ export function formatTargetTable(
 	rows: ReadonlyArray<TargetTableRow>,
 	width: number,
 	paintHealth: (cell: string, row: TargetTableRow) => string = (cell) => cell,
-): { header: string; rows: ReadonlyArray<string> } {
+): { header: string; rows: ReadonlyArray<string>; details: ReadonlyArray<ReadonlyArray<string>> } {
 	const widths = tableWidths(rows, width);
 	const line = (cells: ReadonlyArray<string>): string => cells.join(" ".repeat(TABLE_GAP)).trimEnd();
+	const formatted = rows.map((row) => {
+		const cells = TABLE_COLUMNS.map((key) => column(row[key], widths[key]));
+		const plain = line(cells);
+		const rendered =
+			plain.length > width
+				? truncate(plain, width)
+				: line(cells.map((cell, index) => (TABLE_COLUMNS[index] === "health" ? paintHealth(cell, row) : cell)));
+		const diagnosticFits = !row.diagnostic || (plain.length <= width && widths.notes >= row.diagnostic.length);
+		const details = diagnosticFits ? [] : targetDiagnosticDetails(row.diagnostic ?? "", width);
+		return { rendered, details };
+	});
 	return {
 		header: truncate(line(TABLE_COLUMNS.map((key, index) => column(HEADER[index] ?? key, widths[key]))), width),
-		rows: rows.map((row) => {
-			const cells = TABLE_COLUMNS.map((key) => column(row[key], widths[key]));
-			const plain = line(cells);
-			if (plain.length > width) return truncate(plain, width);
-			return line(cells.map((cell, index) => (TABLE_COLUMNS[index] === "health" ? paintHealth(cell, row) : cell)));
-		}),
+		rows: formatted.map(({ rendered }) => rendered),
+		details: formatted.map(({ details }) => details),
 	};
 }
 
+/** Indented diagnostic text that retains every word when the table row cannot. */
+function targetDiagnosticDetails(diagnostic: string, width: number): string[] {
+	const indent = 2;
+	return wrapPlain(`reason: ${diagnostic}`, Math.max(8, width - indent), indent).map((line, index) =>
+		index === 0 ? `${" ".repeat(indent)}${line}` : line,
+	);
+}
+
 function renderTable(providers: ProvidersContract, entries: ReadonlyArray<TargetStatus>): void {
 	const sorted = [...entries].sort(compareStatusByTier);
 	const table = formatTargetTable(
@@ -950,10 +968,12 @@ function renderTable(providers: ProvidersContract, entries: ReadonlyArray<Target
 			process.stdout.write(`${chalk.bold(table.header)}\n`);
 		}
 		process.stdout.write(`${table.rows[index] ?? ""}\n`);
+		for (const detail of table.details[index] ?? []) process.stdout.write(`${detail}\n`);
 	}
 }
 
-function targetTableRow(providers: ProvidersContract, status: TargetStatus): TargetTableRow {
+export function targetTableRow(providers: ProvidersContract, status: TargetStatus): TargetTableRow {
+	const diagnostic = degradedHealthDiagnostic(status);
 	return {
 		id: status.target.id,
 		tier: statusTier(status),
@@ -964,6 +984,7 @@ function targetTableRow(providers: ProvidersContract, status: TargetStatus): Tar
 		health: status.health.status,
 		caps: capabilityBadges(status.capabilities),
 		notes: formatNotes(status),
+		...(diagnostic ? { diagnostic } : {}),
 	};
 }
 
@@ -1044,8 +1065,14 @@ export function formatContextWindow(
 		: `ctx ${window}`;
 }
 
-function formatNotes(status: TargetStatus): string {
+export function formatNotes(status: TargetStatus): string {
 	const parts: string[] = [];
+	const diagnostic = degradedHealthDiagnostic(status);
+	// The health diagnosis leads because gateway, context, and residency facts
+	// are supplementary once the target says it cannot serve its default model.
+	if (diagnostic) parts.push(diagnostic);
+	const endpoint = endpointCapacityForStatus(status);
+	if (endpoint) parts.push(`slots ${endpoint.limit}`);
 	if (status.target.gateway) parts.push("gateway");
 	if (status.runtime?.auth === "oauth") parts.push("oauth");
 	if (status.runtime?.auth === "claude-cli") parts.push("claude-cli");
@@ -1057,6 +1084,10 @@ function formatNotes(status: TargetStatus): string {
 	return parts.join(" ");
 }
 
+function degradedHealthDiagnostic(status: TargetStatus): string | null {
+	return status.health.status === "degraded" && status.health.lastError ? status.health.lastError : null;
+}
+
 function statusTier(status: TargetStatus): ProviderOutputTier {
 	return status.runtime?.tier ?? "unknown";
 }
@@ -1117,6 +1148,7 @@ interface SerializedStatus {
 	tier: ProviderOutputTier;
 	detectedReasoning: boolean | null;
 	reasoningCandidateModelId: string | null;
+	endpointCapacity?: ReturnType<typeof endpointCapacityForStatus>;
 }
 
 function serializeStatus(
@@ -1138,6 +1170,8 @@ function serializeStatus(
 		detectedReasoning: extras.detectedReasoning,
 		reasoningCandidateModelId: extras.candidateModelId,
 	};
+	const endpointCapacity = endpointCapacityForStatus(status);
+	if (endpointCapacity !== null) out.endpointCapacity = endpointCapacity;
 	if (status.contextWindowProvenance !== undefined) {
 		out.contextWindowProvenance = status.contextWindowProvenance;
 	}

package/src/cli/trace.ts

@@ -4,12 +4,15 @@ import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { clioStatePath } from "../core/xdg.js";
 import {
+	DEFAULT_TRACE_RETENTION_POLICY,
+	resolveTraceRetentionPolicy,
 	TRACE_EVENT_POLL_LIMIT,
 	type TraceEventRow,
 	type TracePhaseRow,
 	type TraceProcessRow,
 	TraceReader,
 	type TraceRunRow,
+	TraceStore,
 	traceDatabasePath,
 } from "../domains/observability/trace-store.js";
 
@@ -18,11 +21,15 @@ const HELP = `Usage:
   clio-coder trace phases <runId> [--db PATH]
   clio-coder trace tail <runId> [--follow] [--db PATH]
   clio-coder trace procs <runId> [--db PATH]
+  clio-coder trace prune [--max-age-days N] [--max-bytes N] [--db PATH] [--json]
   clio-coder trace sql <SELECT query> [--db PATH]
   clio-coder trace ui [--db PATH] [--port N]        source checkout only
 
 The viewer ships with the repository, not the npm package, so from an installed
 Clio the subcommands above are the way in. They read the same database.
+Pruning keeps ${DEFAULT_TRACE_RETENTION_POLICY.maxAgeDays} days and at most ${DEFAULT_TRACE_RETENTION_POLICY.maxBytes} bytes by default. Set
+CLIO_CODER_TRACE_RETENTION_DAYS or CLIO_CODER_TRACE_MAX_BYTES to change the automatic
+policy; prune flags override those values for one command.
 `;
 
 interface ParsedTraceArgs {
@@ -34,6 +41,8 @@ interface ParsedTraceArgs {
 	limit: number;
 	port: number;
 	json: boolean;
+	maxAgeDays: number | undefined;
+	maxBytes: number | undefined;
 }
 
 function parseTraceArgs(args: string[]): ParsedTraceArgs {
@@ -44,11 +53,19 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 	let limit = 50;
 	let port = 0;
 	let json = false;
+	let maxAgeDays: number | undefined;
+	let maxBytes: number | undefined;
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === "--follow") follow = true;
 		else if (arg === "--json") json = true;
-		else if (arg === "--db" || arg === "--limit" || arg === "--port") {
+		else if (
+			arg === "--db" ||
+			arg === "--limit" ||
+			arg === "--port" ||
+			arg === "--max-age-days" ||
+			arg === "--max-bytes"
+		) {
 			const value = args[index + 1];
 			if (value === undefined) throw new Error(`${arg} requires a value`);
 			index += 1;
@@ -56,20 +73,25 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 				db = resolve(value);
 				dbExplicit = true;
 			} else if (arg === "--limit") limit = parseInteger(value, "--limit", 1, 500);
-			else port = parseInteger(value, "--port", 0, 65_535);
+			else if (arg === "--port") port = parseInteger(value, "--port", 0, 65_535);
+			else if (arg === "--max-age-days") maxAgeDays = parseInteger(value, arg, 1, 36_500);
+			else maxBytes = parseInteger(value, arg, 1024 * 1024, Number.MAX_SAFE_INTEGER);
 		} else if (arg?.startsWith("--db=")) {
 			db = resolve(arg.slice(5));
 			dbExplicit = true;
 		} else if (arg?.startsWith("--limit=")) limit = parseInteger(arg.slice(8), "--limit", 1, 500);
 		else if (arg?.startsWith("--port=")) port = parseInteger(arg.slice(7), "--port", 0, 65_535);
+		else if (arg?.startsWith("--max-age-days=")) maxAgeDays = parseInteger(arg.slice(15), "--max-age-days", 1, 36_500);
+		else if (arg?.startsWith("--max-bytes="))
+			maxBytes = parseInteger(arg.slice(12), "--max-bytes", 1024 * 1024, Number.MAX_SAFE_INTEGER);
 		else if (arg?.startsWith("-")) throw new Error(`unknown trace flag: ${arg}`);
 		else if (arg !== undefined) positional.push(arg);
 	}
-	return { positional, db, dbExplicit, follow, limit, port, json };
+	return { positional, db, dbExplicit, follow, limit, port, json, maxAgeDays, maxBytes };
 }
 
 /** Every subcommand `trace` answers to. Anything else is a usage error. */
-const TRACE_COMMANDS = new Set(["runs", "phases", "tail", "procs", "sql", "ui"]);
+const TRACE_COMMANDS = new Set(["runs", "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"]);
@@ -132,6 +154,7 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 	// the operator typed is a different claim, so a --db that is not there stays
 	// an error and says which path it means.
 	if (!existsSync(parsed.db)) return missingDatabase(parsed);
+	if (command === "prune") return runTracePrune(parsed);
 
 	let reader: TraceReader;
 	try {
@@ -189,6 +212,42 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 	}
 }
 
+function runTracePrune(parsed: ParsedTraceArgs): number {
+	let policy: ReturnType<typeof resolveTraceRetentionPolicy>;
+	try {
+		policy = resolveTraceRetentionPolicy({
+			...(parsed.maxAgeDays === undefined ? {} : { maxAgeDays: parsed.maxAgeDays }),
+			...(parsed.maxBytes === undefined ? {} : { maxBytes: parsed.maxBytes }),
+		});
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+	let store: TraceStore;
+	try {
+		store = new TraceStore(parsed.db, { retention: policy });
+	} catch (error) {
+		process.stderr.write(`trace database: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+	try {
+		const result = store.prune(policy);
+		if (parsed.json) {
+			process.stdout.write(`${JSON.stringify({ policy, ...result }, null, 2)}\n`);
+		} else {
+			process.stdout.write(
+				`trace prune: removed ${result.runsRemoved.toLocaleString("en-US")} runs and ${result.rowsRemoved.toLocaleString("en-US")} rows; reclaimed ${result.bytesRemoved.toLocaleString("en-US")} bytes; VACUUM ${result.vacuumed ? "ran" : "not needed"}; protected ${result.protectedRuns.toLocaleString("en-US")} live runs\n`,
+			);
+		}
+		return 0;
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	} finally {
+		store.close();
+	}
+}
+
 async function tail(reader: TraceReader, runId: string, follow: boolean): Promise<void> {
 	let cursor = 0;
 	let idleTerminalPolls = 0;

package/src/cli/usage.ts

@@ -12,9 +12,12 @@ import { readEvidenceIndex } from "../domains/observability/evidence-index.js";
 import { type OutOfTurnUsageRow, readOutOfTurnUsageRows } from "../domains/observability/out-of-turn-usage.js";
 import { loadSkills } from "../domains/resources/index.js";
 import {
+	foldPromptCacheTelemetry,
+	hasPromptCacheTelemetry,
 	type LedgerUsageCall,
 	ledgerUsageCalls,
 	listSessionLedgerRefs,
+	type PromptCacheTelemetry,
 	parseSessionEntries,
 	readAuditRows,
 } from "../domains/session/index.js";
@@ -69,6 +72,8 @@ interface SessionUsage {
 	entriesInWindow: number;
 	/** Completed API calls this session recorded in the window, one per call. */
 	usageCalls: LedgerUsageCall[];
+	/** Backend prompt-cache facts persisted on assistant calls in the window. */
+	promptCache: PromptCacheTelemetry;
 }
 
 /** Per-call usage folded over one grouping (a model, or the whole window). */
@@ -102,32 +107,37 @@ function addResponseModelIdObservation(counts: ResponseModelIdObservationCounts,
 
 /**
  * How the folded calls split between the session's own turns and the rounds
- * that were billed beside it. A `/btw` side question and a `/handoff` round are
- * real spend and belong in the token and cost totals, but neither is a turn:
- * they never entered the session. `turns` therefore subtracts them from the
- * folded row count, which is exactly what the `/cost` overlay does.
+ * that were billed beside it. A `/btw` side question, a `/handoff` round, a
+ * session pre-warm, and a proactive-memory step are real spend and belong in
+ * the token and cost totals, but none of them is a turn: they never entered
+ * the session. `turns` therefore subtracts them from the folded row count,
+ * which is exactly what the `/cost` overlay does.
  */
 interface CallOrigins {
 	rows: number;
 	sideQuestions: number;
 	handoffs: number;
+	prewarms: number;
+	backgroundMemory: number;
 }
 
 function emptyCallOrigins(): CallOrigins {
-	return { rows: 0, sideQuestions: 0, handoffs: 0 };
+	return { rows: 0, sideQuestions: 0, handoffs: 0, prewarms: 0, backgroundMemory: 0 };
 }
 
 function turnsOf(origins: CallOrigins): number {
-	return origins.rows - origins.sideQuestions - origins.handoffs;
+	return origins.rows - origins.sideQuestions - origins.handoffs - origins.prewarms - origins.backgroundMemory;
 }
 
 function hasLabelledCall(origins: CallOrigins): boolean {
-	return origins.sideQuestions > 0 || origins.handoffs > 0;
+	return origins.sideQuestions > 0 || origins.handoffs > 0 || origins.prewarms > 0 || origins.backgroundMemory > 0;
 }
 
 function addOutOfTurnRow(origins: CallOrigins, row: OutOfTurnUsageRow): void {
 	origins.rows += 1;
 	if (row.label === "side-question") origins.sideQuestions += 1;
+	else if (row.label === "prewarm") origins.prewarms += 1;
+	else if (row.label === "background-memory") origins.backgroundMemory += 1;
 	else origins.handoffs += 1;
 }
 
@@ -435,6 +445,9 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 	const usageRows = [...usageByModel.values()].sort(
 		(a, b) => b.totals.totalTokens - a.totals.totalTokens || a.providerId.localeCompare(b.providerId),
 	);
+	const cacheSessions = sessions
+		.filter((session) => hasPromptCacheTelemetry(session.promptCache))
+		.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
 
 	const approvedMemory = memoryRecords.filter((record) => record.approved && record.rejectedAt === undefined);
 	const pendingMemory = memoryRecords.filter((record) => !record.approved && record.rejectedAt === undefined);
@@ -515,8 +528,8 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		emit({ kind: "fact", fact: "audit-tool-calls", value: auditToolCalls.length, blocked: auditBlocked.length });
 		if (usageMeasurable) {
 			// The origin split is emitted only when something out of turn was
-			// recorded, so a report over an archive with no `/btw` or `/handoff`
-			// round in it stays byte-identical to what it printed before.
+			// recorded, so a report over an archive with no `/btw`, `/handoff`, or
+			// pre-warm round in it stays byte-identical to what it printed before.
 			emit({
 				kind: "fact",
 				fact: "tokens",
@@ -526,6 +539,8 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 							turns: turnsOf(callOrigins),
 							sideQuestions: callOrigins.sideQuestions,
 							handoffs: callOrigins.handoffs,
+							prewarms: callOrigins.prewarms,
+							backgroundMemorySteps: callOrigins.backgroundMemory,
 						}
 					: {}),
 			});
@@ -540,6 +555,15 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 					...row.totals,
 				});
 			}
+			for (const session of cacheSessions) {
+				emit({
+					kind: "fact",
+					fact: "session-cache",
+					sessionId: session.sessionId,
+					uncachedPrefillTokens: session.promptCache.uncachedPrefillTokens,
+					verdictCounts: session.promptCache.verdictCounts,
+				});
+			}
 		}
 		for (const [tool, totals] of topTools) emit({ kind: "fact", fact: "top-tool", tool, ...totals });
 		for (const [shape, count] of topShapes) {
@@ -600,6 +624,10 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 			out(`  turns in window: ${turnsOf(callOrigins)}`);
 			if (callOrigins.sideQuestions > 0) out(`  side questions in window: ${callOrigins.sideQuestions}`);
 			if (callOrigins.handoffs > 0) out(`  handoffs in window: ${callOrigins.handoffs}`);
+			if (callOrigins.prewarms > 0) out(`  pre-warms in window: ${callOrigins.prewarms}`);
+			if (callOrigins.backgroundMemory > 0) {
+				out(`  background memory steps in window: ${callOrigins.backgroundMemory}`);
+			}
 		}
 		out(`  provider-reported cost in window: $${usageTotals.costUsd.toFixed(4)}`);
 	}
@@ -639,6 +667,27 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 			),
 		);
 	}
+	if (cacheSessions.length > 0) {
+		out("");
+		out("  prompt cache by session (from backend timings and persisted verdicts)");
+		process.stdout.write(
+			indent(
+				formatColumns([
+					["session", "uncached prefill", "hot/partial/cold/small"],
+					...cacheSessions.map((session) => [
+						session.sessionId,
+						session.promptCache.uncachedPrefillTokens === null ? "n/a" : String(session.promptCache.uncachedPrefillTokens),
+						[
+							session.promptCache.verdictCounts.hot,
+							session.promptCache.verdictCounts.partial,
+							session.promptCache.verdictCounts.cold,
+							session.promptCache.verdictCounts.small,
+						].join("/"),
+					]),
+				]),
+			),
+		);
+	}
 	if (topTools.length > 0) {
 		out("");
 		out("  top tools (from receipt toolStats)");
@@ -865,6 +914,9 @@ async function readSessions(
 		}
 		const parsedEntries = parseSessionEntries(raw, ref.path);
 		diagnostics.malformedSessionLines += parsedEntries.errors.length;
+		const accountingEntries = parsedEntries.entries.filter(
+			(entry) => entry.kind === "modelChange" || inWindow(entry.timestamp, windowStart, windowEnd),
+		);
 		const usage: SessionUsage = {
 			sessionId: ref.sessionId,
 			cwdHash: ref.cwdHash,
@@ -874,11 +926,8 @@ async function readSessions(
 			// modelChange rows are kept regardless of the window: they carry no
 			// usage of their own, and dropping the ones that predate the window
 			// would attribute in-window calls to the wrong target.
-			usageCalls: ledgerUsageCalls(
-				parsedEntries.entries.filter(
-					(entry) => entry.kind === "modelChange" || inWindow(entry.timestamp, windowStart, windowEnd),
-				),
-			),
+			usageCalls: ledgerUsageCalls(accountingEntries),
+			promptCache: foldPromptCacheTelemetry(accountingEntries),
 		};
 		for (const entry of parsedEntries.entries) {
 			if (!inWindow(entry.timestamp, windowStart, windowEnd)) continue;