immune-brain 5.1.0 → 5.1.2

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

@@ -0,0 +1,131 @@
+// Coordinator-side recovery for a Lane Executor's writes that landed in the
+// coordinator checkout instead of its Lane. On a lane-batch re-entry with a
+// dirty coordinator working tree, every dirty path must be provably a Lane's:
+// that Lane changed the path (its bytes differ from the Lane's base) and the
+// coordinator's bytes equal the Lane's, in its worktree or a commit on its
+// branch. Planning is read-only, so the batch preflight can run it before any
+// gate; only the runner, after authorization, backs the paths up, restores
+// them to HEAD and records the restore. Anything else (a staged change, a
+// deletion, bytes no Lane wrote) leaves every file untouched, so a user's own
+// uncommitted work is never restored.
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { BatchLaneRunStateRecord } from "./batch_state";
+
+export interface LaneLeakRestore {
+	at: string;
+	/** Repository-relative directory holding the backed-up bytes and `restore.json`. */
+	backup: string;
+	paths: Array<{ path: string; kind: "modified" | "untracked"; lane_task_id: string }>;
+}
+
+function git(root: string, args: string[]): { status: number | null; stdout: string } {
+	const result = spawnSync("git", ["-C", root, ...args], {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+		env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+	});
+	return { status: result.status, stdout: result.stdout ?? "" };
+}
+
+function blobOfFile(root: string, file: string): string | null {
+	const hashed = git(root, ["hash-object", "--no-filters", "--", file]);
+	return hashed.status === 0 ? hashed.stdout.trim() : null;
+}
+
+function blobAt(root: string, commit: string, path: string): string | null {
+	const blob = git(root, ["rev-parse", "--verify", "--quiet", `${commit}:${path}`]);
+	return blob.status === 0 ? blob.stdout.trim() : null;
+}
+
+/**
+ * The Lane of this batch that wrote `blob` at `path`, or null. A Lane only
+ * counts when its bytes for the path differ from the Lane's own base: a Lane
+ * that never touched the path still holds its base bytes, and matching those
+ * would mistake a user's revert for a Lane write.
+ */
+function laneOrigin(root: string, record: BatchLaneRunStateRecord, path: string, blob: string): string | null {
+	for (const child of record.children) {
+		const lane = child.lane;
+		if (!lane) continue;
+		if (blobAt(root, lane.base_head, path) === blob) continue;
+		if (existsSync(join(lane.path, path)) && blobOfFile(lane.path, join(lane.path, path)) === blob) return child.task_id;
+		const commits = git(root, ["rev-list", `${lane.base_head}..${lane.branch}`]);
+		if (commits.status !== 0) continue;
+		for (const commit of commits.stdout.split("\n").filter(Boolean))
+			if (blobAt(root, commit, path) === blob) return child.task_id;
+	}
+	return null;
+}
+
+export type LeakRestorePlan =
+	| { kind: "clean" }
+	| { kind: "provable"; paths: LaneLeakRestore["paths"] }
+	| { kind: "unprovable"; path: string; detail: string };
+
+/** Read-only: attribute every dirty path to a Lane of this batch, or name the first that cannot be. */
+export function planLaneLeakRestore(
+	root: string,
+	record: BatchLaneRunStateRecord,
+	entries: Array<{ code: string; path: string }>,
+): LeakRestorePlan {
+	if (entries.length === 0) return { kind: "clean" };
+	const planned: LaneLeakRestore["paths"] = [];
+	for (const { code, path } of entries) {
+		if (path.startsWith(".imm/")) return { kind: "unprovable", path, detail: "Immune-Brain state is never restored" };
+		const kind = code === "??" ? "untracked" : code === " M" ? "modified" : null;
+		if (!kind) return { kind: "unprovable", path, detail: `status ${code.trim() || code} is not a Lane write` };
+		const blob = blobOfFile(root, join(root, path));
+		if (!blob) return { kind: "unprovable", path, detail: "its bytes cannot be read" };
+		const origin = laneOrigin(root, record, path, blob);
+		if (!origin) return { kind: "unprovable", path, detail: "its bytes match no Lane of this batch" };
+		planned.push({ path, kind, lane_task_id: origin });
+	}
+	return { kind: "provable", paths: planned };
+}
+
+/**
+ * Back up and restore an already planned, fully provable set. Called only by
+ * the runner after the batch is authorized; it re-plans against the current
+ * status first, so a change since the preflight is never restored blind.
+ */
+export function restoreProvableLaneLeaks(
+	root: string,
+	record: BatchLaneRunStateRecord,
+	entries: Array<{ code: string; path: string }>,
+	now: string,
+): { kind: "clean" } | { kind: "restored"; restore: LaneLeakRestore } | { kind: "unprovable"; path: string; detail: string } {
+	const plan = planLaneLeakRestore(root, record, entries);
+	if (plan.kind !== "provable") return plan;
+	const planned = plan.paths;
+	const stamp = now.replace(/[^0-9TZ]/g, "");
+	const backup = join(".imm", "state", "batches", "restores", record.batch_id, stamp);
+	const backupRoot = join(root, backup);
+	mkdirSync(join(backupRoot, "files"), { recursive: true });
+	const tracked = planned.filter((p) => p.kind === "modified").map((p) => p.path);
+	if (tracked.length > 0) {
+		const diff = git(root, ["diff", "--binary", "HEAD", "--", ...tracked]);
+		writeFileSync(join(backupRoot, "restore.patch"), diff.stdout);
+	}
+	// Back every modified path up before changing any of them; an untracked
+	// path is moved into the backup below, so it keeps exactly one copy.
+	for (const { path, kind } of planned) {
+		mkdirSync(dirname(join(backupRoot, "files", path)), { recursive: true });
+		if (kind === "modified") copyFileSync(join(root, path), join(backupRoot, "files", path));
+	}
+	const restore: LaneLeakRestore = { at: now, backup, paths: planned };
+	writeFileSync(join(backupRoot, "restore.json"), `${JSON.stringify({
+		...restore,
+		undo: "copy each file under files/ back to the same repository path",
+	}, null, 2)}\n`);
+	for (const { path, kind } of planned) {
+		if (kind === "untracked") {
+			renameSync(join(root, path), join(backupRoot, "files", path));
+			continue;
+		}
+		const restored = git(root, ["restore", "--source=HEAD", "--worktree", "--", path]);
+		if (restored.status !== 0) throw new Error(`failed to restore ${path} from HEAD; its bytes are backed up under ${backup}`);
+	}
+	return { kind: "restored", restore };
+}

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

