@iowarp/clio-coder 0.4.2 → 0.4.4

package/src/cli/usage.ts

@@ -8,6 +8,8 @@ import {
 } from "../core/response-model-id.js";
 import { clioDataDir, clioStateDir } from "../core/xdg.js";
 import { loadMemoryRecordsSync, type MemoryRecord } from "../domains/memory/index.js";
+import { summarizeEvidenceIndex } from "../domains/observability/accountability.js";
+import { summarizeFailedCompactionUsage } from "../domains/observability/compaction-usage.js";
 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";
@@ -119,18 +121,32 @@ interface CallOrigins {
 	handoffs: number;
 	prewarms: number;
 	backgroundMemory: number;
+	failedCompaction: number;
 }
 
 function emptyCallOrigins(): CallOrigins {
-	return { rows: 0, sideQuestions: 0, handoffs: 0, prewarms: 0, backgroundMemory: 0 };
+	return { rows: 0, sideQuestions: 0, handoffs: 0, prewarms: 0, backgroundMemory: 0, failedCompaction: 0 };
 }
 
 function turnsOf(origins: CallOrigins): number {
-	return origins.rows - origins.sideQuestions - origins.handoffs - origins.prewarms - origins.backgroundMemory;
+	return (
+		origins.rows -
+		origins.sideQuestions -
+		origins.handoffs -
+		origins.prewarms -
+		origins.backgroundMemory -
+		origins.failedCompaction
+	);
 }
 
 function hasLabelledCall(origins: CallOrigins): boolean {
-	return origins.sideQuestions > 0 || origins.handoffs > 0 || origins.prewarms > 0 || origins.backgroundMemory > 0;
+	return (
+		origins.sideQuestions > 0 ||
+		origins.handoffs > 0 ||
+		origins.prewarms > 0 ||
+		origins.backgroundMemory > 0 ||
+		origins.failedCompaction > 0
+	);
 }
 
 function addOutOfTurnRow(origins: CallOrigins, row: OutOfTurnUsageRow): void {
@@ -138,6 +154,7 @@ function addOutOfTurnRow(origins: CallOrigins, row: OutOfTurnUsageRow): void {
 	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 if (row.label === "failed-compaction") origins.failedCompaction += 1;
 	else origins.handoffs += 1;
 }
 
@@ -148,16 +165,32 @@ function outOfTurnUsageCall(row: OutOfTurnUsageRow): LedgerUsageCall {
 		attributedModelId: row.attributedModelId,
 		requestedModelId: row.attributedModelId,
 		responseModelIdObservation: { state: "not-observed" },
-		input: row.usage.input,
-		output: row.usage.output,
-		cacheRead: row.usage.cacheRead,
-		cacheWrite: row.usage.cacheWrite,
-		reasoningTokens: row.usage.reasoning,
-		totalTokens: row.usage.totalTokens,
-		costUsd: row.usage.costUsd,
+		input: row.usage.input ?? 0,
+		output: row.usage.output ?? 0,
+		cacheRead: row.usage.cacheRead ?? 0,
+		cacheWrite: row.usage.cacheWrite ?? 0,
+		reasoningTokens: row.usage.reasoning ?? 0,
+		totalTokens: row.usage.totalTokens ?? 0,
+		costUsd: row.usage.costUsd ?? 0,
 	};
 }
 
+/** Existing numeric accumulators sum known contributions; the report retains missing coverage. */
+function reportedUsageTotals(totals: UsageTotals, rows: ReadonlyArray<OutOfTurnUsageRow>) {
+	const failedCompaction = summarizeFailedCompactionUsage(rows);
+	if (failedCompaction.calls === 0) return totals;
+	const reported: Record<string, unknown> = { ...totals, knownSubtotals: true, failedCompaction };
+	for (const [field, missing] of Object.entries(failedCompaction.unobservedUsageCalls)) {
+		const key = field === "reasoning" ? "reasoningTokens" : field;
+		if (missing > 0 && reported[key] === 0) reported[key] = null;
+	}
+	return reported;
+}
+
+function usageAmount(value: unknown): string {
+	return typeof value === "number" ? String(value) : "unknown";
+}
+
 function addUsageCall(totals: UsageTotals, call: LedgerUsageCall): void {
 	totals.apiCalls += call.apiCalls ?? 1;
 	totals.input += call.input;
@@ -326,6 +359,7 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		return decision === "blocked" || decision === "denied";
 	});
 	const evidenceRows = readEvidenceIndex(stateDir).filter((row) => inWindow(row.generatedAt, windowStart, now));
