@goodandready/dsh-key-rotation 0.8.11 → 0.8.13

package/lib/ops-telemetry.js

@@ -0,0 +1,113 @@
+// lib/ops-telemetry.js — usage + snapshot operational routes (#312 split from routes-ops.js).
+import {
+  json,
+  readJson,
+  descriptorOf,
+  NS,
+} from './http-bridge.js';
+import { isTrustedBridgeRequest } from './pool.js';
+import {
+  usageRows,
+  usageCsv,
+} from './usage-report.js';
+import {
+  USAGE_PATH,
+  SNAPSHOT_PATH,
+} from './ops-paths.js';
+import { findSecrets } from './keycheck.js';
+
+/**
+ * @param {object} ctx cordis context
+ * @param {object} deps live dependencies from apply()
+ */
+export function registerTelemetryRoutes(ctx, deps) {
+  const {
+    buildRuntime,
+  } = deps;
+
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: USAGE_PATH,
+  handler: (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: usage is local-only' } }); return; }
+    const url = new URL(req.url ?? USAGE_PATH, 'http://localhost');
+    const days = Math.min(90, Math.max(1, Number(url.searchParams.get('days')) || 7));
+    const csv = url.searchParams.get('format') === 'csv';
+    const provider = url.searchParams.get('provider') ?? '';
+    const runtime = buildRuntime();
+    const now = Date.now();
+    const seen = new Set();
+    const report = [];
+    for (const pool of runtime.poolByRef.values()) {
+      if (seen.has(pool.base)) continue;
+      seen.add(pool.base);
+      if (provider && pool.base !== provider) continue;
+      report.push({ provider: pool.base, rows: usageRows(pool, days, now) });
+    }
+    if (csv) {
+      res.writeHead(200, { 'content-type': 'text/csv; charset=utf-8', 'content-disposition': 'attachment; filename="dsh-key-rotation-usage.csv"' });
+      const parts = [];
+      for (const p of report) {
+        if (parts.length > 0) parts.push('');
+        parts.push('# ' + p.provider);
+        parts.push(usageCsv(p.rows));
+      }
+      res.end(parts.join('\n') + '\n');
+      return;
+    }
+    json(res, 200, { at: now, days, providers: report });
+  },
+}), 'dsh-key-rotation: usage route');
+
+// #218: full config snapshot - one JSON file to move between machines.
+// Secret values never travel: only credential/env names. Token fields are
+// exported as empty strings; on import they keep existing values when empty.
+
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: SNAPSHOT_PATH,
+  handler: async (req, res) => {
+    if (req.method !== 'GET' && req.method !== 'POST') { json(res, 405, { error: { code: 'method', message: 'GET (export) or POST (import) only' } }); return; }
+    if (!isTrustedBridgeRequest(req)) { json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: snapshot is local-only' } }); return; }
+    if (req.method === 'GET') {
+      const descriptor = descriptorOf(ctx, NS);
+      const value = descriptor?.value ?? {};
+      const exportable = { ...value };
+      // token-shaped fields stay empty in the file; refs are names, not secrets
+      exportable.webhookActionToken = '';
+      json(res, 200, { at: Date.now(), version: 1, snapshot: exportable });
+      return;
+    }
+    // POST = import: { snapshot } -> merge with current section, PUT semantics
+    let body;
+    try { body = await readJson(req); } catch (e) { json(res, 400, { error: { code: 'bad-request', message: String(e?.message ?? e) } }); return; }
+    const snap = body?.snapshot;
+    if (!snap || typeof snap !== 'object' || Array.isArray(snap)) { json(res, 400, { error: { code: 'bad-format', message: 'dsh-key-rotation: POST requires {"snapshot": {...}}' } }); return; }
+    // #200 leak guard applies to imported content too
+    try {
+      const masked = structuredClone(snap);
+      if (masked.webhookActionToken) masked.webhookActionToken = '***';
+      if (masked.notifyWebhook) masked.notifyWebhook = '***';
+      const findings = findSecrets(JSON.stringify(masked));
+      if (findings.length > 0) { json(res, 400, { error: { code: 'secret-in-snapshot', message: 'dsh-key-rotation: snapshot carries a live-looking credential', findings } }); return; }
+    } catch { /* scanning must never block a valid import */ }
+    const settings = ctx.get('settings');
+    if (!settings) { json(res, 503, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: no settings provider' } }); return; }
+    const desc = descriptorOf(ctx, NS);
+    if (desc === void 0) { json(res, 500, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: namespace missing' } }); return; }
+    const cur = desc.value ?? {};
+    // empty token fields in the file keep the current values (never wipe a secret)
+    const merged = { ...cur, ...snap };
+    if (!snap.webhookActionToken) merged.webhookActionToken = cur.webhookActionToken ?? '';
+    try {
+      await settings.replace(NS, merged, desc.revision);
+      const after = descriptorOf(ctx, NS);
+      json(res, 200, { ok: true, revision: after?.revision });
+    } catch (e) {
+      json(res, e?.code === 'SETTINGS_CONFLICT' ? 409 : 400, { error: { code: 'settings-rejected', message: String(e?.message ?? e) } });
+    }
+  },
+}), 'dsh-key-rotation: snapshot route');
+
+}

package/lib/ops-test.js

@@ -0,0 +1,106 @@
+// lib/ops-test.js — sandbox test + sandbox cache routes (#312 split from routes-ops.js).
+import {
+  json,
+  readJson,
+} from './http-bridge.js';
+import {
+  isTrustedBridgeRequest,
+  isValidRef,
+  keyTail,
+  envValue,
+} from './pool.js';
+import { bestEffort } from './best-effort.js';
+import {
+  TEST_PATH,
+  SANDBOX_CACHE_PATH,
+} from './ops-paths.js';
+
+/**
+ * @param {object} ctx cordis context
+ * @param {object} deps live dependencies from apply()
+ */
+export function registerTestRoutes(ctx, deps) {
+  const {
+    lastTestCache,
+    ensureSandboxRunner,
+    poolState,
+  } = deps;
+
+// ── test route: dry-run a single key without rotation ──
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: TEST_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: test is local-only' } }); return; }
+    let body; try { body = await readJson(req); } catch (e) { json(res, 400, { error: { code: 'bad-request', message: String(e?.message ?? e) } }); return; }
+    const ref = typeof body?.ref === 'string' ? body.ref.trim() : '';
+    if (!isValidRef(ref)) { json(res, 400, { error: { code: 'bad-ref', message: 'dsh-key-rotation: ref must be an environment variable name' } }); return; }
+    // Optional value for pre-save validation (issue #118)
+    const testValue = typeof body?.value === 'string' && body.value.length > 0 ? body.value : undefined;
+    const probe = body?.probe === 'models' || body?.probe === 'chat' ? body.probe : undefined;
+    const base = ctx.get('credentials');
+    try {
+      let hit = await (base?.__dshKeyRotationOriginalResolve ?? base?.resolve)?.call(base, ref);
+      let present = Boolean(hit && typeof hit.value === 'string' && hit.value.length > 0);
+      const effectiveValue = testValue || hit?.value;
+      const valid = present ? Boolean(effectiveValue && typeof effectiveValue === 'string' && effectiveValue.length > 0) : Boolean(testValue);
+      const tail = valid ? keyTail(effectiveValue) : '';
+      let source = null;
+      await bestEffort('credentials.describe', async () => { const d = await base?.describe?.(ref); source = d?.source ?? null; }, ctx.logger);
+      if (!present && !testValue) { json(res, 200, { ok: false, ref, code: 'no-credential', message: 'no such credential' }); return; }
+      if (!present && testValue) { source = 'pre-save'; }
+      else if (!present) {
+        const ev = envValue(ref);
+        if (ev !== undefined) { present = true; json(res, 200, { ok: true, ref, tail: keyTail(ev), source: 'env' }); return; }
+      }
+      // sandbox probe (models is free; chat is hook-only, see sandbox.js)
+      if (probe) {
+        const keyForProbe = effectiveValue;
+        const runner = ensureSandboxRunner(ctx);
+        const result = probe === 'chat' ? await runner.probeChat(ref, keyForProbe) : await runner.probeModels(ref, keyForProbe);
+        const cached = { ...result, at: Date.now() };
+        lastTestCache.set(ref, cached);
+        if (cached.ok) {
+          for (const st of poolState.values()) {
+            if (st.failedUntil?.has(ref) || st.failCounts?.has(ref) || st.brokenUntil?.has(ref)) {
+              st.failedUntil?.delete(ref);
+              st.failCounts?.delete(ref);
+              st.authFailCounts?.delete(ref);
+              st.brokenUntil?.delete(ref);
+            }
+          }
+        }
+        json(res, 200, { ok: cached.ok, ref, tail, source, probe, code: cached.code, latencyMs: cached.latencyMs, modelsCount: cached.modelsCount });
+        return;
+      }
+      json(res, 200, { ok: true, ref, tail, source });
+    } catch (e) {
+      json(res, 200, { ok: false, ref, code: 'error', message: String(e?.message ?? e) });
+    }
+  },
+}), 'dsh-key-rotation: test route');
+
+// Intercept the llm/stream waterfall: rotate any request whose provider maps
+// to a configured key pool; pass everything else (and internal dispatches)
+// straight through.
+// Read-only cache snapshot for clients (badge polling).
+
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: SANDBOX_CACHE_PATH,
+  handler: (req, res) => {
+    if (!isTrustedBridgeRequest(req)) { json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: cache is local-only' } }); return; }
+    const cacheSnap = typeof lastTestCache?.snapshot === 'function'
+      ? lastTestCache.snapshot()
+      : (lastTestCache instanceof Map ? Object.fromEntries(lastTestCache) : (lastTestCache ?? {}));
+    json(res, 200, cacheSnap);
+  },
+}), 'dsh-key-rotation: sandbox cache');
+
+
+
+// #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).
+}

