@cad0p/pi-usage 0.11.5 → 0.11.6-20261107.1

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.11.6] - 2026-11-03
+
+<!-- USER-EDITABLE SECTION START -->
+`/usage` refreshes inside pi with no CLI child, each provider on its own, and every key works under the kitty keyboard protocol.
+
+- **In-process refresh:** `/usage` runs the engine inside pi instead of spawning `piquota`, so it paints in about 0.35 s and `r` finishes in under a second. Each provider updates on its own, so a slow one never holds the others back. The token-stats scan runs in a worker thread and never blocks the TUI. The systemd timer still uses the read-only CLI.
+- **Logins stay valid:** inside pi, Claude and Codex tokens come from pi's own `getProviderAuth`, which renews them under pi's lock exactly as when you use the model. Antigravity, which pi 1.5 no longer resolves, keeps its renewed token in memory for its lifetime; nothing is written back.
+- **Kitty keyboard protocol (Ghostty, kitty, foot):** arrows, Esc, Enter, Tab, Space and every legend key work in their CSI-u form on both tabs. Key releases never act, repeats do. A drift test compares the decoder with the installed pi-tui matcher.
+- **History all-time counts today once**, and an all-time figure that lags behind the month files is shown dimmed with a note instead of disappearing.
+- **Antigravity header:** no repeated project, and no false "token expired" while the account works.
+<!-- USER-EDITABLE SECTION END -->
+
+### 🚀 Features
+
+- In-process /usage refresh, each provider on its own (closes #26)
+
+### 🐛 Bug Fixes
+
+- History all-time counts today once; Antigravity header without the false expiry (closes #29)
+- *(extension)* /usage keys work under the kitty keyboard protocol (closes #33)
+
+
 ## [0.11.5] - 2026-11-03
 
 <!-- USER-EDITABLE SECTION START -->

package/README.md

@@ -6,6 +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.
+> * **Mistral from the API key**: `GET https://api.mistral.ai/v1/billing/budget` and `/v1/billing/subscription`, the two reads the Vibe CLI makes for its usage gauge, return the monthly Vibe Code and API budgets and the plan for the key Pi already stores (`mistral`, and siblings such as `mistral-1-api`). They are read-only and cost no tokens.
 > * **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.
@@ -32,15 +33,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 +68,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 |
@@ -72,10 +80,11 @@ shuvquota, and it never writes to a credential file.
 
 | Provider | Source | Endpoint | Result |
 | --- | --- | --- | --- |
-| 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 |
+| Claude | Claude Code CLI store, else `anthropic.access` | `GET api.anthropic.com/api/oauth/usage` | ✅ 5h + weekly + plan; an `api_key` sibling (`anthropic-1-api`) is a working pay-as-you-go account: no windows, a note, and its key is never sent (Anthropic serves no balance to API keys) |
+| Codex | `openai-codex.access` + `accountId` | `GET chatgpt.com/backend-api/wham/usage` | ✅ 5h + weekly + plan; an `api_key` sibling (`openai-codex-1-api`) is likewise a working pay-as-you-go account whose key is never sent |
 | 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 |
+| Mistral | `mistral.key`, numbered siblings included | `GET api.mistral.ai/v1/billing/budget` + `/v1/billing/subscription` | ✅ Vibe monthly + API monthly + plan per key; without the `see_org_inference_usage` permission the plan alone, with a note. Keys of one organisation share its budgets, so they show the same numbers |
 | 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 |
 
 Four findings worth recording, each of which cost a wrong hypothesis:
@@ -107,14 +116,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 +186,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
 
@@ -266,11 +278,19 @@ refresh (and a gentle refresh after each agent turn). `/usage hide` gives the ro
 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:
+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
@@ -288,6 +308,13 @@ resumes them, and no file is written.
 | `tab`, `1` / `2` | switch between Now and History |
 | `esc` / `q` | close |
 
+Every key works in a terminal that sends the legacy escape sequences and in one
+that negotiates the kitty keyboard protocol (Ghostty among them): the decoder
+reads both encodings, plus kitty press, repeat and release events, so a press
+moves once and its release never moves again. A repeat is a press — a held arrow
+keeps moving, exactly as it does in tmux, where the OS repeat is the same bytes
+as the first press.
+
 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
@@ -300,13 +327,20 @@ 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
+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). A family's open day
+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.
@@ -314,21 +348,25 @@ A report generated before midnight, or the older report cache painted on the fir
 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.
+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 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
+(`key rejected`, `no Go plan`). The base entry in `auth.json` (`opencode-go`) is the
+family's first account, `#1`; sibling slots (`opencode-go-2` …) are numbered
+`#2` … `#14`, and a lone account prints no number. A `<base>-1` sibling
+beside the base would be a second `#1`, so the report warns to renumber it. 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.
 
@@ -349,7 +387,8 @@ right rail instead, under Status and TODO, and the above-editor box stays quiet
 the numbers are not shown twice. See [the rail slot](#the-gentle-pi-rail-slot).
 
 * each name is painted with its **own brand colour** — Claude `#D97757`, Codex
-  `#10A37F`, Antigravity `#4285F4`, OpenCode `#007AFF`;
+  `#10A37F`, Antigravity `#4285F4`, OpenCode `#007AFF`, Mistral `#FA520F` (its row,
+  the Vibe budget, appears only when a Mistral key is configured);
 * the numbers are **used**, not remaining, and the semaphore is both colour and
   shape (`○` plenty left → `◔` → `◕` → `●` nearly spent), so it still reads on a
   colourblind or mono terminal;
@@ -439,6 +478,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.
@@ -486,6 +531,10 @@ Rp suite) without external network daemons or closed-source intermediaries:
 }
 ```
 
+A provider may also carry a top-level `note` when it answered but has no windows
+to show, such as a Mistral key without the `see_org_inference_usage` permission
+(`"ok": true`, `"windows": []`, the plan, and the reason in `note`).
+
 The token part of the same report is abridged here (`recentDays` always carries
 seven entries, oldest first, today last):
 
@@ -522,7 +571,7 @@ stale without triggering rate limits:
 | Family | Clock |
 | --- | --- |
 | Claude | **300 s** (`--claude-ttl`) |
-| Codex, Antigravity, OpenCode Go | **60 s** (`--fetch-ttl`) |
+| Codex, Antigravity, OpenCode Go, Mistral | **60 s** (`--fetch-ttl`) |
 
 `src/refresh.js` keeps a timestamp per family, requests only what is past its own
 clock, and merges the result back into the canonical report. `src/sticky.js`
@@ -535,7 +584,7 @@ credential) are never masked.
 Omarchy 4.0.4's **Agents** bar panel draws every `*.json` record in
 `${XDG_STATE_HOME:-~/.local/state}/omarchy/agents/usage/`, whoever wrote it.
 `piquota omarchy` (opt-in, one shot) writes one record per provider piQuota can
-read, so Claude, Codex, Antigravity and OpenCode Go all get a tab:
+read, so Claude, Codex, Antigravity, OpenCode Go and Mistral all get a tab:
 
 ```bash
 piquota omarchy                  # write pi-claude.json, pi-codex.json, ... once
@@ -554,9 +603,8 @@ 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 unnumbered base entry keeps a
-  blank `id` and its limits are untitled; only real sibling slots carry
-  `#<slot>`. The same record also carries
+  `#8–#10 key rejected · #11–#14 no Go plan`. The base entry's `id` is `#1`
+  and its limits are titled like any other slot's. 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.
@@ -658,7 +706,7 @@ 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
+`anthropic`, `openai-codex`, `antigravity`, `opencode-go`, `mistral` 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.
@@ -793,6 +841,7 @@ src/local/history.js           frozen local-day history: month files + all-time
 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
+src/overlay-keys.js            raw key decoding for /usage: legacy and kitty keyboard encodings
 src/omarchy/record.js          pure mapping from the report to Omarchy usage records
 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
@@ -826,12 +875,13 @@ extensions/quota-panel.ts      Pi TUI line and /usage
 ## Tests
 
 ```bash
-node --test tests/*.test.mjs     # 401 tests, fake tokens only, no network
+node --test tests/*.test.mjs     # 489 tests, fake tokens only, no network
 ```
 
 Modules covered: `auth.json` parsing and de-duplication, the Claude Code store
 (including that the refresh token never leaves it and that reading leaves the file
-byte-identical), Claude source precedence, the five providers (including GitHub
+byte-identical), Claude source precedence, the six providers (including Mistral's two budgets,
+the missing usage permission and a rejected key, GitHub
 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

package/bin/piquota.js

@@ -2,7 +2,7 @@
 /**
  * piquota — independent, read-only quota for the credentials Pi already owns.
  *
- *   piquota                      panel for Claude, Codex, Antigravity, OpenCode Go
+ *   piquota                      panel for Claude, Codex, Antigravity, OpenCode Go, Mistral
  *   piquota --json               normalized report (used by rp-host / tools)
  *   piquota --compact | --status | --explain
  *   piquota auth opencode        open the OpenCode login and capture the session
@@ -177,10 +177,20 @@ async function main() {
   }
 
   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;