@askalf/dario 6.4.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/codex-accounts.d.ts

@@ -61,14 +61,88 @@ export declare function _resetCodexRefreshFailuresForTest(): void;
  * a misleading "run `dario login`" answer to the client.
  */
 export declare function getFreshCodexAccount(creds: CodexAccountCredentials): Promise<CodexAccountCredentials>;
+/** Record that `alias` declined, for as long as the upstream asked. */
+export declare function noteCodexDecline(alias: string, retryAfterMs?: number | null): number;
+/** A seat that just served is not rate-limited — clear it. */
+export declare function clearCodexDecline(alias: string): void;
+/** Ms until `alias` is askable again; 0 when it is askable now. */
+export declare function codexCooldownRemainingMs(alias: string): number;
+/** Test seam — forget every cool-down and binding. */
+export declare function _resetCodexPoolForTest(): void;
+/** The alias currently bound to a conversation, or null. */
+export declare function codexStickyAliasFor(key: string | null | undefined): string | null;
 /**
- * Pick the account to serve a request. Single account is the expected case (one
- * ChatGPT subscription); with several, `DARIO_CODEX_ACCOUNT` names one and
- * otherwise the first alphabetically wins. No rotation/least-recently-used
- * balancing — a subscription is per-seat, so spreading load across seats is the
- * user's decision to make explicitly, not something to do implicitly.
+ * Move a conversation onto `alias`, the codex mirror of pool.rebindSticky.
+ *
+ * Selection binds a conversation to the seat it picked; mid-request failover
+ * then moves it, and without this the binding still names the seat that just
+ * declined — the next turn would read a stale binding, find it cooling, and
+ * re-pick from scratch. A null key is accepted so the caller does not have to
+ * guard: a request with no hashable first user message has no conversation to
+ * bind.
+ */
+export declare function rebindCodexSticky(key: string | null | undefined, alias: string): void;
+/**
+ * Choose a ChatGPT seat for this request.
+ *
+ * Order, most specific first:
+ *   1. an explicitly named alias (`x-dario-account`, DARIO_CODEX_ACCOUNT) — a
+ *      pin is an instruction, so it is honoured even while cooling; the caller
+ *      asked for that seat and gets its answer, 429 included.
+ *   2. the seat this conversation is already bound to, unless it is cooling.
+ *   3. the first seat alphabetically that is not cooling — deterministic, so a
+ *      given conversation lands on the same seat across a restart and keeps its
+ *      prompt cache.
+ *   4. null when every seat is cooling. The caller answers from that rather
+ *      than spending a request that can only 429 again.
+ */
+export declare function selectCodexAccount(preferredAlias?: string, opts?: {
+    stickyKey?: string | null;
+}): Promise<CodexAccountCredentials | null>;
+/**
+ * The next askable seat that this request has NOT already tried.
+ *
+ * Mid-flight failover: a seat that 429s during a request hands the SAME
+ * request to a peer rather than failing it. Without this the pool only helps
+ * the request AFTER the one that discovered the limit — the discovering
+ * request still failed, every time a window rolled over.
+ *
+ * `tried` is per-request, so a seat already attempted here is never revisited
+ * inside the same request even if its cool-down has not landed yet. That is
+ * the codex mirror of the Claude pool's selectExcluding, and it is what makes
+ * the loop terminate: every pass adds a seat, so it is bounded by pool size.
+ *
+ * Stickiness is deliberately NOT consulted. The bound seat is the one that
+ * just declined; re-offering it would loop, and a conversation whose seat has
+ * gone away is better served elsewhere than not at all.
+ */
+export declare function selectCodexAccountExcluding(tried: ReadonlySet<string>): Promise<CodexAccountCredentials | null>;
+/** Every seat is cooling — the fail-fast condition, for the caller's message. */
+/**
+ * Are ALL of these aliases cooling, right now?
+ *
+ * Synchronous on purpose. The provider-wide cool-down is written from this
+ * answer, and an `await` between deciding and writing is a window another
+ * in-flight request can use: the last-limited-seat request observes every seat
+ * cooling, a peer then succeeds on a just-recovered seat and calls
+ * clearCodexDecline, and the delayed continuation re-cools the whole provider
+ * against a pool that is healthy again. canAttempt('codex') then short-circuits
+ * and the healthy seat is skipped until the stale window expires — the exact
+ * single-seat outage this pool exists to prevent, reintroduced by the
+ * bookkeeping meant to prevent it.
+ *
+ * Re-checking inside the continuation narrows that window; it does not close
+ * it, because the re-check is itself another await. Taking the alias list first
+ * and then deciding-and-writing with no suspension point between them closes it
+ * outright: JS runs that callback as one unit, so nothing can interleave.
+ *
+ * The alias list may be a tick stale, which is harmless — a seat added in that
+ * window is not cooling, so "all cooled" is false on the next decline anyway.
  */
