immune-brain 5.1.0 → 5.1.2

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.2" as const;

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

@@ -34,6 +34,13 @@ about the fix's scope, not a new bug. A trigger the accepted contract explicitly
 excludes is reported as an advisory note against that boundary, never as blocking
 rework.
 
+A defect that lies inside the TaskIntent goal and `scope_hint` is a blocking
+finding even when no acceptance assertion names its exact case word for word:
+cite the acceptance whose principle it violates as `acceptance_id` and
+`violated.ref`. Ask for the fix and a test that pins the case, never for the case
+to be written into the acceptance text; a missing literal clause is not itself a
+finding and does not call for an Intent revision.
+
 ## Invariant and Evidence Coverage
 
 Judge whether the change actually closes the invariant its acceptance names,
@@ -53,6 +60,24 @@ 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.
 
+When the Spec referenced by an acceptance maps an `automated` user scenario to
+it, check that the delivered tests at that acceptance's agreed seam assert the
+scenario's `Then`: a scenario whose observable result is asserted nowhere is a
+finding carrying `violated.kind` of `acceptance` with `ref` the acceptance id.
+A `manual` scenario, and an acceptance with no mapped scenario, produce no such
+finding. This adds no finding kind and no verdict branch: it is the same
+`acceptance` finding the seam rule above already defines.
+
+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/prompts/executor.md

@@ -54,6 +54,13 @@ Record missing evidence as blocked and repair it before handoff. The Loop owns
 verdict submission, finding disposition and the second-rework generalize-or-refute
 rule.
 
+A finding whose defect lies inside the TaskIntent goal and `scope_hint` is
+ordinary rework even when no acceptance names its exact case: fix the code and
+add the test that pins the case. Do not propose an Intent revision for it, and
+never append a single input case to an acceptance assertion to close a finding;
+acceptance states principles, tests enumerate cases. Route to `imm-planner` only
+when the goal, the scope, or a user-visible commitment must change.
+
 ## Code Quality Guard
 
 Before handoff, check the implementation for real implementation rather than

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_delegation.ts

