gentle-pi 3.7.0 → 4.0.0

package/extensions/nan-provider.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createNanProviderConfig } from "../lib/nan-provider.ts";
+
+export default function registerNanProvider(pi: ExtensionAPI): void {
+	pi.registerProvider(createNanProviderConfig());
+}

package/extensions/quiet-tools.ts

@@ -1,6 +1,5 @@
-import type { AgentToolResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, ExtensionAPI, ExtensionFactory, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import {
-	createBashTool,
 	createEditTool,
 	createFindTool,
 	createGrepTool,
@@ -13,11 +12,18 @@ import { Text, type Component } from "@earendil-works/pi-tui";
 import { homedir } from "node:os";
 import { isAbsolute } from "node:path";
 import { resolveGentleAiDevBinaryOverride, type GentleAiDevBinaryOverride } from "../lib/gentle-ai-binary.ts";
+import { GentleAiElapsedTimingLedger } from "../lib/gentle-ai-elapsed-store.ts";
 import { quietToolsEnabled } from "../lib/quiet-tools-config.ts";
+import { registerCompactCodemode } from "../lib/codemode-renderer.ts";
 import { getGentleAiRenderState, renderGentleAiLifecycleCall, renderGentleAiResult, type GentleAiRenderContext } from "../lib/gentle-ai-renderer.ts";
-import { sanitizeTerminalText } from "../lib/terminal-theme.ts";
+import {
+	CARD_TONE, cardAwaitingResult, cardBottom, cardInnerWidth, cardLine, cardRunningLine, cardTopRows, floatRows, markCardResult,
+	type CardRowContext, type CardTheme,
+} from "../lib/shell-card.ts";
+import { sanitizeTerminalText, stripAnsi } from "../lib/terminal-theme.ts";
 
 type QuietToolName = "read" | "bash" | "grep" | "find" | "ls" | "edit" | "write";
+type RegisteredToolName = Exclude<QuietToolName, "bash">;
 type ThemeLike = {
 	bold(value: string): string;
 	fg(color: string, value: string): string;
@@ -25,13 +31,23 @@ type ThemeLike = {
 
 const TOOL_CREATORS = {
 	read: createReadToolDefinition,
-	bash: createBashTool,
 	grep: createGrepTool,
 	find: createFindTool,
 	ls: createLsTool,
 	edit: createEditTool,
 	write: createWriteTool,
-} satisfies Record<QuietToolName, (cwd: string) => any>;
+} satisfies Record<RegisteredToolName, (cwd: string) => any>;
+
+// Caller-owned identities: shared notices and lower widgets retain their glyphs.
+const TOOL_GLYPH = {
+	read: "≡",
+	bash: "$",
+	grep: "⌕",
+	find: "⌖",
+	ls: "☷",
+	edit: "✎",
+	write: "+",
+} as const satisfies Record<QuietToolName, string>;
 
 const COLLAPSED_COUNT_LABELS: Partial<Record<QuietToolName, string>> = {
 	grep: "matches",
@@ -49,17 +65,17 @@ const EMPTY_RESULT_MESSAGES: Partial<Record<QuietToolName, string[]>> = {
 	bash: ["(no output)"],
 };
 
-const toolCache = new Map<string, Record<QuietToolName, any>>();
+const toolCache = new Map<string, Record<RegisteredToolName, any>>();
 
-function createBuiltInTools(cwd: string): Record<QuietToolName, any> {
+function createBuiltInTools(cwd: string): Record<RegisteredToolName, any> {
 	return Object.fromEntries(
-		(Object.entries(TOOL_CREATORS) as [QuietToolName, (cwd: string) => any][]).map(
+		(Object.entries(TOOL_CREATORS) as [RegisteredToolName, (cwd: string) => any][]).map(
 			([name, createTool]) => [name, createTool(cwd)],
 		),
-	) as Record<QuietToolName, any>;
+	) as Record<RegisteredToolName, any>;
 }
 
-function getBuiltInTools(cwd: string): Record<QuietToolName, any> {
+function getBuiltInTools(cwd: string): Record<RegisteredToolName, any> {
 	let tools = toolCache.get(cwd);
 	if (!tools) {
 		tools = createBuiltInTools(cwd);
@@ -167,7 +183,7 @@ function isGitCommand(args: Record<string, unknown> | undefined): boolean {
 	return /^(?:env\s+\S+=\S+\s+|command\s+|\w+=\S+\s+)*git(?:\s|$)/.test(command);
 }
 
-export type GentleAiRoutineCommand = "sdd-status" | "sdd-continue" | "sdd-attempt" | "review";
+export type GentleAiRoutineCommand = "review";
 
 const GENTLE_AI_EXECUTABLE = String.raw`(?:gentle-ai(?:\.exe)?|(?:\.{1,2}[\\/]|(?:[A-Za-z]:)?(?:[\\/][^\\/\r\n]+)*[\\/])\.gentle-ai[\\/]v\d+\.\d+\.\d+[\\/]gentle-ai(?:\.exe)?)`;
 const GENTLE_AI_COMMAND_ARGUMENTS = new RegExp(`^${GENTLE_AI_EXECUTABLE}$`);
@@ -238,8 +254,6 @@ function shellTokens(command: string): ShellTokenization {
 function isAssignment(token: string): boolean {
 	return /^[A-Za-z_][A-Za-z0-9_]*=/.test(token);
 }
-const SDD_ATTEMPT_VERBS = new Set(["grant"]);
-
 const REVIEW_DIRECT_OPERATIONS = new Set([
 	"capabilities",
 	"start",
@@ -304,22 +318,6 @@ function displayToken(token: string): string {
 	return token.replace(/-/g, " ");
 }
 
-function authorizationRootCount(tokens: string[]): number {
-	let count = 0;
-	for (let index = 0; index < tokens.length; index += 1) {
-		const token = tokens[index]!;
-		if (token === "--authorization-root") {
-			const value = tokens[index + 1];
-			if (value !== undefined && !value.startsWith("-")) count += 1;
-			continue;
-		}
-		if (token.startsWith("--authorization-root=") && token.slice("--authorization-root=".length).length > 0) {
-			count += 1;
-		}
-	}
-	return count;
-}
-
 function validateGate(tokens: string[]): string | undefined {
 	const gateFlag = tokens.findIndex((token) => token === "--gate" || token.startsWith("--gate="));
 	if (gateFlag < 0) return undefined;
@@ -332,7 +330,7 @@ function validateGate(tokens: string[]): string | undefined {
 /**
  * Matches only supported routine Gentle AI CLI calls, including bounded
  * package-local paths, not arbitrary shell output that merely mentions
- * gentle-ai. These commands otherwise emit machine-readable SDD/RDD data.
+ * gentle-ai. Review commands otherwise emit machine-readable RDD data.
  */
 export function isGentleAiDirectCommand(args: Record<string, unknown> | undefined, commandArguments = GENTLE_AI_COMMAND_ARGUMENTS): boolean {
 	return gentleAiCommandTokens(args, commandArguments) !== undefined;
@@ -341,24 +339,12 @@ export function isGentleAiDirectCommand(args: Record<string, unknown> | undefine
 export function gentleAiRoutineCommand(args: Record<string, unknown> | undefined, commandArguments = GENTLE_AI_COMMAND_ARGUMENTS): GentleAiRoutineCommand | undefined {
 	const tokens = gentleAiCommandTokens(args, commandArguments);
 	if (!tokens) return undefined;
-	if (tokens[0] === "sdd-status") return "sdd-status";
-	if (tokens[0] === "sdd-continue") return "sdd-continue";
-	if (tokens[0] === "sdd-attempt" && SDD_ATTEMPT_VERBS.has(tokens[1] ?? "")) return "sdd-attempt";
 	if (tokens[0] === "review") return "review";
 	return undefined;
 }
 
-function gentleAiOperationPathFrom(tokens: string[]): string {
-	if (tokens[0] === "sdd-status") return "sdd status";
-	if (tokens[0] === "sdd-continue") return "sdd continue";
-	if (tokens[0] === "sdd-attempt") {
-		const verb = tokens[1] ?? "";
-		if (!SDD_ATTEMPT_VERBS.has(verb)) return "sdd attempt";
-		const rootCount = authorizationRootCount(tokens);
-		return rootCount > 0
-			? `sdd attempt grant · ${rootCount} root${rootCount === 1 ? "" : "s"}`
-			: "sdd attempt grant";
-	}
+function gentleAiOperationPathFrom(tokens: string[]): string | undefined {
+	if (tokens[0]?.startsWith("sdd-")) return undefined;
 	if (tokens[0] === "version") return "version";
 	if (tokens[0] !== "review") return "command";
 
@@ -385,11 +371,6 @@ export function gentleAiOperationPath(args: Record<string, unknown> | undefined,
 	return tokens ? gentleAiOperationPathFrom(tokens) : undefined;
 }
 
-export function isGentleAiGrantCommand(args: Record<string, unknown> | undefined, commandArguments = GENTLE_AI_COMMAND_ARGUMENTS): boolean {
-	const tokens = gentleAiCommandTokens(args, commandArguments);
-	return tokens?.[0] === "sdd-attempt" && tokens[1] === "grant";
-}
-
 interface ToolResultFormatOptions {
 	expanded: boolean;
 	isError?: boolean;
@@ -501,7 +482,7 @@ function formatToolCall(toolName: QuietToolName, args: Record<string, unknown>,
 		case "bash": {
 			const command = safeText(asString(args.command, "..."));
 			const timeout = typeof args.timeout === "number" ? theme.fg("muted", ` (timeout ${args.timeout}s)`) : "";
-			return `${theme.fg("toolTitle", theme.bold(`$ ${command}`))}${timeout}`;
+			return `${theme.fg("toolTitle", theme.bold(`bash $ ${command}`))}${timeout}`;
 		}
 		case "grep": {
 			let text = `${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("accent", `/${safeText(asString(args.pattern))}/`)} in ${safeText(shortenPath(args.path) || ".")}`;
@@ -574,6 +555,78 @@ class BoundedRows implements Component {
 	invalidate(): void {}
 }
 
+// Tool card: every quiet tool call is a rounded petal card, like the Gentle AI
+// card, so the call and its output read as one block apart from assistant
+// prose. pi does not paint tool backgrounds for renderShell "self", so the
+// frame tone carries the status the painted Box would otherwise show. The call
+// owns the top rule; the result draws the sides and always closes the frame.
+// Until the first result exists, the call closes the frame itself.
+type ToolTone = typeof CARD_TONE.WARNING | typeof CARD_TONE.SUCCESS | typeof CARD_TONE.ERROR;
+
+function toolTone(pending: boolean, failed: boolean): ToolTone {
+	if (failed) return CARD_TONE.ERROR;
+	return pending ? CARD_TONE.WARNING : CARD_TONE.SUCCESS;
+}
+
+class ToolCardTop implements Component {
+	private readonly header: () => string;
+	private readonly glyph: string;
+	private readonly tone: ToolTone;
+	private readonly theme: CardTheme;
+	private readonly hint: string | undefined;
+	private readonly row: CardRowContext | undefined;
+
+	constructor(header: () => string, tone: ToolTone, theme: CardTheme, glyph: string, hint?: string, row?: CardRowContext) {
+		this.header = header;
+		this.glyph = glyph;
+		this.tone = tone;
+		this.theme = theme;
+		this.hint = hint;
+		this.row = row;
+	}
+
+	/** Renders `╭─ <icon> <call> ── <hint> ╮`, reserving applicable hint space before wrapping the call. A call that does not fit the rule (a long or multi-line command) continues on card rows below it, so every line of the command stays visible. */
+	render(width: number): string[] {
+		const target = Math.max(0, Math.floor(width));
+		if (target === 0) return [];
+		const running = this.row !== undefined && cardAwaitingResult(this.row);
+		return floatRows(this.tone, this.theme, target, (inner) => ({
+			head: cardTopRows({ title: this.header(), glyph: this.glyph, body: [], tone: this.tone }, this.theme, inner, this.hint),
+			body: running ? [cardRunningLine(this.tone, this.theme, inner)] : undefined,
+			bottom: running ? cardBottom(this.tone, this.theme, inner) : undefined,
+		}));
+	}
+
+	invalidate(): void {}
+}
+
+class ToolCardBody implements Component {
+	private readonly inner: () => Component;
+	private readonly tone: ToolTone;
+	private readonly theme: CardTheme;
+
+	constructor(inner: () => Component, tone: ToolTone, theme: CardTheme) {
+		this.inner = inner;
+		this.tone = tone;
+		this.theme = theme;
+	}
+
+	/** Renders the inner component between the card sides and closes the frame, even when the result has no rows. */
+	render(width: number): string[] {
+		const target = Math.max(0, Math.floor(width));
+		if (target === 0) return [];
+		return floatRows(this.tone, this.theme, target, (inner) => ({
+			body: this.inner().render(cardInnerWidth(inner)).map((line) => cardLine(line.trimEnd(), this.tone, this.theme, inner)),
+			bottom: cardBottom(this.tone, this.theme, inner),
+			afterHeading: true,
+		}));
+	}
+
+	invalidate(): void {
+		// Content is rebuilt with the current theme at render time.
+	}
+}
+
 function shouldRenderPreviewTail(
 	toolName: QuietToolName,
 	text: string,
@@ -596,13 +649,6 @@ function hasImageContent(result: AgentToolResult<unknown>): boolean {
 	return result.content.some((content) => content.type === "image");
 }
 
-function hasExpandableContent(toolName: QuietToolName, result: AgentToolResult<unknown>, text: string): boolean {
-	if (isEmptyResultMessage(toolName, text)) return false;
-	if (text.length > 0 || hasImageContent(result)) return true;
-	const diff = detailsRecord(result).diff;
-	return toolName === "edit" && typeof diff === "string" && diff.length > 0;
-}
-
 function sanitizedRenderContext(context: ToolRenderContextLike | undefined): ToolRenderContextLike {
 	if (!context) return { args: {} };
 	return {
@@ -639,17 +685,21 @@ function gentleAiRenderTransition(
 	return { directResult: false };
 }
 
-function registerQuietTool(pi: ExtensionAPI, toolName: QuietToolName, commandArguments: () => RegExp): void {
-	const registrationTool = getBuiltInTools(process.cwd())[toolName];
-	const officialRenderResult = registrationTool.renderResult;
+/** Rendering-only factory; Bash renderers are not attached to production native Bash. */
+export function createQuietToolRenderer(
+	toolName: QuietToolName,
+	resolveOverride: GentleAiDevBinaryOverrideResolver = () => undefined,
+	timing: () => GentleAiElapsedTimingLedger | undefined = () => undefined,
+	officialRenderResult?: ToolDefinition["renderResult"],
+): Pick<ToolDefinition, "renderShell" | "renderCall" | "renderResult"> {
+	const commandArguments = () => createGentleAiCommandArguments(resolveQuietToolsDevBinaryPath(resolveOverride));
+	const withElapsedTiming = (context: GentleAiRenderContext): GentleAiRenderContext => {
+		const ledger = timing();
+		return ledger ? { ...context, elapsedTiming: ledger } : context;
+	};
 
-	pi.registerTool({
-		...registrationTool,
+	return {
 		renderShell: "self",
-		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const runtimeTool = getBuiltInTools(ctx.cwd)[toolName];
-			return runtimeTool.execute(toolCallId, params, signal, onUpdate, ctx);
-		},
 		renderCall(args, theme, context) {
 			const callArgs = args as Record<string, unknown>;
 			const renderContext = sanitizedRenderContext(context as ToolRenderContextLike | undefined);
@@ -658,13 +708,18 @@ function registerQuietTool(pi: ExtensionAPI, toolName: QuietToolName, commandArg
 				: undefined;
 			if (operationPath) {
 				const detail = renderContext.expanded === true && typeof callArgs.command === "string" ? `$ ${callArgs.command}` : undefined;
-				return renderGentleAiLifecycleCall(operationPath, theme, renderContext as GentleAiRenderContext, detail);
+				return renderGentleAiLifecycleCall(operationPath, theme, withElapsedTiming(renderContext as GentleAiRenderContext), detail);
 			}
-			return new Text(formatToolCall(toolName, callArgs, theme), 0, 0);
+			const tone = toolTone(renderContext.isPartial !== false, renderContext.isError === true);
+			// Same place and wording as the Gentle AI card: the expand key rides the top rule once the call finished.
+			const finished = renderContext.isPartial === false && (renderContext.executionStarted === true || renderContext.isError === true);
+			const hint = finished ? stripAnsi(keyHint("app.tools.expand", renderContext.expanded === true ? "to collapse" : "to expand")) : undefined;
+			return new ToolCardTop(() => formatToolCall(toolName, callArgs, theme), tone, theme, TOOL_GLYPH[toolName], hint, renderContext);
 		},
 		/** 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;
+			markCardResult(renderContext?.state);
 			const cacheKey = typeof result === "object" && result !== null ? result : undefined;
 			const safeResult = sanitizedResult(result);
 			const text = safeText(extractTextContent(safeResult));
@@ -676,49 +731,86 @@ function registerQuietTool(pi: ExtensionAPI, toolName: QuietToolName, commandArg
 				{ result: true, isPartial: options.isPartial },
 			).directResult;
 			if (directResult) {
-				return renderGentleAiResult(safeResult, { expanded: options.expanded, isPartial: options.isPartial, isError }, theme, renderContext as GentleAiRenderContext | undefined);
+				return renderGentleAiResult(safeResult, { expanded: options.expanded, isPartial: options.isPartial, isError }, theme, renderContext ? withElapsedTiming(renderContext as GentleAiRenderContext) : undefined);
 			}
+			const resultTone = toolTone(options.isPartial === true, isError);
+			const carded = (component: () => Component): Component => new ToolCardBody(component, resultTone, theme);
 			if (options.isPartial) {
-				if (options.expanded) return new Text(`${theme.fg("warning", partialLabel(toolName, text))}\n${theme.fg("muted", text)}`, 0, 0);
+				if (options.expanded) return carded(() => new Text(`${theme.fg("warning", partialLabel(toolName, text))}\n${theme.fg("muted", text)}`, 0, 0));
 				const visible = lastOutputLines(text, PREVIEW_LINE_LIMIT);
-				return new BoundedRows([
+				return carded(() => new BoundedRows([
 					{ text: theme.fg("warning", partialLabel(toolName, text)), rows: 1 },
 					...(visible ? [{ text: theme.fg("muted", visible), rows: PREVIEW_LINE_LIMIT, tail: true }] : []),
-				], cacheKey);
+				], cacheKey));
 			}
 			if (options.expanded && toolName === "read" && hasImageContent(safeResult) && officialRenderResult) {
-				return officialRenderResult(
+				return carded(() => officialRenderResult(
 					safeResult,
 					options,
 					theme,
 					sanitizedRenderContext(renderContext) as any,
-				);
+				));
 			}
-			const output = formatToolResultOutput(toolName, safeResult, {
+			let output = formatToolResultOutput(toolName, safeResult, {
 				expanded: options.expanded,
 				isError,
 				args: renderContext?.args,
 			});
-			const hint = !options.expanded && !directResult && hasExpandableContent(toolName, safeResult, text)
-				? `\n${keyHint("app.tools.expand", "to expand")}`
-				: "";
-			const color = options.expanded ? "toolOutput" : isError ? "error" : "muted";
-			if (options.expanded) return new Text(output ? theme.fg(color, output) : "", 0, 0);
+			// Counts alone hide the result: retain their useful totals alongside actual rows.
+			if (!options.expanded && !isError && output && COLLAPSED_COUNT_LABELS[toolName]) {
+				output += `\n${firstLines(text, PREVIEW_LINE_LIMIT - 1)}`;
+			}
+			if (!options.expanded && !isError && toolName === "edit") {
+				const diff = detailsRecord(safeResult).diff;
+				if (typeof diff === "string") output += `\n${firstLines(safeText(diff).split("\n").filter((line) => /^[+-]/.test(line)).join("\n"), PREVIEW_LINE_LIMIT - 1)}`;
+			}
+			const color = isError ? "error" : options.expanded ? "toolOutput" : "muted";
+			if (options.expanded) return carded(() => new Text(output ? theme.fg(color, output.replace(/^\n/, "")) : "", 0, 0));
 			if (output) {
 				const tail = shouldRenderPreviewTail(toolName, text, isError, renderContext?.args);
-				return new BoundedRows([
+				return carded(() => 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);
+				], cacheKey));
 			}
-			return new Text(hint ? theme.fg(color, hint.slice(1)) : "", 0, 0);
+			// The card top rule carries the expand key, so an empty result only closes the frame.
+			return carded(() => new Text("", 0, 0));
 		},
+	};
+}
+
+function registerQuietTool(pi: ExtensionAPI, toolName: RegisteredToolName, resolveOverride: GentleAiDevBinaryOverrideResolver, timing: () => GentleAiElapsedTimingLedger | undefined): void {
+	const registrationTool = getBuiltInTools(process.cwd())[toolName];
+	pi.registerTool({
+		...registrationTool,
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			return getBuiltInTools(ctx.cwd)[toolName].execute(toolCallId, params, signal, onUpdate, ctx);
+		},
+		...createQuietToolRenderer(toolName, resolveOverride, timing, registrationTool.renderResult),
 	});
 }
 
-export default function quietTools(pi: ExtensionAPI, resolveOverride: GentleAiDevBinaryOverrideResolver = () => resolveGentleAiDevBinaryOverride()): void {
+export default function quietTools(pi: ExtensionAPI, resolveOverride: GentleAiDevBinaryOverrideResolver = () => resolveGentleAiDevBinaryOverride()): ReturnType<ExtensionFactory> {
 	if (!quietToolsEnabled()) return;
-	for (const toolName of Object.keys(TOOL_CREATORS) as QuietToolName[]) {
-		registerQuietTool(pi, toolName, () => createGentleAiCommandArguments(resolveQuietToolsDevBinaryPath(resolveOverride)));
+	let elapsedTiming: GentleAiElapsedTimingLedger | undefined;
+	pi.on("session_start", (_event, ctx) => {
+		elapsedTiming = new GentleAiElapsedTimingLedger(ctx.sessionManager, pi);
+	});
+	// Only bash calls that render as gentle-ai cards carry a durable duration;
+	// every other quiet tool keeps its plain renderer and writes no entries.
+	const recordGentleTiming = (event: { toolCallId: string; toolName: string; args?: unknown }, endedAt?: number): void => {
+		const ledger = elapsedTiming;
+		if (!ledger || event.toolName !== "bash" || !isGentleAiDirectCommand(event.args as Record<string, unknown> | undefined, createGentleAiCommandArguments(resolveQuietToolsDevBinaryPath(resolveOverride)))) return;
+		try {
+			if (endedAt === undefined) ledger.recordStart(event.toolCallId, Date.now());
+			else ledger.recordEnd(event.toolCallId, endedAt);
+		} catch { /* Timing persistence is best-effort and never breaks the tool event. */ }
+	};
+	pi.on("tool_execution_start", (event) => recordGentleTiming(event));
+	pi.on("tool_execution_end", (event) => recordGentleTiming(event, Date.now()));
+	const withElapsedTiming = (context: GentleAiRenderContext): GentleAiRenderContext =>
+		elapsedTiming ? { ...context, elapsedTiming } : context;
+	for (const toolName of Object.keys(TOOL_CREATORS) as RegisteredToolName[]) {
+		registerQuietTool(pi, toolName, resolveOverride, () => elapsedTiming);
 	}
+	return registerCompactCodemode(pi);
 }

package/extensions/resume-hint.ts

@@ -0,0 +1,60 @@
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { existsSync, writeFileSync } from "node:fs";
+import {
+	isResumeHandoffPath,
+	RESUME_HANDOFF_ENV,
+	resumeHandoffFromSession,
+	serializeResumeHandoff,
+} from "../lib/gentle-shell-resume-hint.ts";
+
+// Hands the quitting session to bin/gentle-shell.mjs, which prints a
+// gentle-shell resume command below pi's "pi --session <id>" exit hint (see
+// lib/gentle-shell-resume-hint.ts). Inert unless the launcher set the env var.
+
+// Process-wide, not per extension instance: /reload re-runs this factory after
+// the env var was already claimed, and must keep using the same handoff path
+// instead of going inert.
+const STATE_KEY = Symbol.for("gentle-pi.resume-hint");
+type StateHolder = { [STATE_KEY]?: string };
+
+function claimHandoffPath(env: NodeJS.ProcessEnv): string | undefined {
+	const holder = globalThis as StateHolder;
+	const path = env[RESUME_HANDOFF_ENV];
+	// Claim the handoff for this process only: subagents and tool shells
+	// inherit process.env, and their own shutdowns must not overwrite it.
+	delete env[RESUME_HANDOFF_ENV];
+	if (holder[STATE_KEY] === undefined && path && isResumeHandoffPath(path)) holder[STATE_KEY] = path;
+	return holder[STATE_KEY];
+}
+
+/** Test-only: forget the claimed handoff path. */
+export function resetResumeHintState(): void {
+	delete (globalThis as StateHolder)[STATE_KEY];
+}
+
+export default function resumeHint(pi: ExtensionAPI, env: NodeJS.ProcessEnv = process.env): void {
+	const handoffPath = claimHandoffPath(env);
+	if (!handoffPath) return;
+
+	pi.on("session_shutdown", (event, ctx) => {
+		if (event.reason !== "quit" || ctx.mode !== "tui") return;
+		const sessionManager = ctx.sessionManager;
+		const handoff = resumeHandoffFromSession({
+			sessionId: sessionManager.getSessionId(),
+			sessionDir: sessionManager.getSessionDir(),
+			sessionFile: sessionManager.getSessionFile(),
+			cwd: sessionManager.getCwd(),
+			launchCwd: process.cwd(),
+			agentDir: getAgentDir(),
+			fileExists: existsSync,
+		});
+		if (!handoff) return;
+		try {
+			// "wx": create only. The launcher's private dir starts empty, so an
+			// existing file (or a planted symlink) means it is not ours to write.
+			writeFileSync(handoffPath, serializeResumeHandoff(handoff), { encoding: "utf8", flag: "wx" });
+		} catch {
+			// Best effort: without a handoff the launcher prints nothing extra.
+		}
+	});
+}

package/extensions/skill-registry.ts

@@ -19,7 +19,6 @@ const CACHE_REL_PATH = ".atl/.skill-registry.cache.json";
 const SECTION_MARKER = "## Skills";
 const EXCLUDE_NAMES = new Set(["_shared", "skill-registry"]);
 const EXCLUDE_PREFIXES = ["sdd-"];
-const ATL_IGNORE_ENTRY = ".atl/";
 const WATCH_DEBOUNCE_MS = 500;
 const REGISTRY_SCHEMA_VERSION = 7;
 const NO_SKILL_REGISTRY_FLAG = "no-skill-registry";
@@ -315,19 +314,23 @@ interface RegenResult {
 }
 
 async function ensureAtlIgnored(cwd: string): Promise<void> {
-	const gitignorePath = join(cwd, ".gitignore");
-	let existing = "";
+	const atlDir = join(cwd, ".atl");
+	const gitignorePath = join(atlDir, ".gitignore");
 	if (await pathExists(gitignorePath)) {
-		existing = await readFile(gitignorePath, "utf8");
+		const existing = await readFile(gitignorePath, "utf8");
+		const ignoreRules = existing
+			.split("\n")
+			.map((line) => line.trim())
+			.filter((line) => line !== "" && !line.startsWith("#"));
+		if (ignoreRules.at(-1) === "*") {
+			return;
+		}
+		const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+		await writeFile(gitignorePath, `${existing}${prefix}*\n`);
+		return;
 	}
-	const hasAtlIgnore = existing
-		.split("\n")
-		.map((line) => line.trim())
-		.some((line) => line === ".atl" || line === ATL_IGNORE_ENTRY);
-	if (hasAtlIgnore) return;
-	const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-	const header = existing.includes("# Local Pi runtime state") ? "" : "# Local Pi runtime state\n";
-	await writeFile(gitignorePath, `${existing}${prefix}${header}${ATL_IGNORE_ENTRY}\n`);
+	await mkdir(atlDir, { recursive: true });
+	await writeFile(gitignorePath, "*\n");
 }
 
 function isGeneratedLegacyProjectRegistry(source: string): boolean {
@@ -534,6 +537,7 @@ export const __testing = {
 	parseFrontmatter,
 	renderRegistry,
 	regenerateRegistry,
+	ensureAtlIgnored,
 	shouldSkipSkillRegistryStartup,
 	shouldSkipDuplicateExtensionLoad,
 	startSkillRegistryWatcher,