gentle-pi 4.2.0 → 4.4.0

package/tests/writer-feature-document-admission.test.ts

@@ -0,0 +1,156 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import { rejectUndocumentedWriterLaunch } from "../lib/bounded-writer-admission.ts";
+import { CONTEXT_BACKSTOP_TOKENS_ENV } from "../lib/context-backstop.ts";
+
+// Pain-point iteration S16. Prompt rules alone did not stop small-task delegation: on a two-feature request the
+// orchestrator still started two writers for ~35-line units (USD 0.36 vs 0.20 inline). A generic writer launch is
+// now admitted only for a task of an existing ODD feature document, or when the parent's measured context reaches
+// the context backstop.
+
+const surfaces = "\n\n## Allowed edit surfaces\nsrc/budget.ts\n";
+
+function workspace(withDocument: boolean): string {
+	const root = mkdtempSync(join(tmpdir(), "writer-admission-"));
+	if (withDocument) {
+		mkdirSync(join(root, "odd", "tasks"), { recursive: true });
+		writeFileSync(join(root, "odd", "tasks", "ledger.md"), "# Ledger\n");
+	}
+	return root;
+}
+
+test("S16: a writer launch without a feature-document task is rejected with an inline instruction", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const denied = rejectUndocumentedWriterLaunch({ agent: "gentle-ai-worker", task: `Implement annual budgets.${surfaces}` }, { root, contextUsage: { tokens: 20_000, contextWindow: 400_000 } });
+	assert.ok(denied?.block, "the launch must be blocked");
+	assert.match(denied.reason, /write this unit inline yourself/);
+	assert.match(denied.reason, /do not retry/);
+	assert.match(denied.reason, /never create a feature document only to launch writers/);
+});
+
+test("S16: a writer naming a task of an existing feature document is admitted", (t) => {
+	const root = workspace(true);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const input = { agent: "gentle-ai-worker", task: `Spec: odd/tasks/ledger.md, T2, S3-S4. Read until ## Log.${surfaces}` };
+	assert.equal(rejectUndocumentedWriterLaunch(input, { root, contextUsage: { tokens: 20_000, contextWindow: 400_000 } }), undefined);
+	const viaContext = { agent: "worker", task: `Implement it.${surfaces}`, context: "Spec: odd/tasks/ledger.md, T1" };
+	assert.equal(rejectUndocumentedWriterLaunch(viaContext, { root, contextUsage: { tokens: 20_000, contextWindow: 400_000 } }), undefined);
+});
+
+test("S16: a Spec reference to a missing document, or one escaping the root, is rejected", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const spec of ["odd/tasks/ledger.md", "odd/tasks/../../etc/passwd.md"]) {
+		const denied = rejectUndocumentedWriterLaunch({ agent: "gentle-ai-worker", task: `Spec: ${spec}, T1${surfaces}` }, { root, contextUsage: { tokens: 20_000, contextWindow: 400_000 } });
+		assert.ok(denied?.block, `${spec} must not admit a writer`);
+	}
+});
+
+test("S16: the measured context backstop admits a writer without a document", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const input = { agent: "gentle-ai-worker", task: `Implement annual budgets.${surfaces}` };
+	assert.equal(rejectUndocumentedWriterLaunch(input, { root, contextUsage: { tokens: 150_000, contextWindow: 1_000_000 } }), undefined);
+	assert.ok(rejectUndocumentedWriterLaunch(input, { root, contextUsage: { tokens: 149_999, contextWindow: 1_000_000 } })?.block, "below the backstop does not admit");
+	assert.ok(rejectUndocumentedWriterLaunch(input, { root, contextUsage: { tokens: null, contextWindow: 400_000 } })?.block, "unknown context usage does not admit");
+	assert.ok(rejectUndocumentedWriterLaunch(input, { root, contextUsage: undefined })?.block, "missing context usage does not admit");
+});
+
+// Harness roadmap R1: the admission uses the same threshold as the runtime notice, min(absolute cap, fraction x
+// window), so a small context window reaches the backstop at 15% of its size instead of a fixed 150,000 tokens.
+test("S16: the admission backstop scales with the measured context window and honors the environment", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const input = { agent: "gentle-ai-worker", task: `Implement annual budgets.${surfaces}` };
+	const decide = (tokens: number, contextWindow: number, env?: NodeJS.ProcessEnv) => rejectUndocumentedWriterLaunch(input, { root, contextUsage: { tokens, contextWindow }, env })?.block ?? false;
+	assert.equal(decide(19_200, 128_000), false, "15% of a small window admits");
+	assert.equal(decide(19_199, 128_000), true);
+	assert.equal(decide(150_000, 1_000_000), false, "a large window keeps the absolute cap");
+	assert.equal(decide(149_999, 1_000_000), true);
+	assert.equal(decide(120_000, 1_000_000), true);
+	assert.equal(decide(120_000, 1_000_000, { [CONTEXT_BACKSTOP_TOKENS_ENV]: "100000" }), false, "the cap is overridable");
+});
+
+test("S16: previous behavior holds for non-writers and Judgment Day fix agents", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const agent of ["gentle-ai-explore", "gentle-ai-verify", "jd-fix-agent"]) {
+		assert.equal(rejectUndocumentedWriterLaunch({ agent, task: "Read src/budget.ts" }, { root, contextUsage: { tokens: 0, contextWindow: 400_000 } }), undefined, agent);
+	}
+});
+
+type ToolCallHandler = (event: { toolName: string; input: unknown }, ctx: ExtensionContext) => Promise<{ block?: boolean; reason?: string } | undefined>;
+
+function launchThroughHook(input: Record<string, unknown>, cwd: string, tokens: number, processEnv: NodeJS.ProcessEnv = {}, contextWindow = 272_000) {
+	const handlers = new Map<string, ToolCallHandler>();
+	const pi = { on(name: string, handler: ToolCallHandler) { handlers.set(name, handler); }, events: { emit() {} }, registerCommand() {}, registerTool() {} } as unknown as ExtensionAPI;
+	createGentleAiExtension({ nativeReviewCli: null, processEnv })(pi);
+	return handlers.get("tool_call")!({ toolName: "subagent_run", input }, {
+		cwd, hasUI: false, ui: { confirm: async () => true },
+		getContextUsage: () => ({ tokens, contextWindow, percent: Math.round((tokens / contextWindow) * 100) }),
+	} as unknown as ExtensionContext);
+}
+
+test("S16: the orchestrator tool_call hook blocks an undocumented writer and admits a documented one", async (t) => {
+	const bare = workspace(false);
+	const documented = workspace(true);
+	t.after(() => { rmSync(bare, { recursive: true, force: true }); rmSync(documented, { recursive: true, force: true }); });
+	const blocked = await launchThroughHook({ agent: "gentle-ai-worker", mode: "background", task: `Implement annual budgets.${surfaces}` }, bare, 20_000);
+	assert.equal(blocked?.block, true);
+	assert.match(blocked?.reason ?? "", /write this unit inline yourself/);
+	const admitted = await launchThroughHook({ agent: "gentle-ai-worker", mode: "background", task: `Spec: odd/tasks/ledger.md, T1. Read until ## Log.${surfaces}` }, documented, 20_000);
+	assert.equal(admitted?.block, undefined);
+	const explorer = await launchThroughHook({ agent: "gentle-ai-explore", mode: "task", task: "Map src/budget.ts" }, bare, 20_000);
+	assert.equal(explorer?.block, undefined, "read-only subagents are unaffected");
+	// The hook passes the measured window, not only the tokens: 19.2k of a 128k window is at the backstop.
+	const smallWindow = await launchThroughHook({ agent: "gentle-ai-worker", mode: "background", task: `Implement annual budgets.${surfaces}` }, bare, 19_200, {}, 128_000);
+	assert.equal(smallWindow?.block, undefined, "15% of the measured window admits");
+	const envCap = await launchThroughHook({ agent: "gentle-ai-worker", mode: "background", task: `Implement annual budgets.${surfaces}` }, bare, 19_200, { GENTLE_PI_CONTEXT_BACKSTOP_FRACTION: "0.9" }, 128_000);
+	assert.equal(envCap?.block, true, "the hook reads the session environment");
+});
+
+// Verifier B1: the delegation card tells the parent to write `Spec: odd/tasks/<feature>.md (read until "## Log").
+// Do T#; S#.`, and a live x6 run wrote `Spec: ... .md T1 S1;`. Both name a document task and must be admitted.
+test("S16: the delegation card format and a comma-free task reference are admitted", (t) => {
+	const root = workspace(true);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const line of [
+		'Spec: odd/tasks/ledger.md (read until "## Log"). Do T2; S3.',
+		"Spec: odd/tasks/ledger.md T1 S1; read through Tasks before Log.",
+		"- Spec: `odd/tasks/ledger.md`, T4",
+	]) {
+		assert.equal(rejectUndocumentedWriterLaunch({ agent: "gentle-ai-worker", task: `${line}\nImplement it.${surfaces}` }, { root, contextUsage: { tokens: 0, contextWindow: 400_000 } }), undefined, line);
+	}
+});
+
+test("S16: a Spec mention inside prose, outside odd/tasks, or through a symlink leaving the root is rejected", (t) => {
+	const root = workspace(true);
+	const outside = mkdtempSync(join(tmpdir(), "writer-admission-outside-"));
+	t.after(() => { rmSync(root, { recursive: true, force: true }); rmSync(outside, { recursive: true, force: true }); });
+	writeFileSync(join(root, "README.md"), "# readme\n");
+	writeFileSync(join(outside, "elsewhere.md"), "# elsewhere\n");
+	symlinkSync(join(outside, "elsewhere.md"), join(root, "odd", "tasks", "link-out.md"));
+	for (const task of [
+		"Do not use Spec: odd/tasks/ledger.md, T1 here.",
+		"Spec: odd/tasks/../../README.md, T1",
+		"Spec: odd/tasks/link-out.md, T1",
+	]) {
+		assert.ok(rejectUndocumentedWriterLaunch({ agent: "gentle-ai-worker", task: `${task}${surfaces}` }, { root, contextUsage: { tokens: 0, contextWindow: 400_000 } })?.block, task);
+	}
+});
+
+test("S16: child sessions are exempt and an empty workspace_root falls back to the session cwd", async (t) => {
+	const bare = workspace(false);
+	const documented = workspace(true);
+	t.after(() => { rmSync(bare, { recursive: true, force: true }); rmSync(documented, { recursive: true, force: true }); });
+	const child = await launchThroughHook({ agent: "gentle-ai-worker", mode: "background", task: `Implement it.${surfaces}` }, bare, 0, { GENTLE_PI_AGENTS_CHILD: "1" });
+	assert.equal(child?.block, undefined, "a child session is not gated");
+	const emptyRoot = await launchThroughHook({ agent: "gentle-ai-worker", mode: "background", workspace_root: "", task: `Spec: odd/tasks/ledger.md, T1${surfaces}` }, documented, 0);
+	assert.equal(emptyRoot?.block, undefined, "an empty workspace_root means the session cwd");
+});

