# Pi 0.86.1 撤回修复与验证记录

验证环境：macOS 26.5.2、arm64、Node.js 23.11.1、Pi SDK 0.86.1。原生路径使用仓库已有的 macOS arm64 helper；本次未修改 Rust 二进制协议。所有 SDK 场景使用离线 faux provider，不请求模型网络。

## 支持范围与行为

- 最低支持版本调整为 Pi 0.86.1，开发依赖与测试夹具固定为 0.86.1，不再承诺 0.84.4 兼容。
- 撤回先停止当前运行，等待输入快照和本轮检查点完成，再选择目标并获取工作区锁。检查点失败会暂停历史，不会撤回上一轮来代替。
- `/undo-cancel` 请求停止当前撤回或重做。Git 默认 120 秒，操作默认 300 秒，分别通过 `PI_UNDO_GIT_TIMEOUT_MS`、`PI_UNDO_OPERATION_TIMEOUT_MS` 调整。
- 取消后等在途任务和并行分支收敛，未提交的操作使用独立预算恢复；cursor 已持久提交时继续完成持久化。不能确认子进程停止时保留隔离，拒绝重建 runtime。
- `/tree` 在适配层区分物理节点、逻辑目标和摘要后的实际逻辑叶。摘要错误或其他扩展取消时，即使缺少 `session_tree` 事件，也会在确认 Pi 导航结束后清理准备事务。
- runtime 重建及退出会等待旧任务与后台持久化。重建时排队文本恢复到编辑器；迟到的 settled 事件不再追加检查点。
- 普通文件原生恢复路径将完整拓扑扫描从 7 次降到 5 次，目录枚举采用有界并发。仍发现忽略目录中的嵌套仓库，保留枚举后与恢复后的复核。
- 沿用 schemaVersion 1 的会话记录、manifest、journal 与 WAL；旧记录仍可读取，不重建缺失或损坏的历史。

长操作和错误的最近一次诊断写入 `<sessionDir>/.pi-undo/diagnostics/<sessionId>-latest.json`，只保留操作 ID、阶段、耗时、已知 Git 子命令名及退出结果，不记录提示词、文件内容、完整参数或进程输出。

## 回归覆盖

真实 SDK 回归包含普通 undo/redo、同一 JSONL 重启重建、第二轮 settled 未结束时撤回、用户节点与根目标导航、摘要导航、摘要失败、其他扩展取消导航。

故障注入包含挂起 Git 和后台后代终止、外部信号终止后清理后代、native helper 取消、TypeScript 部分写入取消、native 写入后验证前取消、cursor 提交前后分流、不可中断任务结束前保留锁、未确认退出时拒绝 runtime 重建，以及丢失事件和排队输入的处理。

验证命令：

```bash
npm run typecheck
npm test
PI_UNDO_DISABLE_NATIVE=1 npm test
cargo test --manifest-path native/pi-undo-fs/Cargo.toml
npm run pack:dry-run
PI_UNDO_LARGE_WORKSPACE=1 PI_UNDO_BENCH_REPORT=/tmp/pi-undo-large-results.jsonl npx vitest run test/large-workspace.test.ts
```

验证结果：

| 检查 | 结果 |
| --- | --- |
| TypeScript 类型检查 | 通过 |
| 标准完整套件 | 593 项通过，4 个按需大型基准用例跳过 |
| 禁用 native helper 的完整套件 | 585 项通过，12 项按条件跳过 |
| Rust 原生测试 | 3 项通过 |
| 大型工作区真实 SDK 基准 | 4 组通过，每组三次撤回／重做 |
| npm 打包清单、Git 空白错误检查 | 通过 |

标准套件包含 native helper 的专项测试；回退套件跳过依赖 native 能力的用例。大型基准单独显式开启并通过，不计入标准套件的通过数。

## 大型工作区测量

每组构建 3,000 或 10,000 个模拟依赖包，每包包含 `lib/index.js`，依赖目录由 `.gitignore` 忽略；工作区不初始化真实 Git 仓库。实际修改 1 或 100 个文件，使用真实 Pi SDK 执行三次 undo/redo，逐文件断言内容与历史状态。下面的耗时仅统计 undo。

| 依赖包数 | 修改文件数 | 三次撤回耗时（毫秒） | 中位数（毫秒） | 每次完整扫描 | 进程峰值 RSS（MiB） | 事件循环延迟 P99（毫秒） |
| ---: | ---: | --- | ---: | --- | ---: | ---: |
| 3,000 | 1 | 1743 / 1769 / 1978 | 1769 | 5 / 5 / 5 | 228 | 13 |
| 3,000 | 100 | 1811 / 1804 / 1800 | 1804 | 5 / 5 / 5 | 354 | 13 |
| 10,000 | 1 | 5366 / 6051 / 6276 | 6051 | 5 / 5 / 5 | 422 | 15 |
| 10,000 | 100 | 5730 / 5666 / 6138 | 5730 | 5 / 5 / 5 | 447 | 15 |

RSS 是同一测试进程连续执行各组时的观测峰值，包含 Pi SDK 和缓存，不是单次撤回的新增内存。事件循环延迟覆盖三轮撤回与重做，不等同于 TUI 的绘制耗时。墙钟数据受文件系统和机器负载影响，因此常规 CI 使用扫描次数和正确性断言，不设置固定耗时门槛。

## 边界

本次测试平台为 macOS arm64，未在 Windows 或 Linux 上重新执行整套验证。不可中断的底层磁盘 I/O 必须实际结束后才安全释放隔离，不能承诺任意磁盘故障都在固定秒数内解除锁。大型工作区仍需要完整扫描；本次没有增加 Rust 目录扫描协议或默认排除目录。