Error Recovery

Error Recovery

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

When to Use

When NOT to Use

Patterns

5.1 Rate Limit Recovery [script]

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

实现要点：

→ 详见

5.2 Crash State Recovery [design]

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

需要检查的残留状态：

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 静默死亡并抢救认知状态。

实现要点：

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

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

5.4 MCP Reconnection [design]

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

实现要点：

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

5.5 Graceful Tool Degradation [design]

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

实现要点：

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

5.6 Model Fallback Advisory [design]

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

实现要点：

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

5.7 Anti-Stampede Retry Asymmetry [design]

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

规则：

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

Scripts

| 脚本 | 用途 | |------|------| | rate-limit-recovery.sh | 扫描 tmux 自动恢复 |

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 响应正常）
   → 成功 → 恢复执行
   → 失败 → 上报给用户，附带错误类型 + 已尝试的恢复策略 + 失败原因

场景：tmux agent 遇到 429 限速 检测: rate-limit-recovery.sh 执行 tmux capture-pane -t $pane -p -S -20 匹配: 输出含 "Rate limited. Press Enter to retry" 二次验证: 重新 capture 最后 5 行，不含 [y/N]、confirm 等确认提示 动作: 发送 Enter 键恢复执行 结果: Agent 从限速中自动恢复，无需人工干预

场景：新 session 启动发现上次 crash 残留 检测 1: sessions/abc123/ralph.json active=true，last_checked_at 距今 3 小时（>7200s 阈值） 动作 1: 设 active=false, deactivation_reason="stale" 检测 2: .claims/src_auth.lock 已存在 20 分钟（>15min 阈值） 动作 2: 自动删除过期 lock 检测 3: .working-state/current-plan.md 存在 动作 3: additionalContext 注入"请先读取 .working-state/current-plan.md 恢复上次计划"

场景：MCP 工具断连后指数退避重连 触发: agent 调用 mcp__firecrawl__scrape，返回 ECONNREFUSED 重试: 1s → 2s → 4s 间隔重试 3 次（第 3 次成功） 状态: 记录到 sessions/xxx/mcp-retry-firecrawl.json {attempt: 3, last_attempt_ts: ...} 失败路径: 5 次全部失败 → 注入 "[MCP FALLBACK] Firecrawl 失败，可用 WebFetch（不支持 JS 渲染）"

错误: 3 个后台 agent 同时遇到 529 过载，全部重试 原因: 后台重试叠加放大服务端压力，529 持续从 2 分钟延长到 15 分钟 正确: 后台 session 应直接放弃（exit 0），只记录日志 规则: 前台重试 + 后台放弃 = anti-stampede 不对称

Output

| 输出 | 说明 | |------|------| | recovery log entries | 每次恢复操作记录到 logs/error-recovery.log，含时间戳、pane、错误类型、执行动作、结果 | | restored ralph.json | crash 恢复后 ralph.json 状态回到最后一致的 checkpoint，迭代计数器和任务列表保留 | | cleaned lock files | 清除残留的 .lock 文件（如 ralph.lock、session.lock），防止后续 session 启动被阻塞 |

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

| Skill | 关系 | |-------|------| | tool-governance | error-recovery 的错误追踪数据（连续失败次数、错误类型分布）喂给 tool-governance 做工具降级决策 | | execution-loop | Ralph crash 后由 error-recovery 恢复 ralph.json 状态，execution-loop 从断点继续执行 | | context-memory | crash 恢复时 handoff state 由 context-memory 保障跨 session 存活，error-recovery 负责触发 handoff 写入 |

在 .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 渲染，适合静态页面）。"}}