@@ -0,0 +1,160 @@
+// Delegated in-Lane Intent revision (ADR 0018). A lane batch whose literal-user
+// confirmation granted `revision_delegation` lets the coordinator approve a
+// Lane child's breaking Intent revision that stays inside the child's TaskIntent
+// as authorized for the batch. The approval is the ordinary Kernel
+// `approve_breaking_intent_revision`, applied in the Lane's own Authority Store
+// with user authority whose actor and confirmation reference name the batch, so
+// the audit history tells it apart from an approval by the user in person.
+// Out-of-bounds revisions are refused here and stay with the user's own gate.
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { writeFileSync } from "node:fs";
+import { projectAssurance } from "../kernel/assurance_projection";
+import { createMutationAuthorityRegistry, digestOfAction, type CapabilityBindingV2 } from "../kernel/authority_port";
+import { capabilityActionFor, createCanaryApplication } from "../kernel/canary_application";
+import { canonicalIntentHash, classifyIntentRevision, parseTaskIntentV1, readTaskIntent } from "../kernel/intent";
+import { boundSpecPath } from "../kernel/spec_binding";
+import { readTaskRecordRaw, recoverKernelStoreFollowUps } from "../kernel/storage";
+import type { TaskIntentV1 } from "../kernel/types";
+import { stagePlanningArtifactTransition } from "../assurance/verdict_authority";
+import { captureStagedIntent, restoreStagedIntent } from "../staged_intent";
+import { taskDeliveryIdentity } from "../workspace_scope";
+
+/** The grant and its bounds, stated in the gate that grants it (both Hosts). */
+export const REVISION_DELEGATION_TEXT =
+	"Optional, off by default: also let the batch coordinator approve a Lane child's breaking Intent revisions that stay inside that child's authorized TaskIntent (acceptance changes, a narrower scope_hint). Widening scope, changing risk, goal or the bound Spec still needs your own confirmation. The grant ends with this batch.";
+
+/** The actor every delegated approval records; never the literal user. */
+export const DELEGATED_ACTOR_ID = "batch-coordinator";
+
+export interface RevisionDelegationGrant {
+	/** The confirmation that granted it; a fresh confirmation replaces it. */
+	confirmation_time: string;
+}
+
+export interface DelegatedRevisionRecord {
+	at: string;
+	task_id: string;
+	from_revision: number;
+	to_revision: number;
+	intent_content_hash: string;
+	confirmation_ref: string;
+}
+
+export interface LaneRevisionRequest {
+	task_id: string;
+	next_intent: TaskIntentV1;
+}
+
+/** The confirmation reference that traces a delegated approval to its batch authorization. */
+export function delegatedConfirmationRef(batchId: string, grant: RevisionDelegationGrant): string {
+	return `delegated-batch:${batchId}@${grant.confirmation_time}`;
+}
+
+/** Untrusted tool input: shape only; the bounds are decided against Kernel facts. */
+export function parseLaneRevision(value: unknown): LaneRevisionRequest | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "object" || Array.isArray(value)) throw new Error("invalid lane_revision: expected an object");
+	const { task_id: taskId, next_intent: nextIntent, ...rest } = value as Record<string, unknown>;
+	if (Object.keys(rest).length > 0) throw new Error("invalid lane_revision: unknown field");
+	if (typeof taskId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(taskId))
+		throw new Error("invalid lane_revision: task_id is not a valid task id");
+	const intent = parseTaskIntentV1(nextIntent);
+	if (intent.task_id !== taskId) throw new Error("invalid lane_revision: next_intent belongs to another task");
+	return { task_id: taskId, next_intent: intent };
+}
+
+/**
+ * Whether the delegation covers this revision. `authorized` is the child's
+ * TaskIntent as the batch authorized it; `current` is the Lane's enrolled one.
+ * Null means covered.
+ */
+export function delegatedRevisionRefusal(authorized: TaskIntentV1, current: TaskIntentV1, next: TaskIntentV1): string | null {
+	if (classifyIntentRevision(current, next) !== "breaking") return "only a breaking revision needs this approval; apply a compatible one with revise_intent";
+	if (next.revision <= current.revision) return "the revision number must increase";
+	if (next.goal !== authorized.goal || next.owner !== authorized.owner || next.task_id !== authorized.task_id)
+		return "goal, owner and task identity are outside the delegation";
+	if (next.risk !== authorized.risk || next.risk !== current.risk) return "a risk change is outside the delegation";
+	if ((boundSpecPath(next) ?? null) !== (boundSpecPath(authorized) ?? null)) return "a change of the bound Spec is outside the delegation";
+	const allowed = new Set(authorized.scope_hint);
+	const widened = next.scope_hint.filter((entry) => !allowed.has(entry));
+	if (widened.length > 0) return `widening scope_hint is outside the delegation: ${widened.join(", ")}`;
+	return null;
+}
+
+/**
+ * Apply one delegated breaking revision in the Lane, exactly as a Host applies
+ * an approved one: write and stage the next sidecar, re-read the projection,
+ * issue a user capability bound to that snapshot, execute, and stage the
+ * planning transition. The prior sidecar bytes and index entry come back on any
+ * failure before commit.
+ */
+export function applyDelegatedIntentRevision(input: {
+	lane_root: string;
+	task_id: string;
+	next_intent: TaskIntentV1;
+	confirmation_ref: string;
+	now: string;
+}): Promise<{ from_revision: number; to_revision: number; intent_content_hash: string }> {
+	return (async () => {
+		const { lane_root: root, task_id: taskId, next_intent: nextIntent, now } = input;
+		recoverKernelStoreFollowUps(root, taskId);
+		const prior = readTaskIntent(root, taskId, readTaskRecordRaw(root, taskId).record?.intent_ref.path);
+		const before = await projectAssurance(root, taskId, taskDeliveryIdentity);
+		if (before.error || before.claim?.task_id !== taskId || before.projection.lifecycle !== "active")
+			throw new Error(`the Lane does not hold an active run of ${taskId}`);
+		const nextHash = canonicalIntentHash(nextIntent);
+		const nextRef = { path: `docs/plans/${taskId}.intent.json`, content_hash: nextHash };
+		const snapshot = captureStagedIntent(root, prior.intent_ref.path);
+		try {
+			writeFileSync(join(root, prior.intent_ref.path), `${JSON.stringify(nextIntent, null, 2)}\n`);
+			execFileSync("git", ["add", "--", prior.intent_ref.path], { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+			const prepared = await projectAssurance(root, taskId, taskDeliveryIdentity);
+			if (prepared.error || prepared.projection.record_revision !== before.projection.record_revision)
+				throw new Error("the Lane's TaskRecord changed while the delegated revision was prepared");
+			const registry = createMutationAuthorityRegistry();
+			const action = capabilityActionFor({
+				op: "approve_breaking_intent_revision",
+				task_id: taskId,
+				at: now,
+				actor_id: DELEGATED_ACTOR_ID,
+				next_intent: nextIntent,
+				next_intent_ref: nextRef,
+			});
+			const binding: CapabilityBindingV2 = {
+				authority_kind: "user",
+				task_id: taskId,
+				...(prepared.projection.run_id ? { run_id: prepared.projection.run_id } : {}),
+				action_digest: digestOfAction(action),
+				expected_record_hash: prepared.projection.record_revision,
+				intent_revision: nextIntent.revision,
+				intent_content_hash: nextHash,
+				diff_hash: prepared.projection.diff_hash,
+				actor_id: DELEGATED_ACTOR_ID,
+				confirmation_ref: input.confirmation_ref,
+				findings_digest: null,
+			};
+			const capability = registry.issue(binding);
+			const result = createCanaryApplication(registry).execute({
+				root,
+				task_id: taskId,
+				operation: {
+					op: "approve_breaking_intent_revision",
+					capability,
+					actor_id: DELEGATED_ACTOR_ID,
+					next_intent: nextIntent,
+					next_intent_ref: nextRef,
+				} as never,
+				prior_intent_token: prior.token,
+				diffProvider: taskDeliveryIdentity,
+				now,
+			});
+			stagePlanningArtifactTransition(root, result.record);
+			return { from_revision: prior.intent.revision, to_revision: nextIntent.revision, intent_content_hash: nextHash };
+		} catch (error) {
+			const current = readTaskRecordRaw(root, taskId);
+			if (current.record?.intent_snapshot.revision === prior.intent.revision) restoreStagedIntent(root, snapshot);
+			throw error;
+		}
+	})();
+}

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 };
+}