重试、错误、取消与恢复

结论：失败恢复是一组分层提交协议，不是一个万能的 retry

这套设计最重要的性质是不把不同的不确定性混成同一种错误。请求可以重放，已启动的写工具却可能只能标成“结果未知”；超时可以发出取消信号，却不能把不合作的 Promise 变成已停止；内存 append 可以表示已接纳，但只有 flush/fsync 才表示进入持久化前缀。理解这些提交点，比背错误码更接近真实恢复模型。

1. 失败所有权地图：每一层只恢复自己能证明的事情

2. Adapter 只把自己拥有的失败降格为终止 chunk

直接调用未 prepared 的 ctx.llm.stream() 时，最终 adapter 边界拥有 adapter 选择、异步 exact-model 解析、dispatch、iterator 构造与消费；这些步骤的异常会变成唯一的 terminal finish(error|aborted)。Agent 主路径则先在 buildRequest() 调用 prepareCall()：除 NO_ADAPTER 回退外，选择或配置解析错误会在 stream 边界之前抛出，由 Turn 记录为 error，而不会进入 agent/request-error。FAILURE-AGENT-PREPARE-BOUNDARY准备成功后，adapter dispatch 与 iterator 错误仍会变成 terminal chunk。middleware、下游 consumer 与 iterator cleanup 错误保持抛出；consumer 提前停止时，边界会 await iterator.return()。FAILURE-ADAPTER-BOUNDARY

3. DeepSeek adapter 把 HTTP 建议、transport 中断和 idle 分开分类

非 2xx 响应会把 401/403、429、400、5xx 映射为稳定的 AUTH、RATE_LIMIT、INVALID_REQUEST、SERVER 等代码；同时提取秒数或 HTTP-date 形式的 Retry-After，以及两个可能的 request-id header。FAILURE-DEEPSEEK-HTTP

一次 stream call 的稳定快照
  connection + credential + user id
        │
        ├─ caller abort ───────────────→ ABORTED
        ├─ outstanding read 无进展 ───→ TIMEOUT
        ├─ 其他 fetch/SSE 故障 ───────→ TRANSPORT
        └─ HTTP 非 2xx ───────────────→ AUTH / RATE_LIMIT / SERVER / ...

每次 stream 调用只解析一份连接与凭据快照，进行中的请求不会混入下一代配置。idle watchdog 只在一次 iterator demand 未完成时计时；退出时 adapter abort consumer controller，并在 iterator 未耗尽时等待 return()，避免“上层已经恢复、底层 transport 还在跑”。FAILURE-DEEPSEEK-STREAM

4. agent/request-error 是窄接缝：只有终止失败才进入

一个 Step 只打开一次，内部 while (true) 为每次尝试重新构造 request 与 assembler。只有 assembler 收到 finish(error|aborted) 才调用 agent/request-error；listener 返回 { kind: "retry" } 才继续循环，否则抛出结构化 LlmError。成功后才写唯一的 assistant/message 并执行工具。FAILURE-REQUEST-LOOP

5. Retry policy 属于 provider route；executor 只执行已经解析的决定

解析器拒绝未知 key、非法边界、空或重复错误码，并生成冻结的 route policy。执行插件本身没有可配置重试策略，避免同一个 provider 被全局 executor 配置暗中改写。FAILURE-RETRY-POLICY

执行时先按同一 turn/step/provider/policyKey 查找历史 retry 次数，再决定 delay。合法且不超过上限的 provider Retry-After 原样采用；normal 模式遇到超上限建议则放弃本地恢复，always 模式改用本地 backoff。llm/retry 在等待之前写入，等待完成才写 llm/retry-started；取消与插件 disposal 都能终止等待，disposal 还会 drain 已捕获的 recovery。FAILURE-RETRY-EXECUTOR

6. 重试保留失败尝试的原始 chunk，但不把它提交成消息或工具副作用

单元测试把失败尝试的 partial text/tool-call chunks 留在 Step 的事件历史中，同时验证它们不成为 assistant/message 的 source、不会产生 tool/call，危险工具的执行次数仍为零；成功尝试才提交该 Step 唯一的 assistant message。测试也固定了重试计划先落事件、指数退避和耗尽后的错误关闭。FAILURE-RETRY-SEMANTICS-TEST

真实 HTTP/SSE 测试进一步覆盖拒绝连接后端点上线、stream disconnect、partial disconnect、空完成与 stalled body；重发 body 保持一致，且仍是同一 Step。一个重要反例是“合法结束但 partial EOF”：它被分类为 STREAM_CLOSED，不在默认 retry code 集合里，因此不会因为“看起来像网络问题”而盲重试。FAILURE-WIRE-RECOVERY-TEST

