@leviyuan/lodestar 0.1.8 → 0.1.10

package/README.md

@@ -4,55 +4,67 @@
 
 # 夜航星 (Lodestar)
 
-**在你最熟悉的飞书群里，开一段不熄灯的 Claude Code 会话。**
+**把 Claude Code 装进你的飞书群。一个群 = 一个项目 = 一段不熄灯的对话。**
 
-## 项目哲学
+离开终端,但不离开 Claude Code。手机上、地铁里、半夜的床上,你只要拇指能点字,Claude 就在另一头跑着。
 
-AI 不是帮手，是倍率。它放大的不是体力，是你——你的直觉、判断和品味，每一样都被乘以一个你以前不敢想的系数。最终走多远，取决于被放大的你有多强。
+## 它为什么存在
 
-夜航星让这件事真正发生：在你思考的地方接住想法，在你转身之后继续把它推向终点。一个群，一个项目，一段不熄灯的对话。你醒着它在听，你睡了它还在跑。
+AI 不是帮手,是倍率。它放大的不是体力,是你——你的直觉、判断和品味,每一样都被乘以一个你以前不敢想的系数。最终走多远,取决于被放大的你有多强。
+
+夜航星让这件事真正发生:在你思考的地方接住想法,在你转身之后继续把它推向终点。**你醒着它在听,你睡了它还在跑。**
+
+## 你会得到什么
+
+- 🌊 **真·流式卡片** — 飞书 Card Kit v1 streaming,Claude 一个 token 一个 token 地打在同一张卡片里,不是发一堆零碎消息刷屏。
+- 🧠 **思考过程透明** — `thinking` 流式渲染,turn 结束后自动收起为可展开面板。每次工具调用也是一格折叠面板:折起是概述,展开看完整 input/output。
+- 🔐 **权限审批就地完成** — 需要授权的工具调用,**原地**升级为 🔐 等审批状态,三颗按钮 `允许 / 始终允许 / 拒绝` 直接嵌在面板里。不弹独立卡片,不破坏时序。点完按钮,后续 output 接在同一条线上继续往下走。
+- ❓ **结构化追问** — Claude 的 `AskUserQuestion` 在群里呈现为可点击选项行;不满意?直接在群里**打字回答**,daemon 会把自由文本当作 custom answer 发回去。多题串行,有进度计数和"已答 N 题"折叠历史。
+- 📦 **状态面板一键唤出** — 发 `hi` 弹一张控制台:model、上下文占用 %、累计 tokens/cost、上一轮 delta、session id、订阅额度(5h / 7d 真实 utilization,直读 Anthropic 官方 OAuth Usage API,凭据走 `~/.claude/.credentials.json`,token 过期自动 refresh)、本机所有活跃项目并列展示。
+- 📎 **图片 / 文件双向互传** — 用户在群里发图/文件,Claude 通过消息里的 `[file: /abs/path]` 提示就能读;Claude 在回复里写 `[[send: /abs/path]]`,标记被剥离,文件以独立消息发回群里。出站路径走 realpath + 白名单校验,只允许工作目录、`/tmp/lodestar-*`、inbox 三块,`/etc`、`~/.ssh`、`~/.config` 即使被符号链接绕也拒绝。
+- 📲 **加急锁屏推送** — 需要你回答问题、需要你批准操作、一轮跑完了——三种关键时刻自动触发飞书"应用内加急",直接打穿勿扰、亮屏推送。卡片摘要会同步改写成具体待办("🔐 等审批: Bash · rm -rf …"、"❓ 待回答 3 题: …"),锁屏一瞥就知道发生了什么。
+- 🗂 **多项目并发** — 一个 daemon 同时持有 N 个飞书群 ↔ N 个 Claude session。状态面板能跨群看到所有活跃项目和它们的 uptime,在群 A 里就能查群 B 在干嘛。
+- 🔄 **不丢上下文** — 每次 `system/init` 落盘 SDK session_id;daemon 被 systemd 重启、机器断电、手抖 kill 进程,下次 `restart` 或自动复活都 `--resume` 到同一段对话,Claude 不知道你离开过。
+- 🛡 **后台守护级稳定性** — 单 PID 锁、WS pong watchdog(180s 无心跳自杀,交给 systemd 拉起)、5s 重投 stale 消息丢弃、200 条 message_id 去重、SIGTERM 优雅写盘、`alive marker` 区分"我自己挂的"和"被用户主动 kill 的"——后者不会被复活。
 
 ## 怎么用
 
