immune-brain 3.6.2 → 3.6.4

package/plugins/immune-brain/dist/claude/mcp-server.mjs

@@ -42,7 +42,7 @@ function probeHost(env = process.env, platform = process.platform, hostVersion)
 }
 
 // plugins/immune-brain/runtime/plugin_version.ts
-var PLUGIN_VERSION = "3.6.2";
+var PLUGIN_VERSION = "3.6.4";
 
 // plugins/immune-brain/runtime/claude/interaction.ts
 import { createHash, randomUUID } from "node:crypto";
@@ -99,7 +99,7 @@ function enrollmentNonce() {
 
 // plugins/immune-brain/runtime/claude/review_host.ts
 import { createHash as createHash2 } from "node:crypto";
-import { constants, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, rmSync, writeSync, closeSync } from "node:fs";
+import { constants, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, rmSync, writeSync, closeSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 var REVIEWER_AGENT = "immune-brain-reviewer";
@@ -183,7 +183,7 @@ function appendPrivate(path, dir, line) {
     closeSync(fd);
   }
 }
-function readPrivate(path) {
+function readPrivate(path, maxBytes = Number.POSITIVE_INFINITY) {
   let fd;
   try {
     fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
@@ -194,6 +194,8 @@ function readPrivate(path) {
     const stat = fstatSync(fd);
     if (!stat.isFile() || !ownedByUs(stat) || (stat.mode & 511) !== 384)
       return;
+    if (stat.size > maxBytes)
+      return;
     const buf = Buffer.alloc(stat.size);
     readSync(fd, buf, 0, stat.size, 0);
     return buf.toString("utf8");
@@ -201,6 +203,67 @@ function readPrivate(path) {
     closeSync(fd);
   }
 }
+var MAX_TRANSCRIPT_BYTES = 32 * 1024 * 1024;
+function parseAsyncAgentLaunch(result) {
+  let payload;
+  try {
+    payload = JSON.parse(result);
+  } catch {
+    return null;
+  }
+  if (!payload || typeof payload !== "object")
+    return null;
+  const obj = payload;
+  if (obj.isAsync !== true && obj.status !== "async_launched")
+    return null;
+  const agentId = typeof obj.agentId === "string" ? obj.agentId : "";
+  const outputFile = typeof obj.outputFile === "string" ? obj.outputFile : "";
+  if (!agentId || !outputFile)
+    return null;
+  return { agentId, outputFile };
+}
+function readAgentTranscriptResult(transcript, agentId) {
+  let last = null;
+  for (const line of transcript.split(`
+`)) {
+    if (!line.trim())
+      continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (row.type !== "assistant" || row.agentId !== agentId)
+      continue;
+    const message = row.message;
+    if (!message || typeof message !== "object")
+      continue;
+    const content = message.content;
+    if (!Array.isArray(content))
+      continue;
+    let text = "";
+    for (const block of content) {
+      if (!block || typeof block !== "object")
+        continue;
+      const part = block;
+      if (part.type === "text" && typeof part.text === "string")
+        text += part.text;
+    }
+    if (text.trim())
+      last = text;
+  }
+  return last;
+}
+function readAgentTranscript(path) {
+  let resolved;
+  try {
+    resolved = realpathSync(path);
+  } catch {
+    return;
+  }
+  return readPrivate(resolved, MAX_TRANSCRIPT_BYTES);
+}
 function hookEventPath(sessionId, root = tmpdir()) {
   return join(cacheDir(root), `${sessionHash(sessionId)}.jsonl`);
 }
@@ -288,6 +351,7 @@ class ClaudeReviewHost {
     this.log = log;
   }
   prepareReview(request) {
+    this.drain();
     const initialCursors = new Map;
     const sessionCursors = new Map;
     for (const sessionId of this.log.sessions()) {
@@ -325,15 +389,23 @@ ${request.prompt}`,
       for (let i = start;i < events.length; i++) {
         const event = events[i];
         if (event.type === "SessionEnd") {
-          this.log.clear(event.sessionId);
-          ended = true;
-          this.appliedBySession.delete(event.sessionId);
           for (const [id, state] of this.pending) {
             if (state.startEvent?.sessionId === event.sessionId || state.postEvent?.sessionId === event.sessionId || state.stopEvent?.sessionId === event.sessionId) {
               this.pending.delete(id);
             }
           }
-          break;
+          for (const state of this.pending.values()) {
+            const current = state.initialCursors.get(sessionId) ?? 0;
+            if (i + 1 > current)
+              state.initialCursors.set(sessionId, i + 1);
+          }
+          if (i === events.length - 1) {
+            this.log.clear(event.sessionId);
+            ended = true;
+            this.appliedBySession.delete(event.sessionId);
+            break;
+          }
+          continue;
         }
         for (const state of this.pending.values()) {
           if (state.consumed || state.error || i < (state.initialCursors.get(sessionId) ?? 0))
@@ -460,13 +532,23 @@ ${request.prompt}`,
     if (state.startEvent.sessionId !== state.postEvent.sessionId || state.startEvent.sessionId !== state.stopEvent.sessionId || state.startEvent.agentId !== state.postEvent.agentId || state.startEvent.agentId !== state.stopEvent.agentId) {
       return { ok: false, reason: "foreground Agent terminal event correlation mismatch", release: true };
     }
-    return {
-      ok: true,
-      receipt: {
-        actorId: `claude:${state.startEvent.agentId ?? reservation.id}`,
-        result: state.postEvent.result
-      }
-    };
+    const actorId = `claude:${state.startEvent.agentId ?? reservation.id}`;
+    const launch = parseAsyncAgentLaunch(state.postEvent.result);
+    if (!launch) {
+      return { ok: true, receipt: { actorId, result: state.postEvent.result } };
+    }
+    if (launch.agentId !== state.postEvent.agentId) {
+      return { ok: false, reason: "async Agent launch envelope names a different agent", release: true };
+    }
+    const transcript = readAgentTranscript(launch.outputFile);
+    if (transcript === undefined) {
+      return { ok: false, reason: "async Agent transcript is not readable", release: false };
+    }
+    const verdict = readAgentTranscriptResult(transcript, launch.agentId);
+    if (!verdict?.trim()) {
+      return { ok: false, reason: "async Agent transcript carries no reviewer result", release: false };
+    }
+    return { ok: true, receipt: { actorId, result: verdict } };
   }
   consumeReview(reservation) {
     const result = this.inspectReview(reservation);
@@ -514,6 +596,11 @@ function parseHookStdin(raw) {
     if (typeof toolInputObj.prompt === "string")
       prompt = toolInputObj.prompt;
   }
+  if (!prompt && typeof payload.tool_response === "object" && payload.tool_response !== null) {
+    const toolResponseObj = payload.tool_response;
+    if (typeof toolResponseObj.prompt === "string")
+      prompt = toolResponseObj.prompt;
+  }
   let extractedOpId = operationId;
   let extractedTaskId = taskId;
   for (const candidate of [payload.input, payload.tool_input, payload.tool_response, payload.toolResponse, payload.response, payload.result]) {
@@ -602,7 +689,7 @@ import { createHash as createHash5, randomUUID as randomUUID2 } from "node:crypt
 // plugins/immune-brain/runtime/assurance/verification.ts
 import { createHash as createHash3 } from "node:crypto";
 import { execFileSync, spawn } from "node:child_process";
-import { realpathSync, statSync } from "node:fs";
+import { realpathSync as realpathSync2, statSync } from "node:fs";
 import { isAbsolute as isAbsolute2, resolve, sep as sep2, relative } from "node:path";
 
 // plugins/immune-brain/runtime/verification_descriptor.ts
@@ -705,7 +792,7 @@ function resolveBunRunner() {
   }
   let real;
   try {
-    real = realpathSync(executable);
+    real = realpathSync2(executable);
   } catch {
     throw new VerificationDescriptorError("bun runner realpath is unresolvable");
   }
@@ -1710,7 +1797,7 @@ import {
   writeFileSync,
   statSync as statSync2,
   readFileSync as readFileSync3,
-  realpathSync as realpathSync3,
+  realpathSync as realpathSync4,
   chmodSync
 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
@@ -1724,7 +1811,7 @@ import {
   lstatSync as lstatSync2,
   readFileSync as readFileSync2,
   readlinkSync,
-  realpathSync as realpathSync2
+  realpathSync as realpathSync3
 } from "node:fs";
 import { resolve as resolve2 } from "node:path";
 function git(root, args) {
@@ -1891,7 +1978,7 @@ function taskSnapshotOnce(root, scope) {
   const head = git(root, ["rev-parse", "--verify", "HEAD^{commit}"])?.trim();
   if (!repositoryRoot || !head || !GIT_OBJECT_ID.test(head))
     throw new Error("cannot derive task snapshot outside a committed Git workspace");
-  if (realpathSync2(resolve2(repositoryRoot)) !== root)
+  if (realpathSync3(resolve2(repositoryRoot)) !== root)
     throw new Error("task snapshot repository root does not match the project root");
   const sparseCheckout = git(root, ["config", "--bool", "core.sparseCheckout"])?.trim();
   const sparseIndex = git(root, ["config", "--bool", "index.sparse"])?.trim();
@@ -1935,7 +2022,7 @@ function captureGitTaskSnapshot(projectRoot, scopeHint) {
   const requestedStat = lstatSync2(requestedRoot);
   if (requestedStat.isSymbolicLink() || !requestedStat.isDirectory())
     throw new Error("task snapshot root must be a real directory");
-  const root = realpathSync2(requestedRoot);
+  const root = realpathSync3(requestedRoot);
   const scope = assertCanonicalTaskScope(scopeHint);
   const before = taskSnapshotOnce(root, scope);
   gitTaskSnapshotTestHook?.();
@@ -1968,7 +2055,7 @@ function taskRevisionSnapshotOnce(root, scope, baseHead) {
   const head = git(root, ["rev-parse", "--verify", "HEAD^{commit}"])?.trim();
   if (!repositoryRoot || !head || !GIT_OBJECT_ID.test(head))
     throw new Error("cannot derive a task revision outside a committed Git workspace");
-  if (realpathSync2(resolve2(repositoryRoot)) !== root)
+  if (realpathSync3(resolve2(repositoryRoot)) !== root)
     throw new Error("task revision repository root does not match the project root");
   if (gitRequired(root, ["cat-file", "-t", baseHead], `task revision base is unreadable: ${baseHead}`) !== "commit")
     throw new Error(`task revision base is not a commit: ${baseHead}`);
@@ -2025,7 +2112,7 @@ function captureGitTaskRevisionSnapshot(projectRoot, scopeHint, baseHead) {
   const requestedStat = lstatSync2(requestedRoot);
   if (requestedStat.isSymbolicLink() || !requestedStat.isDirectory())
     throw new Error("task revision root must be a real directory");
-  const root = realpathSync2(requestedRoot);
+  const root = realpathSync3(requestedRoot);
   if (typeof baseHead !== "string" || !GIT_OBJECT_ID.test(baseHead.toLowerCase()))
     throw new Error("task revision base must be a Git commit id");
   const scope = assertCanonicalTaskScope(scopeHint);
@@ -2397,13 +2484,10 @@ function captureReviewManifest(root, input) {
     throw new Error("immutable review manifest metadata exceeds bounded output limit");
   return manifest;
 }
-function ensureReviewRevision(root, input) {
-  return publishInput(root, input).revision;
-}
 function writeNativeReviewEvidence(payload) {
   const rawDirectory = mkdtempSync(join4(tmpdir2(), "imm-canary-native-review-"));
   try {
-    const directory = realpathSync3(rawDirectory);
+    const directory = realpathSync4(rawDirectory);
     chmodSync(directory, 493);
     const path = join4(directory, "evidence.json");
     writeFileSync(path, JSON.stringify(payload), { encoding: "utf8", mode: 420, flag: "wx" });
@@ -2418,7 +2502,7 @@ function writeNativeReviewEvidence(payload) {
   }
 }
 function assertReviewArtifact(path) {
-  const targetPath = realpathSync3(path);
+  const targetPath = realpathSync4(path);
   let stat;
   try {
     stat = statSync2(targetPath);
@@ -2612,7 +2696,7 @@ import {
   mkdirSync as mkdirSync2,
   openSync as openSync3,
   readFileSync as readFileSync6,
-  realpathSync as realpathSync5,
+  realpathSync as realpathSync6,
   renameSync,
   rmSync as rmSync3,
   writeFileSync as writeFileSync2
@@ -2629,6 +2713,9 @@ var TASK_RECORD_CONTRACT_V2 = "assurance_kernel/task_record/v2";
 var TASK_RECORD_CONTRACT_V3 = "assurance_kernel/task_record/v3";
 var TASK_RECORD_CONTRACT_V4 = "assurance_kernel/task_record/v4";
 var REVIEW_REVISION_IDENTITY_CONTRACT = "assurance_kernel/review_revision_identity/v1";
+function isTaskRecordV4(record) {
+  return record.contract === TASK_RECORD_CONTRACT_V4;
+}
 var REDUCED_MUTATION_BRAND = Symbol("assurance-kernel-reduced-mutation-v2");
 var MUTATION_AUTHORITY_CAPABILITY_BRAND = Symbol("assurance-kernel-mutation-authority-capability");
 
@@ -2641,7 +2728,7 @@ import {
   lstatSync as lstatSync4,
   openSync as openSync2,
   readFileSync as readFileSync5,
-  realpathSync as realpathSync4
+  realpathSync as realpathSync5
 } from "node:fs";
 import { execFileSync as execFileSync3 } from "node:child_process";
 import { join as join6, resolve as resolve4, sep as sep3 } from "node:path";
@@ -2939,7 +3026,7 @@ function resolveCanonicalRoot(root) {
   const rootStat = lstatSync4(resolved);
   if (rootStat.isSymbolicLink() || !rootStat.isDirectory())
     throw new Error("project root must be a real directory, not a symlink");
-  return realpathSync4(resolved);
+  return realpathSync5(resolved);
 }
 function resolveSidecarPath(canonicalRoot, activePath, archivedPath) {
   if (sidecarPresent(canonicalRoot, activePath))
@@ -3016,7 +3103,7 @@ function readTaskIntent(root, taskId, requestedPath) {
   const after = lstatSync4(target);
   assertSameIdentity(statIdentity(before), after, "intent sidecar");
   assertIdentitiesUnchanged(pathIdentities, canonicalRoot, sidecarPath);
-  const canonicalAgain = realpathSync4(root);
+  const canonicalAgain = realpathSync5(root);
   if (canonicalAgain !== canonicalRoot)
     throw new Error("canonical project root drifted while being read");
   if (lstatSync4(canonicalAgain).isSymbolicLink())
@@ -3759,7 +3846,7 @@ function revisionFor(content) {
 }
 function canonicalRoot(root) {
   try {
-    return realpathSync5(root);
+    return realpathSync6(root);
   } catch {
     throw new KernelStoreSecurityError("project root is unavailable");
   }
@@ -5650,6 +5737,8 @@ function applyTaskAction(input) {
       };
     }
     if (input.terminal) {
+      if (nextRecord.lifecycle === "active")
+        throw new Error("terminal settlement requires a done or stopped TaskRecord lifecycle");
       const tombstone = {
         contract: TASK_TOMBSTONE_CONTRACT,
         task_id,
@@ -6389,6 +6478,8 @@ function enrollCanaryTask(root, input, registry) {
     if (checks.gitBaseHead !== gitBaseHead)
       throw new Error("Git HEAD moved after the enrollment confirmation");
     registry.consume(input.capability, input.capability_binding);
+    if (!gitBaseHead)
+      throw new Error("enrollment requires a committed Git HEAD");
     const record = buildTaskRecordV4(input, checks.intent, gitBaseHead);
     const nextWorkspace = {
       ...checks.workspace.state,
@@ -6564,6 +6655,9 @@ async function submitClaudeReview(host, coordinator, ctx, taskId, verdictInput)
   }
   return coordinator.submitReview(taskId, ctx, verdictInput);
 }
+function stopReason(value) {
+  return typeof value === "string" && value.length > 0 ? value : "user stop";
+}
 function assertProjectionBinding(before, after, allowDiffChange = false) {
   const fields = allowDiffChange ? ["record_revision", "workspace_revision", "intent_revision", "intent_content_hash"] : ["record_revision", "workspace_revision", "intent_revision", "intent_content_hash", "diff_hash"];
   if (before.error || !before.claim || after.error || !after.claim || before.claim.task_id !== after.claim.task_id || fields.some((field) => before.projection[field] !== after.projection[field])) {
@@ -6573,22 +6667,57 @@ function assertProjectionBinding(before, after, allowDiffChange = false) {
 function qaOutcomes(record) {
   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 }]));
 }
+async function ensureClaudeReviewRevision(root, taskId, projection) {
+  const current = await readTaskRecord(root, taskId);
+  const record = current.record;
+  if (!record)
+    throw new Error(`task ${taskId} has no TaskRecord`);
+  if (current.revision !== projection.projection.record_revision)
+    throw new Error("TaskRecord changed before Review revision 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: qaOutcomes(record)
+  });
+  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
+  };
+}
 async function buildAssuranceSnapshot(root, taskId, role, projection, runner) {
-  const record = await readTaskRecord(root, taskId);
-  if (!record.record || record.revision !== projection.projection.record_revision)
+  const read = await readTaskRecord(root, taskId);
+  const record = read.record;
+  if (!record || read.revision !== projection.projection.record_revision)
     throw new Error("TaskRecord changed before assurance snapshot capture");
-  const intent = record.record.intent_snapshot;
+  const intent = record.intent_snapshot;
   const descriptors = new Map;
   for (const item of intent.acceptance) {
     const descriptor = parseVerificationDescriptor(item.verification);
     assertRunnerCompatible(descriptor, runner);
     descriptors.set(item.id, descriptor);
   }
-  const v4 = record.record.contract === "assurance_kernel/task_record/v4";
-  const reviewBundle = role === "review" && !v4 ? captureReviewBundle(root, intent.scope_hint, projection.projection.diff_hash, qaOutcomes(record.record)) : null;
-  const reviewManifest = role === "review" && v4 ? captureReviewManifest(root, {
+  const reviewBundle = role === "review" && !isTaskRecordV4(record) ? captureReviewBundle(root, intent.scope_hint, projection.projection.diff_hash, qaOutcomes(record)) : null;
+  const reviewManifest = role === "review" && isTaskRecordV4(record) ? captureReviewManifest(root, {
     taskId,
-    baseHead: record.record.git_base_head,
+    baseHead: record.git_base_head,
     scopeHint: intent.scope_hint,
     expectedDiffHash: projection.projection.diff_hash,
     intentRevision: projection.projection.intent_revision,
@@ -6598,7 +6727,7 @@ async function buildAssuranceSnapshot(root, taskId, role, projection, runner) {
     lifecycle: projection.projection.lifecycle,
     artifactState: projection.projection.artifact_state,
     risk: intent.risk,
-    outcomes: qaOutcomes(record.record)
+    outcomes: qaOutcomes(record)
   }) : null;
   const dirtyFiles = reviewManifest ? Object.keys(reviewManifest.changed_paths) : reviewBundle ? Object.keys(reviewBundle.dirty_files) : [];
   const snapshot = {
@@ -6697,11 +6826,11 @@ class ClaudeRuntime {
     this.interactive = options.interactive ?? true;
     this.requestConfirmation = options.requestConfirmation;
     this.host = options.host ?? new ClaudeReviewHost(new FileHookEventLog);
-    if (options.ports) {
-      this.coordinator = new AssuranceCoordinator({ ...options.ports, host: this.host });
-      return;
-    }
-    this.coordinator = new AssuranceCoordinator(this.createKernelPorts());
+    this.coordinator = new AssuranceCoordinator({
+      ...this.createKernelPorts(),
+      ...options.ports,
+      host: this.host
+    });
   }
   observe(event) {
     this.host.observe(event);
@@ -6715,27 +6844,18 @@ class ClaudeRuntime {
   async shutdown() {
     await this.coordinator.onSessionShutdown();
   }
+  kernelPorts() {
+    return this.createKernelPorts();
+  }
   createKernelPorts() {
     return {
       host: this.host,
       projectTask: (root, taskId) => projectAssurance(root, taskId, diffSnapshotOf),
-      readTaskRecord: (root, taskId) => readTaskRecord(root, taskId),
-      readTaskIntent: (root, taskId) => readTaskIntentForRecord(root, taskId),
+      readTaskRecord: async (root, taskId) => readTaskRecord(root, taskId),
+      readTaskIntent: async (root, taskId) => readTaskIntentForRecord(root, taskId),
       frozenRunner: async () => resolveBunRunner(),
       buildAssurance: (root, taskId, role, projection, runner) => buildAssuranceSnapshot(root, taskId, role, projection, runner),
-      ensureReviewRevision: async (root, taskId, projection) => {
-        const current = await readTaskRecord(root, taskId);
-        if (!current.record)
-          throw new Error(`task ${taskId} has no TaskRecord`);
-        if (current.record.contract !== "assurance_kernel/task_record/v4")
-          return null;
-        return ensureReviewRevision(root, {
-          taskId,
-          baseHead: current.record.git_base_head,
-          scopeHint: current.record.intent_snapshot.scope_hint,
-          expectedDiffHash: projection.projection.diff_hash
-        });
-      },
+      ensureReviewRevision: (root, taskId, projection) => ensureClaudeReviewRevision(root, taskId, projection),
       runQa: (snapshot, descriptors, runner, options) => runDeterministicQa(snapshot, descriptors, runner, options),
       writeReviewEvidence: (input) => writeNativeReviewEvidence(input.evidence),
       applyVerdict: (ctx, input) => this.applyVerdict(ctx, input),
@@ -6950,7 +7070,7 @@ class ClaudeRuntime {
         confirmation_ref: confirmation,
         ...op === "approve_breaking_intent_revision" ? { next_intent: nextIntent, next_intent_ref: nextIntentRef } : {},
         ...op === "resolve_user_decision" && decisionOp ? decisionOp : {},
-        ...op === "stop" ? { reason: extra.reason ?? "user stop" } : {}
+        ...op === "stop" ? { reason: stopReason(extra.reason) } : {}
       });
       throwIfCancelled(meta.signal);
       const result = app.execute({
@@ -6962,7 +7082,7 @@ class ClaudeRuntime {
           actor_id: actorId,
           ...op === "approve_breaking_intent_revision" ? { next_intent: nextIntent, next_intent_ref: nextIntentRef } : {},
           ...op === "resolve_user_decision" && decisionOp ? decisionOp : {},
-          ...op === "stop" ? { reason: extra.reason ?? "user stop" } : {}
+          ...op === "stop" ? { reason: stopReason(extra.reason) } : {}
         },
         prior_intent_token: priorIntent.token,
         diffProvider: diffSnapshotOf,

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

@@ -17,6 +17,7 @@ import { createInvocationRegistry, type InvocationState, type InvocationToken }
 import type { ReviewBundle, ReviewManifestV5, ReviewRevision } from "./review_evidence";
 import { buildRoleDelegationPacket } 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";
 
 export type AssuranceRole = "qa" | "review";
@@ -38,7 +39,11 @@ export interface TaskRecordRead {
 	record?: { contract?: string; findings: Array<{ kind: string; status: string }> } | null;
 }
 export interface TaskIntentRead {
-	token?: string;
+	/**
+	 * The kernel's own intent identity token. Declared as `string` before this
+	 * port was ever type checked, which is a shape no host reader has produced.
+	 */
+	token?: TaskIntentIdentityToken;
 }
 
 export interface GithubTerminalProjectionInput {
@@ -873,7 +878,17 @@ export class AssuranceCoordinator {
 		}
 	}
 
-	private unknownAfterCommit(taskId: string, operation: "qa" | "review", operationId: string, reason: string): AssuranceAdvanceResult {
+	/**
+	 * Declared as the wider advance result, which made it unusable from
+	 * `submitReview` without an implicit widen. The value has always been the
+	 * settlement_unknown member both result unions share.
+	 */
+	private unknownAfterCommit(
+		taskId: string,
+		operation: "qa" | "review",
+		operationId: string,
+		reason: string,
+	): { state: "settlement_unknown"; operation: "qa" | "review"; operation_id: string; reason: string } {
 		this.unknownOperations.set(taskId, { operation, operationId, reason });
 		return { state: "settlement_unknown", operation, operation_id: operationId, reason };
 	}

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

@@ -240,14 +240,32 @@ const SNAPSHOT_IDENTITY = {
 	date: "1970-01-01T00:00:00 +0000",
 };
 
-export interface ReviewRevision {
+/**
+ * The bare synthetic-commit identity. `publishReviewRevision` can prove these
+ * five fields from Git alone; it has no manifest inputs and therefore cannot
+ * produce a digest.
+ */
+export interface ReviewRevisionCommit {
 	contract: "assurance_kernel/review_revision/v1";
 	base_head: string;
 	review_tree: string;
 	review_commit: string;
 	review_ref: string;
 	diff_hash: string;
-	manifest_digest?: string;
+}
+
+/**
+ * The full Review revision identity a host port must return.
+ *
+ * `manifest_digest` was optional here, which is the type-level hole that let a
+ * host return the bare commit identity and still satisfy
+ * `AssuranceCoordinatorPorts.ensureReviewRevision`. `submitReview` compares all
+ * four identity fields against the reservation, so an absent digest compared
+ * against a real one and failed every v4 submission at runtime instead of at
+ * build time. Requiring it makes that omission a compile error.
+ */
+export interface ReviewRevision extends ReviewRevisionCommit {
+	manifest_digest: string;
 }
 
 export interface ReviewManifestV5 {
@@ -354,7 +372,7 @@ export function publishReviewRevision(
 	snapshot: GitTaskRevisionSnapshot,
 	diffHash: string,
 	taskId: string,
-): ReviewRevision {
+): ReviewRevisionCommit {
 	if (snapshot.base_head !== snapshot.base_head.toLowerCase() || !GIT_COMMIT_ID.test(snapshot.base_head))
 		throw new Error("review revision base has invalid identity");
 	if (!REVISION_DIFF_HASH.test(diffHash)) throw new Error("review revision diff hash has invalid identity");
@@ -429,7 +447,7 @@ function publishInput(
 		scopeHint: unknown;
 		expectedDiffHash: string;
 	},
-): { snapshot: GitTaskRevisionSnapshot; revision: ReviewRevision } {
+): { snapshot: GitTaskRevisionSnapshot; revision: ReviewRevisionCommit } {
 	if (typeof input.baseHead !== "string" || !GIT_COMMIT_ID.test(input.baseHead))
 		throw new Error("review requires a TaskRecord v4 git_base_head");
 	if (!REVISION_DIFF_HASH.test(input.expectedDiffHash))
@@ -486,14 +504,6 @@ export function captureReviewManifest(
 	return manifest;
 }
 
-/** Publish and return the exact revision a v4 task must use. */
-export function ensureReviewRevision(
-	root: string,
-	input: { taskId: string; baseHead: string; scopeHint: unknown; expectedDiffHash: string },
-): ReviewRevision {
-	return publishInput(root, input).revision;
-}
-
 export function listReviewRefs(root: string): Array<{ ref: string; commit: string; taskId: string }> {
 	const output = gitEvidence(root, ["for-each-ref", "--format=%(refname) %(objectname)", `${REVIEW_REF_NAMESPACE}/`]);
 	const refs: Array<{ ref: string; commit: string; taskId: string }> = [];
@@ -534,7 +544,7 @@ export function reconcileReviewRefs(
 	return { removed, failed };
 }
 
-export function deleteReviewRef(root: string, revision: ReviewRevision): void {
+export function deleteReviewRef(root: string, revision: ReviewRevisionCommit): void {
 	const parts = revision.review_ref.split("/");
 	let validRef = false;
 	if (