immune-brain 3.6.9 → 4.0.0

package/plugins/immune-brain/runtime/assurance/verification.ts

@@ -1,244 +1,284 @@
-// Host-neutral verification descriptor runner.
-//
-// The strict canonical parser for `assurance_kernel/verification_descriptor/v1`
-// is `runtime/verification_descriptor.ts`. This module binds the frozen Bun
-// runner, compatibility gate, fixed execution, and findings digest.
+// Shared, bounded execution of project commands. No language/tool registry.
+import { createHash, randomBytes } from "node:crypto";
+import { execFileSync, spawn } from "node:child_process";
+import { accessSync, constants, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { delimiter, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { VERIFICATION_DESCRIPTOR_BOUNDS, VerificationDescriptorError, type VerificationCommand } from "../verification_descriptor";
+export * from "../verification_descriptor";
 
-import { createHash } from "node:crypto";
-import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { realpathSync, statSync } from "node:fs";
-import { isAbsolute, join, resolve, sep, relative } from "node:path";
-
-
-export {
-	VERIFICATION_DESCRIPTOR_CONTRACT,
-	parseVerificationDescriptor,
-	canonicalDescriptorBytes,
-	VerificationDescriptorError,
-	VERIFICATION_DESCRIPTOR_BOUNDS,
-	type VerificationDescriptor,
-} from "../verification_descriptor";
-import {
-	VERIFICATION_DESCRIPTOR_BOUNDS,
-	VerificationDescriptorError,
-	type VerificationDescriptor,
-} from "../verification_descriptor";
-
-/** Host-owned frozen runner identity: absolute realpath, device/inode, content hash, version. */
-export interface FrozenRunner {
-	runner_id: "bun";
+export interface ExecutableIdentity {
 	path: string;
+	invocation_path: string;
 	dev: number;
 	ino: number;
 	content_hash: string;
-	version: string;
+}
+export interface FrozenCommand {
+	entry: ExecutableIdentity;
+	interpreter: ExecutableIdentity | null;
+	interpreter_args: string[];
+}
+export interface VerificationResult {
+	exit_code: number;
+	stdout: string;
+	stderr: string;
+	timed_out: boolean;
+	output_limited: boolean;
 }
 
-export function resolveBunRunner(): FrozenRunner {
-	let executable: string;
-	try {
-		executable = execFileSync("which", ["bun"], { encoding: "utf8" }).trim();
-	} catch {
-		throw new VerificationDescriptorError("bun runner is unavailable on this host");
+export class VerificationAbortedError extends Error {
+	constructor() { super("fixed verification aborted"); this.name = "VerificationAbortedError"; }
+}
+export class VerificationLaunchError extends Error {
+	constructor() { super("verification process failed to start"); this.name = "VerificationLaunchError"; }
+}
+export class VerificationCleanupError extends Error {
+	constructor() { super("verification process cleanup failed"); this.name = "VerificationCleanupError"; }
+}
+
+// Bounded window for proving that a signalled process is gone. SIGKILL delivery
+// is not proof of exit, so the set is re-scanned and re-checked until it drains.
+export const CLEANUP_CONFIRM_TIMEOUT_MS = 2_000;
+export const CLEANUP_CONFIRM_POLL_MS = 25;
+
+export function insideVerificationRoot(root: string, candidate: string): string {
+	const realRoot = realpathSync(root);
+	const real = realpathSync(candidate);
+	const rel = relative(realRoot, real);
+	if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+		throw new VerificationDescriptorError("verification path escapes the materialization");
+	return real;
+}
+
+export function verificationPath(): string {
+	return (process.env.PATH ?? "").split(delimiter).filter(path => isAbsolute(path)).join(delimiter);
+}
+
+function toolPath(name: string, path: string): string {
+	for (const dir of path.split(delimiter).filter(isAbsolute)) {
+		const candidate = join(dir, name);
+		try { accessSync(candidate, constants.X_OK); if (statSync(candidate).isFile()) return candidate; }
+		catch { /* Search the remaining host-owned PATH entries. */ }
 	}
-	let real: string;
+	throw new VerificationDescriptorError("verification tool is unavailable on this host");
+}
+
+function identity(path: string): ExecutableIdentity {
 	try {
-		// When which returns a version-manager shim (e.g. mise or asdf),
-		// realpathSync on the shim resolves to the version-manager binary rather
-		// than bun. Ask bun itself for its real process.execPath.
-		const execPath = spawnSync(executable, ["-e", "console.log(process.execPath)"], {
-			encoding: "utf8",
-			stdio: ["ignore", "pipe", "ignore"],
-		});
-		if (execPath.status === 0 && execPath.stdout.trim().length > 0) {
-			real = realpathSync(execPath.stdout.trim());
+		const real = realpathSync(path);
+		accessSync(real, constants.X_OK);
+		const stat = statSync(real);
+		if (!stat.isFile()) throw new Error("not a file");
+		return { path: real, invocation_path: path, dev: stat.dev, ino: stat.ino, content_hash: `sha256:${createHash("sha256").update(readFileSync(real)).digest("hex")}` };
+	} catch { throw new VerificationDescriptorError("verification executable is unavailable or not executable"); }
+}
+
+export function resolveVerificationCommand(root: string, command: VerificationCommand, path = verificationPath()): FrozenCommand {
+	insideVerificationRoot(root, resolve(root, command.cwd));
+	const entry = identity(command.executable.startsWith("./")
+		? insideVerificationRoot(root, resolve(root, command.executable)) : toolPath(command.executable, path));
+	const prefix = readFileSync(entry.path).subarray(0, 512).toString("utf8");
+	let interpreter: ExecutableIdentity | null = null;
+	let interpreter_args: string[] = [];
+	if (prefix.startsWith("#!")) {
+		const lineEnd = prefix.indexOf("\n");
+		if (lineEnd < 0) throw new VerificationDescriptorError("verification interpreter declaration is unbounded");
+		const parts = prefix.slice(2, lineEnd).trim().split(/\s+/);
+		const name = parts.shift()!;
+		if (!isAbsolute(name)) throw new VerificationDescriptorError("verification interpreter must be absolute");
+		if (name === "/usr/bin/env" || name === "/bin/env") {
+			if (parts.length !== 1 || !/^[A-Za-z0-9_][A-Za-z0-9_.+-]*$/.test(parts[0]!))
+				throw new VerificationDescriptorError("verification interpreter resolution is ambiguous; use a direct interpreter command");
+			interpreter = identity(toolPath(parts[0]!, path));
 		} else {
-			real = realpathSync(executable);
+			if (parts.length > 1) throw new VerificationDescriptorError("verification interpreter arguments are ambiguous");
+			interpreter = identity(name);
+			interpreter_args = parts;
 		}
-	} catch {
-		throw new VerificationDescriptorError("bun runner realpath is unresolvable");
-	}
-	let stat: ReturnType<typeof statSync>;
-	try {
-		stat = statSync(real);
-	} catch {
-		throw new VerificationDescriptorError("bun runner is unreadable");
-	}
-	if (!stat.isFile())
-		throw new VerificationDescriptorError("bun runner is not a regular file");
-	const { readFileSync } = require("node:fs") as typeof import("node:fs");
-	const contentHash = `sha256:${createHash("sha256").update(readFileSync(real)).digest("hex")}`;
-	let version = "";
-	try {
-		version = execFileSync(real, ["--version"], { encoding: "utf8" }).trim();
-	} catch {
-		throw new VerificationDescriptorError("bun runner version is unreadable");
+		if (readFileSync(interpreter.path).subarray(0, 2).toString() === "#!")
+			throw new VerificationDescriptorError("verification interpreter is itself a script; resolve the host tool explicitly");
 	}
-	return {
-		runner_id: "bun",
-		path: real,
-		dev: stat.dev,
-		ino: stat.ino,
-		content_hash: contentHash,
-		version,
-	};
+	return { entry, interpreter, interpreter_args };
 }
 
-/** The descriptor's claimed runner version must equal the frozen host runner version. */
-export function assertRunnerCompatible(
-	descriptor: VerificationDescriptor,
-	runner: FrozenRunner,
-): void {
-	if (descriptor.runner_version !== runner.version)
-		throw new VerificationDescriptorError(
-			`frozen runner version mismatch: descriptor claims ${descriptor.runner_version}, host has ${runner.version}; assurance unavailable`,
-		);
-}
-
-/** Raised when the host cancels a running fixed verification. */
-export class VerificationAbortedError extends Error {
-	constructor() {
-		super("fixed verification aborted");
-		this.name = "VerificationAbortedError";
+export function assertCommandIdentity(frozen: FrozenCommand): void {
+	for (const item of [frozen.entry, frozen.interpreter]) {
+		if (item && JSON.stringify(identity(item.invocation_path)) !== JSON.stringify(item))
+			throw new VerificationDescriptorError("verification executable identity changed");
 	}
 }
 
-/** Run the frozen runner with the descriptor argv/cwd under minimal environment. */
 export async function runFixedVerification(
 	root: string,
-	descriptor: VerificationDescriptor,
-	runner: FrozenRunner,
-	options: { signal?: AbortSignal } = {},
-): Promise<{ exit_code: number; stdout: string; stderr: string; timed_out: boolean }> {
-	const canonicalRoot = resolve(root);
-	const cwd = resolve(canonicalRoot, descriptor.cwd);
-	if (cwd === canonicalRoot ? false : !relative(canonicalRoot, cwd).startsWith(".") === false)
-		throw new VerificationDescriptorError("verification cwd escapes the repository");
-	if (isAbsolute(descriptor.cwd) || relative(canonicalRoot, cwd).startsWith(`..${sep}`) || cwd === resolve(canonicalRoot, ".."))
-		throw new VerificationDescriptorError("verification cwd escapes the repository");
+	command: VerificationCommand,
+	frozen: FrozenCommand,
+	options: { signal?: AbortSignal; home: string; path: string; _processScanner?: string; _procRoot?: string } ,
+): Promise<VerificationResult> {
 	if (options.signal?.aborted) throw new VerificationAbortedError();
-	if (process.platform === "win32")
-		throw new VerificationDescriptorError("fixed verification process-group isolation requires a POSIX host");
-	const maxOutput = Math.min(descriptor.max_output_bytes, VERIFICATION_DESCRIPTOR_BOUNDS.max_output_bytes);
+	if (process.platform === "win32") throw new VerificationDescriptorError("fixed verification process-group isolation requires a POSIX host");
+	const cwd = insideVerificationRoot(root, resolve(root, command.cwd));
+	assertCommandIdentity(frozen);
+	// Token discovery is platform native. Only the BSD path needs `ps`, whose
+	// environment modifier procps-ng rejects on Linux, and resolving it is a
+	// hard requirement there but pointless here.
+	const processScanner = process.platform === "linux" ? null
+		: identity(options._processScanner ?? toolPath("ps", verificationPath()));
+	const procRoot = options._procRoot ?? "/proc";
+	const maxOutput = Math.min(command.max_output_bytes, VERIFICATION_DESCRIPTOR_BOUNDS.max_output_bytes);
 	return new Promise((resolvePromise, rejectPromise) => {
-		let settled = false;
-		let stdout = Buffer.alloc(0);
-		let stderr = Buffer.alloc(0);
-		let capturedBytes = 0;
-		const child = spawn(runner.path, descriptor.argv, {
-			cwd,
-			env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "" },
-			detached: process.platform !== "win32",
+		let stdout = Buffer.alloc(0), stderr = Buffer.alloc(0), captured = 0;
+		let aborted = false, timed_out = false, output_limited = false, settled = false;
+		const processToken = randomBytes(24).toString("hex");
+		const args = frozen.interpreter
+			? [...frozen.interpreter_args, frozen.entry.path, ...command.argv] : command.argv;
+		const child = spawn(frozen.interpreter?.invocation_path ?? frozen.entry.invocation_path, args, {
+			cwd, shell: false, detached: true,
+			env: { PATH: options.path, HOME: options.home, TMPDIR: options.home, XDG_CACHE_HOME: options.home,
+				IMM_VERIFICATION_PROCESS_TOKEN: processToken },
 			stdio: ["ignore", "pipe", "pipe"],
 		});
-
-		const killTree = () => {
-			if (child.pid === undefined) return;
-			try {
-				if (process.platform !== "win32") process.kill(-child.pid, "SIGKILL");
-				else child.kill("SIGKILL");
-			} catch {
-				// The process already exited.
+		const killGroup = () => {
+			if (child.pid !== undefined) try { process.kill(-child.pid, "SIGKILL"); } catch { /* Already exited. */ }
+		};
+		// Signal every candidate and its process group. A refusal is not evidence in
+		// either direction, so the result is ignored and liveness below decides.
+		const signalPids = (pids: Iterable<number>): void => {
+			for (const pid of pids) for (const target of [-pid, pid]) {
+				try { process.kill(target, "SIGKILL"); } catch { /* Re-checked by liveness. */ }
 			}
 		};
-		const cleanup = () => {
-			clearTimeout(timeout);
-			options.signal?.removeEventListener("abort", onAbort);
+		// ESRCH is the only evidence a process is gone: an EPERM refusal leaves it
+		// unknown, so it counts as still present and fails the cleanup closed.
+		const alive = (pid: number): boolean => {
+			try { process.kill(pid, 0); return true; }
+			catch (error) { return (error as NodeJS.ErrnoException | undefined)?.code !== "ESRCH"; }
+		};
+		// An environment we cannot read is only missing evidence about a process that
+		// already left this run's session; in-session processes are cleaned without it.
+		const procEnviron = (pid: number): string | null => {
+			try { return readFileSync(join(procRoot, String(pid), "environ"), "utf8"); }
+			catch { return null; }
+		};
+		// Session membership is the attribution evidence: /proc/<pid>/stat needs no
+		// ptrace privilege and stays truthful when a process changes its uid, so a
+		// descendant that drops privileges is still recognised as ours while an
+		// unrelated privileged process never blocks verification.
+		const procSession = (entry: string): number | null | undefined => {
+			let stat: string;
+			try { stat = readFileSync(join(procRoot, entry, "stat"), "utf8"); }
+			catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+				return undefined;
+			}
+			// The quoted comm field may contain spaces and parentheses, so parse after it.
+			const fields = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/);
+			const session = Number(fields[3]);
+			// Session zero is a legitimate value that kernel threads carry, so only a
+			// missing or unobservable number means the session could not be read.
+			return Number.isSafeInteger(session) && session >= 0 ? session : undefined;
+		};
+		const scanTokenPids = (): Set<number> | null => {
+			if (child.pid === undefined) return null;
+			try {
+				// The direct child is known without discovery, so it is always a candidate.
+				const pids = new Set<number>([child.pid]);
+				if (process.platform === "linux") {
+					const marker = `IMM_VERIFICATION_PROCESS_TOKEN=${processToken}`;
+					for (const entry of readdirSync(procRoot)) {
+						if (!/^\d+$/.test(entry)) continue;
+						const session = procSession(entry);
+						if (session === undefined) throw new Error("verification process session is unreadable");
+						if (session === null) continue; // the process vanished mid-scan
+						// The command runs as its own session leader, so everything still in that
+						// session belongs to it whatever uid it has taken on since.
+						if (session === child.pid) { pids.add(Number(entry)); continue; }
+						// A process that left the session is only ours if it still carries the
+						// inherited token, which is checkable whenever the host lets us read it.
+						const environ = procEnviron(Number(entry));
+						if (environ !== null && environ.split("\0").includes(marker)) pids.add(Number(entry));
+					}
+					return pids;
+				}
+				if (processScanner === null || JSON.stringify(identity(processScanner.invocation_path)) !== JSON.stringify(processScanner))
+					throw new Error("process scanner identity changed");
+				for (const line of execFileSync(processScanner.invocation_path, ["eww", "-axo", "pid=,command="], {
+					encoding: "utf8", maxBuffer: 16 * 1024 * 1024, timeout: 5000,
+				}).split("\n")) {
+					if (!line.includes(processToken)) continue;
+					const pid = Number(/^\s*(\d+)/.exec(line)?.[1]);
+					if (Number.isSafeInteger(pid) && pid > 1) pids.add(pid);
+				}
+				return pids;
+			} catch { return null; }
 		};
-		const resolveOnce = (result: { exit_code: number; stdout: string; stderr: string; timed_out: boolean }) => {
+		// Cleanup must be proved before any outcome settles: a scan that fails and
+		// descendants still alive are both re-checked within the bounded window,
+		// and anything left unproven when it closes fails the run closed.
+		const killTree = async (): Promise<boolean> => {
+			const deadline = Date.now() + CLEANUP_CONFIRM_TIMEOUT_MS;
+			for (;;) {
+				// The direct child needs no discovery to be known, so it is signalled on
+				// every pass: a scanner failure must never return a running process.
+				if (child.pid !== undefined) signalPids([child.pid]);
+				const pids = scanTokenPids();
+				if (pids !== null) {
+					signalPids(pids);
+					if ([...pids].every((pid) => !alive(pid))) return true;
+				}
+				if (Date.now() >= deadline) return false;
+				await new Promise((wake) => setTimeout(wake, CLEANUP_CONFIRM_POLL_MS));
+			}
+		};
+		let timeout: ReturnType<typeof setTimeout> | undefined;
+		const closePipes = () => { child.stdout?.destroy(); child.stderr?.destroy(); };
+		const finish = async (code: number | null) => {
 			if (settled) return;
 			settled = true;
-			cleanup();
-			resolvePromise(result);
+			if (timeout) clearTimeout(timeout);
+			options.signal?.removeEventListener("abort", onAbort);
+			const cleaned = await killTree();
+			// An unproven cleanup outranks every outcome, cancellation included: any
+			// other error would hand the caller back a delivery whose process may
+			// still be running against it.
+			if (!cleaned) { rejectPromise(new VerificationCleanupError()); return; }
+			if (aborted) { rejectPromise(new VerificationAbortedError()); return; }
+			try { assertCommandIdentity(frozen); } catch (error) { rejectPromise(error); return; }
+			resolvePromise({ exit_code: timed_out || output_limited ? 1 : code ?? 1,
+				stdout: stdout.toString("utf8"), stderr: stderr.toString("utf8"), timed_out, output_limited });
 		};
-		const rejectOnce = (error: Error) => {
+		const failLaunch = () => {
 			if (settled) return;
 			settled = true;
-			cleanup();
-			rejectPromise(error);
-		};
-		const appendBounded = (current: Buffer<ArrayBuffer>, chunk: Buffer<ArrayBuffer>): { content: Buffer<ArrayBuffer>; exceeded: boolean } => {
-			const available = Math.max(0, maxOutput - capturedBytes);
-			const accepted = chunk.subarray(0, available);
-			capturedBytes += accepted.length;
-			return {
-				content: accepted.length > 0 ? Buffer.concat([current, accepted]) : current,
-				exceeded: chunk.length > available,
-			};
-		};
-		const outputLimitExceeded = () => {
-			const marker = Buffer.from("verification output limit exceeded\n", "utf8");
-			stdout = stdout.subarray(0, Math.max(0, maxOutput - marker.length));
-			stderr = marker.subarray(0, maxOutput - stdout.length);
-			capturedBytes = stdout.length + stderr.length;
-			killTree();
-			child.stdout?.destroy();
-			child.stderr?.destroy();
-			resolveOnce({
-				exit_code: 1,
-				stdout: stdout.toString("utf8"),
-				stderr: stderr.toString("utf8"),
-				timed_out: false,
-			});
-		};
-		child.stdout?.on("data", (chunk: Buffer<ArrayBuffer>) => {
-			const appended = appendBounded(stdout, chunk);
-			stdout = appended.content;
-			if (appended.exceeded) outputLimitExceeded();
-		});
-		child.stderr?.on("data", (chunk: Buffer<ArrayBuffer>) => {
-			const appended = appendBounded(stderr, chunk);
-			stderr = appended.content;
-			if (appended.exceeded) outputLimitExceeded();
-		});
-		child.once("error", (error) => {
-			resolveOnce({
-				exit_code: 1,
-				stdout: stdout.toString("utf8"),
-				stderr: `${stderr.toString("utf8")}runner spawn failed: ${error.message}`.slice(0, maxOutput),
-				timed_out: false,
-			});
-		});
-		child.once("close", (code) => {
-			resolveOnce({
-				exit_code: code ?? 1,
-				stdout: stdout.toString("utf8"),
-				stderr: stderr.toString("utf8"),
-				timed_out: false,
-			});
-		});
-		const onAbort = () => {
-			killTree();
-			child.stdout?.destroy();
-			child.stderr?.destroy();
-			rejectOnce(new VerificationAbortedError());
+			if (timeout) clearTimeout(timeout);
+			options.signal?.removeEventListener("abort", onAbort);
+			closePipes();
+			// A launch failure still owes a confirmed cleanup before it settles.
+			void killTree().then((cleaned) => rejectPromise(
+				cleaned ? new VerificationLaunchError() : new VerificationCleanupError()));
 		};
+		const onAbort = () => { aborted = true; closePipes(); void finish(null); };
 		options.signal?.addEventListener("abort", onAbort, { once: true });
-		const timeout = setTimeout(() => {
-			killTree();
-			child.stdout?.destroy();
-			child.stderr?.destroy();
-			resolveOnce({
-				exit_code: 1,
-				stdout: stdout.toString("utf8"),
-				stderr: stderr.toString("utf8"),
-				timed_out: true,
-			});
-		}, descriptor.timeout_ms);
+		if (options.signal?.aborted) onAbort();
+		if (!settled) timeout = setTimeout(() => { timed_out = true; closePipes(); void finish(null); }, command.timeout_ms);
+		const append = (chunk: Buffer, channel: "stdout" | "stderr") => {
+			if (output_limited) return;
+			const accepted = chunk.subarray(0, Math.max(0, maxOutput - captured));
+			captured += accepted.length;
+			if (channel === "stdout") stdout = Buffer.concat([stdout, accepted]);
+			else stderr = Buffer.concat([stderr, accepted]);
+			if (accepted.length < chunk.length) { output_limited = true; closePipes(); void finish(null); }
+		};
+		child.stdout?.on("data", (chunk: Buffer) => append(chunk, "stdout"));
+		child.stderr?.on("data", (chunk: Buffer) => append(chunk, "stderr"));
+		child.once("error", failLaunch);
+		// A successful parent must not leave descendants holding pipes open.
+		child.once("exit", killGroup);
+		child.once("close", (code) => { void finish(code); });
 	});
 }
 
-/** Normalized findings digest: stable-sorted keys over id/kind/acceptance_id/summary. */
-export function findingsDigest(
-	findings: Array<{ id: string; kind: string; acceptance_id: string | null; summary: string }>,
-): string {
-	const normalized = findings.map((f) =>
-		JSON.stringify({
-			acceptance_id: f.acceptance_id,
-			id: f.id,
-			kind: f.kind,
-			summary: f.summary,
-		}),
-	);
+/** Must remain byte-identical to the Kernel findings digest. */
+export function findingsDigest(findings: Array<{ id: string; kind: string; acceptance_id: string | null; summary: string }>): string {
+	const normalized = findings.map(f => JSON.stringify({ acceptance_id: f.acceptance_id, id: f.id, kind: f.kind, summary: f.summary }));
 	return `sha256:${createHash("sha256").update(`[${normalized.join(",")}]`).digest("hex")}`;
 }

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

@@ -0,0 +1,20 @@
+// Which authority operation a Host may request is Kernel projection policy, not
+// Host policy: the Kernel's own readiness is the sole source. Both Hosts derive
+// the operation here, so the derivation cannot drift between them — Claude used
+// to re-implement this mapping inline.
+
+import type { AssuranceAuthorizationReadiness } from "./kernel/assurance_projection";
+
+export type DerivedAuthorizationOperation =
+	| "resolve-user-decision"
+	| "authorize-rework";
+
+// Kernel projection is the sole source of authorization readiness.
+export function deriveAuthorizationOperation(input: {
+	readiness: AssuranceAuthorizationReadiness;
+}): { operation: DerivedAuthorizationOperation } | { blocked: string } {
+	if (input.readiness.state === "resolve_user_decision") return { operation: "resolve-user-decision" };
+	if (input.readiness.state === "authorize_rework") return { operation: "authorize-rework" };
+	if (input.readiness.blocked) return { blocked: input.readiness.blocked };
+	return { blocked: "no unique host-derived authorization operation" };
+}