断流、限流和 401：Codex 分别从哪里恢复

第 12 章已经把正常路径推进到一个明确边界：added 和 delta 只维护当前投影，done 才可能写入完整 item、启动 tool future，Completed 只结束一次 provider response。它留下的 unresolved error set 却来自好几层：HTTP 请求尚未打开、401、已经打开的 SSE 或 WebSocket 中断、typed event 映射失败、core 收不到 response.completed、工具 future 自己返回 Err。

如果只问“会不会 retry”，这些分支很容易被揉成一个循环。更有效的读法是先把每个信号放回首个观察者，再沿下面这条责任链向外走：

flowchart TB
  accTitle: Codex 失败恢复责任链
  accDescr: 失败信号先由 transport、ModelClientSession、sampling event loop、run_turn 或 Session 观察，再由对应 owner 持有预算或状态，决定重试目标、局部退出以及最终 TurnComplete 或 TurnAborted
  SIGNAL[error or signal] --> OBSERVER[first observer]
  OBSERVER --> OWNER[recovery owner]
  OWNER --> STATE[budget or sticky state]
  STATE --> TARGET[retry target]
  TARGET --> EXIT[local return]
  EXIT --> NORMAL[EventMsg Error then TurnComplete]
  EXIT --> ABORT[TurnAborted lifecycle]
  EXIT --> CONTINUE[continue current task]

这张图没有重画第 10 章的 request shape、HTTP/WS full 与 delta，也不重复第 11 章的正常两层业务循环。本文只回答失败以后控制权停在哪里。

失败先归 owner，再判断能不能恢复

CodexErr::is_retryable 是 sampling 层的一道分类门，但它并不是整套恢复策略。Stream、timeout、UnexpectedStatus、Io 等会通过这道门；TurnAborted、InvalidImageRequest、UsageLimitReached、RetryLimit、RefreshTokenFailed 等不会。401 在进入这里之前可能已经由 client call 内的 auth state machine 消化；HTTP request-open retry 更早发生在 codex-client；WS fallback 还会改 session-scoped transport state。

还要把 local return 与 task lifecycle 分开。run_turn 对一般 sampling error 会发 EventMsg::Error，然后 break 并返回 Ok(last_agent_message)；Session 的 on_task_finished 因而仍走 TurnComplete。只有 CodexErr::TurnAborted 被原样向外传播时，Session 才选择 TurnAborted。因此用户看到 Error 后又看到 TurnComplete，在这版源码里并不矛盾：前者报告工作失败，后者关闭 task 生命周期。

401 的恢复权停在当前 client call

HTTP 和 WebSocket 各自在 ModelClientSession 的调用内部创建一个 UnauthorizedRecovery。HTTP stream_responses_api 捕获 request-open 的 401，WS stream_responses_websocket 捕获 handshake 的 401；两边都调用 handle_unauthorized，成功后 continue 当前 transport loop。调用者没有拿到 stream error，run_sampling_request 的 counter 也没有递增。

managed auth 的状态顺序是 Reload -> RefreshToken -> Done。第一次 401 先按 account id guarded reload；无论磁盘 auth 是否改变，成功后下一次 401 才进入 authority refresh。external auth 从 ExternalRefresh 开始，只给一次 refresh，然后进入 Done。API key、不可 refresh 的 auth、account mismatch 或已经耗尽的 state 都可能没有下一步。

handle_unauthorized 还决定 recovery 自己失败以后用什么错误离开。永久 refresh failure 映射成不可 retry 的 RefreshTokenFailed；transient failure 映射成可 retry 的 Io。若没有 recovery 机会或步骤已经耗尽，原始 401 交给 provider mapper，成为 UnexpectedStatus，随后可以进入上层 sampling retry。这里的“可以”很重要：401 本身没有吃掉 request_max_retries，但映射后的错误可能消耗 stream_max_retries。

主动刷新是另一条路径。第 5 章已经划过 auth owner；在这里需要保留一个窄边界：AuthManager::auth() 会在 token 接近过期时尝试 proactive refresh，失败后记录诊断并继续返回旧 auth。reactive recovery 只有服务端已经给出 401 才启动，不能把两者合成“请求前一定刷新”。

request retry 与 sampling retry 是两套预算

request-open 只重做 HTTP 建流

