gentle-pi 2.1.2 → 2.2.0

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

@@ -85,7 +85,7 @@ function fakeNative(overrides: Partial<NativeReviewCli> = {}): NativeReviewCli {
 		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)
-			: targetStatusFixture({ lineageId: request.lineageId }),
+			: candidateFinalizeTargetStatus(request, request.lineageId),
 		...overrides,
 	};
 }
@@ -202,6 +202,21 @@ function candidateStartTargetStatus(request: Parameters<NonNullable<NativeReview
 	}
 }
 
+function candidateFinalizeTargetStatus(request: Parameters<NonNullable<NativeReviewCli["targetStatus"]>>[0], lineageId: string): ReviewStatusV3 {
+	let candidate: ReturnType<CandidateViewRegistry["create"]> | undefined;
+	try {
+		candidate = new CandidateViewRegistry().create({ contributorRoot: request.cwd });
+		return targetStatusFixture({
+			lineageId,
+			baseTree: candidate.baseTree,
+			currentCandidateTree: candidate.candidateTree,
+			paths: candidate.paths,
+		});
+	} finally {
+		candidate?.cleanup();
+	}
+}
+
 test("INSPECT and STATUS operate on the explicit workspace root while the session cwd stays elsewhere", async (t) => {
 	const sessionCwd = repository(t);
 	const worktree = addWorktree(t, sessionCwd, "feat-binding");
@@ -351,7 +366,7 @@ test("FINALIZE fails closed when the frozen projection belongs to a different wo
 		},
 	}), candidateViews);
 	await controller.execute("start-finalize-b", { operation: "start", workspaceRoot: worktree, input: JSON.stringify({ mode: "ordinary" }) }, undefined, undefined, context(sessionCwd));
-	const input = JSON.stringify({ review_result: { lens_results: [{ lens: "review-reliability", findings: [], evidence: ["reviewed frozen candidate"] }] } });
+	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);

package/tests/review-corrected-finalize-binding.test.ts