package/tests/yolo-customize.test.ts

@@ -116,12 +116,15 @@ test("Customize selects Auto for this session and saves either elevated default
  view.handleInput("j");view.handleInput("j");view.render(140);
  assert.match(text(view),/Session permissions: AUTO/);
  await h.apply("\r");assert.equal(await h.controller().mode(h.ctx),"auto");
- view.handleInput("j");view.handleInput("j");view.handleInput("j");view.render(140);
+ view.handleInput("j");view.handleInput("j");view.handleInput("j");view.handleInput("j");view.render(140);
  assert.match(text(view),/Default permissions: AUTO/);
  await h.apply("\r");assert.equal(h.controller().defaultMode(),"auto");assert.equal(await h.controller().mode(h.ctx),"auto");
  view.handleInput("j");view.render(140);await h.apply("\r");
  assert.equal(h.controller().defaultMode(),"yolo");assert.equal(await h.controller().mode(h.ctx),"auto");
  assert.equal(JSON.parse(readFileSync(join(h.home,"permission-mode.json"),"utf8")).mode,"yolo");
+ view.handleInput("j");view.render(140);await h.apply("\r");
+ assert.equal(h.controller().defaultMode(),"super-yolo");assert.equal(await h.controller().mode(h.ctx),"auto");
+ assert.equal(JSON.parse(readFileSync(join(h.home,"permission-mode.json"),"utf8")).mode,"super-yolo");
  for(const width of [1,20,60,140])assert.ok(view.render(width).every(line=>visibleWidth(line)<=width));
  open.close();await open.result;
 });
