gentle-pi 4.0.0 → 4.2.0

package/tests/review-controller-native-routing.test.ts

@@ -11,7 +11,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { __testing, createGentleAiExtension, PendingReviewConsentRegistry } from "../extensions/gentle-ai.ts";
 import { CandidateViewError, CandidateViewRegistry } from "../lib/review-candidate-view.ts";
 import { NATIVE_REVIEW_ERROR_CODE, NativeReviewCliError, NativeReviewConsentRequiredError, type NativeReviewCli } from "../lib/native-review-cli.ts";
-import { decodeReviewConsentV3, decodeReviewStatusV3, type ReviewCollectInputV3, type ReviewStatusV3 } from "../lib/review-integration-v2.ts";
+import { decodeReviewLastEventClosureV1, decodeReviewConsentV3, decodeReviewStatusV3, type ReviewCollectInputV3, type ReviewStatusV3 } from "../lib/review-integration-v2.ts";
 
 const SHA = `sha256:${"a".repeat(64)}`;
 const TREE = "b".repeat(40);
@@ -129,6 +129,149 @@ test("STATUS renders the managed_assets_outdated continuation command as the act
 	assert.equal(degraded.hint, undefined);
 });
 
+test("caller-relative STATUS approved guidance preserves selected root against a different session", async () => {
+	const lineageId = "caller-relative-status";
+	const root = realpathSync(process.cwd());
+	const native = { targetStatus: async () => approvedAcknowledgementStatus(lineageId, root) } as unknown as NativeReviewCli;
+	const result = await __testing.executeReviewControllerOperation({ operation: "status", lineageId, workspaceRoot: root }, dirname(root), native);
+	assert.equal(result.next_action, `gentle_review {"operation":"acknowledge-approved","lineageId":"${lineageId}","workspaceRoot":${JSON.stringify(root)}}`);
+});
+
+test("caller-relative approved closure guidance preserves selected root and canonical omission", async () => {
+	const lineageId = "caller-relative-closure";
+	const root = realpathSync(process.cwd());
+	const { submission: _submission, artifactSubject: _artifactSubject, ...base } = collectInput(lineageId);
+	const input = { ...base, name: "provider_refuter", schema: "https://gentle-ai.dev/schema/review/refuter/v1", captureOperation: "review.capture-refuter", arguments: [
+		{ name: "lineage", value: lineageId, token: `--lineage=${lineageId}` },
+		{ name: "target", value: SHA, token: `--target=${SHA}` },
+		{ name: "agent", value: "pi", token: "--agent=pi" },
+		{ name: "execute", value: "true", token: "--execute=true" },
+	] } as unknown as ReviewCollectInputV3;
+	const transition = approvedAcknowledgementStatus(lineageId, root).nextTransition;
+	assert.equal(transition?.kind, "execute");
+	if (transition?.kind !== "execute") throw new Error("expected acknowledgement transition");
+	const acknowledgement = transition.execute;
+	const native = {
+		targetStatus: async () => ({ ...status(lineageId), nextTransition: { kind: "collect", reasonCode: "provider_role_required", collect: { inputs: [input] } } }),
+		captureProviderRole: async () => ({ schema: "gentle-ai.review-last-event-closure/v1", operation: "review.capture-refuter", lineageId, state: "approved", storeRevision: SHA, acknowledgement }),
+	} as unknown as NativeReviewCli;
+	const result = await __testing.executeReviewCaptureOperation({ lineageId, workspaceRoot: root, collectBinding: JSON.stringify(input) }, dirname(root), native);
+	assert.equal(result.next_action, `gentle_review {"operation":"acknowledge-approved","lineageId":"${lineageId}","workspaceRoot":${JSON.stringify(root)}}`);
+	const canonical = await __testing.executeReviewCaptureOperation({ lineageId, collectBinding: JSON.stringify(input) }, root, native);
+	assert.equal(canonical.next_action, `gentle_review {"operation":"acknowledge-approved","lineageId":"${lineageId}"}`);
+	assert.deepEqual((result.closure as Record<string, unknown>).acknowledgement, (canonical.closure as Record<string, unknown>).acknowledgement);
+	// This root-only registry double models a remembered lineage without a
+	// frozen projection, and enforces the same root identity at admission.
+	const boundViews = {
+		resolveWorkspaceRoot: (requestedLineage: string) => {
+			assert.equal(requestedLineage, lineageId);
+			return root;
+		},
+		assertWorkspaceRoot: (requestedLineage: string, requestedRoot: string) => {
+			assert.equal(requestedLineage, lineageId);
+			assert.equal(realpathSync(requestedRoot), root);
+		},
+		hasProjection: () => false,
+	} as unknown as CandidateViewRegistry;
+	const bound = await __testing.executeReviewCaptureOperation({ lineageId, collectBinding: JSON.stringify(input) }, dirname(root), native, undefined, boundViews);
+	assert.equal(bound.next_action, canonical.next_action);
+});
+
+test("caller-relative grouped capture closure preserves selected workspace root", async (t) => {
+	t.after(() => __testing.setReviewHostRelayGroupRunnersForTesting());
+	const lineageId = "caller-relative-grouped";
+	const root = realpathSync(process.cwd());
+	const inputs = (["review-risk", "review-resilience", "review-readability", "review-reliability"] as const).map((lens, order) => {
+		const input = collectInput(lineageId);
+		input.arguments = input.arguments.map((argument) => {
+			const value = argument.name === "lens" ? lens : argument.name === "order" ? String(order) : argument.name === "subject-hash" ? `sha256:${String(order).repeat(64)}` : argument.value;
+			return { ...argument, value, token: `--${argument.name}=${value}` };
+		});
+		input.submission!.argumentTokens = [...input.arguments.map((argument) => argument.token!), "--input={{value}}"];
+		input.arguments = [...input.arguments, { name: "agent", value: "pi", token: "--agent=pi" }, { name: "materialize", value: "true", token: "--materialize=true" }];
+		input.artifactSubject = { ...input.artifactSubject!, lens, selectedOrder: order, subjectHash: `sha256:${String(order).repeat(64)}` };
+		return input;
+	});
+	const transition = approvedAcknowledgementStatus(lineageId, root).nextTransition;
+	if (transition?.kind !== "execute") throw new Error("expected acknowledgement transition");
+	const acknowledgement = transition.execute;
+	const native = { targetStatus: async (request: { cwd: string }) => {
+		assert.equal(request.cwd, root);
+		return { ...status(lineageId, inputs), repositoryContext: { capability: "review.opaque_repository_context", handle: `rctx1_${"c".repeat(64)}`, revision: SHA, targetIdentity: SHA } };
+	} } as unknown as NativeReviewCli;
+	const wireAcknowledgement = { ...acknowledgement, binding: { lineage_id: lineageId, revision: SHA, target_identity: SHA } };
+	const wireClosure = { schema: "gentle-ai.review-last-event-closure/v1", operation: "review/capture-result", lineage_id: lineageId, state: "approved", store_revision: SHA, action: "approved by reviewers", acknowledgement: wireAcknowledgement };
+	const decodedClosure = decodeReviewLastEventClosureV1(wireClosure);
+	assert.equal(decodedClosure.lineageId, lineageId);
+	assert.deepEqual(decodedClosure.acknowledgement?.raw, wireAcknowledgement);
+	let submissions = 0;
+	__testing.setReviewHostRelayGroupRunnersForTesting(async (requests) => requests.map((request) => ({ request, promptByteLength: 64, resultByteLength: 32 })), async () => {
+		submissions += 1;
+		return { promptByteLength: 64, resultByteLength: 32, submission: JSON.stringify(wireClosure) };
+	});
+	const result = await __testing.executeReviewCaptureGroupOperation({ lineageId, workspaceRoot: root, collectBindings: inputs.map((input) => JSON.stringify(input)), reviewerRunAcknowledged: true }, dirname(root), native);
+	assert.equal(submissions, 1, JSON.stringify(result));
+	assert.equal(result.outcome, "native-last-event-closure", JSON.stringify(result));
+	assert.equal(result.next_action, `gentle_review {"operation":"acknowledge-approved","lineageId":"${lineageId}","workspaceRoot":${JSON.stringify(root)}}`);
+});
+
+// Issue #1371: approved status mappings and closure envelopes provide additive next_action
+test("STATUS on approved target renders additive next_action naming exact gentle_review acknowledge-approved invocation", async () => {
+	const lineageId = "status-approved-ack";
+	const native = { targetStatus: async () => approvedAcknowledgementStatus(lineageId) } as unknown as NativeReviewCli;
+	const result = await __testing.executeReviewControllerOperation({ operation: "status", lineageId }, process.cwd(), native);
+	assert.equal(result.status, "blocked");
+	assert.equal(result.next_action, `gentle_review {"operation":"acknowledge-approved","lineageId":"${lineageId}"}`);
+});
+
+test("STATUS on approved target preserves workspaceRoot in next_action when distinct from process cwd", async (t) => {
+	const lineageId = "status-approved-ack-worktree";
+	const worktreeRoot = repository(t);
+	const native = { targetStatus: async () => approvedAcknowledgementStatus(lineageId, worktreeRoot) } as unknown as NativeReviewCli;
+	const result = await __testing.executeReviewControllerOperation({ operation: "status", lineageId, workspaceRoot: worktreeRoot }, worktreeRoot, native);
+	assert.equal(result.status, "blocked");
+	assert.equal(result.next_action, `gentle_review {"operation":"acknowledge-approved","lineageId":"${lineageId}","workspaceRoot":${JSON.stringify(worktreeRoot)}}`);
+});
+
+test("invalid acknowledgement input returns self-healing next_action for canonical lineage and fallback slug otherwise", async (t) => {
+	const lineageId = "canonical-lineage-ack";
+	const native = { targetStatus: async () => approvedAcknowledgementStatus(lineageId) } as unknown as NativeReviewCli;
+
+	// 1. Controller-only input with canonical lineage (no workspaceRoot)
+	const rejectedWithInput = await __testing.executeReviewControllerOperation(
+		{ operation: "acknowledge-approved", lineageId, input: "{}" },
+		process.cwd(),
+		native,
+	);
+	assert.equal(rejectedWithInput.outcome, "native-approved-acknowledgement-input-invalid");
+	assert.equal(rejectedWithInput.reason, "controller-only-input");
+	assert.equal(rejectedWithInput.field, "input");
+	assert.equal(rejectedWithInput.next_action, `gentle_review {"operation":"acknowledge-approved","lineageId":"${lineageId}"}`);
+
+	// 2. Controller-only input with canonical lineage and distinct workspaceRoot
+	const worktreeRoot = repository(t);
+	const rejectedWithWorktree = await __testing.executeReviewControllerOperation(
+		{ operation: "acknowledge-approved", lineageId, input: "{}", workspaceRoot: worktreeRoot },
+		process.cwd(),
+		native,
+	);
+	assert.equal(rejectedWithWorktree.outcome, "native-approved-acknowledgement-input-invalid");
+	assert.equal(
+		rejectedWithWorktree.next_action,
+		`gentle_review {"operation":"acknowledge-approved","lineageId":"${lineageId}","workspaceRoot":${JSON.stringify(worktreeRoot)}}`,
+	);
+
+	// 3. Non-canonical / invalid lineage returns fallback slug
+	const rejectedNonCanonical = await __testing.executeReviewControllerOperation(
+		{ operation: "acknowledge-approved", lineageId: "invalid lineage with newline\n", input: "{}" },
+		process.cwd(),
+		native,
+	);
+	assert.equal(rejectedNonCanonical.outcome, "native-approved-acknowledgement-input-invalid");
+	assert.equal(rejectedNonCanonical.reason, "controller-only-input");
+	assert.equal(rejectedNonCanonical.next_action, "resubmit-the-exact-lineage-without-controller-only-input");
+});
+
 test("public acknowledgement relays one current provider vector and never replays after authority burn", async () => {
 	const lineageId = "acknowledge-approved";
 	const requests: Array<Record<string, unknown>> = [];
@@ -1779,6 +1922,7 @@ test("plain START adopts the pre-lineage selection retained by inspect and delet
 		retained,
 	);
 	assert.equal(started.operation, "start");
+	assert.ok(typeof started.result === "object" && started.result !== null && "lineage_id" in started.result);
 	assert.equal(started.result.lineage_id, "review-started");
 	assert.equal(starts.length, 1);
 	assert.equal(requests.length, 3);
@@ -2234,6 +2378,7 @@ test("a failed START retains a pre-lineage selection for a same-candidate retry"
 			{ operation: "start", input: JSON.stringify({ mode: "ordinary" }) },
 			cwd, native, undefined, null, undefined, retained,
 		);
+		assert.ok(typeof retried.result === "object" && retried.result !== null && "lineage_id" in retried.result);
 		assert.equal(retried.result.lineage_id, "retried");
 		assert.equal(starts, 2);
 		assert.equal(retained.has(`${cwd}\u0000`), false);
@@ -2439,6 +2584,115 @@ test("targeted-validator provider vectors preserve their nonuniform native closu
 	assert.equal("correction_target_identity" in result, false);
 });
 
+test("approved capture closure envelope carries additive next_action alongside untouched raw acknowledgement", async () => {
+	const closureLineage = "review-approved-closure-next-action";
+	const input = {
+		name: "provider_targeted_validator",
+		schema: "https://gentle-ai.dev/schema/review/targeted-validator/v1",
+		captureOperation: "review.capture-validation",
+		arguments: [
+			{ name: "lineage", value: closureLineage, token: `--lineage=${closureLineage}` },
+			{ name: "target", value: SHA, token: `--target=${SHA}` },
+			{ name: "agent", value: "pi", token: "--agent=pi" },
+			{ name: "execute", value: "true", token: "--execute=true" },
+		],
+	} as unknown as ReviewCollectInputV3;
+	const roleStatus = { ...status(closureLineage), nextTransition: { kind: "collect", reasonCode: "provider_role_required", collect: { inputs: [input] } } } as ReviewStatusV3;
+	const ackContinuation = {
+		operation: "review.acknowledge-approved",
+		command: "gentle-ai review acknowledge-approved --provider-vector",
+		arguments: [
+			{ name: "cwd", value: process.cwd(), token: `--cwd=${process.cwd()}` },
+			{ name: "lineage", value: closureLineage, token: `--lineage=${closureLineage}` },
+			{ name: "target", value: SHA, token: `--target=${SHA}` },
+			{ name: "expected-revision", value: SHA, token: `--expected-revision=${SHA}` },
+			{ name: "token", value: "provider-tok", token: "--token=provider-tok" },
+		],
+		preconditions: [{ name: "state", value: "approved" }],
+		binding: { lineageId: closureLineage, revision: SHA, targetIdentity: SHA },
+	};
+	const native = {
+		targetStatus: async () => roleStatus,
+		captureProviderRole: async () => ({
+			schema: "gentle-ai.review-last-event-closure/v1",
+			operation: "review/capture-validation",
+			lineageId: closureLineage,
+			state: "approved",
+			action: "approved by validator",
+			storeRevision: SHA,
+			acknowledgement: {
+				operation: "review.acknowledge-approved",
+				command: "gentle-ai review acknowledge-approved --provider-vector",
+				arguments: ackContinuation.arguments,
+				preconditions: ackContinuation.preconditions,
+				binding: ackContinuation.binding,
+				raw: ackContinuation,
+			},
+		}),
+	} as unknown as NativeReviewCli;
+	const result = await __testing.executeReviewCaptureOperation({ lineageId: closureLineage, collectBinding: JSON.stringify(input) }, process.cwd(), native);
+	assert.equal(result.status, "closed");
+	assert.equal(result.outcome, "native-last-event-closure");
+	assert.equal(result.next_action, `gentle_review {"operation":"acknowledge-approved","lineageId":"${closureLineage}"}`);
+	assert.equal((result.closure as { next_action?: string }).next_action, `gentle_review {"operation":"acknowledge-approved","lineageId":"${closureLineage}"}`);
+	assert.deepEqual((result.closure as { acknowledgement?: unknown }).acknowledgement, ackContinuation);
+});
+
+test("approved capture closure envelope preserves workspaceRoot in next_action when distinct from process cwd", async (t) => {
+	const closureLineage = "review-approved-closure-next-action-worktree";
+	const worktreeRoot = repository(t);
+	const input = {
+		name: "provider_targeted_validator",
+		schema: "https://gentle-ai.dev/schema/review/targeted-validator/v1",
+		captureOperation: "review.capture-validation",
+		arguments: [
+			{ name: "lineage", value: closureLineage, token: `--lineage=${closureLineage}` },
+			{ name: "target", value: SHA, token: `--target=${SHA}` },
+			{ name: "agent", value: "pi", token: "--agent=pi" },
+			{ name: "execute", value: "true", token: "--execute=true" },
+		],
+	} as unknown as ReviewCollectInputV3;
+	const roleStatus = { ...status(closureLineage), nextTransition: { kind: "collect", reasonCode: "provider_role_required", collect: { inputs: [input] } } } as ReviewStatusV3;
+	const ackContinuation = {
+		operation: "review.acknowledge-approved",
+		command: "gentle-ai review acknowledge-approved --provider-vector",
+		arguments: [
+			{ name: "cwd", value: worktreeRoot, token: `--cwd=${worktreeRoot}` },
+			{ name: "lineage", value: closureLineage, token: `--lineage=${closureLineage}` },
+			{ name: "target", value: SHA, token: `--target=${SHA}` },
+			{ name: "expected-revision", value: SHA, token: `--expected-revision=${SHA}` },
+			{ name: "token", value: "provider-tok", token: "--token=provider-tok" },
+		],
+		preconditions: [{ name: "state", value: "approved" }],
+		binding: { lineageId: closureLineage, revision: SHA, targetIdentity: SHA },
+	};
+	const native = {
+		targetStatus: async () => roleStatus,
+		captureProviderRole: async () => ({
+			schema: "gentle-ai.review-last-event-closure/v1",
+			operation: "review/capture-validation",
+			lineageId: closureLineage,
+			state: "approved",
+			action: "approved by validator",
+			storeRevision: SHA,
+			acknowledgement: {
+				operation: "review.acknowledge-approved",
+				command: "gentle-ai review acknowledge-approved --provider-vector",
+				arguments: ackContinuation.arguments,
+				preconditions: ackContinuation.preconditions,
+				binding: ackContinuation.binding,
+				raw: ackContinuation,
+			},
+		}),
+	} as unknown as NativeReviewCli;
+	const result = await __testing.executeReviewCaptureOperation({ lineageId: closureLineage, collectBinding: JSON.stringify(input), workspaceRoot: worktreeRoot }, worktreeRoot, native);
+	assert.equal(result.status, "closed");
+	assert.equal(result.outcome, "native-last-event-closure");
+	assert.equal(result.next_action, `gentle_review {"operation":"acknowledge-approved","lineageId":"${closureLineage}","workspaceRoot":${JSON.stringify(worktreeRoot)}}`);
+	assert.equal((result.closure as { next_action?: string }).next_action, `gentle_review {"operation":"acknowledge-approved","lineageId":"${closureLineage}","workspaceRoot":${JSON.stringify(worktreeRoot)}}`);
+	assert.deepEqual((result.closure as { acknowledgement?: unknown }).acknowledgement, ackContinuation);
+});
+
 test("targeted-validator captures echo the distinct provider correction target identity", async () => {
 	const closureLineage = "review-validator-correction-target";
 	const correctionTarget = `sha256:${"d".repeat(64)}`;

package/tests/review-controller-workspace-root.test.ts

@@ -38,7 +38,7 @@ function runtime(
 	const tools = new Map<string, RegisteredTool>();
 	let toolCall: ToolCallHandler | undefined;
 	const handlers = new Map<string, (event: unknown, ctx: ExtensionContext) => unknown>();
-	const dependencies = { nativeReviewCli, candidateViews } as unknown as Parameters<typeof createGentleAiExtension>[0];
+	const dependencies = { nativeReviewCli, candidateViews, processEnv: { GENTLE_PI_AGENTS_CHILD: "0" } } as unknown as Parameters<typeof createGentleAiExtension>[0];
 	createGentleAiExtension(dependencies)({
 		on(name: string, handler: ToolCallHandler) {
 			if (name === "tool_call") toolCall = handler;
@@ -192,6 +192,47 @@ test("invalid bootstrap target selectors reject before native STATUS", async ()
 	assert.equal(statusCalls, 0);
 });
 
+test("START forwards the agent lens selection in canonical order and rejects malformed selections before native STATUS", async (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "app.ts"), "export const value = 2;\n");
+	const startRequests: Parameters<NativeReviewCli["start"]>[0][] = [];
+	const { controller } = runtime(fakeNative({
+		start: async (request) => {
+			startRequests.push(request);
+			return { lineageId: "lens-selection-lineage", state: "reviewing", riskLevel: "medium", selectedLenses: ["review-risk", "review-reliability"], changedFiles: 1, changedLines: 1, correctionBudget: 1, action: "created", lensesRequired: true };
+		},
+	}));
+	const started = await controller.execute("start-lenses", { operation: "start", input: JSON.stringify({ mode: "ordinary", lenses: ["reliability", "review-risk"], lensesReason: "changes token parsing" }) }, undefined, undefined, context(cwd));
+	assert.notEqual((started.details as { status?: string }).status, "blocked");
+	assert.equal(startRequests.length, 1);
+	assert.deepEqual(startRequests[0]?.lenses, ["review-risk", "review-reliability"]);
+	assert.equal(startRequests[0]?.lensesReason, "changes token parsing");
+
+	let statusCalls = 0;
+	const native = fakeNative({
+		reviewMode: async () => ({ operation: "status", scope: "clone", status: { global: "on", cloneLocal: "", effective: "on", source: "global" } }),
+		targetStatus: async () => { statusCalls += 1; throw new Error("must not reach STATUS"); },
+		start: async () => { throw new Error("must not reach START"); },
+	});
+	for (const input of [
+		{ mode: "ordinary", lenses: ["risk"] },
+		{ mode: "ordinary", lensesReason: "why" },
+		{ mode: "ordinary", lenses: [], lensesReason: "why" },
+		{ mode: "ordinary", lenses: "risk", lensesReason: "why" },
+		{ mode: "ordinary", lenses: ["security"], lensesReason: "why" },
+		{ mode: "ordinary", lenses: ["risk", "review-risk"], lensesReason: "why" },
+		{ mode: "ordinary", lenses: ["risk"], lensesReason: " " },
+		{ mode: "ordinary", lenses: ["risk"], lensesReason: "x".repeat(501) },
+		{ mode: "ordinary", lenses: ["risk"], lensesReason: "why", focus: "risk" },
+	]) {
+		const result = await __testing.executeReviewControllerOperation({ operation: "start", input: JSON.stringify(input) }, cwd, native);
+		assert.equal(result.status, "blocked", JSON.stringify(input));
+		assert.equal(result.reason, "lenses-invalid", JSON.stringify(input));
+		assert.equal(result.outcome, "native-start-input-invalid", JSON.stringify(input));
+	}
+	assert.equal(statusCalls, 0);
+});
+
 test("repository discovery ignores ambient Git root overrides", async (t) => {
 	const sessionRoot = repository(t);
 	const targetRoot = repository(t, "gentle-pi-isolated-target-");
@@ -698,7 +739,7 @@ test("same-session START binding migrates to one validation capture without a FI
 		captureProviderRole: async (request) => {
 			captureCalls += 1;
 			assert.equal(request.captureOperation, "review.capture-validation");
-			return { schema: "gentle-ai.review-last-event-closure/v1", operation: "review.capture-validation", lineageId, state: "approved", storeRevision: `sha256:${"a".repeat(64)}` };
+			return { schema: "gentle-ai.review-last-event-closure/v1", operation: "review/capture-validation", lineageId, state: "approved", storeRevision: `sha256:${"a".repeat(64)}` };
 		},
 	});
 	const { controller } = runtime(native, candidateViews);

package/tests/review-controller.test.ts

@@ -371,9 +371,9 @@ test("failed START gives exact mode and serialization guidance and creates no li
 			operation: "start",
 			lineageId: "nested-start-input",
 			idempotencyKey: "nested-start-input-key",
-			input: { mode: "ordinary" },
+			input: { mode: "standard" },
 		}, undefined, undefined, ctx),
-		/START input must be a JSON string.*no lineage was created.*do not call STATUS or ADVANCE/is,
+		/only "ordinary" or "judgment-day".*no lineage was created.*do not call STATUS or ADVANCE/is,
 	);
 	await assert.rejects(
 		controller.execute("invalid-json-start-input", {

package/tests/review-correction-lifecycle.test.ts

@@ -61,7 +61,7 @@ test("passed is the only outcome that unlocks targeted validation", () => {
 	assert.equal(step.kind, "run-targeted-validation");
 	assert.equal(step.unlocksTargetedValidation, true);
 	assert.equal(step.transactionOpen, false);
-	assert.equal(step.escalation, undefined);
+	assert.equal(Object.hasOwn(step, "escalation"), false);
 	// The provider issues the request; Pi must re-query STATUS for it rather
 	// than inventing one, which is why the step names the operation instead of
 	// carrying a fabricated payload.
@@ -95,6 +95,7 @@ test("verification_failed carries the prior identity as supersedes and demands a
 test("verification_failed never consumes budget even when lines were already charged", () => {
 	const charged = { ...STATUS, changedLinesCharged: 40 };
 	const step = resolveCorrectionStep(charged, evidence("verification_failed"));
+	assert.equal(step.kind, "recapture-required");
 
 	// The invariant is about what THIS outcome adds, not about resetting prior
 	// accounting: a failed verification must not move the needle at all.

package/tests/review-gate.test.ts

@@ -14,6 +14,7 @@ import {
 	recheckReleaseFastPathRemoteHeadV1,
 	resolveConfiguredPushDestinationV1,
 	type GateTargetV1,
+	type ReleaseGateTargetV1,
 	type GhCommandRunnerV1,
 	type ReleaseFastPathEvidenceV1,
 } from "../lib/review-publication-gate.ts";
@@ -177,14 +178,14 @@ function temporaryAuthority(t: test.TestContext): GateRepository & {
 test("unbranded receipts are rejected before lifecycle gate evaluation", (t) => {
 	const { repository, finalTree, store, receipt } = temporaryAuthority(t);
 	execFileSync("git", ["read-tree", finalTree], { cwd: repository });
-	assert.throws(() => validateReviewGate({
+	assert.throws(() => Reflect.apply(validateReviewGate, undefined, [{
 		store,
 		receipt,
 		target: { kind: GATE_TARGET_KIND.INTENDED_COMMIT, intended_commit_tree: finalTree },
 		repositoryCwd: repository,
 		idempotencyKey: "unbranded-gate",
 		scopeBudget: budget(),
-	}), /branded authoritative receipt/i);
+	}]), /branded authoritative receipt/i);
 });
 
 test("authoritative receipts cannot be validated through another repository store", (t) => {
@@ -333,6 +334,7 @@ test("push gate allows normal same-name updates while preserving exact-old and c
 	const driftedUpdate = {
 		kind: GATE_TARGET_KIND.PUSH,
 		remote,
+		destination_id: target.destination_id,
 		updates: [{
 			...target.updates[1],
 			old_object: finalCommit,
@@ -347,6 +349,7 @@ test("push gate allows normal same-name updates while preserving exact-old and c
 	const createOverExisting = {
 		kind: GATE_TARGET_KIND.PUSH,
 		remote,
+		destination_id: target.destination_id,
 		updates: [{ ...target.updates[0], destination_ref: "refs/heads/final" }],
 	} as const;
 	assert.equal(
@@ -580,7 +583,7 @@ test("scope child claim and parent gate journal publish atomically across faults
 	assert.equal(store.read(receipt.body.lineage_id).child_claims?.length, 1);
 });
 
-function releaseTarget(repository: GateRepository): GateTargetV1 {
+function releaseTarget(repository: GateRepository): ReleaseGateTargetV1 {
 	return {
 		kind: GATE_TARGET_KIND.RELEASE,
 		tag_ref: "refs/tags/v1.2.3",
@@ -628,7 +631,7 @@ test("release fast path independently accepts complete successful Check Runs des
 	const repository = createGateRepository(t);
 	setRemoteMain(repository, repository.finalCommit);
 	const calls: string[][] = [];
-	const checkRuns = (checks: unknown[], totalCount = checks.length, legacyStatus = "pending"): GhCommandRunnerV1 => (args) => {
+	const checkRuns = (checks: readonly unknown[], totalCount = checks.length, legacyStatus = "pending"): GhCommandRunnerV1 => (args) => {
 		calls.push([...args]);
 		if (args[1] === `repos/{owner}/{repo}/commits/${repository.finalCommit}/check-runs?per_page=100`) {
 			return { status: 0, stdout: JSON.stringify({ total_count: totalCount, returned: checks.length, checks }) };

package/tests/review-graph-schema.test.ts

@@ -63,8 +63,8 @@ test("event schema commits a canonical reducer transition and input", () => {
 		payload: { initial: true },
 		reduced_state_hash: stateHash,
 	} as never);
-	assert.equal((event.body as Record<string, unknown>).reducer_transition, "start");
-	assert.deepEqual((event.body as Record<string, unknown>).reducer_input, { source: "controller" });
+	assert.equal(event.body.reducer_transition, "start");
+	assert.deepEqual(event.body.reducer_input, { source: "controller" });
 	assert.throws(() => createReviewEventV1({
 		lineage_id: "lineage-a",
 		sequence: 0,

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

@@ -211,6 +211,8 @@ function nativeHarness(statuses: readonly ReviewStatusV3[], unachievableResponde
 		native: undefined as unknown as NativeReviewCli,
 	};
 	harness.native = {
+		start: async () => { throw new Error("unexpected START"); },
+		reviewStatus: async () => { throw new Error("unexpected compact STATUS"); },
 		targetStatus: async (request) => {
 			harness.statusCalls.push({ cwd: request.cwd, ...(request.lineageId === undefined ? {} : { lineageId: request.lineageId }), ...(request.agent === undefined ? {} : { agent: request.agent }) });
 			const next = harness.statusQueue.shift();
@@ -226,7 +228,7 @@ async function runCapture(cwd: string, harness: RoutingHarness, lineageId: strin
 	const selected = harness.statusQueue[0]?.nextTransition?.collect?.inputs[0];
 	if (selected === undefined) throw new Error("capture test requires one current collect input");
 	return await __testing.executeReviewCaptureOperation(
-		{ lineageId, collectBinding: JSON.stringify(selected), ...input },
+		{ lineageId, collectBinding: selected, ...input },
 		cwd,
 		harness.native,
 		undefined, undefined, undefined, false, modelRegistry,
@@ -436,9 +438,9 @@ test("Pi-authored review documents are rejected at the capture input boundary",
 	assert.equal(relayCalls, 0);
 });
 
-function groupInputs(lineageId: string, revision = SHA): ReviewCollectInputV3[] { return ["review-risk", "review-resilience", "review-readability", "review-reliability"].map((lens, order) => relayCollectInput(lineageId, lens, order, true, "provider", revision)); }
+function groupInputs(lineageId: string, revision = SHA): ReviewCollectInputV3[] { return (["review-risk", "review-resilience", "review-readability", "review-reliability"] as const).map((lens, order) => relayCollectInput(lineageId, lens, order, true, "provider", revision)); }
 
-async function runCaptureGroup(cwd: string, harness: RoutingHarness, lineageId: string, inputs: readonly ReviewCollectInputV3[], reviewerRunAcknowledged = true, modelRegistry?: InProcessReviewerRegistry): Promise<Record<string, unknown>> { return await __testing.executeReviewCaptureGroupOperation({ lineageId, collectBindings: inputs.map((input) => JSON.stringify(input)), reviewerRunAcknowledged }, cwd, harness.native, undefined, undefined, undefined, false, modelRegistry) as Record<string, unknown>; }
+async function runCaptureGroup(cwd: string, harness: RoutingHarness, lineageId: string, inputs: readonly ReviewCollectInputV3[], reviewerRunAcknowledged = true, modelRegistry?: InProcessReviewerRegistry): Promise<Record<string, unknown>> { return await __testing.executeReviewCaptureGroupOperation({ lineageId, collectBindings: inputs.map((input, index) => index % 2 === 0 ? input : JSON.stringify(input)), reviewerRunAcknowledged }, cwd, harness.native, undefined, undefined, undefined, false, modelRegistry) as Record<string, unknown>; }
 
 function prepared(request: ReviewHostRelayRequest) { return { request, promptByteLength: 64, resultByteLength: 32 }; }
 

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

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import { createNodeExecFileAdapter } from "../lib/native-review-cli.ts";
+import { setBundledInstallForTesting } from "../lib/gentle-shell-bundled.ts";
 import { INPROCESS_REVIEWER_FAILURE, type InProcessReviewerOutcome, type InProcessReviewerRequest, type InProcessReviewerDeps, runInProcessReviewer } from "../lib/inprocess-reviewer.ts";
 import {
 	REVIEW_HOST_RELAY_FAILURE,
@@ -53,7 +54,7 @@ const FAKE_GENTLE_AI = `#!/usr/bin/env node
 const fs = require("node:fs");
 const path = require("node:path");
 const argv = process.argv.slice(2);
-if (process.env.RELAY_FAKE_LOG) fs.appendFileSync(process.env.RELAY_FAKE_LOG, JSON.stringify({ argv, cwd: process.cwd(), contract: process.env.${GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV} ?? null }) + "\\n");
+if (process.env.RELAY_FAKE_LOG) fs.appendFileSync(process.env.RELAY_FAKE_LOG, JSON.stringify({ argv, cwd: process.cwd(), contract: process.env.${GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV} ?? null, home: process.env.GENTLE_AI_HOME ?? null }) + "\\n");
 if (argv.some((token) => token === "--materialize" || token.startsWith("--materialize="))) {
 	const mode = process.env.RELAY_FAKE_MATERIALIZE_MODE || "ok";
 	if (mode === "ok") { process.stdout.write(Buffer.from(process.env.RELAY_FAKE_PROMPT_B64 || "", "base64")); process.exit(0); }
@@ -137,7 +138,7 @@ function harness(t: test.TestContext, overrides: Record<string, string> = {}): R
 	return { directory, gentleAi, logPath, submitCapturePath, targetCwd, environment };
 }
 
-function readLog(path: string): Array<{ argv: string[]; contract: string | null; cwd?: string }> {
+function readLog(path: string): Array<{ argv: string[]; contract: string | null; cwd?: string; home?: string | null }> {
 	if (!existsSync(path)) return [];
 	return readFileSync(path, "utf8").split("\n").filter((line) => line.length > 0).map((line) => JSON.parse(line));
 }
@@ -273,6 +274,24 @@ test("the central native CLI runner declares the relay contract on every gentle-
 	}
 });
 
+// S9: in a bundled install (the testing overlay stands in for this package
+// running from it) both relay invocations get Gentle AI's isolation
+// variables; otherwise neither does.
+test("both relay gentle-ai invocations carry Gentle AI's isolation variables only in a bundled install", async (t) => {
+	const ordinary = harness(t);
+	await runRelay(ordinary);
+	assert.deepEqual(readLog(ordinary.logPath).map((call) => call.home), [null, null]);
+	const prefix = realpathSync(mkdtempSync(join(tmpdir(), "gentle-ai-isolation-relay-")));
+	setBundledInstallForTesting({ root: prefix });
+	t.after(() => {
+		setBundledInstallForTesting(undefined);
+		rmSync(prefix, { recursive: true, force: true });
+	});
+	const bundled = harness(t, { GENTLE_SHELL_PREFIX: prefix });
+	await runRelay(bundled);
+	assert.deepEqual(readLog(bundled.logPath).map((call) => call.home), [join(prefix, "gentle-ai"), join(prefix, "gentle-ai")]);
+});
+
 test("relay contract constants are the compiled gentle-ai handshake values", () => {
 	assert.equal(GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV, "GENTLE_PI_REVIEW_RELAY_CONTRACT");
 	assert.equal(GENTLE_PI_REVIEW_RELAY_CONTRACT, "gentle-pi.review-relay/v1");
@@ -1036,3 +1055,31 @@ test("the negotiated decoder carries the provider submission through the capture
 		submission: { ...rawSubmission, values: [{ slot: "reviewer_result", domain: "artifact_path_or_stdin", substitution_location: rawSubmission.argument_tokens.length }] },
 	}] } }), /substitution_location/);
 });
+
+for (const transport of ["sse", "websocket", "websocket-cached", "auto", undefined] as const) {
+	test(`relay forwards reviewer transport ${transport ?? "absent"} unchanged`, async (t) => {
+		const fixture = harness(t);
+		const reviewer = textReviewer(REVIEWER_TEXT);
+		const result = await runRelay(fixture, { reviewerTransport: transport }, reviewer.runReviewer);
+		assert.equal(reviewer.calls.length, 1);
+		assert.equal(reviewer.calls[0]!.transport, transport);
+		assert.equal(Object.hasOwn(reviewer.calls[0]!, "transport"), transport !== undefined);
+		assert.equal(reviewer.calls[0]!.selection, "openai/gpt-5");
+		assert.equal(result.resultByteLength, Buffer.byteLength(REVIEWER_TEXT));
+		assert.equal(readFileSync(fixture.submitCapturePath, "utf8"), REVIEWER_TEXT);
+	});
+
+	test(`group relay forwards reviewer transport ${transport ?? "absent"} to every completion`, async (t) => {
+		const fixture = harness(t);
+		const reviewer = textReviewer(REVIEWER_TEXT);
+		const requests = reviewerGroupRequests(fixture).map((request) => ({ ...request, reviewerTransport: transport }));
+		const results = await runReviewHostRelayReviewerGroup(requests, (request) => prepareReviewHostRelaySlot(request, reviewer.runReviewer));
+		assert.equal(results.length, requests.length);
+		assert.equal(reviewer.calls.length, requests.length);
+		for (const request of reviewer.calls) {
+			assert.equal(request.transport, transport);
+			assert.equal(Object.hasOwn(request, "transport"), transport !== undefined);
+		}
+		assert.equal(readLog(fixture.logPath).length, requests.length, "group preparation only materializes, never submits");
+	});
+}

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

@@ -947,7 +947,7 @@ test("review-acknowledged/v1 is disjoint from every prior captured identity in b
 		["status/v3", decodeReviewStatusV3],
 		["start/v3", decodeReviewStartV3],
 		["start/v4", decodeReviewStartV4],
-		["capabilities/v2", decodeReviewCapabilitiesV2],
+		["capabilities/v2", (value) => decodeReviewCapabilitiesV2(value, CAPTURED_DIGEST)],
 		["consent/v2", decodeReviewConsentV2],
 		["consent/v3", decodeReviewConsentV3],
 		["last-event-closure/v1", decodeReviewLastEventClosureV1],
@@ -1004,3 +1004,23 @@ test("v7 escalation strictly decodes all causes and optional refuter evidence",
 		assert.throws(() => decodeReviewStatusV3({ ...escalatedStatusV7(), schema: `gentle-ai.review-integration.status/v${version}` }), /not allowed/);
 	}
 });
+
+test("START/v4 accepts every risk reason code and signal the published start schema allows", () => {
+	// gentle-ai publishes dangerous_sink (code and signal) and agent_escalation
+	// (code and signal) in start-v4.schema.json; a high-risk START that names
+	// them must decode instead of failing as schema-incompatible (#5374).
+	const start = reviewingStartV4();
+	start.risk_reasons = [
+		{ code: "dangerous_sink", signal: "dangerous_sink", path: "auth/session.py" },
+		{ code: "hot_path", signal: "auth", path: "auth/session.py" },
+		{ code: "process_boundary", signal: "shell_process", path: "auth/session.py" },
+		{ code: "agent_escalation", signal: "agent_escalation" },
+	];
+	const decoded = decodeReviewStartV4(start);
+	assert.deepEqual(decoded.riskReasons.map((reason) => reason.code), ["dangerous_sink", "hot_path", "process_boundary", "agent_escalation"]);
+	assert.deepEqual(decoded.riskReasons.map((reason) => reason.signal), ["dangerous_sink", "auth", "shell_process", "agent_escalation"]);
+
+	const unknown = reviewingStartV4();
+	unknown.risk_reasons = [{ code: "code_from_a_newer_cli" }];
+	assert.throws(() => decodeReviewStartV4(unknown), /risk_reasons\[0\]\.code is unsupported/);
+});