immune-brain 5.2.0 → 5.5.1

package/plugins/immune-brain/.pi-extension/pi-run-continuation.ts

@@ -0,0 +1,161 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { realpathSync } from "node:fs";
+import { projectTaskStatus } from "../runtime/assurance/coordinator";
+import { readTaskRecordRaw } from "../runtime/kernel/storage";
+import type { PhaseEntry } from "../runtime/assurance/phase_entry";
+import { recordParentRepair } from "../runtime/unattended/batch_git";
+import { readAnyBatchRunState } from "../runtime/unattended/batch_state";
+import { bindRun, decideRunContinuation, observeParentRun, parkFailedCriticalGate, releasesRunBinding, scopedSourceDigest,
+	type RunContinuationState, type ReviewContinuationState } from "../runtime/assurance/run_continuation";
+
+type SettleBoundary = {
+	outcome: "completed" | "aborted" | "error";
+	continue: boolean;
+	context: { canContinue: boolean; pendingMessages: unknown[] };
+};
+type ContinuationBoundaryResult = { continue?: boolean; entries?: Array<{ type: "custom_message"; customType: string; display: boolean; content: string }> } | void;
+
+/** Continuation is session memory, never a capability or durable task owner. */
+export function registerPiRunContinuation(pi: ExtensionAPI, ports: {
+	entry(text: string, root: string): PhaseEntry | null;
+}): { selectedParent(root: string, sessionId: string, slug: string): boolean } {
+	let entered = false;
+	let state: RunContinuationState | undefined;
+	let hostFailure: string | undefined;
+	const failedGates = new Set<string>();
+	let reviewRecovery: string | undefined;
+	let review: ReviewContinuationState = "unobserved";
+	let reviewerPrompt: string | undefined;
+	let reviewerCallId: string | undefined;
+	const calls = new Map<string, { name: string; task_id?: string; op?: string; initiative_slug?: string }>();
+	const reset = () => { entered = false; state = undefined; hostFailure = undefined; reviewRecovery = undefined;
+		review = "unobserved"; reviewerPrompt = undefined; reviewerCallId = undefined; calls.clear(); };
+	pi.on("session_start", () => { failedGates.clear(); reset(); });
+	pi.on("session_shutdown", () => { failedGates.clear(); reset(); });
+	pi.on("input", (event, ctx) => {
+		if (event.source === "extension") return;
+		const entry = ports.entry(event.text, ctx.cwd);
+		if (releasesRunBinding(event.text, entry === "plan" ? "planner" : entry)) { reset(); return; }
+		if (entry === "run") { failedGates.clear(); reset(); entered = true; }
+	});
+	pi.on("tool_call", (event) => {
+		const gateInput = event.input as { task_id?: unknown; initiative_slug?: unknown; action?: { op?: unknown } };
+		const gate = `${event.toolName}:${gateInput.task_id ?? gateInput.initiative_slug ?? ""}:${gateInput.action?.op ?? ""}`;
+		if (failedGates.has(gate)) return { block: true, reason: "This native gate failed or was cancelled; enter imm-run explicitly before retrying" };
+		if (!entered) return;
+		if (event.toolName === "imm_canary_enrollment" && state?.binding.kind === "parent" &&
+			state.binding.blocked_native_tasks?.includes(String(event.input.task_id)))
+			return { block: true, reason: "This critical gate is parked; continue independent work or resolve its same-Host recovery and enter imm-run explicitly" };
+		if (event.toolName === "Agent" && reviewerPrompt &&
+			(event.input.subagent_type === "Review" || event.input.prompt === reviewerPrompt)) {
+			if (event.input.prompt !== reviewerPrompt || event.input.subagent_type !== "Review" || event.input.run_in_background !== false)
+				return { block: true, reason: "Kernel Review requires the complete exact agent_params from advance_assurance: preserve prompt bytes, subagent_type Review, and run_in_background false. No reviewer was dispatched." };
+			if (reviewerCallId) { review = "rejected"; return { block: true, reason: "Reserved Reviewer already dispatched; wait for its result and submit the verdict before any new dispatch" }; }
+			reviewerCallId = event.toolCallId; review = "running"; return;
+		}
+		if (!["imm_canary_enrollment", "imm_kernel_canary", "start_unattended_batch"].includes(event.toolName)) return;
+		const input = event.input as { task_id?: unknown; initiative_slug?: unknown; action?: { op?: unknown } };
+		calls.set(event.toolCallId, { name: event.toolName,
+			task_id: typeof input.task_id === "string" ? input.task_id : undefined,
+			initiative_slug: typeof input.initiative_slug === "string" ? input.initiative_slug : undefined,
+			op: typeof input.action?.op === "string" ? input.action.op : undefined });
+	});
+	pi.on("tool_result", async (event, ctx) => {
+		if (entered && event.toolName === "Agent" && event.toolCallId === reviewerCallId) review = "returned";
+		const call = calls.get(event.toolCallId); calls.delete(event.toolCallId);
+		if (!entered || !call) return;
+		if (call.name === "start_unattended_batch") {
+			const result = event.details as { state?: string; batch_id?: string | null; plan_digest?: string; final_verification_commands?: string[] } | undefined;
+			if (!event.isError && result?.state === "native_parent" && typeof result.plan_digest === "string" && call.initiative_slug) {
+				if (!state || state.binding.kind !== "parent") state = bindRun({ kind: "parent", workspace: realpathSync(ctx.cwd),
+					session_id: ctx.sessionManager.getSessionId(), initiative_slug: call.initiative_slug, batch_id: null,
+					plan_digest: result.plan_digest, final_verification: result.final_verification_commands });
+				return;
+			}
+			if (event.isError || result?.state !== "started" || !result.batch_id || !call.initiative_slug) {
+				failedGates.add(`${call.name}:${call.initiative_slug ?? ""}:`);
+				hostFailure = "Batch native operation did not apply; inspect the same-Host recovery"; return;
+			}
+			const record = readAnyBatchRunState(ctx.cwd, result.batch_id);
+			if (!record || record.initiative_slug !== call.initiative_slug) { hostFailure = "Batch result has no matching persisted identity"; return; }
+			if (!state || state.binding.kind !== "parent") state = bindRun({ kind: "parent", workspace: realpathSync(ctx.cwd),
+				session_id: ctx.sessionManager.getSessionId(), initiative_slug: record.initiative_slug, batch_id: record.batch_id, plan_digest: record.plan_digest });
+			return;
+		}
+		if (!call.task_id) return;
+		const details = event.details as { state?: unknown; reason?: unknown; recovery_action?: unknown; next_action?: unknown;
+			agent_params?: { prompt?: unknown } } | undefined;
+		if ((event.isError || ["blocked", "cancelled", "rejected", "failed"].includes(String(details?.state))) &&
+			(call.name === "imm_canary_enrollment" || ["request_authorization", "approve_breaking_intent_revision", "request_stop"].includes(call.op ?? ""))) {
+			failedGates.add(`${call.name}:${call.task_id}:${call.op ?? ""}`);
+			hostFailure = typeof details?.reason === "string" ? details.reason : "Native authority operation failed or was cancelled";
+			if (call.name === "imm_canary_enrollment" && state && await parkFailedCriticalGate(state.binding, call.task_id)) hostFailure = undefined;
+			return;
+		}
+		if (call.op === "advance_assurance" && !event.isError && details?.state === "review_ready") {
+			if (typeof details.agent_params?.prompt === "string" && details.agent_params.prompt !== reviewerPrompt) {
+				reviewerPrompt = details.agent_params.prompt; reviewerCallId = undefined; review = "ready";
+			}
+			reviewRecovery = undefined;
+		}
+		if (call.op === "submit_review") {
+			if (event.isError) {
+				review = "rejected";
+				const action = details?.recovery_action ?? details?.next_action;
+				reviewRecovery = typeof action === "string" ? action : undefined;
+			} else {
+				review = "unobserved"; reviewerPrompt = undefined; reviewerCallId = undefined; reviewRecovery = undefined;
+			}
+		}
+		if (call.name === "imm_canary_enrollment" && !event.isError && details?.state === "completed" && state?.binding.kind === "parent")
+			await recordParentRepair(ctx.cwd, state.binding.batch_id, call.task_id, state.binding.initiative_slug);
+		if (state || event.isError) return;
+		const status = await projectTaskStatus(ctx.cwd, call.task_id);
+		if (status.error || status.claim?.task_id !== call.task_id || status.projection.lifecycle !== "active" || !status.projection.run_id) return;
+		state = bindRun({ kind: "task", workspace: realpathSync(ctx.cwd), session_id: ctx.sessionManager.getSessionId(),
+			task_id: call.task_id, run_id: status.projection.run_id });
+	});
+	// shortcut: optional workspace SDK types predate Pi 1.2; remove this declaration when that peer reaches 1.2 (owner: Immune-Brain).
+	const boundaryApi = pi as ExtensionAPI & { on(event: "agent_before_settle", handler: (event: SettleBoundary, ctx: ExtensionContext) => Promise<ContinuationBoundaryResult>): void };
+	boundaryApi.on("agent_before_settle", async (event, ctx) => {
+		if (!entered || !state) return;
+		if (event.outcome !== "completed" || !event.context.canContinue) { reset(); return; }
+		if (event.continue || event.context.pendingMessages.length) return;
+		try {
+			if (state.binding.kind === "parent") {
+				const decision = decideRunContinuation(state, { ...await observeParentRun(state.binding,
+					ctx.sessionManager.getLeafId() ?? "empty-session", review, reviewRecovery), host_failure: hostFailure });
+				state = decision.state;
+				if (decision.action === "settled" || decision.action === "unbound") { reset(); return; }
+				if (decision.action === "wait") return;
+				if (decision.action === "pause") { reset(); return { entries: [{ type: "custom_message", customType: "immune-brain-run-paused", display: true, content: `Parent paused: ${decision.reason}. ${decision.next_action ?? ""}` }] }; }
+				return { continue: true, entries: [{ type: "custom_message", customType: "immune-brain-run-continuation", display: false,
+					content: `Parent remains incomplete. ${decision.next_action}. Continue the authorized Loop and batch; individual Slice settlement does not complete the Parent.` }] };
+			}
+			const taskId = state.binding.task_id;
+			const status = await projectTaskStatus(ctx.cwd, taskId);
+			const record = await readTaskRecordRaw(ctx.cwd, taskId);
+			if (!record.record && status.projection.lifecycle === "active") throw new Error("bound run has no live TaskRecord");
+			const decision = decideRunContinuation(state, { kind: "task", workspace: realpathSync(ctx.cwd),
+				session_id: ctx.sessionManager.getSessionId(), boundary_id: ctx.sessionManager.getLeafId() ?? "empty-session",
+				status, source_digest: record.record ? scopedSourceDigest(ctx.cwd, record.record.intent_snapshot.scope_hint) : "terminal",
+				review, recovery_action: reviewRecovery, host_failure: hostFailure });
+			state = decision.state;
+			if (decision.action === "settled" || decision.action === "unbound") { reset(); return; }
+			if (decision.action === "wait") return;
+			if (decision.action === "pause") {
+				reset();
+				return { entries: [{ type: "custom_message" as const, customType: "immune-brain-run-paused", display: true,
+					content: `Run paused: ${decision.reason}${decision.next_action ? `. Recovery: ${decision.next_action}` : ""}` }] };
+			}
+			return { continue: true, entries: [{ type: "custom_message" as const, customType: "immune-brain-run-continuation", display: false,
+				content: `Explicit imm-run remains bound to task ${taskId}, run ${state.binding.kind === "task" ? state.binding.run_id : ""}. Kernel settlement is incomplete. ${decision.next_action}. Continue the authorized Loop; report completion only after authoritative settlement.` }] };
+		} catch (error) {
+			reset();
+			return { entries: [{ type: "custom_message" as const, customType: "immune-brain-run-paused", display: true,
+				content: `Run paused because continuation facts could not be verified: ${error instanceof Error ? error.message : String(error)}` }] };
+		}
+	});
+	return { selectedParent: (root, sessionId, slug) => entered && state?.binding.kind === "parent" &&
+		state.binding.workspace === realpathSync(root) && state.binding.session_id === sessionId && state.binding.initiative_slug === slug };
+}

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

