gentle-pi 2.0.0 → 2.1.1

package/tests/native-review-consent.test.ts

@@ -0,0 +1,205 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import { GENTLE_AI_VERSION } from "../lib/gentle-ai-binary.ts";
+import {
+	NativeReviewCliV216,
+	NativeReviewConsentBindingError,
+	NativeReviewConsentRequiredError,
+	clearNativeReviewCapabilitiesCacheForTesting,
+	type ExecFileAdapter,
+} from "../lib/native-review-cli.ts";
+import type { ReviewConsentV2 } from "../lib/review-integration-v2.ts";
+
+const fixtureRoot = join(process.cwd(), "contracts", "review-integration", "v2", "fixtures");
+const fixture = <T = Record<string, unknown>>(name: string): T => JSON.parse(readFileSync(join(fixtureRoot, name), "utf8")) as T;
+const executableDigest = "dcc846103b16d365eaeeb9d7f289c23fc4f2897f23def1cb3fe7f05557b64705";
+
+function capabilities(): Record<string, unknown> {
+	const value = fixture<Record<string, unknown>>("capabilities.fixture.json");
+	(value.package as Record<string, unknown>).version = GENTLE_AI_VERSION;
+	return value;
+}
+
+function unrelatedStatus(targetIdentity: string): Record<string, unknown> {
+	const status = fixture<Record<string, unknown>>("status.fixture.json");
+	status.applicability = "unrelated";
+	status.receipt = { status: "not_applicable" };
+	status.action = "start";
+	status.replayability = "not_replayable";
+	status.target_identity = targetIdentity;
+	status.candidates = [];
+	delete status.authority;
+	delete status.frozen;
+	delete status.next_transition;
+	const projection = status.projection as Record<string, unknown>;
+	projection.initial_snapshot_identity = targetIdentity;
+	projection.current_snapshot_identity = targetIdentity;
+	return status;
+}
+
+function queuedAdapter(outputs: readonly Record<string, unknown>[]): { adapter: ExecFileAdapter; calls: Array<readonly string[]> } {
+	const queue = [...outputs];
+	const calls: Array<readonly string[]> = [];
+	return {
+		calls,
+		adapter: async (request) => {
+			calls.push(request.arguments);
+			const body = queue.shift();
+			if (body === undefined) throw new Error("unexpected native invocation");
+			return { stdout: JSON.stringify(body), stderr: "", exitCode: 0, signal: null, timedOut: false, outputLimitExceeded: false };
+		},
+	};
+}
+
+function client(adapter: ExecFileAdapter): NativeReviewCliV216 {
+	clearNativeReviewCapabilitiesCacheForTesting();
+	return new NativeReviewCliV216(adapter, "/package/.gentle-ai/gentle-ai", 30_000, 1024 * 1024, async () => undefined, () => executableDigest);
+}
+
+test("negotiated ordinary START declares relay and preserves the complete target-bound consent envelope", async () => {
+	const consent = fixture<Record<string, unknown>>("consent.fixture.json");
+	const target = String(consent.target_identity);
+	const queue = queuedAdapter([
+		capabilities(),
+		unrelatedStatus(target),
+		consent,
+	]);
+	await assert.rejects(
+		() => client(queue.adapter).start({ cwd: "/repo" }),
+		(error: unknown) => {
+			assert.ok(error instanceof NativeReviewConsentRequiredError);
+			assert.deepEqual(error.consent.raw, consent);
+			assert.equal(error.consent.targetIdentity, target);
+			return true;
+		},
+	);
+	assert.deepEqual(queue.calls.at(-1), [
+		"review", "start", "--contract", "gentle-ai.review-integration/v2", "--cwd", "/repo",
+		"--target", target, "--projection", "workspace", "--consent", "relay",
+	]);
+	assert.equal(queue.calls.some((arguments_) => arguments_[1] === "status"), true);
+});
+
+test("controller-prebound START target is used without projecting a second workspace candidate", async () => {
+	const consent = fixture<Record<string, unknown>>("consent.fixture.json");
+	const target = String(consent.target_identity);
+	const queue = queuedAdapter([capabilities(), consent]);
+	await assert.rejects(
+		() => client(queue.adapter).start({ cwd: "/repo", targetIdentity: target, projection: "workspace" }),
+		(error: unknown) => error instanceof NativeReviewConsentRequiredError,
+	);
+	assert.deepEqual(queue.calls.at(-1), [
+		"review", "start", "--contract", "gentle-ai.review-integration/v2", "--cwd", "/repo",
+		"--target", target, "--projection", "workspace", "--consent", "relay",
+	]);
+	assert.equal(queue.calls.some((arguments_) => arguments_[1] === "status"), false, "a prebound START target must not be projected again");
+});
+
+test("consent follow-up executes the provider-named invocation exactly once and refuses a changed target binding", async () => {
+	const consent = fixture<ReviewConsentV2 extends never ? never : Record<string, unknown>>("consent.fixture.json");
+	const decodedConsent = (await import("../lib/review-integration-v2.ts")).decodeReviewConsentV2(consent);
+	const started = JSON.parse(JSON.stringify(fixture<Record<string, unknown>>("start.fixture.json"))
+		.replaceAll("review-start-fixture", "review-consent-fixture")) as Record<string, unknown>;
+	const queue = queuedAdapter([capabilities(), started]);
+	const native = client(queue.adapter);
+	const result = await native.answerConsent!({ cwd: "/repo", consent: decodedConsent, answer: "granted" });
+	assert.equal(result.kind, "started");
+	assert.deepEqual(queue.calls.at(-1), decodedConsent.choices[0].invocation.split(" ").slice(1));
+	assert.equal(queue.calls.filter((arguments_) => arguments_.includes("granted")).length, 1);
+
+	const changed = structuredClone(decodedConsent);
+	changed.targetIdentity = `sha256:${"b".repeat(64)}`;
+	await assert.rejects(
+		() => native.answerConsent!({ cwd: "/repo", consent: changed, answer: "declined" }),
+		/target|binding/,
+	);
+});
+
+// A binding mismatch is decided entirely inside Pi, before the provider is
+// launched, so it must not be reported as a provider failure (issue #247).
+test("a consent invocation binding mismatch is a typed pre-native error that never launches the provider", async () => {
+	const consent = (await import("../lib/review-integration-v2.ts")).decodeReviewConsentV2(fixture<Record<string, unknown>>("consent.fixture.json"));
+	const queue = queuedAdapter([]);
+	await assert.rejects(
+		() => client(queue.adapter).answerConsent!({ cwd: "/repo/.git/gentle-ai/candidate-views/a1c7fdae", consent, answer: "granted" }),
+		(error: unknown) => {
+			assert.ok(error instanceof NativeReviewConsentBindingError);
+			assert.equal(error.name, "NativeReviewConsentBindingError");
+			assert.equal(error.reason, "consent-invocation-cwd-changed");
+			assert.equal(error.launchAttempted, false);
+			assert.equal(error.mutationOutcome, "none");
+			assert.match(error.message, /repository binding changed/);
+			return true;
+		},
+	);
+	assert.deepEqual(queue.calls, []);
+});
+
+// `decodeReviewConsentV2` already rejects a malformed invocation, so these
+// guards defend against a consent object that drifted after decoding. Each one
+// must still name itself rather than collapse into a generic failure.
+test("every consent invocation binding guard reports its own reason without launching the provider", async () => {
+	const decoded = (await import("../lib/review-integration-v2.ts")).decodeReviewConsentV2(fixture<Record<string, unknown>>("consent.fixture.json"));
+	const drifted = (mutate: (consent: ReviewConsentV2) => void): ReviewConsentV2 => {
+		const value = structuredClone(decoded);
+		mutate(value);
+		return value;
+	};
+	const rewriteGranted = (consent: ReviewConsentV2, replace: (invocation: string) => string): void => {
+		const choice = consent.choices.find((candidate) => candidate.answer === "granted") as { invocation: string };
+		choice.invocation = replace(choice.invocation);
+	};
+	const cases = [
+		{
+			reason: "consent-answer-unknown",
+			consent: drifted((consent) => { (consent as { choices: unknown }).choices = consent.choices.filter((choice) => choice.answer !== "granted"); }),
+		},
+		{ reason: "consent-invocation-not-start", consent: drifted((consent) => rewriteGranted(consent, (value) => value.replace("review start", "review finalize"))) },
+		{ reason: "consent-invocation-contract-changed", consent: drifted((consent) => rewriteGranted(consent, (value) => value.replace("gentle-ai.review-integration/v2", "gentle-ai.review-integration/v1"))) },
+		{ reason: "consent-invocation-target-changed", consent: drifted((consent) => { (consent as { targetIdentity: string }).targetIdentity = `sha256:${"c".repeat(64)}`; }) },
+		{ reason: "consent-invocation-projection-changed", consent: drifted((consent) => { (consent as { projection: string }).projection = "staged"; }) },
+		{ reason: "consent-invocation-answer-changed", consent: drifted((consent) => rewriteGranted(consent, (value) => value.replace("--consent granted", "--consent declined"))) },
+		{ reason: "consent-invocation-option-invalid", consent: drifted((consent) => rewriteGranted(consent, (value) => `${value} --consent granted`)) },
+	] as const;
+	for (const scenario of cases) {
+		const queue = queuedAdapter([]);
+		await assert.rejects(
+			() => client(queue.adapter).answerConsent!({ cwd: "/repo", consent: scenario.consent, answer: "granted" }),
+			(error: unknown) => {
+				assert.ok(error instanceof NativeReviewConsentBindingError, `${scenario.reason} must be a typed binding error`);
+				assert.equal(error.reason, scenario.reason);
+				return true;
+			},
+		);
+		assert.deepEqual(queue.calls, [], `${scenario.reason} must not launch the provider`);
+	}
+});
+
+test("declined consent decodes the provider's explicit empty authority fields without creating a lineage", async () => {
+	const rawConsent = fixture<Record<string, unknown>>("consent.fixture.json");
+	const consent = (await import("../lib/review-integration-v2.ts")).decodeReviewConsentV2(rawConsent);
+	const declined = {
+		operation: "review/start",
+		action: "declined",
+		lenses_required: false,
+		lineage_id: "",
+		state: "",
+		risk_level: "high",
+		selected_lenses: [],
+		lens_bindings: [],
+		projection: "workspace",
+		target_identity: consent.targetIdentity,
+		changed_files: 1,
+		changed_lines: 1,
+		correction_budget: 0,
+		risk_evidence: ["shell scripting in scripts/deploy.sh"],
+		consent: "declined_this_candidate",
+	};
+	const queue = queuedAdapter([capabilities(), declined]);
+	const result = await client(queue.adapter).answerConsent!({ cwd: "/repo", consent, answer: "declined" });
+	assert.equal(result.kind, "declined");
+	assert.equal("lineageId" in result, false);
+	assert.deepEqual(queue.calls.at(-1), consent.choices[1].invocation.split(" ").slice(1));
+});