-每个飞书群对应一个 Claude 会话。**群名 = `~/` 下的项目目录名**。
+每个飞书群对应一个 Claude 会话。**群名 = `~/` 下的项目目录名**。这套绑定是骨架,新群第一次发消息时,daemon 会自动 `mkdir -p ~/{群名}` + `git init` 把项目骨架打起来,**开新群 = 开新项目**。
 
-- 在群里发任意文字 — Claude 接管这一轮，回复以**流式打字机**实时渲染在一张飞书卡片里。
-- 思考过程、每一次工具调用都在卡片里被收纳为**可展开折叠面板**：折起来是概述，展开是详情。你随时能审阅它在做什么。
-- 需要授权的操作（执行命令、修改文件……）**就在原来那一格工具调用面板里**升级为 🔐 等审批状态，三颗按钮 `允许` / `始终允许` / `拒绝` 直接内嵌在面板里 — 不再弹独立卡片，决策结果与后续 output 串在同一条时序里。默认 `bypassPermissions`，所以这一格只在 SDK 真的拦下来时才出现。
-- **图片、文件双向互传**：用户发到群里的图/文件，Claude 通过消息里的 `[file: /abs/path]` 提示就能读；Claude 想把文件发回来，在回复任意位置写 `[[send: /abs/path]]`，标记会被剥离，文件以独立消息出现在群里。出站路径限制在该会话的工作目录、`/tmp/lodestar-*` 与 inbox 之内，`/etc`、`~/.ssh`、`~/.config` 等敏感目录被白名单拒绝。
-- 一轮跑完，卡片合上、可转发；下一句话开新一轮。
+在群里发任意文字,Claude 接管这一轮。回复以流式打字机渲染在一张卡片里,工具调用、思考过程、权限审批、追问选项,全都收纳在这张卡片的不同面板里——一目了然,可转发,可回看。
+
+下一句话开新一轮卡片。
 
 ### 文本控制指令
 
-直接发这四个**裸词**（不需要斜杠，不区分大小写），daemon 拦截、不转发给 Claude：
+直接发这四个**裸词**(不需要斜杠,不区分大小写),daemon 拦截、不转发给 Claude:
 
 | 指令 | 行为 |
 | --- | --- |
-| `hi` | 未运行时启动；运行中弹一张**状态卡片**（model · 上下文占用 · 累计 tokens/cost · 上一轮 delta · session id） |
-| `kill` | 优雅关闭 Claude 进程；记住 `sessionId`，下次 `restart` 还能 resume |
-| `restart` | 用上一次的 `sessionId` 重启会话（保留上下文） |
-| `clear` | 杀掉进程并启动一个全新 session（等价于 Claude Code 的 `/clear`） |
-
-> 这四个词被全局保留：在群里发 "hi" 当问候也会触发控制台卡片，不会到 Claude 那边。换来的是手机上单手打字的便利。
+| `hi` | 未运行时启动;运行中弹一张**状态卡片** |
+| `kill` | 优雅关闭 Claude 进程;记住 `sessionId`,下次 `restart` 还能 resume |
+| `restart` | 用上一次的 `sessionId` 重启会话(保留上下文) |
+| `clear` | 杀掉进程并启动一个全新 session(等价于 Claude Code 的 `/clear`) |
 
-整个对话在群里、在手机上、在桌面上完整发生。**离开终端，但不离开 Claude Code。**
+> 这四个词被全局保留:在群里发 "hi" 当问候也会触发控制台卡片,不会到 Claude 那边。换来的是手机上单手打字的便利。
 
 ## 安装
 
 ### 1. 准备
 
