@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/interactive/chat-panel.ts

@@ -2,7 +2,7 @@ import { performance } from "node:perf_hooks";
 import type { OutputVerbosity } from "../core/defaults.js";
 import { SKILL_SUGGESTION_PREFIX } from "../core/skill-activation.js";
 import { rawDurationMs } from "../core/timers.js";
-import { type Component, Markdown, truncateToWidth, wrapTextWithAnsi } from "../engine/tui.js";
+import { type Component, Markdown, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../engine/tui.js";
 import type { AgentMessage } from "../engine/types.js";
 import { toolPresentationPolicy } from "../tools/presentation.js";
 import { toolResultPresentationPolicy } from "../tools/result-disposition.js";
@@ -252,7 +252,7 @@ type ReplayBlockRenderer = (width: number, detail: TranscriptDetailPolicy) => st
 type AssistantStatusLine = { phase: StatusPhase; verb: string; toneHint: VerbRender["toneHint"] };
 
 type TranscriptEntry =
-	| { role: "user"; text: string }
+	| { role: "user"; text: string; status?: () => UserTurnStatus }
 	| { role: "retryStatus"; status: RetryStatusPayload }
 	| {
 			role: "assistant";
@@ -308,8 +308,20 @@ export interface ReplayBlockFoldControl {
 	setFold(fold: FoldOverride): void;
 }
 
+/**
+ * Whether a painted operator turn exists in the ledger yet. `pending` is the
+ * window between the editor being consumed and admission; `refused` is a
+ * submit that never reached the durable append.
+ */
+export type UserTurnStatus = "pending" | "committed" | "refused";
+
 export interface ChatPanel extends Component {
-	appendUser(text: string): void;
+	/**
+	 * Paint an operator turn. `status`, when given, is read every frame while it
+	 * reports anything but `committed`, so the row the transcript shows before
+	 * admission is visibly not the durable turn it will become.
+	 */
+	appendUser(text: string, status?: () => UserTurnStatus): void;
 	/**
 	 * Append a caller-rendered block. Pass `isLive` when the closure reads state
 	 * that keeps changing after the append, so the panel keeps re-rendering it
@@ -675,6 +687,20 @@ function renderErrorSegmentLines(seg: ErrorSegment, width: number): string[] {
 const CLIO_PREFIX = `${TEAL}${AGENT_GLYPH}${RESET} `;
 const CLIO_PREFIX_ERROR = `${RED_CRIT}${AGENT_GLYPH}${RESET} `;
 const USER_PREFIX = `${TEAL}${USER_GLYPH}${RESET} `;
+/**
+ * A prompt Clio has taken but not yet committed. The glyph is dim rather than
+ * teal and the row says so, because the transcript used to paint an
+ * uncommitted prompt exactly like a durable user turn while the ledger still
+ * had no entry for it (issue #251).
+ */
+const USER_PREFIX_PENDING = `${DIM}${USER_GLYPH}${RESET} `;
+/**
+ * The uncommitted-row tails, stored as plain text so their width can be spent
+ * against the row's budget before the dim codes go on. Both begin with the
+ * separating space they carry when they ride on the end of a body line.
+ */
+const USER_PENDING_TAIL = " · preparing";
+const USER_REFUSED_TAIL = " · not sent";
 const PROSE_GUTTER = "  ";
 const PROSE_GUTTER_WIDTH = 2;
 
@@ -688,6 +714,30 @@ function hangProseLines(lines: string[], firstPrefix?: string): string[] {
 	return lines.map((line, index) => `${index === 0 && firstPrefix !== undefined ? firstPrefix : PROSE_GUTTER}${line}`);
 }
 
+/**
+ * Put an uncommitted row's status tail on the row without letting it push a
+ * line past the terminal. The tail used to be concatenated onto the last
+ * rendered line unconditionally, so a body that had already folded near the
+ * content width came out up to 12 cells past the terminal, and pi-tui's
+ * `doRender` throws on an overlong line and kills the process. A `/share` of
+ * a worker answer is the ordinary way to hit that: a `research-report` body is
+ * JSON with no space to fold at, so an 80-column pane died on any shared body
+ * over 58 columns (#257).
+ *
+ * The tail rides on the last body line when that line has room for it, and
+ * drops to its own hanging row when it does not, so it stays whole either way
+ * rather than breaking between `·` and the word.
+ */
+function appendUserRowTail(rendered: string[], tail: string, width: number): void {
+	const last = rendered.length - 1;
+	const lastLine = rendered[last];
+	if (lastLine !== undefined && visibleWidth(lastLine) + tail.length <= width) {
+		rendered[last] = `${lastLine}${DIM}${tail}${RESET}`;
+		return;
+	}
+	rendered.push(`${PROSE_GUTTER}${dimLine(tail.trimStart(), Math.max(1, width - PROSE_GUTTER_WIDTH))}`);
+}
+
 /**
  * Static marker used when thinking is folded. This matches pi-coding-agent's
  * hidden-thinking presentation and avoids previewing reasoning content.
@@ -964,8 +1014,11 @@ function renderEntryLines(
 		const contentWidth = Math.max(1, width - PROSE_GUTTER_WIDTH);
 		const lines: string[] = [];
 		for (const sourceLine of entry.text.split("\n")) lines.push(...wrapTextWithAnsi(sourceLine, contentWidth));
-		const rendered = hangProseLines(lines, USER_PREFIX);
+		const status = entry.status?.() ?? "committed";
+		const rendered = hangProseLines(lines, status === "committed" ? USER_PREFIX : USER_PREFIX_PENDING);
 		if (rendered[0] !== undefined) rendered[0] = `${OSC133_PROMPT_START}${rendered[0]}`;
+		if (status !== "committed")
+			appendUserRowTail(rendered, status === "pending" ? USER_PENDING_TAIL : USER_REFUSED_TAIL, width);
 		return rendered;
 	}
 	if (entry.role === "retryStatus") {
@@ -1450,7 +1503,8 @@ export function createChatPanel(options: ChatPanelOptions = {}): ChatPanel {
 				// only thinking still needs the time-keyed render key.
 			) ||
 				(entry.pending && openThinkingSegment(entry)?.startedAtMs !== undefined))) ||
-		(entry.role === "replayBlock" && entry.isLive?.() === true);
+		(entry.role === "replayBlock" && entry.isLive?.() === true) ||
+		(entry.role === "user" && (entry.status?.() ?? "committed") !== "committed");
 
 	/**
 	 * Settled entries whose render is a pure function of the base key. A live
@@ -1460,7 +1514,7 @@ export function createChatPanel(options: ChatPanelOptions = {}): ChatPanel {
 	 * declares itself live is excluded on the same grounds.
 	 */
 	const entryIsStable = (entry: TranscriptEntry): boolean =>
-		entry.role === "user" ||
+		(entry.role === "user" && (entry.status?.() ?? "committed") === "committed") ||
 		(entry.role === "replayBlock" && entry.isLive?.() !== true) ||
 		(entry.role === "worker" && !entry.state.pending) ||
 		(entry.role === "assistant" &&
@@ -1593,8 +1647,8 @@ export function createChatPanel(options: ChatPanelOptions = {}): ChatPanel {
 	};
 
 	return {
-		appendUser(text: string): void {
-			transcript.push({ role: "user", text });
+		appendUser(text: string, status?: () => UserTurnStatus): void {
+			transcript.push({ role: "user", text, ...(status ? { status } : {}) });
 			markDirty();
 		},
 		appendReplayBlock(renderBlock: ReplayBlockRenderer, isLive?: () => boolean, fold?: ReplayBlockFoldControl): void {

package/src/interactive/clio-editor.ts

@@ -1,12 +1,15 @@
 import { Editor, stripTerminalSequences, type TUI, truncateToWidth, visibleWidth } from "../engine/tui.js";
 import { fitHintEntries } from "./overlay-frame.js";
-import { permissionHintEntries } from "./permission-hint.js";
+import { type PermissionInspectionHint, permissionHintEntries } from "./permission-hint.js";
 import type { ClioTheme } from "./theme/index.js";
 import { clioTheme, editorTheme, GLYPH, rule } from "./theme/index.js";
+import type { TurnPreparationPhase } from "./turn-state.js";
 
 const REVERSE_VIDEO_BLANK = `${String.fromCharCode(27)}[7m ${String.fromCharCode(27)}[0m`;
 const EMPTY_PROMPT = "Ask Clio…  / for commands";
 const CONFIRM_PROMPT = "A parked call is waiting for your decision";
+const PREPARING_PROMPT = "Clio has your prompt and is preparing the turn";
+const COMPACTING_PROMPT = "Clio has your prompt and is compacting the context first";
 const MIN_HINT_WIDTH = 60;
 
 function hasScrollIndicator(line: string): boolean {
@@ -28,6 +31,19 @@ export interface EditorChrome {
 	 * dialog's keys whenever the prompt owns input (issues #186 and #194).
 	 */
 	isAwaitingApproval?: () => boolean;
+	/**
+	 * Whether that prompt is a mutation the operator can read locally, and
+	 * whether it is open. The rail carries the dialog's keys, so it names the
+	 * inspect key on exactly the cards that have one (issue #254).
+	 */
+	getPermissionInspection?: () => PermissionInspectionHint;
+	/**
+	 * Where a consumed prompt is between the editor and the stream. The editor
+	 * is cleared before admission, so without this the composer went straight
+	 * back to `MESSAGE` and a 77-second pre-submit compaction was
+	 * indistinguishable from a dropped Enter (issue #251).
+	 */
+	getTurnPreparation?: () => TurnPreparationPhase;
 	/** Whether the current draft will actually steer Clio or live dispatch work on Enter. */
 	willEnterSteer?: (text: string) => boolean;
 	/** Resolved submit binding, formatted for display. */
@@ -36,7 +52,7 @@ export interface EditorChrome {
 	getNewlineKeyLabel?: () => string;
 }
 
-type ComposerMode = "MESSAGE" | "FOLLOW-UP" | "STEER" | "CONFIRM";
+type ComposerMode = "MESSAGE" | "FOLLOW-UP" | "STEER" | "CONFIRM" | "PREPARING" | "COMPACTING";
 
 function normalizeThinkingHint(value: string): string {
 	return value
@@ -72,7 +88,15 @@ function styledRailLabel(theme: ClioTheme, chrome: EditorChrome): string {
 
 function composerMode(chrome: EditorChrome, text: string): ComposerMode {
 	if (chrome.isAwaitingApproval?.() ?? false) return "CONFIRM";
-	if (!(chrome.isStreaming?.() ?? false)) return "MESSAGE";
+	if (!(chrome.isStreaming?.() ?? false)) {
+		// A prompt Clio is holding is not an idle composer. Streaming outranks it
+		// because a steer typed during a live run is what the rail is for, and a
+		// steer's own submit passes through this window on its way to the queue.
+		const preparation = chrome.getTurnPreparation?.() ?? "idle";
+		if (preparation === "compacting") return "COMPACTING";
+		if (preparation === "preparing") return "PREPARING";
+		return "MESSAGE";
+	}
 	const willSteer = chrome.willEnterSteer?.(text) ?? text.trim().length > 0;
 	return willSteer ? "STEER" : "FOLLOW-UP";
 }
@@ -89,16 +113,29 @@ function lowerRailHint(theme: ClioTheme, chrome: EditorChrome): string {
  * both surfaces narrow in the same order and never drop allow or stop first.
  * The rule spends three columns around a right label, hence the subtraction.
  */
-function confirmRailHint(theme: ClioTheme, width: number, hasDraft: boolean): string {
-	return theme.fg("warning", fitHintEntries(permissionHintEntries(hasDraft), Math.max(1, width - 3)));
+function confirmRailHint(
+	theme: ClioTheme,
+	width: number,
+	hasDraft: boolean,
+	inspection: PermissionInspectionHint,
+): string {
+	return theme.fg("warning", fitHintEntries(permissionHintEntries(hasDraft, inspection), Math.max(1, width - 3)));
 }
 
 function modeToken(mode: ComposerMode): "action" | "accentDeep" | "warning" {
-	if (mode === "STEER") return "action";
+	if (mode === "STEER" || mode === "PREPARING" || mode === "COMPACTING") return "action";
 	if (mode === "CONFIRM") return "warning";
 	return "accentDeep";
 }
 
+/** The line the empty composer shows for the mode it is in. */
+function emptyPromptFor(mode: ComposerMode): string {
+	if (mode === "CONFIRM") return CONFIRM_PROMPT;
+	if (mode === "PREPARING") return PREPARING_PROMPT;
+	if (mode === "COMPACTING") return COMPACTING_PROMPT;
+	return EMPTY_PROMPT;
+}
+
 function renderEmptyPrompt(line: string, width: number, theme: ClioTheme, text = EMPTY_PROMPT): string {
 	const cursorAt = line.indexOf(REVERSE_VIDEO_BLANK);
 	if (cursorAt < 0) return line;
@@ -151,7 +188,7 @@ export class ClioEditor extends Editor {
 		}
 
 		if (text.length === 0 && lines[1]) {
-			lines[1] = renderEmptyPrompt(lines[1], safeWidth, theme, mode === "CONFIRM" ? CONFIRM_PROMPT : EMPTY_PROMPT);
+			lines[1] = renderEmptyPrompt(lines[1], safeWidth, theme, emptyPromptFor(mode));
 		}
 
 		const bottomRail = findBottomRail(lines, safeWidth);
@@ -159,7 +196,7 @@ export class ClioEditor extends Editor {
 		// that a narrow composer can drop, the allow and deny keys are not.
 		if (bottomRail >= 0 && mode === "CONFIRM") {
 			lines[bottomRail] = rule(theme, safeWidth, {
-				right: confirmRailHint(theme, safeWidth, text.length > 0),
+				right: confirmRailHint(theme, safeWidth, text.length > 0, this.chrome.getPermissionInspection?.() ?? "none"),
 				fillToken: "frameStrong",
 				rightRaw: true,
 				rightTail: theme.style("frameStrong", "─", { bold: true }),

package/src/interactive/context-activity.ts

@@ -32,6 +32,8 @@ const PHASES: ReadonlyArray<ContextActivityPhase> = ["scan", "codewiki", "genera
  * happen.
  */
 const WIKI_PHASES: ReadonlyArray<ContextActivityPhase> = ["codewiki", "generate", "state", "done"];
+/** Compaction is one bounded operation, not the five-stage context-init pipeline. */
+const COMPACTION_PHASES: ReadonlyArray<ContextActivityPhase> = ["compact", "done"];
 const PHASE_LABELS: Record<ContextActivityPhase, string> = {
 	scan: "scan",
 	// "index" rather than "wiki": this phase is the codewiki index build, and
@@ -40,6 +42,7 @@ const PHASE_LABELS: Record<ContextActivityPhase, string> = {
 	generate: "draft",
 	"clio-md": "CLIO-CODER.md",
 	state: "state",
+	compact: "compact",
 	done: "done",
 };
 const WIKI_PHASE_LABELS: Partial<Record<ContextActivityPhase, string>> = {
@@ -55,9 +58,10 @@ const KINDS: ReadonlySet<string> = new Set<ContextActivityKind>([
 	"context-wiki",
 	"compaction",
 ]);
-const PHASE_SET: ReadonlySet<string> = new Set<ContextActivityPhase>(PHASES);
+const PHASE_SET: ReadonlySet<string> = new Set<ContextActivityPhase>([...PHASES, ...COMPACTION_PHASES]);
 
 function phasesFor(kind: ContextActivityKind): ReadonlyArray<ContextActivityPhase> {
+	if (kind === "compaction") return COMPACTION_PHASES;
 	return kind === "context-wiki" ? WIKI_PHASES : PHASES;
 }
 

package/src/interactive/context-meter.ts

@@ -18,7 +18,7 @@ export const CONTEXT_CATEGORY_TOKEN: Readonly<Record<ContextLedgerCategory, Clio
 	project: "muted",
 	messages: "accent",
 	pending: "accentDeep",
-	reserve: "dim",
+	reserve: "frame",
 	free: "frame",
 	streaming: "accent",
 };

package/src/interactive/context-overlay.ts

@@ -77,7 +77,7 @@ function legendRow(group: ContextLedgerGroup, contentWidth: number): string {
 	const tokens = formatTokens(group.tokens);
 	const percent = formatContextPercent(group.percent);
 	const right = `${tokens.padStart(9)}  ${percent.padStart(6)}`;
-	const labelToken: ClioToken = group.category === "free" || group.category === "reserve" ? "dim" : "muted";
+	const labelToken: ClioToken = group.category === "reserve" ? "frame" : group.category === "free" ? "dim" : "muted";
 	const leftWidth = Math.max(0, contentWidth - visibleWidth(right) - 2);
 	const labelText = group.label.length > leftWidth ? group.label.slice(0, leftWidth) : group.label.padEnd(leftWidth);
 	return `${swatch} ${theme.fg(labelToken, labelText)} ${theme.fg("muted", right)}`;
@@ -108,6 +108,16 @@ function coldReasonLabel(reason: string): string {
 			return "compaction";
 		case "dispatch":
 			return "dispatch traffic";
+		case "residency":
+			return "residency change";
+		case "thinking_change":
+			return "thinking-level change";
+		case "tool_surface_change":
+			return "tool-surface change";
+		case "prompt_recompiled":
+			return "prompt recompile";
+		case "background_memory":
+			return "background memory step";
 		default:
 			return reason;
 	}
@@ -221,8 +231,10 @@ export function renderContextLedgerLines(
 	if (ledger.promptCache) {
 		const cache = ledger.promptCache;
 		const shell = cache.shellReused ? "shell reused" : "shell recompiled";
-		const backend =
-			cache.backendVerdict === "hot" || cache.backendVerdict === "partial"
+		const backendCacheReadsUnknown = cache.backend?.cachedTokens === null;
+		const backend = backendCacheReadsUnknown
+			? "server does not report cache reads"
+			: cache.backendVerdict === "hot" || cache.backendVerdict === "partial"
 				? "backend reused"
 				: cache.backendVerdict === "cold"
 					? "backend cold"
@@ -232,24 +244,42 @@ export function renderContextLedgerLines(
 		const read = cache.cacheReadTokens !== null ? `cache read ${formatTokens(cache.cacheReadTokens)}` : "cache read n/a";
 		const uncached =
 			cache.uncachedInputTokens !== null ? `uncached input ${formatTokens(cache.uncachedInputTokens)}` : null;
-		const line = ["prompt cache:", shell, "·", backend, "·", read, ...(uncached ? ["·", uncached] : [])].join(" ");
-		// Reasons Clio recorded before the run: working-set eviction, summary
-		// compaction, and dispatch traffic all move the byte prefix a local
-		// single-slot backend caches, so a cold turn after one of them is the
-		// expected outcome rather than a provider surprise.
-		const coldReasons = cache.backendVerdict === "cold" ? (cache.expectedColdReasons ?? []) : [];
+		const line = backendCacheReadsUnknown
+			? ["prompt cache:", shell, "·", backend].join(" ")
+			: ["prompt cache:", shell, "·", backend, "·", read, ...(uncached ? ["·", uncached] : [])].join(" ");
+		// Reasons Clio recorded before the run describe either prefix-byte changes
+		// or local-server activity that displaced the cached prefix. A cold turn
+		// after one of them is expected rather than a provider surprise.
+		const coldReasons =
+			cache.backendVerdict === "cold" && !backendCacheReadsUnknown ? (cache.expectedColdReasons ?? []) : [];
 		// A reused shell with a cold backend means Clio kept the bytes stable
 		// but the provider re-prefilled anyway; surface that disagreement
 		// instead of hiding it. An expected reason explains the same numbers, so
 		// it is reported on its own line and not as a warning.
-		const misleading = cache.shellReused && cache.backendVerdict === "cold" && coldReasons.length === 0;
+		const misleading =
+			cache.shellReused && cache.backendVerdict === "cold" && !backendCacheReadsUnknown && coldReasons.length === 0;
 		lines.push(theme.fg(misleading ? "warning" : "dim", line));
+		if (cache.backend) {
+			const prefill =
+				cache.backend.cachedTokens !== null && cache.uncachedPrefillTokens !== null
+					? `prefill: ${formatTokens(cache.uncachedPrefillTokens)} uncached · ${formatTokens(cache.backend.cachedTokens)} cached · ${formatTokens(cache.backend.promptMs)} ms`
+					: `prefill: ${formatTokens(cache.backend.promptTokens)} prompt · ${formatTokens(cache.backend.promptMs)} ms`;
+			lines.push(theme.fg("dim", prefill));
+		}
 		if (coldReasons.length > 0) {
 			const reasons = coldReasons.map(coldReasonLabel).join(", ");
 			lines.push(theme.fg("dim", `last cold turn: ${reasons} (expected)`));
 		}
 	}
 
+	if (ledger.prewarm) {
+		// What the backend has already prefilled for the turn the operator has not
+		// typed yet. It survives until the next settled run answers the question.
+		const tokens = ledger.prewarm.tokens !== null ? `${formatTokens(ledger.prewarm.tokens)} tokens` : "prefix";
+		const aborted = ledger.prewarm.aborted ? " (aborted on submit; prefix stays in the slot)" : "";
+		lines.push(theme.fg("dim", `prewarmed: ${tokens} in ${formatTokens(ledger.prewarm.ms)} ms${aborted}`));
+	}
+
 	if (ledger.lastCompaction) {
 		const pruneInfo = `last compaction: reclaimed ${formatTokens(ledger.lastCompaction.tokensBefore)} -> ${formatTokens(ledger.lastCompaction.tokensAfter)} tokens (${ledger.lastCompaction.stage})`;
 		lines.push(theme.fg("dim", pruneInfo));
@@ -300,6 +330,7 @@ export function openContextOverlay(
 	const handle = showClioOverlayFrame(tui, text, {
 		anchor: "center",
 		width: CONTEXT_OVERLAY_WIDTH,
+		markerId: "context-view",
 		title: "Context Window",
 		footerHint: buildHint([]),
 	});

package/src/interactive/cost-overlay.ts

@@ -11,6 +11,12 @@ import {
 	type ObservabilityContract,
 	type ObservabilitySnapshot,
 } from "../domains/observability/index.js";
+import {
+	foldPromptCacheTelemetry,
+	hasPromptCacheTelemetry,
+	type PromptCacheTelemetry,
+	type SessionEntry,
+} from "../domains/session/index.js";
 import type { Component, OverlayHandle, TUI } from "../engine/tui.js";
 import { buildHint, showClioOverlayFrame } from "./overlay-frame.js";
 import { clioTheme, rule } from "./theme/index.js";
@@ -36,6 +42,10 @@ export interface CostRow {
 	sideQuestions: number;
 	/** Calls in this row that were `/handoff` extraction rounds rather than turns. */
 	handoffs: number;
+	/** Calls in this row that were session pre-warms rather than turns. */
+	prewarms: number;
+	/** Calls in this row that were proactive-memory steps on the background target. */
+	backgroundMemory: number;
 	cost: CostAggregate;
 }
 
@@ -67,6 +77,8 @@ export function aggregateCostEntries(entries: ReadonlyArray<CostEntry>): CostRow
 			existing.row.apiCalls += entry.apiCalls ?? 1;
 			if (entry.label === "side-question") existing.row.sideQuestions += 1;
 			if (entry.label === "handoff") existing.row.handoffs += 1;
+			if (entry.label === "prewarm") existing.row.prewarms += 1;
+			if (entry.label === "background-memory") existing.row.backgroundMemory += 1;
 			for (const requestedModelId of entry.requestedModelIds) existing.requestedModelIds.add(requestedModelId);
 			addResponseModelIdObservationCounts(
 				existing.responseModelIdObservationCounts,
@@ -89,6 +101,8 @@ export function aggregateCostEntries(entries: ReadonlyArray<CostEntry>): CostRow
 				apiCalls: entry.apiCalls ?? 1,
 				sideQuestions: entry.label === "side-question" ? 1 : 0,
 				handoffs: entry.label === "handoff" ? 1 : 0,
+				prewarms: entry.label === "prewarm" ? 1 : 0,
+				backgroundMemory: entry.label === "background-memory" ? 1 : 0,
 			},
 			requestedModelIds: new Set(entry.requestedModelIds),
 			responseModelIdObservationCounts: { ...entry.responseModelIdObservationCounts },
@@ -127,6 +141,8 @@ function sumRows(
 			apiCalls: acc.apiCalls + row.apiCalls,
 			sideQuestions: acc.sideQuestions + row.sideQuestions,
 			handoffs: acc.handoffs + row.handoffs,
+			prewarms: acc.prewarms + row.prewarms,
+			backgroundMemory: acc.backgroundMemory + row.backgroundMemory,
 		}),
 		{
 			runs: 0,
@@ -139,6 +155,8 @@ function sumRows(
 			apiCalls: 0,
 			sideQuestions: 0,
 			handoffs: 0,
+			prewarms: 0,
+			backgroundMemory: 0,
 		},
 	);
 }
@@ -179,7 +197,12 @@ function kvBlock(entries: ReadonlyArray<readonly [string, string, string?]>): st
 	});
 }
 
-function summaryBlock(totalCost: CostAggregate, totalTokens: number, rows: ReadonlyArray<CostRow>): string[] {
+function summaryBlock(
+	totalCost: CostAggregate,
+	totalTokens: number,
+	rows: ReadonlyArray<CostRow>,
+	promptCache: PromptCacheTelemetry | null,
+): string[] {
 	const totals = sumRows(rows);
 	const resolvedTotal = totalTokens > 0 ? totalTokens : totals.tokens;
 	// No priced call, no cost row: neither the `cost $0.00` the overlay used to
@@ -190,17 +213,36 @@ function summaryBlock(totalCost: CostAggregate, totalTokens: number, rows: Reado
 	// A side question is billed like anything else and is counted here, but it is
 	// deliberately not a turn: it never entered the session, so `turns` above
 	// excludes it and this row says how much of the spend sat beside the session.
+	const cacheRows =
+		promptCache !== null && hasPromptCacheTelemetry(promptCache)
+			? [
+					[
+						"uncached prefill",
+						promptCache.uncachedPrefillTokens === null ? "not reported" : formatTokens(promptCache.uncachedPrefillTokens),
+					] as const,
+					[
+						"cache verdicts",
+						`hot ${promptCache.verdictCounts.hot} · partial ${promptCache.verdictCounts.partial} · cold ${promptCache.verdictCounts.cold} · small ${promptCache.verdictCounts.small}`,
+					] as const,
+				]
+			: [];
 	return kvBlock([
-		["turns", formatTokens(totals.runs - totals.sideQuestions - totals.handoffs)],
+		[
+			"turns",
+			formatTokens(totals.runs - totals.sideQuestions - totals.handoffs - totals.prewarms - totals.backgroundMemory),
+		],
 		["model calls", formatTokens(totals.apiCalls)],
 		...(totals.sideQuestions > 0 ? [["side questions", formatTokens(totals.sideQuestions)] as const] : []),
 		...(totals.handoffs > 0 ? [["handoffs", formatTokens(totals.handoffs)] as const] : []),
+		...(totals.prewarms > 0 ? [["pre-warms", formatTokens(totals.prewarms)] as const] : []),
+		...(totals.backgroundMemory > 0 ? [["memory steps", formatTokens(totals.backgroundMemory)] as const] : []),
 		...(cost === null ? [] : [["cost", cost] as const]),
 		["input", formatTokens(totals.input)],
 		["output", formatTokens(totals.output)],
 		["reasoning", ...reasoningValue(totals.reasoningTokens)],
 		["cache read", ...cacheReadValue(totals.cacheRead, totals.apiCalls)],
 		["cache write", formatTokens(totals.cacheWrite)],
+		...cacheRows,
 		["processed", `${formatTokens(resolvedTotal)} tokens`],
 	]);
 }
@@ -213,10 +255,12 @@ function modelBlock(row: CostRow): string[] {
 	return kvBlock([
 		["requested model ids", row.requestedModelIds.join(", ")],
 		["response model id observation", responseModelIdObservationCountsLabel(row.responseModelIdObservationCounts)],
-		["turns", formatTokens(row.runs - row.sideQuestions - row.handoffs)],
+		["turns", formatTokens(row.runs - row.sideQuestions - row.handoffs - row.prewarms - row.backgroundMemory)],
 		["model calls", formatTokens(row.apiCalls)],
 		...(row.sideQuestions > 0 ? [["side questions", formatTokens(row.sideQuestions)] as const] : []),
 		...(row.handoffs > 0 ? [["handoffs", formatTokens(row.handoffs)] as const] : []),
+		...(row.prewarms > 0 ? [["pre-warms", formatTokens(row.prewarms)] as const] : []),
+		...(row.backgroundMemory > 0 ? [["memory steps", formatTokens(row.backgroundMemory)] as const] : []),
 		...(cost === null ? [] : [["cost", cost] as const]),
 		["input", formatTokens(row.input)],
 		["output", formatTokens(row.output)],
@@ -232,10 +276,11 @@ export function formatCostOverlayBodyLines(
 	totalTokens: number,
 	rows: ReadonlyArray<CostRow>,
 	contentWidth: number,
+	promptCache: PromptCacheTelemetry | null = null,
 ): string[] {
 	const theme = clioTheme();
 	const lines: string[] = [];
-	for (const line of summaryBlock(totalCost, totalTokens, rows)) {
+	for (const line of summaryBlock(totalCost, totalTokens, rows, promptCache)) {
 		lines.push(line);
 	}
 	lines.push(rule(theme, contentWidth));
@@ -258,6 +303,7 @@ export interface CostSnapshot {
 	totalCost: CostAggregate;
 	totalTokens: number;
 	rows: CostRow[];
+	promptCache: PromptCacheTelemetry | null;
 }
 
 // Session totals come from the observability projection: when a snapshot is
@@ -268,6 +314,7 @@ function buildCostSnapshot(
 	observability: ObservabilityContract,
 	sessionId: string | null,
 	snapshot?: ObservabilitySnapshot,
+	getSessionEntries?: () => ReadonlyArray<SessionEntry>,
 ): CostSnapshot {
 	const entries = observability.costEntries();
 	const rows = aggregateCostEntries(entries);
@@ -277,11 +324,14 @@ function buildCostSnapshot(
 		totalCost: snapshot?.session.cost ?? observability.sessionCostSummary(),
 		totalTokens,
 		rows,
+		promptCache: getSessionEntries ? foldPromptCacheTelemetry(getSessionEntries()) : null,
 	};
 }
 
 export interface OpenCostOverlayOptions {
 	sessionId?: string | null;
+	/** Session ledger, read on every render so newly settled and branched calls appear. */
+	getSessionEntries?: () => ReadonlyArray<SessionEntry>;
 }
 
 class CostOverlayBody implements Component {
@@ -290,7 +340,13 @@ class CostOverlayBody implements Component {
 	render(width: number): string[] {
 		const contentWidth = Math.max(1, Math.floor(width));
 		const snapshot = this.getSnapshot();
-		return formatCostOverlayBodyLines(snapshot.totalCost, snapshot.totalTokens, snapshot.rows, contentWidth);
+		return formatCostOverlayBodyLines(
+			snapshot.totalCost,
+			snapshot.totalTokens,
+			snapshot.rows,
+			contentWidth,
+			snapshot.promptCache,
+		);
 	}
 
 	invalidate(): void {}
@@ -312,10 +368,14 @@ export function openCostOverlay(
 ): OverlayHandle {
 	const sessionId = options?.sessionId ?? null;
 	let latest: ObservabilitySnapshot = observability.snapshot();
-	const body = new CostOverlayBody(() => buildCostSnapshot(observability, sessionId, latest));
+	const body = new CostOverlayBody(() =>
+		buildCostSnapshot(observability, sessionId, latest, options?.getSessionEntries),
+	);
 	const handle = showClioOverlayFrame(tui, body, {
 		anchor: "center",
 		width: COST_OVERLAY_WIDTH,
+		// Not derived from the title: that one carries the session id.
+		markerId: "cost",
 		title: sessionId && sessionId.length > 0 ? `Session usage (${sessionId})` : "Session usage",
 		footerHint: buildHint([]),
 	});

package/src/interactive/council-grid.ts

@@ -14,6 +14,7 @@
  */
 
 import { truncateToWidth, wrapTextWithAnsi } from "../engine/tui.js";
+import { COUNCIL_SYNTHESIS_LABEL } from "./council.js";
 import {
 	type ClioTheme,
 	type ClioToken,
@@ -38,9 +39,6 @@ export const COUNCIL_COLUMN_GUTTER = 2;
 /** Rows of a member's bounded answer tail a column shows before it defers to `/view`. */
 export const COUNCIL_ANSWER_ROWS = 4;
 
-/** The label the coordinator gives the synthesis run of every council group. */
-export const COUNCIL_SYNTHESIS_LABEL = "synthesis";
-
 /** One council run as the board draws it: the roster facts plus the run's presentation. */
 export interface CouncilMemberView {
 	runId: string;

package/src/interactive/council.ts

@@ -26,6 +26,17 @@ export type CouncilSynthesisMode = (typeof COUNCIL_SYNTHESIS_MODES)[number];
 /** Rounds the dispatch tool admits. The command enforces the same bound where the operator typed it. */
 export const COUNCIL_MAX_ROUNDS = 3;
 
+/**
+ * The label the coordinator gives the synthesis run of every council group.
+ *
+ * It lives here rather than beside the board layout that draws it because it is
+ * council vocabulary, not presentation: the share path compares against it to
+ * decide whether a run seals the whole council or one voice, and that path must
+ * stay off the render module graph. See the header of
+ * `src/interactive/slash-commands.ts` for the closure budget that depends on it.
+ */
+export const COUNCIL_SYNTHESIS_LABEL = "synthesis";
+
 export function isCouncilSynthesisMode(value: string): value is CouncilSynthesisMode {
 	return COUNCIL_SYNTHESIS_MODES.some((mode) => mode === value);
 }