@askalf/dario 6.12.7 → 6.12.8

package/dist/cli.js

@@ -536,8 +536,9 @@ async function proxy() {
         ?? fileCfg.pool?.strategy;
     // --pool-headroom-floor=<ratio|percent> — the headroom at/below which a seat
     // counts as drained: sticky sessions rebind off it and new conversations
-    // skip it. Default 2%; dario#1333 asked to leave a seat alone at 95% used
-    // rather than ride it into the 429.
+    // skip it. Setting the floor makes it a hard stop; the implicit 2% default
+    // stays a routing preference. dario#1333 asked to leave a seat alone at 95%
+    // used rather than ride it into the 429.
     const poolHeadroomFloorFromFlag = args.find((a) => a.startsWith('--pool-headroom-floor='))?.split('=')[1];
     if (poolHeadroomFloorFromFlag !== undefined && parsePoolHeadroomFloor(poolHeadroomFloorFromFlag) === null) {
         console.error(`[dario] Invalid --pool-headroom-floor "${poolHeadroomFloorFromFlag}". Use a ratio or percent between 2% and 50% (e.g. 0.05 or 5%).`);
@@ -2203,8 +2204,9 @@ async function help() {
     --pool-headroom-floor=<ratio|percent>
                              Headroom at or below which a seat counts as
                              drained: a sticky session rebinds off it and
-                             new conversations skip it. 0.05 or 5%;
-                             default 2%, max 50%. Use it when your seats
+                             new conversations skip it. Setting this makes
+                             the floor a hard stop. 0.05 or 5%; implicit
+                             default 2% is a preference, max 50%. Use it when your seats
                              answer with API errors in the last percent
                              of a window (dario#1333).
                              Env: DARIO_POOL_HEADROOM_FLOOR;

package/dist/doctor-core.js

@@ -1139,7 +1139,7 @@ export async function runChecks(opts = {}) {
                     // default: `new AccountPool()` here always predicted a max-headroom
                     // pick, which is the wrong seat on a fill-first pool.
                     const routing = configuredPoolRouting(loadConfig().config.pool);
-                    const pool = new AccountPool(routing.strategy, routing.headroomFloor);
+                    const pool = new AccountPool(routing.strategy, routing.headroomFloorExplicit ? routing.headroomFloor : undefined);
                     for (const acc of loaded) {
                         pool.add(acc.alias, {
                             accessToken: acc.accessToken,

package/dist/pool.d.ts

@@ -437,6 +437,7 @@ export declare function configuredPoolRouting(file: {
 } | undefined, env?: NodeJS.ProcessEnv): {
     strategy: PoolStrategy;
     headroomFloor: number;
+    headroomFloorExplicit: boolean;
 };
 /**
  * Which wire buckets bind which model family, when the wire does not say it
@@ -602,8 +603,6 @@ export declare function resolvePoolHeadroomFloor(explicit?: string | number | nu
 export declare function seatExpiry(account: PoolAccount, now?: number): number;
 export declare class AccountPool {
     readonly strategy: PoolStrategy;
-    /** Headroom at/below which a seat counts as drained — see DEFAULT_POOL_HEADROOM_FLOOR. */
-    readonly headroomFloor: number;
     private accounts;
     private queue;
     private queueMaxSize;
@@ -611,9 +610,11 @@ export declare class AccountPool {
     private drainTimer;
     private sticky;
     private lastStickyCleanup;
-    constructor(strategy?: PoolStrategy, 
     /** Headroom at/below which a seat counts as drained — see DEFAULT_POOL_HEADROOM_FLOOR. */
-    headroomFloor?: number);
+    readonly headroomFloor: number;
+    /** Only an explicitly configured floor is a hard stop; the implicit 2% remains a preference. */
+    readonly hardHeadroomFloor: boolean;
+    constructor(strategy?: PoolStrategy, headroomFloor?: number);
     add(alias: string, opts: {
         accessToken: string;
         refreshToken: string;
@@ -729,6 +730,8 @@ export declare class AccountPool {
     adoptSnapshot(alias: string, snapshot: RateLimitSnapshot, rejected: boolean, from: string): boolean;
     updateTokens(alias: string, accessToken: string, refreshToken: string, expiresAt: number): void;
     get(alias: string): PoolAccount | undefined;
+    /** Whether a preferred (but not pinned) seat may bypass normal pool ordering. */
+    canPrefer(account: PoolAccount, now?: number, family?: string | null): boolean;
     all(): PoolAccount[];
     status(): PoolStatus;
     /**

package/dist/pool.js

@@ -453,9 +453,11 @@ export function describePoolStrategy(strategy, floor = DEFAULT_POOL_HEADROOM_FLO
  * CLI flag, which only the running process knows (GET /status reports it).
  */
 export function configuredPoolRouting(file, env = process.env) {
+    const floorCandidate = env.DARIO_POOL_HEADROOM_FLOOR ?? file?.headroomFloor;
     return {
         strategy: resolvePoolStrategy(env.DARIO_POOL_STRATEGY ?? file?.strategy, env),
-        headroomFloor: resolvePoolHeadroomFloor(env.DARIO_POOL_HEADROOM_FLOOR ?? file?.headroomFloor, env),
+        headroomFloor: resolvePoolHeadroomFloor(floorCandidate, env),
+        headroomFloorExplicit: parsePoolHeadroomFloor(floorCandidate) !== null,
     };
 }
 /**
@@ -834,11 +836,56 @@ function pickMaxHeadroom(accounts, family) {
     }
     return best;
 }
+function isAboveHeadroomFloor(headroom, floor) {
+    return headroom - floor > Number.EPSILON;
+}
+/**
+ * When a below-floor reading can retire without an upstream probe, return the
+ * first relevant reset in epoch ms. Null means at least one bucket keeping the
+ * seat below the floor has no future reset, so one request must refresh it.
+ */
+function floorParkedUntil(snapshot, family, floor, now) {
+    const rl = expireElapsedWindow(snapshot, now);
+    const limiting = (util) => !isAboveHeadroomFloor(1 - util, floor);
+    const resets = [];
+    if (limiting(rl.util5h)) {
+        const reset = rl.claim === 'five_hour' ? rl.reset * 1000 : 0;
+        if (reset <= now)
+            return null;
+        resets.push(reset);
+    }
+    if (limiting(rl.util7d)) {
+        const reset = (rl.reset7d ?? 0) * 1000 > now
+            ? (rl.reset7d ?? 0) * 1000
+            : rl.claim.startsWith('seven_day') ? rl.reset * 1000 : 0;
+        if (reset <= now)
+            return null;
+        resets.push(reset);
+    }
+    if (family) {
+        for (const bucket of bucketsBindingFamily(rl, family)) {
+            const util = rl.perModel7d[bucket];
+            if (util === undefined || !limiting(util))
+                continue;
+            const reset = (rl.reset7d ?? 0) * 1000 > now
+                ? (rl.reset7d ?? 0) * 1000
+                : rl.claim.startsWith('seven_day') ? rl.reset * 1000 : 0;
+            if (reset <= now)
+                return null;
+            resets.push(reset);
+        }
+    }
+    return resets.length > 0 ? Math.min(...resets) : null;
+}
+function pickFloorProbe(accounts, family, floor, now) {
+    const stale = accounts.filter(a => floorParkedUntil(a.rateLimit, family, floor, now) === null);
+    return stale.length > 0 ? pickMaxHeadroom(stale, family) : null;
+}
 // 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.
+// the floor.
 /**
  * The 7-day reset `expiring-first` orders by, in epoch ms: the seat's own
  * reading while it is still ahead of `now`, else +Infinity (never read, or the
@@ -851,7 +898,7 @@ export function seatExpiry(account, now = Date.now()) {
 function pickExpiringFirst(accounts, family, floor = DEFAULT_POOL_HEADROOM_FLOOR, now = Date.now()) {
     const order = [...accounts].sort((a, b) => (seatExpiry(a, now) - seatExpiry(b, now)) || (a.alias < b.alias ? -1 : a.alias > b.alias ? 1 : 0));
     for (const a of order) {
-        if (computeHeadroom(a.rateLimit, family) > floor)
+        if (isAboveHeadroomFloor(computeHeadroom(a.rateLimit, family), floor))
             return a;
     }
     return null;
@@ -861,14 +908,13 @@ function pickFillFirst(accounts, family, floor = DEFAULT_POOL_HEADROOM_FLOOR) {
     for (const a of accounts) {
         if (best !== null && a.alias >= best.alias)
             continue;
-        if (computeHeadroom(a.rateLimit, family) > floor)
+        if (isAboveHeadroomFloor(computeHeadroom(a.rateLimit, family), floor))
             best = a;
     }
     return best;
 }
 export class AccountPool {
     strategy;
-    headroomFloor;
     accounts = new Map();
     queue = [];
     queueMaxSize = 50;
@@ -877,11 +923,14 @@ export class AccountPool {
     sticky = new Map();
     // Amortize the O(n) sticky TTL/orphan sweep — timestamp of the last run.
     lastStickyCleanup = 0;
-    constructor(strategy = 'headroom', 
     /** Headroom at/below which a seat counts as drained — see DEFAULT_POOL_HEADROOM_FLOOR. */
-    headroomFloor = DEFAULT_POOL_HEADROOM_FLOOR) {
+    headroomFloor;
+    /** Only an explicitly configured floor is a hard stop; the implicit 2% remains a preference. */
+    hardHeadroomFloor;
+    constructor(strategy = 'headroom', headroomFloor) {
         this.strategy = strategy;
-        this.headroomFloor = headroomFloor;
+        this.headroomFloor = headroomFloor ?? DEFAULT_POOL_HEADROOM_FLOOR;
+        this.hardHeadroomFloor = headroomFloor !== undefined;
     }
     add(alias, opts) {
         const existing = this.accounts.get(alias);
@@ -997,11 +1046,13 @@ export class AccountPool {
                     : pickExpiringFirst(eligible, family, this.headroomFloor, now);
                 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);
+            if (!this.hardHeadroomFloor)
+                return pickMaxHeadroom(eligible, family);
+            const aboveFloor = eligible.filter(a => isAboveHeadroomFloor(computeHeadroom(a.rateLimit, family, now), this.headroomFloor));
+            return aboveFloor.length > 0
+                ? pickMaxHeadroom(aboveFloor, family)
+                : pickFloorProbe(eligible, family, this.headroomFloor, now);
         }
         // No seat is eligible. A seat parked inside a live window is not
         // re-probed: its 429 named the reset, the clock has not reached it, and a
@@ -1042,11 +1093,20 @@ export class AccountPool {
         // 429 again (dario#1264 review). An auth cool-down or an expired token
         // still does NOT count — those are not rate limits and must not be
         // reported, or cooled, as if they were.
-        if (!all.every(a => isParkedInLiveWindow(a, now, family) || isCoolingAfterRejection(a, now)))
+        const until = all.map((a) => {
+            if (isParkedInLiveWindow(a, now, family)) {
+                return isBucketScopedRejection(a.rateLimit)
+                    ? (a.rateLimit.parkedBucketsUntil ?? a.rateLimit.reset * 1000)
+                    : a.rateLimit.reset * 1000;
+            }
+            if (isCoolingAfterRejection(a, now))
+                return a.rateLimit.cooldownUntil ?? now;
+            if (this.hardHeadroomFloor && isAccountEligible(a, now, family)) {
+                return floorParkedUntil(a.rateLimit, family, this.headroomFloor, now);
+            }
             return null;
-        return Math.min(...all.map(a => isParkedInLiveWindow(a, now, family)
-            ? (isBucketScopedRejection(a.rateLimit) ? (a.rateLimit.parkedBucketsUntil ?? a.rateLimit.reset * 1000) : a.rateLimit.reset * 1000)
-            : a.rateLimit.cooldownUntil ?? now));
+        });
+        return until.every((reset) => reset !== null) ? Math.min(...until) : null;
     }
     /** Seats a rate limit is currently keeping out of rotation (dario#1244, #1264). */
     parkedCount(now = Date.now()) {
@@ -1077,7 +1137,7 @@ export class AccountPool {
             const bound = this.accounts.get(binding.alias);
             if (bound
                 && isAccountEligible(bound, now, family)
-                && computeHeadroom(bound.rateLimit, family) > this.headroomFloor) {
+                && isAboveHeadroomFloor(computeHeadroom(bound.rateLimit, family), this.headroomFloor)) {
                 // Refresh the idle timer. A session that keeps taking turns must never
                 // be reaped or rebound while active — that would strand its warm prompt
                 // cache — so the TTL is re-based to now on every hit.
@@ -1167,7 +1227,12 @@ export class AccountPool {
                 if (first)
                     return first;
             }
-            return pickMaxHeadroom(eligible, family);
+            if (!this.hardHeadroomFloor)
+                return pickMaxHeadroom(eligible, family);
+            const aboveFloor = eligible.filter(a => isAboveHeadroomFloor(computeHeadroom(a.rateLimit, family, now), this.headroomFloor));
+            return aboveFloor.length > 0
+                ? pickMaxHeadroom(aboveFloor, family)
+                : pickFloorProbe(eligible, family, this.headroomFloor, now);
         }
         // Mid-flight: the seats a 429 could still hand this request to. A seat
         // parked inside a live window is not one of them — on the dario#1244
@@ -1280,6 +1345,18 @@ export class AccountPool {
     get(alias) {
         return this.accounts.get(alias);
     }
+    /** Whether a preferred (but not pinned) seat may bypass normal pool ordering. */
+    canPrefer(account, now = Date.now(), family) {
+        if (!isAccountEligible(account, now, family))
+            return false;
+        if (!this.hardHeadroomFloor)
+            return true;
+        if (isAboveHeadroomFloor(computeHeadroom(account.rateLimit, family, now), this.headroomFloor))
+            return true;
+        // A stale below-floor reading needs one probe to refresh it; a reading
+        // with a known future reset remains hard-parked until that reset.
+        return floorParkedUntil(account.rateLimit, family, this.headroomFloor, now) === null;
+    }
     all() {
         return [...this.accounts.values()];
     }
@@ -1311,11 +1388,9 @@ export class AccountPool {
      */
     async waitForAccount() {
         const immediate = this.select();
-        if (immediate) {
-            const headroom = computeHeadroom(immediate.rateLimit);
-            if (headroom > this.headroomFloor)
-                return immediate;
-        }
+        if (immediate && (this.hardHeadroomFloor
+            || isAboveHeadroomFloor(computeHeadroom(immediate.rateLimit), this.headroomFloor)))
+            return immediate;
         if (this.queue.length >= this.queueMaxSize) {
             throw new Error('Queue full — all accounts exhausted');
         }
@@ -1355,8 +1430,10 @@ export class AccountPool {
             const account = this.select();
             if (!account)
                 break;
-            const headroom = computeHeadroom(account.rateLimit);
-            if (headroom <= this.headroomFloor)
+            // The implicit floor keeps its historical queueing behavior. In hard
+            // mode select() has already applied the floor, including stale probes.
+            if (!this.hardHeadroomFloor
+                && !isAboveHeadroomFloor(computeHeadroom(account.rateLimit), this.headroomFloor))
                 break;
             const entry = this.queue.shift();
             if (entry)

package/dist/proxy.d.ts

@@ -436,7 +436,8 @@ interface ProxyOptions {
     /**
      * Headroom at/below which a seat counts as drained (dario#1333): a sticky
      * session rebinds off it and new conversations skip it. Ratio (`0.05`) or
-     * percent (`5%`); default 2%. Sourced from `--pool-headroom-floor` /
+     * percent (`5%`). The implicit 2% default is a routing preference; setting
+     * this option explicitly makes the floor a hard stop. Sourced from `--pool-headroom-floor` /
      * `DARIO_POOL_HEADROOM_FLOOR` / config `pool.headroomFloor`.
      */
     poolHeadroomFloor?: string | number;

package/dist/proxy.js

@@ -13,7 +13,7 @@ import { CC_TOOL_DEFINITIONS_UNADVERTISABLE, CC_TEMPLATE_PROMPT_BYTES, resolveMa
 import { stampCch, hasCchSeed } from './cch.js';
 import { foldTiming, timingHeaders, timingLogFields } from './timing.js';
 import { describeTemplate, detectDrift, checkCCCompat, probeInstalledCCVersion } from './live-fingerprint.js';
-import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, accountIneligibility, reportedAccountStatus, activeParkedBuckets, reconcilePoolAccounts, resolvePoolStrategy, resolvePoolHeadroomFloor, describePoolStrategy, DEFAULT_POOL_HEADROOM_FLOOR, utilFreshness, rateLimitWindow, accountAction, accountPeers, distinctAccounts, describeRejection, maskEmail, isAccountEligible } from './pool.js';
+import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, accountIneligibility, reportedAccountStatus, activeParkedBuckets, reconcilePoolAccounts, resolvePoolStrategy, resolvePoolHeadroomFloor, parsePoolHeadroomFloor, describePoolStrategy, utilFreshness, rateLimitWindow, accountAction, accountPeers, distinctAccounts, describeRejection, maskEmail } from './pool.js';
 import { backfillIdentity } from './accounts.js';
 import { PoolSync, DEFAULT_POOL_SYNC_INTERVAL_MS } from './pool-sync.js';
 import { Analytics, billingBucketFromClaim, costOfTokensFailClosed, formatUsageLogLine, SUBSCRIPTION_CLAIMS, consumerFromHeader, consumerFromBody, CONSUMER_HEADER, CODEX_CLAIM } from './analytics.js';
@@ -1514,8 +1514,9 @@ export async function startProxy(opts = {}) {
     const accountsList = await loadAllAccounts();
     const poolStrategy = resolvePoolStrategy(opts.poolStrategy);
     const poolHeadroomFloor = resolvePoolHeadroomFloor(opts.poolHeadroomFloor);
-    const pool = new AccountPool(poolStrategy, poolHeadroomFloor);
-    if (poolHeadroomFloor !== DEFAULT_POOL_HEADROOM_FLOOR) {
+    const poolHeadroomFloorExplicit = parsePoolHeadroomFloor(opts.poolHeadroomFloor) !== null;
+    const pool = new AccountPool(poolStrategy, poolHeadroomFloorExplicit ? poolHeadroomFloor : undefined);
+    if (poolHeadroomFloorExplicit) {
         console.log(`[dario] Pool headroom floor: ${Math.round(poolHeadroomFloor * 100)}% — a seat at or below it is left alone: sticky sessions rebind off it, new conversations skip it`);
     }
     // Two aliases that are one account (same OAuth account uuid) are one
@@ -3391,7 +3392,7 @@ export async function startProxy(opts = {}) {
                 // eligible right now, else the pool picks as usual. Failover
                 // mid-request is unchanged either way — a preference, not a pin.
                 const preferredSeat = requestAuth.key?.seat ? (pool.get(requestAuth.key.seat) ?? null) : null;
-                keySeatTaken = preferredSeat !== null && isAccountEligible(preferredSeat, Date.now(), requestFamily);
+                keySeatTaken = preferredSeat !== null && pool.canPrefer(preferredSeat, Date.now(), requestFamily);
                 poolAccount = keySeatTaken ? preferredSeat : pool.select(requestFamily);
                 if (poolAccount)
                     poolParkedAnnounced = false;

package/docs/pool-keys-and-analytics.md

@@ -35,7 +35,7 @@ ChatGPT plans added with `dario codex add <alias>` pool the same way. The Codex
 
 Earlier releases placed ChatGPT conversations fill-first in alias order with cool-down eviction only, on the belief that the backend reported nothing before a 429, so a second seat served nothing until the first one declined.
 
-`--pool-strategy=fill-first` concentrates new conversations on one seat until it drains, for primary/backup setups; `--pool-strategy=expiring-first` fills in order of each seat's 7-day reset, soonest first, so capacity that expires soonest is spent first. `--pool-headroom-floor=5%` (env `DARIO_POOL_HEADROOM_FLOOR`, config `pool.headroomFloor`; default 2%) moves the line at which a seat counts as drained: a sticky session rebinds off it and new conversations skip it once its headroom is at or below the floor, so a seat that answers with API errors in its last percent is left alone before the 429, not at it. Refresh tokens expire about 28 days after the original grant regardless of rotation, so every seat's grant age is tracked and surfaced in `dario accounts list`, `dario doctor` and `GET /accounts` before it becomes a silent outage. Provision over HTTP with the headless [admin API](admin-api.md); pin one request to one seat with `dario accounts check <alias>` (admin API required: `DARIO_ADMIN=1` and a `DARIO_ADMIN_TOKEN`). Internals and the live `/accounts` + `/analytics` endpoints: [multi-account-pool.md](multi-account-pool.md); covered end-to-end by [`test/pool-e2e.mjs`](../test/pool-e2e.mjs).
+`--pool-strategy=fill-first` concentrates new conversations on one seat until it drains, for primary/backup setups; `--pool-strategy=expiring-first` fills in order of each seat's 7-day reset, soonest first, so capacity that expires soonest is spent first. `--pool-headroom-floor=5%` (env `DARIO_POOL_HEADROOM_FLOOR`, config `pool.headroomFloor`) moves the line at which a seat counts as drained: a sticky session rebinds off it and new conversations skip it once its headroom is at or below the floor, so a seat that answers with API errors in its last percent is left alone before the 429, not at it. Setting the floor explicitly makes it a hard stop; the implicit 2% default remains a routing preference and still serves the least-drained seat when it is the only choice. A hard-parked pool answers 429 locally with `retry-after` at the earliest known reset; a reading with no reset stays probeable so stale utilization cannot park a seat forever. Refresh tokens expire about 28 days after the original grant regardless of rotation, so every seat's grant age is tracked and surfaced in `dario accounts list`, `dario doctor` and `GET /accounts` before it becomes a silent outage. Provision over HTTP with the headless [admin API](admin-api.md); pin one request to one seat with `dario accounts check <alias>` (admin API required: `DARIO_ADMIN=1` and a `DARIO_ADMIN_TOKEN`). Internals and the live `/accounts` + `/analytics` endpoints: [multi-account-pool.md](multi-account-pool.md); covered end-to-end by [`test/pool-e2e.mjs`](../test/pool-e2e.mjs).
 
 ## One key per developer
 

package/package.json

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