bug(worktree): 自动回收会删除被 index flags 隐藏的未提交修改 [P1]

[tt-a1i]

解决什么问题

子 Agent 的 worktree 中，如果 tracked 文件被该 worktree 的 index 标记为 assume-unchanged 或 skip-worktree，本地修改可以不出现在 git status 中。OpenPI 的自动回收目前把这类工作区判成没有产出，随后执行不带 --force 的 git worktree remove，仍然能够删除修改文件的唯一副本。

这是特定 worktree index 的状态，不是声称这些标记会从父 checkout 自动继承，也不是普通 ignored 文件问题。OpenPI 已单独保留 ignored 文件；缺口是被 index 标记隐藏的 tracked 修改。

价值是什么

自动清理必须保留无法证明可丢弃的内容。“Git status 为空”和“不使用 force”都不足以证明目录里没有需要保留的工作。补齐检查可以避免子 Agent 执行结束后的静默数据丢失。

验证边界

检查日期：2026-09-08。OpenPI 固定为 ed9dbc1018f890fd54375f5371990ddfee8af5df。

• 已执行事实：使用系统 git version 2.50.1 (Apple Git-155)，在独立临时 Git 仓库中逐一设置两种标记，执行 OpenPI 清理依赖的 Git 检查和相同的 git worktree remove。两种情况都返回删除成功，修改文件随后不存在。
• 已执行 OpenPI 生产函数：使用 Node v26.3.0 直接导入上述 checkout 的 extensions/shared/worktree.ts，在第二组独立临时 fixture 中调用 reclaimWorktree(repo, { path, branch, baseSha })。两种标记均得到 removed: true, branchDeleted: true, dirty: false, ignored: false, commits: 0，修改文件和工作区目录实际被删除，分支也不存在。
• 未验证范围：没有启动完整 OpenPI 子 Agent/Workflow 生命周期，没有调用模型，也没有运行社区插件。
• 全部文件均为合成 fixture，没有读取或删除真实项目数据。

最小复现

以下命令只创建和操作新建临时目录内的测试仓库；两个 worktree remove 是复现中有意执行的删除动作。保留测试主仓库以便检查结果。

audit_root="$(mktemp -d "${TMPDIR:-/tmp}/openpi-index-flags.XXXXXX")"
git init -q "$audit_root/repo"
git -C "$audit_root/repo" config user.name 'Local Fixture'
git -C "$audit_root/repo" config user.email 'fixture@example.invalid'
printf 'base\n' > "$audit_root/repo/tracked.txt"
git -C "$audit_root/repo" add tracked.txt
git -C "$audit_root/repo" commit -qm fixture
audit_base="$(git -C "$audit_root/repo" rev-parse HEAD)"

for audit_flag in assume-unchanged skip-worktree; do
  audit_wt="$audit_root/$audit_flag"
  git -C "$audit_root/repo" worktree add -q -b "probe-$audit_flag" "$audit_wt" HEAD
  printf 'ONLY COPY OF SYNTHETIC USER CHANGE\n' > "$audit_wt/tracked.txt"
  git -C "$audit_wt" update-index "--$audit_flag" tracked.txt

  git -C "$audit_wt" status --porcelain=v1 --untracked-files=all
  git -C "$audit_wt" ls-files --others --ignored --exclude-standard -z
  git -C "$audit_wt" rev-parse --verify HEAD
  git -C "$audit_wt" symbolic-ref --quiet --short HEAD
  git -C "$audit_root/repo" merge-base "$audit_base" "$audit_base"
  git -C "$audit_root/repo" rev-list --count "$audit_base..$audit_base"
  git -C "$audit_wt" ls-files -v

  git -C "$audit_root/repo" worktree remove "$audit_wt"
  test ! -e "$audit_wt/tracked.txt" && printf '%s: modified file was removed\n' "$audit_flag"
done

观察到的关键结果：

