@askalf/dario 6.5.0 → 6.6.1

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

@@ -41,7 +41,39 @@ export interface RequestRecord {
     status: number;
     isStream: boolean;
     isOpenAI: boolean;
+    /**
+     * Set when the stream died with content on the wire and the mid-stream
+     * guard acted (v6.1, src/midstream.ts): what came of it and, when a resume
+     * delivered, which leg served the rest. Absent on every ordinary request.
+     */
+    continuation?: RequestContinuation;
+}
+export interface RequestContinuation {
+    /** See midstream.ts ContinuationOutcome. */
+    outcome: 'continued' | 'continued-unfinished' | 'resume-failed' | 'no-target';
+    /** Label of the leg that served the rest (`gpt-5.6-terra (codex)`), when one did. */
+    by?: string;
+    /** Characters the client already had when the stream died. */
+    partialChars: number;
 }
+/**
+ * How the continuations in a window went. `attempted` is every stream that
+ * died with content on the wire and a guard in place; the other four
+ * partition it. The number that says whether --pool-fallback is set up to
+ * catch a dying stream, and how often one dies at all.
+ */
+export interface ContinuationStats {
+    attempted: number;
+    /** The client holds one complete message. */
+    finished: number;
+    /** A resume delivered content and then died too; the stream was left open-ended. */
+    unfinished: number;
+    /** Every choice delivered nothing; the stream ended truncated as before. */
+    failed: number;
+    /** Nothing to resume through — no --pool-fallback entry for the other provider. */
+    noTarget: number;
+}
+export declare function continuationStats(records: readonly RequestRecord[]): ContinuationStats;
 /**
  * The four billing buckets a request can land in, derived from the
  * `anthropic-ratelimit-unified-representative-claim` response header.
@@ -139,7 +171,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 +200,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;
@@ -281,6 +348,8 @@ interface WindowStats {
     estimatedCost: number;
     avgLatencyMs: number;
     errorRate: number;
+    /** Mid-stream continuations in the window and how they went (v6.1 guard, counted since v6.6.1). */
+    continuations: ContinuationStats;
     claimBreakdown: Record<string, number>;
     /** Count of requests in each derived billing bucket. See #34. */
     billingBucketBreakdown: Record<BillingBucket, number>;

package/dist/analytics.js

@@ -18,6 +18,29 @@
  */
 import { EventEmitter } from 'node:events';
 import { createHash } from 'node:crypto';
+export function continuationStats(records) {
+    const out = { attempted: 0, finished: 0, unfinished: 0, failed: 0, noTarget: 0 };
+    for (const r of records) {
+        if (!r.continuation)
+            continue;
+        out.attempted++;
+        switch (r.continuation.outcome) {
+            case 'continued':
+                out.finished++;
+                break;
+            case 'continued-unfinished':
+                out.unfinished++;
+                break;
+            case 'resume-failed':
+                out.failed++;
+                break;
+            case 'no-target':
+                out.noTarget++;
+                break;
+        }
+    }
+    return out;
+}
 /**
  * Map the raw `representative-claim` header value to a human-friendly
  * billing bucket. Pure function; no state; safe to call from any context.
@@ -206,16 +229,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 +287,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 = [];
@@ -323,6 +395,7 @@ export class Analytics extends EventEmitter {
                 totalInputTokens: 0, totalOutputTokens: 0, totalThinkingTokens: 0,
                 totalCacheReadTokens: 0, totalCacheCreateTokens: 0, cachedPromptPercent: 0,
                 estimatedCost: 0, avgLatencyMs: 0, errorRate: 0,
+                continuations: { attempted: 0, finished: 0, unfinished: 0, failed: 0, noTarget: 0 },
                 claimBreakdown: {},
                 billingBucketBreakdown: {
                     subscription: 0,
@@ -369,6 +442,7 @@ export class Analytics extends EventEmitter {
             estimatedCost: Math.round(cost * 10000) / 10000,
             avgLatencyMs: Math.round(avgLatency),
             errorRate: Math.round((errors / records.length) * 10000) / 10000,
+            continuations: continuationStats(records),
             claimBreakdown: claims,
             billingBucketBreakdown: buckets,
             subscriptionPercent: subscriptionPct,

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).');
@@ -2393,6 +2450,19 @@ async function usage() {
         if ((win.estimatedCost ?? 0) > 0) {
             console.log(`  Est. cost:       $${(win.estimatedCost ?? 0).toFixed(4)} (would-be API cost)`);
         }
+        // Streams that died with content on the wire, and what the mid-stream
+        // guard made of them. Silent when none did — the common case.
+        const c = win.continuations;
+        if (c && c.attempted > 0) {
+            const parts = [`${c.finished} finished`];
+            if (c.unfinished > 0)
+                parts.push(`${c.unfinished} unfinished`);
+            if (c.failed > 0)
+                parts.push(`${c.failed} failed`);
+            if (c.noTarget > 0)
+                parts.push(`${c.noTarget} no target — set --pool-fallback for the other provider`);
+            console.log(`  Continuations:   ${c.attempted} stream${c.attempted === 1 ? '' : 's'} died mid-answer: ${parts.join(', ')}`);
+        }
     }
     if (perAccount && Object.keys(perAccount).length > 0) {
         console.log('');

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;