@hank-warren/pi-statusline 0.1.3 → 0.2.1

package/README.md

@@ -3,28 +3,41 @@
 Replaces Pi's default footer with a compact statusline:
 
 ```text
-gpt-5.6-sol | pi-extensions:main* ⇣1 | 40k/1.0m
+gpt-5.6-sol | pi-extensions:main* ⇣1 | 40k/1.0m |  97·54  80
 ⑂ pi-extensions:feature/statusline* ⇣2 #7 | infra:fix/alerts #168
 019fafa7-29c0-7e99-9f82-5794d5721848
 ```
 
 ## What it shows
 
-- **Line 1** — active model ID, current directory basename and Git branch, and current context usage/window. A yellow `*` marks a dirty checkout and `⇣N` shows how many commits it is behind its locally known upstream ref. Unknown context usage is rendered as `?/<window>` until Pi can provide an estimate. Exceptional prompt-cache hits trigger the celebration described below.
+- **Line 1** — active model ID, current directory basename and Git branch, current context usage/window, and subscription usage headroom (see below). A yellow `*` marks a dirty checkout and `⇣N` shows how many commits it is behind its locally known upstream ref. Unknown context usage is rendered as `?/<window>` until Pi can provide an estimate. Exceptional prompt-cache hits trigger the celebration described below.
 - **Worktree lines** — when the session works in or sends tool calls into linked worktrees, one line shows the same branch/dirty/behind state for each worktree plus its associated PR number.
 - **Final line** — the full Pi session ID.
 
 It uses a fixed true-color palette with context warning thresholds.
 
+## Subscription usage meters
+
+When Pi's `~/.pi/agent/auth.json` contains OAuth credentials for Anthropic (Claude subscription) and/or OpenAI Codex, line 1 shows **percent remaining** for each rate-limit window after the context meter:
+
+- ` 97·54` — Claude 5-hour, then weekly remaining percent (Nerd Font `nf-cod-claude` icon). Subscriptions with a model-scoped weekly limit (e.g. Fable) show it as a third number — ` 97·54·24` — and it is omitted when the account has none.
+- ` 80` — Codex weekly remaining percent (`nf-cod-openai` icon)
+
+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.
+
+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`: it holds the last good snapshot plus the time the last poll was *started*, written atomically via a temp file and rename. A session adopts the cached values on its first refresh — so the meters are populated before it has issued a single request — and only polls when that shared timestamp is older than the interval. A provider answering `429` is parked for fifteen minutes (tracked per provider, 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. Requires a Nerd Font new enough to include the codicon brand glyphs (v3.5.0+); older fonts render them as replacement boxes.
+
 ## Neon cache-wave celebration
 
 Whenever one assistant response reaches a prompt-cache hit rate of at least 90%, a temporary module is appended after context usage for about two seconds:
 
 ```text
