@goodandready/dsh-key-rotation 0.8.63 → 0.8.65

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.8.65 - 2026-10-18
+
+### Features
+- **Traffic Smoothing Micro-Queue (#496)**:
+  - Leaky bucket traffic smoother (`lib/traffic-smoother.js`) absorbs short micro-bursts ($\le 1$s) across multi-agent workflows without tripping upstream per-second or per-minute rate limits or triggering cooldown churning.
+  - Configurable `trafficSmoothingBurst` (default 5 or `ceil(rpmLimit/12)`) and `maxQueueWaitMs` (default 800ms).
+  - If scheduled micro-queue delay exceeds `maxQueueWaitMs`, the smoother flags burst overflow, immediately rotating to the next candidate key in the pool.
+  - Live metric `smoothedRequests` exposed on provider status, with `TRAFFIC_SMOOTHED` audit events.
+- **Accurate Dynamic Provider Limits & Canonical Presets (#503)**:
+  - Header limits detector (`lib/provider-limits-detector.js`): extracts dynamic rate limit headers (`x-ratelimit-limit-*`, `x-ratelimit-remaining-*`, `x-ratelimit-reset-*`, `anthropic-ratelimit-*`, `retry-after`) from upstream provider HTTP responses into `pool.state.detectedLimits`.
+  - Canonical provider presets catalog for DeepSeek, Groq, OpenCode, Anthropic, OpenAI, SiliconFlow, Mistral, Gemini, and OpenRouter with standard RPM, TPM, burst capacity, and calendar reset window specifications.
+  - Endpoint `GET/POST /dsh-key-rotation/preset-limits` to query and auto-apply canonical limits to configured providers.
+  - WebUI button `⚡ Preset Limits` for 1-click rate limit configuration and live upstream limits indicator badge (`⚡ 60 RPM · 100k TPM`).
+
+## 0.8.64 - 2026-10-18
+
+### Features
+- **Permanent Auth Pause & Granular Error Policies (#501)**:
+  - Differentiated error actions: upstream authentication failures (HTTP 401, 403, `invalid_api_key`, `unauthorized`) immediately place the failing key into a permanent auth pause state (`pausedRefs.add`, `pauseReasons.set('AUTH_FAILURE_PAUSED')`, `failedUntil: Infinity`, `KEY_AUTH_PAUSED`).
+  - Dead or unauthorized keys are stopped from waking up repeatedly every 60s cooldown, preventing repetitive broken dispatches.
+  - Granular soft error handling: transient infrastructure drops (HTTP 502, 503, 504, `TIMEOUT`, socket drops) receive a short flat cooldown (<=10s) without doubling exponential penalty counters or incrementing toward recoverable quarantine.
+  - Successful Test Matrix / manual re-test probe automatically unpauses the key.
+- **Automatic Model Capabilities Discovery & Routing (#500)**:
+  - In `lib/sandbox.js` (`probeModels`), parse and return array of supported model IDs from upstream `/models` (`body.data.map(m => m.id)`).
+  - Discovered model capabilities are cached per key (`pool.state.modelCapabilities: Map<ref, Set<modelId>>`).
+  - In `lib/resolver.js` and `lib/rotate.js`, filter candidate keys for a requested model so prompts are never dispatched to a key that doesn't support that model (e.g., DeepSeek-R1 vs DeepSeek-Chat V3). Keys not yet probed are optimistically allowed.
+  - Atomic persistence across restarts: `pausedRefs`, `pauseReasons`, and `modelCapabilities` serialize and restore atomically via `lib/persistence.js`.
+  - Settings Card UI: Display `Auth Paused (401/403)` status badge and discovered model count badges (`🤖 Nm`) on configured keys.
+
 ## 0.8.63 - 2026-10-16
 
 ### Added

package/README.md

@@ -67,6 +67,10 @@
 - **📡 Status extras**: per-provider `circuit` plus `meta.expectedClones` / `meta.notifyQueue`.
 - **🧪 Smoke harness**: scripted 429 → next-key → success path in `test/smoke-rotation-080.test.mjs`.
 
+### 🚀 What's New in v0.8.65
+- **⚡ Leaky Bucket Traffic Smoothing (#496)**: Micro-queue smoothing absorbs rapid multi-agent burst spikes ($\le 1$s) without triggering unnecessary 429 errors or cooldown churning, with zero-delay burst capacity and early failover rotation on queue overflow.
+- **📊 Dynamic Upstream Rate Limits & Presets (#503)**: Dynamic parsing of provider rate limit headers (`x-ratelimit-*`, `anthropic-ratelimit-*`, `retry-after`), live badge display on keys, and 1-click `⚡ Preset Limits` button applying canonical RPM/TPM presets for DeepSeek, Groq, Anthropic, OpenAI, Gemini, and more.
+
 ### 🛠️ What's New in v0.7.33 (Stability & Bugfix Release)
 - **🔍 Resolved Key Probing BaseURL**: Fixed `resolveBaseUrl` to map key credential refs to owning provider pools, restoring live `probeModels` testing.
 - **🛡️ Guarded Cascade Recursion**: Prevented call stack overflow in cross-provider failover when circular cascade chains occur.

package/README.ru.md

@@ -36,6 +36,10 @@
 
 ---
 
+### 🚀 Что нового в v0.8.65
+- **⚡ Сглаживание трафика (Traffic Smoothing Micro-Queue) (#496)**: Микро-очередь leaky bucket сглаживает кратковременные пики нагрузки (<=1с) от мультиагентных вызовов без лишних ошибок 429 и лишних кулдаунов. При превышении таймаута ожидания микро-очереди запрос автоматически переключается на следующий ключ в пуле.
+- **📊 Динамическое определение лимитов провайдеров и пресеты (#503)**: Автоматический парсинг заголовков `x-ratelimit-*`, `anthropic-ratelimit-*`, `retry-after` с отображением актуальных лимитов прямо на карточке ключа, а также кнопка в 1 клик `⚡ Preset Limits` с каноническими пресетами для DeepSeek, Groq, Anthropic, OpenAI, Gemini и др.
+
 ### 🚀 Что нового в v0.8.11 (обновление в один клик и quality gate)
 
 - **Обновление плагина в карточке настроек**: текущая/последняя версия и кнопка установки без выхода из DSH (#307).

package/README.zh.md

@@ -38,6 +38,10 @@
 
 ## ⚡ 概述与核心痛点
 
+### 🚀 v0.8.65 新特性
+- **⚡ 流量平滑微队列 (Traffic Smoothing Micro-Queue) (#496)**: 漏桶微队列平滑多智能体调用中的毫秒级突发并发，避免触发不必要的429限流与冷却流转。队列等待超限时自动轮转至池中下一个候选密钥。
+- **📊 动态上游限制检测与预设规则 (#503)**: 自动提取上游响应头中的限流数据 (`x-ratelimit-*`, `anthropic-ratelimit-*`, `retry-after`)，并在前端展示实时配额状态；支持一键应用 DeepSeek、Groq、Anthropic、OpenAI、Gemini 等官方规范预设限制。
+
 ### 🚀 v0.8.11 新特性（一键更新与质量门禁）
 
 - **设置卡片中的插件更新器**：查看当前/最新版本并一键安装（#307）。

package/lib/client.js

@@ -98,6 +98,12 @@ window.__ModuleLoader__.load({
       bulkImportSuccess: 'Imported {n} keys',
       keyPaused: 'Paused',
       keyRevoked: 'Revoked (401)',
+      keyAuthPaused: 'Auth Paused (401/403)',
+      presetLimitsBtn: '⚡ Preset Limits',
+      presetApplied: 'Applied {prov} preset limits ({rpm} RPM / {tpm} TPM)',
+      presetNone: 'No canonical preset for this provider',
+      detectedLimitsLabel: 'Upstream: {rpm} RPM · {tpm} TPM',
+      trafficSmoothingLabel: 'Traffic Smoothing (Burst)',
       pauseKey: 'Pause key from rotation',
       resumeKey: 'Resume key rotation',
       sparklineTraffic: 'Traffic Trend',
@@ -299,6 +305,12 @@ window.__ModuleLoader__.load({
       bulkImportSuccess: '已导入 {n} 个密钥',
       keyPaused: '已暂停',
       keyRevoked: '已撤销 (401)',
+      keyAuthPaused: '身份验证失败已暂停 (401/403)',
+      presetLimitsBtn: '⚡ 预设限制',
+      presetApplied: '已应用 {prov} 预设限制 ({rpm} RPM / {tpm} TPM)',
+      presetNone: '未找到该提供商预设规则',
+      detectedLimitsLabel: '上游限制：{rpm} RPM · {tpm} TPM',
+      trafficSmoothingLabel: '流量平滑 (突发并发)',
       pauseKey: '暂停此密钥轮换',
       resumeKey: '恢复此密钥轮换',
       sparklineTraffic: '流量趋势',
@@ -1554,6 +1566,31 @@ window.__ModuleLoader__.load({
       };
 
       const [validating, setValidating] = React.useState('');
+      const [presetNotice, setPresetNotice] = React.useState('');
+      const applyPreset = async (pIndex, provName) => {
+        try {
+          const r = await fetch('/dsh-key-rotation/preset-limits?provider=' + encodeURIComponent(provName));
+          const data = await r.json();
+          if (data && data.preset) {
+            setField((cur) => {
+              const providers = [...(cur.providers ?? [])];
+              const ent = { ...providers[pIndex] };
+              if (data.preset.rpmLimit) ent.rpmLimit = data.preset.rpmLimit;
+              if (data.preset.tpmLimit) ent.tpmLimit = data.preset.tpmLimit;
+              providers[pIndex] = ent;
+              return { ...cur, providers };
+            });
+            setPresetNotice(t('presetApplied').replace('{prov}', provName).replace('{rpm}', String(data.preset.rpmLimit)).replace('{tpm}', String(data.preset.tpmLimit)));
+            setTimeout(() => setPresetNotice(''), 4000);
+          } else {
+            setPresetNotice(t('presetNone'));
+            setTimeout(() => setPresetNotice(''), 3000);
+          }
+        } catch (err) {
+          setPresetNotice(String(err?.message || err));
+          setTimeout(() => setPresetNotice(''), 3000);
+        }
+      };
       const [validationResult, setValidationResult] = React.useState({});
       const validateBeforeSave = (ref, value) => {
         setValidating(ref);
@@ -1952,6 +1989,7 @@ window.__ModuleLoader__.load({
         if (isPaused) return { color: 'var(--dsw-alias-state-warn-primary)', text: t('keyPaused'), ready: false, paused: true };
         const hit = keyInfo(providerId, ref);
         if (!hit) return null;
+        if (hit.authPaused || hit.pauseReason === 'AUTH_FAILURE_PAUSED') return { color: 'var(--dsw-alias-state-error-primary)', text: t('keyAuthPaused'), ready: false, authPaused: true };
         if (hit.paused) return { color: 'var(--dsw-alias-state-warn-primary)', text: t('keyPaused'), ready: false, paused: true };
         if (hit.expired) return { color: 'var(--dsw-alias-state-error-primary)', text: t('keyExpired'), ready: false, expired: true };
         if (hit.broken || hit.revoked || hit.status === 'revoked') return { color: 'var(--dsw-alias-state-error-primary)', text: t('keyRevoked'), ready: false, revoked: true };
@@ -2124,6 +2162,28 @@ window.__ModuleLoader__.load({
           if (info && info.broken) {
             meta.push(h('button', { key: 'rt', className: 'krot-btn', onClick: () => retestBroken(key), title: t('retestBroken') }, t('retestBroken')));
           }
+          if (info && info.detectedLimits) {
+            const dl = info.detectedLimits;
+            const parts = [];
+            if (dl.rpmLimit) parts.push(dl.rpmLimit + ' RPM');
+            if (dl.tpmLimit) parts.push(dl.tpmLimit + ' TPM');
+            if (parts.length > 0) {
+              meta.push(h('span', {
+                key: 'dl',
+                className: 'krot-tail',
+                title: 'Live upstream limits:\n' + JSON.stringify(dl, null, 2),
+                style: { fontSize: '11px', opacity: 0.8, color: 'var(--dsw-alias-brand-primary)' }
+              }, '⚡ ' + parts.join(' · ')));
+            }
+          }
+          if (info && info.modelCapabilities && info.modelCapabilities.length > 0) {
+            meta.push(h('span', {
+              key: 'caps',
+              className: 'krot-tail',
+              title: 'Discovered models (' + info.modelCapabilities.length + '):\n' + info.modelCapabilities.join('\n'),
+              style: { fontSize: '11px', opacity: 0.85 }
+            }, '🤖 ' + info.modelCapabilities.length + 'm'));
+          }
           meta.push(h('span', { key: 'a', className: 'krot-acts' },
             btn('↑', () => moveKey(pIndex, kIndex, -1), { disabled: kIndex === 0, title: t('moveUp') }),
             btn('↓', () => moveKey(pIndex, kIndex, 1), { disabled: kIndex === keys.length - 1, title: t('moveDown') }),
@@ -2357,6 +2417,8 @@ window.__ModuleLoader__.load({
               });
             }, { title: t('sortUsage') }),
             h('select', { className: 'krot-in', value: entry.provider, onChange: (e) => setProvider(pIndex, e.target.value) }, options),
+            btn(t('presetLimitsBtn') || '⚡ Preset Limits', () => applyPreset(pIndex, entry.provider), { title: t('presetLimitsBtn') || '⚡ Preset Limits', disabled: !entry.provider.trim() || !stateRef.current.writable }),
+            presetNotice ? h('span', { className: 'krot-badge krot-badge-ok', style: { marginLeft: '4px' } }, presetNotice) : null,
             (() => {
               const ps = status[entry.provider];
               const score = ps && typeof ps.healthScore === 'number' ? ps.healthScore : null;

package/lib/error-taxonomy.js

@@ -36,9 +36,11 @@ export function classifyFailure(failureOrPayload) {
   if (status === 429 || code === 'RATE_LIMIT' || code === 'RESOURCE_EXHAUSTED' || code === 'QUOTA') {
     return { action: 'switch', code: status ? '429' : (code || 'RATE_LIMIT'), soft: false, reason: 'quota' };
   }
-  if (SWITCH_STATUS.has(status)) {
-    const soft = SOFT_FAILURE_CODES.has(String(status));
-    return { action: 'switch', code: String(status), soft, reason: 'http' };
+  const numCode = Number(code);
+  if (SWITCH_STATUS.has(status) || (numCode > 0 && SWITCH_STATUS.has(numCode)) || SOFT_FAILURE_CODES.has(code)) {
+    const effCode = status ? String(status) : (numCode > 0 ? String(numCode) : code);
+    const soft = SOFT_FAILURE_CODES.has(effCode);
+    return { action: 'switch', code: effCode, soft, reason: 'http' };
   }
   if (SURFACE_STATUS.has(status)) {
     return { action: 'surface', code: String(status), soft: false, reason: 'client' };

package/lib/heal.js

@@ -90,6 +90,10 @@ export async function autoUnbreakBrokenKeys(pools, probeFn, now = Date.now(), {
           pool.state.failedUntil?.delete(ref);
           pool.state.failCounts?.delete(ref);
           pool.state.authFailCounts?.delete(ref);
+          if (Array.isArray(res.models) && res.models.length > 0) {
+            if (!pool.state.modelCapabilities) pool.state.modelCapabilities = new Map();
+            pool.state.modelCapabilities.set(ref, new Set(res.models));
+          }
           if (Array.isArray(pool.state.events)) {
             pool.state.events.push({ at: now, ref, reason: 'auto-unbreak', cooldownMs: 0, type: 'heal' });
             if (pool.state.events.length > 50) pool.state.events.shift();

package/lib/index.js

@@ -33,6 +33,7 @@ import { registerOpsRoutes } from './routes-ops.js';
 import { registerPluginUpdater } from './plugin-updater.js';
 import { notifySwitch, notifyExhaustion, notifyEarlyWarning, pushEvent } from './notify-events.js';
 import { QUOTA_WINDOW_TYPES } from './quota-window.js';
+import { TrafficSmoother } from './traffic-smoother.js';
 import { getLogger } from './logger.js';
 import { createSandboxService } from './sandbox-service.js';
 import { checkBudgetAndHealthAlerts } from './budget-monitor.js';
@@ -198,6 +199,7 @@ export function apply(ctx, config = {}) {
   const webhookSender = new WebhookSender({ fetchImpl: globalThis.fetch });
   const alertDebouncer = new AlertDebouncer({ sender: webhookSender, debounceMs: 2000 });
   const moduleNotifyQueue = new NotifyQueue({ send: (url, payload) => alertDebouncer.enqueue(url, payload) });
+  const trafficSmoother = new TrafficSmoother({ maxQueueWaitMs: 800 });
 
   const sandboxService = createSandboxService({ getRuntime: () => buildRuntime() });
   const { ensureSandboxRunner, probeRef, lastTestCache } = sandboxService;
@@ -355,7 +357,7 @@ export function apply(ctx, config = {}) {
       switchNotifyThrottleMs: cfg.switchNotifyThrottleMs ?? 60000,
       warnBelowHealthy: cfg.warnBelowHealthy ?? 0, latencySloMs: cfg.latencySloMs ?? 0,
       index, pools,
-      breaker: moduleBreaker, notifyQueue: moduleNotifyQueue, concurrencyTracker, quotaStore, latencyHistogram,
+      breaker: moduleBreaker, notifyQueue: moduleNotifyQueue, concurrencyTracker, quotaStore, latencyHistogram, trafficSmoother,
       providerTags, providerBudgets, poolByRef, providerToPool, modelPoolByProvider,
       cloneIds, expectedClones,
       circuitBreakerEnabled: cfg.circuitBreakerEnabled ?? true,
@@ -377,6 +379,7 @@ export function apply(ctx, config = {}) {
         buildRuntime,
         currentPool: () => dispatchStorage.getStore()?.pool,
         currentSession: () => dispatchStorage.getStore()?.sessionId,
+        currentModel: () => dispatchStorage.getStore()?.model,
         onPicked: (pool, candidate, meta) => {
           const store = dispatchStorage.getStore();
           if (store && store.pool === pool) {
@@ -433,6 +436,7 @@ export function apply(ctx, config = {}) {
     MARKER,
     finishError,
     setRotateStartMs: (v) => { _rotateStartMs = v; },
+    trafficSmoother,
     quotaStore,
     circuitBreaker: moduleBreaker,
     now: nowMono,

package/lib/ops-keys.js

@@ -22,7 +22,9 @@ import {
   DRAIN_PATH,
   DISCOVER_PATH,
   AUTO_IMPORT_PATH,
+  PRESET_LIMITS_PATH,
 } from './ops-paths.js';
+import { lookupPreset, CANONICAL_PROVIDER_PRESETS } from './provider-limits-detector.js';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -539,4 +541,40 @@ ctx.effect(() => ctx.webServer.register({
   },
 }), 'dsh-key-rotation: auto-import route');
 
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: PRESET_LIMITS_PATH,
+    handler: async (req, res) => {
+      if (!isTrustedBridgeRequest(req)) {
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'Forbidden' }));
+        return;
+      }
+      if (req.method === 'GET') {
+        const urlObj = new URL(req.url, 'http://127.0.0.1');
+        const prov = urlObj.searchParams.get('provider');
+        if (prov) {
+          const preset = lookupPreset(prov);
+          json(res, 200, { ok: true, provider: prov, preset });
+          return;
+        }
+        json(res, 200, { ok: true, presets: CANONICAL_PROVIDER_PRESETS });
+        return;
+      }
+      if (req.method === 'POST') {
+        const body = await readJson(req);
+        const prov = body?.provider;
+        const preset = lookupPreset(prov);
+        if (!preset) {
+          json(res, 404, { ok: false, error: `No canonical preset found for provider '${prov}'` });
+          return;
+        }
+        json(res, 200, { ok: true, provider: prov, preset });
+        return;
+      }
+      res.writeHead(405, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: 'Method Not Allowed' }));
+    },
+  }), 'dsh-key-rotation: preset limits route');
+
 }

package/lib/ops-paths.js

@@ -17,3 +17,4 @@ export const DRAIN_PATH = '/dsh-key-rotation/drain';
 export const TEST_MATRIX_PATH = '/dsh-key-rotation/test-matrix';
 export const DISCOVER_PATH = '/dsh-key-rotation/discover';
 export const AUTO_IMPORT_PATH = '/dsh-key-rotation/auto-import';
+export const PRESET_LIMITS_PATH = '/dsh-key-rotation/preset-limits';

package/lib/ops-status.js

@@ -120,7 +120,10 @@ ctx.effect(() => ctx.webServer.register({
           expired: pool.expiresAt?.[ref] !== undefined && now >= pool.expiresAt[ref],
           broken: pool.state.brokenUntil?.has(ref) ?? false,
           paused: isKeyPaused(pool, ref),
+          pauseReason: pool.state.pauseReasons?.get?.(ref) ?? null,
           revoked: isKeyRevoked(pool, ref),
+          modelCapabilities: pool.state.modelCapabilities?.get?.(ref) ? [...pool.state.modelCapabilities.get(ref)] : null,
+          detectedLimits: pool.state.detectedLimits?.get?.(ref) ?? null,
           modelQuota,
           modelPools: activeModelPools.map(mp => mp.base),
         });
@@ -170,6 +173,7 @@ ctx.effect(() => ctx.webServer.register({
         pauseOnBudget: (providerBudgets?.get ? providerBudgets.get(pool.base) : providerBudgets?.[pool.base])?.pauseOnBudget ?? false,
         routingStrategy: pool.routingStrategy ?? runtime.routingStrategy ?? 'round-robin',
         proactiveRateLimitGuard: pool.proactiveRateLimitGuard ?? runtime.proactiveRateLimitGuard ?? true,
+        smoothedRequests: pool.state.smoothedRequests ?? 0,
       });
       } catch (e) {
         (ctx?.logger ? ctx.logger('dsh-key-rotation') : null)?.warn?.(`[dsh-key-rotation] status: pool ${pool.base} failed: ${String(e?.message ?? e)} ${e?.stack ?? ''}`);

package/lib/ops-test.js

@@ -73,16 +73,24 @@ ctx.effect(() => ctx.webServer.register({
         lastTestCache.set(ref, cached);
         if (cached.ok) {
           for (const st of poolState.values()) {
-            if (st.failedUntil?.has(ref) || st.failCounts?.has(ref) || st.brokenUntil?.has(ref) || st.revokedRefs?.has(ref)) {
-              st.failedUntil?.delete(ref);
-              st.failCounts?.delete(ref);
-              st.authFailCounts?.delete(ref);
-              st.brokenUntil?.delete(ref);
-              st.revokedRefs?.delete(ref);
+            st.failedUntil?.delete(ref);
+            st.failCounts?.delete(ref);
+            st.authFailCounts?.delete(ref);
+            st.brokenUntil?.delete(ref);
+            st.revokedRefs?.delete(ref);
+            if (st.pausedRefs instanceof Set) st.pausedRefs.delete(ref);
+            else if (Array.isArray(st.pausedRefs)) {
+              const pIdx = st.pausedRefs.indexOf(ref);
+              if (pIdx >= 0) st.pausedRefs.splice(pIdx, 1);
+            }
+            st.pauseReasons?.delete(ref);
+            if (Array.isArray(cached.models) && cached.models.length > 0) {
+              if (!st.modelCapabilities) st.modelCapabilities = new Map();
+              st.modelCapabilities.set(ref, new Set(cached.models));
             }
           }
         }
-        json(res, 200, { ok: cached.ok, ref, tail, source, probe, code: cached.code, latencyMs: cached.latencyMs, modelsCount: cached.modelsCount });
+        json(res, 200, { ok: cached.ok, ref, tail, source, probe, code: cached.code, latencyMs: cached.latencyMs, modelsCount: cached.modelsCount, models: cached.models ?? [] });
         return;
       }
       json(res, 200, { ok: true, ref, tail, source });
@@ -179,6 +187,16 @@ ctx.effect(() => ctx.webServer.register({
               st.authFailCounts?.delete(ref);
               st.brokenUntil?.delete(ref);
               st.revokedRefs?.delete(ref);
+              if (st.pausedRefs instanceof Set) st.pausedRefs.delete(ref);
+              else if (Array.isArray(st.pausedRefs)) {
+                const pIdx = st.pausedRefs.indexOf(ref);
+                if (pIdx >= 0) st.pausedRefs.splice(pIdx, 1);
+              }
+              st.pauseReasons?.delete(ref);
+              if (Array.isArray(cached.models) && cached.models.length > 0) {
+                if (!st.modelCapabilities) st.modelCapabilities = new Map();
+                st.modelCapabilities.set(ref, new Set(cached.models));
+              }
             }
           }
           results.push({
@@ -189,6 +207,7 @@ ctx.effect(() => ctx.webServer.register({
             code: cached.code,
             latencyMs: cached.latencyMs,
             modelsCount: cached.modelsCount,
+            models: cached.models ?? [],
           });
         } catch (err) {
           results.push({

package/lib/persistence.js

@@ -44,6 +44,32 @@ export class StatePersistence {
             revokedRefs.push(...st.revokedRefs);
           }
         }
+        const pausedRefs = [];
+        if (st && st.pausedRefs) {
+          if (typeof st.pausedRefs.forEach === 'function') {
+            st.pausedRefs.forEach((r) => pausedRefs.push(r));
+          } else if (Array.isArray(st.pausedRefs)) {
+            pausedRefs.push(...st.pausedRefs);
+          }
+        }
+        const pauseReasons = {};
+        if (st && st.pauseReasons && typeof st.pauseReasons.forEach === 'function') {
+          st.pauseReasons.forEach((reason, ref) => {
+            if (typeof reason === 'string') pauseReasons[ref] = reason;
+          });
+        }
+        const modelCapabilities = {};
+        if (st && st.modelCapabilities && typeof st.modelCapabilities.forEach === 'function') {
+          st.modelCapabilities.forEach((caps, ref) => {
+            if (caps && typeof caps.forEach === 'function') {
+              const arr = [];
+              caps.forEach((m) => { if (typeof m === 'string') arr.push(m); });
+              if (arr.length > 0) modelCapabilities[ref] = arr;
+            } else if (Array.isArray(caps) && caps.length > 0) {
+              modelCapabilities[ref] = caps.filter((m) => typeof m === 'string');
+            }
+          });
+        }
         const tokenUsage = {};
         if (st && st.tokenUsage && typeof st.tokenUsage.forEach === 'function') {
           st.tokenUsage.forEach((entry, ref) => {
@@ -109,6 +135,9 @@ export class StatePersistence {
           lastUsed: typeof st?.lastUsed === 'string' ? st.lastUsed : null,
         };
         if (revokedRefs.length > 0) outPool.revokedRefs = revokedRefs;
+        if (pausedRefs.length > 0) outPool.pausedRefs = pausedRefs;
+        if (Object.keys(pauseReasons).length > 0) outPool.pauseReasons = pauseReasons;
+        if (Object.keys(modelCapabilities).length > 0) outPool.modelCapabilities = modelCapabilities;
         if (Object.keys(tokenUsage).length > 0) outPool.tokenUsage = tokenUsage;
         if (Object.keys(costDays).length > 0) outPool.costDays = costDays;
         if (Object.keys(costPerKey).length > 0) outPool.costPerKey = costPerKey;
@@ -200,6 +229,26 @@ export class StatePersistence {
             if (typeof r === 'string') state.revokedRefs.add(r);
           }
         }
+        if (Array.isArray(saved.pausedRefs)) {
+          if (!state.pausedRefs) state.pausedRefs = new Set();
+          for (const r of saved.pausedRefs) {
+            if (typeof r === 'string') state.pausedRefs.add(r);
+          }
+        }
+        if (saved.pauseReasons && typeof saved.pauseReasons === 'object' && !Array.isArray(saved.pauseReasons)) {
+          if (!state.pauseReasons) state.pauseReasons = new Map();
+          for (const [ref, reason] of Object.entries(saved.pauseReasons)) {
+            if (typeof reason === 'string') state.pauseReasons.set(ref, reason);
+          }
+        }
+        if (saved.modelCapabilities && typeof saved.modelCapabilities === 'object' && !Array.isArray(saved.modelCapabilities)) {
+          if (!state.modelCapabilities) state.modelCapabilities = new Map();
+          for (const [ref, list] of Object.entries(saved.modelCapabilities)) {
+            if (Array.isArray(list)) {
+              state.modelCapabilities.set(ref, new Set(list.filter((m) => typeof m === 'string')));
+            }
+          }
+        }
         if (saved.tokenUsage && typeof saved.tokenUsage === 'object' && !Array.isArray(saved.tokenUsage)) {
           for (const [ref, entry] of Object.entries(saved.tokenUsage)) {
             if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;

package/lib/pool-builder.js

@@ -37,6 +37,8 @@ export function buildPoolItem({
   labels = null,
   pinnedRef = null,
   useKeyRef = null,
+  trafficSmoothingBurst = null,
+  maxQueueWaitMs = null,
 }) {
   const seen = new Set();
   const indexed = (Array.isArray(keys) ? keys : []).map((key, index) => ({ ref: typeof key === 'string' ? key.trim() : '', index }))
@@ -135,6 +137,12 @@ const weightsMap = {};
     proactiveRateLimitGuard: poolGuard,
     labels: labelsMap,
     pinnedRef: cleanPinned,
+    trafficSmoothingBurst: typeof trafficSmoothingBurst === 'number' && Number.isFinite(trafficSmoothingBurst) && trafficSmoothingBurst > 0
+      ? Math.floor(trafficSmoothingBurst)
+      : (typeof rpmLimit === 'number' && rpmLimit > 0 ? Math.max(2, Math.ceil(rpmLimit / 12)) : 5),
+    maxQueueWaitMs: typeof maxQueueWaitMs === 'number' && Number.isFinite(maxQueueWaitMs) && maxQueueWaitMs >= 0
+      ? Math.floor(maxQueueWaitMs)
+      : 800,
   };
 }
 
@@ -175,6 +183,8 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
       model: null,
       labels: p.labels,
       pinnedRef: p.pinnedRef ?? p.useKeyRef,
+      trafficSmoothingBurst: p.trafficSmoothingBurst ?? cfg.trafficSmoothingBurst,
+      maxQueueWaitMs: p.maxQueueWaitMs ?? cfg.maxQueueWaitMs,
     }, provRpm, provTpm, provConcurrency);
     if (pool) {
       for (const ref of pool.refs) {
@@ -203,6 +213,8 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
         quotas: mp.quotas,
         labels: mp.labels ?? p.labels,
         pinnedRef: mp.pinnedRef ?? mp.useKeyRef ?? p.pinnedRef ?? p.useKeyRef,
+        trafficSmoothingBurst: mp.trafficSmoothingBurst ?? p.trafficSmoothingBurst ?? cfg.trafficSmoothingBurst,
+        maxQueueWaitMs: mp.maxQueueWaitMs ?? p.maxQueueWaitMs ?? cfg.maxQueueWaitMs,
       }, modelRpm, modelTpm, modelConcurrency);
       if (!mpool) continue;
       mpool.basePool = pool;

package/lib/pool-state.js

@@ -3,13 +3,18 @@
 const MAP_FIELDS = [
   'failedUntil', 'failCounts', 'authFailCounts', 'brokenUntil', 'costPerKey',
   'lastUsedAt', 'usageCounts', 'byModel', 'usageDays', 'quotaWindows', 'costDays',
-  'tokenUsage', 'rpmWindows', 'tpmWindows', 'sessionSticky',
+  'tokenUsage', 'rpmWindows', 'tpmWindows', 'sessionSticky', 'modelCapabilities', 'pauseReasons', 'detectedLimits',
 ];
 
+const SET_FIELDS = ['pausedRefs', 'revokedRefs'];
+
 export function initializePoolState(state = {}) {
   for (const key of MAP_FIELDS) {
     if (!(state[key] instanceof Map)) state[key] = new Map();
   }
+  for (const key of SET_FIELDS) {
+    if (!(state[key] instanceof Set)) state[key] = new Set(Array.isArray(state[key]) ? state[key] : []);
+  }
   if (!Array.isArray(state.events)) state.events = [];
   if (!Number.isSafeInteger(state.pointer) || state.pointer < 0) state.pointer = 0;
   if (typeof state.lastUsed !== 'string') state.lastUsed = null;
@@ -21,5 +26,7 @@ export function initializePoolState(state = {}) {
 export function hasPoolActivity(state) {
   return state.pointer !== 0 || state.lastUsed !== null || state.events.length > 0 ||
     MAP_FIELDS.some((key) => state[key].size > 0) ||
-    (state.lastSuccessAt?.size ?? 0) > 0;
+    (state.lastSuccessAt?.size ?? 0) > 0 ||
+    (state.pausedRefs?.size ?? 0) > 0 ||
+    (state.revokedRefs?.size ?? 0) > 0;
 }

package/lib/provider-limits-detector.js

@@ -0,0 +1,173 @@
+// lib/provider-limits-detector.js — accurate dynamic provider limits and presets (#503).
+
+export const CANONICAL_PROVIDER_PRESETS = {
+  deepseek: {
+    rpmLimit: 60,
+    tpmLimit: 100000,
+    trafficSmoothingBurst: 5,
+    quotaResetWindow: 'midnight_utc',
+    displayName: 'DeepSeek Official',
+  },
+  groq: {
+    rpmLimit: 30,
+    tpmLimit: 30000,
+    trafficSmoothingBurst: 5,
+    quotaResetWindow: 'per-minute',
+    displayName: 'Groq Cloud',
+  },
+  opencode: {
+    rpmLimit: 120,
+    tpmLimit: 200000,
+    trafficSmoothingBurst: 10,
+    quotaResetWindow: 'midnight_utc',
+    displayName: 'OpenCode Zen',
+  },
+  anthropic: {
+    rpmLimit: 50,
+    tpmLimit: 100000,
+    trafficSmoothingBurst: 5,
+    quotaResetWindow: 'per-minute',
+    displayName: 'Anthropic Claude',
+  },
+  openai: {
+    rpmLimit: 60,
+    tpmLimit: 150000,
+    trafficSmoothingBurst: 10,
+    quotaResetWindow: 'per-minute',
+    displayName: 'OpenAI API',
+  },
+  siliconflow: {
+    rpmLimit: 60,
+    tpmLimit: 100000,
+    trafficSmoothingBurst: 5,
+    quotaResetWindow: 'per-minute',
+    displayName: 'SiliconFlow',
+  },
+  mistral: {
+    rpmLimit: 60,
+    tpmLimit: 100000,
+    trafficSmoothingBurst: 5,
+    quotaResetWindow: 'per-minute',
+    displayName: 'Mistral AI',
+  },
+  gemini: {
+    rpmLimit: 60,
+    tpmLimit: 1000000,
+    trafficSmoothingBurst: 10,
+    quotaResetWindow: 'midnight_pst',
+    displayName: 'Google Gemini',
+  },
+  openrouter: {
+    rpmLimit: 200,
+    tpmLimit: 500000,
+    trafficSmoothingBurst: 15,
+    quotaResetWindow: 'per-minute',
+    displayName: 'OpenRouter',
+  },
+};
+
+/**
+ * Extract rate limit and quota information from HTTP response headers.
+ * @param {Headers|Record<string, string>} rawHeaders
+ * @returns {object|null}
+ */
+export function extractProviderLimits(rawHeaders) {
+  if (!rawHeaders) return null;
+  const headers = {};
+  if (typeof rawHeaders.forEach === 'function') {
+    rawHeaders.forEach((val, key) => { headers[key.toLowerCase()] = String(val); });
+  } else if (typeof rawHeaders === 'object') {
+    for (const [k, v] of Object.entries(rawHeaders)) {
+      if (typeof k === 'string') headers[k.toLowerCase()] = String(v ?? '');
+    }
+  }
+
+  const getNum = (...names) => {
+    for (const name of names) {
+      const val = headers[name];
+      if (val !== undefined && val !== null && val !== '') {
+        const n = Number(val);
+        if (Number.isFinite(n) && n >= 0) return n;
+      }
+    }
+    return undefined;
+  };
+
+  const getSeconds = (...names) => {
+    for (const name of names) {
+      const val = headers[name];
+      if (!val) continue;
+      const str = String(val).trim();
+      // Duration string format "6m0s", "1s", "250ms"
+      const match = /^(\d+(?:\.\d+)?)(s|ms|m|h)?$/i.exec(str);
+      if (match) {
+        const num = parseFloat(match[1]);
+        const unit = (match[2] || 's').toLowerCase();
+        if (unit === 'ms') return Math.max(0.001, num / 1000);
+        if (unit === 's') return num;
+        if (unit === 'm') return num * 60;
+        if (unit === 'h') return num * 3600;
+      }
+      // Check for ISO Date string (e.g., Anthropic reset timestamp)
+      const parsedDate = Date.parse(str);
+      if (Number.isFinite(parsedDate)) {
+        const diffSec = (parsedDate - Date.now()) / 1000;
+        return Math.max(0, diffSec);
+      }
+      const n = Number(str);
+      if (Number.isFinite(n) && n >= 0) return n;
+    }
+    return undefined;
+  };
+
+  const rpmLimit = getNum('x-ratelimit-limit-requests', 'x-ratelimit-limit-rpm', 'ratelimit-limit', 'anthropic-ratelimit-requests-limit');
+  const tpmLimit = getNum('x-ratelimit-limit-tokens', 'x-ratelimit-limit-tpm', 'anthropic-ratelimit-tokens-limit');
+  const remainingRequests = getNum('x-ratelimit-remaining-requests', 'x-ratelimit-remaining', 'anthropic-ratelimit-requests-remaining');
+  const remainingTokens = getNum('x-ratelimit-remaining-tokens', 'anthropic-ratelimit-tokens-remaining');
+  const resetRequests = getSeconds('x-ratelimit-reset-requests', 'x-ratelimit-reset', 'anthropic-ratelimit-requests-reset');
+  const resetTokens = getSeconds('x-ratelimit-reset-tokens', 'anthropic-ratelimit-tokens-reset');
+  const retryAfter = getSeconds('retry-after');
+
+  if (rpmLimit === undefined && tpmLimit === undefined && remainingRequests === undefined && remainingTokens === undefined && resetRequests === undefined && retryAfter === undefined) {
+    return null;
+  }
+
+  const out = {};
+  if (rpmLimit !== undefined) out.rpmLimit = Math.floor(rpmLimit);
+  if (tpmLimit !== undefined) out.tpmLimit = Math.floor(tpmLimit);
+  if (remainingRequests !== undefined) {
+    out.remainingRequests = Math.floor(remainingRequests);
+    out.rpmRemaining = out.remainingRequests;
+  }
+  if (remainingTokens !== undefined) {
+    out.remainingTokens = Math.floor(remainingTokens);
+    out.tpmRemaining = out.remainingTokens;
+  }
+  if (resetRequests !== undefined) {
+    out.resetRequests = resetRequests;
+    out.rpmResetMs = Math.round(resetRequests * 1000);
+  }
+  if (resetTokens !== undefined) {
+    out.resetTokens = resetTokens;
+    out.tpmResetMs = Math.round(resetTokens * 1000);
+  }
+  if (retryAfter !== undefined) {
+    out.retryAfterMs = Math.round(retryAfter * 1000);
+  }
+
+  return out;
+}
+
+/**
+ * Match a configured provider name to canonical preset.
+ * @param {string} providerName
+ * @returns {object|null}
+ */
+export function lookupPreset(providerName) {
+  if (!providerName || typeof providerName !== 'string') return null;
+  const p = providerName.toLowerCase().replace(/[^a-z0-9]/g, '');
+  for (const [key, val] of Object.entries(CANONICAL_PROVIDER_PRESETS)) {
+    if (p.includes(key)) return { ...val, id: key };
+  }
+  return null;
+}

package/lib/resolver.js

@@ -77,6 +77,7 @@ export function createResolver({
   buildRuntime,
   currentPool,
   currentSession,
+  currentModel,
   onPicked,
   latencyHistogram,
   concurrencyTracker,
@@ -88,6 +89,7 @@ export function createResolver({
     // pool that rotate() actually dispatched with decides ownership. A bare
     // resolve outside rotation falls back to the global lookup.
     const requested = currentPool ? currentPool() ?? null : null;
+    const model = resolveOpts?.model ?? currentModel?.() ?? requested?.model ?? null;
     const pool = resolveRefPool(runtime.index, ref, requested);
     if (!pool) {
       const res = await original(ref);
@@ -168,6 +170,11 @@ export function createResolver({
       if (until !== undefined && until > at) continue;
       const candidateExp = pool.expiresAt?.[candidate] ?? pool.basePool?.expiresAt?.[candidate];
       if (candidateExp !== undefined && at >= candidateExp) continue;
+      // Issue #500: skip candidate if modelCapabilities is known and does not include requested model
+      if (model && pool.state.modelCapabilities) {
+        const caps = pool.state.modelCapabilities.get(candidate);
+        if (caps && caps.size > 0 && !caps.has(model)) continue;
+      }
       // Local model token budget: a spent credential is simply not a candidate.
       if (quotaManaged && !isModelQuotaAvailable(pool, candidate, at)) continue;
       const microThrottling = pool.microThrottling ?? runtime.microThrottling ?? false;

package/lib/rotate.js

@@ -35,6 +35,7 @@ import {
 } from './model-quota.js';
 
 import { LOCAL_POOL_EXHAUSTED_CODE } from './resolver.js';
+import { extractProviderLimits } from './provider-limits-detector.js';
 
 export const LOCAL_QUOTA_CODE = 'LOCAL_MODEL_QUOTA_EXHAUSTED';
 
@@ -79,6 +80,7 @@ export function createRotate(deps) {
     circuitBreaker,
     logger,
     schedulePersist,
+    trafficSmoother,
     now = nowMono,
   } = deps;
 
@@ -108,12 +110,19 @@ export function createRotate(deps) {
       const breaker = runtime0.circuitBreakerEnabled === false ? null : circuitBreaker;
       let activePermit = null;
       const sessionId = options?.sessionId ?? options?.session ?? options?.metadata?.sessionId ?? options?.chatId ?? options?.conversationId;
-      const reqStore = { pool, pickedRef: undefined, concurrencyRef: undefined, startMs: now(), sessionId };
+      const reqStore = { pool, pickedRef: undefined, concurrencyRef: undefined, startMs: now(), sessionId, model: options.model };
       setRotateStartMs(reqStore.startMs);
       const wallNow = Date.now();
       const quotaManaged = hasModelQuotaConfig(pool);
       let attemptList = (pool.weightedRefs ?? pool.refs).slice();
       attemptList = attemptList.filter((r) => !isKeyPaused(pool, r) && !isKeyRevoked(pool, r) && !isKeyBroken(pool, r, wallNow) && !isKeyDraining(r));
+      // Issue #500: filter candidate keys by confirmed model capabilities
+      if (options.model && pool.state.modelCapabilities) {
+        attemptList = attemptList.filter((ref) => {
+          const caps = pool.state.modelCapabilities.get(ref);
+          return !caps || caps.size === 0 || caps.has(options.model);
+        });
+      }
       if (pool.pinnedRef && attemptList.includes(pool.pinnedRef)) {
         const pIdx = attemptList.indexOf(pool.pinnedRef);
         if (pIdx > 0) {
@@ -196,7 +205,7 @@ export function createRotate(deps) {
         const _base = pool.cooldownMs ?? cooldownMs;
         const _max = pool.maxCooldownMs ?? maxCooldownMs;
         const _effBase = _retry !== undefined ? Math.max(_base, Math.min(_retry, _max ?? _base * 8)) : _base;
-        const cls = classifyFailure({ code: errCode, message: errMsg });
+        const cls = classifyFailure({ status: Number(errCode) || 0, code: errCode, message: errMsg });
         const _b = recordFailure(pool, targetRef, now(), _effBase, _max, cls.soft, true);
 
         // #337 & #486 (GitHub #24): connect quota-window calendar reset for quota exhaustion
@@ -245,16 +254,26 @@ export function createRotate(deps) {
         }
         if (!pool.state.authFailCounts) pool.state.authFailCounts = new Map();
         if (!pool.state.brokenUntil) pool.state.brokenUntil = new Map();
-        const _cStr = String(errCode ?? '');
-        if (_cStr === 'AUTH' || /auth|unauthorized|invalid[_\s-]?api[_\s-]?key|unauthenticated/i.test(errMsg)) {
+        const _cStr = String(errCode ?? '').toUpperCase();
+        const _isAuth = cls.reason === 'auth' || cls.code === '401' || cls.code === '403' ||
+          _cStr === 'AUTH' || _cStr === '401' || _cStr === '403' ||
+          _cStr === 'PERMISSION_DENIED' || _cStr === 'UNAUTHENTICATED' ||
+          /auth|unauthorized|invalid[_\s-]?api[_\s-]?key|unauthenticated|permission[_\s-]?denied/i.test(errMsg);
+
+        if (_isAuth) {
           const _c2 = (pool.state.authFailCounts.get(targetRef) ?? 0) + 1;
           pool.state.authFailCounts.set(targetRef, _c2);
           if (!pool.state.revokedRefs) pool.state.revokedRefs = new Set();
           pool.state.revokedRefs.add(targetRef);
+          if (!pool.state.pausedRefs) pool.state.pausedRefs = new Set();
+          if (pool.state.pausedRefs instanceof Set) pool.state.pausedRefs.add(targetRef);
+          else if (Array.isArray(pool.state.pausedRefs) && !pool.state.pausedRefs.includes(targetRef)) pool.state.pausedRefs.push(targetRef);
+          if (!pool.state.pauseReasons) pool.state.pauseReasons = new Map();
+          pool.state.pauseReasons.set(targetRef, 'AUTH_FAILURE_PAUSED');
           pool.state.failedUntil.set(targetRef, Infinity);
-          pushEvent(pool, targetRef, 'KEY_REVOKED', 0);
-          logWarn(`[dsh-key-rotation] ${options.provider}: key ${targetRef} permanently REVOKED on auth failure`);
-          // Fan-out revocation across all pools sharing this physical ref (#408):
+          pushEvent(pool, targetRef, 'KEY_AUTH_PAUSED', 0);
+          logWarn(`[dsh-key-rotation] ${options.provider}: key ${targetRef} permanently PAUSED on auth failure (${errCode})`);
+          // Fan-out permanent pause across all pools sharing this physical ref (#408):
           const rAll = buildRuntime();
           const candidatePools = [];
           if (Array.isArray(rAll.pools)) candidatePools.push(...rAll.pools);
@@ -275,8 +294,13 @@ export function createRotate(deps) {
             if (hasRef && other.state) {
               if (!other.state.revokedRefs) other.state.revokedRefs = new Set();
               other.state.revokedRefs.add(targetRef);
+              if (!other.state.pausedRefs) other.state.pausedRefs = new Set();
+              if (other.state.pausedRefs instanceof Set) other.state.pausedRefs.add(targetRef);
+              else if (Array.isArray(other.state.pausedRefs) && !other.state.pausedRefs.includes(targetRef)) other.state.pausedRefs.push(targetRef);
+              if (!other.state.pauseReasons) other.state.pauseReasons = new Map();
+              other.state.pauseReasons.set(targetRef, 'AUTH_FAILURE_PAUSED');
               if (other.state.failedUntil) other.state.failedUntil.set(targetRef, Infinity);
-              pushEvent(other, targetRef, 'KEY_REVOKED', 0);
+              pushEvent(other, targetRef, 'KEY_AUTH_PAUSED', 0);
             }
           }
         } else {
@@ -296,6 +320,25 @@ export function createRotate(deps) {
       };
 
       for (let attempt = 0; attempt < attemptList.length; attempt++) {
+        const candidateRef = attemptList[attempt];
+        // #496: Traffic smoothing micro-queue
+        const smoother = pool.trafficSmoother ?? runtime0.trafficSmoother ?? trafficSmoother;
+        if (smoother && candidateRef) {
+          const smoothRes = await smoother.acquire(candidateRef, {
+            rpmLimit: pool.rpmLimit,
+            burstLimit: pool.trafficSmoothingBurst,
+            maxQueueWaitMs: pool.maxQueueWaitMs,
+            signal: options.signal,
+          });
+          if (smoothRes.overflow) {
+            logWarn(`[dsh-key-rotation] ${options.provider}: key ${candidateRef} micro-queue burst overflow (${smoothRes.delayMs}ms) — rotating to next candidate`);
+            continue;
+          }
+          if (smoothRes.delayed) {
+            pool.state.smoothedRequests = (pool.state.smoothedRequests ?? 0) + 1;
+            pushEvent(pool, candidateRef, 'TRAFFIC_SMOOTHED', smoothRes.delayMs);
+          }
+        }
         // #464: Check deadline & attempt budget before dispatch
         if (!budget.canAttempt()) {
           const isTimeout = budget.isExpired();
@@ -484,6 +527,15 @@ export function createRotate(deps) {
                   // Proactive rate-limit (#115, #303): if response headers say this key is near
                   // its quota or has retry-after, cool it down so the NEXT request starts on a different key.
                   // We do NOT re-run this (already successful) request — that would double-send.
+                  // #503: Extract provider limits and reset headers
+                  const rawHdrs = chunk?.metadata?.headers ?? chunk?.headers;
+                  if (rawHdrs && activeRef) {
+                    const detected = extractProviderLimits(rawHdrs);
+                    if (detected) {
+                      if (!pool.state.detectedLimits) pool.state.detectedLimits = new Map();
+                      pool.state.detectedLimits.set(activeRef, { ...detected, at: now() });
+                    }
+                  }
                   const guardEnabled = pool.proactiveRateLimitGuard ?? runtime0.proactiveRateLimitGuard ?? true;
                   const rate = extractRateLimit(chunk?.metadata?.headers ?? chunk?.headers);
                   if (guardEnabled && rate && activeRef) {

package/lib/sandbox.js

@@ -107,11 +107,15 @@ export class SandboxRunner {
       const status = res.status;
       if (status >= 200 && status < 300) {
         let modelsCount = 0;
+        let models = [];
         try {
           const body = await res.json();
-          modelsCount = Array.isArray(body && body.data) ? body.data.length : 0;
+          if (Array.isArray(body && body.data)) {
+            modelsCount = body.data.length;
+            models = body.data.map((m) => (typeof m === 'string' ? m : (m && m.id))).filter(Boolean);
+          }
         } catch (_) { /* not json */ }
-        return { ok: true, code: 'ok', latencyMs: Date.now() - started, modelsCount };
+        return { ok: true, code: 'ok', latencyMs: Date.now() - started, modelsCount, models };
       }
       return { ok: false, code: classifyStatus(status), latencyMs: Date.now() - started };
     } finally {

package/lib/traffic-smoother.js

@@ -0,0 +1,96 @@
+// lib/traffic-smoother.js — leaky bucket micro-queue traffic smoother (#496).
+// Absorbs momentary request bursts without tripping upstream per-second/per-minute rate limits.
+
+export class TrafficSmoother {
+  constructor({ maxQueueWaitMs = 800, now = Date.now, sleep = null } = {}) {
+    this.maxQueueWaitMs = maxQueueWaitMs;
+    this.now = now;
+    this.sleep = sleep || ((ms, signal) => new Promise((resolve, reject) => {
+      if (signal?.aborted) return reject(signal.reason ?? new Error('aborted'));
+      const timer = setTimeout(resolve, ms);
+      if (signal) {
+        signal.addEventListener('abort', () => {
+          clearTimeout(timer);
+          reject(signal.reason ?? new Error('aborted'));
+        }, { once: true });
+      }
+    }));
+    // Map<ref, { lastTime: number, tokens: number, lastUpdate: number }>
+    this._buckets = new Map();
+  }
+
+  /**
+   * Acquire a slot for `ref` given effective RPM or burst limits.
+   * @param {string} ref
+   * @param {object} opts { rpmLimit, burstLimit, maxQueueWaitMs, signal }
+   * @returns {Promise<{ allowed: boolean, delayed: boolean, delayMs: number, overflow: boolean }>}
+   */
+  async acquire(ref, { rpmLimit, burstLimit, maxQueueWaitMs, signal } = {}) {
+    if (!ref) {
+      return { allowed: true, delayed: false, delayMs: 0, overflow: false };
+    }
+    const maxWait = typeof maxQueueWaitMs === 'number' && maxQueueWaitMs >= 0 ? maxQueueWaitMs : this.maxQueueWaitMs;
+    const effectiveRpm = Number(rpmLimit) > 0 ? Number(rpmLimit) : 0;
+    if (effectiveRpm <= 0) {
+      return { allowed: true, delayed: false, delayMs: 0, overflow: false };
+    }
+
+    const capacity = Number(burstLimit) > 0
+      ? Math.floor(burstLimit)
+      : Math.max(2, Math.ceil(effectiveRpm / 12));
+
+    const ratePerSec = effectiveRpm / 60; // tokens per second
+    const intervalMs = Math.max(1, 1000 / ratePerSec); // ms between tokens
+    const curNow = this.now();
+
+    let bucket = this._buckets.get(ref);
+    if (!bucket) {
+      bucket = { tokens: capacity, lastUpdate: curNow, nextSlot: curNow };
+      this._buckets.set(ref, bucket);
+    }
+
+    // Replenish tokens based on elapsed time
+    const elapsed = Math.max(0, curNow - bucket.lastUpdate);
+    const addedTokens = elapsed * (ratePerSec / 1000);
+    bucket.tokens = Math.min(capacity, bucket.tokens + addedTokens);
+    bucket.lastUpdate = curNow;
+
+    if (bucket.tokens >= 1) {
+      bucket.tokens -= 1;
+      bucket.nextSlot = Math.max(curNow, bucket.nextSlot);
+      return { allowed: true, delayed: false, delayMs: 0, overflow: false };
+    }
+
+    // Burst is exhausted: calculate delay required for next available slot
+    const targetSlot = Math.max(curNow, bucket.nextSlot) + intervalMs;
+    const delayMs = Math.max(0, targetSlot - curNow);
+
+    if (delayMs > maxWait) {
+      // Exceeds max micro-queue wait: signal overflow so caller rotates to next candidate
+      return { allowed: false, delayed: false, delayMs, overflow: true };
+    }
+
+    bucket.nextSlot = targetSlot;
+
+    // Wait for the scheduled slot
+    await this.sleep(delayMs, signal);
+
+    return { allowed: true, delayed: true, delayMs, overflow: false };
+  }
+
+  getQueueDepth(ref) {
+    if (!ref) return this._buckets.size;
+    const b = this._buckets.get(ref);
+    if (!b) return 0;
+    const curNow = this.now();
+    const wait = Math.max(0, b.nextSlot - curNow);
+    return wait > 0 ? Math.ceil(wait / 100) : 0;
+  }
+
+  clear(ref) {
+    if (ref) this._buckets.delete(ref);
+    else this._buckets.clear();
+  }
+}
+
+export default TrafficSmoother;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.63",
+  "version": "0.8.65",
   "packageManager": "pnpm@10.33.2",
   "description": "Per-provider API key rotation for DeepSeek Harness: a key pool per provider, auto-created clone routes, and switching to the next key on quota/rate-limit errors. Includes a Settings section (Key Rotation) to edit the key pools, cooldown and switch codes.",
   "keywords": [