@cad0p/pi-usage 0.11.4 → 0.11.5-20261103.1

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.11.5] - 2026-11-03
+
+<!-- USER-EDITABLE SECTION START -->
+A fullscreen `/usage` with browsable history, and a refresh about three times faster.
+
+- **Fullscreen `/usage`:** bare `/usage` opens a view like `/context`. It paints at once from the last report (`refreshing …` until the new one lands, then `updated HH:MM`), keeps an always-visible key legend, folds provider sections, and scrolls with the arrows, `j`/`k`, PgUp/PgDn, `g`/`G` and the mouse wheel. Rows wrap instead of being clipped, so resets stay visible at 64 columns. Folds, page and month persist for the pi session; `esc`/`q` leaves a clean editor.
+- **History:** `tab` (or `1`/`2`) switches to month history: days, models and per-account tokens, `←`/`→` and `[`/`]` walk the months, and today merges from the live report exactly once. Backed by the new read-only `piquota stats --json [--month YYYY-MM]`.
+- **No invented `#1`:** the unnumbered base account carries no suffix on any surface.
+- **Faster refresh:** a provider's accounts are queried in parallel (default 8, `PI_QUOTA_ACCOUNT_CONCURRENCY` 1–32): a forced refresh went from ~2.9 s to ~1.0 s, OpenCode Go's 14 keys from ~3.8 s to ~0.9 s.
+- **User-Agent:** every request sends `pi-usage/<version> (+https://github.com/cad0p/pi-usage)` instead of Node's generic `node` (Antigravity keeps its CLI agent).
+<!-- USER-EDITABLE SECTION END -->
+
+### 🚀 Features
+
+- Fullscreen /usage with month history; no invented "#1" (closes #21, closes #22)
+
+### ⚡ Performance
+
+- Query a provider's accounts in parallel; send the package User-Agent (closes #23)
+
+
 ## [0.11.4] - 2026-11-03
 
 <!-- USER-EDITABLE SECTION START -->

package/README.md

@@ -6,7 +6,7 @@ One source of truth for quota: **the credentials Pi already owns**.
 > `@cad0p/pi-usage` is a fork of [J3pf/piQuota](https://github.com/J3pf/piQuota) (`@j3pf/piquota`). It adds:
 >
 > * **OpenCode Go from the API key**: `GET https://opencode.ai/zen/go/v1/usage` returns the rolling (5h), weekly and monthly windows for the key Pi already stores, so no browser session is needed.
-> * **Numbered accounts**: `auth.json` entries such as `opencode-go-2` … `opencode-go-14` (the [pi-fallback-provider](https://github.com/cad0p/pi-fallback-provider) sibling convention) are read as extra accounts of their base provider.
+> * **Numbered accounts**: `auth.json` entries such as `opencode-go-2` … `opencode-go-14` (the [pi-fallback-provider](https://github.com/cad0p/pi-fallback-provider) sibling convention) are read as extra accounts of their base provider. The accounts of one provider are queried in parallel (8 at a time, `PI_QUOTA_ACCOUNT_CONCURRENCY` from 1 to 32), so 14 OpenCode Go keys cost about one round trip instead of fourteen. Every request carries `User-Agent: pi-usage/<version> (+https://github.com/cad0p/pi-usage)` unless a provider needs its own client string: OpenCode Go asks clients not to use a generic HTTP-library name, and Node's default is `node`.
 > * **One Omarchy tab per provider**: a multi-account provider shows each account's binding window (`#2 · Monthly`) in a single tab, and summarises failed accounts.
 > * **Tokens by day and by model**: the tokens Pi's own session files recorded are folded per provider and shown in `/usage`, in `--json` (`localStats`) and in the Omarchy records, at a bounded scan cost.
 > * **`/usage` on demand**: the Pi command is `/usage` only, and nothing is pinned above the editor or in the footer unless you ask for it. A multi-account provider gets one line per account in the panel.
@@ -32,15 +32,22 @@ shuvquota, and it never writes to a credential file.
 
 ## Hard guarantees
 
-* `~/.pi/agent/auth.json` is opened with `flag: "r"`. Never written, synced or
-  refreshed. Verified with a checksum before and after every run.
+* pi-usage opens `~/.pi/agent/auth.json` with `flag: "r"` and never writes it.
+  CLI and systemd-timer runs are strictly read-only. In the Pi extension only,
+  `getProviderAuth` may ask Pi to renew Anthropic/Codex OAuth under Pi's own
+  cross-process auth lock; pi-usage never writes auth storage itself. Check the
+  auth.json checksum around live runs.
 * No token, refresh token, API key, session cookie or `sessionKey` is printed,
-  logged, cached, or sent anywhere. E-mail identities are redacted in every
-  artifact.
-* Antigravity's access token **may** be refreshed, but only in memory. Google
-  does not rotate that refresh token, so Pi's stored copy stays valid. Claude and
-  Codex are never refreshed, because they **do** rotate and persisting a rotated
-  token would break Pi.
+  logged, or serialized to a file. Tokens are sent only to their provider; the
+  extension holds resolved access tokens in memory for the request. Antigravity's
+  renewed access token stays in a process-local cache until shortly before expiry.
+  E-mail identities are redacted in every artifact.
+* Antigravity may be renewed in memory because Google does not rotate its refresh
+  token. The CLI and timer never refresh Claude/Codex; inside Pi, the extension
+  calls Pi's `getProviderAuth`, which returns fresh OAuth directly or lets Pi
+  renew and persist it under Pi's auth-store lock. pi-usage itself never writes
+  auth.json. Every surface reports the token the run *used*: an Antigravity
+  renewal clears the stale stored-expiry claim; only a failed renewal leaves it.
 * The Claude Code store (`~/.claude/.credentials.json`) is opened read-only too, and
   its refresh token is never even read into memory, so nothing here can rotate a
   token the installed `claude` owns. `~/.claude.json` is read only for the account
@@ -60,7 +67,7 @@ shuvquota, and it never writes to a credential file.
 
   | Path | What |
   | --- | --- |
-  | `~/.cache/pi-quota/usage.json` | the report cache |
+  | `~/.cache/pi-quota/usage.json` | the report cache, with each family's own fetch time |
   | `~/.cache/pi-quota/local-sessions.json` | per-session-file offsets and open token days |
   | `${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-usage/totals.json`, `tokens-YYYY-MM.json` | frozen token history, plus `.corrupt-<ts>` backups for corrupt files |
   | `~/.cache/pi-quota/refresh-state.json` | each family's own refresh clock |
@@ -107,14 +114,17 @@ There are two ways to be signed in to Claude, and a user may have either or both
 | Claude Code CLI | `~/.claude/.credentials.json` (honours `CLAUDE_CONFIG_DIR`); on macOS, when that file is absent, the `Claude Code-credentials` login Keychain item (read-only, via `security find-generic-password`; macOS may ask once to allow access) | What `npm:pi-claude-code-provider` drives. A subscription with usage credits disabled answers `400` on Pi's own entry for every request, and this is the source that still works. |
 | Pi's own entry | `~/.pi/agent/auth.json` → `anthropic` | `/login anthropic` in Pi, without the plugin installed. |
 
-**The Claude Code CLI wins when both are present and its token is still valid.** The
-choice is a *preference, not a fallback*: only the selected source is tried, so a
-broken preferred source is reported rather than silently masked by the other one.
-The one exception is an expired Claude Code token next to a fresh Pi login: a store
-left behind by an uninstalled CLI never refreshes again, so `auto` reads Pi's login
-instead and adds a warning naming the switch. Override it with
-`PI_QUOTA_CLAUDE_SOURCE=pi` or `=claude-code`; `--explain` prints which one was used
-and why.
+For `piquota` CLI and timer runs, the Claude Code CLI wins when both are
+present and its token is still valid. The choice is a *preference, not a fallback*:
+only the selected source is tried, so a broken preferred source is reported rather
+than silently masked by the other one. An expired Claude Code token next to a fresh
+Pi login is passed over in `auto` mode with a warning. Override CLI selection with
+`PI_QUOTA_CLAUDE_SOURCE=pi` or `=claude-code`; `--explain` prints what was used.
+
+Inside Pi, the extension asks Pi's `getProviderAuth("anthropic")` for OAuth first.
+A fresh token is returned as-is; when it is near expiry, Pi renews and persists it
+under its auth-store lock, then the extension uses that returned token in memory.
+If Pi has no OAuth login, the configured source preference applies.
 
 The Claude Code store is opened read-only, and its refresh token is deliberately
 **never carried into memory**: Anthropic rotates refresh tokens, and a rotation
@@ -174,10 +184,10 @@ When you also run `install.sh` for the terminal CLI, pass
 | `piquota` on your `PATH` for terminal use | no | yes, symlinked |
 | Omarchy sync while Pi is closed | no | yes, with `--omarchy-timer` |
 
-If you live inside Pi and use Omarchy, the npm route covers it: the extension
-runs `piquota omarchy` on every quota refresh, so the bar fills without any
-setup. Choose `install.sh` when you want the CLI in a terminal, or background
-sync while Pi is not running.
+If you live inside Pi and use Omarchy, the extension publishes each
+provider's record in-process as soon as that family finishes, then prunes stale
+records once the complete refresh settles. Choose `install.sh` when you want the
+CLI in a terminal, or background sync while Pi is not running.
 
 ### Manual Install / Development
 
@@ -223,6 +233,9 @@ piquota auth opencode --wait 300
 
 piquota omarchy                 # write pi-*.json records for Omarchy's Agents panel
 piquota stats                   # durable token history: last frozen day, families, totals
+piquota stats --json --month 2026-11
+                                # read-only history feed: months, one month's days
+                                # per family/slot/model, all-time totals, notes
 piquota stats --rebuild-totals  # recompute totals.json from the frozen month files
 ```
 
@@ -242,7 +255,7 @@ Inside Pi:
 
 | Command | Effect |
 | --- | --- |
-| `/usage` | one on-demand refresh, show the full panel until the next prompt (or a second `/usage`), notify a one-line summary |
+| `/usage` | open the fullscreen quota overlay: every provider, window, account and token row, folded by section, refreshed in the background; `tab` opens the month history; `esc` closes it |
 | `/usage box` | pin the five-row box above the editor |
 | `/usage line` | pin the compact line above the editor, in its own row |
 | `/usage panel` | full panel above the editor, pinned across prompts |
@@ -253,18 +266,99 @@ Inside Pi:
 
 ### The Pi surface
 
-Nothing is pinned by default: `/usage` is a one-shot command, so it claims no row
-above the editor and leaves the footer alone. Turn a surface on with `/usage box`,
-`/usage line`, `/usage panel` or `/usage status`; only then does the extension keep
-it fresh with a background refresh (and a gentle refresh after each agent turn).
-`/usage hide` gives the row back.
+Nothing is pinned by default: `/usage` opens a **fullscreen overlay** that takes
+the keyboard, so it claims no row above the editor and leaves the footer alone.
+It is the same `ctx.ui.custom` overlay pattern pi's `/context` uses: it fills the
+terminal, scrolls, folds and closes on Esc (or `q`), leaving nothing behind.
+Turn a persistent surface on with `/usage box`, `/usage line`, `/usage panel` or
+`/usage status`; only then does the extension keep it fresh with a background
+refresh (and a gentle refresh after each agent turn). `/usage hide` gives the row
+back. `/usage panel` still pins the same panel flat above the editor.
+
+The overlay paints on the same keystroke: it renders the report the extension
+already holds, or the on-disk report cache (`~/.cache/pi-quota/usage.json`) when
+memory is empty. That cache is keyed by the Claude source the numbers in it came
+from, so a report fetched with Pi's own OAuth is stored under Pi's key and a
+reader that asked for Claude Code is not served it. It never waits for network work before the first frame. Opening
+`/usage` refreshes only families older than their own clock (60 seconds by
+default; Claude's 300-second throttle-safe interval is preserved); `r` forces
+all enabled families. Families run independently and repaint as they finish. A
+failed family is a line in the view — one line per family, kept until that family
+succeeds again, so an out-of-order success cannot hide another one's failure —
+never a thrown error. The local session
+scan runs in a Node worker thread, not on the TUI event loop, and a shutdown or
+`/reload` stops it mid-scan: it releases its history lock and writes nothing.
+Every provider is a section:
+the header is the brand-coloured name line, the body lists every window with its
+used-fraction bar, reset countdown and the token rows for today, the last seven
+days, the prompts and the heaviest models. All sections start expanded; the fold
+state and the page you left live for the pi session, so reopening `/usage`
+resumes them, and no file is written.
+
+| Key | Action |
+| --- | --- |
+| `↑`/`↓`, `j`/`k` | move the header cursor; a section taller than the viewport scrolls line by line first |
+| `enter` / `space` | fold or unfold the section under the cursor |
+| `→`/`l`, `←`/`h` | expand, collapse |
+| `PgUp`/`PgDn`, `g`/`Home`, `G`/`End` | page, first section, last section |
+| mouse wheel | scroll |
+| `r` | refresh in place (on History: the month and the live report) |
+| `tab`, `1` / `2` | switch between Now and History |
+| `esc` / `q` | close |
+
+The legend at the bottom lists every key the current view answers, and wraps
+into a second or third row on a narrow pane instead of dropping pairs — as few
+rows as fit, with the pairs balanced across them. The frame
+fits from about 60 columns up: a line wider than the terminal wraps at its
+` · ` separators with a hanging indent instead of being cut, so a row never
+loses the datum it ends with, and a resize rebuilds it. The wheel is handled by the component itself, like
+pi-context-view: pi routes fullscreen wheel events to the focused component but
+has no scrolling API for a custom screen, and this extension has no runtime
+dependencies to wrap the body in a `ScrollView`.
+
+`tab` (or `2`) opens **History**, the second page: the durable token history for
+one month, with the same foldable sections. A provider section lists the month's
+days, the prompt count for that month and for all time, the token split by
+model, and — for a multi-account provider — one row per account with its month
+and all-time totals (every account the family has in the month *or* all-time, so
+one busy key does not hide the others). `←`/`→` (or
+`[`/`]`) walk the browsable months — those with a file, plus the live month,
+which is where History opens even before its first freeze — and `tab` (or `1`)
+comes back to Now. The all-time
+figure is `totals.json` (frozen through its watermark) plus, when it is merged,
+the same open day the month counts, so today is never missing from it. A rollup
+that cannot cover the month on screen — a freeze whose totals write failed, a
+month file restored behind `totals.json` — is still printed, dimmed, with
+`~ all-time lags this month; run piquota stats --rebuild-totals` above the rows:
+the figure is the only answer to "how much has this burned ever", so it is
+explained rather than dropped. A family's open day
+(today) is merged from the live report only when the report was *generated* today
+and the frozen month has no row for that family's day — per family, so one family
+frozen early never hides another's live row — and a day is counted exactly once.
+A report generated before midnight, or the older report cache painted on the first
+frame, is skipped: its `todayTotalTokens` belong to another day, and merging them
+under today would count a frozen yesterday twice. The tail then names the report's
+day and says today is not merged. A missing or quarantined month is a note instead
+of rows, a failed history read is redacted and shown with a retry hint, and a slow
+read never moves the page off the month the last keypress asked for.
+
+The extension reads the same `historyJson` payload in-process; the CLI exposes
+it as `piquota stats --json [--month YYYY-MM]`: the month list, one month's days
+per family/slot/model, the all-time rollup and notes. The read path never takes
+the writer lock and never writes, so it is safe while a scan is freezing a day. Everything it reports is frozen: `lastFrozenDay` is its
+watermark, and neither `piquota stats` nor its JSON moves an open day into a
+total. The History page merges the live day itself, for the month and for the
+all-time figures alike, and prints the same "comes from the live report" note
+under both.
 
 A provider with several accounts is shown as one header (`OP-Go · 7 of 14 accounts
 ok`) plus one line per account with every window and its reset, e.g.
 `#2 ● session 2% (10m) · week 10% (6d) · month 90% (19d)`, or the reason it failed
-(`key rejected`, `no Go plan`). The leading glyph is the fullest window's band. The panel is rendered as a component, so Pi's ten-line
-cap on plain widgets never truncates it, and the summary names the account with the
-most room: `OP-Go: 7/14 ok · lowest 24% (#7)`.
+(`key rejected`, `no Go plan`). The base entry in `auth.json` (`opencode-go`) has
+no number, so its label column is blank; only real sibling slots (`opencode-go-2`
+…) are numbered `#2` … `#14`. The leading glyph is the fullest window's band. The
+overlay and the pinned panel are rendered as components, so Pi's ten-line cap on
+plain widgets never truncates them.
 
 `/usage box` pins the **five-row box above the editor**:
 
@@ -373,6 +467,12 @@ Rp suite) without external network daemons or closed-source intermediaries:
 * **Percentages and Countdown**: `usedPercent` and `remainingPercent` report
   percentages (0..100); `resetsInSec` provides the exact integer seconds until
   reset, immune to local clock skew.
+* **`expiresInMin` and `tokenRenewedInMemory`**: the freshness of the credential the
+  run actually used. Antigravity's token is renewed in memory, so its result
+  carries `tokenRenewedInMemory: true` and `expiresInMin: null` instead of Pi's
+  stale stored countdown; a renewal that failed keeps the stored value, which is
+  what the panel's `token EXPIRED` badge and the warning line describe. The field
+  is only present when a renewal happened.
 * **`notConfigured` vs `ok`**: unconfigured providers report `notConfigured: true`,
   allowing consumers to cleanly omit them without displaying false-positive
   error indicators.
@@ -440,7 +540,7 @@ seven entries, oldest first, today last):
       "activeDays": 11,
       "activeDates": ["2026-10-27"],
       "modelUsage": { "gpt-5.1-codex": { "inputTokens": 4, "outputTokens": 425, "cacheReadInputTokens": 6838, "cacheCreationInputTokens": 6905 } },
-      "byAccount": { "#1": { "todayTokens": 14172, "weekTokens": 118422, "todayPrompts": 3, "totalPrompts": 1200, "totalTokens": 48812210 } }
+      "byAccount": { "": { "todayTokens": 14172, "weekTokens": 118422, "todayPrompts": 3, "totalPrompts": 1200, "totalTokens": 48812210 } }
     }
   },
   "localStatsMeta": { "files": 604, "scanned": 1, "reused": 603, "bytesRead": 3042, "durationMs": 9, "partial": false, "budgetMs": 12000, "frozenDays": 0, "locked": false }
@@ -488,7 +588,9 @@ piquota omarchy                  # write pi-claude.json, pi-codex.json, ... once
   `auth.json`) still gets **one** record: every healthy account contributes only
   the window that constrains it, titled `#<slot> · Session|Weekly|Monthly`, and
   failed accounts add no rows but are summarised by reason, e.g.
-  `#8–#10 key rejected · #11–#14 no Go plan`. The same record also carries
+  `#8–#10 key rejected · #11–#14 no Go plan`. The unnumbered base entry keeps a
+  blank `id` and its limits are untitled; only real sibling slots carry
+  `#<slot>`. The same record also carries
   `accounts[{id, ok, status, limits}]` with every window of every account
   (`status` is a short reason such as `Key rejected` for a failed one), which
   Omarchy's built-in panel ignores and this package's own plugin draws.
@@ -510,7 +612,8 @@ is a collapsible section of one scrolling panel.
   with its window and reset (`Weekly · 1d`), a chip when something is wrong
   (`Unavailable`, `7 down`), and the headline meter while folded. The headline is
   the fullest window; for a multi-account provider it is the healthy account
-  with the most room left, the `lowest` figure `/usage` prints.
+  with the most room left. `/usage` does not collapse a family like that: its
+  panel lists one line per account, so this headline is the bar's own summary.
 - **Expanded**: the status card, LIMITS with the built-in meters and countdowns,
   then for a multi-account record one row per account with every window
   (`#2  session 2% 10m · week 10% 6d · month 90% 19d`, failed accounts dimmed
@@ -582,6 +685,8 @@ shows them next to the quota:
 | `/usage` panel | a `tokens` row per provider: today, 7 days, prompts, then the top 3 models of the week |
 | `piquota omarchy` | the optional fields Omarchy's Agents panel draws as "Tokens by day" and "Tokens by model" |
 | `piquota stats` | the durable history: last frozen day, families, prompts, session-days |
+| `/usage` → `tab` | History: per provider, the month's days and models, account totals for a multi-account family, and the all-time rollup |
+| `piquota stats --json` | the same history as a read-only JSON feed (`--month YYYY-MM` selects a month) |
 
 What counts: one assistant message with a non-zero token count is one prompt,
 and its tokens are `input + output + cacheRead + cacheWrite` — the same sum the
@@ -755,7 +860,7 @@ extensions/quota-panel.ts      Pi TUI line and /usage
 ## Tests
 
 ```bash
-node --test tests/*.test.mjs     # 354 tests, fake tokens only, no network
+node --test tests/*.test.mjs     # 441 tests, fake tokens only, no network
 ```
 
 Modules covered: `auth.json` parsing and de-duplication, the Claude Code store

package/bin/piquota.js

@@ -57,7 +57,7 @@ Usage:
   piquota auth <opencode|status> [flags]
   piquota gentle-pi <status|apply|revert>
   piquota omarchy
-  piquota stats [--rebuild-totals]
+  piquota stats [--json] [--month YYYY-MM] [--rebuild-totals]
 
 Quota:
   --json             Emit the normalized report as JSON (for rp-host and automations)
@@ -73,6 +73,7 @@ Quota:
   --explain          Show which stores/fields are read (names only)
   --clear-cache      Delete the local cache and exit
   --rebuild-totals   With \`stats\`: rebuild the token-history totals from its month files
+  --month YYYY-MM    With \`stats\`: read one month (default: the current local month)
   --version          Print the version and exit
 
 Auth (OpenCode Go session, the only credential Pi does not store):
@@ -86,6 +87,9 @@ Auth (OpenCode Go session, the only credential Pi does not store):
 Stats:
   piquota stats                    summarise the durable token history
                                    (dir: \${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-usage)
+  piquota stats --json [--month]   read-only JSON: months (the live month always),
+                                   one month's days per family/slot/model, all-time
+                                   totals, notes
   piquota stats --rebuild-totals   recompute totals.json from the frozen month files
 
 Omarchy:
@@ -96,6 +100,7 @@ Omarchy:
 Environment:
   PI_QUOTA_LOCAL_STATS=0          skip the token scan of Pi's session files
   PI_QUOTA_LOCAL_STATS_BUDGET_MS  wall-clock budget for that scan (default 12000)
+  PI_QUOTA_ACCOUNT_CONCURRENCY    accounts of one provider queried at once (1-32, default 8)
 
 Guarantees:
   * ~/.pi/agent/auth.json is opened read-only. Never written, synced or refreshed.
@@ -161,15 +166,31 @@ async function main() {
     return 2;
   }
 
+  if (args.month && command !== "stats") {
+    err("--month only works with \`piquota stats\`\n");
+    process.stdout.write(HELP);
+    return 2;
+  }
+
   if (command === "stats") {
-    return runStatsCommand({ rebuild: args.rebuildTotals, env: process.env });
+    return runStatsCommand({ rebuild: args.rebuildTotals, json: args.json, month: args.month, env: process.env });
   }
 
   if (command === "omarchy") {
-    const load = async () => {
+    const load = async ({ onFamily } = {}) => {
       const everyFamily = enabledFamilies({ env: process.env });
+      const publishFamily = onFamily
+        ? async (family, fragment) => onFamily(family, mergeLastGood(fragment, {}).report)
+        : undefined;
       const loadFresh = () =>
-        collectQuota({ families: everyFamily, timeoutMs: args.timeoutMs, refresh, force: args.force, localStats: LOCAL_STATS });
+        collectQuota({
+          families: everyFamily,
+          timeoutMs: args.timeoutMs,
+          refresh,
+          force: args.force,
+          localStats: LOCAL_STATS,
+          onFamily: publishFamily,
+        });
       const fresh = args.noCache
         ? await loadFresh()
         : (await withCache({ ttlMs: args.ttlMs, force: args.force, families: everyFamily, key: CACHE_KEY }, loadFresh)).report;