@iowarp/clio-coder 0.3.8 → 0.3.9

package/src/domains/resources/prompts/loader.ts

@@ -27,6 +27,14 @@ export interface PromptTemplate {
 	sourceInfo: ResourceSourceInfo;
 	/** False for a project compatibility root until the operator opts in; such a template refuses to expand. */
 	trusted: boolean;
+	/**
+	 * Why this template cannot be expanded, when a load-time failure left it
+	 * with no usable body. It is loaded anyway, so the namespaced command is
+	 * recognized and invoking it reports this reason instead of "not a command"
+	 * (issue #245). `content` is empty on such a template and nothing may send
+	 * it to a model.
+	 */
+	unavailable?: string;
 	argumentHint?: string;
 }
 
@@ -154,24 +162,28 @@ function contained(root: string, candidate: string): boolean {
 	return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
 }
 
-/** Resolve only existing paths contained by the declaring extension package. */
-function resolveExtensionReferences(
-	body: string,
-	root: PromptTemplateRoot,
-	filePath: string,
-	diagnostics: ResourceDiagnostic[],
-): string | null {
-	if (root.rootPath === undefined || !body.includes(EXTENSION_ROOT_TOKEN)) return body;
+/**
+ * The outcome of a step that may leave the template with no usable body.
+ * `reason` is the one sentence that becomes both the diagnostic the `/prompts`
+ * overlay renders and the refusal the operator gets when they invoke the
+ * command, so the two can never disagree.
+ */
+type BodyResolution = { body: string } | { reason: string };
+
+/**
+ * Resolve only existing paths contained by the declaring extension package.
+ *
+ * The safety half is unchanged: a missing or escaping reference never expands
+ * and never reads outside the package. What changed is what the caller does
+ * with the failure, which used to be dropping the template entirely.
+ */
+function resolveExtensionReferences(body: string, root: PromptTemplateRoot): BodyResolution {
+	if (root.rootPath === undefined || !body.includes(EXTENSION_ROOT_TOKEN)) return { body };
 	let canonicalRoot: string;
 	try {
 		canonicalRoot = realpathSync(root.rootPath);
 	} catch (error) {
-		diagnostics.push({
-			type: "warning",
-			message: `extension root could not be resolved: ${error instanceof Error ? error.message : String(error)}`,
-			path: filePath,
-		});
-		return null;
+		return { reason: `extension root could not be resolved: ${error instanceof Error ? error.message : String(error)}` };
 	}
 	let invalid: string | null = null;
 	const resolved = body.replace(EXTENSION_ROOT_REFERENCE, (reference, suffix: string | undefined) => {
@@ -185,14 +197,44 @@ function resolveExtensionReferences(
 		return candidate;
 	});
 	if (invalid !== null) {
-		diagnostics.push({
-			type: "warning",
-			message: `prompt template has an unresolved or escaping extension reference: ${invalid}`,
-			path: filePath,
-		});
-		return null;
+		return { reason: `prompt template has an unresolved or escaping extension reference: ${invalid}` };
 	}
-	return resolved;
+	return { body: resolved };
+}
+
+/**
+ * A template that exists and cannot run.
+ *
+ * Dropping it made the operator's namespaced command answer "not a command",
+ * so an extension author's single bad `${extensionRoot}` path read to their
+ * users as "the prompt was never installed" (issue #245). The template is
+ * loaded with an empty body and the reason attached instead, which is the same
+ * shape an untrusted project template already had, so the existing refusal
+ * path carries it to the operator with no new machinery.
+ */
+function unavailableTemplate(
+	name: string,
+	filePath: string,
+	root: PromptTemplateRoot,
+	reason: string,
+	diagnostics: ResourceDiagnostic[],
+	description?: string,
+): ResourceCandidate<PromptTemplate> {
+	diagnostics.push({ type: "warning", message: reason, path: filePath });
+	const sourceInfo: ResourceSourceInfo = sourceInfoForRoot(root, filePath);
+	return {
+		name,
+		value: {
+			name,
+			description: description ?? "Prompt template (unavailable)",
+			content: "",
+			filePath,
+			sourceInfo,
+			trusted: root.trusted !== false,
+			unavailable: `${reason} (${filePath})`,
+		},
+		source: sourceInfo,
+	};
 }
 
 function loadPromptFile(
@@ -202,15 +244,9 @@ function loadPromptFile(
 ): ResourceCandidate<PromptTemplate> | null {
 	const ext = path.extname(filePath).toLowerCase();
 	if (ext !== ".md") return null;
-	let raw: string;
-	try {
-		raw = readFileSync(filePath, "utf8");
-	} catch (err) {
-		const reason = err instanceof Error ? err.message : String(err);
-		diagnostics.push({ type: "warning", message: `prompt template could not be read: ${reason}`, path: filePath });
-		return null;
-	}
 
+	// The name comes before the read, so a file that exists but cannot be read
+	// still has a command the operator can invoke and be told why.
 	const relativePath = path.relative(root.path, filePath);
 	if (
 		relativePath === "" ||
@@ -218,21 +254,35 @@ function loadPromptFile(
 		relativePath.startsWith(`..${path.sep}`) ||
 		path.isAbsolute(relativePath)
 	) {
+		// The one failure that stays a drop: the path is outside the discovery
+		// root, so there is no name here to offer a command under.
 		diagnostics.push({ type: "warning", message: "prompt template escaped its discovery root", path: filePath });
 		return null;
 	}
 	const name = relativePath.slice(0, -ext.length).split(path.sep).join(":");
 	if (name.trim().length === 0) return null;
+
+	let raw: string;
+	try {
+		raw = readFileSync(filePath, "utf8");
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		return unavailableTemplate(name, filePath, root, `prompt template could not be read: ${reason}`, diagnostics);
+	}
+
 	const { frontmatter, body } = splitOptionalFrontmatter(raw, filePath, diagnostics);
-	const resolvedBody = resolveExtensionReferences(body, root, filePath, diagnostics);
-	if (resolvedBody === null) return null;
-	const description = stringField(frontmatter, "description") ?? fallbackDescription(resolvedBody);
+	const declaredDescription = stringField(frontmatter, "description");
+	const resolution = resolveExtensionReferences(body, root);
+	if ("reason" in resolution) {
+		return unavailableTemplate(name, filePath, root, resolution.reason, diagnostics, declaredDescription ?? undefined);
+	}
+	const description = declaredDescription ?? fallbackDescription(resolution.body);
 	const argumentHint = stringField(frontmatter, "argument-hint") ?? stringField(frontmatter, "argumentHint");
 	const sourceInfo: ResourceSourceInfo = sourceInfoForRoot(root, filePath);
 	const template: PromptTemplate = {
 		name,
 		description,
-		content: resolvedBody.trim(),
+		content: resolution.body.trim(),
 		filePath,
 		sourceInfo,
 		trusted: root.trusted !== false,
@@ -330,6 +380,18 @@ export function expandPromptTemplateInput(input: string, templates: PromptTempla
 	if (!command) return { expanded: false, text: input, args: [], diagnostics: templates.diagnostics };
 	const template = templates.items.find((entry) => entry.name === command.name);
 	if (!template) return { expanded: false, text: input, args: [], diagnostics: templates.diagnostics };
+	// A load-time failure refuses before anything else, and before the trust
+	// check, because there is no body here to be trusted or untrusted.
+	if (template.unavailable !== undefined) {
+		const message = `prompt template /${template.name} cannot run: ${template.unavailable}`;
+		return {
+			expanded: false,
+			text: input,
+			args: [],
+			diagnostics: templates.diagnostics,
+			refusal: { template, message },
+		};
+	}
 	if (!template.trusted) {
 		const message = `prompt template ${template.name} comes from an untrusted project root; set skills.trustProjectCompatRoots to use it`;
 		return {

package/src/domains/safety/call-target.ts

@@ -31,6 +31,58 @@ function oneLine(value: string): string {
 	return value.replace(/\s+/g, " ").trim();
 }
 
+/** Columns one tab occupies when a multi-line surface expands it. */
+const DISPLAY_TAB_WIDTH = 4;
+
+/** Stands in for a control byte that was neutralized, so the cut is visible. */
+const CONTROL_BYTE_PLACEHOLDER = "·";
+
+export interface SanitizedDisplayText {
+	text: string;
+	/** A control byte or escape sequence was neutralized. */
+	neutralized: boolean;
+	/** A tab was expanded, so column positions are display positions. */
+	tabsExpanded: boolean;
+}
+
+/**
+ * Neutralize escape sequences and control bytes while keeping line structure.
+ * {@link sanitizeCallTargetText} is the one-line form for a card; this is the
+ * form a multi-line operator surface needs, where the newlines are the content
+ * rather than whitespace to collapse. Tabs become spaces because a bordered
+ * frame measures visible width and a literal tab makes that measurement a lie.
+ * Every other C0 byte and DEL becomes a visible placeholder, so a payload
+ * cannot style, reposition, or spoof the surface that is approving it.
+ */
+export function sanitizeMultilineDisplayText(value: string): SanitizedDisplayText {
+	const escapesStripped = value.replace(OSC_PATTERN, "").replace(CSI_PATTERN, "");
+	let neutralized = escapesStripped.length !== value.length;
+	// CRLF is line structure, not an injection, so it normalizes rather than
+	// showing a placeholder at the end of every line of a Windows-authored file.
+	const stripped = escapesStripped.replace(/\r\n/g, "\n");
+	let tabsExpanded = false;
+	let out = "";
+	for (const ch of stripped) {
+		if (ch === "\n") {
+			out += ch;
+			continue;
+		}
+		if (ch === "\t") {
+			out += " ".repeat(DISPLAY_TAB_WIDTH);
+			tabsExpanded = true;
+			continue;
+		}
+		const code = ch.codePointAt(0) ?? 0;
+		if (code < 0x20 || code === 0x7f) {
+			out += CONTROL_BYTE_PLACEHOLDER;
+			neutralized = true;
+			continue;
+		}
+		out += ch;
+	}
+	return { text: out, neutralized, tabsExpanded };
+}
+
 /**
  * Neutralize escape sequences and control bytes in a pre-composed target
  * string and collapse it to one line. Used where a description crosses a

package/src/domains/safety/run-effects.ts

@@ -76,6 +76,23 @@ export interface RunEffects {
 	 * run there is no path left in the checkout that the record can clear.
 	 */
 	writeRecordComplete: boolean;
+	/**
+	 * Successful opaque calls that made the write record incomplete. The call id
+	 * and tool name are retained so a later write-boundary verdict can explain
+	 * exactly why attribution was downgraded instead of exposing only a boolean.
+	 */
+	writeRecordDowngrades: ReadonlyArray<WriteRecordDowngrade>;
+}
+
+export interface WriteRecordDowngrade {
+	reason: "opaque_tool_succeeded";
+	tool: string;
+	toolCallId: string;
+}
+
+export interface RunEffectsRecorderOptions {
+	/** Fires once, when the first successful opaque call opens the record. */
+	onWriteRecordDowngraded?(downgrade: WriteRecordDowngrade): void;
 }
 
 export interface RunEffectsRecorder {
@@ -87,6 +104,8 @@ export interface RunEffectsRecorder {
 }
 
 interface PendingEffects {
+	tool: string;
+	toolCallId: string;
 	paths: ReadonlyArray<string>;
 	validationCommand: string | null;
 	verificationCommand: string | null;
@@ -204,13 +223,13 @@ function validationCommandOf(
  * when its result comes back clean: a blocked write and a red command are not
  * evidence that the workspace changed or that a check passed.
  */
-export function createRunEffectsRecorder(cwd: string): RunEffectsRecorder {
+export function createRunEffectsRecorder(cwd: string, options: RunEffectsRecorderOptions = {}): RunEffectsRecorder {
 	const pending = new Map<string, PendingEffects>();
 	const mutatedPaths = new Set<string>();
 	const failedMutationPaths = new Set<string>();
 	const validationCommands = new Set<string>();
 	const verificationCommands = new Set<string>();
-	let opaqueWriteObserved = false;
+	const writeRecordDowngrades = new Map<string, WriteRecordDowngrade>();
 	return {
 		start(toolCallId, toolName, args) {
 			const paths = mutationTargets(toolName, args);
@@ -223,6 +242,8 @@ export function createRunEffectsRecorder(cwd: string): RunEffectsRecorder {
 			// A bash call may re-base its relative paths with its own cwd argument.
 			const base = typeof args?.cwd === "string" && args.cwd.length > 0 ? path.resolve(cwd, args.cwd) : cwd;
 			pending.set(toolCallId, {
+				tool: toolName,
+				toolCallId,
 				paths: paths.map((target) => path.resolve(base, target)),
 				validationCommand,
 				verificationCommand,
@@ -240,7 +261,16 @@ export function createRunEffectsRecorder(cwd: string): RunEffectsRecorder {
 			// Success-gated on purpose. A shell command the safety policy blocked,
 			// or one that came back an error, never reached the filesystem, so it
 			// leaves the record closed.
-			if (effects.opaque) opaqueWriteObserved = true;
+			if (effects.opaque) {
+				const downgrade: WriteRecordDowngrade = {
+					reason: "opaque_tool_succeeded",
+					tool: effects.tool,
+					toolCallId: effects.toolCallId,
+				};
+				const recordWasComplete = writeRecordDowngrades.size === 0;
+				writeRecordDowngrades.set(effects.toolCallId, downgrade);
+				if (recordWasComplete) options.onWriteRecordDowngraded?.({ ...downgrade });
+			}
 			for (const target of effects.paths) mutatedPaths.add(target);
 			if (effects.validationCommand !== null) validationCommands.add(effects.validationCommand);
 			if (effects.verificationCommand !== null) verificationCommands.add(effects.verificationCommand);
@@ -253,7 +283,8 @@ export function createRunEffectsRecorder(cwd: string): RunEffectsRecorder {
 				failedMutationPaths: new Set([...failedMutationPaths].filter((target) => !mutatedPaths.has(target))),
 				validationCommands: new Set(validationCommands),
 				verificationCommands: new Set(verificationCommands),
-				writeRecordComplete: !opaqueWriteObserved,
+				writeRecordComplete: writeRecordDowngrades.size === 0,
+				writeRecordDowngrades: [...writeRecordDowngrades.values()].map((entry) => ({ ...entry })),
 			};
 		},
 	};

package/src/domains/session/context-accounting.ts

@@ -72,6 +72,19 @@ export interface ContextSnapshot {
 		splits: Record<string, "estimated" | "exact" | "reconciled">;
 	};
 
+	/**
+	 * Divergence record. `estimatedTokens` is the chars/4 prompt-side total this
+	 * snapshot was captured with and is never rewritten by a reconcile, so the
+	 * two figures stay comparable. `reconciledTokens` is the provider's own
+	 * prompt token count for the call this snapshot was reconciled against
+	 * (cached prompt tokens folded back in), and `divergenceRatio` is
+	 * `reconciledTokens / estimatedTokens`. A ratio above 1 is the estimator
+	 * under-counting, which is what issue #227 recorded as a provider overflow.
+	 */
+	estimatedTokens?: number | undefined;
+	reconciledTokens?: number | undefined;
+	divergenceRatio?: number | undefined;
+
 	promptHash?: string | undefined;
 	toolSignature?: string | undefined;
 	messageRange?: { start: number; end: number } | undefined;
@@ -332,6 +345,31 @@ export function getLatestContextSnapshot(meta: SessionMeta): ContextSnapshot | n
 	return list.at(-1) ?? null;
 }
 
+/**
+ * The window a previous process measured this session's prompts against, when
+ * the backend itself reported it as the one it had open (issue #227).
+ *
+ * A resumed session re-resolves its target before discovery has reported a
+ * loaded window, so the first turn budgets against the probed server-wide
+ * figure, which on a multi-slot backend is a multiple of what the model is
+ * actually serving. The snapshot ledger already recorded the number the
+ * backend named, so the resume carries it forward instead of re-probing.
+ * Scoped to the same target and model: a different selection has no claim on
+ * that measurement, and a live loaded window always outranks this one, so a
+ * model reloaded at a new size corrects on the next resolution.
+ */
+export function lastLoadedContextWindow(meta: SessionMeta, providerId: string, modelId: string): number | null {
+	const snapshots = getContextSnapshots(meta);
+	for (let i = snapshots.length - 1; i >= 0; i -= 1) {
+		const snapshot = snapshots[i];
+		if (snapshot?.contextWindowSource !== "loaded") continue;
+		if (snapshot.providerId !== providerId || snapshot.modelId !== modelId) continue;
+		const window = snapshot.effectiveContextWindow;
+		if (typeof window === "number" && Number.isFinite(window) && window > 0) return window;
+	}
+	return null;
+}
+
 export function buildSnapshotCategories(inputs: {
 	systemPrompt?: string | undefined;
 	promptSegments?: ReadonlyArray<{ id: string; tokenEstimate: number }> | undefined;
@@ -456,6 +494,7 @@ export function captureContextSnapshot(input: CaptureContextSnapshotInput): Cont
 		compactionThreshold: input.compactionThreshold,
 	});
 	return {
+		estimatedTokens: sumSplitTokens(categories),
 		snapshotId: nextSnapshotId(),
 		sessionId: input.sessionId,
 		turnId: input.turnId,
@@ -480,9 +519,13 @@ export function captureContextSnapshot(input: CaptureContextSnapshotInput): Cont
 	};
 }
 
+function sumSplitTokens(categories: ContextSnapshot["categories"]): number {
+	return SNAPSHOT_SPLIT_KEYS.reduce((sum, key) => sum + (categories[key] ?? 0), 0);
+}
+
 /** Sum of the prompt-side categories (everything except reserve/free/streaming). */
 export function snapshotInputTokens(snapshot: ContextSnapshot): number {
-	return SNAPSHOT_SPLIT_KEYS.reduce((sum, key) => sum + (snapshot.categories[key] ?? 0), 0);
+	return sumSplitTokens(snapshot.categories);
 }
 
 export function reconcileSnapshot(snapshot: ContextSnapshot, usage: Usage): ContextSnapshot {
@@ -572,9 +615,17 @@ export function reconcileSnapshot(snapshot: ContextSnapshot, usage: Usage): Cont
 		{} as Record<string, "estimated" | "exact" | "reconciled">,
 	);
 
+	// The estimate this snapshot was captured with, kept whole across repeated
+	// reconciles so the recorded divergence always compares the provider count
+	// against chars/4 rather than against a previously normalized total.
+	const estimatedTokens = snapshot.estimatedTokens ?? sumSplitTokens(snapshot.categories);
+
 	return {
 		...snapshot,
 		categories: updatedCategories,
+		estimatedTokens,
+		reconciledTokens: exactInput,
+		divergenceRatio: estimatedTokens > 0 ? Math.round((exactInput / estimatedTokens) * 1000) / 1000 : undefined,
 		sources: {
 			total: "reconciled",
 			splits: splitsSources,

package/src/domains/session/context-ledger.ts

@@ -16,6 +16,7 @@
  * proportional reconciliation the footer bar already performs.
  */
 
+import type { BackendCacheVerdict, BackendCompletionTimings } from "../../core/cache-telemetry.js";
 import type { ContextWindowSlots, ContextWindowSource } from "../providers/index.js";
 import { DEFAULT_COMPACTION_THRESHOLD } from "./compaction/auto.js";
 
@@ -100,6 +101,22 @@ export interface BuildContextLedgerInput {
 	} | null;
 	/** Prompt-cache honesty line; null until a turn has compiled and settled. */
 	promptCache?: PromptCacheStats | null;
+	/** Last pre-warm since the previous settled run; null when none has run. */
+	prewarm?: PrewarmStats | null;
+}
+
+/**
+ * One pre-warm's result. It is deliberately not a token category: the pre-warm
+ * spends no window space and adds no message, it only says the backend has
+ * already prefilled the prefix the next turn will send.
+ */
+export interface PrewarmStats {
+	/** Prompt tokens the backend processed; null when it reported no counts. */
+	tokens: number | null;
+	/** Wall clock the round took. */
+	ms: number;
+	/** True when the operator submitted before the round settled. */
+	aborted: boolean;
 }
 
 /**
@@ -117,13 +134,17 @@ export interface PromptCacheStats {
 	cacheWriteTokens: number | null;
 	/** Provider-reported uncached input tokens for the last run. */
 	uncachedInputTokens: number | null;
+	/** Serving-backend timings for the run's last API call; null when none were captured. */
+	backend: BackendCompletionTimings | null;
+	/** Backend prompt tokens not served from cache, derived only when cache reads were reported. */
+	uncachedPrefillTokens: number | null;
 	/**
-	 * Cache verdict of the run's first API call, classified from the
-	 * provider-reported usage by `backendCacheVerdict`. Null before any
-	 * settled run. "Shell reused but backend cold" is the dishonest
-	 * combination the overlay renders as a warning.
+	 * Cache verdict of the run's first API call, classified by
+	 * `backendCacheVerdict` from normalized provider usage and captured serving
+	 * backend timings when available. Null before any settled run. "Shell reused
+	 * but backend cold" is the dishonest combination the overlay warns about.
 	 */
-	backendVerdict: "hot" | "partial" | "cold" | "small" | null;
+	backendVerdict: BackendCacheVerdict | null;
 	/** Cache disturbances Clio expected before the last settled run. */
 	expectedColdReasons?: ReadonlyArray<string>;
 }
@@ -185,6 +206,8 @@ export interface ContextLedger {
 		trigger: string;
 	} | null;
 	promptCache: PromptCacheStats | null;
+	/** Last pre-warm since the previous settled run; null when none has run. */
+	prewarm: PrewarmStats | null;
 }
 
 /** Maps a prompt segment id to the ledger bucket it belongs to. */
@@ -332,14 +355,6 @@ export function buildContextLedger(input: BuildContextLedgerInput): ContextLedge
 	}
 
 	const meter: ContextLedgerGroup[] = [...groups];
-	if (reserveTokens > 0) {
-		meter.push({
-			category: "reserve",
-			label: CONTEXT_CATEGORY_LABEL.reserve,
-			tokens: reserveTokens,
-			percent: percentOf(reserveTokens, window),
-		});
-	}
 	if (window > 0) {
 		meter.push({
 			category: "free",
@@ -348,6 +363,14 @@ export function buildContextLedger(input: BuildContextLedgerInput): ContextLedge
 			percent: percentOf(freeTokens, window),
 		});
 	}
+	if (reserveTokens > 0) {
+		meter.push({
+			category: "reserve",
+			label: CONTEXT_CATEGORY_LABEL.reserve,
+			tokens: reserveTokens,
+			percent: percentOf(reserveTokens, window),
+		});
+	}
 
 	return {
 		provider: input.provider ?? null,
@@ -369,5 +392,6 @@ export function buildContextLedger(input: BuildContextLedgerInput): ContextLedge
 		meter,
 		lastCompaction: input.lastCompaction ?? null,
 		promptCache: input.promptCache ?? null,
+		prewarm: input.prewarm ?? null,
 	};
 }

package/src/domains/session/index.ts

@@ -61,6 +61,12 @@ export type {
 export { isSessionEntry, isSessionHeader, SESSION_ENTRY_KINDS } from "./entries.js";
 export { SessionManifest } from "./manifest.js";
 export { CURRENT_SESSION_FORMAT_VERSION, runMigrations } from "./migrations/index.js";
+export type { ExpectedColdReasonCount, PromptCacheTelemetry } from "./prompt-cache.js";
+export {
+	foldPromptCacheTelemetry,
+	hasPromptCacheTelemetry,
+	topExpectedColdReason,
+} from "./prompt-cache.js";
 export {
 	protectedArtifactEntryFromArtifact,
 	protectedArtifactFromSessionEntry,

package/src/domains/session/prompt-cache.ts

@@ -0,0 +1,140 @@
+import {
+	type BackendCacheVerdict,
+	type BackendCompletionTimings,
+	type CacheVerdictCounts,
+	emptyCacheVerdictCounts,
+	uncachedPrefillTokens,
+} from "../../core/cache-telemetry.js";
+import type { SessionEntry } from "./entries.js";
+
+/** Durable prompt-cache facts folded across assistant calls in one ledger slice. */
+export interface PromptCacheTelemetry {
+	/** Sum of authoritative backend prefill work, or null when no call reported cache reads. */
+	uncachedPrefillTokens: number | null;
+	/** Calls contributing to `uncachedPrefillTokens`; distinguishes no evidence from a measured zero. */
+	uncachedPrefillCalls: number;
+	/** Counts of the verdict persisted on each assistant call. */
+	verdictCounts: CacheVerdictCounts;
+	/** Number of assistant calls carrying a recognized persisted verdict. */
+	verdictCalls: number;
+	/** How often each expected cache disturbance was stamped. */
+	expectedColdReasonCounts: Readonly<Record<string, number>>;
+}
+
+export interface ExpectedColdReasonCount {
+	reason: string;
+	count: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function finiteNonNegative(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function backendTimings(value: unknown): BackendCompletionTimings | null {
+	if (!isRecord(value)) return null;
+	if (
+		!finiteNonNegative(value.promptTokens) ||
+		!finiteNonNegative(value.predictedTokens) ||
+		!finiteNonNegative(value.promptMs) ||
+		!finiteNonNegative(value.predictedMs) ||
+		(value.source !== "llamacpp-timings" && value.source !== "lmstudio-timings")
+	) {
+		return null;
+	}
+	const cachedTokens = value.cachedTokens;
+	if (cachedTokens !== null && !finiteNonNegative(cachedTokens)) return null;
+	if (typeof cachedTokens === "number" && cachedTokens > value.promptTokens) return null;
+	return {
+		promptTokens: value.promptTokens,
+		cachedTokens,
+		predictedTokens: value.predictedTokens,
+		promptMs: value.promptMs,
+		predictedMs: value.predictedMs,
+		source: value.source,
+	};
+}
+
+function cacheVerdict(value: unknown): BackendCacheVerdict | null {
+	switch (value) {
+		case "hot":
+		case "partial":
+		case "cold":
+		case "small":
+			return value;
+		default:
+			return null;
+	}
+}
+
+/** True when the fold contains at least one durable cache fact. */
+export function hasPromptCacheTelemetry(telemetry: PromptCacheTelemetry): boolean {
+	return (
+		telemetry.verdictCalls > 0 ||
+		telemetry.uncachedPrefillCalls > 0 ||
+		Object.keys(telemetry.expectedColdReasonCounts).length > 0
+	);
+}
+
+/** Most frequent expected disturbance, with deterministic lexical tie-breaking. */
+export function topExpectedColdReason(telemetry: PromptCacheTelemetry): ExpectedColdReasonCount | null {
+	const ranked = Object.entries(telemetry.expectedColdReasonCounts).sort(
+		([leftReason, leftCount], [rightReason, rightCount]) =>
+			rightCount - leftCount || leftReason.localeCompare(rightReason),
+	);
+	const first = ranked[0];
+	return first === undefined ? null : { reason: first[0], count: first[1] };
+}
+
+/**
+ * Fold persisted assistant `promptCache` payloads without reclassifying them.
+ * Callers provide the ledger slice they mean, such as one active branch or one
+ * report window, so every surface shares parsing while retaining its own scope.
+ */
+export function foldPromptCacheTelemetry(entries: ReadonlyArray<SessionEntry>): PromptCacheTelemetry {
+	const verdictCounts = emptyCacheVerdictCounts();
+	const expectedColdReasonCounts: Record<string, number> = {};
+	let verdictCalls = 0;
+	let uncachedTotal = 0;
+	let uncachedPrefillCalls = 0;
+
+	for (const entry of entries) {
+		if (entry.kind !== "message" || entry.role !== "assistant" || !isRecord(entry.payload)) continue;
+		const promptCache = entry.payload.promptCache;
+		if (!isRecord(promptCache)) continue;
+
+		const verdict = cacheVerdict(promptCache.backendVerdict);
+		if (verdict !== null) {
+			verdictCounts[verdict] += 1;
+			verdictCalls += 1;
+		}
+
+		const backend = backendTimings(promptCache.backend);
+		const uncached = uncachedPrefillTokens(backend);
+		if (uncached !== null) {
+			uncachedTotal += uncached;
+			uncachedPrefillCalls += 1;
+		}
+
+		if (!Array.isArray(promptCache.expectedColdReasons)) continue;
+		const reasons = new Set(
+			promptCache.expectedColdReasons.filter(
+				(reason): reason is string => typeof reason === "string" && reason.trim().length > 0,
+			),
+		);
+		for (const reason of reasons) {
+			expectedColdReasonCounts[reason] = (expectedColdReasonCounts[reason] ?? 0) + 1;
+		}
+	}
+
+	return {
+		uncachedPrefillTokens: uncachedPrefillCalls > 0 ? uncachedTotal : null,
+		uncachedPrefillCalls,
+		verdictCounts,
+		verdictCalls,
+		expectedColdReasonCounts,
+	};
+}