fix(usage): keep last-good numbers through token-refresh gaps + per-cause messages

The usage footer blanked to a vague "사용량 표시 불가" whenever the Claude Code OAuth
access token briefly expired between Claude Code's own refreshes: getUsageWindows
returned 'expired' BEFORE the last-good-cache fallback, discarding perfectly good
recent numbers. A 401 (token rejected server-side) was also lumped into 'offline'.

- On a locally-expired token, fall back to the last-good cache (the numbers don't
  change during the few-second refresh gap) instead of blanking; only report
  'expired' when nothing is cached at all.
- Map a 401 response to 'expired' (re-login), distinct from 429 ('rate-limited')
  and other failures ('offline').
- Surface each transient cause with its own actionable message instead of one vague
  line: new pure usageErrorKey() (expired→re-login / rate-limited / offline; null =
  hide for not-logged-in / non-subscriber). New locale keys usage.bar_expired /
  usage.bar_ratelimited (en/ko/ja/zh).

289 tests (+5). Diagnosed via systematic-debugging; removes the blink the user hit
and makes the rare message say what to do.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: writingdeveloper

README.md

@@ -11,7 +11,7 @@ See every repo's state at a glance — git status, how long it's been neglected,
 ![License](https://img.shields.io/badge/license-MIT-blue)
 ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-0078D6)
 ![Built with Electron](https://img.shields.io/badge/Electron-31-47848F)
-![Tests](https://img.shields.io/badge/tests-284%20passing-3fb950)
+![Tests](https://img.shields.io/badge/tests-289%20passing-3fb950)
 ![CI](https://github.com/writingdeveloper/devdeck/actions/workflows/ci.yml/badge.svg)
 
 <img src="docs/demo/demo.gif" width="820" alt="DevDeck demo" />

package.json

@@ -1,6 +1,6 @@
 {
   "name": "devdeck",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "description": "Project command deck — at-a-glance state + claude -c resume",
   "main": "dist/main/main.js",
   "type": "commonjs",

src/main/claudeUsage.test.ts

@@ -78,4 +78,23 @@ describe('getUsageWindows', () => {
     const r = await getUsageWindows(deps({ fetchUsage: async () => ({ ok: false, status: 0 }) }));
     expect(r).toEqual({ enabled: true, error: 'offline' });
   });
+
+  it('expired token but last-good cache present => serves last-good (no blank "unavailable")', async () => {
+    // token expired AND the cache is stale (>5min) so the fresh-TTL path doesn't fire — must still
+    // keep showing the recent numbers through the brief Claude-Code token-refresh gap, not blank out.
+    const cached = { timestamp: 1000, data: { planName: 'Max', fiveHour: 12, sevenDay: 20, fiveHourResetAt: 1, sevenDayResetAt: 1 } };
+    const r = await getUsageWindows(deps({ now: () => 1000 + 10 * 60_000, cacheRead: () => cached, readCredentials: () => ({ ...baseCreds, expiresAt: 500 }) }));
+    expect(r).toEqual({ enabled: true, data: cached.data });
+  });
+
+  it('401 from the usage API => error expired (token rejected → re-login), not offline', async () => {
+    const r = await getUsageWindows(deps({ fetchUsage: async () => ({ ok: false, status: 401 }) }));
+    expect(r).toEqual({ enabled: true, error: 'expired' });
+  });
+
+  it('401 but last-good cache present => serves last-good', async () => {
+    const cached = { timestamp: 1000, data: { planName: 'Max', fiveHour: 4, sevenDay: 6, fiveHourResetAt: 1, sevenDayResetAt: 1 } };
+    const r = await getUsageWindows(deps({ now: () => 1000 + 10 * 60_000, cacheRead: () => cached, fetchUsage: async () => ({ ok: false, status: 401 }) }));
+    expect(r).toEqual({ enabled: true, data: cached.data });
+  });
 });

src/main/claudeUsage.ts

@@ -51,7 +51,12 @@ export async function getUsageWindows(deps: UsageDeps): Promise<UsageResult> {
 
   const creds = deps.readCredentials();
   if (!creds) return { enabled: true, error: 'no-credentials' };
-  if (creds.expiresAt != null && creds.expiresAt <= now) return { enabled: true, error: 'expired' };
+  // Token expired locally: Claude Code refreshes the file on its own, but there's a brief gap. Keep
+  // showing the last-good numbers through it (they don't change) instead of blanking the bar; only
+  // report 'expired' if we have nothing cached at all.
+  if (creds.expiresAt != null && creds.expiresAt <= now) {
+    return fresh ? { enabled: true, data: fresh.data } : { enabled: true, error: 'expired' };
+  }
 
   const plan = planName(creds.subscriptionType);
   if (!plan) return { enabled: true, error: 'not-applicable' };
@@ -60,7 +65,10 @@ export async function getUsageWindows(deps: UsageDeps): Promise<UsageResult> {
   if (!res.ok) {
     // On any failure, fall back to last-good cache (even if stale) so the bar stays useful.
     if (fresh) return { enabled: true, data: fresh.data };
-    return { enabled: true, error: res.status === 429 ? 'rate-limited' : 'offline' };
+    // 401 = the token was rejected server-side (expired/invalid) → tell the user to re-login, same as
+    // a locally-expired token; 429 = usage-API rate limit; everything else = offline/transient.
+    const error = res.status === 401 ? 'expired' : res.status === 429 ? 'rate-limited' : 'offline';
+    return { enabled: true, error };
   }
   const parsed = parseUsageResponse(res.body);
   if (!parsed) {

src/renderer/locales/en.json

@@ -133,6 +133,8 @@
   "usage.bar_week": "Weekly",
   "usage.bar_reset": "until reset",
   "usage.bar_unavailable": "Usage unavailable",
+  "usage.bar_expired": "Login expired · re-login",
+  "usage.bar_ratelimited": "Usage API busy · retry soon",
   "usage.reset_soon": "soon",
   "usage.reset_d": "Xd Yh",
   "usage.reset_h": "Xh Ym",

src/renderer/locales/ja.json

@@ -133,6 +133,8 @@
   "usage.bar_week": "週間",
   "usage.bar_reset": "後にリセット",
   "usage.bar_unavailable": "使用量を表示できません",
+  "usage.bar_expired": "ログイン期限切れ · 再ログイン",
+  "usage.bar_ratelimited": "使用量API混雑 · 後で",
   "usage.reset_soon": "まもなく",
   "usage.reset_d": "X日Y時間",
   "usage.reset_h": "X時間Y分",

src/renderer/locales/ko.json

@@ -133,6 +133,8 @@
   "usage.bar_week": "주간",
   "usage.bar_reset": "후 리셋",
   "usage.bar_unavailable": "사용량 표시 불가",
+  "usage.bar_expired": "로그인 만료 · 재로그인",
+  "usage.bar_ratelimited": "사용량 API 혼잡 · 잠시 후",
   "usage.reset_soon": "곧",
   "usage.reset_d": "X일 Y시간",
   "usage.reset_h": "X시간 Y분",

src/renderer/locales/zh.json

@@ -133,6 +133,8 @@
   "usage.bar_week": "每周",
   "usage.bar_reset": "后重置",
   "usage.bar_unavailable": "无法显示用量",
+  "usage.bar_expired": "登录已过期 · 重新登录",
+  "usage.bar_ratelimited": "用量API繁忙 · 稍后重试",
   "usage.reset_soon": "即将",
   "usage.reset_d": "X天Y小时",
   "usage.reset_h": "X小时Y分",

src/renderer/usageBar.ts

@@ -1,5 +1,5 @@
 import { tr } from './i18n-runtime';
-import { severity, formatReset, type UsageResult, type UsageWindows } from '../shared/usageWindows';
+import { severity, formatReset, usageErrorKey, type UsageResult, type UsageWindows } from '../shared/usageWindows';
 
 const POLL_MS = 5 * 60_000;
 let el: HTMLElement;
@@ -18,9 +18,10 @@ export async function refreshUsageBar(): Promise<void> {
   try { res = await window.devdeck.usageWindows(); } catch { res = { enabled: true, error: 'offline' }; }
   if (!res.enabled) { el.classList.add('hidden'); stopTimer(); return; }
   if ('error' in res) {
-    // Don't nag users who aren't Claude Code subscribers / aren't logged in — just hide the bar.
-    if (res.error === 'not-applicable' || res.error === 'no-credentials') { el.classList.add('hidden'); }
-    else { renderMsg('usage.bar_unavailable'); } // expired / offline / rate-limited — transient
+    // null = not a Claude subscriber / not logged in → hide (no nagging); otherwise a specific,
+    // actionable message (expired→re-login / rate-limited / offline).
+    const key = usageErrorKey(res.error);
+    if (key) renderMsg(key); else el.classList.add('hidden');
     startTimer();
     return;
   }

src/shared/usageWindows.test.ts

@@ -1,6 +1,6 @@
 // src/shared/usageWindows.test.ts
 import { describe, it, expect } from 'vitest';
-import { severity, clampPct, formatReset, parseUsageResponse } from './usageWindows';
+import { severity, clampPct, formatReset, parseUsageResponse, usageErrorKey } from './usageWindows';
 
 describe('severity', () => {
   it('ok < 70, warn 70..89, crit >= 90', () => {
@@ -41,6 +41,18 @@ describe('formatReset', () => {
   });
 });
 
+describe('usageErrorKey', () => {
+  it('hides (null) when not logged in or not applicable — no nagging', () => {
+    expect(usageErrorKey('no-credentials')).toBeNull();
+    expect(usageErrorKey('not-applicable')).toBeNull();
+  });
+  it('maps each transient failure to a specific, actionable message key', () => {
+    expect(usageErrorKey('expired')).toBe('usage.bar_expired');
+    expect(usageErrorKey('rate-limited')).toBe('usage.bar_ratelimited');
+    expect(usageErrorKey('offline')).toBe('usage.bar_unavailable');
+  });
+});
+
 describe('parseUsageResponse', () => {
   it('extracts utilization + resets_at', () => {
     const body = {