immune-brain 2.8.2 → 3.0.1

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

@@ -15,6 +15,8 @@ import {
 	KernelStoreSecurityError,
 	appendJournalEntry,
 	readSecureProjectFile,
+	readTaskRecordRaw,
+	readWorkspaceStateRaw,
 	type JournalEntry,
 	type JournalReasonCode,
 	type TaskPhase,
@@ -23,7 +25,12 @@ import {
 	INTENT_MAX_BYTES,
 	canonicalIntentHash,
 	parseTaskIntentV1,
+	RISK_FLOOR_SCOPE_PREFIXES,
 } from "../kernel/intent";
+import { projectTask, resolveProjectedRisk } from "../kernel/completion";
+import { deriveAssuranceAuthorization } from "../kernel/assurance_projection";
+import { taskDiffIdentity, taskRevisionIdentity } from "../workspace_scope";
+import type { TaskIntentV1, TaskRisk } from "../kernel/types";
 import {
 	canonicalDescriptorBytes,
 	parseVerificationDescriptor,
@@ -152,6 +159,202 @@ function runStatus(root: string): KernelExecution {
 	}
 }
 
+const UNOBSERVABLE = {
+	capability: "unobservable",
+	rehearsal: "unobservable",
+	cas_holder: "unobservable",
+} as const;
+
+const RISK_ORDER: Record<TaskRisk, number> = {
+	routine: 0,
+	material: 1,
+	critical: 2,
+};
+
+function matchingFloorEntries(intent: TaskIntentV1): string[] {
+	return intent.scope_hint.filter((entry) => {
+		try {
+			const trial = parseTaskIntentV1({
+				contract: intent.contract,
+				task_id: intent.task_id,
+				goal: intent.goal,
+				acceptance: intent.acceptance,
+				scope_hint: [entry],
+				risk: "routine",
+				revision: intent.revision,
+				owner: "user",
+			});
+			return trial.risk !== "routine";
+		} catch {
+			return false;
+		}
+	});
+}
+
+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;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * `inspect --json` is a read-only Inspect Projection. It never journals,
+ * never takes a Kernel store lock, and never becomes authority.
+ */
+function runInspect(root: string): KernelExecution {
+	try {
+		const layout = inspectStorageLayout(root);
+		const claim = readBackendClaim(root);
+		const workspace = readWorkspaceOwner(root);
+		const kernel = {
+			claim: claim
+				? {
+						task_id: claim.task_id,
+						lifecycle_status: claim.lifecycle_status,
+					}
+				: null,
+			workspace: { current_working: workspace },
+		};
+		const idleRisk = {
+			declared: null as TaskRisk | null,
+			resolved: null as TaskRisk | null,
+			floor_prefixes: [...RISK_FLOOR_SCOPE_PREFIXES],
+			floor_applied: false,
+			matching_scope_entries: [] as string[],
+		};
+		const ok = layout.layout === "ready" || layout.layout === "migration_uncommitted";
+		if (!claim || !ok || layout.layout !== "ready") {
+			return {
+				result: jsonResult({
+					contract: "assurance_kernel/inspect/v1",
+					layout,
+					kernel,
+					assurance: null,
+					risk: idleRisk,
+					unobservable: UNOBSERVABLE,
+				}),
+				journal: journalFor(
+					"inspect",
+					null,
+					ok ? "ok" : "escalated",
+					layout.layout === "ready" ? "command_ok" : "source_invalid",
+					null,
+					layout.reason,
+				),
+			};
+		}
+		let declared: TaskRisk;
+		let intent: TaskIntentV1;
+		try {
+			const raw = JSON.parse(
+				readSecureProjectFile(root, `docs/plans/${claim.task_id}.intent.json`),
+			) as { risk?: unknown };
+			if (raw.risk !== "routine" && raw.risk !== "material" && raw.risk !== "critical")
+				throw new Error(`intent.risk is unreadable for ${claim.task_id}`);
+			declared = raw.risk;
+			intent = parseTaskIntentV1(raw);
+		} catch (error) {
+			return sourceFailure("inspect", error);
+		}
+		let recordRead: ReturnType<typeof readTaskRecordRaw>;
+		try {
+			recordRead = readTaskRecordRaw(root, claim.task_id);
+		} catch (error) {
+			return sourceFailure("inspect", error);
+		}
+		if (!recordRead.record) {
+			return {
+				result: errorResult(
+					"source_read_failed",
+					`task ${claim.task_id} has no TaskRecord`,
+					1,
+				),
+				journal: journalFor(
+					"inspect",
+					null,
+					"rejected",
+					"source_read_failed",
+					claim.task_id,
+					"Resolve the claimed TaskRecord before retrying inspect.",
+				),
+			};
+		}
+		const record = recordRead.record;
+		const workspaceState = readWorkspaceStateRaw(root);
+		let identity;
+		try {
+			identity =
+				record.contract === "assurance_kernel/task_record/v4"
+					? taskRevisionIdentity(root, intent.scope_hint, record.git_base_head)
+					: taskDiffIdentity(root, intent.scope_hint);
+		} catch (error) {
+			return sourceFailure("inspect", error);
+		}
+		const diffHash = identity.diff_hash;
+		const changedPaths = identity.changed_paths;
+		const decision = projectTask(intent, record, diffHash, record.intent_ref.content_hash, changedPaths);
+		const openUserDecisionCount = record.findings.filter(
+			(finding) => finding.kind === "unresolved_user_decision" && finding.status === "open",
+		).length;
+		const resolved = resolveProjectedRisk(intent, changedPaths);
+		return {
+			result: jsonResult({
+				contract: "assurance_kernel/inspect/v1",
+				layout,
+				kernel,
+				assurance: {
+					contract: "assurance_kernel/assurance_projection/v1",
+					task_id: claim.task_id,
+					error: null,
+					claim: kernel.claim,
+					projection: {
+						record_revision: recordRead.revision,
+						workspace_revision: workspaceState.revision,
+						intent_revision: intent.revision,
+						intent_content_hash: record.intent_ref.content_hash,
+						diff_hash: diffHash,
+						lifecycle: record.lifecycle,
+						artifact_state: record.artifact_state,
+						risk: resolveProjectedRisk(intent, changedPaths),
+						next_obligation: decision.next_obligation,
+						fresh_acceptance_ids: decision.fresh_acceptance_ids,
+						missing_acceptance_ids: decision.missing_acceptance_ids,
+						stale_attestation_ids: decision.stale_attestation_ids,
+						fresh_approval_kinds: [],
+						missing_approval_kinds: decision.missing_approval_kinds,
+						blocking_finding_ids: decision.blocking_finding_ids,
+						unresolved_user_decision_ids: decision.unresolved_user_decision_ids,
+						replan_required_ids: decision.replan_required_ids,
+						independence_violations: decision.independence_violations,
+						open_user_decision_count: openUserDecisionCount,
+						completion_ready: decision.complete,
+						authorization: deriveAssuranceAuthorization({
+							next_obligation: decision.next_obligation,
+							open_user_decision_count: openUserDecisionCount,
+						}),
+					},
+				},
+				risk: {
+					declared,
+					resolved,
+					floor_prefixes: [...RISK_FLOOR_SCOPE_PREFIXES],
+					floor_applied: RISK_ORDER[resolved] > RISK_ORDER[declared],
+					matching_scope_entries: matchingFloorEntries(intent),
+				},
+				unobservable: UNOBSERVABLE,
+			}),
+			journal: journalFor("inspect", null, "ok", "command_ok", claim.task_id, null),
+		};
+	} catch (error) {
+		return sourceFailure("inspect", error);
+	}
+}
+
 const INTENT_SIDECAR_PREFIX = "docs/plans/";
 const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 
@@ -1024,6 +1227,21 @@ function executeKernelCommand(args: string[], root: string): KernelExecution {
 			};
 		return runStatus(root);
 	}
