@askalf/dario 5.2.4 → 5.2.6

package/README.md

@@ -10,6 +10,7 @@
   <a href="https://github.com/askalf/dario/actions/workflows/ci.yml"><img src="https://github.com/askalf/dario/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://github.com/askalf/dario/actions/workflows/codeql.yml"><img src="https://github.com/askalf/dario/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/askalf/dario"><img src="https://img.shields.io/ossf-scorecard/github.com/askalf/dario?label=OpenSSF%20Scorecard&color=6f42c1" alt="OpenSSF Scorecard"></a>
+  <a href="https://www.bestpractices.dev/projects/13638"><img src="https://www.bestpractices.dev/projects/13638/badge" alt="OpenSSF Best Practices"></a>
   <a href="https://github.com/askalf/dario/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/@askalf/dario?color=6f42c1" alt="License"></a>
   <a href="https://www.npmjs.com/package/@askalf/dario"><img src="https://img.shields.io/npm/dm/@askalf/dario?color=6f42c1" alt="Downloads"></a>
   <a href="https://x.com/ask_alf"><img src="https://img.shields.io/badge/follow-@ask__alf-1da1f2?style=flat-square" alt="Follow on X"></a>

package/dist/cc-template.d.ts

@@ -475,8 +475,27 @@ export declare const CC_CACHE_CONTROL: CacheControl;
  * without the enabling beta is not a shape real CC produces, and forwarding
  * half of it risks an upstream 400. DARIO_CACHE_TTL_5M=1 restores the
  * pre-fix behavior (always bare 5m) as the operator escape hatch.
