@askalf/dario 5.2.5 → 5.2.7

package/dist/provider-adapter.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Provider routing seam.
+ *
+ * dario's "which backend owns this request" decision used to live inline in the
+ * request handler as a set of interleaved conditions (path class, provider
+ * prefix, GPT-family model test, the openai-backend reroute guard, the pool
+ * fallback guard). This module consolidates that decision into one place: a
+ * small set of `ProviderAdapter`s and a `route()` function that returns the
+ * primary provider plus any exhaustion fallback.
+ *
+ * Scope is deliberately the DECISION, not the request lifecycle. The Claude
+ * path's pool/template/cch/session/overage machinery stays shared below this
+ * seam — it's infrastructure that happens to serve one provider, not per-
+ * provider behaviour, so pushing it behind an adapter interface would make the
+ * Claude adapter the whole proxy and the OpenAI adapter nearly empty. The seam
+ * that pays for itself is routing + request-shaping; the rest is shared.
+ *
+ * The adapters reuse the same primitive proxy.ts uses (`isOpenAIModel`), so this
+ * is a consolidation of the existing decision, not a re-derivation of it.
+ */
+export type ProviderId = 'claude' | 'openai';
+/** Inputs the routing decision needs, computed once per request. */
+export interface RouteContext {
+    /** urlPath === '/v1/chat/completions' (OpenAI chat shape). */
+    isOpenAIPath: boolean;
+    /** Model name after provider-prefix stripping (e.g. 'gpt-4o', 'claude-opus-4-8'). */
+    model: string;
+    /** Forced provider from a `<provider>:` prefix or `--model` override; null if unforced. */
+    forcedProvider: ProviderId | null;
+    /** An openai-compat backend is configured (`dario backend add …`). */
+    hasOpenAIBackend: boolean;
+    /** `--pool-fallback=<model>` value, or null when disabled. */
+    poolFallbackModel: string | null;
+    /** Live pool account count. */
+    poolSize: number;
+}
+export interface RouteDecision {
+    /** Primary handler for the request. */
+    provider: ProviderId;
+    /** Provider to fall to on primary exhaustion; only claude→openai exists today. */
+    fallback: ProviderId | null;
+    /** Human-readable trace for `--verbose` and tests. */
+    reason: string;
+}
+export interface ProviderAdapter {
+    id: ProviderId;
+    /** Higher priority is offered the request first. */
+    priority: number;
+    /** True if this adapter should PRIMARILY handle the request. */
+    claimsPrimary(ctx: RouteContext): boolean;
+}
+/**
+ * OpenAI-compat backend adapter. Claims a request under exactly the condition
+ * the request handler reroutes on: a configured backend, an OpenAI-shape
+ * request, not force-routed to Claude, and either force-routed to openai or a
+ * recognized GPT-family model.
+ */
+export declare const openaiAdapter: ProviderAdapter;
+/**
+ * Claude adapter — the default owner. Claims anything the openai adapter
+ * doesn't, matching the request handler's fall-through to the template path
+ * (including OpenAI-shape requests with Claude models, which the Claude path
+ * serves via openai→anthropic translation).
+ */
+export declare const claudeAdapter: ProviderAdapter;
+export declare const DEFAULT_ADAPTERS: readonly ProviderAdapter[];
+/**
+ * Resolve the routing decision. Offers the request to adapters in priority
+ * order and takes the first primary claim; the Claude adapter always claims, so
+ * the result is total. The claude→openai pool fallback is layered on top
+ * because it's a cross-adapter relationship (a Claude-primary request that
+ * spills to openai on pool exhaustion), not a primary claim by either side.
+ */
+export declare function route(ctx: RouteContext, adapters?: readonly ProviderAdapter[]): RouteDecision;

package/dist/provider-adapter.js