@@ -52,6 +52,27 @@ cite the acceptance whose principle it violates as `acceptance_id` and
 to be written into the acceptance text; a missing literal clause is not itself a
 finding and does not call for an Intent revision.
 
+## Trigger and Threat Model
+
+`evidence.trigger` must read "concrete input or state → observable wrong
+result". A finding that cannot name the wrong result is not blocking. Judge
+against the threat model and supported environment declared in the Spec or
+TaskIntent goal: a defect that needs an attacker, input source, repository
+format, encoding, or platform outside that declaration is advisory. When
+nothing is declared, assume inputs come from the repository's own tooling and
+the user's trusted workspace. `security_boundary` means a security, data-loss,
+or authority boundary the change actually crosses.
+
+From Review round 3 the manifest carries `prior_review_commit` and
+`delta_paths`: the paths the latest rework changed. Review that delta and its
+direct interactions. A blocking finding is admitted only when at least one
+`caller_chain` entry names a path in `delta_paths`, or `violated.kind` is
+`security_boundary`; an edge case that already existed in round 1 is advisory
+unless it crosses a security, data-loss, or authority boundary. A verdict that
+blocks outside the delta is rejected for resubmission. When the manifest carries
+`delta_skipped` instead, no delta exists for the round and this rule does not
+apply.
+
 ## Invariant and Evidence Coverage
 
 Judge whether the change actually closes the invariant its acceptance names,