-- 一台能常跑后台进程的机器（自家服务器或闲置主机）
-- [Bun](https://bun.sh) 运行时
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 已登录 Anthropic 账号 (`claude auth login`)
-- 一个飞书自建应用 (`cli_xxx`)，开通：
+- 一台能常跑后台进程的机器(自家服务器、闲置 NAS、树莓派均可)
+- [Bun](https://bun.sh) 运行时(≥ 1.0)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 装好且能跑(怎么认证、走官方账号还是第三方网关,你自己看着办)
+- 一个飞书自建应用 (`cli_xxx`),开通:
   - `im:message:send_as_bot` / `im:message` / `im:chat:readonly` / `im:resource`
+  - `im:message.urgent`(加急推送)
   - `cardkit:card:read` `cardkit:card:write`
     `cardkit:card.element:read` `cardkit:card.element:write`
     `cardkit:card.settings:read` `cardkit:card.settings:write`
 
 ### 2. 配置
 
-把凭据写到 `~/.config/lodestar/config.toml`：
+把凭据写到 `~/.config/lodestar/config.toml`:
 
 ```toml
 [feishu]
@@ -60,10 +72,10 @@ app_id     = "cli_xxxxxxxxxxxxxxxx"
 app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 
 [runtime]
-projects_root = "~/"        # 可选，新建群对应的项目目录会落到这里
+projects_root = "~/"        # 可选,新建群对应的项目目录会落到这里
 ```
 
-也支持 `LODESTAR_CONFIG=/abs/path.toml` 或 `XDG_CONFIG_HOME` 覆盖。
+也支持 `LODESTAR_CONFIG=/abs/path.toml` 或 `XDG_CONFIG_HOME` 覆盖。运行时状态走 `~/.local/share/lodestar/`(可用 `LODESTAR_DATA_DIR` 或 `XDG_DATA_HOME` 改写)——daemon.pid、daemon.log、session-chat-map、session-resume-map、alive-marker、inbox/ 都在那里。
 
 ### 3. 启动
 
@@ -72,19 +84,17 @@ bun install -g @leviyuan/lodestar
 lodestar-daemon
 ```
 
-或者一次性跑（无需全局安装）：
+或者一次性跑(无需全局安装):
 
 ```bash
 bunx @leviyuan/lodestar
 ```
 
-把机器人拉进任意飞书群，发一条消息——Claude 就上线了。
+把机器人拉进任意飞书群,发一条消息——Claude 就上线了。
 
-> **小贴士**：群名首次出现时，daemon 会自动在 `~/{群名}/` 创建项目目录并 `git init`。换句话说，开新群 = 开新项目。
+### 4. 守护进程(推荐)
 
-### 4. 守护进程（可选）
-
-要让 daemon 7×24 跑，最简单的方法是配一个 `systemd --user` 单元：
+让 daemon 7×24 跑,最简单的方法是配一个 `systemd --user` 单元:
 
 ```ini
 [Unit]
@@ -101,7 +111,11 @@ RestartSec=3
 WantedBy=default.target
 ```
 
-`systemctl --user enable --now lodestar`。
+```bash
+systemctl --user enable --now lodestar
+```
+
+WS watchdog + alive-marker 的联手设计,意味着每次 systemd 拉起,daemon 会把**上次还在运行的 session 全部 `--resume` 自动复活**;你主动 `kill` 过的不会被吵醒。
 
 ## 许可
 

package/package.json

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

package/src/cards.ts

@@ -593,48 +593,41 @@ const PEER_STATUS_EMOJI: Record<string, string> = {
 
 /** Render the subscription-usage section of the console card. Pulled out
  * of `consoleCard` so the caller can patch it in after the initial card
- * is on screen (ccusage's first cold call is ~5s; we'd rather not block
- * the whole panel on it). Layout intentionally splits 5h and 7d onto
- * their own indented lines for readability on phone.
+ * is on screen (网络往返可能慢于第一次 paint;先占位、回包后替换)。
  *
- * `usage === undefined` → loading placeholder (initial paint).
- * `usage === null`      → permanent "no data" (treat like installed but
- *                          empty; rare path).
- * `usage.installed=false` → install hint.
+ * 数据源是 Anthropic 官方 OAuth Usage API (见 src/usage.ts)。
+ * 百分比是真实 utilization,失败态按 state 区分显示具体原因。
+ *
+ * `usage === undefined` → 初始 loading 占位。
  */
 export function consoleUsageContent(
-  usage: import('./usage').UsageSnapshot | null | undefined,
+  usage: import('./usage').UsageSnapshot | undefined,
 ): string {
   if (usage === undefined) return '**📊 订阅额度**　_加载中…_'
-  if (usage === null) return '**📊 订阅额度**　_无数据_'
-  if (!usage.installed) return '**📊 订阅额度**　未装 `ccusage` — `bun i -g ccusage`'
-  // Format follows user spec: `5h X% $Y 剩Zh` / `7d X% $Y 剩Zd`.
-  // Both % values are vs. the user's own historical peak (peak block
-  // for 5h, peak week for 7d) since ccusage has no view into the
-  // actual subscription tier cap. Omit chips that the data layer
-  // couldn't supply rather than fabricate (no_fallbacks).
-  const lines: string[] = ['**📊 订阅额度**']
+  switch (usage.state) {
+    case 'no_credentials':
+      return '**📊 订阅额度**　未找到 OAuth 凭据 (`~/.claude/.credentials.json`)'
+    case 'auth_failed':
+      return '**📊 订阅额度**　Token 已过期且刷新失败 — 重新 `claude auth login`'
+    case 'rate_limited':
+      return '**📊 订阅额度**　API 429 限流,稍后重试'
+    case 'network':
+      return `**📊 订阅额度**　拉取失败${usage.reason ? ' — `' + usage.reason + '`' : ''}`
+  }
+  // state === 'ok'
+  const head = usage.subscriptionType
+    ? `**📊 订阅额度** · ${usage.subscriptionType}`
+    : '**📊 订阅额度**'
+  const lines: string[] = [head]
   if (usage.fiveHour) {
-    const parts: string[] = []
-    if (usage.fiveHour.percentUsed != null) {
-      parts.push(`${Math.round(usage.fiveHour.percentUsed)}%`)
-    }
-    parts.push(`$${Math.round(usage.fiveHour.costUsd)}`)
-    if (usage.fiveHour.remainingMinutes != null) {
-      parts.push(`剩${(usage.fiveHour.remainingMinutes / 60).toFixed(1)}h`)
-    }
-    lines.push(`　· 5h　${parts.join(' ')}`)
+    const parts = [`${Math.round(usage.fiveHour.percent)}%`]
+    if (usage.fiveHour.resetsAt) parts.push(`重置 ${fmtResetIn(usage.fiveHour.resetsAt)}`)
+    lines.push(`　· 5h　${parts.join(' · ')}`)
   }
   if (usage.weekly) {
-    const parts: string[] = []
-    if (usage.weekly.percentUsed != null) {
-      parts.push(`${Math.round(usage.weekly.percentUsed)}%`)
-    }
-    parts.push(`$${Math.round(usage.weekly.costUsd)}`)
-    if (usage.weekly.remainingDays != null) {
-      parts.push(`剩${usage.weekly.remainingDays.toFixed(1)}d`)
-    }
-    lines.push(`　· 7d　${parts.join(' ')}`)
+    const parts = [`${Math.round(usage.weekly.percent)}%`]
+    if (usage.weekly.resetsAt) parts.push(`重置 ${fmtResetIn(usage.weekly.resetsAt)}`)
+    lines.push(`　· 7d　${parts.join(' · ')}`)
   }
   return lines.length === 1 ? '**📊 订阅额度**　_无数据_' : lines.join('\n')
 }

package/src/session.ts

@@ -152,6 +152,19 @@ export class Session {
     }
   }
 
+  /** Patch the card-level summary (the text Feishu uses for chat-list
+   * preview AND lock-screen push), then return when the API call has
+   * landed. Used right before urgent_app so the push notification's
+   * derived preview describes the *action that needs attention* (an
+   * unanswered question, a pending permission ask) rather than the
+   * stale assistant-text tail that patchSummaryThrottled was streaming.
+   * cancelSummary kills any in-flight throttled write so our explicit
+   * patch isn't immediately clobbered. */
+  private async setUrgentSummary(cardId: string, content: string): Promise<void> {
+    cardkit.cancelSummary(cardId)
+    await cardkit.patchSettings(cardId, { config: { summary: { content } } })
+  }
+
   /** Minimal cross-chat snapshot for the `hi` peer-list section.
    * `startedAt` stays private so this is the documented read path. */
   peerSnapshot(): { name: string; status: Status; uptimeMs?: number } {
@@ -745,9 +758,21 @@ export class Session {
         targetElementId: cards.ELEMENTS.footer,
       })
       // Phone push — user has to come back and answer before Claude can
-      // continue. urgentApp no-ops when userOpenId is empty.
+      // continue. Set summary to the question text so the lock-screen
+      // notification preview shows what the user needs to answer.
       if (this.currentTurn.userOpenId && this.currentTurn.messageId) {
-        void feishu.urgentApp(this.currentTurn.messageId, [this.currentTurn.userOpenId])
+        const turn = this.currentTurn
+        const q0 = questions[0]?.question?.trim() ?? ''
+        const truncated = q0.length > 40 ? q0.slice(0, 40) + '…' : q0
+        const summary = questions.length > 1
+          ? `❓ 待回答 ${questions.length} 题${truncated ? `: ${truncated}` : ''}`
+          : truncated
+            ? `❓ ${truncated}`
+            : '❓ 等你回答问题'
+        void (async () => {
+          await this.setUrgentSummary(turn.cardId, summary)
+          await feishu.urgentApp(turn.messageId, [turn.userOpenId])
+        })()
       }
       return
     }
@@ -925,8 +950,20 @@ export class Session {
     const el = cards.toolCallPermissionElement(meta.i, meta.name, meta.input, req.request_id)
     void cardkit.replaceElement(turn.cardId, cards.ELEMENTS.tool(meta.i), el)
     // Phone push — Claude is blocked until the user approves/denies.
+    // Set summary to "🔐 等审批: <tool>(<input summary>)" so the lock-
+    // screen notification shows which tool needs approval.
     if (turn.userOpenId && turn.messageId) {
-      void feishu.urgentApp(turn.messageId, [turn.userOpenId])
+      const inputSummary = cards.summarizeToolInput(meta.name, meta.input)
+      const tail = inputSummary && inputSummary.length > 30
+        ? inputSummary.slice(0, 30) + '…'
+        : inputSummary
+      const summary = tail
+        ? `🔐 等审批: ${meta.name} · ${tail}`
+        : `🔐 等审批: ${meta.name}`
+      void (async () => {
+        await this.setUrgentSummary(turn.cardId, summary)
+        await feishu.urgentApp(turn.messageId, [turn.userOpenId])
+      })()
     }
   }
 

package/src/usage.ts

@@ -1,201 +1,263 @@
 /**
  * Subscription usage snapshot for the `hi` console panel.
  *
- * Source: the `ccusage` CLI (https://github.com/ryoppippi/ccusage), which
- * parses Claude Code's local JSONL transcripts on demand. We shell out
- * twice in parallel and cache the merged result for CACHE_TTL_MS.
+ * Source: Anthropic 官方 OAuth Usage API —— `GET /api/oauth/usage`.
+ * 不再依赖外部 ccusage CLI。
  *
- *   - `blocks --active --token-limit max` → current 5h billing block.
- *     `tokenLimitStatus.limit` is ccusage's "peak historical block"
- *     value, used as the denominator for the 5h percentage. NOTE:
- *     this is consumption relative to your own heaviest 5h ever —
- *     NOT the Anthropic tier quota (which we have no way to read
- *     without OAuth roundtrips). It's an internally-consistent burn
- *     indicator, not an official quota gauge.
+ * 凭据来源: `~/.claude/.credentials.json`(Linux 服务器,无 macOS
+ * Keychain 分支)。结构由 Claude Code 写入,我们读 `claudeAiOauth`
+ * 字段拿 access_token / refresh_token / expires_at / subscriptionType /
+ * rateLimitTier。
  *
- *   - `weekly --order desc` → list of weekly aggregates, newest first.
- *     ccusage's weekly doesn't expose tokenLimitStatus, so we compute
- *     the same "peak historical week" ratio locally.
+ * access_token 过期时,用 refresh_token 调 platform.claude.com
+ * `/v1/oauth/token` 刷新,刷新成功后原子写回凭据文件
+ * (tmp + rename),保证多进程并发安全。
  *
- * Failures stay visible (no fallback fabrication):
- *   - ccusage not on PATH → `installed: false` → card renders install hint.
- *   - ccusage runs but yields nothing → `fiveHour: null`, `weekly: null`.
+ * 失败可见 (no_fallbacks):
+ *   - 凭据缺失      → state='no_credentials'
+ *   - 刷新也失败    → state='auth_failed'
+ *   - API 返回 429  → state='rate_limited' (+ resetsAt 可选)
+ *   - 其它网络异常  → state='network'
+ *
+ * 卡片渲染层 (`cards.consoleUsageContent`) 按 state 分别显示具体原因,
+ * 不静默回退到旧值,不伪造百分比。
+ *
+ * Lodestar 启动后,每次 `hi` 弹板都会拉一次;CACHE_TTL_MS 内的重复
+ * 调用共享同一份快照,不打 API。in-flight 去重保证并发的多个
+ * 群同时唤出控制台时只触发一次后台请求。
+ *
+ * 参考实现: oh-my-claudecode HUD `src/hud/usage-api.ts`。这里只保留
+ * Lodestar 用得到的最小子集 —— 不处理 keychain、不处理第三方网关
+ * (z.ai / MiniMax)、不处理 enterprise 货币换算、不做多文件 cache 与
+ * 文件锁。
  */
 
-import { spawn } from 'node:child_process'
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import { log } from './log'
 
-const CCUSAGE_BIN = 'ccusage'
+const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage'
+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
-const SPAWN_TIMEOUT_MS = 15_000
-
-export interface FiveHourBlock {
-  costUsd: number
-  totalTokens: number
-  /** End of the current 5h billing window per ccusage. */
-  windowEndsAt: Date
-  /** Tokens/min over the current window, if ccusage reported one. */
-  burnRatePerMin: number | null
-  /** Consumption vs. user's historical peak 5h block (0–100). Null
-   * when ccusage hasn't built a peak yet (very new install). */
-  percentUsed: number | null
-  /** Minutes left in this 5h window per ccusage's projection. */
-  remainingMinutes: number | null
+
+function credentialsPath(): string {
+  return join(homedir(), '.claude', '.credentials.json')
+}
+
+interface OAuthCredentials {
+  accessToken: string
+  refreshToken?: string
+  expiresAt?: number
+  subscriptionType?: string
+  rateLimitTier?: string
 }
 
-export interface WeeklyAggregate {
-  /** ISO date of this week's start, format ccusage chose (Sun by default). */
-  weekStart: string
-  costUsd: number
-  totalTokens: number
-  /** Consumption vs. user's historical peak week (0–100). Null when
-   * there's no prior week to compare against. */
-  percentUsed: number | null
-  /** Fractional days remaining until end of week (start + 7d). */
-  remainingDays: number | null
+export interface UsageWindow {
+  /** 0-100, Anthropic 直接返回的 utilization 真实值 */
+  percent: number
+  /** 这个窗口何时重置;ISO 解析失败则 null */
+  resetsAt: Date | null
 }
 
 export type UsageSnapshot =
-  | { installed: false }
+  | { state: 'no_credentials' }
+  | { state: 'auth_failed' }
+  | { state: 'rate_limited' }
+  | { state: 'network'; reason?: string }
   | {
-      installed: true
-      fiveHour: FiveHourBlock | null
-      weekly: WeeklyAggregate | null
-      /** When this snapshot was computed. */
+      state: 'ok'
+      subscriptionType?: string
+      fiveHour: UsageWindow | null
+      weekly: UsageWindow | null
       fetchedAt: number
     }
 
-function clampPct(v: number): number {
-  if (!isFinite(v)) return 0
-  return Math.max(0, Math.min(100, v))
-}
-
 let cache: { data: UsageSnapshot; at: number } | null = null
 let inFlight: Promise<UsageSnapshot> | null = null
 
-/** `null` = not on PATH (ENOENT); `undefined` = ran but failed (timeout,
- * non-zero exit, JSON parse error). Distinct so the caller can render
- * different UX. */
-type RunResult = any | null | undefined
+function readCredentials(): OAuthCredentials | null {
+  const path = credentialsPath()
+  if (!existsSync(path)) return null
+  try {
+    const raw = readFileSync(path, 'utf8')
+    const parsed = JSON.parse(raw)
+    const creds = parsed.claudeAiOauth ?? parsed
+    if (!creds?.accessToken) return null
+    return {
+      accessToken: creds.accessToken,
+      refreshToken: creds.refreshToken,
+      expiresAt: creds.expiresAt,
+      subscriptionType: creds.subscriptionType,
+      rateLimitTier: creds.rateLimitTier,
+    }
+  } catch (e) {
+    log(`usage: read credentials failed: ${e}`)
+    return null
+  }
+}
 
-function runCcusage(args: string[]): Promise<RunResult> {
-  return new Promise((resolve) => {
-    let stdout = ''
-    let stderr = ''
-    let proc
+/** 把刷新后的 access_token / refresh_token / expires_at 原子写回原文件,
+ * 保留其它字段(scopes、subscriptionType、organizationUuid 等)。
+ * 走 tmp + rename 防止半写状态被读到。 */
+function writeBackCredentials(updated: OAuthCredentials): void {
+  const path = credentialsPath()
+  if (!existsSync(path)) return
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    const target = parsed.claudeAiOauth ?? parsed
+    target.accessToken = updated.accessToken
+    if (updated.refreshToken) target.refreshToken = updated.refreshToken
+    if (updated.expiresAt != null) target.expiresAt = updated.expiresAt
+    const tmp = `${path}.tmp.${process.pid}`
     try {
-      proc = spawn(CCUSAGE_BIN, args, { stdio: ['ignore', 'pipe', 'pipe'] })
-    } catch (e: any) {
-      if (e?.code === 'ENOENT') return resolve(null)
-      log(`ccusage spawn threw: ${e}`)
-      return resolve(undefined)
+      writeFileSync(tmp, JSON.stringify(parsed, null, 2), { mode: 0o600 })
+      renameSync(tmp, path)
+    } catch (e) {
+      try { if (existsSync(tmp)) unlinkSync(tmp) } catch {}
+      throw e
     }
+  } catch (e) {
+    log(`usage: writeBackCredentials failed: ${e}`)
+  }
+}
 
-    const timer = setTimeout(() => {
-      proc.kill('SIGTERM')
-      log(`ccusage ${args.join(' ')}: timeout after ${SPAWN_TIMEOUT_MS}ms`)
-    }, SPAWN_TIMEOUT_MS)
+function isExpired(creds: OAuthCredentials): boolean {
+  return creds.expiresAt != null && creds.expiresAt <= Date.now()
+}
 
-    proc.on('error', (err: any) => {
-      clearTimeout(timer)
-      if (err?.code === 'ENOENT') resolve(null)
-      else { log(`ccusage error: ${err}`); resolve(undefined) }
+async function refreshAccessToken(refreshToken: string): Promise<OAuthCredentials | null> {
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+    client_id: OAUTH_CLIENT_ID,
+  }).toString()
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), API_TIMEOUT_MS)
+  try {
+    const res = await fetch(TOKEN_REFRESH_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body,
+      signal: ctrl.signal,
     })
-    proc.stdout!.on('data', (b) => { stdout += b.toString() })
-    proc.stderr!.on('data', (b) => { stderr += b.toString() })
-    proc.on('close', (code) => {
-      clearTimeout(timer)
-      if (code !== 0) {
-        log(`ccusage ${args.join(' ')}: exit ${code} stderr=${stderr.slice(0, 200)}`)
-        return resolve(undefined)
-      }
-      try { resolve(JSON.parse(stdout)) }
-      catch (e) { log(`ccusage JSON parse: ${e}`); resolve(undefined) }
-    })
-  })
+    if (res.status !== 200) {
+      log(`usage: token refresh HTTP ${res.status}`)
+      return null
+    }
+    const json = await res.json() as any
+    if (!json?.access_token) return null
+    return {
+      accessToken: json.access_token,
+      refreshToken: json.refresh_token ?? refreshToken,
+      expiresAt: json.expires_in
+        ? Date.now() + json.expires_in * 1000
+        : json.expires_at,
+    }
+  } catch (e) {
+    log(`usage: token refresh threw: ${e}`)
+    return null
+  } finally {
+    clearTimeout(timer)
+  }
 }
 
-async function fetchUsage(): Promise<UsageSnapshot> {
-  const [blocks, weekly] = await Promise.all([
-    // --active filters to the current 5h block (cheaper to parse).
-    // --token-limit max derives a cap from the user's peak historical
-    // block so ccusage emits `tokenLimitStatus`, giving us a numerator+
-    // denominator without us reading every block ourselves.
-    runCcusage(['blocks', '--json', '--active', '--token-limit', 'max']),
-    runCcusage(['weekly', '--json', '--order', 'desc']),
-  ])
-
-  if (blocks === null || weekly === null) return { installed: false }
-
-  let fiveHour: FiveHourBlock | null = null
-  if (blocks && Array.isArray(blocks.blocks)) {
-    const active = blocks.blocks.find((b: any) => b?.isActive && !b?.isGap)
-    if (active) {
-      const totalTokens = Number(active.totalTokens) || 0
-      const limit = Number(active.tokenLimitStatus?.limit) || 0
-      fiveHour = {
-        costUsd: Number(active.costUSD) || 0,
-        totalTokens,
-        windowEndsAt: new Date(active.endTime),
-        burnRatePerMin: typeof active.burnRate?.tokensPerMinute === 'number'
-          ? active.burnRate.tokensPerMinute : null,
-        percentUsed: limit > 0 ? clampPct((totalTokens / limit) * 100) : null,
-        remainingMinutes: typeof active.projection?.remainingMinutes === 'number'
-          ? active.projection.remainingMinutes : null,
-      }
+interface UsageApiResponse {
+  five_hour?: { utilization?: number; resets_at?: string }
+  seven_day?: { utilization?: number; resets_at?: string }
+}
+
+function parseDate(s: string | undefined): Date | null {
+  if (!s) return null
+  const d = new Date(s)
+  return isNaN(d.getTime()) ? null : d
+}
+
+function clampPct(v: number | undefined): number {
+  if (v == null || !isFinite(v)) return 0
+  return Math.max(0, Math.min(100, v))
+}
+
+interface FetchResult {
+  data: UsageApiResponse | null
+  /** 失败原因:undefined = 成功;其它字符串是分类错误。 */
+  reason?: 'rate_limited' | 'network'
+  detail?: string
+}
+
+async function fetchUsageFromApi(accessToken: string): Promise<FetchResult> {
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), API_TIMEOUT_MS)
+  try {
+    const res = await fetch(USAGE_URL, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        'anthropic-beta': 'oauth-2025-04-20',
+        'Content-Type': 'application/json',
+      },
+      signal: ctrl.signal,
+    })
+    if (res.status === 200) {
+      const data = await res.json() as UsageApiResponse
+      return { data }
     }
+    if (res.status === 429) return { data: null, reason: 'rate_limited' }
+    return { data: null, reason: 'network', detail: `HTTP ${res.status}` }
+  } catch (e: any) {
+    return { data: null, reason: 'network', detail: e?.message ?? String(e) }
+  } finally {
+    clearTimeout(timer)
   }
+}
 
-  let wk: WeeklyAggregate | null = null
-  if (weekly && Array.isArray(weekly.weekly) && weekly.weekly.length > 0) {
-    const current = weekly.weekly[0]
-    const totalTokens = Number(current.totalTokens) || 0
-    // Peak historical week (excluding the current one — comparing
-    // against itself would always read 100%). When this is the only
-    // recorded week we leave percentUsed null.
-    const peakTokens = weekly.weekly.slice(1).reduce(
-      (m: number, w: any) => Math.max(m, Number(w?.totalTokens) || 0), 0)
-    const percentUsed = peakTokens > 0 ? clampPct((totalTokens / peakTokens) * 100) : null
-    // Week end = weekStart + 7 days. ccusage emits weekStart as YYYY-MM-DD;
-    // parse as UTC so DST/timezone shifts don't drift the countdown.
-    const weekStartIso = String(current.week ?? '')
-    let remainingDays: number | null = null
-    if (weekStartIso) {
-      const start = new Date(weekStartIso + 'T00:00:00Z')
-      if (!isNaN(start.getTime())) {
-        const endMs = start.getTime() + 7 * 24 * 60 * 60 * 1000
-        remainingDays = Math.max(0, (endMs - Date.now()) / (24 * 60 * 60 * 1000))
-      }
-    }
-    wk = {
-      weekStart: weekStartIso,
-      costUsd: Number(current.totalCost) || 0,
-      totalTokens,
-      percentUsed,
-      remainingDays,
-    }
+async function fetchUsage(): Promise<UsageSnapshot> {
+  let creds = readCredentials()
+  if (!creds) return { state: 'no_credentials' }
+
+  if (isExpired(creds)) {
+    if (!creds.refreshToken) return { state: 'auth_failed' }
+    const refreshed = await refreshAccessToken(creds.refreshToken)
+    if (!refreshed) return { state: 'auth_failed' }
+    creds = { ...creds, ...refreshed }
+    writeBackCredentials(creds)
   }
 
-  return { installed: true, fiveHour, weekly: wk, fetchedAt: Date.now() }
+  const result = await fetchUsageFromApi(creds.accessToken)
+  if (result.reason === 'rate_limited') return { state: 'rate_limited' }
+  if (result.reason === 'network' || !result.data) return { state: 'network', reason: result.detail }
+
+  const data = result.data
+  const fiveHour = data.five_hour?.utilization != null
+    ? { percent: clampPct(data.five_hour.utilization), resetsAt: parseDate(data.five_hour.resets_at) }
+    : null
+  const weekly = data.seven_day?.utilization != null
+    ? { percent: clampPct(data.seven_day.utilization), resetsAt: parseDate(data.seven_day.resets_at) }
+    : null
+
+  return {
+    state: 'ok',
+    subscriptionType: creds.subscriptionType,
+    fiveHour,
+    weekly,
+    fetchedAt: Date.now(),
+  }
 }
 
-/** Returns a usage snapshot. Cached for CACHE_TTL_MS; concurrent callers
- * dedupe to a single in-flight ccusage run. First call after stale-out
- * pays the full ccusage cost (~5s on this machine); subsequent reads are
- * instant. Never throws — returns `{ installed: false }` if ccusage is
- * missing, or an empty `{ installed: true, fiveHour: null, ... }` if it
- * runs but yields no data. */
+/** 返回订阅额度快照。CACHE_TTL_MS 内的重复调用读缓存;并发请求去重为
+ * 单次后台 fetch。永不抛出 —— 失败状态由 `state` 字段表达,卡片层
+ * 按 state 分支渲染。 */
 export async function readUsage(): Promise<UsageSnapshot> {
   if (cache && Date.now() - cache.at < CACHE_TTL_MS) return cache.data
   if (inFlight) return inFlight
-  inFlight = fetchUsage().then(d => {
-    cache = { data: d, at: Date.now() }
-    inFlight = null
-    return d
-  }).catch(e => {
-    log(`usage: fetchUsage threw: ${e}`)
-    inFlight = null
-    return cache?.data ?? { installed: false }
-  })
+  inFlight = fetchUsage()
+    .then(d => { cache = { data: d, at: Date.now() }; inFlight = null; return d })
+    .catch(e => {
+      log(`usage: fetchUsage threw: ${e}`)
+      inFlight = null
+      return cache?.data ?? { state: 'network', reason: String(e) }
+    })
   return inFlight
 }