@iowarp/clio-coder 0.3.8 → 0.4.0

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/resources/skills/loader.ts

@@ -893,6 +893,39 @@ export function modelVisibleSkills(skills: ReadonlyArray<Skill>): Skill[] {
 	return skills.filter((skill) => skill.trusted && !skill.disableModelInvocation);
 }
 
+/** Why a loaded skill catalog is not valid. Ordered by which failure to report first. */
+export type SkillCatalogInvalidReason = "load-error" | "collision" | "unloadable-file" | "no-skills";
+
+export interface SkillCatalogValidity {
+	ok: boolean;
+	reason: SkillCatalogInvalidReason | null;
+}
+
+/**
+ * The rule `clio-coder skills validate` applies, in one place.
+ *
+ * A scanned file that produced no loaded skill is malformed, and a collision
+ * drops a skill: both make the catalog invalid, as does any hard error. Benign
+ * warnings (name/path mismatch, name format, description length) attach to a
+ * file that still loaded, so their path is among the loaded skills and they do
+ * not fail validation.
+ *
+ * Lives here rather than in the CLI because two callers now need the same
+ * answer, and a verdict that drifts between the terminal and a GUI is worse
+ * than no verdict at all.
+ */
+export function skillCatalogValidity(list: SkillList): SkillCatalogValidity {
+	if (list.diagnostics.some((diag) => diag.type === "error")) return { ok: false, reason: "load-error" };
+	if (list.diagnostics.some((diag) => diag.type === "collision")) return { ok: false, reason: "collision" };
+	const loadedPaths = new Set(list.items.map((skill) => skill.filePath));
+	const unloadable = list.diagnostics.some(
+		(diag) => diag.type === "warning" && diag.path !== undefined && !loadedPaths.has(diag.path),
+	);
+	if (unloadable) return { ok: false, reason: "unloadable-file" };
+	if (list.items.length === 0) return { ok: false, reason: "no-skills" };
+	return { ok: true, reason: null };
+}
+
 export function parseSkillCommand(input: string): { name: string; args: string } | null {
 	const trimmed = input.trim();
 	if (!trimmed.startsWith("/skill ")) return null;

package/src/domains/safety/action-classifier.ts

@@ -104,6 +104,12 @@ function baseClassify(tool: string): ActionClass | null {
 		// local mirror. Neither touches the workspace, so it is never gated
 		// behind a confirmation.
 		case ToolNames.Ledger:
+		// panes focuses, opens, and closes terminal panes Clio itself created, in
+		// a pane host that lives outside the workspace. Nothing it does writes a
+		// file, runs a model-supplied command (its schema exposes presets only),
+		// or survives the session, so it is reversible, local, and never gated
+		// behind a confirmation.
+		case ToolNames.Panes:
 			return "read";
 		case ToolNames.Write:
 		case ToolNames.Edit:

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,