gentle-pi 4.2.0 → 4.4.0

package/tests/session-scratch.test.ts

@@ -0,0 +1,1011 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import test, { type TestContext } from "node:test";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createSessionScratchExtension, SCRATCH_COMMAND_USAGE } from "../extensions/session-scratch.ts";
+import * as scratchLib from "../lib/session-scratch.ts";
+import { gitArtifactTargets, LEDGER_ARTIFACTS_CAP, LEDGER_VERSION, type ScratchLedger } from "../lib/session-scratch.ts";
+
+// Session scratch and artifact ledger (odd/tasks/session-scratch-ledger.md):
+// the runtime owns the parent session's TMPDIR and the clones/worktrees it
+// creates, records them in a per-session ledger, and removes only what it
+// created and recorded. Every fixture lives under one private test root.
+
+type Handler = (event: unknown, ctx: ExtensionContext) => unknown;
+type Command = { description?: string; handler: (args: string, ctx: ExtensionContext) => Promise<void> };
+
+interface Fixture { root: string; base: string; configHome: string; cwd: string; work: string }
+
+function fixture(t: TestContext): Fixture {
+	const root = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-session-scratch-test-")));
+	const fx = { root, base: join(root, "tmp"), configHome: join(root, "config"), cwd: join(root, "project"), work: join(root, "work") };
+	for (const path of [fx.base, fx.configHome, fx.cwd, fx.work]) mkdirSync(path, { recursive: true });
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	return fx;
+}
+
+type ExtensionFactory = typeof createSessionScratchExtension;
+
+interface Options {
+	sessionId?: string; child?: boolean; hasUI?: boolean; confirm?: boolean; isProcessAlive?: (pid: number) => boolean; now?: () => number; platform?: NodeJS.Platform; tmp?: string;
+	processStartToken?: (pid: number) => string | undefined;
+	/** A shared process environment, as a reload re-runs the extension against the same `process.env`. */
+	env?: NodeJS.ProcessEnv;
+	/** The factory of a separately loaded module instance. */
+	factory?: ExtensionFactory;
+	/** Runs while the confirmation is open, before the user answers. */
+	duringConfirm?: () => void;
+}
+
+interface BashOptions { isError?: boolean; toolName?: string }
+
+let toolCallCount = 0;
+
+function session(fx: Fixture, options: Options = {}) {
+	const handlers = new Map<string, Handler>();
+	const commands = new Map<string, Command>();
+	const notes: string[] = [];
+	const confirms: string[] = [];
+	const env: NodeJS.ProcessEnv = options.env ?? { TMPDIR: options.tmp ?? fx.base, GENTLE_PI_CONFIG_HOME: fx.configHome, ...(options.child ? { GENTLE_PI_AGENTS_CHILD: "1" } : {}) };
+	const pi = {
+		on: (name: string, handler: Handler) => { handlers.set(name, handler); },
+		registerCommand: (name: string, command: Command) => { commands.set(name, command); },
+	} as unknown as ExtensionAPI;
+	(options.factory ?? createSessionScratchExtension)({ env, isProcessAlive: options.isProcessAlive, processStartToken: options.processStartToken, now: options.now, platform: options.platform })(pi);
+	const ctx = {
+		cwd: fx.cwd,
+		hasUI: options.hasUI ?? true,
+		sessionManager: { getSessionId: () => options.sessionId ?? "s-1" },
+		ui: {
+			notify: (message: string) => { notes.push(message); },
+			confirm: async (title: string, message: string) => { confirms.push(`${title}\n${message}`); options.duringConfirm?.(); return options.confirm ?? true; },
+		},
+	} as unknown as ExtensionContext;
+	const emit = async (name: string, event: unknown) => await handlers.get(name)?.(event, ctx);
+	return {
+		env, handlers, commands, notes, confirms, ctx,
+		start: (reason = "startup") => emit("session_start", { type: "session_start", reason }),
+		shutdown: (reason = "quit") => emit("session_shutdown", { type: "session_shutdown", reason }),
+		// The call event, then the command's effect on disk, then its result, as Pi runs a tool.
+		bash: async (command: string, effect?: () => void, { isError = false, toolName = "bash" }: BashOptions = {}) => {
+			const toolCallId = `c${++toolCallCount}`;
+			await emit("tool_call", { type: "tool_call", toolName, toolCallId, input: { command } });
+			effect?.();
+			return await emit("tool_result", { type: "tool_result", toolName, toolCallId, input: { command }, content: [], isError });
+		},
+		run: async (args: string) => { await commands.get("gentle:scratch")!.handler(args, ctx); return notes.at(-1) ?? ""; },
+	};
+}
+
+const ledgerFile = (fx: Fixture, sessionId: string) => join(fx.configHome, "scratch", `${sessionId}.json`);
+const readLedger = (fx: Fixture, sessionId: string) => JSON.parse(readFileSync(ledgerFile(fx, sessionId), "utf8")) as ScratchLedger;
+
+function git(cwd: string, ...args: string[]): string {
+	return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", "-c", "init.defaultBranch=main", ...args], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function origin(fx: Fixture): string {
+	const path = join(fx.work, "origin");
+	mkdirSync(path);
+	git(path, "init", "-q");
+	writeFileSync(join(path, "a.txt"), "a\n");
+	git(path, "add", "a.txt");
+	git(path, "commit", "-q", "-m", "init");
+	return path;
+}
+
+function writeForeignLedger(fx: Fixture, ledger: Partial<ScratchLedger> & { sessionId: string }): void {
+	mkdirSync(join(fx.configHome, "scratch"), { recursive: true });
+	const full: ScratchLedger = { version: LEDGER_VERSION, pid: 999_999, processStartedAt: new Date(0).toISOString(), cwd: fx.cwd, tempRoot: fx.base, inherited: { TMPDIR: fx.base }, scratchDir: null, artifacts: [], ...ledger };
+	writeFileSync(ledgerFile(fx, ledger.sessionId), JSON.stringify(full));
+}
+
+const later = () => Date.now() + 2 * 3_600_000;
+// clean keeps the live scratch's entries changed in the last minute (advisories S5).
+const minutesLater = () => Date.now() + 2 * 60_000;
+
+// S2
+
+// Pi's /reload re-evaluates every extension module (jiti `moduleCache: false`
+// after `clearExtensionCache()`), so the module-level state is new; a fresh
+// import with a cache-busting query string is a separate module instance.
+const loadInstance = async (tag: string): Promise<ExtensionFactory> =>
+	((await import(`../extensions/session-scratch.ts?instance=${tag}-${Date.now()}`)) as { createSessionScratchExtension: ExtensionFactory }).createSessionScratchExtension;
+
+// Native review R3-scratch-socket-path-length: TMPDIR now points at the scratch, and
+// Unix socket paths are capped near 104 bytes, so the name must stay short (S9).
+const SCRATCH_NAME = /^gp[A-Za-z0-9]{6}$/;
+
+test("S9: the scratch name is gpXXXXXX whatever the session id", async (t) => {
+	const fx = fixture(t);
+	const s = session(fx, { sessionId: "a".repeat(64) });
+	await s.start();
+	assert.match(basename(s.env.TMPDIR!), SCRATCH_NAME);
+	await s.shutdown();
+});
+
+test("S9: TMPDIR keeps the inherited spelling while the ledger records real paths", async (t) => {
+	const fx = fixture(t);
+	const link = join(fx.root, "tmp-link");
+	symlinkSync(fx.base, link, "dir");
+	const env: NodeJS.ProcessEnv = { TMPDIR: link, GENTLE_PI_CONFIG_HOME: fx.configHome };
+	const first = session(fx, { env, factory: await loadInstance("spelling-a") });
+	await first.start();
+	const scratch = env.TMPDIR!;
+	assert.equal(dirname(scratch), link, "the TMPDIR value joins the inherited value, never a real path");
+	const ledger = readLedger(fx, "s-1");
+	assert.equal(ledger.scratchDir, join(fx.base, basename(scratch)));
+	assert.equal(ledger.tempRoot, fx.base);
+	assert.deepEqual(ledger.inherited, { TMPDIR: link });
+	writeFileSync(join(scratch, "work.txt"), "x");
+	await first.shutdown("reload");
+	const second = session(fx, { env, factory: await loadInstance("spelling-b") });
+	await second.start("reload");
+	assert.equal(env.TMPDIR, scratch, "a reload recovers the scratch under the same spelling");
+	assert.deepEqual(readdirSync(fx.base), [basename(scratch)]);
+	await second.shutdown("quit");
+	assert.deepEqual(readdirSync(fx.base), []);
+	assert.equal(env.TMPDIR, link);
+});
+
+test("S2: a primary session points TMPDIR at a private session scratch under the inherited one", async (t) => {
+	const fx = fixture(t);
+	const s = session(fx, { sessionId: "abc/../1" });
+	await s.start();
+	const scratch = s.env.TMPDIR!;
+	assert.equal(dirname(scratch), fx.base);
+	assert.match(basename(scratch), SCRATCH_NAME);
+	assert.ok(statSync(scratch).isDirectory());
+	if (process.platform !== "win32") assert.equal(statSync(scratch).mode & 0o777, 0o700);
+	assert.equal(s.env.TMP, undefined, "TMP/TEMP are only set on win32");
+});
+
+test("S2: on win32 TMP and TEMP follow the session scratch", async (t) => {
+	const fx = fixture(t);
+	const s = session(fx, { platform: "win32" });
+	await s.start();
+	assert.equal(s.env.TMP, s.env.TMPDIR);
+	assert.equal(s.env.TEMP, s.env.TMPDIR);
+	await s.shutdown();
+	assert.equal(s.env.TMPDIR, fx.base);
+	assert.equal(s.env.TMP, undefined);
+	assert.equal(s.env.TEMP, undefined);
+});
+
+test("S2: a child session creates no scratch, ledger, capture, or command", async (t) => {
+	const fx = fixture(t);
+	const s = session(fx, { child: true });
+	await s.start();
+	assert.equal(s.env.TMPDIR, fx.base);
+	assert.equal(s.commands.has("gentle:scratch"), false);
+	assert.equal(s.handlers.size, 0);
+	assert.deepEqual(readdirSync(fx.base), []);
+	assert.equal(existsSync(join(fx.configHome, "scratch")), false);
+	// Parent control: the same fixture in a primary session does create one.
+	const parent = session(fx);
+	await parent.start();
+	assert.notEqual(parent.env.TMPDIR, fx.base);
+	await parent.shutdown();
+});
+
+test("S2: when the scratch cannot be created the session keeps the inherited TMPDIR", async (t) => {
+	const fx = fixture(t);
+	const missing = join(fx.root, "missing");
+	const s = session(fx, { tmp: missing });
+	await s.start();
+	assert.equal(s.env.TMPDIR, missing);
+	assert.equal(existsSync(missing), false);
+});
+
+test("S2/S5: reload keeps the same scratch; quit removes it and restores TMPDIR", async (t) => {
+	const fx = fixture(t);
+	const s = session(fx);
+	await s.start();
+	const scratch = s.env.TMPDIR!;
+	writeFileSync(join(scratch, "work.txt"), "x");
+	await s.shutdown("reload");
+	await s.start("reload");
+	assert.equal(s.env.TMPDIR, scratch);
+	assert.ok(existsSync(join(scratch, "work.txt")));
+	await s.shutdown("quit");
+	assert.equal(existsSync(scratch), false);
+	assert.equal(s.env.TMPDIR, fx.base);
+	assert.equal(existsSync(ledgerFile(fx, "s-1")), false, "a ledger without artifacts is deleted");
+});
+
+test("S2/S5: a reload into a fresh module instance recovers the live scratch from the ledger and quit removes it once", async (t) => {
+	const fx = fixture(t);
+	const env: NodeJS.ProcessEnv = { TMPDIR: fx.base, GENTLE_PI_CONFIG_HOME: fx.configHome };
+	const first = session(fx, { env, factory: await loadInstance("first") });
+	await first.start();
+	const scratch = env.TMPDIR!;
+	assert.notEqual(scratch, fx.base);
+	writeFileSync(join(scratch, "work.txt"), "x");
+	await first.shutdown("reload");
+	const second = session(fx, { env, factory: await loadInstance("second") });
+	assert.notEqual(second.handlers.get("session_start"), first.handlers.get("session_start"), "the second instance is a separate module evaluation");
+	await second.start("reload");
+	assert.equal(env.TMPDIR, scratch, "TMPDIR is unchanged");
+	assert.equal(readFileSync(join(scratch, "work.txt"), "utf8"), "x", "the live scratch survives the reload");
+	assert.deepEqual(readdirSync(fx.base), [basename(scratch)], "no second scratch is created");
+	assert.equal(readLedger(fx, "s-1").scratchDir, scratch);
+	await second.shutdown("quit");
+	assert.deepEqual(readdirSync(fx.base), [], "quit removes the one scratch");
+	assert.equal(env.TMPDIR, fx.base, "the inherited TMPDIR recorded in the ledger is restored");
+	assert.equal(existsSync(ledgerFile(fx, "s-1")), false);
+	// The first instance saw only the reload shutdown and removes nothing more.
+	await first.shutdown("quit");
+	assert.equal(env.TMPDIR, fx.base);
+});
+
+test("S5: startup never removes a scratch of this process that TMPDIR no longer points into", async (t) => {
+	const fx = fixture(t);
+	const env: NodeJS.ProcessEnv = { TMPDIR: fx.base, GENTLE_PI_CONFIG_HOME: fx.configHome };
+	const first = session(fx, { env, factory: await loadInstance("keep-a") });
+	await first.start();
+	const scratch = env.TMPDIR!;
+	writeFileSync(join(scratch, "work.txt"), "x");
+	env.TMPDIR = fx.base;
+	const second = session(fx, { env, factory: await loadInstance("keep-b") });
+	await second.start("reload");
+	assert.ok(existsSync(join(scratch, "work.txt")), "a scratch owned by this pid is never removed at startup");
+	await second.shutdown();
+});
+
+test("S5: a session replacement removes the old scratch and the new session gets its own", async (t) => {
+	const fx = fixture(t);
+	let id = "first";
+	const s = session(fx);
+	(s.ctx.sessionManager as { getSessionId: () => string }).getSessionId = () => id;
+	await s.start();
+	const first = s.env.TMPDIR!;
+	await s.shutdown("new");
+	id = "second";
+	await s.start("new");
+	assert.equal(existsSync(first), false);
+	assert.equal(dirname(s.env.TMPDIR!), fx.base, "the new scratch nests under the inherited TMPDIR, not the old scratch");
+	assert.match(basename(s.env.TMPDIR!), SCRATCH_NAME);
+	await s.shutdown();
+});
+
+// S3
+
+test("S3: the ledger records the session, owning process, cwd and scratch, written atomically and privately", async (t) => {
+	const fx = fixture(t);
+	const s = session(fx);
+	await s.start();
+	const ledger = readLedger(fx, "s-1");
+	assert.equal(ledger.version, LEDGER_VERSION);
+	assert.equal(ledger.sessionId, "s-1");
+	assert.equal(ledger.pid, process.pid);
+	assert.ok(!Number.isNaN(Date.parse(ledger.processStartedAt)));
+	assert.equal(ledger.cwd, fx.cwd);
+	assert.equal(ledger.scratchDir, s.env.TMPDIR);
+	assert.deepEqual(ledger.artifacts, []);
+	assert.deepEqual(readdirSync(join(fx.configHome, "scratch")), ["s-1.json"], "no temp file is left after the rename");
+	if (process.platform !== "win32") assert.equal(statSync(ledgerFile(fx, "s-1")).mode & 0o777, 0o600);
+	await s.shutdown();
+});
+
+// S4
+
+test("S4: clone and worktree destinations resolve against cd segments and git -C", () => {
+	const cwd = "/w";
+	const paths = (command: string) => gitArtifactTargets(command, cwd).map(({ kind, path }) => `${kind}:${path}`);
+	assert.deepEqual(paths("git clone https://example.com/org/repo.git"), ["clone:/w/repo"]);
+	assert.deepEqual(paths("git clone --depth 1 -b main git@github.com:org/tool.git dest"), ["clone:/w/dest"]);
+	assert.deepEqual(paths("git clone --origin=up ../a/"), ["clone:/w/a"]);
+	assert.deepEqual(paths("cd sub && git clone ../origin"), ["clone:/w/sub/origin"]);
+	assert.deepEqual(paths("cd sub && git clone ../o here"), ["clone:/w/sub/here"]);
+	assert.deepEqual(paths("git -C sub clone ../o d 2>&1 | tail -1"), ["clone:/w/sub/d"]);
+	assert.deepEqual(paths("GIT_TERMINAL_PROMPT=0 git clone x/b.bundle"), ["clone:/w/b"]);
+	assert.deepEqual(paths("git worktree add -b feat ../wt main"), ["worktree:/wt"]);
+	assert.deepEqual(paths("git worktree add --detach wt2 HEAD; git worktree add -B x \"with space\""), ["worktree:/w/wt2", "worktree:/w/with space"]);
+	for (const none of ["echo git clone x y", "git worktree list", "git clone", "git log --grep clone", "printf 'git worktree add z'"]) {
+		assert.deepEqual(paths(none), [], none);
+	}
+});
+
+test("S4: a successful foreground bash clone or worktree add is recorded with its command and time", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const s = session(fx);
+	await s.start();
+	const clone = `cd ${fx.work} && git clone -q ${source} copy`;
+	await s.bash(clone, () => git(fx.work, "clone", "-q", source, "copy"));
+	await s.bash(`git -C ${source} worktree add -q -b feat ../wt`, () => git(source, "worktree", "add", "-q", "-b", "feat", join(fx.work, "wt")));
+	const ledger = readLedger(fx, "s-1");
+	assert.deepEqual(ledger.artifacts.map(({ kind, path, command }) => ({ kind, path, command })), [
+		{ kind: "clone", path: join(fx.work, "copy"), command: clone },
+		{ kind: "worktree", path: join(fx.work, "wt"), command: `git -C ${source} worktree add -q -b feat ../wt` },
+	]);
+	assert.ok(ledger.artifacts.every((artifact) => !Number.isNaN(Date.parse(artifact.recordedAt))));
+	// The same path is recorded once.
+	await s.bash(clone, () => { rmSync(join(fx.work, "copy"), { recursive: true, force: true }); git(fx.work, "clone", "-q", source, "copy"); });
+	assert.equal(readLedger(fx, "s-1").artifacts.length, 2);
+	await s.shutdown();
+	assert.equal(readLedger(fx, "s-1").scratchDir, null, "the ledger survives shutdown while artifacts remain");
+});
+
+test("S4: failed, missing, non-bash, and child results are not recorded", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	git(fx.work, "clone", "-q", source, "copy");
+	const s = session(fx);
+	await s.start();
+	await s.bash(`cd ${fx.work} && git clone ${source} failed`, () => git(fx.work, "clone", "-q", source, "failed"), { isError: true });
+	await s.bash(`cd ${fx.work} && git clone ${source} never-created`);
+	await s.bash(`cd ${fx.work} && git clone ${source} background`, () => git(fx.work, "clone", "-q", source, "background"), { toolName: "bg_start" });
+	// A result without its call event has no before-state, so nothing is recorded.
+	git(fx.work, "clone", "-q", source, "no-call");
+	await s.handlers.get("tool_result")?.({ type: "tool_result", toolName: "bash", toolCallId: "unseen", input: { command: `cd ${fx.work} && git clone ${source} no-call` }, content: [], isError: false }, s.ctx);
+	assert.deepEqual(readLedger(fx, "s-1").artifacts, []);
+	const child = session(fx, { child: true, sessionId: "child" });
+	await child.start();
+	await child.bash(`cd ${fx.work} && git clone ${source} child-copy`, () => git(fx.work, "clone", "-q", source, "child-copy"));
+	assert.equal(existsSync(ledgerFile(fx, "child")), false);
+	await s.shutdown();
+});
+
+test("S4: a clone fallback over an existing user clone records nothing and clean keeps it", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	// The user's own clean, fully pushed clone, made before the session.
+	git(fx.work, "clone", "-q", source, "dir");
+	writeFileSync(join(fx.work, "dir", ".git", "info", "exclude"), "ignored.txt\n");
+	writeFileSync(join(fx.work, "dir", "ignored.txt"), "user data");
+	const s = session(fx);
+	await s.start();
+	await s.bash(`cd ${fx.work} && git clone ${source} dir || (cd dir && git pull)`, () => git(join(fx.work, "dir"), "pull", "-q"));
+	assert.deepEqual(readLedger(fx, "s-1").artifacts, [], "a destination that existed before the command is not the session's");
+	await s.run("clean");
+	assert.equal(s.confirms.length, 0);
+	assert.equal(readFileSync(join(fx.work, "dir", "ignored.txt"), "utf8"), "user data");
+	// Control: the same fallback creating the clone is recorded.
+	await s.bash(`cd ${fx.work} && git clone ${source} fresh || (cd fresh && git pull)`, () => git(fx.work, "clone", "-q", source, "fresh"));
+	assert.deepEqual(readLedger(fx, "s-1").artifacts.map((artifact) => artifact.path), [join(fx.work, "fresh")]);
+	await s.shutdown();
+});
+
+test("S4: a clone into the session directory or an ancestor of it is never recorded", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const s = session(fx);
+	await s.start();
+	await s.bash(`git clone ${source} .`, () => git(fx.cwd, "clone", "-q", source, "."));
+	await s.bash(`git clone ${source} ..`);
+	assert.deepEqual(readLedger(fx, "s-1").artifacts, []);
+	await s.shutdown();
+});
+
+// S5
+
+test("S5: startup sweeps the scratch of dead sessions past the grace period and keeps their artifacts", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const deadA = session(fx, { sessionId: "dead-a" });
+	await deadA.start();
+	const scratchA = deadA.env.TMPDIR!;
+	writeFileSync(join(scratchA, "left.txt"), "x");
+	const deadB = session(fx, { sessionId: "dead-b" });
+	await deadB.start();
+	const scratchB = deadB.env.TMPDIR!;
+	await deadB.bash(`cd ${fx.work} && git clone ${source} kept`, () => git(fx.work, "clone", "-q", source, "kept"));
+	// Neither session shut down (crash). A later session finds both owners dead.
+	const next = session(fx, { sessionId: "next", isProcessAlive: () => false, now: later });
+	await next.start();
+	assert.equal(existsSync(scratchA), false);
+	assert.equal(existsSync(scratchB), false);
+	assert.equal(existsSync(ledgerFile(fx, "dead-a")), false);
+	const b = readLedger(fx, "dead-b");
+	assert.equal(b.scratchDir, null);
+	assert.deepEqual(b.artifacts.map((artifact) => artifact.path), [join(fx.work, "kept")]);
+	assert.ok(existsSync(join(fx.work, "kept", "a.txt")), "the sweep never removes artifacts");
+	assert.ok(existsSync(next.env.TMPDIR!), "the sweep keeps the new session's own scratch");
+	await next.shutdown();
+});
+
+test("S5: the sweep keeps scratch of live owners and of ledgers younger than the grace period", async (t) => {
+	const fx = fixture(t);
+	const other = session(fx, { sessionId: "other" });
+	await other.start();
+	const scratch = other.env.TMPDIR!;
+	const live = session(fx, { sessionId: "live-check", isProcessAlive: () => true, now: later });
+	await live.start();
+	assert.ok(existsSync(scratch), "a live owning process keeps its scratch");
+	const young = session(fx, { sessionId: "young-check", isProcessAlive: () => false });
+	await young.start();
+	assert.ok(existsSync(scratch), "a ledger younger than the grace period keeps its scratch");
+	for (const s of [live, young, other]) await s.shutdown();
+});
+
+test("S5: the sweep refuses a symlinked scratch, a scratch outside the recorded root, and a directory without the scratch name", async (t) => {
+	const fx = fixture(t);
+	const victim = join(fx.root, "victim");
+	mkdirSync(victim);
+	writeFileSync(join(victim, "keep.txt"), "precious");
+	const link = join(fx.base, "gpLinkAA");
+	symlinkSync(victim, link, "dir");
+	writeForeignLedger(fx, { sessionId: "evil-link", scratchDir: link });
+	writeForeignLedger(fx, { sessionId: "evil-outside", scratchDir: victim });
+	const otherNames = ["gentle-pi-session-evil-prefix-BBBBBB", "gp-1234abcd-BBBBBB", "gpBBBBBBB", "gpBBBBB", "xpBBBBBB"].map((name) => join(fx.base, name));
+	for (const [index, dir] of otherNames.entries()) {
+		mkdirSync(dir);
+		writeFileSync(join(dir, "keep.txt"), "x");
+		writeForeignLedger(fx, { sessionId: `evil-prefix-${index}`, scratchDir: dir });
+	}
+	const s = session(fx, { sessionId: "sweeper", isProcessAlive: () => false, now: later });
+	await s.start();
+	assert.equal(readFileSync(join(victim, "keep.txt"), "utf8"), "precious");
+	assert.ok(lstatSync(link).isSymbolicLink());
+	for (const dir of otherNames) assert.ok(existsSync(join(dir, "keep.txt")), dir);
+	for (const id of ["evil-link", "evil-outside", ...otherNames.map((_, index) => `evil-prefix-${index}`)]) assert.ok(existsSync(ledgerFile(fx, id)), `${id} ledger is kept for the command`);
+	await s.shutdown();
+});
+
+test("S5: a forged ledger naming a session-prefixed directory outside its recorded temp root is refused", async (t) => {
+	const fx = fixture(t);
+	const forged = join(fx.work, "gpEvilAb");
+	mkdirSync(forged);
+	writeFileSync(join(forged, "keep.txt"), "precious");
+	writeForeignLedger(fx, { sessionId: "evil", tempRoot: fx.base, scratchDir: forged });
+	const rootless = join(fx.base, "gpRootAb");
+	mkdirSync(rootless);
+	writeForeignLedger(fx, { sessionId: "rootless", tempRoot: null, scratchDir: rootless });
+	const s = session(fx, { sessionId: "sweeper", isProcessAlive: () => false, now: later });
+	await s.start();
+	await s.run("clean");
+	assert.equal(readFileSync(join(forged, "keep.txt"), "utf8"), "precious");
+	assert.ok(existsSync(rootless), "a ledger without a recorded temp root names no removable scratch");
+	assert.equal(readLedger(fx, "evil").scratchDir, forged);
+	await s.shutdown();
+});
+
+// S9: without the session id in the name, a forged ledger could name another
+// session's live scratch; the ledger of a live session keeps it.
+test("S9: a dead forged ledger never removes the scratch a live session's ledger records, in the sweep or in clean", async (t) => {
+	const fx = fixture(t);
+	const livePid = 4_444_444;
+	const liveScratch = join(fx.base, "gpLiveAb");
+	mkdirSync(liveScratch);
+	writeFileSync(join(liveScratch, "work.txt"), "live");
+	writeForeignLedger(fx, { sessionId: "live", pid: livePid, scratchDir: liveScratch });
+	writeForeignLedger(fx, { sessionId: "forged", scratchDir: liveScratch });
+	// A forged scratch that holds a live session's scratch is kept too.
+	const outer = join(fx.base, "gpOuterA");
+	const nested = join(outer, "gpInnerA");
+	mkdirSync(nested, { recursive: true });
+	writeForeignLedger(fx, { sessionId: "nested-live", pid: livePid, tempRoot: outer, scratchDir: nested });
+	writeForeignLedger(fx, { sessionId: "forged-outer", scratchDir: outer });
+	const s = session(fx, { sessionId: "sweeper", isProcessAlive: (pid) => pid === livePid, now: later });
+	await s.start();
+	assert.equal(readFileSync(join(liveScratch, "work.txt"), "utf8"), "live", "the sweep keeps the live scratch");
+	assert.ok(existsSync(nested), "the sweep keeps a scratch holding a live one");
+	assert.equal(readLedger(fx, "forged").scratchDir, liveScratch);
+	await s.run("clean");
+	assert.equal(readFileSync(join(liveScratch, "work.txt"), "utf8"), "live", "clean keeps the live scratch");
+	assert.ok(existsSync(nested), "clean keeps a scratch holding a live one");
+	// This session's own scratch is live whatever the process check says.
+	const own = readLedger(fx, "sweeper").scratchDir!;
+	writeFileSync(join(own, "mine.txt"), "x");
+	writeForeignLedger(fx, { sessionId: "forged-own", scratchDir: own });
+	await s.run("clean");
+	assert.ok(existsSync(own), "clean keeps this session's scratch named by a forged ledger");
+	// Control: a dead ledger's own scratch that no live ledger records is removed.
+	const deadScratch = join(fx.base, "gpDeadAb");
+	mkdirSync(deadScratch);
+	writeForeignLedger(fx, { sessionId: "dead", scratchDir: deadScratch });
+	await s.run("clean");
+	assert.equal(existsSync(deadScratch), false);
+	await s.shutdown();
+	assert.equal(existsSync(own), false, "shutdown still removes the session's own scratch");
+});
+
+test("S5: a recorded temp root inside the home is accepted only when it is the session's own temp root", async (t) => {
+	const fx = fixture(t);
+	const home = process.env.HOME;
+	process.env.HOME = fx.root;
+	t.after(() => { if (home === undefined) delete process.env.HOME; else process.env.HOME = home; });
+	// fx.base and fx.work are now inside the home; fx.base is this session's inherited TMPDIR.
+	const foreign = join(fx.work, "gpHomeAb");
+	mkdirSync(foreign);
+	writeForeignLedger(fx, { sessionId: "home", tempRoot: fx.work, scratchDir: foreign });
+	const dead = join(fx.base, "gpDeadAb");
+	mkdirSync(dead);
+	writeForeignLedger(fx, { sessionId: "dead", tempRoot: fx.base, scratchDir: dead });
+	const s = session(fx, { sessionId: "sweeper", isProcessAlive: () => false, now: later });
+	await s.start();
+	assert.ok(existsSync(foreign), "a forged root inside the home is refused");
+	assert.equal(existsSync(dead), false, "an ended session under the same temp root is swept");
+	const scratch = s.env.TMPDIR!;
+	await s.shutdown();
+	assert.equal(existsSync(scratch), false, "the session's own scratch under a home temp root is removed");
+});
+
+// Native review R3-untracked-status-guard: `git status --porcelain` honors the user's
+// status.showUntrackedFiles, so with "no" a clone holding new work looked clean.
+test("S6: clean keeps a clone with untracked work even when status hides untracked files", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const s = session(fx);
+	await s.start();
+	await s.bash(`cd ${fx.work} && git clone ${source} hidden`, () => git(fx.work, "clone", "-q", source, "hidden"));
+	git(join(fx.work, "hidden"), "config", "status.showUntrackedFiles", "no");
+	writeFileSync(join(fx.work, "hidden", "work.txt"), "new work\n");
+	const out = await s.run("clean");
+	assert.equal(s.confirms.length, 0, "nothing is offered for removal");
+	assert.equal(readFileSync(join(fx.work, "hidden", "work.txt"), "utf8"), "new work\n");
+	assert.match(out, /hidden: uncommitted changes/);
+});
+
+test("S5: shutdown keeps a scratch that holds a recorded clone", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const s = session(fx);
+	await s.start();
+	const scratch = s.env.TMPDIR!;
+	await s.bash(`cd ${scratch} && git clone ${source} inside`, () => git(scratch, "clone", "-q", source, "inside"));
+	await s.shutdown();
+	assert.ok(existsSync(join(scratch, "inside", "a.txt")));
+	assert.equal(readLedger(fx, "s-1").scratchDir, scratch);
+});
+
+// S6
+
+test("S6: list shows the session scratch with its size and the artifacts of this and dead sessions only", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	git(fx.work, "clone", "-q", source, "dead");
+	git(fx.work, "clone", "-q", source, "live");
+	writeForeignLedger(fx, { sessionId: "dead-1", pid: 1_111_111, artifacts: [{ kind: "clone", path: join(fx.work, "dead"), command: "git clone", recordedAt: new Date().toISOString() }] });
+	writeForeignLedger(fx, { sessionId: "live-1", pid: 2_222_222, artifacts: [{ kind: "clone", path: join(fx.work, "live"), command: "git clone", recordedAt: new Date().toISOString() }] });
+	const s = session(fx, { isProcessAlive: (pid) => pid === 2_222_222 });
+	await s.start();
+	writeFileSync(join(s.env.TMPDIR!, "f.bin"), Buffer.alloc(2048));
+	await s.bash(`cd ${fx.work} && git clone ${source} mine`, () => git(fx.work, "clone", "-q", source, "mine"));
+	const out = await s.run("list");
+	assert.match(out, new RegExp(`Session scratch: ${s.env.TMPDIR!.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")} \\(2\\.0 KiB\\)`));
+	assert.match(out, /clone .*\/work\/mine \(this session\)/);
+	assert.match(out, /clone .*\/work\/dead \(session dead-1, ended\)/);
+	assert.doesNotMatch(out, /work\/live/);
+	assert.equal(await s.run(""), out, "no argument lists");
+	await s.shutdown();
+});
+
+test("S6: clean removes scratch without asking and, after one confirmation, only clean recorded worktrees and pushed clones", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const s = session(fx, { now: minutesLater });
+	await s.start();
+	const scratch = s.env.TMPDIR!;
+	writeFileSync(join(scratch, "junk.txt"), "x");
+	mkdirSync(join(scratch, "gaLiveAa"));
+	const add = async (args: string[], command: string) => { await s.bash(`cd ${fx.work} && ${command}`, () => git(fx.work, ...args)); };
+	await add(["clone", "-q", source, "pushed"], `git clone ${source} pushed`);
+	await add(["clone", "-q", source, "unpushed"], `git clone ${source} unpushed`);
+	git(join(fx.work, "unpushed"), "commit", "-q", "--allow-empty", "-m", "local");
+	await add(["clone", "-q", source, "dirty-clone"], `git clone ${source} dirty-clone`);
+	writeFileSync(join(fx.work, "dirty-clone", "new.txt"), "x");
+	await s.bash(`cd ${source} && git worktree add -b clean-wt ../wt-clean`, () => git(source, "worktree", "add", "-q", "-b", "clean-wt", join(fx.work, "wt-clean")));
+	await s.bash(`cd ${source} && git worktree add -b dirty-wt ../wt-dirty`, () => git(source, "worktree", "add", "-q", "-b", "dirty-wt", join(fx.work, "wt-dirty")));
+	writeFileSync(join(fx.work, "wt-dirty", "a.txt"), "changed\n");
+	git(fx.work, "clone", "-q", source, "unrecorded");
+	const out = await s.run("clean");
+	assert.equal(s.confirms.length, 1);
+	assert.match(s.confirms[0], /pushed/);
+	assert.match(s.confirms[0], /wt-clean/);
+	assert.match(s.confirms[0], /ignored files inside these paths are deleted too/);
+	assert.doesNotMatch(s.confirms[0], /work\/(unpushed|dirty-clone|wt-dirty)/);
+	assert.equal(existsSync(join(fx.work, "pushed")), false);
+	assert.equal(existsSync(join(fx.work, "wt-clean")), false);
+	assert.doesNotMatch(git(source, "worktree", "list"), /wt-clean/, "the worktree is removed and pruned");
+	assert.ok(existsSync(join(fx.work, "unpushed", "a.txt")));
+	assert.ok(existsSync(join(fx.work, "dirty-clone", "new.txt")));
+	assert.equal(readFileSync(join(fx.work, "wt-dirty", "a.txt"), "utf8"), "changed\n");
+	assert.ok(existsSync(join(fx.work, "unrecorded", "a.txt")), "paths outside the recorded set are never touched");
+	assert.match(out, /unpushed: commits not on any remote/);
+	assert.match(out, /dirty-clone: uncommitted changes/);
+	assert.match(out, /wt-dirty: uncommitted changes/);
+	assert.equal(existsSync(join(scratch, "junk.txt")), false);
+	assert.ok(existsSync(join(scratch, "gaLiveAa")), "live subagent scratch is left to the runner");
+	assert.ok(existsSync(scratch), "the session keeps its TMPDIR");
+	assert.deepEqual(readLedger(fx, "s-1").artifacts.map((artifact) => basename(artifact.path)).sort(), ["dirty-clone", "unpushed", "wt-dirty"]);
+	await s.shutdown();
+});
+
+test("S6: a declined confirmation keeps every artifact; without UI clean removes scratch only and reports artifacts", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const declined = session(fx, { confirm: false });
+	await declined.start();
+	await declined.bash(`cd ${fx.work} && git clone ${source} pushed`, () => git(fx.work, "clone", "-q", source, "pushed"));
+	await declined.run("clean");
+	assert.ok(existsSync(join(fx.work, "pushed", "a.txt")));
+	await declined.shutdown();
+	const headless = session(fx, { hasUI: false, sessionId: "headless", now: minutesLater });
+	await headless.start();
+	writeFileSync(join(headless.env.TMPDIR!, "junk.txt"), "x");
+	await headless.bash(`cd ${fx.work} && git clone ${source} headless-pushed`, () => git(fx.work, "clone", "-q", source, "headless-pushed"));
+	const out = await headless.run("clean");
+	assert.equal(headless.confirms.length, 0);
+	assert.ok(existsSync(join(fx.work, "headless-pushed", "a.txt")));
+	assert.equal(existsSync(join(headless.env.TMPDIR!, "junk.txt")), false);
+	assert.match(out, /headless-pushed/);
+	await headless.shutdown();
+});
+
+test("S6: clean refuses a recorded clone replaced by a symlink and leaves live sessions alone", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	git(fx.work, "clone", "-q", source, "real");
+	const s = session(fx, { isProcessAlive: (pid) => pid === 3_333_333 });
+	await s.start();
+	await s.bash(`cd ${fx.work} && git clone ${source} copy`, () => git(fx.work, "clone", "-q", source, "copy"));
+	renameSync(join(fx.work, "copy"), join(fx.work, "moved"));
+	symlinkSync(join(fx.work, "real"), join(fx.work, "copy"), "dir");
+	git(fx.work, "clone", "-q", source, "theirs");
+	const liveScratch = join(fx.base, "gpLiveCC");
+	mkdirSync(liveScratch);
+	writeForeignLedger(fx, { sessionId: "live-2", pid: 3_333_333, scratchDir: liveScratch, artifacts: [{ kind: "clone", path: join(fx.work, "theirs"), command: "git clone", recordedAt: new Date().toISOString() }] });
+	const out = await s.run("clean");
+	assert.equal(s.confirms.length, 0, "nothing removable, nothing to confirm");
+	assert.ok(lstatSync(join(fx.work, "copy")).isSymbolicLink());
+	assert.ok(existsSync(join(fx.work, "real", "a.txt")));
+	assert.ok(existsSync(join(fx.work, "theirs", "a.txt")));
+	assert.ok(existsSync(liveScratch));
+	assert.match(out, /copy: not the recorded directory/);
+	await s.shutdown();
+});
+
+// PR #2300 review: `--all` does not include a detached HEAD, so a commit made only
+// there looked pushed and the clone holding its only copy was removable.
+test("S6: clean keeps a clone whose detached HEAD has a commit on no remote", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const s = session(fx);
+	await s.start();
+	await s.bash(`cd ${fx.work} && git clone ${source} detached`, () => git(fx.work, "clone", "-q", source, "detached"));
+	const clone = join(fx.work, "detached");
+	git(clone, "checkout", "-q", "--detach", "HEAD");
+	git(clone, "commit", "-q", "--allow-empty", "-m", "only here");
+	const out = await s.run("clean");
+	assert.equal(s.confirms.length, 0, "nothing is offered for removal");
+	assert.ok(existsSync(join(clone, "a.txt")));
+	assert.match(out, /detached: commits not on any remote/);
+});
+
+// PR #2300 review: the check ran before the confirmation, so work added while it was
+// open was deleted with the clone.
+test("S6: clean checks a clone again after the confirmation and keeps it if it changed", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const clone = join(fx.work, "late");
+	const s = session(fx, { duringConfirm: () => writeFileSync(join(clone, "late.txt"), "written while asked\n") });
+	await s.start();
+	await s.bash(`cd ${fx.work} && git clone ${source} late`, () => git(fx.work, "clone", "-q", source, "late"));
+	const out = await s.run("clean");
+	assert.equal(s.confirms.length, 1, "the clean clone was offered");
+	assert.equal(readFileSync(join(clone, "late.txt"), "utf8"), "written while asked\n");
+	assert.match(out, /late: uncommitted changes/);
+});
+
+// PR #2300 review: a different directory put at the recorded path while the
+// confirmation was open is not the one that was checked, so it stays.
+test("S6: clean keeps a directory that replaced the checked clone at the same path", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const clone = join(fx.work, "swap");
+	const s = session(fx, { duringConfirm: () => {
+		renameSync(clone, join(fx.work, "swap-old"));
+		git(fx.work, "clone", "-q", source, "swap");
+		writeFileSync(join(clone, ".git", "marker"), "replacement\n");
+	} });
+	await s.start();
+	await s.bash(`cd ${fx.work} && git clone ${source} swap`, () => git(fx.work, "clone", "-q", source, "swap"));
+	const out = await s.run("clean");
+	assert.equal(s.confirms.length, 1, "the checked clone was offered");
+	assert.equal(readFileSync(join(clone, ".git", "marker"), "utf8"), "replacement\n", "the replacement stays");
+	assert.match(out, /swap: replaced after the check/);
+});
+
+// PR #2300 review: a recorded path whose parent became a file (ENOTDIR) is gone, not foreign.
+test("S6: a recorded clone whose parent is no longer a directory is reported gone and dropped", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const s = session(fx);
+	await s.start();
+	mkdirSync(join(fx.work, "nest"));
+	await s.bash(`cd ${fx.work}/nest && git clone ${source} c`, () => git(join(fx.work, "nest"), "clone", "-q", source, "c"));
+	rmSync(join(fx.work, "nest"), { recursive: true, force: true });
+	writeFileSync(join(fx.work, "nest"), "now a file\n");
+	const first = await s.run("clean");
+	assert.match(first, /Already gone: clone .*nest\/c/);
+	assert.doesNotMatch(await s.run("list"), /nest\/c/, "the stale entry is dropped");
+});
+
+test("S6: clean keeps a detached worktree whose commits are on no branch", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const s = session(fx);
+	await s.start();
+	await s.bash(`cd ${source} && git worktree add --detach ../detached`, () => git(source, "worktree", "add", "-q", "--detach", join(fx.work, "detached")));
+	git(join(fx.work, "detached"), "commit", "-q", "--allow-empty", "-m", "orphan");
+	const out = await s.run("clean");
+	assert.equal(s.confirms.length, 0);
+	assert.ok(existsSync(join(fx.work, "detached", "a.txt")));
+	assert.match(out, /detached: commits on no branch/);
+	await s.shutdown();
+});
+
+test("S6/S8: the command help names list and clean", async (t) => {
+	const fx = fixture(t);
+	const s = session(fx);
+	await s.start();
+	assert.match(s.commands.get("gentle:scratch")!.description ?? "", /list\|clean/);
+	assert.equal(await s.run("bogus"), SCRATCH_COMMAND_USAGE);
+	assert.match(SCRATCH_COMMAND_USAGE, /^Usage: \/gentle:scratch \[list\|clean\]/);
+	await s.shutdown();
+});
+
+test("S8: the reference documents the scratch dir, ledger, automatic cleanup, sweep rule, and the command help", () => {
+	const reference = readFileSync(new URL("../docs/readme-reference.md", import.meta.url), "utf8");
+	const section = reference.split("### Session scratch and artifact ledger\n")[1]?.split("\n### ")[0] ?? "";
+	for (const term of [
+		"`gpXXXXXX`", "never its real path", "`TMPDIR`", "`<config home>/scratch/<session id>.json`", "atomically",
+		"`version`", "`sessionId`", "`pid`", "`processStartedAt`", "`processStartToken`", "`cwd`", "`tempRoot`", "`inherited`", "`scratchDir`", "`artifacts`", "`git clone ... [<dir>]`", "`git worktree add ... <path>`",
+		"did not exist before the command", "recovers the live scratch from the ledger", "never removes a scratch of its own process",
+		"At session shutdown", "older than one hour", "never follows symlinks", "directly under the temp root its ledger recorded", "the ledger of a live session",
+		"`/gentle:scratch list`", "`/gentle:scratch clean`", "no uncommitted changes and no unpushed commits", "ignored files inside them are deleted too", "`git worktree remove`", "Without a UI",
+	]) assert.ok(section.includes(term), `scratch reference missing ${term}`);
+	assert.match(reference, /\| `\/gentle:scratch` +\| Lists \(`list`, the default\) or cleans \(`clean`\)/);
+	for (const line of SCRATCH_COMMAND_USAGE.split("\n").slice(1)) {
+		const [action] = line.trim().split(/\s+/);
+		assert.ok(section.includes(`\`/gentle:scratch ${action}\``), `reference missing the ${action} action from the help`);
+	}
+});
+
+// Native review advisories of gentle-shell#2300 (odd/tasks/scratch-review-advisories.md).
+
+// R3-pid-reuse-liveness: a pid the system reused for another process made an
+// ended session look live, so its scratch was never swept. The comparison uses
+// the OS's own start token, never the wall clock: a clock step must not make a
+// live session look ended (review-e6f96fb8f1a7b6c5 R1-start-time-mismatch).
+test("advisories S3: a ledger counts as live only when its pid has the start token the ledger recorded; an unreadable or missing token keeps it", async (t) => {
+	const fx = fixture(t);
+	const current = new Map([[5_555_550, "linux:900"], [5_555_551, "linux:100"], [5_555_553, "linux:900"]]);
+	const cases = [
+		{ name: "gpReuseA", token: "linux:100" },
+		{ name: "gpMatchA", token: "linux:100", startedAt: "2020-01-01T00:00:00.000Z" },
+		{ name: "gpNoTime", token: "linux:100" },
+		{ name: "gpOldLed", token: undefined },
+	];
+	const dirs = cases.map(({ name }) => join(fx.base, name));
+	for (const [index, { token, startedAt }] of cases.entries()) {
+		mkdirSync(dirs[index]);
+		writeForeignLedger(fx, { sessionId: `pid-${index}`, pid: 5_555_550 + index, scratchDir: dirs[index], ...(startedAt ? { processStartedAt: startedAt } : {}), ...(token ? { processStartToken: token } : {}) });
+	}
+	const s = session(fx, { sessionId: "sweeper", isProcessAlive: () => true, processStartToken: (pid) => current.get(pid), now: later });
+	await s.start();
+	assert.equal(existsSync(dirs[0]), false, "a reused pid has another start token: the session ended and its scratch is swept");
+	assert.ok(existsSync(dirs[1]), "the same start token is the same process, whatever the wall clock says");
+	assert.ok(existsSync(dirs[2]), "a start token that cannot be read keeps the ledger live");
+	assert.ok(existsSync(dirs[3]), "a ledger without a start token keeps pid liveness");
+	const listed = await s.run("list");
+	assert.doesNotMatch(listed, /pid-[123]/, "live ledgers are not listed as ended");
+	await s.shutdown();
+});
+
+test("advisories S3: the process start token is read from the OS, stable for a process, and skipped on Windows", () => {
+	const read = (scratchLib as { processStartToken?: (pid: number, platform?: NodeJS.Platform) => string | undefined }).processStartToken;
+	assert.equal(typeof read, "function", "lib/session-scratch.ts exports processStartToken");
+	assert.equal(read!(process.pid, "win32"), undefined, "Windows checks pid liveness only");
+	assert.equal(read!(2 ** 22 + 12_345), undefined, "a pid that does not exist has no start token");
+	if (process.platform === "linux" || process.platform === "darwin") {
+		const own = read!(process.pid);
+		assert.ok(typeof own === "string" && own.length > 0, `own start token ${own}`);
+		assert.equal(read!(process.pid), own, "the token of one process never changes");
+		assert.notEqual(read!(process.ppid), own, "another process has another token");
+	}
+});
+
+test("advisories S3: the ledger records the owning process's start token", async (t) => {
+	const fx = fixture(t);
+	const s = session(fx);
+	await s.start();
+	const ledger = readLedger(fx, "s-1") as ScratchLedger & { processStartToken?: string };
+	const own = (scratchLib as { processStartToken?: (pid: number) => string | undefined }).processStartToken?.(process.pid);
+	if (process.platform === "linux") assert.match(own ?? "", /^linux:\d+$/);
+	assert.equal(ledger.processStartToken, own);
+	await s.shutdown();
+});
+
+// R1-clone-removal-orphans-linked-worktrees: removing a clone left the worktrees
+// linked to it without a repository.
+test("advisories S4: clean keeps a recorded clone with linked worktrees; a prunable one does not count", async (t) => {
+	const fx = fixture(t);
+	const source = origin(fx);
+	const s = session(fx);
+	await s.start();
+	await s.bash(`cd ${fx.work} && git clone ${source} host`, () => git(fx.work, "clone", "-q", source, "host"));
+	const host = join(fx.work, "host");
+	git(host, "worktree", "add", "-q", "--detach", join(fx.work, "linked"));
+	const out = await s.run("clean");
+	assert.equal(s.confirms.length, 0, "nothing is offered for removal");
+	assert.ok(existsSync(join(host, "a.txt")));
+	assert.ok(existsSync(join(fx.work, "linked", "a.txt")));
+	assert.match(out, /host: has linked worktrees/);
+	// Control: once the linked worktree's directory is gone it is prunable, and the clone is removable.
+	rmSync(join(fx.work, "linked"), { recursive: true, force: true });
+	await s.run("clean");
+	assert.equal(s.confirms.length, 1);
+	assert.equal(existsSync(host), false);
+	await s.shutdown();
+});
+
+// R3-clean-empties-live-tmpdir: clean emptied the live TMPDIR while a running
+// command could still be using what it had just created there.
+test("advisories S5: clean keeps the live scratch's entries changed within the minute before it started", async (t) => {
+	const fx = fixture(t);
+	let offset = 0;
+	const s = session(fx, { now: () => Date.now() + offset });
+	await s.start();
+	const scratch = s.env.TMPDIR!;
+	writeFileSync(join(scratch, "fresh.txt"), "x");
+	mkdirSync(join(scratch, "tree", "deep"), { recursive: true });
+	writeFileSync(join(scratch, "tree", "deep", "f.txt"), "x");
+	mkdirSync(join(scratch, "gaChildA"));
+	offset = 30_000;
+	const out = await s.run("clean");
+	assert.ok(existsSync(join(scratch, "fresh.txt")), "an entry changed 30 s before clean stays");
+	assert.ok(existsSync(join(scratch, "tree", "deep", "f.txt")));
+	assert.match(out, /Emptied scratch .* except .*changed in the last minute/);
+	offset = 120_000;
+	await s.run("clean");
+	assert.deepEqual(readdirSync(scratch), ["gaChildA"], "entries older than a minute go; subagent scratch stays");
+	await s.shutdown();
+});
+
+// R3-reload-fallback-inherits-scratch: a reload that could not recover the scratch
+// recorded the old scratch as the inherited TMPDIR and nested the new one in it.
+test("advisories S6: a reload that cannot recover the scratch restores the ledger's inherited TMPDIR", async (t) => {
+	const fx = fixture(t);
+	const env: NodeJS.ProcessEnv = { TMPDIR: fx.base, GENTLE_PI_CONFIG_HOME: fx.configHome };
+	const first = session(fx, { env, factory: await loadInstance("fallback-a") });
+	await first.start();
+	const old = env.TMPDIR!;
+	await first.shutdown("reload");
+	rmSync(old, { recursive: true, force: true });
+	const second = session(fx, { env, factory: await loadInstance("fallback-b") });
+	await second.start("reload");
+	assert.equal(dirname(env.TMPDIR!), fx.base, "the new scratch nests under the inherited TMPDIR, not the old scratch");
+	assert.match(basename(env.TMPDIR!), SCRATCH_NAME);
+	assert.deepEqual(readLedger(fx, "s-1").inherited, { TMPDIR: fx.base });
+	await second.shutdown("quit");
+	assert.equal(env.TMPDIR, fx.base);
+});
+
+test("advisories S6: a reload fallback whose ledger recorded TMPDIR unset creates the new scratch in the system temp dir, not the old scratch", async (t) => {
+	if (process.platform === "win32") { t.skip("os.tmpdir() reads TMP/TEMP differently on Windows"); return; }
+	const fx = fixture(t);
+	// os.tmpdir() falls back to TMP when TMPDIR is unset, which keeps the fixture under its root.
+	const saved = { TMPDIR: process.env.TMPDIR, TMP: process.env.TMP, GENTLE_PI_CONFIG_HOME: process.env.GENTLE_PI_CONFIG_HOME, GENTLE_PI_AGENTS_CHILD: process.env.GENTLE_PI_AGENTS_CHILD };
+	t.after(() => { for (const [key, value] of Object.entries(saved)) { if (value === undefined) delete process.env[key]; else process.env[key] = value; } });
+	delete process.env.TMPDIR;
+	delete process.env.GENTLE_PI_AGENTS_CHILD; // The test runner may itself run inside a subagent.
+	process.env.TMP = fx.base;
+	process.env.GENTLE_PI_CONFIG_HOME = fx.configHome;
+	const first = session(fx, { env: process.env, factory: await loadInstance("unset-a") });
+	await first.start();
+	const old = process.env.TMPDIR!;
+	assert.equal(dirname(old), fx.base);
+	assert.deepEqual(readLedger(fx, "s-1").inherited, { TMPDIR: null });
+	await first.shutdown("reload");
+	rmSync(old, { recursive: true, force: true });
+	const second = session(fx, { env: process.env, factory: await loadInstance("unset-b") });
+	await second.start("reload");
+	assert.equal(dirname(process.env.TMPDIR ?? ""), fx.base, "tmpdir() is asked with the old scratch no longer in TMPDIR");
+	assert.deepEqual(readLedger(fx, "s-1").inherited, { TMPDIR: null });
+	await second.shutdown("quit");
+	assert.equal(process.env.TMPDIR, undefined);
+});
+
+test("advisories S6: a reload without a readable ledger never inherits a gpXXXXXX TMPDIR", async (t) => {
+	const fx = fixture(t);
+	const env: NodeJS.ProcessEnv = { TMPDIR: fx.base, GENTLE_PI_CONFIG_HOME: fx.configHome };
+	const first = session(fx, { env, factory: await loadInstance("lost-a") });
+	await first.start();
+	const old = env.TMPDIR!;
+	await first.shutdown("reload");
+	writeFileSync(ledgerFile(fx, "s-1"), "{}");
+	const second = session(fx, { env, factory: await loadInstance("lost-b") });
+	await second.start("reload");
+	assert.equal(dirname(env.TMPDIR!), fx.base, "the new scratch is not nested in the old one");
+	assert.notEqual(env.TMPDIR, old);
+	assert.deepEqual(readLedger(fx, "s-1").inherited, { TMPDIR: fx.base });
+	await second.shutdown("quit");
+	assert.equal(env.TMPDIR, fx.base);
+	// Control: at startup a gpXXXXXX TMPDIR (a Pi started inside another session) is inherited as it is.
+	const nested = session(fx, { sessionId: "nested", tmp: old });
+	await nested.start();
+	assert.equal(dirname(nested.env.TMPDIR!), old);
+	await nested.shutdown();
+	assert.equal(nested.env.TMPDIR, old);
+});
+
+test("advisories S7: the reference documents the advisory rules", () => {
+	const reference = readFileSync(new URL("../docs/readme-reference.md", import.meta.url), "utf8");
+	const section = reference.split("### Session scratch and artifact ledger\n")[1]?.split("\n### ")[0] ?? "";
+	for (const term of [
+		"live or quarantined subagent", "a later startup sweep", "has a start token other than the one its ledger recorded", "never through the wall clock", "cannot be read", "has linked worktrees",
+		"changed in the last minute", "recorded `inherited` values", "not a `gpXXXXXX` directory",
+	]) assert.ok(section.includes(term), `scratch reference missing ${term}`);
+});
+
+// Perf (long-session audit): the ledger file I/O must not grow with the number
+// of retained ledgers or artifacts. `listLedgers` and `writeLedger` use only
+// the async fs seam, and `capture` keeps at most `LEDGER_ARTIFACTS_CAP`
+// artifacts, evicting the oldest first. Old pre-cap ledgers still read.
+
+test("perf: pushing beyond the cap keeps the ledger bounded and keeps the newest artifacts", async (t) => {
+	const fx = fixture(t);
+	const s = session(fx);
+	await s.start();
+	for (let i = 0; i < LEDGER_ARTIFACTS_CAP + 6; i++) {
+		await s.bash(`cd ${fx.work} && git clone x d${i}`, () => mkdirSync(join(fx.work, `d${i}`)));
+	}
+	const ledger = readLedger(fx, "s-1");
+	assert.equal(ledger.artifacts.length, LEDGER_ARTIFACTS_CAP, "the ledger file stays bounded at the cap");
+	assert.equal(basename(ledger.artifacts[0].path), `d6`, "eviction is oldest-first");
+	assert.equal(basename(ledger.artifacts.at(-1)!.path), `d${LEDGER_ARTIFACTS_CAP + 5}`, "the newest artifacts are kept");
+	assert.ok(!ledger.artifacts.some((artifact) => basename(artifact.path) === "d0"));
+	await s.shutdown();
+	// An old ledger written before the cap still reads, whole, by the pre-cap reader.
+	writeForeignLedger(fx, { sessionId: "pre-cap", artifacts: Array.from({ length: LEDGER_ARTIFACTS_CAP + 10 }, (_, i) => ({ kind: "clone" as const, path: join(fx.work, `old${i}`), command: "git clone", recordedAt: new Date(0).toISOString() })) });
+	const preCap = scratchLib.readLedger(ledgerFile(fx, "pre-cap"));
+	assert.equal(preCap?.artifacts.length, LEDGER_ARTIFACTS_CAP + 10, "a pre-cap ledger is read without pruning");
+	const stored = await scratchLib.listLedgers(fx.configHome);
+	assert.equal(stored.find(({ ledger: found }) => found.sessionId === "pre-cap")?.ledger.artifacts.length, LEDGER_ARTIFACTS_CAP + 10);
+	const out = await s.run("list");
+	assert.match(out, /old0 \(session pre-cap, ended\)/);
+});
+
+test("perf: listLedgers and writeLedger run on the async fs seam only", async (t) => {
+	const fx = fixture(t);
+	assert.equal(scratchLib.writeLedger.constructor.name, "AsyncFunction", "writeLedger is async");
+	assert.equal(scratchLib.listLedgers.constructor.name, "AsyncFunction", "listLedgers is async");
+	const saved = { ...scratchLib.ledgerFs };
+	const calls: Record<string, number> = {};
+	t.after(() => Object.assign(scratchLib.ledgerFs, saved));
+	for (const name of Object.keys(scratchLib.ledgerFs) as (keyof typeof scratchLib.ledgerFs)[]) {
+		(scratchLib.ledgerFs as Record<string, unknown>)[name] = async (...args: unknown[]) => {
+			calls[name] = (calls[name] ?? 0) + 1;
+			return await (saved[name] as (...rest: unknown[]) => unknown)(...args);
+		};
+	}
+	const ledger: ScratchLedger = { version: LEDGER_VERSION, sessionId: "async", pid: 1, processStartedAt: new Date(0).toISOString(), cwd: fx.cwd, tempRoot: null, inherited: {}, scratchDir: null, artifacts: [] };
+	await scratchLib.writeLedger(ledgerFile(fx, "async"), ledger);
+	for (const name of ["mkdir", "writeFile", "rename"]) assert.ok(calls[name], `writeLedger goes through the seam: ${name}`);
+	const stored = await scratchLib.listLedgers(fx.configHome);
+	assert.equal(stored.length, 1);
+	assert.equal(stored[0].ledger.sessionId, "async");
+	for (const name of ["readdir", "readFile", "stat"]) assert.ok(calls[name], `listLedgers goes through the seam: ${name}`);
+});
+
+test("perf: a failed ledger write leaves the previous ledger file intact", async (t) => {
+	if (process.getuid?.() === 0) { t.skip("a write never fails for root"); return; }
+	const fx = fixture(t);
+	const path = ledgerFile(fx, "intact");
+	const ledger: ScratchLedger = { version: LEDGER_VERSION, sessionId: "intact", pid: 1, processStartedAt: new Date(0).toISOString(), cwd: fx.cwd, tempRoot: null, inherited: {}, scratchDir: null, artifacts: [{ kind: "clone", path: join(fx.work, "kept"), command: "git clone", recordedAt: new Date(0).toISOString() }] };
+	await scratchLib.writeLedger(path, ledger);
+	chmodSync(dirname(path), 0o500);
+	try {
+		await assert.rejects(() => scratchLib.writeLedger(path, { ...ledger, sessionId: "lost" }));
+		assert.equal(scratchLib.readLedger(path)?.sessionId, "intact", "the previous ledger file survives the failed write");
+		assert.deepEqual(readdirSync(dirname(path)).filter((name) => name.endsWith(".tmp")), [], "no temp file is left behind");
+	} finally {
+		chmodSync(dirname(path), 0o700);
+	}
+});