@goodandready/dsh-key-rotation 0.8.77 → 0.8.78

package/lib/client-src/60-header-chip.js

@@ -0,0 +1,137 @@
+    // (issue 201, #499) header chip: one dot + counts for all pools. Green = all healthy,
+    // amber = some keys cooling, red = a pool fully exhausted. Click opens quick actions popover.
+    function KeyRotationHeaderChip(props) {
+      const t = resolveT(props);
+      const [snap, setSnap] = React.useState(null);
+      const [open, setOpen] = React.useState(false);
+      const [, setTick] = React.useState(0);
+      const [busy, setBusy] = React.useState(false);
+      const ref = React.useRef(null);
+
+      const load = () => {
+        if (typeof document !== 'undefined' && document.visibilityState !== 'visible') return;
+        fetch('/dsh-key-rotation/health', {
+          headers: { accept: 'application/json' },
+          credentials: 'same-origin',
+          signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(8000) : undefined
+        })
+          .then((r) => (r.ok ? r.json() : null))
+          .then((d) => { if (d) setSnap(d); })
+          .catch((e) => { void e; });
+      };
+
+      React.useEffect(() => {
+        load();
+        const id = setInterval(load, 5000);
+        const onVis = () => { if (typeof document !== 'undefined' && document.visibilityState === 'visible') load(); };
+        if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onVis);
+        return () => {
+          clearInterval(id);
+          if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onVis);
+        };
+      }, []);
+
+      React.useEffect(() => {
+        if (!props?.settingsSource?.subscribe) return;
+        return props.settingsSource.subscribe(() => {
+          setTick((c) => c + 1);
+        });
+      }, [props?.settingsSource]);
+
+      React.useEffect(() => {
+        if (!open) return;
+        const onDocClick = (e) => {
+          if (ref.current && !ref.current.contains(e.target)) setOpen(false);
+        };
+        document.addEventListener('click', onDocClick);
+        return () => document.removeEventListener('click', onDocClick);
+      }, [open]);
+
+      const runAction = (action, provider, keyRef) => {
+        setBusy(true);
+        fetch('/dsh-key-rotation/quick-action', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', accept: 'application/json' },
+          body: JSON.stringify({ action, provider, ref: keyRef }),
+          credentials: 'same-origin',
+          signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(5000) : undefined,
+        })
+          .then((r) => r.json())
+          .then(() => { load(); })
+          .catch((err) => { void err; })
+          .finally(() => { setBusy(false); });
+      };
+
+      let settingsVal = null;
+      try {
+        const sSnap = props?.settingsSource?.getSnapshot?.()?.service?.getSnapshot?.();
+        settingsVal = sSnap?.value;
+      } catch (e) {
+        void e;
+      }
+      if (settingsVal && settingsVal.showChatHeaderChip === false) return null;
+      if (snap && snap.showChatHeaderChip === false) return null;
+
+      const poolsObj = (snap && snap.pools) || {};
+      const poolEntries = Object.entries(poolsObj);
+      const total = poolEntries.reduce((a, [, p]) => a + (p.total || 0), 0);
+      const healthy = poolEntries.reduce((a, [, p]) => a + (p.healthy || 0), 0);
+      const anyExhausted = poolEntries.some(([, p]) => p.exhausted);
+      const color = !poolEntries.length ? 'var(--dsw-alias-label-tertiary)' : anyExhausted ? 'var(--dsw-alias-state-error-primary)' : healthy < total ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-state-success-primary)';
+      const label = poolEntries.length ? `${healthy}/${total} rot` : 'rot';
+
+      return h('div', { ref, style: { position: 'relative', display: 'inline-flex' } },
+        h('button', {
+          type: 'button',
+          className: 'krot-header-chip',
+          title: t('title'),
+          onClick: () => setOpen((v) => !v),
+        },
+          h('span', { style: { width: '8px', height: '8px', borderRadius: '50%', background: color, flex: 'none', boxShadow: `0 0 6px ${color}` } }),
+          label,
+          h('span', { style: { fontSize: '9px', opacity: 0.6 } }, open ? '▲' : '▼')
+        ),
+        open ? h('div', { className: 'krot-popover', style: { minWidth: '220px' } },
+          h('div', { className: 'krot-pop-title' }, t('headerPoolsTitle')),
+          !poolEntries.length ? h('div', { style: { fontSize: '12px', color: 'var(--dsw-alias-label-tertiary)' } }, t('noActivePools')) : null,
+          poolEntries.map(([name, p]) => {
+            const c = p.exhausted ? 'var(--dsw-alias-state-error-primary)' : (p.healthy < p.total ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-state-success-primary)');
+            const provName = p.providerName || name;
+            const tail = p.lastUsedTail;
+            return h('div', { key: name, className: 'krot-pop-row', style: { display: 'flex', flexDirection: 'column', gap: '4px', padding: '6px 0', borderBottom: '1px solid var(--dsw-alias-border-subtle)' } },
+              h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center' } },
+                h('div', { className: 'krot-pop-name' },
+                  h('span', { style: { width: '7px', height: '7px', borderRadius: '50%', background: c, flex: 'none' } }),
+                  name,
+                  tail ? h('span', { style: { marginLeft: '6px', fontSize: '11px', color: 'var(--dsw-alias-label-tertiary)', fontFeatureSettings: '"tnum"', fontFamily: 'monospace' } }, `...${tail}`) : null
+                ),
+                h('div', { className: 'krot-pop-count', style: { color: c, fontWeight: 600 } }, `${p.healthy}/${p.total}`)
+              ),
+              h('div', { style: { display: 'flex', gap: '4px', marginTop: '2px' } },
+                h('button', {
+                  type: 'button',
+                  disabled: busy,
+                  onClick: (e) => { e.stopPropagation(); runAction('skip', provName, p.lastUsed); },
+                  title: t('quickSkipTitle'),
+                  style: { padding: '2px 6px', fontSize: '11px', borderRadius: '4px', border: '1px solid var(--dsw-alias-border-subtle)', background: 'transparent', cursor: 'pointer', color: 'inherit' }
+                }, `⏭️ ${t('quickSkip')}`),
+                h('button', {
+                  type: 'button',
+                  disabled: busy,
+                  onClick: (e) => { e.stopPropagation(); runAction('reset', provName, p.lastUsed); },
+                  title: t('quickResetTitle'),
+                  style: { padding: '2px 6px', fontSize: '11px', borderRadius: '4px', border: '1px solid var(--dsw-alias-border-subtle)', background: 'transparent', cursor: 'pointer', color: 'inherit' }
+                }, `🔄 ${t('quickReset')}`),
+                h('button', {
+                  type: 'button',
+                  disabled: busy || !p.lastUsed,
+                  onClick: (e) => { e.stopPropagation(); runAction('pause', provName, p.lastUsed); },
+                  title: t('quickPauseTitle'),
+                  style: { padding: '2px 6px', fontSize: '11px', borderRadius: '4px', border: '1px solid var(--dsw-alias-border-subtle)', background: 'transparent', cursor: 'pointer', color: 'inherit' }
+                }, `⏸️ ${t('quickPause')}`)
+              )
+            );
+          })
+        ) : null
+      );
+    }

