Back to Details

agent-recovery

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Recovery

Agent 恢复

AI agentの復旧は「同じ会話を再開できること」に依存させない。
native session/thread/subagent resumeが利用できる場合は高速経路として使ってよいが、別agent・別process・別sandboxでもdurable project stateから再構成できることをcanonical recovery pathとする。
AI agent 的恢复不应依赖“能够恢复同一个会话”。
如果 native session/thread/subagent resume 可用，可以将其作为快速路径，但即便在不同 agent、不同 process、不同 sandbox 中，也能从 durable project state 重建，才应作为 canonical recovery path。

1. Recovery goals

1. Recovery goals

最低限、次のfailureから復旧可能にする。
  • model/session context loss
  • agent process crash / cancellation
  • terminal/IDE restart
  • parent agent crash while children continue
  • child/subagent crash
  • sandbox/container/VM recreation
  • local Supervisor restart
  • transient network/provider failure
  • CI interruption/retry
  • host reboot
project/provider要件に応じて、machine/provider lossまでのRPO/RTOも定義する。
至少应能从以下故障中恢复：
  • model/session 上下文丢失
  • agent process 崩溃或被取消
  • terminal/IDE 重启
  • parent agent 崩溃，而 children 仍在运行
  • child/subagent 崩溃
  • sandbox/container/VM 重新创建
  • 本地 Supervisor 重启
  • 临时性 network/provider 故障
  • CI 中断或重试
  • host 重启
根据 project/provider 要求，还应定义直至 machine/provider 丢失时的 RPO/RTO。

2. Durable state / transient state

2. Durable state / transient state

Durable recovery sources

Durable recovery sources

復旧時に優先するcanonical evidence:
  1. GitHub Issue
  2. GitHub Projectのstatus / target release / priority / dependency state
  3. target release branch
  4. ticket branch / current remote commit graph / stack relation
  5. Draft/Ready PRとassignee / reviewer / labels / review / CI state
  6. stack predecessor Issue/PR / pinned predecessor SHA when applicable
  7. committed design / ADR / Agent Skills / docs
  8. immutable worker/subagent result commits/refs/artifacts
  9. durable recovery checkpoint / handoff record
active ticketにはpublished headとPRを必須とし、Issue/branch/baseを確認して欠落PRを修復する。PR stateは作業中Draft／readiness後Readyへ整合し、Ready ticketはblockerがなければ自律landingする。
release branchは例外を持つ。
main
とzero-diffのrelease branchはGitHub上Draft PRを作成できないため、その状態だけはDraft release PR不要である。first meaningful integrated differenceがrelease branchに入った後は、Draft release PRが存在しない状態を正常とみなさない。
恢复时优先采用的 canonical evidence：
  1. GitHub Issue
  2. GitHub Project 的 status / target release / priority / dependency 状态
  3. target release branch
  4. ticket branch / 当前 remote commit graph / stack 关系
  5. Draft/Ready PR 与 assignee / reviewer / labels / review / CI 状态
  6. stack predecessor Issue/PR，以及适用时的 pinned predecessor SHA
  7. 已 commit 的 design / ADR / Agent Skills / docs
  8. 不可变的 worker/subagent result commits/refs/artifacts
  9. durable recovery checkpoint / handoff record
active ticket 必须具备 published head 和 PR，并检查 Issue/branch/base，以修复缺失的 PR。PR state 必须与实际工作状态一致：工作中为 Draft，达到 readiness 后为 Ready；若无 blocker，Ready ticket 可以自主 landing。
release branch 是例外。由于 
main
和 zero-diff 的 release branch 无法在 GitHub 上创建 Draft PR，因此仅此状态不需要 Draft release PR。first meaningful integrated difference 进入 release branch 之后，将“不存在 Draft release PR”视为不正常状态。

Transient optimization state

Transient optimization state

次は利用できれば使うが唯一のSoTにしない。
  • native conversation/thread ID
  • agent/subagent ID
  • Supervisor local DB / queue
  • sandbox process state
  • shell history
  • IDE state
  • unpushed local logs
  • model-private context
transient state消失だけでticketを最初からやり直す設計にしてはいけない。
以下状态可用则使用，但不能作为唯一的 SoT：
  • native conversation/thread ID
  • agent/subagent ID
  • Supervisor local DB / queue
  • sandbox process state
  • shell history
  • IDE state
  • 未 push 的 local logs
  • model-private context
