@cad0p/pi-usage 0.11.4 → 0.11.5

package/extensions/quota-panel.ts

@@ -1,10 +1,11 @@
 /**
  * Pi quota line — read-only quota for the providers Pi already owns.
  *
- * Surface: nothing at session start. Bare /usage shows the panel until the next
- * prompt or a second /usage. /usage box, /usage line or /usage panel pins
- * a surface above the editor, /usage status enables the footer, and /usage hide
- * removes it. No timer or post-turn refresh runs until a surface is on.
+ * Surface: nothing at session start. Bare /usage opens a fullscreen overlay that
+ * takes the keyboard, scrolls, folds a section per provider and closes on Esc or
+ * q; nothing stays on screen behind it. /usage box, /usage line or /usage panel
+ * pins a surface above the editor, /usage status enables the footer, and
+ * /usage hide removes it. No timer or post-turn refresh runs until a surface is on.
  *
  * Design rules:
  *   - the numbers are **used**, not remaining, so the line answers "how much have
@@ -23,7 +24,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -83,6 +84,8 @@ type LocalAccountStats = {
   todayPrompts?: number;
   totalPrompts?: number;
   totalTokens?: number;
+  /** The account's own model split for today; absent from an older report. */
+  todayTokensByModel?: Record<string, number>;
 };
 
 /**
@@ -124,11 +127,17 @@ type Theme = {
 /** Only the UI surface this extension uses. */
 type UiContext = {
   hasUI: boolean;
+  /** Pi's run mode; `custom` components only exist in the TUI. */
+  mode?: string;
   ui: {
     theme: Theme;
     setStatus: (key: string, value: string | undefined) => void;
     setWidget: (key: string, value: any, options?: { placement?: string }) => void;
     notify: (message: string, type?: string) => void;
+    custom?: (
+      factory: (tui: any, theme: Theme, keybindings: any, done: (result?: unknown) => void) => any,
+      options?: { overlay?: boolean; overlayOptions?: Record<string, unknown> },
+    ) => Promise<unknown>;
   };
 };
 
@@ -550,44 +559,103 @@ function clipToWidth(line: string, width: number): string {
   return out;
 }
 
