immune-brain 2.8.2 → 3.0.1

package/plugins/immune-brain/.pi-extension/imm-canary-work.ts

@@ -31,7 +31,16 @@ import {
 	type FrozenRunner,
 	type VerificationDescriptor,
 } from "./pi-canary-verification";
-import { captureReviewBundle, writeNativeReviewEvidence, type ReviewBundle } from "./pi-canary-review-bundle";
+import {
+	captureReviewBundle,
+	captureReviewManifest,
+	listReviewRefs,
+	reconcileReviewRefs,
+	writeNativeReviewEvidence,
+	type ReviewBundle,
+	type ReviewManifestV5,
+	type ReviewRevision,
+} from "./pi-canary-review-bundle";
 import type { InvocationToken } from "./pi-canary-invocations";
 import { qaFindingId } from "./pi-canary-qa-findings";
 import {
@@ -58,7 +67,7 @@ import {
 	type UserAttentionReason,
 } from "./pi-canary-interaction";
 import { isToolFailureState, throwToolFailure } from "./pi-canary-tool-failure";
-import { taskDiffHash, captureGitTaskSnapshot } from "../runtime/workspace_scope";
+import { taskDiffIdentity, taskRevisionIdentity, captureGitTaskSnapshot } from "../runtime/workspace_scope";
 import {
 	AssuranceProgression,
 	buildReviewPrompt,
@@ -108,6 +117,7 @@ import {
 	digestOfAction,
 	type AssuranceAuthorizationReadiness,
 	type AssuranceProjectionResult,
+	type TaskRecordRead,
 	type CanaryApplication,
 	type MutationAuthorityRegistry,
 	type CapabilityBindingV2,
@@ -184,6 +194,14 @@ export interface SnapshotDescriptorInput {
 	acceptance: Array<{ id: string; assertion: string; verification: string }>;
 	dirty_files?: string[];
 	review_bundle_digest?: string | null;
+	/** Present only when Review authority binds an immutable Git revision (v4). */
+	review_revision?: {
+		contract: "assurance_kernel/review_revision_identity/v1";
+		base_head: string;
+		review_commit: string;
+		review_tree: string;
+		manifest_digest: string;
+	};
 }
 
 export function buildSnapshot(input: SnapshotDescriptorInput): SnapshotDescriptor {
@@ -205,6 +223,7 @@ export function buildSnapshot(input: SnapshotDescriptorInput): SnapshotDescripto
 		acceptance: input.acceptance,
 		dirty_files: [...(input.dirty_files ?? [])].sort(),
 		review_bundle_digest: input.review_bundle_digest ?? null,
+		...(input.review_revision ? { review_revision: input.review_revision } : {}),
 		root: resolve(input.root),
 	};
 }
@@ -253,6 +272,7 @@ export default function (
 		frozenRunner: () => frozenRunner(),
 		buildAssurance: (root, taskId, role, projection, runner) =>
 			(dependencies.buildAssurance ?? buildAssuranceSnapshot)(root, taskId, role, projection, runner),
+		ensureReviewRevision: (root, taskId, projection) => ensureTaskReviewRevision(root, taskId, projection),
 		runQa: (snapshot, descriptors, runner, options) =>
 			(dependencies.runQa ?? runDeterministicQa)(snapshot, descriptors, runner, options),
 		writeReviewEvidence: (input) =>
@@ -328,11 +348,13 @@ export default function (
 
 	pi.on("session_start", async (_event: unknown, ctx?: ExtensionContext) => {
 		progression.onSessionStart();
-		if (!ctx || ctx.mode !== "tui") return;
+		if (!ctx) return;
 		railContext = ctx;
+		await reconcileRefsQuietly(ctx.cwd);
+		if (ctx.mode !== "tui") return;
 		await refreshTaskRail(ctx);
 	});
-	pi.on("tool_call", (event: { toolName?: string; input?: unknown; toolCallId?: string }, ctx?: ExtensionContext) => {
+	pi.on("tool_call", (event: { toolName?: string; input?: unknown }, ctx?: ExtensionContext) => {
 		if (ctx) railContext = ctx;
 		if (event.toolName === "imm_canary_enrollment" && ctx) {
 			const input = event.input as { task_id?: string } | undefined;
@@ -343,7 +365,6 @@ export default function (
 				next: "Review the native enrollment decision",
 			});
 		}
-		return progression.observeToolCall(event);
 	});
 	pi.on("tool_result", (event: unknown, ctx?: ExtensionContext) => {
 		if (ctx) railContext = ctx;
@@ -352,10 +373,6 @@ export default function (
 			const taskId = typeof result.details?.task_id === "string" ? result.details.task_id : undefined;
 			if (taskId) presentTaskRailResult(ctx, taskId, result.details);
 		}
-		progression.observeToolResult(event as Parameters<AssuranceProgression["observeToolResult"]>[0]);
-	});
-	pi.on("tool_execution_end", (event: unknown) => {
-		progression.observeToolEnd(event as Parameters<AssuranceProgression["observeToolEnd"]>[0]);
 	});
 	pi.on("session_shutdown", async (_event: unknown, ctx?: ExtensionContext) => {
 		resetInteractionPresentation(ctx ?? railContext);
@@ -368,11 +385,11 @@ export default function (
 		label: "Kernel canary assurance and executor operations",
 		description:
 			"Advance observable QA/Review orchestration, record executor facts, or request host confirmation for one enrolled Kernel canary task.",
-		promptSnippet: "Kernel canary: record facts, run foreground QA, then submit one native Review receipt without polling.",
+		promptSnippet: "Kernel canary: record facts, run foreground QA, then submit one structured Review verdict without polling.",
 		promptGuidelines: [
 			"Only the exact enrolled canary task is routable; verify the active backend claim first via status.",
 			"After implementation and focused verification, freeze the artifacts, call advance_assurance, and consume its direct terminal result; do not poll or create a detached job.",
-			"When advance_assurance returns review_ready, invoke the exact foreground Agent parameters from agent_params once, then call submit_review.",
+			"When advance_assurance returns review_ready, invoke the foreground Agent from agent_params once, then pass its structured verdict to submit_review.",
 			"For a complete breaking revision, call approve_breaking_intent_revision with the complete next_intent directly; do not ask for chat pre-confirmation because the host opens the single native confirmation before applying it.",
 			"For a proven stale authority claim, call repair_authority_state directly; do not ask for chat pre-confirmation because the host opens the single native confirmation.",
 			"After awaiting_user, call request_authorization directly so the host opens the single native confirmation; do not ask for chat pre-confirmation or ask the user to copy or report a command.",
@@ -382,7 +399,7 @@ export default function (
 			action: Type.Union([
 				Type.Object({ op: Type.Literal("status") }),
 				Type.Object({ op: Type.Literal("advance_assurance") }),
-				Type.Object({ op: Type.Literal("submit_review") }),
+				Type.Object({ op: Type.Literal("submit_review"), verdict: Type.Unknown() }),
 				Type.Object({ op: Type.Literal("request_authorization") }),
 				Type.Object({ op: Type.Literal("repair_authority_state") }),
 				Type.Object({ op: Type.Literal("freeze_artifacts") }),
@@ -407,7 +424,8 @@ export default function (
 				Type.Object({ op: Type.Literal("complete") }),
 			]),
 		}),
-		execute: async (toolCallId: string, params: { task_id: string; action: { op: string } }, signal: AbortSignal | undefined, onUpdate: ((update: ReturnType<typeof toolResult>) => void) | undefined, ctx: ExtensionContext) => {
+		prepareArguments: prepareActionArgs,
+		execute: async (toolCallId: string, params: { task_id: string; action: { op: string; verdict?: unknown } }, signal: AbortSignal | undefined, onUpdate: ((update: ReturnType<typeof toolResult>) => void) | undefined, ctx: ExtensionContext) => {
 			const { task_id: taskId, action } = params;
 			railContext = ctx;
 			presentTaskRailResult(ctx, taskId, {
@@ -524,7 +542,7 @@ export default function (
 						presentTaskRailResult(ctx, taskId, update.details as Record<string, unknown> | undefined);
 					})
 					: action.op === "submit_review"
-						? await progression.submitReview(taskId, ctx)
+						? await progression.submitReview(taskId, ctx, action.verdict)
 						: action.op === "approve_breaking_intent_revision"
 							? await authorizeExactOperation(
 								taskId,
@@ -591,6 +609,7 @@ export default function (
 					result: "Kernel executor fact recorded",
 					next_action: nextAction,
 				};
+				await reconcileRefsQuietly(ctx.cwd);
 				presentTaskRailResult(ctx, taskId, details);
 				return toolResult(
 					JSON.stringify(
@@ -643,6 +662,7 @@ export default function (
 				}),
 			]),
 		}),
+		prepareArguments: prepareActionArgs,
 		execute: async (
 			_toolCallId: string,
 			params: { action: LoopToolAction },
@@ -720,6 +740,69 @@ export default function (
 			progression.closeInvocation(invocation);
 			return { state: "blocked", reason };
 		}
+		const priorIntent = await readTaskIntent(ctx.cwd, taskId);
+		const sidecar = nextIntent ? join(ctx.cwd, priorIntent.intent_ref.path) : undefined;
+		const priorBytes = sidecar ? readFileSync(sidecar) : undefined;
+		const priorIndexState = sidecar
+			? execFileSync("git", ["ls-files", "--stage", "-z", "--", priorIntent.intent_ref.path], {
+					cwd: ctx.cwd,
+					stdio: ["ignore", "pipe", "pipe"],
+				})
+			: undefined;
+		let stagedNextDiffHash: string | undefined;
+		const restoreStagedIntent = (): void => {
+			if (!sidecar || !priorBytes || !priorIndexState) return;
+			writeFileSync(sidecar, priorBytes);
+			execFileSync("git", ["update-index", "--force-remove", "--", priorIntent.intent_ref.path], {
+				cwd: ctx.cwd,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			if (priorIndexState.length > 0) {
+				execFileSync("git", ["update-index", "-z", "--index-info"], {
+					cwd: ctx.cwd,
+					input: priorIndexState,
+					stdio: ["pipe", "ignore", "pipe"],
+				});
+			}
+			const restoredBytes = readFileSync(sidecar);
+			if (!restoredBytes.equals(priorBytes)) {
+				throw new Error("failed to restore prior intent bytes");
+			}
+			const restoredIndex = execFileSync("git", ["ls-files", "--stage", "-z", "--", priorIntent.intent_ref.path], {
+				cwd: ctx.cwd,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			if (!restoredIndex.equals(priorIndexState)) {
+				throw new Error("failed to restore prior intent git index entry");
+			}
+		};
+		if (nextIntent) {
+			try {
+				if (!sidecar || !priorBytes) throw new Error("breaking revision sidecar is missing");
+				if (
+					priorIntent.intent.revision !== projection.projection.intent_revision
+					|| priorIntent.content_hash !== projection.projection.intent_content_hash
+				) throw new Error("Intent changed while preparing the breaking revision");
+				writeFileSync(sidecar, `${JSON.stringify(nextIntent, null, 2)}\n`);
+				execFileSync("git", ["add", "--", priorIntent.intent_ref.path], {
+					cwd: ctx.cwd,
+					stdio: ["ignore", "pipe", "pipe"],
+				});
+				const stagedRecord = await readTaskRecord(ctx.cwd, taskId);
+				if (!stagedRecord.record || stagedRecord.revision !== projection.projection.record_revision)
+					throw new Error("TaskRecord changed while preparing the breaking revision");
+				stagedNextDiffHash = diffHashOf(ctx.cwd, stagedRecord.record);
+			} catch (error) {
+				let restoreError: unknown;
+				try { restoreStagedIntent(); } catch (err) { restoreError = err; }
+				const primaryReason = error instanceof Error ? error.message : String(error);
+				const reason = restoreError
+					? `${primaryReason}; additionally, ${restoreError instanceof Error ? restoreError.message : String(restoreError)}`
+					: primaryReason;
+				progression.closeInvocation(invocation);
+				return { state: "blocked", reason };
+			}
+		}
 		let userDecisionOperation: ReturnType<typeof buildUserDecisionOperation> | undefined;
 		if (operation === "resolve-user-decision") {
 			try {
@@ -754,6 +837,7 @@ export default function (
 						`Next Goal: ${nextIntent.goal}`,
 						`Next Scope: ${nextIntent.scope_hint.join(", ")}`,
 						`Next Acceptance Items: ${nextIntent.acceptance.length}`,
+						`Next staged diff: ${stagedNextDiffHash}`,
 					]
 				: []),
 			`Claim: ${projection.claim.lifecycle_status}`,
@@ -791,19 +875,28 @@ export default function (
 				],
 			});
 			confirmed = selected === "authorize";
-		} catch {
+		} catch (error) {
+			if (nextIntent) {
+				restoreStagedIntent();
+			}
 			if (operation !== "stop" && operation !== "approve-breaking-intent-revision")
 				await recordCancelledUserDecision(ctx, taskId, operation, snapshotDigestRef).catch(() => undefined);
 			progression.closeInvocation(invocation);
 			return { state: "cancelled", operation, reason: "confirmation aborted" };
 		}
 		if (!confirmed) {
+			if (nextIntent) {
+				restoreStagedIntent();
+			}
 			if (operation !== "stop" && operation !== "approve-breaking-intent-revision")
 				await recordCancelledUserDecision(ctx, taskId, operation, snapshotDigestRef).catch(() => undefined);
 			progression.closeInvocation(invocation);
 			return { state: "cancelled", operation, reason: "cancelled" };
 		}
 		if (!progression.sessionActiveValue() || progression.sessionGenerationValue() !== authorizationGeneration || progression.invocationState(invocation) !== "open") {
+			if (nextIntent) {
+				restoreStagedIntent();
+			}
 			notifyOnce(ctx, `authorization-session:${taskId}:${operation}`, `authorize ${operation}: session changed; confirmation discarded`, "warning");
 			progression.closeInvocation(invocation);
 			return { state: "blocked", reason: "session changed; confirmation discarded" };
@@ -814,13 +907,15 @@ export default function (
 			try {
 				progression.commitInvocation(invocation);
 			} catch (error) {
+				if (nextIntent) {
+					restoreStagedIntent();
+				}
 				const reason = error instanceof Error ? error.message : String(error);
 				notifyOnce(ctx, `authorization-commit:${taskId}:${operation}:${reason}`, `authorize ${operation} aborted: ${reason}`, "error");
 				return { state: "blocked", reason };
 			}
 			const { registry, app } = await authorityPair();
 			const now = new Date().toISOString();
-			const priorIntent = await readTaskIntent(ctx.cwd, taskId);
 			if (nextIntent) {
 				nextIntentRef = {
 					path: `docs/plans/${nextIntent.task_id}.intent.json`,
@@ -855,20 +950,18 @@ export default function (
 					: userDecisionOperation ?? userOperationFor(operation, approval);
 				// The exact host-built operation is shared by capability digest and
 				// application payload; command arguments cannot inject authority fields.
-				const sidecar = nextIntent ? join(ctx.cwd, priorIntent.intent_ref.path) : undefined;
-				const priorBytes = sidecar ? readFileSync(sidecar) : undefined;
 				try {
-					if (sidecar) {
-						writeFileSync(sidecar, `${JSON.stringify(nextIntent, null, 2)}\n`);
-						execFileSync("git", ["add", "--", priorIntent.intent_ref.path], {
-							cwd: ctx.cwd,
-							stdio: ["ignore", "pipe", "pipe"],
-						});
-						await dependencies.authorizationAfterSidecarStage?.();
-					}
-					const operationDiffHash = nextIntent
-						? diffHashOf(ctx.cwd, priorIntent.intent)
+					if (nextIntent) await dependencies.authorizationAfterSidecarStage?.();
+					// Re-read the owner record after confirmation and compare the staged
+					// candidate digest immediately before capability issuance.
+					const liveRecord = nextIntent ? await readTaskRecord(ctx.cwd, taskId) : null;
+					if (nextIntent && (!liveRecord?.record || liveRecord.revision !== projection.projection.record_revision || !stagedNextDiffHash))
+						throw new Error("TaskRecord changed before the breaking revision digest");
+					const operationDiffHash = liveRecord?.record
+						? diffHashOf(ctx.cwd, liveRecord.record)
 						: projection.projection.diff_hash;
+					if (nextIntent && operationDiffHash !== stagedNextDiffHash)
+						throw new Error("staged next-state diff changed after native confirmation");
 					const capability = await mintCapability(registry, {
 						authority_kind: "user",
 						task_id: taskId,
@@ -893,7 +986,7 @@ export default function (
 						task_id: taskId,
 						operation: { ...exactOperation, capability, actor_id: "literal-user" } as never,
 						prior_intent_token: priorIntent.token,
-						diffProvider: (root: string, intent: { scope_hint: unknown }) => diffHashOf(root, intent),
+						diffProvider: (root: string, record: NonNullable<TaskRecordRead["record"]>) => diffSnapshotOf(root, record),
 						now,
 					})) as unknown as { record: { lifecycle: string; artifact_state: string; intent_ref: { path: string }; intent_snapshot: { scope_hint: string[] } } };
 					if (
@@ -901,19 +994,13 @@ export default function (
 						|| exactOperation.op === "approve_breaking_intent_revision"
 					) stagePlanningArtifactTransition(ctx.cwd, result.record);
 					return { state: "applied", operation, lifecycle: result.record.lifecycle };
-				} catch (error) {
-					if (sidecar && priorBytes) {
-						const current = await readTaskRecord(ctx.cwd, taskId);
-						if (current.record?.intent_snapshot.revision === priorIntent.intent.revision) {
-							writeFileSync(sidecar, priorBytes);
-							execFileSync("git", ["add", "--", priorIntent.intent_ref.path], {
-								cwd: ctx.cwd,
-								stdio: ["ignore", "pipe", "pipe"],
-							});
-						}
-					}
-					throw error;
+			} catch (error) {
+				if (sidecar && priorBytes && priorIndexState) {
+					const current = await readTaskRecord(ctx.cwd, taskId);
+					if (current.record?.intent_snapshot.revision === priorIntent.intent.revision) restoreStagedIntent();
 				}
+				throw error;
+			}
 			} catch (error) {
 				const reason = error instanceof Error ? error.message : String(error);
 				notifyOnce(ctx, `authorization-apply:${taskId}:${operation}:${reason}`, `authorize failed: ${reason}`, "error");
@@ -1018,7 +1105,7 @@ export async function recordCancelledUserDecision(
 			actor_id: "literal-user",
 		} as never,
 		prior_intent_token: (await readTaskIntent(ctx.cwd, taskId)).token,
-		diffProvider: (root: string, intent: { scope_hint: unknown }) => diffHashOf(root, intent),
+		diffProvider: (root: string, record: NonNullable<TaskRecordRead["record"]>) => diffSnapshotOf(root, record),
 		now: new Date().toISOString(),
 	});
 	return { recorded: true, finding_id: findingId };
@@ -1048,8 +1135,25 @@ export function userOperationFor(operation: AuthorizeOperation, approval?: unkno
 	return { op: "record_user_approval" as const, approval };
 }
 
-function diffHashOf(root: string, intent: { scope_hint?: unknown }): string {
-	return taskDiffHash(root, intent.scope_hint);
+/**
+ * One record-aware freshness identity. v4 derives the scoped revision digest
+ * from the immutable Enrollment base so committed and staged task work share a
+ * single diff_hash with Review; v3 keeps the legacy HEAD -> index digest.
+ */
+function diffSnapshotOf(root: string, record: NonNullable<TaskRecordRead["record"]>): {
+	diff_hash: string;
+	changed_paths: string[];
+} {
+	if (record.contract === "assurance_kernel/task_record/v4") {
+		if (!record.git_base_head)
+			throw new Error("TaskRecord v4 is missing git_base_head");
+		return taskRevisionIdentity(root, record.intent_snapshot.scope_hint, record.git_base_head);
+	}
+	return taskDiffIdentity(root, record.intent_snapshot.scope_hint);
+}
+
+function diffHashOf(root: string, record: NonNullable<TaskRecordRead["record"]>): string {
+	return diffSnapshotOf(root, record).diff_hash;
 }
 
 // Translation-only adapter for the internal Kernel assurance projection. All
@@ -1058,7 +1162,81 @@ function diffHashOf(root: string, intent: { scope_hint?: unknown }): string {
 // active-v2 migrator is gone: a v2 TaskRecord in the state layout is a
 // fail-closed projection error, never an automatic migration trigger.
 async function projectAssuranceState(root: string, taskId: string): Promise<AssuranceProjectionResult> {
-	return projectAssurance(root, taskId, diffHashOf);
+	return projectAssurance(root, taskId, diffSnapshotOf);
+}
+
+/**
+ * Publish and prove the task-scoped synthetic revision for a v4 record. v3
+ * records keep the legacy full-source bundle and return null here.
+ */
+async function ensureTaskReviewRevision(
+	root: string,
+	taskId: string,
+	projection: AssuranceProjectionResult,
+): Promise<ReviewRevision | null> {
+	const current = await readTaskRecord(root, taskId);
+	const record = current.record;
+	if (!record) throw new Error(`task ${taskId} has no TaskRecord before Review preparation`);
+	if (current.revision !== projection.projection.record_revision)
+		throw new Error("TaskRecord changed before Review preparation");
+	if (record.contract !== "assurance_kernel/task_record/v4") return null;
+	if (!record.git_base_head)
+		throw new Error("Review revision requires a TaskRecord v4 git_base_head");
+	const manifest = captureReviewManifest(root, {
+		taskId,
+		baseHead: record.git_base_head,
+		scopeHint: record.intent_snapshot.scope_hint,
+		expectedDiffHash: projection.projection.diff_hash,
+		intentRevision: projection.projection.intent_revision,
+		intentContentHash: projection.projection.intent_content_hash,
+		recordRevision: projection.projection.record_revision,
+		workspaceRevision: projection.projection.workspace_revision,
+		lifecycle: projection.projection.lifecycle,
+		artifactState: projection.projection.artifact_state,
+		risk: record.intent_snapshot.risk,
+		outcomes: reviewPreflightOutcomes(record.intent_snapshot.acceptance),
+	});
+	return {
+		contract: "assurance_kernel/review_revision/v1",
+		base_head: manifest.base_head,
+		review_tree: manifest.review_tree,
+		review_commit: manifest.review_commit,
+		review_ref: manifest.review_ref,
+		diff_hash: manifest.diff_hash,
+		manifest_digest: manifest.manifest_digest,
+	};
+}
+
+/**
+ * Review refs are reconstructible evidence transport, never workflow authority.
+ * A ref survives only while its task owns a nonterminal TaskRecord.
+ */
+async function reconcileReviewRevisionRefs(root: string): Promise<{ removed: string[]; failed: string[] }> {
+	let listed: ReturnType<typeof listReviewRefs>;
+	try {
+		listed = listReviewRefs(root);
+	} catch {
+		return { removed: [], failed: [] };
+	}
+	const live = new Set<string>();
+	try {
+		const claim = await readBackendClaim(root);
+		for (const entry of listed) {
+			if (live.has(entry.taskId)) continue;
+			try {
+				const record = await readTaskRecord(root, entry.taskId);
+				if (record.record && record.record.lifecycle === "active" && claim?.task_id === entry.taskId)
+					live.add(entry.taskId);
+			} catch {
+				// An unreadable owner is never proof of life, but deleting evidence on
+				// a transient read failure is worse: leave it for the next pass.
+				live.add(entry.taskId);
+			}
+		}
+	} catch {
+		for (const entry of listed) live.add(entry.taskId);
+	}
+	return reconcileReviewRefs(root, live);
 }
 
 export interface QaVerificationProgressInput {
@@ -1231,7 +1409,7 @@ async function applyAssuranceVerdict(
 				actor_id: actorId,
 			},
 			prior_intent_token: priorIntentToken,
-			diffProvider: (root: string, intent: { scope_hint: unknown }) => diffHashOf(root, intent),
+			diffProvider: (root: string, record: NonNullable<TaskRecordRead["record"]>) => diffSnapshotOf(root, record),
 			now,
 		}))) as unknown as { record: { lifecycle: string; artifact_state: string; intent_ref: { path: string }; intent_snapshot: { scope_hint: string[] }; findings?: Array<{ kind: string; status: string }> } };
 		stagePlanningArtifactTransition(ctx.cwd, result.record);
@@ -1256,6 +1434,11 @@ async function applyAssuranceVerdict(
 		diff_hash: snapshot.diff_hash,
 		actor_id: actorId,
 		summary: verdict.approval!.summary,
+		// Trusted revision identity comes from the host-verified snapshot, never
+		// from the reviewer payload.
+		...(snapshot.role === "review" && snapshot.review_revision
+			? { review_revision: snapshot.review_revision }
+			: {}),
 	};
 	const capability = await mintCapability(registry, {
 		authority_kind: snapshot.role,
@@ -1275,7 +1458,7 @@ async function applyAssuranceVerdict(
 		task_id: snapshot.task_id,
 		operation: { op: "record_approval", capability, approval, actor_id: actorId },
 		prior_intent_token: priorIntentToken,
-		diffProvider: (root: string, intent: { scope_hint: unknown }) => diffHashOf(root, intent),
+		diffProvider: (root: string, record: NonNullable<TaskRecordRead["record"]>) => diffSnapshotOf(root, record),
 		now,
 	}));
 }
@@ -1286,7 +1469,12 @@ async function buildAssuranceSnapshot(
 	role: AssuranceRole,
 	projection: AssuranceProjectionResult,
 	runner: FrozenRunner,
-): Promise<{ snapshot: SnapshotDescriptor; descriptors: Map<string, VerificationDescriptor>; reviewBundle: ReviewBundle | null }> {
+): Promise<{
+	snapshot: SnapshotDescriptor;
+	descriptors: Map<string, VerificationDescriptor>;
+	reviewBundle: ReviewBundle | null;
+	reviewManifest: ReviewManifestV5 | null;
+}> {
 	const record = await readTaskRecord(root, taskId);
 	if (
 		!record.record ||
@@ -1307,23 +1495,47 @@ async function buildAssuranceSnapshot(
 		assertRunnerCompatible(descriptor, runner);
 		descriptors.set(item.id, descriptor);
 	}
-	const reviewBundle = role === "review"
+	const reviewRevision = record.record.contract === "assurance_kernel/task_record/v4"
+		? {
+			contract: "assurance_kernel/review_revision_identity/v1" as const,
+			base_head: record.record.git_base_head,
+			review_commit: "",
+			review_tree: "",
+			manifest_digest: "",
+		}
+		: null;
+	const reviewBundle = role === "review" && !reviewRevision
 		? captureReviewBundle(
 				root,
 				intent.scope_hint,
 				projection.projection.diff_hash,
-				Object.fromEntries(
-					record.record.attestations
-						.filter((item) => item.kind === "qa")
-						.flatMap((item) => item.acceptance_results)
-						.map((result) => [result.acceptance_id, { status: result.status, summary: result.summary }]),
-				),
+				qaOutcomes(record.record),
 			)
 		: null;
-	const taskSnapshot = reviewBundle ? null : captureGitTaskSnapshot(root, intent.scope_hint);
-	const dirtyFiles = reviewBundle
-		? Object.keys(reviewBundle.dirty_files)
-		: Object.keys(taskSnapshot!.staged_files);
+	const reviewManifest = role === "review" && reviewRevision
+		? captureReviewManifest(root, {
+				taskId,
+				baseHead: reviewRevision.base_head,
+				scopeHint: intent.scope_hint,
+				expectedDiffHash: projection.projection.diff_hash,
+				intentRevision: projection.projection.intent_revision,
+				intentContentHash: projection.projection.intent_content_hash,
+				recordRevision: projection.projection.record_revision,
+				workspaceRevision: projection.projection.workspace_revision,
+				lifecycle: projection.projection.lifecycle,
+				artifactState: projection.projection.artifact_state,
+				risk: intent.risk,
+				outcomes: qaOutcomes(record.record),
+			})
+		: null;
+	const taskSnapshot = !reviewBundle && !reviewManifest
+		? captureGitTaskSnapshot(root, intent.scope_hint)
+		: null;
+	const dirtyFiles = reviewManifest
+		? Object.keys(reviewManifest.changed_paths)
+		: reviewBundle
+			? Object.keys(reviewBundle.dirty_files)
+			: Object.keys(taskSnapshot!.staged_files);
 	return {
 		snapshot: buildSnapshot({
 				root,
@@ -1342,13 +1554,43 @@ async function buildAssuranceSnapshot(
 				stale_attestation_ids: projection.projection.stale_attestation_ids,
 				acceptance,
 				dirty_files: dirtyFiles,
-				review_bundle_digest: reviewBundle?.bundle_digest ?? null,
+				review_bundle_digest: reviewManifest?.manifest_digest ?? reviewBundle?.bundle_digest ?? null,
+				review_revision: reviewManifest
+					? {
+							contract: "assurance_kernel/review_revision_identity/v1",
+							base_head: reviewManifest.base_head,
+							review_commit: reviewManifest.review_commit,
+							review_tree: reviewManifest.review_tree,
+							manifest_digest: reviewManifest.manifest_digest,
+						}
+						: undefined,
 		}),
 		descriptors,
 		reviewBundle,
+		reviewManifest,
 	};
 }
 
+function reviewPreflightOutcomes(
+	acceptance: Array<{ id: string }>,
+): Record<string, { status: "passed"; summary: string }> {
+	const summary = `host-attested QA: all ${acceptance.length} fixed verification descriptor(s) passed`;
+	return Object.fromEntries(
+		acceptance.map((item) => [item.id, { status: "passed" as const, summary }]),
+	);
+}
+
+function qaOutcomes(
+	record: NonNullable<TaskRecordRead["record"]>,
+): Record<string, { status: "passed" | "failed" | "blocked"; summary: string }> {
+	return Object.fromEntries(
+		record.attestations
+			.filter((item) => item.kind === "qa")
+			.flatMap((item) => item.acceptance_results)
+			.map((result) => [result.acceptance_id, { status: result.status, summary: result.summary }]),
+	);
+}
+
 let frozenRunnerValue: FrozenRunner | undefined;
 async function frozenRunner(): Promise<FrozenRunner> {
 	frozenRunnerValue ??= resolveBunRunner();
@@ -1407,7 +1649,9 @@ async function mintCapability(
 		intent_content_hash: input.intent_content_hash,
 		diff_hash: input.diff_hash,
 		actor_id: input.actor_id,
-		confirmation_ref: `pi-confirm-${createHash("sha256").update(`${input.task_id}\0${now}`).digest("hex").slice(0, 16)}`,
+		confirmation_ref: `pi-confirm-${createHash("sha256").update(
+			`${input.task_id}\0${now}\0${input.intent_revision}\0${input.intent_content_hash}\0${input.diff_hash}`,
+		).digest("hex").slice(0, 16)}`,
 		expires_at: new Date(Date.now() + 10 * 60 * 1000).toISOString(),
 		findings_digest:
 			input.action_kind === "request_rework"
@@ -1454,7 +1698,7 @@ async function executeOrdinaryOperation(
 			task_id: input.taskId,
 			operation: operation as never,
 			prior_intent_token: priorIntent.token,
-			diffProvider: (root: string, intent: { scope_hint: unknown }) => diffHashOf(root, intent),
+			diffProvider: (root: string, record: NonNullable<TaskRecordRead["record"]>) => diffSnapshotOf(root, record),
 			now: new Date().toISOString(),
 		});
 		if (operation.op === "freeze_artifacts" || operation.op === "stop")
@@ -1471,6 +1715,18 @@ async function executeOrdinaryOperation(
 
 type AssuranceTaskState = AssuranceProjectionResult["projection"] | { error: string };
 
+/**
+ * Ref cleanup is transport hygiene, never workflow authority: a failure is
+ * swallowed here and retried by the next startup or terminal reconciliation.
+ */
+async function reconcileRefsQuietly(root: string): Promise<void> {
+	try {
+		await reconcileReviewRevisionRefs(root);
+	} catch {
+		/* non-authoritative */
+	}
+}
+
 async function enrichAssuranceResult(
 	ctx: ExtensionContext,
 	taskId: string,
@@ -1481,6 +1737,7 @@ async function enrichAssuranceResult(
 		? { error: projection.error }
 		: projection.projection;
 	let tracker: Awaited<ReturnType<typeof markGithubTaskTerminal>> | undefined;
+	await reconcileRefsQuietly(ctx.cwd);
 	if (!projection.error) {
 		try {
 			const terminalInput = deriveGithubTerminalProjectionInput(
@@ -1509,9 +1766,11 @@ async function enrichAssuranceResult(
 
 function nextActionForAssuranceResult(result: Record<string, unknown>, taskState: AssuranceTaskState): string {
 	if ("error" in taskState) return "inspect authority state";
+	if (result.state === "review_preparation_failed") return "retry advance_assurance";
+	if (result.code === "verdict_invalid") return "fix the verdict payload and resubmit submit_review; the Review reservation remains active; do not re-dispatch the reviewer";
 	if (taskState.lifecycle === "done" || taskState.lifecycle === "stopped") return "none";
 	switch (result.state) {
-		case "review_ready": return "invoke the reserved foreground Agent";
+		case "review_ready": return "invoke the foreground reviewer and submit its verdict";
 		case "awaiting_user": return "request_authorization";
 		case "applied": return taskState.completion_ready ? "complete task" : taskState.next_obligation;
 		case "completed":
@@ -1529,6 +1788,37 @@ function toolResult(text: string, details?: Record<string, unknown>) {
 	return { content: [{ type: "text" as const, text }], details };
 }
 
+/**
+ * Pre-validation compatibility recovery for providers that encode the
+ * object-valued Tool `action` as a JSON string (observed with
+ * `hyper/qwen3.8-flash`: `{ "action": "{\"op\":\"status\"}" }`).
+ *
+ * Only the top-level `action` field is parsed, and only when it parses to a
+ * non-null, non-array object. Native object input, invalid JSON, arrays,
+ * `null`, primitives, and every other shape are returned unchanged so the
+ * strict TypeBox schemas remain the authoritative boundary. Nested string
+ * fields (`context`, `next_intent`, `finding`) are deliberately never
+ * touched; this helper does not validate schemas, mutate inputs, or throw.
+ *
+ * Temporary compatibility layer owned by GitHub Issue #14
+ * (github.com/dereknex/immune-brain/issues/14): remove after two consecutive
+ * Pi or Hyper adapter upgrade cycles pass a live nested-object Tool-call
+ * probe at least 30 days apart.
+ */
+function prepareActionArgs(args: unknown): unknown {
+	if (args === null || typeof args !== "object" || Array.isArray(args)) return args;
+	const input = args as Record<string, unknown>;
+	if (typeof input.action !== "string") return input;
+	try {
+		const parsed: unknown = JSON.parse(input.action);
+		if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed))
+			return { ...input, action: parsed };
+	} catch {
+		// Unchanged input keeps the normal host schema error authoritative.
+	}
+	return input;
+}
+
 function stagePlanningArtifactTransition(root: string, record: {
 	intent_ref: { path: string };
 	intent_snapshot: { scope_hint: string[] };
@@ -1585,7 +1875,7 @@ function throwIfCanaryToolFailure(
 		taskId,
 		operation,
 		result.state,
-		`assurance_${result.state}`,
+		typeof result.code === "string" ? result.code : `assurance_${result.state}`,
 		typeof result.reason === "string"
 			? result.reason
 			: typeof result.result === "string"