@askalf/dario 6.5.0 → 6.6.0

package/README.md

@@ -27,7 +27,7 @@
 
 <p><strong>One local endpoint. Every AI tool you own. The subscriptions you already pay for.</strong></p>
 
-<sub><code>npm i -g @askalf/dario</code> · <strong>0</strong> runtime deps · <a href="https://www.npmjs.com/package/@askalf/dario">SLSA-attested</a> every release · nothing phones home · ~35k lines you can read in a weekend · independent, unofficial, third-party (<a href="DISCLAIMER.md">DISCLAIMER.md</a>)</sub>
+<sub><code>npm i -g @askalf/dario</code> · <strong>0</strong> runtime deps · <a href="https://www.npmjs.com/package/@askalf/dario">SLSA-attested</a> every release · nothing phones home · ~36k lines you can read in a weekend · independent, unofficial, third-party (<a href="DISCLAIMER.md">DISCLAIMER.md</a>)</sub>
 
 <sub><a href="#start-in-60-seconds">Start</a> · <a href="#point-your-tools-at-it">Your tools</a> · <a href="#what-it-does-with-a-request">Routing</a> · <a href="#two-plans-one-endpoint">Two plans</a> · <a href="#many-seats-one-endpoint">Pool</a> · <a href="#it-tracks-a-moving-target">Drift</a> · <a href="#trust--transparency">Trust</a> · <a href="#will-my-account-get-suspended">Risk</a> · <a href="#commands">Commands</a> · <a href="#faq">FAQ</a> · <a href="docs/returning.md">Coming back after a while?</a></sub>
 
@@ -373,6 +373,20 @@ Type `dario` with no arguments for a full-screen control panel: live request str
 
 <sub>Both screenshots are rendered from the real TUI against a fixture proxy by <a href="scripts/readme/tui.mjs"><code>scripts/readme/tui.mjs</code></a>, so a layout change shows up here instead of rotting a mock-up. The numbers are illustrative; the pixels are not.</sub>
 
+### What it would have cost
+
+The rolling window forgets on every restart; the **ledger** does not. Since 6.6 dario keeps one small row per day, per model, per billing bucket in `~/.dario/ledger.json` — request counts and the four token buckets, never a price — and prices them at read time from the published API rate cards (Anthropic's, and OpenAI's for the ChatGPT leg), so a pricing correction reprices history instead of freezing the old number in. `dario usage` opens with it, `/analytics` carries it as `lifetime`, the TUI shows it as **API-equivalent**, and it reads from the file when the proxy is down:
+
+```
+  API-equivalent spend (since 2026-09-11, 3 days, 1,515 requests):
+    $413 would have been billed on the metered API — covered by subscriptions
+      Claude       $388   1,204 reqs   (Opus 5 $301 · Sonnet 5 $86.68)
+      ChatGPT    $24.75     311 reqs   (gpt-5.6-terra $24.75)
+    Today $48.20 · Last 7d $413 · Last 30d $413
+```
+
+Only served requests count. Traffic that was metered anyway — an API key upstream, or Anthropic's paid `extra_usage` overage — is kept in its own column and reported as spent, not saved. `dario usage --card` writes the headline as a 640×320 SVG you can drop in a README or a post; `--no-ledger` / `DARIO_LEDGER=0` turns the file off, `DARIO_LEDGER_PATH` moves it, and `GET /analytics/ledger` is the per-day table behind the number. Details: [api-equivalent-spend.md](./docs/api-equivalent-spend.md).
+
 ## It tracks a moving target
 
 Claude Code's request shape changes between releases — new betas, tool renames, per-model thinking configs — usually with no subscriber-facing note. dario doesn't *guess* that shape: it captures it live from your own installed `claude` binary on every startup, diffs it against each upstream release, and replays it faithfully. That's why your subscription routes the same through dario as it does through Claude Code itself: the request that leaves your machine *is* the shape your plan expects. Details: [wire-fidelity.md](./docs/wire-fidelity.md) · [#13](https://github.com/askalf/dario/discussions/13) · [#14](https://github.com/askalf/dario/discussions/14).
