# Native 恢复参考

只读取当前阻塞对应的章节。

## 等待外部输入与监控

- 暂停条件：相关工作只等待用户答复或外部资料，且没有可执行子任务、没有仍在执行的相关任务，也没有需要定期检查的外部状态时，暂停当前工作的定期监控。保留独立任务及其监控。仍在执行的任务，或仍需查看结果的 CI 和外部作业，继续使用平台的等待或监控功能。
- 暂停操作：能够确定哪个自动化任务属于当前工作、且平台允许管理时，调用平台功能实际暂停监控，并核对返回状态。返回信息不足时，再查询该自动化任务的状态。无法识别、权限不足或暂停失败时，明确说明监控尚未确认暂停，以及需要用户执行什么操作。停止回复消息不等于停止定期触发任务；不得操作归属不明或无关的自动化。
- 等待说明：首次进入等待时，一次性告知用户阻塞原因、缺少的资料、实际暂停了哪些监控、哪些任务仍在运行，以及恢复条件。将这些信息、对应监控标识和暂停结果写入已有的任务记录，不另建一种正式文件格式。
- 恢复条件：收到相关新输入，或确认所需条件已经满足后，重新读取 Runtime 状态，沿用原 change、任务标识和已完成结果，按最新 `continuation` 继续。普通进度消息不能解除阻塞，也不能因此重新分配已经完成的任务。只有仍需定期检查时，才恢复对应监控，并核对是否恢复成功。
- 区分状态：平台任务空闲或定期监控暂停，不等同于 Runtime 的 `blocked` / `await-user`。只有现有公开命令适用于当前阶段和阻塞原因时，才通过命令更新 Runtime 状态。否则记录任务被什么问题阻塞，并暂停依赖该信息的工作；不得直接修改状态文件，也不得用 Verifier 状态表示缺少实现所需的资料。

## 故障恢复

