@danypops/pi-jittor 0.2.0 → 0.3.0

package/extension/src/{context-breakdown.ts → observability/context-breakdown.ts}

@@ -1,5 +1,17 @@
+import {
+	CONTEXT_DEFAULT_RESERVE_TOKENS,
+	CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN,
+	CONTEXT_TREE_MAX_NODES,
+	type ContextSegment,
+	type ContextSegmentItem,
+	countTextWithFallback,
+	type RequestTokenReconciliation,
+	reconcileRequestTokens,
+	StructuralTextTokenCounter,
+	type TextTokenCounter,
+	type TokenMeasurement,
+} from "@danypops/jittor";
 import type { BuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
-import { CONTEXT_DEFAULT_RESERVE_TOKENS, CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN, CONTEXT_TREE_MAX_NODES, type ContextSegment, type ContextSegmentItem } from "@danypops/jittor";
 
 /**
  * Ported from pi-papyrus's context-budget.ts: the Pi-generic half (session message-history tree
@@ -26,52 +38,180 @@ export interface SessionTreeNodeLike {
 	children: SessionTreeNodeLike[];
 }
 
-function messageContentCharacters(message: unknown): number {
-	if (typeof message !== "object" || message === null) return 0;
+interface MessageContentAnalysis {
+	characters: number;
+	text: string;
+	items: ContextSegmentItem[];
+	imageCount: number;
+}
+
+export interface ContextTokenMeasurementOptions {
+	provider?: string;
+	model?: string;
+	counters?: readonly TextTokenCounter[];
+}
+
+const STRUCTURAL_TEXT_COUNTER = new StructuralTextTokenCounter();
+
+function measurementForText(text: string, options: ContextTokenMeasurementOptions = {}): TokenMeasurement {
+	return countTextWithFallback(
+		{
+			text,
+			scope: "context-item",
+			...(options.provider === undefined ? {} : { provider: options.provider }),
+			...(options.model === undefined ? {} : { model: options.model }),
+		},
+		options.counters ?? [],
+		STRUCTURAL_TEXT_COUNTER,
+	);
+}
+
+function measuredItem(label: string, textOrCharacters: string | number, options: ContextTokenMeasurementOptions = {}): ContextSegmentItem {
+	const characters = typeof textOrCharacters === "string" ? textOrCharacters.length : textOrCharacters;
+	const measurement =
+		typeof textOrCharacters === "string"
+			? measurementForText(textOrCharacters, options)
+			: {
+					tokens: toCeilTokens(characters),
+					scope: "context-item" as const,
+					provenance: "structural-estimate" as const,
+					method: `char/${CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN}`,
+				};
+	const suffix =
+		measurement.provenance === "structural-estimate"
+			? `${characters.toLocaleString()} chars (≈ char/4)`
+			: `${measurement.tokens.toLocaleString()} tok (${measurement.method}; exact text)`;
+	return { label: `${label} · ${suffix}`, estimatedTokens: measurement.tokens, measurement };
+}
+
+/** Breaks a message into Pi's public content fields and attaches explicit exact-text or structural provenance without retaining content. */
+function analyzeMessageContent(message: unknown, options: ContextTokenMeasurementOptions = {}): MessageContentAnalysis {
+	if (typeof message !== "object" || message === null) return { characters: 0, text: "", items: [], imageCount: 0 };
 	const record = message as Record<string, unknown>;
-	if (record["role"] === "bashExecution") {
+	const effectiveOptions = options;
+	if (record.role === "bashExecution") {
 		// Pi's own context builder excludes "!!"-prefixed bash output from context; match that.
-		if (record["excludeFromContext"] === true) return 0;
-		return String(record["command"] ?? "").length + String(record["output"] ?? "").length;
+		if (record.excludeFromContext === true) return { characters: 0, text: "", items: [], imageCount: 0 };
+		const command = String(record.command ?? "");
+		const output = String(record.output ?? "");
+		return {
+			characters: command.length + output.length,
+			text: command + output,
+			items: [measuredItem("command", command, effectiveOptions), measuredItem("output", output, effectiveOptions)].filter(
+				(item) => item.estimatedTokens > 0,
+			),
+			imageCount: 0,
+		};
 	}
-	const content = record["content"];
-	if (typeof content === "string") return content.length;
-	if (!Array.isArray(content)) return 0;
+	const content = record.content;
+	if (typeof content === "string")
+		return {
+			characters: content.length,
+			text: content,
+			items: [measuredItem("text", content, effectiveOptions)],
+			imageCount: 0,
+		};
+	if (!Array.isArray(content)) return { characters: 0, text: "", items: [], imageCount: 0 };
 	let characters = 0;
-	for (const block of content) {
+	let imageCount = 0;
+	let text = "";
+	const items: ContextSegmentItem[] = [];
+	for (let index = 0; index < content.length; index++) {
+		const block = content[index];
 		if (typeof block !== "object" || block === null) continue;
 		const b = block as Record<string, unknown>;
-		if (b["type"] === "text") characters += String(b["text"] ?? "").length;
-		else if (b["type"] === "thinking") characters += String(b["thinking"] ?? "").length;
-		else if (b["type"] === "toolCall") characters += JSON.stringify(b["arguments"] ?? {}).length;
-		// "image" blocks are deliberately not counted here -- image tokens follow a different,
-		// non-character-based cost model this char/4 estimate cannot represent; this is a real,
-		// documented undercount for image-heavy sessions, not a silent approximation.
+		let blockText = "";
+		let label = `block ${index + 1}`;
+		if (b.type === "text") {
+			blockText = String(b.text ?? "");
+			label = "text";
+		} else if (b.type === "thinking") {
+			blockText = String(b.thinking ?? "");
+			label = "thinking";
+		} else if (b.type === "toolCall") {
+			blockText = JSON.stringify(b.arguments ?? {});
+			label = `tool call ${String(b.name ?? "(unknown)")} arguments`;
+		} else if (b.type === "image") {
+			imageCount += 1;
+			continue; // image tokens are provider/model-specific and cannot be derived from base64 characters
+		} else continue;
+		characters += blockText.length;
+		text += blockText;
+		if (blockText.length > 0) items.push(measuredItem(label, blockText, effectiveOptions));
 	}
-	return characters;
+	return { characters, text, items, imageCount };
 }
 
 function messageSnippet(message: unknown, maxLength = 48): string {
 	if (typeof message !== "object" || message === null) return "";
 	const record = message as Record<string, unknown>;
-	if (record["role"] === "bashExecution") return String(record["command"] ?? "");
-	const content = record["content"];
-	const text = typeof content === "string"
-		? content
-		: Array.isArray(content)
-			? content.map((block) => (typeof block === "object" && block !== null && (block as Record<string, unknown>)["type"] === "text" ? String((block as Record<string, unknown>)["text"] ?? "") : "")).join(" ")
-			: "";
+	if (record.role === "bashExecution") return String(record.command ?? "");
+	const content = record.content;
+	const text =
+		typeof content === "string"
+			? content
+			: Array.isArray(content)
+				? content
+						.map((block) =>
+							typeof block === "object" && block !== null && (block as Record<string, unknown>).type === "text"
+								? String((block as Record<string, unknown>).text ?? "")
+								: "",
+						)
+						.join(" ")
+				: "";
 	const collapsed = text.replace(/\s+/g, " ").trim();
 	return collapsed.length > maxLength ? `${collapsed.slice(0, maxLength - 1)}…` : collapsed;
 }
 
-function entryLabel(entry: SessionEntryLike): string {
+interface ProviderPromptUsage {
+	label: string;
+	reconciliation: RequestTokenReconciliation;
+}
+
+function providerPromptUsage(message: unknown): ProviderPromptUsage | null {
+	if (typeof message !== "object" || message === null) return null;
+	const messageRecord = message as Record<string, unknown>;
+	const usage = messageRecord.usage;
+	if (typeof usage !== "object" || usage === null) return null;
+	const record = usage as Record<string, unknown>;
+	const amount = (value: unknown): number => (typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0);
+	const input = amount(record.input);
+	const cacheRead = amount(record.cacheRead);
+	const cacheWrite = amount(record.cacheWrite);
+	const promptTokens = input + cacheRead + cacheWrite;
+	if (!Number.isSafeInteger(promptTokens) || promptTokens <= 0) return null;
+	const identity =
+		typeof messageRecord.provider === "string" && typeof messageRecord.model === "string"
+			? { provider: messageRecord.provider, model: messageRecord.model }
+			: {};
+	const reconciliation = reconcileRequestTokens(
+		{
+			tokens: promptTokens,
+			scope: "request-context",
+			provenance: "provider-reported",
+			method: "pi-assistant-usage",
+			...identity,
+		},
+		[],
+	);
+	const cache =
+		cacheRead > 0 || cacheWrite > 0
+			? `; new ${input.toLocaleString()}, cache read ${cacheRead.toLocaleString()}, write ${cacheWrite.toLocaleString()}`
+			: "";
+	return {
+		label: ` · provider-reported request context ${promptTokens.toLocaleString()} tok${cache} · unattributed residual ${reconciliation.residual.tokens.toLocaleString()} tok`,
+		reconciliation,
+	};
+}
+
+function entryLabel(entry: SessionEntryLike, imageCount = 0, providerUsage = ""): string {
 	if (entry.type === "compaction") return "compaction summary";
 	if (entry.type === "branch_summary") return "branch summary";
-	const role = typeof entry.message === "object" && entry.message !== null ? (entry.message as Record<string, unknown>)["role"] : undefined;
+	const role = typeof entry.message === "object" && entry.message !== null ? (entry.message as Record<string, unknown>).role : undefined;
 	const prefix = typeof role === "string" ? role : entry.type;
 	const snippet = messageSnippet(entry.message);
-	return snippet ? `${prefix}: ${snippet}` : prefix;
+	const images = imageCount > 0 ? ` · ${imageCount} image${imageCount === 1 ? "" : "s"} (token cost unavailable)` : "";
+	return `${snippet ? `${prefix}: ${snippet}` : prefix}${providerUsage}${images}`;
 }
 
 export interface MessageHistoryTree {
@@ -113,7 +253,12 @@ interface WalkFrame {
  * by a reverse-order (children-before-parent) construction pass -- an ordinary long-running
  * session is one long linear chain, so recursion depth would equal entry count.
  */
-export function buildMessageHistoryTree(roots: ReadonlyArray<SessionTreeNodeLike>, activeEntryIds: ReadonlySet<string>, branchEntryIds?: ReadonlySet<string>): MessageHistoryTree {
+export function buildMessageHistoryTree(
+	roots: ReadonlyArray<SessionTreeNodeLike>,
+	activeEntryIds: ReadonlySet<string>,
+	branchEntryIds?: ReadonlySet<string>,
+	measurementOptions: ContextTokenMeasurementOptions = {},
+): MessageHistoryTree {
 	const visited = new Set<string>();
 	let truncated = false;
 	let activeTokens = 0;
@@ -122,8 +267,14 @@ export function buildMessageHistoryTree(roots: ReadonlyArray<SessionTreeNodeLike
 	const stack: WalkFrame[] = [...roots].reverse().map((root) => ({ node: root, parentIndex: null }));
 	while (stack.length > 0) {
 		const frame = stack.pop()!;
-		if (order.length >= CONTEXT_TREE_MAX_NODES) { truncated = true; break; }
-		if (visited.has(frame.node.entry.id)) { truncated = true; continue; } // cycle guard
+		if (order.length >= CONTEXT_TREE_MAX_NODES) {
+			truncated = true;
+			break;
+		}
+		if (visited.has(frame.node.entry.id)) {
+			truncated = true;
+			continue;
+		} // cycle guard
 		visited.add(frame.node.entry.id);
 		const index = order.length;
 		order.push(frame);
@@ -137,22 +288,35 @@ export function buildMessageHistoryTree(roots: ReadonlyArray<SessionTreeNodeLike
 	for (let index = order.length - 1; index >= 0; index--) {
 		const frame = order[index]!;
 		const entry = frame.node.entry;
-		const characters = entry.type === "message"
-			? messageContentCharacters(entry.message)
-			: entry.type === "compaction" || entry.type === "branch_summary"
-				? (entry.summary ?? "").length
-				: 0;
-		const tokens = Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+		const entryMeasurementOptions = measurementOptions;
+		const analysis =
+			entry.type === "message"
+				? analyzeMessageContent(entry.message, measurementOptions)
+				: { characters: 0, text: "", items: [], imageCount: 0 };
+		const text =
+			entry.type === "message"
+				? analysis.text
+				: entry.type === "compaction" || entry.type === "branch_summary"
+					? (entry.summary ?? "")
+					: "";
+		const measurement = measurementForText(text, entryMeasurementOptions);
+		const tokens = measurement.tokens;
 		const isActive = activeEntryIds.has(entry.id);
 		if (isActive) activeTokens += tokens;
 		const isOnBranch = branchEntryIds ? branchEntryIds.has(entry.id) : isActive; // no branch set given -- fall back to the old binary active/inactive-branch label
 
-		const children = childItemsByParent.get(index) ?? [];
-		if (tokens === 0 && children.length === 0) continue; // no content, no descendants with content -- nothing to show
+		const treeChildren = childItemsByParent.get(index) ?? [];
+		const contentChildren = analysis.items;
+		const children = [...contentChildren, ...treeChildren];
+		if (tokens === 0 && children.length === 0 && analysis.imageCount === 0) continue; // no content, no descendants, and no unknown-cost image -- nothing to show
 
+		const promptUsage = providerPromptUsage(entry.message);
+		const label = entryLabel(entry, analysis.imageCount, promptUsage?.label);
 		const item: ContextSegmentItem = {
-			label: isActive ? entryLabel(entry) : isOnBranch ? `${entryLabel(entry)} (compacted)` : `${entryLabel(entry)} (inactive branch)`,
+			label: isActive ? label : isOnBranch ? `${label} (compacted)` : `${label} (inactive branch)`,
 			estimatedTokens: tokens,
+			measurement,
+			...(promptUsage ? { requestTokenReconciliation: promptUsage.reconciliation } : {}),
 			...(children.length > 0 ? { children } : {}),
 		};
 		itemByIndex.set(index, item);
@@ -204,24 +368,63 @@ export function buildBasePromptItems(options: BuildSystemPromptOptions, totalCha
 	const toolSnippetEntries = Object.entries(options.toolSnippets ?? {});
 	// Mirrors buildSystemPrompt()'s own "- name: snippet\n" line shape closely enough to be a
 	// fair estimate without importing Pi-internal formatting code.
+	const toolSnippetDetails = toolSnippetEntries.map(([name, snippet]) => measuredItem(name, name.length + snippet.length + 4));
 	const toolSnippetsCharacters = toolSnippetEntries.reduce((sum, [name, snippet]) => sum + name.length + snippet.length + 4, 0);
 	if (toolSnippetsCharacters > 0) {
-		items.push({ label: `Tool snippets (${toolSnippetEntries.length} tools)`, estimatedTokens: toCeilTokens(toolSnippetsCharacters) });
+		items.push({
+			label: `Tool snippets (${toolSnippetEntries.length} tools)`,
+			estimatedTokens: toCeilTokens(toolSnippetsCharacters),
+			children: toolSnippetDetails,
+		});
 	}
 
 	const visibleSkills = (options.skills ?? []).filter((skill) => !skill.disableModelInvocation);
-	const skillsCharacters = visibleSkills.reduce((sum, skill) => sum + skill.name.length + skill.description.length + skill.filePath.length + 20, 0);
+	const skillsCharacters = visibleSkills.reduce(
+		(sum, skill) => sum + skill.name.length + skill.description.length + skill.filePath.length + 20,
+		0,
+	);
 	if (skillsCharacters > 0) {
-		items.push({ label: `Skills catalog (${visibleSkills.length} skills)`, estimatedTokens: toCeilTokens(skillsCharacters) });
+		items.push({
+			label: `Skills catalog (${visibleSkills.length} skills)`,
+			estimatedTokens: toCeilTokens(skillsCharacters),
+			children: visibleSkills.map((skill) =>
+				measuredItem(skill.name, skill.name.length + skill.description.length + skill.filePath.length + 20),
+			),
+		});
 	}
 
 	const contextFiles = options.contextFiles ?? [];
 	const contextFilesCharacters = contextFiles.reduce((sum, file) => sum + file.path.length + file.content.length + 40, 0);
 	if (contextFilesCharacters > 0) {
-		items.push({ label: `Project context files (${contextFiles.length}, e.g. AGENTS.md)`, estimatedTokens: toCeilTokens(contextFilesCharacters) });
+		items.push({
+			label: `Project context files (${contextFiles.length}, e.g. AGENTS.md)`,
+			estimatedTokens: toCeilTokens(contextFilesCharacters),
+			children: contextFiles.map((file) => measuredItem(file.path, file.path.length + file.content.length + 40)),
+		});
 	}
 
-	const knownCharacters = toolSnippetsCharacters + skillsCharacters + contextFilesCharacters;
+	const promptGuidelines = options.promptGuidelines ?? [];
+	const promptGuidelinesCharacters = promptGuidelines.reduce((sum, guideline) => sum + guideline.length + 2, 0);
+	if (promptGuidelinesCharacters > 0) {
+		items.push({
+			label: `Tool guidelines (${promptGuidelines.length})`,
+			estimatedTokens: toCeilTokens(promptGuidelinesCharacters),
+			children: promptGuidelines.map((guideline, index) => measuredItem(`guideline ${index + 1}`, guideline.length + 2)),
+		});
+	}
+
+	const customPromptCharacters = options.customPrompt?.length ?? 0;
+	if (customPromptCharacters > 0) items.push(measuredItem("Custom system prompt", customPromptCharacters));
+	const appendedPromptCharacters = options.appendSystemPrompt?.length ?? 0;
+	if (appendedPromptCharacters > 0) items.push(measuredItem("Appended system prompt", appendedPromptCharacters));
+
+	const knownCharacters =
+		toolSnippetsCharacters +
+		skillsCharacters +
+		contextFilesCharacters +
+		promptGuidelinesCharacters +
+		customPromptCharacters +
+		appendedPromptCharacters;
 	const remainderCharacters = Math.max(0, totalCharacters - knownCharacters);
 	if (remainderCharacters > 0 || items.length === 0) {
 		items.push({ label: "Base template, guidelines, and formatting", estimatedTokens: toCeilTokens(remainderCharacters) });
@@ -300,9 +503,10 @@ export function composeContextBreakdown(input: ComposeContextBreakdownInput): Co
 	const overshootTokens = input.totalTokens === null ? 0 : Math.max(0, knownTokens - input.totalTokens);
 	const other: ContextSegment = {
 		key: "other",
-		label: overshootTokens > 0
-			? `Unaccounted (message envelope, cache-control markers, and other wire-protocol overhead) -- estimate overshoot: other segments' estimates already exceed the real total by ~${overshootTokens} tokens, so this is a floor, not a real zero`
-			: "Unaccounted (message envelope, cache-control markers, and other wire-protocol overhead)",
+		label:
+			overshootTokens > 0
+				? `Unaccounted (message envelope, cache-control markers, and other wire-protocol overhead) -- estimate overshoot: other segments' estimates already exceed the real total by ~${overshootTokens} tokens, so this is a floor, not a real zero`
+				: "Unaccounted (message envelope, cache-control markers, and other wire-protocol overhead)",
 		estimatedTokens: input.totalTokens === null ? 0 : Math.max(0, input.totalTokens - knownTokens),
 		confidence: "correlated",
 	};

package/extension/src/observability/context-growth.ts

@@ -0,0 +1,26 @@
+export interface ContextGrowthPoint {
+	turn: number;
+	tokens: number;
+}
+
+/**
+ * Owns the current post-compaction context-growth observation window. Trend fitting and a
+ * trailing-size cap deliberately remain outside this task; reset() is the critical invariant
+ * that prevents one regression window from spanning a real compaction discontinuity.
+ */
+export class ContextGrowthCapability {
+	private points: ContextGrowthPoint[] = [];
+
+	observe(turn: number, tokens: number): void {
+		if (!Number.isInteger(turn) || turn < 0 || !Number.isFinite(tokens) || tokens < 0) return;
+		this.points.push({ turn, tokens });
+	}
+
+	observations(): readonly ContextGrowthPoint[] {
+		return this.points.map((point) => ({ ...point }));
+	}
+
+	reset(): void {
+		this.points = [];
+	}
+}

package/extension/src/{capabilities → observability}/context-hub.ts

@@ -1,8 +1,4 @@
-import {
-	CONTEXT_HUB_CONTRIBUTION_DEDUP_LIMIT,
-	validateContextContribution,
-	type ContextSegment,
-} from "@danypops/jittor";
+import { CONTEXT_HUB_CONTRIBUTION_DEDUP_LIMIT, type ContextSegment, validateContextContribution } from "@danypops/jittor";
 
 /**
  * Merges Jittor's own directly-computed segments (tool ledger, real usage) with whatever

package/extension/src/observability/context-report.ts

@@ -0,0 +1,92 @@
+import type { ContextSegment } from "@danypops/jittor";
+import type { ContextRow, ContextSegment as MalevichContextSegment } from "malevich-tui-components";
+import type { ContextBreakdown } from "./context-breakdown.ts";
+
+/** Bounds how many items render per segment in the plain-text fallback -- a notify-mode report is a scan-at-a-glance summary, not a full dump (the interactive TUI view has no such cap, since it scrolls). */
+const MAX_ITEMS_PER_SEGMENT_LINE = 5;
+const MAX_REPORT_ROWS = 200;
+
+function formatTokens(tokens: number): string {
+	return tokens >= 1_000 ? `${(tokens / 1_000).toFixed(1)}k` : String(tokens);
+}
+
+function percentOf(part: number, whole: number): string {
+	return whole > 0 ? `${((part / whole) * 100).toFixed(1)}%` : "—";
+}
+
+/** Malevich-compatible row projection with an explicit stack, safe for long linear session trees. */
+export function buildContextRowsIterative(segments: readonly MalevichContextSegment[], totalTokens?: number | null): ContextRow[] {
+	const rows: ContextRow[] = [];
+	const denominator = totalTokens ?? segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
+	for (const segment of segments) {
+		const items = [...(segment.items ?? [])]
+			.filter((item) => item.estimatedTokens > 0)
+			.sort((a, b) => b.estimatedTokens - a.estimatedTokens);
+		if (segment.estimatedTokens <= 0 && items.length === 0 && !segment.unknown) continue;
+		rows.push({
+			key: segment.key,
+			isHeader: true,
+			depth: 0,
+			text: `${segment.label} — ${segment.estimatedTokens} tok (${percentOf(segment.estimatedTokens, denominator)})`,
+		});
+		const stack = items.reverse().map((item) => ({ item, depth: 1 }));
+		while (stack.length > 0) {
+			const { item, depth } = stack.pop()!;
+			rows.push({ key: segment.key, isHeader: false, depth, text: `${item.estimatedTokens.toString().padStart(6)} tok  ${item.label}` });
+			const children = [...(item.children ?? [])]
+				.filter((child) => child.estimatedTokens > 0)
+				.sort((a, b) => b.estimatedTokens - a.estimatedTokens);
+			for (let index = children.length - 1; index >= 0; index--) stack.push({ item: children[index]!, depth: depth + 1 });
+		}
+	}
+	return rows;
+}
+
+/** Malevich's row builder is confidence-unaware (it's a generic segment/item shape); folding the tier into the label is how it survives into the rendered row text, e.g. "Active Rules [exact-cooperative]". */
+function withConfidenceLabel(segment: ContextSegment): MalevichContextSegment {
+	const items = [...(segment.items ?? [])]
+		.sort((left, right) => right.estimatedTokens - left.estimatedTokens)
+		.slice(0, MAX_ITEMS_PER_SEGMENT_LINE);
+	return {
+		key: segment.key,
+		label: `${segment.label} [${segment.confidence}]`,
+		estimatedTokens: segment.estimatedTokens,
+		items,
+		unknown: segment.unknown,
+	};
+}
+
+/**
+ * Plain-text Context Hub report (non-TUI fallback): real usage against the model's effective
+ * (reserve-adjusted) budget first -- matching Papyrus's own real-vs-estimate honesty accounting
+ * -- an explicit overshoot warning when the known segments' estimates exceed the real total, then
+ * every segment heaviest-first. Malevich's buildContextRows renders segments in the order given,
+ * so sorting by weight is this function's own policy, not Malevich's.
+ */
+export function buildContextReport(breakdown: ContextBreakdown): string {
+	const lines: string[] = [];
+	if (breakdown.totalTokens !== null && breakdown.effectiveBudget !== null) {
+		lines.push(
+			`Real usage: ${formatTokens(breakdown.totalTokens)} / ${formatTokens(breakdown.effectiveBudget)} tokens (${percentOf(breakdown.totalTokens, breakdown.effectiveBudget)} of usable budget)`,
+		);
+	} else if (breakdown.totalTokens !== null) {
+		lines.push(`Real usage: ${formatTokens(breakdown.totalTokens)} tokens (model context window unknown)`);
+	} else {
+		lines.push("Real usage: not yet reported -- sizes below are estimates only");
+	}
+	if (breakdown.overshootTokens > 0)
+		lines.push(`Estimates exceed real total by ~${breakdown.overshootTokens} tok -- sizes below are approximate, not exact`);
+
+	const sorted = [...breakdown.segments].sort((left, right) => right.estimatedTokens - left.estimatedTokens).map(withConfidenceLabel);
+	const rows = buildContextRowsIterative(sorted, breakdown.totalTokens ?? undefined);
+	if (rows.length === 0) {
+		lines.push("", "(no segments observed yet)");
+		return lines.join("\n");
+	}
+	lines.push("");
+	const visibleRows = rows.slice(0, MAX_REPORT_ROWS);
+	for (const row of visibleRows) lines.push(row.isHeader ? row.text : `${"  ".repeat(row.depth)}${row.text}`);
+	if (rows.length > visibleRows.length)
+		lines.push(`… ${rows.length - visibleRows.length} more context rows (open /context in TUI mode to search and filter)`);
+	return lines.join("\n");
+}