@askalf/dario 6.13.31 → 6.14.1

package/dist/cli.js

@@ -649,6 +649,16 @@ async function proxy() {
         ?? process.env['DARIO_POOL_FALLBACK']
         ?? fileCfg.poolFallback?.model
         ?? '').trim() || undefined;
+    // --family-fallback=fable=claude-opus-5-5 / DARIO_FAMILY_FALLBACK / config
+    // familyFallback: strictly opt-in. A request for a family every seat is
+    // parked on is served as the named model of another family the pool can
+    // serve (response marked x-dario-family-fallback). The proxy parses and
+    // validates it. `--family-fallback=` (empty value) disables, overriding env
+    // and config, as --pool-fallback= does.
+    const familyFallbackFromFlag = args.find((a) => a.startsWith('--family-fallback='))?.split('=').slice(1).join('=');
+    const familyFallback = familyFallbackFromFlag
+        ?? process.env['DARIO_FAMILY_FALLBACK']
+        ?? fileCfg.familyFallback;
     // --model-alias=name=target (repeatable) / DARIO_MODEL_ALIASES=name=target,…
     // / config modelAliases — user-defined model aliases, merged per-key with
     // flags winning over env winning over the config file. Applied at request
@@ -776,7 +786,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, analyticsToken, 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, shutdownGraceMs, poolStrategy, poolHeadroomFloor, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger, keys, keysPath, keySockets: keySockets.length > 0 ? keySockets : undefined });
+    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, analyticsToken, 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, shutdownGraceMs, poolStrategy, poolHeadroomFloor, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, familyFallback, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger, keys, keysPath, keySockets: keySockets.length > 0 ? keySockets : undefined });
 }
 /**
  * `dario keys` — named keys for a shared dario (v6.8, dario#1318). One
@@ -2260,6 +2270,16 @@ async function help() {
                              Needs one of those configured. Empty value
                              disables. Env: DARIO_POOL_FALLBACK. Config:
                              poolFallback.model.
+    --family-fallback=<family=model,...>
+                             When every pool seat is parked for a model
+                             family, serve its requests as <model> on the
+                             Claude pool instead, while some seat can
+                             serve that model's family. For Fable, which
+                             runs out of included credit while Opus still
+                             has room: fable=claude-opus-5-5. Response
+                             carries x-dario-family-fallback. Empty value
+                             disables. Env: DARIO_FAMILY_FALLBACK.
+                             Config: familyFallback.
     --model-alias=<name=target>
                              User-defined model alias, repeatable.
                              Applied to the client's model name before

package/dist/config-file.d.ts

@@ -106,6 +106,13 @@ export interface DarioConfig {
     poolFallback?: {
         model?: string | null;
     };
+    /**
+     * Family fallback: source family to target Claude model (`{ "fable":
+     * "claude-opus-5-5" }`). When every pool seat is parked for a request's
+     * family, the request is served as the target on the Claude pool. The
+     * response is marked `x-dario-family-fallback`. Empty = off.
+     */
+    familyFallback?: Record<string, string>;
     /**
      * User-defined model aliases: client-visible name → target model.
      * Resolved at request time before provider-prefix parsing, so a target

package/dist/config-file.js

@@ -69,6 +69,7 @@ export function defaultConfig() {
         effort: null,
         maxTokens: null,
         poolFallback: { model: null },
+        familyFallback: {},
         modelAliases: {},
         passthroughBetas: [],
         systemPrompt: null,
@@ -335,6 +336,14 @@ function sanitize(parsed) {
         if (n !== undefined)
             out.maxTokens = n;
     }
+    if (isPlainObject(parsed.familyFallback)) {
+        const pairs = {};
+        for (const [k, v] of Object.entries(parsed.familyFallback)) {
+            if (typeof v === 'string')
+                pairs[k] = v;
+        }
+        out.familyFallback = pairs;
+    }
     if (isPlainObject(parsed.modelAliases)) {
         const aliases = {};
         for (const [k, v] of Object.entries(parsed.modelAliases)) {

package/dist/doctor-core.js

@@ -1261,6 +1261,22 @@ export async function runChecks(opts = {}) {
     catch (err) {
         checks.push({ status: 'warn', label: 'Failover', detail: `check failed: ${err.message}` });
     }
+    // ---- Family fallback: what the proxy will parse, from the same sources.
+    try {
+        const { loadConfig } = await import('./config-file.js');
+        const { parseFamilyFallback, describeFamilyFallback } = await import('./family-fallback.js');
+        const spec = process.env.DARIO_FAMILY_FALLBACK ?? loadConfig().config.familyFallback ?? null;
+        const { map, errors } = parseFamilyFallback(spec);
+        if (errors.length > 0) {
+            checks.push({ status: 'warn', label: 'Family fallback', detail: `dropped ${errors.join('; ')}${map.size > 0 ? `; kept ${describeFamilyFallback(map)}` : ''}` });
+        }
+        else {
+            checks.push({ status: map.size > 0 ? 'ok' : 'info', label: 'Family fallback', detail: map.size > 0 ? `${describeFamilyFallback(map)} when every seat is parked for the first` : 'off (set DARIO_FAMILY_FALLBACK=fable=claude-opus-5-5 or --family-fallback)' });
+        }
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Family fallback', detail: `check failed: ${err.message}` });
+    }
     // ---- Ledger (v6.6.4) — see ledgerReadiness() for the why. The default
     // port's file; DARIO_LEDGER_PATH is honoured like the proxy honours it.
     try {

package/dist/family-fallback.d.ts

@@ -0,0 +1,40 @@
+/** Source family → target Claude model. */
+export type FamilyFallbackMap = ReadonlyMap<string, string>;
+export interface ParsedFamilyFallback {
+    map: Map<string, string>;
+    /** One line per entry that was dropped, saying why. */
+    errors: string[];
+}
+/**
+ * Parse `fable=claude-opus-5-5,sonnet=claude-haiku-5` (or the same pairs from
+ * a config object). A source must be a family `modelFamily` knows; a target
+ * must name a Claude model of a DIFFERENT known family, so a fallback can never
+ * point back at the family it is leaving. Bad entries are dropped and reported,
+ * the rest kept. Later entries for the same family win.
+ */
+export declare function parseFamilyFallback(spec: string | Record<string, unknown> | null | undefined): ParsedFamilyFallback;
+/**
+ * The model to serve `model` as, or null to leave the request alone.
+ *
+ * `parked(family)` is whether a rate limit keeps every pool seat off that
+ * family (`AccountPool.familyRateLimited`), and `servable(family)` whether some seat
+ * is eligible for it right now. The switch happens only when the request's own
+ * family is parked and the target's is servable: a pool that is merely busy,
+ * expiring a token or empty keeps its existing handling, and a target that is
+ * parked too gains nothing. One step, never chained.
+ *
+ * A `[1m]` long-context tag on the request is carried onto the target when the
+ * target has none, so the switch does not shrink the context window asked for.
+ *
+ * A model name that is not printable ASCII (at most 256 characters, no spaces
+ * or control characters) is left alone: no real model is named so, and the
+ * name the client sent is echoed in the `x-dario-family-fallback` header and
+ * the log, where a line break would fail the header (setHeader throws, the
+ * request errors) or forge a log line.
+ */
+export declare function familyFallbackModel(map: FamilyFallbackMap, model: string, pool: {
+    parked: (family: string) => boolean;
+    servable: (family: string) => boolean;
+}): string | null;
+/** `fable → claude-opus-5-5, sonnet → claude-haiku-5`, for the startup banner and doctor. */
+export declare function describeFamilyFallback(map: FamilyFallbackMap): string;