package/lib/ops-webhook.js

@@ -0,0 +1,115 @@
+// lib/ops-webhook.js — webhook interactive action route (#312 split from routes-ops.js).
+import {
+  json,
+  readJson,
+} from './http-bridge.js';
+import { WEBHOOK_ACTION_PATH } from './ops-paths.js';
+
+/**
+ * @param {object} ctx cordis context
+ * @param {object} deps live dependencies from apply()
+ */
+export function registerWebhookActionRoute(ctx, deps) {
+  const {
+    buildRuntime,
+    poolState,
+    setRotationDisabled,
+    circuitBreaker,
+  } = deps;
+
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: WEBHOOK_ACTION_PATH,
+  handler: async (req, res) => {
+    if (req.method !== 'POST') { json(res, 405, { error: { code: 'method', message: 'POST only' } }); return; }
+    const runtime = buildRuntime();
+    const expected = runtime.webhookActionToken;
+    if (!expected) { json(res, 503, { error: { code: 'no-token', message: 'dsh-key-rotation: webhookActionToken is not configured' } }); return; }
+    const auth = String(req.headers.authorization ?? '');
+    if (auth !== `Bearer ${expected}`) { json(res, 401, { error: { code: 'unauthorized', message: 'dsh-key-rotation: bad webhook action token' } }); return; }
+    let body;
+    try { body = await readJson(req); } catch (e) { json(res, 400, { error: { code: 'bad-request', message: String(e?.message ?? e) } }); return; }
+    // Accept callback payloads from formatInteractive (Telegram/Discord/Slack) or plain {action}
+    let action = typeof body?.action === 'string' ? body.action : '';
+    if (!action && typeof body?.data === 'string') {
+      try { action = String(JSON.parse(body.data)?.id ?? ''); } catch { action = ''; }
+    }
+    if (!action && typeof body?.callback_data === 'string') {
+      try { action = String(JSON.parse(body.callback_data)?.id ?? ''); } catch { action = ''; }
+    }
+    // #222: Telegram update envelope {update_id, callback_query:{data}}
+    if (!action && typeof body?.callback_query?.data === 'string') {
+      try { action = String(JSON.parse(body.callback_query.data)?.id ?? ''); } catch { action = ''; }
+    }
+    // #222: Telegram setWebhook registration helper
+    if (typeof body?.setWebhook === 'object' && body.setWebhook) {
+      const botToken = typeof body.setWebhook.botToken === 'string' ? body.setWebhook.botToken : '';
+      if (!botToken) { json(res, 400, { error: { code: 'bad-request', message: 'dsh-key-rotation: setWebhook.botToken required' } }); return; }
+      // derive the public URL from request headers; explicit URL wins
+      const url = typeof body.setWebhook.url === 'string' && body.setWebhook.url ? body.setWebhook.url : `https://${String(req.headers.host ?? '')}/dsh-key-rotation/webhook-action`;
+      try {
+        const hookRes = await fetch(`https://api.telegram.org/bot${botToken}/setWebhook`, {
+          method: 'POST', headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ url, allowed_updates: ['callback_query'] }),
+        });
+        const hookData = await hookRes.json().catch(() => ({}));
+        json(res, 200, { ok: hookRes.ok, url, telegram: hookData });
+      } catch (e) {
+        json(res, 502, { error: { code: 'telegram-failed', message: String(e?.message ?? e) } });
+      }
+      return;
+    }
+    if (!action) { json(res, 400, { error: { code: 'bad-action', message: 'dsh-key-rotation: no action in payload' } }); return; }
+    const provider = action.startsWith('pause-') || action.startsWith('reset-') ? action.replace(/^(pause|reset)-/, '') : '';
+    try {
+      if (action === 'disable-rotation') {
+        setRotationDisabled(true);
+        (ctx?.logger ? ctx.logger('dsh-key-rotation') : null)?.warn?.('[dsh-key-rotation] rotation DISABLED via webhook action');
+        json(res, 200, { ok: true, action });
+        return;
+      }
+      if (action === 'enable-rotation') {
+        setRotationDisabled(false);
+        json(res, 200, { ok: true, action });
+        return;
+      }
+      if (action.startsWith('pause-') || action.startsWith('reset-')) {
+        const st = poolState.get(provider);
+        if (!st) { json(res, 404, { error: { code: 'not-found', message: `dsh-key-rotation: no pool for '${provider}'` } }); return; }
+        if (action.startsWith('pause-')) {
+          const until = Date.now() + 3600000; // 1h pause
+          for (const ref of (st.failedUntil ? [...st.failedUntil.keys()] : [])) st.failedUntil.set(ref, Math.max(st.failedUntil.get(ref) ?? 0, until));
+          // also pause every key currently healthy
+          for (const p of buildRuntime().poolByRef.values()) {
+            if (p.base !== provider) continue;
+            for (const ref of p.refs) st.failedUntil.set(ref, Math.max(st.failedUntil.get(ref) ?? 0, until));
+          }
+          (ctx?.logger ? ctx.logger('dsh-key-rotation') : null)?.warn?.(`[dsh-key-rotation] pool ${provider} PAUSED 1h via webhook action`);
+          json(res, 200, { ok: true, action, provider, until: Date.now() + 3600000 });
+          return;
+        }
+        const cleared = st.failedUntil.size;
+        st.failedUntil.clear();
+        st.failCounts?.clear();
+        st.authFailCounts?.clear();
+        st.brokenUntil?.clear();
+        st.switches = 0;
+        st.lastReason = undefined;
+        st.lastSwitchAt = undefined;
+        let circuitReset = false;
+        const br = circuitBreaker ?? buildRuntime().breaker;
+        if (br) {
+          if (typeof br.reset === 'function') { br.reset(provider); circuitReset = true; }
+          else if (typeof br.onSuccess === 'function') { br.onSuccess(provider); circuitReset = true; }
+        }
+        (ctx?.logger ? ctx.logger('dsh-key-rotation') : null)?.warn?.(`[dsh-key-rotation] pool ${provider} RESET via webhook action (circuitReset=${circuitReset})`);
+        json(res, 200, { ok: true, action, provider, cleared, circuitReset });
+        return;
+      }
+      json(res, 400, { error: { code: 'unknown-action', message: `dsh-key-rotation: unknown action '${action}'` } });
+    } catch (e) {
+      json(res, 500, { error: { code: 'action-failed', message: String(e?.message ?? e) } });
+    }
+  },
+}), 'dsh-key-rotation: webhook-action');
+}

