@hank-warren/pi-statusline 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @hank-warren/pi-statusline
 
+## 0.7.2
+
+### Patch Changes
+
+- 7f2143a: Make the subscription usage meters accurate as well as prompt. Three changes to how the poller treats each endpoint and its own cache, following the ten-second tick shipped in 0.7.1.
+
+  **Codex gets its own sixty-second interval.** Both endpoints shared one five-minute spacing, written for the stricter of the two. OpenAI's own Codex CLI polls its usage endpoint every sixty seconds and independent tools converge on the same figure, so the Codex meter had been five times more conservative than the vendor's own client for no reason beyond sharing a constant. Anthropic's endpoint, which rate-limits far harder, keeps the five minutes it needs.
+
+  **A `Retry-After` is now honoured.** Any 429 previously got a flat fifteen-minute backoff, ignoring the header saying when to come back; a provider asking for sixty seconds now gets sixty seconds, and one asking for an hour is no longer cut short by our guess. Both forms are accepted, delta-seconds and HTTP-date. A value that is not in the future is discarded rather than clamped, because Anthropic's usage endpoint is widely reported to answer `retry-after: 0` while still refusing requests — obeying it literally would retry straight back into the limit that produced it. The flat window remains the fallback for a 429 that says nothing.
+
+  **Cached values expire at their window boundary, not just by age.** Each cache entry now records the soonest moment any of its windows rolls over, from Anthropic's `resets_at` or Codex's `reset_at`/`reset_after_seconds`. Once that moment passes the stored percentages describe the window that just _ended_ — not merely stale but wrong, and invisible to any age-based expiry. Such a value is no longer adopted from the shared cache or kept as a last-known-good, and its account skips the poll interval so the post-reset numbers appear promptly. A boundary is answered exactly once rather than on every tick: a failed poll leaves the boundary in the past, so an unconditional override would re-poll continuously for as long as the failure lasted — a 429 sets a backoff that stops that, but a 500 or a timeout does not. An active rate-limit backoff still outranks a boundary, and a value carrying no boundary — which is what an entry written by an earlier statusline looks like — never expires this way.
+
+  The cache file stays compatible in both directions: the reset boundary is an additive field that older readers ignore, and an entry without one behaves exactly as before.
+
+## 0.7.1
+
+### Patch Changes
+
+- 950c926: Tick the subscription usage meters on a clock instead of on turn boundaries. The tracker only refreshed from session start, the end of a turn, and a model switch, while the poll gate that spaces requests is host-wide and five minutes wide. The moment a meter actually moved was therefore the first turn in this session ending more than five minutes after any pi process on the host last polled that account — which made updates look arbitrary, and froze an idle session's numbers indefinitely while the five-hour window was visibly recovering.
+
+  `UsageTracker` now owns an unref'd ten-second tick, started with the footer and stopped with the footer, with the usage setting, or at session shutdown. Request volume is unchanged, because a throttled refresh already issues no request: it reads `auth.json` and the shared cache, publishes whatever another process has already fetched, finds the gate closed and returns. The tick costs two small local reads and buys the two things the turn-driven cadence could not — an idle session's meters keep moving, and a sibling process's fresh values are adopted within one tick rather than waiting for this session's next turn to end. The poll itself now also fires when the five-minute window opens rather than at the first turn to end after it.
+
+  Nothing about the meters' appearance, the poll interval, the rate-limit backoff or the shared cache format changes.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -75,7 +75,7 @@ When Pi's `~/.pi/agent/auth.json` contains OAuth credentials for Anthropic (Clau
 
 Numbers are colored by remaining headroom: green above 60, yellow 41–60, orange 16–40, red at 15 and below.
 
-Usage is fetched from the providers' own usage endpoints with Pi's stored tokens — read-only; tokens are never refreshed or written. Fetches happen on session start and after each turn, throttled to at most once every five minutes (the Anthropic usage endpoint rate-limits aggressively), and are strictly best-effort: on any failure the last-known value is kept, and providers without credentials (or before the first successful fetch) are simply omitted, leaving the statusline exactly as before. While a provider that *does* have credentials still has no value, the throttle drops to 30 seconds — Pi only refreshes an expired OAuth access token when that provider is first used, so a session starting with a stale Anthropic token would otherwise show no Claude meter for a full interval.
+Usage is fetched from the providers' own usage endpoints with Pi's stored tokens — read-only; tokens are never refreshed or written. Fetches are driven by session start, each turn, and a ten-second tick while the footer is mounted, throttled per provider — five minutes for Claude, sixty seconds for Codex (the Anthropic usage endpoint rate-limits aggressively), and are strictly best-effort: on any failure the last-known value is kept, and providers without credentials (or before the first successful fetch) are simply omitted, leaving the statusline exactly as before. While a provider that *does* have credentials still has no value, the throttle drops to 30 seconds — Pi only refreshes an expired OAuth access token when that provider is first used, so a session starting with a stale Anthropic token would otherwise show no Claude meter for a full interval.
 
 ### Which account each meter shows
 
@@ -87,6 +87,14 @@ When [`@hank-warren/pi-multi-login`](../pi-multi-login/README.md) has registered
 
 Polling is host-wide, not per-session. Usage percentages describe the account rather than the session, and a busy machine runs dozens of pi processes, so every process shares `~/.pi/agent/statusline-usage.json`, written atomically via a temp file and rename. It is keyed by **credential id**, one entry per account, each holding that account's last good values plus the time its last poll was *started*. A session adopts the cached values for its selected accounts on first refresh — so the meters are populated before it has issued a single request, and switching back to an account polled earlier repaints with no request at all — and only polls an account whose timestamp is older than the interval. Keying by account rather than by provider family is what lets two sessions on two different Anthropic logins coexist: keyed by family, each looked like an account switch to the other, so they evicted each other's values and re-polled every cycle.
 
+The two intervals differ because the endpoints do. OpenAI's own Codex CLI polls `wham/usage` every sixty seconds, and independent community tools converge on the same figure, so matching the first-party client is well inside what that endpoint expects. Anthropic's usage endpoint is the opposite — it rate-limits hard enough that a whole ecosystem of statusline tools has been stuck in permanent 429 loops — so Claude keeps the conservative five minutes. The two had shared one interval only because it was written for the stricter of them, leaving the Codex meter five times more conservative than the vendor's own client for no reason.
+
+The ten-second tick does not increase request volume; it only stops the meters from being pinned to turn boundaries. A throttled refresh issues no request at all — it reads `auth.json` and the shared cache, publishes whatever another process has already fetched, finds the poll gate closed and returns — so the tick costs two small local reads and buys the two things the previous turn-driven cadence could not: an **idle** session's meters keep moving (quota recovers on a wall clock, not on your turns), and a sibling process's fresh values are adopted within one tick instead of waiting for this session's next turn to end. It also means the poll itself happens when the five-minute window opens rather than at the first turn that ends after it. The tick is `unref`ed, runs only in TUI mode, and stops with the footer — so turning the usage segment off still stops all polling.
+
+A provider answering **429** is left alone before being polled again. When the response carries a usable `Retry-After` — either form, delta-seconds or an HTTP-date — that instruction is authoritative and is used exactly. Otherwise a flat fifteen-minute window applies, because a 429 that says nothing about when to return is only telling us the endpoint wants a break. A `Retry-After` that is not in the future is discarded rather than clamped: Anthropic's usage endpoint is widely reported to answer `retry-after: 0` while still refusing requests, so obeying it literally would retry straight back into the limit that produced it. Any successful poll clears the block.
+
+Cached values also expire at a **window boundary**, not just by age. Each entry records the soonest moment any of its windows rolls over — from Anthropic's `resets_at`, or Codex's `reset_at` (absolute, preferred) or `reset_after_seconds` (relative, resolved against our clock). Once that moment passes, the stored percentages describe the window that just *ended*: they are not merely old, they are wrong, and no age-based expiry can see it. Such a value is never adopted from the cache and never kept as a last-known-good, and the account becomes pollable immediately rather than waiting out its interval, so the post-reset numbers appear promptly. An active 429 backoff still outranks a boundary — a rate-limited endpoint is the last thing to argue with the moment its window turns over. A value carrying no boundary at all, which is what an entry written by an older statusline looks like, never expires this way.
+
 Cache entries stay compatible in both directions: a Codex entry written by a statusline older than 0.6.0 carries no 5-hour value, so a newer one renders it as a single weekly number until its own next poll fills the second slot, and an older reader ignores the extra value entirely.
 
 An account answering `429` is parked for fifteen minutes (tracked per account, so a rate-limited Anthropic never stops codex from updating) and stops counting as pending, since retrying harder is what earns the rate limit in the first place. Every cache entry is keyed to a fingerprint (a sha256 prefix, never the token itself) of the credential that fetched it: switching accounts — or rotating a token — discards that entry's numbers and backoff and polls immediately, so an exhausted old account's meters never masquerade as the new account's. A logged-out account fails the same check, so the file garbage-collects itself.

package/index.ts

@@ -304,7 +304,13 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 		} else if (!previous.showWorktrees || !tracker || previous.worktreeRoot !== next.worktreeRoot) {
 			resetTracker(ctx);
 		}
