@timo972/cc-router 0.10.1 → 0.11.0

package/dist/proxy/token-pool.js

@@ -1,8 +1,55 @@
 import { DEFAULT_RATE_LIMITS, ACCOUNT_USER_DEFAULTS, clampPercent } from "./types.js";
 import { canUseExtraUsage, normalizeModelFamily } from "../providers/anthropic/usage.js";
+import { nextEventSequence } from "./event-sequence.js";
 import { EmptyPoolError, NoEligibleAccountError, } from "./account-pool.js";
 // Re-export so existing importers (anthropic-routing.ts, tests) keep working.
 export { EmptyPoolError, NoEligibleAccountError };
+/**
+ * Operations on one scope's cooldown entries.
+ *
+ * Both cooldown maps — global scopes and model families — need identical
+ * handling, and keeping two copies of it is what let the same merge bug live
+ * on in the model path after the global path was fixed. Every mutation goes
+ * through these four functions so the invariant has one home.
+ */
+const cooldownEntries = {
+    /**
+     * Add a new expiry, dropping entries the new event makes redundant.
+     *
+     * The new event carries the highest sequence, so any entry it also outlasts
+     * can neither outlive it nor be released before it. Entries that expire
+     * later still say something this one does not, and are kept with their own
+     * sequences — collapsing them onto the newest sequence would let a later,
+     * shorter cooldown revive an expiry a refresh had already retired.
+     */
+    merge(entries, until, recordedSeq) {
+        const surviving = (entries ?? []).filter(entry => entry.until > until);
+        surviving.push({ until, recordedSeq });
+        return surviving;
+    },
+    /** Drop entries a refresh at `supersedingSeq` was initiated after. */
+    retireBefore(entries, supersedingSeq) {
+        return entries.filter(entry => supersedingSeq <= entry.recordedSeq);
+    },
+    /** Drop entries whose expiry has passed. */
+    live(entries, nowMs) {
+        return entries.filter(entry => entry.until > nowMs);
+    },
+    /** The scope's effective expiry: the furthest-out entry still standing. */
+    latestUntil(entries) {
+        let latest = 0;
+        for (const entry of entries ?? [])
+            latest = Math.max(latest, entry.until);
+        return latest;
+    },
+};
+/** Store `entries` under `key`, removing the key entirely when nothing is left. */
+function putEntries(map, key, entries) {
+    if (entries.length === 0)
+        map.delete(key);
+    else
+        map.set(key, entries);
+}
 const MAX_TRUSTED_RATE_LIMIT_RESET_MS = 8 * 24 * 60 * 60 * 1_000;
 /**
  * Returns the reset timestamp (seconds) that must pass before the account
@@ -24,6 +71,92 @@ function modelScopedClaim(claim) {
         claim !== "seven_day_oauth_apps" &&
         claim !== "seven_day_overage_included";
 }
+/**
+ * True only for a utilization the provider actually reported as below its
+ * limit. An absent or non-finite value is "unknown", never headroom: these
+ * checks decide whether to *release* a block, so unknown must not unbench.
+ */
+function reportsHeadroom(value) {
+    return typeof value === "number" && Number.isFinite(value) && value < 1;
+}
+/**
+ * The snapshot's place in the event order, or undefined when it has none.
+ *
+ * This is deliberately the *initiation* token, not `fetchedAt`: the latter is
+ * stamped after the response body is parsed, so a refresh already on the wire
+ * when a limit is hit completes afterwards while describing the account as it
+ * was before. Comparing that would treat pre-limit data as post-limit
+ * evidence. Wall-clock ms cannot substitute either — the 429, its headers, and
+ * the refresh the router starts from it all land in one event-loop turn and
+ * read the same millisecond. A snapshot with no token never supersedes.
+ */
+function supersedingSequence(usage) {
+    if (!usage || usage.fetchStatus !== "fresh")
+        return undefined;
+    const requestedSeq = usage.requestedSeq;
+    return typeof requestedSeq === "number" && Number.isFinite(requestedSeq)
+        ? requestedSeq
+        : undefined;
+}
+/**
+ * True when a usage refresh started after the limiting headers landed and
+ * reports the claimed window below its limit.
+ *
+ * `status` is a snapshot of the last response's headers, and the reset
+ * timestamps it is cleared against belong to the window that was limiting
+ * *then*. Anything that refills that window early — a plan upgrade being the
+ * common case — leaves the flag describing a limit that no longer exists,
+ * and a benched account never receives the response that would correct it.
+ * The usage endpoint is the provider's own account of the same windows, so a
+ * later snapshot showing headroom supersedes the flag. This is the same
+ * supersession rule `TokenPool.releaseCooldownsSupersededByUsage` applies to
+ * the pool's cooldown map.
+ *
+ * Only the claimed window counts. An unattributed claim requires both windows,
+ * mirroring the reset-based rule above it; a claim naming a quota the snapshot
+ * does not report cannot reach here at all, since `stillBlocked` is already
+ * false for it.
+ */
+function usageSupersedesRateLimitedStatus(r) {
+    const usage = r.usage;
+    const supersedingSeq = supersedingSequence(usage);
+    if (supersedingSeq === undefined)
+        return false;
+    // Headers with no ordering token cannot be compared, so they stand.
+    if (r.lastUpdatedSeq === undefined || supersedingSeq <= r.lastUpdatedSeq)
+        return false;
+    if (r.claim === "five_hour")
+        return reportsHeadroom(usage?.fiveHour?.utilization);
+    if (r.claim === "seven_day")
+        return reportsHeadroom(usage?.sevenDay?.utilization);
+    if (r.claim === "") {
+        return reportsHeadroom(usage?.fiveHour?.utilization) &&
+            reportsHeadroom(usage?.sevenDay?.utilization);
+    }
+    return false;
+}
+/**
+ * Whether the usage snapshot is the newer account of capacity than the last
+ * response headers, and so the one routing should believe.
+ *
+ * Decided on the event order for the same reason supersession is: a refresh
+ * that starts before a response and finishes after it carries the *older*
+ * picture despite the later clock reading. Preferring it there would hide a
+ * fresher exhaustion signal behind a snapshot that never saw it — and, since
+ * cooldown release already runs on sequences, would leave the two halves of
+ * the same decision disagreeing about which source is current. Snapshots
+ * predating the ordering tokens fall back to the timestamp comparison.
+ */
+function usageOutranksHeaders(r) {
+    const usage = r.usage;
+    if (!usage)
+        return false;
+    const usageSeq = usage.requestedSeq;
+    if (typeof usageSeq === "number" && Number.isFinite(usageSeq) && r.lastUpdatedSeq !== undefined) {
+        return usageSeq > r.lastUpdatedSeq;
+    }
+    return usage.fetchedAt >= r.lastUpdated;
+}
 /** Accept only reset timestamps within the same bounded horizon as cooldown evidence. */
 function trustworthyResetMs(resetAtSeconds, nowMs) {
     if (typeof resetAtSeconds !== "number" || !Number.isFinite(resetAtSeconds) || resetAtSeconds <= 0) {
@@ -52,10 +185,9 @@ function trustworthyResetMs(resetAtSeconds, nowMs) {
  * window expires, `status` flips back to `"allowed"`. The callback fires
  * once per recovery so the dashboard can surface it.
  */
-function clearExpiredRateLimitWindows(a, nowMs, onExpired) {
+function clearExpiredRateLimitWindows(a, nowMs) {
     const nowSec = Math.floor(nowMs / 1000);
     const r = a.rateLimits;
-    let recovered = false;
     if (r.fiveHourReset > 0 && nowSec >= r.fiveHourReset) {
         r.fiveHourUtil = 0;
         r.fiveHourReset = 0;
@@ -64,17 +196,23 @@ function clearExpiredRateLimitWindows(a, nowMs, onExpired) {
         r.sevenDayUtil = 0;
         r.sevenDayReset = 0;
     }
+    // A rolled-over window is no longer *known* to be spent, which is what
+    // unblocks routing — but we have not heard a new figure from the provider
+    // either. Clearing the reading rather than writing a zero keeps that
+    // distinction: safeUtilization() reads it as 0 for blocking decisions, while
+    // supersession, which releases cooldowns only on reported headroom, still
+    // sees nothing reported and leaves them to expire on their own terms.
     const usage = r.usage;
     if (usage) {
         for (const window of [usage.fiveHour, usage.sevenDay]) {
             if (window && window.resetAt > 0 && nowSec >= window.resetAt) {
-                window.utilization = 0;
+                delete window.utilization;
                 window.resetAt = 0;
             }
         }
         for (const limit of usage.modelLimits) {
             if (limit.resetAt > 0 && nowSec >= limit.resetAt) {
-                limit.utilization = 0;
+                delete limit.utilization;
                 limit.resetAt = 0;
             }
         }
@@ -86,24 +224,40 @@ function clearExpiredRateLimitWindows(a, nowMs, onExpired) {
         const stillBlocked = (r.claim === "five_hour" && r.fiveHourReset > 0) ||
             (r.claim === "seven_day" && r.sevenDayReset > 0) ||
             (r.claim === "" && (r.fiveHourReset > 0 || r.sevenDayReset > 0));
-        if (!stillBlocked) {
+        if (!stillBlocked || usageSupersedesRateLimitedStatus(r)) {
             r.status = "allowed";
-            recovered = true;
         }
     }
-    if (recovered && onExpired)
-        onExpired(a);
 }
 export class TokenPool {
     accounts;
     inFlight = new Map();
     cooldowns = new Map();
     now;
+    nextSequence;
+    /**
+     * Accounts known to be blocked for every model, so recovery is announced
+     * once when the final blocker clears.
+     *
+     * Membership is seeded from two places, because the blockers differ in kind.
+     * A `rate_limited` flag or a spent window persists until something rolls it
+     * over, so observing the account is enough to notice it. A cooldown instead
+     * erases itself at its expiry: `globalUntil > now()` already reads false by
+     * the time the next sweep arrives, so an account left idle across a short
+     * cooldown would never be recorded as blocked and its recovery would go
+     * unreported. The account-global cooldown setters therefore record it when
+     * the cooldown is created. Model cooldowns deliberately do not — an account
+     * spent on one family is still serving the rest, so it never left rotation.
+     *
+     * Weak so an account removed while blocked is not retained.
+     */
+    globallyBlocked = new WeakSet();
     currentIndex = 0;
     nextAmbiguousCooldownToken = 1;
     constructor(accounts, options = {}) {
         this.accounts = accounts;
         this.now = options.now ?? Date.now;
+        this.nextSequence = options.nextSequence ?? nextEventSequence;
     }
     /**
      * Compatibility wrapper for request sites that do not yet retain leases.
@@ -156,7 +310,7 @@ export class TokenPool {
         const account = this.findById(accountId);
         if (!account)
             return null;
-        clearExpiredRateLimitWindows(account, this.now(), this.onCooldownExpired);
+        this.refreshBlockingState(account);
         if (this.hardBlock(account, context) || this.overUserCap(account))
             return null;
         return this.createLease(account, false);
@@ -165,7 +319,7 @@ export class TokenPool {
         const account = this.findById(accountId);
         if (!account)
             return false;
-        clearExpiredRateLimitWindows(account, this.now(), this.onCooldownExpired);
+        this.refreshBlockingState(account);
         return this.hardBlock(account, context) === null && !this.overUserCap(account);
     }
     getInFlight(accountId) {
@@ -181,14 +335,23 @@ export class TokenPool {
     setCooldownForAccount(account, durationMs) {
         this.setGlobalCooldownForAccount(account, durationMs);
     }
-    /** Apply an account-global cooldown to the exact account incarnation routed. */
-    setGlobalCooldownForAccount(account, durationMs) {
+    /**
+     * Apply an account-global cooldown to the exact account incarnation routed.
+     *
+     * `usageWindow` names the window whose limit caused this, when the usage
+     * endpoint reports one for it. Omitting it — an upstream overload, an
+     * OAuth-apps quota, any caller that cannot attribute the limit — makes the
+     * cooldown purely time-based, since no snapshot describes that limit.
+     */
+    setGlobalCooldownForAccount(account, durationMs, usageWindow) {
         const expiry = this.proposedExpiry(account, durationMs);
         if (expiry === undefined)
             return;
         const state = this.cooldownsFor(account);
-        state.definiteGlobalUntil = Math.max(state.definiteGlobalUntil, expiry);
+        const scope = usageWindow ?? "unscoped";
+        putEntries(state.definiteGlobal, scope, cooldownEntries.merge(state.definiteGlobal.get(scope), expiry, this.nextSequence()));
         this.recomputeGlobalUntil(state);
+        this.globallyBlocked.add(account);
     }
     /** Apply a model-family cooldown to the exact account incarnation routed. */
     setModelCooldownForAccount(account, modelFamily, durationMs) {
@@ -197,7 +360,7 @@ export class TokenPool {
         if (expiry === undefined || family === undefined)
             return;
         const state = this.cooldownsFor(account);
-        state.modelUntil.set(family, Math.max(state.modelUntil.get(family) ?? 0, expiry));
+        putEntries(state.modelUntil, family, cooldownEntries.merge(state.modelUntil.get(family), expiry, this.nextSequence()));
     }
     /** Mark a conservative global cooldown as eligible for later narrowing. */
     setAmbiguousGlobalCooldownForAccount(account, durationMs, modelFamily) {
@@ -212,6 +375,7 @@ export class TokenPool {
             ...(family ? { modelFamily: family } : {}),
         });
         this.recomputeGlobalUntil(state);
+        this.globallyBlocked.add(account);
         return token;
     }
     /** Narrow only ambiguity-owned global state after a successful usage refresh. */
@@ -229,7 +393,7 @@ export class TokenPool {
             return false;
         const proposed = this.proposedExpiry(account, durationMs) ?? 0;
         const expiry = Math.max(pending.until, proposed);
-        state.modelUntil.set(family, Math.max(state.modelUntil.get(family) ?? 0, expiry));
+        putEntries(state.modelUntil, family, cooldownEntries.merge(state.modelUntil.get(family), expiry, this.nextSequence()));
         state.pendingAmbiguous.delete(token);
         this.recomputeGlobalUntil(state);
         if (state.globalUntil <= this.now()) {
@@ -250,7 +414,7 @@ export class TokenPool {
         if (!current)
             return 0;
         const family = normalizeModelFamily(context?.modelFamily ?? context?.requestedModel);
-        return Math.max(current.globalUntil, family ? current.modelUntil.get(family) ?? 0 : 0);
+        return Math.max(current.globalUntil, family ? cooldownEntries.latestUntil(current.modelUntil.get(family)) : 0);
     }
     isCoolingDown(accountId, context) {
         if (context !== undefined)
@@ -283,10 +447,13 @@ export class TokenPool {
         return {
             globalUntilMs: current.globalUntil,
             modelCooldowns: [...current.modelUntil]
-                .filter(([, untilMs]) => untilMs > 0)
-                .sort(([left], [right]) => left.localeCompare(right))
-                .slice(0, 12)
-                .map(([modelFamily, untilMs]) => ({ modelFamily, untilMs })),
+                .map(([modelFamily, entries]) => ({
+                modelFamily,
+                untilMs: cooldownEntries.latestUntil(entries),
+            }))
+                .filter(cooldown => cooldown.untilMs > 0)
+                .sort((left, right) => left.modelFamily.localeCompare(right.modelFamily))
+                .slice(0, 12),
         };
     }
     hardBlock(account, context) {
@@ -351,7 +518,7 @@ export class TokenPool {
             },
         ];
         const usage = account.rateLimits.usage;
-        if (!usage || usage.fetchStatus === "unavailable" || usage.fetchedAt < account.rateLimits.lastUpdated) {
+        if (!usage || usage.fetchStatus === "unavailable" || !usageOutranksHeaders(account.rateLimits)) {
             return headers;
         }
         return [
@@ -417,35 +584,135 @@ export class TokenPool {
             state = {
                 globalUntil: 0,
                 modelUntil: new Map(),
-                definiteGlobalUntil: 0,
+                definiteGlobal: new Map(),
                 pendingAmbiguous: new Map(),
             };
             this.cooldowns.set(account, state);
         }
         return state;
     }
+    /**
+     * Roll one account's expiry and supersession state forward, announcing
+     * recovery exactly when the last account-global blocker clears.
+     *
+     * The listener used to hang off the `rate_limited` header flag alone, which
+     * both over- and under-reports once anything else can block the account: a
+     * 429 overlapping a 529 would announce recovery while the overload cooldown
+     * still kept the account out of rotation, and because the flag only flips
+     * once, the moment it genuinely came back passed unannounced. Every blocker
+     * is settled first, then the transition is judged on all of them together.
+     */
+    refreshBlockingState(account) {
+        // Seeded before rolling forward as well as after, because the two checks
+        // answer different questions. A blocker that expires purely by the clock
+        // already reads as clear on the way in, so the remembered flag is what
+        // detects that transition; the pre-roll check is what lets an account
+        // first observed at the very moment it recovers still count as having
+        // been blocked.
+        if (this.accountGloballyBlocked(account))
+            this.globallyBlocked.add(account);
+        clearExpiredRateLimitWindows(account, this.now());
+        const state = this.cooldowns.get(account);
+        if (state)
+            this.clearExpiredCooldownState(account, state);
+        if (this.accountGloballyBlocked(account))
+            this.globallyBlocked.add(account);
+        else if (this.globallyBlocked.delete(account))
+            this.onCooldownExpired?.(account);
+    }
+    /**
+     * Whether anything blocks this account for *every* model, which is what the
+     * recovery listener speaks about. Deliberately excludes model-scoped state:
+     * an account spent on one family but serving another has not left rotation.
+     */
+    accountGloballyBlocked(account) {
+        const r = account.rateLimits;
+        if (r.status === "rate_limited" && !modelScopedClaim(r.claim))
+            return true;
+        // Compared against the clock rather than swept first, so this reads
+        // correctly both before and after the state is rolled forward.
+        if ((this.cooldowns.get(account)?.globalUntil ?? 0) > this.now())
+            return true;
+        return this.globalWindows(account).some(window => window.utilization >= 1) &&
+            !this.canUsePaidExtra(account);
+    }
     clearExpiredCooldownState(account, state) {
         const now = this.now();
-        if (state.definiteGlobalUntil <= now)
-            state.definiteGlobalUntil = 0;
+        for (const [scope, entries] of state.definiteGlobal) {
+            putEntries(state.definiteGlobal, scope, cooldownEntries.live(entries, now));
+        }
         for (const [token, pending] of state.pendingAmbiguous) {
             if (pending.until <= now)
                 state.pendingAmbiguous.delete(token);
         }
-        this.recomputeGlobalUntil(state);
-        for (const [family, expiry] of state.modelUntil) {
-            if (expiry <= now)
-                state.modelUntil.delete(family);
+        for (const [family, entries] of state.modelUntil) {
+            putEntries(state.modelUntil, family, cooldownEntries.live(entries, now));
         }
+        this.releaseCooldownsSupersededByUsage(account, state);
+        this.recomputeGlobalUntil(state);
         this.deleteEmptyCooldowns(account, state);
     }
+    /**
+     * Drop cooldowns whose evidence a newer usage snapshot has superseded.
+     *
+     * A cooldown expiry is only a cache of "no capacity until T", derived from
+     * the reset timestamps attached to a 429. Anything that refills the window
+     * ahead of that timestamp — a plan upgrade being the common case — leaves
+     * the cached expiry describing a limit that no longer exists, and because
+     * the account is benched no new response ever arrives to correct it. That
+     * is the same deadlock `clearExpiredRateLimitWindows` resolves for the
+     * header snapshot, which cannot see cooldowns held here.
+     *
+     * Two conditions keep this from unbenching an account that is still limited.
+     * The refresh must have *started* after the cooldown was recorded, so data
+     * gathered before the limiting response is never mistaken for evidence about
+     * it. And the snapshot must report on the scope that produced the cooldown:
+     * only the claimed window releases a global cooldown, and only the matching
+     * family releases a model cooldown. Cooldowns for limits no snapshot
+     * describes are `unscoped` and stay purely time-based, as do ambiguous ones.
+     *
+     * Each scope is judged on its own, so releasing one leaves any other still
+     * running — an overload cooldown outlives the quota cooldown beside it.
+     *
+     * Within scope, releasing opens no hole: `hardBlock` reads the same snapshot
+     * for its exhausted-window check, so an account whose capacity is genuinely
+     * gone stays blocked on that check instead.
+     */
+    releaseCooldownsSupersededByUsage(account, state) {
+        const usage = account.rateLimits.usage;
+        const supersedingSeq = supersedingSequence(usage);
+        if (usage === undefined || supersedingSeq === undefined)
+            return;
+        // Retire only the expiries this refresh was initiated after. A 429 that
+        // landed while it was in flight still stands on its own evidence.
+        for (const [scope, entries] of state.definiteGlobal) {
+            if (scope === "unscoped")
+                continue;
+            const window = scope === "five_hour" ? usage.fiveHour : usage.sevenDay;
+            if (!reportsHeadroom(window?.utilization))
+                continue;
+            putEntries(state.definiteGlobal, scope, cooldownEntries.retireBefore(entries, supersedingSeq));
+        }
+        // A family the snapshot does not mention is left alone: silence is not
+        // evidence of headroom. `active` is deliberately not consulted, matching
+        // matchingModelWindows() — utilization is what gates routing.
+        for (const [family, entries] of state.modelUntil) {
+            const limit = usage.modelLimits.find(candidate => normalizeModelFamily(candidate.modelFamily) === family);
+            if (!limit || !reportsHeadroom(limit.utilization))
+                continue;
+            putEntries(state.modelUntil, family, cooldownEntries.retireBefore(entries, supersedingSeq));
+        }
+    }
     deleteEmptyCooldowns(account, state) {
         if (state.globalUntil === 0 && state.modelUntil.size === 0) {
             this.cooldowns.delete(account);
         }
     }
     recomputeGlobalUntil(state) {
-        let globalUntil = state.definiteGlobalUntil;
+        let globalUntil = 0;
+        for (const entries of state.definiteGlobal.values()) {
+            globalUntil = Math.max(globalUntil, cooldownEntries.latestUntil(entries));
+        }
         for (const pending of state.pendingAmbiguous.values()) {
             globalUntil = Math.max(globalUntil, pending.until);
         }
@@ -459,7 +726,10 @@ export class TokenPool {
         const current = this.cooldowns.get(account);
         if (!current)
             return 0;
-        const expiries = [current.globalUntil, ...current.modelUntil.values()].filter(value => value > 0);
+        const expiries = [
+            current.globalUntil,
+            ...[...current.modelUntil.values()].map(entries => cooldownEntries.latestUntil(entries)),
+        ].filter(value => value > 0);
         return expiries.length > 0 ? Math.min(...expiries) : 0;
     }
     selectEligible(candidates, activeSessions, context) {
@@ -542,13 +812,8 @@ export class TokenPool {
      * poll loop so the UI reflects recovery without waiting for a new request.
      */
     sweepExpiredCooldowns() {
-        const now = this.now();
-        for (const a of this.accounts) {
-            clearExpiredRateLimitWindows(a, now, this.onCooldownExpired);
-            const state = this.cooldowns.get(a);
-            if (state)
-                this.clearExpiredCooldownState(a, state);
-        }
+        for (const a of this.accounts)
+            this.refreshBlockingState(a);
     }
     getAll() {
         return this.accounts;

package/dist/proxy/upstream-retry.js

@@ -0,0 +1,87 @@
+/**
+ * Shared policy for router-side upstream retries. Both providers consult the
+ * same rules so a 429 fails over and a 5xx retries identically whether the
+ * request came from Claude Code or the Codex CLI.
+ *
+ * The policy deliberately lives apart from either transport: it must only be
+ * applied BEFORE any response bytes have been relayed to a client, and the
+ * decision of when that is remains each transport's own.
+ */
+/** Total upstream attempts per client request, the first one included. */
+export const MAX_UPSTREAM_ATTEMPTS = 3;
+/**
+ * Pause before re-sending to the SAME account (a plain 5xx applies no
+ * cooldown and keeps the sticky binding, so re-acquisition returns the
+ * account that just failed). An immediate replay would hit whatever
+ * transient condition produced the 5xx still in progress; failovers to a
+ * different account skip the delay entirely.
+ */
+export const SAME_ACCOUNT_RETRY_DELAY_MS = 500;
+/**
+ * Which upstream statuses the router may retry on its own. 429 fails over to
+ * a different account; 5xx (including Anthropic's 529 and Codex's 503
+ * overloads, whose cooldowns rebind the session elsewhere) retries per the
+ * pool's routing rules. 401 is deliberately absent: auth failures pass
+ * through while a background token refresh runs, exactly as before.
+ */
+export function isRetryableUpstreamStatus(status) {
+    return status === 429 || status >= 500;
+}
+/**
+ * Longest the retry loop will wait for a failover account's token refresh
+ * while an upstream failure response sits ready to relay. Refreshes normally
+ * settle within a couple of seconds; the refresh fetch itself carries no
+ * deadline, and the pre-response proxy timeout was already disarmed when the
+ * failure's headers arrived — so without this bound a stalled OAuth endpoint
+ * could withhold a ready 429/5xx for minutes. Generous on purpose: the
+ * fallback is relaying a failure the client may not recover from, so a slow
+ * but working refresh deserves the extra seconds.
+ */
+export const RETRY_REFRESH_TIMEOUT_MS = 15_000;
+/**
+ * Await `work` for at most `ms`, resolving to `fallback` when the deadline
+ * passes or `signal` aborts first. `work` is NOT cancelled — a token refresh
+ * that settles late still updates its account for future requests — the
+ * caller merely stops waiting for it, and a late rejection is swallowed so
+ * abandoning the wait can never surface an unhandled rejection. A rejection
+ * inside the deadline also resolves to `fallback`; callers that need to tell
+ * failure from timeout map their promise to a value before waiting.
+ */
+export function boundedWait(work, ms, fallback, signal) {
+    return new Promise(resolve => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            resolve(value);
+        };
+        const onAbort = () => finish(fallback);
+        const timer = setTimeout(() => finish(fallback), ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+        work.then(finish, () => finish(fallback));
+    });
+}
+/**
+ * Resolve after `ms`, or as soon as `signal` aborts — a client that hung up
+ * must not keep a retry pending. Never rejects.
+ */
+export function retryDelay(ms, signal) {
+    if (ms <= 0 || signal?.aborted)
+        return Promise.resolve();
+    return new Promise(resolve => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timo972/cc-router",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Cache-aware session router for Claude Max OAuth tokens — use multiple Claude Max accounts with Claude Code",
   "type": "module",
   "bin": {