immune-brain 5.1.1 → 5.2.0

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

@@ -27,6 +27,7 @@ import { captureBatchReconfirmation, retainReconfirmation, ownUnpersistedBatchHe
 import { projectBatchPlan } from "./batch_plan";
 import { batchReason, type BatchReasonKey } from "./batch_reasons";
 import { BATCH_RUN_STATES, isLaneBatchRecord, isTerminalBatchState, readAnyBatchRunState, type AnyBatchRunStateRecord, type BatchRunStateRecord } from "./batch_state";
+import { planLaneLeakRestore } from "./batch_leak_restore";
 import type {
 	BatchPlanBudget,
 	BatchPlanChild,
@@ -374,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.
@@ -594,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");
@@ -616,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;
@@ -748,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> =
@@ -758,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 };
@@ -848,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
@@ -916,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

@@ -93,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",

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

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)

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

@@ -109,6 +109,28 @@ export interface BatchLaneChildRun {
 	commit: string | null;
 	lane: BatchLaneBinding | null;
 	qa_failures: number;
+	/**
+	 * The Child Issue was closed by the coordinator after this child's commit was
+	 * integrated. Absent until then; a Lane settlement never closes it.
+	 */
+	tracker_closed?: boolean;
+	/** Coordinator corrections already spent on this child (at most two). */
+	corrections?: number;
+	/**
+	 * Set when the child exhausted its rework budget and waits for one
+	 * design-level coordinator correction instead of parking; cleared when the
+	 * correction is recorded.
+	 */
+	correction_due?: string;
+}
+
+export interface LaneIntervention {
+	at: string;
+	task_id: string;
+	/** `instruction` is an ordinary correction; `correction` is a design-level correction after an exhausted budget. */
+	kind: "instruction" | "correction";
+	text: string;
+	text_digest: string;
 }
 
 /**
@@ -133,6 +155,30 @@ export interface BatchLaneRunStateRecord {
 	/** Batch-branch commits produced by integration, in integration order. */
 	commits: string[];
 	adopted_heads?: Array<{ from: string; to: string }>;
+	/**
+	 * Lane writes that leaked into the coordinator checkout and were restored on
+	 * re-entry, each with the backup that undoes it. Absent until one happens.
+	 */
+	restores?: import("./batch_leak_restore").LaneLeakRestore[];
+	/**
+	 * Every text instruction the coordinator sent a Lane session, recorded before
+	 * it was sent, so coordinator intervention is told apart from the Executor's
+	 * own behavior afterwards.
+	 */
+	interventions?: LaneIntervention[];
+	/** Commands run on the batch branch once every child is integrated; fixed when the batch starts. */
+	final_verification?: string[];
+	/**
+	 * ADR 0018: the literal user's grant, in this batch's confirmation, to let the
+	 * coordinator approve in-envelope Lane Intent revisions. Absent: not granted.
+	 */
+	revision_delegation?: import("./batch_delegation").RevisionDelegationGrant;
+	/** Every revision applied under that grant. */
+	delegated_revisions?: import("./batch_delegation").DelegatedRevisionRecord[];
+	/** Each child's TaskIntent identity behind `plan_digest`; resealed only for a delegated revision. */
+	intent_identities?: Record<string, { intent_path: string; intent_revision: number; intent_content_hash: string }>;
+	/** Each `plan_digest` reseal at integration, with the digest before and after. */
+	reseals?: Array<{ at: string; task_id: string; from_digest: string; to_digest: string; intent_revision: number; intent_content_hash: string }>;
 	created_at: string;
 	updated_at: string;
 }
@@ -523,6 +569,66 @@ function validateLaneRecordShape(value: unknown, batchId: string): asserts value
 			))
 	)
 		throw new Error(`batch run state ${batchId} has an invalid adopted_heads list`);
