immune-brain 4.4.0 → 4.5.0

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

@@ -12,7 +12,18 @@ import {
 	computeBatchPlanDigest,
 } from "../kernel/batch_authority";
 import type { AssuranceProjectionResult } from "../kernel/assurance_projection";
+import type { TaskRecord } from "../kernel/types";
+import { deriveAssuranceRecovery, type AssuranceRecovery, type TaskRecordRead } from "../assurance/coordinator";
+import type { QaCheckDiagnostic } from "../assurance/qa";
+
+/** Failed atomic QA attempts observed through Kernel history, including Parent-driven QA. */
+export function batchQaFailureFacts(record: Pick<TaskRecord, "history"> & { findings: NonNullable<TaskRecordRead["record"]>["findings"] }) {
+	const failed = record.history.filter((event) => event.type === "request_rework" && event.authority?.authority_kind === "qa");
+	return { qa_failure_count: failed.length, last_qa_failure_at: failed.at(-1)?.at ?? null,
+		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,
@@ -28,6 +39,7 @@ import {
 	prepareBatchRunState,
 	readBatchRunState,
 	writeBatchRunState,
+	replaceBatchRunState,
 	writeBatchRunReport,
 } from "./batch_state";
 
@@ -75,7 +87,7 @@ export interface BatchRunnerKernelPort {
 	 * persistence. Uses the real AssuranceProjectionResult contract; batch
 	 * ownership of the claim is verified separately through the authoritative
 	 * batch registry, because the Kernel claim carries no batch id. */
-	projectTask(root: string, taskId: string): Promise<AssuranceProjectionResult>;
+	projectTask(root: string, taskId: string): Promise<AssuranceProjectionResult & { qa_failure_count?: number; last_qa_failure_at?: string | null; recovery_findings?: NonNullable<TaskRecordRead["record"]>["findings"] }>;
 	/** Authoritative batch ownership check: true when the task's Kernel claim
 	 * is held under this batch's derived capability (consumed child slot). */
 	ownsTaskClaim(taskId: string): boolean;
@@ -92,13 +104,14 @@ export interface BatchRunnerKernelPort {
 	}): ValidatedBatchAuthorization;
 }
 
-export type BatchChildAdvanceResult =
+export type BatchChildAdvanceResult = { diagnostics?: QaCheckDiagnostic[]; environment_failure?: boolean; recovery?: AssuranceRecovery } & (
 	| { state: "completed" }
 	| { state: "stopped" }
 	| { state: "failed"; reason: string }
 	| { state: "rework"; operation: "qa" | "review"; summary: string }
 	| { state: "blocked"; reason: string }
-	| { state: "review_ready"; operation_id: string };
+	| { state: "review_ready"; operation_id: string }
+	| { state: "review_preparation_failed"; operation: "review"; operation_id: string; reason: string });
 
 export interface StartBatchInput {
 	root: string;
@@ -166,13 +179,13 @@ function isAuthorizationExpiryError(error: unknown): boolean {
 	return error instanceof BatchAuthorizationExpiryError;
 }
 
-function requireFreshProjection(
-	result: AssuranceProjectionResult,
+function requireFreshProjection<T extends AssuranceProjectionResult>(
+	result: T,
 	taskId: string,
-): AssuranceProjectionResult & { error: null } {
+): T & { error: null } {
 	if (result.error !== null)
 		throw new Error(`cannot reconcile Kernel projection for ${taskId}: ${result.error}`);
-	return result as AssuranceProjectionResult & { error: null };
+	return result as T & { error: null };
 }
 
 /** Next pending child whose direct dependents are all committed. */
@@ -216,6 +229,29 @@ function reportFor(
 	};
 }
 
+/** Derived observation only: Parent must re-read Kernel ownership before execution. */
+function executorHandoff(
+	record: BatchRunStateRecord,
+	taskId: string,
+	fresh: AssuranceProjectionResult & { error: null; recovery_findings?: NonNullable<TaskRecordRead["record"]>["findings"] },
+	failure: { state?: string; environment_failure?: boolean; diagnostics?: QaCheckDiagnostic[] } = {},
+): BatchRunReport {
+	const recovery = deriveAssuranceRecovery(taskId, fresh, failure, fresh.recovery_findings);
+	return {
+		...reportFor(record, null, recovery?.next_action ?? (fresh.projection.artifact_state === "frozen"
+			? "The child is frozen with pending QA. Call advance_assurance once; follow its diagnostics before retrying, then submit any reserved Review before batch continuation."
+			: "Route the enrolled child to foreground Executor, implement and stage its scoped work, then call Kernel advance_assurance. Submit any reserved Review verdict before continuing start_unattended_batch with the same Initiative.")),
+		...(recovery ? { recovery } : {}),
+		...(failure.diagnostics?.length ? { diagnostics: failure.diagnostics } : {}),
+		handoff: recovery?.category === "authorization" ? undefined : {
+			role: "executor", task_id: taskId,
+			run_id: fresh.projection.run_id ?? null,
+			record_revision: fresh.projection.record_revision,
+			next_obligation: fresh.projection.next_obligation,
+		},
+	};
+}
+
 /** review-3(6th round): persist the single run report when the batch
  * stops — including a needs_human park, which ends the current run even
  * though the batch remains resumable after a human decision. */
@@ -224,8 +260,9 @@ function finalize(
 	record: BatchRunStateRecord,
 	reason: string | null,
 	nextAction: string,
+	details: Pick<BatchRunReport, "recovery" | "diagnostics"> = {},
 ): BatchRunReport {
-	const report = reportFor(record, reason, nextAction);
+	const report = { ...reportFor(record, reason, nextAction), ...details };
 	if (isTerminalBatchState(record.batch_state) || record.batch_state === "needs_human") {
 		writeBatchRunReport(root, report);
 	}
@@ -287,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) => {
@@ -349,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,
@@ -374,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> {
@@ -425,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) {
@@ -452,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,
@@ -461,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) => {
@@ -525,7 +595,6 @@ async function startBatchLocked(input: StartBatchInput): Promise<BatchRunReport>
 			authorization_expires_at: input.authorization_expires_at,
 			budget: input.budget,
 			batch_state: "running",
-			consecutive_qa_failures: 0,
 			children: resumedChildren,
 		});
 	}
@@ -786,105 +855,11 @@ async function startBatchLocked(input: StartBatchInput): Promise<BatchRunReport>
 			break;
 		}
 		}
