immune-brain 5.1.0 → 5.1.2

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 {
@@ -100,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;
 }
 
 /**
@@ -124,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;
 }
@@ -145,7 +200,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 +208,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 +342,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 +455,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,
@@ -493,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 (
@@ -515,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 (
@@ -525,7 +669,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 +703,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`);
@@ -580,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 {
@@ -604,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,
 	};
@@ -693,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;
 }
@@ -707,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;
@@ -756,5 +943,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"
+	);
 }

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/imm-brainstorm/SKILL.md

@@ -32,4 +32,4 @@ 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