package/dist/family-fallback.js

@@ -0,0 +1,93 @@
+// Family fallback: a request for a model family every pool seat is parked on
+// is served as another Claude model the pool can still serve, instead of
+// answering 429 or leaving the Claude pool. The case it is for is Fable, which
+// is metered on a seat's included credit rather than its 5h and 7d windows:
+// once that credit is spent the seat still has room for Opus, but every Fable
+// request is parked until the credit resets.
+//
+// Strictly opt-in. Sourced from `--family-fallback=fable=claude-opus-5-5` /
+// `DARIO_FAMILY_FALLBACK` / config `familyFallback`. Pure: the proxy passes in
+// what the pool says, so the decision is testable without one.
+import { KNOWN_FAMILIES, modelFamily } from './pool.js';
+const ONE_M = /\[1m\]$/i;
+/**
+ * Parse `fable=claude-opus-5-5,sonnet=claude-haiku-5` (or the same pairs from
+ * a config object). A source must be a family `modelFamily` knows; a target
+ * must name a Claude model of a DIFFERENT known family, so a fallback can never
+ * point back at the family it is leaving. Bad entries are dropped and reported,
+ * the rest kept. Later entries for the same family win.
+ */
+export function parseFamilyFallback(spec) {
+    const map = new Map();
+    const errors = [];
+    if (spec === null || spec === undefined)
+        return { map, errors };
+    const pairs = typeof spec === 'string'
+        ? spec.split(',').map((s) => s.trim()).filter(Boolean).map((entry) => {
+            const eq = entry.indexOf('=');
+            return eq < 0 ? [entry, undefined] : [entry.slice(0, eq), entry.slice(eq + 1)];
+        })
+        : Object.entries(spec);
+    for (const [rawFrom, rawTo] of pairs) {
+        const from = rawFrom.trim().toLowerCase();
+        const to = typeof rawTo === 'string' ? rawTo.trim() : '';
+        if (!KNOWN_FAMILIES.includes(from)) {
+            errors.push(`"${rawFrom}": not a model family (one of ${KNOWN_FAMILIES.join(', ')})`);
+            continue;
+        }
+        if (!to) {
+            errors.push(`"${rawFrom}": no target model (write ${from}=<model>)`);
+            continue;
+        }
+        const toFamily = modelFamily(to);
+        if (!toFamily || !/^claude-/i.test(to)) {
+            errors.push(`"${rawFrom}=${to}": the target must be a claude-* model of a known family`);
+            continue;
+        }
+        if (toFamily === from) {
+            errors.push(`"${rawFrom}=${to}": the target is the same family`);
+            continue;
+        }
+        map.set(from, to);
+    }
+    return { map, errors };
+}
+/**
+ * The model to serve `model` as, or null to leave the request alone.
+ *
+ * `parked(family)` is whether a rate limit keeps every pool seat off that
+ * family (`AccountPool.familyRateLimited`), and `servable(family)` whether some seat
+ * is eligible for it right now. The switch happens only when the request's own
+ * family is parked and the target's is servable: a pool that is merely busy,
+ * expiring a token or empty keeps its existing handling, and a target that is
+ * parked too gains nothing. One step, never chained.
+ *
+ * A `[1m]` long-context tag on the request is carried onto the target when the
+ * target has none, so the switch does not shrink the context window asked for.
+ *
+ * A model name that is not printable ASCII (at most 256 characters, no spaces
+ * or control characters) is left alone: no real model is named so, and the
+ * name the client sent is echoed in the `x-dario-family-fallback` header and
+ * the log, where a line break would fail the header (setHeader throws, the
+ * request errors) or forge a log line.
+ */
+export function familyFallbackModel(map, model, pool) {
+    if (map.size === 0)
+        return null;
+    if (!/^[\x21-\x7e]{1,256}$/.test(model))
+        return null;
+    const family = modelFamily(model);
+    if (!family)
+        return null;
+    const target = map.get(family);
+    if (!target)
+        return null;
+    const targetFamily = modelFamily(target);
+    if (!targetFamily || !pool.parked(family) || !pool.servable(targetFamily))
+        return null;
+    return ONE_M.test(model.trim()) && !ONE_M.test(target) ? `${target}[1m]` : target;
+}
+/** `fable → claude-opus-5-5, sonnet → claude-haiku-5`, for the startup banner and doctor. */
+export function describeFamilyFallback(map) {
+    return [...map].map(([from, to]) => `${from} → ${to}`).join(', ');
+}

