pi-zentui 0.24.0 → 0.25.0

package/README.md

@@ -114,7 +114,7 @@ The displayed preset is derived from your current selections: individual changes
 
 ### Minimal overrides
 
-Installation enables Opencode Editor, Framed User messages, Zentui selector borders, and Starship Footer. Working line and Thinking (Experimental) remain disabled. Missing fields retain those defaults; there is no automatic migration. Auto icons assume a Nerd Font without detecting one; ASCII changes icons, not the entire UI.
+Installation enables Opencode Editor, Framed User messages, Zentui selector borders, and Starship Footer. Working line and Thinking (Experimental) remain disabled. Missing fields retain those defaults; there is no automatic migration. Auto icons use Nerd glyphs for iTerm2, WezTerm, Ghostty, Kitty, and Alacritty environment signals, and otherwise fall back to ASCII. Set `ZENTUI_NERD_FONTS=1` or `0` to override Auto. These environment heuristics cannot detect whether a Nerd Font is installed or configured; explicit `nerd` and `ascii` modes always win. ASCII changes icons, not the entire UI.
 
 Change only what you need. For example, this changes only the Editor's accent:
 
@@ -172,10 +172,12 @@ Pi 0.84 also provides a native fullscreen TUI with a sticky editor and Footer. P
 
 **Codex quota (opt-in):** Show remaining 5-hour/weekly quota for `openai-codex` through independent Editor and Starship Footer settings, both off by default. See [configuration and private-endpoint limitations](./docs/configuration.md#codex-account-quota), including `$codex_quota` for custom templates.
 
+Minimalist can also show the latest assistant prompt's cache hit rate in its top-right metadata. Enable **Editor → Minimalist → Cache hit rate** or set `components.editor.styles.minimalist.showCacheHit` to `true`; it is off by default and does not depend on Footer.
+
 ## Requirements
 
 - [Pi](https://pi.dev) coding agent 0.80.5 or newer
-- A [Nerd Font](https://www.nerdfonts.com/) for icons, or `icons.mode: "ascii"`
+- A [Nerd Font](https://www.nerdfonts.com/) for Nerd icons; Auto falls back to ASCII when no supported terminal signal is present
 
 ## Development
 

package/docs/configuration.md

@@ -171,6 +171,7 @@ Reference only—not a starter file. Prefer the minimal overrides above. Optiona
           "showSessionName": true,
           "showTimer": true,
           "showCost": true,
+          "showCacheHit": false,
           "showGit": true,
           "contextThresholds": {
             "warning": 70,
@@ -475,9 +476,9 @@ Set `ZENTUI_DEBUG=1` when launching Pi to log the workaround diagnostic without
 
 ### Minimalist
 
-Set `components.editor.style` to `minimalist` or select it in `/zentui`. The rounded frame places viewport counts, Bash state, current/completed turn duration, and explicit session name at top left; cost, model, thinking, and context at top right; viewport count plus Git at bottom left; and configured path at bottom right. Unnamed sessions add no placeholder.
+Set `components.editor.style` to `minimalist` or select it in `/zentui`. The rounded frame places viewport counts, Bash state, current/completed turn duration, and explicit session name at top left; cost, model, thinking, context, and optional latest-prompt cache hit rate at top right; viewport count plus Git at bottom left; and configured path at bottom right. Unnamed sessions add no placeholder.
 
-Path examples are `src` (`compact`), `zentui/src` (`project`), and `~/Projects/zentui/src` (`full`). Context can render as `11%`, `11%/372k`, or, with the gauge enabled and enough room, `[█░░░░] 11%/372k`. The gauge shortens or disappears before the context text at narrow widths. Session name, timer, cost, and Git can be hidden independently; model, thinking, and context remain structurally stable.
+Path examples are `src` (`compact`), `zentui/src` (`project`), and `~/Projects/zentui/src` (`full`). Context can render as `11%`, `11%/372k`, or, with the gauge enabled and enough room, `[█░░░░] 11%/372k`. Enable `showCacheHit` to append values such as `Cache 98.2%`; it defaults to `false`, omits missing data, yields before context at narrow widths, and remains independent of Footer. The gauge shortens or disappears before the context text at narrow widths. Session name, timer, cost, cache hit rate, and Git can be hidden independently; model, thinking, and context remain structurally stable.
 
 Autocomplete stays inside the frame when Pi output can be split safely. Unknown third-party layouts fail open. Footer visibility remains independently controlled by `components.footer.style`; Minimalist does not remove Pi's header.
 
@@ -637,9 +638,15 @@ Zentui accepts at most 16 unique keys, keys up to 64 code units, and values up t
 | `↓` | Behind |
 | `⇕` | Diverged |
 
+## Icon Auto detection
+
+`icons.mode: "auto"` preserves Auto in memory and on disk while deriving an effective mode for the current process. Exact `ZENTUI_NERD_FONTS=1` or `0` overrides Auto. Otherwise Auto selects Nerd glyphs when `TERM_PROGRAM` is `iTerm.app`, `WezTerm`, or `ghostty` (case-insensitive), or when `KITTY_WINDOW_ID` or `ALACRITTY_SOCKET` is nonempty. Unknown terminals, VS Code, and Windows Terminal default to ASCII-safe glyphs. Explicit `nerd` and `ascii` modes ignore the override and environment signals.
+
+This is conservative terminal-environment detection, not font probing: terminal identity cannot prove that a Nerd Font is installed or configured. Use explicit mode or `ZENTUI_NERD_FONTS` when Auto chooses incorrectly. Custom icon overrides still win over either effective mode.
+
 ## Runtime detection
 
-Runtime/language modules use Starship Nerd Font symbols and defaults such as `bold green` for Node.js. Theme mode maps those styles through Pi; Footer terminal mode uses the terminal colorscheme's ANSI colors.
+Runtime/language modules use Starship Nerd Font symbols and defaults such as `bold green` for Node.js. Theme mode maps those styles through Pi; Footer terminal mode uses the terminal colorscheme's ANSI colors. In Auto mode, runtime, OS, package, rail, and gauge symbols all use the same derived effective icon mode.
 
 | Runtime/language | Detection examples |
 | --- | --- |

package/extensions/zentui/accent-rail-editor.ts

@@ -41,8 +41,8 @@ function clampLines(lines: string[], width: number): string[] {
 
 function selectedRail(config: ZentuiConfig): string {
 	const style = config.components.editor.styles["accent-rail"];
-	const fallback = config.icons.mode === "ascii" ? "|" : "▎";
-	const configured = config.icons.mode === "ascii" ? style.asciiRail : style.rail;
+	const fallback = config.icons.effectiveMode === "ascii" ? "|" : "▎";
+	const configured = config.icons.effectiveMode === "ascii" ? style.asciiRail : style.rail;
 	const sanitized = sanitizeEditorMetadataText(configured);
 	const glyph = truncateToWidth(sanitized, 1, "");
 	return visibleWidth(glyph) === 1 ? glyph : fallback;

package/extensions/zentui/config.ts

@@ -24,9 +24,9 @@ import {
 } from "./component-colors";
 import {
 	ICON_GLYPH_KEYS,
+	type IconEnvironment,
 	type IconGlyphs,
 	type IconMode,
-	NERD_DEFAULT_ICONS,
 	normalizeIconMode,
 	type ResolvedIcons,
 	resolveConfiguredIcons,
@@ -139,6 +139,7 @@ export type MinimalistEditorStyleConfig = {
 	showSessionName: boolean;
 	showTimer: boolean;
 	showCost: boolean;
+	showCacheHit: boolean;
 	showGit: boolean;
 	contextThresholds: ContextThresholds;
 };
@@ -477,6 +478,7 @@ const defaultMinimalistStyle: MinimalistEditorStyleConfig = {
 	showSessionName: true,
 	showTimer: true,
 	showCost: true,
+	showCacheHit: false,
 	showGit: true,
 	contextThresholds: { warning: 70, error: 90 },
 };
@@ -550,7 +552,7 @@ const defaultComponents: ComponentsConfig = {
 
 export const defaultConfig: PolishedTuiConfig = {
 	projectRefreshIntervalMs: DEFAULT_PROJECT_REFRESH_INTERVAL_MS,
-	icons: { mode: "auto", ...NERD_DEFAULT_ICONS },
+	icons: resolveConfiguredIcons("auto"),
 	colors: {
 		cwd: "bold cyan",
 		sessionName: "bold green",
@@ -1312,6 +1314,7 @@ function resolveComponents(config: ConfigRecord): ComponentsConfig {
 					),
 					showTimer: parseBoolean(minimalist.showTimer, defaultMinimalistStyle.showTimer),
 					showCost: parseBoolean(minimalist.showCost, defaultMinimalistStyle.showCost),
+					showCacheHit: parseBoolean(minimalist.showCacheHit, defaultMinimalistStyle.showCacheHit),
 					showGit: parseBoolean(minimalist.showGit, defaultMinimalistStyle.showGit),
 					contextThresholds: minimalistThresholds,
 				},
@@ -1529,7 +1532,10 @@ export function hasUnsupportedComponentStyle(
 	return unsupportedComponentStyles.get(config)?.has(owner) ?? false;
 }
 
-export function mergeConfig(parsed: unknown): PolishedTuiConfig {
+export function mergeConfig(
+	parsed: unknown,
+	iconEnvironment: IconEnvironment = process.env,
+): PolishedTuiConfig {
 	const config = isRecord(parsed) ? parsed : {};
 	const iconsRecord = recordValue(config.icons);
 	const colorsRecord = recordValue(config.colors);
@@ -1539,6 +1545,7 @@ export function mergeConfig(parsed: unknown): PolishedTuiConfig {
 		icons: resolveConfiguredIcons(
 			normalizeIconMode(iconsRecord.mode),
 			normalizeIconOverrides(iconsRecord),
+			iconEnvironment,
 		),
 		colors: {
 			...defaultConfig.colors,
@@ -1806,6 +1813,7 @@ function applyMinimalistStylePatch(
 	if (patch.showSessionName !== undefined) style.showSessionName = patch.showSessionName;
 	if (patch.showTimer !== undefined) style.showTimer = patch.showTimer;
 	if (patch.showCost !== undefined) style.showCost = patch.showCost;
+	if (patch.showCacheHit !== undefined) style.showCacheHit = patch.showCacheHit;
 	if (patch.showGit !== undefined) style.showGit = patch.showGit;
 	if (patch.contextThresholds !== undefined) {
 		style.contextThresholds = { ...style.contextThresholds, ...patch.contextThresholds };

package/extensions/zentui/footer.ts

@@ -240,7 +240,7 @@ export function installFooter(
 					FOOTER_FORMAT_ALIASES,
 				);
 				const colorSource = config.components.footer.colorSource;
-				const iconMode = config.icons.mode;
+				const iconMode = config.icons.effectiveMode;
 				const pathDisplay = config.components.footer.styles.starship.pathDisplay;
 				const formattedCwd = sanitizeEditorMetadataText(
 					formatCwdLabel(ctx.cwd, config.icons.cwd, {
@@ -451,7 +451,12 @@ export function installFooter(
 								theme,
 								colorSource,
 								componentColor(config, "footer", "os"),
-								formatOsLabel(config.icons.os, iconMode),
+								formatOsLabel(
+									config.icons.os,
+									iconMode,
+									process.platform,
+									config.icons.osOverridden,
+								),
 							);
 						case "time":
 							return renderStyleForSource(
@@ -672,7 +677,7 @@ export function installFooter(
 							theme,
 							colorSource,
 							componentColor(config, "footer", "os"),
-							formatOsLabel(config.icons.os, iconMode),
+							formatOsLabel(config.icons.os, iconMode, process.platform, config.icons.osOverridden),
 						)
 					: "";
 				const left = [

package/extensions/zentui/format.ts

@@ -572,6 +572,7 @@ export function formatOsLabel(
 	configuredIcon: string,
 	mode: IconMode = "auto",
 	platform: string = process.platform,
+	osOverridden = false,
 ): string {
-	return resolveOsIcon(configuredIcon, mode, platform);
+	return resolveOsIcon(configuredIcon, mode, platform, process.env, osOverridden);
 }

package/extensions/zentui/icons.ts

@@ -7,6 +7,8 @@
  */
 
 export type IconMode = "auto" | "nerd" | "ascii";
+export type EffectiveIconMode = Exclude<IconMode, "auto">;
+export type IconEnvironment = Readonly<Record<string, string | undefined>>;
 
 export type IconGlyphs = {
 	cwd: string;
@@ -31,7 +33,14 @@ export type IconGlyphs = {
 	package: string;
 };
 
-export type ResolvedIcons = IconGlyphs & { mode: IconMode };
+export type ResolvedIcons = IconGlyphs & {
+	/** Canonical user choice; Auto is never replaced with an environment-specific value. */
+	mode: IconMode;
+	/** Runtime-only mode derived from the canonical choice and current environment. */
+	effectiveMode: EffectiveIconMode;
+	/** Runtime-only provenance needed when an override equals the active mode default. */
+	osOverridden: boolean;
+};
 
 export const ICON_GLYPH_KEYS = [
 	"cwd",
@@ -192,39 +201,65 @@ export function normalizeIconMode(value: unknown): IconMode {
 	return isIconMode(value) ? value : "auto";
 }
 
-export function modeDefaultIcons(mode: IconMode): IconGlyphs {
-	return mode === "ascii" ? { ...ASCII_DEFAULT_ICONS } : { ...NERD_DEFAULT_ICONS };
+export function detectAutoIconMode(env: IconEnvironment): EffectiveIconMode {
+	if (env.ZENTUI_NERD_FONTS === "1") return "nerd";
+	if (env.ZENTUI_NERD_FONTS === "0") return "ascii";
+
+	const termProgram = env.TERM_PROGRAM?.toLowerCase();
+	if (termProgram === "iterm.app" || termProgram === "wezterm" || termProgram === "ghostty") {
+		return "nerd";
+	}
+	if (env.KITTY_WINDOW_ID?.trim() || env.ALACRITTY_SOCKET?.trim()) return "nerd";
+	return "ascii";
+}
+
+export function resolveEffectiveIconMode(
+	mode: IconMode,
+	env: IconEnvironment = process.env,
+): EffectiveIconMode {
+	return mode === "auto" ? detectAutoIconMode(env) : mode;
+}
+
+export function modeDefaultIcons(mode: IconMode, env: IconEnvironment = process.env): IconGlyphs {
+	return resolveEffectiveIconMode(mode, env) === "ascii"
+		? { ...ASCII_DEFAULT_ICONS }
+		: { ...NERD_DEFAULT_ICONS };
 }
 
 export function resolveConfiguredIcons(
 	mode: IconMode,
 	overrides: Partial<IconGlyphs> = {},
+	env: IconEnvironment = process.env,
 ): ResolvedIcons {
-	const base = modeDefaultIcons(mode);
+	const effectiveMode = resolveEffectiveIconMode(mode, env);
+	const base = modeDefaultIcons(effectiveMode);
 	const rail =
 		typeof overrides.rail === "string" && overrides.rail.trim().length > 0
 			? overrides.rail
 			: base.rail;
 	return {
 		mode,
+		effectiveMode,
 		...base,
 		...overrides,
 		rail,
+		osOverridden: typeof overrides.os === "string",
 	};
 }
 
-/**
- * Honor a custom `icons.os` when it differs from the mode default.
- * Otherwise map by platform for the active mode.
- */
+/** Map the active mode default by platform while preserving explicit `icons.os` overrides. */
 export function resolveOsIcon(
 	configuredOsIcon: string,
 	mode: IconMode = "auto",
 	platform: string = process.platform,
+	env: IconEnvironment = process.env,
+	osOverridden = false,
 ): string {
-	const modeDefault = modeDefaultIcons(mode).os;
+	if (osOverridden) return configuredOsIcon;
+	const effectiveMode = resolveEffectiveIconMode(mode, env);
+	const modeDefault = modeDefaultIcons(effectiveMode).os;
 	if (configuredOsIcon !== modeDefault) return configuredOsIcon;
-	const platformMap = mode === "ascii" ? OS_PLATFORM_ICONS_ASCII : OS_PLATFORM_ICONS_NERD;
+	const platformMap = effectiveMode === "ascii" ? OS_PLATFORM_ICONS_ASCII : OS_PLATFORM_ICONS_NERD;
 	return platformMap[platform] ?? configuredOsIcon;
 }
 
@@ -232,8 +267,9 @@ export function resolveRuntimeSymbol(
 	name: string,
 	nerdSymbol: string,
 	mode: IconMode = "auto",
+	env: IconEnvironment = process.env,
 ): string {
-	if (mode !== "ascii") return nerdSymbol;
+	if (resolveEffectiveIconMode(mode, env) !== "ascii") return nerdSymbol;
 	return RUNTIME_ASCII_SYMBOLS[name] ?? (name.slice(0, 3) || "*");
 }
 
@@ -243,8 +279,12 @@ export function resolveRuntimeSymbol(
  * Honors a configured `icons.package` override; otherwise falls back to the
  * mode default (Nerd Font preset / ASCII label).
  */
-export function resolvePackageIcon(configuredPackageIcon: string, mode: IconMode = "auto"): string {
-	const modeDefault = modeDefaultIcons(mode).package;
+export function resolvePackageIcon(
+	configuredPackageIcon: string,
+	mode: IconMode = "auto",
+	env: IconEnvironment = process.env,
+): string {
+	const modeDefault = modeDefaultIcons(mode, env).package;
 	if (typeof configuredPackageIcon === "string" && configuredPackageIcon.length > 0) {
 		return configuredPackageIcon;
 	}

package/extensions/zentui/index.ts

@@ -796,6 +796,7 @@ export default function (pi: ExtensionAPI) {
 						thinkingLevel: getThinkingLevel(),
 						contextPercent: getContextPercent(ctx),
 						contextWindow: getContextWindow(ctx),
+						cacheHitRate: state.usageTotals.latestCacheHitRate,
 						sessionName: ctx.sessionManager.getSessionName() ?? "",
 						agentDurationMs: getAgentDurationMs(),
 						agentActive: agentRunActive,
@@ -836,6 +837,7 @@ export default function (pi: ExtensionAPI) {
 						thinkingLevel: getThinkingLevel(),
 						contextPercent: getContextPercent(ctx),
 						contextWindow: getContextWindow(ctx),
+						cacheHitRate: state.usageTotals.latestCacheHitRate,
 						sessionName: ctx.sessionManager.getSessionName() ?? "",
 						agentDurationMs: getAgentDurationMs(),
 						agentActive: agentRunActive,
@@ -1500,7 +1502,7 @@ export default function (pi: ExtensionAPI) {
 		interactionMetrics.agentEnd();
 		pauseAgentRun();
 		workingLine.finishAgent(ctx);
-		workingLine.updateMetrics(displayTokens, interactionMetrics.currentThought(), ctx);
+		workingLine.flushMetrics(displayTokens, interactionMetrics.currentThought(), ctx);
 		// Reconcile once more after Pi has persisted the assistant message.
 		syncInteractiveAndProjectStateWithUsage(event, ctx);
 	});
@@ -1525,7 +1527,7 @@ export default function (pi: ExtensionAPI) {
 		thinkingExperimental.endMessage(event);
 		const result = interactionMetrics.messageEnd(event.message);
 		if (result.status === "accepted") {
-			workingLine.updateMetrics(result.displayTokens, interactionMetrics.currentThought(), ctx);
+			workingLine.flushMetrics(result.displayTokens, interactionMetrics.currentThought(), ctx);
 		}
 		// Pi notifies extensions before persisting a successful message, so retain its live
 		// context until agent_end; accepted failed messages clear immediately instead of showing

package/extensions/zentui/minimalist-editor.ts

@@ -10,6 +10,7 @@ import {
 	bashModeLabel,
 	buildContextGauge,
 	contextColorTier,
+	formatCacheHitRate,
 	formatCount,
 	formatCwdLabel,
 	formatElapsedDuration,
@@ -53,6 +54,7 @@ export type MinimalistEditorMetadata = {
 	thinkingLevel?: string;
 	contextPercent?: number;
 	contextWindow?: number;
+	cacheHitRate?: number;
 	sessionName?: string;
 	agentDurationMs?: number;
 	agentActive?: boolean;
@@ -256,7 +258,11 @@ function renderTopRight(
 		let context = renderStyleForSource(uiTheme, source, style, text);
 		if (config.components.editor.styles.minimalist.contextGauge) {
 			for (const gaugeWidth of [5, 3]) {
-				const gauge = `[${buildContextGauge(percent, gaugeWidth, config.icons.mode === "ascii")}] ${text}`;
+				const gauge = `[${buildContextGauge(
+					percent,
+					gaugeWidth,
+					config.icons.effectiveMode === "ascii",
+				)}] ${text}`;
 				const styledGauge = renderStyleForSource(uiTheme, source, style, gauge);
 				const candidate = joinParts([...parts, styledGauge]);
 				if (visibleWidth(candidate) <= availableWidth) {
@@ -277,6 +283,15 @@ function renderTopRight(
 		}
 		parts.push(context);
 	}
+	const cacheHit =
+		config.components.editor.styles.minimalist.showCacheHit &&
+		metadata.cacheHitRate !== undefined &&
+		Number.isFinite(metadata.cacheHitRate)
+			? safeThemeFg(uiTheme, "muted", `Cache ${formatCacheHitRate(metadata.cacheHitRate)}`)
+			: "";
+	if (cacheHit && (!fit || visibleWidth(joinParts([...parts, cacheHit])) <= availableWidth)) {
+		parts.push(cacheHit);
+	}
 	const quota = renderCodexQuota(metadata.codexQuota, uiTheme, config, "editor");
 	if (quota && visibleWidth(joinParts([...parts, quota])) <= availableWidth) parts.push(quota);
 	const joined = joinParts(parts);

package/extensions/zentui/settings-command.ts

@@ -570,7 +570,7 @@ function buildAppearanceItems(config: PolishedTuiConfig): SettingItem[] {
 			id: "iconMode",
 			label: "Icon mode",
 			description:
-				"Auto assumes a Nerd Font (no font detection), as does Nerd. ASCII replaces icons only, not every UI border or glyph.",
+				"Auto uses conservative signals: TERM_PROGRAM=iTerm.app|WezTerm|ghostty (case-insensitive), nonempty KITTY_WINDOW_ID or ALACRITTY_SOCKET, and exact ZENTUI_NERD_FONTS=1|0; otherwise ASCII. Environment heuristics cannot detect whether a Nerd Font is installed/configured.",
 			currentValue: config.icons.mode,
 			values: iconModeValues,
 		},
@@ -711,6 +711,13 @@ function buildMinimalistEditorStyleItems(config: PolishedTuiConfig): SettingItem
 			currentValue: featureValue(minimalist.showCost),
 			values: featureStateValues,
 		},
+		{
+			id: "minimalistShowCacheHit",
+			label: "Cache hit rate",
+			description: "Show the latest prompt cache hit rate.",
+			currentValue: featureValue(minimalist.showCacheHit),
+			values: featureStateValues,
+		},
 		{
 			id: "minimalistShowGit",
 			label: "Git",
@@ -1723,9 +1730,11 @@ export function registerZentuiSettingsCommand(pi: ExtensionAPI, deps: SettingsCo
 																? "showTimer"
 																: id === "minimalistShowCost"
 																	? "showCost"
-																	: id === "minimalistShowGit"
-																		? "showGit"
-																		: undefined;
+																	: id === "minimalistShowCacheHit"
+																		? "showCacheHit"
+																		: id === "minimalistShowGit"
+																			? "showGit"
+																			: undefined;
 												if (!key) return;
 												deps.setMinimalist({ [key]: enabled }, ctx);
 											} else return;

package/extensions/zentui/settings-previews.ts

@@ -134,6 +134,7 @@ export function renderEditorSettingsPreview(
 				thinkingLevel: "high",
 				contextPercent: 75,
 				contextWindow: 372_000,
+				cacheHitRate: 98.2,
 				sessionName: "Preview",
 				agentDurationMs: 12_000,
 				agentActive: true,

package/extensions/zentui/working-line.ts

@@ -40,6 +40,8 @@ export const MAX_WORKING_LINE_NORMALIZED_CODE_UNITS = 256;
 export const MAX_WORKING_LINE_STYLE_TOKENS = 4;
 export const MAX_WORKING_LINE_STYLE_CODE_UNITS = 48;
 export const MAX_WORKING_LINE_ENTRIES_EXAMINED = 256;
+/** Minimum interval between metric-only Loader replacements while an assistant streams. */
+export const WORKING_LINE_METRIC_UPDATE_INTERVAL_MS = 50;
 
 const WORKING_LINE_FALLBACKS: Record<"low" | "mid" | "high", SourceStyleFallback> = {
 	low: { theme: "dim", terminal: "bright-black" },
@@ -67,6 +69,16 @@ type WorkingLineContext = {
 
 type AgentDurationListener = (durationMs: number) => void;
 
+export type WorkingLineMetricScheduler = {
+	setTimeout(callback: () => void, delayMs: number): unknown;
+	clearTimeout(handle: unknown): void;
+};
+
+const defaultMetricScheduler: WorkingLineMetricScheduler = {
+	setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
 /** One agent-duration clock shared by minimalist Editor and Working-line consumers. */
 export class AgentDurationClock {
 	private startedAt: number | undefined;
@@ -1051,6 +1063,11 @@ export class WorkingLineController {
 	private elapsedUpdatesContext: WorkingLineContext | undefined;
 	private elapsedUpdatesGeneration = 0;
 	private stopElapsedUpdates: (() => void) | undefined;
+	private lastMetricWriteAt: number | undefined;
+	private metricUpdateScheduled = false;
+	private metricUpdateHandle: unknown;
+	private metricUpdateContext: WorkingLineContext | undefined;
+	private metricUpdateGeneration = 0;
 
 	constructor(
 		private readonly getConfig: () => ZentuiConfig,
@@ -1060,6 +1077,7 @@ export class WorkingLineController {
 		private readonly now: () => number = Date.now,
 		private readonly getThought: () => WorkingLineRuntimeSegments["thought"] = () => this.thought,
 		private readonly onUnavailable: () => void = () => {},
+		private readonly metricScheduler: WorkingLineMetricScheduler = defaultMetricScheduler,
 	) {}
 
 	startSession(ctx: WorkingLineContext): WorkingLineReconcileResult {
@@ -1082,6 +1100,7 @@ export class WorkingLineController {
 	}
 
 	startTurn(ctx: WorkingLineContext): WorkingLineReconcileResult {
+		this.lastMetricWriteAt = undefined;
 		const config = this.getConfig().components.workingLine;
 		this.activeTools.clear();
 		const selectedMessage = selectWorkingLineMessage(config, this.random);
@@ -1099,12 +1118,15 @@ export class WorkingLineController {
 	): void {
 		this.tokens = tokens;
 		this.thought = thought;
-		this.updateIndicator(ctx);
+		this.scheduleMetricIndicator(ctx);
 		this.reconcileElapsedUpdates(ctx);
 	}
 
 	updateTokens(tokens: WorkingLineRuntimeSegments["tokens"], ctx: WorkingLineContext): void {
-		this.updateMetrics(tokens, this.getThought(), ctx);
+		this.tokens = tokens;
+		this.thought = this.getThought();
+		this.updateIndicator(ctx);
+		this.reconcileElapsedUpdates(ctx);
 	}
 
 	updateExtensionSegments(segments: readonly string[], ctx: WorkingLineContext): boolean {
@@ -1143,7 +1165,7 @@ export class WorkingLineController {
 		this.updateIndicator(ctx);
 	}
 
-	settle(
+	flushMetrics(
 		tokens: WorkingLineRuntimeSegments["tokens"],
 		thought: WorkingLineRuntimeSegments["thought"],
 		ctx: WorkingLineContext,
@@ -1154,6 +1176,14 @@ export class WorkingLineController {
 		this.reconcileElapsedUpdates(ctx);
 	}
 
+	settle(
+		tokens: WorkingLineRuntimeSegments["tokens"],
+		thought: WorkingLineRuntimeSegments["thought"],
+		ctx: WorkingLineContext,
+	): void {
+		this.flushMetrics(tokens, thought, ctx);
+	}
+
 	reconcile(ctx: WorkingLineContext): WorkingLineReconcileResult {
 		const config = this.getConfig().components.workingLine;
 		if (!config.enabled) {
@@ -1195,6 +1225,7 @@ export class WorkingLineController {
 		rebasePhase = false,
 		selectedMessage?: string,
 	): WorkingLineReconcileResult {
+		this.cancelMetricIndicator();
 		const ui = workingLineUi(ctx);
 		if (!ui) {
 			this.installed = false;
@@ -1350,6 +1381,7 @@ export class WorkingLineController {
 	}
 
 	private updateIndicator(ctx: WorkingLineContext): boolean {
+		this.cancelMetricIndicator();
 		const rootConfig = this.getConfig();
 		if (!rootConfig.components.workingLine.enabled || !this.installed) return false;
 		const ui = workingLineUi(ctx);
@@ -1365,6 +1397,49 @@ export class WorkingLineController {
 		}
 	}
 
+	private scheduleMetricIndicator(ctx: WorkingLineContext): void {
+		const config = this.getConfig().components.workingLine;
+		if (!config.enabled || !this.installed) return;
+		this.metricUpdateContext = ctx;
+		const sampledAt = this.now();
+		const elapsed =
+			this.lastMetricWriteAt === undefined
+				? Number.POSITIVE_INFINITY
+				: Math.max(0, sampledAt - this.lastMetricWriteAt);
+		if (elapsed >= WORKING_LINE_METRIC_UPDATE_INTERVAL_MS) {
+			this.updateIndicator(ctx);
+			this.lastMetricWriteAt = sampledAt;
+			return;
+		}
+		if (this.metricUpdateScheduled) return;
+		this.metricUpdateScheduled = true;
+		const generation = ++this.metricUpdateGeneration;
+		this.metricUpdateHandle = this.metricScheduler.setTimeout(
+			() => {
+				if (!this.metricUpdateScheduled || generation !== this.metricUpdateGeneration) return;
+				this.metricUpdateScheduled = false;
+				this.metricUpdateHandle = undefined;
+				const latest = this.metricUpdateContext;
+				this.metricUpdateContext = undefined;
+				if (latest) {
+					this.updateIndicator(latest);
+					this.lastMetricWriteAt = this.now();
+				}
+			},
+			Math.max(0, WORKING_LINE_METRIC_UPDATE_INTERVAL_MS - elapsed),
+		);
+	}
+
+	private cancelMetricIndicator(): void {
+		this.metricUpdateContext = undefined;
+		this.metricUpdateGeneration++;
+		if (this.metricUpdateScheduled) {
+			this.metricScheduler.clearTimeout(this.metricUpdateHandle);
+		}
+		this.metricUpdateScheduled = false;
+		this.metricUpdateHandle = undefined;
+	}
+
 	private reconcileElapsedUpdates(ctx: WorkingLineContext): void {
 		this.elapsedUpdatesContext = ctx;
 		const config = this.getConfig().components.workingLine;
@@ -1473,6 +1548,7 @@ export class WorkingLineController {
 	}
 
 	private reset(ctx: WorkingLineContext): void {
+		this.cancelMetricIndicator();
 		this.deactivateElapsedUpdates();
 		if (!this.ownsIndicator && !this.ownsMessage) return;
 		const ui = workingLineUi(ctx);
@@ -1499,6 +1575,8 @@ export class WorkingLineController {
 	}
 
 	private clearRuntime(): void {
+		this.cancelMetricIndicator();
+		this.lastMetricWriteAt = undefined;
 		this.deactivateElapsedUpdates();
 		this.agentActive = false;
 		this.activeTools.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-zentui",
-	"version": "0.24.0",
+	"version": "0.25.0",
 	"description": "A Starship-inspired statusline and Opencode-style TUI for Pi.",
 	"type": "module",
 	"license": "MIT",