@goodandready/dsh-key-rotation 0.8.61 → 0.8.62

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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

package/lib/client.js

@@ -235,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 = {
@@ -420,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
@@ -1127,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;
@@ -2448,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 })
@@ -2661,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/index.js

@@ -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/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';
@@ -412,7 +438,10 @@ 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.lastUsed || (deps.pool && deps.pool.state && deps.pool.state.lastUsed);
+    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) {

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' || strategy === 'sticky') {
-      list = sortAttemptList(list, strategy, { latencyHistogram, concurrencyTracker, weights: pool.weightsMap, tiers: pool.tiers, lastUsed: pool.state.lastUsed });
+      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
@@ -127,7 +137,15 @@ export function createResolver({
     const quotaManaged = hasModelQuotaConfig(pool) && isQuotaManagedRequest(runtime.index, ref, requested);
     let start = strategy === 'round-robin' ? (pool.state.pointer ?? 0) : 0;
     if (strategy === 'sticky') {
-      const lastIdx = pool.state.lastUsed ? list.indexOf(pool.state.lastUsed) : -1;
+      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)) {
@@ -229,14 +247,14 @@ export function createResolver({
       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) {
@@ -268,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, lastUsed: pool.state.lastUsed });
+        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;
@@ -444,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.61",
+  "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": [