[mindfn]

为什么

KD-22（吴浪 09-23）：超时是 dispatch 执行失败的一种原因，应该按正常失败流程处理。之前一个成员最多有三层超时，各自收尾，结果互相矛盾：

• cli-spawn 的无输出定时器：R 记为 failed，原因 PROVIDER_EXECUTION_FAILED。
• invoke-single-cat 外层的 2× 定时器：R 记为 failed / provider_error；如果超时发生在等 session custody 的时候，R 甚至记成 completed。
• carrier 自带的定时器（Codex app-server 空闲中断、tmux 空闲、AGY --print-timeout）：只发 status，R 记为 completed。

而 TurnExecution 那边又记成 invocation_timeout。

KD-24：代码里 CLI_TIMEOUT_MS 的默认值本来就是 0，文档却写着「默认 30 分钟」。

设计是 F117 Phase J 的 J1 和 J4，已由砚砚复审（…1156、…1174），对应路线 Phase 4。

做了什么

1. J1：更正说明（9ce5e8eaa）

.env.example、两份环境变量文档、F254 文档和 FreshnessInvocationStateStore 的注释统一改成「默认 0，即不超时」。代码默认值不变。

2. J4：每个成员只有一个超时，触发后按停止处理（aa4b29a17）

• 唯一的定时器：MemberOutputTimeout，在 invoke-single-cat 里对每个成员跑一次。
  • 只有真正的输出才重新计时：文字、工具调用和结果、thinking、rich block。provider/liveness 信号、status 和各类诊断都不算，成员没法靠心跳续命。
  • 进程还在占用 CPU 时顺延，但距离上次输出最多 2×CLI_TIMEOUT_MS。是否占用 CPU，看 cli-spawn 按 invocation 登记的存活探针（ProcessLivenessProbe.activity()，只看 CPU 增长，与最近有没有 stdout 无关）。没有登记进程的接入不顺延。
  • CLI_TIMEOUT_MS=0 时不布防。
• 触发 = 停止：定时器先把诊断交给 route，再由 QueueProcessor 注入的 stopMember 做一次同步比对：只有槽位里还是布防时那次执行（父执行 ID）时，才会 cancel(…, 'timeout')。所以旧一轮遗留的定时器不会停掉后来占用同一槽位的新一轮。之后这次执行按正常路径自己收尾，不会被广播成「用户停止」。
• 结局：
  • R：failed，原因 timeout，附带诊断和一句「响应超时：N 分钟没有任何输出，已停止。」。原来分散在 route-serial 两处、route-parallel 一处的 R 终态规则，收拢成一个 resolveResponseTerminal。
  • TurnExecution：failed / timeout。
  • 队列：R 提交之后，route 补发一条带诊断的 error 事件，QueueProcessor 据此把这个成员记为失败。resolveFinalStatus 和 disposition 的 isCanceled 都不把 timeout 墓碑算作用户取消。
  • 路由信号：timeout 计为 provider_timeout。旧记录里的 invocation_timeout 仍按 provider_timeout 读。
  • 同一轮的其他成员照常跑完。
• 删掉的：
  • 外层 2× 定时器和 invocation_timeout 路径。
  • cli-spawn、tmux 不再默认读 CLI_TIMEOUT_MS。它们的超时只留给显式传 timeoutMs 的调用（比如 opencode 自动审批探测），成员派发从来不传。
  • AGY 不再传 --print-timeout（它的默认值是 0，等整轮跑完）。
  • Codex app-server 不再传空闲超时。
  • feat(F153 Phase J Slice J-A AC-J2): wire DARE + Codex + CatAgent native tool ids zts212653/clowder-ai#774 的重试收窄到「未收到首帧」的启动超时（isCliStartupTimeoutError），保留 tmux 首事件看门狗在恢复会话时的重试；成员开始输出之后的静默，不会再被吞掉重跑。

3. 文档（d70dc356c）

F117 Phase J 新增「J4 实现」一节，只写和设计的出入。CLI_TIMEOUT_MS 的配置说明改成成员无输出超时的实际含义。

和设计的出入

