gentle-pi 2.4.0 → 2.6.0

package/extensions/gentle-todo.ts

@@ -0,0 +1,234 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text, type Component, type TUI } from "@earendil-works/pi-tui";
+import { NativePointerRegion } from "../lib/native-pointer-region.ts";
+import { sidebarPart } from "../lib/shell-sidebar.ts";
+import { invalidateSidebar } from "../lib/shell-sidebar-layout.ts";
+import {
+	applyTodo,
+	emptyTodo,
+	renderTodoCard,
+	replayTodo,
+	staleTurns,
+	TODO_DETAILS_KEY,
+	TODO_GLYPH,
+	TODO_TOOL_NAME,
+	todoPromptBlock,
+	todoSummary,
+	type TodoParams,
+	type TodoState,
+} from "../lib/shell-todo.ts";
+
+// Gentle Todo: the task list the model keeps while it works, drawn as a
+// Gentle Shell card above the editor. Three things keep it current that a
+// static tool description cannot: `write` replaces the whole list in one
+// call, every turn's system prompt carries the open tasks and the rules, and
+// a list that goes untouched while tasks stay open is marked stale for both
+// the human and the model.
+
+const WIDGET_KEY = "gentle-todo";
+const COLLAPSE_KEY_DEFAULT = "ctrl+shift+t";
+const TOOL_PARAMETERS = {
+	type: "object",
+	additionalProperties: false,
+	required: ["action"],
+	properties: {
+		action: { type: "string", enum: ["write", "add", "update", "clear", "list"], description: "write replaces the whole list; add appends one task; update changes one task by id; clear empties the list; list reports it." },
+		tasks: {
+			type: "array",
+			description: "For write: the complete ordered list. Keep the id of tasks that already exist so their history survives; omit it for new ones.",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				required: ["title"],
+				properties: {
+					id: { type: "integer", description: "Existing task id to keep." },
+					title: { type: "string", description: "Short imperative title, e.g. 'Write the parser'." },
+					status: { type: "string", enum: ["pending", "in_progress", "done"], description: "Defaults to pending." },
+					note: { type: "string", description: "What is happening right now, shown while in_progress, e.g. 'writing tests'." },
+				},
+			},
+		},
+		id: { type: "integer", description: "Task id for update." },
+		title: { type: "string", description: "Title for add, or a new title for update." },
+		status: { type: "string", enum: ["pending", "in_progress", "done"], description: "Status for add or update." },
+		note: { type: "string", description: "Note for add or update." },
+	},
+} as const;
+
+export function todoEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	if (env.GENTLE_PI_AGENTS_CHILD === "1") return false;
+	const value = env.GENTLE_PI_TODO?.trim().toLowerCase();
+	return !(value === "0" || value === "false" || value === "off");
+}
+
+export function todoCollapseKey(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const value = env.GENTLE_PI_TODO_KEY?.trim();
+	if (value === undefined) return COLLAPSE_KEY_DEFAULT;
+	return value === "" || value.toLowerCase() === "off" ? undefined : value;
+}
+
+interface TodoSession {
+	state: TodoState;
+	turn: number;
+	collapsed: boolean;
+	/** A finished list stays on screen for the turn it finished in, then clears. */
+	clearOnNextTurn: boolean;
+	ui: ExtensionContext["ui"] | undefined;
+	host: { requestRender(): void } | undefined;
+	tui: TUI | undefined;
+}
+
+function sessionKey(ctx: ExtensionContext): string {
+	return ctx.sessionManager.getSessionId() ?? "";
+}
+
+export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = process.env): void {
+	if (!todoEnabled(env)) return;
+	const sessions = new Map<string, TodoSession>();
+	const collapseKey = todoCollapseKey(env);
+
+	const session = (ctx: ExtensionContext): TodoSession => {
+		const key = sessionKey(ctx);
+		let current = sessions.get(key);
+		if (!current) {
+			current = { state: emptyTodo(), turn: 0, collapsed: false, clearOnNextTurn: false, ui: undefined, host: undefined, tui: undefined };
+			sessions.set(key, current);
+		}
+		return current;
+	};
+
+	const toggle = (current: TodoSession) => {
+		current.collapsed = !current.collapsed;
+		if (current.tui) invalidateSidebar(current.tui);
+		current.host?.requestRender();
+	};
+
+	const todoCard = (current: TodoSession, theme: Parameters<typeof renderTodoCard>[1], scrollable: boolean, spacer: boolean): Component & { dispose(): void } => {
+		const card: Component = {
+			render(width: number) {
+				const lines = renderTodoCard(current.state, theme, width, {
+					collapsed: current.collapsed,
+					staleTurns: staleTurns(current.state, current.turn),
+					collapseKey,
+					...(scrollable ? { scrollable: true } : {}),
+				});
+				return spacer && lines.length > 0 ? [...lines, ""] : lines;
+			},
+			invalidate() {},
+		};
+		const region = new NativePointerRegion(card, {
+			onClick(event) {
+				if (event.button !== "left" || event.y !== 0) return undefined;
+				toggle(current);
+				return { handled: true, render: true };
+			},
+		});
+		return {
+			render: (width) => region.render(width),
+			handleMouse: (event) => region.handleMouse(event),
+			invalidate: () => region.invalidate(),
+			dispose: () => region.dispose(),
+		};
+	};
+
+	const show = (current: TodoSession) => {
+		if (current.tui) invalidateSidebar(current.tui);
+		if (!current.ui) return;
+		if (current.state.tasks.length === 0) {
+			current.ui.setWidget(WIDGET_KEY, undefined);
+			return;
+		}
+		const snapshot = current;
+		current.ui.setWidget(WIDGET_KEY, (tui, theme) => {
+			snapshot.host = tui;
+			snapshot.tui = tui;
+			return sidebarPart(tui, "todo", todoCard(snapshot, theme, false, true), todoCard(snapshot, theme, true, false));
+		});
+	};
+
+	pi.registerTool({
+		name: TODO_TOOL_NAME,
+		renderShell: "self",
+		label: "Todo",
+		description: "Plan and track multi-step work. Use write to set the whole list, update to move one task, add for a new one, clear to reset, list to read it back.",
+		promptSnippet: "Track multi-step work; rewrite the whole list as the plan changes",
+		promptGuidelines: [
+			"Use todo for work with three or more steps or when the user hands you a list. Skip it for single trivial requests.",
+			"Mark a task in_progress before starting it and done right after finishing it; keep exactly one task in_progress.",
+			"Prefer write with the complete list whenever the plan changes; keep ids of tasks that already exist.",
+			"Never mark a task done while tests fail or the work is partial; add a task for the blocker instead.",
+		],
+		parameters: TOOL_PARAMETERS,
+		executionMode: "sequential",
+		renderCall(args, theme) {
+			const params = args as TodoParams;
+			return new Text(theme.fg("toolTitle", `${TODO_GLYPH} todo · ${params.action}`), 0, 0);
+		},
+		renderResult(result, options, theme) {
+			const text = result.content.map((part) => (part.type === "text" ? part.text : "")).join("\n");
+			return new Text(options.expanded ? text : theme.fg("muted", text.split("\n")[0] ?? ""), 0, 0);
+		},
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const current = session(ctx);
+			const result = applyTodo(current.state, params as TodoParams, current.turn);
+			if (!result.error) {
+				current.state = result.state;
+				current.clearOnNextTurn = false;
+				if (current.tui) invalidateSidebar(current.tui);
+			}
+			return {
+				content: [{ type: "text", text: result.text }],
+				details: { [TODO_DETAILS_KEY]: result.state, ...(result.error ? { error: result.error } : {}) },
+			};
+		},
+	});
+
+	if (collapseKey) {
+		pi.registerShortcut(collapseKey as Parameters<ExtensionAPI["registerShortcut"]>[0], {
+			description: "Collapse or expand the todo list",
+			handler: async (ctx) => {
+				toggle(session(ctx));
+			},
+		});
+	}
+
+	pi.on("session_start", (_event, ctx) => {
+		const current = session(ctx);
+		// A list that was already finished when the session was left is history,
+		// not work: it would otherwise sit on screen until two more turns pass.
+		const replayed = replayTodo(ctx.sessionManager.getBranch());
+		current.state = replayed.tasks.length > 0 && todoSummary(replayed).open === 0 ? { ...replayed, tasks: [] } : replayed;
+		current.turn = ctx.sessionManager.getBranch().filter((entry) => (entry as { type?: string }).type === "message" && (entry as { message?: { role?: string } }).message?.role === "user").length;
+		current.ui = ctx.hasUI ? ctx.ui : undefined;
+		show(current);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		sessions.delete(sessionKey(ctx));
+	});
+
+	pi.on("before_agent_start", (event, ctx) => {
+		const current = session(ctx);
+		current.turn += 1;
+		if (current.tui) invalidateSidebar(current.tui);
+		if (current.clearOnNextTurn) {
+			current.state = { ...current.state, tasks: [] };
+			current.clearOnNextTurn = false;
+			show(current);
+		}
+		const block = todoPromptBlock(current.state, staleTurns(current.state, current.turn));
+		if (!block) return undefined;
+		return { systemPrompt: `${event.systemPrompt}\n\n${block}` };
+	});
+
+	pi.on("tool_execution_end", (event, ctx) => {
+		if (event.toolName !== TODO_TOOL_NAME) return;
+		show(session(ctx));
+	});
+
+	pi.on("agent_end", (_event, ctx) => {
+		const current = session(ctx);
+		if (current.state.tasks.length > 0 && todoSummary(current.state).open === 0) current.clearOnNextTurn = true;
+		show(current);
+	});
+}

