immune-brain 3.6.9 → 4.0.0

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

@@ -0,0 +1,189 @@
+// One frozen table is the only producer of batch-gate reason and recovery prose.
+// Both Host adapters render from it, so a condition reads identically on either
+// Host by construction rather than because two copies still agree. The table is
+// Host-neutral: it names no Host, no SDK, and no transport.
+//
+// Deliberately NOT in this table: a Host's own transport prose, which names that
+// Host's interaction form — Pi's interactive-TUI refusal and its missing-port
+// message, Claude's MCP elicitation refusal — and a transport error's own
+// `message`/`recoveryAction`, which the transport owns. Those stay in the
+// adapter that owns the transport.
+
+export type BatchReasonKey =
+	| "invalid_slug"
+	| "batch_state_unreadable"
+	| "claim_already_active"
+	| "git_head_unreadable"
+	| "branch_already_exists"
+	| "git_status_unreadable"
+	| "working_tree_dirty"
+	| "authorized_scope_underivable"
+	| "working_tree_unstaged"
+	| "working_tree_out_of_scope"
+	| "empty_enrollable_set"
+	| "plan_projection_failed"
+	| "confirmation_port_unavailable"
+	| "confirmation_timed_out"
+	| "confirmation_cancelled"
+	| "confirmation_declined"
+	| "confirmation_no_decision"
+	| "confirmation_failed"
+	| "claim_appeared_during_confirmation"
+	| "plan_became_unreadable"
+	| "plan_changed"
+	| "repository_became_unreadable"
+	| "head_moved"
+	| "cancelled_before_execution"
+	| "batch_run_rejected";
+
+export interface BatchReasonSpec {
+	readonly state: "rejected" | "cancelled" | "blocked";
+	/** A fixed sentence, or a template given the condition's own detail. */
+	readonly reason: string | ((detail: string) => string);
+	readonly recovery_action: string;
+}
+
+export const BATCH_REASONS: Readonly<Record<BatchReasonKey, BatchReasonSpec>> = Object.freeze({
+	invalid_slug: {
+		state: "rejected",
+		reason: (detail: string) => `invalid initiative slug: ${detail}`,
+		recovery_action: "specify a valid initiative slug and retry in the current Host",
+	},
+	batch_state_unreadable: {
+		state: "blocked",
+		reason: (detail: string) => `batch run state is unreadable or invalid: ${detail}`,
+		recovery_action: "resolve or remove the invalid batch state file, then retry in the current Host",
+	},
+	claim_already_active: {
+		state: "blocked",
+		reason: (detail: string) => `an active workspace claim already exists for task: ${detail}`,
+		recovery_action: "resolve or stop the active task before starting a batch in the current Host",
+	},
+	git_head_unreadable: {
+		state: "rejected",
+		reason: (detail: string) => detail,
+		recovery_action: "commit working changes and ensure a committed Git HEAD exists in the current Host",
+	},
+	branch_already_exists: {
+		state: "rejected",
+		reason: (detail: string) => `branch preflight failed: branch refs/heads/${detail} already exists`,
+		recovery_action: "delete or rename the conflicting branch, or commit working changes in the current Host",
+	},
+	git_status_unreadable: {
+		state: "rejected",
+		reason: "branch preflight failed: git status is unreadable",
+		recovery_action: "check the repository integrity and retry in the current Host",
+	},
+	working_tree_dirty: {
+		state: "rejected",
+		reason: "branch preflight failed: working tree is dirty",
+		recovery_action: "delete or rename the conflicting branch, or commit working changes in the current Host",
+	},
+	authorized_scope_underivable: {
+		state: "rejected",
+		reason: "branch preflight failed: cannot derive the in-flight child's authorized scope",
+		recovery_action: "resolve the child's intent record, then retry in the current Host",
+	},
+	working_tree_unstaged: {
+		state: "rejected",
+		reason: "branch preflight failed: working tree has unstaged or untracked changes",
+		recovery_action: "stage the in-flight changes with git add, then retry in the current Host",
+	},
+	working_tree_out_of_scope: {
+		state: "rejected",
+		reason: "branch preflight failed: working tree has changes outside the authorized child scope",
+		recovery_action: "commit or unstage changes outside the active task scope, then retry in the current Host",
+	},
+	empty_enrollable_set: {
+		state: "rejected",
+		reason: "empty enrollable child set: no enrollable child tasks found in the initiative plan",
+		recovery_action: "ensure the initiative has uncompleted, non-critical child tasks in the current Host",
+	},
+	plan_projection_failed: {
+		state: "rejected",
+		reason: (detail: string) => `failed to project batch plan: ${detail}`,
+		recovery_action: "review initiative issues and planning sidecars in the current Host",
+	},
+	confirmation_port_unavailable: {
+		state: "rejected",
+		reason: "native confirmation port is unavailable",
+		recovery_action: "retry through a fresh native gate in the current Host",
+	},
+	confirmation_timed_out: {
+		state: "rejected",
+		reason: "native confirmation timed out waiting for user interaction",
+		recovery_action: "retry through a fresh native gate in the current Host",
+	},
+	confirmation_cancelled: {
+		state: "cancelled",
+		reason: "native interaction cancelled",
+		recovery_action: "wait for a fresh literal-user request",
+	},
+	confirmation_declined: {
+		state: "rejected",
+		reason: "native interaction declined",
+		recovery_action: "wait for a fresh literal-user request",
+	},
+	confirmation_no_decision: {
+		state: "rejected",
+		reason: "native interaction returned no decision",
+		recovery_action: "retry through a fresh native gate in the current Host",
+	},
+	confirmation_failed: {
+		state: "rejected",
+		reason: (detail: string) => detail,
+		recovery_action: "retry through a fresh native gate in the current Host",
+	},
+	claim_appeared_during_confirmation: {
+		state: "blocked",
+		reason: (detail: string) => `an active workspace claim appeared during confirmation for task: ${detail}`,
+		recovery_action: "resolve or stop the active task before starting a batch in the current Host",
+	},
+	plan_became_unreadable: {
+		state: "rejected",
+		reason: "batch plan became unreadable after native confirmation",
+		recovery_action: "review the current workspace and retry through a fresh native gate in the current Host",
+	},
+	plan_changed: {
+		state: "rejected",
+		reason: "batch plan changed after native confirmation",
+		recovery_action: "review the current workspace and retry through a fresh native gate in the current Host",
+	},
+	repository_became_unreadable: {
+		state: "rejected",
+		reason: "Git repository became unreadable after native confirmation",
+		recovery_action: "review the current workspace and retry through a fresh native gate in the current Host",
+	},
+	head_moved: {
+		state: "rejected",
+		reason: "Git HEAD moved after native confirmation",
+		recovery_action: "review the current workspace and retry through a fresh native gate in the current Host",
+	},
+	cancelled_before_execution: {
+		state: "cancelled",
+		reason: "user cancelled before batch execution",
+		recovery_action: "wait for a fresh literal-user request",
+	},
+	batch_run_rejected: {
+		state: "rejected",
+		// The runner owns the specific reason; the fallback is this entry's own text.
+		reason: (detail: string) => detail || "batch run rejected",
+		recovery_action: "delete or rename the conflicting branch, or commit working changes and retry in the current Host",
+	},
+});
+
+export interface BatchReason {
+	state: "rejected" | "cancelled" | "blocked";
+	reason: string;
+	recovery_action: string;
+}
+
+/** Resolve one key into the envelope fields both Hosts return. */
+export function batchReason(key: BatchReasonKey, detail = ""): BatchReason {
+	const spec = BATCH_REASONS[key];
+	return {
+		state: spec.state,
+		reason: typeof spec.reason === "function" ? spec.reason(detail) : spec.reason,
+		recovery_action: spec.recovery_action,
+	};
+}

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