+/** One visible character with the SGR runs in front of it and the style it inherits. */
+type StyledChar = { raw: string; char: string; style: string };
+
+/**
+ * Split a themed line into visible characters, folding each SGR run into the
+ * character that follows it and remembering the style open at that point.
+ * Wrapping needs both: a continuation row must re-open the style it inherits,
+ * and every produced row must close whatever it left open.
+ */
+function styledChars(line: string): { chars: StyledChar[]; trailing: string } {
+  const chars: StyledChar[] = [];
+  let pending = "";
+  let style = "";
+  for (let index = 0; index < line.length; ) {
+    const sgr = /^\u001b\[[0-9;]*m/.exec(line.slice(index));
+    if (sgr) {
+      pending += sgr[0];
+      style = sgr[0] === "\u001b[0m" ? "" : `${style}${sgr[0]}`;
+      index += sgr[0].length;
+      continue;
+    }
+    const char = String.fromCodePoint(line.codePointAt(index) as number);
+    chars.push({ raw: `${pending}${char}`, char, style });
+    pending = "";
+    index += char.length;
+  }
+  return { chars, trailing: pending };
+}
+
+/**
+ * Wrap one themed line to `width` columns, breaking at its " · " separators.
+ *
+ * A hard clip used to cut a row mid-token at 64 columns, which loses the datum
+ * that matters most: "(18d)" is when the month resets, and "token exp" is the
+ * state of the credential. So a row that does not fit wraps instead — the first
+ * row keeps the line's own indent, every continuation is indented by the line's
+ * leading spaces (or `hanging`), and no cell is ever dropped. A single cell
+ * wider than the terminal is the one case that still clips: there is nowhere to
+ * break it.
+ */
+function wrapLine(line: string, width: number, hanging?: string): string[] {
+  const limit = Math.max(1, Math.floor(width));
+  if (visibleLength(line) <= limit) return [line];
+  const { chars, trailing } = styledChars(line);
+  if (chars.length === 0) return [line];
+  const visible = chars.map((item) => item.char).join("");
+  // A break sits on the space in front of " · ", so neither row starts with a
+  // dangling middle dot.
+  const breaks: number[] = [];
+  const spaces: number[] = [];
+  for (let index = 0; index + 2 < visible.length; index += 1) {
+    if (visible[index] === " " && visible[index + 1] === "·" && visible[index + 2] === " ") breaks.push(index);
+  }
+  for (let index = 0; index < visible.length; index += 1) if (visible[index] === " ") spaces.push(index);
+  const indent = hanging ?? /^ */.exec(visible)?.[0] ?? "";
+  const row = (from: number, to: number, prefix: string, extra = ""): string => {
+    // A wrapped row must not end in the padding the break was taken on.
+    const text = `${prefix}${chars.slice(from, to).map((item) => item.raw).join("")}${extra}`.replace(/ +(?=(\u001b\[[0-9;]*m)*$)/, "");
+    return /\u001b\[/.test(text) ? `${text}\u001b[0m` : text;
+  };
+
+  const lines: string[] = [];
+  let start = 0;
+  while (start < chars.length) {
+    const prefix = start === 0 ? "" : chars[start].style === "" ? indent : `${indent}${chars[start].style}`;
+    const fits = start + Math.max(1, limit - visibleLength(prefix));
+    if (fits >= chars.length) {
+      lines.push(row(start, chars.length, prefix, trailing));
+      break;
+    }
+    // A " · " boundary is the natural break; a word boundary is the fallback, so
+    // a long warning wraps between words instead of mid-token; a single word
+    // wider than the pane is the only case left to hard-cut.
+    const breakAt = breaks.filter((index) => index > start && index <= fits).pop();
+    const spaceAt = breakAt === undefined ? spaces.filter((index) => index > start && index <= fits).pop() : undefined;
+    const cut = breakAt ?? spaceAt ?? fits;
+    lines.push(row(start, cut, prefix));
+    start = breakAt === undefined ? (spaceAt === undefined ? cut : cut + 1) : cut + 3;
+  }
+  return lines.length > 0 ? lines : [line];
+}
+
 /**
  * The panel as a component rather than a string array: Pi caps string-array
  * widgets at ten lines, and a multi-account family alone can exceed that.
+ *
+ * A line that does not fit wraps at its separators instead of being cut: at 64
+ * columns a hard clip used to lose the half of a row that says when the month
+ * resets, which is exactly the datum the row exists for.
  */
 function panelComponent(lines: string[]) {
   return () => ({
-    render: (width: number) => lines.map((line) => ` ${clipToWidth(line, Math.max(0, width - 1))}`),
+    render: (width: number) => lines.flatMap((line) => wrapLine(line, Math.max(0, width - 1))).map((line) => ` ${line}`),
     invalidate() {},
   });
 }
 
-/**
- * The one-line notify summary. A multi-account family reports how many accounts
- * answer and the account with the most room, not whichever key happens to be #1.
- */
-function summarize(report: QuotaReport): string {
-  const active = report.providers.filter((provider) => provider.notConfigured !== true);
-  return firstPerFamily(active)
-    .map((provider) => {
-      const name = SHORT_NAME[provider.family] ?? provider.family;
-      if (isMultiAccount(active, provider)) {
-        const accounts = active.filter((other) => other.family === provider.family);
-        const scored = accounts
-          .filter((account) => account.ok)
-          .map((account) => ({ account, used: usedOf(bindingWindow(account)) }))
-          .filter((entry): entry is { account: QuotaProvider; used: number } => entry.used !== null);
-        const counted = `${accounts.filter((account) => account.ok).length}/${accounts.length} ok`;
-        if (scored.length === 0) return `${name}: ${counted}`;
-        const lowest = scored.reduce((best, entry) => (entry.used < best.used ? entry : best));
-        return `${name}: ${counted} · lowest ${Math.round(lowest.used)}% (${lowest.account.account})`;
-      }
-      if (!provider.ok) return `${name}: ${errorCaption(provider.error)}`;
-      const used = usedOf(headline(provider));
-      return `${name}: ${used === null ? "n/a" : `${Math.round(used)}% used`}`;
-    })
-    .join(" · ");
-}
-
 /** Window names for the one-line account rows (same words as the Omarchy panel). */
 const WINDOW_TAG: Record<string, string> = { "5h": "session", weekly: "week", monthly: "month" };
 
@@ -690,11 +758,29 @@ function accountReason(error: string | null | undefined): string {
   return errorCaption(error);
 }
 
-/** `#N` accounts of one family, i.e. a family Pi holds several credentials for. */
+/**
+ * The slot label of an account: "" for the base auth.json entry (it has no
+ * number, so no surface may invent one) and "#<slot>" for a real sibling. A
+ * report cached before the fix still says "#1" for the base entry.
+ */
+function accountLabel(account: string | null | undefined): string {
+  const text = String(account ?? "");
+  if (text === "#1") return "";
+  return /^#\d+$/.test(text) ? text : text;
+}
+
+/** The per-account token row, tolerating the old "#1" key in a cached scan. */
+function accountStats(stats: LocalFamilyStats | undefined, label: string): LocalAccountStats | undefined {
+  if (!stats?.byAccount) return undefined;
+  return stats.byAccount[label] ?? (label === "" ? stats.byAccount["#1"] : undefined);
+}
+
+/**
+ * A family Pi holds several credentials for: one section and one line per
+ * account, whatever the account labels look like.
+ */
 function isMultiAccount(providers: QuotaProvider[], provider: QuotaProvider): boolean {
-  return typeof provider.account === "string"
-    && provider.account.startsWith("#")
-    && providers.filter((other) => other.family === provider.family).length > 1;
+  return providers.filter((other) => other.family === provider.family).length > 1;
 }
 
 /**
@@ -708,20 +794,23 @@ function renderAccountRows(accounts: QuotaProvider[], theme: Theme, stats?: Loca
   const healthy = accounts.filter((account) => account.ok).length;
   const header = `${paint(BRAND[family] ?? "#8B949E", SHORT_NAME[family] ?? accounts[0].label)} ${theme.fg("dim", `· ${healthy} of ${accounts.length} accounts ok`)}`;
   const lines = [header];
-  const width = Math.max(...accounts.map((account) => account.account.length));
-  for (const account of accounts) {
-    const label = theme.fg("dim", account.account.padEnd(width));
+  // The base entry has no number: its label column is blank but padded to the
+  // widest sibling, so the percentage columns still line up.
+  const labels = accounts.map((account) => accountLabel(account.account));
+  const width = Math.max(...labels.map((label) => label.length));
+  accounts.forEach((account, index) => {
+    const label = theme.fg("dim", labels[index].padEnd(width));
     if (!account.ok) {
       const kind = errorKind(account.error);
       const color = kind === "transient" || kind === "throttle" ? "warning" : kind === "expired" || kind === "auth" ? "error" : "dim";
       lines.push(`  ${label}  ${theme.fg(color, errorGlyph(account.error))} ${theme.fg("warning", accountReason(account.error))}`);
-      continue;
+      return;
     }
     const window = bindingWindow(account);
     const used = usedOf(window);
     if (window === null || used === null) {
       lines.push(`  ${label}  ${theme.fg("dim", "no rate-limit windows reported")}`);
-      continue;
+      return;
     }
     // Every window on one line, each in its own band colour; the leading glyph
     // is the fullest window's, so the column still sorts the accounts by eye.
@@ -733,85 +822,1237 @@ function renderAccountRows(accounts: QuotaProvider[], theme: Theme, stats?: Loca
         const reset = each.resetsInSec === null ? "" : ` ${theme.fg("dim", `(${shortDuration(each.resetsInSec)})`.padEnd(5))}`;
         return `${theme.fg("dim", WINDOW_TAG[each.id] ?? each.id)} ${paint(bandFor(pct).color, `${Math.round(pct)}%`.padStart(4))}${reset}`;
       });
-    const today = Number(stats?.byAccount?.[account.account]?.todayTokens) || 0;
+    const today = Number(accountStats(stats, labels[index])?.todayTokens) || 0;
     const tokens = today > 0 ? ` · ${formatTokens(today)} today` : "";
     lines.push(`  ${label}  ${paint(band.color, band.glyph)} ${cells.join(theme.fg("dim", " · "))}${theme.fg("dim", tokens)}`);
-  }
+  });
   return lines;
 }
 
-function renderPanel(report: QuotaReport, theme: Theme): string[] {
+/**
+ * One provider block of the panel: the header painted with the provider name
+ * and every window, account and token row that belongs to it. The overlay
+ * folds on these blocks; the pinned widget renders them flat, unchanged.
+ */
+type PanelSection = { key: string; header: string; body: string[] };
+
+/** The provider block of a single-account provider: its header plus its detail. */
+function renderProviderLines(provider: QuotaProvider, theme: Theme, localStats: LocalFamilyStats | undefined, partialScan: boolean): string[] {
   const lines: string[] = [];
+  const labelWidth = Math.max(6, ...provider.windows.map((window) => String(window.label ?? "").length));
+  const name = paint(BRAND[provider.family] ?? "#8B949E", provider.label);
+  const account = accountLabel(provider.account);
+  const meta: string[] = account === "" ? [] : [account];
+  if (provider.plan) meta.push(`plan ${provider.plan}`);
+  // Two stores can back Claude, and this is the one place that says which.
+  if (provider.sourceKind === "claude-code") meta.push("Claude Code CLI");
+  if (provider.expiresInMin !== null && provider.expiresInMin <= 120) {
+    meta.push(
+      provider.expiresInMin < 0
+        ? theme.fg("error", "token expired")
+        : theme.fg("dim", `token ${provider.expiresInMin}m`),
+    );
+  }
+  lines.push(meta.length > 0 ? `${name} ${theme.fg("dim", `· ${meta.join(" · ")}`)}` : name);
+
+  if (!provider.ok) {
+    const kind = errorKind(provider.error);
+    const glyph = errorGlyph(provider.error);
+    const color = kind === "transient" || kind === "throttle" ? "warning" : kind === "expired" || kind === "auth" ? "error" : "dim";
+    lines.push(`  ${theme.fg(color, glyph)} ${theme.fg("warning", provider.note ?? errorCaption(provider.error))}`);
+    if (isRecoverableError(provider.error) && provider.note) lines.push(`  ${theme.fg("warning", provider.note)}`);
+  } else if (provider.windows.length === 0) {
+    if (provider.note) lines.push(`  ${theme.fg("warning", `~ ${provider.note}`)}`);
+    lines.push(`  ${theme.fg("dim", "no rate-limit windows reported")}`);
+  } else {
+    if (provider.note) lines.push(`  ${theme.fg("warning", `~ ${provider.note}`)}`);
+    for (const window of provider.windows) {
+      const used = usedOf(window);
+      const label = theme.fg("dim", window.label.padEnd(labelWidth));
+      if (used === null) {
+        lines.push(`  ${label}  ${theme.fg("dim", window.note ?? "no percentage reported")}`);
+        continue;
+      }
+      const band = bandFor(used);
+      const reset = window.resetsInSec === null ? "" : theme.fg("dim", ` · reset in ${humanDuration(window.resetsInSec)}`);
+      lines.push(
+        `  ${label}  ${paint(band.color, band.glyph)} ${paint(band.color, bar(used))} ` +
+          `${paint(band.color, `${used.toFixed(used < 10 ? 1 : 0)}%`.padStart(5))} ` +
+          `${theme.fg("dim", "used")}${reset}`,
+      );
+    }
+  }
+
+  // Local token stats survive a failed quota probe: the credential may be
+  // rejected while the tokens already burned are still a fact on disk.
+  lines.push(...renderTokenRows(localStats, labelWidth, theme, partialScan));
+  return lines;
+}
+
+/**
+ * Split the panel into its foldable provider sections and the lines below them
+ * (byline, unconfigured providers, warnings). Bare `/usage` folds these; the
+ * pinned `/usage panel` flattens them back into the same list as before.
+ */
+function renderPanelLayout(report: QuotaReport, theme: Theme): { sections: PanelSection[]; tail: string[] } {
+  const sections: PanelSection[] = [];
   const active = report.providers.filter((provider) => provider.notConfigured !== true);
   const unconfigured = report.providers.filter((provider) => provider.notConfigured === true);
   const renderedFamilies = new Set<string>();
-
   const partialScan = report.localStatsMeta?.partial === true;
+
   for (const provider of active) {
     const localStats = report.localStats?.[provider.family];
     const labelWidth = Math.max(6, ...provider.windows.map((window) => String(window.label ?? "").length));
     if (isMultiAccount(active, provider)) {
       if (renderedFamilies.has(provider.family)) continue;
       renderedFamilies.add(provider.family);
-      lines.push(...renderAccountRows(active.filter((other) => other.family === provider.family), theme, localStats));
-      lines.push(...renderTokenRows(localStats, labelWidth, theme, partialScan));
+      const rows = renderAccountRows(active.filter((other) => other.family === provider.family), theme, localStats);
+      sections.push({
+        key: `${provider.family}`,
+        header: rows[0] ?? paint(BRAND[provider.family] ?? "#8B949E", provider.label),
+        body: [...rows.slice(1), ...renderTokenRows(localStats, labelWidth, theme, partialScan)],
+      });
       continue;
     }
-    const name = paint(BRAND[provider.family] ?? "#8B949E", provider.label);
-    const meta: string[] = [provider.account];
-    if (provider.plan) meta.push(`plan ${provider.plan}`);
-    // Two stores can back Claude, and this is the one place that says which.
-    if (provider.sourceKind === "claude-code") meta.push("Claude Code CLI");
-    if (provider.expiresInMin !== null && provider.expiresInMin <= 120) {
-      meta.push(
-        provider.expiresInMin < 0
-          ? theme.fg("error", "token expired")
-          : theme.fg("dim", `token ${provider.expiresInMin}m`),
-      );
+    const lines = renderProviderLines(provider, theme, localStats, partialScan);
+    sections.push({ key: `${provider.family}:${provider.account}`, header: lines[0] ?? "", body: lines.slice(1) });
+  }
+
+  const tail: string[] = [];
+  // No timestamp here: the overlay header already says when the report landed
+  // ("updated HH:MM"), and a second format for the same fact reads as a
+  // different number to check. The pinned panel prints this line alone.
+  tail.push(theme.fg("dim", "used % · read-only"));
+  if (unconfigured.length > 0) {
+    const names = unconfigured.map((p) => SHORT_NAME[p.family] ?? p.family).join(", ");
+    tail.push(theme.fg("dim", `not configured in Pi: ${names}`));
+  }
+  for (const warning of report.warnings.slice(0, 3)) {
+    tail.push(theme.fg("warning", `warn: ${warning}`));
+  }
+  return { sections, tail };
+}
+
+/** The flat panel: every section, then the footer, unconfigured names, warnings. */
+function renderPanel(report: QuotaReport, theme: Theme): string[] {
+  const { sections, tail } = renderPanelLayout(report, theme);
+  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;
+}
+
+function clampScroll(value: number, max: number): number {
+  return Math.max(0, Math.min(value, max));
+}
+
+/** One line with its label left and its status right, clipped to the width. */
+function spreadLine(left: string, right: string, width: number): string {
+  if (right === "") return clipToWidth(left, width);
+  const rightText = clipToWidth(right, width);
+  const leftText = clipToWidth(left, Math.max(0, width - visibleLength(rightText) - 1));
+  const gap = Math.max(0, width - visibleLength(leftText) - visibleLength(rightText));
+  return `${leftText}${" ".repeat(gap)}${rightText}`;
+}
+
+/** One content row of the overlay, with the section it belongs to. */
+type OverlayRow = { text: string; section: number; header: boolean };
+
+/** One month of the durable history, as `piquota stats --json` returns it. */
+type HistoryPayload = {
+  generatedAt?: string;
+  months?: string[];
+  quarantined?: string[];
+  month?: string;
+  days?: Record<string, Record<string, HistoryFamilyDay>>;
+  totals?: HistoryTotals | null;
+  notes?: string[];
+};
+
+type HistoryFamilyDay = {
+  sessions?: number;
+  tokens?: number;
+  prompts?: number;
+  slots?: Record<string, HistorySlotDay>;
+};
+
+type HistorySlotDay = {
+  sessions?: number;
+  tokens?: number;
+  prompts?: number;
+  models?: Record<string, { tokens?: number; messages?: number }>;
+};
+
+type HistoryTotals = {
+  lastFrozenDay?: string;
+  families?: Record<string, HistoryTotalsFamily>;
+};
+
+type HistoryTotalsModel = {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+};
+
+type HistoryTotalsFamily = {
+  firstDay?: string;
+  activeDates?: string[];
+  totalPrompts?: number;
+  totalSessions?: number;
+  modelUsage?: Record<string, HistoryTotalsModel>;
+  accounts?: Record<string, { totalPrompts?: number; totalSessions?: number; modelUsage?: Record<string, HistoryTotalsModel> }>;
+};
+
+/** One family's month, aggregated from the payload and the live report. */
+type HistoryFamily = {
+  tokens: number;
+  prompts: number;
+  days: Map<string, number>;
+  models: Map<string, number>;
+  accounts: Map<string, { tokens: number; prompts: number; models: Map<string, number> }>;
+  allTime: number;
+  allTimeAccounts: Map<string, number>;
+};
+
+/**
+ * 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
+ * session only, and never on disk.
+ */
+type OverlaySession = {
+  expanded: Map<string, boolean>;
+  view: "now" | "history";
+  month: string | null;
+};
+
+function newOverlaySession(): OverlaySession {
+  return { expanded: new Map(), view: "now", month: null };
+}
+
+/**
+ * The History page's fetch state. "Not asked yet", "in flight" and "the last
+ * fetch failed" are three different frames: the failed one must not also claim
+ * to be loading.
+ */
+type HistoryStatus =
+  | { kind: "idle" }
+  | { kind: "loading"; month: string | null }
+  | { kind: "failed"; month: string | null; message: string };
+
+/**
+ * One id per `stats --json` request, for the whole pi process: a reopened overlay
+ * issues the next id, so an answer to a closed view's request can never be taken
+ * for an answer to its own.
+ */
+let historyRequestSeq = 0;
+
+type UsageOverlayOptions = {
+  /** Close the overlay through the component's completion callback. */
+  done: () => void;
+  /** Ask the TUI for a frame after state changed. */
+  requestRender: () => void;
+  /** Current terminal height. */
+  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;
+  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.
+   */
+  loadHistory: (month: string | null, request: number) => void;
+};
+
+/** Display names for a family the current report does not mention. */
+const FAMILY_LABEL: Record<string, string> = {
+  claude: "Claude (Pi)",
+  codex: "Codex (Pi)",
+  antigravity: "Antigravity (Pi)",
+  "opencode-go": "OpenCode Go (Pi)",
+  "github-actions": "GitHub Actions",
+};
+
+/**
+ * The key legend. Every key the current view answers appears here; a pair a
+ * view does not answer (month navigation outside History) is not listed. The
+ * legend wraps instead of dropping pairs, so a 60-column terminal still shows
+ * every key; the close key stays last.
+ */
+const NOW_HINTS: ReadonlyArray<readonly [string, string]> = [
+  ["↑↓/jk", "move"],
+  ["enter/space/←→/hl", "fold"],
+  ["pgup/pgdn", "page"],
+  ["g/G home/end", "top/end"],
+  ["wheel", "scroll"],
+  ["r", "refresh"],
+  ["tab/1/2", "history"],
+  ["esc/q", "close"],
+];
+
+const HISTORY_HINTS: ReadonlyArray<readonly [string, string]> = [
+  ["↑↓/jk", "move"],
+  ["enter/space/h/l", "fold"],
+  ["←/[", "prev month"],
+  ["]/→", "next month"],
+  ["pgup/pgdn", "page"],
+  ["g/G home/end", "top/end"],
+  ["wheel", "scroll"],
+  ["r", "refresh"],
+  ["tab/1/2", "now"],
+  ["esc/q", "close"],
+];
+
+/** The report cache the CLI writes after every successful run. */
+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".
+ */
+function readCachedReport(): QuotaReport | null {
+  try {
+    const parsed = JSON.parse(readFileSync(reportCachePath(), "utf-8"));
+    const report = parsed?.report;
+    if (!report || !Array.isArray(report.providers)) return null;
+    // The cache stores absolute reset instants; the surfaces paint countdowns.
+    const now = Date.now();
+    for (const provider of report.providers) {
+      for (const window of provider.windows ?? []) {
+        if (!window.resetsAt) continue;
+        const resetsAtMs = Date.parse(window.resetsAt);
+        if (!Number.isNaN(resetsAtMs)) window.resetsInSec = Math.max(0, Math.round((resetsAtMs - now) / 1000));
+      }
     }
-    lines.push(meta.length > 0 ? `${name} ${theme.fg("dim", `· ${meta.join(" · ")}`)}` : name);
+    return report as QuotaReport;
+  } catch {
+    return null;
+  }
+}
 
-    if (!provider.ok) {
-      const kind = errorKind(provider.error);
-      const glyph = errorGlyph(provider.error);
-      const color = kind === "transient" || kind === "throttle" ? "warning" : kind === "expired" || kind === "auth" ? "error" : "dim";
-      lines.push(`  ${theme.fg(color, glyph)} ${theme.fg("warning", provider.note ?? errorCaption(provider.error))}`);
-      if (isRecoverableError(provider.error) && provider.note) lines.push(`  ${theme.fg("warning", provider.note)}`);
-    } else if (provider.windows.length === 0) {
-      if (provider.note) lines.push(`  ${theme.fg("warning", `~ ${provider.note}`)}`);
-      lines.push(`  ${theme.fg("dim", "no rate-limit windows reported")}`);
+/** The update time shown once a refresh lands, as the clock time it happened. */
+function updatedAtLabel(report: QuotaReport): string {
+  const at = new Date(report.generatedAt);
+  if (Number.isNaN(at.getTime())) return "updated";
+  return `updated ${String(at.getHours()).padStart(2, "0")}:${String(at.getMinutes()).padStart(2, "0")}`;
+}
+
+/**
+ * Mask what must never reach a TUI frame or a scrollback. Mirrors
+ * `src/http.js:redact` (this extension is one dependency-free file), and adds the
+ * ANSI strip: a CLI's stderr can carry its own colour codes.
+ */
+function redactCause(value: string): string {
+  return value
+    .replace(/\u001b\[[0-9;]*m/g, "")
+    .replace(/[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}/g, "<email>")
+    .replace(/\beyJ[\w-]{8,}\.[\w-]{8,}\.[\w-]{4,}\b/g, "<jwt>")
+    .replace(/\b(sk-[A-Za-z0-9_-]{6})[A-Za-z0-9_-]+/g, "$1<redacted>")
+    .replace(/\b(ya29\.)[A-Za-z0-9_-]+/g, "$1<redacted>")
+    .replace(/\b(1\/\/)[A-Za-z0-9_-]+/g, "$1<redacted>")
+    .replace(/\b(rt\.[\w.]{4})[A-Za-z0-9_-]+/g, "$1<redacted>")
+    .replace(/\b(Bearer\s+)[A-Za-z0-9._~+/-]+=*/gi, "$1<redacted>")
+    .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;
+}
+
+/** 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")}`;
+}
+
+/** Local YYYY-MM, the history's month key. */
+function localMonthKey(now = new Date()): string {
+  return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}`;
+}
+
+/** Tokens in one compact history model bucket. */
+function historyModelTokens(bucket: { tokens?: number } | undefined): number {
+  return Math.max(0, Math.round(Number(bucket?.tokens) || 0));
+}
+
+/** Tokens in one totals.json model bucket (the rollup's short keys). */
+function totalsModelTokens(bucket: HistoryTotalsModel | undefined): number {
+  const values = [bucket?.input, bucket?.output, bucket?.cacheRead, bucket?.cacheWrite];
+  return values.reduce((sum, value) => sum + Math.max(0, Math.round(Number(value) || 0)), 0);
+}
+
+/** Slot labels sort "" (the unnumbered base) first, then #2, #3 … #10 numerically. */
+function slotOrder(label: string): number {
+  if (label === "") return -1;
+  const numeric = Number.parseInt(label.replace(/^#/, ""), 10);
+  return Number.isFinite(numeric) ? numeric : Number.MAX_SAFE_INTEGER;
+}
+
+/**
+ * Greedy wrap of " · "-joined cells: the first line carries the label, the
+ * continuation lines are indented under it, and no cell is dropped.
+ */
+function wrapCells(cells: string[], first: string, rest: string, width: number): string[] {
+  const lines: string[] = [];
+  let current = first;
+  let count = 0;
+  for (const cell of cells) {
+    const separator = count === 0 ? "" : " · ";
+    if (count > 0 && visibleLength(current) + separator.length + visibleLength(cell) > width) {
+      lines.push(current);
+      current = rest + cell;
+      count = 1;
+      continue;
+    }
+    current += separator + cell;
+    count += 1;
+  }
+  lines.push(count > 0 ? current : first.trimEnd());
+  return lines;
+}
+
+/**
+ * Split `count` cells into the fewest rows that fit `width`, then even them out.
+ *
+ * Greedy filling is the row count; a second pass picks, among all splits into
+ * that many rows, the one whose widest row is the narrowest. That is what turns
+ * a 7+1 legend into 4+4 without ever adding a row or dropping a pair.
+ *
+ * @returns the number of cells on each row.
+ */
+function balanceRows(lengths: number[], width: number, separator: number): number[] {
+  const count = lengths.length;
+  if (count === 0) return [];
+  const prefix: number[] = [0];
+  for (const length of lengths) prefix.push(prefix[prefix.length - 1] + length);
+  const cost = (from: number, to: number) => prefix[to] - prefix[from] + separator * (to - from - 1);
+
+  let rows = 1;
+  let used = lengths[0];
+  for (let index = 1; index < count; index += 1) {
+    if (used + separator + lengths[index] <= width) used += separator + lengths[index];
+    else {
+      rows += 1;
+      used = lengths[index];
+    }
+  }
+  if (rows <= 1) return [count];
+
+  // best[i][r]: the narrowest possible widest row for cells[i..] in exactly r rows.
+  const best: number[][] = Array.from({ length: count + 1 }, () => Array(rows + 1).fill(Number.POSITIVE_INFINITY));
+  best[count][0] = 0;
+  for (let remaining = 1; remaining <= rows; remaining += 1) {
+    for (let from = count - 1; from >= 0; from -= 1) {
+      for (let take = 1; take <= count - from - (remaining - 1); take += 1) {
+        const rest = best[from + take][remaining - 1];
+        if (rest === Number.POSITIVE_INFINITY) continue;
+        const widest = Math.max(cost(from, from + take), rest);
+        if (widest < best[from][remaining]) best[from][remaining] = widest;
+      }
+    }
+  }
+
+  const counts: number[] = [];
+  let from = 0;
+  for (let remaining = rows; remaining > 0; remaining -= 1) {
+    let chosen = 1;
+    for (let take = 1; take <= count - from - (remaining - 1); take += 1) {
+      const rest = best[from + take][remaining - 1];
+      if (rest === Number.POSITIVE_INFINITY) continue;
+      if (Math.max(cost(from, from + take), rest) === best[from][remaining]) {
+        chosen = take;
+        break;
+      }
+    }
+    counts.push(chosen);
+    from += chosen;
+  }
+  return counts;
+}
+
+/**
+ * The focused `/usage` view: two fullscreen pages the keyboard owns.
+ *
+ * Now is the panel, one collapsible section per provider, with a header cursor,
+ * scrolling and a key legend. History is the durable token history for one
+ * month, the same sections folded the same way, with ←/→ walking the months
+ * that have a file. It reads the report, the error and the loaded month through
+ * callbacks, so a background refresh only has to call redraw(); the view holds
+ * no timer and no disk state.
+ */
+export class UsageOverlay {
+  private readonly theme: Theme;
+  private readonly options: UsageOverlayOptions;
+  /** Fold state and the page, shared with the next view for this pi session. */
+  private readonly session: OverlaySession;
+  private cursor = 0;
+  private scroll = 0;
+  private disposed = false;
+  /** Months the CLI says are browsable, newest last. */
+  private historyMonths: string[] = [];
+  /** One loaded month per month key, kept for the lifetime of this overlay. */
+  private readonly historyCache = new Map<string, HistoryPayload>();
+  /** Whether History is idle, loading a month, or showing a failed fetch. */
+  private historyStatus: HistoryStatus = { kind: "idle" };
+  /**
+   * Id of the newest `stats --json` request this view issued. ←/→ fire
+   * overlapping fetches; only the newest answer may move the page.
+   */
+  private historyWanted = 0;
+  /** Width of the last frame; history rows are wrapped for it. */
+  private measureWidth = 80;
+  private cachedLayout: { sections: PanelSection[]; tail: string[] } | null | undefined;
+  private cachedLayoutWidth: number | undefined;
+  private cachedMetrics: { rows: OverlayRow[]; headerRows: number[]; sectionEnds: number[] } | undefined;
+  private cachedMetricsWidth: number | undefined;
+  private cachedWidth: number | undefined;
+  private cachedRows: number | undefined;
+  private cachedLines: string[] | undefined;
+  /** Legend rows the last frame needed; the viewport height depends on it. */
+  private legendRows = 1;
+
+  constructor(theme: Theme, options: UsageOverlayOptions, session: OverlaySession = newOverlaySession()) {
+    this.theme = theme;
+    this.options = options;
+    this.session = session;
+  }
+
+  /** The fold map shared with the next view, so a reopen keeps every fold. */
+  private get expanded(): Map<string, boolean> {
+    return this.session.expanded;
+  }
+
+  private get view(): "now" | "history" {
+    return this.session.view;
+  }
+
+  private set view(value: "now" | "history") {
+    this.session.view = value;
+  }
+
+  /** The month shown in History; null until a payload names one. */
+  private get selectedMonth(): string | null {
+    return this.session.month;
+  }
+
+  private set selectedMonth(value: string | null) {
+    this.session.month = value;
+  }
+
+  /**
+   * Load what a reopened view needs: a page that was closed on History has no
+   * payload in its fresh cache, and its month must not render as empty.
+   */
+  public begin(): void {
+    if (this.disposed || this.view !== "history") return;
+    if (this.selectedMonth !== null && this.historyCache.has(this.selectedMonth)) return;
+    this.requestMonth(this.selectedMonth);
+  }
+
+  /** Drop cached rows and frames; the next render rebuilds from live state. */
+  public invalidate(): void {
+    this.cachedLayout = undefined;
+    this.cachedLayoutWidth = undefined;
+    this.cachedMetrics = undefined;
+    this.cachedMetricsWidth = undefined;
+    this.cachedWidth = undefined;
+    this.cachedRows = undefined;
+    this.cachedLines = undefined;
+  }
+
+  /** Re-render after the extension's background refresh landed. */
+  public redraw(): void {
+    if (this.disposed) return;
+    this.invalidate();
+    this.options.requestRender();
+  }
+
+  /** Stop drawing once the overlay closed, however it closed. */
+  public dispose(): void {
+    this.disposed = true;
+    this.invalidate();
+  }
+
+  /**
+   * Ask for one month (null: the newest with a file) and remember the request
+   * id, so the answer can be matched against the last keypress rather than the
+   * order the CLI happened to finish in.
+   */
+  private requestMonth(month: string | null): void {
+    // The counter lives in the module, not on the view: a reopened overlay must
+    // not reuse an id, or an answer to the closed view's request would pass for
+    // an answer to its own.
+    historyRequestSeq += 1;
+    this.historyWanted = historyRequestSeq;
+    this.historyStatus = { kind: "loading", month };
+    this.options.loadHistory(month, this.historyWanted);
+  }
+
+  /**
+   * A month (or the first payload, with the month list) arrived from the CLI.
+   * 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
+   * the page back and skip a month.
+   */
+  public setHistory(payload: HistoryPayload, request?: number): void {
+    if (this.disposed) return;
+    if (Array.isArray(payload.months)) {
+      this.historyMonths = payload.months.filter((month) => /^\d{4}-\d{2}$/.test(month));
+    }
+    const month = typeof payload.month === "string" && /^\d{4}-\d{2}$/.test(payload.month) ? payload.month : null;
+    if (month !== null) this.historyCache.set(month, payload);
+    // The newest request answered, so nothing is loading any more. It moves the
+    // page only if the page still asks for that month: a newer keypress may have
+    // left it, and the late answer then only fills the cache.
+    if (request === undefined || request === this.historyWanted) {
+      if (month !== null && (this.selectedMonth === null || month === this.selectedMonth)) this.selectedMonth = month;
+      this.historyStatus = { kind: "idle" };
+    }
+    this.invalidate();
+    this.options.requestRender();
+  }
+
+  /** The history fetch failed: a line in the view, never a thrown error. */
+  public setHistoryError(message: string, request?: number): void {
+    if (this.disposed) return;
+    // A failure that answers an older request must not paint over the month the
+    // user is on now: its own request (or its cached payload) owns the frame.
+    if (request !== undefined && request !== this.historyWanted) return;
+    // Keep the month the failed fetch was for: a retry must ask for that month,
+    // and the frame must say "failed" rather than "loading".
+    const month = this.historyStatus.kind === "loading" ? this.historyStatus.month : this.selectedMonth;
+    this.historyStatus = { kind: "failed", month, message };
+    this.invalidate();
+    this.options.requestRender();
+  }
+
+  /** Handle one raw key: switch view, fold, move, month, refresh, close. */
+  public handleInput(data: string): void {
+    if (this.disposed) return;
+    if (data === "\u001b" || 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";
+      this.switchView(target);
+      this.invalidate();
+      return;
+    }
+    if (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();
+      this.options.refresh();
+      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);
+    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.
+    this.invalidate();
+  }
+
+  /**
+   * Wheel notches scroll the body; every other mouse event stays with pi.
+   *
+   * pi's TUI routes fullscreen wheel events to the focused component but offers
+   * no scrolling API for a custom screen: unhandled notches only move a
+   * ScrollView, and this extension ships as one dependency-free file that
+   * cannot import one. So the wheel is handled here, exactly as pi-context-view
+   * does (one notch = wheelDelta lines, undefined for every other event).
+   */
+  public handleMouse(event: { type?: string; wheelDelta?: number }): { handled: true; render: boolean } | undefined {
+    if (this.disposed || event?.type !== "wheel" || !event.wheelDelta) return undefined;
+    const before = this.scroll;
+    this.scroll = clampScroll(this.scroll + event.wheelDelta, this.maxScroll());
+    if (this.scroll === before) return { handled: true, render: false };
+    this.invalidate();
+    this.syncCursor();
+    return { handled: true, render: true };
+  }
+
+  /** Render one fullscreen frame for the given width and terminal height. */
+  public render(width: number): string[] {
+    const rows = terminalRows(this.options.getRows());
+    if (this.cachedLines && this.cachedWidth === width && this.cachedRows === rows) return this.cachedLines;
+
+    this.measureWidth = width;
+    // The legend wraps, so its row count depends on the width: it is measured
+    // before the viewport is cut, and the frame reserves exactly those rows.
+    const legend = this.legendLines(width);
+    this.legendRows = legend.length;
+    const { rows: content } = this.metrics();
+    const height = Math.max(1, rows - this.frameRows());
+    this.scroll = clampScroll(this.scroll, Math.max(0, content.length - height));
+
+    const viewport: string[] = [];
+    for (const row of content.slice(this.scroll, this.scroll + height)) {
+      const text = row.header ? `${row.section === this.cursor ? "❯" : " "} ${row.text}` : row.text;
+      viewport.push(clipToWidth(text, width));
+    }
+    while (viewport.length < height) viewport.push("");
+
+    const title = this.titleLine();
+    const frame = [spreadLine(title, this.statusText(content.length, height), width), "", ...viewport, "", ...legend];
+    while (frame.length < rows) frame.push("");
+    this.cachedWidth = width;
+    this.cachedRows = rows;
+    this.cachedLines = frame.slice(0, rows);
+    return this.cachedLines;
+  }
+
+  /** Rows the frame spends around the scrolling content: title, two blanks, legend. */
+  private frameRows(): number {
+    return 3 + Math.max(1, this.legendRows);
+  }
+
+  /** Visible content height, excluding the fixed frame rows. */
+  private viewportHeight(): number {
+    return Math.max(1, terminalRows(this.options.getRows()) - this.frameRows());
+  }
+
+  private maxScroll(): number {
+    return Math.max(0, this.metrics().rows.length - this.viewportHeight());
+  }
+
+  private isExpanded(key: string): boolean {
+    return this.expanded.get(key) ?? true;
+  }
+
+  /** The report split into its foldable sections; null while the first load runs. */
+  private layout(): { sections: PanelSection[]; tail: string[] } | null {
+    if (this.cachedLayout !== undefined && this.cachedLayoutWidth === this.measureWidth) return this.cachedLayout;
+    this.cachedLayoutWidth = this.measureWidth;
+    this.cachedLayout = this.view === "history" ? this.historyLayout(this.measureWidth) : this.nowLayout();
+    return this.cachedLayout;
+  }
+
+  /** The Now page: the exactly same sections the pinned panel renders flat. */
+  private nowLayout(): { sections: PanelSection[]; tail: string[] } | null {
+    const report = this.options.getReport();
+    return report ? renderPanelLayout(report, this.theme) : null;
+  }
+
+  /** Flattened rows, plus where every section's header starts and ends. */
+  private metrics(): { rows: OverlayRow[]; headerRows: number[]; sectionEnds: number[] } {
+    if (this.cachedMetrics && this.cachedMetricsWidth === this.measureWidth) return this.cachedMetrics;
+    this.cachedMetricsWidth = this.measureWidth;
+    const rows: OverlayRow[] = [];
+    const headerRows: number[] = [];
+    const sectionEnds: number[] = [];
+    const layout = this.layout();
+    if (this.view === "history") {
+      const failure = this.historyFailure();
+      if (failure !== null) {
+        // With a month on screen the error is a line above it, so it carries the
+        // retry hint itself; the no-payload state says it on the line below.
+        const hint = layout ? ` ${this.theme.fg("dim", "· press r to retry")}` : "";
+        // A CLI's stderr line is longer than a pane: wrapped, so neither the
+        // cause nor the hint is lost to the right edge.
+        this.pushRow(rows, `  ${this.theme.fg("error", `! ${failure}`)}${hint}`, -1, false);
+      }
     } else {
-      if (provider.note) lines.push(`  ${theme.fg("warning", `~ ${provider.note}`)}`);
-      for (const window of provider.windows) {
-        const used = usedOf(window);
-        const label = theme.fg("dim", window.label.padEnd(labelWidth));
-        if (used === null) {
-          lines.push(`  ${label}  ${theme.fg("dim", window.note ?? "no percentage reported")}`);
-          continue;
+      const error = this.options.getError();
+      if (error) 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
+      // history …" under its own error, which reads as a spinner that never ends.
+      const status = this.historyStatus;
+      const label = this.view !== "history"
+        ? "loading quota …"
+        : status.kind === "loading"
+          ? status.month === null
+            ? "loading history …"
+            : `loading ${status.month} …`
+          : status.kind === "failed"
+            ? "no history for this month; press r to retry"
+            : "loading history …";
+      rows.push({ text: `  ${this.theme.fg("dim", label)}`, section: -1, header: false });
+    } else {
+      layout.sections.forEach((section, index) => {
+        const open = this.isExpanded(section.key);
+        headerRows.push(rows.length);
+        this.pushRow(rows, `${open ? "▾" : "▸"} ${section.header}`, index, true);
+        if (open) for (const line of section.body) this.pushRow(rows, `    ${line}`, index, false);
+        sectionEnds.push(rows.length - 1);
+      });
+      for (const line of layout.tail) this.pushRow(rows, `  ${line}`, -1, false);
+    }
+    this.cursor = Math.max(0, Math.min(this.cursor, Math.max(0, headerRows.length - 1)));
+    this.cachedMetrics = { rows, headerRows, sectionEnds };
+    return this.cachedMetrics;
+  }
+
+  /**
+   * Append one content row, wrapped to the measured width. The cursor marker and
+   * the body indent are two columns the wrap budget must leave room for, and a
+   * wrapped header's continuation rows are body rows of the same section, so the
+   * header indexes the cursor walks do not shift.
+   */
+  private pushRow(rows: OverlayRow[], text: string, section: number, header: boolean): void {
+    const width = Math.max(8, this.measureWidth - (header ? 2 : 0));
+    const parts = wrapLine(text, width);
+    rows.push({ text: parts[0], section, header });
+    for (const part of parts.slice(1)) rows.push({ text: header ? `  ${part}` : part, section, header: false });
+  }
+
+  /** Walk the headers; a section taller than the viewport scrolls first. */
+  private moveCursor(delta: -1 | 1): void {
+    const { headerRows, sectionEnds } = this.metrics();
+    if (headerRows.length === 0) return;
+    const height = this.viewportHeight();
+    const section = this.layout()?.sections[this.cursor];
+    const open = section !== undefined && this.isExpanded(section.key);
+    const end = sectionEnds[this.cursor] ?? 0;
+    if (delta > 0 && open && end > this.scroll + height - 1) {
+      this.scroll = clampScroll(this.scroll + 1, this.maxScroll());
+      return;
+    }
+    if (delta < 0 && open && headerRows[this.cursor] < this.scroll) {
+      this.scroll = clampScroll(this.scroll - 1, this.maxScroll());
+      return;
+    }
+    const next = this.cursor + delta;
+    if (next < 0 || next >= headerRows.length) {
+      this.scroll = clampScroll(this.scroll + delta, this.maxScroll());
+      return;
+    }
+    this.cursor = next;
+    this.reveal();
+  }
+
+  /** Scroll the cursor's header into view; a tall section starts at its header. */
+  private reveal(): void {
+    const { headerRows, sectionEnds } = this.metrics();
+    const height = this.viewportHeight();
+    const top = headerRows[this.cursor] ?? 0;
+    const bottom = sectionEnds[this.cursor] ?? top;
+    if (top < this.scroll || bottom > this.scroll + height - 1) this.scroll = top;
+    this.scroll = clampScroll(this.scroll, this.maxScroll());
+  }
+
+  /**
+   * Page the body. When nothing can scroll the keystroke does nothing: paging
+   * used to re-snap the cursor to the last on-screen header, so PgUp on a short
+   * page moved the selection *down*.
+   */
+  private page(delta: -1 | 1): void {
+    const before = this.scroll;
+    this.scroll = clampScroll(this.scroll + delta * this.viewportHeight(), this.maxScroll());
+    this.invalidate();
+    if (this.scroll !== before) this.syncCursor();
+  }
+
+  private jumpTo(index: 0 | -1): void {
+    const { headerRows } = this.metrics();
+    if (headerRows.length === 0) {
+      this.scroll = index === 0 ? 0 : this.maxScroll();
+      return;
+    }
+    this.cursor = index === 0 ? 0 : headerRows.length - 1;
+    this.scroll = index === 0 ? 0 : this.maxScroll();
+    const top = headerRows[this.cursor] ?? 0;
+    if (top < this.scroll) this.scroll = top;
+  }
+
+  /**
+   * Keep the cursor on the header nearest the one it was on that is still on
+   * screen. The last visible header is the wrong pick: scrolling a little used
+   * to throw the selection to the bottom of the page. When no header is on
+   * screen the cursor stays put, so scrolling back returns to it.
+   */
+  private syncCursor(): void {
+    const { headerRows } = this.metrics();
+    if (headerRows.length === 0) return;
+    const bottom = this.scroll + this.viewportHeight() - 1;
+    let best: number | null = null;
+    for (let index = 0; index < headerRows.length; index += 1) {
+      const row = headerRows[index];
+      if (row < this.scroll || row > bottom) continue;
+      if (best === null || Math.abs(index - this.cursor) < Math.abs(best - this.cursor)) best = index;
+    }
+    if (best !== null) this.cursor = best;
+  }
+
+  private toggleSection(): void {
+    const section = this.layout()?.sections[this.cursor];
+    if (!section) return;
+    this.setExpanded(!this.isExpanded(section.key));
+  }
+
+  private setExpanded(open: boolean): void {
+    const section = this.layout()?.sections[this.cursor];
+    if (!section || this.isExpanded(section.key) === open) return;
+    this.expanded.set(section.key, open);
+    this.invalidate();
+    this.reveal();
+  }
+
+  private switchView(view: "now" | "history"): void {
+    if (this.view === view) return;
+    this.view = view;
+    this.cursor = 0;
+    this.scroll = 0;
+    if (view === "history" && this.historyStatus.kind === "idle" && this.historyCache.size === 0) {
+      this.requestMonth(this.selectedMonth);
+    }
+  }
+
+  /** ←/→ (or [ and ]) walk only the months that actually have a file. */
+  private moveMonth(delta: -1 | 1): void {
+    const months = this.historyMonths;
+    if (months.length === 0) return;
+    const current = this.selectedMonth;
+    let target: string | null;
+    if (current === null) {
+      target = delta > 0 ? months[0] : months[months.length - 1];
+    } else if (delta < 0) {
+      target = [...months].reverse().find((month) => month < current) ?? null;
+    } else {
+      target = months.find((month) => month > current) ?? null;
+    }
+    if (target === null) return;
+    this.selectMonth(target);
+  }
+
+  private selectMonth(month: string): void {
+    this.selectedMonth = month;
+    this.cursor = 0;
+    this.scroll = 0;
+    if (!this.historyCache.has(month)) this.requestMonth(month);
+  }
+
+  private reloadMonth(): void {
+    this.requestMonth(this.selectedMonth);
+  }
+
+  /**
+   * The failure line for the month on screen, or null. A fetch that failed for a
+   * month the user has since left must not paint over the page they are on, and
+   * its "press r to retry" would retry the wrong month.
+   */
+  private historyFailure(): string | null {
+    const status = this.historyStatus;
+    if (status.kind !== "failed") return null;
+    if (this.selectedMonth === null || status.month === null || status.month === this.selectedMonth) return status.message;
+    return null;
+  }
+
+  /** The History page: one section per family, days, models, accounts, totals. */
+  private historyLayout(width: number): { sections: PanelSection[]; tail: string[] } | null {
+    const month = this.selectedMonth;
+    if (month === null) return null;
+    const payload = this.historyCache.get(month);
+    if (!payload) return null;
+
+    /** @type {Map<string, HistoryFamily>} */
+    const families = new Map<string, HistoryFamily>();
+    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() };
+        families.set(family, entry);
+      }
+      return entry;
+    };
+
+    for (const [date, dayFamilies] of Object.entries(payload.days ?? {})) {
+      for (const [family, day] of Object.entries(dayFamilies ?? {})) {
+        const entry = ensure(family);
+        const tokens = Math.max(0, Math.round(Number(day?.tokens) || 0));
+        entry.tokens += tokens;
+        entry.prompts += Math.max(0, Math.round(Number(day?.prompts) || 0));
+        entry.days.set(date, (entry.days.get(date) ?? 0) + tokens);
+        for (const [slot, slotRow] of Object.entries(day?.slots ?? {})) {
+          const label = slot === "" ? "" : `#${slot}`;
+          const account = entry.accounts.get(label) ?? { tokens: 0, prompts: 0, models: new Map<string, number>() };
+          account.tokens += Math.max(0, Math.round(Number(slotRow?.tokens) || 0));
+          account.prompts += Math.max(0, Math.round(Number(slotRow?.prompts) || 0));
+          for (const [model, bucket] of Object.entries(slotRow?.models ?? {})) {
+            const modelTokens = historyModelTokens(bucket);
+            account.models.set(model, (account.models.get(model) ?? 0) + modelTokens);
+            entry.models.set(model, (entry.models.get(model) ?? 0) + modelTokens);
+          }
+          entry.accounts.set(label, account);
         }
-        const band = bandFor(used);
-        const reset = window.resetsInSec === null ? "" : theme.fg("dim", ` · reset in ${humanDuration(window.resetsInSec)}`);
-        lines.push(
-          `  ${label}  ${paint(band.color, band.glyph)} ${paint(band.color, bar(used))} ` +
-            `${paint(band.color, `${used.toFixed(used < 10 ? 1 : 0)}%`.padStart(5))} ` +
-            `${theme.fg("dim", "used")}${reset}`,
-        );
       }
     }
 
-    // Local token stats survive a failed quota probe: the credential may be
-    // rejected while the tokens already burned are still a fact on disk.
-    lines.push(...renderTokenRows(localStats, labelWidth, theme, partialScan));
+    // The current month's open day is not frozen yet, so the month file has no
+    // row for it. Merge today from the live report's localStats, by day key and
+    // never by adding to an existing day: that is what makes double counting
+    // impossible. The guard is per family, because one family the writer froze
+    // today must not hide every other family's live row.
+    //
+    // The *report's* day decides, not the clock: `todayTotalTokens` is the day the
+    // report was generated on. A pi session that crossed midnight still holds
+    // yesterday's totals, and the first frame paints ~/.cache/pi-quota/usage.json,
+    // which can be days old; merging either into today would add a frozen
+    // yesterday to today. A stale report is skipped, and the tail says so.
+    const now = new Date();
+    const today = localDayKey(now);
+    const report = this.options.getReport();
+    const generatedAt = report?.generatedAt ? new Date(report.generatedAt) : null;
+    // An unparseable generatedAt is no evidence of today: it is skipped, silently.
+    const reportDay = generatedAt && !Number.isNaN(generatedAt.getTime()) ? localDayKey(generatedAt) : null;
+    const frozenToday = payload.days?.[today] ?? {};
+    let mergedToday = false;
+    let skippedReportDay: string | null = null;
+    if (month === localMonthKey(now)) {
+      const stats = report?.localStats ?? {};
+      for (const [family, familyStats] of Object.entries(stats)) {
+        if (!familyStats || familyStats.hasLocalStats === false || frozenToday[family]) continue;
+        const tokens = Math.max(0, Math.round(Number(familyStats.todayTotalTokens) || 0));
+        const prompts = Math.max(0, Math.round(Number(familyStats.todayPrompts) || 0));
+        if (tokens === 0 && prompts === 0) continue;
+        // A day the report does not belong to is not today's row, however fresh
+        // it looks: it is skipped whole, and never merged under today's key.
+        if (reportDay !== today) {
+          if (reportDay !== null) skippedReportDay = reportDay;
+          break;
+        }
+        mergedToday = true;
+        const entry = ensure(family);
+        entry.tokens += tokens;
+        entry.prompts += 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)));
+        }
+        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));
+          // 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 ?? {})) {
+            target.models.set(model, (target.models.get(model) ?? 0) + Math.max(0, Math.round(Number(modelTokens) || 0)));
+          }
+          entry.accounts.set(label, target);
+        }
+      }
+    }
+
+    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);
+      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 sectionOf = (family: string): number => {
+      const providers = this.options.getReport()?.providers ?? [];
+      const index = providers.findIndex((provider) => provider.family === family);
+      return index === -1 ? Number.MAX_SAFE_INTEGER : index;
+    };
+    const ordered = Array.from(families.entries()).sort(
+      (a, b) => sectionOf(a[0]) - sectionOf(b[0]) || a[0].localeCompare(b[0]),
+    );
+
+    // Section bodies are indented by four columns in metrics(); the wrap budget
+    // must leave room for that or a long day list is clipped at the right edge.
+    const bodyWidth = Math.max(24, width - 4);
+    const sections: PanelSection[] = [];
+    for (const [family, entry] of ordered) {
+      // Every account the family has in the month *or* all-time: a month in which
+      // one account carried the usage must still show the family's other keys,
+      // or the page hides the very rows that answer "which key burned what".
+      const accountLabels = Array.from(new Set([...entry.accounts.keys(), ...entry.allTimeAccounts.keys()])).sort(
+        (a, b) => slotOrder(a) - slotOrder(b),
+      );
+      // 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);
+      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 body: string[] = [];
+      const label = (text: string) => `  ${this.theme.fg("dim", text.padEnd(6))}  `;
+      const rest = `  ${" ".repeat(8)}`;
+      const dayCells = Array.from(entry.days.entries())
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([date, tokens]) => `${date.slice(5)} ${formatTokens(tokens)}`);
+      body.push(...wrapCells(
+        dayCells.length > 0 ? dayCells : [this.theme.fg("dim", "no frozen days in this month")],
+        label("days"),
+        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)}`);
+        if (top.length > shown.length) shown.push(this.theme.fg("dim", `+${top.length - shown.length} more`));
+        body.push(...wrapCells(shown, label("models"), rest, bodyWidth));
+      }
+      if (accountLabels.length > 1) {
+        const labelWidth = Math.max(...accountLabels.map((text) => text.length));
+        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 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", " · "))}`);
+        }
+      }
+      sections.push({ key: `history:${family}`, header: `${name} ${this.theme.fg("dim", `· ${meta.join(" · ")}`)}`, body });
+    }
+
+    const tail: string[] = [];
+    if (ordered.length === 0) tail.push(this.theme.fg("dim", `no token history for ${month}`));
+    for (const note of payload.notes ?? []) tail.push(this.theme.fg("warning", `! ${note}`));
+    if (mergedToday) {
+      tail.push(this.theme.fg("warning", `~ ${today} comes from the live report; it is not frozen in history yet`));
+    } else if (skippedReportDay !== null) {
+      // The report on screen is older than today, so its open-day totals belong
+      // to another day: say so, or a missing today row reads as a lost day.
+      tail.push(this.theme.fg("dim", `the live report is from ${skippedReportDay}; ${today} is not merged`));
+    }
+    const lastFrozen = payload.totals?.lastFrozenDay || "none";
+    tail.push(this.theme.fg("dim", `frozen through ${lastFrozen} · ${month} · read-only`));
+    return { sections, tail };
   }