不得设计成仅因 transient state 消失，就从零重新开始 ticket。

3. Recovery checkpoint

3. Recovery checkpoint

長時間taskではmeaningful boundaryでstructured checkpointを作る。
checkpointにはprivate chain-of-thoughtを保存しない。再開に必要な外部化可能な事実・決定・次行動だけを保存する。
最低限候補:
text
schema_version
issue_id
target_release
ticket_branch
pr_number
immediate_pr_base
predecessor_issue_or_pr
predecessor_sha
base_sha
checkpoint_sha_or_snapshot
fencing_identity_or_execution_generation
status
completed_steps
next_steps
pending_validation
active_children
integrated_child_results
external_side_effects
blockers
decision_refs
artifact_refs
updated_at
checkpointはmachine-specific absolute pathやsecretへ依存させない。
README / ADR /通常のIssue・PR本文等のreader-facing proseをrecovery journalとして使用しない。Issue / PRをcheckpoint carrierにする場合も、通常本文へ作業履歴を混在させず、recovery用途として明示されたstructured record / handoff surfaceへ分離する。reader-facing prose側は 
writing-discipline
に従う。
对于长任务，应在 meaningful boundary 创建 structured checkpoint。
checkpoint 不保存 private chain-of-thought，只保存恢复所需、可外部化的事实、决定与下一步行动。
最低候选字段：
text
schema_version
issue_id
target_release
ticket_branch
pr_number
immediate_pr_base
predecessor_issue_or_pr
predecessor_sha
base_sha
checkpoint_sha_or_snapshot
fencing_identity_or_execution_generation
status
completed_steps
next_steps
pending_validation
active_children
integrated_child_results
external_side_effects
blockers
decision_refs
artifact_refs
updated_at
checkpoint 不应依赖 machine-specific absolute path 或 secret。
不要将 README / ADR / 普通 Issue/PR 正文等 reader-facing prose 用作 recovery journal。若使用 Issue/PR 承载 checkpoint，也不要将工作历史混入正文，而应分离到明确标为 recovery 用途的 structured record / handoff surface。reader-facing prose 一侧遵循 
writing-discipline
。

4. Soft checkpoint / hard checkpoint

4. Soft checkpoint / hard checkpoint

すべての小さな操作をremote Gitへcommitしてhistoryを汚さない。
不要将所有小操作都 commit 到 remote Git，从而污染 history。

Soft checkpoint

Soft checkpoint

同一sandbox/host再開向け。
候補:
  • local immutable Git ref/commit
  • filesystem/container snapshot
  • Supervisor durable journal
  • native session state
高頻度に作成できる。
用于同一 sandbox/host 的重启恢复。
候选：
  • local immutable Git ref/commit
  • filesystem/container snapshot
  • Supervisor durable journal
  • native session state
可以较高频率创建。

Hard checkpoint

Hard checkpoint

sandbox/providerを失っても復旧する境界。
最低限:
  • meaningful code stateがcanonical remoteで到達可能
  • durable ticket branchではrecorded commit SHAとremote branch headの対応が追跡可能
  • Issue/Project/PRから現在statusを判断可能
  • active durable ticket branchにはPRが存在し、stateが実際のwork stateと一致
  • release branchはzero-diffならDraft release PR不要、first meaningful integrated difference後はDraft release PRが存在
  • stackならpredecessor identity / exact predecessor snapshotが分かる
  • next step / pending verification / blockerがdurableに分かる
実装方式はproject/runtimeに合わせて選ぶ。ticket branchへのWIP commit、dedicated checkpoint ref、durable object store、PR/Issue上の更新可能なhandoff record等を使用できる。
branch/UI clutterとhistory noiseを増やしすぎない方式を優先する。
即使丢失 sandbox/provider 也可恢复的边界。
最低要求：
  • meaningful code state 可在 canonical remote 上访问
  • durable ticket branch 中可追踪 recorded commit SHA 与 remote branch head 的对应关系
  • 可从 Issue/Project/PR 判断当前 status
  • active durable ticket branch 存在 PR，且 state 与真实 work state 一致
  • release branch 为 zero-diff 时不需要 Draft release PR；first meaningful integrated difference 之后则必须存在 Draft release PR
  • stack 的 predecessor identity / exact predecessor snapshot 清晰可辨
  • next step / pending verification / blocker 均可持久获取
