@llblab/pi-codex-usage 0.10.1 → 0.11.0

package/AGENTS.md

@@ -3,15 +3,15 @@
 - `Statusline-first scope`: Keep this extension zero-configuration and focused on compact status surfaces.
   - Trigger: Considering commands, menus, persisted settings, or notification output.
   - Action: Prefer deleting the surface unless it is required for the optimistic TUI status widget or the optional `pi-telegram` `/start` status-line mirror.
-
 - `Optimistic refresh`: Preserve the last good statusline bar during refresh and transient failures.
   - Trigger: Updating quota polling or error handling.
   - Action: Do not collapse the bar while a request is in flight; only show `n/a` or `error` after repeated failures or no usable quota.
-
 - `Adaptive compact status`: Match the status representation to the server-provided quota windows.
   - Trigger: Changing statusline formatting.
   - Action: When both windows exist, keep the classic dual bar with 20 top steps for the 5-hour window and 20 bottom steps for the weekly window. When only one weekly window exists, show its rounded remaining percentage directly instead of using a bar.
-
 - `Weekly reset countdown`: Append the weekly reset countdown whenever the available weekly window exposes a reset time.
   - Trigger: Changing reset-time normalization or statusline refresh cadence.
   - Action: Treat the secondary window as weekly in dual-window responses and the sole window as weekly in single-window responses. Keep `d` labels rounded upward in 144-minute day-tenth steps above 24h, show 24h..1h labels in upward-rounded 6-minute hour-tenth steps, keep `m`/`s` labels floored, and hold `0s` until a successful quota refresh reports the next window.
+- `Shared refresh`: Instances must not poll independently.
+  - Trigger: Changing refresh cadence, retries, locking, or adding fetch paths.
+  - Action: Keep the single shared-state protocol in the `Shared Refresh` section of `index.ts` (one shared `~/.pi/agent/tmp/pi-codex-usage/usage.json` for all Codex models; leader refreshes every minute, takeover after 90 seconds by claiming leadership before fetching, a non-waiting OS-backed SQLite mutex around claiming and fenced publication, atomic writes, shared failure backoff). Always re-read the file for request authorization (`owner` + `claimId` + lease) and publication; do not use an in-memory ownership fallback. Lock failures and failed claim writes must deny requests. `mutex.sqlite` stores no quota or leadership data: never unlink/replace it while instances run or evict a paused holder; close or process death releases the mutex. Keep network calls outside critical sections. Instances otherwise only read the file. Ignore additional quota buckets; do not restore model-specific labels, source priority, or cache directories. Keep the coordination behavior in sync with `pi-claude-usage`, which has its own independent state directory.

package/BACKLOG.md

@@ -1,3 +1,3 @@
 # Backlog
 
-No open work.
+No open items.

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
-## Unreleased
+## 0.11.0: Shared Quota Refresh
+
+- Coordinated polling across Pi instances through one `~/.pi/agent/tmp/pi-codex-usage/usage.json`: the leader refreshes every 60 seconds, followers normally read every 30 seconds, and leadership becomes eligible for takeover after 90 seconds without a touch. Failure backoff is shared, the last successful report stays visible for up to an hour, and provisional full-availability confirmation runs only in the refreshing instance.
+- Made the JSON authoritative for request admission and fenced publication using the on-disk owner, claim generation, and lease. A non-waiting OS-backed SQLite mutex serializes claiming and publication; lock or claim-write failures deny requests, and late results cannot overwrite a successor. **Upgrade:** close all old Pi instances before starting updated ones; do not mix locking protocols or remove the mutex file while instances run.
+- **Breaking:** Removed Spark-specific quotas, labels, and source priority. All Codex models now use the primary `codex` quota; additional buckets and legacy per-bucket caches are ignored without migration. Dual-bar rendering, loading animation, reset countdowns, Business credit usage, Pi auth, and the Codex app-server fallback are preserved.
 
 ## 0.10.1: Softer Quota Bar
 

package/README.md