-  lines.push(theme.fg("dim", `used % · read-only · ${report.generatedAt}`));
-  if (unconfigured.length > 0) {
-    const names = unconfigured.map((p) => SHORT_NAME[p.family] ?? p.family).join(", ");
-    lines.push(theme.fg("dim", `not configured in Pi: ${names}`));
+
+  private titleLine(): string {
+    const title = this.theme.fg("accent", this.theme.bold("Quota"));
+    if (this.view !== "history") return title;
+    const month = this.selectedMonth === null ? "…" : this.selectedMonth;
+    return `${title} ${this.theme.fg("dim", `· History · ${month}`)}`;
   }
-  for (const warning of report.warnings.slice(0, 3)) {
-    lines.push(theme.fg("warning", `warn: ${warning}`));
+
+  /**
+   * The header's right side: a visible refresh indicator while the CLI runs,
+   * the time the update landed afterwards, the view's position, and the scroll
+   * range when the content is taller than the viewport.
+   */
+  private statusText(total: number, height: number): string {
+    const parts: string[] = [];
+    // History's today row is merged from the live report, so the report's state
+    // (refreshing, its update time, a failed refresh) heads both views.
+    if (this.options.isRefreshing()) {
+      parts.push(this.theme.fg("accent", "refreshing …"));
+    } 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.view === "history") {
+      const status = this.historyStatus;
+      // Only the month on screen reports its own fetch: a fetch for a month the
+      // user already left must not claim the header.
+      const shown = this.selectedMonth;
+      const waitsForShown = shown === null || status.month === null || status.month === shown || !this.historyCache.has(shown);
+      if (status.kind === "loading" && waitsForShown) {
+        parts.push(this.theme.fg("accent", status.month === null ? "loading …" : `loading ${status.month} …`));
+      } else if (this.historyFailure() !== null) {
+        parts.push(this.theme.fg("error", "history failed"));
+      }
+    }
+    if (total > height) {
+      const last = Math.min(total, this.scroll + height);
+      parts.push(this.theme.fg("dim", `${this.scroll + 1}-${last}/${total}`));
+    }
+    return parts.join(this.theme.fg("dim", " · "));
+  }
+
+  /** Hint pairs for the active view; History adds its month navigation. */
+  private legendHints(): ReadonlyArray<readonly [string, string]> {
+    return this.view === "history" ? HISTORY_HINTS : NOW_HINTS;
+  }
+
+  /**
+   * Wrap the legend pairs across as many rows as the width needs, balanced:
+   * greedy filling leaves the last pair alone on a row of its own ("esc/q
+   * close" under seven pairs), which reads as a lost key. The row count is the
+   * minimum greedy needs, so widening the pane never adds a row.
+   */
+  private legendLines(width: number): string[] {
+    const separator = this.theme.fg("dim", " · ");
+    const pairs = this.legendHints().map(([keys, label]) => `${this.theme.fg("dim", keys)} ${label}`);
+    if (pairs.length === 0) return [""];
+    const rows = balanceRows(pairs.map((pair) => visibleLength(pair)), width, 3);
+    const lines: string[] = [];
+    let index = 0;
+    for (const count of rows) {
+      lines.push(pairs.slice(index, index + count).join(separator));
+      index += count;
+    }
+    return lines;
   }
-  return lines;
 }
 
 export default function quotaPanelExtension(pi: ExtensionAPI): void {
@@ -821,10 +2062,15 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
   let agentEndTimer: ReturnType<typeof setTimeout> | null = null;
   let panelVisible = false;
   /**
-   * The panel bare `/usage` opens is a glance, not a pin: it goes away when the
-   * next prompt starts or when `/usage` is run again. `/usage panel` pins it.
+   * The open fullscreen overlay, while there is one. Bare `/usage` opens it and
+   * a background refresh redraws it; closing it leaves nothing behind.
    */
-  let transientPanel = false;
+  let overlayView: UsageOverlay | null = null;
+  /**
+   * What a reopened overlay keeps: every bare `/usage` builds a fresh view, so
+   * the folds and the page live here, for the pi session and never on disk.
+   */
+  let overlaySession = newOverlaySession();
   /**
    * Nothing is pinned by default. A box or line above the editor is a persistent
    * surface, and a quota command should not claim a row until asked.
@@ -869,28 +2115,33 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
     railMode = inspection.state === "patched";
   }
 
-  async function runCli(args: string[]): Promise<QuotaReport | null> {
+  /**
+   * 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.
+   */
+  async function runCli(args: string[], options: { reportErrors?: boolean } = {}): Promise<QuotaReport | null> {
+    const reportErrors = options.reportErrors !== false;
     const cli = resolveCliPath();
     if (!cli) {
-      lastError = "piquota not installed: run install.sh from the pi-quota repo";
+      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() === "") {
-        lastError = result.stderr?.trim() || "piquota produced no output";
+        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)) {
-        lastError = "piquota output was not a quota report";
+        if (reportErrors) lastError = "piquota output was not a quota report";
         return null;
       }
-      lastError = null;
+      if (reportErrors) lastError = null;
       return parsed;
     } catch (error) {
-      lastError = (error as { message?: string })?.message ?? String(error);
+      if (reportErrors) lastError = (error as { message?: string })?.message ?? String(error);
       return null;
     }
   }
