gentle-pi 2.1.1 → 2.2.0

package/lib/native-review-cli.ts

@@ -5,18 +5,21 @@ import { chmod, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, posix, win32 } from "node:path";
 import { promisify } from "node:util";
-import { GENTLE_AI_VERSION, PackageLocalGentleAiBinaryMissingError, resolveGentleAiBinary } from "./gentle-ai-binary.ts";
+import { GENTLE_AI_VERSION, PackageLocalGentleAiBinaryMissingError, gentleAiDevBinaryOverrideConfigured, resolveGentleAiBinary } from "./gentle-ai-binary.ts";
+import { GENTLE_PI_REVIEW_RELAY_CONTRACT, GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV } from "./review-relay-contract.ts";
 import {
 	REVIEW_INTEGRATION_CONTRACT,
 	decodeReviewCapabilitiesV2,
 	decodeReviewConsentV2,
+	decodeReviewConsentV3,
 	decodeReviewFailureV2,
 	decodeReviewOperationV2,
 	decodeReviewRepairV2,
+	decodeReviewResultArtifactV2,
 	decodeReviewStartV3,
 	decodeReviewStatusV3,
 	type ReviewCapabilitiesV2,
-	type ReviewConsentV2,
+	type ReviewConsentEnvelope,
 	type ReviewFailureV2,
 	type ReviewRepairV2,
 	type ReviewStartState,
@@ -25,6 +28,23 @@ import {
 
 const execFileAsync = promisify(execFile);
 
+// Negotiated review/status responses can carry a complete authority inventory.
+// Keep the production default large enough for that payload while retaining a
+// hard 64 MiB ceiling even when GENTLE_PI_REVIEW_MAX_BUFFER_BYTES is set.
+export const NATIVE_REVIEW_DEFAULT_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+const NATIVE_REVIEW_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+const NATIVE_REVIEW_MAX_BUFFER_BYTES_ENV = "GENTLE_PI_REVIEW_MAX_BUFFER_BYTES";
+const NATIVE_REVIEW_MAX_BUFFER_CONFIGURATION_HINT = "Inspect native review state before any new START; GENTLE_PI_REVIEW_MAX_BUFFER_BYTES accepts a positive decimal up to 67108864.";
+
+function resolveNativeReviewMaxBufferBytes(environment: NodeJS.ProcessEnv = process.env): number {
+	const value = environment[NATIVE_REVIEW_MAX_BUFFER_BYTES_ENV];
+	if (value === undefined || !/^[1-9]\d*$/.test(value)) return NATIVE_REVIEW_DEFAULT_MAX_BUFFER_BYTES;
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) && parsed <= NATIVE_REVIEW_MAX_BUFFER_BYTES
+		? parsed
+		: NATIVE_REVIEW_DEFAULT_MAX_BUFFER_BYTES;
+}
+
 export const NATIVE_REVIEW_OPERATION = {
 	VERSION: "version",
 	START: "review/start",
@@ -43,6 +63,7 @@ export const NATIVE_REVIEW_OPERATION = {
 	REPAIR: "review/repair",
 	CAPTURE_EVIDENCE: "review/capture-evidence",
 	CAPTURE_RESULT: "review/capture-result",
+	CAPTURE_PROVIDER_ROLE: "review/capture-provider-role",
 } as const;
 export type NativeReviewOperation = (typeof NATIVE_REVIEW_OPERATION)[keyof typeof NATIVE_REVIEW_OPERATION];
 
@@ -118,6 +139,22 @@ export interface NativeReviewCli {
 	// evidence-first correction lifecycle's collection step.
 	repair?(request: NativeReviewRepairRequest): Promise<ReviewRepairV2>;
 	captureEvidence?(request: NativeReviewCaptureEvidenceRequest): Promise<NativeReviewVerificationEvidenceV2>;
+	// Executes one provider-rendered capture-evidence submission exactly as
+	// rendered (verbatim tokens with only the {{outcome}}/{{input}} slot
+	// substitutions); the preferred form whenever the collect slot renders one.
+	captureEvidenceSubmission?(request: NativeReviewCaptureEvidenceSubmissionRequest): Promise<NativeReviewVerificationEvidenceV2>;
+	// gentle-pi#311 P4-roles: executes one provider-rendered self-contained
+	// role capture vector exactly as rendered (verbatim tokens, foreground).
+	captureProviderRole?(request: NativeReviewProviderRoleCaptureRequest): Promise<NativeReviewProviderRoleCaptureArtifact>;
+	// gentle-pi#311 P5: executes one provider-rendered `review.finalize`
+	// transition exactly as rendered (e.g. `--lineage=<id>
+	// --captured-results=true`); the host never assembles reviewer, refuter,
+	// or validator documents for it.
+	finalizeTransition?(request: NativeReviewFinalizeTransitionRequest): Promise<NativeFinalizeResult>;
+	// Executes one provider-rendered `finalize` submission descriptor exactly
+	// as rendered, substituting only its {{value}} slot (plan line-count
+	// literal, or a staged validation artifact path).
+	finalizeSubmission?(request: NativeReviewFinalizeSubmissionRequest): Promise<NativeFinalizeResult>;
 	// Dark until a negotiated version reports the `mode` capability true
 	// (Design Decision #7, organic-rdd-parity). Plain versioned CLI operation,
 	// outside the negotiated review-integration protocol — same shape as
@@ -175,18 +212,24 @@ export interface NativeReviewModeResult {
 
 // Exact-match tolerated-stderr allowlist for START only, gated on the `mode`
 // capability being true (Design Decision #6, organic-rdd-parity). Byte-exact
-// against gentle-ai's headless notice (internal/cli/review_mode.go
-// reviewConsentSkippedNotice) written when the switch is on but no interactive
-// terminal answered the one-time consent question — which is always true when
-// Pi spawns gentle-ai without a TTY. Any other text still fails closed as
-// UNEXPECTED_STDERR.
-// Each entry is one whole line gentle-ai may write to the console stream while
-// still succeeding. The provenance line rides with the skip notice whenever the
-// resolved mode source is `default`, so a headless START legitimately emits two
-// lines; they are separate Fprintln calls, never one joined string.
+// against gentle-ai's headless notices (internal/cli/review_mode.go
+// reviewConsentSkippedNotice and its siblings) written when the switch is on
+// but no interactive terminal answered the one-time consent question — which
+// is always true when Pi spawns gentle-ai without a TTY. Any other text still
+// fails closed as UNEXPECTED_STDERR.
+//
+// Each entry is one whole line the PINNED gentle-ai may write to the console
+// stream while still succeeding. That last qualifier is what keeps this list
+// honest: v2.4.0 deleted reviewConsentSkippedDefaultProvenance ("Reviews are
+// on by default; this was never explicitly chosen. ..."), which used to ride
+// with the skip notice whenever the resolved mode source was `default`. Under
+// opt-in receipt-driven development a default-source clone is refused long
+// before the consent ceremony runs, so the pinned binary can no longer emit
+// that line and it is removed here rather than left as dead tolerance. Multi-
+// line stderr is still expected in principle — these are separate Fprintln
+// calls, never one joined string — which is why membership is per line.
 export const REVIEW_CONSENT_NOTICES = Object.freeze([
 	"Gentle AI reviewed this change without asking, because this session has no terminal to answer on. Run 'gentle-ai review mode disable' to turn reviews off, or 'gentle-ai review mode status' to see the current setting.",
-	"Reviews are on by default; this was never explicitly chosen. Run 'gentle-ai review mode enable' to make reviews an explicit choice, or 'gentle-ai review mode disable' to turn them off.",
 	"Gentle AI could not read an answer, so it reviewed this change and will ask again next time.",
 	"Gentle AI did not recognize that answer, so it reviewed this change and will ask again next time.",
 	"Review skipped for this candidate at your request. It will be offered again on the next change.",
@@ -201,6 +244,22 @@ function stderrIsTolerated(stderr: string, tolerated: readonly string[]): boolea
 	return lines.length > 0 && lines.every((line) => tolerated.includes(line));
 }
 
+// gentle-ai main narrates the negotiated STATUS forecast head to a human on
+// stderr while keeping the machine envelope on stdout (reviewNarrateForecast
+// in internal/cli/review_narration.go, ground-truthed live against a main-line
+// dev build). The pinned release does not emit it, so this narration is
+// tolerated only for negotiated STATUS while the dev-binary override is
+// configured; any other stderr keeps failing closed.
+const FORECAST_NARRATION_LINES = Object.freeze([
+	/^Forecast horizon: (?:partial|terminal)$/,
+	/^step [0-9]+: (?:execute|collect|stop); reason_code=[a-z0-9_]+; description=.+$/,
+	/^Re-query STATUS after completing this partial head\.$/,
+]);
+function stderrIsForecastNarration(stderr: string): boolean {
+	const lines = stderr.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+	return lines.length > 0 && lines.every((line) => FORECAST_NARRATION_LINES.some((pattern) => pattern.test(line)));
+}
+
 export const NATIVE_REVIEW_RECOVER_DISPOSITION = ["scope_changed", "invalidated", "escalated"] as const;
 export type NativeReviewRecoverDisposition = (typeof NATIVE_REVIEW_RECOVER_DISPOSITION)[number];
 
@@ -244,6 +303,9 @@ export interface NativeReviewAbandonRequest {
 	lineage: string;
 	expectedRevision: string;
 	snapshotIdentity: string;
+	capturedLensResults: readonly string[];
+	findingsPresent: boolean;
+	evidenceRecordsPresent: boolean;
 	actor: string;
 	reason: string;
 	maintainerAuthorization: string;
@@ -345,6 +407,33 @@ export interface NativeReviewAdmittedResultManifest {
 	readonly reference?: string;
 }
 
+// gentle-pi#311 P4-roles: one Go-owned non-lens provider role capture. The
+// provider renders a SELF-CONTAINED authority-advancing vector
+// (`review.capture-refuter` / `review.capture-validation` with binding tokens
+// plus `--agent=pi --execute=true`, no submission descriptor); Pi executes the
+// exact rendered invocation verbatim, in the foreground, and Go materializes
+// the role prompt, spawns its own locked-down pi subprocess, and admits the
+// raw verdict. Nothing here authors, parses, or transports role output.
+export const NATIVE_REVIEW_PROVIDER_ROLE_CAPTURE_SCHEMA = "gentle-ai.review-provider-role-capture/v1";
+
+export interface NativeReviewProviderRoleCaptureRequest {
+	/** The provider-named capture operation, e.g. `review.capture-refuter`. */
+	readonly captureOperation: string;
+	/** Every provider-issued argument token, verbatim, in provider order. */
+	readonly argumentTokens: readonly string[];
+	/** Process working directory only; never rendered into the invocation. */
+	readonly cwd: string;
+	readonly signal?: AbortSignal;
+}
+
+export interface NativeReviewProviderRoleCaptureArtifact {
+	readonly schema: typeof NATIVE_REVIEW_PROVIDER_ROLE_CAPTURE_SCHEMA;
+	readonly lineageId: string;
+	readonly targetIdentity: string;
+	readonly role: string;
+	readonly captured: true;
+}
+
 export interface NativeReviewCaptureEvidenceRequest {
 	cwd: string;
 	lineageId: string;
@@ -355,6 +444,27 @@ export interface NativeReviewCaptureEvidenceRequest {
 	signal?: AbortSignal;
 }
 
+// Field defect (fambig, 2026-08-16): the evidence collect slot renders the
+// exact submission tokens native admits — fix-diff `--target`,
+// `--expected-revision`, and an opaque cwd-independent `--repository-context` —
+// with `{{outcome}}`/`{{input}}` substitution slots. Satisfying the slot means
+// executing those tokens verbatim with only the two slot substitutions, the
+// same discipline captureResult uses; identities are never reconstructed from
+// top-level status fields.
+export interface NativeReviewCaptureEvidenceSubmissionRequest {
+	/** Process working directory; forbidden when the tokens carry --repository-context (the context is cwd-independent). */
+	cwd?: string;
+	/** Provider-rendered submission argument tokens, verbatim, in provider order. */
+	argumentTokens: readonly string[];
+	/** Index of the token carrying the {{outcome}} substitution slot. */
+	outcomeSubstitutionLocation: number;
+	/** Index of the token carrying the {{input}} substitution slot. */
+	inputSubstitutionLocation: number;
+	outcome: NativeReviewCaptureOutcome;
+	evidenceDocument: string;
+	signal?: AbortSignal;
+}
+
 export interface NativeReviewVerificationEvidenceV2 {
 	schema: "gentle-ai.review-verification-evidence/v2";
 	version: 2;
@@ -374,7 +484,7 @@ export interface NativeReviewVerificationEvidenceV2 {
 export interface NativeStartRequest { cwd: string; baseRef?: string; committedOnly?: boolean; lineageId?: string; policyPath?: string; focus?: string; targetIdentity?: string; projection?: "workspace" | "staged"; signal?: AbortSignal; }
 export const NATIVE_REVIEW_CONSENT_ANSWER = { GRANTED: "granted", DECLINED: "declined" } as const;
 export type NativeReviewConsentAnswer = (typeof NATIVE_REVIEW_CONSENT_ANSWER)[keyof typeof NATIVE_REVIEW_CONSENT_ANSWER];
-export interface NativeReviewConsentAnswerRequest { cwd: string; consent: ReviewConsentV2; answer: NativeReviewConsentAnswer; signal?: AbortSignal; }
+export interface NativeReviewConsentAnswerRequest { cwd: string; consent: ReviewConsentEnvelope; answer: NativeReviewConsentAnswer; signal?: AbortSignal; }
 export interface NativeReviewConsentDeclinedResult {
 	kind: "declined";
 	targetIdentity: string;
@@ -403,12 +513,56 @@ export interface NativeFinalizeRequest extends NativeReviewFinalizeCapturedResul
 	failed?: boolean;
 	signal?: AbortSignal;
 }
+// gentle-pi#311 P5: the provider-driven FINALIZE. `argumentTokens` are the
+// exact rendered tokens of one provider-returned `review.finalize` execute
+// transition (e.g. `--lineage=<id> --captured-results=true`), passed through
+// verbatim and never synthesized or reordered by the host.
+export interface NativeReviewFinalizeTransitionRequest {
+	readonly cwd: string;
+	readonly argumentTokens: readonly string[];
+	readonly signal?: AbortSignal;
+}
+
+// The provider-rendered `finalize` submission descriptor forms (status/v5):
+// the correction PLAN slot substitutes a positive line-count literal into its
+// {{value}} token; the TARGETED VALIDATION slot substitutes a staged validator
+// artifact path. The tokens are self-contained and execute verbatim.
+export interface NativeReviewFinalizeSubmissionRequest {
+	/** Process working directory only; the rendered tokens are self-contained. */
+	readonly cwd: string;
+	/** Provider-rendered submission argument tokens, verbatim, in provider order. */
+	readonly argumentTokens: readonly string[];
+	/** Index of the token carrying the {{value}} substitution slot. */
+	readonly valueSubstitutionLocation: number;
+	/** The literal substitution (correction_lines). Exactly one of valueLiteral/valueDocument. */
+	readonly valueLiteral?: string;
+	/** The document to stage as a 0o600 artifact whose path substitutes {{value}} (validation). */
+	readonly valueDocument?: string;
+	readonly signal?: AbortSignal;
+}
+
 export interface NativeValidateRequest { cwd: string; gate: string; lineageId?: string; flags?: readonly string[]; signal?: AbortSignal; }
 export interface NativeBindSddRequest { cwd: string; change: string; lineage: string; expectedBindingRevision: string; signal?: AbortSignal; }
 export interface NativeSddStatusRequest { cwd: string; change: string; signal?: AbortSignal; }
 export interface NativeReviewStatusRequest { cwd: string; signal?: AbortSignal; }
 export interface NativeCapabilitiesRequest { cwd?: string; signal?: AbortSignal; }
-export interface NativeTargetStatusRequest { cwd: string; lineageId?: string; baseRef?: string; projection?: "workspace" | "staged"; signal?: AbortSignal; }
+export interface NativeTargetStatusRequest {
+	cwd: string;
+	lineageId?: string;
+	baseRef?: string;
+	projection?: "workspace" | "staged";
+	/**
+	 * The immutable reviewer runtime this host provides. Measured against the
+	 * live 2.4.0-main provider: the materialize-marked relay slot (agent=pi,
+	 * materialize=true, plus the provider submission) is offered ONLY when the
+	 * caller names its agent; an agent-less status returns a bare
+	 * capture-result input the host relay cannot consume. Providers older than
+	 * v2.4.0 do not define the flag and refuse it, so callers probe and fall
+	 * back rather than version-sniff.
+	 */
+	agent?: "pi";
+	signal?: AbortSignal;
+}
 export interface NativeGateContext { lineageId: string; storeRevision: string; raw: Record<string, unknown>; }
 
 export const NATIVE_REVIEW_AUTHORITY_STATUS = {
@@ -480,6 +634,7 @@ export interface NativeReviewAuthorityEntry {
 	status: NativeReviewAuthorityEntryStatus;
 	state?: string;
 	revision?: string;
+	snapshotIdentity?: string;
 	chainIdentity?: string;
 	recovery?: NativeReviewRecovery;
 	problems: readonly string[];
@@ -665,6 +820,20 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// advertises capabilities/v1.5 and the negotiated start envelope is still
 	// the closed `start/v2`, so riskEvidence and hint still cannot arrive.
 	"2.2.2": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, sddStatus: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// Ground-truthed against the released v2.2.3 binary: the v2 lane remains
+	// protocol 2.0 with the same operation set and closed START fields consumed
+	// by Pi, so the existing capability columns are unchanged.
+	"2.2.3": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, sddStatus: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// Ground-truthed against the released v2.4.0 binary: the v2 lane advertises
+	// capabilities/v2.2 and answers status/v5 and consent/v3, all of which the
+	// existing decoders already read, and the START envelope Pi consumes is
+	// still `start/v3` carrying `risk_reasons` with no `risk_evidence` and no
+	// `hint`, so the existing capability columns are unchanged. v2.4.0 also
+	// made receipt-driven development opt-in, which changes what the mode
+	// envelope reports, not whether it reports it. v2.2.4 and v2.3.0 shipped
+	// while Pi stayed on 2.2.3; they were never pinned or probed, so they get
+	// no row.
+	"2.4.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, sddStatus: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 type NativeCliCapability = keyof (typeof NATIVE_CLI_CONTRACTS)[keyof typeof NATIVE_CLI_CONTRACTS];
 
@@ -681,6 +850,21 @@ function resolvedNativeCliContract(version: string): Record<NativeCliCapability,
 	return nativeCliContractsTestingOverlay.get(version) ?? (NATIVE_CLI_CONTRACTS as Record<string, Record<NativeCliCapability, boolean> | undefined>)[version];
 }
 
+// The latest known contract row, used as the capability floor for the
+// explicit dev-binary override (unpinned field-test mode): a maintainer
+// dev build is at least as capable as the newest release Pi knows. The table
+// is declared in ascending release order, so its last key is the latest.
+const LATEST_NATIVE_CLI_CONTRACT_VERSION = Object.keys(NATIVE_CLI_CONTRACTS).at(-1) as keyof typeof NATIVE_CLI_CONTRACTS;
+
+// Dev-binary override version discipline: with the override configured, a
+// version reported outside the pinned table resolves to the latest known row;
+// with the override absent, behavior is byte-identical to the pinned gate.
+function effectiveNativeCliContract(version: string): Record<NativeCliCapability, boolean> | undefined {
+	const pinned = resolvedNativeCliContract(version);
+	if (pinned !== undefined) return pinned;
+	return gentleAiDevBinaryOverrideConfigured() ? NATIVE_CLI_CONTRACTS[LATEST_NATIVE_CLI_CONTRACT_VERSION] : undefined;
+}
+
 export interface NativeReviewStructuredDenial {
 	schema: "gentle-ai.review-gate-result/v1";
 	result: "scope-changed" | "invalidated" | "escalated";
@@ -696,6 +880,8 @@ export interface NativeReviewProcessDiagnostics {
 	signal?: NodeJS.Signals;
 	timed_out: boolean;
 	output_limit_exceeded: boolean;
+	max_buffer_bytes?: number;
+	configuration_hint?: string;
 	stderr?: string;
 	denial?: NativeReviewStructuredDenial;
 }
@@ -723,15 +909,25 @@ export class NativeReviewCliError extends Error {
 	}
 }
 
+// The one central runner for every gentle-ai CLI invocation the extension
+// makes. It declares the Pi host relay handshake on each spawn: gentle-ai
+// refuses pi admission pre-authority without it (gentle-pi#311 P4), and a
+// single injection point keeps the declaration impossible to forget on any
+// individual operation.
+export function gentleAiProcessEnvironment(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+	return { ...base, [GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV]: GENTLE_PI_REVIEW_RELAY_CONTRACT };
+}
+
 export function createNodeExecFileAdapter(): ExecFileAdapter {
 	return async (request) => {
 		try {
-			const output = await execFileAsync(request.file, [...request.arguments], { cwd: request.cwd, encoding: "utf8", shell: false, windowsHide: true, timeout: request.timeoutMs, maxBuffer: request.maxBufferBytes, signal: request.signal });
+			const output = await execFileAsync(request.file, [...request.arguments], { cwd: request.cwd, encoding: "utf8", shell: false, windowsHide: true, timeout: request.timeoutMs, maxBuffer: request.maxBufferBytes, signal: request.signal, env: gentleAiProcessEnvironment() });
 			return { stdout: output.stdout, stderr: output.stderr, exitCode: 0, signal: null, timedOut: false, outputLimitExceeded: false };
 		} catch (error) {
 			const detail = error as NodeJS.ErrnoException & { stdout?: string; stderr?: string; code?: string | number; signal?: NodeJS.Signals; killed?: boolean };
 			if (detail.code === "ENOENT" || detail.code === "EACCES" || detail.name === "AbortError") throw error;
-			return { stdout: detail.stdout ?? "", stderr: detail.stderr ?? "", exitCode: typeof detail.code === "number" ? detail.code : 1, signal: detail.signal ?? null, timedOut: detail.killed === true, outputLimitExceeded: detail.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" };
+			const outputLimitExceeded = detail.code === "ENOBUFS" || detail.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+			return { stdout: detail.stdout ?? "", stderr: detail.stderr ?? "", exitCode: typeof detail.code === "number" ? detail.code : 1, signal: detail.signal ?? null, timedOut: !outputLimitExceeded && detail.killed === true, outputLimitExceeded };
 		}
 	};
 }
@@ -748,6 +944,7 @@ function exactObject(value: unknown, required: readonly string[], optional: read
 }
 function requiredString(value: unknown): string { if (typeof value !== "string" || value.length === 0) throw new Error("expected string"); return value; }
 function stringValue(value: unknown): string { if (typeof value !== "string") throw new Error("expected string"); return value; }
+function sha256Identity(value: unknown): string { const parsed = requiredString(value); if (!/^sha256:[0-9a-f]{64}$/.test(parsed)) throw new Error("expected canonical SHA-256 identity"); return parsed; }
 function booleanValue(value: unknown): boolean { if (typeof value !== "boolean") throw new Error("expected boolean"); return value; }
 function nonNegativeInteger(value: unknown): number { if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error("expected safe non-negative integer"); return value; }
 function positiveInteger(value: unknown): number { if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new Error("expected safe positive integer"); return value; }
@@ -806,12 +1003,28 @@ function parseStructuredNativeDenial(stdout: string): NativeReviewStructuredDeni
 // Rebuild diagnostics from a duplicated module instance before facade output.
 export function sanitizeForeignNativeReviewDiagnostics(value: unknown): NativeReviewProcessDiagnostics | undefined {
 	try {
-		const raw = exactObject(value, ["operation", "error_code", "timed_out", "output_limit_exceeded"], ["exit_code", "signal", "stderr", "denial"]);
+		const raw = exactObject(value, ["operation", "error_code", "timed_out", "output_limit_exceeded"], ["exit_code", "signal", "max_buffer_bytes", "configuration_hint", "stderr", "denial"]);
 		const operation = enumString(raw.operation, Object.values(NATIVE_REVIEW_OPERATION)) as NativeReviewOperation;
 		const errorCode = enumString(raw.error_code, Object.values(NATIVE_REVIEW_ERROR_CODE)) as NativeReviewErrorCode;
 		const signal = raw.signal === undefined ? undefined : requiredString(raw.signal);
-		if (signal !== undefined && !/^SIG[A-Z0-9]{1,12}$/.test(signal)) return undefined;
-		return { operation, error_code: errorCode, ...(raw.exit_code === undefined ? {} : { exit_code: nonNegativeInteger(raw.exit_code) }), ...(signal === undefined ? {} : { signal: signal as NodeJS.Signals }), timed_out: booleanValue(raw.timed_out), output_limit_exceeded: booleanValue(raw.output_limit_exceeded), ...(raw.stderr === undefined ? {} : { stderr: sanitizeNativeDiagnosticText(stringValue(raw.stderr)) }), ...(raw.denial === undefined ? {} : { denial: sanitizeForeignStructuredDenial(raw.denial) }) };
+		const maxBufferBytes = raw.max_buffer_bytes === undefined ? undefined : positiveInteger(raw.max_buffer_bytes);
+		const configurationHint = raw.configuration_hint === undefined ? undefined : stringValue(raw.configuration_hint);
+		if (
+			(signal !== undefined && !/^SIG[A-Z0-9]{1,12}$/.test(signal)) ||
+			(maxBufferBytes === undefined) !== (configurationHint === undefined) ||
+			(configurationHint !== undefined && (errorCode !== NATIVE_REVIEW_ERROR_CODE.OUTPUT_LIMIT || configurationHint !== NATIVE_REVIEW_MAX_BUFFER_CONFIGURATION_HINT))
+		) return undefined;
+		return {
+			operation,
+			error_code: errorCode,
+			...(raw.exit_code === undefined ? {} : { exit_code: nonNegativeInteger(raw.exit_code) }),
+			...(signal === undefined ? {} : { signal: signal as NodeJS.Signals }),
+			timed_out: booleanValue(raw.timed_out),
+			output_limit_exceeded: booleanValue(raw.output_limit_exceeded),
+			...(maxBufferBytes === undefined ? {} : { max_buffer_bytes: maxBufferBytes, configuration_hint: configurationHint! }),
+			...(raw.stderr === undefined ? {} : { stderr: sanitizeNativeDiagnosticText(stringValue(raw.stderr)) }),
+			...(raw.denial === undefined ? {} : { denial: sanitizeForeignStructuredDenial(raw.denial) }),
+		};
 	} catch { return undefined; }
 }
 
@@ -827,14 +1040,18 @@ function sanitizeForeignStructuredDenial(value: unknown): NativeReviewStructured
 	return { schema: "gentle-ai.review-gate-result/v1", result, action, reason, ...(denial === undefined ? {} : { denial }) };
 }
 
-function nativeProcessDiagnostics(operation: NativeReviewOperation, code: NativeReviewErrorCode, result?: ExecFileResult): NativeReviewProcessDiagnostics {
+function nativeProcessDiagnostics(operation: NativeReviewOperation, code: NativeReviewErrorCode, result?: ExecFileResult, maxBufferBytes?: number): NativeReviewProcessDiagnostics {
+	const outputLimitExceeded = result?.outputLimitExceeded === true;
 	return {
 		operation,
 		error_code: code,
 		...(result === undefined ? {} : { exit_code: result.exitCode }),
 		...(result?.signal === null || result?.signal === undefined ? {} : { signal: result.signal }),
-		timed_out: result?.timedOut === true,
-		output_limit_exceeded: result?.outputLimitExceeded === true,
+		timed_out: !outputLimitExceeded && result?.timedOut === true,
+		output_limit_exceeded: outputLimitExceeded,
+		...(code === NATIVE_REVIEW_ERROR_CODE.OUTPUT_LIMIT && maxBufferBytes !== undefined
+			? { max_buffer_bytes: maxBufferBytes, configuration_hint: NATIVE_REVIEW_MAX_BUFFER_CONFIGURATION_HINT }
+			: {}),
 		...(result?.stderr.trim() ? { stderr: sanitizeNativeDiagnosticText(result.stderr) } : {}),
 		...(result === undefined ? {} : { denial: parseStructuredNativeDenial(result.stdout) }),
 	};
@@ -957,7 +1174,7 @@ function decodeNativeReviewRecovery(value: unknown): NativeReviewRecovery {
 	};
 }
 function decodeNativeReviewStatusEntry(value: unknown): NativeReviewAuthorityEntry {
-	const entry = exactObject(value, ["version", "path", "status", "problems"], ["lineage_id", "state", "revision", "chain_identity", "recovery"]);
+	const entry = exactObject(value, ["version", "path", "status", "problems"], ["lineage_id", "state", "revision", "snapshot_identity", "chain_identity", "recovery"]);
 	return {
 		version: enumString(entry.version, Object.values(NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION)) as NativeReviewAuthorityEntryVersion,
 		...(entry.lineage_id === undefined ? {} : { lineageId: requiredString(entry.lineage_id) }),
@@ -965,6 +1182,7 @@ function decodeNativeReviewStatusEntry(value: unknown): NativeReviewAuthorityEnt
 		status: enumString(entry.status, Object.values(NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS)) as NativeReviewAuthorityEntryStatus,
 		...(entry.state === undefined ? {} : { state: requiredString(entry.state) }),
 		...(entry.revision === undefined ? {} : { revision: requiredString(entry.revision) }),
+		...(entry.snapshot_identity === undefined ? {} : { snapshotIdentity: sha256Identity(entry.snapshot_identity) }),
 		...(entry.chain_identity === undefined ? {} : { chainIdentity: requiredString(entry.chain_identity) }),
 		...(entry.recovery === undefined ? {} : { recovery: decodeNativeReviewRecovery(entry.recovery) }),
 		problems: stringArray(entry.problems),
@@ -1151,8 +1369,8 @@ function hasValidLensesRequired(action: NativeStartAction, state: string, riskLe
 	return !lensesRequired;
 }
 
-function nativeError(code: NativeReviewErrorCode, operation: NativeReviewOperation, mutating: boolean, message: string, result?: ExecFileResult, launchAttempted = true, auditRecord?: Record<string, unknown>): NativeReviewCliError {
-	return new NativeReviewCliError(code, operation, launchAttempted, mutating, message, nativeProcessDiagnostics(operation, code, result), auditRecord);
+function nativeError(code: NativeReviewErrorCode, operation: NativeReviewOperation, mutating: boolean, message: string, result?: ExecFileResult, launchAttempted = true, auditRecord?: Record<string, unknown>, maxBufferBytes?: number): NativeReviewCliError {
+	return new NativeReviewCliError(code, operation, launchAttempted, mutating, message, nativeProcessDiagnostics(operation, code, result, maxBufferBytes), auditRecord);
 }
 
 interface NativeJsonExecution {
@@ -1167,7 +1385,7 @@ export class NativeReviewCliV214 {
 	private readonly timeoutMs: number;
 	private readonly maxBufferBytes: number;
 	private readonly cleanupDirectory: (directory: string) => Promise<void>;
-	constructor(adapter: ExecFileAdapter, executable: string | (() => string) = resolveGentleAiBinary, timeoutMs = 30_000, maxBufferBytes = 1024 * 1024, cleanupDirectory = (directory: string) => rm(directory, { recursive: true, force: true })) {
+	constructor(adapter: ExecFileAdapter, executable: string | (() => string) = resolveGentleAiBinary, timeoutMs = 30_000, maxBufferBytes = resolveNativeReviewMaxBufferBytes(), cleanupDirectory = (directory: string) => rm(directory, { recursive: true, force: true })) {
 		if (typeof executable === "string" && (!isAbsolute(executable) || executable === "gentle-ai")) throw new TypeError("Native review requires an absolute package-local executable");
 		this.adapter = adapter;
 		this.executable = executable;
@@ -1204,8 +1422,8 @@ export class NativeReviewCliV214 {
 			throw nativeError(NATIVE_REVIEW_ERROR_CODE.UNAVAILABLE, operation, mutating, "native process could not start");
 		}
 		const diagnostics = nativeProcessDiagnostics(operation, NATIVE_REVIEW_ERROR_CODE.NON_ZERO, result);
+		if (result.outputLimitExceeded) throw nativeError(NATIVE_REVIEW_ERROR_CODE.OUTPUT_LIMIT, operation, mutating, "native process output exceeded limit", result, true, undefined, this.maxBufferBytes);
 		if (result.timedOut) throw nativeError(NATIVE_REVIEW_ERROR_CODE.TIMEOUT, operation, mutating, "native process timed out", result);
-		if (result.outputLimitExceeded) throw nativeError(NATIVE_REVIEW_ERROR_CODE.OUTPUT_LIMIT, operation, mutating, "native process output exceeded limit", result);
 		if (result.signal) throw nativeError(NATIVE_REVIEW_ERROR_CODE.SIGNAL, operation, mutating, "native process was signalled", result);
 		const structuredValidateDenial = operation === NATIVE_REVIEW_OPERATION.VALIDATE && result.exitCode === 1;
 		const maintenancePartialFailure = [NATIVE_REVIEW_OPERATION.ABANDON, NATIVE_REVIEW_OPERATION.QUARANTINE_LEGACY, NATIVE_REVIEW_OPERATION.RECONCILE_AUTHORITY, NATIVE_REVIEW_OPERATION.REPAIR_LEGACY_ALIAS].includes(operation) && result.exitCode !== 0;
@@ -1223,12 +1441,18 @@ export class NativeReviewCliV214 {
 			if (error instanceof Error && error.name === "AbortError") throw nativeError(NATIVE_REVIEW_ERROR_CODE.CANCELLED, NATIVE_REVIEW_OPERATION.VERSION, false, "version process was cancelled");
 			throw nativeError(NATIVE_REVIEW_ERROR_CODE.UNAVAILABLE, NATIVE_REVIEW_OPERATION.VERSION, false, "gentle-ai is unavailable");
 		}
+		if (result.outputLimitExceeded) throw nativeError(NATIVE_REVIEW_ERROR_CODE.OUTPUT_LIMIT, NATIVE_REVIEW_OPERATION.VERSION, false, "version process output exceeded limit", result, true, undefined, this.maxBufferBytes);
 		if (result.timedOut) throw nativeError(NATIVE_REVIEW_ERROR_CODE.TIMEOUT, NATIVE_REVIEW_OPERATION.VERSION, false, "version process timed out", result);
-		if (result.outputLimitExceeded) throw nativeError(NATIVE_REVIEW_ERROR_CODE.OUTPUT_LIMIT, NATIVE_REVIEW_OPERATION.VERSION, false, "version process output exceeded limit", result);
 		if (result.signal) throw nativeError(NATIVE_REVIEW_ERROR_CODE.SIGNAL, NATIVE_REVIEW_OPERATION.VERSION, false, "version process was signalled", result);
 		if (result.exitCode !== 0) throw nativeError(NATIVE_REVIEW_ERROR_CODE.NON_ZERO, NATIVE_REVIEW_OPERATION.VERSION, false, "version process failed", result);
-		const version = /^gentle-ai ([0-9]+\.[0-9]+\.[0-9]+)\n$/.exec(result.stdout.replace(/\r\n$/, "\n"))?.[1];
-		const contract = version === undefined ? undefined : resolvedNativeCliContract(version);
+		const normalized = result.stdout.replace(/\r\n$/, "\n");
+		const pinnedVersion = /^gentle-ai ([0-9]+\.[0-9]+\.[0-9]+)\n$/.exec(normalized)?.[1];
+		// Dev-binary override (unpinned field-test mode): accept the binary's
+		// reported version even when it is not a pinned three-part release
+		// version (a main-line dev build reports e.g. "2.4.0-rc.8+fix...").
+		// The banner shape itself stays strict. Pinned mode is byte-identical.
+		const version = pinnedVersion ?? (gentleAiDevBinaryOverrideConfigured() ? /^gentle-ai (\S+)\n$/.exec(normalized)?.[1] : undefined);
+		const contract = version === undefined ? undefined : effectiveNativeCliContract(version);
 		if (result.stderr.trim().length > 0 || contract === undefined || capabilities.some((capability) => !contract[capability])) throw nativeError(NATIVE_REVIEW_ERROR_CODE.VERSION_INCOMPATIBLE, NATIVE_REVIEW_OPERATION.VERSION, false, `native gentle-ai lacks required capabilities: expected v${GENTLE_AI_VERSION}, found v${version ?? "unparseable"}`);
 		return version as keyof typeof NATIVE_CLI_CONTRACTS;
 	}
@@ -1239,7 +1463,7 @@ export class NativeReviewCliV214 {
 		if (request.baseRef !== undefined && request.committedOnly !== true) throw new TypeError("Native START baseRef requires explicit committedOnly acknowledgement");
 		if (request.baseRef === undefined && request.committedOnly !== undefined) throw new TypeError("Native START committedOnly requires an explicit baseRef");
 		const version = await this.verifyVersion(request.cwd, request.signal, ["start"]);
-		const toleratedStderr = resolvedNativeCliContract(version)?.mode === true ? REVIEW_CONSENT_NOTICES : [];
+		const toleratedStderr = effectiveNativeCliContract(version)?.mode === true ? REVIEW_CONSENT_NOTICES : [];
 		const { body: result } = await this.execute(NATIVE_REVIEW_OPERATION.START, request.cwd, ["review", "start", "--cwd", request.cwd, ...(request.baseRef === undefined ? [] : ["--base-ref", request.baseRef, "--committed-only"]), ...(request.lineageId ? ["--lineage", request.lineageId] : []), ...(request.policyPath ? ["--policy", request.policyPath] : []), ...(request.focus ? ["--focus", request.focus] : [])], true, request.signal, toleratedStderr);
 		return decode(NATIVE_REVIEW_OPERATION.START, true, () => {
 			// `target_identity` and `lens_bindings` are real, unconditionally-present
@@ -1497,7 +1721,11 @@ export class NativeReviewCliV214 {
 		for (const [name, value] of [["lineage", request.lineage], ["expectedRevision", request.expectedRevision], ["snapshotIdentity", request.snapshotIdentity], ["actor", request.actor], ["reason", request.reason]] as const) {
 			if (!isCanonicalProcessString(value)) throw new TypeError(`Native ABANDON ${name} must be a non-empty, trimmed, NUL-free string`);
 		}
-		if (request.maintainerAuthorization !== nativeReviewAbandonAuthorization(request)) throw new TypeError("Native ABANDON maintainerAuthorization must match the exact lineage, revision, snapshot, actor, and reason binding");
+		if (!Array.isArray(request.capturedLensResults) || request.capturedLensResults.some((entry) => !isCanonicalProcessString(entry))) throw new TypeError("Native ABANDON capturedLensResults must be an array of non-empty, trimmed, NUL-free strings");
+		for (const [name, value] of [["findingsPresent", request.findingsPresent], ["evidenceRecordsPresent", request.evidenceRecordsPresent]] as const) {
+			if (typeof value !== "boolean") throw new TypeError(`Native ABANDON ${name} must be a boolean`);
+		}
+		if (request.maintainerAuthorization !== nativeReviewAbandonAuthorization(request)) throw new TypeError("Native ABANDON maintainerAuthorization must match the exact lineage, revision, snapshot, reason, discarded-work, and actor binding");
 		await this.verifyVersion(request.cwd, request.signal, ["abandon"]);
 		const execution = await this.execute(NATIVE_REVIEW_OPERATION.ABANDON, request.cwd, [
 			"review", "abandon", "--cwd", request.cwd,
@@ -1591,14 +1819,17 @@ export class NativeReviewCliV214 {
 	}
 }
 
-export function nativeReviewAbandonAuthorization(request: Pick<NativeReviewAbandonRequest, "lineage" | "expectedRevision" | "snapshotIdentity" | "actor" | "reason">): string {
+export function nativeReviewAbandonAuthorization(request: Pick<NativeReviewAbandonRequest, "lineage" | "expectedRevision" | "snapshotIdentity" | "capturedLensResults" | "findingsPresent" | "evidenceRecordsPresent" | "actor" | "reason">): string {
 	return [
-		"gentle-ai.review-abandon-authorization/v1",
+		"gentle-ai.review-abandon-authorization/v2",
 		`lineage=${request.lineage}`,
 		`revision=${request.expectedRevision}`,
 		`snapshot_identity=${request.snapshotIdentity}`,
-		`actor=${request.actor}`,
 		`reason=${request.reason}`,
+		`captured_lens_results=${request.capturedLensResults.join(",")}`,
+		`findings_present=${request.findingsPresent}`,
+		`evidence_records_present=${request.evidenceRecordsPresent}`,
+		`actor=${request.actor.trim()}`,
 	].join("\n");
 }
 
@@ -1615,6 +1846,32 @@ export function nativeReviewLegacyQuarantineAuthorization(request: Pick<NativeRe
 	].join("\n");
 }
 
+/**
+ * The exact native `gentle-ai.review-recovery-authorization/v1` binding for one
+ * recovery edge.
+ *
+ * Native `review recover` accepts a caller-supplied authorization only when it
+ * reproduces this binding byte for byte, because it is copied verbatim into the
+ * recovery provenance and read afterwards as a maintainer attestation. Pi
+ * therefore derives it from freshly read native target status and never
+ * forwards a caller-supplied one: a wrong binding is worse than an absent one,
+ * since an absent field cannot lie about who approved what.
+ *
+ * `targetIdentity` is the live target identity the provider itself publishes in
+ * the `review.recover` eligibility binding (`status.target_identity`), which is
+ * the identity the successor's initial snapshot takes.
+ */
+export function nativeReviewRecoverAuthorization(request: Pick<NativeReviewRecoverRequest, "predecessorLineage" | "expectedPredecessorRevision" | "actor" | "reason"> & { targetIdentity: string }): string {
+	return [
+		"gentle-ai.review-recovery-authorization/v1",
+		`predecessor_lineage=${request.predecessorLineage}`,
+		`predecessor_revision=${request.expectedPredecessorRevision}`,
+		`target_identity=${request.targetIdentity}`,
+		`actor=${request.actor.trim()}`,
+		`reason=${request.reason.trim()}`,
+	].join("\n");
+}
+
 export function nativeReviewReconcileAuthorization(request: Pick<NativeReviewReconcileAuthorityRequest, "predecessorLineage" | "expectedPredecessorRevision" | "successorLineage" | "expectedSuccessorRevision" | "actor" | "reason" | "anomalies">): string {
 	return [
 		"gentle-ai.review-reconcile-authorization/v1",
@@ -1655,15 +1912,16 @@ export class NativeReviewIntegrationError extends Error {
 	}
 }
 
-// Raised when negotiated START answers `consent/v2` (action:
+// Raised when negotiated START answers a consent question (`consent/v2` from
+// the pinned line, `consent/v3` from gentle-ai >= 2.3.0; action:
 // "consent_required") instead of `start/v3`. The provider has frozen no
 // authority yet: Pi must relay this complete candidate-scoped question and may
 // answer only through one of the exact invocations carried by the envelope.
 export class NativeReviewConsentRequiredError extends Error {
-	readonly consent: ReviewConsentV2;
+	readonly consent: ReviewConsentEnvelope;
 	readonly launchAttempted = true;
 	readonly mutationOutcome = "none";
-	constructor(consent: ReviewConsentV2) {
+	constructor(consent: ReviewConsentEnvelope) {
 		super(consent.headline);
 		this.name = "NativeReviewConsentRequiredError";
 		this.consent = consent;
@@ -1747,7 +2005,30 @@ function exactConsentOption(arguments_: readonly string[], name: string): string
 	return values[0]!;
 }
 
-function consentInvocationArguments(request: NativeReviewConsentAnswerRequest): readonly string[] {
+function optionalConsentLineageOption(arguments_: readonly string[]): string | undefined {
+	const values: string[] = [];
+	for (let index = 0; index < arguments_.length; index += 1) {
+		const token = arguments_[index]!;
+		if (token === "--lineage") {
+			const value = arguments_[index + 1];
+			if (value === undefined || value.startsWith("--")) throw new NativeReviewConsentBindingError("consent-invocation-option-invalid", "Native consent invocation --lineage is missing its value");
+			values.push(value);
+			index += 1;
+		} else if (token.startsWith("--lineage=")) values.push(token.slice("--lineage=".length));
+	}
+	if (values.length > 1) throw new NativeReviewConsentBindingError("consent-invocation-option-invalid", "Native consent invocation permits at most one --lineage");
+	if (values.length === 0) return undefined;
+	const lineageId = values[0]!;
+	if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(lineageId)) throw new NativeReviewConsentBindingError("consent-invocation-option-invalid", "Native consent invocation --lineage is malformed");
+	return lineageId;
+}
+
+interface ConsentInvocation {
+	arguments_: readonly string[];
+	lineageId?: string;
+}
+
+function consentInvocationArguments(request: NativeReviewConsentAnswerRequest): ConsentInvocation {
 	const choice = request.consent.choices.find((candidate) => candidate.answer === request.answer);
 	if (choice === undefined) throw new NativeReviewConsentBindingError("consent-answer-unknown", "Native consent answer must be granted or declined");
 	const words = splitNativeConsentInvocation(choice.invocation);
@@ -1757,8 +2038,9 @@ function consentInvocationArguments(request: NativeReviewConsentAnswerRequest):
 	if (exactConsentOption(arguments_, "--cwd") !== request.cwd) throw new NativeReviewConsentBindingError("consent-invocation-cwd-changed", "Native consent invocation repository binding changed");
 	if (exactConsentOption(arguments_, "--target") !== request.consent.targetIdentity) throw new NativeReviewConsentBindingError("consent-invocation-target-changed", "Native consent invocation target binding changed");
 	if (exactConsentOption(arguments_, "--projection") !== request.consent.projection) throw new NativeReviewConsentBindingError("consent-invocation-projection-changed", "Native consent invocation projection binding changed");
+	const lineageId = optionalConsentLineageOption(arguments_);
 	if (exactConsentOption(arguments_, "--consent") !== request.answer || arguments_.at(-1) !== request.answer) throw new NativeReviewConsentBindingError("consent-invocation-answer-changed", "Native consent invocation answer binding changed");
-	return arguments_;
+	return { arguments_, ...(lineageId === undefined ? {} : { lineageId }) };
 }
 
 function decodeDeclinedConsentStart(value: unknown, expected: NativeReviewConsentAnswerRequest): NativeReviewConsentDeclinedResult {
@@ -1807,27 +2089,46 @@ interface NegotiatedExecution {
 }
 
 function decodeNativeAdmittedResultManifest(value: unknown): NativeReviewAdmittedResultManifest {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError("native capture-result manifest must be an object");
+	// The admission answer routes through the exact-identity forward decoder
+	// (decoder-freshness discipline): the complete live envelope — identity
+	// constants, binding fields, and the exactly-one-locator rule — is
+	// validated before anything is handed to FINALIZE, and an unknown field
+	// grown by gentle-ai main is rejected instead of silently dropped.
+	const artifact = decodeReviewResultArtifactV2(value);
+	return Object.freeze({
+		schema: artifact.schema,
+		subjectHash: artifact.subjectHash,
+		admissionDecision: artifact.admissionDecision,
+		lens: artifact.lens,
+		...(artifact.path === undefined ? {} : { path: artifact.path }),
+		...(artifact.reference === undefined ? {} : { reference: artifact.reference }),
+	});
+}
+
+// gentle-pi#311 P4-roles: the strict acknowledgement for one executed
+// provider role vector. The immutable verdict bytes live in the Go-owned
+// compact store slot; this envelope only names the binding the capture
+// proved, so anything beyond that exact shape is refused.
+function decodeNativeProviderRoleCaptureArtifact(value: unknown): NativeReviewProviderRoleCaptureArtifact {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError("native provider role capture artifact must be an object");
 	const body = value as Record<string, unknown>;
+	const allowed = new Set(["schema", "lineage_id", "target_identity", "role", "captured"]);
+	for (const key of Object.keys(body)) if (!allowed.has(key)) throw new TypeError(`native provider role capture artifact carries unexpected key ${key}`);
 	const text = (key: string): string => {
 		const found = body[key];
-		if (typeof found !== "string" || found.trim() !== found || found.length === 0) throw new TypeError(`native capture-result manifest ${key} must be a non-empty trimmed string`);
+		if (typeof found !== "string" || found.trim() !== found || found.length === 0) throw new TypeError(`native provider role capture artifact ${key} must be a non-empty trimmed string`);
 		return found;
 	};
-	const schema = text("schema");
-	if (schema !== "gentle-ai.review-result-artifact/v2") throw new TypeError(`native capture-result manifest schema must be gentle-ai.review-result-artifact/v2, received ${schema}`);
-	const admission = text("admission_decision");
-	if (admission !== "completed") throw new TypeError(`native capture-result manifest admission_decision must be completed, received ${admission}`);
-	// Exactly one locator: a provider-owned path OR an opaque reference. Both or
-	// neither means the manifest cannot be handed to FINALIZE.
-	const hasPath = body.path !== undefined, hasReference = body.reference !== undefined;
-	if (hasPath === hasReference) throw new TypeError("native capture-result manifest must carry exactly one of path or reference");
+	if (text("schema") !== NATIVE_REVIEW_PROVIDER_ROLE_CAPTURE_SCHEMA) throw new TypeError(`native provider role capture artifact schema must be ${NATIVE_REVIEW_PROVIDER_ROLE_CAPTURE_SCHEMA}`);
+	const role = text("role");
+	if (role !== "refuter" && role !== "targeted-validator") throw new TypeError(`native provider role capture artifact role must be refuter or targeted-validator, received ${role}`);
+	if (body.captured !== true) throw new TypeError("native provider role capture artifact must report captured: true");
 	return Object.freeze({
-		schema,
-		subjectHash: text("subject_hash"),
-		admissionDecision: admission,
-		...(body.lens === undefined ? {} : { lens: text("lens") }),
-		...(hasPath ? { path: text("path") } : { reference: text("reference") }),
+		schema: NATIVE_REVIEW_PROVIDER_ROLE_CAPTURE_SCHEMA,
+		lineageId: text("lineage_id"),
+		targetIdentity: text("target_identity"),
+		role,
+		captured: true,
 	});
 }
 
@@ -1843,7 +2144,7 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 		adapter: ExecFileAdapter,
 		executable: string | (() => string) = resolveGentleAiBinary,
 		timeoutMs = 30_000,
-		maxBufferBytes = 1024 * 1024,
+		maxBufferBytes = resolveNativeReviewMaxBufferBytes(),
 		cleanupDirectory: (directory: string) => Promise<void> = (directory) => rm(directory, { recursive: true, force: true }),
 		executableDigest: NativeExecutableDigestResolver = defaultExecutableDigest,
 	) {
@@ -1893,8 +2194,8 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 			if (error instanceof Error && error.name === "AbortError") throw nativeError(NATIVE_REVIEW_ERROR_CODE.CANCELLED, operation, mutating, "native process was cancelled");
 			throw nativeError(NATIVE_REVIEW_ERROR_CODE.UNAVAILABLE, operation, mutating, "native process could not start");
 		}
+		if (result.outputLimitExceeded) throw nativeError(NATIVE_REVIEW_ERROR_CODE.OUTPUT_LIMIT, operation, mutating, "native process output exceeded limit", result, true, undefined, this.maxBufferBytes);
 		if (result.timedOut) throw nativeError(NATIVE_REVIEW_ERROR_CODE.TIMEOUT, operation, mutating, "native process timed out", result);
-		if (result.outputLimitExceeded) throw nativeError(NATIVE_REVIEW_ERROR_CODE.OUTPUT_LIMIT, operation, mutating, "native process output exceeded limit", result);
 		if (result.signal) throw nativeError(NATIVE_REVIEW_ERROR_CODE.SIGNAL, operation, mutating, "native process was signalled", result);
 		const diagnostics = nativeProcessDiagnostics(operation, NATIVE_REVIEW_ERROR_CODE.NON_ZERO, result);
 		const body = parseJson(result.stdout, operation, mutating, diagnostics);
@@ -1906,7 +2207,8 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 				throw nativeError(NATIVE_REVIEW_ERROR_CODE.NON_ZERO, operation, mutating, "native negotiated operation failed without a valid failure envelope", result);
 			}
 		}
-		if (result.stderr.trim().length > 0 && !stderrIsTolerated(result.stderr, toleratedStderr)) throw nativeError(NATIVE_REVIEW_ERROR_CODE.UNEXPECTED_STDERR, operation, mutating, "native process wrote stderr", result);
+		const forecastNarrationTolerated = operation === NATIVE_REVIEW_OPERATION.STATUS && gentleAiDevBinaryOverrideConfigured() && stderrIsForecastNarration(result.stderr);
+		if (result.stderr.trim().length > 0 && !stderrIsTolerated(result.stderr, toleratedStderr) && !forecastNarrationTolerated) throw nativeError(NATIVE_REVIEW_ERROR_CODE.UNEXPECTED_STDERR, operation, mutating, "native process wrote stderr", result);
 		return { body, exitCode: result.exitCode };
 	}
 
@@ -1935,7 +2237,12 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 				if (error instanceof NativeReviewCliError) throw error;
 				throw nativeError(NATIVE_REVIEW_ERROR_CODE.SCHEMA_INCOMPATIBLE, NATIVE_REVIEW_OPERATION.VERSION, false, `expected gentle-ai v${GENTLE_AI_VERSION}; the installed runtime is incompatible — reinstall gentle-pi`);
 			}
-			if (capabilities.packageVersion !== GENTLE_AI_VERSION) {
+			// Dev-binary override (unpinned field-test mode): the session accepts
+			// the binary's self-reported package version instead of the exact pin.
+			// The full capabilities decode above still applies unchanged, so an
+			// incompatible envelope is refused either way. Pinned mode keeps the
+			// exact equality byte-identical.
+			if (capabilities.packageVersion !== GENTLE_AI_VERSION && !gentleAiDevBinaryOverrideConfigured()) {
 				throw nativeError(NATIVE_REVIEW_ERROR_CODE.VERSION_INCOMPATIBLE, NATIVE_REVIEW_OPERATION.VERSION, false, `expected gentle-ai v${GENTLE_AI_VERSION}, provider reported v${capabilities.packageVersion}`);
 			}
 			return capabilities;
@@ -1991,12 +2298,20 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 			...(request.focus === undefined ? [] : ["--focus", request.focus]),
 			"--consent", "relay",
 		], true, request.signal);
-		// A negotiated v2 START may answer `consent/v2` (action:
+		// A negotiated v2 START may answer a consent question (action:
 		// "consent_required") instead of `start/v3` when the provider needs an
 		// explicit answer it cannot infer. Discriminate before decode and surface
-		// the complete envelope; only the caller can map a human answer.
+		// the complete envelope; only the caller can map a human answer. The
+		// body's own schema string selects the identity-exact decoder: the
+		// pinned 2.2.x line emits consent/v2, gentle-ai >= 2.3.0 (capabilities
+		// v2.1+) emits consent/v3, and any other identity fails closed inside
+		// the v3 decoder's exact identity gate.
 		if (execution.body.action === "consent_required") {
-			const consent = decode(NATIVE_REVIEW_OPERATION.START, true, () => decodeReviewConsentV2(execution.body));
+			const consent = decode(NATIVE_REVIEW_OPERATION.START, true, () => (
+				execution.body.schema === "gentle-ai.review-integration.consent/v2"
+					? decodeReviewConsentV2(execution.body)
+					: decodeReviewConsentV3(execution.body)
+			));
 			if (consent.targetIdentity !== targetIdentity || consent.projection !== projection) throw nativeError(NATIVE_REVIEW_ERROR_CODE.IDENTITY_MISMATCH, NATIVE_REVIEW_OPERATION.START, true, "native consent target binding mismatch");
 			throw new NativeReviewConsentRequiredError(consent);
 		}
@@ -2033,16 +2348,15 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 	}
 
 	async answerConsent(request: NativeReviewConsentAnswerRequest): Promise<NativeReviewConsentAnswerResult> {
-		const arguments_ = consentInvocationArguments(request);
-		const execution = await this.negotiated(NATIVE_REVIEW_OPERATION.START, request.cwd, arguments_, true, request.signal);
+		const invocation = consentInvocationArguments(request);
+		const execution = await this.negotiated(NATIVE_REVIEW_OPERATION.START, request.cwd, invocation.arguments_, true, request.signal);
 		if (request.answer === NATIVE_REVIEW_CONSENT_ANSWER.DECLINED) {
 			return decode(NATIVE_REVIEW_OPERATION.START, true, () => decodeDeclinedConsentStart(execution.body, request));
 		}
 		const result = decode(NATIVE_REVIEW_OPERATION.START, true, () => decodeReviewStartV3(execution.body));
 		const answeredTarget = result.targetIdentity ?? result.repositoryContext?.targetIdentity;
 		if (answeredTarget !== request.consent.targetIdentity) throw nativeError(NATIVE_REVIEW_ERROR_CODE.IDENTITY_MISMATCH, NATIVE_REVIEW_OPERATION.START, true, "native consent answer target mismatch");
-		const lineageId = exactConsentOption(arguments_, "--lineage");
-		if (result.lineageId !== lineageId) throw nativeError(NATIVE_REVIEW_ERROR_CODE.IDENTITY_MISMATCH, NATIVE_REVIEW_OPERATION.START, true, "native consent answer lineage mismatch");
+		if (invocation.lineageId !== undefined && result.lineageId !== invocation.lineageId) throw nativeError(NATIVE_REVIEW_ERROR_CODE.IDENTITY_MISMATCH, NATIVE_REVIEW_OPERATION.START, true, "native consent answer lineage mismatch");
 		return { kind: "started", start: {
 			lineageId: result.lineageId,
 			state: result.state as NativeStartResult["state"],
@@ -2173,6 +2487,7 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 			"--projection", request.projection ?? "workspace",
 			...(request.baseRef === undefined ? [] : ["--base-ref", request.baseRef]),
 			...(request.lineageId === undefined ? [] : ["--lineage", request.lineageId]),
+			...(request.agent === undefined ? [] : ["--agent", request.agent]),
 			"--next-transition",
 		], false, request.signal);
 		assertSupportedNextTransitionOperation(execution.body);
@@ -2239,6 +2554,118 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 		}
 	}
 
+	// gentle-pi#311 P4-roles: executes one provider-rendered self-contained
+	// role capture vector exactly as rendered — one CLI invocation, verbatim
+	// tokens in provider order, in the foreground. Go materializes the role
+	// prompt, spawns its own locked-down pi subprocess, and admits the raw
+	// verdict; Pi never adds, removes, or reorders a single token (not even
+	// --cwd: the vector's --repository-context is authoritative and mutually
+	// exclusive with a path). The central adapter injects the relay handshake
+	// environment on this spawn like on every other gentle-ai invocation.
+	async captureProviderRole(request: NativeReviewProviderRoleCaptureRequest): Promise<NativeReviewProviderRoleCaptureArtifact> {
+		const verb = request.captureOperation.startsWith("review.") ? request.captureOperation.slice("review.".length) : "";
+		if (verb !== "capture-refuter" && verb !== "capture-validation") throw new TypeError(`Native CAPTURE_PROVIDER_ROLE supports only review.capture-refuter and review.capture-validation, received ${JSON.stringify(request.captureOperation)}`);
+		if (request.argumentTokens.length === 0) throw new TypeError("Native CAPTURE_PROVIDER_ROLE requires the provider-rendered argument tokens");
+		if (request.argumentTokens.some((token) => typeof token !== "string" || token.length === 0)) throw new TypeError("Native CAPTURE_PROVIDER_ROLE argument tokens must all be non-empty strings");
+		const executable = this.verifiedExecutable(NATIVE_REVIEW_OPERATION.CAPTURE_PROVIDER_ROLE, true);
+		const execution = await this.invoke(NATIVE_REVIEW_OPERATION.CAPTURE_PROVIDER_ROLE, request.cwd, [
+			"review", verb,
+			...request.argumentTokens,
+		], true, request.signal, executable.path);
+		return decode(NATIVE_REVIEW_OPERATION.CAPTURE_PROVIDER_ROLE, true, () => decodeNativeProviderRoleCaptureArtifact(execution.body));
+	}
+
+	// gentle-pi#311 P5: executes one provider-rendered `review.finalize`
+	// execute transition exactly as rendered. The tokens come verbatim from
+	// the negotiated next_transition (e.g. `--lineage=<id>
+	// --captured-results=true`); Pi assembles no reviewer, refuter, or
+	// validator documents for this lane — the provider discovers its own
+	// admitted role and lens slots.
+	async finalizeTransition(request: NativeReviewFinalizeTransitionRequest): Promise<NativeFinalizeResult> {
+		if (request.argumentTokens.length === 0) throw new TypeError("Native FINALIZE transition requires the provider-rendered argument tokens");
+		if (request.argumentTokens.some((token) => typeof token !== "string" || token.length === 0)) throw new TypeError("Native FINALIZE transition argument tokens must all be non-empty strings");
+		const execution = await this.negotiated(NATIVE_REVIEW_OPERATION.FINALIZE, request.cwd, [
+			"review", "finalize",
+			...request.argumentTokens,
+		], true, request.signal);
+		return this.decodeFinalizeTransitionExecution(execution);
+	}
+
+	// Same misbinding class as capture-evidence (live smoke, 2026-08-16): the
+	// correction PLAN and TARGETED VALIDATION collect slots render `finalize`
+	// submission descriptors whose tokens are self-contained (--contract,
+	// --lineage, --expected-revision, --target, --request-hash,
+	// --repository-context) plus exactly one {{value}} slot. Executing anything
+	// other than those rendered tokens fails the live emitter's committed-
+	// intent reconciliation, so the tokens pass through verbatim with only the
+	// {{value}} substitution: a literal for correction_lines, a staged 0o600
+	// artifact path for a validation document.
+	async finalizeSubmission(request: NativeReviewFinalizeSubmissionRequest): Promise<NativeFinalizeResult> {
+		if (request.argumentTokens.length === 0) throw new TypeError("Native FINALIZE submission requires the provider-rendered argument tokens");
+		if (request.argumentTokens.some((token) => typeof token !== "string" || token.length === 0)) throw new TypeError("Native FINALIZE submission argument tokens must all be non-empty strings");
+		if ((request.valueLiteral === undefined) === (request.valueDocument === undefined)) throw new TypeError("Native FINALIZE submission takes exactly one of valueLiteral or valueDocument");
+		const valueToken = request.argumentTokens[request.valueSubstitutionLocation];
+		if (valueToken === undefined || !valueToken.includes("{{value}}")) throw new TypeError("Native FINALIZE submission must render exactly one {{value}} slot token");
+		if (request.valueDocument !== undefined && request.valueDocument.length === 0) throw new TypeError("Native FINALIZE submission value document must contain at least one byte");
+		const directory = request.valueDocument === undefined ? undefined : await mkdtemp(join(tmpdir(), "gentle-ai-finalize-submission-"));
+		try {
+			let substituted: string;
+			if (directory !== undefined) {
+				await chmod(directory, 0o700);
+				const valueFile = join(directory, "value.json");
+				await writeFile(valueFile, request.valueDocument!, { encoding: "utf8", mode: 0o600 });
+				await chmod(valueFile, 0o600);
+				substituted = valueFile;
+			} else {
+				substituted = request.valueLiteral!;
+			}
+			const resolved = request.argumentTokens.map((token, index) => index === request.valueSubstitutionLocation ? token.replaceAll("{{value}}", substituted) : token);
+			const execution = await this.negotiated(NATIVE_REVIEW_OPERATION.FINALIZE, request.cwd, [
+				"review", "finalize",
+				...resolved,
+			], true, request.signal);
+			return this.decodeFinalizeTransitionExecution(execution);
+		} finally {
+			if (directory !== undefined) await this.cleanupDirectory(directory).catch(() => undefined);
+		}
+	}
+
+	private decodeFinalizeTransitionExecution(execution: { body: unknown }): NativeFinalizeResult {
+		return decode(NATIVE_REVIEW_OPERATION.FINALIZE, true, () => {
+			const body = object(execution.body);
+			// A transition rendered with `--contract` answers with the negotiated
+			// operation envelope; one rendered without (the pi runtime form)
+			// answers with the plain `review/finalize` shape. Both are decoded
+			// strictly; nothing else is accepted.
+			if (typeof body.schema === "string") {
+				const envelope = decodeReviewOperationV2(body);
+				if (envelope.operation !== "review.finalize") throw new Error("wrong finalize operation envelope");
+				const result = envelope.result;
+				return {
+					lineageId: requiredString(result.lineage_id),
+					state: requiredString(result.state),
+					action: requiredString(result.action),
+					storeRevision: requiredString(result.store_revision),
+					...(result.validation_request === undefined ? {} : { validationRequest: result.validation_request as Readonly<Record<string, unknown>> }),
+					...(result.escalation === undefined ? {} : { escalation: requiredString(result.escalation) }),
+				};
+			}
+			const plain = exactObject(body, ["operation", "lineage_id", "state", "action", "store_revision"], ["receipt_path", "validation_request", "escalation"]);
+			if (plain.operation !== "review/finalize") throw new Error("wrong finalize discriminator");
+			const state = requiredString(plain.state);
+			if (!(NATIVE_FINALIZE_STATE as readonly string[]).includes(state)) throw new Error("unknown finalize state");
+			return {
+				lineageId: requiredString(plain.lineage_id),
+				state,
+				action: requiredString(plain.action),
+				storeRevision: requiredString(plain.store_revision),
+				...(plain.receipt_path === undefined ? {} : { receiptPath: requiredString(plain.receipt_path) }),
+				...(plain.validation_request === undefined ? {} : { validationRequest: plain.validation_request as Readonly<Record<string, unknown>> }),
+				...(plain.escalation === undefined ? {} : { escalation: requiredString(plain.escalation) }),
+			};
+		});
+	}
+
 	async captureEvidence(request: NativeReviewCaptureEvidenceRequest): Promise<NativeReviewVerificationEvidenceV2> {
 		if (!(NATIVE_REVIEW_CAPTURE_OUTCOME as readonly string[]).includes(request.outcome)) throw new TypeError("Native CAPTURE_EVIDENCE outcome must be passed, verification_failed, or procedural_tooling_failed");
 		if (request.evidenceDocument.length === 0) throw new TypeError("Native CAPTURE_EVIDENCE evidence must contain at least one byte");
@@ -2260,6 +2687,45 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 		}
 	}
 
+	// Field defect (fambig, 2026-08-16): at every evidence-pending sub-state
+	// the collect slot renders the identity native demands — for a correction
+	// that is the fix-diff `--target`, not the live workspace snapshot — so the
+	// slot's rendered submission tokens execute verbatim, with only the
+	// {{outcome}} and {{input}} slots substituted. Same verbatim-token
+	// discipline as captureResult; --repository-context is authoritative and
+	// mutually exclusive with a path.
+	async captureEvidenceSubmission(request: NativeReviewCaptureEvidenceSubmissionRequest): Promise<NativeReviewVerificationEvidenceV2> {
+		if (!(NATIVE_REVIEW_CAPTURE_OUTCOME as readonly string[]).includes(request.outcome)) throw new TypeError("Native CAPTURE_EVIDENCE outcome must be passed, verification_failed, or procedural_tooling_failed");
+		if (request.evidenceDocument.length === 0) throw new TypeError("Native CAPTURE_EVIDENCE evidence must contain at least one byte");
+		if (request.argumentTokens.length === 0) throw new TypeError("Native CAPTURE_EVIDENCE submission requires the provider-rendered argument tokens");
+		if (request.argumentTokens.some((token) => typeof token !== "string" || token.length === 0)) throw new TypeError("Native CAPTURE_EVIDENCE submission argument tokens must all be non-empty strings");
+		const outcomeToken = request.argumentTokens[request.outcomeSubstitutionLocation];
+		const inputToken = request.argumentTokens[request.inputSubstitutionLocation];
+		if (request.outcomeSubstitutionLocation === request.inputSubstitutionLocation || outcomeToken === undefined || !outcomeToken.includes("{{outcome}}")) throw new TypeError("Native CAPTURE_EVIDENCE submission must render exactly one {{outcome}} slot token");
+		if (inputToken === undefined || !inputToken.includes("{{input}}")) throw new TypeError("Native CAPTURE_EVIDENCE submission must render exactly one {{input}} slot token");
+		const carriesContext = request.argumentTokens.some((token) => token === "--repository-context" || token.startsWith("--repository-context="));
+		if (carriesContext && request.cwd !== undefined) throw new TypeError("Native CAPTURE_EVIDENCE submission takes a repository context or --cwd, never both");
+		const directory = await mkdtemp(join(tmpdir(), "gentle-ai-capture-evidence-"));
+		try {
+			await chmod(directory, 0o700);
+			const evidenceFile = await this.stageEvidence(directory, request.evidenceDocument);
+			const resolved = request.argumentTokens.map((token, index) =>
+				index === request.outcomeSubstitutionLocation
+					? token.replaceAll("{{outcome}}", request.outcome)
+					: index === request.inputSubstitutionLocation
+						? token.replaceAll("{{input}}", evidenceFile)
+						: token);
+			const execution = await this.negotiated(NATIVE_REVIEW_OPERATION.CAPTURE_EVIDENCE, request.cwd ?? process.cwd(), [
+				"review", "capture-evidence",
+				...resolved,
+				...(carriesContext || request.cwd === undefined ? [] : ["--cwd", request.cwd]),
+			], true, request.signal);
+			return decode(NATIVE_REVIEW_OPERATION.CAPTURE_EVIDENCE, true, () => decodeNativeReviewVerificationEvidence(execution.body));
+		} finally {
+			await this.cleanupDirectory(directory).catch(() => undefined);
+		}
+	}
+
 	reviewStatus(request: NativeReviewStatusRequest): Promise<NativeReviewStatusResult> {
 		return this.legacy.reviewStatus(request);
 	}