@@ -0,0 +1,175 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+import type { NativeReviewCli } from "../lib/native-review-cli.ts";
+import { CandidateViewRegistry } from "../lib/review-candidate-view.ts";
+import type { ReviewStatusV3 } from "../lib/review-integration-v2.ts";
+
+// Field defect (Engram #12547, lineage review-43762fca1bba0bf3): a MEDIUM
+// lineage detected a reliability defect, corrected it inside budget, captured
+// evidence and the native targeted validator. Negotiated STATUS then returned
+// `captured_provider_targeted_validation_ready` with an execute
+// `review.finalize` transition, and running that exact transition failed twice
+// with `candidate-target-projection-drift`, mutation none, so no receipt was
+// ever minted.
+//
+// Measured on a faithful live reproduction (medium candidate, real binary,
+// START through the controller so the registry holds the START-time view):
+//
+//   START candidate tree:     4c24487f850050af0a0944d37d4dbb15287ab3da
+//   corrected candidate tree: 777f48fdc4e6ed9abd325d6b4c49e6d06036c906
+//   FINALIZE (no documents) -> candidate-target-projection-drift, mutation none
+//   registry branch taken:    ["resolveForFinalize"]
+//
+// Root cause: the corrected tree is tolerated only while
+// `correctionCompletion` (validation AND final_evidence) or `validationAttempt`
+// (final_evidence without a forecast) hold. A FINALIZE that merely follows the
+// provider's own execute transition carries no documents, so both are false,
+// the START-time view is resolved, and it is compared against the corrected
+// candidate the provider itself authorized.
+
+const SHA = `sha256:${"1".repeat(64)}`;
+const DEFECT = "export function lastComponent(input) {\n  const parts = input.split(\"/\");\n  return parts[parts.length - 2];\n}\n";
+const CORRECTED = "export function lastComponent(input) {\n  const parts = input.split(\"/\");\n  return parts[parts.length - 1];\n}\n";
+
+function git(cwd: string, ...arguments_: string[]): string {
+	return execFileSync("git", arguments_, { cwd, encoding: "utf8" }).trim();
+}
+
+function repository(t: test.TestContext): string {
+	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-corrected-finalize-"));
+	t.after(() => rmSync(cwd, { recursive: true, force: true }));
+	git(cwd, "init", "-b", "main");
+	git(cwd, "config", "user.name", "Corrected Test");
+	git(cwd, "config", "user.email", "corrected@example.invalid");
+	mkdirSync(join(cwd, "src"), { recursive: true });
+	writeFileSync(join(cwd, "src", "parse.js"), "export function parsePath(input) {\n  return input.split(\"/\");\n}\n");
+	git(cwd, "add", "-A");
+	git(cwd, "commit", "-m", "base");
+	writeFileSync(join(cwd, "src", "parse.js"), DEFECT);
+	return cwd;
+}
+
+/** The live frozen identity of the current workspace candidate. */
+function liveIdentity(cwd: string): { baseTree: string; candidateTree: string; paths: readonly string[] } {
+	const probe = new CandidateViewRegistry();
+	const view = probe.create({ contributorRoot: cwd });
+	try {
+		return { baseTree: view.baseTree, candidateTree: view.candidateTree, paths: view.paths };
+	} finally {
+		probe.cleanup(view.token);
+	}
+}
+
+function correctedStatus(lineageId: string, identity: { baseTree: string; candidateTree: string; paths: readonly string[] }): ReviewStatusV3 {
+	return {
+		contract: "gentle-ai.review-integration/v2",
+		applicability: "current_target",
+		authority: { version: "compact-v2", lineageId, state: "correction_required", generation: 1, revision: SHA },
+		receipt: { status: "expected_missing" },
+		action: "finalize",
+		replayability: "not_replayable",
+		frozen: { tier: "medium", originalChangedLines: 4, correctionBudget: 2 },
+		targetIdentity: SHA,
+		projection: {
+			schema: "gentle-ai.review-integration.projection/v1",
+			kind: "current-changes",
+			projection: "workspace",
+			baseTree: identity.baseTree,
+			initialReviewTree: identity.candidateTree,
+			currentCandidateTree: identity.candidateTree,
+			pathsDigest: SHA,
+			paths: [...identity.paths],
+			intendedUntracked: [],
+			intendedUntrackedProof: SHA,
+			initialSnapshotIdentity: SHA,
+			currentSnapshotIdentity: SHA,
+		},
+		candidates: [],
+		// The provider's own answer after it admitted the captured validator.
+		nextTransition: {
+			kind: "execute",
+			reasonCode: "captured_provider_targeted_validation_ready",
+			execute: {
+				operation: "review.finalize",
+				arguments: [
+					{ name: "lineage", value: lineageId, token: `--lineage=${lineageId}` },
+					{ name: "captured-evidence", value: "true", token: "--captured-evidence=true" },
+				],
+				binding: { lineageId },
+			},
+		},
+		raw: { schema: "gentle-ai.review-integration.status/v5", action: "finalize", lineage_id: lineageId },
+	} as unknown as ReviewStatusV3;
+}
+
+function approvingNative(status: ReviewStatusV3): { native: NativeReviewCli; transitions: number } {
+	const state = { transitions: 0 };
+	const native = {
+		targetStatus: async () => status,
+		finalizeTransition: async () => {
+			state.transitions += 1;
+			return { lineageId: status.authority!.lineageId, state: "approved", action: "approved", storeRevision: "r2" };
+		},
+		finalize: async () => { throw new Error("the provider transition must be executed, not raw finalize"); },
+	} as unknown as NativeReviewCli;
+	return { native, get transitions() { return state.transitions; } } as never;
+}
+
+/** Binds the START-time immutable reviewer view, as a live session does. */
+function sessionWithStartBinding(cwd: string, lineageId: string): { registry: CandidateViewRegistry; startTree: string } {
+	const registry = new CandidateViewRegistry();
+	const view = registry.createOrReuse({ contributorRoot: cwd });
+	registry.bindCurrent({ token: view.token, lineageId, selectedLenses: ["review-reliability"] });
+	return { registry, startTree: view.candidateTree };
+}
+
+test("FINALIZE follows the provider transition after a correction instead of drifting on the START view", async (t) => {
+	const cwd = repository(t);
+	const lineageId = "review-corrected-lineage";
+	const { registry, startTree } = sessionWithStartBinding(cwd, lineageId);
+	t.after(() => { try { registry.cleanup(registry.resolveForFinalize(lineageId).token); } catch { /* already cleaned */ } });
+
+	// The bounded correction lands: the candidate identity legitimately moves.
+	writeFileSync(join(cwd, "src", "parse.js"), CORRECTED);
+	const corrected = liveIdentity(cwd);
+	assert.notEqual(corrected.candidateTree, startTree, "the correction must move the candidate tree");
+
+	const harness = approvingNative(correctedStatus(lineageId, corrected));
+	const result = await __testing.executeReviewControllerOperation(
+		// Exactly the reporter's call: follow the provider transition, no documents.
+		{ operation: "finalize", lineageId, input: JSON.stringify({}) },
+		cwd, new Map(), harness.native, undefined, undefined, undefined, registry,
+	) as Record<string, unknown>;
+
+	assert.notEqual(
+		(result.diagnostics as { code?: string } | undefined)?.code,
+		"candidate-target-projection-drift",
+		"a corrected candidate the provider authorized must not read as reviewer-view drift",
+	);
+	assert.equal(harness.transitions, 1, "the provider's own finalize transition must run");
+	assert.equal((result.result as { state?: string } | undefined)?.state, "approved");
+});
+
+test("FINALIZE still fails closed when the live candidate does not match the provider projection", async (t) => {
+	const cwd = repository(t);
+	const lineageId = "review-drifted-lineage";
+	const { registry } = sessionWithStartBinding(cwd, lineageId);
+	t.after(() => { try { registry.cleanup(registry.resolveForFinalize(lineageId).token); } catch { /* already cleaned */ } });
+
+	// The provider describes a candidate this workspace cannot reproduce.
+	const identity = liveIdentity(cwd);
+	const harness = approvingNative(correctedStatus(lineageId, { ...identity, candidateTree: identity.baseTree }));
+	const result = await __testing.executeReviewControllerOperation(
+		{ operation: "finalize", lineageId, input: JSON.stringify({}) },
+		cwd, new Map(), harness.native, undefined, undefined, undefined, registry,
+	) as Record<string, unknown>;
+
+	assert.equal(result.status, "blocked", "an unverifiable candidate must never mint a receipt");
+	assert.equal(result.mutation_outcome, "none");
+	assert.equal(harness.transitions, 0, "no provider transition may run for an unverifiable candidate");
+});

