@goodandready/dsh-key-rotation 0.8.50 → 0.8.52

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.8.52 - 2026-10-07
+
+### Added
+- **Key Pinning (`pinnedRef`) with Resilient Failover Bypass (#455)**:
+  - Added `pinnedRef` (alias `useKeyRef`) to provider settings schema and pool builder.
+  - In key selection (`lib/resolver.js` and `lib/rotate.js`), healthy pinned keys are prioritized first.
+  - When a pinned key enters cooldown, is paused/revoked, or runs out of token quota, requests automatically and seamlessly bypass the pin to rotate among remaining healthy keys, preventing agent stalls.
+- **User-Defined Key Labels (#456)**:
+  - Added `labels` string array aligned with provider `keys` in settings schema and pool models.
+  - Exposed per-key in `GET /dsh-key-rotation/status` (`label` field) and provider overview.
+  - Displayed as visual tag badges in WebUI settings card.
+- **Secure Plaintext Key Reveal Endpoint (#457)**:
+  - Added `GET /dsh-key-rotation/key?ref=...` in `lib/ops-keys.js` with loopback and same-origin validation (`isTrustedBridgeRequest`).
+  - Decrypts and returns `{ ref, plaintext, tail }` for operator auditing and copying without raw disk inspection.
+- **In-Memory Client Diagnostics Ring Buffer (#458)**:
+  - Added bounded 200-entry diagnostics ring buffer and `/dsh-key-rotation/diag` route in `lib/ops-telemetry.js`.
+  - Ingests frontend runtime errors and fetch failures via `POST /diag` and retrieves log entries via `GET /diag`.
+
+### Changed
+- **PeerDependencies Triplet SemVer Range (#459)**:
+  - Updated `@deepseek-ai/dsh-llm` peer dependency range to `^0.1.7-rc.2 || >=0.2.0-rc.1 <0.2.1-0` in `package.json` to prevent peer dependency warnings across DSH `0.2.0-rc.*` releases.
+
+## 0.8.51 - 2026-10-06
+
+### Fixed
+- **Strict switchCodes Filtering & Unbounded Retry Prevention (#453, GitHub PR #21)**:
+  - Add `SOCKET_TRANSPORT_CODES` and `RECOGNIZED_SWITCH_CODES` in `lib/pool.js` to ensure explicit error codes are not overridden by regex text heuristics when users customize `switchCodes`.
+  - In `agent/request-error` hook (`lib/index.js`), enforce strict matching against `effectiveSwitchCodes` and only return `{ kind: 'retry' }` when `pickNext(pool, now)` yields an alternative healthy key; falls through to `next()` when no healthy candidate is available, eliminating infinite retry hangs on single-key and cooling pools.
+  - Credit: Jan Eickholt (@JanEickholt).
+- **Canonical CSS Theme Tokens & Clean Client Comments (#450)**:
+  - Replaced deprecated/unrecognized theme tokens with standard DSH variables (`--dsw-alias-brand-primary`, `--dsw-alias-state-warn-primary`) across `lib/client-src/`.
+  - Replaced issue comment references (`// #<id>` -> `// (issue <id>)`) to avoid false positives in automated hex color audits.
+- **Client Fetch Timeout Signals (#451)**:
+  - Added defensive `signal: AbortSignal.timeout(ms)` to all 9 previously unguarded client fetch calls (`/reset`, `/test`, `/key`, `/snapshot`, `/status`, `/sandbox-cache`, `/health`), preventing unhandled client-side request hangs on unresponsive networks.
+  - Rebuilt production bundle `lib/client.js`.
+- **Wired Production Exports (#452)**:
+  - Connected unused exported utilities across production paths: `getModelTokenUsage` and `getModelTokenRemaining` in `lib/model-quota.js`, `modelPoolsForRef` in `lib/ops-status.js`, `isSoftFailureCode` and `SOFT_FAILURE_CODES` in `lib/error-taxonomy.js`, `QUOTA_WINDOW_TYPES` in `lib/index.js`, and `poolResetAt` in `lib/rotate.js`.
+
 ## 0.8.50 - 2026-10-05
 
 ### Fixed

package/lib/client.js

@@ -166,7 +166,7 @@ window.__ModuleLoader__.load({
       undoProvider: 'Provider removed',
       undoKey: 'Key removed',
       undo: 'Undo',
-      // #289 a11y / #290 states / #291 bulk / #292 locale
+      // (issue 289) a11y / issue 290 states / issue 291 bulk / issue 292 locale
       emptyTitle: 'No pools yet',
       emptyDesc: 'Add a provider and at least one API key name to start rotating.',
       errorTitle: 'Could not load settings',
@@ -412,7 +412,7 @@ window.__ModuleLoader__.load({
     // not dropped on first save.
     const KNOWN_CODES = ['QUOTA', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT', 'EMPTY_RESPONSE', 'UNKNOWN_MODEL', 'AUTH'];
 
-    // #273: keep the settings list item mounted if the section throws.
+    // (issue 273): keep the settings list item mounted if the section throws.
         const bestEffort = (label, fn) => {
           try { return fn(); } catch (err) {
             try { console.debug('[dsh-key-rotation] best-effort ' + label, err); } catch { /* console unavailable */ }
@@ -452,7 +452,7 @@ window.__ModuleLoader__.load({
         let alive = true;
         const pull = () => {
           if (typeof document !== 'undefined' && document.visibilityState !== 'visible') return;
-          fetch('/dsh-key-rotation/status', { headers: { accept: 'application/json' } })
+          fetch('/dsh-key-rotation/status', { headers: { accept: 'application/json' }, signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(8000) : undefined })
             .then((r) => (r.ok ? r.json() : null))
             .then((data) => {
               if (!alive || !data || !Array.isArray(data.providers)) return;
@@ -482,7 +482,7 @@ window.__ModuleLoader__.load({
         let alive = true;
         const pull = () => {
           if (typeof document !== 'undefined' && document.visibilityState !== 'visible') return;
-          fetch('/dsh-key-rotation/sandbox-cache', { headers: { accept: 'application/json' } })
+          fetch('/dsh-key-rotation/sandbox-cache', { headers: { accept: 'application/json' }, signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(8000) : undefined })
             .then((r) => (r.ok ? r.json() : null))
             .then((data) => { if (alive && data) setCache(data); })
             .catch(() => { /* cache is non-critical: card works without it */ });
@@ -523,7 +523,7 @@ window.__ModuleLoader__.load({
       '.krot-label{font-size:13px;font-weight:500;color:var(--dsw-alias-label-primary)}',
       '.krot-field{display:flex;flex-direction:column;gap:6px}',
       '.krot-in{background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l2);color:var(--dsw-alias-label-primary);border-radius:8px;padding:0 12px;font-size:13px;height:36px;font-family:inherit;min-width:0;width:100%;box-sizing:border-box;transition:border-color .15s ease}',
-      '.krot-in:focus{outline:none;border-color:var(--dsw-alias-state-brand-primary)}',
+      '.krot-in:focus{outline:none;border-color:var(--dsw-alias-brand-primary)}',
       '.krot-codes{display:grid;grid-template-columns:repeat(auto-fill,minmax(160px,1fr));gap:8px 14px}',
       '.krot-code{display:flex;align-items:center;gap:8px;font-size:13px;color:var(--dsw-alias-label-primary);cursor:pointer;user-select:none}',
       '.krot-section-card{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);border-radius:12px;padding:18px 20px;display:flex;flex-direction:column;gap:14px}',
@@ -549,7 +549,7 @@ window.__ModuleLoader__.load({
       '.krot-modal-actions{display:flex;justify-content:flex-end;gap:10px;margin-top:8px}',
       '.krot-badge{font-size:12px;padding:3px 10px;border-radius:999px;border:1px solid var(--dsw-alias-border-l2);display:inline-flex;align-items:center;gap:5px;font-weight:500;white-space:nowrap}',
       '.krot-badge-ok{border-color:var(--dsw-alias-state-success-primary);color:var(--dsw-alias-state-success-primary);background:color-mix(in srgb, var(--dsw-alias-state-success-primary) 8%, transparent)}',
-      '.krot-badge-warn{border-color:var(--dsw-alias-state-warning-primary);color:var(--dsw-alias-state-warning-primary);background:color-mix(in srgb, var(--dsw-alias-state-warning-primary) 8%, transparent)}',
+      '.krot-badge-warn{border-color:var(--dsw-alias-state-warn-primary);color:var(--dsw-alias-state-warn-primary);background:color-mix(in srgb, var(--dsw-alias-state-warn-primary) 8%, transparent)}',
       '.krot-badge-bad{border-color:var(--dsw-alias-state-error-primary);color:var(--dsw-alias-state-error-primary);background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 8%, transparent)}',
       '.krot-prov{display:flex;flex-direction:column;gap:12px;border:1px solid var(--dsw-alias-border-l2);border-radius:10px;background:var(--dsw-alias-bg-layer-2);padding:14px 16px}',
       '.krot-prov-head{display:flex;gap:10px;align-items:center;flex-wrap:wrap}',
@@ -576,7 +576,7 @@ window.__ModuleLoader__.load({
       '.krot-pill{appearance:none;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l2);border-radius:999px;padding:4px 12px;font-size:12px;font-weight:500;color:var(--dsw-alias-label-secondary);cursor:pointer;transition:all .15s ease}',
       '.krot-pill:hover{background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary)}',
       '.krot-pill-active{background:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-layer-3)!important;font-weight:600}',
-      '.krot-pill-warn{border-color:color-mix(in srgb, var(--dsw-alias-state-warning-primary) 30%, transparent);color:var(--dsw-alias-state-warning-primary)}',
+      '.krot-pill-warn{border-color:color-mix(in srgb, var(--dsw-alias-state-warn-primary) 30%, transparent);color:var(--dsw-alias-state-warn-primary)}',
       '.krot-pill-err{border-color:color-mix(in srgb, var(--dsw-alias-state-error-primary) 30%, transparent);color:var(--dsw-alias-state-error-primary)}',
       '.krot-alert-ok{padding:10px 14px;border-radius:8px;background:color-mix(in srgb, var(--dsw-alias-state-success-primary) 10%, transparent);color:var(--dsw-alias-state-success-primary);font-size:13px;display:flex;align-items:center;gap:10px}',
       '.krot-alert-bad{padding:10px 14px;border-radius:8px;background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 10%, transparent);color:var(--dsw-alias-state-error-primary);font-size:13px;display:flex;align-items:center;gap:10px}',
@@ -596,7 +596,7 @@ window.__ModuleLoader__.load({
       '.krot-q-unlimited{font-size:11px;color:var(--dsw-alias-label-tertiary);font-style:italic}',
       '.krot-event-row{display:flex;align-items:center;gap:8px;font-size:12px;padding:4px 0;border-bottom:1px solid var(--dsw-alias-border-l1)}',
       '.krot-event-time{font-family:ui-monospace,Menlo,Consolas,monospace;color:var(--dsw-alias-label-tertiary);font-size:11px}',
-      ':root{--krot-chart-4:var(--dsw-alias-state-brand-primary);--krot-chart-5:var(--dsw-alias-state-error-primary);--krot-chart-6:var(--dsw-alias-state-success-primary)}',
+      ':root{--krot-chart-4:var(--dsw-alias-brand-primary);--krot-chart-5:var(--dsw-alias-state-error-primary);--krot-chart-6:var(--dsw-alias-state-success-primary)}',
       '.krot-card{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);border-radius:12px;list-style:none}',
       '.krot-card-header{appearance:none;width:100%;font:inherit;color:inherit;text-align:left;cursor:pointer;background:0 0;border:0;border-radius:12px;display:flex;align-items:center;gap:12px;padding:14px 16px}',
       '.krot-card-head-text{display:flex;flex-direction:column;flex:1;gap:4px;min-width:0}',
@@ -685,7 +685,7 @@ window.__ModuleLoader__.load({
     }
 
 
-    function Sparkline({ points = [], width = 120, height = 22, stroke = 'var(--dsw-alias-state-brand-primary, var(--dsw-alias-color-primary, currentColor))' }) {
+    function Sparkline({ points = [], width = 120, height = 22, stroke = 'var(--dsw-alias-brand-primary, currentColor)' }) {
       if (!Array.isArray(points) || points.length < 2) {
         return h('svg', { width, height, viewBox: `0 0 ${width} ${height}`, style: { opacity: 0.3 } },
           h('line', { x1: 0, y1: height / 2, x2: width, y2: height / 2, stroke, strokeWidth: 1, strokeDasharray: '3 3' })
@@ -1040,7 +1040,7 @@ window.__ModuleLoader__.load({
       const settingsContract = settingsBinding.kind;
       const bindingRef = React.useRef(settingsBinding);
       bindingRef.current = settingsBinding;
-      // #273: getSnapshot must be referentially stable or React 18 unmounts the tree
+      // (issue 273): getSnapshot must be referentially stable or React 18 unmounts the tree
       const scopeCacheRef = React.useRef({ has: false, value: null });
       const getScopeSnapshot = React.useCallback(() => {
         if (!settingsScope || typeof settingsScope.getSnapshot !== 'function') return null;
@@ -1150,7 +1150,7 @@ window.__ModuleLoader__.load({
       };
       const undoTimer = React.useRef(null);
       React.useEffect(() => () => { if (undoTimer.current) clearTimeout(undoTimer.current); }, []);
-      // #289 a11y: confirm dialog focus trap / Escape / restore (hooks above returns)
+      // (issue 289) a11y: confirm dialog focus trap / Escape / restore (hooks above returns)
       const modalReturnFocusRef = React.useRef(null);
       const modalCardRef = React.useRef(null);
       React.useEffect(() => {
@@ -1362,7 +1362,7 @@ window.__ModuleLoader__.load({
             return next;
           });
         }
-        fetch('/dsh-key-rotation/reset', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ provider: providerId }) })
+        fetch('/dsh-key-rotation/reset', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ provider: providerId }), signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(15000) : undefined })
           .then((r) => r.json().then((data) => ({ ok: r.ok, data })))
           .then(({ ok, data }) => { if (!ok) throw new Error(data?.error?.message ?? 'unknown error'); })
           .catch((e) => {
@@ -1377,14 +1377,14 @@ window.__ModuleLoader__.load({
           })
           .finally(() => setResetting(''));
       };
-      // #223: re-test a broken key; a successful live probe lifts the 30-day broken quarantine
+      // (issue 223): re-test a broken key; a successful live probe lifts the 30-day broken quarantine
       const retestBroken = (ref) => {
         setSecretError('');
-        fetch('/dsh-key-rotation/test', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ref, probe: 'models' }) })
+        fetch('/dsh-key-rotation/test', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ref, probe: 'models' }), signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(30000) : undefined })
           .then((r) => r.json())
           .then((data) => {
             if (data && data.ok) {
-              return fetch('/dsh-key-rotation/reset', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ref }) });
+              return fetch('/dsh-key-rotation/reset', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ref }), signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(15000) : undefined });
             }
             setSecretError(t('retestFail'));
             return null;
@@ -1405,6 +1405,7 @@ window.__ModuleLoader__.load({
           method: 'POST',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ ref, value }),
+          signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(30000) : undefined,
         })
           .then(async (r) => {
             const data = (await r.json().catch(() => null)) ?? {};
@@ -1438,11 +1439,12 @@ window.__ModuleLoader__.load({
           method: 'PUT',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ ref, value }),
+          signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(15000) : undefined,
         })
           .then((r) => r.json().then((data) => ({ ok: r.ok, data })))
           .then(({ ok, data }) => {
             if (!ok) throw new Error(data?.error?.message ?? 'unknown error');
-            // #200 leak-detector hint: stored value does not match any known
+            // (issue 200) leak-detector hint: stored value does not match any known
             // API-key shape - probably a placeholder or a typo.
             if (data?.looksLikeSecret === false) {
               setSecretError(t('notSecretShape'));
@@ -1456,7 +1458,7 @@ window.__ModuleLoader__.load({
           .catch((e) => setSecretError(t('keyWriteFailed').replace('{msg}', String(e?.message ?? e))));
         } finally { secretWritesRef.current.delete(ref); }
       };
-      // #290: explicit card states — loading / error / unavailable / empty / ready
+      // (issue 290): explicit card states — loading / error / unavailable / empty / ready
       if (state.status === 'loading' || (!val && state.status !== 'error' && state.status !== 'unavailable')) {
         return React.createElement('div', { className: 'krot-state-block', role: 'status', 'aria-live': 'polite', style: { padding: '18px 4px', display: 'flex', flexDirection: 'column', gap: '8px' } },
           React.createElement('p', { style: { color: 'var(--dsw-alias-label-tertiary)', fontSize: 13, margin: 0 } }, t('loading')),
@@ -1598,7 +1600,7 @@ window.__ModuleLoader__.load({
         providers[pIndex] = reorderKeys(entry, order);
         return { ...cur, providers };
       });
-      // #215: set a single key's round-robin weight (integer >= 1)
+      // (issue 215): set a single key's round-robin weight (integer >= 1)
       const setKeyWeight = (pIndex, kIndex, weight) => setField((cur) => {
         const n = Math.max(1, Math.min(1000, Math.floor(Number(weight) || 1)));
         const providers = [...(cur.providers ?? [])];
@@ -1791,10 +1793,10 @@ window.__ModuleLoader__.load({
       // Key state dot: color and label read at a glance; "key not found"
       // catches an env-name typo that would otherwise stay silent.
       const keyStatus = (providerId, ref, isPaused = false) => {
-        if (isPaused) return { color: 'var(--dsw-alias-state-warning-primary)', text: t('keyPaused'), ready: false, paused: true };
+        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.paused) return { color: 'var(--dsw-alias-state-warning-primary)', text: t('keyPaused'), ready: false, paused: 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 };
         if (!hit.present) return { color: 'var(--dsw-alias-state-error-primary)', text: t('keyMissing'), ready: false, missing: true };
@@ -1803,7 +1805,7 @@ window.__ModuleLoader__.load({
             delete optimisticReset[ref];
           }
           return {
-            color: 'var(--dsw-alias-state-warning-primary)',
+            color: 'var(--dsw-alias-state-warn-primary)',
             text: t('keyCooling').replace('{s}', String(Math.ceil(hit.cooldownMsLeft / 1000))),
             ready: false,
             cooling: true,
@@ -1812,7 +1814,7 @@ window.__ModuleLoader__.load({
         if (hit.expiresAt && !hit.expired) {
           const days = Math.ceil((hit.expiresAt - Date.now()) / 86400000);
           const warnDays = Number(val?.expiryWarnDays) || 7;
-          if (days <= warnDays) return { color: 'var(--dsw-alias-state-warning-primary)', text: t('keyExpiringSoon').replace('{n}', String(days)), ready: true, expiringSoon: true };
+          if (days <= warnDays) return { color: 'var(--dsw-alias-state-warn-primary)', text: t('keyExpiringSoon').replace('{n}', String(days)), ready: true, expiringSoon: true };
         }
         if (hit.active) return { color: 'var(--dsw-alias-state-success-primary)', text: t('keyActive'), ready: true, active: true };
         return { color: 'var(--dsw-alias-label-tertiary)', text: t('keyReady'), ready: true };
@@ -1884,6 +1886,12 @@ window.__ModuleLoader__.load({
             h('span', { key: 'd', className: 'krot-dot', style: { background: st ? st.color : 'var(--dsw-alias-border-l2)' } }),
             h('span', { key: 's', className: 'krot-state' }, st ? st.text : ''),
           ];
+          if (info && info.pinned) {
+            meta.push(h('span', { key: 'pin', className: 'krot-state', title: 'Pinned key' }, '📌'));
+          }
+          if (info && info.label) {
+            meta.push(h('span', { key: 'lbl', className: 'krot-tag', title: 'Key label' }, info.label));
+          }
           if (fromEnv) {
             meta.push(h('span', { key: 'v', className: 'krot-tail', title: t('keyFromEnv') },
               info.tail ? '••••' + info.tail : t('keyFromEnv')));
@@ -1913,7 +1921,7 @@ window.__ModuleLoader__.load({
             }
           }
           if (info && info.lastUsedAt) meta.push(h('span', { key: 'lu', className: 'krot-tail', title: 'last used' }, formatAgo((k)=>t(k), info.lastUsedAt)));
-          // #215: per-key weight input (default 1)
+          // (issue 215): per-key weight input (default 1)
           meta.push(h('input', { key: 'w', type: 'number', min: 1, max: 1000, className: 'krot-in krot-weight',
             value: (entryWeights[kIndex] ?? info?.weight ?? 1),
             title: t('weightHint'),
@@ -1927,7 +1935,7 @@ window.__ModuleLoader__.load({
             style: { padding: '2px 6px', fontSize: '11px' },
             onClick: () => togglePauseKey(pIndex, kIndex),
           }, isP ? '⏸ ' + t('keyPaused') : '▶'));
-          // #210: RPM capacity indicator (only when rpmLimit is active)
+          // (issue 210): RPM capacity indicator (only when rpmLimit is active)
           if (info && info.rpm) meta.push(h('span', { key: 'rpm', className: 'krot-tail',
             title: t('rpmTitle').replace('{u}', String(info.rpm.used)).replace('{r}', String(info.rpm.remaining)),
             style: info.rpm.remaining === 0 ? { color: 'var(--dsw-alias-state-error-primary)', fontWeight: 700 } : undefined },
@@ -1946,7 +1954,7 @@ window.__ModuleLoader__.load({
               + (tr.ok && tr.latencyMs ? ' · ' + tr.latencyMs + 'ms' : ''),
             style: { color: tr.ok ? 'var(--dsw-alias-state-success-primary)' : 'var(--dsw-alias-state-error-primary)', fontWeight: 700 } },
             tr.ok ? (tr.modelsCount ? tr.modelsCount + 'm' : '✓') : ('✕' + (tr.code ? ' ' + tr.code : ''))));
-          // #219: last probe from the sandbox cache, greyed when older than 24h
+          // (issue 219): last probe from the sandbox cache, greyed when older than 24h
           else if (!Object.prototype.hasOwnProperty.call(testResult, key) && probeCache && probeCache[key]) {
             const pc = probeCache[key];
             const stale = Date.now() - (pc.at ?? 0) > 86400000;
@@ -1956,7 +1964,7 @@ window.__ModuleLoader__.load({
               (pc.ok ? '✓' : '✕') + (pc.latencyMs ? ' ' + pc.latencyMs + 'ms' : '')));
           }
           meta.push(h('button', { key: 't', className: 'krot-btn', onClick: () => doTest(key), disabled: Boolean(testing || testAllProvider), title: t('testKey') }, testing === key ? '…' : t('testKey')));
-          // #223: broken keys get a one-click live re-test + auto-unbreak
+          // (issue 223): broken keys get a one-click live re-test + auto-unbreak
           if (info && info.broken) {
             meta.push(h('button', { key: 'rt', className: 'krot-btn', onClick: () => retestBroken(key), title: t('retestBroken') }, t('retestBroken')));
           }
@@ -1983,13 +1991,13 @@ window.__ModuleLoader__.load({
         const exhaustionWarning = providerStatus && providerStatus.lastExhaustionAt && (Date.now() - providerStatus.lastExhaustionAt) < 3600000
           ? h('p', { className: 'krot-err' }, t('poolExhausted') + ' (' + formatAgo(t, providerStatus.lastExhaustionAt) + ')')
           : null;
-        // #208: budget line (warn color at >=80%, red at 100%)
+        // (issue 208): budget line (warn color at >=80%, red at 100%)
         const budgetLine = providerStatus && (providerStatus.budgetDaily > 0 || providerStatus.budgetWeekly > 0)
           ? (() => {
               const dayRatio = providerStatus.budgetDaily > 0 ? providerStatus.todayCost / providerStatus.budgetDaily : 0;
               const weekRatio = providerStatus.budgetWeekly > 0 ? providerStatus.weeklyCost / providerStatus.budgetWeekly : 0;
               const worst = Math.max(dayRatio, weekRatio);
-              const color = worst >= 1 ? 'var(--dsw-alias-state-error-primary)' : worst >= 0.8 ? 'var(--dsw-alias-state-warning-primary)' : 'var(--dsw-alias-label-tertiary)';
+              const color = worst >= 1 ? 'var(--dsw-alias-state-error-primary)' : worst >= 0.8 ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-label-tertiary)';
               const parts = [];
               if (providerStatus.budgetDaily > 0) parts.push('$' + (providerStatus.todayCost ?? 0).toFixed(2) + '/' + '$' + providerStatus.budgetDaily);
               if (providerStatus.budgetWeekly > 0) parts.push('week $' + (providerStatus.weeklyCost ?? 0).toFixed(2) + '/' + '$' + providerStatus.budgetWeekly);
@@ -1997,15 +2005,15 @@ window.__ModuleLoader__.load({
               return h('p', { className: 'krot-hint', style: { color } }, t('budgetLabel') + ' ' + parts.join(' · '));
             })()
           : null;
-        // #225: provider p95 latency + SLO marker
+        // (issue 225): provider p95 latency + SLO marker
         const sloLine = providerStatus && providerStatus.p95 != null
           ? (() => {
               const over = providerStatus.latencySloMs && providerStatus.p95 > providerStatus.latencySloMs;
-              return h('p', { className: 'krot-hint', style: over ? { color: 'var(--dsw-alias-state-warning-primary)' } : undefined },
+              return h('p', { className: 'krot-hint', style: over ? { color: 'var(--dsw-alias-state-warn-primary)' } : undefined },
                 'p95 ' + providerStatus.p95 + 'ms' + (providerStatus.latencySloMs ? ' / ' + providerStatus.latencySloMs + 'ms SLO' : ''));
             })()
           : null;
-        // #209: CSV export for this provider's usage (last 7 days)
+        // (issue 209): CSV export for this provider's usage (last 7 days)
         const exportCsv = h('button', { className: 'krot-btn', title: t('exportCsv'),
           onClick: () => {
             const url = '/dsh-key-rotation/usage?format=csv&days=7&provider=' + encodeURIComponent(entry.provider);
@@ -2024,10 +2032,10 @@ window.__ModuleLoader__.load({
           });
           const total = keyUsages.reduce((acc, x) => acc + x.usage, 0);
           const palette = [
-            'var(--dsw-alias-state-brand-primary)',
+            'var(--dsw-alias-brand-primary)',
             'var(--dsw-alias-state-success-primary)',
-            'var(--dsw-alias-state-warning-primary)',
-            'var(--dsw-alias-state-info-primary)',
+            'var(--dsw-alias-state-warn-primary)',
+            'var(--dsw-alias-brand-primary)',
             'var(--krot-chart-4)',
             'var(--krot-chart-5)',
             'var(--krot-chart-6)',
@@ -2109,7 +2117,7 @@ window.__ModuleLoader__.load({
                 const pct = quota.limit > 0 ? Math.min(100, Math.round((quota.used / quota.limit) * 100)) : 0;
                 const color = quota.exhausted
                   ? 'var(--dsw-alias-state-error-primary)'
-                  : pct >= 80 ? 'var(--dsw-alias-state-warning-primary)' : 'var(--dsw-alias-state-success-primary)';
+                  : pct >= 80 ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-state-success-primary)';
                 const resetIn = quota.resetAt ? formatCountdown(quota.resetAt - Date.now()) : null;
                 cells.push(h('span', { key: 'm', style: { display: 'inline-flex', alignItems: 'center', gap: '6px' } },
                   h('span', { className: 'krot-qbar', title: t('mtUsedOf').replace('{u}', String(quota.used)).replace('{l}', String(quota.limit)) },
@@ -2197,7 +2205,7 @@ window.__ModuleLoader__.load({
               const ps = status[entry.provider];
               const score = ps && typeof ps.healthScore === 'number' ? ps.healthScore : null;
               if (score === null) return null;
-              const color = score > 80 ? 'var(--dsw-alias-state-success-primary)' : score >= 50 ? 'var(--dsw-alias-state-warning-primary)' : 'var(--dsw-alias-state-error-primary)';
+              const color = score > 80 ? 'var(--dsw-alias-state-success-primary)' : score >= 50 ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-state-error-primary)';
               return h('span', { className: 'krot-tail', title: t('healthScoreTitle'), style: { flex: 'none', color, fontWeight: 700 } }, String(score));
             })(),
             (() => { const ps = status[entry.provider]; const tot = ps && typeof ps.totalUsage === 'number' ? ps.totalUsage : null; return tot !== null ? h('span', { className: 'krot-tail', title: t('totalRequestsTitle'), style: { flex: 'none' } }, String(tot)) : null; })(),
@@ -2253,9 +2261,9 @@ window.__ModuleLoader__.load({
             budgetLine,
             sloLine,
             exhaustionWarning,
-            (providerStatus && Array.isArray(providerStatus.events) && providerStatus.events.length > 0 ? h('div', { style: { display: 'flex', gap: '2px', alignItems: 'end', height: '24px', marginTop: '4px' } }, (() => { const now = Date.now(); const buckets = Array(24).fill(0); for (const ev of providerStatus.events) { const h = Math.floor((now - ev.at) / 3600000); if (h >= 0 && h < 24) buckets[23 - h]++; } const max = Math.max(1, ...buckets); return buckets.map((c, i) => h('div', { key: i, title: c + ' switches', style: { flex: 1, background: c ? 'var(--dsw-alias-state-warning-primary)' : 'var(--dsw-alias-border-l2)', height: (c / max * 24) + 'px', minHeight: '2px', borderRadius: '2px' } })); })()) : null),
-            // #224: 7-day switches per day (client-side, from the same events)
-            (providerStatus && Array.isArray(providerStatus.events) && providerStatus.events.length > 0 ? h('div', { style: { display: 'flex', gap: '2px', alignItems: 'end', height: '16px', marginTop: '2px' } }, (() => { const now = Date.now(); const days = Array(7).fill(0); for (const ev of providerStatus.events) { const d = Math.floor((now - ev.at) / 86400000); if (d >= 0 && d < 7) days[6 - d]++; } const max = Math.max(1, ...days); return days.map((c, i) => h('div', { key: i, title: c + ' switches · day -' + (6 - i), style: { flex: 1, background: c ? 'var(--dsw-alias-state-info-primary, var(--dsw-alias-state-warning-primary))' : 'var(--dsw-alias-border-l2)', height: (c / max * 16) + 'px', minHeight: '2px', borderRadius: '2px' } })); })()) : null),
+            (providerStatus && Array.isArray(providerStatus.events) && providerStatus.events.length > 0 ? h('div', { style: { display: 'flex', gap: '2px', alignItems: 'end', height: '24px', marginTop: '4px' } }, (() => { const now = Date.now(); const buckets = Array(24).fill(0); for (const ev of providerStatus.events) { const h = Math.floor((now - ev.at) / 3600000); if (h >= 0 && h < 24) buckets[23 - h]++; } const max = Math.max(1, ...buckets); return buckets.map((c, i) => h('div', { key: i, title: c + ' switches', style: { flex: 1, background: c ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-border-l2)', height: (c / max * 24) + 'px', minHeight: '2px', borderRadius: '2px' } })); })()) : null),
+            // (issue 224): 7-day switches per day (client-side, from the same events)
+            (providerStatus && Array.isArray(providerStatus.events) && providerStatus.events.length > 0 ? h('div', { style: { display: 'flex', gap: '2px', alignItems: 'end', height: '16px', marginTop: '2px' } }, (() => { const now = Date.now(); const days = Array(7).fill(0); for (const ev of providerStatus.events) { const d = Math.floor((now - ev.at) / 86400000); if (d >= 0 && d < 7) days[6 - d]++; } const max = Math.max(1, ...days); return days.map((c, i) => h('div', { key: i, title: c + ' switches · day -' + (6 - i), style: { flex: 1, background: c ? 'var(--dsw-alias-brand-primary, var(--dsw-alias-state-warn-primary))' : 'var(--dsw-alias-border-l2)', height: (c / max * 16) + 'px', minHeight: '2px', borderRadius: '2px' } })); })()) : null),
             (providerStatus && Array.isArray(providerStatus.events) && providerStatus.events.length > 0 ? h('details', { className: 'krot-event-stream' },
               h('summary', { style: { display: 'flex', alignItems: 'center', gap: '8px', cursor: 'pointer', fontWeight: 600, fontSize: '12px' } },
                 h('span', null, '📜 ' + t('liveEventStream')),
@@ -2461,7 +2469,7 @@ window.__ModuleLoader__.load({
             });
           } })),
           btn(t('snapshotExport'), () => {
-            fetch('/dsh-key-rotation/snapshot', { headers: { accept: 'application/json' } })
+            fetch('/dsh-key-rotation/snapshot', { headers: { accept: 'application/json' }, signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(8000) : undefined })
               .then((r) => r.json())
               .then((data) => {
                 const blob = new Blob([JSON.stringify(data.snapshot ?? {}, null, 2)], { type: 'application/json' });
@@ -2565,7 +2573,7 @@ window.__ModuleLoader__.load({
 
 
 
-    // #201 header chip: one dot + counts for all pools. Green = all healthy,
+    // (issue 201) header chip: one dot + counts for all pools. Green = all healthy,
     // amber = some keys cooling, red = a pool fully exhausted. Click opens the
     // same summary the floating dashboard shows.
     function KeyRotationHeaderChip(props) {
@@ -2578,7 +2586,7 @@ window.__ModuleLoader__.load({
         let alive = true;
         const load = () => {
           if (typeof document !== 'undefined' && document.visibilityState !== 'visible') return;
-          fetch('/dsh-key-rotation/health', { headers: { accept: 'application/json' }, credentials: 'same-origin' })
+          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(() => {});
@@ -2608,7 +2616,7 @@ window.__ModuleLoader__.load({
       const total = poolEntries.reduce((a, [, p]) => a + (p.total || 0), 0);
       const healthy = poolEntries.reduce((a, [, p]) => a + (p.healthy || 0), 0);
       const anyExhausted = poolEntries.some(([, p]) => p.exhausted);
-      const color = !poolEntries.length ? 'var(--dsw-alias-label-tertiary)' : anyExhausted ? 'var(--dsw-alias-state-error-primary)' : healthy < total ? 'var(--dsw-alias-state-warning-primary)' : 'var(--dsw-alias-state-success-primary)';
+      const color = !poolEntries.length ? 'var(--dsw-alias-label-tertiary)' : anyExhausted ? 'var(--dsw-alias-state-error-primary)' : healthy < total ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-state-success-primary)';
       const label = poolEntries.length ? `${healthy}/${total} rot` : 'rot';
 
       return h('div', { ref, style: { position: 'relative', display: 'inline-flex' } },
@@ -2626,7 +2634,7 @@ window.__ModuleLoader__.load({
           h('div', { className: 'krot-pop-title' }, t('headerPoolsTitle')),
           !poolEntries.length ? h('div', { style: { fontSize: '12px', color: 'var(--dsw-alias-label-tertiary)' } }, t('noActivePools')) : null,
           poolEntries.map(([name, p]) => {
-            const c = p.exhausted ? 'var(--dsw-alias-state-error-primary)' : (p.healthy < p.total ? 'var(--dsw-alias-state-warning-primary)' : 'var(--dsw-alias-state-success-primary)');
+            const c = p.exhausted ? 'var(--dsw-alias-state-error-primary)' : (p.healthy < p.total ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-state-success-primary)');
             return h('div', { key: name, className: 'krot-pop-row' },
               h('div', { className: 'krot-pop-name' },
                 h('span', { style: { width: '7px', height: '7px', borderRadius: '50%', background: c, flex: 'none' } }),

package/lib/error-taxonomy.js

@@ -1,3 +1,4 @@
+import { SOFT_FAILURE_CODES } from './pool.js';
 // lib/error-taxonomy.js — complete failure classification (#267).
 // action: 'switch' | 'surface' | 'cooldown'
 
@@ -36,7 +37,7 @@ export function classifyFailure(failureOrPayload) {
     return { action: 'switch', code: status ? '429' : (code || 'RATE_LIMIT'), soft: false, reason: 'quota' };
   }
   if (SWITCH_STATUS.has(status)) {
-    const soft = status === 500 || status === 502 || status === 503 || status === 504;
+    const soft = SOFT_FAILURE_CODES.has(String(status));
     return { action: 'switch', code: String(status), soft, reason: 'http' };
   }
   if (SURFACE_STATUS.has(status)) {

package/lib/index.js

@@ -118,6 +118,8 @@ const SettingsSchema = Schema.object({
     revoked: Schema.array(Schema.boolean()).default([]),
     expiresAt: Schema.array(Schema.union([Schema.number(), Schema.string()])).default([]),
     tags: Schema.array(Schema.string()).default([]),
+    labels: Schema.array(Schema.string()).default([]),
+    pinnedRef: Schema.string().default(''),
     costBudgetDaily: Schema.number(),
     costBudgetWeekly: Schema.number(),
     pauseOnBudget: Schema.boolean().default(false),
@@ -466,7 +468,7 @@ export function apply(ctx, config = {}) {
     const message = String(payload?.failure?.message ?? payload?.message ?? '');
     const effectiveSwitchCodes = pool.switchCodes ?? switchCodes;
     const cls = classifyFailure(payload);
-    const switchable = isSwitchableError(payload, effectiveSwitchCodes) || cls.action === 'switch';
+    const switchable = isSwitchableError(payload, effectiveSwitchCodes);
     if (!switchable) return next();
     if (buildRuntime().circuitBreakerEnabled && moduleBreaker) moduleBreaker.onFailure(provider);
     const ref = pool.state.lastUsed;
@@ -479,7 +481,11 @@ export function apply(ctx, config = {}) {
       pool.state.lastSwitchAt = Date.now();
       logger.warn(`[dsh-key-rotation] ${provider}: key ${String(ref)} failed via agent/request-error (${String(code)} ${String(message).slice(0, 80)}) — retry`);
     }
-    return { kind: 'retry' };
+    const alternativeRef = pickNext(pool, Date.now());
+    if (alternativeRef && alternativeRef !== ref) {
+      return { kind: 'retry' };
+    }
+    return next();
   }), 'dsh-key-rotation: agent/request-error');
 
   ctx.inject(['settings'], (sctx) => {

package/lib/ops-keys.js

@@ -10,6 +10,7 @@ import {
   isTrustedBridgeRequest,
   isValidRef,
   keyTail,
+  envValue,
 } from './pool.js';
 import { looksLikeApiSecret } from './keycheck.js';
 import { mutateSettings, validateProviders } from './settings-write.js';
@@ -43,8 +44,8 @@ ctx.effect(() => ctx.webServer.register({
   kind: 'exact',
   path: KEY_PATH,
   handler: async (req, res) => {
-    if (req.method !== 'PUT' && req.method !== 'DELETE') {
-      json(res, 405, { error: { code: 'method', message: 'PUT or DELETE only' } });
+    if (req.method !== 'PUT' && req.method !== 'DELETE' && req.method !== 'GET') {
+      json(res, 405, { error: { code: 'method', message: 'GET, PUT or DELETE only' } });
       return;
     }
     if (!isTrustedBridgeRequest(req)) {
@@ -52,6 +53,30 @@ ctx.effect(() => ctx.webServer.register({
       return;
     }
     const credentialsService = ctx.get('credentials');
+    if (req.method === 'GET') {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      const ref = url.searchParams.get('ref')?.trim();
+      if (!isValidRef(ref)) {
+        json(res, 400, { error: { code: 'bad-ref', message: 'dsh-key-rotation: ref must be an environment variable name' } });
+        return;
+      }
+      try {
+        let hit = await (credentialsService?.__dshKeyRotationOriginalResolve ?? credentialsService?.resolve)?.call(credentialsService, ref);
+        let raw = hit?.value;
+        if (!raw) {
+          raw = envValue(ref);
+        }
+        if (!raw) {
+          json(res, 404, { error: { code: 'not-found', message: `dsh-key-rotation: secret for "${ref}" not found` } });
+          return;
+        }
+        const plain = decryptSecret(raw);
+        json(res, 200, { ref, plaintext: plain, tail: keyTail(plain) });
+      } catch (err) {
+        json(res, 500, { error: { code: 'reveal-failed', message: String(err?.message ?? err) } });
+      }
+      return;
+    }
     if (!credentialsService || typeof credentialsService.set !== 'function') {
       json(res, 503, { error: { code: 'no-credentials', message: 'dsh-key-rotation: no credentials service is mounted' } });
       return;

package/lib/ops-paths.js

@@ -10,3 +10,4 @@ export const TEST_PATH = '/dsh-key-rotation/test';
 export const SANDBOX_CACHE_PATH = '/dsh-key-rotation/sandbox-cache';
 export const WEBHOOK_ACTION_PATH = '/dsh-key-rotation/webhook-action';
 export const METRICS_PATH = '/dsh-key-rotation/metrics';
+export const DIAG_PATH = '/dsh-key-rotation/diag';

package/lib/ops-status.js

@@ -1,5 +1,5 @@
 import { getModelQuotaStatus, isModelQuotaAvailable, hasModelQuotaConfig } from './model-quota.js';
-import { providerOfBase, basePoolForBase } from './pool-index.js';
+import { providerOfBase, basePoolForBase, modelPoolsForRef } from './pool-index.js';
 import { decryptSecret } from './crypto-storage.js';
 // lib/ops-status.js — status + health operational routes (#312 split from routes-ops.js).
 import { json } from './http-bridge.js';
@@ -93,6 +93,7 @@ ctx.effect(() => ctx.webServer.register({
         }
         const until = pool.state.failedUntil?.get(ref);
         const modelQuota = getModelQuotaStatus(pool, ref, now);
+        const activeModelPools = runtime?.index ? modelPoolsForRef(runtime.index, ref) : [];
         keys.push({
           ref,
           present,
@@ -126,6 +127,8 @@ ctx.effect(() => ctx.webServer.register({
         providerName: pool.provider ?? providerOfBase(pool.base),
         basePool: basePool?.base ?? null,
         model: pool.model ?? null,
+        pinnedRef: pool.pinnedRef ?? null,
+        labels: pool.labels ?? {},
         quotasConfigured: hasModelQuotaConfig(pool),
         keys,
         tags: providerTags?.get?.(pool.base) ?? [],

package/lib/ops-telemetry.js

@@ -13,6 +13,7 @@ import {
 import {
   USAGE_PATH,
   SNAPSHOT_PATH,
+  DIAG_PATH,
 } from './ops-paths.js';
 import { findSecrets } from './keycheck.js';
 import { mutateSettings, sectionOps } from './settings-write.js';
@@ -21,6 +22,24 @@ import { mutateSettings, sectionOps } from './settings-write.js';
  * @param {object} ctx cordis context
  * @param {object} deps live dependencies from apply()
  */
+
+const DIAG_BUFFER_LIMIT = 200;
+const diagBuffer = [];
+
+export function pushDiag(entry) {
+  if (diagBuffer.length >= DIAG_BUFFER_LIMIT) {
+    diagBuffer.shift();
+  }
+  diagBuffer.push({
+    timestamp: Date.now(),
+    ...entry,
+  });
+}
+
+export function getDiagBuffer() {
+  return diagBuffer.slice();
+}
+
 export function registerTelemetryRoutes(ctx, deps) {
   const {
     buildRuntime,
@@ -111,4 +130,34 @@ ctx.effect(() => ctx.webServer.register({
   },
 }), 'dsh-key-rotation: snapshot route');
 
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: DIAG_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: diag is local-only' } });
+      return;
+    }
+    if (req.method === 'POST') {
+      let body;
+      try { body = await readJson(req); } catch (e) {
+        json(res, 400, { error: { code: 'bad-request', message: String(e?.message ?? e) } });
+        return;
+      }
+      pushDiag({
+        level: typeof body?.level === 'string' ? body.level : 'info',
+        message: typeof body?.message === 'string' ? body.message.slice(0, 500) : 'unknown',
+        details: body?.details ?? null,
+      });
+      json(res, 200, { ok: true, count: diagBuffer.length });
+      return;
+    }
+    json(res, 200, { diag: getDiagBuffer() });
+  },
+}), 'dsh-key-rotation: diag route');
+
 }

package/lib/pool-builder.js

@@ -33,6 +33,9 @@ export function buildPoolItem({
   model = null,
   quotas = null,
   quotaResetWindow = null,
+  labels = null,
+  pinnedRef = null,
+  useKeyRef = null,
 }) {
   const seen = new Set();
   const indexed = (Array.isArray(keys) ? keys : []).map((key, index) => ({ ref: typeof key === 'string' ? key.trim() : '', index }))
@@ -84,6 +87,21 @@ export function buildPoolItem({
   for (let i = 0; i < refs.length; i++) {
     weightsMap[refs[i]] = typeof w[i] === 'number' && w[i] > 0 ? Math.floor(w[i]) : 1;
   }
+  const labelsMap = {};
+  if (Array.isArray(labels)) {
+    for (let i = 0; i < refs.length; i++) {
+      const lbl = labels[indexed[i].index];
+      if (typeof lbl === 'string' && lbl.trim()) labelsMap[refs[i]] = lbl.trim();
+    }
+  } else if (labels && typeof labels === 'object') {
+    for (let i = 0; i < refs.length; i++) {
+      const lbl = labels[refs[i]];
+      if (typeof lbl === 'string' && lbl.trim()) labelsMap[refs[i]] = lbl.trim();
+    }
+  }
+  const cleanPinned = typeof pinnedRef === 'string' && pinnedRef.trim()
+    ? pinnedRef.trim()
+    : (typeof useKeyRef === 'string' && useKeyRef.trim() ? useKeyRef.trim() : null);
   const normalizedQuotas = normalizeModelQuotas(quotas);
   return {
     base,
@@ -107,6 +125,8 @@ export function buildPoolItem({
     concurrencyLimit: typeof concurrencyLimit === 'number' && Number.isFinite(concurrencyLimit) && concurrencyLimit > 0 ? Math.floor(concurrencyLimit) : 0,
     routingStrategy: poolStrategy,
     proactiveRateLimitGuard: poolGuard,
+    labels: labelsMap,
+    pinnedRef: cleanPinned,
   };
 }
 
@@ -145,6 +165,8 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
     const pool = buildPool(p.provider, p.keys, p.weights, p.paused, p.revoked, poolCooldown, poolMax, p.expiresAt, p.routingStrategy, p.proactiveRateLimitGuard, {
       provider: p.provider,
       model: null,
+      labels: p.labels,
+      pinnedRef: p.pinnedRef ?? p.useKeyRef,
     }, provRpm, provTpm, provConcurrency);
     if (pool) {
       for (const ref of pool.refs) {
@@ -171,6 +193,8 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
         provider: p.provider,
         model,
         quotas: mp.quotas,
+        labels: mp.labels ?? p.labels,
+        pinnedRef: mp.pinnedRef ?? mp.useKeyRef ?? p.pinnedRef ?? p.useKeyRef,
       }, modelRpm, modelTpm, modelConcurrency);
       if (!mpool) continue;
       mpool.basePool = pool;

package/lib/pool.js

@@ -90,6 +90,10 @@ export const SOFT_FAILURE_CODES = new Set([
 ]);
 
 /** True if failure code or message represents a soft/transient drop. */
+export function isSoftFailureCode(code) {
+  if (!code) return false;
+  return SOFT_FAILURE_CODES.has(String(code).toUpperCase());
+}
 
 /** Ref name validator. Same rule lib/index.js enforces in PUT/DELETE /key. */
 const REF_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -432,6 +436,25 @@ export function sortAttemptList(refs, strategy = 'round-robin', deps = {}) {
  * Unified check whether an error or payload represents a switchable failure.
  * Prioritizes explicit HTTP status codes and gRPC codes before text matching.
  */
+/** Raw socket-level codes the taxonomy maps to TRANSPORT (see classifyFailure). */
+const SOCKET_TRANSPORT_CODES = new Set([
+  'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EPIPE', 'EAI_AGAIN', 'ENOTFOUND',
+  'ECONNABORTED', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET', 'UND_ERR_HEADERS_TIMEOUT',
+]);
+
+/**
+ * Codes isSwitchableError/classifyFailure recognize. Once a failure
+ * carries one of these, the operator's switchCodes verdict is final and the
+ * message-regex fallback must not run (it would resurrect excluded codes).
+ */
+const RECOGNIZED_SWITCH_CODES = new Set([
+  'QUOTA', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT', 'EMPTY_RESPONSE',
+  'UNKNOWN_MODEL', 'AUTH', 'RESOURCE_EXHAUSTED', 'UNAVAILABLE', 'INTERNAL',
+  'DEADLINE_EXCEEDED', 'UNAUTHENTICATED', 'PERMISSION_DENIED', 'ABORTED',
+  'LOCAL_POOL_EXHAUSTED', 'LOCAL_MODEL_QUOTA_EXHAUSTED', 'CIRCUIT_OPEN',
+  '429', '401', '403', '408', '425', '500', '502', '503', '504',
+]);
+
 export function isSwitchableError(failureOrPayload, switchCodes = new Set(DEFAULT_SWITCH_CODES)) {
   if (!failureOrPayload) return false;
   // Runtime switch codes arrive as an array (cfg.switchCodes is a schema array,
@@ -439,7 +462,8 @@ export function isSwitchableError(failureOrPayload, switchCodes = new Set(DEFAUL
   if (!(switchCodes instanceof Set)) switchCodes = new Set(Array.isArray(switchCodes) ? switchCodes : DEFAULT_SWITCH_CODES);
   const failure = failureOrPayload.failure ?? failureOrPayload;
   const status = Number(failure.status ?? failure.statusCode ?? failure.httpStatus ?? 0);
-  const code = String(failure.code ?? failure.reason ?? '').toUpperCase();
+  let code = String(failure.code ?? failure.reason ?? '').toUpperCase();
+  if (code && SOCKET_TRANSPORT_CODES.has(code)) code = 'TRANSPORT';
   const message = String(failure.message ?? failureOrPayload.message ?? '');
 
   // 1. Direct HTTP status codes (#267: also 408/425 transient)
@@ -456,7 +480,11 @@ export function isSwitchableError(failureOrPayload, switchCodes = new Set(DEFAUL
   // 3. Named switch code matching
   if (code && switchCodes.has(code)) return true;
 
-  // 4. Fallback text pattern matching
+  // 4. Fallback text pattern matching — switchCodes is the operator's
+  // explicit contract for which failures rotate keys. Once the failure has a
+  // recognized code, that decision is final: message sniffing must not
+  // resurrect codes the operator deliberately excluded (e.g. TIMEOUT).
+  if (code && RECOGNIZED_SWITCH_CODES.has(code)) return false;
   return SWITCHABLE_MESSAGE_PATTERN.test(message);
 }
 

package/lib/resolver.js

@@ -125,7 +125,16 @@ export function createResolver({
     // original credential must never be used as a bypass. Decided once, before
     // the loop, so it cannot be re-evaluated mid-iteration.
     const quotaManaged = hasModelQuotaConfig(pool) && isQuotaManagedRequest(runtime.index, ref, requested);
-    const start = strategy === 'round-robin' ? (pool.state.pointer ?? 0) : 0;
+    let start = strategy === 'round-robin' ? (pool.state.pointer ?? 0) : 0;
+    if (pool.pinnedRef && list.includes(pool.pinnedRef)) {
+      const pIdx = list.indexOf(pool.pinnedRef);
+      if (pIdx > 0) {
+        list = list.slice();
+        list.splice(pIdx, 1);
+        list.unshift(pool.pinnedRef);
+      }
+      start = 0;
+    }
 
     for (let i = 0; i < list.length; i++) {
       const index = (start + i) % list.length;

package/lib/rotate.js

@@ -16,7 +16,7 @@ import {
   sortAttemptList,
 } from './pool.js';
 import { pickCascadeFallback, CASCADE_MAX_DEPTH } from './cascade.js';
-import { nextQuotaReset } from './quota-window.js';
+import { nextQuotaReset, poolResetAt } from './quota-window.js';
 import { tpmRecord } from './bucket.js';
 import {
   isModelQuotaAvailable,
@@ -89,6 +89,13 @@ export function createRotate(deps) {
       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));
+      if (pool.pinnedRef && attemptList.includes(pool.pinnedRef)) {
+        const pIdx = attemptList.indexOf(pool.pinnedRef);
+        if (pIdx > 0) {
+          attemptList.splice(pIdx, 1);
+          attemptList.unshift(pool.pinnedRef);
+        }
+      }
       if (quotaManaged) {
         attemptList = attemptList.filter((ref) => isModelQuotaAvailable(pool, ref, wallNow));
         if (attemptList.length === 0) {
@@ -163,7 +170,7 @@ export function createRotate(deps) {
           /\b(?:insufficient[_\s-]+quota|quota(?:\s+is)?\s+(?:exhausted|exceeded)|exceeded\s+(?:your\s+)?(?:current\s+)?quota)\b/i.test(errMsg);
         const qWindow = pool.quotaResetWindow ?? runtime0.quotaResetWindow;
         if (isQuota && qWindow) {
-          const quotaResetAt = nextQuotaReset(qWindow, now());
+          const quotaResetAt = poolResetAt(pool, qWindow, now());
           if (quotaResetAt && quotaResetAt > now()) {
             if (!pool.state.quotaWindows) pool.state.quotaWindows = new Map();
             pool.state.quotaWindows.set(targetRef, quotaResetAt);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.50",
+  "version": "0.8.52",
   "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": [
@@ -57,7 +57,7 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2 || >=0.2.0-rc.1 <0.2.1-0",
     "@deepseek-ai/schemastery": "^3.18.4"
   },
   "scripts": {