+ *
+ * DARIO_CACHE_TTL_1H=1 is the opposite override: force `ttl:'1h'` on every
+ * breakpoint regardless of what the client sent, for a client that can't
+ * emit the 1h stamp itself (an SDK/agent harness that only stamps bare 5m —
+ * dario#678). The proxy adds the enabling `extended-cache-ttl-` beta to the
+ * outbound set so the 1h is honored. Deliberate override of the mirror
+ * guardrail: 1h cache *writes* bill ~2× the 5m rate, so it only wins when
+ * idle gaps routinely exceed the 5-minute window; on rapid back-to-back
+ * turns it costs more. 5M takes precedence if both are set.
  */
 export declare function effectiveCacheControl(clientBody: Record<string, unknown>, clientBeta?: string): CacheControl;
+/** The anthropic-beta flag that enables the 1-hour prompt-cache TTL. */
+export declare const EXTENDED_CACHE_TTL_BETA = "extended-cache-ttl-2025-04-11";
+/**
+ * When DARIO_CACHE_TTL_1H forces the 1h stamp, the outbound beta set must also
+ * carry `extended-cache-ttl-` or Anthropic ignores the ttl. Add it (idempotent)
+ * unless DARIO_CACHE_TTL_5M overrides (5M wins, matching effectiveCacheControl).
+ * Pure — `env` is injectable for tests. Returns `beta` unchanged when the flag
+ * is off or the beta is already present.
+ */
+export declare function withForced1hBeta(beta: string, env?: Record<string, string | undefined>): string;
 /**
  * Place CC-style prompt-cache breakpoints on the conversation. The system
  * prompt is already cached at build time (2 system breakpoints); this adds a

package/dist/cc-template.js

@@ -1260,10 +1260,21 @@ export const CC_CACHE_CONTROL = { type: 'ephemeral' };
  * without the enabling beta is not a shape real CC produces, and forwarding
  * half of it risks an upstream 400. DARIO_CACHE_TTL_5M=1 restores the
  * pre-fix behavior (always bare 5m) as the operator escape hatch.
+ *
+ * DARIO_CACHE_TTL_1H=1 is the opposite override: force `ttl:'1h'` on every
+ * breakpoint regardless of what the client sent, for a client that can't
+ * emit the 1h stamp itself (an SDK/agent harness that only stamps bare 5m —
+ * dario#678). The proxy adds the enabling `extended-cache-ttl-` beta to the
+ * outbound set so the 1h is honored. Deliberate override of the mirror
+ * guardrail: 1h cache *writes* bill ~2× the 5m rate, so it only wins when
+ * idle gaps routinely exceed the 5-minute window; on rapid back-to-back
+ * turns it costs more. 5M takes precedence if both are set.
  */
 export function effectiveCacheControl(clientBody, clientBeta) {
     if (process.env['DARIO_CACHE_TTL_5M'] === '1')
         return CC_CACHE_CONTROL;
+    if (process.env['DARIO_CACHE_TTL_1H'] === '1')
+        return { type: 'ephemeral', ttl: '1h' };
     if (!clientBeta || !clientBeta.includes('extended-cache-ttl-'))
         return CC_CACHE_CONTROL;
     const scan = (blocks) => {
@@ -1289,6 +1300,22 @@ export function effectiveCacheControl(clientBody, clientBeta) {
     }
     return CC_CACHE_CONTROL;
 }
+/** The anthropic-beta flag that enables the 1-hour prompt-cache TTL. */
+export const EXTENDED_CACHE_TTL_BETA = 'extended-cache-ttl-2025-04-11';
+/**
+ * When DARIO_CACHE_TTL_1H forces the 1h stamp, the outbound beta set must also
+ * carry `extended-cache-ttl-` or Anthropic ignores the ttl. Add it (idempotent)
+ * unless DARIO_CACHE_TTL_5M overrides (5M wins, matching effectiveCacheControl).
+ * Pure — `env` is injectable for tests. Returns `beta` unchanged when the flag
+ * is off or the beta is already present.
+ */
+export function withForced1hBeta(beta, env = process.env) {
+    if (env['DARIO_CACHE_TTL_1H'] !== '1' || env['DARIO_CACHE_TTL_5M'] === '1')
+        return beta;
+    if (beta.split(',').includes(EXTENDED_CACHE_TTL_BETA))
+        return beta;
+    return beta.length > 0 ? beta + ',' + EXTENDED_CACHE_TTL_BETA : EXTENDED_CACHE_TTL_BETA;
+}
 /**
  * Place CC-style prompt-cache breakpoints on the conversation. The system
  * prompt is already cached at build time (2 system breakpoints); this adds a

package/dist/cli.js

@@ -22,7 +22,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import { startAutoOAuthFlow, startManualOAuthFlow, detectHeadlessEnvironment, getStatus, refreshTokens, loadCredentials } from './oauth.js';
-import { startProxy, sanitizeError } from './proxy.js';
+import { startProxy, sanitizeError, parseModelAliasSpecs } from './proxy.js';
 import { VALID_EFFORT_VALUES } from './cc-template.js';
 import { listAccountAliases, loadAllAccounts, addAccountViaOAuth, addAccountViaManualOAuth, addAccountFromKeychain, KeychainImportError, removeAccount, ensureLoginCredentialsInPool, MIGRATED_LOGIN_ALIAS } from './accounts.js';
 import { listBackends, saveBackend, removeBackend } from './openai-backend.js';
@@ -428,6 +428,21 @@ async function proxy() {
         ?? parsePositiveIntEnv(process.env['DARIO_MAX_QUEUED']);
     const queueTimeoutMs = parsePositiveIntFlag('--queue-timeout=')
         ?? parsePositiveIntEnv(process.env['DARIO_QUEUE_TIMEOUT_MS']);
+    // --pool-strategy=headroom|fill-first — where UNBOUND (new) conversations
+    // land. `headroom` (default) 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 — primary/backup semantics,
+    // alias naming (`1-main`, `2-overflow`) is the ordering knob. Sticky
+    // bindings behave identically under both.
+    const poolStrategyFromFlag = args.find((a) => a.startsWith('--pool-strategy='))?.split('=')[1];
+    if (poolStrategyFromFlag !== undefined
+        && poolStrategyFromFlag !== 'headroom' && poolStrategyFromFlag !== 'fill-first') {
+        console.error(`[dario] Invalid --pool-strategy "${poolStrategyFromFlag}". Must be headroom or fill-first.`);
+        process.exit(1);
+    }
+    const poolStrategy = poolStrategyFromFlag
+        ?? process.env['DARIO_POOL_STRATEGY']
+        ?? fileCfg.pool?.strategy;
     // --effort=low|medium|high|xhigh|ultracode|max|client — pin the outbound
     // output_config.effort (dario#87). Default (unset) forwards the client's
     // own effort — it's a user knob, real CC wires whatever the user tuned —
@@ -503,6 +518,30 @@ async function proxy() {
     // billable-filter. Empty values are dropped. Falls back to
     // DARIO_PASSTHROUGH_BETAS env var.
     const passthroughBetas = parsePassthroughBetasFlag(args, process.env['DARIO_PASSTHROUGH_BETAS']);
+    // --pool-fallback=<model> / DARIO_POOL_FALLBACK / config poolFallback.model
+    // — strictly opt-in. When the Claude pool can't serve, OpenAI-shape
+    // requests are re-pointed at the configured openai-compat backend as
+    // <model> (response marked x-dario-pool-fallback) instead of surfacing
+    // the 429/503. `--pool-fallback=` (empty value) disables, overriding
+    // env + config — same clear-the-default shape as --passthrough-betas=.
+    const poolFallbackFromFlag = args.find((a) => a.startsWith('--pool-fallback='))?.split('=').slice(1).join('=');
+    const poolFallbackModel = (poolFallbackFromFlag
+        ?? process.env['DARIO_POOL_FALLBACK']
+        ?? fileCfg.poolFallback?.model
+        ?? '').trim() || undefined;
+    // --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
+    // time before provider-prefix parsing; a target may carry a prefix
+    // (`--model-alias=my-fast=openai:gpt-4o-mini`) to retarget the backend.
+    const modelAliases = {
+        ...(fileCfg.modelAliases ?? {}),
+        ...parseModelAliasSpecs((process.env['DARIO_MODEL_ALIASES'] ?? '')
+            .split(',').map((s) => s.trim()).filter((s) => s.length > 0)),
+        ...parseModelAliasSpecs(args
+            .filter((a) => a.startsWith('--model-alias='))
+            .map((a) => a.slice('--model-alias='.length))),
+    };
     // --overage-guard / --no-overage-guard / DARIO_OVERAGE_GUARD=off|on (v4.1)
     // When any upstream response carries `representative-claim: overage`,
     // halt the proxy: every new request returns 503 with an Anthropic-shaped
@@ -577,7 +616,7 @@ async function proxy() {
         console.error(`[dario] Override (not recommended): pass --unsafe-no-auth if you have out-of-band network controls and accept the risk.`);
         process.exit(1);
     }
-    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, effort, maxTokens, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat });
+    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, poolStrategy, effort, maxTokens, poolFallbackModel, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat });
 }
 /**
  * Parse `--system-prompt=<verbatim|partial|aggressive|filepath>` (or the
@@ -1355,6 +1394,36 @@ async function help() {
                              dario returns 504 "queue-timeout"
                              (default: 60000).
                              Env: DARIO_QUEUE_TIMEOUT_MS. (dario#80)
+    --pool-strategy=<headroom|fill-first>
+                             Where new conversations land in a multi-
+                             account pool. headroom (default) 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.
+                             Sticky bindings are unaffected.
+                             Env: DARIO_POOL_STRATEGY.
+    --pool-fallback=<model>  When every pool seat is drained or cooling,
+                             forward OpenAI-shape requests to the
+                             configured openai-compat backend as <model>
+                             instead of surfacing the 429/503. Response
+                             carries x-dario-pool-fallback. Anthropic-
+                             shape requests keep the error (no reverse
+                             response translation). Requires an
+                             openai-compat backend. Empty value disables.
+                             Env: DARIO_POOL_FALLBACK. Config:
+                             poolFallback.model.
+    --model-alias=<name=target>
+                             User-defined model alias, repeatable.
+                             Applied to the client's model name before
+                             provider-prefix parsing, so the target may
+                             carry a prefix to retarget the backend
+                             (--model-alias=my-fast=openai:gpt-4o-mini).
+                             Advertised on /v1/models. Names match
+                             case-insensitively; one step, never
+                             recursive. Env: DARIO_MODEL_ALIASES=
+                             name=target,name2=target2. Config:
+                             modelAliases.
     --effort=<low|medium|high|xhigh|ultracode|max|client>
                              Pin the outbound output_config.effort on
                              non-haiku requests, overriding the

package/dist/config-file.d.ts

@@ -80,8 +80,34 @@ export interface DarioConfig {
         maxQueued?: number | null;
         timeoutMs?: number | null;
     };
+    pool?: {
+        /**
+         * `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, alias order is the knob.
+         */
+        strategy?: 'headroom' | 'fill-first';
+    };
     effort?: string | null;
     maxTokens?: number | 'client' | null;
+    /**
+     * Pool-exhausted fallback. When `model` is a non-empty string and an
+     * openai-compat backend is configured, OpenAI-shape requests that the
+     * Claude pool can't serve are forwarded to that backend as `model`
+     * (response marked `x-dario-pool-fallback`) instead of surfacing the
+     * 429/503. Null/absent = off.
+     */
+    poolFallback?: {
+        model?: string | null;
+    };
+    /**
+     * User-defined model aliases: client-visible name → target model.
+     * Resolved at request time before provider-prefix parsing, so a target
+     * may carry a prefix (`"my-fast": "openai:gpt-4o-mini"`). Names are
+     * matched case-insensitively; one step, never recursive.
+     */
+    modelAliases?: Record<string, string>;
     passthroughBetas?: string[];
     systemPrompt?: string | null;
     preserveOrchestrationTags?: boolean;

package/dist/config-file.js

@@ -65,8 +65,11 @@ export function defaultConfig() {
             perClient: false,
         },
         queue: { maxConcurrent: null, maxQueued: null, timeoutMs: null },
+        pool: { strategy: 'headroom' },
         effort: null,
         maxTokens: null,
+        poolFallback: { model: null },
+        modelAliases: {},
         passthroughBetas: [],
         systemPrompt: null,
         preserveOrchestrationTags: false,
@@ -303,6 +306,18 @@ function sanitize(parsed) {
             }
         }
     }
