immune-brain 5.1.0 → 5.1.1

package/plugins/immune-brain/runtime/kernel/canary_application.ts

@@ -26,7 +26,7 @@ import {
 	type BackendClaim,
 } from "./backend_claim";
 import { canonicalIntentHash } from "./intent";
-import { boundSpecPath, readBoundActiveSpec } from "./spec_binding";
+import { assertValidSpecBinding, boundSpecPath, readBoundActiveSpec } from "./spec_binding";
 import { parseTaskRecord } from "./validation";
 import type { TaskIntentIdentityToken } from "./intent_token_registry";
 import {
@@ -208,6 +208,7 @@ export function createCanaryApplication(
 			const current = readTaskRecordRaw(input.root, input.task_id);
 			if (!current.record)
 				throw new KernelInvariantError([`task ${input.task_id} has no TaskRecord v3`]);
+			assertValidSpecBinding(current.record.intent_snapshot);
 			const workspace = readWorkspaceStateRaw(input.root);
 			if (current.record.artifact_state === "frozen")
 				return { revision: current.revision, record: current.record, workspace };
@@ -318,7 +319,13 @@ export function createCanaryApplication(
 		const diffHash = asTaskDiffSnapshot((input.diffProvider ?? taskDeliveryIdentity)(input.root, snapshot.record)).diff_hash;
 		if (operation.op === "stop" && !("capability" in operation))
 			throw new KernelInvariantError(["stop requires user authority capability"]);
-		const hasBoundSpec = boundSpecPath(snapshot.intent_snapshot) !== undefined;
+		// Only a capability-bound breaking revision may recover an invalid prior
+		// binding. Validate the replacement before any authority write.
+		if (operation.op === "approve_breaking_intent_revision") assertValidSpecBinding(operation.next_intent);
+		else assertValidSpecBinding(snapshot.intent_snapshot);
+		const hasBoundSpec = operation.op === "approve_breaking_intent_revision"
+			? boundSpecPath(operation.next_intent) !== undefined
+			: boundSpecPath(snapshot.intent_snapshot) !== undefined;
 		if (operation.op === "complete" && hasBoundSpec && snapshot.record.artifact_state !== "frozen")
 			throw new KernelInvariantError(["complete requires frozen planning artifacts"]);
 		const artifactTransition =

package/plugins/immune-brain/runtime/kernel/completion.ts

@@ -1,5 +1,5 @@
 import { classifyTaskRisk } from "./intent";
-import { archivePath, boundSpecPath } from "./spec_binding";
+import { archivePath, boundSpecPath, inspectSpecBinding } from "./spec_binding";
 import type {
 	ApprovalKind,
 	CompletionDecision,
@@ -49,6 +49,8 @@ export function resolveProjectedRisk(
 	intent: TaskIntentV1,
 	changedPaths: readonly string[] = [],
 ): TaskIntentV1["risk"] {
+	// Invalid bindings have no trusted planning-path exclusions.
+	if (!inspectSpecBinding(intent).ok) return classifyTaskRisk(changedPaths, intent.risk);
 	const excluded = ownSidecarPaths(intent);
 	return classifyTaskRisk(
 		changedPaths.filter((path) => !excluded.has(path)),
@@ -182,6 +184,27 @@ export function projectTask(
 	currentIntentContentHash: string,
 	changedPaths: readonly string[] = [],
 ): TaskProjectionV3 {
+	if (record.lifecycle === "active" && !inspectSpecBinding(intent).ok) {
+		assertKernelInvariantsV3(intent, record);
+		return {
+			contract: "assurance_kernel/projection/v3",
+			task_id: record.task_id,
+			intent_revision: intent.revision,
+			lifecycle: record.lifecycle,
+			artifact_state: record.artifact_state,
+			blocked: true,
+			next_obligation: "revise_intent",
+			complete: false,
+			fresh_acceptance_ids: [],
+			missing_acceptance_ids: intent.acceptance.map((item) => item.id),
+			stale_attestation_ids: record.attestations.map((item) => item.id),
+			missing_approval_kinds: REQUIRED_ATTESTATIONS[resolveProjectedRisk(intent, changedPaths)],
+			blocking_finding_ids: record.findings.filter((item) => item.kind === "blocking" && item.status !== "resolved").map((item) => item.id),
+			unresolved_user_decision_ids: record.findings.filter((item) => item.kind === "unresolved_user_decision" && item.status === "open").map((item) => item.id),
+			replan_required_ids: record.findings.filter((item) => item.kind === "replan_required" && item.status === "open").map((item) => item.id),
+			independence_violations: [],
+		};
+	}
 	const decision = completionDecision(
 		intent,
 		record,

package/plugins/immune-brain/runtime/kernel/reducer.ts

@@ -23,6 +23,7 @@ import {
 	parseTaskRecord,
 } from "./validation";
 import { classifyIntentRevision, canonicalIntentHash } from "./intent";
+import { assertValidSpecBinding } from "./spec_binding";
 
 const RISK_RANK: Record<TaskIntentV1["risk"], number> = {
 	routine: 0,
@@ -431,15 +432,24 @@ export function reduceTask(
 			const reviewRevision = approval.review_revision;
 			if (reviewRevision && approval.kind !== "review")
 				throw new KernelInvariantError(["review_revision is only valid on review approvals"]);
+			if (approval.reviewer_verdict_sha256 && approval.kind !== "review")
+				throw new KernelInvariantError(["reviewer_verdict_sha256 is only valid on review approvals"]);
 			if (approval.kind === "review") {
 				if (!reviewRevision)
 					throw new KernelInvariantError(["v4 review approval requires review_revision"]);
 				if (reviewRevision.base_head !== record.git_base_head)
 					throw new KernelInvariantError(["review_revision.base_head must equal the Enrollment git_base_head"]);
 			}
-			const { review_revision: storedReviewRevision, ...approvalWithoutRevision } = approval;
+				// Re-emit the optional review-only fields in the strict parser's emission
+			// order so a written attestation stays byte-identical to its parse roundtrip.
+			const {
+				review_revision: storedReviewRevision,
+				advisory_findings: storedAdvisoryFindings,
+				reviewer_verdict_sha256: storedReviewerDigest,
+				...approvalWithoutExtras
+			} = approval;
 			record.attestations.push({
-				...approvalWithoutRevision,
+				...approvalWithoutExtras,
 				acceptance_results: approval.kind === "qa"
 					? record.intent_snapshot.acceptance.map((item) => ({
 						acceptance_id: item.id,
@@ -448,12 +458,15 @@ export function reduceTask(
 					}))
 					: [],
 				...(storedReviewRevision ? { review_revision: storedReviewRevision } : {}),
+				...(storedAdvisoryFindings ? { advisory_findings: storedAdvisoryFindings } : {}),
+				...(storedReviewerDigest ? { reviewer_verdict_sha256: storedReviewerDigest } : {}),
 			});
 			appendHistory(record, action, from, approval.id, authorityAudit);
 			break;
 		}
 		case "revise_intent":
 		case "approve_breaking_intent_revision": {
+			assertValidSpecBinding(action.next_intent);
 			if (record.lifecycle !== "active")
 				throw new KernelInvariantError([
 					`cannot revise intent while lifecycle is ${record.lifecycle}`,

package/plugins/immune-brain/runtime/kernel/spec_binding.ts

@@ -57,6 +57,12 @@ export function readBoundActiveSpec(
 	}
 }
 
+/** Validate a candidate before it can replace enrolled authority. */
+export function assertValidSpecBinding(intent: TaskIntentV1): void {
+	const binding = inspectSpecBinding(intent);
+	if (!binding.ok) throw new KernelInvariantError([binding.message]);
+}
+
 export interface BoundSpec {
 	active: string;
 	archive: string;

package/plugins/immune-brain/runtime/kernel/storage.ts

@@ -53,6 +53,7 @@ import {
 	FILE_STORE_CLAIM_RELATIVE,
 	FILE_STORE_TRANSACTIONS_RELATIVE,
 	FILE_STORE_WORKSPACE_RELATIVE,
+	inspectRetiredStateResidue,
 	stateDatabasePath,
 } from "./storage_paths";
 import { canonicalRecordHash } from "./reducer";
@@ -262,7 +263,7 @@ function isRetiredFileProvablySuperseded(
 /**
  * Refuse mutation while the retired `.imm/state/*.json` file store (or the
  * pre-cutover `.imm/tasks` layout) still holds authority. The check is bounded
- * to `existsSync` paths so it can run on every locked mutation.
+ * to retired paths so it can run on every locked mutation.
  */
 function assertNoRetiredFileStore(
 	root: string,
@@ -270,11 +271,19 @@ function assertNoRetiredFileStore(
 	taskId?: string | null,
 ): void {
 	const canonical = canonicalRoot(root);
+	let residue: ReturnType<typeof inspectRetiredStateResidue>;
+	try {
+		residue = inspectRetiredStateResidue(canonical);
+	} catch (error) {
+		throw new KernelStoreSecurityError(
+			`retired file-store residue is invalid: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
 	// Real authority in the retired store: must be imported, never ignored.
 	const retired: Array<[string, string]> = [
 		[".imm/tasks", "pre-cutover task store"],
 		[".imm/workspace.json", "pre-cutover workspace owner"],
-		[".imm/state/tasks", "task records"],
+		...(residue.task_entries.length > 0 ? [[".imm/state/tasks", "task records"] as [string, string]] : []),
 	];
 	for (const [path, label] of retired) {
 		if (existsSync(resolve(canonical, path)))
@@ -293,6 +302,7 @@ function assertNoRetiredFileStore(
 	];
 	for (const [path, label] of derived) {
 		const full = resolve(canonical, path);
+		if (path === FILE_STORE_WORKSPACE_RELATIVE && residue.workspace_owner === null) continue;
 		if (!existsSync(full)) continue;
 		if (db === undefined || typeof taskId !== "string" || taskId.length === 0)
 			throw new KernelStoreSecurityError(
@@ -325,10 +335,16 @@ function retiredFileStoreConflict(
 	taskId: string | null,
 ): string | null {
 	const canonical = canonicalRoot(root);
+	let residue: ReturnType<typeof inspectRetiredStateResidue>;
+	try {
+		residue = inspectRetiredStateResidue(canonical);
+	} catch (error) {
+		return `retired file-store residue is invalid: ${error instanceof Error ? error.message : String(error)}`;
+	}
 	const authority: Array<[string, string]> = [
 		[".imm/tasks", "pre-cutover task store"],
 		[".imm/workspace.json", "pre-cutover workspace owner"],
-		[".imm/state/tasks", "task records"],
+		...(residue.task_entries.length > 0 ? [[".imm/state/tasks", "task records"] as [string, string]] : []),
 	];
 	for (const [path, label] of authority)
 		if (existsSync(resolve(canonical, path)))
@@ -340,7 +356,7 @@ function retiredFileStoreConflict(
 			[FILE_STORE_WORKSPACE_RELATIVE, "workspace owner"],
 		];
 		for (const [path, label] of derived)
-			if (existsSync(resolve(canonical, path)))
+			if ((path !== FILE_STORE_WORKSPACE_RELATIVE || residue.workspace_owner !== null) && existsSync(resolve(canonical, path)))
 				return `retired file-store authority is present (${label}: ${path}); import it with the supported migration before mutating this worktree`;
 	}
 	const transactions = resolve(canonical, FILE_STORE_TRANSACTIONS_RELATIVE);

package/plugins/immune-brain/runtime/kernel/storage_paths.ts

@@ -382,6 +382,36 @@ function readSmallFile(root: string, relativePath: string): string | null {
 	}
 }
 
+/** Shared, bounded classification of the two potentially inert retired paths. */
+export function inspectRetiredStateResidue(root: string): {
+	task_entries: string[];
+	workspace_owner: string | null;
+} {
+	const tasksStatus = entryStatus(root, FILE_STORE_TASKS_RELATIVE);
+	if (tasksStatus !== "absent" && tasksStatus !== "directory")
+		throw new Error(`${FILE_STORE_TASKS_RELATIVE} is not a regular directory`);
+	const entries = tasksStatus === "absent" ? [] : listEntries(root, FILE_STORE_TASKS_RELATIVE);
+	if (entries === null) throw new Error(`${FILE_STORE_TASKS_RELATIVE} is unreadable`);
+	const workspaceStatus = entryStatus(root, FILE_STORE_WORKSPACE_RELATIVE);
+	let owner: string | null = null;
+	if (workspaceStatus !== "absent") {
+		if (workspaceStatus !== "file")
+			throw new Error(`${FILE_STORE_WORKSPACE_RELATIVE} is not a regular file`);
+		const content = readSmallFile(root, FILE_STORE_WORKSPACE_RELATIVE);
+		if (content === null) throw new Error(`${FILE_STORE_WORKSPACE_RELATIVE} is unreadable`);
+		const raw = JSON.parse(content);
+		if (
+			raw === null || typeof raw !== "object" || Array.isArray(raw) ||
+			raw.contract !== "assurance_kernel/workspace/v1" ||
+			(raw.current_working !== null &&
+				(typeof raw.current_working !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(raw.current_working))) ||
+			(raw.current_working === null && Object.keys(raw).some((key) => !["contract", "current_working"].includes(key)))
+		) throw new Error(`${FILE_STORE_WORKSPACE_RELATIVE} has invalid workspace content`);
+		owner = raw.current_working;
+	}
+	return { task_entries: entries, workspace_owner: owner };
+}
+
 interface OldLayoutFacts {
 	old_authority_present: boolean;
 	blocked_active: boolean;
@@ -637,6 +667,7 @@ function inspectFileStoreLayout(root: string): FileStoreFacts {
 		if (stateStatus === "symlink" || stateStatus === "other")
 			throw new Error(`${STATE_RELATIVE} is ${stateStatus}`);
 		if (stateStatus !== "directory") return facts;
+		const residue = inspectRetiredStateResidue(root);
 		for (const entry of listEntries(root, STATE_RELATIVE) ?? []) {
 			const full = `${STATE_RELATIVE}/${entry}`;
 			const status = entryStatus(root, full);
@@ -667,13 +698,12 @@ function inspectFileStoreLayout(root: string): FileStoreFacts {
 				continue;
 			}
 			if (full === FILE_STORE_WORKSPACE_RELATIVE) {
-				const owner = readJsonField(root, full, "current_working");
-				if (typeof owner === "string" && owner.length > 0) facts.blocked_active = true;
+				if (residue.workspace_owner !== null) facts.blocked_active = true;
 				continue;
 			}
 			throw new Error(`unknown file under ${STATE_RELATIVE}: ${entry}`);
 		}
-		for (const entry of listEntries(root, FILE_STORE_TASKS_RELATIVE) ?? []) {
+		for (const entry of residue.task_entries) {
 			const full = `${FILE_STORE_TASKS_RELATIVE}/${entry}`;
 			const status = entryStatus(root, full);
 			if (status === "symlink" || status === "other")

package/plugins/immune-brain/runtime/kernel/types.ts

@@ -187,6 +187,13 @@ export interface TaskApprovalV2 {
 	review_revision?: ReviewRevisionIdentityV1;
 	/** Legal only on a review attestation, alongside its revision identity. */
 	advisory_findings?: ReviewAdvisoryFindingV1[];
+	/**
+	 * ADR 0017: sha256 over the reviewer's own result bytes as observed by the
+	 * host, bound at submission so post-hoc audit can prove the persisted
+	 * verdict equals what the reviewer produced. Legal only on a review
+	 * attestation; emitted only when present so legacy records stay stable.
+	 */
+	reviewer_verdict_sha256?: string;
 }
 
 export interface ReviewRevisionIdentityV1 {

package/plugins/immune-brain/runtime/kernel/validation.ts

@@ -314,7 +314,7 @@ export function parseApprovalV2(
 	const item = objectAt(value, `record.approvals[${index}]`, violations);
 	rejectUnknown(
 		item,
-		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary", "advisory_findings",
+		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary", "advisory_findings", "reviewer_verdict_sha256",
 			...(allowReviewRevision ? ["review_revision"] : [])],
 		`record.approvals[${index}]`,
 		violations,
@@ -365,6 +365,9 @@ export function parseApprovalV2(
 					),
 				}
 			: {}),
+		...(item.reviewer_verdict_sha256 !== undefined
+			? { reviewer_verdict_sha256: stringAt(item.reviewer_verdict_sha256, `record.approvals[${index}].reviewer_verdict_sha256`, violations) }
+			: {}),
 	};
 }
 
@@ -419,7 +422,7 @@ function parseAttestationV3(
 	const item = objectAt(value, path, violations);
 	rejectUnknown(
 		item,
-		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary", "acceptance_results", "advisory_findings",
+		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary", "acceptance_results", "advisory_findings", "reviewer_verdict_sha256",
 			...(allowReviewRevision ? ["review_revision"] : [])],
 		path,
 		violations,
@@ -462,6 +465,13 @@ function parseAttestationV3(
 			);
 	if (advisoryFindings !== undefined && kind !== "review")
 		violations.push(`${path}.advisory_findings is only valid on review attestations`);
+	const reviewerVerdictSha256 = item.reviewer_verdict_sha256 === undefined
+		? undefined
+		: stringAt(item.reviewer_verdict_sha256, `${path}.reviewer_verdict_sha256`, violations);
+	if (reviewerVerdictSha256 !== undefined && kind !== "review")
+		violations.push(`${path}.reviewer_verdict_sha256 is only valid on review attestations`);
+	if (reviewerVerdictSha256 !== undefined && !SHA256_HEX.test(reviewerVerdictSha256))
+		violations.push(`${path}.reviewer_verdict_sha256 must be sha256:<64 hex>`);
 	return {
 		id: stringAt(item.id, `${path}.id`, violations),
 		kind,
@@ -474,6 +484,7 @@ function parseAttestationV3(
 		acceptance_results: acceptanceResults,
 		...(reviewRevision ? { review_revision: reviewRevision } : {}),
 		...(advisoryFindings !== undefined ? { advisory_findings: advisoryFindings } : {}),
+		...(reviewerVerdictSha256 !== undefined ? { reviewer_verdict_sha256: reviewerVerdictSha256 } : {}),
 	};
 }
 

package/plugins/immune-brain/runtime/plugin_version.ts

@@ -1,2 +1,2 @@
 // Generated by scripts/plugin_versioning.ts from the root package.json.
-export const PLUGIN_VERSION = "5.1.0" as const;
+export const PLUGIN_VERSION = "5.1.1" as const;

package/plugins/immune-brain/runtime/prompts/code-review.md

@@ -53,6 +53,16 @@ seam, or a seam silently replaced by a different one, is a finding carrying
 named, its absence is not a finding: candidates written before this rule carries
 no defect for lacking one.
 
+Before pass, enumerate the immutable change set and read each complete per-file
+diff, including deletions. Page bounded reads until every hunk is visible; a
+truncated aggregate output or summary is incomplete coverage. Trace changed
+high-risk behavior through its callers and state owner, and inspect a concrete
+negative case against the embedded acceptance. If immutable evidence remains
+unavailable or incomplete, report the concrete acceptance coverage gap in a
+rework finding with required evidence. `inspected_paths` declares coverage; it
+does not itself prove tool reading. Judge quality by evidence, not elapsed time
+or tool-call count.
+
 A required check that is skipped, that matches zero tests, or whose prerequisite
 is absent does not prove the acceptance; do not accept it as evidence. Full
 suite coverage reported at a coarse pass count is not per-invariant evidence.

package/plugins/immune-brain/runtime/role_prompt_bridge.ts

@@ -233,5 +233,5 @@ export const STATIC_REVIEW_RULES = [
  * to a per-dispatch prompt, because they describe the dispatch itself.
  */
 export const REVIEWER_DISPATCH_RULES = [
-	"A dispatched reviewer is never continued or re-prompted, including through SendMessage. The reserved prompt is dispatched verbatim. A blocked `submit_review` is recovered only through its returned `recovery_action`.",
+	"A dispatched reviewer is never continued or re-prompted, including through SendMessage. The reserved prompt is dispatched verbatim. The host binds this reviewer's final result bytes to the reservation, so a Parent may submit them without transcribing them. A blocked `submit_review` is recovered only through its returned `recovery_action`.",
 ] as const;

package/plugins/immune-brain/runtime/unattended/batch_disposition.ts

@@ -0,0 +1,222 @@
+// Authority-backed disposition for a batch the plan moved past.
+//
+// A batch whose plan changed can neither reconfirm (reconfirmation is eligible
+// only with zero recorded commits) nor continue (its authorization cannot
+// execute the revised plan). Before this module the only exits were editing or
+// deleting the state file by hand, which destroyed the evidence of what the
+// batch had actually delivered — exactly what happened to the batch retired
+// during the parallel-lane Initiative, whose record is no longer on disk.
+//
+// Retiring is one explicit literal-user decision. It writes the record to the
+// terminal `superseded` state under the Kernel store lock, preserves every
+// child state, commit and the batch branch, and grants no handoff: children
+// this batch never executed carry no commit, no batch trailer and no approval,
+// and nothing here infers their delivery from a retired record. The old
+// authorization is never reused for the revised plan; a later batch starts
+// under its own fresh authorization.
+//
+// Authority shape, deliberately: the literal-user native confirmation plus a
+// locked expected-byte check that the record did not move while the gate was
+// open. No Batch Authorization capability is minted, because retiring a record
+// consumes no child and enrolls nothing — the capability exists to authorize
+// child consumption, and minting one here would be ceremony without a property.
+import { readSecureProjectBytes } from "../kernel/storage";
+import { batchStatePath } from "../kernel/storage_paths";
+import { batchReason, type BatchReason } from "./batch_reasons";
+import { findExistingActiveBatch, findSettledBatchRecord, type BatchGateDecision } from "./batch_preflight";
+import {
+	isTerminalBatchState,
+	replaceAnyBatchRunState,
+	writeBatchRunReport,
+	type AnyBatchRunStateRecord,
+	type BatchLaneRunReport,
+	type BatchRunReport,
+	type BatchRunState,
+} from "./batch_state";
+
+/** Child states whose Kernel run is still live; a live run settles on its own. */
+const SERIAL_IN_FLIGHT: ReadonlySet<string> = new Set(["enrolled", "settled"]);
+const LANE_IN_FLIGHT: ReadonlySet<string> = new Set(["lane_admitted", "enrolled", "settled", "lane_committed"]);
+
+/** Evidence-only child projection for the gate; never an execution readiness. */
+export interface StaleBatchChildEvidence {
+	task_id: string;
+	slice_id: string;
+	state: string;
+	commit: string | null;
+	lane_branch: string | null;
+}
+
+/** The exact record identity the literal user is asked to retire. */
+export interface StaleBatchFacts {
+	batch_id: string;
+	initiative_slug: string;
+	batch_state: BatchRunState;
+	plan_digest: string;
+	branch: string;
+	base_head: string;
+	confirmation_time: string;
+	/** Commits this batch itself produced, in child order. */
+	recorded_commits: string[];
+	children: StaleBatchChildEvidence[];
+}
+
+export type StaleBatchLookup =
+	/** No active record for this Initiative. */
+	| { kind: "none" }
+	| { kind: "corrupt"; path: string }
+	| { kind: "terminal"; batch_id: string }
+	| { kind: "in_flight"; batch_id: string; task_id: string }
+	| { kind: "retirable"; record: AnyBatchRunStateRecord; facts: StaleBatchFacts };
+
+const RETIRE_REASON =
+	"Retired by an explicit literal-user disposition: the batch plan moved past this record, so its authorization could neither reconfirm nor continue. " +
+	"Recorded child commits, child states and the batch branch are preserved as evidence. " +
+	"Children this batch never executed carry no commit, no batch trailer and no approval; nothing infers their delivery from this record.";
+
+const RETIRE_NEXT_ACTION =
+	"The Initiative has no active batch. Run each remaining child with imm-run under its own authorization, or start a new batch for this Initiative after checking out its batch branch.";
+
+function childEvidenceOf(record: AnyBatchRunStateRecord): StaleBatchChildEvidence[] {
+	if (record.contract === "assurance_kernel/batch_run_state/v2")
+		return record.children.map((child) => ({
+			task_id: child.task_id,
+			slice_id: child.slice_id,
+			state: child.state,
+			commit: child.commit,
+			lane_branch: child.lane?.branch ?? null,
+		}));
+	return record.children.map((child) => ({
+		task_id: child.task_id,
+		slice_id: child.slice_id,
+		state: child.state,
+		commit: child.commit,
+		lane_branch: null,
+	}));
+}
+
+function inFlightChildOf(record: AnyBatchRunStateRecord): { task_id: string } | null {
+	const inFlight = record.contract === "assurance_kernel/batch_run_state/v2" ? LANE_IN_FLIGHT : SERIAL_IN_FLIGHT;
+	return record.children.find((child) => inFlight.has(child.state)) ?? null;
+}
+
+/**
+ * The Initiative's active batch record as retirement evidence, or why it cannot
+ * be retired. Read-only; a terminal record is not a batch to dispose.
+ */
+export function readStaleBatchLookup(root: string, initiativeSlug: string): StaleBatchLookup {
+	const found = findExistingActiveBatch(root, initiativeSlug);
+	if (found === null) {
+		const settled = findSettledBatchRecord(root, initiativeSlug);
+		if (settled) return { kind: "terminal", batch_id: settled.batch_id };
+		return { kind: "none" };
+	}
+	if (found.corrupt) return { kind: "corrupt", path: found.path };
+	const record = found.record;
+	if (isTerminalBatchState(record.batch_state)) return { kind: "terminal", batch_id: record.batch_id };
+	const inFlight = inFlightChildOf(record);
+	if (inFlight) return { kind: "in_flight", batch_id: record.batch_id, task_id: inFlight.task_id };
+	return {
+		kind: "retirable",
+		record,
+		facts: {
+			batch_id: record.batch_id,
+			initiative_slug: record.initiative_slug,
+			batch_state: record.batch_state,
+			plan_digest: record.plan_digest,
+			branch: record.branch ?? `imm/${record.initiative_slug}`,
+			base_head: record.base_head,
+			confirmation_time: record.confirmation_time,
+			recorded_commits: [...record.commits],
+			children: childEvidenceOf(record),
+		},
+	};
+}
+
+export type RetireStaleBatchOutcome<HostRejection> =
+	| {
+			outcome: "retired";
+			batch_id: string;
+			record: AnyBatchRunStateRecord;
+			report: BatchRunReport | BatchLaneRunReport;
+	  }
+	| { outcome: "rejected"; rejection: BatchReason }
+	| { outcome: "host_rejection"; value: HostRejection };
+
+/**
+ * Retire one Initiative's active batch record after a literal-user gate. The
+ * gate receives the record's own evidence; a declined, cancelled or failed
+ * interaction writes nothing. Between the gate and the write the record is
+ * re-read and must be byte-identical, so a record that moved while the gate was
+ * open is never retired under a stale decision.
+ */
+export async function retireStaleBatch<HostRejection>(options: {
+	root: string;
+	initiative_slug: string;
+	now: string;
+	gate: (facts: StaleBatchFacts) => Promise<BatchGateDecision<HostRejection>>;
+}): Promise<RetireStaleBatchOutcome<HostRejection>> {
+	const { root, initiative_slug: initiativeSlug, now } = options;
+	const lookup = readStaleBatchLookup(root, initiativeSlug);
+	if (lookup.kind === "none")
+		return { outcome: "rejected", rejection: batchReason("stale_batch_absent", `Initiative ${initiativeSlug} has no active batch`) };
+	if (lookup.kind === "corrupt")
+		return { outcome: "rejected", rejection: batchReason("batch_state_unreadable", lookup.path) };
+	if (lookup.kind === "terminal")
+		return {
+			outcome: "rejected",
+			rejection: batchReason("stale_batch_absent", `batch ${lookup.batch_id} already reached a terminal state`),
+		};
+	if (lookup.kind === "in_flight")
+		return {
+			outcome: "rejected",
+			rejection: batchReason("stale_batch_in_flight", `batch ${lookup.batch_id}, child ${lookup.task_id}`),
+		};
+
+	const { record, facts } = lookup;
+	const expected = readSecureProjectBytes(root, batchStatePath(record.batch_id));
+	const decision = await options.gate(facts);
+	if (decision.kind === "host_rejection") return { outcome: "host_rejection", value: decision.value };
+	// A decline or a cancel is the Host's own envelope (batchReason
+	// confirmation_declined / confirmation_cancelled), so it arrives here as a
+	// host_rejection: nothing is written and the record stays parked.
+
+	// Confirmation cannot adopt a record that moved while the gate was open.
+	if (!readSecureProjectBytes(root, batchStatePath(record.batch_id)).equals(expected))
+		return { outcome: "rejected", rejection: batchReason("plan_changed", record.batch_id) };
+
+	// Children, commits and branch are carried over untouched: the disposition
+	// records what the batch did and did not do, and invents neither.
+	const retired: AnyBatchRunStateRecord = { ...record, batch_state: "superseded" };
+	const stored = replaceAnyBatchRunState(root, expected, retired, () => {
+		if (!readSecureProjectBytes(root, batchStatePath(record.batch_id)).equals(expected))
+			throw new Error("batch state changed before the disposition was applied");
+	});
+	const report =
+		stored.contract === "assurance_kernel/batch_run_state/v2"
+			? writeBatchRunReport(root, {
+					contract: "assurance_kernel/batch_run_report/v1",
+					batch_id: stored.batch_id,
+					initiative_slug: stored.initiative_slug,
+					batch_state: stored.batch_state,
+					max_parallel: stored.max_parallel,
+					children: stored.children,
+					commits: stored.commits,
+					reason: RETIRE_REASON,
+					handoffs: [],
+					next_action: RETIRE_NEXT_ACTION,
+					created_at: now,
+				} satisfies BatchLaneRunReport)
+			: writeBatchRunReport(root, {
+					contract: "assurance_kernel/batch_run_report/v1",
+					batch_id: stored.batch_id,
+					initiative_slug: stored.initiative_slug,
+					batch_state: stored.batch_state,
+					children: stored.children,
+					commits: stored.commits,
+					reason: RETIRE_REASON,
+					next_action: RETIRE_NEXT_ACTION,
+					created_at: now,
+				} satisfies BatchRunReport);
+	return { outcome: "retired", batch_id: stored.batch_id, record: stored, report };
+}