-	// Drive the child through the Kernel obligation surface only; rework
-		// below the limit retries the same child in this inner loop.
-		let childTerminal = false;
-		while (!childTerminal) {
-		const terminal = await input.kernel.advanceTask(input.root, child.task_id);
-		if (terminal.state === "completed") {
-			childTerminal = true;
-			// review-6: a successful settlement resets the consecutive-QA-failure
-			// counter so separated failures do not park later children.
-			record.consecutive_qa_failures = 0;
-			record.children = record.children.map((c) =>
-				c.task_id === child.task_id ? { ...c, state: "settled", reason: null } : c,
-			);
-			persist();
-			// Scope-bound commit; a lineage failure fails the whole batch.
-			try {
-				const planChild = input.children.find((c) => c.task_id === child.task_id);
-				const intentPath = planChild?.intent_path ?? undefined;
-				const { commit } = input.git?.commitChild
-					? await input.git.commitChild(input.root, child.task_id, input.batch_id, head, record.branch, intentPath)
-					: input.kernel.commitChild
-						? await input.kernel.commitChild(input.root, child.task_id, input.batch_id, head, record.branch, intentPath)
-						: await commitBatchChild({
-							root: input.root,
-							taskId: child.task_id,
-							batchId: input.batch_id,
-							expectedHead: head,
-							branch: record.branch,
-							intentPath,
-						});
-				record.children = record.children.map((c) =>
-					c.task_id === child.task_id ? { ...c, state: "committed", commit } : c,
-				);
-				record.commits.push(commit);
-				head = commit;
-				persist();
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				record.children = record.children.map((c) =>
-					c.task_id === child.task_id ? { ...c, state: "needs_human", reason: message } : c,
-				);
-				// review-4: a commit failure is terminal; dependents must be
-				// skipped_blocked, not left pending.
-				skipDependents(record, child.task_id, `dependency ${child.task_id} failed to commit`);
-				record.batch_state = "failed";
-				persist();
-				break;
-			}
-		} else if (terminal.state === "stopped") {
-			record.children = record.children.map((c) =>
-				c.task_id === child.task_id
-					? { ...c, state: "needs_human", reason: "Kernel reported the child stopped" }
-					: c,
-			);
-			childTerminal = true;
-			skipDependents(record, child.task_id, `dependency ${child.task_id} parked`);
-			record.batch_state = "needs_human";
-			persist();
-		} else if (terminal.state === "rework" && terminal.operation === "qa") {
-			record.consecutive_qa_failures += 1;
-			if (record.consecutive_qa_failures >= record.budget.qa_failure_limit) {
-				record.children = record.children.map((c) =>
-					c.task_id === child.task_id
-						? { ...c, state: "needs_human", reason: `QA failure limit reached: ${terminal.summary}` }
-						: c,
-				);
-				record.batch_state = "needs_human";
-				childTerminal = true;
-				skipDependents(record, child.task_id, `dependency ${child.task_id} parked`);
-				persist();
-			} else {
-				// Below the limit: the inner loop re-drives the same child.
-				persist();
-			}
-		} else if (terminal.state === "failed" || terminal.state === "blocked" || terminal.state === "rework") {
-			const reason = terminal.state === "rework" ? terminal.summary : terminal.reason;
-			childTerminal = true;
-			record.children = record.children.map((c) =>
-				c.task_id === child.task_id ? { ...c, state: "needs_human", reason } : c,
-			);
-			skipDependents(record, child.task_id, `dependency ${child.task_id} parked`);
-			record.batch_state = "needs_human";
-			persist();
-		} else if (terminal.state === "review_ready") {
-			// A foreground Review reservation is owned by the calling host
-			// turn; the batch pauses here without parking the child.
-			record.children = record.children.map((c) =>
-				c.task_id === child.task_id
-					? { ...c, state: "enrolled", reason: `review reservation ${terminal.operation_id} open` }
-					: c,
-			);
-			persist();
-			return reportFor(
-				record,
-				`child ${child.task_id} holds an open Review reservation`,
-				"Submit the reserved foreground Review verdict, then call startBatch again to continue.",
-			);
-		}
-		}
+		const enrolled = requireFreshProjection(
+			await input.kernel.projectTask(input.root, child.task_id), child.task_id,
+		);
+		return executorHandoff(record, child.task_id, enrolled);
+
 	}
 
 	return finalize(input.root, record, stopReasonFor(record), "");