-gpt-5.6-sol | pi-extensions:main | 135k/272k | ⚡ 96% CACHE
+gpt-5.6-sol | pi-extensions:main | 135k/272k | ⚡96%·CACHE·HIT
 ```
 
-Only the `⚡ 96% CACHE` badge animates with a cyan → blue → magenta wave every 80 ms. The existing model, repository, context, separators, worktree, and session-ID rendering do not change.
+Only the `⚡96%·CACHE·HIT` badge animates: the whole badge flashes between neon magenta and neon cyan every 60 ms. The existing model, repository, context, separators, worktree, and session-ID rendering do not change.
 
 The rate is evaluated per provider response as:
 

package/cache-celebration.ts

@@ -1,5 +1,5 @@
 export const CACHE_HIT_THRESHOLD = 0.9;
-export const CACHE_CELEBRATION_FRAME_INTERVAL_MS = 80;
+export const CACHE_CELEBRATION_FRAME_INTERVAL_MS = 60;
 export const CACHE_CELEBRATION_DURATION_MS = 2_000;
 
 export interface CacheUsage {

package/index.ts

@@ -7,6 +7,7 @@ import {
 	triggerCacheCelebrationForMessage,
 } from "./cache-celebration.ts";
 import { FullRedrawScheduler } from "./redraw.ts";
+import { type UsageSnapshot, usageBand, UsageTracker } from "./usage.ts";
 import {
 	type GitRepositoryStatus,
 	readGitStatus,
@@ -24,6 +25,7 @@ export interface StatuslineData {
 	worktrees: SessionWorktree[];
 	sessionId: string;
 	cacheCelebration?: CacheCelebrationSnapshot;
+	usage?: UsageSnapshot;
 }
 
 const BLUE = "\x1b[38;2;0;153;255m";
@@ -35,17 +37,37 @@ const YELLOW = "\x1b[38;2;230;200;0m";
 const WHITE = "\x1b[38;2;220;220;220m";
 const MAGENTA = "\x1b[38;2;190;120;255m";
 const NEON_CYAN = "\x1b[38;2;0;255;255m";
-const NEON_BLUE = "\x1b[38;2;0;125;255m";
 const NEON_MAGENTA = "\x1b[38;2;255;0;255m";
 const DIM = "\x1b[2m";
 const BOLD = "\x1b[1m";
 const RESET = "\x1b[0m";
-const NEON_WAVE = [NEON_CYAN, NEON_CYAN, NEON_BLUE, NEON_BLUE, NEON_MAGENTA, NEON_MAGENTA] as const;
 
 function styled(style: string, text: string): string {
 	return `${style}${text}${RESET}`;
 }
 
+const CLAUDE_ICON = "\uec82";
+const OPENAI_ICON = "\uec81";
+const USAGE_BAND_COLORS = { green: GREEN, yellow: YELLOW, orange: ORANGE, red: RED } as const;
+
+function remainingPercent(remaining: number): string {
+	return styled(USAGE_BAND_COLORS[usageBand(remaining)], `${remaining}`);
+}
+
+export function renderUsageSegment(usage: UsageSnapshot): string | undefined {
+	const parts: string[] = [];
+	if (usage.claude) {
+		const dot = styled(DIM, "\u00b7");
+		let claude = `${remainingPercent(usage.claude.fiveHour)}${dot}${remainingPercent(usage.claude.sevenDay)}`;
+		if (usage.claude.scopedWeekly !== undefined) claude += `${dot}${remainingPercent(usage.claude.scopedWeekly)}`;
+		parts.push(`${styled(WHITE, CLAUDE_ICON)} ${claude}`);
+	}
+	if (usage.codex) {
+		parts.push(`${styled(WHITE, OPENAI_ICON)} ${remainingPercent(usage.codex.weekly)}`);
+	}
+	return parts.length > 0 ? parts.join(" ") : undefined;
+}
+
 function contextColor(contextTokens: number, contextWindow: number): string {
 	const percent = contextWindow > 0 ? Math.floor((contextTokens * 100) / contextWindow) : 0;
 	if (percent >= 90) return RED;
@@ -77,13 +99,9 @@ export function renderCacheCelebrationLine(
 	summary: string,
 	celebration: CacheCelebrationSnapshot,
 ): string {
-	const badge = `⚡ ${celebration.percent}% CACHE`;
-	const animatedBadge = Array.from(badge)
-		.map((character, index) => {
-			const color = NEON_WAVE[(index + celebration.frame) % NEON_WAVE.length];
-			return `${BOLD}${color}${character}${RESET}`;
-		})
-		.join("");
+	const badge = `⚡${celebration.percent}%·CACHE·HIT`;
+	const color = celebration.frame % 2 === 0 ? NEON_MAGENTA : NEON_CYAN;
+	const animatedBadge = `${BOLD}${color}${badge}${RESET}`;
 	return `${summary}${styled(DIM, " | ")}${animatedBadge}`;
 }
 
@@ -112,7 +130,14 @@ export function renderStatusline(data: StatuslineData, width: number): string[]
 			: styled(contextColor(data.contextTokens, data.contextWindow), formatTokenCount(data.contextTokens));
 	const context = `${used}${styled(DIM, "/")}${styled(WHITE, formatTokenCount(data.contextWindow))}`;
 	const cwd = data.cwdGit ? renderRepository(data.cwd, data.cwdGit) : styled(CYAN, data.cwd);
-	const summary = styled(BLUE, data.model) + separator + cwd + separator + context;
+	const usageSegment = data.usage ? renderUsageSegment(data.usage) : undefined;
+	const summary =
+		styled(BLUE, data.model) +
+		separator +
+		cwd +
+		separator +
+		context +
+		(usageSegment ? separator + usageSegment : "");
 	const firstLine = data.cacheCelebration
 		? renderCacheCelebrationLine(summary, data.cacheCelebration)
 		: summary;
@@ -128,6 +153,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 	const fullRedraw = new FullRedrawScheduler();
 	const cacheCelebration = new CacheCelebrationController(() => requestRender?.());
 	let tracker: SessionWorktreeTracker | undefined;
+	const usageTracker = new UsageTracker({ onChange: () => requestRender?.() });
 	let cwdGit: GitRepositoryStatus | null = null;
 	let cwdStatusAbort: AbortController | undefined;
 	let cwdStatusInFlight: Promise<void> | undefined;
@@ -180,6 +206,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 		runInBackground(refreshCwdStatus(ctx));
 		runInBackground(next.seedFromEntries(ctx.sessionManager.getBranch()));
 		runInBackground(next.includeCurrentWorktree(ctx.cwd));
+		runInBackground(usageTracker.refresh());
 	};
 
 	pi.on("session_start", (_event, ctx) => {
@@ -220,6 +247,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 								worktrees: tracker?.getWorktrees() ?? [],
 								sessionId: ctx.sessionManager.getSessionId(),
 								cacheCelebration: cacheCelebration.snapshot(),
+								usage: usageTracker.snapshot(),
 							},
 							width,
 						),
@@ -240,6 +268,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 		requestRender?.();
 		runInBackground(refreshCwdStatus(ctx));
 		if (tracker) runInBackground(tracker.refresh());
+		runInBackground(usageTracker.refresh());
 	});
 	pi.on("model_select", () => requestRender?.());
 	pi.on("session_tree", (_event, ctx) => resetTracker(ctx));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-statusline",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Compact Pi footer statusline with Git/worktree context, token usage, and neon celebrations for exceptional prompt-cache hits.",
   "type": "module",
   "keywords": [
@@ -34,6 +34,7 @@
     "index.ts",
     "cache-celebration.ts",
     "redraw.ts",
+    "usage.ts",
     "worktrees.ts",
     "README.md",
     "LICENSE"

package/usage.ts

@@ -0,0 +1,377 @@
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pid } from "node:process";
+
+/** Remaining (not used) integer percents per provider window. */
+export interface UsageSnapshot {
+	claude?: { fiveHour: number; sevenDay: number; scopedWeekly?: number };
+	codex?: { weekly: number };
+}
+
+const CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+/**
+ * Minimum spacing between usage polls. The Anthropic usage endpoint rate-limits
+ * (429) aggressively, so keep this well above a per-turn cadence.
+ */
+export const USAGE_REFRESH_INTERVAL_MS = 5 * 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
+ * session that starts with a stale token would otherwise show nothing for a
+ * full refresh interval.
+ */
+export const USAGE_RETRY_INTERVAL_MS = 30_000;
+/**
+ * How long a provider 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.
+ */
+export const USAGE_RATE_LIMIT_BACKOFF_MS = 15 * 60_000;
+const FETCH_TIMEOUT_MS = 10_000;
+const ONE_DAY_SECONDS = 86_400;
+
+function toRemaining(usedPercent: unknown): number | undefined {
+	if (typeof usedPercent !== "number" || !Number.isFinite(usedPercent)) return undefined;
+	return Math.round(Math.min(100, Math.max(0, 100 - usedPercent)));
+}
+
+interface ClaudeLimitEntry {
+	kind?: unknown;
+	percent?: unknown;
+	scope?: { model?: unknown } | null;
+}
+
+/**
+ * Parse the Anthropic OAuth usage payload into remaining percents. Accounts
+ * with a model-scoped weekly limit (e.g. Fable) expose it in the `limits`
+ * array as `weekly_scoped`; accounts without one simply omit the entry.
+ */
+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 };
+		limits?: unknown;
+	};
+	const fiveHour = toRemaining(body.five_hour?.utilization);
+	const sevenDay = toRemaining(body.seven_day?.utilization);
+	if (fiveHour === undefined || sevenDay === undefined) return undefined;
+	const result: UsageSnapshot["claude"] = { fiveHour, sevenDay };
+	if (Array.isArray(body.limits)) {
+		const scoped = body.limits.find(
+			(entry): entry is ClaudeLimitEntry =>
+				typeof entry === "object" &&
+				entry !== null &&
+				(entry as ClaudeLimitEntry).kind === "weekly_scoped" &&
+				typeof (entry as ClaudeLimitEntry).percent === "number",
+		);
+		const scopedWeekly = scoped === undefined ? undefined : toRemaining(scoped.percent);
+		if (scopedWeekly !== undefined) result.scopedWeekly = scopedWeekly;
+	}
+	return result;
+}
+
+interface CodexWindow {
+	used_percent?: unknown;
+	limit_window_seconds?: unknown;
+}
+
+/** Parse the Codex usage payload, selecting the weekly (largest ≥ 1 day) window. */
+export function parseCodexUsage(json: unknown): UsageSnapshot["codex"] | undefined {
+	if (typeof json !== "object" || json === null) return undefined;
+	const rateLimit = (json as { rate_limit?: unknown }).rate_limit;
+	if (typeof rateLimit !== "object" || rateLimit === null) return undefined;
+	const { primary_window, secondary_window } = rateLimit as {
+		primary_window?: CodexWindow | null;
+		secondary_window?: CodexWindow | null;
+	};
+	const windows = [primary_window, secondary_window].filter(
+		(window): window is CodexWindow => typeof window === "object" && window !== null,
+	);
+	const weekly = windows
+		.filter((window) => typeof window.limit_window_seconds === "number" && window.limit_window_seconds >= ONE_DAY_SECONDS)
+		.sort((a, b) => (b.limit_window_seconds as number) - (a.limit_window_seconds as number))[0];
+	const remaining = toRemaining((weekly ?? windows[0])?.used_percent);
+	return remaining === undefined ? undefined : { weekly: remaining };
+}
+
+/** Color band for a remaining percent: >60 green, >40 yellow, >15 orange, else red. */
+export function usageBand(remaining: number): "green" | "yellow" | "orange" | "red" {
+	if (remaining > 60) return "green";
+	if (remaining > 40) return "yellow";
+	if (remaining > 15) return "orange";
+	return "red";
+}
+
+type FetchFn = (url: string, init: { headers: Record<string, string>; signal: AbortSignal }) => Promise<{
+	ok: boolean;
+	status?: number;
+	json(): Promise<unknown>;
+}>;
+
+export interface UsageTrackerOptions {
+	authPath?: string;
+	cachePath?: string;
+	fetchFn?: FetchFn;
+	onChange?: () => void;
+	now?: () => number;
+}
+
+type ProviderKey = "claude" | "codex";
+
+/**
+ * Host-wide poll state shared by every pi process. Usage percentages are a
+ * property of the account, not of a session, so one poll per interval per host
+ * is both sufficient and necessary: a busy host runs dozens of pi processes, and
+ * per-process polling stampedes the endpoints into rate limiting everyone.
+ */
+interface UsageCache {
+	/** Last time any process started a poll; gates the shared throttle. */
+	attemptedAt: number;
+	/** Absolute times before which a rate-limited provider must not be polled. */
+	backoff: Partial<Record<ProviderKey, number>>;
+	snapshot: UsageSnapshot;
+}
+
+const EMPTY_CACHE: UsageCache = { attemptedAt: Number.NEGATIVE_INFINITY, backoff: {}, snapshot: {} };
+
+function parseUsageCache(json: unknown): UsageCache | undefined {
+	if (typeof json !== "object" || json === null) return undefined;
+	const body = json as { attemptedAt?: unknown; backoff?: unknown; snapshot?: unknown };
+	if (typeof body.attemptedAt !== "number" || !Number.isFinite(body.attemptedAt)) return undefined;
+	const snapshot = typeof body.snapshot === "object" && body.snapshot !== null ? (body.snapshot as UsageSnapshot) : {};
+	const backoff: UsageCache["backoff"] = {};
+	if (typeof body.backoff === "object" && body.backoff !== null) {
+		for (const key of ["claude", "codex"] as const) {
+			const value = (body.backoff as Record<string, unknown>)[key];
+			if (typeof value === "number" && Number.isFinite(value)) backoff[key] = value;
+		}
+	}
+	return { attemptedAt: body.attemptedAt, backoff, snapshot };
+}
+
+interface AuthEntries {
+	anthropic?: { access?: unknown };
+	"openai-codex"?: { access?: unknown; accountId?: unknown };
+}
+
+function hasClaudeAuth(auth: AuthEntries): boolean {
+	const access = auth.anthropic?.access;
+	return typeof access === "string" && access.length > 0;
+}
+
+function hasCodexAuth(auth: AuthEntries): boolean {
+	const entry = auth["openai-codex"];
+	return (
+		typeof entry?.access === "string" &&
+		entry.access.length > 0 &&
+		typeof entry.accountId === "string" &&
+		entry.accountId.length > 0
+	);
+}
+
+/**
+ * Best-effort subscription usage poller. Reads Pi's auth.json for tokens (never
+ * refreshes them), fetches both usage endpoints, and keeps the last-known good
+ * value per provider. Refreshes are throttled and must never throw.
+ */
+export class UsageTracker {
+	private readonly authPath: string;
+	private readonly cachePath: string;
+	private readonly fetchFn: FetchFn;
+	private readonly onChange?: () => void;
+	private readonly now: () => number;
+	private current: UsageSnapshot = {};
+	private awaitingProvider = true;
+	private readonly rateLimited = new Set<ProviderKey>();
+	private lastAttempt = Number.NEGATIVE_INFINITY;
+	private inFlight: Promise<void> | undefined;
+
+	constructor(options: UsageTrackerOptions = {}) {
+		this.authPath = options.authPath ?? join(homedir(), ".pi", "agent", "auth.json");
+		this.cachePath = options.cachePath ?? join(homedir(), ".pi", "agent", "statusline-usage.json");
+		this.fetchFn = options.fetchFn ?? ((url, init) => fetch(url, init));
+		this.onChange = options.onChange;
+		this.now = options.now ?? Date.now;
+	}
+
+	snapshot(): UsageSnapshot {
+		return this.current;
+	}
+
+	/**
+	 * Interval until the next allowed attempt: the short retry window while a
+	 * credentialed provider is still missing a value, the full interval otherwise.
+	 */
+	private currentInterval(): number {
+		return this.awaitingProvider ? USAGE_RETRY_INTERVAL_MS : USAGE_REFRESH_INTERVAL_MS;
+	}
+
+	/** Throttled refresh; resolves when the current attempt (if any) settles. */
+	refresh(): Promise<void> {
+		if (this.inFlight) return this.inFlight;
+		const attempt = this.performRefresh()
+			.catch(() => {
+				// Usage display is best-effort and must never interrupt the agent.
+			})
+			.finally(() => {
+				if (this.inFlight === attempt) this.inFlight = undefined;
+			});
+		this.inFlight = attempt;
+		return attempt;
+	}
+
+	/**
+	 * One refresh cycle: adopt whatever another process has already published,
+	 * then poll only if the shared throttle allows it.
+	 */
+	private async performRefresh(): Promise<void> {
+		const auth = (await this.readAuth()) ?? {};
+		const cache = (await this.readCache()) ?? EMPTY_CACHE;
+		// Another process's values are as good as ours and cost no request, so a new
+		// session shows real numbers on its very first render.
+		this.publish(this.merge(cache.snapshot, auth), auth, cache);
+
+		const now = this.now();
+		const lastAttempt = Math.max(this.lastAttempt, cache.attemptedAt);
+		if (now - lastAttempt < this.currentInterval()) return;
+		const claudeAllowed = hasClaudeAuth(auth) && now >= (cache.backoff.claude ?? Number.NEGATIVE_INFINITY);
+		const codexAllowed = hasCodexAuth(auth) && now >= (cache.backoff.codex ?? Number.NEGATIVE_INFINITY);
+		if (!claudeAllowed && !codexAllowed) return;
+
+		this.lastAttempt = now;
+		// Claim the slot before fetching so sibling processes skip this window even
+		// if our own request is slow or fails outright.
+		await this.writeCache({ ...cache, attemptedAt: now });
+
+		const [claude, codex] = await Promise.all([
+			claudeAllowed ? this.fetchClaude(auth) : Promise.resolve(undefined),
+			codexAllowed ? this.fetchCodex(auth) : Promise.resolve(undefined),
+		]);
+		const backoff = { ...cache.backoff };
+		for (const key of ["claude", "codex"] as const) {
+			if (this.rateLimited.has(key)) backoff[key] = now + USAGE_RATE_LIMIT_BACKOFF_MS;
+			else if ((key === "claude" ? claude : codex) !== undefined) delete backoff[key];
+		}
+		this.rateLimited.clear();
+
+		const next = this.merge({ claude, codex }, auth);
+		const updated: UsageCache = { attemptedAt: now, backoff, snapshot: next };
+		this.publish(next, auth, updated);
+		await this.writeCache(updated);
+	}
+
+	/**
+	 * Layer fresh values over the last-known ones and drop providers without
+	 * credentials: a logged-out provider must disappear immediately, while a
+	 * failed fetch keeps whatever we last saw.
+	 */
+	private merge(incoming: UsageSnapshot, auth: AuthEntries): UsageSnapshot {
+		const next: UsageSnapshot = {};
+		if (hasClaudeAuth(auth)) {
+			const claude = incoming.claude ?? this.current.claude;
+			if (claude) next.claude = claude;
+		}
+		if (hasCodexAuth(auth)) {
+			const codex = incoming.codex ?? this.current.codex;
+			if (codex) next.codex = codex;
+		}
+		return next;
+	}
+
+	/** Adopt a snapshot, recompute the retry gate, and repaint only on a change. */
+	private publish(next: UsageSnapshot, auth: AuthEntries, cache: UsageCache): void {
+		const now = this.now();
+		// A provider serving 429s is not "pending": retrying it faster is exactly
+		// what got us rate limited, so it must not hold the short window open.
+		this.awaitingProvider =
+			(hasClaudeAuth(auth) && next.claude === undefined && now >= (cache.backoff.claude ?? 0)) ||
+			(hasCodexAuth(auth) && next.codex === undefined && now >= (cache.backoff.codex ?? 0));
+		if (JSON.stringify(next) === JSON.stringify(this.current)) return;
+		this.current = next;
+		this.onChange?.();
+	}
+
+	private async readCache(): Promise<UsageCache | undefined> {
+		try {
+			return parseUsageCache(JSON.parse(await readFile(this.cachePath, "utf8")));
+		} catch {
+			return undefined;
+		}
+	}
+
+	/** Atomic write; a lost race just costs one extra poll, never a corrupt file. */
+	private async writeCache(cache: UsageCache): Promise<void> {
+		const temporary = `${this.cachePath}.${pid}.tmp`;
+		try {
+			await writeFile(temporary, JSON.stringify(cache), { mode: 0o600 });
+			await rename(temporary, this.cachePath);
+		} catch {
+			// The cache is an optimisation; failing to share it must never surface.
+		}
+	}
+
+	private async readAuth(): Promise<AuthEntries | undefined> {
+		try {
+			const parsed: unknown = JSON.parse(await readFile(this.authPath, "utf8"));
+			if (typeof parsed !== "object" || parsed === null) return undefined;
+			return parsed as AuthEntries;
+		} catch {
+			return undefined;
+		}
+	}
+
+	private async fetchJson(url: string, headers: Record<string, string>, provider: ProviderKey): Promise<unknown> {
+		const controller = new AbortController();
+		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.ok) return undefined;
+			return await response.json();
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+
+	private async fetchClaude(auth: AuthEntries): Promise<UsageSnapshot["claude"] | undefined> {
+		if (!hasClaudeAuth(auth)) return undefined;
+		try {
+			return parseClaudeUsage(
+				await this.fetchJson(
+					CLAUDE_USAGE_URL,
+					{
+						Authorization: `Bearer ${auth.anthropic?.access as string}`,
+						"anthropic-beta": "oauth-2025-04-20",
+					},
+					"claude",
+				),
+			);
+		} catch {
+			return undefined;
+		}
+	}
+
+	private async fetchCodex(auth: AuthEntries): Promise<UsageSnapshot["codex"] | undefined> {
+		if (!hasCodexAuth(auth)) return undefined;
+		const entry = auth["openai-codex"];
+		const access = entry?.access as string;
+		const accountId = entry?.accountId as string;
+		try {
+			return parseCodexUsage(
+				await this.fetchJson(
+					CODEX_USAGE_URL,
+					{
+						Authorization: `Bearer ${access}`,
+						"chatgpt-account-id": accountId,
+					},
+					"codex",
+				),
+			);
+		} catch {
+			return undefined;
+		}
+	}
+}