immune-brain 5.1.0 → 5.1.2

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

@@ -12,8 +12,11 @@ import {
 	type NativeConfirmationPort,
 } from "./interaction";
 import { ClaudeReviewHost, FileHookEventLog, parseHookStdin } from "./review_host";
+import { activeTaskHookOutput, laneGuardHookOutput } from "./lane_guard";
 import { ClaudeRuntime, type ToolMeta } from "./kernel_ports";
-import { parseLaneOffers, parseMaxParallel, resolveLaneParallel } from "../unattended/batch_lanes";
+import { parseLaneInstruction, parseLaneOffers, parseMaxParallel, resolveLaneParallel } from "../unattended/batch_lanes";
+import { parseFinalVerification } from "../unattended/batch_final_verification";
+import { parseLaneRevision, REVISION_DELEGATION_TEXT } from "../unattended/batch_delegation";
 import type { AssuranceCoordinatorPorts } from "../assurance/coordinator";
 
 export const MCP_PROTOCOL_VERSION = "2025-06-18";
@@ -22,12 +25,13 @@ export const TOOLS = [
 	{ name: "status", description: "Read the Kernel Assurance Projection for an exact task.", privileged: false },
 	{ name: "enroll", description: "Enroll a Git-tracked TaskIntent after native confirmation.", privileged: true },
 	{ name: "advance_assurance", description: "Advance frozen Assurance through deterministic QA and Review reservation.", privileged: false },
-	{ name: "submit_review", description: "Submit the Parent-mediated Review verdict bound to the correlated receipt.", privileged: false },
+	{ name: "submit_review", description: "Submit the Review verdict; omit the verdict to apply the correlated reviewer receipt, or relay the reviewer's structured verdict for fingerprint comparison.", privileged: false },
 	{ name: "request_authorization", description: "Apply exact literal-user authorization.", privileged: true },
 	{ name: "revise_intent", description: "Apply a compatible TaskIntent revision.", privileged: false },
 	{ name: "approve_breaking_intent_revision", description: "Approve a breaking TaskIntent revision.", privileged: true },
 	{ name: "stop", description: "Stop the active task with literal-user authority.", privileged: true },
 	{ name: "start_unattended_batch", description: "Start an unattended serial batch run for an Initiative after native confirmation.", privileged: true },
+	{ name: "retire_stale_batch", description: "Retire an Initiative's parked or drifted batch record to the terminal superseded state after native confirmation.", privileged: true },
 	{ name: "repair_authority_state", description: "Repair a proven recoverable stale backend claim.", privileged: false },
 	{ name: "resolve_finding", description: "Resolve one open blocking or advisory finding whose cause is fixed and verified.", privileged: false },
 	{ name: "refute_finding", description: "Refute one open finding by binding the fresh passing QA attestation that contradicts it.", privileged: false },
@@ -40,20 +44,42 @@ export function listMcpTools() {
 		inputSchema: {
 			type: "object",
 			properties: {
-				...(tool.name === "start_unattended_batch"
+				...(tool.name === "start_unattended_batch" || tool.name === "retire_stale_batch"
 					? {
 						initiative_slug: { type: "string" },
-						max_parallel: { type: "integer", minimum: 1 },
-						lane_offers: {
-							type: "array",
-							items: {
-								type: "object",
-								properties: { task_id: { type: "string" }, path: { type: "string" } },
-								required: ["task_id", "path"],
-								additionalProperties: false,
-							},
-						},
-					}
+						...(tool.name === "start_unattended_batch"
+							? {
+									max_parallel: { type: "integer", minimum: 1 },
+									lane_offers: {
+										type: "array",
+										items: {
+											type: "object",
+											properties: { task_id: { type: "string" }, path: { type: "string" } },
+											required: ["task_id", "path"],
+											additionalProperties: false,
+										},
+									},
+									final_verification: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8 },
+									lane_instruction: {
+										type: "object",
+										properties: {
+											task_id: { type: "string" },
+											kind: { type: "string", enum: ["instruction", "correction"] },
+											text: { type: "string" },
+											session_state: { type: "string", enum: ["idle", "working", "blocked", "done"] },
+										},
+										required: ["task_id", "text", "session_state"],
+										additionalProperties: false,
+									},
+									lane_revision: {
+										type: "object",
+										properties: { task_id: { type: "string" }, next_intent: { type: "object" } },
+										required: ["task_id", "next_intent"],
+										additionalProperties: false,
+									},
+								}
+							: {}),
+						}
 					: {
 						task_id: { type: "string" },
 						...(tool.name === "approve_breaking_intent_revision" || tool.name === "revise_intent" ? { next_intent: { type: "object" } } : {}),
@@ -63,17 +89,15 @@ export function listMcpTools() {
 						...(tool.name === "refute_finding" ? { finding_id: { type: "string" }, attestation_id: { type: "string" } } : {}),
 					}),
 			},
-			required: tool.name === "start_unattended_batch"
+			required: tool.name === "start_unattended_batch" || tool.name === "retire_stale_batch"
 				? ["initiative_slug"]
-				: tool.name === "submit_review"
-					? ["task_id", "verdict"]
-					: tool.name === "resolve_finding"
-						? ["task_id", "finding_id"]
-						: tool.name === "refute_finding"
-							? ["task_id", "finding_id", "attestation_id"]
-							: tool.name === "revise_intent"
-								? ["task_id", "next_intent"]
-								: ["task_id"],
+				: tool.name === "resolve_finding"
+					? ["task_id", "finding_id"]
+					: tool.name === "refute_finding"
+						? ["task_id", "finding_id", "attestation_id"]
+						: tool.name === "revise_intent"
+							? ["task_id", "next_intent"]
+							: ["task_id"],
 		},
 		annotations: tool.privileged ? privilegedAnnotations() : { readOnlyHint: tool.name === "status" },
 	}));
