@andyqiu/codeforge 0.5.15 → 0.5.17

package/README.md

@@ -7,18 +7,10 @@ CodeForge — [opencode](https://github.com/sst/opencode) 的零侵入扩展包
 需要 **opencode ≥ 1.14** 和 **Node ≥ 20**。
 
 ```bash
-# 方式一：npm 全局安装（推荐，装完直接有 codeforge 命令）
 npm install -g @andyqiu/codeforge
-codeforge install --global
-
-# 方式二：npx 免安装（一次性，不占全局）
-npx @andyqiu/codeforge install --global
-
-# 只装当前项目（不推荐，每个项目都要装）
-npx @andyqiu/codeforge install
 ```
 
-装完**重启 opencode**。
+装完**重启 opencode**。（postinstall 脚本会自动完成全局配置，无需额外操作。）
 
 ## 怎么用
 
@@ -49,9 +41,15 @@ npx @andyqiu/codeforge install
 | `/review` | 审当前暂存的改动 |
 | `/refactor <目标>` | 安全重构（先补测试锁行为，再改） |
 | `/tdd <需求>` | 严格 RED → GREEN → REFACTOR |
-| `/parallel <任务1>,<任务2>,...` | 多个独立任务并发跑 |
+| `/merge` | 触发 review + squash merge 入主仓 |
+| `/discard-session` | 放弃当前 session 的所有改动 |
 | `/adr-init` | 为当前项目初始化 ADR 决策记录体系 |
-
+| `/debug <问题>` | 调试模式，深入分析问题根因 |
+| `/deep <需求>` | 强制升档用高端推理模型处理 |
+| `/quick <需求>` | 强制降档用快速模型处理 |
+| `/changes` | 查看当前 session 的改动摘要 |
+| `/pause` | 暂停当前任务 |
+| `/parallel <任务1>,<任务2>` | 多个独立任务并发跑 |
 
 ### Discover Agent — 虚拟产品经理
 
@@ -68,7 +66,7 @@ discover 会跑 5 个阶段：
 4. **PRD 起草** — 生成 EARS 句式 PRD.md + 机读 handoff.yaml
 5. **复核** — challenger 二次复核
 
-产物在 `.codeforge/specs/<slug>/{PRD.md, handoff.yaml}`，会被下游 codeforge / planner / coder **自动消费**（通过 `discover-spec-suggest` plugin 注入候选提示）。
+产物在 `.codeforge/specs/<slug>/{PRD.md, handoff.yaml}`，会被下游 codeforge / planner / coder **自动消费**。
 
 详见 [docs/discover/README.md](./docs/discover/README.md)。
 
@@ -77,10 +75,10 @@ discover 会跑 5 个阶段：
 在任意 git 项目根目录执行一次，把完整的 ADR 校验体系下发到该项目：
 
 ```bash
-# 方式一：CLI 命令
+# CLI 命令
 codeforge adr-init
 
-# 方式二：opencode 里直接说
+# opencode 里直接说
 /adr-init
 
 # 常用选项
@@ -109,60 +107,13 @@ git config core.hooksPath .githooks
 
 npm 项目可加 `--write-prepare` 让 `npm install` 自动完成上面这步。
 
-### 难度分级与三道防线（Phase 2 引入）
-
-CodeForge 给每个 agent 配三档变体，让简单任务省 token、复杂任务自动升档保质量：
-
-| 档位 | 模型基线 | 用途 |
-|---|---|---|
-| `coder-quick` | 低成本快速模型 | typo / 单行改动 |
-| `coder`（默认） | 中端模型 | 单文件中等改动 |
-| `coder-deep` | 高端推理模型 | 跨文件重构 / 安全 / 数据迁移 |
-
-三道防线决定最终用哪档（优先级递减）：
-
-- **A · 用户显式 override**：`/deep` 升档、`/quick` 降档；锁定后 B/C 都不会覆盖
-- **B · 前置预判**（Phase 2b 接线中）：派 task 前看跨文件数 / 关键词（auth / refactor / migration / schema）自动选档
-- **C · 运行时升档**：reviewer 连续 REQUEST_CHANGES、stuck-detector 触发、测试连续失败 → 兜底升档（带 quota + debounce 去噪）
-
-升档不会静默改配置——当前会记录日志并提示；完成 auto_escalate 接线后，配置变更才会进入 session worktree 等你通过 `/merge` 审批。完整设计见 `docs/adr/model-tier-three-layer-escalation.md`。
-
-
 ### 代码改动如何落地
 
-每个 session 绑定独立 git worktree，AI 改动直接写到 worktree（不影响主仓）；
-审批通过 `/merge` 命令触发 review-fix-review 闭环，通过后 squash merge 入主仓。
-完整设计见 `docs/adr/worktree-session-isolation.md`。
-
-```bash
-# 查看当前 session worktree 改动
-git -C <worktree> diff
-
-# 触发 review + 合并闭环
-/merge               # TUI 内 slash command
-/discard-session     # 放弃当前 session
-```
-
-## 查版本 / 升级 / 回滚
+每个 session 绑定独立 git worktree，AI 改动直接写到 worktree（不影响主仓）；审批通过 `/merge` 命令触发 review-fix-review 闭环，通过后 squash merge 入主仓。
 
 ```bash
-# 查当前版本
-cat ~/.config/opencode/codeforge/VERSION
-# Windows：Get-Content "$env:USERPROFILE\.config\opencode\codeforge\VERSION"
-
-# 立即升级到最新
-npx @andyqiu/codeforge install --global
-
-# 回滚到上一版
-codeforge rollback
-```
-
-opencode 启动时**自动后台检查新版**并静默升级，下次启动生效。
-
-关闭自动升级（编辑 `~/.config/opencode/codeforge/codeforge.json`）：
-
-```json
-{ "update": { "auto_install": false } }
+/merge               # 触发 review + 合并闭环
+/discard-session     # 放弃当前 session 的所有改动
 ```
 
 ## Knowledge Hub（可选，团队共享经验）
@@ -179,107 +130,16 @@ export KNOWLEDGE_API_KEY=你的-token
 
 详细配置 token 找你的团队管理员。
 
-## 通知集成（可选）
-
-支持把 AI 完成的任务、审阅结果推到 Slack / 飞书。**三种配置方式**，同时存在时按以下优先级合并（0.3.11 起补齐全局层，对齐 KH 配置惯例）：
-
-| 优先级 | 来源 | 适用场景 |
-|---|---|---|
-| 1（最高）| `CODEFORGE_CHANNELS_JSON` env | CI / 本机临时覆盖 / 紧急静音（设为 `[]` 即全禁） |
-| 2 | `<project>/.codeforge/channels.json` | 团队 git 共享（0.3.11 推荐路径） |
-| 3（最低）| `~/.config/codeforge/channels.json` | 个人跨项目共享 |
-
-> 同名 channel：上层覆盖下层（env > project > global），覆盖时打 warn 提示。
-> env 显式为 `[]` 时清空 **三层全部**通知（0.3.11 行为变更，详见 CHANGELOG）。
->
-> 0.3.10 兼容路径 `<root>/.codeforge/config/channels.json` 继续工作但启动 warn 提示迁移；两条路径同时存在时**只读 0.3.11 推荐路径**。
-
-### 方式 ⓪ 全局个人配置（跨项目共享）
-
-适用：你个人想在所有项目里都收同一个飞书/Slack 通知，不想每个项目都重配一遍。
-
-```bash
-# macOS / Linux
-mkdir -p ~/.config/codeforge
-cat > ~/.config/codeforge/channels.json <<'JSON'
-[
-  {
-    "type": "lark",
-    "name": "personal-lark",
-    "webhook_url": "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
-  }
-]
-JSON
-chmod 600 ~/.config/codeforge/channels.json  # 含 webhook secret，建议 600
-```
-
-```powershell
-# Windows PowerShell
-$dir = "$env:USERPROFILE\.config\codeforge"
-New-Item -ItemType Directory -Force -Path $dir | Out-Null
-@'
-[{"type":"lark","name":"personal-lark","webhook_url":"https://open.feishu.cn/open-apis/bot/v2/hook/xxx"}]
-'@ | Set-Content -Encoding UTF8 "$dir\channels.json"
-```
-
-> 含 webhook secret，权限松（group/other 可读）时会启动打一次性 warn 提示 `chmod 600`，但不阻止加载。
-
-### 方式 ① 项目共享配置（推荐团队场景）
-
-在项目根创建 `.codeforge/channels.json`（**0.3.11 推荐路径**，可 git 提交）：
-
-```json
-{
-  "channels": [
-    {
-      "type": "slack",
-      "name": "dev-alerts",
-      "webhook_url": "https://hooks.slack.com/services/T.../B.../xxx",
-      "events": ["workflow.failed", "approval.required"]
-    },
-    {
-      "type": "lark",
-      "name": "team-lark",
-      "webhook_url": "https://open.feishu.cn/open-apis/bot/v2/hook/xxx",
-      "secret": "可选签名密钥",
-      "mentions": ["@all"]
-    }
-  ]
-}
-```
-
-> 0.3.10 兼容路径 `.codeforge/config/channels.json` 仍可用，但启动会 warn 提示迁移到 `.codeforge/channels.json`（与 KH 配置 `<root>/.codeforge/kh.json` 风格统一）。0.3.10 用户继续工作不受影响。
-
-完整字段定义见 `lib/channels.ts` 中 `SlackChannel` / `LarkChannel` 接口。
-
-### 方式 ② 环境变量（CI 友好 / 临时覆盖）
+## 升级
 
 ```bash
-export CODEFORGE_CHANNELS_JSON='[{"type":"lark","name":"ci","webhook_url":"https://..."}]'
+npm update -g @andyqiu/codeforge
 ```
 
-### ⚠️ 老配置迁移
-
-如果你按旧版 README 配过 `~/.config/opencode/codeforge/codeforge.json` 里的 `channels`（**该路径从未被 plugin 读取**，原本就发不出通知），或者 0.3.10 配过 `<root>/.codeforge/config/channels.json`，请按下表迁移：
-
-| 旧 | 新（0.3.11 推荐） |
-|---|---|
-| `~/.config/opencode/codeforge/codeforge.json` 的 `channels` 字段 | `~/.config/codeforge/channels.json`（全局）或 `<project>/.codeforge/channels.json`（项目） |
-| `<project>/.codeforge/config/channels.json`（0.3.10 兼容路径） | `<project>/.codeforge/channels.json`（0.3.11 推荐路径） |
-| `{ "type": "slack", "webhook": "..." }` | `{ "type": "slack", "name": "<必填>", "webhook_url": "..." }` |
-| `{ "type": "lark", "webhook": "...", "secret": "..." }` | `{ "type": "lark", "name": "<必填>", "webhook_url": "...", "secret": "..." }` |
-
-变更点：
-1. **加载路径**：3 层 `env > <project>/.codeforge/channels.json > ~/.config/codeforge/channels.json`（旧 `~/.config/opencode/codeforge/codeforge.json` 无效）
-2. **字段名**：`webhook` → `webhook_url`
-3. **新必填**：`name`（用于跨层合并去重）
-
-配置错误时会在 plugin 启动日志打 warn，告知被忽略的 channel 名与缺失字段。
-
 ## 卸载
 
 ```bash
-npx @andyqiu/codeforge uninstall --global
+npm uninstall -g @andyqiu/codeforge
 ```
 
 ## 出问题怎么办
@@ -288,9 +148,9 @@ npx @andyqiu/codeforge uninstall --global
 |---|---|
 | 装完 opencode 没识别新命令 | 重启 opencode |
 | AI 改动没写入主仓 | 改动在 session worktree 内；用 `/merge` 触发审批 + 合并闭环 |
-| 自动升级把功能搞坏了 | `codeforge rollback` 回上一版 |
-| 启动报"opencode 版本不兼容" | 升级 opencode：`npm i -g opencode-ai@latest` |
-| 命令找不到 | 全局装时确认 npm global bin 在 PATH：`npm config get prefix` |
+| 启动报"opencode 版本不兼容" | 升级 opencode：`npm install -g opencode@latest` |
+| 命令找不到 | 确认 npm global bin 在 PATH：`npm config get prefix` |
+| 需要查当前版本 | `codeforge --version` |
 
 其它问题联系 [@andyqiu](https://www.npmjs.com/~andyqiu)。
 

package/bin/codeforge.mjs

@@ -3,12 +3,12 @@
  * codeforge — opencode 零侵入扩展包的安装入口
  *
  * 一行命令安装：
- *   npx @andyqiu/codeforge install
+ *   npm install -g @andyqiu/codeforge
  *
  * 子命令：
- *   install    [--global|--project] [--dry-run] [--enable-legacy-tools]
+ *   install    [--dry-run] [--enable-legacy-tools]
  *               把 CodeForge 单 bundle 注入到 opencode（写 opencode.json plugin entry）
- *   uninstall  [--global|--project]   卸载（不动 opencode 自身）
+ *   uninstall               卸载（不动 opencode 自身）
  *   list                              探测 opencode 是否在机器上
  *   version                           打印版本
  *   rollback   [--target=<path>] [--dry-run]
@@ -18,7 +18,7 @@
  *                                     把 ADR 体系（hooks + scripts + 模板）下发到当前 git 项目
  *   help [<cmd>]                      打印帮助
  *
- * 默认 --project（项目级，最安全）。
+ * 强制全局安装（~/.config/opencode/），不再支持项目级安装。
  *
  * 只支持 opencode：CodeForge 是单 bundle plugin，跑在 opencode 1.14+ 上（持续跟主线）。
  * Cursor / Claude Code / Codex 都不能加载这种 plugin（API 不兼容），所以不假装支持。
@@ -148,7 +148,7 @@ function detectOpencode() {
 // 子命令：install
 // ────────────────────────────────────────────────────────────────────
 function cmdInstall(args) {
-  const scope = args.flags.global ? "global" : "project"
+  const scope = "global"
   const dryRun = !!args.flags["dry-run"] || !!args.flags.dryRun
   const fromNpm = isFromNpm()
   // npm 场景下 dist/ 已经被 prepack 打过包随 tarball 发布，强制 --skip-build
@@ -189,7 +189,7 @@ function cmdInstall(args) {
 // 子命令：uninstall
 // ────────────────────────────────────────────────────────────────────
 function cmdUninstall(args) {
-  const scope = args.flags.global ? "global" : "project"
+  const scope = "global"
   log(`CodeForge uninstaller`)
   log(`  scope   : ${scope}`)
   hr()
@@ -267,7 +267,7 @@ function cmdRollback(args) {
 
   if (backups.length === 0) {
     err(`找不到任何 backup（pattern: ${prefix}*）`)
-    err(`提示：自动更新尚未执行过 / backup 已被清理。可跑 npx @andyqiu/codeforge install 重装。`)
+    err(`提示：自动更新尚未执行过 / backup 已被清理。可跑 npm install -g @andyqiu/codeforge 重装。`)
     return 1
   }
 
@@ -476,8 +476,8 @@ function cmdHelp() {
   console.log(`${C.bold}codeforge${C.reset} — opencode 的零侵入扩展包安装入口
 
 用法：
-  codeforge install    [--global|--project] [--dry-run] [--skip-build]
-  codeforge uninstall  [--global|--project]
+  codeforge install    [--dry-run] [--skip-build]
+  codeforge uninstall
   codeforge list
   codeforge version
   codeforge rollback   [--target=<path>] [--dry-run]   # 恢复最近 backup（auto_install 失败救场）
@@ -486,13 +486,10 @@ function cmdHelp() {
   codeforge adr-init   [--force] [--dry-run] [--write-prepare] [--no-pre-push]
                                      # 把 ADR 校验体系（hooks + scripts + 模板）下发到当前 git 项目
 
-一行命令（远程安装）：
-  npx @andyqiu/codeforge install
-  npx @andyqiu/codeforge install --global
+安装：
+  npm install -g @andyqiu/codeforge
 
 参数：
-  --global               装到全局（~/.config/opencode/）
-  --project              装到项目（./.opencode/，默认）
   --dry-run              只打印操作，不真改
   --skip-build           跳过 npm run build（已有 dist/index.js 时增量装）
   --enable-legacy-tools  启用旧版 file-based tools（默认禁用，避免 zod 跨实例 bug）

package/commands/merge.md

@@ -71,6 +71,22 @@ session_merge(action="merge", plan_id=<可选>, force=<可选>)
 }
 ```
 
+### `.codeforge/codeforge.json::merge.postMergeScript`（可选，团队共享）
+
+声明 `/merge` squash 成功后要跑的 npm script（dist 重 build）。未配置则跳过。
+
+```json
+{
+  "merge": {
+    "postMergeScript": "build:dev"
+  }
+}
+```
+
+- 非 Node 项目（C# / Go / Rust）一般不需要此字段
+- script 失败会触发主仓 `git reset --hard HEAD` 兜底（保 merge 原子性，详见 ADR:merge-back-rollback）
+- 详见 ADR:merge-post-script-config
+
 ## 与其他命令的关系
 
 | 命令 | 用途 |

package/dist/index.js

@@ -8220,10 +8220,11 @@ function shouldYieldToLocalPlugin(opts = {}) {
   if (envVal === "1" || envVal === "true" || envVal === "yes") {
     return { yield: true, reason: "env" };
   }
+  const usingFallback = !opts.directory;
   const startDir = opts.directory ? resolve(opts.directory) : process.cwd();
-  const maxDepth = Math.max(1, opts.maxDepth ?? 20);
+  const effectiveMaxDepth = opts.maxDepth !== undefined ? Math.max(1, opts.maxDepth) : usingFallback ? 1 : 3;
   let cur = startDir;
-  for (let i = 0;i < maxDepth; i++) {
+  for (let i = 0;i < effectiveMaxDepth; i++) {
     const markerPath = resolve(cur, MARKER_REL);
     try {
       if (fileExists(markerPath)) {
@@ -13130,6 +13131,7 @@ function sleep(ms) {
 }
 
 // lib/session-worktree.ts
+init_global_config();
 var REGISTRY_VERSION = 1;
 var DEFAULT_WORKTREE_SUBDIR = path13.join(".git", "codeforge-worktrees");
 function registryDir(mainRoot) {
@@ -13278,7 +13280,7 @@ async function mergeSessionBack(opts) {
       "--diff-filter=ACMR"
     ]);
     const stagedPaths = stagedRaw.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
-    const canSkipDevOnce = await shouldSkipDevOnce(mainRoot, stagedPaths);
+    const canSkipDevOnce = await shouldSkipDevOnce(mainRoot, stagedPaths, wt);
     if (canSkipDevOnce) {
       const sourceCount = stagedPaths.filter((p) => /^(plugins|lib|src)\//.test(p) && !/\.(md|test\.ts)$/.test(p)).length;
       console.log(`[session-worktree] skip ${buildScript}: dist 已是最新（${sourceCount} staged 源文件 mtime <= dist mtime）`);
@@ -13292,7 +13294,7 @@ async function mergeSessionBack(opts) {
       }
     }
   } else {
-    console.warn(`[session-worktree] skip build step: neither build:dev nor dev:once configured in ${mainRoot}/package.json`);
+    console.warn(`[session-worktree] skip build step: merge.postMergeScript not configured in .codeforge/codeforge.json (project may not need post-merge build)`);
   }
   const squashedRaw = await runGit2(wt, ["log", "--format=%s", `${baseSha}..HEAD`]);
   const squashedCommits = squashedRaw.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
@@ -13418,26 +13420,18 @@ function runGitWithEnv(cwd, args, envOverrides, timeoutMs = 1e4) {
     });
   });
 }
-async function packageHasScript(mainRoot, scriptName) {
-  try {
-    const pkgPath = path13.join(mainRoot, "package.json");
-    const raw = await fs10.readFile(pkgPath, "utf8");
-    const pkg = JSON.parse(raw);
-    if (!pkg.scripts || typeof pkg.scripts !== "object")
-      return false;
-    return typeof pkg.scripts[scriptName] === "string";
-  } catch {
-    return false;
-  }
-}
 async function getBuildScript(mainRoot) {
-  if (await packageHasScript(mainRoot, "build:dev"))
-    return "build:dev";
-  if (await packageHasScript(mainRoot, "dev:once"))
-    return "dev:once";
-  return null;
+  const cfg = getCodeforgeConfig({ root: mainRoot });
+  const merge = cfg["merge"];
+  if (!merge || typeof merge !== "object" || Array.isArray(merge))
+    return null;
+  const script = merge["postMergeScript"];
+  if (typeof script !== "string")
+    return null;
+  const trimmed = script.trim();
+  return trimmed.length > 0 ? trimmed : null;
 }
-async function shouldSkipDevOnce(mainRoot, stagedPaths) {
+async function shouldSkipDevOnce(mainRoot, stagedPaths, worktreePath) {
   let distMtimeSec;
   try {
     const st = await fs10.stat(path13.join(mainRoot, "dist/index.js"));
@@ -13449,18 +13443,28 @@ async function shouldSkipDevOnce(mainRoot, stagedPaths) {
   if (relevant.length === 0)
     return true;
   for (const rel of relevant) {
-    try {
-      const abs = path13.join(mainRoot, rel);
-      const st = await fs10.stat(abs);
-      const srcMtimeSec = Math.floor(st.mtimeMs / 1000);
-      if (srcMtimeSec > distMtimeSec)
-        return false;
-    } catch {
+    const srcMtimeSec = await statSourceMtime(rel, mainRoot, worktreePath);
+    if (srcMtimeSec === null)
+      return false;
+    if (srcMtimeSec > distMtimeSec)
       return false;
-    }
   }
   return true;
 }
+async function statSourceMtime(rel, mainRoot, worktreePath) {
+  if (worktreePath) {
+    try {
+      const st = await fs10.stat(path13.join(worktreePath, rel));
+      return Math.floor(st.mtimeMs / 1000);
+    } catch {}
+  }
+  try {
+    const st = await fs10.stat(path13.join(mainRoot, rel));
+    return Math.floor(st.mtimeMs / 1000);
+  } catch {
+    return null;
+  }
+}
 function runCmd(cmd, args, cwd, timeoutMs = 300000) {
   return new Promise((resolve11, reject) => {
     execFile3(cmd, args, { cwd, timeout: timeoutMs, windowsHide: true, encoding: "utf8" }, (err, stdout, stderr) => {
@@ -16215,10 +16219,11 @@ var codeforgeToolsServer = async (ctx) => {
       session_merge: tool({
         description: description26,
         args: {
-          action: z30.enum(["merge", "status", "discard"]).describe("操作类型：merge=合并到主仓（orchestrator 专用）/ status=查询状态 / discard=放弃"),
+          action: z30.enum(["merge", "status", "discard", "diff"]).describe("操作类型：merge=合并到主仓（orchestrator 专用）/ status=查询状态 / discard=放弃 / diff=查看 worktree 改动"),
           session_id: z30.string().optional().describe("目标 session id；不传则用当前 session"),
           plan_id: z30.string().optional().describe("关联的 plan_id（reviewer 校验时用），格式 plan-YYYYMMDD-HHmmss-NNN"),
-          force: z30.boolean().optional().describe("action=merge 时跳过 review 直接 squash merge（写审计）")
+          force: z30.boolean().optional().describe("action=merge 时跳过 review 直接 squash merge（写审计）"),
+          stat: z30.boolean().optional().describe("action=diff 时：true=只显示文件列表+统计，false=完整 diff（默认 false）")
         },
         async execute(args, input) {
           return await runSafe("session_merge", async () => {
@@ -21785,7 +21790,7 @@ import * as zlib from "node:zlib";
 // lib/version-injected.ts
 function getInjectedVersion() {
   try {
-    const v = "0.5.15";
+    const v = "0.5.17";
     if (typeof v === "string" && /^\d+\.\d+\.\d+/.test(v)) {
       return v;
     }
@@ -23097,6 +23102,70 @@ function buildGitVcsWriteRegex(mainRoot) {
 var WRITE_TOOLS = new Set(["write", "edit", "ast_edit"]);
 var TOUCH_THROTTLE_MS = 5 * 60000;
 var _touchCache = new Map;
+var _sessionIdMissingWarned = false;
+var _bindFailNotified = new Set;
+function formatLazyBindDenyReason(input) {
+  const { sessionId, mainRoot, toolName, errMsg, alreadyNotified } = input;
+  const firstLine = errMsg.split(`
+`).find((l) => l.trim().length > 0)?.trim() ?? errMsg;
+  const lower = firstLine.toLowerCase();
+  if (alreadyNotified) {
+    return `[session-worktree-guard] DENIED: session ${sessionId} 仍无法绑定 worktree（${firstLine}）；` + `详见首次报错或 ~/.cache/codeforge/plugins.log。本 session 已永久无法绑定，可设 ` + `CODEFORGE_DISABLE_WORKTREE_GUARD=1 临时绕过（会失去隔离保护）。`;
+  }
+  if (lower.includes("not a git repository")) {
+    return [
+      `[session-worktree-guard] DENIED: 无法为 session ${sessionId} 绑定 worktree，写操作可能污染主工作区，已拒绝执行`,
+      `原因：当前项目不是 git 仓库（git 错误：${firstLine}）`,
+      `影响工具：${toolName}`,
+      `解决方案：`,
+      `  1. 确认你在正确的项目根目录（当前 mainRoot=${mainRoot}）`,
+      `  2. 若该项目应该是 git 仓库：\`git init && git add -A && git commit -m "initial"\``,
+      `  3. 若该项目不需要 worktree 隔离（如临时脚本目录），可设置环境变量绕过：`,
+      `     \`CODEFORGE_DISABLE_WORKTREE_GUARD=1 opencode\`（**会失去隔离保护，谨慎使用**）`,
+      `排查日志：\`cat ~/.cache/codeforge/plugins.log | grep session-worktree-guard\``
+    ].join(`
+`);
+  }
+  if (lower.includes("git: command not found") || lower.includes("enoent") && lower.includes("git")) {
+    return [
+      `[session-worktree-guard] DENIED: 无法为 session ${sessionId} 绑定 worktree，写操作可能污染主工作区，已拒绝执行`,
+      `原因：找不到 git 可执行文件（错误：${firstLine}）`,
+      `影响工具：${toolName}`,
+      `解决方案：`,
+      `  1. 安装 git（>= 2.5 才支持 worktree）：Linux \`apt install git\` / macOS \`brew install git\``,
+      `  2. 确认 git 在 PATH 中：\`command -v git\``,
+      `  3. 若临时无法安装，可设置环境变量绕过：`,
+      `     \`CODEFORGE_DISABLE_WORKTREE_GUARD=1 opencode\`（**会失去隔离保护，谨慎使用**）`,
+      `排查日志：\`cat ~/.cache/codeforge/plugins.log | grep session-worktree-guard\``
+    ].join(`
+`);
+  }
+  if (lower.includes("worktree") || lower.includes("head")) {
+    return [
+      `[session-worktree-guard] DENIED: 无法为 session ${sessionId} 绑定 worktree，写操作可能污染主工作区，已拒绝执行`,
+      `原因：worktree 创建失败（git 错误：${firstLine}）`,
+      `影响工具：${toolName}`,
+      `常见原因：`,
+      `  - 仓库尚无任何 commit（HEAD 不存在）：先 \`git commit\` 一次`,
+      `  - 同名分支已被其他 worktree 占用：清理 \`git worktree prune\``,
+      `  - .git 目录权限/损坏：检查 \`git fsck\``,
+      `逃生口：\`CODEFORGE_DISABLE_WORKTREE_GUARD=1 opencode\`（**会失去隔离保护，谨慎使用**）`,
+      `排查日志：\`cat ~/.cache/codeforge/plugins.log | grep session-worktree-guard\``
+    ].join(`
+`);
+  }
+  return [
+    `[session-worktree-guard] DENIED: 无法为 session ${sessionId} 绑定 worktree，写操作可能污染主工作区，已拒绝执行`,
+    `原因：bindSessionWorktree 抛错（${firstLine}）`,
+    `影响工具：${toolName}`,
+    `mainRoot：${mainRoot}`,
+    `解决方案：`,
+    `  1. 重试一次（可能是瞬时锁冲突）`,
+    `  2. 看完整日志：\`cat ~/.cache/codeforge/plugins.log | grep session-worktree-guard\``,
+    `  3. 临时绕过：\`CODEFORGE_DISABLE_WORKTREE_GUARD=1 opencode\`（**会失去隔离保护，谨慎使用**）`
+  ].join(`
+`);
+}
 var CLASS_B_CALLER_WHITELIST = new Set([
   "codeforge",
   "reviewer",
@@ -23227,6 +23296,18 @@ function resolveMainRoot2(rawDir) {
   return rawDir;
 }
 var sessionWorktreeGuardPlugin = async (ctx) => {
+  const disableEnv = process.env["CODEFORGE_DISABLE_WORKTREE_GUARD"];
+  if (disableEnv === "1" || disableEnv === "true" || disableEnv === "yes") {
+    log14.warn("[guard] CODEFORGE_DISABLE_WORKTREE_GUARD 已启用，session-worktree-guard 全部 hook 跳过；" + "本次 opencode 会话所有写操作将直接落到主工作区（失去隔离保护）", { env: disableEnv });
+    safeWriteLog(PLUGIN_NAME25, {
+      hook: "activate",
+      action: "skip",
+      source: "disable-env",
+      env_value: disableEnv
+    });
+    logLifecycle(PLUGIN_NAME25, "activate", { disabled_by_env: true });
+    return {};
+  }
   const mainRoot = resolveMainRoot2(ctx.directory ?? process.cwd());
   let policyCfg = {};
   try {
@@ -23245,8 +23326,24 @@ var sessionWorktreeGuardPlugin = async (ctx) => {
   return {
     "tool.execute.before": async (input, output) => {
       const sessionId = input.sessionID ?? process.env["CODEFORGE_SESSION_ID"];
-      if (!sessionId)
+      if (!sessionId) {
+        const isWrite = isWriteOperation(input.tool, output.args ?? {}, mainRoot);
+        if (isWrite && !_sessionIdMissingWarned) {
+          _sessionIdMissingWarned = true;
+          log14.warn("[guard] sessionID 缺失，无法绑定 worktree；本会话所有写操作将落到主工作区（仅本进程内 warn 一次）。" + "排查：grep no-session-id ~/.cache/codeforge/plugins.log", {
+            tool: input.tool,
+            opencode_version_hint: "需 opencode >= 0.x 才会在 tool.execute.before 注入 input.sessionID"
+          });
+        }
+        safeWriteLog(PLUGIN_NAME25, {
+          hook: "tool.execute.before",
+          tool: input.tool,
+          action: "skip",
+          source: "no-session-id",
+          is_write: isWrite
+        });
         return;
+      }
       let denied;
       await safeAsync(PLUGIN_NAME25, "tool.execute.before", async () => {
         const toolName = input.tool;
@@ -23301,14 +23398,32 @@ var sessionWorktreeGuardPlugin = async (ctx) => {
               worktreePath: entry.worktreePath
             });
           } catch (err) {
-            log14.warn(`[lazy-bind] failed (落到主仓写)`, { sessionId, error: err instanceof Error ? err.message : String(err) });
+            const errMsg = err instanceof Error ? err.message : String(err);
+            const alreadyNotified = _bindFailNotified.has(sessionId);
+            const reason = formatLazyBindDenyReason({
+              sessionId,
+              mainRoot,
+              toolName,
+              errMsg,
+              alreadyNotified
+            });
+            _bindFailNotified.add(sessionId);
+            log14.warn(`[lazy-bind] DENY (bind failed)`, {
+              sessionId,
+              tool: toolName,
+              error: errMsg,
+              throttled: alreadyNotified
+            });
             safeWriteLog(PLUGIN_NAME25, {
               hook: "tool.execute.before",
               tool: toolName,
               sessionID: input.sessionID,
-              action: "lazy-bind-failed",
-              error: err instanceof Error ? err.message : String(err)
+              action: "deny",
+              source: "lazy-bind-failed",
+              error: errMsg,
+              throttled: alreadyNotified
             });
+            denied = new DeniedError(reason);
             return;
           }
         }

package/install.sh

@@ -595,6 +595,91 @@ if [ -f ".codeforge/.dev-marker" ] && [ -f "scripts/dev-sync.mjs" ]; then
 fi
 
 
+# Step 9/9: 安装后自检（ADR:worktree-guard-fail-loud Fix D）
+# 在「验证清单」前主动跑 4 项关键依赖检查；warn 不阻塞 install，但用户能立刻看到红绿
+verify_install() {
+  local has_warn=0
+  log "Step 9/9: 安装后自检"
+
+  # 1. git 版本（worktree 隔离硬依赖；需要 >= 2.5）
+  if command -v git >/dev/null 2>&1; then
+    local gv major minor
+    gv="$(git --version 2>/dev/null | awk '{print $3}')"
+    major="$(printf '%s' "$gv" | cut -d. -f1)"
+    minor="$(printf '%s' "$gv" | cut -d. -f2)"
+    # 数值校验失败时按 0 处理，避免 "[: : integer expression expected"
+    case "$major" in *[!0-9]*|"") major=0 ;; esac
+    case "$minor" in *[!0-9]*|"") minor=0 ;; esac
+    if [ "$major" -gt 2 ] || { [ "$major" -eq 2 ] && [ "$minor" -ge 5 ]; }; then
+      ok "git $gv  (>= 2.5 ✓ worktree 支持)"
+    else
+      warn "git $gv 版本太旧（worktree 需要 >= 2.5）；worktree 隔离将失效（写操作会被 DENY）"
+      has_warn=1
+    fi
+  else
+    warn "git 未安装；worktree 隔离将失效（写操作会被 DENY）"
+    has_warn=1
+  fi
+
+  # 1b. git 仓库探测（reviewer 追加：Fix D 补 git rev-parse --git-dir 检查）
+  # 全局模式下当前目录通常**不是** CodeForge 自己的项目，因此只 info 提示；
+  # 项目模式下若当前目录不是 git 仓库，必然影响 worktree 隔离 → warn。
+  if command -v git >/dev/null 2>&1; then
+    if git rev-parse --git-dir >/dev/null 2>&1; then
+      ok "当前目录是 git 仓库（git rev-parse --git-dir ✓）"
+    else
+      if [ "$MODE" = "project" ]; then
+        warn "当前目录不是 git 仓库（git rev-parse --git-dir 失败）；worktree 隔离将失效"
+        warn "  解决：\`git init && git add -A && git commit -m 'initial'\`"
+        has_warn=1
+      else
+        log "  ↳ 当前目录非 git 仓库（全局安装无碍；进入实际项目使用时该项目需是 git 仓库）"
+      fi
+    fi
+  fi
+
+  # 2. opencode 版本
+  if command -v opencode >/dev/null 2>&1; then
+    local ov
+    ov="$(opencode --version 2>/dev/null || echo unknown)"
+    ok "opencode $ov"
+  else
+    warn "opencode 未在 PATH 中；CodeForge 无入口可用（请先安装 opencode）"
+    has_warn=1
+  fi
+
+  # 3. plugin 注册检查
+  local cfg
+  cfg="$(opencode_cfg_path)"
+  if [ -f "$cfg" ] && grep -q '"codeforge"' "$cfg" 2>/dev/null; then
+    ok "plugin 已注册：$cfg"
+  else
+    if [ "$MODE" = "project" ]; then
+      log "  ↳ 项目级配置 $cfg 未包含 codeforge entry（如需用 codeforge agent，请编辑该文件）"
+    else
+      warn "plugin 未在 $cfg 中注册"
+      has_warn=1
+    fi
+  fi
+
+  # 4. dev-marker 误用检测（仅 global 模式有意义）
+  if [ "$MODE" = "global" ]; then
+    if [ -f "$HOME/.codeforge/.dev-marker" ] || [ -f "$HOME/.dev-marker" ]; then
+      warn "检测到 \$HOME 附近有 .codeforge/.dev-marker —— 可能导致所有项目让位到本地 plugin"
+      warn "  建议删除：rm \$HOME/.codeforge/.dev-marker"
+      has_warn=1
+    fi
+  fi
+
+  if [ "$has_warn" -eq 0 ]; then
+    ok "${C_BOLD}自检通过${C_RESET}"
+  else
+    warn "${C_BOLD}自检发现 $has_warn 项问题，详见上方${C_RESET}"
+  fi
+}
+verify_install
+
+
 # 验证清单
 hr
 ok "${C_BOLD}CodeForge v${CF_VERSION} 安装完成${C_RESET}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andyqiu/codeforge",
-  "version": "0.5.15",
+  "version": "0.5.17",
   "description": "CodeForge — opencode 的零侵入扩展包",
   "type": "module",
   "private": false,