gentle-pi 2.3.0 → 2.4.0

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

@@ -1,19 +1,20 @@
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import { __testing } from "../extensions/gentle-ai.ts";
 import type { NativeReviewCli } from "../lib/native-review-cli.ts";
 import { REVIEW_HOST_RELAY_FAILURE, REVIEW_HOST_RELAY_PI_TIMEOUT_ENV, REVIEW_HOST_RELAY_PI_TIMEOUT_MAX_MS, REVIEW_HOST_RELAY_SUBMISSION_MISSING_MESSAGE, REVIEW_HOST_RELAY_UNAVAILABLE_MESSAGE, ReviewHostRelayError, type ReviewHostRelayRequest } from "../lib/review-host-relay.ts";
-import type { ReviewCaptureSubmissionV1, ReviewCollectInputV3, ReviewStatusV3 } from "../lib/review-integration-v2.ts";
+import { decodeReviewStatusV3, type ReviewArtifactSubjectV2, type ReviewCaptureSubmissionV1, type ReviewCollectInputV3, type ReviewStatusV3 } from "../lib/review-integration-v2.ts";
 
 // One-slot capture routing: the host relay runs only when the selected
 // provider-returned collect input carries the --materialize token. Every
 // other capture form stays untouched.
 
 const SHA = `sha256:${"1".repeat(64)}`;
