immune-brain 4.5.0 → 5.0.0

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

@@ -12,8 +12,9 @@ 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
+Before handoff, run the permitted diagnostic checks, complete the Delivery
+Evidence check below and return its table to the Parent as structured diagnostic
+evidence. The read-only Loop
 runtime action only constructs the dispatch envelope; it does not store
 evidence or change task state. Preserve failed and blocked attempts. Do not
 perform QA,
@@ -21,6 +22,38 @@ review, plan mutation, successor approval, Compounder work, or authority
 writes. If the requested change needs scope expansion, stop and return an
 `imm-planner` route with the concrete missing scope and verification reason.
 
+## Delivery Evidence
+
+Reuse the TaskIntent and any bound Spec's agreed seams and controls. Before the
+first Assurance attempt, return one compact row per acceptance; update affected
+rows after repair. This is handoff evidence, not a new artifact or approval gate.
+
+| Acceptance / invariant | Entry and consumers | Positive / negative / boundary controls | Command, outcome and input | Finding coverage |
+|---|---|---|---|---|
+
+For changed shared behavior, trace the real entry through its state owner,
+write, serialization, reload and downstream consumer as applicable. Include
+both affected hosts and recovery/replay branches. An async, return-type or
+exception-contract change requires checking every affected caller's await,
+cancellation and error propagation.
+
+Use the real producer for the success control where available. Derive rejection
+controls from a successful state, change only the target condition, and assert
+the intended rejection reason and required side effects. A control must fail
+when its target protection is removed. For byte-preservation claims compare the
+relevant raw files, index and refs; for observed behavior link each required
+criterion to its concrete observation.
+
+Name whether each check consumed worktree or delivery bytes. Before Assurance,
+verify task-owned changes are staged within scope, generated mirrors match,
+and applicable type/build checks pass. On QA failure, reproduce the reported
+failure under its delivery conditions before another attempt. For rework, name
+the violated invariant, all known trigger classes and their controls in Finding
+coverage; account for affected callers sharing that invariant within scope.
+Record missing evidence as blocked and repair it before handoff. The Loop owns
+verdict submission, finding disposition and the second-rework generalize-or-refute
+rule.
+
 ## Code Quality Guard
 
 Before handoff, check the implementation for real implementation rather than

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

@@ -15,8 +15,10 @@ import {
 	VerificationAbortedError,
 } from "./verification";
 import { createInvocationRegistry, type InvocationState, type InvocationToken } from "./invocations";
-import type { ReviewBundle, ReviewManifestV5, ReviewRevision } from "./review_evidence";
-import { buildRoleDelegationPacket } from "../role_prompt_bridge";
+import type { ReviewBundle, ReviewManifestV5 } from "./review_evidence";
+import { createVerdictAuthority, type VerdictAuthority } from "./verdict_authority";
+import type { ConfirmationReferenceSource } from "./host_port";
+import { buildRoleDelegationPacket, STATIC_REVIEW_RULES } from "../role_prompt_bridge";
 import type { AssuranceProjectionResult } from "../kernel/assurance_projection";
 import type { TaskIntentIdentityToken } from "../kernel/intent_token_registry";
 import type { AssuranceHostPort, HostReviewReservation } from "./host_port";
@@ -316,7 +318,10 @@ export interface ForegroundToolUpdate {
 	details: Record<string, unknown>;
 }
 
