gentle-pi 4.1.0 → 4.3.0

package/tests/standalone-config-home.test.ts

@@ -0,0 +1,324 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { chmodSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+import { gentlePiConfigHome } from "../lib/agent-home.ts";
+import { gentleAiDevBinaryRegistrationPath, gentleAiIsolationEnv } from "../lib/gentle-ai-binary.ts";
+import { GENTLE_SHELL_CONFIG_HOME_ENV, setBundledInstallForTesting } from "../lib/gentle-shell-bundled.ts";
+import { buildPiInvocation, migrateStandaloneConfig, standaloneConfigHome, type ResolvedHome } from "../lib/gentle-shell-launcher.ts";
+import { createActiveProfileReader } from "../extensions/gentle-shell.ts";
+import { readBannerConfig } from "../extensions/startup-banner.ts";
+
+// #2201 (S1, S1a): the standalone launcher's isolated home keeps Gentle Shell's
+// config next to its agent dir (~/.gentle-shell/gentle-ai), not in the shared
+// ~/.pi/gentle-ai that a Pi install with gentle-pi also uses.
+
+const posixOnly = { skip: process.platform === "win32" };
+const binPath = fileURLToPath(new URL("../bin/gentle-shell.mjs", import.meta.url));
+const MARKER = "GENTLE_SHELL_CONFIG_HOME";
+
+function scratch(): string {
+	return realpathSync(mkdtempSync(join(tmpdir(), "standalone-config-home-")));
+}
+
+function launch(home: ResolvedHome, baseEnv: Record<string, string | undefined> = {}, bundled = false) {
+	return buildPiInvocation({
+		runtime: { kind: "path", command: "fake-pi", args: [] },
+		home,
+		packageRoot: "/pkg",
+		declaration: undefined,
+		takeOver: false,
+		otherPackagePaths: [],
+		passthrough: [],
+		baseEnv,
+		homedir: "/os-home",
+		cwd: "/cwd",
+		bundled,
+	});
+}
+
+function isolated(dir = "/os-home/.gentle-shell/agent"): { home: ResolvedHome } {
+	return { home: { mode: "isolated", dir, source: "default" } };
+}
+
+test("the marker is exported under its launcher-owned name, never GENTLE_PI_CONFIG_HOME", () => {
+	assert.equal(GENTLE_SHELL_CONFIG_HOME_ENV, MARKER);
+});
+
+test("config home precedence: explicit GENTLE_PI_CONFIG_HOME > launcher marker > ~/.pi/gentle-ai; empty counts as unset", () => {
+	const home = scratch();
+	const env = (extra: Record<string, string>) => ({ HOME: home, USERPROFILE: home, ...extra });
+	const previous = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE };
+	process.env.HOME = home;
+	process.env.USERPROFILE = home;
+	try {
+		assert.equal(gentlePiConfigHome(env({})), join(home, ".pi", "gentle-ai"));
+		assert.equal(gentlePiConfigHome(env({ [MARKER]: "/shell/gentle-ai" })), "/shell/gentle-ai");
+		assert.equal(gentlePiConfigHome(env({ [MARKER]: "/shell/gentle-ai", GENTLE_PI_CONFIG_HOME: "/explicit" })), "/explicit");
+		assert.equal(gentlePiConfigHome(env({ [MARKER]: "/shell/gentle-ai", GENTLE_PI_CONFIG_HOME: "" })), "/shell/gentle-ai");
+		assert.equal(gentlePiConfigHome(env({ [MARKER]: "" })), join(home, ".pi", "gentle-ai"));
+		assert.equal(gentlePiConfigHome(env({ [MARKER]: "relative/gentle-ai" })), join(home, ".pi", "gentle-ai"), "a relative marker is ignored");
+	} finally {
+		for (const [key, value] of Object.entries(previous)) {
+			if (value === undefined) delete process.env[key];
+			else process.env[key] = value;
+		}
+	}
+});
+
+test("a bundled prefix still outranks the explicit override and the marker", (t) => {
+	const prefix = scratch();
+	setBundledInstallForTesting({ root: prefix });
+	t.after(() => setBundledInstallForTesting(undefined));
+	assert.equal(
+		gentlePiConfigHome({ GENTLE_SHELL_PREFIX: prefix, GENTLE_PI_CONFIG_HOME: "/explicit", [MARKER]: "/shell/gentle-ai" }),
+		join(prefix, "config", "gentle-ai"),
+	);
+});
+
+test("the banner and profile readers follow the same resolver, including an empty GENTLE_PI_CONFIG_HOME", async (t) => {
+	const root = scratch();
+	const config = join(root, "shell", "gentle-ai");
+	mkdirSync(config, { recursive: true });
+	writeFileSync(join(config, "banner.json"), JSON.stringify({ showTextLogo: false }));
+	writeFileSync(join(config, "profiles.json"), JSON.stringify({ kind: "gentle-pi.agent_model_profiles", version: 1, active: "fast", profiles: { fast: {} } }));
+	const previous = { marker: process.env[MARKER], explicit: process.env.GENTLE_PI_CONFIG_HOME };
+	process.env[MARKER] = config;
+	process.env.GENTLE_PI_CONFIG_HOME = "";
+	t.after(() => {
+		if (previous.marker === undefined) delete process.env[MARKER];
+		else process.env[MARKER] = previous.marker;
+		if (previous.explicit === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previous.explicit;
+	});
+	assert.equal((await readBannerConfig()).showTextLogo, false);
+	assert.equal(createActiveProfileReader({ [MARKER]: config, GENTLE_PI_CONFIG_HOME: "" })(), "fast");
+});
+
+test("the launcher gives Pi the marker only in its isolated home", () => {
+	const isolatedLaunch = launch(isolated().home);
+	assert.equal(isolatedLaunch.env[MARKER], "/os-home/.gentle-shell/gentle-ai");
+	assert.equal(isolatedLaunch.env.GENTLE_PI_CONFIG_HOME, undefined, "GENTLE_PI_CONFIG_HOME is never exported to Pi");
+	assert.equal(standaloneConfigHome(isolated().home), "/os-home/.gentle-shell/gentle-ai");
+	// A custom GENTLE_SHELL_HOME's parent may be anyone's folder (~/myagent ->
+	// ~/gentle-ai), so only a .gentle-shell/agent home gets its own config folder.
+	assert.equal(launch(isolated("/custom/shell/agent").home).env[MARKER], undefined, "no marker beside a custom GENTLE_SHELL_HOME");
+	assert.equal(standaloneConfigHome(isolated("/os-home/myagent").home), undefined, "never the generic ~/gentle-ai");
+	assert.equal(standaloneConfigHome(isolated("/data/.gentle-shell/agent").home), "/data/.gentle-shell/gentle-ai");
+});
+
+test("--link, a custom --home and a bundled launch keep today's config home and drop an inherited marker", () => {
+	const inherited = { [MARKER]: "/outer/gentle-ai" };
+	const link = launch({ mode: "link", dir: "/os-home/.pi/agent", source: "flag" }, inherited);
+	const path = launch({ mode: "path", dir: "/custom/home", source: "flag" }, inherited);
+	const bundled = launch(isolated().home, inherited, true);
+	for (const invocation of [link, path, bundled]) assert.equal(MARKER in invocation.env, false);
+	assert.equal(standaloneConfigHome({ mode: "link", dir: "/os-home/.pi/agent", source: "flag" }), undefined);
+	assert.equal(standaloneConfigHome({ mode: "path", dir: "/custom/home", source: "flag" }), undefined);
+});
+
+test("Gentle AI processes started from a standalone isolated session get the bundled-style config pair", () => {
+	const env = gentleAiIsolationEnv({ PATH: "/bin", [MARKER]: "/os-home/.gentle-shell/gentle-ai" });
+	assert.equal(env.GENTLE_AI_PI_CONFIG_DIR, "/os-home/.gentle-shell/gentle-ai");
+	assert.equal(env.GENTLE_PI_CONFIG_HOME, "/os-home/.gentle-shell", "Gentle AI 4.0.0 reads it as the parent of its gentle-ai folder");
+	assert.equal(env.PATH, "/bin");
+	assert.equal(env.GENTLE_AI_HOME, undefined, "standalone keeps Gentle AI's own state where it was");
+});
+
+test("without the marker, or with an explicit GENTLE_PI_CONFIG_HOME, Gentle AI's environment is unchanged", () => {
+	const plain = { PATH: "/bin" };
+	assert.equal(gentleAiIsolationEnv(plain), plain);
+	const explicit = { PATH: "/bin", GENTLE_PI_CONFIG_HOME: "/explicit", [MARKER]: "/os-home/.gentle-shell/gentle-ai" };
+	assert.equal(gentleAiIsolationEnv(explicit), explicit);
+});
+
+test("the main-channel dev-binary registration ignores the marker and an empty GENTLE_PI_CONFIG_HOME", () => {
+	assert.equal(
+		gentleAiDevBinaryRegistrationPath({ env: { [MARKER]: "/os-home/.gentle-shell/gentle-ai", GENTLE_PI_CONFIG_HOME: "" }, home: "/os-home" }),
+		join("/os-home", ".pi", "gentle-ai", "dev-binary.json"),
+	);
+	assert.equal(gentleAiDevBinaryRegistrationPath({ env: { GENTLE_PI_CONFIG_HOME: "/explicit" }, home: "/os-home" }), join("/explicit", "dev-binary.json"));
+});
+
+// --- migration -----------------------------------------------------------------
+
+// The same real filesystem bin/gentle-shell.mjs gives migrateStandaloneConfig.
+const fs = {
+	kind: (path: string) => {
+		try {
+			const stat = lstatSync(path);
+			return stat.isDirectory() ? "dir" as const : stat.isFile() ? "file" as const : "other" as const;
+		} catch {
+			return "missing" as const;
+		}
+	},
+	list: (path: string) => readdirSync(path),
+	mkdirPrivate: (path: string) => { mkdirSync(path, { recursive: true, mode: 0o700 }); },
+	copyNew: (from: string, to: string) => copyFileSync(from, to, constants.COPYFILE_EXCL),
+};
+
+function migrationWorld() {
+	const root = scratch();
+	const source = join(root, "home", ".pi", "gentle-ai");
+	const target = join(root, "home", ".gentle-shell", "gentle-ai");
+	mkdirSync(source, { recursive: true });
+	mkdirSync(dirname(target), { recursive: true });
+	writeFileSync(join(source, "banner.json"), "{\"showTextLogo\":false}\n");
+	writeFileSync(join(source, "profiles.json"), "{\"active\":\"fast\"}\n");
+	writeFileSync(join(source, "dev-binary.json"), "{}\n");
+	writeFileSync(join(source, "channel.json"), "{}\n");
+	mkdirSync(join(source, "main", "gentle-ai"), { recursive: true });
+	writeFileSync(join(source, "main", "gentle-ai", "marker"), "x");
+	return { root, source, target };
+}
+
+function snapshotTree(dir: string): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const name of readdirSync(dir)) {
+		const path = join(dir, name);
+		const stat = lstatSync(path);
+		if (stat.isDirectory()) for (const [key, value] of Object.entries(snapshotTree(path))) out[join(name, key)] = value;
+		else out[name] = stat.isSymbolicLink() ? "symlink" : `${stat.mode}:${stat.mtimeMs}:${readFileSync(path, "utf8")}`;
+	}
+	return out;
+}
+
+test("migration copies the regular files once into a new 0700 folder and never changes the source", posixOnly, () => {
+	const w = migrationWorld();
+	symlinkSync(join(w.source, "banner.json"), join(w.source, "linked.json"));
+	const before = snapshotTree(w.source);
+	const result = migrateStandaloneConfig({ source: w.source, target: w.target, fs });
+	assert.deepEqual(readdirSync(w.target).sort(), ["banner.json", "profiles.json"]);
+	assert.equal(readFileSync(join(w.target, "banner.json"), "utf8"), "{\"showTextLogo\":false}\n");
+	assert.equal(statSync(w.target).mode & 0o777, 0o700);
+	assert.deepEqual(snapshotTree(w.source), before);
+	assert.equal(result.lines.length, 1);
+	assert.match(result.lines[0], new RegExp(`${w.source.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}.*${w.target.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`));
+});
+
+test("migration skips the main-channel files and does nothing once the folder exists", posixOnly, () => {
+	const w = migrationWorld();
+	migrateStandaloneConfig({ source: w.source, target: w.target, fs });
+	assert.equal(existsSync(join(w.target, "dev-binary.json")), false);
+	assert.equal(existsSync(join(w.target, "channel.json")), false);
+	assert.equal(existsSync(join(w.target, "main")), false);
+	writeFileSync(join(w.target, "banner.json"), "{\"color\":\"cyan\"}\n");
+	writeFileSync(join(w.source, "vim.json"), "{}\n");
+	const again = migrateStandaloneConfig({ source: w.source, target: w.target, fs });
+	assert.deepEqual(again.lines, []);
+	assert.equal(readFileSync(join(w.target, "banner.json"), "utf8"), "{\"color\":\"cyan\"}\n", "never overwrites");
+	assert.equal(existsSync(join(w.target, "vim.json")), false, "runs once");
+});
+
+test("without ~/.pi/gentle-ai the migration only creates the empty 0700 folder, silently", posixOnly, () => {
+	const root = scratch();
+	const target = join(root, ".gentle-shell", "gentle-ai");
+	const result = migrateStandaloneConfig({ source: join(root, ".pi", "gentle-ai"), target, fs });
+	assert.deepEqual(result.lines, []);
+	assert.deepEqual(readdirSync(target), []);
+	assert.equal(statSync(target).mode & 0o777, 0o700);
+});
+
+test("a failed copy warns and keeps whatever was copied; it never throws", posixOnly, () => {
+	const w = migrationWorld();
+	chmodSync(join(w.source, "profiles.json"), 0o000);
+	if (spawnSync("cat", [join(w.source, "profiles.json")]).status === 0) return; // running as root: nothing is unreadable
+	const result = migrateStandaloneConfig({ source: w.source, target: w.target, fs });
+	chmodSync(join(w.source, "profiles.json"), 0o644);
+	assert.deepEqual(readdirSync(w.target), ["banner.json"]);
+	assert.equal(result.lines.length, 1);
+	assert.match(result.lines[0], /could not copy/);
+	assert.match(result.lines[0], /profiles\.json/);
+	const blocked = scratch();
+	writeFileSync(join(blocked, "not-a-dir"), "");
+	const failed = migrateStandaloneConfig({ source: w.source, target: join(blocked, "not-a-dir", "gentle-ai"), fs });
+	assert.equal(failed.lines.length, 1);
+	assert.match(failed.lines[0], /could not/);
+});
+
+// --- the real launcher -----------------------------------------------------------
+
+function writeFakePi(path: string) {
+	writeFileSync(path, [
+		"#!/usr/bin/env node",
+		"const args = process.argv.slice(2);",
+		"if (args.includes('--version')) { console.log('1.2.0'); process.exit(0); }",
+		`console.log(JSON.stringify({ marker: process.env.${MARKER} ?? null, explicit: process.env.GENTLE_PI_CONFIG_HOME ?? null }));`,
+		"",
+	].join("\n"));
+	chmodSync(path, 0o755);
+}
+
+function writeFakeGentleAi(path: string) {
+	writeFileSync(path, [
+		"#!/usr/bin/env node",
+		"import { mkdirSync, writeFileSync } from 'node:fs';",
+		"import { homedir } from 'node:os';",
+		"import { join } from 'node:path';",
+		"for (const dir of [process.env.GENTLE_AI_PI_CONFIG_DIR, join(homedir(), '.pi', 'gentle-ai')]) {",
+		"  if (!dir) continue;",
+		"  mkdirSync(dir, { recursive: true });",
+		"  writeFileSync(join(dir, 'persona.json'), JSON.stringify({ mode: 'gentleman' }));",
+		"}",
+		"process.stdout.write(JSON.stringify({ dir: process.env.GENTLE_AI_PI_CONFIG_DIR ?? null, parent: process.env.GENTLE_PI_CONFIG_HOME ?? null }) + '\\n');",
+		"",
+	].join("\n"));
+	chmodSync(path, 0o755);
+}
+
+function launcherWorld() {
+	const root = scratch();
+	const home = join(root, "home");
+	mkdirSync(join(home, ".pi", "gentle-ai"), { recursive: true });
+	writeFileSync(join(home, ".pi", "gentle-ai", "banner.json"), "{\"showTextLogo\":false}\n");
+	const pi = join(root, "fake-pi.mjs");
+	writeFakePi(pi);
+	const env: NodeJS.ProcessEnv = { PATH: process.env.PATH, HOME: home, USERPROFILE: home, GENTLE_SHELL_PI: pi, GENTLE_SHELL_NO_AUTO_SETUP: "1" };
+	const run = (args: string[], extra: NodeJS.ProcessEnv = {}) => spawnSync(process.execPath, [binPath, ...args], { encoding: "utf8", env: { ...env, ...extra } });
+	return { root, home, env, run, shellConfig: join(home, ".gentle-shell", "gentle-ai") };
+}
+
+test("a standalone isolated launch migrates ~/.pi/gentle-ai and points Pi at ~/.gentle-shell/gentle-ai", posixOnly, () => {
+	const w = launcherWorld();
+	const result = w.run(["list"]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.deepEqual(JSON.parse(result.stdout.trim().split("\n").at(-1)!), { marker: w.shellConfig, explicit: null });
+	assert.equal(readFileSync(join(w.shellConfig, "banner.json"), "utf8"), "{\"showTextLogo\":false}\n");
+	assert.equal(readFileSync(join(w.home, ".pi", "gentle-ai", "banner.json"), "utf8"), "{\"showTextLogo\":false}\n");
+	assert.equal(result.stderr.split("\n").filter((line) => line.includes(w.shellConfig) && line.includes("copied")).length, 1);
+	const second = w.run(["list"]);
+	assert.doesNotMatch(second.stderr, /copied/);
+});
+
+test("--link launches keep ~/.pi/gentle-ai: no marker and no migration", posixOnly, () => {
+	const w = launcherWorld();
+	mkdirSync(join(w.home, ".pi", "agent"), { recursive: true });
+	const result = w.run(["--link", "list"], { [MARKER]: "/outer/gentle-ai" });
+	assert.equal(result.status, 0, result.stderr);
+	assert.deepEqual(JSON.parse(result.stdout.trim().split("\n").at(-1)!), { marker: null, explicit: null });
+	assert.equal(existsSync(w.shellConfig), false);
+});
+
+test("an explicit GENTLE_PI_CONFIG_HOME still wins: it reaches Pi and no migration runs", posixOnly, () => {
+	const w = launcherWorld();
+	const result = w.run(["list"], { GENTLE_PI_CONFIG_HOME: join(w.root, "explicit") });
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(JSON.parse(result.stdout.trim().split("\n").at(-1)!).explicit, join(w.root, "explicit"));
+	assert.equal(existsSync(w.shellConfig), false);
+});
+
+test("standalone setup gives Gentle AI the config pair and keeps both persona files unchanged", posixOnly, () => {
+	const w = launcherWorld();
+	const gentleAi = join(w.root, "fake-gentle-ai.mjs");
+	writeFakeGentleAi(gentleAi);
+	writeFileSync(join(w.home, ".pi", "gentle-ai", "persona.json"), "{\"mode\":\"neutral\"}");
+	const result = w.run(["setup"], { GENTLE_SHELL_GENTLE_AI_BIN: gentleAi });
+	assert.equal(result.status, 0, result.stderr);
+	const seen = JSON.parse(result.stdout.split("\n").find((line) => line.includes("\"dir\""))!);
+	assert.deepEqual(seen, { dir: w.shellConfig, parent: join(w.home, ".gentle-shell") });
+	assert.equal(readFileSync(join(w.home, ".pi", "gentle-ai", "persona.json"), "utf8"), "{\"mode\":\"neutral\"}");
+	assert.equal(readFileSync(join(w.shellConfig, "persona.json"), "utf8"), "{\"mode\":\"neutral\"}", "the migrated copy is restored too");
+});

package/tests/startup-banner.test.ts

@@ -462,19 +462,20 @@ test("delegated children never paint the startup banner", async (t) => {
 
 // S9: the config home each of these reads resolves, per case. The OS home is
 // a temporary folder in every case, so no case can reach the real one.
-// "unset" and "empty" are exactly as before: an empty GENTLE_PI_CONFIG_HOME
-// names the current folder. "bundled" stands in for this package running from
+// "unset" and "empty" both name ~/.pi/gentle-ai: an empty GENTLE_PI_CONFIG_HOME
+// counts as unset (#2201; it used to name the current folder). "bundled" stands in for this package running from
 // a bundled install (testing overlay) whose prefix the launcher passed; the
 // user's own GENTLE_PI_CONFIG_HOME is then not this install's.
 type ConfigHomeCase = "unset" | "empty" | "bundled";
 function configHomeCase(t: { after: (fn: () => void) => void }, kind: ConfigHomeCase): { env: NodeJS.ProcessEnv; dir: string; userConfig: string } {
 	const base = realpathSync(mkdtempSync(join(tmpdir(), `config-home-${kind}-`)));
-	const saved = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE, GENTLE_PI_CONFIG_HOME: process.env.GENTLE_PI_CONFIG_HOME, GENTLE_SHELL_PREFIX: process.env.GENTLE_SHELL_PREFIX };
+	const saved = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE, GENTLE_PI_CONFIG_HOME: process.env.GENTLE_PI_CONFIG_HOME, GENTLE_SHELL_PREFIX: process.env.GENTLE_SHELL_PREFIX, GENTLE_SHELL_CONFIG_HOME: process.env.GENTLE_SHELL_CONFIG_HOME };
 	const cwd = process.cwd();
 	process.env.HOME = join(base, "home");
 	process.env.USERPROFILE = join(base, "home");
 	delete process.env.GENTLE_PI_CONFIG_HOME;
 	delete process.env.GENTLE_SHELL_PREFIX;
+	delete process.env.GENTLE_SHELL_CONFIG_HOME;
 	t.after(() => {
 		process.chdir(cwd);
 		setBundledInstallForTesting(undefined);
@@ -489,7 +490,7 @@ function configHomeCase(t: { after: (fn: () => void) => void }, kind: ConfigHome
 	if (kind === "empty") {
 		mkdirSync(join(base, "cwd"));
 		process.chdir(join(base, "cwd"));
-		return { env: { GENTLE_PI_CONFIG_HOME: "" }, dir: join(base, "cwd"), userConfig };
+		return { env: { GENTLE_PI_CONFIG_HOME: "" }, dir: join(base, "home", ".pi", "gentle-ai"), userConfig };
 	}
 	const prefix = join(base, "prefix");
 	mkdirSync(prefix);

package/tests/startup-home-repo.test.ts

@@ -168,3 +168,37 @@ test("startup returns before the native review negotiation finishes, and the fir
 	await __testing.startupNegotiationSettled();
 	assert.equal(calls.target, 1, "the negotiation still completes after startup");
 });
+
+// gentle-shell#2195: the RDD line sits in the cached system-prompt prefix, so a
+// session keeps the line it first rendered and re-renders only when RDD turns
+// off or back on.
+test("a session keeps its first RDD status line until the off state changes", async (t) => {
+	const { cwd, environment } = fixture(t, false);
+	let status: { effective: string; source: string } | undefined;
+	const cli = {
+		reviewMode: async () => {
+			if (status === undefined) throw new Error("native review CLI unavailable");
+			return { operation: "status", scope: "clone", status: { global: "", cloneLocal: status.effective, ...status } };
+		},
+	} as unknown as NativeReviewCli;
+	const { handlers, ctx } = start(cli, cwd, environment);
+	const line = async () => {
+		__testing.clearRddStatusMemoForTesting();
+		const event = { systemPrompt: "base", systemPromptOptions: { appendSystemPrompt: "" } };
+		await handlers.get("before_agent_start")!(event, ctx);
+		return /Receipt-driven development: [^;\n]*/.exec(event.systemPromptOptions.appendSystemPrompt)?.[0];
+	};
+	await handlers.get("session_shutdown")!({}, ctx);
+	assert.equal(await line(), "Receipt-driven development: unknown (native status unavailable)");
+	status = { effective: "on", source: "clone_local" };
+	assert.equal(await line(), "Receipt-driven development: unknown (native status unavailable)", "unknown to on keeps the prompt prefix");
+	status = { effective: "on", source: "global" };
+	assert.equal(await line(), "Receipt-driven development: unknown (native status unavailable)", "a source change keeps the prompt prefix");
+	status = { effective: "off", source: "clone_local" };
+	assert.equal(await line(), "Receipt-driven development: off (decided by clone_local)", "turning RDD off re-renders");
+	status = { effective: "on", source: "global" };
+	assert.equal(await line(), "Receipt-driven development: on (decided by global)", "turning RDD back on re-renders");
+	await handlers.get("session_shutdown")!({}, ctx);
+	status = { effective: "on", source: "clone_local" };
+	assert.equal(await line(), "Receipt-driven development: on (decided by clone_local)", "a new session renders the current line");
+});

package/tests/support/orchestrator-modules.ts

@@ -6,6 +6,7 @@ import { join } from "node:path";
 // so a moved clause stays pinned instead of silently disappearing.
 export const DELEGATION_MODULES = [
 	"orchestrator-delegation.md",
+	"orchestrator-delegation-reference.md",
 	"orchestrator-tracking.md",
 	"orchestrator-verification.md",
 	"orchestrator-writer.md",

package/tests/task-size-routing-contract.test.ts

@@ -80,7 +80,8 @@ test("AC3: small work runs its checks inline and keeps test-first", () => {
 test("AC4: each mechanism turns on only by its own trigger and size is re-evaluated after", () => {
 	const triggers = sectionOf(core, "## Mechanisms");
 	for (const clause of [
-		"each mechanism turns on only by its own trigger",
+		// Writer-rule fix: a trigger holds only when its condition truly holds.
+		"each mechanism turns on only when its own trigger condition truly holds",
 		"re-evaluate task size",
 		"1. **Ask**",
 		"2. **Evidence-budget rule**",
@@ -90,7 +91,8 @@ test("AC4: each mechanism turns on only by its own trigger and size is re-evalua
 		"6. **Incident rule**",
 		"7. **Context backstop**",
 		"open product or design decision",
-		"high risk",
+		// Verification by named risk: rule 3 names the escalated high-risk item.
+		"named high-risk item (assess `escalate`)",
 		"never by file count",
 		// gentle-shell#1731: the writer fires on reasons, not on size alone.
 		"never by file count or a large task alone",
@@ -134,15 +136,29 @@ test("AC5: the high-risk list lives once in the core, native tier wins, unclear
 const MODULE_BUDGETS: Record<string, number> = {
 	// gentle-shell#1731 merge with main: main's session subject/state guidance plus the reason-based Writer rule (20,000 -> 20,500 B).
 	// gentle-shell#1269: capability-compatible routing rule checked before delegation (20,500 -> 20,800 B).
-	"orchestrator-delegation.md": 20_800,
+	// S9 canon change: conditional triggers, behavior-unit writer threshold, named-risk verifier, invariants,
+	// and the PRESERVE differential pointer mirrored from gentle-ai 5f6faa16 (20,800 -> 21,900 B).
+	// Pain-point iteration S11 T2: the parent read this module in most runs and kept ~5K tokens of it in the
+	// transcript on every later call, so it became the lean delegation card (21,900 -> 7,000 B) and the
+	// reference material moved to orchestrator-delegation-reference.md, read only when a situation names it.
+	// Pain-point iteration S13 (C10): the Preparation trigger tells the parent not to read what the worker will
+	// read and to pass paths, not content (7,000 -> 7,100 B; every other card sentence is pinned by a contract).
+	// S15: units of about 100 changed lines or less always run inline (7,100 -> 7,300 B).
+	"orchestrator-delegation.md": 7_300,
+	"orchestrator-delegation-reference.md": 14_800,
 	// gentle-shell#1731 T23: Close gate accepts one Needs your decision result as a stop (12,500 -> 12,600 B).
-	"orchestrator-tracking.md": 12_600,
+	// S14: close the open slice before a high-risk commit; outcomes per commit (12,600 -> 12,850 B).
+	"orchestrator-tracking.md": 12_850,
 	// gentle-shell#1731 T3: parallel review protocol; lazy (delegation or high risk only), core and normative rule untouched.
 	// gentle-shell#1731 T11/T12: verify-per-unit timing and the every-S# verify handoff (6,000 -> 6,400 B).
 	// gentle-shell#1731 T15: one end-of-feature verify for same-model inline deliveries (6,400 -> 6,500 B).
 	// gentle-shell#1731 T23: bounded self-review and partial/blocked writer -> Needs your decision (7,000 -> 7,300 B).
-	"orchestrator-verification.md": 7_300,
-	"orchestrator-writer.md": 4_500,
+	// Verification by named risk: escalate-only tier table and the concrete-occasions rule (7,300 -> 7,500 B).
+	"orchestrator-verification.md": 7_500,
+	// Writer-rule fix (size threshold, one behavior per unit) and C3 (writer prompts name the helpers and
+	// invariants to reuse): 4,500 -> 5,300 B.
+	// Pain-point iteration S10 (C7): writer handoffs keep test scratch outside the worktree (5,300 -> 5,500 B).
+	"orchestrator-writer.md": 5_500,
 	"orchestrator-prompts.md": 13_000,
 };
 
@@ -167,6 +183,46 @@ test("AC7: each delegation module stays under its byte budget and is loaded by i
 	}
 });
 
+// Pain-point iteration S11 T2: once read, a lazy module rides along on every later model call, so the
+// default delegation read must be the lean card; reference material loads only when a pointer names it.
+test("S11: the default delegation pointer resolves to the lean card and the reference loads only by name", () => {
+	const card = read("assets/orchestrator-delegation.md");
+	const reference = read("assets/orchestrator-delegation-reference.md");
+	assert.ok(Buffer.byteLength(card, "utf8") <= MODULE_BUDGETS["orchestrator-delegation.md"], "the delegation card is over its budget");
+	// Every core line that names a delegation module names the card, except the one reference pointer.
+	const pointerLines = core.split("\n").filter((line) => line.includes("`orchestrator-delegation"));
+	const referenceLines = pointerLines.filter((line) => line.includes("`orchestrator-delegation-reference.md`"));
+	assert.equal(referenceLines.length, 1, "the core names the reference exactly once");
+	for (const name of ["Per-action table", "Work Routing Ladder", "Canonical Workflows"]) {
+		assert.ok(referenceLines[0].includes(name), `the reference pointer must name ${name}`);
+	}
+	assert.ok(pointerLines.some((line) => line.includes("`orchestrator-delegation.md`")), "the core must point at the card");
+	// The card carries what the parent needs at the moment it delegates.
+	for (const clause of [
+		"#### Delegation Triggers",
+		"Each trigger holds only when its condition truly holds",
+		"A unit is one independent piece of behavior with its code, tests, and docs together",
+		"`## Allowed edit surfaces`",
+		"Spec: odd/tasks/<feature>.md (read until \"## Log\"). Do T#; S#.",
+		"`## Skills to load before work`",
+		"`orchestrator-verification.md`",
+		"#### Key Learnings closing block",
+		"disjoint Allowed edit surfaces",
+		"Subagent-facing prompts should be written in English by default",
+		"technical artifacts default to English",
+		"returns a task id",
+		"`orchestrator-delegation-reference.md`",
+	]) {
+		assert.ok(card.includes(clause), `the delegation card is missing: ${clause}`);
+	}
+	// Reference material lives once, in the reference.
+	for (const heading of ["### Work Routing Ladder", "#### Background Subagent Policy", "### Canonical Lightweight Workflows", "#### Pi Subagent Model Routing"]) {
+		assert.ok(reference.includes(heading), `the reference is missing: ${heading}`);
+		assert.ok(!card.includes(heading), `the card still carries reference material: ${heading}`);
+	}
+	assert.ok(!reference.includes("#### Delegation Triggers"), "the triggers live once, in the card");
+});
+
 // gentle-shell#1269/#1598: the capability rule is the substantive part of the fix,
 // so losing it must fail a test instead of quietly passing the AC7 budget gate.
 // Focused on the two claims that carry the fix, not on the exact wording around them.
@@ -178,9 +234,11 @@ test("delegation reports a capability gap instead of substituting inline work fo
 });
 
 test("work usage stays complete in the human guide while routing precedence stays canonical", () => {
-	const asset = read("assets/orchestrator-delegation.md");
+	// S11 T2: the work-publication pointer and the runtime bindings moved to the reference; the writer
+	// fallback stays in the card, so the counts read the card plus the reference.
+	const asset = `${read("assets/orchestrator-delegation.md")}\n${read("assets/orchestrator-delegation-reference.md")}`;
 	const guide = read("docs/gentle-agents-activity.md");
-	assert.ok(asset.includes("tool schemas and `docs/gentle-agents-activity.md`"));
+	assert.ok(read("assets/orchestrator-delegation-reference.md").includes("tool schemas and `docs/gentle-agents-activity.md`"));
 	for (const clause of [
 		'`{"area":"Auth","topic":"Login","tags":["Review"],"refs":[{"kind":"issue","repository":"github.com/Owner/Repo","id":"12"}]}`',
 		'`filter: {"related_to":{"session_id":"<stable owner ID>"}}`',
@@ -216,8 +274,10 @@ test("T4: tracking updates edit in place and mirror without re-emitting the docu
 test("T6: each delegation module carries its own clauses and names the modules it depends on", () => {
 	const placement: Record<string, readonly string[]> = {
 		"orchestrator-tracking.md": ["#### Authorization and progress", "Delivery follows work units", "Raise a candidate you know is high risk"],
+		// The tier table header lost "Native risk" with verification by named
+		// risk: the high row is reached only through escalate, not a native tier.
 		"orchestrator-verification.md": [
-			"| Native risk tier | Verification (any RDD state) |",
+			"| Tier | Verification (any RDD state) |",
 			"## Agent escalation (gentle-shell#1494)",
 			"## Parallel review protocol (gentle-shell#1731)",
 		],

package/tests/test-scratch-contract.test.ts

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import test from "node:test";
+
+// Pain-point iteration S10 (C7): blind reviewers flagged tool artifacts in every
+// Gentle Shell delivery. Orchestrators told writers to create a scratch
+// directory in the repository root and point TMPDIR at it, so test state and
+// tool caches entered the diff. Test scratch now lives outside the worktree by
+// default. These are instruction-delivery contracts, not proof of model adherence.
+
+const ROOT = join(import.meta.dirname, "..");
+const read = (path: string): string => readFileSync(join(ROOT, path), "utf8");
+const worker = read("assets/agents/gentle-ai-worker.md");
+const writer = read("assets/orchestrator-writer.md");
+const verifier = read("assets/agents/gentle-ai-verify.md");
+
+function section(text: string, heading: string): string {
+	const start = text.indexOf(`\n## ${heading}\n`);
+	assert.ok(start >= 0, `missing section: ${heading}`);
+	const end = text.indexOf("\n## ", start + heading.length + 4);
+	return text.slice(start, end < 0 ? undefined : end);
+}
+
+function containsAll(text: string, clauses: readonly string[], label: string): void {
+	for (const clause of clauses) assert.ok(text.includes(clause), `${label} is missing: ${clause}`);
+}
+
+test("S10: the worker keeps test scratch outside the worktree and checks git status before returning", () => {
+	const discipline = section(worker, "Test discipline");
+	containsAll(discipline, [
+		"Test scratch lives outside the worktree",
+		"`mktemp -d`",
+		"never point `TMPDIR` or a cache directory into the repository",
+		"use an excluded path that the test removes before it ends",
+		"Never leave tool caches or scratch paths in the change",
+	], "worker test discipline");
+	const finish = discipline.split("\n").find((line) => line.includes("`git status --short`"));
+	assert.ok(finish, "worker finish checks must run `git status --short`");
+	containsAll(finish, ["Before returning", "no tool cache or scratch path", "`risks`"], "worker finish check");
+});
+
+test("S10: writer handoffs never place test scratch inside the repository", () => {
+	const line = writer.split("\n").find((entry) => entry.includes("Test scratch"));
+	assert.ok(line, "orchestrator-writer.md must state where writers put test scratch");
+	containsAll(line, [
+		"outside the worktree",
+		"`mktemp -d`",
+		"never in the repository",
+		"`TMPDIR`",
+		"excluded path",
+	], "writer handoff scratch rule");
+});
+
+test("S10: no shipped guidance points test temp state into the repository", () => {
+	const offenders: string[] = [];
+	const walk = (dir: string): void => {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			const path = join(dir, entry.name);
+			if (entry.isDirectory()) walk(path);
+			else if (/\.(md|ts)$/.test(entry.name) && /TMPDIR=\$(PWD|\(pwd\))|\.test-tmp|\.atl\/test-tmp/.test(readFileSync(path, "utf8"))) {
+				offenders.push(relative(ROOT, path));
+			}
+		}
+	};
+	for (const dir of ["assets", "extensions", "docs"]) walk(join(ROOT, dir));
+	assert.deepEqual(offenders, []);
+});
+
+// S10 follow-up (user, 2026-10-14: "lo de los temporales tambien hacemos limpieza luego?"):
+// scratch outside the worktree was never removed; verifier scratch copies piled up
+// in the system temp directory. The verifier removes only the exact directory its
+// own `mktemp -d` printed; the worker, which may not delete, has tests clean up in
+// teardown and names any leftover outside directory so the parent removes it.
+test("S10: scratch outside the worktree is removed after use", () => {
+	// Independent verification of C7 found child safety blocks `rm -rf` in every
+	// subagent (lib/destructive-command-guard.ts), so a verifier told to delete its
+	// own scratch always failed and nobody removed it. Subagents now report exact
+	// scratch paths and the parent, where deletion is only confirmed, removes them.
+	containsAll(
+		verifier,
+		["list every scratch directory you created by exact path in your result so the parent removes it", "never delete it yourself"],
+		"gentle-ai-verify scratch report",
+	);
+	assert.ok(!/\brm\s+-r/.test(verifier), "gentle-ai-verify must not instruct a deletion child safety blocks");
+	containsAll(
+		section(worker, "Test discipline"),
+		[
+			"Tests delete the temp directories they create in teardown",
+			"name any scratch directory you created outside the worktree in `risks` so the parent removes it",
+		],
+		"worker scratch cleanup",
+	);
+	// Session scratch and artifact ledger: the runtime owns the parent session's
+	// TMPDIR (subagent TMPDIRs nest under it) and records clones and worktrees,
+	// so the writer rule points at the command instead of a model cleanup step.
+	containsAll(writer, ["The runtime owns session scratch", "`/gentle:scratch` lists or cleans recorded clones and worktrees"], "writer runtime-owned cleanup");
+	// The verifier's mktemp copy lives in its own TMPDIR, which the runner removes.
+	const verification = read("assets/orchestrator-verification.md");
+	containsAll(verification, ["the runtime removes each subagent's own TMPDIR, which holds that copy"], "verification runtime cleanup");
+	assert.ok(!verification.includes("the parent removes the scratch paths the verifier reports"), "the parent no longer removes verifier scratch");
+});