gentle-pi 2.4.0 → 2.6.0

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

@@ -184,6 +184,44 @@ test("failure enforces exact keys, enums, and identifiers", () => {
 	assert.throws(() => decodeReviewFailureV2(badCode), /code/);
 });
 
+test("failure with code managed_assets_outdated decodes its continuation, degrades without one, and forbids it elsewhere", () => {
+	const source: JsonObject = {
+		schema: "gentle-ai.review-integration.failure/v2",
+		contract: REVIEW_INTEGRATION_CONTRACT,
+		operation: "review.start",
+		phase: "preflight",
+		code: "managed_assets_outdated",
+		message: "the managed asset set is stale",
+		mutation_outcome: "not_started",
+		authority_applicability: "current_target",
+		retry_safe: true,
+		replayability: "manual_action_required",
+		required_inputs: [],
+		next_action: "explicit-maintainer-action",
+		continuation: { operation: "sync", command: "gentle-ai sync --agent claude-code", agent: "claude-code", stale_assets: ["orchestration/claude-code.md"] },
+	};
+	assert.deepEqual(decodeReviewFailureV2(source).continuation, { operation: "sync", command: "gentle-ai sync --agent claude-code", agent: "claude-code", staleAssets: ["orchestration/claude-code.md"] });
+
+	const missingCommand = clone(source);
+	delete (missingCommand.continuation as JsonObject).command;
+	assert.throws(() => decodeReviewFailureV2(missingCommand), /command.*required|required.*command/);
+
+	// an older gentle-ai may emit managed_assets_outdated with no continuation
+	// at all; decode must not refuse the whole envelope for that
+	const missingContinuation = clone(source);
+	delete missingContinuation.continuation;
+	assert.equal(decodeReviewFailureV2(missingContinuation).continuation, undefined);
+
+	const unexpectedContinuation: JsonObject = { ...clone(source), code: "gate_scope_changed" };
+	assert.throws(() => decodeReviewFailureV2(unexpectedContinuation), /continuation is only valid/);
+
+	// an envelope without continuation, on a code that does not require one, is unchanged
+	const withoutContinuation = clone(source);
+	withoutContinuation.code = "gate_scope_changed";
+	delete withoutContinuation.continuation;
+	assert.equal(decodeReviewFailureV2(withoutContinuation).continuation, undefined);
+});
+
 test("net-new decoders: consent, next-transition, and artifact-subject reject malformed payloads", () => {
 	const consentSource = fixture<JsonObject>("consent.fixture.json");
 	assertRequired(decodeReviewConsentV2, consentSource, ["schema", "contract", "operation", "action", "blocking", "target_identity", "projection", "risk_level", "changed_files", "changed_lines", "headline", "reason", "value", "risk_evidence", "choices", "off_path"]);
@@ -405,6 +443,205 @@ test("next_transition decodes an execute variant and rejects a stop that carries
 	assert.throws(() => decodeReviewNextTransitionV3(stopWithExecute), /stop cannot carry/);
 });
 
+// gentle-pi#627: gentle-ai reports a stale managed-asset set as a typed stop
+// carrying the exact `gentle-ai sync` invocation that resolves it.
+function managedAssetsContinuation(overrides: Partial<JsonObject> = {}): JsonObject {
+	return { operation: "sync", command: "gentle-ai sync --agent claude-code", agent: "claude-code", stale_assets: ["orchestration/claude-code.md"], ...overrides };
+}
+
+test("next_transition stop decodes a managed_assets_outdated continuation and rejects a malformed one", () => {
+	const stop: JsonObject = { kind: "stop", reason_code: "managed_assets_outdated", continuation: managedAssetsContinuation() };
+	const decoded = decodeReviewNextTransitionV3(stop);
+	assert.deepEqual(decoded.continuation, { operation: "sync", command: "gentle-ai sync --agent claude-code", agent: "claude-code", staleAssets: ["orchestration/claude-code.md"] });
+
+	const bare: JsonObject = { kind: "stop", reason_code: "managed_assets_outdated", continuation: { operation: "sync", command: "gentle-ai sync" } };
+	assert.deepEqual(decodeReviewNextTransitionV3(bare).continuation, { operation: "sync", command: "gentle-ai sync" });
+
+	const missingCommand = clone(stop);
+	delete (missingCommand.continuation as JsonObject).command;
+	assert.throws(() => decodeReviewNextTransitionV3(missingCommand), /command.*required|required.*command/);
+
+	const emptyCommand = clone(stop);
+	(emptyCommand.continuation as JsonObject).command = "";
+	assert.throws(() => decodeReviewNextTransitionV3(emptyCommand), /command/);
+
+	// an older gentle-ai may emit this stop with no continuation at all; decode
+	// must not refuse the whole envelope for that
+	const missingForReasonCode = { kind: "stop", reason_code: "managed_assets_outdated" };
+	assert.equal(decodeReviewNextTransitionV3(missingForReasonCode).continuation, undefined);
+
+	const unexpectedOnOtherReasonCode = { kind: "stop", reason_code: "rdd_disabled", continuation: managedAssetsContinuation() };
+	assert.throws(() => decodeReviewNextTransitionV3(unexpectedOnOtherReasonCode), /continuation is only valid/);
+
+	// envelopes without continuation stay unchanged
+	const plainStop = decodeReviewNextTransitionV3({ kind: "stop", reason_code: "rdd_disabled" });
+	assert.equal(plainStop.continuation, undefined);
+});
+
+// gentle-pi#638: after the host relay declares a selected lens slot
+// unachievable through the native capture-unachievable verb, gentle-ai's
+// STATUS stops with reason_code unachievable_lens_slot and carries one entry
+// per declared slot, each naming the complete withdraw command
+// (contracts/review-integration/v2/schemas/status-v7.schema.json, the stop
+// variant). A restart that never saw the collect offer must still be able to
+// retract the declaration from the stop alone, so the withdraw binding is
+// decoded, never dropped.
+function unachievableSlot(overrides: Partial<JsonObject> = {}): JsonObject {
+	return {
+		lens: "review-risk",
+		selected_order: 0,
+		subject_hash: digest,
+		reason: "relay_transport_bound_exceeded",
+		withdraw: {
+			operation: "review.capture-unachievable",
+			command: `gentle-ai review capture-unachievable --lineage=review-fixture --expected-revision=${digest} --target=${digest} --repository-context=rctx1_${"e".repeat(64)} --request-hash=${digest} --withdraw=true`,
+			arguments: [
+				{ name: "lineage", value: "review-fixture", token: "--lineage=review-fixture" },
+				{ name: "expected-revision", value: digest, token: `--expected-revision=${digest}` },
+				{ name: "target", value: digest, token: `--target=${digest}` },
+				{ name: "repository-context", value: `rctx1_${"e".repeat(64)}`, token: `--repository-context=rctx1_${"e".repeat(64)}` },
+				{ name: "request-hash", value: digest, token: `--request-hash=${digest}` },
+				{ name: "withdraw", value: "true", token: "--withdraw=true" },
+			],
+			binding: { lineage_id: "review-fixture", revision: digest, target_identity: digest, repository_context: `rctx1_${"e".repeat(64)}` },
+		},
+		...overrides,
+	};
+}
+
+test("next_transition stop decodes unachievable_lens_slots and their withdraw bindings only on that reason code", () => {
+	const stop: JsonObject = { kind: "stop", reason_code: "unachievable_lens_slot", unachievable_lens_slots: [unachievableSlot()] };
+	const decoded = decodeReviewNextTransitionV3(stop);
+	assert.equal(decoded.kind, "stop");
+	assert.equal(decoded.reasonCode, "unachievable_lens_slot");
+	const slot = decoded.unachievableLensSlots?.[0];
+	assert.equal(slot?.lens, "review-risk");
+	assert.equal(slot?.selectedOrder, 0);
+	assert.equal(slot?.subjectHash, digest);
+	assert.equal(slot?.reason, "relay_transport_bound_exceeded");
+	assert.equal(slot?.detail, undefined);
+	assert.equal(slot?.withdraw.operation, "review.capture-unachievable");
+	assert.deepEqual(slot?.withdraw.arguments.map((argument) => argument.token), ["--lineage=review-fixture", `--expected-revision=${digest}`, `--target=${digest}`, `--repository-context=rctx1_${"e".repeat(64)}`, `--request-hash=${digest}`, "--withdraw=true"]);
+	assert.equal(slot?.withdraw.binding.targetIdentity, digest);
+	assert.equal(slot?.withdraw.command, `gentle-ai review capture-unachievable --lineage=review-fixture --expected-revision=${digest} --target=${digest} --repository-context=rctx1_${"e".repeat(64)} --request-hash=${digest} --withdraw=true`);
+
+	// detail is the one optional field the schema declares
+	const detailed = decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [unachievableSlot({ detail: "killed after 2256004ms against a 2256000ms relay bound" })] });
+	assert.equal(detailed.unachievableLensSlots?.[0]?.detail, "killed after 2256004ms against a 2256000ms relay bound");
+
+	// malformed entries are refused: a negative selected_order, a slot missing
+	// its withdraw form, a foreign withdraw operation, or an empty array
+	assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [unachievableSlot({ selected_order: -1 })] }), /selected_order/);
+	const withoutWithdraw = unachievableSlot();
+	delete withoutWithdraw.withdraw;
+	assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [withoutWithdraw] }), /withdraw.*required|required.*withdraw/);
+	assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [unachievableSlot({ withdraw: { ...(unachievableSlot().withdraw as JsonObject), operation: "review.capture-result" } })] }), /operation/);
+	assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [] }), /length/);
+
+	// the slots are only valid on their own exact stop reason code
+	assert.throws(() => decodeReviewNextTransitionV3({ kind: "stop", reason_code: "rdd_disabled", unachievable_lens_slots: [unachievableSlot()] }), /unachievable_lens_slots is only valid/);
+	// an execute or collect transition never carries them
+	assert.throws(() => decodeReviewNextTransitionV3({ kind: "execute", reason_code: "fresh_target_ready", execute: { operation: "review.start", arguments: [{ name: "lineage", value: "review-fixture" }], preconditions: [], binding: { target_identity: digest } }, unachievable_lens_slots: [unachievableSlot()] }), /unachievable_lens_slots is only valid/);
+	// plain stops stay unchanged
+	assert.equal(decodeReviewNextTransitionV3({ kind: "stop", reason_code: "rdd_disabled" }).unachievableLensSlots, undefined);
+});
+
+// gentle-pi#822: the withdraw form names the slot identity twice — as named arguments and as the binding object — and a slot whose two renderings disagree never decodes, so restart cannot withdraw a different slot.
+test("next_transition stop refuses an unachievable slot whose withdraw arguments disagree with its identity", () => {
+	const stop: JsonObject = { kind: "stop", reason_code: "unachievable_lens_slot", unachievable_lens_slots: [unachievableSlot()] };
+	const drift = (name: string, value: string): JsonObject => {
+		const drifted = unachievableSlot();
+		const withdraw = drifted.withdraw as JsonObject;
+		withdraw.arguments = (withdraw.arguments as unknown[]).map((argument) => (argument as JsonObject).name === name ? { ...(argument as JsonObject), value } : argument);
+		return drifted;
+	};
+	for (const [name, value] of [["request-hash", `sha256:${"b".repeat(64)}`], ["target", `sha256:${"c".repeat(64)}`], ["lineage", "review-fixture-drifted"], ["expected-revision", `sha256:${"d".repeat(64)}`]] as const) {
+		assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [drift(name, value)] }), new RegExp(`${name} does not match`), name);
+	}
+	// the pristine fixture still decodes with both renderings agreeing
+	assert.doesNotThrow(() => decodeReviewNextTransitionV3(stop));
+});
+
+// gentle-pi#822: identity arguments appear exactly once, and the rendered
+// command is an exact, ordered rendering of every validated provider token.
+// Substring checks would accept a missing non-identity token, repeated command,
+// suffix, or shell payload despite the command no longer naming this slot alone.
+test("next_transition stop refuses duplicate identities and non-exact withdraw commands", () => {
+	const stop: JsonObject = { kind: "stop", reason_code: "unachievable_lens_slot", unachievable_lens_slots: [unachievableSlot()] };
+	const duplicated = unachievableSlot();
+	const duplicatedWithdraw = duplicated.withdraw as JsonObject;
+	duplicatedWithdraw.arguments = [...(duplicatedWithdraw.arguments as unknown[]), { name: "lineage", value: "review-fixture-smuggled", token: "--lineage=review-fixture-smuggled" }];
+	assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [duplicated] }), /withdraw\.arguments lineage must appear exactly once/);
+
+	const canonical = `gentle-ai review capture-unachievable --lineage=review-fixture --expected-revision=${digest} --target=${digest} --repository-context=rctx1_${"e".repeat(64)} --request-hash=${digest} --withdraw=true`;
+	for (const [name, command] of [
+		["omitted token", canonical.replace(" --withdraw=true", "")],
+		["duplicate command", `gentle-ai review capture-unachievable ${canonical}`],
+		["extra suffix", `${canonical} --surplus=true`],
+		["shell payload", `${canonical} && printf injected`],
+	] as const) {
+		const malformed = unachievableSlot();
+		(malformed.withdraw as JsonObject).command = command;
+		assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [malformed] }), /withdraw\.command must exactly render/, name);
+	}
+	assert.doesNotThrow(() => decodeReviewNextTransitionV3(stop));
+});
+
+// gentle-pi#822 (CodeRabbit finding): withdrawal is a narrowly scoped, runnable
+// retraction. Its one affirmative flag is part of the exact native vector, not
+// just another provider-defined argument that a malformed STATUS can omit or
+// negate while still rendering a plausible command.
+test("next_transition stop requires exactly one canonical --withdraw=true argument", () => {
+	const stop: JsonObject = { kind: "stop", reason_code: "unachievable_lens_slot", unachievable_lens_slots: [unachievableSlot()] };
+	const canonicalCommand = (slot: JsonObject): string => {
+		const withdraw = slot.withdraw as JsonObject;
+		return `gentle-ai review capture-unachievable ${(withdraw.arguments as JsonObject[]).map((argument) => String(argument.token)).join(" ")}`;
+	};
+
+	const omitted = unachievableSlot();
+	const omittedWithdraw = omitted.withdraw as JsonObject;
+	omittedWithdraw.arguments = (omittedWithdraw.arguments as JsonObject[]).filter((argument) => argument.name !== "withdraw");
+	omittedWithdraw.command = canonicalCommand(omitted);
+	assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [omitted] }), /withdraw must appear exactly once/);
+
+	const falseValue = unachievableSlot();
+	const falseWithdraw = falseValue.withdraw as JsonObject;
+	falseWithdraw.arguments = (falseWithdraw.arguments as JsonObject[]).map((argument) => argument.name === "withdraw"
+		? { ...argument, value: "false", token: "--withdraw=false" }
+		: argument);
+	falseWithdraw.command = canonicalCommand(falseValue);
+	assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [falseValue] }), /withdraw must be true/);
+
+	const noncanonicalToken = unachievableSlot();
+	const tokenWithdraw = noncanonicalToken.withdraw as JsonObject;
+	tokenWithdraw.arguments = (tokenWithdraw.arguments as JsonObject[]).map((argument) => argument.name === "withdraw"
+		? { ...argument, token: "--withdraw true" }
+		: argument);
+	tokenWithdraw.command = canonicalCommand(noncanonicalToken);
+	assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [noncanonicalToken] }), /token must exactly render/);
+
+	const duplicate = unachievableSlot();
+	const duplicateWithdraw = duplicate.withdraw as JsonObject;
+	duplicateWithdraw.arguments = [...duplicateWithdraw.arguments as JsonObject[], { name: "withdraw", value: "true", token: "--withdraw=true" }];
+	duplicateWithdraw.command = canonicalCommand(duplicate);
+	assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [duplicate] }), /withdraw must appear exactly once/);
+});
+
+// gentle-pi#822 (CodeRabbit finding): Go bounds the CAPTURE_UNACHIEVABLE detail at 512 UTF-8 bytes (native-review-cli.ts enforces the same limit when declaring), so the transition decoder mirrors that bound — measured in bytes, not UTF-16 code units — and a STATUS stop can never carry a detail this client would have refused to declare.
+test("next_transition stop bounds an unachievable slot detail at 512 UTF-8 bytes", () => {
+	const stop: JsonObject = { kind: "stop", reason_code: "unachievable_lens_slot", unachievable_lens_slots: [unachievableSlot()] };
+	// exactly 512 one-byte characters still decodes
+	assert.equal(decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [unachievableSlot({ detail: "a".repeat(512) })] }).unachievableLensSlots?.[0]?.detail, "a".repeat(512));
+	// exactly 512 bytes of two-byte characters still decodes: 256 × 2
+	assert.equal(decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [unachievableSlot({ detail: "é".repeat(256) })] }).unachievableLensSlots?.[0]?.detail, "é".repeat(256));
+	// 257 two-byte characters are 514 bytes
+	assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [unachievableSlot({ detail: "é".repeat(257) })] }), /detail exceeds 512 bytes/);
+	// 171 three-byte characters are 513 bytes
+	assert.throws(() => decodeReviewNextTransitionV3({ ...stop, unachievable_lens_slots: [unachievableSlot({ detail: "世".repeat(171) })] }), /detail exceeds 512 bytes/);
+	// an absent detail still decodes as undefined
+	assert.equal(decodeReviewNextTransitionV3(stop).unachievableLensSlots?.[0]?.detail, undefined);
+});
+
 function approvedAcknowledgementTransition(): JsonObject {
 	return {
 		kind: "execute",
@@ -700,6 +937,40 @@ test("v5 targeted-validator collect inputs carry the exact provider-owned valida
 	assert.throws(() => decodeReviewNextTransitionV3(weakenedRequest, { v5: true }), /policy_content/);
 });
 
+test("status.frozen carries the optional frozen manifest digest", () => {
+	const current = devFixture<JsonObject>("status-v5-repository-context.captured.json");
+	delete current.receipt;
+	if (current.action === "finalize") {
+		current.action = "stop";
+		delete current.next_transition;
+		delete current.forecast;
+	}
+	assert.equal(typeof (current.frozen as JsonObject | undefined)?.tier, "string", "the captured status carries frozen");
+	const digest = `sha256:${"ab".repeat(32)}`;
+	(current.frozen as JsonObject).changed_path_manifest_sha256 = digest;
+	assert.equal(decodeReviewStatusV3(current).frozen?.changedPathManifestSha256, digest);
+	(current.frozen as JsonObject).changed_path_manifest_sha256 = "not-a-digest";
+	assert.throws(() => decodeReviewStatusV3(current), /changed_path_manifest_sha256/);
+	delete (current.frozen as JsonObject).changed_path_manifest_sha256;
+	assert.equal(decodeReviewStatusV3(current).frozen?.changedPathManifestSha256, undefined);
+});
+
+test("a capture-result collect input decodes without changed_path_manifest, which the artifact subject digest already binds", () => {
+	const status = fixture<JsonObject>("status.fixture.json");
+	const transition = clone((status.next_transition ?? {}) as JsonObject);
+	const inputs = ((transition.collect as JsonObject | undefined)?.inputs ?? []) as JsonObject[];
+	const captureInput = inputs.find((input) => input.capture_operation === "review.capture-result");
+	assert.ok(captureInput, "the status fixture carries a capture-result collect input");
+	assert.doesNotThrow(() => decodeReviewNextTransitionV3(transition, { v5: true, v6: true }), "with the manifest");
+	delete captureInput.changed_path_manifest;
+	const decoded = decodeReviewNextTransitionV3(transition, { v5: true, v6: true });
+	const decodedInput = decoded.collect?.inputs.find((input) => input.captureOperation === "review.capture-result");
+	assert.ok(decodedInput?.artifactSubject?.changedPathManifestSha256, "the digest on the artifact subject is the binding");
+	assert.equal(decodedInput?.changedPathManifest, undefined);
+	delete captureInput.artifact_subject;
+	assert.throws(() => decodeReviewNextTransitionV3(transition, { v5: true, v6: true }), /requires artifact_subject, base_tree, and candidate_tree/);
+});
+
 test("status enforces authority/frozen/receipt conditionals and decodes the required repair field", () => {
 	const current = devFixture<JsonObject>("status-v5-repository-context.captured.json");
 	delete current.receipt;
@@ -711,6 +982,11 @@ test("status enforces authority/frozen/receipt conditionals and decodes the requ
 	const decoded = decodeReviewStatusV3(current);
 	assert.equal(decoded.repair.status, "unsupported");
 	assert.equal(decoded.authority?.state, "reviewing");
+	for (const action of ["collect", "execute"]) {
+		const projected = clone(current);
+		projected.action = action;
+		assert.equal(decodeReviewStatusV3(projected).action, action, "a live transaction's root action names its mandated transition kind");
+	}
 
 	const missingAuthority = clone(current);
 	delete missingAuthority.authority;

package/tests/review-last-event-closure.test.ts

@@ -156,6 +156,45 @@ test("strictly decodes the real zero-lens closed START and every last-event clos
 	}
 });
 
+test("approved closure preserves complete admitted reviewer results before acknowledgement", () => {
+	const approved = closure("review/capture-result", "review-results");
+	approved.reviewer_results = [{
+		lens: "review-reliability",
+		findings: [{
+			id: "R3-W01",
+			lens: "reliability",
+			location: "lib/session.ts:4",
+			severity: "SUGGESTION",
+			claim: "the complete explanatory narrative remains available",
+			proof_refs: ["the changed line was inspected"],
+			evidence_class: "insufficient",
+			causal_disposition: "pre-existing",
+		}],
+		evidence: ["inspected the complete frozen candidate"],
+		result_hash: SHA,
+	}];
+	const decoded = decodeReviewLastEventClosureV1(approved);
+	assert.deepEqual(decoded.reviewerResults, [{
+		lens: "review-reliability",
+		findings: [{
+			id: "R3-W01",
+			lens: "reliability",
+			location: "lib/session.ts:4",
+			severity: "SUGGESTION",
+			claim: "the complete explanatory narrative remains available",
+			proofRefs: ["the changed line was inspected"],
+			evidenceClass: "insufficient",
+			causalDisposition: "pre-existing",
+		}],
+		evidence: ["inspected the complete frozen candidate"],
+		resultHash: SHA,
+	}]);
+
+	const correctionPlan = closure("review.capture-correction-plan", "review-results");
+	correctionPlan.reviewer_results = approved.reviewer_results;
+	assert.throws(() => decodeReviewLastEventClosureV1(correctionPlan), /reviewer_results requires approved state/);
+});
+
 test("retired legacy client no longer exposes a FINALIZE route", () => {
 	assert.equal("NativeReviewCliV214" in nativeReviewCliModule, false);
 	assert.equal("NativeReviewCliV213" in nativeReviewCliModule, false);
@@ -331,18 +370,23 @@ test("terminal capture closes directly, nonterminal capture does not auto-follow
 	assert.equal(statusCalls, 2, "only initial STATUS plus one ambiguity reconciliation");
 });
 
-test("unknown-capture reconciliation validates the target-scoped lineage without replay", async () => {
+test("unknown-capture reconciliation preserves agentless legacy callers and forwards an explicit Pi agent", async () => {
 	const calls: Array<Record<string, unknown>> = [];
 	const native = {
 		targetStatus: async (request: Record<string, unknown>) => {
 			calls.push(request);
 			assert.equal(request.lineageId, "reconcile-lineage");
-			return { targetIdentity: SHA, authority: { lineageId: "reconcile-lineage" } } as ReviewStatusV3;
+			return { applicability: "current_target", targetIdentity: SHA, authority: { lineageId: "reconcile-lineage" } } as ReviewStatusV3;
 		},
 	} as unknown as NativeReviewCli;
 	const result = await reconcileUnknownReviewLastEventCapture(native, "/repo", { lineageId: "reconcile-lineage", targetIdentity: SHA });
 	await reconcileUnknownReviewLastEventCapture(native, "/repo", { lineageId: "reconcile-lineage", targetIdentity: SHA }, { baseRef: "refs/heads/main", committedOnly: true });
-	assert.deepEqual(calls, [{ cwd: "/repo", lineageId: "reconcile-lineage" }, { cwd: "/repo", lineageId: "reconcile-lineage", baseRef: "refs/heads/main", committedOnly: true }]);
+	await reconcileUnknownReviewLastEventCapture(native, "/repo", { lineageId: "reconcile-lineage", targetIdentity: SHA }, { agent: "pi" });
+	assert.deepEqual(calls, [
+		{ cwd: "/repo", lineageId: "reconcile-lineage" },
+		{ cwd: "/repo", lineageId: "reconcile-lineage", baseRef: "refs/heads/main", committedOnly: true },
+		{ cwd: "/repo", lineageId: "reconcile-lineage", agent: "pi" },
+	]);
 	assert.equal(result.targetIdentity, SHA);
 	let launches = 0;
 	const strictNative = new nativeReviewCliModule.NativeReviewCliV216(async () => { launches += 1; throw new Error("must not launch"); }, "/package/.gentle-ai/gentle-ai");
@@ -350,6 +394,71 @@ test("unknown-capture reconciliation validates the target-scoped lineage without
 	assert.equal(launches, 0);
 });
 
+test("unknown targeted-validator capture reconciliation requires current exact authority and target", async () => {
+	const lineageId = "targeted-validator-reconciliation";
+	const input = roleInput(lineageId, "review.capture-validation");
+	const expected = status(lineageId, [input]);
+	const cases = [
+		["current matching STATUS", expected, true],
+		["unrelated STATUS", { ...expected, applicability: "unrelated" }, false],
+		["STATUS without authority", { ...expected, authority: undefined }, false],
+		["STATUS for another lineage", { ...expected, authority: { ...expected.authority!, lineageId: "other-lineage" } }, false],
+		["STATUS for another target", { ...expected, targetIdentity: `sha256:${"d".repeat(64)}` }, false],
+	] as const;
+
+	for (const [_name, reconciliationStatus, trusted] of cases) {
+		let statusCalls = 0;
+		let captureCalls = 0;
+		let startCalls = 0;
+		const native = {
+			targetStatus: async () => {
+				statusCalls += 1;
+				return statusCalls === 1 ? expected : reconciliationStatus;
+			},
+			captureProviderRole: async () => {
+				captureCalls += 1;
+				throw Object.assign(new Error("targeted-validator response lost"), {
+					mutationOutcome: "unknown",
+					nextAction: "review.status",
+					failureEnvelope: { raw: { code: "targeted-validator-response-lost" }, mutationOutcome: "unknown" },
+				});
+			},
+			start: async () => { startCalls += 1; },
+		} as unknown as NativeReviewCli;
+
+		const result = await capture(lineageId, input, native);
+		assert.equal(result.outcome, trusted ? "native-capture-outcome-unknown" : "native-capture-status-reconciliation-failed");
+		assert.equal(captureCalls, 1, "an ambiguous capture is never replayed");
+		assert.equal(statusCalls, 2, "an ambiguous capture gets one reconciliation STATUS");
+		assert.equal(startCalls, 0, "reconciliation never invokes START");
+		if (trusted) {
+			assert.equal(result.status, "reconciled");
+			assert.deepEqual((result.native_failure as { native_failure: unknown }).native_failure, { code: "targeted-validator-response-lost" });
+		} else {
+			assert.deepEqual(result.native_failure, { code: "targeted-validator-response-lost" }, "the original capture failure is preserved");
+			assert.ok(result.reconciliation_failure, "the rejected STATUS diagnostic remains nested");
+		}
+	}
+});
+
+test("unknown-capture reconciliation rejects a binding without a target identity", async () => {
+	const lineageId = "missing-reconciliation-target";
+	const input = roleInput(lineageId, "review.capture-validation");
+	let statusCalls = 0;
+	const native = {
+		targetStatus: async () => {
+			statusCalls += 1;
+			return status(lineageId, [input]);
+		},
+	} as unknown as NativeReviewCli;
+
+	await assert.rejects(
+		() => reconcileUnknownReviewLastEventCapture(native, process.cwd(), { lineageId }),
+		/capture reconciliation returned missing or different target/,
+	);
+	assert.equal(statusCalls, 1, "the missing binding is rejected after one reconciliation STATUS");
+});
+
 // One approved terminal closure carrying the exact continuation the provider
 // renders: closed positional arguments, the single approved precondition, and a
 // binding that names the candidate being burned.

package/tests/review-ledger-contract.test.ts

@@ -66,13 +66,28 @@ function assertNativeJsonHasNoMetadata(path: string, value: unknown): void {
 	}
 }
 
-const JUDGMENT_DAY_PATTERNS = [
-	/Judgment Day starts only when explicitly requested and replaces ordinary review for that lineage\./,
+const JUDGMENT_DAY_DISCOVERY_PATTERNS = [
 	/Judgment Day starts with exactly two blind judges and zero refuters\./,
 	/Judgment Day alone may iterate discovery and scoped re-judgment, for at most two rounds\./,
 	/Findings surviving round two escalate; no third-round transition exists\./,
 ] as const;
 
+const JUDGMENT_DAY_STANDALONE_SEMANTICS =
+	"Judgment Day is independent: it neither enables nor replaces ordinary review; a separately requested ordinary review remains independent.";
+
+const OBSOLETE_JUDGMENT_DAY_REPLACEMENT =
+	/Judgment Day starts only when explicitly requested and replaces ordinary review for that lineage\./;
+
+const JUDGMENT_DAY_SEMANTIC_SURFACES = [
+	CANONICAL,
+	JD_SKILL,
+	JD_PROMPTS,
+	...JUDGES,
+	FIX_AGENT,
+	"assets/orchestrator-delegation.md",
+	SDD_WORKFLOW,
+] as const;
+
 const JUDGMENT_DAY_REJUDGMENT_PATTERNS = [
 	/Initial discovery and scoped re-judgment are separate modes\./,
 	/On controller-requested scoped re-judgment, receive only requested frozen IDs, their exact hash-bound rows, and the fix diff\./,
@@ -115,7 +130,7 @@ test("canonical contract defines compact risk, causal admission, correction, CAS
 		/reviewer and validator outputs remain semantically untrusted/i,
 		/do not report.*trusted local orchestrator.*security finding/i,
 		/untrusted repository content.*malformed inputs.*stale authority.*path drift.*external callers/i,
-		...JUDGMENT_DAY_PATTERNS,
+		...JUDGMENT_DAY_DISCOVERY_PATTERNS,
 	]);
 	assert.match(read(README), /Review outcomes and receipt state are informational; commit, push, pull-request, and release delivery follow ordinary repository policy\./);
 	assert.doesNotMatch(read(README), /one one-shot authorization for the exact command/i);
@@ -267,7 +282,7 @@ test("the Pi-owned adversarial role agents are retired: roles execute through Go
 for (const path of JUDGES) {
 	test(`${path} preserves graph-v1 Judgment Day discovery and scoped re-judgment`, () => {
 		const content = read(path);
-		assertMatches(path, content, JUDGMENT_DAY_PATTERNS);
+		assertMatches(path, content, JUDGMENT_DAY_DISCOVERY_PATTERNS);
 		assertMatches(path, content, JUDGMENT_DAY_REJUDGMENT_PATTERNS);
 	});
 }
@@ -303,13 +318,53 @@ test("Judgment Day judge prompts contain distinct graph-v1 discovery and re-judg
 	assert.doesNotMatch(judgePrompt, /End with `Skill Resolution:/);
 });
 
+test("Judgment Day canonical and packaged surfaces preserve the independent lifecycle", () => {
+	for (const path of JUDGMENT_DAY_SEMANTIC_SURFACES) {
+		const content = read(path);
+		assert.ok(content.includes(JUDGMENT_DAY_STANDALONE_SEMANTICS), `${path} must use the current standalone Judgment Day sentence`);
+		assert.doesNotMatch(content, OBSOLETE_JUDGMENT_DAY_REPLACEMENT, `${path} must reject the obsolete replacement semantics`);
+	}
+});
+
 test("Judgment Day skill and prompts preserve bounded fix and re-judgment authority", () => {
-	assertMatches(JD_SKILL, read(JD_SKILL), [...JUDGMENT_DAY_PATTERNS, ...JUDGMENT_DAY_REJUDGMENT_PATTERNS, ...FIX_PATTERNS]);
-	assertMatches(JD_PROMPTS, fencedBlock(JD_PROMPTS, "## Judge Prompt"), JUDGMENT_DAY_PATTERNS);
+	const skill = read(JD_SKILL);
+	const judgePrompt = fencedBlock(JD_PROMPTS, "## Judge Prompt");
+	assertMatches(JD_SKILL, skill, [...JUDGMENT_DAY_DISCOVERY_PATTERNS, ...JUDGMENT_DAY_REJUDGMENT_PATTERNS, ...FIX_PATTERNS]);
+	assertMatches(JD_PROMPTS, judgePrompt, JUDGMENT_DAY_DISCOVERY_PATTERNS);
 	assertMatches(JD_PROMPTS, fencedBlock(JD_PROMPTS, "## Fix Agent Prompt"), FIX_PATTERNS);
 	assertMatches(FIX_AGENT, read(FIX_AGENT), FIX_PATTERNS);
 });
 
+test("Judgment Day fix routing has one canonical shape and never falls back to generic roles", () => {
+	const canonicalShape = [
+		"## Judgment Day activation",
+		"User explicitly requested Judgment Day.",
+		"## Exact authorized severe IDs",
+		"- `JD-A-001`",
+		"## Judgment Day correction batch",
+		"Round: 1 of 2.",
+		"Frozen ledger SHA-256: `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`",
+		"## Exact frozen finding rows",
+		'{"id":"JD-A-001","lens":"judgment-day","location":"path/to/authorized-file.ts:1","severity":"CRITICAL","status_at_freeze":"open","evidence_class":"deterministic","evidence_claim":"Concrete user-impact claim supported by the frozen location."}',
+		"## Allowed edit surfaces",
+	].join("\n");
+	for (const [path, content] of [
+		[CANONICAL, read(CANONICAL)],
+		[FIX_AGENT, read(FIX_AGENT)],
+		[JD_SKILL, read(JD_SKILL)],
+		[JD_PROMPTS, fencedBlock(JD_PROMPTS, "## Fix Agent Prompt")],
+		["assets/orchestrator-delegation.md", read("assets/orchestrator-delegation.md")],
+		[SDD_WORKFLOW, read(SDD_WORKFLOW)],
+	] as const) {
+		assert.ok(content.includes(canonicalShape), `${path} must carry the canonical Judgment Day fix shape`);
+		assert.match(content, /requires no graph-v1 or native review lineage/i);
+	}
+	const routing = `${read("assets/orchestrator-delegation.md")}\n${read(SDD_WORKFLOW)}`;
+	assert.match(routing, /Judgment Day phase roles are never generic fallbacks\./);
+	assert.match(routing, /If the generic writer chain is unavailable, use the documented native generic fallback or stop\./);
+	assert.match(read(SDD_WORKFLOW), /\| default\s+\| balanced\s+\| SDD phase fallback; never a Judgment Day role\s+\|/);
+});
+
 test("orchestrator, injected skill, and README defer RDD lifecycle ownership to Gentle AI", () => {
 	const boundary = "This package injects the mirrored provider-bundle review execution contract into this session's system prompt at start; Gentle AI writes nothing into the Pi system prompt, and this package owns everything else here. Absent that mirrored contract, this package invents no lifecycle instructions.";
 	const orchestrator = union(ORCHESTRATOR);

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

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import { declareReviewRelayHandshake, GENTLE_PI_REVIEW_RELAY_CONTRACT, GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV } from "../lib/review-relay-contract.ts";
+
+// gentle-pi#550: the session shell must inherit the relay handshake, so a
+// `gentle-ai review ... --agent pi` typed in a shell tool is eligible without
+// the operator reading package source for the value.
+
+test("declareReviewRelayHandshake exports the exact contract and reports whether it changed anything", () => {
+	const env: NodeJS.ProcessEnv = {};
+	assert.equal(declareReviewRelayHandshake(env), true);
+	assert.equal(env[GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV], GENTLE_PI_REVIEW_RELAY_CONTRACT);
+	assert.equal(declareReviewRelayHandshake(env), false, "already declared");
+	const stale: NodeJS.ProcessEnv = { [GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV]: "gentle-pi.review-relay/v0" };
+	assert.equal(declareReviewRelayHandshake(stale), true, "a wrong value is replaced: this extension is the host");
+	assert.equal(stale[GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV], GENTLE_PI_REVIEW_RELAY_CONTRACT);
+});
+
+test("loading the extension declares the handshake in the session environment", () => {
+	const processEnv: NodeJS.ProcessEnv = { PATH: "/bin" };
+	createGentleAiExtension({ nativeReviewCli: null, processEnv })({ on() {}, registerTool() {}, registerCommand() {} } as unknown as ExtensionAPI);
+	assert.equal(processEnv[GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV], GENTLE_PI_REVIEW_RELAY_CONTRACT);
+	assert.equal(processEnv.PATH, "/bin");
+});

package/tests/review-reminder-receipt.test.ts

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { consumeReviewMutation, pendingReviewMutation, recordReviewMutation, REVIEW_REMINDER_RECEIPT } from "../lib/review-reminder-receipt.ts";
+
+function fixture() {
+	let sessionId = "parent";
+	const entries: Array<{ type: string; customType: string; data: unknown }> = [];
+	const session = { getSessionId: () => sessionId, getBranch: () => entries };
+	const host = { appendEntry: (customType: string, data: unknown) => { entries.push({ type: "custom", customType, data }); } };
+	const write = (toolCallId: string, root = "/repo") => recordReviewMutation(host, session, root, { source: "direct", toolName: "write", toolCallId });
+	return { host, session, entries, write, switchSession: (id: string) => { sessionId = id; } };
+}
+
+test("receipts survive reload but are isolated by session, root, and active branch", () => {
+	const f = fixture();
+	f.write("a");
+	const captured = pendingReviewMutation(f.session, "/repo");
+	assert.ok(captured);
+	assert.equal(pendingReviewMutation({ ...f.session }, "/repo"), captured);
+	assert.equal(pendingReviewMutation(f.session, "/sibling"), undefined);
+	f.switchSession("fork");
+	assert.equal(pendingReviewMutation(f.session, "/repo"), undefined);
+	f.switchSession("new");
+	assert.equal(pendingReviewMutation(f.session, "/repo"), undefined);
+	f.switchSession("parent");
+	assert.equal(pendingReviewMutation({ ...f.session, getBranch: () => [] }, "/repo"), undefined);
+	f.write("a");
+	assert.equal(f.entries.length, 1, "duplicate tool completion cannot re-enable a generation");
+});
+
+for (const kind of ["nudged", "acknowledged"] as const) {
+	test(`${kind} consumes only its captured prefix, retaining a concurrent own mutation`, () => {
+		const f = fixture();
+		f.write("a");
+		const captured = pendingReviewMutation(f.session, "/repo");
+		f.write("b");
+		consumeReviewMutation(f.host, f.session, "/repo", captured, kind, "whole-target");
+		assert.equal(pendingReviewMutation(f.session, "/repo", captured), undefined);
+		const next = pendingReviewMutation(f.session, "/repo");
+		assert.ok(next && next !== captured);
+		consumeReviewMutation(f.host, f.session, "/repo", next, kind, "whole-target");
+		assert.equal(pendingReviewMutation(f.session, "/repo"), undefined);
+		f.write("c");
+		assert.ok(pendingReviewMutation(f.session, "/repo"));
+	});
+}
+
+test("malformed, unknown-version, and unmatched consumption entries do not establish ownership", () => {
+	const f = fixture();
+	f.write("valid");
+	const good = f.entries.pop()!;
+	const data = good.data as Record<string, unknown>;
+	for (const patch of [{ kind: "spawn" }, { source: "prose" }, { toolName: "bash" }, { sessionId: "" }, { root: "relative" }, { taskId: "foreign" }, { extra: true }, { toolCallId: "" }, { id: null }]) {
+		f.entries.push({ ...good, data: { ...data, ...patch } });
+	}
+	f.entries.push({ ...good, customType: "gentle-pi.review-reminder-receipt/v99" });
+	assert.equal(pendingReviewMutation(f.session, "/repo"), undefined);
+	f.entries.push(good);
+	const captured = pendingReviewMutation(f.session, "/repo");
+	consumeReviewMutation(f.host, f.session, "/repo", "unknown", "acknowledged", "target");
+	assert.equal(pendingReviewMutation(f.session, "/repo"), captured);
+});