+/** Wall-clock milliseconds spent per advance stage; the stage names are the progress stages. */
+export interface AssuranceTimings { total_ms: number; stage_ms: Record<string, number> }
 type AssuranceRecoveryFields = {
+	timings?: AssuranceTimings;
 	diagnostics?: QaCheckDiagnostic[];
 	environment_failure?: boolean;
 	recovery?: AssuranceRecovery;
@@ -343,7 +348,7 @@ export type AssuranceSubmitReviewResult = AssuranceRecoveryFields & (
 	| { 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"; recovery_action?: string });
 
 export type ActiveAssuranceState =
 	| { state: "running"; operation: "qa"; operation_id: string; deadline_seconds: number }
@@ -352,51 +357,17 @@ export type ActiveAssuranceState =
 
 export interface AssuranceCoordinatorPorts {
 	host: AssuranceHostPort;
+	confirmationReference: ConfirmationReferenceSource;
+	onReworkApplied?: (ctx: HostContext, taskId: string, findingsCount: number) => void;
 	projectTask(root: string, taskId: string): Promise<AssuranceProjectionResult>;
 	readTaskRecord(root: string, taskId: string): Promise<TaskRecordRead>;
 	readTaskIntent(root: string, taskId: string): Promise<TaskIntentRead>;
-	buildAssurance(
-		root: string,
-		taskId: string,
-		role: AssuranceRole,
-		projection: AssuranceProjectionResult,
-	): Promise<{
-		snapshot: SnapshotDescriptor;
-		descriptors: Map<string, VerificationDescriptor>;
-		reviewBundle: ReviewBundle | null;
-		reviewManifest?: ReviewManifestV5 | null;
-	}>;
-	/**
-	 * Publish and prove the deterministic task-scoped revision before QA runs, so
-	 * a preparation failure can never consume or fake a settled QA attestation.
-	 * Returns null for records still on the legacy v3 bundle path.
-	 */
-	ensureReviewRevision?(
-		root: string,
-		taskId: string,
-		projection: AssuranceProjectionResult,
-	): Promise<ReviewRevision | null>;
 	runQa(
 		snapshot: SnapshotDescriptor,
 		descriptors: Map<string, VerificationDescriptor>,
 		options: { signal?: AbortSignal; onProgress?: (progress: QaVerificationProgress) => void },
 	): Promise<AssuranceVerdict>;
 	writeReviewEvidence(input: { snapshot: SnapshotDescriptor; evidence: ReviewBundle | ReviewManifestV5 }): { path: string; remove(): void };
-	applyVerdict(
-		ctx: HostContext,
-		input: {
-			taskId: string;
-			snapshot: SnapshotDescriptor;
-			verdict: AssuranceVerdict;
-			invocation: InvocationToken;
-			actorId: string;
-			hooks?: {
-				beforeCommit?: () => Promise<void>;
-				onCommit?: () => void;
-				afterCommit?: () => Promise<void>;
-			};
-		},
-	): Promise<void>;
 	applyOrdinaryOperation(ctx: HostContext, input: { taskId: string; operation: { op: string; actor_id: string } }): Promise<unknown>;
 	advanceBeforeProjection?: () => Promise<void>;
 	qaBeforeProjection?: () => Promise<void>;
@@ -404,12 +375,23 @@ export interface AssuranceCoordinatorPorts {
 	qaOnAuthorityCommit?: () => void;
 	qaAfterAuthorityCommit?: () => Promise<void>;
 	qaJobTimeoutMs?: number;
+	/** Attach per-stage `timings` to advance results. Defaults to IMM_ASSURANCE_TIMINGS=1. */
+	reportTimings?: boolean;
+	/** Overrides QA_MAX_IDENTICAL_FAILURES; tests only. */
+	qaMaxIdenticalFailures?: number;
 }
 
 export const QA_MIN_JOB_TIMEOUT_SECONDS = 15 * 60;
 export const QA_MAX_JOB_TIMEOUT_SECONDS = 60 * 60;
 export const QA_JOB_OVERHEAD_SECONDS = 2 * 60;
 export const QA_JOB_TIMEOUT_SECONDS = QA_MIN_JOB_TIMEOUT_SECONDS;
+/**
+ * A QA run that fails before attestation writes no authority, so the Kernel
+ * would happily rerun the same descriptors forever. After this many identical
+ * failures on the same snapshot (record revision, intent hash, diff hash) the
+ * coordinator refuses to rerun until the snapshot changes.
+ */
+export const QA_MAX_IDENTICAL_FAILURES = 2;
 export const REVIEW_PREPARATION_TIMEOUT_MS = 30_000;
 export const REVIEW_DISPATCH_TIMEOUT_MS = 120_000;
 export const REVIEW_VERDICT_VALIDATION_TIMEOUT_MS = 30_000;
@@ -464,19 +446,19 @@ export function snapshotDigest(snapshot: SnapshotDescriptor): string {
 	return `sha256:${createHash("sha256").update(JSON.stringify(snapshot)).digest("hex")}`;
 }
 
-export function buildReviewPrompt(snapshot: SnapshotDescriptor, evidencePath?: string): string {
+/**
+ * The per-dispatch Review facts: which evidence to read, which revision it pins,
+ * what the acceptances assert, and the exact verdict shapes.
+ *
+ * This is the whole prompt for a Host whose reviewer definition already carries
+ * the role contract and `STATIC_REVIEW_RULES` — the Claude Host. A Host whose
+ * dispatched agent carries no instructions (Pi) gets `buildReviewPrompt`, which
+ * prepends both.
+ */
+export function buildReviewSnapshotPrompt(snapshot: SnapshotDescriptor, evidencePath?: string): string {
 	if (snapshot.role !== "review") throw new Error("native review prompt requires review role");
 	const acceptance = snapshot.acceptance.map((item) => `- ${item.id}: ${item.assertion}`).join("\n");
 	const digest = snapshotDigest(snapshot);
-	const rolePacket = buildRoleDelegationPacket({
-		role: "code-review",
-		context: {
-			task_id: snapshot.task_id,
-			review_gate: "imm-code-review",
-			changed_files_signature: snapshot.diff_hash,
-			snapshot_digest: digest,
-		},
-	});
 	const revision = snapshot.review_revision;
 	const evidenceContract = revision
 		? [
@@ -492,25 +474,44 @@ export function buildReviewPrompt(snapshot: SnapshotDescriptor, evidencePath?: s
 				`The user-selected worktree may contain staged task changes that are absent from the isolated reviewer worktree. Review authority is bound only to the bundle dirty_files current_content bytes and committed HEAD provenance. Analyze code exclusively from those bundle bytes; repository file reads are permitted only for the provenance git commands above. A symbol present in current_content but absent from HEAD is the task change, not an absence.`,
 			];
 	return [
-		rolePacket.prompt,
 		...evidenceContract,
-		`Do not edit files, create files, run mutating commands, or change Git state. Focus on correctness, regressions, security, and missing tests.`,
-		`Execution outcomes for every acceptance were verified deterministically by the Kernel QA layer before this review and are embedded in this bundle under outcomes (the immutable evidence file, acceptance_id -> {status, summary}); do not re-execute descriptors and do not treat the absence of local test runs as a finding. Your review covers evidence provenance, code correctness, regressions, security, and missing tests against the embedded assertions and code.`,
 		`Snapshot digest: ${digest}`,
 		`TaskRecord revision: ${snapshot.record_revision}`,
 		revision
 			? `Intent revision ${snapshot.intent_revision} (hash ${snapshot.intent_content_hash}), diff ${snapshot.diff_hash}, review revision ${revision.review_commit} (base ${revision.base_head}, tree ${revision.review_tree}, manifest ${revision.manifest_digest}), state ${snapshot.lifecycle}:${snapshot.artifact_state}.`
 			: `Intent revision ${snapshot.intent_revision} (hash ${snapshot.intent_content_hash}), diff ${snapshot.diff_hash}, review bundle ${snapshot.review_bundle_digest}, state ${snapshot.lifecycle}:${snapshot.artifact_state}.`,
 		"Acceptance assertions:", acceptance,
-		"Reserve the final turn for exactly one strict JSON verdict. Reply with ONLY that object, without markdown fences or commentary.",
-		`Every rework finding must carry machine-checkable provenance: evidence.trigger (the concrete inputs or state that reach the defect), a non-empty evidence.caller_chain (ordered repository paths or symbols), and evidence.violated {kind: "acceptance"|"security_boundary", ref}. The anchor is derived from that evidence; a finding without it is rejected and the correction must be resubmitted.`,
-		`PASS shape: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"pass","approval":{"kind":"review","authority_role":"reviewer","summary":"<one line>"}}`,
-		`A pass verdict may carry non-blocking notes as findings, but every one of them must set kind "advisory"; a blocking finding is a rework verdict and must omit approval: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"pass","approval":{"kind":"review","authority_role":"reviewer","summary":"<one line>"},"findings":[{"id":"review-1","kind":"advisory","acceptance_id":"<id|null>","summary":"<one line>","evidence":{"trigger":"<concrete inputs or state>","caller_chain":["<path-or-symbol>"],"violated":{"kind":"acceptance|security_boundary","ref":"<acceptance id or boundary>"}}}]}`,
+		`PASS shape: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"pass","approval":{"kind":"review","authority_role":"reviewer","summary":"<one line>","inspected_paths":["<every changed path of the reviewed change set>"]}}`,
+		`A pass verdict may carry non-blocking notes as findings, but every one of them must set kind "advisory"; a blocking finding is a rework verdict and must omit approval: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"pass","approval":{"kind":"review","authority_role":"reviewer","summary":"<one line>","inspected_paths":["<every changed path of the reviewed change set>"]},"findings":[{"id":"review-1","kind":"advisory","acceptance_id":"<id|null>","summary":"<one line>","evidence":{"trigger":"<concrete inputs or state>","caller_chain":["<path-or-symbol>"],"violated":{"kind":"acceptance|security_boundary","ref":"<acceptance id or boundary>"}}}]}`,
 		`REWORK shape: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"rework","findings":[{"id":"review-1","kind":"blocking|advisory","acceptance_id":"<id|null>","summary":"<one line>","evidence":{"trigger":"<concrete inputs or state>","caller_chain":["<path-or-symbol>"],"violated":{"kind":"acceptance|security_boundary","ref":"<acceptance id or boundary>"}}}]}`,
 		`REWORK verdicts must omit the approval field entirely; do not emit "approval": null.`,
 	].join("\n");
 }
 
+/**
+ * The complete Review prompt: the internal role contract, the static review
+ * rules, and the per-dispatch facts. Dispatched by a Host whose agent carries no
+ * instructions of its own.
+ */
+export function buildReviewPrompt(snapshot: SnapshotDescriptor, evidencePath?: string): string {
+	if (snapshot.role !== "review") throw new Error("native review prompt requires review role");
+	const digest = snapshotDigest(snapshot);
+	const rolePacket = buildRoleDelegationPacket({
+		role: "code-review",
+		context: {
+			task_id: snapshot.task_id,
+			review_gate: "imm-code-review",
+			changed_files_signature: snapshot.diff_hash,
+			snapshot_digest: digest,
+		},
+	});
+	return [
+		rolePacket.prompt,
+		...STATIC_REVIEW_RULES,
+		buildReviewSnapshotPrompt(snapshot, evidencePath),
+	].join("\n");
+}
+
 function parseVerdictEvidence(value: unknown, index: number): FindingEvidence {
 	if (!value || typeof value !== "object" || Array.isArray(value))
 		throw new Error(`finding ${index} evidence is required`);
@@ -579,7 +580,28 @@ export function parseAssuranceVerdict(input: unknown, snapshot: SnapshotDescript
 		const expectedKind = snapshot.role === "qa" ? "qa" : "review";
 		const expectedRole = snapshot.role === "qa" ? "qa" : "reviewer";
 		if (!approval || approval.kind !== expectedKind || approval.authority_role !== expectedRole || typeof approval.summary !== "string" || !approval.summary.trim()) throw new Error("pass verdict approval is invalid");
-		const unknownApproval = Object.keys(approval).find((key) => !["kind", "authority_role", "summary"].includes(key));
+		// A Review pass must claim the paths it inspected: BR-DEC-3 converts silent
+		// partial coverage into an explicit false statement. The list is checked
+		// here against the reviewed change set and removed before settlement, so
+		// the Kernel approval and TaskRecord never see it. QA verdicts treat the
+		// field as unknown, exactly as before.
+		if (snapshot.role === "review") {
+			const required = snapshot.dirty_files;
+			const listed = approval.inspected_paths;
+			if (listed === undefined) throw new Error(`review pass verdict approval.inspected_paths is required; it must list every reviewed changed path${required.length ? `: ${required.join(", ")}` : " (none for this change set)"}`);
+			if (!Array.isArray(listed) || listed.some((entry) => typeof entry !== "string" || !entry.trim())) throw new Error("review pass verdict approval.inspected_paths must be an array of repository-relative path strings");
+			const seen = new Set<string>();
+			for (const entry of listed as string[]) {
+				if (seen.has(entry)) throw new Error(`review pass verdict approval.inspected_paths lists a duplicate path: ${entry}`);
+				seen.add(entry);
+			}
+			const foreign = (listed as string[]).filter((entry) => !required.includes(entry));
+			if (foreign.length) throw new Error(`review pass verdict approval.inspected_paths lists a path outside the reviewed change set: ${foreign.join(", ")}`);
+			const missing = required.filter((entry) => !seen.has(entry));
+			if (missing.length) throw new Error(`review pass verdict approval.inspected_paths omits reviewed changed paths: ${missing.join(", ")}`);
+		}
+		const allowedApproval = snapshot.role === "review" ? ["kind", "authority_role", "summary", "inspected_paths"] : ["kind", "authority_role", "summary"];
+		const unknownApproval = Object.keys(approval).find((key) => !allowedApproval.includes(key));
 		if (unknownApproval) throw new Error(`pass verdict approval has unknown field: ${unknownApproval}`);
 		const passFindings = raw.findings === undefined ? [] : parseVerdictFindings(raw.findings as unknown[], snapshot);
 		if (passFindings.some((finding) => finding.kind !== "advisory")) throw new Error("pass verdict findings must all be advisory");
@@ -705,12 +727,21 @@ export class AssuranceCoordinator {
 	private readonly operationControllers = new Map<string, { operationId: string; controller: AbortController }>();
 	private readonly reviewReservations = new Map<string, ReviewReservation>();
 	private readonly rejectedReviewOperations = new Map<string, { operationId: string; reason: string }>();
+	private readonly qaFailureStreaks = new Map<string, { key: string; count: number }>();
+	private readonly qaAttemptKeys = new Map<string, string>();
 	private readonly unknownOperations = new Map<string, { operation: "qa" | "review"; operationId: string; reason: string }>();
 	private readonly sessionInvocations = new Set<InvocationToken>();
 	private sessionActive = true;
 	private sessionGeneration = 0;
 
-	constructor(private readonly ports: AssuranceCoordinatorPorts) {}
+	readonly authority: VerdictAuthority;
+	constructor(private readonly ports: AssuranceCoordinatorPorts, authorityOverrides: Partial<VerdictAuthority> = {}) {
+		this.authority = { ...createVerdictAuthority({
+			confirmationReference: ports.confirmationReference,
+			commitInvocation: token => this.commitInvocation(token),
+			onReworkApplied: ports.onReworkApplied,
+		}), ...authorityOverrides };
+	}
 
 	onSessionStart(): void {
 		this.sessionActive = true;
@@ -731,6 +762,8 @@ export class AssuranceCoordinator {
 			this.removeEvidence(reservation);
 		}
 		this.reviewReservations.clear();
+		this.qaFailureStreaks.clear();
+		this.qaAttemptKeys.clear();
 		for (const invocation of [...this.sessionInvocations]) this.closeSessionInvocation(invocation);
 	}
 
@@ -762,7 +795,19 @@ export class AssuranceCoordinator {
 
 	async advance(taskId: string, ctx: HostContext, signal?: AbortSignal, onUpdate?: (update: ForegroundToolUpdate) => void): Promise<AssuranceAdvanceResult> {
 		const checks = new Map<string, QaCheckDiagnostic>();
+		const started = performance.now();
+		const stageMs: Record<string, number> = {};
+		let stage = "preparing";
+		let stageStarted = started;
+		const closeStage = (now: number) => { stageMs[stage] = (stageMs[stage] ?? 0) + Math.round(now - stageStarted); };
 		const result = await this.advanceOnce(taskId, ctx, signal, update => {
+			const next = update.details.stage;
+			if (typeof next === "string" && next !== stage) {
+				const now = performance.now();
+				closeStage(now);
+				stage = next;
+				stageStarted = now;
+			}
 			const diagnostic = update.details.diagnostic as QaCheckDiagnostic | undefined;
 			if (diagnostic) {
 				checks.set(diagnostic.descriptor_ref, diagnostic);
@@ -772,8 +817,25 @@ export class AssuranceCoordinator {
 			}
 			onUpdate?.(update);
 		});
+		this.recordQaAttempt(taskId, result);
 		const diagnostics = result.diagnostics ?? [...checks.values()];
-		return this.withRecovery(taskId, ctx, diagnostics.length ? { ...result, diagnostics } : result);
+		const enriched = diagnostics.length ? { ...result, diagnostics } : result;
+		if (!(this.ports.reportTimings ?? process.env.IMM_ASSURANCE_TIMINGS === "1")) return this.withRecovery(taskId, ctx, enriched);
+		const finished = performance.now();
+		closeStage(finished);
+		return this.withRecovery(taskId, ctx, { ...enriched, timings: { total_ms: Math.round(finished - started), stage_ms: stageMs } });
+	}
+
+	private recordQaAttempt(taskId: string, result: AssuranceAdvanceResult): void {
+		const key = this.qaAttemptKeys.get(taskId);
+		this.qaAttemptKeys.delete(taskId);
+		if (!key || result.state === "cancelled") return;
+		if (result.state !== "failed" || result.operation !== "qa") {
+			this.qaFailureStreaks.delete(taskId);
+			return;
+		}
+		const streak = this.qaFailureStreaks.get(taskId);
+		this.qaFailureStreaks.set(taskId, { key, count: streak?.key === key ? streak.count + 1 : 1 });
 	}
 
 	private async withRecovery<T extends AssuranceAdvanceResult | AssuranceSubmitReviewResult>(taskId: string, ctx: HostContext, enriched: T): Promise<T> {
@@ -926,9 +988,9 @@ export class AssuranceCoordinator {
 				progress("preparing_review_revision", "Proving the immutable Review revision before QA");
 				try {
 					if (parked.record?.contract === "assurance_kernel/task_record/v4") {
-						if (!this.ports.ensureReviewRevision)
+						if (!this.authority.ensureReviewRevision)
 							throw new Error("v4 Review revision preparation is unavailable");
-						await this.ports.ensureReviewRevision(ctx.cwd, taskId, projection);
+						await this.authority.ensureReviewRevision(ctx.cwd, taskId, projection);
 					}
 				} catch (error) {
 					return { state: "blocked", reason: `review revision preparation failed: ${boundedAssuranceError(error)}` };
@@ -942,12 +1004,18 @@ export class AssuranceCoordinator {
 				progress("capturing_snapshot", "Capturing the immutable QA snapshot");
 				await this.ports.qaBeforeProjection?.();
 				ensureOperationLive();
-				const assurance = await this.ports.buildAssurance(ctx.cwd, taskId, "qa", projection);
+				const assurance = await this.authority.buildAssurance(ctx.cwd, taskId, "qa", projection);
 				ensureOperationLive();
 				// Preparation counts against the same ceiling as the checks, so the
 				// aggregate clock starts before the first prepared group runs. A host
 				// may only tighten the derived budget, never raise it past the ceiling.
-				const declaredQaJobMs = deriveQaJobTimeoutMs(assurance.descriptors.values());
+				const qaKey = `${assurance.snapshot.record_revision}|${assurance.snapshot.intent_content_hash}|${assurance.snapshot.diff_hash}`;
+					const streak = this.qaFailureStreaks.get(taskId);
+					const maxFailures = this.ports.qaMaxIdenticalFailures ?? QA_MAX_IDENTICAL_FAILURES;
+					if (streak?.key === qaKey && streak.count >= maxFailures)
+						return { state: "blocked", reason: `deterministic QA already failed ${streak.count} times on this exact snapshot; change the workspace diff or intent, or restart the session after fixing the environment, before retrying` };
+					this.qaAttemptKeys.set(taskId, qaKey);
+					const declaredQaJobMs = deriveQaJobTimeoutMs(assurance.descriptors.values());
 				const qaJobTimeoutMs = Math.min(declaredQaJobMs, this.ports.qaJobTimeoutMs ?? declaredQaJobMs);
 				const qaJobDeadline = setTimeout(() => {
 					qaJobBudgetExceeded = true;
@@ -974,7 +1042,7 @@ export class AssuranceCoordinator {
 				try {
 					progress("settling_qa", "Settling deterministic QA through the Kernel revision boundary");
 					authorityBoundaryStarted = true;
-					await this.ports.applyVerdict(ctx, {
+					await this.authority.applyVerdict(ctx, {
 						taskId,
 						snapshot: assurance.snapshot,
 						verdict: qaVerdict,
@@ -1037,10 +1105,10 @@ export class AssuranceCoordinator {
 			authorityBoundaryStarted = false;
 			if (aborted()) return this.reviewPreparationFailed(taskId, operationId, "host cancellation after QA authority settlement");
 			progress("preparing_review", "Preparing the reserved foreground Review evidence");
-			let review: Awaited<ReturnType<AssuranceCoordinatorPorts["buildAssurance"]>>;
+			let review: Awaited<ReturnType<VerdictAuthority["buildAssurance"]>>;
 			let evidence: { path: string; remove(): void };
 			try {
-				review = await this.ports.buildAssurance(ctx.cwd, taskId, "review", fresh);
+				review = await this.authority.buildAssurance(ctx.cwd, taskId, "review", fresh);
 				const payload = review.reviewManifest ?? review.reviewBundle;
 				if (!payload) throw new Error("review evidence is missing after QA settlement");
 				evidence = this.ports.writeReviewEvidence({ snapshot: review.snapshot, evidence: payload });
@@ -1063,6 +1131,7 @@ export class AssuranceCoordinator {
 					taskId,
 					operationId,
 					prompt: buildReviewPrompt(review.snapshot, evidence.path),
+					snapshotPrompt: buildReviewSnapshotPrompt(review.snapshot, evidence.path),
 					evidencePath: evidence.path,
 					maxTurns: reviewTurnBudget(workload),
 				});
@@ -1149,9 +1218,9 @@ export class AssuranceCoordinator {
 		}
 		if (reservation.snapshot.review_revision) {
 			try {
-				if (!this.ports.ensureReviewRevision)
+				if (!this.authority.ensureReviewRevision)
 					throw new Error("v4 Review revision verification is unavailable");
-				const revision = await this.ports.ensureReviewRevision(ctx.cwd, taskId, fresh);
+				const revision = await this.authority.ensureReviewRevision(ctx.cwd, taskId, fresh);
 				if (!revision || revision.base_head !== reservation.snapshot.review_revision.base_head || revision.review_commit !== reservation.snapshot.review_revision.review_commit || revision.review_tree !== reservation.snapshot.review_revision.review_tree || revision.manifest_digest !== reservation.snapshot.review_revision.manifest_digest)
 					throw new Error("Review revision changed before submission");
 			} catch (error) {
@@ -1167,7 +1236,7 @@ export class AssuranceCoordinator {
 		const invocation = this.openInvocation(taskId);
 		this.releaseReviewReservation(taskId, reservation);
 		try {
-			await this.ports.applyVerdict(ctx, {
+			await this.authority.applyVerdict(ctx, {
 				taskId,
 				snapshot: reservation.snapshot,
 				verdict,

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

@@ -1,7 +1,27 @@
+import type { SnapshotDescriptor } from "./coordinator";
+
+export type ConfirmationReferenceSource = (input: {
+	snapshot: SnapshotDescriptor;
+	actorId: string;
+	now: string;
+}) => string;
+
 export interface ReviewRequest {
 	taskId: string;
 	operationId: string;
+	/**
+	 * The complete Review prompt: internal role contract, static review rules and
+	 * the per-dispatch facts. Dispatched by a Host whose reviewer agent carries no
+	 * instructions of its own.
+	 */
 	prompt: string;
+	/**
+	 * The per-dispatch facts alone, a strict suffix of `prompt`. A Host whose
+	 * reviewer definition already carries the role contract and the static rules
+	 * dispatches only this, so the static instructions stay generated from one
+	 * source instead of being sent twice.
+	 */
+	snapshotPrompt: string;
 	evidencePath: string;
 	maxTurns: number;
 }

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

@@ -8,14 +8,14 @@ import { tmpdir } from "node:os";
 import { join, sep } from "node:path";
 import { qaFindingId } from "./qa_findings";
 import { captureGitTaskRevisionSnapshot } from "../workspace_scope";
-import { readTaskRecord } from "../kernel/storage";
+import { readTaskRecordRaw } from "../kernel/storage";
 
 function deliveryTreeForSnapshot(
 	snapshot: SnapshotDescriptor,
 	writeTree: typeof writeDeliveryTree,
 ): string {
 	if (snapshot.review_revision?.review_tree) return snapshot.review_revision.review_tree;
-	const record = readTaskRecord(snapshot.root, snapshot.task_id).record;
+	const record = readTaskRecordRaw(snapshot.root, snapshot.task_id).record;
 	if (!record || record.contract !== "assurance_kernel/task_record/v4" || !record.git_base_head)
 		throw new Error("QA delivery requires a TaskRecord v4 git_base_head");
 	const captured = captureGitTaskRevisionSnapshot(

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

@@ -463,6 +463,10 @@ function publishInput(
 	const recomputed = `sha256:${createHash("sha256").update(JSON.stringify(snapshot)).digest("hex")}`;
 	if (recomputed !== input.expectedDiffHash)
 		throw new Error("review task revision does not match assurance snapshot");
+	// A revision whose tree equals the base carries nothing to review; reserving
+	// Review for it would settle QA outcomes against bytes it does not contain.
+	if (Object.keys(snapshot.changed_paths).length === 0)
+		throw new Error("review revision carries no task change; stage the task's in-scope work before Review");
 	return { snapshot, revision: publishReviewRevision(snapshot.repository_root, snapshot, recomputed, input.taskId) };
 }