@oh-my-pi/pi-coding-agent 14.5.8 → 14.5.10

package/src/lsp/utils.ts

@@ -596,38 +596,42 @@ function findSymbolMatchIndexes(lineText: string, symbol: string, caseInsensitiv
 	return indexes;
 }
 
-function normalizeOccurrence(occurrence?: number): number {
-	if (occurrence === undefined || !Number.isFinite(occurrence)) return 1;
-	return Math.max(1, Math.trunc(occurrence));
+/**
+ * Parses a symbol spec of the form `name` or `name#N` where N is the 1-indexed
+ * occurrence on the target line. Returns `name` and `occurrence` (default 1).
+ *
+ * Greedy match on `.+` so `#name#2` parses as symbol=`#name` (TS private field)
+ * with occurrence 2. Specs without a trailing `#\d+` are treated as literal.
+ */
+function parseSymbolSpec(spec: string): { symbol: string; occurrence: number } {
+	const match = spec.match(/^(.+)#(\d+)$/);
+	if (!match) return { symbol: spec, occurrence: 1 };
+	const occurrence = Math.max(1, Number.parseInt(match[2], 10));
+	return { symbol: match[1], occurrence };
 }
 
-export async function resolveSymbolColumn(
-	filePath: string,
-	line: number,
-	symbol?: string,
-	occurrence?: number,
-): Promise<number> {
+export async function resolveSymbolColumn(filePath: string, line: number, symbolSpec?: string): Promise<number> {
 	const lineNumber = Math.max(1, line);
-	const matchOccurrence = normalizeOccurrence(occurrence);
 	try {
 		const fileText = await Bun.file(filePath).text();
 		const lines = fileText.split("\n");
 		const targetLine = lines[lineNumber - 1] ?? "";
-		if (!symbol) {
+		if (!symbolSpec) {
 			return firstNonWhitespaceColumn(targetLine);
 		}
 
+		const { symbol, occurrence } = parseSymbolSpec(symbolSpec);
 		const exactIndexes = findSymbolMatchIndexes(targetLine, symbol);
 		const fallbackIndexes = exactIndexes.length > 0 ? exactIndexes : findSymbolMatchIndexes(targetLine, symbol, true);
 		if (fallbackIndexes.length === 0) {
 			throw new Error(`Symbol "${symbol}" not found on line ${lineNumber}`);
 		}
-		if (matchOccurrence > fallbackIndexes.length) {
+		if (occurrence > fallbackIndexes.length) {
 			throw new Error(
-				`Symbol "${symbol}" occurrence ${matchOccurrence} is out of bounds on line ${lineNumber} (found ${fallbackIndexes.length})`,
+				`Symbol "${symbol}" occurrence ${occurrence} is out of bounds on line ${lineNumber} (found ${fallbackIndexes.length})`,
 			);
 		}
-		return fallbackIndexes[matchOccurrence - 1];
+		return fallbackIndexes[occurrence - 1];
 	} catch (error) {
 		if (isEnoent(error)) {
 			throw new Error(`File not found: ${filePath}`);

package/src/memories/index.ts

@@ -277,6 +277,11 @@ async function runPhase1(options: {
 			});
 
 			if (result.kind === "failed") {
+				logger.error("Memory phase1 stage1 job failed", {
+					threadId: claim.threadId,
+					rolloutPath: claim.rolloutPath,
+					reason: result.reason,
+				});
 				markStage1Failed(db, {
 					threadId: claim.threadId,
 					ownershipToken: claim.ownershipToken,

package/src/modes/components/settings-defs.ts

@@ -348,7 +348,7 @@ const OPTION_PROVIDERS: Partial<Record<SettingPath, OptionProvider>> = {
 		{ value: "kagi", label: "Kagi", description: "Requires KAGI_API_KEY and Kagi Search API beta access" },
 		{ value: "synthetic", label: "Synthetic", description: "Requires SYNTHETIC_API_KEY" },
 		{ value: "parallel", label: "Parallel", description: "Requires PARALLEL_API_KEY" },
-		{ value: "searxng", label: "SearXNG", description: "Self-hosted metasearch; set searxng.endpoint" },
+		{ value: "searxng", label: "SearXNG", description: "Requires searxng.endpoint" },
 	],
 	"providers.image": [
 		{

package/src/modes/controllers/command-controller.ts

@@ -24,6 +24,7 @@ import { DynamicBorder } from "../../modes/components/dynamic-border";
 import { PythonExecutionComponent } from "../../modes/components/python-execution";
 import { getMarkdownTheme, getSymbolTheme, theme } from "../../modes/theme/theme";
 import type { InteractiveModeContext } from "../../modes/types";
+import { computeContextBreakdown, renderContextUsage } from "../../modes/utils/context-usage";
 import { buildHotkeysMarkdown } from "../../modes/utils/hotkeys-markdown";
 import { buildToolsMarkdown } from "../../modes/utils/tools-markdown";
 import type { AsyncJobSnapshotItem } from "../../session/agent-session";
@@ -529,6 +530,22 @@ export class CommandController {
 		showMarkdownPanel(this.ctx, "Available Tools", tools);
 	}
 
+	handleContextCommand(): void {
+		const breakdown = computeContextBreakdown(this.ctx.session);
+		if (breakdown.contextWindow <= 0) {
+			this.ctx.showWarning("Context usage is unavailable: no model is selected for this session.");
+			return;
+		}
+		const output = renderContextUsage(breakdown, theme);
+		this.ctx.chatContainer.addChild(new Spacer(1));
+		this.ctx.chatContainer.addChild(new DynamicBorder());
+		this.ctx.chatContainer.addChild(new Text(theme.bold(theme.fg("accent", "Context Usage")), 1, 0));
+		this.ctx.chatContainer.addChild(new Spacer(1));
+		this.ctx.chatContainer.addChild(new Text(output, 1, 0));
+		this.ctx.chatContainer.addChild(new DynamicBorder());
+		this.ctx.ui.requestRender();
+	}
+
 	async handleMemoryCommand(text: string): Promise<void> {
 		const argumentText = text.slice(7).trim();
 		const action = argumentText.split(/\s+/, 1)[0]?.toLowerCase() || "view";

package/src/modes/controllers/input-controller.ts

@@ -45,7 +45,7 @@ export class InputController {
 			);
 		this.ctx.editor.onEscape = () => {
 			if (this.ctx.loopModeEnabled) {
-				this.ctx.disableLoopMode();
+				this.ctx.pauseLoop();
 				if (this.ctx.session.isStreaming) {
 					void this.ctx.session.abort();
 				} else {
@@ -317,6 +317,12 @@ export class InputController {
 				}
 			}
 
+			// While loop mode is on, every user-typed prompt becomes the new loop
+			// prompt that auto-resubmits after each yield.
+			if (this.ctx.loopModeEnabled) {
+				this.ctx.loopPrompt = text;
+			}
+
 			// Queue input during compaction
 			if (this.ctx.session.isCompacting) {
 				if (this.ctx.pendingImages.length > 0) {

package/src/modes/controllers/selector-controller.ts

@@ -659,9 +659,9 @@ export class SelectorController {
 							return;
 						}
 
-						// Update UI
+						// Update UI — pass the context built by navigateTree to skip a second O(N) walk.
 						this.ctx.chatContainer.clear();
-						this.ctx.renderInitialMessages();
+						this.ctx.renderInitialMessages(result.sessionContext);
 						await this.ctx.reloadTodos();
 						if (result.editorText && !this.ctx.editor.getText().trim()) {
 							this.ctx.editor.setText(result.editorText);

package/src/modes/interactive-mode.ts

@@ -14,7 +14,17 @@ import {
 	type UsageReport,
 } from "@oh-my-pi/pi-ai";
 import type { Component, SlashCommand } from "@oh-my-pi/pi-tui";
-import { Container, Loader, Markdown, ProcessTerminal, Spacer, Text, TUI, visibleWidth } from "@oh-my-pi/pi-tui";
+import {
+	Container,
+	clearRenderCache,
+	Loader,
+	Markdown,
+	ProcessTerminal,
+	Spacer,
+	Text,
+	TUI,
+	visibleWidth,
+} from "@oh-my-pi/pi-tui";
 import { APP_NAME, getProjectDir, hsvToRgb, isEnoent, logger, postmortem, prompt } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { KeybindingsManager } from "../config/keybindings";
@@ -442,6 +452,7 @@ export class InteractiveMode implements InteractiveModeContext {
 
 		// Set up theme file watcher
 		onThemeChange(() => {
+			clearRenderCache();
 			this.ui.invalidate();
 			this.updateEditorBorderColor();
 			this.ui.requestRender();
@@ -492,10 +503,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	}
 
 	#scheduleLoopAutoSubmit(): void {
-		if (this.#loopAutoSubmitTimer) {
-			clearTimeout(this.#loopAutoSubmitTimer);
-			this.#loopAutoSubmitTimer = undefined;
-		}
+		this.#cancelLoopAutoSubmit();
 		if (!this.loopModeEnabled || !this.loopPrompt) return;
 		const prompt = this.loopPrompt;
 		const loopAction = settings.get("loop.mode");
@@ -507,6 +515,13 @@ export class InteractiveMode implements InteractiveModeContext {
 		}, 800);
 	}
 
+	#cancelLoopAutoSubmit(): void {
+		if (this.#loopAutoSubmitTimer) {
+			clearTimeout(this.#loopAutoSubmitTimer);
+			this.#loopAutoSubmitTimer = undefined;
+		}
+	}
+
 	async #runLoopIteration(action: "prompt" | "compact" | "reset", prompt: string): Promise<void> {
 		if (action === "compact") {
 			await this.handleCompactCommand();
@@ -517,43 +532,42 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.onInputCallback(this.startPendingSubmission({ text: prompt }));
 	}
 
-	disableLoopMode(options?: { silent?: boolean }): void {
+	disableLoopMode(): void {
 		const wasEnabled = this.loopModeEnabled;
 		this.loopModeEnabled = false;
 		this.loopPrompt = undefined;
-		if (this.#loopAutoSubmitTimer) {
-			clearTimeout(this.#loopAutoSubmitTimer);
-			this.#loopAutoSubmitTimer = undefined;
-		}
+		this.#cancelLoopAutoSubmit();
 		this.statusLine.setLoopModeStatus(undefined);
 		this.updateEditorTopBorder();
 		this.ui.requestRender();
-		if (wasEnabled && !options?.silent) {
+		if (wasEnabled) {
 			this.showStatus("Loop mode disabled.");
 		}
 	}
 
-	async handleLoopCommand(prompt?: string): Promise<void> {
+	/**
+	 * Pause the loop without exiting it: drops the captured prompt and any
+	 * pending auto-resubmit. Loop mode stays enabled — the next prompt the
+	 * user submits becomes the new loop prompt and resumes iteration.
+	 */
+	pauseLoop(): void {
+		this.loopPrompt = undefined;
+		this.#cancelLoopAutoSubmit();
+	}
+
+	async handleLoopCommand(): Promise<void> {
 		if (this.loopModeEnabled) {
 			this.disableLoopMode();
 			return;
 		}
-		const trimmed = prompt?.trim();
-		if (!trimmed) {
-			this.showError("Usage: /loop <prompt>");
-			return;
-		}
 		this.loopModeEnabled = true;
-		this.loopPrompt = trimmed;
+		this.loopPrompt = undefined;
 		this.statusLine.setLoopModeStatus({ enabled: true });
 		this.updateEditorTopBorder();
 		this.ui.requestRender();
-		this.showStatus("Loop mode enabled. Esc to stop.");
-
-		// Submit the first iteration immediately so the loop kicks off.
-		if (this.onInputCallback) {
-			this.onInputCallback(this.startPendingSubmission({ text: trimmed }));
-		}
+		this.showStatus(
+			"Loop mode enabled. Your next prompt will repeat after each turn. Esc cancels the current iteration; /loop again to disable.",
+		);
 	}
 
 	startPendingSubmission(input: { text: string; images?: ImageContent[] }): SubmittedUserInput {
@@ -864,6 +878,19 @@ export class InteractiveMode implements InteractiveModeContext {
 			} else {
 				await this.session.setModelTemporary(prev.model, prev.thinkingLevel);
 			}
+			// If #applyPlanModeModel queued a deferred switch to the plan-role model
+			// (because the session was streaming on entry), drop it now: we are
+			// leaving plan mode, so flushing it on the next agent_end would land the
+			// session on the plan-role model after the user has exited plan mode
+			// (issue #816). Only clear when the pending target matches the plan-role
+			// model — leave any unrelated user-queued switch intact.
+			const pending = this.#pendingModelSwitch;
+			if (pending) {
+				const planResolution = this.session.resolveRoleModelWithThinking("plan");
+				if (planResolution.model && modelsAreEqual(pending.model, planResolution.model)) {
+					this.#pendingModelSwitch = undefined;
+				}
+			}
 		}
 		this.session.setPlanModeState(undefined);
 		this.planModeEnabled = false;
@@ -1331,8 +1358,8 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#uiHelpers.renderSessionContext(sessionContext, options);
 	}
 
-	renderInitialMessages(): void {
-		this.#uiHelpers.renderInitialMessages();
+	renderInitialMessages(prebuiltContext?: SessionContext): void {
+		this.#uiHelpers.renderInitialMessages(prebuiltContext);
 	}
 
 	getUserMessageText(message: Message): string {
@@ -1396,6 +1423,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#commandController.handleToolsCommand();
 	}
 
+	handleContextCommand(): void {
+		this.#commandController.handleContextCommand();
+	}
+
 	#prepareSessionSwitch(): void {
 		this.#btwController.dispose();
 		this.#extensionUiController.clearExtensionTerminalInputListeners();

package/src/modes/theme/theme.ts

@@ -2328,8 +2328,14 @@ export function getSymbolTheme(): SymbolTheme {
 	};
 }
 
+let _markdownTheme: MarkdownTheme | undefined;
+let _markdownThemeRef: Theme | undefined;
+
 export function getMarkdownTheme(): MarkdownTheme {
-	return {
+	if (_markdownTheme !== undefined && _markdownThemeRef === theme) {
+		return _markdownTheme;
+	}
+	const markdownTheme: MarkdownTheme = {
 		heading: (text: string) => theme.fg("mdHeading", text),
 		link: (text: string) => theme.fg("mdLink", text),
 		linkUrl: (text: string) => theme.fg("mdLinkUrl", text),
@@ -2355,6 +2361,9 @@ export function getMarkdownTheme(): MarkdownTheme {
 			}
 		},
 	};
+	_markdownTheme = markdownTheme;
+	_markdownThemeRef = theme;
+	return markdownTheme;
 }
 
 export function getSelectListTheme(): SelectListTheme {

package/src/modes/types.ts

@@ -159,7 +159,7 @@ export interface InteractiveModeContext {
 		sessionContext: SessionContext,
 		options?: { updateFooter?: boolean; populateHistory?: boolean },
 	): void;
-	renderInitialMessages(): void;
+	renderInitialMessages(prebuiltContext?: SessionContext): void;
 	getUserMessageText(message: Message): string;
 	findLastAssistantMessage(): AssistantMessage | undefined;
 	extractAssistantText(message: AssistantMessage): string;
@@ -181,6 +181,7 @@ export interface InteractiveModeContext {
 	handleChangelogCommand(showFull?: boolean): Promise<void>;
 	handleHotkeysCommand(): void;
 	handleToolsCommand(): void;
+	handleContextCommand(): void;
 	handleDumpCommand(): void;
 	handleDebugTranscriptCommand(): Promise<void>;
 	handleClearCommand(): Promise<void>;
@@ -236,8 +237,9 @@ export interface InteractiveModeContext {
 	openExternalEditor(): void;
 	registerExtensionShortcuts(): void;
 	handlePlanModeCommand(initialPrompt?: string): Promise<void>;
-	handleLoopCommand(prompt?: string): Promise<void>;
-	disableLoopMode(options?: { silent?: boolean }): void;
+	handleLoopCommand(): Promise<void>;
+	disableLoopMode(): void;
+	pauseLoop(): void;
 	handleExitPlanModeTool(details: ExitPlanModeDetails): Promise<void>;
 
 	// Hook UI methods

package/src/modes/utils/context-usage.ts

@@ -0,0 +1,294 @@
+import type { Model } from "@oh-my-pi/pi-ai";
+import { countTokens } from "@oh-my-pi/pi-natives";
+import { formatNumber } from "@oh-my-pi/pi-utils";
+import type { Skill } from "../../extensibility/skills";
+import type { AgentSession } from "../../session/agent-session";
+import type { CompactionSettings } from "../../session/compaction";
+import { effectiveReserveTokens, estimateTokens, resolveThresholdTokens } from "../../session/compaction";
+import type { Tool } from "../../tools";
+import type { theme as Theme } from "../theme/theme";
+
+const GRID_COLS = 20;
+const GRID_ROWS = 10;
+const GRID_CELLS = GRID_COLS * GRID_ROWS;
+const GRID_GUTTER = "   ";
+
+const CELL_FILLED = "⛁";
+const CELL_FILLED_MESSAGES = "⛃";
+const CELL_FREE = "⛶";
+const CELL_BUFFER = "⛝";
+
+type CategoryId = "systemPrompt" | "systemTools" | "skills" | "messages";
+
+interface CategoryInfo {
+	id: CategoryId;
+	label: string;
+	tokens: number;
+	color: "accent" | "warning" | "success" | "userMessageText";
+	glyph: string;
+}
+
+export interface ContextBreakdown {
+	model: Model | undefined;
+	contextWindow: number;
+	categories: CategoryInfo[];
+	usedTokens: number;
+	autoCompactBufferTokens: number;
+	freeTokens: number;
+}
+
+function estimateSkillsTokens(skills: readonly Skill[]): number {
+	const fragments: string[] = [];
+	for (const skill of skills) {
+		// "- name: description\n" wire framing tokenizes ~identically to the
+		// concatenated form, so encode each piece separately and sum.
+		fragments.push(skill.name, skill.description);
+	}
+	return countTokens(fragments);
+}
+
+function estimateToolSchemaTokens(tools: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">>): number {
+	const fragments: string[] = [];
+	for (const tool of tools) {
+		fragments.push(tool.name, tool.description);
+		try {
+			fragments.push(JSON.stringify(tool.parameters ?? {}));
+		} catch {
+			// Schema may contain functions or cycles; ignore.
+		}
+	}
+	return countTokens(fragments);
+}
+
+function estimateMessagesTokens(session: AgentSession): number {
+	let total = 0;
+	for (const message of session.messages) {
+		total += estimateTokens(message);
+	}
+	return total;
+}
+
+/**
+ * Compute a breakdown of estimated context usage by category for the active
+ * session and model.
+ */
+export function computeContextBreakdown(session: AgentSession): ContextBreakdown {
+	const model = session.model;
+	const contextWindow = model?.contextWindow ?? 0;
+
+	const skillsTokens = estimateSkillsTokens(session.skills);
+	const toolsTokens = estimateToolSchemaTokens(session.agent.state.tools);
+	const messagesTokens = estimateMessagesTokens(session);
+
+	// The rendered system prompt already contains the skill descriptions and the
+	// markdown tool descriptions. To present a non-overlapping breakdown:
+	//   System prompt = total system prompt text - skills section (tool descriptions stay)
+	//   Tools         = JSON tool schema sent separately on the wire
+	//   Skills        = the skill list embedded in the system prompt
+	//   Messages      = conversation messages
+	const systemPromptTextTokens = countTokens(session.systemPrompt);
+	const systemPromptTokens = Math.max(0, systemPromptTextTokens - skillsTokens);
+
+	const categories: CategoryInfo[] = [
+		{ id: "systemPrompt", label: "System prompt", tokens: systemPromptTokens, color: "accent", glyph: CELL_FILLED },
+		{ id: "systemTools", label: "System tools", tokens: toolsTokens, color: "warning", glyph: CELL_FILLED },
+		{ id: "skills", label: "Skills", tokens: skillsTokens, color: "success", glyph: CELL_FILLED },
+		{
+			id: "messages",
+			label: "Messages",
+			tokens: messagesTokens,
+			color: "userMessageText",
+			glyph: CELL_FILLED_MESSAGES,
+		},
+	];
+
+	const usedTokens = categories.reduce((sum, c) => sum + c.tokens, 0);
+
+	let autoCompactBufferTokens = 0;
+	if (contextWindow > 0) {
+		const compactionSettings = session.settings.getGroup("compaction") as CompactionSettings;
+		if (compactionSettings.enabled && compactionSettings.strategy !== "off") {
+			const threshold = resolveThresholdTokens(contextWindow, compactionSettings);
+			autoCompactBufferTokens = Math.max(0, contextWindow - threshold);
+		} else {
+			autoCompactBufferTokens = 0;
+		}
+		// Even when fully disabled, fall back to a sensible reserve floor for display.
+		if (autoCompactBufferTokens === 0 && compactionSettings.enabled) {
+			autoCompactBufferTokens = effectiveReserveTokens(contextWindow, compactionSettings);
+		}
+	}
+	autoCompactBufferTokens = Math.min(autoCompactBufferTokens, Math.max(0, contextWindow - usedTokens));
+
+	const freeTokens = Math.max(0, contextWindow - usedTokens - autoCompactBufferTokens);
+
+	return {
+		model,
+		contextWindow,
+		categories,
+		usedTokens,
+		autoCompactBufferTokens,
+		freeTokens,
+	};
+}
+
+interface CellSpec {
+	glyph: string;
+	color: "accent" | "warning" | "success" | "userMessageText" | "muted" | "dim";
+}
+
+function planCells(breakdown: ContextBreakdown): CellSpec[] {
+	const cells: CellSpec[] = [];
+	const window = breakdown.contextWindow;
+
+	if (window <= 0) {
+		for (let i = 0; i < GRID_CELLS; i++) {
+			cells.push({ glyph: CELL_FREE, color: "dim" });
+		}
+		return cells;
+	}
+
+	const tokensPerCell = window / GRID_CELLS;
+
+	const ratioCells = (tokens: number): number => {
+		if (tokens <= 0) return 0;
+		return Math.max(1, Math.round(tokens / tokensPerCell));
+	};
+
+	const categoryCounts = breakdown.categories.map(category => ({
+		category,
+		count: ratioCells(category.tokens),
+	}));
+
+	let bufferCount = ratioCells(breakdown.autoCompactBufferTokens);
+
+	let usedCount = categoryCounts.reduce((sum, c) => sum + c.count, 0);
+
+	// Prevent the visualization from over-running the grid.
+	const maxUsable = GRID_CELLS - bufferCount;
+	if (usedCount > maxUsable) {
+		// Scale categories proportionally down to fit.
+		let overflow = usedCount - maxUsable;
+		// Trim from the largest categories first to preserve visibility for small ones.
+		const order = [...categoryCounts].sort((a, b) => b.count - a.count);
+		for (const entry of order) {
+			while (overflow > 0 && entry.count > 1) {
+				entry.count -= 1;
+				overflow -= 1;
+			}
+		}
+		usedCount = categoryCounts.reduce((sum, c) => sum + c.count, 0);
+		if (usedCount + bufferCount > GRID_CELLS) {
+			bufferCount = Math.max(0, GRID_CELLS - usedCount);
+		}
+	}
+
+	for (const { category, count } of categoryCounts) {
+		for (let i = 0; i < count; i++) {
+			cells.push({ glyph: category.glyph, color: category.color });
+		}
+	}
+
+	const freeCount = Math.max(0, GRID_CELLS - cells.length - bufferCount);
+	for (let i = 0; i < freeCount; i++) {
+		cells.push({ glyph: CELL_FREE, color: "dim" });
+	}
+	for (let i = 0; i < bufferCount; i++) {
+		cells.push({ glyph: CELL_BUFFER, color: "warning" });
+	}
+
+	// Pad to exactly GRID_CELLS in case rounding undershot.
+	while (cells.length < GRID_CELLS) {
+		cells.push({ glyph: CELL_FREE, color: "dim" });
+	}
+	return cells.slice(0, GRID_CELLS);
+}
+
+function percentString(part: number, whole: number, fractionDigits = 1): string {
+	if (whole <= 0) return "0%";
+	const pct = (part / whole) * 100;
+	if (pct > 0 && pct < 0.05) return "<0.1%";
+	return `${pct.toFixed(fractionDigits)}%`;
+}
+
+function buildLegendLines(breakdown: ContextBreakdown, theme: typeof Theme): string[] {
+	const lines: string[] = [];
+	const { model, contextWindow, categories, usedTokens, autoCompactBufferTokens, freeTokens } = breakdown;
+
+	const modelName = model?.name ?? model?.id ?? "no model";
+	const modelId = model?.id ?? "unknown";
+	const windowLabel = formatNumber(contextWindow).toLowerCase();
+
+	lines.push(theme.bold(`${modelName}`) + theme.fg("dim", ` (${windowLabel} context)`));
+	lines.push(theme.fg("muted", `${modelId}[${windowLabel}]`));
+	lines.push(
+		`${theme.bold(formatNumber(usedTokens))}${theme.fg("dim", `/${windowLabel} tokens`)}` +
+			theme.fg("muted", ` (${percentString(usedTokens, contextWindow)})`),
+	);
+	lines.push("");
+	lines.push(theme.fg("muted", "Estimated usage by category"));
+
+	for (const category of categories) {
+		const dot = theme.fg(category.color, category.glyph);
+		const label = category.label;
+		const tokens = formatNumber(category.tokens);
+		const pct = percentString(category.tokens, contextWindow);
+		lines.push(`${dot} ${label}: ${theme.bold(tokens)} ${theme.fg("dim", `tokens (${pct})`)}`);
+	}
+
+	const freeDot = theme.fg("dim", CELL_FREE);
+	lines.push(
+		`${freeDot} Free space: ${theme.bold(formatNumber(freeTokens))} ${theme.fg("dim", `(${percentString(freeTokens, contextWindow)})`)}`,
+	);
+
+	if (autoCompactBufferTokens > 0) {
+		const bufferDot = theme.fg("warning", CELL_BUFFER);
+		lines.push(
+			`${bufferDot} Autocompact buffer: ${theme.bold(formatNumber(autoCompactBufferTokens))} ${theme.fg(
+				"dim",
+				`tokens (${percentString(autoCompactBufferTokens, contextWindow)})`,
+			)}`,
+		);
+	}
+
+	return lines;
+}
+
+/**
+ * Render a colorful context-usage panel as ANSI text. Output is a series of
+ * lines pairing the grid (left) with the legend (right).
+ */
+export function renderContextUsage(breakdown: ContextBreakdown, theme: typeof Theme): string {
+	if (breakdown.contextWindow <= 0) {
+		return theme.fg("muted", "Context usage is unavailable: no model is selected for this session.");
+	}
+
+	const cells = planCells(breakdown);
+	const legend = buildLegendLines(breakdown, theme);
+
+	const totalLines = Math.max(GRID_ROWS, legend.length);
+	const lines: string[] = [];
+
+	for (let row = 0; row < totalLines; row++) {
+		let gridSegment = "";
+		if (row < GRID_ROWS) {
+			const rowCells: string[] = [];
+			for (let col = 0; col < GRID_COLS; col++) {
+				const cell = cells[row * GRID_COLS + col];
+				rowCells.push(theme.fg(cell.color, cell.glyph));
+			}
+			gridSegment = rowCells.join(" ");
+		} else {
+			// Pad with blanks the same visible width as a grid row so legend lines
+			// past the grid stay aligned with their column.
+			const blank = " ".repeat(GRID_COLS * 2 - 1);
+			gridSegment = blank;
+		}
+
+		const legendSegment = legend[row] ?? "";
+		const line = legendSegment.length > 0 ? `${gridSegment}${GRID_GUTTER}${legendSegment}` : gridSegment;
+		lines.push(line);
+	}
+
+	return lines.join("\n");
+}