编程 Agent 到开发者的接管检查点：工作树证据、未决假设与续作确认

编程 Agent 说“代码基本完成，只差一个测试”时，开发者仍不知道这句话对应哪个提交、哪些未跟踪文件、哪条命令真的执行过，也不知道 Agent 的假设是否已经失效。直接接着编辑，可能覆盖尚未保存的改动；让另一个 Agent 继续，又可能重复迁移、生成文件或外部写操作。接班点的目标不是保存聊天全文，而是把“当前可续作状态”冻结为能够独立验证的工程制品。

这与长任务 Agent 的持久化工作流不同：后者让运行时自动恢复步骤，本文处理 Agent 把未完成编码责任交给具体开发者的瞬间。它也不替代Agent 人工复核队列的业务审批，接收人确认的是工作状态与下一步责任，不是批准高风险操作。

冻结 handoff.v1 版本化合同

handoff.v1 至少记录 taskId、checkpointGeneration、producerRunId、repositoryId、baseCommit、headCommit、worktreeTree、indexTree、未跟踪文件清单摘要、补丁与对象包摘要、路径租约引用、最后编辑时间、已完成 claim、未决假设、未执行命令、已知失败、建议下一步和禁止动作。每项证据使用内容摘要寻址，整份清单再生成 checkpointDigest；任何字段变化都产生新 generation，不能覆盖旧记录。

schema: handoff.v1
taskId: DEV-1842
generation: 7
repository: {base: 91b2..., head: a771..., worktreeTree: 8e43...}
artifacts:
  patch: {uri: artifact:patch/4c1f..., sha256: 4c1f...}
  gitBundle: {uri: artifact:bundle/920a..., sha256: 920a...}
claims:
  - {id: AC-3, state: evidenced, receipt: test/72d9...}
  - {id: AC-4, state: open, reason: needs_product_decision}
next: {action: choose_null_semantics, forbidden: [merge, deploy]}

worktreeTree 不能只取 HEAD。暂存区、未暂存文件、重命名、删除、可执行位、符号链接和未跟踪文件都要进入快照；被 .gitignore 排除的密钥和构建缓存只登记“已排除规则及原因”，不得打包。可在临时 index 中读取 HEAD、加入允许路径并用 git write-tree 得到树对象，避免改动开发者的真实 index。私有 checkpoint ref 通过 git update-ref <ref> <new> <old> 做比较并交换，拒绝迟到 Agent 覆盖更新。

Git bundle 能携带可达对象与 refs，但不会自动保存任意脏工作树，因此清单还需独立补丁、未跟踪文件归档和二进制摘要。先在临时干净 clone 中执行 git bundle verify，再应用补丁并核对最终 tree；不能恢复的 Git LFS 对象、submodule 提交或外部生成源必须列为 blocker，而不是留一句“本机可用”。W3C PROV 的 entity、activity、agent 关系可用于表达谁生成哪个制品、依据哪个仓库状态，但真正验收仍以摘要和重放结果为准。

只交付已证明的完成度

每条“已完成”都要引用 acceptance claim 和验证回执。命令证据由编程 Agent 命令记录证据与脱敏提供；接班清单只引用 receipt ID、覆盖的 tree digest 与结论，不复制可能含敏感数据的日志。故障调查则引用编程 Agent 调试复现包的 bundle ID，避免接班协议重新发明环境采集。

未决事项必须是可决策条目，而不是“还有一些边界情况”。每项登记 owner、两到三个互斥选项、现有证据、阻塞 claim、最迟决定时间和默认安全动作。Agent 不确定字段为空还是缺失时，应明确“未决定，禁止迁移”，而不是选择一个实现后在摘要中弱化风险。Agent 故障恢复顺序仍决定失败后是否重试；handoff 只如实冻结已经发生的尝试和剩余责任。

接收动作使用独立的 handoff-accept.v1：开发者提交身份、读取的 checkpointDigest、接受的 generation、选择的下一动作与新的责任期限。服务端仅当 task 当前 generation 完全相同时接受；若 Agent 在开发者阅读期间又写入文件，旧确认返回 STALE_CHECKPOINT。路径写集仍引用并行工作协议的 lease，接班不能暗中扩大所有权，也不能以“人工接手”为由绕过Agent 委派协议中的权限边界。

用故障注入证明接班包可恢复

测试不能止于 schema 校验。先让 Agent 修改已跟踪文件、增加未跟踪 fixture、删除一个文件并改变可执行位，在生成清单后再偷偷编辑其中一行；接收必须因 tree digest 不一致失败。再分别注入缺失 bundle 对象、损坏补丁、submodule 不可达、LFS 对象缺失、归档中命中测试密钥，以及开发者用旧 generation 确认，期望结果均为阻断且指出确切制品。

恢复演练从空目录和最小凭证开始，只使用 handoff 清单声明的来源重建工作树，重跑允许的验证命令，并由另一名执行者判断下一步。若必须访问 Agent 的聊天历史、本机绝对路径或未登记缓存才能继续，说明检查点不完整。另做一次迟到写入演练：开发者已接受 generation 7 后，旧 Agent 尝试发布 generation 6 的修订，update-ref 与任务状态机都必须拒绝它。

量化验收门与可逆发布

强制接管前设置硬门：允许范围内的变更路径和未跟踪文件摘要覆盖率为 100%；baseCommit、submodule 与关键制品均可达；补丁、bundle 和清单摘要校验错误为 0；秘密扫描高危命中为 0；所有完成 claim 都有绑定当前 worktreeTree 的回执；所有 open claim 都有 owner 与安全默认动作；在干净 clone 的恢复成功率为 100%，p95 恢复到首条验证命令不超过 10 分钟。随机抽取 20 个检查点时，未解释 diff 必须为 0，旧 generation 接受与迟到写入的拦截率必须为 100%。

上线先以 shadow 模式为现有暂停流程生成 handoff.v1，不改变责任归属，连续两周比较人工重建结果；再只对低风险仓库的 10% 接班启用显式 accept，达到上述门槛后逐级扩大。开关按仓库和合同版本控制，旧客户端不识别 v1 时只能走旧流程，不能把未知字段当作已确认。

回滚时关闭强制 accept、停止创建新 generation，并把尚未接收的任务恢复到原人工队列；已经接受的责任记录保持不可变，不能因回滚删掉审计链。checkpoint refs 与制品按保留期延迟清理，恢复工具同时保留当前和前一合同解析器。这样撤回的是执行门禁，不是接班证据，开发者仍能准确回答自己从哪个状态接手、接受了什么，以及哪些工作从未完成。