immune-brain 3.6.9 → 4.0.0

package/plugins/immune-brain/runtime/commands/kernel.ts

@@ -1,4 +1,3 @@
-import { createHash } from "node:crypto";
 import {
 	closeSync,
 	constants as fsConstants,
@@ -8,7 +7,7 @@ import {
 	writeFileSync,
 } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import {
@@ -27,6 +26,7 @@ import {
 	parseTaskIntentV1,
 	RISK_FLOOR_SCOPE_PREFIXES,
 } from "../kernel/intent";
+import { inspectSpecBinding } from "../kernel/spec_binding";
 import { projectTask, resolveProjectedRisk } from "../kernel/completion";
 import { deriveAssuranceAuthorization } from "../kernel/assurance_projection";
 import { taskDiffIdentity, taskRevisionIdentity } from "../workspace_scope";
@@ -40,7 +40,7 @@ import { projectLegacyAudit } from "../kernel/legacy_audit";
 import { inspectStorageLayout } from "../kernel/storage_paths";
 import { migrateLegacyLayout } from "../kernel/storage_layout_migration";
 import { readBackendClaim } from "../kernel/backend_claim";
-import { withKernelStoreLock } from "../kernel";
+import { probeKernelStore } from "../kernel";
 
 export interface KernelCommandResult {
 	stdout: string;
@@ -65,12 +65,6 @@ function errorResult(code: string, message: string, returncode: number): KernelC
 	return jsonResult({ error: { code, message } }, returncode);
 }
 
-function asRecord(value: unknown): Record<string, unknown> {
-	return value && typeof value === "object" && !Array.isArray(value)
-		? (value as Record<string, unknown>)
-		: {};
-}
-
 function journalFor(
 	command: string,
 	phase: TaskPhase | null,
@@ -121,16 +115,7 @@ function runStatus(root: string): KernelExecution {
 	try {
 		const layout = inspectStorageLayout(root);
 		const claim = readBackendClaim(root);
-		const workspace = (() => {
-			try {
-				const raw = JSON.parse(readSecureProjectFile(root, ".imm/state/workspace.json")) as {
-					current_working?: unknown;
-				};
-				return typeof raw.current_working === "string" ? raw.current_working : null;
-			} catch {
-				return null;
-			}
-		})();
+		const workspace = readWorkspaceOwner(root);
 		return {
 			result: jsonResult({
 				contract: "assurance_kernel/status/v1",
@@ -193,10 +178,7 @@ function matchingFloorEntries(intent: TaskIntentV1): string[] {
 
 function readWorkspaceOwner(root: string): string | null {
 	try {
-		const raw = JSON.parse(readSecureProjectFile(root, ".imm/state/workspace.json")) as {
-			current_working?: unknown;
-		};
-		return typeof raw.current_working === "string" ? raw.current_working : null;
+		return readWorkspaceStateRaw(root).state.current_working;
 	} catch {
 		return null;
 	}
@@ -292,8 +274,8 @@ function runInspect(root: string): KernelExecution {
 		try {
 			identity =
 				record.contract === "assurance_kernel/task_record/v4"
-					? taskRevisionIdentity(root, intent.scope_hint, record.git_base_head)
-					: taskDiffIdentity(root, intent.scope_hint);
+					? taskRevisionIdentity(root, intent.scope_hint, record.git_base_head, intent.task_id)
+					: taskDiffIdentity(root, intent.scope_hint, intent.task_id);
 		} catch (error) {
 			return sourceFailure("inspect", error);
 		}
@@ -499,7 +481,7 @@ function runIntentAuthor(args: string[], root: string): KernelExecution {
 	// its frozen manifest under both locks. The original authoring is retried
 	// only after the affected migration diff is committed.
 	try {
-		withKernelStoreLock(root, () => undefined);
+		probeKernelStore(root);
 	} catch (error) {
 		return {
 			result: errorResult(
@@ -536,46 +518,13 @@ function runIntentAuthor(args: string[], root: string): KernelExecution {
 		};
 	}
 	if (layout.layout === "recovery_required" || layout.layout === "migration_required") {
-		const migration = migrateLegacyLayout(root);
-		if (migration.outcome === "migrated") {
-			return {
-				result: jsonResult({
-					contract: "assurance_kernel/migration_completed/v1",
-					operation: "intent author",
-					affected_paths: migration.affected_paths,
-					next_action: "commit the affected migration paths, then retry intent author",
-				}),
-				journal: journalFor(
-					"intent",
-					null,
-					"escalated",
-					"migration_ambiguous",
-					null,
-					"Legacy evidence was relocated without Git index writes; commit and retry.",
-				),
-			};
-		}
-		if (migration.outcome === "migration_uncommitted") {
-			return {
-				result: errorResult(
-					"migration_uncommitted",
-					`affected storage paths differ from HEAD: ${migration.affected_paths.join(", ") || "(none)"}`,
-					1,
-				),
-				journal: journalFor(
-					"intent",
-					null,
-					"rejected",
-					"migration_ambiguous",
-					null,
-					"Commit or restore the affected paths before retrying.",
-				),
-			};
-		}
+		// Authoring never migrates implicitly: the retired layout is converted by
+		// the explicit claimless command only, so creating a draft cannot publish a
+		// database or retire historical files behind the operator's back.
 		return {
 			result: errorResult(
-				layout.layout === "recovery_required" ? "layout_recovery_required" : "layout_migration_blocked",
-				migration.reason ?? layout.reason ?? "storage layout is not ready",
+				layout.layout === "recovery_required" ? "layout_recovery_required" : "layout_migration_required",
+				`${layout.reason ?? "storage layout is not ready"}; run imm-kernel migrate --storage-layout first`,
 				1,
 			),
 			journal: journalFor(
@@ -584,7 +533,7 @@ function runIntentAuthor(args: string[], root: string): KernelExecution {
 				"rejected",
 				"source_invalid",
 				null,
-				"Resolve the reported storage layout condition before authoring.",
+				"Run imm-kernel migrate --storage-layout, commit the affected paths, then retry intent author.",
 			),
 		};
 	}
@@ -760,7 +709,7 @@ function runIntentAuthor(args: string[], root: string): KernelExecution {
 		return {
 			result: errorResult(
 				"intent_invalid",
-				`candidate acceptance verification failed strict verification_descriptor/v1 parsing: ${error instanceof Error ? error.message : error}`,
+				`candidate acceptance verification failed strict verification_descriptor/v2 parsing: ${error instanceof Error ? error.message : error}`,
 				1,
 			),
 			journal: journalFor(
@@ -769,7 +718,7 @@ function runIntentAuthor(args: string[], root: string): KernelExecution {
 				"rejected",
 				"intent_invalid",
 				null,
-				"Fix the reported verification_descriptor/v1 violations and retry.",
+				"Fix the reported verification_descriptor/v2 violations and retry.",
 			),
 		};
 	}
@@ -1132,6 +1081,29 @@ function runIntentValidate(args: string[], root: string): KernelExecution {
 			),
 		};
 	}
+	const specBinding = inspectSpecBinding(intent);
+	if (!specBinding.ok) {
+		return {
+			result: jsonResult(
+				{
+					contract: "assurance_kernel/intent_validation/v1",
+					valid: false,
+					path: relative,
+					task_id: intent.task_id,
+					reason: specBinding.message,
+				},
+				0,
+			),
+			journal: journalFor(
+				"intent",
+				null,
+				"ok",
+				"command_ok",
+				null,
+				null,
+			),
+		};
+	}
 
 	const verification: Array<{ id: string; eligible: boolean; reason: string | null }> = [];
 	let allEligible = true;
@@ -1244,6 +1216,25 @@ function executeKernelCommand(args: string[], root: string): KernelExecution {
 			};
 		return runInspect(root);
 	}
+	if (command === "migrate") {
+		if (flags.length !== 1 || flags[0] !== "--storage-layout")
+			return {
+				result: errorResult(
+					"invalid_command",
+					"migrate accepts only --storage-layout",
+					2,
+				),
+				journal: journalFor(
+					command,
+					null,
+					"rejected",
+					"invalid_command",
+					null,
+					"Run imm-kernel migrate --storage-layout.",
+				),
+			};
+		return runStorageLayoutMigration(root);
+	}
 	if (command === "audit") {
 		if (args.length !== 2 || args[1] !== "--legacy")
 			return {
@@ -1341,6 +1332,106 @@ function executeKernelCommand(args: string[], root: string): KernelExecution {
 	};
 }
 
+/**
+ * Explicit claimless storage-layout migration.
+ *
+ * The retired file store is converted here and nowhere else: this command never
+ * authors an intent, never opens a task, and never needs an active claim, so a
+ * worktree that is still on the retired layout has one reachable entry point.
+ * Mutating commands keep their fail-closed gate; this is the command that
+ * resolves it.
+ */
+function runStorageLayoutMigration(root: string): KernelExecution {
+	const inspection = inspectStorageLayout(root);
+	// Only a live owner blocks the command. Every other diagnosis is handed to
+	// the migrator, which owns the recovery decisions: an interrupted
+	// publication shows both stores and must stay reachable through this CLI.
+	if (inspection.layout === "migration_blocked_active")
+		return {
+			result: errorResult(
+				"layout_migration_blocked",
+				inspection.reason ?? "a live legacy task still owns work; settle or stop it on the prior runtime first",
+				1,
+			),
+			journal: journalFor(
+				"migrate",
+				null,
+				"rejected",
+				"source_invalid",
+				null,
+				"Resolve the reported layout condition, then rerun imm-kernel migrate --storage-layout.",
+			),
+		};
+	const migration = migrateLegacyLayout(root);
+	if (migration.outcome === "migrated")
+		return {
+			result: jsonResult({
+				contract: "assurance_kernel/migration_completed/v1",
+				operation: "storage layout migration",
+				affected_paths: migration.affected_paths,
+				next_action: "commit the affected migration paths, then retry the original command",
+			}),
+			journal: journalFor(
+				"migrate",
+				null,
+				"escalated",
+				"migration_ambiguous",
+				null,
+				"Commit the affected migration paths, then retry the original command.",
+			),
+		};
+	if (migration.outcome === "migration_uncommitted")
+		return {
+			result: jsonResult({
+				contract: "assurance_kernel/migration_pending_commit/v1",
+				operation: "storage layout migration",
+				affected_paths: migration.affected_paths,
+				reason: migration.reason,
+				next_action: "commit the preserved audit evidence, then rerun imm-kernel migrate --storage-layout",
+			}),
+			journal: journalFor(
+				"migrate",
+				null,
+				"escalated",
+				"migration_ambiguous",
+				null,
+				"Commit the preserved audit evidence, then rerun imm-kernel migrate --storage-layout.",
+			),
+		};
+	if (migration.outcome === "already_migrated")
+		return {
+			result: jsonResult({
+				contract: "assurance_kernel/migration_completed/v1",
+				operation: "storage layout migration",
+				affected_paths: [],
+				next_action: "retry the original command",
+			}),
+			journal: journalFor(
+				"migrate",
+				null,
+				"ok",
+				"command_ok",
+				null,
+				"Retry the original command.",
+			),
+		};
+	return {
+		result: errorResult(
+			"layout_migration_blocked",
+			migration.reason ?? "the storage layout migration did not complete",
+			1,
+		),
+		journal: journalFor(
+			"migrate",
+			null,
+			"rejected",
+			"source_invalid",
+			null,
+			"Resolve the reported layout condition, then rerun imm-kernel migrate --storage-layout.",
+		),
+	};
+}
+
 export function runKernelCommand(
 	args: string[],
 	root = process.cwd(),

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

@@ -2360,7 +2360,7 @@ export async function runGithubInitiativePublication(
 		);
 		if (!("get" in topology)) return publicationResult(topology.status, topology.message, topology);
 		const historicalRelations = new Map<string, { blocked_by: number[]; state_reason: string | null }>();
-		for (const [taskId, binding] of amendment.historical) {
+		for (const [taskId] of amendment.historical) {
 			const issue = topology.get(taskId)!;
 			const observed = await readBlockedByIds(absoluteRoot, gh, "upsert-task", initial.repository, issue.number);
 			if (!Array.isArray(observed)) return publicationResult(observed.status, observed.message, observed);

package/plugins/immune-brain/runtime/kernel/actor_identity.ts

@@ -0,0 +1,33 @@
+// The literal-user authority identity, spelled once.
+//
+// Audit survey before the convergence (122 settled records under .imm/audit/,
+// counting every `actor_id` in each record): `literal-user` appears 220 times
+// across 54 records — the spelling Pi has recorded since the first managed
+// task. The shortened `user` appears 4 times, all of them in three
+// Claude-Host-era records, and the Kernel's own batch validation already
+// demanded "a literal-user actor_id" while accepting the string "user". The
+// converged spelling is therefore `literal-user`.
+//
+// Settled records are never rewritten: the reader keeps accepting both
+// spellings, so a historical `user` audit or a batch capability issued before
+// the convergence still validates and stays byte-identical. Every newly written
+// record carries the canonical spelling.
+
+export const LITERAL_USER_ACTOR_ID = "literal-user";
+
+/** Spellings that mean the literal user. Both are read; only one is written. */
+const LITERAL_USER_SPELLINGS: ReadonlySet<string> = new Set([LITERAL_USER_ACTOR_ID, "user"]);
+
+/** True for a historical or current literal-user actor. */
+export function isLiteralUserActor(actorId: string): boolean {
+	return LITERAL_USER_SPELLINGS.has(actorId);
+}
+
+/**
+ * The spelling to record. A historical `user` is read as what it meant and
+ * recorded as the canonical identity; every other actor is passed through
+ * unchanged.
+ */
+export function canonicalActorId(actorId: string): string {
+	return actorId === "user" ? LITERAL_USER_ACTOR_ID : actorId;
+}

package/plugins/immune-brain/runtime/kernel/application.ts

@@ -4,9 +4,9 @@
 // the dedicated recoverable workspace transaction. Consumed by the Pi canary
 // host adapter via canary_application.
 
+import { terminalRequestDigest } from "./run_identity";
 import {
 	type MutationAuthorityRegistry,
-	type ValidatedAuthorityV2,
 } from "./authority_port";
 import { asTaskDiffSnapshot } from "./completion";
 import { canonicalIntentHash, readTaskIntent } from "./intent";
@@ -26,6 +26,7 @@ import {
 	commitTerminalLocked,
 	readTaskRecordRaw,
 	readWorkspaceStateRaw,
+	currentRunId,
 	revisionForContent,
 	serializeWorkspace,
 	withKernelStoreLock,
@@ -37,8 +38,6 @@ import type {
 	AuthorityAuditDescriptor,
 	MutationAuthorityCapabilityV2,
 	StoredTaskMutationV3,
-	TaskAction,
-	TaskIntentV1,
 	TaskRecord,
 } from "./types";
 import { TASK_TOMBSTONE_CONTRACT, type TaskTombstone } from "./backend_claim";
@@ -164,9 +163,15 @@ export function applyTaskAction(
 			action.type === "stop" ||
 			action.type === "resolve_user_decision";
 
+		// A capability is opaque: its binding lives in the issuing registry, so
+		// the run this worktree holds is read here and handed to the registry as
+		// the expected identity. Authority issued for another run is refused
+		// before any write, which is what keeps it inside the worktree that
+		// issued it even when task, record, intent and diff content are identical.
 		const expectedAuthority = privileged
 			? {
 					task_id,
+					run_id: currentRunId(root, task_id) ?? undefined,
 					action,
 					expected_record_hash: current.revision,
 					intent_revision: isRevisionAction
@@ -189,6 +194,7 @@ export function applyTaskAction(
 		const inspectedAudit = expectedAuthority
 			? registry.inspect(capability, expectedAuthority, now)
 			: null;
+		const authorityRunId = inspectedAudit?.run_id;
 		const mutation = reduceTask(
 			current.record,
 			action,
@@ -227,9 +233,8 @@ export function applyTaskAction(
 		// All preflight passed: consume tokens and authority, then commit.
 		consumeIntentToken(prior_intent_token);
 		consumeIntentToken(freshRead.token);
-		let consumedAudit: ValidatedAuthorityV2 | null = null;
 		if (expectedAuthority) {
-			consumedAudit = registry.consume(
+			registry.consume(
 				capability as MutationAuthorityCapabilityV2,
 				expectedAuthority,
 				now,
@@ -284,7 +289,17 @@ export function applyTaskAction(
 				next_workspace_content: serializeWorkspace(nextWorkspaceState),
 				...(input.artifact_transition ? { artifact_relocations: input.artifact_transition.relocations } : {}),
 			};
-			commitTerminalLocked(root, task_id, transaction, tombstone);
+			commitTerminalLocked(
+				root,
+				task_id,
+				transaction,
+				tombstone,
+				authorityRunId,
+				// The request this settlement answers: a retry with a different
+				// reason, actor or event time is a different decision and must be
+				// authorized again rather than replayed.
+				terminalRequestDigest(action),
+			);
 			return {
 				revision: canonicalRecordHash(nextRecord),
 				record: nextRecord,
@@ -303,6 +318,7 @@ export function applyTaskAction(
 			workspace.revision,
 			nextWorkspaceState,
 			input.artifact_transition?.relocations,
+			authorityRunId,
 		);
 	});
 }

package/plugins/immune-brain/runtime/kernel/assurance_projection.ts

@@ -12,9 +12,16 @@
 // "start QA" or "start Review"; it returns Kernel-owned facts only.
 
 import { readBackendClaim, readTaskTombstone } from "./backend_claim";
-import { readTaskRecord, readAuditTaskPair, readWorkspaceStateRaw, reconcileKernelAuthority } from "./storage";
+import {
+	readTaskRecord,
+	readAuditTaskPair,
+	readCommittedRecord,
+	readWorkspaceStateRaw,
+	reconcileKernelAuthority,
+} from "./storage";
 import { projectTask, resolveProjectedRisk } from "./completion";
-import type { AssuranceObligation, TaskIntentV1, TaskRecord, TaskRecordV2 } from "./types";
+import type { AssuranceObligation, TaskIntentV1, TaskRecord, TaskRecordV3 } from "./types";
+import type { TaskRecordV2 } from "./legacy_task_record";
 
 export interface TaskDiffSnapshot {
 	diff_hash: string;
@@ -34,6 +41,12 @@ export interface AssuranceAuthorizationReadiness {
 }
 
 export interface AssuranceProjection {
+	/**
+	 * The exact run this projection describes: one worktree owns one store and
+	 * one active run, so the run id is the authority identity a capability must
+	 * bind. Null when no run is committed.
+	 */
+	run_id: string | null;
 	record_revision: string;
 	workspace_revision: string;
 	intent_revision: number;
@@ -83,6 +96,7 @@ export function deriveAssuranceAuthorization(input: {
 
 function emptyProjection(): AssuranceProjection {
 	return {
+		run_id: null,
 		record_revision: "",
 		workspace_revision: "",
 		intent_revision: 0,
@@ -128,6 +142,36 @@ function projectHistoricalTerminal(
 	};
 }
 
+function projectHistoricalTerminalV3(
+	record: TaskRecordV3,
+	recordRevision: string,
+	workspaceRevision: string,
+): AssuranceProjection {
+	const freshAcceptanceIds = [
+		...new Set(
+			record.attestations
+				.filter((item) => item.kind === "qa")
+				.flatMap((item) => item.acceptance_results)
+				.filter((item) => item.status === "passed")
+				.map((item) => item.acceptance_id),
+		),
+	];
+	const approvalKinds = [...new Set(record.attestations.map((item) => item.kind))];
+	return {
+		...emptyProjection(),
+		record_revision: recordRevision,
+		workspace_revision: workspaceRevision,
+		intent_revision: record.intent_snapshot.revision,
+		intent_content_hash: record.intent_ref.content_hash,
+		lifecycle: record.lifecycle,
+		artifact_state: "frozen",
+		risk: record.intent_snapshot.risk,
+		fresh_acceptance_ids: freshAcceptanceIds,
+		fresh_approval_kinds: approvalKinds,
+		completion_ready: record.lifecycle === "done",
+	};
+}
+
 function freshApprovalKinds(
 	record: TaskRecord,
 	currentIntentContentHash: string,
@@ -168,6 +212,8 @@ function projectFromRecord(
 		(finding) => finding.kind === "unresolved_user_decision" && finding.status === "open",
 	).length;
 	return {
+		// Filled by the caller from the committed run row.
+		run_id: null,
 		record_revision: recordRevision,
 		workspace_revision: workspaceRevision,
 		intent_revision: record.intent_snapshot.revision,
@@ -232,9 +278,19 @@ export async function projectAssurance(
 			const tombstone = readTaskTombstone(root, taskId);
 			if (tombstone) {
 				const authority = reconcileKernelAuthority(root, taskId);
-				if (authority.state === "repairable_stale_claim")
+				// A terminal proof keyed by task id may have been exported by
+				// another worktree's run of this same task: it is that run's
+				// evidence, not a conflict with this worktree's own run. The local
+				// store decides, and an active local run keeps its authority.
+				if (authority.state === "active_owner") {
+					// fall through: the local run owns this task here
+				} else if (authority.state === "repairable_stale_claim")
 					return fail(`task ${taskId} has a repairable stale backend claim`, claim);
-				return fail(authority.diagnostic ?? `authority state conflicts for ${taskId}`, claim);
+				else
+					return fail(
+						authority.diagnostic ?? `authority state conflicts for ${taskId}`,
+						claim,
+					);
 			}
 		} else {
 			const authority = reconcileKernelAuthority(root, taskId);
@@ -254,6 +310,28 @@ export async function projectAssurance(
 		}
 		if (!read.record) {
 			if (!terminalOwner) return fail(`task ${taskId} has no TaskRecord v3`, claim);
+			const committedRunId = reconcileKernelAuthority(root, taskId).owner_run_id;
+			// The store keeps the terminal record itself, so a settled task projects
+			// from committed facts even while its audit export is still in flight.
+			const committed = await readCommittedRecord(root, taskId);
+			if (committed) {
+				const workspace = await readWorkspaceStateRaw(root);
+				return {
+					contract: "assurance_kernel/assurance_projection/v1",
+					task_id: taskId,
+					error: null,
+					claim: null,
+					projection: {
+						...projectFromRecord(
+							committed.record,
+							committed.revision,
+							workspace.revision,
+							diffProvider(root, committed.record),
+						),
+						run_id: committedRunId,
+					},
+				};
+			}
 			const auditPair = await readAuditTaskPair(root, taskId);
 			if (!auditPair) return fail(`task ${taskId} has no terminal audit pair`, claim);
 			const workspace = await readWorkspaceStateRaw(root);
@@ -265,6 +343,14 @@ export async function projectAssurance(
 					claim: null,
 					projection: projectHistoricalTerminal(auditPair.record, auditPair.recordRevision, workspace.revision),
 				};
+			if (auditPair.record.contract === "assurance_kernel/task_record/v3")
+				return {
+					contract: "assurance_kernel/assurance_projection/v1",
+					task_id: taskId,
+					error: null,
+					claim: null,
+					projection: projectHistoricalTerminalV3(auditPair.record, auditPair.recordRevision, workspace.revision),
+				};
 			return {
 				contract: "assurance_kernel/assurance_projection/v1",
 				task_id: taskId,
@@ -284,7 +370,10 @@ export async function projectAssurance(
 			task_id: taskId,
 			error: null,
 			claim,
-			projection: projectFromRecord(read.record, read.revision, workspace.revision, snapshot),
+			projection: {
+				...projectFromRecord(read.record, read.revision, workspace.revision, snapshot),
+				run_id: reconcileKernelAuthority(root, taskId).owner_run_id,
+			},
 		};
 	} catch (error) {
 		return fail(error instanceof Error ? error.message : String(error));