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

package/src/edit/modes/hashline.ts

@@ -605,6 +605,26 @@ export class HashlineMismatchError extends Error {
 			`Edit rejected: ${mismatches.length} line${mismatches.length > 1 ? "s have" : " has"} changed since the last read (marked *).`,
 			"The edit was NOT applied, please use the updated file content shown below, and issue another edit tool-call.",
 		);
+
+		// Content-based recovery hint: the two-letter hash is weak, so a
+		// unique match elsewhere is only a candidate. Keep this advisory; never
+		// silently retarget stale edits based on a whole-file hash-only match.
+		const hints: string[] = [];
+		for (const m of mismatches) {
+			const matches: number[] = [];
+			for (let line = 1; line <= fileLines.length; line++) {
+				if (computeLineHash(line, fileLines[line - 1]) === m.expected) matches.push(line);
+				if (matches.length > 1) break;
+			}
+			if (matches.length === 1 && matches[0] !== m.line) {
+				hints.push(`  ${m.line}${m.expected} → ${matches[0]}${m.expected}`);
+			}
+		}
+		if (hints.length > 0) {
+			lines.push("Hash-only shifted candidate; verify content/context before using:");
+			lines.push(...hints);
+		}
+
 		lines.push("");
 
 		let prevLine = -1;
@@ -650,7 +670,7 @@ export function validateLineRef(ref: { line: number; hash: string }, fileLines:
 /**
  * Default search window for {@link tryRebaseAnchor} (lines on each side of the requested anchor).
  */
-export const ANCHOR_REBASE_WINDOW = 2;
+export const ANCHOR_REBASE_WINDOW = 5;
 
 /**
  * Look for the requested hash within ±`window` lines of `anchor.line`.

package/src/lsp/index.ts

@@ -1136,7 +1136,7 @@ export class LspTool implements AgentTool<typeof lspSchema, LspToolDetails, Them
 		_onUpdate?: AgentToolUpdateCallback<LspToolDetails>,
 		_context?: AgentToolContext,
 	): Promise<AgentToolResult<LspToolDetails>> {
-		const { action, file, line, symbol, occurrence, query, new_name, apply, timeout } = params;
+		const { action, file, line, symbol, query, new_name, apply, timeout } = params;
 		const timeoutSec = clampTimeout("lsp", timeout);
 		const timeoutSignal = AbortSignal.timeout(timeoutSec * 1000);
 		signal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
@@ -1449,9 +1449,7 @@ export class LspTool implements AgentTool<typeof lspSchema, LspToolDetails, Them
 
 			const uri = targetFile ? fileToUri(targetFile) : "";
 			const resolvedLine = line ?? 1;
-			const resolvedCharacter = targetFile
-				? await resolveSymbolColumn(targetFile, resolvedLine, symbol, occurrence)
-				: 0;
+			const resolvedCharacter = targetFile ? await resolveSymbolColumn(targetFile, resolvedLine, symbol) : 0;
 			const position = { line: resolvedLine - 1, character: resolvedCharacter };
 
 			let output: string;

package/src/lsp/render.ts

@@ -131,9 +131,6 @@ export function renderResult(
 	}
 	if (request?.symbol) {
 		requestLines.push(theme.fg("dim", `symbol: ${sanitizeInlineText(request.symbol)}`));
-		if (request.occurrence !== undefined) {
-			requestLines.push(theme.fg("dim", `occurrence: ${request.occurrence}`));
-		}
 	}
 	if (request?.query) requestLines.push(theme.fg("dim", `query: ${request.query}`));
 	if (request?.new_name) requestLines.push(theme.fg("dim", `new name: ${request.new_name}`));

package/src/lsp/types.ts

@@ -25,10 +25,7 @@ export const lspSchema = Type.Object({
 	),
 	file: Type.Optional(Type.String({ description: "File path" })),
 	line: Type.Optional(Type.Number({ description: "Line number (1-indexed)" })),
-	symbol: Type.Optional(
-		Type.String({ description: "Symbol/substring to locate on the line (used to compute column)" }),
-	),
-	occurrence: Type.Optional(Type.Number({ description: "Symbol occurrence on line (1-indexed, default: 1)" })),
+	symbol: Type.Optional(Type.String({ description: "Symbol/substring to locate on the line" })),
 	query: Type.Optional(Type.String({ description: "Search query or SSR pattern" })),
 	new_name: Type.Optional(Type.String({ description: "New name for rename" })),
 	apply: Type.Optional(Type.Boolean({ description: "Apply edits (default: true)" })),

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/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/interactive-mode.ts

@@ -492,10 +492,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 +504,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 +521,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 {
@@ -1396,6 +1399,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/types.ts

@@ -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");
+}