@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/interactive/chat-renderer.ts

@@ -1,16 +1,19 @@
 /**
  * Coalescing wrapper around chat events (slice 12.5d).
  *
- * Streaming responses fire `text_delta` / `thinking_delta` events at very
- * high frequency. The TUI's per-event `requestRender()` call rebuilt the
+ * Streaming responses fire text, thinking, and cumulative tool-result updates
+ * at very high frequency. The TUI's per-event `requestRender()` call rebuilt the
  * entire transcript on every delta, which scaled linearly with response
- * length and made long answers visibly lag. This wrapper applies every
- * event to the panel synchronously (so internal state stays consistent)
- * but defers `requestRender()` for delta events to a single coalesced
- * timer (~16ms = one frame at 60fps). Non-delta events render
- * synchronously so finalizers like `message_end` are never deferred.
+ * length and made long answers visibly lag. This wrapper applies events to
+ * the panel synchronously (so internal state stays consistent) but defers
+ * `requestRender()` for delta events to a single coalesced timer (~16ms =
+ * one frame at 60fps). Non-delta events render synchronously so finalizers
+ * like `message_end` are never deferred. The one exception is the raw
+ * text/thinking wrapper, which is dropped before the panel entirely; see
+ * `isTransparentAssistantWrapper`.
  */
 
