Error Recovery

Agent session 的错误恢复：限速恢复、crash 状态恢复、MCP 断连、模型降级。

When to Use

• tmux agent 限速后挂死 → Rate limit recovery
• Session crash 后恢复进度 → Crash state recovery
• 模型反复失败 → Model fallback advisory

When NOT to Use

• 工具重试 → 用 tool-governance
• Agent 提前停止 → 用 execution-loop

Patterns

5.1 Rate Limit Recovery [script]

周期性扫描 tmux pane 内容，检测限速关键词（429 / "too many requests" / "usage limit"），限速解除后自动发送按键恢复。

实现要点：

• 扫描：tmux capture-pane -t "$pane" -p -S -20 取最后 20 行，grep rate.?limit|429|too many requests|usage limit
• 二次验证（关键）：发送 Enter 前重新 capture 最后 5 行，如果匹配 \[y/N\]|\[yes/no\]|confirm|delete|overwrite|force push，拒绝发送——此时 pane 内容已从限速提示变成了破坏性确认
• 轮询间隔 60 秒，PID 文件防多实例

→ 详见

5.2 Crash State Recovery [design]

新 session 启动时扫描残留状态，可恢复的从断点继续，损坏的回滚。

需要检查的残留状态：

• sessions/*/ralph.json：active=true 且 last_checked_at 超过 7200 秒（2 小时）→ 设 active=false, deactivation_reason="stale"
• .claims/*.lock：超过 15 分钟未释放 → find .claims -name "*.lock" -mmin +15 -delete
• .working-state/current-plan.md：存在则注入"上次 session 有中断的计划"到 additionalContext

Claude Code 自身的 conversationRecovery.ts 已处理消息链修复（孤立 tool_use 补 placeholder），hook 只需聚焦 ralph.json 和 lock 这些外部状态。

无脚本时：新 session 开始时手动执行 find .claims -name "*.lock" -mmin +15 -delete 和检查 cat sessions/*/ralph.json | grep active。 → 详见

5.3 Stale Session Daemon [design]

检测 session 静默死亡并抢救认知状态。

实现要点：

• Heartbeat 写入：PostToolUse hook 异步写 date +%s > sessions/$SESSION_ID/heartbeat
• Daemon 每分钟检查：heartbeat age > 300 秒且 tmux has-session -t $SESSION 失败 → session 死亡
• 抢救：从 transcript 提取未保存的发现，写入 sessions/$SESSION/handoffs/scavenged.md，设 status 为 scavenged

与 crash recovery 的区别：crash recovery 恢复执行状态，stale session daemon 抢救认知状态。

