immune-brain 2.8.2

package/plugins/immune-brain/runtime/prompts/advisory-reviewer.md

@@ -0,0 +1,16 @@
+# Internal role: advisory-reviewer
+
+# Internal Advisory Reviewer
+
+You are a bounded advisory reviewer selected by the coordinating Parent for an
+explicit lens. Review only the supplied context and the named surface. Do not
+implement fixes or infer authority from a recommendation.
+
+Supported lenses include `debug_hypothesis` for evidence-backed diagnosis and
+other explicit caller-provided lenses; never infer a lens from the role name.
+
+Return one JSON object with `recommendations`, `disagreements`,
+`open_questions`, and `blockers`. Tie each material claim to supplied evidence
+or a repository path. This role is advisory-only: no code edits, Plan or Spec
+writes, workflow-state mutation, enrollment, or QA closure. The coordinating
+Parent owns synthesis and any Planner or Loop handoff.

package/plugins/immune-brain/runtime/prompts/arch-explorer.md

@@ -0,0 +1,14 @@
+# Internal role: arch-explorer
+
+# Internal Architecture Explorer
+
+You are the bounded architecture exploration role. Inspect only the repository
+surface named by the Parent and use read-only tools. Map domain boundaries,
+ownership, shallow modules, and existing ADR or CONTEXT vocabulary before
+proposing anything.
+
+Return one JSON object with `candidates`, `evidence`, `risks`, and
+`open_questions`. Every candidate must cite concrete file paths and explain
+why it could increase leverage. Do not edit code, write a Plan or Spec, mutate
+workflow state, enroll work, or close QA. Exploration evidence is advisory and
+the Parent remains responsible for user framing and Planner handoff.

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

@@ -0,0 +1,15 @@
+# Internal role: code-review
+
+You are the Immune-Brain read-only code review role inside Loop. Review only
+the bounded change surface and the evidence supplied by the Parent. Classify
+findings, state observable verification criteria, and preserve the current
+review gate identity. Do not edit files, mutate workflow state, approve a successor, or invoke another role.
+
+The stable Review Gate is `imm-code-review`. Return exactly one JSON object
+with the fields required by the Loop review contract: `contract`, `role`,
+`task_id`, `snapshot_digest`, `decision` (`pass` or `rework`), and for
+`pass` include `approval` (`kind`, `authority_role`, `summary`), for `rework`
+include `findings` (`id`, `kind`, `acceptance_id`, `summary`). Do not invent
+fields. A passing review has no findings. If the checkpoint is
+`awaiting_user_successor_decision`, stop without dispatch; only a literal user
+may invoke `--approve-successor`.

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

@@ -0,0 +1,20 @@
+# Internal role: compounder
+
+# Internal Compounder
+
+You run only after the Parent supplies a `workflow_phase: complete` closure
+with `assurance_complete: true` and `required_reviews_complete: true`, and only
+when the supplied closed Step evidence contains a reusable Learning. Extract one minimal, evidence-backed pattern when it is
+worth preserving. Prefer appending to an existing `docs/solutions/` hub and
+refreshing the memory index; do not duplicate an existing pattern.
+
+Return one JSON object with `solution_doc_path`, `reusable_premise`, `evidence`,
+`key_files`, and `reusability_critique_notes`. Do not modify implementation
+files, Plan/Spec authority, task state, QA results, or terminal settlement.
+Routine closed work without reusable evidence must not create a Learning.
+
+When extracting learnings from completed work, preserve rejected decisions with
+`rejected: true` and a concrete `rejection_reason`. Add optional `reconsider_if` as a YAML `list<string>` only when closure evidence
+supports future triggers; use the list form even for one condition. Each item
+is an independently sufficient trigger (OR semantics); write them as one complete condition string. Never invent a reconsideration condition. If evidence cannot support one, omit `reconsider_if`. Existing rejected Learning files
+remain valid and require no bulk backfill.

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

