@cocorograph/hub-agent 0.7.28 → 0.7.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.7.28",
+  "version": "0.7.30",
   "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの tmux/pty を中継する。",
   "type": "module",
   "license": "UNLICENSED",

package/src/claude-stream-bridge.mjs

@@ -568,18 +568,27 @@ class ClaudeStreamSession {
     }
   }
 
-  /** モデルが Opus 4.6+ (effort / adaptive thinking 対応) かどうか。
+  /** モデルが effort / adaptive thinking 対応 (Opus 4.6+ / Fable 5) かどうか。
    *  budget 方式 (maxThinkingTokens) は Opus 4.7+ で廃止扱いのため、effort モデルでは
-   *  effort + thinking:{type:'adaptive'} に切り替える。 */
+   *  effort + thinking:{type:'adaptive'} に切り替える。
+   *  ⚠️ frontend の isEffortModelByPattern (types/cockpit.ts) と同一パターンを維持する
+   *  こと。旧実装は fable-5 を含まず、frontend が effort を送っても bridge が非 effort
+   *  分岐に入り「effort も budget も未適用」になる不整合があった (2026-07-02 修正)。 */
   _isEffortModel() {
-    return typeof this.model === "string" && /claude-opus-4-[678]/.test(this.model)
+    return (
+      typeof this.model === "string" && /claude-fable-5|claude-opus-4-[678]/.test(this.model)
+    )
   }
 
   /** 思考関連オプション (effort / adaptive thinking / 旧 budget) を options へ適用する。
    *  per-message / 常駐 query の両方から呼ぶ共通ロジック (分岐の二重定義を避ける)。 */
   _applyThinkingOptions(options) {
-    if (this._isEffortModel()) {
-      // Opus: adaptive thinking を明示 ON にし、effort で深さを指定する。
+    // model 未指定 (= browser が agent/アカウント既定モデルへ委任) でも、browser が
+    // effort を明示送信してきた場合は effort 分岐に入れる。frontend は system/init の
+    // 実効モデル (runtimeModel) で capability 判定してから effort を送るため、ここでは
+    // その判断を信頼する (2026-07-02)。
+    if (this._isEffortModel() || (!this.model && this.effort)) {
+      // effort モデル: adaptive thinking を明示 ON にし、effort で深さを指定する。
       // budget 方式 (maxThinkingTokens) は使わない (Opus 4.7+ で非対応)。
       options.thinking = { type: "adaptive" }
       if (this.effort) options.effort = this.effort
@@ -803,6 +812,26 @@ class ClaudeStreamSession {
         } catch {
           /* ignore */
         }
+        // 停止即時化 (2026-07-02): onTurnSettled はチャット信号 (サイドバードット) 専用で、
+        // browser の SDK ストリーム UI (turnActive / interrupting) を解除するイベントでは
+        // ない。abort でターンが終わると result が届かず、UI は 120s 無音ウォッチドッグ
+        // まで「停止中…」のまま固着する。合成 result を通常のイベント経路 (claude.event)
+        // へ流し、reducer にターン終了を即時確定させる。subtype はユーザー中断 (abort) と
+        // 異常終了 (result 無しの自然終了) を区別する (frontend は前者を「中断しました」
+        // フッターで表示する)。uuid を持たせるのは重複排除 (isDuplicateEvent) が result
+        // 署名 (session_id + num_turns + duration_ms + cost) で判定するため — 合成 result
+        // はこれらが毎回同値になり、2 回目以降の中断で「重複」と誤判定され捨てられるのを防ぐ。
+        try {
+          this._emit({
+            type: "result",
+            subtype: aborted ? "aborted_by_user" : "turn_settled",
+            uuid: randomUUID(),
+            session_id: this.sessionId ?? undefined,
+            timestamp: new Date().toISOString(),
+          })
+        } catch {
+          /* ignore */
+        }
       }
       // graceful detach: browser が切れている間にターンが完走したら、ここで遅延
       // クローズする。manager 側で sessions Map から撤去 + exit を emit する。
@@ -1559,6 +1588,73 @@ export class ClaudeStreamBridge extends EventEmitter {
     return this._mergeNeedsAuthCache(servers)
   }
 
+  /**
+   * アカウント全体の 5h/7d rate-limit 使用率 + プラン種別を返す (usage.mjs
+   * recordChatUsageSnapshot に渡す想定)。mcpStatus と同じ control-only query を共有する
+   * (account-level = session/チャット非依存。statusLine が動かない純 SDK チャット運用でも
+   * 取得できる)。
+   *
+   * SDK の `usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET()` は unstable な
+   * 実験的 API のため、失敗 (未実装 SDK バージョン / 一時的なエラー等) は null を返す。
+   * 呼び出し側 (main.mjs `usage.request` ハンドラ) は null なら何もせず、既存の
+   * statusLine / transcript 推定フォールバックに委ねる。
+   *
+   * @returns {Promise<import('@anthropic-ai/claude-agent-sdk').SDKControlGetUsageResponse|null>}
+   */
+  async getAccountUsage() {
+    try {
+      const q = await this._ensureMcpControlQuery()
+      this._armMcpControlIdle()
+      if (typeof q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET !== "function") {
+        return null
+      }
+      return await q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET()
+    } catch (err) {
+      this.logger?.warn(
+        { err: err?.message },
+        "getAccountUsage failed (SDK experimental usage API)",
+      )
+      return null
+    }
+  }
+
+  /**
+   * 指定 cwd で現在ライブな (browser 接続中、または detach 猶予内の) SDK チャット
+   * session_id を返す。無ければ null。
+   *
+   * TUI モードには tuiReboundSessions による bound session 解決 (main.mjs
+   * `turnActiveForCwd`/`jsonlContextForCwd` 呼び出し) があるが、チャット (SDK stream)
+   * モードには同等の仕組みが無かった。同一 cwd の encode dir にはチャット本体の他に
+   * サブエージェント / headless `claude -p` (記憶蒸留 Stop hook 等) / 過去セッションの
+   * jsonl が堆積するため、bound 指定無しの mtime 最新フォールバックは cross-activity
+   * 汚染 (無関係な jsonl を「そのチャット」と誤認) を起こし得る。本メソッドはチャット版
+   * の bound session 解決として main.mjs (startStateLoop / tmux.list_sessions ハンドラ)
+   * から使う。同一 cwd に複数ライブセッションがある場合は最終アクティビティが最も
+   * 新しいものを採用する。
+   *
+   * @param {string} cwd
+   * @returns {string|null}
+   */
+  liveSessionIdForCwd(cwd) {
+    if (!cwd) return null
+    let best = null
+    let bestAt = -1
+    const seen = new Set()
+    for (const session of this.sessions.values()) {
+      if (seen.has(session) || session.cwd !== cwd || !session.sessionId) continue
+      seen.add(session)
+      let at = 0
+      for (const t of session.lastActivityByStream.values()) {
+        if (t > at) at = t
+      }
+      if (at > bestAt) {
+        bestAt = at
+        best = session.sessionId
+      }
+    }
+    return best
+  }
+
   /**
    * `mcpServerStatus()` の結果に、needs-auth キャッシュにあるが結果へ含まれない
    * サーバーを `needs-auth` として補完する。

package/src/main.mjs

@@ -98,6 +98,7 @@ import {
   getUsage,
   isFreshUnboundBind,
   recordChatRateLimit,
+  recordChatUsageSnapshot,
   turnActiveForCwd,
 } from "./usage.mjs"
 import {
@@ -271,12 +272,21 @@ async function loadClaudeSdk(logger) {
 
 /**
  * B7: 直列 dispatchChain をバイパスして即時処理してよい高頻度・低レイテンシ経路かを判定する。
- * pty 出力データ (pty.data) と resize (pty.resize) のみ true。入力系 (claude.input)・制御系
- * (tmux.exec / permission / cancel→paste 等) は WS 受信順 = pane 反映順を守るため false
- * (= 直列キューに残す)。1 件の tmux.exec ハングで pty 入出力まで止まるのを防ぐ。
+ * - pty 出力データ (pty.data) と resize (pty.resize): 高頻度・順序保証不要。
+ * - claude.interrupt / codex.interrupt (2026-07-02): 停止指示。前段に重い dispatch
+ *   (tmux.exec 等) が滞留していると停止が遅延するため直列キューをバイパスする。
+ *   中断は「現ターンを止める」冪等な制御で、入力系のような順序依存が無い (むしろ
+ *   キュー内の後続入力より先に届くべき)。
+ * 入力系 (claude.input)・他の制御系 (tmux.exec / permission / cancel→paste 等) は
+ * WS 受信順 = pane 反映順を守るため false (= 直列キューに残す)。
  */
 export function isFastPathMessage(type) {
-  return type === "pty.data" || type === "pty.resize"
+  return (
+    type === "pty.data" ||
+    type === "pty.resize" ||
+    type === "claude.interrupt" ||
+    type === "codex.interrupt"
+  )
 }
 
 /**
@@ -1334,6 +1344,61 @@ export function enrichTmuxSessionsForListResponse(
   })
 }
 
+/**
+ * state loop 内で「チャット信号 (getChatSignal) でペイン status/context_pct を上書きするか」
+ * を決める純関数 (startStateLoop から抽出、単体テスト用)。
+ *
+ * バグ修正 (2026-07): 従来コードは書き換え「後」の status で processing ガードを判定して
+ * いたため、チャット自身が processing を立てたときに自分自身の条件 (`status !== "processing"`)
+ * を満たせなくなり、SDK チャット生成中はドーナツ (context_pct) が一切更新されなかった。
+ * 本関数は判定を必ず「上書き前の pane 由来 status (paneStatus)」で行う。ペイン
+ * (capture-pane) が実際に processing (= 本物の TUI が生成中) の場合のみチャット信号での
+ * 上書きを止める。それ以外 (pane が idle 等 = SDK チャット専用ペイン含む) は常にチャット
+ * 信号を優先する。
+ *
+ * @param {string} paneStatus capture-pane 由来の生 status (上書き前)
+ * @param {number|null|undefined} paneContextPct capture-pane 由来の生 context_pct
+ * @param {{status?:string|null, context_pct?:number|null}|null} chat getChatSignal() の戻り値
+ * @returns {{status:string, contextPct:number|null|undefined}}
+ */
+export function applyChatOverlay(paneStatus, paneContextPct, chat) {
+  let status = paneStatus
+  let contextPct = paneContextPct
+  if (chat) {
+    const paneIsProcessing = paneStatus === "processing"
+    if (chat.status && !paneIsProcessing) status = chat.status
+    if (typeof chat.context_pct === "number" && !paneIsProcessing) {
+      contextPct = chat.context_pct
+    }
+  }
+  return { status, contextPct }
+}
+
+/**
+ * turnActiveForCwd / jsonlContextForCwd に渡す bound session_id を解決する純関数。
+ *
+ * TUI (tuiReboundSessions, tmux セッション名キー) を優先し、無ければ claudeBridge の
+ * ライブ SDK チャットセッション (cwd キー) にフォールバックする。チャットモードには
+ * tmux 上の bind 台帳が無いため、これが無いとチャット信号 stale (90s 無活動) 時の
+ * フォールバックが cwd の encode dir 内の別アクティビティ jsonl (サブエージェント /
+ * headless `claude -p` / 過去セッション等) を「最新」と取り違える cross-activity 汚染を
+ * 起こし得る (TUI 版は tuiReboundSessions で 2026-06 に根治済み。本関数はチャット版の同根治)。
+ *
+ * @param {Map<string,string>|null|undefined} boundSessions ctx.tuiReboundSessions
+ * @param {string} sessionName tmux セッション名
+ * @param {string|null|undefined} cwd
+ * @param {{liveSessionIdForCwd?: (cwd:string)=>string|null}|null|undefined} claudeBridge
+ * @returns {string|null}
+ */
+export function resolveStateLoopBoundSessionId(boundSessions, sessionName, cwd, claudeBridge) {
+  const tuiId = boundSessionId(boundSessions, sessionName)
+  if (tuiId) return tuiId
+  if (cwd && claudeBridge && typeof claudeBridge.liveSessionIdForCwd === "function") {
+    return claudeBridge.liveSessionIdForCwd(cwd) || null
+  }
+  return null
+}
+
 export function startStateLoop({ client, plugins, logger, intervalMs, claudeBridge, readinessTracker, boundSessions }) {
   const lastByName = new Map() // session_name → {status, context_pct}
   const lastTurnAtByName = new Map() // session_name → 最後に event ファイル化した turnAt
@@ -1370,25 +1435,25 @@ export function startStateLoop({ client, plugins, logger, intervalMs, claudeBrid
       await refreshContextWindow()
       const states = await listSessionStates({ plugins, logger })
       for (const s of states) {
-        let status = s.status
-        let contextPct = s.context_pct
         // 対話 TUI のペインから読んだ権限モード (素のシェル / SDK チャットでは null)。
         // tmux 上で直接 shift+tab した変更もここで拾い、全ブラウザへ追従させる。
         const permissionMode = s.permission_mode ?? null
         // チャットモード補完: tmux ペインのスクレイプは TUI 前提で効かないため、
         // session の cwd に一致する新鮮なチャット信号があれば status/context% を
         // 上書きする (Hub ホスト型 Cockpit のステータスドット/各行ドーナツ用)。
+        // capture-pane が processing (= ペインに "esc to interrupt" が実在 = 本物の
+        // TUI が生成中) のときのみチャット信号で上書きしない (判定は applyChatOverlay
+        // 内部で必ず「上書き前の pane 由来 status (s.status)」を使う。2026-07 バグ修正:
+        // 旧実装は書き換え後の status で判定していたため、SDK チャット生成中はドーナツが
+        // 一切更新されなかった)。素のシェル (SDK チャットのペイン) は processing を
+        // 返せないため、SDK チャットの補完は従来どおり効く。TUI 生成中に stale な SDK
+        // status (waiting) が勝ってステータスドット/三点リーダーが消える事故の防止
+        // (2026-06-12) は paneIsProcessing ガードのまま維持される。
         const chat = s.cwd ? getChatSignal(s.cwd) : null
+        const overlay = applyChatOverlay(s.status, s.context_pct, chat)
+        let status = overlay.status
+        let contextPct = overlay.contextPct
         if (chat) {
-          // capture-pane が processing (= ペインに "esc to interrupt" が実在 = 本物の
-          // TUI が生成中) のときはチャット信号で上書きしない。素のシェル (SDK チャット
-          // のペイン) は processing を返せないため、SDK チャットの補完は従来どおり効く。
-          // TUI 生成中に stale な SDK status (waiting) が勝ってステータスドット/
-          // 三点リーダーが消える事故の防止 (2026-06-12)。
-          if (chat.status && status !== "processing") status = chat.status
-          if (typeof chat.context_pct === "number" && status !== "processing") {
-            contextPct = chat.context_pct
-          }
           // チャットのターン境界 (turnAt 前進) を sort 用 session-event に橋渡し。
           // tmux ペインが動かず bundle hook が発火しないため、ここで代替発火する。
           const prevTurnAt = lastTurnAtByName.get(s.session_name) || 0
@@ -1457,6 +1522,11 @@ export function startStateLoop({ client, plugins, logger, intervalMs, claudeBrid
         //    T2: tool_use 末尾 active 中の中断マーカー無しクラッシュ判定のため、tmux pane_current_command
         //    から claude プロセス生存を 3 値で返す paneClaudeAliveOrUnknown を probe として渡す。
         //    'dead' (シェル前景)→active=false に倒す。'alive'/'unknown' は active 維持(偽陰性ゼロ)。
+        //  - チャット信号が stale (90s 無活動) でこの else-if に落ちるケース: SDK チャットは
+        //    tmux bind 台帳 (tuiReboundSessions) を持たないため、従来は boundSessionId が常に
+        //    null を返し mtime 最新 jsonl へフォールバックしていた (chat 版の cross-activity
+        //    汚染, 2026-07 発覚)。resolveStateLoopBoundSessionId が claudeBridge のライブ
+        //    セッション id へフォールバックすることで TUI と同じ方式で根治する。
         let turnActive = null
         if (chat?.status === "processing") {
           turnActive = true
@@ -1470,7 +1540,7 @@ export function startStateLoop({ client, plugins, logger, intervalMs, claudeBrid
         } else if (s.cwd) {
           turnActive = await turnActiveForCwd(
             s.cwd,
-            boundSessionId(boundSessions, s.session_name),
+            resolveStateLoopBoundSessionId(boundSessions, s.session_name, s.cwd, claudeBridge),
             s.session_name,
             { paneAliveProbe: paneClaudeAliveOrUnknown },
           )
@@ -3302,10 +3372,13 @@ async function dispatch(msg, ctx) {
         try {
           // boundSessions: 各行の context% (ドーナツ) を bound session の jsonl から引く
           // (cwd dir 内の別セッション jsonl を最新と取り違える=メタ欠陥#1 の根治)。
+          // claudeBridge: TUI bind が無い SDK チャット cwd 向けの同根治フォールバック
+          // (2026-07 追加。tmux.mjs listSessions 参照)。
           const sessions = await listTmuxSessions({
             plugins: ctx.plugins,
             logger: ctx.logger,
             boundSessions: ctx.tuiReboundSessions,
+            claudeBridge: ctx.claudeBridge,
           })
           // 各 session の最新 hook event を /tmp/cockpit_session_events/ から読んで
           // レスポンスに含める (Phase 4: ハードリロード時の lastEvent 復元用)。
@@ -3572,6 +3645,20 @@ async function dispatch(msg, ctx) {
       }
       case "usage.request": {
         try {
+          // 5h/7d の本命ソース: SDK control request (アカウント全体、session 非依存)。
+          // statusLine が rate_limits を出さなくなった環境 (2026-07 時点の Claude CLI) でも
+          // ここでライブ更新できる。frontend の usage.request ポーリング (既定 60s) 頻度に
+          // 相乗りするだけで十分な鮮度が保てるため、専用タイマーは設けない。EXPERIMENTAL
+          // API の失敗は getAccountUsage 内で握りつぶし null を返す (recordChatUsageSnapshot
+          // は no-op) ので、既存の statusLine/transcript フォールバックは無傷で残る。
+          if (ctx.claudeBridge) {
+            try {
+              const acct = await ctx.claudeBridge.getAccountUsage()
+              if (acct) recordChatUsageSnapshot(acct)
+            } catch (err) {
+              ctx.logger?.debug?.({ err: err?.message }, "account usage snapshot skipped")
+            }
+          }
           const [usage, sessions] = await Promise.all([
             getUsage(),
             getSessionUsages(),

package/src/tmux.mjs

@@ -643,7 +643,15 @@ export async function listSessions(opts = {}) {
       //  4. それも無ければ pane scrape の正規表現フォールバック。
       const fromStatusLine = cwd ? ctxByCwd.get(cwd)?.contextPercent : null
       // bound session があればその jsonl で context% を引く (cwd dir の別セッション jsonl の取り違え回避)。
-      const boundId = boundSessionId(opts.boundSessions, s.name)
+      // TUI bind (opts.boundSessions, tmux セッション名キー) を優先し、無ければ SDK チャット
+      // (claudeBridge, cwd キー) のライブセッションへフォールバックする。チャットモードには
+      // tmux 上の bind 台帳が無いため、これが無いと cold-start (session.state snapshot 未取得)
+      // の poll 応答で cwd の別アクティビティ jsonl を「最新」と取り違える cross-activity 汚染が
+      // 起き得る (2026-07 発覚。TUI 版は本行の boundSessions 解決で既に根治済みだった)。
+      const boundId =
+        boundSessionId(opts.boundSessions, s.name) ||
+        (cwd && opts.claudeBridge?.liveSessionIdForCwd?.(cwd)) ||
+        null
       const jsonlInfo = cwd ? await jsonlContextForCwd(cwd, boundId) : null
       const context_pct =
         jsonlInfo?.isReset && typeof jsonlInfo.percent === "number"

package/src/usage.mjs

@@ -272,6 +272,125 @@ export function whenChatRateLimitsPersisted() {
   return _persistInFlight
 }
 
+// ---------------------------------------------------------------------------
+// SDK control request (`usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET`)
+// から取得した 5h/7d + plan のスナップショット (プロセス内共有 + ディスク永続化)。
+//
+// 背景: `recordChatRateLimit` (上記, SDK の `rate_limit_event`) は 2026-07 時点の
+// SDK/Claude CLI で `utilization` フィールドが送られなくなり (実測確認済み)、事実上
+// 常時 no-op 化した。加えて statusLine cache (`~/.hub/usage/latest.json`) 自体も
+// `rate_limits` を出さなくなったため (readOfficial 参照)、5h/7d はターミナル・
+// チャット両モードで estimate (transcript 集計の粗い近似) に落ちていた。
+//
+// SDK の control request `usage_EXPERIMENTAL_...()` は実測で正確な utilization/
+// resets_at を返すことを確認済み (claude-agent-sdk 0.3.198)。account-level (session
+// 非依存) なので、claude-stream-bridge.mjs の MCP control-only query を共有して
+// 定期的に呼び出し (main.mjs `usage.request` ハンドラ)、ここに記録する。
+//
+// 永続化先は statusLine cache とは別ファイル (`~/.hub/usage/chat-usage.json`)。
+// 同じ latest.json に混ぜると TUI の statusLine スクリプトが全文上書きで消してしまう
+// (旧 chatRateLimits の設計的弱点)。専用ファイルなら誰にも上書きされない。
+// ---------------------------------------------------------------------------
+
+function chatUsageCachePath() {
+  return configPath("HUB_CHAT_USAGE_CACHE", os.homedir(), ".hub", "usage", "chat-usage.json")
+}
+
+/** @type {{five_hour:{percent:number,resetAtMs:number|null}|null, seven_day:{percent:number,resetAtMs:number|null}|null, plan:string|null, updatedAtMs:number}|null} */
+let chatUsageSnapshot = null
+let _chatUsagePersistInFlight = Promise.resolve()
+
+/** SDKControlGetUsageResponse.rate_limits.{five_hour,seven_day} の 1 窓を正規化する。 */
+function normalizeRateLimitWindow(w) {
+  if (!w || typeof w !== "object") return null
+  const percent = typeof w.utilization === "number" ? w.utilization : null
+  if (percent === null) return null
+  let resetAtMs = null
+  if (typeof w.resets_at === "string") {
+    const t = Date.parse(w.resets_at)
+    if (!Number.isNaN(t)) resetAtMs = t
+  } else if (typeof w.resets_at === "number") {
+    resetAtMs = w.resets_at < 1e12 ? w.resets_at * 1000 : w.resets_at
+  }
+  return { percent, resetAtMs }
+}
+
+/**
+ * SDK control request `usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET()`
+ * の戻り値 (SDKControlGetUsageResponse) を取り込む。EXPERIMENTAL API なので形が
+ * 変わる可能性があり、想定外の入力は無視する (呼び出し側は try/catch で包む前提)。
+ *
+ * @param {{rate_limits_available?: boolean, rate_limits?: {five_hour?: object|null, seven_day?: object|null}|null, subscription_type?: string|null}|null} usageResponse
+ * @param {number} [now]
+ */
+export function recordChatUsageSnapshot(usageResponse, now = Date.now()) {
+  if (!usageResponse || typeof usageResponse !== "object") return
+  if (usageResponse.rate_limits_available === false) return
+  const rl = usageResponse.rate_limits
+  if (!rl || typeof rl !== "object") return
+  const five = normalizeRateLimitWindow(rl.five_hour)
+  const seven = normalizeRateLimitWindow(rl.seven_day)
+  if (!five && !seven) return
+  chatUsageSnapshot = {
+    five_hour: five,
+    seven_day: seven,
+    plan: usageResponse.subscription_type || chatUsageSnapshot?.plan || null,
+    updatedAtMs: now,
+  }
+  // P5(bug) と同じ直列化パターン (recordChatRateLimit 参照): 並行 persist の tmp 破壊/
+  // 中間状態読みを防ぐため、常に前回の persist 完了を待ってから次を実行する。
+  _chatUsagePersistInFlight = _chatUsagePersistInFlight.then(
+    () => persistChatUsageSnapshot(),
+    () => persistChatUsageSnapshot(),
+  )
+}
+
+async function persistChatUsageSnapshot() {
+  const snapshot = chatUsageSnapshot
+  if (!snapshot) return
+  const p = chatUsageCachePath()
+  try {
+    await fs.mkdir(path.dirname(p), { recursive: true })
+  } catch {
+    /* ignore */
+  }
+  const tmp = `${p}.tmp.${randomUUID()}`
+  try {
+    await fs.writeFile(tmp, JSON.stringify(snapshot))
+    await fs.rename(tmp, p)
+  } catch {
+    try {
+      await fs.unlink(tmp)
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/** 直近の chat usage snapshot 書き込みの完了を待つ。テスト用。 */
+export function whenChatUsageSnapshotPersisted() {
+  return _chatUsagePersistInFlight
+}
+
+/** プロセス内メモリを優先し、無ければディスク永続化 (hub-agent 再起動直後等) を読む。 */
+async function readChatUsageSnapshot() {
+  if (chatUsageSnapshot) return chatUsageSnapshot
+  const text = await readOrNull(chatUsageCachePath())
+  if (!text) return null
+  try {
+    const j = JSON.parse(text)
+    if (j && typeof j === "object" && typeof j.updatedAtMs === "number") return j
+  } catch {
+    /* ignore */
+  }
+  return null
+}
+
+/** テスト用: chatUsageSnapshot をクリアする。 */
+export function _resetChatUsageSnapshot() {
+  chatUsageSnapshot = null
+}
+
 async function readOfficial(now) {
   const text = await readOrNull(statuslineCache())
   if (!text) return null
@@ -284,8 +403,13 @@ async function readOfficial(now) {
   const rl = j.rate_limits ?? j.rateLimits ?? {}
   const five = rl.five_hour ?? rl.fiveHour ?? rl["5h"]
   const seven = rl.seven_day ?? rl.sevenDay ?? rl["7d"]
-  if (!five && !seven) return null
   const ctx = j.context_window?.used_percentage ?? j.contextWindow?.used_percentage ?? null
+  // 2026-07: Claude CLI 2.1.197+ の statusLine は rate_limits を出さなくなった
+  // (chatUsageSnapshot 由来の SDK control request がその代替本命ソースになる。
+  // 下の getUsage() 参照)。以前は rate_limits 欠落時に無関係な context_window まで
+  // 巻き込んで握りつぶしていた (ドーナツが常に jsonl 推定フォールバックへ落ちる副作用)。
+  // rate_limits と context の両方が無いときだけ official ソースとして無意味とみなす。
+  if (!five && !seven && ctx === null) return null
 
   const bucketize = (b, defaultLimit) => {
     if (!b) return { ...emptyBucket(defaultLimit), limit: defaultLimit }
@@ -310,7 +434,10 @@ async function readOfficial(now) {
   return {
     plan: j.plan || "official",
     computedAt: now,
-    source: "official",
+    // 5h/7d の実値が伴わない (rate_limits 欠落・context のみ) ときは "official" を名乗らない。
+    // badge/表示は source を「5h/7d の信頼度」の意味で使っているため、chatUsageSnapshot 等の
+    // 上位レイヤーがまだ埋めていない時点では honest に "estimate" を返す。
+    source: five || seven ? "official" : "estimate",
     context: typeof ctx === "number" ? ctx : null,
     last5h: bucketize(five, 100),
     last7d: bucketize(seven, 100),
@@ -1048,6 +1175,33 @@ export async function getUsage() {
       result.source = "official"
     }
   }
+
+  // SDK control request (usage_EXPERIMENTAL...) 由来のスナップショット。上の
+  // chatRateLimits (rate_limit_event) より本命の情報源 (utilization 欠落問題が無い、
+  // 2026-07 時点で実測確認済み)。statusLine / rate_limit_event のどちらよりも新しければ
+  // 上書きする。5h/7d が実際に埋まったときだけ source を official に昇格させる。
+  const chatSnap = await readChatUsageSnapshot()
+  if (chatSnap && chatSnap.updatedAtMs > 0) {
+    const baseline = Math.max(cacheMtime ?? 0, chatRateLimits.updatedAtMs || 0)
+    if (chatSnap.updatedAtMs > baseline) {
+      if (chatSnap.five_hour) {
+        result.last5h = {
+          ...result.last5h,
+          percent: chatSnap.five_hour.percent,
+          resetAtMs: chatSnap.five_hour.resetAtMs ?? result.last5h?.resetAtMs ?? null,
+        }
+      }
+      if (chatSnap.seven_day) {
+        result.last7d = {
+          ...result.last7d,
+          percent: chatSnap.seven_day.percent,
+          resetAtMs: chatSnap.seven_day.resetAtMs ?? result.last7d?.resetAtMs ?? null,
+        }
+      }
+      if (chatSnap.plan) result.plan = chatSnap.plan
+      if (chatSnap.five_hour || chatSnap.seven_day) result.source = "official"
+    }
+  }
   return result
 }