immune-brain 4.3.0 → 4.4.1

package/plugins/immune-brain/dist/imm-loop.md

@@ -116,6 +116,23 @@ batch state transition: the shared `startBatch` driver in
 `runtime/unattended/` owns every batch transition, and each child is still
 enrolled, assured, and settled by the Kernel under an ordinary TaskRecord.
 
+A successful child Enrollment returns a `running` report with `handoff.role`
+`executor`; the child remains `enrolled`. The Parent implements that TaskIntent
+in the current foreground conversation, stages only its scoped changes, and
+runs focused diagnostics before Kernel Assurance. Re-entering the batch before
+implementation returns the same handoff without QA or another confirmation.
+The runtime owns no model invocation and adds no persisted execution lifecycle.
+
+After diagnostics pass, the Parent advances Kernel QA and dispatches any reserved
+foreground Review once using the exact returned `agent_params`, then submits its
+structured verdict. An open Review reservation stays with that Host invocation;
+batch re-entry waits for it rather than redispatching. On Kernel `done`, stage
+only that child's generated terminal audit evidence and call
+`start_unattended_batch` with the same slug. The driver reconciles settlement,
+adopts or creates the one scope-bound commit, then enrolls the next ready child
+under the still-valid authorization. Ordinary Executor handoff and below-limit
+QA repair do not park the batch; genuine budget/authority stops remain fail-closed.
+
 Batch execution never pushes a ref, opens or updates a pull request, resolves a
 user decision, or creates, switches, or deletes a Git worktree. Its sole Git
 effect is the batch branch `imm/<initiative-slug>` plus one scope-bounded commit
@@ -147,8 +164,24 @@ per completed child.
   and exactly one same-Host recovery action. Never recommend another Host,
   worktree, Direct Path, unmanaged implementation, or automatic retry.
 - After interruption, read a fresh projection and run only the pending obligation.
-  A committed QA result is honored; an interrupted precommit QA run produces no
-  approval. Do not rerun fresh QA simply because Review was interrupted.
+  `recovery` carries that task/run/record identity, affected acceptance/finding IDs
+  and one legal `next_action`; it is an observation, never execution readiness.
+  Own-claim technical rework goes to foreground Executor, not user authorization.
+  `review_preparation_failed` keeps the batch running/enrolled: repair the Review
+  evidence environment and resume `run_review`, retaining fresh QA without batch
+  re-confirmation.
+  Repair and verify the cause, then dispose each identified finding explicitly by
+  `resolve_finding` or evidence-bound `refute_finding`. Local green cannot close
+  findings or settle the task; obtain fresh Kernel QA and required Review.
+  Environment preparation/resolution/integrity failure is not an assertion finding.
+  Use its canonical descriptor reference/digest, phase/outcome, timing and byte
+  counts to diagnose; QA diagnostic metadata is capped at 16 KiB and contains no
+  stdout/stderr, argv, environment values or arbitrary executor error text.
+  A frozen child with `run_qa` pending returns to Parent; batch re-entry does not
+  blindly retry an unchanged failure. Fix the environment before a fresh attempt.
+  Scope/authority exceptions still use their existing native gates. A committed
+  QA result is honored; an interrupted precommit QA run produces no approval.
+  Do not rerun fresh QA simply because Review was interrupted.
 - Malformed or stale reviewer output is not a verdict. Keep the existing
   reservation only if the Host reports it valid; use its exact recovery action.
   Do not fabricate a pass or blindly redispatch Review.

package/plugins/immune-brain/dist/role-prompts/executor.md

@@ -6,6 +6,12 @@ same-boundary follow-up) in the current Parent conversation. New helpers or
 tests inside an approved directory or glob do not require a revision. Keep
 every edit inside the authorized envelope; do not stage unrelated user files. Do not discover or load a Pi Skill.
 
+On a batch `handoff.role=executor`, implement only its named enrolled child;
+the batch stays `running` with that child `enrolled`. Return to the Parent after
+scoped implementation, staging and focused diagnostics. Enrollment itself does
+not start QA; the Parent owns the subsequent Kernel Assurance and foreground
+Review handoff under the same still-valid batch authorization.
+
 Before handoff, run the permitted diagnostic checks and return commands and
 outcomes to the Parent as structured diagnostic evidence. The read-only Loop
 runtime action only constructs the dispatch envelope; it does not store

package/plugins/immune-brain/runtime/assurance/coordinator.ts

@@ -22,6 +22,7 @@ import type { TaskIntentIdentityToken } from "../kernel/intent_token_registry";
 import type { AssuranceHostPort, HostReviewReservation } from "./host_port";
 import type { GithubTrackerResult as GithubTrackerProjectionResult } from "../github_issue_tracker";
 
