holo-codex 0.1.0 → 0.1.2

package/docs/release-checklist.md

@@ -1,6 +1,6 @@
 # HOLO-Codex npm Release Checklist
 
-Use this checklist for npm releases such as `v0.1.0`.
+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
 ```
@@ -33,23 +33,52 @@ Expected result: no real tokens, no committed `.agent-loop/`, no raw hook payloa
 ## Tarball Smoke
 
 ```bash
-npm pack --ignore-scripts --json
+pack_json="$(npm pack --ignore-scripts --json)"
+tgz="$(node -e 'const fs = require("fs"); const pack = JSON.parse(fs.readFileSync(0, "utf8")); console.log(pack[0].filename)' <<< "$pack_json")"
+tar -xOf "$tgz" package/plugins/autonomous-pr-loop/hooks/hooks.json
+tar -xOf "$tgz" package/plugins/autonomous-pr-loop/hooks/hooks.json | node -e 'const fs = require("fs"); const hooks = JSON.parse(fs.readFileSync(0, "utf8")); const legacy = Object.keys(hooks).filter((key) => key !== "hooks"); if (!hooks.hooks || typeof hooks.hooks !== "object" || legacy.length) { console.error(JSON.stringify({ legacy }, null, 2)); process.exit(1); }'
 tmp="$(mktemp -d)"
 export CODEX_HOME="$tmp/codex-home"
 mkdir -p "$tmp/target-repo"
 git -C "$tmp/target-repo" init -b main
 git -C "$tmp/target-repo" remote add origin https://github.com/example/holo-codex-smoke.git
-npm install --prefix "$tmp/install" ./holo-codex-*.tgz
+npm install --prefix "$tmp/install" "./$tgz"
 "$tmp/install/node_modules/.bin/agent-loop" --help
 "$tmp/install/node_modules/.bin/agent-loop" --repo "$tmp/target-repo" init --json
 "$tmp/install/node_modules/.bin/agent-loop" install-hooks --repo "$tmp/target-repo" --json
 "$tmp/install/node_modules/.bin/agent-loop" --repo "$tmp/target-repo" local doctor --json
 ```
 
-Do not publish if this smoke fails.
+The extracted `hooks.json` must have a top-level `hooks` object and must not have legacy top-level hook event keys such as `PreToolUse`. Do not publish if this smoke fails.
 
 ## 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
@@ -126,11 +155,12 @@ Expected result: hooks and binding registry restore from the snapshot, non-agent
 After publish and post-publish smoke pass:
 
 ```bash
-git tag v0.1.0
-git push origin v0.1.0
-gh release create v0.1.0 \
+VERSION=0.1.2
+git tag "v$VERSION"
+git push origin "v$VERSION"
+gh release create "v$VERSION" \
   --repo tizerluo/HOLO-Codex \
-  --title "HOLO-Codex v0.1.0" \
+  --title "HOLO-Codex v$VERSION" \
   --notes-file /path/to/release-notes.md
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holo-codex",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Human On Loop Codex control plane for observable, recoverable Codex workflow loops.",
   "license": "MIT",
   "author": "tizerluo",
@@ -28,6 +28,7 @@
   "files": [
     "README.md",
     "README.zh-CN.md",
+    "CHANGELOG.md",
     "LICENSE",
     "SECURITY.md",
     "CONTRIBUTING.md",
@@ -59,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.0",
+  "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

@@ -10,6 +10,7 @@ import { startDashboardServer } from "./dashboard-server.js";
 import { runDoctor } from "./doctor.js";
 import { AgentLoopError, isGateCode, toErrorPayload, type AgentLoopErrorCode } from "./errors.js";
 import { recoverBlockedRun } from "./gate-recovery.js";
+import { commandsReferencingLegacyPrivateRepo, inspectAgentLoopBinary, inspectBundledHooksConfig, redactDiagnosticText, type AgentLoopBinaryInspection, type BundledHooksConfigInspection } from "./hook-diagnostics.js";
 import { agentLoopRouterHookEntries, collectHookCommands, isAgentLoopHookCommand, isLegacyAgentLoopHookCommand } from "./hook-installation.js";
 import { hookRegistryPath, inspectHookRegistryLock, listHookBindings, removeHookBinding, upsertHookBinding } from "./hook-router.js";
 import { inspectLocalInstall, installLocalAgentLoop, listLocalInstallSnapshots, pruneLocalInstallSnapshots, rollbackLocalAgentLoop } from "./local-install.js";
@@ -141,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);
     }