@@ -492,7 +506,7 @@ Longer version, with specifics: [#68](https://github.com/askalf/dario/discussion
 | `dario accounts list` / `add` / `remove` / `check <alias>` | Pool management; `check` sends one pinned request per model through the running proxy (admin API on) |
 | `dario backend list` / `add` / `remove` | OpenAI-compatible API-key backends |
 | `dario codex list` / `add` / `remove` | ChatGPT accounts (the long form of `dario add altman`) |
-| `dario usage` · `dario config` · `dario status` | Burn rate for the last hour · effective config, redacted · token health |
+| `dario usage` · `dario config` · `dario status` | Lifetime API-equivalent spend + burn rate for the last hour (`--card` writes the share card) · effective config, redacted · token health |
 | `dario resume` · `dario refresh` · `dario logout` · `dario upgrade` | Clear an overage halt · force a token refresh · delete credentials · safe self-update |
 | `dario mcp` · `dario subagent install` / `remove` / `status` | Reach dario from inside any MCP client, or from inside a Claude Code session, read-only |
 
@@ -503,7 +517,7 @@ Longer version, with specifics: [#68](https://github.com/askalf/dario/discussion
 | `GET /health` · `GET /livez` | Serviceability (503 when not) · liveness. `/health?probe=1` sends one real request |
 | `GET /status` · `GET /accounts` · `GET /analytics` | OAuth detail · per-seat utilization and grant age · per-account / per-model stats and burn rate |
 | `POST /v1/messages/count_tokens` · `POST /v1/complete` | Token counting and the legacy Text Completions shape |
-| `GET /analytics/stream` · `GET /codex` | Live analytics over SSE · ChatGPT-seat status, read without spending or exposing a token |
+| `GET /analytics/stream` · `GET /analytics/ledger` · `GET /codex` | Live analytics over SSE · the ledger's per-day table · ChatGPT-seat status, read without spending or exposing a token |
 | `/admin/*` | Provisioning, `GET /admin/accounts`, `POST /admin/resume`; only with `DARIO_ADMIN=1` ([admin API](./docs/admin-api.md)) |
 
 Flags: [commands.md](./docs/commands.md), plus `dario --help` for the ones it doesn't list yet (`--effort`, `--max-tokens`, `--model-alias`, `--fast-model`, session rotation, concurrency caps, the pacing knobs behind `--stealth`) · env vars grouped by task, for Docker / k8s / systemd: [configuration.md](./docs/configuration.md) · SDK examples: [usage.md](./docs/usage.md).

package/dist/analytics.d.ts

@@ -139,7 +139,7 @@ export declare function consumerFromBody(body: Record<string, unknown> | null |
  * the proxy on every transient non-200/stream-abort.
  */
 export declare function isNonSubscriptionBilling(claim: string | null | undefined): boolean;
-interface Rate {
+export interface Rate {
     input: number;
     output: number;
     cacheRead: number;
@@ -168,15 +168,50 @@ interface PricingEntry extends Rate {
  * is why the watcher exists (#1048).
  */
 export declare const PRICING: Record<string, PricingEntry>;
+/**
+ * OpenAI's published per-1M-token rates for the models the codex backend
+ * serves, standard tier, read off developers.openai.com/api/docs/pricing on
+ * 2026-09-11. Kept apart from PRICING because scripts/check-pricing-drift.mjs
+ * diffs that table against Anthropic's page and would report every row here
+ * as "absent upstream". OpenAI charges nothing to write a cache entry, so
+ * cacheCreate is the input rate (the codex path reports no cache writes
+ * anyway — `cached_tokens` lands in cacheReadTokens, the rest in inputTokens).
+ *
+ * Before this table every `gpt-*` row was priced at the sonnet-4-6 fallback:
+ * a ChatGPT-plan request showed up in "would-be API cost" at Anthropic's
+ * rate for a model Anthropic does not sell. Nothing watches this table yet.
+ */
+export declare const OPENAI_PRICING: Record<string, Rate>;
+export type PricingProvider = 'anthropic' | 'openai';
+/**
+ * Which price list a model id belongs to. Every id the codex backend serves
+ * starts `gpt-`; the rest of the pattern covers the older OpenAI families a
+ * `--model-alias` might name. Anything else is priced as Claude.
+ */
+export declare function providerOfModel(model: string): PricingProvider;
 /**
  * The per-1M-token rate for `model` in effect at `atMs` (epoch ms): the intro
  * rate while within its window, otherwise the standard rate. A trailing context
  * tag (`claude-sonnet-5[1m]`, `claude-opus-4-7[1m]`) is stripped before lookup —
  * the [1m] ids used to fall through to the sonnet fallback and bill at the wrong
- * family's rate. Unknown models fall back to the sonnet-4-6 rate. Exported for
- * tests.
+ * family's rate — and so are an effort suffix (`gpt-5.6-terra:high`) and the
+ * dated form the response echoes (`claude-haiku-4-5-20251001`, which priced
+ * at the sonnet fallback until the ledger's first live run caught it).
+ * Unknown Claude models fall back to the sonnet-4-6 rate, unknown OpenAI
+ * models to gpt-5.6-terra's. Exported for tests.
  */
 export declare function pricingRateFor(model: string, atMs: number): Rate;
+/**
+ * USD the four token buckets would bill at `model`'s rate in effect at `atMs`.
+ * The ledger prices its per-day rows through this too, so a pricing
+ * correction reprices history instead of freezing the old number in.
+ */
+export declare function costOfTokens(model: string, atMs: number, t: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreateTokens: number;
+}): number;
 export declare class Analytics extends EventEmitter {
     private records;
     private maxRecords;

package/dist/analytics.js

@@ -206,16 +206,57 @@ export const PRICING = {
     // LOW. Found by check-pricing-drift.mjs on its very first run (#1048).
     'claude-haiku-4-5': { input: 1, output: 5, cacheRead: 0.1, cacheCreate: 1.25 },
 };
+/**
+ * OpenAI's published per-1M-token rates for the models the codex backend
+ * serves, standard tier, read off developers.openai.com/api/docs/pricing on
+ * 2026-09-11. Kept apart from PRICING because scripts/check-pricing-drift.mjs
+ * diffs that table against Anthropic's page and would report every row here
+ * as "absent upstream". OpenAI charges nothing to write a cache entry, so
+ * cacheCreate is the input rate (the codex path reports no cache writes
+ * anyway — `cached_tokens` lands in cacheReadTokens, the rest in inputTokens).
+ *
+ * Before this table every `gpt-*` row was priced at the sonnet-4-6 fallback:
+ * a ChatGPT-plan request showed up in "would-be API cost" at Anthropic's
+ * rate for a model Anthropic does not sell. Nothing watches this table yet.
+ */
+export const OPENAI_PRICING = {
+    'gpt-6-astra': { input: 10, output: 50, cacheRead: 1, cacheCreate: 10 },
+    'gpt-5.6-sol': { input: 4, output: 20, cacheRead: 0.4, cacheCreate: 4 },
+    'gpt-5.6-terra': { input: 2, output: 12, cacheRead: 0.2, cacheCreate: 2 },
+    'gpt-5.6-luna': { input: 0.2, output: 1.2, cacheRead: 0.02, cacheCreate: 0.2 },
+    'gpt-5.5': { input: 5, output: 30, cacheRead: 0.5, cacheCreate: 5 },
+    'gpt-5.4': { input: 2.5, output: 15, cacheRead: 0.25, cacheCreate: 2.5 },
+    'gpt-5.4-mini': { input: 0.75, output: 4.5, cacheRead: 0.075, cacheCreate: 0.75 },
+    'gpt-5.4-nano': { input: 0.2, output: 1.25, cacheRead: 0.02, cacheCreate: 0.2 },
+    'gpt-5.3-codex': { input: 1.75, output: 14, cacheRead: 0.175, cacheCreate: 1.75 },
+};
+/** The unknown-model rate on the OpenAI side: dario's default codex model. */
+const OPENAI_FALLBACK_MODEL = 'gpt-5.6-terra';
+/**
+ * Which price list a model id belongs to. Every id the codex backend serves
+ * starts `gpt-`; the rest of the pattern covers the older OpenAI families a
+ * `--model-alias` might name. Anything else is priced as Claude.
+ */
+export function providerOfModel(model) {
+    return /^(gpt-|o\d|codex|chatgpt)/i.test(model) ? 'openai' : 'anthropic';
+}
 /**
  * The per-1M-token rate for `model` in effect at `atMs` (epoch ms): the intro
  * rate while within its window, otherwise the standard rate. A trailing context
  * tag (`claude-sonnet-5[1m]`, `claude-opus-4-7[1m]`) is stripped before lookup —
  * the [1m] ids used to fall through to the sonnet fallback and bill at the wrong
- * family's rate. Unknown models fall back to the sonnet-4-6 rate. Exported for
- * tests.
+ * family's rate — and so are an effort suffix (`gpt-5.6-terra:high`) and the
+ * dated form the response echoes (`claude-haiku-4-5-20251001`, which priced
+ * at the sonnet fallback until the ledger's first live run caught it).
+ * Unknown Claude models fall back to the sonnet-4-6 rate, unknown OpenAI
+ * models to gpt-5.6-terra's. Exported for tests.
  */
 export function pricingRateFor(model, atMs) {
-    const baseModel = model.replace(/\[[^\]]*\]$/, '');
+    const baseModel = model.replace(/\[[^\]]*\]$/, '').replace(/:[a-z]+$/i, '').replace(/-\d{8}$/, '');
+    if (providerOfModel(baseModel) === 'openai') {
+        const rate = OPENAI_PRICING[baseModel] ?? OPENAI_PRICING[OPENAI_FALLBACK_MODEL];
+        return { ...rate };
+    }
     const entry = PRICING[baseModel] ?? PRICING['claude-sonnet-4-6'];
     if (entry.intro && atMs <= Date.parse(`${entry.intro.until}T23:59:59.999Z`)) {
         const { until: _until, ...introRate } = entry.intro;
@@ -223,16 +264,24 @@ export function pricingRateFor(model, atMs) {
     }
     return { input: entry.input, output: entry.output, cacheRead: entry.cacheRead, cacheCreate: entry.cacheCreate };
 }
+/**
+ * USD the four token buckets would bill at `model`'s rate in effect at `atMs`.
+ * The ledger prices its per-day rows through this too, so a pricing
+ * correction reprices history instead of freezing the old number in.
+ */
+export function costOfTokens(model, atMs, t) {
+    const p = pricingRateFor(model, atMs);
+    return ((t.inputTokens * p.input) +
+        (t.outputTokens * p.output) +
+        (t.cacheReadTokens * p.cacheRead) +
+        (t.cacheCreateTokens * p.cacheCreate)) / 1_000_000;
+}
 function estimateCost(record) {
     // Price each record at the rate effective at ITS OWN timestamp, so a window
     // that spans a pricing cutover (no model currently has one — Sonnet 5's
     // scheduled increase was cancelled and its $2/$10 made permanent)
     // estimates each side correctly rather than repricing history at today's rate.
-    const p = pricingRateFor(record.model, record.timestamp);
-    return ((record.inputTokens * p.input) +
-        (record.outputTokens * p.output) +
-        (record.cacheReadTokens * p.cacheRead) +
-        (record.cacheCreateTokens * p.cacheCreate)) / 1_000_000;
+    return costOfTokens(record.model, record.timestamp, record);
 }
 export class Analytics extends EventEmitter {
     records = [];

package/dist/cli.js

@@ -16,7 +16,8 @@
 // at the bottom of the file so importing this module (e.g. from tests that
 // just want `parsePositiveIntEnv`) doesn't trigger a Bun relaunch or any
 // other startup side effect.
-import { unlink } from 'node:fs/promises';
+import { unlink, writeFile } from 'node:fs/promises';
+import { formatLedgerSummary, formatUsd, renderLedgerCard, readLedgerFile, resolveLedgerPath, summarizeLedger } from './ledger.js';
 import { loadAllAccounts as loadAllAccountsForIdentity, regenerateClientIdentity } from './accounts.js';
 import { maskEmail } from './pool.js';
 import { realpathSync, readFileSync } from 'node:fs';
@@ -630,6 +631,10 @@ async function proxy() {
     // On by default; see ProxyOptions.midstreamContinue.
     const midstreamContinue = !(args.includes('--no-midstream-continue')
         || ['0', 'false', 'no', 'off'].includes((process.env['DARIO_MIDSTREAM_CONTINUE'] ?? '').toLowerCase()));
+    // --no-ledger / DARIO_LEDGER=0 — do not keep the lifetime ledger (v6.6).
+    // On by default; see ProxyOptions.ledger.
+    const ledger = !(args.includes('--no-ledger')
+        || ['0', 'false', 'no', 'off'].includes((process.env['DARIO_LEDGER'] ?? '').toLowerCase()));
     // --preserve-output-format — carry the client body's `output_config.format`
     // (structured-output JSON schema) through to upstream instead of dropping it
     // during the CC rebuild. See ProxyOptions.preserveOutputFormat for rationale.
@@ -654,7 +659,7 @@ async function proxy() {
         console.error(`[dario] Override (not recommended): pass --unsafe-no-auth if you have out-of-band network controls and accept the risk.`);
         process.exit(1);
     }
-    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, maxConcurrentPerConsumer, poolStrategy, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue });
+    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, maxConcurrentPerConsumer, poolStrategy, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger });
 }
 /**
  * Parse `--system-prompt=<verbatim|partial|aggressive|filepath>` (or the
@@ -1583,7 +1588,12 @@ async function help() {
                              rate-limit snapshot from Anthropic, see
                              \`dario doctor --usage\`. --port=N to target
                              a non-default port; --json for the raw
-                             /analytics payload.
+                             /analytics payload. Above the window: the
+                             lifetime API-equivalent spend from the
+                             ledger (read from disk when the proxy is
+                             down). --card[=file.svg] writes a share
+                             card of that number (default
+                             dario-api-equivalent.svg). (v6.6)
     dario upgrade            npm install -g @askalf/dario@latest with a
                              pre-flight current-vs-latest check.
 
@@ -1704,6 +1714,14 @@ async function help() {
                              fallback entry for the other provider,
                              the stream ends truncated as before.
                              Env: DARIO_MIDSTREAM_CONTINUE=0. (v6.1)
+    --no-ledger              Do not keep the lifetime ledger
+                             (~/.dario/ledger.json): per-day, per-model
+                             token totals that let /analytics and
+                             \`dario usage\` say what the traffic would
+                             have cost on the metered API since the
+                             first request, across restarts. Env:
+                             DARIO_LEDGER=0; DARIO_LEDGER_PATH=<file>
+                             moves it. (v6.6)
     --session-idle-rotate=MS Idle ms before an account's session id
                              rotates (default: 900000 = 15 min).
                              Real CC rotates once per conversation, not
@@ -2322,6 +2340,9 @@ async function usage() {
             ? parseInt(process.env['DARIO_USAGE_PORT'], 10)
             : 3456;
     const asJson = args.includes('--json');
+    // --card / --card=<file>: write the share card (SVG) of the lifetime number.
+    const cardArg = args.find(a => a === '--card' || a.startsWith('--card='));
+    const cardPath = cardArg ? (cardArg.includes('=') ? cardArg.slice('--card='.length) : 'dario-api-equivalent.svg') : null;
     const url = `http://127.0.0.1:${port}/analytics`;
     let payload = null;
     let connectError = null;
@@ -2337,18 +2358,54 @@ async function usage() {
     catch (err) {
         connectError = err instanceof Error ? err.message : String(err);
     }
+    // The lifetime number does not need a running proxy: the ledger is a file.
+    // Prefer the proxy's view (it holds records not yet flushed); fall back to
+    // reading the file this port's proxy would write.
+    let lifetime = payload?.lifetime ?? null;
+    let lifetimeNote = null;
+    if (!payload) {
+        const ledgerPath = resolveLedgerPath(port);
+        const { file, error } = await readLedgerFile(ledgerPath);
+        if (file)
+            lifetime = summarizeLedger(file, ledgerPath);
+        else if (error)
+            lifetimeNote = `ledger at ${ledgerPath} unreadable: ${error}`;
+        else
+            lifetimeNote = `no ledger at ${ledgerPath} yet — it appears after the first request through a proxy on this port`;
+    }
+    else if (payload.lifetime === null) {
+        lifetimeNote = 'ledger disabled on this proxy (--no-ledger)';
+    }
+    if (cardPath) {
+        if (!lifetime) {
+            console.error(`  No lifetime numbers to draw${lifetimeNote ? ` (${lifetimeNote})` : ''}.`);
+            process.exit(1);
+        }
+        await writeFile(cardPath, renderLedgerCard(lifetime), 'utf8');
+        if (!asJson)
+            console.log(`  Wrote ${cardPath} — ${formatUsd(lifetime.apiEquivalentCost)} API-equivalent since ${lifetime.since.slice(0, 10)}.`);
+    }
     if (asJson) {
         if (payload) {
             process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
             return;
         }
-        process.stdout.write(JSON.stringify({ error: 'proxy not reachable', port, detail: connectError }, null, 2) + '\n');
+        process.stdout.write(JSON.stringify({ error: 'proxy not reachable', port, detail: connectError, lifetime }, null, 2) + '\n');
         process.exit(1);
     }
     console.log('');
     console.log('  dario — Usage');
     console.log('  ─────────────');
     console.log('');
+    if (lifetime) {
+        for (const line of formatLedgerSummary(lifetime))
+            console.log(line);
+        console.log('');
+    }
+    else if (lifetimeNote) {
+        console.log(`  API-equivalent spend: ${lifetimeNote}.`);
+        console.log('');
+    }
     if (!payload) {
         console.log(`  Proxy not reachable on http://127.0.0.1:${port} (${connectError ?? 'no response'}).`);
         console.log('  `dario usage` summarizes traffic from a running proxy (live history).');

package/dist/ledger.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The ledger — what the traffic dario has served would have cost on the
+ * metered API, kept across restarts.
+ *
+ * /analytics is a rolling in-memory window: it forgets on every restart and
+ * caps at 10k records, so the one number a subscription user actually wants
+ * — "what has this saved me" — was never answerable past the last few hours.
+ * The ledger keeps one small row per (UTC day, model, bucket): a request
+ * count and the four token buckets. It never stores a price. Rows are priced
+ * at read time through `costOfTokens` at the day's own timestamp, so a
+ * pricing correction (#1047, #1048 — both happened) reprices history instead
+ * of freezing the wrong number in.
+ *
+ * Two buckets per row. `covered` is traffic a subscription paid for — the
+ * API-equivalent cost of that is the headline, the invoice that never
+ * arrived. `metered` is traffic billed per token anyway (an API key, or
+ * Anthropic's paid `extra_usage` overage) — that money was spent, and it is
+ * reported separately rather than counted as saved. Only 2xx responses
+ * count: a 429 carries no tokens and a 5xx bills nothing.
+ *
+ * On disk: `~/.dario/ledger.json` for the default port, `ledger-<port>.json`
+ * for any other, so two instances sharing a home (the box's live-test rig
+ * runs one on :3999 next to production) do not overwrite each other's file.
+ * Writes are debounced and durable (`durableWriteFile`); the shutdown hook
+ * flushes what the debounce still holds, so at most the last few seconds
+ * before a SIGKILL are lost.
+ */
+import { type PricingProvider, type RequestRecord } from './analytics.js';
+export declare const LEDGER_VERSION = 1;
+/** Days kept before the oldest roll off — two years at one row per model per day. */
+export declare const LEDGER_MAX_DAYS = 730;
+/** How long after the last record the file is rewritten. */
+export declare const LEDGER_FLUSH_DELAY_MS = 3000;
+export type LedgerBucket = 'covered' | 'metered';
+export interface LedgerCell {
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreateTokens: number;
+}
+export type LedgerRow = Partial<Record<LedgerBucket, LedgerCell>>;
+export interface LedgerFile {
+    version: number;
+    /** ISO timestamp of the first record the ledger ever saw. */
+    since: string;
+    /** ISO timestamp of the last write. */
+    updated: string;
+    /** `YYYY-MM-DD` (UTC) → model id → per-bucket totals. */
+    days: Record<string, Record<string, LedgerRow>>;
+}
+export interface LedgerModelSummary {
+    provider: PricingProvider;
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreateTokens: number;
+    /** API-equivalent cost of this model's covered traffic, USD. */
+    apiEquivalentCost: number;
+    /** What this model's metered traffic cost at list price, USD. */
+    meteredCost: number;
+}
+export interface LedgerSummary {
+    /** Where the file lives — so `dario usage` can say what it read. */
+    path: string;
+    since: string;
+    /** Distinct UTC days with traffic. */
+    days: number;
+    /** Covered + metered, 2xx only. */
+    requests: number;
+    /**
+     * The headline: what subscription-covered traffic would have been billed
+     * on the metered API at today's list prices, USD.
+     */
+    apiEquivalentCost: number;
+    /** What metered traffic (API key, paid overage) actually cost at list price, USD. */
+    meteredCost: number;
+    /** Covered token totals. */
+    tokens: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheCreate: number;
+    };
+    perProvider: Record<PricingProvider, {
+        requests: number;
+        apiEquivalentCost: number;
+    }>;
+    perModel: Record<string, LedgerModelSummary>;
+    /** apiEquivalentCost over the trailing windows, UTC days. */
+    recent: {
+        today: number;
+        last7d: number;
+        last30d: number;
+    };
+}
+export declare function ledgerPathFor(port: number, home?: string): string;
+/**
+ * `DARIO_LEDGER_PATH` names the file; `DARIO_LEDGER=0` (or `--no-ledger`)
+ * turns the ledger off. Off, /analytics reports `lifetime: null` and the
+ * usage command says so.
+ */
+export declare function resolveLedgerPath(port: number, env?: NodeJS.ProcessEnv): string;
+export declare function ledgerDisabledByEnv(env?: NodeJS.ProcessEnv): boolean;
+export declare function emptyLedger(now?: number): LedgerFile;
+/** UTC calendar day of an epoch-ms timestamp. */
+export declare function dayKey(atMs: number): string;
+/**
+ * Which bucket a record lands in, or null when it should not be counted.
+ * `api` and `extra_usage` are metered; every subscription claim, the codex
+ * claim, and an absent claim on a 2xx (stream aborts, api-key mode without
+ * the header) are covered — the request was served, and nothing says it was
+ * billed per token.
+ */
+export declare function ledgerBucketFor(record: Pick<RequestRecord, 'status' | 'claim'>): LedgerBucket | null;
+/**
+ * Parse a ledger file's text, keeping only well-formed rows. A file that is
+ * not a ledger at all throws; the caller moves it aside and starts fresh.
+ */
+export declare function parseLedger(text: string): LedgerFile;
+/** Add one record's tokens to the file in place. Returns false when it was not counted. */
+export declare function addToLedger(file: LedgerFile, record: RequestRecord): boolean;
+/** Drop the oldest days past LEDGER_MAX_DAYS. */
+export declare function pruneLedger(file: LedgerFile, maxDays?: number): void;
+export declare function summarizeLedger(file: LedgerFile, path: string, now?: number): LedgerSummary;
+/**
+ * Read a ledger file for display without a running proxy (`dario usage`
+ * when the proxy is down). Missing file → null; unreadable → null with the
+ * reason, never a throw.
+ */
+export declare function readLedgerFile(path: string): Promise<{
+    file: LedgerFile | null;
+    error?: string;
+}>;
+export declare class Ledger {
+    readonly path: string;
+    private readonly log;
+    private file;
+    private dirty;
+    private timer;
+    private writing;
+    private closed;
+    private constructor();
+    /**
+     * Load the ledger at `path`, or start one. A file that cannot be parsed is
+     * moved aside (`<path>.corrupt-<ts>`) rather than overwritten, so a bad
+     * write never silently zeroes two years of history.
+     */
+    static open(path: string, log?: (line: string) => void): Promise<Ledger>;
+    /** Count a request. Returns false when it was not ledger material. */
+    add(record: RequestRecord): boolean;
+    summary(now?: number): LedgerSummary;
+    /** The raw per-day table, for /analytics/ledger. */
+    snapshot(): LedgerFile;
+    private scheduleFlush;
+    /** Write now if anything changed. Serialized; a failure is logged, not thrown. */
+    flush(): Promise<void>;
+    /** Final flush for the shutdown hook. */
+    close(): Promise<void>;
+}
+export declare function formatUsd(usd: number): string;
+/** `claude-opus-5` → `Opus 5`, `claude-haiku-4-5-20251001` → `Haiku 4.5`, `gpt-5.6-terra` → `gpt-5.6-terra`. */
+export declare function shortModelName(model: string): string;
+/**
+ * The block `dario usage` prints above the rolling window. Two-space indent
+ * to match the rest of that command's output.
+ */
+export declare function formatLedgerSummary(s: LedgerSummary): string[];
+/**
+ * A share card: one SVG, 640×320, dark, the number in the middle. Plain
+ * system monospace so it renders the same in a README, a tweet screenshot
+ * and an <img> tag with nothing to fetch.
+ */
+export declare function renderLedgerCard(s: LedgerSummary): string;

package/dist/ledger.js

@@ -0,0 +1,411 @@
+/**
+ * The ledger — what the traffic dario has served would have cost on the
+ * metered API, kept across restarts.
+ *
+ * /analytics is a rolling in-memory window: it forgets on every restart and
+ * caps at 10k records, so the one number a subscription user actually wants
+ * — "what has this saved me" — was never answerable past the last few hours.
+ * The ledger keeps one small row per (UTC day, model, bucket): a request
+ * count and the four token buckets. It never stores a price. Rows are priced
+ * at read time through `costOfTokens` at the day's own timestamp, so a
+ * pricing correction (#1047, #1048 — both happened) reprices history instead
+ * of freezing the wrong number in.
+ *
+ * Two buckets per row. `covered` is traffic a subscription paid for — the
+ * API-equivalent cost of that is the headline, the invoice that never
+ * arrived. `metered` is traffic billed per token anyway (an API key, or
+ * Anthropic's paid `extra_usage` overage) — that money was spent, and it is
+ * reported separately rather than counted as saved. Only 2xx responses
+ * count: a 429 carries no tokens and a 5xx bills nothing.
+ *
+ * On disk: `~/.dario/ledger.json` for the default port, `ledger-<port>.json`
+ * for any other, so two instances sharing a home (the box's live-test rig
+ * runs one on :3999 next to production) do not overwrite each other's file.
+ * Writes are debounced and durable (`durableWriteFile`); the shutdown hook
+ * flushes what the debounce still holds, so at most the last few seconds
+ * before a SIGKILL are lost.
+ */
+import { readFile, mkdir, rename } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { durableWriteFile } from './durable-write.js';
+import { billingBucketFromClaim, costOfTokens, providerOfModel } from './analytics.js';
+export const LEDGER_VERSION = 1;
+/** The default proxy port; any other port gets its own ledger file. */
+const DEFAULT_PORT = 3456;
+/** Days kept before the oldest roll off — two years at one row per model per day. */
+export const LEDGER_MAX_DAYS = 730;
+/** How long after the last record the file is rewritten. */
+export const LEDGER_FLUSH_DELAY_MS = 3_000;
+export function ledgerPathFor(port, home = homedir()) {
+    return join(home, '.dario', port === DEFAULT_PORT ? 'ledger.json' : `ledger-${port}.json`);
+}
+/**
+ * `DARIO_LEDGER_PATH` names the file; `DARIO_LEDGER=0` (or `--no-ledger`)
+ * turns the ledger off. Off, /analytics reports `lifetime: null` and the
+ * usage command says so.
+ */
+export function resolveLedgerPath(port, env = process.env) {
+    const explicit = env['DARIO_LEDGER_PATH'];
+    return explicit && explicit.trim().length > 0 ? explicit.trim() : ledgerPathFor(port);
+}
+export function ledgerDisabledByEnv(env = process.env) {
+    return ['0', 'false', 'no', 'off'].includes((env['DARIO_LEDGER'] ?? '').toLowerCase());
+}
+const emptyCell = () => ({ requests: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreateTokens: 0 });
+export function emptyLedger(now = Date.now()) {
+    const iso = new Date(now).toISOString();
+    return { version: LEDGER_VERSION, since: iso, updated: iso, days: {} };
+}
+/** UTC calendar day of an epoch-ms timestamp. */
+export function dayKey(atMs) {
+    return new Date(atMs).toISOString().slice(0, 10);
+}
+/** Noon UTC of a day key — inside any intro window that ends that day. */
+function dayMs(day) {
+    return Date.parse(`${day}T12:00:00Z`);
+}
+/**
+ * Which bucket a record lands in, or null when it should not be counted.
+ * `api` and `extra_usage` are metered; every subscription claim, the codex
+ * claim, and an absent claim on a 2xx (stream aborts, api-key mode without
+ * the header) are covered — the request was served, and nothing says it was
+ * billed per token.
+ */
+export function ledgerBucketFor(record) {
+    if (record.status < 200 || record.status >= 300)
+        return null;
+    const bucket = billingBucketFromClaim(record.claim);
+    return bucket === 'api' || bucket === 'extra_usage' ? 'metered' : 'covered';
+}
+function isCell(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const c = v;
+    return ['requests', 'inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheCreateTokens']
+        .every((k) => typeof c[k] === 'number' && Number.isFinite(c[k]) && c[k] >= 0);
+}
+/**
+ * Parse a ledger file's text, keeping only well-formed rows. A file that is
+ * not a ledger at all throws; the caller moves it aside and starts fresh.
+ */
+export function parseLedger(text) {
+    const raw = JSON.parse(text);
+    if (!raw || typeof raw !== 'object' || raw.version !== LEDGER_VERSION || !raw.days || typeof raw.days !== 'object') {
+        throw new Error('not a dario ledger');
+    }
+    const days = {};
+    for (const [day, models] of Object.entries(raw.days)) {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(day) || !models || typeof models !== 'object')
+            continue;
+        const clean = {};
+        for (const [model, row] of Object.entries(models)) {
+            if (!row || typeof row !== 'object')
+                continue;
+            const r = {};
+            if (isCell(row.covered))
+                r.covered = { ...row.covered };
+            if (isCell(row.metered))
+                r.metered = { ...row.metered };
+            if (r.covered || r.metered)
+                clean[model] = r;
+        }
+        if (Object.keys(clean).length > 0)
+            days[day] = clean;
+    }
+    const since = typeof raw.since === 'string' && !Number.isNaN(Date.parse(raw.since)) ? raw.since : new Date().toISOString();
+    const updated = typeof raw.updated === 'string' && !Number.isNaN(Date.parse(raw.updated)) ? raw.updated : since;
+    return { version: LEDGER_VERSION, since, updated, days };
+}
+/** Add one record's tokens to the file in place. Returns false when it was not counted. */
+export function addToLedger(file, record) {
+    const bucket = ledgerBucketFor(record);
+    if (!bucket)
+        return false;
+    const day = dayKey(record.timestamp);
+    const model = record.model || 'unknown';
+    const models = (file.days[day] ??= {});
+    const row = (models[model] ??= {});
+    const cell = (row[bucket] ??= emptyCell());
+    cell.requests += 1;
+    cell.inputTokens += record.inputTokens;
+    cell.outputTokens += record.outputTokens;
+    cell.cacheReadTokens += record.cacheReadTokens;
+    cell.cacheCreateTokens += record.cacheCreateTokens;
+    if (Date.parse(file.since) > record.timestamp)
+        file.since = new Date(record.timestamp).toISOString();
+    pruneLedger(file);
+    return true;
+}
+/** Drop the oldest days past LEDGER_MAX_DAYS. */
+export function pruneLedger(file, maxDays = LEDGER_MAX_DAYS) {
+    const days = Object.keys(file.days).sort();
+    for (const day of days.slice(0, Math.max(0, days.length - maxDays)))
+        delete file.days[day];
+}
+// Six places, not the window's four: a handful of gpt-5.6-luna requests is
+// real money in the millionths and "$0 for 2 requests" reads as free.
+const round = (usd) => Math.round(usd * 1_000_000) / 1_000_000;
+export function summarizeLedger(file, path, now = Date.now()) {
+    const today = dayKey(now);
+    const cutoff7 = dayKey(now - 6 * 86_400_000);
+    const cutoff30 = dayKey(now - 29 * 86_400_000);
+    const perModel = {};
+    const perProvider = {
+        anthropic: { requests: 0, apiEquivalentCost: 0 },
+        openai: { requests: 0, apiEquivalentCost: 0 },
+    };
+    const tokens = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 };
+    let requests = 0;
+    let covered = 0;
+    let metered = 0;
+    const recent = { today: 0, last7d: 0, last30d: 0 };
+    for (const [day, models] of Object.entries(file.days)) {
+        const at = dayMs(day);
+        for (const [model, row] of Object.entries(models)) {
+            const m = (perModel[model] ??= {
+                provider: providerOfModel(model), requests: 0,
+                inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreateTokens: 0,
+                apiEquivalentCost: 0, meteredCost: 0,
+            });
+            if (row.covered) {
+                const cost = costOfTokens(model, at, row.covered);
+                covered += cost;
+                m.apiEquivalentCost += cost;
+                m.requests += row.covered.requests;
+                m.inputTokens += row.covered.inputTokens;
+                m.outputTokens += row.covered.outputTokens;
+                m.cacheReadTokens += row.covered.cacheReadTokens;
+                m.cacheCreateTokens += row.covered.cacheCreateTokens;
+                tokens.input += row.covered.inputTokens;
+                tokens.output += row.covered.outputTokens;
+                tokens.cacheRead += row.covered.cacheReadTokens;
+                tokens.cacheCreate += row.covered.cacheCreateTokens;
+                perProvider[m.provider].requests += row.covered.requests;
+                perProvider[m.provider].apiEquivalentCost += cost;
+                requests += row.covered.requests;
+                if (day === today)
+                    recent.today += cost;
+                if (day >= cutoff7)
+                    recent.last7d += cost;
+                if (day >= cutoff30)
+                    recent.last30d += cost;
+            }
+            if (row.metered) {
+                const cost = costOfTokens(model, at, row.metered);
+                metered += cost;
+                m.meteredCost += cost;
+                m.requests += row.metered.requests;
+                requests += row.metered.requests;
+            }
+        }
+    }
+    for (const m of Object.values(perModel)) {
+        m.apiEquivalentCost = round(m.apiEquivalentCost);
+        m.meteredCost = round(m.meteredCost);
+    }
+    for (const p of Object.values(perProvider))
+        p.apiEquivalentCost = round(p.apiEquivalentCost);
+    return {
+        path,
+        since: file.since,
+        days: Object.keys(file.days).length,
+        requests,
+        apiEquivalentCost: round(covered),
+        meteredCost: round(metered),
+        tokens,
+        perProvider,
+        perModel,
+        recent: { today: round(recent.today), last7d: round(recent.last7d), last30d: round(recent.last30d) },
+    };
+}
+/**
+ * Read a ledger file for display without a running proxy (`dario usage`
+ * when the proxy is down). Missing file → null; unreadable → null with the
+ * reason, never a throw.
+ */
+export async function readLedgerFile(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (err) {
+        const code = err.code;
+        return code === 'ENOENT' ? { file: null } : { file: null, error: err.message };
+    }
+    try {
+        return { file: parseLedger(text) };
+    }
+    catch (err) {
+        return { file: null, error: err.message };
+    }
+}
+export class Ledger {
+    path;
+    log;
+    file;
+    dirty = false;
+    timer = null;
+    writing = Promise.resolve();
+    closed = false;
+    constructor(path, file, log) {
+        this.path = path;
+        this.log = log;
+        this.file = file;
+    }
+    /**
+     * Load the ledger at `path`, or start one. A file that cannot be parsed is
+     * moved aside (`<path>.corrupt-<ts>`) rather than overwritten, so a bad
+     * write never silently zeroes two years of history.
+     */
+    static async open(path, log = () => { }) {
+        const { file, error } = await readLedgerFile(path);
+        if (file)
+            return new Ledger(path, file, log);
+        if (error) {
+            const aside = `${path}.corrupt-${Date.now()}`;
+            try {
+                await rename(path, aside);
+            }
+            catch { /* best effort — the next flush overwrites */ }
+            log(`[dario] ledger: could not read ${path} (${error}); moved aside to ${aside}, starting fresh`);
+        }
+        return new Ledger(path, emptyLedger(), log);
+    }
+    /** Count a request. Returns false when it was not ledger material. */
+    add(record) {
+        if (this.closed)
+            return false;
+        const counted = addToLedger(this.file, record);
+        if (counted)
+            this.scheduleFlush();
+        return counted;
+    }
+    summary(now = Date.now()) {
+        return summarizeLedger(this.file, this.path, now);
+    }
+    /** The raw per-day table, for /analytics/ledger. */
+    snapshot() {
+        return JSON.parse(JSON.stringify(this.file));
+    }
+    scheduleFlush() {
+        this.dirty = true;
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => { this.timer = null; void this.flush(); }, LEDGER_FLUSH_DELAY_MS);
+        this.timer.unref();
+    }
+    /** Write now if anything changed. Serialized; a failure is logged, not thrown. */
+    flush() {
+        if (!this.dirty)
+            return this.writing;
+        this.dirty = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.file.updated = new Date().toISOString();
+        const text = JSON.stringify(this.file);
+        this.writing = this.writing.then(async () => {
+            try {
+                await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+                await durableWriteFile(this.path, text, 0o600);
+            }
+            catch (err) {
+                this.dirty = true;
+                this.log(`[dario] ledger: write to ${this.path} failed: ${err.message}`);
+            }
+        });
+        return this.writing;
+    }
+    /** Final flush for the shutdown hook. */
+    async close() {
+        await this.flush();
+        this.closed = true;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Presentation — the number, formatted for a terminal and for a share card
+// ─────────────────────────────────────────────────────────────────────────
+export function formatUsd(usd) {
+    if (usd >= 100)
+        return `$${Math.round(usd).toLocaleString('en-US')}`;
+    if (usd >= 1)
+        return `$${usd.toFixed(2)}`;
+    if (usd === 0)
+        return '$0';
+    if (usd < 0.0001)
+        return '<$0.0001';
+    return `$${usd.toFixed(usd >= 0.01 ? 2 : 4)}`;
+}
+/** `claude-opus-5` → `Opus 5`, `claude-haiku-4-5-20251001` → `Haiku 4.5`, `gpt-5.6-terra` → `gpt-5.6-terra`. */
+export function shortModelName(model) {
+    const m = /^claude-([a-z]+)-(\d+)(?:-(\d+))?(?:-\d{8})?(\[[^\]]*\])?$/i.exec(model);
+    if (!m)
+        return model;
+    const family = m[1].charAt(0).toUpperCase() + m[1].slice(1);
+    return `${family} ${m[2]}${m[3] ? `.${m[3]}` : ''}${m[4] ?? ''}`;
+}
+const providerLabel = { anthropic: 'Claude', openai: 'ChatGPT' };
+/**
+ * The block `dario usage` prints above the rolling window. Two-space indent
+ * to match the rest of that command's output.
+ */
+export function formatLedgerSummary(s) {
+    const since = s.since.slice(0, 10);
+    const lines = [];
+    lines.push(`  API-equivalent spend (since ${since}, ${s.days} day${s.days === 1 ? '' : 's'}, ${s.requests.toLocaleString('en-US')} request${s.requests === 1 ? '' : 's'}):`);
+    lines.push(`    ${formatUsd(s.apiEquivalentCost)} would have been billed on the metered API — covered by subscriptions`);
+    const providers = Object.entries(s.perProvider)
+        .filter(([, p]) => p.requests > 0)
+        .sort((a, b) => b[1].apiEquivalentCost - a[1].apiEquivalentCost);
+    for (const [provider, p] of providers) {
+        const models = Object.entries(s.perModel)
+            .filter(([, m]) => m.provider === provider && m.apiEquivalentCost > 0)
+            .sort((a, b) => b[1].apiEquivalentCost - a[1].apiEquivalentCost)
+            .slice(0, 4)
+            .map(([id, m]) => `${shortModelName(id)} ${formatUsd(m.apiEquivalentCost)}`);
+        lines.push(`      ${providerLabel[provider].padEnd(8)} ${formatUsd(p.apiEquivalentCost).padStart(9)}   ${p.requests.toLocaleString('en-US')} req${p.requests === 1 ? '' : 's'}${models.length > 0 ? `   (${models.join(' · ')})` : ''}`);
+    }
+    lines.push(`    Today ${formatUsd(s.recent.today)} · Last 7d ${formatUsd(s.recent.last7d)} · Last 30d ${formatUsd(s.recent.last30d)}`);
+    if (s.meteredCost > 0)
+        lines.push(`    Paid per token on top (API key / extra usage): ${formatUsd(s.meteredCost)}`);
+    return lines;
+}
+const escapeXml = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+/**
+ * A share card: one SVG, 640×320, dark, the number in the middle. Plain
+ * system monospace so it renders the same in a README, a tweet screenshot
+ * and an <img> tag with nothing to fetch.
+ */
+export function renderLedgerCard(s) {
+    const providers = Object.entries(s.perProvider)
+        .filter(([, p]) => p.requests > 0)
+        .sort((a, b) => b[1].apiEquivalentCost - a[1].apiEquivalentCost)
+        .map(([provider, p]) => `${providerLabel[provider]} ${formatUsd(p.apiEquivalentCost)}`)
+        .join('   ·   ');
+    const since = s.since.slice(0, 10);
+    const headline = formatUsd(s.apiEquivalentCost);
+    const size = headline.length > 9 ? 56 : headline.length > 7 ? 68 : 80;
+    const meta = `${s.requests.toLocaleString('en-US')} requests  ·  since ${since}  ·  ${s.days} day${s.days === 1 ? '' : 's'}`;
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="640" height="320" viewBox="0 0 640 320" role="img" aria-label="${escapeXml(headline)} of API-equivalent usage covered by subscriptions through dario">
+  <defs>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#7c3aed"/>
+      <stop offset="1" stop-color="#db2777"/>
+    </linearGradient>
+    <clipPath id="card"><rect width="640" height="320" rx="20"/></clipPath>
+  </defs>
+  <rect width="640" height="320" rx="20" fill="#0a0a0f"/>
+  <rect x="0" y="0" width="640" height="6" fill="url(#accent)" clip-path="url(#card)"/>
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" fill="#e5e7eb">
+    <text x="40" y="66" font-size="15" fill="#9ca3af" letter-spacing="2">API-EQUIVALENT SPEND · COVERED BY SUBSCRIPTIONS</text>
+    <text x="40" y="160" font-size="${size}" font-weight="700" fill="#ffffff">${escapeXml(headline)}</text>
+    <text x="40" y="200" font-size="17" fill="#d1d5db">would have been billed on the metered API</text>
+    <text x="40" y="244" font-size="15" fill="#a78bfa">${escapeXml(providers)}</text>
+    <text x="40" y="284" font-size="13" fill="#6b7280">${escapeXml(meta)}</text>
+    <text x="600" y="284" font-size="13" fill="#6b7280" text-anchor="end">dario</text>
+  </g>
+</svg>
+`;
+}

package/dist/proxy.d.ts

@@ -326,6 +326,14 @@ interface ProxyOptions {
      * it off; with no fallback chain it is inert and says so on the first miss.
      */
     midstreamContinue?: boolean;
+    /**
+     * Keep the lifetime ledger (v6.6, src/ledger.ts): per-day, per-model token
+     * totals on disk, priced at read time, so /analytics and `dario usage` can
+     * say what the traffic would have cost on the metered API since the first
+     * request — across restarts. On by default; `--no-ledger` /
+     * `DARIO_LEDGER=0` turns it off, `DARIO_LEDGER_PATH` moves the file.
+     */
+    ledger?: boolean;
     sessionIdleRotateMs?: number;
     sessionRotateJitterMs?: number;
     sessionMaxAgeMs?: number;

package/dist/proxy.js

@@ -16,6 +16,7 @@ import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCo
 import { backfillIdentity } from './accounts.js';
 import { PoolSync, DEFAULT_POOL_SYNC_INTERVAL_MS } from './pool-sync.js';
 import { Analytics, billingBucketFromClaim, formatUsageLogLine, SUBSCRIPTION_CLAIMS, consumerFromHeader, consumerFromBody, CONSUMER_HEADER, CODEX_CLAIM } from './analytics.js';
+import { Ledger, resolveLedgerPath, ledgerDisabledByEnv } from './ledger.js';
 import { OverageGuard, buildHaltErrorBody } from './overage-guard.js';
 import { notify as osNotify } from './notify.js';
 import { grantAge, grantThresholds, worstGrantLevel, describeGrantAge } from './refresh-grant.js';
@@ -1445,6 +1446,19 @@ export async function startProxy(opts = {}) {
     // : null` — that gated the /analytics endpoint, but burn-rate /
     // per-request visibility is useful for a pool of one too.
     const analytics = new Analytics();
+    // The lifetime ledger rides the same record stream analytics emits, so
+    // every site that records a request feeds it without a second call. Off,
+    // /analytics reports `lifetime: null`.
+    const ledgerOn = opts.ledger !== false && !ledgerDisabledByEnv();
+    const ledger = ledgerOn ? await Ledger.open(resolveLedgerPath(port), (line) => console.log(line)) : null;
+    if (ledger) {
+        analytics.on('record', (r) => { ledger.add(r); });
+        if (verbose)
+            console.log(`[dario] ledger: ${ledger.path}`);
+    }
+    else {
+        console.log('[dario] ledger: disabled (--no-ledger)');
+    }
     // Per-alias request counts for GET /codex — the pool has requestCount per
     // account; the codex accounts had nothing until now.
     const codexRequestCounts = new Map();
@@ -2569,7 +2583,19 @@ export async function startProxy(opts = {}) {
             // `queue` rides along the summary (dario#905): request-queue.ts always
             // documented snapshot() as "exposed for /analytics", but it was never
             // actually wired in, so slot exhaustion was invisible from outside.
-            res.end(JSON.stringify({ ...analytics.summary(), queue: queue.snapshot() }));
+            res.end(JSON.stringify({ ...analytics.summary(), queue: queue.snapshot(), lifetime: ledger ? ledger.summary() : null }));
+            return;
+        }
+        // The ledger's per-day table, for anyone charting it. `lifetime` on
+        // /analytics is the summary; this is the data behind it.
+        if (urlPath === '/analytics/ledger' && req.method === 'GET') {
+            if (!ledger) {
+                res.writeHead(404, JSON_HEADERS);
+                res.end(JSON.stringify({ error: 'ledger disabled', hint: 'start without --no-ledger / DARIO_LEDGER=0' }));
+                return;
+            }
+            res.writeHead(200, JSON_HEADERS);
+            res.end(JSON.stringify({ path: ledger.path, ...ledger.snapshot() }));
             return;
         }
         // Analytics live stream — SSE of new RequestRecord JSON, one event
@@ -5532,7 +5558,7 @@ export async function startProxy(opts = {}) {
         // Flush tokens first (best-effort, bounded), then close the server. The
         // flush is fire-and-forget under the same 5s force-exit guard below so a
         // hung fsync can't wedge shutdown.
-        void flushPoolTokens().finally(() => {
+        void Promise.all([flushPoolTokens(), ledger?.close()]).finally(() => {
             server.close(() => process.exit(0));
         });
         // Force exit after 5s if connections (or the flush) don't complete.

package/dist/tui/tabs/analytics.d.ts

@@ -43,6 +43,14 @@ interface SummaryShape {
         currentUtil7d: number;
         lastClaim: string;
     }>;
+    /** The ledger's lifetime view (v6.6); null when the proxy runs --no-ledger, absent on older proxies. */
+    lifetime?: {
+        apiEquivalentCost: number;
+        since: string;
+        recent: {
+            today: number;
+        };
+    } | null;
 }
 export interface AnalyticsState {
     summary: SummaryShape | null;

package/dist/tui/tabs/analytics.js

@@ -14,6 +14,7 @@
 import { fg, dim, brand, progressBar, pad, truncate } from '../render.js';
 import { renderKvRow } from '../layout.js';
 import { fitPanels } from '../panels.js';
+import { formatUsd } from '../../ledger.js';
 const POLL_INTERVAL_MS = 2000;
 /**
  * Label column for the gauge rows (5h / 7d / Overage). Was 6, which is
@@ -97,13 +98,21 @@ export const AnalyticsTab = {
         counters.push('  ' + renderKvRow('Thinking tokens', formatNumber(s.window.totalThinkingTokens), w - 4));
         counters.push('  ' + renderKvRow('Avg latency', `${Math.round(s.window.avgLatencyMs)}ms`, w - 4));
         counters.push('  ' + renderKvRow('Subscription %', `${s.window.subscriptionPercent.toFixed(0)}%`, w - 4));
-        // Headline numbers — the two that answer "is this costing me money?"
+        // The ledger's number: what everything since the first request would
+        // have been billed on the metered API. Lifetime, not the window.
+        const lifetimeRow = s.lifetime
+            ? '  ' + renderKvRow('API-equivalent', `${formatUsd(s.lifetime.apiEquivalentCost)}  ${dim(`lifetime, ${formatUsd(s.lifetime.recent.today)} today, since ${s.lifetime.since.slice(0, 10)}`)}`, w - 4)
+            : null;
+        if (lifetimeRow)
+            counters.push(lifetimeRow);
+        // Headline numbers — the ones that answer "is this costing me money?"
         // survive as the collapsed form.
         panels.push({
             lines: counters,
             collapsed: ['',
                 '  ' + renderKvRow('Requests', `${s.window.requests}  ${dim(`(${rpm.toFixed(1)}/min)`)}`, w - 4),
-                '  ' + renderKvRow('Subscription %', `${s.window.subscriptionPercent.toFixed(0)}%`, w - 4)],
+                '  ' + renderKvRow('Subscription %', `${s.window.subscriptionPercent.toFixed(0)}%`, w - 4),
+                ...(lifetimeRow ? [lifetimeRow] : [])],
             priority: 1,
         });
         // ── Per-model bars ─────────────────────────────────────────

package/docs/api-equivalent-spend.md

@@ -0,0 +1,116 @@
+# API-equivalent spend — the ledger
+
+What the traffic dario has served would have cost on the metered API, kept
+across restarts. `dario usage` opens with it; `/analytics` carries it as
+`lifetime`; the TUI's Analytics tab shows it as **API-equivalent**.
+
+## Why a file
+
+`/analytics` is a rolling in-memory window: 10k records, gone on restart. It
+answers "what is this costing me right now" and could never answer the
+question a subscription user actually has — what has this saved me since I
+set it up. The ledger is the persistent half. It is deliberately small: one
+row per UTC day, per model, per billing bucket, holding a request count and
+the four token buckets (input, output, cache read, cache write). Nothing else.
+
+It never stores a price. Rows are priced when read, at the rate in effect on
+the row's day, from the same tables the rolling window uses (`PRICING` for
+Claude, `OPENAI_PRICING` for the ChatGPT leg, both in `src/analytics.ts`).
+Pricing has been wrong twice in this repo (#1047, #1048); a stored dollar
+figure would have frozen the wrong number in, a stored token count gets
+repriced the moment the table is fixed.
+
+## What counts
+
+Only responses with a 2xx status. A 429 carries no tokens and a 5xx bills
+nothing.
+
+Two columns per row:
+
+- **covered** — served against a subscription: every Anthropic subscription
+  claim (`five_hour`, `seven_day`, their `_fallback` and `_overage_included`
+  forms), the ChatGPT leg, and a 2xx that carried no claim at all (a stream
+  cut before the headers were read, api-key mode without the header). The
+  API-equivalent cost of this column is the headline — the invoice that never
+  arrived.
+- **metered** — billed per token anyway: an API key upstream (`api`) or
+  Anthropic's paid overage (`overage` → `extra_usage`). That money was spent.
+  It is reported on its own line ("Paid per token on top") and never counted
+  as saved.
+
+A mid-stream continuation (6.1) is two upstream requests and records as two
+rows, one per provider, each with the tokens that leg actually consumed.
+
+## Where it lives
+
+`~/.dario/ledger.json` for a proxy on the default port; `ledger-<port>.json`
+for any other, so two instances sharing a home (a live-test rig next to
+production) do not overwrite each other. `DARIO_LEDGER_PATH=<file>` moves it;
+`--no-ledger` / `DARIO_LEDGER=0` turns it off, after which `/analytics`
+reports `lifetime: null`, `/analytics/ledger` is a 404 and `dario usage` says
+so.
+
+Writes are debounced (3 s after the last record) and durable — temp file,
+fsync, rename, directory fsync, the same path the credential store uses
+(#790). The shutdown hook flushes what the debounce still holds, so a
+`docker rm -f` loses at most the last few seconds. A file that will not parse
+is moved aside as `ledger.json.corrupt-<ts>` and the ledger starts fresh; it
+is never overwritten in place. Days past 730 roll off the front.
+
+The test suite pins `DARIO_LEDGER_PATH` to a temp directory, so a suite run
+does not add stub traffic to the operator's file.
+
+## Reading it
+
+```
+$ dario usage
+  API-equivalent spend (since 2026-09-11, 3 days, 1,515 requests):
+    $413 would have been billed on the metered API — covered by subscriptions
+      Claude       $388   1,204 reqs   (Opus 5 $301 · Sonnet 5 $86.68)
+      ChatGPT    $24.75     311 reqs   (gpt-5.6-terra $24.75)
+    Today $48.20 · Last 7d $413 · Last 30d $413
+    Paid per token on top (API key / extra usage): $1.10
+```
+
+The proxy's view is preferred (it holds records the debounce has not flushed
+yet); with no proxy on the port, the command reads the file the proxy on that
+port would write. `--card[=file.svg]` renders the headline as a 640×320 SVG
+(default `dario-api-equivalent.svg`) — plain system monospace, nothing to
+fetch, so it looks the same in a README and a screenshot. `--json` is the raw
+`/analytics` payload, `lifetime` included.
+
+`GET /analytics` → `lifetime`:
+
+```json
+{
+  "path": "/root/.dario/ledger.json",
+  "since": "2026-09-11T02:14:09.000Z",
+  "days": 3,
+  "requests": 1515,
+  "apiEquivalentCost": 412.87,
+  "meteredCost": 1.1,
+  "tokens": { "input": 1204000, "output": 388000, "cacheRead": 91200000, "cacheCreate": 4100000 },
+  "perProvider": { "anthropic": { "requests": 1204, "apiEquivalentCost": 388.12 }, "openai": { "requests": 311, "apiEquivalentCost": 24.75 } },
+  "perModel": { "claude-opus-5": { "provider": "anthropic", "requests": 900, "apiEquivalentCost": 301.44, "meteredCost": 1.1, "...": "token totals" } },
+  "recent": { "today": 48.2, "last7d": 412.87, "last30d": 412.87 }
+}
+```
+
+`GET /analytics/ledger` is the file itself: `{ path, version, since, updated,
+days: { "YYYY-MM-DD": { "<model>": { covered: {…}, metered: {…} } } } }`.
+
+## Pricing on the ChatGPT leg
+
+Before 6.6 a `gpt-*` row fell through to the Claude fallback rate and the
+"would-be API cost" of a ChatGPT-plan request was Anthropic's Sonnet 4.6
+price for a model Anthropic does not sell. `OPENAI_PRICING` carries OpenAI's
+published standard-tier rates for the models the codex backend serves, read
+off `developers.openai.com/api/docs/pricing` on 2026-09-11. OpenAI charges
+nothing to write a cache entry, so cache-write tokens (which the codex path
+never reports anyway) are priced at the input rate. Unknown `gpt-*` ids take
+gpt-5.6-terra's rate, dario's default codex model.
+
+`scripts/check-pricing-drift.mjs` watches the Claude table against
+Anthropic's page. Nothing watches the OpenAI table yet — an entry that is
+correct today goes wrong the moment OpenAI changes it, and the only signal
+would be this number moving.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.5.0",
+  "version": "6.6.0",
   "description": "Use your Claude and ChatGPT subscriptions in Cursor, Cline, Aider, Claude Code and the Agent SDK — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint: either plan answers either wire shape, with automatic failover when one hits its limit.",
   "type": "module",
   "bin": {