@askalf/dario 5.5.28 → 5.5.30

package/dist/admin-api.d.ts

@@ -77,6 +77,17 @@ export interface AdminAccountRecord {
 export interface AdminAccountLive {
     util5h: number;
     util7d: number;
+    /**
+     * When `util5h` / `util7d` were last observed, epoch ms — or `null` if this
+     * account has never served a response. The utilisation figures are a
+     * snapshot of the last response the account served, not a live gauge: while
+     * an account is parked nothing refreshes them, so without a timestamp a
+     * consumer cannot tell a current reading from one frozen minutes ago
+     * (dario#1032).
+     */
+    lastObservedAt: number | null;
+    /** Age of that reading in ms, or `null` when never observed. */
+    utilAgeMs: number | null;
     claim: string;
     status: string;
     requestCount: number;

package/dist/health-response.d.ts

@@ -82,6 +82,19 @@ export interface HealthResponse {
 export interface PoolAccountStatusLike {
     expiresAt: number;
     inAuthCooldown: boolean;
+    /**
+     * Why the ROUTER cannot serve from this account, or null when it can —
+     * `accountIneligibility()` in pool.ts, computed by the caller (dario#1030).
+     *
+     * Required, deliberately. This surface previously derived usability itself
+     * from `inAuthCooldown` alone, which is a SUBSET of what select() filters on:
+     * a pool with every token expired, or every account rate-limited, reported
+     * `healthy` / `authenticated: true` while every request it served failed.
+     * The field is passed in rather than computed here so this module stays free
+     * of pool machinery and unit-testable as a pure function — and required so a
+     * caller cannot silently reintroduce the subset.
+     */
+    ineligible: string | null;
 }
 export interface PoolDerivedStatus {
     authenticated: boolean;

package/dist/health-response.js

@@ -14,6 +14,17 @@
  * The HTTP status (200 healthy / 503 degraded) is identical either way, so external
  * uptime monitoring that keys on the status code is unaffected.
  */
+/**
+ * Reason -> operator-facing summary. Keyed by `accountIneligibility()`'s return
+ * values; declared here rather than imported so this module stays free of pool
+ * machinery (see the file header). An unrecognised reason falls through to a
+ * generic line rather than being dropped.
+ */
+const POOL_DEAD_SUMMARY = {
+    'rate-limited': 'all accounts rate-limited',
+    'token-expired': 'all tokens expired — run `dario login`',
+    'auth-cooldown': 'all accounts in auth-cooldown',
+};
 function formatMsLeft(ms) {
     const clamped = Math.max(0, ms);
     return `${Math.floor(clamped / 3_600_000)}h ${Math.floor((clamped % 3_600_000) / 60_000)}m`;
@@ -33,17 +44,25 @@ export function derivePoolStatus(accounts, now, adminEnabled) {
                 : 'no accounts yet — run `dario accounts add <alias>`',
         };
     }
-    const usable = accounts.filter((a) => !a.inAuthCooldown);
+    // Ask exactly the question the router asks. Anything select() would refuse
+    // to serve from is unusable here too, whatever the reason.
+    const usable = accounts.filter((a) => a.ineligible === null);
     if (usable.length === 0) {
-        // Every account is routing-excluded after upstream auth failures — the
-        // next request will fail, which is the deadness /health exists to signal.
+        // No account can serve the next request — the deadness /health exists to
+        // signal. Name the reason: an operator seeing 'broken' needs to know
+        // whether to run `dario login`, wait out a rate limit, or fix credentials,
+        // and those have nothing in common but the verdict.
+        const reasons = new Set(accounts.map((a) => a.ineligible).filter((r) => r !== null));
+        const summary = reasons.size === 1
+            ? POOL_DEAD_SUMMARY[[...reasons][0]] ?? `all accounts unusable: ${[...reasons][0]}`
+            : `no account can serve (${[...reasons].sort().join(', ')})`;
         return {
             authenticated: false,
             status: 'broken',
             mode: 'pool',
             accounts: accounts.length,
             expiresAt: Math.min(...accounts.map((a) => a.expiresAt)),
-            expiresIn: 'all accounts in auth-cooldown',
+            expiresIn: summary,
         };
     }
     // Earliest expiry among USABLE accounts — the pool's background refresh

package/dist/pool.d.ts

@@ -40,6 +40,31 @@ export interface RateLimitSnapshot {
     updatedAt: number;
 }
 export declare const EMPTY_SNAPSHOT: RateLimitSnapshot;
+/** Freshness of an account's utilisation reading — see `utilFreshness`. */
+export interface UtilFreshness {
+    /** When util5h/util7d were last observed, epoch ms; null if never. */
+    lastObservedAt: number | null;
+    /** Age of that reading in ms; null if never observed. */
+    utilAgeMs: number | null;
+}
+/**
+ * Derive how old an account's utilisation reading is (dario#1032).
+ *
+ * `util5h` / `util7d` are a SNAPSHOT of the last response the account served.
+ * They do not tick on their own, and nothing refreshes them while an account is
+ * parked (rejected, or in auth cooldown) — so they stay frozen at whatever they
+ * read at the moment it was parked. The pool does return parked accounts to
+ * service on its own and the value corrects itself when it does, which is what
+ * makes this a REPORTING problem rather than a routing one: the payload carried
+ * no timestamp, so no consumer could tell a current reading from one frozen
+ * minutes ago, and a dashboard rendered "5-hour window full" for an account
+ * that had since reset and was free.
+ *
+ * `updatedAt` was already on the snapshot; it was simply never surfaced. An
+ * `updatedAt` of 0 is EMPTY_SNAPSHOT's "never observed", which must report as
+ * null rather than as an age of ~56 years since epoch.
+ */
+export declare function utilFreshness(rl: RateLimitSnapshot, now: number): UtilFreshness;
 export interface PoolAccount {
     alias: string;
     accessToken: string;
@@ -67,6 +92,33 @@ export interface PoolAccount {
 }
 export declare function authCooldownMs(consecutiveFailures: number): number;
 export declare function isInAuthCooldown(account: PoolAccount, now?: number): boolean;
+/**
+ * How long before a token's stated expiry the router stops trusting it. A
+ * request selected at T must still be valid when it reaches Anthropic.
+ */
+export declare const TOKEN_EXPIRY_MARGIN_MS = 30000;
+/** Why the router cannot serve a request from an account. */
+export type AccountIneligibility = 'rate-limited' | 'token-expired' | 'auth-cooldown';
+/**
+ * The single answer to "can the router serve a request from this account, and
+ * if not, why not?" (dario#1030).
+ *
+ * This predicate was inline at four sites in this file and had been
+ * re-implemented, as a SUBSET, by a fifth reader in health-response.ts — which
+ * filtered on auth-cooldown alone. A pool whose tokens had all expired, or
+ * whose accounts were all rate-limited, therefore reported `healthy` /
+ * `authenticated: true` on /health while every request it served failed. That
+ * is the exact case /health exists to catch: a monitor watching it sees
+ * nothing, and `dario doctor` reads the same derivation.
+ *
+ * It returns the REASON rather than a boolean because the surfaces want to say
+ * why — /health's `expiresIn` line, the 503 body, and doctor's routing row all
+ * need to name the failure, and a boolean forces each of them to re-derive it
+ * and drift again.
+ */
+export declare function accountIneligibility(account: PoolAccount, now?: number): AccountIneligibility | null;
+/** Boolean form of `accountIneligibility` — the router's eligibility filter. */
+export declare function isAccountEligible(account: PoolAccount, now?: number): boolean;
 export interface PoolStatus {
     accounts: number;
     healthy: number;

package/dist/pool.js

@@ -34,6 +34,30 @@ export const EMPTY_SNAPSHOT = {
     fallbackPct: 0,
     updatedAt: 0,
 };
+/**
+ * Derive how old an account's utilisation reading is (dario#1032).
+ *
+ * `util5h` / `util7d` are a SNAPSHOT of the last response the account served.
+ * They do not tick on their own, and nothing refreshes them while an account is
+ * parked (rejected, or in auth cooldown) — so they stay frozen at whatever they
+ * read at the moment it was parked. The pool does return parked accounts to
+ * service on its own and the value corrects itself when it does, which is what
+ * makes this a REPORTING problem rather than a routing one: the payload carried
+ * no timestamp, so no consumer could tell a current reading from one frozen
+ * minutes ago, and a dashboard rendered "5-hour window full" for an account
+ * that had since reset and was free.
+ *
+ * `updatedAt` was already on the snapshot; it was simply never surfaced. An
+ * `updatedAt` of 0 is EMPTY_SNAPSHOT's "never observed", which must report as
+ * null rather than as an age of ~56 years since epoch.
+ */
+export function utilFreshness(rl, now) {
+    const lastObservedAt = rl.updatedAt || null;
+    return {
+        lastObservedAt,
+        utilAgeMs: lastObservedAt === null ? null : Math.max(0, now - lastObservedAt),
+    };
+}
 /**
  * Cool-down schedule after auth failures. First failure: 60s. Each
  * consecutive failure doubles the window up to 30 minutes. Cleared
@@ -54,6 +78,41 @@ export function isInAuthCooldown(account, now = Date.now()) {
     const cooldown = authCooldownMs(account.consecutiveAuthFailures);
     return now - account.lastAuthFailureAt < cooldown;
 }
+/**
+ * How long before a token's stated expiry the router stops trusting it. A
+ * request selected at T must still be valid when it reaches Anthropic.
+ */
+export const TOKEN_EXPIRY_MARGIN_MS = 30_000;
+/**
+ * The single answer to "can the router serve a request from this account, and
+ * if not, why not?" (dario#1030).
+ *
+ * This predicate was inline at four sites in this file and had been
+ * re-implemented, as a SUBSET, by a fifth reader in health-response.ts — which
+ * filtered on auth-cooldown alone. A pool whose tokens had all expired, or
+ * whose accounts were all rate-limited, therefore reported `healthy` /
+ * `authenticated: true` on /health while every request it served failed. That
+ * is the exact case /health exists to catch: a monitor watching it sees
+ * nothing, and `dario doctor` reads the same derivation.
+ *
+ * It returns the REASON rather than a boolean because the surfaces want to say
+ * why — /health's `expiresIn` line, the 503 body, and doctor's routing row all
+ * need to name the failure, and a boolean forces each of them to re-derive it
+ * and drift again.
+ */
+export function accountIneligibility(account, now = Date.now()) {
+    if (account.rateLimit.status === 'rejected')
+        return 'rate-limited';
+    if (account.expiresAt <= now + TOKEN_EXPIRY_MARGIN_MS)
+        return 'token-expired';
+    if (isInAuthCooldown(account, now))
+        return 'auth-cooldown';
+    return null;
+}
+/** Boolean form of `accountIneligibility` — the router's eligibility filter. */
+export function isAccountEligible(account, now = Date.now()) {
+    return accountIneligibility(account, now) === null;
+}
 /**
  * Resolve the pool strategy from an explicit value (CLI flag / config file,
  * already precedence-merged by the caller) with `DARIO_POOL_STRATEGY` as
@@ -289,9 +348,7 @@ export class AccountPool {
             return null;
         const now = Date.now();
         const all = [...this.accounts.values()];
-        const eligible = all.filter(a => a.rateLimit.status !== 'rejected' &&
-            a.expiresAt > now + 30_000 &&
-            !isInAuthCooldown(a, now));
+        const eligible = all.filter(a => isAccountEligible(a, now));
         if (eligible.length > 0) {
             if (this.strategy === 'fill-first') {
                 const first = pickFillFirst(eligible, family);
@@ -342,9 +399,7 @@ export class AccountPool {
         if (binding) {
             const bound = this.accounts.get(binding.alias);
             if (bound
-                && bound.rateLimit.status !== 'rejected'
-                && bound.expiresAt > now + 30_000
-                && !isInAuthCooldown(bound, now)
+                && isAccountEligible(bound, now)
                 && computeHeadroom(bound.rateLimit, family) > POOL_HEADROOM_FLOOR) {
                 // Refresh the idle timer. A session that keeps taking turns must never
                 // be reaped or rebound while active — that would strand its warm prompt
@@ -422,9 +477,7 @@ export class AccountPool {
             return null;
         const now = Date.now();
         const candidates = [...this.accounts.values()].filter(a => !excluded.has(a.alias));
-        const eligible = candidates.filter(a => a.rateLimit.status !== 'rejected' &&
-            a.expiresAt > now + 30_000 &&
-            !isInAuthCooldown(a, now));
+        const eligible = candidates.filter(a => isAccountEligible(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 —
@@ -472,9 +525,7 @@ export class AccountPool {
     status() {
         const all = this.all();
         const now = Date.now();
-        const healthy = all.filter(a => a.rateLimit.status !== 'rejected' &&
-            a.expiresAt > now + 30_000 &&
-            !isInAuthCooldown(a, now));
+        const healthy = all.filter(a => isAccountEligible(a, now));
         // Status is a pool-wide aggregate; family-agnostic. Per-model
         // headroom is request-context-specific and only meaningful at
         // select() time.

package/dist/proxy.js

@@ -12,7 +12,7 @@ import { darioVersion } from './version.js';
 import { buildCCRequest, applyCcPromptCaching, parseEffortSuffix, reverseMapResponse, createStreamingReverseMapper, orderHeadersForOutbound, overlayTemplateHeaderValues, forwardClientCCIdentityHeaders, isMcpToolName, CC_TEMPLATE, effectiveCacheControl, withForced1hBeta } from './cc-template.js';
 import { stampCch, hasCchSeed } from './cch.js';
 import { describeTemplate, detectDrift, checkCCCompat, probeInstalledCCVersion } from './live-fingerprint.js';
-import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, reconcilePoolAccounts, resolvePoolStrategy } from './pool.js';
+import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, accountIneligibility, reconcilePoolAccounts, resolvePoolStrategy, utilFreshness } 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';
@@ -1677,7 +1677,14 @@ export async function startProxy(opts = {}) {
     // made the TUI claim the proxy was down).
     async function currentStatus() {
         const now = Date.now();
-        return derivePoolStatus(pool.all().map((a) => ({ expiresAt: a.expiresAt, inAuthCooldown: isInAuthCooldown(a, now) })), now, adminEnabled);
+        return derivePoolStatus(
+        // `ineligible` carries the ROUTER's verdict, so /health cannot answer a
+        // narrower question than select() does (#1030).
+        pool.all().map((a) => ({
+            expiresAt: a.expiresAt,
+            inAuthCooldown: isInAuthCooldown(a, now),
+            ineligible: accountIneligibility(a, now),
+        })), now, adminEnabled);
     }
     // Model catalog wiring — /v1/models serves the upstream-autodetected set,
     // authenticated the same way the request path is (per-token API key when
@@ -1834,6 +1841,10 @@ export async function startProxy(opts = {}) {
                         snap.set(a.alias, {
                             util5h: a.rateLimit.util5h,
                             util7d: a.rateLimit.util7d,
+                            // Same freshness fields GET /accounts exposes (#1032) — this
+                            // surface documents itself as reporting the same snapshot, so it
+                            // must not be the one place a stale reading still looks current.
+                            ...utilFreshness(a.rateLimit, snapNow),
                             claim: a.rateLimit.claim,
                             status: isInAuthCooldown(a, snapNow) ? 'auth-cooldown' : a.rateLimit.status,
                             requestCount: a.requestCount,
@@ -1913,10 +1924,25 @@ export async function startProxy(opts = {}) {
                 const cooldownMs = inCooldown && a.lastAuthFailureAt
                     ? Math.max(0, authCooldownMs(a.consecutiveAuthFailures) - (now - a.lastAuthFailureAt))
                     : 0;
+                // Freshness of the utilisation reading (#1032). util5h/util7d are a
+                // SNAPSHOT of the last response this account served — they do not tick
+                // on their own. While an account is parked (rejected, or in auth
+                // cooldown) nothing refreshes them, so they stay frozen at whatever
+                // they read at the moment it was parked, and a consumer sees "5-hour
+                // window full" for an account that has since reset and is free.
+                //
+                // The pool does return parked accounts to service on its own and the
+                // value corrects itself the moment it does, so this is a reporting
+                // problem, not a routing one: nothing downstream could tell a current
+                // reading from one frozen minutes ago, because the payload carried no
+                // timestamp at all. `updatedAt` was already on the snapshot; it was
+                // simply never surfaced. null means "never observed" (no response has
+                // been served on this account yet) rather than "observed at epoch 0".
                 return {
                     alias: a.alias,
                     util5h: a.rateLimit.util5h,
                     util7d: a.rateLimit.util7d,
+                    ...utilFreshness(a.rateLimit, now),
                     claim: a.rateLimit.claim,
                     status: inCooldown ? 'auth-cooldown' : a.rateLimit.status,
                     requestCount: a.requestCount,

package/package.json

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