tmuxclihook 0.4.1 → 0.5.1

package/README.md

@@ -9,9 +9,16 @@
 npm install -g tmuxclihook
 tmuxclihook
 
-# 检查 npm registry 并将全局安装更新到最新版
+# 按当前安装方式（npm/volta）检查并更新到最新版
 tmuxclihook update
 
+# 升级并直接删除不生效的另一份安装（默认会交互确认）
+tmuxclihook update --prune
+
+# hooks 健康明细（非交互）：每个 CLI 的完整性、判定真源、注册路径、漂移警告
+# 可选参数 claude|codex|opencode 只看一个；exit 1 = 有缺失或漂移
+tmuxclihook check
+
 # 查看版本 / 帮助（version、--version、-v 与 help、--help、-h 等价）
 tmuxclihook --version
 tmuxclihook --help
@@ -30,16 +37,18 @@ npm start
 
 hooks 安装、tmux 集成写入的路径由「source」决定：环境变量 `TMUXCLIHOOK_SOURCE` > 持久化配置 `~/.config/tmuxclihook/config.json`（TUI「source 管理」菜单写入）> 包内自带 scripts/（生产默认）> 仓库根 scripts/（`cd installer && npm start` 时的开发回落）。见下方「source 管理」一节。
 
-`tmuxclihook update` 会显示当前版本，通过 `npm view tmuxclihook version` 查询最新版；版本不同时直接执行 `npm install -g tmuxclihook@latest`，版本相同则不做修改。网络查询或安装失败时命令以非零状态退出。
+`tmuxclihook update` 会显示当前版本，通过 `npm view tmuxclihook version` 查询最新版；版本相同则不做修改。需要升级时，它按 PATH 上第一个可执行的 `tmuxclihook` 判断当前生效的安装方式：入口位于 `$VOLTA_HOME/bin/`（默认 `~/.volta/bin/`）或 volta 的 packages 镜像内时，只执行 `volta install tmuxclihook@latest`；其余入口（npm 全局、nvm/fnm 等 node 工具链目录）只执行 `npm install -g tmuxclihook@latest`。不会同时写入两套安装。网络查询或安装失败时命令以非零状态退出。
+
+安装完成后会按 PATH 自检实际生效版本。若生效入口不是 volta、自检仍未反映新版，且本机可执行 volta，则补执行一次 `volta install tmuxclihook@latest` 作为兜底并复检；仍不一致时打印警告（不影响退出码）。
 
-安装成功后会做一次生效自检：按 PATH 解析实际会被运行的 `tmuxclihook`，读取其真实版本与最新版比对。若本机使用 volta，`npm install -g` 只会更新 node 工具链目录里的副本、不会更新 volta 的 shim 镜像（实测 volta 2.0.2：shim npm 的全局 prefix 即工具链目录），自检发现这种情况时会自动补执行 `volta install tmuxclihook@latest` 使更新生效并复检；volta 缺失或修正失败时打警告并提示手动命令。`npm install` 始终是标准安装方式，无需因 volta 改变习惯。
+升级确认成功后，update 会检查另一套安装（volta packages 镜像或当前 npm 全局 prefix）是否还留有副本。发现副本时：TTY 下询问是否删除（默认不删）；非交互环境只打印警告；`--prune` 跳过询问直接删除。删除前会校验该副本未被任何 hooks 与 `~/.tmux.conf` 引用——任一检查无法确认就保留并提示先重装 hooks。**生效入口永远不删**，清理失败不影响升级结果。也可以手动收敛：卸载不再使用的那份（`npm uninstall -g tmuxclihook` 或 `volta uninstall tmuxclihook`），再从生效入口重新安装 hooks。
 
 ## 功能
 
 | 菜单项 | 说明 |
 |--------|------|
 | 环境检查 | 侦测 tmux(≥3.1) / jq / bash(任意版本) / node(≥18)，显示 `✓ ready`、`✗ missing`、`⚠ outdated`，并在确认后安全修复。检测到 cc-switch（`~/.cc-switch/cc-switch.db`）时追加 sqlite3 项 |
-| 侦测 AI CLI | 扫描 Claude Code / Codex / opencode，显示版本、最低版本和 hooks 状态；不自动安装或升级 AI CLI。cc-switch 环境下 Claude Code 的 hooks 状态由 bash 侧 `install-claude-hooks.sh check`（sqlite 真源）判定 |
+| 侦测 AI CLI | 扫描 Claude Code / Codex / opencode，显示版本、最低版本和 hooks 健康明细（判定真源、缺失原因、注册路径、漂移警告，见下节）；不自动安装或升级 AI CLI。判定全部走 bash 侧 wrapper `check --json`（cc-switch 模式在 bash 内查 sqlite 真源），TUI 只渲染 |
 | 安装 hooks | 选工具（claude/codex/opencode/全部）→ 调 `scripts/install-<tool>-hooks.sh`（路径随当前 source 解析） |
 | 卸载 hooks | 对称卸载本插件 hooks，保留其他工具注册的 hook |
 | 修复 hooks | 完整性检查 → 缺失则重装 |
