gentle-pi 4.2.0 → 4.4.0

package/extensions/gentle-todo.ts

@@ -13,8 +13,11 @@ import {
 	staleTurns,
 	TODO_DETAILS_KEY,
 	TODO_GLYPH,
+	TODO_PROGRESS_EVENT,
 	TODO_TOOL_NAME,
 	todoCardTone,
+	TODO_CLOSED_STATE,
+	todoProgress,
 	todoPromptBlock,
 	todoStateMessage,
 	todoSummary,
@@ -26,8 +29,9 @@ import {
 // 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, each run's system prompt carries a byte-stable rules block while the
-// open tasks reach the model as a request-local trailing message (so list
-// changes never invalidate the cached prompt prefix, gentle-shell#1662), and
+// open tasks reach the model as a hidden transcript message appended when the
+// list changes (so list changes never invalidate the cached prompt prefix and
+// requests stay append-only, gentle-shell#1662, #2195), and
 // a list that goes untouched while tasks stay open is marked stale for the
 // human. Long runs also receive one request-local reminder after several
 // tool-use turns, without waking the agent or changing tasks.
@@ -87,6 +91,10 @@ interface TodoSession {
 	collapsed: boolean;
 	/** A finished list stays on screen for the turn it finished in, then clears. */
 	clearOnNextTurn: boolean;
+	/** The last state snapshot sent to the transcript. */
+	lastSent: string | undefined;
+	/** A snapshot queued during the current turn; Pi appends it at turn_end. */
+	pending: string | undefined;
 	ui: ExtensionContext["ui"] | undefined;
 	host: { requestRender(): void } | undefined;
 	tui: TUI | undefined;
@@ -107,12 +115,21 @@ 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, toolTurnsSinceWrite: 0, reminded: false, wroteThisTurn: false, collapsed: false, clearOnNextTurn: false, ui: undefined, host: undefined, tui: undefined };
+			current = { state: emptyTodo(), turn: 0, toolTurnsSinceWrite: 0, reminded: false, wroteThisTurn: false, collapsed: false, clearOnNextTurn: false, lastSent: undefined, pending: undefined, ui: undefined, host: undefined, tui: undefined };
 			sessions.set(key, current);
 		}
 		return current;
 	};
 
+	// While the agent streams, Pi appends this hidden message at turn_end, after
+	// the tool results and before the next model request; it never starts a turn.
+	const persistState = (current: TodoSession, state: string) => {
+		if (!pi.sendMessage) return;
+		pi.sendMessage({ customType: "gentle-todo-state", content: state, display: false }, { triggerTurn: false });
+		current.lastSent = state;
+		current.pending = state;
+	};
+
 	const toggle = (current: TodoSession) => {
 		current.collapsed = !current.collapsed;
 		if (current.tui) invalidateSidebar(current.tui);
@@ -265,6 +282,11 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 					current.toolTurnsSinceWrite = 0;
 					current.reminded = false;
 					current.wroteThisTurn = true;
+					// A closed list persists the closing marker, so the last open
+					// snapshot in the transcript never reads as current work.
+					const state = todoStateMessage(current.state) ?? (current.lastSent === undefined ? undefined : TODO_CLOSED_STATE);
+					if (state !== undefined && state !== current.lastSent) persistState(current, state);
+					pi.events?.emit(TODO_PROGRESS_EVENT, todoProgress(current.state, ctx.sessionManager.getSessionId()));
 				}
 				if (current.tui) invalidateSidebar(current.tui);
 			}
@@ -303,6 +325,8 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 		current.toolTurnsSinceWrite = 0;
 		current.reminded = false;
 		current.wroteThisTurn = false;
+		current.lastSent = undefined;
+		current.pending = undefined;
 		current.ui = ctx.hasUI ? ctx.ui : undefined;
 		show(current);
 	});
@@ -335,17 +359,27 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 			current.toolTurnsSinceWrite += 1;
 		}
 		current.wroteThisTurn = false;
