gentle-pi 4.0.0 → 4.2.0

package/tests/gentle-ai-binary-isolation.test.ts

@@ -0,0 +1,135 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import test from "node:test";
+import { bundledGentleAiPaths, gentleAiIsolationEnv } from "../lib/gentle-ai-binary.ts";
+import { resetRunningBundledPrefixForTesting, runningBundledPrefix } from "../lib/gentle-shell-bundled.ts";
+import { engramPinVersion } from "../scripts/installer-downloads.mjs";
+
+// S9: gentle-pi's own gentle-ai runs in a bundled install keep Gentle AI's
+// state, persona and Engram inside the prefix. Only this package inside the
+// prefix's versions/ honors the launcher's GENTLE_SHELL_PREFIX.
+
+const ID = "4.1.0-1.1.0";
+
+// A valid bundled install: the version's marker, and `current` naming it (a
+// relative symlink on POSIX, a pointer file on Windows), as bundled-install.mjs writes them.
+function bundledPrefix(t: test.TestContext, { marked = true, current = ID } = {}) {
+	const prefix = realpathSync(mkdtempSync(join(tmpdir(), "gentle-ai-isolation-")));
+	t.after(() => rmSync(prefix, { recursive: true, force: true }));
+	const version = join(prefix, "versions", ID);
+	const packageRoot = join(version, "node_modules", "gentle-pi");
+	mkdirSync(packageRoot, { recursive: true });
+	if (marked) writeFileSync(join(version, ".gentle-shell-version"), `${ID}\n`);
+	if (process.platform === "win32") writeFileSync(join(prefix, "current"), `${current}\n`);
+	else symlinkSync(`versions/${current}`, join(prefix, "current"));
+	const engram = join(prefix, "runtime", `engram-${engramPinVersion}`, process.platform === "win32" ? "engram.exe" : "engram");
+	mkdirSync(join(engram, ".."), { recursive: true });
+	writeFileSync(engram, "engram", { mode: 0o700 });
+	return { prefix, packageRoot, engram };
+}
+
+// B2a: gentle-pi's bundled config folder is <prefix>/config/gentle-ai, so a
+// Gentle AI 4.0.0 given GENTLE_PI_CONFIG_HOME=<prefix>/config (its parent, the
+// way 4.0.0 reads it) writes the background-subagents policy into it.
+test("bundledGentleAiPaths names the prefix's Gentle AI home, gentle-pi config folder and its parent, and pinned Engram", () => {
+	assert.deepEqual(bundledGentleAiPaths("/home/ana/.gentle-shell", "linux"), {
+		home: "/home/ana/.gentle-shell/gentle-ai",
+		piConfigParent: "/home/ana/.gentle-shell/config",
+		piConfig: "/home/ana/.gentle-shell/config/gentle-ai",
+		engram: `/home/ana/.gentle-shell/runtime/engram-${engramPinVersion}/engram`,
+	});
+	assert.equal(bundledGentleAiPaths("C:\\Users\\Ana\\AppData\\Local\\gentle-shell", "win32").engram,
+		`C:\\Users\\Ana\\AppData\\Local\\gentle-shell\\runtime\\engram-${engramPinVersion}\\engram.exe`);
+});
+
+test("gentleAiIsolationEnv adds the four Gentle AI variables for this package inside a bundled prefix", (t) => {
+	const { prefix, packageRoot, engram } = bundledPrefix(t);
+	const base = { PATH: "/usr/bin", GENTLE_SHELL_PREFIX: prefix };
+	const env = gentleAiIsolationEnv(base, { packageRoot });
+	assert.deepEqual(env, {
+		...base,
+		GENTLE_AI_HOME: join(prefix, "gentle-ai"),
+		GENTLE_AI_PI_CONFIG_DIR: join(prefix, "config", "gentle-ai"),
+		GENTLE_AI_ENGRAM_BIN: engram,
+		GENTLE_AI_NO_SELF_UPDATE: "1",
+		GENTLE_PI_CONFIG_HOME: join(prefix, "config"),
+		// #2105: Gentle AI 4.0.0 ignores GENTLE_AI_ENGRAM_BIN and looks `engram` up on PATH
+		// first; with the pinned one first it never falls back to `brew tap`.
+		PATH: `${dirname(engram)}${delimiter}/usr/bin`,
+	});
+	assert.equal("GENTLE_AI_HOME" in base, false, "the caller's environment is not changed");
+	// Without the published Engram, Gentle AI gets no Engram to use, and PATH stays as it was.
+	rmSync(engram);
+	const without = gentleAiIsolationEnv(base, { packageRoot });
+	assert.equal("GENTLE_AI_ENGRAM_BIN" in without, false);
+	assert.equal(without.PATH, "/usr/bin");
+});
+
+test("gentleAiIsolationEnv returns the environment unchanged outside a bundled install", (t) => {
+	const { prefix, packageRoot } = bundledPrefix(t);
+	const unchanged = (env: NodeJS.ProcessEnv, root = packageRoot) => assert.equal(gentleAiIsolationEnv(env, { packageRoot: root }), env);
+	unchanged({ PATH: "/usr/bin" });
+	unchanged({ GENTLE_SHELL_PREFIX: "" });
+	unchanged({ GENTLE_SHELL_PREFIX: "relative/prefix" });
+	unchanged({ GENTLE_SHELL_PREFIX: join(prefix, "missing") });
+	// A gentle-pi outside the prefix's versions (the user's own, run from the
+	// agent's shell, which inherits GENTLE_SHELL_PREFIX) keeps its own Gentle AI.
+	const outside = join(prefix, "elsewhere", "gentle-pi");
+	mkdirSync(outside, { recursive: true });
+	unchanged({ GENTLE_SHELL_PREFIX: prefix }, outside);
+	unchanged({ GENTLE_SHELL_PREFIX: prefix }, join(prefix, "versions"));
+});
+
+// A2: only a valid bundled install, never a folder that merely sits under a versions/.
+test("gentleAiIsolationEnv gives nothing to an nvm gentle-pi or an unmarked version", (t) => {
+	const nvm = realpathSync(mkdtempSync(join(tmpdir(), "gentle-ai-isolation-nvm-")));
+	t.after(() => rmSync(nvm, { recursive: true, force: true }));
+	const nvmPackage = join(nvm, ".nvm", "versions", "node", "v24.21.0", "lib", "node_modules", "gentle-pi");
+	mkdirSync(nvmPackage, { recursive: true });
+	const nvmEnv = { GENTLE_SHELL_PREFIX: join(nvm, ".nvm") };
+	assert.equal(gentleAiIsolationEnv(nvmEnv, { packageRoot: nvmPackage }), nvmEnv);
+	const { prefix: unmarked, packageRoot: unmarkedRoot } = bundledPrefix(t, { marked: false });
+	const unmarkedEnv = { GENTLE_SHELL_PREFIX: unmarked };
+	assert.equal(gentleAiIsolationEnv(unmarkedEnv, { packageRoot: unmarkedRoot }), unmarkedEnv);
+	// A valid install, but the variable names another folder.
+	const { packageRoot } = bundledPrefix(t);
+	const other = { GENTLE_SHELL_PREFIX: nvm };
+	assert.equal(gentleAiIsolationEnv(other, { packageRoot }), other);
+});
+
+// The answer is remembered per package root and GENTLE_SHELL_PREFIX value: one
+// process gets each env's own answer, and a `current` that moves while Pi runs
+// does not change a remembered one.
+test("runningBundledPrefix answers per env in one process and keeps a remembered answer when current moves", (t) => {
+	resetRunningBundledPrefixForTesting();
+	t.after(resetRunningBundledPrefixForTesting);
+	const { prefix, packageRoot } = bundledPrefix(t);
+	const other = realpathSync(mkdtempSync(join(tmpdir(), "gentle-ai-isolation-other-")));
+	t.after(() => rmSync(other, { recursive: true, force: true }));
+	assert.equal(runningBundledPrefix({ GENTLE_SHELL_PREFIX: prefix }, { packageRoot }), prefix);
+	assert.equal(runningBundledPrefix({ GENTLE_SHELL_PREFIX: other }, { packageRoot }), undefined);
+	assert.equal(runningBundledPrefix({}, { packageRoot }), undefined);
+	assert.equal(runningBundledPrefix({ GENTLE_SHELL_PREFIX: prefix }, { packageRoot }), prefix);
+	// An upgrade switches current to another version while this one runs.
+	rmSync(join(prefix, "current"));
+	if (process.platform === "win32") writeFileSync(join(prefix, "current"), "4.2.0-1.1.0\n");
+	else symlinkSync("versions/4.2.0-1.1.0", join(prefix, "current"));
+	// The version stops being a finished install (its marker is gone).
+	rmSync(join(prefix, "versions", ID, ".gentle-shell-version"));
+	assert.equal(runningBundledPrefix({ GENTLE_SHELL_PREFIX: prefix }, { packageRoot }), prefix, "remembered");
+	resetRunningBundledPrefixForTesting();
+	assert.equal(runningBundledPrefix({ GENTLE_SHELL_PREFIX: prefix }, { packageRoot }), undefined, "decided again after a reset");
+});
+
+// N1: a subagent started after `gentle-shell upgrade` moved `current` runs from
+// the previous version, which the prefix still keeps: it stays bundled.
+test("a kept, marked version that current no longer names is still bundled for its own runs", (t) => {
+	resetRunningBundledPrefixForTesting();
+	t.after(resetRunningBundledPrefixForTesting);
+	const { prefix, packageRoot } = bundledPrefix(t, { current: "4.2.0-1.1.0" });
+	const env = { GENTLE_SHELL_PREFIX: prefix };
+	assert.equal(runningBundledPrefix(env, { packageRoot }), prefix);
+	assert.equal(gentleAiIsolationEnv(env, { packageRoot }).GENTLE_AI_HOME, join(prefix, "gentle-ai"));
+});

