用途：修复 Git worktree 中索引与提交失败，典型报错为 error: invalid object … 与 error: Error building trees，常出现在长时间 pre-commit（例如 npm run lint）之后，此时暂存区看似正常但 git write-tree 失败。
根因：索引引用了本仓库对象数据库中不存在的 blob OID。worktree 与主仓库共享同一个 .git/objects 存储，该处损坏或 GC 会影响所有 worktree。常见幻影条目来源包括 IDE 后台 git status / git diff 刷新陈旧索引，以及路径曾暂存、blob 后被 git gc 清理而索引仍引用。
诊断：macOS 可用 sudo fs_usage -w -f filesys | grep 'worktrees/<name>/index'，在另一终端触发钩子，观察索引上的 WrData 与 rename。
Husky 二分排查：先重建正常索引，调试时避免盲目 git add -A；逐个禁用 pre-commit 步骤（从耗时最长的 npm run lint 开始）；可用 sh -x .husky/pre-commit 2>&1 | tee /tmp/precommit.trace 追踪。紧急时 HUSKY=0 git commit，但须明确后续在 CI 或本地补跑相同检查。
手动修复（规范做法）：在受影响 worktree 仓库根目录执行 git read-tree HEAD、git add -A、git write-tree >/dev/null && echo "index OK"。若 write-tree 仍失败则不要提交。最小暂存可用 git add <paths> 替代 add -A。丢弃单个坏路径：git rm --cached -f --ignore-unmatch <path>，再 git add -A 与 git write-tree。
仓库健康检查：git fsck --no-progress 2>&1 | head -50；缺失 blob 时从完整远端 git fetch，修复可能需主仓库对象存储。
预防：在 .vscode/settings.json 设 git.autoRefresh: false；多 worktree 共享对象库时注意 git gc。
限制与注意：不要在钩子内重建索引（read-tree + add -A 于 trap 中）会与 IDE git 进程竞争；不要强制添加被忽略的密钥目录，除非用户明确要求；任何可能打开编辑器的 Git 步骤可结合 kmcp-dev-git-editor-safe；修复后按需运行 npm run lint / npm run handoff。