gentle-pi 3.3.0 → 3.4.0

package/extensions/gentle-shell.ts

@@ -5,7 +5,7 @@ import { statSync } from "node:fs";
 import { profilesFilePath, readProfilesFileResult } from "../lib/agent-profiles.ts";
 import * as os from "node:os";
 import { join } from "node:path";
-import { buildShellHeaderModel, renderShellBar, renderShellHeaderBar, renderShellSidebarBar, shellEnabled, type ShellBarModel, type ShellBarTheme } from "../lib/shell-bar.ts";
+import { buildShellHeaderModel, renderShellBar, renderShellHeaderBar, renderShellHeaderRule, renderShellSidebarBar, shellEnabled, type ShellBarModel, type ShellBarTheme } from "../lib/shell-bar.ts";
 import { CHANGE_STATUS, RootBranchLabels, renderChangesWidget, type ChangedFile, type ChangesModel, type GitRunner, type WorktreeChanges } from "../lib/shell-changes.ts";
 import { WorktreeChangesView } from "../lib/shell-changes-view.ts";
 import { SessionWorktreeRegistry, resolveSessionWorktree, worktreeGitEnvironment, type WorktreeResolver } from "../lib/session-worktree-registry.ts";
@@ -16,6 +16,7 @@ import { agentsViewKey } from "../lib/agents-keys.ts";
 import { GentleAiDevBinaryOverrideError, resolveGentleAiDevBinaryOverride } from "../lib/gentle-ai-binary.ts";
 import { DOUBLE_ESC_CANCEL_HINT, framePromptLines, IDLE_ESC_CLEAR_HINT, PROMPT_HINT, PROMPT_STATE, SHELL_PULSE_MS, withPromptHint, type PromptState } from "../lib/shell-prompt.ts";
 import { gentlePiConfigHome } from "../lib/agent-home.ts";