+	const accountability = summarizeEvidenceIndex(evidenceRows);
 	let memoryRecords: MemoryRecord[] = [];
 	try {
 		memoryRecords = loadMemoryRecordsSync(clioDataDir());
@@ -442,6 +476,8 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 	// session store is gone can still have recorded out-of-turn spend, and
 	// dropping those rows would report money that was spent as nothing at all.
 	const usageMeasurable = presence.sessionsPresent || outOfTurnRows.length > 0;
+	const reportedTotals = reportedUsageTotals(usageTotals, outOfTurnRows);
+	const failedCompaction = summarizeFailedCompactionUsage(outOfTurnRows);
 	const usageRows = [...usageByModel.values()].sort(
 		(a, b) => b.totals.totalTokens - a.totals.totalTokens || a.providerId.localeCompare(b.providerId),
 	);
@@ -525,6 +561,8 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		else emit({ kind: "fact", fact: "session-store-missing", path: presence.sessionsPath });
 		if (presence.receiptsPresent) emit({ kind: "fact", fact: "dispatch-runs", value: receipts.length });
 		else emit({ kind: "fact", fact: "receipt-store-missing", path: presence.receiptsPath });
+		emit({ kind: "fact", fact: "unverified-successes", value: accountability.unverifiedSuccesses });
+		emit({ kind: "fact", fact: "ungrounded-claims", value: accountability.ungroundedClaims });
 		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
@@ -533,7 +571,7 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 			emit({
 				kind: "fact",
 				fact: "tokens",
-				...usageTotals,
+				...reportedTotals,
 				...(hasLabelledCall(callOrigins)
 					? {
 							turns: turnsOf(callOrigins),
@@ -541,6 +579,7 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 							handoffs: callOrigins.handoffs,
 							prewarms: callOrigins.prewarms,
 							backgroundMemorySteps: callOrigins.backgroundMemory,
+							...(callOrigins.failedCompaction > 0 ? { failedCompactionCalls: callOrigins.failedCompaction } : {}),
 						}
 					: {}),
 			});
@@ -552,7 +591,12 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 					attributedModelId: row.attributedModelId,
 					requestedModelIds: [...row.requestedModelIds].sort(),
 					responseModelIdObservationCounts: row.responseModelIdObservationCounts,
-					...row.totals,
+					...reportedUsageTotals(
+						row.totals,
+						outOfTurnRows.filter(
+							(call) => call.target === row.providerId && call.attributedModelId === row.attributedModelId,
+						),
+					),
 				});
 			}
 			for (const session of cacheSessions) {
@@ -615,7 +659,7 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 	out(`  audited tool calls in window: ${auditToolCalls.length} (${auditBlocked.length} blocked/denied)`);
 	if (usageMeasurable) {
 		out(
-			`  tokens in window: ${usageTotals.totalTokens} over ${usageTotals.apiCalls} model calls (input ${usageTotals.input}, output ${usageTotals.output}, cache read ${usageTotals.cacheRead}, cache write ${usageTotals.cacheWrite}, reasoning ${usageTotals.reasoningTokens})`,
+			`  tokens in window: ${usageAmount(reportedTotals.totalTokens)} over ${usageTotals.apiCalls} model calls (input ${usageAmount(reportedTotals.input)}, output ${usageAmount(reportedTotals.output)}, cache read ${usageAmount(reportedTotals.cacheRead)}, cache write ${usageAmount(reportedTotals.cacheWrite)}, reasoning ${usageAmount(reportedTotals.reasoningTokens)})`,
 		);
 		if (hasLabelledCall(callOrigins)) {
 			// Only printed when a labelled call is in the window. Over an archive
@@ -629,7 +673,18 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 				out(`  background memory steps in window: ${callOrigins.backgroundMemory}`);
 			}
 		}
-		out(`  provider-reported cost in window: $${usageTotals.costUsd.toFixed(4)}`);
+		if (failedCompaction.calls > 0) {
+			out(
+				`  failed-compaction streams: ${failedCompaction.calls} (${failedCompaction.erroredCalls} errored, ${failedCompaction.abortedCalls} aborted, ${failedCompaction.successfulCalls} completed before the attempt failed)`,
+			);
+			out("  usage figures are known subtotals; missing compaction usage is not zero or a complete spending bound");
+			out(
+				`  errored compaction known cost: ${failedCompaction.erroredKnownUsage.costUsd === null ? "unknown" : `$${failedCompaction.erroredKnownUsage.costUsd.toFixed(4)}`}`,
+			);
+		}
+		out(
+			`  ${failedCompaction.calls > 0 ? "known reported/estimated" : "provider-reported"} cost in window: ${typeof reportedTotals.costUsd === "number" ? `$${reportedTotals.costUsd.toFixed(4)}` : "unknown"}`,
+		);
 	}
 	if (usageRows.length > 0) {
 		out("");
@@ -650,19 +705,27 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 						"tokens",
 						"cost",
 					],
