pi-zentui 0.26.0 → 0.27.0

package/docs/configuration.md

@@ -4,6 +4,16 @@
 
 Zentui reads optional user configuration from `~/.pi/agent/zentui.json`. Missing or invalid known values fall back to defaults. Unknown fields are ignored at runtime but preserved on disk by component save operations where they are user-owned migration or future-style data.
 
+## Refresh and cache freshness
+
+- Settings telemetry checks file signatures on each demanded sync, including inode, size, modification and change times. Ordinary edits, replacements and trust changes reload the snapshot; untrusted project settings are never inspected. Signature equality assumes normal filesystem metadata updates, not content hashing. Read failures retry.
+- Session usage reuses one event-owned snapshot under Pi's append-only session contract. Session/leaf changes and message, agent, settlement, tree and compaction boundaries refresh totals. Silent same-leaf history edits outside those boundaries are not detected by this fast path; the generic usage helper remains mutation-safe.
+- Repository path rendering uses the latest controlled project refresh. Creating or removing a `.git` marker becomes visible on the next demanded event, explicit or interval refresh, not every render. Disabling polling leaves event/explicit refreshes active.
+- Runtime and package discovery share one asynchronous filesystem snapshot per refresh; manifests are read fresh. Runtime versions retain the bounded 32-project cache, 60-second successful-version lifetime and 5-second failure retry, with marker and environment changes invalidating earlier results.
+- Footer syntax uses a 32-entry exact-format cache. Format and alias edits are observed immediately; theme, width, status and quota output are never cached with syntax.
+
+Disabled, native and unowned surfaces do not demand these probes on behalf of Zentui. Pi and other extensions may perform their own work.
+
 ## Start with minimal overrides
 
 Do not copy the complete defaults into your file. Omitted fields keep defaults and source-aware inheritance. New installs enable Opencode Editor, Framed User messages, Zentui selector borders, and Starship Footer; Working line and Thinking (Experimental) are disabled.
@@ -215,7 +225,8 @@ Reference only—not a starter file. Prefer the minimal overrides above. Optiona
           "contextThresholds": {
             "warning": 70,
             "error": 90
-          }
+          },
+          "separator": "dash"
         }
       }
     },
