gentle-pi 3.2.1 → 3.4.0

package/extensions/gentle-todo.ts

@@ -104,19 +104,37 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 	};
 
 	const todoCard = (current: TodoSession, theme: Parameters<typeof renderTodoCard>[1], scrollable: boolean, spacer: boolean): Component & { dispose(): void } => {
+		let hovered = false;
 		const card: Component = {
 			render(width: number) {
 				const lines = renderTodoCard(current.state, theme, width, {
 					collapsed: current.collapsed,
 					staleTurns: staleTurns(current.state, current.turn),
 					collapseKey,
+					hovered,
 					...(scrollable ? { scrollable: true } : {}),
 				});
 				return spacer && lines.length > 0 ? [...lines, ""] : lines;
 			},
-			invalidate() {},
+			invalidate() {
+				hovered = false;
+			},
 		};
 		const region = new NativePointerRegion(card, {
+			onHover(event) {
+				// The region spans the whole card, but only the header row (y===0)
+				// is the clickable control, so a move elsewhere in the card clears
+				// hover exactly like leaving the region entirely would.
+				const next = event.y === 0;
+				if (next === hovered) return { handled: true };
+				hovered = next;
+				return { handled: true, render: true };
+			},
+			onLeave() {
+				if (!hovered) return;
+				hovered = false;
+				current.host?.requestRender();
+			},
 			onClick(event) {
 				if (event.button !== "left" || event.y !== 0) return undefined;
 				toggle(current);

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/agents-view.ts

@@ -1,5 +1,6 @@
 import { Key, matchesKey, truncateToWidth, visibleWidth, type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
 import { measureAgentsViewLayout, type AgentsViewLayout } from "./agents-view-layout.ts";
+import { HOVER_ROLE, paintHoverable } from "./shell-hover.ts";
 import { emptyThread, isFinished, TASK_STATUS, type TaskRecord, type TaskStore, type TaskThread, type ThreadItem } from "./agents-protocol.ts";
 import { renderThreadItem, type AgentsThreadTheme } from "./agents-thread-view.ts";
 import { formatElapsed } from "./agents-widget.ts";
@@ -42,7 +43,7 @@ const ROLE = {
 	FRAME: "border",
 	TITLE: "customMessageLabel",
 	SELECTED: "accent",
-	HOVER: "warning",
+	HOVER: HOVER_ROLE,
 	NAME: "text",
 	NAME_IDLE: "muted",
 	META: "dim",
@@ -69,7 +70,7 @@ const GLYPH_ROLE: Record<string, string> = {
 	[TASK_STATUS.CANCELLED]: "dim",
 	[TASK_STATUS.TIMED_OUT]: "error",
 };
-export const SESSION_FINISHED_TTL_MS = 15 * 60_000;
+const MAX_FINISHED_PER_SESSION = 200;
 const SCOPE_LABEL: Record<ViewScope, string> = { [VIEW_SCOPE.SESSION]: "this session", [VIEW_SCOPE.ALL]: "all sessions" };
 const SCOPE_KEY: Record<ViewScope, string> = { [VIEW_SCOPE.SESSION]: "all sessions", [VIEW_SCOPE.ALL]: "this session" };
 const EMPTY_LIST = "no tasks yet";
@@ -428,7 +429,8 @@ export class AgentsView {
 
 	private counts(): string {
 		const active = this.tasks.filter((task) => !isFinished(task.status)).length;
-		return `${active} active`;
+		const finished = this.tasks.length - active;
+		return `${active} active · ${finished} finished`;
 	}
 
 	private actionableTask(): TaskRecord | undefined {
@@ -470,8 +472,12 @@ export class AgentsView {
 	}
 
 	private inScope(task: TaskRecord, _now: number): boolean {
-		return !isFinished(task.status) && (task.parentSessionId === this.deps.sessionId
-			|| (this.scope === VIEW_SCOPE.ALL && this.remoteThreads.has(task.id)));
+		// A local task (this session's own, active or finished history) always
+		// belongs; refreshTasks() is the single authority on which finished ones
+		// survive its own retention cap. A remote (presence) task never keeps
+		// history -- it drops out of scope the moment it finishes.
+		if (task.parentSessionId === this.deps.sessionId) return true;
+		return !isFinished(task.status) && this.scope === VIEW_SCOPE.ALL && this.remoteThreads.has(task.id);
 	}
 
 	private directoryRoot(): boolean {
@@ -534,8 +540,19 @@ export class AgentsView {
 	}
 
 	private refreshTasks(): void {
-		this.tasks = this.deps.store.list().filter((task) => task.parentSessionId === this.deps.sessionId
-			&& !isFinished(task.status) && (this.deps.isLocalTask?.(task) ?? true));
+		// Finished history bypasses isLocalTask: that dep exists to keep an
+		// unrelated task resolveTask pulled in on demand (e.g. `subagent_result`
+		// for an id from another session) out of the live panel, never to hide
+		// this session's own finished subagents -- those belong here whether
+		// they were restored on resume or just finished live.
+		const local = this.deps.store.list().filter((task) => task.parentSessionId === this.deps.sessionId
+			&& (isFinished(task.status) || (this.deps.isLocalTask?.(task) ?? true)));
+		const active = local.filter((task) => !isFinished(task.status));
+		const finished = local
+			.filter((task) => isFinished(task.status))
+			.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0))
+			.slice(0, MAX_FINISHED_PER_SESSION);
+		this.tasks = [...active, ...finished];
 		if (this.scope === VIEW_SCOPE.ALL) this.tasks.push(...this.peers.flatMap((group) => group.tasks));
 		const groups = this.sessionGroups();
 		const present = new Set(groups.map((group) => group.id));
@@ -564,7 +581,15 @@ export class AgentsView {
 			group.tasks.push(task);
 		}
 		for (const group of groups.values()) {
-			group.tasks.sort((a, b) => b.createdAt - a.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+			// Active tasks first (newest created), then finished ones as history
+			// (newest ended first) -- a task never reorders within its own group
+			// just because it finished.
+			group.tasks.sort((a, b) => {
+				const finishedRank = Number(isFinished(a.status)) - Number(isFinished(b.status));
+				if (finishedRank !== 0) return finishedRank;
+				if (isFinished(a.status)) return (b.endedAt ?? 0) - (a.endedAt ?? 0);
+				return b.createdAt - a.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+			});
 		}
 		if (this.scope === VIEW_SCOPE.ALL) {
 			const localId = `session:${this.deps.sessionId}`;
@@ -637,16 +662,18 @@ export class AgentsView {
 		const theme = this.deps.theme;
 		this.taskRegion(row).render(this.pointerLayout?.listWidth ?? 1);
 		const selected = entry.id === this.selectedRow()?.id;
-		const hovered = entry.id === this.hoveredId;
-		const emphasis = selected ? ROLE.SELECTED : hovered ? ROLE.HOVER : undefined;
-		const marker = emphasis ? theme.fg(emphasis, selected ? "▸" : "▹") : " ";
+		// Selection always outranks hover; the shared hover painter only
+		// applies once selection is ruled out.
+		const hovered = !selected && entry.id === this.hoveredId;
+		const markerRole = selected ? ROLE.SELECTED : hovered ? ROLE.HOVER : undefined;
+		const marker = markerRole ? theme.fg(markerRole, selected ? "▸" : "▹") : " ";
 		if (entry.kind === "heading") {
 			const state = this.isExpanded(entry.group) ? "▾" : "▸";
-			return `${marker}${theme.fg(emphasis ?? ROLE.SELECTED, state)} ${theme.fg(emphasis ?? ROLE.NAME_IDLE, this.groupHeading(entry.group))}`;
+			return `${marker}${paintHoverable(theme, state, hovered, ROLE.SELECTED)} ${paintHoverable(theme, this.groupHeading(entry.group), hovered, selected ? ROLE.SELECTED : ROLE.NAME_IDLE)}`;
 		}
 		const task = entry.task;
 		const glyph = theme.fg(GLYPH_ROLE[task.status] ?? ROLE.META, GLYPH[task.status] ?? "?");
-		const name = theme.fg(emphasis ?? ROLE.NAME_IDLE, `Subagent ${task.agent}`);
+		const name = paintHoverable(theme, `Subagent ${task.agent}`, hovered, selected ? ROLE.SELECTED : ROLE.NAME_IDLE);
 		const time = task.startedAt === null ? "" : theme.fg(ROLE.META, formatElapsed((task.endedAt ?? this.deps.now()) - task.startedAt));
 		return `${marker} ${theme.fg(ROLE.META, "└")} ${glyph} ${name}  ${time}`;
 	}
@@ -756,7 +783,7 @@ export class AgentsView {
 			actions.push({ x: 2 + visibleWidth(text), width: label.length, region: control.region });
 			control.region.render(label.length);
 			const hovered = (control.region === this.followRegion && this.hoveredControl === "follow") || (control.region === this.openRegion && this.hoveredControl === "open");
-			text += this.deps.theme.fg(!control.enabled ? ROLE.META : hovered ? ROLE.HOVER : ROLE.KEY, label);
+			text += control.enabled ? paintHoverable(this.deps.theme, label, hovered, ROLE.KEY) : this.deps.theme.fg(ROLE.META, label);
 		}
 		if (required > width) {
 			const more = this.actionRegion("more", () => {

package/lib/agents-widget.ts

@@ -29,7 +29,28 @@ interface Columns {
 	name: number;
 	task: number;
 	meta: number;
-	fullMetrics: boolean;
+	// Columnar rows give each surviving metadata field its own fixed,
+	// right-aligned column sized to the widest value among shown tasks, so
+	// model·effort, tokens, cost, and elapsed line up vertically across rows.
+	// A narrow card may have dropped some of those columns and still be
+	// columnar; false means the clipped single-string fallback.
+	columnar: boolean;
+	// Populated only when columnar is true.
+	metaWidths?: MetaColumnWidths;
+}
+
+interface MetaFields {
+	exec: string;
+	tokens: string;
+	cost: string;
+	elapsed: string;
+}
+
+interface MetaColumnWidths {
+	exec: number;
+	tokens: number;
+	cost: number;
+	elapsed: number;
 }
 
 const LOOK: Record<TaskStatus, StatusLook> = {
@@ -150,11 +171,48 @@ function executionLabel(task: TaskRecord, width = Infinity): string {
 	return clip(model, width - visibleWidth(suffix)) + suffix;
 }
 
-function meta(task: TaskRecord, now: number, fullMetrics: boolean): string {
-	if (task.status === TASK_STATUS.QUEUED) return "queued";
-	if (!fullMetrics) return executionLabel(task);
-	const parts = [executionLabel(task), task.tokens > 0 ? formatTokens(task.tokens) : "", task.cost > 0 ? `$${task.cost.toFixed(2)}` : "", elapsed(task, now)];
-	return parts.filter((part) => part.length > 0).join(" · ");
+// Narrow (non-columnar) rows keep the single-string contract: a queued
+// task shows the bare word, everything else shows its exec label.
+function narrowMetaText(task: TaskRecord): string {
+	return task.status === TASK_STATUS.QUEUED ? "queued" : executionLabel(task);
+}
+
+// Queued rows carry no model, token, or cost data yet, so every field but
+// elapsed stays blank — and elapsed itself becomes the literal word "queued"
+// rather than the empty string startedAt === null would otherwise produce.
+function metaFields(task: TaskRecord, now: number): MetaFields {
+	if (task.status === TASK_STATUS.QUEUED) return { exec: "", tokens: "", cost: "", elapsed: "queued" };
+	return {
+		exec: executionLabel(task),
+		tokens: task.tokens > 0 ? formatTokens(task.tokens) : "",
+		cost: task.cost > 0 ? `$${task.cost.toFixed(2)}` : "",
+		elapsed: elapsed(task, now),
+	};
+}
+
+function metaColumnWidths(tasks: readonly TaskRecord[], now: number): MetaColumnWidths {
+	const fields = tasks.map((task) => metaFields(task, now));
+	const widest = (pick: (field: MetaFields) => string) => Math.max(0, ...fields.map((field) => visibleWidth(pick(field))));
+	return { exec: widest((field) => field.exec), tokens: widest((field) => field.tokens), cost: widest((field) => field.cost), elapsed: widest((field) => field.elapsed) };
+}
+
+// A column whose widest value is empty across every shown task (e.g. no task
+// carries a cost yet) is dropped entirely, together with its separator —
+// exactly like the old joined string dropped an empty field, but decided once
+// for the whole card rather than per row, so the remaining columns still align.
+function metaTotalWidth(widths: MetaColumnWidths): number {
+	const active = [widths.exec, widths.tokens, widths.cost, widths.elapsed].filter((width) => width > 0);
+	return active.reduce((sum, width) => sum + width, 0) + Math.max(0, active.length - 1) * visibleWidth(" · ");
+}
+
+function metaRowText(task: TaskRecord, now: number, widths: MetaColumnWidths): string {
+	const fields = metaFields(task, now);
+	const parts: string[] = [];
+	if (widths.exec > 0) parts.push(fields.exec.padStart(widths.exec));
+	if (widths.tokens > 0) parts.push(fields.tokens.padStart(widths.tokens));
+	if (widths.cost > 0) parts.push(fields.cost.padStart(widths.cost));
+	if (widths.elapsed > 0) parts.push(fields.elapsed.padStart(widths.elapsed));
+	return parts.join(" · ");
 }
 
 function taskText(task: TaskRecord): string {
@@ -163,27 +221,40 @@ function taskText(task: TaskRecord): string {
 	return task.label;
 }
 
-// Narrow cards give up the task and usage columns before execution metadata.
+// Narrow cards degrade per column, decided once for the whole card so the
+// surviving columns keep lining up: the task text goes first, then the
+// model·effort label, then tokens, then cost. Elapsed is the one value the
+// reader cannot rebuild from anything else on screen, so it is the last to go
+// (gentle-shell#1143). Only when even elapsed alone does not fit does the row
+// fall back to the clipped single-string label.
 function columns(tasks: readonly TaskRecord[], inner: number, now: number): Columns {
 	const name = Math.max(0, Math.min(NAME_MAX, inner - 3, Math.max(...tasks.map((task) => visibleWidth(task.agent)))));
 	const fixed = 1 + GLYPH_GAP.length + name + COLUMN_GAP.length;
-	const metaWidth = (fullMetrics: boolean) => Math.max(...tasks.map((task) => visibleWidth(meta(task, now, fullMetrics))));
-	const full = metaWidth(true);
+	const metaWidths = metaColumnWidths(tasks, now);
+	const full = metaTotalWidth(metaWidths);
 	const task = inner - fixed - full - COLUMN_GAP.length;
-	if (task >= TASK_MIN) return { inner, name, meta: full, task, fullMetrics: true };
-	return { inner, name, meta: Math.max(0, Math.min(inner - fixed, metaWidth(false))), task: 0, fullMetrics: false };
+	if (task >= TASK_MIN) return { inner, name, meta: full, task, columnar: true, metaWidths };
+	let widths = metaWidths;
+	for (const drop of ["exec", "tokens", "cost"] as const) {
+		if (metaTotalWidth(widths) <= inner - fixed) break;
+		widths = { ...widths, [drop]: 0 };
+	}
+	const meta = metaTotalWidth(widths);
+	if (meta > 0 && meta <= inner - fixed) return { inner, name, meta, task: 0, columnar: true, metaWidths: widths };
+	const narrow = Math.max(0, ...tasks.map((task) => visibleWidth(narrowMetaText(task))));
+	return { inner, name, meta: Math.max(0, Math.min(inner - fixed, narrow)), task: 0, columnar: false };
 }
 
 function row(task: TaskRecord, theme: CardTheme, cols: Columns, now: number, allowMetadataRow: boolean): string[] {
 	const look = LOOK[task.status];
 	const name = clip(task.agent, cols.name);
 	const head = `${theme.fg(look.role, look.glyph)}${GLYPH_GAP}${theme.fg(NAME_ROLE, name)}${" ".repeat(cols.name - visibleWidth(name))}`;
-	const metadata = cols.fullMetrics ? meta(task, now, true) : task.status === TASK_STATUS.QUEUED ? clip("queued", cols.meta) : executionLabel(task, cols.meta);
+	const metadata = cols.columnar && cols.metaWidths ? metaRowText(task, now, cols.metaWidths) : task.status === TASK_STATUS.QUEUED ? clip("queued", cols.meta) : executionLabel(task, cols.meta);
 	const tail = theme.fg(META_ROLE, " ".repeat(Math.max(0, cols.meta - visibleWidth(metadata))) + metadata);
 	if (cols.inner < 3) return [theme.fg(look.role, clip(look.glyph, cols.inner))];
 	// The scrollable sidebar can preserve identity and execution metadata on
 	// separate rows. The height-capped above-editor widget keeps its row budget.
-	if (allowMetadataRow && cols.task === 0 && task.status !== TASK_STATUS.QUEUED && visibleWidth(executionLabel(task)) > cols.meta) {
+	if (allowMetadataRow && !cols.columnar && cols.task === 0 && task.status !== TASK_STATUS.QUEUED && visibleWidth(executionLabel(task)) > cols.meta) {
 		return [head, theme.fg(META_ROLE, executionLabel(task, cols.inner))];
 	}
 	if (cols.task === 0) return [`${head}${" ".repeat(Math.max(0, cols.inner - visibleWidth(head) - visibleWidth(tail)))}${tail}`];

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

@@ -25,6 +25,8 @@ export const COMMAND_PALETTE_CATALOG: readonly CommandPaletteCatalogGroup[] = [
 			{ command: "gentle:persona", label: "Switch persona" },
 			{ 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" },