@@ -0,0 +1,76 @@
+/**
+ * Provider routing seam.
+ *
+ * dario's "which backend owns this request" decision used to live inline in the
+ * request handler as a set of interleaved conditions (path class, provider
+ * prefix, GPT-family model test, the openai-backend reroute guard, the pool
+ * fallback guard). This module consolidates that decision into one place: a
+ * small set of `ProviderAdapter`s and a `route()` function that returns the
+ * primary provider plus any exhaustion fallback.
+ *
+ * Scope is deliberately the DECISION, not the request lifecycle. The Claude
+ * path's pool/template/cch/session/overage machinery stays shared below this
+ * seam — it's infrastructure that happens to serve one provider, not per-
+ * provider behaviour, so pushing it behind an adapter interface would make the
+ * Claude adapter the whole proxy and the OpenAI adapter nearly empty. The seam
+ * that pays for itself is routing + request-shaping; the rest is shared.
+ *
+ * The adapters reuse the same primitive proxy.ts uses (`isOpenAIModel`), so this
+ * is a consolidation of the existing decision, not a re-derivation of it.
+ */
+import { isOpenAIModel } from './openai-backend.js';
+/**
+ * OpenAI-compat backend adapter. Claims a request under exactly the condition
+ * the request handler reroutes on: a configured backend, an OpenAI-shape
+ * request, not force-routed to Claude, and either force-routed to openai or a
+ * recognized GPT-family model.
+ */
+export const openaiAdapter = {
+    id: 'openai',
+    priority: 100,
+    claimsPrimary(ctx) {
+        if (!ctx.hasOpenAIBackend)
+            return false;
+        if (!ctx.isOpenAIPath)
+            return false;
+        if (ctx.forcedProvider === 'claude')
+            return false;
+        return ctx.forcedProvider === 'openai' || isOpenAIModel(ctx.model);
+    },
+};
+/**
+ * Claude adapter — the default owner. Claims anything the openai adapter
+ * doesn't, matching the request handler's fall-through to the template path
+ * (including OpenAI-shape requests with Claude models, which the Claude path
+ * serves via openai→anthropic translation).
+ */
+export const claudeAdapter = {
+    id: 'claude',
+    priority: 0,
+    claimsPrimary() {
+        return true;
+    },
+};
+export const DEFAULT_ADAPTERS = [openaiAdapter, claudeAdapter];
+/**
+ * Resolve the routing decision. Offers the request to adapters in priority
+ * order and takes the first primary claim; the Claude adapter always claims, so
+ * the result is total. The claude→openai pool fallback is layered on top
+ * because it's a cross-adapter relationship (a Claude-primary request that
+ * spills to openai on pool exhaustion), not a primary claim by either side.
+ */
+export function route(ctx, adapters = DEFAULT_ADAPTERS) {
+    const ordered = [...adapters].sort((a, b) => b.priority - a.priority);
+    const primary = ordered.find((a) => a.claimsPrimary(ctx)) ?? claudeAdapter;
+    let fallback = null;
+    let reason = `${primary.id} primary`;
+    if (primary.id === 'claude' &&
+        ctx.poolFallbackModel !== null &&
+        ctx.hasOpenAIBackend &&
+        ctx.isOpenAIPath &&
+        ctx.poolSize > 0) {
+        fallback = 'openai';
+        reason = 'claude primary, openai fallback on pool-exhaustion';
+    }
+    return { provider: primary.id, fallback, reason };
+}

package/dist/proxy.d.ts

@@ -37,6 +37,24 @@ export declare function buildBillingTag(cliVersion: string, cch: string | null):
  * that needs to Just Work.
  */
 export declare function resolveClaudeAlias(model: string): string;
+/**
+ * User-defined model aliases: client-visible name → target model.
+ *
+ * Complements the built-in family shorthands above — those track the model
+ * catalog; these are operator-declared (config `modelAliases`, repeatable
+ * `--model-alias=name=target`, `DARIO_MODEL_ALIASES=name=target,…`) and
+ * resolve FIRST at request time, before provider-prefix parsing, so a
+ * target may carry a prefix (`my-fast` → `openai:gpt-4o-mini`) and
+ * retarget the backend. One step, never recursive: a target that names
+ * another alias is forwarded as-is. Alias names match case-insensitively;
+ * targets forward verbatim. An alias may shadow a real model id or a
+ * built-in shorthand — deliberate, that's how you downgrade every `opus`
+ * call from a client whose picker you don't control.
+ */
+export declare function parseModelAliasSpecs(specs: readonly string[]): Record<string, string>;
+/** Resolve `model` through user aliases. Null = no alias applies (also on
+ *  self-mapping, so a misconfigured `opus=opus` can't loop the caller). */
+export declare function applyModelAlias(model: string | null | undefined, aliases: Record<string, string> | undefined): string | null;
 /**
  * Pick the per-request model override under a forced `--model`.
  *
@@ -52,6 +70,13 @@ export declare function resolveClaudeAlias(model: string): string;
  * change is inert until the operator opts in.
  */
 export declare function selectModelOverride(incomingModel: string, modelOverride: string | null, fastModelOverride: string | null): string | null;
