gentle-pi 2.5.0 → 2.6.0

package/lib/review-integration-v2.ts

@@ -560,6 +560,29 @@ export interface ReviewManagedAssetsContinuationV1 {
 	staleAssets?: readonly string[];
 }
 
+// gentle-pi#638: one selected lens slot the host declared unachievable
+// through the native capture-unachievable verb, mirrored from Go's
+// ReviewUnachievableLensSlot (internal/cli/review_next_transition.go). The
+// withdraw form is deliberately narrower than a full execute transition:
+// it is the literally runnable retraction command for exactly this slot, so
+// a restart that never saw the collect offer can still take the declaration
+// back from the stop alone.
+export interface ReviewUnachievableLensWithdrawV3 {
+	operation: "review.capture-unachievable";
+	command: string;
+	arguments: readonly ReviewTransitionArgumentV3[];
+	binding: { targetIdentity: string; lineageId?: string; revision?: string };
+}
+
+export interface ReviewUnachievableLensSlotV3 {
+	lens: string;
+	selectedOrder: number;
+	subjectHash: string;
+	reason: string;
+	detail?: string;
+	withdraw: ReviewUnachievableLensWithdrawV3;
+}
+
 export interface ReviewNextTransitionV3 {
 	kind: "execute" | "collect" | "stop";
 	reasonCode: string;
@@ -569,9 +592,26 @@ export interface ReviewNextTransitionV3 {
 	correctionRequest?: ReviewCorrectionPlanRequestV1;
 	/** stop only, reason_code managed_assets_outdated: the sync continuation. */
 	continuation?: ReviewManagedAssetsContinuationV1;
+	/** stop only, reason_code unachievable_lens_slot: one entry per declared slot. */
+	unachievableLensSlots?: readonly ReviewUnachievableLensSlotV3[];
+}
+
+const ESCALATION_CAUSES = ["unknown_causality", "insufficient_evidence", "missing_refuter_outcome", "targeted_validator_rejected", "correction_budget_exceeded", "unresolved_severe_findings"] as const;
+const ESCALATION_REFUTER_OUTCOMES = ["corroborated", "refuted", "inconclusive"] as const;
+export interface ReviewEscalationRefuterOutcomeV1 {
+	findingId: string;
+	outcome: (typeof ESCALATION_REFUTER_OUTCOMES)[number];
+	proof: string;
+}
+export interface ReviewEscalationV1 {
+	cause: (typeof ESCALATION_CAUSES)[number];
+	findingIds: readonly string[];
+	refuterOutcomes?: readonly ReviewEscalationRefuterOutcomeV1[];
 }
 
 export interface ReviewStatusV3 {
+	/** Optional v7 diagnostic evidence, never routing or reconstructed authority. */
+	escalation?: ReviewEscalationV1;
 	contract: typeof REVIEW_INTEGRATION_CONTRACT;
 	applicability: Exclude<ReviewAuthorityApplicability, "not_evaluated">;
 	authority?: ReviewStatusAuthorityV1;
@@ -1712,7 +1752,7 @@ export function decodeReviewManagedAssetsContinuationV1(value: unknown, label: s
 export function decodeReviewNextTransitionV3(value: unknown, options: { v5?: boolean; v6?: boolean } = {}): ReviewNextTransitionV3 {
 	const v6 = options.v6 === true;
 	const v5 = options.v5 === true || v6;
-	const transition = exactRecord(value, "next_transition", ["kind", "reason_code"], ["execute", "collect", ...(v5 ? ["correction_request"] : []), "continuation"]);
+	const transition = exactRecord(value, "next_transition", ["kind", "reason_code"], ["execute", "collect", ...(v5 ? ["correction_request"] : []), "continuation", "unachievable_lens_slots"]);
 	const kind = enumeration(transition.kind, ["execute", "collect", "stop"] as const, "next_transition.kind");
 	const reasonCode = text(transition.reason_code, "next_transition.reason_code", { minimum: 1, pattern: /^[a-z0-9_]+$/ });
 	const continuation = transition.continuation === undefined ? undefined : decodeReviewManagedAssetsContinuationV1(transition.continuation, "next_transition.continuation");
@@ -1722,6 +1762,13 @@ export function decodeReviewNextTransitionV3(value: unknown, options: { v5?: boo
 	// it is only valid on a stop with this exact reason_code.
 	if (continuation !== undefined && !(kind === "stop" && reasonCode === "managed_assets_outdated")) throw new TypeError("next_transition.continuation is only valid for a stop transition with reason_code managed_assets_outdated");
 
+	// gentle-pi#638: the unachievable stop names one entry per declared slot, each carrying its complete withdraw command (schemas/status-v7.schema.json, the stop variant). Like the continuation, the field is only valid on its own exact stop reason code, and an entry is refused rather than silently dropped when the provider drifts.
+	let unachievableLensSlots: readonly ReviewUnachievableLensSlotV3[] | undefined;
+	if (transition.unachievable_lens_slots !== undefined) {
+		if (!(kind === "stop" && reasonCode === "unachievable_lens_slot")) throw new TypeError("next_transition.unachievable_lens_slots is only valid for a stop transition with reason_code unachievable_lens_slot");
+		unachievableLensSlots = array(transition.unachievable_lens_slots, "next_transition.unachievable_lens_slots", decodeUnachievableLensSlot, { minimum: 1 });
+	}
+
 	// status/v5: the bounded correction plan request rides exactly its two
 	// reason codes and never any other (vendored status-v5.schema.json).
 	let correctionRequest: ReviewCorrectionPlanRequestV1 | undefined;
@@ -1770,7 +1817,64 @@ export function decodeReviewNextTransitionV3(value: unknown, options: { v5?: boo
 		return { kind, reasonCode, collect: { inputs }, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
 	}
 	if (transition.execute !== undefined || transition.collect !== undefined) throw new TypeError("next_transition stop cannot carry a transition");
-	return { kind, reasonCode, ...(correctionRequest === undefined ? {} : { correctionRequest }), ...(continuation === undefined ? {} : { continuation }) };
+	return { kind, reasonCode, ...(correctionRequest === undefined ? {} : { correctionRequest }), ...(continuation === undefined ? {} : { continuation }), ...(unachievableLensSlots === undefined ? {} : { unachievableLensSlots }) };
+}
+
+// Mirrors NATIVE_REVIEW_UNACHIEVABLE_LENS_DETAIL_LIMIT (lib/native-review-cli.ts) and Go's 512-byte CAPTURE_UNACHIEVABLE detail bound.
+export const REVIEW_INTEGRATION_UNACHIEVABLE_LENS_DETAIL_LIMIT = 512;
+
+function decodeUnachievableLensSlot(value: unknown, label: string): ReviewUnachievableLensSlotV3 {
+	const body = exactRecord(value, label, ["lens", "selected_order", "subject_hash", "reason", "withdraw"], ["detail"]);
+	const lens = nonempty(body.lens, `${label}.lens`);
+	const selectedOrder = integer(body.selected_order, `${label}.selected_order`);
+	const subjectHash = sha256(body.subject_hash, `${label}.subject_hash`);
+	const reason = nonempty(body.reason, `${label}.reason`);
+	const detail = body.detail === undefined ? undefined : nonempty(body.detail, `${label}.detail`);
+	// gentle-pi#822: Go refuses a CAPTURE_UNACHIEVABLE detail above 512 UTF-8 bytes, so the stop decoder mirrors the same 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.
+	if (detail !== undefined && Buffer.byteLength(detail, "utf8") > REVIEW_INTEGRATION_UNACHIEVABLE_LENS_DETAIL_LIMIT) throw new TypeError(`${label}.detail exceeds ${REVIEW_INTEGRATION_UNACHIEVABLE_LENS_DETAIL_LIMIT} bytes`);
+	const withdraw = exactRecord(body.withdraw, `${label}.withdraw`, ["operation", "command", "arguments", "binding"]);
+	const operation = enumeration(withdraw.operation, ["review.capture-unachievable"] as const, `${label}.withdraw.operation`);
+	const command = nonempty(withdraw.command, `${label}.withdraw.command`);
+	const arguments_ = decodeTransitionArguments(withdraw.arguments, `${label}.withdraw.arguments`);
+	// Withdrawal is a single affirmative native action, never an optional or
+	// negatable provider argument. The general token and command checks below
+	// then prove its exact --withdraw=true rendering is the complete vector.
+	const withdrawArguments = arguments_.filter((argument) => argument.name === "withdraw");
+	if (withdrawArguments.length !== 1) throw new TypeError(`${label}.withdraw.arguments withdraw must appear exactly once`);
+	if (withdrawArguments[0]!.value !== "true") throw new TypeError(`${label}.withdraw.arguments withdraw must be true`);
+	// The binding keeps the execute branch's open-record discipline: the Go shape is target_identity plus optional lineage_id, revision, and repository_context, and closing it here would make Pi stricter than the contract it implements.
+	const binding = exactRecord(withdraw.binding, `${label}.withdraw.binding`, ["target_identity"], ["lineage_id", "revision", "repository_context"], true);
+	const targetIdentity = sha256(binding.target_identity, `${label}.withdraw.binding.target_identity`);
+	const lineageId = binding.lineage_id === undefined ? undefined : lineage(binding.lineage_id, `${label}.withdraw.binding.lineage_id`);
+	const revision = binding.revision === undefined ? undefined : sha256(binding.revision, `${label}.withdraw.binding.revision`);
+	// gentle-pi#822: the withdraw form names the slot identity twice — as named arguments and as the binding object — and the two renderings must agree before the slot decodes. Strict equality also enforces both-or-neither on the optional lineage and revision fields, so a partially rendered binding never slips through and restart cannot withdraw a different slot. Each identity argument must appear EXACTLY once: a first-match lookup let a duplicate {name} entry smuggle a second value past the identity checks.
+	const withdrawIdentityArgument = (name: string): ReviewTransitionArgumentV3 | undefined => {
+		const matches = arguments_.filter((argument) => argument.name === name);
+		if (matches.length > 1) throw new TypeError(`${label}.withdraw.arguments ${name} must appear exactly once`);
+		return matches[0];
+	};
+	const withdrawRequestHash = withdrawIdentityArgument("request-hash");
+	if (withdrawRequestHash?.value !== subjectHash) throw new TypeError(`${label}.withdraw.arguments request-hash does not match the slot subject_hash`);
+	const withdrawTarget = withdrawIdentityArgument("target");
+	if (withdrawTarget?.value !== targetIdentity) throw new TypeError(`${label}.withdraw.arguments target does not match the withdraw binding target_identity`);
+	const withdrawLineage = withdrawIdentityArgument("lineage");
+	if (withdrawLineage?.value !== lineageId) throw new TypeError(`${label}.withdraw.arguments lineage does not match the withdraw binding lineage_id`);
+	const withdrawExpectedRevision = withdrawIdentityArgument("expected-revision");
+	if (withdrawExpectedRevision?.value !== revision) throw new TypeError(`${label}.withdraw.arguments expected-revision does not match the withdraw binding revision`);
+	// gentle-pi#822: command is executable authority, not a display hint. Every
+	// provider-issued argument token must be the canonical --name=value rendering,
+	// and command must render the canonical operation plus those tokens exactly in
+	// order. This rejects omitted tokens, a second command, suffixes, and shell
+	// payloads rather than merely finding identity-token substrings.
+	const tokens = arguments_.map((argument, index) => {
+		if (argument.token === undefined) throw new TypeError(`${label}.withdraw.arguments[${index}].token is required`);
+		const expectedToken = `--${argument.name}=${argument.value}`;
+		if (argument.token !== expectedToken) throw new TypeError(`${label}.withdraw.arguments[${index}].token must exactly render its name and value`);
+		return argument.token;
+	});
+	const expectedCommand = `gentle-ai review capture-unachievable ${tokens.join(" ")}`;
+	if (command !== expectedCommand) throw new TypeError(`${label}.withdraw.command must exactly render the canonical operation and withdraw arguments`);
+	return { lens, selectedOrder, subjectHash, reason, ...(detail === undefined ? {} : { detail }), withdraw: { operation, command, arguments: arguments_, binding: { targetIdentity, ...(lineageId === undefined ? {} : { lineageId }), ...(revision === undefined ? {} : { revision }) } } };
 }
 
 // ---------------------------------------------------------------------------
@@ -1820,7 +1924,7 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 	// key set plus the optional forecast and the v5-only next_transition
 	// surfaces. status/v6 adds the intended-untracked selection; status/v7
 	// (gentle-ai v2.6.0, advertised through capabilities/v2.5 alongside v6)
-	// adds only the top-level optional `eligible_untracked_inventory` digest,
+	// adds optional `eligible_untracked_inventory` and escalation metadata,
 	// so it is decoded on the v6 surface. v3 keeps rejecting every v5/v6/v7-only
 	// field.
 	const schema = typeof value === "object" && value !== null ? (value as Record<string, unknown>).schema : undefined;
@@ -1829,7 +1933,7 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 	const v5 = v6 || schema === "gentle-ai.review-integration.status/v5";
 	const body = exactRecord(value, "status", [
 		"schema", "contract", "operation", "applicability", "action", "replayability", "target_identity", "projection", "repair", "candidates",
-	], ["authority", "frozen", "action_disposition", "eligibility", "next_transition", "authority_target_identity", ...(v5 ? ["receipt", "forecast", "repository_context", "validation_request"] : []), ...(v7 ? ["eligible_untracked_inventory"] : [])]);
+	], ["authority", "frozen", "action_disposition", "eligibility", "next_transition", "authority_target_identity", ...(v5 ? ["receipt", "forecast", "repository_context", "validation_request"] : []), ...(v7 ? ["eligible_untracked_inventory", "escalation"] : [])]);
 	requireIdentity(body, v7 ? "gentle-ai.review-integration.status/v7" : v6 ? "gentle-ai.review-integration.status/v6" : v5 ? "gentle-ai.review-integration.status/v5" : "gentle-ai.review-integration.status/v3", REVIEW_INTEGRATION_OPERATION.STATUS);
 
 	const applicability = enumeration(body.applicability, ["current_target", "unrelated", "ambiguous", "corrupted"] as const, "status.applicability");
@@ -1913,6 +2017,24 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 		};
 	}
 
+	let escalation: ReviewEscalationV1 | undefined;
+	if (Object.hasOwn(body, "escalation")) {
+		const label = "status.escalation";
+		const source = exactRecord(body.escalation, label, ["cause", "finding_ids"], ["refuter_outcomes"]);
+		escalation = {
+			cause: enumeration(source.cause, ESCALATION_CAUSES, `${label}.cause`),
+			findingIds: stringArray(source.finding_ids, `${label}.finding_ids`),
+		};
+		if (Object.hasOwn(source, "refuter_outcomes")) escalation.refuterOutcomes = array(source.refuter_outcomes, `${label}.refuter_outcomes`, (entry, itemLabel) => {
+			const row = exactRecord(entry, itemLabel, ["finding_id", "outcome", "proof"]);
+			return {
+				findingId: nonempty(row.finding_id, `${itemLabel}.finding_id`),
+				outcome: enumeration(row.outcome, ESCALATION_REFUTER_OUTCOMES, `${itemLabel}.outcome`),
+				proof: nonempty(row.proof, `${itemLabel}.proof`),
+			};
+		});
+	}
+
 	// status/v7 top-level optional digest (gentle-ai v2.6.0): resolves #4066's
 	// closed loop where `sdd-attempt finish` named a digest status never
 	// published. Absent on the `staged` projection, which never resolves an
@@ -1940,6 +2062,7 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 		...(forecast === undefined ? {} : { forecast }),
 		...(repositoryContext === undefined ? {} : { repositoryContext }),
 		...(validationRequest === undefined ? {} : { validationRequest }),
+		...(escalation === undefined ? {} : { escalation }),
 		...(eligibleUntrackedInventory === undefined ? {} : { eligibleUntrackedInventory }),
 		raw: body,
 	};
@@ -2450,6 +2573,28 @@ export function decodeReviewAcknowledgedV1(value: unknown, expected: ReviewAckno
 	return decoded;
 }
 
+const REVIEW_LAST_EVENT_FINDING_SEVERITIES = ["BLOCKER", "CRITICAL", "WARNING", "SUGGESTION"] as const;
+const REVIEW_LAST_EVENT_EVIDENCE_CLASSES = ["deterministic", "inferential", "insufficient"] as const;
+const REVIEW_LAST_EVENT_CAUSAL_DISPOSITIONS = ["introduced", "behavior-activated", "worsened", "pre-existing", "base-only", "unknown"] as const;
+
+export interface ReviewLastEventReviewerFindingV1 {
+	id: string;
+	lens: string;
+	location: string;
+	severity: (typeof REVIEW_LAST_EVENT_FINDING_SEVERITIES)[number];
+	claim: string;
+	proofRefs: readonly string[];
+	evidenceClass?: (typeof REVIEW_LAST_EVENT_EVIDENCE_CLASSES)[number];
+	causalDisposition?: (typeof REVIEW_LAST_EVENT_CAUSAL_DISPOSITIONS)[number];
+}
+
+export interface ReviewLastEventReviewerResultV1 {
+	lens: string;
+	findings: readonly ReviewLastEventReviewerFindingV1[];
+	evidence: readonly string[];
+	resultHash: string;
+}
+
 export interface ReviewLastEventClosureV1 {
 	schema: typeof REVIEW_LAST_EVENT_CLOSURE_SCHEMA;
 	operation: ReviewLastEventClosureOperation;
@@ -2461,6 +2606,7 @@ export interface ReviewLastEventClosureV1 {
 	requestHash?: string;
 	correctionLines?: number;
 	advisoryFindings?: ReviewAdvisoryFindingsV1;
+	reviewerResults?: readonly ReviewLastEventReviewerResultV1[];
 	statusContinuation?: ReviewStatusContinuationV1;
 	acknowledgement?: ReviewApprovedAcknowledgementV1;
 	// Set when the provider sent an acknowledgement this decoder could not
@@ -2572,8 +2718,38 @@ function decodeReviewStatusContinuationV1(value: unknown): ReviewStatusContinuat
 	};
 }
 
+function decodeReviewLastEventReviewerFindingV1(value: unknown, label: string): ReviewLastEventReviewerFindingV1 {
+	const finding = exactRecord(value, label, ["id", "lens", "location", "severity", "claim", "proof_refs"], ["evidence_class", "causal_disposition"]);
+	const evidenceClass = finding.evidence_class === undefined
+		? undefined
+		: enumeration(finding.evidence_class, REVIEW_LAST_EVENT_EVIDENCE_CLASSES, `${label}.evidence_class`);
+	const causalDisposition = finding.causal_disposition === undefined
+		? undefined
+		: enumeration(finding.causal_disposition, REVIEW_LAST_EVENT_CAUSAL_DISPOSITIONS, `${label}.causal_disposition`);
+	return {
+		id: nonempty(finding.id, `${label}.id`),
+		lens: nonempty(finding.lens, `${label}.lens`),
+		location: nonempty(finding.location, `${label}.location`),
+		severity: enumeration(finding.severity, REVIEW_LAST_EVENT_FINDING_SEVERITIES, `${label}.severity`),
+		claim: nonempty(finding.claim, `${label}.claim`),
+		proofRefs: stringArray(finding.proof_refs, `${label}.proof_refs`, { minimum: 1 }),
+		...(evidenceClass === undefined ? {} : { evidenceClass }),
+		...(causalDisposition === undefined ? {} : { causalDisposition }),
+	};
+}
+
+function decodeReviewLastEventReviewerResultV1(value: unknown, label: string): ReviewLastEventReviewerResultV1 {
+	const result = exactRecord(value, label, ["lens", "findings", "evidence", "result_hash"]);
+	return {
+		lens: nonempty(result.lens, `${label}.lens`),
+		findings: array(result.findings, `${label}.findings`, decodeReviewLastEventReviewerFindingV1),
+		evidence: stringArray(result.evidence, `${label}.evidence`),
+		resultHash: sha256(result.result_hash, `${label}.result_hash`),
+	};
+}
+
 export function decodeReviewLastEventClosureV1(value: unknown): ReviewLastEventClosureV1 {
-	const body = exactRecord(value, "last_event_closure", ["schema", "operation", "lineage_id", "state", "store_revision"], ["target_identity", "request_hash", "correction_lines", "action", "advisory_findings", "status_continuation", "acknowledgement"]);
+	const body = exactRecord(value, "last_event_closure", ["schema", "operation", "lineage_id", "state", "store_revision"], ["target_identity", "request_hash", "correction_lines", "action", "advisory_findings", "reviewer_results", "status_continuation", "acknowledgement"]);
 	if (body.schema !== REVIEW_LAST_EVENT_CLOSURE_SCHEMA) throw new TypeError(`last_event_closure.schema must be ${REVIEW_LAST_EVENT_CLOSURE_SCHEMA}`);
 	const operation = enumeration(body.operation, Object.values(REVIEW_LAST_EVENT_CLOSURE_OPERATION), "last_event_closure.operation") as ReviewLastEventClosureOperation;
 	const state = enumeration(body.state, REVIEW_LAST_EVENT_TERMINAL_STATES, "last_event_closure.state") as ReviewLastEventClosureState;
@@ -2585,6 +2761,7 @@ export function decodeReviewLastEventClosureV1(value: unknown): ReviewLastEventC
 		storeRevision: sha256(body.store_revision, "last_event_closure.store_revision"),
 	};
 	if (operation === REVIEW_LAST_EVENT_CLOSURE_OPERATION.CAPTURE_CORRECTION_PLAN) {
+		if (body.reviewer_results !== undefined) throw new TypeError("last_event_closure reviewer_results requires approved state");
 		if (body.action !== undefined || body.advisory_findings !== undefined || body.status_continuation !== undefined) throw new TypeError("last_event_closure correction-plan cannot carry action, advisory_findings, or status_continuation");
 		if (state !== "correction_required") throw new TypeError("last_event_closure correction-plan requires correction_required state");
 		return {
@@ -2652,10 +2829,15 @@ export function decodeReviewLastEventClosureV1(value: unknown): ReviewLastEventC
 		? undefined
 		: decodeReviewAdvisoryFindingsV1(body.advisory_findings, "last_event_closure.advisory_findings");
 	if (advisoryFindings !== undefined && state !== "approved") throw new TypeError("last_event_closure advisory_findings requires approved state");
+	const reviewerResults = body.reviewer_results === undefined
+		? undefined
+		: array(body.reviewer_results, "last_event_closure.reviewer_results", decodeReviewLastEventReviewerResultV1);
+	if (reviewerResults !== undefined && state !== "approved") throw new TypeError("last_event_closure reviewer_results requires approved state");
 	return {
 		...shared,
 		action,
 		...(advisoryFindings === undefined ? {} : { advisoryFindings }),
+		...(reviewerResults === undefined ? {} : { reviewerResults }),
 		...(statusContinuation === undefined ? {} : { statusContinuation }),
 		...(acknowledgement === undefined ? {} : { acknowledgement }),
 		...(acknowledgementUndecodable ? { acknowledgementUndecodable: true as const } : {}),

package/lib/review-last-event-controller.ts

@@ -26,11 +26,14 @@ export async function reconcileUnknownReviewLastEventCapture(
 		lineageId: binding.lineageId,
 		...(selector === undefined ? {} : selector),
 	});
-	if (binding.targetIdentity !== undefined && status.targetIdentity !== binding.targetIdentity) {
-		throw new TypeError("capture reconciliation returned a different target");
+	if (status.applicability !== "current_target") {
+		throw new TypeError("capture reconciliation STATUS is not current for the bound target");
 	}
-	if (status.authority?.lineageId !== undefined && status.authority.lineageId !== binding.lineageId) {
-		throw new TypeError("capture reconciliation returned a different lineage");
+	if (status.authority?.lineageId !== binding.lineageId) {
+		throw new TypeError("capture reconciliation returned missing or different lineage authority");
+	}
+	if (binding.targetIdentity === undefined || status.targetIdentity !== binding.targetIdentity) {
+		throw new TypeError("capture reconciliation returned missing or different target");
 	}
 	return status;
 }

package/lib/review-reminder-receipt.ts

@@ -0,0 +1,74 @@
+import { isAbsolute } from "node:path";
+
+// Reminder bookkeeping only: these entries neither define review scope nor grant
+// authority. Both extensions append to the parent's active Pi session branch.
+export const REVIEW_REMINDER_RECEIPT = "gentle-pi.review-reminder-receipt/v1";
+export interface ReceiptSession {
+	getSessionId(): string;
+	getBranch(): readonly { type: string; customType?: string; data?: unknown }[];
+}
+interface ReceiptHost { appendEntry(type: string, data: unknown): void }
+export interface MutationEvidence {
+	source: "direct" | "subagent";
+	toolName: "write" | "edit";
+	toolCallId: string;
+	taskId?: string;
+}
+type Mutation = MutationEvidence & { kind: "mutation"; sessionId: string; root: string; id: string };
+type Consumption = { kind: "nudged" | "acknowledged"; sessionId: string; root: string; through: string; targetIdentity: string };
+type Receipt = Mutation | Consumption;
+const text = (value: unknown): value is string => typeof value === "string" && value.trim().length > 0;
+
+function valid(value: unknown): value is Receipt {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const data = value as Record<string, unknown>;
+	if (!text(data.sessionId) || !text(data.root) || !isAbsolute(data.root)) return false;
+	let fields: string[];
+	if (data.kind === "mutation") {
+		if (!text(data.id) || !text(data.toolCallId) || (data.toolName !== "write" && data.toolName !== "edit")) return false;
+		if (data.source !== "direct" && data.source !== "subagent") return false;
+		if (data.source === "subagent" ? !text(data.taskId) : data.taskId !== undefined) return false;
+		if (data.id !== JSON.stringify([data.source, data.taskId ?? "", data.toolCallId])) return false;
+		fields = ["kind", "sessionId", "root", "id", "source", "toolName", "toolCallId", ...(data.source === "subagent" ? ["taskId"] : [])];
+	} else {
+		if (data.kind !== "nudged" && data.kind !== "acknowledged") return false;
+		if (!text(data.through) || !text(data.targetIdentity)) return false;
+		fields = ["kind", "sessionId", "root", "through", "targetIdentity"];
+	}
+	return Object.keys(data).length === fields.length && fields.every((field) => Object.hasOwn(data, field));
+}
+
+function receipts(session: ReceiptSession, root: string): Receipt[] {
+	const sessionId = session.getSessionId();
+	return session.getBranch().flatMap((entry) => entry.type === "custom" && entry.customType === REVIEW_REMINDER_RECEIPT &&
+		valid(entry.data) && entry.data.sessionId === sessionId && entry.data.root === root ? [entry.data] : []);
+}
+
+export function pendingReviewMutation(session: ReceiptSession, root: string, captured?: string): string | undefined {
+	const mutations: string[] = [];
+	let consumed = -1;
+	for (const receipt of receipts(session, root)) {
+		if (receipt.kind === "mutation") {
+			if (!mutations.includes(receipt.id)) mutations.push(receipt.id);
+		} else {
+			// Only consume the captured prefix, not writes arriving while native
+			// STATUS/ACK was awaited. Unknown or off-branch watermarks do nothing.
+			consumed = Math.max(consumed, mutations.indexOf(receipt.through));
+		}
+	}
+	if (captured !== undefined) return mutations.indexOf(captured) > consumed ? captured : undefined;
+	return mutations.length - 1 > consumed ? mutations.at(-1) : undefined;
+}
+
+export function recordReviewMutation(host: ReceiptHost, session: ReceiptSession, root: string, evidence: MutationEvidence): void {
+	const id = JSON.stringify([evidence.source, evidence.taskId ?? "", evidence.toolCallId]);
+	const receipt: Mutation = { kind: "mutation", sessionId: session.getSessionId(), root, id, ...evidence };
+	if (!valid(receipt) || receipts(session, root).some((entry) => entry.kind === "mutation" && entry.id === id)) return;
+	host.appendEntry(REVIEW_REMINDER_RECEIPT, receipt);
+}
+
+export function consumeReviewMutation(host: ReceiptHost, session: ReceiptSession, root: string, through: string | undefined, kind: Consumption["kind"], targetIdentity: string): void {
+	if (through === undefined) return;
+	const receipt: Consumption = { kind, sessionId: session.getSessionId(), root, through, targetIdentity };
+	if (valid(receipt)) host.appendEntry(REVIEW_REMINDER_RECEIPT, receipt);
+}

package/lib/review-session-standing-permission.ts

@@ -10,6 +10,16 @@ export const REVIEW_SESSION_PERMISSION_REGISTRY_SYMBOL = Symbol.for(REVIEW_SESSI
 
 const execFileAsync = promisify(execFile);
 
+export interface GitCommandOptions {
+	encoding: "utf8";
+	timeout: number;
+	maxBuffer: number;
+	windowsHide?: boolean;
+}
+
+export type GitAsyncRunner = (command: string, args: readonly string[], options: GitCommandOptions) => Promise<{ stdout: string }>;
+export type GitSyncRunner = (command: string, args: readonly string[], options: GitCommandOptions) => string;
+
 export interface ReviewSessionManager {
 	getSessionId(): unknown;
 }
@@ -78,12 +88,16 @@ function validAbsoluteGitPath(value: string): boolean {
 	return isAbsolute(value) && value.length > 0 && !value.includes("\n") && !value.includes("\r");
 }
 
-export async function resolveCanonicalGitWorktreeRoot(cwd: string): Promise<string | undefined> {
+export async function resolveCanonicalGitWorktreeRoot(
+	cwd: string,
+	run: GitAsyncRunner = execFileAsync as unknown as GitAsyncRunner,
+): Promise<string | undefined> {
 	try {
-		const result = await execFileAsync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+		const result = await run("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
 			encoding: "utf8",
 			timeout: 5_000,
 			maxBuffer: 64 * 1024,
+			windowsHide: true,
 		});
 		const output = result.stdout.trim();
 		if (!validAbsoluteGitPath(output)) return undefined;
@@ -94,12 +108,16 @@ export async function resolveCanonicalGitWorktreeRoot(cwd: string): Promise<stri
 }
 
 /** Resolves a non-secret, clone-stable identity from Git's canonical common dir. */
-export async function resolveCanonicalGitRepositoryIdentity(cwd: string): Promise<string | undefined> {
+export async function resolveCanonicalGitRepositoryIdentity(
+	cwd: string,
+	run: GitAsyncRunner = execFileAsync as unknown as GitAsyncRunner,
+): Promise<string | undefined> {
 	try {
-		const result = await execFileAsync("git", ["-C", cwd, "rev-parse", "--git-common-dir"], {
+		const result = await run("git", ["-C", cwd, "rev-parse", "--git-common-dir"], {
 			encoding: "utf8",
 			timeout: 5_000,
 			maxBuffer: 64 * 1024,
+			windowsHide: true,
 		});
 		const output = result.stdout.trim();
 		if (output.length === 0 || output.includes("\n") || output.includes("\r")) return undefined;
@@ -110,9 +128,12 @@ export async function resolveCanonicalGitRepositoryIdentity(cwd: string): Promis
 }
 
 /** The parent AgentRunner binds a child task to this same digest at spawn time. */
-export function resolveCanonicalGitRepositoryIdentitySync(cwd: string): string | undefined {
+export function resolveCanonicalGitRepositoryIdentitySync(
+	cwd: string,
+	run: GitSyncRunner = execFileSync as unknown as GitSyncRunner,
+): string | undefined {
 	try {
-		const output = execFileSync("git", ["-C", cwd, "rev-parse", "--git-common-dir"], { encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024 }).trim();
+		const output = run("git", ["-C", cwd, "rev-parse", "--git-common-dir"], { encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024, windowsHide: true }).trim();
 		if (output.length === 0 || output.includes("\n") || output.includes("\r")) return undefined;
 		return canonicalRepositoryIdentity(realpathSync(resolve(cwd, output)));
 	} catch {