@iowarp/clio-coder 0.3.2 → 0.3.4

package/src/interactive/renderers/tool-execution.ts

@@ -15,11 +15,15 @@
 import { sanitizeCallTargetText } from "../../domains/safety/call-target.js";
 import { formatSize } from "../../engine/truncate.js";
 import { visibleWidth, wrapTextWithAnsi } from "../../engine/tui.js";
+import { classifyResourceRead, toolPresentationPolicy } from "../../tools/presentation.js";
+import { toolResultPresentationPolicy, toolResultPresentationText } from "../../tools/result-disposition.js";
 import type { ApprovalRequestView } from "../permission-overlay.js";
 import { clioTheme, formatCompactMs, GLYPH } from "../theme/index.js";
 import { renderDiffLines } from "./diff.js";
 import { tryRenderJson, tryRenderXml } from "./structured.js";
 
+export { classifyResourceRead };
+
 const theme = clioTheme();
 const dim = (text: string): string => theme.fg("dim", text);
 const red = (text: string): string => theme.fg("error", text);
@@ -40,6 +44,8 @@ const FULL_RESULT_PREVIEW_LIMIT = 60_000;
 const FULL_RESULT_ROW_LIMIT = 120;
 const STREAMING_RESULT_ROW_LIMIT = 20;
 const ARGS_BODY_LINE_LIMIT = 24;
+/** Rows of mutation diff a folded edit/write row keeps visible before it defers to the body. */
+const FOLDED_DIFF_ROW_LIMIT = 24;
 const STATUS_OK_GLYPH = GLYPH.ok;
 const STATUS_ERROR_GLYPH = GLYPH.error;
 
