gentle-pi 3.7.0 → 4.0.0

package/tests/review-candidate-view.test.ts

@@ -364,6 +364,164 @@ test("candidate owner publication never removes a replaced marker", (t) => {
 	assert.equal(readdirSync(parent).some((name) => name.endsWith(".reaper-lock")), false);
 });
 
+test("public POSIX candidate-views parent reports bounded privacy guidance without changing permissions or adding a worktree", { skip: process.platform === "win32" }, (t) => {
+	const cwd = repository(t);
+	const parent = join(cwd, ".git", "gentle-ai", "candidate-views");
+	mkdirSync(parent, { recursive: true, mode: 0o700 });
+	chmodSync(parent, 0o777);
+	let adds = 0;
+	const registry = new CandidateViewRegistry((file, args, options) => {
+		if (args[0] === "worktree" && args[1] === "add") adds++;
+		return execFileSync(file, args, options);
+	});
+	assert.throws(() => registry.create({ contributorRoot: cwd }), (error: unknown) => {
+		assert.ok(error instanceof CandidateViewError);
+		assert.equal(error.reason, "candidate-owner-preparation-failed");
+		assert.deepEqual(error.diagnostics, {
+			code: "candidate-owner-parent-privacy",
+			message: "candidate-views parent must be owned by the current user and inaccessible to group and others; inspect its ownership and permissions, then correct them out of band before retrying START",
+		});
+		assert.doesNotMatch(JSON.stringify(error.diagnostics), new RegExp(cwd));
+		return true;
+	});
+	assert.equal(lstatSync(parent).mode & 0o777, 0o777);
+	assert.equal(adds, 0);
+	chmodSync(parent, 0o700);
+	const view = registry.create({ contributorRoot: cwd });
+	view.cleanup();
+});
+
+test("POSIX chmod-ineffective parent reports filesystem capability guidance before worktree creation", { skip: process.platform === "win32" }, (t) => {
+	const cwd = repository(t);
+	const parent = join(cwd, ".git", "gentle-ai", "candidate-views");
+	mkdirSync(parent, { recursive: true, mode: 0o700 });
+	chmodSync(parent, 0o777);
+	const originalLstat = fs.lstatSync;
+	t.mock.method(fs, "lstatSync", (path: Parameters<typeof fs.lstatSync>[0], ...args: unknown[]) => {
+		const stat = (originalLstat as (...arguments_: unknown[]) => ReturnType<typeof fs.lstatSync>)(path, ...args);
+		return typeof path === "string" && path.includes(".gentle-ai-chmod-probe-")
+			? Object.assign(Object.create(Object.getPrototypeOf(stat)), stat, { mode: (Number(stat.mode) & ~0o777) | 0o777, uid: process.getuid?.() })
+			: stat;
+	});
+	syncBuiltinESMExports();
+	t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+	let adds = 0;
+	const registry = new CandidateViewRegistry((file, args, options) => {
+		if (args[0] === "worktree" && args[1] === "add") adds++;
+		return execFileSync(file, args, options);
+	});
+	assert.throws(() => registry.create({ contributorRoot: cwd }), (error: unknown) => {
+		assert.ok(error instanceof CandidateViewError);
+		assert.equal(error.reason, "candidate-owner-preparation-failed");
+		assert.deepEqual(error.diagnostics, {
+			code: "candidate-owner-parent-chmod-ineffective",
+			message: "candidate-views parent filesystem does not honor POSIX permission changes; move this repository's Git common directory to a POSIX-metadata filesystem or enable metadata support before retrying START",
+		});
+		assert.doesNotMatch(JSON.stringify(error.diagnostics), new RegExp(cwd));
+		return true;
+	});
+	assert.equal(adds, 0);
+	assert.equal(readdirSync(parent).some((name) => name.includes(".gentle-ai-chmod-probe-")), false);
+});
+
+test("inconclusive private-mode probe keeps bounded privacy guidance instead of claiming ineffective chmod", { skip: process.platform === "win32" }, (t) => {
+	const cwd = repository(t);
+	const parent = join(cwd, ".git", "gentle-ai", "candidate-views");
+	mkdirSync(parent, { recursive: true, mode: 0o700 });
+	chmodSync(parent, 0o777);
+	const originalMkdir = fs.mkdirSync;
+	t.mock.method(fs, "mkdirSync", (path: Parameters<typeof fs.mkdirSync>[0], ...args: unknown[]) => {
+		if (typeof path === "string" && path.includes(".gentle-ai-chmod-probe-")) throw Object.assign(new Error("probe creation refused"), { code: "EACCES" });
+		return (originalMkdir as (...arguments_: unknown[]) => ReturnType<typeof fs.mkdirSync>)(path, ...args);
+	});
+	syncBuiltinESMExports();
+	t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+	let adds = 0;
+	const registry = new CandidateViewRegistry((file, args, options) => {
+		if (args[0] === "worktree" && args[1] === "add") adds++;
+		return execFileSync(file, args, options);
+	});
+	assert.throws(() => registry.create({ contributorRoot: cwd }), (error: unknown) => {
+		assert.ok(error instanceof CandidateViewError);
+		assert.equal(error.reason, "candidate-owner-preparation-failed");
+		assert.deepEqual(error.diagnostics, {
+			code: "candidate-owner-parent-privacy",
+			message: "candidate-views parent must be owned by the current user and inaccessible to group and others; inspect its ownership and permissions, then correct them out of band before retrying START",
+		});
+		assert.doesNotMatch(JSON.stringify(error.diagnostics), new RegExp(cwd));
+		return true;
+	});
+	assert.equal(adds, 0);
+	assert.equal(readdirSync(parent).some((name) => name.includes(".gentle-ai-chmod-probe-")), false);
+	chmodSync(parent, 0o700);
+	const view = registry.create({ contributorRoot: cwd });
+	view.cleanup();
+});
+
+test("POSIX parent privacy classification does not probe a replaced path after validating it", { skip: process.platform === "win32" }, (t) => {
+	const cwd = repository(t);
+	const commonDir = realpathSync(join(cwd, ".git"));
+	const parent = join(commonDir, "gentle-ai", "candidate-views");
+	mkdirSync(parent, { recursive: true, mode: 0o700 });
+	const originalLstat = fs.lstatSync;
+	let parentProbes = 0;
+	t.mock.method(fs, "lstatSync", (path: Parameters<typeof fs.lstatSync>[0], ...args: unknown[]) => {
+		if (path === parent && ++parentProbes === 2) {
+			const moved = `${parent}-moved`;
+			renameSync(parent, moved);
+			symlinkSync(moved, parent, "dir");
+		}
+		return (originalLstat as (...args: unknown[]) => ReturnType<typeof fs.lstatSync>)(path, ...args);
+	});
+	syncBuiltinESMExports();
+	t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+	let failure: unknown;
+	try { assertCandidateOwnerParent(commonDir); } catch (error) { failure = error; }
+	assert.equal(parentProbes, 1, "the privacy decision must share the checked directory probe");
+	assert.equal(failure, undefined);
+});
+
+test("POSIX non-directory and symlink parents never receive privacy guidance", { skip: process.platform === "win32" }, (t) => {
+	const cwd = repository(t);
+	const commonDir = realpathSync(join(cwd, ".git"));
+	const control = join(commonDir, "gentle-ai");
+	const parent = join(control, "candidate-views");
+	mkdirSync(control, { recursive: true, mode: 0o700 });
+	for (const kind of ["file", "symlink"] as const) {
+		if (kind === "file") writeFileSync(parent, "not a directory");
+		else symlinkSync(control, parent, "dir");
+		assert.throws(() => assertCandidateOwnerParent(commonDir), (error: unknown) => {
+			assert.notEqual((error as Error).name, "PosixCandidateOwnerParentPrivacyError");
+			return true;
+		});
+		rmSync(parent);
+	}
+});
+
+test("owner privacy diagnostic sanitizer rejects injected text", () => {
+	for (const code of ["candidate-owner-parent-privacy", "candidate-owner-parent-chmod-ineffective"] as const) {
+		const forged = new CandidateViewError("rejected", "candidate-owner-preparation-failed", {
+			code,
+			message: "private-fixture-path-and-user",
+		} as unknown as ConstructorParameters<typeof CandidateViewError>[2]);
+		assert.equal(forged.diagnostics, undefined);
+	}
+});
+
+test("unknown owner failures never expose arbitrary messages in diagnostics", (t) => {
+	const cwd = repository(t);
+	const secret = "private-fixture-path-and-user";
+	t.mock.method(fs, "fsyncSync", () => { throw new Error(secret); });
+	syncBuiltinESMExports();
+	t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+	assert.throws(() => new CandidateViewRegistry().create({ contributorRoot: cwd }), (error: unknown) => {
+		assert.ok(error instanceof CandidateViewError);
+		assert.equal(error.diagnostics, undefined);
+		assert.doesNotMatch(error.message, /private-fixture-path-and-user/);
+		return true;
+	});
+});
+
 test("candidate owner rejects an absent POSIX getuid before worktree creation", { skip: process.platform === "win32" }, (t) => {
 	const originalGetuid = process.getuid;
 	Object.defineProperty(process, "getuid", { configurable: true, value: undefined });
@@ -1619,6 +1777,100 @@ test("candidate view accepts internal relative symlink targets and rejects unsaf
 	}
 });
 