package/tests/review-dispatch-hydration-gap.test.ts

@@ -0,0 +1,197 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+import type { NativeReviewCli } from "../lib/native-review-cli.ts";
+import { CandidateViewError, CandidateViewRegistry, injectReviewCandidateView } from "../lib/review-candidate-view.ts";
+import type { ReviewCollectInputV3, ReviewStatusV3 } from "../lib/review-integration-v2.ts";
+
+// Field report (2026-08-16, gentle-pi main 402f9f77 + gentle-ai
+// 2.4.0-main.20278905): after #340 the FINALIZE routing defect was fixed but
+// the Pi relay's candidate-view registration still refused for an externally
+// recovered successor. Reproduced against the live binary: hydration itself
+// works for that shape (a dirty LINKED worktree hydrates fine) — the gap is
+// that hydration was wired into the STATUS controller operation ONLY, while
+// the maintainer's flow is `finalize` (now correctly blocked with
+// review.capture-result) followed by a reviewer dispatch. The FINALIZE lane
+// decodes the same authoritative status and never hydrated from it.
+//
+// Second defect in the same area: every hydration failure was swallowed by a
+// bare catch, so the later dispatch refusal claimed no binding existed
+// without ever admitting hydration had been attempted and why it failed.
+
+const SHA = `sha256:${"1".repeat(64)}`;
+
+function git(cwd: string, ...arguments_: string[]): string {
+	return execFileSync("git", arguments_, { cwd, encoding: "utf8" }).trim();
+}
+
+/** A LINKED worktree (not the primary checkout) with dirty tracked files. */
+function linkedDirtyWorktree(t: test.TestContext): string {
+	const root = mkdtempSync(join(tmpdir(), "gentle-pi-hydration-gap-"));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const primary = join(root, "primary");
+	const linked = join(root, "linked");
+	mkdirSync(primary, { recursive: true });
+	git(primary, "init", "-b", "main");
+	git(primary, "config", "user.name", "Hydration Test");
+	git(primary, "config", "user.email", "hydration@example.invalid");
+	mkdirSync(join(primary, "internal"), { recursive: true });
+	writeFileSync(join(primary, "internal", "parser.go"), "package internal\n\nfunc Parse(s string) string {\n\treturn s\n}\n");
+	git(primary, "add", "-A");
+	git(primary, "commit", "-m", "base");
+	git(primary, "worktree", "add", linked, "-b", "feature/fence-info");
+	// Uncommitted tracked modification, exactly the field shape.
+	writeFileSync(join(linked, "internal", "parser.go"), "package internal\n\nimport \"strings\"\n\nfunc Parse(s string) string {\n\treturn strings.TrimSpace(s)\n}\n");
+	return linked;
+}
+
+function reviewerResultCollectInput(lineageId: string, lens: string): ReviewCollectInputV3 {
+	return {
+		name: "reviewer_result",
+		schema: "https://gentle-ai.dev/schema/review/reviewer/v1",
+		captureOperation: "review.capture-result",
+		arguments: [
+			{ name: "lineage", value: lineageId, token: `--lineage=${lineageId}` },
+			{ name: "expected-revision", value: SHA, token: `--expected-revision=${SHA}` },
+			{ name: "lens", value: lens, token: `--lens=${lens}` },
+			{ name: "order", value: "0", token: "--order=0" },
+		],
+		artifactSubject: {
+			schema: "gentle-ai.review-artifact-subject/v2",
+			subjectHash: SHA,
+			lineageId,
+			authorityRevision: SHA,
+			targetIdentity: SHA,
+			baseTree: "3".repeat(40),
+			candidateTree: "4".repeat(40),
+			changedPathManifestSha256: SHA,
+			lens,
+			selectedOrder: 0,
+		},
+	} as unknown as ReviewCollectInputV3;
+}
+
+function successorStatus(lineageId: string, projection: { baseTree: string; currentCandidateTree: string; paths: readonly string[] }): ReviewStatusV3 {
+	return {
+		contract: "gentle-ai.review-integration/v2",
+		applicability: "current_target",
+		authority: { version: "compact-v2", lineageId, state: "reviewer_results_required", generation: 2, revision: SHA },
+		receipt: { status: "expected_missing" },
+		action: "finalize",
+		replayability: "not_replayable",
+		targetIdentity: SHA,
+		projection: {
+			schema: "gentle-ai.review-integration.projection/v1",
+			kind: "current-changes",
+			projection: "workspace",
+			baseTree: projection.baseTree,
+			initialReviewTree: projection.currentCandidateTree,
+			currentCandidateTree: projection.currentCandidateTree,
+			pathsDigest: SHA,
+			paths: [...projection.paths],
+			intendedUntracked: [],
+			intendedUntrackedProof: SHA,
+			initialSnapshotIdentity: SHA,
+			currentSnapshotIdentity: SHA,
+		},
+		candidates: [],
+		nextTransition: { kind: "collect", reasonCode: "reviewer_results_required", collect: { inputs: [reviewerResultCollectInput(lineageId, "review-reliability")] } },
+		raw: { schema: "gentle-ai.review-integration.status/v5", action: "finalize", lineage_id: lineageId },
+	} as unknown as ReviewStatusV3;
+}
+
+/** The live frozen identity of the dirty linked worktree candidate. */
+function liveProjection(cwd: string): { baseTree: string; currentCandidateTree: string; paths: readonly string[] } {
+	const probe = new CandidateViewRegistry();
+	const view = probe.create({ contributorRoot: cwd });
+	try {
+		return { baseTree: view.baseTree, currentCandidateTree: view.candidateTree, paths: view.paths };
+	} finally {
+		probe.cleanup(view.token);
+	}
+}
+
+function statusNative(status: ReviewStatusV3): NativeReviewCli {
+	return {
+		targetStatus: async () => status,
+		finalize: async () => { throw new Error("native finalize must not run while reviewer results are outstanding"); },
+	} as unknown as NativeReviewCli;
+}
+
+async function runController(parameters: Record<string, unknown>, cwd: string, native: NativeReviewCli, candidateViews: CandidateViewRegistry): Promise<Record<string, unknown>> {
+	return await __testing.executeReviewControllerOperation(
+		parameters, cwd, new Map(), native, undefined, undefined, undefined, candidateViews,
+	) as Record<string, unknown>;
+}
+
+test("FINALIZE hydrates the dispatch binding for an externally recovered successor in a dirty linked worktree", async (t) => {
+	const cwd = linkedDirtyWorktree(t);
+	const lineageId = "recovered-dirty-successor";
+	const registry = new CandidateViewRegistry();
+	const native = statusNative(successorStatus(lineageId, liveProjection(cwd)));
+
+	// The maintainer's flow: FINALIZE first (correctly blocked since #340),
+	// then a reviewer dispatch. FINALIZE never went through the STATUS
+	// controller operation, so nothing had hydrated the registry.
+	const finalize = await runController({ operation: "finalize", lineageId, input: JSON.stringify({}) }, cwd, native, registry);
+	assert.equal(finalize.outcome, "reviewer-results-required");
+	assert.equal(registry.hasCurrentBinding(), true, "FINALIZE must hydrate the dispatch binding from the status it decoded");
+	assert.deepEqual(finalize.dispatch_binding, { hydrated: true, lineage_id: lineageId, lenses: ["review-reliability"] });
+
+	try {
+		const dispatch: Record<string, unknown> = { agent: "review-reliability", task: "review the recovered successor", mode: "task" };
+		assert.doesNotThrow(() => injectReviewCandidateView(dispatch, registry));
+		assert.match(String(dispatch.task), new RegExp(lineageId));
+	} finally {
+		registry.cleanup(registry.resolveCurrentForLens("review-reliability").token);
+	}
+});
+
+test("a swallowed hydration failure becomes an observable typed dispatch refusal", async (t) => {
+	const cwd = linkedDirtyWorktree(t);
+	const lineageId = "drifted-successor";
+	const registry = new CandidateViewRegistry();
+	// Realistic drift: the frozen candidate names the pristine HEAD tree while
+	// the live worktree carries the uncommitted modification. Hydration
+	// legitimately fails, and that failure must stop being invisible.
+	const live = liveProjection(cwd);
+	const drifted = { ...live, currentCandidateTree: live.baseTree };
+	const finalize = await runController({ operation: "finalize", lineageId, input: JSON.stringify({}) }, cwd, statusNative(successorStatus(lineageId, drifted)), registry);
+
+	assert.equal(finalize.outcome, "reviewer-results-required");
+	assert.equal(registry.hasCurrentBinding(), false);
+	const binding = finalize.dispatch_binding as { hydrated: boolean; lineage_id: string; reason: string; message: string };
+	assert.equal(binding.hydrated, false, "a failed hydration must be reported, never swallowed");
+	assert.equal(binding.lineage_id, lineageId);
+	assert.ok(typeof binding.reason === "string" && binding.reason.length > 0, "the failure carries a typed reason");
+	assert.match(binding.message, /projection|live candidate/i);
+
+	// The dispatch refusal must now admit that hydration was attempted.
+	assert.throws(
+		() => injectReviewCandidateView({ agent: "review-reliability", task: "review", mode: "task" }, registry),
+		(error: unknown) => error instanceof CandidateViewError
+			&& error.reason === "current-binding-hydration-failed"
+			&& /hydrat/i.test(error.message)
+			&& error.message.includes(lineageId),
+	);
+});
+
+test("STATUS keeps hydrating and stays read-only when hydration fails", async (t) => {
+	const cwd = linkedDirtyWorktree(t);
+	const lineageId = "status-drifted-successor";
+	const registry = new CandidateViewRegistry();
+	const statusLive = liveProjection(cwd);
+	const drifted = { ...statusLive, currentCandidateTree: statusLive.baseTree };
+	// STATUS must never fail because hydration failed.
+	const envelope = await runController({ operation: "status", lineageId }, cwd, statusNative(successorStatus(lineageId, drifted)), registry);
+	assert.equal(envelope.operation, "status");
+	assert.equal(registry.hasCurrentBinding(), false);
+	assert.throws(
+		() => injectReviewCandidateView({ agent: "review-reliability", task: "review", mode: "task" }, registry),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "current-binding-hydration-failed",
+	);
+});