@cad0p/pi-usage 0.11.3 → 0.11.4

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.11.4] - 2026-11-03
+
+<!-- USER-EDITABLE SECTION START -->
+Token history, a scrolling bar panel, and Antigravity from Pi's own login.
+
+- **Token stats from Pi's sessions:** tokens by day and by model per provider and account, read from `~/.pi/agent/sessions` with no extra credential. Incremental (a warm run reads only appended bytes) and durable: finished days are frozen into `${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-usage/` (`totals.json` + `tokens-YYYY-MM.json`) and survive session deletion and cache loss. Shown in `/usage` and in the Omarchy records; `piquota stats` inspects the history.
+- **AI Usage bar plugin (`cad0p.pi-usage`):** looks like Omarchy's Agents panel, but every provider is a collapsible section of one scrolling panel, multi-account providers list every window of every account, and tokens by day and by model are drawn as in the built-in. `install.sh --omarchy-plugin` links it from the pi package, so `pi update` updates it.
+- **No more writes into other Omarchy plugins:** `piquota omarchy` stopped copying provider marks into every `~/.config/omarchy/plugins/*/assets`.
+- **`/usage` glance:** bare `/usage` closes on the next prompt or a second `/usage` (`/usage panel` still pins), and each account line shows session, week and month.
+- **Antigravity:** read from Pi's `google-antigravity` login (the legacy `antigravity` key still works).
+- `docs/verification.md`: the checklist every change follows.
+<!-- USER-EDITABLE SECTION END -->
+
+### 🚀 Features
+
+- *(local)* Token stats by day and by model from Pi's session files (closes #16)
+- *(omarchy)* AI Usage bar plugin, every provider a collapsible section (closes #18)
+
+### 🐛 Bug Fixes
+
+- *(extension)* /usage glance closes on the next prompt; every window per account (closes #9)
+- *(auth)* Read Antigravity from Pi's google-antigravity login (closes #12)
+
+### 📚 Documentation
+
+- Add the verification checklist every change follows (closes #14)
+
+
 ## [0.11.3] - 2026-11-02
 
 <!-- USER-EDITABLE SECTION START -->

package/README.md

@@ -8,6 +8,7 @@ One source of truth for quota: **the credentials Pi already owns**.
 > * **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.
 > * **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.
 > * **No dead Claude store**: `auto` passes over an expired Claude Code token when Pi's own `anthropic` login is fresh, and says so in the warnings.
 >
@@ -17,7 +18,7 @@ One source of truth for quota: **the credentials Pi already owns**.
 shuvquota, and it never writes to a credential file.
 
 > [!TIP]
-> **Working with AI Agents?** See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for architectural boundaries, test runner commands, and hard invariants for AI coding agents.
+> **Working with AI Agents?** See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for architectural boundaries, test runner commands, and hard invariants for AI coding agents, and [docs/verification.md](docs/verification.md) for the verification checklist every change follows.
 
 | Surface | Command |
 | --- | --- |
@@ -49,11 +50,19 @@ shuvquota, and it never writes to a credential file.
   endpoint is gone and no session cookie is configured.
 * `/usage` never injects quota into the LLM context: the extension only calls
   `ui.setStatus`, `ui.setWidget` and `ui.notify`.
+* Pi's session files (`~/.pi/agent/sessions/**/*.jsonl`) are opened read-only, to
+  count tokens per day and per model. The scan cache keys each file by its path,
+  size and byte offset and stores open days; the durable history under
+  `~/.pi/agent/pi-usage/` stores frozen days. Both hold only aggregate counts and
+  model names — no prompt text or tool output reaches a cache, a record or the
+  report.
 * Nothing is written outside these paths:
 
   | Path | What |
   | --- | --- |
   | `~/.cache/pi-quota/usage.json` | the report cache |
+  | `~/.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 |
   | `~/.cache/pi-quota/last-published.json`, `last-good.json`, `backoff.json` | sticky snapshots and throttle state |
   | `~/.config/pi-quota/opencode-cookie` | only after `piquota auth opencode`, mode `600` |
@@ -65,7 +74,7 @@ shuvquota, and it never writes to a credential file.
 | --- | --- | --- | --- |
 | Claude | Claude Code CLI store, else `anthropic.access` | `GET api.anthropic.com/api/oauth/usage` | ✅ 5h + weekly + plan |
 | Codex | `openai-codex.access` + `accountId` | `GET chatgpt.com/backend-api/wham/usage` | ✅ 5h + weekly + plan |
-| Antigravity | `antigravity.access` + `projectId` | `POST cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary` | ✅ Gemini + Claude/GPT buckets, **with in-memory refresh** |
+| Antigravity | `google-antigravity.access` (or legacy `antigravity`) + `projectId` | `POST cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary` | ✅ Gemini + Claude/GPT buckets, **with in-memory refresh** |
 | OpenCode Go | `opencode-go.key`, numbered siblings included | `GET opencode.ai/zen/go/v1/usage` | ✅ 5h + weekly + monthly per account; the session cookie and SSR dashboard are a base-account fallback |
 | GitHub Actions (opt-in) | Authenticated `gh` CLI | `gh api /organizations/<org>/settings/billing/usage/summary?product=Actions` | ✅ org-wide monthly Linux minutes, plan-derived allowance |
 
@@ -177,6 +186,7 @@ git clone https://github.com/cad0p/pi-usage.git
 cd pi-usage
 ./install.sh                 # --link for development, --uninstall to remove
 ./install.sh --no-extension  # CLI only; keep the Pi extension installed as a package
+./install.sh --omarchy-plugin  # also link the AI Usage bar plugin (see Omarchy integration)
 ```
 
 No sudo. It validates Node, Pi and Gentle AI, reports which Claude source it found,
@@ -212,6 +222,8 @@ piquota auth opencode --no-browser
 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 --rebuild-totals  # recompute totals.json from the frozen month files
 ```
 
 Colours: green above 50% remaining, yellow 20–50%, red below 20%.
@@ -230,10 +242,10 @@ Inside Pi:
 
 | Command | Effect |
 | --- | --- |
-| `/usage` | one on-demand refresh, show the full panel, notify a one-line summary |
+| `/usage` | one on-demand refresh, show the full panel until the next prompt (or a second `/usage`), notify a one-line summary |
 | `/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 boxed panel above the editor |
+| `/usage panel` | full panel above the editor, pinned across prompts |
 | `/usage hide` | hide the panel/line and stop background refresh until a surface is on again |
 | `/usage status` / `nostatus` | enable/disable the footer status |
 | `/usage refresh` | refresh only |
@@ -248,8 +260,9 @@ it fresh with a background refresh (and a gentle refresh after each agent turn).
 `/usage hide` gives the row back.
 
 A provider with several accounts is shown as one header (`OP-Go · 7 of 14 accounts
-ok`) plus one line per account: its fullest window, or the reason it failed (`key
-rejected`, `no Go plan`). The panel is rendered as a component, so Pi's ten-line
+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)`.
 
@@ -363,6 +376,10 @@ Rp suite) without external network daemons or closed-source intermediaries:
 * **`notConfigured` vs `ok`**: unconfigured providers report `notConfigured: true`,
   allowing consumers to cleanly omit them without displaying false-positive
   error indicators.
+* **`localStats`**: the tokens Pi's own session files recorded, per family,
+  shaped exactly like the fields Omarchy's Agents panel reads (today, the last
+  seven local days, all-time per-model buckets) plus a `byAccount` breakdown for
+  numbered siblings. `localStatsMeta` says how the scan went.
 
 ```json
 {
@@ -403,6 +420,33 @@ Rp suite) without external network daemons or closed-source intermediaries:
 }
 ```
 
+The token part of the same report is abridged here (`recentDays` always carries
+seven entries, oldest first, today last):
+
+```json
+{
+  "localStats": {
+    "codex": {
+      "hasLocalStats": true,
+      "hasPromptStats": true,
+      "todayTotalTokens": 14172,
+      "todayPrompts": 3,
+      "todaySessions": 1,
+      "todayTokensByModel": { "gpt-5.1-codex": 14172 },
+      "weekTokensByModel": { "gpt-5.1-codex": 118422 },
+      "recentDays": [{ "date": "2026-10-27", "messageCount": 0 }],
+      "totalPrompts": 1200,
+      "totalSessions": 42,
+      "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 } }
+    }
+  },
+  "localStatsMeta": { "files": 604, "scanned": 1, "reused": 603, "bytesRead": 3042, "durationMs": 9, "partial": false, "budgetMs": 12000, "frozenDays": 0, "locked": false }
+}
+```
+
 ### Each provider refreshes on its own clock
 
 Anthropic's usage endpoint answers `429` when polled every minute; Codex,
@@ -434,7 +478,9 @@ piquota omarchy                  # write pi-claude.json, pi-codex.json, ... once
 
 - Records are named `pi-<family>.json`, so they never overwrite Omarchy's own
   `claude.json` / `codex.json`. They hold plan names, used percentages, window
-  labels and reset times only; no tokens, accounts or e-mail addresses.
+  labels, reset times, and — when the token scan has run — aggregate token counts
+  per local day and per model (`hasLocalStats`, `recentDays`, `modelUsage`).
+  No prompt text, session path, account or e-mail address is copied.
 - A provider with a failing sign-in shows a status and a help line instead of
   limits. A provider that is not configured gets no record, and a stale
   `pi-*.json` is removed on the next run.
@@ -442,13 +488,219 @@ 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`.
+  `#8–#10 key rejected · #11–#14 no Go plan`. 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.
 - Omarchy's native collector already tracks Claude with richer local statistics, so
   `piquota omarchy` automatically skips `claude` and cleans up duplicate `pi-claude.json`
   files when `claude.json` exists in the usage directory (override with `PI_QUOTA_OMARCHY_SKIP`).
 - `PI_QUOTA_OMARCHY_DIR` overrides the output directory. `./install.sh --uninstall`
   removes the timer and the `pi-*.json` records.
 
+### The AI Usage bar plugin
+
+The package also ships its own Omarchy bar widget, `cad0p.pi-usage` ("AI
+Usage", in [`omarchy/cad0p.pi-usage/`](omarchy/cad0p.pi-usage/)). It is derived
+from Omarchy's built-in Agents plugin (MIT, by Omarchy) and reuses the shell's
+own panel components, so it looks the same, but it has no tabs: every provider
+is a collapsible section of one scrolling panel.
+
+- **Header row**: the provider's mark, name and plan, the headline percentage
+  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.
+- **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
+  with their reason), then TOKENS BY DAY and TOKENS BY MODEL whenever the record
+  carries local statistics, drawn exactly as the built-in draws them.
+- **Which section is open**: on first use, only the provider closest to a limit
+  (ties go to the earliest reset). Every expand or collapse you make sticks,
+  across popup opens and shell restarts, in
+  `~/.local/state/omarchy/settings/cad0p.pi-usage.json`.
+- **Keys**: `j`/`k` or the arrows walk the section headers (a tall open section
+  scrolls first), Enter or Space toggles, `l`/`h` expand/collapse, `r` refreshes,
+  Tab moves to the neighbouring bar panel, Esc closes. The mouse wheel scrolls;
+  a click on a header toggles it.
+- **Records**: every `*.json` in the usage directory, Omarchy's own included.
+  A provider is hidden by `providers.<id>.enabled = false` in the widget's
+  settings, the same switch the built-in uses. The plugin does **not** support
+  the built-in Agents widget's synced cross-device aggregation
+  (`syncMode`, `syncDir`, `syncFileName`, `syncDeviceId`). Users who rely on
+  synced aggregation should keep the built-in widget; this plugin is not a full
+  replacement for it.
+- **Refresh**: the systemd timer and the Pi extension already publish the
+  `pi-*.json` records, so the plugin never schedules `piquota`. `r`, a middle
+  click or `omarchy-shell cad0p.pi-usage refresh` starts
+  `piquota-omarchy.service` (or runs the package's `piquota omarchy` when there is
+  no unit). Omarchy's collectors (`omarchy-agent-usage-update`) run on the
+  `refreshIntervalSec` timer and for a record's `retryAdvised` retry, and only
+  while the built-in Agents widget is off the bar (`omarchyCollectors`: `Auto`,
+  `On` or `Off`, where `Off` never runs them), so keeping both never doubles the
+  work.
+
+Install it by linking it into Omarchy's plugin directory; the link points into
+the pi package when there is one, so `pi update` updates the plugin too:
+
+```bash
+./install.sh --omarchy-plugin                          # symlink ~/.config/omarchy/plugins/cad0p.pi-usage (idempotent)
+omarchy plugin enable cad0p.pi-usage                   # put it on the bar (right section)
+omarchy bar put cad0p.pi-usage --after omarchy.agents  # or: right next to the built-in Agents icon
+omarchy plugin disable omarchy.agents                  # optional: drop the built-in widget
+```
+
+Without the installer, the link is
+`ln -s ~/.pi/agent/npm/node_modules/@cad0p/pi-usage/omarchy/cad0p.pi-usage ~/.config/omarchy/plugins/cad0p.pi-usage`
+followed by `omarchy-shell shell rescanPlugins`. To hide providers, pass the whole
+object, as with the built-in:
+`omarchy bar set cad0p.pi-usage providers '{"fireworks":{"enabled":false}}' --json`.
+Remove it with `omarchy plugin disable cad0p.pi-usage` and
+`rm ~/.config/omarchy/plugins/cad0p.pi-usage` (`./install.sh --uninstall` removes
+the link too); `omarchy plugin enable omarchy.agents` brings the built-in back.
+
+IPC: `omarchy-shell cad0p.pi-usage <open|close|toggle|refresh>`, plus
+`expand <id>` / `collapse <id>` (e.g. `expand pi-opencode-go`).
+
+`tests/omarchy-harness/render.sh [out-dir] [--light]` renders the panel offscreen
+to PNGs against fixture records, with Omarchy's real components and the current
+theme, next to the built-in panel for comparison. It never touches the running
+shell.
+
+## Token stats from Pi's own sessions
+
+Pi writes every assistant message's `usage` block into
+`~/.pi/agent/sessions/**.jsonl` (plus `~/.omp/agent/sessions` when the omp fork
+is installed; `PI_CODING_AGENT_DIR` relocates the Pi agent directory). piQuota
+folds those messages into tokens per local day and per model, per provider, and
+shows them next to the quota:
+
+| Where | What |
+| --- | --- |
+| `piquota --json` | `localStats.<family>` — the Omarchy-shaped counters plus `byAccount` |
+| `/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 |
+
+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
+Omarchy panel renders. Messages are bucketed by **local** date (the panel calls
+the last row "Today"). Only providers piQuota can bill are counted:
+`anthropic`, `openai-codex`, `antigravity`, `opencode-go` and their numbered
+siblings, so `opencode-go-7` is account `#7`. Providers it does not manage
+(`deepinfra`, `xai`, ...) are ignored, and so is the custom `claude-bridge`
+provider: its tokens are not a Pi subscription.
+
+**Two stores, two lifetimes.** Open days (normally just today) live in the
+disposable scan cache. Once a local day is over it is frozen into a durable
+history that no rescan, no cache wipe and no session deletion can rewrite. The
+history is Pi data, so it lives next to Pi's agent directory:
+
+| Path | What |
+| --- | --- |
+| `${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-usage/totals.json` | all-time rollup per family and account (models, prompts, session-days, active dates) plus `lastFrozenDay` |
+| `${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-usage/tokens-YYYY-MM.json` | the frozen days of one local month, keyed day → family → slot → model |
+| `~/.cache/pi-quota/local-sessions.json` | per-session-file size, mtime, byte offset and copy fingerprint, open days, and pending late deltas for unreadable months |
+
+> `~/.pi` is often a git repository. Add `agent/pi-usage/` to that repo's
+> `.gitignore` if you do not want your token counts committed.
+
+Freezing: every run moves each day before today that is not frozen yet into its
+month file and into `totals.json`, then drops it from the per-file cache. The
+month file is written first and the totals second; the `lastFrozenDay` watermark
+makes a restart re-freeze a half-written day idempotently (the month write is a
+SET per day) instead of adding it twice. A late write to an already-frozen day —
+a session that appends just past midnight — increments both stores directly; if
+its month is temporarily unreadable, the delta stays in the cache until a later
+run can write it. Such a held delta lives only in the disposable cache: if the
+cache is lost before the month becomes writable, that delta is dropped, because
+the bytes of a frozen day are never read again. A crash between the month and totals writes can double that
+one small delta. A budget-truncated scan never freezes: history is only written
+from complete runs.
+
+Consequences, all covered by tests: history survives session deletion and cache
+loss. A lost or corrupt `totals.json` is moved aside as
+`totals.json.corrupt-<ts>` and **rebuilt from the month files**, which are the
+authoritative record of frozen days — not from the session files, because a
+session deleted since then would otherwise shrink history. Frozen days are never
+recomputed, so a replaced session file cannot rewrite them either.
+
+Damaged month files are handled without rebuilding frozen days from sessions. A
+month that cannot be *read* (permissions, I/O) is left alone: the run warns, keeps
+its open days in the cache, and does not freeze them until the month is readable.
+Other history proceeds normally, and this alone does not force a full session
+rescan. A rollup rebuild never writes `totals.json` from an incomplete month set.
+
+A *corrupt* or foreign-version month is moved aside by the lock owner (never by a
+read-only run) to `.corrupt-<ts>`. Its warning names the file and directs you to copy the
+`.corrupt-<ts>` backup back to the original month path if recoverable, or to delete
+the backup to abandon those counts. Until one of the two happens, freezing stops at
+that month for *every* later day too (the frozen watermark only moves forward), so
+later days stay open in the cache and each run repeats the warning; once the backup
+is restored or deleted, the held days freeze on the next run. Frozen days are never rebuilt from sessions: their
+daily rows are missing (shown as 0) in `recentDays`, while `totals.json` retains
+the all-time counts, so the two views may disagree. `piquota stats --rebuild-totals`
+refuses while a quarantined month has not been restored. A lost *month* file
+loses that month's daily detail; normal runs keep the all-time totals, and a
+rebuild can recover counts from every remaining month file even if sessions are
+gone. Rebuild refuses when there is no month file at all while `totals.json`
+still has data, because replacing that rollup with an empty one would turn a
+missing directory into permanently lost history. A normal run reads only
+`totals.json` plus the month files covering the last seven days (current month,
+and the previous one early in a month), so years of history never slow a run: on
+this machine 45 frozen days cost ~28 KB in total — `totals.json` 6.9 KB and two
+month files of 5.4 KB and 16 KB. A day inside that window is read from its month
+file once frozen, so late writes appear in "tokens by day" without waiting for
+the week to roll over.
+
+Cost: the first run streams each session file once — 1.56 GB across 608 files
+in 3.0 s here; later runs read only the bytes appended since the previous scan
+(59 ms of scanning for the whole store, ~20 KB read), and every byte is parsed
+once in normal operation. The CLI's own wall time is dominated by the provider
+calls either way.
+
+What forces a file to be read from its first byte (a *rescan*, in which frozen
+days are skipped and only open days are rebuilt): the cache missing or corrupt,
+the file replaced or now shorter, a path the cache has never seen (a copy, a
+move, a restored backup — its old days were already frozen under its previous
+path), or the same size with a new mtime (an in-place rewrite of the same
+length). An append only reads the new bytes. The one rewrite this cannot see is
+one that restores both the size *and* the mtime, which no stat-based check can
+detect. The cache is atomic and `0600`.
+
+Two writers are routine here (the systemd timer and `/usage`), so a run takes an
+exclusive lock — `local-sessions.json.lock`, with a 2-minute stale timeout —
+before it reads the history. The file holds an owner token, and a live run
+refreshes its mtime as it walks the store, so a slow scan is never mistaken for a
+dead one. A run that cannot take the lock reports the numbers already on disk and
+writes nothing; a run that is taken over mid-scan notices on its next refresh and
+also writes nothing (it never deletes its successor's lock).
+
+Duplicate *sessions* are handled two ways. A byte-identical copy of a session
+file (a copy, a restored backup, a sync tool) is recognised by a (size, first
+32 KB, last 32 KB) fingerprint and contributes nothing; anything appended to it
+later is counted normally, and if the original is deleted the copy is adopted and
+read on the next run. A fingerprint can collide — two same-size sessions that
+differ only in the middle — so a candidate is verified by streaming both files
+before it is called a copy; that full comparison runs only on the rare duplicate.
+A *fork* that copies a prefix and then diverges has its own size and tail, so it
+is counted as a session of its own, duplicated prefix included: on this machine
+(611 files, 186,443 assistant messages) only 11 message ids appeared in more than
+one file (0.006%), none of them on today, so message-id de-duplication would cost
+megabytes to correct a handful of tokens and is not implemented.
+
+The scan has a wall-clock budget (12 s, or `PI_QUOTA_LOCAL_STATS_BUDGET_MS`) so
+the first run cannot push `/usage` past its 30 s exec timeout; when it runs out
+the report carries `localStatsMeta.partial`, the panel marks the numbers
+`scan partial`, and nothing is frozen that run. `PI_QUOTA_LOCAL_STATS=0` turns
+the scan off.
+
+Session counts are **session-days**, not distinct session files: a day is frozen
+as aggregate rows, without the list of files that fed it, so a session that runs
+past midnight counts once on each day it appears in. `todaySessions` is exact
+(those files are still open); `totalSessions` is the sum of the per-day counts.
+
 ## Layout
 
 ```
@@ -465,6 +717,8 @@ src/providers/antigravity-oauth.js  in-memory refresh with Google's public clien
 src/providers/backoff.js       per-family throttle state
 src/sticky.js                  last published / last good snapshots and throttle recovery
 src/engine.js                  collectQuota() -> one normalized report
+src/local/pi-sessions.js       token counts from Pi's session files, incremental scan
+src/local/history.js           frozen local-day history: month files + all-time rollup
 src/model.js                   window normalization, percent and reset parsing
 src/render/{theme,panel}.js    colors, thresholds, rings, bars, boxed panel
 src/cache.js                   report cache at ~/.cache/pi-quota/usage.json
@@ -472,9 +726,12 @@ src/omarchy/record.js          pure mapping from the report to Omarchy usage rec
 src/omarchy/publish.js         atomic writer for pi-*.json, and stale-record cleanup
 src/refresh.js                 per-family refresh clocks, and the merge back into one report
 src/cli/args.js                argument parsing, and the flag/positional split
+src/cli/commands/stats.js      `piquota stats` and `--rebuild-totals`
 src/exec.js                    the one place that spawns gh CLI binary
 src/http.js                    fetch wrapper: timeouts, JSON, redaction
 contrib/systemd/               user service and timer behind `install.sh --omarchy-timer`
+omarchy/cad0p.pi-usage/        the AI Usage Omarchy bar plugin (QML; UsageLogic.js is its pure logic)
+tests/omarchy-harness/         offscreen renderer for the plugin, fixtures included
 bin/piquota.js                 the only CLI
 extensions/quota-panel.ts      Pi TUI line and /usage
 ```
@@ -498,7 +755,7 @@ extensions/quota-panel.ts      Pi TUI line and /usage
 ## Tests
 
 ```bash
-node --test tests/*.test.mjs     # 265 tests, fake tokens only, no network
+node --test tests/*.test.mjs     # 354 tests, fake tokens only, no network
 ```
 
 Modules covered: `auth.json` parsing and de-duplication, the Claude Code store
@@ -508,9 +765,14 @@ Actions plan resolution, opt-in gating and degradation, the two Antigravity
 failures and the OpenCode degradation), the dashboard parser's three
 strategies, the Firefox cookie reader against a synthetic SQLite database, the
 Antigravity refresh (in-memory only), sticky and last-good snapshots resilience,
-the Omarchy record mapping and atomic writer, the renderers, the Pi
-extension contract, the per-family refresh clocks, argument parsing, and the
-structure of these documents themselves (tables, fences, links, anchors).
+the Omarchy record mapping and atomic writer, the Omarchy plugin's logic,
+manifest and marks, the local token scan (family and slot mapping, incremental
+append, shrink, deletion, local-day bucketing, cache corruption), the durable
+history (month partitioning, freezing at midnight, late appends to frozen days,
+cache loss, a crash between the month and totals writes, corrupt-history
+quarantine, rebuild-totals), the renderers, the Pi extension contract, the
+per-family refresh clocks, argument parsing, and the structure of these
+documents themselves (tables, fences, links, anchors).
 
 ## Acknowledgments & Prior Art
 

package/bin/piquota.js

@@ -19,6 +19,7 @@ import { parseArgs } from "../src/cli/args.js";
 import { runAuthCommand } from "../src/cli/commands/auth.js";
 import { runGentlePiCommand } from "../src/cli/commands/gentle-pi.js";
 import { runOmarchyCommand } from "../src/cli/commands/omarchy.js";
+import { runStatsCommand } from "../src/cli/commands/stats.js";
 import { explainLines, resolveFamilies } from "../src/cli/explain.js";
 import { err, out } from "../src/cli/output.js";
 import { collectQuota, enabledFamilies, normalizeClaudeSourceMode } from "../src/engine.js";
@@ -35,6 +36,20 @@ const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.u
  */
 const CACHE_KEY = `claude-source:${normalizeClaudeSourceMode(process.env.PI_QUOTA_CLAUDE_SOURCE)}`;
 
+/**
+ * Local token statistics from Pi's session files are on for the CLI: the Omarchy
+ * records and /usage both show them. `PI_QUOTA_LOCAL_STATS=0` turns the scan
+ * off (e.g. on a machine where the session store is huge and network quota is
+ * all that matters), and the budget keeps a first full scan from delaying a
+ * report past the 30 s the /usage extension allows.
+ */
+const LOCAL_STATS_BUDGET_MS = Number(process.env.PI_QUOTA_LOCAL_STATS_BUDGET_MS);
+const LOCAL_STATS = process.env.PI_QUOTA_LOCAL_STATS === "0"
+  ? false
+  : LOCAL_STATS_BUDGET_MS > 0
+    ? { budgetMs: LOCAL_STATS_BUDGET_MS }
+    : {};
+
 const HELP = `piquota ${VERSION} — read-only quota from Pi's provider credentials
 
 Usage:
@@ -42,6 +57,7 @@ Usage:
   piquota auth <opencode|status> [flags]
   piquota gentle-pi <status|apply|revert>
   piquota omarchy
+  piquota stats [--rebuild-totals]
 
 Quota:
   --json             Emit the normalized report as JSON (for rp-host and automations)
@@ -56,6 +72,7 @@ Quota:
   --no-refresh       Never refresh Antigravity's token in memory
   --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
   --version          Print the version and exit
 
 Auth (OpenCode Go session, the only credential Pi does not store):
@@ -66,18 +83,31 @@ Auth (OpenCode Go session, the only credential Pi does not store):
   piquota auth opencode --wait <s> how long to wait for the login (default 180)
   piquota auth status              report every credential source
 
+Stats:
+  piquota stats                    summarise the durable token history
+                                   (dir: \${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-usage)
+  piquota stats --rebuild-totals   recompute totals.json from the frozen month files
+
 Omarchy:
   piquota omarchy                  write pi-<family>.json records for Omarchy's Agents bar panel
                                    (dir: $PI_QUOTA_OMARCHY_DIR or $XDG_STATE_HOME/omarchy/agents/usage)
                                    run it on a timer: ./install.sh --omarchy-timer
 
+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)
+
 Guarantees:
   * ~/.pi/agent/auth.json is opened read-only. Never written, synced or refreshed.
+  * Pi's session files are opened read-only too; the token scan keeps only
+    aggregate counts per day and model, never prompt text or session paths.
   * Antigravity's access token may be refreshed in memory; it is never persisted.
   * Browser cookie databases are copied and opened read-only; values are never logged.
-  * Only percentages, window labels, reset times and plan names leave this machine.
+  * Only percentages, window labels, reset times, plan names and aggregate token
+    counts leave this machine.
   * \`omarchy\` (opt-in) writes only pi-*.json records, atomically, into Omarchy's usage dir;
-    records hold plan names, percentages, window labels and reset times, never accounts.
+    records hold plan names, percentages, window labels, reset times and aggregate
+    token counts, never prompt text or accounts.
   * \`gentle-pi\` is the one file this tool edits outside its own state: it appends
     piQuota's part to gentle-pi's rail allowlist so the card can be painted there.
     The edit is one array literal, it is reversible with \`piquota gentle-pi revert\`,
@@ -122,10 +152,24 @@ async function main() {
     return runGentlePiCommand(sub);
   }
 
+  if (args.rebuildTotals && command !== "stats") {
+    // The flag repairs one thing (the all-time rollup) and reads nothing else,
+    // so running it beside `piquota` or `piquota omarchy` would silently skip
+    // the command the user asked for.
+    err("--rebuild-totals only works with `piquota stats`\n");
+    process.stdout.write(HELP);
+    return 2;
+  }
+
+  if (command === "stats") {
+    return runStatsCommand({ rebuild: args.rebuildTotals, env: process.env });
+  }
+
   if (command === "omarchy") {
     const load = async () => {
       const everyFamily = enabledFamilies({ env: process.env });
-      const loadFresh = () => collectQuota({ families: everyFamily, timeoutMs: args.timeoutMs, refresh, force: args.force });
+      const loadFresh = () =>
+        collectQuota({ families: everyFamily, timeoutMs: args.timeoutMs, refresh, force: args.force, localStats: LOCAL_STATS });
       const fresh = args.noCache
         ? await loadFresh()
         : (await withCache({ ttlMs: args.ttlMs, force: args.force, families: everyFamily, key: CACHE_KEY }, loadFresh)).report;
@@ -149,7 +193,8 @@ async function main() {
     requested: families.length > 0 ? families : undefined,
     explicit,
   });
-  const load = () => collectQuota({ families: selected, explicit, timeoutMs: args.timeoutMs, refresh, force: args.force });
+  const load = () =>
+    collectQuota({ families: selected, explicit, timeoutMs: args.timeoutMs, refresh, force: args.force, localStats: LOCAL_STATS });
 
   let report;
   let cached = false;