package/lib/pool-builder.js

@@ -0,0 +1,86 @@
+// lib/pool-builder.js — provider & per-model pool assembly and cleanup
+import { bucketSweep } from './bucket.js';
+
+export function parseExpiry(v) {
+  if (typeof v === 'number' && Number.isFinite(v) && v > 0) return v;
+  if (typeof v === 'string' && v.length > 0) {
+    const t = Date.parse(v);
+    if (!Number.isNaN(t)) return t;
+  }
+  return undefined;
+}
+
+export function buildPoolItem({
+  base,
+  keys,
+  weights,
+  poolCooldown,
+  poolMax,
+  expiresAt,
+  poolStrategy,
+  poolGuard,
+  rpmLimit,
+  makeState,
+}) {
+  const refs = (keys ?? []).filter((ref) => typeof ref === 'string' && ref.length > 0);
+  if (refs.length === 0) return null;
+  const w = Array.isArray(weights) ? weights : [];
+  const weightedRefs = [];
+  for (let i = 0; i < refs.length; i++) {
+    const ww = typeof w[i] === 'number' && w[i] > 0 ? Math.floor(w[i]) : 1;
+    for (let k = 0; k < ww; k++) weightedRefs.push(refs[i]);
+  }
+  const parsedExpiry = {};
+  if (Array.isArray(expiresAt)) {
+    for (let i = 0; i < refs.length; i++) {
+      const exp = parseExpiry(expiresAt[i]);
+      if (exp !== undefined) parsedExpiry[refs[i]] = exp;
+    }
+  }
+  return {
+    base,
+    refs,
+    weights: refs.map((_, i) => (typeof w[i] === 'number' && w[i] > 0 ? Math.floor(w[i]) : 1)),
+    weightedRefs: weightedRefs.length > 0 ? weightedRefs : refs,
+    state: makeState(base),
+    cooldownMs: poolCooldown,
+    maxCooldownMs: poolMax,
+    expiresAt: parsedExpiry,
+    rpmLimit,
+    routingStrategy: poolStrategy,
+    proactiveRateLimitGuard: poolGuard,
+  };
+}
+
+export function cleanupRemovedProviders({
+  cfg,
+  poolState,
+  poolByRef,
+  providerToPool,
+  expectedClones,
+  moduleBreaker,
+  lowHealthNotifiedAt,
+  budgetNotifiedAt,
+}) {
+  // auto-cleanup: remove poolState for providers that are now empty or removed
+  for (const key of [...poolState.keys()]) {
+    if (![...poolByRef.values()].some((p) => p.base === key)) {
+      poolState.delete(key);
+      lowHealthNotifiedAt?.delete?.(key);
+      budgetNotifiedAt?.delete?.(key + ':budget');
+    }
+  }
+  // #192: drop RPM windows for refs that no longer belong to any pool
+  for (const st of poolState.values()) {
+    if (st.rpmWindows) bucketSweep(st.rpmWindows, new Set(poolByRef.keys()));
+  }
+  // drop breaker entries for removed providers
+  if (moduleBreaker) {
+    for (const key of Object.keys(moduleBreaker.snapshot())) {
+      if (![...providerToPool.keys()].includes(key) && !expectedClones.has(key)) {
+        const still = (cfg.providers ?? []).some((p) => p.provider === key);
+        if (!still) moduleBreaker.reset(key);
+      }
+    }
+  }
+}