检查	assume-unchanged	skip-worktree
status 输出	空	空
ignored inventory	空	空
HEAD / merge base	等于创建基线	等于创建基线
新增 commit 数	0	0
ls-files -v	h tracked.txt	S tracked.txt
worktree remove	exit 0	exit 0
修改文件仍存在	否	否

OpenPI 生产函数的直接结果

对上述等价 fixture，以当前源码直接执行：

const cleanup = await reclaimWorktree(repo, { path: worktreePath, branch, baseSha });

两种标记得到相同的核心回执和独立文件检查结果：

{
  "cleanup": {
    "removed": true,
    "branchDeleted": true,
    "detached": false,
    "commits": 0,
    "dirty": false,
    "untracked": false,
    "ignored": false
  },
  "worktreeExistsAfter": false,
  "modifiedFileExistsAfter": false,
  "branchesAfter": ""
}

当前代码路径

• reclaimWorktree 的 status 与 ignored 检查 没有读取 index flags。
• 基线与 commit 检查 在上述 fixture 中均通过。
• 保留条件与 remove 仅因 dirty、ignored 或 detached 保留，这里三者都不成立。

社区实现启发

@narumitw/pi-worktree 的当前实现（MIT，固定 09d0f4d4d8d31f506e6f2478a0060be5f5c31c09）提供了可借鉴的具体机制：

• 额外执行 git ls-files -v -z。
• 把 assume-unchanged 与非正常 sparse 管理的 skip-worktree 路径列为受保护数据。
• 存在受保护数据时拒绝删除。

建议借鉴清理前的数据保护机制，不引入另一套 worktree 管理器，也不为了检查而清除用户的 index 标记。

最小验收

• 带 assume-unchanged 的 tracked 修改在自动回收后文件仍完整保留，回执说明 index 标记造成的不确定性。
• 带 skip-worktree 的 tracked 修改同样保留；不能简单把所有 skip-worktree 都当成安全 sparse checkout。
• Index inventory 读取失败、截断或格式无法识别时保留 worktree，不能声称清理成功。
• 若支持回收正常 sparse checkout，必须单独证明未落盘路径与被隐藏本地内容的边界，不能影响上述保护。
• 检查不修改 index，不执行 reset、clean、checkout 或强制删除来“修复”状态。
• 对 reclaimWorktree 补实际临时 Git 仓库回归测试，分别断言文件内容、清理回执与分支状态；现有 ignored/untracked/committed/detached 保护继续通过。
• bun run check、bun run test 通过。

研究记录：Pi 社区能力研究与候选清单（2026-09-08）。源码证据、运行验证与采用决策分别记录。

[testikun]

我来认领 worktree 自动回收的 hidden-index 修改保护切片。

技术方案：在 reclaimWorktree 的 remove 前，通过临时 GIT_INDEX_FILE 复制当前 index，清除 assume-unchanged/skip-worktree 视图后重新计算 tracked diff；把隐藏的修改、未跟踪文件、ignored 文件和已提交分支分别纳入现有 dirty/commits 证据，任何无法证明干净的 worktree 都不自动删除。原 index 不被改写，保留原始错误与清理路径；补充两类 index flag、空目录、提交后清理和失败回滚测试。

[testikun]

开始实现，基线为 upstream/main a3edee2。复核验收后收敛此前方案：直接只读执行有界、NUL 分隔的 git ls-files -v -z；assume-unchanged、skip-worktree、未知格式、截断或读取失败均保留 worktree 并说明不确定性。不再引入临时 index 复制/清旗流程，也不尝试自动判断 sparse checkout 安全性。保持现有 ignored/untracked/committed/detached 保护。验证使用真实临时 Git fixture，分别断言内容、index 字节与分支状态，并执行完整 check/test 及消融实验。技术记录将随 PR 提交到 docs/design/WORKTREE_INDEX_SAFETY.md。

[testikun]

