immune-brain 5.1.1 → 5.1.2

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

@@ -0,0 +1,75 @@
+// The contract identifiers one runtime reads and writes in a worktree's
+// Authority Store. A lane-mode batch reads every Lane's Kernel state with the
+// coordinator's own runtime, so the coordinator and the runtime a Lane
+// Executor loads must agree on these identifiers; a plugin version number
+// proves nothing (two different builds can carry the same one).
+//
+// `runtime_contracts.json` is the same set as data, shipped next to this
+// module, so a coordinator can read another runtime's identifiers without
+// executing its code. A test keeps the two in step.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { TASK_TOMBSTONE_CONTRACT } from "./backend_claim";
+import { KERNEL_STORE_SCHEMA_VERSION } from "./storage_paths";
+import { TASK_RECORD_CONTRACT_V4 } from "./types";
+
+export const RUNTIME_CONTRACTS_MANIFEST = "runtime_contracts.json";
+
+export interface RuntimeContracts {
+	contract: "immune_brain/runtime_contracts/v1";
+	task_record: string;
+	task_tombstone: string;
+	assurance_projection: string;
+	kernel_store_schema: number;
+}
+
+/** The identifiers this running runtime supports. */
+export const RUNTIME_CONTRACTS: RuntimeContracts = {
+	contract: "immune_brain/runtime_contracts/v1",
+	task_record: TASK_RECORD_CONTRACT_V4,
+	task_tombstone: TASK_TOMBSTONE_CONTRACT,
+	assurance_projection: "assurance_kernel/assurance_projection/v1",
+	kernel_store_schema: KERNEL_STORE_SCHEMA_VERSION,
+};
+
+const KEYS = ["task_record", "task_tombstone", "assurance_projection", "kernel_store_schema"] as const;
+
+/** Where this running runtime's code was loaded from, for a refusal that names both sides. */
+export function runningRuntimeSource(): string {
+	try {
+		return dirname(fileURLToPath(import.meta.url));
+	} catch {
+		return "unknown";
+	}
+}
+
+/**
+ * Read another runtime's identifiers from its manifest. `runtimeDir` is either
+ * the `runtime/kernel` directory or a plugin root that contains one. Null when
+ * no manifest exists there; a malformed manifest throws.
+ */
+export function readRuntimeContracts(runtimeDir: string): { contracts: RuntimeContracts; path: string } | null {
+	const candidates = [
+		join(runtimeDir, RUNTIME_CONTRACTS_MANIFEST),
+		join(runtimeDir, "kernel", RUNTIME_CONTRACTS_MANIFEST),
+		join(runtimeDir, "runtime", "kernel", RUNTIME_CONTRACTS_MANIFEST),
+		join(runtimeDir, "plugins", "immune-brain", "runtime", "kernel", RUNTIME_CONTRACTS_MANIFEST),
+	];
+	const path = candidates.find((candidate) => existsSync(candidate));
+	if (!path) return null;
+	const raw = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+	if (raw.contract !== "immune_brain/runtime_contracts/v1")
+		throw new Error(`${path} is not an immune_brain/runtime_contracts/v1 manifest`);
+	for (const key of KEYS) {
+		const value = raw[key];
+		if (key === "kernel_store_schema" ? !Number.isSafeInteger(value) : typeof value !== "string" || !value)
+			throw new Error(`${path} has an invalid ${key}`);
+	}
+	return { contracts: raw as unknown as RuntimeContracts, path: resolve(path) };
+}
+
+/** The identifiers on which two runtimes disagree; empty when they can read each other's state. */
+export function runtimeContractDifferences(a: RuntimeContracts, b: RuntimeContracts): string[] {
+	return KEYS.filter((key) => a[key] !== b[key]).map((key) => `${key}: ${String(a[key])} != ${String(b[key])}`);
+}

package/plugins/immune-brain/runtime/plugin_version.ts

@@ -1,2 +1,2 @@
 // Generated by scripts/plugin_versioning.ts from the root package.json.
-export const PLUGIN_VERSION = "5.1.1" as const;
+export const PLUGIN_VERSION = "5.1.2" as const;

package/plugins/immune-brain/runtime/prompts/code-review.md

@@ -34,6 +34,13 @@ about the fix's scope, not a new bug. A trigger the accepted contract explicitly
 excludes is reported as an advisory note against that boundary, never as blocking
 rework.
 
