@askalf/dario 5.5.90 → 6.0.1

package/README.md

@@ -18,7 +18,7 @@
 
 <p><strong>One local endpoint. Every AI tool you own. The subscription 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 · ~28k 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 · ~29k lines you can read in a weekend · independent, unofficial, third-party (<a href="DISCLAIMER.md">DISCLAIMER.md</a>)</sub>
 
 <sub>Part of <a href="#own-your-stack"><strong>Own Your Stack</strong></a> — 12 open tools for owning your AI infra: <a href="https://github.com/askalf/truecopy">truecopy</a> · <a href="https://github.com/askalf/strongroom">strongroom</a> · <a href="https://github.com/askalf/fieldpass">fieldpass</a> · <a href="https://github.com/askalf/plumbline">plumbline</a> · <a href="#own-your-stack">full family ↓</a></sub>
 
@@ -133,32 +133,85 @@ The tool doesn't know. The backend doesn't know. dario is the seam.
 
 ## ChatGPT subscription accounts (Codex engine)
 
-Your ChatGPT Plus/Pro plan, served on dario's OpenAI-compatible endpoint — so any client or harness that speaks `/v1/chat/completions` can use it: Codex CLI, OpenClaw-style clients, the OpenAI SDKs, your own scripts.
+Your ChatGPT Plus/Pro plan, served on **both** of dario's endpoints — so any client that speaks `/v1/chat/completions` can use it (Codex CLI, the OpenAI SDKs, your own scripts), and so can any client that speaks `/v1/messages` (Claude Code, the Anthropic SDKs, agent runtimes). The harness does not need to know which subscription is behind it.
 
 ```bash
-dario codex add work        # prints an authorize URL; paste the redirect URL back
+dario add altman            # prints an authorize URL; paste the redirect URL back
 dario codex list
-dario codex remove work
+dario codex remove altman
 ```
 
+`dario add altman` names whose plan you are attaching; `dario add amodei` attaches a Claude account instead. `dario codex add <name>` is the same command and still works.
+
 The browser lands on a `localhost` page that doesn't load — that's expected, nothing is listening there. Copy the whole address bar and paste it at the prompt; dario reads the code out of it. A bare code (or `code#state`) works too.
 
-Once an account is stored, an OpenAI-shape request naming a model that account may use is served from the subscription:
+Once an account is stored, a request naming a model that account may use is served from the subscription — on either endpoint:
 
 ```bash
 curl localhost:3456/v1/models | jq -r '.data[].id'
 curl localhost:3456/v1/chat/completions -H 'content-type: application/json' \
   -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"hi"}]}'
+
+# same subscription, Anthropic wire shape — this is what Claude Code speaks
+curl localhost:3456/v1/messages -H 'content-type: application/json' \
+  -d '{"model":"gpt-5.5","max_tokens":64,"messages":[{"role":"user","content":"hi"}]}'
 ```
 
 **Model names are discovered, not hardcoded.** The set a ChatGPT subscription may use is per-account and moves; dario asks the backend which models this account lists, caches the answer, and advertises them on `GET /v1/models` so a client's model picker finds them. Anything not on that list — `gpt-4o` and friends — is untouched and still routes to a configured API-key backend as before. `codex:<model>` / `chatgpt:<model>` forces the route explicitly.
 
-Streaming, tool calls, and tool-result round trips work: dario translates chat/completions to the Responses API the subscription backend speaks, and translates the stream back to `chat.completion.chunk`. Inbound is chat/completions only — there is no `/v1/responses` inbound yet.
+Streaming, tool calls, and tool-result round trips work on both shapes: dario translates chat/completions **or** Messages into the Responses API the subscription backend speaks, and translates the stream back into `chat.completion.chunk` or Anthropic message events to match what the client asked in. There is no `/v1/responses` inbound yet.
 
 Codex accounts live in `~/.dario/codex-accounts/`, entirely separate from the Claude pool. Nothing about `dario login`, `dario accounts`, or Claude routing changes.
 
 ---
 
