gentle-pi 2.4.0 → 2.6.0

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
@@ -142,25 +142,44 @@ function finalizeStatus(lineageId: string, inputs?: readonly ReviewCollectInputV
 	} as unknown as ReviewStatusV3;
 }
 
+function providerRefuterRequiredStatus(lineageId: string): ReviewStatusV3 {
+	const refuter: ReviewCollectInputV3 = {
+		name: "provider_refuter",
+		schema: "https://gentle-ai.dev/schema/review/refuter/v1",
+		captureOperation: "review.capture-refuter",
+		arguments: bindingArguments(lineageId, "review-risk", 0),
+	};
+	return {
+		...finalizeStatus(lineageId),
+		nextTransition: { kind: "collect", reasonCode: "provider_refuter_required", collect: { inputs: [refuter] } },
+	};
+}
+
 interface RoutingHarness {
 	statusQueue: ReviewStatusV3[];
-	statusCalls: Array<{ cwd: string; lineageId?: string }>;
+	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 = {
 		targetStatus: async (request) => {
-			harness.statusCalls.push({ cwd: request.cwd, ...(request.lineageId === undefined ? {} : { lineageId: request.lineageId }) });
+			harness.statusCalls.push({ cwd: request.cwd, ...(request.lineageId === undefined ? {} : { lineageId: request.lineageId }), ...(request.agent === undefined ? {} : { agent: request.agent }) });
 			const next = harness.statusQueue.shift();
 			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;
 }
@@ -226,7 +245,7 @@ function prepared(request: ReviewHostRelayRequest) { return { request, promptByt
 test("grouped capture forecasts once, reaches a four-reviewer barrier, and reconciles unclosed submissions", async (t) => {
 	t.after(() => __testing.setReviewHostRelayGroupRunnersForTesting());
 	const cwd = repository(t), lineageId = "relay-group", inputs = groupInputs(lineageId), lenses = inputs.map((input) => input.arguments.find((argument) => argument.name === "lens")!.value);
-	const harness = nativeHarness([finalizeStatus(lineageId, inputs), finalizeStatus(lineageId, inputs), ...inputs.map((_input, index) => finalizeStatus(lineageId, index === 1 ? [...inputs.slice(index), { name: "unrelated", schema: "example", captureOperation: "external.example", arguments: [] }] : inputs.slice(index))), finalizeStatus(lineageId)]);
+	const harness = nativeHarness([finalizeStatus(lineageId, inputs), finalizeStatus(lineageId, inputs), ...inputs.map((_input, index) => finalizeStatus(lineageId, index === 1 ? [...inputs.slice(index), { name: "unrelated", schema: "example", captureOperation: "external.example", arguments: [] }] : inputs.slice(index))), providerRefuterRequiredStatus(lineageId)]);
 	let ready!: () => void;
 	const allStarted = new Promise<void>((resolve) => { ready = resolve; });
 	const releases = new Map<string, () => void>(), completed: string[] = [], submitted: string[] = [];
@@ -249,7 +268,9 @@ test("grouped capture forecasts once, reaches a four-reviewer barrier, and recon
 	assert.deepEqual(completed, [...lenses].reverse(), "reviewer completion order is not submission order");
 	assert.deepEqual(submitted, lenses);
 	assert.deepEqual({ outcome: result.outcome, statusCalls: harness.statusCalls.length, providerAction: result.provider_action }, { outcome: "native-reviewer-group-status-reconciled", statusCalls: 7, providerAction: "stop" });
-	assert.equal(result.next_transition, undefined);
+	assert.equal(harness.statusCalls.at(-1)?.agent, "pi", "post-last-capture reconciliation preserves the Pi host runtime");
+	assert.equal((result.next_transition as { kind?: string; reasonCode?: string } | undefined)?.kind, "collect");
+	assert.equal((result.next_transition as { kind?: string; reasonCode?: string } | undefined)?.reasonCode, "provider_refuter_required");
 });
 
 test("captured v5 STATUS accepts capture-phase Pn when authority has advanced to Rn at the forecast boundary", async (t) => {
@@ -465,6 +486,7 @@ test("a submission whose outcome is genuinely indeterminate still reconciles thr
 	assert.deepEqual(result.failure, { kind: "submission-refused", stage: "submit", exit_code: null, timed_out: true, elapsed_ms: 120_004, timeout_ms: 120_000 });
 	assert.match(String(result.reason), /exceeded its 120000ms bound/);
 	assert.equal(harness.statusCalls.length, 2, "an indeterminate submission reconciles exactly once through STATUS");
+	assert.equal(harness.statusCalls.at(-1)?.agent, "pi", "ordinary host-relay reconciliation preserves the Pi host runtime");
 });
 
 test("a relay timeout reports its one-slot measurements and no auto-follow", async (t) => {
@@ -490,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.
 // ---------------------------------------------------------------------------

package/tests/review-integration-v2-forward.test.ts

@@ -699,3 +699,47 @@ test("review-acknowledged/v1 is disjoint from every prior captured identity in b
 		assert.throws(() => decoder(clone(acknowledged)), `${name} must reject the acknowledged envelope`);
 	}
 });
+
+// Producer-shaped projection: gentle-ai d521b5e, target_status.go and
+// last-event-closure.schema.json#/properties/escalation (not a live capture).
+function escalatedStatusV7(): JsonObject {
+	const body = currentStatusFixture("status-v5-capture-result-submission.captured.json");
+	body.schema = "gentle-ai.review-integration.status/v7";
+	(body.authority as JsonObject).state = "escalated";
+	body.action = "stop";
+	body.replayability = "manual_action_required";
+	body.next_transition = { kind: "stop", reason_code: "escalated" };
+	delete body.forecast;
+	body.escalation = { cause: "unknown_causality", finding_ids: ["R1"] };
+	return body;
+}
+
+test("v7 escalation is typed metadata and preserves native stop authority", () => {
+	const body = escalatedStatusV7();
+	const decoded = decodeReviewStatusV3(body);
+	assert.deepEqual(decoded.escalation, { cause: "unknown_causality", findingIds: ["R1"] });
+	delete body.escalation;
+	const older = decodeReviewStatusV3(body);
+	assert.deepEqual({ ...decoded, escalation: undefined, raw: undefined }, { ...older, escalation: undefined, raw: undefined });
+	assert.equal(decoded.action, "stop");
+	assert.equal(decoded.authority?.state, "escalated");
+	assert.deepEqual(decoded.nextTransition, { kind: "stop", reasonCode: "escalated" });
+});
+
+test("v7 escalation strictly decodes all causes and optional refuter evidence", () => {
+	for (const cause of ["unknown_causality", "insufficient_evidence", "missing_refuter_outcome", "targeted_validator_rejected", "correction_budget_exceeded", "unresolved_severe_findings"]) {
+		const body = escalatedStatusV7();
+		const rows = ["corroborated", "refuted", "inconclusive"].map((outcome) => ({ finding_id: "R2", outcome, proof: "observed evidence" }));
+		body.escalation = { cause, finding_ids: [], refuter_outcomes: rows };
+		assert.deepEqual(decodeReviewStatusV3(body).escalation, { cause, findingIds: [], refuterOutcomes: rows.map(({ finding_id, ...row }) => ({ findingId: finding_id, ...row })) });
+	}
+	for (const escalation of [null, undefined, [], {}, { cause: "future", finding_ids: [] }, { cause: "unknown_causality" }, { cause: "unknown_causality", finding_ids: [""] }, { cause: "unknown_causality", finding_ids: "R1" }, { cause: "unknown_causality", finding_ids: [], extra: true }]) {
+		assert.throws(() => decodeReviewStatusV3({ ...escalatedStatusV7(), escalation }), /status\.escalation/);
+	}
+	for (const refuter_outcomes of [null, undefined, {}, [null], [{}], [{ finding_id: "R1", outcome: "future", proof: "proof" }], [{ finding_id: "", outcome: "refuted", proof: "proof" }], [{ finding_id: "R1", outcome: "refuted", proof: "" }], [{ finding_id: "R1", outcome: "refuted", proof: "proof", extra: true }]]) {
+		assert.throws(() => decodeReviewStatusV3({ ...escalatedStatusV7(), escalation: { cause: "missing_refuter_outcome", finding_ids: ["R1"], refuter_outcomes } }), /refuter_outcomes/);
+	}
+	for (const version of [3, 5, 6]) {
+		assert.throws(() => decodeReviewStatusV3({ ...escalatedStatusV7(), schema: `gentle-ai.review-integration.status/v${version}` }), /not allowed/);
+	}
+});