-		if (next.showUsage && !previous.showUsage) runInBackground(usageTracker.refresh());
+		if (next.showUsage && !previous.showUsage) {
+			runInBackground(usageTracker.refresh());
+			usageTracker.start();
+		} else if (!next.showUsage && previous.showUsage) {
+			// A hidden meter must not keep polling, matching the worktree line above.
+			usageTracker.stop();
+		}
 		if (!next.showCacheCelebration) cacheCelebration.dispose();
 		// Dropping a row leaves a stale one behind in fullscreen mode.
 		if (previous.showSessionId !== next.showSessionId || previous.showWorktrees !== next.showWorktrees) {
@@ -406,6 +412,10 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 			// Fullscreen mode never repaints unchanged rows; the session id line is
 			// static, so it needs periodic forced redraws to shed stale cells.
 			fullRedraw.attach(tui);
+			// The meters are wall-clock quantities, not per-turn ones: an idle session
+			// still needs them to move, and a sibling process's poll is worth adopting
+			// before the next turn ends.
+			if (settings.showUsage) usageTracker.start();
 			const stopBranchUpdates = footerData.onBranchChange(() => {
 				runInBackground(refreshCwdStatus(ctx));
 				tui.requestRender();
@@ -417,6 +427,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 					cacheCelebration.dispose();
 					celebrationPreview.dispose();
 					fullRedraw.detach();
+					usageTracker.stop();
 					requestRender = undefined;
 				},
 				invalidate(): void {},
@@ -479,6 +490,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 	pi.on("session_shutdown", () => {
 		cacheCelebration.dispose();
 		fullRedraw.detach();
+		usageTracker.stop();
 		tracker?.dispose();
 		tracker = undefined;
 		cwdStatusAbort?.abort();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-statusline",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Compact Pi footer statusline with Git/worktree context, token usage, and neon celebrations for exceptional prompt-cache hits.",
   "type": "module",
   "keywords": [

package/usage.ts

@@ -4,7 +4,15 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { pid } from "node:process";
 
-/** Remaining (not used) integer percents per provider window. */
+/**
+ * Remaining (not used) integer percents per provider window.
+ *
+ * `resetsAt` is the soonest moment any of that provider's windows rolls over,
+ * as epoch milliseconds. It is what makes a cached value falsifiable: once that
+ * boundary passes, the percentages describe the *previous* window and are not
+ * merely old but wrong. Absent when the payload carried no usable reset time,
+ * which is also what an entry written by an older statusline looks like.
+ */
 export interface UsageSnapshot {
 	claude?: { fiveHour: number; sevenDay: number; scopedWeekly?: number };
 	/**
@@ -15,6 +23,27 @@ export interface UsageSnapshot {
 	codex?: { fiveHour?: number; weekly?: number };
 }
 
+/**
+ * Whether a reset boundary has passed. A missing boundary never expires, which
+ * is what an entry written by an older statusline looks like.
+ */
+function hasReset(resetsAt: number | undefined, now: number): boolean {
+	return resetsAt !== undefined && now >= resetsAt;
+}
+
+/** The soonest of a set of candidate reset times, ignoring unusable ones. */
+function earliestReset(candidates: (number | undefined)[]): number | undefined {
+	const usable = candidates.filter((value): value is number => value !== undefined && Number.isFinite(value));
+	return usable.length === 0 ? undefined : Math.min(...usable);
+}
+
+/** Anthropic reports reset times as an ISO 8601 string. */
+function parseIsoReset(value: unknown): number | undefined {
+	if (typeof value !== "string") return undefined;
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
 const CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
 const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
 /**
@@ -22,6 +51,15 @@ const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
  * (429) aggressively, so keep this well above a per-turn cadence.
  */
 export const USAGE_REFRESH_INTERVAL_MS = 5 * 60_000;
+/**
+ * Minimum spacing for the Codex endpoint, which is markedly more permissive
+ * than Anthropic's. OpenAI's own Codex CLI polls this exact endpoint on a
+ * 60-second interval (`ChatWidget::prefetch_rate_limits`), and independent
+ * community tools converge on the same figure, so matching the first-party
+ * client is well inside what the endpoint expects. The two providers had
+ * shared one interval purely because it was written for the stricter of them.
+ */
+export const CODEX_USAGE_REFRESH_INTERVAL_MS = 60_000;
 /**
  * Shorter spacing used while a credentialed provider still has no value. Pi
  * refreshes an expired OAuth token only when that provider is first used, so a
@@ -30,11 +68,23 @@ export const USAGE_REFRESH_INTERVAL_MS = 5 * 60_000;
  */
 export const USAGE_RETRY_INTERVAL_MS = 30_000;
 /**
- * How long an account is left alone after it answers 429. Polls are host-wide
- * (see the shared cache below), so a rate limit means the provider itself wants
- * a break rather than that we are racing ourselves.
+ * How long an account is left alone after it answers 429 *without* telling us
+ * when to come back. Polls are host-wide (see the shared cache below), so a rate
+ * limit means the provider itself wants a break rather than that we are racing
+ * ourselves. A usable `Retry-After` always wins over this guess.
  */
 export const USAGE_RATE_LIMIT_BACKOFF_MS = 15 * 60_000;
+/**
+ * How often a bound tracker calls itself. This is deliberately far shorter than
+ * the poll interval, because a throttled `refresh()` issues no request at all:
+ * it reads auth.json and the shared cache, publishes whatever another process
+ * has already fetched, finds the poll gate closed, and returns. So the tick
+ * costs two small local reads and buys two things the previous turn-driven
+ * cadence could not — an idle session's meters keep moving, and a sibling
+ * process's fresh values appear within one tick instead of at the next turn.
+ * Request volume is unchanged: both throttles still gate every fetch.
+ */
+export const USAGE_TICK_INTERVAL_MS = 10_000;
 const FETCH_TIMEOUT_MS = 10_000;
 const ONE_DAY_SECONDS = 86_400;
 
@@ -57,8 +107,8 @@ interface ClaudeLimitEntry {
 export function parseClaudeUsage(json: unknown): UsageSnapshot["claude"] | undefined {
 	if (typeof json !== "object" || json === null) return undefined;
 	const body = json as {
-		five_hour?: { utilization?: unknown };
-		seven_day?: { utilization?: unknown };
+		five_hour?: { utilization?: unknown; resets_at?: unknown };
+		seven_day?: { utilization?: unknown; resets_at?: unknown };
 		limits?: unknown;
 	};
 	const fiveHour = toRemaining(body.five_hour?.utilization);
@@ -82,6 +132,18 @@ export function parseClaudeUsage(json: unknown): UsageSnapshot["claude"] | undef
 interface CodexWindow {
 	used_percent?: unknown;
 	limit_window_seconds?: unknown;
+	/** Absolute reset, Unix seconds. Preferred over the relative form. */
+	reset_at?: unknown;
+	/** Relative reset, seconds from the moment the payload was produced. */
+	reset_after_seconds?: unknown;
+}
+
+/** A Codex window's reset time as epoch ms, absolute form preferred. */
+function codexReset(window: CodexWindow | undefined, now: number): number | undefined {
+	if (window === undefined) return undefined;
+	if (typeof window.reset_at === "number" && Number.isFinite(window.reset_at)) return window.reset_at * 1_000;
+	const after = window.reset_after_seconds;
+	return typeof after === "number" && Number.isFinite(after) ? now + after * 1_000 : undefined;
 }
 
 /** A window whose span is known, so it can be sorted into a slot. */
@@ -98,9 +160,21 @@ interface SpannedCodexWindow extends CodexWindow {
  * and an absent window simply leaves its slot empty.
  */
 export function parseCodexUsage(json: unknown): UsageSnapshot["codex"] | undefined {
-	if (typeof json !== "object" || json === null) return undefined;
+	const { shortest, longest } = slotCodexWindows(json);
+	const fiveHour = toRemaining(shortest?.used_percent);
+	const weekly = toRemaining(longest?.used_percent);
+	if (fiveHour === undefined && weekly === undefined) return undefined;
+	const result: UsageSnapshot["codex"] = {};
+	if (fiveHour !== undefined) result.fiveHour = fiveHour;
+	if (weekly !== undefined) result.weekly = weekly;
+	return result;
+}
+
+/** Sort a Codex payload's windows into the short and long display slots. */
+function slotCodexWindows(json: unknown): { shortest?: SpannedCodexWindow; longest?: SpannedCodexWindow } {
+	if (typeof json !== "object" || json === null) return {};
 	const rateLimit = (json as { rate_limit?: unknown }).rate_limit;
-	if (typeof rateLimit !== "object" || rateLimit === null) return undefined;
+	if (typeof rateLimit !== "object" || rateLimit === null) return {};
 	const { primary_window, secondary_window } = rateLimit as {
 		primary_window?: CodexWindow | null;
 		secondary_window?: CodexWindow | null;
@@ -113,19 +187,35 @@ export function parseCodexUsage(json: unknown): UsageSnapshot["codex"] | undefin
 			typeof window.limit_window_seconds === "number" &&
 			Number.isFinite(window.limit_window_seconds),
 	);
-	const shortest = windows
-		.filter((window) => window.limit_window_seconds < ONE_DAY_SECONDS)
-		.sort((a, b) => a.limit_window_seconds - b.limit_window_seconds)[0];
-	const longest = windows
-		.filter((window) => window.limit_window_seconds >= ONE_DAY_SECONDS)
-		.sort((a, b) => b.limit_window_seconds - a.limit_window_seconds)[0];
-	const fiveHour = toRemaining(shortest?.used_percent);
-	const weekly = toRemaining(longest?.used_percent);
-	if (fiveHour === undefined && weekly === undefined) return undefined;
-	const result: UsageSnapshot["codex"] = {};
-	if (fiveHour !== undefined) result.fiveHour = fiveHour;
-	if (weekly !== undefined) result.weekly = weekly;
-	return result;
+	return {
+		shortest: windows
+			.filter((window) => window.limit_window_seconds < ONE_DAY_SECONDS)
+			.sort((a, b) => a.limit_window_seconds - b.limit_window_seconds)[0],
+		longest: windows
+			.filter((window) => window.limit_window_seconds >= ONE_DAY_SECONDS)
+			.sort((a, b) => b.limit_window_seconds - a.limit_window_seconds)[0],
+	};
+}
+
+/**
+ * The soonest moment any window in a Claude payload rolls over, epoch ms.
+ * Kept out of the parsed value on purpose: this is cache-lifetime metadata,
+ * never rendered, and folding it into the display shape would make every
+ * snapshot assertion carry a timestamp.
+ */
+export function claudeResetAt(json: unknown): number | undefined {
+	if (typeof json !== "object" || json === null) return undefined;
+	const body = json as { five_hour?: { resets_at?: unknown }; seven_day?: { resets_at?: unknown } };
+	return earliestReset([parseIsoReset(body.five_hour?.resets_at), parseIsoReset(body.seven_day?.resets_at)]);
+}
+
+/**
+ * The soonest moment any slotted Codex window rolls over, epoch ms. Needs the
+ * clock because Codex may report only a relative `reset_after_seconds`.
+ */
+export function codexResetAt(json: unknown, now: number): number | undefined {
+	const { shortest, longest } = slotCodexWindows(json);
+	return earliestReset([codexReset(shortest, now), codexReset(longest, now)]);
 }
 
 /** Color band for a remaining percent: >60 green, >40 yellow, >15 orange, else red. */
@@ -139,9 +229,31 @@ export function usageBand(remaining: number): "green" | "yellow" | "orange" | "r
 type FetchFn = (url: string, init: { headers: Record<string, string>; signal: AbortSignal }) => Promise<{
 	ok: boolean;
 	status?: number;
+	/** Optional so a caller (or a test double) may omit response headers. */
+	headers?: { get(name: string): string | null };
 	json(): Promise<unknown>;
 }>;
 
+/**
+ * Absolute time a `Retry-After` header points at, or undefined when it is
+ * absent, unparseable, or already in the past. Both forms in RFC 9110 are
+ * accepted: delta-seconds (`Retry-After: 120`) and an HTTP-date.
+ *
+ * A value that is not in the future is deliberately discarded rather than
+ * clamped to now. Anthropic's usage endpoint is documented by its users to
+ * answer `retry-after: 0` while continuing to refuse requests, so obeying it
+ * literally would retry straight into the limit that produced it.
+ */
+export function parseRetryAfter(value: string | null | undefined, now: number): number | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return undefined;
+	const seconds = Number(trimmed);
+	const at = Number.isFinite(seconds) ? now + seconds * 1_000 : Date.parse(trimmed);
+	if (!Number.isFinite(at) || at <= now) return undefined;
+	return at;
+}
+
 export interface UsageTrackerOptions {
 	authPath?: string;
 	cachePath?: string;
@@ -150,6 +262,20 @@ export interface UsageTrackerOptions {
 	now?: () => number;
 	/** Provider id of the session's main model; selects which account is polled. */
 	activeProvider?: string;
+	tickIntervalMs?: number;
+	schedule?: (callback: () => void, intervalMs: number) => unknown;
+	cancel?: (handle: unknown) => void;
+}
+
+function defaultSchedule(callback: () => void, intervalMs: number): unknown {
+	const timer = setInterval(callback, intervalMs);
+	// A usage meter is cosmetic; it must never hold the process open at exit.
+	(timer as { unref?: () => void }).unref?.();
+	return timer;
+}
+
+function defaultCancel(handle: unknown): void {
+	clearInterval(handle as ReturnType<typeof setInterval>);
 }
 
 type ProviderKey = "claude" | "codex";
@@ -162,9 +288,21 @@ export const USAGE_BASE_PROVIDERS: Record<ProviderKey, string> = {
 	codex: "openai-codex",
 };
 
+/** Steady-state poll spacing per family; each endpoint has its own tolerance. */
+const PROVIDER_REFRESH_INTERVAL_MS: Record<ProviderKey, number> = {
+	claude: USAGE_REFRESH_INTERVAL_MS,
+	codex: CODEX_USAGE_REFRESH_INTERVAL_MS,
+};
+
 /** Credential id polled for each family. */
 export type UsageAccounts = Record<ProviderKey, string>;
 
+/** A freshly fetched value together with the boundary it is valid until. */
+interface FetchedUsage<K extends ProviderKey> {
+	value: NonNullable<UsageSnapshot[K]>;
+	resetsAt?: number;
+}
+
 function inFamily(providerId: string | undefined, base: string): boolean {
 	return providerId === base || (providerId !== undefined && providerId.startsWith(`${base}-`));
 }
@@ -242,6 +380,12 @@ function credentialIdentities(auth: AuthEntries, accounts: UsageAccounts): Provi
 interface UsageAccountEntry {
 	/** Credential fingerprint the stored values were fetched with. */
 	identity: string;
+	/**
+	 * Epoch ms at which the soonest window in the stored value rolls over. Past
+	 * it the percentages describe the previous window, so they are wrong rather
+	 * than merely old. Absent on entries written before this existed.
+	 */
+	resetsAt?: number;
 	/** Last time any process started a poll for this account. */
 	attemptedAt: number;
 	/** Absolute time before which a rate-limited account must not be polled. */
@@ -298,6 +442,7 @@ function parseUsageCache(json: unknown): UsageCache | undefined {
 		if (typeof body.attemptedAt !== "number" || !Number.isFinite(body.attemptedAt)) continue;
 		const entry: UsageAccountEntry = { identity: body.identity, attemptedAt: body.attemptedAt };
 		if (typeof body.backoff === "number" && Number.isFinite(body.backoff)) entry.backoff = body.backoff;
+		if (typeof body.resetsAt === "number" && Number.isFinite(body.resetsAt)) entry.resetsAt = body.resetsAt;
 		if (typeof body.claude === "object" && body.claude !== null) entry.claude = body.claude as UsageSnapshot["claude"];
 		if (typeof body.codex === "object" && body.codex !== null) entry.codex = body.codex as UsageSnapshot["codex"];
 		accounts[accountId] = entry;
@@ -317,12 +462,19 @@ export class UsageTracker {
 	private readonly onChange?: () => void;
 	private readonly now: () => number;
 	private current: UsageSnapshot = {};
+	/** Reset boundary of each value in `current`, so it can expire in place. */
+	private currentResets: Partial<Record<ProviderKey, number>> = {};
 	private identities: ProviderIdentities = {};
 	private activeProvider: string | undefined;
 	private awaitingProvider = true;
-	private readonly rateLimited = new Set<ProviderKey>();
+	/** Families that answered 429 this cycle, mapped to their `Retry-After`. */
+	private readonly rateLimited = new Map<ProviderKey, number | undefined>();
 	private lastAttempt: Record<string, number> = {};
 	private inFlight: Promise<void> | undefined;
+	private readonly tickIntervalMs: number;
+	private readonly schedule: (callback: () => void, intervalMs: number) => unknown;
+	private readonly cancel: (handle: unknown) => void;
+	private tickHandle: unknown;
 
 	constructor(options: UsageTrackerOptions = {}) {
 		this.authPath = options.authPath ?? join(homedir(), ".pi", "agent", "auth.json");
@@ -331,12 +483,34 @@ export class UsageTracker {
 		this.onChange = options.onChange;
 		this.now = options.now ?? Date.now;
 		this.activeProvider = options.activeProvider;
+		this.tickIntervalMs = options.tickIntervalMs ?? USAGE_TICK_INTERVAL_MS;
+		this.schedule = options.schedule ?? defaultSchedule;
+		this.cancel = options.cancel ?? defaultCancel;
 	}
 
 	snapshot(): UsageSnapshot {
 		return this.current;
 	}
 
+	/**
+	 * Begin ticking. Idempotent, so the caller may start from whichever lifecycle
+	 * event happens first without tracking whether it already did.
+	 */
+	start(): void {
+		if (this.tickHandle !== undefined) return;
+		this.tickHandle = this.schedule(() => {
+			// refresh() swallows its own failures and no-ops while one is in flight.
+			void this.refresh();
+		}, this.tickIntervalMs);
+	}
+
+	/** Stop ticking. Safe to call when never started, and leaves values in place. */
+	stop(): void {
+		if (this.tickHandle === undefined) return;
+		this.cancel(this.tickHandle);
+		this.tickHandle = undefined;
+	}
+
 	/**
 	 * Point the meters at the session's main model. A switch between two accounts
 	 * in the same family changes which one is displayed; the next refresh adopts
@@ -347,11 +521,12 @@ export class UsageTracker {
 	}
 
 	/**
-	 * Interval until the next allowed attempt: the short retry window while a
-	 * credentialed provider is still missing a value, the full interval otherwise.
+	 * Interval until the next allowed attempt for one family: the short retry
+	 * window while a credentialed provider is still missing a value, that
+	 * family's own steady-state interval otherwise.
 	 */
-	private currentInterval(): number {
-		return this.awaitingProvider ? USAGE_RETRY_INTERVAL_MS : USAGE_REFRESH_INTERVAL_MS;
+	private currentInterval(key: ProviderKey): number {
+		return this.awaitingProvider ? USAGE_RETRY_INTERVAL_MS : PROVIDER_REFRESH_INTERVAL_MS[key];
 	}
 
 	/** Throttled refresh; resolves when the current attempt (if any) settles. */
@@ -381,21 +556,32 @@ export class UsageTracker {
 		// Another process's values are as good as ours and cost no request, so a new
 		// session — or a switch back to an account polled earlier — shows real
 		// numbers on its very first render.
-		this.publish(this.merge(cachedSnapshot(cache, accounts), auth, accounts), auth, accounts, cache);
-
 		const now = this.now();
-		const interval = this.currentInterval();
+		this.publish(this.merge(...cachedSnapshot(cache, accounts, now), auth, accounts, now), auth, accounts, cache);
+
 		const pollable: Partial<Record<ProviderKey, string>> = {};
 		for (const key of PROVIDER_KEYS) {
 			const accountId = accounts[key];
 			if (!hasAuth(auth, accountId)) continue;
 			const entry = cache.accounts[accountId];
+			// A backoff outranks everything: a rate-limited endpoint does not want to
+			// hear from us at a window boundary either.
 			if (now < (entry?.backoff ?? Number.NEGATIVE_INFINITY)) continue;
 			const lastAttempt = Math.max(
 				this.lastAttempt[accountId] ?? Number.NEGATIVE_INFINITY,
 				entry?.attemptedAt ?? Number.NEGATIVE_INFINITY,
 			);
-			if (now - lastAttempt < interval) continue;
+			// Past a window boundary the stored percentages are wrong rather than
+			// merely old, so the interval is skipped to republish promptly — but only
+			// for a boundary we have not already answered. A failed poll leaves the
+			// boundary in the past, so an unconditional override would poll on every
+			// tick for as long as the failure lasted. A 429 sets a backoff that stops
+			// that; a 500, a timeout or a dropped connection does not. Answering each
+			// boundary once hands the account back to the ordinary intervals, which
+			// for a provider now holding no value is the short retry window.
+			const boundary = entry?.resetsAt;
+			const boundaryUnanswered = hasReset(boundary, now) && (boundary as number) > lastAttempt;
+			if (!boundaryUnanswered && now - lastAttempt < this.currentInterval(key)) continue;
 			pollable[key] = accountId;
 		}
 		if (pollable.claude === undefined && pollable.codex === undefined) return;
@@ -416,10 +602,15 @@ export class UsageTracker {
 		}
 		await this.writeCache({ accounts: claimed });
 
-		const [claude, codex] = await Promise.all([
+		const [claudeResult, codexResult] = await Promise.all([
 			pollable.claude === undefined ? Promise.resolve(undefined) : this.fetchClaude(auth, pollable.claude),
 			pollable.codex === undefined ? Promise.resolve(undefined) : this.fetchCodex(auth, pollable.codex),
 		]);
+		const claude = claudeResult?.value;
+		const codex = codexResult?.value;
+		const incomingResets: Partial<Record<ProviderKey, number>> = {};
+		if (claudeResult?.resetsAt !== undefined) incomingResets.claude = claudeResult.resetsAt;
+		if (codexResult?.resetsAt !== undefined) incomingResets.codex = codexResult.resetsAt;
 
 		const updatedAccounts = { ...claimed };
 		for (const key of PROVIDER_KEYS) {
@@ -427,18 +618,33 @@ export class UsageTracker {
 			if (accountId === undefined) continue;
 			const entry: UsageAccountEntry = { ...(updatedAccounts[accountId] as UsageAccountEntry) };
 			const value = key === "claude" ? claude : codex;
-			if (this.rateLimited.has(key)) entry.backoff = now + USAGE_RATE_LIMIT_BACKOFF_MS;
+			// A `Retry-After` we could use is authoritative; the flat window is only a
+			// guess for a 429 that told us nothing. Deliberately a plain assignment:
+			// the poll gate above skips any account whose backoff is still in the
+			// future, so a value we are about to overwrite is necessarily absent or
+			// already expired, and a monotonic max() here would never do anything.
+			if (this.rateLimited.has(key)) {
+				entry.backoff = this.rateLimited.get(key) ?? now + USAGE_RATE_LIMIT_BACKOFF_MS;
+			}
 			else if (value !== undefined) delete entry.backoff;
 			// A failed fetch leaves the last-known value in place rather than blanking
 			// the meter for whatever caused one bad response.
 			if (claude !== undefined && key === "claude") entry.claude = claude;
 			if (codex !== undefined && key === "codex") entry.codex = codex;
+			// The boundary travels with the value it describes: a refreshed value gets
+			// the new window, and one that arrived without a usable reset must not
+			// inherit the previous window's.
+			if (value !== undefined) {
+				const resetsAt = incomingResets[key];
+				if (resetsAt === undefined) delete entry.resetsAt;
+				else entry.resetsAt = resetsAt;
+			}
 			updatedAccounts[accountId] = entry;
 		}
 		this.rateLimited.clear();
 
 		const updated: UsageCache = { accounts: updatedAccounts };
-		this.publish(this.merge({ claude, codex }, auth, accounts), auth, accounts, updated);
+		this.publish(this.merge({ claude, codex }, incomingResets, auth, accounts, now), auth, accounts, updated);
 		await this.writeCache(updated);
 	}
 
@@ -452,6 +658,7 @@ export class UsageTracker {
 		this.identities = identity;
 		if (changedKeys.length === 0) return;
 		for (const key of changedKeys) delete this.lastAttempt[accounts[key]];
+		for (const key of changedKeys) delete this.currentResets[key];
 		if (!changedKeys.some((key) => this.current[key] !== undefined)) return;
 		const next = { ...this.current };
 		for (const key of changedKeys) delete next[key];
@@ -465,21 +672,44 @@ export class UsageTracker {
 	 * account has no credentials: a logged-out account must disappear immediately,
 	 * while a failed fetch keeps whatever we last saw.
 	 */
-	private merge(incoming: UsageSnapshot, auth: AuthEntries, accounts: UsageAccounts): UsageSnapshot {
-		const next: UsageSnapshot = {};
-		if (hasAuth(auth, accounts.claude)) {
-			const claude = incoming.claude ?? this.current.claude;
-			if (claude) next.claude = claude;
-		}
-		if (hasAuth(auth, accounts.codex)) {
-			const codex = incoming.codex ?? this.current.codex;
-			if (codex) next.codex = codex;
+	private merge(
+		incoming: UsageSnapshot,
+		incomingResets: Partial<Record<ProviderKey, number>>,
+		auth: AuthEntries,
+		accounts: UsageAccounts,
+		now: number,
+	): { snapshot: UsageSnapshot; resets: Partial<Record<ProviderKey, number>> } {
+		const snapshot: UsageSnapshot = {};
+		const resets: Partial<Record<ProviderKey, number>> = {};
+		for (const key of PROVIDER_KEYS) {
+			if (!hasAuth(auth, accounts[key])) continue;
+			if (incoming[key] !== undefined) {
+				// biome-ignore lint/suspicious/noExplicitAny: one assignment, two value shapes.
+				snapshot[key] = incoming[key] as any;
+				if (incomingResets[key] !== undefined) resets[key] = incomingResets[key];
+				continue;
+			}
+			// A last-known-good value survives a failed fetch, but not the rollover of
+			// the window it describes.
+			if (this.current[key] === undefined || hasReset(this.currentResets[key], now)) continue;
+			// biome-ignore lint/suspicious/noExplicitAny: one assignment, two value shapes.
+			snapshot[key] = this.current[key] as any;
+			if (this.currentResets[key] !== undefined) resets[key] = this.currentResets[key];
 		}
-		return next;
+		return { snapshot, resets };
 	}
 
 	/** Adopt a snapshot, recompute the retry gate, and repaint only on a change. */
-	private publish(next: UsageSnapshot, auth: AuthEntries, accounts: UsageAccounts, cache: UsageCache): void {
+	private publish(
+		merged: { snapshot: UsageSnapshot; resets: Partial<Record<ProviderKey, number>> },
+		auth: AuthEntries,
+		accounts: UsageAccounts,
+		cache: UsageCache,
+	): void {
+		const next = merged.snapshot;
+		// Boundaries follow their values even when the percentages are unchanged, so
+		// a refreshed window cannot be judged against the previous one's deadline.
+		this.currentResets = merged.resets;
 		const now = this.now();
 		// An account serving 429s is not "pending": retrying it faster is exactly
 		// what got us rate limited, so it must not hold the short window open.
@@ -528,7 +758,9 @@ export class UsageTracker {
 		const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
 		try {
 			const response = await this.fetchFn(url, { headers, signal: controller.signal });
-			if (response.status === 429) this.rateLimited.add(provider);
+			if (response.status === 429) {
+				this.rateLimited.set(provider, parseRetryAfter(response.headers?.get("retry-after"), this.now()));
+			}
 			if (!response.ok) return undefined;
 			return await response.json();
 		} finally {
@@ -536,47 +768,64 @@ export class UsageTracker {
 		}
 	}
 
-	private async fetchClaude(auth: AuthEntries, accountId: string): Promise<UsageSnapshot["claude"] | undefined> {
+	private async fetchClaude(auth: AuthEntries, accountId: string): Promise<FetchedUsage<"claude"> | undefined> {
 		const access = auth[accountId]?.access;
 		if (typeof access !== "string" || access.length === 0) return undefined;
 		try {
-			return parseClaudeUsage(
-				await this.fetchJson(
-					CLAUDE_USAGE_URL,
-					{ Authorization: `Bearer ${access}`, "anthropic-beta": "oauth-2025-04-20" },
-					"claude",
-				),
+			const json = await this.fetchJson(
+				CLAUDE_USAGE_URL,
+				{ Authorization: `Bearer ${access}`, "anthropic-beta": "oauth-2025-04-20" },
+				"claude",
 			);
+			const value = parseClaudeUsage(json);
+			return value === undefined ? undefined : { value, resetsAt: claudeResetAt(json) };
 		} catch {
 			return undefined;
 		}
 	}
 
-	private async fetchCodex(auth: AuthEntries, accountId: string): Promise<UsageSnapshot["codex"] | undefined> {
+	private async fetchCodex(auth: AuthEntries, accountId: string): Promise<FetchedUsage<"codex"> | undefined> {
 		const entry = auth[accountId];
 		const access = entry?.access;
 		const account = entry?.accountId;
 		if (typeof access !== "string" || typeof account !== "string" || !access || !account) return undefined;
 		try {
-			return parseCodexUsage(
-				await this.fetchJson(
-					CODEX_USAGE_URL,
-					{ Authorization: `Bearer ${access}`, "chatgpt-account-id": account },
-					"codex",
-				),
+			const json = await this.fetchJson(
+				CODEX_USAGE_URL,
+				{ Authorization: `Bearer ${access}`, "chatgpt-account-id": account },
+				"codex",
 			);
+			const value = parseCodexUsage(json);
+			// Codex may report only a relative reset, which is meaningless without the
+			// clock the rest of the tracker runs on.
+			return value === undefined ? undefined : { value, resetsAt: codexResetAt(json, this.now()) };
 		} catch {
 			return undefined;
 		}
 	}
 }
 
-/** The cached values for the currently selected accounts, in display shape. */
-function cachedSnapshot(cache: UsageCache, accounts: UsageAccounts): UsageSnapshot {
+/**
+ * The cached values for the currently selected accounts, in display shape.
+ * Values whose window has already rolled are dropped: adopting another
+ * process's stale reading is exactly as wrong as keeping our own.
+ */
+function cachedSnapshot(
+	cache: UsageCache,
+	accounts: UsageAccounts,
+	now: number,
+): [UsageSnapshot, Partial<Record<ProviderKey, number>>] {
 	const snapshot: UsageSnapshot = {};
-	const claude = cache.accounts[accounts.claude]?.claude;
-	const codex = cache.accounts[accounts.codex]?.codex;
-	if (claude) snapshot.claude = claude;
-	if (codex) snapshot.codex = codex;
-	return snapshot;
+	const resets: Partial<Record<ProviderKey, number>> = {};
+	const claudeEntry = cache.accounts[accounts.claude];
+	const codexEntry = cache.accounts[accounts.codex];
+	if (claudeEntry?.claude && !hasReset(claudeEntry.resetsAt, now)) {
+		snapshot.claude = claudeEntry.claude;
+		if (claudeEntry.resetsAt !== undefined) resets.claude = claudeEntry.resetsAt;
+	}
+	if (codexEntry?.codex && !hasReset(codexEntry.resetsAt, now)) {
+		snapshot.codex = codexEntry.codex;
+		if (codexEntry.resetsAt !== undefined) resets.codex = codexEntry.resetsAt;
+	}
+	return [snapshot, resets];
 }