+## Failover between subscriptions
+
+Two consumer plans, no API keys, and neither one able to take you down on its own.
+
+```bash
+dario proxy --pool-fallback=gpt-5.6-sol,claude-sonnet-5
+```
+
+That is a **chain**, read left to right, and each provider takes the first entry it can actually serve. When the Claude pool is drained or cooling, the request is served as `gpt-5.6-sol` from your ChatGPT subscription. When the subscription is rate-limited or down, the request is handed back to the Claude pool as `claude-sonnet-5`. Every substituted response carries `x-dario-pool-fallback: <model>` — a silently swapped model family is exactly the surprise this project exists to avoid.
+
+A single-entry chain is one-way and means what it always meant, so an existing config is unaffected. Failover is entirely opt-in: without `--pool-fallback`, a drained pool still returns its honest 429/503.
+
+The Claude entry must be a real `claude-*` model id. "Not a GPT model" is not the same as "the pool can serve it", and swapping in a typo would trade a recoverable 429 for an unrecoverable 404 — so an entry that doesn't look like an Anthropic model is ignored and the error surfaces honestly.
+
+Only a **429 or 5xx** fails over. A 400 surfaces to you, because a bad request that fails over just reproduces itself on the other provider and buries the real cause.
+
+`dario doctor` tells you which of these you are actually in:
+
+```
+[ OK ]  Failover   symmetric: gpt-5.6-sol → claude-sonnet-5, across 1 Codex account
+[WARN]  Failover   armed (gpt-5.6-sol) but INERT — no Codex account and no backend
+                   to fall back to. Add one: `dario add altman`
+```
+
+That warning is the whole reason the check exists. Armed with nothing to fall back to is green on every other check and incapable of doing anything.
+
+---
+
+## Shadow compare
+
+Once either subscription can serve either wire shape, the interesting question stops being *can I reach GPT* and becomes *which of these is better at my work*. Benchmarks answer that badly. Your own traffic answers it well.
+
+```bash
+curl localhost:3456/v1/messages \
+  -H 'content-type: application/json' \
+  -H 'x-dario-compare: gpt-5.6-sol' \
+  -d '{"model":"claude-opus-4-8","max_tokens":1024,"messages":[…]}'
+```
+
+You get the Claude answer, exactly as you would have. Beside it, dario runs the same prompt past `gpt-5.6-sol` and writes both to `~/.dario/compare/<timestamp>-<model>.json`, in your own wire shape so you are comparing like with like rather than eyeballing across two formats.
+
+The comparison cannot degrade the request it observes: it only reads bytes already on their way out, your request is never held open for it, and a comparison that fails, times out, or has nowhere to go is dropped with the record still written. Both sides are stored as raw payloads — extracting text is where a bug would quietly make two answers look more alike than they are.
+
+Compares run against a Codex account. Comparing against the Claude pool would occupy a seat for a request nobody is waiting on.
+
+---
+
 ## Multi-account pool
 
 **In v5 every dario is a pool** — a plain `dario login` is a pool of one, no separate mode to switch on. One Claude subscription has a ceiling; hold more than one seat — a personal Max and a work Max, a couple of Pros, team seats — and the same `localhost:3456` routes every request to whichever seat has the most headroom, live, per request. A single `dario accounts add` even bootstraps a servable proxy with no `dario login` step:
@@ -250,7 +303,7 @@ The split isn't live, but it was announced once on short notice and could return
 
 | Signal | Status |
 |---|---|