ModelProviderInfo::request_max_retries() 默认是 4，配置值被硬截到 100。它进入 API provider 时形成 policy：当前 Responses policy 对 5xx、timeout 和 network error 开启 retry，对 429 关闭。401 也没有对应开关，所以不在这层 retry。

HTTP Responses 先把 body 和 request 准备好，再把可 clone 的 request 交给 run_with_request_telemetry。后者只包 auth.apply_auth(req) 与 transport.stream(req)。所以这一预算重试的是 HTTP 请求和建流，没有重建 history、Prompt 或已经开始消费的 SSE。

run_with_retry 遍历 0..=max_attempts。因此配置 N 次 retry 会产生最多 N+1 次 request attempt。最后一次 retryable error 到来时，should_retry 因 attempt >= max_attempts 返回 false，原 TransportError 从 Err(err) 分支上抛。函数尾保留了 TransportError::RetryLimit fallback，但正常的有限循环通常在最后一个 Err arm 已返回；不能把 request budget 耗尽一律写成新造 RetryLimit。

sampling retry 重做完整 request

run_sampling_request 才持有 sampling counter。它读取 stream_max_retries()，默认 5、上限 100，然后用初始 input 建第一次 Prompt。后续 retry 不续读旧 stream：它从 Session 的最新 history 重新做 for_prompt，重建 Prompt，再调用一遍 try_run_sampling_request。这也接上第 9 章的边界：retry input 是新的 history projection。

responses_retry.rs 只是共享 decision helper。counter 的生存期仍在调用者。正常 tool follow-up 回到 run_turn 的下一轮，又调用一个新的 run_sampling_request，局部 retries 再从 0 开始；它不会继承上一轮 sampling 已用掉的次数。

RateLimits、HTTP 429、response.failed 各走一条路

ResponseEvent::RateLimits(snapshot) 是成功 stream 中的 metadata。core 把 snapshot 写进 Session rate-limit state，只把 should_emit_token_count 置起；真正的 TokenCount 延迟到 tool future drain 以后。这个 event 不递增任何 retry counter，也不让 sampling 退出。

HTTP 429 发生在 stream 打开前。request policy 已经明确 retry_429=false，provider mapper 再看 body：type=usage_limit_reached 变成不可 retry 的 UsageLimitReached，并可携带 reset、plan 和 snapshot；usage_not_included 另行映射；其他 429 直接变成不可 retry 的 RetryLimit。后一个名字描述 core error shape，不证明 run_with_retry 已经用完次数。

response.failed 与 response.incomplete 已经发生在 stream 内。共享 mapper 会把 context window、quota、usage-not-included、cyber policy、invalid request 和 overloaded 等已知 failed code 映到各自错误；其余 failed error，包括 rate_limit_exceeded，成为带可选 server delay 的 ApiError::Retryable，随后映成 sampling 可 retry 的 CodexErr::Stream。response.incomplete 也形成 ApiError::Stream。所以同样是“限流”，HTTP usage limit 可以直接结束 sampling，stream 内的 rate_limit_exceeded 却可能重做完整 sampling request。

WS fallback 分两种：426 不占预算，耗尽时清零；sticky 状态跨 turn 生效

WS handshake 返回 426 时，stream_responses_websocket 直接返回 FallbackToHttp。同一次 ModelClientSession::stream 随即调用 try_switch_fallback_transport，然后进入 HTTP branch。这个切换发生在 stream 成功返回给 sampling 层之前，不消耗 sampling retry counter。

另一条 fallback 发生在可 retry 的 WS stream error 已经吃完 stream_max_retries 时。shared helper 先尝试切换 transport；成功就发 Warning，把 counter 清成 0，并让 sampling loop 立即再来一次。下一次 Prompt 仍会重建，但 transport 已是 HTTP，而且 HTTP 得到一份完整的新 stream budget。若当前已经是 HTTP，或 fallback state 已经打开，helper 无法再次切换，最终返回原错误。

sticky 状态是 Arc<ModelClientState> 里的 disable_websockets: AtomicBool。force_http_fallback 原子置位并清空 cached WS session；之后 responses_websocket_enabled() 对同一存活 Session 返回 false。这里没有修改 provider、Config 或配置文件，也没有给新进程留下 durable marker。

固定版本实验：同一存活 session 的 fallback 跨 turn 保持

实验前确认 CODEX_SANDBOX_NETWORK_DISABLED 完全未设置。fixture 的 skip macro 只要发现该变量存在就提前返回，因此不能用 env -u 把受限环境伪装成真实执行。本次变量为 unset，输出中也没有 Skipping test because...。

