Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(usage): show Claude fetch failures without discarding stale bars

reviewe862567baf1d
diff --git a/CLAUDE.md b/CLAUDE.md
index f108819c7..20c7c313a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2964,6 +2964,11 @@ else, and its context links must keep classifying across restarts).
that host (cache eviction still runs against the FULL target list, so switching between two SSH
projects doesn't throw each host's cache away).
+- **Usage failure readouts** — an empty Claude snapshot with `status: error` says "Could not
+ read usage." in both the single-account and multi-account popovers, including beside healthy
+ provider rows. Nonempty snapshots retain their last-known bars on error; no error-specific
+ authentication advice is inferred from the status.
+
- **Remote usage** (SSH hosts, `src/core/usage/remote-claude-usage.ts`) — the source behind the
SSH scope above. v1 excluded remote accounts, which left a user whose Claude only ever runs on a
server staring at an empty indicator while the host had perfectly good numbers.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0223794bd..a8e8dc825 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -611,6 +611,10 @@ examples). If the same effect also WRITES, latch its first run: otherwise switch
mid-session applies stored state to whatever the user is doing right then, which is a different
feature from the one they asked for.
+**Usage readouts distinguish failed reads from empty data.** For Claude, show the failure when
+`status` is `error` and limits are empty, including beside other providers; preserve last-known
+bars when limits remain. Keep both single-account and multi-account views covered.
+
## Testing
`npm test` must pass, and `npm run typecheck` is the fastest gate.
diff --git a/src/renderer/components/UsageIndicator.test.tsx b/src/renderer/components/UsageIndicator.test.tsx
new file mode 100644
index 000000000..542418711
--- /dev/null
+++ b/src/renderer/components/UsageIndicator.test.tsx
@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { DEFAULT_SETTINGS, type ClaudeUsage, type ProviderUsage, type UsageLimit } from '@shared/types'
+import { useSettings } from '../state/settings'
+import { UsageIndicator } from './UsageIndicator'
+
+const limit: UsageLimit = {
+ kind: 'session', group: 'session', usedPercent: 37, severity: null,
+ resetsAt: null, windowMinutes: 300, scopeLabel: null, isActive: false
+}
+const snapshot = (status: ClaudeUsage['status'], limits: UsageLimit[] = []): ClaudeUsage => ({
+ status, limits, session: null, weekly: null, email: null, updatedAt: 0
+})
+
+let host: HTMLDivElement
+let root: Root
+let update: (u: ClaudeUsage) => void
+
+beforeEach(() => {
+ host = document.createElement('div')
+ document.body.appendChild(host)
+ root = createRoot(host)
+ useSettings.setState({ settings: { ...DEFAULT_SETTINGS, usagePercentMode: 'remaining' } })
+})
+
+afterEach(() => {
+ act(() => root.unmount())
+ host.remove()
+ useSettings.setState({ settings: DEFAULT_SETTINGS })
+ vi.unstubAllGlobals()
+})
+
+async function open(system: ClaudeUsage, account?: ClaudeUsage | 'pending', providers: ProviderUsage[] = []) {
+ if (account) useSettings.setState({ settings: {
+ ...DEFAULT_SETTINGS, usagePercentMode: 'remaining',
+ claudeAccounts: [{ id: 'work', label: 'Work', createdAt: 0 }]
+ } })
+ vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+ // No credentials, network, or running sessions: exercise the real component using bridge snapshots.
+ vi.stubGlobal('nodeTerminal', { usage: {
+ fetch: async (id?: string) => id
+ ? account === 'pending' ? new Promise<ClaudeUsage>(() => {}) : account
+ : system,
+ providers: async () => providers,
+ onUpdate: (listener: typeof update) => { update = listener; return () => {} }
+ } })
+ await act(async () => root.render(<UsageIndicator />))
+ await act(async () => host.querySelector('.usage-indicator')!.dispatchEvent(
+ new MouseEvent('mouseover', { bubbles: true })
+ ))
+}
+
+describe('Claude usage failure readout', () => {
+ it('distinguishes failed system and managed account reads from empty data', async () => {
+ await open(snapshot('error'), snapshot('error'))
+ expect(host.querySelectorAll('.usage-popover__empty')).toHaveLength(2)
+ for (const row of host.querySelectorAll('.usage-popover__empty')) {
+ expect(row.textContent).toBe('Could not read usage.')
+ }
+ })
+
+ it.each(['ok', 'fetching', 'unavailable'] as const)('keeps the empty account wording for %s', async (status) => {
+ await open(snapshot('ok', [limit]), snapshot(status))
+ expect(host.querySelector('.usage-popover__empty')?.textContent).toBe('No usage data.')
+ })
+
+ it('keeps the loading pulse while the managed account has no snapshot', async () => {
+ await open(snapshot('ok', [limit]), 'pending')
+ expect(host.querySelector('.usage-popover__empty.usage-pill__pulse')?.textContent).toBe('···')
+ })
+
+ it('preserves stale limit bars for both system and managed accounts', async () => {
+ await open(snapshot('ok', [limit]), snapshot('error', [limit]))
+ await act(async () => update(snapshot('error', [limit])))
+ expect(host.querySelectorAll('.usage-row')).toHaveLength(2)
+ expect(host.querySelector('.usage-popover__empty')).toBeNull()
+ for (const row of host.querySelectorAll('.usage-row')) expect(row.textContent).toContain('63%')
+ })
+
+ it('shows the failure without any managed accounts', async () => {
+ await open(snapshot('error'))
+ expect(host.querySelector('.usage-popover__empty')?.textContent).toBe('Could not read usage.')
+ })
+
+ it('still attributes the Claude failure when another provider has data', async () => {
+ await open(snapshot('error'), undefined, [{ provider: 'codex', account: null, status: 'ok', limits: [limit], updatedAt: 0 }])
+ expect(host.querySelector('.usage-popover__empty')?.textContent).toBe('Could not read usage.')
+ expect(host.querySelector('.usage-popover__body > .usage-account__label')?.textContent).toBe('Claude')
+ expect(host.querySelectorAll('.usage-row')).toHaveLength(1)
+ })
+
+ it('preserves stale bars in the single-account view', async () => {
+ await open(snapshot('error', [limit]))
+ expect(host.querySelectorAll('.usage-row')).toHaveLength(1)
+ expect(host.querySelector('.usage-popover__empty')).toBeNull()
+ })
+})
diff --git a/src/renderer/components/UsageIndicator.tsx b/src/renderer/components/UsageIndicator.tsx
index 7599233e9..68f816e70 100644
--- a/src/renderer/components/UsageIndicator.tsx
+++ b/src/renderer/components/UsageIndicator.tsx
@@ -132,7 +132,11 @@ function AccountUsageBlock({
{u?.limits.map((l) => (
<LimitRow key={limitKey(l)} limit={l} mode={mode} />
))}
- {u && u.limits.length === 0 && <div className="usage-popover__empty">No usage data.</div>}
+ {u && u.limits.length === 0 && (
+ <div className="usage-popover__empty">
+ {u.status === 'error' ? 'Could not read usage.' : 'No usage data.'}
+ </div>
+ )}
{!u && <div className="usage-popover__empty usage-pill__pulse">···</div>}
</div>
)
@@ -525,13 +529,19 @@ export function UsageIndicator({
<>
{/* Claude's rows are bare when it is the only provider; once others share the
panel they need a heading of their own to stay attributable. */}
- {enabled.length > 0 && limits.length > 0 && (
+ {enabled.length > 0 && (limits.length > 0 || isError) && (
<div className="usage-account__label">Claude</div>
)}
{limits.map((l) => (
<LimitRow key={limitKey(l)} limit={l} mode={percentMode} />
))}
- {!hasData && <div className="usage-popover__empty">No usage data.</div>}
+ {/* Another provider's data must not hide a failed Claude read. Keep any
+ last-known Claude bars instead of replacing them with the empty state. */}
+ {(!hasData || (isError && limits.length === 0)) && (
+ <div className="usage-popover__empty">
+ {isError ? 'Could not read usage.' : 'No usage data.'}
+ </div>
+ )}
{claudeUsage?.email && (
<div className="usage-account">
<div className="usage-account__label">Claude Account</div>