gentle-pi 2.1.2 → 2.3.0

package/tests/review-recovered-lineage-routing.test.ts

@@ -0,0 +1,199 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, 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 { CandidateViewRegistry, injectReviewCandidateView } from "../lib/review-candidate-view.ts";
+import type { ReviewCollectInputV3, ReviewStatusV3 } from "../lib/review-integration-v2.ts";
+
+// Live-confirmed adapter defects (2026-08-16, gentle-ai 2.4.0-main, Engram
+// #12461/#12466), both around a lineage recovered EXTERNALLY through native
+// `gentle-ai review recover` (disposition scope_changed):
+//
+//   A. The controller never saw the successor's START, so direct reviewer
+//      dispatch refused with `no current controller-owned candidate view
+//      lineage binding` even though the controller itself had just decoded
+//      the successor's authoritative STATUS.
+//   B. `gentle_review finalize` on a lineage still at reviewer_results_required
+//      misrouted into the correction evidence-first-ordering lane and failed
+//      instead of surfacing the provider-offered review.capture-result step.
+
+const SHA = `sha256:${"1".repeat(64)}`;
+
+function git(cwd: string, ...arguments_: string[]): string {
+	return execFileSync("git", arguments_, { cwd, encoding: "utf8" }).trim();
+}
+
+function repository(t: test.TestContext): string {
+	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-recovered-routing-"));
+	t.after(() => rmSync(cwd, { recursive: true, force: true }));
+	git(cwd, "init", "-b", "main");
+	writeFileSync(join(cwd, "tracked.txt"), "base\n");
+	git(cwd, "add", "tracked.txt");
+	git(cwd, "-c", "user.name=Recovered Test", "-c", "user.email=recovered@example.invalid", "commit", "-m", "base");
+	return cwd;
+}
+
+function reviewerResultCollectInput(lineageId: string, lens: string, order: number): ReviewCollectInputV3 {
+	return {
+		name: "reviewer_result",
+		schema: "https://gentle-ai.dev/schema/review/reviewer/v1",
+		captureOperation: "review.capture-result",
+		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: "lens", value: lens, token: `--lens=${lens}` },
+			{ name: "order", value: String(order), token: `--order=${order}` },
+			{ name: "subject-hash", value: `sha256:${String(order).repeat(64)}`, token: `--subject-hash=sha256:${String(order).repeat(64)}` },
+		],
+		artifactSubject: {
+			schema: "gentle-ai.review-artifact-subject/v2",
+			subjectHash: `sha256:${String(order).repeat(64)}`,
+			lineageId,
+			authorityRevision: SHA,
+			targetIdentity: SHA,
+			baseTree: "3".repeat(40),
+			candidateTree: "4".repeat(40),
+			changedPathManifestSha256: SHA,
+			lens,
+			selectedOrder: order,
+		},
+	} as unknown as ReviewCollectInputV3;
+}
+
+interface StatusFixtureShape {
+	lineageId: string;
+	baseTree: string;
+	currentCandidateTree: string;
+	paths: readonly string[];
+	inputs?: readonly ReviewCollectInputV3[];
+	executeFinalize?: boolean;
+}
+
+function recoveredStatus(shape: StatusFixtureShape): ReviewStatusV3 {
+	return {
+		contract: "gentle-ai.review-integration/v2",
+		applicability: "current_target",
+		authority: { version: "compact-v2", lineageId: shape.lineageId, state: "reviewer_results_required", generation: 2, revision: SHA },
+		receipt: { status: "expected_missing" },
+		action: "finalize",
+		replayability: "not_replayable",
+		targetIdentity: SHA,
+		projection: {
+			schema: "gentle-ai.review-integration.projection/v1",
+			kind: "current-changes",
+			projection: "workspace",
+			baseTree: shape.baseTree,
+			initialReviewTree: shape.currentCandidateTree,
+			currentCandidateTree: shape.currentCandidateTree,
+			pathsDigest: SHA,
+			paths: [...shape.paths],
+			intendedUntracked: [],
+			intendedUntrackedProof: SHA,
+			initialSnapshotIdentity: SHA,
+			currentSnapshotIdentity: SHA,
+		},
+		candidates: [],
+		...(shape.inputs !== undefined
+			? { nextTransition: { kind: "collect", reasonCode: "reviewer_results_required", collect: { inputs: [...shape.inputs] } } }
+			: {}),
+		...(shape.executeFinalize === true
+			? { nextTransition: { kind: "execute", reasonCode: "captured_results_ready", execute: { operation: "review.finalize", arguments: [], binding: { lineageId: shape.lineageId } } } }
+			: {}),
+		raw: { schema: "gentle-ai.review-integration.status/v5", action: "finalize", lineage_id: shape.lineageId },
+	} as unknown as ReviewStatusV3;
+}
+
+function statusOnlyNative(statuses: readonly ReviewStatusV3[]): { native: NativeReviewCli; finalizeCalls: () => number; statusCalls: () => number } {
+	const queue = [...statuses];
+	let finalizeCalls = 0;
+	let statusCalls = 0;
+	const native = {
+		targetStatus: async () => {
+			statusCalls += 1;
+			// The v5 lane legitimately re-queries STATUS (workspace-root
+			// rebind); keep serving the terminal fixture once drained.
+			const next = queue.length > 1 ? queue.shift() : queue[0];
+			if (next === undefined) throw new Error("status queue exhausted");
+			return next;
+		},
+		finalize: async () => {
+			finalizeCalls += 1;
+			throw new Error("native finalize must not be invoked while reviewer results are outstanding");
+		},
+	} as unknown as NativeReviewCli;
+	return { native, finalizeCalls: () => finalizeCalls, statusCalls: () => statusCalls };
+}
+
+async function runController(
+	parameters: Record<string, unknown>,
+	cwd: string,
+	native: NativeReviewCli,
+	candidateViews: CandidateViewRegistry,
+): Promise<Record<string, unknown>> {
+	return await __testing.executeReviewControllerOperation(
+		parameters,
+		cwd,
+		native,
+		undefined,
+		candidateViews,
+	) as Record<string, unknown>;
+}
+
+// --- DEFECT A: STATUS discovery hydrates the dispatch binding ---
+
+test("STATUS discovery hydrates the dispatch binding for an externally recovered lineage", async (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "successor candidate change\n");
+	// Derive the real frozen identity of the live workspace candidate the way
+	// native recover froze it: the descriptor in status/v5 names these trees.
+	const probe = new CandidateViewRegistry();
+	const probeView = probe.create({ contributorRoot: cwd });
+	const frozen = { baseTree: probeView.baseTree, currentCandidateTree: probeView.candidateTree, paths: probeView.paths };
+	probe.cleanup(probeView.token);
+
+	const successor = "review-recovered-successor";
+	const status = recoveredStatus({ lineageId: successor, ...frozen, inputs: [reviewerResultCollectInput(successor, "review-reliability", 0)] });
+	const { native } = statusOnlyNative([status]);
+	const registry = new CandidateViewRegistry();
+
+	// The controller does not know this lineage: dispatch refuses.
+	assert.throws(
+		() => injectReviewCandidateView({ agent: "review-reliability", task: "review", mode: "task" }, registry),
+		/no current controller-owned candidate view lineage binding/,
+	);
+
+	const envelope = await runController({ operation: "status", lineageId: successor }, cwd, native, registry);
+	assert.equal(envelope.operation, "status");
+
+	// After the controller itself decoded the successor's authoritative
+	// STATUS, the dispatch binding must be hydrated from that status.
+	assert.equal(registry.hasCurrentBinding(), true, "STATUS discovery must hydrate the controller-owned dispatch binding");
+	try {
+		const dispatch: Record<string, unknown> = { agent: "review-reliability", task: "review the recovered successor", mode: "task" };
+		assert.doesNotThrow(() => injectReviewCandidateView(dispatch, registry));
+		assert.match(String(dispatch.task), new RegExp(successor));
+		assert.equal(registry.resolveCurrentForLens("review-reliability").candidateTree, frozen.currentCandidateTree);
+	} finally {
+		registry.cleanup(registry.resolveCurrentForLens("review-reliability").token);
+	}
+});
+
+test("STATUS discovery never hydrates without pending reviewer-result collection", async (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "successor candidate change\n");
+	const probe = new CandidateViewRegistry();
+	const probeView = probe.create({ contributorRoot: cwd });
+	const frozen = { baseTree: probeView.baseTree, currentCandidateTree: probeView.candidateTree, paths: probeView.paths };
+	probe.cleanup(probeView.token);
+
+	const successor = "review-recovered-successor";
+	const { native } = statusOnlyNative([recoveredStatus({ lineageId: successor, ...frozen, executeFinalize: true })]);
+	const registry = new CandidateViewRegistry();
+	await runController({ operation: "status", lineageId: successor }, cwd, native, registry);
+	assert.equal(registry.hasCurrentBinding(), false, "an execute transition offers no reviewer dispatch and must not hydrate");
+});

