immune-brain 5.1.0 → 5.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "description": "Immune-Brain agent skill system",
   "publishConfig": {
     "access": "public",

package/plugins/immune-brain/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "description": "Immune-Brain Claude Code Host: native Enrollment, QA, Review, and Kernel settlement.",
   "author": {
     "name": "Immune-Brain Team"

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

@@ -371,8 +371,12 @@ export default function (
 		if (ctx.mode !== "tui") return;
 		await refreshTaskRail(ctx);
 	});
-	pi.on("tool_call", (event: { toolName?: string; input?: unknown }, ctx?: ExtensionContext) => {
+	pi.on("tool_call", (event: { toolName?: string; input?: unknown; toolCallId?: string }, ctx?: ExtensionContext) => {
 		if (ctx) railContext = ctx;
+		if (event.toolName === "Agent") {
+			// ADR 0017: correlate a reserved reviewer dispatch to its reservation.
+			progression.piReviewHost.observeReviewDispatch(event.input as { prompt?: unknown; subagent_type?: unknown } | undefined, event.toolCallId);
+		}
 		if (event.toolName === "imm_canary_enrollment" && ctx) {
 			const input = event.input as { task_id?: string } | undefined;
 			if (input?.task_id) presentTaskRail(ctx, {
@@ -385,7 +389,14 @@ export default function (
 	});
 	pi.on("tool_result", (event: unknown, ctx?: ExtensionContext) => {
 		if (ctx) railContext = ctx;
-		const result = event as { toolName?: string; details?: Record<string, unknown> };
+		const result = event as { toolName?: string; details?: Record<string, unknown>; toolCallId?: string; content?: Array<{ type?: string; text?: string }> };
+		if (result.toolName === "Agent" && result.toolCallId) {
+			// ADR 0017: record the reviewer's own result bytes for receipt-bound submission.
+			const text = Array.isArray(result.content)
+				? result.content.filter((part) => typeof part?.text === "string").map((part) => part.text as string).join("\n")
+				: "";
+			progression.piReviewHost.observeReviewResult(result.toolCallId, text);
+		}
 		if (result.toolName === "imm_canary_enrollment" && ctx) {
 			const taskId = typeof result.details?.task_id === "string" ? result.details.task_id : undefined;
 			if (taskId) presentTaskRailResult(ctx, taskId, result.details);
@@ -406,7 +417,7 @@ export default function (
 		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 foreground Agent from agent_params once, then pass its structured verdict to submit_review.",
+			"When advance_assurance returns review_ready, invoke the foreground Agent from agent_params once, then call submit_review: omit the verdict to apply the observed reviewer result, or relay its structured verdict exactly.",
 			"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; the Kernel revalidates and removes only the redundant claim without user interaction.",
 			"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.",
@@ -416,7 +427,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"), verdict: Type.Unknown() }),
+				Type.Object({ op: Type.Literal("submit_review"), verdict: Type.Optional(Type.Unknown()) }),
 				Type.Object({ op: Type.Literal("request_authorization") }),
 				Type.Object({ op: Type.Literal("request_stop") }),
 				Type.Object({ op: Type.Literal("repair_authority_state") }),
@@ -549,7 +560,7 @@ export default function (
 						presentTaskRailResult(ctx, taskId, update.details as Record<string, unknown> | undefined);
 					})
 					: action.op === "submit_review"
-						? await progression.submitReview(taskId, ctx, action.verdict)
+						? await progression.submitMediated(taskId, ctx, action.verdict)
 						: action.op === "approve_breaking_intent_revision"
 							? await authorizeExactOperation(
 								taskId,
@@ -1509,6 +1520,7 @@ async function enrichAssuranceResult(
 function nextActionForAssuranceResult(result: Record<string, unknown>, taskState: AssuranceTaskState): string {
 	const derived = result.recovery as { next_action: string } | undefined;
 	if (derived) return derived.next_action;
+	if (typeof result.recovery_action === "string") return result.recovery_action;
 	const recovery = recoveryActionForAssuranceFailure(
 		"error" in taskState ? taskState.error : result.reason,
 	);

package/plugins/immune-brain/.pi-extension/imm-unattended-batch.ts

@@ -26,6 +26,9 @@ import {
 	authorizeBatch,
 	projectBatchPreflight,
 } from "../runtime/unattended/batch_preflight";
+import { retireStaleBatch, type StaleBatchFacts } from "../runtime/unattended/batch_disposition";
+import type { BatchLaneRunReport } from "../runtime/unattended/batch_state";
+
 import {
 	presentTaskRail,
 	renderStructuredCall,
@@ -305,6 +308,69 @@ export async function executePiUnattendedBatch(
 	};
 }
 
+export type PiRetireStaleBatchResult =
+	| { state: "retired"; batch_id: string; report: BatchRunReport | BatchLaneRunReport }
+	| { state: "rejected" | "cancelled" | "blocked"; reason: string; recovery_action: string };
+
+/**
+ * The gate text for one batch disposition. Every fact rendered is the record's
+ * own evidence: what it delivered, what it never executed, and what retiring
+ * does and does not claim. Nothing here is a readiness certificate.
+ */
+function retireConfirmationDetails(facts: StaleBatchFacts): {
+	title: string;
+	summary: string;
+	details: string;
+} {
+	return {
+		title: `Retire Stale Batch: ${facts.initiative_slug}`,
+		summary: `Batch: ${facts.batch_id}\nState: ${facts.batch_state}\nBatch branch: ${facts.branch}\nPlan digest: ${facts.plan_digest}\nRecorded child commits: ${facts.recorded_commits.length}\nConfirmed at: ${facts.confirmation_time}`,
+		details: `Children (${facts.children.length}):\n${facts.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")}\n\nRetiring 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.\n\nA 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.\n\nAfter retiring, run each remaining child with imm-run under its own authorization, or start a new batch for this Initiative.`,
+	};
+}
+
+export async function executePiRetireStaleBatch(options: {
+	root: string;
+	initiativeSlug: string;
+	signal?: AbortSignal;
+	confirmBatch: (details: { title: string; summary: string; details: string; signal?: AbortSignal }) => Promise<"accept" | "decline" | "cancel">;
+}): Promise<PiRetireStaleBatchResult> {
+	const { root, initiativeSlug, signal } = options;
+	const outcome = await retireStaleBatch({
+		root,
+		initiative_slug: initiativeSlug,
+		now: new Date().toISOString(),
+		gate: async (facts) => {
+			const details = retireConfirmationDetails(facts);
+			let decision: "accept" | "decline" | "cancel";
+			try {
+				decision = await options.confirmBatch({ ...details, signal });
+			} catch (err) {
+				if (signal?.aborted) return { kind: "host_rejection", value: batchReason("confirmation_cancelled") };
+				return {
+					kind: "host_rejection",
+					value: batchReason("confirmation_failed", err instanceof Error ? err.message : String(err)),
+				};
+			}
+			if (decision === "cancel" || signal?.aborted)
+				return { kind: "host_rejection", value: batchReason("confirmation_cancelled") };
+			if (decision === "decline")
+				return { kind: "host_rejection", value: batchReason("confirmation_declined") };
+			if (decision !== "accept")
+				return { kind: "host_rejection", value: batchReason("confirmation_no_decision") };
+			return { kind: "confirmed", request_id: randomUUID() };
+		},
+	});
+	if (outcome.outcome === "host_rejection") return outcome.value;
+	if (outcome.outcome === "rejected") return outcome.rejection;
+	return { state: "retired", batch_id: outcome.batch_id, report: outcome.report };
+}
+
 /**
  * Injectable seams for the batch Tool. Production passes nothing and gets the
  * real Initiative reader, Kernel port and Git port; tests drive the registered
@@ -439,4 +505,103 @@ export default function (
 			);
 		},
 	});
+	// The batch disposition: one explicit literal-user decision that closes a
+	// batch the plan moved past, preserving its evidence instead of leaving the
+	// record parked forever or deleting it by hand. Grants no handoff.
+	pi.registerTool({
+		name: "retire_stale_batch",
+		label: "Retire stale batch",
+		description: "Retire an Initiative's parked or drifted batch record to the terminal superseded state after native confirmation.",
+		promptSnippet: "Retire stale batch: invoke once in foreground after the stale batch record is inspected.",
+		promptGuidelines: [
+			"Call only after inspecting the batch record; execute once in the foreground and consume the direct terminal result.",
+			"Do not run this Tool in background, poll for completion, or issue a cancel subcommand.",
+		],
+		parameters: Type.Object({
+			initiative_slug: Type.String({ pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }),
+		}, { additionalProperties: false }),
+		execute: async (
+			_toolCallId: string,
+			params: { initiative_slug: string },
+			signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			ctx: ExtensionContext,
+		) => {
+			const { initiative_slug: initiativeSlug } = params;
+			if (ctx.mode !== "tui") {
+				const refusal = nonInteractiveRefusal();
+				throwToolFailure({
+					tool: "imm_canary_enrollment",
+					task_id: initiativeSlug,
+					operation: "retire_stale_batch",
+					state: "blocked",
+					code: "unsupported_host",
+					message: refusal.reason,
+					next_action: refusal.recovery_action,
+				});
+			}
+
+			const result = await executePiRetireStaleBatch({
+				root: ctx.cwd,
+				initiativeSlug,
+				signal,
+				confirmBatch: async (details) => {
+					presentTaskRail(ctx, {
+						task_id: initiativeSlug,
+						state: "Approval required",
+						result: details.title,
+						next: "Review batch record evidence",
+					});
+					const selected = await requestAuthorityDialog(
+						pi,
+						ctx,
+						{
+							attention_id: randomUUID(),
+						task_id: initiativeSlug,
+							reason: "enrollment",
+							label: details.title,
+						},
+						{
+							title: details.title,
+							summary: details.summary,
+							details: details.details,
+							signal: details.signal,
+							actions: [
+								{ value: "confirm", label: "Retire batch record", description: "Write the terminal superseded state and its report" },
+								{ value: "decline", label: "Keep batch parked", description: "Leave the batch record and its authorization unchanged" },
+								{ value: "cancel", label: "Cancel", description: "Leave repository and authority unchanged" },
+							],
+						},
+					);
+					return mapDialogSelection(selected);
+				},
+			});
+
+			if (result.state !== "retired") {
+				throwToolFailure({
+					tool: "imm_canary_enrollment",
+					task_id: initiativeSlug,
+					operation: "retire_stale_batch",
+					state: result.state === "blocked" ? "blocked" : "failed",
+					code: `batch_${result.state}`,
+					message: result.reason,
+					next_action: result.recovery_action,
+				});
+			}
+			return {
+				content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+				details: result,
+			};
+		},
+		renderCall(args, theme) {
+			const params = args as { initiative_slug?: string };
+			return renderStructuredCall("retire_stale_batch", "retire", params.initiative_slug, theme);
+		},
+		renderResult(result, _options, theme) {
+			return renderStructuredResult(
+				result as Parameters<typeof renderStructuredResult>[0],
+				theme,
+			);
+		},
+	});
 }

package/plugins/immune-brain/.pi-extension/pi-canary-assurance-progression.ts

@@ -46,9 +46,10 @@ export type {
 	ReviewTimingProfile,
 } from "../runtime/assurance/coordinator";
 
-import { AssuranceCoordinator, type AssuranceCoordinatorPorts } from "../runtime/assurance/coordinator";
+import { AssuranceCoordinator, type AssuranceCoordinatorPorts, type HostContext, type AssuranceSubmitReviewResult } from "../runtime/assurance/coordinator";
 import type { AssuranceHostPort, HostReviewReservation, ReviewRequest } from "../runtime/assurance/host_port";
-import { reservedAgentParams } from "./pi-canary-native-review";
+import { submitMediatedReview, type ReviewObservation } from "../runtime/assurance/review_mediation";
+import { reservedAgentParams, promptDigest } from "./pi-canary-native-review";
 
 import type { VerdictAuthority } from "../runtime/assurance/verdict_authority";
 
@@ -57,9 +58,18 @@ export type AssuranceProgressionPorts = Omit<AssuranceCoordinatorPorts, "host">
 	authorityOverrides?: Partial<VerdictAuthority>;
 };
 
+interface RecordedReviewReceipt {
+	taskId: string;
+	promptDigest: string;
+	toolCallId?: string;
+	result?: string;
+	error?: string;
+}
+
 class PiReviewHost implements AssuranceHostPort {
 	readonly host = "pi" as const;
 	private readonly pending = new Set<string>();
+	private readonly receipts = new Map<string, RecordedReviewReceipt>();
 
 	prepareReview(request: ReviewRequest): HostReviewReservation {
 		const params = reservedAgentParams({
@@ -69,17 +79,70 @@ class PiReviewHost implements AssuranceHostPort {
 			max_turns: request.maxTurns,
 		});
 		this.pending.add(request.operationId);
+		this.receipts.set(request.operationId, { taskId: request.taskId, promptDigest: promptDigest(params.prompt) });
 		return { id: request.operationId, dispatch: params };
 	}
 
 	releaseReview(reservation: HostReviewReservation): void {
 		this.pending.delete(reservation.id);
+		this.receipts.delete(reservation.id);
+	}
+
+	/** Extension event seam: correlate one observed `Agent` dispatch to its reservation (ADR 0017). */
+	observeReviewDispatch(input: { prompt?: unknown; subagent_type?: unknown } | undefined, toolCallId: string | undefined): void {
+		if (typeof input?.prompt !== "string") return;
+		for (const record of this.receipts.values()) {
+			if (record.promptDigest !== promptDigest(input.prompt)) continue;
+			if (input.subagent_type !== "Review") {
+				record.error = "the reserved reviewer prompt was dispatched with a different Agent type";
+				return;
+			}
+			if (record.toolCallId !== undefined && record.toolCallId !== toolCallId) {
+				record.error = "the reserved reviewer was dispatched more than once";
+				return;
+			}
+			record.toolCallId = toolCallId;
+			return;
+		}
+	}
+
+	/** Extension event seam: store the observed reviewer result bytes (ADR 0017). */
+	observeReviewResult(toolCallId: string | undefined, bytes: string): void {
+		if (!toolCallId) return;
+		for (const record of this.receipts.values()) {
+			if (record.toolCallId !== toolCallId) continue;
+			if (record.result === undefined) record.result = bytes;
+			else if (record.result !== bytes) record.error = "the reserved reviewer returned conflicting result bytes";
+			return;
+		}
+	}
+
+	inspectReview(taskId: string): ReviewObservation {
+		for (const record of this.receipts.values()) {
+			if (record.taskId !== taskId) continue;
+			if (record.error) return { ok: false, release: false, reason: record.error };
+			if (record.toolCallId === undefined)
+				return { ok: false, release: false, reason: "the reserved foreground Agent was not observed in this session" };
+			if (record.result === undefined)
+				return { ok: false, release: false, reason: "the reserved foreground reviewer has not returned its result yet; wait for it, then call submit_review again" };
+			return { ok: true, receipt: { actorId: "pi-review-agent", result: record.result } };
+		}
+		return { ok: false, release: true, reason: "the reserved foreground Agent was not observed in this session" };
 	}
 }
 
 export class AssuranceProgression extends AssuranceCoordinator {
+	readonly piReviewHost: PiReviewHost;
+
 	constructor(ports: AssuranceProgressionPorts) {
-		(ports as AssuranceCoordinatorPorts).host = new PiReviewHost();
+		const host = new PiReviewHost();
+		(ports as AssuranceCoordinatorPorts).host = host;
 		super(ports as AssuranceCoordinatorPorts, ports.authorityOverrides);
+		this.piReviewHost = host;
+	}
+
+	/** ADR 0017: verdict-source resolution happens here, before the shared submit path. */
+	submitMediated(taskId: string, ctx: HostContext, verdictInput: unknown): Promise<AssuranceSubmitReviewResult> {
+		return submitMediatedReview(this, ctx, taskId, verdictInput, () => this.piReviewHost.inspectReview(taskId));
 	}
 }

package/plugins/immune-brain/agents/immune-brain-reviewer.md

@@ -59,6 +59,16 @@ seam, or a seam silently replaced by a different one, is a finding carrying
 named, its absence is not a finding: candidates written before this rule carries
 no defect for lacking one.
 
+Before pass, enumerate the immutable change set and read each complete per-file
+diff, including deletions. Page bounded reads until every hunk is visible; a
+truncated aggregate output or summary is incomplete coverage. Trace changed
+high-risk behavior through its callers and state owner, and inspect a concrete
+negative case against the embedded acceptance. If immutable evidence remains
+unavailable or incomplete, report the concrete acceptance coverage gap in a
+rework finding with required evidence. `inspected_paths` declares coverage; it
+does not itself prove tool reading. Judge quality by evidence, not elapsed time
+or tool-call count.
+
 A required check that is skipped, that matches zero tests, or whose prerequisite
 is absent does not prove the acceptance; do not accept it as evidence. Full
 suite coverage reported at a coarse pass count is not per-invariant evidence.
@@ -96,5 +106,5 @@ Every rework finding must carry machine-checkable provenance: evidence.trigger (
 
 A pass verdict's approval must carry `inspected_paths`: an array of unique repository-relative path strings listing every path of the reviewed change set (changed_paths for a Git review revision, dirty_files for a bundle), deleted paths included; an empty change set is listed as an empty array. A path may be listed only after its diff was read. A pass that omits any changed path, lists a path outside the change set, or duplicates a path is rejected as a correctable invalid verdict.
 
-A dispatched reviewer is never continued or re-prompted, including through SendMessage. The reserved prompt is dispatched verbatim. A blocked `submit_review` is recovered only through its returned `recovery_action`.
+A dispatched reviewer is never continued or re-prompted, including through SendMessage. The reserved prompt is dispatched verbatim. The host binds this reviewer's final result bytes to the reservation, so a Parent may submit them without transcribing them. A blocked `submit_review` is recovered only through its returned `recovery_action`.