immune-brain 4.4.1 → 4.5.0

package/plugins/immune-brain/runtime/kernel/storage.ts

@@ -480,10 +480,15 @@ function ensureSecureDirectory(root: string, relativePath: string): string {
 	return target.path;
 }
 
-export function readSecureProjectFile(
+export function readSecureProjectFile(root: string, relativePath: string): string {
+	return readSecureProjectBytes(root, relativePath).toString("utf8");
+}
+
+/** Preserve byte identity while retaining the same secure filesystem checks. */
+export function readSecureProjectBytes(
 	root: string,
 	relativePath: string,
-): string {
+): Buffer {
 	const candidate = safeCandidate(root, relativePath);
 	assertNoSymlinkSegments(candidate.root, candidate.path);
 	const before = pathStatOrNull(candidate.path);
@@ -498,7 +503,7 @@ export function readSecureProjectFile(
 		const opened = fstatSync(fd);
 		if (opened.dev !== before.dev || opened.ino !== before.ino)
 			throw new KernelStoreSecurityError(`source identity changed: ${relativePath}`);
-		const content = readFileSync(fd, "utf8");
+		const content = readFileSync(fd);
 		const after = lstatSync(candidate.path);
 		if (after.dev !== opened.dev || after.ino !== opened.ino)
 			throw new KernelStoreSecurityError(`source identity changed: ${relativePath}`);

package/plugins/immune-brain/runtime/plugin_version.ts

@@ -1,2 +1,2 @@
 // Generated by scripts/plugin_versioning.ts from the root package.json.
-export const PLUGIN_VERSION = "4.4.1" as const;
+export const PLUGIN_VERSION = "4.5.0" as const;

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

@@ -34,6 +34,25 @@ about the fix's scope, not a new bug. A trigger the accepted contract explicitly
 excludes is reported as an advisory note against that boundary, never as blocking
 rework.
 
+## Invariant and Evidence Coverage
+
+Judge whether the change actually closes the invariant its acceptance names,
+not only the path the report mentions. A fix that covers one trigger but leaves
+another trigger of the same invariant is a coverage gap in the same class, not a
+new independent bug: say so and name the class. Check the negative and bound
+behavior, not only the happy path. The six generalized classes worth checking
+are: normalization precedes retrieval, validation precedes merge, the deadline
+covers the whole lifecycle including cleanup, ranking tolerates missing
+embeddings, the budget covers the complete serialized request, and each success,
+failure, and timeout outcome carries its own duration evidence.
+
+A required check that is skipped, that matches zero tests, or whose prerequisite
+is absent does not prove the acceptance; do not accept it as evidence. Full
+suite coverage reported at a coarse pass count is not per-invariant evidence.
+Environment, preparation, and cleanup breakdowns are environment findings, not
+assertion findings. Keep automated behavioral or geometry evidence separated
+from a human quality judgment.
+
 Return exactly one JSON object with the fields required by the Loop review
 contract: `contract`, `role`, `task_id`, `snapshot_digest`, `decision` (`pass`
 or `rework`), and for `pass` include `approval` (`kind`, `authority_role`,

package/plugins/immune-brain/runtime/prompts/qa.md

@@ -20,4 +20,16 @@ Plan remains a literal-user decision.
 For elevated-risk work, check the latest referenced Spec's Design Conformance
 against implementation evidence. A local implementation mismatch is `rework`;
 return `rework` with bounded repair evidence. A structural or intended design
-change is `replan`; return `replan` with the missing design fact. QA must not approve a changed design or silently accept a deviation. If the checkpoint is `awaiting_user_successor_decision`, stop without dispatch; only a literal user may invoke `--approve-successor`.
+change is `replan`; return `replan` with the missing design fact. QA must not approve a changed design or silently accept a deviation.
+
+Judge the recorded execution evidence, not the descriptor text. A required check
+proves an acceptance invariant only when it actually executed and passed: an
+absent dependency, a prerequisite preparation failure, a skipped required check,
+or a check that matched zero tests is a failure, not a pass. Structural
+"Enrollment ready" or "descriptor valid" is not execution evidence, and a
+contract string proves nothing about provider behavior. Automated behavioral or
+geometry evidence cannot stand in for a human motion-quality judgment, and vice
+versa; keep the two claims separate. Environment, preparation, and cleanup
+breakdowns are environment findings, not assertion findings: report them with
+the descriptor reference and observed outcome rather than as a code defect.
+ If the checkpoint is `awaiting_user_successor_decision`, stop without dispatch; only a literal user may invoke `--approve-successor`.

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

@@ -22,6 +22,7 @@ import { readGitHead } from "../kernel/pi_canary_prepare";
 import { readTaskIntent } from "../kernel/intent";
 import { localRunId, readAuditTaskPair, readTaskRecordRaw, readWorkspaceStateRaw, reconcileKernelAuthority } from "../kernel/storage";
 import { pathMatchesScope } from "../workspace_scope";
+import { captureBatchReconfirmation, retainReconfirmation, ownUnpersistedBatchHead, type ReconfirmationSnapshot } from "./batch_reconfirmation";
 import { DEFAULT_DEADLINE_MS, projectBatchPlan } from "./batch_plan";
 import { batchReason, type BatchReasonKey } from "./batch_reasons";
 import { isTerminalBatchState, readBatchRunState, type BatchRunStateRecord } from "./batch_state";
@@ -44,6 +45,8 @@ export interface BatchPreflightOptions {
 }
 
 export interface BatchPreflightProjection {
+	/** Captured observations only; never serialized or used as capability. */
+	reconfirmation?: ReconfirmationSnapshot;
 	initiative_slug: string;
 	batch_branch: string;
 	is_resuming: boolean;
@@ -291,8 +294,8 @@ function porcelainEntries(root: string): Array<{ code: string; path: string }> |
 	// an unstaged modification (" M path") and silently mis-scoped the path.
 	const statusProc = spawnSync(
 		"git",
-		["-C", root, "status", "--porcelain=v1", "-z", "--no-renames", "--untracked-files=all"],
-		{ encoding: "utf8" },
+		["-C", root, "status", "--porcelain=v1", "-z", "--no-renames", "--untracked-files=all", "--ignore-submodules=none"],
+		{ encoding: "utf8", env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } },
 	);
 	if (statusProc.status !== 0) return null;
 	const entries: Array<{ code: string; path: string }> = [];
@@ -552,22 +555,26 @@ export async function projectBatchPreflight(
 	});
 	if (!planSurface.ok)
 		return reject(planSurface.key, planSurface.detail);
+	let reconfirmation: ReconfirmationSnapshot | undefined;
+	if (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"); }
+	}
 
-	return {
-		ok: true,
-		projection: {
-			initiative_slug: initiativeSlug,
-			batch_branch: batchBranch,
-			is_resuming: isResuming,
-			existing_batch: existingBatch,
-			base_head: baseHead,
-			budget: planSurface.surface.budget,
-			plan_digest: planSurface.surface.plan_digest,
-			recovery_children: planSurface.surface.recovery_children,
-			risk_by_task: planSurface.surface.risk_by_task,
-			excluded: planSurface.surface.excluded,
-		},
+	const projection: BatchPreflightProjection = {
+		initiative_slug: initiativeSlug,
+		batch_branch: batchBranch,
+		is_resuming: isResuming,
+		existing_batch: existingBatch,
+		base_head: baseHead,
+		budget: planSurface.surface.budget,
+		plan_digest: planSurface.surface.plan_digest,
+		recovery_children: planSurface.surface.recovery_children,
+		risk_by_task: planSurface.surface.risk_by_task,
+		excluded: planSurface.surface.excluded,
 	};
+	if (reconfirmation) Object.defineProperty(projection, "reconfirmation", { value: reconfirmation });
+	return { ok: true, projection };
 }
 
 /**
@@ -700,6 +707,11 @@ export async function authorizeBatch<HostRejection>(
 	// ADR-0005 Decision 1: a resume of an intact, still-binding authorization
 	// reuses it instead of opening a second native gate. Anything that no longer
 	// binds falls through to the gate below, which names the reason.
+	const ownsUnpersistedHead = isResuming && existingBatch !== null && existingBatch.plan_digest === planDigest &&
+		expectedBatchHead(existingBatch) !== baseHead && ownUnpersistedBatchHead(root, existingBatch, baseHead);
+	if (isResuming && existingBatch && !existingBatch.commits.length && existingBatch.children[0]?.state === "settled" &&
+		expectedBatchHead(existingBatch) !== baseHead && !ownsUnpersistedHead)
+		return { outcome: "rejected", rejection: batchRejection("head_moved", "first unpersisted commit provenance is invalid") };
 	const reuseBlockers: string[] = [];
 	if (isResuming && existingBatch) {
 		if (isExistingExpired) reuseBlockers.push("batch_authorization_expired");
@@ -707,7 +719,7 @@ export async function authorizeBatch<HostRejection>(
 		if (existingBatch.batch_state !== "running") reuseBlockers.push("batch_not_running");
 		if (existingBatch.plan_digest !== planDigest) reuseBlockers.push("batch_plan_digest_changed");
 		if (existingBatch.branch !== batchBranch) reuseBlockers.push("batch_branch_changed");
-		if (expectedBatchHead(existingBatch) !== baseHead) reuseBlockers.push("batch_head_lineage_moved");
+		if (expectedBatchHead(existingBatch) !== baseHead && !ownsUnpersistedHead) reuseBlockers.push("batch_head_lineage_moved");
 	}
 	const reuseAuthorization = isResuming && reuseBlockers.length === 0;
 	const expiresAt = reuseAuthorization ? existingBatch!.authorization_expires_at : budget.deadline_at;
@@ -753,7 +765,7 @@ export async function authorizeBatch<HostRejection>(
 	if (drift.plan_digest !== planDigest)
 		return { outcome: "rejected", rejection: batchRejection("plan_changed", drift.plan_digest) };
 	if (drift.base_head === null) return { outcome: "rejected", rejection: batchRejection("repository_became_unreadable") };
-	if (drift.base_head !== baseHead)
+	if (drift.base_head !== baseHead || (ownsUnpersistedHead && !ownUnpersistedBatchHead(root, existingBatch!, baseHead)))
 		return { outcome: "rejected", rejection: batchRejection("head_moved", drift.base_head) };
 
 	// The drift projection's own claim read happened before its plan read; this
@@ -778,6 +790,10 @@ export async function authorizeBatch<HostRejection>(
 	if (Date.parse(expiresAt) <= Date.now())
 		return { outcome: "rejected", rejection: batchRejection("confirmation_failed", "confirmed batch deadline expired before authorization issuance") };
 
+	if (projection.reconfirmation) {
+		try { projection.reconfirmation.assertUnchanged(); }
+		catch { return { outcome: "rejected", rejection: batchRejection("plan_changed") }; }
+	}
 	const binding: BatchAuthorizationBinding = {
 		batch_id: batchId,
 		initiative_slug: initiativeSlug,
@@ -790,6 +806,7 @@ export async function authorizeBatch<HostRejection>(
 		expires_at: expiresAt,
 		nonce: options.nonce,
 	};
+	if (projection.reconfirmation) retainReconfirmation(binding.nonce, binding.expires_at, projection.reconfirmation);
 	return {
 		outcome: "authorized",
 		batch_id: batchId,

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

@@ -0,0 +1,194 @@
+// Read-only eligibility for a first, zero-commit plan reconfirmation.
+import { spawnSync } from "node:child_process";
+import { computeBatchPlanDigest, type BatchPlanChild as DigestChild } from "../kernel/batch_authority";
+import { canonicalIntentHash, parseTaskIntentV1, readTaskIntent } from "../kernel/intent";
+import { projectAssurance } from "../kernel/assurance_projection";
+import { localRunId, readAuditTaskPair, readSecureProjectBytes, readWorkspaceStateRaw } from "../kernel/storage";
+import { readRunRowByTask, withKernelRead } from "../kernel/sqlite_store";
+import { taskRevisionIdentity, taskCommitRevisionIdentity, pathMatchesScope } from "../workspace_scope";
+import { projectTask } from "../kernel/completion";
+import { isTerminalBatchState, type BatchRunStateRecord } from "./batch_state";
+import type { BatchPlanChild } from "./types";
+
+const oid = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const id = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const batchAuthor = process.env.GIT_AUTHOR_NAME || "Immune-Brain Batch";
+const decode = (bytes: Uint8Array) => new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+function refuse(): never { throw new Error("plan_digest mismatch: batch plan reconfirmation is not eligible"); }
+function matchesLocalProof(localJson: string | null, exported: object): boolean {
+	return localJson !== null && JSON.stringify(Object.entries(JSON.parse(localJson)).sort()) === JSON.stringify(Object.entries(exported).sort());
+}
+function git(root: string, args: string[]): string {
+	const r = spawnSync("git", ["-C", root, ...args], { encoding: "buffer", maxBuffer: 262144, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } });
+	if (r.status !== 0) refuse();
+	return decode(r.stdout);
+}
+// Recognize only the first commit/persist crash window; never query Git with
+// an OID read from mutable evidence. The existing Git port performs final adoption.
+export function ownUnpersistedBatchHead(root: string, record: BatchRunStateRecord, head: string): boolean {
+	try {
+		if (!oid.test(head) || !oid.test(record.base_head) || !id.test(record.batch_id) || record.commits.length ||
+			record.children[0]?.state !== "settled" || record.children.some(c => c.commit !== null)) return false;
+		const task = record.children[0].task_id;
+		if (!id.test(task)) return false;
+		const evidence = JSON.parse(decode(readSecureProjectBytes(root, `.imm/state/batches/commits/${record.batch_id}-${task}.json`)));
+		if (evidence.contract !== "assurance_kernel/batch_commit_evidence/v1" || evidence.batch_id !== record.batch_id ||
+			evidence.task_id !== task || evidence.commit !== head || evidence.parent_head !== record.base_head) return false;
+		if (git(root, ["symbolic-ref", "--short", "HEAD"]).trim() !== record.branch) return false;
+		const parents = git(root, ["rev-list", "--parents", "-n", "1", head]).trim().split(/\s+/).slice(1);
+		if (parents.length !== 1 || parents[0] !== record.base_head) return false;
+		const metadata = git(root, ["show", "-s", "--format=%an%x00%s%x00%(trailers:key=Immune-Brain-Batch,valueonly)", head]).split("\0");
+		if (metadata[0] !== batchAuthor || !metadata[1]?.startsWith(`imm(${task}):`) || metadata[2]?.trim() !== record.batch_id) return false;
+		const run = localRunId(root, task);
+		if (!run || !id.test(run)) return false;
+		const pair = readAuditTaskPair(root, task, run);
+		if (!pair || pair.record.contract !== "assurance_kernel/task_record/v4" || pair.record.lifecycle !== "done" || pair.proof.terminal_lifecycle !== "done") return false;
+		const local = withKernelRead(root, db => readRunRowByTask(db, task));
+		if (!local || local.run_id !== run || local.state !== "done" || !matchesLocalProof(local.terminal_proof_json, pair.proof)) return false;
+		for (const file of ["task-record.json", "terminal-proof.json"]) {
+			const path = `.imm/audit/${task}/${run}/${file}`;
+			if (!readSecureProjectBytes(root, path).equals(Buffer.from(git(root, ["show", `${head}:${path}`])))) return false;
+		}
+		const paths = git(root, ["diff-tree", "--no-commit-id", "--name-only", "--no-renames", "-z", "-r", head]).split("\0").filter(Boolean);
+		if (!paths.length || paths.some(path => !path.startsWith(`.imm/audit/${task}/${run}/`) &&
+			!pair.record.intent_snapshot.scope_hint.some(s => pathMatchesScope(path, s)))) return false;
+		const identity = taskCommitRevisionIdentity(root, pair.record.intent_snapshot.scope_hint, pair.record.git_base_head, head);
+		if (!projectTask(pair.record.intent_snapshot, pair.record, identity.diff_hash, pair.record.intent_ref.content_hash, identity.changed_paths).complete) return false;
+		return git(root, ["rev-parse", "HEAD"]).trim() === head;
+	} catch { return false; }
+}
+
+export interface ReconfirmationSnapshot {
+	root: string;
+	plan_digest: string;
+	stateBytes: Buffer;
+	/** Synchronous read-only check repeated under the state owner's lock. */
+	assertUnchanged(): void;
+}
+
+// Ephemeral captured observations, not authority: the runner independently
+// validates the native capability. Entries expire and are discarded on application.
+const confirmations = new Map<string, { snapshot: ReconfirmationSnapshot; expires: number }>();
+export function retainReconfirmation(nonce: string, expires: string, snapshot: ReconfirmationSnapshot): void {
+	for (const [key, value] of confirmations) if (value.expires <= Date.now()) confirmations.delete(key);
+	if (confirmations.has(nonce)) refuse();
+	confirmations.set(nonce, { snapshot, expires: Date.parse(expires) });
+}
+export function takeReconfirmation(nonce: string): ReconfirmationSnapshot {
+	const found = confirmations.get(nonce); confirmations.delete(nonce);
+	if (!found || found.expires <= Date.now()) refuse();
+	return found.snapshot;
+}
+
+export async function captureBatchReconfirmation(root: string, record: BatchRunStateRecord, children: BatchPlanChild[]): Promise<ReconfirmationSnapshot> {
+	if (!id.test(record.batch_id) || !oid.test(record.base_head) || isTerminalBatchState(record.batch_state) || record.commits.length ||
+		record.children.some(c => c.commit !== null || c.state === "committed") || record.children.length !== children.length || !children.length) refuse();
+	const assertNoCommitEvidence = () => {
+		for (const child of record.children) {
+			if (!id.test(child.task_id)) refuse();
+			const path = `.imm/state/batches/commits/${record.batch_id}-${child.task_id}.json`;
+			let missing = false;
+			try { readSecureProjectBytes(root, path); }
+			catch (error) {
+				if (error instanceof Error && error.message === `source_missing: ${path}`) missing = true;
+				else refuse();
+			}
+			if (!missing) refuse();
+		}
+	};
+	assertNoCommitEvidence();
+	const statePath = `.imm/state/batches/${record.batch_id}.json`;
+	const stateBytes = readSecureProjectBytes(root, statePath);
+	if (JSON.stringify(JSON.parse(decode(stateBytes))) !== JSON.stringify(record)) refuse();
+	const files = new Map<string, Buffer>();
+	const capture = (path: string) => { const bytes = readSecureProjectBytes(root, path); files.set(path, bytes); return bytes; };
+	const oldChildren: DigestChild[] = [];
+	const changed: Array<{ task: string; run: string; identity: string; local: string }> = [];
+	let scope: string[] | null = null;
+	const workspace = readWorkspaceStateRaw(root);
+	if (workspace.state.current_working !== null) refuse();
+	for (const [index, child] of children.entries()) {
+		const previous = record.children[index]!;
+		if (!id.test(child.task_id) || child.task_id !== previous.task_id || child.slice_id !== previous.slice_id ||
+			JSON.stringify(child.blocked_by) !== JSON.stringify(previous.blocked_by) || child.intent_path !== `docs/plans/${child.task_id}.intent.json`) refuse();
+		const old = parseTaskIntentV1(JSON.parse(git(root, ["show", `${record.base_head}:${child.intent_path}`])));
+		if (old.task_id !== child.task_id) refuse();
+		const oldHash = canonicalIntentHash(old);
+		oldChildren.push({ task_id: child.task_id, blocked_by: [...child.blocked_by], intent_path: child.intent_path, intent_revision: old.revision, intent_content_hash: oldHash });
+		const currentBytes = capture(child.intent_path);
+		const current = parseTaskIntentV1(JSON.parse(decode(currentBytes)));
+		const currentHash = canonicalIntentHash(current);
+		const tracked = readTaskIntent(root, child.task_id, child.intent_path);
+		if (currentHash !== tracked.content_hash || currentHash !== child.intent_content_hash || current.revision !== child.intent_revision) refuse();
+		if (currentHash === oldHash) continue;
+		if (scope !== null || previous.state === "pending" || previous.state === "skipped_blocked" || current.revision <= old.revision || current.goal !== old.goal || current.owner !== old.owner) refuse();
+		const run = localRunId(root, child.task_id);
+		if (!run || !id.test(run)) refuse();
+		const local = withKernelRead(root, db => readRunRowByTask(db, child.task_id));
+		if (!local || local.run_id !== run || local.state !== "done" || local.enrollment_event_id !== `enroll-${child.task_id}-${local.created_at}` ||
+			Date.parse(local.created_at) > Date.parse(record.updated_at)) refuse();
+		const pair = readAuditTaskPair(root, child.task_id, run);
+		if (!pair || pair.record.contract !== "assurance_kernel/task_record/v4") refuse();
+		const r = pair.record;
+		if (r.lifecycle !== "done" || r.intent_ref.content_hash !== currentHash || canonicalIntentHash(r.intent_snapshot) !== currentHash ||
+			r.git_base_head !== record.base_head || pair.proof.terminal_lifecycle !== "done") refuse();
+		const terminal = r.history.at(-1);
+		if (terminal?.type !== "complete" || terminal.from_state !== "active:frozen" || terminal.to_state !== "done:frozen" || terminal.id !== pair.proof.terminal_event_id) refuse();
+		const recordPath = `.imm/audit/${child.task_id}/${run}/task-record.json`;
+		const proofPath = `.imm/audit/${child.task_id}/${run}/terminal-proof.json`;
+		if (!capture(recordPath).equals(Buffer.from(local.record_json))) refuse();
+		const capturedProof = JSON.parse(decode(capture(proofPath)));
+		if (!matchesLocalProof(local.terminal_proof_json, capturedProof) || !matchesLocalProof(local.terminal_proof_json, pair.proof)) refuse();
+		const identity = taskRevisionIdentity(root, r.intent_snapshot.scope_hint, r.git_base_head, r.task_id);
+		const projection = await projectAssurance(root, child.task_id, (cwd, task) => {
+			if (task.contract !== "assurance_kernel/task_record/v4" || !task.git_base_head) refuse();
+			return taskRevisionIdentity(cwd, task.intent_snapshot.scope_hint, task.git_base_head, task.task_id);
+		});
+		if (projection.error || projection.claim || projection.projection.run_id !== run || projection.projection.lifecycle !== "done" ||
+			!projection.projection.completion_ready || projection.projection.intent_content_hash !== currentHash || projection.projection.diff_hash !== identity.diff_hash ||
+			!projection.projection.fresh_approval_kinds.includes("qa") ||
+			(projection.projection.risk !== "routine" && !projection.projection.fresh_approval_kinds.includes("review"))) refuse();
+		scope = r.intent_snapshot.scope_hint;
+		changed.push({ task: child.task_id, run, identity: JSON.stringify(identity), local: JSON.stringify(local) });
+	}
+	if (computeBatchPlanDigest(oldChildren) !== record.plan_digest || changed.length !== 1 || scope === null) refuse();
+	const confirmedScope = scope;
+	const owner = changed[0]!;
+	const status = () => git(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignore-submodules=none"]);
+	const statusBytes = status();
+	const entries = statusBytes.split("\0").filter(Boolean);
+	// This bounded path refuses renames; staged regular edits/additions/deletions
+	// are enough for a revised child and cannot hide a second source path.
+	for (const entry of entries) {
+		const code = entry.slice(0, 2), path = entry.slice(3);
+		if (code[1] !== " " || !["A", "M", "D"].includes(code[0]!) ||
+			(!path.startsWith(`.imm/audit/${owner.task}/${owner.run}/`) &&
+			!confirmedScope.some(s => pathMatchesScope(path, s)))) refuse();
+	}
+	const flagsBytes = git(root, ["ls-files", "-v"]);
+	const flags = flagsBytes.split("\n").filter(Boolean);
+	if (flags.some(line => line[0] === "S" || line[0] !== line[0]?.toUpperCase())) refuse();
+	const head = () => git(root, ["rev-parse", "HEAD"]).trim();
+	const branch = () => git(root, ["symbolic-ref", "--short", "HEAD"]).trim();
+	if (head() !== record.base_head || branch() !== record.branch) refuse();
+	const assertDeliveryUnchanged = () => {
+		for (const c of changed) {
+			const pair = readAuditTaskPair(root, c.task, c.run);
+			if (!pair || pair.record.contract !== "assurance_kernel/task_record/v4" || !pair.record.git_base_head) refuse();
+			const local = withKernelRead(root, db => readRunRowByTask(db, c.task));
+			const diff = taskRevisionIdentity(root, pair.record.intent_snapshot.scope_hint, pair.record.git_base_head, c.task);
+			if (localRunId(root, c.task) !== c.run || JSON.stringify(local) !== c.local || JSON.stringify(diff) !== c.identity) refuse();
+		}
+	};
+	const assertUnchanged = () => {
+		assertNoCommitEvidence();
+		if (!readSecureProjectBytes(root, statePath).equals(stateBytes) || head() !== record.base_head || branch() !== record.branch || status() !== statusBytes || git(root, ["ls-files", "-v"]) !== flagsBytes ||
+			readWorkspaceStateRaw(root).revision !== workspace.revision) refuse();
+		for (const [path, bytes] of files) if (!readSecureProjectBytes(root, path).equals(bytes)) refuse();
+		assertDeliveryUnchanged();
+	};
+	assertUnchanged();
+	const plan_digest = computeBatchPlanDigest(oldChildren.map((old, index) => ({ ...old,
+		intent_revision: children[index]!.intent_revision!, intent_content_hash: children[index]!.intent_content_hash! })));
+	return { root, plan_digest, stateBytes, assertUnchanged };
+}

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

@@ -23,6 +23,7 @@ export function batchQaFailureFacts(record: Pick<TaskRecord, "history"> & { find
 		recovery_findings: record.findings.filter(f => f.status === "open").map(f => ({ id: f.id, kind: f.kind, status: f.status, acceptance_id: f.acceptance_id })) };
 }
 import type { BatchPlanChild } from "./types";
+import { ownUnpersistedBatchHead, takeReconfirmation } from "./batch_reconfirmation";
 import {
 	type BatchRunnerGitPort,
 	type BatchGitPreflightResult,
@@ -38,6 +39,7 @@ import {
 	prepareBatchRunState,
 	readBatchRunState,
 	writeBatchRunState,
+	replaceBatchRunState,
 	writeBatchRunReport,
 } from "./batch_state";
 
@@ -322,6 +324,11 @@ function externalHeadDriftMessage(root: string, record: BatchRunStateRecord): st
 }
 
 async function validatePersistedRun(input: StartBatchInput, record: BatchRunStateRecord): Promise<void> {
+	if (!record.commits.length && record.children[0]?.state === "settled" && existsSync(join(input.root, ".git"))) {
+		const head = spawnSync("git", ["-C", input.root, "rev-parse", "HEAD"], { encoding: "utf8" });
+		if (head.status !== 0 || (head.stdout.trim() !== record.base_head && !ownUnpersistedBatchHead(input.root, record, head.stdout.trim())))
+			throw new Error("first unpersisted batch commit provenance is invalid");
+	}
 	const plan = input.registry.children(input.capability);
 	if (record.plan_digest !== computeBatchPlanDigest(plan) ||
 		record.children.length !== plan.length || record.children.some((child, index) => {
@@ -384,7 +391,7 @@ function replayTerminal(
 	);
 }
 
-function validateRunAuthorization(input: StartBatchInput, existing: BatchRunStateRecord | null): void {
+function validateRunAuthorization(input: StartBatchInput, existing: BatchRunStateRecord | null): ValidatedBatchAuthorization {
 	const authorized = input.kernel.validateBatchAuthorization({
 		registry: input.registry,
 		capability: input.capability,
@@ -409,6 +416,32 @@ function validateRunAuthorization(input: StartBatchInput, existing: BatchRunStat
 	if (computeBatchPlanDigest(children) !== authorized.plan_digest ||
 		input.plan_digest !== authorized.plan_digest || input.base_head !== authorized.base_head)
 		throw new Error("batch run input does not match the authorized plan or base_head");
+	return authorized;
+}
+
+function applyPlanReconfirmation(input: StartBatchInput, existing: BatchRunStateRecord): BatchRunStateRecord {
+	if (existing.plan_digest === input.plan_digest) return existing;
+	const next = { ...existing, plan_digest: input.plan_digest, confirmation_time: input.confirmation_time,
+		authorization_expires_at: input.authorization_expires_at, budget: input.budget };
+	if (!existing.branch || input.batch_id !== existing.batch_id || input.initiative_slug !== existing.initiative_slug || input.base_head !== existing.base_head ||
+		input.budget.max_children !== existing.budget.max_children || input.budget.qa_failure_limit !== existing.budget.qa_failure_limit)
+		throw new Error("plan_digest mismatch: reconfirmation binding changed");
+	const validate = () => {
+		const plan = input.registry.children(input.capability);
+		if (existing.children.length !== plan.length || plan.some((child, index) => {
+			const old = existing.children[index]!, nextChild = input.children[index];
+			return !nextChild || old.task_id !== child.task_id || old.slice_id !== nextChild.slice_id ||
+				JSON.stringify(old.blocked_by) !== JSON.stringify(child.blocked_by) || JSON.stringify(nextChild.blocked_by) !== JSON.stringify(child.blocked_by);
+		})) throw new Error("plan_digest mismatch: reconfirmation topology changed");
+		const { issued_at: _issuedAt, ...binding } = validateRunAuthorization(input, { ...existing, plan_digest: input.plan_digest });
+		if (binding.branch !== existing.branch) throw new Error("plan_digest mismatch: reconfirmation branch changed");
+		prepareBatchRunState(input);
+		return input.registry.inspect(input.capability, binding);
+	};
+	const authority = validate();
+	const captured = takeReconfirmation(authority.nonce);
+	if (captured.root !== input.root || captured.plan_digest !== input.plan_digest) throw new Error("plan_digest mismatch: captured reconfirmation does not match run input");
+	return replaceBatchRunState(input.root, captured.stateBytes, next, () => { captured.assertUnchanged(); validate(); });
 }
 
 export async function startBatch(input: StartBatchInput): Promise<BatchRunReport> {
@@ -460,7 +493,9 @@ async function startBatchLocked(input: StartBatchInput): Promise<BatchRunReport>
 	}
 
 	let existing = readBatchRunState(input.root, input.batch_id);
+	const reconfirmed = existing !== null && existing.plan_digest !== input.plan_digest;
 	if (existing) {
+		existing = applyPlanReconfirmation(input, existing);
 		try {
 			await validatePersistedRun(input, existing);
 		} catch (error) {
@@ -487,7 +522,7 @@ async function startBatchLocked(input: StartBatchInput): Promise<BatchRunReport>
 			nextConfirmation > priorConfirmation &&
 			Number.isFinite(nextExpiry) &&
 			nextExpiry > Date.now();
-		if (!freshAuthorization) {
+		if (!freshAuthorization && !reconfirmed) {
 			return finalize(
 				input.root,
 				existing,
@@ -496,7 +531,7 @@ async function startBatchLocked(input: StartBatchInput): Promise<BatchRunReport>
 			);
 		}
 
-		validateRunAuthorization(input, existing);
+		if (!reconfirmed) validateRunAuthorization(input, existing);
 		prepareBatchRunState({ ...input, now: input.now });
 		const remapped = await Promise.all(
 			existing.children.map(async (child) => {
@@ -863,7 +898,8 @@ export async function resumeBatch(
 	projection: (root: string, taskId: string) => Promise<AssuranceProjectionResult>,
 ): Promise<BatchRunReport> {
 	let existing = readBatchRunState(input.root, input.batch_id);
-	if (!existing) return startBatch(input);
+	if (!existing || existing.batch_state === "needs_human") return startBatch(input);
+	existing = applyPlanReconfirmation(input, existing);
 	try {
 		await validatePersistedRun(input, existing);
 	} catch (error) {
@@ -877,7 +913,6 @@ export async function resumeBatch(
 	}
 	if (isTerminalBatchState(existing.batch_state))
 		return replayTerminal(input.root, existing);
-	if (existing.batch_state === "needs_human") return startBatch(input);
 
 	// An enrolled-but-unsettled child must reach its own Kernel terminal
 	// settlement before anything else, even under an expired authorization:
@@ -1103,6 +1138,8 @@ async function driveInterruptedChild(
 					intentPath,
 				});
 			};
+			if (existing && !record.commits.length && existsSync(join(input.root, ".git")) && !ownUnpersistedBatchHead(input.root, record, existing.commit))
+				throw new Error("first unpersisted batch commit provenance is invalid");
 			const adopted =
 				existing ??
 				(await doCommit().catch((error: unknown) => {

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

@@ -4,7 +4,7 @@
 import { existsSync, mkdirSync, openSync, closeSync, writeFileSync, renameSync, lstatSync, constants, rmSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
-import { readSecureProjectFile, withKernelStoreLock } from "../kernel/storage";
+import { readSecureProjectFile, readSecureProjectBytes, withKernelStoreLock } from "../kernel/storage";
 import type { BatchPlanChild } from "./types";
 
 export type BatchRunState =
@@ -243,12 +243,18 @@ export function prepareBatchRunState(input: {
 	return prepared;
 }
 
+/** Validate a captured snapshot without reading or writing filesystem state. */
+export function parseBatchRunState(raw: string, batchId: string): BatchRunStateRecord {
+	validateBatchId(batchId);
+	const parsed: unknown = JSON.parse(raw);
+	validateRecordShape(parsed, batchId);
+	return parsed;
+}
+
 export function readBatchRunState(root: string, batchId: string): BatchRunStateRecord | null {
 	const path = statePath(batchId);
 	if (!existsSync(join(root, path))) return null;
-	const parsed: unknown = JSON.parse(readSecureProjectFile(root, path));
-	validateRecordShape(parsed, batchId);
-	return parsed;
+	return parseBatchRunState(readSecureProjectFile(root, path), batchId);
 }
 
 function ensureSecureDirectory(root: string, relative: string): string {
@@ -287,6 +293,19 @@ function writeFileAtomically(root: string, relative: string, bytes: string): voi
 	}
 }
 
+/** Replace an existing authorization only after a locked expected-byte check. */
+export function replaceBatchRunState(root: string, expected: Buffer, next: BatchRunStateRecord, validate: () => void): BatchRunStateRecord {
+	const path = statePath(next.batch_id);
+	validateRecordShape(next, next.batch_id);
+	return withKernelStoreLock(root, () => {
+		if (!readSecureProjectBytes(root, path).equals(expected)) throw new Error("batch state CAS mismatch");
+		validate();
+		const stored = { ...next, updated_at: new Date().toISOString() };
+		writeFileAtomically(root, path, canonicalBytes(stored));
+		return stored;
+	});
+}
+
 export function writeBatchRunState(
 	root: string,
 	record: BatchRunStateRecord,

package/plugins/immune-brain/runtime/v4_runtime.ts

@@ -176,6 +176,15 @@ async function runKernelCli(args: string[], root: string): Promise<{
 	// status --json, and the explicit audit command. All other kernel
 	// subcommands (readiness, journal, migrate) are retired.
 	const sub = args[0] ?? "";
+	// The canonical author shape is discoverable before any error probing: a
+	// caller who does not know the destination/stdin contract reads it here
+	// instead of discovering it through a failed call.
+	if (sub === "intent" && (args[1] === "--help" || args[1] === "help" || args[1] === undefined))
+		return {
+			stdout: `${intentAuthorHelp()}\n`,
+			stderr: "",
+			returncode: 0,
+		};
 	// The explicit claimless storage-layout migration is reachable here: a
 	// worktree still on the retired file store has no other entry point, and
 	// every mutating subcommand stays fail-closed behind it.
@@ -224,6 +233,51 @@ async function runCli(command: string, args: string[], root: string): Promise<{
 	};
 }
 
+/**
+ * The canonical TaskIntent author contract, printed by `imm-kernel intent` and
+ * `imm-kernel intent --help`. It states destination, stdin, and the strict v2
+ * descriptor shape before a caller has to discover them by failing a call.
+ */
+export function intentAuthorHelp(): string {
+	return [
+		"imm-kernel intent author <destination> --stdin --json",
+		"  destination: docs/plans/<task-id>.intent.json (created exclusively; never overwritten)",
+		"  stdin:       the complete candidate TaskIntent JSON on file descriptor 0",
+		"  stdout:      { valid, enrollment_ready, intent_ref, git_base_initialization_required, ... }",
+		"",
+		"imm-kernel intent validate <path> --json",
+		"",
+		"Candidate shape (assurance_kernel/task_intent/v1):",
+		JSON.stringify(
+			{
+				contract: "assurance_kernel/task_intent/v1",
+				task_id: "<task-id>",
+				owner: "user",
+				goal: "<one closable outcome>",
+				risk: "routine|material|critical",
+				revision: 1,
+				scope_hint: ["<every file the slice touches>"],
+				acceptance: [
+					{
+						id: "<ID>",
+						assertion: "<observable invariant>",
+						verification: JSON.stringify({
+							contract: "assurance_kernel/verification_descriptor/v2",
+							command: { executable: "bun", argv: ["test", "tests/<focused>.test.ts"], cwd: ".", timeout_ms: 180000, max_output_bytes: 196608 },
+							environment: { prepare: null, writable_paths: [] },
+						}),
+					},
+				],
+			},
+			null,
+			2,
+		),
+		"",
+		"Unknown fields are rejected; the descriptor parser is strict v2 and never infers a runner.",
+		"A v1 descriptor is historical-only and needs an explicit Intent revision before execution.",
+	].join("\n");
+}
+
 async function main(argv: string[]): Promise<number> {
 	const mode = argv[0];
 	const root = process.cwd();