holo-codex 0.1.0 → 0.1.2

package/plugins/autonomous-pr-loop/core/hook-policy.ts

@@ -19,6 +19,7 @@ export interface HookPolicyInput {
   isWorker?: boolean;
   protectedPaths?: string[];
   storage?: AgentLoopStorage;
+  runId?: string;
 }
 
 export interface HookPolicyDecision {
@@ -28,8 +29,19 @@ export interface HookPolicyDecision {
   blockedCommand: string;
   nextAction: string;
   reason: string;
+  auditDetails?: Record<string, unknown>;
 }
 
+type MaintainerOverrideScope = "publish" | "merge";
+
+interface ActiveMaintainerOverride {
+  decisionId: string;
+  scope: MaintainerOverrideScope;
+  expiresAt: string;
+}
+
+const REQUIRED_PUBLISH_EVIDENCE_SUBSTAGES = ["lint", "full_tests", "gitnexus_detect"] as const;
+
 /** Normalize a Codex PreToolUse hook payload into an argv-like command. */
 export function commandFromHookPayload(payload: unknown): HookCommand | undefined {
   if (!isRecord(payload)) {
@@ -50,7 +62,12 @@ export function commandFromHookPayload(payload: unknown): HookCommand | undefine
 
 /** Evaluate a hook command without spawning subprocesses. */
 export function evaluateHookPolicy(input: HookPolicyInput): HookPolicyDecision {
-  const command = unwrapCommand(normalizeCommand(input.command));
+  const normalized = normalizeCommand(input.command);
+  const shellControl = shellControlPolicy(normalized);
+  if (shellControl) {
+    return deny(renderCommand(normalized), shellControl, "policy_violation", "Run one allowlisted command at a time without shell control operators.");
+  }
+  const command = unwrapCommand(normalized);
   const blockedCommand = renderCommand(command);
   const destructive = destructivePolicy(command);
   if (destructive) {
@@ -67,10 +84,25 @@ export function evaluateHookPolicy(input: HookPolicyInput): HookPolicyDecision {
   if (protectedPath) {
     return deny(blockedCommand, protectedPath, "policy_violation", "Remove protected path changes from the command.");
   }
-  const gate = gatedLifecyclePolicy(command, input.storage);
+  const gate = gatedLifecyclePolicy(command, input.storage, input.runId);
   if (gate) {
     return deny(blockedCommand, gate.policy, gate.gate, gate.nextAction);
   }
+  const override = activeMaintainerOverride(input.storage, lifecycleOverrideScope(command), input.runId);
+  if (override && matchesHookAllowlist(command)) {
+    return {
+      allow: true,
+      matchedPolicy: `maintainer_override:${override.scope}`,
+      blockedCommand,
+      nextAction: "Continue.",
+      reason: `Maintainer override ${override.decisionId} allows ${blockedCommand} until ${override.expiresAt}.`,
+      auditDetails: {
+        overrideDecisionId: override.decisionId,
+        overrideScope: override.scope,
+        overrideExpiresAt: override.expiresAt
+      }
+    };
+  }
   if (!matchesHookAllowlist(command)) {
     return deny(blockedCommand, "command_not_in_hook_allowlist", "policy_violation", "Use agent-loop MCP/CLI control surfaces or an allowlisted read/check command.");
   }
@@ -123,7 +155,13 @@ export function evaluatePreToolUseHook(payload: unknown, repoRoot?: string): Hoo
   try {
     const config = loadConfig(route.binding.repoRoot).config;
     storage = new SqliteAgentLoopStorage(statePath(route.binding.repoRoot));
-    const decision = evaluateHookPolicy({ repoRoot: route.binding.repoRoot, command, storage, protectedPaths: config.protectedPaths });
+    const decision = evaluateHookPolicy({
+      repoRoot: route.binding.repoRoot,
+      command,
+      storage,
+      ...(route.binding.runId ? { runId: route.binding.runId } : {}),
+      protectedPaths: config.protectedPaths
+    });
     recordHookDecision(storage, decision, route.binding.runId);
     return decision;
   } catch (error) {
@@ -147,10 +185,8 @@ export function toCodexHookResponse(decision: HookPolicyDecision): Record<string
     return { continue: true };
   }
   return {
-    decision: "deny",
-    permissionDecision: "deny",
-    continue: false,
-    stopReason: decision.reason,
+    decision: "block",
+    reason: decision.reason,
     systemMessage: formatHookMessage(decision)
   };
 }
@@ -166,6 +202,7 @@ function recordHookDecision(storage: AgentLoopStorage, decision: HookPolicyDecis
       allow: decision.allow,
       matchedPolicy: decision.matchedPolicy,
       ...(decision.gate ? { gate: decision.gate } : {}),
+      ...(decision.auditDetails ? { auditDetails: decision.auditDetails } : {}),
       nextAction: decision.nextAction,
       commandLength: command.length,
       commandSha256: createHash("sha256").update(command).digest("hex"),
@@ -175,9 +212,11 @@ function recordHookDecision(storage: AgentLoopStorage, decision: HookPolicyDecis
 }
 
 function routeErrorDecision(command: HookCommand, reason: string): HookPolicyDecision {
-  const normalized = unwrapCommand(normalizeCommand(command));
+  const baseCommand = normalizeCommand(command);
+  const shellControl = shellControlPolicy(baseCommand);
+  const normalized = shellControl ? baseCommand : unwrapCommand(baseCommand);
   const blockedCommand = renderCommand(normalized);
-  const destructive = destructivePolicy(normalized);
+  const destructive = shellControl ?? destructivePolicy(normalized);
   if (destructive || lifecycleCommand(normalized)) {
     return deny(
       blockedCommand,
@@ -196,9 +235,11 @@ function routeErrorDecision(command: HookCommand, reason: string): HookPolicyDec
 }
 
 function routeSessionMismatchDecision(command: HookCommand, reason: string): HookPolicyDecision {
-  const normalized = unwrapCommand(normalizeCommand(command));
+  const baseCommand = normalizeCommand(command);
+  const shellControl = shellControlPolicy(baseCommand);
+  const normalized = shellControl ? baseCommand : unwrapCommand(baseCommand);
   const blockedCommand = renderCommand(normalized);
-  const destructive = destructivePolicy(normalized);
+  const destructive = shellControl ?? destructivePolicy(normalized);
   if (destructive || lifecycleCommand(normalized)) {
     return deny(
       blockedCommand,
@@ -222,7 +263,7 @@ function lifecycleCommand(command: HookCommand): boolean {
     command.file === "gh" && command.args[0] === "pr" && ["create", "ready", "merge"].includes(command.args[1] ?? "");
 }
 
-function gatedLifecyclePolicy(command: HookCommand, storage?: AgentLoopStorage): { policy: string; gate: AgentLoopGateKind; nextAction: string } | undefined {
+function gatedLifecyclePolicy(command: HookCommand, storage?: AgentLoopStorage, runId?: string): { policy: string; gate: AgentLoopGateKind; nextAction: string } | undefined {
   const args = stripGitGlobalOptions(command.args);
   const lifecycleCommand = command.file === "git" && args[0] === "commit" ||
     command.file === "git" && args[0] === "push" ||
@@ -238,22 +279,24 @@ function gatedLifecyclePolicy(command: HookCommand, storage?: AgentLoopStorage):
     };
   }
   const current = storage.getCurrentStatus();
-  const state = current.run?.currentState;
-  if (command.file === "git" && (args[0] === "commit" || args[0] === "push") && state !== "COMMIT_PUSH_PR") {
+  const run = runId ? storage.getRun(runId) : current.run;
+  const state = run?.currentState;
+  const override = activeMaintainerOverride(storage, lifecycleOverrideScope(command), runId);
+  if (command.file === "git" && (args[0] === "commit" || args[0] === "push") && state !== "COMMIT_PUSH_PR" && !override) {
     return {
       policy: "commit_push_state_gate",
       gate: current.gate?.kind ?? "policy_violation",
       nextAction: "Resume agent-loop until COMMIT_PUSH_PR owns publishing."
     };
   }
-  if (command.file === "git" && (args[0] === "commit" || args[0] === "push") && !publishPrerequisitesSatisfied(storage)) {
+  if (command.file === "git" && (args[0] === "commit" || args[0] === "push") && !publishPrerequisitesSatisfied(storage, runId)) {
     return {
       policy: "commit_push_prerequisite_gate",
       gate: "policy_violation",
       nextAction: "Run SELF_CHECK and GitNexus detect_changes through agent-loop before publishing."
     };
   }
-  if (command.file === "gh" && command.args[0] === "pr" && command.args[1] === "merge" && state !== "MERGE") {
+  if (command.file === "gh" && command.args[0] === "pr" && command.args[1] === "merge" && state !== "MERGE" && !override) {
     return {
       policy: "merge_state_gate",
       gate: current.gate?.kind ?? "merge_requires_confirmation",
@@ -263,6 +306,45 @@ function gatedLifecyclePolicy(command: HookCommand, storage?: AgentLoopStorage):
   return undefined;
 }
 
+function lifecycleOverrideScope(command: HookCommand): MaintainerOverrideScope | undefined {
+  const args = stripGitGlobalOptions(command.args);
+  if (command.file === "git" && (args[0] === "commit" || args[0] === "push")) {
+    return "publish";
+  }
+  if (command.file === "gh" && command.args[0] === "pr" && command.args[1] === "merge") {
+    return "merge";
+  }
+  return undefined;
+}
+
+function activeMaintainerOverride(storage: AgentLoopStorage | undefined, scope: MaintainerOverrideScope | undefined, runId?: string): ActiveMaintainerOverride | undefined {
+  if (!storage || !scope) {
+    return undefined;
+  }
+  const run = runId ? storage.getRun(runId) : storage.getCurrentRun();
+  if (!run) {
+    return undefined;
+  }
+  return storage.listDecisions(run.id)
+    .map((decision) => {
+      const details = objectDetails(decision.details);
+      const overrideScope = stringValue(details?.scope);
+      const expiresAt = stringValue(details?.expiresAt);
+      if (decision.kind !== "maintainer_override_approved" || !overrideScope || !expiresAt) {
+        return undefined;
+      }
+      if (overrideScope !== scope) {
+        return undefined;
+      }
+      const expiresAtMs = Date.parse(expiresAt);
+      if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now()) {
+        return undefined;
+      }
+      return { decisionId: decision.id, scope, expiresAt };
+    })
+    .find((override): override is ActiveMaintainerOverride => override !== undefined);
+}
+
 function destructivePolicy(command: HookCommand): string | undefined {
   const args = stripGitGlobalOptions(command.args);
   if (command.file === "git" && args[0] === "reset" && args.includes("--hard")) {
@@ -271,7 +353,11 @@ function destructivePolicy(command: HookCommand): string | undefined {
   if (command.file === "git" && args[0] === "clean" && args.some((arg) => /^-.*f/.test(arg))) {
     return "destructive_git_clean";
   }
-  if (command.file === "git" && args[0] === "push" && args.some((arg) => ["-f", "--force", "--force-with-lease"].includes(arg))) {
+  if (command.file === "git" && args[0] === "push" && args.some((arg) =>
+    ["-f", "-d", "--force", "--force-with-lease", "--mirror", "--delete"].includes(arg) ||
+    arg.startsWith("+") ||
+    /^:[^:]+/.test(arg)
+  )) {
     return "destructive_git_force_push";
   }
   if (command.file === "gh" && command.args[0] === "repo" && command.args[1] === "delete") {
@@ -304,24 +390,33 @@ function protectedPathPolicy(command: HookCommand, protectedPaths: string[]): st
 
 function matchesHookAllowlist(command: HookCommand): boolean {
   const args = stripGitGlobalOptions(command.args);
+  if (command.file === "rg" && matchesRipgrepAllowlist(command.args) || isApplyPatchCommand(command)) {
+    return true;
+  }
   if (command.file === "git") {
     return args[0] === "status" ||
       args[0] === "branch" && args[1] === "--show-current" ||
       args[0] === "rev-parse" ||
       args[0] === "diff" ||
+      ["log", "show"].includes(args[0] ?? "") ||
+      args[0] === "grep" && matchesGitGrepAllowlist(args.slice(1)) ||
+      args[0] === "switch" && args.length === 2 && typeof args[1] === "string" && !args[1].startsWith("-") ||
       args[0] === "add" && args[1] === "--" ||
       args[0] === "commit" && args[1] === "-m" ||
-      args[0] === "push" && args[1] === "-u";
+      args[0] === "push" && matchesGitPushAllowlist(args.slice(1));
   }
   if (command.file === "gh") {
     return command.args[0] === "auth" && command.args[1] === "status" ||
-      command.args[0] === "pr" && ["list", "view"].includes(command.args[1] ?? "") ||
+      command.args[0] === "pr" && ["list", "view", "checks"].includes(command.args[1] ?? "") ||
+      command.args[0] === "pr" && command.args[1] === "merge" && matchesGhPrMergeAllowlist(command.args.slice(2)) ||
       command.args[0] === "api" && command.args[1] === "graphql";
   }
   if (command.file === "pnpm") {
     return command.args[0] === "test" ||
       command.args[0] === "lint" ||
-      command.args[0] === "agent-loop" && ["status", "doctor", "logs"].includes(command.args[1] ?? "");
+      command.args[0] === "build:hooks" ||
+      command.args[0] === "build:mcp" ||
+      command.args[0] === "agent-loop" && matchesAgentLoopAllowlist(command.args.slice(1));
   }
   if (command.file === "npx") {
     return command.args[0] === "gitnexus" &&
@@ -333,6 +428,87 @@ function matchesHookAllowlist(command: HookCommand): boolean {
   return false;
 }
 
+function matchesRipgrepAllowlist(args: string[]): boolean {
+  return !args.some((arg) => arg === "--pre" || arg.startsWith("--pre="));
+}
+
+function matchesGitGrepAllowlist(args: string[]): boolean {
+  return !args.some((arg) =>
+    arg === "-O" ||
+    arg.startsWith("-O") ||
+    arg === "--open-files-in-pager" ||
+    arg.startsWith("--open-files-in-pager=")
+  );
+}
+
+function matchesGitPushAllowlist(args: string[]): boolean {
+  return args.length >= 3 &&
+    args[0] === "-u" &&
+    args.every((arg) => !["-f", "-d", "--force", "--force-with-lease", "--mirror", "--delete"].includes(arg) && !arg.startsWith("+") && !/^:[^:]+/.test(arg));
+}
+
+function matchesGhPrMergeAllowlist(args: string[]): boolean {
+  const allowedFlags = new Set(["--merge", "--squash", "--rebase", "--body", "--subject"]);
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? "";
+    if (["--admin", "--auto", "--delete-branch", "-d"].includes(arg)) {
+      return false;
+    }
+    if (arg.startsWith("--") && !allowedFlags.has(arg)) {
+      return false;
+    }
+    if ((arg === "--body" || arg === "--subject") && args[index + 1]) {
+      index += 1;
+    }
+  }
+  return args.some((arg) => ["--merge", "--squash", "--rebase"].includes(arg));
+}
+
+function isApplyPatchCommand(command: HookCommand): boolean {
+  return command.file === "apply_patch" || command.raw?.startsWith("*** Begin Patch") === true;
+}
+
+function matchesAgentLoopAllowlist(args: string[]): boolean {
+  if (["status", "doctor", "logs", "observe", "timeline", "workers", "stop"].includes(args[0] ?? "")) {
+    return true;
+  }
+  if (args[0] === "local") {
+    return args[1] === "doctor";
+  }
+  if (args[0] === "hooks") {
+    return ["doctor", "list"].includes(args[1] ?? "");
+  }
+  if (args[0] === "delivery") {
+    return ["bind", "stage"].includes(args[1] ?? "");
+  }
+  if (args[0] === "evidence") {
+    return args[1] === "append";
+  }
+  if (args[0] === "maintainer-override") {
+    return args[1] === "approve";
+  }
+  return false;
+}
+
+function shellControlPolicy(command: HookCommand): string | undefined {
+  if (isApplyPatchCommand(command)) {
+    return undefined;
+  }
+  if (command.raw && hasShellControlOperator(command.raw)) {
+    return "shell_control_operator_forbidden";
+  }
+  if (command.file === "env") {
+    const index = command.args.findIndex((arg) => !arg.includes("="));
+    if (index >= 0) {
+      return shellControlPolicy({ file: basename(command.args[index] ?? ""), args: command.args.slice(index + 1) });
+    }
+  }
+  if ((command.file === "sh" || command.file === "bash") && command.args[0] === "-c" && command.args[1] && hasShellControlOperator(command.args[1])) {
+    return "shell_control_operator_forbidden";
+  }
+  return undefined;
+}
+
 function deny(
   blockedCommand: string,
   matchedPolicy: string,
@@ -385,6 +561,10 @@ function tokenizeCommand(command: string): HookCommand {
   return { file: basename(file), args, raw: command };
 }
 
+function hasShellControlOperator(value: string): boolean {
+  return /&&|\|\||[;|<>\n\r]/.test(value);
+}
+
 function stripGitGlobalOptions(args: string[]): string[] {
   const result = [...args];
   while (result.length > 0) {
@@ -406,12 +586,35 @@ function stripGitGlobalOptions(args: string[]): string[] {
   return result;
 }
 
-function publishPrerequisitesSatisfied(storage: AgentLoopStorage): boolean {
-  const run = storage.getCurrentRun();
+function publishPrerequisitesSatisfied(storage: AgentLoopStorage, runId?: string): boolean {
+  const run = runId ? storage.getRun(runId) : storage.getCurrentRun();
   if (!run) {
     return false;
   }
-  return storage.hasRunCheck(run.id, "self_check") && storage.hasRunCheck(run.id, "gitnexus_detect_changes");
+  if (storage.hasRunCheck(run.id, "self_check") && storage.hasRunCheck(run.id, "gitnexus_detect_changes")) {
+    return true;
+  }
+  return publishWorkflowEvidenceSatisfied(storage, run.id);
+}
+
+function publishWorkflowEvidenceSatisfied(storage: AgentLoopStorage, runId: string): boolean {
+  const completed = new Set<string>();
+  for (const event of storage.listEvents(200)) {
+    const payload = objectDetails(event.payload);
+    if (
+      event.runId !== runId ||
+      event.kind !== "workflow_stage_evidence" ||
+      stringValue(payload?.stageId) !== "verify" ||
+      stringValue(payload?.status) !== "done"
+    ) {
+      continue;
+    }
+    const substageId = stringValue(payload?.substageId);
+    if (substageId) {
+      completed.add(substageId);
+    }
+  }
+  return REQUIRED_PUBLISH_EVIDENCE_SUBSTAGES.every((substageId) => completed.has(substageId));
 }
 
 function basename(value: string): string {
@@ -421,3 +624,7 @@ function basename(value: string): string {
 function stringValue(value: unknown): string | undefined {
   return typeof value === "string" && value.length > 0 ? value : undefined;
 }
+
+function objectDetails(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}

package/plugins/autonomous-pr-loop/core/local-install.ts

@@ -1,11 +1,11 @@
 import { createHash, randomUUID } from "node:crypto";
-import { execFileSync } from "node:child_process";
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { runCommand } from "./command.js";
 import { isRecord } from "./config.js";
 import { AgentLoopError } from "./errors.js";
+import { commandsReferencingLegacyPrivateRepo, inspectAgentLoopBinary, inspectBundledHooksConfig, redactDiagnosticText, type AgentLoopBinaryInspection, type BundledHooksConfigInspection } from "./hook-diagnostics.js";
 import { agentLoopRouterHookCommand, collectHookCommands, isLegacyAgentLoopHookCommand } from "./hook-installation.js";
 import { CODEX_HOOK_EVENTS, hookScriptName } from "./hook-events.js";
 import { hookRegistryPath, inspectHookRegistryLock, listHookBindings } from "./hook-router.js";
@@ -90,13 +90,19 @@ export interface LocalDoctorReport {
     realPath?: string;
     expectedPackageRoot: string;
     pointsToExpectedPackage: boolean;
+    referencesExpectedPackage: boolean;
+    legacyPrivateRepoReferences: string[];
+    readError?: string;
+    readTruncated?: boolean;
   };
   hooks: {
     hooksPath: string;
     hooksJsonError?: string;
+    bundledHooksConfig: BundledHooksConfigInspection;
     routerInstalled: boolean;
     missingRouterEvents: string[];
     legacyCommands: string[];
+    legacyPrivateRepoCommands: string[];
     routerCommandsPointToExpectedDist: boolean;
   };
   bindings: {
@@ -353,8 +359,7 @@ export function inspectLocalInstall(options: LocalInstallOptions): LocalDoctorRe
   const repoRoot = canonicalPath(options.repoRoot);
   const codexHome = codexHomePath();
   const hooksPath = join(codexHome, "hooks.json");
-  const binaryPath = firstPathBinary("agent-loop");
-  const realBinaryPath = binaryPath && existsSync(binaryPath) ? canonicalPath(binaryPath) : undefined;
+  const binary = inspectAgentLoopBinary(packageRoot);
   const hooks = inspectHooks(hooksPath, packageRoot);
   const bindings = inspectBindings(codexHome, repoRoot);
   const selfLinkPollution = detectSelfLinkPollution(packageRoot);
@@ -363,12 +368,7 @@ export function inspectLocalInstall(options: LocalInstallOptions): LocalDoctorRe
     packageRoot,
     repoRoot,
     codexHome,
-    binary: {
-      ...(binaryPath ? { path: binaryPath } : {}),
-      ...(realBinaryPath ? { realPath: realBinaryPath } : {}),
-      expectedPackageRoot: packageRoot,
-      pointsToExpectedPackage: realBinaryPath ? realBinaryPath.startsWith(packageRoot) : false
-    },
+    binary,
     hooks,
     bindings,
     selfLinkPollution
@@ -599,12 +599,15 @@ function inspectHooks(hooksPath: string, packageRoot: string): LocalDoctorReport
   const missingRouterEvents = CODEX_HOOK_EVENTS.filter((event) => !commands.includes(agentLoopRouterHookCommand(event, packageRoot)));
   const expectedDist = hookDistRoot(packageRoot);
   const routerCommands = commands.filter((command) => command.includes("autonomous-pr-loop/hooks/dist/"));
+  const bundledHooksConfig = inspectBundledHooksConfig(packageRoot);
   return {
     hooksPath,
     ...(hooksJsonError ? { hooksJsonError } : {}),
+    bundledHooksConfig,
     routerInstalled: missingRouterEvents.length === 0,
     missingRouterEvents,
-    legacyCommands: commands.filter(isLegacyAgentLoopHookCommand),
+    legacyCommands: commands.filter(isLegacyAgentLoopHookCommand).map(redactDiagnosticText),
+    legacyPrivateRepoCommands: commandsReferencingLegacyPrivateRepo(commands),
     routerCommandsPointToExpectedDist: routerCommands.length > 0 && routerCommands.every((command) => command.includes(expectedDist))
   };
 }
@@ -735,15 +738,6 @@ function gitStatus(cwd: string): string[] {
   return result.ok && result.stdout ? result.stdout.split(/\r?\n/).filter(Boolean) : [];
 }
 
-function firstPathBinary(name: string): string | undefined {
-  try {
-    const output = execFileSync("sh", ["-lc", `command -v ${name} || true`], { encoding: "utf8" }).trim();
-    return output || undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 function localInstallBackupsDir(): string {
   return join(codexHomePath(), "agent-loop", "backups");
 }

package/plugins/autonomous-pr-loop/core/storage.ts

@@ -602,6 +602,9 @@ export class SqliteAgentLoopStorage implements AgentLoopStorage {
       }
 
       const run = this.getRun(runId);
+      if (!run) {
+        throw new AgentLoopError("storage_error", `Run not found: ${runId}`);
+      }
       this.db
         .prepare(
           `insert into states (run_id, status, state, version, payload_json, created_at)
@@ -1562,7 +1565,7 @@ export class SqliteAgentLoopStorage implements AgentLoopStorage {
     return row.user_version;
   }
 
-  private getRun(runId: string): AgentLoopRun {
+  getRun(runId: string): AgentLoopRun | undefined {
     const row = this.db
       .prepare(
         `select id, status, current_state, version, branch, worktree_clean, started_at, stopped_at, created_at, updated_at
@@ -1570,10 +1573,7 @@ export class SqliteAgentLoopStorage implements AgentLoopStorage {
          where id = ?`
       )
       .get(runId) as RunRow | undefined;
-    if (!row) {
-      throw new AgentLoopError("storage_error", `Run not found: ${runId}`);
-    }
-    return fromRunRow(row);
+    return row ? fromRunRow(row) : undefined;
   }
 
   private getActiveRun(): AgentLoopRun | undefined {

package/plugins/autonomous-pr-loop/core/types.ts

@@ -474,6 +474,8 @@ export interface AgentLoopStorage {
   listRunChecks(runId: string): AgentLoopRunCheck[];
   /** Return the latest run by update time, if any exists. */
   getCurrentRun(): AgentLoopRun | undefined;
+  /** Fetch a run by stable id. */
+  getRun(runId: string): AgentLoopRun | undefined;
   /** List persisted runs newest-first. */
   listRuns(limit?: number): AgentLoopRun[];
   /** Run a group of read queries against one consistent SQLite snapshot. */

package/plugins/autonomous-pr-loop/core/workflow-board.ts

@@ -771,13 +771,15 @@ function buildStage(input: {
     status,
     actorChips: actorChipsForStage(input.definition.id, status, input.profileRoleMapping, input.stageMetadata),
     evidenceCounts: counts,
-    substages: input.definition.substages.map((substage, substageIndex) => ({
-      ...substage,
-      status: substageIndex === 0 && status === "active" ? "active" : status === "done" ? "done" : "pending",
-      evidenceCounts: counts,
-      latestEvidence: stageEvidence.slice(0, 3),
-      requiredEvidence: []
-    })),
+    substages: input.definition.id === "cleanup"
+      ? cleanupSubstages(input.definition, input.input, input.evidenceRefs, status)
+      : input.definition.substages.map((substage, substageIndex) => ({
+        ...substage,
+        status: substageIndex === 0 && status === "active" ? "active" : status === "done" ? "done" : "pending",
+        evidenceCounts: counts,
+        latestEvidence: stageEvidence.slice(0, 3),
+        requiredEvidence: []
+      })),
     latestAction: { label: status === "blocked" ? "Resolve blocker" : input.definition.nextAction, safeToRunFromDashboard: false, requiresConfirmation: false },
     blockers: [],
     nextAction: input.definition.nextAction
@@ -1343,14 +1345,36 @@ function satisfiedReviewEvidence(events: AgentLoopEvent[]): string | undefined {
 }
 
 function cleanupRows(input: WorkflowBoardInput): WorkflowCheckRow[] {
+  return cleanupSubstageRows(input);
+}
+
+function cleanupSubstages(
+  definition: (typeof WORKFLOW_STAGE_DEFINITIONS)[number],
+  input: WorkflowBoardInput,
+  refs: WorkflowEvidenceRef[],
+  stageStatus: WorkflowStageStatus
+): WorkflowBoardSubstage[] {
+  const rows = cleanupSubstageRows(input);
+  const firstIncompleteIndex = rows.findIndex((row) => row.status !== "passed" && row.status !== "skipped");
+  return definition.substages.map((substage, index) => {
+    const row = rows.find((item) => item.id === substage.id);
+    const latestEvidence = cleanupEvidenceRefs(input.events, refs, substage.id);
+    return {
+      ...substage,
+      status: row ? cleanupSubstageStatus(row, stageStatus, index === firstIncompleteIndex) : "pending",
+      evidenceCounts: evidenceCounts(latestEvidence),
+      latestEvidence,
+      requiredEvidence: []
+    };
+  });
+}
+
+function cleanupSubstageRows(input: WorkflowBoardInput): WorkflowCheckRow[] {
   const evidence = cleanupEvidenceBySubstage(input.events);
-  return [
-    cleanupCheck("pr_merged", "PR merged", "GitHub", evidence, input.pr?.state === "MERGED", input.pr?.state ?? "no PR link"),
-    cleanupCheck("switched_main", "Switched to main", "Codex", evidence),
-    cleanupCheck("pulled_latest", "Pulled latest", "Codex", evidence),
-    cleanupCheck("gitnexus_reindexed", "GitNexus index rebuilt", "GitNexus", evidence),
-    cleanupCheck("worktree_clean", "Worktree clean", "Codex", evidence, input.run?.worktreeClean === true, String(input.run?.worktreeClean ?? "unknown"))
-  ];
+  return cleanupDefinition().substages.map((substage) => {
+    const fallback = cleanupFallback(input, substage.id);
+    return cleanupCheck(substage.id, substage.label, cleanupOwner(substage.id), evidence, fallback.passed, fallback.evidence);
+  });
 }
 
 function cleanupCheck(
@@ -1368,6 +1392,46 @@ function cleanupCheck(
   return { id, label, status: fallbackPassed ? "passed" : "pending", evidence: fallbackEvidence, owner };
 }
 
+function cleanupSubstageStatus(row: WorkflowCheckRow, stageStatus: WorkflowStageStatus, isFirstIncomplete: boolean): WorkflowStageStatus {
+  if (row.status === "passed") return "done";
+  if (row.status === "failed") return "failed";
+  if (row.status === "blocked") return "blocked";
+  if (row.status === "skipped") return "skipped";
+  if (stageStatus === "active" && isFirstIncomplete) return "active";
+  return "pending";
+}
+
+function cleanupFallback(input: WorkflowBoardInput, substageId: string): { passed: boolean; evidence: string } {
+  if (substageId === "pr_merged") {
+    return { passed: input.pr?.state === "MERGED", evidence: input.pr?.state ?? "no PR link" };
+  }
+  if (substageId === "worktree_clean") {
+    return { passed: input.run?.worktreeClean === true, evidence: String(input.run?.worktreeClean ?? "unknown") };
+  }
+  return { passed: false, evidence: "no appended evidence" };
+}
+
+function cleanupOwner(substageId: string): string {
+  if (substageId === "pr_merged") return "GitHub";
+  if (substageId === "gitnexus_reindexed") return "GitNexus";
+  return "Codex";
+}
+
+function cleanupEvidenceRefs(events: AgentLoopEvent[], refs: WorkflowEvidenceRef[], substageId: string): WorkflowEvidenceRef[] {
+  const eventIds = new Set(events
+    .filter((event) => event.kind === WORKFLOW_EVIDENCE_KIND && payloadStage(event) === "cleanup" && payloadString(event, "substageId") === substageId)
+    .map((event) => event.id));
+  return refs.filter((ref) => eventIds.has(ref.id)).slice(0, 3);
+}
+
+function cleanupDefinition(): (typeof WORKFLOW_STAGE_DEFINITIONS)[number] {
+  const definition = STAGE_BY_ID.get("cleanup");
+  if (!definition) {
+    throw new AgentLoopError("invalid_config", "cleanup workflow stage definition is missing.");
+  }
+  return definition;
+}
+
 function cleanupEvidenceBySubstage(events: AgentLoopEvent[]): Map<string, AgentLoopEvent> {
   const bySubstage = new Map<string, AgentLoopEvent>();
   for (const event of [...events].sort((left, right) => right.seq - left.seq)) {

package/plugins/autonomous-pr-loop/hooks/dist/permission-request.js

@@ -923,6 +923,9 @@ var SqliteAgentLoopStorage = class {
         );
       }
       const run = this.getRun(runId);
+      if (!run) {
+        throw new AgentLoopError("storage_error", `Run not found: ${runId}`);
+      }
       this.db.prepare(
         `insert into states (run_id, status, state, version, payload_json, created_at)
            values (?, ?, ?, ?, null, ?)`
@@ -1696,10 +1699,7 @@ var SqliteAgentLoopStorage = class {
          from runs
          where id = ?`
     ).get(runId);
-    if (!row) {
-      throw new AgentLoopError("storage_error", `Run not found: ${runId}`);
-    }
-    return fromRunRow(row);
+    return row ? fromRunRow(row) : void 0;
   }
   getActiveRun() {
     const row = this.db.prepare(