+test("unchanged committed symlinks materialize as links with core.symlinks disabled or enabled", (t) => {
+	const contributorRoot = repository(t);
+	mkdirSync(join(contributorRoot, "nested"));
+	mkdirSync(join(contributorRoot, "target-dir"));
+	writeFileSync(join(contributorRoot, "target-dir", "file.txt"), "frozen target\n");
+	try {
+		symlinkSync("../target-dir/file.txt", join(contributorRoot, "nested", "link"));
+		symlinkSync("../target-dir", join(contributorRoot, "nested", "directory-link"), "dir");
+		symlinkSync("../missing-file", join(contributorRoot, "nested", "dangling-link"));
+	}
+	catch { t.skip("native symlink creation unavailable"); return; }
+	git(contributorRoot, "add", "nested/link", "nested/directory-link", "nested/dangling-link", "target-dir/file.txt");
+	git(contributorRoot, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "link base");
+	for (const setting of ["false", "true"]) {
+		git(contributorRoot, "config", "core.symlinks", setting);
+		writeFileSync(join(contributorRoot, "tracked.txt"), `changed ${setting}\n`);
+		const view = createCandidateView({ contributorRoot });
+		try {
+			assert.deepEqual(view.paths, ["tracked.txt"]);
+			assert.equal(lstatSync(join(view.root, "nested", "link")).isSymbolicLink(), true);
+			assert.equal(readFileSync(join(view.root, "nested", "link"), "utf8"), "frozen target\n");
+			assert.equal(readFileSync(join(view.root, "nested", "directory-link", "file.txt"), "utf8"), "frozen target\n");
+			assert.equal(lstatSync(join(view.root, "nested", "dangling-link")).isSymbolicLink(), true);
+			assert.equal(readFileSync(join(view.root, "tracked.txt"), "utf8"), `changed ${setting}\n`);
+			assert.equal(git(contributorRoot, "config", "core.symlinks"), setting);
+			view.verify();
+		} finally { view.cleanup(); }
+	}
+});
+
+test("frozen symlink bytes survive disabled checkout, while replaced links and regular files fail verification", (t) => {
+	const cwd = repository(t);
+	try { symlinkSync("tracked.txt", join(cwd, "alias")); }
+	catch { t.skip("native symlink creation unavailable"); return; }
+	git(cwd, "add", "alias");
+	git(cwd, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "link base");
+	git(cwd, "config", "core.symlinks", "false");
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const view = createCandidateView({ contributorRoot: cwd });
+	try {
+		assert.deepEqual(readFileSync(join(view.root, "alias"), "utf8"), "changed\n");
+		assert.equal(git(cwd, "cat-file", "blob", git(cwd, "rev-parse", "HEAD:alias")), "tracked.txt");
+		for (const replacement of ["other.txt", "../escape", null]) {
+			chmodSync(view.root, 0o755);
+			rmSync(join(view.root, "alias"));
+			if (replacement === null) writeFileSync(join(view.root, "alias"), "tracked.txt");
+			else symlinkSync(replacement, join(view.root, "alias"));
+			assert.throws(() => view.verify(), CandidateViewError);
+		}
+	} finally { view.cleanup(); }
+});
+
+test("unsafe frozen symlink blobs are rejected before any link is created with core.symlinks disabled", (t) => {
+	for (const target of ["/absolute", "../escape", ".git/config", "bad\\\\target", "bad//target"]) {
+		const cwd = repository(t);
+		git(cwd, "config", "core.symlinks", "false");
+		const safe = execFileSync("git", ["hash-object", "-w", "--stdin"], { cwd, input: "tracked.txt", encoding: "utf8" }).trim();
+		const unsafe = execFileSync("git", ["hash-object", "-w", "--stdin"], { cwd, input: target, encoding: "utf8" }).trim();
+		git(cwd, "update-index", "--add", "--cacheinfo", `120000,${safe},a-safe-link`);
+		git(cwd, "update-index", "--add", "--cacheinfo", `120000,${unsafe},z-unsafe-link`);
+		const base = git(cwd, "rev-parse", "HEAD");
+		git(cwd, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "unsafe frozen link");
+		let creations = 0;
+		const original = fs.symlinkSync;
+		t.mock.method(fs, "symlinkSync", (...args: Parameters<typeof fs.symlinkSync>) => { creations++; return original(...args); });
+		syncBuiltinESMExports();
+		try { assert.throws(() => createCandidateView({ contributorRoot: cwd, baseRef: base, committedOnly: true }), CandidateViewError, target); }
+		finally { t.mock.restoreAll(); syncBuiltinESMExports(); }
+		assert.equal(creations, 0, target);
+		assert.equal(git(cwd, "config", "core.symlinks"), "false");
+	}
+});
+
+test("unavailable native symlink capability fails with bounded reason and cleans owned view", (t) => {
+	const cwd = repository(t);
+	try { symlinkSync("tracked.txt", join(cwd, "alias")); }
+	catch { t.skip("native symlink creation unavailable for fixture"); return; }
+	git(cwd, "add", "alias");
+	git(cwd, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "link base");
+	git(cwd, "config", "core.symlinks", "false");
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const original = fs.symlinkSync;
+	t.mock.method(fs, "symlinkSync", (...args: Parameters<typeof fs.symlinkSync>) => {
+		if (String(args[1]).includes("candidate-views")) throw Object.assign(new Error("private path and user"), { code: "EPERM" });
+		return original(...args);
+	});
+	syncBuiltinESMExports();
+	t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+	assert.throws(() => createCandidateView({ contributorRoot: cwd }), (error: unknown) => error instanceof CandidateViewError && error.reason === "symlink-materialization-failed" && !error.message.includes("private path and user"));
+	const parent = join(cwd, ".git", "gentle-ai", "candidate-views");
+	assert.deepEqual(readdirSync(parent), []);
+	assert.equal(git(cwd, "worktree", "list", "--porcelain").includes("candidate-views"), false);
+});
+
 test("candidate view detects symlink target-byte tampering after materialization", (t) => {
 	const contributorRoot = repository(t);
 	const link = join(contributorRoot, "candidate-link");
@@ -1843,6 +2095,52 @@ test("native projections recover a committed range base from its frozen tree", (
 	assert.equal(projection.committedOnly, true);
 });
 
+test("provider-owned tree remains the exact base across reuse, correction and native dispatch restoration", (t) => {
+	const contributorRoot = repository(t);
+	const baseTree = git(contributorRoot, "rev-parse", "HEAD^{tree}");
+	writeFileSync(join(contributorRoot, "tracked.txt"), "tree-backed candidate\n");
+	git(contributorRoot, "add", "tracked.txt");
+	git(contributorRoot, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "candidate");
+	const head = git(contributorRoot, "rev-parse", "HEAD");
+	const candidateTree = git(contributorRoot, "rev-parse", "HEAD^{tree}");
+	const registry = new CandidateViewRegistry();
+	const first = registry.createOrReuse({ contributorRoot, providerBaseTree: baseTree, committedOnly: true, replayKey: "provider-tree" });
+	try {
+		const reused = registry.createOrReuse({ contributorRoot, providerBaseTree: baseTree, committedOnly: true, replayKey: "provider-tree" });
+		assert.equal(reused.token, first.token);
+		assert.equal(first.baseTree, baseTree);
+		assert.equal(first.baseCommit, head, "HEAD anchors the worktree, not the diff base");
+		registry.retain(first.token, "tree-lineage");
+		const corrected = registry.createCorrected("tree-lineage", contributorRoot, "tree-correction");
+		assert.equal(corrected.baseTree, baseTree);
+		registry.promoteCorrected("tree-lineage", corrected.token, contributorRoot);
+		assert.equal(registry.resolveProjection("tree-lineage", contributorRoot).providerBaseTree, baseTree);
+		const restored = new CandidateViewRegistry();
+		try {
+			restored.restoreCurrentForDispatchFromNative("restored-tree", contributorRoot, { baseTree, currentCandidateTree: candidateTree, paths: ["tracked.txt"], intendedUntracked: [], projection: "staged" }, ["review-reliability"], baseTree);
+			const view = restored.resolveCurrentForLens("review-reliability", contributorRoot);
+			assert.equal(view.baseTree, baseTree);
+			assert.equal(restored.resolveProjection("restored-tree", contributorRoot).providerBaseTree, baseTree);
+		} finally { restored.cleanupAll(); }
+		const finalized = new CandidateViewRegistry();
+		try {
+			const view = finalized.restoreForFinalizeFromNative("finalized-tree", contributorRoot, { baseTree, currentCandidateTree: candidateTree, paths: ["tracked.txt"], intendedUntracked: [], projection: "staged" }, baseTree);
+			assert.equal(view.baseTree, baseTree);
+			assert.equal(finalized.resolveProjection("finalized-tree", contributorRoot).providerBaseTree, baseTree);
+		} finally { finalized.cleanupAll(); }
+	} finally { registry.cleanupAll(); }
+});
+
+test("provider tree materialization and restoration reject wrong objects and mismatched frozen bases", (t) => {
+	const contributorRoot = repository(t);
+	const head = git(contributorRoot, "rev-parse", "HEAD");
+	const baseTree = git(contributorRoot, "rev-parse", "HEAD^{tree}");
+	assert.throws(() => new CandidateViewRegistry().create({ contributorRoot, providerBaseTree: head, committedOnly: true }), (error: unknown) => error instanceof CandidateViewError && error.reason === "provider-base-tree-invalid");
+	assert.throws(() => new CandidateViewRegistry().create({ contributorRoot, baseRef: head, providerBaseTree: baseTree, committedOnly: true }), (error: unknown) => error instanceof CandidateViewError && error.reason === "provider-base-tree-invalid");
+	const registry = new CandidateViewRegistry();
+	assert.throws(() => registry.restoreProjectionFromNative("wrong-tree", contributorRoot, { baseTree, currentCandidateTree: baseTree, paths: [], intendedUntracked: [], projection: "workspace" }, head), (error: unknown) => error instanceof CandidateViewError && error.reason === "provider-base-tree-invalid");
+});
+
 test("fresh registries restore only one exact authoritative reviewing candidate and reject zero or multiple matches", (t) => {
 	const contributorRoot = repository(t);
 	writeFileSync(join(contributorRoot, "tracked.txt"), "reviewing\n");

package/tests/review-contract-prompt.test.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import test from "node:test";
+import test, { after, before } from "node:test";
 import { pathToFileURL } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
@@ -16,12 +16,43 @@ import type { NativeReviewCli } from "../lib/native-review-cli.ts";
 // These tests exercise the real committed mirror (contracts/review-provider-contract-mirror/)
 // rather than a fake one: the mirror IS the package under test.
 
-type BeforeAgentStartResult = { systemPrompt: string };
+type BeforeAgentStartResult = undefined;
 type BeforeAgentStartHandler = (event: unknown, ctx: ExtensionContext) => Promise<BeforeAgentStartResult>;
+type MutableEvent = { agentName?: string; systemPrompt: string; systemPromptOptions: { appendSystemPrompt: string } };
 
 const REPO_ROOT = join(import.meta.dirname, "..");
 const MIRROR_LOCK_PATH = join(REPO_ROOT, "contracts", "review-provider-contract-mirror", "provider-contract.lock.json");
 
+let fixtureRoot: string | undefined;
+let fixtureCwd: string;
+const fixtureEnvironment: NodeJS.ProcessEnv = {};
+const previousEnvironment = new Map<string, string | undefined>();
+before(() => {
+	fixtureRoot = mkdtempSync(join(tmpdir(), "gentle-pi-review-prompt-"));
+	fixtureCwd = join(fixtureRoot, "project");
+	const home = join(fixtureRoot, "home");
+	mkdirSync(fixtureCwd);
+	mkdirSync(home);
+	Object.assign(fixtureEnvironment, {
+		HOME: home, USERPROFILE: home,
+		GENTLE_PI_CONFIG_HOME: join(home, "config"),
+		GENTLE_PI_AGENT_HOME: join(home, "agents"),
+		PI_CODING_AGENT_DIR: join(home, "pi"),
+		XDG_CONFIG_HOME: join(home, "xdg"),
+	});
+	for (const [key, value] of Object.entries(fixtureEnvironment)) {
+		previousEnvironment.set(key, process.env[key]);
+		process.env[key] = value;
+	}
+});
+after(() => {
+	for (const [key, value] of previousEnvironment) {
+		if (value === undefined) delete process.env[key];
+		else process.env[key] = value;
+	}
+	if (fixtureRoot !== undefined) rmSync(fixtureRoot, { recursive: true, force: true });
+});
+
 function mirroredPiOrchestrationText(): string {
 	const lock = JSON.parse(readFileSync(MIRROR_LOCK_PATH, "utf8")) as { contract_semver: string };
 	return readFileSync(
@@ -30,7 +61,7 @@ function mirroredPiOrchestrationText(): string {
 	).trim();
 }
 
-function harness(nativeReviewCli: NativeReviewCli | null): { beforeAgentStart: BeforeAgentStartHandler } {
+function harness(nativeReviewCli: NativeReviewCli | null, processEnv?: NodeJS.ProcessEnv): { beforeAgentStart: BeforeAgentStartHandler } {
 	const handlers = new Map<string, BeforeAgentStartHandler>();
 	const pi = {
 		on(name: string, handler: BeforeAgentStartHandler) {
@@ -40,7 +71,12 @@ function harness(nativeReviewCli: NativeReviewCli | null): { beforeAgentStart: B
 		registerCommand() {},
 		registerTool() {},
 	} as unknown as ExtensionAPI;
-	createGentleAiExtension({ nativeReviewCli })(pi);
+	createGentleAiExtension({
+		nativeReviewCli,
+		processEnv: { ...fixtureEnvironment, GENTLE_PI_AGENTS_CHILD: "0", ...processEnv, GENTLE_AI_TELEMETRY: "0" },
+		resolveTelemetryTriggerBinary: () => join(fixtureCwd, "never-executed"),
+		telemetryTriggerSpawn: () => assert.fail("Review prompt fixtures must not spawn telemetry"),
+	})(pi);
 	const beforeAgentStart = handlers.get("before_agent_start");
 	assert.equal(typeof beforeAgentStart, "function");
 	return { beforeAgentStart: beforeAgentStart as BeforeAgentStartHandler };
@@ -48,7 +84,7 @@ function harness(nativeReviewCli: NativeReviewCli | null): { beforeAgentStart: B
 
 function ctx(overrides: Record<string, unknown> = {}): ExtensionContext {
 	return {
-		cwd: process.cwd(),
+		cwd: fixtureCwd,
 		hasUI: true,
 		ui: { notify() {} },
 		sessionManager: { getSessionId: () => "review-contract-prompt-session" },
@@ -56,28 +92,35 @@ function ctx(overrides: Record<string, unknown> = {}): ExtensionContext {
 	} as unknown as ExtensionContext;
 }
 
-const primaryEvent = { systemPrompt: "base" };
+function primaryEvent(overrides: Partial<MutableEvent> = {}): MutableEvent {
+	return { systemPrompt: "base", systemPromptOptions: { appendSystemPrompt: "" }, ...overrides };
+}
 
-test("before_agent_start injects the mirrored review execution contract for the primary session", async () => {
+test("before_agent_start injects the mirrored review execution contract for the primary session through appendSystemPrompt, never a returned systemPrompt", async () => {
 	const { beforeAgentStart } = harness({} as NativeReviewCli);
-	const result = await beforeAgentStart(primaryEvent, ctx());
+	const event = primaryEvent();
+	const result = await beforeAgentStart(event, ctx());
+	assert.equal(result, undefined, "the handler must not return a replacement systemPrompt");
+	const appended = event.systemPromptOptions.appendSystemPrompt;
 	const expected = mirroredPiOrchestrationText();
-	assert.match(result.systemPrompt, /Substantial authorized work: use ODD/);
-	assert.match(result.systemPrompt, /Use configured TDD mode, source, and exact runner/);
-	assert.match(result.systemPrompt, /test presence does not enable it/);
-	assert.doesNotMatch(result.systemPrompt, /If tests exist, use strict TDD/);
-	assert.match(result.systemPrompt, /ODD \(Default Workflow, harness section above\) is mandatory on every request/);
-	assert.doesNotMatch(result.systemPrompt, /Prefer SDD\/OpenSpec artifacts/);
-	assert.match(result.systemPrompt, /## Gentle AI review execution contract \(mirrored provider bundle 1\.2\.0\)/);
-	assert.ok(result.systemPrompt.includes(expected), "the mirrored orchestration/pi.md text must appear verbatim");
-	assert.match(result.systemPrompt, /call `gentle_review` with {"operation":"inspect"}/);
-	assert.match(result.systemPrompt, /call `gentle_review` with operation `status`, the exact retained `lineageId`, and `workspaceRoot`/);
-	assert.match(result.systemPrompt, /Use `gentle_review_capture` for one current returned slot or `gentle_review_capture_group` for the complete current reviewer group/);
-	assert.match(result.systemPrompt, /An eligible interactive Pi host may resolve `gentle-ai\.review-integration\.consent\/v3` before the envelope reaches the model/);
-	assert.match(result.systemPrompt, /If `gentle_review` returns the envelope unresolved, it is still the original provider-owned two-choice contract/);
-	assert.match(result.systemPrompt, /Never add the host action to a decoded or relayed provider envelope/);
-	assert.match(result.systemPrompt, /An approved capture awaits acknowledgement; it is not burned\. On `approved`, use bound facade STATUS to obtain or replay the exact provider-issued `acknowledge-approved` continuation, then execute it unchanged\. Only its successful returned envelope burns authority; do not issue STATUS after that burn\./);
-	let previousLifecycleIndex = result.systemPrompt.indexOf("## Gentle AI review execution contract");
+	assert.match(appended, /Substantial authorized work: use ODD/);
+	assert.match(appended, /For behavior changes with applicable runnable deterministic tests and a clear expected outcome, use test-first by default: observe RED, GREEN, then refactor with focused checks/);
+	assert.match(appended, /Test presence alone does not establish applicability; no chat or TUI toggle activates it/);
+	assert.match(appended, /no meaningful RED, explain why and run proportionate ordinary functional or structural verification/);
+	assert.match(appended, /Never invent lifecycle evidence or skip checks/);
+	assert.doesNotMatch(appended, /If tests exist, use strict TDD/);
+	assert.match(appended, /ODD \(Default Workflow, harness section above\) is mandatory on every request/);
+	assert.doesNotMatch(appended, /Prefer SDD\/OpenSpec artifacts/);
+	assert.match(appended, /## Gentle AI review execution contract \(mirrored provider bundle 1\.2\.0\)/);
+	assert.ok(appended.includes(expected), "the mirrored orchestration/pi.md text must appear verbatim");
+	assert.match(appended, /call `gentle_review` with {"operation":"inspect"}/);
+	assert.match(appended, /call `gentle_review` with operation `status`, the exact retained `lineageId`, and `workspaceRoot`/);
+	assert.match(appended, /Use `gentle_review_capture` for one current returned slot or `gentle_review_capture_group` for the complete current reviewer group/);
+	assert.match(appended, /An eligible interactive Pi host may resolve `gentle-ai\.review-integration\.consent\/v3` before the envelope reaches the model/);
+	assert.match(appended, /If `gentle_review` returns the envelope unresolved, it is still the original provider-owned two-choice contract/);
+	assert.match(appended, /Never add the host action to a decoded or relayed provider envelope/);
+	assert.match(appended, /An approved capture awaits acknowledgement; it is not burned\. On `approved`, use bound facade STATUS to obtain or replay the exact provider-issued `acknowledge-approved` continuation, then execute it unchanged\. Only its successful returned envelope burns authority; do not issue STATUS after that burn\./);
+	let previousLifecycleIndex = appended.indexOf("## Gentle AI review execution contract");
 	for (const marker of [
 		'call `gentle_review` with {"operation":"inspect"}',
 		"2. **Freeze once.**",
@@ -85,47 +128,69 @@ test("before_agent_start injects the mirrored review execution contract for the
 		"Use `gentle_review_capture` for one current returned slot",
 		"5. **Acknowledge exactly.**",
 	]) {
-		const markerIndex = result.systemPrompt.indexOf(marker, previousLifecycleIndex + 1);
+		const markerIndex = appended.indexOf(marker, previousLifecycleIndex + 1);
 		assert.ok(markerIndex > previousLifecycleIndex, `${marker} must follow the previous lifecycle step`);
 		previousLifecycleIndex = markerIndex;
 	}
-	assert.doesNotMatch(result.systemPrompt, /authority is already burned/);
-	assert.doesNotMatch(result.systemPrompt, /gentle-ai review status\b.*--agent pi/);
+	assert.doesNotMatch(appended, /authority is already burned/);
+	assert.doesNotMatch(appended, /gentle-ai review status\b.*--agent pi/);
 });
 
 test("before_agent_start does not inject the review execution contract for a named agent session", async () => {
 	const { beforeAgentStart } = harness({} as NativeReviewCli);
-	const result = await beforeAgentStart({ agentName: "review-readability", systemPrompt: "base" }, ctx());
-	assert.doesNotMatch(result.systemPrompt, /Gentle AI review execution contract/);
+	const event = primaryEvent({ agentName: "review-readability" });
+	await beforeAgentStart(event, ctx());
+	assert.doesNotMatch(event.systemPromptOptions.appendSystemPrompt, /Gentle AI review execution contract/);
 });
 
 test("before_agent_start does not inject the review execution contract for gentle-ai-worker", async () => {
 	const { beforeAgentStart } = harness({} as NativeReviewCli);
-	const result = await beforeAgentStart({ agentName: "gentle-ai-worker", systemPrompt: "base" }, ctx());
-	assert.equal(result.systemPrompt, "base");
-	assert.doesNotMatch(result.systemPrompt, /Substantial authorized work: use ODD/);
-	assert.doesNotMatch(result.systemPrompt, /Gentle AI review execution contract/);
+	const event = primaryEvent({ agentName: "gentle-ai-worker" });
+	await beforeAgentStart(event, ctx());
+	assert.equal(event.systemPromptOptions.appendSystemPrompt, "", "a named agent gets nothing appended");
 });
 
 test("before_agent_start does not inject the review execution contract for jd-fix-agent", async () => {
 	const { beforeAgentStart } = harness({} as NativeReviewCli);
-	const result = await beforeAgentStart({ agentName: "jd-fix-agent", systemPrompt: "base" }, ctx());
-	assert.equal(result.systemPrompt, "base");
-	assert.doesNotMatch(result.systemPrompt, /Substantial authorized work: use ODD/);
-	assert.doesNotMatch(result.systemPrompt, /Gentle AI review execution contract/);
+	const event = primaryEvent({ agentName: "jd-fix-agent" });
+	await beforeAgentStart(event, ctx());
+	assert.equal(event.systemPromptOptions.appendSystemPrompt, "", "a named agent gets nothing appended");
 });
 
-test("before_agent_start does not inject the review execution contract for an SDD executor session", async () => {
+test("before_agent_start does not let legacy prompt text bypass primary ODD and review injection", async () => {
 	const { beforeAgentStart } = harness({} as NativeReviewCli);
-	const result = await beforeAgentStart({ systemPrompt: "SDD apply executor body" }, ctx());
-	assert.doesNotMatch(result.systemPrompt, /Substantial authorized work: use ODD/);
-	assert.doesNotMatch(result.systemPrompt, /Gentle AI review execution contract/);
+	const event = primaryEvent({ systemPrompt: "SDD apply executor body" });
+	await beforeAgentStart(event, ctx());
+	const appended = event.systemPromptOptions.appendSystemPrompt;
+	assert.match(appended, /Substantial authorized work: use ODD/);
+	assert.match(appended, /Gentle AI review execution contract/);
+	assert.doesNotMatch(appended, /### 3\. SDD \(optional\)/);
+});
+
+test("before_agent_start does not inject the review execution contract or gentlePrompt for a child session (GENTLE_PI_AGENTS_CHILD=1)", async () => {
+	const { beforeAgentStart } = harness({} as NativeReviewCli, { GENTLE_PI_AGENTS_CHILD: "1" });
+	const event = primaryEvent({ systemPromptOptions: { appendSystemPrompt: "Worker-specific instructions" } });
+	const result = await beforeAgentStart(event, ctx());
+	assert.equal(result, undefined, "the handler must not return a replacement systemPrompt");
+	assert.equal(event.systemPromptOptions.appendSystemPrompt, "Worker-specific instructions", "child instructions must remain unchanged, without primary harness or review injection");
 });
 
 test("before_agent_start injects nothing when nativeReviewCli is null", async () => {
 	const { beforeAgentStart } = harness(null);
-	const result = await beforeAgentStart(primaryEvent, ctx());
-	assert.doesNotMatch(result.systemPrompt, /Gentle AI review execution contract/);
+	const event = primaryEvent();
+	await beforeAgentStart(event, ctx());
+	assert.doesNotMatch(event.systemPromptOptions.appendSystemPrompt, /Gentle AI review execution contract/);
+});
+
+test("before_agent_start is idempotent: running twice on the same systemPromptOptions never duplicates the harness", async () => {
+	const { beforeAgentStart } = harness({} as NativeReviewCli);
+	const event = primaryEvent();
+	await beforeAgentStart(event, ctx());
+	const firstLength = event.systemPromptOptions.appendSystemPrompt.length;
+	await beforeAgentStart(event, ctx());
+	assert.equal(event.systemPromptOptions.appendSystemPrompt.length, firstLength, "a second run on the same options object must not append again");
+	const occurrences = event.systemPromptOptions.appendSystemPrompt.split("Gentle AI review execution contract").length - 1;
+	assert.equal(occurrences, 1);
 });
 
 // gentle-ai R1/R3: a tampered mirrored orchestration/pi.md must never be spliced into the system prompt.

package/tests/review-controller-lock-status.test.ts

@@ -101,7 +101,6 @@ function fakeNative(status: NativeReviewStatusResult, onStart?: (request: Parame
 		finalize: async () => { throw new Error("finalize must not run"); },
 		validate: async () => { throw new Error("validate must not run"); },
 		bindSdd: async () => { throw new Error("bindSdd must not run"); },
-		sddStatus: async () => ({ ready: false }),
 		reviewStatus: async () => { throw new Error("inventory status must not run"); },
 		targetStatus: async () => ({
 			applicability: blocking ? "corrupted" : "unrelated",