实现方式应根据 project/runtime 灵活选择。可以使用 ticket branch 上的 WIP commit、dedicated checkpoint ref、durable object store、PR/Issue 上可更新的 handoff record 等。
应优先选择不会过度增加 branch/UI clutter 和 history noise 的方案。

5. Checkpoint triggers

5. Checkpoint triggers

最低限、次の前後でcheckpointを検討する。
  • non-trivial implementation milestone完了
  • risky refactor/migration前
  • child/subagent spawn前
  • child result integration後
  • stack predecessor update / downstream rebase前後
  • long validation開始前/完了後
  • external side effect前/後
  • user/external input待ちへ移る時
  • provider shutdown/TTL接近時
  • graceful cancellation/shutdown signal受信時
  • context limit接近時
時間ベースcheckpointも利用できるが、semantic boundaryを優先する。
至少应在以下时点前后考虑 checkpoint：
  • non-trivial implementation milestone 完成
  • risky refactor/migration 之前
  • child/subagent spawn 之前
  • child result integration 之后
  • stack predecessor update / downstream rebase 前后
  • long validation 开始前或完成后
  • external side effect 之前或之后
  • 转入等待 user/external input 时
  • provider shutdown/TTL 临近时
  • 收到 graceful cancellation/shutdown signal 时
  • context limit 临近时
可以使用基于时间的 checkpoint，但应优先采用 semantic boundary。

6. Recovery algorithm

6. Recovery algorithm

新しいagentは以前の会話を推測しない。
標準手順:
  1. Issue / GitHub Project / PR / target release / dependencyを特定する。
  2. current ticket/release branch、remote commit graph、stack predecessor/successor relationをfetchする。
  3. ticket PRのhead/state、linked Issue、metadata/baseをread-only確認し、欠落やdriftを修復候補として記録する。
  4. 未landingのReady PR、未close Issue、残存branch、dependent PRをread-only検出する。ownership取得前はmutationしない。
  5. release branchのmain差分とDraft PRを確認（zero-diff例外あり）。release PRはbulk landing対象外で、explicit authorizationなしにmergeしない。
  6. latest valid recovery checkpointを読む。
  7. canonical design/policy/decision refsを再確認する。
  8. observed fencing identityに対するcompare-and-set等でrecovery ownershipを原子的に取得し、新しいfencing identityを確定する。current implementationでgeneration方式を使う場合はnew 
    execution_generation
    と一意なlease/fencing tokenを発行する。競合した場合はownershipを共有せず、stateを再読してやり直す。
  9. active child/subagent stateをlogical Supervisorへ問い合わせ、current fencing identityとの関係をreconcileする。
  10. current workspaceをcheckpointからrecreateする。
  11. stack-ready workではrecorded predecessor SHAとcurrent intended predecessor stateを比較し、差があればstale baseとしてreconcileする。
  12. completed/pending validationをcurrent snapshotに対して再評価する。
  13. current fencing・refs・validation・side effectsを再確認後、3〜5のPR修復、ticket landing、Issue close、dependent PR調整、safe cleanupを順次実行。mutationごとにfencing再検証し、release mergeを含めない。
  14. stale base / conflicting integrationを確認する。
  15. remaining planを再構成する。
  16. safeな最小verificationを実行してstateを信頼できることを確認する。
  17. current fencing identityの所有権を維持したまま作業を継続する。