@@ -377,6 +377,41 @@ function validateRunAuthorization(input: StartBatchInput, existing: BatchRunStat
 }
 
 export async function startBatch(input: StartBatchInput): Promise<BatchRunReport> {
+	try {
+		return await startBatchLocked(input);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (!/retired file-store|kernel store|CAS mismatch|store is busy|locked/i.test(message))
+			throw error;
+		// A store condition the run cannot resolve stops the batch with one
+		// explicit recovery action instead of escaping as an unstructured crash.
+		// The rejected report keeps whatever this batch already persisted — a run
+		// resumed after partial progress reports its children and commits rather
+		// than an empty plan — and only a batch with no durable state reports the
+		// empty plan it validated.
+		return rejectionReport(input, message);
+	}
+}
+
+function rejectionReport(input: StartBatchInput, reason: string): BatchRunReport {
+	const persisted = (() => {
+		try {
+			return readBatchRunState(input.root, input.batch_id);
+		} catch {
+			return null;
+		}
+	})();
+	return reportFor(
+		{
+			...(persisted ?? prepareBatchRunState({ ...input, children: [], now: input.now })),
+			batch_state: "rejected",
+		},
+		reason,
+		"settle the reported kernel store condition and retry in the current Host",
+	);
+}
+
+async function startBatchLocked(input: StartBatchInput): Promise<BatchRunReport> {
 	// Validation failure before the first enrollment: zero writes, rejected.
 	// reportFor only builds the report object; finalize would persist it and
 	// the spec forbids any write on a pre-enrollment rejection.

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

@@ -0,0 +1,33 @@
+// A native confirmation is bounded on both Hosts. Claude bounded its MCP
+// elicitation with IMMUNE_BRAIN_BATCH_TIMEOUT_MS and Pi waited indefinitely; the
+// bound, its default, and the "this deadline expired rather than the user
+// cancelling" distinction are shared here. Each Host still owns its transport:
+// this module only produces the signal to hand it and reports expiry.
+
+export const CONFIRMATION_TIMEOUT_DEFAULT_MS = 60_000;
+export const CONFIRMATION_TIMEOUT_ENV = "IMMUNE_BRAIN_BATCH_TIMEOUT_MS";
+
+export interface ConfirmationDeadline {
+	/** The caller's signal, combined with this deadline. */
+	signal: AbortSignal;
+	/** True when this deadline fired and the caller's own signal did not. */
+	timedOut(): boolean;
+	clear(): void;
+}
+
+export function startConfirmationDeadline(input: {
+	env?: Record<string, string | undefined>;
+	signal?: AbortSignal;
+}): ConfirmationDeadline {
+	const configured = Number(input.env?.[CONFIRMATION_TIMEOUT_ENV]);
+	const timeoutMs = Number.isFinite(configured) && configured > 0 ? configured : CONFIRMATION_TIMEOUT_DEFAULT_MS;
+	const controller = new AbortController();
+	const timer = setTimeout(() => {
+		controller.abort(new Error("native confirmation timed out waiting for user interaction"));
+	}, timeoutMs);
+	return {
+		signal: input.signal ? AbortSignal.any([input.signal, controller.signal]) : controller.signal,
+		timedOut: () => controller.signal.aborted && !input.signal?.aborted,
+		clear: () => clearTimeout(timer),
+	};
+}

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

@@ -27,12 +27,25 @@ export type BatchPlanChildStatus =
 	| "needs_human"
 	| "blocked";
 
+/**
+ * Stable per-child exclusion reasons a Host renders verbatim. The Spec-binding
+ * reasons mirror the shared enrollment precondition, and the incomplete form
+ * names every path the TaskIntent has to add.
+ */
+export type BatchPlanChildReason =
+	| "critical"
+	| "invalid_intent"
+	| "dependency_unavailable"
+	| "spec_binding_missing"
+	| "spec_binding_ambiguous"
+	| `spec_binding_incomplete: ${string}`;
+
 export interface BatchPlanChild {
 	task_id: string;
 	slice_id: string;
 	blocked_by: string[];
 	status: BatchPlanChildStatus;
-	reason: "critical" | "invalid_intent" | "dependency_unavailable" | null;
+	reason: BatchPlanChildReason | null;
 	intent_path: string | null;
 	intent_revision: number | null;
 	intent_content_hash: string | null;

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

@@ -10,8 +10,12 @@
  *   - `imm-plan --routing-status --json` (strict Git-owned route projection)
  *   - `imm-plan <plan-path> [--json]` (read-only Plan validation)
  *   - `imm-tracker` (opt-in, one-way, non-authoritative GitHub Issue projection)
- *   - a stable `drain_required` / `v3_storage_retired` wall for every v3
- *     mutating command (work/review/migrate/finish/autowork/heal/...).
+ *
+ * Every retired v3 mutating command (`imm-work`, `imm-review`, `imm-migrate`,
+ * `imm-finish`, `imm-autowork`, `imm-heal`, `imm-check-child-output`,
+ * `imm-retire-stale-wrapper`) and its `bin/` wrapper is fully removed: the name
+ * falls through to the generic unknown-command response instead of a
+ * per-command diagnostic. Only the retired *option* wall on `imm-plan` remains.
  *
  * v3 State Ledger mutations, migrations, authority receipts, automatic
  * observations, and TaskRecord v1 writers are NOT reachable from any shipped
@@ -33,21 +37,8 @@ import {
 } from "./plan_core";
 import { runGithubTrackerCli } from "./github_issue_tracker";
 
-// Retired v3 mutating command wall. Read-only v3 commands that only project
-// state (imm-plan validate) stay available; every writer is retired.
-const RETIRED_MUTATING_COMMANDS = new Set([
-	"imm-work",
-	"imm-review",
-	"imm-migrate",
-	"imm-finish",
-	"imm-autowork",
-	"imm-heal",
-	"imm-check-child-output",
-	"imm-retire-stale-wrapper",
-]);
-
-const READ_ONLY_V3_COMMANDS = new Set(["imm-plan"]);
-
+// The retired *option* wall on imm-plan: the command stays available for
+// read-only validation, while its v3 mutating options keep this rejection.
 const RETIRED_PLAN_OPTIONS = new Set([
 	"--sync",
 	"--terminate-current",
@@ -85,7 +76,10 @@ function unavailableRoutingProjection(): RoutingPolicyProjection {
 	};
 }
 
-function retiredResponse(command: string, args: string[], root: string): {
+// The read-only v3 option wall: retired plan options keep this exact
+// rejection, so the message shape is deliberately not a parameter of the
+// caller's option name or arguments.
+function retiredPlanOptionResponse(root: string): {
 	stdout: string;
 	stderr: string;
 	returncode: number;
@@ -124,7 +118,7 @@ function runPlanCli(args: string[], root: string): {
 	stderr: string;
 	returncode: number;
 } {
-	if (hasRetiredPlanOption(args)) return retiredResponse("imm-plan", args, root);
+	if (hasRetiredPlanOption(args)) return retiredPlanOptionResponse(root);
 	if (
 		args.length === 2 &&
 		args[0] === "--routing-status" &&
@@ -182,6 +176,10 @@ async function runKernelCli(args: string[], root: string): Promise<{
 	// status --json, and the explicit audit command. All other kernel
 	// subcommands (readiness, journal, migrate) are retired.
 	const sub = args[0] ?? "";
+	// The explicit claimless storage-layout migration is reachable here: a
+	// worktree still on the retired file store has no other entry point, and
+	// every mutating subcommand stays fail-closed behind it.
+	if (sub === "migrate") return runKernelCommand(args, root);
 	if (sub === "intent") return runKernelCommand(args, root);
 	if (sub === "status" && args.includes("--json")) return runKernelCommand(args, root);
 	if (sub === "inspect" && args.includes("--json")) return runKernelCommand(args, root);
@@ -206,7 +204,7 @@ async function runKernelCli(args: string[], root: string): Promise<{
 	}
 	return {
 		stdout: "",
-		stderr: "invalid_kernel_command: imm-kernel supports intent author|validate, status --json, inspect --json, and audit --legacy only\n",
+		stderr: "invalid_kernel_command: imm-kernel supports intent author|validate, migrate --storage-layout, status --json, inspect --json, and audit --legacy only\n",
 		returncode: 2,
 	};
 }
@@ -219,7 +217,6 @@ async function runCli(command: string, args: string[], root: string): Promise<{
 	if (command === "imm-kernel") return runKernelCli(args, root);
 	if (command === "imm-plan") return runPlanCli(args, root);
 	if (command === "imm-tracker") return runGithubTrackerCli(args, root);
-	if (RETIRED_MUTATING_COMMANDS.has(command)) return retiredResponse(command, args, root);
 	return {
 		stdout: "",
 		stderr: `Unknown Immune-Brain v4 command: ${command}\n`,
@@ -268,7 +265,6 @@ async function main(argv: string[]): Promise<number> {
 							],
 						},
 					],
-					retired: [...RETIRED_MUTATING_COMMANDS].sort(),
 				},
 				null,
 				2,
@@ -294,4 +290,4 @@ if (fileURLToPath(import.meta.url) === process.argv[1]) {
 	process.exit(code);
 }
 
-export { main, runCli, runKernelCli, runGithubTrackerCli, RETIRED_MUTATING_COMMANDS };
+export { main, runCli, runKernelCli, runGithubTrackerCli };

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

@@ -1,50 +1,34 @@
-// Shared verification_descriptor/v1 pure parser.
-//
-// The complete `acceptance[].verification` string of a TaskIntent is accepted
-// only as strict canonical JSON for `assurance_kernel/verification_descriptor/v1`.
-// Never execute free text, an executable path, a shell string, PATH lookup,
-// environment overrides, or a cwd outside the repository. The production runner
-// registry contains only the host-resolved `bun` runner.
-//
-// This module is the single parser implementation for the wire contract. Pi
-// assurance (`.pi-extension/pi-canary-verification.ts`) re-exports it and keeps
-// runner resolution/execution extension-owned. Kernel intent author/validate
-// consume the same implementation, so the two consumers cannot drift.
-//
-// JSON whitespace and key ordering are NOT eligibility conditions: parsing is
-// whitespace/order-insensitive. `canonicalDescriptorBytes` produces the
-// deterministic bytes that Planner authoring binds.
+// One host-neutral parser for project-owned verification. Historical TaskRecords
+// retain their verification strings; only v2 descriptors are executable.
+import { isAbsolute } from "node:path";
 
-import { isAbsolute, sep } from "node:path";
-
-export const VERIFICATION_DESCRIPTOR_CONTRACT =
-	"assurance_kernel/verification_descriptor/v1" as const;
+export const VERIFICATION_DESCRIPTOR_CONTRACT = "assurance_kernel/verification_descriptor/v2" as const;
+export const VERIFICATION_DESCRIPTOR_BOUNDS = {
+	max_arg_tokens: 64,
+	max_arg_token_bytes: 512,
+	max_cwd_depth: 32,
+	max_timeout_ms: 600_000,
+	max_output_bytes: 262_144,
+	max_descriptor_bytes: 65_536,
+	max_writable_paths: 32,
+} as const;
 
-export interface VerificationDescriptor {
-	contract: typeof VERIFICATION_DESCRIPTOR_CONTRACT;
-	runner_id: "bun";
-	runner_version: string;
+export interface VerificationCommand {
+	executable: string;
 	argv: string[];
 	cwd: string;
 	timeout_ms: number;
 	max_output_bytes: number;
 }
-
-const DESCRIPTOR_FIELDS = [
-	"contract",
-	"runner_id",
-	"runner_version",
-	"argv",
-	"cwd",
-	"timeout_ms",
-	"max_output_bytes",
-] as const;
-
-const MAX_ARGV_TOKENS = 64;
-const MAX_ARGV_TOKEN_BYTES = 512;
-const MAX_CWD_DEPTH = 32;
-const MAX_TIMEOUT_MS = 600_000;
-const MAX_OUTPUT_BYTES = 262_144;
+export interface VerificationEnvironment {
+	prepare: VerificationCommand | null;
+	writable_paths: string[];
+}
+export interface VerificationDescriptor {
+	contract: typeof VERIFICATION_DESCRIPTOR_CONTRACT;
+	command: VerificationCommand;
+	environment: VerificationEnvironment;
+}
 
 export class VerificationDescriptorError extends Error {
 	constructor(message: string) {
@@ -53,110 +37,82 @@ export class VerificationDescriptorError extends Error {
 	}
 }
 
-/** Parse the complete verification string as strict canonical JSON. */
-export function parseVerificationDescriptor(text: string): VerificationDescriptor {
-	const trimmed = text.trim();
-	if (!trimmed) throw new VerificationDescriptorError("verification string is empty");
-	let raw: Record<string, unknown>;
-	try {
-		raw = JSON.parse(trimmed) as Record<string, unknown>;
-	} catch {
-		throw new VerificationDescriptorError("verification string is not valid JSON");
+function object(value: unknown, fields: readonly string[], label: string): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value))
+		throw new VerificationDescriptorError(`${label} must be an object`);
+	const raw = value as Record<string, unknown>;
+	if (Object.keys(raw).some(key => !fields.includes(key)))
+		throw new VerificationDescriptorError(`${label} has an unknown field`);
+	return raw;
+}
+
+export function verificationRelativePath(value: unknown, label: string): string {
+	if (typeof value !== "string" || !value || value.length > 512 || /[\x00-\x1f\x7f\\]/.test(value)
+		|| isAbsolute(value) || value.startsWith("~") || value.split("/").includes("..")
+		|| value.split("/").includes(".git") || value.split("/").length > VERIFICATION_DESCRIPTOR_BOUNDS.max_cwd_depth)
+		throw new VerificationDescriptorError(`${label} must stay inside the repository`);
+	return value.split("/").filter(part => part && part !== ".").join("/") || ".";
+}
+
+function bound(value: unknown, max: number, label: string): number {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > max)
+		throw new VerificationDescriptorError(`${label} exceeds the host bound`);
+	return value;
+}
+
+function command(value: unknown): VerificationCommand {
+	const raw = object(value, ["executable", "argv", "cwd", "timeout_ms", "max_output_bytes"], "verification command");
+	if (typeof raw.executable !== "string") throw new VerificationDescriptorError("verification executable is invalid");
+	let executable: string = raw.executable;
+	if (executable.startsWith("./")) {
+		const path = verificationRelativePath(executable, "verification executable");
+		if (path === ".") throw new VerificationDescriptorError("verification executable must be a file");
+		executable = `./${path}`;
+	} else if (!/^[A-Za-z0-9_][A-Za-z0-9_.+-]{0,127}$/.test(executable)) {
+		throw new VerificationDescriptorError("verification executable must be a host tool name or ./project-file");
+	}
+	if (!Array.isArray(raw.argv) || raw.argv.length > VERIFICATION_DESCRIPTOR_BOUNDS.max_arg_tokens)
+		throw new VerificationDescriptorError("verification argv must be a bounded array");
+	for (const arg of raw.argv) {
+		if (typeof arg !== "string" || Buffer.byteLength(arg) > VERIFICATION_DESCRIPTOR_BOUNDS.max_arg_token_bytes || /[\x00-\x1f\x7f]/.test(arg))
+			throw new VerificationDescriptorError("verification argv must contain bounded literal strings");
 	}
-	const unknown = Object.keys(raw).filter((key) => !DESCRIPTOR_FIELDS.includes(key as never));
-	if (unknown.length > 0)
-		throw new VerificationDescriptorError(`verification descriptor has unknown field: ${unknown[0]}`);
+	return {
+		executable,
+		argv: raw.argv as string[],
+		cwd: verificationRelativePath(raw.cwd, "verification cwd"),
+		timeout_ms: bound(raw.timeout_ms, VERIFICATION_DESCRIPTOR_BOUNDS.max_timeout_ms, "verification timeout_ms"),
+		max_output_bytes: bound(raw.max_output_bytes, VERIFICATION_DESCRIPTOR_BOUNDS.max_output_bytes, "verification max_output_bytes"),
+	};
+}
+
+export function parseVerificationDescriptor(text: string): VerificationDescriptor {
+	if (Buffer.byteLength(text) > VERIFICATION_DESCRIPTOR_BOUNDS.max_descriptor_bytes)
+		throw new VerificationDescriptorError("verification descriptor exceeds the byte bound");
+	let value: unknown;
+	try { value = JSON.parse(text); }
+	catch { throw new VerificationDescriptorError("verification string is not valid JSON"); }
+	if (value && typeof value === "object" && "contract" in value
+		&& value.contract === "assurance_kernel/verification_descriptor/v1")
+		throw new VerificationDescriptorError("verification_contract_migration_required: revise the verification definition to v2 before execution");
+	const raw = object(value, ["contract", "command", "environment"], "verification descriptor");
 	if (raw.contract !== VERIFICATION_DESCRIPTOR_CONTRACT)
 		throw new VerificationDescriptorError("verification descriptor contract is invalid");
-	if (raw.runner_id !== "bun")
-		throw new VerificationDescriptorError(
-			`verification runner must be bun; got ${String(raw.runner_id)}`,
-		);
-	if (typeof raw.runner_version !== "string" || !raw.runner_version.trim())
-		throw new VerificationDescriptorError("verification runner_version is invalid");
-	if (!Array.isArray(raw.argv) || raw.argv.length === 0)
-		throw new VerificationDescriptorError("verification argv must be a non-empty array");
-	if (raw.argv.length > MAX_ARGV_TOKENS)
-		throw new VerificationDescriptorError("verification argv exceeds the token bound");
-	for (const token of raw.argv) {
-		if (typeof token !== "string" || !token.trim())
-			throw new VerificationDescriptorError("verification argv tokens must be non-empty strings");
-		if (Buffer.byteLength(token) > MAX_ARGV_TOKEN_BYTES)
-			throw new VerificationDescriptorError("verification argv token exceeds the byte bound");
-		if (/[\x00-\x1f\x7f]/.test(token))
-			throw new VerificationDescriptorError("verification argv token contains control characters");
-		if (
-			token.includes("..") ||
-			token.includes("\\") ||
-			token.startsWith("/") ||
-			token.startsWith("~") ||
-			token.includes("$") ||
-			token.includes(";") ||
-			token.includes("&") ||
-			token.includes("|") ||
-			token.includes(">") ||
-			token.includes("<") ||
-			token.includes("`") ||
-			token.includes("*") ||
-			token.includes("?") ||
-			token.includes("[") ||
-			token.includes("]") ||
-			token.includes("{") ||
-			token.includes("}") ||
-			token.includes("(") ||
-			token.includes(")") ||
-			token.includes(" ") ||
-			token.includes("\t")
-		)
-			throw new VerificationDescriptorError(
-				`verification argv token is not a safe literal: ${token}`,
-			);
-	}
-	if (typeof raw.cwd !== "string" || !raw.cwd.trim())
-		throw new VerificationDescriptorError("verification cwd is invalid");
-	if (isAbsolute(raw.cwd) || raw.cwd.includes("\\"))
-		throw new VerificationDescriptorError("verification cwd must be repository-relative");
-	if (raw.cwd === ".." || raw.cwd.startsWith(`..${sep}`) || raw.cwd.split(sep).includes(".."))
-		throw new VerificationDescriptorError("verification cwd escapes the repository");
-	if (raw.cwd.split(sep).filter(Boolean).length > MAX_CWD_DEPTH)
-		throw new VerificationDescriptorError("verification cwd exceeds the depth bound");
-	if (typeof raw.timeout_ms !== "number" || !Number.isFinite(raw.timeout_ms) || raw.timeout_ms < 1)
-		throw new VerificationDescriptorError("verification timeout_ms must be a finite positive integer");
-	if (!Number.isInteger(raw.timeout_ms) || raw.timeout_ms > MAX_TIMEOUT_MS)
-		throw new VerificationDescriptorError("verification timeout_ms exceeds the host ceiling");
-	if (
-		typeof raw.max_output_bytes !== "number" ||
-		!Number.isFinite(raw.max_output_bytes) ||
-		raw.max_output_bytes < 1
-	)
-		throw new VerificationDescriptorError(
-			"verification max_output_bytes must be a finite positive integer",
-		);
-	if (!Number.isInteger(raw.max_output_bytes) || raw.max_output_bytes > MAX_OUTPUT_BYTES)
-		throw new VerificationDescriptorError(
-			"verification max_output_bytes exceeds the host ceiling",
-		);
+	const env = raw.environment === undefined ? {} : object(raw.environment, ["prepare", "writable_paths"], "verification environment");
+	const writable = env.writable_paths ?? [];
+	if (!Array.isArray(writable) || writable.length > VERIFICATION_DESCRIPTOR_BOUNDS.max_writable_paths)
+		throw new VerificationDescriptorError("verification writable_paths exceeds the host bound");
+	const paths = writable.map(path => verificationRelativePath(path, "verification writable path")).sort();
+	if (paths.includes(".") || new Set(paths).size !== paths.length
+		|| paths.some((path, i) => paths.some((other, j) => j !== i && path.startsWith(`${other}/`))))
+		throw new VerificationDescriptorError("verification writable paths must be distinct non-overlapping directories");
 	return {
 		contract: VERIFICATION_DESCRIPTOR_CONTRACT,
-		runner_id: "bun",
-		runner_version: raw.runner_version,
-		argv: raw.argv as string[],
-		cwd: raw.cwd,
-		timeout_ms: raw.timeout_ms,
-		max_output_bytes: raw.max_output_bytes,
+		command: command(raw.command),
+		environment: { prepare: env.prepare === undefined || env.prepare === null ? null : command(env.prepare), writable_paths: paths },
 	};
 }
 
-/** Canonical bytes of the parsed descriptor (for digest binding). */
 export function canonicalDescriptorBytes(descriptor: VerificationDescriptor): string {
 	return `${JSON.stringify(descriptor, null, 2)}\n`;
 }
-
-/** Re-exported bounds for host-side consistency checks. */
-export const VERIFICATION_DESCRIPTOR_BOUNDS = {
-	max_arg_tokens: MAX_ARGV_TOKENS,
-	max_arg_token_bytes: MAX_ARGV_TOKEN_BYTES,
-	max_cwd_depth: MAX_CWD_DEPTH,
-	max_timeout_ms: MAX_TIMEOUT_MS,
-	max_output_bytes: MAX_OUTPUT_BYTES,
-} as const;