gentle-pi 2.2.0 → 2.4.0

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

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
@@ -7,28 +7,39 @@ import { createNodeExecFileAdapter } from "../lib/native-review-cli.ts";
 import {
 	REVIEW_HOST_RELAY_FAILURE,
 	REVIEW_HOST_RELAY_PI_ARGV,
+	REVIEW_HOST_RELAY_PI_TIMEOUT_ENV,
+	REVIEW_HOST_RELAY_PI_TIMEOUT_FLOOR_MS,
+	REVIEW_HOST_RELAY_PI_TIMEOUT_MAX_MS,
+	REVIEW_HOST_RELAY_PI_TIMEOUT_PER_MEBIBYTE_MS,
 	REVIEW_HOST_RELAY_SUBMISSION_MISSING_MESSAGE,
 	REVIEW_HOST_RELAY_UNAVAILABLE_MESSAGE,
 	ReviewHostRelayError,
 	classifyReviewHostRelayRefusal,
+	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";
 
 // ---------------------------------------------------------------------------
 // Fake binaries. Following the repo's fake-executable idiom (shell/git
-// wrappers in review-gate/git-commit-transaction tests), these are
+// wrappers in related review tests), these are
 // shebang scripts written into a scratch directory; node scripts are used so
 // binary-unsafe bytes survive verbatim.
 // ---------------------------------------------------------------------------
 
 const FAKE_GENTLE_AI = `#!/usr/bin/env node
 const fs = require("node:fs");
+const path = require("node:path");
 const argv = process.argv.slice(2);
-if (process.env.RELAY_FAKE_LOG) fs.appendFileSync(process.env.RELAY_FAKE_LOG, JSON.stringify({ argv, contract: process.env.${GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV} ?? null }) + "\\n");
+if (process.env.RELAY_FAKE_LOG) fs.appendFileSync(process.env.RELAY_FAKE_LOG, JSON.stringify({ argv, cwd: process.cwd(), contract: process.env.${GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV} ?? null }) + "\\n");
 if (argv.some((token) => token === "--materialize" || token.startsWith("--materialize="))) {
 	const mode = process.env.RELAY_FAKE_MATERIALIZE_MODE || "ok";
 	if (mode === "ok") { process.stdout.write(Buffer.from(process.env.RELAY_FAKE_PROMPT_B64 || "", "base64")); process.exit(0); }
@@ -40,10 +51,37 @@ if (argv.some((token) => token === "--materialize" || token.startsWith("--materi
 const inputToken = argv.find((token) => token === "--input" || token.startsWith("--input="));
 if (inputToken !== undefined) {
 	const mode = process.env.RELAY_FAKE_SUBMIT_MODE || "ok";
-	if (mode === "ok") {
-		const inputPath = inputToken.startsWith("--input=") ? inputToken.slice("--input=".length) : argv[argv.indexOf("--input") + 1];
+	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);
+		const accepted = JSON.stringify({ schema: "gentle-ai.review-result-artifact/v2", admission_decision: "completed" });
+		if (mode === "cleanup-fail") {
+			process.stdout.write(accepted, () => {
+				fs.chmodSync(path.dirname(path.dirname(inputPath)), 0o500);
+				process.exit(0);
+			});
+			return;
+		}
+		process.stdout.write(accepted);
+		process.exit(0);
+	}
+	if (mode === "refuse-cleanup-fail") fs.chmodSync(path.dirname(path.dirname(inputPath)), 0o500);
+	if (mode === "admit") {
+		// Go's admission refusal shape: a schema-bounded failure/v2 envelope on
+		// stdout, the operator line with the typed code suffix on stderr, exit 1.
+		const bytes = fs.readFileSync(inputPath);
+		let parsed;
+		try { parsed = JSON.parse(bytes.toString("utf8")); } catch { parsed = undefined; }
+		const refuse = (cause) => {
+			process.stdout.write(JSON.stringify({ schema: "gentle-ai.review-integration.failure/v2", contract: "gentle-ai.review-integration/v2", operation: "review.capture-result", phase: "preflight", code: "invalid_request", message: "The negotiated review request is invalid.", mutation_outcome: "not_started", authority_applicability: "not_evaluated", retry_safe: true, replayability: "not_replayable", required_inputs: [], next_action: "correct_request", cause }));
+			process.stderr.write("Error: " + cause + " [invalid_request]\\n");
+			process.exit(1);
+		};
+		if (parsed === undefined || typeof parsed !== "object") refuse("lens provider result admission incomplete: reviewer payload contains no complete JSON object: no object start was found in " + bytes.length + " bytes; the rejected reviewer payload was preserved at " + inputPath + ".rejected");
+		if (parsed.subject_hash !== process.env.RELAY_FAKE_EXPECTED_SUBJECT) refuse("reviewer artifact admission binding_mismatch: reviewer result echoed a different artifact subject: the rejected admission did not consume the lens slot, so re-run the lens and invoke gentle-ai review capture-result again on the same lineage with a result that echoes the binding's top-level subject_hash, which is " + process.env.RELAY_FAKE_EXPECTED_SUBJECT);
 		process.stdout.write(JSON.stringify({ schema: "gentle-ai.review-result-artifact/v2", admission_decision: "completed" }));
 		process.exit(0);
 	}
@@ -56,6 +94,7 @@ process.exit(9);
 
 const FAKE_PI = `#!/usr/bin/env node
 const fs = require("node:fs");
+const path = require("node:path");
 const argv = process.argv.slice(2);
 if (process.env.RELAY_FAKE_PI_LOG) fs.appendFileSync(process.env.RELAY_FAKE_PI_LOG, JSON.stringify({ argv, cwd: process.cwd(), entries: fs.readdirSync(process.cwd()), contract: process.env.${GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV} ?? null }) + "\\n");
 const chunks = [];
@@ -63,12 +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 (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();
 });
 `;
 
@@ -80,11 +139,12 @@ interface RelayHarness {
 	piLogPath: string;
 	stdinCapturePath: string;
 	submitCapturePath: string;
+	targetCwd: string;
 	environment: NodeJS.ProcessEnv;
 }
 
 function harness(t: test.TestContext, overrides: Record<string, string> = {}): RelayHarness {
-	const directory = mkdtempSync(join(tmpdir(), "gentle-pi-relay-harness-"));
+	const directory = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-relay-harness-")));
 	t.after(() => rmSync(directory, { recursive: true, force: true }));
 	const gentleAi = join(directory, "gentle-ai");
 	const pi = join(directory, "pi");
@@ -96,6 +156,8 @@ function harness(t: test.TestContext, overrides: Record<string, string> = {}): R
 	const piLogPath = join(directory, "pi.log");
 	const stdinCapturePath = join(directory, "pi-stdin.bin");
 	const submitCapturePath = join(directory, "submitted.bin");
+	const targetCwd = join(directory, "target-worktree");
+	mkdirSync(targetCwd);
 	const environment: NodeJS.ProcessEnv = {
 		...process.env,
 		RELAY_FAKE_LOG: logPath,
@@ -107,7 +169,7 @@ function harness(t: test.TestContext, overrides: Record<string, string> = {}): R
 	// The relay itself must add the handshake; the base environment never
 	// carries it, so the fake-binary log proves the injection.
 	delete environment[GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV];
-	return { directory, gentleAi, pi, logPath, piLogPath, stdinCapturePath, submitCapturePath, environment };
+	return { directory, gentleAi, pi, logPath, piLogPath, stdinCapturePath, submitCapturePath, targetCwd, environment };
 }
 
 function readLog(path: string): Array<{ argv: string[]; contract: string | null; cwd?: string; entries?: string[] }> {
@@ -115,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)}`,
@@ -125,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.
@@ -152,6 +223,7 @@ function relayRequest(fixture: RelayHarness, overrides: Record<string, unknown>
 		submission: SUBMISSION,
 		gentleAiExecutable: fixture.gentleAi,
 		piExecutable: fixture.pi,
+		targetCwd: fixture.targetCwd,
 		environment: {
 			...fixture.environment,
 			RELAY_FAKE_PROMPT_B64: PROMPT_BYTES.toString("base64"),
@@ -163,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) => {
@@ -229,11 +315,13 @@ test("relay happy path moves prompt and result bytes verbatim through a fresh em
 	const substituted = gentleAiCalls[1]!.argv.at(-1)!;
 	assert.match(substituted, /^--input=\S+$/);
 	assert.equal(substituted.includes("{{value}}"), false);
+	assert.equal(existsSync(substituted.slice("--input=".length)), false, "the coordinator removes its temporary result file after provider submission");
 	assert.equal(gentleAiCalls[1]!.argv.length, 2 + SUBMISSION.argumentTokens.length);
 	assert.equal(gentleAiCalls[1]!.argv.some((token) => token.includes("--agent") || token.includes("--materialize")), false);
 	// Handshake declared on both gentle-ai invocations even though the base
 	// environment carried none.
 	assert.deepEqual(gentleAiCalls.map((call) => call.contract), [GENTLE_PI_REVIEW_RELAY_CONTRACT, GENTLE_PI_REVIEW_RELAY_CONTRACT]);
+	assert.deepEqual(gentleAiCalls.map((call) => call.cwd), [fixture.targetCwd, fixture.targetCwd]);
 
 	const piCalls = readLog(fixture.piLogPath);
 	assert.equal(piCalls.length, 1);
@@ -266,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.
 // ---------------------------------------------------------------------------
@@ -305,12 +532,108 @@ test("empty pi stdout fails closed with a typed error and no submission", async
 
 test("pi timeout fails closed with a typed error and no submission", async (t) => {
 	const fixture = harness(t, { RELAY_FAKE_PI_MODE: "hang" });
-	const error = await rejectsWithRelayError(runReviewHostRelaySlot(relayRequest(fixture, { piTimeoutMs: 300 })), REVIEW_HOST_RELAY_FAILURE.PI_FAILED, "pi");
+	const error = await rejectsWithRelayError(runReviewHostRelaySlot(relayRequest(fixture, { piTimeoutMs: 300 })), REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi");
 	assert.equal(error.timedOut, true);
 	assert.equal(readLog(fixture.logPath).length, 1);
 	assert.equal(existsSync(fixture.submitCapturePath), false);
 });
 
+// ---------------------------------------------------------------------------
+// gentle-pi#367 — the reviewer bound is reachable from production, and a
+// reviewer killed by it says so with both measurements.
+// ---------------------------------------------------------------------------
+
+test("the reviewer bound scales with materialized prompt bytes instead of one fixed number", () => {
+	const empty: NodeJS.ProcessEnv = {};
+	// A tiny prompt still gets the model-latency floor.
+	assert.equal(resolveReviewHostRelayPiTimeoutMs(0, empty), REVIEW_HOST_RELAY_PI_TIMEOUT_FLOOR_MS);
+	assert.equal(resolveReviewHostRelayPiTimeoutMs(1, empty), REVIEW_HOST_RELAY_PI_TIMEOUT_FLOOR_MS + 1);
+	// One mebibyte of prompt buys exactly one linear allowance.
+	assert.equal(
+		resolveReviewHostRelayPiTimeoutMs(1024 * 1024, empty),
+		REVIEW_HOST_RELAY_PI_TIMEOUT_FLOOR_MS + REVIEW_HOST_RELAY_PI_TIMEOUT_PER_MEBIBYTE_MS,
+	);
+	// The reported field candidate: ~1.58 MB of prompt, whose reviewer needed
+	// 478s and was killed by the old fixed 600s bound. The derived bound must
+	// clear that measurement with real margin.
+	const reported = resolveReviewHostRelayPiTimeoutMs(1_580_000, empty);
+	assert.ok(reported > 600_000, `derived bound ${reported} must exceed the old fixed 600000ms bound`);
+	assert.ok(reported > 478_000 * 3, `derived bound ${reported} must keep real margin over the measured 478000ms reviewer run`);
+	// Never unbounded, however large the prompt gets.
+	assert.equal(resolveReviewHostRelayPiTimeoutMs(Number.MAX_SAFE_INTEGER, empty), REVIEW_HOST_RELAY_PI_TIMEOUT_MAX_MS);
+});
+
+test("the reviewer bound honours the environment override and ignores malformed values", () => {
+	const bytes = 4 * 1024 * 1024;
+	assert.equal(resolveReviewHostRelayPiTimeoutMs(bytes, { [REVIEW_HOST_RELAY_PI_TIMEOUT_ENV]: "1234" }), 1234);
+	// The override is clamped by the same hard ceiling as the derived bound.
+	assert.equal(resolveReviewHostRelayPiTimeoutMs(bytes, { [REVIEW_HOST_RELAY_PI_TIMEOUT_ENV]: "999999999" }), REVIEW_HOST_RELAY_PI_TIMEOUT_MAX_MS);
+	const derived = resolveReviewHostRelayPiTimeoutMs(bytes, {});
+	for (const malformed of ["", "0", "-1", "12.5", "abc", " 600000", "1e6"]) {
+		assert.equal(resolveReviewHostRelayPiTimeoutMs(bytes, { [REVIEW_HOST_RELAY_PI_TIMEOUT_ENV]: malformed }), derived, `malformed ${JSON.stringify(malformed)} must fall back to the derived bound`);
+	}
+});
+
+test("the production relay path resolves the reviewer bound from the environment, with no injected timeout", async (t) => {
+	// The regression: piTimeoutMs was reachable only through the test seam, so
+	// production always ran against the fixed 600s bound. This request injects
+	// no timeout at all — the override must reach the real spawn.
+	const fixture = harness(t, { RELAY_FAKE_PI_MODE: "hang", [REVIEW_HOST_RELAY_PI_TIMEOUT_ENV]: "300" });
+	const error = await rejectsWithRelayError(
+		runReviewHostRelaySlot(relayRequest(fixture, { piTimeoutMs: undefined })),
+		REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT,
+		"pi",
+	);
+	assert.equal(error.timeoutMs, 300);
+	assert.equal(error.timedOut, true);
+	assert.equal(readLog(fixture.logPath).length, 1, "no submission after a reviewer timeout");
+	assert.equal(existsSync(fixture.submitCapturePath), false);
+});
+
+test("a relay Pi timeout keeps its typed mapping and timing evidence when opaque scratch cleanup also fails", async (t) => {
+	const fixture = harness(t, { RELAY_FAKE_PI_MODE: "hang", RELAY_FAKE_PI_BREAK_CLEANUP: "true" });
+	const scratchParent = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-relay-pi-primary-failure-")));
+	const originalTmpdir = process.env.TMPDIR;
+	process.env.TMPDIR = scratchParent;
+	try {
+		const error = await rejectsWithRelayError(
+			runReviewHostRelaySlot(relayRequest(fixture, { piTimeoutMs: 300 })),
+			REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT,
+			"pi",
+		);
+		assert.equal(error.timedOut, true);
+		assert.equal(error.timeoutMs, 300);
+		assert.ok(error.elapsedMs !== null && error.elapsedMs >= 250);
+	} finally {
+		if (originalTmpdir === undefined) delete process.env.TMPDIR;
+		else process.env.TMPDIR = originalTmpdir;
+		chmodSync(scratchParent, 0o700);
+		rmSync(scratchParent, { recursive: true, force: true });
+	}
+});
+
+test("a killed reviewer reports elapsed, limit, and what to change instead of an opaque transport failure", async (t) => {
+	const fixture = harness(t, { RELAY_FAKE_PI_MODE: "hang" });
+	const error = await rejectsWithRelayError(runReviewHostRelaySlot(relayRequest(fixture, { piTimeoutMs: 300 })), REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi");
+	assert.equal(error.timeoutMs, 300);
+	assert.ok(error.elapsedMs !== null && error.elapsedMs >= 250, `elapsed ${error.elapsedMs} must record the real wall time`);
+	assert.ok(error.elapsedMs! < 10_000, "the reviewer was killed at the bound, not left to finish");
+	assert.match(error.message, /exceeded the relay bound/);
+	assert.match(error.message, new RegExp(String(error.elapsedMs)));
+	assert.match(error.message, /limit for a \d+-byte materialized prompt/);
+	assert.match(error.message, new RegExp(REVIEW_HOST_RELAY_PI_TIMEOUT_ENV));
+	assert.equal(error.mutationOutcome, "none");
+});
+
+test("a crashed reviewer stays distinguishable from a killed one and still carries its measurements", async (t) => {
+	const fixture = harness(t, { RELAY_FAKE_PI_MODE: "fail" });
+	const error = await rejectsWithRelayError(runReviewHostRelaySlot(relayRequest(fixture, { piTimeoutMs: 30_000 })), REVIEW_HOST_RELAY_FAILURE.PI_FAILED, "pi");
+	assert.equal(error.timedOut, false);
+	assert.equal(error.exitCode, 4);
+	assert.equal(error.timeoutMs, 30_000);
+	assert.ok(error.elapsedMs !== null && error.elapsedMs >= 0);
+});
+
 test("submission refusal is a typed error whose outcome is unknown pending STATUS", async (t) => {
 	const fixture = harness(t, { RELAY_FAKE_SUBMIT_MODE: "refuse" });
 	const error = await rejectsWithRelayError(runReviewHostRelaySlot(relayRequest(fixture)), REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit");
@@ -319,6 +642,84 @@ test("submission refusal is a typed error whose outcome is unknown pending STATU
 	assert.equal(readLog(fixture.logPath).length, 2);
 });
 
+// gentle-pi#522 / #524: Go refuses a reviewer submission at admission with a
+// typed [invalid_request] refusal and states that the lens slot was not
+// consumed. That is a proven non-mutation, not an unknown outcome, and the
+// refusal text is the only thing that tells the host what to change.
+function admittingRequest(fixture: RelayHarness, reviewerOutput: Buffer) {
+	return relayRequest(fixture, {
+		environment: {
+			...fixture.environment,
+			RELAY_FAKE_PROMPT_B64: PROMPT_BYTES.toString("base64"),
+			RELAY_FAKE_PI_OUTPUT_B64: reviewerOutput.toString("base64"),
+		},
+	});
+}
+
+test("a reviewer printing garbage is refused at admission as a proven non-mutation carrying Go's refusal", async (t) => {
+	const fixture = harness(t, { RELAY_FAKE_SUBMIT_MODE: "admit", RELAY_FAKE_EXPECTED_SUBJECT: `sha256:${"a".repeat(64)}` });
+	const error = await rejectsWithRelayError(
+		runReviewHostRelaySlot(admittingRequest(fixture, Buffer.from("not json at all", "utf8"))),
+		REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED,
+		"submit",
+	);
+	assert.equal(error.mutationOutcome, "none");
+	assert.equal(error.exitCode, 1);
+	assert.equal(error.timedOut, false);
+	assert.match(error.stderr, /reviewer payload contains no complete JSON object/);
+	assert.match(error.stderr, /\[invalid_request\]/);
+	assert.match(error.message, /reviewer payload contains no complete JSON object/);
+	assert.equal(readLog(fixture.logPath).length, 2, "the refusal must not be retried by the relay");
+});
+
+test("a reviewer echoing a different subject is refused at admission as a proven non-mutation carrying Go's continuation", async (t) => {
+	const fixture = harness(t, { RELAY_FAKE_SUBMIT_MODE: "admit", RELAY_FAKE_EXPECTED_SUBJECT: `sha256:${"a".repeat(64)}` });
+	const wrongSubject = Buffer.from(JSON.stringify({ subject_hash: `sha256:${"0".repeat(64)}`, inspection: { status: "completed", paths: [] }, findings: [], evidence: ["x"] }), "utf8");
+	const error = await rejectsWithRelayError(
+		runReviewHostRelaySlot(admittingRequest(fixture, wrongSubject)),
+		REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED,
+		"submit",
+	);
+	assert.equal(error.mutationOutcome, "none");
+	assert.equal(error.exitCode, 1);
+	assert.match(error.stderr, /binding_mismatch/);
+	assert.match(error.stderr, /did not consume the lens slot/);
+	assert.match(error.stderr, /\[invalid_request\]/);
+	assert.match(error.message, /did not consume the lens slot/);
+	assert.equal(readLog(fixture.logPath).length, 2, "the refusal must not be retried by the relay");
+});
+
+test("a submission the fake admits with the expected subject still completes", async (t) => {
+	const fixture = harness(t, { RELAY_FAKE_SUBMIT_MODE: "admit", RELAY_FAKE_EXPECTED_SUBJECT: `sha256:${"a".repeat(64)}` });
+	const result = await runReviewHostRelaySlot(admittingRequest(fixture, Buffer.from(JSON.stringify({ subject_hash: `sha256:${"a".repeat(64)}`, inspection: { status: "completed", paths: [] }, findings: [], evidence: ["x"] }), "utf8")));
+	assert.equal(JSON.parse(result.submission).admission_decision, "completed");
+});
+
+test("submission refusal preserves its primary evidence when result staging cleanup also fails", async (t) => {
+	const fixture = harness(t, { RELAY_FAKE_SUBMIT_MODE: "refuse-cleanup-fail" });
+	const scratchParent = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-relay-primary-failure-")));
+	const originalTmpdir = process.env.TMPDIR;
+	process.env.TMPDIR = scratchParent;
+	try {
+		const error = await rejectsWithRelayError(
+			runReviewHostRelaySlot(relayRequest(fixture)),
+			REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED,
+			"submit",
+		);
+		assert.equal(error.exitCode, 1);
+		assert.equal(error.timedOut, false);
+		assert.equal(error.timeoutMs, 30_000);
+		assert.ok(error.elapsedMs !== null && error.elapsedMs >= 0);
+		assert.match(error.stderr, /capture binding does not match/);
+		assert.doesNotMatch(error.message, /staging cleanup/i);
+	} finally {
+		if (originalTmpdir === undefined) delete process.env.TMPDIR;
+		else process.env.TMPDIR = originalTmpdir;
+		chmodSync(scratchParent, 0o700);
+		rmSync(scratchParent, { recursive: true, force: true });
+	}
+});
+
 test("relay scratch and staging directories are removed after failures too", async (t) => {
 	const fixture = harness(t, { RELAY_FAKE_PI_MODE: "fail" });
 	await rejectsWithRelayError(runReviewHostRelaySlot(relayRequest(fixture)), REVIEW_HOST_RELAY_FAILURE.PI_FAILED, "pi");
@@ -327,6 +728,27 @@ test("relay scratch and staging directories are removed after failures too", asy
 	assert.equal(existsSync(piCalls[0]!.cwd!), false);
 });
 
+test("a result staging cleanup failure remains a typed submit failure", async (t) => {
+	const fixture = harness(t, { RELAY_FAKE_SUBMIT_MODE: "cleanup-fail" });
+	const scratchParent = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-relay-cleanup-")));
+	const originalTmpdir = process.env.TMPDIR;
+	process.env.TMPDIR = scratchParent;
+	try {
+		const error = await rejectsWithRelayError(
+			runReviewHostRelaySlot(relayRequest(fixture)),
+			REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED,
+			"submit",
+		);
+		assert.equal(error.mutationOutcome, "unknown");
+		assert.match(error.message, /staging cleanup/i);
+	} finally {
+		if (originalTmpdir === undefined) delete process.env.TMPDIR;
+		else process.env.TMPDIR = originalTmpdir;
+		chmodSync(scratchParent, 0o700);
+		rmSync(scratchParent, { recursive: true, force: true });
+	}
+});
+
 // ---------------------------------------------------------------------------
 // Capability detection — typed refusal classes, no version sniffing.
 // ---------------------------------------------------------------------------