gentle-pi 2.3.0 → 2.4.0

package/tests/review-agent-end-preflight.test.ts

@@ -0,0 +1,408 @@
+import assert from "node:assert/strict";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import type { NativeReviewCli } from "../lib/native-review-cli.ts";
+import type { ReviewStatusV3 } from "../lib/review-integration-v2.ts";
+
+// gentle-pi#556 / gentle-ai#4051: with RDD enabled, the agent finished an
+// implementation and reported completion without ever entering the review
+// preflight. These tests cover the read-only, idempotent `agent_end` nudge
+// that reminds the agent to call gentle_review before reporting completion,
+// without ever starting a review or answering consent itself.
+//
+// gentle-pi#568: `session_start` records the target identity STATUS reports
+// at session start as a baseline, so `agent_end` skips a candidate that
+// already existed before this session touched the worktree (the user's own
+// pre-session work, not this session's output). These tests point
+// `GENTLE_PI_AGENT_HOME` and the session `cwd` at fresh temp directories so
+// `session_start`'s real SDD asset install and model config sweep never
+// touch this machine's actual home directory.
+
+type AnyHandler = (event: unknown, ctx: ExtensionContext) => unknown;
+type SentMessage = { message: Record<string, unknown>; options: Record<string, unknown> };
+
+function harness(nativeReviewCli: NativeReviewCli | null): {
+	handlers: Map<string, AnyHandler>;
+	sent: SentMessage[];
+} {
+	const handlers = new Map<string, AnyHandler>();
+	const sent: SentMessage[] = [];
+	const pi = {
+		on(name: string, handler: AnyHandler) {
+			handlers.set(name, handler);
+		},
+		events: { emit() {} },
+		registerCommand() {},
+		registerTool() {},
+		sendMessage(message: Record<string, unknown>, options: Record<string, unknown> = {}) {
+			sent.push({ message, options });
+		},
+	} as unknown as ExtensionAPI;
+	createGentleAiExtension({ nativeReviewCli })(pi);
+	return { handlers, sent };
+}
+
+function ctx(sessionId: string, hasUI = true, cwd = process.cwd()): ExtensionContext {
+	return {
+		cwd,
+		hasUI,
+		ui: { notify() {} },
+		sessionManager: { getSessionId: () => sessionId },
+	} as unknown as ExtensionContext;
+}
+
+async function withSessionStartEnv<T>(callback: (cwd: string) => Promise<T>): Promise<T> {
+	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+	const previousConfigHome = process.env.GENTLE_PI_CONFIG_HOME;
+	process.env.GENTLE_PI_AGENT_HOME = await mkdtemp(join(tmpdir(), "gentle-pi-session-baseline-agent-home-"));
+	// Isolates both the model-config sweep and the dev-binary registration
+	// lookup from this machine's real ~/.pi/gentle-ai, so `session_start`'s
+	// unrelated notifications never leak into these assertions.
+	process.env.GENTLE_PI_CONFIG_HOME = await mkdtemp(join(tmpdir(), "gentle-pi-session-baseline-config-home-"));
+	try {
+		const cwd = await mkdtemp(join(tmpdir(), "gentle-pi-session-baseline-cwd-"));
+		return await callback(cwd);
+	} finally {
+		if (previousAgentHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		if (previousConfigHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previousConfigHome;
+	}
+}
+
+function onMode(effective: "on" | "off"): NativeReviewCli["reviewMode"] {
+	return async () => ({
+		operation: "status",
+		scope: "clone",
+		status: { global: "", cloneLocal: effective === "on" ? "on" : "", effective, source: "clone_local" },
+	});
+}
+
+function executeStartStatus(targetIdentity: string): ReviewStatusV3 {
+	return {
+		applicability: "unrelated",
+		action: "start",
+		targetIdentity,
+		nextTransition: { kind: "execute", execute: { operation: "review.start", arguments: [] } },
+	} as unknown as ReviewStatusV3;
+}
+
+function collectStatus(targetIdentity: string): ReviewStatusV3 {
+	return {
+		applicability: "unrelated",
+		action: "start",
+		targetIdentity,
+		nextTransition: { kind: "collect", collect: { inputs: [] } },
+	} as unknown as ReviewStatusV3;
+}
+
+function stopStatus(targetIdentity: string): ReviewStatusV3 {
+	return {
+		applicability: "unrelated",
+		action: "start",
+		targetIdentity,
+		nextTransition: { kind: "stop" },
+	} as unknown as ReviewStatusV3;
+}
+
+const agentEndEvent = { type: "agent_end", messages: [] };
+
+test("agent_end performs no STATUS call and sends nothing when RDD is off", async () => {
+	const statusRequests: unknown[] = [];
+	const native = {
+		reviewMode: onMode("off"),
+		targetStatus: async (request: unknown) => {
+			statusRequests.push(request);
+			throw new Error("targetStatus must not be called when RDD is off");
+		},
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const agentEnd = handlers.get("agent_end");
+	assert.equal(typeof agentEnd, "function");
+	await agentEnd!(agentEndEvent, ctx("agent-end-rdd-off"));
+	assert.deepEqual(statusRequests, []);
+	assert.deepEqual(sent, []);
+});
+
+test("agent_end nudges exactly once when RDD is on and STATUS offers review.start", async () => {
+	const targetIdentity = `sha256:${"a".repeat(64)}`;
+	const statusRequests: Array<{ agent?: string }> = [];
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async (request: { agent?: string }) => {
+			statusRequests.push(request);
+			return executeStartStatus(targetIdentity);
+		},
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const agentEnd = handlers.get("agent_end");
+	await agentEnd!(agentEndEvent, ctx("agent-end-execute"));
+
+	assert.equal(sent.length, 1);
+	const [entry] = sent;
+	assert.equal(entry?.message.customType, "gentle-pi.review-preflight");
+	const content = String(entry?.message.content);
+	assert.match(content, /gentle_review/);
+	assert.ok(content.includes(targetIdentity), "message must name the target identity");
+	assert.equal(entry?.options.triggerTurn, true);
+	assert.equal(statusRequests[0]?.agent, "pi");
+});
+
+test("agent_end nudges once per target identity and again for a fresh identity", async () => {
+	let targetIdentity = `sha256:${"b".repeat(64)}`;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => executeStartStatus(targetIdentity),
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const agentEnd = handlers.get("agent_end");
+	const session = ctx("agent-end-repeat");
+
+	await agentEnd!(agentEndEvent, session);
+	await agentEnd!(agentEndEvent, session);
+	assert.equal(sent.length, 1, "the same target identity nudges only once");
+
+	targetIdentity = `sha256:${"e".repeat(64)}`;
+	await agentEnd!(agentEndEvent, session);
+	assert.equal(sent.length, 2, "a different target identity nudges again");
+});
+
+test("agent_end sends nothing when STATUS offers collect or stop", async () => {
+	for (const [label, status] of [
+		["collect", collectStatus(`sha256:${"c".repeat(64)}`)],
+		["stop", stopStatus(`sha256:${"d".repeat(64)}`)],
+	] as const) {
+		const native = {
+			reviewMode: onMode("on"),
+			targetStatus: async () => status,
+		} as unknown as NativeReviewCli;
+		const { handlers, sent } = harness(native);
+		const agentEnd = handlers.get("agent_end");
+		await agentEnd!(agentEndEvent, ctx(`agent-end-${label}`));
+		assert.deepEqual(sent, [], label);
+	}
+});
+
+test("agent_end skips headless sessions before any native call", async () => {
+	const native = {
+		reviewMode: async () => {
+			throw new Error("reviewMode must not be called when hasUI is false");
+		},
+		targetStatus: async () => {
+			throw new Error("targetStatus must not be called when hasUI is false");
+		},
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const agentEnd = handlers.get("agent_end");
+	await agentEnd!(agentEndEvent, ctx("agent-end-no-ui", false));
+	assert.deepEqual(sent, []);
+});
+
+test("agent_end pairs a named agent's start with its own end, then still nudges for the primary loop's end", async () => {
+	const targetIdentity = `sha256:${"f".repeat(64)}`;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => executeStartStatus(targetIdentity),
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const beforeAgentStart = handlers.get("before_agent_start");
+	const agentEnd = handlers.get("agent_end");
+	assert.equal(typeof beforeAgentStart, "function");
+	const session = ctx("agent-end-subagent");
+
+	await beforeAgentStart!({ agentName: "review-readability", systemPrompt: "" }, session);
+	await agentEnd!(agentEndEvent, session);
+	assert.deepEqual(sent, [], "the subagent's own loop end is suppressed");
+
+	await agentEnd!(agentEndEvent, session);
+	assert.equal(sent.length, 1, "the primary loop's end still nudges once the subagent's end is paired off");
+});
+
+test("agent_end resets the subagent depth when a fresh primary loop starts", async () => {
+	const targetIdentity = `sha256:${"1".repeat(64)}`;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => executeStartStatus(targetIdentity),
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const beforeAgentStart = handlers.get("before_agent_start");
+	const agentEnd = handlers.get("agent_end");
+	const session = ctx("agent-end-subagent-reset");
+
+	await beforeAgentStart!({ agentName: "review-readability", systemPrompt: "" }, session);
+	await beforeAgentStart!({ systemPrompt: "" }, session);
+	await agentEnd!(agentEndEvent, session);
+
+	assert.equal(sent.length, 1, "a fresh primary-loop start resets the depth so its own end nudges");
+});
+
+test("agent_end handler exists but sends nothing when nativeReviewCli is null", async () => {
+	const { handlers, sent } = harness(null);
+	const agentEnd = handlers.get("agent_end");
+	assert.equal(typeof agentEnd, "function");
+	await agentEnd!(agentEndEvent, ctx("agent-end-null-cli"));
+	assert.deepEqual(sent, []);
+});
+
+test("agent_end sends nothing and does not throw when target STATUS rejects", async () => {
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => {
+			throw new Error("native status unavailable");
+		},
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const agentEnd = handlers.get("agent_end");
+	await assert.doesNotReject(async () => agentEnd!(agentEndEvent, ctx("agent-end-status-throws")));
+	assert.deepEqual(sent, []);
+});
+
+test("session_shutdown clears the nudged-target set for its session key", async () => {
+	const targetIdentity = `sha256:${"9".repeat(64)}`;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => executeStartStatus(targetIdentity),
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const agentEnd = handlers.get("agent_end");
+	const shutdown = handlers.get("session_shutdown");
+	assert.equal(typeof shutdown, "function");
+	const session = ctx("agent-end-shutdown");
+
+	await agentEnd!(agentEndEvent, session);
+	assert.equal(sent.length, 1);
+
+	await shutdown!({}, session);
+	await agentEnd!(agentEndEvent, session);
+	assert.equal(sent.length, 2, "shutdown clears the nudged set so the same identity nudges again");
+});
+
+test("session_start records the baseline target identity when RDD is on", async () => {
+	const targetIdentity = `sha256:${"2".repeat(64)}`;
+	const statusRequests: Array<{ agent?: string }> = [];
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async (request: { agent?: string }) => {
+			statusRequests.push(request);
+			return executeStartStatus(targetIdentity);
+		},
+	} as unknown as NativeReviewCli;
+	await withSessionStartEnv(async (cwd) => {
+		const { handlers, sent } = harness(native);
+		const sessionStart = handlers.get("session_start");
+		assert.equal(typeof sessionStart, "function");
+		const notifications: Array<{ message: string; severity: string }> = [];
+		const session = {
+			...ctx("session-baseline-record", true, cwd),
+			ui: { notify: (message: string, severity: string) => notifications.push({ message, severity }) },
+		};
+		await sessionStart!({}, session);
+		assert.equal(statusRequests[0]?.agent, "pi");
+		assert.deepEqual(sent, []);
+		assert.deepEqual(notifications, []);
+	});
+});
+
+test("agent_end skips the candidate that matches the session's recorded baseline, then nudges for a new one", async () => {
+	let targetIdentity = `sha256:${"3".repeat(64)}`;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => executeStartStatus(targetIdentity),
+	} as unknown as NativeReviewCli;
+	await withSessionStartEnv(async (cwd) => {
+		const { handlers, sent } = harness(native);
+		const sessionStart = handlers.get("session_start");
+		const agentEnd = handlers.get("agent_end");
+		const session = ctx("session-baseline-skip", true, cwd);
+
+		await sessionStart!({}, session);
+		await agentEnd!(agentEndEvent, session);
+		assert.deepEqual(sent, [], "the baseline candidate predates the session and is not nudged");
+
+		targetIdentity = `sha256:${"4".repeat(64)}`;
+		await agentEnd!(agentEndEvent, session);
+		assert.equal(sent.length, 1, "a candidate identity different from the baseline still nudges");
+	});
+});
+
+test("session_start with RDD off records no baseline, so agent_end still reminds once", async () => {
+	const targetIdentity = `sha256:${"5".repeat(64)}`;
+	let mode: "on" | "off" = "off";
+	const statusRequests: unknown[] = [];
+	const native = {
+		reviewMode: async () => ({
+			operation: "status",
+			scope: "clone",
+			status: { global: "", cloneLocal: mode === "on" ? "on" : "", effective: mode, source: "clone_local" },
+		}),
+		targetStatus: async (request: unknown) => {
+			statusRequests.push(request);
+			if (mode === "off") throw new Error("targetStatus must not be called when RDD is off");
+			return executeStartStatus(targetIdentity);
+		},
+	} as unknown as NativeReviewCli;
+	await withSessionStartEnv(async (cwd) => {
+		const { handlers, sent } = harness(native);
+		const sessionStart = handlers.get("session_start");
+		const agentEnd = handlers.get("agent_end");
+		const session = ctx("session-baseline-rdd-off", true, cwd);
+
+		await sessionStart!({}, session);
+		assert.deepEqual(statusRequests, []);
+
+		mode = "on";
+		await agentEnd!(agentEndEvent, session);
+		assert.equal(sent.length, 1, "no baseline was recorded while RDD was off, so the first dirty candidate still reminds");
+	});
+});
+
+test("session_start whose targetStatus rejects records no baseline, so agent_end still reminds once", async () => {
+	const targetIdentity = `sha256:${"6".repeat(64)}`;
+	let shouldThrow = true;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => {
+			if (shouldThrow) throw new Error("native status unavailable at session start");
+			return executeStartStatus(targetIdentity);
+		},
+	} as unknown as NativeReviewCli;
+	await withSessionStartEnv(async (cwd) => {
+		const { handlers, sent } = harness(native);
+		const sessionStart = handlers.get("session_start");
+		const agentEnd = handlers.get("agent_end");
+		const session = ctx("session-baseline-throws", true, cwd);
+
+		await assert.doesNotReject(async () => sessionStart!({}, session));
+
+		shouldThrow = false;
+		await agentEnd!(agentEndEvent, session);
+		assert.equal(sent.length, 1, "STATUS threw at session_start, so no baseline was recorded and the candidate still reminds");
+	});
+});
+
+test("session_shutdown clears the recorded baseline so the same identity reminds again", async () => {
+	const targetIdentity = `sha256:${"7".repeat(64)}`;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => executeStartStatus(targetIdentity),
+	} as unknown as NativeReviewCli;
+	await withSessionStartEnv(async (cwd) => {
+		const { handlers, sent } = harness(native);
+		const sessionStart = handlers.get("session_start");
+		const agentEnd = handlers.get("agent_end");
+		const shutdown = handlers.get("session_shutdown");
+		const session = ctx("session-baseline-shutdown", true, cwd);
+
+		await sessionStart!({}, session);
+		await agentEnd!(agentEndEvent, session);
+		assert.deepEqual(sent, [], "the baseline candidate is skipped");
+
+		await shutdown!({}, session);
+		await agentEnd!(agentEndEvent, session);
+		assert.equal(sent.length, 1, "shutdown cleared the baseline, so the same identity reminds again in the next session");
+	});
+});

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

