gentle-pi 2.2.0 → 2.4.0

package/lib/review-host-relay.ts

@@ -1,16 +1,16 @@
 // The thin Pi host relay (gentle-pi#311 P4; provider contract gentle-ai#3249).
 //
 // gentle-ai owns prompt materialization, role and schema selection, byte
-// budgets, parsing, admission, immutable capture, retry and correction
-// accounting, receipts, and delivery gates. This host boundary is
+// budgets, parsing, admission, immutable capture, retry, correction
+// accounting, and receipt state. This host boundary is
 // intentionally narrow:
 //
 //   1. Run the exact provider-issued capture binding with `--agent pi
 //      --materialize` and take stdout as opaque prompt BYTES, verbatim.
-//   2. Launch a brand-new locked-down print-mode `pi` subprocess in a fresh
-//      empty scratch directory, pipe the prompt through stdin, and take
-//      stdout as raw final bytes. Model/provider/profile selection stays
-//      user-owned: no --model, no --provider, environment untouched.
+//   2. Pass those prompt bytes to the pure opaque Pi adapter, which owns its
+//      locked-down print-mode subprocess and fresh empty scratch directory;
+//      take its stdout as raw final bytes. Model/provider/profile selection
+//      stays user-owned: no --model, no --provider, environment untouched.
 //   3. Submit those bytes untouched through the provider-owned `submission`
 //      form carried by the collect input: execute its exact operation and
 //      argument tokens with only the tempfile path substituted into the
@@ -30,25 +30,18 @@ import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { resolveGentleAiBinary } from "./gentle-ai-binary.ts";
+import {
+	OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE,
+	OpaquePiReviewerTransportError,
+	runOpaquePiReviewer,
+	type OpaquePiReviewerResult,
+} from "./opaque-pi-reviewer-adapter.ts";
 import { REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION, REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS, type ReviewCaptureSubmissionV1, type ReviewCollectInputV3 } from "./review-integration-v2.ts";
 import { GENTLE_PI_REVIEW_RELAY_CONTRACT, GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV } from "./review-relay-contract.ts";
 
-// The complete pinned lockdown argv for the reviewer `pi` subprocess: print
-// mode, text output, and every discovery surface disabled. Nothing may be
-// added or removed here without a new relay contract — in particular no
-// --model/--provider/--profile, which remain user-owned.
-export const REVIEW_HOST_RELAY_PI_ARGV = Object.freeze([
-	"--print",
-	"--mode", "text",
-	"--no-session",
-	"--no-tools",
-	"--no-extensions",
-	"--no-skills",
-	"--no-prompt-templates",
-	"--no-themes",
-	"--no-context-files",
-	"--no-approve",
-] as const);
+// Compatibility export for existing relay consumers. The pure adapter owns the
+// fixed Pi process boundary and its locked-down argv.
+export { OPAQUE_PI_REVIEWER_ARGV as REVIEW_HOST_RELAY_PI_ARGV } from "./opaque-pi-reviewer-adapter.ts";
 
 export const REVIEW_HOST_RELAY_UNAVAILABLE_MESSAGE =
 	"provider relay requires a gentle-ai build with the pi host relay surface";
@@ -61,6 +54,11 @@ export const REVIEW_HOST_RELAY_FAILURE = {
 	EMPTY_PROMPT: "empty-prompt",
 	PI_LAUNCH_FAILED: "pi-launch-failed",
 	PI_FAILED: "pi-failed",
+	// gentle-pi#367: a reviewer killed by the relay bound is not a crash. It
+	// is the one failure class that a byte-identical relaunch cannot survive,
+	// so it carries its own kind, its own elapsed/limit evidence, and its own
+	// continuation instead of hiding inside `pi-failed`.
+	PI_TIMED_OUT: "pi-timed-out",
 	PI_EMPTY_OUTPUT: "pi-empty-output",
 	SUBMISSION_REFUSED: "submission-refused",
 } as const;