+import { ToolNames } from "../core/tool-names.js";
 import type {
 	BashExecutionEntry,
 	BranchSummaryEntry,
@@ -26,8 +29,17 @@ import type {
 	WorkerRunEntry,
 } from "../domains/session/entries.js";
 import { filterEntriesToActivePath } from "../domains/session/tree/active-path.js";
+import {
+	type BashExecutionMessage,
+	BRANCH_SUMMARY_PREFIX,
+	BRANCH_SUMMARY_SUFFIX,
+	bashExecutionToText,
+	COMPACTION_SUMMARY_PREFIX,
+	COMPACTION_SUMMARY_SUFFIX,
+} from "../engine/messages.js";
 import { wrapTextWithAnsi } from "../engine/tui.js";
 import type { AgentMessage } from "../engine/types.js";
+import { toolPresentationPolicy } from "../tools/presentation.js";
 import type { ChatLoopEvent, RetryStatusPayload } from "./chat-loop.js";
 import { isSelfExplainingAbort } from "./chat-loop-messages.js";
 import type { ChatPanel } from "./chat-panel.js";
@@ -35,8 +47,16 @@ import { renderBranchSummaryEntry } from "./renderers/branch-summary.js";
 import { renderCompactionSummaryEntry } from "./renderers/compaction-summary.js";
 import { styleTaggedNotice } from "./renderers/notice.js";
 import { formatRetryStatus } from "./renderers/retry-status.js";
-import { renderToolResultOnly } from "./renderers/tool-execution.js";
-import { readWorkerReceiptFacts } from "./worker-receipts.js";
+import { renderBashTranscriptExecution, renderToolResultOnly } from "./renderers/tool-execution.js";
+import {
+	classifyStreamEvent,
+	createStreamPacer,
+	type SmoothStreamingMode,
+	type StreamPacer,
+	type StreamPacerSlice,
+} from "./stream-pacer.js";
+import { type FoldOverride, policyToolFold, resolveFold, type TranscriptDetailPolicy } from "./transcript-detail.js";
+import { readWorkerReceiptFactsForReplay } from "./worker-receipts.js";
 import { workerEntriesFromRunEntries } from "./worker-replay.js";
 import type { WorkerReceiptReader } from "./worker-stream.js";
 
@@ -47,7 +67,28 @@ const MAX_REPLAY_TEXT_CHARS = 20_000;
  * Event kinds whose render is deferred into a coalesce window. All other
  * `ChatLoopEvent` kinds render synchronously and cancel any pending timer.
  */
-const DELTA_TYPES: ReadonlySet<ChatLoopEvent["type"]> = new Set(["text_delta", "thinking_delta"]);
+const DELTA_TYPES: ReadonlySet<ChatLoopEvent["type"]> = new Set([
+	"text_delta",
+	"thinking_delta",
+	"tool_execution_update",
+]);
+
+/**
+ * A raw `message_update` wrapper whose inner event is a text or thinking
+ * delta is transparent to the transcript: the panel ignores it, and the
+ * derived `text_delta`/`thinking_delta` emitted in the same stack (see
+ * turn-runtime's public-event fan-out) is the canonical display input. Yet
+ * this renderer classified the wrapper as non-delta, so every provider chunk
+ * cancelled the pending coalesce window and requested an immediate render.
+ * The coalescer was defeated exactly while streaming, which is the one time
+ * it matters. Wrappers carrying tool-call formation stay on the synchronous
+ * path, because the panel consumes those directly.
+ */
+function isTransparentAssistantWrapper(event: ChatLoopEvent): boolean {
+	if (event.type !== "message_update") return false;
+	const inner = (event as { assistantMessageEvent?: { type?: unknown } }).assistantMessageEvent;
+	return inner?.type === "text_delta" || inner?.type === "thinking_delta";
+}
 
 export interface CreateCoalescingChatRendererDeps {
 	chatPanel: ChatPanel;
@@ -58,14 +99,35 @@ export interface CreateCoalescingChatRendererDeps {
 	setTimer?: (cb: () => void, ms: number) => unknown;
 	/** Override for tests. Mirrors the clearTimeout signature. */
 	clearTimer?: (id: unknown) => void;
-	/** Opt-in instrument; counts deltas so a frame row can report how many it absorbed. */
+	/** Monotonic clock shared with the pacer; injectable for deterministic tests. */
+	now?: () => number;
+	/** Sequence captured at canonical projection ingress before this panel consumer runs. */
+	visibleEventSequence?: (event: ChatLoopEvent) => number | null;
+	onQueue?: (eventSeq: number, action: "admit" | "dequeue") => void;
+	onPanelApplied?: (eventSeq: number) => void;
+	/** Legacy aggregate callback retained for non-text cumulative tool-update observations. */
 	onDelta?: () => void;
+	/** Canonical presentation-ingress identity; absent keeps the exact legacy coalescer. */
+	streamIngress?: (event: ChatLoopEvent) => { sequence: number; generation: string | number; ingressAt: number } | null;
+	getSmoothStreamingMode?: () => SmoothStreamingMode;
+	isAutoPacingAllowed?: () => boolean;
+	/** Force and await one actual frame plus any stdout drain. */
+	commitFrame?: (reason?: string) => Promise<unknown>;
 }
 
 export interface CoalescingChatRenderer {
 	applyEvent(event: ChatLoopEvent): void;
 	/** Cancel the pending coalesce timer (if any) and request one synchronous render. */
 	flush(): void;
+	/** Ordered barrier for replay, worker, command-output, and other panel mutations. */
+	mutate(mutation: () => void, reason?: string): void;
+	/** Drop queued presentation content before replacing/resetting the transcript. */
+	reset(mutation: () => void): void;
+	/** Drain paced content and await the first committed frame containing it. */
+	flushAndCommit(reason?: string): Promise<void>;
+	/** Apply a live mode change as an immediate ordered drain boundary. */
+	setSmoothStreamingMode(mode: SmoothStreamingMode): void;
+	dispose(): void;
 }
 
 export function createCoalescingChatRenderer(deps: CreateCoalescingChatRendererDeps): CoalescingChatRenderer {
@@ -78,8 +140,13 @@ export function createCoalescingChatRenderer(deps: CreateCoalescingChatRendererD
 	const coalesceMs = deps.coalesceMs ?? DEFAULT_COALESCE_MS;
 
 	let pendingTimer: unknown = null;
+	let mutationDepth = 0;
+	let transactionNeedsRender = false;
+	let disposed = false;
+	let pacer: StreamPacer | null = null;
 
 	const fireCoalesced = (): void => {
+		if (disposed) return;
 		pendingTimer = null;
 		deps.requestRender();
 	};
@@ -91,24 +158,165 @@ export function createCoalescingChatRenderer(deps: CreateCoalescingChatRendererD
 		return true;
 	};
 
-	return {
+	const requestTransactionalRender = (coalesce: boolean): void => {
+		if (mutationDepth > 0) {
+			transactionNeedsRender = true;
+			return;
+		}
+		if (!coalesce) {
+			cancelPending();
+			deps.requestRender();
+			return;
+		}
+		deps.onDelta?.();
+		if (pendingTimer === null) pendingTimer = setTimer(fireCoalesced, coalesceMs);
+	};
+	const transaction = (operation: () => void, coalesce = false): void => {
+		mutationDepth += 1;
+		try {
+			operation();
+		} finally {
+			mutationDepth -= 1;
+			if (mutationDepth === 0 && transactionNeedsRender) {
+				transactionNeedsRender = false;
+				requestTransactionalRender(coalesce);
+			}
+		}
+	};
+	const applySlice = (slice: StreamPacerSlice): void => {
+		const event =
+			slice.kind === "text"
+				? ({ type: "text_delta", contentIndex: slice.contentIndex, delta: slice.text, partialText: "" } as const)
+				: ({ type: "thinking_delta", contentIndex: slice.contentIndex, delta: slice.text, partialThinking: "" } as const);
+		deps.chatPanel.applyEvent(event);
+		if (slice.finalForItem) {
+			deps.onPanelApplied?.(slice.sequence);
+			deps.onQueue?.(slice.sequence, "dequeue");
+		}
+		requestTransactionalRender(true);
+	};
+	if (deps.streamIngress && deps.getSmoothStreamingMode) {
+		pacer = createStreamPacer({
+			mode: deps.getSmoothStreamingMode(),
+			onSlice: applySlice,
+			onDiscard: (sequence) => deps.onQueue?.(sequence, "dequeue"),
+			...(deps.now ? { now: deps.now } : {}),
+			...(deps.setTimer ? { setTimer: deps.setTimer } : {}),
+			...(deps.clearTimer ? { clearTimer: deps.clearTimer } : {}),
+			...(deps.isAutoPacingAllowed ? { isAutoPacingAllowed: deps.isAutoPacingAllowed } : {}),
+		});
+	}
+	const syncPacerMode = (): SmoothStreamingMode => {
+		const mode = deps.getSmoothStreamingMode?.() ?? "off";
+		if (pacer && pacer.mode !== mode) transaction(() => pacer?.setMode(mode));
+		return mode;
+	};
+	const drainPacer = (reason: string): void => {
+		if (pacer?.snapshot().queuedItems) pacer.flush(reason);
+	};
+	const applyLegacy = (event: ChatLoopEvent): void => {
+		const visibleEventSeq = deps.visibleEventSequence?.(event) ?? null;
+		if (visibleEventSeq !== null) deps.onQueue?.(visibleEventSeq, "admit");
+		deps.chatPanel.applyEvent(event);
+		if (visibleEventSeq !== null) {
+			deps.onPanelApplied?.(visibleEventSeq);
+			deps.onQueue?.(visibleEventSeq, "dequeue");
+		}
+		if (DELTA_TYPES.has(event.type)) {
+			requestTransactionalRender(true);
+			return;
+		}
+		requestTransactionalRender(false);
+	};
+
+	const renderer: CoalescingChatRenderer = {
 		applyEvent(event) {
-			deps.chatPanel.applyEvent(event);
-			if (DELTA_TYPES.has(event.type)) {
-				deps.onDelta?.();
-				if (pendingTimer !== null) return;
-				pendingTimer = setTimer(fireCoalesced, coalesceMs);
+			if (disposed) return;
+			if (isTransparentAssistantWrapper(event)) return;
+			const mode = syncPacerMode();
+			const ingress = deps.streamIngress?.(event) ?? null;
+			if (!pacer || mode === "off") {
+				applyLegacy(event);
 				return;
 			}
-			cancelPending();
-			deps.requestRender();
+			const classification = classifyStreamEvent(event);
+			if (classification === "paced-display-content") {
+				if (ingress === null) {
+					applyLegacy(event);
+					return;
+				}
+				const delta = event as Extract<ChatLoopEvent, { type: "text_delta" | "thinking_delta" }>;
+				if (delta.delta.length === 0) {
+					applyLegacy(event);
+					return;
+				}
+				deps.onQueue?.(ingress.sequence, "admit");
+				transaction(() => {
+					pacer?.enqueue({
+						sequence: ingress.sequence,
+						generation: ingress.generation,
+						kind: delta.type === "text_delta" ? "text" : "thinking",
+						contentIndex: delta.contentIndex,
+						text: delta.delta,
+						ingressAt: ingress.ingressAt,
+						folded: delta.type === "thinking_delta" && !deps.chatPanel.isThinkingExpanded(),
+					});
+				}, true);
+				return;
+			}
+			if (classification === "cumulative-live-state") {
+				transaction(() => {
+					drainPacer("cumulative-live-state");
+					applyLegacy(event);
+				}, true);
+				return;
+			}
+			transaction(() => {
+				drainPacer(`boundary:${event.type}`);
+				applyLegacy(event);
+			});
 		},
 		flush() {
+			if (disposed) return;
+			transaction(() => drainPacer("explicit-flush"));
 			const wasPending = cancelPending();
-			if (!wasPending) return;
-			deps.requestRender();
+			if (wasPending) deps.requestRender();
+		},
+		mutate(mutation, reason = "panel-mutation") {
+			if (disposed) return;
+			transaction(() => {
+				drainPacer(reason);
+				mutation();
+				requestTransactionalRender(false);
+			});
+		},
+		reset(mutation) {
+			if (disposed) return;
+			transaction(() => {
+				pacer?.invalidateEpoch();
+				mutation();
+				requestTransactionalRender(false);
+			});
+		},
+		async flushAndCommit(reason = "final-frame") {
+			if (disposed) return;
+			transaction(() => drainPacer(reason));
+			cancelPending();
+			if (deps.commitFrame) await deps.commitFrame(reason);
+			else deps.requestRender();
+		},
+		setSmoothStreamingMode(mode) {
+			if (disposed || !pacer || pacer.mode === mode) return;
+			transaction(() => pacer?.setMode(mode));
+		},
+		dispose() {
+			if (disposed) return;
+			transaction(() => pacer?.dispose("renderer-dispose"));
+			cancelPending();
+			disposed = true;
 		},
 	};
+	return renderer;
 }
 
 /**
@@ -263,18 +471,18 @@ function toolCallMessageFromEntry(entry: MessageEntry): AgentMessage {
 	} as unknown as AgentMessage;
 }
 
-function toolResultContent(result: unknown): unknown[] {
+function toolResultContent(result: unknown, unbounded = false): unknown[] {
 	const obj = payloadObject(result);
 	if (Array.isArray(obj?.content)) {
-		return cloneContentBlocks(obj.content, MAX_REPLAY_TEXT_CHARS) ?? [];
+		return cloneContentBlocks(obj.content, unbounded ? undefined : MAX_REPLAY_TEXT_CHARS) ?? [];
 	}
-	if (isTextResult(result)) return [{ type: "text", text: truncateReplayText(result.text) }];
-	if (typeof result === "string") return [{ type: "text", text: truncateReplayText(result) }];
-	return [{ type: "text", text: stringifyPreview(result, 10_000) }];
+	if (isTextResult(result)) return [{ type: "text", text: unbounded ? result.text : truncateReplayText(result.text) }];
+	if (typeof result === "string") return [{ type: "text", text: unbounded ? result : truncateReplayText(result) }];
+	return [{ type: "text", text: stringifyPreview(result, unbounded ? Number.POSITIVE_INFINITY : 10_000) }];
 }
 
-function displayReplayToolResult(result: unknown): unknown {
-	const content = toolResultContent(result);
+function displayReplayToolResult(result: unknown, unbounded = false): unknown {
+	const content = toolResultContent(result, unbounded);
 	// 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;
@@ -499,30 +707,29 @@ function appendReplayLine(chatPanel: ChatPanel, text: string): void {
 	chatPanel.appendReplayBlock((width) => renderReplayLine(truncateReplayText(text), width));
 }
 
-const BASH_REPLAY_MAX_LINES = 12;
-
-export function renderBashExecutionEntry(entry: BashExecutionEntry, width: number): string[] {
-	const lines: string[] = [];
-	lines.push(...wrapTextWithAnsi(`bash: $ ${entry.command}`, width));
-	const output = truncateReplayText(entry.output.replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/\s+$/g, ""));
-	if (output.length > 0) {
-		const outputLines = output.split("\n");
-		const hidden = Math.max(0, outputLines.length - BASH_REPLAY_MAX_LINES);
-		const visible = outputLines.slice(-BASH_REPLAY_MAX_LINES);
-		if (hidden > 0) lines.push(...wrapTextWithAnsi(`  ... ${hidden} earlier lines`, width));
-		for (const line of visible) {
-			lines.push(...wrapTextWithAnsi(`  ${line}`, width));
-		}
-	} else {
-		lines.push(...wrapTextWithAnsi("  (no output)", width));
-	}
-	const status: string[] = [];
-	if (entry.cancelled) status.push("cancelled");
-	if (entry.exitCode !== null && entry.exitCode !== 0) status.push(`exit ${entry.exitCode}`);
-	if (entry.truncated) status.push(entry.fullOutputPath ? `truncated: ${entry.fullOutputPath}` : "truncated");
-	if (entry.excludeFromContext) status.push("excluded from context");
-	if (status.length > 0) lines.push(...wrapTextWithAnsi(`  (${status.join(", ")})`, width));
-	return lines;
+function renderBashExecutionEntry(
+	entry: BashExecutionEntry,
+	width: number,
+	folded: boolean,
+	unbounded: boolean,
+): string[] {
+	const normalizedOutput = entry.output.replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/\s+$/g, "");
+	return renderBashTranscriptExecution(
+		{
+			command: entry.command,
+			output: unbounded ? normalizedOutput : truncateReplayText(normalizedOutput),
+			running: false,
+			exitCode: entry.exitCode,
+			cancelled: entry.cancelled,
+			truncated: entry.truncated,
+			fullOutputPath: entry.fullOutputPath,
+			excludeFromContext: entry.excludeFromContext,
+			folded,
+		},
+		width,
+		undefined,
+		{ unbounded, diffStyle: "plain" },
+	);
 }
 
 function renderRetryStatusEntry(entry: CustomEntry, width: number): string[] {
@@ -746,33 +953,26 @@ function dropLegacyToolResultAssistantDuplicates(entries: ReadonlyArray<SessionE
 }
 
 function compactionContextText(entry: CompactionSummaryEntry): string {
-	return [
-		"The conversation history before this point was compacted into the following summary:",
-		"",
-		"<summary>",
-		entry.summary,
-		"</summary>",
-	].join("\n");
+	return `${COMPACTION_SUMMARY_PREFIX}${entry.summary}${COMPACTION_SUMMARY_SUFFIX}`;
 }
 
 function branchContextText(entry: BranchSummaryEntry): string {
-	return [
-		"The following is a summary of a branch that this conversation came back from:",
-		"",
-		"<summary>",
-		entry.summary,
-		"</summary>",
-	].join("\n");
+	return `${BRANCH_SUMMARY_PREFIX}${entry.summary}${BRANCH_SUMMARY_SUFFIX}`;
 }
 
+/** Project Clio's ledger entry onto pi's bash message so pi owns the replay wording. */
 function bashContextText(entry: BashExecutionEntry): string {
-	let text = `Ran \`${entry.command}\`\n`;
-	const output = truncateReplayText(entry.output);
-	text += output.length > 0 ? `\`\`\`\n${output}\n\`\`\`` : "(no output)";
-	if (entry.cancelled) text += "\n\n(command cancelled)";
-	else if (entry.exitCode !== null && entry.exitCode !== 0) text += `\n\nCommand exited with code ${entry.exitCode}`;
-	if (entry.truncated && entry.fullOutputPath) text += `\n\n[Output truncated. Full output: ${entry.fullOutputPath}]`;
-	return text;
+	const message: BashExecutionMessage = {
+		role: "bashExecution",
+		command: entry.command,
+		output: truncateReplayText(entry.output),
+		exitCode: entry.exitCode ?? undefined,
+		cancelled: entry.cancelled,
+		truncated: entry.truncated,
+		...(entry.fullOutputPath !== undefined ? { fullOutputPath: entry.fullOutputPath } : {}),
+		timestamp: Date.parse(entry.timestamp) || 0,
+	};
+	return bashExecutionToText(message);
 }
 
 function appendContextMessage(out: AgentMessage[], role: "user" | "assistant", text: string, timestamp: string): void {
@@ -838,6 +1038,7 @@ export function buildReplayAgentMessagesFromTurns(
 			case "label":
 			case "protectedArtifact":
 			case "taskLedger":
+			case "decisionLedger":
 			// A worker's answer is not the operator's words and not the model's.
 			// 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.
@@ -877,19 +1078,21 @@ export function rehydrateChatPanelFromTurns(
 	options: RehydrateChatPanelOptions = {},
 ): void {
 	const pendingToolIds: string[] = [];
+	let runAssistantMessages: AgentMessage[] = [];
 	const selected = selectReplayEntries(turns, options);
 	// 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.
 	const workerStates = workerEntriesFromRunEntries(
 		selected.filter((entry): entry is WorkerRunEntry => entry.kind === "workerRun"),
-		options.readWorkerReceipt ?? readWorkerReceiptFacts,
+		options.readWorkerReceipt ?? readWorkerReceiptFactsForReplay,
 	);
 	const placedAssignments = new Set<string>();
 	for (const entry of selected) {
 		switch (entry.kind) {
 			case "message": {
 				if (entry.role === "user") {
+					runAssistantMessages = [];
 					const text = truncateReplayText(replayedUserText(entry));
 					if (text.length > 0) chatPanel.appendUser(text);
 					break;
@@ -905,7 +1108,8 @@ export function rehydrateChatPanelFromTurns(
 							(message as { stopReason?: string; errorMessage?: string }).errorMessage = failure.errorMessage;
 						}
 						chatPanel.applyEvent({ type: "message_end", message });
-						chatPanel.applyEvent({ type: "agent_end", messages: [message] });
+						runAssistantMessages.push(message);
+						chatPanel.applyEvent({ type: "agent_end", messages: runAssistantMessages });
 					}
 					break;
 				}
@@ -918,6 +1122,7 @@ export function rehydrateChatPanelFromTurns(
 						toolName: call.name,
 						args: call.args,
 					});
+					chatPanel.markToolReplayed?.(call.id);
 					break;
 				}
 				if (entry.role === "tool_result") {
@@ -930,7 +1135,7 @@ export function rehydrateChatPanelFromTurns(
 							type: "tool_execution_end",
 							toolCallId: fallbackId,
 							toolName: result.name,
-							result: displayReplayToolResult(result.result),
+							result: displayReplayToolResult(result.result, options.unboundedToolBodies === true),
 							isError: result.isError,
 							...(result.durationMs !== undefined ? { durationMs: result.durationMs } : {}),
 							...(result.resultSummary !== undefined ? { resultSummary: result.resultSummary } : {}),
@@ -943,7 +1148,7 @@ export function rehydrateChatPanelFromTurns(
 								{
 									toolCallId: result.id ?? "",
 									toolName: result.name,
-									result: displayReplayToolResult(result.result),
+									result: displayReplayToolResult(result.result, options.unboundedToolBodies === true),
 									isError: result.isError,
 									...(result.durationMs !== undefined ? { durationMs: result.durationMs } : {}),
 									...(result.resultSummary !== undefined ? { resultSummary: result.resultSummary } : {}),
@@ -969,9 +1174,25 @@ export function rehydrateChatPanelFromTurns(
 				}
 				break;
 			}
-			case "bashExecution":
-				chatPanel.appendReplayBlock((width) => renderBashExecutionEntry(entry, width));
+			case "bashExecution": {
+				let fold: FoldOverride;
+				const presentation = toolPresentationPolicy(ToolNames.Bash, undefined);
+				const policyFold = (detail: TranscriptDetailPolicy) => policyToolFold(detail, presentation);
+				const unbounded = options.unboundedToolBodies === true;
+				chatPanel.appendReplayBlock(
+					(width, detail) =>
+						renderBashExecutionEntry(entry, width, resolveFold(fold, policyFold(detail)) === "folded", unbounded),
+					undefined,
+					{
+						policyFold,
+						fold: () => fold,
+						setFold: (next: FoldOverride) => {
+							fold = next;
+						},
+					},
+				);
 				break;
+			}
 			case "custom":
 				if (rendersCustomEntry(entry)) chatPanel.appendReplayBlock((width) => renderCustomEntry(entry, width));
 				break;
@@ -1017,6 +1238,7 @@ export function rehydrateChatPanelFromTurns(
 			}
 			case "label":
 			case "taskLedger":
+			case "decisionLedger":
 				break;
 		}
 	}
@@ -1029,10 +1251,9 @@ export function rehydrateChatPanelFromTurns(
 			isError: true,
 		});
 	}
-	// Replay reproduces the settled view: tools collapse to their one-line
-	// ledger summary. The live path collapses tools because they fire while the
-	// assistant is streaming (pending), a state replay cannot reconstruct
-	// per-tool, so collapse them explicitly here. /export re-expands afterward
-	// via toggleAllToolsExpanded; /resume and /fork keep the collapsed form.
-	chatPanel.collapseAllTools();
+	// A rehydrated transcript starts from the transcript detail policy alone:
+	// whatever the operator had opened or folded before the switch belonged to
+	// the transcript they left. /export reaches the same policy with a verbose
+	// panel, so nothing here is terminal-only.
+	chatPanel.clearFoldOverrides();
 }

package/src/interactive/clio-editor.ts

@@ -1,18 +1,13 @@
-import { Editor, type TUI, truncateToWidth, visibleWidth } from "../engine/tui.js";
+import { Editor, stripTerminalSequences, type TUI, truncateToWidth, visibleWidth } from "../engine/tui.js";
 import type { ClioTheme } from "./theme/index.js";
 import { clioTheme, editorTheme, GLYPH, rule } from "./theme/index.js";
 
-const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;?]*[A-Za-z]`, "g");
 const REVERSE_VIDEO_BLANK = `${String.fromCharCode(27)}[7m ${String.fromCharCode(27)}[0m`;
 const EMPTY_PROMPT = "Ask Clio…  / for commands";
 const MIN_HINT_WIDTH = 60;
 
-function stripAnsi(text: string): string {
-	return text.replace(ANSI, "");
-}
-
 function hasScrollIndicator(line: string): boolean {
-	const stripped = stripAnsi(line);
+	const stripped = stripTerminalSequences(line);
 	return stripped.includes(GLYPH.up) || stripped.includes(GLYPH.down);
 }
 
@@ -91,7 +86,7 @@ function renderEmptyPrompt(line: string, width: number, theme: ClioTheme): strin
 function findBottomRail(lines: readonly string[], width: number): number {
 	const rail = "─".repeat(Math.max(0, width));
 	for (let index = 1; index < lines.length; index += 1) {
-		if (stripAnsi(lines[index] ?? "") === rail) return index;
+		if (stripTerminalSequences(lines[index] ?? "") === rail) return index;
 	}
 	return -1;
 }

package/src/interactive/command-fallbacks.ts

@@ -12,12 +12,12 @@ export function runCompactWithNotice(
 	instructions: string | undefined,
 ): void {
 	if (!onCompact) {
-		emitCommandNotice(notice, "error", "compact", "compaction not wired; pass onCompact to startInteractive");
+		emitCommandNotice(notice, "error", "context compact", "compaction not wired; pass onCompact to startInteractive");
 		return;
 	}
 	const task = onCompact(instructions);
 	void task.catch((err) => {
 		const msg = err instanceof Error ? err.message : String(err);
-		emitCommandNotice(notice, "error", "compact", msg);
+		emitCommandNotice(notice, "error", "context compact", msg);
 	});
 }

package/src/interactive/context-overlay.ts

@@ -1,3 +1,5 @@
+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 { ContextLedger, ContextLedgerGroup } from "../domains/session/context-ledger.js";
@@ -40,6 +42,27 @@ function contextWindowProvenanceLabel(source: ContextLedger["contextWindowSource
 	}
 }
 
+/** A handbook path the operator can read at a glance: workspace-relative when
+ * the file sits under the current directory, `~`-shortened otherwise. */
+function displayHandbookPath(filePath: string): string {
+	const rel = relative(process.cwd(), filePath);
+	if (rel.length > 0 && !rel.startsWith("..")) return rel;
+	const home = homedir();
+	return home.length > 0 && filePath.startsWith(`${home}/`) ? `~${filePath.slice(home.length)}` : filePath;
+}
+
+/**
+ * Which CLIO-CODER*.md file(s) the compiled prompt actually selected. With
+ * override semantics the operator cannot infer the winner from the preload
+ * size alone, so the effective chain is named explicitly, nearest last.
+ */
+function handbookProvenanceLines(handbookFiles: ReadonlyArray<string> | null): string[] {
+	if (!handbookFiles || handbookFiles.length === 0) return [];
+	const first = handbookFiles[0];
+	if (handbookFiles.length === 1 && first !== undefined) return [`handbook: ${displayHandbookPath(first)}`];
+	return ["handbooks (ancestor → nearest):", ...handbookFiles.map((filePath) => `  ${displayHandbookPath(filePath)}`)];
+}
+
 function gridDimensions(ledger: ContextLedger, contentWidth: number): { cols: number; rows: number } {
 	const cols = Math.max(12, Math.min(contentWidth, 40));
 	const rows = ledger.contextWindow >= 200_000 ? 8 : 6;
@@ -58,7 +81,7 @@ function legendRow(group: ContextLedgerGroup, contentWidth: number): string {
 	return `${swatch} ${theme.fg(labelToken, labelText)} ${theme.fg("muted", right)}`;
 }
 
-function renderContextLedgerLines(ledger: ContextLedger, contentWidth: number): string[] {
+export function renderContextLedgerLines(ledger: ContextLedger, contentWidth: number): string[] {
 	const theme = clioTheme();
 	const lines: string[] = [];
 
@@ -92,6 +115,9 @@ function renderContextLedgerLines(ledger: ContextLedger, contentWidth: number):
 	if (ledger.projectPreload && ledger.groups.some((group) => group.category === "project")) {
 		lines.push(theme.fg("dim", `project preload: ${ledger.projectPreload}`));
 	}
+	for (const handbookLine of handbookProvenanceLines(ledger.projectHandbookFiles)) {
+		lines.push(theme.fg("dim", handbookLine));
+	}
 	const compaction =
 		ledger.compactionThreshold !== null
 			? `autocompact at ${Math.round(ledger.compactionThreshold * 100)}% (${ledger.compactionAuto ? "auto" : "manual"})`