@@ -188,6 +192,7 @@ function helpResult(json: boolean, usage = "agent-loop <command> [options]"): Cl
     "hooks",
     "local",
     "approve-gate",
+    "maintainer-override",
     "dashboard",
     "evidence",
     "delivery"
@@ -217,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]"
@@ -239,7 +245,9 @@ const OPTIONS_WITH_VALUES = new Set([
   "--port",
   "--issue",
   "--ref",
+  "--reason",
   "--run",
+  "--scope",
   "--source",
   "--stage",
   "--status",
@@ -248,6 +256,7 @@ const OPTIONS_WITH_VALUES = new Set([
   "--substage",
   "--summary",
   "--title",
+  "--ttl-minutes",
   "--url",
   "--worker"
 ]);
@@ -714,6 +723,9 @@ function hooks(repoRoot: string, args: string[], json: boolean, localeOverride:
       report.routerInstalled ? "hook router installed" : "hook router missing",
       `active bindings: ${report.activeBindings}`,
       `legacy entries: ${report.legacyCommands.length}`,
+      `old private repo hook refs: ${report.legacyPrivateRepoCommands.length}`,
+      `bundled hooks config: ${report.bundledHooksConfig.valid ? "valid" : "invalid"}`,
+      `binary old private repo refs: ${report.agentLoopBinary.legacyPrivateRepoReferences.length}`,
       `hook capture: ${report.hookCapture.status} - ${report.hookCapture.reason}`
     ]);
   }
