immune-brain 3.6.9 → 4.0.1

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

@@ -7,11 +7,10 @@
 // evidence reservation.
 
 import { createHash, randomUUID } from "node:crypto";
-import type { FindingEvidence, TaskFinding } from "../kernel/types";
+import type { FindingEvidence, ReviewAdvisoryFindingV1, TaskFinding } from "../kernel/types";
 import { anchorForEvidence } from "../kernel/refutation";
 import {
 	findingsDigest,
-	type FrozenRunner,
 	type VerificationDescriptor,
 	VerificationAbortedError,
 } from "./verification";
@@ -21,6 +20,7 @@ import { buildRoleDelegationPacket } from "../role_prompt_bridge";
 import type { AssuranceProjectionResult } from "../kernel/assurance_projection";
 import type { TaskIntentIdentityToken } from "../kernel/intent_token_registry";
 import type { AssuranceHostPort, HostReviewReservation } from "./host_port";
+import type { GithubTrackerResult as GithubTrackerProjectionResult } from "../github_issue_tracker";
 
 export type AssuranceRole = "qa" | "review";
 export interface AssuranceCorrelation {
@@ -74,6 +74,42 @@ export function deriveGithubTerminalProjectionInput(
 	};
 }
 
+/**
+ * Post-settlement GitHub tracker projection, shared so a task settled under
+ * either Host produces the same opted-in terminal projection.
+ *
+ * Transport, never authority: the projection runs only for a fresh claimless
+ * done/stopped projection plus its exact terminal tombstone (`derive` returns
+ * null otherwise), a tracker failure is reported as a retryable failure rather
+ * than evidence or a blocker, and a failure never repeats the settling Kernel
+ * mutation.
+ */
+export async function projectTerminalTrackerState(input: {
+	root: string;
+	task_id: string;
+	projection: AssuranceProjectionResult;
+	tombstone: TaskTombstone | null;
+	markTerminal: (root: string, projection: GithubTerminalProjectionInput) => Promise<GithubTrackerProjectionResult>;
+}): Promise<GithubTrackerProjectionResult | undefined> {
+	if (input.projection.error) return undefined;
+	const terminal = deriveGithubTerminalProjectionInput(input.task_id, input.projection, input.tombstone);
+	if (!terminal) return undefined;
+	try {
+		return await input.markTerminal(input.root, terminal);
+	} catch {
+		return TRACKER_PROJECTION_FAILURE;
+	}
+}
+
+/** The one shape both Hosts report when post-settlement observation fails. */
+export const TRACKER_PROJECTION_FAILURE: GithubTrackerProjectionResult = {
+	contract: "immune_brain/github_issue_tracker_result/v1",
+	operation: "mark-terminal",
+	status: "retryable_failure",
+	association_found: false,
+	message: "tracker observation failed after authoritative settlement",
+};
+
 export interface AssuranceVerdict {
 	contract: "assurance_kernel/assurance_verdict/v2";
 	role: AssuranceRole;
@@ -91,8 +127,8 @@ export interface AssuranceVerdict {
 		acceptance_id: string | null;
 		summary: string;
 		/**
-		 * Derived by `parseAssuranceVerdict` for Review-role rework findings. QA
-		 * findings and pass verdicts never carry it.
+		 * Derived by `parseAssuranceVerdict` for every Review-role finding, the
+		 * advisory notes of a pass verdict included. QA findings never carry it.
 		 */
 		anchor?: string;
 		evidence?: FindingEvidence;
@@ -124,6 +160,24 @@ export function reviewReworkFindings(verdict: AssuranceVerdict): TaskFinding[] {
 	}));
 }
 