@@ -150,12 +174,38 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 				};
 				const laneOffers = parseLaneOffers(args.lane_offers);
 				// A lane_offers-only call resumes the recorded lane batch; refused before any gate otherwise.
-				const maxParallel = resolveLaneParallel(options.cwd ?? process.cwd(), initiativeSlug, parseMaxParallel(args.max_parallel), laneOffers);
+				const laneInstruction = parseLaneInstruction(args.lane_instruction);
+				const laneRevision = parseLaneRevision(args.lane_revision);
+				const maxParallel = resolveLaneParallel(options.cwd ?? process.cwd(), initiativeSlug, parseMaxParallel(args.max_parallel), laneOffers, laneInstruction ?? laneRevision);
+				const finalVerification = parseFinalVerification(args.final_verification);
 				return runtime.startUnattendedBatch(initiativeSlug, toolMeta, {
 					...(maxParallel !== undefined ? { max_parallel: maxParallel } : {}),
 					...(laneOffers !== undefined ? { lane_offers: laneOffers } : {}),
+					...(finalVerification !== undefined ? { final_verification: finalVerification } : {}),
+					...(laneInstruction !== undefined ? { lane_instruction: laneInstruction } : {}),
+					...(laneRevision !== undefined ? { lane_revision: laneRevision } : {}),
 				});
 			}
+			if (name === "retire_stale_batch") {
+				const initiativeSlug = String(args.initiative_slug ?? "");
+				if (!initiativeSlug) throw new Error("initiative_slug is required");
+				if ("native_decision" in args) throw new Error("native_decision cannot be supplied in tool arguments");
+				if (!negotiatedVersion) throw new NativeAuthorityError("unsupported_host", "Claude Code version is unavailable");
+				if (!negotiatedInteractive) {
+					throw new NativeAuthorityError("unsupported_host", "interactive MCP elicitation is unavailable");
+				}
+				const probe = probeHost(options.env ?? process.env, process.platform, negotiatedVersion);
+				if (!probe.ok) throw new NativeAuthorityError("unsupported_host", probe.reason);
+				const toolMeta: ToolMeta = {
+					sessionId: meta.sessionId ?? connectionId,
+					toolCallId: meta.toolCallId ?? `call-${name}`,
+					taskId: initiativeSlug,
+					initiativeSlug,
+					interactive: meta.interactive ?? options.interactive ?? negotiatedInteractive,
+					signal: meta.signal,
+				};
+				return runtime.retireStaleBatch(initiativeSlug, toolMeta);
+			}
 			const taskId = String(args.task_id ?? "");
 			if (!taskId) throw new Error("task_id is required");
 			if ("native_decision" in args) throw new Error("native_decision cannot be supplied in tool arguments");