@@ -79,11 +77,20 @@ export class ReviewHostRelayError extends Error {
 	readonly exitCode: number | null;
 	readonly stderr: string;
 	readonly timedOut: boolean;
+	// Wall time the killed or failed child actually consumed, and the bound it
+	// was measured against. Both are null only when no child process ran.
+	// Without them a transport failure cannot be told apart from a crash, which
+	// is what forced the gentle-pi#367 reporter to measure the relay by hand.
+	readonly elapsedMs: number | null;
+	readonly timeoutMs: number | null;
 	// "none" until the submission invocation launches; a launched submission
 	// whose outcome could not be read is "unknown" and the caller reconciles
-	// through negotiated STATUS, never through a blind retry.
+	// through negotiated STATUS, never through a blind retry. A launched
+	// submission that gentle-ai refused with its typed admission refusal is
+	// "none" again: the provider states that the lens slot was not consumed
+	// (gentle-pi#522 / #524).
 	readonly mutationOutcome: "none" | "unknown";
-	constructor(kind: ReviewHostRelayFailureKind, stage: ReviewHostRelayStage, message: string, details?: { exitCode?: number | null; stderr?: string; timedOut?: boolean }) {
+	constructor(kind: ReviewHostRelayFailureKind, stage: ReviewHostRelayStage, message: string, details?: { exitCode?: number | null; stderr?: string; timedOut?: boolean; elapsedMs?: number; timeoutMs?: number; mutationOutcome?: "none" | "unknown" }) {
 		super(message);
 		this.name = "ReviewHostRelayError";
 		this.kind = kind;
@@ -91,10 +98,23 @@ export class ReviewHostRelayError extends Error {
 		this.exitCode = details?.exitCode ?? null;
 		this.stderr = details?.stderr ?? "";
 		this.timedOut = details?.timedOut ?? false;
-		this.mutationOutcome = stage === "submit" ? "unknown" : "none";
+		this.elapsedMs = details?.elapsedMs ?? null;
+		this.timeoutMs = details?.timeoutMs ?? null;
+		this.mutationOutcome = details?.mutationOutcome ?? (stage === "submit" ? "unknown" : "none");
 	}
 }
 
+// gentle-pi#522 / #524: gentle-ai refuses a reviewer submission before any
+// admission with exit 1 and its typed operator line, `<reason> [invalid_request]`.
+// That code is the provider's preflight class: the request was refused as
+// sent and the lens slot was not consumed. The relay recognises only that
+// typed shape; it never parses the reason, and it never retries.
+const ADMISSION_REFUSAL = /\[invalid_request\]/;
+
+export function isReviewHostRelayAdmissionRefusal(capture: { exitCode: number | null; timedOut: boolean }, stderr: string): boolean {
+	return capture.exitCode === 1 && !capture.timedOut && ADMISSION_REFUSAL.test(stderr);
+}
+
 // Refusal classification for the materialize invocation. The installed
 // gentle-ai is the only authority on whether the materialize form exists; Pi
 // never version-sniffs. Two typed refusal classes are distinguished:
@@ -237,6 +257,8 @@ export function resolveReviewHostRelaySubmission(submission: ReviewCaptureSubmis
 
 export interface ReviewHostRelayRequest {
 	readonly captureArgumentTokens: readonly string[];
+	/** Canonical target worktree for coordinator-only native materialize/submit calls. */
+	readonly targetCwd?: string;
 	/** The provider-owned completing form; absent means contract mismatch. */
 	readonly submission?: ReviewCaptureSubmissionV1;
 	/** Absolute path; defaults to the verified package-local binary. */
@@ -245,6 +267,12 @@ export interface ReviewHostRelayRequest {
 	readonly piExecutable?: string;
 	readonly environment?: NodeJS.ProcessEnv;
 	readonly gentleAiTimeoutMs?: number;
+	/**
+	 * Overrides the reviewer bound entirely. Production leaves it unset and the
+	 * relay derives the bound from the materialized prompt bytes and
+	 * {@link REVIEW_HOST_RELAY_PI_TIMEOUT_ENV}; this seam exists so tests can
+	 * exercise the timeout leg without a wall-clock wait.
+	 */
 	readonly piTimeoutMs?: number;
 	readonly signal?: AbortSignal;
 }
@@ -256,24 +284,88 @@ export interface ReviewHostRelayResult {
 	readonly submission: string;
 }
 
+/** Opaque materialize-and-review result, not yet submitted to the provider. */
+export interface ReviewHostRelayPreparedResult {
+	/** Copy-safe request snapshot captured before materialization starts. */
+	readonly request: ReviewHostRelayRequest;
+	readonly promptByteLength: number;
+	readonly resultByteLength: number;
+}
+
+const preparedResultBytes = new WeakMap<ReviewHostRelayPreparedResult, Buffer>();
+
 export type ReviewHostRelayRunner = (request: ReviewHostRelayRequest) => Promise<ReviewHostRelayResult>;
+export type ReviewHostRelayPreparationRunner = (request: ReviewHostRelayRequest) => Promise<ReviewHostRelayPreparedResult>;
+export type ReviewHostRelaySubmissionRunner = (prepared: ReviewHostRelayPreparedResult) => Promise<ReviewHostRelayResult>;
 
 const DEFAULT_GENTLE_AI_TIMEOUT_MS = 120_000;
-const DEFAULT_PI_TIMEOUT_MS = 600_000;
+
+// ---------------------------------------------------------------------------
+// The reviewer subprocess bound (gentle-pi#367).
+//
+// The previous bound was a single hardcoded 600_000 ms reachable only through
+// the test-injectable runner. A field-measured lens legitimately needed 478s
+// against a ~1.58 MB materialized prompt: it survived by hand and was killed
+// under the relay, and the sanctioned continuation then re-spent every lens to
+// reach the same wall. One fixed number cannot serve a prompt class that
+// varies by orders of magnitude, so the bound is derived instead:
+//
+//   floor + ceil(promptBytes / MiB * perMebibyte), clamped to the ceiling
+//
+// The floor covers model latency that does not depend on prompt size; the
+// linear term covers the part that does. At the measured 1.58 MB the derived
+// bound is ~37 minutes, roughly a 4.7x margin over the 478s the reviewer
+// actually needed — deliberately generous, because the reviewer model and
+// provider are user-owned and the relay cannot know their throughput.
+//
+// GENTLE_PI_REVIEW_RELAY_PI_TIMEOUT_MS replaces the derived bound entirely for
+// callers who know their own configuration. It follows the repository's
+// established numeric-override shape (GENTLE_PI_CANDIDATE_GIT_TIMEOUT_MS,
+// GENTLE_PI_REVIEW_MAX_BUFFER_BYTES): a positive decimal, silently ignored
+// when malformed, and clamped to the same hard ceiling so no configuration can
+// turn a foreground FINALIZE into an unbounded child process.
+// ---------------------------------------------------------------------------
+
+export const REVIEW_HOST_RELAY_PI_TIMEOUT_ENV = "GENTLE_PI_REVIEW_RELAY_PI_TIMEOUT_MS";
+export const REVIEW_HOST_RELAY_PI_TIMEOUT_FLOOR_MS = 900_000;
+export const REVIEW_HOST_RELAY_PI_TIMEOUT_PER_MEBIBYTE_MS = 900_000;
+export const REVIEW_HOST_RELAY_PI_TIMEOUT_MAX_MS = 7_200_000;
+const BYTES_PER_MEBIBYTE = 1024 * 1024;
+
+export function resolveReviewHostRelayPiTimeoutMs(promptByteLength: number, environment: NodeJS.ProcessEnv = process.env): number {
+	const configured = environment[REVIEW_HOST_RELAY_PI_TIMEOUT_ENV];
+	if (configured !== undefined && /^[1-9]\d*$/.test(configured)) {
+		const parsed = Number(configured);
+		if (Number.isSafeInteger(parsed)) return Math.min(parsed, REVIEW_HOST_RELAY_PI_TIMEOUT_MAX_MS);
+	}
+	const bytes = Number.isSafeInteger(promptByteLength) && promptByteLength > 0 ? promptByteLength : 0;
+	const scaled = REVIEW_HOST_RELAY_PI_TIMEOUT_FLOOR_MS + Math.ceil((bytes / BYTES_PER_MEBIBYTE) * REVIEW_HOST_RELAY_PI_TIMEOUT_PER_MEBIBYTE_MS);
+	return Math.min(scaled, REVIEW_HOST_RELAY_PI_TIMEOUT_MAX_MS);
+}
+
+// The reviewer ran out of time; it did not crash. The message states both
+// measurements and names the two things that can change the outcome, because
+// the one thing that cannot is relaunching the identical slot.
+export function reviewHostRelayPiTimeoutMessage(elapsedMs: number, timeoutMs: number, promptByteLength: number): string {
+	return `pi reviewer subprocess exceeded the relay bound: killed after ${elapsedMs}ms against a ${timeoutMs}ms limit for a ${promptByteLength}-byte materialized prompt. `
+		+ `Relaunching the same slot unchanged reaches the same wall. Raise ${REVIEW_HOST_RELAY_PI_TIMEOUT_ENV} above the reviewer's real wall time (ceiling ${REVIEW_HOST_RELAY_PI_TIMEOUT_MAX_MS}ms) or reduce the candidate scope so the materialized prompt is smaller.`;
+}
 
 interface ProcessCapture {
 	stdout: Buffer;
 	stderr: Buffer;
 	exitCode: number | null;
 	timedOut: boolean;
+	elapsedMs: number;
 }
 
-function collectProcess(
+function collectGentleAiProcess(
 	file: string,
 	arguments_: readonly string[],
 	options: { cwd: string; env: NodeJS.ProcessEnv; stdin?: Buffer; timeoutMs: number; signal?: AbortSignal },
 ): Promise<ProcessCapture> {
 	return new Promise((resolve, reject) => {
+		const startedAt = Date.now();
 		const child = spawn(file, [...arguments_], {
 			cwd: options.cwd,
 			env: options.env,
@@ -305,7 +397,7 @@ function collectProcess(
 			if (settled) return;
 			settled = true;
 			if (timer !== undefined) clearTimeout(timer);
-			resolve({ stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr), exitCode: code, timedOut });
+			resolve({ stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr), exitCode: code, timedOut, elapsedMs: Date.now() - startedAt });
 		});
 		if (options.stdin === undefined) {
 			child.stdin.end();
@@ -316,6 +408,45 @@ function collectProcess(
 	});
 }
 
+function relayPiTransportError(error: unknown, promptByteLength: number, piTimeoutMs: number): ReviewHostRelayError {
+	if (!(error instanceof OpaquePiReviewerTransportError)) {
+		return new ReviewHostRelayError(
+			REVIEW_HOST_RELAY_FAILURE.PI_LAUNCH_FAILED,
+			"pi",
+			`pi subprocess could not start: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	const details = {
+		exitCode: error.exitCode,
+		stderr: error.stderr.toString("utf8"),
+		timedOut: error.timedOut,
+		...(error.elapsedMs === null ? {} : { elapsedMs: error.elapsedMs }),
+		...(error.timeoutMs === null ? {} : { timeoutMs: error.timeoutMs }),
+	};
+	if (
+		error.kind === OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.TIMED_OUT
+		&& error.elapsedMs !== null
+		&& error.timeoutMs !== null
+	) {
+		return new ReviewHostRelayError(
+			REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT,
+			"pi",
+			reviewHostRelayPiTimeoutMessage(error.elapsedMs, error.timeoutMs, promptByteLength),
+			{ ...details, timedOut: true, elapsedMs: error.elapsedMs, timeoutMs: error.timeoutMs },
+		);
+	}
+	if (error.kind === OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.EMPTY_OUTPUT) {
+		return new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_EMPTY_OUTPUT, "pi", "pi subprocess produced no output bytes", details);
+	}
+	if (
+		error.kind === OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.LAUNCH_FAILED
+		|| error.kind === OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.SCRATCH_FAILED
+	) {
+		return new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_LAUNCH_FAILED, "pi", `pi subprocess could not start: ${error.message}`, details);
+	}
+	return new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_FAILED, "pi", "pi subprocess failed", details);
+}
+
 function assertTokens(name: string, tokens: readonly string[]): void {
 	if (tokens.length === 0) throw new TypeError(`Pi host relay requires the provider-issued ${name} tokens`);
 	if (tokens.some((token) => typeof token !== "string" || token.length === 0)) {
@@ -323,38 +454,54 @@ function assertTokens(name: string, tokens: readonly string[]): void {
 	}
 }
 
+function snapshotReviewHostRelayRequest(request: ReviewHostRelayRequest): ReviewHostRelayRequest {
+	assertTokens("capture", request.captureArgumentTokens);
+	// The completing form is validated before any process launches: a materialize
+	// slot without a provider-owned submission is a typed contract mismatch,
+	// never a synthesized invocation.
+	resolveReviewHostRelaySubmission(request.submission);
+	const gentleAiExecutable = request.gentleAiExecutable ?? resolveGentleAiBinary();
+	if (!isAbsolute(gentleAiExecutable)) throw new TypeError("Pi host relay requires an absolute gentle-ai executable path");
+	const environment = Object.freeze({ ...(request.environment ?? process.env) }) as NodeJS.ProcessEnv;
+	const submission = request.submission === undefined ? undefined : Object.freeze({
+		operationToken: request.submission.operationToken,
+		argumentTokens: Object.freeze([...request.submission.argumentTokens]),
+		values: Object.freeze(request.submission.values.map((value) => Object.freeze({ ...value }))),
+	});
+	return Object.freeze({
+		...request,
+		captureArgumentTokens: Object.freeze([...request.captureArgumentTokens]),
+		...(submission === undefined ? {} : { submission }),
+		gentleAiExecutable,
+		environment,
+		gentleAiTimeoutMs: request.gentleAiTimeoutMs ?? DEFAULT_GENTLE_AI_TIMEOUT_MS,
+		targetCwd: request.targetCwd ?? process.cwd(),
+	});
+}
+
 /**
- * Runs one complete host-relay capture for one provider-bound slot:
- * materialize → fresh locked-down pi subprocess → submit. Throws a typed
- * {@link ReviewHostRelayError} on every failure leg and submits nothing after
- * a failure; the caller re-queries negotiated STATUS instead of retrying.
+ * Materializes one provider-bound reviewer prompt and runs its opaque Pi
+ * subprocess. It does not submit anything, so independent reviewer work can
+ * finish before the caller performs provider-ordered admission.
  */
-export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): Promise<ReviewHostRelayResult> {
-	assertTokens("capture", request.captureArgumentTokens);
-	// The completing form is validated before any process launches: a
-	// materialize slot without a provider-owned submission is a typed
-	// contract mismatch, never a synthesized invocation.
-	const submissionBinding = resolveReviewHostRelaySubmission(request.submission);
-	const gentleAi = request.gentleAiExecutable ?? resolveGentleAiBinary();
-	if (!isAbsolute(gentleAi)) throw new TypeError("Pi host relay requires an absolute gentle-ai executable path");
-	const baseEnvironment = request.environment ?? process.env;
-	// Every gentle-ai invocation the relay makes carries the handshake; the
-	// pi subprocess environment stays exactly as the user configured it.
-	const gentleAiEnvironment = { ...baseEnvironment, [GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV]: GENTLE_PI_REVIEW_RELAY_CONTRACT };
-	const gentleAiTimeoutMs = request.gentleAiTimeoutMs ?? DEFAULT_GENTLE_AI_TIMEOUT_MS;
-	const piTimeoutMs = request.piTimeoutMs ?? DEFAULT_PI_TIMEOUT_MS;
-
-	// (a) Materialize the Go-issued opaque prompt. This invocation is also the
-	// capability detection: an old binary's unknown-flag refusal proves the
-	// relay surface is absent, and the provider's handshake refusal surfaces
-	// verbatim. No version sniffing.
+export async function prepareReviewHostRelaySlot(
+	request: ReviewHostRelayRequest,
+	reviewer: typeof runOpaquePiReviewer = runOpaquePiReviewer,
+): Promise<ReviewHostRelayPreparedResult> {
+	// Copy mutable transport configuration before the first async boundary. The
+	// supplied AbortSignal intentionally stays live across materialize, reviewer,
+	// and submit, preserving the established cancellation behavior.
+	const preparedRequest = snapshotReviewHostRelayRequest(request);
+
+	// The provider materializes the opaque prompt and detects whether this relay
+	// surface is available. No version sniffing or prompt reconstruction occurs.
 	let materialized: ProcessCapture;
 	try {
-		materialized = await collectProcess(gentleAi, ["review", "capture-result", ...request.captureArgumentTokens], {
-			cwd: process.cwd(),
-			env: gentleAiEnvironment,
-			timeoutMs: gentleAiTimeoutMs,
-			...(request.signal === undefined ? {} : { signal: request.signal }),
+		materialized = await collectGentleAiProcess(preparedRequest.gentleAiExecutable!, ["review", "capture-result", ...preparedRequest.captureArgumentTokens], {
+			cwd: preparedRequest.targetCwd!,
+			env: { ...preparedRequest.environment!, [GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV]: GENTLE_PI_REVIEW_RELAY_CONTRACT },
+			timeoutMs: preparedRequest.gentleAiTimeoutMs!,
+			...(preparedRequest.signal === undefined ? {} : { signal: preparedRequest.signal }),
 		});
 	} catch (error) {
 		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.MATERIALIZE_FAILED, "materialize", `gentle-ai prompt materialization could not start: ${error instanceof Error ? error.message : String(error)}`);
@@ -362,75 +509,156 @@ export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): P
 	if (materialized.exitCode !== 0 || materialized.timedOut) {
 		const stderr = materialized.stderr.toString("utf8");
 		const refusal = classifyReviewHostRelayRefusal(stderr);
+		const timing = { elapsedMs: materialized.elapsedMs, timeoutMs: preparedRequest.gentleAiTimeoutMs! };
 		if (refusal === "unknown-flag") {
-			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.RELAY_UNAVAILABLE, "materialize", REVIEW_HOST_RELAY_UNAVAILABLE_MESSAGE, { exitCode: materialized.exitCode, stderr, timedOut: materialized.timedOut });
+			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.RELAY_UNAVAILABLE, "materialize", REVIEW_HOST_RELAY_UNAVAILABLE_MESSAGE, {
+				exitCode: materialized.exitCode,
+				stderr,
+				timedOut: materialized.timedOut,
+				...timing,
+			});
 		}
 		if (refusal === "handshake") {
-			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.HANDSHAKE_REFUSED, "materialize", stderr, { exitCode: materialized.exitCode, stderr, timedOut: materialized.timedOut });
+			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.HANDSHAKE_REFUSED, "materialize", stderr, {
+				exitCode: materialized.exitCode,
+				stderr,
+				timedOut: materialized.timedOut,
+				...timing,
+			});
 		}
-		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.MATERIALIZE_FAILED, "materialize", "gentle-ai prompt materialization failed", { exitCode: materialized.exitCode, stderr, timedOut: materialized.timedOut });
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.MATERIALIZE_FAILED, "materialize", materialized.timedOut
+			? `gentle-ai prompt materialization exceeded its ${preparedRequest.gentleAiTimeoutMs!}ms bound after ${materialized.elapsedMs}ms`
+			: "gentle-ai prompt materialization failed", { exitCode: materialized.exitCode, stderr, timedOut: materialized.timedOut, ...timing });
 	}
 	const promptBytes = materialized.stdout;
 	if (promptBytes.length === 0) {
-		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.EMPTY_PROMPT, "materialize", "gentle-ai prompt materialization produced no bytes", { exitCode: 0, stderr: materialized.stderr.toString("utf8") });
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.EMPTY_PROMPT, "materialize", "gentle-ai prompt materialization produced no bytes", {
+			exitCode: 0,
+			stderr: materialized.stderr.toString("utf8"),
+			elapsedMs: materialized.elapsedMs,
+			timeoutMs: preparedRequest.gentleAiTimeoutMs!,
+		});
+	}
+	// The reviewer bound is derived from the prompt the provider actually
+	// materialized. The explicit request timeout is a test seam that wins over
+	// both the user-owned environment override and the scale-derived bound.
+	const piTimeoutMs = preparedRequest.piTimeoutMs ?? resolveReviewHostRelayPiTimeoutMs(promptBytes.length, preparedRequest.environment);
+
+	// The pure adapter owns the fresh isolated Pi process. Its input and output
+	// are opaque bytes; this coordinator only maps transport failures.
+	let piResult: OpaquePiReviewerResult;
+	try {
+		piResult = await reviewer(promptBytes, {
+			...(preparedRequest.piExecutable === undefined ? {} : { piExecutable: preparedRequest.piExecutable }),
+			environment: preparedRequest.environment,
+			timeoutMs: piTimeoutMs,
+			...(preparedRequest.signal === undefined ? {} : { signal: preparedRequest.signal }),
+		});
+	} catch (error) {
+		throw relayPiTransportError(error, promptBytes.length, piTimeoutMs);
+	}
+	const prepared = Object.freeze({
+		request: preparedRequest,
+		promptByteLength: promptBytes.length,
+		resultByteLength: piResult.stdoutByteLength,
+	});
+	preparedResultBytes.set(prepared, Buffer.from(piResult.stdout));
+	return prepared;
+}
+
+/**
+ * Starts every reviewer before awaiting any result. If one or more reviewers
+ * fail, it rejects only after every started transport has settled and reports
+ * the earliest failed request in provider order.
+ */
+export async function runReviewHostRelayReviewerGroup(
+	requests: readonly ReviewHostRelayRequest[],
+	prepare: ReviewHostRelayPreparationRunner = prepareReviewHostRelaySlot,
+): Promise<readonly ReviewHostRelayPreparedResult[]> {
+	if (requests.length === 0) {
+		throw new TypeError("Pi host relay reviewer group requires at least one provider-bound request");
 	}
+	const settled = await Promise.allSettled(requests.map(async (request) => await prepare(request)));
+	const failed = settled.find((result) => result.status === "rejected");
+	if (failed?.status === "rejected") throw failed.reason;
+	return settled.map((result) => (result as PromiseFulfilledResult<ReviewHostRelayPreparedResult>).value);
+}
 
-	// (b)/(c) Fresh locked-down pi subprocess in an empty scratch directory.
-	const scratchDirectory = await mkdtemp(join(tmpdir(), "gentle-pi-host-relay-scratch-"));
+/**
+ * Submits one already-reviewed opaque result through the exact provider-owned
+ * completing form. Only the provider-declared artifact slot is substituted.
+ */
+export async function submitReviewHostRelayPreparedResult(prepared: ReviewHostRelayPreparedResult): Promise<ReviewHostRelayResult> {
+	const resultBytes = preparedResultBytes.get(prepared);
+	if (resultBytes === undefined) throw new TypeError("Pi host relay requires a recognized prepared result");
+	const { request } = prepared;
+	assertTokens("capture", request.captureArgumentTokens);
+	const submissionBinding = resolveReviewHostRelaySubmission(request.submission);
 	const stagingDirectory = await mkdtemp(join(tmpdir(), "gentle-pi-host-relay-result-"));
+	let primaryFailure = false;
 	try {
-		await chmod(scratchDirectory, 0o700);
 		await chmod(stagingDirectory, 0o700);
-		let piRun: ProcessCapture;
-		try {
-			piRun = await collectProcess(request.piExecutable ?? "pi", REVIEW_HOST_RELAY_PI_ARGV, {
-				cwd: scratchDirectory,
-				env: baseEnvironment,
-				stdin: promptBytes,
-				timeoutMs: piTimeoutMs,
-				...(request.signal === undefined ? {} : { signal: request.signal }),
-			});
-		} catch (error) {
-			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_LAUNCH_FAILED, "pi", `pi subprocess could not start: ${error instanceof Error ? error.message : String(error)}`);
-		}
-		if (piRun.exitCode !== 0 || piRun.timedOut) {
-			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_FAILED, "pi", "pi subprocess failed", { exitCode: piRun.exitCode, stderr: piRun.stderr.toString("utf8"), timedOut: piRun.timedOut });
-		}
-		const resultBytes = piRun.stdout;
-		if (resultBytes.length === 0) {
-			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_EMPTY_OUTPUT, "pi", "pi subprocess produced no output bytes", { exitCode: 0, stderr: piRun.stderr.toString("utf8") });
-		}
-
-		// (d) Submit the raw final bytes untouched through the provider-owned
-		// completing form: its exact operation and argument tokens, with only
-		// the artifact path substituted into the declared {{value}} slot.
 		const resultFile = join(stagingDirectory, "result.raw");
 		await writeFile(resultFile, resultBytes, { mode: 0o600 });
 		await chmod(resultFile, 0o600);
 		const submitTokens = submissionBinding.argumentTokens.map((token, index) =>
-			index === submissionBinding.substitutionLocation ? token.split(REVIEW_HOST_RELAY_SUBMISSION_VALUE_SLOT).join(resultFile) : token,
+			index === submissionBinding.substitutionLocation
+				? token.split(REVIEW_HOST_RELAY_SUBMISSION_VALUE_SLOT).join(resultFile)
+				: token,
 		);
 		let submission: ProcessCapture;
 		try {
-			submission = await collectProcess(gentleAi, ["review", submissionBinding.operationToken, ...submitTokens], {
-				cwd: process.cwd(),
-				env: gentleAiEnvironment,
-				timeoutMs: gentleAiTimeoutMs,
+			submission = await collectGentleAiProcess(request.gentleAiExecutable!, ["review", submissionBinding.operationToken, ...submitTokens], {
+				cwd: request.targetCwd!,
+				env: { ...request.environment!, [GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV]: GENTLE_PI_REVIEW_RELAY_CONTRACT },
+				timeoutMs: request.gentleAiTimeoutMs!,
 				...(request.signal === undefined ? {} : { signal: request.signal }),
 			});
 		} catch (error) {
 			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit", `gentle-ai capture submission could not start: ${error instanceof Error ? error.message : String(error)}`);
 		}
 		if (submission.exitCode !== 0 || submission.timedOut || submission.stdout.length === 0) {
-			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit", "gentle-ai refused the relayed capture submission", { exitCode: submission.exitCode, stderr: submission.stderr.toString("utf8"), timedOut: submission.timedOut });
+			const stderr = submission.stderr.toString("utf8");
+			const details = { exitCode: submission.exitCode, stderr, timedOut: submission.timedOut, elapsedMs: submission.elapsedMs, timeoutMs: request.gentleAiTimeoutMs! };
+			// A typed admission refusal proves the provider consumed no slot.
+			// Every other launched submission stays unknown pending fresh STATUS.
+			if (isReviewHostRelayAdmissionRefusal(submission, stderr)) {
+				throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit", stderr.trim(), {
+					...details,
+					mutationOutcome: "none",
+				});
+			}
+			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit", submission.timedOut
+				? `gentle-ai capture submission exceeded its ${request.gentleAiTimeoutMs!}ms bound after ${submission.elapsedMs}ms`
+				: "gentle-ai refused the relayed capture submission", details);
 		}
 		return {
-			promptByteLength: promptBytes.length,
-			resultByteLength: resultBytes.length,
+			promptByteLength: prepared.promptByteLength,
+			resultByteLength: prepared.resultByteLength,
 			submission: submission.stdout.toString("utf8"),
 		};
+	} catch (error) {
+		primaryFailure = true;
+		throw error;
 	} finally {
-		await rm(scratchDirectory, { recursive: true, force: true }).catch(() => undefined);
-		await rm(stagingDirectory, { recursive: true, force: true }).catch(() => undefined);
+		try {
+			await rm(stagingDirectory, { recursive: true, force: true });
+		} catch (error) {
+			if (!primaryFailure) {
+				throw new ReviewHostRelayError(
+					REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED,
+					"submit",
+					`Pi host relay result staging cleanup failed: ${error instanceof Error ? error.message : String(error)}`,
+				);
+			}
+		}
 	}
 }
+
+/**
+ * Compatibility one-binding path: materialize → opaque Pi adapter → submit.
+ * It preserves the established API and its typed failure behavior exactly.
+ */
+export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): Promise<ReviewHostRelayResult> {
+	return await submitReviewHostRelayPreparedResult(await prepareReviewHostRelaySlot(request));
+}