@@ -1050,11 +2301,14 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
       if (disposed) return;
       if (next) {
         report = next;
-        paintUi(ctx);
-        void runCli(["omarchy"]);
+        // 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 });
       }
     } finally {
       refreshing = false;
+      overlayView?.redraw();
     }
   }
 
@@ -1063,6 +2317,8 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
     const ui = ctx as unknown as UiContext;
     if (!ui.hasUI) return;
     disposed = false;
+    // A new session starts with every section open, on the Now page.
+    overlaySession = newOverlaySession();
     // Resolve the native rail mode before the first paint.
     await syncRailPatch();
     if (disposed) return;
@@ -1072,17 +2328,7 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
     paintUi(ui);
   });
 
-  function dismissTransientPanel(ui: UiContext): void {
-    panelVisible = false;
-    transientPanel = false;
-    if (!surfaceActive()) stopPolling();
-    paintUi(ui);
-  }
-
-  pi.on("agent_start", (_event, ctx) => {
-    // SAFETY: Pi's agent_start context implements UiContext when hasUI is true.
-    const ui = ctx as unknown as UiContext;
-    if (transientPanel && panelVisible && ui?.hasUI && !disposed) dismissTransientPanel(ui);
+  pi.on("agent_start", () => {
     if (agentEndTimer) {
       clearTimeout(agentEndTimer);
       agentEndTimer = null;
@@ -1124,6 +2370,103 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
     }
   });
 
+  /**
+   * 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.
+   *
+   * 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
+   * "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;
+      }
+      if (!parsed || !Array.isArray(parsed.months)) {
+        overlayView?.setHistoryError(cliFailureLine(result), request);
+        return;
+      }
+      overlayView?.setHistory(parsed, request);
+    } catch (error) {
+      const message = (error as { message?: string })?.message ?? String(error);
+      overlayView?.setHistoryError(capCause(redactCause(message).split("\n")[0]), request);
+    }
+  }
+
+  /**
+   * Bare /usage: a fullscreen overlay that owns the keyboard and closes on Esc,
+   * so no panel is left above the editor. It opens with the cached report and
+   * refreshes in the background; a failure becomes a line in the view.
+   */
+  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();
+    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.
+      panelVisible = true;
+      lineVisible = false;
+      boxVisible = false;
+      explicitBox = false;
+      if (!report) await 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");
+      return;
+    }
+    await custom(
+      (tui, theme, _keybindings, done) => {
+        const view = new UsageOverlay(theme, {
+          done: () => done(undefined),
+          requestRender: () => tui?.requestRender?.(),
+          getRows: () => tui?.terminal?.rows ?? process.stdout.rows ?? 24,
+          getReport: () => report,
+          getError: () => lastError,
+          isRefreshing: () => refreshing,
+          refresh: () => {
+            void refresh(ctx, true);
+          },
+          loadHistory: (month, request) => {
+            void loadHistory(month, request);
+          },
+        }, overlaySession);
+        overlayView = view;
+        // A view reopened on History holds no payload: ask for its month.
+        view.begin();
+        return {
+          render: (width: number) => view.render(width),
+          invalidate: () => view.invalidate(),
+          dispose: () => {
+            if (overlayView === view) overlayView = null;
+            view.dispose();
+          },
+          handleInput: (data: string) => {
+            view.handleInput(data);
+            tui?.requestRender?.();
+          },
+          handleMouse: (event: any) => view.handleMouse(event),
+        };
+      },
+      { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", margin: 0 } },
+    );
+  }
+
   const handler = async (args: string, ctx: UiContext): Promise<void> => {
     if (!ctx.hasUI) return;
     const action = args.trim().toLowerCase();
@@ -1151,7 +2494,6 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
         return;
       case "panel":
         panelVisible = true;
-        transientPanel = false;
         lineVisible = false;
         boxVisible = false;
         explicitBox = false;
@@ -1198,29 +2540,15 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
         break;
     }
 
-    // Bare /usage again while its glance is open closes it.
-    if (panelVisible && transientPanel) {
-      dismissTransientPanel(ctx);
-      return;
-    }
-
-    // Bare /usage: one on-demand refresh, show the panel, report the percentages.
-    panelVisible = true;
-    transientPanel = true;
-    lineVisible = false;
-    boxVisible = false;
-    await refresh(ctx, true);
-    ensurePolling(ctx);
-    paintUi(ctx);
-    if (!report) {
-      ctx.ui.notify(`Quota unavailable: ${lastError}`, "error");
-      return;
-    }
-    ctx.ui.notify(summarize(report) || "No active providers configured in Pi", "info");
+    // 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);
+    await opening;
   };
 
   pi.registerCommand("usage", {
-    description: "Show read-only provider quota on demand (used %, shortest window)",
+    description: "Open the read-only quota overlay (used %, one foldable section per provider)",
     getArgumentCompletions: (prefix: string) => {
       const options = ["refresh", "line", "box", "panel", "hide", "status", "nostatus", "json"];
       const matches = options.filter((option) => option.startsWith(prefix));