@goodandready/dsh-key-rotation 0.8.60 → 0.8.62

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.8.62 - 2026-10-16
+
+### Added
+- **Session-Aware Sticky Routing Affinity for Prompt Caching (#489)**:
+  - Enhanced `sticky` routing strategy with LRU session affinity (`pool.state.sessionSticky`, capped at 500 active sessions).
+  - Parallel DSH chat sessions or multi-agent subtasks retain dedicated sticky keys based on `sessionId` (`options.sessionId` / `options.session` / `options.metadata.sessionId`), preventing cross-session cache evictions and maximizing prompt prefix cache hit rates for Anthropic, DeepSeek, and OpenAI.
+  - Graceful failover to the next healthy candidate if a session's pinned key is in cooldown or quota-exhausted; automatic eviction from session map on error.
+- **1-Click Test Matrix Dashboard (#490)**:
+  - Added `/dsh-key-rotation/test-matrix` endpoint in `lib/ops-test.js` supporting batch validation of all configured keys across all pools with bounded concurrency (5 workers) and latency tracking.
+  - Added "⚡ Test All Keys" action button in the WebUI Settings Card with an interactive results modal displaying operational key status, latency in milliseconds, and error details.
+- **Zero-Config Pool Auto-Discovery & 1-Click Import (#491)**:
+  - Added `/dsh-key-rotation/discover` and `/dsh-key-rotation/auto-import` endpoints in `lib/ops-keys.js`.
+  - Automatically scans `~/.dsh/.credentials.yaml` and environment variables for unconfigured provider keys matching standard patterns (`DEEPSEEK_API_KEY`, `OPENCODE_GO_API_KEY_*`, `OPENAI_API_KEY`, `GROQ_API_KEY`, etc.), excluding keys already assigned to rotation pools.
+  - Added smart auto-discovery banner to the Settings Card with 1-click import into provider pools.
+
+## 0.8.61 - 2026-10-15
+
+### Fixed
+- **Prevent Transient Rate Limit Deadlocks from Calendar Quota Locks (#486 / GitHub #24)**:
+  - Upstream errors returning transient 429, RPM/TPM exhaustion, or concurrency limits (such as SenseNova `{"message":"rpm exhausted","type":"quota_exceeded_error"}` or `{"message":"inference exceeds tpm/rpm limit","code":"insufficient_quota"}`) are now classified as `isRateThrottling` and excluded from `isQuota`.
+  - Transient rate limits receive standard short backoff (`cooldownMs` with jitter) rather than being locked out until next UTC midnight.
+  - Cleared `pool.state.quotaWindows` in `recordSuccess` upon first successful request.
+  - Extended background `autoUnbreakBrokenKeys` and proactive health probing to probe keys with calendar quota locks, restoring healthy keys immediately upon receiving 200 OK from upstream.
+  - Added `INSUFFICIENT_QUOTA` and present-tense regex matches to switchable error classification.
+
+### Added
+- **Sticky Key Routing Strategy to Preserve Prompt Caching (#487 / GitHub #23)**:
+  - Added `'sticky'` routing strategy option in settings and provider configurations.
+  - In `'sticky'` mode, the resolver retains the same active key across consecutive requests as long as it remains healthy, maximizing prefix prompt cache hit rate on providers that cache per API key (Anthropic, DeepSeek, OpenAI).
+  - Automatically fails over to the next healthy key in the pool if the sticky key experiences an error or cooldown, then sticks to the new key.
+  - Added UI dropdown selection in the Key Rotation Settings Card with English and Chinese localizations.
+
 ## 0.8.60 - 2026-10-14
 
 ### Changed

package/lib/client.js

@@ -221,6 +221,7 @@ window.__ModuleLoader__.load({
       routingStrategyRoundRobin: 'Round-Robin (default)',
       routingStrategyLeastLoaded: 'Least-Loaded (concurrency)',
       routingStrategyLowestLatency: 'Lowest-Latency (p95)',
+      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',
       selfHealingLabel: 'Auto-Unbreak Interval (min)',
@@ -234,6 +235,19 @@ window.__ModuleLoader__.load({
       updateFailed: 'Update failed',
       currentVersion: 'Current version',
       latestVersion: 'Latest version',
+      testAllKeys: 'Test All Keys',
+      testingMatrix: 'Testing Keys…',
+      matrixModalTitle: '⚡ Key Test Matrix',
+      matrixModalDesc: 'Parallel probe of all configured credentials across all provider pools.',
+      matrixSummary: '{healthy}/{total} keys operational',
+      matrixLatency: 'Latency',
+      matrixStatus: 'Status',
+      matrixClose: 'Close',
+      discoverBannerTitle: '⚡ Unassigned API Keys Discovered',
+      discoverBannerDesc: 'Found {n} credentials in your environment (~/.dsh/.credentials.yaml / env) not yet assigned to any rotation pool.',
+      autoImportBtn: '1-Click Auto-Import',
+      autoImportSuccess: 'Imported {n} keys into rotation pools',
+      autoImporting: 'Importing…',
     };
 
     const zh = {
@@ -405,6 +419,7 @@ window.__ModuleLoader__.load({
       routingStrategyRoundRobin: '轮询 (默认)',
       routingStrategyLeastLoaded: '最低负载 (并发)',
       routingStrategyLowestLatency: '最低延迟 (p95)',
+      routingStrategySticky: '粘性模式 (优先保持提示词缓存)',
       proactiveGuardLabel: '前瞻性限流防护',
       proactiveGuardHint: '当响应中的剩余配额或 Retry-After 头提示即将超限时，预先冷却密钥以防触发 429',
       selfHealingLabel: '自愈检查间隔 (分钟)',
@@ -418,6 +433,19 @@ window.__ModuleLoader__.load({
       updateFailed: '更新失败',
       currentVersion: '当前版本',
       latestVersion: '最新版本',
+      testAllKeys: '批量测试所有密钥',
+      testingMatrix: '正在测试密钥…',
+      matrixModalTitle: '⚡ 密钥测试矩阵',
+      matrixModalDesc: '并行探测所有提供商密钥池中配置的凭据。',
+      matrixSummary: '{healthy}/{total} 个密钥正常可用',
+      matrixLatency: '延迟',
+      matrixStatus: '状态',
+      matrixClose: '关闭',
+      discoverBannerTitle: '⚡ 发现未分配的 API 密钥',
+      discoverBannerDesc: '在当前环境 (~/.dsh/.credentials.yaml / env) 中发现 {n} 个未分配给轮换池的密钥。',
+      autoImportBtn: '一键自动导入',
+      autoImportSuccess: '成功导入 {n} 个密钥到轮换池',
+      autoImporting: '正在导入…',
     };
 
     // Codes worth switching on. Host list is DEFAULT_SWITCH_CODES; config may
@@ -1125,6 +1153,73 @@ window.__ModuleLoader__.load({
       const [simResult, setSimResult] = React.useState(null);
       const [simError, setSimError] = React.useState('');
 
+      // Auto-Discovery State (#491)
+      const [discoveredKeys, setDiscoveredKeys] = React.useState([]);
+      const [autoImporting, setAutoImporting] = React.useState(false);
+      const [autoImportMsg, setAutoImportMsg] = React.useState('');
+
+      // Test Matrix State (#490)
+      const [testMatrixRunning, setTestMatrixRunning] = React.useState(false);
+      const [testMatrixResults, setTestMatrixResults] = React.useState(null);
+      const [testMatrixModal, setTestMatrixModal] = React.useState(false);
+
+      React.useEffect(() => {
+        let mounted = true;
+        fetch('/dsh-key-rotation/discover', {
+          signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(5000) : undefined,
+        })
+          .then((r) => r.json())
+          .then((data) => {
+            if (mounted && data?.ok && Array.isArray(data.discovered)) {
+              setDiscoveredKeys(data.discovered);
+            }
+          })
+          .catch((e) => { void e; });
+        return () => { mounted = false; };
+      }, []);
+
+      const runTestMatrix = async () => {
+        setTestMatrixRunning(true);
+        setTestMatrixModal(true);
+        try {
+          const res = await fetch('/dsh-key-rotation/test-matrix', {
+            method: 'POST',
+            signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(15000) : undefined,
+          });
+          const data = await res.json();
+          if (data?.ok) {
+            setTestMatrixResults(data);
+          }
+        } catch (err) {
+          setTestMatrixResults({ ok: false, failed: 1, total: 1, results: [{ provider: 'all', ref: 'matrix', ok: false, code: 'error', error: String(err?.message ?? err) }] });
+        } finally {
+          setTestMatrixRunning(false);
+        }
+      };
+
+      const runAutoImport = async () => {
+        setAutoImporting(true);
+        setAutoImportMsg('');
+        try {
+          const res = await fetch('/dsh-key-rotation/auto-import', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({}),
+            signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(8000) : undefined,
+          });
+          const data = await res.json();
+          if (data?.ok) {
+            setAutoImportMsg(t('autoImportSuccess').replace('{n}', String(data.importedCount || 0)));
+            setDiscoveredKeys([]);
+            void load();
+          }
+        } catch (err) {
+          setAutoImportMsg(String(err?.message ?? err));
+        } finally {
+          setAutoImporting(false);
+        }
+      };
+
       const runSimulator = async () => {
         const activeProv = simProvider || (providersList[0]?.provider || '');
         if (!activeProv) return;
@@ -2446,6 +2541,7 @@ window.__ModuleLoader__.load({
         h('div', { className: 'krot-keys' }, providerRows),
         h('div', { className: 'krot-foot', style: { marginTop: '10px' } },
           btn(t('addProvider'), addProvider, { primary: false }),
+          btn('⚡ ' + (testMatrixRunning ? t('testingMatrix') : t('testAllKeys')), runTestMatrix, { disabled: testMatrixRunning || totalKeysCount === 0 }),
           noProviders
         ),
         h(UpdaterSection, { t })
@@ -2489,6 +2585,7 @@ window.__ModuleLoader__.load({
             h('option', { key: 'round-robin', value: 'round-robin' }, t('routingStrategyRoundRobin')),
             h('option', { key: 'least-loaded', value: 'least-loaded' }, t('routingStrategyLeastLoaded')),
             h('option', { key: 'lowest-latency', value: 'lowest-latency' }, t('routingStrategyLowestLatency')),
+            h('option', { key: 'sticky', value: 'sticky' }, t('routingStrategySticky')),
           ])),
           field(t('selfHealingLabel'), textInput(String(val.selfHealingIntervalMinutes ?? 30), (v) => setField((cur) => ({ ...cur, selfHealingIntervalMinutes: Number(v) || 0 })))),
           field(t('proactiveGuardLabel'), h('label', { style: { display: 'flex', alignItems: 'center', gap: '8px', height: '36px', cursor: 'pointer' } }, [
@@ -2658,10 +2755,105 @@ window.__ModuleLoader__.load({
         h('div', { className: 'krot-page-sub' }, t('header.sub'))
       );
 
+      const discoveryBanner = (discoveredKeys.length > 0 || autoImportMsg) ? h('div', {
+        className: 'krot-section-card',
+        style: {
+          background: 'var(--dsw-alias-bg-hover)',
+          border: '1px solid var(--dsw-alias-border-l2)',
+          marginBottom: '12px',
+          padding: '12px 14px',
+          display: 'flex',
+          flexDirection: 'column',
+          gap: '8px',
+        }
+      },
+        h('div', { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' } },
+          h('div', null,
+            h('span', { style: { fontWeight: 600, fontSize: '13px' } }, t('discoverBannerTitle')),
+            h('div', { className: 'krot-hint', style: { fontSize: '11px', marginTop: '2px' } },
+              autoImportMsg || t('discoverBannerDesc').replace('{n}', String(discoveredKeys.length))
+            ),
+          ),
+          discoveredKeys.length > 0 ? btn(autoImporting ? t('autoImporting') : t('autoImportBtn'), runAutoImport, {
+            primary: true,
+            disabled: autoImporting,
+          }) : null
+        ),
+        discoveredKeys.length > 0 ? h('div', { style: { display: 'flex', gap: '6px', flexWrap: 'wrap', marginTop: '4px' } },
+          discoveredKeys.slice(0, 10).map((d) => h('span', {
+            key: d.ref,
+            className: 'krot-badge',
+            style: { fontSize: '10px', background: 'var(--dsw-alias-bg-layer-3)' }
+          }, `${d.provider}: ${d.ref} ${d.keyTail ? '(' + d.keyTail + ')' : ''}`))
+        ) : null
+      ) : null;
+
+      const testMatrixDialog = testMatrixModal ? h('div', {
+        className: 'krot-modal-backdrop',
+        onClick: () => setTestMatrixModal(false),
+      },
+        h('div', {
+          className: 'krot-modal-card',
+          role: 'dialog',
+          'aria-modal': 'true',
+          onClick: (e) => e.stopPropagation(),
+          style: {
+            maxWidth: '560px',
+            width: '90vw',
+            maxHeight: '80vh',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '12px',
+          }
+        },
+          h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center' } },
+            h('span', { style: { fontWeight: 600, fontSize: '15px' } }, t('matrixModalTitle')),
+            btn('✕', () => setTestMatrixModal(false), { className: 'krot-btn-sub' })
+          ),
+          h('div', { className: 'krot-hint', style: { fontSize: '12px' } }, t('matrixModalDesc')),
+          testMatrixRunning ? h('div', { style: { textAlign: 'center', padding: '20px' } }, t('testingMatrix')) : null,
+          testMatrixResults ? h('div', { style: { display: 'flex', flexDirection: 'column', gap: '10px', overflowY: 'auto', maxHeight: '50vh' } },
+            h('div', { style: { fontWeight: 600, fontSize: '13px' } },
+              t('matrixSummary').replace('{healthy}', String(testMatrixResults.healthy)).replace('{total}', String(testMatrixResults.total))
+            ),
+            h('div', { style: { display: 'flex', flexDirection: 'column', gap: '6px' } },
+              (testMatrixResults.results || []).map((r, i) => h('div', {
+                key: i,
+                style: {
+                  display: 'flex',
+                  justifyContent: 'space-between',
+                  alignItems: 'center',
+                  padding: '6px 10px',
+                  borderRadius: '6px',
+                  background: 'var(--dsw-alias-bg-hover)',
+                  fontSize: '12px',
+                }
+              },
+                h('div', { style: { display: 'flex', gap: '8px', alignItems: 'center' } },
+                  h('span', { style: { fontWeight: 500 } }, r.provider),
+                  h('span', { style: { fontFamily: 'monospace' } }, r.ref),
+                  r.keyTail ? h('span', { style: { color: 'var(--dsw-alias-text-sub)', fontSize: '11px' } }, `(${r.keyTail})`) : null
+                ),
+                h('div', { style: { display: 'flex', gap: '8px', alignItems: 'center' } },
+                  h('span', { style: { color: 'var(--dsw-alias-text-sub)' } }, `${r.latencyMs || 0}ms`),
+                  h('span', {
+                    className: 'krot-badge ' + (r.ok ? 'krot-badge-ok' : 'krot-badge-bad')
+                  }, r.ok ? 'OK' : (r.code || 'FAIL'))
+                )
+              ))
+            )
+          ) : null,
+          h('div', { style: { display: 'flex', justifyContent: 'flex-end', marginTop: '8px' } },
+            btn(t('matrixClose'), () => setTestMatrixModal(false), { primary: true })
+          )
+        )
+      ) : null;
       return h('div', { className: 'krot', 'aria-busy': saving || importing },
         confirmModalEl,
+        testMatrixDialog,
         headerSection,
         statsSection,
+        discoveryBanner,
         h('fieldset', { disabled: saving || importing || !state.writable,
           style: { border: 0, padding: 0, margin: 0, minWidth: 0, display: 'flex', flexDirection: 'column', gap: '14px' } },
           poolsSection,

package/lib/heal.js

@@ -52,21 +52,31 @@ export async function autoUnbreakBrokenKeys(pools, probeFn, now = Date.now(), {
   for (const pool of pools) {
     if (!pool || !pool.state || !pool.base) continue;
     const bu = pool.state.brokenUntil;
-    if (!bu || bu.size === 0) continue;
-    const brokenRefs = [];
-    for (const [ref, until] of bu.entries()) {
-      if (isKeyRevoked(pool, ref) || isKeyPaused(pool, ref)) continue;
-      if (Number.isFinite(until) && until > now) {
-        brokenRefs.push(ref);
+    const qw = pool.state.quotaWindows;
+    const candidates = new Set();
+    if (bu && bu.size > 0) {
+      for (const [ref, until] of bu.entries()) {
+        if (!isKeyRevoked(pool, ref) && !isKeyPaused(pool, ref) && Number.isFinite(until) && until > now) {
+          candidates.add(ref);
+        }
       }
     }
-    for (const ref of brokenRefs) {
+    if (qw && qw.size > 0) {
+      for (const [ref, until] of qw.entries()) {
+        if (!isKeyRevoked(pool, ref) && !isKeyPaused(pool, ref) && Number.isFinite(until) && until > now) {
+          candidates.add(ref);
+        }
+      }
+    }
+    if (candidates.size === 0) continue;
+
+    for (const ref of candidates) {
       if (!isActive()) return results;
       const state = pool.state;
-      const fields = ['brokenUntil', 'failedUntil', 'failCounts', 'authFailCounts'];
+      const fields = ['brokenUntil', 'failedUntil', 'quotaWindows', 'failCounts', 'authFailCounts'];
       const observed = fields.map(field => [field, state[field], state[field]?.get(ref)]);
       // An earlier await may have removed this key from the captured worklist.
-      if (state.brokenUntil !== bu || !bu.has(ref)) continue;
+      if (!((bu && bu.has(ref)) || (qw && qw.has(ref)))) continue;
       try {
         const res = await probeFn(ref);
         if (!isActive()) return results;
@@ -74,7 +84,9 @@ export async function autoUnbreakBrokenKeys(pools, probeFn, now = Date.now(), {
         if (pool.state !== state || observed.some(([field, map, value]) =>
           state[field] !== map || map?.get(ref) !== value)) continue;
         if (res && res.ok) {
-          bu.delete(ref);
+          bu?.delete(ref);
+          qw?.delete(ref);
+          pool.state.quotaWindows?.delete(ref);
           pool.state.failedUntil?.delete(ref);
           pool.state.failCounts?.delete(ref);
           pool.state.authFailCounts?.delete(ref);

package/lib/index.js

@@ -95,7 +95,7 @@ const SettingsSchema = Schema.object({
   rateLimitThreshold: Schema.number().default(0.1),
   proactiveRateLimitGuard: Schema.boolean().default(true),
   selfHealingIntervalMinutes: Schema.number().default(30),
-  routingStrategy: Schema.union(['round-robin', 'least-loaded', 'lowest-latency']).default('round-robin'),
+  routingStrategy: Schema.union(['round-robin', 'least-loaded', 'lowest-latency', 'sticky']).default('round-robin'),
   rpmLimit: Schema.number().default(0),
   tpmLimit: Schema.number().default(0),
   webhookActionToken: Schema.string().role('secret').default(''),
@@ -144,7 +144,7 @@ const SettingsSchema = Schema.object({
     })).default({}),
     cooldownMs: Schema.number(),
     maxCooldownMs: Schema.number(),
-    routingStrategy: Schema.union(['round-robin', 'least-loaded', 'lowest-latency']),
+    routingStrategy: Schema.union(['round-robin', 'least-loaded', 'lowest-latency', 'sticky']),
     proactiveRateLimitGuard: Schema.boolean(),
     rpmLimit: Schema.number(),
     tpmLimit: Schema.number(),
@@ -374,6 +374,7 @@ export function apply(ctx, config = {}) {
       const resolve = createResolver({
         buildRuntime,
         currentPool: () => dispatchStorage.getStore()?.pool,
+        currentSession: () => dispatchStorage.getStore()?.sessionId,
         onPicked: (pool, candidate, meta) => {
           const store = dispatchStorage.getStore();
           if (store && store.pool === pool) {
@@ -384,7 +385,7 @@ export function apply(ctx, config = {}) {
         latencyHistogram,
         concurrencyTracker,
       });
-      credentials.resolve = async (ref) => resolve(ref, original);
+      credentials.resolve = async (ref, opts) => resolve(ref, original, opts);
       credentials.__dshKeyRotationPatched = true;
       return () => {
         if (credentials.__dshKeyRotationPatched) {

package/lib/lifecycle.js

@@ -171,8 +171,10 @@ export function setupProactiveHealthProbeEffect(ctx, getConfig, buildRuntime, en
       running = true;
       try {
         const c = getConfig();
-        if (!c || c.proactiveHealthProbing !== true) return;
+        if (!c) return;
         const { pools } = buildRuntime();
+        const hasCalendarLocks = (pools || []).some(p => p?.state?.quotaWindows?.size > 0);
+        if (c.proactiveHealthProbing !== true && !hasCalendarLocks) return;
         const runner = ensureSandboxRunner(ctx);
         const now = Date.now();
         for (const pool of (pools || [])) {
@@ -203,6 +205,7 @@ export function setupProactiveHealthProbeEffect(ctx, getConfig, buildRuntime, en
               if (res && res.ok) {
                 pool.state.failedUntil?.delete(ref);
                 pool.state.brokenUntil?.delete(ref);
+                pool.state.quotaWindows?.delete(ref);
                 pool.state.failCounts?.delete(ref);
                 if (Array.isArray(pool.state.events)) {
                   pool.state.events.push({ at: Date.now(), ref, reason: 'proactive-probe-heal', cooldownMs: 0, type: 'heal' });

package/lib/ops-keys.js

@@ -20,13 +20,138 @@ import {
   RESET_PATH,
   IMPORT_PATH,
   DRAIN_PATH,
+  DISCOVER_PATH,
+  AUTO_IMPORT_PATH,
 } from './ops-paths.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { markKeyDraining, isKeyDraining, cancelKeyDrain, getDrainingStatus, getAllDrainingKeys } from './key-drain.js';
 
 /**
  * @param {object} ctx cordis context
  * @param {object} deps live dependencies from apply()
  */
+const KNOWN_PROVIDER_PATTERNS = [
+  { provider: 'deepseek', pattern: /^DEEPSEEK_API_KEY(?:_\w+)?$/i },
+  { provider: 'opencode', pattern: /^OPENCODE(?:_GO)?_API_KEY(?:_\w+)?$/i },
+  { provider: 'openai', pattern: /^OPENAI_API_KEY(?:_\w+)?$/i },
+  { provider: 'anthropic', pattern: /^ANTHROPIC_API_KEY(?:_\w+)?$/i },
+  { provider: 'openrouter', pattern: /^OPENROUTER_API_KEY(?:_\w+)?$/i },
+  { provider: 'siliconflow', pattern: /^SILICONFLOW_API_KEY(?:_\w+)?$/i },
+  { provider: 'groq', pattern: /^GROQ_API_KEY(?:_\w+)?$/i },
+  { provider: 'mistral', pattern: /^MISTRAL_API_KEY(?:_\w+)?$/i },
+  { provider: 'gemini', pattern: /^(?:GEMINI|GOOGLE)_API_KEY(?:_\w+)?$/i },
+  { provider: 'ollama', pattern: /^OLLAMA_API_KEY(?:_\w+)?$/i },
+  { provider: 'sensenova', pattern: /^SENSENOVA_API_KEY(?:_\w+)?$/i },
+  { provider: 'cohere', pattern: /^COHERE_API_KEY(?:_\w+)?$/i },
+  { provider: 'fal', pattern: /^FAL_API_KEY(?:_\w+)?$/i },
+  { provider: 'together', pattern: /^TOGETHER_API_KEY(?:_\w+)?$/i },
+  { provider: 'xai', pattern: /^XAI_API_KEY(?:_\w+)?$/i },
+];
+
+export function inferProviderFromRef(ref) {
+  if (!ref || typeof ref !== 'string') return null;
+  for (const { provider, pattern } of KNOWN_PROVIDER_PATTERNS) {
+    if (pattern.test(ref)) return provider;
+  }
+  const generic = /^([A-Z0-9]+)_API_KEY(?:_\w+)?$/i.exec(ref);
+  if (generic && generic[1]) {
+    const prov = generic[1].toLowerCase();
+    if (!/TOKEN|SECRET|WEBHOOK|PASSWORD|AUTH|SESSION|OAUTH|GITEA|KANBAN/i.test(prov)) {
+      return prov;
+    }
+  }
+  return null;
+}
+
+export async function discoverUnconfiguredKeys(ctx, runtimePools = []) {
+  const configuredRefs = new Set();
+  for (const p of runtimePools) {
+    for (const r of (p.refs || [])) configuredRefs.add(r);
+    for (const r of (p.keys || [])) configuredRefs.add(typeof r === 'string' ? r : r?.ref);
+  }
+
+  // Also check DSH settings describe if available
+  const settings = ctx.get('settings');
+  if (settings && typeof settings.describe === 'function') {
+    try {
+      const desc = settings.describe({ redactSecrets: true })?.find?.((c) => c.ns === NS);
+      const providers = desc?.value?.providers ?? [];
+      for (const p of providers) {
+        for (const k of (p.keys || [])) {
+          configuredRefs.add(typeof k === 'string' ? k : k?.ref);
+        }
+      }
+    } catch (_) { /* best-effort */ }
+  }
+
+  const candidates = new Map(); // ref -> { provider, source }
+
+  // 1. Process environment
+  for (const k of Object.keys(process.env)) {
+    if (configuredRefs.has(k)) continue;
+    const prov = inferProviderFromRef(k);
+    if (prov && process.env[k]?.trim()) {
+      candidates.set(k, { provider: prov, source: 'env' });
+    }
+  }
+
+  // 2. ~/.dsh/.credentials.yaml
+  try {
+    const credPath = path.join(os.homedir(), '.dsh', '.credentials.yaml');
+    if (fs.existsSync(credPath)) {
+      const content = fs.readFileSync(credPath, 'utf8');
+      let inRefs = false;
+      for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === 'refs:') {
+          inRefs = true;
+          continue;
+        }
+        if (inRefs) {
+          if (line.startsWith('  ') && line.includes(':')) {
+            const refName = trimmed.split(':')[0].trim();
+            if (!configuredRefs.has(refName)) {
+              const prov = inferProviderFromRef(refName);
+              if (prov && !candidates.has(refName)) {
+                candidates.set(refName, { provider: prov, source: 'credentials' });
+              }
+            }
+          } else if (!line.startsWith(' ') && trimmed.length > 0) {
+            inRefs = false;
+          }
+        }
+      }
+    }
+  } catch (_) { /* best-effort */ }
+
+  const credentialsService = ctx.get('credentials');
+  const discovered = [];
+
+  for (const [ref, { provider, source }] of candidates) {
+    let tail = '';
+    try {
+      let hit = await (credentialsService?.__dshKeyRotationOriginalResolve ?? credentialsService?.resolve)?.call(credentialsService, ref);
+      let raw = hit?.value;
+      if (!raw) raw = envValue(ref);
+      if (raw) {
+        const plain = decryptSecret(raw);
+        tail = keyTail(plain);
+      }
+    } catch (_) { /* best-effort tail */ }
+    discovered.push({
+      provider,
+      ref,
+      keyTail: tail,
+      source,
+    });
+  }
+
+  return discovered;
+}
+
+
 export function registerKeyRoutes(ctx, deps) {
 
 ctx.effect(() => ctx.webServer.register({
@@ -300,4 +425,118 @@ ctx.effect(() => ctx.webServer.register({
 }), 'dsh-key-rotation: import route');
 
 // Health for external panels (Beszel/Uptime)
+
+// ── discover unconfigured keys route (#491) ──
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: DISCOVER_PATH,
+  handler: async (req, res) => {
+    if (req.method !== 'GET') {
+      json(res, 405, { error: { code: 'method', message: 'GET only' } });
+      return;
+    }
+    if (!isTrustedBridgeRequest(req)) {
+      json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: discover is local-only' } });
+      return;
+    }
+    try {
+      const runtime = deps.buildRuntime?.() ?? {};
+      const discovered = await discoverUnconfiguredKeys(ctx, runtime.pools || []);
+      json(res, 200, { ok: true, discovered });
+    } catch (e) {
+      json(res, 500, { error: { code: 'discover-failed', message: String(e?.message ?? e) } });
+    }
+  },
+}), 'dsh-key-rotation: discover route');
+
+// ── auto-import discovered keys into pools (#491) ──
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: AUTO_IMPORT_PATH,
+  handler: async (req, res) => {
+    if (req.method !== 'POST') {
+      json(res, 405, { error: { code: 'method', message: 'POST only' } });
+      return;
+    }
+    if (!isTrustedBridgeRequest(req)) {
+      json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: auto-import is local-only' } });
+      return;
+    }
+    let body = {};
+    try { body = await readJson(req); } catch (_) { body = {}; }
+
+    try {
+      const runtime = deps.buildRuntime?.() ?? {};
+      const discovered = await discoverUnconfiguredKeys(ctx, runtime.pools || []);
+      const targetRefs = Array.isArray(body?.refs) && body.refs.length > 0
+        ? new Set(body.refs)
+        : null;
+
+      const toImport = targetRefs
+        ? discovered.filter((d) => targetRefs.has(d.ref))
+        : discovered;
+
+      if (toImport.length === 0) {
+        json(res, 200, { ok: true, importedCount: 0, message: 'No unassigned keys to import' });
+        return;
+      }
+
+      const settings = ctx.get('settings');
+      if (!settings) {
+        json(res, 503, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: no settings provider' } });
+        return;
+      }
+      const desc = settings.describe({ redactSecrets: true })?.find?.((c) => c.ns === NS);
+      if (!desc) throw new Error('Settings namespace is unavailable');
+
+      const curProviders = (desc.value?.providers ?? []).map((p) => ({
+        ...p,
+        keys: Array.isArray(p.keys) ? [...p.keys] : [],
+      }));
+
+      const providerMap = new Map();
+      for (const p of curProviders) {
+        if (p?.provider) providerMap.set(p.provider, p);
+      }
+
+      let importedCount = 0;
+      for (const item of toImport) {
+        const { provider, ref } = item;
+        let poolConfig = providerMap.get(provider);
+        if (!poolConfig) {
+          poolConfig = {
+            provider,
+            strategy: 'round-robin',
+            cooldownMs: 30000,
+            keys: [],
+          };
+          providerMap.set(provider, poolConfig);
+        }
+        const existingKeys = poolConfig.keys.map((k) => (typeof k === 'string' ? k : k?.ref));
+        if (!existingKeys.includes(ref)) {
+          poolConfig.keys.push(ref);
+          importedCount++;
+        }
+      }
+
+      const updatedProviders = [...providerMap.values()];
+      await mutateSettings(
+        settings,
+        NS,
+        [{ op: 'set', path: ['providers'], value: updatedProviders }],
+        body.expectedRevision ?? desc.revision
+      );
+
+      json(res, 200, {
+        ok: true,
+        importedCount,
+        providersCount: updatedProviders.length,
+        providers: updatedProviders,
+      });
+    } catch (e) {
+      json(res, 400, { error: { code: 'auto-import-failed', message: String(e?.message ?? e) } });
+    }
+  },
+}), 'dsh-key-rotation: auto-import route');
+
 }

package/lib/ops-paths.js

@@ -14,3 +14,6 @@ export const DIAG_PATH = '/dsh-key-rotation/diag';
 export const TRACE_PATH = '/dsh-key-rotation/trace';
 export const SIMULATE_PATH = '/dsh-key-rotation/simulate';
 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';

package/lib/ops-test.js

@@ -13,6 +13,7 @@ import { bestEffort } from './best-effort.js';
 import {
   TEST_PATH,
   SANDBOX_CACHE_PATH,
+  TEST_MATRIX_PATH,
 } from './ops-paths.js';
 import { decryptSecret } from './crypto-storage.js';
 
@@ -114,4 +115,114 @@ ctx.effect(() => ctx.webServer.register({
 // #199 webhook-action: interactive webhook buttons call back here.
 // Auth: bearer token from Config (external services like Telegram/Discord
 // cannot be same-origin, so a shared secret is the gate).
+
+// ── test matrix route: batch probe all configured keys (#490) ──
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: TEST_MATRIX_PATH,
+  handler: async (req, res) => {
+    if (req.method !== 'GET' && req.method !== 'POST') {
+      json(res, 405, { error: { code: 'method', message: 'GET or POST only' } });
+      return;
+    }
+    if (!isTrustedBridgeRequest(req)) {
+      json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: test-matrix is local-only' } });
+      return;
+    }
+    const base = ctx.get('credentials');
+    const runner = ensureSandboxRunner(ctx);
+    const runtime = deps.buildRuntime?.() ?? {};
+    const pools = runtime.pools || [];
+
+    const keyItems = [];
+    const seen = new Set();
+    for (const p of pools) {
+      const pName = p.provider ?? p.base ?? 'unknown';
+      for (const ref of (p.refs || [])) {
+        const id = `${pName}:${ref}`;
+        if (!seen.has(id)) {
+          seen.add(id);
+          keyItems.push({ provider: pName, ref });
+        }
+      }
+    }
+
+    const CONCURRENCY = 5;
+    const results = [];
+    let idx = 0;
+
+    async function worker() {
+      while (idx < keyItems.length) {
+        const item = keyItems[idx++];
+        if (!item) break;
+        const { provider, ref } = item;
+        try {
+          let hit = await (base?.__dshKeyRotationOriginalResolve ?? base?.resolve)?.call(base, ref);
+          let rawValue = hit?.value;
+          if (!rawValue) {
+            const ev = envValue(ref);
+            if (ev !== undefined) rawValue = ev;
+          }
+          let effectiveValue = rawValue ? decryptSecret(rawValue) : rawValue;
+          const tail = effectiveValue ? keyTail(effectiveValue) : '';
+          if (!effectiveValue) {
+            results.push({ provider, ref, keyTail: tail, ok: false, code: 'no-credential', latencyMs: 0 });
+            continue;
+          }
+          const probeRes = await runner.probeModels(ref, effectiveValue);
+          const cached = { ...probeRes, at: Date.now() };
+          lastTestCache.set(ref, cached);
+          if (cached.ok) {
+            for (const st of poolState.values()) {
+              st.failedUntil?.delete(ref);
+              st.failCounts?.delete(ref);
+              st.authFailCounts?.delete(ref);
+              st.brokenUntil?.delete(ref);
+              st.revokedRefs?.delete(ref);
+            }
+          }
+          results.push({
+            provider,
+            ref,
+            keyTail: tail,
+            ok: cached.ok,
+            code: cached.code,
+            latencyMs: cached.latencyMs,
+            modelsCount: cached.modelsCount,
+          });
+        } catch (err) {
+          results.push({
+            provider,
+            ref,
+            keyTail: '',
+            ok: false,
+            code: 'error',
+            error: String(err?.message ?? err),
+            latencyMs: 0,
+          });
+        }
+      }
+    }
+
+    const workers = [];
+    for (let i = 0; i < Math.min(CONCURRENCY, keyItems.length); i++) {
+      workers.push(worker());
+    }
+    await Promise.all(workers);
+
+    const total = results.length;
+    const healthy = results.filter((r) => r.ok).length;
+    const failed = total - healthy;
+
+    json(res, 200, {
+      ok: true,
+      at: Date.now(),
+      total,
+      healthy,
+      failed,
+      results,
+    });
+  },
+}), 'dsh-key-rotation: test matrix route');
+
 }

package/lib/pool-state.js

@@ -3,7 +3,7 @@
 const MAP_FIELDS = [
   'failedUntil', 'failCounts', 'authFailCounts', 'brokenUntil', 'costPerKey',
   'lastUsedAt', 'usageCounts', 'byModel', 'usageDays', 'quotaWindows', 'costDays',
-  'tokenUsage', 'rpmWindows', 'tpmWindows',
+  'tokenUsage', 'rpmWindows', 'tpmWindows', 'sessionSticky',
 ];
 
 export function initializePoolState(state = {}) {

package/lib/pool.js

@@ -1,3 +1,29 @@
+export const MAX_SESSION_STICKY_ENTRIES = 500;
+
+export function setSessionSticky(pool, sessionId, candidate) {
+  if (!sessionId || !candidate || !pool?.state) return;
+  if (!(pool.state.sessionSticky instanceof Map)) {
+    pool.state.sessionSticky = new Map();
+  }
+  if (pool.state.sessionSticky.has(sessionId)) {
+    pool.state.sessionSticky.delete(sessionId);
+  } else if (pool.state.sessionSticky.size >= MAX_SESSION_STICKY_ENTRIES) {
+    const oldest = pool.state.sessionSticky.keys().next().value;
+    if (oldest !== undefined) pool.state.sessionSticky.delete(oldest);
+  }
+  pool.state.sessionSticky.set(sessionId, candidate);
+}
+
+export function getSessionSticky(pool, sessionId) {
+  if (!sessionId || !pool?.state?.sessionSticky) return null;
+  return pool.state.sessionSticky.get(sessionId) ?? null;
+}
+
+export function clearSessionSticky(pool, sessionId) {
+  if (!sessionId || !pool?.state?.sessionSticky) return;
+  pool.state.sessionSticky.delete(sessionId);
+}
+
 import { resetModelQuotaIfNeeded } from './model-quota.js';
 import { decryptSecret } from './crypto-storage.js';
 import { bestEffort } from './best-effort.js';
@@ -68,7 +94,8 @@ export const SWITCHABLE_MESSAGE_PATTERN = new RegExp([
   /\b(?:quota|usage[\s_-]+limit|rate[\s_-]?limit)\b/i,
   /\binsufficient[\s_-]+(?:quota|balance|credits?)\b/i,
   /\bout[\s_-]+of[\s_-]+(?:credits?|budget)\b/i,
-  /\b(?:exceeded|exhausted)[\s_-]+(?:quota|limit|budget)\b/i,
+  /\b(?:exceeded|exceeds|exhausted|exhausts)[\s_-]+(?:quota|limit|budget|rpm|tpm|inference)\b/i,
+  /\b(?:rpm|tpm)\b/i,
   /\bbilling\b/i,
   /\bresource[\s_-]+exhausted\b/i,
   /\bcapacity[\s_-]+(?:limit|exceeded|reached)\b/i,
@@ -171,7 +198,8 @@ export function recordFailure(pool, ref, now, baseMs, maxMs, isSoft = false, jit
 /** Record a success for `ref`. */
 export function recordSuccess(pool, ref, now = Date.now()) {
   if (pool.state.failCounts) pool.state.failCounts.delete(ref);
-  pool.state.failedUntil.delete(ref);
+  pool.state.failedUntil?.delete(ref);
+  pool.state.quotaWindows?.delete(ref);
   if (!pool.state.lastSuccessAt) pool.state.lastSuccessAt = new Map();
   pool.state.lastSuccessAt.set(ref, now);
 }
@@ -409,6 +437,20 @@ export function isRateLimited(rate, threshold = 0.1) {
 export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
   if (!Array.isArray(refs) || refs.length <= 1) return (refs ?? []).slice();
   const list = refs.slice();
+  if (strategy === 'sticky') {
+    const last = deps.sessionSticky ||
+      (deps.sessionId && (deps.pool?.state?.sessionSticky?.get?.(deps.sessionId) || deps.sessionStickyMap?.get?.(deps.sessionId))) ||
+      deps.lastUsed ||
+      (deps.pool && deps.pool.state && deps.pool.state.lastUsed);
+    if (last && list.includes(last)) {
+      const idx = list.indexOf(last);
+      if (idx > 0) {
+        list.splice(idx, 1);
+        list.unshift(last);
+      }
+    }
+    return list;
+  }
   if (strategy === 'tier-priority') {
     const tiers = deps.tiers || (deps.pool && deps.pool.tiers) || {};
     return list.sort((a, b) => {
@@ -482,7 +524,7 @@ export function isSwitchableError(failureOrPayload, switchCodes = new Set(DEFAUL
   if ((status >= 500 && status <= 504) && (switchCodes.has('SERVER') || switchCodes.has(String(status)))) return true;
 
   // 2. Standard gRPC / cloud error codes
-  if (code === 'RESOURCE_EXHAUSTED' && (switchCodes.has('QUOTA') || switchCodes.has('RATE_LIMIT'))) return true;
+  if ((code === 'RESOURCE_EXHAUSTED' || code === 'INSUFFICIENT_QUOTA') && (switchCodes.has('QUOTA') || switchCodes.has('RATE_LIMIT'))) return true;
   if ((code === 'UNAVAILABLE' || code === 'INTERNAL') && switchCodes.has('SERVER')) return true;
   if (code === 'DEADLINE_EXCEEDED' && switchCodes.has('TIMEOUT')) return true;
   if ((code === 'UNAUTHENTICATED' || code === 'PERMISSION_DENIED') && switchCodes.has('AUTH')) return true;

package/lib/resolver.js

@@ -9,7 +9,7 @@
 // delegates to `original(ref)`.
 
 import { bucketAllow, bucketRetryMs, tpmAllow, tpmRetryMs } from './bucket.js';
-import { envValue, sortAttemptList, isKeyPaused, isKeyRevoked, isKeyBroken, costForDay, costForWeek, budgetVerdict } from './pool.js';
+import { envValue, sortAttemptList, isKeyPaused, isKeyRevoked, isKeyBroken, costForDay, costForWeek, budgetVerdict, getSessionSticky, setSessionSticky } from './pool.js';
 import { decryptSecret } from './crypto-storage.js';
 import { resolveRefPool, isQuotaManagedRequest, providerOfBase, basePoolForBase } from './pool-index.js';
 import {
@@ -76,12 +76,13 @@ export function getProviderCost(provider, runtime, now = Date.now()) {
 export function createResolver({
   buildRuntime,
   currentPool,
+  currentSession,
   onPicked,
   latencyHistogram,
   concurrencyTracker,
   now = Date.now,
 }) {
-  return async function resolve(ref, original) {
+  return async function resolve(ref, original, resolveOpts) {
     const runtime = buildRuntime();
     // A ref may belong to several model pools at once, so the request-scoped
     // pool that rotate() actually dispatched with decides ownership. A bare
@@ -116,9 +117,18 @@ export function createResolver({
     }
 
     const strategy = pool.routingStrategy ?? runtime.routingStrategy ?? 'round-robin';
+    const sessionId = resolveOpts?.sessionId ?? resolveOpts?.session ?? resolveOpts?.metadata?.sessionId ?? currentSession?.();
     let list = pool.weightedRefs ?? pool.refs;
-    if (strategy === 'lowest-latency' || strategy === 'least-loaded') {
-      list = sortAttemptList(list, strategy, { latencyHistogram, concurrencyTracker, weights: pool.weightsMap, tiers: pool.tiers });
+    if (strategy === 'lowest-latency' || strategy === 'least-loaded' || strategy === 'sticky') {
+      list = sortAttemptList(list, strategy, {
+        latencyHistogram,
+        concurrencyTracker,
+        weights: pool.weightsMap,
+        tiers: pool.tiers,
+        sessionId,
+        sessionSticky: sessionId ? getSessionSticky(pool, sessionId) : null,
+        lastUsed: pool.state.lastUsed,
+      });
     }
     // Fail closed: when this request is managed by a model pool that has local
     // token budgets, an exhausted candidate may not be dispatched and the
@@ -126,6 +136,18 @@ export function createResolver({
     // the loop, so it cannot be re-evaluated mid-iteration.
     const quotaManaged = hasModelQuotaConfig(pool) && isQuotaManagedRequest(runtime.index, ref, requested);
     let start = strategy === 'round-robin' ? (pool.state.pointer ?? 0) : 0;
+    if (strategy === 'sticky') {
+      let preferred = null;
+      if (sessionId) {
+        const stick = getSessionSticky(pool, sessionId);
+        if (stick && list.includes(stick)) preferred = stick;
+      }
+      if (!preferred && pool.state.lastUsed && list.includes(pool.state.lastUsed)) {
+        preferred = pool.state.lastUsed;
+      }
+      const lastIdx = preferred ? list.indexOf(preferred) : -1;
+      start = lastIdx >= 0 ? lastIdx : (pool.state.pointer ?? 0);
+    }
     if (pool.pinnedRef && list.includes(pool.pinnedRef)) {
       const pIdx = list.indexOf(pool.pinnedRef);
       if (pIdx > 0) {
@@ -217,18 +239,22 @@ export function createResolver({
 
       // Advance the shared cursor at selection time: concurrent requests must
       // not all pick the same slot.
-      pool.state.pointer = (index + 1) % list.length;
+      if (strategy === 'sticky') {
+        pool.state.pointer = index;
+      } else {
+        pool.state.pointer = (index + 1) % list.length;
+      }
       try {
         const hit = await original(candidate);
         if (hit && typeof hit.value === 'string' && hit.value.length > 0) {
-          settle(pool, candidate, at, onPicked, acquired ? candidate : undefined);
+          settle(pool, candidate, at, onPicked, acquired ? candidate : undefined, sessionId);
           return { ...hit, value: decryptSecret(hit.value) };
         }
         // No stored credential: fall back to the launching environment, which is
         // how env-bootstrapped pools work (issue #7).
         const envVal = envValue(candidate);
         if (envVal !== undefined) {
-          settle(pool, candidate, at, onPicked, acquired ? candidate : undefined);
+          settle(pool, candidate, at, onPicked, acquired ? candidate : undefined, sessionId);
           return { value: decryptSecret(envVal), source: 'env' };
         }
       } catch (err) {
@@ -260,8 +286,9 @@ export function createResolver({
 }
 
 /** Record a successful credential selection on the pool and request scope. */
-function settle(pool, candidate, now, onPicked, concurrencyRef) {
+function settle(pool, candidate, now, onPicked, concurrencyRef, sessionId) {
   pool.state.lastUsed = candidate;
+  if (sessionId) setSessionSticky(pool, sessionId, candidate);
   if (!pool.state.lastUsedAt) pool.state.lastUsedAt = new Map();
   pool.state.lastUsedAt.set(candidate, now);
   onPicked?.(pool, candidate, { concurrencyRef });

package/lib/rotate.js

@@ -14,6 +14,9 @@ import {
   isKeyBroken,
   formatExhaustionMessage,
   sortAttemptList,
+  getSessionSticky,
+  setSessionSticky,
+  clearSessionSticky,
 } from './pool.js';
 import { pickCascadeFallback, CASCADE_MAX_DEPTH } from './cascade.js';
 import { createRequestBudget, BUDGET_EXHAUSTED_TIMEOUT, BUDGET_EXHAUSTED_ATTEMPTS } from './request-budget.js';
@@ -104,7 +107,8 @@ export function createRotate(deps) {
       let lastFailure = null;
       const breaker = runtime0.circuitBreakerEnabled === false ? null : circuitBreaker;
       let activePermit = null;
-      const reqStore = { pool, pickedRef: undefined, concurrencyRef: undefined, startMs: now() };
+      const sessionId = options?.sessionId ?? options?.session ?? options?.metadata?.sessionId ?? options?.chatId ?? options?.conversationId;
+      const reqStore = { pool, pickedRef: undefined, concurrencyRef: undefined, startMs: now(), sessionId };
       setRotateStartMs(reqStore.startMs);
       const wallNow = Date.now();
       const quotaManaged = hasModelQuotaConfig(pool);
@@ -155,7 +159,15 @@ export function createRotate(deps) {
       }
       const strategy = pool.routingStrategy ?? runtime0.routingStrategy ?? 'round-robin';
       if (strategy !== 'round-robin') {
-        attemptList = sortAttemptList(attemptList, strategy, { latencyHistogram, concurrencyTracker, weights: pool.weightsMap, tiers: pool.tiers });
+        attemptList = sortAttemptList(attemptList, strategy, {
+          latencyHistogram,
+          concurrencyTracker,
+          weights: pool.weightsMap,
+          tiers: pool.tiers,
+          sessionId,
+          sessionSticky: sessionId ? getSessionSticky(pool, sessionId) : null,
+          lastUsed: pool.state.lastUsed,
+        });
       }
       if (strategy !== 'least-loaded' && runtime0.concurrencyLimit > 0 && concurrencyTracker.isEnabled()) {
         // #193 / #365: prefer least-loaded key within limit with weights
@@ -178,6 +190,7 @@ export function createRotate(deps) {
 
       const penalizeRef = (targetRef, errCode, errMsg) => {
         if (!targetRef) return;
+        if (sessionId) clearSessionSticky(pool, sessionId);
         if (errCode === LOCAL_QUOTA_CODE) return;
         const _retry = parseRetryAfter(errMsg);
         const _base = pool.cooldownMs ?? cooldownMs;
@@ -186,11 +199,16 @@ export function createRotate(deps) {
         const cls = classifyFailure({ code: errCode, message: errMsg });
         const _b = recordFailure(pool, targetRef, now(), _effBase, _max, cls.soft, true);
 
-        // #337: connect quota-window calendar reset for quota exhaustion
-        // "rate limit exceeded" and "deadline exceeded" are not evidence
-        // of an exhausted billing quota. Keep those on ordinary cooldowns.
-        const isQuota = errCode === 'QUOTA' || cls.code === 'QUOTA' ||
-          /\b(?:insufficient[_\s-]+quota|quota(?:\s+is)?\s+(?:exhausted|exceeded)|exceeded\s+(?:your\s+)?(?:current\s+)?quota)\b/i.test(errMsg);
+        // #337 & #486 (GitHub #24): connect quota-window calendar reset for quota exhaustion
+        // Transient rate limiting (RPM/TPM, requests/tokens per minute, concurrency)
+        // must NOT be locked until midnight. Keep those on ordinary cooldowns.
+        const isRateThrottling = /\b(?:rpm|tpm|requests?\s+per\s+minute|tokens?\s+per\s+minute|per[-_\s]*minute|per[-_\s]*second|concurrency|requests?\s+limit|tokens?\s+limit|traffic)\b/i.test(errMsg) ||
+          (/\b(?:rate[-_\s]*limit)\b/i.test(errMsg) && !/\b(?:insufficient[_\s-]+quota|exceeded\s+(?:your\s+)?(?:current\s+)?quota|credit\s+balance|billing)\b/i.test(errMsg));
+
+        const isQuota = !isRateThrottling && (
+          (errCode === 'QUOTA' && !/\b(?:rpm|tpm|rate|traffic|throttle)\b/i.test(errMsg)) ||
+          /\b(?:quota(?:\s+is)?\s+(?:exhausted|exceeded)|exceeded\s+(?:your\s+)?(?:current\s+)?quota|insufficient[_\s-]+quota|credit\s+balance|billing\s+quota|out\s+of\s+credits?)\b/i.test(errMsg)
+        );
         const qWindow = pool.quotaResetWindow ?? runtime0.quotaResetWindow;
         if (isQuota && qWindow) {
           const quotaResetAt = poolResetAt(pool, qWindow, now());
@@ -439,6 +457,7 @@ export function createRotate(deps) {
                   // #336: record success for the active key upon successful stream finish
                   if (activeRef) {
                     recordSuccess(pool, activeRef, now());
+                    if (sessionId) setSessionSticky(pool, sessionId, activeRef);
                   }
                   if (activeRef) {
                     const usedTokens = extractUsageTokens(chunk?.usage ?? chunk?.metadata?.usage);

package/package.json

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