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): back off after a Codex usage 429 and keep the last good numbers (#1168) (#1227)

eneskircae4d1092ee869
diff --git a/CLAUDE.md b/CLAUDE.md
index 4d9a371d4..6de7f877d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5791,6 +5791,11 @@ bridges enter live state only via `appendBridgeEdges`) and the server
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.
+ **Local Codex reads (issue #1168)**: an HTTP 429 from the backend returns `rateLimited` and
+ starts a per-home cooldown (`Retry-After`, else 2 min doubling, 30 s–1 h); during it NEITHER
+ tier is asked — the app-server fallback reads the same account's limits, so falling through
+ after a 429 spent the budget twice. The service holds each account row's last good numbers
+ (`holdLastGoodProvider`). The SSH Codex reader has no cooldown yet.
- **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
diff --git a/src/core/usage/claude-usage-map.test.ts b/src/core/usage/claude-usage-map.test.ts
index d70c06e7f..a5172c8a0 100644
--- a/src/core/usage/claude-usage-map.test.ts
+++ b/src/core/usage/claude-usage-map.test.ts
@@ -3,10 +3,12 @@ import {
HOLD_LAST_GOOD_MAX_MS,
emptyUsage,
holdLastGood,
+ holdLastGoodProvider,
mapUsageLimits,
parseResetTimestamp,
usageFromPayload
} from './claude-usage-map'
+import type { ProviderUsage } from '../../shared/types'
import { findLimit, limitLabel, limitShortLabel } from '../../shared/usage-limits'
/**
@@ -229,3 +231,19 @@ describe('holdLastGood', () => {
}
})
})
+
+describe('holdLastGoodProvider (Codex rows, issue #1168)', () => {
+ const limit = { kind: 'session', group: 'session', usedPercent: 40, severity: null, resetsAt: null, windowMinutes: 300, scopeLabel: null, isActive: false }
+ const good: ProviderUsage = { provider: 'codex', accountId: 'a', account: 'a@x', limits: [limit], updatedAt: 1_000, status: 'ok' }
+ const limited: ProviderUsage = { provider: 'codex', accountId: 'a', account: 'a@x', limits: [], updatedAt: 2_000, status: 'error', rateLimited: true }
+
+ it('keeps the last good numbers through a rate-limited read, marked error + rateLimited', () => {
+ expect(holdLastGoodProvider(good, limited, 2_000)).toEqual({ ...good, status: 'error', rateLimited: true })
+ })
+
+ it('never holds another account\'s numbers, nor across a sign-out', () => {
+ expect(holdLastGoodProvider(good, { ...limited, accountId: 'b' }, 2_000)).toEqual({ ...limited, accountId: 'b' })
+ const out: ProviderUsage = { ...limited, status: 'unavailable', rateLimited: undefined }
+ expect(holdLastGoodProvider(good, out, 2_000)).toBe(out)
+ })
+})
diff --git a/src/core/usage/claude-usage-map.ts b/src/core/usage/claude-usage-map.ts
index 2e39dfe93..ac1627116 100644
--- a/src/core/usage/claude-usage-map.ts
+++ b/src/core/usage/claude-usage-map.ts
@@ -10,7 +10,7 @@
// contract: when the next model ships, its limit arrives as another array entry and this file
// does not change. Binding a `fableWeekly` slot (or a `seven_day_fable` field) would recreate
// the exact rigidity Anthropic just moved away from.
-import type { ClaudeUsage, ClaudeUsageWindow, UsageLimit } from '../../shared/types'
+import type { ClaudeUsage, ClaudeUsageWindow, ProviderUsage, UsageLimit } from '../../shared/types'
import { findLimit } from '../../shared/usage-limits'
/** `percent`/`utilization` are portions USED, 0–100. Clamp — the server is not our validator. */
@@ -172,3 +172,25 @@ export function holdLastGood(
const { rateLimited: _previousFailure, ...numbers } = prev
return { ...numbers, status: 'error', ...(next.rateLimited ? { rateLimited: true } : {}) }
}
+
+/**
+ * `holdLastGood` for a non-Claude provider row (Codex, issue #1168): a failed read with no numbers
+ * keeps the previous good numbers of the SAME provider and account, marked `error` (and
+ * `rateLimited` when that is why), under the same age and reset bounds. Anything else passes
+ * through unchanged.
+ */
+export function holdLastGoodProvider(
+ prev: ProviderUsage | undefined,
+ next: ProviderUsage,
+ now: number
+): ProviderUsage {
+ if (next.status !== 'error' || next.limits.length > 0) return next
+ if (!prev || prev.limits.length === 0) return next
+ if (prev.status !== 'ok' && prev.status !== 'error') return next
+ if (prev.provider !== next.provider || prev.accountId !== next.accountId) return next
+ if (next.account && prev.account && next.account !== prev.account) return next
+ if (now - prev.updatedAt > HOLD_LAST_GOOD_MAX_MS) return next
+ if (prev.limits.some((l) => l.resetsAt !== null && l.resetsAt <= now)) return next
+ const { rateLimited: _previousFailure, ...numbers } = prev
+ return { ...numbers, status: 'error', ...(next.rateLimited ? { rateLimited: true } : {}) }
+}
diff --git a/src/core/usage/codex-usage.rate-limit.test.ts b/src/core/usage/codex-usage.rate-limit.test.ts
new file mode 100644
index 000000000..a8e2de88c
--- /dev/null
+++ b/src/core/usage/codex-usage.rate-limit.test.ts
@@ -0,0 +1,141 @@
+// Issue #1168: a Codex usage read the backend refuses with HTTP 429 is named, starts a cooldown
+// (Retry-After when sent, else a doubling default), and is NOT followed by the app-server
+// fallback — which reads the same account's limits and so spends the same budget.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import fs from 'fs'
+import path from 'path'
+import { testTmpDir } from '../test-tmp'
+
+const { findInLoginPath } = vi.hoisted(() => ({ findInLoginPath: vi.fn(async () => null) }))
+vi.mock('../exec-path', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('../exec-path')>()),
+ findInLoginPath
+}))
+
+import {
+ CODEX_RATE_LIMIT_DEFAULT_MS,
+ CODEX_RATE_LIMIT_MAX_MS,
+ CODEX_RATE_LIMIT_MIN_MS,
+ codexRateLimitCooldownMs,
+ fetchCodexUsage,
+ parseRetryAfter,
+ resetCodexUsageCooldownsForTests
+} from './codex-usage'
+
+const OK_BODY = {
+ plan_type: 'pro',
+ rate_limit: { primary_window: { used_percent: 10, limit_window_seconds: 18_000, reset_at: 4_102_444_800 } }
+}
+
+function home(): string {
+ const dir = testTmpDir('codex-429-')
+ fs.writeFileSync(path.join(dir, 'auth.json'), JSON.stringify({ tokens: { access_token: 't' } }))
+ return dir
+}
+
+function respond(status: number, headers: Record<string, string> = {}, body: unknown = OK_BODY) {
+ return {
+ ok: status >= 200 && status < 300,
+ status,
+ headers: new Headers(headers),
+ json: async () => body
+ }
+}
+
+beforeEach(() => {
+ resetCodexUsageCooldownsForTests()
+ findInLoginPath.mockClear()
+ vi.useFakeTimers({ toFake: ['Date'] })
+ vi.setSystemTime(new Date('2026-10-16T12:00:00Z'))
+})
+afterEach(() => {
+ vi.useRealTimers()
+ vi.unstubAllGlobals()
+})
+
+describe('parseRetryAfter / codexRateLimitCooldownMs', () => {
+ it('reads delta-seconds and HTTP-dates, null otherwise', () => {
+ const now = Date.parse('2026-10-16T12:00:00Z')
+ expect(parseRetryAfter('120', now)).toBe(120_000)
+ expect(parseRetryAfter('Fri, 16 Oct 2026 12:05:00 GMT', now)).toBe(300_000)
+ expect(parseRetryAfter(null, now)).toBeNull()
+ expect(parseRetryAfter('soon', now)).toBeNull()
+ })
+
+ it('clamps the header and doubles the default per consecutive 429', () => {
+ expect(codexRateLimitCooldownMs(1000, 0)).toBe(CODEX_RATE_LIMIT_MIN_MS)
+ expect(codexRateLimitCooldownMs(10 * 60 * 60_000, 0)).toBe(CODEX_RATE_LIMIT_MAX_MS)
+ expect(codexRateLimitCooldownMs(null, 0)).toBe(CODEX_RATE_LIMIT_DEFAULT_MS)
+ expect(codexRateLimitCooldownMs(null, 1)).toBe(2 * CODEX_RATE_LIMIT_DEFAULT_MS)
+ expect(codexRateLimitCooldownMs(null, 40)).toBe(CODEX_RATE_LIMIT_MAX_MS)
+ })
+})
+
+describe('fetchCodexUsage after HTTP 429', () => {
+ it('names the 429 and does not fall through to the app-server tier', async () => {
+ const fetch = vi.fn(async () => respond(429, { 'retry-after': '120' }))
+ vi.stubGlobal('fetch', fetch)
+ const row = await fetchCodexUsage(home(), { id: 'acc-1', email: '[email protected]' })
+ expect(row).toMatchObject({ provider: 'codex', status: 'error', rateLimited: true, limits: [] })
+ expect(row.accountId).toBe('acc-1')
+ expect(fetch).toHaveBeenCalledTimes(1)
+ expect(findInLoginPath).not.toHaveBeenCalled()
+ })
+
+ it('sends nothing while the Retry-After cooldown runs, then reads again', async () => {
+ const fetch = vi.fn(async () => respond(429, { 'retry-after': '120' }))
+ vi.stubGlobal('fetch', fetch)
+ const dir = home()
+ await fetchCodexUsage(dir)
+ vi.setSystemTime(Date.now() + 119_000)
+ const cooling = await fetchCodexUsage(dir)
+ expect(cooling).toMatchObject({ status: 'error', rateLimited: true })
+ expect(fetch).toHaveBeenCalledTimes(1)
+ expect(findInLoginPath).not.toHaveBeenCalled()
+
+ fetch.mockImplementation(async () => respond(200))
+ vi.setSystemTime(Date.now() + 2_000)
+ const after = await fetchCodexUsage(dir)
+ expect(after.status).toBe('ok')
+ expect(after.rateLimited).toBeUndefined()
+ expect(fetch).toHaveBeenCalledTimes(2)
+ })
+
+ it('without Retry-After the wait doubles on a second 429 and a success clears it', async () => {
+ const fetch = vi.fn(async () => respond(429))
+ vi.stubGlobal('fetch', fetch)
+ const dir = home()
+ await fetchCodexUsage(dir)
+ vi.setSystemTime(Date.now() + CODEX_RATE_LIMIT_DEFAULT_MS + 1)
+ await fetchCodexUsage(dir)
+ expect(fetch).toHaveBeenCalledTimes(2)
+ // Second strike: twice the default, so one default later it is still cooling.
+ vi.setSystemTime(Date.now() + CODEX_RATE_LIMIT_DEFAULT_MS + 1)
+ await fetchCodexUsage(dir)
+ expect(fetch).toHaveBeenCalledTimes(2)
+ vi.setSystemTime(Date.now() + CODEX_RATE_LIMIT_DEFAULT_MS)
+ fetch.mockImplementation(async () => respond(200))
+ expect((await fetchCodexUsage(dir)).status).toBe('ok')
+ // Cleared: the next 429 waits the default again, not four times it.
+ fetch.mockImplementation(async () => respond(429))
+ await fetchCodexUsage(dir)
+ vi.setSystemTime(Date.now() + CODEX_RATE_LIMIT_DEFAULT_MS + 1)
+ await fetchCodexUsage(dir)
+ expect(fetch).toHaveBeenCalledTimes(5)
+ })
+
+ it('a cooldown belongs to one home: another account is still read', async () => {
+ const fetch = vi.fn(async () => respond(429))
+ vi.stubGlobal('fetch', fetch)
+ await fetchCodexUsage(home())
+ fetch.mockImplementation(async () => respond(200))
+ expect((await fetchCodexUsage(home())).status).toBe('ok')
+ })
+
+ it('a non-429 failure still falls back to the app-server tier', async () => {
+ vi.stubGlobal('fetch', vi.fn(async () => respond(500)))
+ const row = await fetchCodexUsage(home())
+ expect(findInLoginPath).toHaveBeenCalled()
+ expect(row.rateLimited).toBeUndefined()
+ })
+})
diff --git a/src/core/usage/codex-usage.ts b/src/core/usage/codex-usage.ts
index fe67b43a4..710357a53 100644
--- a/src/core/usage/codex-usage.ts
+++ b/src/core/usage/codex-usage.ts
@@ -22,6 +22,38 @@ export const CODEX_BACKEND_USAGE_URL = 'https://chatgpt.com/backend-api/wham/usa
const FETCH_TIMEOUT_MS = 8000
const APP_SERVER_TIMEOUT_MS = 10_000
+/**
+ * After the backend answers HTTP 429 (issue #1168) this home is left alone for a while: no backend
+ * request AND no app-server fallback, which reads the same account's limits and so spends the same
+ * budget. `Retry-After` wins when the backend sends one (clamped); otherwise the wait starts at
+ * the default and doubles on each consecutive 429. A successful read clears it.
+ */
+export const CODEX_RATE_LIMIT_MIN_MS = 30_000
+export const CODEX_RATE_LIMIT_DEFAULT_MS = 2 * 60_000
+export const CODEX_RATE_LIMIT_MAX_MS = 60 * 60_000
+const cooldowns = new Map<string, { until: number; strikes: number }>()
+
+/** Test seam: forget every cooldown. */
+export function resetCodexUsageCooldownsForTests(): void {
+ cooldowns.clear()
+}
+
+/** `Retry-After` as a delay in ms — delta-seconds or an HTTP-date; null when absent/unreadable. */
+export function parseRetryAfter(value: string | null | undefined, now: number): number | null {
+ const v = value?.trim()
+ if (!v) return null
+ if (/^\d+$/.test(v)) return Number(v) * 1000
+ const at = Date.parse(v)
+ return Number.isFinite(at) ? Math.max(0, at - now) : null
+}
+
+/** The wait after a 429, given the header and how many 429s in a row came before this one. */
+export function codexRateLimitCooldownMs(retryAfterMs: number | null, priorStrikes: number): number {
+ const base =
+ retryAfterMs ?? CODEX_RATE_LIMIT_DEFAULT_MS * 2 ** Math.min(Math.max(priorStrikes, 0), 10)
+ return Math.min(CODEX_RATE_LIMIT_MAX_MS, Math.max(CODEX_RATE_LIMIT_MIN_MS, base))
+}
+
/** Fallback bucket durations, used only when the backend omits `limit_window_seconds`. */
const PRIMARY_WINDOW_MINUTES = 300 // 5h
const SECONDARY_WINDOW_MINUTES = 10_080 // 7d
@@ -116,8 +148,8 @@ function snapshot(
return { provider: 'codex', limits, account, accountId, updatedAt: Date.now(), status }
}
-/** Tier 1: the endpoint the Codex CLI itself reads. */
-async function fetchViaBackend(home: string): Promise<ProviderUsage | null> {
+/** Tier 1: the endpoint the Codex CLI itself reads. `'rate-limited'` = it answered HTTP 429. */
+async function fetchViaBackend(home: string): Promise<ProviderUsage | 'rate-limited' | null> {
const { accessToken, accountId } = await readCodexAuth(home)
if (!accessToken) return null
@@ -135,6 +167,13 @@ async function fetchViaBackend(home: string): Promise<ProviderUsage | null> {
const res = await fetch(CODEX_BACKEND_USAGE_URL, { signal: ctrl.signal, headers }).finally(() =>
clearTimeout(t)
)
+ if (res.status === 429) {
+ const now = Date.now()
+ const strikes = cooldowns.get(home)?.strikes ?? 0
+ const wait = codexRateLimitCooldownMs(parseRetryAfter(res.headers?.get?.('retry-after'), now), strikes)
+ cooldowns.set(home, { until: now + wait, strikes: strikes + 1 })
+ return 'rate-limited'
+ }
if (!res.ok) return null
const payload = (await res.json()) as Record<string, any>
@@ -143,6 +182,7 @@ async function fetchViaBackend(home: string): Promise<ProviderUsage | null> {
// the app-server tier still gets its turn instead of reporting a confidently empty snapshot.
if (typeof payload.plan_type !== 'string') return null
+ cooldowns.delete(home)
return snapshot(mapCodexLimits(payload.rate_limit), 'ok')
}
@@ -276,8 +316,15 @@ export async function fetchCodexUsage(
): Promise<ProviderUsage> {
const account = identity?.email || identity?.label || null
const accountId = identity?.id
+ // Rate limited (issue #1168): named, and neither tier is asked again until the cooldown ends —
+ // the app-server reads the same account's limits, so falling through would spend the same
+ // budget twice. The service keeps the last good numbers on screen meanwhile (holdLastGoodProvider).
+ const rateLimited = (): ProviderUsage => ({ ...snapshot([], 'error', account, accountId), rateLimited: true })
+ const cooling = cooldowns.get(home)
+ if (cooling && Date.now() < cooling.until) return rateLimited()
try {
const viaBackend = await fetchViaBackend(home)
+ if (viaBackend === 'rate-limited') return rateLimited()
if (viaBackend) return { ...viaBackend, account, accountId }
} catch {
// fall through to the app-server tier
diff --git a/src/core/usage/usage-service.codex-accounts.test.ts b/src/core/usage/usage-service.codex-accounts.test.ts
index 9d3377773..41d62587a 100644
--- a/src/core/usage/usage-service.codex-accounts.test.ts
+++ b/src/core/usage/usage-service.codex-accounts.test.ts
@@ -170,3 +170,23 @@ describe('Codex multi-account usage', () => {
expect(rows.filter((r) => r.accountId === undefined)).toHaveLength(1)
})
})
+
+describe('a rate-limited Codex read keeps the last good numbers (issue #1168)', () => {
+ it('holds each account row through a 429, marked error + rateLimited', async () => {
+ const limit = {
+ kind: 'session', group: 'session', usedPercent: 40, severity: null,
+ resetsAt: null, windowMinutes: 300, scopeLabel: null, isActive: false
+ }
+ service = startUsageService({ shouldPoll: () => false })
+ fetchCodexUsage.mockImplementationOnce(async () => ({
+ provider: 'codex', account: null, limits: [limit], updatedAt: Date.now(), status: 'ok'
+ }))
+ await platform.handlers[IPC.usageProviders](true)
+ fetchCodexUsage.mockImplementationOnce(async () => ({
+ provider: 'codex', account: null, limits: [], updatedAt: Date.now(), status: 'error', rateLimited: true
+ }))
+ const rows = codexRows((await platform.handlers[IPC.usageProviders](true)) as ProviderUsage[])
+ expect(rows).toHaveLength(1)
+ expect(rows[0]).toMatchObject({ status: 'error', rateLimited: true, limits: [limit] })
+ })
+})
diff --git a/src/core/usage/usage-service.ts b/src/core/usage/usage-service.ts
index 0f84ff3bf..d2eade358 100644
--- a/src/core/usage/usage-service.ts
+++ b/src/core/usage/usage-service.ts
@@ -17,7 +17,7 @@ import type {
RemoteAccountUsage,
RemoteUsageQuery
} from '../../shared/types'
-import { emptyUsage, holdLastGood, usageFromPayload } from './claude-usage-map'
+import { emptyUsage, holdLastGood, holdLastGoodProvider, usageFromPayload } from './claude-usage-map'
import {
fetchRemoteUsage,
type RemoteUsageRunner,
@@ -350,6 +350,8 @@ export function startUsageService(opts: UsageServiceOptions = {}): UsageService
// or relabelled) the cache is busted so a snapshot from a DIFFERENT account set is never served —
// switching accounts can't show stale numbers (S6 §4.3, cache fingerprint).
let codexAccountsFingerprint = ''
+ // The last Codex row with numbers, per account (`accountId ?? ''`) — what a failed read holds.
+ const lastGoodCodex = new Map<string, ProviderUsage>()
// A throwing provider must never break the sweep — fail closed to the empty set (system-only),
// never a fabricated account (S6 §4.3).
@@ -409,8 +411,19 @@ export function startUsageService(opts: UsageServiceOptions = {}): UsageService
)
)
try {
- providersCache = await providersInFlight
- providersAt = Date.now()
+ const fresh = await providersInFlight
+ // A failed Codex read (a 429 above all, issue #1168) keeps that row's last good numbers
+ // instead of blanking it — keyed per account, so a held row is only ever its own account's.
+ const now = Date.now()
+ providersCache = fresh.map((row) => {
+ if (row.provider !== 'codex') return row
+ const key = row.accountId ?? ''
+ const held = holdLastGoodProvider(lastGoodCodex.get(key), row, now)
+ if (held.limits.length > 0) lastGoodCodex.set(key, held)
+ else lastGoodCodex.delete(key)
+ return held
+ })
+ providersAt = now
return providersCache
} finally {
providersInFlight = null
diff --git a/src/renderer/components/UsageIndicator.grok.test.tsx b/src/renderer/components/UsageIndicator.grok.test.tsx
index 17841e62d..2ac2b95b9 100644
--- a/src/renderer/components/UsageIndicator.grok.test.tsx
+++ b/src/renderer/components/UsageIndicator.grok.test.tsx
@@ -108,3 +108,17 @@ describe('Grok billing diagnostics in the usage popover', () => {
expect(host.querySelector('.usage-account')?.textContent).toContain('Could not read usage.')
})
})
+
+describe('a rate-limited Codex read in the usage popover (issue #1168)', () => {
+ it('names the 429 when there are no numbers to keep', async () => {
+ await open(snapshot('unavailable'), [{ provider: 'codex', account: null,
+ status: 'error', limits: [], updatedAt: 0, rateLimited: true }])
+ expect(host.querySelector('.usage-account')?.textContent).toContain('Rate limited by the usage endpoint (HTTP 429)')
+ })
+ it('keeps the held bars and says why they are old', async () => {
+ await open(snapshot('unavailable'), [{ provider: 'codex', account: null,
+ status: 'error', limits: [limit], updatedAt: Date.now() - 10 * 60_000, rateLimited: true }])
+ expect(host.querySelectorAll('.usage-account .usage-row')).toHaveLength(1)
+ expect(host.querySelector('.usage-account')?.textContent).toContain('Latest read was rate limited (HTTP 429)')
+ })
+})
diff --git a/src/renderer/components/UsageIndicator.tsx b/src/renderer/components/UsageIndicator.tsx
index eef1326a7..ef019c41b 100644
--- a/src/renderer/components/UsageIndicator.tsx
+++ b/src/renderer/components/UsageIndicator.tsx
@@ -113,7 +113,7 @@ function DefaultAccountMark({
}
/** Why the bars above are old — only for numbers kept through a failed read. */
-function HeldNote({ u }: { u: ClaudeUsage | null | undefined }) {
+function HeldNote({ u }: { u: ClaudeUsage | ProviderUsage | null | undefined }) {
const text = u ? heldUsageText(u) : null
return text ? <div className="usage-popover__held">{text}</div> : null
}
@@ -325,6 +325,8 @@ function ProviderBlock({ u, mode, hostKey }: { u: ProviderUsage; mode: 'used' |
{u.limits.map((l) => (
<LimitRow key={limitKey(l)} limit={l} mode={mode} />
))}
+ {/* Numbers the service kept because the latest read failed (a Codex 429, issue #1168). */}
+ <HeldNote u={u} />
{/* One line per distinct reason (issue #912): two views failing the same way are one
failure of this provider, not two paragraphs of the same sentence. */}
{usageDiagnosticLines(label, u.diagnostics).map((line) => (
@@ -334,7 +336,7 @@ function ProviderBlock({ u, mode, hostKey }: { u: ProviderUsage; mode: 'used' |
))}
{u.limits.length === 0 && !u.diagnostics?.length && (
<div className="usage-popover__empty">
- {u.status === 'error' ? 'Could not read usage.' : 'No usage data.'}
+ {u.status === 'error' ? usageFailureText(u) : 'No usage data.'}
</div>
)}
</div>
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 28a9b2612..c3b310be8 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -3076,9 +3076,14 @@ export interface ProviderUsage {
updatedAt: number
/**
* 'unavailable' = not signed in / no subscription to report → hide this provider entirely.
- * 'fetching' = request in flight. 'ok' = limits present. 'error' = the fetch failed.
+ * 'fetching' = request in flight. 'ok' = limits present. 'error' = the fetch failed — and when
+ * `limits` is non-empty alongside it, those are the LAST GOOD numbers the service kept
+ * (`holdLastGoodProvider`), still stamped with their own `updatedAt`.
*/
status: 'unavailable' | 'fetching' | 'ok' | 'error'
+ /** The latest read was refused with HTTP 429 (Codex today, issue #1168). Absent = not rate
+ * limited, or not known to be. */
+ rateLimited?: boolean
}
/** Host memory snapshot in MB. `null` from any reader means "could not read" — never "zero".