package/extensions/quiet-tools.ts

@@ -625,6 +625,7 @@ function registerQuietTool(pi: ExtensionAPI, toolName: QuietToolName, commandArg
 
 	pi.registerTool({
 		...registrationTool,
+		renderShell: "self",
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			const runtimeTool = getBuiltInTools(ctx.cwd)[toolName];
 			return runtimeTool.execute(toolCallId, params, signal, onUpdate, ctx);
@@ -653,7 +654,7 @@ function registerQuietTool(pi: ExtensionAPI, toolName: QuietToolName, commandArg
 				{ result: true, isPartial: options.isPartial },
 			).directResult;
 			if (directResult) {
-				return renderGentleAiResult(safeResult, { expanded: options.expanded });
+				return renderGentleAiResult(safeResult, { expanded: options.expanded, isPartial: options.isPartial, isError }, theme, renderContext as GentleAiRenderContext | undefined);
 			}
 			if (options.isPartial) {
 				if (options.expanded) return new Text(`${theme.fg("warning", partialLabel(toolName, text))}\n${theme.fg("muted", text)}`, 0, 0);

package/extensions/runtime-metrics.ts

@@ -0,0 +1,130 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { EFFORTS, ORCHESTRATOR_AGENT_CLASS, RuntimeMetrics, UNKNOWN_AGENT_CLASS, type FinalResponse, type TokenMeasurement } from "../lib/runtime-metrics.ts";
+import { classifyPiCatalogName, lookupPiCatalogName } from "../lib/runtime-metrics-pi-identity.ts";
+import { CHILD_METRICS_EVENT, CHILD_METRICS_REVOKED, snapshotChildEvent, type ChildLaunchBucket } from "../lib/runtime-metrics-children.ts";
+import { RuntimeMetricsAttempt } from "../lib/runtime-metrics-delivery.ts";
+import { sendNativeRuntimeEvent, type NativeRuntimeTransportDeps } from "../lib/runtime-metrics-native.ts";
+import { runtimeMetricsEnvAllows } from "../lib/runtime-metrics-policy.ts";
+
+/** Available final usage -> one deferred attempt -> discard. No history reads,
+ * cumulative session accounting, policy leases, delivery queue or retry. Print
+ * mode alone joins its accepted attempt for at most 1.5 seconds at shutdown.
+ * Pi hooks lack request correlation: latency and SDK-zero presence are unknown.
+ */
+export default function runtimeMetrics(pi: ExtensionAPI, env = process.env,
+	{ lookup = lookupPiCatalogName, classify = classifyPiCatalogName, native, send = sendNativeRuntimeEvent,
+		now = () => performance.now(), shutdownWaitMs = 1500 }:
+	{ lookup?: typeof lookupPiCatalogName; classify?: typeof classifyPiCatalogName; native?: NativeRuntimeTransportDeps;
+		send?: typeof sendNativeRuntimeEvent; now?: () => number; shutdownWaitMs?: number } = {}): void {
+	const allows = () => env.GENTLE_PI_AGENTS_CHILD !== "1" && runtimeMetricsEnvAllows(env);
+	if (!allows()) return;
+	type Selection = Pick<FinalResponse, "selectedModelId" | "selectedProvider" | "effort">;
+	let selection: Selection | undefined;
+	let active = false;
+	let requestSeen = false;
+	let ambiguous = false;
+	let live: { id: string; started: number; ctx: ExtensionContext; attempt: RuntimeMetricsAttempt;
+		seen: WeakSet<object>; children: Set<string>; catalog: boolean } | undefined;
+	const missing = { state: "unavailable" } as const;
+	function invalidate() { selection = undefined; ambiguous = true; }
+	function dispose() { live?.attempt.dispose(); live = undefined; active = false; invalidate(); }
+	function current(ctx: ExtensionContext) {
+		if (!allows() || live?.id !== ctx.sessionManager.getSessionId()) dispose();
+		return live;
+	}
+	function refreshCatalog(owner: NonNullable<typeof live>, input: { provider: unknown; modelId: unknown }) {
+		void lookup(input).then(result => {
+			if (live === owner && result.classification === "catalog_public") owner.catalog = true;
+		}, () => { /* A later classification callback may retry the bounded load. */ });
+	}
+	function submit(owner: NonNullable<typeof live>, responses: FinalResponse[], launches?: ChildLaunchBucket[]) {
+		if (!responses.length || live !== owner || !current(owner.ctx)) return;
+		// Ephemeral event-local accounting only; source IDs never enter these rows.
+		const metrics = new RuntimeMetrics({ classifyModel: classify });
+		for (const [index, row] of responses.entries()) metrics.record({ ...row, responseId: String(index) });
+		const rows = metrics.snapshot();
+		if (!rows.length) return;
+		const cwd = owner.ctx.cwd;
+		owner.attempt.offer(async signal => {
+			if (live !== owner || !current(owner.ctx) || signal.aborted) return;
+			await send(rows, cwd, { ...native, launches, env, signal,
+				current: () => live === owner && current(owner.ctx) === owner });
+		});
+	}
+	const offChild = pi.events.on(CHILD_METRICS_EVENT, value => {
+		try {
+			const owner = live && current(live.ctx);
+			const event = snapshotChildEvent(value);
+			if (!owner || !event || event.parentSessionId !== owner.id || event.launchedAt < owner.started
+				|| owner.children.has(event.taskId) || owner.children.size >= 256) return;
+			owner.children.add(event.taskId); // Busy/failed completions stay consumed.
+			submit(owner, event.responses, [{ ...event.launch, evidence: "launch_configuration", launches: 1 }]);
+		} catch { /* No telemetry error enters the shared event bus. */ }
+	});
+	const offRevoke = pi.events.on(CHILD_METRICS_REVOKED, id => {
+		if (live?.id === id) {
+			live.attempt.dispose();
+			live.attempt = new RuntimeMetricsAttempt();
+			invalidate();
+		}
+	});
+	pi.on("session_start", (_event, ctx) => {
+		dispose();
+		if (!allows()) return;
+		const owner = { id: ctx.sessionManager.getSessionId(), started: now(), ctx,
+			attempt: new RuntimeMetricsAttempt(), seen: new WeakSet<object>(), children: new Set<string>(), catalog: false };
+		live = owner;
+		refreshCatalog(owner, { provider: "openai", modelId: "gpt-4o" });
+	});
+	pi.on("session_shutdown", (_event, ctx) => {
+		const teardown = () => { dispose(); offChild(); offRevoke(); };
+		const owner = live;
+		if (ctx.mode !== "print" || !owner) { teardown(); return; }
+		return owner.attempt.waitForSettled(shutdownWaitMs).finally(teardown);
+	});
+	pi.on("turn_start", () => { ambiguous = active; active = true; requestSeen = false; selection = undefined; });
+	pi.on("turn_end", () => { active = false; invalidate(); });
+	pi.on("agent_end", () => { active = false; invalidate(); });
+	pi.on("session_before_compact", invalidate);
+	pi.on("session_before_tree", invalidate);
+	pi.on("before_provider_request", (_event, ctx) => {
+		const owner = current(ctx);
+		if (!owner) return;
+		if (requestSeen) invalidate();
+		requestSeen = true;
+		if (!active || ambiguous) return;
+		let effort: FinalResponse["effort"] = "unavailable";
+		try { const value = pi.getThinkingLevel(); if (EFFORTS.includes(value)) effort = value; } catch { /* No evidence. */ }
+		selection = { selectedProvider: owner.catalog ? ctx.model?.provider as FinalResponse["provider"] ?? "unknown" : "unknown",
+			selectedModelId: owner.catalog && typeof ctx.model?.id === "string" && ctx.model.id.length <= 128 ? ctx.model.id : undefined, effort };
+	});
+	function token(value: unknown): TokenMeasurement {
+		return typeof value === "number" && Number.isSafeInteger(value) && value > 0 && value <= 1_000_000_000
+			? { state: "reported", value } : missing;
+	}
+	pi.on("message_end", (event, ctx) => {
+		try {
+			const owner = current(ctx);
+			const message = event.message;
+			if (!owner || message.role !== "assistant" || message.stopReason === "pending" || message.stopReason === "deferred"
+				|| owner.seen.has(message)) return;
+			owner.seen.add(message);
+			refreshCatalog(owner, { provider: "openai", modelId: "gpt-4o" });
+			const selected = active && !ambiguous ? selection : undefined;
+			submit(owner, [{ kind: "final_assistant_response", responseId: "0",
+				selectedProvider: selected?.selectedProvider ?? "unknown", selectedModelId: selected?.selectedModelId,
+				effort: selected?.effort ?? "unavailable",
+				executor: env.GENTLE_PI_AGENTS_CHILD === undefined ? "orchestrator" : "unknown",
+				agentClass: env.GENTLE_PI_AGENTS_CHILD === undefined ? ORCHESTRATOR_AGENT_CLASS : UNKNOWN_AGENT_CLASS,
+				observedModelId: message.model, responseModelId: message.responseModel,
+				providerThinkingLevel: EFFORTS.includes(message.providerThinkingLevel as FinalResponse["effort"])
+					? message.providerThinkingLevel as FinalResponse["effort"] : "unavailable",
+				provider: message.provider as FinalResponse["provider"], modelFamily: "unknown",
+				error: message.stopReason === "aborted" ? "aborted" : message.stopReason === "error" ? "unknown" : "none",
+				tokens: { input: token(message.usage?.input), output: token(message.usage?.output), cacheRead: token(message.usage?.cacheRead),
+					cacheWrite: token(message.usage?.cacheWrite), reasoning: token(message.usage?.reasoning), totalTokens: token(message.usage?.totalTokens) },
+				responseHeadersMs: missing, fullResponseMs: missing }]);
+			invalidate();
+		} catch { /* Provider hooks never expose telemetry failures. */ }
+	});
+}

package/extensions/sdd-init.ts

@@ -7,7 +7,7 @@ import {
 } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
 import { applySavedModelConfig } from "./gentle-ai.ts";
-import { ensureSddPreflight, installSddAssets } from "../lib/sdd-preflight.ts";
+import { ensureSddPreflight, installPackageAssets } from "../lib/sdd-preflight.ts";
 type ExtensionAPI = any;
 
 const CONFIG_REL_PATH = "openspec/config.yaml";
@@ -775,7 +775,7 @@ export default function (pi: ExtensionAPI) {
 		description:
 			"Auto-detect project stack and bootstrap openspec/config.yaml for SDD.",
 		handler: async (_args: unknown, ctx: any) => {
-			const prefs = await ensureSddPreflight(ctx, { pi, installAssets: (cwd) => installSddAssets(cwd, false), applyModelConfig: () => applySavedModelConfig(ctx) }, { promptFields: [] });
+			const prefs = await ensureSddPreflight(ctx, { pi, installAssets: (cwd) => installPackageAssets(cwd, true, ["sdd"]), applyModelConfig: () => applySavedModelConfig(ctx) }, { promptFields: [] });
 
 			const detection = detectProject(ctx.cwd);
 			const testSummary = detection.testCommand

package/extensions/startup-banner.ts

@@ -2,12 +2,10 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { VERSION } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import * as os from "node:os";
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
+import { execFile } from "node:child_process";
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-const execAsync = promisify(exec);
 const PI_AGENT_DIR = join(os.homedir(), ".pi", "agent");
 const PI_NPM_DIR = join(PI_AGENT_DIR, "npm", "node_modules");
 
@@ -527,7 +525,26 @@ async function countPackageExtensions(packages: unknown[]): Promise<number> {
   return count;
 }
 
+export function readGitBranch(cwd: string, run: typeof execFile = execFile): Promise<string> {
+  return new Promise((resolve) => {
+    run("git", ["-C", cwd, "branch", "--show-current"], {
+      encoding: "utf8",
+      shell: false,
+      windowsHide: true,
+    }, (error, stdout) => {
+      if (error) {
+        resolve("Not a git repo");
+        return;
+      }
+      const branch = String(stdout).trim();
+      resolve(branch ? `On branch ${branch}` : "Detached HEAD");
+    });
+  });
+}
+
 export default function (pi: ExtensionAPI) {
+  let disposeHeader = () => {};
+  pi.on("session_shutdown", () => disposeHeader());
   const notifyBannerConfig = (ctx: any, config: BannerConfig) => {
     ctx.ui.notify(
       [
@@ -597,6 +614,7 @@ export default function (pi: ExtensionAPI) {
   registerColorCommand("gentle:banner-color");
 
   pi.on("session_start", async (_event, ctx) => {
+    disposeHeader();
     if (!ctx.hasUI) return;
 
     // Si se está ejecutando un comando de CLI como "pi update" o "pi install", no mostramos la intro animada.
@@ -607,16 +625,13 @@ export default function (pi: ExtensionAPI) {
 
     if (currentIntroMode() === "skip") return;
 
-    // Fire-and-forget: el setup geométrico de cada letra corre en background
-    // para que la animación arranque en el primer frame sin bloquear el event loop.
-    void warmupLetterStrokes();
-
-    process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
-
+    // Pi has already started its renderer. Let setHeader schedule the paint;
+    // clearing stdout here would leave its previous-frame cache out of sync.
     const bannerConfig = await readBannerConfig();
     const palette = BANNER_PALETTES[bannerConfig.color];
     const roseBase = padLines(normalizeAscii(ROSE_LARGE_RAW));
     const logoBase = padLines(TEXT_LOGO);
+    void warmupLetterStrokes();
 
     let gitBranch = "Not a git repo";
     let mcpServersCount = 0;
@@ -632,12 +647,9 @@ export default function (pi: ExtensionAPI) {
     );
 
     setTimeout(() => {
-      execAsync(`git -C "${ctx.cwd}" branch --show-current`)
-        .then(({ stdout }) => {
-          const b = stdout.trim();
-          gitBranch = b ? `On branch ${b}` : "Detached HEAD";
-        })
-        .catch(() => {});
+      readGitBranch(ctx.cwd)
+        .then((branch) => { gitBranch = branch; })
+        .finally(() => refreshStats());
     }, 100);
 
     setTimeout(() => {
@@ -652,6 +664,7 @@ export default function (pi: ExtensionAPI) {
         } catch {
           mcpServersCount = 0;
         }
+        refreshStats();
       })();
     }, 150);
 
@@ -671,10 +684,12 @@ export default function (pi: ExtensionAPI) {
           extensionsCount = 0;
           packagesCount = 0;
         }
+        refreshStats();
       })();
     }, 200);
 
     let tick = 0;
+    let refreshStats = () => {};
     const state = {
       timer: null as NodeJS.Timeout | null,
       mode: currentIntroMode() as IntroMode,
@@ -683,6 +698,7 @@ export default function (pi: ExtensionAPI) {
     };
 
     const cleanup = () => {
+      refreshStats = () => {};
       if (state.timer) {
         clearInterval(state.timer);
         state.timer = null;
@@ -697,27 +713,21 @@ export default function (pi: ExtensionAPI) {
       }
     };
 
+    disposeHeader = cleanup;
     setTimeout(() => {
       ctx.ui.setHeader((tui, theme) => {
         if (state.timer) clearInterval(state.timer);
 
+        refreshStats = () => tui.requestRender();
         const animStart = Date.now();
-        const HARD_TIMEOUT_MS = 5000;
-
         state.timer = setInterval(() => {
           tick++;
-          const elapsed = Date.now() - animStart;
-          const finishedAnimation =
-            allStrokesReady() && tick > WRITING_END_TICK + 22;
-          if (finishedAnimation || elapsed > HARD_TIMEOUT_MS) {
-            cleanup();
-            return;
-          }
-          try {
-            tui.requestRender();
-          } catch {
-            cleanup();
+          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);
 
         // Grace period: pi-tui emite resizes transitorios mientras compone su layout inicial.
@@ -730,11 +740,7 @@ export default function (pi: ExtensionAPI) {
             const next = currentIntroMode();
             if (next === state.mode) return;
             state.mode = next;
-            if (next === "skip") {
-              cleanup();
-              process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
-              return;
-            }
+            // Pi owns removal in skip mode; keep listening for later expansion.
             try {
               tui.requestRender();
             } catch {
@@ -758,9 +764,9 @@ export default function (pi: ExtensionAPI) {
             const frame = Math.floor(tick / 2);
 
             const sideBySideMinWidth = roseBase.width + 3 + logoBase.width + 4;
-            const wideStatsMinWidth = 122;
             const horizontal =
               state.mode === "full" && bannerConfig.showRose && bannerConfig.showTextLogo && width >= sideBySideMinWidth;
+            const wideStatsMinWidth = 122;
             const wideStats = width >= wideStatsMinWidth;
 
             const b = new LayoutBuilder();
@@ -772,52 +778,27 @@ export default function (pi: ExtensionAPI) {
                 const logoLine = logoBase.lines[logoI];
                 b.addRow();
                 b.lines[b.lines.length - 1].push(
-                  ...buildPenLogoLine(
-                    logoLine,
-                    logoI,
-                    logoBase.lines.length,
-                    tick,
-                  ),
+                  ...buildPenLogoLine(logoLine, logoI, logoBase.lines.length, tick),
                 );
                 b.center(width);
               }
             } else if (horizontal) {
-              const rowCount = Math.max(
-                roseBase.lines.length,
-                logoBase.lines.length,
-              );
-              const roseOffset = Math.max(
-                0,
-                Math.floor((rowCount - roseBase.lines.length) / 2),
-              );
-              const logoOffset = Math.max(
-                0,
-                Math.floor((rowCount - logoBase.lines.length) / 2),
-              );
-
+              const rowCount = Math.max(roseBase.lines.length, logoBase.lines.length);
+              const roseOffset = Math.max(0, Math.floor((rowCount - roseBase.lines.length) / 2));
+              const logoOffset = Math.max(0, Math.floor((rowCount - logoBase.lines.length) / 2));
               for (let i = 0; i < rowCount; i++) {
                 const roseI = i - roseOffset;
                 const logoI = i - logoOffset;
-                const roseLine =
-                  roseI >= 0 && roseI < roseBase.lines.length
-                    ? roseBase.lines[roseI]
-                    : " ".repeat(roseBase.width);
-                const logoLine =
-                  logoI >= 0 && logoI < logoBase.lines.length
-                    ? logoBase.lines[logoI]
-                    : " ".repeat(logoBase.width);
-
+                const roseLine = roseI >= 0 && roseI < roseBase.lines.length
+                  ? roseBase.lines[roseI] : " ".repeat(roseBase.width);
+                const logoLine = logoI >= 0 && logoI < logoBase.lines.length
+                  ? logoBase.lines[logoI] : " ".repeat(logoBase.width);
                 b.addRow();
                 b.add("rose", roseLine);
                 b.add("none", "   ");
                 if (logoI >= 0 && logoI < logoBase.lines.length) {
                   b.lines[b.lines.length - 1].push(
-                    ...buildPenLogoLine(
-                      logoLine,
-                      logoI,
-                      logoBase.lines.length,
-                      tick,
-                    ),
+                    ...buildPenLogoLine(logoLine, logoI, logoBase.lines.length, tick),
                   );
                 } else {
                   b.add("none", " ".repeat(logoBase.width));
@@ -832,12 +813,7 @@ export default function (pi: ExtensionAPI) {
                   const logoLine = logoBase.lines[logoI];
                   b.addRow();
                   b.lines[b.lines.length - 1].push(
-                    ...buildPenLogoLine(
-                      logoLine,
-                      logoI,
-                      logoBase.lines.length,
-                      tick,
-                    ),
+                    ...buildPenLogoLine(logoLine, logoI, logoBase.lines.length, tick),
                   );
                   b.center(width);
                 }
@@ -1075,7 +1051,8 @@ export default function (pi: ExtensionAPI) {
 
             return out;
           },
-          invalidate() {
+          invalidate() {},
+          dispose() {
             cleanup();
           },
         };