package/tests/native-review-parity-runtime.test.ts

@@ -378,7 +378,7 @@ test("official pinned package runtime keeps frozen candidate lineages and receip
 	t.diagnostic("pre-push, pre-pr, and release require remote/publication evidence; their network-aware gate contracts remain covered by dedicated gate integration tests rather than this hermetic binary E2E.");
 });
 
-test("registered gentle_review START materializes a safe internal skill symlink before invoking native authority", async (t) => {
+test("registered gentle_review START materializes a safe internal skill symlink and cleans pending consent on session shutdown", async (t) => {
 	const workspace = await mkdtemp(join(tmpdir(), "gentle-pi-v215-symlink-candidate-"));
 	const repository = join(workspace, "repository");
 	t.after(async () => rm(workspace, { recursive: true, force: true }));
@@ -412,8 +412,9 @@ test("registered gentle_review START materializes a safe internal skill symlink
 		return { ...command, signal: null, timedOut: false, outputLimitExceeded: false };
 	});
 	const tools = new Map<string, RegisteredController>();
+	let sessionShutdown: ((event: unknown, context: ExtensionContext) => Promise<void> | void) | undefined;
 	createGentleAiExtension({ nativeReviewCli: native, candidateViews } as Parameters<typeof createGentleAiExtension>[0])({
-		on() {},
+		on(name: string, handler: (event: unknown, context: ExtensionContext) => Promise<void> | void) { if (name === "session_shutdown") sessionShutdown = handler; },
 		registerTool(definition: RegisteredController & { name: string }) { tools.set(definition.name, definition); },
 		registerCommand() {},
 	} as unknown as ExtensionAPI);
@@ -434,8 +435,16 @@ test("registered gentle_review START materializes a safe internal skill symlink
 	t.diagnostic(JSON.stringify({ returned: returned?.details, error, nativeStartReached }));
 	assert.equal(thrown, undefined, "safe internal symlink materialization must not throw before START");
 	assert.equal(nativeStartReached, true, "safe internal symlink materialization must reach native START");
-	const result = (returned?.details as { result?: Record<string, unknown> } | undefined)?.result;
-	assert.equal(typeof result?.lineage_id, "string", "safe internal symlink materialization must return native review authority");
-	assert.equal(result?.state, "reviewing");
-	candidateViews.cleanup(candidateViews.resolveForLens(result!.lineage_id as string, "review-reliability").token);
+	const result = returned?.details as Record<string, unknown> | undefined;
+	assert.equal(result?.status, "blocked");
+	assert.equal(result?.outcome, "native-review-consent-required");
+	assert.equal(typeof result?.consent_binding, "string");
+	assert.equal(result?.lineage_created, false);
+	assert.ok(sessionShutdown, "extension must register session_shutdown cleanup");
+	const context = { cwd: repository, hasUI: false, ui: { notify: () => {} } } as unknown as ExtensionContext;
+	await sessionShutdown({}, context);
+	await assert.rejects(
+		controller.execute("answer-after-shutdown", { operation: "answer-consent", input: JSON.stringify({ consentBinding: result!.consent_binding, answer: "granted" }) }, undefined, undefined, context),
+		/unknown, expired, or already consumed/,
+	);
 });

package/tests/native-review-parity.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
@@ -9,14 +9,20 @@ import { __testing, createGentleAiExtension } from "../extensions/gentle-ai.ts";
 import {
 	NATIVE_REVIEW_ERROR_CODE,
 	NativeReviewCliError,
+	NativeReviewConsentBindingError,
+	NativeReviewConsentRequiredError,
 	NativeReviewCliV213 as NativeReviewCliV213Production,
+	normalizeNativeReviewCwd,
 	setNativeCliContractForTesting,
 	type ExecFileAdapter,
 	type NativeReviewCli,
+	type NativeReviewConsentAnswer,
+	type NativeReviewConsentAnswerRequest,
+	type NativeStartRequest,
 } from "../lib/native-review-cli.ts";
 import { CandidateViewRegistry } from "../lib/review-candidate-view.ts";
-import { readReviewConsentLatch, recordReviewConsentLatch } from "../lib/review-consent-latch.ts";
-import type { AuthorityRepairAssessmentV1, ReviewStatusV3 } from "../lib/review-integration-v2.ts";
+import { recordReviewConsentLatch } from "../lib/review-consent-latch.ts";
+import type { AuthorityRepairAssessmentV1, ReviewConsentV2, ReviewStatusV3 } from "../lib/review-integration-v2.ts";
 
 // Queued-adapter clients never execute a real process; default to a fixed
 // absolute package-local path so these tests do not depend on an installed
@@ -110,6 +116,26 @@ test("reviewMode status uses the exact fixed argv and decodes the effective mode
 	assert.equal(result.scope, "both");
 });
 
+test("reviewMode canonicalizes an existing repository cwd before the version probe and status argv", async (t) => {
+	if (process.platform === "win32") return t.skip("directory symlink creation requires elevated Windows privileges");
+	const repository = mkdtempSync(join(tmpdir(), "gentle-pi-review-mode-cwd-"));
+	const alias = `${repository}-alias`;
+	symlinkSync(repository, alias, "dir");
+	t.after(() => { rmSync(alias, { force: true }); rmSync(repository, { recursive: true, force: true }); });
+	const queue = queuedAdapter([CAPABLE_VERSION_LINE, { stdout: JSON.stringify(reviewModeStatusBody("off", { global: "off", source: "global" })) }]);
+	const result = await new NativeReviewCliV213(queue.adapter).reviewMode({ cwd: alias, operation: "status" });
+	assert.equal(result.status.effective, "off");
+	assert.equal(queue.calls.every((call) => call.cwd === repository), true);
+	assert.deepEqual(queue.calls[1]?.arguments, ["review", "mode", "status", "--cwd", repository, "--json"]);
+});
+
+test("native review cwd normalization unifies Git Bash and drive-form Windows paths", () => {
+	const expected = "C:\\Users\\Alan\\worktree B";
+	assert.equal(normalizeNativeReviewCwd("/c/Users/Alan/worktree B", "win32"), expected);
+	assert.equal(normalizeNativeReviewCwd("c:/Users/Alan/worktree B", "win32"), expected);
+	assert.equal(normalizeNativeReviewCwd("/c/Users/Alan/worktree B", "linux"), "/c/Users/Alan/worktree B");
+});
+
 test("reviewMode status decodes an off effective mode with its deciding source", async () => {
 	const queue = queuedAdapter([CAPABLE_VERSION_LINE, { stdout: JSON.stringify(reviewModeStatusBody("off", { clone_local: "off", source: "clone_local", revision: "sha256:deadbeef" })) }]);
 	const result = await new NativeReviewCliV213(queue.adapter).reviewMode({ cwd: "/repo", operation: "status" });
@@ -290,18 +316,22 @@ const UNSUPPORTED_REPAIR_ASSESSMENT: AuthorityRepairAssessmentV1 = {
 	authorizationSchema: "gentle-ai.review-repair-authorization/v1",
 };
 
-function unrelatedStartTargetStatus(): ReviewStatusV3 {
+function unrelatedStartTargetStatus(cwd: string): ReviewStatusV3 {
 	const sha = `sha256:${"a".repeat(64)}`;
-	const tree = "b".repeat(40);
+	const candidate = new CandidateViewRegistry().create({ contributorRoot: cwd });
+	const tree = candidate.candidateTree;
+	const baseTree = candidate.baseTree;
+	const paths = candidate.paths;
+	candidate.cleanup();
 	const projection = {
 		schema: "gentle-ai.review-integration.projection/v1" as const,
 		kind: "current-changes" as const,
 		projection: "workspace" as const,
-		baseTree: tree,
+		baseTree,
 		initialReviewTree: tree,
 		currentCandidateTree: tree,
 		pathsDigest: sha,
-		paths: ["app.ts"],
+		paths,
 		intendedUntracked: [],
 		intendedUntrackedProof: sha,
 		initialSnapshotIdentity: sha,
@@ -331,7 +361,7 @@ function unrelatedStartTargetStatus(): ReviewStatusV3 {
 			schema: "gentle-ai.review-integration.status/v3", contract: "gentle-ai.review-integration/v2", operation: "review.status",
 			applicability: "unrelated", receipt: { status: "not_applicable" }, action: "start", replayability: "not_replayable", target_identity: sha,
 			repair: rawRepair,
-			projection: { schema: projection.schema, kind: projection.kind, projection: projection.projection, base_tree: tree, initial_review_tree: tree, current_candidate_tree: tree, paths_digest: sha, paths: ["app.ts"], intended_untracked: [], intended_untracked_proof: sha, initial_snapshot_identity: sha, current_snapshot_identity: sha },
+			projection: { schema: projection.schema, kind: projection.kind, projection: projection.projection, base_tree: baseTree, initial_review_tree: tree, current_candidate_tree: tree, paths_digest: sha, paths, intended_untracked: [], intended_untracked_proof: sha, initial_snapshot_identity: sha, current_snapshot_identity: sha },
 			candidates: [],
 		},
 	};
@@ -367,8 +397,8 @@ function fakeOrganicNative(options: FakeOrganicNativeOptions = {}): { native: Na
 		async bindSdd(): Promise<never> { throw new Error("bindSdd not used in this test"); },
 		async sddStatus(): Promise<never> { throw new Error("sddStatus not used in this test"); },
 		async reviewStatus(): Promise<never> { throw new Error("reviewStatus not used in this test"); },
-		async targetStatus() {
-			return unrelatedStartTargetStatus();
+		async targetStatus(request: { cwd: string }) {
+			return unrelatedStartTargetStatus(request.cwd);
 		},
 		...(reviewModeCapable
 			? {
@@ -407,18 +437,23 @@ interface RegisteredCommandFixture {
 	handler: (args: string, ctx: ExtensionContext) => Promise<void>;
 }
 
-function runtime(nativeReviewCli: NativeReviewCli | null): { controller: RegisteredTool; commands: Map<string, RegisteredCommandFixture> } {
+interface RegisteredEventFixture {
+	(event: unknown, ctx: ExtensionContext): Promise<unknown> | unknown;
+}
+
+function runtime(nativeReviewCli: NativeReviewCli | null): { controller: RegisteredTool; commands: Map<string, RegisteredCommandFixture>; events: Map<string, RegisteredEventFixture> } {
 	const tools = new Map<string, RegisteredTool>();
 	const commands = new Map<string, RegisteredCommandFixture>();
+	const events = new Map<string, RegisteredEventFixture>();
 	const dependencies = { nativeReviewCli, candidateViews: new CandidateViewRegistry() } as unknown as Parameters<typeof createGentleAiExtension>[0];
 	createGentleAiExtension(dependencies)({
-		on() {},
+		on(name: string, handler: RegisteredEventFixture) { events.set(name, handler); },
 		registerTool(definition: RegisteredTool & { name: string }) { tools.set(definition.name, definition); },
 		registerCommand(name: string, definition: RegisteredCommandFixture) { commands.set(name, definition); },
 	} as unknown as ExtensionAPI);
 	const controller = tools.get("gentle_review");
 	assert.ok(controller);
-	return { controller: controller!, commands };
+	return { controller: controller!, commands, events };
 }
 
 function headlessContext(cwd: string, notices: Array<{ message: string; type?: string }> = []): ExtensionContext {
@@ -447,6 +482,7 @@ test("kill-switch: effective off returns a non-failure skipped envelope and neve
 	const result = await execStart(controller, "kill-switch-off", headlessContext(cwd));
 	assert.equal(result.status, "skipped");
 	assert.equal(result.outcome, "review-mode-disabled");
+	assert.equal(result.delivery, "disabled/unmanaged");
 	assert.equal(result.mutation_performed, false);
 	assert.equal(state.startCalls, 0, "native start must not be called once the kill switch reports off");
 });
@@ -516,67 +552,206 @@ test("kill-switch: an unexpected reviewMode failure maps to the existing native-
 	assert.equal(result.outcome, "native-operation-failed");
 });
 
-test("consent: an existing latch skips the prompt and proceeds with actor_binding", async (t) => {
+function candidateConsent(cwd: string): ReviewConsentV2 {
+	const targetIdentity = `sha256:${"a".repeat(64)}`;
+	const choices = [
+		{ answer: "granted" as const, label: "Run the review now", effect: "Review this exact candidate only.", invocation: `gentle-ai review start --contract gentle-ai.review-integration/v2 --cwd ${cwd} --target ${targetIdentity} --projection workspace --lineage native-lineage --consent granted` },
+		{ answer: "declined" as const, label: "Not now, just this once", effect: "Create no authority and ask again next candidate.", invocation: `gentle-ai review start --contract gentle-ai.review-integration/v2 --cwd ${cwd} --target ${targetIdentity} --projection workspace --lineage native-lineage --consent declined` },
+	] as const;
+	const raw = { schema: "gentle-ai.review-integration.consent/v2", contract: "gentle-ai.review-integration/v2", operation: "review.start", action: "consent_required", blocking: true, target_identity: targetIdentity, projection: "workspace", risk_level: "high", changed_files: 1, changed_lines: 1, headline: "Review this candidate", reason: "It changes a process boundary.", value: "Review catches regressions.", risk_evidence: ["shell process"], choices: choices.map((choice) => ({ ...choice })), off_path: { note: "Disable reviews separately.", command: "gentle-ai review mode disable" } };
+	return { schema: "gentle-ai.review-integration.consent/v2", contract: "gentle-ai.review-integration/v2", operation: "review.start", action: "consent_required", blocking: true, targetIdentity, projection: "workspace", riskLevel: "high", changedFiles: 1, changedLines: 1, headline: "Review this candidate", reason: "It changes a process boundary.", value: "Review catches regressions.", riskEvidence: ["shell process"], choices, offPath: { note: "Disable reviews separately.", command: "gentle-ai review mode disable" }, raw };
+}
+
+function relayedConsentNative(cwd: string): { native: NativeReviewCli; answers: NativeReviewConsentAnswer[]; startRequests: NativeStartRequest[]; answerRequests: NativeReviewConsentAnswerRequest[] } {
+	const { native } = fakeOrganicNative();
+	const consent = candidateConsent(cwd);
+	const answers: NativeReviewConsentAnswer[] = [];
+	const startRequests: NativeStartRequest[] = [];
+	const answerRequests: NativeReviewConsentAnswerRequest[] = [];
+	native.start = async (request) => {
+		startRequests.push(request);
+		throw new NativeReviewConsentRequiredError(consent);
+	};
+	native.answerConsent = async (request) => {
+		answers.push(request.answer);
+		answerRequests.push(request);
+		if (request.answer === "declined") return { kind: "declined", targetIdentity: consent.targetIdentity, projection: "workspace", riskLevel: "high", changedFiles: 1, changedLines: 1, consent: "declined_this_candidate", raw: { operation: "review/start", action: "declined", consent: "declined_this_candidate" } };
+		return { kind: "started", start: { lineageId: "native-lineage", state: "reviewing", riskLevel: "high", selectedLenses: ["review-risk", "review-resilience", "review-readability", "review-reliability"], changedFiles: 1, changedLines: 1, correctionBudget: 1, action: "created", lensesRequired: true } };
+	};
+	return { native, answers, startRequests, answerRequests };
+}
+
+async function answerConsent(controller: RegisteredTool, binding: unknown, answer: unknown, ctx: ExtensionContext): Promise<Record<string, unknown>> {
+	const { details } = await controller.execute("consent-answer", { operation: "answer-consent", input: JSON.stringify({ consentBinding: binding, answer }) }, undefined, undefined, ctx);
+	return details as Record<string, unknown>;
+}
+
+async function blockedConsent(controller: RegisteredTool, id: string, ctx: ExtensionContext): Promise<Record<string, unknown>> {
+	const result = await execStart(controller, id, ctx);
+	assert.equal(result.status, "blocked");
+	assert.equal(result.outcome, "native-review-consent-required");
+	assert.equal(typeof result.consent_binding, "string");
+	return result;
+}
+
+test("consent relay returns the identical complete parent-visible envelope with or without UI and never answers internally", async (t) => {
 	const cwd = repository(t);
 	recordReviewConsentLatch(cwd);
-	const { native } = fakeOrganicNative({ riskEvidence: ["shell scripting in deploy.sh"] });
-	const { controller } = runtime(native);
-	const result = await execStart(controller, "consent-latched", confirmContext(cwd, false));
-	assert.ok(result.actor_binding, "an existing latch must not block actor_binding even though confirm() would decline");
-	assert.equal(result.consent_notice, undefined);
+	for (const ctx of [
+		{ cwd, hasUI: true, ui: { select: async () => { throw new Error("internal consent UI must not run"); }, notify: () => {} } } as unknown as ExtensionContext,
+		headlessContext(cwd),
+	]) {
+		const { native, answers } = relayedConsentNative(cwd);
+		const result = await blockedConsent(runtime(native).controller, "consent-blocked", ctx);
+		assert.deepEqual(result.consent, candidateConsent(cwd).raw);
+		assert.deepEqual(answers, []);
+		assert.equal(result.lineage_created, false);
+	}
 });
 
-test("consent: headless never blocks, always surfaces a notice, and leaves the latch untouched", async (t) => {
+test("explicit consent follow-up grants or declines exactly once", async (t) => {
 	const cwd = repository(t);
-	const { native } = fakeOrganicNative({ riskEvidence: ["service credentials in .env.example"] });
-	const { controller } = runtime(native);
-	const notices: Array<{ message: string; type?: string }> = [];
-	const result = await execStart(controller, "consent-headless", headlessContext(cwd, notices));
-	assert.ok(result.actor_binding, "headless must still run the review");
-	assert.equal(typeof result.consent_notice, "string");
-	assert.ok(notices.some((notice) => notice.type === "info" && notice.message === result.consent_notice));
-	assert.equal(readReviewConsentLatch(cwd), false, "headless must never consume/persist the one-time question");
+	for (const answer of ["granted", "declined"] as const) {
+		const { native, answers, startRequests, answerRequests } = relayedConsentNative(cwd);
+		const { controller } = runtime(native);
+		const blocked = await blockedConsent(controller, `consent-${answer}`, headlessContext(cwd));
+		const result = await answerConsent(controller, blocked.consent_binding, answer, headlessContext(cwd));
+		assert.deepEqual(answers, [answer]);
+		assert.equal(startRequests.length, 1);
+		assert.equal(startRequests[0]?.cwd, cwd);
+		assert.equal(startRequests[0]?.targetIdentity, candidateConsent(cwd).targetIdentity);
+		assert.equal(startRequests[0]?.projection, "workspace");
+		assert.equal(answerRequests.length, 1);
+		assert.equal(answerRequests[0]?.cwd, cwd);
+		assert.equal(answerRequests[0]?.consent.targetIdentity, startRequests[0]?.targetIdentity);
+		if (answer === "granted") {
+			const actorBinding = result.actor_binding as { workspace_root: string; candidate_root: string };
+			assert.equal(actorBinding.workspace_root, cwd);
+			assert.notEqual(actorBinding.candidate_root, cwd);
+		} else {
+			assert.equal(result.outcome, "consent-declined-this-candidate");
+			assert.equal(result.lineage_created, false);
+			assert.equal(result.actor_binding, undefined);
+		}
+		await assert.rejects(() => answerConsent(controller, blocked.consent_binding, answer, headlessContext(cwd)), /unknown, expired, or already consumed/);
+	}
 });
 
-test("consent: accepting the prompt records the latch and proceeds with actor_binding", async (t) => {
+// Issue #247: a local binding mismatch was indistinguishable from a provider
+// outage, so the reporter diagnosed a missing --cwd that Pi does forward.
+test("a consent binding mismatch surfaces as an actionable local failure, not an opaque native operation failure", async (t) => {
 	const cwd = repository(t);
-	const { native } = fakeOrganicNative({ riskEvidence: ["payments in billing.ts"] });
+	const { native, answers } = relayedConsentNative(cwd);
+	native.answerConsent = async () => {
+		throw new NativeReviewConsentBindingError("consent-invocation-cwd-changed", "Native consent invocation repository binding changed");
+	};
 	const { controller } = runtime(native);
-	assert.equal(readReviewConsentLatch(cwd), false);
-	const result = await execStart(controller, "consent-accept", confirmContext(cwd, true));
-	assert.ok(result.actor_binding);
-	assert.equal(readReviewConsentLatch(cwd), true);
+	const blocked = await blockedConsent(controller, "consent-binding", headlessContext(cwd));
+	const result = await answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd));
+	assert.equal(result.status, "blocked");
+	assert.equal(result.outcome, "consent-binding-invalid");
+	assert.deepEqual(result.diagnostics, { code: "consent-invocation-cwd-changed", message: "Native consent invocation repository binding changed" });
+	assert.equal(result.native_invocation_attempted, false);
+	assert.equal(result.lineage_created, false);
+	assert.equal(result.mutation_performed, false);
+	assert.equal(result.mutation_outcome, "none");
+	assert.equal(result.next_action, "resolve-consent-binding");
+	assert.deepEqual(answers, []);
 });
 
-test("consent: declining persists nothing, applies only to this work unit, and withholds actor_binding", async (t) => {
+test("consent follow-up rejects invalid token, unknown id, changed cwd, and changed target binding", async (t) => {
 	const cwd = repository(t);
-	const { native } = fakeOrganicNative({ riskEvidence: ["authentication in auth.ts"] });
+	const consent = candidateConsent(cwd);
+	const { native, answers } = relayedConsentNative(cwd);
+	native.start = async () => { throw new NativeReviewConsentRequiredError(consent); };
 	const { controller } = runtime(native);
-	const result = await execStart(controller, "consent-decline", confirmContext(cwd, false));
-	assert.equal(result.actor_binding, undefined, "declining must withhold actor dispatch for this work unit");
-	assert.equal(readReviewConsentLatch(cwd), false, "declining must never persist anything");
-	assert.ok(result.result, "the native start result itself is still reported");
+	const blocked = await blockedConsent(controller, "consent-invalid", headlessContext(cwd));
+	await assert.rejects(() => controller.execute("malformed", { operation: "answer-consent", input: "not-json" }, undefined, undefined, headlessContext(cwd)), /input is not valid JSON/);
+	await assert.rejects(() => controller.execute("extra", { operation: "answer-consent", input: JSON.stringify({ consentBinding: blocked.consent_binding, answer: "granted", target: "substitute" }) }, undefined, undefined, headlessContext(cwd)), /exactly consentBinding and answer/);
+	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "yes", headlessContext(cwd)), /answer must be granted or declined/);
+	await assert.rejects(() => answerConsent(controller, "missing", "granted", headlessContext(cwd)), /unknown, expired, or already consumed/);
+	const other = repository(t);
+	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "granted", headlessContext(other)), /repository binding changed/);
+	const originalTarget = consent.targetIdentity;
+	(consent as { targetIdentity: string }).targetIdentity = `sha256:${"b".repeat(64)}`;
+	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd)), /consent envelope binding changed/);
+	(consent as { targetIdentity: string }).targetIdentity = originalTarget;
+	(consent as { projection: string }).projection = "staged";
+	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd)), /consent envelope binding changed/);
+	(consent as { projection: string }).projection = "workspace";
+	(consent.choices[0] as { invocation: string }).invocation = consent.choices[0].invocation.replace("native-lineage", "changed-lineage");
+	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd)), /consent envelope binding changed/);
+	assert.deepEqual(answers, []);
+});
+
+test("ambiguous consent mutation consumes the one-shot binding and requires status instead of blind replay", async (t) => {
+	const cwd = repository(t);
+	const { native } = relayedConsentNative(cwd);
+	let statusCalls = 0;
+	const targetStatus = native.targetStatus!;
+	native.targetStatus = async (request) => { statusCalls += 1; return await targetStatus(request); };
+	native.answerConsent = async () => { throw Object.assign(new Error("ambiguous"), { mutationOutcome: "unknown", nextAction: "review.status" }); };
+	const { controller } = runtime(native);
+	const blocked = await blockedConsent(controller, "consent-ambiguous", headlessContext(cwd));
+	await answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd));
+	assert.equal(statusCalls, 2, "ambiguous consent must reconcile through target status");
+	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd)), /unknown, expired, or already consumed/);
 });
 
