gsd-core 修复 gsd-code-fixer 同分支检出冲突：基于 `git worktree add -b` 的 gsd-reviewfix 隔离分支机制

导读

本文剖析 gsd-core 中 PR #2990 的一次关键缺陷修复：gsd-code-fixer 代理在工作树（worktree）隔离场景下，因 Git 拒绝在同一仓库的两个 worktree 中同时检出同一分支而启动即失败的问题。通过阅读本文，你将掌握该修复引入的gsd-reviewfix/临时分支创建、--ff-only快进合并清理、崩溃恢复哨兵（recovery sentinel）以及workflow.use_worktrees配置开关等一整套可落地的 Git worktree 隔离与清理方案，并能从源码与回归测试中验证其行为。

一、修复背景：gsd-code-fixer 与代码审查修复流程

gsd-core 的/gsd:code-review命令先由 gsd-code-reviewer 代理审查阶段代码并产出REVIEW.md；当用户追加--fix标志时，工作流会委托给 code-review-fix.md，由其 spawn gsd-code-fixer 子代理读取REVIEW.md的逐条 finding（CR-*/BL-*/WR-*/IN-*），智能地应用修复、逐条原子提交，并产出REVIEW-FIX.md报告。

关键约束在于：gsd-code-fixer 是一个在后台进行 git 提交的代理，如果它直接在主工作树上操作，就会与前台会话竞争共享的 HEAD、索引和磁盘文件（即 issue #2686 描述的竞态）。因此代理必须在独立 worktree中完成所有读取、编辑与提交，这就是本文修复所在的隔离机制。

二、Bug 本质：Git 默认拒绝在两个 worktree 检出同一分支

修复前的代理指令执行的是：

git worktree add "$wt" "$branch"

其中$branch是用户当前检出的分支。Git 出于安全设计，默认禁止在同一个仓库的两个 worktree 中同时检出同一个分支（否则两个工作树会争抢同一份 HEAD 与索引）。由于用户的主 checkout 已经持有$branch，这条命令必然失败——而且失败发生在代理能够做任何修复工作之前，整个 code-review-fix 流程直接被卡死。这正是 changeset 中 "the agent now creates a new gsd-reviewfix/ branch" 所对应的原始缺陷（#2990）。

三、修复方案：git worktree add -b创建 gsd-reviewfix 临时分支

修复的核心思路是：不再把 worktree 挂到用户分支上，而是从当前分支尖端派生一条全新的临时分支，再让 worktree 检出这条新分支。这样 worktree 与用户 checkout 各持一条分支，互不冲突；临时分支与$branch共享创建时刻之前的历史，因此 worktree 内的提交可以在清理阶段快进合并回用户分支。

代理定义 agents/gsd-code-fixer.md 中 setup_worktree 步骤的完整逻辑如下：

# 从当前分支派生临时分支名（phase 编号 + PID，保证并发唯一） reviewfix_branch="gsd-reviewfix/${padded_phase}-$$" # 关键修复（#2990）：-b 创建新分支并挂载 worktree， # 而不是直接检出用户已经持有的 $branch git worktree add -b "$reviewfix_branch" "$wt" "$branch"

配套的 worktree 路径同样经过了专门设计（#2647）：仓库相对路径，落在.claude/worktrees/目录下，与 harness 托管的 executor worktree 共用目录，天然被.claude/的.gitignore规则覆盖，也处于代理会话的权限允许范围内：

main_repo="$(git worktree list --porcelain | awk '/^worktree / { sub(/^worktree /, ""); print; exit }')" wt="$main_repo/.claude/worktrees/rf-${padded_phase}-$$-$(date +%s)" mkdir -p "$wt" git worktree add -b "$reviewfix_branch" "$wt" "$branch"

其中$$（PID）+$(date +%s)（纪元秒）后缀保证了同一阶段并发运行多次时路径互不冲突，替代了旧实现中在 Windows/Git Bash 下不可移除、且落在项目树之外的/tmpmktemp 路径。