• SDK 接入不顺延：它的引擎子进程由 SDK 自己拉起，我们拿不到进程号，按设计「没有进程号的接入不顺延」处理。以前 SDK 接入只受外层 2× 定时器约束，3001 上是 60 分钟；现在是 CLI_TIMEOUT_MS，也就是 30 分钟没有任何输出就停。Claude Code 的 Bash 工具本身 10 分钟封顶，更长的命令本来就该交给托管命令。
• cli-spawn、tmux 保留可选超时：设计写的是删除「cli-spawn 为 invocation 设的无输出定时器」。实际只去掉了对 CLI_TIMEOUT_MS 的默认读取，保留显式调用方用的机制，因为 opencode 自动审批探测依赖它。
• Codex app-server 客户端的 timeoutMs 选项：已经没有调用方，留待之后清理，这次不扩大改动。
• 不在这次范围的计时器（A2A、bg、ACP、Antigravity、PTY，见设计里的表）：保持现状，等 Landy 决定是否并入（…000465）。

验证

在 develop_base 6824f8445 + 本 PR + #198 的清单修复这棵树上，完全照运行实例自己的构建流程跑（/tmp/f117-p4-verify.sh）。#198 当时还没合入，这里带的是它的临时 cherry-pick，内容与后来合入的 c2ebff168 相同；本 PR 现已变基到 8a77b9bf1，代码与验证时一致。

• 构建：pnpm install --frozen-lockfile、shared、MCP、API、web next build 全部通过（next build 用时 134 秒）。
• API 公开测试全量：6 个分片，一个一次性 Redis。和 Phase 3 的候选运行对比（那时 develop_base 还没有 test(infra): a test run never reaches the running instance's Redis #197、fix(f247): back off the personal Chrome reply poll while the Host Adapter is unavailable (cherry-pick of upstream #1531) #193）：
  • 候选 23431 个用例，基线 23454 个。差异来自 test(infra): a test run never reaches the running instance's Redis #197、fix(f247): back off the personal Chrome reply poll while the Host Adapter is unavailable (cherry-pick of upstream #1531) #193 对测试的改动，以及本 PR 新增和改写的测试。
  • 基线原有的 2 条失败都还在，此外只多出一条：api-instance-lease.test.js 的「连续续约失败超过宽限窗口后失效（P1-B）」。这个测试用的是假 Redis，心跳 5ms，只等 80ms，6 个分片并行的负载下心跳来不及跳够 3 次。本 PR 没有改任何租约相关的文件，同一棵树上单独跑 5 次都是 11/11 通过。判断为负载造成的时序抖动，不算新增失败。
• Phase 4 专项测试：
  • 1398-phase4-member-output-timeout（7）：哪些消息算输出、CPU 顺延和 2× 上限、CLI_TIMEOUT_MS=0。
  • 1398-phase4-member-timeout-stop（7）：走真实的 route 派发，父执行 ID 和子轮 ID 不同。
    • 超时的成员被停下：墓碑原因是 timeout，R 和 TurnExecution 都是 failed / timeout，诊断保留。
    • 同一轮的其他成员照常跑完，串行和并行两种都测了。
    • 旧一轮遗留的定时器不会停掉新一轮。
    • 队列聚合时不把超时算成用户取消。
  • 改写：invocation-timeout-guard（原来测外层 2× 定时器，现在测成员超时，6 条）、gemini-agent-service（AGY 不再带 --print-timeout）、f254-provider-native-freshness（Codex app-server 不再自己按超时中断）。
  • 以上在 8 路并发下全部通过。
• 周边套件：cli-spawn、tmux、存活探针、codex-app-server、route-serial/parallel、invocation-tracker 等受影响文件，在全量对比里都通过。

回退兼容

• 只新增了取值：R 的 reason 和 TurnExecution 的 terminalReason 都是自由字符串，旧版本能照常读 timeout；诊断写在 R 已有的 metadata.timeoutDiagnostics 字段里。队列和存储格式都没有变化。
• 回退之后，旧的三层定时器会回来，行为回到改动之前；已经写下的超时记录照常显示为失败。

[宪宪/claude-opus-5-5🐾]

🤖 Generated with Claude Code