+const PHASE_REVISION = `sha256:${"3".repeat(64)}`;
 const TREE = "2".repeat(40);
 
 function repository(t: test.TestContext): string {
@@ -26,10 +27,10 @@ function repository(t: test.TestContext): string {
 	return cwd;
 }
 
-function bindingArguments(lineageId: string, lens: string, order: number): ReviewCollectInputV3["arguments"] {
+function bindingArguments(lineageId: string, lens: ReviewArtifactSubjectV2["lens"], order: number, revision = SHA): ReviewCollectInputV3["arguments"] {
 	return [
 		{ name: "lineage", value: lineageId, token: `--lineage=${lineageId}` },
-		{ name: "expected-revision", value: SHA, token: `--expected-revision=${SHA}` },
+		{ name: "expected-revision", value: revision, token: `--expected-revision=${revision}` },
 		{ name: "target", value: SHA, token: `--target=${SHA}` },
 		{ name: "repository-context", value: `rctx1_${"e".repeat(64)}`, token: `--repository-context=rctx1_${"e".repeat(64)}` },
 		{ name: "lens", value: lens, token: `--lens=${lens}` },
@@ -38,8 +39,8 @@ function bindingArguments(lineageId: string, lens: string, order: number): Revie
 	];
 }
 
-function providerSubmission(lineageId: string, lens: string, order: number): ReviewCaptureSubmissionV1 {
-	const bindingTokens = bindingArguments(lineageId, lens, order).map((argument) => argument.token!);
+function providerSubmission(lineageId: string, lens: ReviewArtifactSubjectV2["lens"], order: number, revision = SHA): ReviewCaptureSubmissionV1 {
+	const bindingTokens = bindingArguments(lineageId, lens, order, revision).map((argument) => argument.token!);
 	return {
 		operationToken: "capture-result",
 		argumentTokens: [...bindingTokens, "--input={{value}}"],
@@ -47,22 +48,71 @@ function providerSubmission(lineageId: string, lens: string, order: number): Rev
 	};
 }
 
-function relayCollectInput(lineageId: string, lens: string, order: number, materialize = true, submission: ReviewCaptureSubmissionV1 | "provider" | "absent" = "provider"): ReviewCollectInputV3 {
+function relayCollectInput(lineageId: string, lens: ReviewArtifactSubjectV2["lens"], order: number, materialize = true, submission: ReviewCaptureSubmissionV1 | "provider" | "absent" = "provider", revision = SHA): ReviewCollectInputV3 {
 	return {
 		name: "reviewer_result",
 		schema: "https://gentle-ai.dev/schema/review/reviewer/v1",
 		captureOperation: "review.capture-result",
 		arguments: [
-			...bindingArguments(lineageId, lens, order),
+			...bindingArguments(lineageId, lens, order, revision),
 			...(materialize ? [
 				{ name: "agent", value: "pi", token: "--agent=pi" },
 				{ name: "materialize", value: "true", token: "--materialize=true" },
 			] : []),
 		],
-		...(materialize && submission !== "absent" ? { submission: submission === "provider" ? providerSubmission(lineageId, lens, order) : submission } : {}),
+		artifactSubject: {
+			schema: "gentle-ai.review-artifact-subject/v2", subjectHash: `sha256:${String(order).repeat(64)}`,
+			lineageId, authorityRevision: revision, targetIdentity: SHA, baseTree: TREE, candidateTree: TREE,
+			changedPathManifestSha256: SHA, lens, selectedOrder: order,
+		},
+		baseTree: TREE, candidateTree: TREE, changedPathManifest: [],
+		...(materialize && submission !== "absent" ? { submission: submission === "provider" ? providerSubmission(lineageId, lens, order, revision) : submission } : {}),
 	};
 }
 
+function capturedGroupedStatus(lineageId: string, authorityRevision = SHA): ReviewStatusV3 {
+	const raw = JSON.parse(readFileSync(new URL("./fixtures/devbinary/status-v5-capture-result-submission.captured.json", import.meta.url), "utf8")) as Record<string, unknown>;
+	// The captured binary's forward-only `finalize` action is not accepted by
+	// this checked-out decoder; retain the v5 capture and normalize only that
+	// unrelated routing action before decoding its provider-owned group.
+	raw.action = "stop";
+	const authority = raw.authority as Record<string, unknown>, repositoryContext = raw.repository_context as Record<string, unknown>;
+	authority.lineage_id = lineageId;
+	authority.revision = authorityRevision;
+	const phaseRevision = String(repositoryContext.revision), targetIdentity = String(raw.target_identity);
+	const source = ((((raw.next_transition as Record<string, unknown>).collect as Record<string, unknown>).inputs as Array<Record<string, unknown>>)[0]!);
+	const lenses = ["review-risk", "review-resilience", "review-readability", "review-reliability"];
+	((raw.next_transition as Record<string, unknown>).collect as Record<string, unknown>).inputs = lenses.map((lens, order) => {
+		const input = JSON.parse(JSON.stringify(source)) as Record<string, unknown>;
+		const subjectHash = `sha256:${String(order + 1).repeat(64)}`;
+		const arguments_ = input.arguments as Array<Record<string, unknown>>;
+		for (const argument of arguments_) {
+			const value = argument.name === "lineage" ? lineageId
+				: argument.name === "lens" ? lens
+				: argument.name === "order" ? String(order)
+				: argument.name === "subject-hash" ? subjectHash
+				: argument.value;
+			argument.value = value;
+			argument.token = `--${String(argument.name)}=${String(value)}`;
+		}
+		const submission = input.submission as Record<string, unknown>;
+		submission.argument_tokens = [...arguments_.filter((argument) => argument.name !== "agent" && argument.name !== "materialize").map((argument) => argument.token), "--input={{value}}"];
+		const artifactSubject = input.artifact_subject as Record<string, unknown>;
+		artifactSubject.subject_hash = subjectHash;
+		artifactSubject.lineage_id = lineageId;
+		artifactSubject.authority_revision = phaseRevision;
+		artifactSubject.target_identity = targetIdentity;
+		artifactSubject.lens = lens;
+		artifactSubject.selected_order = order;
+		return input;
+	});
+	return decodeReviewStatusV3(raw);
+}
+
+function replaceArgument(input: ReviewCollectInputV3, name: string, value: string): void {
+	input.arguments = input.arguments.map((argument) => argument.name === name ? { ...argument, value, token: `--${name}=${value}` } : argument);
+}
+
 function finalizeStatus(lineageId: string, inputs?: readonly ReviewCollectInputV3[]): ReviewStatusV3 {
 	return {
 		contract: "gentle-ai.review-integration/v2",
@@ -86,6 +136,7 @@ function finalizeStatus(lineageId: string, inputs?: readonly ReviewCollectInputV
 			currentSnapshotIdentity: SHA,
 		},
 		candidates: [],
+		repositoryContext: { capability: "review.opaque_repository_context", handle: `rctx1_${"e".repeat(64)}`, revision: SHA, targetIdentity: SHA },
 		...(inputs === undefined ? {} : { nextTransition: { kind: "collect", reasonCode: "reviewer_results_required", collect: { inputs: [...inputs] } } }),
 		raw: { schema: "gentle-ai.review-integration.status/v3", action: "stop", lineage_id: lineageId },
 	} as unknown as ReviewStatusV3;
@@ -166,6 +217,157 @@ test("Pi-authored review documents are rejected at the capture input boundary",
 	assert.equal(relayCalls, 0);
 });
 
+function groupInputs(lineageId: string, revision = SHA): ReviewCollectInputV3[] { return ["review-risk", "review-resilience", "review-readability", "review-reliability"].map((lens, order) => relayCollectInput(lineageId, lens, order, true, "provider", revision)); }
+
+async function runCaptureGroup(cwd: string, harness: RoutingHarness, lineageId: string, inputs: readonly ReviewCollectInputV3[], reviewerRunAcknowledged = true): Promise<Record<string, unknown>> { return await __testing.executeReviewCaptureGroupOperation({ lineageId, collectBindings: inputs.map((input) => JSON.stringify(input)), reviewerRunAcknowledged }, cwd, harness.native) as Record<string, unknown>; }
+
+function prepared(request: ReviewHostRelayRequest) { return { request, promptByteLength: 64, resultByteLength: 32 }; }
+
+test("grouped capture forecasts once, reaches a four-reviewer barrier, and reconciles unclosed submissions", async (t) => {
+	t.after(() => __testing.setReviewHostRelayGroupRunnersForTesting());
+	const cwd = repository(t), lineageId = "relay-group", inputs = groupInputs(lineageId), lenses = inputs.map((input) => input.arguments.find((argument) => argument.name === "lens")!.value);
+	const harness = nativeHarness([finalizeStatus(lineageId, inputs), finalizeStatus(lineageId, inputs), ...inputs.map((_input, index) => finalizeStatus(lineageId, index === 1 ? [...inputs.slice(index), { name: "unrelated", schema: "example", captureOperation: "external.example", arguments: [] }] : inputs.slice(index))), finalizeStatus(lineageId)]);
+	let ready!: () => void;
+	const allStarted = new Promise<void>((resolve) => { ready = resolve; });
+	const releases = new Map<string, () => void>(), completed: string[] = [], submitted: string[] = [];
+	const reviewerGroup = async (requests: readonly ReviewHostRelayRequest[]) => await Promise.all(requests.map(async (request) => {
+		const lens = request.captureArgumentTokens.find((token) => token.startsWith("--lens="))!.slice(7);
+		await new Promise<void>((resolve) => { releases.set(lens, resolve); if (releases.size === requests.length) ready(); });
+		completed.push(lens); return prepared(request);
+	}));
+	__testing.setReviewHostRelayGroupRunnersForTesting(reviewerGroup, async (result) => {
+		submitted.push(result.request.captureArgumentTokens.find((token) => token.startsWith("--lens="))!.slice(7));
+		return { promptByteLength: result.promptByteLength, resultByteLength: result.resultByteLength, submission: "{}" };
+	});
+	const forecast = await runCaptureGroup(cwd, harness, lineageId, inputs, false);
+	assert.deepEqual(forecast.cost_forecast, { transport: "pi_host_relay", model_runs: 4, lenses });
+	const run = runCaptureGroup(cwd, harness, lineageId, inputs);
+	await allStarted;
+	assert.deepEqual([...releases.keys()], lenses, "all reviewers start before the group waits");
+	for (const lens of [...lenses].reverse()) releases.get(lens!)!();
+	const result = await run;
+	assert.deepEqual(completed, [...lenses].reverse(), "reviewer completion order is not submission order");
+	assert.deepEqual(submitted, lenses);
+	assert.deepEqual({ outcome: result.outcome, statusCalls: harness.statusCalls.length, providerAction: result.provider_action }, { outcome: "native-reviewer-group-status-reconciled", statusCalls: 7, providerAction: "stop" });
+	assert.equal(result.next_transition, undefined);
+});
+
+test("captured v5 STATUS accepts capture-phase Pn when authority has advanced to Rn at the forecast boundary", async (t) => {
+	t.after(() => __testing.setReviewHostRelayGroupRunnersForTesting());
+	const cwd = repository(t), lineageId = "relay-group-phase-revision", status = capturedGroupedStatus(lineageId, SHA), inputs = status.nextTransition!.collect!.inputs!;
+	let launches = 0;
+	__testing.setReviewHostRelayGroupRunnersForTesting(async (requests) => { launches += requests.length; return requests.map(prepared); });
+
+	assert.notEqual(status.authority!.revision, status.repositoryContext!.revision, "captured v5 group keeps capture-phase Pn distinct from authority Rn");
+	const forecast = await runCaptureGroup(cwd, nativeHarness([status]), lineageId, inputs, false);
+
+	assert.equal(forecast.outcome, "reviewer-model-run-forecast");
+	assert.deepEqual(forecast.cost_forecast, { transport: "pi_host_relay", model_runs: 4, lenses: ["review-risk", "review-resilience", "review-readability", "review-reliability"] });
+	assert.equal(launches, 0, "decoder-valid capture-phase Pn must pass admission before any reviewer model launch");
+});
+
+ test("group rejects STATUS repository target mismatch and per-slot revision, context, or target drift before launch", async (t) => {
+	t.after(() => __testing.setReviewHostRelayGroupRunnersForTesting());
+	const cwd = repository(t), lineageId = "relay-group-slot-consistency";
+	const repositoryTargetMismatch = capturedGroupedStatus(lineageId, SHA);
+	repositoryTargetMismatch.repositoryContext!.targetIdentity = SHA;
+	const revisionMismatch = capturedGroupedStatus(lineageId, SHA);
+	replaceArgument(revisionMismatch.nextTransition!.collect!.inputs![1]!, "expected-revision", SHA);
+	const contextMismatch = capturedGroupedStatus(lineageId, SHA);
+	replaceArgument(contextMismatch.nextTransition!.collect!.inputs![1]!, "repository-context", `rctx1_${"f".repeat(64)}`);
+	const targetMismatch = capturedGroupedStatus(lineageId, SHA);
+	replaceArgument(targetMismatch.nextTransition!.collect!.inputs![1]!, "target", SHA);
+	let launches = 0;
+	__testing.setReviewHostRelayGroupRunnersForTesting(async (requests) => { launches += requests.length; return requests.map(prepared); });
+
+	// Each call forwards this STATUS's own current set, so rejection proves an
+	// internal STATUS guard rather than stale or caller/canonical mismatch.
+	const repositoryTargetResult = await runCaptureGroup(cwd, nativeHarness([repositoryTargetMismatch]), lineageId, repositoryTargetMismatch.nextTransition!.collect!.inputs!);
+	assert.deepEqual({ outcome: repositoryTargetResult.outcome, reason: repositoryTargetResult.reason }, {
+		outcome: "capture-group-rejected",
+		reason: "current STATUS repository context does not match the reviewer group binding",
+	});
+	const revisionResult = await runCaptureGroup(cwd, nativeHarness([revisionMismatch]), lineageId, revisionMismatch.nextTransition!.collect!.inputs!);
+	assert.deepEqual({ outcome: revisionResult.outcome, reason: revisionResult.reason }, {
+		outcome: "capture-group-rejected",
+		reason: "current STATUS carries an incomplete or mismatched materialize reviewer binding",
+	});
+	const contextResult = await runCaptureGroup(cwd, nativeHarness([contextMismatch]), lineageId, contextMismatch.nextTransition!.collect!.inputs!);
+	assert.deepEqual({ outcome: contextResult.outcome, reason: contextResult.reason }, {
+		outcome: "capture-group-rejected",
+		reason: "current STATUS carries an incomplete or mismatched materialize reviewer binding",
+	});
+	const targetResult = await runCaptureGroup(cwd, nativeHarness([targetMismatch]), lineageId, targetMismatch.nextTransition!.collect!.inputs!);
+	assert.deepEqual({ outcome: targetResult.outcome, reason: targetResult.reason }, {
+		outcome: "capture-group-rejected",
+		reason: "current STATUS carries an incomplete or mismatched materialize reviewer binding",
+	});
+	assert.equal(launches, 0, "current STATUS consistency checks reject before reviewer model launch");
+});
+
+test("group rejects absent or mismatched current repository context before launch", async (t) => {
+	t.after(() => __testing.setReviewHostRelayGroupRunnersForTesting());
+	const cwd = repository(t), lineageId = "relay-group-context-reject", inputs = groupInputs(lineageId, PHASE_REVISION);
+	const revisionMismatch = finalizeStatus(lineageId, inputs);
+	const handleMismatch = finalizeStatus(lineageId, inputs);
+	const absent = finalizeStatus(lineageId, inputs);
+	handleMismatch.repositoryContext = { capability: "review.opaque_repository_context", handle: `rctx1_${"f".repeat(64)}`, revision: PHASE_REVISION, targetIdentity: SHA };
+	delete absent.repositoryContext;
+	let launches = 0;
+	__testing.setReviewHostRelayGroupRunnersForTesting(async (requests) => { launches += requests.length; return requests.map(prepared); });
+
+	for (const status of [revisionMismatch, handleMismatch, absent]) {
+		const result = await runCaptureGroup(cwd, nativeHarness([status]), lineageId, inputs);
+		assert.equal(result.outcome, "capture-group-rejected");
+	}
+	assert.equal(launches, 0, "repository-context validation must reject before reviewer model launch");
+});
+
+test("group rejects partial, duplicate, reordered, stale, mixed, and late-invalid bindings before launch", async (t) => {
+	t.after(() => __testing.setReviewHostRelayGroupRunnersForTesting());
+	const cwd = repository(t), lineageId = "relay-group-reject", inputs = groupInputs(lineageId);
+	const stale = JSON.parse(JSON.stringify(inputs[3]!)) as ReviewCollectInputV3;
+	stale.arguments = [...stale.arguments, { name: "replacement", value: "stale", token: "--replacement=stale" }];
+	const mixed = [...inputs.slice(0, 3), relayCollectInput(lineageId, "review-reliability", 3, false)];
+	const malformed = JSON.parse(JSON.stringify(inputs)) as ReviewCollectInputV3[];
+	malformed[3]!.submission!.argumentTokens = ["--input={{value}}"];
+	const cases = [
+		{ bindings: inputs.slice(0, 3), current: inputs }, { bindings: [...inputs].reverse(), current: inputs },
+		{ bindings: [...inputs.slice(0, 3), inputs[2]!], current: inputs }, { bindings: [...inputs.slice(0, 3), stale], current: inputs },
+		{ bindings: mixed, current: mixed }, { bindings: malformed, current: malformed },
+	];
+	let launches = 0;
+	__testing.setReviewHostRelayGroupRunnersForTesting(async (requests) => { launches += requests.length; return requests.map(prepared); });
+	for (const entry of cases) {
+		const result = await runCaptureGroup(cwd, nativeHarness([finalizeStatus(lineageId, entry.current)]), lineageId, entry.bindings);
+		assert.equal(result.outcome, "capture-group-rejected");
+	}
+	assert.equal(launches, 0);
+});
+
+test("group preserves earlier admission when a later STATUS drifts, and stops on closure or unknown outcome", async (t) => {
+	t.after(() => __testing.setReviewHostRelayGroupRunnersForTesting());
+	const cwd = repository(t), lineageId = "relay-group-stop", inputs = groupInputs(lineageId);
+	const reviewerGroup = async (requests: readonly ReviewHostRelayRequest[]) => requests.map(prepared);
+	let submissions = 0;
+	__testing.setReviewHostRelayGroupRunnersForTesting(reviewerGroup, async (result) => { submissions += 1; return { promptByteLength: result.promptByteLength, resultByteLength: result.resultByteLength, submission: "{}" }; });
+	const staleStatus = finalizeStatus(lineageId, inputs), stale = await runCaptureGroup(cwd, nativeHarness([finalizeStatus(lineageId, inputs), finalizeStatus(lineageId, inputs), staleStatus]), lineageId, inputs);
+	assert.deepEqual({ outcome: stale.outcome, submissions, mutation: stale.mutation_performed, mutationOutcome: stale.mutation_outcome }, { outcome: "capture-group-authority-drift", submissions: 1, mutation: true, mutationOutcome: "partial" });
+	assert.equal(stale.reconciliation, staleStatus.raw);
+	submissions = 0;
+	const drift = await runCaptureGroup(cwd, nativeHarness([finalizeStatus(lineageId, inputs), finalizeStatus(lineageId, inputs), finalizeStatus(lineageId, inputs.slice(2))]), lineageId, inputs);
+	assert.deepEqual({ outcome: drift.outcome, submissions, mutation: drift.mutation_performed, mutationOutcome: drift.mutation_outcome }, { outcome: "capture-group-authority-drift", submissions: 1, mutation: true, mutationOutcome: "partial" });
+	assert.deepEqual(((drift.host_relay as { reviewers: Array<{ lens: string }> }).reviewers).map((reviewer) => reviewer.lens), ["review-risk"]);
+	submissions = 0;
+	__testing.setReviewHostRelayGroupRunnersForTesting(reviewerGroup, async (result) => { submissions += 1; return { promptByteLength: result.promptByteLength, resultByteLength: result.resultByteLength, submission: JSON.stringify({ schema: "gentle-ai.review-last-event-closure/v1", operation: "review/capture-result", lineage_id: lineageId, state: "approved", store_revision: SHA, action: "native last event closed the review" }) }; });
+	const terminal = await runCaptureGroup(cwd, nativeHarness([finalizeStatus(lineageId, inputs), finalizeStatus(lineageId, inputs)]), lineageId, inputs);
+	assert.deepEqual({ status: terminal.status, submissions }, { status: "closed", submissions: 1 });
+	submissions = 0;
+	__testing.setReviewHostRelayGroupRunnersForTesting(reviewerGroup, async () => { submissions += 1; throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit", "unknown", { timedOut: true }); });
+	const unknown = await runCaptureGroup(cwd, nativeHarness([finalizeStatus(lineageId, inputs), finalizeStatus(lineageId, inputs), finalizeStatus(lineageId, inputs)]), lineageId, inputs);
+	assert.deepEqual({ status: unknown.status, submissions }, { status: "reconciled", submissions: 1 });
+});
+
 test("an old binary reports the relay as unavailable without touching existing behavior", async (t) => {
 	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
 	const cwd = repository(t);

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-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/runtime-harness.mjs

@@ -314,6 +314,7 @@ async function run() {
 		const capture = lastEventPi.tools.get("gentle_review_capture");
 		assert.ok(controller, "runtime must register the public status controller");
 		assert.ok(capture, "runtime must register the one-slot capture tool");
+		assert.equal(lastEventPi.tools.get("gentle_review_capture_group")?.executionMode, "sequential", "runtime must register grouped capture with bounded foreground concurrency");
 		assert.equal(controller.parameters.properties.operation.enum.includes("finalize"), false);
 		assert.equal(controller.parameters.properties.operation.enum.includes("validate"), false);