package/tests/review-relay-transport-agent.test.ts

@@ -0,0 +1,322 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, 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 { NativeReviewIntegrationError, type NativeReviewCli } from "../lib/native-review-cli.ts";
+import { CandidateViewRegistry } from "../lib/review-candidate-view.ts";
+import type { ReviewCollectInputV3, ReviewStatusV3 } from "../lib/review-integration-v2.ts";
+import type { ReviewHostRelayRequest } from "../lib/review-host-relay.ts";
+
+// Third field failure on the recovered-lineage defect (2026-08-16, gentle-pi
+// main 402f9f77 + gentle-ai 2.4.0-main.20278905): STATUS recognises the
+// lineage, the Pi RELAY never runs, no lens is launched, zero mutations.
+//
+// Measured against the live binary on a faithful reproduction (linked
+// worktree, uncommitted tracked files, externally recovered successor):
+//
+//   agent-less STATUS  -> collect input arguments:
+//       lineage, expected-revision, target, repository-context, lens, order,
+//       subject-hash                      (no agent, no materialize, no submission)
+//   `--agent pi` STATUS -> the same input PLUS agent=pi, materialize=true and
+//       the provider submission (operation_token=capture-result)
+//
+// The adapter's negotiated targetStatus never sent `--agent pi`, so the
+// provider never offered the materialize-marked relay slot,
+// reviewHostRelaySlots() returned 0 for every real lineage, and the host relay
+// was unreachable. The prior fixes all exercised dispatch-shaped slots.
+//
+// Binaries older than v2.4.0 do not define `--agent` on `review status` and
+// refuse it outright, so the agent is probed rather than version-sniffed and
+// the typed refusal must reach the user instead of being swallowed.
+
+const SHA = `sha256:${"1".repeat(64)}`;
+const TRANSPORT_REFUSAL_CODE = "immutable_review_transport_unsupported";
+
+function repository(t: test.TestContext): string {
+	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-relay-transport-"));
+	t.after(() => rmSync(cwd, { recursive: true, force: true }));
+	execFileSync("git", ["init", "-b", "main"], { cwd });
+	writeFileSync(join(cwd, "app.ts"), "export const value = 1;\n");
+	execFileSync("git", ["add", "."], { cwd });
+	execFileSync("git", ["-c", "user.name=Relay", "-c", "user.email=relay@example.invalid", "commit", "-m", "base"], { cwd });
+	return cwd;
+}
+
+function collectInput(lineageId: string, materialize: boolean): ReviewCollectInputV3 {
+	const binding = [
+		{ 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: `rctx1_${"e".repeat(64)}`, token: `--repository-context=rctx1_${"e".repeat(64)}` },
+		{ name: "lens", value: "review-reliability", token: "--lens=review-reliability" },
+		{ name: "order", value: "0", token: "--order=0" },
+		{ name: "subject-hash", value: SHA, token: `--subject-hash=${SHA}` },
+	];
+	return {
+		name: "reviewer_result",
+		schema: "https://gentle-ai.dev/schema/review/reviewer/v1",
+		captureOperation: "review.capture-result",
+		arguments: materialize
+			? [...binding, { name: "agent", value: "pi", token: "--agent=pi" }, { name: "materialize", value: "true", token: "--materialize=true" }]
+			: binding,
+		artifactSubject: {
+			schema: "gentle-ai.review-artifact-subject/v2",
+			subjectHash: SHA,
+			lineageId,
+			authorityRevision: SHA,
+			targetIdentity: SHA,
+			baseTree: "3".repeat(40),
+			candidateTree: "4".repeat(40),
+			changedPathManifestSha256: SHA,
+			lens: "review-reliability",
+			selectedOrder: 0,
+		},
+		...(materialize
+			? {
+				submission: {
+					operationToken: "capture-result",
+					argumentTokens: [...binding.map((argument) => argument.token), "--input={{value}}"],
+					values: [{ slot: "reviewer_result", domain: "artifact_path_or_stdin", substitutionLocation: binding.length }],
+				},
+			}
+			: {}),
+	} as unknown as ReviewCollectInputV3;
+}
+
+function recoveredStatus(lineageId: string, materialize: boolean): ReviewStatusV3 {
+	return {
+		contract: "gentle-ai.review-integration/v2",
+		applicability: "current_target",
+		authority: { version: "compact-v2", lineageId, state: "reviewer_results_required", generation: 2, revision: SHA },
+		action: "stop",
+		replayability: "not_replayable",
+		targetIdentity: SHA,
+		projection: {
+			schema: "gentle-ai.review-integration.projection/v1",
+			kind: "current-changes",
+			projection: "workspace",
+			baseTree: "3".repeat(40),
+			initialReviewTree: "4".repeat(40),
+			currentCandidateTree: "4".repeat(40),
+			pathsDigest: SHA,
+			paths: ["app.ts"],
+			intendedUntracked: [],
+			intendedUntrackedProof: SHA,
+			initialSnapshotIdentity: SHA,
+			currentSnapshotIdentity: SHA,
+		},
+		candidates: [],
+		nextTransition: { kind: "collect", reasonCode: "reviewer_results_required", collect: { inputs: [collectInput(lineageId, materialize)] } },
+		raw: { schema: "gentle-ai.review-integration.status/v5", action: "stop", lineage_id: lineageId },
+	} as unknown as ReviewStatusV3;
+}
+
+/**
+ * Mirrors the MEASURED live provider: the materialize-marked relay slot is
+ * offered only when the caller asks for the pi agent.
+ */
+function transportAwareNative(options: { refusalCode?: string } = {}): {
+	native: NativeReviewCli;
+	agents: Array<string | undefined>;
+} {
+	const agents: Array<string | undefined> = [];
+	const native = {
+		targetStatus: async (request: { lineageId?: string; agent?: string }) => {
+			agents.push(request.agent);
+			if (request.agent === "pi" && options.refusalCode !== undefined) {
+				throw new NativeReviewIntegrationError({
+					schema: "gentle-ai.review-integration.failure/v2",
+					contract: "gentle-ai.review-integration/v2",
+					operation: "review.status",
+					phase: "pre_native",
+					code: options.refusalCode,
+					message: "supported immutable review runtimes: claude-code, opencode, codex",
+					mutationOutcome: "none",
+					authorityApplicability: "current_target",
+					retrySafe: true,
+					replayability: "not_replayable",
+					nextAction: "stop",
+					raw: {},
+				} as never);
+			}
+			return recoveredStatus(request.lineageId ?? "relay-lineage", request.agent === "pi");
+		},
+	} as unknown as NativeReviewCli;
+	return { native, agents };
+}
+
+async function runCapture(cwd: string, native: NativeReviewCli, lineageId: string, input: Record<string, unknown> = { reviewerRunAcknowledged: true }): Promise<Record<string, unknown>> {
+	return await __testing.executeReviewCaptureOperation(
+		{ lineageId, collectBinding: JSON.stringify(collectInput(lineageId, true)), ...input },
+		cwd, native, undefined, new CandidateViewRegistry(),
+	) as Record<string, unknown>;
+}
+
+
+async function runStatus(cwd: string, native: NativeReviewCli, lineageId: string): Promise<Record<string, unknown>> {
+	return await __testing.executeReviewControllerOperation(
+		{ operation: "status", lineageId },
+		cwd, native, undefined, new CandidateViewRegistry(),
+	) as Record<string, unknown>;
+}
+
+test("the negotiated status asks for the pi agent so the provider offers its materialize relay slot", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "relay-recovered-successor";
+	const { native, agents } = transportAwareNative();
+	const relayed: ReviewHostRelayRequest[] = [];
+	__testing.setReviewHostRelayRunnerForTesting(async (request: ReviewHostRelayRequest) => {
+		relayed.push(request);
+		return { promptByteLength: 128, resultByteLength: 64, submission: '{"admission_decision":"completed"}' };
+	});
+
+	const result = await runCapture(cwd, native, lineageId);
+
+	assert.equal(agents.at(0), "pi", "the successful Pi route starts with pi-bound STATUS negotiation");
+	assert.ok(agents.every((agent) => agent === "pi"), "the selected capture performs no post-success agent-less STATUS re-query");
+	assert.equal(relayed.length, 1, "the materialize-marked slot must reach the host relay");
+	assert.ok(relayed[0]!.captureArgumentTokens.includes("--materialize=true"));
+	assert.ok(relayed[0]!.submission !== undefined, "the provider submission drives the completing form");
+	const hostRelay = result.host_relay as { transport: string } | undefined;
+	assert.ok(hostRelay !== undefined, "the envelope reports the one relay capture");
+	assert.equal(hostRelay.transport, "pi_host_relay");
+});
+
+test("capture forecasts the reviewer model run once and spends nothing until it is acknowledged", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "forecast-lineage";
+	const { native } = transportAwareNative();
+	let launches = 0;
+	__testing.setReviewHostRelayRunnerForTesting(async () => {
+		launches += 1;
+		return { promptByteLength: 128, resultByteLength: 64, submission: '{"admission_decision":"completed"}' };
+	});
+
+	// An unacknowledged capture must forecast, never spend.
+	const forecast = await runCapture(cwd, native, lineageId, {});
+	assert.equal(launches, 0, "no reviewer model run may start before the forecast is acknowledged");
+	assert.equal(forecast.status, "blocked");
+	assert.equal(forecast.outcome, "reviewer-model-run-forecast");
+	assert.equal(forecast.mutation_performed, false);
+	assert.equal(forecast.mutation_outcome, "none");
+	const cost = forecast.cost_forecast as { transport: string; model_runs: number; lenses: readonly string[] };
+	assert.equal(cost.transport, "pi_host_relay");
+	assert.equal(cost.model_runs, 1, "one model run per outstanding lens, forecast once before launch");
+	assert.deepEqual(cost.lenses, ["review-reliability"]);
+
+	// The acknowledged capture runs exactly the forecast work.
+	const acknowledged = await runCapture(cwd, native, lineageId, { reviewerRunAcknowledged: true });
+	assert.equal(launches, 1, "the acknowledged capture runs the forecast model run");
+	assert.equal(acknowledged.status, "captured");
+});
+
+test("a provider that refuses the pi transport blocks immediately without an agent-less lifecycle fallback", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const lineageId = "legacy-transport-lineage";
+	const { native, agents } = transportAwareNative({ refusalCode: TRANSPORT_REFUSAL_CODE });
+	let relayCalls = 0;
+	__testing.setReviewHostRelayRunnerForTesting(async () => {
+		relayCalls += 1;
+		return { promptByteLength: 1, resultByteLength: 1, submission: "{}" };
+	});
+
+	const result = await runCapture(cwd, native, lineageId);
+
+	assert.deepEqual(agents, ["pi"], "the refusal path issues one pi-bound STATUS and never falls back to an agent-less STATUS");
+	assert.equal(relayCalls, 0, "a refused transport must not launch a relay capture");
+	const transport = result.relay_transport as { supported: boolean; code: string; message: string } | undefined;
+	assert.ok(transport !== undefined, "the blocked envelope must report the typed transport refusal");
+	assert.equal(transport.supported, false);
+	assert.equal(transport.code, TRANSPORT_REFUSAL_CODE);
+	assert.match(transport.message, /immutable review runtimes/i);
+	assert.equal(result.status, "blocked");
+	assert.equal(result.outcome, "pi-host-relay-transport-unavailable");
+	assert.equal(result.mutation_performed, false);
+	assert.equal(result.mutation_outcome, "none");
+	assert.match(String(result.next_action), /support.*--agent pi/i);
+	assert.doesNotMatch(JSON.stringify(result), /no current controller-owned candidate view/);
+	assert.doesNotMatch(JSON.stringify(result), /"status":"(?:approved|allowed)"/);
+});
+
+test("a transport refusal names the runnable wrapper continuation, never a raw CLI command as the only exit", async (t) => {
+	// #535: a provider-printed raw `gentle-ai review ...` continuation is a dead
+	// end in this runtime — Pi is not in the provider's immutable review runtime
+	// list — so the refusal envelope itself must name the exit that runs in this
+	// surface: the gentle_review / gentle_review_capture wrapper tools. The
+	// provider's diagnostic stays intact as evidence alongside the runnable exit.
+	const captureCwd = repository(t);
+	const { native: captureNative } = transportAwareNative({ refusalCode: TRANSPORT_REFUSAL_CODE });
+	const capture = await runCapture(captureCwd, captureNative, "continuation-capture-lineage");
+	__testing.clearReviewTransportProbeForTesting(captureNative);
+	assert.equal(capture.outcome, "pi-host-relay-transport-unavailable");
+	const captureNextAction = String(capture.next_action);
+	assert.match(captureNextAction, /gentle_review \{"operation":"inspect"\}/, "the capture refusal re-enters negotiated STATUS through the wrapper controller");
+	assert.match(captureNextAction, /gentle_review_capture/, "the capture refusal names the wrapper resubmission, not a CLI command");
+	assert.doesNotMatch(captureNextAction, /gentle-ai review/, "a raw `gentle-ai review ...` invocation is not a runnable exit in this runtime");
+	assert.deepEqual(capture.wrapper_continuation, { tool: "gentle_review", operation: "inspect", then: "gentle_review_capture" });
+	assert.match(String((capture.relay_transport as { message: string }).message), /immutable review runtimes/i, "the provider diagnostic remains intact in the envelope");
+
+	const statusCwd = repository(t);
+	const { native: statusNative } = transportAwareNative({ refusalCode: TRANSPORT_REFUSAL_CODE });
+	const status = await runStatus(statusCwd, statusNative, "continuation-status-lineage");
+	__testing.clearReviewTransportProbeForTesting(statusNative);
+	assert.equal(status.outcome, "pi-host-relay-transport-unavailable");
+	const statusNextAction = String(status.next_action);
+	assert.match(statusNextAction, /gentle_review \{"operation":"inspect"\}/, "the controller refusal re-enters negotiated STATUS through the wrapper controller");
+	assert.doesNotMatch(statusNextAction, /gentle-ai review/, "a raw `gentle-ai review ...` invocation is not a runnable exit in this runtime");
+	assert.deepEqual(status.wrapper_continuation, { tool: "gentle_review", operation: "inspect" });
+});
+
+test("a remembered pi transport refusal remains blocked without re-probing or lifecycle continuation", async (t) => {
+	const cwd = repository(t);
+	const { native, agents } = transportAwareNative({ refusalCode: TRANSPORT_REFUSAL_CODE });
+	const first = await runCapture(cwd, native, "probe-lineage");
+	const second = await runCapture(cwd, native, "probe-lineage");
+	assert.equal(first.outcome, "pi-host-relay-transport-unavailable");
+	assert.equal(second.outcome, "pi-host-relay-transport-unavailable");
+	assert.deepEqual(agents, ["pi"], "a cached refusal must not re-probe or issue an agent-less STATUS");
+	__testing.clearReviewTransportProbeForTesting(native);
+});
+
+test("every typed Pi transport refusal code fails closed", async (t) => {
+	const refusalCodes = [
+		"immutable_review_transport_unsupported",
+		"unsupported_agent",
+		"unknown_flag",
+	];
+	for (const refusalCode of refusalCodes) {
+		const cwd = repository(t);
+		const { native, agents } = transportAwareNative({ refusalCode });
+		const result = await runCapture(cwd, native, `refusal-${refusalCode}`);
+		assert.equal(result.status, "blocked", `${refusalCode} must be blocked`);
+		assert.equal(result.outcome, "pi-host-relay-transport-unavailable", `${refusalCode} must use the unavailable envelope`);
+		assert.equal((result.relay_transport as { code: string }).code, refusalCode);
+		assert.deepEqual(agents, ["pi"], `${refusalCode} must not fall back to agent-less STATUS`);
+		__testing.clearReviewTransportProbeForTesting(native);
+	}
+});
+
+test("typed status errors outside the Pi transport refusal set remain native errors", async (t) => {
+	const cwd = repository(t);
+	const { native, agents } = transportAwareNative({ refusalCode: "provider_unavailable" });
+	const result = await runCapture(cwd, native, "non-transport-status-error");
+	assert.deepEqual(agents, ["pi"], "a non-transport error must not be retried as an agent-less lifecycle STATUS");
+	assert.equal(result.status, "blocked");
+	assert.equal(result.outcome, undefined, "a non-transport error must not be coerced into a transport refusal envelope");
+	assert.ok("native_failure" in result, "the native error envelope must remain available to the caller");
+	assert.equal(result.relay_transport, undefined);
+});
+
+test("ordinary STATUS inspection uses the Pi public collect-binding route", async (t) => {
+	const cwd = repository(t);
+	const { native, agents } = transportAwareNative();
+	const result = await runStatus(cwd, native, "ordinary-status-lineage");
+	assert.deepEqual(agents, ["pi"], "ordinary STATUS must request the Pi public collect-binding route");
+	assert.equal(result.operation, "status");
+});

package/tests/review-snapshot.test.ts

@@ -2,9 +2,10 @@ import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
 import {
 	existsSync,
-	mkdtempSync,
 	mkdirSync,
+	mkdtempSync,
 	readFileSync,
+	realpathSync,
 	rmSync,
 	writeFileSync,
 } from "node:fs";
@@ -60,7 +61,7 @@ function createRepository(t: test.TestContext): {
 	repository: string;
 	git: (...args: string[]) => string;
 } {
-	const parent = mkdtempSync(join(tmpdir(), "gentle-pi-snapshot-"));
+	const parent = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-snapshot-")));
 	const repository = join(parent, "repo");
 	mkdirSync(repository);
 	t.after(() => rmSync(parent, { recursive: true, force: true }));