@@ -14,18 +14,18 @@ This repository is a minimal fork of [`narumiruna/pi-extensions/extensions/pi-co
 
 ## Features
 
-- Shows two counter-moving half-height markers in the statusline bar while the active Codex/Spark quota bucket is loading, then refreshes every 60 seconds
-- Keeps the last usable active-bucket bar visible during ordinary refreshes instead of replacing known quota with a loading state
+- Shows two counter-moving half-height markers in the statusline bar while Codex usage is loading, then keeps the bar fresh (the countdown ticks locally)
+- Keeps the last usable bar visible during ordinary refreshes instead of replacing known quota with a loading state
 - Statusline output adapts to the response: weekly-only limits show an explicit remaining percentage and reset countdown, while dual-window limits keep the compact themed bar
-- Regular Codex subscription models show the primary `codex` quota bucket
-- `GPT-5.3-Codex-Spark` shows the parallel Spark quota bucket with the `spark` label
-- When `pi-telegram` is available, the same compact value appears as `codex: <value>` or `spark: <value>` in the `/start` menu status text for active OpenAI Codex subscription models
-- Additional returned buckets unrelated to the active Codex/Spark model are ignored
+- All Codex subscription models share the primary `codex` quota and status label
+- When `pi-telegram` is available, the same compact value appears as `codex: <value>` in the `/start` menu status text for active OpenAI Codex subscription models
+- Additional returned quota buckets are ignored
 - Pi OpenAI Codex provider auth is used first
 - Codex CLI app-server remains available as a fallback
 - Missing auth, subscription, plan, or quota windows are shown as `n/a`, not as an error
 - Successful updates briefly redraw the bar only when a 5% segment changes
-- Network/provider failures keep the last good bar briefly, then show `error`
+- Network/provider failures keep the last good bar (up to an hour), then show `error`
+- Any number of Pi instances share one request stream, see [Shared Refresh](#shared-refresh)
 - No commands or configuration are required
 
 ## Install
@@ -50,12 +50,6 @@ Regular Codex usage:
 codex ██████▀▀▀▀ 6d
 ```
 
-Spark model usage:
-
-```text
-spark ██████████ 7d
-```
-
 When OpenAI returns only the weekly window, the status shows the exact rounded remaining percentage and reset countdown directly:
 
 ```text
@@ -64,7 +58,7 @@ codex 67% 7d
 
 When both windows exist, the ten-character bar encodes two twenty-step limits at once: the top quadrants show the 5-hour limit and the bottom quadrants show the weekly limit, with each step representing 5%. If either quota window is exhausted, the bar keeps its shape but switches to the error background color.
 
-Before the first usable report for the active quota bucket arrives, two half-height markers move through the same fixed-width themed bar. The upper 5-hour marker travels opposite the lower weekly marker; both reverse smoothly at the ends, and each loader run randomly starts from one of the two mirrored endpoint phases. Their motion distinguishes loading from 100% remaining quota while preserving the normal bar background. A first report claiming both windows are completely unused is treated as provisional for 15 seconds and retried every second, because providers can briefly emit zeroed windows while initializing. Once a usable report exists, refresh requests preserve that last good bar.
+Before the first usable Codex report arrives, two half-height markers move through the same fixed-width themed bar. The upper 5-hour marker travels opposite the lower weekly marker; both reverse smoothly at the ends, and each loader run randomly starts from one of the two mirrored endpoint phases. Their motion distinguishes loading from 100% remaining quota while preserving the normal bar background. A first report claiming both windows are completely unused is treated as provisional for 15 seconds and retried every second by the refreshing instance before it is published, because providers can briefly emit zeroed windows while initializing. Once a usable report exists, refresh requests preserve that last good bar.
 
 When the weekly reset time is available, it follows either the single-window percentage or the dual-window bar. More than a day remains is shown in 144-minute day-tenth steps such as `7d`, `6.9d`, `6.6d`, `5.1d`, `5d`, `3.7d`, `3d`, `2d`, `1.9d`, `1.5d`, and `1.1d`, rounded upward to the next tenth. At 24 hours and below it switches to upward-rounded 6-minute hour-tenth steps such as `24h`, `23.7h`, `20.1h`, `20h`, `19.9h`, `1.4h`, `1.3h`, `1.2h`, `1.1h`, and `1h`. Under an hour it switches to floored minutes, and under a minute to seconds. After the reset timestamp passes, `0s` is held until the next successful quota refresh reports the new weekly window.
 
@@ -94,16 +88,35 @@ Runtime failure, such as a network or provider error:
 codex error
 ```
 
+## Shared Refresh
+
+The coordination code lives in the `Shared Refresh` section of [`index.ts`](./index.ts); the extension ships as a single TypeScript source file.
+
+All Codex models and instances coordinate through `~/.pi/agent/tmp/pi-codex-usage/usage.json` (quota percentages and timestamps only, no tokens). The Claude extension uses its own independent file at `~/.pi/agent/tmp/pi-claude-usage/usage.json`.
+
+Previous per-bucket cache directories are no longer read or written; there is no migration. Restart all previously running instances when upgrading to stop them writing the old layout.
+
+- The instance that last updated the file is the leader and refreshes it every minute
+- Every other instance only reads the file (re-checking every ≤30s) and redraws when it changes
+- Leadership is never cached in memory: before each usage request (including retries and fallbacks), the instance re-reads the file and checks its `owner`, unique `claimId`, and 90s lease. Publication rechecks that claim under the lock; a superseded success or failure is discarded. Failed locks or unwritten claims never authorize a request
+- If the file is 90 seconds old (leader is closed, busy, or asleep), the first follower that obtains the mutex takes over: it re-reads the JSON, writes itself as the leader with a fresh timestamp, releases the mutex, then fetches from the server and publishes under the mutex after rechecking its claim. Its next refresh is one minute later; JSON writes remain atomic renames
+- Claiming and publication use a non-waiting transaction in `mutex.sqlite`, through Node's built-in `node:sqlite` (Node ≥22.19.0, the existing package minimum). It stores no quota or leadership records and needs no extra package or service. The OS releases the lock when the connection closes or the process dies; there is no timeout-based lock stealing
+- Failures are written to the file with an exponential backoff (1 to 5 minutes; 5 to 30 minutes on HTTP 429) that applies to all instances
+- Instances without data yet show the loading bar and re-check every second until the leader publishes
+
+Coordination assumes a local filesystem and cooperating instances on the same machine. Never delete or replace `mutex.sqlite` while instances are running. Network requests do not hold the mutex; a process paused inside a short critical section keeps it until it resumes or exits, so other writers retry later without blocking the TUI. This preserves exclusion instead of stealing a live lock.
+
+**Upgrade:** Close all old instances before starting updated ones. The legacy `lock` files are ignored; old and new locking protocols must not run together. Cached `usage.json` data needs no migration.
+
 ## Telegram Status Menu
 
 If `@llblab/pi-telegram` is loaded with the public status-line provider API, this extension registers an optional `/start` menu status row. The row is shown only while the active model uses the OpenAI Codex subscription provider:
 
 ```text
 codex: ██████▀▀▀▀ 6d
-spark: ██████████ 7d
 ```
 
-The value is the same compact quota bar plus weekly reset countdown used by the terminal statusline, and the label follows the active Codex/Spark model. If `pi-telegram` is absent, older, or the active model is not a Codex subscription model, no Telegram row is added.
+The value is the same compact quota bar plus weekly reset countdown used by the terminal statusline, always with the `codex` label. If `pi-telegram` is absent, older, or the active model is not a Codex subscription model, no Telegram row is added.
 
 ## Auth
 

package/index.ts

@@ -1,9 +1,14 @@
 import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { createInterface } from "node:readline";
+import { DatabaseSync } from "node:sqlite";
 
-import type {
-  ExtensionAPI,
-  ExtensionContext,
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  getAgentDir,
 } from "@earendil-works/pi-coding-agent";
 
 const CODEX_PROVIDER_ID = "openai-codex";
@@ -16,7 +21,12 @@ const HOUR_MS = 60 * MINUTE_MS;
 const HOUR_TENTH_MS = 6 * MINUTE_MS;
 const DAY_MS = 24 * HOUR_MS;
 const DAY_TENTH_MS = 144 * MINUTE_MS;
-const REFRESH_INTERVAL_MS = 60 * SECOND_MS;
+/** How often an instance re-reads the shared file to redraw fresh data. */
+const MAX_TICK_MS = 30 * SECOND_MS;
+const MIN_TICK_MS = SECOND_MS;
+const TAKEOVER_JITTER_MS = 2 * SECOND_MS;
+/** A report older than this is no longer shown as current. */
+const STALE_REPORT_MAX_AGE_MS = HOUR_MS;
 const PROVISIONAL_RETRY_MS = SECOND_MS;
 const FULL_AVAILABILITY_CONFIRMATION_MS = 15 * SECOND_MS;
 const LOADING_FRAME_MS = 30;
@@ -24,10 +34,7 @@ const REDRAW_BLINK_MS = 150;
 const STATUS_KEY = "aa-codex-usage";
 const MAX_ERROR_BODY_CHARS = 600;
 const DEFAULT_STATUS_LABEL_TEXT = "codex";
-const SPARK_STATUS_LABEL_TEXT = "spark";
 const CODEX_USAGE_LIMIT_ID = "codex";
-const SPARK_USAGE_LIMIT_ID = "spark";
-const SPARK_MODEL_KEY = "gpt-5.3-codex-spark";
 const DUAL_BAR_WIDTH = 10;
 const TELEGRAM_STATUS_IMPORT_SPECIFIERS = [
   "@llblab/pi-telegram/status",
@@ -73,15 +80,12 @@ type QueryUsageOptions = {
   timeoutMs: number;
 };
 
-type CachedReport = {
-  createdAt: number;
-  report: CodexUsageReport;
-};
-
 type QueryUsageResult =
   | { ok: true; report: CodexUsageReport }
   | { ok: false; errors: UsageQueryError[] };
 
+type CodexSharedState = SharedState<CodexUsageReport>;
+
 export type UsageQueryError = {
   source: UsageSource;
   message: string;
@@ -116,12 +120,6 @@ type RateLimitStatusPayload = {
   spend_control?: unknown;
 };
 
-type BackendAdditionalRateLimit = {
-  limit_name?: unknown;
-  metered_feature?: unknown;
-  rate_limit?: unknown;
-};
-
 type BackendRateLimitDetails = {
   primary_window?: unknown;
   secondary_window?: unknown;
@@ -170,33 +168,256 @@ type PendingRpc = {
   reject: (error: Error) => void;
 };
 
+// --- Shared Refresh ---
+
+/**
+ * Cross-instance coordination for quota polling. Every Pi instance reads one
+ * JSON file; a single "leader"
+ * refreshes it every `LEADER_INTERVAL_MS`. Any other instance may take over once
+ * the file is `TAKEOVER_AFTER_MS` old: it first claims leadership (owner and
+ * timestamp) so nobody else is due, then fetches, then stamps the result. The
+ * file is the only authority for requests and fenced publication. Writes are
+ * atomic renames; short critical sections use an OS-backed SQLite mutex.
+ */
+
+export const LEADER_INTERVAL_MS = 60_000;
+/** The leader is considered gone after missing its slot by 30 seconds. */
+export const TAKEOVER_AFTER_MS = LEADER_INTERVAL_MS + 30_000;
+/** Minimum pause between two fetch attempts of the same instance. */
+export const MIN_ATTEMPT_GAP_MS = 60_000;
+
+const STATE_FILE = "usage.json";
+const LOCK_FILE = "mutex.sqlite";
+
+export type SharedState<Report = unknown> = {
+  report?: Report;
+  /** When `report` was last fetched successfully. */
+  updatedAt?: number;
+  /**
+   * When the leader last touched the file: written when it claims a refresh,
+   * before fetching, and again when the fetch finishes.
+   */
+  claimedAt?: number;
+  /** Instance id of the current leader (the last instance to claim). */
+  owner?: string;
+  /** Unique generation for this refresh, including renewals by the same owner. */
+  claimId?: string;
+  /** Last failure message; cleared by the next success. */
+  error?: string;
+  /** The failure means "no quota available" (n/a), not a runtime error. */
+  unavailable?: boolean;
+  failures?: number;
+  /** No instance should fetch before this time. */
+  retryNotBefore?: number;
+};
+
+export function readState<Report>(
+  dir: string,
+): SharedState<Report> | undefined {
+  try {
+    const parsed = JSON.parse(
+      readFileSync(join(dir, STATE_FILE), "utf8"),
+    ) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as SharedState<Report>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeState<Report>(
+  dir: string,
+  state: SharedState<Report>,
+): boolean {
+  try {
+    mkdirSync(dir, { recursive: true });
+    const temp = join(dir, `${STATE_FILE}.${process.pid}.tmp`);
+    writeFileSync(temp, JSON.stringify(state), { mode: 0o600 });
+    renameSync(temp, join(dir, STATE_FILE));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export type RefreshClaim = { owner: string; claimId: string };
+
+export type RefreshOutcome<Report> =
+  | { ok: true; report: Report }
+  | {
+      ok: false;
+      error: string;
+      unavailable?: boolean;
+      rateLimited: boolean;
+      retryAfterMs?: number;
+    };
+
+/** Read, decide and claim under the lock; never authorize an unwritten claim. */
+export function claimRefresh(
+  dir: string,
+  owner: string,
+  now?: number,
+): RefreshClaim | undefined {
+  const release = tryAcquireLock(dir);
+  if (!release) return undefined;
+  try {
+    const current = readState(dir);
+    const at = now ?? Date.now();
+    if (!isRefreshDue(current, owner, at)) return undefined;
+    const claim = { owner, claimId: randomUUID() };
+    return writeState(dir, { ...current, ...claim, claimedAt: at })
+      ? claim
+      : undefined;
+  } finally {
+    release();
+  }
+}
+
+function matchesClaim(
+  state: SharedState | undefined,
+  claim: RefreshClaim,
+  now: number,
+): boolean {
+  return (
+    state?.owner === claim.owner &&
+    state.claimId === claim.claimId &&
+    typeof state.claimedAt === "number" &&
+    now - state.claimedAt < TAKEOVER_AFTER_MS
+  );
+}
+
+/** Each admission check reads the file, not a remembered leadership flag. */
+export function ownsRefreshClaim(
+  dir: string,
+  claim: RefreshClaim,
+  now?: number,
+): boolean {
+  const current = readState(dir);
+  return matchesClaim(current, claim, now ?? Date.now());
+}
+
+/** A late success OR failure must not overwrite a successor's state. */
+export function publishRefresh<Report>(
+  dir: string,
+  claim: RefreshClaim,
+  outcome: RefreshOutcome<Report>,
+  now?: number,
+): boolean {
+  const release = tryAcquireLock(dir);
+  if (!release) return false;
+  try {
+    const current = readState<Report>(dir);
+    const at = now ?? Date.now();
+    if (!matchesClaim(current, claim, at)) return false;
+    if (outcome.ok) {
+      return writeState(dir, {
+        ...claim,
+        claimedAt: at,
+        updatedAt: at,
+        report: outcome.report,
+      });
+    }
+    const failures = (current?.failures ?? 0) + 1;
+    return writeState(dir, {
+      ...current,
+      ...claim,
+      claimedAt: at,
+      error: outcome.error,
+      unavailable: outcome.unavailable,
+      failures,
+      retryNotBefore: at + failureBackoffMs(failures, outcome),
+    });
+  } finally {
+    release();
+  }
+}
+
+/** Earliest time at which `owner` should try to refresh the state. */
+export function nextRefreshAt(
+  state: SharedState<unknown> | undefined,
+  owner: string,
+  now: number,
+): number {
+  const hold = state?.retryNotBefore ?? 0;
+  const touchedAt = Math.max(
+    state?.updatedAt ?? -Infinity,
+    state?.claimedAt ?? -Infinity,
+  );
+  if (touchedAt === -Infinity) return Math.max(now, hold);
+  const interval =
+    state?.owner === owner ? LEADER_INTERVAL_MS : TAKEOVER_AFTER_MS;
+  return Math.max(touchedAt + interval, hold);
+}
+
+export function isRefreshDue(
+  state: SharedState<unknown> | undefined,
+  owner: string,
+  now: number,
+): boolean {
+  return nextRefreshAt(state, owner, now) <= now;
+}
+
+/** Exponential failure backoff; HTTP 429 gets a longer base and cap. */
+export function failureBackoffMs(
+  failures: number,
+  options: { rateLimited: boolean; retryAfterMs?: number },
+): number {
+  const base = options.rateLimited ? 5 * 60_000 : 60_000;
+  const cap = options.rateLimited ? 30 * 60_000 : 5 * 60_000;
+  const exponential = Math.min(cap, base * 2 ** Math.max(0, failures - 1));
+  return Math.max(options.retryAfterMs ?? 0, exponential);
+}
+
+/**
+ * An empty SQLite transaction is a non-waiting, OS-backed mutex, not storage
+ * for quota or leadership. Close or process death releases it; a paused live
+ * holder cannot be evicted. Never unlink/replace mutex.sqlite while in use.
+ */
+export function tryAcquireLock(dir: string): (() => void) | undefined {
+  let database: DatabaseSync | undefined;
+  try {
+    mkdirSync(dir, { recursive: true });
+    database = new DatabaseSync(join(dir, LOCK_FILE));
+    // Contention must not wait on Pi's TUI thread; PRAGMA also works on Node 22.
+    database.exec("PRAGMA busy_timeout = 0; BEGIN EXCLUSIVE");
+  } catch {
+    database?.close();
+    return undefined;
+  }
+  return () => {
+    const held = database;
+    database = undefined;
+    held?.close();
+  };
+}
+
 export default function codexUsage(pi: ExtensionAPI) {
-  let cache: CachedReport | undefined;
-  let failedRefreshes = 0;
-  let inFlightUsageQuery:
-    { limitId: string; promise: Promise<QueryUsageResult> } | undefined;
+  const instanceId = `${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+  const stateDir = join(getAgentDir(), "tmp", "pi-codex-usage");
+  let lastAttemptAt = 0;
+  let inFlightRefresh: Promise<void> | undefined;
+  let shown: { key?: string; report?: CodexUsageReport; updatedAt?: number } = {};
   let statuslineBlinkTimer: TimeoutHandle | undefined;
-  let statuslineClearTimer: TimeoutHandle | undefined;
   let statuslineCountdownTimer: TimeoutHandle | undefined;
   let statuslineLoadingTimer: TimeoutHandle | undefined;
   let statuslineRefreshTimer: TimeoutHandle | undefined;
   let statuslineLoadingFrame = 0;
-  let statuslineLoadingLimitId: string | undefined;
   let statuslineRequestId = 0;
-  let provisionalFullReport:
-    { limitId: string; firstSeenAt: number } | undefined;
   let unregisterTelegramStatusLine: (() => void) | undefined;
   let telegramStatusLineRegistration: Promise<void> | undefined;
 
+  const loadState = () => readState<CodexUsageReport>(stateDir);
+
   const ensureTelegramStatusLineRegistered = () => {
     if (unregisterTelegramStatusLine || telegramStatusLineRegistration) return;
     telegramStatusLineRegistration = registerCodexUsageTelegramStatusLine(
       ({ activeModel }) => {
         if (!isOpenAICodexModel(activeModel)) return undefined;
-        if (!cache) return undefined;
-        const value = formatCodexUsageStatusValue(cache.report, activeModel);
+        if (!shown.report) return undefined;
+        const value = formatCodexUsageStatusValue(shown.report, activeModel);
         return value
-          ? { label: activeUsageLabel(activeModel), value }
+          ? { label: DEFAULT_STATUS_LABEL_TEXT, value }
           : undefined;
       },
     )
@@ -210,33 +431,26 @@ export default function codexUsage(pi: ExtensionAPI) {
 
   const clearStatuslineTimers = () => {
     if (statuslineBlinkTimer) clearTimeout(statuslineBlinkTimer);
-    if (statuslineClearTimer) clearTimeout(statuslineClearTimer);
     if (statuslineCountdownTimer) clearTimeout(statuslineCountdownTimer);
     if (statuslineLoadingTimer) clearTimeout(statuslineLoadingTimer);
     if (statuslineRefreshTimer) clearTimeout(statuslineRefreshTimer);
     statuslineBlinkTimer = undefined;
-    statuslineClearTimer = undefined;
     statuslineCountdownTimer = undefined;
     statuslineLoadingTimer = undefined;
-    statuslineLoadingLimitId = undefined;
     statuslineRefreshTimer = undefined;
   };
 
   const stopStatuslineLoading = () => {
     if (statuslineLoadingTimer) clearTimeout(statuslineLoadingTimer);
     statuslineLoadingTimer = undefined;
-    statuslineLoadingLimitId = undefined;
   };
 
   const startStatuslineLoading = (
     ctx: ExtensionContext,
     model: CodexUsageModel | undefined,
   ) => {
-    const limitId = activeUsageLimitId(model);
-    if (statuslineLoadingTimer && statuslineLoadingLimitId === limitId) return;
-    stopStatuslineLoading();
+    if (statuslineLoadingTimer) return;
     statuslineLoadingFrame = Math.random() < 0.5 ? 0 : DUAL_BAR_WIDTH * 2 - 1;
-    statuslineLoadingLimitId = limitId;
     const drawNextFrame = () => {
       try {
         ctx.ui.setStatus(
@@ -260,29 +474,14 @@ export default function codexUsage(pi: ExtensionAPI) {
   const clearUsageStatusline = (ctx: ExtensionContext) => {
     statuslineRequestId += 1;
     clearStatuslineTimers();
+    shown = {};
     ctx.ui.setStatus(STATUS_KEY, undefined);
   };
 
-  const scheduleTemporaryStatuslineClear = (ctx: ExtensionContext) => {
-    if (statuslineClearTimer) clearTimeout(statuslineClearTimer);
-    statuslineClearTimer = setTimeout(() => {
-      try {
-        ctx.ui.setStatus(STATUS_KEY, undefined);
-        statuslineClearTimer = undefined;
-      } catch (error) {
-        handleTimerError(error);
-      }
-    }, REFRESH_INTERVAL_MS) as TimeoutHandle;
-    statuslineClearTimer.unref?.();
-  };
-
-  const scheduleStatuslineRefresh = (
-    ctx: ExtensionContext,
-    delayMs = REFRESH_INTERVAL_MS,
-  ) => {
+  const scheduleStatuslineRefresh = (ctx: ExtensionContext, delayMs: number) => {
     if (statuslineRefreshTimer) clearTimeout(statuslineRefreshTimer);
     statuslineRefreshTimer = setTimeout(() => {
-      void refreshCurrentCodexUsageStatusline(ctx, true).catch(
+      void refreshCurrentCodexUsageStatusline(ctx, false).catch(
         handleAsyncTimerError,
       );
     }, delayMs) as TimeoutHandle;
@@ -319,18 +518,12 @@ export default function codexUsage(pi: ExtensionAPI) {
   const setUsageStatusline = (
     ctx: ExtensionContext,
     report: CodexUsageReport,
-    options: {
-      autoRefresh: boolean;
-      blink: boolean;
-      model: CodexUsageModel | undefined;
-    },
+    options: { blink: boolean; model: CodexUsageModel | undefined },
   ) => {
     if (statuslineBlinkTimer) clearTimeout(statuslineBlinkTimer);
-    if (statuslineClearTimer) clearTimeout(statuslineClearTimer);
     if (statuslineCountdownTimer) clearTimeout(statuslineCountdownTimer);
     stopStatuslineLoading();
     statuslineBlinkTimer = undefined;
-    statuslineClearTimer = undefined;
     statuslineCountdownTimer = undefined;
     const text = formatCodexUsageStatusline(report, ctx, options.model);
     if (options.blink) {
@@ -352,32 +545,148 @@ export default function codexUsage(pi: ExtensionAPI) {
       ctx.ui.setStatus(STATUS_KEY, text);
       scheduleStatuslineCountdown(ctx, report, options.model);
     }
-    if (options.autoRefresh) scheduleStatuslineRefresh(ctx);
-    else scheduleTemporaryStatuslineClear(ctx);
   };
 
-  const queryCurrentUsage = (
+  /** Draws the shared state; skips redraws when nothing changed. */
+  const renderState = (
     ctx: ExtensionContext,
+    state: CodexSharedState | undefined,
     model: CodexUsageModel | undefined,
+    force: boolean,
   ) => {
-    const limitId = activeUsageLimitId(model);
-    if (inFlightUsageQuery?.limitId === limitId)
-      return inFlightUsageQuery.promise;
-    const promise = queryUsage(
+    // Cached display data is not permission to query when the file is unreadable.
+    if (!state && shown.report && Date.now() - (shown.updatedAt ?? 0) < STALE_REPORT_MAX_AGE_MS) {
+      if (force) setUsageStatusline(ctx, shown.report, { blink: false, model });
+      return;
+    }
+    const usable =
+      state?.report &&
+      state.updatedAt !== undefined &&
+      Date.now() - state.updatedAt < STALE_REPORT_MAX_AGE_MS &&
+      canReuseCachedReport(state.report, model)
+        ? state.report
+        : undefined;
+    if (usable) {
+      const key = `report:${state?.updatedAt}`;
+      if (!force && shown.key === key) return;
+      const blink = shown.report
+        ? formatReportBar(shown.report, model) !== formatReportBar(usable, model)
+        : false;
+      shown = { key, report: usable, updatedAt: state?.updatedAt };
+      setUsageStatusline(ctx, usable, { blink, model });
+    } else if (state?.error) {
+      const key = `error:${state.error}`;
+      if (!force && shown.key === key) return;
+      shown = { key };
+      clearStatuslineTimers();
+      ctx.ui.setStatus(
+        STATUS_KEY,
+        formatStatuslineProblem(ctx, state.unavailable === true, model),
+      );
+    } else {
+      shown = { key: "loading" };
+      startStatuslineLoading(ctx, model);
+    }
+  };
+
+  /**
+   * When this instance is due (leader after 1 minute, anyone after 90 seconds) it
+   * claims leadership under the lock (owner and timestamp, so no other
+   * instance is due), then fetches, then stamps the outcome. Failures are
+   * published with a backoff so other instances do not pile on.
+   */
+  const refreshSharedState = (
+    ctx: ExtensionContext,
+    model: CodexUsageModel | undefined,
+  ) => {
+    if (inFlightRefresh) return inFlightRefresh;
+    const promise = (async () => {
+      const claim = claimRefresh(stateDir, instanceId);
+      if (!claim) return;
+      lastAttemptAt = Date.now();
+      const result = await queryConfirmedUsage(
+        ctx,
+        model,
+        loadState()?.report,
+        () => ownsRefreshClaim(stateDir, claim),
+      );
+      if (!result) return;
+      if (result.ok) {
+        publishRefresh(stateDir, claim, result);
+        return;
+      }
+      if (result.errors.some((error) => isStaleExtensionContextError(error.cause)))
+        return;
+      publishRefresh(stateDir, claim, {
+        ok: false,
+        error: result.errors.map((error) => error.message).join("; "),
+        unavailable: isUsageUnavailable(result.errors),
+        rateLimited: result.errors.some((error) =>
+          error.message.includes("returned 429"),
+        ),
+      });
+    })().finally(() => {
+      if (inFlightRefresh === promise) inFlightRefresh = undefined;
+    });
+    inFlightRefresh = promise;
+    return promise;
+  };
+
+  /**
+   * Queries the usage. A first report claiming every window is completely
+   * unused is provisional (providers can briefly emit zeroed windows while
+   * initializing), so the claiming leader re-queries it every second for up to
+   * 15 seconds before publishing.
+   */
+  const queryConfirmedUsage = async (
+    ctx: ExtensionContext,
+    model: CodexUsageModel | undefined,
+    previous: CodexUsageReport | undefined,
+    mayQuery: () => boolean,
+  ): Promise<QueryUsageResult | undefined> => {
+    const startedAt = Date.now();
+    let result = await queryUsage(
       ctx,
       { timeoutMs: DEFAULT_TIMEOUT_MS },
       model,
-    ).finally(() => {
-      if (inFlightUsageQuery?.promise === promise)
-        inFlightUsageQuery = undefined;
-    });
-    inFlightUsageQuery = { limitId, promise };
-    return promise;
+      mayQuery,
+    );
+    if (previous && isFullyAvailableReport(previous, model)) return result;
+    while (
+      result?.ok &&
+      isFullyAvailableReport(result.report, model) &&
+      Date.now() - startedAt < FULL_AVAILABILITY_CONFIRMATION_MS
+    ) {
+      await new Promise((resolve) => setTimeout(resolve, PROVISIONAL_RETRY_MS));
+      const retry = await queryUsage(
+        ctx,
+        { timeoutMs: DEFAULT_TIMEOUT_MS },
+        model,
+        mayQuery,
+      );
+      if (!retry) return undefined;
+      if (!retry.ok) break;
+      result = retry;
+    }
+    return result;
+  };
+
+  const nextTickDelayMs = (state: CodexSharedState | undefined) => {
+    // Nothing to show yet (e.g. a claimed fetch is in flight): poll quickly.
+    if (shown.key === "loading") return MIN_TICK_MS;
+    const now = Date.now();
+    const dueAt = Math.max(
+      nextRefreshAt(state, instanceId, now),
+      lastAttemptAt + MIN_ATTEMPT_GAP_MS,
+    );
+    const jitter =
+      state?.owner === instanceId ? 0 : Math.random() * TAKEOVER_JITTER_MS;
+    return Math.min(MAX_TICK_MS, Math.max(MIN_TICK_MS, dueAt - now + jitter));
   };
 
   const refreshCurrentCodexUsageStatusline = async (
     ctx: ExtensionContext,
-    force: boolean,
+    forceRender: boolean,
     model?: CodexUsageModel,
   ) => {
     try {
@@ -387,93 +696,26 @@ export default function codexUsage(pi: ExtensionAPI) {
         return;
       }
 
-      const usableCache =
-        cache && canReuseCachedReport(cache.report, activeModel)
-          ? cache
-          : undefined;
-      if (usableCache) {
-        setUsageStatusline(ctx, usableCache.report, {
-          autoRefresh: true,
-          blink: false,
-          model: activeModel,
-        });
-      } else {
-        startStatuslineLoading(ctx, activeModel);
-      }
       const requestId = statuslineRequestId + 1;
       statuslineRequestId = requestId;
-      const freshCache =
-        usableCache && Date.now() - usableCache.createdAt < REFRESH_INTERVAL_MS
-          ? usableCache
-          : undefined;
-      if (freshCache && !force) {
-        setUsageStatusline(ctx, freshCache.report, {
-          autoRefresh: true,
-          blink: false,
-          model: activeModel,
-        });
-        return;
-      }
+      let state = loadState();
+      renderState(ctx, state, activeModel, forceRender);
 
-      const result = await queryCurrentUsage(ctx, activeModel);
-      if (requestId !== statuslineRequestId) return;
-      if (!isOpenAICodexModel(ctx.model)) {
-        clearUsageStatusline(ctx);
-        return;
-      }
-
-      if (!result.ok) {
-        failedRefreshes += 1;
-        const activeCache =
-          cache && canReuseCachedReport(cache.report, activeModel)
-            ? cache
-            : undefined;
-        if (!activeCache || failedRefreshes >= 5) {
-          stopStatuslineLoading();
-          ctx.ui.setStatus(
-            STATUS_KEY,
-            formatStatuslineProblem(ctx, result.errors, activeModel),
-          );
-        }
-        scheduleStatuslineRefresh(ctx);
-        return;
-      }
-
-      const previousReport = cache?.report;
-      const previousWasFullyAvailable = previousReport
-        ? isFullyAvailableReport(previousReport, activeModel)
-        : false;
+      const now = Date.now();
       if (
-        isFullyAvailableReport(result.report, activeModel) &&
-        !previousWasFullyAvailable
+        isRefreshDue(state, instanceId, now) &&
+        now - lastAttemptAt >= MIN_ATTEMPT_GAP_MS
       ) {
-        const now = Date.now();
-        const limitId = activeUsageLimitId(activeModel);
-        if (provisionalFullReport?.limitId !== limitId) {
-          provisionalFullReport = { limitId, firstSeenAt: now };
-        }
-        if (
-          now - provisionalFullReport.firstSeenAt <
-          FULL_AVAILABILITY_CONFIRMATION_MS
-        ) {
-          scheduleStatuslineRefresh(ctx, PROVISIONAL_RETRY_MS);
+        await refreshSharedState(ctx, activeModel);
+        if (requestId !== statuslineRequestId) return;
+        if (!isOpenAICodexModel(ctx.model)) {
+          clearUsageStatusline(ctx);
           return;
         }
-      } else {
-        provisionalFullReport = undefined;
+        state = loadState();
+        renderState(ctx, state, activeModel, false);
       }
-      const blink = previousReport
-        ? formatReportBar(previousReport, activeModel) !==
-          formatReportBar(result.report, activeModel)
-        : false;
-      failedRefreshes = 0;
-      provisionalFullReport = undefined;
-      cache = { createdAt: Date.now(), report: result.report };
-      setUsageStatusline(ctx, result.report, {
-        autoRefresh: true,
-        blink,
-        model: activeModel,
-      });
+      scheduleStatuslineRefresh(ctx, nextTickDelayMs(state));
     } catch (error) {
       if (isStaleExtensionContextError(error)) {
         clearStatuslineTimers();
@@ -488,7 +730,7 @@ export default function codexUsage(pi: ExtensionAPI) {
   pi.on("session_start", (_event, ctx) => {
     ensureTelegramStatusLineRegistered();
     if (isOpenAICodexModel(ctx.model))
-      void refreshCurrentCodexUsageStatusline(ctx, false).catch(
+      void refreshCurrentCodexUsageStatusline(ctx, true).catch(
         handleAsyncTimerError,
       );
     else clearUsageStatusline(ctx);
@@ -496,7 +738,7 @@ export default function codexUsage(pi: ExtensionAPI) {
 
   pi.on("session_tree", (_event, ctx) => {
     if (isOpenAICodexModel(ctx.model))
-      void refreshCurrentCodexUsageStatusline(ctx, false).catch(
+      void refreshCurrentCodexUsageStatusline(ctx, true).catch(
         handleAsyncTimerError,
       );
     else clearUsageStatusline(ctx);
@@ -504,7 +746,7 @@ export default function codexUsage(pi: ExtensionAPI) {
 
   pi.on("model_select", (event, ctx) => {
     if (isOpenAICodexModel(event.model)) {
-      void refreshCurrentCodexUsageStatusline(ctx, false, event.model).catch(
+      void refreshCurrentCodexUsageStatusline(ctx, true, event.model).catch(
         handleAsyncTimerError,
       );
     } else {
@@ -538,28 +780,6 @@ function isOpenAICodexModel(
   return model?.provider === CODEX_PROVIDER_ID;
 }
 
-function isSparkCodexModel(
-  model: Pick<PiModel, "id" | "name" | "provider"> | undefined,
-): boolean {
-  if (!isOpenAICodexModel(model)) return false;
-  const key = `${model?.id ?? ""} ${model?.name ?? ""}`.toLowerCase();
-  return key.includes(SPARK_MODEL_KEY);
-}
-
-function activeUsageLimitId(
-  model: Pick<PiModel, "id" | "name" | "provider"> | undefined,
-): string {
-  return isSparkCodexModel(model) ? SPARK_USAGE_LIMIT_ID : CODEX_USAGE_LIMIT_ID;
-}
-
-function activeUsageLabel(
-  model: Pick<PiModel, "id" | "name" | "provider"> | undefined,
-): string {
-  return isSparkCodexModel(model)
-    ? SPARK_STATUS_LABEL_TEXT
-    : DEFAULT_STATUS_LABEL_TEXT;
-}
-
 async function importTelegramStatusLineModule(): Promise<
   TelegramStatusLineModule | undefined
 > {
@@ -589,27 +809,28 @@ async function queryUsage(
   ctx: ExtensionContext,
   options: Pick<QueryUsageOptions, "timeoutMs">,
   model: CodexUsageModel | undefined,
-): Promise<QueryUsageResult> {
+  mayQuery: () => boolean,
+): Promise<QueryUsageResult | undefined> {
   const errors: UsageQueryError[] = [];
-  const sources = isSparkCodexModel(model)
-    ? (["codex-app-server", "pi-auth"] as const)
-    : (["pi-auth", "codex-app-server"] as const);
+  const sources = ["pi-auth", "codex-app-server"] as const;
 
   for (const source of sources) {
+    if (!mayQuery()) return undefined;
     try {
       const report =
         source === "pi-auth"
-          ? await queryViaPiAuth(ctx, options.timeoutMs)
-          : await queryViaCodexAppServer(options.timeoutMs);
+          ? await queryViaPiAuth(ctx, options.timeoutMs, mayQuery)
+          : await queryViaCodexAppServer(options.timeoutMs, mayQuery);
+      if (!report) return undefined;
       if (
-        selectUsageSnapshot(report, activeUsageLimitId(model)) ||
+        selectUsageSnapshot(report, CODEX_USAGE_LIMIT_ID) ||
         report.credits
       ) {
         return { ok: true, report };
       }
       errors.push({
         source,
-        message: `${source} returned no displayable ${activeUsageLabel(model)} rate-limit windows`,
+        message: `${source} returned no displayable codex rate-limit windows`,
       });
     } catch (cause) {
       errors.push({ source, message: errorMessage(cause), cause });
@@ -622,7 +843,8 @@ async function queryUsage(
 async function queryViaPiAuth(
   ctx: ExtensionContext,
   timeoutMs: number,
-): Promise<CodexUsageReport> {
+  mayQuery: () => boolean,
+): Promise<CodexUsageReport | undefined> {
   const auth = await resolvePiCodexAuth(ctx);
   if (!auth) {
     throw new Error(
@@ -630,6 +852,7 @@ async function queryViaPiAuth(
     );
   }
 
+  if (!mayQuery()) return undefined;
   const response = await fetchWithTimeout(
     CODEX_USAGE_URL,
     { headers: auth.headers },
@@ -724,10 +947,12 @@ async function fetchWithTimeout(
 
 async function queryViaCodexAppServer(
   timeoutMs: number,
-): Promise<CodexUsageReport> {
+  mayQuery: () => boolean,
+): Promise<CodexUsageReport | undefined> {
   const client = new CodexAppServerClient(timeoutMs);
   try {
     await client.start();
+    if (!mayQuery()) return undefined;
     await client.request("initialize", {
       clientInfo: {
         name: "pi_codex_usage",
@@ -741,6 +966,7 @@ async function queryViaCodexAppServer(
       },
     });
     client.notify("initialized");
+    if (!mayQuery()) return undefined;
     const result = await client.request("account/rateLimits/read", undefined);
     return normalizeAppServerResponse(
       assertObject(
@@ -916,21 +1142,6 @@ export function normalizeBackendPayload(
   );
   if (primarySnapshot) snapshots.push(primarySnapshot);
 
-  if (Array.isArray(payload.additional_rate_limits)) {
-    for (const item of payload.additional_rate_limits) {
-      const additional = assertObject(
-        item,
-        "additional rate limit",
-      ) as BackendAdditionalRateLimit;
-      const snapshot = normalizeBackendSnapshot(
-        backendAdditionalLimitId(additional),
-        additional.rate_limit,
-        _capturedAt,
-      );
-      if (snapshot) snapshots.push(snapshot);
-    }
-  }
-
   const credits = normalizeBackendCredits(payload, _capturedAt);
   if (snapshots.length === 0 && !credits) {
     throw new Error(
@@ -983,13 +1194,6 @@ function normalizeBackendCredits(
     : { remainingPercent, resetAt };
 }
 
-function backendAdditionalLimitId(limit: BackendAdditionalRateLimit): string {
-  const raw = `${asString(limit.limit_name) ?? ""} ${asString(limit.metered_feature) ?? ""}`;
-  return raw.toLowerCase().includes("spark")
-    ? SPARK_USAGE_LIMIT_ID
-    : (normalizedUsageKey(raw) ?? CODEX_USAGE_LIMIT_ID);
-}
-
 function normalizeBackendSnapshot(
   limitId: string,
   rateLimit: unknown,
@@ -1079,6 +1283,7 @@ function normalizeAppServerSnapshot(
     "app-server rate-limit snapshot",
   ) as AppServerRateLimitSnapshot;
   const limitId = asString(snapshot.limitId) ?? fallbackId;
+  if (normalizedUsageKey(limitId) !== CODEX_USAGE_LIMIT_ID) return undefined;
   const primary = normalizeAppServerWindow(snapshot.primary, capturedAt);
   const secondary = normalizeAppServerWindow(snapshot.secondary, capturedAt);
   if (!primary && !secondary) return undefined;
@@ -1290,9 +1495,9 @@ function formatReportBar(
 function formatStatuslineText(
   ctx: ExtensionContext,
   value: string,
-  model?: CodexUsageModel,
+  _model?: CodexUsageModel,
 ): string {
-  const label = ctx.ui.theme.fg("accent", activeUsageLabel(model));
+  const label = ctx.ui.theme.fg("accent", DEFAULT_STATUS_LABEL_TEXT);
   return `${label} ${ctx.ui.theme.fg("dim", value)}`;
 }
 
@@ -1300,9 +1505,9 @@ function formatStatuslineBarText(
   ctx: ExtensionContext,
   bar: string,
   background: "userMessageBg" | "toolErrorBg",
-  model?: CodexUsageModel,
+  _model?: CodexUsageModel,
 ): string {
-  const label = ctx.ui.theme.fg("accent", activeUsageLabel(model));
+  const label = ctx.ui.theme.fg("accent", DEFAULT_STATUS_LABEL_TEXT);
   const value = ctx.ui.theme.bg(background, ctx.ui.theme.fg("dim", bar));
   return `${label} ${value}`;
 }
@@ -1338,11 +1543,11 @@ function formatStatuslineLoading(
 
 function formatStatuslineProblem(
   ctx: ExtensionContext,
-  errors: UsageQueryError[],
-  model?: CodexUsageModel,
+  unavailable: boolean,
+  _model?: CodexUsageModel,
 ): string {
-  const label = ctx.ui.theme.fg("accent", activeUsageLabel(model));
-  const value = isUsageUnavailable(errors)
+  const label = ctx.ui.theme.fg("accent", DEFAULT_STATUS_LABEL_TEXT);
+  const value = unavailable
     ? ctx.ui.theme.fg("muted", "n/a")
     : ctx.ui.theme.fg("error", "error");
   return `${label} ${value}`;
@@ -1490,9 +1695,9 @@ function weeklyWindow(
 
 function selectActiveUsageSnapshot(
   report: CodexUsageReport,
-  model: CodexUsageModel | undefined,
+  _model: CodexUsageModel | undefined,
 ): NormalizedRateLimitSnapshot | undefined {
-  return selectUsageSnapshot(report, activeUsageLimitId(model));
+  return selectUsageSnapshot(report, CODEX_USAGE_LIMIT_ID);
 }
 
 function selectUsageSnapshot(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-codex-usage",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "private": false,
   "description": "Minimal Pi extension that shows primary Codex ChatGPT subscription usage limits",
   "keywords": [