-test("consent: an unreadable answer (confirm throws) still runs the review, leaves the latch untouched, and surfaces a notice", async (t) => {
+test("session shutdown clears pending candidate consent bindings and is idempotent", async (t) => {
+	const cwd = repository(t);
+	const { native, answers } = relayedConsentNative(cwd);
+	const { controller, events } = runtime(native);
+	const blocked = await blockedConsent(controller, "consent-before-shutdown", headlessContext(cwd));
+	const shutdown = events.get("session_shutdown");
+	assert.ok(shutdown);
+	await shutdown({}, headlessContext(cwd));
+	await shutdown({}, headlessContext(cwd));
+	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd)), /unknown, expired, or already consumed/);
+	assert.deepEqual(answers, []);
+});
+
+test("successful explicit disable clears pending candidate consent binding even after re-enable", async (t) => {
 	const cwd = repository(t);
-	const { native } = fakeOrganicNative({ riskEvidence: ["an executable permission change in run.sh"] });
+	const { native, answers } = relayedConsentNative(cwd);
+	let effective: "on" | "off" = "on";
+	native.reviewMode = async (request) => {
+		if (request.operation === "disable") effective = "off";
+		if (request.operation === "enable") effective = "on";
+		return { operation: request.operation, scope: "clone", status: { global: "", cloneLocal: effective === "off" ? "off" : "", effective, source: effective === "off" ? "clone_local" : "default" } };
+	};
+	const { controller, commands } = runtime(native);
+	const blocked = await blockedConsent(controller, "consent-before-disable", headlessContext(cwd));
+	const command = commands.get("gentle:review-mode")!;
+	await command.handler("disable", headlessContext(cwd));
+	await command.handler("enable", headlessContext(cwd));
+	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd)), /unknown, expired, or already consumed/);
+	assert.deepEqual(answers, []);
+});
+
+test("candidate-scoped decline creates no authority and the next candidate asks again", async (t) => {
+	const cwd = repository(t);
+	const { native, answers } = relayedConsentNative(cwd);
 	const { controller } = runtime(native);
-	const result = await execStart(controller, "consent-throw", throwingConfirmContext(cwd));
-	assert.ok(result.actor_binding, "an unreadable answer must still run the review");
-	assert.equal(typeof result.consent_notice, "string");
-	assert.equal(readReviewConsentLatch(cwd), false);
+	for (const id of ["decline-one", "decline-two"]) {
+		const blocked = await blockedConsent(controller, id, headlessContext(cwd));
+		const result = await answerConsent(controller, blocked.consent_binding, "declined", headlessContext(cwd));
+		assert.equal(result.outcome, "consent-declined-this-candidate");
+		assert.equal(result.lineage_created, false);
+		assert.equal(result.actor_binding, undefined);
+	}
+	assert.deepEqual(answers, ["declined", "declined"]);
 });
 
-test("consent stays dark (capability-gated) when the native start result carries no riskEvidence", async (t) => {
+test("low-risk zero-lens START remains silent", async (t) => {
 	const cwd = repository(t);
-	const { native } = fakeOrganicNative({ riskEvidence: undefined, lensesRequired: true });
+	const { native } = fakeOrganicNative({ riskEvidence: undefined, lensesRequired: false });
 	const { controller } = runtime(native);
-	let confirmed = false;
-	const ctx = { cwd, hasUI: true, ui: { confirm: async () => { confirmed = true; return true; }, notify: () => {} } } as unknown as ExtensionContext;
-	const result = await execStart(controller, "consent-dark", ctx);
-	assert.equal(confirmed, false, "no riskEvidence (dark riskEvidence capability) must never trigger the consent prompt");
-	assert.ok(result.actor_binding);
+	let selected = false;
+	const ctx = { cwd, hasUI: true, ui: { select: async () => { selected = true; return undefined; }, notify: () => {} } } as unknown as ExtensionContext;
+	const result = await execStart(controller, "consent-low-risk", ctx);
+	assert.equal(selected, false);
+	assert.ok(result.result);
 });
 
 // ---------------------------------------------------------------------------