specrune-codex 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jsfaint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# specrune-codex
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SpecRune 的 Codex 宿主适配与项目级安装器。
+
+Codex 的 hooks 与 agents 都从项目内 `.codex/` 发现，所以本包**只支持项目级
+安装**，也不写全局 `~/.codex/config.toml`。安装器不判断 hooks 的信任状态：
+首次运行仍需在 Codex 的 `/hooks` 中审阅并信任。
+
+## 安装
+
+```bash
+npm i -g specrune-codex
+specrune-codex install
+```
+
+插件自带平台二进制（`dependencies.specrune`），安装器会把它复制到
+`<项目>/.codex/specrune/bin/specrune[.exe]` 并把 `hooks.json` 里的本工具命令
+改写为该绝对路径（带引号）。用户不需要另外安装 CLI。
+
+安装器的通用编排在 `specrune` 包内的 `specrune/lib/installer-core.mjs`（共享核心）；
+本包只保留 Codex 的落点、模板与 `hooks.json` 键级合并。入口命令不变：
+`specrune-codex install` 仍是用户入口。共享核心随 `specrune` 发布，旧版
+`specrune` 缺少它时安装器会提示升级。
+
+不要用 `npx specrune-codex install` 常驻：npx 把包解到临时的 `_npx` 目录，
+退出即清；已落盘的 agents 与二进制不受影响，但 `status`、升级与再次安装都得
+重新下载。依赖缺失（例如全局安装时用了 `--omit=optional`）时安装器仍会落盘
+agents，但不复制二进制，hook 保留裸 `specrune codex-hook` 并回退 PATH，同时在
+stderr 告警。
+
+### 安装模式与五宿主矩阵
+
+同一宿主在同一台机器上只能选一种模式：两处同时启用会每轮重复注入，技能也会在两处同名出现。`<adapter>` 是宿主适配器标识，不是 OS / 机器名；`specrune-windows-*` 是平台二进制包，不是安装器。下表 global / project 指**插件安装范围**；技能 `--scope` 由 `specrune skills` 单独决定（Codex 的技能可用 global，只有插件必须 project；DSH 技能与插件都只有 global）。
+
+| 适配器 | npm 包 | global | project |
+|---|---|---|---|
+| `opencode` | `specrune-opencode` | ✓ | ✓ |
+| `pi` | `specrune-pi` | ✓ | ✓ |
+| `claude` | `specrune-claude` | ✓ | ✓ |
+| `codex` | `specrune-codex` | —（自动纠正为 project） | ✓ |
+| `dsh` | `specrune-dsh-host` | ✓ | —（自动纠正为 global） |
+
+本适配器的**插件安装**只支持 project：Codex 的 hooks 与 agents 都从项目内
+`.codex/` 发现，传 `--scope global` 会被纠正为 project 并打印提示。技能与插件
+都在项目内：`.specrune/`、`.agents/skills/`、`.codex/`。
+
+Windows 完整示例（PowerShell）：
+
+```powershell
+npm i -g specrune-codex
+cd C:\path\to\project
+specrune init --developer "你的名字"
+specrune-codex install   # 只能 project；等价于 --scope project
+```
+
+技能由 CLI 统一安装：`specrune skills install --adapter codex --scope project`；
+`specrune skills migrate --scope project` 可把全局技能收拢到当前项目。Codex
+插件只有 project 安装，但技能本身仍可用 `--scope global` 共享（插件留在项目内）。
+项目根放 `.specrune-disabled` 可禁用该项目的自动注入；`specrune-setup` 只能由
+用户显式调用（`agents/openai.yaml` 的 `policy.allow_implicit_invocation: false`）。
+
+安装器写入：
+
+| 内容 | 位置 | 说明 |
+|---|---|---|
+| `agents/specrune-*.toml` | `<项目>/.codex/agents/` | implement / check / research 子代理 |
+| `hooks.json` | `<项目>/.codex/hooks.json` | 只合并本工具的 hook 组 |
+| `specrune/bin/specrune[.exe]` | `<项目>/.codex/specrune/bin/` | 插件自带的平台二进制（有依赖时） |
+
+`hooks.json` 是混合所有权文件，安装器只增删本工具的条目（裸命令，或
+`.codex/specrune/bin/` 下的绝对路径 + `codex-hook`）：
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "specrune codex-hook", "timeout": 3 }] }
+    ],
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "command", "command": "specrune codex-hook", "timeout": 3 }] }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "^specrune_(implement|check|research)$",
+        "hooks": [{ "type": "command", "command": "specrune codex-hook", "timeout": 30 }]
+      }
+    ]
+  }
+}
+```
+
+用户自己的其它事件、分组与顶层键原样保留。同一事件里已经有本工具组且
+matcher 与模板一致时只更新命令，不重复追加；升级（路径变化）也只会替换旧
+命令。结构不可控或非法 JSON 时不动文件并告警。卸载只摘本工具的条目，组里只剩
+我们的条目时删分组，事件数组空了删事件键，`hooks` 空了删 `hooks` 键，并删除
+`.codex/specrune/`；顶层 `description` 只在仍是模板原文时删除。
+
+状态写在 `<项目>/.specrune/.state/plugins/codex.json`，记录
+`{ protocol, version, files: [{ path, sha256 }] }`。`hooks.json` 不进
+`files`：它走键级擦除，不能按整文件哈希删除。
+
+## 命令
+
+```bash
+specrune-codex install   [--scope project|global] [--dir <项目根>] [--dry-run] [--force]
+specrune-codex uninstall [--scope project|global] [--dir <项目根>] [--dry-run] [--force]
+specrune-codex status    [--scope project|global] [--dir <项目根>] [--json]
+```
+
+- `--scope` 默认 `project`；传 `global` 会纠正为 `project` 并打印提示（Codex 只有项目级 hooks / agents）。
+- `--dir` 指定项目根，缺省当前目录。
+- `--dry-run` 只打印计划，不写盘。
+- `--force` 覆盖（install）或删除（uninstall）已被用户改过的 agents。
+- 退出码：`0` 成功，`1` 运行失败，`2` 用法错误。
+
+## 从旧版 `init --codex` 迁移
+
+旧版 `specrune init --codex` 会写 `<项目>/.codex/`，文件名为下划线形态
+（`agents/specrune_implement.toml`）。新版安装器写连字符形态
+（`agents/specrune-implement.toml`），两者靠 TOML 内的 `name` 字段区分身份，
+两套同时存在会让 Codex 看到重复的子代理定义。
+
+CLI 已不再提供平台旧文件检测（`specrune doctor` 只校验研究与技能）。请在项目里
+手工删除旧版写入的 `.codex/agents/specrune_*.toml`（下划线形态），并从
+`.codex/hooks.json` 移除 `command` 为 `specrune codex-hook` 的分组；用户自己的
+hooks 与其它事件保留。已装新插件的项目（连字符 agents 或状态文件）不要动 hooks
+里的新分组。内容已改过的文件先备份再删。
+
+## 开发
+
+```bash
+npm test
+```
+
+包内 agents 与 `hooks.json` 是 Codex 适配的权威副本；CLI 不再 embed 平台资产。

package/agents/specrune-check.toml

@@ -0,0 +1,17 @@
+name = "specrune_check"
+description = "Check the current SpecRune task against its acceptance criteria and curated check context."
+developer_instructions = """
+Review the active SpecRune task against its PRD and injected check context. Inspect the actual diff and run focused checks. Report concrete correctness gaps with file locations and evidence. Do not edit files unless the parent explicitly asks you to fix a finding.
+
+You are already the delegated check role. Follow the parent's scoped assignment; do not repeat coordinator dispatch steps or spawn another agent for this role.
+
+Before acting, load the `specrune-review` skill, plus any other skills named in your dispatch prompt. Use the host skill tool when available; otherwise read `.agents/skills/<name>/SKILL.md` (project) or `~/.agents/skills/<name>/SKILL.md` (global) for each. If any is unavailable, report `<name> skill unavailable` and stop before reviewing.
+
+Fix mechanical and local issues when the parent authorizes edits; for design or judgment calls, report the evidence and stop.
+
+Before acting, recover the task context:
+1. If Codex says full hook output was saved to a file, read that exact file first. A preview or the <!-- specrune-codex-context --> marker confirms delivery, not completeness.
+2. Check the delivered Role, Active task, and Context status, including warning, truncated, and dropped notices, then read the required originals.
+3. Read the active task's prd.md and, when present, design.md and implement.md. Inspect check.jsonl and read the referenced specs; a compiled excerpt does not replace missing requirements.
+4. If startup context is missing or incomplete, use the task path the parent supplied explicitly. Do not infer the parent's task from your child session, environment identity, or other sessions. If essential context is unavailable, report what is missing before task-dependent work.
+"""

package/agents/specrune-implement.toml

@@ -0,0 +1,17 @@
+name = "specrune_implement"
+description = "Implement the current SpecRune task using its PRD and curated implement context."
+developer_instructions = """
+Implement the active SpecRune task. Read the task PRD, design, and implement plan and the context injected at startup; follow the project specs, make the smallest correct change, run the required checks, and report changed files, checks, and remaining risks.
+
+You are already the delegated implement role. Follow the parent's scoped assignment; do not repeat coordinator dispatch steps or spawn another agent for this role.
+
+Before acting, load the `specrune-before-dev` skill, plus any other skills named in your dispatch prompt. Use the host skill tool when available; otherwise read `.agents/skills/<name>/SKILL.md` (project) or `~/.agents/skills/<name>/SKILL.md` (global) for each. If any is unavailable, report `<name> skill unavailable` and stop before editing.
+
+Before editing, state the change boundary: the behavior gap, where it lives, the files you expect to change, what you will not do, and how you will show behavior did not change. If the scope is larger than the dispatch, say so before continuing.
+
+Before acting, recover the task context:
+1. If Codex says full hook output was saved to a file, read that exact file first. A preview or the <!-- specrune-codex-context --> marker confirms delivery, not completeness.
+2. Check the delivered Role, Active task, and Context status, including warning, truncated, and dropped notices, then read the required originals.
+3. Read the active task's prd.md and, when present, design.md and implement.md. Inspect implement.jsonl and read the referenced specs; a compiled excerpt does not replace missing requirements.
+4. If startup context is missing or incomplete, use the task path the parent supplied explicitly. Do not infer the parent's task from your child session, environment identity, or other sessions. If essential context is unavailable, report what is missing before task-dependent work.
+"""

package/agents/specrune-research.toml

@@ -0,0 +1,54 @@
+name = "specrune_research"
+description = "Investigate a question for a SpecRune task and return source-backed findings."
+developer_instructions = """
+Research the question delegated by the parent. Trace the repository or official source that answers it and distinguish evidence from inference. When a task is confirmed, write a research report before returning its path and a concise summary.
+
+You are already the delegated research role. Follow the parent's scoped assignment; do not repeat coordinator dispatch steps or spawn another agent to perform this same role.
+
+Before acting, recover and verify the task context:
+1. If Codex says full hook output was saved to a file, read that exact file first. A head/tail preview or the <!-- specrune-codex-context --> marker confirms delivery, not completeness.
+2. Check the delivered Role, Active task, and Context status. Read warning, truncated, and dropped notices. If the parent supplies an expected task path for a strict Codex dispatch, compare its resolved task directory with the Hook's Active task before proceeding. Both must identify the same existing task directory, with delivered Role research and usable Context status. If they differ, either task is absent or invalid, or the startup context is unavailable, stop task-dependent work before reading task artifacts or writing a report and report the mismatch to the parent. The expected path is a consistency check: never let an explicit path override a different Hook task. Do not change a session binding or use the parent's context key. For assignments without a strict expected task, resolve any role/task mismatch with the parent before proceeding.
+3. Read the confirmed task's prd.md and, when present, design.md and implement.md. A compiled excerpt is not a replacement for missing requirements.
+4. For assignments without a strict expected task, if startup context is missing or incomplete, use the task path explicitly supplied by the parent. Do not infer the parent's task from your child session's `specrune task current`, environment identity, or other sessions. If essential task context is unavailable, report what is missing to the parent before task-dependent work.
+
+## Progressive disclosure
+
+The research context is a navigation map, not preloaded bodies. Start from its paths and titles, read relevant contracts, then trace code and tests. Skip specs that are merely listed. `kind: navigation` entries record delivered pointers, not files read; a body intentionally not preloaded is not a dropped candidate. Search `.specrune/spec/` when incomplete. Record the sources the conclusions actually use in the evidence card; the ledger records delivery, not reading.
+
+Use the navigation delivered by the startup Hook; do not fetch it again merely because bodies were not preloaded. Complete the strict task comparison above before any recovery; navigation self-fetch must never override a different or unavailable Hook task in a strict dispatch.
+
+## Task and report
+
+When the Hook's Active task or the parent's explicit path confirms a task:
+For a strict dispatch, the startup task comparison above must have succeeded first.
+1. Create `<task-dir>/research/` if it is not there yet.
+2. Look through the code, the specs, and any external documentation that actually bears on the question.
+3. Give each distinct topic its own file: `<task-dir>/research/<slug>.md`, headed by its evidence card.
+4. Report file paths and a short summary, not the full contents. If writing the report fails, report that failure; never claim the file exists.
+
+If no task can be confirmed but the delegated question is self-contained, complete the investigation and return source-backed findings without writing a task report. Never guess a task directory.
+
+## Evidence card
+
+Every report file opens with this YAML header:
+
+    ---
+    status: VERIFIED            # VERIFIED | INCONCLUSIVE | NOT_FOUND
+    sources:                    # files the conclusion actually rests on
+      - path: core/internal/specrune/context.go
+        lines: 654-682
+      - path: https://github.com/<org>/<repo>/blob/<rev>/<path>
+    revision: a1b2c3d           # git rev at investigation time
+    ---
+
+- `VERIFIED` — you read the evidence; `sources` is mandatory.
+- `INCONCLUSIVE` — the evidence does not settle the question.
+- `NOT_FOUND` — the thing genuinely is not there.
+- External repo? `sources[].path` may be an `http(s)://` permalink embedding the rev; `revision` then records that repo's rev (req:sessions-memory#session-record-authoritative; the doctor skips URL checks).
+
+Pick exactly one. No `sources` entry means it is not a fact: cite, downgrade, or drop it — never dress a guess up as a conclusion. Cite `file:line` so a stale reference can be re-located from `revision`.
+
+## Stay in your lane
+
+Write only a plain `<slug>.md` report under this task's `research/` — no subdirectories, and never copy source into the task directory; cite it by `file:line` plus the `revision` in the card. Do not edit code, specs, platform config, or task files; patching is no longer investigating.
+"""

package/bin/specrune-codex.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// specrune-codex 的可执行入口。
+//
+// 安装器只写项目内 `.codex/`：Codex 的 hooks 与 agents 都是项目级发现，
+// 现有规范还明确不写全局 `~/.codex/config.toml`。装包时偷偷改用户全局配置
+// 既不可见也不可控，pnpm 10 也会拦截依赖的生命周期脚本。
+// 共享核心缺失（旧版 specrune）等启动错误只打印可操作消息，不甩模块堆栈。
+try {
+  const { main } = await import("../src/install.mjs");
+  process.exitCode = await main(process.argv.slice(2));
+} catch (err) {
+  process.stderr.write(`specrune-codex: ${err?.message ?? err}\n`);
+  process.exitCode = 1;
+}

package/hooks.json

@@ -0,0 +1,39 @@
+{
+  "description": "SpecRune session context and task workflow for Codex",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "specrune codex-hook",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "specrune codex-hook",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "^specrune_(implement|check|research)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "specrune codex-hook",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "specrune-codex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.0",
+  "description": "SpecRune 的 Codex 宿主适配与项目级安装器：装配 .codex/agents 子代理，并合并 .codex/hooks.json 的事件 hook",
+  "type": "module",
+  "bin": {
+    "specrune-codex": "bin/specrune-codex.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "agents",
+    "hooks.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "specrune": "^0.9.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jsfaint/SpecRune.git",
+    "directory": "plugins/codex"
+  },
+  "homepage": "https://github.com/jsfaint/SpecRune#readme",
+  "bugs": {
+    "url": "https://github.com/jsfaint/SpecRune/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "specrune",
+    "codex",
+    "codex-cli",
+    "plugin",
+    "spec-driven",
+    "workflow"
+  ]
+}

package/src/install.mjs

@@ -0,0 +1,906 @@
+// specrune-codex 安装器 adapter。
+//
+// 通用编排（参数解析、CLI 定位、状态/哈希/原子写、scope 校验、互斥检测、
+// skills 调用、install/uninstall/status 流程）在 specrune/lib/installer-core.mjs；
+// 这里只保留 Codex 的落点、agents/*.toml、hooks.json 键级合并/擦除、
+// scope 强制 project 与旧 agent 警告。安装器放在插件包而不是 Go CLI 的原因见
+// README：宿主装配是插件的版本轴。
+//
+// Codex 只支持项目级：hooks 与 agents 都从 `<项目>/.codex/` 发现，现有规范
+// 明确不写全局 `~/.codex/config.toml`。因此没有 `--scope global`，也不推断
+// Codex 的 hooks 信任状态——那只能由用户在 `/hooks` 里审阅。
+import { existsSync, readFileSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// 发布后从 specrune 依赖导入；源码仓库未执行 npm install，回退到仓库内的父包。
+// 旧版 specrune 没有 lib/installer-core.mjs：两档都解析不到时给可操作错误，
+// 不让裸 ERR_MODULE_NOT_FOUND 堆栈直接抛给用户。
+async function loadInstallerCore() {
+  try {
+    return await import("specrune/lib/installer-core.mjs");
+  } catch (err) {
+    if (!err || err.code !== "ERR_MODULE_NOT_FOUND") throw err;
+    try {
+      return await import("../../../npm/cli/lib/installer-core.mjs");
+    } catch (fallbackErr) {
+      if (!fallbackErr || fallbackErr.code !== "ERR_MODULE_NOT_FOUND") throw fallbackErr;
+      throw new Error(
+        "无法加载共享安装核心 specrune/lib/installer-core.mjs：当前 specrune 版本不含 installer-core。" +
+          "请升级 specrune 后重试（npm i -g specrune@latest）；" +
+          "若 specrune 尚未安装，请重新安装本插件。" +
+          `\n原始错误: ${err.message}`,
+      );
+    }
+  }
+}
+
+const core = await loadInstallerCore();
+const {
+  createInstaller,
+  contentHash,
+  hashContent,
+  loadState,
+  rawHash,
+  readIfExists,
+  readTemplateExisting,
+  resolveWithin,
+} = core;
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(HERE, "..");
+const PKG = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8"));
+
+// protocol 是后端钩子帧协议的版本，不是产品版本。插件只检查它，产品命令可以
+// 自由演进而不打断已装插件（.specrune/spec/backend/agent-plugin-contract.md）。
+export const PROTOCOL = 1;
+
+// 插件声明编写时依赖的 installer-core API 版本。必须写字面量：从核心导入
+// 会让声明永远等于当前核心，旧插件在新核心上就无法被拦下。
+const REQUIRED_CORE_VERSION = 1;
+
+export const AGENTS_REL = "agents";
+export const HOOKS_REL = "hooks.json";
+
+// 与 CLI 的 codex-hook 命令逐字一致：它是合并幂等判据，也是卸载摘除判据——
+// hooks.json 里认领本工具条目的唯一标识。
+export const HOOK_COMMAND = "specrune codex-hook";
+export const HOOK_SUBCOMMAND = "codex-hook";
+export const HOOK_DESCRIPTION = "SpecRune session context and task workflow for Codex";
+
+export const STATE_REL = ".specrune/.state/plugins/codex.json";
+
+const USAGE = `specrune-codex — 把 SpecRune 的 Codex 适配装进项目
+
+用法:
+  specrune-codex install   [--scope project|global] [--dir <项目根>] [--dry-run] [--force]
+  specrune-codex uninstall [--scope project|global] [--dir <项目根>] [--dry-run] [--force]
+  specrune-codex status    [--scope project|global] [--dir <项目根>] [--json]
+
+选项:
+  --scope project|global  只支持项目级：显式传 global 会纠正为 project 并提示
+  --dir <路径>            项目根（默认当前目录）
+  --dry-run               只打印计划，不写盘、不改状态文件
+  --force                 install 覆盖已修改的 agents，并在检测到全局 ~/.codex 痕迹时继续；
+                          uninstall 连改过的文件一起删
+  --json                  status 以机器可读 JSON 输出
+  -h, --help              显示本帮助
+
+安装内容:
+  <项目根>/.codex/agents/specrune-*.toml   implement / check / research 子代理
+  <项目根>/.codex/hooks.json               只增删本工具的 hook 组
+
+hooks.json 是混合所有权文件：用户自己的分组、事件与顶层键原样保留；只替换
+本工具的条目（裸命令，或旧版 .codex/specrune/bin/ 下的绝对路径 + codex-hook）。
+project 模式不复制 CLI 二进制（CLI 全局唯一），命令写为解析到的全局 CLI 绝对
+路径 + codex-hook；找不到时保留裸 "specrune codex-hook" 并回退 PATH。非法 JSON
+或结构不可控时不动并告警。状态写在 <项目根>/.specrune/.state/plugins/codex.json。
+技能由 'specrune skills install --adapter codex --scope project --dir <项目根>'
+统一落位；project 模式要求目标目录已有 .specrune/（先运行 specrune init）。
+技能失败只告警，插件安装仍成功。
+
+安装器不写 ~/.codex/config.toml，也不判断 hooks 是否已被信任；首次运行请在
+Codex 的 /hooks 中审阅并信任。
+
+退出码: 0 成功，1 运行失败，2 用法错误。
+`;
+
+// locateBundledBinary 以本模块为锚解析平台二进制：适配器自己的依赖树决定
+// 查找起点，不能换成共享核心的位置。
+export function locateBundledBinary() {
+  return core.locateBundledBinary({ anchor: import.meta.url });
+}
+
+export { contentHash, rawHash };
+
+// bundledRel 是自带 CLI 在宿主根（`.codex/`）下的相对路径。放进
+// `<项目根>/.codex/specrune/bin/`：这个目录只归本工具，卸载时整目录清掉，
+// 不会碰到用户自己的文件。
+export function bundledRel() {
+  return process.platform === "win32" ? "specrune/bin/specrune.exe" : "specrune/bin/specrune";
+}
+
+function isBinaryRel(rel) {
+  return rel === bundledRel();
+}
+
+// missingBinaryWarning 在没产出二进制时给出可行动的告警。解析到的路径存在但
+// 读不到，与「压根没解析到」是两种故障：前者多半是 SPECRUNE_BIN 指错，必须把
+// 用户填的路径回显出来，否则他会去重装依赖。
+function missingBinaryWarning(bundledBinary) {
+  const tail =
+    "hook 命令保留裸 `specrune codex-hook`，运行时回退 PATH 上的 specrune。" +
+    "请用 `npm i -g specrune-codex` 安装（npx 的临时目录会被清理），或设置 SPECRUNE_BIN 指向二进制。";
+  if (bundledBinary) return `解析到的 specrune 二进制读不到（${bundledBinary}）。${tail}`;
+  return `未找到本机平台的 specrune 二进制（缺少 specrune 依赖）。${tail}`;
+}
+
+// 二进制要按字节读，不能走 utf8——否则落盘的是替换字符而不是原可执行文件。
+
+// templateAgents 读包内 agents/*.toml，返回安装后的 POSIX 相对路径与正文。
+// 排序让安装计划与状态文件稳定：每次 install 给出不同顺序会让「这次改了什么」
+// 没法用 diff 看。
+//
+// 文件名用连字符（specrune-implement.toml），与旧 CLI 写的下划线
+// （specrune_implement.toml）区分开：旧 CLI 只写下划线文件，
+// 不会把插件当前安装误判成旧装配再删掉。Codex 以 TOML 内的 name 字段为身份，
+// 文件名只影响磁盘可读性。
+export function templateAgents() {
+  const abs = join(PKG_ROOT, AGENTS_REL);
+  return readdirSync(abs)
+    .filter((name) => name.endsWith(".toml"))
+    .sort()
+    .map((name) => ({
+      rel: `${AGENTS_REL}/${name}`,
+      content: readFileSync(join(abs, name), "utf8"),
+    }));
+}
+
+// templateFiles 是本次安装要落盘的全部自有文件。hooks.json 不在其中：
+// 它是混合所有权文件，走键级合并与擦除，不能按「整文件哈希」删除。
+//
+// CLI 全局唯一：Codex 没有全局安装，project 模式也不复制二进制；hook 指向
+// 解析到的全局 CLI（或裸 specrune 回退 PATH）。<root>/specrune/ 仍按旧版
+// 安装痕迹处理，卸载时整目录清掉。
+export function templateFiles() {
+  return templateAgents();
+}
+
+// hookCommandFor 是 hooks.json 里本工具的完整命令。路径加引号：项目目录可以
+// 在含空格的路径下（Windows 的 `C:\Users\John Doe`），裸路径会被 shell 拆成
+// 两个参数；引号不影响不含空格的路径。
+export function hookCommandFor(root) {
+  if (!root) return HOOK_COMMAND;
+  return hookCommandForBinary(join(resolve(root), ...bundledRel().split("/")));
+}
+
+// hookCommandForBinary 把「要执行的 CLI 路径」写成 hook 命令。空路径表示
+// 解析不到 CLI，保留裸命令回退 PATH。
+export function hookCommandForBinary(binary) {
+  if (!binary) return HOOK_COMMAND;
+  return `${JSON.stringify(resolve(binary))} ${HOOK_SUBCOMMAND}`;
+}
+
+// defaultHooks 直接取包内 hooks.json：命令等于裸命令时逐字节返回，保持全新
+// 安装（以及迁移期同步测试）与包内模板一致；有自带二进制时把模板里的裸命令
+// 换成绝对路径，返回结构与 merge 产物同形。
+export function defaultHooks(command = HOOK_COMMAND) {
+  const raw = readFileSync(join(PKG_ROOT, HOOKS_REL), "utf8");
+  if (command === HOOK_COMMAND) return raw;
+  const doc = JSON.parse(raw);
+  for (const groups of Object.values(doc.hooks ?? {})) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      if (!Array.isArray(group?.hooks)) continue;
+      for (const entry of group.hooks) {
+        if (entry && typeof entry === "object" && entry.command === HOOK_COMMAND) {
+          entry.command = command;
+        }
+      }
+    }
+  }
+  return JSON.stringify(doc, null, 2) + "\n";
+}
+
+function parseHooksDoc(raw) {
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    return { error: `不是合法 JSON: ${err.message}` };
+  }
+  if (doc === null) return { doc: {} };
+  if (typeof doc !== "object" || Array.isArray(doc)) {
+    return { error: "顶层不是 JSON 对象" };
+  }
+  return { doc };
+}
+
+function normalizePathForCompare(path) {
+  const abs = resolve(path);
+  return process.platform === "win32" ? abs.replace(/\//g, "\\").toLowerCase() : abs;
+}
+
+// commandExecutable 拆出「命令首段」：带引号路径与裸命令都可能出现。
+// 返回 null 表示这条命令不是 `... codex-hook` 的形状。
+function commandExecutable(command) {
+  const text = String(command).trim();
+  if (!text.endsWith(` ${HOOK_SUBCOMMAND}`)) return null;
+  let head = text.slice(0, -HOOK_SUBCOMMAND.length).trim();
+  if (head.length >= 2 && head.startsWith('"') && head.endsWith('"')) {
+    head = head.slice(1, -1);
+  }
+  return head;
+}
+
+// isOurHookCommand 认三类命令：
+//   - 裸 `specrune codex-hook`（旧安装，或没有依赖时的 PATH 回退）；
+//   - `<root>/specrune/bin/` 下的绝对路径 + codex-hook（旧版把二进制复制
+//     进项目时的安装）；
+//   - 当前解析到的全局 CLI 或状态文件里记录的 cliPath（新版 project 模式
+//     不复制二进制，hook 直接指向全局 CLI）。
+// 第三类必须显式传入，避免把用户自己指向别处 specrune 的 hook 当成我们的。
+export function isOurHookCommand(command, root = "", ownedExecutables = []) {
+  if (typeof command !== "string") return false;
+  if (command.trim() === HOOK_COMMAND) return true;
+  const executable = commandExecutable(command);
+  if (!executable || !isAbsolute(executable)) return false;
+  const candidate = normalizePathForCompare(executable);
+  for (const owned of ownedExecutables) {
+    if (owned && normalizePathForCompare(owned) === candidate) return true;
+  }
+  if (!root) return false;
+  const expectedDir = normalizePathForCompare(join(resolve(root), "specrune", "bin"));
+  return normalizePathForCompare(dirname(executable)) === expectedDir;
+}
+
+function isOursCommand(value, root = "", ownedExecutables = []) {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    typeof value.command === "string" &&
+    isOurHookCommand(value.command, root, ownedExecutables)
+  );
+}
+
+function isOursGroup(group, root = "", ownedExecutables = []) {
+  if (!group || typeof group !== "object" || Array.isArray(group)) return false;
+  return (
+    Array.isArray(group.hooks) &&
+    group.hooks.some((entry) => isOursCommand(entry, root, ownedExecutables))
+  );
+}
+
+// withoutOurs 保留分组元数据与相邻的用户命令，只摘掉本工具的命令。
+// 分组里只剩我们的命令时返回 null（调用方据此丢弃整个分组）。
+function withoutOurs(group, root = "", ownedExecutables = []) {
+  if (!isOursGroup(group, root, ownedExecutables)) return group;
+  const kept = group.hooks.filter(
+    (entry) => !isOursCommand(entry, root, ownedExecutables),
+  );
+  if (kept.length === 0) return null;
+  return { ...group, hooks: kept };
+}
+
+// upsertOursCommand 把分组内的本工具条目收敛成一条当前命令：命中旧命令
+// （裸命令或旧路径）时原地替换，保留 timeout 等其它字段；重复命中的后续条目
+// 删除。这样升级只改命令字符串，不会越追加越多。
+function upsertOursCommand(group, command, root, ownedExecutables = []) {
+  const kept = [];
+  let found = false;
+  let changed = false;
+  for (const entry of group.hooks) {
+    if (isOursCommand(entry, root, ownedExecutables)) {
+      if (found) {
+        changed = true;
+        continue;
+      }
+      found = true;
+      if (entry.command !== command) {
+        entry.command = command;
+        changed = true;
+      }
+      kept.push(entry);
+      continue;
+    }
+    kept.push(entry);
+  }
+  group.hooks = kept;
+  return changed;
+}
+
+// sameMatcher 对齐 Go 的 reflect.DeepEqual：模板里 SessionStart /
+// UserPromptSubmit 没有 matcher（undefined），SubagentStart 是字符串。
+function sameMatcher(a, b) {
+  return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+
+// mergeHooks 是 Go 侧 mergeCodexHooks 的移植，并补上自带二进制后的命令改写。
+//
+// 只替换本工具的 hook 组：用户分组与其它事件原样保留；同一事件里已有本工具
+// 组且 matcher 与模板一致时只更新命令，避免重复安装叠加。结构不可控（hooks 或
+// 事件不是预期形态）时拒绝整个文件，由调用方给出可执行指引。
+export function mergeHooks(raw, root = "", command = "", ownedExecutables = []) {
+  const parsed = parseHooksDoc(raw);
+  if (parsed.error) return { error: parsed.error };
+  const doc = parsed.doc;
+  const wanted = command || (root ? hookCommandFor(root) : HOOK_COMMAND);
+  const generated = JSON.parse(defaultHooks(wanted));
+  const ours = generated.hooks;
+
+  let hooks = doc.hooks;
+  if (hooks !== undefined && hooks !== null) {
+    if (typeof hooks !== "object" || Array.isArray(hooks)) {
+      return { error: "hooks 不是对象" };
+    }
+  } else {
+    hooks = {};
+  }
+
+  let changed = false;
+  for (const event of Object.keys(ours)) {
+    const value = hooks[event];
+    if (value !== undefined && value !== null && !Array.isArray(value)) {
+      return { error: `${event} 不是数组` };
+    }
+    const groups = Array.isArray(value) ? value : [];
+    const expected = ours[event];
+    const match = groups.find(
+      (group) =>
+        isOursGroup(group, root, ownedExecutables) &&
+        sameMatcher(group.matcher, expected[0].matcher),
+    );
+
+    if (match) {
+      // 同 matcher 的自有组：只改命令，保留分组内用户条目与 timeout。
+      if (upsertOursCommand(match, wanted, root, ownedExecutables)) changed = true;
+      // 其它分组里若还有本工具条目（旧 matcher、重复安装），一并摘掉。
+      const kept = [];
+      for (const group of groups) {
+        if (group === match) {
+          kept.push(group);
+          continue;
+        }
+        const remaining = withoutOurs(group, root, ownedExecutables);
+        if (remaining === null && isOursGroup(group, root, ownedExecutables)) changed = true;
+        else if (remaining !== group) changed = true;
+        if (remaining !== null || !isOursGroup(group, root, ownedExecutables)) {
+          kept.push(remaining);
+        }
+      }
+      if (changed) hooks[event] = kept;
+      continue;
+    }
+
+    const kept = [];
+    for (const group of groups) {
+      const remaining = withoutOurs(group, root, ownedExecutables);
+      if (remaining !== null || !isOursGroup(group, root, ownedExecutables)) kept.push(remaining);
+    }
+    hooks[event] = [...kept, ...expected];
+    changed = true;
+  }
+
+  if (!changed) return { content: raw, changed: false };
+  doc.hooks = hooks;
+  if (!("description" in doc)) doc.description = generated.description;
+  return { content: JSON.stringify(doc, null, 2) + "\n", changed: true };
+}
+
+// updateHooksTemplate 是 Go 侧 CodexHooksUpdateTemplate 的移植：升级时把本工具
+// 的组整体替换为当前模板（不比较 matcher），用户组与其它事件保留。无法安全
+// 合并时返回 ok=false，调用方不得写回。
+export function updateHooksTemplate(raw, root = "", command = "", ownedExecutables = []) {
+  const parsed = parseHooksDoc(raw);
+  if (parsed.error) return { content: raw, ok: false };
+  const doc = parsed.doc;
+  const wanted = command || (root ? hookCommandFor(root) : HOOK_COMMAND);
+  const generated = JSON.parse(defaultHooks(wanted));
+  const ours = generated.hooks;
+  const hooks = doc.hooks;
+  if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) {
+    return { content: raw, ok: false };
+  }
+  for (const event of Object.keys(ours)) {
+    const value = hooks[event];
+    if (value !== undefined && value !== null && !Array.isArray(value)) {
+      return { content: raw, ok: false };
+    }
+  }
+
+  let changed = false;
+  for (const event of Object.keys(ours)) {
+    const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const expected = ours[event];
+    const kept = [];
+    for (const group of groups) {
+      const remaining = withoutOurs(group, root, ownedExecutables);
+      if (remaining !== null || !isOursGroup(group, root, ownedExecutables)) {
+        kept.push(remaining);
+      }
+    }
+    const next = [...kept, ...expected];
+    if (JSON.stringify(groups) === JSON.stringify(next)) continue;
+    hooks[event] = next;
+    changed = true;
+  }
+
+  if (!changed) return { content: raw, ok: true };
+  doc.hooks = hooks;
+  if (!("description" in doc)) doc.description = generated.description;
+  return { content: JSON.stringify(doc, null, 2) + "\n", ok: true };
+}
+
+// scrubHooks 是 Go 侧 ScrubCodexHooks 的移植：只摘本工具的命令（裸命令或
+// `<root>/specrune/bin/` 下的绝对路径）。分组里只剩我们的条目时删分组、事件
+// 数组空了删事件键、hooks 对象空了删 hooks 键；顶层 description 只在仍是模板
+// 原文时删。
+export function scrubHooks(raw, root = "", ownedExecutables = []) {
+  const parsed = parseHooksDoc(raw);
+  if (parsed.error) return { error: parsed.error };
+  const doc = parsed.doc;
+  let changed = false;
+
+  const hooks = doc.hooks;
+  if (hooks && typeof hooks === "object" && !Array.isArray(hooks)) {
+    for (const event of Object.keys(hooks)) {
+      const groups = hooks[event];
+      if (!Array.isArray(groups)) continue;
+      const kept = [];
+      for (const group of groups) {
+        if (isOursGroup(group, root, ownedExecutables)) changed = true;
+        const remaining = withoutOurs(group, root, ownedExecutables);
+        if (remaining !== null || !isOursGroup(group, root, ownedExecutables)) {
+          kept.push(remaining);
+        }
+      }
+      if (kept.length === 0) {
+        delete hooks[event];
+      } else {
+        hooks[event] = kept;
+      }
+    }
+    if (changed && Object.keys(hooks).length === 0) {
+      delete doc.hooks;
+    }
+  }
+
+  if (doc.description === HOOK_DESCRIPTION) {
+    delete doc.description;
+    changed = true;
+  }
+
+  if (!changed) return { content: raw, changed: false, fullyEmpty: false };
+  const fullyEmpty = Object.keys(doc).length === 0;
+  return {
+    // 与 Go 的 finishScrub 同形：即便对象已空也返回规范 JSON，由调用方按
+    // fullyEmpty 决定删文件；返回值本身永远是可解析的 JSON 字节。
+    content: JSON.stringify(doc, null, 2) + "\n",
+    changed: true,
+    fullyEmpty,
+  };
+}
+
+// hooksHaveOurHook 判断 hooks.json 里有没有本工具的 hook 条目。
+export function hooksHaveOurHook(raw, root = "", ownedExecutables = []) {
+  const parsed = parseHooksDoc(raw);
+  if (parsed.error) return false;
+  const hooks = parsed.doc.hooks;
+  if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) return false;
+  for (const value of Object.values(hooks)) {
+    if (
+      Array.isArray(value) &&
+      value.some((group) => isOursGroup(group, root, ownedExecutables))
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function resolveTargets(opts, ctx) {
+  if (ctx) ctx.command = opts.command;
+  // 只支持项目级：--dir 是项目根，默认当前目录。这里不做向上查找——
+  // 安装位置必须由用户显式所在的项目决定，猜祖先仓库只会写错地方。
+  const projectRoot = resolve(opts.dir || process.cwd());
+  return {
+    scope: "project",
+    projectRoot,
+    root: join(projectRoot, ".codex"),
+    statePath: join(projectRoot, ...STATE_REL.split("/")),
+  };
+}
+
+function binaryUsable(path) {
+  if (!path) return false;
+  try {
+    readFileSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ownedCliPaths(bundledBinary, state) {
+  return [bundledBinary, state?.cliPath].filter(
+    (path) => typeof path === "string" && path !== "",
+  );
+}
+
+// Codex 只能项目级：显式传 global 时纠正为 project，并让调用方输出实际 scope。
+function actualScope(requested) {
+  return { scope: "project", correctedFrom: requested === "global" ? "global" : "" };
+}
+
+// 互斥检测的另一 scope：Codex 没有全局安装，但用户可能手工留过 ~/.codex
+// 的 agents/hooks；两处都在会让 Codex 看到重复子代理与 hook。
+function detectOtherScope(targets, ctx) {
+  const bundledBinary = ctx?.locateBinary ? ctx.locateBinary() : locateBundledBinary();
+  const ownedPaths = ownedCliPaths(bundledBinary, loadState(targets.statePath).state);
+  const root = join(homedir(), ".codex");
+  const found = [];
+  for (const file of templateAgents()) {
+    try {
+      if (existsSync(resolveWithin(root, file.rel))) found.push(file.rel);
+    } catch {
+      /* 越界，跳过 */
+    }
+  }
+  const raw = readIfExists(join(root, HOOKS_REL));
+  if (raw !== null && hooksHaveOurHook(raw, root, ownedPaths)) found.push(HOOKS_REL);
+  if (existsSync(join(root, ...bundledRel().split("/")))) found.push(bundledRel());
+  return { scope: "global", root, found, installed: found.length > 0 };
+}
+
+// 与迁移前逐字一致：测试锁的是「拒绝 + 指出全局 ~/.codex + 提示 --force」。
+function otherScopeError(other) {
+  return (
+    `specrune-codex: 检测到全局 ~/.codex 已有 Codex 安装痕迹` +
+    `（${other.found.length} 个，位于 ${other.root}）；继续安装会重复定义子代理/hook。` +
+    `请先清理这些全局文件；确认要并存时加 --force。\n`
+  );
+}
+
+function forceWarning(other) {
+  return `已按 --force 忽略全局 ~/.codex 的既有安装痕迹（${other.root}）；两处并存会重复加载，请尽快清理。`;
+}
+
+function scopeCorrectionWarning() {
+  return "已按 project 安装（Codex 适配只支持项目级，不写全局配置）";
+}
+
+function hookInfo(bundledBinary) {
+  const cliUsable = binaryUsable(bundledBinary);
+  // CLI 全局唯一：project 模式不复制二进制，hook 指向解析到的全局 CLI。
+  return {
+    cliUsable,
+    cliPath: cliUsable ? resolve(bundledBinary) : "",
+    command: hookCommandForBinary(cliUsable ? resolve(bundledBinary) : ""),
+  };
+}
+
+function mergeOwnedConfig(targets, templates, opts, ctx) {
+  const bundledBinary = ctx.bundledBinary ?? (ctx.locateBinary ? ctx.locateBinary() : "");
+  if (bundledBinary) ctx.bundledBinary = bundledBinary;
+  const info = hookInfo(bundledBinary);
+  const ownedPaths = ownedCliPaths(bundledBinary, ctx.state);
+
+  // hooks.json 是混合所有权文件：只增删本工具条目，绝不整体替换。
+  const hooksAbs = join(targets.root, HOOKS_REL);
+  const hooksRaw = ctx.readIfExists(hooksAbs);
+  let action = "unchanged";
+  let content = null;
+  if (hooksRaw === null || hooksRaw.trim() === "") {
+    action = "created";
+    content = defaultHooks(info.command);
+  } else {
+    const merged = mergeHooks(hooksRaw, targets.root, info.command, ownedPaths);
+    if (merged.error) {
+      ctx.warn(
+        `${HOOKS_REL}: ${merged.error}，已保留原文件未改动；请手工把 ` +
+          `"${info.command}" 加进对应事件。`,
+      );
+      action = "skipped";
+    } else if (merged.changed) {
+      action = "updated";
+      content = merged.content;
+    }
+  }
+  if (content !== null && !opts.dryRun) {
+    ctx.atomicWriteFile(hooksAbs, content);
+  }
+  return { label: "hooks", action, path: hooksAbs };
+}
+
+function scrubOwnedConfig(targets, state, opts, ctx) {
+  const bundledBinary = ctx.locateBinary ? ctx.locateBinary() : locateBundledBinary();
+  const ownedPaths = ownedCliPaths(bundledBinary, state);
+
+  // hooks.json 走键级擦除：用户其它分组、事件与顶层键必须原样留下。
+  // 擦完为空才删文件。
+  const hooksAbs = join(targets.root, HOOKS_REL);
+  const hooksRaw = ctx.readIfExists(hooksAbs);
+  if (hooksRaw === null) {
+    return { label: "hooks", action: "absent", path: hooksAbs };
+  }
+  const scrubbed = scrubHooks(hooksRaw, targets.root, ownedPaths);
+  if (scrubbed.error) {
+    ctx.warn(`${HOOKS_REL}: ${scrubbed.error}，未改动；请手工移除本工具的 hook 条目。`);
+    return { label: "hooks", action: "skipped", path: hooksAbs };
+  }
+  if (!scrubbed.changed) {
+    return { label: "hooks", action: "unchanged", path: hooksAbs };
+  }
+  if (scrubbed.fullyEmpty) {
+    if (!opts.dryRun) unlinkSync(hooksAbs);
+    return {
+      label: "hooks",
+      action: "removed",
+      path: hooksAbs,
+      removedRel: HOOKS_REL,
+    };
+  }
+  if (!opts.dryRun) ctx.atomicWriteFile(hooksAbs, scrubbed.content);
+  return { label: "hooks", action: "updated", path: hooksAbs };
+}
+
+// ---- 输出：保持迁移前逐字一致 ----
+
+function installPlanLines(result) {
+  const { targets, bundledBinary, skills, stats, merge } = result;
+  const info = hookInfo(bundledBinary);
+  const lines = [];
+  lines.push(`[dry-run] specrune 二进制: ${bundledBinary || "（未找到，hook 回退 PATH）"}`);
+  if (skills) lines.push(`[dry-run] 技能: ${skills.scope} ${skills.sharedRoot}`);
+  lines.push(`[dry-run] hook 命令: ${info.command}`);
+  for (const rel of stats.created) {
+    lines.push(`[dry-run] 写入 ${join(targets.root, ...rel.split("/"))}`);
+  }
+  for (const rel of stats.updated) {
+    lines.push(`[dry-run] 更新 ${join(targets.root, ...rel.split("/"))}`);
+  }
+  for (const rel of stats.unchanged) {
+    lines.push(`[dry-run] 未变 ${join(targets.root, ...rel.split("/"))}`);
+  }
+  for (const rel of stats.skipped) {
+    lines.push(`[dry-run] 保留 ${join(targets.root, ...rel.split("/"))}`);
+  }
+  for (const rel of stats.stale) {
+    lines.push(`[dry-run] 删除 ${join(targets.root, ...rel.split("/"))}`);
+  }
+  if (merge && (merge.action === "created" || merge.action === "updated")) {
+    lines.push(`[dry-run] ${merge.action === "created" ? "写入" : "更新"} ${merge.path}`);
+  }
+  lines.push(`[dry-run] 写状态 ${targets.statePath}`);
+  return lines.join("\n") + "\n";
+}
+
+function installSummary(result) {
+  const { targets, bundledBinary, skills, stats, merge, opts } = result;
+  const info = hookInfo(bundledBinary);
+  const prefix = opts.dryRun ? "[dry-run] " : "";
+  const stale = stats.stale.length > 0 ? ` / 清理 ${stats.stale.length}` : "";
+  return (
+    `${prefix}specrune-codex ${PKG.version}（scope=project）\n` +
+    `  项目根: ${targets.projectRoot}\n` +
+    `  状态文件: ${targets.statePath}\n` +
+    `  CLI: global（${info.cliUsable ? info.cliPath : "PATH 回退"}）\n` +
+    `  技能: ${skills ? `${skills.scope} ${skills.sharedRoot}` : "未安装（CLI 不可用或失败）"}\n` +
+    `  hook 命令: ${info.command}\n` +
+    `  新增 ${stats.created.length} / 更新 ${stats.updated.length} / 未变 ${stats.unchanged.length} / 保留 ${stats.skipped.length}${stale}\n` +
+    `  hooks: ${merge ? merge.action : "unchanged"}\n`
+  );
+}
+
+function uninstallSummary(result) {
+  const { targets, skill, scrub, removed, kept, opts } = result;
+  const prefix = opts.dryRun ? "[dry-run] " : "";
+  const lines = [
+    `${prefix}specrune-codex 卸载（scope=project）`,
+    `  项目根: ${targets.projectRoot}`,
+    `  技能: ${skill.record ? `${skill.record.scope} ${skill.record.sharedRoot}` : "未变更（CLI 不可用或失败）"}`,
+    `  删除 ${removed.length} / 保留 ${kept.length}`,
+    `  hooks: ${scrub ? scrub.action : "absent"}`,
+  ];
+  if (opts.dryRun && result.extra?.binDirExists) {
+    lines.push(`  [dry-run] 删除 ${result.extra.binDir}`);
+  }
+  for (const rel of removed) lines.push(`  - ${rel}`);
+  return lines.join("\n") + "\n";
+}
+
+// 返回完整 payload：binary 与 hooks 在旧输出里位于 files 与 skills 之间，
+// 只有控制字段顺序才能保持 status --json 的字节级兼容。
+function statusPayload(targets, state, ctx, payload) {
+  const bundledBinary = ctx.locateBinary ? ctx.locateBinary() : locateBundledBinary();
+  const ownedPaths = ownedCliPaths(bundledBinary, state);
+
+  // 二进制即使不在状态里（旧版状态、手工删过状态）也要单独报告：它决定 hook
+  // 绝对路径是否还指向一个真实可执行文件。
+  const binaryAbs = join(targets.root, ...bundledRel().split("/"));
+  const binaryExisting = readTemplateExisting(binaryAbs, true);
+  const binaryEntry = (state?.files ?? []).find((entry) => isBinaryRel(entry.path));
+  let binaryState = "missing";
+  if (binaryExisting !== null) {
+    binaryState = !binaryEntry
+      ? "present"
+      : hashContent(binaryExisting) === binaryEntry.sha256
+        ? "ok"
+        : "modified";
+  }
+  const binary = { path: binaryAbs, present: binaryExisting !== null, state: binaryState };
+
+  const hooksAbs = join(targets.root, HOOKS_REL);
+  const hooksRaw = ctx.readIfExists(hooksAbs);
+  let hooksCommand = null;
+  if (hooksRaw !== null) {
+    const parsed = parseHooksDoc(hooksRaw);
+    if (!parsed.error) {
+      outer: for (const groups of Object.values(parsed.doc.hooks ?? {})) {
+        if (!Array.isArray(groups)) continue;
+        for (const group of groups) {
+          if (!Array.isArray(group?.hooks)) continue;
+          for (const entry of group.hooks) {
+            if (isOursCommand(entry, targets.root, ownedPaths)) {
+              hooksCommand = entry.command;
+              break outer;
+            }
+          }
+        }
+      }
+    }
+  }
+  const hooks = {
+    path: hooksAbs,
+    present: hooksRaw !== null,
+    hook: hooksRaw !== null && hooksHaveOurHook(hooksRaw, targets.root, ownedPaths),
+    command: hooksCommand,
+  };
+
+  return {
+    scope: "project",
+    projectRoot: targets.projectRoot,
+    root: payload.root,
+    statePath: payload.statePath,
+    installed: Boolean(payload.installed) || hooks.hook,
+    protocol: payload.protocol,
+    version: payload.version,
+    cli: payload.cli,
+    cliPath: state?.cliPath ?? null,
+    files: payload.files,
+    binary,
+    hooks,
+    skills: payload.skills,
+    otherScope: payload.otherScope,
+  };
+}
+
+function statusSummary(payload, targets, ctx) {
+  const other = payload.otherScope || {
+    scope: "global",
+    root: null,
+    installed: false,
+    found: [],
+  };
+  const hooks = payload.hooks;
+  const lines = [
+    `scope: project`,
+    `项目根: ${payload.projectRoot}`,
+    `宿主根: ${payload.root}`,
+    `状态文件: ${payload.statePath}`,
+    `CLI: ${payload.cli ?? "unknown"}${payload.cliPath ? `（${payload.cliPath}）` : ""}`,
+    `技能: ${core.skillsLabel(payload.skills)}`,
+    `其它 scope: ${other.scope} ${other.root} — ${
+      other.installed ? `已安装（${other.found.length} 个文件）` : "未安装"
+    }`,
+    `旧版宿主目录二进制: ${
+      payload.binary.present
+        ? `${payload.binary.path}（${payload.binary.state}）`
+        : "缺失（新版不复制，hook 指向全局 CLI）"
+    }`,
+    `hook 命令: ${hooks.command ?? "未挂载"}`,
+  ];
+  if (!payload.installed) {
+    const suffix = ctx.state === null && !ctx.stateError ? "（无状态文件）" : "";
+    lines.push(`状态: 未安装${suffix}`);
+    return lines.join("\n") + "\n";
+  }
+  lines.push(
+    `状态: 已安装（specrune-codex ${payload.version ?? "-"}，protocol ${payload.protocol ?? "-"}）`,
+  );
+  for (const file of payload.files) {
+    const label = { ok: "正常", modified: "已修改", missing: "缺失" }[file.state] || file.state;
+    lines.push(`  ${file.path}: ${label}`);
+  }
+  lines.push(`  ${HOOKS_REL}: ${hooks.hook ? "已挂载" : "未挂载"}`);
+  return lines.join("\n") + "\n";
+}
+
+// legacyAgentRels 报旧 CLI 写的下划线文件落位。它们与插件当前安装的连字符
+// 文件同名（TOML 的 name 字段相同），两套都在会让 Codex 看到重复子代理定义。
+//
+// 命名不合 `specrune-<role>.toml` 约定的文件推导不出旧落位：跳过而不是原样
+// 保留相对路径，否则刚装好的当前文件会被当成 legacy 误报。
+function legacyAgentRels() {
+  const out = [];
+  for (const file of templateAgents()) {
+    const match = /^specrune-([a-z0-9]+)\.toml$/.exec(basename(file.rel));
+    if (match) out.push({ rel: `${AGENTS_REL}/specrune_${match[1]}.toml` });
+  }
+  return out;
+}
+
+function warnLegacyAgents(targets, warnings) {
+  const found = [];
+  for (const file of legacyAgentRels()) {
+    if (existsSync(resolveWithin(targets.root, file.rel))) found.push(file.rel);
+  }
+  if (found.length > 0) {
+    warnings.push(
+      `检测到旧 CLI 写过的 Codex 子代理（${found.join(", ")}）；它们会与本次安装重复定义同名子代理。` +
+        `请手工删除这些旧文件（保留内容已改过的）。`,
+    );
+  }
+}
+
+// 解析到的路径存在但读不到时，核心不会替你告警（它只按「解析结果为空」判断），
+// 这里补上同一条可行动提示。
+function legacyWarnings(targets, warnings, ctx) {
+  const bundledBinary = ctx.bundledBinary ?? (ctx.locateBinary ? ctx.locateBinary() : "");
+  if (bundledBinary && !binaryUsable(bundledBinary)) {
+    warnings.push(missingBinaryWarning(bundledBinary));
+  }
+  warnLegacyAgents(targets, warnings);
+}
+
+// `<root>/specrune/` 整个目录归本工具：即便状态文件丢了、二进制被改过，
+// 卸载语义也是清场。只删这一个目录，不碰宿主根下其它内容。
+function uninstallExtra(targets, state, opts, ctx) {
+  const binDir = join(targets.root, "specrune");
+  const binDirExists = existsSync(binDir);
+  if (binDirExists && !opts.dryRun) {
+    rmSync(binDir, { recursive: true, force: true });
+  }
+  return { binDir, binDirExists };
+}
+
+const adapter = {
+  name: "codex",
+  displayName: "specrune-codex",
+  command: "specrune-codex",
+  packageName: "specrune-codex",
+  version: PKG.version,
+  protocol: PROTOCOL,
+  coreVersion: REQUIRED_CORE_VERSION,
+  moduleUrl: import.meta.url,
+  usage: USAGE,
+  rootLabel: "宿主根",
+  defaultScope: "project",
+  scopeHint: "Codex 只装项目级，global 会纠正为 project",
+  resolveTargets,
+  templateFiles,
+  actualScope,
+  detectOtherScope,
+  otherScopeError,
+  forceWarning,
+  scopeCorrectionWarning,
+  missingBinaryWarning,
+  mergeOwnedConfig,
+  scrubOwnedConfig,
+  stateFields(result) {
+    const info = hookInfo(result.bundledBinary);
+    return { cli: "global", cliPath: info.cliPath };
+  },
+  installPlanLines,
+  installSummary,
+  uninstallExtra,
+  uninstallSummary,
+  statusPayload,
+  statusSummary,
+  legacyWarnings,
+};
+
+export const { install, uninstall, status, parse, main } = createInstaller(adapter);
+export { adapter };