# 高级用法：run checkpoint 与续跑

> **权威来源**：[run 现场 checkpoint 续跑设计](https://github.com/Athenavi/chiron/blob/master/docs/run-checkpoint-design.md)。
> **状态**：**已落地并跨进程验证**（回合末落盘 → 重启后能续）。

## 它解决什么

一次 run 可能很长。进程重启、实例切换、或用户主动恢复时，**不能从头再来** ——
要从「上次的现场」继续，且**不能重复副作用**。

## 代码在哪

```
python-engine/app/agent/checkpoint.py   407 行 —— 落盘与恢复
python-engine/app/agent/resume.py       461 行 —— 恢复流程
python-engine/app/agent/runtime.py      _save_checkpoint（回合末落盘）
python-engine/app/run_registry.py       运行注册表
```

## 恢复不是"取最新"

恢复有**多个分支**，其中一条值得特别注意：

> 若标记**跨过了一个更晚的已完成回合** ⇒ **保留整段 WAL 并发 warn**，而不是直接跳到最新。

也就是说：**宁可多留证据、并发警告，也不静默地丢掉一段历史**。
这与本仓库"证据优先"的一贯做法一致。

## 三条不变量

1. **回合末落盘**：checkpoint 的写入点是**回合边界**，不是任意时刻 —— 这样恢复的语义才明确。
2. **副作用要幂等**：恢复后重放的部分不能重复产生外部效果（靠幂等键，见 `app/queue/idempotency.py`）。
3. **恢复要留痕**：走了哪条分支、为什么，要能被审计读到，而不是只写在日志里。

## 与"文件级回退（rewind）"的区别

- **checkpoint / 续跑**（本页）：**已实现**，是"往前继续"。
- **文件级回退（rewind）**：**未实现**，是"往回撤销"（事务化 + 覆盖率显式 + 冲突类型化）。
  它是差距分析里"值得追"的新能力，**需迁移**；形态要改成「引擎侧持久化 + 网关端点」，
  **不照搬会话旁挂目录**。

## 延伸阅读

- [会话](Core-Sessions.md) · [队列与幂等](Core-Engine.md)
- [生产：多实例](Production-Multi-Instance.md) —— 实例切换时的续跑

---

_本页由仓库内 `docs/wiki/` 同步生成（`scripts/sync_github_wiki.py`）。**请不要直接编辑本 wiki** —— 改动会下次同步时被覆盖；请改仓库里的对应文件。_