@@ -767,9 +779,12 @@ function local(repoRoot: string, args: string[], json: boolean): CliResult {
       "agent-loop local doctor",
       `binary: ${result.binary.path ?? "not found"}`,
       `binary points to expected package: ${result.binary.pointsToExpectedPackage ? "yes" : "no"}`,
+      `binary old private repo refs: ${result.binary.legacyPrivateRepoReferences.length}`,
+      `bundled hooks config: ${result.hooks.bundledHooksConfig.valid ? "valid" : "invalid"}`,
       `router installed: ${result.hooks.routerInstalled}`,
       `router points to expected dist: ${result.hooks.routerCommandsPointToExpectedDist ? "yes" : "no"}`,
       `legacy entries: ${result.hooks.legacyCommands.length}`,
+      `old private repo hook refs: ${result.hooks.legacyPrivateRepoCommands.length}`,
       `current repo bindings: ${result.bindings.currentRepoBindings}`,
       `stale/missing path bindings: ${result.bindings.staleOrMissingPathBindings}`,
       `temp path bindings: ${result.bindings.tempPathBindings}`,
@@ -913,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;
@@ -1123,6 +1202,9 @@ function hookInstallReport(repoRoot: string, packageRoot: string): {
   routerInstalled: boolean;
   missingRouterEvents: string[];
   legacyCommands: string[];
+  legacyPrivateRepoCommands: string[];
+  bundledHooksConfig: BundledHooksConfigInspection;
+  agentLoopBinary: AgentLoopBinaryInspection;
   activeBindings: number;
   currentRepoBindings: number;
   lock: ReturnType<typeof inspectHookRegistryLock>;
@@ -1145,7 +1227,10 @@ function hookInstallReport(repoRoot: string, packageRoot: string): {
   const missingRouterEvents = Object.entries(routerEntries)
     .filter(([, entries]) => !entries.some((entry) => hookCommands(entry).every((command) => commands.includes(command))))
     .map(([event]) => event);
-  const legacyCommands = commands.filter(isLegacyAgentLoopHookCommand);
+  const legacyCommands = commands.filter(isLegacyAgentLoopHookCommand).map(redactDiagnosticText);
+  const legacyPrivateRepoCommands = commandsReferencingLegacyPrivateRepo(commands);
+  const bundledHooksConfig = inspectBundledHooksConfig(packageRoot);
+  const agentLoopBinary = inspectAgentLoopBinary(packageRoot);
   let bindings: ReturnType<typeof listHookBindings>;
   let registryError: string | undefined;
   try {
@@ -1164,6 +1249,9 @@ function hookInstallReport(repoRoot: string, packageRoot: string): {
     routerInstalled: hooksJsonError === undefined && missingRouterEvents.length === 0,
     missingRouterEvents,
     legacyCommands,
+    legacyPrivateRepoCommands,
+    bundledHooksConfig,
+    agentLoopBinary,
     activeBindings,
     currentRepoBindings,
     lock,

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

@@ -5,6 +5,7 @@ import { redactRemote, runCommand } from "./command.js";
 import { loadConfig, statePath } from "./config.js";
 import { AgentLoopError } from "./errors.js";
 import { inspectHookCapture } from "./hook-capture.js";
+import { commandsReferencingLegacyPrivateRepo, inspectAgentLoopBinary, inspectBundledHooksConfig, redactDiagnosticText } 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";
@@ -202,10 +203,17 @@ function checkHooksInstalled(repoRoot: string, pluginRoot: string): DoctorCheck
   }
   const commands = collectHookCommands(parsedHooks);
   const missing = CODEX_HOOK_EVENTS.filter((event) => !commands.includes(agentLoopRouterHookCommand(event, pluginRoot)));
-  const legacyCommands = commands.filter(isLegacyAgentLoopHookCommand);
+  const legacyCommands = commands.filter(isLegacyAgentLoopHookCommand).map(redactDiagnosticText);
   const expectedDist = hookDistRoot(pluginRoot);
   const routerCommands = commands.filter((command) => command.includes("autonomous-pr-loop/hooks/dist/"));
-  const unexpectedRouterCommands = routerCommands.filter((command) => !command.includes(expectedDist));
+  const unexpectedRouterCommands = routerCommands
+    .filter((command) => !command.includes(expectedDist))
+    .map(redactDiagnosticText);
+  const bundledHooksConfig = inspectBundledHooksConfig(pluginRoot);
+  const agentLoopBinary = inspectAgentLoopBinary(pluginRoot);
+  const legacyPrivateRepoCommands = commandsReferencingLegacyPrivateRepo(commands);
+  const legacyPrivateRepoDrift =
+    legacyPrivateRepoCommands.length > 0 || agentLoopBinary.legacyPrivateRepoReferences.length > 0;
   let bindings: ReturnType<typeof listHookBindings>;
   let registryError: string | undefined;
   try {
@@ -221,10 +229,12 @@ function checkHooksInstalled(repoRoot: string, pluginRoot: string): DoctorCheck
   const installed = missing.length === 0;
   const routerDistDrift = unexpectedRouterCommands.length > 0;
   const captureWarn = capture.status === "ambiguous" || capture.status === "unavailable";
-  const status = !installed ? "warn" : routerDistDrift || registryError || lock.stale || legacyCommands.length > 0 || currentRepoBindings.length === 0 || captureWarn ? "warn" : "pass";
+  const status = !installed ? "warn" : routerDistDrift || !bundledHooksConfig.valid || legacyPrivateRepoDrift || registryError || lock.stale || legacyCommands.length > 0 || currentRepoBindings.length === 0 || captureWarn ? "warn" : "pass";
   const message = hookInstallMessage({
     installed,
     routerDistDrift,
+    bundledHooksConfigValid: bundledHooksConfig.valid,
+    legacyPrivateRepoDrift,
     registryError,
     lockStale: lock.stale,
     lockPath: lock.path,
@@ -247,6 +257,9 @@ function checkHooksInstalled(repoRoot: string, pluginRoot: string): DoctorCheck
       legacyCommands,
       routerCommandsPointToExpectedDist: routerCommands.length > 0 && unexpectedRouterCommands.length === 0,
       unexpectedRouterCommands,
+      bundledHooksConfig,
+      agentLoopBinary,
+      legacyPrivateRepoCommands,
       activeBindings: activeBindings.length,
       currentRepoBindings: currentRepoBindings.length,
       lock,
@@ -260,6 +273,8 @@ function checkHooksInstalled(repoRoot: string, pluginRoot: string): DoctorCheck
 function hookInstallMessage(input: {
   installed: boolean;
   routerDistDrift: boolean;
+  bundledHooksConfigValid: boolean;
+  legacyPrivateRepoDrift: boolean;
   registryError: string | undefined;
   lockStale: boolean;
   lockPath: string;
@@ -268,28 +283,37 @@ function hookInstallMessage(input: {
   installCommand: string;
   codexHome: string;
 }): string {
+  const suffix = input.legacyPrivateRepoDrift
+    ? " Also, hook commands still reference the old private repo."
+    : "";
+  if (!input.bundledHooksConfigValid) {
+    return `Bundled plugin hooks config is not valid for current Codex. Reinstall or refresh the HOLO-Codex plugin after fixing hooks/hooks.json.${suffix}`;
+  }
   if (!input.installed && input.routerDistDrift) {
-    return `Codex hook router is not installed at the expected hook dist; existing router commands point outside the expected hook dist. Run \`${input.installCommand}\` to refresh router hooks and bind this repo.`;
+    return `Codex hook router is not installed at the expected hook dist; existing router commands point outside the expected hook dist. Run \`${input.installCommand}\` to refresh router hooks and bind this repo.${suffix}`;
   }
   if (!input.installed) {
-    return `Codex hook router is not installed. Run \`${input.installCommand}\` to install router hooks and bind this repo.`;
+    return `Codex hook router is not installed. Run \`${input.installCommand}\` to install router hooks and bind this repo.${suffix}`;
   }
   if (input.routerDistDrift) {
-    return `Codex hook router includes commands outside the expected hook dist. Run \`${input.installCommand}\` to refresh router hooks.`;
+    return `Codex hook router includes commands outside the expected hook dist. Run \`${input.installCommand}\` to refresh router hooks.${suffix}`;
   }
   if (input.registryError) {
-    return `Codex hook binding registry is not valid. Fix ${hookRegistryPath(input.codexHome)}, then run \`${input.installCommand}\`.`;
+    return `Codex hook binding registry is not valid. Fix ${hookRegistryPath(input.codexHome)}, then run \`${input.installCommand}\`.${suffix}`;
   }
   if (input.lockStale) {
-    return `Codex hook binding registry lock appears stale. Remove ${input.lockPath} or rerun after the stale writer exits.`;
+    return `Codex hook binding registry lock appears stale. Remove ${input.lockPath} or rerun after the stale writer exits.${suffix}`;
   }
   if (input.legacyCommands.length > 0) {
-    return `Codex hook router is installed, but legacy per-repo agent-loop hooks remain. Run \`${input.installCommand}\` to migrate them.`;
+    return `Codex hook router is installed, but legacy per-repo agent-loop hooks remain. Run \`${input.installCommand}\` to migrate them.${suffix}`;
+  }
+  if (input.legacyPrivateRepoDrift) {
+    return `Codex hook setup still references the old private repo. Run \`${input.installCommand}\` from the canonical HOLO-Codex workspace and reinstall the global CLI if needed.`;
   }
   if (input.currentRepoBindings.length === 0) {
-    return `Codex hook router is installed, but this repo is not bound. Run \`${input.installCommand}\`.`;
+    return `Codex hook router is installed, but this repo is not bound. Run \`${input.installCommand}\`.${suffix}`;
   }
-  return "HOLO-Codex hook router is installed and this repo has an active binding.";
+  return `HOLO-Codex hook router is installed and this repo has an active binding.${suffix}`;
 }
 
 function installHooksCommand(repoRoot: string): string {

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

@@ -0,0 +1,153 @@
+import { execFileSync } from "node:child_process";
+import { closeSync, existsSync, openSync, readFileSync, readSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { CODEX_HOOK_EVENTS } from "./hook-events.js";
+import { redactSecrets } from "./redaction.js";
+
+export const LEGACY_PRIVATE_REPO_MARKER = "codex-auto-PR-loop-plusin";
+const BINARY_READ_LIMIT_BYTES = 128 * 1024;
+
+export interface BundledHooksConfigInspection {
+  path: string;
+  valid: boolean;
+  legacyTopLevelEvents: string[];
+  error?: string;
+}
+
+export interface AgentLoopBinaryInspection {
+  path?: string;
+  realPath?: string;
+  expectedPackageRoot: string;
+  pointsToExpectedPackage: boolean;
+  referencesExpectedPackage: boolean;
+  legacyPrivateRepoReferences: string[];
+  readError?: string;
+  readTruncated?: boolean;
+}
+
+/** Inspect the plugin-bundled Codex hooks config without mutating plugin cache or user config. */
+export function inspectBundledHooksConfig(packageRoot: string): BundledHooksConfigInspection {
+  const path = join(packageRoot, "plugins", "autonomous-pr-loop", "hooks", "hooks.json");
+  if (!existsSync(path)) {
+    return {
+      path,
+      valid: false,
+      legacyTopLevelEvents: [],
+      error: "missing bundled hooks config"
+    };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    if (!isRecord(parsed)) {
+      return { path, valid: false, legacyTopLevelEvents: [], error: "expected JSON object" };
+    }
+    const legacyTopLevelEvents = CODEX_HOOK_EVENTS.filter((event) => event in parsed);
+    if (!isRecord(parsed.hooks)) {
+      return {
+        path,
+        valid: false,
+        legacyTopLevelEvents,
+        error: "expected top-level hooks object"
+      };
+    }
+    return {
+      path,
+      valid: legacyTopLevelEvents.length === 0,
+      legacyTopLevelEvents,
+      ...(legacyTopLevelEvents.length > 0 ? { error: "legacy top-level hook events are not valid bundled hook config" } : {})
+    };
+  } catch (error) {
+    return {
+      path,
+      valid: false,
+      legacyTopLevelEvents: [],
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+/** Inspect the first PATH agent-loop binary for source-install drift. */
+export function inspectAgentLoopBinary(expectedPackageRoot: string): AgentLoopBinaryInspection {
+  const path = firstPathBinary("agent-loop");
+  const realPath = path && existsSync(path) ? realpathSync(path) : undefined;
+  let text = "";
+  let readError: string | undefined;
+  let readTruncated = false;
+  if (path && existsSync(path)) {
+    try {
+      const result = readTextPrefix(path, BINARY_READ_LIMIT_BYTES);
+      text = result.text;
+      readTruncated = result.truncated;
+    } catch (error) {
+      readError = error instanceof Error ? error.message : String(error);
+    }
+  }
+  const referencesExpectedPackage = text.includes(expectedPackageRoot);
+  const legacyPrivateRepoReferences = [
+    ...(path?.includes(LEGACY_PRIVATE_REPO_MARKER) ? [path] : []),
+    ...(realPath?.includes(LEGACY_PRIVATE_REPO_MARKER) ? [realPath] : []),
+    ...text.split(/\r?\n/).filter((line) => line.includes(LEGACY_PRIVATE_REPO_MARKER))
+  ].map(redactDiagnosticText);
+  return {
+    ...(path ? { path } : {}),
+    ...(realPath ? { realPath } : {}),
+    expectedPackageRoot,
+    pointsToExpectedPackage: (realPath ? realPath.startsWith(expectedPackageRoot) : false) || referencesExpectedPackage,
+    referencesExpectedPackage,
+    legacyPrivateRepoReferences,
+    ...(readError ? { readError } : {}),
+    ...(readTruncated ? { readTruncated } : {})
+  };
+}
+
+export function commandsReferencingLegacyPrivateRepo(commands: string[]): string[] {
+  return commands
+    .filter((command) => command.includes(LEGACY_PRIVATE_REPO_MARKER))
+    .map(redactDiagnosticText);
+}
+
+export function redactDiagnosticText(value: string): string {
+  return redactLegacyPrivateRepoPaths(redactSecrets(value));
+}
+
+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 isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function redactLegacyPrivateRepoPaths(value: string): string {
+  const marker = escapeRegExp(LEGACY_PRIVATE_REPO_MARKER);
+  const unixPath = new RegExp(`(?:/[^\\s'"=]+)*/${marker}(?:/[^\\s'"]*)?`, "g");
+  const windowsPath = new RegExp(`(?:[A-Za-z]:\\\\[^\\s'"=]+\\\\)*${marker}(?:\\\\[^\\s'"]*)?`, "g");
+  return value
+    .replace(unixPath, "<legacy-private-repo-path>")
+    .replace(windowsPath, "<legacy-private-repo-path>");
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function readTextPrefix(path: string, limitBytes: number): { text: string; truncated: boolean } {
+  const size = statSync(path).size;
+  const length = Math.min(size, limitBytes);
+  const buffer = Buffer.alloc(length);
+  const fd = openSync(path, "r");
+  try {
+    const bytesRead = readSync(fd, buffer, 0, length, 0);
+    return {
+      text: buffer.subarray(0, bytesRead).toString("utf8"),
+      truncated: size > bytesRead
+    };
+  } finally {
+    closeSync(fd);
+  }
+}