+/**
+ * Rebuild an OpenAI-shape request body with the model swapped to the pool-
+ * fallback target. Null when the body isn't a JSON object — the caller
+ * surfaces the original error instead of forwarding garbage. Exported for
+ * tests; the two call sites are the pool-exhausted dispatch paths.
+ */
+export declare function buildPoolFallbackBody(body: Buffer, fallbackModel: string): Buffer | null;
 export declare function parseProviderPrefix(model: string): {
     provider: 'openai' | 'claude';
     model: string;
@@ -288,6 +313,16 @@ interface ProxyOptions {
      * --strict-tls. dario#77.
      */
     strictTemplate?: boolean;
+    /**
+     * Pool routing strategy. `headroom` (default) spreads new conversations
+     * to the seat with the most headroom; `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 where a
+     * `z-backup` seat stays untouched until `a-main` is actually drained.
+     * Sticky bindings behave identically in both modes. Sourced from
+     * `--pool-strategy` / `DARIO_POOL_STRATEGY` / config `pool.strategy`.
+     */
+    poolStrategy?: string;
     /** Max concurrent in-flight requests. Default 10. dario#80. */
     maxConcurrent?: number;
     /** Max requests buffered waiting for a concurrency slot. Default 128. dario#80. */
@@ -312,6 +347,27 @@ interface ProxyOptions {
      * their output capacity. dario#88 (Hermes compat).
      */
     maxTokens?: number | 'client';
+    /**
+     * Pool-exhausted fallback model (strictly opt-in; off when unset/empty).
+     * When the Claude pool can't serve — selection finds every seat drained
+     * or cooling, or a mid-flight 429 has no peer left — OpenAI-shape
+     * requests (/v1/chat/completions) are forwarded to the configured
+     * openai-compat backend with the model swapped to this value, instead
+     * of surfacing the 429/503. Responses carry `x-dario-pool-fallback`.
+     * Anthropic-shape requests keep the error: dario has no OpenAI→Anthropic
+     * response translation. Inert without a configured backend. Sourced from
+     * `--pool-fallback` / `DARIO_POOL_FALLBACK` / config `poolFallback.model`.
+     */
+    poolFallbackModel?: string;
+    /**
+     * User-defined model aliases, client-visible name (lowercase) → target.
+     * Resolved per request BEFORE provider-prefix parsing (a target may
+     * carry a prefix and retarget the backend) and advertised on
+     * /v1/models. One step, never recursive. See parseModelAliasSpecs.
+     * Sourced from config `modelAliases` < `DARIO_MODEL_ALIASES` <
+     * repeatable `--model-alias=name=target`, merged per-key by the CLI.
+     */
+    modelAliases?: Record<string, string>;
     /**
      * Append-only request log file. One JSON line per completed request,
      * with secrets scrubbed via redactSecrets. Useful for backgrounded

package/dist/proxy.js

@@ -12,14 +12,15 @@ import { darioVersion } from './version.js';
 import { buildCCRequest, applyCcPromptCaching, parseEffortSuffix, reverseMapResponse, createStreamingReverseMapper, orderHeadersForOutbound, isMcpToolName, CC_TEMPLATE, effectiveCacheControl, withForced1hBeta } from './cc-template.js';
 import { stampCch, hasCchSeed } from './cch.js';
 import { describeTemplate, detectDrift, checkCCCompat } from './live-fingerprint.js';
-import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, reconcilePoolAccounts } from './pool.js';
+import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, reconcilePoolAccounts, resolvePoolStrategy } from './pool.js';
 import { Analytics, billingBucketFromClaim, formatUsageLogLine, SUBSCRIPTION_CLAIMS } from './analytics.js';
 import { OverageGuard, buildHaltErrorBody } from './overage-guard.js';
 import { notify as osNotify } from './notify.js';
-import { loadAllAccounts, loadAccount, refreshAccountToken, resyncLoginFromCredentialsIfStale, ensureLoginCredentialsInPool } from './accounts.js';
+import { loadAllAccounts, loadAccount, saveAccount, refreshAccountToken, resyncLoginFromCredentialsIfStale, ensureLoginCredentialsInPool } from './accounts.js';
 import { handleAdminRequest } from './admin-api.js';
 import { createTokenBucket } from './rate-limit.js';
 import { getOpenAIBackend, isOpenAIModel, forwardToOpenAI } from './openai-backend.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';
 import { redactSecrets } from './redact.js';
 import { BAKED_BASE_MODELS, withLongContextVariants, buildOpenAIModelsList, getModelCatalog, getCachedBases, resolveAliasAgainst, prewarmModelCatalog, retryModelCatalogNow, isSuspendedModel } from './model-catalog.js';
@@ -235,6 +236,44 @@ const MODEL_ALIASES = {
 export function resolveClaudeAlias(model) {
     return resolveAliasAgainst(model, getCachedBases()) ?? MODEL_ALIASES[model] ?? model;
 }
+/**
+ * User-defined model aliases: client-visible name → target model.
+ *
+ * Complements the built-in family shorthands above — those track the model
+ * catalog; these are operator-declared (config `modelAliases`, repeatable
+ * `--model-alias=name=target`, `DARIO_MODEL_ALIASES=name=target,…`) and
+ * resolve FIRST at request time, before provider-prefix parsing, so a
+ * target may carry a prefix (`my-fast` → `openai:gpt-4o-mini`) and
+ * retarget the backend. One step, never recursive: a target that names
+ * another alias is forwarded as-is. Alias names match case-insensitively;
+ * targets forward verbatim. An alias may shadow a real model id or a
+ * built-in shorthand — deliberate, that's how you downgrade every `opus`
+ * call from a client whose picker you don't control.
+ */
+export function parseModelAliasSpecs(specs) {
+    const out = {};
+    for (const spec of specs) {
+        const idx = spec.indexOf('=');
+        if (idx <= 0)
+            continue;
+        const name = spec.slice(0, idx).trim().toLowerCase();
+        const target = spec.slice(idx + 1).trim();
+        if (!name || !target)
+            continue;
+        out[name] = target;
+    }
+    return out;
+}
+/** Resolve `model` through user aliases. Null = no alias applies (also on
+ *  self-mapping, so a misconfigured `opus=opus` can't loop the caller). */
+export function applyModelAlias(model, aliases) {
+    if (!aliases || !model)
+        return null;
+    const target = aliases[model.trim().toLowerCase()];
+    if (target === undefined || target === model)
+        return null;
+    return target;
+}
 /**
  * Pick the per-request model override under a forced `--model`.
  *
@@ -268,6 +307,24 @@ const PROVIDER_PREFIXES = {
     claude: 'claude',
     anthropic: 'claude',
 };
+/**
+ * Rebuild an OpenAI-shape request body with the model swapped to the pool-
+ * fallback target. Null when the body isn't a JSON object — the caller
+ * surfaces the original error instead of forwarding garbage. Exported for
+ * tests; the two call sites are the pool-exhausted dispatch paths.
+ */
+export function buildPoolFallbackBody(body, fallbackModel) {
+    try {
+        const parsed = JSON.parse(body.toString());
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return null;
+        parsed.model = fallbackModel;
+        return Buffer.from(JSON.stringify(parsed));
+    }
+    catch {
+        return null;
+    }
+}
 export function parseProviderPrefix(model) {
     const idx = model.indexOf(':');
     if (idx <= 0)
@@ -1035,6 +1092,30 @@ export async function startProxy(opts = {}) {
     if (openaiBackend) {
         console.log(`  OpenAI-compat backend: ${openaiBackend.name} → ${openaiBackend.baseUrl}`);
     }
+    // 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.');
+    }
+    // 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
+    // pickers can offer them.
+    const modelAliases = opts.modelAliases ?? {};
+    if (Object.keys(modelAliases).length > 0) {
+        console.log(`  Model aliases: ${Object.entries(modelAliases).map(([k, v]) => `${k} → ${v}`).join(', ')}`);
+    }
     // Pool-as-primitive (v5.0). The account pool is the one credential model:
     // a plain `dario login` is a pool of one under the reserved `login` alias,
     // and a pool of many is the same path with more members. There is no
@@ -1063,7 +1144,11 @@ export async function startProxy(opts = {}) {
     // POST /admin/login/*, taking effect with no restart (see onAccountsChanged).
     const adminEnabled = process.env.DARIO_ADMIN === '1';
     const accountsList = await loadAllAccounts();
-    const pool = new AccountPool();
+    const poolStrategy = resolvePoolStrategy(opts.poolStrategy);
+    const pool = new AccountPool(poolStrategy);
+    if (poolStrategy !== 'headroom') {
+        console.log(`  Pool strategy: ${poolStrategy} (new conversations fill the alphabetically-first seat, spill at the 2% floor)`);
+    }
     // Per-model rate-limit bucket families seen during this proxy run. First-
     // sight is logged once when verbose so a new Anthropic bucket (e.g. an
     // eventual `7d_opus`) doesn't slip past unnoticed. Pure observability —
@@ -1125,6 +1210,33 @@ export async function startProxy(opts = {}) {
                 accountUuid: acc.accountUuid,
             });
         }
+        // Startup self-heal (dario#790): eagerly refresh any account whose access
+        // token is already expired or within the 45-min refresh window BEFORE the
+        // proxy starts serving. On a container recreate after >8h uptime the
+        // on-disk token is stale; without this the account sits 'expired' in the
+        // pool and every request 401s until the first background tick (up to
+        // 15 min later). A single refresh recovers cleanly as long as the refresh
+        // token is still live — and durably persists the rotated token to disk, so
+        // the *next* recreate loads a fresh credential family too. A dead refresh
+        // token (invalid_grant) just logs and leaves the account expired; the auth
+        // gate below then surfaces it. Skipped in --no-claude-auth mode.
+        if (!opts.noClaudeAuth) {
+            await Promise.all(pool.all().map(async (acc) => {
+                if (acc.expiresAt >= Date.now() + 45 * 60 * 1000)
+                    return;
+                try {
+                    const saved = await loadAccount(acc.alias);
+                    if (!saved)
+                        return;
+                    const refreshed = await refreshAccountToken(saved);
+                    pool.updateTokens(acc.alias, refreshed.accessToken, refreshed.refreshToken, refreshed.expiresAt);
+                    console.error(`[dario] Startup refresh recovered account ${acc.alias} (was expired/expiring).`);
+                }
+                catch (err) {
+                    console.error(`[dario] Startup refresh failed for ${acc.alias}: ${err instanceof Error ? err.message : err}. Account left as-is; auth gate will surface it.`);
+                }
+            }));
+        }
     }
     // Background refresh — keep every account's token fresh without blocking requests
     const refreshInterval = setInterval(async () => {
@@ -1803,7 +1915,12 @@ export async function startProxy(opts = {}) {
             // throws). [1m] variants come from the shared long-context rule, so
             // every family advertises its 1M form the same way.
             const catalog = await getModelCatalog(catalogDeps);
-            const body = JSON.stringify(buildOpenAIModelsList(withLongContextVariants(catalog.bases)));
+            // User aliases are advertised after the real ids so pickers offer
+            // them; already-advertised names aren't duplicated (an alias that
+            // shadows a real id still applies at request time).
+            const advertised = withLongContextVariants(catalog.bases);
+            const aliasNames = Object.keys(modelAliases).filter((n) => !advertised.includes(n));
+            const body = JSON.stringify(buildOpenAIModelsList(advertised.concat(aliasNames)));
             res.writeHead(200, { ...JSON_HEADERS, 'Access-Control-Allow-Origin': corsOrigin });
             res.end(body);
             return;
@@ -1914,26 +2031,36 @@ export async function startProxy(opts = {}) {
                 // pool of one, so every OAuth request selects from the pool.
                 poolAccount = pool.select();
                 if (!poolAccount) {
-                    // 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',
-                        }));
-                    return;
+                    // Pool-exhausted fallback: when armed, the pool HAS accounts (all
+                    // drained / cooling), and the client speaks OpenAI shape, defer —
+                    // the fallback dispatch below the body read re-points the request
+                    // at the 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;
+                    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',
+                            }));
+                        return;
+                    }
                 }