@@ -183,8 +233,8 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 			if (name === "enroll") return runtime.enroll(taskId, toolMeta);
 			if (name === "advance_assurance") return runtime.advance(taskId, toolMeta.signal, toolMeta);
 			if (name === "submit_review") {
-				if (!Object.hasOwn(args, "verdict")) throw new Error("verdict is required");
-				return runtime.submitReview(taskId, args.verdict, toolMeta);
+				// ADR 0017: an absent verdict is the receipt-bound submission.
+				return runtime.submitReview(taskId, Object.hasOwn(args, "verdict") ? args.verdict : undefined, toolMeta);
 			}
 			if (name === "revise_intent") {
 				if (!Object.hasOwn(args, "next_intent")) throw new Error("next_intent is required");
@@ -381,6 +431,34 @@ async function writeReply(output: Writable, reply: JsonRpc): Promise<void> {
 }
 
 export function elicitationParams(input: NativeConfirmationInput) {
+	if (input.operation === "retire_stale_batch") {
+		const d = input.batchDisposition;
+		const details = [
+			`Operation: retire_stale_batch`,
+			`Initiative: ${input.initiativeSlug}`,
+			d ? `Batch: ${d.batch_id}` : null,
+			d ? `Batch state: ${d.batch_state}` : null,
+			d ? `Batch branch: ${d.batch_branch}` : null,
+			d ? `Plan digest: ${d.plan_digest}` : null,
+			d ? `Recorded child commits: ${d.recorded_commits}` : null,
+			d
+				? `Children (${d.children.length}):\n${d.children
+						.map(
+							(child) =>
+								`  - ${child.task_id} (${child.slice_id}) [state: ${child.state}]${child.commit ? ` [commit: ${child.commit}]` : " [no commit]"}${child.lane_branch ? ` [lane: ${child.lane_branch}]` : ""}`,
+						)
+						.join("\n")}`
+				: null,
+			"Retiring writes this record to the terminal superseded state. Child states, recorded commits and the batch branch are preserved as evidence; nothing is deleted and no batch trailer or approval is manufactured.",
+			"A child without a commit was never executed by this batch: it carries no delivery evidence, and the retired authorization is never reused for a revised plan.",
+			"After retiring, run each remaining child with imm-run under its own authorization, or start a new batch for this Initiative.",
+		].filter(Boolean);
+		return {
+			mode: "form",
+			message: `Retire this stale batch record for ${input.initiativeSlug}?\n\n${details.join("\n")}`,
+			requestedSchema: { type: "object", properties: {} },
+		};
+	}
 	if (input.operation === "start_unattended_batch") {
 		const b = input.batchDetails;
 		const details = [
@@ -394,11 +472,25 @@ export function elicitationParams(input: NativeConfirmationInput) {
 			b?.lane_mode ? `Lane mode: max_parallel=${b.lane_mode.max_parallel}` : null,
 			b?.lane_mode ? `Parallel groups (${b.lane_mode.parallel_groups.length}):\n${b.lane_mode.parallel_groups.map((group) => `  - ${group.join(", ")}`).join("\n")}` : null,
 			b?.lane_mode && b.lane_mode.serialized.length > 0 ? `Serialized by overlapping scope (${b.lane_mode.serialized.length}):\n${b.lane_mode.serialized.map((c) => `  - ${c.task_id} after ${c.overlaps_with.join(", ")}`).join("\n")}` : null,
+			b?.lane_mode?.final_verification ? `Final verification: ${b.lane_mode.final_verification.join("; ")}` : null,
+			b?.lane_mode?.offer_revision_delegation ? REVISION_DELEGATION_TEXT : null,
 		].filter(Boolean);
 		return {
 			mode: "form",
 			message: `Authorize this unattended batch run for ${input.initiativeSlug}?\n\n${details.join("\n")}`,
-			requestedSchema: { type: "object", properties: {} },
+			requestedSchema: b?.lane_mode?.offer_revision_delegation
+				? {
+						type: "object",
+						properties: {
+							delegate_in_lane_revisions: {
+								type: "boolean",
+								title: "Delegate in-envelope Lane Intent revisions to the batch coordinator",
+								description: REVISION_DELEGATION_TEXT,
+								default: false,
+							},
+						},
+					}
+				: { type: "object", properties: {} },
 		};
 	}
 	const details = [
@@ -476,13 +568,19 @@ export async function serveStdio(options: {
 			if (action !== "accept" && action !== "decline" && action !== "cancel") {
 				throw new NativeAuthorityError("correlation_missing", "MCP elicitation returned an invalid action");
 			}
+			let delegateRevisions = false;
 			if (action === "accept") {
 				const content = (result as { content?: unknown }).content;
-				if (typeof content !== "object" || content === null || Array.isArray(content) || Object.keys(content).length !== 0) {
+				const offered = input.operation === "start_unattended_batch" && input.batchDetails?.lane_mode?.offer_revision_delegation === true;
+				const keys = typeof content === "object" && content !== null && !Array.isArray(content) ? Object.keys(content) : null;
+				const valid = keys !== null && (keys.length === 0 ||
+					(offered && keys.length === 1 && keys[0] === "delegate_in_lane_revisions" && typeof (content as Record<string, unknown>).delegate_in_lane_revisions === "boolean"));
+				if (!valid) {
 					throw new NativeAuthorityError("correlation_missing", "MCP elicitation accept content did not match the requested schema");
 				}
+				delegateRevisions = offered && (content as Record<string, unknown>).delegate_in_lane_revisions === true;
 			}
-			return { decision: action, requestId };
+			return { decision: action, requestId, ...(delegateRevisions ? { delegateRevisions: true } : {}) };
 		} finally {
 			pending.delete(requestId);
 			if (abortListener) input.signal?.removeEventListener("abort", abortListener);
@@ -635,7 +733,20 @@ async function runHook(): Promise<void> {
 	const lines: string[] = [];
 	const rl = createInterface({ input: stdin });
 	for await (const line of rl) lines.push(line);
-	const event = parseHookStdin(lines.join("\n"));
+	const raw = lines.join("\n");
+	let payload: Record<string, unknown> | null = null;
+	try { payload = JSON.parse(raw) as Record<string, unknown>; } catch { payload = null; }
+	if (payload?.hook_event_name === "PreToolUse") {
+		const decision = laneGuardHookOutput(payload);
+		if (decision) process.stdout.write(`${decision}\n`);
+		return;
+	}
+	if (payload?.hook_event_name === "UserPromptSubmit") {
+		const notice = await activeTaskHookOutput(payload);
+		if (notice) process.stdout.write(`${notice}\n`);
+		return;
+	}
+	const event = parseHookStdin(raw);
 	if (!event) return;
 	new FileHookEventLog().append(event);
 }

package/plugins/immune-brain/runtime/commands/kernel.ts

@@ -8,6 +8,7 @@ import {
 } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
+import { projectScopeOverlap } from "../unattended/batch_schedule";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import {
@@ -858,6 +859,57 @@ function runIntentAuthor(args: string[], root: string): KernelExecution {
  * TaskRecord, claim, Ledger, Git index, or session write. Returns a stable
  * bounded projection.
  */
+/**
+ * Read-only: compare the `scope_hint` of two or more TaskIntents of one
+ * Initiative and report every overlapping entry pair plus the start waves the
+ * Batch Plan would use. Optional `--blocked-by a=b,c` edges order the waves the
+ * way the Initiative's dependencies do. Writes nothing.
+ */
+function runIntentOverlap(args: string[], root: string): KernelExecution {
+	const usage = "Run imm-kernel intent overlap <path> <path>... [--blocked-by <task-id>=<task-id>,...] --json.";
+	const reject = (message: string): KernelExecution => ({
+		result: errorResult("invalid_command", message, 2),
+		journal: journalFor("intent", null, "rejected", "invalid_command", null, usage),
+	});
+	const paths: string[] = [];
+	const blockedBy = new Map<string, string[]>();
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index]!;
+		if (arg === "--json") continue;
+		if (arg === "--blocked-by") {
+			const edge = args[++index] ?? "";
+			const match = /^([A-Za-z0-9][A-Za-z0-9._-]*)=([A-Za-z0-9._,-]+)$/.exec(edge);
+			if (!match) return reject(`invalid --blocked-by edge: ${edge}`);
+			blockedBy.set(match[1]!, match[2]!.split(",").filter(Boolean));
+			continue;
+		}
+		if (arg.startsWith("-")) return reject(`unsupported intent overlap option: ${arg}`);
+		paths.push(arg);
+	}
+	if (paths.length < 2) return reject("imm-kernel intent overlap requires at least two paths");
+	const children: Array<{ task_id: string; blocked_by: string[]; scope_hint: string[] }> = [];
+	for (const path of paths) {
+		let intent: { task_id?: unknown; scope_hint?: unknown };
+		try {
+			intent = JSON.parse(readFileSync(resolve(root, path), "utf8"));
+		} catch (error) {
+			return { result: errorResult("source_invalid", `cannot read ${path}: ${error instanceof Error ? error.message : String(error)}`, 1), journal: journalFor("intent", null, "rejected", "source_read_failed", null, usage) };
+		}
+		if (typeof intent.task_id !== "string" || !Array.isArray(intent.scope_hint) || intent.scope_hint.some((entry) => typeof entry !== "string"))
+			return { result: errorResult("source_invalid", `${path} has no task_id and string scope_hint`, 1), journal: journalFor("intent", null, "rejected", "source_invalid", null, usage) };
+		children.push({ task_id: intent.task_id, blocked_by: [], scope_hint: intent.scope_hint as string[] });
+	}
+	const known = new Set(children.map((child) => child.task_id));
+	for (const child of children) child.blocked_by = (blockedBy.get(child.task_id) ?? []).filter((id) => known.has(id));
+	let report: ReturnType<typeof projectScopeOverlap>;
+	try {
+		report = projectScopeOverlap(children);
+	} catch (error) {
+		return reject(error instanceof Error ? error.message : String(error));
+	}
+	return { result: jsonResult(report, 0), journal: journalFor("intent", null, "ok", "command_ok", null, null) };
+}
+
 function runIntentValidate(args: string[], root: string): KernelExecution {
 	const nonFlags = args.filter((arg) => !arg.startsWith("-"));
 	if (nonFlags.length !== 1)
@@ -1173,10 +1225,11 @@ function executeKernelCommand(args: string[], root: string): KernelExecution {
 		const sub = args[1] ?? "";
 		if (sub === "author") return runIntentAuthor(args.slice(2), root);
 		if (sub === "validate") return runIntentValidate(args.slice(2), root);
+		if (sub === "overlap") return runIntentOverlap(args.slice(2), root);
 		return {
 			result: errorResult(
 				"invalid_command",
-				"usage: imm-kernel intent author <path> --stdin --json | validate <path> --json",
+				"usage: imm-kernel intent author <path> --stdin --json | validate <path> --json | overlap <path> <path>... [--blocked-by <task-id>=<task-id>,...] --json",
 				2,
 			),
 			journal: journalFor(