gentle-pi 2.5.0 → 2.6.0

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

@@ -72,6 +72,21 @@ function relayCollectInput(lineageId, lens, order) {
 			{ name: "agent", value: "pi", token: "--agent=pi" },
 			{ name: "materialize", value: "true", token: "--materialize=true" },
 		],
+		// gentle-pi#638: the artifact subject is what makes the slot declarable —
+		// its subject_hash is the --request-hash the capture-unachievable verb
+		// binds to. A slot without one cannot be declared, only retried.
+		artifactSubject: {
+			schema: "gentle-ai.review-artifact-subject/v2",
+			subjectHash: `sha256:${String(order).repeat(64)}`,
+			lineageId,
+			authorityRevision: SHA,
+			targetIdentity: SHA,
+			baseTree: TREE,
+			candidateTree: TREE,
+			changedPathManifestSha256: SHA,
+			lens,
+			selectedOrder: order,
+		},
 		submission: providerSubmission(lineageId, lens, order),
 	};
 }
@@ -146,6 +161,7 @@ const { ReviewHostRelayError, REVIEW_HOST_RELAY_FAILURE } = await import(${JSON.
 const statusQueue = JSON.parse(await readFile(statusFile, "utf8"));
 const relayRequests = [];
 const statusCalls = [];
+const unachievableCalls = [];
 let captureCalls = 0;
 
 __testing.setReviewHostRelayRunnerForTesting(async (request) => {
@@ -156,6 +172,9 @@ __testing.setReviewHostRelayRunnerForTesting(async (request) => {
 	if (mode === "capture-fail") {
 		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_FAILED, "pi", "pi subprocess failed", { exitCode: 4 });
 	}
+	if (mode === "capture-timeout") {
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "pi reviewer subprocess exceeded the relay bound", { exitCode: null, timedOut: true, elapsedMs: 2256004, timeoutMs: 2256000 });
+	}
 	if (mode === "capture-ambiguous") {
 		throw Object.assign(new Error("capture response lost"), { mutationOutcome: "unknown", nextAction: "review.status" });
 	}
@@ -172,6 +191,27 @@ const nativeReviewCli = {
 		if (next === undefined) throw new Error("status queue exhausted");
 		return next;
 	},
+	captureUnachievableLens: async (request) => {
+		unachievableCalls.push({
+			cwd: request.cwd,
+			lineageId: request.lineageId,
+			targetIdentity: request.targetIdentity,
+			expectedRevision: request.expectedRevision,
+			requestHash: request.requestHash,
+			reason: request.reason,
+			...(request.detail === undefined ? {} : { detail: request.detail }),
+			...(request.repositoryContext === undefined ? {} : { repositoryContext: request.repositoryContext }),
+		});
+		return {
+			schema: "gentle-ai.review-capture-unachievable/v1",
+			lineageId: request.lineageId,
+			targetIdentity: request.targetIdentity,
+			lens: ${JSON.stringify(LENS)},
+			selectedOrder: ${JSON.stringify(ORDER)},
+			reason: request.reason,
+			recorded: true,
+		};
+	},
 };
 
 let result;
@@ -199,7 +239,7 @@ try {
 	error = caught instanceof Error ? { name: caught.name, message: caught.message } : String(caught);
 }
 
-await writeFile(outFile, JSON.stringify({ result, inspectResult, captureBinding, error, relayRequests, statusCalls, captureCalls }, null, 2));
+await writeFile(outFile, JSON.stringify({ result, inspectResult, captureBinding, error, relayRequests, statusCalls, captureCalls, unachievableCalls }, null, 2));
 `;
 }
 
@@ -225,6 +265,107 @@ function inspectCollectBinding(inspectResult) {
 const PENDING = collectStatus(LINEAGE, [relayCollectInput(LINEAGE, LENS, ORDER)]);
 const CONVERGED = collectStatus(LINEAGE, []);
 
+// gentle-pi#638: the typed stop the provider renders once the slot is declared
+// unachievable — no collect inputs, one withdraw binding per declared slot.
+// Built in the same plain-object style as collectStatus: typed fields for the
+// controller, raw fields for the envelope passthrough.
+function unachievableStopStatus(lineageId, lens, order) {
+	const subjectHash = `sha256:${String(order).repeat(64)}`;
+	const repositoryContext = `rctx1_${"e".repeat(64)}`;
+	const withdrawArguments = [
+		{ name: "lineage", value: lineageId, token: `--lineage=${lineageId}` },
+		{ name: "expected-revision", value: SHA, token: `--expected-revision=${SHA}` },
+		{ name: "target", value: SHA, token: `--target=${SHA}` },
+		{ name: "repository-context", value: repositoryContext, token: `--repository-context=${repositoryContext}` },
+		{ name: "request-hash", value: subjectHash, token: `--request-hash=${subjectHash}` },
+		{ name: "withdraw", value: "true", token: "--withdraw=true" },
+	];
+	const withdrawCommand = `gentle-ai review capture-unachievable --lineage=${lineageId} --expected-revision=${SHA} --target=${SHA} --repository-context=${repositoryContext} --request-hash=${subjectHash} --withdraw=true`;
+	return {
+		...collectStatus(lineageId, []),
+		nextTransition: {
+			kind: "stop",
+			reasonCode: "unachievable_lens_slot",
+			unachievableLensSlots: [
+				{
+					lens,
+					selectedOrder: order,
+					subjectHash,
+					reason: "relay_transport_bound_exceeded",
+					withdraw: {
+						operation: "review.capture-unachievable",
+						command: withdrawCommand,
+						arguments: withdrawArguments,
+						binding: { targetIdentity: SHA, lineageId, revision: SHA },
+					},
+				},
+			],
+		},
+		raw: {
+			schema: "gentle-ai.review-integration.status/v5",
+			action: "stop",
+			lineage_id: lineageId,
+			target_identity: SHA,
+			next_transition: {
+				kind: "stop",
+				reason_code: "unachievable_lens_slot",
+				unachievable_lens_slots: [
+					{
+						lens,
+						selected_order: order,
+						subject_hash: subjectHash,
+						reason: "relay_transport_bound_exceeded",
+						withdraw: {
+							operation: "review.capture-unachievable",
+							command: withdrawCommand,
+							arguments: withdrawArguments,
+							binding: { lineage_id: lineageId, revision: SHA, target_identity: SHA, repository_context: repositoryContext },
+						},
+					},
+				],
+			},
+		},
+	};
+}
+const UNACHIEVABLE_STOP = unachievableStopStatus(LINEAGE, LENS, ORDER);
+
+// gentle-pi#638: the declared slot must not survive the restart as a reoffer.
+// Process A declares after the deterministic bound kill; fresh Process B sees
+// the provider's typed stop with the withdraw hint instead of the public
+// collectBinding it would have seen before the declaration.
+test("an unachievable declaration survives the controller restart as a typed stop, not a reoffer", async (t) => {
+	const cwd = repository(t);
+
+	// Process A: the deterministic relay bound kills the reviewer; the capture
+	// path declares the slot unachievable and renders the provider's stop. The
+	// worker always runs INSPECT first, so the queue carries the pending collect
+	// twice (inspect + capture selection) before the post-declaration stop.
+	const declared = runWorker(t, cwd, [PENDING, PENDING, UNACHIEVABLE_STOP], "capture-timeout");
+	assert.equal(declared.error, undefined, `declared run threw: ${JSON.stringify(declared.error)}`);
+	assert.equal(declared.captureCalls, 1, "Process A invokes one capture");
+	assert.equal(declared.relayRequests.length, 1, "Process A launches one relay transport");
+	assert.equal(declared.unachievableCalls.length, 1, "the declaration is recorded exactly once");
+	assert.deepEqual(declared.unachievableCalls, [{ cwd, lineageId: LINEAGE, targetIdentity: SHA, expectedRevision: SHA, requestHash: `sha256:${String(ORDER).repeat(64)}`, reason: "relay_transport_bound_exceeded", detail: "killed after 2256004ms against a 2256000ms relay bound", repositoryContext: `rctx1_${"e".repeat(64)}` }]);
+	assert.equal(declared.statusCalls.length, 3, "inspect and selection STATUS plus exactly one bound re-query");
+	assert.equal(declared.result.tool, "gentle_review_capture");
+	assert.equal(declared.result.status, "blocked");
+	assert.equal(declared.result.outcome, "unachievable-lens-slot-declared");
+	assert.equal(declared.result.mutation_performed, true);
+	assert.match(String(declared.result.next_action), /withdraw/);
+
+	// Process B (fresh): the provider's STATUS no longer reoffers the binding;
+	// INSPECT renders the typed stop whose hint is the withdraw command.
+	const inspect = runWorker(t, cwd, [UNACHIEVABLE_STOP], "inspect");
+	assert.equal(inspect.error, undefined, `inspect run threw: ${JSON.stringify(inspect.error)}`);
+	assert.equal(inspect.captureCalls, 0, "no capture runs without a reoffered binding");
+	assert.equal(inspect.relayRequests.length, 0, "INSPECT never launches the relay");
+	assert.equal(inspect.unachievableCalls.length, 0, "INSPECT never declares");
+	assert.equal(inspectCollectBinding(inspect.result), undefined, "the declared slot is not reoffered after restart");
+	assert.equal(inspect.result.status, "blocked");
+	assert.match(String(inspect.result.hint), /capture-unachievable/);
+	assert.match(String(inspect.result.hint), /--withdraw=true/);
+});
+
 test("a fresh controller process reoffers the exact public binding before one capture closes", async (t) => {
 	const cwd = repository(t);
 

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

@@ -1,13 +1,13 @@
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, realpathSync, 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 type { NativeReviewCli, NativeReviewUnachievableLensCaptureArtifact, NativeReviewUnachievableLensCaptureRequest } 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 { decodeReviewStatusV3, type ReviewArtifactSubjectV2, type ReviewCaptureSubmissionV1, type ReviewCollectInputV3, type ReviewStatusV3 } from "../lib/review-integration-v2.ts";
+import { decodeReviewNextTransitionV3, 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
@@ -158,13 +158,18 @@ function providerRefuterRequiredStatus(lineageId: string): ReviewStatusV3 {
 interface RoutingHarness {
 	statusQueue: ReviewStatusV3[];
 	statusCalls: Array<{ cwd: string; lineageId?: string; agent?: "pi" }>;
+	unachievableCalls: NativeReviewUnachievableLensCaptureRequest[];
 	native: NativeReviewCli;
 }
 
-function nativeHarness(statuses: readonly ReviewStatusV3[]): RoutingHarness {
+type UnachievableResponder = (request: NativeReviewUnachievableLensCaptureRequest) => Promise<NativeReviewUnachievableLensCaptureArtifact>;
+
+// The declaration verb stays OPT-IN: an absent captureUnachievableLens is the invocation-adjacent capability gate, so every pre-existing failure test keeps its exact envelope through the unchanged fall-back.
+function nativeHarness(statuses: readonly ReviewStatusV3[], unachievableResponder?: UnachievableResponder): RoutingHarness {
 	const harness: RoutingHarness = {
 		statusQueue: [...statuses],
 		statusCalls: [],
+		unachievableCalls: [],
 		native: undefined as unknown as NativeReviewCli,
 	};
 	harness.native = {
@@ -174,6 +179,7 @@ function nativeHarness(statuses: readonly ReviewStatusV3[]): RoutingHarness {
 			if (next === undefined) throw new Error("status queue exhausted");
 			return next;
 		},
+		...(unachievableResponder === undefined ? {} : { captureUnachievableLens: async (request: NativeReviewUnachievableLensCaptureRequest) => { harness.unachievableCalls.push(request); return await unachievableResponder(request); } }),
 	};
 	return harness;
 }
@@ -506,6 +512,360 @@ test("a relay timeout reports its one-slot measurements and no auto-follow", asy
 	assert.equal(harness.statusCalls.length, 1);
 });
 
+// gentle-pi#638: the typed stop a provider renders after a host declared a
+// slot unachievable, built through the production decoder so the routing
+// tests exercise the same typed shape the extension consumes.
+function unachievableStopStatus(lineageId: string, lens: ReviewArtifactSubjectV2["lens"], order: number, reason = "relay_transport_bound_exceeded"): ReviewStatusV3 {
+	const subjectHash = `sha256:${String(order).repeat(64)}`;
+	const repositoryContext = `rctx1_${"e".repeat(64)}`;
+	const rawTransition = {
+		kind: "stop",
+		reason_code: "unachievable_lens_slot",
+		unachievable_lens_slots: [
+			{
+				lens,
+				selected_order: order,
+				subject_hash: subjectHash,
+				reason,
+				withdraw: {
+					operation: "review.capture-unachievable",
+					command: `gentle-ai review capture-unachievable --lineage=${lineageId} --expected-revision=${SHA} --target=${SHA} --repository-context=${repositoryContext} --request-hash=${subjectHash} --withdraw=true`,
+					arguments: [
+						{ name: "lineage", value: lineageId, token: `--lineage=${lineageId}` },
+						{ name: "expected-revision", value: SHA, token: `--expected-revision=${SHA}` },
+						{ name: "target", value: SHA, token: `--target=${SHA}` },
+						{ name: "repository-context", value: repositoryContext, token: `--repository-context=${repositoryContext}` },
+						{ name: "request-hash", value: subjectHash, token: `--request-hash=${subjectHash}` },
+						{ name: "withdraw", value: "true", token: "--withdraw=true" },
+					],
+					binding: { lineage_id: lineageId, revision: SHA, target_identity: SHA, repository_context: repositoryContext },
+				},
+			},
+		],
+	};
+	return {
+		...finalizeStatus(lineageId),
+		nextTransition: decodeReviewNextTransitionV3(rawTransition),
+		raw: { schema: "gentle-ai.review-integration.status/v5", action: "stop", lineage_id: lineageId, target_identity: SHA, next_transition: rawTransition },
+	} as unknown as ReviewStatusV3;
+}
+
+function unachievableArtifact(lineageId: string, lens: ReviewArtifactSubjectV2["lens"], order: number, reason = "relay_transport_bound_exceeded"): NativeReviewUnachievableLensCaptureArtifact {
+	return { schema: "gentle-ai.review-capture-unachievable/v1", lineageId, targetIdentity: SHA, lens, selectedOrder: order, reason, recorded: true };
+}
+
+// gentle-pi#638: a deterministic pi timeout is declared unachievable through
+// the native verb, and one bound STATUS re-query renders the typed stop with
+// its withdraw binding instead of reoffering the same slot.
+test("a deterministic pi timeout declares the slot unachievable and renders the typed stop", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "relay-lineage";
+	const input = relayCollectInput(lineageId, "review-risk", 0);
+	const stop = unachievableStopStatus(lineageId, "review-risk", 0);
+	const harness = nativeHarness([finalizeStatus(lineageId, [input]), stop], () => Promise.resolve(unachievableArtifact(lineageId, "review-risk", 0)));
+	__testing.setReviewHostRelayRunnerForTesting(async () => {
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "pi reviewer subprocess exceeded the relay bound", { exitCode: null, timedOut: true, elapsedMs: 2_256_004, timeoutMs: 2_256_000 });
+	});
+
+	const result = await runCapture(cwd, harness, lineageId);
+
+	assert.equal(result.status, "blocked");
+	assert.equal(result.outcome, "unachievable-lens-slot-declared");
+	assert.deepEqual(result.failure, { kind: "pi-timed-out", stage: "pi", exit_code: null, timed_out: true, elapsed_ms: 2_256_004, timeout_ms: 2_256_000 });
+	assert.deepEqual(harness.unachievableCalls, [{ cwd: realpathSync(cwd), lineageId, targetIdentity: SHA, expectedRevision: SHA, requestHash: `sha256:${"0".repeat(64)}`, reason: "relay_transport_bound_exceeded", detail: "killed after 2256004ms against a 2256000ms relay bound", repositoryContext: `rctx1_${"e".repeat(64)}` }]);
+	assert.deepEqual(result.declaration, { lens: "review-risk", selected_order: 0, subject_hash: `sha256:${"0".repeat(64)}`, reason: "relay_transport_bound_exceeded" });
+	assert.deepEqual(result.result, stop.raw);
+	const slots = result.unachievable_lens_slots as Array<{ lens: string; subject_hash: string; withdraw: string }>;
+	assert.equal(slots.length, 1);
+	assert.equal(slots[0]!.lens, "review-risk");
+	assert.equal(slots[0]!.subject_hash, `sha256:${"0".repeat(64)}`);
+	assert.match(slots[0]!.withdraw, /capture-unachievable.*--withdraw=true/);
+	assert.match(String(result.next_action), /withdraw/);
+	assert.equal(result.mutation_performed, true);
+	// gentle-pi#822: the native declaration was recorded, so the flow reports the mutation as committed, not none.
+	assert.equal(result.mutation_outcome, "committed");
+	assert.equal(harness.statusCalls.length, 2, "one selection STATUS plus exactly one bound re-query");
+	assert.equal(harness.statusCalls.at(-1)?.agent, "pi", "the bound re-query preserves the Pi host runtime");
+});
+
+// gentle-pi#638: generic admission rejections describe the submitted reviewer
+// bytes, not a deterministic failure of the provider-bound slot. A fresh
+// reviewer can repair malformed JSON or a binding mismatch, so both retain the
+// ordinary exact-reoffer path and must never declare the slot unachievable.
+test("repairable submission refusals retain the exact-slot retry path", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "relay-lineage";
+	for (const refusal of [
+		"Error: reviewer payload contains no complete JSON object [invalid_request]\n",
+		"Error: reviewer artifact admission binding_mismatch [invalid_request]\n",
+	]) {
+		const input = relayCollectInput(lineageId, "review-reliability", 0);
+		const harness = nativeHarness([finalizeStatus(lineageId, [input])], async () => {
+			throw new Error("a repairable refusal must not call capture-unachievable");
+		});
+		__testing.setReviewHostRelayRunnerForTesting(async () => {
+			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit", refusal.trim(), { exitCode: 1, stderr: refusal, mutationOutcome: "none" });
+		});
+
+		const result = await runCapture(cwd, harness, lineageId);
+
+		assert.equal(result.outcome, "pi-host-relay-transport-failure");
+		assert.equal(result.mutation_performed, false);
+		assert.equal(result.mutation_outcome, "none");
+		assert.match(String(result.next_action), /fresh STATUS/);
+		assert.deepEqual(harness.unachievableCalls, []);
+		assert.equal(harness.statusCalls.length, 1, "a repairable non-mutation needs no reconciliation before the provider reoffers it");
+	}
+});
+
+// gentle-pi#822: a stop carrying slots that do not match the identity this
+// session declared is a reconciliation failure — never a success rendering
+// someone else's withdraw command.
+test("a stop whose slots do not match the declared identity reports a reconciliation failure", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "relay-lineage";
+	const input = relayCollectInput(lineageId, "review-risk", 0);
+	const foreignStop = unachievableStopStatus(lineageId, "review-risk", 1);
+	const harness = nativeHarness([finalizeStatus(lineageId, [input]), foreignStop], () => Promise.resolve(unachievableArtifact(lineageId, "review-risk", 0)));
+	__testing.setReviewHostRelayRunnerForTesting(async () => {
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "pi reviewer subprocess exceeded the relay bound", { exitCode: null, timedOut: true, elapsedMs: 2_256_004, timeoutMs: 2_256_000 });
+	});
+
+	const result = await runCapture(cwd, harness, lineageId);
+
+	assert.equal(result.status, "blocked");
+	assert.equal(result.outcome, "unachievable-lens-declaration-reconciliation-failed");
+	assert.deepEqual(result.declaration, { lens: "review-risk", selected_order: 0, subject_hash: `sha256:${"0".repeat(64)}`, reason: "relay_transport_bound_exceeded" });
+	assert.equal(result.unachievable_lens_slots, undefined, "a foreign slot is never exposed as this session's withdraw command");
+	const reconciliationFailure = result.reconciliation_failure as { outcome?: string; reason?: string } | undefined;
+	assert.equal(reconciliationFailure?.outcome, "unachievable-lens-slot-declaration-unmatched");
+	assert.match(String(reconciliationFailure?.reason), /no unachievable_lens_slots entry matches the declared slot identity/);
+	assert.equal(result.mutation_performed, true);
+	assert.equal(result.mutation_outcome, "committed");
+	assert.match(String(result.next_action), /refused the unachievable declaration/);
+	assert.equal(harness.statusCalls.length, 2, "the bound re-query still runs exactly once");
+});
+
+// gentle-pi#822: with several declared entries on the stop, only the matching
+// identity is exposed — never the withdraw commands of other runs.
+test("a stop carrying several declared slots exposes only the one this session declared", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "relay-lineage";
+	const input = relayCollectInput(lineageId, "review-risk", 0);
+	const stop = unachievableStopStatus(lineageId, "review-risk", 0);
+	const foreign = unachievableStopStatus(lineageId, "review-reliability", 2).nextTransition?.unachievableLensSlots?.[0];
+	assert.ok(foreign !== undefined);
+	stop.nextTransition = { ...stop.nextTransition!, unachievableLensSlots: [...stop.nextTransition!.unachievableLensSlots!, foreign] };
+	const harness = nativeHarness([finalizeStatus(lineageId, [input]), stop], () => Promise.resolve(unachievableArtifact(lineageId, "review-risk", 0)));
+	__testing.setReviewHostRelayRunnerForTesting(async () => {
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "pi reviewer subprocess exceeded the relay bound", { exitCode: null, timedOut: true, elapsedMs: 2_256_004, timeoutMs: 2_256_000 });
+	});
+
+	const result = await runCapture(cwd, harness, lineageId);
+
+	assert.equal(result.outcome, "unachievable-lens-slot-declared");
+	const slots = result.unachievable_lens_slots as Array<{ lens: string; selected_order: number; subject_hash: string }>;
+	assert.equal(slots.length, 1, "only the declared entry is exposed");
+	assert.equal(slots[0]!.lens, "review-risk");
+	assert.equal(slots[0]!.selected_order, 0);
+	assert.equal(slots[0]!.subject_hash, `sha256:${"0".repeat(64)}`);
+	assert.equal(result.mutation_outcome, "committed");
+});
+
+// gentle-pi#822 (CodeRabbit finding): success must be proven by the unachievable_lens_slot stop itself — a bound STATUS that comes back with a collect reoffer instead of the stop is a reconciliation failure, never a silent success with no withdraw command.
+test("a bound STATUS that reoffers the collect transition instead of the stop reports a reconciliation failure", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "relay-lineage";
+	const input = relayCollectInput(lineageId, "review-risk", 0);
+	const harness = nativeHarness([finalizeStatus(lineageId, [input]), finalizeStatus(lineageId, [input])], () => Promise.resolve(unachievableArtifact(lineageId, "review-risk", 0)));
+	__testing.setReviewHostRelayRunnerForTesting(async () => {
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "pi reviewer subprocess exceeded the relay bound", { exitCode: null, timedOut: true, elapsedMs: 2_256_004, timeoutMs: 2_256_000 });
+	});
+
+	const result = await runCapture(cwd, harness, lineageId);
+
+	assert.equal(result.status, "blocked");
+	assert.equal(result.outcome, "unachievable-lens-declaration-reconciliation-failed");
+	assert.equal(result.unachievable_lens_slots, undefined, "no stop means no withdraw command to expose");
+	const reconciliationFailure = result.reconciliation_failure as { outcome?: string; reason?: string };
+	assert.equal(reconciliationFailure?.outcome, "unachievable-lens-slot-declaration-unmatched");
+	assert.match(String(reconciliationFailure?.reason), /did not return the unachievable_lens_slot stop/);
+	assert.equal(result.mutation_performed, true, "the declaration was recorded");
+	assert.equal(result.mutation_outcome, "committed");
+	assert.equal(harness.statusCalls.length, 2, "the bound re-query still runs exactly once");
+});
+
+// gentle-pi#822 (CodeRabbit finding): the same proof requirement covers every STATUS shape that is not the stop — a foreign stop reason code or no transition at all.
+test("a bound STATUS stop with a foreign reason code or no transition reports a reconciliation failure", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "relay-lineage";
+	const input = relayCollectInput(lineageId, "review-risk", 0);
+	const responder = () => Promise.resolve(unachievableArtifact(lineageId, "review-risk", 0));
+	const relayFailure = async () => {
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "pi reviewer subprocess exceeded the relay bound", { exitCode: null, timedOut: true, elapsedMs: 2_256_004, timeoutMs: 2_256_000 });
+	};
+
+	const foreignStop = { ...finalizeStatus(lineageId), nextTransition: { kind: "stop", reasonCode: "rdd_disabled" } } as unknown as ReviewStatusV3;
+	const foreignHarness = nativeHarness([finalizeStatus(lineageId, [input]), foreignStop], responder);
+	__testing.setReviewHostRelayRunnerForTesting(relayFailure);
+	const foreign = await runCapture(cwd, foreignHarness, lineageId);
+
+	assert.equal(foreign.outcome, "unachievable-lens-declaration-reconciliation-failed");
+	assert.equal(foreign.unachievable_lens_slots, undefined);
+	const foreignFailure = foreign.reconciliation_failure as { outcome?: string; reason?: string };
+	assert.match(String(foreignFailure?.reason), /did not return the unachievable_lens_slot stop/);
+	assert.equal(foreign.mutation_performed, true);
+	assert.equal(foreign.mutation_outcome, "committed");
+
+	const bareHarness = nativeHarness([finalizeStatus(lineageId, [input]), finalizeStatus(lineageId)], responder);
+	__testing.setReviewHostRelayRunnerForTesting(relayFailure);
+	const bare = await runCapture(cwd, bareHarness, lineageId);
+
+	assert.equal(bare.outcome, "unachievable-lens-declaration-reconciliation-failed");
+	assert.equal(bare.unachievable_lens_slots, undefined);
+	const bareFailure = bare.reconciliation_failure as { outcome?: string; reason?: string };
+	assert.match(String(bareFailure?.reason), /did not return the unachievable_lens_slot stop/);
+	assert.equal(bare.mutation_outcome, "committed");
+	assert.equal(bareHarness.statusCalls.length, 2);
+});
+
+// gentle-pi#822: STATUS for one lineage renders only that lineage's withdraw
+// command as the hint; a request for an unlisted lineage omits the hint rather
+// than surfacing a potentially unrelated withdraw command.
+test("an unachievable stop renders the withdraw hint only for the requested lineage", async (t) => {
+	const cwd = repository(t);
+	const matchedHarness = nativeHarness([unachievableStopStatus("other-lineage", "review-risk", 0)]);
+	const matched = (await __testing.executeReviewControllerOperation({ operation: "status", lineageId: "other-lineage" }, cwd, matchedHarness.native)) as Record<string, unknown>;
+	assert.match(String(matched.hint), /capture-unachievable.*--withdraw=true/);
+	assert.equal(matched.requested_lineage_id, "other-lineage");
+
+	const unmatchedHarness = nativeHarness([unachievableStopStatus("other-lineage", "review-risk", 0)]);
+	const unmatched = (await __testing.executeReviewControllerOperation({ operation: "status", lineageId: "relay-lineage" }, cwd, unmatchedHarness.native)) as Record<string, unknown>;
+	assert.equal(unmatched.hint, undefined, "no hint when no slot matches the requested lineage");
+	assert.equal(unmatched.requested_lineage_id, "relay-lineage");
+});
+
+// The fail-open capability gate: an older binary that refuses the whole verb
+// keeps today's transport-failure envelope untouched.
+test("an unknown-verb refusal falls back to today's transport-failure behavior", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "relay-lineage";
+	const harness = nativeHarness([finalizeStatus(lineageId, [relayCollectInput(lineageId, "review-risk", 0)])], async () => {
+		throw Object.assign(new Error("native command returned empty output"), { diagnostics: { stderr: 'Error: unknown review command "capture-unachievable"\n' } });
+	});
+	__testing.setReviewHostRelayRunnerForTesting(async () => {
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "pi reviewer subprocess exceeded the relay bound", { exitCode: null, timedOut: true, elapsedMs: 2_256_004, timeoutMs: 2_256_000 });
+	});
+
+	const result = await runCapture(cwd, harness, lineageId);
+
+	assert.equal(result.status, "blocked");
+	assert.equal(result.outcome, "pi-host-relay-timeout");
+	assert.equal(harness.unachievableCalls.length, 1, "the verb was attempted exactly once");
+	assert.equal(harness.statusCalls.length, 1, "the fall-back performs no bound STATUS re-query");
+	assert.match(String(result.next_action), new RegExp(`${REVIEW_HOST_RELAY_PI_TIMEOUT_ENV}=<milliseconds>`));
+});
+
+// Every non-capability declaration failure — here a typed binding-mismatch
+// refusal — is surfaced with both failures, never hidden behind the relay
+// failure it followed.
+test("a refused declaration surfaces both failures instead of the transport fall-back", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "relay-lineage";
+	const harness = nativeHarness([finalizeStatus(lineageId, [relayCollectInput(lineageId, "review-risk", 0)])], async () => {
+		throw Object.assign(new Error("review capture-unachievable binding does not match the current reviewing authority"), { diagnostics: { stderr: "Error: review capture-unachievable binding does not match [invalid_request]" } });
+	});
+	__testing.setReviewHostRelayRunnerForTesting(async () => {
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "pi reviewer subprocess exceeded the relay bound", { exitCode: null, timedOut: true, elapsedMs: 2_256_004, timeoutMs: 2_256_000 });
+	});
+
+	const result = await runCapture(cwd, harness, lineageId);
+
+	assert.equal(result.status, "blocked");
+	assert.equal(result.outcome, "unachievable-lens-declaration-failed");
+	assert.equal(result.mutation_performed, false);
+	assert.equal(result.mutation_outcome, "none");
+	assert.deepEqual(result.failure, { kind: "pi-timed-out", stage: "pi", exit_code: null, timed_out: true, elapsed_ms: 2_256_004, timeout_ms: 2_256_000 });
+	assert.ok(result.declaration_failure, "the declaration refusal rides the envelope");
+	assert.equal(harness.statusCalls.length, 1, "a refused declaration performs no bound STATUS re-query");
+	assert.match(String(result.next_action), /fresh STATUS/);
+});
+
+// gentle-pi#822 (outside-diff finding): the declaration failure's own envelope carries the mutation truth — a failure AFTER the provider recorded the declaration reports committed, never a hardcoded none.
+test("a declaration failure whose envelope already committed propagates its mutation state", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "relay-lineage";
+	const harness = nativeHarness([finalizeStatus(lineageId, [relayCollectInput(lineageId, "review-risk", 0)])], async () => {
+		throw Object.assign(new Error("review capture-unachievable failed after recording"), { failureEnvelope: { raw: { code: "invalid_request", message: "review capture-unachievable failed after recording" }, mutationOutcome: "committed" } });
+	});
+	__testing.setReviewHostRelayRunnerForTesting(async () => {
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "pi reviewer subprocess exceeded the relay bound", { exitCode: null, timedOut: true, elapsedMs: 2_256_004, timeoutMs: 2_256_000 });
+	});
+
+	const result = await runCapture(cwd, harness, lineageId);
+
+	assert.equal(result.status, "blocked");
+	assert.equal(result.outcome, "unachievable-lens-declaration-failed");
+	assert.equal(result.mutation_performed, true);
+	assert.equal(result.mutation_outcome, "committed");
+	assert.ok(result.declaration_failure, "the declaration failure still rides the envelope");
+	assert.equal(harness.statusCalls.length, 1, "a committed outcome needs no reconciliation re-query");
+});
+
+// gentle-pi#822 (outside-diff finding): an unknown declaration outcome is proven or disproven by one bound STATUS re-query without ever changing the failure outcome.
+test("an unknown declaration outcome is proven committed by one bound STATUS re-query", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "relay-lineage";
+	const input = relayCollectInput(lineageId, "review-risk", 0);
+	const stop = unachievableStopStatus(lineageId, "review-risk", 0);
+	const harness = nativeHarness([finalizeStatus(lineageId, [input]), stop], async () => {
+		throw Object.assign(new Error("native command timed out while recording the declaration"), { failureEnvelope: { raw: { code: "deadline_exceeded", message: "native command timed out" }, mutationOutcome: "unknown" } });
+	});
+	__testing.setReviewHostRelayRunnerForTesting(async () => {
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "pi reviewer subprocess exceeded the relay bound", { exitCode: null, timedOut: true, elapsedMs: 2_256_004, timeoutMs: 2_256_000 });
+	});
+
+	const result = await runCapture(cwd, harness, lineageId);
+
+	assert.equal(result.status, "blocked");
+	assert.equal(result.outcome, "unachievable-lens-declaration-failed", "the failure outcome never changes");
+	assert.equal(result.mutation_performed, true);
+	assert.equal(result.mutation_outcome, "committed");
+	assert.equal(harness.statusCalls.length, 2, "one selection STATUS plus exactly one bound reconciliation re-query");
+	assert.equal(harness.statusCalls.at(-1)?.agent, "pi", "the reconciliation re-query preserves the Pi host runtime");
+});
+
+// gentle-pi#822 (outside-diff finding): a malformed declaration error with no envelope at all keeps the conservative none outcome and performs no re-query.
+test("a malformed declaration error without an envelope keeps mutation none", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "relay-lineage";
+	const harness = nativeHarness([finalizeStatus(lineageId, [relayCollectInput(lineageId, "review-risk", 0)])], async () => {
+		throw new TypeError("cannot read properties of undefined (reading 'detail')");
+	});
+	__testing.setReviewHostRelayRunnerForTesting(async () => {
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "pi reviewer subprocess exceeded the relay bound", { exitCode: null, timedOut: true, elapsedMs: 2_256_004, timeoutMs: 2_256_000 });
+	});
+
+	const result = await runCapture(cwd, harness, lineageId);
+
+	assert.equal(result.status, "blocked");
+	assert.equal(result.outcome, "unachievable-lens-declaration-failed");
+	assert.equal(result.mutation_performed, false);
+	assert.equal(result.mutation_outcome, "none");
+	assert.equal(harness.statusCalls.length, 1, "no envelope means no unknown outcome and no re-query");
+});
+
 test("a non-timeout transport failure keeps its generic continuation and now carries its measurements", async (t) => {
 	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
 	const cwd = repository(t);

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

@@ -18,6 +18,8 @@ import {
 	resolveReviewHostRelayPiTimeoutMs,
 	resolveReviewHostRelaySubmission,
 	reviewHostRelaySlots,
+	reviewHostRelayUnachievableDetail,
+	reviewHostRelayUnachievableReason,
 	prepareReviewHostRelaySlot,
 	runReviewHostRelayReviewerGroup,
 	runReviewHostRelaySlot,
@@ -779,6 +781,33 @@ test("refusal classification distinguishes unknown-flag, handshake, and other",
 	assert.equal(classifyReviewHostRelayRefusal("some unrelated explosion"), "other");
 });
 
+// gentle-pi#638: only a reviewer killed by the scaled relay bound is proven
+// deterministic for this exact slot. Generic admission refusals are repairable
+// by a fresh reviewer and retain the ordinary exact-reoffer behavior.
+test("the unachievable predicate names only deterministic slot failures", () => {
+	const killed = new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "pi reviewer subprocess exceeded the relay bound", { timedOut: true, elapsedMs: 2_256_004, timeoutMs: 2_256_000 });
+	assert.equal(reviewHostRelayUnachievableReason(killed), "relay_transport_bound_exceeded");
+	assert.equal(reviewHostRelayUnachievableDetail(killed), "killed after 2256004ms against a 2256000ms relay bound");
+
+	for (const refusal of ["reviewer payload contains no complete JSON object", "reviewer artifact admission binding_mismatch"]) {
+		const admitted = new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit", `${refusal} [invalid_request]`, { exitCode: 1, mutationOutcome: "none" });
+		assert.equal(reviewHostRelayUnachievableReason(admitted), undefined, `${refusal} is repairable by a fresh reviewer`);
+		assert.equal(reviewHostRelayUnachievableDetail(admitted), undefined);
+	}
+
+	const unknownOutcome = new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit", "gentle-ai capture submission exceeded its bound", { timedOut: true });
+	assert.equal(reviewHostRelayUnachievableReason(unknownOutcome), undefined, "an unknown mutation outcome is never deterministic");
+	assert.equal(reviewHostRelayUnachievableDetail(unknownOutcome), undefined);
+
+	for (const kind of [REVIEW_HOST_RELAY_FAILURE.PI_FAILED, REVIEW_HOST_RELAY_FAILURE.PI_LAUNCH_FAILED, REVIEW_HOST_RELAY_FAILURE.PI_EMPTY_OUTPUT, REVIEW_HOST_RELAY_FAILURE.MATERIALIZE_FAILED, REVIEW_HOST_RELAY_FAILURE.EMPTY_PROMPT, REVIEW_HOST_RELAY_FAILURE.RELAY_UNAVAILABLE, REVIEW_HOST_RELAY_FAILURE.HANDSHAKE_REFUSED, REVIEW_HOST_RELAY_FAILURE.SUBMISSION_CONTRACT_MISMATCH]) {
+		assert.equal(reviewHostRelayUnachievableReason(new ReviewHostRelayError(kind, "pi", "transient")), undefined, `${kind} stays transient`);
+	}
+
+	const unmeasured = new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT, "pi", "killed at the bound");
+	assert.equal(reviewHostRelayUnachievableReason(unmeasured), "relay_transport_bound_exceeded");
+	assert.equal(reviewHostRelayUnachievableDetail(unmeasured), undefined, "no measurements means no detail, never a fabricated one");
+});
+
 // ---------------------------------------------------------------------------
 // Slot detection — the provider decides; nothing is inferred.
 // ---------------------------------------------------------------------------