holo-codex 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.2
+
+- Added the manual GitHub Actions Release workflow for npm Trusted Publishing, dry-run tarball validation, and registry install smoke.
+- Added audited maintainer override support for lifecycle gates so verified release and merge operations can proceed with recorded evidence.
+- Relaxed the hook allowlist for maintainer-owned commands after verified evidence is present.
+- Hardened Codex hook and MCP startup compatibility for current Codex configurations.
+- Fixed dashboard Cleanup status consistency so sidebar substages and the main cleanup checklist use the same cleanup evidence.
+- Added the `next_issue_selected` cleanup checklist item to keep cleanup progress complete and visible.
+- Validated the release path with the existing GitHub Actions Release workflow, tarball checks, and dashboard smoke requirements.
+- Kept #16, #17, #18, and #19 as follow-up improvements outside this release-prep PR.
+
 ## 0.1.1
 
 - Fixed the bundled Codex plugin hooks schema for newer Codex config parsers.

package/docs/release-checklist.md

@@ -1,6 +1,6 @@
 # HOLO-Codex npm Release Checklist
 
-Use this checklist for npm releases such as `v0.1.1`. Replace `VERSION` with the package version being released.
+Use this checklist for npm releases such as `v0.1.2`. Replace `VERSION` with the package version being released.
 
 The public source release remains available at `https://github.com/tizerluo/HOLO-Codex`. The npm package is `holo-codex` and installs the stable `agent-loop` CLI. Compatibility identifiers remain unchanged: `agent-loop`, `.agent-loop/`, `autonomous-pr-loop`, and `plugins/autonomous-pr-loop/`.
 
@@ -12,7 +12,7 @@ Run from the release checkout:
 pnpm install --frozen-lockfile
 pnpm build:hooks
 pnpm lint
-pnpm test
+pnpm exec vitest run --no-file-parallelism --maxWorkers=1
 npm pack --ignore-scripts --dry-run --json
 npm view holo-codex name version dist-tags --json || true
 ```
@@ -53,6 +53,32 @@ The extracted `hooks.json` must have a top-level `hooks` object and must not hav
 
 ## Publish
 
+### GitHub Actions CD
+
+For `v0.1.2` and later, prefer the manual Release workflow:
+
+1. Configure npm Trusted Publishing for package `holo-codex`:
+   - Provider: GitHub Actions
+   - Repository: `tizerluo/HOLO-Codex`
+   - Workflow file: `release.yml`
+   - Allowed action: `npm publish`
+   - Environment: leave blank unless the workflow is later changed to use one.
+2. Run the `Release` workflow from `main` with:
+   - `version`: the exact `package.json` version
+   - `tag`: blank to use `v<version>`, or an explicit tag
+   - `dry_run`: `true` first
+3. Inspect the dry-run artifact and logs.
+4. Re-run with `dry_run: false` to publish with npm provenance and create the GitHub Release.
+
+The workflow uses GitHub OIDC (`id-token: write`) instead of a long-lived npm token. It runs on Node 24 and installs npm `^11.5.1` in both validation and publish jobs, satisfying the npm Trusted Publishing floor of Node 22.14.0+ and npm 11.5.1+.
+Dry runs may use an already-published version to test the workflow shape; real releases fail if the npm version or Git tag already exists.
+Dry runs validate inputs, run the stable Vitest suite, pack the tarball, verify hook schema, smoke the packed tarball, and upload the release candidate. The workflow checks existing npm versions through retried registry HTTP status codes instead of parsing npm CLI error text. The publish job re-verifies the downloaded tarball integrity against `holo-pack.json` before `npm publish`.
+Dry runs do not execute `npm publish`, so the first `dry_run: false` run is the first real Trusted Publishing/OIDC validation.
+After a real publish, the workflow creates the Git tag and GitHub Release before the registry install smoke. That keeps the release recoverable even if npm registry propagation makes the smoke temporarily fail.
+The manual fallback below is intentionally separate from Trusted Publishing. It may not create provenance unless npm supports it in the local environment and the maintainer explicitly chooses that path.
+
+### Manual fallback
+
 Confirm npm authentication without printing tokens:
 
 ```bash
