gentle-pi 4.2.0 → 4.3.0

package/extensions/gentle-herdr-activity.ts

@@ -1,6 +1,6 @@
 import { statSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { activitySummary, ActivityPublisher, createActivityColumns, metadataTransport } from "../lib/herdr-activity.ts";
+import { activitySummary, ActivityPublisher, createActivityColumns, herdrDetected, metadataTransport } from "../lib/herdr-activity.ts";
 import { replayTodo, type TodoState } from "../lib/shell-todo.ts";
 
 interface ActivityOptions {
@@ -15,8 +15,7 @@ interface ActivityOptions {
 export function createHerdrActivityExtension(options: ActivityOptions = {}) {
 	return (pi: ExtensionAPI): void => {
 		const env = options.env ?? process.env;
-		if (env.GENTLE_PI_AGENTS_CHILD === "1" || env.HERDR_ENV !== "1" ||
-			!env.HERDR_PANE_ID?.trim() || !env.HERDR_SOCKET_PATH?.trim()) return;
+		if (env.GENTLE_PI_AGENTS_CHILD === "1" || !herdrDetected(env)) return;
 		const isSocket = options.isSocket ?? ((path: string) => {
 			try { return statSync(path).isSocket(); } catch { return false; }
 		});

package/extensions/gentle-shell.ts

@@ -12,6 +12,7 @@ import { dirname, join, resolve } from "node:path";
 import { buildShellHeaderModel, renderShellBar, renderShellBelowInputFloat, renderShellBottomOnlyBar, renderShellHeaderChrome, renderShellSidebarBar, keepNativeWorkingRow, shellEnabled, shellHeaderUsageHit, shellJobsCount, type ShellBarModel, type ShellBarTheme } from "../lib/shell-bar.ts";
 import { CHANGE_STATUS, DIFF_MAX_BYTES, DIFF_MAX_LINES, DIFF_TOO_LARGE, WorktreeChangesTracker, renderChangesWidget, type ChangedFile, type ChangesModel, type FileRevision, type GitRunner, type LineCounter, type WorktreeChanges } from "../lib/shell-changes.ts";
 import { WorktreeChangesView } from "../lib/shell-changes-view.ts";
+import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
 import { SessionWorktreeRegistry, resolveSessionWorktree, worktreeGitEnvironment, type WorktreeResolver, type WorktreeIdentity } from "../lib/session-worktree-registry.ts";
 import { CARD_STYLE, CARD_TONE, cardStyle, renderCard, setCardStyle, type Card, type CardTheme } from "../lib/shell-card.ts";
 import { resolveCardStyle, writeCardStyle } from "../lib/card-style-policy.ts";
@@ -21,6 +22,8 @@ import { buildCommandPaletteGroups } from "../lib/command-palette-catalog.ts";
 import { discoverYoloUiAdapter, YOLO_DISPLAY, type YoloDisplay, type YoloUiAdapter } from "../lib/yolo-session-policy.ts";
 import { VisualCustomizeView, type CustomizeCategory, type CustomizeRow, type ProfileActions } from "../lib/visual-customize-view.ts";
 import { deleteVisualProfile, getVisualProfile, listVisualProfiles, resetVisualProfiles, saveVisualProfile } from "../lib/visual-profiles.ts";
+import { gaugePaintFor } from "../lib/gauge-theme.ts";
+import type { GaugePaint } from "../lib/shell-gauge.ts";
 import { sourcePalettePreview } from "../lib/theme-customization.ts";
 import { DEFAULT_VISUAL_SETTINGS, DENSITY, HEADER_PLACEMENT, STATUS_PLACEMENT, VISUAL_SECTION_KEYS, resolveVisualSettings, writeVisualSettings } from "../lib/visual-customization-policy.ts";
 import { BANNER_COLORS, DEFAULT_BANNER_CONFIG, readBannerConfig, readBannerConfigForEdit, writeBannerConfig } from "./startup-banner.ts";
@@ -31,7 +34,6 @@ import { oddPhaseRegistry } from "../lib/odd-phase.ts";
 import { inferOddPhase } from "../lib/odd-phase-inference.ts";
 import { isInteractiveMode } from "../lib/rpc-host.ts";
 import { gentlePiConfigHome } from "../lib/agent-home.ts";
-import { bundledGentlePiConfigHome } from "../lib/gentle-shell-bundled.ts";
 import { isNanAdaptiveReasoningModel } from "../lib/nan-provider.ts";
 import { resolveAnimationPolicy, writeAnimationPolicy, type AnimationPolicy } from "../lib/animation-policy.ts";
 import { resolveVimPolicy, writeVimPolicy, type VimPolicy } from "../lib/vim-policy.ts";
@@ -180,7 +182,7 @@ export type ActiveProfileReader = (() => string | undefined) & {
 // Unbound reads retain the global file-identity cache, including atomic replacements.
 // Bound reads are snapshots: no filesystem or Git work is done during a frame.
 export function createActiveProfileReader(env: NodeJS.ProcessEnv = process.env): ActiveProfileReader {
-	const path = profilesFilePath(bundledGentlePiConfigHome(env) ?? env.GENTLE_PI_CONFIG_HOME ?? join(os.homedir(), ".pi", "gentle-ai"));
+	const path = profilesFilePath(gentlePiConfigHome(env));
 	let fingerprint: string | undefined;
 	let name: string | undefined;
 	let bound = false;
@@ -215,7 +217,7 @@ export function createActiveProfileReader(env: NodeJS.ProcessEnv = process.env):
 		const next = cwd === undefined ? global() : sessionProfileLabel(resolveSessionProfile({
 			sessionId,
 			cwd,
-			configHome: bundledGentlePiConfigHome(env) ?? env.GENTLE_PI_CONFIG_HOME ?? join(os.homedir(), ".pi", "gentle-ai"),
+			configHome: gentlePiConfigHome(env),
 			resolveWorktree: () => identity,
 			env,
 		}));
@@ -334,6 +336,16 @@ export function buildShellBarModel(
 	};
 }
 
+// Gauge-specific theme roles (issue #2222): resolved from the installed theme
+// source and memoized by gauge-theme.ts, so the render hot path only stats the
+// theme file. Undefined — and therefore today's shared roles — whenever the theme
+// source is unavailable.
+function gaugePaint(ctx: ExtensionContext): GaugePaint | undefined {
+	const themeName = ctx.ui.theme.name;
+	const source = ctx.ui.theme.sourcePath ?? ctx.ui.getAllThemes?.().find((item) => item?.name === themeName)?.path;
+	return gaugePaintFor(typeof source === "string" ? source : undefined);
+}
+
 export function createShellBarComponent(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
@@ -350,7 +362,7 @@ export function createShellBarComponent(
 	});
 	return {
 		render(width: number) {
-			return renderShellBar(buildShellBarModel(pi, ctx, footerData, { dirty: dirty(), usage: usage() }), theme, width, presentation?.());
+			return renderShellBar(buildShellBarModel(pi, ctx, footerData, { dirty: dirty(), usage: usage() }), theme, width, presentation?.(), gaugePaint(ctx));
 		},
 		invalidate() {},
 		dispose() {
@@ -1223,8 +1235,6 @@ const CHANGES_SHORTCUT_DEFAULT = "alt+g";
 const CHANGES_POLL_DEFAULT_MS = 2000;
 const GIT_TIMEOUT_MS = 5000;
 const COMMANDS_COMMAND_NAME = "gentle:commands";
-const OVERLAY_HEIGHT_RATIO = 0.8;
-const OVERLAY_MIN_ROWS = 8;
 
 export function shellGitRunner(cwd: string, env: NodeJS.ProcessEnv = process.env, run: typeof execFile = execFile, maxBuffer = Infinity): GitRunner {
 	// Pi exec cannot replace the inherited environment. Use argv directly and
@@ -1329,6 +1339,8 @@ interface OverlayDeps {
 }
 
 // The overlay polls each root's Git state while it is open; diffs load lazily.
+// Like Gentle Agents it takes the whole terminal, and the native fullscreen
+// wrapper keeps mouse dispatch on the view while it owns the keyboard.
 async function showChangesOverlay(ctx: ExtensionContext, deps: OverlayDeps): Promise<void> {
 	let host: ExternalEditorHost | undefined;
 	let view: WorktreeChangesView | undefined;
@@ -1346,16 +1358,18 @@ async function showChangesOverlay(ctx: ExtensionContext, deps: OverlayDeps): Pro
 				host = tui;
 				view = new WorktreeChangesView(deps.worktrees(), {
 					theme,
-					rows: () => Math.max(OVERLAY_MIN_ROWS, Math.floor(tui.terminal.rows * OVERLAY_HEIGHT_RATIO)),
+					rows: () => Math.max(0, tui.terminal.rows),
 					loadDiff: deps.loadDiff,
 					onOpen: (root, file) => close({ root, file }),
 					onRefresh: () => void refresh().catch(() => {}),
 					onClose: () => close(null),
 					requestRender: () => tui.requestRender(),
 				});
-				return view;
+				const interaction = createNativeFullscreenInteraction({ keyboardTarget: view, requestRender: () => tui.requestRender() });
+				interaction.addChild(view);
+				return interaction;
 			},
-			{ overlay: true, overlayOptions: { width: "92%", anchor: "center" } },
+			{ overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", margin: 0, anchor: "center" } },
 		);
 		if (!chosen || !host) return;
 		if (!openInExternalEditor(host, chosen.file.path, process.env, spawnSync, chosen.root)) ctx.ui.notify("No editor configured. Set $VISUAL or $EDITOR.", "warning");
@@ -1738,6 +1752,7 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 					onClose: () => withOverlayRepaint(tui, done)(null),
 					requestRender: () => tui.requestRender(),
 					scope: () => ({ providers: usageScope, failed: new Set(usageFailures) }),
+					gauge: () => gaugePaint(ctx),
 				});
 				// Open promptly: the panel draws whatever the store already holds
 				// while the forced refresh runs underneath it, and repaints when
@@ -1924,7 +1939,7 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 			const statusOwner = () => narrowStatusOwner({ mode: (tui as TUI & { mode?: string }).mode, columns: tui.terminal?.columns ?? 0, statusPlacement: visualSettings.statusPlacement, headerPlacement: visualSettings.headerPlacement });
 			const statusCardVisible = () => Boolean(tui.terminal && tui.terminal.columns >= SIDEBAR_BREAKPOINT && sidebarState(tui).ownsHost?.() && visualSettings.statusPlacement !== "hidden");
 			const belowFloat = (width: number, statuses: boolean) => (tui as TUI & { mode?: string }).mode === "fullscreen"
-				? renderShellBelowInputFloat({ ...footerModel(), ...(statuses ? {} : { statuses: [] }), ...(statusCardVisible() ? { jobs: undefined } : {}) }, theme, width, usageShortcutKey, visualSettings, tracker.model)
+				? renderShellBelowInputFloat({ ...footerModel(), ...(statuses ? {} : { statuses: [] }), ...(statusCardVisible() ? { jobs: undefined } : {}) }, theme, width, usageShortcutKey, visualSettings, tracker.model, gaugePaint(ctx))
 				: undefined;
 			// Match sidebarPart's live paint ownership, including an unavailable rail.
 			const footerSuppressed = () => {
@@ -1935,7 +1950,7 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 			groupedChangesOwner = (width) => belowFloat(width, !footerSuppressed()) !== undefined;
 			const bottomBar = {
 				...bottom,
-				render: (width: number) => belowFloat(width, true)?.rows ?? (statusOwner() === STATUS_OWNER.BOTTOM ? renderShellBottomOnlyBar(footerModel(), theme, width, usageShortcutKey, visualSettings) : bottom.render(width)),
+				render: (width: number) => belowFloat(width, true)?.rows ?? (statusOwner() === STATUS_OWNER.BOTTOM ? renderShellBottomOnlyBar(footerModel(), theme, width, usageShortcutKey, visualSettings, undefined, gaugePaint(ctx)) : bottom.render(width)),
 				handleMouse(event: Parameters<NonNullable<SidebarRail["handleMouse"]>>[0]) {
 					if (footerSuppressed() || event.type !== "click" || event.button !== "left") return undefined;
 					const chrome = belowFloat(event.width, true);
@@ -1952,7 +1967,7 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 			// The header row carries everything that ticks every frame (model,
 			// effort, context, cost, usage) plus session identity and the jobs count
 			// when Status is absent. Opaque statuses and working state stay excluded.
-			const headerBar = (width: number) => renderShellHeaderChrome(buildShellHeaderModel(footerModel(), !statusCardVisible() && (statusOwner() === STATUS_OWNER.HEADER || visualSettings.statusPlacement === "hidden")), theme, width, usageShortcutKey, visualSettings);
+			const headerBar = (width: number) => renderShellHeaderChrome(buildShellHeaderModel(footerModel(), !statusCardVisible() && (statusOwner() === STATUS_OWNER.HEADER || visualSettings.statusPlacement === "hidden")), theme, width, usageShortcutKey, visualSettings, gaugePaint(ctx));
 			const disposeHeader = sidebarHeader(tui, {
 				digest: () => JSON.stringify([footerModel(), tracker.model, visualSettings, cardStyle()]),
 				render: (width) => headerBar(width).rows,

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/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,365 @@
+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_VERSION,
+	ledgerPath,
+	listLedgers,
+	liveSubagentScratch,
+	processStartToken,
+	readLedger,
+	realTempRoot,
+	removeArtifact,
+	removeSessionScratch,
+	scratchRefusal,
+	SWEEP_GRACE_MS,
+	type ArtifactCheck,
+	type ArtifactTarget,
+	type ScratchArtifact,
+	type ScratchLedger,
+	type StoredLedger,
+	writeLedger,
+} 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 = (path: string, ledger: ScratchLedger) => {
+		try {
+			if (ledger.scratchDir === null && ledger.artifacts.length === 0) deleteLedger(path);
+			else writeLedger(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(listLedgers(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;
+		}
+		persist(session.path, ledger);
+		activeSessions.delete(env);
+		pending.clear();
+	};
+
+	// S5(b): scratch of ended sessions past the grace period; their artifacts stay for the command.
+	const sweep = (ownPath: string) => {
+		const ledgers = listLedgers(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() });
+			persist(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!));
+	};
+
+	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 });
+			persist(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(listLedgers(configHome()))(path, ledger);
+			removeSessionScratch(previous, scratchDir ? [...held, scratchDir] : held, { ownRoot: ownRoot(), liveSubagentDirs: subagentDirs() });
+		}
+		activeSessions.set(env, { sessionId, path, ledger });
+		persist(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.
+	const capture = (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) persist(session.path, ledger);
+	};
+
+	const endedLedgers = (ownPath: string | undefined) =>
+		listLedgers(configHome()).filter(({ path, ledger }) => path !== ownPath && !isLive(ledger));
+
+	const describe = (artifact: ScratchArtifact) => `${artifact.kind} ${artifact.path}`;
+
+	const list = (): 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 = 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 }] : []),
+			...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(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) 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", (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 { 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(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);
+}