+/**
+ * The advisory counterpart of `reviewReworkFindings`: a pass verdict may carry
+ * non-blocking Review notes, and both Hosts record them on the review
+ * attestation itself so settlement can never separate the two.
+ */
+export function reviewAdvisoryRecords(verdict: AssuranceVerdict): ReviewAdvisoryFindingV1[] {
+	if (verdict.decision !== "pass") throw new Error("advisory findings require a pass verdict");
+	return (verdict.findings ?? [])
+		.filter((finding) => finding.kind === "advisory")
+		.map((finding) => ({
+			id: finding.id,
+			acceptance_id: finding.acceptance_id,
+			summary: finding.summary,
+			anchor: finding.anchor ?? null,
+			evidence: finding.evidence ?? null,
+		}));
+}
+
 export interface ReviewRevisionIdentity {
 	contract: "assurance_kernel/review_revision_identity/v1";
 	base_head: string;
@@ -135,6 +189,8 @@ export interface ReviewRevisionIdentity {
 export interface SnapshotDescriptor {
 	contract: "assurance_kernel/assurance_snapshot/v2";
 	task_id: string;
+	/** The exact run this snapshot was captured from; null when none is committed. */
+	run_id: string | null;
 	role: AssuranceRole;
 	record_revision: string;
 	workspace_revision: string;
@@ -201,13 +257,11 @@ export interface AssuranceCoordinatorPorts {
 	projectTask(root: string, taskId: string): Promise<AssuranceProjectionResult>;
 	readTaskRecord(root: string, taskId: string): Promise<TaskRecordRead>;
 	readTaskIntent(root: string, taskId: string): Promise<TaskIntentRead>;
-	frozenRunner(): Promise<FrozenRunner>;
 	buildAssurance(
 		root: string,
 		taskId: string,
 		role: AssuranceRole,
 		projection: AssuranceProjectionResult,
-		runner: FrozenRunner,
 	): Promise<{
 		snapshot: SnapshotDescriptor;
 		descriptors: Map<string, VerificationDescriptor>;
@@ -227,7 +281,6 @@ export interface AssuranceCoordinatorPorts {
 	runQa(
 		snapshot: SnapshotDescriptor,
 		descriptors: Map<string, VerificationDescriptor>,
-		runner: FrozenRunner,
 		options: { signal?: AbortSignal; onProgress?: (progress: QaVerificationProgress) => void },
 	): Promise<AssuranceVerdict>;
 	writeReviewEvidence(input: { snapshot: SnapshotDescriptor; evidence: ReviewBundle | ReviewManifestV5 }): { path: string; remove(): void };
@@ -272,13 +325,19 @@ export const REVIEW_TIMING_PROFILES: Readonly<Record<ReviewWorkload, ReviewTimin
 	heavy: { softDeadlineSeconds: 20 * 60, stopThresholdSeconds: 60 * 60 },
 };
 
-function declaredQaJobTimeoutMs(descriptors: Iterable<Pick<VerificationDescriptor, "timeout_ms">>): number {
+function declaredQaJobTimeoutMs(descriptors: Iterable<VerificationDescriptor>): number {
 	let declaredMs = 0;
-	for (const descriptor of descriptors) declaredMs += descriptor.timeout_ms;
+	const prepared = new Set<string>();
+	for (const descriptor of descriptors) {
+		declaredMs += descriptor.command.timeout_ms;
+		const key = JSON.stringify(descriptor.environment);
+		if (!prepared.has(key)) declaredMs += descriptor.environment.prepare?.timeout_ms ?? 0;
+		prepared.add(key);
+	}
 	return Math.max(QA_MIN_JOB_TIMEOUT_SECONDS * 1000, declaredMs + QA_JOB_OVERHEAD_SECONDS * 1000);
 }
 
-export function deriveQaJobTimeoutMs(descriptors: Iterable<Pick<VerificationDescriptor, "timeout_ms">>): number {
+export function deriveQaJobTimeoutMs(descriptors: Iterable<VerificationDescriptor>): number {
 	const derivedMs = declaredQaJobTimeoutMs(descriptors);
 	if (derivedMs > QA_MAX_JOB_TIMEOUT_SECONDS * 1000)
 		throw new Error(`declared QA budget ${Math.ceil(derivedMs / 60_000)} minutes exceeds the maximum of 60 minutes`);
@@ -348,6 +407,7 @@ export function buildReviewPrompt(snapshot: SnapshotDescriptor, evidencePath?: s
 		"Reserve the final turn for exactly one strict JSON verdict. Reply with ONLY that object, without markdown fences or commentary.",
 		`Every rework finding must carry machine-checkable provenance: evidence.trigger (the concrete inputs or state that reach the defect), a non-empty evidence.caller_chain (ordered repository paths or symbols), and evidence.violated {kind: "acceptance"|"security_boundary", ref}. The anchor is derived from that evidence; a finding without it is rejected and the correction must be resubmitted.`,
 		`PASS shape: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"pass","approval":{"kind":"review","authority_role":"reviewer","summary":"<one line>"}}`,
+		`A pass verdict may carry non-blocking notes as findings, but every one of them must set kind "advisory"; a blocking finding is a rework verdict and must omit approval: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"pass","approval":{"kind":"review","authority_role":"reviewer","summary":"<one line>"},"findings":[{"id":"review-1","kind":"advisory","acceptance_id":"<id|null>","summary":"<one line>","evidence":{"trigger":"<concrete inputs or state>","caller_chain":["<path-or-symbol>"],"violated":{"kind":"acceptance|security_boundary","ref":"<acceptance id or boundary>"}}}]}`,
 		`REWORK shape: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"rework","findings":[{"id":"review-1","kind":"blocking|advisory","acceptance_id":"<id|null>","summary":"<one line>","evidence":{"trigger":"<concrete inputs or state>","caller_chain":["<path-or-symbol>"],"violated":{"kind":"acceptance|security_boundary","ref":"<acceptance id or boundary>"}}}]}`,
 		`REWORK verdicts must omit the approval field entirely; do not emit "approval": null.`,
 	].join("\n");
@@ -423,12 +483,31 @@ export function parseAssuranceVerdict(input: unknown, snapshot: SnapshotDescript
 		if (!approval || approval.kind !== expectedKind || approval.authority_role !== expectedRole || typeof approval.summary !== "string" || !approval.summary.trim()) throw new Error("pass verdict approval is invalid");
 		const unknownApproval = Object.keys(approval).find((key) => !["kind", "authority_role", "summary"].includes(key));
 		if (unknownApproval) throw new Error(`pass verdict approval has unknown field: ${unknownApproval}`);
-		if (raw.findings !== undefined) throw new Error("pass verdict must omit findings");
-		return { contract: "assurance_kernel/assurance_verdict/v2", role: snapshot.role, task_id: snapshot.task_id, snapshot_digest: snapshotDigest(snapshot), decision: "pass", approval: { kind: expectedKind, authority_role: expectedRole, summary: approval.summary } };
+		const passFindings = raw.findings === undefined ? [] : parseVerdictFindings(raw.findings as unknown[], snapshot);
+		if (passFindings.some((finding) => finding.kind !== "advisory")) throw new Error("pass verdict findings must all be advisory");
+		return {
+			contract: "assurance_kernel/assurance_verdict/v2",
+			role: snapshot.role,
+			task_id: snapshot.task_id,
+			snapshot_digest: snapshotDigest(snapshot),
+			decision: "pass",
+			approval: { kind: expectedKind, authority_role: expectedRole, summary: approval.summary },
+			...(passFindings.length > 0 ? { findings: passFindings } : {}),
+		};
 	}
 	if (!Array.isArray(raw.findings) || raw.findings.length === 0) throw new Error("rework verdict findings are invalid");
 	if (raw.approval !== undefined && raw.approval !== null) throw new Error("rework verdict must omit approval");
-	const findings = raw.findings.map((item, index) => {
+	const findings = parseVerdictFindings(raw.findings, snapshot);
+	return { contract: "assurance_kernel/assurance_verdict/v2", role: snapshot.role, task_id: snapshot.task_id, snapshot_digest: snapshotDigest(snapshot), decision: "rework", findings };
+}
+
+/**
+ * Parse one verdict's findings. Review findings carry evidence and derive their
+ * anchor here so a capability minted for one anchor set cannot be spent on
+ * another; QA findings stay identifier-only.
+ */
+function parseVerdictFindings(rawFindings: unknown[], snapshot: SnapshotDescriptor) {
+	return rawFindings.map((item, index) => {
 		const finding = item as Record<string, unknown>;
 		const allowedFindingKeys =
 			snapshot.role === "review"
@@ -458,7 +537,57 @@ export function parseAssuranceVerdict(input: unknown, snapshot: SnapshotDescript
 			findings_digest: findingsDigest([normalized]),
 		};
 	});
-	return { contract: "assurance_kernel/assurance_verdict/v2", role: snapshot.role, task_id: snapshot.task_id, snapshot_digest: snapshotDigest(snapshot), decision: "rework", findings };
+}
+
+/**
+ * The five snapshot fields one Review reservation binds. A reservation is only
+ * reusable while all five still match the live projection; each call site adds
+ * its own conditions on top of this comparison.
+ */
+export interface ReservationSnapshot {
+	record_revision: string;
+	workspace_revision: string;
+	intent_revision: number;
+	intent_content_hash: string;
+	diff_hash: string;
+}
+
+/**
+ * Field names where the reserved snapshot differs from the live projection;
+ * an empty result is an exact match on all five. BR-DEC-06 keeps the five
+ * fields distinct, so this compares each one instead of a merged digest.
+ */
+export function compareReservationSnapshot(
+	snapshot: ReservationSnapshot,
+	current: ReservationSnapshot,
+): string[] {
+	const fields: Array<keyof ReservationSnapshot> = [
+		"record_revision",
+		"workspace_revision",
+		"intent_revision",
+		"intent_content_hash",
+		"diff_hash",
+	];
+	return fields.filter((field) => snapshot[field] !== current[field]);
+}
+
+/**
+ * `advance()`'s complete Review-ready predicate: claim identity, an active task
+ * still awaiting Review, and an exactly matching reservation snapshot. The
+ * release-on-mismatch cleanup that follows stays with the caller, because it is
+ * a side effect rather than part of this pure decision.
+ */
+export function reservationStillValid(
+	reservation: { snapshot: ReservationSnapshot } | undefined,
+	projection: AssuranceProjectionResult,
+	taskId: string,
+): boolean {
+	if (projection.error) return false;
+	if (projection.claim?.task_id !== taskId) return false;
+	const current = projection.projection;
+	if (current.lifecycle !== "active" || current.next_obligation !== "run_review") return false;
+	if (!reservation) return false;
+	return compareReservationSnapshot(reservation.snapshot, current).length === 0;
 }
 
 interface ReviewReservation {
@@ -544,17 +673,7 @@ export class AssuranceCoordinator {
 			} catch (error) {
 				return { state: "blocked", reason: `cannot validate Review reservation: ${boundedAssuranceError(error)}` };
 			}
-			const current = projection.projection;
-			const matches = !projection.error
-				&& projection.claim?.task_id === taskId
-				&& current.lifecycle === "active"
-				&& current.next_obligation === "run_review"
-				&& reservation !== undefined
-				&& reservation.snapshot.record_revision === current.record_revision
-				&& reservation.snapshot.workspace_revision === current.workspace_revision
-				&& reservation.snapshot.intent_revision === current.intent_revision
-				&& reservation.snapshot.intent_content_hash === current.intent_content_hash
-				&& reservation.snapshot.diff_hash === current.diff_hash;
+			const matches = reservationStillValid(reservation, projection, taskId);
 			if (matches) return this.reviewReadyResult(taskId);
 			if (reservation) this.releaseReviewReservation(taskId, reservation);
 			this.rejectedReviewOperations.delete(taskId);
@@ -579,6 +698,8 @@ export class AssuranceCoordinator {
 		// nothing instead of being reported as an unknown settlement.
 		let boundaryBaseline: string | null = null;
 		let reviewPreparationStarted = false;
+		// Set only by the QA job-budget deadline, which is not a host cancellation.
+		let qaJobBudgetExceeded = false;
 		let phase = "preparing";
 		const operationLive = () => this.sessionActive
 			&& this.sessionGeneration === operationGeneration
@@ -592,6 +713,14 @@ export class AssuranceCoordinator {
 			onUpdate?.({ content: [{ type: "text", text: summary }], details: { state: "running", operation: "qa", operation_id: operationId, stage, ...details } });
 		};
 		const aborted = () => operationController.signal.aborted;
+		// A declared job budget past the ceiling is refused here, before any
+		// preparation command runs or any snapshot is captured.
+		const qaBudgetFailure = () => ({
+			state: "failed" as const,
+			operation: "qa" as const,
+			operation_id: operationId,
+			reason: `${phase}: deterministic QA exceeded its declared job budget before settlement`,
+		});
 		try {
 			ensureOperationLive();
 			progress(phase, `Preparing deterministic QA for ${taskId}`);
@@ -621,7 +750,7 @@ export class AssuranceCoordinator {
 			if (projection.projection.lifecycle === "active") this.unknownOperations.delete(taskId);
 			const parked = await this.ports.readTaskRecord(ctx.cwd, taskId);
 			ensureOperationLive();
-			if (parked.record?.findings.some((finding) => finding.kind === "replan_required" && finding.status === "open")) return { state: "blocked", reason: "review rework limit reached; a durable replan is required" };
+			if (parked.record?.findings.some((finding) => finding.kind === "replan_required" && finding.status === "open")) return { state: "blocked", reason: "review requires a durable replan; the task is paused for a user decision" };
 			if (projection.projection.artifact_state === "active") {
 				if (projection.projection.next_obligation !== "submit_assurance")
 					return { state: "blocked", reason: `Kernel requires ${projection.projection.next_obligation}` };
@@ -657,7 +786,6 @@ export class AssuranceCoordinator {
 				return { state: "blocked", reason: `Kernel requires ${projection.projection.next_obligation}` };
 			const qaAlreadySettled = projection.projection.next_obligation === "run_review";
 			if (qaAlreadySettled) reviewPreparationStarted = true;
-			const runner = await this.ports.frozenRunner();
 			ensureOperationLive();
 			// Prove the immutable Review revision before any descriptor runs. A task
 			// that cannot publish its revision must stop with zero QA attestation
@@ -682,18 +810,31 @@ export class AssuranceCoordinator {
 				progress("capturing_snapshot", "Capturing the immutable QA snapshot");
 				await this.ports.qaBeforeProjection?.();
 				ensureOperationLive();
-				const assurance = await this.ports.buildAssurance(ctx.cwd, taskId, "qa", projection, runner);
+				const assurance = await this.ports.buildAssurance(ctx.cwd, taskId, "qa", projection);
 				ensureOperationLive();
-				qaVerdict = await this.ports.runQa(assurance.snapshot, assurance.descriptors, runner, {
-					signal: operationController.signal,
-					onProgress: (item) => progress("verifying", `QA ${item.index}/${item.total} ${item.acceptance_id} ${item.phase}`, {
-						current: item.index,
-						total: item.total,
-						acceptance_id: item.acceptance_id,
-						acceptance_phase: item.phase,
-						elapsed_ms: item.elapsed_ms,
-					}),
-				});
+				// Preparation counts against the same ceiling as the checks, so the
+				// aggregate clock starts before the first prepared group runs. A host
+				// may only tighten the derived budget, never raise it past the ceiling.
+				const declaredQaJobMs = deriveQaJobTimeoutMs(assurance.descriptors.values());
+				const qaJobTimeoutMs = Math.min(declaredQaJobMs, this.ports.qaJobTimeoutMs ?? declaredQaJobMs);
+				const qaJobDeadline = setTimeout(() => {
+					qaJobBudgetExceeded = true;
+					operationController.abort(new Error(`deterministic QA exceeded its declared ${Math.ceil(qaJobTimeoutMs / 60_000)} minute job budget`));
+				}, qaJobTimeoutMs);
+				try {
+					qaVerdict = await this.ports.runQa(assurance.snapshot, assurance.descriptors, {
+						signal: operationController.signal,
+						onProgress: (item) => progress("verifying", `QA ${item.index}/${item.total} ${item.acceptance_id} ${item.phase}`, {
+							current: item.index,
+							total: item.total,
+							acceptance_id: item.acceptance_id,
+							acceptance_phase: item.phase,
+							elapsed_ms: item.elapsed_ms,
+						}),
+					});
+				} finally {
+					clearTimeout(qaJobDeadline);
+				}
 				ensureOperationLive();
 				const invocation = this.openInvocation(taskId);
 				try {
@@ -722,6 +863,7 @@ export class AssuranceCoordinator {
 						authorityBoundaryStarted = false;
 					}
 				} catch (error) {
+					if (qaJobBudgetExceeded) return qaBudgetFailure();
 					if (!authorityCommitted && (aborted() || error instanceof VerificationAbortedError)) return this.cancelled("qa", operationId, "host cancellation before QA authority commit");
 					return authorityCommitted
 						? this.unknownAfterCommit(taskId, "qa", operationId, boundedAssuranceError(error))
@@ -764,7 +906,7 @@ export class AssuranceCoordinator {
 			let review: Awaited<ReturnType<AssuranceCoordinatorPorts["buildAssurance"]>>;
 			let evidence: { path: string; remove(): void };
 			try {
-				review = await this.ports.buildAssurance(ctx.cwd, taskId, "review", fresh, runner);
+				review = await this.ports.buildAssurance(ctx.cwd, taskId, "review", fresh);
 				const payload = review.reviewManifest ?? review.reviewBundle;
 				if (!payload) throw new Error("review evidence is missing after QA settlement");
 				evidence = this.ports.writeReviewEvidence({ snapshot: review.snapshot, evidence: payload });
@@ -826,6 +968,7 @@ export class AssuranceCoordinator {
 					return { state: "failed", operation: "qa", operation_id: operationId, reason: `${phase}: ${boundedAssuranceError(error)}` };
 				return this.unknownAfterCommit(taskId, "qa", operationId, `${phase}: ${boundedAssuranceError(error)}`);
 			}
+			if (qaJobBudgetExceeded) return qaBudgetFailure();
 			if (aborted() || error instanceof VerificationAbortedError) return this.cancelled("qa", operationId, `${phase}: host cancellation`);
 			return { state: "failed", operation: "qa", operation_id: operationId, reason: `${phase}: ${boundedAssuranceError(error)}` };
 		} finally {
@@ -851,7 +994,7 @@ export class AssuranceCoordinator {
 			this.releaseReviewReservation(taskId, reservation, reason);
 			return { state: "blocked", reason };
 		}
-		if (fresh.error || !fresh.claim || fresh.claim.task_id !== taskId || fresh.projection.record_revision !== reservation.snapshot.record_revision || fresh.projection.workspace_revision !== reservation.snapshot.workspace_revision || fresh.projection.intent_revision !== reservation.snapshot.intent_revision || fresh.projection.intent_content_hash !== reservation.snapshot.intent_content_hash || fresh.projection.diff_hash !== reservation.snapshot.diff_hash || fresh.projection.lifecycle !== reservation.snapshot.lifecycle || fresh.projection.artifact_state !== reservation.snapshot.artifact_state) {
+		if (fresh.error || !fresh.claim || fresh.claim.task_id !== taskId || compareReservationSnapshot(reservation.snapshot, fresh.projection).length > 0 || fresh.projection.lifecycle !== reservation.snapshot.lifecycle || fresh.projection.artifact_state !== reservation.snapshot.artifact_state) {
 			const reason = fresh.error ?? "assurance snapshot changed before Review submission";
 			this.releaseReviewReservation(taskId, reservation, reason);
 			return { state: "blocked", reason };

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

@@ -0,0 +1,240 @@
+// Disposable QA materialization of one immutable delivery tree.
+// Never binds the user's index, refs, or node_modules.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+
+import type { GitTaskRevisionSnapshot } from "../workspace_scope";
+
+export class DeliveryWorkspaceError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "DeliveryWorkspaceError";
+	}
+}
+
+export interface DeliveryWorkspace {
+	root: string;
+	tree: string;
+	seal: string;
+	cleanup: () => void;
+}
+
+export function removeTaskOwnedTree(root: string): void {
+	const makeDirectoriesWritable = (path: string): void => {
+		let stat;
+		try { stat = lstatSync(path); }
+		catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return; throw error; }
+		if (!stat.isDirectory() || stat.isSymbolicLink()) return;
+		chmodSync(path, (stat.mode & 0o7777) | 0o700);
+		for (const name of readdirSync(path)) makeDirectoriesWritable(join(path, name));
+	};
+	makeDirectoriesWritable(root);
+	rmSync(root, { recursive: true, force: true });
+}
+
+const GIT_OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+
+function isolatedGitEnv(extra: Record<string, string> = {}): NodeJS.ProcessEnv {
+	const env = { ...process.env };
+	delete env.GIT_DIR;
+	delete env.GIT_WORK_TREE;
+	delete env.GIT_INDEX_FILE;
+	delete env.GIT_OBJECT_DIRECTORY;
+	delete env.GIT_ALTERNATE_OBJECT_DIRECTORIES;
+	return {
+		...env,
+		GIT_CONFIG_NOSYSTEM: "1",
+		GIT_TERMINAL_PROMPT: "0",
+		GIT_OPTIONAL_LOCKS: "0",
+		...extra,
+	};
+}
+
+function git(cwd: string, args: string[], extra: Record<string, string> = {}): string {
+	return execFileSync("git", args, {
+		cwd,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+		env: isolatedGitEnv(extra),
+	}).trim();
+}
+
+function assertTree(tree: string): void {
+	if (!GIT_OBJECT_ID.test(tree)) throw new DeliveryWorkspaceError("delivery tree has invalid identity");
+}
+
+function assertInside(root: string, candidate: string, label: string): void {
+	const rel = relative(root, candidate);
+	if (rel.startsWith(`..${sep}`) || rel === ".." || isAbsolute(rel))
+		throw new DeliveryWorkspaceError(`delivery ${label} escapes materialization: ${rel}`);
+}
+
+function resolvedSymlinkTarget(path: string): string {
+	const target = readlinkSync(path);
+	let current = isAbsolute(target) ? parse(target).root : parse(path).root;
+	let pending = (isAbsolute(target)
+		? target.split(sep)
+		: [...relative(current, dirname(path)).split(sep), ...target.split(sep)]
+	).filter(Boolean);
+	let links = 0;
+	while (pending.length) {
+		const part = pending.shift()!;
+		if (part === ".") continue;
+		if (part === "..") { current = dirname(current); continue; }
+		const next = join(current, part);
+		try {
+			if (!lstatSync(next).isSymbolicLink()) { current = next; continue; }
+			if (++links > 40) throw new DeliveryWorkspaceError("delivery symlink chain is too deep");
+			const nested = readlinkSync(next);
+			if (isAbsolute(nested)) current = parse(nested).root;
+			pending = [...nested.split(sep).filter(Boolean), ...pending];
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			current = next;
+		}
+	}
+	return current;
+}
+
+function assertNoEscapingSymlinks(root: string, dir = root): void {
+	const realRoot = realpathSync(root);
+	for (const name of readdirSync(dir)) {
+		const path = join(dir, name);
+		const stat = lstatSync(path);
+		if (stat.isSymbolicLink()) {
+			assertInside(realRoot, resolvedSymlinkTarget(path), `symlink ${relative(root, path)}`);
+		} else if (stat.isDirectory()) {
+			assertNoEscapingSymlinks(root, path);
+		}
+	}
+}
+
+
+export function writeDeliveryTree(sourceRoot: string, snapshot: GitTaskRevisionSnapshot): string {
+	const indexDirectory = mkdtempSync(join(tmpdir(), "imm-delivery-index-"));
+	try {
+		git(sourceRoot, ["read-tree", snapshot.base_tree], {
+			GIT_INDEX_FILE: join(indexDirectory, "index"),
+			GIT_DIR: join(sourceRoot, ".git"),
+		});
+		for (const [path, entry] of Object.entries(snapshot.changed_paths)) {
+			if (entry.oid && entry.mode) {
+				git(sourceRoot, ["update-index", "--add", "--cacheinfo", `${entry.mode},${entry.oid},${path}`], {
+					GIT_INDEX_FILE: join(indexDirectory, "index"),
+					GIT_DIR: join(sourceRoot, ".git"),
+				});
+			} else {
+				git(sourceRoot, ["update-index", "--force-remove", "--", path], {
+					GIT_INDEX_FILE: join(indexDirectory, "index"),
+					GIT_DIR: join(sourceRoot, ".git"),
+				});
+			}
+		}
+		const next = git(sourceRoot, ["write-tree"], {
+			GIT_INDEX_FILE: join(indexDirectory, "index"),
+			GIT_DIR: join(sourceRoot, ".git"),
+		});
+		assertTree(next);
+		return next;
+	} finally {
+		rmSync(indexDirectory, { recursive: true, force: true });
+	}
+}
+
+// The seal lives in host memory, outside the project. Compare bytes directly:
+// project commands can rewrite their disposable index or porcelain state.
+function workspaceFiles(
+	root: string,
+	dir = root,
+	result: Record<string, string> = Object.create(null) as Record<string, string>,
+): Record<string, string> {
+	if (dir === root) result["."] = `${lstatSync(root).mode & 0o7777}:directory`;
+	for (const name of readdirSync(dir).sort()) {
+		const path = join(dir, name), rel = relative(root, path);
+		const stat = lstatSync(path);
+		if (stat.isSymbolicLink()) result[rel] = `link:${stat.mode & 0o7777}:${readlinkSync(path)}`;
+		else if (stat.isDirectory()) { result[rel] = `${stat.mode & 0o7777}:directory`; workspaceFiles(root, path, result); }
+		else if (stat.isFile()) result[rel] = `${stat.mode & 0o7777}:${createHash("sha256").update(readFileSync(path)).digest("hex")}`;
+		else throw new DeliveryWorkspaceError("delivery contains an unsupported filesystem entry");
+	}
+	return result;
+}
+
+function workspaceSeal(root: string): string {
+	return JSON.stringify(workspaceFiles(root));
+}
+
+export function assertDeliveryClean(root: string, tree: string, seal?: string, writablePaths: string[] = []): void {
+	assertTree(tree);
+	if (seal === undefined) {
+		if (git(root, ["status", "--porcelain", "--untracked-files=all", "--ignored=matching"]))
+			throw new DeliveryWorkspaceError("delivery workspace was contaminated");
+		if (git(root, ["rev-parse", "HEAD^{tree}"]) !== tree)
+			throw new DeliveryWorkspaceError("delivery workspace tree drifted from the frozen identity");
+		return;
+	}
+	if (seal === "[]") {
+		for (const name of readdirSync(root)) {
+			const stat = lstatSync(join(root, name));
+			if (!stat.isDirectory() || name !== ".git") throw new DeliveryWorkspaceError("delivery workspace was contaminated");
+		}
+		return;
+	}
+	const expected = JSON.parse(seal) as Record<string, string>;
+	for (const path of writablePaths) {
+		if (path === "." || path === ".git" || path.startsWith(".git/") || isAbsolute(path) || path.split("/").includes("..")
+			|| Object.keys(expected).some(p => p === path || p.startsWith(`${path}/`)))
+			throw new DeliveryWorkspaceError("delivery writable path overlaps protected inputs");
+	}
+	const current = workspaceFiles(root);
+	for (const [path, bytes] of Object.entries(expected))
+		if (current[path] !== bytes) throw new DeliveryWorkspaceError("delivery protected input was contaminated");
+	for (const [path, bytes] of Object.entries(current)) {
+		if (Object.hasOwn(expected, path)) continue;
+		const permitted = writablePaths.some(p => path === p || path.startsWith(`${p}/`)
+			|| (bytes.endsWith(":directory") && p.startsWith(`${path}/`)));
+		if (!permitted) throw new DeliveryWorkspaceError("delivery undeclared output was contaminated");
+		if (bytes.startsWith("link:")) {
+			assertInside(realpathSync(root), resolvedSymlinkTarget(join(root, path)), "generated symlink");
+		}
+	}
+}
+
+
+export function materializeDeliveryWorkspace(
+	sourceRoot: string,
+	tree: string,
+): DeliveryWorkspace {
+	assertTree(tree);
+	const dest = mkdtempSync(join(tmpdir(), "imm-delivery-"));
+	const cleanup = () => removeTaskOwnedTree(dest);
+	try {
+		mkdirSync(dest, { recursive: true });
+		const commit = git(sourceRoot, ["commit-tree", tree, "-m", `delivery ${tree}`], {
+			GIT_DIR: join(sourceRoot, ".git"),
+			GIT_AUTHOR_NAME: "Immune-Brain Assurance",
+			GIT_AUTHOR_EMAIL: "assurance@immune-brain.local",
+			GIT_AUTHOR_DATE: "1970-01-01T00:00:00 +0000",
+			GIT_COMMITTER_NAME: "Immune-Brain Assurance",
+			GIT_COMMITTER_EMAIL: "assurance@immune-brain.local",
+			GIT_COMMITTER_DATE: "1970-01-01T00:00:00 +0000",
+		});
+		if (!GIT_OBJECT_ID.test(commit)) throw new DeliveryWorkspaceError("delivery commit write failed");
+		git(dest, ["init", "-q"]);
+		git(dest, ["fetch", "--depth=1", `file://${resolve(sourceRoot)}`, `${commit}:refs/heads/delivery`]);
+		git(dest, ["checkout", "-q", "delivery"]);
+		const got = git(dest, ["rev-parse", "HEAD^{tree}"]);
+		if (got !== tree) throw new DeliveryWorkspaceError("delivery materialization does not match the frozen tree");
+		assertNoEscapingSymlinks(dest);
+		const seal = workspaceSeal(dest);
+		assertDeliveryClean(dest, tree, seal);
+		return { root: dest, tree, seal, cleanup };
+	} catch (error) {
+		cleanup();
+		throw error;
+	}
+}