@@ -269,3 +272,4 @@ test("real Theme and existing component obey narrow dimensions with invisible co
 	assert.equal(await h.controller().active(h.ctx), false);
 	open.close(); await open.result;
 });
+

package/tests/yolo-mode.test.ts

@@ -11,7 +11,7 @@ import { YOLO_STATUS_TEXT } from "../lib/yolo-session-policy.ts";
 const ON_TEXT = "🚀 YOLO ON 🔥 — destructive confirmations remain";
 const USAGE = "Use /gentle:yolo enable|disable|status. State unchanged.";
 const STALE_MENU = "YOLO unchanged — the session changed while the menu was open.";
-const menuTitle = (state: "ON" | "OFF") => `🚀 Gentle YOLO 🔥 — full speed, destructive actions still ask (current: ${state})`;
+const menuTitle = (state: "ON" | "OFF") => `🚀 Gentle YOLO 🔥 — standing permission (current: ${state})`;
 
 // An empty env would resolve the developer's real ~/.pi/gentle-ai and inherit its persisted mode default.
 const isolatedConfigHomes: string[] = [];
@@ -203,6 +203,24 @@ test("active YOLO waives only ordinary push after full destructive/guard evaluat
 	await h.command("disable"); assert.ok(await call("git push origin main"));
 });
 
