@minonl/dia 0.0.8 → 0.0.10

package/docs/msg-collab-m1.md

@@ -64,3 +64,32 @@ dia graph --json --task t-xxx
 - `blocked_by` 只在 task 节点里做派生提示，不是边；
 - 任务依赖成环：`cycles` 非空，退出码 **3**（参数错仍是 2）；
 - `--task` 只输出该任务的直接依赖/touches/claim 邻居，不做全图闭包。
+
+---
+
+# 只读 TUI 图（M2 第一步）
+
+```bash
+dia graph --tui                 # 打印一次（有环 exit 3）
+dia graph --watch               # 每 2s 刷新，Ctrl-C 退出
+dia graph --tui --no-color      # 关 ANSI 颜色
+```
+
+- 按状态分组显示 task → deps / touches / blocked_by；claims 单列；
+- 不启 HTTP/daemon，遵守框架“无网络模块”约束；
+- `--task t-...` 只显示该任务的直接邻居。
+
+---
+
+# handoff + claim 联动（M2）
+
+```bash
+dia claim src/collab.ts --reason "正在重构"
+dia out --to ses_xxx --kind handoff --subject "交接" --body-file handoff.md \
+        --touches src/collab.ts,docs/msg-collab-m1.md
+```
+
+- `--touches a,b`（也接受重复 `--touch`）写入消息 `refs.touches`；
+- 发送时如果有他人活跃 claim，输出 `⚠ claim overlap`（advisory，仍发送）；
+- 收件方 `dia in` 会在消息下显示 `⚠ claim: <path> 由 <holder> 持有`；
+- 不自动排队/阻断；claim 仍是可见性工具。

package/docs/overview.md

@@ -85,6 +85,12 @@ $ dia --persona yan kb scene S1  → 正常出场景卡
 
 ---
 
+## 3.1 CI 口径（见 README「CI 矩阵」）
+
+- required = `test (ubuntu-latest)` + `test (macos-latest)`（分支保护，`enforce_admins`）
+- `windows-smoke` 非阻塞：Windows 后端未实现（`dia job install` rc=3），落地后再升 required
+- **docs-only 快通道**：只改 `docs/**` / 根 `*.md` / `llms*.txt` 时跳过测试矩阵
+
 ## 4. 已知缺口（按优先级）
 
 1. **yan 安装落后来源仓 1 个提交**（`83fbaa9` vs `8d10cc5`，内容是 dsh profile 根 `cordis.yml` 修复）。

package/docs/service-noun.md

@@ -1,8 +1,11 @@
 # 服务（service）：可托管的执行体
 
-> 状态：提案（设计，未实现）。只做脚本型服务；healthcheck 按专用退出码域判定，旧结果超新鲜度窗口即报 stale。
+> 状态：**已实现（v0.0.10，脚本型 + agent 型）**。脚本型走 `entry.cmd`，agent 型走 `entry.agent` + `healthcheck.kind="acp"`；
+> healthcheck 按专用码域 `0/20/21` 判定（外加 `124`=timeout、信号=crash），旧结果超新鲜度窗口即报 `unknown (stale …)`。
+> **实现状态逐节对照见 §15。**
 > 日期 2026-11-05（rev.2：按 [设计评审 B1–B5 / C1–C7 / D1–D4](review/service-noun-review-2026-11-05.md) 改稿；
-> **rev.3**：按复核意见改「去抖单一写入方 / health 码域 `0/20/21` / timeout 映射 / 手动检查落台账 / adopted 口径」，见 §13）。
+> **rev.3**：按复核意见改「去抖单一写入方 / health 码域 `0/20/21` / timeout 映射 / 手动检查落台账 / adopted 口径」，见 §13；
+> **rev.4**：回填实现状态（PR #49 / #54 / #60）与 §15 对照表）。
 > 关联：[`cli.md`](cli.md)（名词与动词矩阵 / 退出码）· [`persona-install.md`](persona-install.md)（`dia.json` schema）·
 > [`kit-install.md`](kit-install.md) · [`acp-integration.md`](acp-integration.md)（agent 会话型服务）· `packages/job`（生命周期、状态台账）
 
@@ -243,9 +246,11 @@ unknown（stale）**不单独返回**——`health` 是实时执行，不存在
 
 - `job` 仍是**唯一调度实现**（不新增第二套）；健康检查任务本身就是一个 `job`（`periodic`）。
 - `service` 只多一层「声明 + 校验 + 健康检查」。
-- `dia job status` 的每行增加 `health=<ok|degraded|fail|unknown|n/a> (Ns ago)`（读 §4.5 缓存，不执行）。
+- `dia job status` 的每行增加 `health=<ok|degraded|fail|unknown|n/a> (Ns ago)`（读 §4.5 缓存，不执行）。**✅ 已实现（PR #54）**：
+  仅对 `local.dia-job-svc-<id>` 行追加，其它行原样（向后兼容）。
 - 对 `service` 型（常驻）任务：Linux 走 systemd `--user`，**常驻需 `loginctl enable-linger`**（`job doctor` 已提示，`dia service add` 一并转述）；
   对 `periodic` 任务，cron 后端**没有进程状态**，health 是唯一判据 → 新鲜度条款（§4.6）尤其关键。
+- **性能**：只读台账、零执行；实测 N=50 时 `3.1ms`（阈值 200ms），基准见 `tests/service-health-status.perf.test.ts`。
 
 ## 7. 边界与异常
 