package/lib/client-src/90-apply.js

@@ -0,0 +1,69 @@
+    function apply(ctx) {
+      const settingsSource = createSettingsSource(ctx);
+      ctx.effect(() => ctx.locale.register(NS, { en, zh }), 'dsh-key-rotation: dictionaries');
+      // Header chip (#201): status dot in the session header utilities slot,
+      // same slot dsh-gitea / dsh-subscriptions use for their header widgets.
+      ctx.effect(() => {
+        if (!ctx.slots) return;
+        try {
+          ctx.slots.inject('conversation.session.header.utilities', () =>
+            ctx.slots.register(
+              { name: 'conversation.session.header.utilities', id: 'dsh-key-rotation-header-chip', order: 6, locale: NS, inject: () => ({ ctx, settingsSource }) },
+              KeyRotationHeaderChip,
+            ));
+        } catch { /* slot not available in this build */ }
+      }, 'dsh-key-rotation: header chip');
+
+      function useLocale() {
+        return useActiveLocale(ctx);
+      }
+      // Collapsible card in Settings -> Plugins -> Plugin settings
+      // (settings.plugin.item), matching Model Sync / Spendmeter / Vision Bridge.
+      // key MUST equal the settings namespace (NS), else the tab silently skips it.
+      
+  function KeyRotationCard(props) {
+        const locale = useLocale();
+        const t = resolveT(props);
+        const page = !!(props && props.view === 'page');
+        const [open, setOpen] = React.useState(!!page);
+        // Row seat (plugins.row.config): the host page draws title/icon/crumb and the
+        // padding, so the summary is a one-liner and the page drops our card chrome.
+        if (props && props.view === 'summary') {
+          return h('span', { className: 'krot-card-description' }, t('subtitle'));
+        }
+        return h(page ? 'div' : 'div', { className: page ? 'krot-page' : 'krot-card' + (open ? ' krot-card-open' : '') },
+          h('button', { type: 'button', className: 'krot-card-header', style: page ? { display: 'none' } : undefined, 'aria-expanded': page ? true : open, onClick: () => setOpen((v) => !v) },
+            h('span', { className: 'krot-card-head-text' },
+              h('span', { className: 'krot-card-name' }, t('title')),
+              h('span', { className: 'krot-card-description' }, t('subtitle'))),
+            h('span', { className: 'krot-card-chevron' + (open ? ' krot-card-chevron-open' : ''), 'aria-hidden': 'true' },
+              h('svg', { width: 14, height: 14, viewBox: '0 0 14 14', fill: 'none', stroke: 'currentColor', strokeWidth: 1.5, style: { display: 'block' } },
+                h('path', { d: 'M3.5 5.25L7 8.75L10.5 5.25' })))),
+          (page || open) ? h('div', { className: 'krot-card-body' }, h(KeyRotationErrorBoundary, null, h(KeyRotationSection, { ...props, locale }))) : null);
+      }
+      // Register each available seat independently. A missing legacy seat must
+      // not prevent the current bundle or row seat from registering.
+      for (const [name, key] of [
+        ['plugins.bundle.config', PKG],
+        ['plugins.row.config', ROW_CONFIG_KEY],
+        ['settings.plugin.item', NS],
+      ]) {
+        try {
+          ctx.slots.inject(name, () => ctx.slots.register(
+            { name, key, locale: NS, inject: () => ({ ctx, settingsSource }) }, KeyRotationCard,
+          ));
+        } catch (error) {
+          bestEffort('slots.register.log', () => { console.error('[dsh-key-rotation] settings seat unavailable', name, error); });
+        }
+      }
+    }
+
+    module.exports = { apply, inject: ['slots', 'locale'] };
+    if (typeof globalThis !== 'undefined') {
+      globalThis.__dshKeyRotationClientInternals = {
+        quotaMapOf, withQuotas, modelEntriesOf, isValidModelId, formatCountdown, validatePoolDraft,
+      };
+    }
+    return module.exports;
+  },
+});

