@leviyuan/lodestar 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leviyuan/lodestar",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "publishConfig": {
     "access": "public"
   },

package/src/cards.ts

@@ -171,7 +171,6 @@ interface MainCardOpts {
   turn: number
   model?: string
   effort?: string
-  userText: string
   /** What started this turn. `'scheduled'` adds a top-of-card banner so
    * the user can tell a cron-fired wakeup apart from one of their own
    * messages — the user's message bubble is otherwise the only visual
@@ -200,7 +199,8 @@ export function mainConversationCard(opts: MainCardOpts): object {
       // panels are inserted between them in real time as Claude streams.
       // Note: empty-string content is rejected by CardKit PUT so the
       // thinking element starts with a single space placeholder; the first
-      // real append overwrites it.
+      // real append overwrites it. No echo of the user's message inside
+      // the card — the chat bubble above already shows it.
       elements: [
         ...banner,
         { tag: 'markdown', element_id: ELEMENTS.thinking, content: ' ' },
@@ -595,6 +595,15 @@ function fmtResetIn(date: Date | null): string {
   return `${Math.round(ms / (24 * 60 * 60 * 1000))}d`
 }
 
+/** Human-readable "time since" — clamps sub-minute values to "刚刚". */
+function fmtAgo(timestamp: number): string {
+  const ms = Date.now() - timestamp
+  if (ms < 60_000) return '刚刚'
+  if (ms < 60 * 60 * 1000) return `${Math.round(ms / 60_000)}m 前`
+  if (ms < 24 * 60 * 60 * 1000) return `${Math.round(ms / (60 * 60 * 1000))}h 前`
+  return `${Math.round(ms / (24 * 60 * 60 * 1000))}d 前`
+}
+
 const PEER_STATUS_EMOJI: Record<string, string> = {
   idle: '🟢', working: '⚙️', awaiting_permission: '🔐',
   starting: '🚀', stopped: '⚪',
@@ -623,19 +632,22 @@ export function consoleUsageContent(
     case 'network':
       return `**📊 订阅额度**　拉取失败${usage.reason ? ' — `' + usage.reason + '`' : ''}`
   }
-  // state === 'ok'
+  // state === 'ok' —— stale 时 head 加 "缓存 Xm 前",重置时间加 `~`
+  // 前缀,沿用 omchud HUD 的 stale 标记约定。
+  const staleNote = usage.stale ? ` _· 缓存 ${fmtAgo(usage.fetchedAt)}_` : ''
+  const resetPrefix = usage.stale ? '~' : ''
   const head = usage.subscriptionType
-    ? `**📊 订阅额度** · ${usage.subscriptionType}`
-    : '**📊 订阅额度**'
+    ? `**📊 订阅额度** · ${usage.subscriptionType}${staleNote}`
+    : `**📊 订阅额度**${staleNote}`
   const lines: string[] = [head]
   if (usage.fiveHour) {
     const parts = [`${Math.round(usage.fiveHour.percent)}%`]
-    if (usage.fiveHour.resetsAt) parts.push(`重置 ${fmtResetIn(usage.fiveHour.resetsAt)}`)
+    if (usage.fiveHour.resetsAt) parts.push(`重置 ${resetPrefix}${fmtResetIn(usage.fiveHour.resetsAt)}`)
     lines.push(`　· 5h　${parts.join(' · ')}`)
   }
   if (usage.weekly) {
     const parts = [`${Math.round(usage.weekly.percent)}%`]
-    if (usage.weekly.resetsAt) parts.push(`重置 ${fmtResetIn(usage.weekly.resetsAt)}`)
+    if (usage.weekly.resetsAt) parts.push(`重置 ${resetPrefix}${fmtResetIn(usage.weekly.resetsAt)}`)
     lines.push(`　· 7d　${parts.join(' · ')}`)
   }
   return lines.length === 1 ? '**📊 订阅额度**　_无数据_' : lines.join('\n')

package/src/feishu.ts

@@ -8,6 +8,7 @@
 
 import * as lark from '@larksuiteoapi/node-sdk'
 import { execSync } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
 import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, extname, join } from 'node:path'
@@ -165,32 +166,84 @@ export async function refreshChatList(): Promise<void> {
 }
 
 // ── Outbound: text + card ──────────────────────────────────────────────
-export async function sendText(chatId: string, text: string): Promise<string | null> {
-  try {
-    const res: any = await client.im.message.create({
-      params: { receive_id_type: 'chat_id' },
-      data: { receive_id: chatId, msg_type: 'text', content: JSON.stringify({ text }) },
-    })
-    if (res?.code && res.code !== 0) {
-      log(`feishu: sendText rejected chat=${chatId} code=${res.code} msg=${res.msg}`)
-      return null
+/** Delay schedule for sendText/sendCard SDK retries. Three attempts total
+ * (the leading 0 is the eager first try). Tuned for the bun+axios+lark-SDK
+ * ECONNREFUSED transient we've been seeing — by ~5s the socket pool
+ * usually recovers. Business errors (Feishu code != 0) are NOT retried;
+ * only thrown network errors are. */
+const SEND_RETRY_DELAYS_MS = [0, 1000, 4000]
+
+async function sendViaSdkWithRetry(
+  what: 'text' | 'card',
+  chatId: string,
+  msgType: 'text' | 'interactive',
+  content: string,
+): Promise<string | null> {
+  // Same uuid across retries → Feishu dedupes on its side so a successful-
+  // but-response-lost first attempt doesn't produce a duplicate message.
+  const uuid = randomUUID()
+  let lastErr: unknown = null
+  for (let i = 0; i < SEND_RETRY_DELAYS_MS.length; i++) {
+    if (SEND_RETRY_DELAYS_MS[i] > 0) {
+      await new Promise(r => setTimeout(r, SEND_RETRY_DELAYS_MS[i]))
     }
-    return res?.data?.message_id ?? null
-  } catch (e) { log(`feishu: sendText failed chat=${chatId}: ${e}`); return null }
+    try {
+      const res: any = await client.im.message.create({
+        params: { receive_id_type: 'chat_id' },
+        data: { receive_id: chatId, msg_type: msgType, content, uuid },
+      })
+      if (res?.code && res.code !== 0) {
+        log(`feishu: send${what === 'text' ? 'Text' : 'Card'} rejected chat=${chatId} code=${res.code} msg=${res.msg}`)
+        return null
+      }
+      return res?.data?.message_id ?? null
+    } catch (e) {
+      lastErr = e
+      log(`feishu: send${what === 'text' ? 'Text' : 'Card'} attempt ${i + 1}/${SEND_RETRY_DELAYS_MS.length} chat=${chatId} failed: ${e}`)
+    }
+  }
+  log(`feishu: send${what === 'text' ? 'Text' : 'Card'} chat=${chatId} EXHAUSTED ${SEND_RETRY_DELAYS_MS.length} retries: ${lastErr}`)
+  return null
+}
+
+export async function sendText(chatId: string, text: string): Promise<string | null> {
+  return sendViaSdkWithRetry('text', chatId, 'text', JSON.stringify({ text }))
 }
 
 export async function sendCard(chatId: string, card: object): Promise<string | null> {
+  return sendViaSdkWithRetry('card', chatId, 'interactive', JSON.stringify(card))
+}
+
+/** Last-resort text send that bypasses the lark SDK and uses raw fetch
+ * (which is what cardkit.ts uses and has never had stability issues on
+ * this runtime). Used by callers that need to *surface a failure when
+ * the SDK send path itself is the broken thing* — e.g. `openTurnCard`'s
+ * `sendCard` exhausted retries on ECONNREFUSED and we still owe the
+ * user a visible "your message was lost, please retry" notice. Do not
+ * use this as a general-purpose send; it's the failure-surfacing
+ * channel, not a silent fallback. */
+export async function sendTextRaw(chatId: string, text: string): Promise<string | null> {
   try {
-    const res: any = await client.im.message.create({
-      params: { receive_id_type: 'chat_id' },
-      data: { receive_id: chatId, msg_type: 'interactive', content: JSON.stringify(card) },
+    const token = await getTenantToken()
+    const res = await fetch('https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id', {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        receive_id: chatId,
+        msg_type: 'text',
+        content: JSON.stringify({ text }),
+      }),
     })
-    if (res?.code && res.code !== 0) {
-      log(`feishu: sendCard rejected chat=${chatId} code=${res.code} msg=${res.msg}`)
+    const json = await res.json() as any
+    if (json?.code !== 0) {
+      log(`feishu: sendTextRaw rejected chat=${chatId} code=${json?.code} msg=${json?.msg}`)
       return null
     }
-    return res?.data?.message_id ?? null
-  } catch (e) { log(`feishu: sendCard failed chat=${chatId}: ${e}`); return null }
+    return json.data?.message_id ?? null
+  } catch (e) {
+    log(`feishu: sendTextRaw chat=${chatId} failed: ${e}`)
+    return null
+  }
 }
 
 // ── Reactions ──────────────────────────────────────────────────────────

package/src/session.ts

@@ -34,7 +34,6 @@ interface TurnState {
    * not signal. Ask / permission urgents inside the turn still fire
    * regardless (those genuinely need attention even mid-schedule). */
   trigger: 'user_message' | 'scheduled'
-  userText: string
   thinkingText: string
   toolCount: number
   /** `output` / `isError` are filled in by completeTool — kept on the
@@ -480,12 +479,47 @@ export class Session {
       const ok = await this.start()
       if (!ok) return
     }
+    // Garbage-collect leftover state from a batch the SDK abandoned —
+    // most commonly an AskUserQuestion mid-turn, which makes the SDK
+    // emit `QUEUE remove × N` and drop every msg we'd already
+    // sendText'd into its queue. The daemon doesn't see those remove
+    // events, so `pendingUserMessageCount` and `pendingReactionIds`
+    // stay stuck. If the SDK is idle right now (no turn, no eager-
+    // open in flight) AND init has already fired at least once
+    // (otherwise we'd be in the bootstrap race window where
+    // leftover count IS valid — see wasBusy comment below), the
+    // leftover count is stale and must be cleared BEFORE the
+    // wasBusy computation — otherwise this fresh solo message gets
+    // falsely wrapped `<u>…</u>` and its card closes with
+    // `📨 转交新卡` instead of `✅`.
+    if (this.initCount >= 1 && !this.currentTurn && !this.openingTurn && this.pendingUserMessageCount > 0) {
+      this.pendingUserMessageCount = 0
+      // Release stale ⏳ reactions left on the abandoned batch's
+      // chat messages. addReaction callbacks still in flight will
+      // fall through to the orphan path in the wasBusy branch
+      // below (which deletes whatever rid lands after both maps
+      // are empty).
+      for (const [m, rid] of this.pendingReactionIds) {
+        if (rid) void feishu.deleteReaction(m, rid)
+      }
+      this.pendingReactionIds = new Map()
+    }
     // Capture busy-state SYNC, before any state mutation — this decides
     // whether the message will visibly queue (gets the OneSecond → later
     // CheckMark lifecycle reactions on its Feishu chat message) or
     // eager-open its own card (no reaction needed; the card itself is
     // the acknowledgement).
-    const wasBusy = this.currentTurn !== null || this.openingTurn
+    //
+    // `pendingUserMessageCount > 0` catches the bootstrap race: daemon
+    // just spawned, `initCount` is still 0 so no card is open yet, but
+    // we've already sendText'd a previous user message into the SDK.
+    // The next message lands in the SAME merged-batch SDK queue, so
+    // it IS mid-flight from the SDK's perspective — without this
+    // check, the daemon would mark it as solo (no `<u>` wrap, no ⏳
+    // reaction) and the model would see e.g. "123" + "321" + "1"
+    // glued into a single string "1233211" (2026-05-16 accumulator
+    // bug).
+    const wasBusy = this.currentTurn !== null || this.openingTurn || this.pendingUserMessageCount > 0
     this.pendingUserMessageCount++
     this.lastUserOpenId = userOpenId
     // When the SDK will merge this msg with siblings into a multi-
@@ -496,8 +530,9 @@ export class Session {
     // chars and `<u>1</u><u>45</u>` became "145" to the model
     // (2026-05-16 accumulator test). HTML-tag wrap is visible but
     // models parse `<tag>` boundaries very reliably from training.
-    // Solo (eager-open) msgs don't get wrapped — no sibling, no
-    // merge, no need. Contract declared in CHANNEL_INSTRUCTIONS.
+    // Only the very first solo message of a fresh SDK turn slot
+    // skips the wrap — no sibling, no merge, no need. Contract
+    // declared in CHANNEL_INSTRUCTIONS.
     const wireText = wasBusy ? `<u>${text}</u>` : text
     this.proc!.sendUserText(wireText, files)
     if (wasBusy && msgId) {
@@ -509,11 +544,34 @@ export class Session {
       this.pendingReactionIds.set(msgId, '')
       void (async () => {
         const rid = await feishu.addReaction(msgId, 'OneSecond')
-        if (rid && this.pendingReactionIds.has(msgId)) {
+        if (!rid) return
+        if (this.pendingReactionIds.has(msgId)) {
           this.pendingReactionIds.set(msgId, rid)
+        } else if (this.currentBatchReactionIds.has(msgId)) {
+          // Init handler renamed the sentinel into the batch map while
+          // addReaction was in flight — record the rid there so the
+          // batch's close-time deleteReaction sees it.
+          this.currentBatchReactionIds.set(msgId, rid)
+        } else {
+          // Orphan: both maps cleared (closeTurnCard already released
+          // them) before our add returned. The reaction is now stuck
+          // on the Feishu message with no one tracking it — delete
+          // directly so the user doesn't see a stale ⏳ forever.
+          // (Observed bug 2026-05-16: 8 OneSeconds added during a M0
+          // turn, 2 addReaction callbacks landed after close fired the
+          // release loop, those rids never made it back into either
+          // map → 2 stuck ⏳ in chat.)
+          void feishu.deleteReaction(msgId, rid)
         }
       })()
     }
+    // Mid-turn user messages don't touch the in-flight card — the SDK
+    // queues them and dequeues them on its next turn boundary, at
+    // which point `result` closes the current card with `📨 转交新卡`
+    // and `init` opens a fresh card for the merged batch turn. The
+    // user's own message bubble in the chat (plus the OneSecond ⏳
+    // reaction added above) is the only mid-flight feedback they get;
+    // no card edit, no echo inside the card.
     if (!this.currentTurn && !this.openingTurn && this.initCount >= 1) {
       // Eager open: this message is going to be processed solo (no current
       // turn to merge with on the SDK side, so SDK runs it as its own turn).
@@ -524,7 +582,7 @@ export class Session {
       this.openingTurn = true
       this.pendingUserMessageCount--
       try {
-        await this.openTurnCard(text, userOpenId, 'user_message')
+        await this.openTurnCard(userOpenId, 'user_message')
         this.status = 'working'
       } finally {
         this.openingTurn = false
@@ -744,31 +802,22 @@ export class Session {
       }
       this.initCount++
 
-      // The boot init (initCount === 1) only happens once per spawn and
-      // is claimed by whichever user message gets processed first — that
-      // message's card is opened eagerly in `onUserMessage`, so the boot
-      // init itself opens nothing. EXCEPTION: if a user message landed
-      // before the boot init (rare race during start()), the queue has
-      // an entry — drain it here.
+      // Boot init (initCount === 1) is claimed by `onUserMessage`'s
+      // eager-open path — if a user message landed before the init
+      // arrived, it sits in `pendingUserMessageCount` and we drain it
+      // below; otherwise the init opens nothing. Subsequent inits
+      // (initCount >= 2) mark the start of an SDK-initiated turn:
+      // either the SDK is draining the type-ahead queue we fed it via
+      // `sendUserText` (isUserBatch), or it's a CronCreate /
+      // ScheduleWakeup fire from idle (isScheduledFire).
       //
-      // Subsequent inits (initCount >= 2) mark the start of an SDK-
-      // initiated turn — either the SDK draining its internal type-ahead
-      // queue (we'll have an entry in `pendingUserMessages` mirroring
-      // it) or a CronCreate / ScheduleWakeup fire (queue empty). The
-      // `currentTurn` / `openingTurn` checks guard the race where
-      // `onUserMessage` already eager-opened (or is mid-open) for the
-      // same user message and the SDK emitted an init#≥2 we don't need
-      // to act on. The init handler ALSO claims `openingTurn` for its
-      // own async open so a user message landing during the open
-      // doesn't spawn a duplicate card.
+      // SDK-driven rotation puts the boundary HERE: the previous
+      // turn's `result` already closed the in-flight card with
+      // `📨 转交新卡` (because pendingUserMessageCount > 0). Now we
+      // open a fresh card whose top panel shows the queued messages.
+      // currentTurn should be null at this point (result null'd it);
+      // the openingTurn guard catches the eager-open vs init race.
       if (this.currentTurn || this.openingTurn) return
-      // `pendingUserMessageCount > 0` ⇒ SDK is about to fire an init for a
-      // merged batch of one-or-more user messages we already sendText'd
-      // (the eager-open path didn't claim them because a turn was still
-      // running at the time). Claim the ENTIRE count here — the SDK
-      // collapses them into ONE turn, so only one card opens; any further
-      // messages that arrive after this point will start a fresh count
-      // and a fresh batch.
       const isUserBatch = this.pendingUserMessageCount > 0
       const isScheduledFire = !isUserBatch && this.initCount > 1
       if (!isUserBatch && !isScheduledFire) return
@@ -784,11 +833,7 @@ export class Session {
       this.openingTurn = true
       void (async () => {
         try {
-          await this.openTurnCard(
-            isUserBatch ? '' : '⏰ 定时唤醒',
-            userOpenId,
-            isUserBatch ? 'user_message' : 'scheduled',
-          )
+          await this.openTurnCard(userOpenId, isUserBatch ? 'user_message' : 'scheduled')
           this.status = 'working'
         } finally {
           this.openingTurn = false
@@ -816,7 +861,14 @@ export class Session {
     })
     p.on('result', () => {
       this.accumulateResultStats()
-      void this.closeTurnCard()
+      // SDK-driven rotation: if any mid-turn user messages stacked up
+      // (the SDK is about to dequeue them into a fresh merged-batch
+      // turn), close the in-flight card with `📨 转交新卡` so the user
+      // sees the cut. The next `init` for that batch turn will open a
+      // new card whose top panel echoes those queued messages. No
+      // pending → natural ✅ close.
+      const suffix = this.pendingUserMessageCount > 0 ? '📨 转交新卡' : undefined
+      void this.closeTurnCard(suffix)
       this.status = 'idle'
     })
     p.on('exit', ({ code, signal, expected }: any) => {
@@ -880,17 +932,35 @@ export class Session {
     return this.proc?.lastContextWindow ?? 200_000
   }
 
-  private async openTurnCard(userText: string, userOpenId: string, trigger: 'user_message' | 'scheduled'): Promise<void> {
+  private async openTurnCard(userOpenId: string, trigger: 'user_message' | 'scheduled'): Promise<void> {
     const turn = ++this.turnCounter
     const card = cards.mainConversationCard({
       sessionName: this.sessionName,
       turn,
       effort: 'max',
-      userText,
       kind: trigger,
     })
     const messageId = await feishu.sendCard(this.chatId, card)
-    if (!messageId) { log(`session "${this.sessionName}": openTurnCard sendCard failed`); return }
+    if (!messageId) {
+      log(`session "${this.sessionName}": openTurnCard sendCard EXHAUSTED retries — surfacing via raw text`)
+      // sendCard already retried 3× through the SDK. If it still came back
+      // null we're either on a sustained SDK-axios outage or a Feishu
+      // business reject. Either way the user just sent us a message and
+      // it's gone into a black hole — surface that explicitly so they
+      // know to resend instead of waiting for a reply that won't come.
+      // Use raw fetch (not sendText) because if the SDK is the broken
+      // thing we'd be doomed to silence otherwise.
+      await feishu.sendTextRaw(
+        this.chatId,
+        '❌ 创建对话卡片失败 (Feishu SDK 重试 3 次后仍连不上)。你这条消息没能送到 Claude,请稍后重发。',
+      )
+      // Halt Claude — we already wrote the user text to its stdin in
+      // onUserMessage, but with no card to stream into the response would
+      // be lost. Interrupt now so the model doesn't burn tokens producing
+      // an answer that has nowhere to land.
+      this.proc?.sendInterrupt()
+      return
+    }
     let cardId: string
     try { cardId = await cardkit.convertMessageToCard(messageId) }
     catch (e) { log(`session "${this.sessionName}": id_convert failed: ${e}`); return }
@@ -899,7 +969,6 @@ export class Session {
       messageId,
       userOpenId,
       trigger,
-      userText,
       thinkingText: '',
       toolCount: 0,
       toolByUseId: new Map(),

package/src/usage.ts

@@ -26,6 +26,18 @@
  * 调用共享同一份快照,不打 API。in-flight 去重保证并发的多个
  * 群同时唤出控制台时只触发一次后台请求。
  *
+ * Stale fallback (照 omchud HUD 规则): 单独记最后一次成功拉到的
+ * `state:'ok'` 快照,本次拉取失败 (network/rate_limited/auth_failed)
+ * 且距上次成功 <= MAX_STALE_MS (15 分钟) 时,返回上次的 ok 快照并打
+ * `stale:true` 标签,卡片层加 "缓存 Xm 前" 提示。这是 no_fallbacks
+ * 规则的显式例外 —— 用户明确要求订阅额度面板用缓存兜底,因为短暂
+ * 网络抖动里把面板上的数字抹成红色"拉取失败"信息密度反而更低。
+ *
+ * 429 指数退避: 收到 rate_limited 时增加 rateLimitedCount,下次允许
+ * 实拉的时间设为 now + CACHE_TTL_MS * 2^(count-1),封顶 5 分钟。
+ * 退避窗口内的 readUsage 直接走 stale fallback,不打 API。任何非 429
+ * 的响应 (ok / network / auth_failed) 都会重置计数器。
+ *
  * 参考实现: oh-my-claudecode HUD `src/hud/usage-api.ts`。这里只保留
  * Lodestar 用得到的最小子集 —— 不处理 keychain、不处理第三方网关
  * (z.ai / MiniMax)、不处理 enterprise 货币换算、不做多文件 cache 与
@@ -42,6 +54,11 @@ const TOKEN_REFRESH_URL = 'https://platform.claude.com/v1/oauth/token'
 const OAUTH_CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e'
 const API_TIMEOUT_MS = 10_000
 const CACHE_TTL_MS = 60_000
+/** 失败时回退到上次成功快照的最大年龄。超过此值就不再用缓存兜底,
+ * 显示真实失败状态 —— 跟 omchud HUD 的 MAX_STALE_DATA_MS 对齐。 */
+const MAX_STALE_MS = 15 * 60 * 1000
+/** 429 退避封顶,跟 omchud HUD 的 MAX_RATE_LIMITED_BACKOFF_MS 对齐。 */
+const RATE_LIMITED_MAX_BACKOFF_MS = 5 * 60 * 1000
 
 function credentialsPath(): string {
   return join(homedir(), '.claude', '.credentials.json')
@@ -73,10 +90,29 @@ export type UsageSnapshot =
       fiveHour: UsageWindow | null
       weekly: UsageWindow | null
       fetchedAt: number
+      /** true 时本快照不是这次实拉的,而是 lastOk 兜底回来的旧数据。
+       * 卡片层据此显示 "缓存" 标记 + 重置时间加 `~` 前缀。 */
+      stale?: boolean
     }
 
+type UsageSnapshotOk = Extract<UsageSnapshot, { state: 'ok' }>
+
 let cache: { data: UsageSnapshot; at: number } | null = null
+/** 最近一次 state:'ok' 的快照,用于失败时兜底。和 cache 分开存:
+ * cache 是短时去重 (60s),lastOk 是长尾兜底 (15min)。 */
+let lastOk: { snapshot: UsageSnapshotOk; at: number } | null = null
 let inFlight: Promise<UsageSnapshot> | null = null
+/** 连续 429 计数,用于指数退避;遇到任何非 429 响应就重置为 0。 */
+let rateLimitedCount = 0
+/** 在这个时间戳之前不打 API,直接走 stale fallback。 */
+let rateLimitedUntil = 0
+
+function rateLimitedBackoffMs(count: number): number {
+  return Math.min(
+    CACHE_TTL_MS * Math.pow(2, Math.max(0, count - 1)),
+    RATE_LIMITED_MAX_BACKOFF_MS,
+  )
+}
 
 function readCredentials(): OAuthCredentials | null {
   const path = credentialsPath()
@@ -246,18 +282,46 @@ async function fetchUsage(): Promise<UsageSnapshot> {
   }
 }
 
+/** 失败快照 → 如果 MAX_STALE_MS 内还有 lastOk,就返回 lastOk 的副本
+ * (打 stale 标);否则透传失败快照。state:'ok' 走 fast path 原样返回。 */
+function withStaleFallback(snapshot: UsageSnapshot): UsageSnapshot {
+  if (snapshot.state === 'ok') return snapshot
+  if (lastOk && Date.now() - lastOk.at < MAX_STALE_MS) {
+    return { ...lastOk.snapshot, stale: true }
+  }
+  return snapshot
+}
+
 /** 返回订阅额度快照。CACHE_TTL_MS 内的重复调用读缓存;并发请求去重为
- * 单次后台 fetch。永不抛出 —— 失败状态由 `state` 字段表达,卡片层
- * 按 state 分支渲染。 */
+ * 单次后台 fetch。拉取失败但 lastOk 仍在 MAX_STALE_MS 内时,回退到
+ * lastOk 并打 stale 标。连续 429 走指数退避,退避窗口内不打 API。
+ * 永不抛出 —— 失败状态由 `state` 字段表达,卡片层按 state 分支渲染。 */
 export async function readUsage(): Promise<UsageSnapshot> {
-  if (cache && Date.now() - cache.at < CACHE_TTL_MS) return cache.data
+  // 429 退避窗口内不打 API。cache 里可能存的就是 rate_limited 失败态,
+  // withStaleFallback 会自动用 lastOk 顶上(15min 内)。
+  if (Date.now() < rateLimitedUntil) {
+    return withStaleFallback(cache?.data ?? { state: 'rate_limited' })
+  }
+  if (cache && Date.now() - cache.at < CACHE_TTL_MS) return withStaleFallback(cache.data)
   if (inFlight) return inFlight
   inFlight = fetchUsage()
-    .then(d => { cache = { data: d, at: Date.now() }; inFlight = null; return d })
+    .then(d => {
+      cache = { data: d, at: Date.now() }
+      if (d.state === 'ok') lastOk = { snapshot: d, at: Date.now() }
+      if (d.state === 'rate_limited') {
+        rateLimitedCount += 1
+        rateLimitedUntil = Date.now() + rateLimitedBackoffMs(rateLimitedCount)
+      } else {
+        rateLimitedCount = 0
+        rateLimitedUntil = 0
+      }
+      inFlight = null
+      return withStaleFallback(d)
+    })
     .catch(e => {
       log(`usage: fetchUsage threw: ${e}`)
       inFlight = null
-      return cache?.data ?? { state: 'network', reason: String(e) }
+      return withStaleFallback({ state: 'network', reason: String(e) })
     })
   return inFlight
 }