-                accessToken = poolAccount.accessToken;
+                accessToken = poolAccount?.accessToken ?? '';
             }
             // Client-side session key (constant per request) for the rotation registry
             // — consulted at body-build, at the outbound header, and on each mid-request
@@ -1987,6 +2114,19 @@ export async function startProxy(opts = {}) {
                 try {
                     const parsed = JSON.parse(body.toString());
                     parsedBody = parsed;
+                    // User-defined aliases first — before provider-prefix parsing, so
+                    // an alias target carrying a prefix (`my-fast` → `openai:gpt-4o`)
+                    // retargets the backend through the existing machinery below.
+                    {
+                        const clientModel = parsed.model ?? '';
+                        const aliasTarget = applyModelAlias(clientModel, modelAliases);
+                        if (aliasTarget !== null) {
+                            parsed.model = aliasTarget;
+                            body = Buffer.from(JSON.stringify(parsed));
+                            if (verbose)
+                                console.log(`[dario] model alias: ${clientModel} → ${aliasTarget}`);
+                        }
+                    }
                     const rawModel = parsed.model ?? '';
                     const prefix = parseProviderPrefix(rawModel);
                     if (prefix) {
@@ -2042,11 +2182,26 @@ export async function startProxy(opts = {}) {
             // through to the backend instead of running it through the Claude
             // template path. Requests on /v1/messages or with Claude-family models
             // fall through to existing behavior.
-            if (openaiBackend && isOpenAI && forcedProvider !== 'claude' && body.length > 0) {
+            //
+            // The decision itself lives in provider-adapter.ts (`route`): `route(...)
+            // .provider === 'openai'` is exactly the prior inline condition
+            // (`openaiBackend && isOpenAI && forcedProvider !== 'claude' &&
+            // (forcedProvider === 'openai' || isOpenAIModel(model))`), consolidated so
+            // the routing rule is testable and lives in one place. `openaiBackend`
+            // stays in the guard for TS narrowing (route already implies it non-null).
+            if (body.length > 0) {
                 try {
                     const peek = JSON.parse(body.toString());
                     const rawModel = (peek.model || '').toString();
-                    if (rawModel && (forcedProvider === 'openai' || isOpenAIModel(rawModel))) {
+                    const decision = routeProvider({
+                        isOpenAIPath: isOpenAI,
+                        model: rawModel,
+                        forcedProvider,
+                        hasOpenAIBackend: openaiBackend !== null,
+                        poolFallbackModel,
+                        poolSize: pool.size,
+                    });
+                    if (rawModel && openaiBackend && decision.provider === 'openai') {
                         if (verbose) {
                             console.log(`[dario] #${requestCount} ${req.method} ${urlPath} (model: ${rawModel}) → openai backend`);
                         }
@@ -2057,6 +2212,28 @@ export async function startProxy(opts = {}) {
                 }
                 catch { /* not JSON — fall through to existing path */ }
             }
+            // Pool-exhausted fallback dispatch. In OAuth mode poolAccount can only
+            // be null here when the selection above deferred to this path (armed
+            // fallback + drained pool + OpenAI-shape request): swap the model and
+            // forward the client's own body to the openai-compat backend. The
+            // 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) {
+                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',
+                    }));
+                    return;
+                }
+                console.log(`[dario] #${requestCount} pool exhausted — /v1/chat/completions → ${openaiBackend.name} as ${poolFallbackModel}`);
+                requestCount++;
+                await forwardToOpenAI(req, res, fallbackBody, openaiBackend, corsOrigin, { ...SECURITY_HEADERS, 'x-dario-pool-fallback': poolFallbackModel }, UPSTREAM_TIMEOUT_MS, verbose);
+                return;
+            }
             // Parse body once, apply OpenAI translation, model override, and sanitization
             let finalBody = body.length > 0 ? body : undefined;
             let ccToolMap = null;
@@ -2927,6 +3104,22 @@ export async function startProxy(opts = {}) {
                             continue dispatchLoop;
                         }
                     }
+                    // Pool-exhausted fallback: no peer left to fail over to. For an
+                    // OpenAI-shape request with the fallback armed, re-point the
+                    // client's own body at the openai-compat backend instead of
+                    // surfacing the 429. `body` still holds the client's OpenAI-shape
+                    // bytes — the Anthropic translation went into finalBody, never
+                    // back into body. Marked via x-dario-pool-fallback, same as the
+                    // selection-time path.
+                    if (isOpenAI && poolFallbackModel && openaiBackend) {
+                        const fallbackBody = buildPoolFallbackBody(body, poolFallbackModel);
+                        if (fallbackBody) {
+                            console.log(`[dario] #${requestCount} pool exhausted mid-flight (429, no peer) — /v1/chat/completions → ${openaiBackend.name} as ${poolFallbackModel}`);
+                            requestCount++;
+                            await forwardToOpenAI(req, res, fallbackBody, openaiBackend, corsOrigin, { ...SECURITY_HEADERS, 'x-dario-pool-fallback': poolFallbackModel }, UPSTREAM_TIMEOUT_MS, verbose);
+                            return;
+                        }
+                    }
                     const errBody = await upstream.text().catch(() => '');
                     const enriched = enrich429(errBody, upstream.headers);
                     const responseHeaders = {
@@ -3536,6 +3729,38 @@ export async function startProxy(opts = {}) {
     // account periodic refresh that lived here is gone with the single-account
     // path — refreshing credentials.json alongside the pool would double-refresh
     // a shared lineage and trip reuse-detection (see the presence-loop note).
+    // Flush the freshest in-memory pool tokens to disk on shutdown (dario#790,
+    // belt-and-braces alongside persist-on-refresh). If a background refresh
+    // rotated a token seconds before SIGTERM, this guarantees the rotated token
+    // is on disk before the process exits — so the container recreate that
+    // usually follows a SIGTERM (autodeploy) loads a live credential family
+    // instead of a rotated-away one. Only writes when the in-memory token is
+    // newer than what's on disk (freshest-wins), preserving the on-disk scopes /
+    // identity; a stale in-memory copy never clobbers a fresher disk write.
+    let flushingTokens = false;
+    const flushPoolTokens = async () => {
+        if (flushingTokens || opts.noClaudeAuth)
+            return;
+        flushingTokens = true;
+        await Promise.all(pool.all().map(async (acc) => {
+            try {
+                const disk = await loadAccount(acc.alias);
+                // Nothing on disk to merge scopes/identity from, or disk is already
+                // at least as fresh — skip (avoids clobbering a concurrent writer).
+                if (!disk)
+                    return;
+                if (disk.expiresAt >= acc.expiresAt)
+                    return;
+                await saveAccount({
+                    ...disk,
+                    accessToken: acc.accessToken,
+                    refreshToken: acc.refreshToken,
+                    expiresAt: acc.expiresAt,
+                });
+            }
+            catch { /* best-effort flush — never block shutdown on it */ }
+        }));
+    };
     // Graceful shutdown
     const shutdown = () => {
         console.log('\n[dario] Shutting down...');
@@ -3543,8 +3768,13 @@ export async function startProxy(opts = {}) {
         clearInterval(refreshInterval);
         if (logFileStream)
             logFileStream.end();
-        server.close(() => process.exit(0));
-        // Force exit after 5s if connections don't close
+        // Flush tokens first (best-effort, bounded), then close the server. The
+        // flush is fire-and-forget under the same 5s force-exit guard below so a
+        // hung fsync can't wedge shutdown.
+        void flushPoolTokens().finally(() => {
+            server.close(() => process.exit(0));
+        });
+        // Force exit after 5s if connections (or the flush) don't complete.
         setTimeout(() => process.exit(0), 5000).unref();
     };
     process.on('SIGINT', shutdown);

package/dist/tui/tabs/config.js

@@ -38,6 +38,7 @@ const FIELDS = [
     { path: 'thinkTime.maxMs', label: 'Think-time cap (ms)', type: 'number', hint: 'upper bound for the whole formula' },
     { path: 'sessionStart.minMs', label: 'Session-start min', type: 'number', hint: 'first-request delay floor' },
     { path: 'sessionStart.jitterMs', label: 'Session-start jitter', type: 'number' },
+    { path: 'pool.strategy', label: 'Pool strategy', type: 'string', hint: '"headroom" (default) or "fill-first"' },
     // ── Overage-guard (v4.1, dario#288) ─────────────────────────
     { path: 'overageGuard.enabled', label: 'Overage-guard', type: 'bool', hint: 'halt proxy on any representative-claim=overage' },
     { path: 'overageGuard.behavior', label: 'Overage behavior', type: 'string', hint: '"halt" (default) or "warn"' },
@@ -255,6 +256,7 @@ function commitEdit(state) {
  */
 const STRING_ENUMS = {
     'overageGuard.behavior': ['halt', 'warn'],
+    'pool.strategy': ['headroom', 'fill-first'],
 };
 function doSave(state) {
     try {