-					...usageRows.map((row) => [
-						row.providerId,
-						row.attributedModelId,
-						[...row.requestedModelIds].sort().join(","),
-						responseModelIdObservationCountsLabel(row.responseModelIdObservationCounts),
-						String(row.totals.apiCalls),
-						String(row.totals.input),
-						String(row.totals.output),
-						String(row.totals.cacheRead),
-						String(row.totals.reasoningTokens),
-						String(row.totals.totalTokens),
-						`$${row.totals.costUsd.toFixed(4)}`,
-					]),
+					...usageRows.map((row) => {
+						const reported = reportedUsageTotals(
+							row.totals,
+							outOfTurnRows.filter(
+								(call) => call.target === row.providerId && call.attributedModelId === row.attributedModelId,
+							),
+						);
+						return [
+							row.providerId,
+							row.attributedModelId,
+							[...row.requestedModelIds].sort().join(","),
+							responseModelIdObservationCountsLabel(row.responseModelIdObservationCounts),
+							String(row.totals.apiCalls),
+							usageAmount(reported.input),
+							usageAmount(reported.output),
+							usageAmount(reported.cacheRead),
+							usageAmount(reported.reasoningTokens),
+							usageAmount(reported.totalTokens),
+							typeof reported.costUsd === "number" ? `$${reported.costUsd.toFixed(4)}` : "unknown",
+						];
+					}),
 				]),
 			),
 		);
@@ -747,6 +810,8 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 			),
 		);
 	}