package/dist/pool.d.ts

@@ -637,6 +637,23 @@ export declare class AccountPool {
     }): void;
     remove(alias: string): boolean;
     get size(): number;
+    /**
+     * Whether some seat is eligible for `family` right now: the filter
+     * `select()` starts from, asked without picking a seat. The family fallback
+     * reads it to switch only to a family the pool can serve.
+     */
+    canServe(family: string | null, now?: number): boolean;
+    /**
+     * Whether a rate limit keeps every seat off `family` right now: its own
+     * window, or a per-model bucket parked by an earlier 429. Unlike
+     * `parkedUntil()`, which counts a seat only while its LAST reading is the
+     * rejection, this stays true after the seat has served another family
+     * since: an Opus 200 after a Fable credit 429 replaces the reading, but the
+     * carried-forward bucket still keeps Fable off the seat. False for an empty
+     * pool, and for a seat that is off for another reason (an expiring token,
+     * an auth cool-down).
+     */
+    familyRateLimited(family: string | null, now?: number): boolean;
     /**
      * Record an auth failure (401/403/auth_error/permission_error/invalid_grant)
      * against `alias`. Increments the consecutive-failure counter and stamps

package/dist/pool.js

@@ -341,6 +341,14 @@ export function withParkedBuckets(prev, next, now = Date.now()) {
  */
 export function isParkedInLiveWindow(account, now = Date.now(), family) {
     const rl = account.rateLimit;
+    // A bucket the seat was parked on, carried past a reading that did not
+    // measure it (an Opus 200, or an Opus 429 that named no exhausted window,
+    // after a Fable credit 429; see withParkedBuckets): whatever the seat's
+    // status says now, the bucket's reset is still ahead and a probe for a
+    // family it binds can only 429 again. The bucket-scoped rejection itself is
+    // decided below, where a 429 with no stated reset stays probeable.
+    if (!isBucketScopedRejection(rl) && familyParkedOnBuckets(rl, family, now))
+        return true;
     // A non-exhausted rejection is never "parked in a live window": its reset
     // was not this seat's window, and once its cool-down passes asking is the
     // way back (the all-exhausted branch may probe it even sooner).
@@ -1013,6 +1021,28 @@ export class AccountPool {
     get size() {
         return this.accounts.size;
     }
+    /**
+     * Whether some seat is eligible for `family` right now: the filter
+     * `select()` starts from, asked without picking a seat. The family fallback
+     * reads it to switch only to a family the pool can serve.
+     */
+    canServe(family, now = Date.now()) {
+        return [...this.accounts.values()].some((a) => isAccountEligible(a, now, family));
+    }
+    /**
+     * Whether a rate limit keeps every seat off `family` right now: its own
+     * window, or a per-model bucket parked by an earlier 429. Unlike
+     * `parkedUntil()`, which counts a seat only while its LAST reading is the
+     * rejection, this stays true after the seat has served another family
+     * since: an Opus 200 after a Fable credit 429 replaces the reading, but the
+     * carried-forward bucket still keeps Fable off the seat. False for an empty
+     * pool, and for a seat that is off for another reason (an expiring token,
+     * an auth cool-down).
+     */
+    familyRateLimited(family, now = Date.now()) {
+        const all = [...this.accounts.values()];
+        return all.length > 0 && all.every((a) => accountIneligibility(a, now, family) === 'rate-limited');
+    }
     /**
      * Record an auth failure (401/403/auth_error/permission_error/invalid_grant)
      * against `alias`. Increments the consecutive-failure counter and stamps
@@ -1124,7 +1154,7 @@ export class AccountPool {
         // reported, or cooled, as if they were.
         const until = all.map((a) => {
             if (isParkedInLiveWindow(a, now, family)) {
-                return isBucketScopedRejection(a.rateLimit)
+                return familyParkedOnBuckets(a.rateLimit, family, now)
                     ? (a.rateLimit.parkedBucketsUntil ?? a.rateLimit.reset * 1000)
                     : a.rateLimit.reset * 1000;
             }
@@ -1326,7 +1356,9 @@ export class AccountPool {
             : exhausted
                 ? { ...merged, status: 'rejected', exhausted: true, parkedBuckets: undefined, parkedBucketsUntil: undefined }
                 : {
-                    ...merged,
+                    // Not a window, so not this seat's buckets either: a bucket parked
+                    // before it stays parked, as across any reading that did not measure it.
+                    ...withParkedBuckets(account.rateLimit, merged, now),
                     status: 'rejected',
                     exhausted: false,
                     cooldownUntil: now + (snapshot.retryAfterMs ?? NON_WINDOW_REJECTION_COOLDOWN_MS),

package/dist/proxy.d.ts

@@ -536,6 +536,17 @@ interface ProxyOptions {
      * `poolFallback.model`.
      */
     poolFallbackModel?: string;
+    /**
+     * Family fallback (opt-in): source family → target Claude model, as
+     * `fable=claude-opus-5-5,...` or an object. When every pool seat is parked
+     * for a request's family and some seat can serve the target's, the request
+     * is served as the target on the Claude pool, before the pool fallback is
+     * considered. Responses carry `x-dario-family-fallback: <requested model>`.
+     * Skipped in upstream API-key mode, under --model / --fast-model and for a
+     * seat-pinned request. Sourced from `--family-fallback` /
+     * `DARIO_FAMILY_FALLBACK` / config `familyFallback`. See family-fallback.ts.
+     */
+    familyFallback?: string | Record<string, string>;
     /**
      * User-defined model aliases, client-visible name (lowercase) → target.
      * Resolved per request BEFORE provider-prefix parsing (a target may

package/dist/proxy.js

@@ -55,6 +55,7 @@ import { codexUsageView, resolveCodexUsagePollMs } from './codex-usage.js';
 import { seedStaleCodexUsage } from './codex-backend.js';
 import { route as routeProvider } from './provider-adapter.js';
 import { selectPoolFallbackModels } from './pool-fallback-tier.js';
+import { parseFamilyFallback, familyFallbackModel, describeFamilyFallback } from './family-fallback.js';
 import { RequestQueue, QueueFullError, QueueTimeoutError, DEFAULT_MAX_CONCURRENT, DEFAULT_MAX_QUEUED, DEFAULT_QUEUE_TIMEOUT_MS, resolveMaxConcurrent } from './request-queue.js';
 import { waitForIdle, drainThenClose, shutdownTimers, DEFAULT_SHUTDOWN_GRACE_MS } from './shutdown-drain.js';
 import { clampTimerMs } from './timer-ms.js';
@@ -1555,6 +1556,15 @@ export async function startProxy(opts = {}) {
             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.');
         }
     }
+    // Family fallback (strictly opt-in, family-fallback.ts). Bad entries are
+    // dropped with a warning; the rest still apply.
+    const familyFallbackParsed = parseFamilyFallback(opts.familyFallback ?? null);
+    for (const e of familyFallbackParsed.errors)
+        console.warn(`[dario] family fallback: dropped ${e}`);
+    const familyFallback = familyFallbackParsed.map;
+    if (familyFallback.size > 0) {
+        console.log(`  Family fallback: ${describeFamilyFallback(familyFallback)}, when every seat is parked for the first and some seat can serve the second (marked x-dario-family-fallback)`);
+    }
     // User-defined model aliases (see parseModelAliasSpecs). Resolved by the
     // CLI (config < env < flags, per-key) and applied per request before
     // provider-prefix parsing; also advertised on /v1/models so client model
@@ -4412,6 +4422,33 @@ export async function startProxy(opts = {}) {
             // the fix for dario#1137 — a ChatGPT-subscription-only user has a
             // legitimately empty Claude pool, and the empty-pool 503 used to answer
             // codex-bound requests before the adapter was ever consulted.
+            //
+            // Family fallback first (see family-fallback.ts): a request for a family
+            // every seat is parked on, Fable once its included credit is spent, is
+            // re-pointed at the configured model of a family the pool can serve, so
+            // selection below picks a seat for THAT family. The same in-place swap
+            // as the codex-unavailable path above: `body` rebuilt, `parsedBody`
+            // dropped so the Claude path cannot send the old model.
+            if (familyFallback.size > 0 && !upstreamApiKey && !pinnedAccount && !modelOverride && !fastModelOverride && pool.size > 0) {
+                let fromModel = '';
+                try {
+                    fromModel = String((parsedBody ?? JSON.parse(body.toString())).model ?? '');
+                }
+                catch { /* not JSON: nothing to re-point */ }
+                const now = Date.now();
+                const toModel = fromModel ? familyFallbackModel(familyFallback, fromModel, {
+                    parked: (f) => pool.familyRateLimited(f, now),
+                    servable: (f) => pool.canServe(f, now),
+                }) : null;
+                const swapped = toModel ? buildPoolFallbackBody(body, toModel) : null;
+                if (toModel && swapped) {
+                    body = Buffer.from(swapped);
+                    parsedBody = null;
+                    requestFamily = modelFamily(toModel);
+                    res.setHeader('x-dario-family-fallback', fromModel);
+                    console.log(`[dario] #${requestCount} every seat is parked for ${fromModel} -> served as ${toModel} (family fallback)`);
+                }
+            }
             if (!selectPoolAccount())
                 return;
             // Pool-exhausted fallback dispatch. In OAuth mode poolAccount can only