+	if (command === "inspect") {
+		if (flags.length !== 1 || flags[0] !== "--json")
+			return {
+				result: errorResult("invalid_command", "inspect accepts only --json", 2),
+				journal: journalFor(
+					command,
+					null,
+					"rejected",
+					"invalid_command",
+					null,
+					"Run imm-kernel inspect --json.",
+				),
+			};
+		return runInspect(root);
+	}
 	if (command === "audit") {
 		if (args.length !== 2 || args[1] !== "--legacy")
 			return {
@@ -1097,7 +1315,7 @@ function executeKernelCommand(args: string[], root: string): KernelExecution {
 		return {
 			result: {
 				stdout:
-					"usage: imm-kernel status --json\n       imm-kernel audit --legacy\n       imm-kernel intent author <path> --stdin --json\n       imm-kernel intent validate <path> --json\n",
+					"usage: imm-kernel status --json\n       imm-kernel inspect --json\n       imm-kernel audit --legacy\n       imm-kernel intent author <path> --stdin --json\n       imm-kernel intent validate <path> --json\n",
 				stderr: "",
 				returncode: 0,
 			},
@@ -1106,7 +1324,7 @@ function executeKernelCommand(args: string[], root: string): KernelExecution {
 	return {
 		result: errorResult(
 			"invalid_command",
-			"usage: imm-kernel status --json | audit --legacy | intent author <path> --stdin --json | intent validate <path> --json",
+			"usage: imm-kernel status --json | inspect --json | audit --legacy | intent author <path> --stdin --json | intent validate <path> --json",
 
 			2,
 		),
@@ -1130,7 +1348,7 @@ export function runKernelCommand(
 	// subcommands (migrate/readiness/journal) are no-journal: they never
 	// append the friction journal. Only the fallback unknown-command path
 	// keeps journaling.
-	if (["intent", "status", "audit", "migrate", "readiness", "journal"].includes(args[0] ?? ""))
+	if (["intent", "status", "inspect", "audit", "migrate", "readiness", "journal"].includes(args[0] ?? ""))
 		return execution.result;
 	let warning = "";
 	try {

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

@@ -8,9 +8,10 @@ const PROTOCOL_MARKER = "<!-- immune-brain-tracker:v1 -->";
 const KIND_INITIATIVE_MARKER = "<!-- immune-brain:kind=initiative -->";
 const KIND_TASK_MARKER = "<!-- immune-brain:kind=task -->";
 const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const MAX_GH_OUTPUT = 1024 * 1024;
+const MAX_GH_OUTPUT = 8 * 1024 * 1024;
 const MAX_DIAGNOSTIC = 512;
 const GH_TIMEOUT_MS = 20_000;
+const MAX_SNAPSHOT_PAGES = 100;
 const GITHUB_ISSUE_BODY_LIMIT = 65_536;
 const MAX_TERMINAL_EVENT_ID = 500;
 
@@ -348,19 +349,33 @@ async function snapshot(root: string, gh: GhTransport, operation: TrackerOperati
 	} catch (error) {
 		return result(operation, "permanent_failure", error instanceof Error ? error.message : String(error));
 	}
-	const issuesExecution = await gh.run([
-		"api",
-		"--paginate",
-		"--slurp",
-		`repos/${repository.name_with_owner}/issues?state=all&per_page=100`,
-	], { cwd: root });
-	if (issuesExecution.exit_code !== 0 || issuesExecution.output_exceeded)
-		return ghFailure(operation, issuesExecution, "cannot query GitHub Issues");
-	try {
-		return { repository, issues: parseIssues(issuesExecution.stdout) };
-	} catch (error) {
-		return result(operation, "permanent_failure", error instanceof Error ? error.message : String(error));
+	// ponytail: paginated fetch avoids single 1MiB slurp blob; 100 issues/page * 8MiB handles 65KB bodies without hitting limit
+	const issues: GithubIssue[] = [];
+	for (let page = 1; page <= MAX_SNAPSHOT_PAGES; page += 1) {
+		const issuesExecution = await gh.run(
+			["api", `repos/${repository.name_with_owner}/issues?state=all&per_page=100&page=${page}`],
+			{ cwd: root },
+		);
+		if (issuesExecution.exit_code !== 0 || issuesExecution.output_exceeded)
+			return ghFailure(operation, issuesExecution, "cannot query GitHub Issues");
+		let raw: unknown;
+		try {
+			raw = JSON.parse(issuesExecution.stdout);
+		} catch (error) {
+			return result(operation, "permanent_failure", error instanceof Error ? error.message : String(error));
+		}
+		if (!Array.isArray(raw)) return result(operation, "permanent_failure", "gh returned malformed Issue list");
+		const pageCount = raw.length;
+		try {
+			issues.push(...parseIssues(issuesExecution.stdout));
+		} catch (error) {
+			return result(operation, "permanent_failure", error instanceof Error ? error.message : String(error));
+		}
+		if (pageCount < 100) break;
+		if (page === MAX_SNAPSHOT_PAGES)
+			return result(operation, "permanent_failure", "too many GitHub Issues to snapshot");
 	}
+	return { repository, issues };
 }
 
 function findIssue(issues: GithubIssue[], primary: string[], required: string[]): IssueLookup {

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

@@ -8,6 +8,7 @@ import {
 	type MutationAuthorityRegistry,
 	type ValidatedAuthorityV2,
 } from "./authority_port";
+import { asTaskDiffSnapshot } from "./completion";
 import { canonicalIntentHash, readTaskIntent } from "./intent";
 import {
 	inspectIntentTokenPair,
@@ -38,6 +39,7 @@ import type {
 	StoredTaskMutationV3,
 	TaskAction,
 	TaskIntentV1,
+	TaskRecord,
 } from "./types";
 import { TASK_TOMBSTONE_CONTRACT, type TaskTombstone } from "./backend_claim";
 import { KernelInvariantError, parseTaskAction } from "./validation";
@@ -51,7 +53,7 @@ export interface ApplyTaskActionInput {
 	registry: MutationAuthorityRegistry;
 	capability?: MutationAuthorityCapabilityV2;
 	/** Trusted injected diff provider; the action's diff_hash is only an expectation. */
-	diffProvider: (root: string, intent: TaskIntentV1) => string;
+	diffProvider: (root: string, record: TaskRecord) => string | { diff_hash: string; changed_paths?: readonly string[] };
 	now?: number;
 	/**
 	 * Terminal commit mode: record + workspace + active-claim removal + task
@@ -89,10 +91,10 @@ export function applyTaskAction(
 		// closed before any token or capability is consumed.
 
 		// Trusted diff provider is the only diff authority.
-		const diffHash = diffProvider(root, current.record.intent_snapshot);
-		if (diffHash !== action.diff_hash)
+		const trustedDiff = asTaskDiffSnapshot(diffProvider(root, current.record));
+		if (trustedDiff.diff_hash !== action.diff_hash)
 			throw new KernelInvariantError([
-				`action diff_hash ${action.diff_hash} does not match the trusted diff ${diffHash}`,
+				`action diff_hash ${action.diff_hash} does not match the trusted diff ${trustedDiff.diff_hash}`,
 			]);
 
 		// Fresh secure reread of the sidecar inside the same lock.
@@ -173,7 +175,7 @@ export function applyTaskAction(
 					intent_content_hash: isRevisionAction
 						? freshRead.content_hash
 						: current.record.intent_ref.content_hash,
-					diff_hash: diffHash,
+					diff_hash: trustedDiff.diff_hash,
 					...(action.type === "request_rework"
 						? { findings_digest: findingsDigestV2(action.findings) }
 						: {}),
@@ -191,6 +193,7 @@ export function applyTaskAction(
 			current.record,
 			action,
 			inspectedAudit ? (inspectedAudit.audit as AuthorityAuditDescriptor) : null,
+			trustedDiff.changed_paths,
 		);
 		if (!isReducedMutation(mutation))
 			throw new KernelInvariantError(["reducer returned an invalid mutation"]);

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

@@ -13,8 +13,13 @@
 
 import { readBackendClaim, readTaskTombstone } from "./backend_claim";
 import { readTaskRecord, readAuditTaskPair, readWorkspaceStateRaw, reconcileKernelAuthority } from "./storage";
-import { projectTask } from "./completion";
-import type { AssuranceObligation, TaskIntentV1, TaskRecordV2, TaskRecordV3 } from "./types";
+import { projectTask, resolveProjectedRisk } from "./completion";
+import type { AssuranceObligation, TaskIntentV1, TaskRecord, TaskRecordV2 } from "./types";
+
+export interface TaskDiffSnapshot {
+	diff_hash: string;
+	changed_paths: readonly string[];
+}
 
 export interface AssuranceAuthorizationReadiness {
 	/**
@@ -127,7 +132,7 @@ function projectHistoricalTerminal(
 }
 
 function freshApprovalKinds(
-	record: TaskRecordV3,
+	record: TaskRecord,
 	currentIntentContentHash: string,
 	diffHash: string,
 ): string[] {
@@ -148,14 +153,20 @@ function freshApprovalKinds(
 }
 
 function projectFromRecord(
-	record: TaskRecordV3,
+	record: TaskRecord,
 	recordRevision: string,
 	workspaceRevision: string,
-	diffHash: string,
+	snapshot: TaskDiffSnapshot,
 ): AssuranceProjection {
 	const intent: TaskIntentV1 = record.intent_snapshot;
-	const decision = projectTask(intent, record, diffHash, record.intent_ref.content_hash);
-	const approvalKinds = freshApprovalKinds(record, record.intent_ref.content_hash, diffHash);
+	const decision = projectTask(
+		intent,
+		record,
+		snapshot.diff_hash,
+		record.intent_ref.content_hash,
+		snapshot.changed_paths,
+	);
+	const approvalKinds = freshApprovalKinds(record, record.intent_ref.content_hash, snapshot.diff_hash);
 	const openUserDecisionCount = record.findings.filter(
 		(finding) => finding.kind === "unresolved_user_decision" && finding.status === "open",
 	).length;
@@ -164,10 +175,10 @@ function projectFromRecord(
 		workspace_revision: workspaceRevision,
 		intent_revision: record.intent_snapshot.revision,
 		intent_content_hash: record.intent_ref.content_hash,
-		diff_hash: diffHash,
+		diff_hash: snapshot.diff_hash,
 		lifecycle: record.lifecycle,
 		artifact_state: record.artifact_state,
-		risk: intent.risk,
+		risk: resolveProjectedRisk(intent, snapshot.changed_paths),
 		next_obligation: decision.next_obligation,
 		fresh_acceptance_ids: decision.fresh_acceptance_ids,
 		missing_acceptance_ids: decision.missing_acceptance_ids,
@@ -203,7 +214,7 @@ function projectFromRecord(
 export async function projectAssurance(
 	root: string,
 	taskId: string,
-	diffProvider: (root: string, intent: { scope_hint?: unknown }) => string,
+	diffProvider: (root: string, record: TaskRecord) => TaskDiffSnapshot,
 ): Promise<AssuranceProjectionResult> {
 	const fail = (
 		error: string,
@@ -262,7 +273,7 @@ export async function projectAssurance(
 				task_id: taskId,
 				error: null,
 				claim: null,
-				projection: projectFromRecord(auditPair.record, auditPair.recordRevision, workspace.revision, diffProvider(root, auditPair.record.intent_snapshot)),
+				projection: projectFromRecord(auditPair.record, auditPair.recordRevision, workspace.revision, diffProvider(root, auditPair.record)),
 			};
 		}
 		if (read.record.task_id !== taskId)
@@ -270,13 +281,13 @@ export async function projectAssurance(
 		if (claim && read.record.lifecycle !== "active")
 			return fail(`terminal task ${taskId} has no matching tombstone proof`, claim);
 		const workspace = await readWorkspaceStateRaw(root);
-		const diffHash = diffProvider(root, read.record.intent_snapshot);
+		const snapshot = diffProvider(root, read.record);
 		return {
 			contract: "assurance_kernel/assurance_projection/v1",
 			task_id: taskId,
 			error: null,
 			claim,
-			projection: projectFromRecord(read.record, read.revision, workspace.revision, diffHash),
+			projection: projectFromRecord(read.record, read.revision, workspace.revision, snapshot),
 		};
 	} catch (error) {
 		return fail(error instanceof Error ? error.message : String(error));