+test("active YOLO waives a push with harmless redirections and a read-only filter; Normal and children still ask", async () => {
+	const command = "git push -u origin feat/x 2>&1 | tail -5";
+	const call = (h: ReturnType<typeof harness>, input: string) => h.emit("tool_call", { toolName: "bash", input: { command: input } });
+	const h = harness();
+	assert.ok(await call(h, "git push origin main 2>&1"), "Normal mode still confirms");
+	assert.equal(h.confirmations(), 1);
+	await h.command("enable");
+	assert.equal(await call(h, command), undefined);
+	assert.equal(await call(h, "git push origin main 2>&1"), undefined);
+	assert.equal(h.confirmations(), 1, "waived pushes never reach the confirmation dialog");
+	for (const asks of ["git push origin main | sh", "git push origin main > out.txt", "git push origin main 2>&1 | tee out"]) {
+		assert.ok(await call(h, asks), asks);
+	}
+	const child = harness({ GENTLE_PI_AGENTS_CHILD: "1" });
+	await child.command("enable");
+	assert.ok(await call(child, command), "children never receive the waiver");
+});
+
 test("active command path preserves configured push confirmations and blocks, including legacy env override", async () => {
 	const configHome = mkdtempSync(join(tmpdir(), "gentle-yolo-config-"));
 	const previousHome = process.env.GENTLE_PI_CONFIG_HOME;

package/tests/yolo-session-policy-capture.test.ts

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { registerYoloSessionPolicy } from "../lib/yolo-session-policy.ts";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// Identity is re-captured for every tool admission: freshness is a security
+// invariant, so cross-admission reuse is never allowed. Within one admission
+// the redundant mode() lookups share at most ONE capture, keyed by that
+// admission's tool call id; a different or absent id re-captures. Generation
+// bumps and cwd changes still invalidate a shared slot.
+
+const isolatedConfigHomes: string[] = [];
+process.once("exit", () => { for (const home of isolatedConfigHomes) rmSync(home, { recursive: true, force: true }); });
+
+function harness() {
+	const home = mkdtempSync(join(tmpdir(), "yolo-capture-config-"));
+	isolatedConfigHomes.push(home);
+	let resolveCalls = 0, statusCalls = 0, widgetCalls = 0;
+	const commands = new Map<string, { handler: (args: string, ctx: ExtensionContext) => Promise<void> }>();
+	const pi = {
+		registerCommand: (name: string, command: { handler: (args: string, ctx: ExtensionContext) => Promise<void> }) => commands.set(name, command),
+		events: { on: () => () => {} },
+	} as unknown as ExtensionAPI;
+	const controller = registerYoloSessionPolicy(pi, { GENTLE_PI_CONFIG_HOME: home }, {
+		// Test seam: observe identity resolution without spawning Git.
+		resolveIdentity: async () => { resolveCalls += 1; return undefined; },
+	});
+	const ctx = {
+		cwd: process.cwd(), mode: "tui", hasUI: true,
+		sessionManager: { getSessionId: () => "capture-test" },
+		ui: {
+			notify() {},
+			setStatus: () => { statusCalls += 1; },
+			setWidget: () => { widgetCalls += 1; },
+		},
+	} as unknown as ExtensionContext;
+	return {
+		controller, ctx, commands,
+		resolveCalls: () => resolveCalls,
+		uiCalls: () => ({ status: statusCalls, widget: widgetCalls }),
+	};
+}
+
+test("lookups of one tool admission share one capture; a second admission re-captures", async () => {
+	const h = harness();
+	assert.equal(await h.controller.mode(h.ctx, { toolCallId: "call-1" }), "normal");
+	assert.equal(h.resolveCalls(), 1, "the first admission captures");
+	await h.controller.mode(h.ctx, { toolCallId: "call-1" });
+	assert.equal(h.resolveCalls(), 1, "lookups of one tool call share one capture");
+	await h.controller.mode(h.ctx, { toolCallId: "call-2" });
+	assert.equal(h.resolveCalls(), 2, "a second admission re-captures even with unchanged generation and cwd");
+	await h.controller.mode(h.ctx);
+	assert.equal(h.resolveCalls(), 3, "an absent admission id keeps the uncached capture path");
+});
+
+// The tool admission key never outranks the generation: a bump mid-admission
+// (a reselected mode, a revocation) must force a fresh capture, never replay.
+test("a generation bump invalidates a shared admission slot", async () => {
+	const h = harness();
+	assert.equal(await h.controller.mode(h.ctx, { toolCallId: "call-1" }), "normal");
+	assert.equal(await h.controller.setMode("yolo", h.ctx), true);
+	const before = h.resolveCalls();
+	assert.equal(await h.controller.mode(h.ctx, { toolCallId: "call-1" }), "yolo", "the same admission id never answers a mode captured before the bump");
+	assert.equal(h.resolveCalls(), before + 1, "the bump forced a fresh capture");
+});
+
+test("after a mode change the next mode() re-captures and never answers the stale mode", async () => {
+	const h = harness();
+	assert.equal(await h.controller.mode(h.ctx), "normal");
+	assert.equal(await h.controller.setMode("yolo", h.ctx), true);
+	const resolveBefore = h.resolveCalls();
+	assert.equal(await h.controller.mode(h.ctx), "yolo", "a generation bump re-reads the live mode");
+	assert.equal(h.resolveCalls(), resolveBefore + 1, "the invalidated cache is re-captured, not reused");
+});
+
+test("publish writes UI only when the rendered strings change", async () => {
+	const h = harness();
+	await h.controller.mode(h.ctx);
+	const first = h.uiCalls();
+	assert.ok(first.status > 0 && first.widget > 0, "the first publication paints the status and widget");
+	await h.controller.mode(h.ctx);
+	assert.deepEqual(h.uiCalls(), first, "an unchanged mode() costs zero UI writes");
+	await h.controller.setMode("yolo", h.ctx);
+	const second = h.uiCalls();
+	assert.ok(second.status > first.status && second.widget > first.widget, "an actual change still publishes");
+	await h.controller.mode(h.ctx);
+	assert.deepEqual(h.uiCalls(), second, "reading the settled mode does not repaint");
+});
+
+test("a cwd change re-captures and revokes instead of answering a stale workspace mode", async () => {
+	const h = harness();
+	assert.equal(await h.controller.setMode("yolo", h.ctx), true);
+	const other = realpathSync(mkdtempSync(join(tmpdir(), "yolo-capture-cwd-")));
+	try {
+		Object.assign(h.ctx, { cwd: other });
+		assert.equal(await h.controller.mode(h.ctx), "normal", "the new workspace never inherits the old binding");
+		assert.equal(h.resolveCalls(), 2, "the cwd change forced a fresh capture");
+		await h.controller.mode(h.ctx);
+		assert.equal(h.resolveCalls(), 3, "a call without an admission id keeps the uncached capture path");
+	} finally { rmSync(other, { recursive: true, force: true }); }
+});

package/tests/yolo-temp-scratch.test.ts

@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { defaultTempScratchFs, isTempScratchTarget, type TempScratchFs } from "../lib/yolo-temp-scratch.ts";
+
+const ownDir = { uid: 1000, isDirectory: () => true, isFile: () => false, isSymbolicLink: () => false };
+const mock = (overrides: Partial<TempScratchFs> = {}): TempScratchFs => ({
+	uid: 1000, tmpdir: "/tmp", home: "/home/user",
+	lstat: () => ownDir,
+	...overrides,
+});
+
+test("temp roots are /tmp, /var/tmp and the resolved tmpdir, never the root itself", () => {
+	assert.equal(isTempScratchTarget("/tmp/tmp.abcdef", mock()), true);
+	assert.equal(isTempScratchTarget("/var/tmp/tmp.abcdef", mock()), true);
+	assert.equal(isTempScratchTarget("/run/user/1000/tmp.abcdef", mock({ tmpdir: "/run/user/1000" })), true);
+	for (const target of ["/tmp", "/var/tmp", "/run/user/1000/tmp.abcdef", "/", "/tmp.abcdef"]) {
+		assert.equal(isTempScratchTarget(target, mock()), false, target);
+	}
+});
+
+test("a tmpdir that is /, home, an ancestor or a descendant of home is not a temp root", () => {
+	for (const tmpdir of ["/", "/home/user", "/home", "/home/user/work/repo"]) {
+		const fs = mock({ tmpdir });
+		for (const target of ["/tmp.abcdef", "/home/user/tmp.abcdef", "/home/tmp.abcdef", "/home/user/work/repo/tmp.abcdef"]) {
+			assert.equal(isTempScratchTarget(target, fs), false, `${tmpdir}: ${target}`);
+		}
+	}
+	const ownFile = { uid: 1000, isDirectory: () => false, isFile: () => true, isSymbolicLink: () => false };
+	assert.equal(isTempScratchTarget("/home/gentleman/work/repo/README.md", mock({ home: "/home/gentleman", tmpdir: "/home/gentleman/work/repo", lstat: () => ownFile })), false);
+	assert.equal(isTempScratchTarget("/home/gentleman-tmp/x.log", mock({ home: "/home/gentleman", tmpdir: "/home/gentleman-tmp", lstat: () => ownFile })), true, "sibling prefix is not a descendant");
+});
+
+test("only mktemp-named own directories qualify; files need ownership, symlinks and missing paths always qualify", () => {
+	const dir = (uid: number) => ({ uid, isDirectory: () => true, isFile: () => false, isSymbolicLink: () => false });
+	assert.equal(isTempScratchTarget("/tmp/tmp.ab12CD", mock({ lstat: () => dir(1000) })), true);
+	assert.equal(isTempScratchTarget("/tmp/tmp.ab12C", mock({ lstat: () => dir(1000) })), false, "short suffix");
+	assert.equal(isTempScratchTarget("/tmp/cache", mock({ lstat: () => dir(1000) })), false, "non-mktemp name");
+	assert.equal(isTempScratchTarget("/tmp/tmp.ab12CD", mock({ lstat: () => dir(0) })), false, "other uid");
+	const other = { uid: 0, isDirectory: () => false, isFile: () => false, isSymbolicLink: () => false };
+	assert.equal(isTempScratchTarget("/tmp/fifo", mock({ lstat: () => other })), false, "special file");
+	assert.equal(isTempScratchTarget("/tmp/x.log", mock({ lstat: () => ({ ...other, uid: 1000, isFile: () => true }) })), true);
+	assert.equal(isTempScratchTarget("/tmp/x.log", mock({ lstat: () => ({ ...other, isFile: () => true }) })), false);
+	assert.equal(isTempScratchTarget("/tmp/link", mock({ lstat: () => ({ ...other, isSymbolicLink: () => true }) })), true);
+	const missing = () => { throw Object.assign(new Error("ENOENT"), { code: "ENOENT" }); };
+	assert.equal(isTempScratchTarget("/tmp/whatever", mock({ lstat: missing })), true);
+	const denied = () => { throw Object.assign(new Error("EACCES"), { code: "EACCES" }); };
+	assert.equal(isTempScratchTarget("/tmp/whatever", mock({ lstat: denied })), false);
+});
+
+test("the production probe recognizes a real mktemp directory, own file and symlink", () => {
+	const fs = defaultTempScratchFs();
+	if (fs.uid === undefined) return;
+	const root = realpathSync(tmpdir());
+	const scratch = mkdtempSync(join(root, "tmp."));
+	const file = join(root, `gentle-scratch-${process.pid}.log`);
+	const link = join(root, `gentle-scratch-${process.pid}.link`);
+	const named = mkdtempSync(join(root, "gentle-scratch-"));
+	try {
+		writeFileSync(file, "log");
+		symlinkSync(named, link);
+		assert.equal(isTempScratchTarget(scratch, fs), true, scratch);
+		assert.equal(isTempScratchTarget(file, fs), true, file);
+		assert.equal(isTempScratchTarget(link, fs), true, link);
+		assert.equal(isTempScratchTarget(named, fs), false, named);
+	} finally {
+		for (const path of [scratch, file, link, named]) rmSync(path, { recursive: true, force: true });
+	}
+});

package/scripts/mirror-odd-routing.mjs

@@ -1,242 +0,0 @@
-#!/usr/bin/env node
-// ODD routing drift ratchet — canonical fixture regeneration.
-//
-// gentle-pi hand-mirrors the always-on ODD routing block rendered by gentle-ai
-// `internal/components/agentguidance/routing.go` (RenderRouting). There is no
-// automated sync, so a canonical change leaves the pi mirror stale with nothing
-// catching it. This script renders the canonical block from a LOCAL gentle-ai
-// checkout and vendors it into `fixtures/odd-routing-canonical.md` with managed
-// provenance, where `tests/odd-routing-canonical-ratchet.test.ts` turns drift
-// into a failing test.
-//
-// This script NEVER fetches anything from the network (GOPROXY=off), NEVER
-// modifies the gentle-ai checkout beyond a transient temporary Go entrypoint
-// that it always deletes, and NEVER touches the installer release pin
-// (scripts/gentle-ai-installer.mjs INSTALLER_VERSION). Regeneration writes ONLY
-// the fixture; it never auto-rewrites the pi mirror assets.
-//
-// Usage:
-//   node scripts/mirror-odd-routing.mjs [--gentle-ai <path to local checkout>]
-
-import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-export const ODD_ROUTING_FIXTURE_RELATIVE = "fixtures/odd-routing-canonical.md";
-export const ODD_ROUTING_SOURCE_REPO = "https://github.com/Gentleman-Programming/gentle-ai";
-export const ODD_ROUTING_SOURCE_PATH = "internal/components/agentguidance/routing.go";
-export const ODD_ROUTING_HEADER_OPEN = "<!-- gentle-pi:managed-odd-routing-canonical\n";
-export const ODD_ROUTING_HEADER_CLOSE = "\n-->\n";
-export const ODD_ROUTING_TEMP_DIR = "tmp-odd-routing-dump";
-export const ODD_ROUTING_BLOCK_PREFIX = "## Implementation Routing";
-
-const GO_ENTRYPOINT = `package main
-
-import (
-	"fmt"
-	"os"
-
-	"github.com/gentleman-programming/gentle-ai/v4/internal/components/agentguidance"
-	"github.com/gentleman-programming/gentle-ai/v4/internal/model"
-)
-
-func main() {
-	rendered, err := agentguidance.RenderRouting(model.AgentPi)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, err)
-		os.Exit(1)
-	}
-	fmt.Print(rendered)
-}
-`;
-
-export function sha256Hex(value) {
-	return createHash("sha256").update(value).digest("hex");
-}
-
-export function parseOddRoutingFixture(raw) {
-	if (!raw.startsWith(ODD_ROUTING_HEADER_OPEN)) {
-		throw new Error(`fixture does not start with the managed header ${JSON.stringify(ODD_ROUTING_HEADER_OPEN)}`);
-	}
-	const headerEnd = raw.indexOf(ODD_ROUTING_HEADER_CLOSE, ODD_ROUTING_HEADER_OPEN.length);
-	if (headerEnd === -1) {
-		throw new Error(`fixture managed header is not terminated by ${JSON.stringify(ODD_ROUTING_HEADER_CLOSE)}`);
-	}
-	const headerText = raw.slice(ODD_ROUTING_HEADER_OPEN.length, headerEnd);
-	const body = raw.slice(headerEnd + ODD_ROUTING_HEADER_CLOSE.length);
-	const header = {};
-	for (const line of headerText.split("\n")) {
-		const separator = line.indexOf(": ");
-		if (separator === -1) continue;
-		header[line.slice(0, separator)] = line.slice(separator + 2);
-	}
-	return { header, body };
-}
-
-export function renderOddRoutingFixture(block, { sourceCommit, generatedAt }) {
-	const body = block.endsWith("\n") ? block : `${block}\n`;
-	const header = [
-		ODD_ROUTING_HEADER_OPEN.trimEnd(),
-		`source_repo: ${ODD_ROUTING_SOURCE_REPO}`,
-		`source_path: ${ODD_ROUTING_SOURCE_PATH}`,
-		`source_commit: ${sourceCommit}`,
-		`generated_at: ${generatedAt}`,
-		`block_sha256: ${sha256Hex(body)}`,
-		"-->",
-	].join("\n");
-	return `${header}\n${body}`;
-}
-
-// `git status --porcelain --untracked-files=no` emits one `XY PATH` line per
-// modified tracked file. Extract just the repository-relative path so the
-// fail-closed error can name what would make provenance unverifiable.
-export function parsePorcelainPaths(porcelainOutput) {
-	return porcelainOutput
-		.split("\n")
-		.map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line))
-		.filter((line) => line.length > 0)
-		.map((line) => line.slice(3).trim())
-		.filter((path) => path.length > 0);
-}
-
-// Fail closed when the checkout carries uncommitted changes to tracked files.
-// The fixture header asserts the rendered block came from the committed tree;
-// rendering a dirty tree under that claim would make the provenance a lie.
-// Untracked files never reach this guard because the git call excludes them.
-export function assertCleanGentleAiCheckout(porcelainOutput) {
-	const dirtyPaths = parsePorcelainPaths(porcelainOutput);
-	if (dirtyPaths.length > 0) {
-		throw new Error(
-			`gentle-ai checkout is dirty; provenance would be unverifiable: ${dirtyPaths.join(", ")}. Commit or stash first.`,
-		);
-	}
-}
-
-function parseArguments(argv) {
-	const values = { gentleAi: undefined };
-	for (let index = 0; index < argv.length; index += 2) {
-		const flag = argv[index];
-		const value = argv[index + 1];
-		if (flag !== "--gentle-ai" || value === undefined) {
-			throw new Error("usage: node scripts/mirror-odd-routing.mjs [--gentle-ai <path to local checkout>]");
-		}
-		if (values.gentleAi !== undefined) throw new Error("duplicate --gentle-ai argument");
-		values.gentleAi = value;
-	}
-	return values;
-}
-
-function requireGentleAiCheckout(gentleAiRoot) {
-	if (!existsSync(gentleAiRoot)) {
-		throw new Error(
-			`no gentle-ai checkout at ${gentleAiRoot}; pass --gentle-ai <path> or clone ${ODD_ROUTING_SOURCE_REPO} as a sibling of gentle-pi`,
-		);
-	}
-	const routingPath = join(gentleAiRoot, ...ODD_ROUTING_SOURCE_PATH.split("/"));
-	if (!existsSync(routingPath)) {
-		throw new Error(`not a gentle-ai checkout: missing ${routingPath}`);
-	}
-}
-
-export function renderCanonicalRouting(gentleAiRoot) {
-	const tempRoot = join(gentleAiRoot, ODD_ROUTING_TEMP_DIR);
-	// Clear any stale temp entrypoint from a previous crash so the render is clean.
-	rmSync(tempRoot, { recursive: true, force: true });
-	mkdirSync(tempRoot, { recursive: true });
-	try {
-		writeFileSync(join(tempRoot, "main.go"), GO_ENTRYPOINT, { encoding: "utf8" });
-		const rendered = execFileSync("go", ["run", `./${ODD_ROUTING_TEMP_DIR}`], {
-			cwd: gentleAiRoot,
-			encoding: "utf8",
-			// GOPROXY=off fails closed instead of downloading: this script must
-			// never touch the network.
-			env: { ...process.env, GOPROXY: "off" },
-			stdio: ["ignore", "pipe", "inherit"],
-		});
-		if (!rendered.startsWith(ODD_ROUTING_BLOCK_PREFIX)) {
-			throw new Error(
-				`RenderRouting(model.AgentPi) did not return the expected routing block (starts with ${JSON.stringify(ODD_ROUTING_BLOCK_PREFIX)})`,
-			);
-		}
-		return rendered;
-	} finally {
-		rmSync(tempRoot, { recursive: true, force: true });
-	}
-}
-
-// Resolve fixture provenance from the committed gentle-ai tree. `generatedAt`
-// is the committer date, not wall-clock time, so rendering the same commit
-// twice yields byte-identical fixture files. `execGit` is injectable for tests.
-export function resolveOddRoutingProvenance(gentleAiRoot, execGit) {
-	const git = execGit ?? ((args) => execFileSync("git", args, { cwd: gentleAiRoot, encoding: "utf8" }));
-	assertCleanGentleAiCheckout(git(["status", "--porcelain", "--untracked-files=no"]));
-	return {
-		sourceCommit: git(["rev-parse", "HEAD"]).trim(),
-		generatedAt: git(["show", "-s", "--format=%cI", "HEAD"]).trim(),
-	};
-}
-
-export function mirrorOddRouting(packageRoot, gentleAiRoot) {
-	requireGentleAiCheckout(gentleAiRoot);
-	// Resolve (and fail closed on dirty) provenance BEFORE rendering: the
-	// transient Go entrypoint must not run against a tree whose commit hash the
-	// fixture would misrepresent.
-	const provenance = resolveOddRoutingProvenance(gentleAiRoot);
-	const block = renderCanonicalRouting(gentleAiRoot);
-	const contents = renderOddRoutingFixture(block, provenance);
-
-	const fixturePath = join(resolve(packageRoot), ...ODD_ROUTING_FIXTURE_RELATIVE.split("/"));
-	const previous = readPreviousFixture(fixturePath);
-	mkdirSync(dirname(fixturePath), { recursive: true });
-
-	// Atomic overwrite: write a sibling temp file, then rename it into place.
-	const stagingPath = `${fixturePath}.tmp`;
-	try {
-		writeFileSync(stagingPath, contents, { encoding: "utf8" });
-		renameSync(stagingPath, fixturePath);
-	} finally {
-		rmSync(stagingPath, { force: true });
-	}
-
-	const next = parseOddRoutingFixture(contents);
-	return {
-		fixturePath,
-		sourceCommit: next.header.source_commit,
-		blockSha256: next.header.block_sha256,
-		changed: previous === undefined || previous.body !== next.body || previous.header.source_commit !== next.header.source_commit,
-		previous,
-	};
-}
-
-function readPreviousFixture(fixturePath) {
-	if (!existsSync(fixturePath)) return undefined;
-	const raw = readFileSync(fixturePath, "utf8");
-	// Verify the existing fixture before clobbering it: an unparseable file is a
-	// signal to inspect, not to silently overwrite.
-	const parsed = parseOddRoutingFixture(raw);
-	const recorded = parsed.header.block_sha256;
-	const actual = sha256Hex(parsed.body);
-	if (recorded !== undefined && recorded !== actual) {
-		console.warn(`warning: existing fixture body does not match its recorded digest (${recorded}); regenerating from canonical`);
-	}
-	return parsed;
-}
-
-async function main() {
-	const packageRoot = join(fileURLToPath(new URL("..", import.meta.url)));
-	const { gentleAi } = parseArguments(process.argv.slice(2));
-	const gentleAiRoot = resolve(gentleAi ?? join(packageRoot, "..", "gentle-ai"));
-	const result = mirrorOddRouting(packageRoot, gentleAiRoot);
-	console.log(`${result.changed ? "Wrote" : "Refreshed"} ${result.fixturePath}`);
-	console.log(`source commit ${result.sourceCommit}; block sha256 ${result.blockSha256}`);
-	if (result.previous !== undefined) {
-		console.log(`previous commit ${result.previous.header.source_commit}; previous block sha256 ${result.previous.header.block_sha256}`);
-	}
-}
-
-const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isMainModule) {
-	await main();
-}