package/docs/commands.md

@@ -43,6 +43,7 @@ This page is the per-flag reference. For environment variables grouped by task
 | `--no-keys` / `DARIO_KEYS=0`; `--keys-path=<file>` / `DARIO_KEYS_PATH` | Ignore named keys (`~/.dario/keys.json`) so only `DARIO_API_KEY` authenticates; or move the file. See [Named keys](./keys.md). (v6.8) | on, `~/.dario/keys.json` |
 | `--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=<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 |
+| `--family-fallback=<family=model,...>` / `DARIO_FAMILY_FALLBACK` / config `familyFallback` | Strictly opt-in. When a rate limit keeps every pool seat off a model family, serve that family's requests as `<model>` on the Claude pool, while some seat can serve the target's family. Written for Fable: its included credit runs out while the seat still has room for Opus, so `fable=claude-opus-5-5` keeps Fable traffic on the subscription instead of a local 429 until the credit resets. The target must be a `claude-*` model of another family; one step, never chained. Runs before `--pool-fallback`, so a pool with room for the target never leaves the Claude pool. Skipped in upstream API-key mode, under `--model`/`--fast-model` and for a seat-pinned request. A `[1m]` tag on the request carries over. Every switched response carries `x-dario-family-fallback: <requested model>`. Empty flag value disables, overriding env + config. See [Family fallback](./multi-account-pool.md#family-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` |
@@ -54,6 +55,7 @@ This page is the per-flag reference. For environment variables grouped by task
 | `--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\|expiring-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 floor, then spills to the next — primary/backup semantics, alias naming (`1-main`, `2-overflow`) picks the fill order; `expiring-first` does the same in order of each seat's 7-day reset, soonest first, so capacity that expires soonest is spent first. Sticky bindings behave identically under all three. See [Multi-account pool](./multi-account-pool.md#routing-strategy). | `headroom` |
 | `--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 |
