pi-sub-quota 0.1.1 → 0.1.2

package/README.md

@@ -24,8 +24,8 @@ Restart pi (or run `/reload`). There is nothing to configure: the extension reus
 
 | Command | Effect |
 | --- | --- |
-| `/quota` | quota for every configured provider, as a panel |
-| `/quota refresh` | fetch fresh numbers for the active provider now |
+| `/quota` | cached quota for every configured provider, instantly — stale numbers refresh in the background and the panel updates when they land |
+| `/quota refresh` | force a re-fetch for the active provider now (at most one request per provider per minute, machine-wide, plus one immediate in-cycle retry when a request fails) |
 | `/quota mode inline\|line\|off` | how — and whether — the footer shows quota |
 | `/quota help` | list options |
 
@@ -72,7 +72,7 @@ kimi-coding  coding plan · Allegretto · booster ¥100.00/¥200.00
 /quota refresh · /quota mode line|inline|off · /quota help
 ```
 
-The footer shows how much you have used; the panel shows what is left, as a meter and a percentage, with each reset as a concrete local time (`13:47` today, `Fri 15:00` this week, `Sep 01` later).
+The footer shows how much you have used; the panel shows what is left, as a meter and a percentage, with each reset as a concrete local time (`13:47` today, `Fri 15:00` this week, `Sep 01` later). The panel never waits on the network: whatever is cached renders the moment you press Enter — old numbers carry a `~`, missing ones read `fetching…` — and a second panel replaces it once the refreshed numbers land.
 
 ## Supported providers
 
@@ -86,8 +86,9 @@ Custom providers work without configuration too: detection falls back to the mod
 
 ## Good to know
 
-- Numbers refresh at most every five minutes; countdowns tick every minute without touching the network.
-- A failed refresh never breaks anything: the last numbers stay, marked `~`, until the next success — and `/quota` says why a provider failed (`quota unavailable (HTTP 401)`).
+- Numbers refresh while you work — on model switches and on every agent run — but at most once every five minutes per provider; an idle session, mode `off`, and non-TUI sessions (RPC, JSON) send no requests at all.
+- Each provider endpoint is asked at most once per minute, machine-wide: every attempt (even a failed one) persists its timestamp in the shared cache before the request starts, so several pi sessions keep their distance too. A failed request earns a single immediate retry inside its cycle; when a fetch keeps failing, the `/quota` panel says so on the provider's own line — never as an interrupting notification.
+- A failed refresh never breaks anything: the last numbers stay, marked `~`, until the next success — and `/quota` says why a provider failed (`quota unavailable (HTTP 401)`) or when it will retry (`retry in 42s`).
 - Several pi sessions on the same machine share one cache safely.
 - A lapsed Kimi OAuth token is skipped with a note — it refreshes the next time pi itself calls Kimi.
 - Credentials come only from pi's own store; no environment variables are read, and a key can never be sent to the wrong host.

package/cache.ts

@@ -11,6 +11,12 @@ export const CACHE_VERSION = 2;
 export interface QuotaCacheFile {
 	version: number;
 	snapshots: Partial<Record<ProviderKind, QuotaSnapshot>>;
+	/**
+	 * Last fetch attempt per provider, in ms epoch. Persisted — not kept in
+	 * memory — so every pi session on the machine shares one rate limit and a
+	 * failing endpoint is retried at most once per interval machine-wide.
+	 */
+	lastRequests?: Partial<Record<ProviderKind, number>>;
 }
 
 export function emptyCache(): QuotaCacheFile {
@@ -84,7 +90,7 @@ export function parseCache(text: string | undefined): QuotaCacheFile {
 	try {
 		const raw: unknown = JSON.parse(text);
 		if (typeof raw !== "object" || raw === null) return emptyCache();
-		const file = raw as { version?: unknown; snapshots?: unknown };
+		const file = raw as { version?: unknown; snapshots?: unknown; lastRequests?: unknown };
 		if (file.version !== CACHE_VERSION || typeof file.snapshots !== "object" || file.snapshots === null) {
 			return emptyCache();
 		}
@@ -94,7 +100,19 @@ export function parseCache(text: string | undefined): QuotaCacheFile {
 				snapshots[kind as ProviderKind] = snapshot;
 			}
 		}
-		return { version: CACHE_VERSION, snapshots };
+		// Attempt times drive the request rate limit; an invalid entry simply
+		// does not limit — it must never block parsing of the snapshots.
+		const lastRequests: Partial<Record<ProviderKind, number>> = {};
+		if (typeof file.lastRequests === "object" && file.lastRequests !== null) {
+			for (const [kind, at] of Object.entries(file.lastRequests)) {
+				if ((PROVIDER_KINDS as readonly string[]).includes(kind) && typeof at === "number" && Number.isFinite(at)) {
+					lastRequests[kind as ProviderKind] = at;
+				}
+			}
+		}
+		const cache: QuotaCacheFile = { version: CACHE_VERSION, snapshots };
+		if (Object.keys(lastRequests).length > 0) cache.lastRequests = lastRequests;
+		return cache;
 	} catch {
 		return emptyCache();
 	}
@@ -125,3 +143,8 @@ export function isNewerCacheFile(text: string | undefined): boolean {
 export function freshSnapshot(snapshot: QuotaSnapshot | undefined, now: number, ttlMs: number): snapshot is QuotaSnapshot {
 	return snapshot !== undefined && now - snapshot.fetchedAt < ttlMs;
 }
+
+/** True when a request may be sent: none was recorded, or the minimum interval since the last attempt has passed. */
+export function requestDue(lastRequestAt: number | undefined, now: number, minIntervalMs: number): boolean {
+	return lastRequestAt === undefined || now - lastRequestAt >= minIntervalMs;
+}

package/index.ts

@@ -20,10 +20,25 @@
  * quota provider is active and a snapshot with at least one item exists.
  * With no data at all (missing API key, empty cache, failed fetch) — and in
  * off mode, or after switching to a provider without quota — the built-in
- * footer stays completely untouched. Snapshots are fetched at most every
- * five minutes, cached in `<agent-dir>/quota-cache.json`, and when a
- * refresh fails the last snapshot is kept with a warning `~` prefix until a
- * fetch succeeds again.
+ * footer stays completely untouched. Snapshots live in
+ * `<agent-dir>/quota-cache.json` with a five-minute TTL, shared (and
+ * written atomically) by every pi session on the machine.
+ *
+ * Fetches never run on a wall clock; they happen on demand and on activity:
+ *   - `/quota` renders every configured provider from cache instantly —
+ *     stale snapshots keep their numbers behind a `~` — then refreshes the
+ *     stale ones in the background and re-renders once when data landed;
+ *   - `/quota refresh` force-refreshes the active provider;
+ *   - agent runs (`agent_start` / `agent_end`) and model switches refresh
+ *     the active provider, TTL-gated — an idle session, mode off, and
+ *     non-TUI sessions (RPC, JSON, print) send no requests at all.
+ * Each provider endpoint is asked at most once per minute machine-wide:
+ * every attempt, successful or not, persists `lastRequests` in the cache
+ * file before the request starts, so concurrent sessions and failing
+ * endpoints keep their distance too (a failed request earns one immediate
+ * retry inside its cycle). When a refresh fails, the last snapshot is kept
+ * with a warning `~` prefix, and the failure itself is explained inside the
+ * /quota panel — never as an interrupting notification.
  *
  * Display modes (persisted in `<agent-dir>/quota-settings.json`):
  *   line     dedicated quota line under the stats with labeled meters and
@@ -33,8 +48,9 @@
  *   off      restore the built-in footer entirely
  *
  * Commands:
- *   /quota             show quota for every configured provider
- *   /quota refresh     force a re-fetch for the active provider
+ *   /quota             cached quota for every configured provider, instantly;
+ *                     refreshed in the background and re-rendered when done
+ *   /quota refresh     force a re-fetch for the active provider (once per minute at most)
  *   /quota mode line|inline|off  change display mode (persisted)
  *   /quota help        list options
  */
@@ -44,15 +60,34 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import { emptyCache, freshSnapshot, isNewerCacheFile, parseCache, type QuotaCacheFile, serializeCache } from "./cache.ts";
+import {
+	emptyCache,
+	freshSnapshot,
+	isNewerCacheFile,
+	parseCache,
+	type QuotaCacheFile,
+	requestDue,
+	serializeCache,
+} from "./cache.ts";
 import { createQuotaFooter } from "./footer.ts";
-import { configuredQuotaProviders, detectProvider, type QuotaProvider, type QuotaSnapshot } from "./providers/index.ts";
+import {
+	type ConfiguredQuotaProvider,
+	configuredQuotaProviders,
+	detectProvider,
+	type ProviderKind,
+	type QuotaProvider,
+	type QuotaSnapshot,
+} from "./providers/index.ts";
 import { DEFAULT_MODE, MODES, parseSettings, type QuotaMode, serializeSettings } from "./settings.ts";
 import { formatQuota, formatQuotaPanel, type QuotaPanelRow } from "./view.ts";
 
 const CACHE_TTL_MS = 300_000;
 const TICK_MS = 60_000;
 const FETCH_TIMEOUT_MS = 8000;
+/** No provider endpoint is asked more often than this, machine-wide. */
+const MIN_REQUEST_INTERVAL_MS = 60_000;
+/** Pause before the single retry a failed fetch earns inside its cycle. */
+const FETCH_RETRY_DELAY_MS = 500;
 
 /** The model fields detection needs; structurally compatible with pi's Model. */
 interface ActiveModel {
@@ -67,6 +102,19 @@ let activeProviderId: string | undefined;
 let activeBaseUrl: string | undefined;
 let currentMode: QuotaMode | undefined;
 let refreshing = false;
+/**
+ * Serializes refresh cycles end-to-end: a call that arrives while a cycle is
+ * open waits for it and then runs its own. A manual /quota refresh can then
+ * never be dropped by (or interleave with) the boot or activity refresh — it
+ * queues behind it and reports the machine-wide rate limit instead of racing.
+ */
+let refreshQueue: Promise<void> = Promise.resolve();
+/**
+ * Last fetch failure per provider, remembered for the /quota panel: it
+ * explains missing-or-stale numbers on the panel's own surface until a
+ * fetch succeeds again, instead of interrupting the user with a notification.
+ */
+const lastErrors = new Map<ProviderKind, { message: string; at: number }>();
 /** True when the shown snapshot predates a failed refresh. */
 let stale = false;
 let currentSnapshot: QuotaSnapshot | undefined;
@@ -75,6 +123,8 @@ let footerInstalled = false;
 let activeCtx: ExtensionContext | undefined;
 /** Listeners notified whenever the snapshot, staleness, or mode changes (footer re-renders). */
 const snapshotListeners = new Set<() => void>();
+/** Last fetch attempt per provider in this process — the cache file shares them across sessions. */
+const lastAttempts = new Map<ProviderKind, number>();
 
 function publishSnapshot(): void {
 	for (const listener of snapshotListeners) listener();
@@ -91,11 +141,19 @@ function oauthExpired(entry: unknown): boolean {
 	return typeof expires === "number" && expires <= Date.now() + 30_000;
 }
 
+/** True when the auth entry carries a credential a fetch could use: an unexpired OAuth access token or an API key. */
+function hasUsableCredential(entry: unknown): boolean {
+	if (typeof entry !== "object" || entry === null) return false;
+	if (oauthExpired(entry)) return false;
+	const { access, key } = entry as { access?: unknown; key?: unknown };
+	return typeof (access ?? key) === "string";
+}
+
 /**
  * Read the credential for a provider from pi's auth.json: the OAuth access
  * token (`access`) for OAuth providers such as kimi-coding, the API `key`
  * otherwise. The file is re-read on every fetch so a token pi refreshed
- * mid-session is picked up on the next tick. A lapsed OAuth token counts as
+ * mid-session is picked up on the next request. A lapsed OAuth token counts as
  * no credential — pi only refreshes it when it calls the provider itself,
  * so requesting with it would be a guaranteed 401.
  */
@@ -152,8 +210,23 @@ async function saveMode(mode: QuotaMode): Promise<void> {
 	publishSnapshot();
 }
 
-/** Read-modify-write with a rename, so concurrent pi sessions never read a torn file. */
-async function writeCacheSnapshot(snapshot: QuotaSnapshot): Promise<void> {
+/** The cache write in flight, if any; in-process writers queue behind it. */
+let cacheWriteChain: Promise<void> = Promise.resolve();
+
+/**
+ * Read-modify-write with a rename, so concurrent pi sessions never read a
+ * torn file. Writes are serialized in-process first: the /quota panel
+ * refreshes several providers in parallel, and two interleaved
+ * read-modify-write cycles would silently drop whichever update renamed
+ * first. performCacheWrite never rejects, so the chain cannot break.
+ */
+async function writeCacheFile(update: (cache: QuotaCacheFile) => void): Promise<void> {
+	const write = cacheWriteChain.then(() => performCacheWrite(update));
+	cacheWriteChain = write;
+	await write;
+}
+
+async function performCacheWrite(update: (cache: QuotaCacheFile) => void): Promise<void> {
 	const path = join(agentDir(), "quota-cache.json");
 	try {
 		const text = await readFile(path, "utf8").catch(() => undefined);
@@ -161,7 +234,7 @@ async function writeCacheSnapshot(snapshot: QuotaSnapshot): Promise<void> {
 		// this version would silently discard whatever that format stored.
 		if (isNewerCacheFile(text)) return;
 		const cache = parseCache(text);
-		cache.snapshots[snapshot.kind] = snapshot;
+		update(cache);
 		// A unique tmp name per writer: two sessions sharing one fixed tmp path
 		// could interleave writes into the same file and rename a torn result.
 		const tmp = `${path}.${process.pid}-${Math.random().toString(36).slice(2)}.tmp`;
@@ -172,34 +245,136 @@ async function writeCacheSnapshot(snapshot: QuotaSnapshot): Promise<void> {
 	}
 }
 
-async function fetchSnapshot(
-	provider: QuotaProvider,
-	providerId: string | undefined,
-	baseUrl?: string,
-): Promise<QuotaSnapshot | undefined> {
-	// Credentials come exclusively from pi's auth.json: the same credential pi
-	// itself runs the provider with, so a matched provider always has its key
-	// and no environment fallback can pair a key with a foreign host.
+/** Store a fetched snapshot, keeping every other provider's data and attempt times. */
+async function writeCacheSnapshot(snapshot: QuotaSnapshot): Promise<void> {
+	await writeCacheFile((cache) => {
+		cache.snapshots[snapshot.kind] = snapshot;
+	});
+}
+
+/** Persist a fetch-attempt time so every pi session on the machine shares one rate limit. */
+async function writeCacheLastRequest(kind: ProviderKind, now: number): Promise<void> {
+	await writeCacheFile((cache) => {
+		cache.lastRequests = { ...cache.lastRequests, [kind]: now };
+	});
+}
+
+/** One provider's fetch outcome, including why no fresh data arrived. */
+type FetchOutcome =
+	| { status: "fetched"; snapshot: QuotaSnapshot }
+	| { status: "limited" }
+	| { status: "no-credential" }
+	| { status: "error"; message: string };
+
+/**
+ * Reserve the next request slot for a provider: true when at least
+ * MIN_REQUEST_INTERVAL_MS has passed since any session last attempted a
+ * fetch. The attempt time is persisted before the request starts, so even
+ * concurrent sessions and failing endpoints keep at least a minute between
+ * attempts machine-wide. Two bounded excesses remain: a read-write race can
+ * admit one duplicate reservation, and a failed attempt earns one immediate
+ * in-cycle retry — both are extra status requests only, never data ones.
+ */
+async function reserveFetchSlot(kind: ProviderKind): Promise<boolean> {
+	const now = Date.now();
+	const local = lastAttempts.get(kind);
+	if (local !== undefined && !requestDue(local, now, MIN_REQUEST_INTERVAL_MS)) return false;
+	const persisted = (await readCacheFile()).lastRequests?.[kind];
+	if (typeof persisted === "number" && !requestDue(persisted, now, MIN_REQUEST_INTERVAL_MS)) {
+		// Adopt the other session's timestamp so this process counts down from it.
+		lastAttempts.set(kind, Math.max(persisted, local ?? 0));
+		return false;
+	}
+	lastAttempts.set(kind, now);
+	await writeCacheLastRequest(kind, now);
+	return true;
+}
+
+/**
+ * Fetch one provider's quota and cache the snapshot, honoring the
+ * machine-wide request interval. Credentials come exclusively from pi's
+ * auth.json: the same credential pi itself runs the provider with, so no
+ * environment fallback can pair a key with a foreign host.
+ */
+async function fetchAndCache(provider: QuotaProvider, providerId: string | undefined, baseUrl?: string): Promise<FetchOutcome> {
 	const apiKey = await readAuthKey(providerId);
-	if (!apiKey) return undefined;
-	return provider.fetchQuota(apiKey, { now: Date.now, timeoutMs: FETCH_TIMEOUT_MS, baseUrl });
+	if (!apiKey) return { status: "no-credential" };
+	if (!(await reserveFetchSlot(provider.kind))) return { status: "limited" };
+	// One retry: quota endpoints blip (5xx, connection resets) and a single
+	// immediate re-request usually clears it. The slot this cycle reserved
+	// covers both tries, so the machine-wide interval still bounds the pair.
+	for (let attempt = 0; ; attempt++) {
+		try {
+			const snapshot = await provider.fetchQuota(apiKey, { now: Date.now, timeoutMs: FETCH_TIMEOUT_MS, baseUrl });
+			lastErrors.delete(provider.kind);
+			await writeCacheSnapshot(snapshot);
+			return { status: "fetched", snapshot };
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			if (attempt < 1) {
+				await new Promise((resolve) => setTimeout(resolve, FETCH_RETRY_DELAY_MS));
+				continue;
+			}
+			// Expected while offline or on provider errors: keep showing the
+			// last snapshot; the /quota panel explains the outage on its own surface.
+			lastErrors.set(provider.kind, { message, at: Date.now() });
+			return { status: "error", message };
+		}
+	}
 }
 
-async function refresh(force: boolean): Promise<QuotaSnapshot | undefined> {
+/** What a refresh cycle produced for the active provider. */
+interface RefreshResult {
+	/** Latest snapshot for the active provider, from memory or cache. */
+	snapshot?: QuotaSnapshot;
+	/** True when this call brought back fresh numbers. */
+	fetched: boolean;
+	/** True when the request was skipped: some session asked within the last minute. */
+	limited: boolean;
+	/** Set when this cycle's own fetch failed (after its retry); the panel, not a notification, shows it. */
+	error?: string;
+}
+
+function refresh(opts: { force?: boolean } = {}): Promise<RefreshResult> {
+	// Capture the active provider here, not when the queued cycle starts: a
+	// model switch between the two would pair the cycle with the wrong (or no)
+	// provider, and a manual refresh must report the provider it was asked about.
 	const provider = activeProvider;
-	if (!provider || refreshing) return currentSnapshot;
+	if (!provider) return Promise.resolve({ snapshot: currentSnapshot, fetched: false, limited: false });
+	const providerId = activeProviderId;
+	const baseUrl = activeBaseUrl;
+	const cycle = refreshQueue.then(() => runRefreshCycle(provider, providerId, baseUrl, opts));
+	// The queue itself never rejects, or one failed cycle would poison every later one.
+	refreshQueue = cycle.then(
+		() => undefined,
+		() => undefined,
+	);
+	return cycle;
+}
+
+async function runRefreshCycle(
+	provider: QuotaProvider,
+	providerId: string | undefined,
+	baseUrl: string | undefined,
+	opts: { force?: boolean },
+): Promise<RefreshResult> {
 	/** True when the model switched to another provider since this refresh started. */
 	const switchedProvider = () => provider.kind !== activeProvider?.kind;
 	refreshing = true;
+	let fetched = false;
+	let limited = false;
+	let fetchError: string | undefined;
+	/** The snapshot this cycle fetched, if any — reported even when a mid-fetch model switch keeps it out of the footer. */
+	let fetchedSnapshot: QuotaSnapshot | undefined;
 	try {
-		if (!force) {
+		if (!opts.force) {
 			const cached = await readCacheFile().then((cache) => cache.snapshots[provider.kind]);
 			if (!switchedProvider() && freshSnapshot(cached, Date.now(), CACHE_TTL_MS)) {
 				currentSnapshot = cached;
 				stale = false;
 				await syncFooterInstall();
 				publishSnapshot();
-				return currentSnapshot;
+				return { snapshot: currentSnapshot, fetched: false, limited: false, error: undefined };
 			}
 			// Show the last snapshot of any age while a refresh is in flight, so the
 			// footer never waits on the network with nothing to display.
@@ -210,16 +385,12 @@ async function refresh(force: boolean): Promise<QuotaSnapshot | undefined> {
 				publishSnapshot();
 			}
 		}
-		let next: QuotaSnapshot | undefined;
-		try {
-			next = await fetchSnapshot(provider, activeProviderId, activeBaseUrl);
-			if (next) await writeCacheSnapshot(next);
-		} catch {
-			// Expected while offline or on provider errors: keep showing the
-			// last snapshot (marked stale below) instead of logging — pi shows
-			// extension stderr to the user, and a dropped status fetch is not
-			// an error worth interrupting anyone for.
-		}
+		const outcome = await fetchAndCache(provider, providerId, baseUrl);
+		limited = outcome.status === "limited";
+		fetchError = outcome.status === "error" ? outcome.message : undefined;
+		fetchedSnapshot = outcome.status === "fetched" ? outcome.snapshot : undefined;
+		fetched = fetchedSnapshot !== undefined;
+		let next = fetchedSnapshot;
 		// The model switched mid-fetch: the result belongs to the previous
 		// provider and must never bleed into the new provider's prefix.
 		if (next && switchedProvider()) next = undefined;
@@ -231,8 +402,22 @@ async function refresh(force: boolean): Promise<QuotaSnapshot | undefined> {
 			currentSnapshot = await readCacheFile().then((cache) => cache.snapshots[provider.kind]);
 			stale = true;
 		} else if (currentSnapshot) {
-			// Keep showing the last snapshot, marked stale.
-			stale = true;
+			// Keep showing the last snapshot. A failed refresh marks it stale; a
+			// rate-limited or credential-less skip only when it is past the TTL.
+			// A limited skip sent nothing, and this cycle may have waited in the
+			// queue first: another session can have fetched meanwhile, so adopt the
+			// machine-wide cache's snapshot when it is newer than memory. Memory is
+			// captured before the await — sync() can clear currentSnapshot while the
+			// file is read — and the switch is re-checked after it so an old
+			// provider's numbers never bleed into the new one's memory.
+			if (outcome.status === "limited" && !switchedProvider()) {
+				const memory = currentSnapshot;
+				if (memory) {
+					const machine = await readCacheFile().then((cache) => cache.snapshots[provider.kind]);
+					if (machine && machine.fetchedAt > memory.fetchedAt && !switchedProvider()) currentSnapshot = machine;
+				}
+			}
+			stale = outcome.status === "error" || !freshSnapshot(currentSnapshot, Date.now(), CACHE_TTL_MS);
 		}
 		await syncFooterInstall();
 		publishSnapshot();
@@ -241,9 +426,12 @@ async function refresh(force: boolean): Promise<QuotaSnapshot | undefined> {
 	}
 	// A model switch that arrived while this refresh was in flight left its
 	// own sync() call a no-op behind the refreshing guard; catch up for the
-	// new provider immediately instead of waiting for the next tick.
-	if (activeProvider && activeProvider.kind !== provider.kind) void refresh(false).catch(() => {});
-	return currentSnapshot;
+	// new provider immediately instead of waiting for the next activity.
+	if (activeProvider && activeProvider.kind !== provider.kind) void refresh().catch(() => {});
+	// Report what this call produced: the fetched snapshot even when a
+	// mid-fetch model switch kept it out of the footer (describeSnapshot
+	// names its kind), else the active provider's latest from memory.
+	return { snapshot: fetchedSnapshot ?? currentSnapshot, fetched, limited, error: fetchError };
 }
 
 function stopTimer(): void {
@@ -255,13 +443,11 @@ function stopTimer(): void {
 
 function startTimer(): void {
 	if (tickTimer !== undefined) return;
-	// Refresh() reads the cache first, so the tick only hits the network
-	// about once per TTL. Unref'd so the timer never keeps pi alive.
-	tickTimer = setInterval(() => {
-		// Swallow rejections: a status side channel must never surface an
-		// unhandled-rejection crash if a refresh path throws unexpectedly.
-		void refresh(false).catch(() => {});
-	}, TICK_MS);
+	// Render-only tick: countdowns and reset times stay current once a minute
+	// without touching the network — fetches happen on activity (agent runs,
+	// model switches) and on demand (/quota), never on a wall clock. Unref'd
+	// so the timer never keeps pi alive.
+	tickTimer = setInterval(() => publishSnapshot(), TICK_MS);
 	tickTimer.unref?.();
 }
 
@@ -340,15 +526,117 @@ async function sync(ctx: ExtensionContext, model: ActiveModel | undefined): Prom
 		return;
 	}
 	startTimer();
-	void refresh(false).catch(() => {});
+	void refresh().catch(() => {});
+}
+
+/**
+ * Streaming activity (agent run started or finished): the active
+ * subscription's numbers may have moved with the work. Refresh in the
+ * background, TTL- and rate-gated — at most one request per CACHE_TTL_MS
+ * while the session is active, none while it sits idle or displays no
+ * footer (mode off, non-TUI). Never awaited: the agent loop must not
+ * wait on a status fetch.
+ */
+function onAgentActivity(): void {
+	// Off and non-TUI sessions show nothing (the /quota panel fetches on
+	// demand), so a background refresh there would be cost without a viewer.
+	if (currentMode === "off" || (activeCtx !== undefined && activeCtx.mode !== "tui")) return;
+	void refresh().catch(() => {});
+}
+
+/** Short fetch-failure text for the panel; the endpoint is implied by the provider block it belongs to. */
+function panelFetchError(message: string): string {
+	return message.replace(/ from \S+.*$/, "");
 }
 
-/** Load or fetch quota for every configured provider and render the panel. */
-async function describeAllProviders(): Promise<string> {
+/**
+ * One configured provider as a panel row, rendered from cache alone: fresh
+ * snapshots as-is, stale ones with their numbers kept and marked `~`,
+ * missing ones as a note — "fetching…" while a refresh is in flight, the
+ * failure reason or retry countdown after it failed. A remembered failure
+ * rides along with the numbers it explains, so stale data always says why.
+ */
+function panelRow(
+	entry: ConfiguredQuotaProvider,
+	authFile: Record<string, unknown> | undefined,
+	cached: QuotaSnapshot | undefined,
+	opts: { pending: boolean; fetchError?: string; retryInSeconds?: number },
+	now: number,
+): QuotaPanelRow {
+	const row: QuotaPanelRow = {
+		label: entry.providerId,
+		planLabel: entry.provider.planLabel,
+		active: entry.provider.kind === activeProvider?.kind,
+	};
+	if (cached) {
+		// Any age: show the numbers now — old ones marked stale (~), replaced
+		// by the pending refresh when it lands. freshSnapshot is a type guard,
+		// so the age check is inlined to keep `cached` narrowed here.
+		const fresh = now - cached.fetchedAt < CACHE_TTL_MS;
+		const failure = opts.fetchError ? `quota unavailable (${panelFetchError(opts.fetchError)})` : undefined;
+		return fresh
+			? { ...row, planLevel: cached.planLevel, snapshot: cached, note: failure }
+			: { ...row, planLevel: cached.planLevel, snapshot: cached, stale: true, note: failure };
+	}
+	if (opts.pending) return { ...row, note: "fetching…" };
+	if (opts.fetchError) return { ...row, note: `quota unavailable (${panelFetchError(opts.fetchError)})` };
+	if (oauthExpired(authFile?.[entry.providerId])) {
+		return { ...row, note: "oauth token expired; it refreshes the next time pi uses this provider" };
+	}
+	if (opts.retryInSeconds !== undefined) return { ...row, note: `quota unavailable (retry in ${opts.retryInSeconds}s)` };
+	return row;
+}
+
+/** The /quota panel text for one cache state; pending and errors describe an in-flight refresh. */
+function renderPanel(
+	ordered: readonly ConfiguredQuotaProvider[],
+	authFile: Record<string, unknown> | undefined,
+	cache: QuotaCacheFile,
+	pending: ReadonlySet<ProviderKind>,
+	errors: ReadonlyMap<ProviderKind, string>,
+): string {
+	const now = Date.now();
+	const rows = ordered.map((entry): QuotaPanelRow => {
+		const kind = entry.provider.kind;
+		const lastRequestAt = cache.lastRequests?.[kind];
+		// A credential-less provider never fetches, so a recent attempt only
+		// matters as a retry note when a request could follow.
+		const retryInSeconds =
+			pending.has(kind) || !hasUsableCredential(authFile?.[entry.providerId])
+				? undefined
+				: lastRequestAt !== undefined && !requestDue(lastRequestAt, now, MIN_REQUEST_INTERVAL_MS)
+					? Math.ceil((lastRequestAt + MIN_REQUEST_INTERVAL_MS - now) / 1000)
+					: undefined;
+		return panelRow(
+			entry,
+			authFile,
+			cache.snapshots[kind],
+			{
+				pending: pending.has(kind),
+				fetchError: errors.get(kind),
+				retryInSeconds,
+			},
+			now,
+		);
+	});
+	return `${formatQuotaPanel(rows, now)}\n\n/quota refresh · /quota mode line|inline|off · /quota help`;
+}
+
+/**
+ * Show the /quota panel without waiting on the network: the cached state of
+ * every configured provider renders immediately (stale snapshots keep their
+ * numbers behind `~`, missing ones read "fetching…"), then the stale or
+ * missing providers refresh in the background and the panel re-renders
+ * once — unless nothing changed (every fetch failed with only stale
+ * numbers shown, which the first panel already says with its `~` marks).
+ */
+async function showQuotaPanel(ctx: ExtensionContext): Promise<void> {
 	const authFile = await readAuthFile();
 	const configured = configuredQuotaProviders(authFile);
-	if (configured.length === 0) return "no quota providers configured";
-	const cache = await readCacheFile();
+	if (configured.length === 0) {
+		ctx.ui.notify("no quota providers configured", "info");
+		return;
+	}
 	// Active provider first, the rest alphabetical by display label —
 	// predictable and stable, independent of auth.json key order.
 	const ordered = [...configured].sort((a, b) => {
@@ -356,47 +644,67 @@ async function describeAllProviders(): Promise<string> {
 		if (b.provider.kind === activeProvider?.kind) return 1;
 		return a.providerId < b.providerId ? -1 : a.providerId > b.providerId ? 1 : 0;
 	});
-	const rows = await Promise.all(
-		ordered.map(async (entry): Promise<QuotaPanelRow> => {
-			const { provider } = entry;
-			const row: QuotaPanelRow = {
-				label: entry.providerId,
-				planLabel: provider.planLabel,
-				active: provider.kind === activeProvider?.kind,
-			};
-			const cached = cache.snapshots[provider.kind];
-			let snapshot: QuotaSnapshot | undefined;
-			let stale = false;
-			let fetchError: string | undefined;
-			if (freshSnapshot(cached, Date.now(), CACHE_TTL_MS)) {
-				snapshot = cached;
-			} else {
-				try {
-					snapshot = await fetchSnapshot(provider, entry.providerId);
-				} catch (error) {
-					// Keep the reason short: the panel is narrow, and the endpoint
-					// is implied by the provider block it belongs to.
-					fetchError = error instanceof Error ? error.message.replace(/ from \S+.*$/, "") : String(error);
-				}
-				if (snapshot) {
-					await writeCacheSnapshot(snapshot);
-				} else if (cached) {
-					// Fetch failed: fall back to the cached snapshot of any age, marked stale.
-					snapshot = cached;
-					stale = true;
-				}
-			}
-			const note = !snapshot
-				? fetchError
-					? `quota unavailable (${fetchError})`
-					: oauthExpired(authFile?.[entry.providerId])
-						? "oauth token expired; it refreshes the next time pi uses this provider"
-						: undefined
-				: undefined;
-			return { ...row, planLevel: snapshot?.planLevel, snapshot, stale, note };
+	const cache = await readCacheFile();
+	const now = Date.now();
+	// A remembered failure explains missing-or-stale numbers for its provider
+	// until fresher data lands; fetch errors belong on this panel, nowhere else.
+	const rememberedErrors = (snapshots: QuotaCacheFile["snapshots"]): Map<ProviderKind, string> => {
+		const remembered = new Map<ProviderKind, string>();
+		for (const entry of ordered) {
+			const failure = lastErrors.get(entry.provider.kind);
+			if (!failure) continue;
+			const snapshot = snapshots[entry.provider.kind];
+			if (!snapshot || snapshot.fetchedAt < failure.at) remembered.set(entry.provider.kind, failure.message);
+		}
+		return remembered;
+	};
+	// Providers needing a fetch: a stale-or-missing snapshot, a usable
+	// credential, and the machine-wide request interval elapsed. The rate
+	// limit itself lives in fetchAndCache; this only keeps the first render
+	// honest about what is about to happen.
+	const due = ordered.filter(
+		(entry) =>
+			!freshSnapshot(cache.snapshots[entry.provider.kind], now, CACHE_TTL_MS) &&
+			hasUsableCredential(authFile?.[entry.providerId]) &&
+			requestDue(cache.lastRequests?.[entry.provider.kind], now, MIN_REQUEST_INTERVAL_MS),
+	);
+	const first = renderPanel(
+		ordered,
+		authFile,
+		cache,
+		new Set(due.map((entry) => entry.provider.kind)),
+		rememberedErrors(cache.snapshots),
+	);
+	ctx.ui.notify(first, "info");
+	if (due.length === 0) return;
+	const errors = new Map<ProviderKind, string>();
+	await Promise.allSettled(
+		due.map(async (entry) => {
+			// The active provider keeps its regional base URL; the rest use
+			// their default endpoint.
+			const baseUrl = entry.provider.kind === activeProvider?.kind ? activeBaseUrl : undefined;
+			const outcome = await fetchAndCache(entry.provider, entry.providerId, baseUrl);
+			if (outcome.status === "error") errors.set(entry.provider.kind, outcome.message);
 		}),
 	);
-	return `${formatQuotaPanel(rows, Date.now())}\n\n/quota refresh · /quota mode line|inline|off · /quota help`;
+	const refreshed = await readCacheFile();
+	// This pass's own errors win; remembered ones fill in every other provider.
+	for (const [kind, message] of rememberedErrors(refreshed.snapshots)) {
+		if (!errors.has(kind)) errors.set(kind, message);
+	}
+	// A fresh snapshot for the active provider also updates the footer —
+	// unless an activity refresh is mid-flight, which owns that state.
+	if (!refreshing && activeProvider) {
+		const activeCached = refreshed.snapshots[activeProvider.kind];
+		if (activeCached && freshSnapshot(activeCached, Date.now(), CACHE_TTL_MS)) {
+			currentSnapshot = activeCached;
+			stale = false;
+			await syncFooterInstall();
+			publishSnapshot();
+		}
+	}
+	const second = renderPanel(ordered, authFile, refreshed, new Set(), errors);
+	if (second !== first) ctx.ui.notify(second, "info");
 }
 
 function describeSnapshot(snapshot: QuotaSnapshot | undefined): string {
@@ -408,7 +716,7 @@ function describeSnapshot(snapshot: QuotaSnapshot | undefined): string {
 
 /** Sub-command hints for /quota autocompletion. */
 const SUBCOMMANDS: { value: string; label: string; description: string }[] = [
-	{ value: "refresh", label: "refresh", description: "force a re-fetch for the active provider" },
+	{ value: "refresh", label: "refresh", description: "force a re-fetch for the active provider (once per minute at most)" },
 	{ value: "mode", label: "mode", description: "switch display mode (line, inline, off)" },
 	{ value: "help", label: "help", description: "show usage" },
 ];
@@ -432,6 +740,10 @@ export default function (pi: ExtensionAPI): void {
 	pi.on("model_select", async (event, ctx) => {
 		await sync(ctx, event.model);
 	});
+	// Run boundaries are the activity signal: refreshes ride on real work
+	// instead of a wall clock, so an idle session sends no requests at all.
+	pi.on("agent_start", onAgentActivity);
+	pi.on("agent_end", onAgentActivity);
 	pi.on("session_shutdown", () => {
 		// The runtime is about to be torn down (quit, /reload, session
 		// replacement): stop the tick timer so a reused module instance never
@@ -460,14 +772,26 @@ export default function (pi: ExtensionAPI): void {
 		handler: async (args, ctx) => {
 			const [sub, arg] = args.trim().toLowerCase().split(/\s+/);
 			if (sub === "refresh") {
-				if (refreshing) {
-					ctx.ui.notify("Quota: a refresh is already in progress", "info");
+				// Cycles are serialized, so a manual refresh waits for any
+				// in-flight one and then runs — and reports the rate limit — itself.
+				const result = await refresh({ force: true });
+				// A failed fetch is not worth interrupting anyone: the /quota panel
+				// explains the outage on its own surface, with the numbers it has.
+				if (result.error !== undefined) {
+					await showQuotaPanel(ctx);
+					return;
+				}
+				// Without a credential there is nothing to fetch; and without data
+				// or a rate-limit skip, nothing worth reporting either.
+				if (!result.fetched && !result.limited) {
+					ctx.ui.notify("Quota: nothing to refresh", "warning");
 					return;
 				}
-				const snapshot = await refresh(true);
 				ctx.ui.notify(
-					snapshot ? `Quota refreshed: ${describeSnapshot(snapshot)}` : "Quota: nothing to refresh",
-					snapshot ? "info" : "warning",
+					result.fetched
+						? `Quota refreshed: ${describeSnapshot(result.snapshot)}`
+						: `Quota: requested within the last minute — ${describeSnapshot(result.snapshot)}`,
+					"info",
 				);
 				return;
 			}
@@ -495,8 +819,9 @@ export default function (pi: ExtensionAPI): void {
 				);
 				return;
 			}
-			// No argument (or anything unrecognized): show every configured provider.
-			ctx.ui.notify(await describeAllProviders(), "info");
+			// No argument (or anything unrecognized): cached numbers instantly,
+			// refreshed in the background and re-rendered when they land.
+			await showQuotaPanel(ctx);
 		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sub-quota",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Coding-plan quota and prepaid balance in the pi footer, shown only while a subscription provider such as ZAI/GLM, DeepSeek, or Kimi is active",
   "keywords": [
     "pi-package",

package/view.ts

@@ -316,11 +316,7 @@ export function formatQuotaPanel(rows: QuotaPanelRow[], now: number): string {
 				.filter(Boolean)
 				.join(" · ");
 			const lines = [`${row.stale ? "~" : ""}${row.label}  ${header}`];
-			if (row.note) {
-				lines.push(`  ${row.note}`);
-			} else if (!snapshot) {
-				lines.push("  quota unavailable");
-			} else {
+			if (snapshot) {
 				for (const window of windowItems(snapshot)) {
 					const left = 100 - window.usedPercent;
 					const reset =
@@ -334,6 +330,13 @@ export function formatQuotaPanel(rows: QuotaPanelRow[], now: number): string {
 					}
 				}
 			}
+			// A note rides along below the numbers it explains; only a row with
+			// neither snapshot nor note falls back to the bare unavailability line.
+			if (row.note) {
+				lines.push(`  ${row.note}`);
+			} else if (!snapshot) {
+				lines.push("  quota unavailable");
+			}
 			return lines.join("\n");
 		})
 		.join("\n\n");