固定 commit 还有一个实验准备问题：workspace manifest 已标成 0.144.6，同 commit 的 lockfile 中本地 workspace packages 仍是 0.0.0。直接在固定 checkout 执行 just test --locked，Cargo 会在编译前拒绝更新 lock。为了不污染证据 checkout，第三部的共享准备脚本从该 commit 创建 git archive，只在副本中校准 132 个本地 workspace version 条目；diff 必须确认所有变化都是 0.0.0 -> 0.144.6，没有外部 dependency 的 version、checksum 或 source 变化。

完整的 archive/lock 校准由本仓库的 scripts/codex-handbook-part3.sh 提供。跳读到本章时，下面代码块会在自己的 shell 中 source helper、调用 prepare_codex_part3 并注册 cleanup trap；没有博客 checkout 时，可把第三部导读展开区的完整 helper 保存到任意路径，再通过 CODEX_HANDBOOK_PART3_HELPER 指向它。它不会依赖另一个已经退出的 shell。断言说明测试启动前必须已经成立的合同。SOURCE_ROOT 是固定仓库根，SOURCE_DIR 是其中的 codex-rs；ARCHIVE_DIR 是一次性副本根，Cargo target 也只能写在这个目录。两份 132 行的 name set 必须完全相同，不能只核对数量：

SOURCE_ROOT="${SOURCE_ROOT:-/tmp/codex-handbook-final-rust-v0.144.6}"
SOURCE_DIR="$SOURCE_ROOT/codex-rs"
EXPECTED_LOCAL_PACKAGES=132
CODEX_HANDBOOK_PART3_HELPER="${CODEX_HANDBOOK_PART3_HELPER:-$PWD/scripts/codex-handbook-part3.sh}"
test -f "$CODEX_HANDBOOK_PART3_HELPER"
source "$CODEX_HANDBOOK_PART3_HELPER"
prepare_codex_part3
trap 'cleanup_codex_part3 "$?"' EXIT
ARCHIVE_CODEX_RS="$ARCHIVE_DIR/codex-rs"
export CARGO_TARGET_DIR="$ARCHIVE_DIR/target"

test -f "$SOURCE_DIR/Cargo.toml"
test -f "$ARCHIVE_CODEX_RS/Cargo.lock.before"
test "$(wc -l <"$ARCHIVE_CODEX_RS/workspace.names" | tr -d ' ')" \
  -eq "$EXPECTED_LOCAL_PACKAGES"
test "$(wc -l <"$ARCHIVE_CODEX_RS/lock.names" | tr -d ' ')" \
  -eq "$EXPECTED_LOCAL_PACKAGES"
cmp -s "$ARCHIVE_CODEX_RS/workspace.names" "$ARCHIVE_CODEX_RS/lock.names"
test "$CARGO_TARGET_DIR" = "$ARCHIVE_DIR/target"
cd "$ARCHIVE_CODEX_RS"

测试仍经共享的 run_checked_test 执行。它要求 nextest 确实运行并通过 1 项测试，同时拒绝 Skipping test... 输出；环境 marker 已存在时，导读里的前置断言会直接退出，不会把 fixture 的提前返回记成通过：

set -euo pipefail
SOURCE_ROOT="${SOURCE_ROOT:-/tmp/codex-handbook-final-rust-v0.144.6}"
SOURCE_DIR="$SOURCE_ROOT/codex-rs"
CODEX_HANDBOOK_PART3_HELPER="${CODEX_HANDBOOK_PART3_HELPER:-$PWD/scripts/codex-handbook-part3.sh}"
test -f "$CODEX_HANDBOOK_PART3_HELPER"
source "$CODEX_HANDBOOK_PART3_HELPER"
prepare_codex_part3
trap 'cleanup_codex_part3 "$?"' EXIT
cd "$ARCHIVE_CODEX_RS"

run_checked_test websocket 1 \
  just test --locked -p codex-core --test all --no-capture \
  -E 'test(=suite::websocket_fallback::websocket_fallback_is_sticky_across_turns)'

关键判定不再依赖旧 harness 的 filtered out 文案，而是 nextest 的实际运行数与通过数：

PASS [...] suite::websocket_fallback::websocket_fallback_is_sticky_across_turns
Summary [...] 1 test run: 1 passed

