Worker Checkpoint Files
读取时机：启动 worker、写 worker prompt、PM 巡检或收口时。
Worker 必须把进度压缩到 .claude/agent-sessions/<session-id>/，避免 PM 为了巡检频繁读取完整日志。这里的 checkpoint 是 PM 巡检文件协议，不等同于 Claude Code 自身用于回退会话的 checkpointing 功能。
1. 文件清单
| 文件 | 写入时机 | PM 用途 |
|---|---|---|
.claude/agent-sessions/<session-id>/METADATA.json |
PM 启动 worker 时创建，通常不由 worker 修改 | 记录 base、worktree、session、runtime profile、provider slot、验证命令和 PR 占位 |
.claude/agent-sessions/<session-id>/STATUS.json |
启动后立即创建，每 10-15 分钟或阶段变化时更新 | 判断运行状态、阻塞、测试进度、最近提交 |
.claude/agent-sessions/<session-id>/RESULT.md |
完成、失败或主动停止时写入 | 快速了解结果、验证、风险和下一步 |
.claude/agent-sessions/<session-id>/PATCH_SUMMARY.md |
有代码或文件 diff 时写入 | 不读完整日志也能理解改动范围和意图 |
2. METADATA.json
METADATA.json 由 PM 的 scripts/spawn-worker.sh 写入，属于静态执行上下文，不替代 worker 的心跳。它用于回答“这个 worktree 从哪里来、由谁跑、用了哪个 provider slot、预期怎么验证、PR 信息待填在哪里”。
PM 可用 scripts/worktree-status.sh 读取 metadata 摘要；清理前 scripts/clean-worktree.sh 也会显示 metadata，辅助判断是否要保留 worktree。
3. STATUS.json
复制 templates/checkpoint-status.json 到 Session Context/STATUS.json 后替换占位符。该 JSON 模板必须保持可被 jq 解析；不要在 JSON 文件内写注释。
status 取值：
| 值 | 含义 |
|---|---|
running |
正在执行 |
blocked |
需要 PM 或用户输入 |
done |
完成，已写 RESULT/PATCH_SUMMARY |
failed |
失败，RESULT 中说明原因 |
stopped |
PM 或用户要求停止 |
supervised 模式下 STATUS 是辅助观察信号（阶段/心跳可缺席）：完成权威是 worker_done → Delivery，PM 的 wave spec 不应把周期性 STATUS 更新当完成判据或巡检依据（badminton-lab Wave 2 三个 supervised worker 均未写 STATUS，Delivery 流转完全正常）。STATUS 轮询只适用于 tmux/terminal-managed 回退路径。
字段经济性规则：
| 字段组 | 必要性 | PM 自动监控 |
|---|---|---|
status、phase、progress、updated_at、heartbeat_interval_seconds |
判断 worker 是否健康、是否过期 | 是 |
task_source、orchestration_goal、wave、branch、worktree、session_id、session_context |
把事件映射回任务、Goal Loop、Wave、分支和 worktree | 是 |
worker_class、runtime.settings_profile_path、runtime.api_provider、runtime.model、runtime.provider_slot |
记录 worker 类型、风险、settings/profile 路径和 provider 并发槽位 | 是 |
orchestration_gate |
判断 session、cwd、branch、worktree 隔离是否通过，避免 PM/worker 逃逸 | 是 |
current_action、next_action |
避免 PM 读取完整日志也能判断是否偏题 | 是 |
needs_input、pm_action_required、blocker、issues |
触发 PM 介入 | 是 |
tests、git.pr_url、git.last_commit_sha、git.last_commit_at、git.commits_since_base |
判断是否进入 review/收口，识别长时间无提交的 worker | 是 |
runtime、scope、files_touched、risks、model_evaluation、last_pm_correction |
PM 手动 review 和 Wave 收口时快速定位风险 | 部分 |
execution_authority |
记录安装门禁模式、显式授权来源、精确授权命令、缺失依赖与机器环境变更 | 是 |
长任务应在完成一个可验证阶段或每 30-60 分钟生成一次可 review 的阶段性 commit，并同步刷新 git.last_commit_sha、git.last_commit_at 和 git.commits_since_base。提交格式仍由项目 git-workflow / git-batch-commit 决定。
Wave worker 应在 bootstrap 时写入 orchestration_goal.id、orchestration_goal.loop_iteration、wave.id、wave.worker_id、wave.role 和 worker_class.type。收口时由 worker 或 PM 填写 wave.exit_state 和 model_evaluation，用于下一 Wave 的 provider/model 路由。
不要把完整日志、长推理、完整环境变量或 token 写入 STATUS.json。runtime.settings_profile_path 只记录 settings 文件路径或 profile 名，不记录 settings 内容、密钥、认证头、完整 settings JSON 或完整 shell env。PM 读取 tmux pane 或 RESULT tail 时应使用 wait-worker.sh 的脱敏输出作为默认观察面。
4. RESULT.md
复制 templates/checkpoint-result.md，在完成、失败或主动停止时写入 Session Context/RESULT.md。RESULT 负责给 PM 快速理解结果，不要重复完整日志。
依赖缺失时，RESULT 必须写明：缺什么、查过哪些已有路径、跳过了哪条验证、是否存在显式授权。验证命令本身不构成安装授权；没有精确授权命令与授权来源时，worker 应进入 blocked，而不是自行修改机器环境。
5. PATCH_SUMMARY.md
复制 templates/checkpoint-patch-summary.md，在有代码或文件 diff 时写入 Session Context/PATCH_SUMMARY.md。PATCH_SUMMARY 负责说明 diff 意图、范围、行为变化、测试和 review 重点。
6. PM 读取规则
PM 巡检优先顺序：
METADATA.jsonSTATUS.jsonRESULT.mdPATCH_SUMMARY.mdgit status --short和git diff --stat- tmux pane、agent view logs 或完整 stream-json 日志
只有 checkpoint 缺失、过期、互相矛盾或报告阻塞时，才读取完整日志。