+A defect that lies inside the TaskIntent goal and `scope_hint` is a blocking
+finding even when no acceptance assertion names its exact case word for word:
+cite the acceptance whose principle it violates as `acceptance_id` and
+`violated.ref`. Ask for the fix and a test that pins the case, never for the case
+to be written into the acceptance text; a missing literal clause is not itself a
+finding and does not call for an Intent revision.
+
 ## Invariant and Evidence Coverage
 
 Judge whether the change actually closes the invariant its acceptance names,
@@ -53,6 +60,14 @@ 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.
 
+When the Spec referenced by an acceptance maps an `automated` user scenario to
+it, check that the delivered tests at that acceptance's agreed seam assert the
+scenario's `Then`: a scenario whose observable result is asserted nowhere is a
+finding carrying `violated.kind` of `acceptance` with `ref` the acceptance id.
+A `manual` scenario, and an acceptance with no mapped scenario, produce no such
+finding. This adds no finding kind and no verdict branch: it is the same
+`acceptance` finding the seam rule above already defines.
+
 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

package/plugins/immune-brain/runtime/prompts/executor.md

@@ -54,6 +54,13 @@ Record missing evidence as blocked and repair it before handoff. The Loop owns
 verdict submission, finding disposition and the second-rework generalize-or-refute
 rule.
 
+A finding whose defect lies inside the TaskIntent goal and `scope_hint` is
+ordinary rework even when no acceptance names its exact case: fix the code and
+add the test that pins the case. Do not propose an Intent revision for it, and
+never append a single input case to an acceptance assertion to close a finding;
+acceptance states principles, tests enumerate cases. Route to `imm-planner` only
+when the goal, the scope, or a user-visible commitment must change.
+
 ## Code Quality Guard
 
 Before handoff, check the implementation for real implementation rather than

package/plugins/immune-brain/runtime/unattended/batch_delegation.ts