@@ -0,0 +1,139 @@
+import assert from "node:assert/strict";
+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 { pathToFileURL } from "node:url";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import type { NativeReviewCli } from "../lib/native-review-cli.ts";
+
+// gentle-pi#560 / gentle-ai#4056, #4057: since 2026-08-01 Gentle AI stopped
+// writing a runtime-specific review execution contract into Pi's generated
+// APPEND_SYSTEM composition. This package now injects the mirrored provider
+// contract bundle's own `orchestration/pi.md` text at session start instead.
+// 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 BeforeAgentStartHandler = (event: unknown, ctx: ExtensionContext) => Promise<BeforeAgentStartResult>;
+
+const REPO_ROOT = join(import.meta.dirname, "..");
+const MIRROR_LOCK_PATH = join(REPO_ROOT, "contracts", "review-provider-contract-mirror", "provider-contract.lock.json");
+
+function mirroredPiOrchestrationText(): string {
+	const lock = JSON.parse(readFileSync(MIRROR_LOCK_PATH, "utf8")) as { contract_semver: string };
+	return readFileSync(
+		join(REPO_ROOT, "contracts", "review-provider-contract-mirror", `v${lock.contract_semver}`, "bundle", "orchestration", "pi.md"),
+		"utf8",
+	).trim();
+}
+
+function harness(nativeReviewCli: NativeReviewCli | null): { beforeAgentStart: BeforeAgentStartHandler } {
+	const handlers = new Map<string, BeforeAgentStartHandler>();
+	const pi = {
+		on(name: string, handler: BeforeAgentStartHandler) {
+			handlers.set(name, handler);
+		},
+		events: { emit() {} },
+		registerCommand() {},
+		registerTool() {},
+	} as unknown as ExtensionAPI;
+	createGentleAiExtension({ nativeReviewCli })(pi);
+	const beforeAgentStart = handlers.get("before_agent_start");
+	assert.equal(typeof beforeAgentStart, "function");
+	return { beforeAgentStart: beforeAgentStart as BeforeAgentStartHandler };
+}
+
+function ctx(overrides: Record<string, unknown> = {}): ExtensionContext {
+	return {
+		cwd: process.cwd(),
+		hasUI: true,
+		ui: { notify() {} },
+		sessionManager: { getSessionId: () => "review-contract-prompt-session" },
+		...overrides,
+	} as unknown as ExtensionContext;
+}
+
+const primaryEvent = { systemPrompt: "base" };
+
+test("before_agent_start injects the mirrored review execution contract for the primary session", async () => {
+	const { beforeAgentStart } = harness({} as NativeReviewCli);
+	const result = await beforeAgentStart(primaryEvent, ctx());
+	const expected = mirroredPiOrchestrationText();
+	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 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");
+	for (const marker of [
+		'call `gentle_review` with {"operation":"inspect"}',
+		"2. **Freeze once.**",
+		"call `gentle_review` with operation `status`",
+		"Use `gentle_review_capture` for one current returned slot",
+		"5. **Acknowledge exactly.**",
+	]) {
+		const markerIndex = result.systemPrompt.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/);
+});
+
+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/);
+});
+
+test("before_agent_start does not inject the review execution contract for an SDD executor session", async () => {
+	const { beforeAgentStart } = harness({} as NativeReviewCli);
+	const result = await beforeAgentStart({ systemPrompt: "SDD apply executor body" }, ctx());
+	assert.doesNotMatch(result.systemPrompt, /Gentle AI review execution contract/);
+});
+
+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/);
+});
+
+// gentle-ai R1/R3: a tampered mirrored orchestration/pi.md must never be spliced into the system prompt.
+function tempMirror(text: string, entrySha256: string): string {
+	const root = mkdtempSync(join(tmpdir(), "gentle-pi-mirror-"));
+	const bundleDir = join(root, "v9.9.9", "bundle", "orchestration");
+	mkdirSync(bundleDir, { recursive: true });
+	writeFileSync(join(bundleDir, "pi.md"), text, "utf8");
+	const lock = JSON.stringify({ contract_semver: "9.9.9", entries: { "orchestration/pi.md": entrySha256 } });
+	writeFileSync(join(root, "provider-contract.lock.json"), lock, "utf8");
+	return root;
+}
+
+test("rejects a tampered mirror, accepts a matching one, and warns once", async () => {
+	const tampered = tempMirror("tampered contract text", "0".repeat(64));
+	const matchingText = "matching contract text";
+	const matching = tempMirror(matchingText, createHash("sha256").update(Buffer.from(matchingText, "utf8")).digest("hex"));
+	try {
+		// Cache-bust: isolate this module's fragment cache from the real-mirror tests above.
+		const cacheBustedUrl = `${pathToFileURL(join(import.meta.dirname, "..", "extensions", "gentle-ai.ts")).href}?tamper=${Math.random()}`;
+		type Testing = {
+			readMirroredReviewContractFragment: (mirrorRoot?: string) => string | null;
+			loadReviewContractPromptFragment: (ctx: ExtensionContext, mirrorRoot?: string) => string | null;
+		};
+		const fresh = (await import(cacheBustedUrl)) as { __testing: Testing };
+		assert.equal(fresh.__testing.readMirroredReviewContractFragment(tampered), null);
+		assert.ok(fresh.__testing.readMirroredReviewContractFragment(matching)?.includes(matchingText));
+		let notifyCount = 0;
+		const spyCtx = { hasUI: true, ui: { notify: () => { notifyCount += 1; } } } as unknown as ExtensionContext;
+		fresh.__testing.loadReviewContractPromptFragment(spyCtx, tampered);
+		fresh.__testing.loadReviewContractPromptFragment(spyCtx, tampered);
+		assert.equal(notifyCount, 1);
+	} finally {
+		rmSync(tampered, { recursive: true, force: true });
+		rmSync(matching, { recursive: true, force: true });
+	}
+});

package/tests/review-controller.test.ts

@@ -421,7 +421,7 @@ test("shipped controller fails closed while static prompts defer RDD lifecycle o
 	assert.match(toolContract, /ambiguous START output.*target-scoped native status.*declared action.*ambiguous gentle_review_capture.*never replays/is);
 	assert.doesNotMatch(toolContract, /START throws.*lineage does not exist/is);
 
-	const boundary = "Gentle AI dynamically supplies runtime-specific RDD instructions via generated Pi APPEND_SYSTEM composition. Follow only those exact native instructions; if absent or unsupported, this package does not invent or fall back.";
+	const boundary = "This package injects the mirrored provider-bundle review execution contract into this session's system prompt at start; Gentle AI writes nothing into the Pi system prompt, and this package owns everything else here. Absent that mirrored contract, this package invents no lifecycle instructions.";
 	const core = readFileSync("assets/orchestrator.md", "utf8");
 	assert.match(core, new RegExp(boundary.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));