gentle-pi 2.3.0 → 2.5.0

package/tests/review-host-relay.test.ts

@@ -18,7 +18,12 @@ import {
 	resolveReviewHostRelayPiTimeoutMs,
 	resolveReviewHostRelaySubmission,
 	reviewHostRelaySlots,
+	prepareReviewHostRelaySlot,
+	runReviewHostRelayReviewerGroup,
 	runReviewHostRelaySlot,
+	submitReviewHostRelayPreparedResult,
+	type ReviewHostRelayPreparedResult,
+	type ReviewHostRelayRequest,
 } from "../lib/review-host-relay.ts";
 import { GENTLE_PI_REVIEW_RELAY_CONTRACT, GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV } from "../lib/review-relay-contract.ts";
 import { decodeReviewNextTransitionV3, type ReviewCaptureSubmissionV1, type ReviewCollectInputV3 } from "../lib/review-integration-v2.ts";
@@ -47,6 +52,8 @@ const inputToken = argv.find((token) => token === "--input" || token.startsWith(
 if (inputToken !== undefined) {
 	const mode = process.env.RELAY_FAKE_SUBMIT_MODE || "ok";
 	const inputPath = inputToken.startsWith("--input=") ? inputToken.slice("--input=".length) : argv[argv.indexOf("--input") + 1];
+	const submitDelayMs = Number(process.env.RELAY_FAKE_SUBMIT_DELAY_MS || "0");
+	if (Number.isSafeInteger(submitDelayMs) && submitDelayMs > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, submitDelayMs);
 	if (mode === "ok" || mode === "cleanup-fail") {
 		const bytes = fs.readFileSync(inputPath);
 		if (process.env.RELAY_FAKE_SUBMIT_CAPTURE) fs.writeFileSync(process.env.RELAY_FAKE_SUBMIT_CAPTURE, bytes);
@@ -95,13 +102,32 @@ process.stdin.on("data", (chunk) => chunks.push(chunk));
 process.stdin.on("end", () => {
 	const stdin = Buffer.concat(chunks);
 	if (process.env.RELAY_FAKE_PI_STDIN_CAPTURE) fs.writeFileSync(process.env.RELAY_FAKE_PI_STDIN_CAPTURE, stdin);
-	const mode = process.env.RELAY_FAKE_PI_MODE || "ok";
-	if (process.env.RELAY_FAKE_PI_BREAK_CLEANUP === "true") fs.chmodSync(path.dirname(process.cwd()), 0o500);
-	if (mode === "ok") { process.stdout.write(Buffer.from(process.env.RELAY_FAKE_PI_OUTPUT_B64 || "", "base64")); process.exit(0); }
-	if (mode === "empty") process.exit(0);
-	if (mode === "hang") { setTimeout(() => process.exit(0), 10_000); return; }
-	process.stderr.write("pi exploded\\n");
-	process.exit(4);
+	const finish = () => {
+		const mode = process.env.RELAY_FAKE_PI_MODE || "ok";
+		if (process.env.RELAY_FAKE_PI_BREAK_CLEANUP === "true") fs.chmodSync(path.dirname(process.cwd()), 0o500);
+		if (mode === "ok") { process.stdout.write(Buffer.from(process.env.RELAY_FAKE_PI_OUTPUT_B64 || "", "base64")); process.exit(0); }
+		if (mode === "empty") process.exit(0);
+		if (mode === "hang") { setTimeout(() => process.exit(0), 10_000); return; }
+		process.stderr.write("pi exploded\\n");
+		process.exit(4);
+	};
+	const barrierDirectory = process.env.RELAY_FAKE_PI_BARRIER_DIR;
+	if (barrierDirectory === undefined) { finish(); return; }
+	fs.mkdirSync(barrierDirectory, { recursive: true });
+	fs.writeFileSync(path.join(barrierDirectory, String(process.pid)), "started");
+	const expected = Number(process.env.RELAY_FAKE_PI_BARRIER_COUNT || "4");
+	const deadline = Date.now() + 1_000;
+	const releaseFile = process.env.RELAY_FAKE_PI_RELEASE_FILE;
+	const waitForGroup = () => {
+		if (fs.readdirSync(barrierDirectory).length < expected) {
+			if (Date.now() >= deadline) { process.stderr.write("reviewer barrier timed out\\n"); process.exit(5); return; }
+			setTimeout(waitForGroup, 10);
+			return;
+		}
+		if (releaseFile !== undefined && !fs.existsSync(releaseFile)) { setTimeout(waitForGroup, 10); return; }
+		finish();
+	};
+	waitForGroup();
 });
 `;
 
@@ -151,6 +177,14 @@ function readLog(path: string): Array<{ argv: string[]; contract: string | null;
 	return readFileSync(path, "utf8").split("\n").filter((line) => line.length > 0).map((line) => JSON.parse(line));
 }
 
+async function waitFor(condition: () => boolean, message: string): Promise<void> {
+	for (let attempt = 0; attempt < 100; attempt += 1) {
+		if (condition()) return;
+		await new Promise<void>((resolve) => setTimeout(resolve, 10));
+	}
+	throw new Error(message);
+}
+
 const BINDING_TOKENS = Object.freeze([
 	"--lineage=review-1d5aadacc600e167",
 	`--expected-revision=sha256:${"c".repeat(64)}`,
@@ -161,6 +195,7 @@ const BINDING_TOKENS = Object.freeze([
 	`--subject-hash=sha256:${"a".repeat(64)}`,
 ]);
 const CAPTURE_TOKENS = Object.freeze([...BINDING_TOKENS, "--agent=pi", "--materialize=true"]);
+const REVIEWER_GROUP_LENSES = ["review-risk", "review-resilience", "review-readability", "review-reliability"] as const;
 
 // The provider-owned completing form: exact operation and argument tokens
 // with one declared {{value}} substitution slot for the artifact path.
@@ -200,6 +235,20 @@ function relayRequest(fixture: RelayHarness, overrides: Record<string, unknown>
 	};
 }
 
+function reviewerGroupRequests(fixture: RelayHarness): ReviewHostRelayRequest[] {
+	return REVIEWER_GROUP_LENSES.map((lens, order) => relayRequest(fixture, {
+		captureArgumentTokens: CAPTURE_TOKENS.map((token) => token === "--lens=review-reliability"
+			? `--lens=${lens}`
+			: token === "--order=0" ? `--order=${order}` : token),
+		environment: {
+			...fixture.environment,
+			RELAY_FAKE_PROMPT_B64: PROMPT_BYTES.toString("base64"),
+			RELAY_FAKE_PI_OUTPUT_B64: PI_OUTPUT_BYTES.toString("base64"),
+		},
+	}));
+}
+
+
 async function rejectsWithRelayError(promise: Promise<unknown>, kind: string, stage: string): Promise<ReviewHostRelayError> {
 	let caught: ReviewHostRelayError | undefined;
 	await assert.rejects(promise, (error: unknown) => {
@@ -305,6 +354,145 @@ test("the pi lockdown argv is pinned exactly with no model or provider selection
 	assert.equal(piCalls[0]!.argv.some((token) => token.startsWith("--model") || token.startsWith("--provider") || token.startsWith("--profile")), false);
 });
 
+test("preparation snapshots mutable submission tokens and values before materialization", async (t) => {
+	const fixture = harness(t);
+	const barrierDirectory = join(fixture.directory, "submission-snapshot-barrier");
+	const releaseFile = join(fixture.directory, "submission-snapshot-release");
+	const submissionTokens = [...SUBMISSION.argumentTokens];
+	const submissionValues = SUBMISSION.values.map((value) => ({ ...value }));
+	const submission: ReviewCaptureSubmissionV1 = { ...SUBMISSION, argumentTokens: submissionTokens, values: submissionValues };
+	const prepared = prepareReviewHostRelaySlot(relayRequest(fixture, {
+		submission,
+		environment: {
+			...fixture.environment,
+			RELAY_FAKE_PROMPT_B64: PROMPT_BYTES.toString("base64"),
+			RELAY_FAKE_PI_OUTPUT_B64: PI_OUTPUT_BYTES.toString("base64"),
+			RELAY_FAKE_PI_BARRIER_DIR: barrierDirectory,
+			RELAY_FAKE_PI_BARRIER_COUNT: "1",
+			RELAY_FAKE_PI_RELEASE_FILE: releaseFile,
+		},
+	}));
+	await waitFor(() => readLog(fixture.piLogPath).length === 1, "reviewer did not reach the snapshot barrier");
+	submissionTokens[submissionTokens.length - 1] = "--input=mutated";
+	submissionValues[0]!.slot = "mutated";
+	writeFileSync(releaseFile, "release");
+
+	const result = await prepared;
+	assert.deepEqual(result.request.submission, SUBMISSION);
+	await submitReviewHostRelayPreparedResult(result);
+	assert.deepEqual(readFileSync(fixture.submitCapturePath), PI_OUTPUT_BYTES);
+});
+
+test("preparation keeps reviewer bytes private through deferred submission", async (t) => {
+	const fixture = harness(t);
+	const reviewerBytes = Buffer.from(PI_OUTPUT_BYTES);
+	const prepared = await prepareReviewHostRelaySlot(relayRequest(fixture), async () => ({
+		stdout: reviewerBytes,
+		promptByteLength: PROMPT_BYTES.length,
+		stdoutByteLength: reviewerBytes.length,
+	}));
+	reviewerBytes.fill(0);
+	const mutablePrepared = prepared as unknown as { resultBytes?: Buffer };
+	mutablePrepared.resultBytes?.fill(0);
+	assert.throws(() => { mutablePrepared.resultBytes = Buffer.from("fabricated"); }, TypeError);
+	await submitReviewHostRelayPreparedResult(prepared);
+	assert.deepEqual(readFileSync(fixture.submitCapturePath), PI_OUTPUT_BYTES);
+
+	const fabricated = { ...prepared, resultBytes: Buffer.from("fabricated") } as unknown as ReviewHostRelayPreparedResult;
+	await assert.rejects(submitReviewHostRelayPreparedResult(fabricated), /recognized prepared result/);
+	assert.equal(readLog(fixture.logPath).length, 2, "unrecognized results must not launch provider submission");
+});
+
+test("the supplied AbortSignal stays live through deferred submission", async (t) => {
+	const fixture = harness(t, { RELAY_FAKE_SUBMIT_DELAY_MS: "1000" });
+	const controller = new AbortController();
+	const prepared = await prepareReviewHostRelaySlot(relayRequest(fixture, { signal: controller.signal }));
+	const submission = submitReviewHostRelayPreparedResult(prepared);
+	await waitFor(() => readLog(fixture.logPath).length === 2, "submission did not start");
+	controller.abort();
+	await rejectsWithRelayError(submission, REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit");
+});
+
+test("four reviewers cross a shared barrier before any result submission can begin", async (t) => {
+	const fixture = harness(t);
+	const barrierDirectory = join(fixture.directory, "reviewer-barrier");
+	const requests = reviewerGroupRequests(fixture).map((request) => ({
+		...request,
+		environment: {
+			...request.environment,
+			RELAY_FAKE_PI_BARRIER_DIR: barrierDirectory,
+			RELAY_FAKE_PI_BARRIER_COUNT: String(REVIEWER_GROUP_LENSES.length),
+		},
+	}));
+
+	const prepared = await runReviewHostRelayReviewerGroup(requests);
+
+	assert.equal(prepared.length, REVIEWER_GROUP_LENSES.length);
+	assert.ok(prepared.every((result) => result.resultByteLength === PI_OUTPUT_BYTES.length));
+	assert.equal(readLog(fixture.piLogPath).length, REVIEWER_GROUP_LENSES.length);
+	assert.equal(readLog(fixture.logPath).length, REVIEWER_GROUP_LENSES.length, "preparation materializes only; it does not submit");
+});
+
+test("four reviewer results retain provider order when their preparation resolves in reverse", async (t) => {
+	const requests = reviewerGroupRequests(harness(t));
+	const started: number[] = [];
+	const complete: Array<() => void> = [];
+	const group = runReviewHostRelayReviewerGroup(requests, (request) => new Promise<ReviewHostRelayPreparedResult>((resolve) => {
+		const index = requests.indexOf(request);
+		assert.notEqual(index, -1);
+		started.push(index);
+		complete.push(() => resolve({
+			request,
+			promptByteLength: index + 1,
+			resultByteLength: index + 1,
+		}));
+	}));
+
+	assert.deepEqual(started, [0, 1, 2, 3], "every reviewer starts before the group waits");
+	for (const finish of [...complete].reverse()) finish();
+	const prepared = await group;
+
+	assert.deepEqual(prepared.map((result) => result.resultByteLength), [1, 2, 3, 4]);
+});
+
+test("partial reviewer failures wait for a later pending transport and report the first provider-ordered error", async (t) => {
+	const requests = reviewerGroupRequests(harness(t));
+	const started: number[] = [];
+	let groupSettled = false;
+	let releaseLaterReviewer: (() => void) | undefined, rejectFirstProvider: ((reason?: unknown) => void) | undefined;
+	const firstProviderError = new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_FAILED, "pi", "first provider error");
+
+	const group = runReviewHostRelayReviewerGroup(requests, (request) => {
+		const index = requests.indexOf(request);
+		assert.notEqual(index, -1);
+		started.push(index);
+		if (index === 1) return new Promise<ReviewHostRelayPreparedResult>((_resolve, reject) => { rejectFirstProvider = reject; });
+		if (index === 2) return Promise.reject(new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_FAILED, "pi", "later provider error"));
+		if (index === 3) {
+			return new Promise<ReviewHostRelayPreparedResult>((resolve) => {
+				releaseLaterReviewer = () => resolve({
+					request,
+					promptByteLength: index + 1,
+					resultByteLength: index + 1,
+				});
+			});
+		}
+		return Promise.resolve({
+			request,
+			promptByteLength: index + 1,
+			resultByteLength: index + 1,
+		});
+	});
+	void group.then(() => { groupSettled = true; }, () => { groupSettled = true; });
+
+	await new Promise<void>((resolve) => setImmediate(resolve));
+	assert.deepEqual(started, [0, 1, 2, 3], "one failed reviewer does not prevent later reviewers from starting");
+	rejectFirstProvider!(firstProviderError); await new Promise<void>((resolve) => setImmediate(resolve));
+	assert.equal(groupSettled, false, "the group must remain pending until the later reviewer settles");
+	releaseLaterReviewer!();
+	await assert.rejects(group, (error: unknown) => error === firstProviderError);
+});
+
 // ---------------------------------------------------------------------------
 // Fail-closed legs — a typed transport error and NO submission.
 // ---------------------------------------------------------------------------

package/tests/review-integration-v2-forward.test.ts

@@ -393,6 +393,53 @@ test("capabilities/v2.3 retains status/v5 while v2.4 requires status/v6", () =>
 	assert.throws(() => decodeReviewCapabilitiesV2(v22Retired, CAPTURED_DIGEST), /schema/);
 });
 
+test("capabilities/v2.5 negotiates the v2.6.0 advertisement and status/v7 decodes the eligible untracked inventory", () => {
+	// gentle-ai v2.6.0 advertises capabilities/v2.5: the v2.4 surface plus
+	// status/v7, with status/v6 still advertised for compatibility.
+	const v25 = clone(fixture(DEV_FIXTURES, "capabilities-v2.2.captured.json") as JsonObject);
+	v25.schema = "gentle-ai.review-integration.capabilities/v2.5";
+	(v25.protocol as JsonObject).minor = 5;
+	const features = v25.features as JsonObject;
+	features.mandatory = (features.mandatory as JsonObject[]).filter((feature) =>
+		!["exact_receipt_replay", "five_delivery_gates", "sdd_receipt_binding"].includes(feature.name as string));
+	v25.schemas = [
+		...(v25.schemas as string[]).map((schema) => schema
+			.replace("capabilities/v2.2", "capabilities/v2.5")
+			.replace("start/v3", "start/v4")
+			.replace("status/v5", "status/v6")),
+		"gentle-ai.review-intended-untracked-selection/v1",
+		"gentle-ai.review-integration.status/v7",
+	];
+	const decoded = decodeReviewCapabilitiesV2(v25, CAPTURED_DIGEST);
+	assert.equal(decoded.schemas.has("gentle-ai.review-integration.status/v6"), true);
+	// The negotiated set is the v2.5 requirement floor; status/v7 is additive
+	// and never required, so an advertisement without it still negotiates.
+	assert.equal(decoded.schemas.has("gentle-ai.review-integration.status/v7"), false);
+	const withoutStatusV7 = clone(v25);
+	withoutStatusV7.schemas = (withoutStatusV7.schemas as string[]).filter((schema) => schema !== "gentle-ai.review-integration.status/v7");
+	assert.equal(decodeReviewCapabilitiesV2(withoutStatusV7, CAPTURED_DIGEST).schemas.has("gentle-ai.review-integration.status/v6"), true);
+
+	// status/v6 stays required: v7 is an additive extension, not a replacement.
+	const missingStatusV6 = clone(v25);
+	missingStatusV6.schemas = (missingStatusV6.schemas as string[]).filter((schema) => schema !== "gentle-ai.review-integration.status/v6");
+	assert.throws(() => decodeReviewCapabilitiesV2(missingStatusV6, CAPTURED_DIGEST), /status\/v6/);
+
+	// status/v7 adds only the optional top-level eligible untracked inventory digest.
+	const v7 = initialIntendedUntrackedStatusV6();
+	v7.schema = "gentle-ai.review-integration.status/v7";
+	v7.eligible_untracked_inventory = sha("e");
+	assert.equal(decodeReviewStatusV3(v7).eligibleUntrackedInventory, sha("e"));
+
+	const v7Staged = initialIntendedUntrackedStatusV6();
+	v7Staged.schema = "gentle-ai.review-integration.status/v7";
+	assert.equal(decodeReviewStatusV3(v7Staged).eligibleUntrackedInventory, undefined);
+
+	// The digest is v7-only: a v6 envelope carrying it is still rejected.
+	const v6WithDigest = initialIntendedUntrackedStatusV6();
+	v6WithDigest.eligible_untracked_inventory = sha("e");
+	assert.throws(() => decodeReviewStatusV3(v6WithDigest), /eligible_untracked_inventory/);
+});
+
 test("status/v6 decodes and enforces the intended-untracked selection submission", () => {
 	const decoded = decodeReviewStatusV3(initialIntendedUntrackedStatusV6());
 	const input = decoded.nextTransition?.collect?.inputs[0];

package/tests/review-integration-v2.test.ts

@@ -184,6 +184,44 @@ test("failure enforces exact keys, enums, and identifiers", () => {
 	assert.throws(() => decodeReviewFailureV2(badCode), /code/);
 });
 
+test("failure with code managed_assets_outdated decodes its continuation, degrades without one, and forbids it elsewhere", () => {
+	const source: JsonObject = {
+		schema: "gentle-ai.review-integration.failure/v2",
+		contract: REVIEW_INTEGRATION_CONTRACT,
+		operation: "review.start",
+		phase: "preflight",
+		code: "managed_assets_outdated",
+		message: "the managed asset set is stale",
+		mutation_outcome: "not_started",
+		authority_applicability: "current_target",
+		retry_safe: true,
+		replayability: "manual_action_required",
+		required_inputs: [],
+		next_action: "explicit-maintainer-action",
+		continuation: { operation: "sync", command: "gentle-ai sync --agent claude-code", agent: "claude-code", stale_assets: ["orchestration/claude-code.md"] },
+	};
+	assert.deepEqual(decodeReviewFailureV2(source).continuation, { operation: "sync", command: "gentle-ai sync --agent claude-code", agent: "claude-code", staleAssets: ["orchestration/claude-code.md"] });
+
+	const missingCommand = clone(source);
+	delete (missingCommand.continuation as JsonObject).command;
+	assert.throws(() => decodeReviewFailureV2(missingCommand), /command.*required|required.*command/);
+
+	// an older gentle-ai may emit managed_assets_outdated with no continuation
+	// at all; decode must not refuse the whole envelope for that
+	const missingContinuation = clone(source);
+	delete missingContinuation.continuation;
+	assert.equal(decodeReviewFailureV2(missingContinuation).continuation, undefined);
+
+	const unexpectedContinuation: JsonObject = { ...clone(source), code: "gate_scope_changed" };
+	assert.throws(() => decodeReviewFailureV2(unexpectedContinuation), /continuation is only valid/);
+
+	// an envelope without continuation, on a code that does not require one, is unchanged
+	const withoutContinuation = clone(source);
+	withoutContinuation.code = "gate_scope_changed";
+	delete withoutContinuation.continuation;
+	assert.equal(decodeReviewFailureV2(withoutContinuation).continuation, undefined);
+});
+
 test("net-new decoders: consent, next-transition, and artifact-subject reject malformed payloads", () => {
 	const consentSource = fixture<JsonObject>("consent.fixture.json");
 	assertRequired(decodeReviewConsentV2, consentSource, ["schema", "contract", "operation", "action", "blocking", "target_identity", "projection", "risk_level", "changed_files", "changed_lines", "headline", "reason", "value", "risk_evidence", "choices", "off_path"]);
@@ -405,6 +443,41 @@ test("next_transition decodes an execute variant and rejects a stop that carries
 	assert.throws(() => decodeReviewNextTransitionV3(stopWithExecute), /stop cannot carry/);
 });
 
+// gentle-pi#627: gentle-ai reports a stale managed-asset set as a typed stop
+// carrying the exact `gentle-ai sync` invocation that resolves it.
+function managedAssetsContinuation(overrides: Partial<JsonObject> = {}): JsonObject {
+	return { operation: "sync", command: "gentle-ai sync --agent claude-code", agent: "claude-code", stale_assets: ["orchestration/claude-code.md"], ...overrides };
+}
+
+test("next_transition stop decodes a managed_assets_outdated continuation and rejects a malformed one", () => {
+	const stop: JsonObject = { kind: "stop", reason_code: "managed_assets_outdated", continuation: managedAssetsContinuation() };
+	const decoded = decodeReviewNextTransitionV3(stop);
+	assert.deepEqual(decoded.continuation, { operation: "sync", command: "gentle-ai sync --agent claude-code", agent: "claude-code", staleAssets: ["orchestration/claude-code.md"] });
+
+	const bare: JsonObject = { kind: "stop", reason_code: "managed_assets_outdated", continuation: { operation: "sync", command: "gentle-ai sync" } };
+	assert.deepEqual(decodeReviewNextTransitionV3(bare).continuation, { operation: "sync", command: "gentle-ai sync" });
+
+	const missingCommand = clone(stop);
+	delete (missingCommand.continuation as JsonObject).command;
+	assert.throws(() => decodeReviewNextTransitionV3(missingCommand), /command.*required|required.*command/);
+
+	const emptyCommand = clone(stop);
+	(emptyCommand.continuation as JsonObject).command = "";
+	assert.throws(() => decodeReviewNextTransitionV3(emptyCommand), /command/);
+
+	// an older gentle-ai may emit this stop with no continuation at all; decode
+	// must not refuse the whole envelope for that
+	const missingForReasonCode = { kind: "stop", reason_code: "managed_assets_outdated" };
+	assert.equal(decodeReviewNextTransitionV3(missingForReasonCode).continuation, undefined);
+
+	const unexpectedOnOtherReasonCode = { kind: "stop", reason_code: "rdd_disabled", continuation: managedAssetsContinuation() };
+	assert.throws(() => decodeReviewNextTransitionV3(unexpectedOnOtherReasonCode), /continuation is only valid/);
+
+	// envelopes without continuation stay unchanged
+	const plainStop = decodeReviewNextTransitionV3({ kind: "stop", reason_code: "rdd_disabled" });
+	assert.equal(plainStop.continuation, undefined);
+});
+
 function approvedAcknowledgementTransition(): JsonObject {
 	return {
 		kind: "execute",
@@ -700,6 +773,40 @@ test("v5 targeted-validator collect inputs carry the exact provider-owned valida
 	assert.throws(() => decodeReviewNextTransitionV3(weakenedRequest, { v5: true }), /policy_content/);
 });
 
+test("status.frozen carries the optional frozen manifest digest", () => {
+	const current = devFixture<JsonObject>("status-v5-repository-context.captured.json");
+	delete current.receipt;
+	if (current.action === "finalize") {
+		current.action = "stop";
+		delete current.next_transition;
+		delete current.forecast;
+	}
+	assert.equal(typeof (current.frozen as JsonObject | undefined)?.tier, "string", "the captured status carries frozen");
+	const digest = `sha256:${"ab".repeat(32)}`;
+	(current.frozen as JsonObject).changed_path_manifest_sha256 = digest;
+	assert.equal(decodeReviewStatusV3(current).frozen?.changedPathManifestSha256, digest);
+	(current.frozen as JsonObject).changed_path_manifest_sha256 = "not-a-digest";
+	assert.throws(() => decodeReviewStatusV3(current), /changed_path_manifest_sha256/);
+	delete (current.frozen as JsonObject).changed_path_manifest_sha256;
+	assert.equal(decodeReviewStatusV3(current).frozen?.changedPathManifestSha256, undefined);
+});
+
+test("a capture-result collect input decodes without changed_path_manifest, which the artifact subject digest already binds", () => {
+	const status = fixture<JsonObject>("status.fixture.json");
+	const transition = clone((status.next_transition ?? {}) as JsonObject);
+	const inputs = ((transition.collect as JsonObject | undefined)?.inputs ?? []) as JsonObject[];
+	const captureInput = inputs.find((input) => input.capture_operation === "review.capture-result");
+	assert.ok(captureInput, "the status fixture carries a capture-result collect input");
+	assert.doesNotThrow(() => decodeReviewNextTransitionV3(transition, { v5: true, v6: true }), "with the manifest");
+	delete captureInput.changed_path_manifest;
+	const decoded = decodeReviewNextTransitionV3(transition, { v5: true, v6: true });
+	const decodedInput = decoded.collect?.inputs.find((input) => input.captureOperation === "review.capture-result");
+	assert.ok(decodedInput?.artifactSubject?.changedPathManifestSha256, "the digest on the artifact subject is the binding");
+	assert.equal(decodedInput?.changedPathManifest, undefined);
+	delete captureInput.artifact_subject;
+	assert.throws(() => decodeReviewNextTransitionV3(transition, { v5: true, v6: true }), /requires artifact_subject, base_tree, and candidate_tree/);
+});
+
 test("status enforces authority/frozen/receipt conditionals and decodes the required repair field", () => {
 	const current = devFixture<JsonObject>("status-v5-repository-context.captured.json");
 	delete current.receipt;
@@ -711,6 +818,11 @@ test("status enforces authority/frozen/receipt conditionals and decodes the requ
 	const decoded = decodeReviewStatusV3(current);
 	assert.equal(decoded.repair.status, "unsupported");
 	assert.equal(decoded.authority?.state, "reviewing");
+	for (const action of ["collect", "execute"]) {
+		const projected = clone(current);
+		projected.action = action;
+		assert.equal(decodeReviewStatusV3(projected).action, action, "a live transaction's root action names its mandated transition kind");
+	}
 
 	const missingAuthority = clone(current);
 	delete missingAuthority.authority;

package/tests/review-last-event-closure.test.ts

@@ -331,7 +331,7 @@ test("terminal capture closes directly, nonterminal capture does not auto-follow
 	assert.equal(statusCalls, 2, "only initial STATUS plus one ambiguity reconciliation");
 });
 
-test("unknown-capture reconciliation validates the target-scoped lineage without replay", async () => {
+test("unknown-capture reconciliation preserves agentless legacy callers and forwards an explicit Pi agent", async () => {
 	const calls: Array<Record<string, unknown>> = [];
 	const native = {
 		targetStatus: async (request: Record<string, unknown>) => {
@@ -342,7 +342,12 @@ test("unknown-capture reconciliation validates the target-scoped lineage without
 	} as unknown as NativeReviewCli;
 	const result = await reconcileUnknownReviewLastEventCapture(native, "/repo", { lineageId: "reconcile-lineage", targetIdentity: SHA });
 	await reconcileUnknownReviewLastEventCapture(native, "/repo", { lineageId: "reconcile-lineage", targetIdentity: SHA }, { baseRef: "refs/heads/main", committedOnly: true });
-	assert.deepEqual(calls, [{ cwd: "/repo", lineageId: "reconcile-lineage" }, { cwd: "/repo", lineageId: "reconcile-lineage", baseRef: "refs/heads/main", committedOnly: true }]);
+	await reconcileUnknownReviewLastEventCapture(native, "/repo", { lineageId: "reconcile-lineage", targetIdentity: SHA }, { agent: "pi" });
+	assert.deepEqual(calls, [
+		{ cwd: "/repo", lineageId: "reconcile-lineage" },
+		{ cwd: "/repo", lineageId: "reconcile-lineage", baseRef: "refs/heads/main", committedOnly: true },
+		{ cwd: "/repo", lineageId: "reconcile-lineage", agent: "pi" },
+	]);
 	assert.equal(result.targetIdentity, SHA);
 	let launches = 0;
 	const strictNative = new nativeReviewCliModule.NativeReviewCliV216(async () => { launches += 1; throw new Error("must not launch"); }, "/package/.gentle-ai/gentle-ai");

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

@@ -311,7 +311,7 @@ test("Judgment Day skill and prompts preserve bounded fix and re-judgment author
 });
 
 test("orchestrator, injected skill, and README defer RDD lifecycle ownership to Gentle AI", () => {
-	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 orchestrator = union(ORCHESTRATOR);
 	assert.ok(orchestrator.includes(boundary), "orchestrator must carry the sole static ownership boundary");
 

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

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import { declareReviewRelayHandshake, GENTLE_PI_REVIEW_RELAY_CONTRACT, GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV } from "../lib/review-relay-contract.ts";
+
+// gentle-pi#550: the session shell must inherit the relay handshake, so a
+// `gentle-ai review ... --agent pi` typed in a shell tool is eligible without
+// the operator reading package source for the value.
+
+test("declareReviewRelayHandshake exports the exact contract and reports whether it changed anything", () => {
+	const env: NodeJS.ProcessEnv = {};
+	assert.equal(declareReviewRelayHandshake(env), true);
+	assert.equal(env[GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV], GENTLE_PI_REVIEW_RELAY_CONTRACT);
+	assert.equal(declareReviewRelayHandshake(env), false, "already declared");
+	const stale: NodeJS.ProcessEnv = { [GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV]: "gentle-pi.review-relay/v0" };
+	assert.equal(declareReviewRelayHandshake(stale), true, "a wrong value is replaced: this extension is the host");
+	assert.equal(stale[GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV], GENTLE_PI_REVIEW_RELAY_CONTRACT);
+});
+
+test("loading the extension declares the handshake in the session environment", () => {
+	const processEnv: NodeJS.ProcessEnv = { PATH: "/bin" };
+	createGentleAiExtension({ nativeReviewCli: null, processEnv })({ on() {}, registerTool() {}, registerCommand() {} } as unknown as ExtensionAPI);
+	assert.equal(processEnv[GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV], GENTLE_PI_REVIEW_RELAY_CONTRACT);
+	assert.equal(processEnv.PATH, "/bin");
+});

package/tests/review-repository.test.ts

@@ -4,7 +4,7 @@ import { cpSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import test from "node:test";
-import { resolveRepositoryAuthorityV1, setReviewRepositoryIdentityRetryHookForTesting } from "../lib/review-repository.ts";
+import { resolveRepositoryAuthorityV1, reviewGitEnvironment, setReviewRepositoryIdentityRetryHookForTesting } from "../lib/review-repository.ts";
 import { REVIEW_MODE, ReviewTransactionStore, createReviewState, setReviewMutationLockPlatformForTesting } from "../lib/review-transaction.ts";
 import { REVIEW_LENS, REVIEW_ROUTE } from "../lib/review-triggers.ts";
 import { qualifiedReviewLockPlatform, testSnapshot } from "./review-test-fixtures.ts";
@@ -49,6 +49,33 @@ function addOrphanRoot(root: string, branch: string, file: string): void {
 	git(root, "checkout", "main");
 }
 
+test("review Git environment uses a Git-compatible null config path on Windows", () => {
+	const environment = reviewGitEnvironment();
+	assert.equal(environment.GIT_CONFIG_GLOBAL, "/dev/null");
+	assert.equal(environment.GIT_CONFIG_SYSTEM, "/dev/null");
+});
+
+test("review Git environment runs a real Git authority probe", (t) => {
+	const root = repository(t);
+	const commonDirectory = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+		cwd: root,
+		encoding: "utf8",
+		env: reviewGitEnvironment(),
+	}).trim();
+	assert.equal(resolve(commonDirectory), resolve(git(root, "rev-parse", "--path-format=absolute", "--git-common-dir")));
+});
+
+test("review Git environment rejects inherited unsafe Git overrides", () => {
+	const prior = process.env.GIT_DIR;
+	try {
+		process.env.GIT_DIR = "/unsafe";
+		assert.throws(() => reviewGitEnvironment(), /REVIEW_GIT_ENV_UNSAFE/);
+	} finally {
+		if (prior === undefined) delete process.env.GIT_DIR;
+		else process.env.GIT_DIR = prior;
+	}
+});
+
 test("a Windows drive-letter Git common directory resolves repository authority", { skip: process.platform !== "win32" }, (t) => {
 	const root = repository(t);
 	const commonDirectory = git(root, "rev-parse", "--path-format=absolute", "--git-common-dir");