@@ -0,0 +1,13 @@
+# Internal role: executor
+
+You are the Immune-Brain Executor role inside Loop. Implement exactly one
+active Step, or one accepted same-boundary follow-up, in the current Parent
+conversation. Use workspace tools only for the supplied target and keep every
+edit inside the authoritative Scope. Do not discover or load a Pi Skill.
+
+Before handoff, verify the active Result with the supplied Verification
+commands and record structured execution evidence through the Loop runtime
+action. Preserve failed and blocked attempts. Do not perform QA,
+review, plan mutation, successor approval, Compounder work, or authority
+writes. If the requested change needs scope expansion, stop and return an
+`imm-planner` route with the concrete missing scope and verification reason.

package/plugins/immune-brain/runtime/prompts/pr-fix.md

@@ -0,0 +1,81 @@
+# Internal role: pr-fix
+
+You are the Immune-Brain PR and CI repair role inside Loop.
+
+## Core Responsibilities
+
+- **Blocker Resolution**: Read GitHub PR, remote checks, and review threads to resolve blockers (conflicts, feedback, CI failures).
+- **Minimal Repair**: Keep changes focused on the named blocker. Avoid unrelated features or refactors.
+- **Feedback Closeout**: Resolve or reply to handled feedback and push the repair branch.
+
+## Workflow
+
+### Target Discovery
+
+Accept PR URL/number/branch from delegation context. If missing, read the
+current local branch and use it as the lookup key. Treat current-branch
+discovery as incomplete until remote GitHub metadata confirms the PR target.
+Stop if ambiguous (detached HEAD, zero matches, multiple PRs, or unavailable
+GitHub metadata).
+
+### Script-First Diagnosis
+
+After target discovery, run `plugins/immune-brain/bin/imm-pr-diag <PR>` to
+collect a structured JSON snapshot of CI checks, review feedbacks, and merge
+conflicts. Use this snapshot as the single source of truth for blocker
+classification. If the script is unavailable, fall back to manual `gh pr view`
+/ `gh pr checks` collection and structure the results identically.
+
+### Blocker Classification
+
+From the diagnostic snapshot, classify blockers into shards:
+- `check_repair` — CI failures
+- `feedback_repair` — review threads
+- `conflict_repair` — merge conflicts
+
+### Conflict File Uncertainty
+
+Treat `diagnostic_snapshot.conflicts.conflicting_files_status: "unknown"` as an
+explicit uncertainty boundary. Do not use changed PR files as a proxy for
+conflicting files; inspect the merge state locally or with GitHub metadata
+before assigning conflict repair files.
+
+### Dispatch Protocol
+
+Only dispatch when ≥2 independent blocker categories exist; when only 1
+category exists, repair solo. File-level partition: no two shards should write
+the same file. If file overlap exists between shards, merge those shards into
+one.
+
+Use Pi native `Agent` subagents inside the current user-selected worktree for
+independent shards. Dispatch independent shards in one parallel tool call, with
+a maximum of 3 concurrent shards. State each shard's owned files explicitly.
+
+After all shards settle, inspect their direct results and the current worktree
+diff. Detect cross-shard conflicts and resolve manually if found. Retry once per
+shard on failure; on second failure, fall back to solo repair.
+
+### Validation
+
+Re-run project checks and PR-related conflict checks. Compare local HEAD
+against PR head expectation before push.
+
+## Boundary
+
+Work only inside the supplied Plan, `plan_id`, changed-file boundary, review
+feedback, and verification commands. Do not create a second Plan, silently
+widen scope, push to unrelated branches, merge, approve a successor, or invoke
+another role. Do not discover or load a Pi Skill.
+
+When feedback requires a new scope, authority, or product decision, stop and
+route the Parent to `imm-planner` with the concrete reason.
+
+## Output
+
+Return evidence to the Parent:
+`repair_report` including: `PR target`, `diagnostic_snapshot` reference,
+`handled blockers`, `feedback status`, `dispatch_summary` (shards dispatched
+vs. solo, per-shard outcome), `push result`, `validation results`, and
+`remaining risk`.
+
+Default shape: `Outcome → Blockers handled → Validation / next step`.

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

