immune-brain 5.1.0 → 5.1.1

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

@@ -279,12 +279,15 @@ function releaseHandoffs(
 	record: BatchLaneRunStateRecord,
 	lanes: BatchLaneGitPort,
 ): BatchLaneHandoff[] {
+	const lineage = classifyBatchLineage({ root: input.root, branch: record.branch ?? "",
+		expectedHead: expectedBatchHead(record), childCommits: record.commits, batchId: record.batch_id });
+	if (lineage.kind === "broken") return [];
 	const handoffs: BatchLaneHandoff[] = [];
 	for (const child of record.children) {
 		if (child.state !== "integrated" || !child.lane) continue;
 		const facts = lanes.inspectLane(input.root, child.lane.path);
-		if (!facts.exists || !facts.same_repository || !facts.clean || facts.branch !== child.lane.branch) continue;
-		if (!lanes.auditReachable({ root: input.root, head: expectedBatchHead(record), task_id: child.task_id })) continue;
+		if (!facts.exists || !facts.same_repository || !facts.is_worktree_root || !facts.clean || facts.branch !== child.lane.branch || facts.active_claim_task_id !== null) continue;
+		if (!lanes.auditReachable({ root: input.root, head: lineage.head, task_id: child.task_id })) continue;
 		handoffs.push({ role: "lane-steward", action: "release", task_id: child.task_id, lane_branch: child.lane.branch });
 	}
 	return handoffs;
@@ -342,7 +345,7 @@ function scheduleView(input: StartBatchInput, record: BatchLaneRunStateRecord) {
 	}));
 }
 
-/** The lane batch has stopped on a parked child. A re-confirmation returns the same stop; only a new Batch Authorization starts a fresh run. */
+/** Recovery preserves the parked run and requires fresh literal-user authorization. */
 const LANE_NEEDS_HUMAN_NEXT_ACTION =
 	"The lane batch has stopped on a parked child and its Lane is kept. Resolve the child by hand; continuing needs a new Batch Authorization.";
 