fixture 使用本机 Wiremock/loopback。startup deferred prewarm 产生 1 次 WS GET；第一 turn 再产生 initial + 2 retries，共 3 次 WS GET，随后 fallback；第一、第二 turn 各走 1 次 HTTP POST 并命中 1 次 SSE response。最终计数是 WS_GET=4 / HTTP_POST=2 / SSE_POST=2。

下面这张既有截图记录的是另外两条 Responses WebSocket 恢复测试，不是上面的 sticky-fallback fixture。它只作为同一环境下的命令与输出样本；本节的跨 turn 结论仍以上面的 exact test 和 WS_GET / HTTP_POST / SSE_POST 计数为准。

这项实验只证明同一存活 Session 中，WS retry exhaustion 触发的 HTTP fallback 会跨 turn 保持。它没有覆盖 426、401、中途断流、进程重启、resume、新 Session 或真实外网。

sampling 层还要区分 EOF、invalid image 与 cancellation

第 12 章留下的“解析失败”需要拆回实际 return path：

• unknown typed event、字段不足的 event 与无法形成 item 的 added/done 可以由共享 mapper 返回 Ok(None)；它们不会自动触发 retry。
• malformed SSE envelope 在 SSE reader 里 debug 后继续；malformed WS envelope 也 debug 后继续。两者都没有进入 typed mapper。
• typed mapper 的 error 在 SSE 中先存进 response_error，reader 继续取 event；若随后 EOF，才优先发保存的 error。WS 对相同 mapper error 立即返回。
• SSE premature EOF 发保存的 mapper error 或通用 stream closed before response.completed；idle timeout 发自己的 stream error。WS premature EOF、idle timeout 和 socket read error 也各自在 WS reader 返回。
• core event loop 收到 Some(Err(err)) 会原样结束；若 channel 直接为 None，才由 core 自己生成 stream closed before response.completed。这些路径最终都可能映成可 retry 的 sampling error，但 first observer 不同。

InvalidImageRequest 的 recovery owner 在更外层 run_turn。release build 先记录诊断，再把 last-turn image 替换成文本占位；替换成功就 continue sampling/action loop。它不调用 sampling retry helper，也不占 stream_max_retries。若没有可替换图片，则发 BadRequest Error 并正常离开 run_turn，之后 task 仍是 TurnComplete。debug assertions build 会在同一诊断 helper 处 panic，早于 sanitation；这条 build-mode 差异不能省掉。

显式 cancellation 则沿 or_cancel 或 loop 末尾的 token check 变成 CodexErr::TurnAborted，绕过普通 Error 分支，交给第 7 章已经固定的 Session abort lifecycle。只有这条错误类型会把自然 task return 映成 TurnAborted。

side effect 不随 retry 回滚

sampling replay 没有 transaction boundary。第 12 章已经证明，完整 tool call item 在 future 创建前先更新当前 history；成功的 tool output 随后尝试写入 rollout，但 append 失败只记录错误，不会回滚 live history。若 stream 随后失败并重做 sampling，新的 Prompt 从最新 history 重建；已经写入的 completed item 不会自动回滚。

工具对机器产生的副作用更没有自动 undo。命令可能已经写文件、启动进程或调用外部系统，然后 future 才返回错误。retry 只重做模型采样，不能恢复副作用前的世界状态。是否应该再次执行、补一条失败 output 或要求人工确认，需要第 14 章继续从 handler failure 接手。

当前 drain_in_flight 还有一个不整齐的边界：future Ok 才把 ResponseInputItem 写进 conversation；future Err 调用 error_or_panic，不生成 durable tool output。debug build 在这里 panic；release build 只记录 error，继续 drain 后面的 future。源码没有一套统一的 tool failure recovery 可以替这段行为兜底。

恢复责任矩阵

表中的“local exit”指当前函数怎样交还控制权；最后一列才是用户可见 task lifecycle。成功恢复后，task 当然还可能在更晚阶段遇到另一种错误，因此这里不把“继续”写成完成保证。

到这里，第 12 章交来的 error set 已经按 owner 拆开：auth recovery 停在 client call，HTTP request-open 与完整 sampling 各有预算，WS fallback 修改当前 Session 的 transport state，run_turn 负责 invalid image 与普通 Error，Session 才负责 task terminalization。下一章只需要接住一个更窄的缺口：tool registry、handler 与执行 policy 内部失败以后，什么结果能被可靠地交回模型，什么副作用只能由更外层协调。