@iowarp/clio-coder 0.3.3 → 0.3.4

package/src/domains/session/migrations/index.ts

@@ -2,7 +2,15 @@
  * Strict session-format version reader.
  *
  * Runs before every session resume. Earlier pre-1.0 formats are disposable
- * local state and must not be transformed into the current format.
+ * local state and must not be transformed into the current format. A version
+ * from the future is refused for the opposite reason: the file is not
+ * disposable, it belongs to a newer Clio, and this build would silently drop
+ * whatever that build understood and this one does not. Downgrading and
+ * resuming would then write the truncated reading back over the original.
+ *
+ * Version 3 to 4 is the one additive step: 4 only adds the working-set kinds
+ * (`contextEviction`, `contextRecall`), so a version-3 ledger is read as-is
+ * and the metadata is restamped. Nothing in the file changes.
  */
 
 import { CURRENT_SESSION_FORMAT_VERSION } from "../../../engine/session.js";
@@ -10,6 +18,9 @@ import type { SessionMeta } from "../contract.js";
 
 export { CURRENT_SESSION_FORMAT_VERSION };
 
+/** Oldest version this build reads without transforming the ledger. */
+export const OLDEST_READABLE_SESSION_FORMAT_VERSION = 3;
+
 export interface MigrationResult {
 	migrated: boolean;
 	from: number;
@@ -18,10 +29,18 @@ export interface MigrationResult {
 
 export function runMigrations(meta: SessionMeta, sessionPath: string): MigrationResult {
 	const from = meta.sessionFormatVersion ?? 1;
-	if (from < CURRENT_SESSION_FORMAT_VERSION) {
+	if (from < OLDEST_READABLE_SESSION_FORMAT_VERSION) {
+		throw new Error(
+			`session metadata has an unsupported format version (expected version ${CURRENT_SESSION_FORMAT_VERSION}, got ${from}): ${sessionPath}. Remove the session directory to start a new session.`,
+		);
+	}
+	if (from > CURRENT_SESSION_FORMAT_VERSION) {
 		throw new Error(
-			`session metadata has an unsupported format version (expected version 3, got ${from}): ${sessionPath}. Remove the session directory to start a new session.`,
+			`session was written by a newer Clio (format version ${from}, this build reads version ${CURRENT_SESSION_FORMAT_VERSION}): ${sessionPath}. Upgrade clio-coder to resume this session.`,
 		);
 	}
+	if (from < CURRENT_SESSION_FORMAT_VERSION) {
+		return { migrated: true, from, to: CURRENT_SESSION_FORMAT_VERSION };
+	}
 	return { migrated: false, from, to: from };
 }

package/src/engine/acp/server.ts

@@ -12,6 +12,7 @@ import type { SessionContract, SessionMeta } from "../../domains/session/contrac
 import type { MessageEntry, SessionEntry } from "../../domains/session/entries.js";
 import { filterEntriesToActivePath } from "../../domains/session/tree/active-path.js";
 import type { ToolRegistry } from "../../tools/registry.js";
+import { toolResultPresentationText } from "../../tools/result-disposition.js";
 import type { AgentMessage } from "../types.js";
 import { ACP_TURN_FAILED_MESSAGE, AcpRequestError, AcpTimeoutError, acpErrorMessage } from "./errors.js";
 import type { AcpJsonRpcPeerTransport } from "./transport.js";
@@ -537,6 +538,8 @@ function applyStopReason(active: ActivePrompt, message: unknown): void {
 function outputText(value: unknown): string {
 	if (typeof value === "string") return value;
 	if (!isRecord(value)) return "";
+	const presentationText = toolResultPresentationText(value);
+	if (presentationText !== null) return presentationText;
 	if (Array.isArray(value.content)) return contentText(value.content);
 	if (typeof value.output === "string") return value.output;
 	if (typeof value.text === "string") return value.text;

package/src/engine/agent.ts

@@ -11,6 +11,7 @@
  */
 
 import { Agent, type AgentOptions, type StreamFn } from "@earendil-works/pi-agent-core";
+import { isDispositionedToolResultError } from "../tools/result-disposition.js";
 import { engineStreamSimple } from "./api-registry.js";
 
 export type EngineAgentOptions = Omit<AgentOptions, "streamFn"> & { streamFn?: StreamFn };
@@ -20,8 +21,24 @@ export interface EngineAgentHandle {
 	state(): Agent["state"];
 }
 
+function dispositionAwareAfterToolCall(
+	delegate: AgentOptions["afterToolCall"],
+): NonNullable<AgentOptions["afterToolCall"]> {
+	return async (context, signal) => {
+		const override = await delegate?.(context, signal);
+		const effectiveResult =
+			override?.details === undefined ? context.result : { ...context.result, details: override.details };
+		if (isDispositionedToolResultError(effectiveResult)) return { ...override, isError: true };
+		return override;
+	};
+}
+
 export function createEngineAgent(options: EngineAgentOptions = {}): EngineAgentHandle {
-	const agent = new Agent({ streamFn: engineStreamSimple, ...options });
+	const agent = new Agent({
+		streamFn: engineStreamSimple,
+		...options,
+		afterToolCall: dispositionAwareAfterToolCall(options.afterToolCall),
+	});
 	return {
 		agent,
 		state: () => agent.state,

package/src/engine/session.ts

@@ -57,13 +57,19 @@ export interface ClioSessionMeta {
 	platform: string;
 	nodeVersion: string;
 	/**
-	 * Version 3 on every new session. Readers reject earlier versions and
-	 * sessions that omit this field.
+	 * Version 4 on every new session. Readers reject earlier versions, sessions
+	 * that omit this field, and versions from the future.
 	 */
 	sessionFormatVersion?: number;
 }
 
-export const CURRENT_SESSION_FORMAT_VERSION = 3;
+/**
+ * Version 4 adds the working-set ledger kinds (`contextEviction`,
+ * `contextRecall`). A version-3 reader would parse those entries as unknown
+ * kinds and replay a session as if nothing had been evicted, so the bump is
+ * what makes an older Clio refuse the file instead of misreading it.
+ */
+export const CURRENT_SESSION_FORMAT_VERSION = 4;
 
 export interface ClioSessionJsonlHeader {
 	type: "session";

package/src/entry/orchestrator.ts

@@ -161,8 +161,8 @@ import {
 import { openSession, readSessionTailTurns, sessionCurrentPath, sessionPaths } from "../engine/session.js";
 import type { EngineModel } from "../engine/types.js";
 import { createChatLoop } from "../interactive/chat-loop.js";
-import { buildReplayAgentMessagesFromTurns } from "../interactive/chat-renderer.js";
 import { type RunIo, startInteractive } from "../interactive/index.js";
+import { buildModelReplayAgentMessagesFromTurns } from "../interactive/model-session-replay.js";
 import type { BootOptions } from "./boot-options.js";
 
 export type { BootOptions, HeadlessSamplingOverrides } from "./boot-options.js";
@@ -1236,7 +1236,16 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	// one object the dispatch tool and the keypress both hold.
 	const dispatchBackground = createDispatchBackgroundRegistry();
 	registerAllTools(toolRegistry, {
-		...(session ? { session } : {}),
+		...(session
+			? {
+					session,
+					readSessionEntries: () => {
+						const meta = session.current();
+						return meta ? readSessionEntriesForCompact(meta.id) : [];
+					},
+					onContextRecalled: (payload) => bus.emit(BusChannels.ContextRecalled, payload),
+				}
+			: {}),
 		taskBoard,
 		userTasks,
 		dispatch,
@@ -1612,7 +1621,10 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 				// parent onto.
 				chat.resetForSession(
 					leafTurnId,
-					buildReplayAgentMessagesFromTurns(readCurrentSessionEntries(), leafTurnId ? { activeLeafTurnId: leafTurnId } : {}),
+					buildModelReplayAgentMessagesFromTurns(
+						readCurrentSessionEntries(),
+						leafTurnId ? { activeLeafTurnId: leafTurnId } : {},
+					),
 				);
 			} catch (err) {
 				chat.resetForSession(leafTurnId);
@@ -1664,7 +1676,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 					? {
 							readSessionEntries: readSessionEntriesForCompact,
 							buildReplayMessages: (entries: ReadonlyArray<SessionEntry>, leafTurnId: string | null) =>
-								buildReplayAgentMessagesFromTurns(entries, leafTurnId === null ? {} : { activeLeafTurnId: leafTurnId }),
+								buildModelReplayAgentMessagesFromTurns(entries, leafTurnId === null ? {} : { activeLeafTurnId: leafTurnId }),
 						}
 					: {}),
 				providers,

package/src/interactive/chat-loop-messages.ts

@@ -555,21 +555,33 @@ export function toolResultSummary(result: unknown): Record<string, unknown> {
 	const bytes = Buffer.byteLength(text, "utf8");
 	const details = recordValue(obj?.details);
 	const size = recordValue(details?.resultSize);
+	const disposition = recordValue(details?.resultDisposition);
 	const truncation = recordValue(details?.truncation);
 	const observation = recordValue(details?.observation);
 	const offloadPath =
-		typeof observation?.offloadPath === "string"
-			? observation.offloadPath
-			: typeof size?.offloadPath === "string"
-				? size.offloadPath
-				: null;
+		typeof disposition?.offloadPath === "string"
+			? disposition.offloadPath
+			: typeof observation?.offloadPath === "string"
+				? observation.offloadPath
+				: typeof size?.offloadPath === "string"
+					? size.offloadPath
+					: null;
+	const displayedBytes =
+		typeof disposition?.displayedBytes === "number" && Number.isFinite(disposition.displayedBytes)
+			? disposition.displayedBytes
+			: bytes;
 	return {
-		bytes,
+		bytes: displayedBytes,
 		truncated:
+			disposition?.presentationTruncated === true ||
 			size?.truncated === true ||
 			truncation?.truncated === true ||
 			observation?.truncated === true ||
 			text.includes("[tool result truncated]"),
+		...(typeof disposition?.capturedBytes === "number" ? { capturedBytes: disposition.capturedBytes } : {}),
+		...(typeof disposition?.displayedBytes === "number" ? { displayedBytes: disposition.displayedBytes } : {}),
+		...(typeof disposition?.contextBytes === "number" ? { contextBytes: disposition.contextBytes } : {}),
+		...(disposition?.contextTruncated === true ? { contextTruncated: true } : {}),
 		...(typeof size?.policy === "string" ? { policy: size.policy } : {}),
 		...(typeof size?.followUpHint === "string" ? { followUpHint: size.followUpHint } : {}),
 		...(offloadPath !== null ? { offloadPath } : {}),

package/src/interactive/chat-panel.ts

@@ -5,6 +5,7 @@ import { rawDurationMs } from "../core/timers.js";
 import { type Component, Markdown, truncateToWidth, 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";
 import type { ChatLoopEvent, RetryStatusPayload } from "./chat-loop.js";
 import { extractText, isSelfExplainingAbort } from "./chat-loop-messages.js";
 import type { ApprovalRequestView } from "./permission-overlay.js";
@@ -202,6 +203,12 @@ type ToolSegment = {
 	 * was refused and leaves the operator no way to learn why.
 	 */
 	blockReason?: string | undefined;
+	/**
+	 * Working-set eviction reason for a replayed result whose body the
+	 * projection has replaced. Set only on rehydrate, from the folded ledger;
+	 * a live call is never evicted while it is still being rendered.
+	 */
+	evictedReason?: string | undefined;
 	/** View-only marker: historical calls render mutation diffs without live color. */
 	replayed?: true;
 };
@@ -835,7 +842,7 @@ function styleStatusVerb(text: string, toneHint: VerbRender["toneHint"]): string
 function policySegmentFold(seg: ToolSegment, detail: TranscriptDetailPolicy): Fold {
 	if (!seg.finished) return policyRunningToolFold(detail);
 	if (seg.isError && detail.errors === "body") return "expanded";
-	return policyToolFold(detail, toolPresentationPolicy(seg.name, seg.args));
+	return policyToolFold(detail, toolResultPresentationPolicy(seg.result) ?? toolPresentationPolicy(seg.name, seg.args));
 }
 
 /** Effective state of a tool segment: the operator's override, else the policy. */
@@ -884,6 +891,7 @@ function renderToolSegmentLines(
 						resultSummary: seg.resultSummary,
 						outcome: seg.settlement,
 						blockReason: seg.blockReason,
+						evictedReason: seg.evictedReason,
 					}
 				: { toolCallId: seg.id, toolName: seg.name, args: seg.args, elapsedMs, phase },
 			width,
@@ -916,6 +924,7 @@ function renderToolSegmentLines(
 			resultSummary: seg.resultSummary,
 			outcome: seg.settlement,
 			blockReason: seg.blockReason,
+			evictedReason: seg.evictedReason,
 		},
 		width,
 		{ unbounded: unboundedToolBodies, diffStyle: seg.replayed === true ? "plain" : "color" },
@@ -1936,7 +1945,14 @@ export function createChatPanel(options: ChatPanelOptions = {}): ChatPanel {
 						resultSummary?: unknown;
 						outcome?: unknown;
 						blockReason?: unknown;
+						evictedReason?: unknown;
 					};
+					// Replay-only: the rehydrator reads the working-set fold and tags
+					// the rows whose bodies the projection has replaced for the model.
+					tool.evictedReason =
+						typeof enriched.evictedReason === "string" && enriched.evictedReason.length > 0
+							? enriched.evictedReason
+							: undefined;
 					// Settlement is that verdict, never an inference from result text.
 					// The text of a tool result is the tool's own output: `node --test`
 					// prints `cancelled 0` on every run and a linter can print

package/src/interactive/chat-renderer.ts

@@ -14,6 +14,8 @@
  */
 
 import { ToolNames } from "../core/tool-names.js";
+import { foldWorkingSet } from "../domains/context/working-set/fold.js";
+import { compactionCut } from "../domains/context/working-set/visible.js";
 import type {
 	BashExecutionEntry,
 	BranchSummaryEntry,
@@ -40,6 +42,7 @@ import {
 import { wrapTextWithAnsi } from "../engine/tui.js";
 import type { AgentMessage } from "../engine/types.js";
 import { toolPresentationPolicy } from "../tools/presentation.js";
+import { toolResultPresentationText } from "../tools/result-disposition.js";
 import type { ChatLoopEvent, RetryStatusPayload } from "./chat-loop.js";
 import { isSelfExplainingAbort } from "./chat-loop-messages.js";
 import type { ChatPanel } from "./chat-panel.js";
@@ -482,7 +485,11 @@ function toolResultContent(result: unknown, unbounded = false): unknown[] {
 }
 
 function displayReplayToolResult(result: unknown, unbounded = false): unknown {
-	const content = toolResultContent(result, unbounded);
+	const presentationText = toolResultPresentationText(result);
+	const content =
+		presentationText === null
+			? toolResultContent(result, unbounded)
+			: [{ type: "text", text: unbounded ? presentationText : truncateReplayText(presentationText) }];
 	// Preserve the details record (observation envelope, exec records) so the
 	// replayed ledger line carries the same outcome facts as the live one.
 	const details = payloadObject(result)?.details;
@@ -835,13 +842,6 @@ function truncateAtTurn(entries: ReadonlyArray<SessionEntry>, uptoTurnId?: strin
 	return entries.slice(0, index + 1);
 }
 
-function latestCompactionIndex(entries: ReadonlyArray<SessionEntry>): number {
-	for (let i = entries.length - 1; i >= 0; i--) {
-		if (entries[i]?.kind === "compactionSummary") return i;
-	}
-	return -1;
-}
-
 function toolCallIdsInEntry(entry: SessionEntry): string[] {
 	if (entry.kind !== "message") return [];
 	if (entry.role === "tool_call") return [extractToolCall(entry).id];
@@ -919,19 +919,13 @@ export function selectReplayEntries(
 ): SessionEntry[] {
 	const active = filterEntriesToActivePath(turns, options.activeLeafTurnId ?? options.uptoTurnId);
 	const entries = truncateAtTurn(active, options.uptoTurnId);
-	const compactionIndex = latestCompactionIndex(entries);
-	if (compactionIndex < 0) return dropLegacyToolResultAssistantDuplicates(entries);
-
-	const compaction = entries[compactionIndex] as CompactionSummaryEntry;
-	const selected: SessionEntry[] = [compaction];
-	const firstKeptIndex = compaction.firstKeptTurnId
-		? entries.findIndex((entry) => entry.turnId === compaction.firstKeptTurnId)
-		: -1;
-	if (firstKeptIndex >= 0 && firstKeptIndex < compactionIndex) {
-		selected.push(...entries.slice(firstKeptIndex, compactionIndex));
-	}
-	selected.push(...entries.slice(compactionIndex + 1));
-	return dropLegacyToolResultAssistantDuplicates(repairToolResultOrphans(entries, selected, compactionIndex));
+	// The cut itself is the working-set layer's definition of "what the model
+	// can see", shared with the eviction policy input so the two cannot drift.
+	const cut = compactionCut(entries);
+	if (cut.compactionIndex < 0) return dropLegacyToolResultAssistantDuplicates(entries);
+	const compaction = entries[cut.compactionIndex] as CompactionSummaryEntry;
+	const selected: SessionEntry[] = [compaction, ...cut.visible];
+	return dropLegacyToolResultAssistantDuplicates(repairToolResultOrphans(entries, selected, cut.compactionIndex));
 }
 
 function dropLegacyToolResultAssistantDuplicates(entries: ReadonlyArray<SessionEntry>): SessionEntry[] {
@@ -1043,6 +1037,11 @@ export function buildReplayAgentMessagesFromTurns(
 			// It reaches the model only when an operator shares it, and a share
 			// is already a user message by the time it lands in the ledger.
 			case "workerRun":
+			// Working-set entries are folded into a view by the context domain
+			// and applied as a projection before this builder runs; the
+			// entries themselves never become messages.
+			case "contextEviction":
+			case "contextRecall":
 				break;
 		}
 	}
@@ -1080,6 +1079,11 @@ export function rehydrateChatPanelFromTurns(
 	const pendingToolIds: string[] = [];
 	let runAssistantMessages: AgentMessage[] = [];
 	const selected = selectReplayEntries(turns, options);
+	// The transcript shows the ledger, never the projection: an evicted result
+	// still renders its full body here, tagged with the reason it left the
+	// model's working set. Folded once over the same active path the replay
+	// uses, so a /tree switch cannot tag a row from an abandoned branch.
+	const workingSet = foldWorkingSet(turns, options.activeLeafTurnId ?? options.uptoTurnId);
 	// One block per assignment, drawn where its first attempt started. Later
 	// attempts of the same assignment fold into that block as `↻` rail lines, so
 	// a failover replays as the one run it was rather than as two.
@@ -1127,6 +1131,7 @@ export function rehydrateChatPanelFromTurns(
 				}
 				if (entry.role === "tool_result") {
 					const result = extractToolResult(entry);
+					const evictedReason = workingSet.evicted.get(entry.turnId)?.reason;
 					const fallbackId = result.id ?? pendingToolIds.pop() ?? null;
 					if (fallbackId) {
 						const pendingIndex = pendingToolIds.indexOf(fallbackId);
@@ -1141,6 +1146,7 @@ export function rehydrateChatPanelFromTurns(
 							...(result.resultSummary !== undefined ? { resultSummary: result.resultSummary } : {}),
 							...(result.outcome !== undefined ? { outcome: result.outcome } : {}),
 							...(result.blockReason !== undefined ? { blockReason: result.blockReason } : {}),
+							...(evictedReason !== undefined ? { evictedReason } : {}),
 						} as ChatLoopEvent);
 					} else {
 						chatPanel.appendReplayBlock((width) =>
@@ -1154,6 +1160,7 @@ export function rehydrateChatPanelFromTurns(
 									...(result.resultSummary !== undefined ? { resultSummary: result.resultSummary } : {}),
 									...(result.outcome === "blocked" ? { outcome: "blocked" as const } : {}),
 									...(result.blockReason !== undefined ? { blockReason: result.blockReason } : {}),
+									...(evictedReason !== undefined ? { evictedReason } : {}),
 								},
 								width,
 								{ unbounded: options.unboundedToolBodies === true },
@@ -1239,6 +1246,8 @@ export function rehydrateChatPanelFromTurns(
 			case "label":
 			case "taskLedger":
 			case "decisionLedger":
+			case "contextEviction":
+			case "contextRecall":
 				break;
 		}
 	}

package/src/interactive/context-meter.ts

@@ -156,6 +156,16 @@ export function renderContextMeterGrid(
 	return lines;
 }
 
+/**
+ * Evicted tokens live outside the window: the working-set projection removed
+ * them from what the model sees, so they are not a meter category and must
+ * not claim cells or a legend row. One line after the legend names them.
+ */
+export function renderEvictedTokensLine(evictedTokens: number, theme: ClioTheme = clioTheme()): string {
+	const tokens = Math.round(Math.max(0, evictedTokens)).toLocaleString("en-US");
+	return `${theme.fg("dim", GLYPH.contextReserve)} ${theme.fg("muted", "evicted (outside window)")} ${theme.fg("dim", `${tokens} tokens`)}`;
+}
+
 /** A small colored swatch for a category, for inline legends. */
 export function contextCategorySwatch(category: ContextLedgerCategory, theme: ClioTheme = clioTheme()): string {
 	return theme.fg(CONTEXT_CATEGORY_TOKEN[category], contextCategoryGlyph(category));

package/src/interactive/context-overlay.ts

@@ -2,9 +2,10 @@ import { homedir } from "node:os";
 import { relative } from "node:path";
 import { BusChannels } from "../core/bus-events.js";
 import type { SafeEventBus } from "../core/event-bus.js";
+import type { WorkingSetView } from "../domains/context/working-set/contract.js";
 import type { ContextLedger, ContextLedgerGroup } from "../domains/session/context-ledger.js";
 import { type OverlayHandle, Text, type TUI, visibleWidth } from "../engine/tui.js";
-import { contextCategorySwatch, renderContextMeterGrid } from "./context-meter.js";
+import { contextCategorySwatch, renderContextMeterGrid, renderEvictedTokensLine } from "./context-meter.js";
 import { buildHint, showClioOverlayFrame } from "./overlay-frame.js";
 import { abbreviateModelId, type ClioToken, clioTheme, formatContextPercent } from "./theme/index.js";
 
@@ -81,7 +82,62 @@ function legendRow(group: ContextLedgerGroup, contentWidth: number): string {
 	return `${swatch} ${theme.fg(labelToken, labelText)} ${theme.fg("muted", right)}`;
 }
 
-export function renderContextLedgerLines(ledger: ContextLedger, contentWidth: number): string[] {
+function evictedTokens(view: WorkingSetView): number {
+	let total = 0;
+	for (const state of view.evicted.values()) total += state.tokensFreed;
+	return total;
+}
+
+function formatChurn(view: WorkingSetView): string {
+	if (view.itemsEvicted === 0) return "n/a";
+	return (view.recalls / view.itemsEvicted).toFixed(2);
+}
+
+/**
+ * Prose for one cache-disturbance reason. The wire values are stamped by
+ * `noteColdReason` in turn-context.ts and persisted on the assistant entry's
+ * `promptCache.expectedColdReasons`; the overlay reads them back, so an unknown
+ * reason renders as itself rather than disappearing.
+ */
+function coldReasonLabel(reason: string): string {
+	switch (reason) {
+		case "working_set_evict":
+			return "working-set eviction";
+		case "compaction":
+			return "compaction";
+		case "dispatch":
+			return "dispatch traffic";
+		default:
+			return reason;
+	}
+}
+
+/**
+ * The working-set section: what the projection has taken out of the window
+ * and how often the model has asked for it back. Churn is recalls over items
+ * evicted; a high number means the policy evicts what is still needed.
+ */
+function renderWorkingSetLines(view: WorkingSetView): string[] {
+	const theme = clioTheme();
+	const items = view.evicted.size;
+	const summary = [
+		`${items} evicted item${items === 1 ? "" : "s"}`,
+		`${formatTokens(evictedTokens(view))} tokens`,
+		`${view.evictionEvents} event${view.evictionEvents === 1 ? "" : "s"}`,
+		`${view.recalls} recall${view.recalls === 1 ? "" : "s"}`,
+		`churn ${formatChurn(view)}`,
+	].join(" · ");
+	return [
+		`${theme.fg("muted", "working set")} ${theme.fg("dim", "·")} ${theme.fg("accent", `policy ${view.lastPolicyId ?? "none"}`)}`,
+		theme.fg("dim", summary),
+	];
+}
+
+export function renderContextLedgerLines(
+	ledger: ContextLedger,
+	contentWidth: number,
+	workingSet?: WorkingSetView | null,
+): string[] {
 	const theme = clioTheme();
 	const lines: string[] = [];
 
@@ -110,8 +166,13 @@ export function renderContextLedgerLines(ledger: ContextLedger, contentWidth: nu
 	lines.push("");
 
 	for (const group of ledger.meter) lines.push(legendRow(group, contentWidth));
+	if (workingSet && workingSet.evicted.size > 0) lines.push(renderEvictedTokensLine(evictedTokens(workingSet), theme));
 
 	lines.push("");
+	if (workingSet) {
+		for (const line of renderWorkingSetLines(workingSet)) lines.push(line);
+		lines.push("");
+	}
 	if (ledger.projectPreload && ledger.groups.some((group) => group.category === "project")) {
 		lines.push(theme.fg("dim", `project preload: ${ledger.projectPreload}`));
 	}
@@ -141,11 +202,21 @@ export function renderContextLedgerLines(ledger: ContextLedger, contentWidth: nu
 		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 ?? []) : [];
 		// 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.
-		const misleading = cache.shellReused && cache.backendVerdict === "cold";
+		// 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;
 		lines.push(theme.fg(misleading ? "warning" : "dim", line));
+		if (coldReasons.length > 0) {
+			const reasons = coldReasons.map(coldReasonLabel).join(", ");
+			lines.push(theme.fg("dim", `last cold turn: ${reasons} (expected)`));
+		}
 	}
 
 	if (ledger.lastCompaction) {
@@ -170,6 +241,8 @@ export interface OpenContextOverlayOptions {
 		onEvent(handler: (event: { type: string }) => void): () => void;
 		isStreaming(): boolean;
 	};
+	/** Working-set fold at the live leaf; null or absent hides the section. */
+	getWorkingSet?: () => WorkingSetView | null;
 }
 
 /**
@@ -183,7 +256,9 @@ export function openContextOverlay(
 	getLedger: () => ContextLedger,
 	options?: OpenContextOverlayOptions,
 ): OverlayHandle {
-	const text = new Text(renderContextLedgerLines(getLedger(), DEFAULT_CONTENT_WIDTH).join("\n"), 0, 0);
+	const render = (): string =>
+		renderContextLedgerLines(getLedger(), DEFAULT_CONTENT_WIDTH, options?.getWorkingSet?.() ?? null).join("\n");
+	const text = new Text(render(), 0, 0);
 	const handle = showClioOverlayFrame(tui, text, {
 		anchor: "center",
 		width: CONTEXT_OVERLAY_WIDTH,
@@ -192,7 +267,7 @@ export function openContextOverlay(
 	});
 
 	const refresh = (): void => {
-		text.setText(renderContextLedgerLines(getLedger(), DEFAULT_CONTENT_WIDTH).join("\n"));
+		text.setText(render());
 		text.invalidate();
 		tui.requestRender();
 	};