package/lib/index.js

@@ -60,6 +60,9 @@ export { notifySwitch, notifyExhaustion, notifyEarlyWarning };
 export { classifyResponseError } from './errors.js';
 export { SessionRouter, defaultSessionRouter, unstickFailedKey } from './session-router.js';
 export { isContentChunk } from './rotate.js';
+export { ModelCatalog, defaultModelCatalog } from './model-catalog.js';
+export { QuotaRunway, defaultQuotaRunway, estimateRunway } from './quota-runway.js';
+export * as transports from './transports/index.js';
 
 const NS = 'dsh-key-rotation';
 

package/lib/model-catalog.js

@@ -0,0 +1,296 @@
+// lib/model-catalog.js — Centralized model catalog with Cache Stampede protection (#550).
+// Deduplicates concurrent in-flight requests and provides TTL-based caching and model capability normalization.
+
+export const DEFAULT_CATALOG_TTL_MS = 60 * 60 * 1000; // 1 hour
+export const DEFAULT_CATALOG_TIMEOUT_MS = 15_000;      // 15 seconds
+
+export const DEFAULT_CONTEXT_WINDOW = 128_000;
+export const DEFAULT_MAX_TOKENS = 8_192;
+
+export const KNOWN_MODELS_FALLBACK = {
+  'deepseek-chat': {
+    id: 'deepseek-chat',
+    name: 'DeepSeek Chat',
+    contextWindow: 64_000,
+    maxTokens: 8_000,
+    supportsReasoning: false,
+    supportsTools: true,
+    supportsVision: false,
+  },
+  'deepseek-reasoner': {
+    id: 'deepseek-reasoner',
+    name: 'DeepSeek Reasoner',
+    contextWindow: 64_000,
+    maxTokens: 8_000,
+    supportsReasoning: true,
+    supportsTools: false,
+    supportsVision: false,
+  },
+  'gpt-4o': {
+    id: 'gpt-4o',
+    name: 'GPT-4o',
+    contextWindow: 128_000,
+    maxTokens: 16_384,
+    supportsReasoning: false,
+    supportsTools: true,
+    supportsVision: true,
+  },
+  'gpt-4o-mini': {
+    id: 'gpt-4o-mini',
+    name: 'GPT-4o mini',
+    contextWindow: 128_000,
+    maxTokens: 16_384,
+    supportsReasoning: false,
+    supportsTools: true,
+    supportsVision: true,
+  },
+  'claude-3-5-sonnet-20241022': {
+    id: 'claude-3-5-sonnet-20241022',
+    name: 'Claude 3.5 Sonnet',
+    contextWindow: 200_000,
+    maxTokens: 8_192,
+    supportsReasoning: false,
+    supportsTools: true,
+    supportsVision: true,
+  },
+};
+
+/**
+ * Normalizes raw model object from provider /models endpoint.
+ * @param {object|string} raw
+ * @returns {object}
+ */
+export function normalizeModelMeta(raw) {
+  if (typeof raw === 'string') {
+    const fallback = KNOWN_MODELS_FALLBACK[raw];
+    return fallback ? { ...fallback } : {
+      id: raw,
+      name: raw,
+      contextWindow: DEFAULT_CONTEXT_WINDOW,
+      maxTokens: DEFAULT_MAX_TOKENS,
+      supportsReasoning: raw.includes('reason') || raw.includes('r1') || raw.includes('thought'),
+      supportsTools: true,
+      supportsVision: raw.includes('vision') || raw.includes('4o') || raw.includes('vl'),
+    };
+  }
+
+  const id = String(raw?.id || raw?.slug || raw?.name || '');
+  const fallback = KNOWN_MODELS_FALLBACK[id];
+
+  const name = String(raw?.name || raw?.display_name || id);
+  const contextWindow =
+    Number(raw?.context_window || raw?.max_context_window || raw?.contextWindow) ||
+    fallback?.contextWindow ||
+    DEFAULT_CONTEXT_WINDOW;
+  const maxTokens =
+    Number(raw?.max_tokens || raw?.max_output_tokens || raw?.maxTokens) ||
+    fallback?.maxTokens ||
+    DEFAULT_MAX_TOKENS;
+
+  const caps = Array.isArray(raw?.capabilities) ? raw.capabilities : [];
+  const reasoningLevels = Array.isArray(raw?.supported_reasoning_levels) ? raw.supported_reasoning_levels : [];
+
+  const supportsReasoning =
+    Boolean(raw?.supportsReasoning) ||
+    caps.includes('thinking') ||
+    caps.includes('reasoning') ||
+    reasoningLevels.length > 0 ||
+    id.includes('reason') ||
+    id.includes('r1') ||
+    fallback?.supportsReasoning ||
+    false;
+
+  const supportsTools =
+    raw?.supportsTools !== undefined
+      ? Boolean(raw.supportsTools)
+      : caps.includes('tools') || fallback?.supportsTools || true;
+
+  const inputModalities = Array.isArray(raw?.input_modalities) ? raw.input_modalities : [];
+  const supportsVision =
+    Boolean(raw?.supportsVision) ||
+    inputModalities.includes('image') ||
+    id.includes('vision') ||
+    id.includes('4o') ||
+    id.includes('vl') ||
+    fallback?.supportsVision ||
+    false;
+
+  return {
+    id,
+    name,
+    contextWindow,
+    maxTokens,
+    supportsReasoning,
+    supportsTools,
+    supportsVision,
+    raw,
+  };
+}
+
+export class ModelCatalog {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.ttlMs]
+   * @param {number} [options.timeoutMs]
+   * @param {typeof fetch} [options.fetchImpl]
+   */
+  constructor(options = {}) {
+    this.ttlMs = options.ttlMs ?? DEFAULT_CATALOG_TTL_MS;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_CATALOG_TIMEOUT_MS;
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    /** @type {Map<string, { at: number, models: Array<object> }>} */
+    this.cache = new Map();
+    /** @type {Map<string, Promise<Array<object>>>} In-flight deduplication map */
+    this.inflight = new Map();
+  }
+
+  _buildKey(endpoint, apiKey) {
+    const keyHint = apiKey ? apiKey.slice(-6) : 'anonymous';
+    return `${endpoint || 'default'}|${keyHint}`;
+  }
+
+  /**
+   * Gets list of models for an endpoint.
+   * If a request for this endpoint is already in flight, reuses the promise (anti-stampede).
+   *
+   * @param {object} options
+   * @param {string} options.endpoint Base URL or /models URL
+   * @param {string} [options.apiKey]
+   * @param {boolean} [options.forceRefresh]
+   * @param {typeof fetch} [options.fetchImpl]
+   * @returns {Promise<Array<object>>}
+   */
+  async getModels(options = {}) {
+    const { endpoint, apiKey, forceRefresh = false } = options;
+    const fetchFn = options.fetchImpl || this.fetchImpl;
+    const cacheKey = this._buildKey(endpoint, apiKey);
+    const now = Date.now();
+
+    // 1. Check TTL cache if not forcing refresh
+    if (!forceRefresh) {
+      const cached = this.cache.get(cacheKey);
+      if (cached && (now - cached.at < this.ttlMs)) {
+        return cached.models;
+      }
+    }
+
+    // 2. Check in-flight deduplication map (Cache Stampede protection)
+    const existingPromise = this.inflight.get(cacheKey);
+    if (existingPromise) {
+      return existingPromise;
+    }
+
+    // 3. Initiate single fetch and record in inflight map
+    const fetchPromise = (async () => {
+      try {
+        const models = await this._fetchModels(endpoint, apiKey, fetchFn);
+        this.cache.set(cacheKey, { at: Date.now(), models });
+        return models;
+      } catch (err) {
+        // On error, if we have stale cache, serve stale cache
+        const stale = this.cache.get(cacheKey);
+        if (stale && Array.isArray(stale.models) && stale.models.length > 0) {
+          return stale.models;
+        }
+        // Fallback to known models
+        return Object.values(KNOWN_MODELS_FALLBACK).map(normalizeModelMeta);
+      } finally {
+        this.inflight.delete(cacheKey);
+      }
+    })();
+
+    this.inflight.set(cacheKey, fetchPromise);
+    return fetchPromise;
+  }
+
+  /**
+   * Gets metadata for a specific model ID.
+   * @param {string} modelId
+   * @param {object} [options]
+   * @returns {Promise<object|null>}
+   */
+  async getModel(modelId, options = {}) {
+    if (!modelId) return null;
+    const models = await this.getModels(options);
+    const found = models.find((m) => m.id === modelId);
+    if (found) return found;
+    return normalizeModelMeta(modelId);
+  }
+
+  async _fetchModels(endpoint, apiKey, fetchFn) {
+    if (!endpoint || typeof fetchFn !== 'function') {
+      return Object.values(KNOWN_MODELS_FALLBACK).map(normalizeModelMeta);
+    }
+
+    let url = endpoint;
+    if (!url.endsWith('/models') && !url.includes('/models?')) {
+      url = url.replace(/\/+$/, '') + '/models';
+    }
+
+    const headers = {
+      accept: 'application/json',
+      'user-agent': 'dsh-key-rotation/model-catalog',
+    };
+    if (apiKey) {
+      headers.authorization = `Bearer ${apiKey}`;
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const resp = await fetchFn(url, {
+        headers,
+        signal: controller.signal,
+      });
+
+      if (!resp.ok) {
+        throw new Error(`Catalog fetch failed with status ${resp.status}`);
+      }
+
+      const body = await resp.json();
+      let rawList = [];
+
+      if (Array.isArray(body?.data)) {
+        rawList = body.data;
+      } else if (Array.isArray(body?.models)) {
+        rawList = body.models;
+      } else if (body?.models && typeof body.models === 'object') {
+        rawList = Object.entries(body.models).map(([k, v]) => ({ id: k, ...(typeof v === 'object' ? v : {}) }));
+      }
+
+      if (rawList.length === 0) {
+        return Object.values(KNOWN_MODELS_FALLBACK).map(normalizeModelMeta);
+      }
+
+      return rawList.map(normalizeModelMeta);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  invalidate(endpoint, apiKey) {
+    const key = this._buildKey(endpoint, apiKey);
+    this.cache.delete(key);
+    this.inflight.delete(key);
+  }
+
+  clear() {
+    this.cache.clear();
+    this.inflight.clear();
+  }
+
+  getStatus(endpoint, apiKey) {
+    const key = this._buildKey(endpoint, apiKey);
+    const entry = this.cache.get(key);
+    const isInflight = this.inflight.has(key);
+    return {
+      cached: Boolean(entry),
+      count: entry?.models?.length ?? 0,
+      fetchedAt: entry?.at ?? null,
+      inflight: isInflight,
+    };
+  }
+}
+
+export const defaultModelCatalog = new ModelCatalog();

package/lib/pool-selection.js

@@ -1,4 +1,4 @@
-// lib/pool-selection.js — pool selection, sticky sessions, attempt sorting and budget metrics (#512, #548).
+// lib/pool-selection.js — pool selection, sticky sessions, attempt sorting and budget metrics (#512, #548, #549).
 // Extracted from lib/pool.js to enforce < 600 line modularity standard.
 
 import {
@@ -8,11 +8,18 @@ import {
   SESSION_TTL_MS,
 } from './session-router.js';
 
+import {
+  QuotaRunway,
+  defaultQuotaRunway,
+} from './quota-runway.js';
+
 export {
   SessionRouter,
   defaultSessionRouter,
   MAX_SESSIONS,
   SESSION_TTL_MS,
+  QuotaRunway,
+  defaultQuotaRunway,
 };
 
 export const MAX_SESSION_STICKY_ENTRIES = MAX_SESSIONS;
@@ -103,11 +110,13 @@ export function selectPool(modelPoolByProvider, providerToPool, provider, model)
 
 /**
  * Sort candidate refs according to pool routing strategy.
+ * Preemptively deprioritizes keys projected to exhaust their quota before reset (#549).
  * Returns a new array; does not mutate input.
  */
 export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
   if (!Array.isArray(refs) || refs.length <= 1) return (refs ?? []).slice();
-  const list = refs.slice();
+  let list = refs.slice();
+
   if (strategy === 'sticky') {
     const router = getOrCreateSessionRouter(deps.pool);
     let chosenKey = null;
@@ -133,19 +142,16 @@ export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
         list.unshift(last);
       }
     }
-    return list;
-  }
-  if (strategy === 'tier-priority') {
+  } else if (strategy === 'tier-priority') {
     const tiers = deps.tiers || (deps.pool && deps.pool.tiers) || {};
-    return list.sort((a, b) => {
+    list = list.sort((a, b) => {
       const ta = (tiers[a] && Number(tiers[a]) >= 1) ? Number(tiers[a]) : 1;
       const tb = (tiers[b] && Number(tiers[b]) >= 1) ? Number(tiers[b]) : 1;
       return ta - tb;
     });
-  }
-  if (strategy === 'least-loaded' && deps.concurrencyTracker && typeof deps.concurrencyTracker.getActive === 'function') {
+  } else if (strategy === 'least-loaded' && deps.concurrencyTracker && typeof deps.concurrencyTracker.getActive === 'function') {
     const weights = deps.weights || (deps.pool && deps.pool.weightsMap) || {};
-    return list.sort((a, b) => {
+    list = list.sort((a, b) => {
       const ca = deps.concurrencyTracker.getActive(a) ?? 0;
       const cb = deps.concurrencyTracker.getActive(b) ?? 0;
       const wa = (weights[a] && Number(weights[a]) > 0) ? Number(weights[a]) : 1;
@@ -155,9 +161,8 @@ export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
       if (scoreA !== scoreB) return scoreA - scoreB;
       return ca - cb;
     });
-  }
-  if (strategy === 'lowest-latency' && deps.latencyHistogram && typeof deps.latencyHistogram.snapshot === 'function') {
-    return list.sort((a, b) => {
+  } else if (strategy === 'lowest-latency' && deps.latencyHistogram && typeof deps.latencyHistogram.snapshot === 'function') {
+    list = list.sort((a, b) => {
       const sa = deps.latencyHistogram.snapshot(a);
       const sb = deps.latencyHistogram.snapshot(b);
       const la = (sa && Number.isFinite(sa.p95)) ? sa.p95 : ((sa && Number.isFinite(sa.avg)) ? sa.avg : 500);
@@ -165,6 +170,25 @@ export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
       return la - lb;
     });
   }
+
+  // Preemptively deprioritize keys projected to exhaust before quota window reset (#549)
+  const runway = deps.quotaRunway ?? deps.pool?.state?.quotaRunway;
+  if (runway && typeof runway.isExhaustingBeforeReset === 'function' && list.length > 1) {
+    const now = typeof deps.now === 'function' ? deps.now() : (Number(deps.now) || Date.now());
+    const healthy = [];
+    const exhausting = [];
+    for (const ref of list) {
+      if (runway.isExhaustingBeforeReset(ref, now)) {
+        exhausting.push(ref);
+      } else {
+        healthy.push(ref);
+      }
+    }
+    if (healthy.length > 0 && exhausting.length > 0) {
+      return healthy.concat(exhausting);
+    }
+  }
+
   return list;
 }
 
@@ -221,4 +245,3 @@ export function budgetVerdict(spend, budget) {
   const ratio = spend / budget;
   return { spend, budget, ratio, warn: ratio >= 0.8, exceeded: ratio >= 1 };
 }
-