+    if (isPlainObject(parsed.pool)) {
+        out.pool = {};
+        if (parsed.pool.strategy === 'headroom' || parsed.pool.strategy === 'fill-first') {
+            out.pool.strategy = parsed.pool.strategy;
+        }
+    }
+    if (isPlainObject(parsed.poolFallback)) {
+        out.poolFallback = {};
+        if (parsed.poolFallback.model === null || typeof parsed.poolFallback.model === 'string') {
+            out.poolFallback.model = parsed.poolFallback.model;
+        }
+    }
     const effort = pickStringOrNull('effort');
     if (effort !== undefined)
         out.effort = effort;
@@ -316,6 +331,19 @@ function sanitize(parsed) {
         if (n !== undefined)
             out.maxTokens = n;
     }
+    if (isPlainObject(parsed.modelAliases)) {
+        const aliases = {};
+        for (const [k, v] of Object.entries(parsed.modelAliases)) {
+            if (typeof v !== 'string')
+                continue;
+            const name = k.trim().toLowerCase();
+            const target = v.trim();
+            if (!name || !target)
+                continue;
+            aliases[name] = target;
+        }
+        out.modelAliases = aliases;
+    }
     if (Array.isArray(parsed.passthroughBetas)) {
         out.passthroughBetas = parsed.passthroughBetas
             .filter((x) => typeof x === 'string');

package/dist/live-fingerprint.d.ts

@@ -282,7 +282,7 @@ export declare function _resetInstalledVersionProbeForTest(): void;
  */
 export declare const SUPPORTED_CC_RANGE: {
     readonly min: "1.0.0";
-    readonly maxTested: "2.1.211";
+    readonly maxTested: "2.1.212";
 };
 /**
  * Compare two dotted-numeric version strings. Returns negative if `a<b`,

package/dist/live-fingerprint.js

@@ -806,7 +806,7 @@ export function _resetInstalledVersionProbeForTest() {
  */
 export const SUPPORTED_CC_RANGE = {
     min: '1.0.0',
-    maxTested: '2.1.211',
+    maxTested: '2.1.212',
 };
 /**
  * Compare two dotted-numeric version strings. Returns negative if `a<b`,

package/dist/pool.d.ts

@@ -75,6 +75,32 @@ export interface PoolStatus {
     bestAccount: string;
     queued: number;
 }
+/**
+ * Pool routing strategy.
+ *
+ * `headroom` (default) — every selection picks the account with the most
+ * headroom, spreading new conversations across all seats.
+ *
+ * `fill-first` — concentrate new conversations on the lexicographically-
+ * first eligible account (by alias) until its headroom drops to the 2%
+ * floor, then spill to the next. Two things headroom spreading can't give
+ * you: primary/backup semantics (a `z-backup` seat stays untouched until
+ * `a-main` is actually drained), and cache concentration (every fresh
+ * conversation lands where the prompt-cache pressure already is, keeping
+ * the spill seat's windows fully fresh for when they're needed). Alias
+ * order is the operator's knob — name seats `1-main` / `2-overflow` to
+ * pick the fill order. Sticky bindings behave identically in both modes;
+ * strategy only decides where UNBOUND (new) conversations land.
+ */
+export type PoolStrategy = 'headroom' | 'fill-first';
+/**
+ * Resolve the pool strategy from an explicit value (CLI flag / config file,
+ * already precedence-merged by the caller) with `DARIO_POOL_STRATEGY` as
+ * the env fallback. Unrecognized values fall through — a typo behaves like
+ * the default rather than crashing startup, matching the other resolvers
+ * in this codebase (see resolveSessionRotationConfig).
+ */
+export declare function resolvePoolStrategy(explicit?: string | null, env?: NodeJS.ProcessEnv): PoolStrategy;
 /** Parse an Anthropic response's rate-limit headers into a snapshot. */
 export declare function parseRateLimits(headers: Headers): RateLimitSnapshot;
 /**
@@ -105,6 +131,7 @@ export declare function modelFamily(modelId: string | null | undefined): string
  */
 export declare function computeHeadroom(snapshot: RateLimitSnapshot, family?: string | null): number;
 export declare class AccountPool {
+    private readonly strategy;
     private accounts;
     private queue;
     private queueMaxSize;
@@ -112,6 +139,7 @@ export declare class AccountPool {
     private drainTimer;
     private sticky;
     private lastStickyCleanup;
+    constructor(strategy?: PoolStrategy);
     add(alias: string, opts: {
         accessToken: string;
         refreshToken: string;

package/dist/pool.js

@@ -54,6 +54,23 @@ export function isInAuthCooldown(account, now = Date.now()) {
     const cooldown = authCooldownMs(account.consecutiveAuthFailures);
     return now - account.lastAuthFailureAt < cooldown;
 }
+/**
+ * Resolve the pool strategy from an explicit value (CLI flag / config file,
+ * already precedence-merged by the caller) with `DARIO_POOL_STRATEGY` as
+ * the env fallback. Unrecognized values fall through — a typo behaves like
+ * the default rather than crashing startup, matching the other resolvers
+ * in this codebase (see resolveSessionRotationConfig).
+ */
+export function resolvePoolStrategy(explicit, env = process.env) {
+    for (const c of [explicit, env.DARIO_POOL_STRATEGY]) {
+        if (typeof c !== 'string')
+            continue;
+        const s = c.trim().toLowerCase();
+        if (s === 'headroom' || s === 'fill-first')
+            return s;
+    }
+    return 'headroom';
+}
 /**
  * Match `anthropic-ratelimit-unified-7d_<family>-utilization`. Generic on
  * `<family>` so a future `7d_opus` / `7d_haiku` (or anything Anthropic
@@ -166,7 +183,23 @@ function pickMaxHeadroom(accounts, family) {
     }
     return best;
 }
+// Fill-first pick: lexicographically-first eligible account still above the
+// headroom floor. Alias order (not insertion order) — accounts load from a
+// readdir whose order the OS doesn't guarantee, and the operator can control
+// alias names but not readdir. Returns null when every candidate is at/below
+// the floor so the caller can fall back to max-headroom.
+function pickFillFirst(accounts, family) {
+    let best = null;
+    for (const a of accounts) {
+        if (best !== null && a.alias >= best.alias)
+            continue;
+        if (computeHeadroom(a.rateLimit, family) > POOL_HEADROOM_FLOOR)
+            best = a;
+    }
+    return best;
+}
 export class AccountPool {
+    strategy;
     accounts = new Map();
     queue = [];
     queueMaxSize = 50;
@@ -175,6 +208,9 @@ export class AccountPool {
     sticky = new Map();
     // Amortize the O(n) sticky TTL/orphan sweep — timestamp of the last run.
     lastStickyCleanup = 0;
+    constructor(strategy = 'headroom') {
+        this.strategy = strategy;
+    }
     add(alias, opts) {
         const existing = this.accounts.get(alias);
         this.accounts.set(alias, {
@@ -257,6 +293,14 @@ export class AccountPool {
             a.expiresAt > now + 30_000 &&
             !isInAuthCooldown(a, now));
         if (eligible.length > 0) {
+            if (this.strategy === 'fill-first') {
+                const first = pickFillFirst(eligible, family);
+                if (first)
+                    return first;
+                // Every eligible account is at/below the floor — the terminal state
+                // both strategies share. Fall through to max-headroom so the caller
+                // still gets the least-drained account instead of null.
+            }
             return pickMaxHeadroom(eligible, family);
         }
         // All accounts exhausted — return the one with the earliest reset.
@@ -374,6 +418,15 @@ export class AccountPool {
             a.expiresAt > now + 30_000 &&
             !isInAuthCooldown(a, now));
         if (eligible.length > 0) {
+            // Fill-first failover keeps the fill order: the next account tried
+            // after a 429 is the next alias in line, not the max-headroom seat —
+            // otherwise a single failover would defeat the concentration the
+            // strategy exists to provide.
+            if (this.strategy === 'fill-first') {
+                const first = pickFillFirst(eligible, family);
+                if (first)
+                    return first;
+            }
             return pickMaxHeadroom(eligible, family);
         }
         if (candidates.length > 0) {

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

@@ -9,10 +9,10 @@ import { arch, platform } from 'node:process';
 import { getAccessToken, getStatus } from './oauth.js';
 import { buildHealthResponse, derivePoolStatus, shouldDiscloseHealthInternals } from './health-response.js';
 import { darioVersion } from './version.js';
-import { buildCCRequest, applyCcPromptCaching, parseEffortSuffix, reverseMapResponse, createStreamingReverseMapper, orderHeadersForOutbound, isMcpToolName, CC_TEMPLATE, effectiveCacheControl } from './cc-template.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';
@@ -235,6 +235,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 +306,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 +1091,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 +1143,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 —
@@ -1803,7 +1887,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 +2003,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 +2086,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) {
@@ -2057,6 +2169,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;
@@ -2399,6 +2533,12 @@ export async function startProxy(opts = {}) {
                     if (toAdd.length > 0)
                         beta += ',' + toAdd.join(',');
                 }
+                // Forced 1h cache (DARIO_CACHE_TTL_1H): effectiveCacheControl stamps
+                // ttl:'1h', but the 1h is only honored WITH the extended-cache-ttl
+                // beta — add it here (no-op unless the flag is set). If the upstream
+                // 400s the flag on a non-sub account, the rejected-set strip below
+                // drops it on the retry.
+                beta = withForced1hBeta(beta);
                 // Strip any beta flags the upstream has previously rejected on this
                 // account so we don't re-pay the 400 round-trip (dario#42 afk-mode
                 // fallout: captured templates carry tier-gated flags whose availability
@@ -2921,6 +3061,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 = {

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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "5.2.4",
+  "version": "5.2.6",
   "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": {