@cad0p/pi-usage 0.11.3 → 0.11.4-20261103.1

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

@@ -6,8 +6,9 @@ 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.
 > * **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,11 @@ 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 --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
 ```
 
 Colours: green above 50% remaining, yellow 20–50%, red below 20%.
@@ -230,10 +245,10 @@ Inside Pi:
 
 | Command | Effect |
 | --- | --- |
-| `/usage` | one on-demand refresh, show the full panel, 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 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 |
@@ -241,17 +256,81 @@ 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 CLI's on-disk report cache (`~/.cache/pi-quota/usage.json`,
+read-only) when memory is empty, and never waits for the CLI before the first
+frame. The same forced refresh bare `/usage` always ran then runs behind it: the
+header says `refreshing …` while it does, and the update time when it lands. A
+failed refresh is a line in the view, never a thrown error. 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 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). 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 `stats` run shows the CLI's own stderr line (redacted) or its
+exit status with a retry hint, and a slow fetch never moves the page off the month
+the last keypress asked for.
+
+History reads `piquota stats --json [--month YYYY-MM]`: the month list, one
+month's days per family/slot/model, the all-time rollup and notes. That command
+never takes the writer lock and never writes, so it is safe to run while a scan
+is freezing a day.
 
 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
-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)`.
+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 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**:
 
@@ -363,6 +442,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 +486,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": { "": { "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 +544,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 +554,224 @@ 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 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.
 - 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. `/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
+  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 |
+| `/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
+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 +788,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 +797,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 +826,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     # 401 tests, fake tokens only, no network
 ```
 
 Modules covered: `auth.json` parsing and de-duplication, the Claude Code store
@@ -508,9 +836,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