immune-brain 2.8.2

package/plugins/immune-brain/.pi-extension/pi-canary-native-review.ts

@@ -0,0 +1,214 @@
+import { createHash } from "node:crypto";
+
+export const STANDARD_AGENT_TOOL = "Agent";
+
+export interface NativeReviewResult {
+	agentId: string;
+	result: string;
+	status: string;
+	durationMs?: number;
+	tokens?: { input: number; output: number; total: number };
+}
+
+const NATIVE_REVIEW_FAILURE_STATUSES = new Set([
+	"failed",
+	"error",
+	"cancelled",
+	"stopped",
+	"terminated",
+]);
+
+export function nativeReviewResultIsFailure(result: NativeReviewResult): boolean {
+	return NATIVE_REVIEW_FAILURE_STATUSES.has(result.status);
+}
+
+export interface ReservedAgentParams {
+	subagent_type: "Review";
+	description: string;
+	prompt: string;
+	inherit_context: false;
+	isolated: true;
+	isolation: "worktree";
+	run_in_background: false;
+	max_turns: number;
+	resume: "";
+	schedule: "";
+}
+
+export interface ToolExecutionEndLike {
+	toolName?: string;
+	toolCallId?: string;
+	args?: unknown;
+	input?: unknown;
+	result?: unknown;
+	content?: unknown;
+	details?: unknown;
+	isError?: boolean;
+}
+
+export interface ToolResultLike extends ToolExecutionEndLike {}
+
+export function reservedAgentDescription(taskId: string, operationId: string): string {
+	return `Review ${shortId(taskId)} ${shortId(operationId)}`;
+}
+
+export function semanticNeighborhoodReviewPrompt(prompt: string): string {
+	return [
+		prompt,
+		`For every neighborhood_files entry, verify git rev-parse HEAD:<path> equals base_oid, then analyze current_content exclusively from the immutable bundle. path_provenance is authoritative: diff marks task changes and neighborhood marks unchanged same-state-machine context selected only from scope_hint.`,
+		`For settlement-class changes, enumerate every terminal, cancellation, timeout, and race path present across dirty_files and neighborhood_files before deciding the verdict; report findings for every affected path. Reference a bundle path at the start of each finding summary (for example, "path/to/file.ts: ...") so verdict v2 can identify neighborhood context without live repository reads.`,
+	].join("\n");
+}
+
+export function reservedAgentParams(input: {
+	taskId: string;
+	operationId: string;
+	prompt: string;
+	max_turns?: number;
+}): ReservedAgentParams {
+	return {
+		subagent_type: "Review",
+		description: reservedAgentDescription(input.taskId, input.operationId),
+		prompt: semanticNeighborhoodReviewPrompt(input.prompt),
+		inherit_context: false,
+		isolated: true,
+		isolation: "worktree",
+		run_in_background: false,
+		max_turns: input.max_turns ?? 16,
+		resume: "",
+		schedule: "",
+	};
+}
+
+export function matchesReservedAgentArgs(
+	args: unknown,
+	params: ReservedAgentParams,
+): boolean {
+	if (!isRecord(args)) return false;
+	const expectedKeys = Object.entries(params)
+		.filter(([, value]) => value !== undefined)
+		.map(([key]) => key);
+	// Host serializes Agent input, may omit falsy inherit_context, and resolves
+	// execution metadata. name/model/thinking are host-owned and not Review
+	// authority identity: strip them, then require the exact reserved field set.
+	const normalizedArgs: Record<string, unknown> = { ...(args as Record<string, unknown>) };
+	delete normalizedArgs["name"];
+	delete normalizedArgs["model"];
+	delete normalizedArgs["thinking"];
+	if (!Object.hasOwn(normalizedArgs, "inherit_context") && (params as unknown as Record<string, unknown>)["inherit_context"] === false) {
+		normalizedArgs["inherit_context"] = false;
+	}
+	if (
+		Object.keys(normalizedArgs).length !== expectedKeys.length ||
+		expectedKeys.some((key) => !Object.hasOwn(normalizedArgs, key))
+	) return false;
+	return (
+		normalizedArgs.subagent_type === params.subagent_type &&
+		normalizedArgs.description === params.description &&
+		normalizedArgs.prompt === params.prompt &&
+		normalizedArgs.inherit_context === params.inherit_context &&
+		normalizedArgs.isolated === params.isolated &&
+		normalizedArgs.isolation === params.isolation &&
+		normalizedArgs.run_in_background === params.run_in_background &&
+		normalizedArgs.max_turns === params.max_turns &&
+		normalizedArgs.resume === params.resume &&
+		normalizedArgs.schedule === params.schedule
+	);
+}
+
+export function parseForegroundAgentResult(
+	event: ToolResultLike,
+	fallbackAgentId: string,
+): NativeReviewResult {
+	if (event.toolName !== STANDARD_AGENT_TOOL || event.isError)
+		throw new Error("foreground Agent result is unavailable");
+	const details = isRecord(event.details)
+		? event.details
+		: toolDetails(event.result);
+	const status = stringField(details, "status") ?? "completed";
+	if (NATIVE_REVIEW_FAILURE_STATUSES.has(status)) {
+		throw new Error(stringField(details, "error") ?? `foreground Agent ${status}`);
+	}
+	if (!["completed", "steered", "wrapped_up"].includes(status))
+		throw new Error(`foreground Agent returned unsupported status: ${status}`);
+	const content = event.content ?? event.result;
+	const result = toolText(content);
+	if (!result.trim()) throw new Error("foreground Agent returned no review result");
+	const agentId = stringField(details, "agentId")
+		?? stringField(details, "agent_id")
+		?? `foreground-${fallbackAgentId}`;
+	const durationMs = parseDurationMs(result);
+	return {
+		agentId,
+		result,
+		status,
+		...(durationMs === undefined ? {} : { durationMs }),
+	};
+}
+
+export function promptDigest(prompt: string): string {
+	return `sha256:${createHash("sha256").update(prompt).digest("hex")}`;
+}
+
+export function toolResultText(result: unknown): string {
+	return toolText(result);
+}
+
+export function toolResultDetails(result: unknown): Record<string, unknown> | null {
+	return toolDetails(result);
+}
+
+function toolDetails(result: unknown): Record<string, unknown> | null {
+	if (!isRecord(result)) return null;
+	if (isRecord(result.details)) return result.details;
+	if (Array.isArray(result.content)) {
+		for (const item of result.content) {
+			if (isRecord(item) && isRecord(item.details)) return item.details;
+		}
+	}
+	return result;
+}
+
+function toolText(result: unknown): string {
+	if (typeof result === "string") return result;
+	if (Array.isArray(result)) {
+		return result
+			.map((item) => (isRecord(item) && typeof item.text === "string" ? item.text : ""))
+			.filter(Boolean)
+			.join("\n");
+	}
+	if (!isRecord(result)) return "";
+	if (typeof result.text === "string") return result.text;
+	if (Array.isArray(result.content)) {
+		return result.content
+			.map((item) => (isRecord(item) && typeof item.text === "string" ? item.text : ""))
+			.filter(Boolean)
+			.join("\n");
+	}
+	return "";
+}
+
+function parseDurationMs(text: string): number | undefined {
+	const match = text.match(/Duration:\s+([0-9.]+)\s*(ms|s|m)?/i);
+	if (!match) return undefined;
+	const amount = Number(match[1]);
+	if (!Number.isFinite(amount)) return undefined;
+	switch ((match[2] ?? "ms").toLowerCase()) {
+		case "s": return Math.round(amount * 1000);
+		case "m": return Math.round(amount * 60_000);
+		default: return Math.round(amount);
+	}
+}
+
+function stringField(record: Record<string, unknown> | null, key: string): string | null {
+	const value = record?.[key];
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function shortId(value: string): string {
+	return value.replace(/[^A-Za-z0-9]/g, "").slice(-8) || "review";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/plugins/immune-brain/.pi-extension/pi-canary-qa-findings.ts

@@ -0,0 +1,50 @@
+import { randomUUID } from "node:crypto";
+
+/**
+ * QA finding ids must stay globally unique for the lifetime of a task: the
+ * Kernel reducer rejects any finding id that was ever recorded, including
+ * resolved ones. Scoping each id to the snapshot digest plus a per-invocation
+ * suffix guarantees repeated rework attempts (even on an identical snapshot)
+ * never collide, while keeping the acceptance id traceable in the id itself.
+ */
+
+/** Digest-scoped id for a per-acceptance QA rework finding. */
+export function qaFindingId(acceptanceId: string, snapshotDigest: string): string {
+	return `qa-${acceptanceId}-${attemptRef(snapshotDigest)}`;
+}
+
+/** Digest-scoped id for an evidence-freshness QA rework finding. */
+export function qaEvidenceFreshnessId(snapshotDigest: string): string {
+	const digest16 = snapshotDigest.slice("sha256:".length, "sha256:".length + 16);
+	return `qa-evidence-freshness-${digest16}-${attemptRef(snapshotDigest)}`;
+}
+
+function attemptRef(snapshotDigest: string): string {
+	const digest8 = snapshotDigest.slice("sha256:".length, "sha256:".length + 8);
+	return `${digest8}-${randomUUID().slice(0, 6)}`;
+}
+
+/**
+ * Preserve the original QA verdict details (which acceptance failed and why)
+ * when applying an authority verdict fails. The raw reducer error alone masks
+ * the failure reason that matters; append the verdict findings when present.
+ */
+export function describeQaFailure(
+	boundedBase: string,
+	findings?: Array<{ id: string; summary: string }>,
+): string {
+	if (!findings?.length) return boundedBase;
+	const detail = findings.map((finding) => `${finding.id}: ${finding.summary}`).join(" | ");
+	const marker = "; verdict: ";
+	const totalBudget = 300;
+	// Reserve room for at least the first 160 chars of verdict detail.
+	const baseBudget = Math.max(0, totalBudget - marker.length - Math.min(detail.length, 160));
+	const trimmedBase =
+		boundedBase.length <= baseBudget
+			? boundedBase
+			: `${boundedBase.slice(0, Math.max(0, baseBudget - 1))}…`;
+	const detailBudget = Math.max(0, totalBudget - trimmedBase.length - marker.length);
+	const bounded =
+		detail.length <= detailBudget ? detail : `${detail.slice(0, Math.max(0, detailBudget - 3))}...`;
+	return `${trimmedBase}${marker}${bounded}`;
+}

package/plugins/immune-brain/.pi-extension/pi-canary-review-bundle.ts

@@ -0,0 +1,262 @@
+// Host-captured immutable review evidence for native Pi subagents.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+	mkdtempSync,
+	rmSync,
+	writeFileSync,
+	statSync,
+	readFileSync,
+	realpathSync,
+	chmodSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	captureGitTaskSnapshot,
+	pathMatchesScope,
+	taskDiffHash,
+	type GitTaskIndexEntry,
+} from "../runtime/workspace_scope";
+
+const MAX_REVIEW_BUNDLE_BYTES = 2 * 1024 * 1024;
+
+export interface ReviewOutcome {
+	status: "passed" | "failed" | "blocked";
+	summary: string;
+}
+
+export interface ReviewNeighborhoodFile {
+	mode: "100644" | "100755" | "120000";
+	oid: string;
+	base_mode: "100644" | "100755" | "120000";
+	base_oid: string;
+	fingerprint: string;
+	current_content: string;
+}
+
+export interface ReviewBundle {
+	contract: "assurance_kernel/review_bundle/v4";
+	root: string;
+	head: string;
+	scope: string[];
+	diff_hash: string;
+	dirty_files: Record<string, GitTaskIndexEntry & {
+		fingerprint: string;
+		current_content: string | null;
+	}>;
+	/** Present on newly captured bundles; optional only for legacy in-memory test fixtures. */
+	neighborhood_files?: Record<string, ReviewNeighborhoodFile>;
+	/** Explicit provenance for every bundled path. */
+	path_provenance?: Record<string, "diff" | "neighborhood">;
+	outcomes: Record<string, ReviewOutcome>;
+	bundle_digest: string;
+}
+
+function bundleDigest(bundle: Omit<ReviewBundle, "bundle_digest">): string {
+	return `sha256:${createHash("sha256").update(JSON.stringify(bundle)).digest("hex")}`;
+}
+
+const reviewUtf8 = new TextDecoder("utf-8", { fatal: true });
+
+function readIndexBlob(
+	root: string,
+	path: string,
+	entry: Pick<GitTaskIndexEntry, "oid">,
+): string | null {
+	if (!entry.oid) return null;
+	const type = execFileSync("git", ["cat-file", "-t", entry.oid], {
+		cwd: root,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+		maxBuffer: 16,
+		timeout: 10_000,
+	}).trim();
+	if (type !== "blob") throw new Error(`index object is not a blob for ${path}`);
+	const sizeText = execFileSync("git", ["cat-file", "-s", entry.oid], {
+		cwd: root,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+		maxBuffer: 64,
+		timeout: 10_000,
+	}).trim();
+	const size = Number(sizeText);
+	if (!Number.isSafeInteger(size) || size < 0 || size > MAX_REVIEW_BUNDLE_BYTES)
+		throw new Error(`review file exceeds bounded size: ${path}`);
+	const bytes = execFileSync("git", ["cat-file", "blob", entry.oid], {
+		cwd: root,
+		encoding: "buffer",
+		stdio: ["ignore", "pipe", "ignore"],
+		maxBuffer: MAX_REVIEW_BUNDLE_BYTES + 1,
+		timeout: 10_000,
+	}) as Buffer;
+	if (bytes.length !== size) throw new Error(`index blob size changed during capture: ${path}`);
+	let content: string;
+	try {
+		content = reviewUtf8.decode(bytes);
+	} catch {
+		throw new Error(`review file is not valid UTF-8: ${path}`);
+	}
+	if (!Buffer.from(content, "utf8").equals(bytes))
+		throw new Error(`review file does not round-trip through UTF-8: ${path}`);
+	return content;
+}
+
+const GIT_OBJECT_ID = /^[a-f0-9]{40,64}$/;
+const REVIEW_MODES = new Set(["100644", "100755", "120000"] as const);
+
+function nullRecords(bytes: Buffer): Buffer[] {
+	if (bytes.length === 0) return [];
+	if (bytes[bytes.length - 1] !== 0) throw new Error("git index listing is not NUL-terminated");
+	const records: Buffer[] = [];
+	let start = 0;
+	for (let index = 0; index < bytes.length; index += 1) {
+		if (bytes[index] !== 0) continue;
+		if (index === start) throw new Error("git index listing contains an empty record");
+		records.push(bytes.subarray(start, index));
+		start = index + 1;
+	}
+	return records;
+}
+
+function scopedNeighborhoodFiles(
+	root: string,
+	scope: string[],
+	dirtyPaths: Set<string>,
+): Record<string, ReviewNeighborhoodFile> {
+	const listing = execFileSync("git", ["ls-files", "--stage", "-z"], {
+		cwd: root,
+		encoding: "buffer",
+		stdio: ["ignore", "pipe", "ignore"],
+		maxBuffer: 32 * 1024 * 1024,
+		timeout: 10_000,
+	}) as Buffer;
+	const entries: Array<[string, ReviewNeighborhoodFile]> = [];
+	for (const record of nullRecords(listing)) {
+		const tab = record.indexOf(9);
+		if (tab < 0) throw new Error("git index entry is malformed");
+		const [mode, oid, stage] = record.subarray(0, tab).toString("ascii").split(" ");
+		let path: string;
+		try {
+			path = reviewUtf8.decode(record.subarray(tab + 1));
+		} catch {
+			throw new Error("git index path is not valid UTF-8");
+		}
+		if (!Buffer.from(path, "utf8").equals(record.subarray(tab + 1)))
+			throw new Error("git index path does not round-trip through UTF-8");
+		if (!scope.some((scopePath) => pathMatchesScope(path, scopePath)) || dirtyPaths.has(path)) continue;
+		if (!REVIEW_MODES.has(mode as "100644" | "100755" | "120000"))
+			throw new Error(`review neighborhood file has unsupported mode: ${path}`);
+		if (!GIT_OBJECT_ID.test(oid ?? "") || /^0+$/.test(oid ?? "") || stage !== "0")
+			throw new Error(`review neighborhood file has invalid index identity: ${path}`);
+		const content = readIndexBlob(root, path, { oid });
+		if (content === null) throw new Error(`review neighborhood file is missing index content: ${path}`);
+		entries.push([path, {
+			mode: mode as ReviewNeighborhoodFile["mode"],
+			oid,
+			base_mode: mode as ReviewNeighborhoodFile["base_mode"],
+			base_oid: oid,
+			fingerprint: `index:${mode}:${oid}`,
+			current_content: content,
+		}]);
+	}
+	entries.sort(([left], [right]) => left.localeCompare(right));
+	return Object.fromEntries(entries);
+}
+
+export function captureReviewBundle(
+	root: string,
+	scopeHint: unknown,
+	expectedDiffHash: string,
+	outcomes: Record<string, ReviewOutcome>,
+): ReviewBundle {
+	const before = captureGitTaskSnapshot(root, scopeHint);
+	if (taskDiffHash(root, before.scope) !== expectedDiffHash)
+		throw new Error("review task snapshot does not match assurance snapshot");
+	const dirtyFiles = Object.fromEntries(
+		Object.entries(before.staged_files).map(([path, entry]) => [path, {
+			...entry,
+			fingerprint: `index:${entry.mode ?? "missing"}:${entry.oid ?? "missing"}`,
+			current_content: readIndexBlob(before.repository_root, path, entry),
+		}]),
+	);
+	const neighborhoodFiles = scopedNeighborhoodFiles(
+		before.repository_root,
+		before.scope,
+		new Set(Object.keys(dirtyFiles)),
+	);
+	const pathProvenance = Object.fromEntries([
+		...Object.keys(dirtyFiles).map((path) => [path, "diff"] as const),
+		...Object.keys(neighborhoodFiles).map((path) => [path, "neighborhood"] as const),
+	].sort(([left], [right]) => left.localeCompare(right)));
+	const after = captureGitTaskSnapshot(root, before.scope);
+	if (
+		JSON.stringify(after) !== JSON.stringify(before) ||
+		taskDiffHash(root, before.scope) !== expectedDiffHash
+	) {
+		throw new Error("task snapshot changed while capturing immutable review bundle");
+	}
+	const unsigned = {
+		contract: "assurance_kernel/review_bundle/v4" as const,
+		root: before.repository_root,
+		head: before.head,
+		scope: before.scope,
+		diff_hash: expectedDiffHash,
+		dirty_files: dirtyFiles,
+		neighborhood_files: neighborhoodFiles,
+		path_provenance: pathProvenance,
+		// Defensive copies so later caller mutation cannot alter the frozen record.
+		outcomes: Object.fromEntries(
+			Object.entries(outcomes).map(([id, outcome]) => [id, { ...outcome }]),
+		),
+	};
+	if (Buffer.byteLength(JSON.stringify(unsigned)) > MAX_REVIEW_BUNDLE_BYTES) {
+		throw new Error("immutable review bundle exceeds bounded output limit");
+	}
+	return { ...unsigned, bundle_digest: bundleDigest(unsigned) };
+}
+
+export function verifyReviewBundle(bundle: ReviewBundle): void {
+	const { bundle_digest, ...unsigned } = bundle;
+	if (bundle_digest !== bundleDigest(unsigned)) throw new Error("immutable review bundle digest mismatch");
+}
+
+export function writeNativeReviewEvidence(payload: unknown): { path: string; remove(): void } {
+	const rawDirectory = mkdtempSync(join(tmpdir(), "imm-canary-native-review-"));
+	try {
+		const directory = realpathSync(rawDirectory);
+		chmodSync(directory, 0o755);
+		const path = join(directory, "evidence.json");
+		writeFileSync(path, JSON.stringify(payload), { encoding: "utf8", mode: 0o644, flag: "wx" });
+		// Fail-closed artifact check: the immutable evidence must be readable
+		// before a reserved review is dispatched.
+		assertReviewArtifact(path);
+		return {
+			path,
+			remove: () => rmSync(directory, { recursive: true, force: true }),
+		};
+	} catch (error) {
+		rmSync(rawDirectory, { recursive: true, force: true });
+		throw error;
+	}
+}
+
+/**
+ * Fail-closed artifact check: the immutable evidence file must exist and be
+ * readable before a reserved review is dispatched. Missing or unreadable
+ * artifacts throw so dispatch writes zero authority and exposes an explicit
+ * re-reserve path.
+ */
+export function assertReviewArtifact(path: string): void {
+	const targetPath = realpathSync(path);
+	let stat;
+	try {
+		stat = statSync(targetPath);
+	} catch {
+		throw new Error(`review evidence artifact is missing or empty: ${path}`);
+	}
+	if (!stat.isFile() || stat.size === 0) throw new Error(`review evidence artifact is missing or empty: ${path}`);
+	const read = readFileSync(targetPath, { encoding: "utf8" });
+	if (read.trim().length === 0) throw new Error(`review evidence artifact is empty: ${path}`);
+}

package/plugins/immune-brain/.pi-extension/pi-canary-tool-failure.ts

@@ -0,0 +1,28 @@
+export interface ToolFailureV1 {
+	contract: "immune_brain/tool_failure/v1";
+	tool: "imm_canary_enrollment" | "imm_kernel_canary";
+	task_id: string;
+	operation: string;
+	state: "blocked" | "failed" | "authority_conflict" | "settlement_unknown";
+	code: string;
+	message: string;
+	next_action: string;
+}
+
+export function throwToolFailure(
+	failure: Omit<ToolFailureV1, "contract">,
+): never {
+	throw new Error(JSON.stringify({
+		contract: "immune_brain/tool_failure/v1",
+		...failure,
+	} satisfies ToolFailureV1));
+}
+
+export function isToolFailureState(
+	state: unknown,
+): state is ToolFailureV1["state"] {
+	return state === "blocked"
+		|| state === "failed"
+		|| state === "authority_conflict"
+		|| state === "settlement_unknown";
+}