-export declare function selectCodexAccount(preferredAlias?: string): Promise<CodexAccountCredentials | null>;
+export declare function allAliasesCooled(aliases: readonly string[]): boolean;
+export declare function allCodexAccountsCooled(): Promise<boolean>;
+/** Longest remaining cool-down across every seat, for a `retry-after`. */
+export declare function codexPoolRetryAfterMs(): Promise<number>;
 /**
  * Parse whatever the user pastes back after authorizing.
  *

package/dist/codex-accounts.js

@@ -15,6 +15,7 @@ import { homedir } from 'node:os';
 import { randomBytes } from 'node:crypto';
 import { generateCodexPKCE, buildCodexAuthorizeUrl, exchangeCodexAuthorizationCode, refreshCodexAccessToken, CodexRefreshError, } from './codex-oauth.js';
 import { durableWriteFile } from './durable-write.js';
+import { ProviderCooldowns } from './provider-cooldown.js';
 const DARIO_DIR = join(homedir(), '.dario');
 const CODEX_ACCOUNTS_DIR = join(DARIO_DIR, 'codex-accounts');
 /** Same alias charset/traversal guard as accounts.ts's safeAliasPath. */
@@ -298,7 +299,105 @@ export async function getFreshCodexAccount(creds) {
  * balancing — a subscription is per-seat, so spreading load across seats is the
  * user's decision to make explicitly, not something to do implicitly.
  */
-export async function selectCodexAccount(preferredAlias) {
+/**
+ * Per-seat cool-downs and conversation stickiness for the ChatGPT pool
+ * (dario#1244 follow-up).
+ *
+ * Until now selectCodexAccount returned `sort()[0]` — the alphabetically FIRST
+ * account, every time. `dario add altman` will happily store a dozen seats and
+ * dario would use exactly one of them. That is why the account-wide 429 on
+ * 2026-09-07 took the whole GPT lane down: a second seat sat there, healthy and
+ * unreachable, while every request failed over to Claude.
+ *
+ * Reuses ProviderCooldowns keyed by ALIAS rather than by provider name. It is
+ * already the right shape — arbitrary string key, injectable clock, entries
+ * dropped on read — so the pool needs no second cool-down implementation.
+ *
+ * ROTATION IS PER-CONVERSATION, NOT PER-REQUEST, and that is the whole design.
+ * The Codex prompt cache is scoped to the serving account: a conversation that
+ * builds a prefix on seat A reads nothing from it on seat B, and measured cache
+ * share on this lane is 59% in production against a 73% controlled ceiling.
+ * Rotating per request would trade a rate-limit problem for a cache problem and
+ * come out behind. So a conversation binds to a seat and stays there until that
+ * seat actually declines.
+ *
+ * Deliberately NOT headroom routing like the Claude pool. Claude responds with
+ * `anthropic-ratelimit-*` headers on every response, so that pool can read
+ * utilisation before it picks. The Codex backend states nothing until it 429s —
+ * the only signal is the decline itself plus its `retry-after` — so this is
+ * fill-first with cool-down eviction, which is what the available signal
+ * supports. If the backend ever starts reporting utilisation, this is where
+ * headroom would go.
+ */
+let codexCooldowns = new ProviderCooldowns();
+/** conversation sticky key -> alias. Bounded; swept when it exceeds the cap. */
+const codexSticky = new Map();
+const CODEX_STICKY_MAX = 500;
+/** Record that `alias` declined, for as long as the upstream asked. */
+export function noteCodexDecline(alias, retryAfterMs) {
+    return codexCooldowns.note(alias, retryAfterMs);
+}
+/** A seat that just served is not rate-limited — clear it. */
+export function clearCodexDecline(alias) {
+    codexCooldowns.clear(alias);
+}
+/** Ms until `alias` is askable again; 0 when it is askable now. */
+export function codexCooldownRemainingMs(alias) {
+    return codexCooldowns.remainingMs(alias);
+}
+/** Test seam — forget every cool-down and binding. */
+export function _resetCodexPoolForTest() {
+    codexSticky.clear();
+    // A fresh instance rather than clearing per alias: the previous version
+    // emptied the sticky map first and then iterated it, so it cleared nothing
+    // and cool-downs leaked between test cases.
+    codexCooldowns = new ProviderCooldowns();
+}
+/** The alias currently bound to a conversation, or null. */
+export function codexStickyAliasFor(key) {
+    return key ? codexSticky.get(key) ?? null : null;
+}
+function bindCodexSticky(key, alias) {
+    if (codexSticky.size >= CODEX_STICKY_MAX && !codexSticky.has(key)) {
+        // Oldest-first eviction: Map preserves insertion order, so the first key is
+        // the least recently bound. Losing a binding costs one cache miss, never
+        // correctness, so a cheap sweep beats an LRU.
+        const oldest = codexSticky.keys().next().value;
+        if (oldest !== undefined)
+            codexSticky.delete(oldest);
+    }
+    codexSticky.set(key, alias);
+}
+/**
+ * Move a conversation onto `alias`, the codex mirror of pool.rebindSticky.
+ *
+ * Selection binds a conversation to the seat it picked; mid-request failover
+ * then moves it, and without this the binding still names the seat that just
+ * declined — the next turn would read a stale binding, find it cooling, and
+ * re-pick from scratch. A null key is accepted so the caller does not have to
+ * guard: a request with no hashable first user message has no conversation to
+ * bind.
+ */
+export function rebindCodexSticky(key, alias) {
+    if (!key)
+        return;
+    bindCodexSticky(key, alias);
+}
+/**
+ * Choose a ChatGPT seat for this request.
+ *
+ * Order, most specific first:
+ *   1. an explicitly named alias (`x-dario-account`, DARIO_CODEX_ACCOUNT) — a
+ *      pin is an instruction, so it is honoured even while cooling; the caller
+ *      asked for that seat and gets its answer, 429 included.
+ *   2. the seat this conversation is already bound to, unless it is cooling.
+ *   3. the first seat alphabetically that is not cooling — deterministic, so a
+ *      given conversation lands on the same seat across a restart and keeps its
+ *      prompt cache.
+ *   4. null when every seat is cooling. The caller answers from that rather
+ *      than spending a request that can only 429 again.
+ */
+export async function selectCodexAccount(preferredAlias, opts) {
     const alias = preferredAlias || process.env.DARIO_CODEX_ACCOUNT;
     if (alias) {
         const one = await loadCodexAccount(alias);
@@ -308,7 +407,83 @@ export async function selectCodexAccount(preferredAlias) {
     const all = await loadAllCodexAccounts();
     if (all.length === 0)
         return null;
-    return [...all].sort((a, b) => a.alias.localeCompare(b.alias))[0];
+    const byAlias = [...all].sort((a, b) => a.alias.localeCompare(b.alias));
+    const key = opts?.stickyKey ?? null;
+    if (key) {
+        const bound = codexSticky.get(key);
+        if (bound && !codexCooldowns.isCooled(bound)) {
+            const hit = byAlias.find((c) => c.alias === bound);
+            // A binding to a seat that has since been removed falls through to a
+            // fresh pick rather than failing the request.
+            if (hit)
+                return hit;
+            codexSticky.delete(key);
+        }
+    }
+    const free = byAlias.find((c) => !codexCooldowns.isCooled(c.alias));
+    if (!free)
+        return null;
+    if (key)
+        bindCodexSticky(key, free.alias);
+    return free;
+}
+/**
+ * The next askable seat that this request has NOT already tried.
+ *
+ * Mid-flight failover: a seat that 429s during a request hands the SAME
+ * request to a peer rather than failing it. Without this the pool only helps
+ * the request AFTER the one that discovered the limit — the discovering
+ * request still failed, every time a window rolled over.
+ *
+ * `tried` is per-request, so a seat already attempted here is never revisited
+ * inside the same request even if its cool-down has not landed yet. That is
+ * the codex mirror of the Claude pool's selectExcluding, and it is what makes
+ * the loop terminate: every pass adds a seat, so it is bounded by pool size.
+ *
+ * Stickiness is deliberately NOT consulted. The bound seat is the one that
+ * just declined; re-offering it would loop, and a conversation whose seat has
+ * gone away is better served elsewhere than not at all.
+ */
+export async function selectCodexAccountExcluding(tried) {
+    const all = await loadAllCodexAccounts();
+    if (all.length === 0)
+        return null;
+    return [...all]
+        .sort((a, b) => a.alias.localeCompare(b.alias))
+        .find((c) => !tried.has(c.alias) && !codexCooldowns.isCooled(c.alias)) ?? null;
+}
+/** Every seat is cooling — the fail-fast condition, for the caller's message. */
+/**
+ * Are ALL of these aliases cooling, right now?
+ *
+ * Synchronous on purpose. The provider-wide cool-down is written from this
+ * answer, and an `await` between deciding and writing is a window another
+ * in-flight request can use: the last-limited-seat request observes every seat
+ * cooling, a peer then succeeds on a just-recovered seat and calls
+ * clearCodexDecline, and the delayed continuation re-cools the whole provider
+ * against a pool that is healthy again. canAttempt('codex') then short-circuits
+ * and the healthy seat is skipped until the stale window expires — the exact
+ * single-seat outage this pool exists to prevent, reintroduced by the
+ * bookkeeping meant to prevent it.
+ *
+ * Re-checking inside the continuation narrows that window; it does not close
+ * it, because the re-check is itself another await. Taking the alias list first
+ * and then deciding-and-writing with no suspension point between them closes it
+ * outright: JS runs that callback as one unit, so nothing can interleave.
+ *
+ * The alias list may be a tick stale, which is harmless — a seat added in that
+ * window is not cooling, so "all cooled" is false on the next decline anyway.
+ */
+export function allAliasesCooled(aliases) {
+    return aliases.length > 0 && aliases.every((a) => codexCooldowns.isCooled(a));
+}
+export async function allCodexAccountsCooled() {
+    return allAliasesCooled(await listCodexAccountAliases());
+}
+/** Longest remaining cool-down across every seat, for a `retry-after`. */
+export async function codexPoolRetryAfterMs() {
+    const aliases = await listCodexAccountAliases();
+    return aliases.reduce((max, a) => Math.max(max, codexCooldowns.remainingMs(a)), 0);
 }
 /**
  * Parse whatever the user pastes back after authorizing.