@askalf/dario 6.4.0 → 6.6.0

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';
@@ -31,7 +32,7 @@ import { responsesRequestToAnthropic, unsupportedOnClaudeError, ResponsesRequest
 import { isClaudeServableModel } from './claude-model.js';
 import { MODEL_UNROUTABLE } from './upstream-rejection.js';
 import { readCompareTarget, teeResponse, runCompare, writeCompareRecord, COMPARE_RESULT_HEADER } from './compare.js';
-import { listCodexAccountAliases, loadAllCodexAccounts, codexAccountNeedsRefresh, hasAnyCodexAccount, selectCodexAccount, getFreshCodexAccount, getCodexRefreshFailure, CodexCredentialsUnavailableError } from './codex-accounts.js';
+import { listCodexAccountAliases, loadAllCodexAccounts, codexAccountNeedsRefresh, hasAnyCodexAccount, selectCodexAccount, selectCodexAccountExcluding, rebindCodexSticky, getFreshCodexAccount, noteCodexDecline, clearCodexDecline, allAliasesCooled, getCodexRefreshFailure, CodexCredentialsUnavailableError } from './codex-accounts.js';
 import { route as routeProvider } from './provider-adapter.js';
 import { selectPoolFallbackModels } from './pool-fallback-tier.js';
 import { RequestQueue, QueueFullError, QueueTimeoutError, DEFAULT_MAX_CONCURRENT, DEFAULT_MAX_QUEUED, DEFAULT_QUEUE_TIMEOUT_MS } from './request-queue.js';
@@ -163,6 +164,30 @@ function extractFirstUserMessage(body) {
     }
     return '';
 }
