@goodandready/dsh-key-rotation 0.8.62 → 0.8.64

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 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
+- **Configurable Switch to Disable Chat Header Status Chip (#493 / GitHub #25)**:
+  - Added `showChatHeaderChip` boolean setting (defaults to `true` for 100% backward compatibility) in `SettingsSchema` and runtime configuration.
+  - Added user-facing toggle in the Settings card ("Chat Header Status Chip" / "聊天头部状态按钮") under rotation settings.
+  - `KeyRotationHeaderChip` (`conversation.session.header.utilities`) dynamically subscribes to settings and checks server health state, cleanly returning `null` when disabled without taking up conversational header toolbar space.
+  - Additive field `showChatHeaderChip` exposed in `/dsh-key-rotation/status` and `/dsh-key-rotation/health`.
+
 ## 0.8.62 - 2026-10-16
 
 ### Added

package/README.md

@@ -378,6 +378,7 @@ dsh-key-rotation:
 | `circuitBreakerOpenMs` | `number` | `30000` | How long the circuit stays open (ms). |
 | `circuitBreakerHalfOpenProbes` | `number` | `1` | Probe requests allowed in half-open state. |
 | `verboseLogging` | `boolean` | `false` | Per-request rotation logs (noisy; off by default). |
+| `showChatHeaderChip` | `boolean` | `true` | Show or hide the pool status button in conversation header toolbar (#25). |
 | `concurrencyLimit` | `number` | `0` (disabled) | Max concurrent in-flight streams per key (0 = unlimited). |
 | `quotaResetWindow` | `object` | `null` | Calendar reset alignment for both provider-reported quota cooldowns and local per-model token budgets (`midnight_utc`, `midnight_pst`, `rolling_24h`). |
 | `cascade` | `array` | `[]` | Fallback provider chain when primary pool is completely exhausted. |

package/README.ru.md

@@ -409,6 +409,7 @@ MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
 | `circuitBreakerOpenMs` | number | `30000` | Длительность open, мс |
 | `circuitBreakerHalfOpenProbes` | number | `1` | Проб в half-open |
 | `verboseLogging` | boolean | `false` | Подробные логи rotation (шумно) |
+| `showChatHeaderChip` | boolean | `true` | Показывать кнопку статуса пула в шапке чата (#25) |
 
 Status API (v0.8.0): у каждого провайдера `circuit`, в корне ответа `meta.expectedClones` и `meta.notifyQueue`.
 

package/README.zh.md

@@ -378,3 +378,4 @@ MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
 | `circuitBreakerThreshold` | number | `5` | 连续失败阈值 |
 | `circuitBreakerOpenMs` | number | `30000` | 打开时长 ms |
 | `circuitBreakerHalfOpenProbes` | number | `1` | 半开探测次数 |
+| `showChatHeaderChip` | boolean | `true` | 在会话界面顶部工具栏显示密钥池状态按钮 (#25) |

package/lib/client.js

@@ -98,6 +98,7 @@ window.__ModuleLoader__.load({
       bulkImportSuccess: 'Imported {n} keys',
       keyPaused: 'Paused',
       keyRevoked: 'Revoked (401)',
+      keyAuthPaused: 'Auth Paused (401/403)',
       pauseKey: 'Pause key from rotation',
       resumeKey: 'Resume key rotation',
       sparklineTraffic: 'Traffic Trend',
@@ -224,6 +225,8 @@ window.__ModuleLoader__.load({
       routingStrategySticky: 'Sticky (preserves prompt cache)',
       proactiveGuardLabel: 'Proactive Rate-Limit Guard',
       proactiveGuardHint: 'Pre-emptively pause keys when remaining quota or Retry-After header indicates limit before hitting 429',
+      showChatHeaderChipLabel: 'Chat Header Status Chip',
+      showChatHeaderChipDesc: 'Show pool status chip in conversation header',
       selfHealingLabel: 'Auto-Unbreak Interval (min)',
       selfHealingHint: 'Periodic free model check to revive broken keys (0 to disable)',
       updateCheck: 'Check for updates',
@@ -297,6 +300,7 @@ window.__ModuleLoader__.load({
       bulkImportSuccess: '已导入 {n} 个密钥',
       keyPaused: '已暂停',
       keyRevoked: '已撤销 (401)',
+      keyAuthPaused: '身份验证失败已暂停 (401/403)',
       pauseKey: '暂停此密钥轮换',
       resumeKey: '恢复此密钥轮换',
       sparklineTraffic: '流量趋势',
@@ -422,6 +426,8 @@ window.__ModuleLoader__.load({
       routingStrategySticky: '粘性模式 (优先保持提示词缓存)',
       proactiveGuardLabel: '前瞻性限流防护',
       proactiveGuardHint: '当响应中的剩余配额或 Retry-After 头提示即将超限时，预先冷却密钥以防触发 429',
+      showChatHeaderChipLabel: '聊天头部状态按钮',
+      showChatHeaderChipDesc: '在会话界面顶部工具栏显示密钥池状态按钮',
       selfHealingLabel: '自愈检查间隔 (分钟)',
       selfHealingHint: '定期轻量探测以自动恢复损坏密钥 (0 为禁用)',
       updateCheck: '检查更新',
@@ -1948,6 +1954,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 };
@@ -2120,6 +2127,14 @@ 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.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') }),
@@ -2596,6 +2611,16 @@ window.__ModuleLoader__.load({
             }),
             h('span', { key: 'label', style: { fontSize: '13px', color: 'var(--dsw-alias-label-secondary)' } }, t('proactiveGuardLabel')),
           ]))
+        ),
+        h('div', { className: 'krot-grid-2', style: { marginTop: '10px' } },
+          field(t('showChatHeaderChipLabel'), h('label', { style: { display: 'flex', alignItems: 'center', gap: '8px', height: '36px', cursor: 'pointer' } }, [
+            h('input', {
+              key: 'input', type: 'checkbox',
+              checked: val.showChatHeaderChip ?? true,
+              onChange: (e) => setField((cur) => ({ ...cur, showChatHeaderChip: e.target.checked })),
+            }),
+            h('span', { key: 'label', style: { fontSize: '13px', color: 'var(--dsw-alias-label-secondary)' } }, t('showChatHeaderChipDesc')),
+          ]))
         )
       );
 
@@ -2886,6 +2911,7 @@ window.__ModuleLoader__.load({
       const t = resolveT(props);
       const [snap, setSnap] = React.useState(null);
       const [open, setOpen] = React.useState(false);
+      const [, setTick] = React.useState(0);
       const ref = React.useRef(null);
 
       React.useEffect(() => {
@@ -2895,7 +2921,7 @@ window.__ModuleLoader__.load({
           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 (alive) setSnap(d); })
-            .catch(() => {});
+            .catch((e) => { void e; });
         };
         load();
         const id = setInterval(load, 5000);
@@ -2908,6 +2934,13 @@ window.__ModuleLoader__.load({
         };
       }, []);
 
+      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) => {
@@ -2917,6 +2950,16 @@ window.__ModuleLoader__.load({
         return () => document.removeEventListener('click', onDocClick);
       }, [open]);
 
+      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);
@@ -2952,7 +2995,6 @@ window.__ModuleLoader__.load({
         ) : null
       );
     }
-
     function apply(ctx) {
       const settingsSource = createSettingsSource(ctx);
       ctx.effect(() => ctx.locale.register(NS, { en, zh }), 'dsh-key-rotation: dictionaries');
@@ -2963,7 +3005,7 @@ window.__ModuleLoader__.load({
         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 },
+              { 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 */ }

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

@@ -119,6 +119,7 @@ const SettingsSchema = Schema.object({
   earlyWarningKeyThreshold: Schema.number().default(0.25),
   warnBelowHealthy: Schema.number().default(0),
   latencySloMs: Schema.number().default(0),
+  showChatHeaderChip: Schema.boolean().default(true),
   providers: Schema.array(Schema.object({
     provider: Schema.string().required(),
     keys: Schema.array(Schema.string()).default([]),
@@ -350,6 +351,7 @@ export function apply(ctx, config = {}) {
       proactiveRateLimitGuard: cfg.proactiveRateLimitGuard ?? true,
       selfHealingIntervalMinutes: cfg.selfHealingIntervalMinutes ?? 30,
       routingStrategy: cfg.routingStrategy ?? 'round-robin',
+      showChatHeaderChip: cfg.showChatHeaderChip !== false,
       switchNotifyThrottleMs: cfg.switchNotifyThrottleMs ?? 60000,
       warnBelowHealthy: cfg.warnBelowHealthy ?? 0, latencySloMs: cfg.latencySloMs ?? 0,
       index, pools,
@@ -375,6 +377,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) {

package/lib/ops-status.js

@@ -120,7 +120,9 @@ 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,
           modelQuota,
           modelPools: activeModelPools.map(mp => mp.base),
         });
@@ -178,6 +180,7 @@ ctx.effect(() => ctx.webServer.register({
     }
     json(res, 200, sanitizeSnapshot({
       providers,
+      showChatHeaderChip: runtime.showChatHeaderChip !== false,
       // #266/#263 operational extras (additive)
       meta: {
         expectedClones: [...(runtime.expectedClones ?? [])],
@@ -248,7 +251,7 @@ ctx.effect(() => ctx.webServer.register({
       }
     }
     const isDegraded = exhaustedAny || circuitOpenAny;
-    json(res, 200, { status: isDegraded ? 'degraded' : 'ok', pools, exhaustedAny, latency: latencyHistogram.snapshotAll(), quota: typeof quotaStore?.snapshot === 'function' ? quotaStore.snapshot() : null });
+    json(res, 200, { status: isDegraded ? 'degraded' : 'ok', showChatHeaderChip: runtimeH.showChatHeaderChip !== false, pools, exhaustedAny, latency: latencyHistogram.snapshotAll(), quota: typeof quotaStore?.snapshot === 'function' ? quotaStore.snapshot() : null });
   },
 }), 'dsh-key-rotation: health');
 

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-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',
 ];
 
+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/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

@@ -108,12 +108,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 +203,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 +252,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 +292,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 {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.62",
+  "version": "0.8.64",
   "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": [