@@ -236,6 +247,7 @@ Reference only—not a starter file. Prefer the minimal overrides above. Optiona
     },
     "workingLine": {
       "enabled": false,
+      "placement": "above",
       "turnSummary": true,
       "spinner": "star-bloom",
       "spinnerIntervalMs": 100,
@@ -412,6 +424,7 @@ Reference only—not a starter file. Prefer the minimal overrides above. Optiona
 - `components.thinkingSteps` independently owns opt-in **Thinking (Experimental)** display. It defaults to `{ "enabled": false, "mode": "tree" }`; canonical modes are `rail | tree | streaming`. The former persisted `streaming-experimental` value is accepted only as a migration alias and is normalized to `streaming` on save.
 - All three modes decorate Pi's private host renderer and are tested on exact Pi versions 0.80.5, 0.82.1, 0.83.0, 0.84.0, 0.84.4, and 0.85.1. Active Streaming can switch live to Rail or Tree, and Rail and Tree can switch live between each other. Entering Streaming from a structural mode, first enable, and re-enable after live disable require restart; live disable restores native thinking. Disabled mode changes only preconfigure.
 - `components.workingLine.enabled` is the sole Working-line ownership switch. Thinking (Experimental) never enables, configures, or owns the Working line and leaves the existing **Thinking time** option unchanged.
+- `components.workingLine.placement` (`above | border`) selects the default floating row or the Minimalist/Opencode top border. Accent Rail supports only Above. Disabled, native, unavailable, or unsafe/narrow editors and Pi versions without working-row visibility control fall back to Above without changing saved choices. Legacy `input` normalizes to `above`; the prompt remains available for typing.
 - `components.selectorBorders` owns selector-border enablement, fixed `zentui` style, and color source. Disable it for native Pi behavior.
 - `components.footer` owns `native | starship | hidden` style selection, color source, model label, and Starship options. Hidden hides its main segments, retaining only allowed extension statuses; an empty status line occupies no rows.
 - Starship's package-version segment reads the project manifest and is distinct from the runtime segment, which reports the installed toolchain.
@@ -521,7 +534,7 @@ Set `ZENTUI_DEBUG=1` when launching Pi to log the workaround diagnostic without
 
 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`. 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.
+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. Metadata items are joined with dashes by default (`separator: "dash"`) or dots (`separator: "dot"`).
 
 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.
 

package/extensions/zentui/config.ts

@@ -54,10 +54,12 @@ export type WorkingLineSpinner =
 	| "claude-inspired"
 	| "pulse";
 export type WorkingLineTextAnimation = "classic" | "kitt" | "disabled";
+export type WorkingLinePlacement = "above" | "border";
 export type ThinkingStepsMode = "rail" | "tree" | "streaming";
 export type ComponentStyleOwner = "editor" | "userMessages" | "selectorBorders" | "footer";
 export type MinimalistPathDisplayMode = "compact" | "project" | "full";
 export type MinimalistContextFormat = "percent" | "percent-total";
+export type MinimalistEditorSeparator = "dash" | "dot";
 export type EditorBorderColorMode = "static" | "adaptive";
 export type CompletionMenuStyle = "native" | "palette";
 export type CompactFooterMaxLines = 1 | 2 | 3 | "unlimited";
@@ -142,6 +144,7 @@ export type MinimalistEditorStyleConfig = {
 	showCacheHit: boolean;
 	showGit: boolean;
 	contextThresholds: ContextThresholds;
+	separator: MinimalistEditorSeparator;
 };
 
 /** Temporary name retained for existing settings consumers. */
@@ -258,6 +261,7 @@ export type WorkingLineComponentConfig = {
 	colorSource: ColorSource;
 	messages: WorkingLineMessagesConfig;
 	segments: WorkingLineSegmentsConfig;
+	placement: WorkingLinePlacement;
 };
 
 export type WorkingLineComponentPatch = Partial<
@@ -498,6 +502,7 @@ const defaultMinimalistStyle: MinimalistEditorStyleConfig = {
 	showCacheHit: false,
 	showGit: true,
 	contextThresholds: { warning: 70, error: 90 },
+	separator: "dash",
 };
 
 const defaultStarshipStyle: StarshipFooterStyleConfig = {
@@ -557,6 +562,7 @@ const defaultComponents: ComponentsConfig = {
 		colorSource: "theme",
 		messages: { custom: true, values: [...PI_WORKING_LINE_MESSAGES] },
 		segments: { tool: true, elapsed: true, thought: true, tokens: true },
+		placement: "above",
 	},
 	selectorBorders: { enabled: true, style: "zentui", colorSource: "theme" },
 	footer: {
@@ -1405,6 +1411,10 @@ function resolveComponents(config: ConfigRecord): ComponentsConfig {
 					showCacheHit: parseBoolean(minimalist.showCacheHit, defaultMinimalistStyle.showCacheHit),
 					showGit: parseBoolean(minimalist.showGit, defaultMinimalistStyle.showGit),
 					contextThresholds: minimalistThresholds,
+					separator:
+						minimalist.separator === "dash" || minimalist.separator === "dot"
+							? minimalist.separator
+							: defaultMinimalistStyle.separator,
 				},
 			},
 		},
@@ -1466,6 +1476,10 @@ function resolveComponents(config: ConfigRecord): ComponentsConfig {
 				workingLine.textAnimation === "disabled"
 					? workingLine.textAnimation
 					: defaultComponents.workingLine.textAnimation,
+			placement:
+				workingLine.placement === "border"
+					? workingLine.placement
+					: defaultComponents.workingLine.placement,
 			colorSource: parseColorSource(
 				workingLine.colorSource,
 				defaultComponents.workingLine.colorSource,
@@ -1903,6 +1917,7 @@ function applyMinimalistStylePatch(
 	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.separator !== undefined) style.separator = patch.separator;
 	if (patch.contextThresholds !== undefined) {
 		style.contextThresholds = { ...style.contextThresholds, ...patch.contextThresholds };
 	}
@@ -1970,6 +1985,7 @@ export function saveWorkingLineComponentPatch(
 			if (patch.textIntervalMs !== undefined) component.textIntervalMs = patch.textIntervalMs;
 			if (patch.textAnimation !== undefined) component.textAnimation = patch.textAnimation;
 			if (patch.colorSource !== undefined) component.colorSource = patch.colorSource;
+			if (patch.placement !== undefined) component.placement = patch.placement;
 			if (patch.messages?.custom !== undefined) component.messages.custom = patch.messages.custom;
 			if (patch.messages?.values !== undefined) {
 				component.messages.values = normalizeWorkingLineMessages([...patch.messages.values]);

package/extensions/zentui/editor-mouse.ts

@@ -1,11 +1,17 @@
-// Structural subset keeps mouse support optional on Pi versions before 0.85.
-export type EditorMouseEvent = {
+import type { EditorComponent } from "@earendil-works/pi-tui";
+
+type LegacyEditorMouseEvent = {
 	type: string;
 	x: number;
 	y: number;
 	width: number;
 	height: number;
 };
+// Use the installed Pi event contract without requiring mouse exports on pre-0.85 Pi.
+type MouseEventFor<T> = T extends { handleMouse?: (event: infer Event) => unknown }
+	? Event
+	: LegacyEditorMouseEvent;
+export type EditorMouseEvent = MouseEventFor<EditorComponent>;
 export type EditorMouseResult = {
 	handled?: boolean;
 	capture?: boolean;

package/extensions/zentui/footer-format.ts

@@ -19,6 +19,131 @@ export type CompactFormatChunk =
 	| { kind: "tokens"; tokens: FormatToken[]; boundary: CompactBoundaryKind }
 	| { kind: "extensions"; boundary: CompactBoundaryKind };
 
+/** Cached syntax is deeply readonly; public parser/compiler results remain mutable. */
+export type ReadonlyFormatToken =
+	| Readonly<Exclude<FormatToken, { kind: "group" }>>
+	| { readonly kind: "group"; readonly tokens: readonly ReadonlyFormatToken[] };
+
+type ReadonlyCompactChunk =
+	| {
+			readonly kind: "tokens";
+			readonly tokens: readonly ReadonlyFormatToken[];
+			readonly boundary: CompactBoundaryKind;
+	  }
+	| { readonly kind: "extensions"; readonly boundary: CompactBoundaryKind };
+
+export type CompiledCompactChunk = ReadonlyCompactChunk & {
+	readonly references: readonly string[];
+};
+
+export type CompiledFooterFormat = {
+	readonly tokens: readonly ReadonlyFormatToken[];
+	readonly references: readonly string[];
+	readonly compact: {
+		readonly left: readonly CompiledCompactChunk[];
+		readonly right: readonly CompiledCompactChunk[];
+		readonly alignRight: boolean;
+	};
+};
+
+type SyntaxEntry = {
+	tokens: readonly ReadonlyFormatToken[];
+	compact: {
+		left: readonly ReadonlyCompactChunk[];
+		right: readonly ReadonlyCompactChunk[];
+		alignRight: boolean;
+	};
+	names: readonly string[];
+	canonicalNames?: readonly string[];
+	compiled?: CompiledFooterFormat;
+};
+
+// Format text only: no session, config object, rendered output, or theme is retained.
+const syntaxCache = new Map<string, SyntaxEntry>();
+const SYNTAX_CACHE_LIMIT = 32;
+
+function freezeTokens(tokens: FormatToken[]): readonly ReadonlyFormatToken[] {
+	for (const token of tokens) {
+		if (token.kind === "group") freezeTokens(token.tokens);
+		Object.freeze(token);
+	}
+	return Object.freeze(tokens);
+}
+
+/** Share bounded syntax/analysis across rendering and dependency-demand checks. */
+export function compiledFooterFormat(
+	format: string,
+	aliases: Readonly<Record<string, string>> = {},
+): CompiledFooterFormat {
+	let entry = syntaxCache.get(format);
+	if (!entry) {
+		const tokens = parseFooterFormat(format);
+		const compact = compileCompactFormatSplit(tokens);
+		const names = new Set<string>();
+		const visit = (items: FormatToken[]) => {
+			for (const token of items) {
+				if (token.kind === "group") visit(token.tokens);
+				else if (token.kind === "var") names.add(token.name);
+			}
+		};
+		visit(tokens);
+		const freezeChunks = (chunks: CompactFormatChunk[]) =>
+			Object.freeze(
+				chunks.map((chunk) => {
+					if (chunk.kind === "tokens") freezeTokens(chunk.tokens);
+					return Object.freeze(chunk);
+				}),
+			);
+		entry = {
+			tokens: freezeTokens(tokens),
+			compact: Object.freeze({
+				left: freezeChunks(compact.left),
+				right: freezeChunks(compact.right),
+				alignRight: compact.alignRight,
+			}),
+			names: Object.freeze([...names]),
+		};
+		if (syntaxCache.size >= SYNTAX_CACHE_LIMIT) {
+			const oldest = syntaxCache.keys().next().value;
+			if (oldest !== undefined) syntaxCache.delete(oldest);
+		}
+	} else {
+		syntaxCache.delete(format);
+	}
+	syntaxCache.set(format, entry);
+	// Compare only names that occur in this syntax, including structural variables.
+	// This observes in-place alias edits without retaining mutable caller objects.
+	if (
+		entry.compiled &&
+		entry.names.every((name, i) => (aliases[name] ?? name) === entry.canonicalNames?.[i])
+	) {
+		return entry.compiled;
+	}
+	const references = (tokens: readonly ReadonlyFormatToken[]) =>
+		Object.freeze([...collectFooterFormatReferences(tokens, aliases)]);
+	const analyzeChunks = (chunks: readonly ReadonlyCompactChunk[]) =>
+		Object.freeze(
+			chunks.map((chunk) =>
+				Object.freeze({
+					...chunk,
+					references:
+						chunk.kind === "tokens" ? references(chunk.tokens) : Object.freeze([] as string[]),
+				}),
+			),
+		);
+	entry.canonicalNames = Object.freeze(entry.names.map((name) => aliases[name] ?? name));
+	entry.compiled = Object.freeze({
+		tokens: entry.tokens,
+		references: references(entry.tokens),
+		compact: Object.freeze({
+			left: analyzeChunks(entry.compact.left),
+			right: analyzeChunks(entry.compact.right),
+			alignRight: entry.compact.alignRight,
+		}),
+	});
+	return entry.compiled;
+}
+
 const TOKEN_REGEX = /\$\{([a-zA-Z_][a-zA-Z0-9_]*)\}|\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
 
 /**
@@ -118,7 +243,7 @@ function parseTokenSlice(
  * spaces are inserted — the user controls all spacing.
  */
 export function renderFormatSplit(
-	tokens: FormatToken[],
+	tokens: readonly ReadonlyFormatToken[],
 	renderVariable: (name: string) => string,
 ): { left: string; middle: string; right: string } {
 	const fillIndices = findTopLevelFillIndices(tokens);
@@ -224,18 +349,18 @@ function trimBoundaryWhitespace(tokens: FormatToken[]): FormatToken[] {
 }
 
 export function renderFormatTokens(
-	tokens: FormatToken[],
+	tokens: readonly ReadonlyFormatToken[],
 	renderVariable: (name: string) => string,
 ): string {
 	return renderTokenSlice(tokens, 0, tokens.length, renderVariable);
 }
 
 export function collectFooterFormatReferences(
-	tokens: FormatToken[],
+	tokens: readonly ReadonlyFormatToken[],
 	aliases: Record<string, string> = {},
 ): Set<string> {
 	const references = new Set<string>();
-	const visit = (items: FormatToken[]) => {
+	const visit = (items: readonly ReadonlyFormatToken[]) => {
 		for (const token of items) {
 			if (token.kind === "group") {
 				visit(token.tokens);
@@ -252,7 +377,7 @@ export function collectFooterFormatReferences(
 	return references;
 }
 
-function findTopLevelFillIndices(tokens: FormatToken[]): number[] {
+function findTopLevelFillIndices(tokens: readonly ReadonlyFormatToken[]): number[] {
 	const fillIndices: number[] = [];
 	for (let index = 0; index < tokens.length; index++) {
 		if (tokens[index]?.kind === "fill") fillIndices.push(index);
@@ -261,7 +386,7 @@ function findTopLevelFillIndices(tokens: FormatToken[]): number[] {
 }
 
 function renderTokenSlice(
-	tokens: FormatToken[],
+	tokens: readonly ReadonlyFormatToken[],
 	start: number,
 	end: number,
 	renderVariable: (name: string) => string,
@@ -275,7 +400,7 @@ function renderTokenSlice(
 	return result;
 }
 
-function renderToken(token: FormatToken, renderVariable: (name: string) => string): string {
+function renderToken(token: ReadonlyFormatToken, renderVariable: (name: string) => string): string {
 	if (token.kind === "text") return token.value;
 	if (token.kind === "var") return renderVariable(token.name);
 	if (token.kind === "fill") return "";
@@ -298,7 +423,7 @@ const NON_CONTENT_VARS = new Set(["sep", "separator"]);
  * ignored for emptiness so orphan themed pipes do not force a group to render.
  */
 function isGroupEmpty(
-	group: FormatToken & { kind: "group" },
+	group: ReadonlyFormatToken & { kind: "group" },
 	renderVariable: (name: string) => string,
 ): boolean {
 	let sawContentVarOrGroup = false;
@@ -317,7 +442,7 @@ function isGroupEmpty(
 	return sawContentVarOrGroup || groupOnlyNonContentVars(group);
 }
 
-function groupOnlyNonContentVars(group: FormatToken & { kind: "group" }): boolean {
+function groupOnlyNonContentVars(group: ReadonlyFormatToken & { kind: "group" }): boolean {
 	let sawSep = false;
 	for (const child of group.tokens) {
 		if (child.kind === "text") {

package/extensions/zentui/footer.ts

@@ -14,10 +14,8 @@ import {
 	sanitizeExtensionStatusText,
 } from "./extension-status";
 import {
-	type CompactFormatChunk,
-	collectFooterFormatReferences,
-	compileCompactFormatSplit,
-	parseFooterFormat,
+	type CompiledCompactChunk,
+	compiledFooterFormat,
 	renderFormatSplit,
 	renderFormatTokens,
 	stripOrphanSeparators,
@@ -34,6 +32,7 @@ import { truncateFooterText } from "./footer-text";
 import {
 	buildContextDisplayLabel,
 	buildSessionDurationLabel,
+	type ContextUsageSnapshot,
 	contextColorTier,
 	formatCwdLabel,
 	formatGitBranchText,
@@ -219,7 +218,11 @@ export function installFooter(
 				hooks.onDispose?.();
 			},
 			invalidate() {},
-			render: function renderFooter(width: number, showQuota = true): string[] {
+			render: function renderFooter(
+				width: number,
+				showQuota = true,
+				contextSnapshot?: ContextUsageSnapshot,
+			): string[] {
 				if (width <= 0) return [""];
 				const config = getConfig();
 				const footer = config.components.footer;
@@ -230,20 +233,18 @@ export function installFooter(
 				let quotaLabel = styledQuota;
 				let quotaProbe = "";
 				const footerModelLabel = modelLabelFor(state, footer.modelLabel);
-				const wideFormatTokens = config.components.footer.styles.starship.format
-					? parseFooterFormat(config.components.footer.styles.starship.format)
-					: [];
-				const compactFormatTokens = config.components.footer.styles.starship.responsive
-					? parseFooterFormat(config.components.footer.styles.starship.compactFormat)
-					: [];
-				const wideReferences = collectFooterFormatReferences(
-					wideFormatTokens,
+				const wideFormat = compiledFooterFormat(
+					footer.styles.starship.format,
 					FOOTER_FORMAT_ALIASES,
 				);
-				const compactReferences = collectFooterFormatReferences(
-					compactFormatTokens,
+				const compactFormat = compiledFooterFormat(
+					footer.styles.starship.responsive ? footer.styles.starship.compactFormat : "",
 					FOOTER_FORMAT_ALIASES,
 				);
+				const wideFormatTokens = wideFormat.tokens;
+				const compactFormatTokens = compactFormat.tokens;
+				const wideReferences = wideFormat.references;
+				const compactReferences = compactFormat.references;
 				const colorSource = config.components.footer.colorSource;
 				const iconMode = config.icons.effectiveMode;
 				const pathDisplay = config.components.footer.styles.starship.pathDisplay;
@@ -293,9 +294,9 @@ export function installFooter(
 				);
 				const needsSessionName =
 					(config.components.footer.styles.starship.format
-						? wideReferences.has("session_name")
+						? wideReferences.includes("session_name")
 						: config.components.footer.styles.starship.segments.sessionName) ||
-					compactReferences.has("session_name");
+					compactReferences.includes("session_name");
 				const sessionName = needsSessionName
 					? sanitizeExtensionStatusText(ctx.sessionManager.getSessionName() ?? "")
 					: "";
@@ -314,10 +315,21 @@ export function installFooter(
 							config.components.footer.styles.starship.gitBranch.maxLength,
 						)
 					: undefined;
-				const { percent: contextPercent, contextWindow } = resolveContextUsage(
-					ctx,
-					hooks.getLiveContext?.(),
-				);
+				const needsContext =
+					(config.components.footer.styles.starship.format
+						? wideReferences.includes("context")
+						: config.components.footer.styles.starship.segments.context) ||
+					compactReferences.includes("context") ||
+					(state.autoCompaction &&
+						(wideReferences.includes("auto_compaction") ||
+							compactReferences.includes("auto_compaction")));
+				// Reuse only within this render's quota fallback, including resolved unknown usage.
+				const context =
+					contextSnapshot ??
+					(needsContext
+						? resolveContextUsage(ctx, hooks.getLiveContext?.())
+						: { percent: undefined, contextWindow: undefined });
+				const { percent: contextPercent, contextWindow } = context;
 				const contextLabel = buildContextDisplayLabel({
 					percent: contextPercent,
 					contextWindow,
@@ -794,7 +806,7 @@ export function installFooter(
 						(value) => !otherText.includes(value),
 					);
 					// Bounded fail-open fallback if every candidate collides with non-quota text.
-					if (!letter) return renderFooter(width, false);
+					if (!letter) return renderFooter(width, false, context);
 					quotaProbe = codexQuotaText(quota).replace(/[a-z0-9]/gi, letter);
 					quotaLabel = styledQuota.replace(codexQuotaText(quota), quotaProbe);
 				}
@@ -841,7 +853,7 @@ export function installFooter(
 								0,
 							);
 						// Recompose without quota if any occurrence was clipped, split, or omitted.
-						if (count(source) !== count(framedRows)) return renderFooter(width, false);
+						if (count(source) !== count(framedRows)) return renderFooter(width, false, context);
 						return framedRows.map((row) => row.replaceAll(quotaProbe, codexQuotaText(quota)));
 					}
 					return framedRows;
@@ -907,7 +919,9 @@ export function installFooter(
 							return renderVariable(name);
 					}
 				};
-				const renderCompactChunks = (chunks: CompactFormatChunk[]): CompactLayoutChunk[] => {
+				const renderCompactChunks = (
+					chunks: readonly CompiledCompactChunk[],
+				): CompactLayoutChunk[] => {
 					const compactChunks: CompactLayoutChunk[] = [];
 					for (const chunk of chunks) {
 						if (chunk.kind === "extensions") {
@@ -927,10 +941,10 @@ export function installFooter(
 						let rendered = stripOrphanSeparators(
 							renderFormatTokens(chunk.tokens, renderCompactVariable),
 						);
-						const references = collectFooterFormatReferences(chunk.tokens, FOOTER_FORMAT_ALIASES);
+						const references = chunk.references;
 						if (
-							(!quotaLabel || !references.has("codex_quota")) &&
-							["cwd", "session_name", "git_branch"].some((name) => references.has(name))
+							(!quotaLabel || !references.includes("codex_quota")) &&
+							["cwd", "session_name", "git_branch"].some((name) => references.includes(name))
 						) {
 							rendered = truncateFooterText(rendered, chunkBudget, "…");
 						}
@@ -938,7 +952,7 @@ export function installFooter(
 					}
 					return compactChunks;
 				};
-				const compact = compileCompactFormatSplit(compactFormatTokens);
+				const compact = compactFormat.compact;
 				const compactLeft = renderCompactChunks(compact.left);
 				const compactRight = renderCompactChunks(compact.right);
 				return frameRows(

package/extensions/zentui/format.ts

@@ -295,6 +295,74 @@ export function getUsageTotals(ctx: ExtensionContext): UsageTotals {
 	return totals;
 }
 
+const EMPTY_USAGE_TOTALS: UsageTotals = Object.freeze({
+	input: 0,
+	output: 0,
+	cacheRead: 0,
+	cacheWrite: 0,
+	cost: 0,
+});
+
+/**
+ * Production-only snapshot for Pi's append-only session contract. The owner must invalidate
+ * at message/agent completion, settlement, tree/compaction and session boundaries. Leaf IDs
+ * supplement those events; they are NOT a full-history revision. Silent same-leaf in-place
+ * edits outside those boundaries require the generic mutation-safe getUsageTotals instead.
+ */
+export class EventUsageTotalsController {
+	private snapshot?: {
+		manager: ExtensionContext["sessionManager"];
+		sessionId: string;
+		leafId: string | null;
+		totals: UsageTotals;
+	};
+
+	invalidate(): void {
+		this.snapshot = undefined;
+	}
+
+	resolve(ctx: ExtensionContext, demanded: boolean): UsageTotals {
+		if (!demanded) {
+			this.invalidate();
+			return EMPTY_USAGE_TOTALS;
+		}
+		const manager = ctx.sessionManager;
+		let identity: { sessionId: string; leafId: string | null } | undefined;
+		try {
+			if (
+				typeof manager.getEntries === "function" &&
+				typeof manager.getSessionId === "function" &&
+				typeof manager.getLeafId === "function"
+			) {
+				const sessionId = manager.getSessionId();
+				const leafId = manager.getLeafId();
+				if (
+					typeof sessionId === "string" &&
+					sessionId.length > 0 &&
+					(leafId === null || (typeof leafId === "string" && leafId.length > 0))
+				)
+					identity = { sessionId, leafId };
+			}
+		} catch {
+			// Older or unsupported hosts retain the generic mutation-safe path.
+		}
+		if (!identity) {
+			this.invalidate();
+			return getUsageTotals(ctx);
+		}
+		if (
+			this.snapshot?.manager === manager &&
+			this.snapshot.sessionId === identity.sessionId &&
+			this.snapshot.leafId === identity.leafId
+		)
+			return this.snapshot.totals;
+		this.invalidate();
+		const totals = computeUsageTotals(manager.getEntries() as readonly SessionEntry[]);
+		this.snapshot = { manager, ...identity, totals };
+		return totals;
+	}
+}
+
 export function buildCacheReadLabel(cacheRead: number): string {
 	return cacheRead > 0 ? `R${formatCount(cacheRead)}` : "";
 }
@@ -397,12 +465,22 @@ export function resolveContextUsage(
 	ctx: Pick<ExtensionContext, "model" | "getContextUsage">,
 	live?: { tokens: number },
 ): ContextUsageSnapshot {
+	const liveTokens =
+		live && Number.isFinite(live.tokens) && live.tokens >= 0 ? live.tokens : undefined;
+	const modelWindow = ctx.model?.contextWindow;
+	// Live provider usage is authoritative; avoid rebuilding the host session projection.
+	if (liveTokens !== undefined && modelWindow && Number.isFinite(modelWindow) && modelWindow > 0) {
+		return { percent: (liveTokens / modelWindow) * 100, contextWindow: modelWindow };
+	}
 	const usage = ctx.getContextUsage();
-	const contextWindow = ctx.model?.contextWindow ?? usage?.contextWindow;
+	const contextWindow = modelWindow ?? usage?.contextWindow;
 	return {
 		percent:
-			live && contextWindow && contextWindow > 0
-				? (live.tokens / contextWindow) * 100
+			liveTokens !== undefined &&
+			contextWindow &&
+			Number.isFinite(contextWindow) &&
+			contextWindow > 0
+				? (liveTokens / contextWindow) * 100
 				: (usage?.percent ?? undefined),
 		contextWindow,
 	};