pi-zentui 0.26.0 → 0.26.1

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.

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,
 	};

package/extensions/zentui/git.ts

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import { promisify } from "node:util";
 
 const execFileAsync = promisify(execFile);
@@ -229,33 +229,44 @@ export function detectGitState(paths: GitStatePaths): {
 	return {};
 }
 
-async function resolveGitPath(cwd: string, pathSpec: string): Promise<string | undefined> {
-	try {
-		const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", pathSpec], {
-			cwd,
-			timeout: GIT_COMMAND_TIMEOUT_MS,
-		});
-		const resolved = (typeof stdout === "string" ? stdout : String(stdout)).trim();
-		if (!resolved) return undefined;
-		return resolved.startsWith("/") ? resolved : join(cwd, resolved);
-	} catch {
-		return undefined;
-	}
-}
+const GIT_OPERATION_PATHS = [
+	"rebase-merge",
+	"rebase-apply",
+	"MERGE_HEAD",
+	"CHERRY_PICK_HEAD",
+	"REVERT_HEAD",
+	"BISECT_LOG",
+] as const;
 
 async function readGitOperationState(cwd: string): Promise<{
 	gitState?: GitOperationState;
 	gitStateLabel?: string;
 }> {
-	const [rebaseMerge, rebaseApply, mergeHead, cherryPickHead, revertHead, bisectLog] =
-		await Promise.all([
-			resolveGitPath(cwd, "rebase-merge"),
-			resolveGitPath(cwd, "rebase-apply"),
-			resolveGitPath(cwd, "MERGE_HEAD"),
-			resolveGitPath(cwd, "CHERRY_PICK_HEAD"),
-			resolveGitPath(cwd, "REVERT_HEAD"),
-			resolveGitPath(cwd, "BISECT_LOG"),
-		]);
+	let paths: string[];
+	try {
+		const { stdout } = await execFileAsync(
+			"git",
+			[
+				"rev-parse",
+				"--path-format=absolute",
+				...GIT_OPERATION_PATHS.flatMap((path) => ["--git-path", path]),
+			],
+			{ cwd, timeout: GIT_COMMAND_TIMEOUT_MS },
+		);
+		// rev-parse is line-delimited, not NUL-delimited. Reject ambiguous paths
+		// (including embedded newlines) rather than assigning another operation's path.
+		paths = String(stdout)
+			.replace(/\r?\n$/, "")
+			.split(/\r?\n/);
+		if (
+			paths.length !== GIT_OPERATION_PATHS.length ||
+			paths.some((path) => !isAbsolute(path) || /[\r\n\0]/.test(path))
+		)
+			return {};
+	} catch {
+		return {};
+	}
+	const [rebaseMerge, rebaseApply, mergeHead, cherryPickHead, revertHead, bisectLog] = paths;
 
 	const existing = (path: string | undefined) => (path && existsSync(path) ? path : undefined);
 	const rebaseDir = existing(rebaseMerge) ?? existing(rebaseApply);
@@ -282,10 +293,14 @@ function isNotARepoError(error: unknown): boolean {
 
 /**
  * Options for the optional probes that piggyback on the existing git refresh.
- * Both default to `false` so no extra git process is spawned unless a segment
- * is enabled and needs the data.
+ * Tag/metrics default to false; stash/operation state retain the full-status
+ * default for standalone callers. UI consumers may omit probes they do not display.
  */
 export type ReadGitStatusOptions = {
+	/** Read stash counts (default true). */
+	readStash?: boolean;
+	/** Resolve and inspect operation paths (default true). */
+	readOperationState?: boolean;
 	/** Run `git describe --tags --exact-match HEAD` for the git_commit segment. */
 	readExactTag?: boolean;
 	/**
@@ -311,10 +326,12 @@ export async function readGitStatus(
 				cwd,
 				timeout: GIT_COMMAND_TIMEOUT_MS,
 			}),
-			execFileAsync("git", ["stash", "list"], {
-				cwd,
-				timeout: GIT_COMMAND_TIMEOUT_MS,
-			}).catch(() => ({ stdout: "" })),
+			options.readStash !== false
+				? execFileAsync("git", ["stash", "list"], {
+						cwd,
+						timeout: GIT_COMMAND_TIMEOUT_MS,
+					}).catch(() => ({ stdout: "" }))
+				: Promise.resolve({ stdout: "" }),
 			readExactTag
 				? execFileAsync("git", ["describe", "--tags", "--exact-match", "HEAD"], {
 						cwd,
@@ -356,7 +373,7 @@ export async function readGitStatus(
 				status.metrics = parseGitNumstat(metricsStdout);
 			}
 		}
-		const operation = await readGitOperationState(cwd);
+		const operation = options.readOperationState !== false ? await readGitOperationState(cwd) : {};
 		return {
 			kind: "ok",
 			status: {