值得注意的防御性设计：padded_phase会被插值进 worktree路径和 git分支名，因此代理指令在插入前先做一次下沉校验，只接受^[0-9]+[A-Z]?(\.[0-9]+)*$的规范阶段号语法（如02、36.14、12A），拒绝../、空格与 shell 元字符，防止路径穿越或分支名注入（#2647 的 defense-in-depth）。

四、清理尾段：--ff-only快进合并与事务性四步清理

修复提交后，代理必须把成果"归还"给用户的$branch。清理尾段是严格有序的四步事务，定义在 agents/gsd-code-fixer.md 的 Cleanup tail 小节：

# Step 1：在主仓库中把用户分支快进到临时分支（#2990） if git -C "$main_repo" merge --ff-only "$reviewfix_branch" 2>&1; then ff_status=0 else ff_status=$? echo "WARN: could not fast-forward $branch to $reviewfix_branch (exit $ff_status)." echo " The temp branch $reviewfix_branch is preserved for manual merge." fi # Step 2：移除 worktree git worktree remove "$wt" --force # Step 3：仅在快进成功后删除临时分支；失败则保留供人工合并 if [ "$ff_status" -eq 0 ]; then git -C "$main_repo" branch -D "$reviewfix_branch" || true fi # Step 4：最后删除恢复哨兵 rm -f "$sentinel"

四个步骤的顺序不可颠倒，原因如下：

1. --ff-only确保合并是纯快进，若用户在此期间并发提交导致分支分叉，合并会响亮地失败而不是静默改写历史——此时临时分支被保留，供用户手动检视与合并；
2. worktree 必须在删除临时分支之前移除（反过来会在中断时留下无哨兵引用的孤儿 worktree，正是 #2839 的原始 bug）；
3. 临时分支只有在快进成功后才删除；
4. 哨兵只有在git worktree remove成功后才删除，从而保证从编排器视角看整个清理是原子的。

五、崩溃恢复：.review-fix-recovery-pending.json哨兵机制

由于清理尾段发生在"最后一次提交之后、git worktree remove之前"，进程若在此窗口内被系统重启或 OOM kill 中断，就会留下孤儿 worktree 与未合并的临时分支。为此代理在git worktree add成功之后、清理开始之前，于阶段目录写入恢复哨兵（#2839，并经 #3001 CR 增强）：

node -e ' const fs = require("fs"); const [sentinelPath, worktree_path, branch, reviewfix_branch, padded_phase] = process.argv.slice(1); fs.writeFileSync(sentinelPath, JSON.stringify({ worktree_path, branch, reviewfix_branch, padded_phase, started_at: new Date().toISOString() }, null, 2)); ' "$sentinel" "$wt" "$branch" "$reviewfix_branch" "$padded_phase"

哨兵路径为${phase_dir}/.review-fix-recovery-pending.json，记录worktree_path、branch、reviewfix_branch、padded_phase与started_at。其中reviewfix_branch字段是 #3001 的 CR 补充——若先前运行死在git worktree remove之后、git branch -D之前，仅记录 worktree 路径无法清除幸存下来的孤儿分支。

下次运行/gsd:code-review --fix（或/gsd:resume-work、/gsd:progress）若发现哨兵已存在，会先执行自愈恢复：解析 JSON 取出两个字段，best-effort 地git worktree remove --force清除孤儿 worktree、git branch -D清除孤儿临时分支，再删除旧哨兵并重新开始。这样修复流程对中断具有幂等自愈能力。

六、配置开关：workflow.use_worktrees退出隔离

并非所有用户都需要 worktree 隔离。代理同样遵循workflow.use_worktrees配置（#2825）——这是与/gsd:execute-phase、/gsd:quick等兄弟 writer 工作流一致的可文档化退出通道。该配置位于 docs/CONFIGURATION.md：

当取值为false时，gsd-code-fixer不会创建任何 worktree：wt="."、reviewfix_branch="$branch"、不写哨兵、清理尾段直接 early-exit。其安全性依据有二：其一，用户显式退出过 worktree，就绝不能违背其意图再创建；其二，手工 worktree 内没有node_modules，无法安全运行项目门禁，直接在主 checkout 编辑/提交反而是安全路径（也规避了 Windows 上 junction/reparse point 被rm -rf递归删除真实node_modules的隐患）。详见功能文档 worktree-toggle.md。