@@ -129,7 +155,7 @@ Expected result: hooks and binding registry restore from the snapshot, non-agent
 After publish and post-publish smoke pass:
 
 ```bash
-VERSION=0.1.1
+VERSION=0.1.2
 git tag "v$VERSION"
 git push origin "v$VERSION"
 gh release create "v$VERSION" \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holo-codex",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Human On Loop Codex control plane for observable, recoverable Codex workflow loops.",
   "license": "MIT",
   "author": "tizerluo",
@@ -60,7 +60,8 @@
   "scripts": {
     "agent-loop": "tsx plugins/autonomous-pr-loop/scripts/agent-loop.ts",
     "build:hooks": "esbuild plugins/autonomous-pr-loop/hooks/pre-tool-use.ts plugins/autonomous-pr-loop/hooks/post-tool-use.ts plugins/autonomous-pr-loop/hooks/user-prompt-submit.ts plugins/autonomous-pr-loop/hooks/stop.ts plugins/autonomous-pr-loop/hooks/session-start.ts plugins/autonomous-pr-loop/hooks/pre-compact.ts plugins/autonomous-pr-loop/hooks/post-compact.ts plugins/autonomous-pr-loop/hooks/permission-request.ts --bundle --platform=node --format=esm --outdir=plugins/autonomous-pr-loop/hooks/dist",
-    "prepack": "pnpm build:hooks",
+    "build:mcp": "esbuild plugins/autonomous-pr-loop/mcp-server/src/index.ts --bundle --platform=node --format=esm --outfile=plugins/autonomous-pr-loop/mcp-server/dist/index.js",
+    "prepack": "pnpm build:hooks && pnpm build:mcp",
     "test": "vitest run",
     "lint": "tsc --noEmit"
   },

package/plugins/autonomous-pr-loop/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "autonomous-pr-loop",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Human On Loop Codex control plane for observable, recoverable Codex workflow loops.",
   "skills": "./skills/",
   "interface": {

package/plugins/autonomous-pr-loop/.mcp.json

@@ -2,11 +2,9 @@
   "mcpServers": {
     "autonomous-pr-loop": {
       "cwd": ".",
-      "command": "pnpm",
+      "command": "node",
       "args": [
-        "exec",
-        "tsx",
-        "./mcp-server/src/index.ts"
+        "./mcp-server/dist/index.js"
       ]
     }
   }

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

@@ -142,6 +142,9 @@ export async function runAgentLoopCli(
     if (command === "approve-gate") {
       return approveGate(targetRepoRoot, filtered, json, localeOverride);
     }
+    if (command === "maintainer-override") {
+      return maintainerOverride(targetRepoRoot, filtered, json);
+    }
     if (command === "evidence") {
       return evidence(targetRepoRoot, filtered, json, localeOverride);
     }
@@ -189,6 +192,7 @@ function helpResult(json: boolean, usage = "agent-loop <command> [options]"): Cl
     "hooks",
     "local",
     "approve-gate",
+    "maintainer-override",
     "dashboard",
     "evidence",
     "delivery"
@@ -218,6 +222,7 @@ function commandHelpUsage(command: string): string | undefined {
     hooks: "agent-loop hooks install-router|bind|list|doctor|unbind [--session SESSION_ID] [--run RUN_ID] [--json]",
     local: "agent-loop local install|rollback|doctor|snapshots [--repo /path/to/repo] [--snapshot PATH] [--json]",
     "approve-gate": "agent-loop approve-gate <gate-id> --note \"...\" [--next-state STATE] [--json]",
+    "maintainer-override": "agent-loop maintainer-override approve --scope publish|merge --reason \"...\" [--ttl-minutes N] [--run RUN_ID] [--json]",
     dashboard: "agent-loop dashboard [--host 127.0.0.1] [--port 0] [--json]",
     evidence: "agent-loop evidence append --stage STAGE --summary \"...\" [--run RUN_ID] [--substage ID] [--actor ACTOR] [--status STATUS] [--source SOURCE] [--ref REF] [--artifact ID] [--json]",
     delivery: "agent-loop delivery bind|stage [options] [--json]"
@@ -240,7 +245,9 @@ const OPTIONS_WITH_VALUES = new Set([
   "--port",
   "--issue",
   "--ref",
+  "--reason",
   "--run",
+  "--scope",
   "--source",
   "--stage",
   "--status",
@@ -249,6 +256,7 @@ const OPTIONS_WITH_VALUES = new Set([
   "--substage",
   "--summary",
   "--title",
+  "--ttl-minutes",
   "--url",
   "--worker"
 ]);
@@ -920,6 +928,70 @@ function approveGate(repoRoot: string, args: string[], json: boolean, localeOver
   }
 }
 
+function maintainerOverride(repoRoot: string, args: string[], json: boolean): CliResult {
+  const subcommand = args[1];
+  const scope = optionArg(args, "--scope");
+  const reason = optionArg(args, "--reason");
+  const ttlMinutes = maintainerOverrideTtlMinutes(args);
+  if (subcommand !== "approve") {
+    throw new AgentLoopError("unknown_command", "Usage: agent-loop maintainer-override approve --scope publish|merge --reason \"...\" [--ttl-minutes N] [--run RUN_ID]");
+  }
+  if (scope !== "publish" && scope !== "merge") {
+    throw new AgentLoopError("invalid_config", "maintainer-override approve requires --scope publish|merge.");
+  }
+  if (!reason || reason.trim().length === 0) {
+    throw new AgentLoopError("invalid_config", "maintainer-override approve requires --reason.");
+  }
+  const storage = new SqliteAgentLoopStorage(statePath(repoRoot));
+  try {
+    const runId = optionArg(args, "--run") ?? storage.getCurrentRun()?.id;
+    if (!runId) {
+      throw new AgentLoopError("invalid_config", "maintainer-override approve requires an active run or --run.");
+    }
+    if (!storage.getRun(runId)) {
+      throw new AgentLoopError("invalid_config", `maintainer-override run ${runId} was not found.`);
+    }
+    const actor = process.env.USER ?? process.env.LOGNAME ?? "unknown";
+    const expiresAt = new Date(Date.now() + ttlMinutes * 60_000).toISOString();
+    const details = {
+      scope,
+      reason,
+      actor,
+      source: "cli",
+      expiresAt,
+      ttlMinutes
+    };
+    const decision = storage.appendDecision({
+      runId,
+      kind: "maintainer_override_approved",
+      message: `Maintainer override approved for ${scope}.`,
+      details
+    });
+    const event = storage.appendEvent({
+      runId,
+      kind: "maintainer_override_approved",
+      message: `Maintainer override approved for ${scope}.`,
+      payload: details
+    });
+    return ok(json, { ok: true, decision, event, scope, expiresAt }, [
+      `maintainer override: ${scope}`,
+      `expires: ${expiresAt}`,
+      `reason: ${reason}`
+    ]);
+  } finally {
+    storage.close();
+  }
+}
+
+function maintainerOverrideTtlMinutes(args: string[]): number {
+  const value = optionArg(args, "--ttl-minutes") ?? "30";
+  const ttl = Number(value);
+  if (!Number.isInteger(ttl) || ttl < 1 || ttl > 120) {
+    throw new AgentLoopError("invalid_config", "maintainer-override --ttl-minutes must be an integer from 1 to 120.");
+  }
+  return ttl;
+}
+
 function gateState(details: unknown): string | undefined {
   if (typeof details !== "object" || details === null || Array.isArray(details)) return undefined;
   const state = (details as { state?: unknown }).state;

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/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 {