gentle-pi 2.2.0 → 2.3.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;
 }
@@ -259,21 +287,73 @@ export interface ReviewHostRelayResult {
 export type ReviewHostRelayRunner = (request: ReviewHostRelayRequest) => 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 +385,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 +396,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)) {
@@ -325,7 +444,7 @@ function assertTokens(name: string, tokens: readonly string[]): void {
 
 /**
  * Runs one complete host-relay capture for one provider-bound slot:
- * materialize → fresh locked-down pi subprocess → submit. Throws a typed
+ * materialize → opaque Pi adapter → 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.
  */
@@ -342,7 +461,7 @@ export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): P
 	// 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;
+	const targetCwd = request.targetCwd ?? process.cwd();
 
 	// (a) Materialize the Go-issued opaque prompt. This invocation is also the
 	// capability detection: an old binary's unknown-flag refusal proves the
@@ -350,8 +469,8 @@ export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): P
 	// verbatim. No version sniffing.
 	let materialized: ProcessCapture;
 	try {
-		materialized = await collectProcess(gentleAi, ["review", "capture-result", ...request.captureArgumentTokens], {
-			cwd: process.cwd(),
+		materialized = await collectGentleAiProcess(gentleAi, ["review", "capture-result", ...request.captureArgumentTokens], {
+			cwd: targetCwd,
 			env: gentleAiEnvironment,
 			timeoutMs: gentleAiTimeoutMs,
 			...(request.signal === undefined ? {} : { signal: request.signal }),
@@ -362,48 +481,49 @@ 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: 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 ${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: gentleAiTimeoutMs });
 	}
+	// The reviewer bound is derived from the prompt the provider actually
+	// materialized, so it can only be resolved here. An explicit request
+	// timeout (the test seam) still wins over both the override and the scale.
+	const piTimeoutMs = request.piTimeoutMs ?? resolveReviewHostRelayPiTimeoutMs(promptBytes.length, baseEnvironment);
+
+	// (b) The pure adapter owns the fresh isolated Pi process. Its input and
+	// output are opaque bytes; this coordinator only maps transport failures to
+	// the established relay boundary.
+	let piResult: OpaquePiReviewerResult;
+	try {
+		piResult = await runOpaquePiReviewer(promptBytes, {
+			...(request.piExecutable === undefined ? {} : { piExecutable: request.piExecutable }),
+			environment: baseEnvironment,
+			timeoutMs: piTimeoutMs,
+			...(request.signal === undefined ? {} : { signal: request.signal }),
+		});
+	} catch (error) {
+		throw relayPiTransportError(error, promptBytes.length, piTimeoutMs);
+	}
+	const resultBytes = piResult.stdout;
 
-	// (b)/(c) Fresh locked-down pi subprocess in an empty scratch directory.
-	const scratchDirectory = await mkdtemp(join(tmpdir(), "gentle-pi-host-relay-scratch-"));
+	// (c) 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 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);
@@ -412,8 +532,8 @@ export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): P
 		);
 		let submission: ProcessCapture;
 		try {
-			submission = await collectProcess(gentleAi, ["review", submissionBinding.operationToken, ...submitTokens], {
-				cwd: process.cwd(),
+			submission = await collectGentleAiProcess(gentleAi, ["review", submissionBinding.operationToken, ...submitTokens], {
+				cwd: targetCwd,
 				env: gentleAiEnvironment,
 				timeoutMs: gentleAiTimeoutMs,
 				...(request.signal === undefined ? {} : { signal: request.signal }),
@@ -422,15 +542,37 @@ export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): P
 			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: gentleAiTimeoutMs };
+			// A typed admission refusal is a proven non-mutation whose reason is
+			// the refusal text itself; everything else that launched (timeout,
+			// signal, untyped exit) stays unknown pending 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 ${gentleAiTimeoutMs}ms bound after ${submission.elapsedMs}ms`
+				: "gentle-ai refused the relayed capture submission", details);
 		}
 		return {
 			promptByteLength: promptBytes.length,
-			resultByteLength: resultBytes.length,
+			resultByteLength: piResult.stdoutByteLength,
 			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)}`,
+				);
+			}
+		}
 	}
 }