+import { resolveAnimationPolicy, writeAnimationPolicy, type AnimationPolicy } from "../lib/animation-policy.ts";
 import {
 	DOUBLE_ESC_CANCEL_WINDOW_MS,
 	resolveDoubleEscCancelPolicy,
@@ -23,7 +24,7 @@ import {
 	type DoubleEscCancelPolicy,
 	type DoubleEscCancelResolution,
 } from "../lib/double-esc-cancel-policy.ts";
-import { accountIdFromToken, CODEX_PROVIDER, CODEX_USAGE_URL, NAN_PROVIDER, NAN_QUOTA_URL, parseCodexUsage, parseNanQuota, parseUsageHeaders, UsageStore, type ProviderUsage } from "../lib/shell-usage.ts";
+import { accountIdFromToken, CODEX_PROVIDER, CODEX_USAGE_URL, NAN_PROVIDER, NAN_QUOTA_URL, parseCodexUsage, parseNanQuota, parseProviderUsage, parseUsageHeaders, parseUsageSource, UsageSourceRegistry, UsageStore, USAGE_SOURCE_EVENT, type ProviderUsage, type UsageSource } from "../lib/shell-usage.ts";
 import { UsageView } from "../lib/shell-usage-view.ts";
 import { sidebarHeader, sidebarPart } from "../lib/shell-sidebar.ts";
 import { installSidebar, invalidateSidebar } from "../lib/shell-sidebar-layout.ts";
@@ -229,6 +230,7 @@ export function extractQueuedText(combined: string, draft: string): string | und
 export class GentlePromptEditor extends CustomEditor {
 	private promptState: PromptState = PROMPT_STATE.IDLE;
 	private tick = 0;
+	private animationPolicy: AnimationPolicy = "quality";
 	private pulse: NodeJS.Timeout | undefined;
 	private readonly deps: PromptEditorDeps;
 	// CustomEditor keeps its own `keybindings` private, so this class holds
@@ -248,6 +250,23 @@ export class GentlePromptEditor extends CustomEditor {
 		this.keybindingsManager = keybindings;
 	}
 
+	setAnimationPolicy(policy: AnimationPolicy): void {
+		if (this.animationPolicy === policy) return;
+		this.animationPolicy = policy;
+		this.stopPulse();
+		if (this.promptState === PROMPT_STATE.WORKING) this.startPulse();
+		this.deps.requestRender();
+	}
+
+	private startPulse(): void {
+		if (this.animationPolicy === "potato") return;
+		this.pulse = setInterval(() => {
+			this.tick += 1;
+			this.deps.requestRender();
+		}, this.animationPolicy === "performance" ? 1000 : SHELL_PULSE_MS);
+		this.pulse.unref();
+	}
+
 	setWorking(working: boolean): void {
 		this.promptState = working ? PROMPT_STATE.WORKING : PROMPT_STATE.IDLE;
 		this.stopPulse();
@@ -256,11 +275,7 @@ export class GentlePromptEditor extends CustomEditor {
 		} else {
 			this.pendingIdleClearDeadline = undefined;
 			this.pendingIdleClearText = undefined;
-			this.pulse = setInterval(() => {
-				this.tick += 1;
-				this.deps.requestRender();
-			}, SHELL_PULSE_MS);
-			this.pulse.unref();
+			this.startPulse();
 		}
 		this.deps.requestRender();
 	}
@@ -743,28 +758,67 @@ export async function fetchNanUsage(apiKey: string | undefined, fetchFn: typeof
 	}
 }
 
+// A registered source is foreign code running inside a fire-and-forget
+// refresh: it must degrade exactly like the built-in fetchers above, never
+// throw past this call, and never leave an unhandled rejection behind.
+async function fetchFromSource(source: UsageSource, apiKey: string | undefined, fetchFn: typeof fetch, now: number): Promise<ProviderUsage | undefined> {
+	try {
+		const result = await source.fetch(apiKey, fetchFn, now);
+		return result === undefined ? undefined : parseProviderUsage(result, source.provider);
+	} catch {
+		return undefined;
+	}
+}
+
 export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = process.env, overrides: Partial<ShellDeps> = {}): void {
 	installSessionChangeCapture(pi, env, overrides.resolveWorktree ?? resolveSessionWorktree);
 	if (!shellEnabled(env)) return;
 	const deps: ShellDeps = { ...defaultShellDeps, activeProfile: createActiveProfileReader(env), ...overrides };
 	const usage = new UsageStore();
+	// Providers gentle-shell has never heard of get a usage source too, when
+	// the extension that owns them registers one on pi.events; see the
+	// USAGE_SOURCE_EVENT subscription below.
+	const usageSources = new UsageSourceRegistry();
 	let renderHost: ShellRenderHost | undefined;
 	// The 5-minute rule is per provider: one provider's fetch cannot leave the
 	// next one waiting for an interval it never used.
 	const usageFetchedAt = new Map<string, number>();
 	const refreshUsage = async (ctx: ExtensionContext, force: boolean) => {
 		const provider = ctx.model?.provider;
-		if (provider !== CODEX_PROVIDER && provider !== NAN_PROVIDER) return;
+		if (!provider) return;
+		const source = usageSources.get(provider);
+		if (!source && provider !== CODEX_PROVIDER && provider !== NAN_PROVIDER) return;
 		const now = deps.now();
 		if (!force && now - (usageFetchedAt.get(provider) ?? 0) < USAGE_REFRESH_MS) return;
 		usageFetchedAt.set(provider, now);
 		const apiKey = await ctx.modelRegistry.getApiKeyForProvider(provider).catch(() => undefined);
-		const fetched = provider === NAN_PROVIDER ? await fetchNanUsage(apiKey, deps.fetch, deps.now()) : await fetchCodexUsage(apiKey, deps.fetch, deps.now());
+		const fetched = source
+			? await fetchFromSource(source, apiKey, deps.fetch, deps.now())
+			: provider === NAN_PROVIDER
+				? await fetchNanUsage(apiKey, deps.fetch, deps.now())
+				: await fetchCodexUsage(apiKey, deps.fetch, deps.now());
 		if (!fetched) return;
+		// A registered source can be replaced while its own fetch is still in
+		// flight; the identity captured above is this call's source, so a stale
+		// answer that outlives its replacement is discarded instead of
+		// overwriting whatever the replacement already recorded.
+		if (source && usageSources.get(provider) !== source) return;
 		usage.record(fetched);
 		renderHost?.invalidateSidebar?.();
 		renderHost?.requestRender();
 	};
+	// Subscribed once, for the life of the extension: a registration can
+	// arrive before the first session_start (the owning extension's factory
+	// runs first) or after it (its own session_start fires later, or it
+	// registers lazily). Either order is fine: a registration for the
+	// currently active provider forces exactly one refresh, so the panel
+	// never waits for the 5-minute window or the next turn to notice it.
+	pi.events.on(USAGE_SOURCE_EVENT, (payload) => {
+		const source = parseUsageSource(payload);
+		if (!source) return;
+		usageSources.register(source);
+		if (currentContext?.model?.provider === source.provider) void refreshUsage(currentContext, true);
+	});
 	pi.on("after_provider_response", (event) => {
 		const parsed = parseUsageHeaders(event.headers, deps.now());
 		if (!parsed) return;
@@ -785,6 +839,7 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 					theme,
 					now: () => deps.now(),
 					active: () => (ctx.model ? { provider: ctx.model.provider } : undefined),
+					registry: () => usageSources,
 					onRefresh: () => refreshUsage(ctx, true),
 					onClose: () => done(null),
 					requestRender: () => tui.requestRender(),
@@ -818,6 +873,8 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 	// direction, and the Esc gate always describe the same effective policy
 	// even when another session or a hand edit changed the file mid-session.
 	const doubleEscCancelConfigHome = gentlePiConfigHome(env);
+	const animationOptions = { gentlePiConfigHome: doubleEscCancelConfigHome };
+	let animationPolicy = resolveAnimationPolicy(animationOptions).policy;
 	let doubleEscCancelPolicy: DoubleEscCancelPolicy = resolveDoubleEscCancelPolicy({
 		env,
 		gentlePiConfigHome: doubleEscCancelConfigHome,
@@ -889,10 +946,11 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 			const headerBar = (width: number) => renderShellHeaderBar(buildShellHeaderModel(footerModel()), theme, width, usageShortcutKey);
 			const disposeHeader = sidebarHeader(tui, {
 				digest: () => JSON.stringify(buildShellHeaderModel(footerModel())),
-				render: (width) => [headerBar(width).text],
+				render: (width) => [headerBar(width).text, renderShellHeaderRule(theme, width)],
 				invalidate() {},
 				handleMouse(event) {
 					if (event.type !== "click" || event.button !== "left") return undefined;
+					if (event.y !== 0) return undefined; // the rule row under the status line is decorative, never clickable
 					const { usageSpan } = headerBar(event.width);
 					if (!usageSpan || event.x < usageSpan.start || event.x >= usageSpan.end) return undefined;
 					void openUsage(ctx);
@@ -908,6 +966,7 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 			(created) => {
 				prompt?.dispose();
 				prompt = created;
+				prompt.setAnimationPolicy(animationPolicy);
 			},
 			{ now: () => deps.now(), doubleEscCancelEnabled: () => doubleEscCancelPolicy === "on", dispatchQueuedText: (text) => { pendingQueuedText = pendingQueuedText === undefined ? text : `${pendingQueuedText}\n\n${text}`; } },
 		);
@@ -971,6 +1030,36 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 			handler: async (ctx) => showCommandPalette(pi, ctx, env),
 		});
 	}
+	pi.registerCommand("gentle:animations", {
+		description: "Show or set global animations; no argument opens a selectable menu (quality|performance|potato, plus status).",
+		// No argument opens a selectable menu when an interactive UI is present;
+		// headless callers and fakes without ui.select keep the status fallback.
+		handler: async (args, ctx) => {
+			let action = args.trim() || "status";
+			if (args.trim().length === 0 && ctx.hasUI && typeof ctx.ui.select === "function") {
+				const selected = await ctx.ui.select(
+					`Gentle animations (current: ${animationPolicy})`,
+					["quality", "performance", "potato", "status"],
+				);
+				if (selected === undefined) return;
+				action = selected;
+			}
+			if (action !== "status" && action !== "quality" && action !== "performance" && action !== "potato") {
+				ctx.ui.notify("Use /gentle:animations status|quality|performance|potato.", "warning");
+				return;
+			}
+			try {
+				if (action !== "status") writeAnimationPolicy(action, animationOptions);
+				const result = resolveAnimationPolicy(animationOptions);
+				animationPolicy = result.policy;
+				prompt?.setAnimationPolicy(animationPolicy);
+				const source = result.source === "default" ? "built-in default" : `global file ${result.globalFile}`;
+				ctx.ui.notify(`animations: ${result.policy} (decided by ${source})${result.malformed ? "; malformed or unreadable file, falling back to quality" : ""}. Prompt applies now; startup banner applies at next creation.`, result.malformed ? "warning" : "info");
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
 	// User-owned, like gentle:background-subagents and gentle:review-mode: the
 	// only writer is this handler, reached only by explicit invocation. Unlike
 	// those two, no argument toggles the effective policy instead of merely

package/extensions/quiet-tools.ts

@@ -535,18 +535,39 @@ interface BoundedRowSection {
 	tail?: boolean;
 }
 
+// Cache the rendered preview slice per stable tool-result object: pi re-renders
+// every visible card each frame, so re-tokenizing the full output text per pass is
+// pure waste. Only the returned preview slice is retained, never the full wrapped
+// text, so an arbitrarily large output cannot pin every wrapped line for the
+// result object's lifetime.
+const boundedRowsLineCache = new WeakMap<object, Array<{ text: string; width: number; rows: number; tail: boolean; lines: string[] } | undefined>>();
+
 class BoundedRows implements Component {
 	private readonly sections: readonly BoundedRowSection[];
+	private readonly cacheKey: object | undefined;
 
-	constructor(sections: readonly BoundedRowSection[]) {
+	constructor(sections: readonly BoundedRowSection[], cacheKey?: object) {
 		this.sections = sections;
+		this.cacheKey = cacheKey;
 	}
 
+	/** Renders each section through the wrapped-line cache, sliced to the section row budget; cache hits skip re-tokenizing and re-wrapping the section text. */
 	render(width: number): string[] {
-		return this.sections.flatMap(({ text, rows, tail = false }) => {
+		const cache = this.cacheKey ? boundedRowsLineCache.get(this.cacheKey) : undefined;
+		return this.sections.flatMap(({ text, rows, tail = false }, index) => {
 			if (rows <= 0) return [];
+			const hit = cache?.[index];
+			if (hit && hit.text === text && hit.width === width && hit.rows === rows && hit.tail === tail) {
+				return [...hit.lines];
+			}
 			const rendered = new Text(text, 0, 0).render(width);
-			return tail ? rendered.slice(-rows) : rendered.slice(0, rows);
+			const sliced = tail ? rendered.slice(-rows) : rendered.slice(0, rows);
+			if (this.cacheKey) {
+				const slot = boundedRowsLineCache.get(this.cacheKey) ?? [];
+				slot[index] = { text, width, rows, tail, lines: sliced };
+				boundedRowsLineCache.set(this.cacheKey, slot);
+			}
+			return [...sliced];
 		});
 	}
 
@@ -641,8 +662,10 @@ function registerQuietTool(pi: ExtensionAPI, toolName: QuietToolName, commandArg
 			}
 			return new Text(formatToolCall(toolName, callArgs, theme), 0, 0);
 		},
+		/** Builds the card component for this render pass; collapsed cards delegate to the wrapped-line cache keyed by the tool result object. */
 		renderResult(result, options, theme, context) {
 			const renderContext = context as ToolRenderContextLike | undefined;
+			const cacheKey = typeof result === "object" && result !== null ? result : undefined;
 			const safeResult = sanitizedResult(result);
 			const text = safeText(extractTextContent(safeResult));
 			const isError = renderContext?.isError ?? options.isError ?? false;
@@ -661,7 +684,7 @@ function registerQuietTool(pi: ExtensionAPI, toolName: QuietToolName, commandArg
 				return new BoundedRows([
 					{ text: theme.fg("warning", partialLabel(toolName, text)), rows: 1 },
 					...(visible ? [{ text: theme.fg("muted", visible), rows: PREVIEW_LINE_LIMIT, tail: true }] : []),
-				]);
+				], cacheKey);
 			}
 			if (options.expanded && toolName === "read" && hasImageContent(safeResult) && officialRenderResult) {
 				return officialRenderResult(
@@ -686,7 +709,7 @@ function registerQuietTool(pi: ExtensionAPI, toolName: QuietToolName, commandArg
 				return new BoundedRows([
 					{ text: theme.fg(color, output.replace(/^\n/, "")), rows: PREVIEW_LINE_LIMIT, tail },
 					...(hint ? [{ text: theme.fg(color, hint.slice(1)), rows: 1 }] : []),
-				]);
+				], cacheKey);
 			}
 			return new Text(hint ? theme.fg(color, hint.slice(1)) : "", 0, 0);
 		},

package/extensions/startup-banner.ts

@@ -5,6 +5,7 @@ import * as os from "node:os";
 import { execFile } from "node:child_process";
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { resolveAnimationPolicy } from "../lib/animation-policy.ts";
 
 const PI_AGENT_DIR = join(os.homedir(), ".pi", "agent");
 const PI_NPM_DIR = join(PI_AGENT_DIR, "npm", "node_modules");
@@ -691,6 +692,7 @@ export default function (pi: ExtensionAPI) {
 
     let tick = 0;
     let refreshStats = () => {};
+    let headerCache: { key: string; out: string[] } | null = null;
     const state = {
       timer: null as NodeJS.Timeout | null,
       mode: currentIntroMode() as IntroMode,
@@ -718,18 +720,27 @@ export default function (pi: ExtensionAPI) {
     setTimeout(() => {
       ctx.ui.setHeader((tui, theme) => {
         if (state.timer) clearInterval(state.timer);
+        headerCache = null;
 
         refreshStats = () => tui.requestRender();
+        // Capture once: a command changes the live prompt, not this intro.
+        const animationPolicy = resolveAnimationPolicy().policy;
         const animStart = Date.now();
-        state.timer = setInterval(() => {
-          tick++;
-          const finished = allStrokesReady() && tick > WRITING_END_TICK + 22;
-          if (finished || Date.now() - animStart > 5000) {
-            clearInterval(state.timer!);
-            state.timer = null;
-          }
-          try { tui.requestRender(); } catch { cleanup(); }
-        }, 25);
+        if (animationPolicy === "potato") {
+          tick = Number.MAX_SAFE_INTEGER;
+          state.timer = null;
+        } else {
+          const performance = animationPolicy === "performance";
+          state.timer = setInterval(() => {
+            tick += performance ? 10 : 1;
+            const finished = allStrokesReady() && tick > WRITING_END_TICK + 22;
+            if (finished || Date.now() - animStart > 5000) {
+              clearInterval(state.timer!);
+              state.timer = null;
+            }
+            try { tui.requestRender(); } catch { cleanup(); }
+          }, performance ? 250 : 25);
+        }
 
         // Grace period: pi-tui emite resizes transitorios mientras compone su layout inicial.
         const bootStart = Date.now();
@@ -753,8 +764,11 @@ export default function (pi: ExtensionAPI) {
         process.stdout.on("resize", resizeHandler);
 
         return {
+          /** Renders the persistent header grid; memoized per width, tick, mode and stats so static passes reuse the built lines. */
           render(width: number): string[] {
             if (state.mode === "skip") return [];
+            const headerKey = `${width}|${tick}|${state.mode}|${gitBranch}|${mcpServersCount}|${extensionsCount}|${packagesCount}|${sddAgentsCount}|${ctx.cwd}|${skills.length}|${customTools.length}`;
+            if (headerCache?.key === headerKey) return headerCache.out;
 
             const flashStartTick = 10;
             const roseOpacity = Math.min(1, tick / 10);
@@ -1050,9 +1064,10 @@ export default function (pi: ExtensionAPI) {
               out.push(truncateToWidth(line, Math.max(1, width), ""));
             }
 
+            headerCache = { key: headerKey, out };
             return out;
           },
-          invalidate() {},
+          invalidate() { headerCache = null; },
           dispose() {
             cleanup();
           },

package/lib/animation-policy.ts

@@ -0,0 +1,52 @@
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { gentlePiConfigHome } from "./agent-home.ts";
+
+export const ANIMATION_POLICY = { QUALITY: "quality", PERFORMANCE: "performance", POTATO: "potato" } as const;
+export type AnimationPolicy = (typeof ANIMATION_POLICY)[keyof typeof ANIMATION_POLICY];
+const SOURCE = { GLOBAL: "global_file", DEFAULT: "default" } as const;
+export const ANIMATION_SCHEMA = "gentle-pi.animations/v1";
+
+interface AnimationOptions { gentlePiConfigHome?: string }
+export interface AnimationResolution {
+	policy: AnimationPolicy;
+	source: (typeof SOURCE)[keyof typeof SOURCE];
+	malformed: boolean;
+	globalFile: string;
+}
+
+export function parseAnimationPolicyFile(raw: string): AnimationPolicy | undefined {
+	try {
+		const value: unknown = JSON.parse(raw);
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+		if (!("schema" in value) || value.schema !== ANIMATION_SCHEMA || !("policy" in value) || Object.keys(value).length !== 2) return undefined;
+		return value.policy === "quality" || value.policy === "performance" || value.policy === "potato" ? value.policy : undefined;
+	} catch { return undefined; }
+}
+
+export function resolveAnimationPolicy(options: AnimationOptions = {}): AnimationResolution {
+	const globalFile = join(options.gentlePiConfigHome ?? gentlePiConfigHome(), "animations.json");
+	try {
+		const policy = parseAnimationPolicyFile(readFileSync(globalFile, "utf8"));
+		return { policy: policy ?? "quality", source: SOURCE.GLOBAL, malformed: policy === undefined, globalFile };
+	} catch (error) {
+		const missing = typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+		return { policy: "quality", source: missing ? SOURCE.DEFAULT : SOURCE.GLOBAL, malformed: !missing, globalFile };
+	}
+}
+
+/** Same-directory rename prevents readers from seeing a partially written policy. */
+export function writeAnimationPolicy(policy: AnimationPolicy, options: AnimationOptions = {}): string {
+	const home = options.gentlePiConfigHome ?? gentlePiConfigHome();
+	const path = join(home, "animations.json");
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	mkdirSync(home, { recursive: true });
+	try {
+		writeFileSync(temporary, `${JSON.stringify({ schema: ANIMATION_SCHEMA, policy })}\n`, { flag: "wx", mode: 0o600 });
+		renameSync(temporary, path);
+	} finally {
+		try { unlinkSync(temporary); } catch { /* Rename already consumed the temporary file. */ }
+	}
+	return path;
+}

package/lib/background-cache-warming.ts

@@ -0,0 +1,38 @@
+import type { TaskRecord } from "./agents-protocol.ts";
+
+const ACTION = { WARM: "warm", STOP: "stop" } as const;
+type WarmingAction = (typeof ACTION)[keyof typeof ACTION];
+interface WarmingDecision {
+	warmCost: number;
+	missCost: number;
+	continuationProbability: number;
+	action: WarmingAction;
+}
+interface WarmingOverride { action: WarmingAction }
+interface WarmingEvents {
+	on(event: "cache_warming_decision", handler: (event: WarmingDecision) => WarmingOverride | undefined): unknown;
+}
+export interface WarmingState {
+	sessionId: string | undefined;
+	ownedTaskIds: ReadonlySet<string>;
+	tasks: Array<Pick<TaskRecord, "id" | "parentSessionId" | "mode" | "status">>;
+}
+
+// Pi 0.86.1's native minimum expected savings, in dollars. Ownership raises
+// continuation probability to 1, not permission to spend without a benefit.
+const MINIMUM_EXPECTED_SAVINGS = 0.05;
+
+export function installBackgroundCacheWarming(pi: WarmingEvents, state: () => WarmingState): void {
+	pi.on("cache_warming_decision", (event) => {
+		const { sessionId, ownedTaskIds, tasks } = state();
+		if (!sessionId || !tasks.some(task => task.parentSessionId === sessionId &&
+			ownedTaskIds.has(task.id) && task.mode === "background" &&
+			(task.status === "queued" || task.status === "running"))) return;
+		// Only native candidates arrive here: Pi owns opt-out, replay safety,
+		// provider TTLs, fixed horizons, scheduling and usage outside context.
+		const economic = Number.isFinite(event.warmCost) && event.warmCost >= 0 &&
+			Number.isFinite(event.missCost) && event.missCost > 0 &&
+			event.missCost - event.warmCost >= MINIMUM_EXPECTED_SAVINGS;
+		return { action: economic ? ACTION.WARM : ACTION.STOP };
+	});
+}

package/lib/command-palette-catalog.ts

@@ -26,6 +26,7 @@ export const COMMAND_PALETTE_CATALOG: readonly CommandPaletteCatalogGroup[] = [
 			{ command: "gentle:review-mode", label: "Review mode (receipt-driven development)" },
 			{ command: "gentle:background-subagents", label: "Background subagents" },
 			{ command: "gentle:double-esc-cancel", label: "Require double Esc to cancel" },
+			{ command: "gentle:animations", label: "Animation mode" },
 			{ command: "gentle:telemetry", label: "Telemetry" },
 			{ command: "gentle:banner", label: "Startup banner" },
 			{ command: "gentle:banner-color", label: "Banner color" },

package/lib/inprocess-reviewer.ts

@@ -59,6 +59,13 @@ export interface InProcessReviewerRequest {
 	readonly prompt: Buffer;
 	readonly timeoutMs: number;
 	readonly signal?: AbortSignal;
+	/**
+	 * The live pi session id, threaded from the extension context. Pi's main
+	 * agent loop adds OpenCode attribution headers itself; this side-call must
+	 * carry them itself instead. Absent (or empty) means no attribution header,
+	 * never an invented one and never an error.
+	 */
+	readonly sessionId?: string;
 	/** e.g. "review-risk" — only used to name the routing config key in refusal messages. */
 	readonly routingKey: string;
 }
@@ -126,6 +133,30 @@ function isTextContent(part: { type?: unknown }): part is TextContent {
 	return part.type === "text";
 }
 
+/**
+ * Mirrors pi's main-loop OpenCode attribution condition exactly
+ * (core/provider-attribution.js#getSessionHeaders): the model's provider is
+ * `opencode` or `opencode-go`, or its baseUrl host is `opencode.ai`. Returns
+ * the `{ x-opencode-session, x-opencode-client }` attribution pair, or
+ * undefined when the model is not OpenCode-routed or there is no live session
+ * id — a missing session id is never an error and never invents a header.
+ * The URL parse is guarded: an unparseable baseUrl follows the provider
+ * condition alone.
+ */
+export function openCodeSessionAttributionHeaders(model: Model<Api>, sessionId: string | undefined): ProviderHeaders | undefined {
+	const isOpenCode = model.provider === "opencode"
+		|| model.provider === "opencode-go"
+		|| (() => {
+			try {
+				return new URL(String(model.baseUrl ?? "")).hostname === "opencode.ai";
+			} catch {
+				return false;
+			}
+		})();
+	if (!isOpenCode || typeof sessionId !== "string" || sessionId.length === 0) return undefined;
+	return { "x-opencode-session": sessionId, "x-opencode-client": "pi" };
+}
+
 /**
  * Runs one reviewer completion in-process: resolve the model, authenticate,
  * map the routing thinking label, and complete exactly one frozen prompt as
@@ -168,6 +199,12 @@ export async function runInProcessReviewer(request: InProcessReviewerRequest, de
 		);
 	}
 
+	// Extension side-calls bypass pi's main agent loop, which is where OpenCode
+	// attribution headers are otherwise added, so this completion carries them
+	// itself — as a default beneath the registry's own auth headers, the same
+	// merge order pi's core uses for explicit header sources.
+	const attributionHeaders = openCodeSessionAttributionHeaders(model, request.sessionId);
+
 	// The caller's own signal (if any) and a floor timeout race together:
 	// whichever fires first aborts the completion. The catch branch below
 	// tells them apart by which underlying signal actually fired, never by
@@ -188,7 +225,7 @@ export async function runInProcessReviewer(request: InProcessReviewerRequest, de
 		signal: combinedSignal,
 		timeoutMs: request.timeoutMs,
 		...(auth.apiKey === undefined ? {} : { apiKey: auth.apiKey }),
-		...(auth.headers === undefined ? {} : { headers: auth.headers }),
+		...(auth.headers === undefined && attributionHeaders === undefined ? {} : { headers: attributionHeaders === undefined ? auth.headers : { ...attributionHeaders, ...auth.headers } }),
 		...(reasoning.reasoning === undefined ? {} : { reasoning: reasoning.reasoning }),
 	};
 

package/lib/native-review-cli.ts

@@ -201,7 +201,7 @@ export interface NativeReviewModeRequest {
 // explicit `committedOnly` acknowledgement, exactly like Native START's
 // baseRef/committedOnly pairing, because both select a committed range
 // instead of the ambient working tree.
-export interface NativeReviewAssessRequest {
+export interface NativeReviewAssessRequest extends NativeUntrackedSelection {
 	cwd: string;
 	baseRef?: string;
 	committedOnly?: boolean;
@@ -705,7 +705,11 @@ function isNativeUntrackedPath(value: unknown): value is string {
 		&& value.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 }
 
-function nativeUntrackedSelection(request: NativeUntrackedSelectionRequest): NativeUntrackedSelection {
+export function nativeUntrackedSelection(request: {
+	untrackedScope?: unknown;
+	expectedUntrackedInventory?: unknown;
+	intendedUntracked?: unknown;
+}): NativeUntrackedSelection {
 	const { untrackedScope, expectedUntrackedInventory, intendedUntracked } = request;
 	const declared = untrackedScope !== undefined || expectedUntrackedInventory !== undefined || intendedUntracked !== undefined;
 	if (!declared) return {};
@@ -716,16 +720,19 @@ function nativeUntrackedSelection(request: NativeUntrackedSelectionRequest): Nat
 	) {
 		throw new TypeError("Native untracked selection must declare one scope, one inventory digest, and unique repository-relative paths");
 	}
-	if (untrackedScope === NATIVE_UNTRACKED_SCOPE.EXCLUDE && (intendedUntracked?.length ?? 0) > 0) {
+	// The guard above establishes the array and element types for both typed
+	// native requests and untyped facade input.
+	const paths = intendedUntracked as readonly string[] | undefined;
+	if (untrackedScope === NATIVE_UNTRACKED_SCOPE.EXCLUDE && (paths?.length ?? 0) > 0) {
 		throw new TypeError("Native exclude untracked selection cannot include paths");
 	}
-	if (untrackedScope === NATIVE_UNTRACKED_SCOPE.SELECT && (intendedUntracked?.length ?? 0) === 0) {
+	if (untrackedScope === NATIVE_UNTRACKED_SCOPE.SELECT && (paths?.length ?? 0) === 0) {
 		throw new TypeError("Native select untracked selection requires at least one path");
 	}
 	return {
 		untrackedScope,
 		expectedUntrackedInventory,
-		intendedUntracked: intendedUntracked === undefined ? undefined : [...intendedUntracked],
+		intendedUntracked: paths === undefined ? undefined : [...paths],
 	};
 }
 
@@ -1018,6 +1025,13 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// and hint remain dark because neither is proven to reach the negotiated
 	// START path Pi consumes.
 	"3.4.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v3.5.0 repeats 3.4.0: the published provider contract bundle is
+	// byte-identical at 1.2.0, both binaries advertise capabilities/v2.6
+	// with only build-identity differences, and no review-integration schema
+	// changed. The v2 preflight failure identity fix does not change the
+	// closed START/STATUS fields this row negotiates. riskEvidence and hint
+	// remain dark; neither is proven to reach Pi's negotiated START path.
+	"3.5.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 export interface NativeReviewProcessDiagnostics {
@@ -1102,8 +1116,19 @@ function decodeSelectedLenses(value: unknown, riskLevel: string, lensesRequired:
 function enumString(value: unknown, allowed: readonly string[]): string { const parsed = stringValue(value); if (!allowed.includes(parsed)) throw new Error("unsupported enum"); return parsed; }
 const NATIVE_DIAGNOSTIC_TEXT_LIMIT = 4_096;
 
-function sanitizeNativeDiagnosticText(value: string, limit = NATIVE_DIAGNOSTIC_TEXT_LIMIT): string {
-	const normalized = value
+function sanitizeNativeDiagnosticText(value: string, limit = NATIVE_DIAGNOSTIC_TEXT_LIMIT, operation?: NativeReviewOperation): string {
+	// ASSESS diagnostics are projected into a public verification plan. Retain
+	// native guidance, not local paths or environment assignment values.
+	const input = operation === NATIVE_REVIEW_OPERATION.ASSESS
+		? value
+			.replace(/(?<![\w-])[a-z_][a-z0-9_]*=(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s]+)/gi, "[REDACTED ENV]")
+			.replace(/--(?:password|token|secret|authorization|cookie|private[_-]key|access[_-]token|[a-z0-9_-]+[_-]token|api[_-]?key)[ \t]+(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s]+)/gi, "[REDACTED CREDENTIAL]")
+			// Quoted paths have a clear boundary. For an unquoted path, the
+			// remaining line is ambiguous (spaces may belong to the filename).
+			// Redact that suffix rather than leak trailing path components.
+			.replace(/"(?:[A-Za-z]:[\\/]|\/)[^"\r\n]*"|'(?:[A-Za-z]:[\\/]|\/)[^'\r\n]*'|(?:[A-Za-z]:[\\/]|\/)[^\r\n]*/g, "[REDACTED PATH]")
+		: value;
+	const normalized = input
 		.replace(/\x1b](?:[^\x07\x1b]|\x1b(?!\\))*?(?:\x07|\x1b\\)/g, "[REDACTED CONTROL]")
 		.replace(/\x1b[PX^_][\s\S]*?\x1b\\/g, "[REDACTED CONTROL]")
 		.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "[REDACTED CONTROL]")
@@ -1137,7 +1162,7 @@ export function sanitizeForeignNativeReviewDiagnostics(value: unknown): NativeRe
 			timed_out: booleanValue(raw.timed_out),
 			output_limit_exceeded: booleanValue(raw.output_limit_exceeded),
 			...(maxBufferBytes === undefined ? {} : { max_buffer_bytes: maxBufferBytes, configuration_hint: configurationHint! }),
-			...(raw.stderr === undefined ? {} : { stderr: sanitizeNativeDiagnosticText(stringValue(raw.stderr)) }),
+			...(raw.stderr === undefined ? {} : { stderr: sanitizeNativeDiagnosticText(stringValue(raw.stderr), NATIVE_DIAGNOSTIC_TEXT_LIMIT, operation) }),
 		};
 	} catch { return undefined; }
 }
@@ -1154,7 +1179,7 @@ function nativeProcessDiagnostics(operation: NativeReviewOperation, code: Native
 		...(code === NATIVE_REVIEW_ERROR_CODE.OUTPUT_LIMIT && maxBufferBytes !== undefined
 			? { max_buffer_bytes: maxBufferBytes, configuration_hint: NATIVE_REVIEW_MAX_BUFFER_CONFIGURATION_HINT }
 			: {}),
-		...(result?.stderr.trim() ? { stderr: sanitizeNativeDiagnosticText(result.stderr) } : {}),
+		...(result?.stderr.trim() ? { stderr: sanitizeNativeDiagnosticText(result.stderr, NATIVE_DIAGNOSTIC_TEXT_LIMIT, operation) } : {}),
 	};
 }
 
@@ -2535,6 +2560,7 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 	// rejects -- callers (the `gentle_review` tool's `assess` operation) fail
 	// closed to `high`.
 	async assess(request: NativeReviewAssessRequest): Promise<ReviewAssessmentV1> {
+		const selection = nativeUntrackedSelection(request);
 		if (request.baseRef !== undefined && !isCanonicalProcessString(request.baseRef)) throw new TypeError("Native ASSESS baseRef must be a non-empty, trimmed, NUL-free string");
 		if (request.baseRef !== undefined && request.committedOnly !== true) throw new TypeError("Native ASSESS baseRef requires explicit committedOnly acknowledgement");
 		if (request.baseRef === undefined && request.committedOnly !== undefined) throw new TypeError("Native ASSESS committedOnly requires an explicit baseRef");
@@ -2542,7 +2568,7 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 		const execution = await this.invoke(
 			NATIVE_REVIEW_OPERATION.ASSESS,
 			cwd,
-			["review", "assess", "--cwd", cwd, ...(request.baseRef === undefined ? [] : ["--base-ref", request.baseRef, "--committed-only"]), "--json"],
+			["review", "assess", "--cwd", cwd, ...(request.baseRef === undefined ? [] : ["--base-ref", request.baseRef, "--committed-only"]), ...nativeUntrackedSelectionArguments(selection), "--json"],
 			false,
 			request.signal,
 			this.executablePath(NATIVE_REVIEW_OPERATION.ASSESS, false),