+| `--family-fallback=<family=model,...>` / `DARIO_FAMILY_FALLBACK` / config `familyFallback` | Strictly opt-in. When a rate limit keeps every pool seat off a model family, serve that family's requests as `<model>` on the Claude pool, while some seat can serve the target's family. Written for Fable: its included credit runs out while the seat still has room for Opus, so `fable=claude-opus-5-5` keeps Fable traffic on the subscription instead of a local 429 until the credit resets. The target must be a `claude-*` model of another family; one step, never chained. Runs before `--pool-fallback`, so a pool with room for the target never leaves the Claude pool. Skipped in upstream API-key mode, under `--model`/`--fast-model` and for a seat-pinned request. A `[1m]` tag on the request carries over. Every switched response carries `x-dario-family-fallback: <requested model>`. Empty flag value disables, overriding env + config. See [Family fallback](./multi-account-pool.md#family-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

@@ -82,6 +82,22 @@ dario backend add openrouter --key=sk-or-... --base-url=https://openrouter.ai/ap
 dario proxy --pool-fallback=openrouter/anthropic/claude-3.5-sonnet
 ```
 
+## Family fallback
+
+`--family-fallback=<family=model,...>` (env `DARIO_FAMILY_FALLBACK`, config `familyFallback`) is for a pool that has room, but not for the family a request asks for. Fable is the case it was written for: it is metered on a seat's included credit (the `7d_oi` bucket), so once that credit is spent every Fable request is refused while the same seat still serves Opus. Without a fallback, Fable requests get `429` until the credit resets.
+
+```bash
+dario proxy --family-fallback=fable=claude-opus-5-5
+```
+
+- **When.** Only when a rate limit keeps every seat off the request's family, AND some seat can serve the target's family right now. A pool that is merely busy, a seat with an expiring token or in auth cool-down, and a target family that is parked too all keep their existing handling.
+- **Where.** On the Claude pool: the request is rebuilt with the target model before a seat is chosen, so selection, stickiness and the template all see the target. It runs before `--pool-fallback`, which then still covers a pool with no room at all.
+- **Never silent.** The response carries `x-dario-family-fallback: <requested model>`, the answer names the model that served it, and the proxy logs each switch.
+- **Not for.** Upstream API-key mode (no pool), a server-wide `--model`/`--fast-model` (which replaces the name anyway) and a seat-pinned request (`x-dario-account`), which asked for that seat as it is.
+- **Shape.** The source is a family (`opus`, `sonnet`, `haiku`, `fable`); the target a `claude-*` model of another family. One step, never chained. Bad entries are dropped with a warning at startup and in `dario doctor`. A `[1m]` tag on the request carries over to a target without one.
+
+The first Fable request after the credit runs out still goes upstream and comes back `429`: that answer is what parks Fable on the seat. Every Fable request after it is switched, including after the seat has served Opus since.
+
 ## In-flight 429 failover
 
 When a Claude request hits a 429 mid-flight, dario retries the *same request* against a different account before the client sees an error. The client sees one successful response; the pool sees the rejected account go cold until its window resets. Combined with session stickiness, long agent runs survive pool-level exhaustion without dropping user-facing turns.
@@ -108,6 +124,8 @@ curl http://localhost:3456/analytics    # per-account / per-model stats, burn ra
 
 **When every seat is parked.** A pool whose seats are all `rejected` inside live windows does not probe them again: dario answers the request itself with `429`, `retry-after` set to the earliest reset, `x-dario-upstream-rejection: pool_parked`, and nothing sent upstream. One log line marks the transition (`pool parked: all 6 seats are over their rate-limit windows, earliest resets in 21m`). Before 6.0.35 every such request re-probed the earliest-reset seat, so `rejectedCount` on that seat grew by one per request — a seat reading `rejected_count: 500` next to `request_count: 1` was that, not a seat that needed a re-login. With a `--pool-fallback` armed, the request goes to the fallback instead, as before.
 
+**A seat parked on one family's bucket stays parked for it.** A seat parked on a per-model bucket counts for the families that bucket binds even after it has served another family since: an Opus `200` (or an Opus `429` that names no exhausted window) after a Fable credit `429` does not make it probeable for Fable again before the bucket resets.
+
 **Spending extra usage while the pool is parked (dario#1282).** The parked answer is decided
 from the seats' own rate-limit verdicts, before anything is sent. Disarming the overage-guard
 does **not** change it: the guard is reactive — it reads the `representative-claim` on a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.13.31",
+  "version": "6.14.1",
   "description": "Use your Claude and ChatGPT subscriptions in Cursor, Cline, Aider, Claude Code and the Agent SDK — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint: either plan answers either wire shape, with automatic failover when one hits its limit.",
   "type": "module",
   "bin": {