gentle-pi 3.7.0 → 4.0.0

package/lib/codemode-renderer.ts

@@ -0,0 +1,185 @@
+import {
+	createCodemodeExtension,
+	keyHint,
+	type AgentToolResult,
+	type CodemodeToolDetails,
+	type ExtensionAPI,
+	type ExtensionFactory,
+	type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { getCapabilities, imageFallback, type Component } from "@earendil-works/pi-tui";
+import {
+	CARD_TONE, cardAwaitingResult, cardBodyRows, cardBottom, cardLine, cardRunningLine, cardTop, floatRows, markCardResult,
+	type CardRowContext, type CardTheme, type CardTone,
+} from "./shell-card.ts";
+import { sanitizeTerminalText, stripAnsi } from "./terminal-theme.ts";
+
+const CALL_STATUS = {
+	RUNNING: "running",
+	OK: "ok",
+	ERROR: "error",
+	CANCELLED: "cancelled",
+} as const satisfies Record<string, CodemodeToolDetails["calls"][number]["status"]>;
+const COLLAPSED_CALL_LIMIT = 8;
+
+interface ObservedCall {
+	name?: string;
+	status?: CodemodeToolDetails["calls"][number]["status"];
+	durationMs?: number;
+	error?: string;
+}
+
+function record(value: unknown): Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? value as Record<string, unknown> : {};
+}
+
+function safe(value: string): string {
+	return sanitizeTerminalText(value)
+		.replace(/[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "")
+		.replace(/\t/g, "    ");
+}
+
+function singleLine(value: string): string {
+	return safe(value).replace(/[\r\n\t]/g, " ");
+}
+
+function observedCalls(details: unknown): ObservedCall[] {
+	const calls = record(details).calls;
+	if (!Array.isArray(calls)) return [];
+	return calls.map((value) => {
+		const call = record(value);
+		return {
+			name: typeof call.name === "string" ? singleLine(call.name) : undefined,
+			status: Object.values(CALL_STATUS).includes(call.status as ObservedCall["status"] & string)
+				? call.status as ObservedCall["status"] : undefined,
+			durationMs: typeof call.durationMs === "number" && Number.isFinite(call.durationMs) && call.durationMs >= 0
+				? call.durationMs : undefined,
+			error: typeof call.error === "string" ? safe(call.error) : undefined,
+		};
+	});
+}
+
+function duration(ms: number | undefined): string {
+	if (ms === undefined) return "";
+	return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+
+function failed(call: ObservedCall): boolean {
+	return call.status === CALL_STATUS.ERROR || call.status === CALL_STATUS.CANCELLED || Boolean(call.error);
+}
+
+function childLine(call: ObservedCall, theme: CardTheme): string {
+	const status = call.status ?? "status unavailable";
+	const tone = failed(call) ? CARD_TONE.ERROR : call.status === CALL_STATUS.OK ? CARD_TONE.SUCCESS : CARD_TONE.WARNING;
+	const time = duration(call.durationMs);
+	// Arguments are deliberately never read; error payloads have their own bounded preview.
+	return `${theme.fg(tone, status)} · ${call.name || "name unavailable"}${time ? ` · ${time}` : ""}${call.error && call.status !== CALL_STATUS.ERROR ? " · error reported" : ""}`;
+}
+
+class CodemodeCard implements Component {
+	private readonly theme: CardTheme;
+	private readonly tone: CardTone;
+	private readonly body: (width: number) => string[];
+	private readonly top: boolean;
+	private readonly hint?: string;
+	// Whether the call card above this result already drew body rows (the script).
+	private readonly afterBody: boolean;
+	// The call card's render context: until a result exists, the call closes the frame.
+	private readonly row?: CardRowContext;
+
+	constructor(theme: CardTheme, tone: CardTone, body: (width: number) => string[], top: boolean, hint?: string, afterBody = false, row?: CardRowContext) {
+		this.theme = theme;
+		this.tone = tone;
+		this.body = body;
+		this.top = top;
+		this.hint = hint;
+		this.afterBody = afterBody;
+		this.row = row;
+	}
+
+	render(width: number): string[] {
+		const target = Math.max(0, Math.floor(width));
+		if (target === 0) return [];
+		const running = this.top && this.row !== undefined && cardAwaitingResult(this.row);
+		return floatRows(this.tone, this.theme, target, (inner) => ({
+			head: this.top ? [cardTop({ title: "Code", glyph: "λ", body: [], tone: this.tone }, this.theme, inner, this.hint)] : [],
+			body: running ? [...this.body(inner), cardRunningLine(this.tone, this.theme, inner)] : this.body(inner),
+			bottom: this.top && !running ? undefined : cardBottom(this.tone, this.theme, inner),
+			afterHeading: !this.top && !this.afterBody,
+		}));
+	}
+
+	invalidate(): void {}
+}
+
+/** Replace presentation only: execute, schema and every loadout/exposure field retain their references. */
+export function decorateCodemodeTool(tool: ToolDefinition): ToolDefinition {
+	return {
+		...tool,
+		renderShell: "self",
+		renderCall(args, theme, context) {
+			const tone = context.isError ? CARD_TONE.ERROR : context.isPartial ? CARD_TONE.WARNING : CARD_TONE.INFO;
+			const code = record(args).code;
+			const rows = context.expanded && typeof code === "string" ? [safe(code)] : [];
+			const hint = stripAnsi(keyHint("app.tools.expand", context.expanded ? "to collapse" : "to expand"));
+			return new CodemodeCard(theme, tone, (width) => cardBodyRows(rows, tone, theme, width, { expanded: true }), true, hint, false, context);
+		},
+		renderResult(result, options, theme, context) {
+			markCardResult(context?.state);
+			const calls = observedCalls(result.details);
+			const isError = context.isError || record(result).isError === true;
+			const failures = calls.filter(failed).length;
+			const tone = isError || failures > 0 ? CARD_TONE.ERROR : options.isPartial ? CARD_TONE.WARNING : CARD_TONE.INFO;
+			const shown = options.expanded ? calls : calls.slice(0, COLLAPSED_CALL_LIMIT);
+			const output = textOutput(result, context.showImages).flatMap((text) => {
+				const rows = text.split("\n");
+				// Pi prefixes final script output with status/wall-time bookkeeping.
+				// Keep it in expansion, but spend the collapsed budget on the payload.
+				const marker = rows.indexOf("Output:");
+				return !options.expanded && /^Script (?:completed|failed)/.test(rows[0] ?? "") && marker >= 0
+					? rows.slice(marker + 1) : rows;
+			});
+			const path = record(result.details).fullOutputPath;
+			// Mirrors renderCall: an expanded call shows the script as its body.
+			const callHasBody = options.expanded && typeof record(context?.args).code === "string";
+			return new CodemodeCard(theme, tone, (width) => {
+				const rows = shown.flatMap((call) => [
+					childLine(call, theme),
+					...(options.expanded && call.error ? [theme.fg("error", call.error)] : []),
+				]);
+				if (shown.length < calls.length) rows.push(theme.fg("muted", `${failures} errors/cancellations reported · ${calls.length - shown.length} more calls · expand to inspect`));
+				if (isError) rows.push(theme.fg("error", "Script failed"));
+				if (calls.length === 0) rows.push(theme.fg("muted", "No observed child calls"));
+				// Each child gets one collapsed physical row, preserving the observed order.
+				const body = options.expanded
+					? cardBodyRows(rows, tone, theme, width, { expanded: true })
+					: rows.map((row) => cardLine(row, tone, theme, width));
+				if (!options.expanded) {
+					const errors = calls.filter((call) => call.error).map((call) => `${call.name || "name unavailable"}: ${call.error}`);
+					body.push(...cardBodyRows(errors.map((error) => theme.fg("error", error)), tone, theme, width, { expanded: false, previewRows: 2 }));
+				}
+				body.push(...cardBodyRows(output.filter((row) => options.expanded || row.trim().length > 0).map((row) => theme.fg(isError ? "error" : "toolOutput", row)), tone, theme, width, { expanded: options.expanded, previewRows: 3 }));
+				if (typeof path === "string") body.push(...cardBodyRows([theme.fg("muted", `Full output: ${safe(path)}`)], tone, theme, width, { expanded: options.expanded, previewRows: 1 }));
+				return body;
+			}, false, undefined, callHasBody);
+		},
+	};
+}
+
+function textOutput(result: AgentToolResult<unknown>, showImages: boolean): string[] {
+	const showImageFallback = !getCapabilities().images || !showImages;
+	return result.content.flatMap((item) => item.type === "text" ? [safe(item.text)]
+		: item.type === "image" && showImageFallback ? [imageFallback(safe(item.mimeType))] : []);
+}
+
+/** Run the public factory once, intercepting only its registration; all other API access passes through. */
+export function registerCompactCodemode(pi: ExtensionAPI, factory: ExtensionFactory = createCodemodeExtension()): ReturnType<ExtensionFactory> {
+	const decoratedAPI = new Proxy(pi, {
+		get(target, property, receiver) {
+			if (property === "registerTool") return (tool: ToolDefinition) => pi.registerTool(tool.name === "codemode" ? decorateCodemodeTool(tool) : tool);
+			return Reflect.get(target, property, receiver);
+		},
+	});
+	return factory(decoratedAPI);
+}

package/lib/command-palette-catalog.ts

@@ -26,7 +26,9 @@ 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:customize", label: "Visual customization" },
 			{ command: "gentle:animations", label: "Animation mode" },
+			{ command: "gentle:vim", label: "Vim opt-in · Pi slash commands" },
 			{ command: "gentle:telemetry", label: "Telemetry" },
 			{ command: "gentle:banner", label: "Startup banner" },
 			{ command: "gentle:banner-color", label: "Banner color" },
@@ -38,6 +40,7 @@ export const COMMAND_PALETTE_CATALOG: readonly CommandPaletteCatalogGroup[] = [
 	{
 		title: "Session",
 		items: [
+			{ command: "gentle:yolo", label: "🚀 YOLO 🔥 session permission" },
 			{ command: "gentle:changes", label: "Browse captured changes" },
 			{ command: "gentle:agents", label: "Subagents" },
 			{ command: "gentle:usage", label: "Subscription usage" },
@@ -51,15 +54,6 @@ export const COMMAND_PALETTE_CATALOG: readonly CommandPaletteCatalogGroup[] = [
 			{ command: "gentle:doctor", label: "Doctor" },
 		],
 	},
-	{
-		title: "SDD",
-		items: [
-			{ command: "gentle:sdd-preflight", label: "SDD preflight" },
-			{ command: "gentle-sdd-status", label: "SDD status" },
-			{ command: "gentle-sdd-continue", label: "SDD continue" },
-			{ command: "gentle-sdd-init", label: "SDD init" },
-		],
-	},
 	{
 		title: "Skills",
 		items: [{ command: "skill-registry:refresh", label: "Refresh skill registry" }],

package/lib/command-palette.ts

@@ -97,7 +97,30 @@ const TONE_COLOR: Record<Tone, string> = {
 };
 
 // Two border glyphs ("│ " and " │") plus the padding space on each side.
-const CARD_PADDING = 4;
+export const CARD_PADDING = 4;
+
+/** Commands card chrome shared with other fullscreen overlay panels. */
+export function renderPaletteCard(lines: string[], width: number, theme?: CommandPaletteTheme): string[] {
+	const innerWidth = Math.max(1, width - CARD_PADDING);
+	const border = (text: string) => theme ? theme.fg("border", text) : text;
+	const horizontal = "─".repeat(innerWidth + 2);
+	return [border(`╭${horizontal}╮`), ...lines.map((content) => {
+		const visible = visibleWidth(stripAnsi(content));
+		const fitted = visible > innerWidth ? truncateToWidth(content, innerWidth, "…", true) : content + " ".repeat(innerWidth - visible);
+		return `${border("│")} ${fitted} ${border("│")}`;
+	}), border(`╰${horizontal}╯`)];
+}
+
+export function renderPaletteSelection(label: string, width: number, focused: boolean, theme?: CommandPaletteTheme): string {
+	const safe = sanitizeTerminalText(label);
+	if (focused && theme?.bg) {
+		const row = truncateToWidth(`  ${safe}`, width, "…", true);
+		return theme.bg("selectedBg", row + " ".repeat(Math.max(0, width - visibleWidth(stripAnsi(row)))));
+	}
+	const prefix = focused ? (theme ? theme.fg("accent", "▸ ") : "▸ ") : "  ";
+	const text = truncateToWidth(safe, Math.max(0, width - 2), "…", true);
+	return prefix + (theme ? theme.fg("text", text) : text);
+}
 const CARD_BORDER_ROWS = 2;
 // Fixed content rows outside the grouped match list: header, query/search,
 // a blank row, a blank row before the footer, and the footer itself.
@@ -194,7 +217,7 @@ export class CommandPalette {
 	render(width: number): string[] {
 		const innerWidth = Math.max(1, width - CARD_PADDING);
 		const maxTotalLines = Math.max(MIN_TOTAL_ROWS, Math.floor(this.rowsFn() * HEIGHT_RATIO));
-		return this.renderCard(this.renderBody(innerWidth, maxTotalLines), innerWidth);
+		return renderPaletteCard(this.renderBody(innerWidth, maxTotalLines), width, this.theme);
 	}
 
 	/**
@@ -307,18 +330,6 @@ export class CommandPalette {
 		return `${left}${" ".repeat(gap)}${right}${" ".repeat(trailingPad)}`;
 	}
 
-	private renderCard(lines: string[], innerWidth: number): string[] {
-		const horizontal = "─".repeat(innerWidth + 2);
-		const border = (text: string) => this.renderText(text, "border");
-		return [border(`╭${horizontal}╮`), ...lines.map((content) => `${border("│")} ${this.fitStyledLine(content, innerWidth)} ${border("│")}`), border(`╰${horizontal}╯`)];
-	}
-
-	private fitStyledLine(content: string, width: number): string {
-		const visible = visibleWidth(stripAnsi(content));
-		if (visible > width) return truncateToWidth(content, Math.max(1, width), "…", true);
-		return `${content}${" ".repeat(Math.max(0, width - visible))}`;
-	}
-
 	private renderLine(text = "", width: number, tone?: Tone): string {
 		const safe = truncateToWidth(sanitizeTerminalText(text), Math.max(1, width), "…", true);
 		return tone ? this.renderText(safe, tone) : safe;

package/lib/destructive-command-guard.ts

@@ -0,0 +1,144 @@
+// Recognizable executable forms only. This is deliberately not a shell/SQL
+// interpreter or a sandbox: no expansion, script loading or remote inspection.
+const DESTRUCTION_KIND = { DATABASE: "database", FILESYSTEM: "filesystem", GIT: "git" } as const;
+type DestructionKind = (typeof DESTRUCTION_KIND)[keyof typeof DESTRUCTION_KIND];
+export interface DestructiveCommandMatch {
+	kind: DestructionKind;
+	triggerIndex: number;
+	hardDeny: boolean;
+}
+interface Token {
+	value: string;
+	raw: string;
+	operator: boolean;
+	index: number;
+}
+const separators = new Set([";", "&&", "||", "|", "&", "\n", "(", ")"]);
+
+/** Keep quoted arguments intact so harmless prose is never treated as a command. */
+function tokenize(command: string): Token[] {
+	const tokens: Token[] = [];
+	// Literal, named heredocs are data, not executable shell segments.
+	command = command.replace(/<<-?\s*(['"]?)([A-Za-z_]\w*)\1[^\n]*\n[\s\S]*?\n\2(?=\n|$)/g, (raw) => {
+		const headerLength = raw.indexOf("\n") + 1;
+		return raw.slice(0, headerLength) + " ".repeat(raw.length - headerLength);
+	});
+	const pattern = /(?:"(?:\\.|[^"\\])*"|'[^']*'|\\.|[^\s;&|()'"\\])+|&&|\|\||[;&|()\n]/g;
+	for (const match of command.matchAll(pattern)) {
+		const raw = match[0];
+		const value = raw.replace(/"((?:\\.|[^"\\])*)"|'([^']*)'|\\(.)/g,
+			(_raw, double: string | undefined, single: string | undefined, escaped: string | undefined) => {
+				if (double !== undefined) return double.replace(/\\(["\\$`\n])/g, (_escape, char: string) => char === "\n" ? "" : char);
+				return single ?? escaped ?? "";
+			});
+		// Only raw operators are boundaries; quoted/escaped operators are words.
+		tokens.push({ value, raw, operator: separators.has(raw), index: match.index });
+	}
+	return tokens;
+}
+const executable = (value: string) => value.split("/").at(-1) ?? value;
+
+function sqlDestroys(sql: string): boolean {
+	// Mask quoted identifiers as non-keyword atoms, and remove comments and
+	// strings. A table named "where" is not a predicate or a statement boundary.
+	const code = sql.replace(/--[^\n]*|\/\*[\s\S]*?\*\/|'(?:''|[^'])*'|"(?:""|[^"])*"|`(?:``|[^`])*`|\[(?:\]\]|[^\]])*\]/g,
+		(raw) => /^["`\[]/.test(raw) ? "identifier" : " ");
+	return code.split(";").some((statement) => {
+		if (/^\s*(?:DROP\s+(?:TABLE|DATABASE|SCHEMA|INDEX|VIEW)\b|TRUNCATE\s+(?:TABLE\s+)?\S)/i.test(statement)) return true;
+		if (!/^\s*DELETE\s+FROM\s+\S/i.test(statement)) return false;
+		return !/\bWHERE\b/i.test(statement) || /\bWHERE\s+(?:1\s*=\s*1|TRUE)\s*$/i.test(statement.trim());
+	});
+}
+
+export function recognizeDestructiveCommands(command: string, depth = 0): DestructiveCommandMatch[] {
+	if (depth > 4) return [];
+	const tokens = tokenize(command);
+	const matches: DestructiveCommandMatch[] = [];
+	let previous: Token[] = [];
+	let previousSeparator = "";
+	let start = 0;
+	for (let end = 0; end <= tokens.length; end++) {
+		if (end < tokens.length && !tokens[end].operator) continue;
+		const segment = tokens.slice(start, end);
+		let cursor = 0;
+		// Assignments and familiar executable wrappers preserve command position.
+		while (cursor < segment.length) {
+			const value = segment[cursor].value;
+			if (/^[A-Za-z_][A-Za-z_0-9]*=/.test(value)) {
+				cursor++;
+				continue;
+			}
+			const name = executable(value);
+			if (!["env", "sudo", "command", "exec", "nohup", "timeout", "xargs"].includes(name)) break;
+			const valueOptions: Record<string, readonly string[]> = {
+				env: ["-u", "--unset", "-C", "--chdir"],
+				sudo: ["-u", "-g", "-h", "-p", "-C", "--user", "--group", "--host", "--prompt", "--chdir"],
+				timeout: ["-s", "--signal", "-k", "--kill-after"],
+				xargs: ["-n", "-I", "-P", "--max-args", "--replace", "--max-procs"],
+			};
+			cursor++;
+			while (cursor < segment.length && segment[cursor].value.startsWith("-")) {
+				const flag = segment[cursor++].value;
+				if (flag === "--") break;
+				if (valueOptions[name]?.includes(flag)) cursor++;
+			}
+			if (name === "timeout") cursor++;
+		}
+		const head = segment[cursor];
+		const name = executable(head?.value ?? "");
+		const args = segment.slice(cursor + 1).map((token) => token.value);
+		const add = (kind: DestructionKind, hardDeny = false) => matches.push({ kind, hardDeny, triggerIndex: head.index });
+		if (["sh", "bash", "zsh", "dash"].includes(name)) {
+			const flag = args.findIndex((arg) => /^-[a-z]*c[a-z]*$/.test(arg));
+			if (flag >= 0 && args[flag + 1]) {
+				// Nested offsets use the enclosing executable, which is stable even
+				// when quote removal changes the payload's byte positions.
+				matches.push(...recognizeDestructiveCommands(args[flag + 1], depth + 1).map((match) => ({ ...match, triggerIndex: head.index })));
+			}
+		}
+		if (["psql", "mysql", "mariadb", "sqlite3"].includes(name)) {
+			const payloads = args.map((arg) => arg.replace(/^(?:--command|--execute)=/, ""));
+			const heredoc = command.slice(head.index).match(/^[^\n]*<<-?\s*(['"]?)([A-Za-z_]\w*)\1[^\n]*\n([\s\S]*?)\n\2(?=\n|$)/);
+			if (heredoc) payloads.push(heredoc[3]);
+			if (previousSeparator === "|" && ["echo", "printf"].includes(executable(previous[0]?.value ?? ""))) {
+				payloads.push(previous.slice(1).map((token) => token.value).join(" ").replace(/^%s\s*/, ""));
+			}
+			if (payloads.some(sqlDestroys)) add(DESTRUCTION_KIND.DATABASE);
+		}
+		if (name === "rm" && args.some((arg) => /^-[^-]*[rR]/.test(arg) || arg === "--recursive")) {
+			const rootTarget = args.some((arg) => /^(?:\/(?:\*+)?$|\.{1,2}\/?$|~(?:\/|$)|\$\{?HOME\}?(?:\/|$))/.test(arg));
+			add(DESTRUCTION_KIND.FILESYSTEM, rootTarget);
+		}
+		if (name === "find") {
+			if (args.includes("-delete")) add(DESTRUCTION_KIND.FILESYSTEM);
+			for (let execIndex = 0; execIndex < args.length; execIndex++) {
+				if (!["-exec", "-execdir"].includes(args[execIndex])) continue;
+				const invocation = segment.slice(cursor + execIndex + 2);
+				const terminator = invocation.findIndex((arg) => arg.value === ";" || arg.value === "+");
+				const nested = (terminator < 0 ? invocation : invocation.slice(0, terminator)).map((arg) => arg.raw).join(" ");
+				matches.push(...recognizeDestructiveCommands(nested, depth + 1).map((match) => ({ ...match, triggerIndex: head.index })));
+				if (terminator < 0) break;
+				execIndex += terminator + 1;
+			}
+		}
+		if (name === "git") {
+			let index = 0;
+			while (args[index]?.startsWith("-")) {
+				const flag = args[index++];
+				if (["-C", "-c", "--git-dir", "--work-tree", "--namespace"].includes(flag)) index++;
+			}
+			const action = args[index];
+			const flags = args.slice(index + 1);
+			const force = flags.some((arg) => /^--force(?:-with-lease|=|$)/.test(arg) || /^-[^-]*f/.test(arg));
+			const hard = (action === "reset" && flags.includes("--hard")) || (action === "clean" && force) || (action === "push" && force);
+			const branchDelete = action === "branch" && (flags.some((arg) => /^-[^-]*D/.test(arg)) || (force && flags.some((arg) => arg === "--delete" || /^-[^-]*d/.test(arg))));
+			if (hard || branchDelete || ["reset", "clean", "restore", "rebase"].includes(action) ||
+				(action === "checkout" && (force || flags.includes("--"))) ||
+				(action === "stash" && ["drop", "clear"].includes(flags[0]))) add(DESTRUCTION_KIND.GIT, hard);
+		}
+		previous = segment;
+		previousSeparator = tokens[end]?.value ?? "";
+		start = end + 1;
+	}
+	return matches;
+}

package/lib/gentle-ai-elapsed-store.ts

@@ -0,0 +1,87 @@
+export const GENTLE_AI_TIMING_ENTRY = "gentle-ai-elapsed-timing/v1";
+
+export interface GentleAiTimingRecord {
+	toolCallId: string;
+	startedAt: number;
+	endedAt?: number;
+}
+
+/** What the renderer consumes: a read-only lookup keyed by pi's stable toolCallId. */
+export interface GentleAiTimingLookup {
+	lookup(toolCallId: string): GentleAiTimingRecord | undefined;
+}
+
+export interface GentleAiTimingEntry {
+	type: string;
+	customType?: string;
+	data?: unknown;
+}
+
+export interface GentleAiTimingSessionReader {
+	getEntries(): readonly GentleAiTimingEntry[];
+}
+
+export interface GentleAiTimingAppendHost {
+	appendEntry(type: string, data?: unknown): void;
+}
+
+export function parseGentleAiTimingData(data: unknown): GentleAiTimingRecord | undefined {
+	if (!data || typeof data !== "object" || Array.isArray(data)) return undefined;
+	const record = data as { toolCallId?: unknown; startedAt?: unknown; endedAt?: unknown };
+	if (typeof record.toolCallId !== "string" || record.toolCallId.length === 0) return undefined;
+	if (typeof record.startedAt !== "number" || !Number.isFinite(record.startedAt)) return undefined;
+	// Local capture + a plain typeof guard: under non-strict null checks a
+	// `x === undefined` condition leaves `unknown` unnarrowed, so the finite-
+	// number branch must be decided by typeof before the value is used.
+	const endedAt = record.endedAt;
+	if (endedAt !== undefined) {
+		if (typeof endedAt !== "number" || !Number.isFinite(endedAt)) return undefined;
+		return { toolCallId: record.toolCallId, startedAt: record.startedAt, endedAt };
+	}
+	return { toolCallId: record.toolCallId, startedAt: record.startedAt };
+}
+
+/** Replay: entries are append-only, so the last timing entry per toolCallId wins. */
+export function readGentleAiTimings(entries: readonly GentleAiTimingEntry[]): Map<string, GentleAiTimingRecord> {
+	const timings = new Map<string, GentleAiTimingRecord>();
+	for (const entry of entries) {
+		if (entry.type !== "custom" || entry.customType !== GENTLE_AI_TIMING_ENTRY) continue;
+		const record = parseGentleAiTimingData(entry.data);
+		if (record) timings.set(record.toolCallId, record);
+	}
+	return timings;
+}
+
+// No global store: the owning extension binds its own Pi API, and reading all
+// entries also catches a launch that happened while the shell was absent.
+export class GentleAiElapsedTimingLedger implements GentleAiTimingLookup {
+	private readonly recorded = new Set<string>();
+	private readonly session: GentleAiTimingSessionReader;
+	private readonly host?: GentleAiTimingAppendHost;
+
+	constructor(session: GentleAiTimingSessionReader, host?: GentleAiTimingAppendHost) {
+		this.session = session;
+		this.host = host;
+	}
+
+	lookup(toolCallId: string): GentleAiTimingRecord | undefined {
+		return readGentleAiTimings(this.session.getEntries()).get(toolCallId);
+	}
+
+	recordStart(toolCallId: string, startedAt: number): void {
+		this.append(`${toolCallId}:start`, { toolCallId, startedAt });
+	}
+
+	recordEnd(toolCallId: string, endedAt: number): void {
+		const startedAt = this.lookup(toolCallId)?.startedAt;
+		// A terminal without a durable start has no honest duration to freeze.
+		if (startedAt === undefined) return;
+		this.append(`${toolCallId}:end`, { toolCallId, startedAt, endedAt });
+	}
+
+	private append(stage: string, data: GentleAiTimingRecord): void {
+		if (this.recorded.has(stage)) return;
+		this.host?.appendEntry(GENTLE_AI_TIMING_ENTRY, data);
+		this.recorded.add(stage);
+	}
+}