@@ -47,6 +56,27 @@ hooks 安装、tmux 集成写入的路径由「source」决定：环境变量 `T
 | source 管理 | 查看当前生效 source（来源 + 失效警告）；设置本地仓库路径用于开发调试；清除持久化配置恢复默认 |
 | 完整卸载插件 | 停止 Codex monitor、清除聚合状态 `@ai_all_status`、清理历史遗留软链（不删仓库）；`.tmux.conf` 删声明与 `tmux kill-server` 因破坏性仅打印手动指引 |
 
+### hooks 健康明细与漂移收敛
+
+`tmuxclihook check`（子命令）与 TUI「侦测 AI CLI」共用同一份 bash 侧明细：每个 wrapper 的 `check --json` 模式输出单行 JSON（status / 判定真源 mode / 逐事件 registered+alive / opencode plugin 结构指纹 / suppress 标记 / drift）。默认 `check`（无 `--json`）输出逐字节不变（`ok`/`missing` + exit code），TUI 与 tmux 自修复的既有契约不受影响。
+
+**漂移（drift）**：hooks 指向其他安装源但脚本仍存活（典型场景：本地调试切 source 后、volta 换路径后旧包仍可用）。此时功能未坏、check 仍判 `ok`，但 `tmuxclihook check` 与 TUI 会给出 ⚠ 警告并列出旧路径。漂移参照系是**执行中的 wrapper 自身路径**——`tmuxclihook`/TUI 经当前 source 调 wrapper，警告即「已装 hooks 不是当前 source 写的」。
+
+**发现漂移后的收敛（策略不对称）**：
+
+| 配置 | 收敛代价 | 方式 |
+|------|---------|------|
+| Claude Code hooks | 无（install 幂等强收敛） | TUI 选择即收敛 |
+| Codex hooks | 重写 `hooks.json` 使 `trusted_hash` 失效，需重新 Trust all | TUI 显式确认后收敛（`TMUX_AI_FORCE_INSTALL=1` 旁路 no-op 门禁） |
+| opencode plugin | 无信任代价（整文件重写） | TUI 确认后收敛 |
+| `.tmux.conf` 声明 | 无 | 复用「tmux 集成」的原地替换 + 重载 |
+
+非交互场景下 `tmuxclihook check` 只报告并 exit 1，收敛动作需回 TUI（或手动跑对应 `install-<tool>-hooks.sh`；codex 记得带 `TMUX_AI_FORCE_INSTALL=1`）。
+
+### Esc 导航
+
+clack 0.7 只把 ctrl+c 映射为取消（Esc 默认无效果），安装器在 TUI 内把 Esc 转译为合成取消：**主菜单 Esc 退出**、子菜单 Esc 返回主菜单、确认/输入框 Esc 取消。spinner 期间 Esc 静默（避免误触硬退出）；ctrl+c 行为不变。
+
 ### cc-switch 模式（Claude Code）
 
 检测到 `~/.cc-switch/cc-switch.db` 时，Claude Code hooks 的装/卸/修/状态检查全部指向其通用配置（db `settings` 表 `common_config_claude`）——`switch` 命令启动 claude 时会把通用配置合并进实例配置，`~/.claude/settings.json` 与实例文件都会被 cc-switch 覆盖，直接写它们不持久。写入用与 cc-switch 自身一致的 `json_patch` 原子更新，他人 hook 与配置其他字段保留。注意：cc-switch GUI 运行中会把内存缓存写回 db，安装前建议先退出 GUI（脚本会警告）；不经 `switch` 直接运行的 `claude` 读不到 db 里的 hooks。

package/bin/cli.js

@@ -14,10 +14,12 @@ import { checkEnv, detectClis, interactiveShell } from '../src/detect.js';
 import { planBrewRemediation, runBrewAction } from '../src/env.js';
 import { installHooks, uninstallHooks, repairHooks } from '../src/hooks.js';
 import { checkSymlink, checkTmuxConf } from '../src/symlink.js';
+import { checkToolDetail, renderToolDetail, summarizeDetails } from '../src/check-detail.js';
 import { ensureTmuxIntegration, reloadTmux } from '../src/tmuxconf.js';
 import { stopMonitor, clearAggregateStatus, removeSymlinks } from '../src/purge.js';
 import {
   TOOLS,
+  toolById,
   repoExists,
   REPO_ROOT,
   TMUX_ENTRY,
@@ -26,12 +28,24 @@ import {
   refreshSource,
 } from '../src/adapters-meta.js';
 import { setSource, clearSource, getPersistedSource, originLabel } from '../src/source.js';
+import { enableEscapeCancel, setSpinnerActive } from '../src/esc.js';
 import { note, padDisplay } from '../src/tui.js';
 import { updatePackage, CURRENT_VERSION } from '../src/update.js';
 
 const OK = '✓';
 const NO = '✗';
 
+// p.spinner 的包装：spinner 活跃期间 esc.js 不把 Esc 转译为 ctrl+c
+// （否则 Esc 会在 spinner 期间触发 block() 的 process.exit 硬退出）。
+function spinner(...args) {
+  const s = p.spinner(...args);
+  const start = s.start.bind(s);
+  const stop = s.stop.bind(s);
+  s.start = (...a) => { setSpinnerActive(true); return start(...a); };
+  s.stop = (...a) => { setSpinnerActive(false); return stop(...a); };
+  return s;
+}
+
 function renderEnvResults(results, title = '环境依赖') {
   const lines = results.map((result) => {
     const mark = result.status === 'ready' ? OK : result.status === 'outdated' ? '⚠' : NO;
@@ -41,7 +55,7 @@ function renderEnvResults(results, title = '环境依赖') {
 }
 
 async function doctor() {
-  const s = p.spinner();
+  const s = spinner();
   s.start('检查环境依赖');
   const results = await checkEnv();
   s.stop('环境检查完成');
@@ -101,14 +115,14 @@ async function doctor() {
     const entry = entryByKey.get(key);
     if (!entry) continue;
 
-    const s2 = p.spinner();
+    const s2 = spinner();
     s2.start(entry.command);
     const result = await runBrewAction(entry.action, entry.pkg);
     if (result.ok) s2.stop(`${OK} ${entry.name} 修复命令执行完成`);
     else s2.stop(`${NO} ${entry.name} 修复失败: ${result.output}`);
   }
 
-  const verifySpinner = p.spinner();
+  const verifySpinner = spinner();
   verifySpinner.start('重新检查环境依赖');
   const finalResults = await checkEnv();
   verifySpinner.stop('环境复检完成');
@@ -122,7 +136,7 @@ async function doctor() {
 }
 
 async function detectCliMenu() {
-  const s = p.spinner();
+  const s = spinner();
   s.start('侦测已安装的 AI CLI');
   const rows = await detectClis();
   s.stop('侦测完成');
@@ -131,10 +145,88 @@ async function detectCliMenu() {
     if (!r.installed) return `  ${NO} ${padDisplay(r.label, 14)} 未安装`;
     const verMark = r.meetsMin ? OK : '⚠';
     const minNote = r.minVersion && !r.meetsMin ? ` (需 ≥ ${r.minVersion})` : '';
-    const hookNote = r.hooksInstalled ? '已装 hooks' : '未装 hooks';
-    return `  ${verMark} ${padDisplay(r.label, 14)} v${r.version}${minNote}  ${hookNote}`;
+    return `  ${verMark} ${padDisplay(r.label, 14)} v${r.version}${minNote}`;
   });
   note(lines.join('\n'), 'AI CLI');
+
+  // 逐工具 hooks 明细（判定在 bash 侧 check --json，这里只渲染——缺失原因、
+  // 判定真源、注册路径、漂移）。未安装的 CLI 跳过（wrapper 判 missing 无意义）。
+  const details = [];
+  for (const r of rows) {
+    if (!r.installed) continue;
+    const tool = toolById(r.id);
+    if (!tool) continue;
+    const d = await checkToolDetail(tool);
+    details.push(d);
+    note(renderToolDetail(d).join('\n'), `${r.label} hooks 明细`);
+  }
+
+  await offerDriftConvergence(details);
+}
+
+// 漂移收敛入口：检测（check --json 的 drift 字段 + .tmux.conf 的 pointsToCurrent）
+// 与收敛分离。收敛策略不对称——claude 无代价直接收敛；codex 重写即 trusted_hash
+// 失效，必须显式确认；opencode 重写无信任代价，确认一次即可。
+async function offerDriftConvergence(details) {
+  const driftTools = details.filter((d) => d.status !== 'unknown' && d.drift?.drifted);
+  const conf = checkTmuxConf();
+  const confStale = conf.exists && conf.referenced && !conf.pointsToCurrent;
+
+  const options = driftTools.map((d) => ({
+    value: `tool:${d.tool}`,
+    label: `${d.label} hooks 收敛到当前 source`,
+    hint: `旧路径 ${(d.drift.stale || []).join(', ')}`,
+  }));
+  if (confStale) {
+    options.push({ value: 'tmuxconf', label: '.tmux.conf 加载声明更新为当前 source' });
+  }
+  if (options.length === 0) return;
+
+  options.push({ value: '__skip__', label: '← 暂不处理' });
+  p.log.warn('检测到部分配置指向其他安装源（漂移）。功能仍可用，但新安装/自修复只会收敛当前 source。');
+  const sel = await p.select({
+    message: '选择要收敛的项（Esc 跳过）',
+    options,
+  });
+  if (p.isCancel(sel) || sel === '__skip__') return;
+
+  if (sel === 'tmuxconf') {
+    await confirmAndApplyTmuxIntegration(conf);
+    return;
+  }
+
+  const id = sel.slice('tool:'.length);
+  await convergeDrift(id);
+  // 收敛后复检闭环
+  const tool = toolById(id);
+  if (tool) {
+    const d = await checkToolDetail(tool);
+    note(renderToolDetail(d).join('\n'), `${d.label} 收敛后状态`);
+  }
+}
+
+async function convergeDrift(id) {
+  if (id === 'codex') {
+    const go = await p.confirm({
+      message: '重写 ~/.codex/hooks.json 会使 trusted_hash 失效，下次启动 codex 需在 TUI 点 "Trust all and continue" 授信一次。继续收敛？',
+    });
+    if (p.isCancel(go) || !go) { p.log.info('已取消'); return; }
+  } else if (id === 'opencode') {
+    const go = await p.confirm({
+      message: '将重写 plugin 文件指向当前 source（本地插件无需重新授信）。继续收敛？',
+    });
+    if (p.isCancel(go) || !go) { p.log.info('已取消'); return; }
+  }
+  // claude 无代价（install 本就幂等强收敛），选择即确认
+  const r = await installHooks(id, { force: true });
+  if (r.ok) {
+    p.log.success(`${OK} ${id} hooks 已收敛到当前 source`);
+    if (id === 'codex') p.log.warn('下次启动 codex 时选择 "Trust all and continue" 授信一次。');
+    if (r.output) p.log.message(r.output.trim());
+  } else {
+    p.log.error(`${NO} ${id} 收敛失败`);
+    p.log.error(r.output || '未知错误');
+  }
 }
 
 async function pickTool(message) {
@@ -155,7 +247,7 @@ async function runHookAction(action, verb) {
   if (!sel) { p.log.info('返回主菜单'); return; }
   const ids = sel === '__all__' ? TOOLS.map((t) => t.id) : [sel];
   for (const id of ids) {
-    const s = p.spinner();
+    const s = spinner();
     s.start(`${verb} ${id} hooks`);
     const r = await action(id);
     if (r.ok) {
@@ -317,6 +409,9 @@ async function purgeMenu() {
 
 async function main() {
   p.intro('tmux-ai-status 安装器');
+  // clack 0.7 只认 ctrl+c 取消；启用 Esc → 合成 ctrl+c 的转译后，
+  // 主菜单 Esc 退出、子菜单 Esc 返回、confirm/text Esc 取消全部真实生效。
+  enableEscapeCancel();
 
   note(currentSourceLines().join('\n'), 'source 状态');
 
@@ -328,10 +423,10 @@ async function main() {
 
   while (true) {
     const choice = await p.select({
-      message: '选择操作（Esc 在子菜单返回主页面）',
+      message: '选择操作（Esc 退出；子菜单 Esc 返回本菜单）',
       options: [
         { value: 'doctor', label: '环境检查', hint: 'tmux / jq / bash / node' },
-        { value: 'detect', label: '侦测 AI CLI', hint: '版本 + hooks 状态' },
+        { value: 'detect', label: '侦测 AI CLI', hint: '版本 + hooks 明细 + 漂移' },
         { value: 'install', label: '安装 hooks' },
         { value: 'uninstall', label: '卸载 hooks' },
         { value: 'repair', label: '修复 hooks', hint: '完整性检查 + 缺失重装' },
@@ -341,11 +436,9 @@ async function main() {
         { value: 'exit', label: '退出' },
       ],
     });
-    // 主菜单是顶层：Esc（isCancel）不退出程序，留在主菜单；退出仅走「退出」项。
-    if (p.isCancel(choice)) {
-      p.log.info('已在主菜单（退出请选「退出」项）');
-      continue;
-    }
+    // 主菜单是顶层：Esc 经 esc.js 转译为合成 ctrl+c → isCancel，与「退出」项等价
+    // （outro 在循环后统一输出）。子菜单 isCancel → 返回主菜单的既有语义同时被激活。
+    if (p.isCancel(choice)) break;
     if (choice === 'exit') break;
 
     try {
@@ -365,14 +458,50 @@ async function main() {
   p.outro('完成');
 }
 
+// tmuxclihook check [claude|codex|opencode] — hooks 健康明细（非交互）。
+// 判定全在 bash 侧 check --json，这里渲染；末尾附 bash 判不了的两项全局信息
+// （.tmux.conf 加载声明指向、当前 source）。有缺失/漂移/无法判定 → exitCode 1。
+async function runCheckCommand(only) {
+  let tools = TOOLS;
+  if (only) {
+    const t = toolById(only);
+    if (!t) {
+      console.error(`未知工具: ${only}（可选 claude|codex|opencode）`);
+      process.exitCode = 1;
+      return;
+    }
+    tools = [t];
+  }
+  const details = [];
+  for (const t of tools) {
+    const d = await checkToolDetail(t);
+    details.push(d);
+    console.log(`${d.label} hooks：`);
+    console.log(renderToolDetail(d).join('\n'));
+  }
+  const conf = checkTmuxConf();
+  console.log('.tmux.conf：');
+  console.log(`  ${confStatusLine(conf)}`);
+  console.log('source：');
+  for (const line of currentSourceLines()) console.log(line);
+
+  const s = summarizeDetails(details);
+  if (s.hasMissing || s.hasDrift || s.hasError) process.exitCode = 1;
+}
+
 const arg = process.argv[2];
 if (arg === 'update') {
-  updatePackage().then((ok) => {
+  updatePackage({ prune: process.argv.includes('--prune') }).then((ok) => {
     if (!ok) process.exitCode = 1;
   }).catch((err) => {
     console.error(err);
     process.exitCode = 1;
   });
+} else if (arg === 'check') {
+  runCheckCommand(process.argv[3]).catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+  });
 } else if (arg === '--version' || arg === '-v' || arg === 'version') {
   console.log(`tmuxclihook v${CURRENT_VERSION}`);
 } else if (arg === '--help' || arg === '-h' || arg === 'help') {
@@ -381,7 +510,9 @@ if (arg === 'update') {
     '\n' +
     '用法：\n' +
     '  tmuxclihook              打开交互式 TUI 安装器\n' +
-    '  tmuxclihook update       检查并更新到 npm 最新版本\n' +
+    '  tmuxclihook check        hooks 健康明细（可跟 claude|codex|opencode；exit 1 = 有缺失或漂移）\n' +
+    '  tmuxclihook update       按当前安装方式（npm/volta）检查并更新到最新版本\n' +
+    '  tmuxclihook update --prune  升级后直接删除不生效的另一份安装（默认交互确认）\n' +
     '  tmuxclihook version      显示版本（--version / -v 等价）\n' +
     '  tmuxclihook help         显示本帮助（--help / -h 等价）',
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmuxclihook",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "交互式 TUI 安装器：环境侦测、AI CLI 侦测、tmux-ai-status hooks 装/卸/修、TPM 软链校验",
   "type": "module",
   "bin": {

package/scripts/adapters/claude.sh

@@ -13,6 +13,8 @@
 #   ADAPTER_HOLD_UNMATCHED_PERMISSION "true"|"false" 无请求 ID 时是否保守保持审批态
 #   ADAPTER_INSTALLER         install 脚本绝对路径（供自修复/TUI 调用）
 #   adapter_check_integrity() hooks 是否完整注册本插件（返回 0=完整）
+#   adapter_check_detail()    check --json 明细 JSON 片段（可选实现；仅 install wrapper
+#                             的 check --json 上下文调用，失败输出降级片段不报错）
 #   adapter_install_hooks()   安装 hooks（合并式，保留他人 hook）
 #   adapter_uninstall_hooks() 卸载本插件 hooks
 #
@@ -220,6 +222,63 @@ adapter_check_integrity() {
     return 0
 }
 
+# 明细检查（仅 install wrapper 的 check --json 调用；事件热路径不触达）。
+# stdout 输出单行紧凑 JSON 片段 {"mode":...,"events":{...},"plugin":null,"registeredPaths":[...]}，
+# 由 lib-install-hooks.sh 的 _wrapper_check_json 拼装 tool/status/suppress/drift。
+# 数据源与存活口径（逐条 command test -x）与 adapter_check_integrity 完全一致；
+# status 判定仍由 integrity 本体独立给出，两者永不发散。
+# 任何失败（jq 失败/配置缺失）输出空 events 的降级片段，不 exit 非 0。
+adapter_check_detail() {
+    local mode="file" src="" pairs rows line ev p a
+    if _ccswitch_active; then
+        mode="ccswitch"
+        if ! _ccswitch_dump_common src; then
+            printf '{"mode":"ccswitch","events":{},"plugin":null,"registeredPaths":[]}\n'
+            return 0
+        fi
+    elif [ -f "$ADAPTER_HOOKS_FILE" ]; then
+        src="$ADAPTER_HOOKS_FILE"
+    fi
+    if [ -z "$src" ]; then
+        printf '{"mode":"%s","events":{},"plugin":null,"registeredPaths":[]}\n' "$mode"
+        return 0
+    fi
+    # TSV：event\tscript（不去重、保留零事件——计数与去重交给下游 jq 聚合）
+    pairs=$(jq -r '.hooks as $h |
+        ["SessionStart","SessionEnd","UserPromptSubmit","PreToolUse","PostToolUse",
+         "PostToolUseFailure","PermissionRequest","Notification","Stop","StopFailure"] as $events |
+        $events[] as $e |
+        $h[$e][]?.hooks[]?.command // empty |
+        select(contains("tmux-ai-status")) | split(" ")[0] | "\($e)\t\(.)"' "$src" 2>/dev/null)
+    if [ "$src" != "$ADAPTER_HOOKS_FILE" ]; then
+        rm -f "$src"
+    fi
+    # TSV：event\tscript\talive(0|1)。bash 3.2 无关联数组，逐行展开后由 jq 一次聚合。
+    rows=""
+    while IFS= read -r line; do
+        [ -n "$line" ] || continue
+        ev="${line%%$'\t'*}"
+        p="${line#*$'\t'}"
+        if [ -x "$p" ]; then a=1; else a=0; fi
+        rows="${rows}${ev}"$'\t'"${p}"$'\t'"${a}"$'\n'
+    done <<EOF
+$pairs
+EOF
+    jq -R -s --arg mode "$mode" --arg events "$_CLAUDE_EVENTS" '
+        (reduce ($events | split(" ")[]) as $e
+            ({}; .[$e] = {registered: 0, alive: 0, scriptPaths: []})) as $base
+        | reduce (split("\n") | .[] | select(length > 0) | split("\t")) as $r (
+            $base;
+            .[$r[0]] = {
+                registered: (.[$r[0]].registered + 1),
+                alive: (.[$r[0]].alive + ($r[2] | tonumber)),
+                scriptPaths: ((.[$r[0]].scriptPaths + [$r[1]]) | unique)
+            })
+        | {mode: $mode, events: ., plugin: null,
+           registeredPaths: ([.[] | .scriptPaths[]] | unique)}
+    ' <<<"$rows"
+}
+
 # 安装：合并式更新，保留他人（masko 等）注册的 hook。cc-switch 模式只写库
 # （~/.claude/settings.json 与实例文件都会被 cc-switch 覆盖，写了也不持久）。
 adapter_install_hooks() {

package/scripts/adapters/codex.sh

@@ -74,6 +74,45 @@ adapter_check_integrity() {
 _CODEX_EVENTS="SessionStart UserPromptSubmit PreToolUse PermissionRequest PostToolUse Stop"
 _CODEX_LEGACY_TOML="${CODEX_HOME:-$HOME/.codex}/hooks.toml"
 
+# 明细检查（仅 install wrapper 的 check --json 调用；与 claude adapter 同构）。
+# 差异：无 cc-switch 分支（hooks.json 即文件真源，mode 恒 file）、6 事件、
+# 匹配串为 "tmux-ai-status codex"。失败输出空 events 降级片段，不 exit 非 0。
+adapter_check_detail() {
+    local src="$ADAPTER_HOOKS_FILE" pairs rows line ev p a
+    if [ ! -f "$src" ]; then
+        printf '{"mode":"file","events":{},"plugin":null,"registeredPaths":[]}\n'
+        return 0
+    fi
+    pairs=$(jq -r '.hooks as $h |
+        ["SessionStart","UserPromptSubmit","PreToolUse","PermissionRequest","PostToolUse","Stop"] as $events |
+        $events[] as $e |
+        $h[$e][]?.hooks[]?.command // empty |
+        select(contains("tmux-ai-status codex")) | split(" ")[0] | "\($e)\t\(.)"' "$src" 2>/dev/null)
+    rows=""
+    while IFS= read -r line; do
+        [ -n "$line" ] || continue
+        ev="${line%%$'\t'*}"
+        p="${line#*$'\t'}"
+        if [ -x "$p" ]; then a=1; else a=0; fi
+        rows="${rows}${ev}"$'\t'"${p}"$'\t'"${a}"$'\n'
+    done <<EOF
+$pairs
+EOF
+    jq -R -s --arg mode "file" --arg events "$_CODEX_EVENTS" '
+        (reduce ($events | split(" ")[]) as $e
+            ({}; .[$e] = {registered: 0, alive: 0, scriptPaths: []})) as $base
+        | reduce (split("\n") | .[] | select(length > 0) | split("\t")) as $r (
+            $base;
+            .[$r[0]] = {
+                registered: (.[$r[0]].registered + 1),
+                alive: (.[$r[0]].alive + ($r[2] | tonumber)),
+                scriptPaths: ((.[$r[0]].scriptPaths + [$r[1]]) | unique)
+            })
+        | {mode: $mode, events: ., plugin: null,
+           registeredPaths: ([.[] | .scriptPaths[]] | unique)}
+    ' <<<"$rows"
+}
+
 # 从每个事件数组剔除本插件 group（command 含 tmux-ai-status），事件/hooks 清空后删键。
 _codex_strip_managed() {
     jq '
@@ -99,12 +138,14 @@ _codex_read_existing() {
 # 安装：改写 hooks.json（剥离旧 managed group 后为每事件追加本插件 group），保留他人 hook。
 # no-op if valid：事件齐全且脚本存活时不改写——重写即 trusted_hash 失效（command 路径
 # 变化 → codex 启动要重新 Trust all），跨安装源重复安装因此保持既有授信。
+# TMUX_AI_FORCE_INSTALL=1 旁路 no-op 门禁（漂移收敛专用：hooks 指向其他安装源但脚本
+# 仍存活时 integrity 恒过，普通 install 永远收敛不了；代价由调用方确认 re-trust）。
 # 清理旧 hooks.toml（0.144 不再读取）。trust 无法在 bash 复现，靠用户首启 codex TUI 授信。
 adapter_install_hooks() {
     _install_require_jq
     mkdir -p "$(dirname "$ADAPTER_HOOKS_FILE")" 2>/dev/null || true
     [ -f "$_CODEX_LEGACY_TOML" ] && rm -f "$_CODEX_LEGACY_TOML" && echo "移除旧 hooks.toml（0.144 不再读取）"
-    if adapter_check_integrity; then
+    if adapter_check_integrity && [ -z "${TMUX_AI_FORCE_INSTALL:-}" ]; then
         echo "Codex hooks already installed and valid at $ADAPTER_HOOKS_FILE (no-op, trust preserved)"
         return 0
     fi

package/scripts/adapters/opencode.sh

@@ -56,6 +56,32 @@ adapter_check_integrity() {
     grep -q 'request_id: p.requestID' "$ADAPTER_HOOKS_FILE" 2>/dev/null
 }
 
+# 明细检查（仅 install wrapper 的 check --json 调用）。plugin 模型无逐事件注册数，
+# 明细为 integrity 五段判定拆成的布尔 + HOOK_SCRIPT 提取与存活。失败输出降级片段。
+adapter_check_detail() {
+    local exists="false" marker="false" script="" alive="false"
+    local pa="false" qa="false" pr="false" rid="false"
+    if [ -f "$ADAPTER_HOOKS_FILE" ]; then
+        exists="true"
+        if grep -q "$_OPENCODE_MARKER" "$ADAPTER_HOOKS_FILE" 2>/dev/null; then marker="true"; fi
+        script=$(sed -n 's/^const HOOK_SCRIPT = "\(.*\)"$/\1/p' "$ADAPTER_HOOKS_FILE" 2>/dev/null | head -n 1)
+        if [ -n "$script" ] && [ -x "$script" ]; then alive="true"; fi
+        if grep -q 'case "permission.asked"' "$ADAPTER_HOOKS_FILE" 2>/dev/null; then pa="true"; fi
+        if grep -q 'case "question.asked"' "$ADAPTER_HOOKS_FILE" 2>/dev/null; then qa="true"; fi
+        if grep -q 'case "permission.replied"' "$ADAPTER_HOOKS_FILE" 2>/dev/null; then pr="true"; fi
+        if grep -q 'request_id: p.requestID' "$ADAPTER_HOOKS_FILE" 2>/dev/null; then rid="true"; fi
+    fi
+    jq -cn --arg path "$ADAPTER_HOOKS_FILE" --argjson exists "$exists" --argjson marker "$marker" \
+        --arg script "$script" --argjson alive "$alive" \
+        --argjson pa "$pa" --argjson qa "$qa" --argjson pr "$pr" --argjson rid "$rid" '
+        {mode: "plugin", events: {},
+         plugin: {path: $path, exists: $exists, marker: $marker,
+                  hookScript: $script, hookScriptAlive: $alive,
+                  structure: {permissionAsked: $pa, questionAsked: $qa,
+                              permissionReplied: $pr, requestId: $rid}},
+         registeredPaths: (if ($script | length) > 0 then [$script] else [] end)}'
+}
+
 # 生成 plugin 文件内容。$1 = tmux-ai-status 绝对路径。
 _opencode_plugin_content() {
     local hook_script="$1"
@@ -149,8 +175,9 @@ EOF
 
 # 安装：写出/覆盖 plugin 文件。整文件替换（非合并）——同目录下他人 plugin 文件不受影响。
 # no-op if valid：文件完整且 HOOK_SCRIPT 存活时不重写（避免跨安装源无谓覆盖）。
+# TMUX_AI_FORCE_INSTALL=1 旁路 no-op 门禁（漂移收敛专用；重写无需重新授信）。
 adapter_install_hooks() {
-    if adapter_check_integrity; then
+    if adapter_check_integrity && [ -z "${TMUX_AI_FORCE_INSTALL:-}" ]; then
         echo "opencode plugin already installed and valid at $ADAPTER_HOOKS_FILE (no-op)"
         return 0
     fi

package/scripts/install-claude-hooks.sh

@@ -1,11 +1,13 @@
 #!/bin/bash
 # install-claude-hooks.sh — Claude Code hooks 安装/卸载/检查 wrapper
-# 用法: install-claude-hooks.sh [install|uninstall|check|auto]
+# 用法: install-claude-hooks.sh [install|uninstall|check [--json]|auto]
 #
 # 薄 wrapper：source 公共骨架 + claude adapter，dispatch 到 adapter_install_hooks /
 # adapter_uninstall_hooks。实际逻辑在 scripts/adapters/claude.sh。
 # check：输出 ok/missing（exit 0/1），供 TUI 侦测在 cc-switch 模式下走 bash 侧
 # 完整性判定（sqlite 真源），与非 cc-switch 的文件判定共用同一真相。
+# check --json：单行紧凑明细 JSON（mode/events/plugin/registeredPaths/suppress/drift），
+# 同样 exit 0/1，供 tmuxclihook check 子命令与 TUI 渲染（见 lib-install-hooks.sh）。
 # auto：tmux 入口加载时的自动安装——存在卸载意图标记（suppressed-claude）时不装。
 # 显式 uninstall 成功写标记、显式 install 成功清标记（见 lib-install-hooks.sh）。
 
@@ -22,7 +24,9 @@ case "${1:-install}" in
         _hooks_suppress_write claude
         ;;
     check)
-        if adapter_check_integrity; then
+        if [ "${2:-}" = "--json" ]; then
+            _wrapper_check_json claude
+        elif adapter_check_integrity; then
             echo ok
         else
             echo missing

package/scripts/install-codex-hooks.sh

@@ -1,10 +1,11 @@
 #!/bin/bash
 # install-codex-hooks.sh — Codex CLI hooks 安装/卸载/检查 wrapper（需 codex ≥ 0.144）
-# 用法: install-codex-hooks.sh [install|uninstall|check]
+# 用法: install-codex-hooks.sh [install|uninstall|check [--json]]
 #
 # 薄 wrapper：source 公共骨架 + codex adapter，dispatch 到 adapter_install_hooks /
 # adapter_uninstall_hooks。实际逻辑在 scripts/adapters/codex.sh。
 # check：输出 ok/missing（exit 0/1），供 TUI 侦测走 bash 侧完整性判定。
+# check --json：单行紧凑明细 JSON（mode/events/suppress/drift），同样 exit 0/1。
 # 显式 uninstall 成功写标记、显式 install 成功清标记（见 lib-install-hooks.sh）。
 
 set -o errexit
@@ -20,7 +21,9 @@ case "${1:-install}" in
         _hooks_suppress_write codex
         ;;
     check)
-        if adapter_check_integrity; then
+        if [ "${2:-}" = "--json" ]; then
+            _wrapper_check_json codex
+        elif adapter_check_integrity; then
             echo ok
         else
             echo missing

package/scripts/install-opencode-hooks.sh

@@ -1,10 +1,11 @@
 #!/bin/bash
 # install-opencode-hooks.sh — opencode plugin 安装/卸载/检查 wrapper
-# 用法: install-opencode-hooks.sh [install|uninstall|check]
+# 用法: install-opencode-hooks.sh [install|uninstall|check [--json]]
 #
 # 薄 wrapper：source 公共骨架 + opencode adapter，dispatch 到 adapter_install_hooks /
 # adapter_uninstall_hooks。实际逻辑在 scripts/adapters/opencode.sh。
 # check：输出 ok/missing（exit 0/1），供 TUI 侦测走 bash 侧完整性判定。
+# check --json：单行紧凑明细 JSON（mode/plugin/suppress/drift），同样 exit 0/1。
 # 显式 uninstall 成功写标记、显式 install 成功清标记（见 lib-install-hooks.sh）。
 
 set -o errexit
@@ -20,7 +21,9 @@ case "${1:-install}" in
         _hooks_suppress_write opencode
         ;;
     check)
-        if adapter_check_integrity; then
+        if [ "${2:-}" = "--json" ]; then
+            _wrapper_check_json opencode
+        elif adapter_check_integrity; then
             echo ok
         else
             echo missing

package/scripts/lib-install-hooks.sh

@@ -37,3 +37,41 @@ _hooks_suppress_write() {
     date +%s > "$(_hooks_suppress_file "$1")" 2>/dev/null || true
 }
 _hooks_suppress_clear() { rm -f "$(_hooks_suppress_file "$1")" 2>/dev/null || true; }
+
+# --- check --json：完整性明细 JSON（wrapper 专用，事件热路径不触达）---
+# stdout = 单行紧凑 JSON；exit code 与默认 check 一致（ok→0 / missing→1）。
+# status 判定复用 adapter_check_integrity 本体（同一真源，与 ok/missing 永不发散）；
+# suppress 在 wrapper 层判定（adapter 双上下文不依赖本文件，见各 adapter 头注释）；
+# drift 参照系 = 执行中 wrapper 自身的 _LIB_DIR：Node 侧经 execa 调用的正是其解析出的
+# SCRIPTS_DIR 下的 wrapper，故 _LIB_DIR 即当前 source 的 scripts dir；手动用旧 source
+# 的 wrapper 跑 check 得到「相对该 source 无漂移」也是正确语义（它正是那个源的收敛执行者）。
+_wrapper_check_json() {  # $1=tool id
+    local tool="$1" status="missing" detail suppress
+    if ! command -v jq >/dev/null 2>&1; then
+        printf '{"tool":"%s","status":"missing","mode":"unknown","suppress":false,"events":{},"plugin":null,"registeredPaths":[],"drift":{"drifted":false,"expected":"","currentScriptsDir":"%s","stale":[]},"error":"jq not found"}\n' "$tool" "$_LIB_DIR"
+        exit 1
+    fi
+    detail=$(adapter_check_detail 2>/dev/null) || detail=""
+    [ -n "$detail" ] || detail='{}'
+    if adapter_check_integrity >/dev/null 2>&1; then
+        status="ok"
+    fi
+    if [ -f "$(_hooks_suppress_file "$tool")" ]; then
+        suppress="true"
+    else
+        suppress="false"
+    fi
+    jq -cn --arg tool "$tool" --arg status "$status" --argjson detail "$detail" \
+        --argjson suppress "$suppress" --arg dir "$_LIB_DIR" '
+        ($detail + {tool: $tool, status: $status, suppress: $suppress})
+        | .drift = {
+            expected: ($dir + "/tmux-ai-status"),
+            currentScriptsDir: $dir,
+            stale: (($detail.registeredPaths // [])
+                    | map(select(. != ($dir + "/tmux-ai-status")) ) | unique)
+          }
+        | .drift.drifted = ((.drift.stale | length) > 0)'
+    if [ "$status" != "ok" ]; then
+        exit 1
+    fi
+}

package/scripts/lib-tmux-ai-status.sh

@@ -604,6 +604,13 @@ _maybe_repair_hooks() {
     local installer="${ADAPTER_INSTALLER}"
     if ! _check_hooks_integrity; then
         _ai_log "REPAIR: hooks integrity check failed, reinstalling (${TOOL_ID:-claude})"
-        [ -x "$installer" ] && "$installer" >/dev/null 2>&1 || true
+        # 浮出提示与 SessionStart 修复路径（tmux-ai-status）对齐：修复不再完全静默。
+        # 本函数仅经 _run_refresh 被 tmux hook 事件触发（run-shell 上下文，不在 AI CLI
+        # 同步 hook 路径）；display-message 无 -p 写 client tty 而非调用方 stdout。
+        if [ -x "$installer" ] && "$installer" >/dev/null 2>&1; then
+            tmux display-message "✓ ${TOOL_ID:-claude} hooks 已自动修复（检测到缺失）" 2>/dev/null || true
+        else
+            tmux display-message "⚠ ${TOOL_ID:-claude} hooks 自动修复失败，请运行 tmuxclihook 检查" 2>/dev/null || true
+        fi
     fi
 }

package/src/check-detail.js

@@ -0,0 +1,159 @@
+// check-detail.js — wrapper `check --json` 的解析、规范化与人类可读渲染
+//
+// `tmuxclihook check` 子命令与 TUI「侦测 AI CLI」明细共用；判定逻辑全在 bash 侧
+// （adapter_check_detail + lib-install-hooks.sh 的 _wrapper_check_json），本模块只做
+// 解析与渲染，不重复实现判定（避免两处真源）。status 永远以 bash 的判定为准。
+import { execa } from 'execa';
+
+const OK = '✓';
+const NO = '✗';
+const WARN = '⚠';
+
+const MODE_LABEL = {
+  file: '配置文件',
+  ccswitch: 'cc-switch db（通用配置）',
+  plugin: 'opencode plugin 文件',
+  unknown: '未知',
+};
+
+function defaultRun(tool) {
+  return execa('bash', [tool.installer, 'check', '--json'], { reject: false, timeout: 15000 });
+}
+
+function baseDetail(tool) {
+  return {
+    ok: false,
+    tool: tool.id,
+    label: tool.label,
+    status: 'unknown',
+    mode: 'unknown',
+    suppress: false,
+    events: {},
+    plugin: null,
+    registeredPaths: [],
+    drift: null,
+    error: null,
+    raw: null,
+  };
+}
+
+// 调某工具 wrapper 的 check --json 并解析规范化。
+// 返回 baseDetail 的超集；status='unknown' 表示 wrapper 输出无法采信
+// （脚本缺失 / 输出非 JSON / jq 缺失的 error JSON），error 字段给出原因。
+// run 可注入供单测（沿用 env.test.js 的依赖注入风格）。
+export async function checkToolDetail(tool, { run } = {}) {
+  const runFn = run || defaultRun;
+  let res;
+  try {
+    res = await runFn(tool);
+  } catch (err) {
+    return { ...baseDetail(tool), error: err.shortMessage || String(err) };
+  }
+  const stdout = String(res.stdout ?? '').trim();
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return {
+      ...baseDetail(tool),
+      error: `wrapper 输出不是合法 JSON（exit ${res.exitCode ?? '?'}）：${stdout.slice(0, 200)}`,
+      raw: stdout,
+    };
+  }
+  if (parsed.error) {
+    return {
+      ...baseDetail(tool),
+      status: parsed.status === 'ok' ? 'ok' : 'unknown',
+      mode: parsed.mode || 'unknown',
+      suppress: Boolean(parsed.suppress),
+      events: parsed.events || {},
+      plugin: parsed.plugin ?? null,
+      registeredPaths: parsed.registeredPaths || [],
+      drift: parsed.drift || null,
+      error: parsed.error,
+      raw: stdout,
+    };
+  }
+  const status = parsed.status === 'ok' ? 'ok' : 'missing';
+  return {
+    ...baseDetail(tool),
+    ok: status === 'ok' && res.exitCode === 0,
+    status,
+    mode: parsed.mode || 'unknown',
+    suppress: Boolean(parsed.suppress),
+    events: parsed.events || {},
+    plugin: parsed.plugin ?? null,
+    registeredPaths: parsed.registeredPaths || [],
+    drift: parsed.drift || null,
+    raw: stdout,
+  };
+}
+
+// 渲染单工具明细为人类可读行。drift 行用 ⚠ 前缀（脚本仍可用，功能未坏，
+// 但指向的安装源不是当前 source——收敛入口在 TUI 侧）。
+export function renderToolDetail(detail) {
+  const lines = [];
+  const modeNote = MODE_LABEL[detail.mode] || detail.mode;
+  if (detail.status === 'ok') {
+    lines.push(`  ${OK} hooks 完整（真源：${modeNote}）`);
+  } else if (detail.status === 'missing') {
+    lines.push(`  ${NO} hooks 缺失或损坏（真源：${modeNote}）`);
+  } else {
+    lines.push(`  ${NO} 无法判定：${detail.error || '未知错误'}`);
+  }
+
+  if (detail.suppress) {
+    lines.push(`  ${WARN} 存在卸载意图标记（suppressed-${detail.tool}）：自动修复已被抑制`);
+  }
+
+  // 逐事件缺失明细（cc-switch/文件模式的 tools）
+  if (detail.status === 'missing') {
+    const broken = [];
+    for (const [ev, e] of Object.entries(detail.events || {})) {
+      if (!e || e.registered === 0) broken.push(`    ${NO} ${ev}：未注册`);
+      else if (e.alive === 0) {
+        broken.push(`    ${NO} ${ev}：脚本不可执行（${(e.scriptPaths || []).join(', ') || '未知路径'}）`);
+      }
+    }
+    if (broken.length > 0) {
+      lines.push('  缺失明细：');
+      lines.push(...broken);
+    }
+  }
+
+  // opencode plugin 明细（无逐事件概念，异常按布尔汇总）
+  if (detail.plugin && detail.status === 'missing') {
+    const pl = detail.plugin;
+    if (!pl.exists) {
+      lines.push(`  ${NO} plugin 文件不存在：${pl.path}`);
+    } else {
+      const marks = [];
+      if (!pl.marker) marks.push('缺本插件标记');
+      if (!pl.hookScriptAlive) marks.push('HOOK_SCRIPT 不可执行');
+      for (const [k, v] of Object.entries(pl.structure || {})) {
+        if (!v) marks.push(`缺结构片段 ${k}`);
+      }
+      if (marks.length > 0) lines.push(`  ${NO} plugin 异常：${marks.join('、')}`);
+    }
+  }
+
+  // 注册路径与漂移
+  if (detail.drift?.drifted) {
+    lines.push(`  ${WARN} 漂移：hooks 指向其他安装源（脚本仍可用，check 仍判完整）`);
+    for (const s of detail.drift.stale || []) lines.push(`      旧路径：${s}`);
+    lines.push(`      当前 source 路径：${detail.drift.expected}`);
+  } else if (detail.status !== 'unknown' && (detail.registeredPaths || []).length > 0) {
+    for (const rp of detail.registeredPaths) lines.push(`  注册路径：${rp}`);
+  }
+
+  return lines;
+}
+
+// 多工具汇总（tmuxclihook check 的 exit code 与 TUI 收敛入口判定用）
+export function summarizeDetails(details) {
+  return {
+    hasMissing: details.some((d) => d.status === 'missing'),
+    hasDrift: details.some((d) => d.drift?.drifted),
+    hasError: details.some((d) => d.status === 'unknown'),
+  };
+}

package/src/esc.js

@@ -0,0 +1,33 @@
+// esc.js — 把 Esc 键转译为合成 ctrl+c
+//
+// clack 0.7 的 Prompt 仅把 \x03（ctrl+c）映射为 cancel（core 的 onKeypress 里
+// 唯一的 cancel 触发是 ch === "\x03"），Esc 默认无任何效果——各子菜单的
+// 「Esc 返回」此前只是文案承诺，从未生效。这里在 stdin 上挂全局 keypress
+// 监听，看到 escape 键就向 stdin 注入合成 \x03，复用 clack 既有且经实测的
+// ctrl+c cancel 路径：主菜单 Esc → isCancel → 退出；子菜单 Esc → isCancel →
+// 返回主菜单；confirm/text Esc → isCancel → 各自的取消分支。
+//
+// spinner 期间不转译（与改动前一致：Esc 静默）。原因：clack 的 block() 给
+// \x03 装了 process.exit(0) 的监听，若在 spinner 期间转译，Esc 会硬退出 TUI
+// 且不恢复 raw mode；ctrl+c 行为不变（仍走该路径，与既有行为一致）。
+
+let spinnerDepth = 0;
+
+export function setSpinnerActive(on) {
+  spinnerDepth += on ? 1 : -1;
+  if (spinnerDepth < 0) spinnerDepth = 0;
+}
+
+// 返回解绑函数（进程退出即回收，正常无需调用；导出以便单测）。
+export function enableEscapeCancel() {
+  const onKeypress = (ch, key) => {
+    if (spinnerDepth === 0 && key?.name === 'escape') {
+      // 直接 emit 合成 keypress（ch='\x03'）：clack 的 onKeypress 以 ch === '\x03'
+      // 判定 cancel，对它来说这与真实 ctrl+c 完全同构。不走 stdin.write——
+      // raw mode（-echo）下向 fd 0 写入不会回环成输入。
+      process.stdin.emit('keypress', '\x03', { name: 'c', ctrl: true, sequence: '\x03' });
+    }
+  };
+  process.stdin.on('keypress', onKeypress);
+  return () => process.stdin.off('keypress', onKeypress);
+}

package/src/hooks.js

@@ -4,13 +4,19 @@ import { existsSync } from 'node:fs';
 import { toolById } from './adapters-meta.js';
 import { hooksInstalledAsync } from './detect.js';
 
-// 安装某工具 hooks（调薄 wrapper install-<tool>-hooks.sh）
-export async function installHooks(id) {
+// 安装某工具 hooks（调薄 wrapper install-<tool>-hooks.sh）。
+// force: 传 TMUX_AI_FORCE_INSTALL=1 旁路 codex/opencode 的 no-op if valid 门禁——
+// 漂移收敛专用（hooks 指向其他安装源但脚本存活时 integrity 恒过，普通 install
+// 永远收敛不了）；codex 重写即 trusted_hash 失效，force 前须由调用方确认代价。
+export async function installHooks(id, { force = false } = {}) {
   const tool = toolById(id);
   if (!tool) return { ok: false, output: `未知工具: ${id}` };
   if (!existsSync(tool.installer)) return { ok: false, output: `找不到安装脚本: ${tool.installer}` };
   try {
-    const { stdout } = await execa('bash', [tool.installer], { timeout: 30000 });
+    const { stdout } = await execa('bash', [tool.installer], {
+      timeout: 30000,
+      env: force ? { TMUX_AI_FORCE_INSTALL: '1' } : undefined,
+    });
     return { ok: true, output: stdout };
   } catch (err) {
     return { ok: false, output: err.stderr || err.shortMessage || String(err) };

package/src/update.js

@@ -1,5 +1,6 @@
-import { readFileSync, accessSync, constants as fsConstants, realpathSync } from 'node:fs';
-import { delimiter, dirname, join } from 'node:path';
+import { readFileSync, accessSync, existsSync, constants as fsConstants, realpathSync } from 'node:fs';
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { execa } from 'execa';
 
 const PACKAGE_NAME = 'tmuxclihook';
@@ -9,12 +10,13 @@ export const CURRENT_VERSION = packageJson.version;
 
 // —— 生效版本自检 ————————————————————————————————————————————————
 //
-// `npm install -g` 在版本管理器（volta 等）环境下不会更新其管理的 shim：
-// volta 的 `~/.volta/bin` shim 指向 packages/ 镜像，而 npm -g 只写 node
-// 工具链目录，两者互不感知（实测 0.3.0 → 0.3.2 升级时用户命令仍解析到
-// 旧版）。生效收敛由 repairWithVolta 无条件完成（见下）；本节自检只是
-// 事后确认：按 update 进程的 PATH 解析一份，尽力读取真实版本并与
-// registry latest 比对，无法确认或版本不符时打警告。
+// `npm install -g` 在版本管理器（volta 等）环境下只写 node 工具链目录，
+// 不更新 volta 的 shim 镜像（shim 指向 packages/）。因此升级前先按 PATH
+// 上第一个可执行 tmuxclihook 判断「当前生效入口」属于哪套安装机制，只走
+// 对应那一套（见 detectInstallSource / updatePackage），避免同一版本被写
+// 成两份、hooks 指向其中一份而 PATH 命中另一份造成漂移。
+// 本节自检只是事后确认：按 update 进程的 PATH 解析一份，尽力读取真实版本
+// 并与 registry latest 比对，无法确认或版本不符时打警告。
 // 验证是尽力而为的提示，不改变 update 的返回值（install 本身已成功）。
 
 function findOnPath(name, env) {
@@ -31,6 +33,200 @@ function findOnPath(name, env) {
   return null;
 }
 
+// realpath 失败时退回字面绝对路径，保证包含判断仍可进行（不抛）。
+function realOrResolved(p) {
+  if (!p) return null;
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+// child 是否位于 parent 目录内（含相等）。用 relative 而非 startsWith，
+// 避免 `$VOLTA_HOME/bin-other` 被误判为 `$VOLTA_HOME/bin` 的子路径。
+function isPathInside(child, parent) {
+  const rel = relative(parent, child);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+const VOLTA_SHIM_NAMES = new Set(['volta-shim', 'volta-shim.exe']);
+
+// 判断 PATH 上第一个可执行的 tmuxclihook 来自哪套安装机制：
+//   'volta'   — $VOLTA_HOME/bin 下的 shim、或 volta packages 镜像
+//   'npm'     — npm 全局 / nvm / fnm 等 node 工具链目录
+//   'unknown' — PATH 上找不到可执行入口
+// 跟随「当前生效入口」是 update 的核心语义：只升级用户实际会执行的那一份。
+export function detectInstallSource(env = process.env) {
+  try {
+    const entry = findOnPath(PACKAGE_NAME, env);
+    if (!entry) return 'unknown';
+
+    const voltaHome = env.VOLTA_HOME || (env.HOME ? join(env.HOME, '.volta') : null);
+    const realEntry = realOrResolved(entry);
+
+    if (voltaHome) {
+      // macOS 的 /var → /private/var 等：原始路径与 canonical 路径都要比对
+      const homes = [voltaHome];
+      const realHome = realOrResolved(voltaHome);
+      if (realHome && realHome !== voltaHome) homes.push(realHome);
+
+      for (const home of homes) {
+        const binDir = join(home, 'bin');
+        const pkgDir = join(home, 'tools', 'image', 'packages', PACKAGE_NAME);
+        for (const candidate of [entry, realEntry]) {
+          if (!candidate) continue;
+          if (isPathInside(candidate, binDir) || isPathInside(candidate, pkgDir)) return 'volta';
+        }
+      }
+    }
+
+    if (realEntry && VOLTA_SHIM_NAMES.has(basename(realEntry))) return 'volta';
+    return 'npm';
+  } catch {
+    return 'unknown';
+  }
+}
+
+// —— 非生效副本检测与可选收敛 ——————————————————————————————————————
+//
+// update 只升级生效入口，不主动动另一套安装。历史遗留的双份副本会让后续
+// 手动交叉升级「升级到不生效的那份」，因此提供可选收敛：只删同时满足以下
+// 条件的副本——不是生效入口、未被 hooks 引用、未被 ~/.tmux.conf 引用、
+// 位于已知标准位置。TTY 下交互确认（默认 No）；--prune 跳过确认；
+// 非交互环境只警告，绝不静默删除。
+
+const TOOL_IDS = ['claude', 'codex', 'opencode'];
+
+function voltaPackagesRoot(env) {
+  const voltaHome = env.VOLTA_HOME || (env.HOME ? join(env.HOME, '.volta') : null);
+  return voltaHome ? join(voltaHome, 'tools', 'image', 'packages', PACKAGE_NAME) : null;
+}
+
+async function readNpmGlobalPrefix(run) {
+  try {
+    const r = await run('npm', ['prefix', '-g']);
+    return (r.stdout || '').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// 返回「非生效 + 位于标准位置」的副本。source 为 unknown 时不做任何
+// 检测——找不到生效入口时删除任何一份都可能让用户彻底没有命令。
+export async function detectStaleInstalls(source, env = process.env, run = execa) {
+  if (source === 'unknown') return [];
+
+  const stale = [];
+  if (source === 'npm') {
+    const voltaRoot = voltaPackagesRoot(env);
+    if (voltaRoot && existsSync(voltaRoot)) stale.push({ kind: 'volta', root: voltaRoot });
+  }
+  if (source === 'volta') {
+    const prefix = await readNpmGlobalPrefix(run);
+    const npmRoot = prefix ? join(prefix, 'lib', 'node_modules', PACKAGE_NAME) : null;
+    if (npmRoot && existsSync(npmRoot)) stale.push({ kind: 'npm', root: npmRoot });
+  }
+  return stale;
+}
+
+// hooks 是否引用该副本。走三个 wrapper 的 check --json（与 TUI 同源），
+// 输出里出现目标路径即视为引用。任何异常都按「有引用」处理，宁可不动。
+async function hooksReference(root, env, run) {
+  const scriptsDir = fileURLToPath(new URL('../scripts/', import.meta.url));
+  for (const tool of TOOL_IDS) {
+    const script = join(scriptsDir, `install-${tool}-hooks.sh`);
+    if (!existsSync(script)) continue;
+    try {
+      const r = await run('bash', [script, 'check', '--json'], { env });
+      if ((r.stdout || '').includes(root)) return tool;
+    } catch (err) {
+      if ((err.stdout || '').includes(root)) return tool;
+      return tool;
+    }
+  }
+  return null;
+}
+
+function tmuxConfReferences(root, env) {
+  if (!env.HOME) return true;
+  try {
+    return readFileSync(join(env.HOME, '.tmux.conf'), 'utf8').includes(root);
+  } catch {
+    return false;
+  }
+}
+
+async function uninstallStale(item, run) {
+  try {
+    if (item.kind === 'volta') {
+      await run('volta', ['uninstall', PACKAGE_NAME], { stdio: 'inherit' });
+    } else {
+      await run('npm', ['uninstall', '-g', PACKAGE_NAME], { stdio: 'inherit' });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// 交互确认的默认实现：读一行，默认 No。测试通过 options.confirm 注入。
+async function defaultConfirm(question) {
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`${question} [y/N] `);
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+// 清理非生效副本。返回是否实际删除过任何副本。
+export async function cleanupStale(options) {
+  const {
+    source, env, run, log, prune, isTTY, confirm, checkHooks, checkTmuxConf,
+  } = options;
+
+  const stale = await options.detectStale(source, env, run);
+  if (stale.length === 0) return false;
+
+  let removed = false;
+  for (const item of stale) {
+    const label = `${item.kind} install at ${item.root}`;
+
+    const hookTool = await checkHooks(item.root, env, run);
+    if (hookTool) {
+      log.error(`Not removing ${label}: still referenced by ${hookTool} hooks. Reinstall hooks from the effective entry first.`);
+      continue;
+    }
+    if (checkTmuxConf(item.root, env)) {
+      log.error(`Not removing ${label}: still referenced by ~/.tmux.conf.`);
+      continue;
+    }
+
+    if (!prune) {
+      if (!isTTY) {
+        log.error(`Another install found: ${label}. Run "tmuxclihook update --prune" in a terminal to remove it.`);
+        continue;
+      }
+      const yes = await confirm(`Remove the non-effective ${label}?`);
+      if (!yes) {
+        log.log(`Keeping ${label}.`);
+        continue;
+      }
+    }
+
+    if (await uninstallStale(item, run)) {
+      log.log(`Removed ${label}.`);
+      removed = true;
+    } else {
+      log.error(`Failed to remove ${label}.`);
+    }
+  }
+  return removed;
+}
+
 // npm 布局下入口是 .../lib/node_modules/<pkg>/bin/cli.js（或其 symlink）：
 // realpath 后向上最多 3 层找 name 匹配的 package.json 读版本。版本管理器
 // shim 是独立二进制，向上找不到包 → 返回 null。
@@ -94,14 +290,11 @@ function warnNotEffective(log, result) {
   log.error(`If you use volta, run: volta install ${PACKAGE_NAME}@latest`);
 }
 
-// volta 生效修正：`npm install -g` 只写 node 工具链目录，不更新 volta 的
-// shim 镜像（实测 volta 2.0.2：shim npm 的全局 prefix 就是工具链目录），
-// 用户的命令经 ~/.volta/bin shim 解析时仍是旧版。因此只要检测到 volta
-// 就无条件补一次 volta install 完成生效（幂等，已是最新时秒回）。不走
-// 「自检失败才修」的条件路径：自检按 update 进程自己的 PATH 找第一份，
-// 可能恰好命中 npm -g 刚写的那份而误判 ok（实测 0.3.3 → 0.3.4：verify
-// 判 ok，修复从未触发，用户命令仍是旧版）。npm install -g 是安装语义，
-// volta install 是生效语义，两者都执行；用户无需改变安装习惯。
+// volta 安装路径：当 PATH 上的生效入口来自 volta（shim 或 packages 镜像）
+// 时，升级只能走 `volta install`——`npm install -g` 只写 node 工具链目录，
+// 不会更新 volta 的 packages 镜像。此函数现在是 volta 分支的唯一升级动作，
+// 不再作为 npm 安装后的无条件补丁（双写会制造两份副本并引发漂移）。
+// volta 不可执行时返回 false，由调用方决定如何报告。
 export async function repairWithVolta(run, log, env = process.env) {
   const voltaHome = env.VOLTA_HOME || join(env.HOME || '', '.volta');
   const voltaBin = findOnPath('volta', env) || join(voltaHome, 'bin', 'volta');
@@ -124,9 +317,21 @@ export async function updatePackage(options = {}) {
   const run = options.run || execa;
   const log = options.log || console;
   const currentVersion = options.currentVersion || CURRENT_VERSION;
+  const env = options.env || process.env;
   // 显式传 null 跳过自检/修正（测试用）；默认真实现
   const verify = options.verify === undefined ? verifyEffectiveVersion : options.verify;
   const repairVolta = options.repairVolta === undefined ? repairWithVolta : options.repairVolta;
+  const detectSource = options.detectSource === undefined ? detectInstallSource : options.detectSource;
+  // 非生效副本收敛：默认开启，TTY 下交互确认；--prune 跳过确认。
+  const cleanup = options.cleanup !== false;
+  const prune = options.prune === true;
+  const isTTY = options.isTTY === undefined
+    ? Boolean(process.stdin.isTTY && process.stdout.isTTY)
+    : options.isTTY;
+  const confirm = options.confirm || defaultConfirm;
+  const detectStale = options.detectStale || detectStaleInstalls;
+  const checkHooks = options.checkHooks || hooksReference;
+  const checkTmuxConf = options.checkTmuxConf || tmuxConfReferences;
 
   log.log(`Current version: v${currentVersion}`);
 
@@ -145,28 +350,61 @@ export async function updatePackage(options = {}) {
   }
 
   log.log(`Updating to v${latestVersion}...`);
-  try {
-    await run('npm', ['install', '-g', `${PACKAGE_NAME}@latest`], { stdio: 'inherit' });
-  } catch {
-    return false;
+
+  // 跟随当前生效入口：PATH 上第一个 tmuxclihook 属于哪套机制，就只升级那套。
+  // volta 入口走 volta install（npm -g 写不到 packages 镜像）；其余入口走 npm -g。
+  // 不再双写——那会留下两份同版本副本，配置指向一份而命令执行另一份即产生漂移。
+  const source = typeof detectSource === 'function' ? detectSource(env) : 'unknown';
+
+  if (source === 'volta') {
+    if (repairVolta) {
+      const ok = await repairVolta(run, log, env);
+      if (!ok) {
+        log.error('Failed to update via volta. Please check your volta installation.');
+        return false;
+      }
+    }
+  } else {
+    try {
+      await run('npm', ['install', '-g', `${PACKAGE_NAME}@latest`], { stdio: 'inherit' });
+    } catch {
+      return false;
+    }
   }
 
   log.log(`Done. Updated to v${latestVersion}`);
 
-  // 生效收敛：有 volta 就无条件跑（幂等；无 volta 时静默跳过，纯 npm 场景
-  // npm -g 本身已生效）。任何命令行执行 update 都能升级生效的关键。
-  if (repairVolta) {
-    await repairVolta(run, log);
+  if (!verify) return true;
+
+  // 事后确认（尽力而为）：正常情况下生效入口应已是新版。
+  let result = await verify(latestVersion, env);
+
+  // 兜底：非 volta 来源、自检未过、且本机确有 volta 时补一次并复检。
+  // 仅在异常场景触发（例如 npm 全局 bin 不在 PATH），保持「不双写」语义。
+  if (result.status !== 'ok' && source !== 'volta' && repairVolta) {
+    const repaired = await repairVolta(run, log, env);
+    if (repaired) result = await verify(latestVersion, env);
   }
 
-  if (verify) {
-    // 事后确认（尽力而为）：两处落点都应已是新版，命中哪份都该 ok；
-    // 不 ok（如 PATH 上另有第三份旧安装）只警告，不影响返回值。
-    const result = await verify(latestVersion);
-    if (result.status === 'ok') {
-      log.log(`Verified: tmuxclihook on your PATH now resolves to v${latestVersion}.`);
-    } else {
-      warnNotEffective(log, result);
+  if (result.status === 'ok') {
+    log.log(`Verified: tmuxclihook on your PATH now resolves to v${latestVersion}.`);
+  } else {
+    warnNotEffective(log, result);
+  }
+
+  // 升级已确认成功后再收敛历史副本；清理失败不影响升级结果，也不改变退出码。
+  if (cleanup && result.status === 'ok') {
+    try {
+      const removed = await cleanupStale({
+        source, env, run, log, prune, isTTY, confirm, checkHooks, checkTmuxConf, detectStale,
+      });
+      // 删过东西就再确认一次生效入口，避免误删导致命令不可用。
+      if (removed && verify) {
+        const after = await verify(latestVersion, env);
+        if (after.status !== 'ok') warnNotEffective(log, after);
+      }
+    } catch (err) {
+      log.error(`Cleanup skipped: ${err}`);
     }
   }