@goodandready/dsh-key-rotation 0.8.5 → 0.8.7

package/lib/circuit-breaker.js

@@ -90,4 +90,22 @@ export class CircuitBreaker {
     if (provider) this._st.delete(provider);
     else this._st.clear();
   }
-}
+
+  /** Restore entries from a persistence snapshot (#287). */
+  restore(snapshot) {
+    if (!snapshot || typeof snapshot !== 'object') return 0;
+    let n = 0;
+    for (const [provider, e] of Object.entries(snapshot)) {
+      if (!e || typeof e !== 'object') continue;
+      const state = e.state === BREAKER_OPEN || e.state === BREAKER_HALF_OPEN ? e.state : BREAKER_CLOSED;
+      this._st.set(provider, {
+        state,
+        fails: Number.isFinite(e.fails) ? e.fails : 0,
+        openedAt: Number.isFinite(e.openedAt) ? e.openedAt : 0,
+        probes: 0,
+      });
+      n += 1;
+    }
+    return n;
+  }
+}

package/lib/client.js

@@ -116,6 +116,31 @@ window.__ModuleLoader__.load({
       undoProvider: 'Provider removed',
       undoKey: 'Key removed',
       undo: 'Undo',
+      // #289 a11y / #290 states / #291 bulk / #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',
+      retry: 'Retry',
+      unavailableTitle: 'Settings bridge unavailable',
+      unavailableDesc: 'The host did not expose the dsh-key-rotation settings namespace. Reopen Settings or check the plugin is enabled.',
+      modalClose: 'Close dialog',
+      dialogLabel: 'Confirmation',
+      loadChartAria: 'Key traffic distribution',
+      bulkCooldownPlaceholder: 'Bulk cooldown (ms)',
+      bulkApply: 'Apply to selected',
+      bulkRemove: 'Remove selected',
+      confirmBulkRemoveTitle: 'Remove {n} provider(s)?',
+      confirmBulkRemoveDesc: 'Selected providers and all their keys will be removed from rotation. You can undo once immediately after.',
+      selectProvider: 'Select provider {p}',
+      activeBadge: 'active',
+      healthScoreTitle: 'health score',
+      totalRequestsTitle: 'total requests',
+      exportProvider: 'Export this provider',
+      recentFailures: 'Recent failures ({n})',
+      noActivePools: 'No active pools',
+      headerPoolsTitle: 'Key rotation pools',
+      pausedBudget: 'paused',
+      sortUsage: 'Sort by usage',
     };
 
     // Коды, на которых имеет смысл переключать ключ. Список из хоста
@@ -409,6 +434,12 @@ window.__ModuleLoader__.load({
         getScopeSnapshot
       );
       const [state, setState] = React.useState({ status: 'loading', value: null, revision: 0, error: '', providers: [] });
+      // #290: surface settingsScope availability as card state
+      React.useEffect(() => {
+        if (!settingsScope) {
+          setState((s) => (s.status === 'unavailable' ? s : { ...s, status: 'unavailable' }));
+        }
+      }, [settingsScope]);
       const [draft, setDraft] = React.useState(null);
       // ── all hooks live ABOVE any early return (React error 310 otherwise) ──
       const [search, setSearch] = React.useState('');
@@ -419,6 +450,46 @@ window.__ModuleLoader__.load({
       const [bulkCooldown, setBulkCooldown] = React.useState('');
       const [undo, setUndo] = React.useState(null);
       const undoTimer = React.useRef(null);
+      // #289 a11y: confirm dialog focus trap / Escape / restore (hooks above returns)
+      const modalReturnFocusRef = React.useRef(null);
+      const modalCardRef = React.useRef(null);
+      React.useEffect(() => {
+        if (!confirmModal) return undefined;
+        modalReturnFocusRef.current = typeof document !== 'undefined' ? document.activeElement : null;
+        const onKey = (e) => {
+          if (e.key === 'Escape') {
+            e.stopPropagation();
+            setConfirmModal(null);
+            return;
+          }
+          if (e.key !== 'Tab' || !modalCardRef.current) return;
+          const focusables = modalCardRef.current.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
+          if (!focusables.length) return;
+          const first = focusables[0];
+          const last = focusables[focusables.length - 1];
+          if (e.shiftKey && document.activeElement === first) {
+            e.preventDefault();
+            last.focus();
+          } else if (!e.shiftKey && document.activeElement === last) {
+            e.preventDefault();
+            first.focus();
+          }
+        };
+        document.addEventListener('keydown', onKey, true);
+        const id = requestAnimationFrame(() => {
+          if (!modalCardRef.current) return;
+          const cancelBtn = modalCardRef.current.querySelector('[data-krot-modal-cancel]');
+          (cancelBtn || modalCardRef.current.querySelector('button'))?.focus();
+        });
+        return () => {
+          document.removeEventListener('keydown', onKey, true);
+          cancelAnimationFrame(id);
+          const prev = modalReturnFocusRef.current;
+          if (prev && typeof prev.focus === 'function') {
+            try { prev.focus(); } catch (_) {}
+          }
+        };
+      }, [confirmModal]);
       const [testing, setTesting] = React.useState('');
       const [testResult, setTestResult] = React.useState({});
       const [testAllProvider, setTestAllProvider] = React.useState('');
@@ -586,8 +657,31 @@ window.__ModuleLoader__.load({
           })
           .catch((e) => setSecretError(t('keyWriteFailed').replace('{msg}', String(e?.message ?? e))));
       };
-      if (state.status === 'loading' || !val) {
-        return React.createElement('p', { style: { color: 'var(--dsw-alias-label-tertiary)', fontSize: 13 } }, t('loading'));
+      // #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')),
+          React.createElement('div', {
+            className: 'krot-skeleton',
+            'aria-hidden': 'true',
+            style: {
+              height: 10, borderRadius: 999, background: 'linear-gradient(90deg, var(--dsw-alias-bg-layer-2), var(--dsw-alias-bg-layer-3), var(--dsw-alias-bg-layer-2))',
+              backgroundSize: '200% 100%', animation: 'krot-shimmer 1.2s ease-in-out infinite', maxWidth: 280,
+            },
+          })
+        );
+      }
+      if (state.status === 'error') {
+        return React.createElement('div', { className: 'krot-state-block', role: 'alert', style: { padding: '12px 0', display: 'flex', flexDirection: 'column', gap: '10px', alignItems: 'flex-start' } },
+          React.createElement('p', { className: 'krot-err', style: { margin: 0 } }, t('errorTitle') + (state.error ? (': ' + state.error) : '')),
+          React.createElement('button', { type: 'button', className: 'krot-btn', onClick: () => load() }, t('retry'))
+        );
+      }
+      if (state.status === 'unavailable' || !settingsScope) {
+        return React.createElement('div', { className: 'krot-state-block', role: 'status', style: { padding: '12px 0', display: 'flex', flexDirection: 'column', gap: '6px' } },
+          React.createElement('p', { style: { fontSize: 14, fontWeight: 600, color: 'var(--dsw-alias-label-primary)', margin: 0 } }, t('unavailableTitle')),
+          React.createElement('p', { className: 'krot-hint', style: { margin: 0 } }, t('unavailableDesc'))
+        );
       }
 
       const providers = state.providers;
@@ -914,7 +1008,7 @@ window.__ModuleLoader__.load({
               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);
-              if (worst >= 1 && providerStatus.pauseOnBudget) parts.push('· paused');
+              if (worst >= 1 && providerStatus.pauseOnBudget) parts.push('· ' + t('pausedBudget'));
               return h('p', { className: 'krot-hint', style: { color } }, t('budgetLabel') + ' ' + parts.join(' · '));
             })()
           : null;
@@ -956,6 +1050,8 @@ window.__ModuleLoader__.load({
           return h('div', { className: 'krot-load-chart' },
             h('div', { className: 'krot-load-header' },
               h('span', { style: { fontWeight: 600 } }, '📊 ' + t('loadDistribution')),
+              h('span', { className: 'krot-sr-only', style: { position: 'absolute', width: 1, height: 1, padding: 0, margin: -1, overflow: 'hidden', clip: 'rect(0,0,0,0)', border: 0 } },
+                t('loadChartAria') + ': ' + (total > 0 ? keyUsages.map((x) => t('keyLabel').replace('{n}', String(x.index + 1)) + ' ' + x.usage).join(', ') : t('noTrafficYet'))),
               h('span', null, total > 0 ? (total + ' ' + t('statRequests')) : t('noTrafficYet'))
             ),
             h('div', { className: 'krot-load-bar' },
@@ -988,13 +1084,18 @@ window.__ModuleLoader__.load({
 
         return h('div', { key: pIndex, className: 'krot-prov' },
           h('div', { className: 'krot-prov-head' },
-            h('input', { type: 'checkbox', checked: selected.has(entry.provider), onChange: (e) => { const ns = new Set(selected); if (e.target.checked) ns.add(entry.provider); else ns.delete(entry.provider); setSelected(ns); } }),
+            h('input', {
+              type: 'checkbox',
+              'aria-label': t('selectProvider').replace('{p}', entry.provider),
+              checked: selected.has(entry.provider),
+              onChange: (e) => { const ns = new Set(selected); if (e.target.checked) ns.add(entry.provider); else ns.delete(entry.provider); setSelected(ns); },
+            }),
             btn(t('exportOne'), () => {
               const data = JSON.stringify([entry], null, 2);
               const blob = new Blob([data], { type: 'application/json' });
               const url = URL.createObjectURL(blob);
               const a = document.createElement('a'); a.href = url; a.download = entry.provider + '.json'; a.click(); URL.revokeObjectURL(url);
-            }, { title: 'Export this provider' }),
+            }, { title: t('exportProvider') }),
             btn('⇅', () => {
               const ps = status[entry.provider];
               if (!ps || !Array.isArray(ps.keys)) return;
@@ -1006,16 +1107,16 @@ window.__ModuleLoader__.load({
                 next[pIndex] = { ...next[pIndex], keys: sorted };
                 return { ...cur, providers: next };
               });
-            }, { title: 'Sort by usage' }),
+            }, { title: t('sortUsage') }),
             h('select', { className: 'krot-in', value: entry.provider, onChange: (e) => setProvider(pIndex, e.target.value) }, options),
             (() => {
               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)';
-              return h('span', { className: 'krot-tail', title: 'health score', style: { flex: 'none', color, fontWeight: 700 } }, String(score));
+              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: 'total requests', style: { flex: 'none' } }, String(tot)) : null; })(),
+            (() => { 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; })(),
             btn('✕', () => setConfirmModal({
               title: t('confirmRemoveProvTitle').replace('{p}', entry.provider),
               desc: t('confirmRemoveProvDesc'),
@@ -1036,7 +1137,7 @@ window.__ModuleLoader__.load({
             (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('details', { style: { fontSize: '11px', marginTop: '6px' } }, h('summary', null, 'Recent failures ('+providerStatus.events.length+')'), h('ul', { style: { margin: '4px 0 0', paddingLeft: '16px' } }, providerStatus.events.slice().reverse().map((ev, i) => h('li', { key: i, style: ev.type === 'probe' ? { opacity: .5 } : null }, new Date(ev.at).toLocaleTimeString() + ' ' + (ev.type === 'probe' ? '[probe] ' : '') + ev.ref + ' ' + ev.reason + ' cd=' + ev.cooldownMs)) )) : null),
+            (providerStatus && Array.isArray(providerStatus.events) && providerStatus.events.length > 0 ? h('details', { style: { fontSize: '11px', marginTop: '6px' } }, h('summary', null, t('recentFailures').replace('{n}', String(providerStatus.events.length))), h('ul', { style: { margin: '4px 0 0', paddingLeft: '16px' } }, providerStatus.events.slice().reverse().map((ev, i) => h('li', { key: i, style: ev.type === 'probe' ? { opacity: .5 } : null }, new Date(ev.at).toLocaleTimeString() + ' ' + (ev.type === 'probe' ? '[probe] ' : '') + ev.ref + ' ' + ev.reason + ' cd=' + ev.cooldownMs)) )) : null),
             btn(t('resetCooldown'), () => setConfirmModal({
               title: t('confirmResetTitle').replace('{p}', entry.provider),
               desc: t('confirmResetDesc'),
@@ -1051,7 +1152,11 @@ window.__ModuleLoader__.load({
       });
 
       const noProviders = providers.length === 0
-        ? h('p', { className: 'krot-err' }, t('noProviders'))
+        ? h('div', { className: 'krot-empty', role: 'status', style: { display: 'flex', flexDirection: 'column', gap: '6px', padding: '16px 14px', border: '1px dashed var(--dsw-alias-border-l2)', borderRadius: 10, background: 'var(--dsw-alias-bg-layer-2)' } },
+            h('p', { style: { margin: 0, fontWeight: 600, fontSize: 14, color: 'var(--dsw-alias-label-primary)' } }, t('emptyTitle')),
+            h('p', { className: 'krot-hint', style: { margin: 0 } }, t('emptyDesc')),
+            h('p', { className: 'krot-hint', style: { margin: 0 } }, t('noProviders')),
+          )
         : null;
 
       const allConfiguredProviders = Array.isArray(val?.providers) ? val.providers : [];
@@ -1102,19 +1207,36 @@ window.__ModuleLoader__.load({
         h('div', { className: 'krot-foot', style: { marginBottom: '8px' } },
           h('input', {
             className: 'krot-in',
-            placeholder: 'Bulk cooldown ms',
+            placeholder: t('bulkCooldownPlaceholder'),
             value: bulkCooldown,
             onChange: (e) => setBulkCooldown(e.target.value),
             style: { maxWidth: '160px' },
           }),
-          btn('Apply to selected', () => {
+          btn(t('bulkApply'), () => {
             const v = Number(bulkCooldown); if (!v) return;
             setField((cur) => {
               const next = [...(cur.providers ?? [])];
               for (let i = 0; i < next.length; i++) if (selected.has(next[i].provider)) next[i] = { ...next[i], cooldownMs: v };
               return { ...cur, providers: next };
             });
-          }, { disabled: selected.size === 0 || !bulkCooldown })
+          }, { disabled: selected.size === 0 || !bulkCooldown }),
+          btn(t('bulkRemove'), () => {
+            const ids = [...selected];
+            if (!ids.length) return;
+            setConfirmModal({
+              title: t('confirmBulkRemoveTitle').replace('{n}', String(ids.length)),
+              desc: t('confirmBulkRemoveDesc'),
+              actionLabel: t('bulkRemove'),
+              danger: true,
+              onConfirm: () => {
+                setField((cur) => {
+                  const next = (cur.providers ?? []).filter((p) => !ids.has(p.provider));
+                  return { ...cur, providers: next };
+                });
+                setSelected(new Set());
+              },
+            });
+          }, { disabled: selected.size === 0, className: 'krot-btn-danger' })
         ),
         h('div', { className: 'krot-keys' }, providerRows),
         h('div', { className: 'krot-foot', style: { marginTop: '10px' } },
@@ -1126,7 +1248,7 @@ window.__ModuleLoader__.load({
       const failoverSection = h('div', { className: 'krot-section-card' },
         h('div', { className: 'krot-section-title' },
           h('span', null, '⚡ ' + t('codesTitle')),
-          h('span', { className: 'krot-badge krot-badge-warn' }, selectedCodes.size + ' active')
+          h('span', { className: 'krot-badge krot-badge-warn' }, selectedCodes.size + ' ' + t('activeBadge'))
         ),
         h('div', { className: 'krot-section-desc' }, t('sectionFailoverDesc')),
         h('div', { className: 'krot-codes' }, codeList.map((code) => h('label', { key: code, className: 'krot-code' },
@@ -1211,12 +1333,23 @@ window.__ModuleLoader__.load({
         ) : null,
       ].filter(Boolean);
 
-      const confirmModalEl = confirmModal ? h('div', { className: 'krot-modal-backdrop', onClick: () => setConfirmModal(null) },
-        h('div', { className: 'krot-modal-card', onClick: (e) => e.stopPropagation() },
-          h('div', { className: 'krot-modal-title' }, confirmModal.title),
-          h('div', { className: 'krot-modal-desc' }, confirmModal.desc),
+      const confirmModalEl = confirmModal ? h('div', {
+          className: 'krot-modal-backdrop',
+          onClick: () => setConfirmModal(null),
+        },
+        h('div', {
+          className: 'krot-modal-card',
+          ref: modalCardRef,
+          role: 'dialog',
+          'aria-modal': 'true',
+          'aria-labelledby': 'krot-modal-title',
+          'aria-describedby': 'krot-modal-desc',
+          onClick: (e) => e.stopPropagation(),
+        },
+          h('div', { className: 'krot-modal-title', id: 'krot-modal-title' }, confirmModal.title),
+          h('div', { className: 'krot-modal-desc', id: 'krot-modal-desc' }, confirmModal.desc),
           h('div', { className: 'krot-modal-actions' },
-            btn(t('cancel'), () => setConfirmModal(null)),
+            btn(t('cancel'), () => setConfirmModal(null), { 'data-krot-modal-cancel': '1' }),
             btn(confirmModal.actionLabel || t('confirm'), () => {
               const fn = confirmModal.onConfirm;
               setConfirmModal(null);
@@ -1301,7 +1434,7 @@ window.__ModuleLoader__.load({
           h('span', { style: { fontSize: '9px', opacity: 0.6 } }, open ? '▲' : '▼')
         ),
         open ? h('div', { className: 'krot-popover' },
-          h('div', { className: 'krot-pop-title' }, 'Key rotation pools'),
+          h('div', { className: 'krot-pop-title' }, t('headerPoolsTitle')),
           !poolEntries.length ? h('div', { style: { fontSize: '12px', color: 'var(--dsw-alias-label-tertiary)' } }, 'No active pools') : 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)');

package/lib/index.js

@@ -49,6 +49,8 @@ import { BoundedMap } from './bounded-map.js';
 import { classifyFailure } from './error-taxonomy.js';
 import { safeParseJson } from './atomic-io.js';
 import { registerOpsRoutes } from './routes-ops.js';
+import { StatePersistence, resolveStatePath } from './persistence.js';
+import path from 'node:path';
 
 /** The llm-pi-ai namespace whose provider profiles map providers to pools. */
 const PIAI_NS = 'llm-pi-ai';
@@ -113,6 +115,9 @@ let moduleBreaker = null;
 let moduleNotifyQueue = null;
 // Global config accessor safe against early initialization
 let getConfig = () => null;
+function verboseLoggingOn() {
+  try { return Boolean(getConfig()?.verboseLogging); } catch (_) { return false; }
+}
 let getRuntime = () => null;
 let sandboxRunner = null;
 const webhookSender = new WebhookSender({ fetchImpl: globalThis.fetch });
@@ -204,6 +209,9 @@ export const Config = Schema.object({
   circuitBreakerThreshold: Schema.number().default(5),
   circuitBreakerOpenMs: Schema.number().default(30000),
   circuitBreakerHalfOpenProbes: Schema.number().default(1),
+  // #287 persistence across restarts
+  persistenceEnabled: Schema.boolean().default(true),
+  persistencePath: Schema.string().default(''),
   switchNotifyThrottleMs: Schema.number().default(60000),
   warnBelowHealthy: Schema.number().default(0),
   latencySloMs: Schema.number().default(0),
@@ -278,6 +286,77 @@ export function apply(ctx, config = {}) {
   // ── key-pool state, persisted across config reloads ──
   // base provider -> { failedUntil: Map<ref, epochMs>, pointer: number, lastUsed: ref }
   const poolState = new Map();
+
+  // #287: persist cooldowns / circuit / quota across DSH reloads.
+  // Path resolution: explicit config -> host data dir -> DSH_HOME -> cwd.
+  // Disabled (with a single warn) when no writable directory can be found.
+  let statePersistence = null;
+  try {
+    const cfg0 = getConfig() ?? config ?? {};
+    // Cordis ctx properties require inject; bare getters throw.
+    // Use only host env/cwd so apply() never trips the injector.
+    const hostDirs = [
+      process.env.DSH_HOME,
+      process.cwd(),
+    ].filter((d) => typeof d === 'string' && d.length > 0);
+    const resolvedPath = resolveStatePath({
+      configuredPath: cfg0.persistencePath,
+      dataDir: hostDirs[0],
+    });
+    if (cfg0.persistenceEnabled !== false && resolvedPath) {
+      statePersistence = new StatePersistence({ filePath: resolvedPath });
+      statePersistence.load().then((snap) => {
+        if (!snap) return;
+        try {
+          StatePersistence.restorePools(poolState, snap);
+          if (moduleBreaker && snap.circuit) moduleBreaker.restore(snap.circuit);
+          if (verboseLoggingOn()) {
+            console.warn(`[dsh-key-rotation] restored ${Object.keys(snap.pools ?? {}).length} pool state(s) from ${path.basename(resolvedPath)}`);
+          }
+        } catch (e) {
+          console.warn('[dsh-key-rotation] persistence restore failed', e?.message ?? e);
+        }
+      }).catch(() => {});
+    } else if (cfg0.persistenceEnabled !== false && !resolvedPath) {
+      console.warn('[dsh-key-rotation] persistence disabled: no data directory');
+    }
+  } catch (e) {
+    console.warn('[dsh-key-rotation] persistence init failed', e?.message ?? e);
+  }
+
+  function persistenceSnapshot() {
+    if (!statePersistence) return null;
+    return StatePersistence.serialize({
+      poolState,
+      circuitSnapshot: moduleBreaker ? moduleBreaker.snapshot() : {},
+      quotaSnapshot: {},
+    });
+  }
+
+  function schedulePersist() {
+    if (!statePersistence) return;
+    const snap = persistenceSnapshot();
+    if (snap) statePersistence.save(snap);
+  }
+
+  ctx.effect(() => {
+    const timer = setInterval(() => { try { schedulePersist(); } catch (_) {} }, 15000);
+    if (typeof timer.unref === 'function') timer.unref();
+    return () => {
+      clearInterval(timer);
+      try {
+        if (statePersistence) {
+          const snap = persistenceSnapshot();
+          if (snap) {
+            statePersistence.save(snap);
+            // best-effort flush; dispose clears the debounce timer
+            void statePersistence.flush();
+          }
+          statePersistence.dispose();
+        }
+      } catch (_) {}
+    };
+  }, 'dsh-key-rotation: state persistence');
   // Periodic sweep of expired cooldowns — keeps health probe cheap and avoids waiting for next user request
   ctx.effect(() => {
     const id = setInterval(() => {
@@ -786,6 +865,7 @@ export function apply(ctx, config = {}) {
     if (ref) {
       const backoff = recordFailure(pool, ref, Date.now(), pool.cooldownMs ?? 60000, undefined, cls.soft, true);
       pushEvent(pool, ref, code || 'UNKNOWN', backoff);
+      schedulePersist();
       pool.state.switches = (pool.state.switches ?? 0) + 1;
       pool.state.lastReason = code || 'UNKNOWN';
       pool.state.lastSwitchAt = Date.now();

package/lib/persistence.js

@@ -0,0 +1,146 @@
+// lib/persistence.js — atomic snapshot of rotation state across restarts (#287).
+// Cooldowns, circuit-breaker entries and quota counters live in memory; a DSH
+// reload would otherwise forget cooldowns and stampede recovered keys.
+
+import path from 'node:path';
+import { atomicWriteJson, safeReadJson } from './atomic-io.js';
+
+const DEFAULT_FILE = 'dsh-key-rotation-state.json';
+const SAVE_DEBOUNCE_MS = 400;
+
+/**
+ * @param {{ filePath: string, now?: () => number }} opts
+ */
+export class StatePersistence {
+  constructor({ filePath, now = Date.now } = {}) {
+    if (!filePath || typeof filePath !== 'string') {
+      throw new Error('StatePersistence: filePath is required');
+    }
+    this.filePath = filePath;
+    this._now = now;
+    this._timer = null;
+    this._dirty = false;
+    this._lastWrite = 0;
+  }
+
+  /** Build a plain snapshot from live maps/objects. */
+  static serialize({ poolState, circuitSnapshot, quotaSnapshot }) {
+    const pools = {};
+    if (poolState && typeof poolState.forEach === 'function') {
+      poolState.forEach((st, base) => {
+        const failedUntil = {};
+        if (st && st.failedUntil && typeof st.failedUntil.forEach === 'function') {
+          st.failedUntil.forEach((until, ref) => {
+            if (Number.isFinite(until)) failedUntil[ref] = until;
+          });
+        }
+        pools[base] = {
+          failedUntil,
+          pointer: Number.isFinite(st?.pointer) ? st.pointer : 0,
+          lastUsed: typeof st?.lastUsed === 'string' ? st.lastUsed : null,
+        };
+      });
+    }
+    return {
+      version: 1,
+      savedAt: Date.now(),
+      pools,
+      circuit: circuitSnapshot && typeof circuitSnapshot === 'object' ? circuitSnapshot : {},
+      quota: quotaSnapshot && typeof quotaSnapshot === 'object' ? quotaSnapshot : {},
+    };
+  }
+
+  _nowSafe() {
+    const n = Number(this._now?.() ?? Date.now());
+    return Number.isFinite(n) ? n : Date.now();
+  }
+
+  /**
+   * Schedule a debounced atomic write. Never throws to the caller.
+   * @param {object} payload result of StatePersistence.serialize
+   */
+  save(payload) {
+    this._pending = payload;
+    this._dirty = true;
+    if (this._timer) return;
+    this._timer = setTimeout(() => {
+      this._timer = null;
+      void this.flush();
+    }, SAVE_DEBOUNCE_MS);
+    if (typeof this._timer.unref === 'function') this._timer.unref();
+  }
+
+  async flush() {
+    if (!this._dirty || !this._pending) return false;
+    const payload = this._pending;
+    this._dirty = false;
+    this._pending = null;
+    try {
+      await atomicWriteJson(this.filePath, payload);
+      this._lastWrite = this._nowSafe();
+      return true;
+    } catch {
+      // Keep previous good file; mark dirty so a later save retries.
+      this._dirty = true;
+      this._pending = this._pending || payload;
+      return false;
+    }
+  }
+
+  /**
+   * Load a snapshot. Corrupt/missing file → null (never wipes memory).
+   * @returns {Promise<object|null>}
+   */
+  async load() {
+    const raw = await safeReadJson(this.filePath, null);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+    if (raw.version !== 1) return null;
+    return raw;
+  }
+
+  /** Restore poolState Map from a loaded snapshot. */
+  static restorePools(poolState, snapshot) {
+    if (!poolState || !snapshot || !snapshot.pools || typeof snapshot.pools !== 'object') return 0;
+    let n = 0;
+    for (const [base, st] of Object.entries(snapshot.pools)) {
+      if (!st || typeof st !== 'object') continue;
+      const failedUntil = new Map();
+      if (st.failedUntil && typeof st.failedUntil === 'object') {
+        for (const [ref, until] of Object.entries(st.failedUntil)) {
+          if (Number.isFinite(until)) failedUntil.set(ref, until);
+        }
+      }
+      poolState.set(base, {
+        failedUntil,
+        pointer: Number.isFinite(st.pointer) ? st.pointer : 0,
+        lastUsed: typeof st.lastUsed === 'string' ? st.lastUsed : undefined,
+      });
+      n += 1;
+    }
+    return n;
+  }
+
+  dispose() {
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+  }
+}
+
+/**
+ * Resolve the on-disk state path. Prefer an explicit config path; otherwise
+ * place the file under `dataDir` when the host provides one. Returns null when
+ * persistence cannot be enabled safely (no writable data directory).
+ */
+export function resolveStatePath({ dataDir, configuredPath } = {}) {
+  if (configuredPath && typeof configuredPath === 'string' && configuredPath.trim()) {
+    return configuredPath.trim();
+  }
+  if (dataDir && typeof dataDir === 'string' && dataDir.trim()) {
+    return path.join(dataDir.trim(), DEFAULT_FILE);
+  }
+  return null;
+}
+
+export default StatePersistence;

package/lib/routes-ops.js

@@ -22,6 +22,7 @@ import { usageRows, usageCsv } from './usage-report.js';
 import { findSecrets, looksLikeApiSecret } from './keycheck.js';
 import { nextQuotaReset } from './quota-window.js';
 import { classifyFailure } from './error-taxonomy.js';
+import { sanitizeSnapshot } from './sanitize-snapshot.js';
 
 const STATUS_PATH = '/dsh-key-rotation/status';
 const SNAPSHOT_PATH = '/dsh-key-rotation/snapshot';
@@ -166,7 +167,7 @@ export function registerOpsRoutes(ctx, deps) {
           providers.push({ provider: pool.base, keys: [], statusError: String(e?.message ?? e) });
         }
       }
-      json(res, 200, {
+      json(res, 200, sanitizeSnapshot({
         providers,
         // #266/#263 operational extras (additive)
         meta: {
@@ -175,7 +176,7 @@ export function registerOpsRoutes(ctx, deps) {
           breakerEnabled: runtime.circuitBreakerEnabled !== false,
           at: now,
         },
-      });
+      }, now));
     },
   }), 'dsh-key-rotation: status route');
 

package/lib/sanitize-snapshot.js

@@ -0,0 +1,83 @@
+// lib/sanitize-snapshot.js — clamp/repair runtime snapshots before they leave the host (#288).
+// Guards the settings card and ops APIs against NaN, negative remaining times,
+// and inconsistent counters after clock jumps or empty-pool edge cases.
+
+function toFiniteNumber(value, fallback = 0) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function clampNonNegative(value) {
+  const n = toFiniteNumber(value, 0);
+  return n < 0 ? 0 : n;
+}
+
+function clampRemaining(value, nowMs) {
+  const n = toFiniteNumber(value, 0);
+  if (n <= 0) return 0;
+  // If the absolute timestamp is in the past relative to now, remaining is 0.
+  if (n > 1e12 && n <= nowMs) return 0;
+  // Cooldown remaining should not exceed ~7 days.
+  if (n < 1e12 && n > 7 * 86400000) return 7 * 86400000;
+  return n;
+}
+
+/**
+ * Sanitize a per-key status entry.
+ * @param {object} key
+ * @param {number} now
+ */
+export function sanitizeKeyStatus(key, now = Date.now()) {
+  if (!key || typeof key !== 'object') return null;
+  return {
+    ...key,
+    present: Boolean(key.present),
+    active: Boolean(key.active),
+    cooldownMsLeft: clampRemaining(key.cooldownMsLeft, now),
+    usage: clampNonNegative(key.usage),
+    failures: clampNonNegative(key.failures),
+    weight: clampNonNegative(key.weight || 1) || 1,
+    rpm: key.rpm && typeof key.rpm === 'object'
+      ? {
+          ...key.rpm,
+          used: clampNonNegative(key.rpm.used),
+          remaining: clampNonNegative(key.rpm.remaining),
+          limit: clampNonNegative(key.rpm.limit),
+        }
+      : key.rpm,
+  };
+}
+
+/**
+ * Sanitize a full status snapshot ({ providers: [...], ... }).
+ * Never mutates the input.
+ */
+export function sanitizeSnapshot(snapshot, now = Date.now()) {
+  if (!snapshot || typeof snapshot !== 'object') return { providers: [] };
+  const providers = Array.isArray(snapshot.providers) ? snapshot.providers : [];
+  return {
+    ...snapshot,
+    providers: providers.map((p) => {
+      if (!p || typeof p !== 'object') return p;
+      const keys = Array.isArray(p.keys) ? p.keys : [];
+      return {
+        ...p,
+        switches: clampNonNegative(p.switches),
+        totalUsage: p.totalUsage == null ? p.totalUsage : clampNonNegative(p.totalUsage),
+        healthScore: p.healthScore == null
+          ? p.healthScore
+          : Math.max(0, Math.min(100, toFiniteNumber(p.healthScore, 0))),
+        lastSwitchAt: p.lastSwitchAt == null ? null : (Number.isFinite(Number(p.lastSwitchAt)) ? Number(p.lastSwitchAt) : null),
+        lastExhaustionAt: p.lastExhaustionAt == null ? null : (Number.isFinite(Number(p.lastExhaustionAt)) ? Number(p.lastExhaustionAt) : null),
+        todayCost: p.todayCost == null ? p.todayCost : clampNonNegative(p.todayCost),
+        weeklyCost: p.weeklyCost == null ? p.weeklyCost : clampNonNegative(p.weeklyCost),
+        budgetDaily: p.budgetDaily == null ? p.budgetDaily : clampNonNegative(p.budgetDaily),
+        budgetWeekly: p.budgetWeekly == null ? p.budgetWeekly : clampNonNegative(p.budgetWeekly),
+        p95: p.p95 == null ? null : clampNonNegative(p.p95),
+        keys: keys.map((k) => sanitizeKeyStatus(k, now)).filter(Boolean),
+      };
+    }),
+  };
+}
+
+export default sanitizeSnapshot;

package/package.json

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