@@ -101,7 +122,7 @@ contract: `contract`, `role`, `task_id`, `snapshot_digest`, `decision` (`pass`
 or `rework`), and for `pass` include `approval` (`kind`, `authority_role`,
 `summary`), for `rework` include `findings` (`id`, `kind`, `acceptance_id`,
 `summary`, `evidence`). Every rework finding's `evidence` must carry
-`trigger` (the concrete inputs or state that reach the defect), a non-empty
+`trigger` (the concrete input or state that reaches the defect and the observable wrong result it produces), a non-empty
 `caller_chain` (ordered repository paths or symbols), and `violated`
 (`kind`: `acceptance` or `security_boundary`, `ref`: the acceptance id or
 boundary name). Do not invent fields, and never send an anchor yourself: the
@@ -110,7 +131,10 @@ violated.ref, caller_chain}`, so an identical claim keeps one stable identity
 across review rounds while a different call chain is a different claim. A
 passing review carries no blocking findings; non-blocking notes may ride along as
 `kind: "advisory"` findings, and every finding, advisory included, needs the
-same machine-checkable evidence. If the
+same machine-checkable evidence. Advisory notes are archived on a pass and never
+become Executor work. A rework carries only `kind: "blocking"` findings, at
+least one: the coordinator rejects a rework with an advisory finding or without
+a blocking one, so submit `pass` with `inspected_paths` when nothing blocks. If the
 checkpoint is `awaiting_user_successor_decision`, stop without dispatch; only
 a literal user may invoke `--approve-successor`.
 

package/plugins/immune-brain/dist/BASELINE.md

@@ -15,6 +15,12 @@
   their own existing grant. An explicit approval already covering the same
   operation, target, and impact — including a valid batch capability — stays
   usable without another gate.
+- A precondition commit is the one commit the runtime makes without a separate
+  grant. When an `imm-run` precondition would fail only because paths are
+  uncommitted, the runtime commits that precondition's committable set, an
+  explicit path list, silently and continues. It runs Git hooks normally and
+  grants no push, publication, history rewrite, or commit of any other path. A
+  model never makes this commit itself and never asks the user to make it.
 - Before a new outbound effect, check the project's existing research channel and
 data scope. A public article, a mock, a documentation example, or a local
 read-only database gives no authority to call an arbitrary provider or send new
@@ -55,11 +61,19 @@ framing does not load that execution guidance.
 
 Ordinary host input stays host-native and does not run natural-language Managed
 routing. A new Managed workflow starts only from explicit `imm-brainstorm`,
-`imm-planner`, or `imm-run` Skill entry.
+`imm-planner`, or `imm-run` Skill entry. For `imm-planner` and `imm-brainstorm`
+the user's request for that planning or clarification, by slash command or in
+natural language, is such an entry; a request that asks for neither stays
+host-native. `imm-run` starts only from a literal-user entry. A model-entered
+Planner or Brainstorm leaves the session's run entry unchanged.
 
 1. **Continue an existing Managed owner explicitly**: an active Assurance
    projection, TaskIntent, TaskRecord, reviewer `follow_up`, or other nonterminal
    Managed owner remains authoritative; the user resumes it with `imm-run`.
+   Once that entry binds this session, ordinary status questions and in-scope
+   clarification retain automatic response continuation. Explicit cancel, planning
+   entry or session replacement releases the binding; Host continuation metadata
+   remains non-authoritative.
 2. **Start explicitly**: the selected Immune-Brain Skill owns its planning or
    coordination work. It creates only requested artifacts and their required
    parent directories. Explicit Planner entry also owns absent routing-policy
@@ -112,6 +126,8 @@ Routine Managed enrollment is the first step of an explicit `imm-run` entry and
 
 For an unborn symbolic Git HEAD, the same Enrollment confirmation discloses an empty root commit. After approval, the Host creates that commit without staging project content or changing the index/worktree, then revalidates ownership and rehearses Enrollment against the new base. Git identity uses existing environment/config values with an explicit automation fallback, never config writes. Decline or pre-initialization cancellation leaves HEAD unborn; if later Enrollment fails or is cancelled, report the remaining commit. Invalid Git refs are errors, not initialization candidates.
 
+Before Enrollment prepares its binding, the Host commits the Enrollment committable set when an untracked TaskIntent would otherwise fail it. The set is the task's own TaskIntent and the Spec its binding names. In-scope changes that already exist are not committed: the Enrollment gate lists them and only the listed paths become task work on confirmation, so a dirty scope is never claimed without that list being shown. The commit is silent, needs no separate confirmation, and the native confirmation binds the HEAD that results. When no precondition fails, no commit is made. Dirty paths outside the set are left as they are and do not block Enrollment. With an unborn HEAD the empty root commit comes first and this commit follows it. A commit Git refuses fails Enrollment with Git's message and is never retried with hooks bypassed; if Enrollment is declined, cancelled or fails afterwards, report the remaining commit.
+
 ## Parallel Read-Only Dispatch
 
 State mutations, step activations, QA decisions, and plan switches remain