native resumeが成功しても、重要なIssue/Project/branch/PR/stack/checkpoint stateとの整合を確認してから続行する。
新的 agent 不猜测以前的会话。
标准步骤：
  1. 确定 Issue / GitHub Project / PR / target release / dependency。
  2. fetch 当前 ticket/release branch、remote commit graph，以及 stack predecessor/successor 关系。
  3. 以 read-only 方式确认 ticket PR 的 head/state、linked Issue、metadata/base，并将缺失或 drift 记录为修复候选。
  4. 以 read-only 方式检测未 landing 的 Ready PR、未 close 的 Issue、残留 branch 和 dependent PR。在取得 ownership 之前不得进行 mutation。
  5. 检查 release branch 与 main 的差异以及 Draft PR（存在 zero-diff 例外）。release PR 不属于 bulk landing 范围，未经 explicit authorization 不得 merge。
  6. 读取 latest valid recovery checkpoint。
  7. 再次确认 canonical design/policy/decision refs。
  8. 针对 observed fencing identity，通过 compare-and-set 等方式原子性地获取 recovery ownership，并确定新的 fencing identity。如果当前实现采用 generation 方式，则签发新的 
    execution_generation
    以及唯一的 lease/fencing token。发生冲突时不得共享 ownership，而应重新读取 state 并重试。
  9. 向 logical Supervisor 查询 active child/subagent state，并 reconcile 其与 current fencing identity 的关系。
  10. 根据 checkpoint 重建 current workspace。
  11. 对于 stack-ready work，将 recorded predecessor SHA 与 current intended predecessor state 进行比较；若存在差异，则将其作为 stale base 进行 reconcile。
  12. 针对 current snapshot 重新评估 completed/pending validation。
  13. 再次确认 current fencing、refs、validation 和 side effects 后，依次执行第 3～5 步中的 PR 修复，以及 ticket landing、Issue close、dependent PR 调整和 safe cleanup。每次 mutation 前都要重新验证 fencing，并且不包含 release merge。
  14. 检查 stale base / conflicting integration。
  15. 重新构建 remaining plan。
  16. 执行安全的最小组 verification，以确认 state 可信。
  17. 在持续持有 current fencing identity 所有权的情况下继续工作。
即使 native resume 成功，也必须先确认与重要的 Issue/Project/branch/PR/stack/checkpoint state 一致，然后再继续。

7. Parent / child recovery

7. Parent / child recovery

child lifecycleはparent model processではなくSupervisorが所有する。
parentが死亡しても、safeならchildを即cancelしない。
recovered parent/coordinatorは:
  • child一覧を再発見
  • input snapshot / predecessor snapshot / applicableなcurrent fencing identityを確認
  • running/completed/failed/orphanedを分類
  • completed resultをimmutable resultとして回収
  • stale child resultは自動統合しない
  • durable branchを作ったchildではpublished remote head / PR identity/state / metadataをreconcile
  • 必要ならretry/resume/re-spawn
を行う。
child自身も独立checkpointを持てるようにする。
child lifecycle 由 Supervisor 持有，而不是由 parent model process 持有。
parent 死亡时，如果情况安全，不要立即取消 child。
恢复后的 parent/coordinator 应当：
  • 重新发现 child 列表
  • 确认 input snapshot / predecessor snapshot / 适用的 current fencing identity
  • 将 child 分类为 running/completed/failed/orphaned
  • 将 completed result 作为 immutable result 回收
  • 不自动集成 stale child result
  • 对创建了 durable branch 的 child，reconcile published remote head / PR identity/state / metadata
  • 必要时执行 retry/resume/re-spawn
child 自身也应持有独立的 checkpoint。

8. Duplicate execution / split-brain防止

8. Duplicate execution / split-brain 防止

network partitionやtimeout後に旧agentと新agentが同時実行される可能性を前提にする。
Supervisorはticket/taskごとにleaseまたはfencing identityを持つ。
  • current implementationがgeneration方式の場合、mutable taskの初期 
    execution_generation
    は 
    1
    とする
  • recovery/reassignment時はobserved fencing identityに対するcompare-and-set等でownershipと新しいfencing identityを原子的に取得する
  • 複数recoveryへ同じfencing identityを発行しない
  • worker resultへapplicableなfencing identityを付与する
  • stale fencing identityからのbranch integration / external writeを拒否する
  • 各external write直前にcurrent fencing tokenを再検証する
  • heartbeat消失だけで即座に同一side effectを再実行しない
同じticket branchへ複数fencing identityが同時pushすることを通常運用にしない。
必须预设 network partition 或 timeout 之后，旧 agent 与新 agent 可能同时执行。
Supervisor 为每个 ticket/task 持有 lease 或 fencing identity。
  • 如果当前实现采用 generation 方式，mutable task 的初始 
    execution_generation
    应设为 
    1
  • 在 recovery/reassignment 时，针对 observed fencing identity，通过 compare-and-set 等方式原子性地获取 ownership 和新的 fencing identity
  • 不得向多个 recovery 签发同一个 fencing identity
  • 为 worker result 附加适用的 fencing identity
  • 拒绝来自 stale fencing identity 的 branch integration / external write
  • 每次 external write 之前都要重新验证 current fencing token
  • 不能仅因 heartbeat 消失就立即重新执行相同的 side effect
