@cad0p/pi-usage 0.11.5 → 0.11.6-20261107.0

package/extensions/quota-panel.ts

@@ -26,14 +26,26 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-// `mergeLastGood` is intentionally NOT imported here: it lives in src/sticky.js
-// and the CLI (`bin/piquota.js`) already applies it on every `--json` run, so the
-// extension sees a report whose transiently-failed families already carry the last
-// good snapshot in `provider.note`. The classifier below mirrors src/providers/error-kind.js
-// so the extension can render category-specific glyphs without depending on the repo.
+import { extractChatGptAccountId, extractExpiresAtMs } from "../src/auth/jwt.js";
+import { mergeReportIntoCache, writeCache } from "../src/cache.js";
+import { normalizeClaudeSourceMode, collectFamily, enabledFamilies, FAMILIES } from "../src/engine.js";
+import { historyJson } from "../src/cli/commands/stats.js";
+import { resolveHistoryDir } from "../src/local/history.js";
+import { startLocalStatsWorker } from "../src/local/worker.js";
+import { publishRecords } from "../src/omarchy/publish.js";
+import { buildRecords } from "../src/omarchy/record.js";
+import { skippedFamilies } from "../src/cli/commands/omarchy.js";
+import { isKeyRelease, matchesKey, matchesPrintable } from "../src/overlay-keys.js";
+import { mergeLastGood } from "../src/sticky.js";
+import { readRefreshState, resolveFamilyTtls, staleFamilies, writeRefreshState } from "../src/refresh.js";
+
+// The in-process collector does not pass through the CLI's sticky layer, so this
+// extension applies the same last-good merge as the CLI before painting or publishing.
+// The classifier below mirrors src/providers/error-kind.js so the extension can
+// render category-specific glyphs without depending on the repo.
 
 const STATUS_KEY = "00-quota";
 const WIDGET_KEY = "quota-line";
@@ -42,7 +54,12 @@ const RAIL_KEY = "quota";
 const SIDEBAR_STATE_KEY = Symbol.for("gentle-pi.experimental-sidebar.state");
 const REFRESH_MS = Number(process.env.PI_QUOTA_REFRESH_MS) || 300_000;
 const AGENT_END_DEBOUNCE_MS = 1_500;