+		// Pi flushes the queued snapshot right after this event.
+		current.pending = undefined;
 	});
 
 	pi.on("context", (event, ctx) => {
 		const current = session(ctx);
-		// Context transforms are request-local: no transcript entry, UI
-		// notification, continuation or provider-specific wake is needed. The
-		// current list trails the transcript (gentle-shell#1662), then the
-		// one-shot reminder when it is due.
+		// gentle-shell#1662, #2195: providers cache the request prefix up to the
+		// last message (Anthropic) or send only the delta after the previous input
+		// (openai-codex), so a trailing message that the next request drops breaks
+		// both. The list is persisted when it changes; this transform only covers a
+		// transcript that lacks the current snapshot (compaction, branch navigation,
+		// sessions recorded earlier): it trails this one request and persists the
+		// snapshot once, so the following requests are append-only again.
 		const trailing: Array<{ role: "custom"; customType: string; content: string; display: false; timestamp: number }> = [];
-		const state = todoStateMessage(current.state);
-		if (state !== undefined) trailing.push({ role: "custom", customType: "gentle-todo-state", content: state, display: false, timestamp: Date.now() });
+		const last = [...event.messages].reverse().find((message) => (message as { customType?: string }).customType === "gentle-todo-state") as { content?: unknown } | undefined;
+		const seen = typeof last?.content === "string" ? last.content : undefined;
+		const state = todoStateMessage(current.state) ?? (seen === undefined || seen === TODO_CLOSED_STATE ? undefined : TODO_CLOSED_STATE);
+		if (state !== undefined && seen !== state) {
+			trailing.push({ role: "custom", customType: "gentle-todo-state", content: state, display: false, timestamp: Date.now() });
+			if (current.pending !== state) persistState(current, state);
+		}
 		const actionable = current.state.tasks.some((task) => task.status === "pending" || task.status === "in_progress");
 		if (!current.reminded && current.toolTurnsSinceWrite >= REMIND_AFTER_TOOL_TURNS && actionable) {
 			current.reminded = true;

package/extensions/gentle-voice.ts

@@ -0,0 +1,11 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerVoiceCommand, type VoiceCommandDeps } from "../lib/voice-command.ts";
+
+// Gentle Voice: /gentle:voice owns optional local dictation (docs/voice.md).
+// Loading this extension registers the command and, when the push-to-talk
+// toggle is on, a hold-Space listener at session start. Nothing is probed,
+// downloaded, loaded or recorded until the user runs the command or holds Space.
+
+export default function gentleVoice(pi: ExtensionAPI, deps: VoiceCommandDeps = {}): void {
+	registerVoiceCommand(pi, deps);
+}

package/extensions/quiet-tools.ts

@@ -795,7 +795,7 @@ export function createQuietToolRenderer(
 					safeResult,
 					options,
 					theme,
-					sanitizedRenderContext(renderContext) as any,
+					{ ...sanitizedRenderContext(renderContext), lastComponent: undefined } as any,
 				), false);
 			}
 			let output = formatToolResultOutput(toolName, safeResult, {

package/extensions/session-scratch.ts

@@ -0,0 +1,384 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { lstatSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { gentlePiConfigHome } from "../lib/agent-home.ts";
+import {
+	checkArtifact,
+	CLEAN_RECENT_MS,
+	createSessionScratch,
+	deleteLedger,
+	directorySize,
+	formatSize,
+	gitArtifactTargets,
+	isProcessAlive,
+	isProtectedPath,
+	isSessionScratchName,
+	isWithin,
+	LEDGER_ARTIFACTS_CAP,
+	LEDGER_VERSION,
+	ledgerPath,
+	listLedgers,
+	listLedgersSync,
+	liveSubagentScratch,
+	processStartToken,
+	readLedger,
+	realTempRoot,
+	removeArtifact,
+	removeSessionScratch,
+	scratchRefusal,
+	SWEEP_GRACE_MS,
+	type ArtifactCheck,
+	type ArtifactTarget,
+	type ScratchArtifact,
+	type ScratchLedger,
+	type StoredLedger,
+	writeLedger,
+	writeLedgerSync,
+} from "../lib/session-scratch.ts";
+
+// Session scratch and artifact ledger (odd/tasks/session-scratch-ledger.md):
+// the primary session gets its own TMPDIR, the runtime records the clones and
+// worktrees its bash commands create, removes the scratch at shutdown (and the
+// scratch of crashed sessions at the next start), and /gentle:scratch lists or
+// cleans the rest. Delegated children (GENTLE_PI_AGENTS_CHILD=1) do none of it:
+// their own TMPDIR comes from the runner and nests under the parent's scratch.
+
+export const SCRATCH_COMMAND_USAGE = [
+	"Usage: /gentle:scratch [list|clean]",
+	"  list   this session's scratch dir with its size, and the clones and worktrees recorded by this and ended sessions",
+	"  clean  remove scratch dirs; after one confirmation, remove recorded worktrees and clones with no uncommitted changes and no unpushed commits",
+].join("\n");
+
+export interface SessionScratchOptions {
+	env?: NodeJS.ProcessEnv;
+	configHome?: string;
+	now?: () => number;
+	isProcessAlive?: (pid: number) => boolean;
+	/** When a process started (epoch ms), or undefined when it cannot be read. */
+	processStartToken?: (pid: number) => string | undefined;
+	graceMs?: number;
+	platform?: NodeJS.Platform;
+}
+
+interface ActiveSession {
+	sessionId: string;
+	path: string;
+	ledger: ScratchLedger;
+}
+
+// Keyed by the environment the session scratch was applied to. A /reload that
+// re-runs this factory in the same module instance finds the live session here;
+// one that re-evaluates the module (Pi's loader) recovers it from the ledger.
+const activeSessions = new WeakMap<NodeJS.ProcessEnv, ActiveSession>();
+
+export function createSessionScratchExtension(options: SessionScratchOptions = {}): (pi: ExtensionAPI) => void {
+	const env = options.env ?? process.env;
+	const now = options.now ?? Date.now;
+	const alive = options.isProcessAlive ?? isProcessAlive;
+	const startToken = options.processStartToken ?? processStartToken;
+	// A live pid is the ledger's process only if it has the start token the ledger
+	// recorded: the OS may have reused it. A token that is missing or cannot be
+	// read keeps the ledger live.
+	const isLive = (ledger: ScratchLedger) => {
+		if (!alive(ledger.pid)) return false;
+		if (ledger.processStartToken === undefined) return true;
+		let current: string | undefined;
+		try { current = startToken(ledger.pid); } catch { current = undefined; }
+		return current === undefined || current === ledger.processStartToken;
+	};
+	// This process's own token, or undefined (omitted from the ledger JSON) when it cannot be read.
+	const safeStartToken = () => { try { return startToken(process.pid); } catch { return undefined; } };
+	// Real paths of this process's live and quarantined subagent TMPDIRs (lib/agents-runner.ts).
+	const subagentDirs = () => liveSubagentScratch().flatMap((dir) => realTempRoot(dir) ?? []);
+	const graceMs = options.graceMs ?? SWEEP_GRACE_MS;
+	const tempVariables = (options.platform ?? process.platform) === "win32" ? ["TMPDIR", "TMP", "TEMP"] : ["TMPDIR"];
+	const configHome = () => options.configHome ?? gentlePiConfigHome(env);
+
+	const persist = async (path: string, ledger: ScratchLedger) => {
+		try {
+			if (ledger.scratchDir === null && ledger.artifacts.length === 0) deleteLedger(path);
+			else await writeLedger(path, ledger);
+		} catch { /* Best effort: an unwritable config home keeps the session running. */ }
+	};
+	// The shutdown path stays synchronous: its callers (tests/agents-runner.ts, and any
+	// handler consumer that does not await) read its post-conditions right after it runs.
+	const persistSync = (path: string, ledger: ScratchLedger) => {
+		try {
+			if (ledger.scratchDir === null && ledger.artifacts.length === 0) deleteLedger(path);
+			else writeLedgerSync(path, ledger);
+		} catch { /* Best effort: an unwritable config home keeps the session running. */ }
+	};
+	// Paths the runtime never records or removes, whatever a ledger says.
+	const protectedDirs = (ledger: ScratchLedger) => [configHome(), ledger.cwd, process.cwd()];
+
+	// The temp root the asking session trusts inside the home: its own, as recorded.
+	const ownRoot = () => activeSessions.get(env)?.ledger.tempRoot ?? realTempRoot(env.TMPDIR?.trim() || tmpdir());
+
+	// S9: a scratch name no longer carries its session id, so a scratch dir that a
+	// live session's ledger records stays out of reach of every other ledger. This
+	// session is live whatever the process check says. Returns, per ledger path,
+	// what removal through that ledger must keep: its artifacts and others' live scratch.
+	const heldBy = (ledgers: readonly StoredLedger[]) => {
+		const own = activeSessions.get(env);
+		const live = ledgers.filter(({ ledger }) => ledger.scratchDir !== null && isLive(ledger)).map(({ path, ledger }) => ({ path, dir: ledger.scratchDir! }));
+		if (own?.ledger.scratchDir) live.push({ path: own.path, dir: own.ledger.scratchDir });
+		return (path: string, ledger: ScratchLedger) => [
+			...ledger.artifacts.map((artifact) => artifact.path),
+			...live.filter((entry) => entry.path !== path).map((entry) => entry.dir),
+		];
+	};
+
+	const endSession = (session: ActiveSession) => {
+		const { ledger } = session;
+		// A running or quarantined subagent's TMPDIR stays; the scratch then stays in the ledger for a later sweep.
+		const removal = removeSessionScratch(ledger, heldBy(listLedgersSync(configHome()))(session.path, ledger), { ownRoot: ledger.tempRoot ?? undefined, liveSubagentDirs: subagentDirs() });
+		if (removal === "removed" || removal === "absent") ledger.scratchDir = null;
+		for (const [key, value] of Object.entries(ledger.inherited)) {
+			if (value === null) delete env[key];
+			else env[key] = value;
+		}
+		persistSync(session.path, ledger);
+		activeSessions.delete(env);
+		pending.clear();
+	};
+
+	// S5(b): scratch of ended sessions past the grace period; their artifacts stay for the command.
+	// The startup sweep stays synchronous: session_start's callers (tests/agents-runner.ts) read
+	// its post-conditions right after it runs, without awaiting the handler.
+	const sweep = (ownPath: string) => {
+		const ledgers = listLedgersSync(configHome());
+		const held = heldBy(ledgers);
+		for (const { path, ledger, mtimeMs } of ledgers) {
+			if (path === ownPath || isLive(ledger) || now() - mtimeMs < graceMs) continue;
+			const artifacts = ledger.artifacts.filter((artifact) => { try { lstatSync(artifact.path); return true; } catch { return false; } });
+			const removal = ledger.scratchDir === null ? "absent" : removeSessionScratch(ledger, held(path, { ...ledger, artifacts }), { ownRoot: ownRoot(), liveSubagentDirs: subagentDirs() });
+			persistSync(path, { ...ledger, scratchDir: removal === "removed" || removal === "absent" ? null : ledger.scratchDir, artifacts });
+		}
+	};
+
+	// The live scratch of this process: its ledger names this pid and a scratch it
+	// created that TMPDIR still points into, as after a reload that lost module state.
+	const isLiveScratch = (ledger: ScratchLedger | undefined): boolean => {
+		if (!ledger?.scratchDir || ledger.pid !== process.pid || scratchRefusal(ledger, ledger.tempRoot ?? undefined) !== undefined) return false;
+		const current = env.TMPDIR?.trim();
+		return !!current && [resolve(current), realTempRoot(current)].some((dir) => dir !== undefined && isWithin(dir, ledger.scratchDir!));
+	};
+
+	// The startup path stays synchronous, like the shutdown path: its callers
+	// (tests/agents-runner.ts) read its post-conditions without awaiting the handler.
+	const startSession = (ctx: ExtensionContext, reason: string) => {
+		const sessionId = ctx.sessionManager.getSessionId?.();
+		if (!sessionId) return;
+		const current = activeSessions.get(env);
+		if (current?.sessionId === sessionId && reason === "reload") return;
+		if (current) endSession(current);
+		const path = ledgerPath(configHome(), sessionId);
+		const previous = readLedger(path);
+		if (previous && isLiveScratch(previous)) {
+			activeSessions.set(env, { sessionId, path, ledger: previous });
+			persistSync(path, previous);
+			sweep(path);
+			return;
+		}
+		// A reload that could not recover the scratch finds TMPDIR pointing at it:
+		// the inherited values are the ones this process's ledger recorded, else
+		// TMPDIR as it is unless it is a session scratch, whose parent it was made in.
+		const reloaded = reason === "reload" && previous?.pid === process.pid ? previous.inherited : undefined;
+		const inheritedValue = (key: string) => {
+			if (reloaded && key in reloaded) return reloaded[key];
+			const value = env[key];
+			if (reason === "reload" && value?.trim() && isSessionScratchName(value.trim())) return dirname(value.trim());
+			return value ?? null;
+		};
+		const inherited = Object.fromEntries(tempVariables.map((key) => [key, inheritedValue(key)]));
+		// Restored first, so tmpdir() never answers with the old scratch.
+		for (const [key, value] of Object.entries(inherited)) {
+			if (value === null) delete env[key];
+			else env[key] = value;
+		}
+		const inheritedTmp = inherited.TMPDIR?.trim();
+		const created = createSessionScratch(inheritedTmp ? inheritedTmp : tmpdir());
+		// TMPDIR keeps the inherited spelling (S9: socket path length); the ledger keeps real paths.
+		if (created) for (const key of tempVariables) env[key] = created.path;
+		const scratchDir = created?.realPath;
+		// A resumed session keeps the artifacts an earlier run of it recorded.
+		const ledger: ScratchLedger = {
+			version: LEDGER_VERSION,
+			sessionId,
+			pid: process.pid,
+			processStartedAt: new Date(now() - process.uptime() * 1000).toISOString(),
+			processStartToken: safeStartToken(),
+			cwd: ctx.cwd,
+			tempRoot: scratchDir ? dirname(scratchDir) : null,
+			inherited,
+			scratchDir: scratchDir ?? null,
+			artifacts: previous?.artifacts ?? [],
+		};
+		// A scratch of this process is never removed at startup: it may still be in use.
+		if (previous?.scratchDir && previous.scratchDir !== scratchDir && previous.pid !== process.pid && !isLive(previous)) {
+			const held = heldBy(listLedgersSync(configHome()))(path, ledger);
+			removeSessionScratch(previous, scratchDir ? [...held, scratchDir] : held, { ownRoot: ownRoot(), liveSubagentDirs: subagentDirs() });
+		}
+		activeSessions.set(env, { sessionId, path, ledger });
+		persistSync(path, ledger);
+		sweep(path);
+	};
+
+	// S4: destinations a foreground bash command is about to create, by tool call
+	// id. A destination that already exists belongs to someone else.
+	const pending = new Map<string, ArtifactTarget[]>();
+
+	const note = (toolCallId: string, command: string, ctx: ExtensionContext) => {
+		if (!activeSessions.get(env)) return;
+		const absent = gitArtifactTargets(command, ctx.cwd).filter((target) => {
+			try { lstatSync(target.path); return false; } catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT"; }
+		});
+		if (absent.length > 0) pending.set(toolCallId, absent);
+	};
+
+	// S4: the noted destinations that a successful command created. The ledger keeps
+	// only the most recent artifacts, evicting the oldest first, so a long session's
+	// ledger file stays bounded.
+	const capture = async (targets: readonly ArtifactTarget[], command: string) => {
+		const session = activeSessions.get(env);
+		if (!session) return;
+		const { ledger } = session;
+		let changed = false;
+		for (const target of targets) {
+			let path: string;
+			try {
+				if (!lstatSync(target.path).isDirectory()) continue;
+				path = realpathSync(target.path);
+			} catch { continue; }
+			if (isProtectedPath(path, protectedDirs(ledger)) || ledger.artifacts.some((artifact) => artifact.path === path)) continue;
+			ledger.artifacts.push({ kind: target.kind, path, command, recordedAt: new Date(now()).toISOString() });
+			changed = true;
+		}
+		if (!changed) return;
+		if (ledger.artifacts.length > LEDGER_ARTIFACTS_CAP) ledger.artifacts = ledger.artifacts.slice(-LEDGER_ARTIFACTS_CAP);
+		await persist(session.path, ledger);
+	};
+
+	const endedLedgers = async (ownPath: string | undefined) =>
+		(await listLedgers(configHome())).filter(({ path, ledger }) => path !== ownPath && !isLive(ledger));
+
+	const describe = (artifact: ScratchArtifact) => `${artifact.kind} ${artifact.path}`;
+
+	const list = async (): Promise<string> => {
+		const session = activeSessions.get(env);
+		const lines: string[] = [];
+		const own = session?.ledger;
+		lines.push(own?.scratchDir
+			? `Session scratch: ${own.scratchDir} (${formatSize(directorySize(own.scratchDir))})`
+			: `Session scratch: none (TMPDIR ${env.TMPDIR ?? tmpdir()})`);
+		const ended = await endedLedgers(session?.path);
+		for (const { ledger } of ended) if (ledger.scratchDir) lines.push(`Ended-session scratch: ${ledger.scratchDir} (session ${ledger.sessionId})`);
+		const artifacts = [
+			...(own?.artifacts ?? []).map((artifact) => `  ${describe(artifact)} (this session)`),
+			...ended.flatMap(({ ledger }) => ledger.artifacts.map((artifact) => `  ${describe(artifact)} (session ${ledger.sessionId}, ended)`)),
+		];
+		lines.push(artifacts.length > 0 ? "Recorded clones and worktrees:" : "Recorded clones and worktrees: none", ...artifacts);
+		return lines.join("\n");
+	};
+
+	const clean = async (ctx: ExtensionContext): Promise<string> => {
+		// Entries of the live scratch changed since this moment may belong to a running command.
+		const recentSince = now() - CLEAN_RECENT_MS;
+		const session = activeSessions.get(env);
+		const groups = [
+			...(session ? [{ path: session.path, ledger: session.ledger, own: true }] : []),
+			...(await endedLedgers(session?.path)).map(({ path, ledger }) => ({ path, ledger, own: false })),
+		];
+		const lines: string[] = [];
+		const entries = groups.flatMap((group) => group.ledger.artifacts.map((artifact) => ({ group, artifact })));
+		const drop = (entry: (typeof entries)[number]) => {
+			entry.group.ledger.artifacts = entry.group.ledger.artifacts.filter((artifact) => artifact !== entry.artifact);
+		};
+		if (entries.length > 0 && !ctx.hasUI) {
+			lines.push("Recorded clones and worktrees kept (no UI to confirm their removal):", ...entries.map(({ artifact }) => `  ${describe(artifact)}`));
+		} else if (entries.length > 0) {
+			const checked = await Promise.all(entries.map(async (entry) => ({ ...entry, check: await checkArtifact(entry.artifact, protectedDirs(entry.group.ledger)) })));
+			const removable: Array<(typeof entries)[number] & { check: Extract<ArtifactCheck, { state: "removable" }> }> = [];
+			for (const entry of checked) {
+				if (entry.check.state === "missing") { drop(entry); lines.push(`Already gone: ${describe(entry.artifact)}`); }
+				else if (entry.check.state === "kept") lines.push(`Kept ${describe(entry.artifact)}: ${entry.check.reason}`);
+				else removable.push(entry as (typeof removable)[number]);
+			}
+			if (removable.length > 0) {
+				const confirmed = await ctx.ui.confirm(
+					`Remove ${removable.length} recorded clone${removable.length === 1 ? "" : "s"}/worktree${removable.length === 1 ? "" : "s"}?`,
+					`No uncommitted changes and no unpushed commits; ignored files inside these paths are deleted too:\n${removable.map(({ artifact }) => `  ${describe(artifact)}`).join("\n")}`,
+				);
+				for (const entry of removable) {
+					if (!confirmed) { lines.push(`Kept ${describe(entry.artifact)}: not confirmed`); continue; }
+					// The clone may have changed while the confirmation was open: check it again.
+					const recheck = await checkArtifact(entry.artifact, protectedDirs(entry.group.ledger));
+					if (recheck.state === "missing") { drop(entry); lines.push(`Already gone: ${describe(entry.artifact)}`); continue; }
+					if (recheck.state === "kept") { lines.push(`Kept ${describe(entry.artifact)}: ${recheck.reason}`); continue; }
+					if (recheck.identity?.dev !== entry.check.identity?.dev || recheck.identity?.ino !== entry.check.identity?.ino) { lines.push(`Kept ${describe(entry.artifact)}: replaced after the check`); continue; }
+					const failure = await removeArtifact(entry.artifact, recheck);
+					if (failure) lines.push(`Kept ${describe(entry.artifact)}: ${failure}`);
+					else { drop(entry); lines.push(`Removed ${describe(entry.artifact)}`); }
+				}
+			}
+		}
+		// Scratch goes without asking; the live session keeps its TMPDIR and empties it.
+		const held = heldBy(await listLedgers(configHome()));
+		for (const group of groups) {
+			const { ledger } = group;
+			if (!ledger.scratchDir) continue;
+			const dir = ledger.scratchDir;
+			const removal = removeSessionScratch(ledger, held(group.path, ledger), { contentsOnly: group.own, ownRoot: ownRoot(), liveSubagentDirs: subagentDirs(), keepChangedSince: group.own ? recentSince : undefined });
+			if (!group.own && (removal === "removed" || removal === "absent")) ledger.scratchDir = null;
+			if (removal === "refused") lines.push(`Kept scratch ${dir}: not a directory this runtime created`);
+			else if (removal === "kept") lines.push(`${group.own ? "Emptied" : "Kept"} scratch ${dir}${group.own ? " except subagent scratch, live sessions' scratch, recorded artifacts, and entries changed in the last minute" : ": holds a recorded artifact, a live session's scratch, or a live subagent's scratch"}`);
+			else lines.push(`${group.own ? "Emptied" : "Removed"} scratch ${dir}`);
+		}
+		for (const group of groups) await persist(group.path, group.ledger);
+		return lines.length > 0 ? lines.join("\n") : "Nothing to clean.";
+	};
+
+	return (pi: ExtensionAPI) => {
+		if (env.GENTLE_PI_AGENTS_CHILD === "1") return;
+		pi.on("session_start", (event, ctx) => {
+			try { startSession(ctx, (event as { reason?: string }).reason ?? "startup"); } catch { /* The session keeps the inherited TMPDIR. */ }
+		});
+		pi.on("session_shutdown", (event) => {
+			// A reload continues the same session and keeps its scratch.
+			if ((event as { reason?: string }).reason === "reload") return;
+			const session = activeSessions.get(env);
+			try { if (session) endSession(session); } catch { /* best effort */ }
+		});
+		pi.on("tool_call", (event, ctx) => {
+			// Only foreground bash: a background job's result arrives before its clone exists.
+			const command = (event.input as { command?: unknown } | undefined)?.command;
+			if (event.toolName !== "bash" || typeof command !== "string") return undefined;
+			try { note(event.toolCallId, command, ctx); } catch { /* Capture never blocks a tool call. */ }
+			return undefined;
+		});
+		pi.on("tool_result", async (event) => {
+			const targets = pending.get(event.toolCallId);
+			if (!targets) return undefined;
+			pending.delete(event.toolCallId);
+			const command = (event.input as { command?: unknown } | undefined)?.command;
+			if (event.toolName !== "bash" || event.isError !== false || typeof command !== "string") return undefined;
+			try { await capture(targets, command); } catch { /* Capture never changes a tool result. */ }
+			return undefined;
+		});
+		pi.registerCommand("gentle:scratch", {
+			description: "List or clean this session's scratch dir and the recorded clones and worktrees (list|clean).",
+			getArgumentCompletions: (prefix) => ["list", "clean"].filter((action) => action.startsWith(prefix.trim())).map((action) => ({ value: action, label: action })),
+			handler: async (args, ctx) => {
+				const action = args.trim() || "list";
+				if (action === "list") ctx.ui.notify(await list(), "info");
+				else if (action === "clean") ctx.ui.notify(await clean(ctx), "info");
+				else ctx.ui.notify(SCRATCH_COMMAND_USAGE, "warning");
+			},
+		});
+	};
+}
+
+export default function sessionScratch(pi: ExtensionAPI): void {
+	createSessionScratchExtension()(pi);
+}

package/extensions/skill-registry.ts

@@ -25,6 +25,11 @@ const SECTION_MARKER = "## Skills";
 const EXCLUDE_NAMES = new Set(["_shared", "skill-registry"]);
 const EXCLUDE_PREFIXES = ["sdd-"];
 const WATCH_DEBOUNCE_MS = 500;
+// inotify budgets are finite (ENOSPC/EMFILE) and recursive watches degrade
+// silently on exhausted systems -- WSL2 hits this constantly -- so a slow
+// poll is the floor that keeps regeneration working when the OS cannot
+// deliver change events. The fingerprint gate makes a redundant poll cheap.
+const WATCH_FALLBACK_POLL_MS = 2_000;
 const REGISTRY_SCHEMA_VERSION = 7;
 const NO_SKILL_REGISTRY_FLAG = "no-skill-registry";
 const NO_SKILL_REGISTRY_ENV = "GENTLE_PI_NO_SKILL_REGISTRY";
@@ -98,6 +103,11 @@ function projectSkillDirs(cwd: string): string[] {
 	];
 }
 
+function isMissingSkillFileError(error: unknown): boolean {
+	if (typeof error !== "object" || error === null || !("code" in error)) return false;
+	return error.code === "ENOENT" || error.code === "ENOTDIR";
+}
+
 async function findSkillFiles(root: string): Promise<string[]> {
 	if (!(await pathExists(root))) return [];
 	let entries;
@@ -107,7 +117,8 @@ async function findSkillFiles(root: string): Promise<string[]> {
 		return [];
 	}
 
-	const out: string[] = [];
+	const directSkills: string[] = [];
+	const nestedSkills: string[] = [];
 	for (const entry of entries) {
 		const skillDir = join(root, entry.name);
 		let dirInfo;
@@ -121,12 +132,40 @@ async function findSkillFiles(root: string): Promise<string[]> {
 		const candidate = join(skillDir, "SKILL.md");
 		try {
 			const skillInfo = await stat(candidate);
-			if (skillInfo.isFile()) out.push(candidate);
+			if (skillInfo.isFile()) directSkills.push(candidate);
+			continue;
+		} catch (error) {
+			if (!isMissingSkillFileError(error)) continue;
+		}
+		if (entry.isSymbolicLink() || isExcluded(entry.name)) continue;
+
+		let nestedEntries;
+		try {
+			nestedEntries = await readdir(skillDir, { withFileTypes: true });
 		} catch {
-			// Missing or unreadable skill files are ignored; the registry is best-effort.
+			continue;
+		}
+		for (const nestedEntry of nestedEntries) {
+			if (nestedEntry.isSymbolicLink()) continue;
+			const nestedSkillDir = join(skillDir, nestedEntry.name);
+			let nestedDirInfo;
+			try {
+				nestedDirInfo = await stat(nestedSkillDir);
+			} catch {
+				continue;
+			}
+			if (!nestedDirInfo.isDirectory()) continue;
+
+			const nestedCandidate = join(nestedSkillDir, "SKILL.md");
+			try {
+				const nestedSkillInfo = await stat(nestedCandidate);
+				if (nestedSkillInfo.isFile()) nestedSkills.push(nestedCandidate);
+			} catch {
+				// Missing or unreadable skill files are ignored; the registry is best-effort.
+			}
 		}
 	}
-	return out.sort();
+	return [...directSkills.sort(), ...nestedSkills.sort()];
 }
 
 function parseFrontmatter(source: string): { name?: string; description?: string; body: string } {
@@ -346,7 +385,7 @@ async function hasNoGitMetadata(cwd: string): Promise<boolean> {
 }
 
 // Freshness (including forced self-heal) never grants automatic write permission.
-async function automaticWriteWarning(
+export async function automaticWriteWarning(
 	cwd: string,
 	targets: string[],
 	remedy = "Run /skill-registry:refresh to deliberately regenerate runtime files.",
@@ -357,6 +396,7 @@ async function automaticWriteWarning(
 			cwd,
 			env: { ...process.env, LC_ALL: "C" },
 			timeout: gitTimeoutMs,
+			windowsHide: true,
 		});
 		tracked = stdout.split("\0").filter(Boolean);
 	} catch (error) {
@@ -496,6 +536,7 @@ async function regenerateRegistry(
 }
 
 const watchedCwds = new Set<string>();
+const watcherPolls = new Map<string, ReturnType<typeof setInterval>>();
 // Startup regeneration runs after session_start returns; watcher refreshes
 // wait for it so an older startup scan never overwrites a newer refresh.
 const pendingStartups = new Map<string, Promise<void>>();
@@ -574,6 +615,8 @@ function closeSkillRegistryWatchers(): void {
 		}
 	}
 	activeWatchers.clear();
+	for (const poll of watcherPolls.values()) clearInterval(poll);
+	watcherPolls.clear();
 	watchedCwds.clear();
 }
 
@@ -588,6 +631,9 @@ async function startSkillRegistryWatcher(
 		...userSkillDirs(),
 	]);
 	let timer: ReturnType<typeof setTimeout> | undefined;
+	// The poll re-asks a state the watchers already answered: without this,
+	// an unchanged tracked-target warning would repeat every poll interval.
+	let lastWarning: string | undefined;
 	const refresh = () => {
 		if (timer) clearTimeout(timer);
 		timer = setTimeout(() => {
@@ -595,9 +641,14 @@ async function startSkillRegistryWatcher(
 				try {
 					await pendingStartups.get(cwd);
 					const result = await regenerateRegistry(cwd, false);
-					if (result.warning) notify(result.warning, "warning");
-					if (result.regenerated) {
-						notify(`Skill registry refreshed (${result.skillCount} skills)`, "info");
+					if (result.warning) {
+						if (result.warning !== lastWarning) notify(result.warning, "warning");
+						lastWarning = result.warning;
+					} else {
+						lastWarning = undefined;
+						if (result.regenerated) {
+							notify(`Skill registry refreshed (${result.skillCount} skills)`, "info");
+						}
 					}
 				} catch (error) {
 					notify(`Skill registry refresh failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
@@ -620,12 +671,16 @@ async function startSkillRegistryWatcher(
 			// Some filesystems do not support recursive watches; session_start/manual refresh still work.
 		}
 	}
+	// Watchers may be absent (unsupported filesystem) or silently eventless
+	// (exhausted inotify budget): the poll keeps regeneration alive either way.
+	if (!watcherPolls.has(cwd)) watcherPolls.set(cwd, setInterval(refresh, WATCH_FALLBACK_POLL_MS));
 }
 
 export const __testing = {
 	projectSkillDirs,
 	userSkillDirs,
 	findSkillFiles,
+	isMissingSkillFileError,
 	uniqueExistingDirs,
 	dedupeBySkillName,
 	scopeForPath,