-| Source | **~25k** lines of TypeScript across **53** files — auditable in a weekend (v5 removed shim; the pool is the one code path) |
+| Source | **~29k** lines of TypeScript across **58** files — auditable in a weekend (v5 removed shim; the pool is the one code path) |
 | Dependencies | **0 runtime.** Verify: `npm ls --production` |
 | Provenance | Every release [SLSA-attested](https://www.npmjs.com/package/@askalf/dario) via GitHub Actions + Sigstore |
 | Scanning | [CodeQL](https://github.com/askalf/dario/actions/workflows/codeql.yml) on every push and weekly |
@@ -303,7 +356,7 @@ Ongoing discussion, including other users' experiences: [#724](https://github.co
 
 ## Commands
 
-`dario` (TUI) · `login` · `proxy` · `doctor` · `accounts {list,add,remove}` · `backend {list,add,remove}` · `codex {list,add,remove}` · `mcp` · `subagent {install,status,remove}` · `usage` · `config` · `upgrade` · `status` · `refresh` · `resume` · `logout` · `help`
+`dario` (TUI) · `login` · `proxy` · `doctor` · `add {altman,amodei}` · `accounts {list,add,remove}` · `backend {list,add,remove}` · `codex {list,add,remove}` · `mcp` · `subagent {install,status,remove}` · `usage` · `config` · `upgrade` · `status` · `refresh` · `resume` · `logout` · `help`
 
 Per-flag reference: [`docs/commands.md`](./docs/commands.md) · env vars grouped by task, for Docker / k8s / systemd: [`docs/configuration.md`](./docs/configuration.md) · SDK examples + per-tool setup: [`docs/usage.md`](./docs/usage.md)
 

package/dist/analytics.d.ts

@@ -63,6 +63,8 @@ export declare function billingBucketFromClaim(claim: string | null | undefined)
  * non-subscription billing classification or the `unknown` sentinel below.
  */
 export declare const SUBSCRIPTION_CLAIMS: ReadonlySet<string>;
+/** The claim the proxy stamps on codex-engine requests (see above). */
+export declare const CODEX_CLAIM = "chatgpt_subscription";
 /**
  * One-line per-request usage summary for verbose (-v / -vv) logs.
  *

package/dist/analytics.js

@@ -35,6 +35,7 @@ export function billingBucketFromClaim(claim) {
         // (30-min cooldown loops) exactly when the weekly window tightens.
         case 'five_hour_overage_included':
         case 'seven_day_overage_included':
+        case 'chatgpt_subscription':
             return 'subscription';
         case 'five_hour_fallback':
         case 'seven_day_fallback':
@@ -61,7 +62,15 @@ export const SUBSCRIPTION_CLAIMS = new Set([
     'seven_day_fallback',
     'five_hour_overage_included',
     'seven_day_overage_included',
+    // The codex engine: a request served from a ChatGPT-subscription account
+    // (dario#1009). There is no Anthropic claim header on that path; the proxy
+    // stamps this one. It is subscription billing — the user's ChatGPT plan —
+    // so it must be recognised here, or the overage guard reads it as
+    // pay-as-you-go and halts the proxy after the first GPT request.
+    'chatgpt_subscription',
 ]);
+/** The claim the proxy stamps on codex-engine requests (see above). */
+export const CODEX_CLAIM = 'chatgpt_subscription';
 /**
  * One-line per-request usage summary for verbose (-v / -vv) logs.
  *

package/dist/cli.js

@@ -534,11 +534,12 @@ async function proxy() {
     // DARIO_PASSTHROUGH_BETAS env var.
     const passthroughBetas = parsePassthroughBetasFlag(args, process.env['DARIO_PASSTHROUGH_BETAS']);
     // --pool-fallback=<model> / DARIO_POOL_FALLBACK / config poolFallback.model
-    // — strictly opt-in. When the Claude pool can't serve, OpenAI-shape
-    // requests are re-pointed at the configured openai-compat backend as
-    // <model> (response marked x-dario-pool-fallback) instead of surfacing
-    // the 429/503. `--pool-fallback=` (empty value) disables, overriding
-    // env + config — same clear-the-default shape as --passthrough-betas=.
+    // — strictly opt-in. When the Claude pool can't serve, the request is
+    // re-pointed at whichever provider can serve <model> (response marked
+    // x-dario-pool-fallback) instead of surfacing the 429/503: a stored Codex
+    // account when it lists <model>, otherwise the openai-compat backend.
+    // `--pool-fallback=` (empty value) disables, overriding env + config —
+    // same clear-the-default shape as --passthrough-betas=.
     const poolFallbackFromFlag = args.find((a) => a.startsWith('--pool-fallback='))?.split('=').slice(1).join('=');
     const poolFallbackModel = (poolFallbackFromFlag
         ?? process.env['DARIO_POOL_FALLBACK']
@@ -1310,6 +1311,9 @@ async function help() {
     dario codex add NAME     Add a ChatGPT-subscription account (prints an
                              authorize URL; paste the redirect URL back).
     dario codex remove NAME  Remove a ChatGPT-subscription account.
+    dario add altman [NAME]  Attach a ChatGPT subscription — the same thing
+                             as 'dario codex add', named by whose plan it is.
+                             'dario add amodei' attaches a Claude account.
     dario backend list       List configured OpenAI-compat backends
     dario backend add NAME --key=sk-... [--base-url=...]
                              Add an OpenAI-compat backend (OpenAI, OpenRouter, Groq, etc.)
@@ -1558,14 +1562,14 @@ async function help() {
                              Sticky bindings are unaffected.
                              Env: DARIO_POOL_STRATEGY.
     --pool-fallback=<model>  When every pool seat is drained or cooling,
-                             forward OpenAI-shape requests to the
-                             configured openai-compat backend as <model>
-                             instead of surfacing the 429/503. Response
-                             carries x-dario-pool-fallback. Anthropic-
-                             shape requests keep the error (no reverse
-                             response translation). Requires an
-                             openai-compat backend. Empty value disables.
-                             Env: DARIO_POOL_FALLBACK. Config:
+                             serve the request as <model> from whichever
+                             provider can, instead of surfacing the
+                             429/503: a Codex/ChatGPT subscription that
+                             lists <model> (both wire shapes), else the
+                             openai-compat backend (OpenAI shape only).
+                             Response carries x-dario-pool-fallback.
+                             Needs one of those configured. Empty value
+                             disables. Env: DARIO_POOL_FALLBACK. Config:
                              poolFallback.model.
     --model-alias=<name=target>
                              User-defined model alias, repeatable.
@@ -2228,6 +2232,55 @@ function pkgVersion() {
         return 'unknown';
     }
 }
+/**
+ * `dario add <who> [NAME]` — one verb for "give dario another subscription to
+ * draw on", added in v6.0.0.
+ *
+ * This is the command dario#1009 actually asked for. Until now the answer was
+ * "run `dario codex add` instead", which is a worse answer than it looks: by
+ * v6.0.0 a Codex account is no longer a niche OpenAI-path add-on but one of two
+ * symmetric subscriptions either of which can carry the whole deployment, and
+ * the command surface should say so. `add` names WHOSE plan you are attaching,
+ * which is the distinction that actually matters to someone holding two
+ * consumer subscriptions and no API keys.
+ *
+ * It dispatches to the existing implementations rather than duplicating them —
+ * there is exactly one add-a-Codex-account code path, and this is a second door
+ * into it. `dario codex add` keeps working unchanged and undeprecated.
+ *
+ * The name defaults to the vendor word, so the bare `dario add altman` from the
+ * issue works end to end instead of erroring on a missing alias.
+ */
+async function add() {
+    const who = (args[1] ?? '').toLowerCase();
+    const CODEX = new Set(['altman', 'chatgpt', 'openai', 'codex', 'gpt']);
+    const CLAUDE = new Set(['amodei', 'claude', 'anthropic']);
+    if (CODEX.has(who)) {
+        // Reshape argv into the `codex add [NAME]` form and reuse that one path.
+        args[2] = args[2] ?? who;
+        args[1] = 'add';
+        return codex();
+    }
+    if (CLAUDE.has(who)) {
+        if (args[2]) {
+            console.error('');
+            console.error(`  Claude accounts are named during login, not on the command line.`);
+            console.error(`  Run \`dario add ${who}\` and follow the browser flow.`);
+            console.error('');
+            process.exit(1);
+        }
+        return login();
+    }
+    console.error('');
+    console.error(who ? `  Unknown provider: ${who}` : '  Usage: dario add <provider> [NAME]');
+    console.error('');
+    console.error('    dario add altman [NAME]   a ChatGPT subscription (Codex backend)');
+    console.error('    dario add amodei          a Claude subscription (adds a pool seat)');
+    console.error('');
+    console.error('  Aliases: altman = chatgpt/openai/codex/gpt, amodei = claude/anthropic.');
+    console.error('');
+    process.exit(1);
+}
 // Main
 const commands = {
     login,
@@ -2237,6 +2290,7 @@ const commands = {
     resume,
     logout,
     accounts,
+    add,
     codex,
     backend,
     shim,

package/dist/codex-backend.d.ts

@@ -46,6 +46,22 @@ export declare function fetchCodexModels(creds: CodexAccountCredentials, fetchIm
  * "route nothing here by name". An explicit `codex:`/`chatgpt:` prefix still
  * routes, so discovery being down never makes the engine unusable.
  */
+/** What the proxy learns from one forwarded codex request — enough for an
+ *  analytics row and a log line. Reported once per request, on every exit
+ *  that answered the client; a DECLINE (deferred to the Claude pool) reports
+ *  nothing, since the Claude path records what it then serves. */
+export interface CodexForwardOutcome {
+    status: number;
+    latencyMs: number;
+    inputTokens: number;
+    outputTokens: number;
+    stream: boolean;
+    model: string;
+    alias: string;
+}
+/** The cached slug list for an alias WITHOUT fetching. For the admin surface:
+ *  a status read must never cost an upstream call or a token refresh. */
+export declare function peekCodexModelSlugs(alias: string): readonly string[] | null;
 export declare function getCodexModelSlugs(creds: CodexAccountCredentials, fetchImpl?: typeof fetch): Promise<readonly string[]>;
 /**
  * Whether a request naming `model` should be served from the subscription: the
@@ -56,6 +72,20 @@ export declare function getCodexModelSlugs(creds: CodexAccountCredentials, fetch
  * configured API-key backend.
  */
 export declare function isCodexModel(model: string, slugs: readonly string[]): boolean;
+/**
+ * A pool-fallback value may name a CHAIN — `gpt-5.6-sol,claude-sonnet-5` — and
+ * each provider takes the first entry it can actually serve. These two pickers
+ * are the whole selection rule, kept pure so it is testable without a socket.
+ *
+ * Reading the chain from both ends is what makes failover SYMMETRIC in v6.0.0:
+ * `pickCodexFallback` catches a drained Claude pool, `pickClaudeFallback`
+ * catches a ChatGPT subscription that is rate-limited or down. Neither
+ * subscription hitting its ceiling can take the whole deployment dark on its
+ * own. A single-entry chain keeps the pre-6.0 meaning exactly, so configs
+ * written before this release behave identically.
+ */
+export declare function pickCodexFallback(models: readonly string[], slugs: readonly string[]): string | null;
+export declare function pickClaudeFallback(models: readonly string[], slugs: readonly string[]): string | null;
 /**
  * Pull `chatgpt_account_id` out of the id_token's `https://api.openai.com/auth`
  * claim. Payload only — this is reading our own token for a routing header, not
@@ -111,6 +141,14 @@ export declare function createResponsesTranslator(model: string): {
     chunk(line: string): string | null;
     /** True when the upstream stream terminated as a FAILURE. */
     didFail(): boolean;
+    /** Token usage from the terminal event, or null if none arrived. Read by
+     *  the proxy to record the request in analytics — before this, codex
+     *  requests were invisible to /analytics and the request log entirely. */
+    usage(): {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    } | null;
     /** Everything seen so far, as one non-streaming chat.completion body. */
     complete(): Record<string, unknown>;
 };
@@ -153,8 +191,16 @@ export declare function buildCodexHeaders(creds: CodexAccountCredentials): Recor
  * shapes. For the Anthropic shape the non-streaming body is rebuilt from the
  * `response` object carried by the terminal `response.completed` event.
  *
+ * Returns TRUE when it answered the client. With `deferOnUnavailable` it may
+ * instead return FALSE having written NOTHING — that is the subscription
+ * saying "not right now" (429, a 5xx, or a transport failure that never got a
+ * status at all) so the caller can fail over to another provider rather than
+ * pass a rate limit or an outage through to the client. It only ever declines
+ * before any byte is written, so a stream in flight is never abandoned
+ * half-sent.
+ *
  * `fetchImpl` is injectable so the translation and header construction are
  * testable without network (test/codex-backend.mjs), matching the pattern
  * test/codex-oauth.mjs already uses.
  */
-export declare function forwardToCodex(req: IncomingMessage, res: ServerResponse, body: Buffer, creds: CodexAccountCredentials, corsOrigin: string, securityHeaders: Record<string, string>, upstreamTimeoutMs: number, verbose: boolean, shape?: CodexRequestShape, fetchImpl?: typeof fetch): Promise<void>;
+export declare function forwardToCodex(req: IncomingMessage, res: ServerResponse, body: Buffer, creds: CodexAccountCredentials, corsOrigin: string, securityHeaders: Record<string, string>, upstreamTimeoutMs: number, verbose: boolean, shape?: CodexRequestShape, fetchImpl?: typeof fetch, deferOnUnavailable?: boolean, onDone?: (outcome: CodexForwardOutcome) => void): Promise<boolean>;

package/dist/codex-backend.js

@@ -59,12 +59,12 @@ export async function fetchCodexModels(creds, fetchImpl = fetch) {
     }
     return slugs;
 }
-/**
- * Cached {@link fetchCodexModels}, keyed by account alias. Never throws — an
- * unreachable backend yields the last known set, or an empty one, which means
- * "route nothing here by name". An explicit `codex:`/`chatgpt:` prefix still
- * routes, so discovery being down never makes the engine unusable.
- */
+/** The cached slug list for an alias WITHOUT fetching. For the admin surface:
+ *  a status read must never cost an upstream call or a token refresh. */
+export function peekCodexModelSlugs(alias) {
+    const hit = modelCache.get(alias);
+    return hit ? hit.slugs : null;
+}
 export async function getCodexModelSlugs(creds, fetchImpl = fetch) {
     const hit = modelCache.get(creds.alias);
     if (hit && Date.now() - hit.fetchedAt < hit.ttlMs)
@@ -94,6 +94,37 @@ export function isCodexModel(model, slugs) {
     const m = model.toLowerCase();
     return slugs.some(s => s.toLowerCase() === m);
 }
+/**
+ * A pool-fallback value may name a CHAIN — `gpt-5.6-sol,claude-sonnet-5` — and
+ * each provider takes the first entry it can actually serve. These two pickers
+ * are the whole selection rule, kept pure so it is testable without a socket.
+ *
+ * Reading the chain from both ends is what makes failover SYMMETRIC in v6.0.0:
+ * `pickCodexFallback` catches a drained Claude pool, `pickClaudeFallback`
+ * catches a ChatGPT subscription that is rate-limited or down. Neither
+ * subscription hitting its ceiling can take the whole deployment dark on its
+ * own. A single-entry chain keeps the pre-6.0 meaning exactly, so configs
+ * written before this release behave identically.
+ */
+export function pickCodexFallback(models, slugs) {
+    return models.find(m => isCodexModel(m, slugs)) ?? null;
+}
+export function pickClaudeFallback(models, slugs) {
+    // "Not a codex slug" is NOT the same as "the Claude pool can serve it". A
+    // typo, a retired model, or an entry meant for some third provider would all
+    // pass that test, and the request would be swapped to a model Anthropic 404s
+    // on — trading a recoverable 429 for an unrecoverable 404, which is strictly
+    // worse than not failing over at all.
+    //
+    // So require it to look like an Anthropic model. Every model the pool serves
+    // is `claude-*`; anything else means the chain has no Claude entry and the
+    // codex error surfaces honestly. Failing CLOSED is the right direction here.
+    //
+    // Known limitation: a `--model-alias` that resolves to a Claude model is not
+    // accepted, because aliases resolve later in the request path than this. Name
+    // the real model id in the chain.
+    return models.find(m => !isCodexModel(m, slugs) && /^claude/i.test(m)) ?? null;
+}
 /**
  * Pull `chatgpt_account_id` out of the id_token's `https://api.openai.com/auth`
  * claim. Payload only — this is reading our own token for a routing header, not
@@ -355,6 +386,12 @@ export function createResponsesTranslator(model) {
         didFail() {
             return failed;
         },
+        /** Token usage from the terminal event, or null if none arrived. Read by
+         *  the proxy to record the request in analytics — before this, codex
+         *  requests were invisible to /analytics and the request log entirely. */
+        usage() {
+            return usage;
+        },
         /** Everything seen so far, as one non-streaming chat.completion body. */
         complete() {
             const calls = [...toolCalls.values()].sort((a, b) => a.index - b.index);
@@ -438,13 +475,35 @@ export function buildCodexHeaders(creds) {
  * shapes. For the Anthropic shape the non-streaming body is rebuilt from the
  * `response` object carried by the terminal `response.completed` event.
  *
+ * Returns TRUE when it answered the client. With `deferOnUnavailable` it may
+ * instead return FALSE having written NOTHING — that is the subscription
+ * saying "not right now" (429, a 5xx, or a transport failure that never got a
+ * status at all) so the caller can fail over to another provider rather than
+ * pass a rate limit or an outage through to the client. It only ever declines
+ * before any byte is written, so a stream in flight is never abandoned
+ * half-sent.
+ *
  * `fetchImpl` is injectable so the translation and header construction are
  * testable without network (test/codex-backend.mjs), matching the pattern
  * test/codex-oauth.mjs already uses.
  */
-export async function forwardToCodex(req, res, body, creds, corsOrigin, securityHeaders, upstreamTimeoutMs, verbose, shape = 'openai', fetchImpl = fetch) {
+export async function forwardToCodex(req, res, body, creds, corsOrigin, securityHeaders, upstreamTimeoutMs, verbose, shape = 'openai', fetchImpl = fetch, deferOnUnavailable = false, onDone) {
     void req;
     const isAnthropic = shape === 'anthropic';
+    // Reported exactly once, on every exit that answered the client. Without
+    // this the proxy had no idea a codex request happened: no analytics row, no
+    // log line, no per-account count.
+    const startedAt = Date.now();
+    let reported = false;
+    const report = (status, usage, stream, model) => {
+        if (reported || !onDone)
+            return;
+        reported = true;
+        try {
+            onDone({ status, latencyMs: Date.now() - startedAt, inputTokens: usage?.input ?? 0, outputTokens: usage?.output ?? 0, stream, model, alias: creds.alias });
+        }
+        catch { /* a reporting failure must never break a served request */ }
+    };
     // An Anthropic-shape error body is {type,error{type,message}}; an OpenAI one
     // is {error}. A client SDK reads its own shape, so errors follow the request.
     const errBody = (message, extra = {}) => JSON.stringify(isAnthropic
@@ -457,7 +516,8 @@ export async function forwardToCodex(req, res, body, creds, corsOrigin, security
     catch {
         res.writeHead(400, { 'Content-Type': 'application/json', ...securityHeaders });
         res.end(errBody(`Codex backend requires a JSON ${isAnthropic ? 'messages' : 'chat/completions'} body`));
-        return;
+        report(400, null, false, '');
+        return true;
     }
     const clientWantsStream = parsed.stream === true;
     const model = String(parsed.model ?? '');
@@ -482,9 +542,19 @@ export async function forwardToCodex(req, res, body, creds, corsOrigin, security
             const detail = await upstream.text().catch(() => '');
             if (verbose)
                 console.error(`[dario] codex backend ${upstream.status}: ${detail.slice(0, 300)}`);
+            // "Not right now" — a rate limit or an upstream fault — is the caller's
+            // cue to fail over, not something to hand the client. A 4xx that is our
+            // own fault (a bad body, an unsupported parameter) is NOT: failing over
+            // would just reproduce it somewhere else and hide the real error.
+            const unavailable = upstream.status === 429 || upstream.status >= 500;
+            if (deferOnUnavailable && unavailable) {
+                console.log(`[dario] codex account ${creds.alias} unavailable (${upstream.status}) — deferring to the next provider`);
+                return false;
+            }
             res.writeHead(upstream.status, { 'Content-Type': 'application/json', ...securityHeaders });
             res.end(errBody('Upstream Codex backend error', { status: upstream.status, account: creds.alias }));
-            return;
+            report(upstream.status, null, clientWantsStream, model);
+            return true;
         }
         // OpenAI shape: one stateful line-in/line-out translator (unchanged).
         // Anthropic shape: parse the typed Responses event stream, then map events
@@ -577,7 +647,8 @@ export async function forwardToCodex(req, res, body, creds, corsOrigin, security
                 console.error(`[dario] codex backend (${creds.alias}) response failed: ${detail}`);
             res.writeHead(502, { 'Content-Type': 'application/json', ...securityHeaders });
             res.end(errBody(`Codex backend response failed: ${detail}`, { account: creds.alias }));
-            return;
+            report(502, null, clientWantsStream, model);
+            return true;
         }
         if (isAnthropic) {
             if (clientWantsStream) {
@@ -606,6 +677,17 @@ export async function forwardToCodex(req, res, body, creds, corsOrigin, security
             });
             res.end(JSON.stringify(translator.complete()));
         }
+        // Token usage rides the terminal Responses event on either shape. A stream
+        // that failed upstream still ended as 200 on the wire (the client saw the
+        // failure event); analytics must count it as the 502 it was.
+        {
+            const tr = terminalResponse;
+            const usage = isAnthropic
+                ? (tr?.usage ? { input: Number(tr.usage.input_tokens ?? 0), output: Number(tr.usage.output_tokens ?? 0) } : null)
+                : (() => { const u = translator.usage(); return u ? { input: u.prompt_tokens, output: u.completion_tokens } : null; })();
+            report(upstreamFailed ? 502 : 200, usage, clientWantsStream, model);
+        }
+        return true;
     }
     catch (err) {
         // Detail stays server-side (CodeQL js/stack-trace-exposure), same as
@@ -613,6 +695,19 @@ export async function forwardToCodex(req, res, body, creds, corsOrigin, security
         const detail = err instanceof Error ? err.message : String(err);
         if (verbose)
             console.error(`[dario] codex backend (${creds.alias}) error: ${detail}`);
+        // A transport failure before any byte was written is the same "not right
+        // now" as a 429: DNS, a refused connection, a reset socket or our own
+        // upstream timeout all mean this subscription did not answer, and none of
+        // them is the client's bad request. Deferring here is what makes failover
+        // cover the outage case rather than only the rate-limit case — without it
+        // a ChatGPT backend that is merely unreachable is terminal for the request
+        // even with an idle Claude pool beside it. The headersSent guard keeps the
+        // contract intact: once a stream is in flight it is far too late to hand
+        // the request to anyone else.
+        if (deferOnUnavailable && !res.headersSent) {
+            console.log(`[dario] codex account ${creds.alias} unreachable (${detail}) — deferring to the next provider`);
+            return false;
+        }
         if (!res.headersSent) {
             res.writeHead(502, { 'Content-Type': 'application/json', ...securityHeaders });
             res.end(errBody('Upstream Codex backend error', { account: creds.alias }));
@@ -623,6 +718,8 @@ export async function forwardToCodex(req, res, body, creds, corsOrigin, security
             }
             catch { /* already closed */ }
         }
+        report(502, null, false, '');
+        return true;
     }
     finally {
         clearTimeout(timeout);

package/dist/compare.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Shadow compare (v6.0.0) — run one prompt past a second model family and keep
+ * both answers, without the client ever knowing.
+ *
+ * WHY THIS SHAPE. Once dario can serve either wire shape from either
+ * subscription, the obvious question stops being "can I reach GPT" and becomes
+ * "which of these two is actually better at MY work". Answering that from
+ * benchmarks is close to worthless; answering it from your own real traffic is
+ * not. So a compare is triggered per-request by a header, on prompts you were
+ * sending anyway.
+ *
+ * THE CLIENT IS NEVER AFFECTED. The primary answer streams through untouched
+ * and the comparison runs beside it — the request is not held open for it, and
+ * a compare that fails, times out, or has nowhere to go is dropped silently
+ * with the record still written. A diagnostic that can degrade the thing it is
+ * measuring is worse than no diagnostic.
+ *
+ * BOTH SIDES ARE RECORDED IN THE CLIENT'S OWN WIRE SHAPE. The comparison is
+ * dispatched through the same forwardToCodex translation the real path uses, so
+ * an Anthropic-shape request yields two Anthropic-shape answers. Comparing a
+ * Messages response against a raw Responses payload would mean eyeballing
+ * across two formats and calling the difference a model difference.
+ *
+ * Raw payloads are stored rather than extracted text: extraction is exactly
+ * where a subtle bug would quietly make two answers look more alike than they
+ * are, and this release was written off the back of five failures that read as
+ * successes.
+ */
+import type { ServerResponse } from 'node:http';
+/** Request header that arms a comparison: `x-dario-compare: <model>`. */
+export declare const COMPARE_HEADER = "x-dario-compare";
+/**
+ * Response header naming the model a comparison was REQUESTED against.
+ *
+ * Deliberately not "compared-with". The header has to be set before the primary
+ * response starts streaming, which is strictly earlier than we can know whether
+ * the comparison ran — it may still be skipped for a missing account, an
+ * unlisted model, or an unparseable body. A header claiming a comparison
+ * happened would therefore sometimes be a lie, which is the exact failure this
+ * release exists to stamp out. The name now states only what is true at the
+ * moment it is written; whether it actually ran is in the record.
+ */
+export declare const COMPARE_RESULT_HEADER = "x-dario-compare-requested";
+export declare const COMPARE_DIR: string;
+export interface CompareSide {
+    status: number | null;
+    /** The response payload exactly as written — SSE text or a JSON body. */
+    body: string;
+    ms: number;
+}
+export interface CompareRecord {
+    ts: string;
+    path: string;
+    shape: 'openai' | 'anthropic';
+    streaming: boolean;
+    primaryModel: string;
+    comparedModel: string;
+    /** The client's request body, verbatim, so a record replays on its own. */
+    request: unknown;
+    primary: CompareSide;
+    compare: CompareSide | null;
+    /** Why there is no compare side, when there isn't one. */
+    skipped?: string;
+}
+/**
+ * Read the compare target from request headers. Returns null when unarmed, and
+ * for the empty value, so `-H 'x-dario-compare:'` reliably means "off" rather
+ * than "compare against a model named empty string".
+ */
+export declare function readCompareTarget(headers: Record<string, unknown>): string | null;
+/**
+ * Swap the model in a JSON request body. Returns null when the body is not
+ * JSON — the caller then skips the comparison rather than sending something it
+ * could not read.
+ */
+export declare function withModel(body: Buffer, model: string): Buffer | null;
+/**
+ * Tee everything written to a real response into a buffer, leaving delivery
+ * completely unchanged. `captured()` is meaningful once the response finishes.
+ */
+export declare function teeResponse(res: ServerResponse): {
+    captured: () => CompareSide;
+};
+/**
+ * Run the comparison against the ChatGPT subscription.
+ *
+ * Resolves to a reason-for-skipping string when it declines, never throwing:
+ * the caller is on the success path of a request it has already answered, and
+ * a diagnostic must not be able to take that down.
+ *
+ * v6.0.0 compares against a Codex account only. Comparing against the Claude
+ * pool would mean occupying a seat for a request nobody is waiting on, which is
+ * a trade worth making deliberately rather than by default.
+ */
+export declare function runCompare(opts: {
+    body: Buffer;
+    shape: 'openai' | 'anthropic';
+    targetModel: string;
+    corsOrigin: string;
+    timeoutMs: number;
+    verbose: boolean;
+}): Promise<{
+    side: CompareSide | null;
+    skipped?: string;
+}>;
+/**
+ * Persist one record. Returns the path written, or null on failure — a compare
+ * log that cannot be written is not worth failing a served request over.
+ */
+export declare function writeCompareRecord(record: CompareRecord, dir?: string): string | null;