gentle-pi 2.1.2 → 2.2.0

package/tests/crosslane/cross-lane.mjs

@@ -0,0 +1,1169 @@
+// Cross-lane battery for the Pi direct lane. LOCAL, out of CI on purpose:
+// it requires the dev-binary override and drives a real gentle-ai binary
+// through live scratch-repository lifecycles.
+//
+//   pnpm test:cross-lane            # requires the dev-binary override
+//   pnpm test:cross-lane --with-model   # adds the real pi reviewer run
+//
+// The battery exists because the pinned decoder lane never sees new envelope
+// schemas and the controller sequencing was never driven through a full
+// lifecycle before merge. Three check groups:
+//   1. Full direct-lane lifecycles against the override binary through
+//      runtime/*.mjs (low to gate allow; medium consent/v3 granted).
+//   2. Controller sequencing: at every step the client's decoded offered
+//      next step must equal the native transition, and correction evidence
+//      must be collected before targeted validation is ever offered
+//      (the validate-before-evidence class, pending fix/validate-before-evidence).
+//   3. Forward-decoder freshness: every live envelope captured from the
+//      override binary must decode without unknown-key rejection - the
+//      early warning that gentle-ai main grew a field gentle-pi lacks.
+//
+// Excluded from `pnpm test` by construction: the default suite globs
+// tests/*.test.ts only.
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+	GENTLE_AI_DEV_BINARY_ENV,
+	resolveGentleAiDevBinaryOverride,
+} from "../../runtime/gentle-ai-binary.mjs";
+import {
+	createNativeReviewCli,
+	gentleAiProcessEnvironment,
+	nativeReviewAbandonAuthorization,
+	NativeReviewConsentRequiredError,
+} from "../../runtime/native-review-cli.mjs";
+import {
+	decodeReviewCapabilitiesV2,
+	decodeReviewConsentV3,
+	decodeReviewOperationV2,
+	decodeReviewResultArtifactV2,
+	decodeReviewStartV3,
+	decodeReviewStatusV3,
+} from "../../runtime/review-integration-v2.mjs";
+// The recovered-successor checks drive the CONTROLLER (not just the runtime
+// adapter) against the live binary; Node's default type stripping loads the
+// authored TypeScript directly.
+import { __testing } from "../../extensions/gentle-ai.ts";
+import { CandidateViewRegistry, injectReviewCandidateView } from "../../lib/review-candidate-view.ts";
+
+const WITH_MODEL = process.argv.includes("--with-model");
+const CONTRACT = "gentle-ai.review-integration/v2";
+const KNOWN_RED_SEQUENCING = "known-red pending fix/validate-before-evidence";
+
+// A schema-incompatible failure mid-lifecycle means the forward decoder lags
+// a field gentle-ai main already emits: the exact parity gap this battery
+// exists to surface before merge. The sequencing check (the
+// validate-before-evidence class, pending fix/validate-before-evidence)
+// stays unevaluated until decoder parity lands.
+function knownRedParity(message) {
+	if (!message.includes("schema incompatible")) return message;
+	return `known-red pending gentle-pi decoder parity with gentle-ai main: ${message}`;
+}
+
+const checks = [];
+const rawEnvelopes = [];
+
+function describeError(error) {
+	if (!(error instanceof Error)) return String(error);
+	const parts = [error.message];
+	let cause = error.cause;
+	while (cause !== undefined && cause !== null) {
+		parts.push(cause instanceof Error ? cause.message : String(cause));
+		cause = cause instanceof Error ? cause.cause : undefined;
+	}
+	let described = parts.join(" <- ");
+	if (described.includes("schema incompatible")) {
+		described += " (the decoder freshness lane below names the exact rejected field)";
+	}
+	return described;
+}
+
+function report(name, status, note) {
+	checks.push({ name, status, note });
+}
+
+function pass(name, note) {
+	report(name, "PASS", note);
+}
+function fail(name, note) {
+	report(name, "FAIL", note);
+}
+function skip(name, note) {
+	report(name, "SKIP", note);
+}
+
+// --- binary resolution: the dev-binary override is this battery's reason to exist ---
+
+function resolveBatteryBinary() {
+	const fromEnv = process.env[GENTLE_AI_DEV_BINARY_ENV];
+	if (fromEnv !== undefined && fromEnv.length > 0) return fromEnv;
+	const override = resolveGentleAiDevBinaryOverride();
+	if (override !== undefined) {
+		// Project the registration into the env override so every downstream
+		// dev-mode relaxation (version banner, capability floor) is active.
+		process.env[GENTLE_AI_DEV_BINARY_ENV] = override.path;
+		return override.path;
+	}
+	throw new Error(
+		`no dev binary override: set ${GENTLE_AI_DEV_BINARY_ENV}=<absolute path> or register one with /gentle:dev-binary <path>`,
+	);
+}
+
+// --- raw native access (the battery's independent view of the binary) ---
+
+function rawInvoke(binary, cwd, args) {
+	const stdout = execFileSync(binary, args, {
+		cwd,
+		encoding: "utf8",
+		env: gentleAiProcessEnvironment(),
+	});
+	const body = JSON.parse(stdout);
+	if (body !== null && typeof body === "object" && typeof body.schema === "string") {
+		rawEnvelopes.push({ schema: body.schema, source: args.slice(0, 2).join(" "), body });
+	}
+	return body;
+}
+
+function rawStatus(binary, cwd) {
+	return rawInvoke(binary, cwd, [
+		"review", "status", "--contract", CONTRACT, "--cwd", cwd,
+		"--projection", "workspace", "--next-transition",
+	]);
+}
+
+// --- scratch repositories ---
+
+function git(cwd, ...args) {
+	execFileSync("git", args, { cwd, encoding: "utf8" });
+}
+
+function scratchRepo(root, name) {
+	const cwd = join(root, name);
+	mkdirSync(cwd, { recursive: true });
+	git(cwd, "init", "-q", "-b", "main");
+	git(cwd, "config", "user.email", "crosslane@example.com");
+	git(cwd, "config", "user.name", "Cross Lane Battery");
+	git(cwd, "commit", "-q", "--allow-empty", "-m", "chore: root");
+	return cwd;
+}
+
+// A LINKED git worktree (not the primary checkout) of a fresh scratch repo:
+// the field shape the reported defect was hit in.
+function scratchLinkedWorktree(root, name) {
+	const primary = scratchRepo(root, `${name}-primary`);
+	const linked = join(root, `${name}-linked`);
+	git(primary, "worktree", "add", "-q", linked, "-b", `feature/${name}`);
+	git(linked, "config", "user.email", "crosslane@example.com");
+	git(linked, "config", "user.name", "Cross Lane Battery");
+	return linked;
+}
+
+function write(cwd, name, content) {
+	const path = join(cwd, name);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, content);
+}
+
+function commitAll(cwd, message) {
+	git(cwd, "add", "-A");
+	git(cwd, "commit", "-q", "-m", message);
+}
+
+// --- transition parity: the controller's offered next step vs the native one ---
+
+function transitionSummary(kind, reasonCode, executeOperation, collectOperations) {
+	return JSON.stringify({ kind, reasonCode, executeOperation, collectOperations });
+}
+
+function summarizeDecoded(transition) {
+	return transitionSummary(
+		transition?.kind ?? "(none)",
+		transition?.reasonCode ?? "(none)",
+		transition?.execute?.operation,
+		transition?.collect?.inputs.map((input) => input.captureOperation),
+	);
+}
+
+function summarizeRaw(transition) {
+	return transitionSummary(
+		transition?.kind ?? "(none)",
+		transition?.reason_code ?? "(none)",
+		transition?.execute?.operation,
+		transition?.collect?.inputs.map((input) => input.capture_operation),
+	);
+}
+
+function assertOfferedStepMatchesNative(step, decodedStatus, rawDocument) {
+	const offered = summarizeDecoded(decodedStatus.nextTransition);
+	const native = summarizeRaw(rawDocument.next_transition);
+	if (offered !== native) {
+		throw new Error(`${step}: controller offered ${offered} but native transition is ${native}`);
+	}
+}
+
+function executeTokens(transition) {
+	return transition.execute.arguments.map(
+		(argument) => argument.token ?? `--${argument.name.replaceAll("_", "-")}=${argument.value}`,
+	);
+}
+
+function rawArgumentValues(input) {
+	const values = {};
+	for (const argument of input.arguments ?? []) values[argument.name] = argument.value;
+	return values;
+}
+
+function substitute(tokens, slots) {
+	return tokens.map((token) => {
+		let out = token;
+		for (const [slot, value] of Object.entries(slots)) out = out.replaceAll(`{{${slot}}}`, value);
+		return out;
+	});
+}
+
+// --- checks ---
+
+async function lowLifecycle(binary, cli, root) {
+	const cwd = scratchRepo(root, "pi-low");
+	write(cwd, "docs/ordinary-guide.md", "# Ordinary guide\n\nline one\n");
+	commitAll(cwd, "docs: guide");
+	write(cwd, "docs/ordinary-guide.md", "# Ordinary guide\n\nline one\nline two, purely passive documentation\n");
+
+	let raw = rawStatus(binary, cwd);
+	let status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("pre-start", status, raw);
+	if (status.nextTransition?.execute?.operation !== "review.start") {
+		throw new Error(`expected review.start, got ${summarizeDecoded(status.nextTransition)}`);
+	}
+	const start = await cli.start({ cwd, targetIdentity: status.targetIdentity, projection: "workspace" });
+	if (start.riskLevel !== "low" || start.state !== "reviewing" || start.lensesRequired) {
+		throw new Error(`low start decoded riskLevel=${start.riskLevel} state=${start.state} lensesRequired=${start.lensesRequired}`);
+	}
+
+	raw = rawStatus(binary, cwd);
+	status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("pre-finalize", status, raw);
+	if (status.nextTransition?.execute?.operation !== "review.finalize") {
+		throw new Error(`expected review.finalize, got ${summarizeDecoded(status.nextTransition)}`);
+	}
+	const finalize = await cli.finalizeTransition({ cwd, argumentTokens: executeTokens(status.nextTransition) });
+	if (finalize.state !== "approved") throw new Error(`finalize state=${finalize.state}`);
+
+	git(cwd, "add", "-A");
+	const validate = await cli.validate({ cwd, gate: "pre-commit", lineageId: finalize.lineageId });
+	if (!validate.allowed || validate.result !== "allow") {
+		throw new Error(`gate result=${validate.result} allowed=${validate.allowed}`);
+	}
+	return "start (low, zero lenses) -> finalize approved -> pre-commit validate allow, offered step matched native at every hop";
+}
+
+async function mediumConsent(binary, cli, root) {
+	const cwd = scratchRepo(root, "pi-medium");
+	write(cwd, "src/mul.js", "export function mul(a, b) {\n  return a * b;\n}\n");
+	commitAll(cwd, "feat: mul");
+	write(cwd, "src/mul.js", "export function mul(a, b) {\n  return a * b;\n}\nexport function twice(a) {\n  return a + a;\n}\n");
+
+	const raw = rawStatus(binary, cwd);
+	const status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("pre-start", status, raw);
+	let consent;
+	try {
+		await cli.start({ cwd, targetIdentity: status.targetIdentity, projection: "workspace" });
+		throw new Error("medium start unexpectedly proceeded without surfacing consent");
+	} catch (error) {
+		if (!(error instanceof NativeReviewConsentRequiredError)) throw error;
+		consent = error.consent;
+	}
+	if (consent.schema !== "gentle-ai.review-integration.consent/v3") {
+		throw new Error(`consent schema=${consent.schema}`);
+	}
+	rawEnvelopes.push({ schema: consent.schema, source: "review start (consent)", body: consent.raw });
+	const answer = await cli.answerConsent({ cwd, consent, answer: "granted" });
+	if (answer.kind !== "started") throw new Error(`granted answer kind=${answer.kind}`);
+	const granted = answer.start;
+	if (granted.state !== "reviewing" || granted.riskLevel !== "medium" || granted.selectedLenses.length !== 1) {
+		throw new Error(`granted state=${granted.state} risk=${granted.riskLevel} lenses=${granted.selectedLenses.length}`);
+	}
+	return { cwd, note: "consent/v3 surfaced through the direct decoder lane; granted answer created a reviewing medium lineage" };
+}
+
+// sequencingLifecycle drives a scripted correction on its own medium lineage
+// and checks, at every step, that the client's decoded offered step equals
+// the native transition - including the evidence-before-validation ordering.
+async function sequencingLifecycle(binary, cli, root) {
+	const cwd = scratchRepo(root, "pi-sequencing");
+	const base = "export function greet(name) {\n  return \"hi \" + name;\n}\n";
+	write(cwd, "src/greet.js", base);
+	commitAll(cwd, "feat: greet");
+	write(cwd, "src/greet.js", `${base}export function shout(name) {\n  return name.toUpperCase() + "!";\n}\n`);
+
+	let raw = rawStatus(binary, cwd);
+	let status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("pre-start", status, raw);
+	let consent;
+	try {
+		await cli.start({ cwd, targetIdentity: status.targetIdentity, projection: "workspace" });
+		throw new Error("medium start unexpectedly proceeded without surfacing consent");
+	} catch (error) {
+		if (!(error instanceof NativeReviewConsentRequiredError)) throw error;
+		consent = error.consent;
+	}
+	const sequencingAnswer = await cli.answerConsent({ cwd, consent, answer: "granted" });
+	if (sequencingAnswer.kind !== "started") throw new Error(`granted answer kind=${sequencingAnswer.kind}`);
+
+	// Reviewer slot: capture one deterministic candidate-causal blocker.
+	raw = rawStatus(binary, cwd);
+	status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("reviewer-slot", status, raw);
+	const reviewerInput = status.nextTransition?.collect?.inputs[0];
+	if (reviewerInput?.captureOperation !== "review.capture-result") {
+		throw new Error(`expected review.capture-result, got ${summarizeDecoded(status.nextTransition)}`);
+	}
+	const args = rawArgumentValues(raw.next_transition.collect.inputs[0]);
+	const reviewerFile = join(root, "pi-reviewer.json");
+	writeFileSync(reviewerFile, JSON.stringify({
+		subject_hash: args["subject-hash"],
+		inspection: { status: "completed", paths: ["src/greet.js"] },
+		evidence: ["shout calls toUpperCase without a nullish guard; introduced by the candidate hunk"],
+		findings: [{
+			claim: "shout calls toUpperCase on its argument without a null/undefined guard",
+			severity: "BLOCKER",
+			evidence_class: "deterministic",
+			causal_disposition: "introduced",
+			lens: "review-reliability",
+			location: "src/greet.js:5",
+			proof_refs: ["src/greet.js:4-6 calls name.toUpperCase() with no nullish guard in the candidate tree"],
+		}],
+	}));
+	rawInvoke(binary, cwd, [
+		"review", "capture-result",
+		"--lineage", args.lineage,
+		"--expected-revision", args["expected-revision"],
+		"--target", args.target,
+		"--repository-context", args["repository-context"],
+		"--lens", args.lens,
+		"--order", args.order,
+		"--subject-hash", args["subject-hash"],
+		"--input", reviewerFile,
+	]);
+
+	// Finalize into correction_required through the client.
+	raw = rawStatus(binary, cwd);
+	status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("post-capture", status, raw);
+	if (status.nextTransition?.execute?.operation !== "review.finalize") {
+		throw new Error(`expected review.finalize, got ${summarizeDecoded(status.nextTransition)}`);
+	}
+	const finalize = await cli.finalizeTransition({ cwd, argumentTokens: executeTokens(status.nextTransition) });
+	if (finalize.state !== "correction_required") throw new Error(`finalize state=${finalize.state}`);
+
+	// Correction plan forecast is submitted BEFORE editing.
+	raw = rawStatus(binary, cwd);
+	status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("correction-plan", status, raw);
+	const planInput = raw.next_transition?.collect?.inputs[0];
+	if (planInput?.capture_operation !== "external.plan_correction") {
+		throw new Error(`expected external.plan_correction, got ${summarizeRaw(raw.next_transition)}`);
+	}
+	const planTokens = substitute(planInput.submission.argument_tokens, { value: "2" });
+	rawInvoke(binary, root, ["review", planInput.submission.operation_token, ...planTokens]);
+
+	// Bounded fix edit.
+	write(cwd, "src/greet.js", `${base}export function shout(name) {\n  if (name == null) return "!";\n  return name.toUpperCase() + "!";\n}\n`);
+
+	// THE sequencing class check: correction evidence must be collected
+	// before any targeted validation is offered.
+	raw = rawStatus(binary, cwd);
+	status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("post-fix", status, raw);
+	const inputs = status.nextTransition?.kind === "collect" ? status.nextTransition.collect?.inputs ?? [] : [];
+	// An offered validation STEP is a targeted-validation collect input. The
+	// bare `validation_request` field is descriptive context both live
+	// emitters (pinned 2.2.3 and 2.4.0-main, probed 2026-08-16) publish
+	// alongside the evidence collect at `correction_required`.
+	const validationOffered =
+		inputs.some((input) => input.captureOperation === "external.run_targeted_validation" || input.captureOperation === "review.capture-validation");
+	const evidenceInputs = inputs.filter((input) => input.captureOperation === "review.capture-evidence");
+	if (validationOffered) {
+		throw new Error(`${KNOWN_RED_SEQUENCING}: targeted validation was offered before correction evidence was captured`);
+	}
+	if (evidenceInputs.length !== 1) {
+		throw new Error(`${KNOWN_RED_SEQUENCING}: expected exactly one review.capture-evidence input before validation, got ${summarizeDecoded(status.nextTransition)}`);
+	}
+	pass("sequencing: evidence collected before targeted validation", "correction status offers exactly one review.capture-evidence and no validation until evidence lands");
+
+	const evidenceArgs = rawArgumentValues(raw.next_transition.collect.inputs[0]);
+	const evidence = await cli.captureEvidence({
+		cwd,
+		lineageId: evidenceArgs.lineage,
+		targetIdentity: evidenceArgs.target,
+		expectedRevision: evidenceArgs["expected-revision"],
+		outcome: "passed",
+		evidenceDocument: `cross-lane battery: node --check src/greet.js passed; shout(null) now returns "!" instead of throwing\n`,
+	});
+	if (evidence.outcome !== "passed") throw new Error(`evidence outcome=${evidence.outcome}`);
+
+	// Only now may targeted validation be offered.
+	raw = rawStatus(binary, cwd);
+	status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("post-evidence", status, raw);
+	const validationInput = raw.next_transition?.collect?.inputs[0];
+	if (
+		validationInput?.capture_operation !== "external.run_targeted_validation" &&
+		validationInput?.capture_operation !== "review.capture-validation"
+	) {
+		throw new Error(`expected targeted validation after evidence, got ${summarizeRaw(raw.next_transition)}`);
+	}
+	if (status.validationRequest === undefined) {
+		throw new Error("decoded status is missing the validation request after evidence capture");
+	}
+	const validatorFile = join(root, "pi-validator.json");
+	writeFileSync(validatorFile, JSON.stringify({
+		targeted_validation_request_hash: status.validationRequest.requestHash,
+		correction_target_identity: status.validationRequest.correctionTargetIdentity,
+		original_criteria: { passed: true, evidence: ["frozen correction tree guards name == null before toUpperCase per the embedded diff"] },
+		correction_regression: { passed: true, evidence: ["greet() is untouched by the correction diff; only shout gained the guard"] },
+		follow_ups: [],
+	}));
+	const validationTokens = substitute(validationInput.submission.argument_tokens, { value: validatorFile });
+	const approved = rawInvoke(binary, root, ["review", validationInput.submission.operation_token, ...validationTokens]);
+	const approvedState = approved?.result?.state ?? approved?.state;
+	if (approvedState !== "approved") throw new Error(`validation finalize state=${approvedState}`);
+	return "offered step matched native at every hop; plan -> fix -> evidence -> targeted validation -> approved receipt";
+}
+
+// abandonLifecycle drives the audited abandon end-to-end through the real
+// adapter runtime against the real binary: start a low lineage, abandon it
+// with the adapter-built maintainer authorization, and confirm the native
+// gate accepted the binding, committed a quarantine record, and no longer
+// offers the lineage as live authority. RED-provable: the check asserts the
+// adapter-built binding is exactly the nine-line
+// gentle-ai.review-abandon-authorization/v2 discarded-work binding, so a
+// v1-emitting builder (the drift class that escaped to a live Pi session)
+// fails this check before the binary is even invoked - and would be refused
+// by the native gate anyway.
+async function abandonLifecycle(binary, cli, root) {
+	const cwd = scratchRepo(root, "pi-abandon");
+	write(cwd, "docs/abandon-guide.md", "# Abandon guide\n\nline one\n");
+	commitAll(cwd, "docs: abandon guide");
+	write(cwd, "docs/abandon-guide.md", "# Abandon guide\n\nline one\nline two, purely passive documentation\n");
+
+	let raw = rawStatus(binary, cwd);
+	let status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("pre-start", status, raw);
+	const start = await cli.start({ cwd, targetIdentity: status.targetIdentity, projection: "workspace" });
+	if (start.state !== "reviewing") throw new Error(`abandon precondition start state=${start.state}`);
+
+	raw = rawStatus(binary, cwd);
+	if (raw.authority?.lineage_id !== start.lineageId || typeof raw.authority?.revision !== "string") {
+		throw new Error(`live authority missing for started lineage ${start.lineageId}: ${JSON.stringify(raw.authority)}`);
+	}
+	// A fresh lineage before any capture carries the smallest discarded-work
+	// summary the v2 binding names: no captured lens results, no findings,
+	// no evidence records.
+	const request = {
+		cwd,
+		lineage: raw.authority.lineage_id,
+		expectedRevision: raw.authority.revision,
+		snapshotIdentity: raw.projection.initial_snapshot_identity,
+		capturedLensResults: [],
+		findingsPresent: false,
+		evidenceRecordsPresent: false,
+		actor: "cross-lane-battery",
+		reason: "operator_disposition",
+	};
+	const authorization = nativeReviewAbandonAuthorization(request);
+	const expectedBinding = [
+		"gentle-ai.review-abandon-authorization/v2",
+		`lineage=${request.lineage}`,
+		`revision=${request.expectedRevision}`,
+		`snapshot_identity=${request.snapshotIdentity}`,
+		"reason=operator_disposition",
+		"captured_lens_results=",
+		"findings_present=false",
+		"evidence_records_present=false",
+		"actor=cross-lane-battery",
+	].join("\n");
+	if (authorization !== expectedBinding) {
+		throw new Error(
+			`adapter built ${authorization.split("\n")[0]} instead of the exact nine-line gentle-ai.review-abandon-authorization/v2 binding: the audited-abandon drift class (v1 emission) is back`,
+		);
+	}
+	const result = await cli.abandon({ ...request, maintainerAuthorization: authorization });
+	if (result.record?.status !== "committed") throw new Error(`abandon record status=${result.record?.status}`);
+	if (result.record?.abandonment?.schema !== "gentle-ai.review-abandon-authorization/v2") {
+		throw new Error(`abandon record binding schema=${result.record?.abandonment?.schema}`);
+	}
+
+	// The abandoned lineage must no longer be offered as live authority.
+	raw = rawStatus(binary, cwd);
+	status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("post-abandon", status, raw);
+	if (raw.authority !== null && raw.authority !== undefined) {
+		throw new Error(`post-abandon status still reports live authority ${JSON.stringify(raw.authority)}`);
+	}
+	if (status.nextTransition?.execute?.operation !== "review.start") {
+		throw new Error(`post-abandon expected a fresh review.start, got ${summarizeDecoded(status.nextTransition)}`);
+	}
+	return "adapter-built nine-line v2 binding accepted natively; quarantine record committed; post-abandon status offers only a fresh start";
+}
+
+// recoveredSuccessorLifecycle reproduces the maintainer's live scenario
+// (2026-08-16, Engram #12461/#12466): a lineage recovered EXTERNALLY through
+// the native CLI, then driven by the Pi controller from STATUS alone.
+//   1. approve a low documentation lineage;
+//   2. change the scope with a code edit (medium risk);
+//   3. native `review recover --disposition scope_changed` with the explicit
+//      LF-only gentle-ai.review-recovery-authorization/v1 binding (an ACTIVE
+//      reviewing predecessor refuses recovery, so approval comes first);
+//   4. defect A: the controller's dispatch binding must hydrate from the
+//      STATUS the controller itself decodes — before that STATUS, dispatch
+//      refuses with current-binding-missing;
+//   5. defect B: finalize at reviewer_results_required must surface the
+//      provider-offered review.capture-result step, never the correction
+//      evidence-first-ordering lane;
+//   6. the drive completes to one really captured lens.
+async function recoveredSuccessorLifecycle(binary, cli, root) {
+	const cwd = scratchRepo(root, "pi-recovered");
+	write(cwd, "docs/recover-guide.md", "# Recover guide\n\nline one\n");
+	write(cwd, "src/mul.js", "export function mul(a, b) {\n  return a * b;\n}\n");
+	commitAll(cwd, "feat: base");
+	write(cwd, "docs/recover-guide.md", "# Recover guide\n\nline one\nline two, purely passive documentation\n");
+
+	// Low predecessor to approval.
+	let raw = rawStatus(binary, cwd);
+	let status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("pre-start", status, raw);
+	const start = await cli.start({ cwd, targetIdentity: status.targetIdentity, projection: "workspace" });
+	if (start.riskLevel !== "low" || start.state !== "reviewing") throw new Error(`predecessor start risk=${start.riskLevel} state=${start.state}`);
+	status = await cli.targetStatus({ cwd });
+	if (status.nextTransition?.execute?.operation !== "review.finalize") {
+		throw new Error(`expected review.finalize, got ${summarizeDecoded(status.nextTransition)}`);
+	}
+	const finalize = await cli.finalizeTransition({ cwd, argumentTokens: executeTokens(status.nextTransition) });
+	if (finalize.state !== "approved") throw new Error(`predecessor finalize state=${finalize.state}`);
+
+	// External scope change: code joins the approved documentation change.
+	write(cwd, "src/mul.js", "export function mul(a, b) {\n  return a * b;\n}\nexport function twice(a) {\n  return a + a;\n}\n");
+	raw = rawStatus(binary, cwd);
+	const successor = "recovered-successor-crosslane";
+	const authorization = [
+		"gentle-ai.review-recovery-authorization/v1",
+		`predecessor_lineage=${finalize.lineageId}`,
+		`predecessor_revision=${finalize.storeRevision}`,
+		`target_identity=${raw.target_identity}`,
+		"actor=cross-lane-battery",
+		"reason=scope changed after approval",
+	].join("\n");
+	rawInvoke(binary, cwd, [
+		"review", "recover", "--cwd", cwd,
+		"--predecessor-lineage", finalize.lineageId,
+		"--expected-predecessor-revision", finalize.storeRevision,
+		"--successor-lineage", successor,
+		"--disposition", "scope_changed",
+		"--actor", "cross-lane-battery",
+		"--reason", "scope changed after approval",
+		"--maintainer-authorization", authorization,
+	]);
+
+	const registry = new CandidateViewRegistry();
+	try {
+		// Defect A: before the controller decodes the successor's STATUS, the
+		// dispatch registry knows nothing — the refusal is the pre-fix shape.
+		let refused = false;
+		try {
+			injectReviewCandidateView({ agent: "review-reliability", task: "probe", mode: "task" }, registry);
+		} catch (error) {
+			refused = /no current controller-owned candidate view lineage binding/.test(String(error instanceof Error ? error.message : error));
+		}
+		if (!refused) throw new Error("pre-STATUS dispatch unexpectedly resolved a binding for the recovered successor");
+		await __testing.executeReviewControllerOperation({ operation: "status", lineageId: successor }, cwd, new Map(), cli, undefined, undefined, undefined, registry);
+		if (!registry.hasCurrentBinding()) {
+			throw new Error("controller STATUS did not hydrate the candidate-view dispatch binding for the recovered successor");
+		}
+		const dispatch = { agent: "review-reliability", task: "review the recovered successor", mode: "task" };
+		injectReviewCandidateView(dispatch, registry);
+		if (!dispatch.task.includes(successor)) throw new Error("hydrated dispatch context is not bound to the recovered successor lineage");
+		pass(
+			"recovered binding: STATUS hydrates controller dispatch",
+			"external scope_changed successor driven from STATUS alone: pre-STATUS dispatch refused, post-STATUS dispatch injected the successor candidate context (a controller without STATUS hydration fails here)",
+		);
+
+		// Defect B: finalize must follow the provider transition for reviewer
+		// results and never the correction evidence-first-ordering lane. On a
+		// provider that admits the pi transport the correct route is the host
+		// relay; the pi-subprocess hop is stubbed to keep this check free.
+		let relaySlots = 0;
+		__testing.setReviewHostRelayRunnerForTesting(async (request) => {
+			relaySlots += 1;
+			return { promptByteLength: request.captureArgumentTokens.length, resultByteLength: 0, submission: "{}" };
+		});
+		let finalizeEnvelope;
+		try {
+			finalizeEnvelope = await __testing.executeReviewControllerOperation({ operation: "finalize", lineageId: successor, input: JSON.stringify({ reviewer_run_acknowledged: true }) }, cwd, new Map(), cli, undefined, undefined, undefined, registry);
+		} finally {
+			__testing.setReviewHostRelayRunnerForTesting();
+		}
+		const routedToRelay = relaySlots > 0 && finalizeEnvelope.host_relay?.transport === "pi_host_relay";
+		const routedToBlockedCapture = finalizeEnvelope.outcome === "reviewer-results-required"
+			&& /capture the reviewer result first/i.test(String(finalizeEnvelope.reason))
+			&& finalizeEnvelope.mutation_performed === false;
+		if (!routedToRelay && !routedToBlockedCapture) {
+			throw new Error(`finalize routed to ${String(finalizeEnvelope.outcome ?? finalizeEnvelope.status)} instead of the provider reviewer-result step`);
+		}
+		if (JSON.stringify(finalizeEnvelope).includes("evidence-first-ordering")) {
+			throw new Error("finalize still leaked the correction evidence-first-ordering lane");
+		}
+		pass(
+			"recovered routing: finalize offers capture-result, never evidence ordering",
+			routedToRelay
+				? "finalize followed the provider transition into the pi host relay for the outstanding reviewer result. Accepting either provider-correct route (relay when the provider admits the pi transport, blocked capture-result otherwise) is NOT a relaxation of the evidence-ordering guard: this check still fails on any evidence-first-ordering leak in the envelope, and on any route that is neither of the two"
+				: "document-free finalize at reviewer_results_required returned the actionable review.capture-result block with zero mutations. Accepting either provider-correct route (relay when the provider admits the pi transport, blocked capture-result otherwise) is NOT a relaxation of the evidence-ordering guard: this check still fails on any evidence-first-ordering leak in the envelope, and on any route that is neither of the two",
+		);
+
+		// Complete the drive to one really captured lens through the exact
+		// provider collect input.
+		raw = rawStatus(binary, cwd);
+		const input = raw.next_transition?.collect?.inputs?.[0];
+		if (input?.capture_operation !== "review.capture-result") throw new Error(`expected review.capture-result, got ${summarizeRaw(raw.next_transition)}`);
+		const args = rawArgumentValues(input);
+		const reviewerFile = join(root, "pi-recovered-reviewer.json");
+		writeFileSync(reviewerFile, JSON.stringify({
+			subject_hash: args["subject-hash"],
+			inspection: { status: "completed", paths: (input.changed_path_manifest ?? []).map((entry) => entry.path) },
+			evidence: ["twice(a) returns a + a: pure arithmetic introduced by the candidate hunk with no external effects"],
+			findings: [],
+		}));
+		const artifact = rawInvoke(binary, cwd, [
+			"review", "capture-result",
+			"--lineage", args.lineage,
+			"--expected-revision", args["expected-revision"],
+			"--target", args.target,
+			"--repository-context", args["repository-context"],
+			"--lens", args.lens,
+			"--order", args.order,
+			"--subject-hash", args["subject-hash"],
+			"--input", reviewerFile,
+		]);
+		if (artifact?.schema !== "gentle-ai.review-result-artifact/v2") throw new Error(`successor lens capture returned schema=${artifact?.schema}`);
+		return "low predecessor approved -> native scope_changed recover (explicit v1 binding) -> controller drove the successor from STATUS alone to one captured lens";
+	} finally {
+		try {
+			registry.cleanup(registry.resolveCurrentForLens("review-reliability").token);
+		} catch {
+			// No hydrated view to clean when the check failed before binding.
+		}
+	}
+}
+
+// externallyRecoveredSuccessor performs the shared setup both recovered-
+// lineage checks need: approve a predecessor in `cwd`, change the scope, and
+// create a successor through the EXTERNAL native `review recover` command
+// with its explicit LF-only v1 binding. Returns the successor lineage id.
+async function externallyRecoveredSuccessor(binary, cli, cwd, successor) {
+	let raw = rawStatus(binary, cwd);
+	let status = await cli.targetStatus({ cwd });
+	assertOfferedStepMatchesNative("pre-start", status, raw);
+	const start = await cli.start({ cwd, targetIdentity: status.targetIdentity, projection: "workspace" });
+	if (start.state !== "reviewing") throw new Error(`predecessor start state=${start.state}`);
+	status = await cli.targetStatus({ cwd });
+	if (status.nextTransition?.execute?.operation !== "review.finalize") {
+		throw new Error(`expected review.finalize, got ${summarizeDecoded(status.nextTransition)}`);
+	}
+	const finalize = await cli.finalizeTransition({ cwd, argumentTokens: executeTokens(status.nextTransition) });
+	if (finalize.state !== "approved") throw new Error(`predecessor finalize state=${finalize.state}`);
+	// The caller has already staged its scope change in the worktree.
+	write(cwd, "src/mul.js", "export function mul(a, b) {\n  return a * b;\n}\nexport function twice(a) {\n  return a + a;\n}\n");
+	raw = rawStatus(binary, cwd);
+	const authorization = [
+		"gentle-ai.review-recovery-authorization/v1",
+		`predecessor_lineage=${finalize.lineageId}`,
+		`predecessor_revision=${finalize.storeRevision}`,
+		`target_identity=${raw.target_identity}`,
+		"actor=cross-lane-battery",
+		"reason=scope changed after approval",
+	].join("\n");
+	rawInvoke(binary, cwd, [
+		"review", "recover", "--cwd", cwd,
+		"--predecessor-lineage", finalize.lineageId,
+		"--expected-predecessor-revision", finalize.storeRevision,
+		"--successor-lineage", successor,
+		"--disposition", "scope_changed",
+		"--actor", "cross-lane-battery",
+		"--reason", "scope changed after approval",
+		"--maintainer-authorization", authorization,
+	]);
+	return successor;
+}
+
+// recoveredSuccessorFieldFlow reproduces the FIELD-REPORTED flow (2026-08-16,
+// gentle-pi 402f9f77 + gentle-ai 2.4.0-main): the candidate lives in a LINKED
+// git worktree with UNCOMMITTED tracked modifications, the successor came
+// from an external native recover, and the session drives `finalize` FIRST
+// and dispatches the reviewer straight after — never calling the STATUS
+// controller operation. Hydration wired only into STATUS leaves that flow
+// refusing, which is exactly what the maintainer hit after #340.
+//
+// Residual gap, honestly stated: the battery cannot age a lineage by days or
+// span real OS processes; it reproduces linked-worktree placement, dirty
+// tracked files, external recovery, and a FRESH controller registry (the
+// property a new process actually contributes), not wall-clock age.
+async function recoveredSuccessorFieldFlow(binary, cli, root) {
+	const cwd = scratchLinkedWorktree(root, "pi-recovered-linked");
+	write(cwd, "docs/recover-guide.md", "# Recover guide\n\nline one\n");
+	write(cwd, "src/mul.js", "export function mul(a, b) {\n  return a * b;\n}\n");
+	commitAll(cwd, "feat: base");
+	write(cwd, "docs/recover-guide.md", "# Recover guide\n\nline one\nline two, purely passive documentation\n");
+	const successor = await externallyRecoveredSuccessor(binary, cli, cwd, "recovered-linked-successor");
+	// The tracked scope change stays UNCOMMITTED, like the reported worktree.
+	const dirty = execFileSync("git", ["status", "--porcelain"], { cwd, encoding: "utf8" });
+	if (!/^ M src\/mul\.js$/m.test(dirty)) throw new Error(`expected an uncommitted tracked modification, got ${JSON.stringify(dirty)}`);
+
+	// A brand-new registry stands in for the fresh Pi session.
+	const registry = new CandidateViewRegistry();
+	try {
+		// The pi-subprocess hop is stubbed: this check is about the dispatch
+		// binding the finalize-first flow leaves behind, on whichever route the
+		// provider offers (host relay when it admits the pi transport).
+		__testing.setReviewHostRelayRunnerForTesting(async (request) => ({ promptByteLength: request.captureArgumentTokens.length, resultByteLength: 0, submission: "{}" }));
+		let finalizeEnvelope;
+		try {
+			finalizeEnvelope = await __testing.executeReviewControllerOperation({ operation: "finalize", lineageId: successor, input: JSON.stringify({ reviewer_run_acknowledged: true }) }, cwd, new Map(), cli, undefined, undefined, undefined, registry);
+		} finally {
+			__testing.setReviewHostRelayRunnerForTesting();
+		}
+		const routed = finalizeEnvelope.outcome === "reviewer-results-required" || finalizeEnvelope.host_relay?.transport === "pi_host_relay";
+		if (!routed) {
+			throw new Error(`finalize routed to ${String(finalizeEnvelope.outcome ?? finalizeEnvelope.status)} instead of the provider reviewer-result step`);
+		}
+		if (JSON.stringify(finalizeEnvelope).includes("evidence-first-ordering")) {
+			throw new Error("finalize leaked the correction evidence-first-ordering lane");
+		}
+		const binding = finalizeEnvelope.dispatch_binding;
+		if (binding === undefined) throw new Error("the blocked finalize envelope does not report a dispatch-binding hydration outcome");
+		if (binding.hydrated !== true) {
+			throw new Error(`finalize reported hydration failure ${String(binding.reason)}: ${String(binding.message)}`);
+		}
+		if (!registry.hasCurrentBinding()) throw new Error("finalize did not hydrate the candidate-view dispatch binding");
+		// The reviewer dispatch the maintainer runs next must resolve.
+		const dispatch = { agent: "review-reliability", task: "review the recovered successor", mode: "task" };
+		injectReviewCandidateView(dispatch, registry);
+		if (!dispatch.task.includes(successor)) throw new Error("hydrated dispatch context is not bound to the recovered successor lineage");
+		return "linked worktree + uncommitted tracked changes + external recover: finalize-first (no STATUS call) hydrated the dispatch binding and the reviewer dispatch resolved, on whichever provider-correct route was offered, and the envelope still carries no evidence-first-ordering leak; residual gap: the battery cannot age a lineage by days or span OS processes, only a fresh registry";
+	} finally {
+		try {
+			registry.cleanup(registry.resolveCurrentForLens("review-reliability").token);
+		} catch {
+			// No hydrated view to clean when the check failed before binding.
+		}
+	}
+}
+
+// relayMaterializeSlotLifecycle covers the shape every earlier check missed:
+// the provider's MATERIALIZE-marked host-relay slot (agent=pi,
+// materialize=true, provider submission) on an externally recovered lineage.
+// Measured root cause (third field report): the adapter's negotiated STATUS
+// never named its agent, so the provider only ever returned a bare
+// capture-result input, reviewHostRelaySlots() saw zero slots, and the relay
+// never ran. This check fails on any build that drops `--agent pi`.
+//
+// Residual gap, stated honestly: the locked-down pi subprocess and the final
+// provider submit leg are NOT executed here — those cost model spend. The
+// check drives everything up to and including the REAL materialize leg
+// against the real binary (the provider-issued tokens must actually produce
+// prompt bytes), and stubs only the pi-subprocess hop.
+// correctedLifecycleThroughAdapter drives the shape three field defects in a
+// row escaped through: a MEDIUM candidate taken all the way through detection,
+// bounded correction, evidence and targeted validation to an approved receipt
+// THROUGH THE ADAPTER — not the clean-approval path, and not raw CLI.
+//
+// Field defect it locks down (Engram #12547): after an admitted correction the
+// candidate identity legitimately moves, and a FINALIZE that merely follows the
+// provider's own execute transition carries no documents. That made the
+// adapter resolve the START-time reviewer view and report
+// `candidate-target-projection-drift`, so no corrected lineage could ever reach
+// a receipt through Pi.
+//
+// The controller-driven client is built from lib/*.ts on purpose: the battery's
+// shared `cli` comes from runtime/*.mjs, and mixing that module instance with
+// the extension's lib/*.ts instance breaks `instanceof` across the boundary,
+// which silently turns the consent path into a generic failure.
+async function correctedLifecycleThroughAdapter(binary, root) {
+	const { createNativeReviewCli } = await import("../../lib/native-review-cli.ts");
+	const cli = createNativeReviewCli(undefined, binary);
+	const cwd = scratchRepo(root, "pi-corrected");
+	const base = "export function parsePath(input) {\n  return input.split(\"/\");\n}\n";
+	write(cwd, "src/parse.js", base);
+	commitAll(cwd, "feat: parse");
+	// The intentional reliability defect: the last component is omitted.
+	write(cwd, "src/parse.js", `${base}export function lastComponent(input) {\n  const parts = input.split("/");\n  return parts[parts.length - 2];\n}\n`);
+
+	const registry = new CandidateViewRegistry();
+	const context = { cwd, hasUI: false, ui: { confirm: async () => true, notify: () => {} } };
+	// The real tool is used, not the bare entry point: the pending-consent map
+	// lives for the tool's lifetime, so START and ANSWER-CONSENT share it.
+	const { createGentleAiExtension } = await import("../../extensions/gentle-ai.ts");
+	const tools = new Map();
+	createGentleAiExtension({ nativeReviewCli: cli, candidateViews: registry })({
+		on() {}, registerTool(definition) { tools.set(definition.name, definition); }, registerCommand() {},
+	});
+	const tool = tools.get("gentle_review");
+	let call = 0;
+	const controller = async (parameters) => (await tool.execute(`corrected-${call++}`, parameters, undefined, undefined, context)).details;
+	let boundLineageId;
+	try {
+		// START through the controller so this session holds the START-time
+		// immutable reviewer view — the state the defect needs.
+		let envelope = await controller({ operation: "start", input: JSON.stringify({ mode: "ordinary" }) });
+		if (envelope.consent_binding === undefined) throw new Error(`medium START did not surface consent: ${String(envelope.outcome ?? envelope.status)}`);
+		envelope = await controller({ operation: "answer-consent", input: JSON.stringify({ consentBinding: envelope.consent_binding, answer: "granted" }) });
+		const lineageId = envelope.result?.lineage_id;
+		boundLineageId = lineageId;
+		if (envelope.result?.state !== "reviewing" || lineageId === undefined) throw new Error(`granted START state=${String(envelope.result?.state)}`);
+		if (!registry.hasCurrentBinding()) throw new Error("START did not bind the immutable reviewer view for this session");
+		const startTree = rawStatus(binary, cwd).projection.current_candidate_tree;
+
+		// Reviewer slot: one deterministic candidate-caused BLOCKER.
+		let raw = rawStatus(binary, cwd);
+		let slot = raw.next_transition?.collect?.inputs?.[0];
+		if (slot?.capture_operation !== "review.capture-result") throw new Error(`expected review.capture-result, got ${summarizeRaw(raw.next_transition)}`);
+		let args = rawArgumentValues(slot);
+		const reviewerFile = join(root, "pi-corrected-reviewer.json");
+		writeFileSync(reviewerFile, JSON.stringify({
+			subject_hash: args["subject-hash"],
+			inspection: { status: "completed", paths: ["src/parse.js"] },
+			evidence: ["lastComponent indexes parts.length - 2 and omits the last component; introduced by the candidate hunk"],
+			findings: [{
+				claim: "lastComponent returns the second-to-last path component instead of the last",
+				severity: "BLOCKER",
+				evidence_class: "deterministic",
+				causal_disposition: "introduced",
+				lens: args.lens,
+				location: "src/parse.js:6",
+				proof_refs: ["src/parse.js:4-7 indexes parts.length - 2 in the candidate tree"],
+			}],
+		}));
+		rawInvoke(binary, cwd, ["review", "capture-result", "--lineage", args.lineage, "--expected-revision", args["expected-revision"],
+			"--target", args.target, "--repository-context", args["repository-context"], "--lens", args.lens,
+			"--order", args.order, "--subject-hash", args["subject-hash"], "--input", reviewerFile]);
+
+		envelope = await controller({ operation: "finalize", lineageId, input: JSON.stringify({}) });
+		if (envelope.result?.state !== "correction_required") throw new Error(`finalize after capture state=${String(envelope.result?.state ?? envelope.outcome)}`);
+
+		// Bounded correction: forecast BEFORE editing, then the edit.
+		raw = rawStatus(binary, cwd);
+		const planInput = raw.next_transition?.collect?.inputs?.[0];
+		if (planInput?.capture_operation !== "external.plan_correction") throw new Error(`expected external.plan_correction, got ${summarizeRaw(raw.next_transition)}`);
+		const bounds = planInput.submission?.values?.[0] ?? {};
+		envelope = await controller({ operation: "finalize", lineageId, input: JSON.stringify({ correction_line_forecast: bounds.minimum ?? 1 }) });
+		if (envelope.result?.state !== "correction_required") throw new Error(`correction forecast rejected: ${JSON.stringify(envelope.diagnostics ?? envelope.outcome)}`);
+		write(cwd, "src/parse.js", `${base}export function lastComponent(input) {\n  const parts = input.split("/");\n  return parts[parts.length - 1];\n}\n`);
+		const correctedTree = rawStatus(binary, cwd).projection.current_candidate_tree;
+		if (correctedTree === startTree) throw new Error("the correction did not move the candidate identity");
+
+		// THE REGRESSION PROBE: a FINALIZE that just follows the provider
+		// transition carries no documents. Whatever the provider answers is
+		// fine; what must never come back is adapter-side reviewer-view drift.
+		envelope = await controller({ operation: "finalize", lineageId, input: JSON.stringify({}) });
+		if (envelope.diagnostics?.code === "candidate-target-projection-drift") {
+			throw new Error("document-free FINALIZE on the corrected candidate still reports candidate-target-projection-drift");
+		}
+
+		// Correction evidence, then targeted validation, to the receipt.
+		envelope = await controller({ operation: "finalize", lineageId, input: JSON.stringify({ final_evidence: "node --check src/parse.js passed; lastComponent now returns the final component", final_verification_passed: true }) });
+		if (envelope.diagnostics?.code === "candidate-target-projection-drift") throw new Error("evidence FINALIZE reported candidate-target-projection-drift");
+		raw = rawStatus(binary, cwd);
+		const validationInput = raw.next_transition?.collect?.inputs?.[0];
+		if (validationInput?.capture_operation !== "external.run_targeted_validation") {
+			return `corrected lineage reached ${String(raw.authority?.state)} through the adapter with no candidate-target-projection-drift at any step; residual gap: this provider renders targeted validation as the Go-owned ${String(validationInput?.capture_operation)} vector, which costs a model run, so the battery stops before the receipt`;
+		}
+		// The evidence-only FINALIZE above already advanced the provider to
+		// targeted validation, so the receipt is completed through the exact
+		// provider-rendered submission (the same way the sequencing check does).
+		// Re-calling FINALIZE with final_evidence AND validation re-enters
+		// evidence capture on this provider; that lane question is pre-existing
+		// and out of scope for this defect, and is noted rather than papered over.
+		const request = raw.validation_request ?? validationInput.validation_request;
+		const validatorFile = join(root, "pi-corrected-validator.json");
+		writeFileSync(validatorFile, JSON.stringify({
+			targeted_validation_request_hash: request.request_hash,
+			correction_target_identity: request.correction_target_identity,
+			original_criteria: { passed: true, evidence: ["frozen correction tree returns parts[parts.length - 1]"] },
+			correction_regression: { passed: true, evidence: ["parsePath is untouched by the correction diff"] },
+			follow_ups: [],
+		}));
+		const submitted = rawInvoke(binary, root, ["review", validationInput.submission.operation_token,
+			...substitute(validationInput.submission.argument_tokens, { value: validatorFile })]);
+		const finalState = submitted?.result?.state ?? submitted?.state ?? rawStatus(binary, cwd).authority?.state;
+		if (finalState !== "approved") throw new Error(`corrected lineage ended at ${String(finalState)} instead of approved`);
+		// The receipt must be the adapter-validatable one for the corrected tree.
+		const gate = await controller({ operation: "status", lineageId });
+		if (gate.result?.authority?.state !== "approved") throw new Error(`adapter status does not see the approved corrected lineage: ${String(gate.result?.authority?.state)}`);
+		return "medium candidate driven through the adapter: BLOCKER detected -> bounded correction -> document-free provider-transition FINALIZE with no candidate-target-projection-drift -> correction evidence -> targeted validation -> approved receipt the adapter can see. Residual gap: the final targeted-validation document is submitted through the exact provider-rendered vector, because a combined evidence+validation FINALIZE re-enters evidence capture on this provider (pre-existing lane question, not this defect)";
+	} finally {
+		// Candidate views are materialized read-only; leaving one behind makes
+		// the battery's own root cleanup fail with EACCES.
+		const resolvers = [
+			() => registry.resolveCurrentForLens("review-reliability"),
+			...(boundLineageId === undefined ? [] : [() => registry.resolveForFinalize(boundLineageId)]),
+		];
+		for (const resolve of resolvers) {
+			try { registry.cleanup(resolve().token); } catch { /* nothing bound to clean */ }
+		}
+	}
+}
+
+async function relayMaterializeSlotLifecycle(binary, cli, root) {
+	const cwd = scratchLinkedWorktree(root, "pi-relay-slot");
+	write(cwd, "docs/relay-guide.md", "# Relay guide\n\nline one\n");
+	write(cwd, "src/mul.js", "export function mul(a, b) {\n  return a * b;\n}\n");
+	commitAll(cwd, "feat: base");
+	write(cwd, "docs/relay-guide.md", "# Relay guide\n\nline one\nline two, purely passive documentation\n");
+	const successor = await externallyRecoveredSuccessor(binary, cli, cwd, "relay-materialize-successor");
+
+	const relayed = [];
+	let materializedBytes = 0;
+	const registry = new CandidateViewRegistry();
+	__testing.setReviewHostRelayRunnerForTesting(async (request) => {
+		relayed.push(request);
+		// The REAL materialize leg: the provider-issued tokens must produce a
+		// non-empty opaque prompt from the real binary. No model spend.
+		const prompt = execFileSync(binary, ["review", "capture-result", ...request.captureArgumentTokens], {
+			cwd,
+			env: gentleAiProcessEnvironment(),
+			maxBuffer: 64 * 1024 * 1024,
+		});
+		materializedBytes = prompt.length;
+		if (materializedBytes === 0) throw new Error("provider materialize produced no prompt bytes");
+		return { promptByteLength: materializedBytes, resultByteLength: 0, submission: "{}" };
+	});
+	try {
+		const envelope = await __testing.executeReviewControllerOperation(
+			{ operation: "finalize", lineageId: successor, input: JSON.stringify({ reviewer_run_acknowledged: true }) },
+			cwd, new Map(), cli, undefined, undefined, undefined, registry,
+		);
+		if (relayed.length !== 1) {
+			throw new Error(`the provider materialize slot never reached the host relay (relayed ${relayed.length}); outcome=${String(envelope.outcome ?? envelope.status)}`);
+		}
+		const tokens = relayed[0].captureArgumentTokens;
+		if (!tokens.includes("--agent=pi") || !tokens.includes("--materialize=true")) {
+			throw new Error(`relay slot is missing the provider transport tokens: ${tokens.join(" ")}`);
+		}
+		if (relayed[0].submission?.operationToken !== "capture-result") {
+			throw new Error("relay slot carries no provider submission completing form");
+		}
+		const hostRelay = envelope.host_relay;
+		if (hostRelay?.transport !== "pi_host_relay" || hostRelay.captured_slots?.length !== 1) {
+			throw new Error(`controller envelope did not report one relayed slot: ${JSON.stringify(hostRelay)}`);
+		}
+		return `provider offered the materialize slot to the adapter and it reached the relay verbatim (agent=pi, materialize=true, submission=capture-result); the real materialize leg returned ${materializedBytes} prompt bytes. Residual gap: the locked-down pi subprocess and the provider submit leg are not executed here (model spend)`;
+	} finally {
+		__testing.setReviewHostRelayRunnerForTesting();
+		try {
+			registry.cleanup(registry.resolveCurrentForLens("review-reliability").token);
+		} catch {
+			// No hydrated view to clean when the relay lane bound nothing.
+		}
+	}
+}
+
+async function modelReview(binary, cli, cwd) {
+	const raw = rawStatus(binary, cwd);
+	const input = raw.next_transition?.collect?.inputs?.[0];
+	if (input?.capture_operation !== "review.capture-result") {
+		throw new Error(`expected review.capture-result, got ${summarizeRaw(raw.next_transition)}`);
+	}
+	const args = rawArgumentValues(input);
+	const artifact = rawInvoke(binary, cwd, [
+		"review", "capture-result",
+		"--lineage", args.lineage,
+		"--expected-revision", args["expected-revision"],
+		"--target", args.target,
+		"--repository-context", args["repository-context"],
+		"--lens", args.lens,
+		"--order", args.order,
+		"--subject-hash", args["subject-hash"],
+		"--agent", "pi",
+	]);
+	if (artifact?.schema !== "gentle-ai.review-result-artifact/v2") {
+		throw new Error(`model capture returned schema=${artifact?.schema}`);
+	}
+	return "Go-owned locked-down pi reviewer captured a native result artifact";
+}
+
+// --- forward-decoder freshness over every captured live envelope ---
+
+function decoderFor(schema, binaryDigest) {
+	switch (schema) {
+		case "gentle-ai.review-integration.status/v3":
+		case "gentle-ai.review-integration.status/v4":
+		case "gentle-ai.review-integration.status/v5":
+			return (body) => decodeReviewStatusV3(body);
+		case "gentle-ai.review-integration.start/v3":
+			return (body) => decodeReviewStartV3(body);
+		case "gentle-ai.review-integration.consent/v3":
+			return (body) => decodeReviewConsentV3(body);
+		case "gentle-ai.review-integration.operation/v2":
+			return (body) => decodeReviewOperationV2(body);
+		case "gentle-ai.review-result-artifact/v2":
+			return (body) => decodeReviewResultArtifactV2(body);
+		case "gentle-ai.review-integration.capabilities/v2":
+		case "gentle-ai.review-integration.capabilities/v2.1":
+		case "gentle-ai.review-integration.capabilities/v2.2":
+			return (body) => decodeReviewCapabilitiesV2(body, binaryDigest);
+		default:
+			return undefined;
+	}
+}
+
+function decoderFreshness(binary) {
+	const digest = `sha256:${createHash("sha256").update(readFileSync(binary)).digest("hex")}`;
+	const outcomes = new Map();
+	for (const envelope of rawEnvelopes) {
+		const state = outcomes.get(envelope.schema) ?? { total: 0, failures: [] };
+		state.total += 1;
+		const decoder = decoderFor(envelope.schema, digest);
+		if (decoder === undefined) {
+			state.failures.push(`no forward decoder maps ${envelope.schema} (${envelope.source})`);
+		} else {
+			try {
+				decoder(envelope.body);
+			} catch (error) {
+				state.failures.push(`${envelope.source}: ${describeError(error)}`);
+			}
+		}
+		outcomes.set(envelope.schema, state);
+	}
+	for (const schema of [...outcomes.keys()].sort()) {
+		const state = outcomes.get(schema);
+		const unique = [...new Set(state.failures)].slice(0, 3);
+		if (state.failures.length === 0) {
+			pass(`decoder freshness: ${schema}`, `${state.total} live envelope(s) decoded without unknown-key rejection`);
+		} else {
+			fail(`decoder freshness: ${schema}`, `${state.failures.length}/${state.total} rejected: ${unique.join(" | ")}`);
+		}
+	}
+}
+
+// Candidate views are materialized read-only, so a leaked one makes a plain
+// rmSync fail with EACCES — and losing the battery's results table to a scratch
+// permission is worse than leaving bytes in /tmp. Make everything writable
+// first, then remove, and never let cleanup mask the run's outcome.
+function removeScratchRoot(root) {
+	const makeWritable = (path) => {
+		let entry;
+		try { entry = statSync(path); } catch { return; }
+		try { chmodSync(path, entry.isDirectory() ? 0o700 : 0o600); } catch { /* best effort */ }
+		if (!entry.isDirectory()) return;
+		let children = [];
+		try { children = readdirSync(path); } catch { return; }
+		for (const child of children) makeWritable(join(path, child));
+	};
+	makeWritable(root);
+	try {
+		rmSync(root, { recursive: true, force: true });
+	} catch (error) {
+		console.log(`note: scratch root ${root} could not be fully removed (${error.code ?? "unknown"}); results below are unaffected`);
+	}
+}
+
+// --- driver ---
+
+async function main() {
+	const binary = resolveBatteryBinary();
+	console.log(`cross-lane battery (Pi direct lane)`);
+	console.log(`binary: ${binary}`);
+	const root = mkdtempSync(join(tmpdir(), "gentle-pi-crosslane-"));
+	const cli = createNativeReviewCli(undefined, binary);
+	try {
+		// Capture one live capabilities envelope for the freshness lane.
+		rawInvoke(binary, root, ["review", "capabilities", "--contract", CONTRACT]);
+
+		try {
+			pass("low lifecycle to gate allow", await lowLifecycle(binary, cli, root));
+		} catch (error) {
+			fail("low lifecycle to gate allow", knownRedParity(describeError(error)));
+		}
+
+		let mediumRepo;
+		try {
+			const outcome = await mediumConsent(binary, cli, root);
+			mediumRepo = outcome.cwd;
+			pass("medium consent/v3 granted round-trip", outcome.note);
+		} catch (error) {
+			fail("medium consent/v3 granted round-trip", describeError(error));
+		}
+
+		try {
+			pass("sequencing lifecycle to approved receipt", await sequencingLifecycle(binary, cli, root));
+		} catch (error) {
+			const message = describeError(error);
+			const name = message.startsWith(KNOWN_RED_SEQUENCING)
+				? "sequencing: evidence collected before targeted validation"
+				: "sequencing lifecycle to approved receipt";
+			fail(name, knownRedParity(message));
+		}
+
+		try {
+			pass("audited abandon end-to-end (v2 discarded-work binding)", await abandonLifecycle(binary, cli, root));
+		} catch (error) {
+			fail("audited abandon end-to-end (v2 discarded-work binding)", knownRedParity(describeError(error)));
+		}
+
+		try {
+			pass("external native recover to captured successor lens", await recoveredSuccessorLifecycle(binary, cli, root));
+		} catch (error) {
+			fail("external native recover to captured successor lens", knownRedParity(describeError(error)));
+		}
+
+		try {
+			pass("recovered field flow: linked dirty worktree, finalize-first dispatch", await recoveredSuccessorFieldFlow(binary, cli, root));
+		} catch (error) {
+			fail("recovered field flow: linked dirty worktree, finalize-first dispatch", knownRedParity(describeError(error)));
+		}
+
+		try {
+			pass("relay materialize slot on an externally recovered lineage", await relayMaterializeSlotLifecycle(binary, cli, root));
+		} catch (error) {
+			fail("relay materialize slot on an externally recovered lineage", knownRedParity(describeError(error)));
+		}
+
+		try {
+			pass("corrected lifecycle through the adapter to an approved receipt", await correctedLifecycleThroughAdapter(binary, root));
+		} catch (error) {
+			fail("corrected lifecycle through the adapter to an approved receipt", knownRedParity(describeError(error)));
+		}
+
+		if (WITH_MODEL && mediumRepo !== undefined) {
+			try {
+				pass("medium reviewer model run (pi)", await modelReview(binary, cli, mediumRepo));
+			} catch (error) {
+				fail("medium reviewer model run (pi)", describeError(error));
+			}
+		} else {
+			skip("medium reviewer model run (pi)", "pass --with-model to run the Go-owned pi reviewer (model spend)");
+		}
+
+		decoderFreshness(binary);
+	} finally {
+		removeScratchRoot(root);
+	}
+
+	const nameWidth = Math.max(...checks.map((check) => check.name.length), "check".length);
+	console.log("");
+	console.log(`${"check".padEnd(nameWidth)}  status  note`);
+	let failed = 0;
+	for (const check of checks) {
+		console.log(`${check.name.padEnd(nameWidth)}  ${check.status.padEnd(6)}  ${check.note}`);
+		if (check.status === "FAIL") failed += 1;
+	}
+	console.log("");
+	console.log(`total: ${checks.length} checks, ${failed} failed`);
+	if (failed > 0) process.exitCode = 1;
+}
+
+await main();