读取该标志的时机也有讲究：setup_worktree步骤运行于规范的 gsd_run launcher preamble 被 source之前，此时调用 CLI 属于未定义行为，因此代理直接以node解析.planning/config.json：

USE_WORKTREES=$(node -e ' try { const fs = require("fs"); const p = (process.env.GSD_PROJECT_DIR || process.cwd()) + "/.planning/config.json"; const cfg = JSON.parse(fs.readFileSync(p, "utf8")); process.stdout.write(String((cfg.workflow && cfg.workflow.use_worktrees) ?? true)); } catch { process.stdout.write("true"); } ')

七、回归测试保障：source-text-is-the-product

该修复配套了完备的回归测试，折叠在 tests/agent-frontmatter.test.cjs 的folded:bug-2990-code-fixer-worktree-branch套件中。测试遵循项目"源码文本即产品"（source-text-is-the-product）的测试哲学：gsd-code-fixer 的指令文本就是运行时实际执行的内容，因此直接解析代理 markdown 中的 bash 代码块并断言其形态，就是在测试已部署的运行时契约。

测试覆盖的关键断言包括：

• 解析所有git worktree add调用，断言不存在裸检出现象（attachesToBareBranch违规列表为空），且存在使用-b "$reviewfix_branch" "$wt" "$branch"的规范调用（#2990）；
• 断言 worktree 路径是仓库相对路径、位于.claude/worktrees/rf-之下、且同时携带$$与$(date +%s)双后缀保证并发唯一（#2647）；
• 解析清理尾段 bash 块，断言恰好一次merge --ff-only针对$reviewfix_branch、恰好一次git branch -D针对$reviewfix_branch，且 merge 必须先于branch 删除执行；
• 断言恢复哨兵 JSON 必须同时包含reviewfix_branch与worktree_path字段（#3001 CR），恢复脚本必须通过parsed.reviewfix_branch读取该字段，并在哨兵检测与rm -f "$sentinel"之间调用git branch -D "$prior_branch"；
• 同文件中的 #2686 套件进一步断言git worktree add必须出现在任何分支切换git checkout与 commit 命令之前，且指令必须包含git worktree remove清理。

这些断言把"同分支检出失败""孤儿 worktree""孤儿临时分支"等历史 bug 逐一定格为不可回归的契约。

八、底层关联：worktree-base-ref 退化检查

gsd-code-fixer 的手工 worktree 之外，仓库还有一套自动化的 worktree 基线检测逻辑，见 src/worktree-base-ref.cts 的evaluateWorktreeBaseDegrade：当本分支 HEAD 与origin/HEAD（harness 创建并行 worktree 的 fork 基点）发生漂移时，系统会打印警告并自动降级为顺序执行，避免基线错配。该模块通过--mode区分harness-worktree与orchestrator-worktree两种隔离来源，并支持.claude/settings.local.json中worktree.baseRef: "head"的无覆盖写入（gsd-tools worktree set-baseref）。它回答了"哪些运行时由 GSD 自己创建 worktree、哪些由 harness 创建"的能力边界问题，与 gsd-code-fixer 的手工 worktree 互为补充。

九、总结

PR #2990 的修复看似只有一行-b参数，实则牵动了整条隔离链路的重新设计：从"拒绝同分支双检出"的 Git 语义出发，建立了gsd-reviewfix/${padded_phase}-$$临时分支 +--ff-only快进归还 + 有序四步清理 + 崩溃恢复哨兵 +use_worktrees退出开关的完整闭环，并由 agents/gsd-code-fixer.md 的 bash 契约与 tests/agent-frontmatter.test.cjs 的文本级断言双重锁定。对于任何在 AI 代理工作流中做 git 隔离的工程实践，这套"派生临时分支 → 隔离执行 → 快进归还 → 哨兵自愈"的模式都值得直接借鉴。