@@ -351,6 +354,7 @@ const TERMINAL_NEXT_ACTIONS: Record<string, string> = {
 	budget_stopped: "The child budget stopped new enrollments; re-confirm to continue under a new authorization.",
 	failed: "A lineage failure stopped the batch; inspect the failing child and the branch state.",
 	rejected: "The batch was rejected before any enrollment; correct the stated reason and re-confirm.",
+	superseded: "The plan moved past this record and an explicit disposition retired it; it grants no handoff and no child delivery.",
 	needs_human: LANE_NEEDS_HUMAN_NEXT_ACTION,
 	running: "The batch is still running; no terminal report is due yet.",
 	prepared: "The batch is prepared but not started.",
@@ -379,8 +383,13 @@ function laneReport(
 }
 
 /** A store-condition rejection of a persisted lane batch: its persisted lane children, commits and parallelism, never an empty serial plan. */
-export function laneRejectionReport(record: BatchLaneRunStateRecord, reason: string, nextAction: string): BatchLaneRunReport {
-	return laneReport({ ...record, batch_state: "rejected" }, reason, nextAction);
+export function laneRejectionReport(input: StartBatchInput, record: BatchLaneRunStateRecord, reason: string, nextAction: string): BatchLaneRunReport {
+	// A rejected tick grants no execution or admission authority. Only already
+	// integrated, unoccupied Lanes with surviving audit evidence may be released.
+	const handoffs = releaseHandoffs(input, record, laneGitOf(input));
+	return laneReport({ ...record, batch_state: "rejected" }, reason,
+		handoffs.length ? `${nextAction}. Check each release handoff with the Lane Steward.` : nextAction,
+		{ handoffs });
 }
 
 function finalizeLane(
@@ -535,13 +544,31 @@ export async function runLaneBatch(
 			return finalizeLane(input.root, record, `terminal state already reached: ${record.batch_state}`, "", {
 				handoffs: record.batch_state === "completed" ? releaseHandoffs(input, record, lanes) : [],
 			});
-		if (record.batch_state === "needs_human")
-			return finalizeLane(
-				input.root,
-				record,
-				"a parked child needs a human decision",
-				LANE_NEEDS_HUMAN_NEXT_ACTION,
-			);
+		if (record.batch_state === "needs_human") {
+			const invalid = validateNewAuthorization(input);
+			if (invalid || Date.parse(input.confirmation_time) <= Date.parse(record.confirmation_time))
+				return laneReport(record, invalid ?? "the parked batch requires a fresh literal-user confirmation", LANE_NEEDS_HUMAN_NEXT_ACTION);
+			const resumed: BatchLaneChildRun[] = [];
+			for (const child of record.children) {
+				if (child.state !== "needs_human") { resumed.push(child); continue; }
+				if (!child.lane?.run_id)
+					return laneReport(record, "parked Lane has no recorded run identity; inspect it without re-enrolling", LANE_NEEDS_HUMAN_NEXT_ACTION);
+				const facts = lanes.inspectLane(input.root, child.lane.path);
+				const fresh = await input.kernel.projectTask(child.lane.path, child.task_id);
+				if (!facts.exists || !facts.same_repository || !facts.is_worktree_root || facts.branch !== child.lane.branch ||
+					fresh.error !== null || fresh.projection.run_id !== child.lane.run_id ||
+					fresh.projection.open_user_decision_count > 0 || fresh.projection.replan_required_ids.length > 0)
+					return laneReport(record, "parked Lane identity or decision is unresolved", LANE_NEEDS_HUMAN_NEXT_ACTION);
+				const state = fresh.projection.lifecycle === "done" && fresh.projection.completion_ready ?
+					(child.lane.lane_commit ? "lane_committed" : "settled") :
+					fresh.projection.lifecycle === "active" && fresh.claim?.task_id === child.task_id &&
+					(facts.active_claim_task_id === null || facts.active_claim_task_id === child.task_id) ? "enrolled" : null;
+				if (!state) return laneReport(record, "parked child has no recoverable owned run", LANE_NEEDS_HUMAN_NEXT_ACTION);
+				resumed.push({ ...child, state, reason: null, qa_failures: 0 });
+			}
+			record = { ...record, batch_state: "running", confirmation_time: input.confirmation_time,
+				children: resumed.map(child => child.state === "skipped_blocked" ? { ...child, state: "pending", reason: null } : child) };
+		}
 	} else {
 		const invalid = validateNewAuthorization(input);
 		if (invalid) return refuse(input, null, "batch_authorization_invalid", invalid);
@@ -567,6 +594,8 @@ export async function runLaneBatch(
 	const persist = (): void => {
 		record = writeBatchLaneRunState(input.root, record);
 	};
+	// A resumed park is persisted only after the existing lineage validation below.
+	const resumedPark = persisted?.batch_state === "needs_human" && record.batch_state === "running";
 	if (record.batch_state === "prepared") {
 		record.batch_state = "running";
 		persist();
@@ -622,6 +651,7 @@ export async function runLaneBatch(
 		return failLineage(input.root, record, error instanceof Error ? error.message : String(error));
 	}
 
+	if (resumedPark) persist();
 	const refusals: NonNullable<BatchLaneRunReport["lane_refusals"]> = [];
 	// A parked child ends only itself and its dependents; the batch keeps moving
 	// for every scope-disjoint sibling and settles needs_human at the end of the
@@ -641,7 +671,10 @@ export async function runLaneBatch(
 				task_id: taskId,
 				batch: { registry: input.registry, capability: input.capability, binding: { batch_id: record.batch_id, expected_head: lane.base_head } },
 			});
-			record.children = record.children.map((c) => (c.task_id === taskId ? { ...c, state: "enrolled", reason: null } : c));
+			const fresh = await input.kernel.projectTask(lane.path, taskId);
+			if (fresh.error !== null || !fresh.projection.run_id || fresh.claim?.task_id !== taskId)
+				throw new Error("enrolled Lane has no observable owned run");
+			record.children = record.children.map((c) => (c.task_id === taskId ? { ...c, state: "enrolled", reason: null, lane: { ...lane, run_id: fresh.projection.run_id } } : c));
 			persist();
 			return null;
 		} catch (error) {
@@ -669,12 +702,16 @@ export async function runLaneBatch(
 			parkChild(child.task_id, "batch_lane_lost");
 			continue;
 		}
+		if (child.lane.run_id && fresh.projection.run_id !== child.lane.run_id) {
+			parkChild(child.task_id, "batch_lane_run_mismatch");
+			continue;
+		}
 		const holdsClaim = fresh.claim !== null && fresh.claim.task_id === child.task_id;
 		if (child.state === "lane_admitted") {
 			// A crash between admission and enrollment adopts an existing claim or enrolls now.
 			if (holdsClaim) {
 				record.children = record.children.map((c) =>
-					c.task_id === child.task_id ? { ...c, state: "enrolled", reason: "adopted existing lane claim after interruption" } : c,
+					c.task_id === child.task_id ? { ...c, state: "enrolled", reason: "adopted existing lane claim after interruption", lane: { ...child.lane!, run_id: fresh.projection.run_id } } : c,
 				);
 				persist();
 			} else {

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

@@ -26,7 +26,7 @@ import { pathMatchesScope } from "../workspace_scope";
 import { captureBatchReconfirmation, retainReconfirmation, ownUnpersistedBatchHead, type ReconfirmationSnapshot } from "./batch_reconfirmation";
 import { projectBatchPlan } from "./batch_plan";
 import { batchReason, type BatchReasonKey } from "./batch_reasons";
-import { isLaneBatchRecord, isTerminalBatchState, readAnyBatchRunState, type AnyBatchRunStateRecord, type BatchRunStateRecord } from "./batch_state";
+import { BATCH_RUN_STATES, isLaneBatchRecord, isTerminalBatchState, readAnyBatchRunState, type AnyBatchRunStateRecord, type BatchRunStateRecord } from "./batch_state";
 import type {
 	BatchPlanBudget,
 	BatchPlanChild,
@@ -126,7 +126,7 @@ export function findResumableBatchSlugForTask(root: string, taskId: string): str
 
 /**
  * The batch record for this initiative, or a corruption marker. A terminal
- * record (completed, budget_stopped, failed, rejected) is not active: returning
+ * record (completed, budget_stopped, failed, rejected, superseded) is not active: returning
  * it would let a settled batch block or be resumed by a later run.
  */
 export type BatchRecordLookup =
@@ -150,15 +150,9 @@ export function findExistingActiveBatch(root: string, initiativeSlug: string): B
 		const candidate = record as AnyBatchRunStateRecord;
 		if (candidate?.contract !== "assurance_kernel/batch_run_state/v1" && candidate?.contract !== "assurance_kernel/batch_run_state/v2") continue;
 		if (candidate.initiative_slug !== initiativeSlug) continue;
-		const validStates = new Set([
-			"prepared",
-			"running",
-			"needs_human",
-			"completed",
-			"budget_stopped",
-			"failed",
-			"rejected",
-		]);
+		// Every state the state owner accepts, so a retired record reads as settled
+		// instead of failing this lookup closed as an unknown state.
+		const validStates = new Set<string>(BATCH_RUN_STATES);
 		if (
 			typeof candidate.batch_id !== "string" ||
 			typeof candidate.base_head !== "string" ||
@@ -659,7 +653,9 @@ export async function projectBatchPreflight(
 	let reconfirmation: ReconfirmationSnapshot | undefined;
 	if (activeRecord && !isLaneBatchRecord(activeRecord) && activeRecord.plan_digest !== planSurface.surface.plan_digest) {
 		try { reconfirmation = await captureBatchReconfirmation(root, activeRecord, planSurface.surface.recovery_children); }
-		catch { return reject("plan_projection_failed", "batch plan reconfirmation is not eligible"); }
+		catch { return reject("plan_projection_failed", activeRecord.commits.length
+			? `batch plan changed after ${activeRecord.commits.length} recorded child commit(s). The old authorization cannot execute the revised plan. Preserve the batch record, report, commit evidence and audit; inspect each remaining child's Kernel run before an explicit imm-run handoff. Do not re-enroll settled children or manufacture batch trailers. To close the parked record explicitly, dispose it with the retire_stale_batch Tool for this Initiative; a child that is still mid-flight must settle first. This rejection neither terminates the old batch nor authorizes the revised plan.`
+			: "batch plan reconfirmation is not eligible"); }
 	}
 
 	const projection: BatchPreflightProjection = {

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

@@ -34,7 +34,9 @@ export type BatchReasonKey =
 	| "repository_became_unreadable"
 	| "head_moved"
 	| "cancelled_before_execution"
-	| "batch_run_rejected";
+	| "batch_run_rejected"
+	| "stale_batch_absent"
+	| "stale_batch_in_flight";
 
 export interface BatchReasonSpec {
 	readonly state: "rejected" | "cancelled" | "blocked";
@@ -170,6 +172,16 @@ export const BATCH_REASONS: Readonly<Record<BatchReasonKey, BatchReasonSpec>> =
 		reason: (detail: string) => detail || "batch run rejected",
 		recovery_action: "delete or rename the conflicting branch, or commit working changes and retry in the current Host",
 	},
+	stale_batch_absent: {
+		state: "rejected",
+		reason: (detail: string) => `no retirable batch record to dispose: ${detail}`,
+		recovery_action: "start a batch for this Initiative, or inspect the batch records under .imm/state/batches in the current Host",
+	},
+	stale_batch_in_flight: {
+		state: "blocked",
+		reason: (detail: string) => `a batch child is still mid-flight, so the record cannot be disposed: ${detail}`,
+		recovery_action: "settle or stop the in-flight child through its own task, then dispose the batch in the current Host",
+	},
 });
 
 export interface BatchReason {

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

@@ -179,6 +179,7 @@ const TERMINAL_NEXT_ACTIONS: Record<string, string> = {
 	budget_stopped: "The child budget stopped new enrollments; re-confirm to continue under a new authorization.",
 	failed: "A commit or lineage failure stopped the batch; inspect the failing child and the branch state.",
 	rejected: "The batch was rejected before any enrollment; correct the stated reason and re-confirm.",
+	superseded: "The plan moved past this record and an explicit disposition retired it; it grants no handoff and no child delivery.",
 	needs_human: "A parked child needs a human decision; resolve it, then re-confirm to continue.",
 	running: "The batch is still running; no terminal report is due yet.",
 	prepared: "The batch is prepared but not started.",
@@ -449,6 +450,7 @@ function rejectionReport(input: StartBatchInput, reason: string): BatchRunReport
 	})();
 	if (persisted !== null && isLaneBatchRecord(persisted))
 		return laneRejectionReport(
+			input,
 			persisted,
 			reason,
 			"settle the reported kernel store condition and retry in the current Host",

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

@@ -14,7 +14,14 @@ export type BatchRunState =
 	| "completed"
 	| "budget_stopped"
 	| "failed"
-	| "rejected";
+	| "rejected"
+	/**
+	 * Retired by an explicit literal-user disposition after the batch plan moved
+	 * past it. Terminal, and not a failure of the batch's own: the record, its
+	 * children, its commits and its branch stay as evidence, and the retired
+	 * authorization is never reused for the revised plan.
+	 */
+	| "superseded";
 
 export type BatchChildRunState =
 	| "pending"
@@ -88,6 +95,8 @@ export interface BatchLaneBinding {
 	base_head: string;
 	/** Commit created in the Lane after the Lane Kernel settled the child. */
 	lane_commit: string | null;
+	/** Kernel run observed at enrollment; absent historical bindings cannot resume a parked child. */
+	run_id?: string | null;
 }
 
 export interface BatchLaneChildRun {
@@ -145,7 +154,7 @@ const CHILD_RUN_STATES: ReadonlySet<string> = new Set([
 	"skipped_blocked",
 ]);
 
-const BATCH_RUN_STATES: ReadonlySet<string> = new Set([
+export const BATCH_RUN_STATES: ReadonlySet<string> = new Set([
 	"prepared",
 	"running",
 	"needs_human",
@@ -153,6 +162,7 @@ const BATCH_RUN_STATES: ReadonlySet<string> = new Set([
 	"budget_stopped",
 	"failed",
 	"rejected",
+	"superseded",
 ]);
 
 const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
@@ -286,7 +296,8 @@ function validateRecordShape(value: unknown, batchId: string): asserts value is
 	if (
 		(record.batch_state === "budget_stopped" ||
 			record.batch_state === "failed" ||
-			record.batch_state === "rejected") &&
+			record.batch_state === "rejected" ||
+			record.batch_state === "superseded") &&
 		record.children.some((child) => child.state === "enrolled" || child.state === "settled")
 	)
 		throw new Error(`batch run state ${batchId} is ${String(record.batch_state)} but a child is still mid-flight`);
@@ -398,6 +409,25 @@ export function replaceBatchRunState(root: string, expected: Buffer, next: Batch
 	});
 }
 
+/** Replace a record of either version only after a locked expected-byte check. */
+export function replaceAnyBatchRunState(
+	root: string,
+	expected: Buffer,
+	next: AnyBatchRunStateRecord,
+	validate: () => void,
+): AnyBatchRunStateRecord {
+	const path = statePath(next.batch_id);
+	if (isLaneBatchRecord(next)) validateLaneRecordShape(next, next.batch_id);
+	else validateRecordShape(next, next.batch_id);
+	return withKernelStoreLock(root, () => {
+		if (!readSecureProjectBytes(root, path).equals(expected)) throw new Error("batch state CAS mismatch");
+		validate();
+		const stored = withoutRetiredClock({ ...next, updated_at: new Date().toISOString() });
+		writeFileAtomically(root, path, canonicalBytes(stored));
+		return stored;
+	});
+}
+
 export function writeBatchRunState(
 	root: string,
 	record: BatchRunStateRecord,
@@ -525,7 +555,8 @@ function validateLaneRecordShape(value: unknown, batchId: string): asserts value
 				!lane.branch ||
 				typeof lane.base_head !== "string" ||
 				!lane.base_head ||
-				(lane.lane_commit !== null && typeof lane.lane_commit !== "string")
+				(lane.lane_commit !== null && typeof lane.lane_commit !== "string") ||
+				(lane.run_id !== undefined && lane.run_id !== null && (typeof lane.run_id !== "string" || !lane.run_id))
 			)
 				throw new Error(`batch run state ${batchId} child ${child.task_id} has an invalid lane`);
 		}
@@ -558,7 +589,8 @@ function validateLaneRecordShape(value: unknown, batchId: string): asserts value
 		child.state === "settled" ||
 		child.state === "lane_committed";
 	if (
-		(record.batch_state === "budget_stopped" || record.batch_state === "failed" || record.batch_state === "rejected") &&
+		(record.batch_state === "budget_stopped" || record.batch_state === "failed" || record.batch_state === "rejected" ||
+			record.batch_state === "superseded") &&
 		record.children.some(inFlight)
 	)
 		throw new Error(`batch run state ${batchId} is ${String(record.batch_state)} but a child is still mid-flight`);
@@ -756,5 +788,11 @@ function canonicalReportBytes(report: PersistableReport): string {
 
 /** All terminal batch states; needs_human is a park, not terminal. */
 export function isTerminalBatchState(state: BatchRunState): boolean {
-	return state === "completed" || state === "budget_stopped" || state === "failed" || state === "rejected";
+	return (
+		state === "completed" ||
+		state === "budget_stopped" ||
+		state === "failed" ||
+		state === "rejected" ||
+		state === "superseded"
+	);
 }