命令已返回具体错误、当前状态和恢复动作时，先按该响应处理。Runner 输入校验失败按[填写命令输入](commands.md#填写命令输入)修正，归档提交或合并失败按[Archive 收尾](workspace.md#archive-收尾)继续，仍在运行的任务保持原标识。没有当前状态、调用中断或现场与响应不一致时，先停止依赖该状态的修改，运行一次 `status --details --json`；状态或恢复记录仍无法解释问题时，再运行只读 `doctor`。只执行 `continuation` 或 `doctor` 明确返回的恢复动作。跨设备状态、本机执行状态、锁和事务始终由 Runtime 管理；无法确定自动恢复是否安全时，保留现场并等待用户决定。

仅等待外部输入时，按[等待外部输入与监控](#等待外部输入与监控)处理，独立工作继续。恢复后重新分配 Supervisor 任务前，必须读取[Supervisor 协作](commands.md#supervisor-协作)；重新启动 Verifier 前，必须读取[Verify 协议](commands.md#verify-协议)，核对当前任务标识、待验收的实现版本和执行状态。

### 工作区

`status` 会在已登记的 worktree 中查找与当前项目和分支关联的 change，并返回实际工作目录 `workspace.projectRoot`。进入该目录并重新执行 `select`。恢复时沿用找到的 change 和工作目录，不复制 change，也不在其他目录重建同名 change。

如果项目根目录、分支、工作区类型或 Git 状态与 `comet-state.yaml` 中的记录不一致，Runtime 会阻止写入。Runtime 能安全找到或创建已声明的 worktree 时，按返回动作继续；否则进入阻塞等待用户决定（`disposition: blocked`，recovery action 为 `await-user`）。原目录或分支确实丢失时，由用户决定使用哪个恢复目录、是否从可信备份重建，或是否放弃 change。

### 工作流记录与本机执行状态

`comet-state.yaml` 记录最后一个可以安全恢复的工作流状态。本机 `state.json` 只说明这台机器正在执行什么；如果它缺失、版本落后或属于旧任务，Runtime 会根据 YAML、brief 和目标 Spec 重建。本机状态不能覆盖版本更新的 YAML。

- Shape：保持 Shape，继续澄清或确认。
- Build：如果 Runtime 显示 `repairing`，表示 Verify 未通过后已返回 Build。普通 change 保持当前验收轮次并继续修改；Supervisor Change 按 `repair-child` 添加新的修复子任务，处理尚未通过的验收项（编辑 `children.yaml` 后运行 `comet native next <parent> --summary "<说明>"`，契约变化会让 Runtime 退回 Shape 重新确认），不重新打开已经归档的子任务。
- Verify（`verify-ready`）：重新运行当前实现所需的检查，并启动新的 Verifier；不沿用旧设备上的通过结果。
- Archive（`archive-ready`）：先安全返回 Verify，把验收结果重置为待检查（`pending`），再验收已经同步到新设备的实现。
- 等待用户或阻塞（`await-user` / `blocked`）：恢复原来的阻塞原因、负责处理的人和允许动作，等待对应条件满足后再继续。
- active 目录中的 `done`：只按 Runtime 返回的动作完成目录移动与清理；尚有 Git 收尾时，按[Archive 收尾](workspace.md#archive-收尾)继续。
- archive 目录中的 `done`：先核对公开状态中的工作区收尾结果。所选收尾已完成或保留时只读展示；仍报告未完成或 `blocked` 时，按[Archive 收尾](workspace.md#archive-收尾)继续。

旧任务的进程、日志连接和 Agent 会话都视为已经丢失，不能根据残留文件猜测它们是否成功。检查已经结束、但 YAML 尚未记录结果时，只能重跑可以安全重复的检查；可能重复产生外部影响的操作，需要等待用户决定。

`verification.md` 缺失、写入中断或 `generated_from_state_version` 落后时，只根据 YAML 重建报告。YAML 仍是恢复依据；报告版本与状态版本一致后，才能进入 Archive。

旧版本的 active change 会以只读状态显示 `migration-required`。使用 `doctor --repair` 或 Runtime 明确返回的迁移命令处理。迁移失败时保留旧文件，等待 Runtime 给出下一步。

### 没有聊天记录时跨设备恢复

在没有聊天记录的新设备上恢复时，需要取得同一份已同步项目代码、`comet-state.yaml`、brief 和目标 Spec。如果 change 使用非默认产物目录，还需要同步 `.comet/config.yaml`。

先停止旧设备上的推进并完成同步。发现 Git 冲突，或同一状态版本出现两份不同内容时，进入阻塞状态并交给用户处理。

旧设备上尚未同步的代码，不能仅靠工作流状态恢复；同一个 subagent 任务也不能跨设备继续。新设备根据 YAML 中的工作目录、验收轮次、验收结果、阻塞原因、Builder handoff 和下一步，创建新的本机执行任务。如果同步后的实现不完整，新的 Verifier 会指出缺失内容，并返回 Build。

处于 Verify 或待归档状态的 change，在新设备上重新验收属于恢复操作，不增加验收轮次、失败轮次或无进展次数。只有实际启动新的 Verifier 时，Verifier 尝试次数才增加。已经完成的 Shape 和 Build 不会重做，Runtime 也不会扫描整个项目来猜测进度。

### Verify 未通过与持续无进展

Verify 未通过后，读取未通过、暂时无法验证的验收项以及失败检查。完成实际修改后，再提交新的 Builder handoff。只有未解决的问题变少才算有进展；只改说明文字、重复相同检查或再次报告同一原因，不算解决问题。

连续多轮没有进展，或 Verifier 任务多次执行出错时，按 Runtime 返回的阻塞处理动作继续。失败轮次达到 `native.max_verify_failures` 时进入等待用户，让用户选择继续当前目标、修改已经确认的需求或停止。用户确认新的验收清单并开始一轮新目标后，验收失败计数清零。

### 规格与 Archive 冲突

如果项目中已经归档的正式 Spec 在当前 change 期间发生变化，重读最新正式 Spec、brief 和当前 change 的完整目标规格，按用户意图改写后执行 Runtime 冲突信息中给出的重新对齐（rebase）动作，再重新实现和验收。并发产生的新内容应保留。

两个 active change 同时修改同一功能区域（capability）时，Archive 会进入等待用户。用户决定先归档哪一个，另一个 change 随后重新对齐最新 Spec。

Archive 或 change 目录移动中断时，以 `doctor` 返回的事务状态和允许动作作为恢复依据。路径、工作流状态和实际文件互相对不上时，保留两侧现场并等待明确的恢复动作。

若工作区收尾结果 `workspaceFinishResult.status` 为阻塞（`blocked`），change 可能已经完成归档或 Git 提交。先执行 `recoveryArgs` 检查实际 Git 状态，再根据返回结果决定下一步。

### 损坏状态

- 锁由 Runtime 管理；只有 `doctor` 明确给出命令时才修复。
- config、change、brief、规格或 verification 损坏时，保留原文件并等待 `doctor` 或用户给出恢复来源。
- 同一个 change 同时出现在 active 和 archive、无法确定文件归属，或无法判断事务进行到哪一步时，保留现场并停止写入。