-const EXEC_TIMEOUT_MS = 30_000;
+/** The report cache is keyed by the Claude source its numbers came from. */
+const CLAUDE_SOURCE_CACHE_PREFIX = "claude-source:";
+
+function cacheKeyFor(source: string): string {
+  return `${CLAUDE_SOURCE_CACHE_PREFIX}${normalizeClaudeSourceMode(source)}`;
+}
 
 type QuotaWindow = {
   id: string;
@@ -124,9 +141,32 @@ type Theme = {
   bg?: (key: string, text: string) => string;
 };
 
+/**
+ * One running local token scan. It is a handle, not a promise, because the scan
+ * can outlive the session that started it: a shutdown has to be able to end it
+ * and have its lock and cache left clean.
+ */
+type LocalStatsScan = {
+  result: Promise<{ byFamily: Record<string, LocalFamilyStats>; warnings: string[]; scan: { partial?: boolean } | null }>;
+  stop: () => Promise<void>;
+};
+
+type ExtensionDependencies = {
+  collectFamily?: typeof collectFamily;
+  startLocalStats?: () => LocalStatsScan;
+  getProviderAuth?: (ctx: UiContext, provider: string) => Promise<{ auth?: { apiKey?: string }; accountId?: string; source?: string } | undefined>;
+  loadHistory?: (month: string | null) => Promise<HistoryPayload> | HistoryPayload;
+  publishOmarchy?: (report: QuotaReport, prune: boolean) => void;
+  railPatcherPath?: string;
+};
+
 /** Only the UI surface this extension uses. */
 type UiContext = {
   hasUI: boolean;
+  /** Pi resolves/renews its OAuth credentials under its own auth-store lock. */
+  modelRegistry?: {
+    getProviderAuth?: (provider: string) => Promise<{ auth?: { apiKey?: string }; source?: string } | undefined>;
+  };
   /** Pi's run mode; `custom` components only exist in the TUI. */
   mode?: string;
   ui: {
@@ -147,6 +187,7 @@ const BRAND: Record<string, string> = {
   codex: "#10A37F",
   antigravity: "#4285F4",
   "opencode-go": "#007AFF",
+  mistral: "#FA520F",
   "github-actions": "#2088FF",
 };
 
@@ -156,6 +197,7 @@ const SHORT_NAME: Record<string, string> = {
   codex: "Codex",
   antigravity: "Agy",
   "opencode-go": "OP-Go",
+  mistral: "Mistral",
   "github-actions": "GH",
 };
 
@@ -193,23 +235,7 @@ function usedOf(window: QuotaWindow | null): number | null {
   return null;
 }
 
-function resolveCliPath(): string | null {
-  const override = process.env.PI_QUOTA_BIN;
-  if (override && existsSync(override)) return override;
-  try {
-    const sibling = fileURLToPath(new URL("../bin/piquota.js", import.meta.url));
-    if (existsSync(sibling)) return sibling;
-  } catch {}
-  for (const candidate of [
-    join(homedir(), ".local", "share", "pi-quota", "bin", "piquota.js"),
-    join(homedir(), ".local", "bin", "piquota"),
-    join(homedir(), ".pi", "agent", "npm", "node_modules", "@cad0p", "pi-usage", "bin", "piquota.js"),
-    join(homedir(), ".pi", "agent", "npm", "node_modules", "@j3pf", "piquota", "bin", "piquota.js"),
-  ]) {
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
-}
+
 
 /**
  * Rank by how soon a window constrains you: 5h/session first, then daily,
@@ -445,6 +471,9 @@ export function renderBox(report: QuotaReport, theme: Theme, totalWidth?: number
     { label: "Agy C/G:", color: "#7AA2F7", ...windowFor("antigravity", (window) => window.id === "claude-gpt-5h" || (/(claude|gpt|3p)/i.test(window.id) && isFiveHour(window))) },
     { label: "OP-Go:  ", color: "#007AFF", ...windowFor("opencode-go", isFiveHour) },
   ];
+  if (providerFor("mistral") && providerFor("mistral")?.notConfigured !== true) {
+    rows.push({ label: "Mistral:", color: "#FA520F", ...windowFor("mistral", (window) => window.id === "vibe") });
+  }
   if (providerFor("github-actions")) {
     rows.push({ label: "GH Actions:", color: "#2088FF", ...windowFor("github-actions", (window) => window.id === "monthly") });
   }
@@ -494,6 +523,9 @@ function renderSidebarCard(report: QuotaReport | null, theme: Theme, width: numb
         { label: "Agy:    ", color: "#4285F4", ...windowFor("antigravity", (window) => window.id === "gemini-5h" || (/gemini/i.test(window.id) && isFiveHour(window))) },
         { label: "Agy C/G:", color: "#7AA2F7", ...windowFor("antigravity", (window) => window.id === "claude-gpt-5h" || (/(claude|gpt|3p)/i.test(window.id) && isFiveHour(window))) },
         { label: "OP-Go:  ", color: "#007AFF", ...windowFor("opencode-go", isFiveHour) },
+        ...(providerFor("mistral") && providerFor("mistral")?.notConfigured !== true
+          ? [{ label: "Mistral:", color: "#FA520F", ...windowFor("mistral", (window) => window.id === "vibe") }]
+          : []),
         ...(providerFor("github-actions")
           ? [{ label: "GH Actions:", color: "#2088FF", ...windowFor("github-actions", (window) => window.id === "monthly") }]
           : []),
@@ -940,27 +972,6 @@ function renderPanel(report: QuotaReport, theme: Theme): string[] {
   return [...sections.flatMap((section) => [section.header, ...section.body]), ...tail];
 }
 
-/**
- * Raw input sequences for the keys the overlay turns into actions. The
- * extension ships as one file with no runtime dependencies, so this mirrors
- * the subset of pi-tui's matchesKey() the overlay needs: arrows, paging and
- * home/end in the encodings terminals and tmux actually send.
- */
-const KEY_SEQUENCES: Record<string, string[]> = {
-  up: ["\u001b[A", "\u001bOA"],
-  down: ["\u001b[B", "\u001bOB"],
-  left: ["\u001b[D", "\u001bOD"],
-  right: ["\u001b[C", "\u001bOC"],
-  pageUp: ["\u001b[5~", "\u001b[[5~"],
-  pageDown: ["\u001b[6~", "\u001b[[6~"],
-  home: ["\u001b[H", "\u001bOH", "\u001b[1~", "\u001b[7~"],
-  end: ["\u001b[F", "\u001bOF", "\u001b[4~", "\u001b[8~"],
-};
-
-function isKey(data: string, name: string): boolean {
-  return (KEY_SEQUENCES[name] ?? []).includes(data);
-}
-
 /** Pi reports the terminal height as a number; fall back to a usable frame. */
 function terminalRows(value: number | undefined): number {
   return Number.isFinite(value) ? Math.max(1, Math.floor(value as number)) : 24;
@@ -1036,9 +1047,33 @@ type HistoryFamily = {
   models: Map<string, number>;
   accounts: Map<string, { tokens: number; prompts: number; models: Map<string, number> }>;
   allTime: number;
-  allTimeAccounts: Map<string, number>;
+  allTimePrompts: number;
+  allTimeAccounts: Map<string, { tokens: number; prompts: number }>;
+  /** The live day's delta, added to both the month and the all-time figures. */
+  liveTokens: number;
+  livePrompts: number;
+  liveAccounts: Map<string, { tokens: number; prompts: number }>;
 };
 
+/** An all-time figure, and whether the rollup behind it lags the month on screen. */
+type AllTimeFigure = { value: number; lags: boolean };
+
+/**
+ * The all-time figure for one scope. All time contains every frozen day, so it
+ * can never be smaller than a month of it: a smaller rollup means totals.json is
+ * behind the month file — a freeze whose totals write failed, a month restored
+ * behind the rollup. That is printed, dimmed and with a note, never hidden: the
+ * figure is the only answer to "how much has this burned ever", and dropping it
+ * silently is a worse lie than a number with a caveat.
+ */
+function allTimeFigure(month: number, allTime: number): AllTimeFigure {
+  if (allTime <= 0) return { value: 0, lags: false };
+  return { value: allTime, lags: allTime < month };
+}
+
+/** The note printed with an all-time figure that cannot cover the month on screen. */
+const ALL_TIME_LAGS_NOTE = "all-time lags this month; run piquota stats --rebuild-totals";
+
 /**
  * What outlives one overlay instance. Every bare `/usage` builds a fresh view,
  * so the folds and the page it was closed on live in the extension — for the pi
@@ -1080,15 +1115,19 @@ type UsageOverlayOptions = {
   getRows: () => number;
   /** The newest report the extension holds, or null before the first one. */
   getReport: () => QuotaReport | null;
-  /** The last refresh failure, shown as a line instead of thrown. */
-  getError: () => string | null;
+  /**
+   * Every family's refresh failure, one line each, in family order. A failure
+   * is not cleared by another family's success: the families finish out of
+   * order, and a single shared slot made the last arrival erase the others.
+   */
+  getErrors: () => string[];
   isRefreshing: () => boolean;
   /** Run the same forced refresh `/usage` always ran, in the background. */
   refresh: () => void;
   /**
-   * Ask the extension to run `piquota stats --json` for one month (null: newest).
-   * The request id comes back with the answer, so a slow fetch cannot apply a
-   * month the last keypress did not ask for.
+   * Ask the extension to read one month in-process (null: current month). The
+   * request id comes back with the answer, so a slow read cannot apply a month
+   * the last keypress did not ask for.
    */
   loadHistory: (month: string | null, request: number) => void;
 };
@@ -1099,6 +1138,7 @@ const FAMILY_LABEL: Record<string, string> = {
   codex: "Codex (Pi)",
   antigravity: "Antigravity (Pi)",
   "opencode-go": "OpenCode Go (Pi)",
+  mistral: "Mistral (Pi)",
   "github-actions": "GitHub Actions",
 };
 
@@ -1132,18 +1172,20 @@ const HISTORY_HINTS: ReadonlyArray<readonly [string, string]> = [
   ["esc/q", "close"],
 ];
 
-/** The report cache the CLI writes after every successful run. */
+/** The report cache the CLI and in-process extension share. */
 function reportCachePath(): string {
   const cacheHome = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
   return join(cacheHome, "pi-quota", "usage.json");
 }
 
 /**
- * The last report the CLI cached, read synchronously so the overlay can paint
- * on the same keystroke as /usage. Read-only, age is irrelevant for a first
- * frame, and a missing or malformed cache is simply "no cached report".
+ * The last report on disk, read synchronously so the overlay paints on the same
+ * keystroke as /usage: read-only, age is irrelevant for a first frame, and a
+ * missing or malformed cache is simply "no cached report". The key travels back
+ * with it because it names the Claude source those numbers came from, and a
+ * later partial write has to keep describing the same data.
  */
-function readCachedReport(): QuotaReport | null {
+function readCachedReport(): { report: QuotaReport; key: string | null } | null {
   try {
     const parsed = JSON.parse(readFileSync(reportCachePath(), "utf-8"));
     const report = parsed?.report;
@@ -1157,7 +1199,10 @@ function readCachedReport(): QuotaReport | null {
         if (!Number.isNaN(resetsAtMs)) window.resetsInSec = Math.max(0, Math.round((resetsAtMs - now) / 1000));
       }
     }
-    return report as QuotaReport;
+    return {
+      report: report as QuotaReport,
+      key: typeof parsed?.key === "string" ? parsed.key : null,
+    };
   } catch {
     return null;
   }
@@ -1188,32 +1233,23 @@ function redactCause(value: string): string {
     .replace(/\b((?:__Host-console_session|auth)=)[^;\s]+/gi, "$1<redacted>");
 }
 
-/**
- * One short, redacted line for a failed `stats --json` run: the CLI's own first
- * stderr line when it printed one, otherwise its exit status. The raw parse
- * error ("Unexpected end of JSON input") says nothing about why the read failed.
- */
-function cliFailureLine(result: { stdout?: string; stderr?: string; code?: number; killed?: boolean } | null | undefined): string {
-  const first = String(result?.stderr ?? "")
-    .split("\n")
-    .map((line) => line.trim())
-    .find((line) => line !== "");
-  const code = Number(result?.code);
-  const cause = first
-    ? redactCause(first)
-    : result?.killed
-      ? "piquota stats was stopped (timeout)"
-      : Number.isFinite(code) && code !== 0
-        ? `piquota stats exited ${code}`
-        : "piquota stats --json printed no history payload";
-  return capCause(cause);
-}
-
 /** A stderr line or a thrown message can quote a whole path list; the frame gets one line. */
 function capCause(cause: string): string {
   return cause.length > 160 ? `${cause.slice(0, 157)}…` : cause;
 }
 
+/** Append warnings that are not already there: a repeated scan repeats its notes. */
+function mergeWarnings(existing: string[], added: string[] | undefined): string[] {
+  const seen = new Set(existing);
+  const merged = [...existing];
+  for (const warning of added ?? []) {
+    if (typeof warning !== "string" || warning === "" || seen.has(warning)) continue;
+    seen.add(warning);
+    merged.push(warning);
+  }
+  return merged;
+}
+
 /** Local YYYY-MM-DD, the history's day key. */
 function localDayKey(now = new Date()): string {
   return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
@@ -1443,7 +1479,7 @@ export class UsageOverlay {
   }
 
   /**
-   * A month (or the first payload, with the month list) arrived from the CLI.
+   * A month (or the first payload, with the month list) arrived from the in-process reader.
    * Every answer is cached — a later ← must not refetch what already arrived —
    * but only the answer to the newest request may move the page: ←/→ overlap,
    * and a late answer for a month the last keypress did not ask for used to snap
@@ -1481,21 +1517,32 @@ export class UsageOverlay {
     this.options.requestRender();
   }
 
-  /** Handle one raw key: switch view, fold, move, month, refresh, close. */
+  /**
+   * Handle one raw key: switch view, fold, move, month, refresh, close.
+   *
+   * Keys arrive in the terminal's own encoding — legacy escape sequences or
+   * kitty CSI sequences with an event type — so every test goes through
+   * src/overlay-keys.js. A kitty release is the second half of a press the
+   * terminal already reported: acting on it would move twice per keystroke.
+   * Repeats stay presses, so a held arrow keeps moving as it does in tmux.
+   */
   public handleInput(data: string): void {
     if (this.disposed) return;
-    if (data === "\u001b" || data === "q") {
+    if (isKeyRelease(data)) return;
+    if (matchesKey(data, "escape") || matchesPrintable(data, "q")) {
       this.dispose();
       this.options.done();
       return;
     }
-    if (data === "\t" || data === "1" || data === "2") {
-      const target = data === "1" ? "now" : data === "2" ? "history" : this.view === "now" ? "history" : "now";
+    const nowKey = matchesPrintable(data, "1");
+    const historyKey = matchesPrintable(data, "2");
+    if (matchesKey(data, "tab") || nowKey || historyKey) {
+      const target = nowKey ? "now" : historyKey ? "history" : this.view === "now" ? "history" : "now";
       this.switchView(target);
       this.invalidate();
       return;
     }
-    if (data === "r") {
+    if (matchesPrintable(data, "r")) {
       // History's today row comes from the live report, so a refresh there
       // reloads the month and the report together; one key, one meaning.
       if (this.view === "history") this.reloadMonth();
@@ -1503,17 +1550,17 @@ export class UsageOverlay {
       this.invalidate();
       return;
     }
-    if (isKey(data, "up") || data === "k") this.moveCursor(-1);
-    else if (isKey(data, "down") || data === "j") this.moveCursor(1);
-    else if (data === "\r" || data === "\n" || data === " ") this.toggleSection();
-    else if (isKey(data, "pageUp")) this.page(-1);
-    else if (isKey(data, "pageDown")) this.page(1);
-    else if (isKey(data, "home") || data === "g") this.jumpTo(0);
-    else if (isKey(data, "end") || data === "G") this.jumpTo(-1);
-    else if (this.view === "history" && (isKey(data, "left") || data === "[")) this.moveMonth(-1);
-    else if (this.view === "history" && (isKey(data, "right") || data === "]")) this.moveMonth(1);
-    else if (isKey(data, "left") || data === "h") this.setExpanded(false);
-    else if (isKey(data, "right") || data === "l") this.setExpanded(true);
+    if (matchesKey(data, "up") || matchesPrintable(data, "k")) this.moveCursor(-1);
+    else if (matchesKey(data, "down") || matchesPrintable(data, "j")) this.moveCursor(1);
+    else if (matchesKey(data, "enter") || matchesKey(data, "space")) this.toggleSection();
+    else if (matchesKey(data, "pageUp")) this.page(-1);
+    else if (matchesKey(data, "pageDown")) this.page(1);
+    else if (matchesKey(data, "home") || matchesPrintable(data, "g")) this.jumpTo(0);
+    else if (matchesKey(data, "end") || matchesPrintable(data, "G")) this.jumpTo(-1);
+    else if (this.view === "history" && (matchesKey(data, "left") || matchesPrintable(data, "["))) this.moveMonth(-1);
+    else if (this.view === "history" && (matchesKey(data, "right") || matchesPrintable(data, "]"))) this.moveMonth(1);
+    else if (matchesKey(data, "left") || matchesPrintable(data, "h")) this.setExpanded(false);
+    else if (matchesKey(data, "right") || matchesPrintable(data, "l")) this.setExpanded(true);
     else return;
     // The TUI renders the component again after every key, so the cached frame
     // and the cached row map must be dropped here, not only on report changes.
@@ -1620,8 +1667,9 @@ export class UsageOverlay {
         this.pushRow(rows, `  ${this.theme.fg("error", `! ${failure}`)}${hint}`, -1, false);
       }
     } else {
-      const error = this.options.getError();
-      if (error) rows.push({ text: `  ${this.theme.fg("error", `! ${error}`)}`, section: -1, header: false });
+      for (const error of this.options.getErrors()) {
+        rows.push({ text: `  ${this.theme.fg("error", `! ${error}`)}`, section: -1, header: false });
+      }
     }
     if (!layout) {
       // Distinct states, distinct lines: a failed fetch used to say "loading
@@ -1819,7 +1867,19 @@ export class UsageOverlay {
     const ensure = (family: string): HistoryFamily => {
       let entry = families.get(family);
       if (!entry) {
-        entry = { tokens: 0, prompts: 0, days: new Map(), models: new Map(), accounts: new Map(), allTime: 0, allTimeAccounts: new Map() };
+        entry = {
+          tokens: 0,
+          prompts: 0,
+          days: new Map(),
+          models: new Map(),
+          accounts: new Map(),
+          allTime: 0,
+          allTimePrompts: 0,
+          allTimeAccounts: new Map(),
+          liveTokens: 0,
+          livePrompts: 0,
+          liveAccounts: new Map(),
+        };
         families.set(family, entry);
       }
       return entry;
@@ -1884,6 +1944,10 @@ export class UsageOverlay {
         const entry = ensure(family);
         entry.tokens += tokens;
         entry.prompts += prompts;
+        // Kept apart from the frozen month: the all-time figures add this same
+        // delta below, and a live day may only ever be counted once in each.
+        entry.liveTokens += tokens;
+        entry.livePrompts += prompts;
         entry.days.set(today, (entry.days.get(today) ?? 0) + tokens);
         for (const [model, modelTokens] of Object.entries(familyStats.todayTokensByModel ?? {})) {
           entry.models.set(model, (entry.models.get(model) ?? 0) + Math.max(0, Math.round(Number(modelTokens) || 0)));
@@ -1891,8 +1955,12 @@ export class UsageOverlay {
         for (const [rawLabel, account] of Object.entries(familyStats.byAccount ?? {})) {
           const label = rawLabel === "#1" ? "" : rawLabel;
           const target = entry.accounts.get(label) ?? { tokens: 0, prompts: 0, models: new Map<string, number>() };
-          target.tokens += Math.max(0, Math.round(Number(account?.todayTokens) || 0));
-          target.prompts += Math.max(0, Math.round(Number(account?.todayPrompts) || 0));
+          const accountTokens = Math.max(0, Math.round(Number(account?.todayTokens) || 0));
+          const accountPrompts = Math.max(0, Math.round(Number(account?.todayPrompts) || 0));
+          target.tokens += accountTokens;
+          target.prompts += accountPrompts;
+          const liveAccount = entry.liveAccounts.get(label) ?? { tokens: 0, prompts: 0 };
+          entry.liveAccounts.set(label, { tokens: liveAccount.tokens + accountTokens, prompts: liveAccount.prompts + accountPrompts });
           // The account's own models for today: without them the merged row
           // shows a month total and no model, which reads as "no usage".
           for (const [model, modelTokens] of Object.entries(account?.todayTokensByModel ?? {})) {
@@ -1906,10 +1974,33 @@ export class UsageOverlay {
     for (const [family, totals] of Object.entries(payload.totals?.families ?? {})) {
       const entry = ensure(family);
       entry.allTime = Object.values(totals?.modelUsage ?? {}).reduce((sum, bucket) => sum + totalsModelTokens(bucket), 0);
+      entry.allTimePrompts = Math.max(0, Math.round(Number(totals?.totalPrompts) || 0));
       for (const [rawLabel, account] of Object.entries(totals?.accounts ?? {})) {
         const label = rawLabel === "#1" ? "" : rawLabel;
         const tokens = Object.values(account?.modelUsage ?? {}).reduce((sum, bucket) => sum + totalsModelTokens(bucket), 0);
-        entry.allTimeAccounts.set(label, (entry.allTimeAccounts.get(label) ?? 0) + tokens);
+        const prompts = Math.max(0, Math.round(Number(account?.totalPrompts) || 0));
+        const seen = entry.allTimeAccounts.get(label) ?? { tokens: 0, prompts: 0 };
+        entry.allTimeAccounts.set(label, { tokens: seen.tokens + tokens, prompts: seen.prompts + prompts });
+      }
+    }
+
+    // Today's live day is part of all time, not only of this month: it is the
+    // same usage the month row and the day row above already show, so it is
+    // added here exactly once — the single place the live delta is folded into
+    // a rollup, and only under the merge guard above (the day frozen, or a
+    // report from another day, never produces a delta at all).
+    //
+    // A family with no rollup in totals.json gets nothing: there is no all-time
+    // figure to extend, and calling today's tokens "all-time" would hide every
+    // frozen day before it. The page already carries the CLI's note for that.
+    for (const [family, entry] of families) {
+      if (!payload.totals?.families?.[family]) continue;
+      if (entry.liveTokens === 0 && entry.livePrompts === 0) continue;
+      entry.allTime += entry.liveTokens;
+      entry.allTimePrompts += entry.livePrompts;
+      for (const [label, delta] of entry.liveAccounts) {
+        const seen = entry.allTimeAccounts.get(label) ?? { tokens: 0, prompts: 0 };
+        entry.allTimeAccounts.set(label, { tokens: seen.tokens + delta.tokens, prompts: seen.prompts + delta.prompts });
       }
     }
 
@@ -1936,10 +2027,29 @@ export class UsageOverlay {
       // Multi-account families use the same short name as the Now panel header.
       const display = accountLabels.length > 1 ? SHORT_NAME[family] ?? FAMILY_LABEL[family] ?? family : FAMILY_LABEL[family] ?? family;
       const name = paint(BRAND[family] ?? "#8B949E", display);
+      // The month first, then the all-time rollup with today's live day folded
+      // in: every figure here counts a live day once. Prompts are scope-labelled
+      // in their own row below, because an unlabelled count reads as the wrong
+      // one of the two.
+      //
+      // Every all-time figure is computed before the first line is built: the
+      // note a lagging rollup earns belongs at the top of the section, where it
+      // explains the header, the prompts row and the account rows at once.
       const meta = [`${formatTokens(entry.tokens)} in ${month}`];
-      if (entry.allTime > 0) meta.push(`${formatTokens(entry.allTime)} all-time`);
-      if (entry.prompts > 0) meta.push(`${entry.prompts} prompt${entry.prompts === 1 ? "" : "s"}`);
+      const familyAllTime = allTimeFigure(entry.tokens, entry.allTime);
+      if (familyAllTime.value > 0) meta.push(`${formatTokens(familyAllTime.value)} all-time`);
+      const promptsAllTime = allTimeFigure(entry.prompts, entry.allTimePrompts);
+      const accountAllTime = new Map<string, AllTimeFigure>();
+      for (const accountLabel of accountLabels) {
+        accountAllTime.set(
+          accountLabel,
+          allTimeFigure(entry.accounts.get(accountLabel)?.tokens ?? 0, entry.allTimeAccounts.get(accountLabel)?.tokens ?? 0),
+        );
+      }
+      const lagsMonth =
+        familyAllTime.lags || promptsAllTime.lags || Array.from(accountAllTime.values()).some((figure) => figure.lags);
       const body: string[] = [];
+      if (lagsMonth) body.push(`  ${this.theme.fg("warning", `~ ${ALL_TIME_LAGS_NOTE}`)}`);
       const label = (text: string) => `  ${this.theme.fg("dim", text.padEnd(6))}  `;
       const rest = `  ${" ".repeat(8)}`;
       const dayCells = Array.from(entry.days.entries())
@@ -1951,6 +2061,22 @@ export class UsageOverlay {
         rest,
         bodyWidth,
       ));
+      // Both scopes, always: the live day is merged into each of them once, so
+      // the month count and the all-time count may never disagree about it.
+      const promptCells: string[] = [];
+      if (entry.prompts > 0) promptCells.push(`${entry.prompts} in ${month}`);
+      if (promptsAllTime.value > 0) {
+        // A figure that lags the month is still a figure: it is printed, dimmed
+        // whole, and the note above the rows says why it is small.
+        promptCells.push(
+          promptsAllTime.lags
+            ? this.theme.fg("dim", `${promptsAllTime.value} all-time`)
+            : `${promptsAllTime.value} ${this.theme.fg("dim", "all-time")}`,
+        );
+      }
+      if (promptCells.length > 0) {
+        body.push(...wrapCells(promptCells, label("prompts"), rest, bodyWidth));
+      }
       if (entry.models.size > 0) {
         const top = Array.from(entry.models.entries()).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
         const shown = top.slice(0, 5).map(([model, tokens]) => `${shortModelName(model)} ${formatTokens(tokens)}`);
@@ -1962,8 +2088,14 @@ export class UsageOverlay {
         for (const accountLabel of accountLabels) {
           const account = entry.accounts.get(accountLabel) ?? { tokens: 0, prompts: 0, models: new Map<string, number>() };
           const parts = [`${this.theme.fg("dim", "month")} ${formatTokens(account.tokens)}`];
-          const allTime = entry.allTimeAccounts.get(accountLabel) ?? 0;
-          if (allTime > 0) parts.push(`${this.theme.fg("dim", "all-time")} ${formatTokens(allTime)}`);
+          const accountFigure = accountAllTime.get(accountLabel) ?? { value: 0, lags: false };
+          if (accountFigure.value > 0) {
+            parts.push(
+              accountFigure.lags
+                ? this.theme.fg("dim", `all-time ${formatTokens(accountFigure.value)}`)
+                : `${this.theme.fg("dim", "all-time")} ${formatTokens(accountFigure.value)}`,
+            );
+          }
           const best = Array.from(account.models.entries()).sort((a, b) => b[1] - a[1])[0];
           if (best) parts.push(this.theme.fg("dim", shortModelName(best[0])));
           body.push(`  ${this.theme.fg("dim", accountLabel.padEnd(labelWidth))}  ${parts.join(this.theme.fg("dim", " · "))}`);
@@ -2008,7 +2140,7 @@ export class UsageOverlay {
     } else {
       const report = this.options.getReport();
       if (report) parts.push(this.theme.fg("dim", updatedAtLabel(report)));
-      if (this.options.getError()) parts.push(this.theme.fg("error", "refresh failed"));
+      if (this.options.getErrors().length > 0) parts.push(this.theme.fg("error", "refresh failed"));
     }
     if (this.view === "history") {
       const status = this.historyStatus;
@@ -2055,9 +2187,34 @@ export class UsageOverlay {
   }
 }
 
-export default function quotaPanelExtension(pi: ExtensionAPI): void {
+export default function quotaPanelExtension(pi: ExtensionAPI, dependencies: ExtensionDependencies = {}): void {
+  const loadFamily = dependencies.collectFamily ?? collectFamily;
+  const startScan = dependencies.startLocalStats ?? (() => startLocalStatsWorker() as LocalStatsScan);
+  const getProviderAuth = dependencies.getProviderAuth ?? (async (ctx, provider) => ctx.modelRegistry?.getProviderAuth?.(provider));
+  const readHistory = (month: string | null) => dependencies.loadHistory
+    ? dependencies.loadHistory(month)
+    : (historyJson({ historyDir: resolveHistoryDir(), month }) as HistoryPayload);
+  const publishOmarchy = dependencies.publishOmarchy ?? ((value, prune) => {
+    const skip = skippedFamilies(process.env);
+    const reportToPublish = skip.size > 0
+      ? { ...value, providers: value.providers.filter((provider) => !skip.has(provider.family)) }
+      : value;
+    publishRecords(buildRecords(reportToPublish as any), { prune });
+  });
   let report: QuotaReport | null = null;
-  let refreshing = false;
+  const inFlight = new Map<string, Promise<boolean>>();
+  let resultGeneration = 0;
+  let prunedGeneration = 0;
+  let localStatsInFlight: Promise<void> | null = null;
+  let localStatsScan: LocalStatsScan | null = null;
+  let localStatsResult: Awaited<LocalStatsScan["result"]> | null = null;
+  /**
+   * The notes the scan produced (its own warnings, or the one line a failure
+   * becomes). They live here, not only in the report, because the scan can
+   * finish before the first family does: it is the report that is late then,
+   * not the warning.
+   */
+  let localStatsWarnings: string[] = [];
   let timer: ReturnType<typeof setInterval> | null = null;
   let agentEndTimer: ReturnType<typeof setTimeout> | null = null;
   let panelVisible = false;
@@ -2080,22 +2237,30 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
   let explicitBox = false;
   /** gentle-pi owns the footer and truncates it from the end, so start off. */
   let statusVisible = false;
-  let lastError: string | null = null;
+  /** One failure per family: an out-of-order success must not hide another's. */
+  const familyErrors = new Map<string, string>();
+  /**
+   * The Claude source the report in memory actually came from. The extension
+   * forces Pi's own OAuth when Pi resolves a token, and that is a different
+   * fact from what PI_QUOTA_CLAUDE_SOURCE says: keying the cache by the setting
+   * alone stored Pi-sourced numbers under the CLI's auto/claude-code key, where
+   * the next reader asked the other question and was served them anyway.
+   */
+  let claudeSourceUsed: string | null = null;
   let disposed = false;
   /** True once the installed gentle-pi is known to paint a rail slot for this card. */
   let railMode = false;
 
   /**
-   * Load the rail inspector from the installed CLI tree. A missing patcher disables
-   * native-layout detection; the runtime chaining hook remains available.
+   * Load the rail inspector from this package, not from a quota CLI subprocess.
+   * A missing patcher disables native-layout detection; the runtime chaining
+   * hook remains available.
    */
   async function loadRailPatcher(): Promise<{
     resolveGentlePiLayout: (options?: { dir?: string }) => { layoutPath: string; present: boolean };
     inspectRailPatch: (options: { layoutPath: string }) => { state: string };
   } | null> {
-    const cli = resolveCliPath();
-    if (!cli) return null;
-    const modulePath = join(dirname(cli), "..", "src", "gentle-pi", "rail-patch.js");
+    const modulePath = dependencies.railPatcherPath ?? fileURLToPath(new URL("../src/gentle-pi/rail-patch.js", import.meta.url));
     if (!existsSync(modulePath)) return null;
     try {
       return await import(pathToFileURL(modulePath).href);
@@ -2115,35 +2280,211 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
     railMode = inspection.state === "patched";
   }
 
+  /** Whether a family refresh is in flight; the header shows it while one is. */
+  function isRefreshing(): boolean {
+    return inFlight.size > 0;
+  }
+
+  /** Resolve Pi's own auth for the two rotating OAuth providers. Tokens stay local to this call. */
+  async function authOverridesFor(ctx: UiContext, family: string): Promise<Record<string, { access: string; expiresAtMs: number | null; accountId?: string }> | undefined> {
+    const provider = family === "claude" ? "anthropic" : family === "codex" ? "openai-codex" : null;
+    if (!provider) return undefined;
+    try {
+      const resolved = await getProviderAuth(ctx, provider);
+      // Pi can resolve api_key credentials through the same method. Quota
+      // endpoints here require the subscription OAuth access token, not an API
+      // key; only Pi's OAuth result is eligible for the in-memory override.
+      if (resolved?.source !== "OAuth") return undefined;
+      const token = resolved.auth?.apiKey;
+      if (typeof token !== "string" || token.length === 0) return undefined;
+      const accountId = (typeof resolved?.accountId === "string" && resolved.accountId) || extractChatGptAccountId(token) || undefined;
+      return {
+        [provider]: {
+          access: token,
+          expiresAtMs: extractExpiresAtMs(token),
+          ...(family === "codex" && accountId ? { accountId } : {}),
+        },
+      };
+    } catch {
+      // Never put arbitrary auth errors in a TUI frame; the engine will report its read-only credential state.
+      return undefined;
+    }
+  }
+
+  function mergeFamilyReport(fragment: QuotaReport): void {
+    const prior = report;
+    const merged = mergeReportIntoCache(prior, fragment as any) as QuotaReport;
+    merged.localStats = localStatsResult?.byFamily ?? prior?.localStats ?? fragment.localStats ?? {};
+    merged.localStatsMeta = localStatsResult?.scan ?? prior?.localStatsMeta ?? fragment.localStatsMeta ?? null;
+    merged.warnings = mergeWarnings(merged.warnings ?? [], localStatsWarnings);
+    const families = enabledFamilies({ env: process.env, requested: FAMILIES });
+    const ordering = [...families, ...Object.keys(merged.byFamily).filter((family) => !families.includes(family))];
+    merged.providers = ordering.flatMap((family) => merged.providers.filter((provider) => provider.family === family));
+    merged.byFamily = Object.fromEntries(
+      ordering
+        .map((family) => [family, merged.providers.filter((provider) => provider.family === family)] as const)
+        .filter(([, providers]) => providers.length > 0),
+    );
+    report = merged;
+  }
+
   /**
-   * Run the CLI. A report run owns `lastError`; the advisory `omarchy` publish
-   * writes human text, not JSON, and must never surface as a quota failure.
+   * The report in memory, or the one on disk. Reading the cache also adopts the
+   * Claude source its key names, so a codex-only write keeps describing the
+   * Claude numbers the file already holds.
    */
-  async function runCli(args: string[], options: { reportErrors?: boolean } = {}): Promise<QuotaReport | null> {
-    const reportErrors = options.reportErrors !== false;
-    const cli = resolveCliPath();
-    if (!cli) {
-      if (reportErrors) lastError = "piquota not installed: run install.sh from the pi-quota repo";
-      return null;
-    }
-    try {
-      const runner = /node(\.exe)?$/i.test(process.execPath) ? process.execPath : "node";
-      const result = await pi.exec(runner, [cli, ...args], { timeout: EXEC_TIMEOUT_MS });
-      if (!result.stdout || result.stdout.trim() === "") {
-        if (reportErrors) lastError = result.stderr?.trim() || "piquota produced no output";
-        return null;
-      }
-      const parsed = JSON.parse(result.stdout) as QuotaReport;
-      if (!parsed || !Array.isArray(parsed.providers)) {
-        if (reportErrors) lastError = "piquota output was not a quota report";
-        return null;
+  function ensureReport(): QuotaReport | null {
+    if (report) return report;
+    const cached = readCachedReport();
+    if (!cached) return null;
+    const stored = cached.key?.startsWith(CLAUDE_SOURCE_CACHE_PREFIX)
+      ? cached.key.slice(CLAUDE_SOURCE_CACHE_PREFIX.length)
+      : null;
+    if (stored) claudeSourceUsed = normalizeClaudeSourceMode(stored);
+    report = cached.report;
+    return report;
+  }
+
+  /** The key this report belongs under: the source it used, not the setting. */
+  function cacheKey(): string {
+    return cacheKeyFor(claudeSourceUsed ?? process.env.PI_QUOTA_CLAUDE_SOURCE ?? "");
+  }
+
+  function persistReport(freshFamilies: string[] = []): void {
+    if (!report) return;
+    // Every family keeps the clock it was fetched on: this report is written one
+    // family at a time, and stamping the whole file with "now" made Claude's
+    // five-minute-old numbers look as fresh as the Codex ones saved beside them.
+    // Only the family that just resolved is "now"; a family without a clock in
+    // refresh-state keeps the cache's, or its own results' age.
+    writeCache(report as any, { key: cacheKey(), fetchedAtMs: readRefreshState().fetchedAtMs, freshFamilies });
+  }
+
+  function updateFamilyClock(family: string): void {
+    const state = readRefreshState();
+    writeRefreshState({ fetchedAtMs: { ...state.fetchedAtMs, [family]: Date.now() } });
+  }
+
+  function startLocalStats(ctx: UiContext): void {
+    if (process.env.PI_QUOTA_LOCAL_STATS === "0" || localStatsInFlight) return;
+    const scan = startScan();
+    localStatsScan = scan;
+    const task = scan.result
+      .then((result) => {
+        if (disposed) return;
+        localStatsResult = result;
+        // The scan's own notes (a corrupt cache, an unreadable file) are part of
+        // the report the CLI already publishes; dropping them here made the same
+        // scan quieter inside Pi than in the terminal.
+        localStatsWarnings = result.warnings ?? [];
+        if (report) {
+          report = {
+            ...report,
+            localStats: result.byFamily,
+            localStatsMeta: result.scan,
+            warnings: mergeWarnings(report.warnings, localStatsWarnings),
+          };
+          persistReport();
+          if (surfaceActive()) paintUi(ctx);
+          try {
+            publishOmarchy(report, false);
+          } catch {
+            // The quota view is independent of the optional Omarchy record writer.
+          }
+          overlayView?.redraw();
+        }
+      })
+      .catch((error: { name?: string; message?: string }) => {
+        // The scan is optional, so a failure never delays or erases quotas — but
+        // it is not the same as a scan that found nothing. The CLI reports a
+        // failed scan as one warning line; a swallowed worker error meant a
+        // crash in the scanner looked exactly like an empty token history.
+        if (disposed || error?.name === "AbortError") return;
+        const cause = capCause(redactCause(error?.message ?? String(error)).split("\n")[0]);
+        localStatsWarnings = mergeWarnings(localStatsWarnings, [`local token stats: ${cause}`]);
+        if (!report) return;
+        report = { ...report, warnings: mergeWarnings(report.warnings, localStatsWarnings) };
+        if (surfaceActive()) paintUi(ctx);
+        overlayView?.redraw();
+      })
+      .finally(() => {
+        if (localStatsScan === scan) localStatsScan = null;
+        if (localStatsInFlight === task) localStatsInFlight = null;
+      });
+    localStatsInFlight = task;
+  }
+
+  /**
+   * End the local scan this session started. Nothing it began may outlive the
+   * session: a /quit or /reload one second into a cold scan would otherwise
+   * keep reading the session store and hold the token-history lock until the
+   * 120 s stale timeout, making the next scan read-only.
+   */
+  async function stopLocalStats(): Promise<void> {
+    const scan = localStatsScan;
+    localStatsScan = null;
+    if (!scan) return;
+    await scan.stop();
+  }
+
+  async function refreshFamily(ctx: UiContext, family: string, force: boolean): Promise<boolean> {
+    const running = inFlight.get(family);
+    if (running) return running;
+    let task: Promise<boolean>;
+    task = (async () => {
+      try {
+        // Explicit delay seam used by the live progressive-refresh proof; absent in normal runs.
+        if (process.env.PI_QUOTA_DEBUG_DELAY_FAMILY === family) {
+          const delay = Math.max(0, Math.min(30_000, Number(process.env.PI_QUOTA_DEBUG_DELAY_MS) || 2_000));
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+        const authOverrides = await authOverridesFor(ctx, family);
+        const env = family === "claude" && authOverrides
+          ? { ...process.env, PI_QUOTA_CLAUDE_SOURCE: "pi" }
+          : process.env;
+        const fragment = await loadFamily(family, { force, authOverrides, env, localStats: false } as any);
+        if (disposed) return false;
+        if (family === "claude") claudeSourceUsed = normalizeClaudeSourceMode(env.PI_QUOTA_CLAUDE_SOURCE);
+        const stickyFragment = mergeLastGood(fragment as any, {}).report as QuotaReport;
+        mergeFamilyReport(stickyFragment);
+        updateFamilyClock(family);
+        persistReport([family]);
+        resultGeneration += 1;
+        familyErrors.delete(family);
+        try {
+          const familyReport = { ...stickyFragment, localStats: report?.localStats ?? stickyFragment.localStats ?? {} };
+          publishOmarchy(familyReport, false);
+        } catch {
+          // A bar-record failure must not turn a quota refresh into an error.
+        }
+        if (surfaceActive()) paintUi(ctx);
+        return true;
+      } catch (error) {
+        const message = (error as { message?: string })?.message ?? String(error);
+        familyErrors.set(family, capCause(redactCause(message).split("\n")[0]));
+        return false;
+      } finally {
+        if (inFlight.get(family) === task) inFlight.delete(family);
+        if (surfaceActive()) paintUi(ctx);
+        overlayView?.redraw();
       }
-      if (reportErrors) lastError = null;
-      return parsed;
-    } catch (error) {
-      if (reportErrors) lastError = (error as { message?: string })?.message ?? String(error);
-      return null;
-    }
+    })();
+    inFlight.set(family, task);
+    return task;
+  }
+
+  /**
+   * One line per failing family, in family order so the list does not reshuffle
+   * as families land. The name is short for the same reason: this is a row in a
+   * dense panel, not a log.
+   */
+  function errorLines(): string[] {
+    const order = [...enabledFamilies({ env: process.env, requested: FAMILIES })];
+    for (const family of familyErrors.keys()) if (!order.includes(family)) order.push(family);
+    return order.flatMap((family) => {
+      const message = familyErrors.get(family);
+      return message ? [`${SHORT_NAME[family] ?? family}: ${message}`] : [];
+    });
   }
 
   function paintUi(ctx: UiContext): void {
@@ -2294,21 +2635,42 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
   }
 
   async function refresh(ctx: UiContext, force: boolean): Promise<void> {
-    if (refreshing) return;
-    refreshing = true;
-    try {
-      const next = await runCli(force ? ["--json", "--force"] : ["--json"]);
-      if (disposed) return;
-      if (next) {
-        report = next;
-        // A bare /usage overlay is not a pinned surface: only repaint the widget
-        // and the footer when something is actually on screen.
-        if (surfaceActive()) paintUi(ctx);
-        void runCli(["omarchy"], { reportErrors: false });
+    if (disposed) return;
+    report = ensureReport();
+    const families = enabledFamilies({ env: process.env, requested: FAMILIES });
+    const now = Date.now();
+    const fetchedAtMs = { ...readRefreshState().fetchedAtMs };
+    // Upgrade path: an older CLI cache has no per-family clock file, but each
+    // provider already carries its own updatedAt. Do not refetch fresh cached data
+    // merely because this extension version has not written clocks yet.
+    for (const family of families) {
+      if (typeof fetchedAtMs[family] === "number") continue;
+      const providerTimes = (report?.providers ?? [])
+        .filter((provider) => provider.family === family)
+        .map((provider) => Date.parse(provider.updatedAt))
+        .filter((time) => Number.isFinite(time));
+      const generatedAt = report?.generatedAt ? Date.parse(report.generatedAt) : NaN;
+      const fallback = providerTimes.length > 0 ? Math.max(...providerTimes) : generatedAt;
+      if (Number.isFinite(fallback)) fetchedAtMs[family] = fallback;
+    }
+    const staleByClock = new Set(staleFamilies({
+      fetchedAtMs,
+      ttls: resolveFamilyTtls({ families }),
+      families,
+      now,
+    }));
+    const cachedFamilies = new Set(report?.providers.map((provider) => provider.family) ?? []);
+    const selected = force ? families : families.filter((family) => !cachedFamilies.has(family) || staleByClock.has(family));
+    if (selected.length === 0) return;
+    startLocalStats(ctx);
+    const outcomes = await Promise.all(selected.map((family) => refreshFamily(ctx, family, force)));
+    if (outcomes.every(Boolean) && inFlight.size === 0 && report && resultGeneration !== prunedGeneration) {
+      try {
+        publishOmarchy(report, true);
+        prunedGeneration = resultGeneration;
+      } catch {
+        // Keep fresh quota data even if the optional final stale-record prune fails.
       }
-    } finally {
-      refreshing = false;
-      overlayView?.redraw();
     }
   }
 
@@ -2368,36 +2730,23 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
       ui.ui.setStatus(STATUS_KEY, undefined);
       ui.ui.setWidget(WIDGET_KEY, undefined);
     }
+    // Pi awaits session_shutdown (reason "reload" included), so the scan is gone
+    // and its lock released before the next session or the process starts.
+    await stopLocalStats();
   });
 
   /**
-   * Run `piquota stats --json` for one month (null: the newest with a file) and
-   * hand the payload to the overlay. Read-only, no lock: the CLI only reads.
+   * Read one month (null: the current local month) in-process and hand the
+   * aggregate-only payload to the overlay. Read-only, no lock: historyJson only reads.
    *
-   * A failure is reported the way the report path reports one: the CLI's own
-   * stderr line or its exit status, redacted and on one line. The JSON parser's
+   * A reader failure is redacted and limited to one line. The JSON parser's
    * "Unexpected end of JSON input" says nothing about the cause.
    */
   async function loadHistory(month: string | null, request: number): Promise<void> {
-    const cli = resolveCliPath();
-    if (!cli) {
-      overlayView?.setHistoryError("piquota not installed: run install.sh from the pi-quota repo", request);
-      return;
-    }
     try {
-      const runner = /node(\.exe)?$/i.test(process.execPath) ? process.execPath : "node";
-      const argv = [cli, "stats", "--json", ...(month ? ["--month", month] : [])];
-      const result = await pi.exec(runner, argv, { timeout: EXEC_TIMEOUT_MS });
-      const stdout = typeof result?.stdout === "string" ? result.stdout : "";
-      let parsed: HistoryPayload | null = null;
-      try {
-        parsed = stdout.trim() === "" ? null : (JSON.parse(stdout) as HistoryPayload);
-      } catch {
-        // A truncated or non-JSON stdout: report the run, not the parser.
-        parsed = null;
-      }
+      const parsed = await readHistory(month);
       if (!parsed || !Array.isArray(parsed.months)) {
-        overlayView?.setHistoryError(cliFailureLine(result), request);
+        overlayView?.setHistoryError("piquota stats returned no history payload", request);
         return;
       }
       overlayView?.setHistory(parsed, request);
@@ -2414,9 +2763,9 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
    */
   async function showOverlay(ctx: UiContext): Promise<void> {
     // Paint on the same keystroke: the report already in memory, otherwise the
-    // CLI's on-disk cache. The forced refresh runs behind the overlay and never
-    // delays the first frame.
-    if (!report) report = readCachedReport();
+    // on-disk cache. Only stale families refresh behind the overlay; the first
+    // frame never waits for the network.
+    report = ensureReport();
     const custom = ctx.ui.custom;
     if (typeof custom !== "function" || (ctx.mode !== undefined && ctx.mode !== "tui")) {
       // A host without custom components still gets the panel that /usage panel pins.
@@ -2424,7 +2773,8 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
       lineVisible = false;
       boxVisible = false;
       explicitBox = false;
-      if (!report) await refresh(ctx, false);
+      report = ensureReport();
+      void refresh(ctx, false);
       ensurePolling(ctx);
       paintUi(ctx);
       ctx.ui.notify("This host has no fullscreen overlay; the quota panel is pinned above the editor", "info");
@@ -2437,8 +2787,8 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
           requestRender: () => tui?.requestRender?.(),
           getRows: () => tui?.terminal?.rows ?? process.stdout.rows ?? 24,
           getReport: () => report,
-          getError: () => lastError,
-          isRefreshing: () => refreshing,
+          getErrors: () => errorLines(),
+          isRefreshing: () => isRefreshing(),
           refresh: () => {
             void refresh(ctx, true);
           },
@@ -2474,10 +2824,11 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
     switch (action) {
       case "refresh":
         await refresh(ctx, true);
+        const failures = errorLines();
         ctx.ui.notify(
           report
             ? `Quota refreshed (${report.providers.filter((provider) => provider.ok).length}/${report.providers.length} providers)`
-            : `Quota refresh failed: ${lastError}`,
+            : `Quota refresh failed: ${failures.length > 1 ? `${failures[0]} (+${failures.length - 1} more)` : failures[0] ?? "unknown error"}`,
           report ? "info" : "error",
         );
         return;
@@ -2487,7 +2838,9 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
         boxVisible = false;
         explicitBox = false;
         panelVisible = false;
+        report = ensureReport();
         if (!report) await refresh(ctx, false);
+        else void refresh(ctx, false);
         ensurePolling(ctx);
         paintUi(ctx);
         ctx.ui.notify("Quota line pinned above the editor", "info");
@@ -2497,7 +2850,9 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
         lineVisible = false;
         boxVisible = false;
         explicitBox = false;
+        report = ensureReport();
         if (!report) await refresh(ctx, false);
+        else void refresh(ctx, false);
         ensurePolling(ctx);
         paintUi(ctx);
         ctx.ui.notify("Quota panel shown above the editor", "info");
@@ -2507,7 +2862,9 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
         boxVisible = true;
         explicitBox = true;
         panelVisible = false;
+        report = ensureReport();
         if (!report) await refresh(ctx, false);
+        else void refresh(ctx, false);
         ensurePolling(ctx);
         paintUi(ctx);
         ctx.ui.notify("Quota box pinned above the editor", "info");
@@ -2534,7 +2891,7 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
         paintUi(ctx);
         return;
       case "json":
-        ctx.ui.notify(`${resolveCliPath() ?? "piquota"} --json   (cached at ~/.cache/pi-quota/usage.json)`, "info");
+        ctx.ui.notify(`Report cache: ${reportCachePath()}`, "info");
         return;
       default:
         break;
@@ -2543,7 +2900,7 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
     // Bare /usage (or an unknown argument): open the overlay with whatever the
     // extension already has, and refresh in the background behind it.
     const opening = showOverlay(ctx);
-    void refresh(ctx, true);
+    void refresh(ctx, false);
     await opening;
   };