实现已完成并提交 PR #487：只读检查 git ls-files -v -z，隐藏 flag、异常/截断/未知 inventory 均 fail-closed 保留 worktree；含临时 Git fixture、index 字节不变断言、设计与消融记录。

[tt-a1i]

结论

官方 dirty-repo-guard 用的是同一把 porcelain 尺子，也会看不见本帖的 assume-unchanged / skip-worktree 隐藏修改。

事实（源码，未安装未运行）

earendil-works/pi 6160683 dirty-repo-guard.ts blob 5357464e：只跑 git status --porcelain。非空才确认换会话 / fork；code !== 0 直接放行。它挡的是会话动作，不是 worktree 回收，但仪器同类：porcelain 空 ≠ 没有不可丢的工作。

本帖已证明这两种 index flag 对 status / 无 --force 的 worktree remove 隐形。若有人把官方脏仓门搬进 OpenPI，必须复用本帖的 ls-files -v -z 证据，不能只抄 example。

会话门本身挂 #193，不是本 bug 的修复范围。未运行该 example。

本地深读：docs/research/EXPERIMENT_HANDOFF_GATES_2026-09-09.md。

[tt-a1i]

结论

a9b40f0 与 origin/main 0d17f45 都还没有 ls-files -v 门。PR #487 仍 OPEN（testikun/openpi 1151b75）。origin 相对本树只多了 #258 的 formatWorktreeCleanupWarning；reclaim 谓词没变。

Pi-native 检查该观察 index flag，不是文件字节，也不是再跑一遍 git diff。

事实（源码 + 本机 git fixture，未 pi install，未跑 Session）

本机 git 2.50.1 (Apple Git-155)，与帖面同一版本。独立临时仓里两种旗都让：

• 工作区 hash-object ≠ index blob（文件字节已变）
• status --porcelain=v1 与 ignored ls-files 为空
• git diff / git diff HEAD / git diff --binary <baseSha> / git diff --cached 都是 0 字节
• ls-files -v：h / S
• ls-files -t：assume-unchanged 仍报 H（与干净 cached 同形），只有 skip-worktree 报 S
• 无 --force 的 worktree remove exit 0，唯一副本被删

因此同一把尺子还会让 git_diff、/lg、Workflow prepareWorktreeHandoff 的空 patch（ok: true 然后 reclaim 删除）、replay fingerprint 的 git diff HEAD 一起撒谎。handoff 失败才会挡住回收；隐藏修改让 handoff 成功。

Plan Mode：git ls-files -v 拒（-v 不在 GIT_FLAGS，只在 rg 的 invert-match）；git ls-files -t 放行但看不见 assume-unchanged。不要把 allowlist 当本票修复。

#487 diff 观察 flag（S 或小写或非 H / 截断 / 未知 / 读失败 → preserve；连「旗在、字节未改」也留），不复制 index、不清旗、不猜 sparse。这仍是正确的最小缝。dirty === false 不能当字节干净；#487 测试把隐藏路径的 dirty 锁成 undefined。

Git 拥有 index。Pi 拥有普通 bash。OpenPI 拥有 reclaim / 有界 git_* / /lg。implementer child 的 bash 能在自己的 worktree 上 update-index；只读 child 不能设旗，也不能拦 parent 回收。门必须在 parent reclaimWorktree。

建议

不实现、不 cherry-pick、不新开帖。不要做成第二套 git OS，不要并进 #508 stash checkpoint 或 #509 SSH。cleanup-guard 不读 git。合上 #487 之后，origin 已有的 warning helper 才会第一次有 reason 可投影；今天 removed && branchDeleted 让它闭嘴。

本地深读（未提交）：docs/research/EXPERIMENT_ASSUME_UNCHANGED_472_2026-09-09.md。对照 SHA：本工作区 a9b40f0044ee59c360a6077c1c0bdbdbd30da10b，origin/main 0d17f4577fe31315fe6c95370d251bdb4e2413cf，本树 worktree.ts blob 38dae77c，origin blob 49b8a32a。