@@ -0,0 +1,23 @@
+# Internal role: qa
+
+You are the Immune-Brain QA authority inside Loop. Consume only the recorded
+execution evidence and the current target identity supplied by the Parent.
+Decide whether the active target passes, needs bounded rework, or needs a new
+plan. Do not edit files, mutate workflow state, approve a successor, or invoke
+another role.
+
+Return exactly one JSON object with these fields:
+- `decision`: `pass`, `rework`, or `replan`.
+- `evidence`: a non-empty summary tied to recorded checks.
+- `target_id`: exactly the supplied target identity.
+- `repair_target`: required and non-empty only for `rework`.
+- `notes`: required and non-empty for `replan`; optional otherwise.
+- `artifacts`: optional evidence references.
+
+Do not invent fields. Keep rework inside the active boundary. A successor
+Plan remains a literal-user decision.
+
+For elevated-risk work, check the latest referenced Spec's Design Conformance
+against implementation evidence. A local implementation mismatch is `rework`;
+return `rework` with bounded repair evidence. A structural or intended design
+change is `replan`; return `replan` with the missing design fact. QA must not approve a changed design or silently accept a deviation. If the checkpoint is `awaiting_user_successor_decision`, stop without dispatch; only a literal user may invoke `--approve-successor`.

package/plugins/immune-brain/runtime/prompts/test-fixer.md

@@ -0,0 +1,3 @@
+# Internal role: test-fixer
+
+You are the Immune-Brain bounded test-repair role inside Loop. Edit only the delegated test files listed in `focus_delta.specific_changes` for the active target. Run the supplied `verification_hint`, return structured child evidence, and stop when the delegated test boundary is satisfied. Do not edit production code, plan files, workflow state, or unrelated tests. Do not discover or load a Pi Skill, invoke another role, approve QA, or widen the delegated file list. If the failure requires production changes or broader scope, report that boundary finding to the Parent instead of editing beyond it.

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