+
 export type AssuranceRole = "qa" | "review";
 export interface AssuranceCorrelation {
 	record_revision: string;
@@ -38,7 +39,8 @@ export interface TaskTombstone {
 	terminal_event_id: string;
 }
 export interface TaskRecordRead {
-	record?: { contract?: string; findings: Array<{ kind: string; status: string }> } | null;
+	revision?: string;
+	record?: { contract?: string; findings: Array<{ kind: string; status: string; id?: string; acceptance_id?: string | null }> } | null;
 }
 export interface TaskIntentRead {
 	/**
@@ -211,12 +213,102 @@ export interface SnapshotDescriptor {
 	root: string;
 }
 
-export interface QaVerificationProgress {
+export type QaPreparationReason = "executable_or_cwd_unavailable" | "process_launch_failed" | "process_cleanup_failed"
+	| "protected_input_or_output_drift" | "execution_metadata_limit_exceeded" | "timeout" | "output_limit" | "nonzero_exit"
+	| "execution_failed" | "command_identity_changed" | "delivery_cleanup_failed" | "delivery_unavailable";
+export interface QaCheckDiagnostic {
+	acceptance_id: string;
+	descriptor_ref: string;
+	descriptor_digest: string;
+	stage: "resolution" | "prepare" | "check" | "integrity";
+	outcome: "running" | "passed" | QaPreparationReason;
+	elapsed_ms: number;
+	exit_code: number | null;
+	stdout_bytes: number | null;
+	stderr_bytes: number | null;
+}
+
+const QA_STAGES = ["resolution", "prepare", "check", "integrity"];
+const QA_OUTCOMES = ["running", "passed", "executable_or_cwd_unavailable", "process_launch_failed", "process_cleanup_failed",
+	"protected_input_or_output_drift", "execution_metadata_limit_exceeded", "timeout", "output_limit", "nonzero_exit", "execution_failed",
+	"command_identity_changed", "delivery_cleanup_failed", "delivery_unavailable"];
+/** The Tool boundary never spreads arbitrary executor fields. */
+export function qaDiagnosticMetadata(d: QaCheckDiagnostic): QaCheckDiagnostic {
+	if (typeof d.acceptance_id !== "string" || !d.acceptance_id
+		|| !/^acceptance\/\d{1,6}\/verification\/(command|environment\/prepare)$/.test(d.descriptor_ref)
+		|| !/^sha256:[a-f0-9]{64}$/.test(d.descriptor_digest) || !QA_STAGES.includes(d.stage) || !QA_OUTCOMES.includes(d.outcome)
+		|| !Number.isFinite(d.elapsed_ms) || d.elapsed_ms < 0
+		|| [d.stdout_bytes, d.stderr_bytes].some(n => n !== null && (!Number.isSafeInteger(n) || n < 0))
+		|| (d.exit_code !== null && !Number.isSafeInteger(d.exit_code))) throw new Error("invalid QA diagnostic metadata");
+	const safe = { acceptance_id: d.acceptance_id, descriptor_ref: d.descriptor_ref, descriptor_digest: d.descriptor_digest,
+		stage: d.stage, outcome: d.outcome, elapsed_ms: d.elapsed_ms, exit_code: d.exit_code, stdout_bytes: d.stdout_bytes, stderr_bytes: d.stderr_bytes };
+	if (Buffer.byteLength(JSON.stringify(safe)) > 16_384) throw new QaPreparationError("prepare", [], "execution_metadata_limit_exceeded");
+	return safe;
+}
+
+export interface QaVerificationProgressInput {
 	index: number;
 	total: number;
 	acceptance_id: string;
 	phase: "running" | "passed" | "failed";
 	elapsed_ms: number;
+	diagnostic?: QaCheckDiagnostic;
+}
+
+export class QaPreparationError extends Error {
+	constructor(public readonly stage: QaCheckDiagnostic["stage"], public readonly acceptance_ids: string[], public readonly reason: QaPreparationReason,
+		public readonly diagnostics: QaCheckDiagnostic[] = []) {
+		if (!QA_STAGES.includes(stage) || !QA_OUTCOMES.includes(reason)) throw new Error("invalid QA preparation classification");
+		const safe = diagnostics.map(qaDiagnosticMetadata);
+		if (Buffer.byteLength(JSON.stringify(safe)) > 16_384) throw new QaPreparationError("prepare", [], "execution_metadata_limit_exceeded");
+		super(`QA ${stage} failed (${reason}); affected checks=${acceptance_ids.length}`);
+		this.diagnostics = safe;
+		this.name = "QaPreparationError";
+	}
+}
+
+export type QaVerificationProgress = QaVerificationProgressInput;
+
+export interface AssuranceRecovery {
+	category: "repair" | "environment" | "authorization";
+	task_id: string;
+	run_id: string | null;
+	record_revision: string;
+	next_obligation: AssuranceProjectionResult["projection"]["next_obligation"];
+	acceptance_ids: string[];
+	finding_ids: string[];
+	next_action: string;
+}
+
+/** Observation only; fresh Kernel facts remain the sole owner of the obligation. */
+export function deriveAssuranceRecovery(taskId: string, fresh: AssuranceProjectionResult,
+	result: { state?: string; environment_failure?: boolean; diagnostics?: QaCheckDiagnostic[]; reason?: string },
+	findings: NonNullable<TaskRecordRead["record"]>["findings"] = []): AssuranceRecovery | null {
+	if (fresh.error || fresh.claim?.task_id !== taskId || fresh.projection.lifecycle !== "active") return null;
+	const p = fresh.projection;
+	const findingIds = [...p.blocking_finding_ids, ...p.unresolved_user_decision_ids, ...p.replan_required_ids];
+	const scope = result.reason?.includes("task delivery contains paths outside the authorization envelope");
+	const migration = result.reason?.includes("verification_contract_migration_required");
+	const unstaged = result.reason?.includes("task delivery has unstaged or untracked changes");
+	const reviewPreparation = result.state === "review_preparation_failed" && p.next_obligation === "run_review";
+	const authority = scope || migration || p.next_obligation === "resolve_user_decision" || p.next_obligation === "revise_intent"
+		|| p.unresolved_user_decision_ids.length > 0 || p.replan_required_ids.length > 0 || p.authorization.state !== "none";
+	const repair = unstaged || p.next_obligation === "resolve_findings" || p.blocking_finding_ids.length > 0;
+	if (!authority && !repair && !result.environment_failure && !reviewPreparation) return null;
+	const affected = findings.filter(f => f.status === "open" && f.id && findingIds.includes(f.id) && f.acceptance_id).map(f => f.acceptance_id!);
+	const category = authority ? "authorization" : repair ? "repair" : "environment";
+	return { category, task_id: taskId, run_id: p.run_id ?? null, record_revision: p.record_revision,
+		next_obligation: p.next_obligation, finding_ids: findingIds,
+		acceptance_ids: [...new Set(affected.length ? affected : result.diagnostics?.length ? result.diagnostics.map(d => d.acceptance_id) : reviewPreparation ? p.fresh_acceptance_ids : p.missing_acceptance_ids)],
+		next_action: scope ? "Reconcile the listed paths with the TaskIntent scope: unstage unrelated changes or submit the required native Intent revision."
+			: migration ? "route Planner for the verification descriptor v2 Intent revision and native gate"
+			: category === "authorization"
+			? p.authorization.blocked ? "inspect authority state" : p.next_obligation === "revise_intent" ? "route Planner for the required Intent revision and native gate" : "request_authorization"
+			: unstaged ? "Stage only the scoped implementation changes, then call advance_assurance."
+			: category === "repair" ? "Route foreground Executor to repair and verify the identified findings; dispose each by resolve_finding or evidence-bound refute_finding, then run fresh advance_assurance."
+			: reviewPreparation ? "Repair the Review evidence environment, then call advance_assurance to resume run_review; retain fresh QA and do not re-confirm the batch."
+			: "Repair the identified verification environment, then call advance_assurance; a local check is non-attesting.",
+	};
 }
 
 export interface ForegroundToolUpdate {
@@ -224,7 +316,13 @@ export interface ForegroundToolUpdate {
 	details: Record<string, unknown>;
 }
 
-export type AssuranceAdvanceResult =
+type AssuranceRecoveryFields = {
+	diagnostics?: QaCheckDiagnostic[];
+	environment_failure?: boolean;
+	recovery?: AssuranceRecovery;
+	recovery_error?: "fresh_kernel_projection_unavailable";
+};
+export type AssuranceAdvanceResult = AssuranceRecoveryFields & (
 	| { state: "review_ready"; operation: "review"; operation_id: string; snapshot_digest: string; review_bundle_digest: string; agent_params: unknown }
 	| { state: "rework"; operation: "qa"; operation_id: string; summary: string }
 	| { state: "cancelled"; operation: "qa" | "review"; operation_id: string; reason: string }
@@ -238,14 +336,14 @@ export type AssuranceAdvanceResult =
 	| { state: "settlement_unknown"; operation: "qa" | "review"; operation_id: string; reason: string }
 	| { state: "blocked"; reason: string; code?: "verdict_invalid" }
 	| { state: "completed" }
-	| { state: "stopped" };
+	| { state: "stopped" });
 
-export type AssuranceSubmitReviewResult =
+export type AssuranceSubmitReviewResult = AssuranceRecoveryFields & (
 	| { state: "rework"; operation: "review"; operation_id: string; summary: string }
 	| { state: "review_preparation_failed"; operation: "review"; operation_id: string; reason: string }
 	| { state: "completed" }
 	| { state: "settlement_unknown"; operation: "qa" | "review"; operation_id: string; reason: string }
-	| { state: "blocked"; reason: string; code?: "verdict_invalid" };
+	| { state: "blocked"; reason: string; code?: "verdict_invalid" });
 
 export type ActiveAssuranceState =
 	| { state: "running"; operation: "qa"; operation_id: string; deadline_seconds: number }
@@ -663,6 +761,36 @@ export class AssuranceCoordinator {
 	sessionGenerationValue(): number { return this.sessionGeneration; }
 
 	async advance(taskId: string, ctx: HostContext, signal?: AbortSignal, onUpdate?: (update: ForegroundToolUpdate) => void): Promise<AssuranceAdvanceResult> {
+		const checks = new Map<string, QaCheckDiagnostic>();
+		const result = await this.advanceOnce(taskId, ctx, signal, update => {
+			const diagnostic = update.details.diagnostic as QaCheckDiagnostic | undefined;
+			if (diagnostic) {
+				checks.set(diagnostic.descriptor_ref, diagnostic);
+				if (Buffer.byteLength(JSON.stringify([...checks.values()])) > 16_384)
+					throw new QaPreparationError("prepare", [diagnostic.acceptance_id], "execution_metadata_limit_exceeded",
+						[{ ...diagnostic, stage: "prepare", outcome: "execution_metadata_limit_exceeded" }]);
+			}
+			onUpdate?.(update);
+		});
+		const diagnostics = result.diagnostics ?? [...checks.values()];
+		return this.withRecovery(taskId, ctx, diagnostics.length ? { ...result, diagnostics } : result);
+	}
+
+	private async withRecovery<T extends AssuranceAdvanceResult | AssuranceSubmitReviewResult>(taskId: string, ctx: HostContext, enriched: T): Promise<T> {
+		if (enriched.recovery_error || !["failed", "blocked", "rework", "review_preparation_failed"].includes(enriched.state)) return enriched;
+		try {
+			const fresh = await this.ports.projectTask(ctx.cwd, taskId);
+			if (fresh.error || fresh.claim?.task_id !== taskId || fresh.projection.lifecycle !== "active")
+				return { ...enriched, recovery_error: "fresh_kernel_projection_unavailable" };
+			const record = await this.ports.readTaskRecord(ctx.cwd, taskId);
+			if (!record.record || record.revision !== fresh.projection.record_revision)
+				return { ...enriched, recovery_error: "fresh_kernel_projection_unavailable" };
+			const recovery = deriveAssuranceRecovery(taskId, fresh, enriched, record.record?.findings);
+			return recovery ? { ...enriched, recovery } : enriched;
+		} catch { return { ...enriched, recovery_error: "fresh_kernel_projection_unavailable" }; }
+	}
+
+	private async advanceOnce(taskId: string, ctx: HostContext, signal?: AbortSignal, onUpdate?: (update: ForegroundToolUpdate) => void): Promise<AssuranceAdvanceResult> {
 		if (this.isInvocationOpen(taskId)) return { state: "blocked", reason: "an authority invocation is already open" };
 		const active = this.active(taskId);
 		if (active?.state === "review_ready") {
@@ -671,12 +799,14 @@ export class AssuranceCoordinator {
 			try {
 				projection = await this.ports.projectTask(ctx.cwd, taskId);
 			} catch (error) {
-				return { state: "blocked", reason: `cannot validate Review reservation: ${boundedAssuranceError(error)}` };
+				return { state: "blocked", reason: `cannot validate Review reservation: ${boundedAssuranceError(error)}`, recovery_error: "fresh_kernel_projection_unavailable" };
 			}
 			const matches = reservationStillValid(reservation, projection, taskId);
 			if (matches) return this.reviewReadyResult(taskId);
 			if (reservation) this.releaseReviewReservation(taskId, reservation);
 			this.rejectedReviewOperations.delete(taskId);
+			if (projection.error || (projection.projection.lifecycle !== "done" && projection.projection.lifecycle !== "stopped" && (!projection.claim || projection.claim.task_id !== taskId)))
+				return { state: "blocked", reason: projection.error ?? "no active backend claim for this task", recovery_error: "fresh_kernel_projection_unavailable" };
 		}
 		const refreshed = this.active(taskId);
 		if (refreshed?.state === "running") return { state: "blocked", reason: `assurance operation ${refreshed.operation_id} is already running` };
@@ -698,6 +828,7 @@ export class AssuranceCoordinator {
 		// nothing instead of being reported as an unknown settlement.
 		let boundaryBaseline: string | null = null;
 		let reviewPreparationStarted = false;
+		let initialProjectionAvailable = false;
 		// Set only by the QA job-budget deadline, which is not a host cancellation.
 		let qaJobBudgetExceeded = false;
 		let phase = "preparing";
@@ -738,13 +869,14 @@ export class AssuranceCoordinator {
 				projection = await this.ports.projectTask(ctx.cwd, taskId);
 			}
 			ensureOperationLive();
-			if (projection.error) return { state: "blocked", reason: projection.error };
+			if (projection.error) return { state: "blocked", reason: projection.error, recovery_error: "fresh_kernel_projection_unavailable" };
 			if (projection.projection.lifecycle === "done" || projection.projection.lifecycle === "stopped") {
 				this.unknownOperations.delete(taskId);
 				return { state: projection.projection.lifecycle === "done" ? "completed" : "stopped" };
 			}
-			if (!projection.claim) return { state: "blocked", reason: "no active backend claim" };
-			if (projection.claim.task_id !== taskId) return { state: "blocked", reason: `backend claim belongs to ${projection.claim.task_id}, not ${taskId}` };
+			if (!projection.claim) return { state: "blocked", reason: "no active backend claim", recovery_error: "fresh_kernel_projection_unavailable" };
+			if (projection.claim.task_id !== taskId) return { state: "blocked", reason: `backend claim belongs to ${projection.claim.task_id}, not ${taskId}`, recovery_error: "fresh_kernel_projection_unavailable" };
+			initialProjectionAvailable = true;
 			// A closed Kernel projection, not the lost host reply, decides what
 			// remains. Committed QA/Review is never replayed from local memory.
 			if (projection.projection.lifecycle === "active") this.unknownOperations.delete(taskId);
@@ -822,6 +954,7 @@ export class AssuranceCoordinator {
 					operationController.abort(new Error(`deterministic QA exceeded its declared ${Math.ceil(qaJobTimeoutMs / 60_000)} minute job budget`));
 				}, qaJobTimeoutMs);
 				try {
+					phase = "verifying";
 					qaVerdict = await this.ports.runQa(assurance.snapshot, assurance.descriptors, {
 						signal: operationController.signal,
 						onProgress: (item) => progress("verifying", `QA ${item.index}/${item.total} ${item.acceptance_id} ${item.phase}`, {
@@ -830,6 +963,7 @@ export class AssuranceCoordinator {
 							acceptance_id: item.acceptance_id,
 							acceptance_phase: item.phase,
 							elapsed_ms: item.elapsed_ms,
+							...(item.diagnostic ? { diagnostic: qaDiagnosticMetadata(item.diagnostic) } : {}),
 						}),
 					});
 				} finally {
@@ -950,6 +1084,16 @@ export class AssuranceCoordinator {
 			progress("review_ready", "QA passed; invoke the reserved foreground Agent, then call submit_review", { snapshot_digest: snapshotDigest(review.snapshot), review_bundle_digest: review.snapshot.review_bundle_digest ?? "", agent_params: hostReservation.dispatch });
 			return { state: "review_ready", operation: "review", operation_id: operationId, snapshot_digest: snapshotDigest(review.snapshot), review_bundle_digest: review.snapshot.review_bundle_digest ?? "", agent_params: hostReservation.dispatch };
 		} catch (error) {
+			// Recovery decoration must not bypass the initial read retry policy.
+			if (!initialProjectionAvailable && !aborted() && !(error instanceof VerificationAbortedError))
+				return { state: "failed", operation: "qa", operation_id: operationId, reason: `${phase}: ${boundedAssuranceError(error)}`,
+					recovery_error: "fresh_kernel_projection_unavailable" };
+			if (error instanceof QaPreparationError && !authorityCommitted && !authorityBoundaryStarted && !aborted())
+				return { state: "failed", operation: "qa", operation_id: operationId, reason: error.message,
+					environment_failure: true, diagnostics: error.diagnostics.map(qaDiagnosticMetadata) };
+			if (phase === "verifying" && !authorityCommitted && !authorityBoundaryStarted && !aborted() && !(error instanceof VerificationAbortedError))
+				return { state: "failed", operation: "qa", operation_id: operationId,
+					reason: "QA execution failed before attestation (execution_failed)", environment_failure: true };
 			if (reviewPreparationStarted) {
 				const reason = aborted() || error instanceof VerificationAbortedError
 					? `${phase}: host cancellation`
@@ -980,6 +1124,10 @@ export class AssuranceCoordinator {
 	}
 
 	async submitReview(taskId: string, ctx: HostContext, verdictInput: unknown): Promise<AssuranceSubmitReviewResult> {
+		return this.withRecovery(taskId, ctx, await this.submitReviewOnce(taskId, ctx, verdictInput));
+	}
+
+	private async submitReviewOnce(taskId: string, ctx: HostContext, verdictInput: unknown): Promise<AssuranceSubmitReviewResult> {
 		const unknown = this.unknownOperations.get(taskId);
 		if (unknown) return { state: "settlement_unknown", operation: unknown.operation, operation_id: unknown.operationId, reason: unknown.reason };
 		const rejected = this.rejectedReviewOperations.get(taskId);
@@ -992,12 +1140,12 @@ export class AssuranceCoordinator {
 		} catch (error) {
 			const reason = boundedAssuranceError(error);
 			this.releaseReviewReservation(taskId, reservation, reason);
-			return { state: "blocked", reason };
+			return { state: "blocked", reason, recovery_error: "fresh_kernel_projection_unavailable" };
 		}
 		if (fresh.error || !fresh.claim || fresh.claim.task_id !== taskId || compareReservationSnapshot(reservation.snapshot, fresh.projection).length > 0 || fresh.projection.lifecycle !== reservation.snapshot.lifecycle || fresh.projection.artifact_state !== reservation.snapshot.artifact_state) {
 			const reason = fresh.error ?? "assurance snapshot changed before Review submission";
 			this.releaseReviewReservation(taskId, reservation, reason);
-			return { state: "blocked", reason };
+			return { state: "blocked", reason, ...(fresh.error || !fresh.claim || fresh.claim.task_id !== taskId ? { recovery_error: "fresh_kernel_projection_unavailable" as const } : {}) };
 		}
 		if (reservation.snapshot.review_revision) {
 			try {

package/plugins/immune-brain/runtime/assurance/qa.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { snapshotDigest, type SnapshotDescriptor, type AssuranceVerdict } from "./coordinator";
+import { snapshotDigest, QaPreparationError, type AssuranceVerdict, type SnapshotDescriptor, type QaCheckDiagnostic, type QaPreparationReason, type QaVerificationProgressInput } from "./coordinator";
+export { QaPreparationError, type QaCheckDiagnostic, type QaPreparationReason, type QaVerificationProgressInput } from "./coordinator";
 import { assertDeliveryClean, materializeDeliveryWorkspace, removeTaskOwnedTree, writeDeliveryTree } from "./delivery_workspace";
 import { runFixedVerification, resolveVerificationCommand, assertCommandIdentity, verificationPath, VerificationAbortedError, VerificationCleanupError, VerificationLaunchError, type FrozenCommand, type VerificationDescriptor, type VerificationCommand } from "./verification";
 import { mkdtempSync, realpathSync } from "node:fs";
@@ -9,14 +10,6 @@ import { qaFindingId } from "./qa_findings";
 import { captureGitTaskRevisionSnapshot } from "../workspace_scope";
 import { readTaskRecord } from "../kernel/storage";
 
-export interface QaVerificationProgressInput {
-	index: number;
-	total: number;
-	acceptance_id: string;
-	phase: "running" | "passed" | "failed";
-	elapsed_ms: number;
-}
-
 function deliveryTreeForSnapshot(
 	snapshot: SnapshotDescriptor,
 	writeTree: typeof writeDeliveryTree,
@@ -37,13 +30,6 @@ function deliveryTreeForSnapshot(
 	return writeDeliveryTree(snapshot.root, captured);
 }
 
-export class QaPreparationError extends Error {
-	constructor(public readonly stage: "resolution" | "prepare" | "integrity", public readonly acceptance_ids: string[], public readonly reason: string) {
-		super(`QA ${stage} failed (${reason}); affected checks=${acceptance_ids.join(",")}`);
-		this.name = "QaPreparationError";
-	}
-}
-
 export async function runDeterministicQa(
 	snapshot: SnapshotDescriptor,
 	descriptors: Map<string, VerificationDescriptor>,
@@ -74,38 +60,60 @@ export async function runDeterministicQa(
 	const path = verificationPath();
 	const findings: NonNullable<AssuranceVerdict["findings"]> = [];
 	const evidence: unknown[] = [];
-	const allCommands: FrozenCommand[] = [];
+	const allCommands: Array<{ frozen: FrozenCommand; diagnostics: QaCheckDiagnostic[] }> = [];
 	for (const [environmentKey, group] of groups) {
 		live();
 		const ids = group.map(item => item.id);
 		const environment = group[0]!.descriptor.environment;
-		const delivery = (options._materializeDeliveryWorkspace ?? materializeDeliveryWorkspace)(snapshot.root, tree);
-		const home = mkdtempSync(join(tmpdir(), "imm-qa-home-"));
+		const diagnostics = (stage: QaCheckDiagnostic["stage"], outcome: QaCheckDiagnostic["outcome"], affected = group,
+			commandStage: "prepare" | "check" = "check", elapsed = 0, result?: { exit_code: number; stdout: string; stderr: string }): QaCheckDiagnostic[] =>
+			affected.map(item => ({ acceptance_id: item.id,
+				descriptor_ref: `acceptance/${item.index}/verification/${commandStage === "prepare" ? "environment/prepare" : "command"}`,
+				descriptor_digest: `sha256:${createHash("sha256").update(JSON.stringify(item.descriptor)).digest("hex")}`,
+				stage, outcome, elapsed_ms: elapsed, exit_code: result?.exit_code ?? null,
+				stdout_bytes: result ? Buffer.byteLength(result.stdout) : null, stderr_bytes: result ? Buffer.byteLength(result.stderr) : null }));
+		const { delivery, home, deliveryPrefix } = (() => {
+			let delivery: ReturnType<typeof materializeDeliveryWorkspace> | undefined, home: string | undefined;
+			try {
+				delivery = (options._materializeDeliveryWorkspace ?? materializeDeliveryWorkspace)(snapshot.root, tree);
+				home = mkdtempSync(join(tmpdir(), "imm-qa-home-"));
+				return { delivery, home, deliveryPrefix: `${realpathSync(delivery.root)}${sep}` };
+			} catch {
+				let reason: QaPreparationReason = "delivery_unavailable";
+				try { try { delivery?.cleanup(); } finally { if (home) removeTaskOwnedTree(home); } }
+				catch { reason = "delivery_cleanup_failed"; }
+				throw new QaPreparationError("prepare", ids, reason, diagnostics("prepare", reason));
+			}
+		})();
 		const clean = () => {
 			if (options._materializeDeliveryWorkspace) return;
 			try { assertDeliveryClean(delivery.root, tree, delivery.seal, environment.writable_paths); }
-			catch { throw new QaPreparationError("integrity", ids, "protected_input_or_output_drift"); }
+			catch { throw new QaPreparationError("integrity", ids, "protected_input_or_output_drift", diagnostics("integrity", "protected_input_or_output_drift")); }
 		};
 		const groupCommands: FrozenCommand[] = [];
-		const deliveryPrefix = `${realpathSync(delivery.root)}${sep}`;
-		const execute = async (command: VerificationCommand, stage: "prepare" | "check") => {
+		const execute = async (command: VerificationCommand, stage: "prepare" | "check", affected = group) => {
+			const started = performance.now();
+			const fail = (errorStage: QaCheckDiagnostic["stage"], reason: QaPreparationReason) =>
+				new QaPreparationError(errorStage, affected.map(item => item.id), reason, diagnostics(errorStage, reason, affected, stage, Math.round(performance.now() - started)));
 			live(); clean();
 			let frozen: FrozenCommand;
 			try { frozen = (options._resolveVerificationCommand ?? resolveVerificationCommand)(delivery.root, command, path); }
-			catch { throw new QaPreparationError("resolution", ids, "executable_or_cwd_unavailable"); }
+			catch { throw fail("resolution", "executable_or_cwd_unavailable"); }
 			let result;
 			try { result = await (options._runFixedVerification ?? runFixedVerification)(delivery.root, command, frozen, { signal: options.signal, home, path }); }
 			catch (error) {
-				if (error instanceof VerificationLaunchError) throw new QaPreparationError("resolution", ids, "process_launch_failed");
-				if (error instanceof VerificationCleanupError) throw new QaPreparationError("resolution", ids, "process_cleanup_failed");
-				throw error;
+				if (error instanceof VerificationAbortedError) throw error;
+				if (error instanceof VerificationLaunchError) throw fail("resolution", "process_launch_failed");
+				if (error instanceof VerificationCleanupError) throw fail("resolution", "process_cleanup_failed");
+				throw fail(stage, "execution_failed");
 			}
 			live(); clean();
 			groupCommands.push(frozen);
 			if (frozen?.entry) {
-				if (!command.executable.startsWith("./")) allCommands.push(frozen);
+				const identityDiagnostics = diagnostics("integrity", "command_identity_changed", affected, stage, Math.round(performance.now() - started), result);
+				if (!command.executable.startsWith("./")) allCommands.push({ frozen, diagnostics: identityDiagnostics });
 				else if (frozen.interpreter && !frozen.interpreter.path.startsWith(deliveryPrefix))
-					allCommands.push({ entry: frozen.interpreter, interpreter: null, interpreter_args: [] });
+					allCommands.push({ frozen: { entry: frozen.interpreter, interpreter: null, interpreter_args: [] }, diagnostics: identityDiagnostics });
 			}
 			// Paths and process output are not persisted. Identity hashes describe
 			// observed entries, not a claim about every transitive dependency.
@@ -114,38 +122,45 @@ export async function runDeterministicQa(
 				entry: frozen?.entry?.content_hash ?? null, interpreter: frozen?.interpreter?.content_hash ?? null,
 				exit_code: result.exit_code, timed_out: result.timed_out, output_limited: result.output_limited });
 			if (Buffer.byteLength(JSON.stringify(evidence)) > 16_384)
-				throw new QaPreparationError("prepare", ids, "execution_metadata_limit_exceeded");
+				throw fail("prepare", "execution_metadata_limit_exceeded");
 			return result;
 		};
 		try {
 			clean();
 			if (environment.prepare) {
+				const prepareStarted = performance.now();
 				const result = await execute(environment.prepare, "prepare");
 				if (result.exit_code !== 0 || result.timed_out || result.output_limited)
-					throw new QaPreparationError("prepare", ids, result.timed_out ? "timeout" : result.output_limited ? "output_limit" : "nonzero_exit");
+					throw new QaPreparationError("prepare", ids, result.timed_out ? "timeout" : result.output_limited ? "output_limit" : "nonzero_exit",
+						diagnostics("prepare", result.timed_out ? "timeout" : result.output_limited ? "output_limit" : "nonzero_exit", group, "prepare", Math.round(performance.now() - prepareStarted), result));
 			}
 			for (const item of group) {
-				const started = Date.now();
-				const progress = (phase: QaVerificationProgressInput["phase"]) => options.onProgress?.({
-					index: item.index + 1, total: snapshot.acceptance.length, acceptance_id: item.id, phase, elapsed_ms: Date.now() - started,
+				const started = performance.now();
+				const progress = (phase: QaVerificationProgressInput["phase"], outcome: QaCheckDiagnostic["outcome"], result?: { exit_code: number; stdout: string; stderr: string }) => options.onProgress?.({
+					index: item.index + 1, total: snapshot.acceptance.length, acceptance_id: item.id, phase, elapsed_ms: Math.round(performance.now() - started),
+					diagnostic: diagnostics("check", outcome, [item], "check", Math.round(performance.now() - started), result)[0],
 				});
-				progress("running");
-				const result = await execute(item.descriptor.command, "check");
+				progress("running", "running");
+				const result = await execute(item.descriptor.command, "check", [item]);
 				const failed = result.exit_code !== 0 || result.timed_out || result.output_limited;
-				progress(failed ? "failed" : "passed");
+				progress(failed ? "failed" : "passed", result.timed_out ? "timeout" : result.output_limited ? "output_limit" : failed ? "nonzero_exit" : "passed", result);
 				if (failed) findings.push({ id: qaFindingId(item.id, snapshotDigest(snapshot)), kind: "blocking", acceptance_id: item.id,
 					summary: `verification failed (exit ${result.exit_code}${result.timed_out ? ", timed out" : ""}${result.output_limited ? ", output limit" : ""}) stdout=${Buffer.byteLength(result.stdout)}B stderr=${Buffer.byteLength(result.stderr)}B`, findings_digest: "" });
 			}
 			// Recheck while project entries still exist; cleanup removes them.
-			for (const frozen of groupCommands) {
-				if (frozen?.entry) assertCommandIdentity(frozen);
-			}
-		} finally { try { delivery.cleanup(); } finally { removeTaskOwnedTree(home); } }
+			try {
+				for (const frozen of groupCommands) if (frozen?.entry) assertCommandIdentity(frozen);
+			} catch { throw new QaPreparationError("integrity", ids, "command_identity_changed", diagnostics("integrity", "command_identity_changed")); }
+		} finally {
+			try { try { delivery.cleanup(); } finally { removeTaskOwnedTree(home); } }
+			catch { throw new QaPreparationError("integrity", ids, "delivery_cleanup_failed", diagnostics("integrity", "delivery_cleanup_failed")); }
+		}
 	}
 	live();
 	// Host entries survive materialization cleanup and must still match before approval.
-	for (const frozen of allCommands) {
-		if (frozen?.entry) assertCommandIdentity(frozen);
+	for (const entry of allCommands) {
+		try { if (entry.frozen?.entry) assertCommandIdentity(entry.frozen); }
+		catch { throw new QaPreparationError("integrity", entry.diagnostics.map(item => item.acceptance_id), "command_identity_changed", entry.diagnostics); }
 	}
 	const base = { contract: "assurance_kernel/assurance_verdict/v2" as const, role: "qa" as const,
 		task_id: snapshot.task_id, snapshot_digest: snapshotDigest(snapshot) };

package/plugins/immune-brain/runtime/claude/kernel_ports.ts

@@ -62,6 +62,7 @@ import {
 } from "../unattended/batch_preflight";
 import {
 	startBatch,
+	batchQaFailureFacts,
 	type BatchRunnerKernelPort,
 	type BatchRunReport,
 } from "../unattended/batch_runner";
@@ -658,6 +659,13 @@ export class ClaudeRuntime {
 		}
 	}
 
+	async reviseIntent(taskId: string, nextIntent: unknown) {
+		return this.executeOrdinary({ cwd: this.cwd }, {
+			taskId,
+			operation: { op: "revise_intent", next_intent: nextIntent, actor_id: "executor" },
+		});
+	}
+
 	/**
 	 * Ordinary Kernel operation, not a privileged one: canary_application builds
 	 * the action without a capability and the Pi Host lists resolve_finding in
@@ -994,7 +1002,7 @@ export class ClaudeRuntime {
 		// availability, working-tree cleanliness against the authorized scope,
 		// recovery children, plan digest, and base HEAD are one shared projection,
 		// so neither Host re-implements a batch decision.
-		const now = new Date().toISOString();
+		let now = new Date().toISOString();
 		const preflight = await projectBatchPreflight({
 			root: this.cwd,
 			initiative_slug: initiativeSlug,
@@ -1119,6 +1127,9 @@ export class ClaudeRuntime {
 		// review-1: verify cancellation signal right before authority issuance and startBatch
 		if (meta.signal?.aborted) return batchReason("cancelled_before_execution");
 
+		now = new Date().toISOString();
+		if (Date.parse(expiresAt) <= Date.parse(now))
+			return batchReason("confirmation_failed", "confirmed batch deadline expired before authorization issuance");
 		const capability = this.batchRegistry.issue(binding, recoveryChildren as any, now);
 
 		const basePort = this.createBatchKernelPort(this.batchRegistry, capability, binding);
@@ -1202,14 +1213,22 @@ export class ClaudeRuntime {
 			},
 			advanceTask: async (root, taskId) => {
 				const result = await this.coordinator.advance(taskId, { cwd: root });
-				if (result.state === "completed") return { state: "completed" };
-				if (result.state === "stopped") return { state: "stopped" };
-				if (result.state === "rework") return { state: "rework", operation: result.operation, summary: result.summary };
-				if (result.state === "review_ready") return { state: "review_ready", operation_id: result.operation_id };
-				if (result.state === "blocked") return { state: "blocked", reason: result.reason };
-				return { state: "failed", reason: (result as { reason?: string }).reason ?? "advance failed" };
+				const facts = { diagnostics: result.diagnostics, environment_failure: result.environment_failure, recovery: result.recovery };
+				if (result.state === "completed") return { state: "completed", ...facts };
+				if (result.state === "stopped") return { state: "stopped", ...facts };
+				if (result.state === "rework") return { state: "rework", operation: result.operation, summary: result.summary, ...facts };
+				if (result.state === "review_ready") return { state: "review_ready", operation_id: result.operation_id, ...facts };
+				if (result.state === "review_preparation_failed") return { state: result.state, operation: result.operation, operation_id: result.operation_id, reason: result.reason, ...facts };
+				if (result.state === "blocked") return { state: "blocked", reason: result.reason, ...facts };
+				return { state: "failed", reason: (result as { reason?: string }).reason ?? "advance failed", ...facts };
+			},
+			projectTask: async (root, taskId) => {
+				const fresh = await projectAssurance(root, taskId, diffSnapshotOf);
+				if (!fresh.claim || fresh.projection.lifecycle !== "active" || fresh.error !== null) return fresh;
+				const { record, revision } = readTaskRecordRaw(root, taskId);
+				if (!record || revision !== fresh.projection.record_revision) throw new Error(`Kernel recovery projection changed for ${taskId}`);
+				return { ...fresh, ...batchQaFailureFacts(record) };
 			},
-			projectTask: async (root, taskId) => projectAssurance(root, taskId, diffSnapshotOf),
 			ownsTaskClaim: (taskId) => {
 				return registry.isChildConsumed(capability, taskId);
 			},