+	out(`  unverified successes: ${accountability.unverifiedSuccesses}`);
+	out(`  ungrounded claims: ${accountability.ungroundedClaims}`);
 	if (tagCounts.size > 0) {
 		out("");
 		out("  failure tags (from evidence index)");

package/src/cli/validate-model.ts

@@ -15,9 +15,8 @@ export interface ValidateModelInput {
 	modelId: string;
 	knownModels: ReadonlyArray<string>;
 	/**
-	 * The live list, when one was fetched. It is consulted only when the static
-	 * catalog is empty, so the catalog stays the authority for cloud runtimes
-	 * and the probe becomes the authority where there is nothing else.
+	 * The live list, when one was fetched. Callers provide it only when that
+	 * runtime declares live discovery authoritative for the concrete target.
 	 */
 	live?: LiveModelInventory | undefined;
 	force: boolean;
@@ -50,6 +49,7 @@ function formatUnadvertisedModelReason(modelId: string, live: LiveModelInventory
 
 export function validateModelChoice(input: ValidateModelInput): ValidateModelResult {
 	const { runtimeId, modelId, knownModels, live, force } = input;
+	if (live !== undefined) return validateAgainstLive(modelId, live, force);
 	if (knownModels.length === 0) return validateAgainstLive(modelId, live, force);
 	if (knownModels.includes(modelId)) return { ok: true };
 	if (force) {

package/src/cli/verifiers.ts

@@ -6,8 +6,15 @@ import {
 	runVerifierAuthoringWorkflow,
 	type VerifierRevision,
 } from "../tools/verify/authoring.js";
-import { loadProjectVerifierCatalog, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH } from "../tools/verify/catalog.js";
+import {
+	DECLARED_CHECK_KINDS,
+	type DeclaredCheckKind,
+	loadProjectVerifierCatalog,
+	PROJECT_VERIFIER_CATALOG_RELATIVE_PATH,
+} from "../tools/verify/catalog.js";
 import { verifyTool } from "../tools/verify/index.js";
+import { normalizeNumericTolerance } from "../tools/verify/numeric.js";
+import { recordPerfBaseline } from "../tools/verify/scripts.js";
 import { printError, printOk } from "./argv.js";
 import { runVerifiersInspect } from "./verifiers-inspect.js";
 
@@ -23,11 +30,22 @@ Usage:
   clio-coder verifiers edit <id> [--description <text>] [--command <json-argv>] [fields] [--yes]
   clio-coder verifiers rename <old> <new> [--yes]
   clio-coder verifiers remove <id> [--yes]
+  clio-coder verifiers baseline <id>
 
 Fields:
   --cwd <path>            repository-relative working directory (default .)
   --timeout-ms <number>   bounded timeout in milliseconds (default 120000)
   --tags <a,b>            comma-separated catalog tags
+  --kind <kind>           command (default), numeric-compare, or perf-budget
+  --reference <path>      numeric-compare: repository-relative reference JSON of string -> number | number[]
+  --tolerance <json>      numeric-compare: {"relative"?,"absolute"?,"ulp"?}, at least one;
+                          perf-budget with --baseline: {"relative"} headroom over the baseline
+  --budget-ms <number>    perf-budget: wall-time bound in milliseconds
+  --budget-relative <r>   perf-budget with --budget-ms: fractional headroom over the bound
+  --baseline <path>       perf-budget: repository-relative baseline JSON written by 'verifiers baseline <id>'
+
+baseline runs a perf-budget check once and records its wall time at the check's
+baseline path; a failing or timed-out command records nothing.
 
 Discovery and every preview are read-only. Mutating commands write only with
 --yes after printing the exact argv, cwd, timeout, tags, source provenance, and
@@ -48,6 +66,12 @@ const VALUE_OPTIONS = new Set([
 	"--exclude",
 	"--rename",
 	"--dry-run",
+	"--kind",
+	"--reference",
+	"--tolerance",
+	"--budget-ms",
+	"--budget-relative",
+	"--baseline",
 ]);
 
 interface ParsedAuthoringArgs {
@@ -124,6 +148,93 @@ function tags(value: string | undefined): string[] {
 				.filter((tag) => tag.length > 0);
 }
 
+type KindFields = Pick<Extract<VerifierRevision, { kind: "add" }>["check"], "kind" | "numeric" | "perf">;
+
+function parseJsonObject(value: string, option: string): Record<string, unknown> | Error {
+	try {
+		const parsed = JSON.parse(value) as unknown;
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+			return new Error(`${option} must be a JSON object`);
+		}
+		return parsed as Record<string, unknown>;
+	} catch (error) {
+		return new Error(`${option} must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/**
+ * The kind and its parameters from the option set. Returns `{}` when no kind
+ * option was given so a plain command check keeps the version-1 shape, and an
+ * Error when the options disagree with the kind the way the catalog parser
+ * would refuse them, so the operator reads one message here instead of a
+ * rejected preview.
+ */
+function kindFieldsFromArgs(parsed: ParsedAuthoringArgs): KindFields | Error {
+	const kindValue = oneValue(parsed, "--kind") ?? "command";
+	if (!(DECLARED_CHECK_KINDS as ReadonlyArray<string>).includes(kindValue)) {
+		return new Error(`--kind must be one of ${DECLARED_CHECK_KINDS.join(", ")}`);
+	}
+	const kind = kindValue as DeclaredCheckKind;
+	const reference = oneValue(parsed, "--reference");
+	const toleranceValue = oneValue(parsed, "--tolerance");
+	const budgetMs = oneValue(parsed, "--budget-ms");
+	const budgetRelative = oneValue(parsed, "--budget-relative");
+	const baseline = oneValue(parsed, "--baseline");
+	if (kind === "command") {
+		const stray = [
+			["--reference", reference],
+			["--tolerance", toleranceValue],
+			["--budget-ms", budgetMs],
+			["--budget-relative", budgetRelative],
+			["--baseline", baseline],
+		].filter(([, value]) => value !== undefined);
+		if (stray.length > 0)
+			return new Error(`${stray.map(([name]) => name).join(", ")} require --kind numeric-compare or perf-budget`);
+		return {};
+	}
+	if (kind === "numeric-compare") {
+		if (budgetMs !== undefined || budgetRelative !== undefined || baseline !== undefined) {
+			return new Error("--budget-ms, --budget-relative, and --baseline belong to --kind perf-budget");
+		}
+		if (reference === undefined) return new Error("--reference is required for --kind numeric-compare");
+		if (toleranceValue === undefined) return new Error("--tolerance is required for --kind numeric-compare");
+		const toleranceJson = parseJsonObject(toleranceValue, "--tolerance");
+		if (toleranceJson instanceof Error) return toleranceJson;
+		const tolerance = normalizeNumericTolerance(toleranceJson);
+		if (tolerance instanceof Error) return new Error(`--tolerance ${tolerance.message}`);
+		return { kind, numeric: { reference, tolerance } };
+	}
+	if (reference !== undefined) return new Error("--reference belongs to --kind numeric-compare");
+	if ((budgetMs === undefined) === (baseline === undefined)) {
+		return new Error("--kind perf-budget requires exactly one of --budget-ms or --baseline");
+	}
+	if (budgetMs !== undefined) {
+		if (toleranceValue !== undefined) return new Error("use --budget-relative for headroom over --budget-ms");
+		const wallTimeMs = Number(budgetMs);
+		if (!Number.isFinite(wallTimeMs) || wallTimeMs <= 0) return new Error("--budget-ms must be a positive number");
+		const budget: NonNullable<KindFields["perf"]>["budget"] = { wallTimeMs };
+		if (budgetRelative !== undefined) {
+			const relative = Number(budgetRelative);
+			if (!Number.isFinite(relative) || relative < 0) return new Error("--budget-relative must be a non-negative number");
+			budget.tolerance = { relative };
+		}
+		return { kind, perf: { budget } };
+	}
+	if (budgetRelative !== undefined)
+		return new Error("--budget-relative belongs with --budget-ms; use --tolerance with --baseline");
+	const perf: NonNullable<KindFields["perf"]> = { baseline: baseline as string };
+	if (toleranceValue !== undefined) {
+		const toleranceJson = parseJsonObject(toleranceValue, "--tolerance");
+		if (toleranceJson instanceof Error) return toleranceJson;
+		const relative = toleranceJson.relative;
+		if (typeof relative !== "number" || !Number.isFinite(relative) || relative < 0) {
+			return new Error('--tolerance for a baseline must be {"relative": <non-negative number>}');
+		}
+		perf.tolerance = { relative };
+	}
+	return { kind, perf };
+}
+
 function requiredValue(parsed: ParsedAuthoringArgs, option: string): string | Error {
 	const value = oneValue(parsed, option);
 	return value === undefined || value.length === 0 ? new Error(`${option} is required`) : value;
@@ -151,6 +262,8 @@ function addRevision(parsed: ParsedAuthoringArgs): VerifierRevision | Error {
 	if (command instanceof Error) return command;
 	const timeoutMs = parseTimeout(oneValue(parsed, "--timeout-ms"));
 	if (timeoutMs instanceof Error) return timeoutMs;
+	const kindFields = kindFieldsFromArgs(parsed);
+	if (kindFields instanceof Error) return kindFields;
 	return {
 		kind: "add",
 		check: {
@@ -160,6 +273,7 @@ function addRevision(parsed: ParsedAuthoringArgs): VerifierRevision | Error {
 			cwd: oneValue(parsed, "--cwd") ?? ".",
 			timeoutMs,
 			tags: tags(oneValue(parsed, "--tags")),
+			...kindFields,
 		},
 	};
 }
@@ -186,6 +300,13 @@ function editRevision(parsed: ParsedAuthoringArgs): VerifierRevision | Error {
 	}
 	const tagValue = oneValue(parsed, "--tags");
 	if (tagValue !== undefined) changes.tags = tags(tagValue);
+	if (oneValue(parsed, "--kind") !== undefined) {
+		const kindFields = kindFieldsFromArgs(parsed);
+		if (kindFields instanceof Error) return kindFields;
+		changes.kind = kindFields.kind ?? "command";
+		if (kindFields.numeric !== undefined) changes.numeric = kindFields.numeric;
+		if (kindFields.perf !== undefined) changes.perf = kindFields.perf;
+	}
 	if (Object.keys(changes).length === 0) return new Error("edit requires at least one changed field");
 	return { kind: "edit", id, changes };
 }
@@ -260,6 +381,30 @@ async function executeWorkflow(
 	return code;
 }
 
+async function baselineCommand(id: string | undefined): Promise<number> {
+	if (id === undefined) {
+		printError("baseline requires a check ID");
+		return 2;
+	}
+	const loaded = loadProjectVerifierCatalog(process.cwd());
+	if (!loaded.ok) {
+		printError(`production catalog parser rejected ${loaded.reason}`);
+		return 1;
+	}
+	const check = loaded.source?.checks.find((candidate) => candidate.id === id);
+	if (check === undefined) {
+		printError(`no catalog check '${id}' in ${PROJECT_VERIFIER_CATALOG_RELATIVE_PATH}`);
+		return 1;
+	}
+	const recorded = await recordPerfBaseline(check);
+	if (!recorded.ok) {
+		printError(`baseline '${id}' not recorded: ${recorded.message}`);
+		return 1;
+	}
+	printOk(`recorded baseline for '${id}': ${Math.round(recorded.wallTimeMs)}ms at ${recorded.path}`);
+	return 0;
+}
+
 async function discoverCommand(): Promise<number> {
 	const discovery = discoverVerifierAuthoring();
 	if (!discovery.ok) {
@@ -304,6 +449,7 @@ export async function runVerifiersCommand(argv: string[]): Promise<number> {
 	const command = parsed.positional[0];
 	if (command === "discover") return discoverCommand();
 	if (command === "validate") return validateCommand();
+	if (command === "baseline") return baselineCommand(parsed.positional[1]);
 	if (command === "dry-run") {
 		const id = parsed.positional[1];
 		if (id === undefined) {

package/src/cli/wiki-generate.ts

@@ -336,6 +336,7 @@ async function runPagePhase(
 			codewiki: input.codewiki,
 			page,
 			siblings: plan.pages,
+			...(input.decisions ? { decisions: input.decisions } : {}),
 			outputDir: input.outputDir,
 			seeded,
 		}),

package/src/core/commit-attribution.ts

@@ -15,6 +15,21 @@ export const CLIO_COMMIT_TRAILERS = {
 	coAuthored: `Co-authored-by: ${CLIO_COMMIT_IDENTITY}`,
 } as const;
 
+export const CLIO_DECISION_TRAILER_KEY = "Clio-Decision";
+
+/** Most `Clio-Decision:` trailers one commit carries; matches the receipt cap. */
+export const CLIO_DECISION_TRAILER_CAP = 32;
+
+/**
+ * A decision ref is `<interviewId>/<key>`: an `ask_user` interview id or an
+ * `agent:<uuid>` decision-set id, then the decision key. Operator keys are
+ * snake_case and agent keys are kebab-case, the same shape `isDecisionRecord`
+ * admits. Only refs of this shape become trailers, so a malformed value can
+ * never inject a second trailer line or a stray control character into a
+ * commit message.
+ */
+export const DECISION_REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,127}\/[a-z0-9]+(?:[_-][a-z0-9]+)*$/u;
+
 export interface CommitReceiptEvidence {
 	version: 20;
 	algorithm: "sha256";
@@ -37,6 +52,12 @@ export interface CommitAttributionEvidence {
 	materiallyAuthored?: boolean;
 	/** Optional sealed receipt for a directly relevant fact above. */
 	receipt?: CommitReceiptEvidence;
+	/**
+	 * Decision refs (`<interviewId>/<key>`) the committed work was done under,
+	 * read from the session decision board or a sealed receipt's
+	 * `decisionRefs`. Each becomes one `Clio-Decision:` trailer.
+	 */
+	decisions?: ReadonlyArray<string>;
 }
 
 const TRAILER_LINE = /^([A-Za-z0-9][A-Za-z0-9-]*):[ \t]+(.+)$/u;
@@ -58,7 +79,25 @@ const KNOWN_CLIO_TRAILERS = new Set(
 );
 
 function isClioTrailer(key: string): boolean {
-	return KNOWN_CLIO_TRAILERS.has(key) || key.startsWith("clio-evidence:receipt-v20/sha256:");
+	return (
+		KNOWN_CLIO_TRAILERS.has(key) ||
+		key.startsWith("clio-evidence:receipt-v20/sha256:") ||
+		key.startsWith(`${CLIO_DECISION_TRAILER_KEY.toLowerCase()}:`)
+	);
+}
+
+/** Well-formed decision refs from the evidence, deduplicated, sorted, and capped. */
+export function decisionTrailerRefs(decisions: ReadonlyArray<string> | undefined): string[] {
+	if (decisions === undefined) return [];
+	const refs = new Set<string>();
+	for (const ref of decisions) {
+		if (typeof ref === "string" && DECISION_REF_PATTERN.test(ref)) refs.add(ref);
+	}
+	return [...refs].sort().slice(0, CLIO_DECISION_TRAILER_CAP);
+}
+
+function decisionTrailer(ref: string): string {
+	return `${CLIO_DECISION_TRAILER_KEY}: ${ref}`;
 }
 
 /**
@@ -138,6 +177,7 @@ export function attributeCommitMessage(
 	if (evidence.materiallyAuthored === true) desired.push(CLIO_COMMIT_TRAILERS.coAuthored);
 	const receipt = receiptTrailer(evidence.receipt);
 	if (receipt !== null) desired.push(receipt);
+	for (const ref of decisionTrailerRefs(evidence.decisions)) desired.push(decisionTrailer(ref));
 
 	const existing = new Set(
 		(blockStart === null ? [] : retained.slice(blockStart))

package/src/core/config.ts

@@ -525,6 +525,57 @@ function validateLmStudioSettings(
 	return Object.keys(out).length > 0 ? out : undefined;
 }
 
+function validateLiteLLMSettings(
+	issues: Issues,
+	path: string,
+	value: unknown,
+): ClioSettings["targets"][number]["litellm"] | undefined {
+	if (!isPlainObject(value)) {
+		issues.add(path, `expected a map, got ${describe(value)}`);
+		return undefined;
+	}
+	issues.unknownKeys(path, value, ["request"]);
+	const out: NonNullable<ClioSettings["targets"][number]["litellm"]> = {};
+	if ("request" in value) {
+		if (!isPlainObject(value.request)) {
+			issues.add(`${path}.request`, `expected a map, got ${describe(value.request)}`);
+		} else {
+			issues.unknownKeys(`${path}.request`, value.request, [
+				"tags",
+				"sendSessionId",
+				"timeoutSeconds",
+				"streamTimeoutSeconds",
+				"numRetries",
+			]);
+			const request: NonNullable<typeof out.request> = {};
+			if ("tags" in value.request) {
+				const parsed = expectStringArray(issues, `${path}.request.tags`, value.request.tags);
+				if (parsed !== undefined) {
+					const invalidTag = parsed.find((tag) => tag.includes(","));
+					if (invalidTag) issues.add(`${path}.request.tags`, "tags may not contain commas");
+					else if (parsed.length > 0) request.tags = [...new Set(parsed)];
+				}
+			}
+			if ("sendSessionId" in value.request) {
+				const parsed = expectBoolean(issues, `${path}.request.sendSessionId`, value.request.sendSessionId);
+				if (parsed !== undefined) request.sendSessionId = parsed;
+			}
+			for (const key of ["timeoutSeconds", "streamTimeoutSeconds"] as const) {
+				if (key in value.request) {
+					const parsed = expectNumber(issues, `${path}.request.${key}`, value.request[key], { min: 0.001, max: 86_400 });
+					if (parsed !== undefined) request[key] = parsed;
+				}
+			}
+			if ("numRetries" in value.request) {
+				const parsed = expectInteger(issues, `${path}.request.numRetries`, value.request.numRetries, { min: 0, max: 100 });
+				if (parsed !== undefined) request.numRetries = parsed;
+			}
+			if (Object.keys(request).length > 0) out.request = request;
+		}
+	}
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
 function validateTarget(issues: Issues, path: string, value: unknown): ClioSettings["targets"][number] | null {
 	if (!isPlainObject(value)) {
 		issues.add(path, `expected a map, got ${describe(value)}`);
@@ -542,6 +593,7 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		"gateway",
 		"pricing",
 		"lmstudio",
+		"litellm",
 		"maxConcurrentRequests",
 	]);
 	const id = "id" in value ? expectString(issues, `${path}.id`, value.id) : undefined;
@@ -593,6 +645,10 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		const v = validateLmStudioSettings(issues, `${path}.lmstudio`, value.lmstudio);
 		if (v !== undefined) target.lmstudio = v;
 	}
+	if ("litellm" in value) {
+		const v = validateLiteLLMSettings(issues, `${path}.litellm`, value.litellm);
+		if (v !== undefined) target.litellm = v;
+	}
 	if ("maxConcurrentRequests" in value) {
 		const v = expectInteger(issues, `${path}.maxConcurrentRequests`, value.maxConcurrentRequests, { min: 1 });
 		if (v !== undefined) target.maxConcurrentRequests = v;

package/src/core/external-diagnostic.ts

@@ -0,0 +1,44 @@
+const REDACTED = "[redacted]";
+
+/**
+ * Sanitize free-form text received from an external process before it crosses
+ * into errors, receipts, transcripts, evidence, or model-catalog snapshots.
+ */
+function redactExternalDiagnostic(input: string): string {
+	return input
+		.replace(/\b(?:authorization|proxy-authorization)\s*:\s*[^\r\n]+/giu, `Authorization: ${REDACTED}`)
+		.replace(/\b(?:set-cookie|cookie)\s*:\s*[^\r\n]+/giu, `Cookie: ${REDACTED}`)
+		.replace(/\bbearer\s+[A-Za-z0-9._~+/-]+=*/giu, `Bearer ${REDACTED}`)
+		.replace(
+			/\b(?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password)\s*[:=]\s*[^\s,;]+/giu,
+			(match) => {
+				const separator = match.includes(":") ? ":" : "=";
+				return `${match.slice(0, match.indexOf(separator)).trim()}${separator}${REDACTED}`;
+			},
+		)
+		.replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, REDACTED)
+		.replace(
+			/(?:~|\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*)\/\.(?:gemini\/antigravity-cli|antigravitycli)(?:\/[^\s]*)?/gu,
+			"[redacted credential path]",
+		)
+		.replace(/https?:\/\/[^\s"'<>]+/giu, (url) => {
+			try {
+				const parsed = new URL(url);
+				if (/(?:auth|oauth|login|signin|callback)/iu.test(parsed.pathname)) return "[redacted authorization URL]";
+				parsed.username = "";
+				parsed.password = "";
+				parsed.search = "";
+				parsed.hash = "";
+				return parsed.toString();
+			} catch {
+				return REDACTED;
+			}
+		});
+}
+
+export function boundedExternalDiagnostic(input: string, maxBytes = 8192): string {
+	const redacted = redactExternalDiagnostic(input).trim();
+	const bytes = Buffer.from(redacted, "utf8");
+	if (bytes.byteLength <= maxBytes) return redacted;
+	return `${bytes.subarray(0, Math.max(0, maxBytes - 32)).toString("utf8")}\n[diagnostic truncated]`;
+}