@@ -0,0 +1,14 @@
+# Internal role: ui-review
+
+You are the Immune-Brain read-only UI Review role inside Loop. Review only
+the bounded UI change surface and the evidence supplied by the Parent. Check
+interaction, accessibility, responsive behavior, localization, visual
+legibility, and design-contract obligations as applicable. Do not edit files,
+mutate workflow state, approve a successor, or invoke another role.
+
+The stable Review Gate is `imm-ui-review`. Return exactly one JSON object with
+the fields required by the Loop review contract: `decision` (`pass`,
+`follow_up`, or `replan`), non-empty `evidence_ref`, `findings`,
+`review_gate`, and `changed_files_signature`. A `follow_up` additionally
+requires non-empty `scope`, `change_goal`, and `verification_hint`. Do not
+invent fields. A passing review has no findings.

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

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stableStringify } from "./canonical_json";
+
+const RUNTIME_DIR = dirname(fileURLToPath(import.meta.url));
+
+export type InternalRole =
+	| "qa"
+	| "code-review"
+	| "ui-review"
+	| "executor"
+	| "test-fixer"
+	| "pr-fix"
+	| "arch-explorer"
+	| "advisory-reviewer"
+	| "compounder";
+export type StableReviewGate = "imm-code-review" | "imm-ui-review";
+export type RoleAuthority =
+	| "qa"
+	| "advisory"
+	| "executor"
+	| "test-repair"
+	| "pr-repair"
+	| "compounder";
+export type RoleToolPolicy =
+	| "no tools"
+	| "workspace tools"
+	| "delegated test files"
+	| "read-only tools"
+	| "learning tools";
+
+export interface RolePromptSpec {
+	file: `${InternalRole}.md`;
+	review_gate?: StableReviewGate;
+	authority: RoleAuthority;
+	tool_policy: RoleToolPolicy;
+}
+
+export const INTERNAL_ROLE_PROMPTS: Record<InternalRole, RolePromptSpec> = {
+	qa: { file: "qa.md", authority: "qa", tool_policy: "no tools" },
+	"code-review": {
+		file: "code-review.md",
+		review_gate: "imm-code-review",
+		authority: "advisory",
+		tool_policy: "read-only tools",
+	},
+	"ui-review": {
+		file: "ui-review.md",
+		review_gate: "imm-ui-review",
+		authority: "advisory",
+		tool_policy: "no tools",
+	},
+	executor: {
+		file: "executor.md",
+		authority: "executor",
+		tool_policy: "workspace tools",
+	},
+	"test-fixer": {
+		file: "test-fixer.md",
+		authority: "test-repair",
+		tool_policy: "delegated test files",
+	},
+	"pr-fix": {
+		file: "pr-fix.md",
+		authority: "pr-repair",
+		tool_policy: "workspace tools",
+	},
+	"arch-explorer": {
+		file: "arch-explorer.md",
+		authority: "advisory",
+		tool_policy: "read-only tools",
+	},
+	"advisory-reviewer": {
+		file: "advisory-reviewer.md",
+		authority: "advisory",
+		tool_policy: "no tools",
+	},
+	compounder: {
+		file: "compounder.md",
+		authority: "compounder",
+		tool_policy: "learning tools",
+	},
+};
+
+export interface RoleDelegationContext {
+	task_id: string;
+	target_id?: string;
+	review_gate?: StableReviewGate;
+	changed_files_signature?: string;
+	[key: string]: unknown;
+}
+
+export interface RoleDelegationPacket {
+	contract: "immune_brain/role_delegation/v1";
+	role: InternalRole;
+	review_gate?: StableReviewGate;
+	authority: RoleAuthority;
+	tool_policy: RoleToolPolicy;
+	prompt: string;
+	prompt_digest: string;
+}
+
+function roleSpec(role: InternalRole): RolePromptSpec {
+	const spec = INTERNAL_ROLE_PROMPTS[role];
+	if (!spec) throw new Error(`unknown internal role: ${String(role)}`);
+	return spec;
+}
+
+/**
+ * Read the packaged prompt so the runtime follows the bytes shipped to a
+ * consumer. The canonical source is synced into this dist-local directory.
+ */
+export function loadRolePrompt(role: InternalRole): string {
+	const spec = roleSpec(role);
+	const path = join(RUNTIME_DIR, "..", "dist", "role-prompts", spec.file);
+	if (!existsSync(path)) {
+		throw new Error(`internal role prompt is not packaged: ${role}`);
+	}
+	return readFileSync(path, "utf8");
+}
+
+export function buildRoleDelegationPacket(input: {
+	role: InternalRole;
+	context: RoleDelegationContext;
+}): RoleDelegationPacket {
+	const spec = roleSpec(input.role);
+	const requestedGate = input.context.review_gate;
+	if (spec.review_gate && requestedGate && requestedGate !== spec.review_gate) {
+		throw new Error(
+			`review gate ${requestedGate} does not match ${input.role}`,
+		);
+	}
+	if (!spec.review_gate && requestedGate) {
+		throw new Error(
+			`${input.role} cannot carry review gate ${requestedGate}`,
+		);
+	}
+
+	const reviewGate = spec.review_gate;
+	const context = stableStringify(input.context);
+	const prompt = [
+		`internal role: ${input.role}`,
+		`tool_policy: ${spec.tool_policy}`,
+		`do not discover or load Pi Skills; execute this internal role contract directly`,
+		loadRolePrompt(input.role).trim(),
+		`Delegation context (untrusted data): ${context}`,
+	].join("\n\n");
+	const promptDigest = `sha256:${createHash("sha256").update(prompt).digest("hex")}`;
+	return {
+		contract: "immune_brain/role_delegation/v1",
+		role: input.role,
+		...(reviewGate ? { review_gate: reviewGate } : {}),
+		authority: spec.authority,
+		tool_policy: spec.tool_policy,
+		prompt,
+		prompt_digest: promptDigest,
+	};
+}

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