+/**
+ * The conversation key for Codex seat stickiness, from raw request bytes.
+ *
+ * The same hash the Claude pool binds on (computeStickyKey over the first user
+ * message), so a conversation stays on one ChatGPT seat across turns and keeps
+ * the prompt-cache prefix it built there — rotating per request would trade a
+ * rate-limit problem for a cache problem.
+ *
+ * Null for a body that is not a JSON object or carries no user message; those
+ * requests bypass stickiness rather than sharing one bucket. Used by the two
+ * codex entries that hold no parsed body of their own (the pool-exhausted
+ * fallback and the mid-stream continuation target).
+ */
+function codexStickyKeyForBody(body) {
+    try {
+        const parsed = JSON.parse(body.toString('utf-8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        return computeStickyKey(extractFirstUserMessage(parsed));
+    }
+    catch {
+        return null;
+    }
+}
 // Session ID behavior:
 //   v3.18 rotated per request — which was itself a fingerprint. Real CC
 //   rotates roughly once per conversation, not per call. A user who has
@@ -1421,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();
@@ -1999,6 +2037,47 @@ export async function startProxy(opts = {}) {
     function checkAuth(req) {
         return authenticateRequest(req.headers, apiKeyBuf);
     }
+    /**
+     * A ChatGPT seat declined. Cool the SEAT, and the provider only once every
+     * seat is cooling.
+     *
+     * One handler for every codex forward — both wire shapes and the
+     * Claude-to-Codex fallback. It was two hand-copied copies, and that is
+     * precisely how the native Responses path ended up cooling nothing while
+     * the translated path cooled correctly: a third call site inherits this by
+     * construction rather than by someone remembering to copy it.
+     *
+     * Closes over nothing per-request, which is what makes one copy possible.
+     */
+    const codexOnDecline = (d) => {
+        // Cool the PROVIDER (is the codex lane usable at all) and the SEAT
+        // that actually declined (which ChatGPT account said no, and for how
+        // long). Before the seat half existed, selectCodexAccount returned the
+        // alphabetically-first account every time, so one 429'd seat took the
+        // whole lane down while its healthy peers sat unreachable.
+        if (d.status !== 429)
+            return;
+        // A 429 is a SEAT-level condition, so cool the seat unconditionally.
+        // The provider is only cooled once EVERY seat is cooling.
+        //
+        // Cooling the provider on any single 429 defeats the pool: the routing
+        // gate short-circuits on canAttempt('codex'), so the next request never
+        // reaches selectCodexAccount to find the healthy peer — the exact
+        // single-seat outage this change exists to remove (caught in review of
+        // #1288). Dropping provider cooling altogether is equally wrong the other
+        // way: on a single-seat deployment nothing would fail fast, and every
+        // request would re-hammer a seat already known to be limited instead of
+        // falling through to Claude. All-seats-cooled is the condition that means
+        // what the provider cool-down was always trying to say.
+        noteCodexDecline(d.alias, d.retryAfterMs);
+        void listCodexAccountAliases().then((aliases) => {
+            // Decide and write in the SAME tick — see allAliasesCooled. An await
+            // between the two lets a concurrent success clear a seat in the gap,
+            // and the late write then cools a pool that has recovered.
+            if (allAliasesCooled(aliases))
+                providerCooldowns.note('codex', d.retryAfterMs);
+        }).catch(() => { });
+    };
     /**
      * Serve a pool-exhausted request from the ChatGPT subscription (v6.0.0).
      *
@@ -2025,50 +2104,101 @@ export async function startProxy(opts = {}) {
             return false;
         if (!(await hasAnyCodexAccount().catch(() => false)))
             return false;
-        const stored = await selectCodexAccount().catch(() => null);
+        // Sticky on the CONVERSATION, not on this fallback hop: a conversation
+        // that reaches the subscription twice lands on the same seat both times,
+        // so the second turn reads the prefix the first one paid to create.
+        const stickyKey = codexStickyKeyForBody(body);
+        const stored = await selectCodexAccount(undefined, { stickyKey }).catch(() => null);
         if (!stored)
             return false;
-        let creds;
+        let seat;
         try {
-            creds = await getFreshCodexAccount(stored);
+            seat = await getFreshCodexAccount(stored);
         }
         catch {
             return false;
         }
-        const slugs = await getCodexModelSlugs(creds).catch(() => []);
-        const fallbackPick = pickCodexFallback(fallbackModels, slugs);
-        if (!fallbackPick)
-            return false;
-        const fallbackModel = fallbackPick.model;
-        const fallbackBody = buildPoolFallbackBody(body, fallbackModel);
-        if (!fallbackBody)
-            return false;
-        console.log(`[dario] #${requestCount} ${why} → codex account ${creds.alias} as ${fallbackModel}`);
-        requestCount++;
-        attempted.add('codex');
         // If an api-key backend could ALSO serve this request, let the subscription
         // decline a 429/5xx rather than answer with it, and report not-served so the
-        // caller falls through to that backend. This helper's contract has always
-        // said it declines so the caller can continue; it just never exercised the
-        // mechanism it was built on, so a rate-limited subscription ended the chain
-        // with a healthy backend sitting unused beside it.
+        // caller falls through to that backend.
         //
-        // With NO next option, do not defer: the real upstream error is more useful
-        // to the client than replacing it with a generic 503.
+        // With NO next option and no peer, do not defer: the real upstream error is
+        // more useful to the client than replacing it with a generic 503.
         const hasNextOption = openaiBackend !== null && shape === 'openai';
-        const served = await forwardToCodex(req, res, fallbackBody, creds, corsOrigin, { ...SECURITY_HEADERS, 'x-dario-pool-fallback': fallbackModel }, upstreamTimeoutMs, verbose, shape, fetch, hasNextOption, undefined, 
-        // Only a rate limit cools the provider. A 5xx or a transport failure is
-        // an outage, not quota — cooling it would park a provider that may be
-        // back on the next request, which is the opposite of the fix.
-        (d) => { if (d.status === 429)
-            providerCooldowns.note('codex', d.retryAfterMs); }, 
-        // The mirror of the Claude side (dario#1161): an operator who writes
-        // `--pool-fallback=gpt-5.6-terra:high` is choosing the effort the
-        // failover runs at, so the entry's own suffix reaches the request rather
-        // than the failover quietly running at the backend default.
-        effortForCodex(fallbackPick.effort));
-        if (served)
+        // The next seat that could serve one of these fallback models, excluding
+        // everything already tried. `peek` is the cached read, so the scan costs no
+        // upstream call; a seat whose model list is unknown is still worth a try.
+        //
+        // Scans rather than testing one candidate: with mixed model availability
+        // across seats, the alphabetically-next peer may be the one that lists none
+        // of the fallback models while a later one lists one.
+        const nextFallbackPeer = async (tried) => {
+            const skipped = new Set(tried);
+            for (;;) {
+                const candidate = await selectCodexAccountExcluding(skipped).catch(() => null);
+                if (!candidate)
+                    return null;
+                const peerSlugs = peekCodexModelSlugs(candidate.alias);
+                if (!peerSlugs || pickCodexFallback(fallbackModels, peerSlugs))
+                    return candidate;
+                skipped.add(candidate.alias);
+            }
+        };
+        // Mid-flight seat failover on the CLAUDE-TO-CODEX route, the same as the
+        // primary Codex route has. Without it this route selected one seat and
+        // stopped: a 429 from that seat was written to the client while a healthy
+        // peer sat unused, so the pool helped every route except this one (caught
+        // in review of #1288). The fallback model is re-picked per seat because
+        // pickCodexFallback reads that SEAT's slugs — peers need not list the same
+        // model, and the one that answers may answer as a different one.
+        //
+        // Terminates by construction: every pass adds a seat to `tried`, and
+        // nextFallbackPeer never returns one already in it.
+        const tried = new Set();
+        let served = false;
+        while (seat) {
+            tried.add(seat.alias);
+            const slugs = await getCodexModelSlugs(seat).catch(() => []);
+            const fallbackPick = pickCodexFallback(fallbackModels, slugs);
+            // Resolved BEFORE the attempt: it decides whether this attempt may defer,
+            // and becomes the seat to retry on if it declines.
+            const peer = await nextFallbackPeer(tried);
+            if (!fallbackPick) {
+                // This seat lists none of the fallback models. That used to end the
+                // attempt outright; a peer may still list one.
+                if (!peer)
+                    return false;
+                seat = await getFreshCodexAccount(peer).catch(() => peer);
+                continue;
+            }
+            const fallbackModel = fallbackPick.model;
+            const fallbackBody = buildPoolFallbackBody(body, fallbackModel);
+            if (!fallbackBody)
+                return false;
+            console.log(`[dario] #${requestCount} ${why} → codex account ${seat.alias} as ${fallbackModel}`);
+            requestCount++;
+            // Marked only once an attempt is actually being made. Marking it before
+            // the guards above would tell the rest of the request that codex had been
+            // tried when it had not, suppressing a later legitimate attempt.
+            attempted.add('codex');
+            served = await forwardToCodex(req, res, fallbackBody, seat, corsOrigin, { ...SECURITY_HEADERS, 'x-dario-pool-fallback': fallbackModel }, upstreamTimeoutMs, verbose, shape, fetch, hasNextOption || peer !== null, undefined, codexOnDecline, 
+            // The mirror of the Claude side (dario#1161): an operator who writes
+            // `--pool-fallback=gpt-5.6-terra:high` is choosing the effort the
+            // failover runs at, so the entry's own suffix reaches the request rather
+            // than the failover quietly running at the backend default.
+            effortForCodex(fallbackPick.effort));
+            if (served || !peer)
+                break;
+            console.log(`[dario] codex seat ${seat.alias} declined — retrying this fallback on ${peer.alias}`);
+            // The conversation follows the request. Its binding still names the seat
+            // that just declined; leaving it there would send the next turn back to a
+            // cooling seat and re-pick from scratch.
+            rebindCodexSticky(stickyKey, peer.alias);
+            seat = await getFreshCodexAccount(peer).catch(() => peer);
+        }
+        if (served) {
             providerCooldowns.clear('codex');
+        }
         return served;
     };
     /**
@@ -2453,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
@@ -3027,7 +3169,10 @@ export async function startProxy(opts = {}) {
                     return null;
                 if (!(await hasAnyCodexAccount().catch(() => false)))
                     return null;
-                const stored = await selectCodexAccount().catch(() => null);
+                // The CLIENT's bytes rather than the rewritten `body`: a resume is the
+                // same conversation as the request that died mid-stream, so it must
+                // hash to the same key and land on the seat that conversation holds.
+                const stored = await selectCodexAccount(undefined, { stickyKey: codexStickyKeyForBody(clientBodyBytes) }).catch(() => null);
                 if (!stored)
                     return null;
                 let creds;
@@ -3328,8 +3473,17 @@ export async function startProxy(opts = {}) {
                     // account, rather than letting the throw escape into the JSON-peek
                     // catch below and disappear (DEV-179a412f).
                     let codexUnavailable = null;
+                    // Conversation -> seat binding for the codex lane, the mirror of the
+                    // Claude pool's stickyKey below. It belongs HERE because this is
+                    // where the seat is CHOSEN: without a key every turn independently
+                    // re-picks "the first seat not cooling", so a lower-alias seat that
+                    // frees up mid-conversation silently moves the conversation off the
+                    // seat holding its prompt-cache prefix (caught in review of #1288).
+                    // `parsedBody` is the object the invalid-body guard already parsed,
+                    // so this costs no second JSON.parse.
+                    const codexStickyKey = parsedBody ? computeStickyKey(extractFirstUserMessage(parsedBody)) : null;
                     if (await hasAnyCodexAccount()) {
-                        const stored = await selectCodexAccount();
+                        const stored = await selectCodexAccount(undefined, { stickyKey: codexStickyKey });
                         if (stored) {
                             try {
                                 codexCreds = await getFreshCodexAccount(stored);
@@ -3466,14 +3620,22 @@ export async function startProxy(opts = {}) {
                                 },
                             })
                             : null;
-                        // Before this hook a codex request left no trace: nothing in
-                        // /analytics, nothing in the request log, no per-account count.
-                        // The dock (and anyone reading /analytics) saw a proxy that
-                        // served GPT all day and reported zero of it. A decline (the
-                        // request handed to the Claude pool) reports nothing here; the
-                        // Claude path records what it then serves.
+                        // Reporting is one function for BOTH codex shapes below: the Responses
+                        // passthrough and the translated Messages path record the same row, so a
+                        // GPT request looks the same in /analytics whichever shape asked for it.
+                        //
+                        // Before this hook a codex request left no trace: nothing in /analytics,
+                        // nothing in the request log, no per-account count. The dock (and anyone
+                        // reading /analytics) saw a proxy that served GPT all day and reported
+                        // zero of it. A decline (the request handed to the Claude pool) reports
+                        // nothing here; the Claude path records what it then serves.
                         const codexOnDone = (o) => {
                             codexRequestCounts.set(o.alias, (codexRequestCounts.get(o.alias) ?? 0) + 1);
+                            // A seat that actually SERVED is not rate-limited. Keyed on a 2xx,
+                            // never on forwardToCodex returning true — that means "I wrote a
+                            // response", which is equally true when it wrote the upstream 429.
+                            if (o.status >= 200 && o.status < 300)
+                                clearCodexDecline(o.alias);
                             analytics.record({
                                 timestamp: Date.now(),
                                 consumer,
@@ -3502,24 +3664,83 @@ export async function startProxy(opts = {}) {
                                     cacheReadTokens: o.cacheReadTokens, cacheCreateTokens: o.cacheCreateTokens,
                                 }, consumer));
                         };
-                        // A Responses client on a ChatGPT-subscription model: the backend
-                        // speaks that shape natively, so the body goes through as written
-                        // (model resolved) and the SSE comes back untouched — no round
-                        // trip through the Messages shape, which cannot carry the newest
-                        // Codex CLI request features. Answers on the raw response: these
-                        // bytes are already in the client's shape.
-                        const served = codexAvailable && (isResponses && responsesBodyRaw
-                            ? await forwardResponsesToCodex(rawRes, { ...responsesBodyRaw, model: rawModel }, codexCreds, corsOrigin, SECURITY_HEADERS, upstreamTimeoutMs, verbose, codexFetch, codexOnDone)
-                            : await forwardToCodex(req, res, body, codexCreds, corsOrigin, SECURITY_HEADERS, upstreamTimeoutMs, verbose, isOpenAI ? 'openai' : 'anthropic', codexFetch, canDefer, codexOnDone, 
-                            // Cool codex on a rate limit only — a 5xx or an unreachable backend
-                            // is an outage, and parking a provider for that would keep it out
-                            // of the chain while it was already coming back.
-                            (d) => { if (d.status === 429)
-                                providerCooldowns.note('codex', d.retryAfterMs); }, 
-                            // dario#1260 — the effort named by the model-name suffix stripped
-                            // above. Undefined for every request that did not name one, which
-                            // leaves the outbound body exactly as it was.
-                            effortForCodex(requestEffort), codexGuard));
+                        // Mid-flight seat failover. A 429 lands BEFORE any body is written —
+                        // forwardToCodex only returns false on the decline path — so the same
+                        // request can be handed to a healthy peer instead of failing. Without
+                        // this the pool only helps the request AFTER the one that discovered the
+                        // limit; the discovering request still failed, every window rollover.
+                        //
+                        // `deferOnUnavailable` is widened to `canDefer || a peer exists`: without
+                        // that, a decline with no Claude fallback configured writes the 429 to the
+                        // client and returns true, and there is nothing left to retry onto.
+                        //
+                        // Terminates by construction: every pass adds a seat to `codexTried`, and
+                        // selectCodexAccountExcluding never returns a seat already in it.
+                        let served = false;
+                        if (codexAvailable) {
+                            const codexTried = new Set();
+                            let codexSeat = codexCreds;
+                            while (codexSeat) {
+                                codexTried.add(codexSeat.alias);
+                                // Resolved BEFORE the attempt: it decides whether this attempt may
+                                // defer, and becomes the seat to retry on if it declines.
+                                // A peer that demonstrably does not list this model cannot serve it;
+                                // trying it would trade a 429 for a 400. peek is the cached read, so
+                                // this never costs an upstream call — an unknown list still gets a try.
+                                //
+                                // Scanning rather than testing one candidate: with mixed model
+                                // availability across seats, the alphabetically-next peer may be the
+                                // one that cannot serve this model while a later one can. Stopping at
+                                // the first incompatible candidate left `codexPeer` null and abandoned
+                                // a usable seat — with no Claude fallback the declining seat's 429 went
+                                // straight to the client (caught in review of #1288). `peerTried` is
+                                // seeded from `codexTried` and grows every pass, so this terminates.
+                                let codexPeer = null;
+                                const peerTried = new Set(codexTried);
+                                for (;;) {
+                                    const candidate = await selectCodexAccountExcluding(peerTried).catch(() => null);
+                                    if (!candidate)
+                                        break;
+                                    const peerSlugs = rawModel ? peekCodexModelSlugs(candidate.alias) : null;
+                                    if (!peerSlugs || isCodexModel(rawModel, peerSlugs)) {
+                                        codexPeer = candidate;
+                                        break;
+                                    }
+                                    peerTried.add(candidate.alias);
+                                }
+                                // A Responses client on a ChatGPT-subscription model: the backend speaks
+                                // that shape natively, so the body goes through as written (model
+                                // resolved) and the SSE comes back untouched — no round trip through the
+                                // Messages shape, which cannot carry the newest Codex CLI request
+                                // features. Answers on the raw response: these bytes are already in the
+                                // client's shape.
+                                //
+                                // It sits INSIDE the retry loop, on the same seat sequence and the same
+                                // defer condition as the translated path. Outside it, a 429 on this shape
+                                // cooled nothing: selection handed the same limited seat back on every
+                                // following request and a healthy peer was never reached — the single-seat
+                                // outage this change exists to remove, surviving on the one shape Codex
+                                // CLI actually speaks (caught in review of #1288).
+                                if (isResponses && responsesBodyRaw) {
+                                    served = await forwardResponsesToCodex(rawRes, { ...responsesBodyRaw, model: rawModel }, codexSeat, corsOrigin, SECURITY_HEADERS, upstreamTimeoutMs, verbose, codexFetch, codexOnDone, codexOnDecline, canDefer || codexPeer !== null);
+                                }
+                                else {
+                                    served = await forwardToCodex(req, res, body, codexSeat, corsOrigin, SECURITY_HEADERS, upstreamTimeoutMs, verbose, isOpenAI ? 'openai' : 'anthropic', codexFetch, canDefer || codexPeer !== null, codexOnDone, codexOnDecline, 
+                                    // dario#1260 — the effort named by the model-name suffix stripped
+                                    // above. Undefined for every request that did not name one, which
+                                    // leaves the outbound body exactly as it was.
+                                    effortForCodex(requestEffort), codexGuard);
+                                }
+                                if (served || !codexPeer)
+                                    break;
+                                console.log(`[dario] codex seat ${codexSeat.alias} declined — retrying this request on ${codexPeer.alias}`);
+                                // The conversation follows the request. Its binding still names
+                                // the seat that just declined; leaving it there would send the
+                                // next turn back to a cooling seat and re-pick from scratch.
+                                rebindCodexSticky(codexStickyKey, codexPeer.alias);
+                                codexSeat = await getFreshCodexAccount(codexPeer).catch(() => codexPeer);
+                            }
+                        }
                         if (served) {
                             // A provider that just served is not rate-limited.
                             providerCooldowns.clear('codex');
@@ -5337,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.4.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": {