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

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

<example> 场景：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 从限速中自动恢复，无需人工干预 </example> <example> 场景：新 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 恢复上次计划" </example> <example> 场景：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 渲染）" </example> <anti-example> 错误: 3 个后台 agent 同时遇到 529 过载，全部重试原因: 后台重试叠加放大服务端压力，529 持续从 2 分钟延长到 15 分钟正确: 后台 session 应直接放弃（exit 0），只记录日志规则: 前台重试 + 后台放弃 = anti-stampede 不对称 </anti-example>

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

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 写入

error-recovery

Safety Notice

Copy this and send it to your AI assistant to learn

Error Recovery

When to Use

When NOT to Use

Patterns

5.1 Rate Limit Recovery [script]

5.2 Crash State Recovery [design]

5.3 Stale Session Daemon [design]

5.4 MCP Reconnection [design]

5.5 Graceful Tool Degradation [design]

5.6 Model Fallback Advisory [design]

5.7 Anti-Stampede Retry Asymmetry [design]

Scripts

Workflow

Output

Usage

Related

Source Transparency

Related Skills

Tool Governance

Execution Loop

Context Memory

Quality Verification