7. 文档漂移：当前实现是在同一 Turn、同一 Step 内 retry

在固定提交 47f943859bef60e4160492346772ded9b24f765a 上，应以源码和可执行测试为准：retry event 仍带同一坐标，Step 只写一次 start/end，成功 assistant message 也只写一次。README 描述应视为尚未同步的旧语义，而不是实现存在两种模式。

8. 工具 timeout 是协作式 deadline，不是 Promise race 或 hard kill

timeout policy 只包装声明了 timeoutMs 的工具。它把 caller signal 与本地 deadline 融合，dispatch 期间临时替换 exec.signal，随后恢复原 signal；最关键的是它 await downstream tool，仅当自己的 timeout code 先赢时才把最终结果替换成 TOOL_TIMEOUT。它不会提前放弃仍在运行的 Promise。FAILURE-TOOL-TIMEOUT

测试覆盖三类竞态：合作工具收到 abort 后返回、工具以 abort error 抛出、caller abort 与 timeout 先后到达。timeout 先到时，Promise 会一直等到工具的清理 gate 放行才完成；caller 先到则保留普通 abort，而不会误报 timeout。FAILURE-TIMEOUT-TEST

9. 并行工具取消：停止补充、排空已启动、为未启动项补齐结构

并行池在 abort 后不再启动新 call，但会等待所有已经 dispatch 的 call 收敛，按模型顺序提交其 result 和 additional context；随后给尚未启动的每个模型 call 写入有序的 synthetic aborted-before-dispatch call/result。scheduler 自身失败也会 allSettled 已在途 dispatch，但不会伪造成功恢复结果。FAILURE-TOOL-DRAIN

10. Agent cancellation 是状态转换；cancel 返回不等于活动已结束

默认 cancel() 清空未 claim Inbox 并 abort 当前 phase；keepInbox 只保留未 claim 工作。abort-to-idle 窗口中新到达的 waking input 会被重分类到 next Turn 并设置 wake latch，旧 driver 在 turn/end(aborted) 后回到 idle 再启动它。driver 容纳已报告错误，连续 Turn 则各自换新的 AbortController。FAILURE-AGENT-CANCEL

测试验证 post-abort wake 不丢失、默认 cancel 会同时清队列和 latch、删除已 latch 消息会抑制空重放、慢收敛期间仍能 latch，而 disposal 原因永不 latch 新工作。另一个测试固定了“中途取消丢掉 queued tail”的默认语义。FAILURE-CANCEL-TEST

11. Disposal 是共享的静止点：先 cancel，再 drain，再逆序拆资源

Agent 生命周期把 caller、owner 和 factory 三个取消来源融合到同一个 setup signal。memoized disposer 只执行一次：发出 disposed-cause cancel，await whenIdle()，dispose 私有 scope，最后才从 agent/session registry detach 并释放 ownership 记账。所有并发调用方等待同一个 Promise。FAILURE-AGENT-DISPOSAL

12. Write-behind 把“事件已接纳”和“事件已 durable”明确拆开

每个 live Session 有独立 pending queue、固定 batching deadline、active write 和共享 flush barrier。enqueue 会 clone event 并立即返回；flush 取消 timer，等待重叠写，再一直 drain 到队列静止。写失败时 batch 按原顺序放回队首，自动路径暂停；后台失败只报告，显式 barrier 则 reject。FAILURE-WRITE-BEHIND

协调器利用逆序 teardown 先关闭 event admission，再做最终 flush、等待所有 session chain，最后关闭 backend；session retirement 也先 flush，之后才释放精确 lifecycle state，且 close error 不会遮蔽更早的 drain error。FAILURE-PERSISTENCE-WIRING

13. Semantic checkpoint 把可恢复意图放在不可逆副作用之前

模型路径：turn/start → claim → step/start → user/message → flush → adapter dispatch
工具路径：assistant/message → tool/call → flush → tool body
下一 Step：上一轮 response/result batch → pre-step flush → 新请求

Agent 先记录 Turn/Step、输入消息、request header/context，再构造带 session id 的请求并进入 stream。FAILURE-CHECKPOINT-AGENT-ORDERFAILURE-CHECKPOINT-REQUEST-PREFIX llm/stream wrapper 延迟构造下游 stream，直到该 request prefix flush。工具路径先 append tool/call，再进入 scheduler dispatch；dispatch 通过 tools/execute waterfall 才能抵达 body。FAILURE-CHECKPOINT-TOOL-INTENTFAILURE-CHECKPOINT-TOOL-WRAPPER checkpoint policy 在这个 waterfall 中 flush 顶层 call；abort 若在 checkpoint 中发生则返回 canonical aborted-before-dispatch result。pre-step 还会 flush 前一 Step 的 response/result batch。checkpoint 失败全部 fail-closed，不调用 adapter 或工具 body。FAILURE-CHECKPOINT-POLICY

