gentle-pi 2.2.0 → 2.3.0

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

@@ -91,8 +91,7 @@ function recoveredStatus(lineageId: string, materialize: boolean): ReviewStatusV
 		contract: "gentle-ai.review-integration/v2",
 		applicability: "current_target",
 		authority: { version: "compact-v2", lineageId, state: "reviewer_results_required", generation: 2, revision: SHA },
-		receipt: { status: "expected_missing" },
-		action: "finalize",
+		action: "stop",
 		replayability: "not_replayable",
 		targetIdentity: SHA,
 		projection: {
@@ -111,7 +110,7 @@ function recoveredStatus(lineageId: string, materialize: boolean): ReviewStatusV
 		},
 		candidates: [],
 		nextTransition: { kind: "collect", reasonCode: "reviewer_results_required", collect: { inputs: [collectInput(lineageId, materialize)] } },
-		raw: { schema: "gentle-ai.review-integration.status/v5", action: "finalize", lineage_id: lineageId },
+		raw: { schema: "gentle-ai.review-integration.status/v5", action: "stop", lineage_id: lineageId },
 	} as unknown as ReviewStatusV3;
 }
 
@@ -119,18 +118,21 @@ function recoveredStatus(lineageId: string, materialize: boolean): ReviewStatusV
  * Mirrors the MEASURED live provider: the materialize-marked relay slot is
  * offered only when the caller asks for the pi agent.
  */
-function transportAwareNative(options: { refusePiAgent?: boolean } = {}): { native: NativeReviewCli; agents: Array<string | undefined> } {
+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.refusePiAgent === true) {
+			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: TRANSPORT_REFUSAL_CODE,
+					code: options.refusalCode,
 					message: "supported immutable review runtimes: claude-code, opencode, codex",
 					mutationOutcome: "none",
 					authorityApplicability: "current_target",
@@ -142,15 +144,22 @@ function transportAwareNative(options: { refusePiAgent?: boolean } = {}): { nati
 			}
 			return recoveredStatus(request.lineageId ?? "relay-lineage", request.agent === "pi");
 		},
-		finalize: async () => { throw new Error("native finalize must not run while reviewer results are outstanding"); },
 	} as unknown as NativeReviewCli;
 	return { native, agents };
 }
 
-async function runFinalize(cwd: string, native: NativeReviewCli, lineageId: string, input: Record<string, unknown> = { reviewer_run_acknowledged: true }): Promise<Record<string, unknown>> {
+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: "finalize", lineageId, input: JSON.stringify(input) },
-		cwd, new Map(), native, undefined, undefined, undefined, new CandidateViewRegistry(),
+		{ operation: "status", lineageId },
+		cwd, native, undefined, new CandidateViewRegistry(),
 	) as Record<string, unknown>;
 }
 
@@ -165,19 +174,19 @@ test("the negotiated status asks for the pi agent so the provider offers its mat
 		return { promptByteLength: 128, resultByteLength: 64, submission: '{"admission_decision":"completed"}' };
 	});
 
-	const result = await runFinalize(cwd, native, lineageId);
+	const result = await runCapture(cwd, native, lineageId);
 
-	assert.ok(agents.includes("pi"), "the controller must negotiate STATUS for the pi reviewer transport");
+	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; captured_slots: readonly unknown[] } | undefined;
-	assert.ok(hostRelay !== undefined, "the envelope reports the relay capture");
+	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");
-	assert.equal(hostRelay.captured_slots.length, 1);
 });
 
-test("finalize forecasts the reviewer model run once and spends nothing until it is acknowledged", async (t) => {
+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";
@@ -188,62 +197,126 @@ test("finalize forecasts the reviewer model run once and spends nothing until it
 		return { promptByteLength: 128, resultByteLength: 64, submission: '{"admission_decision":"completed"}' };
 	});
 
-	// An unacknowledged finalize must forecast, never spend.
-	const forecast = await runFinalize(cwd, native, lineageId, {});
+	// 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[]; side_effects: readonly string[] };
+	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"]);
-	assert.ok(cost.side_effects.length > 0);
-	assert.match(String(forecast.reason), /model run/i);
-	assert.match(String(forecast.next_action), /reviewer_run_acknowledged/);
-
-	// The acknowledged finalize runs exactly the forecast work.
-	const acknowledged = await runFinalize(cwd, native, lineageId, { reviewer_run_acknowledged: true });
-	assert.equal(launches, 1, "the acknowledged finalize runs the forecast model run");
-	assert.equal((acknowledged.host_relay as { captured_slots: readonly unknown[] }).captured_slots.length, 1);
+
+	// 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 surfaces the typed cause and still returns status", async (t) => {
+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({ refusePiAgent: true });
+	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 runFinalize(cwd, native, lineageId);
+	const result = await runCapture(cwd, native, lineageId);
 
-	assert.ok(agents.includes("pi"), "the transport is probed once");
-	assert.ok(agents.includes(undefined), "a refusal falls back to the agent-less status instead of failing the operation");
-	assert.equal(relayCalls, 0, "no relay slot exists on a provider without the pi transport");
-	// Deliverable: the user sees the real typed cause, never a generic
-	// candidate-view message.
+	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 envelope must report the transport refusal");
+	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/);
-	// The lifecycle still routes: reviewer results remain outstanding.
-	assert.equal(result.outcome, "reviewer-results-required");
+	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("the pi transport is probed once per provider and the refusal is remembered", async (t) => {
+test("typed status errors outside the Pi transport refusal set remain native errors", async (t) => {
 	const cwd = repository(t);
-	const { native, agents } = transportAwareNative({ refusePiAgent: true });
-	await runFinalize(cwd, native, "probe-lineage");
-	const afterFirst = agents.filter((agent) => agent === "pi").length;
-	await runFinalize(cwd, native, "probe-lineage");
-	const afterSecond = agents.filter((agent) => agent === "pi").length;
-	assert.equal(afterFirst, 1, "the first flow probes the pi transport exactly once");
-	assert.equal(afterSecond, 1, "a remembered refusal is never re-probed for the same provider");
+	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 }));