gentle-pi 2.5.0 → 2.6.0

package/extensions/gentle-shell.ts

@@ -1,17 +1,20 @@
 import { CustomEditor, keyHint, type ExtensionAPI, type ExtensionContext, type KeybindingsManager } from "@earendil-works/pi-coding-agent";
 import type { EditorTheme, TUI } from "@earendil-works/pi-tui";
-import { spawnSync } from "node:child_process";
+import { execFile, spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import * as os from "node:os";
 import { join } from "node:path";
-import { renderShellBar, shellEnabled, type ShellBarModel, type ShellBarTheme } from "../lib/shell-bar.ts";
-import { CHANGE_STATUS, ChangesTracker, renderChangesWidget, type ChangedFile, type ChangesModel, type GitRunner, type LineCounter } from "../lib/shell-changes.ts";
-import { ChangesView } from "../lib/shell-changes-view.ts";
+import { renderShellBar, renderShellSidebarBar, shellEnabled, type ShellBarModel, type ShellBarTheme } from "../lib/shell-bar.ts";
+import { CHANGE_STATUS, WorktreeChangesTracker, renderChangesWidget, type ChangedFile, type ChangesModel, type GitRunner, type LineCounter, type WorktreeChanges } from "../lib/shell-changes.ts";
+import { WorktreeChangesView } from "../lib/shell-changes-view.ts";
+import { SessionWorktreeRegistry, SESSION_WORKTREE_CHANGED, resolveSessionWorktree, toolWorktreePath, worktreeGitEnvironment, type WorktreeResolver } from "../lib/session-worktree-registry.ts";
 import { CARD_TONE, renderCard, type Card, type CardTheme } from "../lib/shell-card.ts";
 import { GentleAiDevBinaryOverrideError, resolveGentleAiDevBinaryOverride } from "../lib/gentle-ai-binary.ts";
-import { framePromptLines, panelPainter, PROMPT_HINT, PROMPT_STATE, withPromptHint, type PromptState } from "../lib/shell-prompt.ts";
+import { framePromptLines, PROMPT_HINT, PROMPT_STATE, withPromptHint, type PromptState } from "../lib/shell-prompt.ts";
 import { accountIdFromToken, CODEX_PROVIDER, CODEX_USAGE_URL, parseCodexUsage, parseUsageHeaders, UsageStore, type ProviderUsage } from "../lib/shell-usage.ts";
 import { UsageView } from "../lib/shell-usage-view.ts";
+import { sidebarPart } from "../lib/shell-sidebar.ts";
+import { installSidebar, invalidateSidebar } from "../lib/shell-sidebar-layout.ts";
 
 // Gentle Shell: the visual layer gentle-pi puts on top of pi. It installs the
 // status bar, the petal prompt, the working-tree changes widget and overlay,
@@ -26,6 +29,7 @@ export interface ShellFooterData {
 
 interface ShellRenderHost {
 	requestRender(): void;
+	invalidateSidebar?(): void;
 }
 
 interface ShellBarComponent {
@@ -46,6 +50,8 @@ export interface ShellDeps {
 	fetch: typeof fetch;
 	now(): number;
 	devBinary(): DevBinaryNotice | undefined;
+	resolveWorktree: WorktreeResolver;
+	gitRunner(cwd: string): GitRunner;
 }
 
 function ambientDevBinary(): DevBinaryNotice | undefined {
@@ -58,7 +64,7 @@ function ambientDevBinary(): DevBinaryNotice | undefined {
 	}
 }
 
-const defaultShellDeps: ShellDeps = { fetch: (...args) => globalThis.fetch(...args), now: () => Date.now(), devBinary: ambientDevBinary };
+const defaultShellDeps: ShellDeps = { fetch: (...args) => globalThis.fetch(...args), now: () => Date.now(), devBinary: ambientDevBinary, resolveWorktree: resolveSessionWorktree, gitRunner: shellGitRunner };
 
 interface AssistantUsageEntry {
 	type: string;
@@ -121,7 +127,10 @@ export function createShellBarComponent(
 	dirty: () => number | undefined = () => undefined,
 	usage: () => ProviderUsage | undefined = () => undefined,
 ): ShellBarComponent {
-	const unsubscribe = footerData.onBranchChange(() => host.requestRender());
+	const unsubscribe = footerData.onBranchChange(() => {
+		host.invalidateSidebar?.();
+		host.requestRender();
+	});
 	return {
 		render(width: number) {
 			return renderShellBar(buildShellBarModel(pi, ctx, footerData, { dirty: dirty(), usage: usage() }), theme, width);
@@ -136,7 +145,6 @@ export function createShellBarComponent(
 interface PromptEditorDeps {
 	fg: (color: string, text: string) => string;
 	bold: (text: string) => string;
-	paint?: (line: string) => string;
 	requestRender(): void;
 	pending(): boolean;
 }
@@ -181,7 +189,6 @@ export class GentlePromptEditor extends CustomEditor {
 			borderColor: (text) => this.deps.fg(PROMPT_FRAME_ROLE, text),
 			fg: this.deps.fg,
 			bold: this.deps.bold,
-			paint: this.deps.paint,
 		});
 	}
 
@@ -202,7 +209,6 @@ function installPrompt(ctx: ExtensionContext, onCreated: (prompt: GentlePromptEd
 		const prompt = new GentlePromptEditor(tui, theme, keybindings, {
 			fg: (color, text) => ctx.ui.theme.fg(color as Parameters<typeof ctx.ui.theme.fg>[0], text),
 			bold: (text) => ctx.ui.theme.bold(text),
-			paint: panelPainter(ctx.ui.theme.getBgAnsi("customMessageBg")),
 			requestRender: () => tui.requestRender(),
 			pending: () => ctx.hasPendingMessages(),
 		});
@@ -220,11 +226,24 @@ const GIT_TIMEOUT_MS = 5000;
 const OVERLAY_HEIGHT_RATIO = 0.8;
 const OVERLAY_MIN_ROWS = 8;
 
-function gitRunner(pi: ExtensionAPI, cwd: string): GitRunner {
-	return async (args: string[]) => {
-		const result = await pi.exec("git", ["-C", cwd, ...args], { timeout: GIT_TIMEOUT_MS });
-		return { stdout: result.stdout, code: result.code };
-	};
+export function shellGitRunner(cwd: string, env: NodeJS.ProcessEnv = process.env, run: typeof execFile = execFile): GitRunner {
+	// Pi exec cannot replace the inherited environment. Use argv directly and
+	// a complete sanitized environment for discovery, status, and lazy diffs.
+	const childEnv = worktreeGitEnvironment(env);
+	return (args) => new Promise((resolve) => {
+		run("git", ["-C", cwd, ...args], {
+			env: childEnv,
+			encoding: "utf8",
+			shell: false,
+			windowsHide: true,
+			timeout: GIT_TIMEOUT_MS,
+			// Pi exec accumulates output without a maxBuffer cap. In particular,
+			// large porcelain inventories must not become partial successful scans.
+			maxBuffer: Infinity,
+		}, (error, stdout) => {
+			resolve({ stdout, code: error ? typeof error.code === "number" ? error.code : 1 : 0 });
+		});
+	});
 }
 
 function lineCounter(cwd: string): LineCounter {
@@ -247,13 +266,13 @@ export interface ExternalEditorHost {
 	requestRender(force?: boolean): void;
 }
 
-export function openInExternalEditor(host: ExternalEditorHost, path: string, env: NodeJS.ProcessEnv = process.env, spawn: typeof spawnSync = spawnSync): boolean {
+export function openInExternalEditor(host: ExternalEditorHost, path: string, env: NodeJS.ProcessEnv = process.env, spawn: typeof spawnSync = spawnSync, cwd?: string): boolean {
 	const command = env.VISUAL || env.EDITOR;
 	if (!command) return false;
 	const [editor, ...editorArgs] = command.split(" ");
 	host.stop();
 	try {
-		spawn(editor, [...editorArgs, path], { stdio: "inherit", shell: process.platform === "win32" });
+		spawn(editor, [...editorArgs, path], { cwd, stdio: "inherit", shell: process.platform === "win32" });
 	} finally {
 		host.start();
 		host.requestRender(true);
@@ -289,7 +308,8 @@ function changesFingerprint(model: ChangesModel): string {
 }
 
 interface OverlayDeps {
-	git: GitRunner;
+	git(root: string): GitRunner;
+	worktrees(): WorktreeChanges[];
 	refresh(): Promise<ChangesModel>;
 	apply(ctx: ExtensionContext, model: ChangesModel): void;
 	pollMs: number;
@@ -297,24 +317,26 @@ interface OverlayDeps {
 
 // While the overlay is open, git is polled so edits made outside pi (nvim,
 // another agent, a git checkout) show up without reopening it.
-async function showChangesOverlay(ctx: ExtensionContext, model: ChangesModel, deps: OverlayDeps): Promise<void> {
+async function showChangesOverlay(ctx: ExtensionContext, deps: OverlayDeps): Promise<void> {
 	let host: ExternalEditorHost | undefined;
-	let view: ChangesView | undefined;
-	const poll = setInterval(async () => {
+	let view: WorktreeChangesView | undefined;
+	const refresh = async () => {
 		const latest = await deps.refresh();
-		view?.update(latest);
+		view?.update(deps.worktrees());
 		deps.apply(ctx, latest);
-	}, deps.pollMs);
+	};
+	const poll = setInterval(() => void refresh(), deps.pollMs);
 	poll.unref();
 	try {
-		const chosen = await ctx.ui.custom<ChangedFile | null>(
+		const chosen = await ctx.ui.custom<{ root: string; file: ChangedFile } | null>(
 			(tui, theme, _keybindings, done) => {
 				host = tui;
-				view = new ChangesView(model, {
+				view = new WorktreeChangesView(deps.worktrees(), {
 					theme,
-					rows: Math.max(OVERLAY_MIN_ROWS, Math.floor(tui.terminal.rows * OVERLAY_HEIGHT_RATIO)),
-					loadDiff: (file) => loadFileDiff(deps.git, file),
-					onOpen: (file) => done(file),
+					rows: () => Math.max(OVERLAY_MIN_ROWS, Math.floor(tui.terminal.rows * OVERLAY_HEIGHT_RATIO)),
+					loadDiff: (root, file) => loadFileDiff(deps.git(root), file),
+					onOpen: (root, file) => done({ root, file }),
+					onRefresh: () => void refresh(),
 					onClose: () => done(null),
 					requestRender: () => tui.requestRender(),
 				});
@@ -323,9 +345,11 @@ async function showChangesOverlay(ctx: ExtensionContext, model: ChangesModel, de
 			{ overlay: true, overlayOptions: { width: "92%", anchor: "center" } },
 		);
 		if (!chosen || !host) return;
-		if (!openInExternalEditor(host, chosen.path)) ctx.ui.notify("No editor configured. Set $VISUAL or $EDITOR.", "warning");
+		if (!openInExternalEditor(host, chosen.file.path, process.env, spawnSync, chosen.root)) ctx.ui.notify("No editor configured. Set $VISUAL or $EDITOR.", "warning");
 	} finally {
 		clearInterval(poll);
+		view?.dispose();
+		view = undefined;
 	}
 }
 
@@ -336,11 +360,25 @@ function showChanges(ctx: ExtensionContext, model: ChangesModel): void {
 	}
 	ctx.ui.setWidget(
 		CHANGES_WIDGET_KEY,
-		(_tui, theme) => ({
+		(tui, theme) => sidebarPart(tui, "changes", {
 			render(width: number) {
 				return renderChangesWidget(model, theme, width);
 			},
 			invalidate() {},
+		}, {
+			render(width: number) {
+				const noun = model.files.length === 1 ? "file" : "files";
+				return renderCard({
+					title: "Changes",
+					tone: CARD_TONE.INFO,
+					body: [
+						`${model.files.length} ${noun} · ${theme.fg("success", `+${model.added}`)} ${theme.fg("error", `−${model.deleted}`)}`,
+						"",
+						theme.fg("muted", `/${CHANGES_COMMAND_NAME}`),
+					],
+				}, theme, width, { expanded: true });
+			},
+			invalidate() {},
 		}),
 		{ placement: "belowEditor" },
 	);
@@ -359,7 +397,6 @@ function messageText(content: string | Array<{ type: string; text?: string }>):
 interface CardComponentOptions {
 	expanded: boolean;
 	hint?: string;
-	paint?: (line: string) => string;
 }
 
 function cardComponent(card: Card, theme: CardTheme, options: CardComponentOptions) {
@@ -429,12 +466,14 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 		const fetched = await fetchCodexUsage(token, deps.fetch, deps.now());
 		if (!fetched) return;
 		usage.record(fetched);
+		renderHost?.invalidateSidebar?.();
 		renderHost?.requestRender();
 	};
 	pi.on("after_provider_response", (event) => {
 		const parsed = parseUsageHeaders(event.headers, deps.now());
 		if (!parsed) return;
 		usage.record(parsed);
+		renderHost?.invalidateSidebar?.();
 		renderHost?.requestRender();
 	});
 	pi.registerMessageRenderer(REVIEW_PREFLIGHT_TYPE, (message, options, theme) => {
@@ -461,7 +500,10 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 		},
 	});
 	let prompt: GentlePromptEditor | undefined;
-	let changes: ChangesTracker | undefined;
+	let changes: WorktreeChangesTracker | undefined;
+	let registry: SessionWorktreeRegistry | undefined;
+	let currentContext: ExtensionContext | undefined;
+	const pendingTools = new Map<string, { sessionId: string; path?: string }>();
 	let watch: NodeJS.Timeout | undefined;
 	let shown = "";
 	const applyChanges = (ctx: ExtensionContext, model: ChangesModel) => {
@@ -471,20 +513,59 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 		showChanges(ctx, model);
 	};
 	const refreshChanges = async (ctx: ExtensionContext) => {
-		if (!changes || !ctx.hasUI) return;
-		applyChanges(ctx, await changes.refresh());
+		const tracker = changes;
+		if (!tracker || !ctx.hasUI || registry?.sessionId !== ctx.sessionManager.getSessionId()) return;
+		const model = await tracker.refresh();
+		if (changes === tracker) applyChanges(ctx, model);
 	};
 	const stopWatch = () => {
 		if (watch) clearInterval(watch);
 		watch = undefined;
 	};
+	const unsubscribeWorktrees = pi.events.on(SESSION_WORKTREE_CHANGED, (data) => {
+		if (!currentContext || !registry || (data as { sessionId?: string } | undefined)?.sessionId !== registry.sessionId) return;
+		void refreshChanges(currentContext);
+	});
+	pi.registerTool({
+		name: "session_worktree_register",
+		renderShell: "self",
+		label: "Register session worktree",
+		description: "Register a worktree used by this session, including earlier work or opaque shell use. Only the same Git clone is accepted. Shows ALL dirty files in that root, including preexisting and untracked files; never infers roots from shell commands or prose.",
+		parameters: { type: "object", required: ["path"], additionalProperties: false, properties: { path: { type: "string", description: "Worktree path to include in this session." } } } as never,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			if (!registry || registry.sessionId !== ctx.sessionManager.getSessionId()) throw new Error("No active session worktree registry.");
+			const root = registry.register((params as { path: string }).path, "explicit");
+			await refreshChanges(ctx);
+			return { content: [{ type: "text", text: `Registered session worktree: ${root}` }], details: { root, sessionId: registry.sessionId } };
+		},
+	});
 	pi.on("session_start", async (_event, ctx) => {
+		stopWatch();
+		registry?.close();
+		pendingTools.clear();
+		currentContext = ctx;
+		changes = undefined;
+		registry = new SessionWorktreeRegistry(pi, ctx.sessionManager, ctx.cwd, deps.resolveWorktree);
+		registry.start();
+		const sessionRegistry = registry;
 		if (!ctx.hasUI) return;
-		changes = new ChangesTracker(gitRunner(pi, ctx.cwd), lineCounter(ctx.cwd));
+		changes = new WorktreeChangesTracker(deps.gitRunner(ctx.cwd), deps.gitRunner, lineCounter, () => sessionRegistry.roots());
 		const tracker = changes;
 		ctx.ui.setFooter((tui, theme, footerData) => {
-			renderHost = tui;
-			return createShellBarComponent(pi, ctx, tui, theme, footerData, () => tracker.model.files.length, () => usage.get(ctx.model?.provider ?? ""));
+			renderHost = { requestRender: () => tui.requestRender(), invalidateSidebar: () => invalidateSidebar(tui) };
+			const bottom = createShellBarComponent(pi, ctx, renderHost, theme, footerData, () => tracker.model.files.length, () => usage.get(ctx.model?.provider ?? ""));
+			// The Status card paints live session state that no event re-registers a
+			// part for: model, effort, context, cost, session name and extension
+			// statuses. The digest is what keeps the fullscreen memo honest, and it
+			// rebuilds the model exactly as the narrow bottom bar does every frame.
+			const footerModel = () => buildShellBarModel(pi, ctx, footerData, { dirty: tracker.model.files.length, usage: usage.get(ctx.model?.provider ?? "") });
+			const part = sidebarPart(tui, "footer", bottom, {
+				digest: () => JSON.stringify(footerModel()),
+				render: (width) => renderShellSidebarBar(footerModel(), theme, width),
+				invalidate() {},
+			});
+			const uninstall = installSidebar(tui, theme);
+			return { ...part, dispose() { uninstall(); part.dispose(); } };
 		});
 		void refreshUsage(ctx, true);
 		installPrompt(ctx, (created) => {
@@ -496,10 +577,11 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 		ctx.ui.setWidget(
 			DEV_BINARY_WIDGET_KEY,
 			notice
-				? (_tui, theme) => spaced(cardComponent(devBinaryCard(notice), theme, { expanded: true, paint: (line) => theme.bg("customMessageBg", line) }))
+				? (_tui, theme) => spaced(cardComponent(devBinaryCard(notice), theme, { expanded: true }))
 				: undefined,
 		);
 		await tracker.start();
+		if (changes !== tracker) return;
 		shown = "";
 		applyChanges(ctx, tracker.model);
 		stopWatch();
@@ -509,7 +591,15 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 			watch.unref();
 		}
 	});
-	pi.on("session_shutdown", () => stopWatch());
+	pi.on("session_shutdown", () => {
+		stopWatch();
+		registry?.close();
+		registry = undefined;
+		changes = undefined;
+		currentContext = undefined;
+		pendingTools.clear();
+		unsubscribeWorktrees();
+	});
 	const openChanges = async (ctx: ExtensionContext) => {
 		if (!changes) return;
 		const tracker = changes;
@@ -518,10 +608,10 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 			ctx.ui.notify("No changes in the working tree.", "info");
 			return;
 		}
-		await showChangesOverlay(ctx, model, { git: gitRunner(pi, ctx.cwd), refresh: () => tracker.refresh(), apply: applyChanges, pollMs: changesPollMs(env) });
+		await showChangesOverlay(ctx, { git: deps.gitRunner, worktrees: () => tracker.worktrees, refresh: () => tracker.refresh(), apply: applyChanges, pollMs: changesPollMs(env) });
 	};
 	pi.registerCommand(CHANGES_COMMAND_NAME, {
-		description: "Show the working tree changes against HEAD, with diffs. Press o to open a file in $EDITOR.",
+		description: "Browse this session's registered dirty worktrees and their changes against HEAD. Press o on a file to open $EDITOR.",
 		handler: async (_args, ctx) => openChanges(ctx),
 	});
 	const shortcut = changesShortcut(env);
@@ -541,7 +631,20 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 		await refreshChanges(ctx);
 		void refreshUsage(ctx, false);
 	});
-	pi.on("tool_execution_end", async (_event, ctx) => {
+	pi.on("tool_execution_start", (event, ctx) => {
+		pendingTools.set(event.toolCallId, { sessionId: ctx.sessionManager.getSessionId() });
+	});
+	pi.on("tool_result", (event, ctx) => {
+		const pending = pendingTools.get(event.toolCallId);
+		if (pending?.sessionId === ctx.sessionManager.getSessionId()) pending.path = toolWorktreePath(event.toolName, event.input);
+	});
+	pi.on("tool_execution_end", async (event, ctx) => {
+		const pending = pendingTools.get(event.toolCallId);
+		pendingTools.delete(event.toolCallId);
+		if (!event.isError && pending?.path !== undefined && pending.sessionId === registry?.sessionId && pending.sessionId === ctx.sessionManager.getSessionId()) {
+			try { registry.register(pending.path, `tool:${event.toolName}`); }
+			catch { /* Non-project paths and missing roots do not expand the registry. */ }
+		}
 		await refreshChanges(ctx);
 	});
 }

package/extensions/gentle-todo.ts

@@ -1,5 +1,8 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+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,
@@ -72,6 +75,7 @@ interface TodoSession {
 	clearOnNextTurn: boolean;
 	ui: ExtensionContext["ui"] | undefined;
 	host: { requestRender(): void } | undefined;
+	tui: TUI | undefined;
 }
 
 function sessionKey(ctx: ExtensionContext): string {
@@ -87,13 +91,48 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 		const key = sessionKey(ctx);
 		let current = sessions.get(key);
 		if (!current) {
-			current = { state: emptyTodo(), turn: 0, collapsed: false, clearOnNextTurn: false, ui: undefined, host: undefined };
+			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);
@@ -102,18 +141,14 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 		const snapshot = current;
 		current.ui.setWidget(WIDGET_KEY, (tui, theme) => {
 			snapshot.host = tui;
-			return {
-				render(width: number) {
-					const lines = renderTodoCard(snapshot.state, theme, width, { collapsed: snapshot.collapsed, staleTurns: staleTurns(snapshot.state, snapshot.turn), collapseKey });
-					return lines.length === 0 ? [] : [...lines, ""];
-				},
-				invalidate() {},
-			};
+			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",
@@ -139,6 +174,7 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 			if (!result.error) {
 				current.state = result.state;
 				current.clearOnNextTurn = false;
+				if (current.tui) invalidateSidebar(current.tui);
 			}
 			return {
 				content: [{ type: "text", text: result.text }],
@@ -151,9 +187,7 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 		pi.registerShortcut(collapseKey as Parameters<ExtensionAPI["registerShortcut"]>[0], {
 			description: "Collapse or expand the todo list",
 			handler: async (ctx) => {
-				const current = session(ctx);
-				current.collapsed = !current.collapsed;
-				current.host?.requestRender();
+				toggle(session(ctx));
 			},
 		});
 	}
@@ -176,6 +210,7 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 	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;

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);

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