不要将多个 fencing identity 同时 push 到同一个 ticket branch 作为常规操作。

9. External side effects / idempotency

9. External side effects / idempotency

Git外の操作は特に危険。
例:
  • production/staging deploy
  • DB migration
  • package publish
  • release/tag creation
  • cloud resource mutation
  • notification/email/comment creation
  • billing/cost-producing operation
可能ならidempotency keyを使用する。
side effect前にintent、後にresult/remote identifierをdurable journalへ記録する。実行直前にcurrent fencing tokenを検証し、recovery時はownership取得後にremote actual stateを確認してからretryする。
command returned no response = operation did not happen
と推測してはいけない。
irreversible/destructive operationはengineering-decisionsのuser escalation policyも適用する。
Git 之外的操作尤其危险。
例如：
  • production/staging 部署
  • DB migration
  • package publish
  • release/tag creation
  • cloud resource mutation
  • notification/email/comment creation
  • billing/cost-producing operation
如果可能，应使用 idempotency key。
side effect 之前将 intent、之后将 result/remote identifier 记录到 durable journal。执行之前验证 current fencing token；recovery 时取得 ownership 后，先确认 remote actual state，再执行 retry。
绝不能推测 
command returned no response = operation did not happen
。
irreversible/destructive operation 还需遵循 engineering-decisions 的 user escalation policy。

10. Validation recovery

10. Validation recovery

validation途中で中断した場合、途中までのgreenをfull passとみなさない。
各validation resultには最低限:
  • validated_sha
    またはcontent-addressed 
    validated_snapshot
  • validation profile/version
  • completed checks
  • failed checks
  • not-run checks
  • artifacts/report references
を記録する。
recovery後に既存resultを再利用できるのは、validated snapshotがcurrent code snapshotと完全一致し、そのcheck自体のdeterminism/dependency条件も維持されている場合だけとする。checkpointまたはcode snapshotが変わった場合は、古いgreen resultをcurrent codeのpassとして扱わない。
特にstack predecessor変更によるrebase/updateでdownstream SHAが変わった場合、affected required validationを新しいSHAで再実行する。
release/integration gateでは、stale code state上の古い成功結果を流用しない。
如果 validation 在中途中断，不得将截至中断时的 green 视为 full pass。
每个 validation result 至少应记录：
  • validated_sha
    或 content-addressed 
    validated_snapshot
  • validation profile/version
  • 已完成的 checks
  • 失败的 checks
  • 未运行的 checks
  • artifacts/report references
只有在 validated snapshot 与 current code snapshot 完全一致，并且该 check 自身的 determinism/dependency 条件仍然成立时，recovery 后才能复用既有 result。
如果 checkpoint 或 code snapshot 发生变化，不得将旧的 green result 视为 current code 的 pass。
尤其是 stack predecessor 改动引发 rebase/update、导致 downstream SHA 变化时，必须使用新的 SHA 重新执行 affected required validation。
在 release/integration gate 中，不得沿用在 stale code state 上取得的旧成功结果。

11. Context compaction / handoff

11. Context compaction / handoff

context window接近はfailureではなく予測可能なhandoff eventとして扱う。
agentはcontext不足になる前に:
  • current objective
  • accepted decisions
  • relevant refs/files
  • Issue / target release / PR / stack predecessor
  • completed work
  • current diff/checkpoint
  • pending work
  • validation state
  • blockers
をstructured checkpointへ外部化する。
長い会話要約やprivate reasoningを保存するのではなく、fresh agentが再実行可能なoperational stateへ圧縮する。
context window 临近不是 failure，而应将其视为可预测的 handoff event。
agent 应在 context 不足之前，将以下内容外部化到 structured checkpoint：
  • current objective
  • accepted decisions
  • relevant refs/files
  • Issue / target release / PR / stack predecessor
  • completed work
  • current diff/checkpoint
  • pending work
  • validation state
  • blockers
