holo-codex 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.1
+
+- Fixed the bundled Codex plugin hooks schema for newer Codex config parsers.
+- Kept stable runtime identifiers unchanged: `agent-loop`, `.agent-loop/`, and `autonomous-pr-loop`.
+
+## 0.1.0
+
+- Initial public npm release of HOLO-Codex.

package/README.md

@@ -4,62 +4,109 @@
 
 ![HOLO-Codex README hero](./assets/brand/holo-codex-readme-hero.png)
 
-HOLO-Codex, short for **Human On Loop Codex**, turns long-running Codex workflows into observable, recoverable, human-on-loop systems. The operator sets goals and boundaries, observes progress, and steps in only when a real gate needs attention.
+[![npm version](https://img.shields.io/npm/v/holo-codex?color=0f766e)](https://www.npmjs.com/package/holo-codex)
+[![npm downloads](https://img.shields.io/npm/dm/holo-codex)](https://www.npmjs.com/package/holo-codex)
+[![GitHub release](https://img.shields.io/github/v/release/tizerluo/HOLO-Codex)](https://github.com/tizerluo/HOLO-Codex/releases)
+[![CI](https://github.com/tizerluo/HOLO-Codex/actions/workflows/ci.yml/badge.svg)](https://github.com/tizerluo/HOLO-Codex/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+![Node >=22.5](https://img.shields.io/badge/node-%3E%3D22.5-339933)
 
-The supervisor owns durable workflow state, evidence, gates, worker orchestration, Codex hooks, the MCP control plane, and the local dashboard. Workers perform scoped tasks and return structured output.
+HOLO-Codex, short for **Human On Loop Codex**, turns long-running Codex workflows into observable, recoverable systems that you can supervise without living inside chat history.
 
-## What It Provides
+Codex can plan, edit, test, review, and hand work across agents. HOLO-Codex gives that work a local control plane: workflow state, evidence, gates, hooks, review status, recovery actions, and a dashboard you can open while the work is running.
 
-- A Codex plugin under `plugins/autonomous-pr-loop/`.
-- The `agent-loop` CLI for local loop state, hooks, dashboard, workflow evidence, and rollback-safe local install.
-- Local SQLite state under `.agent-loop/`.
-- A local dashboard for Mission Control, workflow board, observability, gates, review/CI state, workers, artifacts, recovery, notifications, policy config, and theme modes.
-- stdio MCP control plane.
-- Codex hooks for policy checks and observability.
-- TypeScript + Vitest test suite.
-- Bilingual display support for `zh-CN`, `en-US`, and `system` locale selection.
-- Workflow profiles, role profiles, `generic-loop`, and the first bundled workflow: `pr-loop`.
+## Quickstart
 
-This is not a hosted service. It does not run GitHub webhooks or cloud workers.
+Install the package and attach HOLO-Codex to a target repository:
 
-## Compatibility Names
+```bash
+npm install --global holo-codex
+agent-loop --repo /path/to/repo init
+agent-loop install-hooks --repo /path/to/repo
+agent-loop --repo /path/to/repo dashboard
+```
+
+Open the printed loopback URL. The dashboard unlocks locally without putting a token in the URL.
 
-HOLO-Codex is the public product name. Some stable runtime identifiers intentionally keep their legacy names for compatibility:
+Plugin enablement is separate from the CLI install:
 
-- CLI command: `agent-loop`
-- Runtime state directory: `.agent-loop/`
-- Plugin id and MCP server id: `autonomous-pr-loop`
-- Source directory: `plugins/autonomous-pr-loop/`
-- npm package name: `holo-codex`
-- Local marketplace entry name: `codex-auto-pr-loop`
+```bash
+codex plugin marketplace add "$(npm root -g)/holo-codex"
+```
 
-Do not treat those names as a second product. They are compatibility identifiers.
+Then enable the `autonomous-pr-loop` plugin in Codex. The CLI is called `agent-loop` for compatibility.
 
-## First Workflow: PR Delivery
+## Why HOLO-Codex?
+
+| Problem | What HOLO-Codex adds |
+| --- | --- |
+| Long Codex tasks disappear into a thread. | A workflow board shows the current stage, state source, evidence, and next action. |
+| Manual decisions, review reports, and CI signals live in different places. | Evidence is recorded as append-only workflow events and surfaced in the dashboard. |
+| Recovery gets hard after a pause, gate, failed worker, or context switch. | Gates, recovery actions, timeline, artifacts, and hook diagnostics stay tied to the run. |
+
+## What It Gives You
+
+- Workflow Board for long Codex workflows, including stage status, evidence counts, and current-stage details.
+- Evidence Trail for plans, implementation notes, tests, reviews, PR actions, CI checks, merge readiness, and cleanup.
+- Gates and Recovery for policy blocks, human approval, stale runs, and historical gate re-evaluation.
+- Hook-based Observability that routes Codex hook events by repo, worktree, and session context.
+- Local Dashboard for Mission Control, observability, gates, review/CI state, workers, artifacts, notifications, policy config, and theme modes.
+- CLI and stdio MCP control plane for scripts, skills, and Codex plugin actions.
+- Review and CI visibility through structured review evidence, severity summaries, PR comment links, and merge readiness checks.
+
+HOLO-Codex is local-first. It is not a hosted service, and it does not run cloud workers or GitHub webhooks for you.
 
-PR delivery is the first complete workflow shipped with HOLO-Codex. It is the strongest sample of the loop model, not the product boundary.
+## How It Fits Together
 
-Typical flow:
+```mermaid
+flowchart LR
+  A["Codex skill or commander"] --> B["agent-loop CLI / MCP"]
+  B --> C["Local workflow state<br/>.agent-loop SQLite"]
+  B --> D["Codex hooks<br/>repo / worktree / session routing"]
+  C --> E["Dashboard workflow board"]
+  D --> E
+  E --> F["Gates and recovery"]
+  E --> G["Review, CI, PR, cleanup evidence"]
+```
+
+The dashboard and MCP tools read persisted loop state. They do not depend on the chat transcript being intact.
+
+## First Workflow: PR Delivery
+
+PR delivery is the first bundled workflow. It is the strongest sample today, not the product boundary.
 
 ```text
-sync main
-bind work item
-plan
-build
-verify
-open PR
-run review / CI
-fix findings
-check merge readiness
-merge
-cleanup
+Work Item -> Plan -> Build -> Verify -> PR -> Review -> Merge Readiness -> Cleanup
 ```
 
-The dashboard and MCP tools read persisted loop state. They do not rely on chat history.
+The bundled PR workflow can bind a GitHub issue, track implementation evidence, collect tester and reviewer reports, show PR and CI readiness, and keep cleanup visible after merge.
+
+The same control-plane model can support other long-running Codex workflows:
+
+- release preparation
+- repo hygiene
+- security review
+- docs publishing
+- migrations
+- evaluations
+- customer issue triage
+
+## Compatibility Names
+
+HOLO-Codex is the public product name. Some runtime identifiers keep older names so existing installs and local state do not break:
 
-The same control-plane model can support other long-running Codex workflows such as release preparation, repo hygiene, security review, docs publishing, migrations, evaluations, and customer-issue triage.
+| Public concept | Stable identifier |
+| --- | --- |
+| CLI command | `agent-loop` |
+| Runtime state directory | `.agent-loop/` |
+| Plugin id and MCP server id | `autonomous-pr-loop` |
+| Source directory | `plugins/autonomous-pr-loop/` |
+| npm package | `holo-codex` |
+| Local marketplace entry | `codex-auto-pr-loop` |
 
-## Install
+These are compatibility identifiers, not separate products.
+
+## Install Details
 
 Canonical public source:
 
@@ -74,69 +121,56 @@ Requirements:
 - GitHub CLI `gh`
 - Codex CLI / plugin support
 - `pnpm` when installing from source or using rollback-snapshot local install
-- Optional but recommended: GitNexus via `npx gitnexus`
+- Optional: GitNexus via `npx gitnexus`
 
 Install from npm:
 
 ```bash
 npm install --global holo-codex
-# Replace /path/to/repo with the repository you want HOLO-Codex to supervise.
 agent-loop --repo /path/to/repo init
 agent-loop install-hooks --repo /path/to/repo
 agent-loop --repo /path/to/repo doctor
 ```
 
-The npm package installs the `agent-loop` CLI. `agent-loop install-hooks` installs or refreshes the hook router and target binding without reinstalling the global CLI. To remove an npm install, run `agent-loop hooks unbind --repo /path/to/repo`, remove HOLO-Codex router entries from `~/.codex/hooks.json` only when no target repositories still use them, and then run `npm uninstall --global holo-codex`.
+The npm package installs the `agent-loop` CLI. `agent-loop install-hooks` installs or refreshes the hook router and target binding without reinstalling the global CLI.
+
+To remove an npm install:
+
+```bash
+agent-loop hooks unbind --repo /path/to/repo
+npm uninstall --global holo-codex
+```
+
+Remove HOLO-Codex router entries from `~/.codex/hooks.json` only when no target repositories still use them.
 
-Install from source when developing HOLO-Codex or when you want to inspect the source checkout directly:
+Install from source when developing HOLO-Codex or when you want to inspect the checkout:
 
 ```bash
 git clone https://github.com/tizerluo/HOLO-Codex.git
 cd HOLO-Codex
 pnpm install
 pnpm build:hooks
-# Replace /path/to/repo with the repository you want HOLO-Codex to supervise.
 pnpm agent-loop local install --repo /path/to/repo
 agent-loop --repo /path/to/repo status
 ```
 
-`pnpm agent-loop ...` is the source checkout command. `agent-loop ...` is the global convenience command for day-to-day use from any directory after npm or local source install. Use `agent-loop local snapshots prune --keep 10` to preview old snapshot cleanup, and add `--apply` only when you want to delete valid old snapshots.
+`pnpm agent-loop ...` runs from the source checkout. `agent-loop ...` is the global command after npm or local source install.
 
-For a complete local install, upgrade, reinstall, uninstall, and smoke-test checklist, see [Local Release Readiness](./docs/local-release-readiness.md).
+For the full install, upgrade, reinstall, uninstall, rollback, and smoke-test checklist, see [Local Release Readiness](./docs/local-release-readiness.md).
 
-Add HOLO-Codex to the local Codex plugin marketplace. For npm installs:
+## Initialize A Repo
 
-```bash
-codex plugin marketplace add "$(npm root -g)/holo-codex"
-```
-
-For source installs:
-
-```bash
-codex plugin marketplace add /path/to/HOLO-Codex
-```
-
-Then enable the `autonomous-pr-loop` plugin in Codex. Plugin enablement and global CLI installation are separate steps.
-
-## Initialize State
-
-Run from the target repository root:
+Run from the target repository root or pass `--repo`:
 
 ```bash
 agent-loop --repo /path/to/repo init
 agent-loop --repo /path/to/repo doctor
-agent-loop --repo /path/to/repo status
-```
-
-Install Codex hooks:
-
-```bash
 agent-loop install-hooks --repo /path/to/repo
 ```
 
-This installs one stable hook router into `~/.codex/hooks.json`, preserves existing user hooks, and records the target repository binding under `~/.codex/agent-loop/hook-bindings.json`.
+Hook installation writes one router into `~/.codex/hooks.json`, preserves existing hooks, and records target repository bindings under `~/.codex/agent-loop/hook-bindings.json`.
 
-Multi-repo note: multiple repositories can share the same `CODEX_HOME`; hook events are routed by Codex cwd/worktree/session context before any repo state is written or policy is applied. A separate `CODEX_HOME` remains useful for high-isolation sandbox testing.
+Multiple repositories can share the same `CODEX_HOME`. Hook events are routed by Codex cwd, worktree, and session context before any repository state is written or policy is applied. A separate `CODEX_HOME` is still useful for high-isolation sandbox testing.
 
 Runtime files are written to `.agent-loop/` and must not be committed.
 
@@ -146,7 +180,7 @@ Runtime files are written to `.agent-loop/` and must not be committed.
 agent-loop --repo /path/to/repo dashboard
 ```
 
-The command prints a loopback URL on stdout and a fallback session token on stderr:
+The command prints a loopback URL:
 
 ```text
 dashboard started
@@ -154,9 +188,9 @@ url: http://127.0.0.1:<port>/
 targetRepoRoot: /path/to/repo
 ```
 
-Dashboard mutations require the local session token and go through the shared controller. The UI does not write SQLite directly. Loopback dashboard sessions unlock through a same-origin session bootstrap; the stderr token is only a fallback for static UI or recovery. Do not copy it into docs, logs, PR bodies, commits, artifacts, or screenshots.
+Dashboard mutations require the local session token and go through the shared controller. The UI does not write SQLite directly. Loopback dashboard sessions unlock through a same-origin bootstrap; the stderr token is only a fallback for static UI or recovery. Do not copy it into docs, logs, PR bodies, commits, artifacts, or screenshots.
 
-Dashboard-visible delivery work is produced by persisted `agent-loop` actions and workflow evidence. Direct terminal edits or commander decisions are not automatically visible unless they are recorded through agent-loop events, artifacts, or PR comments. For the current self-maintenance flow, see [Self-bootstrap workflow](./docs/self-bootstrap.md). For an end-to-end audit template, see [Agent-loop-first Delivery Audit Checklist](./docs/checklists/agent-loop-first-delivery-audit.md).
+Dashboard-visible delivery work comes from persisted `agent-loop` actions and workflow evidence. Direct terminal edits or commander decisions become visible only when they are recorded as agent-loop events, artifacts, or PR comments.
 
 ## Common CLI
 
@@ -182,7 +216,7 @@ Human-readable CLI output supports `--locale zh-CN|en-US|system`. JSON output re
 
 ## Workflow Profiles And Themes
 
-The default workflow remains `pr-loop` with `default_pr_loop` and `default_pr_roles`. Policy Config can also select `generic-loop` with built-in profiles for research reports, document preparation, repo hygiene, weekly review, and data extraction workflows. For a concrete non-PR workflow, see the [generic-loop repo hygiene example](./docs/examples/generic-loop-repo-hygiene.md).
+The default workflow is `pr-loop` with `default_pr_loop` and `default_pr_roles`. Policy Config can also select `generic-loop` with built-in profiles for research reports, document preparation, repo hygiene, weekly review, and data extraction workflows. For a concrete non-PR workflow, see the [generic-loop repo hygiene example](./docs/examples/generic-loop-repo-hygiene.md).
 
 Dashboard theme is a local browser preference. It supports `light`, `dark`, and `system`, and does not write to repo config or SQLite.
 
@@ -192,9 +226,41 @@ Dashboard theme is a local browser preference. It supports `light`, `dark`, and
 - The supervisor owns Git and GitHub lifecycle actions.
 - Destructive Git/GitHub commands are blocked by command policy and hooks.
 - Merge readiness depends on config, review/CI evidence, open review comments, scope guard, and policy decisions.
-- Never store secrets in code, docs, logs, artifacts, commits, or PR bodies.
+- HOLO-Codex must not store secrets, raw prompts, raw transcripts, dashboard tokens, or raw hook payloads in docs, logs, artifacts, commits, or PR bodies.
 - Hooks cover the Codex tool loop, not manual commands run in an external terminal.
 
+See [Trust and Safety](./docs/trust-and-safety.md) and [Security](./SECURITY.md).
+
+## FAQ
+
+### Is HOLO-Codex hosted?
+
+No. HOLO-Codex runs locally. The dashboard, SQLite state, hooks, and CLI live on your machine.
+
+### Does it replace Codex?
+
+No. Codex still does the work. HOLO-Codex gives long Codex workflows state, evidence, gates, recovery, and a dashboard.
+
+### Why is the CLI still called `agent-loop`?
+
+`agent-loop` is the stable runtime command. Keeping it avoids breaking existing installs, scripts, hooks, and local state.
+
+### Why is the plugin id still `autonomous-pr-loop`?
+
+That id is part of the existing plugin and MCP wiring. HOLO-Codex is the public product name; `autonomous-pr-loop` is a compatibility identifier.
+
+### Does it auto-merge PRs?
+
+No. HOLO-Codex can track merge readiness and evidence, but the supervisor controls Git and GitHub lifecycle actions.
+
+### Does it require GitHub?
+
+The bundled PR delivery workflow expects GitHub and `gh`. The underlying loop model can support non-PR workflows through `generic-loop`.
+
+### Where is state stored?
+
+Repository runtime state lives under `.agent-loop/`. Hook routing bindings live under `~/.codex/agent-loop/`. Runtime files should not be committed.
+
 ## Development
 
 ```bash

package/README.zh-CN.md

@@ -4,62 +4,109 @@
 
 ![HOLO-Codex README hero](./assets/brand/holo-codex-readme-hero.png)
 
-HOLO-Codex 是 **Human On Loop Codex** 的缩写，它把长流程 Codex workflow 变成可观察、可恢复、可人工接管的 loop。人设定目标和边界、观察进展，并只在真实 gate 需要关注时回到环上。
+[![npm version](https://img.shields.io/npm/v/holo-codex?color=0f766e)](https://www.npmjs.com/package/holo-codex)
+[![npm downloads](https://img.shields.io/npm/dm/holo-codex)](https://www.npmjs.com/package/holo-codex)
+[![GitHub release](https://img.shields.io/github/v/release/tizerluo/HOLO-Codex)](https://github.com/tizerluo/HOLO-Codex/releases)
+[![CI](https://github.com/tizerluo/HOLO-Codex/actions/workflows/ci.yml/badge.svg)](https://github.com/tizerluo/HOLO-Codex/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+![Node >=22.5](https://img.shields.io/badge/node-%3E%3D22.5-339933)
 
-Supervisor 负责持久化 workflow 状态、evidence、gates、worker 编排、Codex hooks、MCP control plane 和本地 dashboard。Worker 只做受控任务并返回结构化输出。
+HOLO-Codex 是 **Human On Loop Codex** 的缩写。它把长流程 Codex workflow 变成可观察、可恢复、可人工接管的系统，让你不用一直守在聊天记录里猜它做到了哪一步。
 
-## 提供能力
+Codex 负责计划、改代码、测试、review 和调用子代理。HOLO-Codex 负责把这些工作落到本地 control plane 上：workflow 状态、evidence、gates、hooks、review 状态、恢复动作，以及一个可以边跑边看的 dashboard。
 
-- `plugins/autonomous-pr-loop/` 下的 Codex 插件。
-- `agent-loop` CLI：管理本地 loop 状态、hooks、dashboard、workflow evidence 和可回滚本地安装。
-- `.agent-loop/` 下的本地 SQLite 状态。
-- 本地 dashboard：Mission Control、workflow board、Observability Console、Gate、Review/CI、Worker、Artifact、Notifications、Recovery、Policy Config、主题模式。
-- stdio MCP control plane。
-- 用于 policy 检查和 observability 的 Codex hooks。
-- TypeScript + Vitest 测试套件。
-- `zh-CN`、`en-US`、`system` 双语显示支持。
-- workflow profile、role profile、`generic-loop`，以及第一个内置 workflow：`pr-loop`。
+## 快速开始
 
-这不是托管服务，不提供 GitHub webhook daemon 或云端 worker。
+安装 npm package，并把 HOLO-Codex 接到一个目标仓库：
 
-## 兼容名称
+```bash
+npm install --global holo-codex
+agent-loop --repo /path/to/repo init
+agent-loop install-hooks --repo /path/to/repo
+agent-loop --repo /path/to/repo dashboard
+```
 
-HOLO-Codex 是公开产品名。一些稳定运行时标识会继续保留旧名称，以避免破坏已有安装和本地状态：
+打开命令打印出来的本地 URL。Dashboard 会在本机自动解锁，不会把 token 放进 URL。
 
-- CLI 命令：`agent-loop`
-- 运行态目录：`.agent-loop/`
-- Plugin id 和 MCP server id：`autonomous-pr-loop`
-- 源码目录：`plugins/autonomous-pr-loop/`
-- npm package 名：`holo-codex`
-- 本地 marketplace 条目名：`codex-auto-pr-loop`
+Codex plugin 启用和 CLI 安装是两件事：
 
-这些是兼容标识，不是第二个产品名。
+```bash
+codex plugin marketplace add "$(npm root -g)/holo-codex"
+```
 
-## 第一个工作流：PR 交付
+然后在 Codex 里启用 `autonomous-pr-loop` 插件。CLI 继续叫 `agent-loop`，这是兼容已有安装和本地状态的名字。
+
+## 为什么需要 HOLO-Codex
 
-PR 交付是 HOLO-Codex 随附的第一个完整 workflow，也是 loop 模型最强的样板，但不是产品边界。
+| 问题 | HOLO-Codex 补上的东西 |
+| --- | --- |
+| 长流程 Codex 任务容易消失在一个聊天线程里。 | Workflow board 会显示当前阶段、状态来源、证据和下一步。 |
+| 人工决策、review report、CI 信号分散在不同地方。 | Evidence 会作为 append-only workflow event 记录下来，并显示在 dashboard。 |
+| 一旦暂停、遇到 gate、worker 失败或切上下文，恢复成本很高。 | Gate、recovery、timeline、artifact 和 hook 诊断都会绑定到同一个 run。 |
 
-典型流程：
+## 它提供什么
+
+- Workflow Board：展示长流程 Codex workflow 的阶段状态、证据数量和当前阶段详情。
+- Evidence Trail：记录计划、实现、测试、review、PR、CI、merge readiness 和 cleanup。
+- Gates and Recovery：处理 policy block、人工批准、stale run 和历史 gate re-evaluate。
+- Hook-based Observability：按 repo、worktree、session context 路由 Codex hook events。
+- Local Dashboard：包含 Mission Control、Observability Console、Gate、Review/CI、Worker、Artifact、Notifications、Recovery、Policy Config 和主题模式。
+- CLI 和 stdio MCP control plane：供脚本、skills 和 Codex plugin 调用。
+- Review and CI visibility：通过结构化 review evidence、severity summary、PR comment link 和 merge readiness 追踪交付状态。
+
+HOLO-Codex 是 local-first 工具。它不是托管服务，也不会替你运行云端 worker 或 GitHub webhook daemon。
+
+## 它如何工作
+
+```mermaid
+flowchart LR
+  A["Codex skill or commander"] --> B["agent-loop CLI / MCP"]
+  B --> C["Local workflow state<br/>.agent-loop SQLite"]
+  B --> D["Codex hooks<br/>repo / worktree / session routing"]
+  C --> E["Dashboard workflow board"]
+  D --> E
+  E --> F["Gates and recovery"]
+  E --> G["Review, CI, PR, cleanup evidence"]
+```
+
+Dashboard 和 MCP tools 读取持久化 loop 状态，不依赖聊天记录还在不在。
+
+## 第一个工作流：PR 交付
+
+PR 交付是 HOLO-Codex 随附的第一个完整 workflow，也是目前最完整的样板，但它不是产品边界。
 
 ```text
-sync main
-bind work item
-plan
-build
-verify
-open PR
-run review / CI
-fix findings
-check merge readiness
-merge
-cleanup
+Work Item -> Plan -> Build -> Verify -> PR -> Review -> Merge Readiness -> Cleanup
 ```
 
-Dashboard 和 MCP tools 读取持久化 loop 状态，不依赖聊天历史。
+内置 PR workflow 可以绑定 GitHub issue、追踪实现证据、收集 tester 和 reviewer report、显示 PR/CI readiness，并在 merge 后继续保留 cleanup 状态。
+
+同一套 control plane 以后也可以承载其他长流程 Codex workflow：
+
+- release 准备
+- repo hygiene
+- security review
+- docs publishing
+- migration
+- evaluation
+- customer issue triage
+
+## 兼容名称
+
+HOLO-Codex 是公开产品名。一些运行时标识会继续保留旧名称，避免破坏已有安装、脚本、hooks 和本地状态：
 
-同一套 control plane 也可以承载其他长流程 Codex workflow，例如 release 准备、仓库卫生审计、安全审查、文档发布、迁移、评测和客户 issue 分诊。
+| 公开概念 | 稳定标识 |
+| --- | --- |
+| CLI 命令 | `agent-loop` |
+| 运行态目录 | `.agent-loop/` |
+| Plugin id 和 MCP server id | `autonomous-pr-loop` |
+| 源码目录 | `plugins/autonomous-pr-loop/` |
+| npm package | `holo-codex` |
+| 本地 marketplace 条目 | `codex-auto-pr-loop` |
+
+这些是兼容标识，不是第二个产品名。
 
-## 安装
+## 安装细节
 
 公开源码入口：
 
@@ -74,19 +121,27 @@ https://github.com/tizerluo/HOLO-Codex
 - GitHub CLI `gh`
 - Codex CLI / plugin support
 - 从源码安装或使用 snapshot/rollback local install 时需要 `pnpm`
-- 可选但推荐：GitNexus，使用 `npx gitnexus`
+- 可选：GitNexus，使用 `npx gitnexus`
 
 从 npm 安装：
 
 ```bash
 npm install --global holo-codex
-# 将 /path/to/repo 替换成你要让 HOLO-Codex 监督的目标仓库。
 agent-loop --repo /path/to/repo init
 agent-loop install-hooks --repo /path/to/repo
 agent-loop --repo /path/to/repo doctor
 ```
 
-npm package 会安装 `agent-loop` CLI。`agent-loop install-hooks` 会安装或刷新 hook router 和目标仓库绑定，不会重新安装全局 CLI。移除 npm 安装时，先运行 `agent-loop hooks unbind --repo /path/to/repo`；确认没有任何目标仓库还在使用 HOLO-Codex router 后，再从 `~/.codex/hooks.json` 手动移除 HOLO-Codex router entries，最后运行 `npm uninstall --global holo-codex`。
+npm package 会安装 `agent-loop` CLI。`agent-loop install-hooks` 会安装或刷新 hook router 和目标仓库绑定，不会重新安装全局 CLI。
+
+移除 npm 安装：
+
+```bash
+agent-loop hooks unbind --repo /path/to/repo
+npm uninstall --global holo-codex
+```
+
+只有确认没有任何目标仓库还在使用 HOLO-Codex router 后，才从 `~/.codex/hooks.json` 移除 HOLO-Codex router entries。
 
 开发 HOLO-Codex 或需要直接检查源码 checkout 时，从源码安装：
 
@@ -95,48 +150,27 @@ git clone https://github.com/tizerluo/HOLO-Codex.git
 cd HOLO-Codex
 pnpm install
 pnpm build:hooks
-# 将 /path/to/repo 替换成你要让 HOLO-Codex 监督的目标仓库。
 pnpm agent-loop local install --repo /path/to/repo
 agent-loop --repo /path/to/repo status
 ```
 
-`pnpm agent-loop ...` 是源码 checkout 内的命令。`agent-loop ...` 是 npm 或本地源码安装后从任意目录日常使用的全局命令。用 `agent-loop local snapshots prune --keep 10` 预览旧 snapshot 清理；确认要删除时再加 `--apply`。
-
-完整的本地安装、升级、重装、卸载和 smoke test 清单见：[Local Release Readiness](./docs/local-release-readiness.md)。
-
-把 HOLO-Codex 加入本地 Codex plugin marketplace。npm 安装时：
-
-```bash
-codex plugin marketplace add "$(npm root -g)/holo-codex"
-```
-
-源码安装时：
+`pnpm agent-loop ...` 是源码 checkout 内的命令。`agent-loop ...` 是 npm 或本地源码安装后从任意目录使用的全局命令。
 
-```bash
-codex plugin marketplace add /path/to/HOLO-Codex
-```
+完整的安装、升级、重装、卸载、rollback 和 smoke test 清单见：[Local Release Readiness](./docs/local-release-readiness.md)。
 
-然后在 Codex 中启用 `autonomous-pr-loop` 插件。Codex plugin 启用和全局 CLI 安装是两件事。
+## 初始化一个仓库
 
-## 初始化状态
-
-在目标仓库根目录执行：
+在目标仓库根目录执行，或显式传 `--repo`：
 
 ```bash
 agent-loop --repo /path/to/repo init
 agent-loop --repo /path/to/repo doctor
-agent-loop --repo /path/to/repo status
-```
-
-安装 Codex hooks：
-
-```bash
 agent-loop install-hooks --repo /path/to/repo
 ```
 
-这会向 `~/.codex/hooks.json` 安装一组稳定 hook router，保留已有用户 hooks，并在 `~/.codex/agent-loop/hook-bindings.json` 记录目标仓库绑定。
+Hook 安装会向 `~/.codex/hooks.json` 写入一组 router，保留已有 hooks，并在 `~/.codex/agent-loop/hook-bindings.json` 记录目标仓库绑定。
 
-多仓库注意：多个仓库可以共用同一个 `CODEX_HOME`；hook event 会先按 Codex cwd/worktree/session context 路由，再写入仓库状态或执行 policy。独立 `CODEX_HOME` 仍适合高隔离 sandbox 测试。
+多个仓库可以共用同一个 `CODEX_HOME`。Hook event 会先按 Codex cwd、worktree 和 session context 路由，再写入仓库状态或执行 policy。独立 `CODEX_HOME` 仍适合高隔离 sandbox 测试。
 
 运行态文件写入 `.agent-loop/`，不要提交。
 
@@ -146,7 +180,7 @@ agent-loop install-hooks --repo /path/to/repo
 agent-loop --repo /path/to/repo dashboard
 ```
 
-命令会在 stdout 打印 loopback URL，并在 stderr 单独打印 fallback session token：
+命令会打印一个本地 URL：
 
 ```text
 dashboard 已启动
@@ -154,9 +188,9 @@ url: http://127.0.0.1:<port>/
 targetRepoRoot: /path/to/repo
 ```
 
-Dashboard mutation 必须带本地 session token，并统一走 controller。UI 不直接写 SQLite。本地 loopback dashboard 会用同源 session bootstrap 自动解锁。stderr token 只作为静态 UI 或恢复场景的 fallback；不要把它复制到 docs、日志、PR body、commit、artifact 或截图里。
+Dashboard mutation 必须带本地 session token，并统一走 controller。UI 不直接写 SQLite。本地 loopback dashboard 会用同源 bootstrap 自动解锁。stderr token 只作为静态 UI 或恢复场景的 fallback，不要把它复制到 docs、日志、PR body、commit、artifact 或截图里。
 
-Dashboard 能看到的交付工作来自持久化的 `agent-loop` 动作和 workflow evidence。直接在终端改文件或 commander 决策不会自动出现在 dashboard，除非它们被记录成 agent-loop event、artifact 或 PR comment。当前自维护流程见：[自举维护流程](./docs/self-bootstrap.md)。端到端审计模板见：[Agent-loop-first Delivery Audit Checklist](./docs/checklists/agent-loop-first-delivery-audit.md)。
+Dashboard 能看到的交付工作来自持久化的 `agent-loop` 动作和 workflow evidence。直接在终端改文件或 commander 决策不会自动出现在 dashboard，除非它们被记录成 agent-loop event、artifact 或 PR comment。
 
 ## 常用 CLI
 
@@ -182,9 +216,9 @@ agent-loop --repo /path/to/repo dashboard
 
 ## Workflow Profiles 和主题
 
-默认 workflow 仍是 `pr-loop`，使用 `default_pr_loop` 和 `default_pr_roles`。Policy Config 也可以选择 `generic-loop`，并使用内置的调研报告、文档准备、仓库卫生审计、周报、数据抽取 workflow profiles。具体非 PR 工作流可参考：[generic-loop 仓库卫生审计示例](./docs/examples/generic-loop-repo-hygiene.md)。
+默认 workflow 是 `pr-loop`，使用 `default_pr_loop` 和 `default_pr_roles`。Policy Config 也可以选择 `generic-loop`，并使用内置的调研报告、文档准备、仓库卫生审计、周报、数据抽取 workflow profiles。具体非 PR 工作流可参考：[generic-loop 仓库卫生审计示例](./docs/examples/generic-loop-repo-hygiene.md)。
 
-Dashboard 主题是浏览器本地显示偏好，支持 `light`、`dark`、`system`，不会写入 repo config 或 SQLite。
+Dashboard 主题是浏览器本地显示偏好，支持 `light`、`dark` 和 `system`，不会写入 repo config 或 SQLite。
 
 ## 安全边界
 
@@ -192,9 +226,41 @@ Dashboard 主题是浏览器本地显示偏好，支持 `light`、`dark`、`syst
 - Supervisor 负责 Git 和 GitHub 生命周期。
 - 破坏性 Git/GitHub 命令由 command policy 和 hooks 阻止。
 - Merge readiness 由 config、review/CI evidence、open review comments、scope guard 和 policy decisions 共同决定。
-- 不要把密钥写入代码、文档、日志、artifacts、commit 或 PR body。
+- HOLO-Codex 不应该把 secrets、raw prompts、raw transcripts、dashboard tokens 或 raw hook payloads 写入 docs、日志、artifacts、commit 或 PR body。
 - Hooks 只覆盖 Codex tool loop，不拦截外部 Terminal 手动命令。
 
+更多细节见：[信任与安全](./docs/trust-and-safety.md) 和 [安全政策](./SECURITY.md)。
+
+## FAQ
+
+### HOLO-Codex 是托管服务吗？
+
+不是。HOLO-Codex 在本机运行。Dashboard、SQLite 状态、hooks 和 CLI 都在你的机器上。
+
+### 它会替代 Codex 吗？
+
+不会。Codex 还是负责做事。HOLO-Codex 给长流程 Codex 工作补上状态、证据、gate、恢复动作和 dashboard。
+
+### 为什么 CLI 还叫 `agent-loop`？
+
+`agent-loop` 是稳定运行时命令。保留这个名字可以避免破坏已有安装、脚本、hooks 和本地状态。
+
+### 为什么 plugin id 还是 `autonomous-pr-loop`？
+
+这个 id 已经接入现有 plugin 和 MCP wiring。HOLO-Codex 是公开产品名，`autonomous-pr-loop` 是兼容标识。
+
+### 它会自动 merge PR 吗？
+
+不会。HOLO-Codex 可以追踪 merge readiness 和 evidence，但 Git 和 GitHub 生命周期动作仍由 supervisor 控制。
+
+### 它必须依赖 GitHub 吗？
+
+内置 PR delivery workflow 需要 GitHub 和 `gh`。底层 loop 模型可以通过 `generic-loop` 承载非 PR workflow。
+
+### 状态存在哪里？
+
+仓库运行态状态在 `.agent-loop/` 下。Hook routing bindings 在 `~/.codex/agent-loop/` 下。运行态文件不要提交。
+
 ## 开发
 
 ```bash

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.1`. 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/`.
 
@@ -33,20 +33,23 @@ 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
 
@@ -126,11 +129,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.1
+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.1",
   "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",

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

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

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";
@@ -714,6 +715,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 +771,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}`,
@@ -1123,6 +1130,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 +1155,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 +1177,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);
+  }
+}

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/hooks/hooks.json

@@ -1,106 +1,3 @@
 {
-  "PreToolUse": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node ./hooks/dist/pre-tool-use.js",
-          "timeout": 1000,
-          "statusMessage": "Checking agent-loop command policy"
-        }
-      ]
-    }
-  ],
-  "PostToolUse": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node ./hooks/dist/post-tool-use.js",
-          "timeout": 500,
-          "statusMessage": "Recording agent-loop PostToolUse event"
-        }
-      ]
-    }
-  ],
-  "UserPromptSubmit": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node ./hooks/dist/user-prompt-submit.js",
-          "timeout": 500,
-          "statusMessage": "Recording agent-loop UserPromptSubmit event"
-        }
-      ]
-    }
-  ],
-  "Stop": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node ./hooks/dist/stop.js",
-          "timeout": 500,
-          "statusMessage": "Recording agent-loop Stop event"
-        }
-      ]
-    }
-  ],
-  "SessionStart": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node ./hooks/dist/session-start.js",
-          "timeout": 500,
-          "statusMessage": "Recording agent-loop SessionStart event"
-        }
-      ]
-    }
-  ],
-  "PreCompact": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node ./hooks/dist/pre-compact.js",
-          "timeout": 500,
-          "statusMessage": "Recording agent-loop PreCompact event"
-        }
-      ]
-    }
-  ],
-  "PostCompact": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node ./hooks/dist/post-compact.js",
-          "timeout": 500,
-          "statusMessage": "Recording agent-loop PostCompact event"
-        }
-      ]
-    }
-  ],
-  "PermissionRequest": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "node ./hooks/dist/permission-request.js",
-          "timeout": 500,
-          "statusMessage": "Recording agent-loop PermissionRequest event"
-        }
-      ]
-    }
-  ]
+  "hooks": {}
 }

package/plugins/autonomous-pr-loop/mcp-server/src/index.ts

@@ -35,7 +35,7 @@ async function handleLine(line: string): Promise<void> {
       respond(request.id, {
         protocolVersion: "2024-11-05",
         capabilities: { tools: {} },
-        serverInfo: { name: "autonomous-pr-loop", version: "0.1.0" }
+        serverInfo: { name: "autonomous-pr-loop", version: "0.1.1" }
       });
       return;
     }

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

@@ -1,6 +1,6 @@
 {
   "name": "autonomous-pr-loop",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": true,
   "type": "module",
   "engines": {