gentle-pi 2.2.0 → 2.4.0

package/tests/review-controller-retired-ops.test.ts

@@ -13,7 +13,7 @@ function scratchDir(prefix: string): string {
 
 async function runRetiredOperation(parameters: Record<string, unknown>): Promise<Record<string, unknown>> {
 	const cwd = scratchDir("gentle-pi-retired-ops-");
-	return await __testing.executeReviewControllerOperation(parameters, cwd, new Map(), null);
+	return await __testing.executeReviewControllerOperation(parameters, cwd, null);
 }
 
 function assertRetiredEnvelope(details: Record<string, unknown>, operation: string): void {

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

@@ -5,7 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import { __testing, createGentleAiExtension } from "../extensions/gentle-ai.ts";
 import type { NativeReviewCli } from "../lib/native-review-cli.ts";
 import { CandidateViewRegistry } from "../lib/review-candidate-view.ts";
 import type { AuthorityRepairAssessmentV1, ReviewStatusV3 } from "../lib/review-integration-v2.ts";
@@ -55,8 +55,13 @@ function context(cwd: string): ExtensionContext {
 }
 
 function repository(t: test.TestContext, prefix = "gentle-pi-workspace-root-"): string {
-	const cwd = mkdtempSync(join(tmpdir(), prefix));
-	t.after(() => rmSync(cwd, { recursive: true, force: true }));
+	const cwd = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+	t.after(() => {
+		if (process.platform !== "win32") {
+			try { execFileSync("chmod", ["-R", "u+w", cwd], { stdio: "ignore" }); } catch { /* best effort */ }
+		}
+		rmSync(cwd, { recursive: true, force: true });
+	});
 	execFileSync("git", ["init", "-b", "main"], { cwd });
 	writeFileSync(join(cwd, "app.ts"), "export const value = 1;\n");
 	execFileSync("git", ["add", "."], { cwd });
@@ -65,7 +70,7 @@ function repository(t: test.TestContext, prefix = "gentle-pi-workspace-root-"):
 }
 
 function addWorktree(t: test.TestContext, cwd: string, branch: string): string {
-	const parent = mkdtempSync(join(tmpdir(), "gentle-pi-workspace-worktrees-"));
+	const parent = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-workspace-worktrees-")));
 	t.after(() => {
 		try { execFileSync("git", ["worktree", "remove", "--force", join(parent, branch)], { cwd }); } catch {}
 		rmSync(parent, { recursive: true, force: true });
@@ -78,14 +83,11 @@ function addWorktree(t: test.TestContext, cwd: string, branch: string): string {
 function fakeNative(overrides: Partial<NativeReviewCli> = {}): NativeReviewCli {
 	return {
 		start: async () => ({ lineageId: "native-lineage", state: "reviewing", riskLevel: "medium", selectedLenses: ["review-reliability"], changedFiles: 2, changedLines: 7, correctionBudget: 4, action: "created", lensesRequired: true }),
-		finalize: async () => ({ lineageId: "native-lineage", state: "approved", action: "approved", storeRevision: "r1", receiptPath: "/opaque/receipt" }),
-		validate: async () => { throw new Error("validate is not expected in workspace-root tests"); },
-		bindSdd: async () => { throw new Error("bind-sdd is not expected in workspace-root tests"); },
 		sddStatus: async () => ({ ready: false }),
 		reviewStatus: async () => ({ schema: "gentle-ai.review-authority-status/v1", repository: "/repo", complete: true, authoritative: true, status: "clean", entries: [], locks: [], diagnostics: [], raw: { schema: "gentle-ai.review-authority-status/v1", operation: "review/status", repository: "/repo", complete: true, authoritative: true, status: "clean", entries: [], locks: [], diagnostics: [] } }),
 		targetStatus: async (request) => request.lineageId === undefined
 			? candidateStartTargetStatus(request)
-			: candidateFinalizeTargetStatus(request, request.lineageId),
+			: candidateTargetStatus(request, request.lineageId),
 		...overrides,
 	};
 }
@@ -102,17 +104,20 @@ function targetStatusFixture(options: {
 	applicability?: "current_target" | "unrelated";
 	action?: ReviewStatusV3["action"];
 	lineageId?: string;
+	authorityState?: NonNullable<ReviewStatusV3["authority"]>["state"];
 	baseTree?: string;
 	currentCandidateTree?: string;
 	paths?: readonly string[];
+	intendedUntracked?: readonly string[];
 } = {}): ReviewStatusV3 {
 	const applicability = options.applicability ?? "current_target";
-	const action = options.action ?? (applicability === "current_target" ? "finalize" : "start");
-	const lineageId = options.lineageId ?? "native-lineage";
+	const action = options.action ?? (applicability === "current_target" ? "stop" : "start");	const lineageId = options.lineageId ?? "native-lineage";
+	const authorityState = options.authorityState ?? "reviewing";
 	const sha = `sha256:${"a".repeat(64)}`;
 	const tree = options.currentCandidateTree ?? "b".repeat(40);
 	const baseTree = options.baseTree ?? tree;
 	const paths = options.paths ?? ["app.ts"];
+	const intendedUntracked = options.intendedUntracked ?? [];
 	const projection = {
 		schema: "gentle-ai.review-integration.projection/v1" as const,
 		kind: "current-changes" as const,
@@ -122,7 +127,7 @@ function targetStatusFixture(options: {
 		currentCandidateTree: tree,
 		pathsDigest: sha,
 		paths,
-		intendedUntracked: [],
+		intendedUntracked,
 		intendedUntrackedProof: sha,
 		initialSnapshotIdentity: sha,
 		currentSnapshotIdentity: sha,
@@ -156,7 +161,7 @@ function targetStatusFixture(options: {
 			current_candidate_tree: tree,
 			paths_digest: sha,
 			paths,
-			intended_untracked: [],
+			intended_untracked: intendedUntracked,
 			intended_untracked_proof: sha,
 			initial_snapshot_identity: sha,
 			current_snapshot_identity: sha,
@@ -164,13 +169,13 @@ function targetStatusFixture(options: {
 		candidates: [],
 	};
 	if (applicability === "current_target") {
-		raw.authority = { version: "compact-v2", lineage_id: lineageId, state: "reviewing", generation: 1, revision: sha };
+		raw.authority = { version: "compact-v2", lineage_id: lineageId, state: authorityState, generation: 1, revision: sha };
 		raw.frozen = { tier: "medium", original_changed_lines: 2, correction_budget: 1 };
 	}
 	return {
 		contract: "gentle-ai.review-integration/v2",
 		applicability,
-		...(applicability === "current_target" ? { authority: { version: "compact-v2" as const, lineageId, state: "reviewing", generation: 1, revision: sha } } : {}),
+		...(applicability === "current_target" ? { authority: { version: "compact-v2" as const, lineageId, state: authorityState, generation: 1, revision: sha } } : {}),
 		receipt: { status: applicability === "current_target" ? "expected_missing" : "not_applicable" },
 		action,
 		replayability: "not_replayable",
@@ -189,6 +194,7 @@ function candidateStartTargetStatus(request: Parameters<NonNullable<NativeReview
 		candidate = new CandidateViewRegistry().create({
 			contributorRoot: request.cwd,
 			...(request.baseRef === undefined ? {} : { baseRef: request.baseRef, committedOnly: true }),
+			...(request.intendedUntracked === undefined ? {} : { intendedUntracked: request.intendedUntracked }),
 		});
 		return targetStatusFixture({
 			applicability: "unrelated",
@@ -196,13 +202,14 @@ function candidateStartTargetStatus(request: Parameters<NonNullable<NativeReview
 			baseTree: candidate.baseTree,
 			currentCandidateTree: candidate.candidateTree,
 			paths: candidate.paths,
+			intendedUntracked: request.intendedUntracked,
 		});
 	} finally {
 		candidate?.cleanup();
 	}
 }
 
-function candidateFinalizeTargetStatus(request: Parameters<NonNullable<NativeReviewCli["targetStatus"]>>[0], lineageId: string): ReviewStatusV3 {
+function candidateTargetStatus(request: Parameters<NonNullable<NativeReviewCli["targetStatus"]>>[0], lineageId: string): ReviewStatusV3 {
 	let candidate: ReturnType<CandidateViewRegistry["create"]> | undefined;
 	try {
 		candidate = new CandidateViewRegistry().create({ contributorRoot: request.cwd });
@@ -270,39 +277,164 @@ test("START freezes the candidate from the explicit workspace root and returns t
 	candidateViews.cleanup(view.token);
 });
 
-test("absent workspaceRoot keeps the session-cwd flow and still reports the actor binding envelope", async (t) => {
-	const sessionCwd = repository(t);
-	writeFileSync(join(sessionCwd, "app.ts"), "export const value = 3;\n");
+test("an omitted workspaceRoot canonicalizes a nested same-worktree session before supported operations", async (t) => {
+	const root = repository(t);
+	const sessionCwd = join(root, "nested");
+	mkdirSync(sessionCwd);
+	writeFileSync(join(root, "app.ts"), "export const value = 3;\n");
 	const candidateViews = new CandidateViewRegistry();
+	const targetStatusCwds: string[] = [];
 	const startRequests: Parameters<NativeReviewCli["start"]>[0][] = [];
 	const { controller } = runtime(fakeNative({
+		targetStatus: async (request) => { targetStatusCwds.push(request.cwd); return request.lineageId === undefined ? candidateStartTargetStatus(request) : candidateTargetStatus(request, request.lineageId); },
 		start: async (request) => {
 			startRequests.push(request);
 			return { lineageId: "session-lineage", state: "reviewing", riskLevel: "medium", selectedLenses: ["review-reliability"], changedFiles: 1, changedLines: 1, correctionBudget: 1, action: "created", lensesRequired: true };
 		},
 	}), candidateViews);
-	const started = await controller.execute("start-session", { operation: "start", input: JSON.stringify({ mode: "ordinary" }) }, undefined, undefined, context(sessionCwd));
-	const details = started.details as {
-		workspace_root: string;
-		actor_binding: { workspace_root: string; candidate_root: string; candidate_paths: readonly string[] };
-	};
-	assert.equal(details.workspace_root, sessionCwd);
-	assert.equal(details.actor_binding.workspace_root, sessionCwd);
+	const ctx = context(sessionCwd);
+	await controller.execute("inspect-session", { operation: "inspect" }, undefined, undefined, ctx);
+	const started = await controller.execute("start-session", { operation: "start", input: JSON.stringify({ mode: "ordinary" }) }, undefined, undefined, ctx);
+	const status = await controller.execute("status-session", { operation: "status", lineageId: "session-lineage" }, undefined, undefined, ctx);
+	const details = started.details as { workspace_root: string; actor_binding: { workspace_root: string; candidate_root: string; candidate_paths: readonly string[] } };
+	assert.equal(details.workspace_root, root);
+	assert.equal(details.actor_binding.workspace_root, root);
+	assert.equal((status.details as { workspace_root: string }).workspace_root, root);
 	assert.deepEqual(details.actor_binding.candidate_paths, ["app.ts"]);
-	assert.deepEqual(startRequests, [{ cwd: sessionCwd, targetIdentity: `sha256:${"a".repeat(64)}`, projection: "workspace" }]);
+	assert.deepEqual(startRequests, [{ cwd: root, targetIdentity: `sha256:${"a".repeat(64)}`, projection: "workspace" }]);
 	const view = candidateViews.resolveForLens("session-lineage", "review-reliability");
 	assert.equal(details.actor_binding.candidate_root, view.root);
+	assert.ok(targetStatusCwds.every((cwd) => cwd === root), JSON.stringify(targetStatusCwds));
 	candidateViews.cleanup(view.token);
 });
 
-test("workspaceRoot fails closed before any native call for non-worktree and foreign targets", async (t) => {
+test("an explicit nested foreign workspace root canonically owns inspect, status, and START", async (t) => {
+	const sessionCwd = repository(t, "gentle-pi-session-a-");
+	const target = repository(t, "gentle-pi-target-b-");
+	const nested = join(target, "nested");
+	mkdirSync(nested);
+	writeFileSync(join(target, "app.ts"), "export const value = 2; // target B\n");
+	const root = realpathSync(target);
+	const targetStatusCwds: string[] = [];
+	const targetStatusRequests: Parameters<NonNullable<NativeReviewCli["targetStatus"]>>[0][] = [];
+	const startCwds: string[] = [];
+	const candidateViews = new CandidateViewRegistry();
+	let initialCrossRootStatus = true;
+	const { controller } = runtime(fakeNative({
+		targetStatus: async (request) => {
+			targetStatusCwds.push(request.cwd);
+			targetStatusRequests.push(request);
+			if (request.lineageId === "cross-root-lineage" && initialCrossRootStatus) {
+				initialCrossRootStatus = false;
+				return request.untrackedScope === "select"
+					? targetStatusFixture({ lineageId: request.lineageId, authorityState: "correction_required" })
+					: targetStatusFixture({ applicability: "unrelated", action: "start" });
+			}
+			return request.lineageId === undefined
+				? candidateStartTargetStatus(request)
+				: candidateTargetStatus(request, request.lineageId);
+		},
+		start: async (request) => {
+			startCwds.push(request.cwd);
+			return { lineageId: "cross-root-lineage", state: "reviewing", riskLevel: "medium", selectedLenses: ["review-reliability"], changedFiles: 1, changedLines: 1, correctionBudget: 1, action: "created", lensesRequired: true };
+		},
+	}), candidateViews);
+
+	const digest = `sha256:${"b".repeat(64)}`;
+	const intendedUntracked = ["selected-b.ts", "selected-a.ts"];
+	const inspect = await controller.execute("inspect-target-b", { operation: "inspect", workspaceRoot: nested }, undefined, undefined, context(sessionCwd));
+	const status = await controller.execute("status-target-b", { operation: "status", lineageId: "cross-root-lineage", workspaceRoot: nested, input: JSON.stringify({ untrackedScope: "select", expectedUntrackedInventory: digest, intendedUntracked }) }, undefined, undefined, context(sessionCwd));
+	const started = await controller.execute("start-target-b", { operation: "start", workspaceRoot: nested, input: JSON.stringify({ mode: "ordinary" }) }, undefined, undefined, context(sessionCwd));
+
+	for (const result of [inspect, status, started]) {
+		assert.equal((result.details as { workspace_root?: string }).workspace_root, root);
+	}
+	const statusDetails = status.details as { status?: string; result?: { authority?: { state?: string } } };
+	assert.equal(statusDetails.status, "blocked");
+	assert.equal(statusDetails.result?.authority?.state, "correction_required");
+	assert.deepEqual(targetStatusRequests[1], { cwd: root, lineageId: "cross-root-lineage", untrackedScope: "select", expectedUntrackedInventory: digest, intendedUntracked, agent: "pi" });
+	assert.ok(targetStatusCwds.every((cwd) => cwd === root), JSON.stringify(targetStatusCwds));
+	assert.deepEqual(startCwds, [root]);
+	candidateViews.cleanup(candidateViews.resolveForLens("cross-root-lineage", "review-reliability").token);
+});
+
+
+test("STATUS relays exclude selection and rejects malformed input before native status", async (t) => {
+	const cwd = repository(t);
+	const requests: Parameters<NonNullable<NativeReviewCli["targetStatus"]>>[0][] = [];
+	const { controller } = runtime(fakeNative({
+		targetStatus: async (request) => {
+			requests.push(request);
+			return targetStatusFixture({ lineageId: request.lineageId });
+		},
+	}));
+	const digest = `sha256:${"c".repeat(64)}`;
+	const excluded = await controller.execute("status-exclude", { operation: "status", lineageId: "excluded-lineage", input: JSON.stringify({ untrackedScope: "exclude", expectedUntrackedInventory: digest, intendedUntracked: [] }) }, undefined, undefined, context(cwd));
+	assert.equal((excluded.details as { status?: string }).status, "blocked");
+	assert.deepEqual(requests, [{ cwd, lineageId: "excluded-lineage", untrackedScope: "exclude", expectedUntrackedInventory: digest, intendedUntracked: [], agent: "pi" }]);
+
+	for (const [input, reason] of [
+		[{}, "untracked-selection-invalid"],
+		[{ untrackedScope: "select", expectedUntrackedInventory: digest, intendedUntracked: [] }, "untracked-selection-invalid"],
+		[{ untrackedScope: "select" }, "untracked-selection-invalid"],
+		[{ untrackedScope: "exclude", expectedUntrackedInventory: digest, intendedUntracked: [], unexpected: true }, "unknown-field"],
+	] as const) {
+		const rejected = await controller.execute("status-invalid", { operation: "status", input: JSON.stringify(input) }, undefined, undefined, context(cwd));
+		assert.equal((rejected.details as { reason?: string }).reason, reason);
+	}
+	assert.equal(requests.length, 1);
+});
+
+test("an explicit foreign workspace root works when the Pi session cwd is not a Git repository", async (t) => {
+	const target = repository(t, "gentle-pi-target-b-non-git-session-");
+	const nested = join(target, "nested");
+	mkdirSync(nested);
+	const nonGit = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-non-git-session-")));
+	t.after(() => rmSync(nonGit, { recursive: true, force: true }));
+	const observed: string[] = [];
+	const { controller } = runtime(fakeNative({
+		targetStatus: async (request) => {
+			observed.push(request.cwd);
+			return targetStatusFixture();
+		},
+	}));
+	const result = await controller.execute("inspect-target-from-non-git", { operation: "inspect", workspaceRoot: nested }, undefined, undefined, context(nonGit));
+	assert.equal((result.details as { workspace_root?: string }).workspace_root, realpathSync(target));
+	assert.deepEqual(observed, [realpathSync(target)]);
+});
+
+test("omitted workspaceRoot fails closed for the same lineage bound to two target repositories", async (t) => {
+	const rootA = repository(t, "gentle-pi-ambiguous-a-");
+	const rootB = repository(t, "gentle-pi-ambiguous-b-");
+	const candidateViews = new CandidateViewRegistry();
+	const viewA = candidateViews.create({ contributorRoot: rootA });
+	const viewB = candidateViews.create({ contributorRoot: rootB });
+	candidateViews.bindCurrent({ token: viewA.token, lineageId: "shared-lineage", selectedLenses: ["review-reliability"] });
+	candidateViews.bindCurrent({ token: viewB.token, lineageId: "shared-lineage", selectedLenses: ["review-reliability"] });
+	let nativeCalls = 0;
+	const { controller } = runtime(fakeNative({
+		targetStatus: async (request) => {
+			nativeCalls += 1;
+			return targetStatusFixture({ lineageId: request.lineageId });
+		},
+	}), candidateViews);
+	await assert.rejects(
+		controller.execute("ambiguous-omission", { operation: "status", lineageId: "shared-lineage" }, undefined, undefined, context(rootA)),
+		/workspaceRoot/,
+	);
+	assert.equal(nativeCalls, 0);
+	const explicit = await controller.execute("explicit-b", { operation: "status", lineageId: "shared-lineage", workspaceRoot: rootB }, undefined, undefined, context(rootA));
+	assert.equal((explicit.details as { workspace_root?: string }).workspace_root, realpathSync(rootB));
+	assert.equal(nativeCalls, 1);
+	candidateViews.cleanupTerminal("shared-lineage", "approved", rootA);
+	candidateViews.cleanupTerminal("shared-lineage", "approved", rootB);
+});
+
+test("workspaceRoot fails closed before any native call for invalid target paths", async (t) => {
 	const sessionCwd = repository(t);
 	const worktree = addWorktree(t, sessionCwd, "feat-guard");
-	const foreign = repository(t, "gentle-pi-foreign-root-");
-	const nonGit = mkdtempSync(join(tmpdir(), "gentle-pi-non-git-"));
+	const nonGit = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-non-git-")));
 	t.after(() => rmSync(nonGit, { recursive: true, force: true }));
-	const nested = join(worktree, "nested");
-	mkdirSync(nested);
 	const filePath = join(worktree, "app.ts");
 	let nativeCalls = 0;
 	const counting = fakeNative({
@@ -311,16 +443,13 @@ test("workspaceRoot fails closed before any native call for non-worktree and for
 		reviewStatus: async () => { nativeCalls += 1; throw new Error("native review status must not run"); },
 	});
 	const { controller } = runtime(counting);
-	const rejected: Array<{ label: string; workspaceRoot: string; ctx: string }> = [
-		{ label: "non-git directory", workspaceRoot: nonGit, ctx: sessionCwd },
-		{ label: "missing directory", workspaceRoot: join(nonGit, "missing"), ctx: sessionCwd },
-		{ label: "file path", workspaceRoot: filePath, ctx: sessionCwd },
-		{ label: "relative path", workspaceRoot: "relative/worktree", ctx: sessionCwd },
-		{ label: "worktree subdirectory", workspaceRoot: nested, ctx: sessionCwd },
-		{ label: "foreign repository", workspaceRoot: foreign, ctx: sessionCwd },
-		{ label: "session outside a repository", workspaceRoot: worktree, ctx: nonGit },
+	const rejected: Array<{ label: string; workspaceRoot: string }> = [
+		{ label: "non-git directory", workspaceRoot: nonGit },
+		{ label: "missing directory", workspaceRoot: join(nonGit, "missing") },
+		{ label: "file path", workspaceRoot: filePath },
+		{ label: "relative path", workspaceRoot: "relative/worktree" },
 	];
-	for (const { label, workspaceRoot, ctx } of rejected) {
+	for (const { label, workspaceRoot } of rejected) {
 		for (const operation of ["inspect", "start", "status"] as const) {
 			await assert.rejects(
 				controller.execute(`${operation}-${label}`, {
@@ -328,7 +457,7 @@ test("workspaceRoot fails closed before any native call for non-worktree and for
 					...(operation === "start" ? { input: JSON.stringify({ mode: "ordinary" }) } : {}),
 					...(operation === "status" ? { lineageId: "native-lineage" } : {}),
 					workspaceRoot,
-				}, undefined, undefined, context(ctx)),
+				}, undefined, undefined, context(sessionCwd)),
 				/workspaceRoot/,
 				`${operation} must fail closed for ${label}`,
 			);
@@ -337,40 +466,62 @@ test("workspaceRoot fails closed before any native call for non-worktree and for
 	assert.equal(nativeCalls, 0);
 });
 
-test("workspaceRoot rejection reports both roots for a shared-common-dir mismatch", async (t) => {
+function providerRoleBinding(lineageId: string) {
+	return {
+		name: "provider_targeted_validator",
+		schema: "https://gentle-ai.dev/schema/review/targeted-validator/v1",
+		captureOperation: "review.capture-validation",
+		arguments: [
+			{ name: "lineage", value: lineageId, token: `--lineage=${lineageId}` },
+			{ name: "target", value: `sha256:${"a".repeat(64)}`, token: `--target=sha256:${"a".repeat(64)}` },
+			{ name: "agent", value: "pi", token: "--agent=pi" },
+			{ name: "execute", value: "true", token: "--execute=true" },
+		],
+	};
+}
+
+test("same-session START binding migrates to one validation capture without a FINALIZE operation", async (t) => {
 	const sessionCwd = repository(t);
-	const foreign = repository(t, "gentle-pi-foreign-report-");
-	const { controller } = runtime(fakeNative());
-	await assert.rejects(
-		controller.execute("inspect-foreign", { operation: "inspect", workspaceRoot: foreign }, undefined, undefined, context(sessionCwd)),
-		(error: Error) => {
-			assert.match(error.message, /workspaceRoot/);
-			assert.ok(error.message.includes(realpathSync(foreign)));
-			assert.ok(error.message.includes(sessionCwd));
-			return true;
+	const worktree = addWorktree(t, sessionCwd, "feat-last-event");
+	writeFileSync(join(worktree, "app.ts"), "export const value = 2;\n");
+	const candidateViews = new CandidateViewRegistry();
+	const lineageId = "workspace-last-event";
+	const binding = providerRoleBinding(lineageId);
+	let captureCalls = 0;
+	const native = fakeNative({
+		targetStatus: async (request) => request.lineageId === undefined
+			? candidateStartTargetStatus(request)
+			: ({ ...candidateTargetStatus(request, lineageId), nextTransition: { kind: "collect", reasonCode: "provider_role_required", collect: { inputs: [binding] } } } as unknown as ReviewStatusV3),
+		start: async () => ({ lineageId, state: "reviewing", riskLevel: "medium", selectedLenses: ["review-reliability"], changedFiles: 1, changedLines: 1, correctionBudget: 1, action: "created", lensesRequired: true }),
+		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)}` };
 		},
-	);
+	});
+	const { controller } = runtime(native, candidateViews);
+	await controller.execute("start", { operation: "start", workspaceRoot: worktree, input: JSON.stringify({ mode: "ordinary" }) }, undefined, undefined, context(sessionCwd));
+	const captured = await __testing.executeReviewCaptureOperation({ lineageId, workspaceRoot: worktree, collectBinding: JSON.stringify(binding) }, sessionCwd, native, undefined, candidateViews);
+	assert.equal(captured.outcome, "native-last-event-closure");
+	assert.equal(captured.status, "closed");
+	assert.equal(captureCalls, 1);
+	candidateViews.cleanupTerminal(lineageId, "approved", realpathSync(worktree));
 });
 
-test("FINALIZE fails closed when the frozen projection belongs to a different workspace than requested", async (t) => {
+test("an explicit linked-worktree root owns STATUS collect capture over the session candidate root", async (t) => {
 	const sessionCwd = repository(t);
-	const worktree = addWorktree(t, sessionCwd, "feat-finalize");
-	writeFileSync(join(worktree, "app.ts"), "export const value = 4;\n");
-	const candidateViews = new CandidateViewRegistry();
-	let finalizes = 0;
-	const { controller } = runtime(fakeNative({
-		start: async () => ({ lineageId: "finalize-lineage", state: "reviewing", riskLevel: "medium", selectedLenses: ["review-reliability"], changedFiles: 1, changedLines: 1, correctionBudget: 1, action: "created", lensesRequired: true }),
-		finalize: async () => {
-			finalizes += 1;
-			return { lineageId: "finalize-lineage", state: "approved", action: "approved", storeRevision: "r1" };
+	const worktree = addWorktree(t, sessionCwd, "feat-explicit-capture");
+	const lineageId = "explicit-worktree-capture";
+	const binding = providerRoleBinding(lineageId);
+	const observedRoots: string[] = [];
+	const native = {
+		targetStatus: async (request: { cwd: string }) => {
+			observedRoots.push(request.cwd);
+			return { ...targetStatusFixture({ lineageId }), nextTransition: { kind: "collect", reasonCode: "provider_role_required", collect: { inputs: [binding] } } } as unknown as ReviewStatusV3;
 		},
-	}), candidateViews);
-	await controller.execute("start-finalize-b", { operation: "start", workspaceRoot: worktree, input: JSON.stringify({ mode: "ordinary" }) }, undefined, undefined, context(sessionCwd));
-	const input = JSON.stringify({});
-	const mismatch = await controller.execute("finalize-wrong-root", { operation: "finalize", lineageId: "finalize-lineage", input }, undefined, undefined, context(sessionCwd));
-	assert.equal((mismatch.details as { outcome?: string }).outcome, "native-operation-failed");
-	assert.equal(finalizes, 0);
-	const matched = await controller.execute("finalize-right-root", { operation: "finalize", lineageId: "finalize-lineage", workspaceRoot: worktree, input }, undefined, undefined, context(sessionCwd));
-	assert.equal((matched.details as { result?: { state?: string } }).result?.state, "approved");
-	assert.equal(finalizes, 1);
+		captureProviderRole: async () => ({ schema: "gentle-ai.review-last-event-closure/v1", operation: "review.capture-validation", lineageId, state: "approved", storeRevision: `sha256:${"a".repeat(64)}` }),
+	} as unknown as NativeReviewCli;
+	const result = await __testing.executeReviewCaptureOperation({ lineageId, workspaceRoot: worktree, collectBinding: JSON.stringify(binding) }, sessionCwd, native);
+	assert.equal(result.outcome, "native-last-event-closure");
+	assert.deepEqual(observedRoots, [realpathSync(worktree)]);
 });