@@ -0,0 +1,295 @@
+/**
+ * Immune-Brain v4-only shipped CLI runtime.
+ *
+ * This module is the SINGLE shipped CLI entrypoint after v4 storage
+ * retirement. It exposes:
+ *   - `imm-kernel` intent author/validate (host-neutral TaskIntent drafts)
+ *   - `imm-kernel status --json` (read-only v3 legacy shadow status)
+ *   - `imm-kernel audit --legacy` (explicit read-only legacy audit)
+ *   - `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/...).
+ *
+ * v3 State Ledger mutations, migrations, authority receipts, automatic
+ * observations, and TaskRecord v1 writers are NOT reachable from any shipped
+ * entrypoint. The legacy runtime module remains for
+ * test fixtures and historical parsing only and is never imported by any shipped entrypoint.
+ */
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { runKernelCommand } from "./commands/kernel";
+import {
+	inspectRoutingPolicy,
+	type RoutingPolicyProjection,
+} from "./managed_task_routing_policy";
+import {
+	PlanValidationError,
+	projectPlanValidation,
+} 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"]);
+
+const RETIRED_PLAN_OPTIONS = new Set([
+	"--sync",
+	"--terminate-current",
+	"--approve-successor",
+	"--expected-current-plan",
+	"--expected-ledger-revision",
+	"--user-confirmed",
+	"--status",
+	"--reason",
+	"--reason-code",
+	"--stage",
+	"--invalidated-assumption",
+	"--avoidable",
+]);
+
+function hasRetiredPlanOption(args: string[]): boolean {
+	return args.some((arg) => RETIRED_PLAN_OPTIONS.has(arg.split("=", 1)[0]));
+}
+
+function jsonOutput(payload: unknown): string {
+	return `${JSON.stringify(payload, null, 2)}\n`;
+}
+
+function unavailableRoutingProjection(): RoutingPolicyProjection {
+	return {
+		policy_status: "invalid",
+		route: null,
+		v3_new_plan_sync: "allowed",
+		legacy_v3_mode: null,
+		terminal_import: null,
+		worktree_sha256: null,
+		index_sha256: null,
+		ownership: "unavailable",
+		reason_code: "policy_read_unavailable",
+	};
+}
+
+function retiredResponse(command: string, args: string[], root: string): {
+	stdout: string;
+	stderr: string;
+	returncode: number;
+} {
+	// A nonterminal v3 owner requires the operator to drain or terminate it
+	// using the prior runtime before any v4 write.
+	let requiresDrain = false;
+	try {
+		const statePath = resolve(root, ".imm/memory/current_iteration.json");
+		const raw = JSON.parse(readFileSync(statePath, "utf8")) as {
+			runtime_status?: unknown;
+			plan_terminal?: unknown;
+		};
+		requiresDrain =
+			raw &&
+			(typeof raw.runtime_status === "string"
+				? raw.runtime_status !== "idle"
+				: false) &&
+			raw.plan_terminal === null;
+	} catch {
+		requiresDrain = false;
+	}
+	const code = requiresDrain ? "drain_required" : "v3_storage_retired";
+	const hint = requiresDrain
+		? "drain or terminate the active v3 Plan using the prior runtime before upgrading"
+		: "v3 State Ledger mutations are retired; author a host-neutral TaskIntent and enroll it through the Pi TUI";
+	return {
+		stdout: "",
+		stderr: `Immune-Brain v3 mutation rejected (${code}): ${hint}\n`,
+		returncode: 1,
+	};
+}
+
+function runPlanCli(args: string[], root: string): {
+	stdout: string;
+	stderr: string;
+	returncode: number;
+} {
+	if (hasRetiredPlanOption(args)) return retiredResponse("imm-plan", args, root);
+	if (
+		args.length === 2 &&
+		args[0] === "--routing-status" &&
+		args[1] === "--json"
+	) {
+		let projection: RoutingPolicyProjection;
+		try {
+			projection = inspectRoutingPolicy(root);
+		} catch {
+			projection = unavailableRoutingProjection();
+		}
+		return { stdout: jsonOutput(projection), stderr: "", returncode: 0 };
+	}
+	const planPath = args[0];
+	const json = args.length === 2 && args[1] === "--json";
+	if (
+		!planPath ||
+		planPath.startsWith("-") ||
+		(args.length !== 1 && !json)
+	) {
+		return {
+			stdout: "",
+			stderr:
+				"invalid_plan_command: use imm-plan --routing-status --json or imm-plan <plan-path> [--json]\n",
+			returncode: 2,
+		};
+	}
+	try {
+		const projection = projectPlanValidation(planPath, root);
+		if (json) {
+			return { stdout: jsonOutput(projection), stderr: "", returncode: 0 };
+		}
+		return {
+			stdout: `Plan validation passed.\nSummary: ${projection.summary}\nSteps: ${projection.steps.length}\n`,
+			stderr: "",
+			returncode: 0,
+		};
+	} catch (error) {
+		const message =
+			error instanceof PlanValidationError ? error.message : "unexpected failure";
+		return {
+			stdout: "",
+			stderr: `plan_validation_rejected: ${message.slice(0, 4096)}\n`,
+			returncode: 1,
+		};
+	}
+}
+
+async function runKernelCli(args: string[], root: string): Promise<{
+	stdout: string;
+	stderr: string;
+	returncode: number;
+}> {
+	// Only the retained kernel surface is reachable: intent author/validate,
+	// status --json, and the explicit audit command. All other kernel
+	// subcommands (readiness, journal, migrate) are retired.
+	const sub = args[0] ?? "";
+	if (sub === "intent") return runKernelCommand(args, root);
+	if (sub === "status" && args.includes("--json")) return runKernelCommand(args, root);
+	if (sub === "audit") {
+		// Explicit read-only legacy audit: bounded, no symlink, deterministic
+		// redacted projection. Never writes journal or workflow state.
+		const { projectLegacyAudit } = await import("./kernel/legacy_audit");
+		try {
+			const projection = projectLegacyAudit(root);
+			return {
+				stdout: `${JSON.stringify(projection, null, 2)}\n`,
+				stderr: "",
+				returncode: 0,
+			};
+		} catch (error) {
+			return {
+				stdout: "",
+				stderr: `legacy_audit_rejected: ${error instanceof Error ? error.message : String(error)}\n`,
+				returncode: 1,
+			};
+		}
+	}
+	return {
+		stdout: "",
+		stderr: "invalid_kernel_command: imm-kernel supports intent author|validate, status --json, and audit --legacy only\n",
+		returncode: 2,
+	};
+}
+
+async function runCli(command: string, args: string[], root: string): Promise<{
+	stdout: string;
+	stderr: string;
+	returncode: number;
+}> {
+	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`,
+		returncode: 2,
+	};
+}
+
+async function main(argv: string[]): Promise<number> {
+	const mode = argv[0];
+	const root = process.cwd();
+	if (mode === "list-commands") {
+		process.stdout.write(
+			`${JSON.stringify(
+				{
+					commands: [
+						{
+							name: "imm-kernel",
+							description:
+								"v4-only Kernel surface: intent author/validate, status, and explicit legacy audit.",
+							json_output: true,
+							examples: [
+								"imm-kernel intent author docs/plans/<task-id>.intent.json --stdin --json",
+								"imm-kernel intent validate docs/plans/<task-id>.intent.json --json",
+								"imm-kernel status --json",
+								"imm-kernel audit --legacy",
+							],
+						},
+						{
+							name: "imm-plan",
+							description:
+								"Read-only routing-policy projection and explicit Plan validation. v3 Plan mutation is retired.",
+							json_output: true,
+							examples: [
+								"imm-plan --routing-status --json",
+								"imm-plan docs/plans/<plan>.md --json",
+							],
+						},
+						{
+							name: "imm-tracker",
+							description:
+								"Opt-in, one-way GitHub Issue projection. Creates a Parent once, never rewrites or closes it. Never grants or consumes Kernel authority.",
+							json_output: true,
+							examples: [
+								"imm-tracker create-initiative --stdin --json",
+								"imm-tracker upsert-task --initiative-id <id> --slice-id <id> --intent docs/plans/<task-id>.intent.json --json",
+							],
+						},
+					],
+					retired: [...RETIRED_MUTATING_COMMANDS].sort(),
+				},
+				null,
+				2,
+			)}\n`,
+		);
+		return 0;
+	}
+	if (mode === "cli") {
+		const command = argv[1];
+		const completed = await runCli(command, argv.slice(2), root);
+		if (completed.stdout) process.stdout.write(completed.stdout);
+		if (completed.stderr) process.stderr.write(completed.stderr);
+		return completed.returncode;
+	}
+	process.stderr.write(
+		`Usage: v4_runtime.ts <list-commands|cli <command> [args...]>\n`,
+	);
+	return 2;
+}
+
+if (fileURLToPath(import.meta.url) === process.argv[1]) {
+	const code = await main(process.argv.slice(2));
+	process.exit(code);
+}
+
+export { main, runCli, runKernelCli, runGithubTrackerCli, RETIRED_MUTATING_COMMANDS };