@@ -352,3 +357,108 @@ unknown（stale）**不单独返回**——`health` 是实时执行，不存在
 
 1. 判据写成**可判定的检查**：`node scripts/docs-index.mjs --check && node scripts/docs-link-check.mjs`（+ 可选 checklist 计数）；
 2. 或者把它当**评审工具**用：接受 `escalated` 是预期结果，只取 `verify.json` 的 findings 作为 grill 产出。
+
+## 14. P2：agent 型服务（entry = persona 会话）
+
+> 状态：**已实现（PR #60）**。本节定义脚本型之外的 agent 型入口（`entry.agent` + `healthcheck.kind="acp"`）；
+> 实现与本节一致，差异见 §15。
+
+### 14.1 与脚本型的关系
+
+```mermaid
+flowchart LR
+  S["service"] --> A["脚本型（已实现）<br/>entry = bin/*"]
+  S --> B["agent 型（P2）<br/>entry = ACP 会话"]
+  B --> J["job：把 ACP 端点拉起并保持<br/>(dsh --profile dia-acp / opencode acp)"]
+  B --> H["healthcheck：端点可应答 + 最近一轮成功<br/>(不判断“想得对不对”)"]
+```
+
+**不变的**：`lifecycle`（job 托管）、`healthcheck` 契约（专用码域）、台账（`kind:"health"`）、`gen` 代际。
+**不同的**：没有 `stdin` 事件契约 —— 输入是 ACP 的 `prompt`，输出是会话事件；所以 `contract` 换成 ACP 语义。
+
+### 14.2 清单
+
+```jsonc
+{
+  "kind": "service",
+  "id": "example-agent",
+  "entry": {
+    "agent": {
+      "host": "dsh",                 // dsh | opencode
+      "profile": "dia-acp",          // 由 persona/宿主提供；缺省用宿主默认
+      "persona": "yan"               // 可选：仅做归属校验，不注入内容
+    }
+  },
+  "lifecycle": { "type": "service", "target": "local" },
+  "healthcheck": { "kind": "acp", "interval": 1800, "timeout": 60 },
+  "kits": []
+}
+```
+
+| 字段 | 语义 |
+|---|---|
+| `entry.agent.host` | 用哪套 ACP 实现（`dsh --profile <p>` 或 `opencode acp`） |
+| `entry.agent.profile` | 宿主的 profile 名（不复制 persona 内容，只引用） |
+| `entry.agent.persona` | 可选；`verify` 时校验「该 profile 是否属于此 persona」，防止挂错人 |
+| `healthcheck.kind: "acp"` | 走 ACP 健康检查（见 §14.3），**不再要求 `cmd`** |
+
+### 14.3 健康检查（ACP 版）
+
+| 检查 | 判据 | 失败归类 |
+|---|---|---|
+| 端点存活 | `initialize` 能返回 `protocolVersion`（JSON-RPC 1.0） | 连不上/超时 → `degraded` |
+| 会话可用 | `session/new` 成功返回 `sessionId` | 返回错误 → `fail` |
+| 最近一轮 | 台账里最近一次 `prompt` 的成功/失败（由调用方写事件） | 连续失败 `debounce` 次 → `degraded` |
+
+**明确不做**：不判断「回答质量」、不重放 prompt、不在 healthcheck 里跑真实业务（成本 + 副作用）。
+
+### 14.4 与脚本型的复用
+
+- `healthView` / `transition` / `gen` / 台账格式**完全复用**（`state.jsonl` + `kind:"health"`）
+- 差异只在「怎么产生一次 judgement」：`runHealth()` 换成 `runAcpHealth()`（`initialize` + `session/new`）
+- `dia service health <id>` 对 agent 型走 `runAcpHealth`，退出码沿用 §5
+
+### 14.5 边界
+
+| 场景 | 行为 |
+|---|---|
+| 宿主未安装 / profile 不存在 | `add` 期 `E_BACKEND`（不装半套） |
+| 端点活着但 `session/new` 失败 | `fail`（配置/鉴权问题，不是 infra 抖动） |
+| 长任务（一轮 prompt 很久） | **不算失败**；只有「端点不可应答」才算 |
+| 多实例 | `lifecycle.target` 声明归属；ACP 端点同机只允许一个 |
+| 权限/凭据 | 由宿主 profile 自己管；`dia` 不读取、不注入 |
+
+### 14.6 验收（P2）
+
+- [ ] 单测：清单校验（`entry.agent` 与 `entry.cmd` **互斥**，同时给 → `E_MANIFEST`）
+- [ ] 单测：`runAcpHealth` 用 `tests/fixtures/fake-acp.mjs` 覆盖 `initialize` 失败 / `session/new` 失败 / 正常三态
+- [ ] 单测：`healthcheck.kind` 缺省时按脚本型（向后兼容）
+- [ ] e2e：装一个 agent 型 demo（fake ACP）→ `dia job status` 显示 `health=ok…`，杀掉端点后变 `degraded(stale)`
+
+## 15. 实现状态（2026-11-06 回填）
+
+> 规则：**设计先改、代码同批**（R35）。本节是「设计 ↔ 实现」的对照表；后续改动必须同批更新本表。
+
+| 设计小节 | 状态 | 实现落点 |
+|---|---|---|
+| §2 构成（entry/lifecycle/contract/healthcheck） | ✅ | `src/service.ts`：`ServiceManifest` / `validateServiceManifest`（PR #49） |
+| §3 清单与校验（entry 规则、`E_MANIFEST`） | ✅ | `checkEntry` / `checkAgentEntry` / `resolveEntry`（#49、#60） |
+| §4.1 码域 `0/20/21` + `124` + 信号 | ✅ | `judgeHealth` / `judgeSpawnResult`；`124` 与 `137/143` 分流（#49；无 `timeout(1)` 的兜底见 #49 后续修复 `29a4341`） |
+| §4.2 执行环境 / `E_BACKEND` | ✅ | `healthShell`、`checkCronInterval`（#49） |
+| §4.3 去抖 + 单一写入方 + `gen` | ✅ | `transition`（`gen` 不同的行不计数）（#49） |
+| §4.4 崩溃语义（保持上次状态 + `last_error`） | ✅ | `judgeSpawnResult` + `transition`（#49） |
+| §4.5 台账（`state.jsonl` + `kind:"health"`） | ✅ | `appendHealthRecord` / `findLastHealth` / `readHealthLines`（#49、#54） |
+| §4.6 新鲜度（`interval × 1.5` → stale） | ✅ | `healthView` / `staleAfter`（#54） |
+| §5 CLI（add/remove/list/show/verify/health） | ✅ | `packages/cli/src/index.ts`（#49）；`health` 的 agent 分支（#60） |
+| §6 `dia job status` 追列 health | ✅ | `decorateStatus` + `runJobCapture`（#54） |
+| §7 边界（`E_UNSTABLE_ENTRY` / adopted / three-state） | ✅ | `verify` / `healthView`（#49、#54） |
+| §14 agent 型（`entry.agent` + `kind:"acp"`） | ✅ | `acpAgentCommand` / `runAcpHealth` / `recordHealth`（#60） |
+| §6 性能基准（N=50 ≤200ms） | ✅ | 实测 **3.1ms**（单服务 0.1ms，macOS / bun 1.4.4）；`tests/service-health-status.perf.test.ts` 断言 ≤200ms 且不随 N 线性增长 |
+
+### 15.1 已知与设计的偏差
+
+| 项 | 设计 | 实现 | 处置 |
+|---|---|---|---|
+| `healthcheck.kind` 缺省 | 未写 | 缺省 `script`（向后兼容） | 与 §14.6 一致，已写回 §14 |
+| `dia service health` 的 agent 分支 | §5 未细化 | 先跑 ACP 探测再落 `source:"manual"` 行 | 与 §5/§14 语义一致，无需改设计 |
+| `entry.agent` 与 `healthcheck.kind` 的强绑定 | §14.6 验收项 | 已实现为 `E_MANIFEST`（agent 型必须 acp；acp 只能配 agent 型） | 已写回 §14.2 校验说明 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minonl/dia",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "type": "module",
   "description": "dia (嗲) — lightweight agent framework: knowledge index, audit, session ingest",
   "bin": {

package/packages/wt/bin/dia-wt

@@ -1167,22 +1167,31 @@ wt_default_branch() {
   printf '%s' "$b"
 }
 
-wt_write_hook() {
-  local hooksdir="$1" name="$2" extra="${3:-}" chain="${4:-}"
-  cat > "$hooksdir/$name" <<'HOOK'
-#!/usr/bin/env bash
-# dia-wt guard（managed by `dia wt adopt`；勿手改）
+wt_guard_body() {
+  cat <<'HOOKBODY'
 set -uo pipefail
-name="$(basename "$0")"
+# 钩子名：生成的钩子用 basename $0；`dia wt guard` 用环境变量指定
+name="${DIA_WT_HOOK_NAME:-$(basename "$0")}"
 top="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
 common="$(git rev-parse --git-common-dir 2>/dev/null || true)"
-case "$common" in /*) ;; *) common="$(cd "$top" && cd "$common" 2>/dev/null && pwd -P)" ;; esac
+case "$common" in /*) ;; *) common="$(cd "$top" 2>/dev/null && cd "$common" 2>/dev/null && pwd -P)" ;; esac
+[ -n "$common" ] || exit 0
 gd="$(git rev-parse --git-dir 2>/dev/null || true)"
-case "$gd" in /*) ;; *) gd="$(cd "$top" && cd "$gd" 2>/dev/null && pwd -P)" ;; esac
+case "$gd" in /*) ;; *) gd="$(cd "$top" 2>/dev/null && cd "$gd" 2>/dev/null && pwd -P)" ;; esac
 is_main=0; [ "$gd" = "$common" ] && is_main=1
 branch="$(git symbolic-ref --short HEAD 2>/dev/null || true)"
-prot=" main master develop dev "
 probe="${DIA_WT_GUARD_PROBE:-0}"
+
+# 只对已 adopt 的仓生效；未 adopt → 纯透传（保持本机其它仓行为不变）
+cfg="$common/dia/config.json"
+adopted=0; [ -f "$cfg" ] && adopted=1
+def=""
+if [ "$adopted" = 1 ]; then
+  def="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("defaultBranch") or "")' "$cfg" 2>/dev/null || true)"
+fi
+prot=" main master develop dev $def "
+prot="${prot//  / }"
+
 wt_guard_scan() {
 local ls="$1" rs="$2" range="" base="" hits=""
 if [ -n "$rs" ] && [ "$rs" != "0000000000000000000000000000000000000000" ] && git cat-file -e "$rs" 2>/dev/null; then
@@ -1197,74 +1206,100 @@ hits="$(git diff -U0 "$range" -- . 2>/dev/null | grep -E '^\+' | grep -vE '^\+\+
 if [ -n "$hits" ]; then
   echo "[dia-wt] 推送包含敏感内容（已阻断）：" >&2
   printf '%s\n' "$hits" >&2
-  echo "[dia-wt] 误报请修扫描规则（hooks 由 dia wt adopt 生成），不提供关闭开关" >&2
+  echo "[dia-wt] 误报请修扫描规则（hooks 由 dia wt adopt 安装），不提供关闭开关" >&2
   return 1
 fi
 }
 
-case "$name" in
-  pre-commit)
-    if [ "$probe" = 1 ]; then
-      { [ "$is_main" = 1 ] && [[ "$prot" == *" $branch "* ]]; } && exit 1 || exit 0
-    fi
-    if [ "$is_main" = 1 ] && [[ "$prot" == *" $branch "* ]]; then
-      echo "[dia-wt] 主 checkout 禁止在 $branch 直接提交；请先：dia wt create <repo> <feature>" >&2
-      exit 1
-    fi ;;
-  pre-push)
-    if [ "$probe" = 1 ]; then
-      [ "$is_main" = 1 ] && exit 1 || exit 0
-    fi
-    if [ "$is_main" = 1 ]; then
-      echo "[dia-wt] 主 checkout 禁止直接 push；请走 worktree 分支 + MR" >&2
-      exit 1
-    fi
-    while read -r _lr ls rr rs; do
-      case "${rr:-}" in
-        refs/heads/main|refs/heads/master|refs/heads/develop|refs/heads/dev)
-          echo "[dia-wt] 禁止直接 push ${rr#refs/heads/}；请走 MR" >&2; exit 1 ;;
-      esac
-      wt_guard_scan "$ls" "$rs" || exit 1
-    done ;;
-  post-checkout)
-    [ "$probe" = 1 ] && exit 0
-    if [ "$is_main" = 1 ] && [[ "$prot" != *" $branch "* ]]; then
-      echo "[dia-wt] 提示：主 checkout 当前在 $branch（建议回到默认分支）" >&2
-    fi ;;
-esac
-# 钩子链：原 hooksPath（husky / .githooks / simple-git-hooks）优先，其次仓库默认 hooks 目录
-chain="${DIA_WT_CHAIN_DIR:-}"
-case "$chain" in
-  "") ;;
-  /*) ;;
-  *) chain="$top/$chain" ;;
-esac
-if [ -n "$chain" ] && [ -x "$chain/$name" ] && [ "$chain/$name" != "$0" ]; then exec "$chain/$name" "$@"; fi
+if [ "$probe" = 1 ]; then
+  case "$name" in
+    pre-commit) { [ "$adopted" = 1 ] && [ "$is_main" = 1 ] && [[ "$prot" == *" $branch "* ]]; } && exit 1 || exit 0 ;;
+    pre-push)   { [ "$adopted" = 1 ] && [ "$is_main" = 1 ]; } && exit 1 || exit 0 ;;
+    *) exit 0 ;;
+  esac
+fi
+
+if [ "$adopted" = 1 ]; then
+  case "$name" in
+    pre-commit)
+      if [ "$is_main" = 1 ] && [[ "$prot" == *" $branch "* ]]; then
+        echo "[dia-wt] 主 checkout 禁止在 $branch 直接提交；请先：dia wt create <repo> <feature>" >&2
+        exit 1
+      fi ;;
+    pre-push)
+      if [ "$is_main" = 1 ]; then
+        echo "[dia-wt] 主 checkout 禁止直接 push；请走 worktree 分支 + MR" >&2
+        exit 1
+      fi
+      # 先把 stdin 全读进来：既要逐条判 ref / 扫敏感内容，也要原样喂给仓库自己的钩子
+      push_lines=()
+      while IFS= read -r line; do push_lines+=("$line"); done
+      for line in "${push_lines[@]}"; do
+        read -r _lr ls rr rs <<<"$line"
+        case "${rr:-}" in
+          refs/heads/main|refs/heads/master|refs/heads/develop|refs/heads/dev)
+            echo "[dia-wt] 禁止直接 push ${rr#refs/heads/}；请走 MR" >&2; exit 1 ;;
+        esac
+        [ -n "${ls:-}" ] || continue
+        wt_guard_scan "$ls" "${rs:-}" || exit 1
+      done ;;
+    post-checkout)
+      if [ "$is_main" = 1 ] && [[ "$prot" != *" $branch "* ]]; then
+        echo "[dia-wt] 提示：主 checkout 当前在 $branch（建议回到默认分支）" >&2
+      fi ;;
+  esac
+fi
+
+# 链式：仓库自己的钩子（simple-git-hooks 等管理器生成在 <common>/hooks）
 orig="$common/hooks/$name"
-if [ -x "$orig" ] && [ "$orig" != "$0" ]; then exec "$orig" "$@"; fi
+if [ -x "$orig" ] && [ "$orig" != "$0" ]; then
+  if [ "$name" = "pre-push" ] && [ ${#push_lines[@]} -gt 0 ]; then
+    printf '%s\n' "${push_lines[@]}" | "$orig" "$@"
+    exit $?
+  fi
+  exec "$orig" "$@"
+fi
 exit 0
-HOOK
+HOOKBODY
+}
+
+# simple-git-hooks RC 注入目录（跟随 dia 数据根）
+wt_hooks_rc_dir() { printf '%s/hooks' "${DIA_ROOT:-${DIA_DATA_DIR:-$HOME/.dia}}"; }
+# 在 ~/.zshenv 里确保 export KEY=VALUE（幂等；带 marker 便于移除）
+wt_ensure_env_export() {
+  local key="$1" val="$2" rc="${DIA_WT_SHELL_RC:-$HOME/.zshenv}"
+  local marker="# dia-wt: $key"
+  [ -f "$rc" ] || : > "$rc"
+  grep -q "^$marker" "$rc" 2>/dev/null && return 0
+  printf '\n%s\nexport %s="%s"\n' "$marker" "$key" "$val" >> "$rc"
+}
+wt_write_hook() {
+  local hooksdir="$1" name="$2" extra="${3:-}" chain="${4:-}"
+  {
+    printf '#!/usr/bin/env bash\n# dia-wt guard（managed by `dia wt adopt`；勿手改）\n'
+    wt_guard_body
+  } > "$hooksdir/$name"
   if [ -n "$chain" ]; then
     python3 - "$hooksdir/$name" "$chain" <<'PYCHAIN'
 import sys
 p, chain = sys.argv[1], sys.argv[2]
 s = open(p).read()
-s = s.replace('chain="${DIA_WT_CHAIN_DIR:-}"', 'chain="${DIA_WT_CHAIN_DIR:-%s}"' % chain.replace('\\', '\\\\').replace('"', '\\"'))
+s = s.replace('orig="$common/hooks/$name"', 'orig="%s/$name"' % chain.replace('\\', '\\\\').replace('"', '\\"'))
 open(p, "w").write(s)
 PYCHAIN
-  fi
-  if [ -n "$extra" ]; then
-    python3 - "$hooksdir/$name" "$extra" <<'PYGT'
-import sys, re
-p, extra = sys.argv[1], sys.argv[2]
-s = open(p).read()
-s = re.sub(r'^prot=" main master develop dev "$', f'prot=" main master develop dev {extra} "', s, flags=re.M)
-open(p, "w").write(s)
-PYGT
   fi
   chmod +x "$hooksdir/$name"
 }
 
+cmd_guard() {
+  local name="${1:-}"
+  case "$name" in
+    pre-commit|pre-push|post-checkout) ;;
+    *) echo "usage: dia wt guard <pre-commit|pre-push|post-checkout>" >&2; return 2 ;;
+  esac
+  DIA_WT_HOOK_NAME="$name" eval "$(wt_guard_body)"
+}
+
 cmd_adopt() {
   local repo="" mode="dry" template="" def="" json=0 all=0
   local -a orig=("$@")
@@ -1305,19 +1340,20 @@ cmd_adopt() {
   local common cfgdir cfg hooksdir prev
   common="$(wt_common_dir "$repo")" || die "无法解析 git-common-dir"
   cfgdir="$common/dia"; cfg="$cfgdir/config.json"; hooksdir="$cfgdir/hooks"
-  prev="$(git -C "$repo" config --get core.hooksPath 2>/dev/null || true)"
+  prev="$(git -C "$repo" config --local --get core.hooksPath 2>/dev/null || true)"
   [ -n "$template" ] || template='{{parent}}/{{repo}}-worktree--{{feature}}'
   [ -n "$def" ] || def="$(wt_default_branch "$repo")"
 
   if [ "$mode" = "revert" ]; then
     [ -f "$cfg" ] || die "未 adopt（缺 $cfg）"
-    local saved
-    saved="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("hooksPrevious") or "")' "$cfg")"
-    if [ "$prev" != "$hooksdir" ]; then
-      echo "[dia-wt] hooksPath 已被改动（$prev），跳过还原并保留 $cfgdir 备份" >&2
-      return 1
+    local saved mgr
+    saved="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("hooksPrevious") or "")' "$cfg" 2>/dev/null || true)"
+    mgr="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("hooksManager") or "")' "$cfg" 2>/dev/null || true)"
+    if [ "$mgr" = "local" ] || [ -z "$mgr" ]; then
+      if [ "$prev" = "$hooksdir" ]; then
+        if [ -n "$saved" ]; then git -C "$repo" config --local core.hooksPath "$saved"; else git -C "$repo" config --local --unset core.hooksPath 2>/dev/null || true; fi
+      fi
     fi
-    if [ -n "$saved" ]; then git -C "$repo" config --local core.hooksPath "$saved"; else git -C "$repo" config --local --unset core.hooksPath 2>/dev/null || true; fi
     rm -rf "$cfgdir"
     echo "reverted：$cfgdir"
     return 0
@@ -1331,16 +1367,28 @@ cmd_adopt() {
       local cfgDef; cfgDef="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("defaultBranch") or "")' "$cfg" 2>/dev/null || true)"
       [ -n "$cfgDef" ] && def="$cfgDef"
     fi
-    case "$prev" in /*) ;; *) echo "FAIL D02 core.hooksPath 不是绝对路径（$prev）"; bad=1 ;; esac
-    for h in pre-commit pre-push post-checkout; do
-      [ -x "$hooksdir/$h" ] || { echo "FAIL D02 缺 $h 钩子"; bad=1; }
-    done
-    if [ -n "$def" ] && [ -x "$hooksdir/pre-commit" ]; then
-      grep -q "prot=\" main master develop dev $def \"" "$hooksdir/pre-commit" \
-        || { echo "FAIL D03 钩子未保护默认分支 $def"; bad=1; }
-      if wt_is_main_checkout "$repo" && [ "$(git -C "$repo" symbolic-ref --short HEAD 2>/dev/null)" = "$def" ]; then
+    local mgr2; mgr2="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("hooksManager") or "")' "$cfg" 2>/dev/null || true)"
+    if [ "$mgr2" = "simple-git-hooks" ]; then
+      local rcf; rcf="$(wt_hooks_rc_dir)/simple-git-hooks-rc.sh"
+      [ -f "$rcf" ] || { echo "FAIL D02 缺 simple-git-hooks RC：$rcf"; bad=1; }
+      grep -rqs "SIMPLE_GIT_HOOKS_RC" "$HOME/.zshenv" || { echo "FAIL D02 shell 未 export SIMPLE_GIT_HOOKS_RC"; bad=1; }
+      python3 - "$repo/package.json" <<'PYM' >/dev/null 2>&1 || { echo "FAIL D02 package.json 未启用 simple-git-hooks"; bad=1; }
+import json,sys
+d=json.load(open(sys.argv[1])); c=d.get("simple-git-hooks"); dev=d.get("devDependencies",{}) or {}
+raise SystemExit(0 if isinstance(c,dict) or "simple-git-hooks" in dev else 1)
+PYM
+      if [ -n "$def" ] && wt_is_main_checkout "$repo" && [ "$(git -C "$repo" symbolic-ref --short HEAD 2>/dev/null)" = "$def" ]; then
+        ( cd "$repo" && DIA_WT_GUARD_PROBE=1 bash "$SELF" guard pre-commit >/dev/null 2>&1 ) \
+          && { echo "FAIL D03 守卫探针未拦截 $def 提交"; bad=1; }
+      fi
+    else
+      case "$prev" in /*) ;; *) echo "FAIL D02 本地 core.hooksPath 非绝对（$prev）"; bad=1 ;; esac
+      for h in pre-commit pre-push post-checkout; do
+        [ -x "$hooksdir/$h" ] || { echo "FAIL D02 缺 $h 钩子"; bad=1; }
+      done
+      if [ -n "$def" ] && wt_is_main_checkout "$repo" && [ "$(git -C "$repo" symbolic-ref --short HEAD 2>/dev/null)" = "$def" ]; then
         ( cd "$repo" && DIA_WT_GUARD_PROBE=1 "$hooksdir/pre-commit" >/dev/null 2>&1 ) \
-          && { echo "FAIL D03 守卫探针未拦截主 checkout 的 $def 提交"; bad=1; }
+          && { echo "FAIL D03 守卫探针未拦截 $def 提交"; bad=1; }
       fi
     fi
     if [ "$json" = 1 ]; then
@@ -1366,6 +1414,80 @@ cmd_adopt() {
 
   [ -n "$def" ] || die "默认分支不可解析；请 --default-branch main"
   mkdir -p "$hooksdir"
+  # 安装/刷新本机全局钩子，并让本仓走全局钩子（不改 package.json、不占用仓库钩子目录）
+  # ── 方案：每个仓本地钩子；simple-git-hooks 仓改用它的 RC 注入 ──────────────
+  # 不再写任何全局 git 配置（避免外溢）。
+  if [ -f "$repo/package.json" ] && python3 - "$repo/package.json" <<'PYCHK'
+import json,sys
+d=json.load(open(sys.argv[1]))
+cfg=d.get("simple-git-hooks")
+dev=d.get("devDependencies",{}) or {}
+raise SystemExit(0 if isinstance(cfg,dict) or "simple-git-hooks" in dev else 1)
+PYCHK
+  then
+    # simple-git-hooks：钩子由管理器生成到 .git/hooks，我们不碰；通过 SIMPLE_GIT_HOOKS_RC 注入守卫
+    local rcdir rcf
+    rcdir="$(wt_hooks_rc_dir)"; rcf="$rcdir/simple-git-hooks-rc.sh"
+    mkdir -p "$rcdir"
+    cat > "$rcf" <<'RC'
+# 由 simple-git-hooks 生成的钩子 source 本文件（SIMPLE_GIT_HOOKS_RC）
+# 只对已 adopt 的仓生效；未 adopt → 直接返回
+if command -v dia >/dev/null 2>&1; then
+  dia wt guard "$(basename "$0")" || exit $?
+fi
+RC
+    wt_ensure_env_export SIMPLE_GIT_HOOKS_RC "$rcf"
+    python3 - "$cfg" "$repo" "$def" "$template" "$prev" <<'PYG'
+import json, sys, datetime
+cfg, repo, br, tmpl, prev = sys.argv[1:6]
+json.dump({
+  "schema": 2, "repo": repo, "defaultBranch": br, "template": tmpl,
+  "hooksManager": "simple-git-hooks", "hooksPrevious": prev or None,
+  "adoptedAt": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+}, open(cfg, "w"), ensure_ascii=False, indent=1)
+PYG
+    echo "adopted：$repo（hook manager = simple-git-hooks；守卫经 SIMPLE_GIT_HOOKS_RC 注入）"
+    return 0
+  fi
+
+  # 其它仓：自己管 <common>/dia/hooks，并把本地 core.hooksPath 指过去。
+  # 若该仓已有**别人**的本地 hooksPath（husky/.githooks 等），不抢占：只报告，交由转为 simple-git-hooks 处理。
+  if [ -n "$prev" ] && [ "$prev" != "$hooksdir" ]; then
+    python3 - "$cfg" "$repo" "$def" "$template" "$prev" <<'PYG'
+import json, sys, datetime
+cfg, repo, br, tmpl, prev = sys.argv[1:6]
+json.dump({
+  "schema": 2, "repo": repo, "defaultBranch": br, "template": tmpl,
+  "hooksManager": "external", "hooksPrevious": prev,
+  "adoptedAt": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+}, open(cfg, "w"), ensure_ascii=False, indent=1)
+PYG
+    echo "[dia-wt] ⚠️ $repo 的 core.hooksPath=$prev 由其它管理器管理，未接管（守卫不生效）；建议改用 simple-git-hooks（见 docs/worktree.md）" >&2
+    return 0
+  fi
+  mkdir -p "$hooksdir"
+  local savedPrev=""
+  [ -f "$cfg" ] && savedPrev="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("hooksPrevious") or "")' "$cfg" 2>/dev/null || true)"
+  [ "$prev" = "$hooksdir" ] && prev="$savedPrev"
+  local chain="$prev"
+  [ -n "$chain" ] || chain="$common/hooks"
+  [ -f "$cfg" ] && cp "$cfg" "$cfgdir/config.json.bak.$(date +%s)"
+  wt_write_hook "$hooksdir" pre-commit "$def" "$chain"
+  wt_write_hook "$hooksdir" pre-push "$def" "$chain"
+  wt_write_hook "$hooksdir" post-checkout "$def" "$chain"
+  git -C "$repo" config --local core.hooksPath "$hooksdir"
+  python3 - "$cfg" "$repo" "$def" "$template" "$prev" "$chain" <<'PYG'
+import json, sys, datetime
+cfg, repo, br, tmpl, prev, chain = sys.argv[1:7]
+json.dump({
+  "schema": 2, "repo": repo, "defaultBranch": br, "template": tmpl,
+  "hooksManager": "local", "hooksPath": cfg.rsplit("/",1)[0] + "/hooks",
+  "hooksPrevious": prev or None, "hooksChain": chain,
+  "adoptedAt": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+}, open(cfg, "w"), ensure_ascii=False, indent=1)
+PYG
+  echo "adopted：$repo（守卫 = 仓库本地钩子 $hooksdir）"
+  return 0
   # 保留首次 adopt 记下的 hooksPrevious（重复 apply 时 prev 已是我们自己的 hooksdir）
   local savedPrev=""
   [ -f "$cfg" ] && savedPrev="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("hooksPrevious") or "")' "$cfg" 2>/dev/null || true)"
@@ -1384,11 +1506,6 @@ data = {
 }
 json.dump(data, open(cfg, "w"), ensure_ascii=False, indent=1)
 PY
-  # 提示：simple-git-hooks / husky 的 postinstall 会重写 core.hooksPath 下的钩子，
-  # 每次 `pnpm/npm install` 后可能把守卫冲掉 → 用 `dia wt doctor --fix` 或重跑 adopt --apply 修复。
-  if grep -qs '"simple-git-hooks"\|"husky"\|lefthook' "$repo/package.json" "$repo/.lefthook.yml" 2>/dev/null; then
-    echo "[dia-wt] 注意：该仓使用 hook manager（simple-git-hooks/husky/lefthook），install 后若守卫被重写，跑 dia wt doctor --fix" >&2
-  fi
   wt_write_hook "$hooksdir" pre-commit "$def" "$chain"
   wt_write_hook "$hooksdir" pre-push "$def" "$chain"
   wt_write_hook "$hooksdir" post-checkout "$def" "$chain"
@@ -1419,14 +1536,25 @@ cmd_doctor() {
     git -C "$repo" rev-parse --git-dir >/dev/null 2>&1 || continue
     local common cfgdir cfg hooksdir prev def
     common="$(wt_common_dir "$repo")"; cfgdir="$common/dia"; cfg="$cfgdir/config.json"; hooksdir="$cfgdir/hooks"
-    prev="$(git -C "$repo" config --get core.hooksPath 2>/dev/null || true)"
+    prev="$(git -C "$repo" config --local --get core.hooksPath 2>/dev/null || true)"
     def=""
     if [ -f "$cfg" ]; then
       def="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("defaultBranch") or "")' "$cfg" 2>/dev/null || true)"
     fi
     [ -n "$def" ] || def="$(wt_default_branch "$repo")"
     # --fix：无损修复（重写三个守卫钩子 + hooksPath 绝对路径）。只对已 adopt 的仓生效。
-    if [ "$fix" = 1 ] && [ -f "$cfg" ]; then
+    if [ "$fix" = 1 ] && [ -f "$cfg" ] && [ "$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("hooksManager") or "")' "$cfg" 2>/dev/null || true)" = "simple-git-hooks" ]; then
+      local rcdir rcf; rcdir="$(wt_hooks_rc_dir)"; rcf="$rcdir/simple-git-hooks-rc.sh"
+      mkdir -p "$rcdir"
+      cat > "$rcf" <<'RC'
+# 由 simple-git-hooks 生成的钩子 source 本文件（SIMPLE_GIT_HOOKS_RC）
+if command -v dia >/dev/null 2>&1; then
+  dia wt guard "$(basename "$0")" || exit $?
+fi
+RC
+      wt_ensure_env_export SIMPLE_GIT_HOOKS_RC "$rcf"
+      [ "$json" = 0 ] && echo "FIX $repo simple-git-hooks RC 已重建"
+    elif [ "$fix" = 1 ] && [ -f "$cfg" ]; then
       local fixChain=""
       fixChain="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("hooksChain") or "")' "$cfg" 2>/dev/null || true)"
       [ -n "$fixChain" ] || fixChain="$common/hooks"
@@ -1438,18 +1566,31 @@ cmd_doctor() {
       prev="$hooksdir"
       [ "$json" = 0 ] && echo "FIX $repo 钩子已重装（chain=$fixChain）"
     fi
-    local bad=0
+    local bad=0 mcfg=""
     [ -f "$cfg" ] || { echo "FAIL D01 $repo 未 adopt"; bad=1; }
-    case "$prev" in /*) ;; *) echo "FAIL D02 $repo hooksPath 非绝对（$prev）"; bad=1 ;; esac
-    for h in pre-commit pre-push post-checkout; do
-      [ -x "$hooksdir/$h" ] || { echo "FAIL D02 $repo 缺 $h"; bad=1; }
-    done
-    if [ -n "$def" ] && [ -x "$hooksdir/pre-commit" ]; then
-      # 静态：钩子里的 protected 列表必须包含 defaultBranch
-      grep -q "prot=\" main master develop dev $def \"" "$hooksdir/pre-commit" \
-        || { echo "FAIL D03 $repo 钩子未保护默认分支 $def"; bad=1; }
-      # 动态：主 checkout 当前就在 def 上时必须被拦
-      if wt_is_main_checkout "$repo" && [ "$(git -C "$repo" symbolic-ref --short HEAD 2>/dev/null)" = "$def" ]; then
+    [ -f "$cfg" ] && mcfg="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("hooksManager") or "")' "$cfg" 2>/dev/null || true)"
+    local ghp mgr2
+    ghp="$(git config --global --get core.hooksPath 2>/dev/null || true)"
+    # D20 全局配置残留：旧版把守卫装到全局 hooksPath；现在改为每仓本地，必须清掉
+    if [ -n "$ghp" ] && [ -f "$ghp/pre-commit" ] && grep -q "dia-wt guard" "$ghp/pre-commit" 2>/dev/null; then
+      echo "FAIL D20 全局 core.hooksPath 仍指向 dia 旧钩子目录（$ghp）；执行 git config --global --unset core.hooksPath"
+      bad=1
+    fi
+    mgr2="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("hooksManager") or "")' "$cfg" 2>/dev/null || true)"
+    if [ "$mgr2" = "simple-git-hooks" ]; then
+      local rcf; rcf="$(wt_hooks_rc_dir)/simple-git-hooks-rc.sh"
+      [ -f "$rcf" ] || { echo "FAIL D02 $repo 缺 simple-git-hooks RC：$rcf"; bad=1; }
+      grep -rqs "SIMPLE_GIT_HOOKS_RC" "$HOME/.zshenv" || echo "WARN D02 $repo shell 未 export SIMPLE_GIT_HOOKS_RC（守卫不会执行）"
+      if [ -n "$def" ] && wt_is_main_checkout "$repo" && [ "$(git -C "$repo" symbolic-ref --short HEAD 2>/dev/null)" = "$def" ]; then
+        ( cd "$repo" && DIA_WT_GUARD_PROBE=1 bash "$SELF" guard pre-commit >/dev/null 2>&1 ) \
+          && { echo "FAIL D03 $repo 守卫探针未拦截 $def 提交"; bad=1; }
+      fi
+    else
+      case "$prev" in /*) ;; *) echo "FAIL D02 $repo 本地 core.hooksPath 非绝对（$prev）"; bad=1 ;; esac
+      for h in pre-commit pre-push post-checkout; do
+        [ -x "$hooksdir/$h" ] || { echo "FAIL D02 $repo 缺 $h"; bad=1; }
+      done
+      if [ -n "$def" ] && wt_is_main_checkout "$repo" && [ "$(git -C "$repo" symbolic-ref --short HEAD 2>/dev/null)" = "$def" ]; then
         ( cd "$repo" && DIA_WT_GUARD_PROBE=1 "$hooksdir/pre-commit" >/dev/null 2>&1 ) \
           && { echo "FAIL D03 $repo 守卫未拦截 $def 提交"; bad=1; }
       fi
@@ -1507,6 +1648,7 @@ case "${1:-}" in
   status) shift; cmd_status "$@" ;;
   check)  shift; cmd_check "$@" ;;
   adopt)  shift; cmd_adopt "$@" ;;
+  guard)  shift; cmd_guard "$@" ;;
   doctor) shift; cmd_doctor "$@" ;;
   gate)   shift; cmd_gate "$@" ;;
   clean)  shift; cmd_clean "$@" ;;
@@ -1522,6 +1664,7 @@ dia wt —— worktree 目录形式选型 + 创建（唯一实现）
   dia wt status [repo-path]              # ★ 清理前必查：唯一工作副本 + 改动重叠（只读）
   dia wt check  [<repo>...] [--all] [--deep] [--quiet]
                                                # ★ 依赖体检（R20）：软链/逃逸/悬空；--all 扫全部仓
+  dia wt guard  <pre-commit|pre-push|post-checkout>   # 守卫本体（供 hook manager 调用）
   dia wt adopt  <repo>|--all [--apply|--check|--revert] [--template T] [--default-branch B] [--json]
                                                # 配置路径模板 + 守卫钩子（默认 dry-run；--all 扫仓根）
                                                # 守卫含推送前敏感扫描（不提供关闭开关；误报修规则）