package/lib/rotate.js

@@ -33,9 +33,12 @@ export function createRotate(deps) {
     setRotateStartMs,
     quotaStore,
     circuitBreaker,
+    logger,
     now = nowMono,
   } = deps;
 
+  const logWarn = (msg) => (logger?.warn ? logger.warn(msg) : null);
+
   function rotate(options, pool) {
     return (async function* () {
       const runtime0 = buildRuntime();
@@ -93,7 +96,7 @@ export function createRotate(deps) {
 
       // #260: fail fast when provider circuit is open
       if (circuitBreaker && !circuitBreaker.canRequest(options.provider)) {
-        console.warn(`[dsh-key-rotation] ${options.provider}: circuit open — skipping dispatch`);
+        logWarn(`[dsh-key-rotation] ${options.provider}: circuit open — skipping dispatch`);
         yield finishError('CIRCUIT_OPEN', `[dsh-key-rotation] provider '${options.provider}' circuit is open`);
         return;
       }
@@ -116,7 +119,7 @@ export function createRotate(deps) {
           penalizeRef(curRef, e?.code ?? 'TRANSPORT', String(e?.message ?? ''));
           lastFailure = finishError(e?.code ?? 'TRANSPORT',
             `dsh-key-rotation: dispatch failed: ${String(e?.message ?? e)}`);
-          console.warn(`[dsh-key-rotation] ${options.provider}: key ${String(curRef ?? '?')} threw ${String(e?.code ?? e?.message ?? e)}`);
+          logWarn(`[dsh-key-rotation] ${options.provider}: key ${String(curRef ?? '?')} threw ${String(e?.code ?? e?.message ?? e)}`);
           continue;
         }
 
@@ -146,7 +149,7 @@ export function createRotate(deps) {
                   pool.state.lastReason = String(code ?? 'UNKNOWN');
                   pool.state.lastSwitchAt = now();
                   lastFailure = chunk;
-                  console.warn(`[dsh-key-rotation] ${options.provider}: key ${String(activeRef ?? '?')} failed (${String(code)} ${String(message).slice(0, 100)}) - next key`);
+                  logWarn(`[dsh-key-rotation] ${options.provider}: key ${String(activeRef ?? '?')} failed (${String(code)} ${String(message).slice(0, 100)}) - next key`);
                   // #216: per-switch webhook (opt-in switchNotify), deduped per provider
                   if (switchNotify && activeRef) {
                     notifySwitch(runtime0, pool, {
@@ -206,7 +209,7 @@ export function createRotate(deps) {
                     const effCool = Math.min(cool, maxCool ?? cool);
                     recordFailure(pool, activeRef, now(), effCool, maxCool);
                     pushEvent(pool, activeRef, 'RATE_LIMIT', effCool);
-                    console.warn(`[dsh-key-rotation] ${options.provider}: key ${activeRef} proactive pause (remaining ${String(rate.remaining ?? '?')}/${String(rate.limit ?? '?')}, cool ${Math.round(effCool / 1000)}s) — next request will rotate`);
+                    logWarn(`[dsh-key-rotation] ${options.provider}: key ${activeRef} proactive pause (remaining ${String(rate.remaining ?? '?')}/${String(rate.limit ?? '?')}, cool ${Math.round(effCool / 1000)}s) — next request will rotate`);
                   }
                 }
                 // #7: persist quota snapshot regardless of threshold (so dashboard widget can show it).
@@ -229,7 +232,7 @@ export function createRotate(deps) {
               pool.state.lastReason = String(e?.code ?? 'TRANSPORT');
               pool.state.lastSwitchAt = now();
               lastFailure = finishError(e?.code ?? 'TRANSPORT', String(e?.message ?? e));
-              console.warn(`[dsh-key-rotation] ${options.provider}: key ${String(activeRef ?? '?')} stream threw ${String(e?.code ?? e?.message ?? e)} - failover to next key`);
+              logWarn(`[dsh-key-rotation] ${options.provider}: key ${String(activeRef ?? '?')} stream threw ${String(e?.code ?? e?.message ?? e)} - failover to next key`);
               if (switchNotify && activeRef) {
                 notifySwitch(runtime0, pool, {
                   provider: options.provider,
@@ -256,7 +259,7 @@ export function createRotate(deps) {
       // pool exhausted — all keys cooling or missing
       pool.state.lastExhaustionAt = now();
       pool.state.exhaustionCount = (pool.state.exhaustionCount ?? 0) + 1;
-      console.warn(`[dsh-key-rotation] ${options.provider}: pool exhausted — all ${pool.refs.length} keys cooling`);
+      logWarn(`[dsh-key-rotation] ${options.provider}: pool exhausted — all ${pool.refs.length} keys cooling`);
       const runtime = buildRuntime();
       // notify via extracted helper (see notifyExhaustion above)
       notifyExhaustion(runtime, pool, { provider: options.provider });
@@ -266,7 +269,7 @@ export function createRotate(deps) {
         const pools = runtime.providerToPool;
         const fb = pickCascadeFallback(options.provider, runtime, pools);
         if (fb && fb.pool && fb.pool !== pool) {
-          console.warn(`[dsh-key-rotation] ${options.provider}: pool exhausted — cascading to ${fb.provider}`);
+          logWarn(`[dsh-key-rotation] ${options.provider}: pool exhausted — cascading to ${fb.provider}`);
           pool.state.lastReason = 'CASCADE';
           pool.state.lastSwitchAt = now();
           // Re-dispatch on the fallback pool (depth-1 via __isCascade guard)