@@ -76,6 +82,13 @@ export interface ToolExecutionFinished {
 	 * model reading the same transcript, to guess at the rule.
 	 */
 	blockReason?: string | undefined;
+	/**
+	 * Working-set eviction reason, when the projection has replaced this
+	 * result's body for the model. The transcript still renders the full body:
+	 * the ledger is what the operator scrolls, the projection is only what the
+	 * next request carries. The tag says the two now differ here.
+	 */
+	evictedReason?: string | undefined;
 	/** Structured exit status when the caller has one; text parsing is legacy fallback only. */
 	exitCode?: number | string | null | undefined;
 	/** Local `!!` bash output is visible to the operator but excluded from model context. */
@@ -286,24 +299,6 @@ function summarizeArgs(toolName: string, args: unknown): string {
 	return truncate(jsonStringifySafe(safeArgs), ARG_PREVIEW_LIMIT);
 }
 
-/**
- * Compact resource-read classification. Reads of skill/handbook/agent
- * instruction files and docs pages collapse to one labeled line and never
- * auto-expand; their bodies are reference material, not task output.
- */
-export function classifyResourceRead(toolName: string, args: unknown): string | null {
-	if (toolName !== "read") return null;
-	const path = readStringField(args, "path");
-	if (path === null) return null;
-	const normalized = path.replace(/\\/g, "/");
-	const base = normalized.split("/").pop() ?? "";
-	if (base === "SKILL.md") return "skill";
-	if (base === "CLIO-CODER.md") return "handbook";
-	if (base === "AGENTS.md") return "agents";
-	if (/(^|\/)docs\//.test(normalized)) return "docs";
-	return null;
-}
-
 function detailsOf(result: unknown): Record<string, unknown> | null {
 	if (!isPlainObject(result)) return null;
 	return isPlainObject(result.details) ? result.details : null;
@@ -448,15 +443,61 @@ function ledgerTail(finished: ToolExecutionFinished): { facts: string; offload:
 	const parts: string[] = [];
 	const outcome = outcomeSummary(finished);
 	if (outcome !== null) parts.push(outcome);
-	const bytes = isNonExecutedOutcome(finished.outcome) ? null : shownBytesOf(finished);
-	if (bytes !== null && bytes > 0) parts.push(formatSize(bytes));
-	const offloadPath = offloadPathOf(finished);
+	const executed = !isNonExecutedOutcome(finished.outcome);
+	// A folded bash row is the only view of the call the operator gets by
+	// default, so its settlement facts have to be here rather than only in the
+	// expanded body. A failed row already carries `(exit N)` on the status glyph.
+	if (executed && finished.toolName === "bash" && !finished.isError) {
+		parts.push(`exit ${structuredExitCode(finished) ?? "0"}`);
+	}
+	const bytes = executed ? shownBytesOf(finished) : null;
+	if (bytes !== null && bytes > 0) {
+		const total = totalBytesOf(finished);
+		parts.push(
+			total !== null && total > bytes ? `${formatSize(bytes)} shown / ${formatSize(total)} total` : formatSize(bytes),
+		);
+	}
+	if (executed) {
+		if (isTruncatedResult(finished)) parts.push("truncated");
+		const details = detailsOf(finished.result);
+		if (details?.timedOut === true) parts.push("timed out");
+		if (details?.outputCapped === true) parts.push("output capped");
+	}
+	if (finished.excludeFromContext === true) parts.push("excluded from context");
+	if (finished.evictedReason !== undefined) parts.push("evicted", finished.evictedReason);
+	const offloadPath = executed ? offloadPathOf(finished) : null;
 	return {
 		facts: parts.length > 0 ? dim(` · ${parts.join(" · ")}`) : "",
 		offload: offloadPath !== null ? dim(` · full: ${offloadPath}`) : "",
 	};
 }
 
+/** Longest diagnostic excerpt a folded failure row may carry. */
+const FAILURE_EXCERPT_LIMIT = 80;
+
+/**
+ * Last non-empty output line of a failed call, bounded so the folded row stays
+ * diagnostically useful without opening the body. Sanitized to one line: the
+ * source is raw tool output. The tool's presentation policy decides whether
+ * its failures carry one; the renderer never names a tool here.
+ */
+function failureExcerpt(finished: ToolExecutionFinished, width: number): string {
+	const presentation =
+		toolResultPresentationPolicy(finished.result) ?? toolPresentationPolicy(finished.toolName, finished.args);
+	if (!finished.isError || !presentation.failureExcerpt) return "";
+	if (isNonExecutedOutcome(finished.outcome)) return "";
+	const text = unwrapResultEnvelope(finished.result);
+	if (typeof text !== "string") return "";
+	let excerpt: string | undefined;
+	for (const raw of text.split("\n")) {
+		const line = sanitizeCallTargetText(raw).trim();
+		if (line.length > 0) excerpt = line;
+	}
+	if (excerpt === undefined) return "";
+	const limit = Math.min(FAILURE_EXCERPT_LIMIT, Math.max(20, width - 20));
+	return dim(` · ${truncate(excerpt, limit)}`);
+}
+
 /**
  * Marker for a call parked at admission awaiting operator approval. Rendered
  * in place of the elapsed counter so a parked call never reads as executing
@@ -531,8 +572,8 @@ function statusGlyph(status: HeaderStatus, meta: StatusMeta = {}): string {
 }
 
 function headerLine(toolName: string, args: unknown, status: HeaderStatus, meta: StatusMeta = {}): string {
-	const summary = summarizeArgs(toolName, args);
-	const head = `${dim(HEADER_PREFIX_PLAIN)}${cyanBold(toolName)}${dim("(")}${cyan(summary)}${dim(")")}`;
+	const body = styleSublineBody(buildSublineBody(toolName, args, status, undefined, meta.outcome));
+	const head = `${dim(HEADER_PREFIX_PLAIN)}${body}`;
 	return `${head}${statusGlyph(status, meta)}`;
 }
 
@@ -546,8 +587,9 @@ function styleSublineBody(body: string): string {
 	return sublineLead(match.groups.lead, match.groups.rest);
 }
 
-function buildUnknownToolBody(toolName: string, args: unknown): string {
-	return `${toolName}(${summarizeArgs(toolName, args)})`;
+function buildGenericToolBody(toolName: string, args: unknown): string {
+	const summary = summarizeArgs(toolName, args);
+	return summary.length > 0 ? `tool action ${summary}` : "tool action";
 }
 
 function buildFieldSublineBody(
@@ -604,6 +646,7 @@ const SUBLINE_BODY_BUILDERS: Readonly<Record<string, (args: unknown) => string |
 	bash: (args) => buildFieldSublineBody(args, "command", "running ", { wrapInBackticks: true }),
 	grep: (args) => buildFieldSublineBody(args, "pattern", "searching for ", { wrapInBackticks: true }),
 	find: (args) => buildFieldSublineBody(args, "pattern", "finding ", { wrapInBackticks: true }),
+	web_fetch: (args) => buildFieldSublineBody(args, "url", "fetching "),
 	git: (args) => buildFieldSublineBody(args, "op", "git "),
 	verify: (args) => buildFieldSublineBody(args, "check", "verifying "),
 	code_nav: (args) => {
@@ -641,7 +684,7 @@ const SUBLINE_BODY_BUILDERS: Readonly<Record<string, (args: unknown) => string |
 /**
  * Per-tool subline templates. Maps a tool name to a function that builds the
  * verb-led subline body without the leading glyph and without the trailing
- * status glyph. Unknown tools fall back to the existing `<name>(<arg>)` form.
+ * status glyph. Unknown tools fall back to a tool-neutral action summary.
  */
 function webFetchMeta(result: unknown): string | null {
 	if (!isPlainObject(result) || !isPlainObject(result.details)) return null;
@@ -658,11 +701,10 @@ function webFetchMeta(result: unknown): string | null {
 
 /**
  * A call the permission gate blocked never executed, so the collapsed row must
- * not claim it did. `ran \`id\` · 667B ✗ blocked` read as a command that ran and
- * produced 667 bytes, while the expanded header for the same node correctly said
- * `bash(id) ✗ blocked`. Blocked rows use that same call-signature form, and the
- * ledger byte count is suppressed because those bytes are the denial text, not
- * output.
+ * not claim it did. Blocked calls keep the ordinary operator-facing action
+ * description but use a neutral noun for commands; the status tail supplies the
+ * blocked outcome. The ledger byte count is suppressed elsewhere because those
+ * bytes are the denial text, not output.
  */
 function isNonExecutedOutcome(outcome: ToolExecutionFinished["outcome"]): boolean {
 	return outcome === "blocked";
@@ -675,21 +717,29 @@ function buildSublineBody(
 	result?: unknown,
 	outcome?: ToolExecutionFinished["outcome"],
 ): string {
-	if (isNonExecutedOutcome(outcome)) return buildUnknownToolBody(toolName, args);
-	if (status === "forming" || status === "ready") return buildUnknownToolBody(toolName, args);
+	if (isNonExecutedOutcome(outcome)) {
+		if (toolName === "bash") {
+			return (
+				buildFieldSublineBody(args, "command", "command ", { wrapInBackticks: true }) ??
+				buildGenericToolBody(toolName, args)
+			);
+		}
+		return SUBLINE_BODY_BUILDERS[toolName]?.(args) ?? buildGenericToolBody(toolName, args);
+	}
 	if (toolName === "web_fetch") {
 		const meta = status === undefined ? null : webFetchMeta(result);
-		return `${buildUnknownToolBody(toolName, args)}${meta ? dim(` · ${meta}`) : ""}`;
+		const body = SUBLINE_BODY_BUILDERS.web_fetch?.(args) ?? buildGenericToolBody(toolName, args);
+		return `${body}${meta ? dim(` · ${meta}`) : ""}`;
 	}
 	if (toolName === "bash") {
-		const lead = status === "running" || status === undefined ? "running " : "ran ";
+		const lead = status === "ok" || status === "error" ? "ran " : "running ";
 		return (
-			buildFieldSublineBody(args, "command", lead, { wrapInBackticks: true }) ?? buildUnknownToolBody(toolName, args)
+			buildFieldSublineBody(args, "command", lead, { wrapInBackticks: true }) ?? buildGenericToolBody(toolName, args)
 		);
 	}
 	const body = SUBLINE_BODY_BUILDERS[toolName]?.(args);
 	if (body !== null && body !== undefined) return body;
-	return buildUnknownToolBody(toolName, args);
+	return buildGenericToolBody(toolName, args);
 }
 
 interface SublineParts {
@@ -832,6 +882,8 @@ function renderArgsBody(toolName: string, args: unknown, width: number, isError:
  */
 function unwrapResultEnvelope(result: unknown): unknown {
 	if (typeof result === "string" || result === null || result === undefined) return result;
+	const presentationText = toolResultPresentationText(result);
+	if (presentationText !== null) return presentationText;
 	const blocks = Array.isArray(result)
 		? result
 		: isPlainObject(result) && Array.isArray(result.content)
@@ -1002,6 +1054,7 @@ function outputFacts(finished: ToolExecutionFinished): string[] {
 	}
 	if (isPlainObject(finished.result) && finished.result.terminate === true) parts.push("terminal result");
 	if (finished.excludeFromContext === true) parts.push("excluded from context");
+	if (finished.evictedReason !== undefined) parts.push("evicted", finished.evictedReason);
 	return parts;
 }
 
@@ -1116,10 +1169,42 @@ function sublineStatus(call: ToolExecutionStart | ToolExecutionFinished): Header
  * imports the keybindings manager directly; the caller resolves the key string
  * and passes it in to keep this module pure.
  */
+export interface ToolSublineRenderOptions {
+	/** Live rows color the folded mutation diff; replay and export request plain rows. */
+	diffStyle?: "color" | "plain";
+	/**
+	 * Whether the folded row carries the extras its tool's presentation asks
+	 * for (today the bounded mutation diff). The bare subline level drops them;
+	 * the failure excerpt is not one of them and always rides the row.
+	 */
+	foldedExtras?: "per-tool" | "none";
+}
+
+/**
+ * The bounded diff a folded mutation row keeps under itself, when the tool's
+ * presentation asks for one and the result carries one. A folded `edit` that
+ * hid its change told the operator nothing they could act on.
+ */
+function foldedDiffRows(finished: ToolExecutionFinished, width: number, opts: ToolSublineRenderOptions): string[] {
+	if (opts.foldedExtras === "none") return [];
+	if (finished.isError || isNonExecutedOutcome(finished.outcome)) return [];
+	const presentation =
+		toolResultPresentationPolicy(finished.result) ?? toolPresentationPolicy(finished.toolName, finished.args);
+	if (!presentation.showDiffWhenFolded) return [];
+	const diff = resultDiff(finished.result);
+	if (diff === null) return [];
+	return truncateRowsMiddle(
+		renderMutationDiffBlock(diff, width, opts.diffStyle !== "plain"),
+		FOLDED_DIFF_ROW_LIMIT,
+		false,
+	);
+}
+
 export function renderToolSubline(
 	call: ToolExecutionStart | ToolExecutionFinished,
 	width: number,
 	expandKey?: string,
+	opts: ToolSublineRenderOptions = {},
 ): string[] {
 	const status = sublineStatus(call);
 	const meta: StatusMeta =
@@ -1132,9 +1217,12 @@ export function renderToolSubline(
 				}
 			: { elapsedMs: call.elapsedMs };
 	const parts = sublineParts(call, status, meta);
+	const excerpt = "result" in call ? failureExcerpt(call, width) : "";
 	const showHint = "result" in call && expandKey !== undefined && expandKey.length > 0;
 	const tail = showHint ? `${parts.tail}${dim(` (${expandKey})`)}` : parts.tail;
-	return wrapSublineWithTail(parts.lead, tail, width);
+	const lines = wrapSublineWithTail(`${parts.lead}${excerpt}`, tail, width);
+	if ("result" in call) lines.push(...foldedDiffRows(call, width, opts));
+	return lines;
 }
 
 /**
@@ -1294,6 +1382,13 @@ export interface BashTranscriptExecution {
 	fullOutputPath?: string | undefined;
 	excludeFromContext?: boolean | undefined;
 	error?: string | undefined;
+	/**
+	 * Whether the block draws its one-line row instead of the full body. The
+	 * caller resolves this from the transcript detail policy and the operator's
+	 * override, the same way the panel resolves a model bash call. Omitted means
+	 * folded.
+	 */
+	folded?: boolean | undefined;
 }
 
 /**
@@ -1301,7 +1396,12 @@ export interface BashTranscriptExecution {
  * as model-initiated bash. This is a view projection only; callers keep Clio's
  * existing immutable `bashExecution` ledger entry.
  */
-export function renderBashTranscriptExecution(execution: BashTranscriptExecution, width: number): string[] {
+export function renderBashTranscriptExecution(
+	execution: BashTranscriptExecution,
+	width: number,
+	expandKey?: string,
+	bodyOptions: ToolBodyRenderOptions = {},
+): string[] {
 	const shownBytes = Buffer.byteLength(execution.output, "utf8");
 	const totalBytes = execution.totalBytes ?? shownBytes;
 	const args: Record<string, unknown> = { command: execution.command };
@@ -1319,7 +1419,20 @@ export function renderBashTranscriptExecution(execution: BashTranscriptExecution
 		content: [{ type: "text", text: execution.output }],
 		details,
 	};
+	const folded = execution.folded !== false;
 	if (execution.running) {
+		if (folded) {
+			return renderToolSubline(
+				{
+					toolCallId: "local-bash",
+					toolName: "bash",
+					args,
+					elapsedMs: execution.elapsedMs,
+					phase: "running",
+				},
+				width,
+			);
+		}
 		return renderToolStreamingExecution(
 			{
 				toolCallId: "local-bash",
@@ -1336,22 +1449,20 @@ export function renderBashTranscriptExecution(execution: BashTranscriptExecution
 	const output = message
 		? `${execution.output}${execution.output.length > 0 ? "\n\n" : ""}${message}`
 		: execution.output;
-	return renderToolExecution(
-		{
-			toolCallId: "local-bash",
-			toolName: "bash",
-			args,
-			result: { ...result, content: [{ type: "text", text: output }] },
-			isError: execution.cancelled === true || execution.error !== undefined || (execution.exitCode ?? 0) !== 0,
-			exitCode: execution.exitCode,
-			...(execution.cancelled === true ? { outcome: "aborted" as const } : {}),
-			excludeFromContext: execution.excludeFromContext,
-			resultSummary: {
-				bytes: shownBytes,
-				truncated: execution.truncated === true,
-				...(execution.fullOutputPath !== undefined ? { offloadPath: execution.fullOutputPath } : {}),
-			},
+	const finished: ToolExecutionFinished = {
+		toolCallId: "local-bash",
+		toolName: "bash",
+		args,
+		result: { ...result, content: [{ type: "text", text: output }] },
+		isError: execution.cancelled === true || execution.error !== undefined || (execution.exitCode ?? 0) !== 0,
+		exitCode: execution.exitCode,
+		...(execution.cancelled === true ? { outcome: "aborted" as const } : {}),
+		excludeFromContext: execution.excludeFromContext,
+		resultSummary: {
+			bytes: shownBytes,
+			truncated: execution.truncated === true,
+			...(execution.fullOutputPath !== undefined ? { offloadPath: execution.fullOutputPath } : {}),
 		},
-		width,
-	);
+	};
+	return folded ? renderToolSubline(finished, width, expandKey) : renderToolExecution(finished, width, bodyOptions);
 }

package/src/interactive/session-transcript.ts

@@ -3,7 +3,7 @@ import { collectSessionEntries } from "../domains/session/compaction/session-ent
 import type { SessionContract, SessionEntry } from "../domains/session/index.js";
 import { openSession, sessionPaths } from "../engine/session.js";
 import type { ChatLoop } from "./chat-loop.js";
-import { buildReplayAgentMessagesFromTurns } from "./chat-renderer.js";
+import { buildModelReplayAgentMessagesFromTurns } from "./model-session-replay.js";
 
 type SessionOwner = Pick<SessionContract, "create" | "current">;
 type SessionChat = Pick<ChatLoop, "resetForSession">;
@@ -87,7 +87,7 @@ export function createSessionTranscript(deps: SessionTranscriptDeps): SessionTra
 		const turns = deps.readSessionEntries();
 		deps.chat.resetForSession(
 			leafTurnId,
-			buildReplayAgentMessagesFromTurns(turns, {
+			buildModelReplayAgentMessagesFromTurns(turns, {
 				...(leafTurnId ? { activeLeafTurnId: leafTurnId } : {}),
 			}),
 		);

package/src/interactive/slash-commands.ts

@@ -44,6 +44,8 @@ type SlashCommandVariant =
 	| { kind: "init"; options: InitCommandOptions }
 	| { kind: "context-clear"; options: ContextClearCommandOptions }
 	| { kind: "context-refresh" }
+	/** `ref` is the turnId an `[evicted ...]` marker names. */
+	| { kind: "context-recall"; ref: string }
 	| { kind: "skill-selector" }
 	| { kind: "skill-invocation"; text: string }
 	| { kind: "prompts" }
@@ -343,6 +345,13 @@ export interface SlashCommandContext {
 	 * Optional until the host wires onContextRefresh.
 	 */
 	runContextRefresh?: () => void;
+	/**
+	 * Read an evicted tool-result body back into the transcript by ref, and
+	 * record the `contextRecall` entry. Transcript-only: an operator recall
+	 * answers the person, so the body never becomes model context. Optional
+	 * until the host wires a session.
+	 */
+	runContextRecall?: (ref: string) => void;
 	openSkillsHub?: () => void;
 	listPrompts: () => ResourceList<PromptTemplate>;
 	/**
@@ -481,6 +490,13 @@ const COMPACT_POSITIONALS: ReadonlyArray<CommandPositionalSpec> = [
 	{ name: "instructions", required: false, rest: true },
 ];
 
+/**
+ * `/context recall <ref>` takes exactly one ref, not a rest tail: a ref is a
+ * single turnId, and a second token is a mistake worth reporting rather than
+ * text to fold into the first.
+ */
+const RECALL_POSITIONALS: ReadonlyArray<CommandPositionalSpec> = [{ name: "ref", required: true }];
+
 /**
  * A registered command whose arguments do not parse is a mistake to report,
  * not a chat message to send. Falling through to `unknown` submitted the raw
@@ -859,11 +875,12 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	},
 	{
 		name: "context",
-		description: "Context hub: window overlay plus compact, init, refresh, and reset",
+		description: "Context hub: window overlay plus compact, recall, init, refresh, and reset",
 		group: "Inspect",
-		kinds: ["context-view", "compact", "init", "context-clear", "context-refresh"],
+		kinds: ["context-view", "compact", "context-recall", "init", "context-clear", "context-refresh"],
 		subcommandDescriptions: {
 			compact: "Compact session context",
+			recall: "Recall an evicted result",
 			init: "Initialize project context",
 			refresh: "Refresh project context",
 			reset: "Reset project context",
@@ -871,6 +888,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 		args: {
 			subcommands: {
 				compact: { positionals: [...COMPACT_POSITIONALS] },
+				recall: { positionals: [...RECALL_POSITIONALS] },
 				init: {},
 				refresh: {},
 				reset: {},
@@ -881,6 +899,8 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 			switch (parsed.subcommand) {
 				case "compact":
 					return { kind: "compact", instructions: parsed.rest };
+				case "recall":
+					return { kind: "context-recall", ref: parsed.positionals[0] ?? "" };
 				case "init":
 					return { kind: "init", options: {} };
 				case "refresh":
@@ -899,6 +919,13 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 				case "compact":
 					ctx.runCompact(command.instructions);
 					return;
+				case "context-recall":
+					if (ctx.runContextRecall) {
+						ctx.runContextRecall(command.ref);
+					} else {
+						ctx.notice("error", "context recall is not wired; no session is bound to this process");
+					}
+					return;
 				case "init":
 					ctx.runInit(command.options);
 					return;

package/src/interactive/status/index.ts

@@ -1,13 +1,24 @@
 export type { StatusController, StatusControllerDeps } from "./controller.js";
 export { createStatusController } from "./controller.js";
+export {
+	compactReasoningTokens,
+	formatReasoningChip,
+	formatReasoningLabel,
+	type ReasoningProvenance,
+	type ReasoningUsageView,
+	reasoningFromSummary,
+	reasoningFromTally,
+	UNMEASURED_REASONING,
+} from "./reasoning.js";
 export { type ReduceContext, reduceStatus, type StatusInputEvent } from "./state-machine.js";
-export { type BuildSummaryInput, buildSummary } from "./summary.js";
+export { type BuildSummaryInput, buildSummary, emptyRunTally, foldMessageIntoRunTally } from "./summary.js";
 export {
 	type AgentStatus,
 	type AgentStatusChangedPayload,
 	type AgentStatusEvent,
 	INITIAL_STATUS,
 	type ReasoningTokenProvenance,
+	type RunTally,
 	type StatusPhase,
 	type TurnStopReason,
 	type TurnSummary,

package/src/interactive/status/reasoning.ts

@@ -0,0 +1,87 @@
+import type { ReasoningTokenProvenance, RunTally, TurnSummary } from "./types.js";
+
+/**
+ * One projection of a turn's reasoning spend for every surface that shows it.
+ *
+ * Reasoning counts used to be derived in three places (the status tally, the
+ * chat panel's own `message_end` re-derivation, and a chars/4 estimate over the
+ * visible thinking text), so the transcript, the turn receipt, and the footer
+ * could each report a different number for the same turn. Everything now reads
+ * `RunTally`/`TurnSummary` through this module, so a surface can differ in
+ * layout but never in the number or its provenance.
+ *
+ * `unmeasured` is a view-only state: nothing has been folded yet, so the count
+ * is unknown rather than zero. It never reaches `TurnSummary`, which keeps its
+ * persisted `provider | estimated | mixed` vocabulary.
+ */
+export type ReasoningProvenance = ReasoningTokenProvenance | "unmeasured";
+
+export interface ReasoningUsageView {
+	tokens: number;
+	provenance: ReasoningProvenance;
+}
+
+export const UNMEASURED_REASONING: ReasoningUsageView = { tokens: 0, provenance: "unmeasured" };
+
+function provenanceOf(hadProvider: boolean, hadEstimated: boolean): ReasoningProvenance {
+	if (hadProvider && hadEstimated) return "mixed";
+	if (hadProvider) return "provider";
+	if (hadEstimated) return "estimated";
+	return "unmeasured";
+}
+
+function finiteTokens(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+
+/** Live view of the in-flight turn, folded message by message as the run settles. */
+export function reasoningFromTally(tally: RunTally | undefined): ReasoningUsageView {
+	if (!tally) return UNMEASURED_REASONING;
+	const provenance = provenanceOf(tally.hadProviderReasoning === true, tally.hadEstimatedReasoning === true);
+	if (provenance === "unmeasured") return UNMEASURED_REASONING;
+	return { tokens: finiteTokens(tally.reasoningTokens), provenance };
+}
+
+/** Settled view of a turn, including one replayed from a persisted summary. */
+export function reasoningFromSummary(summary: TurnSummary | undefined): ReasoningUsageView {
+	if (!summary || typeof summary.reasoningTokens !== "number") return UNMEASURED_REASONING;
+	// A summary persisted before provenance was recorded carries a count and no
+	// label. `summaryFromRunTally` writes both together, so this only covers
+	// replayed history, where the count came from provider usage.
+	return { tokens: finiteTokens(summary.reasoningTokens), provenance: summary.reasoningTokenProvenance ?? "provider" };
+}
+
+/**
+ * Compact token text for the surfaces that have no formatter of their own. The
+ * footer passes its own `formatFooterTokens` so its chips keep the width
+ * budget the rest of the footer is measured against.
+ */
+export function compactReasoningTokens(value: number): string {
+	if (value < 1000) return String(Math.round(value));
+	if (value < 1_000_000) {
+		const scaled = (value / 1000).toFixed(1);
+		return `${scaled.endsWith(".0") ? scaled.slice(0, -2) : scaled}k`;
+	}
+	const scaled = (value / 1_000_000).toFixed(1);
+	return `${scaled.endsWith(".0") ? scaled.slice(0, -2) : scaled}M`;
+}
+
+/**
+ * `r123` for a provider-attested count, `r≈123` for anything Clio inferred.
+ * Null when there is nothing to state: an unmeasured turn, or one that spent no
+ * reasoning tokens at all (a chip reading `r0` names the provenance of zero).
+ */
+export function formatReasoningChip(
+	view: ReasoningUsageView,
+	format: (value: number) => string = compactReasoningTokens,
+): string | null {
+	if (view.provenance === "unmeasured" || view.tokens <= 0) return null;
+	return `r${view.provenance === "provider" ? "" : "≈"}${format(view.tokens)}`;
+}
+
+export function formatReasoningLabel(view: ReasoningUsageView): string {
+	if (view.provenance === "provider") return "provider-reported";
+	if (view.provenance === "estimated") return "estimated";
+	if (view.provenance === "mixed") return "mixed";
+	return "unmeasured";
+}

package/src/interactive/status/summary.ts

@@ -18,6 +18,7 @@ interface UsageLike {
 	output?: number;
 	cacheRead?: number;
 	cacheWrite?: number;
+	estimated?: boolean;
 }
 
 function assistantThinkingText(message: AgentMessage): string {
@@ -91,7 +92,10 @@ export function foldMessageIntoRunTally(tally: RunTally, message: AgentMessage):
 		cacheReadTokens: tally.cacheReadTokens + (usage ? finite(usage.cacheRead) : 0),
 		cacheWriteTokens: tally.cacheWriteTokens + (usage ? finite(usage.cacheWrite) : 0),
 	};
-	const reasoning = usage ? extractReasoningTokens(usage) : null;
+	// Interrupted turns carry Clio's own estimated usage object. It retains the
+	// completed-record shape, including `reasoning: 0`, but that zero is not a
+	// provider attestation and must not suppress the thinking-text fallback.
+	const reasoning = usage && usage.estimated !== true ? extractReasoningTokens(usage) : null;
 	if (reasoning !== null) {
 		next.reasoningTokens += reasoning;
 		next.hadProviderReasoning = true;
@@ -102,7 +106,14 @@ export function foldMessageIntoRunTally(tally: RunTally, message: AgentMessage):
 	// reported as mixed rather than silently dropping the unreported block.
 	const estimated = estimateReasoningTextTokens(assistantThinkingText(message));
 	if (estimated !== null) {
-		next.reasoningTokens += estimated;
+		// A chars/4 estimate over displayed thinking text can outrun what the
+		// provider says the call generated (summarized reasoning, a rail that
+		// re-renders the same block). Reported output is the ceiling for anything
+		// inferred: reasoning is part of that output, never more than it. No
+		// clamp exists upstream in the adapters, so it lives here, once.
+		const reportedOutput =
+			usage && typeof usage.output === "number" && Number.isFinite(usage.output) ? Math.max(0, usage.output) : null;
+		next.reasoningTokens += reportedOutput === null ? estimated : Math.min(estimated, reportedOutput);
 		next.hadEstimatedReasoning = true;
 	}
 	return next;