@@ -26,7 +26,8 @@ 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 { planLaneLeakRestore } from "./batch_leak_restore";
 import type {
 	BatchPlanBudget,
 	BatchPlanChild,
@@ -126,7 +127,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 +151,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" ||
@@ -380,7 +375,7 @@ function authorizedScopeOf(root: string, taskId: string, state: string): string[
 	return scope;
 }
 
-function porcelainEntries(root: string): Array<{ code: string; path: string }> | null {
+export function porcelainEntries(root: string): Array<{ code: string; path: string }> | null {
 	// review-batch-resume-porcelain-leading-space: parse the NUL-delimited v1
 	// format. Trimming the whole output first shifted the fixed status columns of
 	// an unstaged modification (" M path") and silently mis-scoped the path.
@@ -600,9 +595,19 @@ export async function projectBatchPreflight(
 	if (branchExists.status === 0 && !existingBatch)
 		return reject("branch_already_exists", batchBranch);
 
-	const statusEntries = porcelainEntries(root);
+	let statusEntries = porcelainEntries(root);
 	if (statusEntries === null)
 		return reject("git_status_unreadable");
+	// A lane batch keeps its delivery in Lanes, so a dirty coordinator is a leak.
+	// This read-only check only attributes it: when every dirty path is provably
+	// a Lane's write, the runner restores them after the gate; any change of
+	// unknown origin is refused below and nothing is touched.
+	let unprovableLeak = "";
+	if (statusEntries.length > 0 && activeRecord && isLaneBatchRecord(activeRecord)) {
+		const plan = planLaneLeakRestore(root, activeRecord, statusEntries);
+		if (plan.kind === "provable") statusEntries = [];
+		else if (plan.kind === "unprovable") unprovableLeak = `${plan.path}: ${plan.detail}`;
+	}
 	if (statusEntries.length > 0) {
 		if (!isResuming)
 			return reject("working_tree_dirty");
@@ -622,7 +627,7 @@ export async function projectBatchPreflight(
 		}
 		const dirtyBytes = statusEntries.some(({ code }) => code === "??" || code[1] !== " ");
 		if (dirtyBytes)
-			return reject("working_tree_unstaged");
+			return reject("working_tree_unstaged", unprovableLeak);
 		let outsideScope = false;
 		for (const { path } of statusEntries) {
 			if (path.startsWith(".imm/") || path.startsWith("docs/plans/") || path.startsWith("docs/specs/")) continue;
@@ -659,7 +664,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 = {
@@ -752,7 +759,12 @@ export interface BatchConfirmationFacts {
  * own failure-envelope shape.
  */
 export type BatchGateDecision<HostRejection> =
-	| { kind: "confirmed"; request_id: string }
+	| {
+			kind: "confirmed";
+			request_id: string;
+			/** ADR 0018: the user also delegated in-envelope Lane Intent revisions (lane mode only). */
+			delegate_revisions?: boolean;
+	  }
 	| { kind: "host_rejection"; value: HostRejection };
 
 export type BatchAuthorizationOutcome<HostRejection> =
@@ -762,6 +774,8 @@ export type BatchAuthorizationOutcome<HostRejection> =
 			reuse_authorization: boolean;
 			reuse_blockers: string[];
 			binding: BatchAuthorizationBinding;
+			/** The gate's delegation answer; absent when the authorization was reused and no gate opened. */
+			revision_delegation?: boolean;
 	  }
 	| { outcome: "rejected"; rejection: BatchPreflightRejection }
 	| { outcome: "host_rejection"; value: HostRejection };
@@ -852,10 +866,12 @@ export async function authorizeBatch<HostRejection>(
 	};
 
 	let requestId: string | null = null;
+	let revisionDelegation: boolean | undefined;
 	if (!reuseAuthorization) {
 		const decision = await options.gate(facts);
 		if (decision.kind === "host_rejection") return { outcome: "host_rejection", value: decision.value };
 		requestId = decision.request_id;
+		revisionDelegation = decision.delegate_revisions === true;
 	}
 
 	// Post-gate cascade: the drift projection reports the live claim it read
@@ -920,5 +936,6 @@ export async function authorizeBatch<HostRejection>(
 		reuse_authorization: reuseAuthorization,
 		reuse_blockers: reuseBlockers,
 		binding,
+		...(revisionDelegation !== undefined ? { revision_delegation: revisionDelegation } : {}),
 	};
 }

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";
@@ -91,8 +93,9 @@ export const BATCH_REASONS: Readonly<Record<BatchReasonKey, BatchReasonSpec>> =
 	},
 	working_tree_unstaged: {
 		state: "rejected",
-		reason: "branch preflight failed: working tree has unstaged or untracked changes",
-		recovery_action: "stage the in-flight changes with git add, then retry in the current Host",
+		reason: (detail: string) =>
+			`branch preflight failed: working tree has unstaged or untracked changes${detail ? ` (not restored: ${detail})` : ""}`,
+		recovery_action: "establish where each unstaged or untracked change came from before staging anything; move changes that are not the active child's verified work out of the working tree, then retry in the current Host",
 	},
 	working_tree_out_of_scope: {
 		state: "rejected",
@@ -170,6 +173,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

@@ -108,6 +108,48 @@ export interface StartBatchInput {
 	max_parallel?: number;
 	/** Present only in lane mode: Lanes someone else created, offered to the batch. */
 	lane_offers?: LaneOffer[];
+	/**
+	 * Lane mode only: the opted-in tracker projection the coordinator runs after
+	 * integrating a child. A Lane settlement writes nothing to the tracker, so
+	 * this is where its Child Issue is closed, exactly once. Absent, nothing is
+	 * projected.
+	 */
+	tracker?: BatchTrackerPort;
+	/**
+	 * Lane mode only: the plugin or runtime directory the Lane Executor Host
+	 * loads. Absent, the repository's own plugin source is compared when the
+	 * repository is the Immune-Brain package; otherwise nothing is compared.
+	 */
+	executor_runtime?: string;
+	/**
+	 * Lane mode only: the project's full verification commands, recorded when a
+	 * new batch starts and run on the batch branch once every child is
+	 * integrated. Ignored on a resume; the recorded list stands.
+	 */
+	final_verification?: string[];
+	/**
+	 * Lane mode only: one text instruction the Parent wants to send a Lane
+	 * session. The tick records it and answers whether it may be sent; it is
+	 * never sent to a blocked or working session.
+	 */
+	lane_instruction?: import("./batch_lanes").LaneInstructionRequest;
+	/**
+	 * Lane mode only, ADR 0018: the literal user's answer, in this call's own
+	 * batch confirmation, on delegating in-envelope Lane Intent revisions to the
+	 * coordinator. Absent when no gate opened (a reused authorization): the
+	 * recorded grant stands.
+	 */
+	revision_delegation?: boolean;
+	/** Lane mode only, ADR 0018: one breaking Intent revision the coordinator approves under the grant. */
+	lane_revision?: import("./batch_delegation").LaneRevisionRequest;
+}
+
+/** The one tracker effect a lane batch may cause: closing an integrated child's Issue. */
+export interface BatchTrackerPort {
+	markTerminal(
+		root: string,
+		input: { task_id: string; phase: "done"; terminal_event_id: string },
+	): Promise<{ status: string; message: string }>;
 }
 
 /** One git seam: the injected BatchRunnerGitPort, or the default adapter over
@@ -179,6 +221,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 +492,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_schedule.ts

@@ -83,6 +83,46 @@ export function scopesOverlap(left: readonly string[], right: readonly string[])
 	});
 }
 
+/**
+ * The entry pairs that make two scope lists overlap, in list order: the
+ * machine evidence behind `scopesOverlap`, so a plan can name the shared paths
+ * instead of asserting disjointness by hand. An empty list on either side
+ * overlaps everything and is reported as the pair `["", entry]`.
+ */
+export function overlappingScopeEntries(left: readonly string[], right: readonly string[]): Array<[string, string]> {
+	if (!left.length || !right.length) return [[left[0] ?? "", right[0] ?? ""]];
+	const pairs: Array<[string, string]> = [];
+	for (const entry of left) {
+		const prefix = scopePrefix(entry);
+		for (const other of right) if (prefixOverlaps(prefix, scopePrefix(other))) pairs.push([entry, other]);
+	}
+	return pairs;
+}
+
+export interface ScopeOverlapReport {
+	contract: "assurance_kernel/intent_scope_overlap/v1";
+	overlaps: Array<{ task_ids: [string, string]; entries: Array<[string, string]> }>;
+	parallel_groups: BatchPlanParallelGroups;
+	scope_conflicts: BatchPlanScopeConflict[];
+}
+
+/**
+ * Compare the `scope_hint` of every pair of Intents of one Initiative. The
+ * groups use the same projection the Batch Plan uses, so the Planner's review
+ * table and the batch confirmation agree on what runs together.
+ */
+export function projectScopeOverlap(children: readonly PlanScheduleChild[]): ScopeOverlapReport {
+	const overlaps: ScopeOverlapReport["overlaps"] = [];
+	for (let i = 0; i < children.length; i += 1)
+		for (let j = i + 1; j < children.length; j += 1) {
+			const entries = scopesOverlap(children[i]!.scope_hint, children[j]!.scope_hint)
+				? overlappingScopeEntries(children[i]!.scope_hint, children[j]!.scope_hint)
+				: [];
+			if (entries.length) overlaps.push({ task_ids: [children[i]!.task_id, children[j]!.task_id], entries });
+		}
+	return { contract: "assurance_kernel/intent_scope_overlap/v1", overlaps, ...projectParallelGroups(children) };
+}
+
 function positiveLimit(maxParallel: number): number {
 	if (maxParallel === Number.POSITIVE_INFINITY) return maxParallel;
 	if (!Number.isSafeInteger(maxParallel) || maxParallel <= 0)