无 daemon 时：手动检查 tmux ls 和对比 sessions/*/heartbeat 时间戳识别死 session。 → 详见

5.4 MCP Reconnection [design]

检测 MCP 工具调用的连接错误并重连。

实现要点：

• 错误模式：grep ECONNREFUSED|ECONNRESET|EPIPE|MCP.*disconnect|transport.*closed|server.*not.*running
• 指数退避：1<<(attempt-1) 秒 → 1, 2, 4, 8, 16 秒
• 上限 5 次，状态跟踪：sessions/$SESSION_ID/mcp-retry-$TOOL.json 含 {attempt, last_attempt_ts}
• 超过上限 → 注入 fallback 建议（替代工具或提示用户重启 MCP server）
• Claude Code 没有 MCP restart API，hook 只能建议

无脚本时：手动 npx @anthropic-ai/claude-code mcp restart <server> 或重启 Claude Code session。 → 详见

5.5 Graceful Tool Degradation [design]

工具连续失败后自动注入替代工具建议。

实现要点：

• 映射表：.working-state/fallback-tools.md（如 mcp__firecrawl__scrape → WebFetch，注明能力差异）
• PostToolUse hook：regex 检测 error|ECONNREFUSED|not found|command not found
• 失败计数：sessions/$SESSION_ID/fail-count-$TOOL.txt，连续 2 次失败后查映射表注入降级建议
• 成功使用后重置失败计数

无脚本时：工具连续失败 2 次后，agent 应主动尝试替代工具（如 Firecrawl 不可用时用 WebFetch）。 → 详见

5.6 Model Fallback Advisory [design]

模型连续失败时建议升级模型。

实现要点：

• 状态文件：sessions/$SESSION_ID/failure-tracker.json 含 {consecutive_failures, current_model}
• 阈值：连续 3 次失败触发升级建议（haiku → sonnet → opus），成功后重置计数
• 529 vs 429：429 等一下就好（honoring retry-after），529 需要换模型
• 限制：StopFailure hook 通过 additionalContext 建议 agent，无法直接切换模型
• Subagent 架构中可实现真正的自动切换：定义 analyzer-haiku 和 analyzer-sonnet 两个 agent，coordinator 失败后用更高模型的 agent 重试

无脚本时：模型连续失败 3 次后，手动在 prompt 中指定 --model sonnet 或切换 subagent 的 model 字段。 → 详见

5.7 Anti-Stampede Retry Asymmetry [design]

前台/后台对 529 的处理刻意不对称。

规则：

• 前台任务遇 529 → 重试最多 3 次，honoring retry-after header
• 后台任务（summary、compaction、async hook）遇 529 → 立即放弃，不重试
• async hook 设 curl --max-time 5，超时 exit 0 静默退出

原因：后台任务丢失可容忍，但后台重试会在系统最脆弱的时候叠加负载。 → 详见

Scripts

Workflow

1. 检测错误类型（rate limit / crash / MCP disconnect / model failure）
   ⚠ 先查 ralph.json 和 lock 文件判断错误是暂时性还是永久性。
     永久性错误（auth 401/403、PTL）直接上报，不进入重试。

2. 按错误类型选择恢复策略（不同错误码的恢复路径独立，不共享重试计数）
   → rate limit (429): 扫描 tmux pane，二次验证内容后发送 Enter
   → crash: 读取 ralph.json 残留状态，清理过期 lock，从断点恢复
   → MCP disconnect: 指数退避重连，5 次失败后降级到本地工具
   → model failure (529): 3 次失败后建议升级模型或切换 provider

3. 区分前台/后台重试
   前台 session → 执行重试（honors retry-after）
   后台 session → 记录错误后放弃，不重试（anti-stampede）

4. 执行恢复

5. 验证 session 状态（ralph.json 一致、lock 文件已清理、pane 响应正常）
   → 成功 → 恢复执行
   → 失败 → 上报给用户，附带错误类型 + 已尝试的恢复策略 + 失败原因

Output

Usage

在 .claude/settings.json 中配置 hook：

{
  "hooks": {
    // Crash recovery：新 session 启动时扫描残留状态
    "UserPromptSubmit": [
      {
        "hooks": [{
          "type": "command",
          "command": "bash crash-recovery-check.sh"
        }]
      }
    ],
    // MCP 错误追踪 + 工具降级建议
    "PostToolUse": [
      {
        "hooks": [{
          "type": "command",
          "command": "bash error-tracker.sh"
        }]
      }
    ],
    // Stale session heartbeat（async，不阻塞 agent）
    "PostToolUse": [
      {
        "hooks": [{
          "type": "command",
          "command": "bash heartbeat-write.sh",
          "async": true
        }]
      }
    ]
  }
}

Hook 输出格式：

Crash recovery 发现残留状态时：

{"decision": "allow", "hookSpecificOutput": {"additionalContext": "[CRASH RECOVERY] 检测到上次 session 残留: ralph.json active=true (stale 3h), 2 个过期 lock 已清理, .working-state/current-plan.md 存在。请先读取 .working-state/current-plan.md 恢复上次计划。"}}

MCP 重连失败后的 fallback 建议：

{"decision": "allow", "hookSpecificOutput": {"additionalContext": "[MCP FALLBACK] mcp__firecrawl__scrape 连续失败 5 次 (ECONNREFUSED)。可用替代: WebFetch（不支持 JS 渲染，适合静态页面）。"}}

Related