@leviyuan/lodestar 0.1.9 → 0.1.11

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/daemon.ts

@@ -175,7 +175,7 @@ async function handleMessage(data: any): Promise<void> {
   }
 
   if (!text && !filePath) return
-  await session.onUserMessage(text || '(empty)', filePath ? [filePath] : [], userOpenId)
+  await session.onUserMessage(text || '(empty)', filePath ? [filePath] : [], userOpenId, msgId ?? '')
 }
 
 // ── Card action handler ────────────────────────────────────────────────

package/package.json

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

package/src/cards.ts

@@ -172,10 +172,18 @@ interface MainCardOpts {
   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
+   * cue, and scheduled turns have no preceding bubble in the chat. */
+  kind?: 'user_message' | 'scheduled'
 }
 
 /** Initial card sent at the start of each turn. Streaming on. */
-export function mainConversationCard(_opts: MainCardOpts): object {
+export function mainConversationCard(opts: MainCardOpts): object {
+  const banner = opts.kind === 'scheduled'
+    ? [{ tag: 'markdown', content: '⏰ **定时任务触发** — Claude 在 idle 间隙被 CronCreate / ScheduleWakeup 唤醒' }]
+    : []
   return {
     schema: '2.0',
     config: {
@@ -194,6 +202,7 @@ export function mainConversationCard(_opts: MainCardOpts): object {
       // thinking element starts with a single space placeholder; the first
       // real append overwrites it.
       elements: [
+        ...banner,
         { tag: 'markdown', element_id: ELEMENTS.thinking, content: ' ' },
         { tag: 'markdown', element_id: ELEMENTS.footer, content: '⏳ working…' },
       ],
@@ -593,48 +602,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/feishu.ts

@@ -194,14 +194,34 @@ export async function sendCard(chatId: string, card: object): Promise<string | n
 }
 
 // ── Reactions ──────────────────────────────────────────────────────────
-export async function addReaction(messageId: string, emojiType: string): Promise<void> {
-  if (!messageId) return
+/** Add an emoji reaction. Returns the new reaction_id on success (needed
+ * to delete the reaction later via {@link deleteReaction}) or null on
+ * failure. Failures are logged and swallowed — reactions are non-load-
+ * bearing UX, not worth bubbling errors. */
+export async function addReaction(messageId: string, emojiType: string): Promise<string | null> {
+  if (!messageId) return null
   try {
-    await client.im.messageReaction.create({
+    const res: any = await client.im.messageReaction.create({
       path: { message_id: messageId },
       data: { reaction_type: { emoji_type: emojiType } },
     })
-  } catch (e) { log(`feishu: addReaction ${emojiType} on ${messageId} failed: ${e}`) }
+    return res?.data?.reaction_id ?? null
+  } catch (e) { log(`feishu: addReaction ${emojiType} on ${messageId} failed: ${e}`); return null }
+}
+
+/** Remove a previously-added reaction by its reaction_id (returned from
+ * {@link addReaction}). Used for the "queued → released" lifecycle: the
+ * OneSecond placed on arrival is *removed* when the daemon hands the
+ * message off to the SDK's batch / system-reminder pipeline, instead of
+ * stacking a second CheckMark on top — keeps the message's reaction row
+ * uncluttered. Quiet on failure. */
+export async function deleteReaction(messageId: string, reactionId: string): Promise<void> {
+  if (!messageId || !reactionId) return
+  try {
+    await client.im.messageReaction.delete({
+      path: { message_id: messageId, reaction_id: reactionId },
+    })
+  } catch (e) { log(`feishu: deleteReaction ${reactionId} on ${messageId} failed: ${e}`) }
 }
 
 // ── Urgent push ───────────────────────────────────────────────────────

package/src/session.ts

@@ -28,6 +28,12 @@ interface TurnState {
    * urgent_app push so only the initiator gets pinged (in case there
    * are other members in the group). Empty string → skip the ping. */
   userOpenId: string
+  /** What kicked off this turn. Only `'user_message'` turns fire the
+   * end-of-turn urgent_app push — scheduled / cron / loop wakeups
+   * finish on their own time and pinging the user would be noise,
+   * 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
@@ -92,6 +98,79 @@ export class Session {
 
   private proc: ClaudeProcess | null = null
   private currentTurn: TurnState | null = null
+  /** Count of user messages we've written to Claude's stdin since the last
+   * turn opened on our side. NOT a FIFO of individual messages — the SDK
+   * batch-merges every mid-turn user message into a single combined turn
+   * once the in-flight turn finishes, so the daemon only ever observes
+   * **one** init event per batch (no matter how many Feishu messages went
+   * into the batch). Tracking a count + last-sender (rather than an
+   * Array<msg>) keeps the daemon's view in sync with the SDK's actual
+   * dequeue semantics. Empirically verified 2026-05-15 from the SDK's
+   * `queue-operation` transcript events: 4 enqueues during a long turn
+   * → single dequeue at turn end → one merged user message. Count is
+   * decremented to 0 wholesale at the `init` boundary because the SDK
+   * has already collapsed them into one turn. Distinguishes user-msg
+   * turns from cron-fired scheduled wakeups: count > 0 ⇒ user;
+   * count === 0 ⇒ scheduled (and `initCount > 1`). */
+  private pendingUserMessageCount = 0
+  /** Most recent userOpenId seen via `onUserMessage`. Used only when a
+   * merged batch fires its init event and the daemon needs *some* open_id
+   * to scope the eventual `urgent_app` push — there's no obviously right
+   * answer when N messages from possibly different users collapse into
+   * one turn, and "the most recent sender" is a defensible default for
+   * the single-user private-bot scenario this product targets. */
+  private lastUserOpenId = ''
+  /** Feishu message_ids of user messages that arrived while the daemon
+   * was busy (turn in flight or mid-open), mapped to the `reaction_id`
+   * of the `OneSecond` reaction placed at arrival. The reaction_id is
+   * what `deleteReaction` needs to *remove* the OneSecond once the
+   * message has been absorbed by the SDK (either system-reminder
+   * injection mid-turn or a merged-batch dequeue on next turn).
+   * User feedback (2026-05-15): replacing OneSecond with a second
+   * CheckMark stacked two emojis on the same row; cleaner UX is
+   * "queued → released" via removal, not "queued → done" via
+   * stacking. */
+  private pendingReactionIds = new Map<string, string>()
+  /** Snapshot of `pendingReactionIds` taken when the init handler
+   * claims a merged batch — these are the Feishu messages whose
+   * OneSecond reactions are the currently-open turn's responsibility
+   * to clear (via deleteReaction). Empty for eager-opened solo turns
+   * and for scheduled wakeups (no user messages went into those). */
+  private currentBatchReactionIds = new Map<string, string>()
+  /** Set the moment a mid-turn user message lands. Tells the next
+   * content-adding event (assistant text delta or fresh tool_use) to
+   * rotate the card before applying its update — closes the in-flight
+   * card with a `📨 转交新卡` footer and opens a fresh card, so the
+   * continuation has a visible boundary instead of piling up under
+   * one card. Reset to false after the rotation fires (or on
+   * stop/restart/exit). User feedback (2026-05-15): the prior
+   * everything-in-one-card behavior made the order feel jumbled. */
+  private wantsRotation = false
+  /** Holds assistant / thinking / tool_use events that arrive while a
+   * card rotation is mid-flight (close-old → open-new straddles a
+   * Feishu API await window during which `currentTurn` is transiently
+   * null). Replayed onto the new card the moment rotation completes
+   * so no streamed token is lost across the boundary. */
+  private rotationBuffer: Array<
+    | { kind: 'assistant'; delta: string }
+    | { kind: 'thinking'; delta: string }
+    | { kind: 'tool_use'; id: string; name: string; input: any }
+  > = []
+  /** Count of `system/init` events seen this subprocess. The first one is
+   * the boot init (claimed by whichever user message lands first); all
+   * subsequent ones mark the start of an SDK-initiated turn (queued
+   * user message draining or a CronCreate fire). Reset on stop/restart/exit
+   * since `init` re-fires after every spawn. */
+  private initCount = 0
+  /** Sync guard set before any `await` in the eager-open path of
+   * `onUserMessage`, cleared after `currentTurn` is set. Closes the race
+   * where an SDK-emitted `init` event lands during the eager open's
+   * Feishu API await — without this, the init handler would observe
+   * `currentTurn === null && queue empty` (we've already shifted) and
+   * incorrectly open a *second* scheduled card for the same user
+   * message. The flag tells the init handler "an eager open is already
+   * claiming the slot, stand down". */
+  private openingTurn = false
   private pendingPermissions = new Map<string, { toolUseId: string }>()
   /** Open AskUserQuestion tool calls — keyed by tool_use_id. The SDK
    * routes AskUserQuestion through the can_use_tool flow even under
@@ -228,6 +307,14 @@ export class Session {
     this.lastSessionId = proc.sessionId ?? this.lastSessionId
     this.proc = null
     this.currentTurn = null
+    this.pendingUserMessageCount = 0
+    this.lastUserOpenId = ''
+    this.pendingReactionIds = new Map()
+    this.currentBatchReactionIds = new Map()
+    this.wantsRotation = false
+    this.rotationBuffer = []
+    this.initCount = 0
+    this.openingTurn = false
     this.pendingPermissions.clear()
     this.status = 'stopped'
     await proc.kill()
@@ -242,6 +329,14 @@ export class Session {
       this.proc = null
     }
     this.currentTurn = null
+    this.pendingUserMessageCount = 0
+    this.lastUserOpenId = ''
+    this.pendingReactionIds = new Map()
+    this.currentBatchReactionIds = new Map()
+    this.wantsRotation = false
+    this.rotationBuffer = []
+    this.initCount = 0
+    this.openingTurn = false
     this.pendingPermissions.clear()
     if (resume && prevSessionId) {
       this.proc = new ClaudeProcess({
@@ -271,15 +366,18 @@ export class Session {
     }
   }
 
-  /** Run a bare-text control command (`hi`, `kill`, `restart`, `clear`).
+  /** Run a bare-text control command (`hi`, `stop`, `kill`, `restart`, `clear`).
    * Returns true if the command was consumed (don't forward to Claude).
    * Exact match, case-insensitive, ignores trailing whitespace.
    *
-   * Trade-off (user-confirmed 2026-05-15): the four words are reserved
+   * Trade-off (user-confirmed 2026-05-15): these words are reserved
    * globally — typing "hi" as a literal greeting will show the console
    * card instead of reaching Claude. The ergonomic win (no slash, no
    * shift key, one-handed phone use) outweighs the collision in this
-   * product's private-bot use case. */
+   * product's private-bot use case. `stop` was added 2026-05-15 once
+   * auto-interrupt on mid-turn user messages was removed (matching
+   * claude-code's native type-ahead behavior) — explicit barge-out
+   * needed a knob and `kill` (full subprocess teardown) is too heavy. */
   async runCommand(raw: string): Promise<boolean> {
     switch (raw.trim().toLowerCase()) {
       case 'hi':
@@ -289,6 +387,38 @@ export class Session {
         }
         await this.showConsole()
         return true
+      case 'stop':
+        // Soft barge-out: interrupt the current turn (if any) AND drop
+        // the pending-message count so a stack of type-ahead doesn't
+        // refire after the interrupt. Subprocess stays alive. Note: the
+        // SDK keeps its OWN internal queue of the user-text frames we
+        // already sendText'd — interrupt should also flush that side,
+        // but the daemon can't reach into it directly; in practice the
+        // sendInterrupt() control_request causes the SDK to discard
+        // queued input alongside the in-flight call.
+        if (!this.currentTurn && this.pendingUserMessageCount === 0) {
+          await feishu.sendText(this.chatId, '⚪ 当前没有正在执行的 turn')
+          return true
+        }
+        log(`session "${this.sessionName}": stop command — interrupt + drop count=${this.pendingUserMessageCount}`)
+        // Cancelled queued msgs: remove the OneSecond (no longer waiting)
+        // and stamp a CrossMark (explicit cancelled state, distinct from
+        // a natural release where reactions just disappear). Cancelled
+        // mid-batch msgs get the same treatment.
+        for (const [msgId, rid] of [
+          ...this.pendingReactionIds.entries(),
+          ...this.currentBatchReactionIds.entries(),
+        ]) {
+          if (rid) void feishu.deleteReaction(msgId, rid)
+          void feishu.addReaction(msgId, 'CrossMark')
+        }
+        this.pendingUserMessageCount = 0
+        this.lastUserOpenId = ''
+        this.pendingReactionIds = new Map()
+        this.currentBatchReactionIds = new Map()
+        this.wantsRotation = false
+        this.interrupt()
+        return true
       case 'kill':
         await this.stop()
         return true
@@ -359,19 +489,62 @@ export class Session {
   }
 
   // ── Inbound from Feishu ────────────────────────────────────────────
-  async onUserMessage(text: string, files: string[] = [], userOpenId = ''): Promise<void> {
+  /** Inbound user message. Always writes to Claude's stdin immediately —
+   * the SDK queues internally if a turn is in flight (FIFO, exactly the
+   * type-ahead semantics of the native claude-code REPL). Card opening:
+   *   - First msg of session OR no turn in flight  → open card eagerly here
+   *   - Mid-flight msg                              → defer; the `init`
+   *     handler opens its card when the SDK actually starts the turn
+   * This is what lets a single subprocess host both user-typed turns and
+   * cron-fired wakeups without the daemon ever calling `sendInterrupt` —
+   * `kill`/`stop` are the only paths that interrupt now. */
+  async onUserMessage(text: string, files: string[] = [], userOpenId = '', msgId = ''): Promise<void> {
     if (!this.isRunning()) {
       const ok = await this.start()
       if (!ok) return
     }
-    if (this.currentTurn) {
-      log(`session "${this.sessionName}": new turn arriving mid-flight, interrupting`)
-      this.proc!.sendInterrupt()
-      await this.closeTurnCard('🛑 用户打断')
-    }
-    await this.openTurnCard(text, userOpenId)
+    // 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
+    this.pendingUserMessageCount++
+    this.lastUserOpenId = userOpenId
     this.proc!.sendUserText(text, files)
-    this.status = 'working'
+    if (wasBusy && msgId) {
+      // Hold the slot in the map even if the API call hasn't returned
+      // yet — empty string is a sentinel meaning "we tried to react;
+      // reaction_id pending". When deleteReaction time comes, an empty
+      // string is a no-op (deleteReaction guards against it), which is
+      // the right behavior if the add failed.
+      this.pendingReactionIds.set(msgId, '')
+      void (async () => {
+        const rid = await feishu.addReaction(msgId, 'OneSecond')
+        if (rid && this.pendingReactionIds.has(msgId)) {
+          this.pendingReactionIds.set(msgId, rid)
+        }
+      })()
+      // Rotation hint: a mid-turn user msg means the next assistant /
+      // tool event should split the visual into a new card.
+      this.wantsRotation = true
+    }
+    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).
+      // Claim one count and open the card with this message's own text +
+      // sender; any *additional* messages arriving during the open's
+      // Feishu API await will pile up in the count and get batched by the
+      // SDK into the NEXT turn (handled by the init handler).
+      this.openingTurn = true
+      this.pendingUserMessageCount--
+      try {
+        await this.openTurnCard(text, userOpenId, 'user_message')
+        this.status = 'working'
+      } finally {
+        this.openingTurn = false
+      }
+    }
   }
 
   async onPermissionDecision(
@@ -420,6 +593,15 @@ export class Session {
     return this.pendingAsks.size > 0
   }
 
+  /** True iff a turn is currently running (or a queued user message is
+   * waiting for its turn to start). daemon uses this to drop a hourglass
+   * reaction on inbound messages — without it the user sees no visible
+   * acknowledgement that their type-ahead message landed (the card
+   * doesn't open until the current turn finishes). */
+  isBusy(): boolean {
+    return this.currentTurn !== null || this.pendingUserMessageCount > 0
+  }
+
   /** Funnel an arbitrary chat message into the *current* question
    * of the oldest pending ask as a `customText` answer. Multi-
    * question semantics: from the user's perspective, the chat
@@ -575,6 +757,58 @@ export class Session {
         this.lastSessionId = p.sessionId
         feishu.bindSessionResume(this.sessionName, p.sessionId)
       }
+      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.
+      //
+      // 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.
+      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
+      const userOpenId = isUserBatch ? this.lastUserOpenId : ''
+      if (isUserBatch) {
+        this.pendingUserMessageCount = 0
+        // Inherit the queued reaction_ids — this turn is collectively
+        // responsible for releasing their OneSecond reactions when it
+        // closes (via deleteReaction in closeTurnCard).
+        this.currentBatchReactionIds = this.pendingReactionIds
+        this.pendingReactionIds = new Map()
+      }
+      this.openingTurn = true
+      void (async () => {
+        try {
+          await this.openTurnCard(
+            isUserBatch ? '' : '⏰ 定时唤醒',
+            userOpenId,
+            isUserBatch ? 'user_message' : 'scheduled',
+          )
+          this.status = 'working'
+        } finally {
+          this.openingTurn = false
+        }
+      })()
     })
     p.on('assistant_text', ({ text }: { text: string }) => {
       this.appendAssistant(text)
@@ -604,6 +838,13 @@ export class Session {
       log(`session "${this.sessionName}": claude exited code=${code} signal=${signal} expected=${expected}`)
       this.proc = null
       this.currentTurn = null
+      this.pendingUserMessageCount = 0
+      this.lastUserOpenId = ''
+      this.pendingReactionIds = new Map()
+      this.currentBatchReactionIds = new Map()
+      this.wantsRotation = false
+      this.initCount = 0
+      this.openingTurn = false
       this.status = 'stopped'
       if (!expected && code !== 0 && signal !== 'SIGTERM') {
         void feishu.sendText(this.chatId, `⚠️ Claude 异常退出 (code=${code}, signal=${signal})。回复任意消息将重新启动。`)
@@ -642,13 +883,14 @@ export class Session {
     return this.lastTurnDelta?.inputTokens ?? 0
   }
 
-  private async openTurnCard(userText: string, userOpenId: string): Promise<void> {
+  private async openTurnCard(userText: string, 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 }
@@ -659,6 +901,7 @@ export class Session {
       cardId,
       messageId,
       userOpenId,
+      trigger,
       userText,
       thinkingText: '',
       toolCount: 0,
@@ -676,8 +919,43 @@ export class Session {
   // forget here and rely on enqueue source order — that way no `await`
   // can yield mid-handler and let `closeTurnCard` (or another event) race
   // and mutate `this.currentTurn` underfoot.
+  /** Rotate to a fresh card mid-turn: close the in-flight card with a
+   * `📨 转交新卡` footer (distinct from `✅ done` and `🛑 打断`) and
+   * open a new card so the post-user-message continuation has a
+   * visible boundary. Streams that land during the rotation's await
+   * windows are buffered in `rotationBuffer` and replayed onto the
+   * new card the moment it's ready, so no tokens are lost across the
+   * cut. Caller guarantees `wantsRotation` was true sync-immediately
+   * before. */
+  private async rotateCard(): Promise<void> {
+    this.openingTurn = true
+    try {
+      await this.closeTurnCard('📨 转交新卡')
+      await this.openTurnCard('', this.lastUserOpenId, 'user_message')
+    } finally {
+      this.openingTurn = false
+    }
+    if (this.rotationBuffer.length === 0) return
+    const buf = this.rotationBuffer
+    this.rotationBuffer = []
+    for (const e of buf) {
+      if (e.kind === 'assistant') this.appendAssistant(e.delta)
+      else if (e.kind === 'thinking') this.appendThinking(e.delta)
+      else if (e.kind === 'tool_use') this.addTool(e.id, e.name, e.input)
+    }
+  }
+
   private appendAssistant(delta: string): void {
-    if (!this.currentTurn) return
+    if (!this.currentTurn) {
+      if (this.openingTurn) this.rotationBuffer.push({ kind: 'assistant', delta })
+      return
+    }
+    if (this.wantsRotation) {
+      this.wantsRotation = false
+      this.rotationBuffer.push({ kind: 'assistant', delta })
+      void this.rotateCard()
+      return
+    }
     if (!this.currentTurn.currentAssistantSegmentId) {
       const i = this.currentTurn.assistantSegmentCount++
       const segId = cards.ELEMENTS.assistant(i)
@@ -703,7 +981,16 @@ export class Session {
   }
 
   private appendThinking(delta: string): void {
-    if (!this.currentTurn) return
+    if (!this.currentTurn) {
+      if (this.openingTurn) this.rotationBuffer.push({ kind: 'thinking', delta })
+      return
+    }
+    if (this.wantsRotation) {
+      this.wantsRotation = false
+      this.rotationBuffer.push({ kind: 'thinking', delta })
+      void this.rotateCard()
+      return
+    }
     this.currentTurn.thinkingText += delta
     cardkit.streamTextThrottled(
       this.currentTurn.cardId,
@@ -721,7 +1008,16 @@ export class Session {
   }
 
   private addTool(toolUseId: string, name: string, input: any): void {
-    if (!this.currentTurn) return
+    if (!this.currentTurn) {
+      if (this.openingTurn) this.rotationBuffer.push({ kind: 'tool_use', id: toolUseId, name, input })
+      return
+    }
+    if (this.wantsRotation) {
+      this.wantsRotation = false
+      this.rotationBuffer.push({ kind: 'tool_use', id: toolUseId, name, input })
+      void this.rotateCard()
+      return
+    }
     // Close current assistant segment (if any) so the tool panel renders
     // AFTER it in card body order. Flush queues the segment's last
     // buffered delta before the tool element is inserted.
@@ -1007,7 +1303,11 @@ export class Session {
       await cardkit.replaceElement(cardId, cards.ELEMENTS.thinking, cards.thinkingCollapsedPanel(thinkingText))
     }
     const sendNote = sendPaths.length ? ` · 📎 ${sendPaths.length}` : ''
-    const footer = `⏱ ${elapsed}s${suffix ? ' · ' + suffix : ''}${sendNote} · ✅ done`
+    // Suffix REPLACES the trailing `✅ done` — it represents a terminal
+    // state distinct from natural completion (e.g. `📨 转交新卡` for a
+    // mid-turn rotation). When absent, the turn ended cleanly.
+    const stateMark = suffix ? ` · ${suffix}` : ' · ✅ done'
+    const footer = `⏱ ${elapsed}s${sendNote}${stateMark}`
     await cardkit.streamText(cardId, cards.ELEMENTS.footer, footer)
     // Final chat-list preview: clean finish shows "⏱ Xs · NK tokens";
     // interrupted shows the suffix instead (no usage event landed).
@@ -1023,12 +1323,44 @@ export class Session {
 
     // Phone push on clean turn close so the user knows Claude is done
     // even with the chat backgrounded. Skip on interrupts (no real
-    // completion) and when we don't know who to ping. Fire-and-forget;
-    // urgent_app failures are non-fatal and already logged in feishu.ts.
-    if (!suffix && turn.userOpenId && turn.messageId) {
+    // completion), when we don't know who to ping, and when the turn
+    // wasn't kicked off by the user typing a message — scheduled /
+    // cron / loop wakeups finish on their own and shouldn't ping the
+    // phone. Fire-and-forget; urgent_app failures are non-fatal and
+    // already logged in feishu.ts.
+    if (!suffix && turn.trigger === 'user_message' && turn.userOpenId && turn.messageId) {
       void feishu.urgentApp(turn.messageId, [turn.userOpenId])
     }
 
+    // Release the OneSecond reactions on every queued Feishu message
+    // this turn was responsible for. Two buckets:
+    //   1. `currentBatchReactionIds` — msgs the init handler explicitly
+    //      claimed (SDK dequeued them as a merged next-turn batch).
+    //   2. `pendingReactionIds` — msgs whose fate is invisible to the
+    //      daemon: the SDK either dequeued them as part of the
+    //      JUST-CLOSED turn OR injected them mid-turn as
+    //      `<system-reminder>` and silently removed them from the
+    //      queue (common when the current turn had tool calls).
+    //      Without visibility into queue-operation events the daemon
+    //      can't tell which; the safe default is "the prior turn just
+    //      ended, so the msg is at least *acknowledged* now —
+    //      release the OneSecond and let it stop saying 'queued',
+    //      instead of leaving it stuck permanently."
+    //      For merged-batch follow-ups, this releases slightly early
+    //      (before the merged turn actually runs), which is an
+    //      acceptable trade vs. msgs stuck under OneSecond forever.
+    const releaseEntries = [
+      ...this.currentBatchReactionIds.entries(),
+      ...this.pendingReactionIds.entries(),
+    ]
+    if (releaseEntries.length > 0) {
+      for (const [msgId, rid] of releaseEntries) {
+        if (rid) void feishu.deleteReaction(msgId, rid)
+      }
+      this.currentBatchReactionIds = new Map()
+      this.pendingReactionIds = new Map()
+    }
+
     // Fire uploads sequentially AFTER the card is sealed so each file
     // posts as its own Feishu message below the conversation card.
     // Path gate: workDir (Claude's project sandbox), the inbox where

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
 }