用途
checkpoint-resume 用于让长时间、多单元的自主工作变得持久且可恢复。它把一项大任务拆成若干可追踪的单元，并用一个位于 .ulpi/runs/<id>.json 的状态文件持续记录进度，使得工作可以从任意会话、任意中断之后继续，而不会丢失已完成的成果、也不会重复已完成的部分。
主要能力
持久化状态文件。 状态文件是进度的权威视图，记录维度包括：文档级（createdAt/updatedAt/finishedAt）、每个单元（含状态、dependsOn、note 及时间戳）、每个阶段（phase）、开放事项（openItems）以及最终结果（result）。所有时间戳均为 ISO-8601 UTC。
内置 CLI。 技能附带 scripts/checkpoint.mjs（零依赖 Node），实现完整契约：原子写入、拒绝覆盖活跃检查点、拒绝降级 done 单元、fail-closed 终结、以及恢复集合计算。可用命令包括 init、unit、phase、get、resume、item、finalize、gc。调用点建议追加 || true，因为状态写入不应中止实际工作。该 CLI 在违反契约的操作时会以退出码 2 拒绝执行。
只读状态查看器。 scripts/run-status.mjs 提供不写入的查看能力，可渲染最新运行、指定运行、列表或原始 JSON，并在持久化启动描述符可运行时打印恢复命令；它绝不会伪造命令。
类型化启动描述符。 init 可通过 --launch 持久化精确的重启配方，使运行仅凭状态文件即可恢复，与具体会话无关。描述符为类型化对象 { scriptPath, args? }，init 会在写入磁盘前校验其合法性。
大运行可选事件日志。 默认为单个原子 JSON 文件；对于每次状态转换都重写快照成本过高的计划，可选用 scripts/lib/event-log.mjs，在原子替换同一读取器兼容的 .json 快照前先 fsync 一条 JSONL 转换记录，崩溃后通过 rebuildSnapshot 重放。该路径为显式选用，不改变普通检查点契约。
恢复逻辑。 恢复时先核对持久化集成证据，再计算工作集：done 单元直接跳过；任何非 done 单元（pending/in_progress/blocked/dep_blocked）若其所有 dependsOn 均已 done 则变为可执行，需重建；in_progress 视为被中断，需重做；依赖未完成的单元标记为 dep_blocked 并不予构建，依赖落地后自动恢复可执行。
版本兼容。 新运行以 schemaVersion 2 写入。schemaVersion 1 的运行完全受支持：读取、恢复、终结均逐字节不变；仅在变更写入时做幂等的、仅追加的原地升级（补上缺失的 resolvedItems 并提升版本号），绝不重写既有单元、阶段、开放事项或启动描述符。
使用方式
典型流程为：先判定是新运行还是恢复（若目标指向已存在的运行 id/文件，或用户说 resume/continue，则为恢复，绝不重新初始化）；新运行用 checkpoint.mjs init 创建状态文件；工作中每个单元到达终态后用 checkpoint.mjs unit 更新；恢复时用 checkpoint.mjs resume 计算 skip/eligible/dep_blocked 集合；工作集耗尽后用 finalize 写入终态。对于 git 集成流水线，恢复前应扫描集成引用上可到达的 Task-Id 提交信息进行核对。对于协调器拥有的运行，可执行 node autonomous-pipeline/scripts/pipeline.mjs resume --run <id> 由协调器跳过 done 单元并重跑可执行集合。
适用场景
适用于可拆分为多单元、可能被中断、需要跨会话续跑的长任务，例如按 DAG 组织的任务、需迁移的文件集合，以及编码协调器（如 Codex）驱动的自主工程流水线。对于发现驱动的运行，可以先以空单元集合启动，随后逐步添加。若运行工作的编排器没有文件系统访问权（例如沙箱化的 Workflow），则由调用方创建并更新该状态文件，并传入绝对路径。
限制
状态写入失败不得阻断、中止或使底层工作失败（调用点用 || true）。不得在恢复时用新的待处理文档覆盖既有运行文件。不得在单元完成且验证之前标记为 done。不得跳过依赖实际未落地的单元。不得伪造时间戳，应读取时钟（date -u）。崩溃后不得把陈旧/正在运行的文件当作真值，应从产物重建。写入应保持原子（tmp + mv）且增量（补丁而非全文重写）以应对竞态。状态写入失败或崩溃最多丢失在途单元。run-status.mjs 的实时叠加层只读取外部日志，其缺失或格式漂移会诚实提示，且绝不改变持久化状态。