不要保存冗长的对话摘要或 private reasoning，而应将其压缩为 fresh agent 能够重新执行的 operational state。

12. Recovery test

12. Recovery test

recovery policyはdocumentだけで終わらせない。
project/runtimeが許す範囲で定期的に:
  1. ticket workをcheckpointする
  2. agent/sandboxを意図的に停止する
  3. fresh agent/sandboxからrecoveryする
  4. Issue/Project/branch/PR/stack/children/validation/side-effect journalを再構成する
  5. durable ticketではpublished remote head / PR identity/state / linked Issue / metadata / predecessor baseを検証し、missing PRをrepairできることを確認する
  6. Ready ticket PRのautonomous landing、target release landing後のIssue close、safe branch cleanupがrecovery後も重複mutationなしでreconcileできることを確認する
  7. release branchではzero-diff例外またはfirst-difference後Draft release PRの存在を検証し、release PRがexplicit authorizationなしにlandingされないことを確認する
  8. duplicate mutationなしで続行できることを確認する
chaos/recovery drillをintegration infrastructureの一部として採用できる。
recovery policy 不可只停留在文档层面。
在 project/runtime 允许的范围内，应定期执行：
  1. 对 ticket work 创建 checkpoint
  2. 故意停止 agent/sandbox
  3. 从 fresh agent/sandbox 执行 recovery
  4. 重新构建 Issue/Project/branch/PR/stack/children/validation/side-effect journal
  5. 对 durable ticket 验证 published remote head / PR identity/state / linked Issue / metadata / predecessor base，并确认能够修复 missing PR
  6. 确认 Ready ticket PR 的 autonomous landing、target release landing 后的 Issue close 以及 safe branch cleanup 在 recovery 后均能在没有重复 mutation 的情况下完成 reconcile
  7. 对 release branch 验证 zero-diff 例外或 first-difference 后 Draft release PR 的存在，并确认 release PR 未经 explicit authorization 不会被 landing
  8. 确认能够在不产生 duplicate mutation 的情况下继续工作
chaos/recovery drill 可以作为 integration infrastructure 的一部分采用。

13. Recovery completion criteria

13. Recovery completion criteria

recovered taskを「再開成功」とみなす条件:
  • canonical Issue/Project/PR/release/dependencyとの対応が確認済み
  • active durable ticket branchはmeaningful stateがcanonical remoteへpublish済みで、remote head identityが確認済み
  • active ticketにPRと現状に合うDraft/Ready state、Issue/base/metadataが存在
  • Ready ticketはblockerがなければlanding済みで、Issue close・safe cleanupまで整合
  • release PRはzero-diff例外・Draft/Ready・明示authorization boundaryを遵守
  • stackならpredecessor identity / exact base snapshotが確認済み
  • workspaceが追跡可能なsnapshot/commitから再構成済み
  • current fencing identityを一意に所有している
  • stale executionがintegration/external-write権限を持たない
  • active childrenがreconciled済み
  • external side effectsの不明状態がない、または明示的blocker化済み
  • validation stateがcurrent code snapshotに対して正しく再評価済み
  • remaining next stepがstructured stateとして明確
会話を完全復元できたことは必要条件ではない。
将 recovered task 视为“恢复成功”的条件：
  • 已确认与 canonical Issue/Project/PR/release/dependency 的对应关系
  • active durable ticket branch 的 meaningful state 已 publish 到 canonical remote，并确认 remote head identity
  • active ticket 具备 PR，且 Draft/Ready state 与现状一致，同时具备 Issue/base/metadata
  • Ready ticket 若无 blocker，则已 landing，且 Issue close 与 safe cleanup 均已达成一致
  • release PR 遵循 zero-diff 例外、Draft/Ready 以及 explicit authorization boundary
  • stack 的 predecessor identity / exact base snapshot 已确认
  • workspace 已从可追踪的 snapshot/commit 重建
  • 唯一持有 current fencing identity
  • stale execution 不具备 integration/external-write 权限
  • active children 已完成 reconcile
  • external side effects 不存在状态不明的情况，或已将其明确标记为 blocker
  • validation state 已针对 current code snapshot 正确重新评估
  • remaining next step 已在 structured state 中明确
完全恢复对话并不是必要条件。