+	if (
+		record.restores !== undefined &&
+		(!Array.isArray(record.restores) ||
+			record.restores.some(
+				(r: unknown) =>
+					typeof r !== "object" || r === null ||
+					typeof (r as { backup?: unknown }).backup !== "string" ||
+					!Array.isArray((r as { paths?: unknown }).paths),
+			))
+	)
+		throw new Error(`batch run state ${batchId} has an invalid restores list`);
+	if (
+		record.final_verification !== undefined &&
+		(!Array.isArray(record.final_verification) ||
+			record.final_verification.length === 0 ||
+			record.final_verification.some((c: unknown) => typeof c !== "string" || !c))
+	)
+		throw new Error(`batch run state ${batchId} has an invalid final_verification list`);
+	if (
+		record.interventions !== undefined &&
+		(!Array.isArray(record.interventions) ||
+			record.interventions.some(
+				(i: unknown) =>
+					typeof i !== "object" || i === null ||
+					typeof (i as LaneIntervention).task_id !== "string" ||
+					((i as LaneIntervention).kind !== "instruction" && (i as LaneIntervention).kind !== "correction") ||
+					typeof (i as LaneIntervention).text !== "string" ||
+					typeof (i as LaneIntervention).text_digest !== "string",
+			))
+	)
+		throw new Error(`batch run state ${batchId} has an invalid interventions list`);
+	// ADR 0018 fields carry authority effects, so a malformed one fails closed.
+	const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+	const isHash = (v: unknown) => typeof v === "string" && /^sha256:[0-9a-f]{64}$/.test(v);
+	const isRevision = (v: unknown) => typeof v === "number" && Number.isSafeInteger(v) && v > 0;
+	if (record.revision_delegation !== undefined &&
+		(!isObject(record.revision_delegation) || Object.keys(record.revision_delegation).join() !== "confirmation_time" ||
+			!isCanonicalTimestamp(record.revision_delegation.confirmation_time)))
+		throw new Error(`batch run state ${batchId} has an invalid revision_delegation`);
+	if (record.delegated_revisions !== undefined &&
+		(!Array.isArray(record.delegated_revisions) || record.delegated_revisions.some((r: unknown) =>
+			!isObject(r) || typeof r.task_id !== "string" || !isRevision(r.from_revision) || !isRevision(r.to_revision) ||
+			(r.to_revision as number) <= (r.from_revision as number) || !isHash(r.intent_content_hash) ||
+			typeof r.confirmation_ref !== "string" || !r.confirmation_ref.startsWith(`delegated-batch:${batchId}@`) ||
+			!isCanonicalTimestamp(r.at))))
+		throw new Error(`batch run state ${batchId} has an invalid delegated_revisions list`);
+	if (record.delegated_revisions?.length && !record.revision_delegation)
+		throw new Error(`batch run state ${batchId} records delegated revisions without a delegation grant`);
+	if (record.intent_identities !== undefined &&
+		(!isObject(record.intent_identities) || Object.values(record.intent_identities).some((i: unknown) =>
+			!isObject(i) || typeof i.intent_path !== "string" || !i.intent_path || !isRevision(i.intent_revision) || typeof i.intent_content_hash !== "string" || !i.intent_content_hash)))
+		throw new Error(`batch run state ${batchId} has an invalid intent_identities map`);
+	if (record.reseals !== undefined &&
+		(!Array.isArray(record.reseals) || record.reseals.some((r: unknown) =>
+			!isObject(r) || typeof r.task_id !== "string" || typeof r.from_digest !== "string" || typeof r.to_digest !== "string" ||
+			!isRevision(r.intent_revision) || !isHash(r.intent_content_hash) ||
+			!(record.delegated_revisions as Array<{ task_id: string; intent_content_hash: string }> | undefined)?.some((d) => d.task_id === r.task_id && d.intent_content_hash === r.intent_content_hash))))
+		throw new Error(`batch run state ${batchId} has an invalid reseals list`);
+	if (record.reseals?.length && record.reseals[record.reseals.length - 1].to_digest !== record.plan_digest)
+		throw new Error(`batch run state ${batchId} plan_digest does not match its last reseal`);
 	const seenTaskIds = new Set<string>();
 	for (const child of record.children) {
 		if (
@@ -545,6 +651,14 @@ function validateLaneRecordShape(value: unknown, batchId: string): asserts value
 			throw new Error(`batch run state ${batchId} child ${child.task_id} has invalid terminal fields`);
 		if (typeof child.qa_failures !== "number" || !Number.isInteger(child.qa_failures) || child.qa_failures < 0)
 			throw new Error(`batch run state ${batchId} child ${child.task_id} has an invalid qa_failures`);
+		if (child.corrections !== undefined && (!Number.isInteger(child.corrections) || child.corrections < 0 || child.corrections > 2))
+			throw new Error(`batch run state ${batchId} child ${child.task_id} has an invalid corrections count`);
+		if (child.correction_due !== undefined && (typeof child.correction_due !== "string" || !child.correction_due || child.state !== "enrolled"))
+			throw new Error(`batch run state ${batchId} child ${child.task_id} has an invalid correction_due`);
+		if (child.tracker_closed !== undefined && child.tracker_closed !== true)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} has an invalid tracker_closed`);
+		if (child.tracker_closed === true && child.state !== "integrated" && child.state !== "released")
+			throw new Error(`batch run state ${batchId} child ${child.task_id} closed its tracker Issue before integration`);
 		const lane = child.lane as BatchLaneBinding | null | undefined;
 		if (lane !== null) {
 			if (
@@ -612,6 +726,8 @@ export function prepareBatchLaneRunState(input: {
 	budget: { max_children: number; qa_failure_limit: number };
 	max_parallel: number;
 	now: string;
+	final_verification?: string[];
+	revision_delegation?: import("./batch_delegation").RevisionDelegationGrant;
 }): BatchLaneRunStateRecord {
 	validateBatchId(input.batch_id);
 	return {
@@ -636,6 +752,13 @@ export function prepareBatchLaneRunState(input: {
 			qa_failures: 0,
 		})),
 		commits: [],
+		...(input.final_verification?.length ? { final_verification: [...input.final_verification] } : {}),
+		...(input.revision_delegation ? { revision_delegation: { ...input.revision_delegation } } : {}),
+		intent_identities: Object.fromEntries(
+			input.children
+				.filter((child) => child.intent_path !== null && child.intent_revision !== null && child.intent_content_hash !== null)
+				.map((child) => [child.task_id, { intent_path: child.intent_path!, intent_revision: child.intent_revision!, intent_content_hash: child.intent_content_hash! }]),
+		),
 		created_at: input.now,
 		updated_at: input.now,
 	};
@@ -725,6 +848,23 @@ export interface BatchLaneRunReport {
 	handoffs: BatchLaneHandoff[];
 	/** Offers refused at admission; a refused offer wrote nothing. */
 	lane_refusals?: Array<{ task_id: string; path: string; reason: string }>;
+	/**
+	 * Child Issue closures this tick attempted after integration. A failure is a
+	 * tracker observation beside the batch result, retried by the next tick.
+	 */
+	tracker_observations?: Array<{ task_id: string; status: string; message: string }>;
+	/** The completion run of the recorded final verification commands; `passed: false` marks the batch not passed. */
+	final_verification?: import("./batch_final_verification").FinalVerificationReport;
+	/** Coordinator instructions sent to Lane sessions (see BatchLaneRunStateRecord.interventions). */
+	interventions?: LaneIntervention[];
+	/** This tick's decision on the coordinator's `lane_revision` (ADR 0018). */
+	lane_revision?: { task_id: string; accepted: boolean; reason: string | null; fallback?: string };
+	delegated_revisions?: import("./batch_delegation").DelegatedRevisionRecord[];
+	reseals?: BatchLaneRunStateRecord["reseals"];
+	/** This tick's decision on the Parent's `lane_instruction`: send the text only when accepted. */
+	lane_instruction?: { task_id: string; kind: LaneIntervention["kind"]; accepted: boolean; reason: string | null };
+	/** Restored Lane leaks with their backup location (see BatchLaneRunStateRecord.restores). */
+	restores?: import("./batch_leak_restore").LaneLeakRestore[];
 	next_action: string;
 	created_at: string;
 }
@@ -739,6 +879,21 @@ export type BatchLaneHandoff =
 			executor_hosts: readonly string[];
 	  }
 	| { role: "lane-steward"; action: "release"; task_id: string; lane_branch: string }
+	| {
+			/**
+			 * The child exhausted its rework budget. The Parent reads the findings of
+			 * every round from the Lane's Kernel state, decides whether they share one
+			 * root cause, starts a new Lane session and sends one design-level
+			 * correction as `lane_instruction` kind `correction`.
+			 */
+			role: "coordinator";
+			action: "correct";
+			task_id: string;
+			reason: string;
+			corrections_used: number;
+			corrections_left: number;
+			lane_path: string;
+	  }
 	| {
 			role: "executor";
 			task_id: string;

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

@@ -0,0 +1,58 @@
+// Read-only identification of a Lane worktree from its checked-out branch.
+// A Lane sits on `imm-lane/<initiative-slug>/<task-id>` (ADR 0013), so the
+// settling Host can tell a Lane settlement from a coordinator or single-task
+// settlement without reading any batch state.
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const LANE_BRANCH = /^imm-lane\/[^/]+\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/;
+
+/** The task id the Lane at `root` was cut for, or null when `root` is not a Lane. */
+export function laneTaskOfWorkspace(root: string): string | null {
+	const branch = spawnSync("git", ["-C", root, "symbolic-ref", "--quiet", "--short", "HEAD"], {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+	});
+	if (branch.status !== 0) return null;
+	return LANE_BRANCH.exec((branch.stdout ?? "").trim())?.[1] ?? null;
+}
+
+/** True when `root` is the Lane of `taskId`: its tracker close waits for integration. */
+export function isLaneWorkspaceForTask(root: string, taskId: string): boolean {
+	return laneTaskOfWorkspace(root) === taskId;
+}
+
+function realpathOfNearest(path: string): string {
+	let current = path;
+	const suffix: string[] = [];
+	for (;;) {
+		try {
+			return join(realpathSync(current), ...suffix.reverse());
+		} catch {
+			const parent = dirname(current);
+			if (parent === current) return path;
+			suffix.push(basename(current));
+			current = parent;
+		}
+	}
+}
+
+/**
+ * Refusal text for an `edit`/`write` a Lane session aims outside its Lane, or
+ * null when `cwd` is not a Lane or the target is inside it. The target is
+ * resolved against `cwd` and through symlinks of its nearest existing
+ * ancestor. Only file-editing tools are checked: a shell command is not
+ * intercepted, and the contract says so.
+ */
+export function laneWriteRefusal(cwd: string, target: unknown): string | null {
+	if (typeof target !== "string" || !target) return null;
+	if (laneTaskOfWorkspace(cwd) === null) return null;
+	const top = spawnSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+	if (top.status !== 0) return null;
+	const laneRoot = realpathOfNearest((top.stdout ?? "").trim());
+	const resolved = realpathOfNearest(isAbsolute(target) ? target : resolve(cwd, target));
+	const inside = relative(laneRoot, resolved);
+	if (inside === "" || (inside !== ".." && !inside.startsWith(`..${sep}`) && !isAbsolute(inside))) return null;
+	return `Lane write refused: ${resolved} is outside this Lane. In a batch Lane every edit and write stays under ${laneRoot}; use the same repository-relative path inside the Lane.`;
+}

package/plugins/immune-brain/skills/BASELINE.md

@@ -108,7 +108,7 @@ An existing grant for one of these never inherits another: a stage-only
 instruction stays stage-only, a commit is not push or publication authority,
 and a valid batch capability commits only its own scope-bounded child.
 
-Routine Managed enrollment uses one current-Host native confirmation bound to the TaskIntent content hash after Planner validation. Explicit Plan-only requests stop with candidate artifacts and do not invoke Enrollment; execution-bearing requests open the native gate directly without chat pre-confirmation. Enrollment validates intent, Git ownership, scope, workspace claim, and final authority preconditions without executing acceptance descriptors; deterministic QA executes them after implementation. The routine task proceeds from that single confirmation through enrollment, execution, and QA without a second human stop. Do not request confirmation for local in-scope edits, local verification, ordinary Direct rework, scoped diff review, or completion reporting. Managed evidence, QA, Review, and completion authority remain governed by their Managed contracts; R2 does not weaken them. Managed native-authority failures fail closed with one stable reason and exactly one same-Host recovery action; never offer a Pi, Direct Path, cross-Host/worktree, unmanaged, or automatic-retry fallback.
+Routine Managed enrollment is the first step of an explicit `imm-run` entry and uses one current-Host native confirmation bound to the TaskIntent content hash after Planner validation. Planner and Brainstorm stop with candidate artifacts and never invoke Enrollment, whether or not the request also asks for execution; explicit Plan-only requests stop the same way. `imm-run` opens the native gate directly without chat pre-confirmation. Enrollment validates intent, Git ownership, scope, workspace claim, and final authority preconditions without executing acceptance descriptors; deterministic QA executes them after implementation. Once the user has entered `imm-run`, the routine task proceeds from that single confirmation through enrollment, execution, and QA with no further confirmation. Do not request confirmation for local in-scope edits, local verification, ordinary Direct rework, scoped diff review, or completion reporting. Managed evidence, QA, Review, and completion authority remain governed by their Managed contracts; R2 does not weaken them. Managed native-authority failures fail closed with one stable reason and exactly one same-Host recovery action; never offer a Pi, Direct Path, cross-Host/worktree, unmanaged, or automatic-retry fallback.
 
 For an unborn symbolic Git HEAD, the same Enrollment confirmation discloses an empty root commit. After approval, the Host creates that commit without staging project content or changing the index/worktree, then revalidates ownership and rehearses Enrollment against the new base. Git identity uses existing environment/config values with an explicit automation fallback, never config writes. Decline or pre-initialization cancellation leaves HEAD unborn; if later Enrollment fails or is cancelled, report the remaining commit. Invalid Git refs are errors, not initialization candidates.
 

package/plugins/immune-brain/skills/imm-brainstorm/SKILL.md

@@ -25,11 +25,12 @@ or all references as an entry prerequisite.
 - requested framing document: [Output Language Policy](../../dist/BASELINE.md#output-language-policy)
 
 When framing discusses later execution, describe Enrollment only as the
-current Host's native gate. A failed Managed authority interaction stays
+current Host's native gate, opened as the first step of a user-launched
+`imm-run`. Brainstorm stops after framing; the user launches `imm-planner`. A failed Managed authority interaction stays
 fail-closed: report one same-Host recovery action, never another Host,
 worktree, or unmanaged implementation.
 
 Every sourced branch closes as resolved, explicitly excluded, explicitly
 deferred, or dependent-blocked with its blocking node named, including for a
 clear zero-question request; a confirmed outcome is never conserved as a
-smaller deliverable.
+smaller deliverable, and a confirmed user scenario is a `BR-SCN-*` item with Actor, Given, When, Then, written in English, whose Then is a result the actor observes directly; framing without a user-observable change gets no invented scenario.

package/plugins/immune-brain/skills/imm-planner/SKILL.md

@@ -16,7 +16,9 @@ grants execution authority — only the native Enrollment gate can. Every Spec d
 user-owned one with no source is removed or returned for clarification. Before
 handoff it maps every upstream item and required phase exactly once and reports
 each Slice result plus the remaining gap; a plan that conserves a smaller
-deliverable than the confirmed outcome fails that check instead of passing.
+deliverable than the confirmed outcome fails that check instead of passing, and a
+Spec carries user scenarios mapped one way to acceptance, or records `no
+user-visible change` with a reason.
 
 Section routes - load a section's instructions only when its branch applies.
 Read each linked heading body up to the next heading; nested sections and
@@ -40,11 +42,11 @@ own routes instead of these stages.
 - retirement design: [Retirement Completion Contract](../../dist/imm-planner.md#retirement-completion-contract)
 - optional research dispatch: [Research Dispatch](../../dist/imm-planner.md#research-dispatch)
 
-Plan-only requests stop after candidate TaskIntent validation, plus Spec validation when the work is complex. Requests
-that include execution invoke the current Host's native Enrollment gate
-directly, without chat pre-confirmation. Native-gate failure stays fail-closed
-in that Host: report its reason and one retry action only; never suggest
-another Host, worktree, or unmanaged implementation as a fallback.
+Every request stops after candidate TaskIntent validation, plus Spec validation when the work is complex; Plan-only requests stop there too. The Planner
+never invokes the current Host's native Enrollment gate, even when the request also asks for
+execution: report the candidate and name a literal-user `imm-run` entry as the
+only next step. Never suggest another Host, worktree, or unmanaged
+implementation as a fallback.
 
 Before that handoff, confirm complete mapping of every upstream item and
 required phase with each Slice's result and the remaining gap; reject a plan