package/tests/gentle-ai-binary.test.ts

@@ -32,7 +32,7 @@ const nativeBinaryGate = requireNativeBinary({
 	digestsPinned: releaseDigestsPinned,
 	env: process.env,
 });
-if (!nativeBinaryGate.run) console.log(`gentle-ai-binary: ${nativeBinaryGate.reason}`);
+if (nativeBinaryGate.run === false) console.log(`gentle-ai-binary: ${nativeBinaryGate.reason}`);
 const verifiedBinaryTest = nativeBinaryGate.run && process.platform !== "win32" ? test : test.skip;
 
 interface PinnedBinaryIsolation {
@@ -44,6 +44,7 @@ interface PinnedBinaryIsolation {
 let pinnedBinaryIsolation: PinnedBinaryIsolation | undefined;
 
 test.beforeEach((t) => {
+	assert.ok("after" in t);
 	const home = mkdtempSync(join(tmpdir(), "gentle-pi-pinned-binary-home-"));
 	const environment: GentleAiDevBinaryEnvironment = { env: { ...process.env }, home };
 	delete environment.env.GENTLE_PI_CONFIG_HOME;
@@ -97,7 +98,7 @@ async function writeWindowsSourceBinary(packageRoot: string): Promise<{ binaryPa
 		method: "go-sumdb-source-build",
 		package: "github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai",
 		module: "github.com/gentleman-programming/gentle-ai/v4",
-		tag: "v4.0.0",
+		tag: "v4.1.1",
 		architecture: process.arch === "x64" ? "x64" : "arm64",
 		binarySha256: createHash("sha256").update(binary).digest("hex"),
 		moduleChecksum: GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM,
@@ -174,6 +175,22 @@ test("runtime validates a Windows Go SumDB source manifest and rejects tampering
 	assert.doesNotMatch(gentleAiBinaryPathForTest(packageRoot), /(^|[/\\])PATH($|[/\\])/i);
 });
 
+// Every native call resolved the binary by reading and hashing all of it; on
+// Windows each read is also scanned by antivirus. The digest is reused only
+// while the file keeps its identity (device, inode, size, mtime and ctime).
+test("runtime reuses the binary digest while the file is unchanged and re-hashes after any rewrite", async () => {
+	const packageRoot = await mkdtemp(join(tmpdir(), "gentle-pi-binary-digest-cache-"));
+	const { binaryPath } = await writeWindowsSourceBinary(packageRoot);
+	let reads = 0;
+	const countingRead = (path: string) => { reads++; return readFileSync(path); };
+	assert.equal(resolveGentleAiBinary(packageRoot, "win32", countingRead), binaryPath);
+	assert.equal(resolveGentleAiBinary(packageRoot, "win32", countingRead), binaryPath);
+	assert.equal(reads, 1, "an unchanged binary is hashed once");
+	await writeFile(binaryPath, "tampered Windows source build");
+	assert.throws(() => resolveGentleAiBinary(packageRoot, "win32", countingRead), /package-local-binary-missing/);
+	assert.equal(reads, 2, "a rewritten binary is hashed again, even with the same size");
+});
+
 function gentleAiBinaryPathForTest(packageRoot: string): string {
 	return join(packageRoot, ".gentle-ai", RUNTIME_DIRECTORY, "gentle-ai.exe");
 }

package/tests/gentle-ai-child-guards.test.ts

@@ -0,0 +1,202 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { type TestContext } from "node:test";
+import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import { bindSessionRepositoryPreparation } from "../lib/bounded-writer-admission.ts";
+import { GENTLE_AI_TIMING_ENTRY } from "../lib/gentle-ai-elapsed-store.ts";
+import { REVIEW_SIDEBAR_EVENT } from "../lib/review-sidebar-state.ts";
+import { YOLO_STATUS_KEY } from "../lib/yolo-session-policy.ts";
+
+// gentle-shell#1690: the package is forwarded to delegated rpc children
+// (GENTLE_PI_AGENTS_CHILD=1, where ctx.hasUI is true). Parent-owned startup
+// work and shared-state writes must not run there; each case pairs the child
+// with a parent control so the guard cannot pass vacuously.
+
+type Handler = (event: unknown, ctx: ExtensionContext) => unknown;
+
+function isolate(t: TestContext): { root: string; cwd: string; agentHome: string } {
+	const root = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-child-guards-")));
+	const cwd = join(root, "project");
+	const agentHome = join(root, "agent-home");
+	const configHome = join(root, "config");
+	for (const path of [cwd, agentHome, configHome]) mkdirSync(path, { recursive: true });
+	const previous = { agentHome: process.env.GENTLE_PI_AGENT_HOME, configHome: process.env.GENTLE_PI_CONFIG_HOME };
+	process.env.GENTLE_PI_AGENT_HOME = agentHome;
+	process.env.GENTLE_PI_CONFIG_HOME = configHome;
+	t.after(() => {
+		if (previous.agentHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previous.agentHome;
+		if (previous.configHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previous.configHome;
+		rmSync(root, { recursive: true, force: true });
+	});
+	return { root, cwd, agentHome };
+}
+
+function harness(child: boolean, cwd: string) {
+	const handlers = new Map<string, Handler>();
+	const entries: Array<{ type: string; customType: string; data: unknown }> = [];
+	const nativeAccesses: string[] = [];
+	const sweeps: string[] = [];
+	const prompts: string[] = [];
+	const statuses: Array<[string, string | undefined]> = [];
+	const emitted: Array<{ name: string; payload: unknown }> = [];
+	const tools = new Map<string, ToolDefinition>();
+	const pi = {
+		on: (name: string, handler: Handler) => { handlers.set(name, handler); },
+		events: { on() {}, emit: (name: string, payload: unknown) => { emitted.push({ name, payload }); } },
+		appendEntry: (customType: string, data: unknown) => { entries.push({ type: "custom", customType, data }); },
+		getThinkingLevel: () => "medium",
+		registerTool: (tool: ToolDefinition) => { tools.set(tool.name, tool); },
+		registerCommand() {}, registerShortcut() {}, registerMessageRenderer() {},
+	} as unknown as ExtensionAPI;
+	// Any read of the native CLI means the session reached review negotiation
+	// or repository preparation.
+	const nativeReviewCli = new Proxy({}, {
+		get: (_target, key) => { nativeAccesses.push(String(key)); return undefined; },
+	});
+	const candidateViews = { sweepOrphans: (path: string) => { sweeps.push(path); }, cleanupAll() {} };
+	createGentleAiExtension({
+		processEnv: { GENTLE_PI_AGENTS_CHILD: child ? "1" : "0", GENTLE_AI_TELEMETRY: "0" },
+		nativeReviewCli: nativeReviewCli as never,
+		candidateViews: candidateViews as never,
+		childStandingReviewPermissionClient: { requestAuthorization: async () => false, close() {} },
+	})(pi);
+	const sessionManager = { getSessionId: () => `session-${child ? "child" : "parent"}`, getCwd: () => cwd, getEntries: () => entries, getBranch: () => entries };
+	const ctx = {
+		cwd,
+		mode: "rpc",
+		hasUI: true,
+		sessionManager,
+		ui: {
+			notify() {},
+			setStatus: (key: string, text?: string) => { statuses.push([key, text]); },
+			confirm: async (title: string) => { prompts.push(`confirm:${title}`); return false; },
+			select: async (title: string) => { prompts.push(`select:${title}`); return undefined; },
+		},
+	} as unknown as ExtensionContext;
+	return { handlers, entries, nativeAccesses, sweeps, prompts, statuses, emitted, tools, ctx, sessionManager };
+}
+
+function legacySettings(cwd: string): string {
+	const path = join(cwd, ".pi", "settings.json");
+	mkdirSync(join(cwd, ".pi"), { recursive: true });
+	writeFileSync(path, `${JSON.stringify({ subagents: { agentOverrides: { worker: "openai/gpt-5" } } }, null, 2)}\n`);
+	return path;
+}
+
+test("child session_start keeps local resets but skips parent-owned startup work", async (t) => {
+	const { cwd, agentHome } = isolate(t);
+	const settingsPath = legacySettings(cwd);
+	const before = readFileSync(settingsPath, "utf8");
+	const h = harness(true, cwd);
+	const timings = () => h.entries.filter((entry) => entry.customType === GENTLE_AI_TIMING_ENTRY);
+	await h.handlers.get("tool_execution_start")!({ toolName: "gentle_review", toolCallId: "before" }, h.ctx);
+	assert.equal(timings().length, 0, "no elapsed-timing ledger exists before session_start");
+	await h.handlers.get("session_start")!({ reason: "startup" }, h.ctx);
+	await h.handlers.get("tool_execution_start")!({ toolName: "gentle_review", toolCallId: "after" }, h.ctx);
+	assert.equal(timings().length, 1, "the child still creates its elapsed-timing ledger");
+	assert.deepEqual(readdirSync(agentHome), [], "a child must not install package assets");
+	assert.equal(readFileSync(settingsPath, "utf8"), before, "a child must not migrate project model overrides");
+	assert.deepEqual(h.sweeps, [], "a child must not sweep candidate views");
+	assert.deepEqual(h.nativeAccesses, [], "a child must not negotiate review status or bind repository preparation");
+});
+
+test("parent session_start still runs the startup work skipped in children", async (t) => {
+	const { cwd, agentHome } = isolate(t);
+	const settingsPath = legacySettings(cwd);
+	const before = readFileSync(settingsPath, "utf8");
+	const h = harness(false, cwd);
+	await h.handlers.get("session_start")!({ reason: "startup" }, h.ctx);
+	assert.notDeepEqual(readdirSync(agentHome), [], "the parent installs package assets");
+	assert.notEqual(readFileSync(settingsPath, "utf8"), before, "the parent migrates legacy project model overrides");
+	assert.deepEqual(h.sweeps, [cwd]);
+	assert.ok(h.nativeAccesses.length > 0, "the parent negotiates review status");
+});
+
+test("child session_start re-arms the reminder session for its own session manager", async (t) => {
+	const { cwd } = isolate(t);
+	mkdirSync(join(cwd, "src"), { recursive: true });
+	writeFileSync(join(cwd, "src", "a.ts"), "export {};\n");
+	const h = harness(true, cwd);
+	const next = { ...h.sessionManager, getSessionId: () => "session-child-next" };
+	const nextCtx = { ...h.ctx, sessionManager: next } as unknown as ExtensionContext;
+	const write = (ctx: ExtensionContext, toolCallId: string) => h.handlers.get("tool_result")!({ toolName: "write", toolCallId, isError: false, input: { path: "src/a.ts" } }, ctx);
+	const mutations = () => h.entries.filter((entry) => (entry.data as { kind?: string })?.kind === "mutation");
+	await h.handlers.get("session_start")!({ reason: "startup" }, h.ctx);
+	await h.handlers.get("session_shutdown")!({ reason: "new" }, h.ctx);
+	await write(h.ctx, "after-shutdown");
+	assert.equal(mutations().length, 0, "a shut-down session records nothing");
+	await h.handlers.get("session_start")!({ reason: "new" }, nextCtx);
+	await write(h.ctx, "stale-manager");
+	assert.equal(mutations().length, 0, "the reminder manager moved to the new session");
+	await write(nextCtx, "current-manager");
+	assert.equal(mutations().length, 1, "the restarted child records its own mutation");
+});
+
+test("child session_start re-arms YOLO and the review sidebar for its own session", async (t) => {
+	const { cwd } = isolate(t);
+	const h = harness(true, cwd);
+	const next = { ...h.sessionManager, getSessionId: () => "session-child-next" };
+	const nextCtx = { ...h.ctx, sessionManager: next } as unknown as ExtensionContext;
+	const yoloClears = () => h.statuses.filter(([key, text]) => key === YOLO_STATUS_KEY && text === undefined).length;
+	const sidebarSessions = () => h.emitted.filter((event) => event.name === REVIEW_SIDEBAR_EVENT)
+		.map((event) => (event.payload as { sessionId: string }).sessionId);
+	// Any non-assess call passes through the sidebar wrapper, which publishes
+	// before running; the native outcome itself is irrelevant here.
+	const capture = async (ctx: ExtensionContext, toolCallId: string) => {
+		try { await h.tools.get("gentle_review_capture")!.execute(toolCallId, {}, undefined, undefined, ctx as never); } catch { /* outcome irrelevant */ }
+	};
+	await h.handlers.get("session_start")!({ reason: "startup" }, h.ctx);
+	await h.handlers.get("session_shutdown")!({ reason: "new" }, h.ctx);
+	await capture(h.ctx, "after-shutdown");
+	assert.deepEqual(sidebarSessions(), [], "a shut-down sidebar publishes nothing");
+	const clearsBeforeRestart = yoloClears();
+	await h.handlers.get("session_start")!({ reason: "new" }, nextCtx);
+	assert.equal(yoloClears(), clearsBeforeRestart + 1, "the child session_start resets YOLO and clears its indicator");
+	await capture(h.ctx, "stale-session");
+	assert.deepEqual(sidebarSessions(), [], "the sidebar moved to the new session");
+	await capture(nextCtx, "current-session");
+	assert.ok(sidebarSessions().length > 0, "the restarted child sidebar publishes again");
+	assert.ok(sidebarSessions().every((id) => id === "session-child-next"), JSON.stringify(sidebarSessions()));
+});
+
+async function writeToolResult(child: boolean, t: TestContext) {
+	const { cwd } = isolate(t);
+	mkdirSync(join(cwd, "src"), { recursive: true });
+	writeFileSync(join(cwd, "src", "a.ts"), "export {};\n");
+	const h = harness(child, cwd);
+	await h.handlers.get("session_start")!({ reason: "startup" }, h.ctx);
+	// Bind an observable preparation on the same session owner the parent
+	// session_start would have bound, so only the tool_result guard decides.
+	const preparations: string[] = [];
+	const unbind = bindSessionRepositoryPreparation(h.sessionManager, cwd, async (root) => { preparations.push(root); return false; }, () => true);
+	t.after(unbind);
+	await h.handlers.get("tool_result")!({ toolName: "write", toolCallId: "call-1", isError: false, input: { path: "src/a.ts" } }, h.ctx);
+	const mutations = h.entries.filter((entry) => (entry.data as { kind?: string })?.kind === "mutation");
+	return { cwd, preparations, mutations };
+}
+
+test("child tool_result records the mutation but never prepares the bound repository", async (t) => {
+	const { preparations, mutations } = await writeToolResult(true, t);
+	assert.equal(mutations.length, 1, "the child keeps its own mutation receipt");
+	assert.deepEqual(preparations, []);
+});
+
+test("parent tool_result still prepares the bound repository", async (t) => {
+	const { cwd, preparations, mutations } = await writeToolResult(false, t);
+	assert.equal(mutations.length, 1);
+	assert.deepEqual(preparations, [cwd]);
+});
+
+test("child confirm-class guardrail commands ask the parent instead of running or blocking headlessly", async (t) => {
+	const { cwd } = isolate(t);
+	const h = harness(true, cwd);
+	const result = await h.handlers.get("tool_call")!({ toolName: "bash", input: { command: "pi remove some-package" } }, h.ctx) as { block?: boolean; reason?: string } | undefined;
+	assert.equal(h.prompts.length, 1, JSON.stringify(h.prompts));
+	assert.equal(result?.block, true, "the declined confirmation blocks the command");
+	assert.doesNotMatch(result?.reason ?? "", /requires interactive confirmation/);
+});

package/tests/gentle-ai-dev-binary-surfacing.test.ts

@@ -1,10 +1,10 @@
 import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
-import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import test from "node:test";
+import test, { afterEach, beforeEach } from "node:test";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
 import {
@@ -18,6 +18,28 @@ import {
 // version, and its content digest — the maintainer must never wonder which
 // gentle-ai actually answered.
 
+// These tests model a principal session unless a case explicitly selects a child.
+// Never let startup resolve profiles from the launching operator's config home.
+let restoreSessionEnvironment: (() => void) | undefined;
+beforeEach(async () => {
+	const home = await mkdtemp(join(tmpdir(), "gentle-pi-dev-config-home-"));
+	const previousConfigHome = process.env.GENTLE_PI_CONFIG_HOME;
+	const previousChild = process.env.GENTLE_PI_AGENTS_CHILD;
+	process.env.GENTLE_PI_CONFIG_HOME = home;
+	delete process.env.GENTLE_PI_AGENTS_CHILD;
+	restoreSessionEnvironment = () => {
+		if (previousConfigHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previousConfigHome;
+		if (previousChild === undefined) delete process.env.GENTLE_PI_AGENTS_CHILD;
+		else process.env.GENTLE_PI_AGENTS_CHILD = previousChild;
+		rmSync(home, { recursive: true, force: true });
+	};
+});
+afterEach(() => {
+	restoreSessionEnvironment?.();
+	restoreSessionEnvironment = undefined;
+});
+
 interface CommandRegistration {
 	handler: (args: string, ctx: ExtensionContext) => Promise<void>;
 }
@@ -58,6 +80,8 @@ async function withDevOverride<T>(callback: (state: { devBinary: string; sha256:
 		return await callback({ devBinary, sha256, home });
 	} finally {
 		setGentleAiDevBinaryEnvironmentForTesting(undefined);
+		rmSync(home, { recursive: true, force: true });
+		rmSync(bin, { recursive: true, force: true });
 	}
 }
 
@@ -164,25 +188,109 @@ test("gentle:dev-binary registers, reports, and clears the persistent override",
 	}
 });
 
-test("session start announces the active override once, loudly", async () => {
+interface SessionStartHarness {
+	sessionStart: (event: unknown, ctx: ExtensionContext) => Promise<void>;
+}
+
+async function sessionStartHarness(): Promise<SessionStartHarness> {
+	const handlers = new Map<string, (event: unknown, ctx: ExtensionContext) => Promise<void>>();
+	const pi = {
+		on(name: string, handler: (event: unknown, ctx: ExtensionContext) => Promise<void>) {
+			handlers.set(name, handler);
+		},
+		registerCommand() {},
+		registerTool() {},
+	} as unknown as ExtensionAPI;
+	createGentleAiExtension({ nativeReviewCli: null })(pi);
+	const sessionStart = handlers.get("session_start");
+	assert.equal(typeof sessionStart, "function");
+	return { sessionStart: sessionStart! };
+}
+
+// The 🌹 dev-binary card (gentle-shell) owns the startup notice when it can
+// render; the session-start toast is only the fallback for when the card is
+// unavailable (shell disabled, no UI).
+test("session start defers the active-override announcement to the shell card", async () => {
 	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+	const previousShell = process.env.GENTLE_PI_SHELL;
 	process.env.GENTLE_PI_AGENT_HOME = await mkdtemp(join(tmpdir(), "gentle-pi-dev-agent-home-"));
+	delete process.env.GENTLE_PI_SHELL;
 	try {
 		await withDevOverride(async ({ devBinary, sha256 }) => {
-			const handlers = new Map<string, (event: unknown, ctx: ExtensionContext) => Promise<void>>();
-			const pi = {
-				on(name: string, handler: (event: unknown, ctx: ExtensionContext) => Promise<void>) {
-					handlers.set(name, handler);
-				},
-				registerCommand() {},
-				registerTool() {},
-			} as unknown as ExtensionAPI;
-			createGentleAiExtension({ nativeReviewCli: null })(pi);
-			const sessionStart = handlers.get("session_start");
-			assert.equal(typeof sessionStart, "function");
+			const { sessionStart } = await sessionStartHarness();
+			const cwd = await mkdtemp(join(tmpdir(), "gentle-pi-dev-cwd-"));
+			const notifications: Array<{ message: string; severity: string }> = [];
+			await sessionStart({}, contextFor(cwd, notifications));
+			const expected = `Gentle AI dev binary override active (unpinned, field-test only): ${devBinary} 9.9.9-dev+surface sha256:${sha256.slice(0, 16)}`;
+			const announcement = notifications.find((entry) => entry.message.includes(expected));
+			assert.equal(announcement, undefined, JSON.stringify(notifications));
+		});
+	} finally {
+		if (previousAgentHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		if (previousShell === undefined) delete process.env.GENTLE_PI_SHELL;
+		else process.env.GENTLE_PI_SHELL = previousShell;
+	}
+});
+
+test("a child session keeps exactly one warning fallback even when the shell is enabled", async (t) => {
+	const previousShell = process.env.GENTLE_PI_SHELL;
+	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+	const home = await mkdtemp(join(tmpdir(), "gentle-pi-dev-child-home-"));
+	process.env.GENTLE_PI_AGENT_HOME = home;
+	process.env.GENTLE_PI_AGENTS_CHILD = "1";
+	process.env.GENTLE_PI_SHELL = "on";
+	t.after(() => {
+		if (previousShell === undefined) delete process.env.GENTLE_PI_SHELL;
+		else process.env.GENTLE_PI_SHELL = previousShell;
+		if (previousAgentHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		rmSync(home, { recursive: true, force: true });
+	});
+	await withDevOverride(async ({ devBinary, sha256 }) => {
+		const { sessionStart } = await sessionStartHarness();
+		const notifications: Array<{ message: string; severity: string }> = [];
+		await sessionStart({}, contextFor(home, notifications));
+		const expected = `Gentle AI dev binary override active (unpinned, field-test only): ${devBinary} 9.9.9-dev+surface sha256:${sha256.slice(0, 16)}`;
+		assert.equal(notifications.length, 1, JSON.stringify(notifications));
+		assert.ok(notifications[0]!.message.includes(expected));
+		assert.equal(notifications[0]!.severity, "warning");
+	});
+});
+
+test("session start stays silent in headless contexts even with an active override", async () => {
+	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+	const previousShell = process.env.GENTLE_PI_SHELL;
+	process.env.GENTLE_PI_AGENT_HOME = await mkdtemp(join(tmpdir(), "gentle-pi-dev-agent-home-"));
+	delete process.env.GENTLE_PI_SHELL;
+	try {
+		await withDevOverride(async () => {
+			const { sessionStart } = await sessionStartHarness();
+			const cwd = await mkdtemp(join(tmpdir(), "gentle-pi-dev-cwd-"));
+			const notifications: Array<{ message: string; severity: string }> = [];
+			const headless = { ...contextFor(cwd, notifications), hasUI: false } as unknown as ExtensionContext;
+			await sessionStart({}, headless);
+			assert.equal(notifications.length, 0, JSON.stringify(notifications));
+		});
+	} finally {
+		if (previousAgentHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		if (previousShell === undefined) delete process.env.GENTLE_PI_SHELL;
+		else process.env.GENTLE_PI_SHELL = previousShell;
+	}
+});
+
+test("session start keeps the loud toast as fallback when the shell card is unavailable", async () => {
+	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+	const previousShell = process.env.GENTLE_PI_SHELL;
+	process.env.GENTLE_PI_AGENT_HOME = await mkdtemp(join(tmpdir(), "gentle-pi-dev-agent-home-"));
+	process.env.GENTLE_PI_SHELL = "off";
+	try {
+		await withDevOverride(async ({ devBinary, sha256 }) => {
+			const { sessionStart } = await sessionStartHarness();
 			const cwd = await mkdtemp(join(tmpdir(), "gentle-pi-dev-cwd-"));
 			const notifications: Array<{ message: string; severity: string }> = [];
-			await sessionStart!({}, contextFor(cwd, notifications));
+			await sessionStart({}, contextFor(cwd, notifications));
 			const expected = `Gentle AI dev binary override active (unpinned, field-test only): ${devBinary} 9.9.9-dev+surface sha256:${sha256.slice(0, 16)}`;
 			const announcement = notifications.find((entry) => entry.message.includes(expected));
 			assert.ok(announcement, JSON.stringify(notifications));
@@ -191,5 +299,7 @@ test("session start announces the active override once, loudly", async () => {
 	} finally {
 		if (previousAgentHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
 		else process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		if (previousShell === undefined) delete process.env.GENTLE_PI_SHELL;
+		else process.env.GENTLE_PI_SHELL = previousShell;
 	}
 });