14. 硬崩溃恢复先保护字节前缀，再修补事件语义

独立子进程 E2E 在模型 dispatch 和工具 side-effect 边界收到 SIGKILL。子进程分别在 adapter 收到请求及工具写出外部副作用 marker 后永久等待；父进程观察 marker 后硬杀它。恢复后，第一个场景仍保有完整模型请求前缀；第二个场景证明 tool/call 在外部 marker 之前 durable，而没有结果的已启动工具被恢复为 TOOL_OUTCOME_UNKNOWN。本次复核中该文件 2/2 用例通过。FAILURE-CRASH-FIXTUREFAILURE-CRASH-E2E

原始 JSONL scanner 只提交以换行结束、成功解码且 sequence 连续的记录；Zstd scanner 只列出结构完整的 frame，并把 EOF 中断的最后一帧标为 torn。FAILURE-JSONL-RAW-SCANFAILURE-JSONL-ZSTD-SCAN Loader 把这些完整边界变成稳定前缀；发现 torn tail 时保留完整记录并生成 opaque truncation marker，repair 先截断，再追加可恢复事件和 synthetic closers。FAILURE-JSONL-PREFIX

首次 materialize 使用已 fsync 落盘的临时文件和不会覆盖已有目标的 publish：POSIX 通过 link() 发布并 fsync 父目录，Windows 则用不允许替换的 MoveFileExW(..., MOVEFILE_WRITE_THROUGH)。后续 append 写入并 fsync；write/sync 失败会关闭 handle、截回原长度并再次 fsync，避免同一 sequence 在重试时重复。repair 的 truncate 也会 fsync。FAILURE-JSONL-ATOMICITYFAILURE-JSONL-WIN32

15. Crash repair 修的是 transcript truth，不是 external side-effect truth

修复器使用最后一个真实事件的时间戳和连续 sequence，先为 dangling tool calls 合成 result，再关闭 Step 和 Turn；是否“已启动”只由 durable tool/call 事实决定。其模型面对的恢复文本也明确禁止盲重试潜在副作用。FAILURE-CRASH-REPAIR

backend-agnostic shared contract 定义了 interrupted Turn、未开始工具与结果未知工具的恢复行为；该 contract 分别由内存、JSONL 与 SQLite backend 的测试套件实例化，因此这些语义不只绑定在 JSONL 实现上。FAILURE-CRASH-CONTRACTFAILURE-CRASH-CONTRACT-MEMORYFAILURE-CRASH-CONTRACT-JSONLFAILURE-CRASH-CONTRACT-SQLITE

16. Misconfiguration 不是一类故障：启动、热更新和缺凭据采用三种策略

DeepSeek 配置有 schema 和显式 resolver 两层验证；首次 options() 在 adapter publication 前执行，而 live snapshot 失败时返回整个 lastGood。FAILURE-CONFIG-RESOLUTION凭据则从该请求的同一 connection snapshot 延迟解析；retry policy 是注册时捕获的例外，因此用同步 replace 更新，避免发布空 route 窗口。FAILURE-CREDENTIAL-ROUTE

应用层 watcher 对 present-but-invalid patch 明确 fail loud，并把新 patch 交给一次 entry update；配置 loader 的事务语义负责保留上一棵可用树。FAILURE-HMR-WATCH测试覆盖 parse/validation 失败后的 last-good 与下一次合法 refresh。FAILURE-HMR-CONFIG-TEST另一组测试覆盖用户 patch 的 add → apply failure → parse failure → recovery → removal 全链路。FAILURE-HMR-USER-PATCH-TEST

17. 与 Codex 的公开合同比较：恢复会话与约束权限，不等于证明副作用结果

18. 保证、取舍和仍需上层解决的空白

19. 本章复核范围

所有仓库内结论均针对上游固定提交 47f943859bef60e4160492346772ded9b24f765a。本次聚焦验证运行 13 个 source-level 测试文件，共 407 个用例；另以 E2E 配置独立运行 hard-crash 文件 2 个用例。合计 14 个文件、409 个测试全部通过。

13 focused source-level files  → 407 passed
1 hard-crash E2E file          →   2 passed
total                          → 409 passed

测试覆盖 provider adapter、request recovery、retry 与真实 HTTP/SSE transport、timeout/cancel/disposal、checkpoint/JSONL repair、动态 DeepSeek 配置和应用配置热更新。它们证明这里描述的边界行为；没有把 load、性能、跨机器断电或真实第三方 API 可用性包装成已经验证的结论。