@@ -0,0 +1,160 @@
+// Delegated in-Lane Intent revision (ADR 0018). A lane batch whose literal-user
+// confirmation granted `revision_delegation` lets the coordinator approve a
+// Lane child's breaking Intent revision that stays inside the child's TaskIntent
+// as authorized for the batch. The approval is the ordinary Kernel
+// `approve_breaking_intent_revision`, applied in the Lane's own Authority Store
+// with user authority whose actor and confirmation reference name the batch, so
+// the audit history tells it apart from an approval by the user in person.
+// Out-of-bounds revisions are refused here and stay with the user's own gate.
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { writeFileSync } from "node:fs";
+import { projectAssurance } from "../kernel/assurance_projection";
+import { createMutationAuthorityRegistry, digestOfAction, type CapabilityBindingV2 } from "../kernel/authority_port";
+import { capabilityActionFor, createCanaryApplication } from "../kernel/canary_application";
+import { canonicalIntentHash, classifyIntentRevision, parseTaskIntentV1, readTaskIntent } from "../kernel/intent";
+import { boundSpecPath } from "../kernel/spec_binding";
+import { readTaskRecordRaw, recoverKernelStoreFollowUps } from "../kernel/storage";
+import type { TaskIntentV1 } from "../kernel/types";
+import { stagePlanningArtifactTransition } from "../assurance/verdict_authority";
+import { captureStagedIntent, restoreStagedIntent } from "../staged_intent";
+import { taskDeliveryIdentity } from "../workspace_scope";
+
+/** The grant and its bounds, stated in the gate that grants it (both Hosts). */
+export const REVISION_DELEGATION_TEXT =
+	"Optional, off by default: also let the batch coordinator approve a Lane child's breaking Intent revisions that stay inside that child's authorized TaskIntent (acceptance changes, a narrower scope_hint). Widening scope, changing risk, goal or the bound Spec still needs your own confirmation. The grant ends with this batch.";
+
+/** The actor every delegated approval records; never the literal user. */
+export const DELEGATED_ACTOR_ID = "batch-coordinator";
+
+export interface RevisionDelegationGrant {
+	/** The confirmation that granted it; a fresh confirmation replaces it. */
+	confirmation_time: string;
+}
+
+export interface DelegatedRevisionRecord {
+	at: string;
+	task_id: string;
+	from_revision: number;
+	to_revision: number;
+	intent_content_hash: string;
+	confirmation_ref: string;
+}
+
+export interface LaneRevisionRequest {
+	task_id: string;
+	next_intent: TaskIntentV1;
+}
+
+/** The confirmation reference that traces a delegated approval to its batch authorization. */
+export function delegatedConfirmationRef(batchId: string, grant: RevisionDelegationGrant): string {
+	return `delegated-batch:${batchId}@${grant.confirmation_time}`;
+}
+
+/** Untrusted tool input: shape only; the bounds are decided against Kernel facts. */
+export function parseLaneRevision(value: unknown): LaneRevisionRequest | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "object" || Array.isArray(value)) throw new Error("invalid lane_revision: expected an object");
+	const { task_id: taskId, next_intent: nextIntent, ...rest } = value as Record<string, unknown>;
+	if (Object.keys(rest).length > 0) throw new Error("invalid lane_revision: unknown field");
+	if (typeof taskId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(taskId))
+		throw new Error("invalid lane_revision: task_id is not a valid task id");
+	const intent = parseTaskIntentV1(nextIntent);
+	if (intent.task_id !== taskId) throw new Error("invalid lane_revision: next_intent belongs to another task");
+	return { task_id: taskId, next_intent: intent };
+}
+
+/**
+ * Whether the delegation covers this revision. `authorized` is the child's
+ * TaskIntent as the batch authorized it; `current` is the Lane's enrolled one.
+ * Null means covered.
+ */
+export function delegatedRevisionRefusal(authorized: TaskIntentV1, current: TaskIntentV1, next: TaskIntentV1): string | null {
+	if (classifyIntentRevision(current, next) !== "breaking") return "only a breaking revision needs this approval; apply a compatible one with revise_intent";
+	if (next.revision <= current.revision) return "the revision number must increase";
+	if (next.goal !== authorized.goal || next.owner !== authorized.owner || next.task_id !== authorized.task_id)
+		return "goal, owner and task identity are outside the delegation";
+	if (next.risk !== authorized.risk || next.risk !== current.risk) return "a risk change is outside the delegation";
+	if ((boundSpecPath(next) ?? null) !== (boundSpecPath(authorized) ?? null)) return "a change of the bound Spec is outside the delegation";
+	const allowed = new Set(authorized.scope_hint);
+	const widened = next.scope_hint.filter((entry) => !allowed.has(entry));
+	if (widened.length > 0) return `widening scope_hint is outside the delegation: ${widened.join(", ")}`;
+	return null;
+}
+
+/**
+ * Apply one delegated breaking revision in the Lane, exactly as a Host applies
+ * an approved one: write and stage the next sidecar, re-read the projection,
+ * issue a user capability bound to that snapshot, execute, and stage the
+ * planning transition. The prior sidecar bytes and index entry come back on any
+ * failure before commit.
+ */
+export function applyDelegatedIntentRevision(input: {
+	lane_root: string;
+	task_id: string;
+	next_intent: TaskIntentV1;
+	confirmation_ref: string;
+	now: string;
+}): Promise<{ from_revision: number; to_revision: number; intent_content_hash: string }> {
+	return (async () => {
+		const { lane_root: root, task_id: taskId, next_intent: nextIntent, now } = input;
+		recoverKernelStoreFollowUps(root, taskId);
+		const prior = readTaskIntent(root, taskId, readTaskRecordRaw(root, taskId).record?.intent_ref.path);
+		const before = await projectAssurance(root, taskId, taskDeliveryIdentity);
+		if (before.error || before.claim?.task_id !== taskId || before.projection.lifecycle !== "active")
+			throw new Error(`the Lane does not hold an active run of ${taskId}`);
+		const nextHash = canonicalIntentHash(nextIntent);
+		const nextRef = { path: `docs/plans/${taskId}.intent.json`, content_hash: nextHash };
+		const snapshot = captureStagedIntent(root, prior.intent_ref.path);
+		try {
+			writeFileSync(join(root, prior.intent_ref.path), `${JSON.stringify(nextIntent, null, 2)}\n`);
+			execFileSync("git", ["add", "--", prior.intent_ref.path], { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+			const prepared = await projectAssurance(root, taskId, taskDeliveryIdentity);
+			if (prepared.error || prepared.projection.record_revision !== before.projection.record_revision)
+				throw new Error("the Lane's TaskRecord changed while the delegated revision was prepared");
+			const registry = createMutationAuthorityRegistry();
+			const action = capabilityActionFor({
+				op: "approve_breaking_intent_revision",
+				task_id: taskId,
+				at: now,
+				actor_id: DELEGATED_ACTOR_ID,
+				next_intent: nextIntent,
+				next_intent_ref: nextRef,
+			});
+			const binding: CapabilityBindingV2 = {
+				authority_kind: "user",
+				task_id: taskId,
+				...(prepared.projection.run_id ? { run_id: prepared.projection.run_id } : {}),
+				action_digest: digestOfAction(action),
+				expected_record_hash: prepared.projection.record_revision,
+				intent_revision: nextIntent.revision,
+				intent_content_hash: nextHash,
+				diff_hash: prepared.projection.diff_hash,
+				actor_id: DELEGATED_ACTOR_ID,
+				confirmation_ref: input.confirmation_ref,
+				findings_digest: null,
+			};
+			const capability = registry.issue(binding);
+			const result = createCanaryApplication(registry).execute({
+				root,
+				task_id: taskId,
+				operation: {
+					op: "approve_breaking_intent_revision",
+					capability,
+					actor_id: DELEGATED_ACTOR_ID,
+					next_intent: nextIntent,
+					next_intent_ref: nextRef,
+				} as never,
+				prior_intent_token: prior.token,
+				diffProvider: taskDeliveryIdentity,
+				now,
+			});
+			stagePlanningArtifactTransition(root, result.record);
+			return { from_revision: prior.intent.revision, to_revision: nextIntent.revision, intent_content_hash: nextHash };
+		} catch (error) {
+			const current = readTaskRecordRaw(root, taskId);
+			if (current.record?.intent_snapshot.revision === prior.intent.revision) restoreStagedIntent(root, snapshot);
+			throw error;
+		}
+	})();
+}

package/plugins/immune-brain/runtime/unattended/batch_final_verification.ts

@@ -0,0 +1,72 @@
+// Full verification of the batch branch once every child is integrated. The
+// commands are the project's own convention, resolved by the Parent from its
+// instruction files and recorded on the batch record when the batch starts, so
+// the completing tick runs exactly what the literal user saw at confirmation.
+// A failure marks the completion report as not passed; integrated commits are
+// never rolled back. Only exit status and timing are recorded, never output.
+import { spawn, spawnSync } from "node:child_process";
+
+export const MAX_FINAL_VERIFICATION_COMMANDS = 8;
+const MAX_COMMAND_LENGTH = 512;
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+
+export interface FinalVerificationResult {
+	command: string;
+	exit_code: number | null;
+	signal: string | null;
+	passed: boolean;
+	duration_ms: number;
+}
+
+export interface FinalVerificationReport {
+	passed: boolean;
+	head: string | null;
+	results: FinalVerificationResult[];
+}
+
+/** Untrusted tool input: a short list of plain commands, split on whitespace and never run through a shell. */
+export function parseFinalVerification(value: unknown): string[] | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (!Array.isArray(value) || value.length === 0 || value.length > MAX_FINAL_VERIFICATION_COMMANDS)
+		throw new Error(`invalid final_verification: expected 1 to ${MAX_FINAL_VERIFICATION_COMMANDS} commands`);
+	return value.map((command) => {
+		if (typeof command !== "string" || !command.trim() || command.length > MAX_COMMAND_LENGTH || /[\0\n\r]/.test(command))
+			throw new Error("invalid final_verification: each command must be one non-empty line");
+		if (/[|&;<>`$(){}"'\\]/.test(command))
+			throw new Error("invalid final_verification: commands run without a shell and are split on spaces, so shell syntax and quoting are not allowed");
+		return command.trim().replace(/\s+/g, " ");
+	});
+}
+
+/** One command, asynchronously, so a long suite never blocks the Host's event loop. */
+function runOne(root: string, command: string, timeoutMs: number): Promise<FinalVerificationResult> {
+	const [executable, ...argv] = command.split(" ");
+	const started = Date.now();
+	return new Promise((resolve) => {
+		let settled = false;
+		const finish = (exitCode: number | null, signal: string | null) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve({ command, exit_code: exitCode, signal, passed: exitCode === 0, duration_ms: Date.now() - started });
+		};
+		const child = spawn(executable!, argv, { cwd: root, stdio: "ignore", env: process.env });
+		const timer = setTimeout(() => {
+			child.kill("SIGKILL");
+			finish(null, "timeout");
+		}, timeoutMs);
+		child.once("error", (error) => finish(null, String((error as NodeJS.ErrnoException).code ?? "spawn_failed")));
+		child.once("close", (code, signal) => finish(code, signal));
+	});
+}
+
+export async function runFinalVerification(
+	root: string,
+	commands: readonly string[],
+	options: { timeoutMs?: number } = {},
+): Promise<FinalVerificationReport> {
+	const head = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], { encoding: "utf8" });
+	const results: FinalVerificationResult[] = [];
+	for (const command of commands) results.push(await runOne(root, command, options.timeoutMs ?? DEFAULT_TIMEOUT_MS));
+	return { passed: results.every((result) => result.passed), head: head.status === 0 ? head.stdout.trim() : null, results };
+}