@askalf/dario 5.5.89 → 6.0.0

package/dist/proxy.js

@@ -20,7 +20,8 @@ import { loadAllAccounts, loadAccount, saveAccount, refreshAccountToken, resyncL
 import { handleAdminRequest } from './admin-api.js';
 import { createTokenBucket } from './rate-limit.js';
 import { getOpenAIBackend, isOpenAIModel, forwardToOpenAI } from './openai-backend.js';
-import { forwardToCodex, getCodexModelSlugs, CODEX_BACKEND_BASE_URL } from './codex-backend.js';
+import { forwardToCodex, getCodexModelSlugs, pickCodexFallback, pickClaudeFallback, CODEX_BACKEND_BASE_URL } from './codex-backend.js';
+import { readCompareTarget, teeResponse, runCompare, writeCompareRecord, COMPARE_RESULT_HEADER } from './compare.js';
 import { listCodexAccountAliases, hasAnyCodexAccount, selectCodexAccount, getFreshCodexAccount } from './codex-accounts.js';
 import { route as routeProvider } from './provider-adapter.js';
 import { RequestQueue, QueueFullError, QueueTimeoutError, DEFAULT_MAX_CONCURRENT, DEFAULT_MAX_QUEUED, DEFAULT_QUEUE_TIMEOUT_MS } from './request-queue.js';
@@ -1234,20 +1235,40 @@ export async function startProxy(opts = {}) {
         console.log(`  Codex accounts: ${startupCodexAliases.join(', ')} → ${CODEX_BACKEND_BASE_URL}`);
     }
     // Pool-exhausted fallback (strictly opt-in). When the Claude pool can't
-    // serve — every seat rate-limited or in auth cool-down — OpenAI-shape
-    // requests (/v1/chat/completions) are re-pointed at the configured
-    // openai-compat backend with the model swapped to `poolFallbackModel`,
-    // instead of surfacing the 429/503. Anthropic-shape requests keep the
-    // error: dario has no OpenAI→Anthropic response translation, and
-    // half-translating would corrupt streaming clients. Every substituted
-    // response carries `x-dario-pool-fallback: <model>` — a silently swapped
-    // model is the kind of surprise this project exists to avoid.
-    const poolFallbackModel = (opts.poolFallbackModel ?? '').trim() || null;
-    if (poolFallbackModel && openaiBackend) {
-        console.log(`  Pool fallback: exhausted-pool /v1/chat/completions requests → ${openaiBackend.name} as ${poolFallbackModel} (marked x-dario-pool-fallback)`);
-    }
-    else if (poolFallbackModel && !openaiBackend) {
-        console.warn('[dario] --pool-fallback is set but no OpenAI-compat backend is configured (`dario backend add …`) — fallback is inert.');
+    // serve — every seat rate-limited or in auth cool-down — the request is
+    // re-pointed at whichever provider can serve `poolFallbackModel` instead
+    // of surfacing the 429/503:
+    //
+    //   • a stored Codex/ChatGPT subscription that LISTS that model, on
+    //     EITHER wire shape. This is the v6.0.0 change and the one that
+    //     matters for a deployment whose providers are both subscriptions:
+    //     failover now costs nothing per token, needs no API key, and covers
+    //     Anthropic-shape clients (Claude Code, agent runtimes) that used to
+    //     have nowhere to go and simply went dark when the pool filled.
+    //   • otherwise the openai-compat backend, OpenAI shape only — that route
+    //     still has no Messages translation.
+    //
+    // Every substituted response carries `x-dario-pool-fallback: <model>` — a
+    // silently swapped model is the kind of surprise this project exists to
+    // avoid.
+    // The value may name a chain — see pickCodexFallback/pickClaudeFallback.
+    // `poolFallbackModel` stays the FIRST entry so every pre-6.0 reference and
+    // every single-value config keeps its exact previous meaning.
+    const poolFallbackModels = ((opts.poolFallbackModel ?? '').trim() || '')
+        .split(',').map((m) => m.trim()).filter(Boolean);
+    const poolFallbackModel = poolFallbackModels[0] ?? null;
+    if (poolFallbackModel) {
+        const targets = [];
+        if (startupCodexAliases.length > 0)
+            targets.push(`codex subscription (${startupCodexAliases.join(', ')}) — both wire shapes`);
+        if (openaiBackend)
+            targets.push(`${openaiBackend.name} — OpenAI shape only`);
+        if (targets.length > 0) {
+            console.log(`  Pool fallback: exhausted-pool requests → ${targets.join(', then ')} as ${poolFallbackModel} (marked x-dario-pool-fallback)`);
+        }
+        else {
+            console.warn('[dario] --pool-fallback is set but there is nothing to fall back TO — add a Codex account (`dario codex add …`) or an OpenAI-compat backend (`dario backend add …`). Fallback is inert.');
+        }
     }
     // User-defined model aliases (see parseModelAliasSpecs). Resolved by the
     // CLI (config < env < flags, per-key) and applied per request before
@@ -1787,6 +1808,58 @@ export async function startProxy(opts = {}) {
     function checkAuth(req) {
         return authenticateRequest(req.headers, apiKeyBuf);
     }
+    /**
+     * Serve a pool-exhausted request from the ChatGPT subscription (v6.0.0).
+     *
+     * Returns true when it answered, false when it declined — declining is
+     * silent so the caller can fall through to the api-key backend and then to
+     * the honest 429/503. It never manufactures a reason to fire: no codex
+     * account, an unreadable one, or a `poolFallbackModel` that account does not
+     * list all mean "not mine to serve".
+     *
+     * Works for BOTH wire shapes, which is the point: forge's agents and Claude
+     * Code speak Anthropic, and before v5.5.87 they had nowhere to fail over to
+     * and simply went dark when the Claude pool filled. The substituted model is
+     * announced on `x-dario-pool-fallback` exactly as the api-key path does —
+     * a silently swapped model family is precisely the surprise this project
+     * exists to avoid.
+     */
+    const tryCodexPoolFallback = async (req, res, body, fallbackModels, shape, why) => {
+        if (fallbackModels.length === 0)
+            return false;
+        if (!(await hasAnyCodexAccount().catch(() => false)))
+            return false;
+        const stored = await selectCodexAccount().catch(() => null);
+        if (!stored)
+            return false;
+        let creds;
+        try {
+            creds = await getFreshCodexAccount(stored);
+        }
+        catch {
+            return false;
+        }
+        const slugs = await getCodexModelSlugs(creds).catch(() => []);
+        const fallbackModel = pickCodexFallback(fallbackModels, slugs);
+        if (!fallbackModel)
+            return false;
+        const fallbackBody = buildPoolFallbackBody(body, fallbackModel);
+        if (!fallbackBody)
+            return false;
+        console.log(`[dario] #${requestCount} ${why} → codex account ${creds.alias} as ${fallbackModel}`);
+        requestCount++;
+        // 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.
+        //
+        // With NO next option, 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';
+        return await forwardToCodex(req, res, fallbackBody, creds, corsOrigin, { ...SECURITY_HEADERS, 'x-dario-pool-fallback': fallbackModel }, upstreamTimeoutMs, verbose, shape, fetch, hasNextOption);
+    };
     const server = createServer(async (req, res) => {
         if (req.method === 'OPTIONS') {
             res.writeHead(204, CORS_HEADERS);
@@ -2305,6 +2378,29 @@ export async function startProxy(opts = {}) {
              * null without answering in the pool-exhausted-fallback case, which the
              * fallback dispatch right below picks up.
              */
+            // The pool-unavailable 503, in one place. Two distinct empty-selection
+            // cases (#599): the pool has no accounts at all (headless admin
+            // bootstrap — nothing added yet), vs. it has accounts but all are
+            // rate-limited / in auth cool-down. Each gets a truthful, actionable
+            // message so a headless operator isn't told "rate-limited" when they
+            // simply haven't added an account.
+            //
+            // Shared because two callers must agree: the selector, and the dispatch
+            // below for a request the selector DEFERRED but no provider could serve.
+            const writePoolUnavailable = () => {
+                res.writeHead(503, JSON_HEADERS);
+                res.end(JSON.stringify(pool.size === 0
+                    ? {
+                        error: 'No account configured',
+                        message: adminEnabled
+                            ? 'dario is running in admin mode with no account yet. Add one via POST /admin/login/start, then retry.'
+                            : 'No accounts available. Run `dario login`, or add accounts with `dario accounts add`.',
+                    }
+                    : {
+                        error: 'No accounts available in pool',
+                        message: 'all accounts are rate-limited or in auth cool-down; retry shortly',
+                    }));
+            };
             const selectPoolAccount = () => {
                 if (upstreamApiKey) {
                     // Per-token API-key mode: no OAuth, no pool selection. `poolAccount`
@@ -2322,26 +2418,25 @@ export async function startProxy(opts = {}) {
                     // openai-compat backend. An EMPTY pool still 503s: that's a setup
                     // error the operator needs to see, not traffic to quietly re-bill
                     // somewhere else.
-                    const fallbackViable = poolFallbackModel !== null && openaiBackend !== null
-                        && isOpenAI && pool.size > 0;
+                    // Defer whenever a fallback is ARMED and the pool has seats that
+                    // could be drained. WHICH provider can serve it is decided at the
+                    // dispatch below, not here, because answering that needs an await —
+                    // a Codex account's model list — and this selector is synchronous.
+                    //
+                    // Before v6.0.0 this also demanded `openaiBackend !== null && isOpenAI`,
+                    // which silently made the entire subscription failover unreachable:
+                    // an Anthropic-shape request, or a box with a Codex account and no
+                    // api-key backend, 503'd HERE, before the dispatcher ever ran. That is
+                    // exactly the deployment this release is about, so the feature was
+                    // dead in the configuration it was written for. Caught in review on
+                    // dario#1145 — the routing tests all passed, because none of them went
+                    // through this selector.
+                    //
+                    // An EMPTY pool still 503s: that's a setup error the operator needs to
+                    // see, not traffic to quietly re-bill somewhere else.
+                    const fallbackViable = poolFallbackModels.length > 0 && pool.size > 0;
                     if (!fallbackViable) {
-                        // Two distinct empty-selection cases (#599): the pool has no accounts
-                        // at all (headless admin bootstrap — nothing added yet), vs. it has
-                        // accounts but all are rate-limited / in auth cool-down. Give each a
-                        // truthful, actionable message so a headless operator isn't told
-                        // "rate-limited" when they simply haven't added an account.
-                        res.writeHead(503, JSON_HEADERS);
-                        res.end(JSON.stringify(pool.size === 0
-                            ? {
-                                error: 'No account configured',
-                                message: adminEnabled
-                                    ? 'dario is running in admin mode with no account yet. Add one via POST /admin/login/start, then retry.'
-                                    : 'No accounts available. Run `dario login`, or add accounts with `dario accounts add`.',
-                            }
-                            : {
-                                error: 'No accounts available in pool',
-                                message: 'all accounts are rate-limited or in auth cool-down; retry shortly',
-                            }));
+                        writePoolUnavailable();
                         return false;
                     }
                 }
@@ -2462,6 +2557,65 @@ export async function startProxy(opts = {}) {
                 }
                 catch { /* not JSON — fall through */ }
             }
+            // Shadow compare (v6.0.0) — the full rationale is in compare.ts. Armed
+            // per request by `x-dario-compare: <model>`, it runs the same prompt past
+            // the other model family BESIDE the real answer and keeps both. Hooked in
+            // here, ahead of routing, so it covers whichever provider ends up serving.
+            //
+            // Nothing below is allowed to depend on it: the tee only observes bytes
+            // already on their way out, the comparison is never awaited by the
+            // request, and every failure path resolves rather than throws.
+            const compareTarget = readCompareTarget(req.headers);
+            if (compareTarget) {
+                const compareShape = isOpenAI ? 'openai' : 'anthropic';
+                // Snapshot the body NOW. `body` is reassigned later by the codex→Claude
+                // fall-through, and the finish callback below closes over it — so a
+                // comparison on a request that failed over would record the SWAPPED
+                // model as `primaryModel` and the swapped payload as the "verbatim"
+                // request. That record would then quietly attribute the primary answer
+                // to the wrong model family, which is worse than having no record: the
+                // whole point of the log is deciding which family did better.
+                const compareRequestBody = Buffer.from(body);
+                const tee = teeResponse(res);
+                res.setHeader(COMPARE_RESULT_HEADER, compareTarget);
+                // Started before the primary is dispatched so the two overlap; holding
+                // it until afterwards would double the wall-clock of a comparison
+                // nobody is waiting on, for no benefit.
+                const running = runCompare({
+                    body: compareRequestBody,
+                    shape: compareShape,
+                    targetModel: compareTarget,
+                    corsOrigin,
+                    timeoutMs: upstreamTimeoutMs,
+                    verbose,
+                });
+                res.on('finish', () => {
+                    void running.then((result) => {
+                        let request = null;
+                        try {
+                            request = JSON.parse(compareRequestBody.toString());
+                        }
+                        catch { /* recorded as null */ }
+                        const asObj = (request ?? {});
+                        const written = writeCompareRecord({
+                            ts: new Date().toISOString(),
+                            path: urlPath,
+                            shape: compareShape,
+                            streaming: asObj.stream === true,
+                            primaryModel: typeof asObj.model === 'string' ? asObj.model : '(unknown)',
+                            comparedModel: compareTarget,
+                            request,
+                            primary: tee.captured(),
+                            compare: result.side,
+                            ...(result.skipped ? { skipped: result.skipped } : {}),
+                        });
+                        if (written)
+                            console.log(`[dario] compare vs ${compareTarget} -> ${written}`);
+                        else if (result.skipped)
+                            console.log(`[dario] compare vs ${compareTarget} skipped: ${result.skipped}`);
+                    });
+                });
+            }
             // Multi-provider routing (v3.6.0+). When an OpenAI-compat backend is
             // configured and the request is on /v1/chat/completions with a
             // GPT-family model (or a forced `openai:` prefix), forward it straight
@@ -2520,8 +2674,36 @@ export async function startProxy(opts = {}) {
                             console.log(`[dario] #${requestCount} ${req.method} ${urlPath} (model: ${rawModel}) → codex account ${codexCreds.alias}`);
                         }
                         requestCount++;
-                        await forwardToCodex(req, res, body, codexCreds, corsOrigin, SECURITY_HEADERS, upstreamTimeoutMs, verbose, isOpenAI ? 'openai' : 'anthropic');
-                        return;
+                        // Symmetric failover (v6.0.0). When the chain nominates a model the
+                        // Claude pool can serve and there are seats to serve it, let the
+                        // subscription DECLINE a 429/5xx rather than pass it to the client,
+                        // and pick the request back up on the Claude path below. Before
+                        // this, a rate-limited ChatGPT plan was terminal for a gpt-bound
+                        // request even with an idle Claude pool sitting right beside it.
+                        const claudeTarget = pickClaudeFallback(poolFallbackModels, codexModels);
+                        const canDefer = claudeTarget !== null && pool.size > 0 && !upstreamApiKey;
+                        const served = await forwardToCodex(req, res, body, codexCreds, corsOrigin, SECURITY_HEADERS, upstreamTimeoutMs, verbose, isOpenAI ? 'openai' : 'anthropic', fetch, canDefer);
+                        if (served)
+                            return;
+                        const swapped = buildPoolFallbackBody(body, claudeTarget);
+                        if (!swapped) {
+                            res.writeHead(503, { 'Content-Type': 'application/json', ...SECURITY_HEADERS });
+                            res.end(JSON.stringify({ error: { type: 'upstream_unavailable', message: 'Codex backend unavailable and the request body could not be re-pointed at the Claude pool.' } }));
+                            return;
+                        }
+                        console.log(`[dario] #${requestCount} codex unavailable -> claude pool as ${claudeTarget}`);
+                        // Copy so the type matches the ArrayBuffer-backed buffer this
+                        // handler threads through (Buffer.concat's), as the other in-place
+                        // body rewrites above already do.
+                        body = Buffer.from(swapped);
+                        // The Claude path prefers this cached parse over `body`. Leaving it
+                        // stale would send the OLD model upstream while every log line and
+                        // the response header claimed the swap happened — a failure that
+                        // reads as a success, which is the exact bug class this release
+                        // spent its whole review budget hunting.
+                        parsedBody = null;
+                        res.setHeader('x-dario-pool-fallback', claudeTarget);
+                        // fall through to Claude's turn below
                     }
                     if (rawModel && openaiBackend && decision.provider === 'openai') {
                         if (verbose) {
@@ -2548,14 +2730,20 @@ export async function startProxy(opts = {}) {
             // response carries `x-dario-pool-fallback` — a substituted model must
             // never be silent. GPT-bound requests never reach here (the routing
             // block above already forwarded them; they don't need the pool).
-            if (!upstreamApiKey && !poolAccount && poolFallbackModel && openaiBackend) {
+            if (!upstreamApiKey && !poolAccount && await tryCodexPoolFallback(req, res, body, poolFallbackModels, isOpenAI ? 'openai' : 'anthropic', 'pool exhausted')) {
+                return;
+            }
+            // `isOpenAI` is REQUIRED here and was not, before v6.0.0 — the selector's
+            // own isOpenAI check was the only thing keeping Anthropic-shape requests
+            // out of this branch. Relaxing the selector without moving that guard down
+            // would forward a /v1/messages request to an openai-compat backend and
+            // hand the client an OpenAI-shaped response for a Messages request. This
+            // route still has no reverse translation; the codex route above does,
+            // which is why it takes both shapes and this one does not.
+            if (!upstreamApiKey && !poolAccount && poolFallbackModel && openaiBackend && isOpenAI) {
                 const fallbackBody = buildPoolFallbackBody(body, poolFallbackModel);
                 if (!fallbackBody) {
-                    res.writeHead(503, JSON_HEADERS);
-                    res.end(JSON.stringify({
-                        error: 'No accounts available in pool',
-                        message: 'all accounts are rate-limited or in auth cool-down; retry shortly',
-                    }));
+                    writePoolUnavailable();
                     return;
                 }
                 console.log(`[dario] #${requestCount} pool exhausted — /v1/chat/completions → ${openaiBackend.name} as ${poolFallbackModel}`);
@@ -2563,6 +2751,17 @@ export async function startProxy(opts = {}) {
                 await forwardToOpenAI(req, res, fallbackBody, openaiBackend, corsOrigin, { ...SECURITY_HEADERS, 'x-dario-pool-fallback': poolFallbackModel }, upstreamTimeoutMs, verbose);
                 return;
             }
+            // Deferred at selection because a fallback was armed, but nothing could
+            // actually serve it — no Codex account lists the model, and either there
+            // is no api-key backend or this is the wrong wire shape for one. Answer
+            // with the truth the selector used to give. Without this the request
+            // would fall through to the Claude path with no account and an empty
+            // bearer token, turning a clean 503 into a confusing upstream 401.
+            if (!upstreamApiKey && !poolAccount) {
+                console.log(`[dario] #${requestCount} pool exhausted and no fallback provider could serve ${poolFallbackModels.join(', ') || '(none configured)'}`);
+                writePoolUnavailable();
+                return;
+            }
             // Parse body once, apply OpenAI translation, model override, and sanitization
             let finalBody = body.length > 0 ? body : undefined;
             let ccToolMap = null;
@@ -3429,6 +3628,9 @@ export async function startProxy(opts = {}) {
                     // bytes — the Anthropic translation went into finalBody, never
                     // back into body. Marked via x-dario-pool-fallback, same as the
                     // selection-time path.
+                    if (await tryCodexPoolFallback(req, res, body, poolFallbackModels, isOpenAI ? 'openai' : 'anthropic', 'pool exhausted mid-flight (429, no peer)')) {
+                        return;
+                    }
                     if (isOpenAI && poolFallbackModel && openaiBackend) {
                         const fallbackBody = buildPoolFallbackBody(body, poolFallbackModel);
                         if (fallbackBody) {

package/docs/commands.md

@@ -37,7 +37,7 @@ This page is the per-flag reference. For environment variables grouped by task
 | `--verbose` / `-v` | Log every request (one line per request — method + path + billing bucket) | off |
 | `--verbose=2` / `-vv` / `DARIO_LOG_BODIES=1` | Also dump the outbound request body (redacted: bearer tokens, `sk-ant-*` keys, JWTs stripped; capped at 8KB). For wire-level client-compat debugging. | off |
 | `--log-file=<path>` / `DARIO_LOG_FILE` | Append one JSON-ND record per completed request to PATH. Useful for backgrounded proxies where stdout is unobserved (where `--verbose` can't help). Field set: `ts`, `req`, `method`, `path`, `model`, `status`, `latency_ms`, `in_tokens`, `out_tokens`, `cache_read`, `cache_create`, `claim`, `bucket`, `account`, `client`, `preserve_tools`, `stream`, plus `reject` / `error` on failure paths. Secrets scrubbed via the same redactor that `--verbose-bodies` uses; no request bodies. | off |
-| `--pool-fallback=<model>` / `DARIO_POOL_FALLBACK` / config `poolFallback.model` | Strictly opt-in. When every pool seat is drained or in auth cool-down, forward OpenAI-shape requests (`/v1/chat/completions`) to the configured openai-compat backend as `<model>` instead of surfacing the 429/503. Every fallback response carries `x-dario-pool-fallback: <model>` — never silent. Anthropic-shape requests keep the error (no reverse response translation). Requires an openai-compat backend (`dario backend add …`); inert without one. Empty pool still 503s (setup error, not traffic to re-bill). Empty flag value disables, overriding env + config. See [Pool-exhausted fallback](./multi-account-pool.md#pool-exhausted-fallback). | off |
+| `--pool-fallback=<models>` / `DARIO_POOL_FALLBACK` / config `poolFallback.model` | Strictly opt-in. When every pool seat is drained or in auth cool-down (at selection, or mid-flight on a 429 with no peer left), serve the request as `<model>` from whichever provider can, instead of surfacing the 429/503. Accepts a **chain** — `gpt-5.6-sol,claude-sonnet-5` — read left to right, each provider taking the first entry it can serve. A Codex/ChatGPT subscription that lists the model is preferred (no per-token cost) and works on **both** wire shapes; otherwise a configured openai-compat backend, which is still OpenAI-path only (no Messages translation on that route). A chain also makes failover **symmetric**: a rate-limited or failing subscription hands the request back to the Claude pool. Only a 429/5xx fails over — a 400 surfaces, since a bad request would just reproduce itself elsewhere. Every substituted response carries `x-dario-pool-fallback: <model>` — never silent. Needs a Codex account (`dario add altman`) or a backend (`dario backend add …`); `dario doctor` reports it as INERT with neither. Empty pool still 503s (setup error, not traffic to re-bill). Empty flag value disables, overriding env + config. See [Pool-exhausted fallback](./multi-account-pool.md#pool-exhausted-fallback). | off |
 | `--passthrough-betas=<csv>` / `DARIO_PASSTHROUGH_BETAS` | Beta flags ALWAYS forwarded upstream regardless of CC's captured set or the client's `anthropic-beta` header. Bypasses the billable-beta filter (so `extended-cache-ttl-*` survives if you opt in). Per-account rejection cache still applies — a pinned flag the upstream 400's gets dropped on retry rather than re-sent forever. Use when you know a beta works on your account but isn't in the captured template, or when client traffic should be force-augmented. Empty flag value (`--passthrough-betas=`) clears the env-default. | off |
 | `--strict-tls` / `DARIO_STRICT_TLS=1` | Refuse to start proxy mode unless runtime classifies as `bun-match` — i.e. the TLS ClientHello matches CC's. See [Wire-fidelity axes](./wire-fidelity.md). (v3.23) | off |
 | `--pace-min=<ms>` / `DARIO_PACE_MIN_MS` | Minimum inter-request gap in ms. Replaces the legacy hardcoded 500 ms. (v3.24) | `500` |
@@ -48,7 +48,7 @@ This page is the per-flag reference. For environment variables grouped by task
 | `--session-max-age=<ms>` / `DARIO_SESSION_MAX_AGE_MS` | Hard ceiling on a session-id's lifetime regardless of activity. (v3.28) | off |
 | `--session-per-client` / `DARIO_SESSION_PER_CLIENT=1` | Split session-id registry by a per-client header so multi-UI fan-out doesn't collapse onto one id. (v3.28) | off |
 | `--pool-strategy=<headroom\|fill-first>` / `DARIO_POOL_STRATEGY` | Where new conversations land in a multi-account pool. `headroom` spreads them to the seat with the most slack; `fill-first` concentrates them on the alphabetically-first eligible seat until it drains to the 2% floor, then spills to the next — primary/backup semantics, alias naming (`1-main`, `2-overflow`) picks the fill order. Sticky bindings behave identically under both. See [Multi-account pool](./multi-account-pool.md#routing-strategy). | `headroom` |
-| `--pool-fallback=<model>` / `DARIO_POOL_FALLBACK` / config `poolFallback.model` | When every pool seat is drained or in auth cool-down (at selection, or mid-flight on a 429 with no peer left), forward **OpenAI-shape** requests (`/v1/chat/completions`) to the configured openai-compat backend as `<model>` instead of surfacing the 429/503. Every substituted response carries `x-dario-pool-fallback: <model>` — a swapped model is never silent. Anthropic-shape requests (`/v1/messages`) keep the error: dario has no OpenAI→Anthropic response translation. Requires `dario backend add …`; inert otherwise. Empty flag value (`--pool-fallback=`) disables, overriding env + config. See [Multi-account pool](./multi-account-pool.md#pool-exhausted-fallback). | off |
+| `--pool-fallback=<models>` / `DARIO_POOL_FALLBACK` / config `poolFallback.model` | Strictly opt-in. When every pool seat is drained or in auth cool-down (at selection, or mid-flight on a 429 with no peer left), serve the request as `<model>` from whichever provider can, instead of surfacing the 429/503. Accepts a **chain** — `gpt-5.6-sol,claude-sonnet-5` — read left to right, each provider taking the first entry it can serve. A Codex/ChatGPT subscription that lists the model is preferred (no per-token cost) and works on **both** wire shapes; otherwise a configured openai-compat backend, which is still OpenAI-path only (no Messages translation on that route). A chain also makes failover **symmetric**: a rate-limited or failing subscription hands the request back to the Claude pool. Only a 429/5xx fails over — a 400 surfaces, since a bad request would just reproduce itself elsewhere. Every substituted response carries `x-dario-pool-fallback: <model>` — never silent. Needs a Codex account (`dario add altman`) or a backend (`dario backend add …`); `dario doctor` reports it as INERT with neither. Empty pool still 503s (setup error, not traffic to re-bill). Empty flag value disables, overriding env + config. See [Pool-exhausted fallback](./multi-account-pool.md#pool-exhausted-fallback). | off |
 | `--system-prompt=<verbatim\|partial\|aggressive\|filepath>` / `DARIO_SYSTEM_PROMPT` | System-prompt mode for outbound CC-shaped requests. `partial` strips behavioral constraints (Tone-and-style, Text-output, scope/verbosity/comment bullets) for ~1.2–2.8× output capability on open-ended work. `aggressive` adds prompt-level RLHF restatement removal (<3% over partial — alignment is RLHF-trained). `<filepath>` fully replaces the slot with file contents. Empirically validated as unfingerprinted by the billing classifier — see [`system-prompt.md`](./system-prompt.md) and [`research/system-prompt-classifier-study.md`](./research/system-prompt-classifier-study.md). (v3.34) | `verbatim` |
 | `--upstream-proxy=<url>` / `--via=<url>` / `DARIO_UPSTREAM_PROXY` | Route dario's outbound fetches (api.anthropic.com, OpenAI-compat backends, OAuth) through an HTTP/HTTPS proxy. Pair with the HTTP proxy mode of a VPN provider (Mullvad, AirVPN), a corporate proxy, privoxy/Tor, etc. Localhost calls bypass. Requires Bun runtime; SOCKS5 not supported. Full provider matrix + setup in [`vpn-routing.md`](./vpn-routing.md). (v3.35) | unset |
 | `DARIO_API_KEY` | If set, all endpoints (except `/health`) require a matching `x-api-key` or `Authorization: Bearer` header. Required when `--host` binds non-loopback. | unset (open) |

package/docs/multi-account-pool.md

@@ -41,13 +41,39 @@ Multi-turn agent sessions pin to one account for the life of the conversation, s
 
 ## Pool-exhausted fallback
 
-`--pool-fallback=<model>` (env `DARIO_POOL_FALLBACK`, config `poolFallback.model`) is a strictly opt-in escape hatch for when the whole pool is drained or cooling. With it set **and** an openai-compat backend configured (`dario backend add …`), an OpenAI-shape request (`/v1/chat/completions`) that the pool can't serve — at selection time, or after a mid-flight 429 with no peer left — is forwarded to that backend with the model swapped to `<model>`, instead of returning the 429/503.
+`--pool-fallback=<models>` (env `DARIO_POOL_FALLBACK`, config `poolFallback.model`) is a strictly opt-in escape hatch for when a provider can't serve. A request the Claude pool can't take — at selection time, or after a mid-flight 429 with no peer left — is served as the nominated model by whichever provider can, instead of returning the 429/503.
 
-Three deliberate limits:
+The value may be a **chain**, read left to right, each provider taking the first entry it can actually serve:
 
-- **OpenAI-shape only.** Anthropic-shape requests (`/v1/messages`) keep the error. dario translates Anthropic→OpenAI on the way out but has no OpenAI→Anthropic *response* translator, so a fallback there would corrupt the client's stream. Point Anthropic-native clients that want this at `/v1/chat/completions`, or leave the fallback off.
-- **Never silent.** Every substituted response carries `x-dario-pool-fallback: <model>`. A quietly swapped model is exactly the surprise this project exists to avoid — check for the header if you need to know which requests fell back.
+```bash
+dario proxy --pool-fallback=gpt-5.6-sol,claude-sonnet-5
+```
+
+- Claude pool drained → served as `gpt-5.6-sol` from your ChatGPT subscription.
+- Subscription rate-limited or down → handed back to the Claude pool as `claude-sonnet-5`.
+
+Neither subscription hitting its ceiling can take the deployment down on its own. A single-entry chain is one-way and behaves exactly as it did before v6.0.0.
+
+**Since v6.0.0 a subscription is a first-class failover target**, on both wire shapes. Before that the only target was an api-key backend on `/v1/chat/completions`, which made failover inert for anyone whose second provider is a ChatGPT plan — and left Anthropic-shape clients (Claude Code, the Anthropic SDKs, agent runtimes) with nowhere to go at all.
+
+Deliberate limits:
+
+- **Only a 429 or 5xx fails over.** A 400 surfaces to the client. A bad request that fails over just reproduces itself on the other provider and buries the real cause.
+- **The Claude entry must be a real `claude-*` id.** "Not a codex slug" would also match a typo or a model meant for a third provider, and swapping that in trades a recoverable 429 for an unrecoverable 404. Anything that doesn't look like an Anthropic model is ignored — failing closed. A `--model-alias` is not accepted here; name the real id.
+- **The api-key backend is still OpenAI-shape only.** There is no Messages translation on that route. A Codex account has one, which is why it is preferred.
+- **Never silent.** Every substituted response carries `x-dario-pool-fallback: <model>`. A quietly swapped model is exactly the surprise this project exists to avoid.
 - **Empty pool still errors.** A pool with zero accounts is a setup mistake (`dario login` never ran); that returns the usual 503 rather than silently re-billing every request to another provider.
+- **Strictly opt-in.** Without the flag, a drained pool returns its honest 429/503.
+
+`dario doctor` reports which state you are actually in — including *armed but INERT*, meaning a fallback is configured with no provider able to serve it:
+
+```
+[ 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`
+```
+
+An api-key backend still works as a target, on the OpenAI path:
 
 ```bash
 dario backend add openrouter --key=sk-or-... --base-url=https://openrouter.ai/api/v1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "5.5.89",
+  "version": "6.0.0",
   "description": "Use your Claude Pro/Max subscription in any tool — Cursor, Cline, Aider, the Agent SDK, your scripts — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint.",
   "type": "module",
   "bin": {