@@ -923,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) {
@@ -937,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:
@@ -987,6 +962,26 @@ export async function resumeBatch(
 				});
 				return finalize(input.root, existing, "claim held by another batch", "needs-human-attention");
 			}
+			if (holdsClaim) {
+				const failures = Math.max(existing.consecutive_qa_failures, fresh.qa_failure_count ?? 0);
+				if (failures >= existing.budget.qa_failure_limit && fresh.last_qa_failure_at &&
+					Date.parse(fresh.last_qa_failure_at) > Date.parse(existing.confirmation_time)) {
+					const reason = "QA failure limit reached; repair and settle the own child through Kernel before resuming the batch";
+					skipDependents(existing, driven.task_id, `dependency ${driven.task_id} parked`);
+					existing = writeBatchRunState(input.root, {
+						...existing, batch_state: "needs_human", consecutive_qa_failures: failures,
+						children: existing.children.map((c) => c.task_id === driven.task_id ? { ...c, state: "needs_human", reason } : c),
+					});
+					return finalize(input.root, existing, reason, "Repair and settle the own child through Kernel, then re-confirm the batch.",
+						{ recovery: deriveAssuranceRecovery(driven.task_id, fresh, {}, fresh.recovery_findings) ?? undefined });
+				}
+				if (failures !== existing.consecutive_qa_failures)
+					existing = writeBatchRunState(input.root, { ...existing, consecutive_qa_failures: failures });
+				// A failed preparation can leave frozen inputs with run_qa pending.
+				// The Parent owns that attempt; batch re-entry never blindly reruns it.
+				if (fresh.projection.next_obligation === "run_qa" || fresh.projection.artifact_state !== "frozen")
+					return executorHandoff(existing, driven.task_id, fresh);
+			}
 			if (!holdsClaim) {
 				// review-1(4th round): a claimless projection still carries a
 				// projection body when the task is a terminal owner. If the fresh
@@ -1001,6 +996,7 @@ export async function resumeBatch(
 				if (settledRemotely) {
 					existing = writeBatchRunState(input.root, {
 						...existing,
+						consecutive_qa_failures: 0,
 						children: existing.children.map((c) =>
 							c.task_id === driven.task_id
 								? { ...c, state: "settled", reason: "crash after settlement; resuming at commit" }
@@ -1142,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) => {
@@ -1178,39 +1176,9 @@ async function driveInterruptedChild(
 			);
 			record.consecutive_qa_failures = 0;
 			persist();
-			try {
-				const planChild = input.children.find((c) => c.task_id === child.task_id);
-				const intentPath = planChild?.intent_path ?? undefined;
-				const { commit } = input.git?.commitChild
-					? await input.git.commitChild(input.root, child.task_id, input.batch_id, head, record.branch, intentPath)
-					: input.kernel.commitChild
-						? await input.kernel.commitChild(input.root, child.task_id, input.batch_id, head, record.branch, intentPath)
-						: await commitBatchChild({
-							root: input.root,
-							taskId: child.task_id,
-							batchId: input.batch_id,
-							expectedHead: head,
-							branch: record.branch,
-							intentPath,
-						});
-				record.children = record.children.map((c) =>
-					c.task_id === child.task_id ? { ...c, state: "committed", commit } : c,
-				);
-				record.commits.push(commit);
-				head = commit;
-				persist();
-				child = { ...child, state: "committed", commit };
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				record.children = record.children.map((c) =>
-					c.task_id === child.task_id ? { ...c, state: "needs_human", reason: message } : c,
-				);
-				// review-4: dependents are skipped_blocked, not left pending.
-				skipDependents(record, child.task_id, `dependency ${child.task_id} failed to commit`);
-				record.batch_state = "failed";
-				persist();
-				return finalize(input.root, record, message, "");
-			}
+			// Use the same lookup/commit path for new settlement and crash recovery.
+			child = { ...child, state: "settled", reason: null };
+			continue;
 		} else if (terminal.state === "review_ready") {
 			record.children = record.children.map((c) =>
 				c.task_id === child.task_id
@@ -1227,24 +1195,31 @@ async function driveInterruptedChild(
 		} else if (terminal.state === "rework" && terminal.operation === "qa") {
 			// review-3(3rd round): interrupted-child rework applies the same
 			// consecutive-failure limit as startBatch instead of parking on the
-			// first rework; below the limit the loop re-drives the same child.
+			// first rework; below the limit implementation returns to the Parent.
 			record.consecutive_qa_failures += 1;
 			if (record.consecutive_qa_failures >= record.budget.qa_failure_limit) {
-				const reason = `QA failure limit reached: ${terminal.summary}`;
+				const reason = "QA failure limit reached";
 				record.children = record.children.map((c) =>
 					c.task_id === child.task_id ? { ...c, state: "needs_human", reason } : c,
 				);
 				record.batch_state = "needs_human";
 				skipDependents(record, child.task_id, `dependency ${child.task_id} parked`);
 				persist();
-				return finalize(input.root, record, reason, "");
+				const fresh = requireFreshProjection(await input.kernel.projectTask(input.root, child.task_id), child.task_id);
+				return finalize(input.root, record, reason, "Repair and settle the own child through Kernel, then re-confirm the batch.",
+					{ recovery: deriveAssuranceRecovery(child.task_id, fresh, terminal, fresh.recovery_findings) ?? undefined, diagnostics: terminal.diagnostics });
 			}
 			persist();
+			const fresh = requireFreshProjection(await input.kernel.projectTask(input.root, child.task_id), child.task_id);
+			return executorHandoff(record, child.task_id, fresh, terminal);
+		} else if (terminal.state === "rework" || terminal.environment_failure || terminal.state === "review_preparation_failed" || terminal.recovery?.category === "repair") {
+			// Ordinary own-claim repair is a Parent handoff, not a new user gate.
+			const fresh = requireFreshProjection(await input.kernel.projectTask(input.root, child.task_id), child.task_id);
+			return executorHandoff(record, child.task_id, fresh, terminal);
 		} else {
 			// stopped | failed | blocked: park and stop.
 			const reason =
-				terminal.state === "stopped" ? "Kernel reported the child stopped"
-					: terminal.state === "rework" ? terminal.summary : terminal.reason;
+				terminal.state === "stopped" ? "Kernel reported the child stopped" : terminal.reason;
 			record.children = record.children.map((c) =>
 				c.task_id === child.task_id ? { ...c, state: "needs_human", reason } : c,
 			);

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,
@@ -315,6 +334,17 @@ export interface BatchRunReport {
 	children: BatchChildRun[];
 	commits: string[];
 	reason: string | null;
+	/** Non-authoritative foreground implementation obligation, never persisted as readiness. */
+	handoff?: {
+		role: "executor";
+		task_id: string;
+		run_id: string | null;
+		record_revision: string;
+		next_obligation: import("../kernel/types").AssuranceObligation;
+	};
+	/** Safe observation only; never an execution-readiness certificate. */
+	recovery?: import("../assurance/coordinator").AssuranceRecovery;
+	diagnostics?: import("../assurance/qa").QaCheckDiagnostic[];
 	/** The single next action for the operator. */
 	next_action: string;
 	created_at: string;

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();

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

@@ -19,11 +19,13 @@ export interface GitWorkspaceSnapshot {
 }
 
 function git(root: string, args: string[]): string | null {
-	const result = spawnSync("git", ["-C", root, ...args], {
+	const diff = args[0] === "diff";
+	const command = diff ? ["diff", "--exit-code", ...args.slice(1)] : args;
+	const result = spawnSync("git", ["--no-optional-locks", "-c", "diff.autoRefreshIndex=false", "-C", root, ...command], {
 		encoding: "utf8",
 		stdio: ["ignore", "pipe", "pipe"],
 	});
-	return result.status === 0 ? result.stdout : null;
+	return result.status === 0 || (diff && result.status === 1) ? result.stdout : null;
 }
 
 function splitNull(value: string): string[] {
@@ -217,12 +219,14 @@ export function setGitTaskSnapshotTestHook(hook: () => void): () => void {
 }
 
 function gitBytes(root: string, args: string[]): Buffer {
-	const result = spawnSync("git", ["-C", root, ...args], {
+	const diff = args[0] === "diff";
+	const command = diff ? ["diff", "--exit-code", ...args.slice(1)] : args;
+	const result = spawnSync("git", ["--no-optional-locks", "-c", "diff.autoRefreshIndex=false", "-C", root, ...command], {
 		encoding: null,
 		stdio: ["ignore", "pipe", "pipe"],
 		maxBuffer: 8 * 1024 * 1024,
 	});
-	if (result.status !== 0 || !Buffer.isBuffer(result.stdout)) {
+	if ((result.status !== 0 && !(diff && result.status === 1)) || !Buffer.isBuffer(result.stdout)) {
 		throw new Error(`Git task snapshot command failed: git ${args.join(" ")}`);
 	}
 	return result.stdout;
@@ -631,6 +635,29 @@ export function taskRevisionIdentity(
 	};
 }
 
+/** The same v4 identity for an immutable delivered commit, without touching the index. */
+export function taskCommitRevisionIdentity(projectRoot: string, scopeHint: unknown, baseHead: string, commit: string): GitTaskDiffIdentity {
+	const requested = resolve(projectRoot);
+	if (lstatSync(requested).isSymbolicLink()) throw new Error("task commit root must be a real directory");
+	const root = realpathSync(requested), scope = assertCanonicalTaskScope(scopeHint);
+	if (!GIT_OBJECT_ID.test(baseHead) || !GIT_OBJECT_ID.test(commit)) throw new Error("invalid task commit identity");
+	if (gitRequired(root, ["cat-file", "-t", baseHead], "unreadable task base") !== "commit" ||
+		gitRequired(root, ["cat-file", "-t", commit], "unreadable task commit") !== "commit" ||
+		git(root, ["merge-base", "--is-ancestor", baseHead, commit]) === null) throw new Error("invalid task commit ancestry");
+	const paths = decodeNullPaths(gitBytes(root, ["diff", "--no-renames", "--name-only", "-z", baseHead, commit, "--"]), "task commit paths")
+		.filter(path => !isNonDeliveryPath(path) && taskPathMatchesScope(path, scope)).sort(comparePaths);
+	assertNoCaseFoldCollisions(paths, "task commit paths");
+	const changed_paths: Record<string, GitTaskIndexEntry> = {};
+	for (const path of paths) {
+		const current = headEntry(root, commit, path), base = headEntry(root, baseHead, path);
+		changed_paths[path] = { status: !base ? "added" : !current ? "deleted" : "modified",
+			mode: current?.mode ?? null, oid: current?.oid ?? null, base_mode: base?.mode ?? null, base_oid: base?.oid ?? null };
+	}
+	const snapshot: GitTaskRevisionSnapshot = { kind: "git-task-revision-v1", repository_root: root, base_head: baseHead,
+		base_tree: gitRequired(root, ["rev-parse", `${baseHead}^{tree}`], "unreadable task base tree"), scope, changed_paths };
+	return { diff_hash: hashTaskSnapshot(snapshot), changed_paths: paths };
+}
+
 /** The single v4 freshness identity shared by QA, Review, authorization, and completion. */
 export function taskRevisionDiffHash(
 	projectRoot: string,