@goodandready/dsh-key-rotation 0.7.26 → 0.7.28

package/lib/canary.js

@@ -1,56 +1,56 @@
-// canary.js — canary probing before releasing a key from cooldown (issue #196).
-
-export const CANARY_PROBE_TIMEOUT_MS = 5000;
-export const CANARY_DEFAULT_INTERVAL_MS = 30 * 1000;
-
-export class CanaryProber {
-  constructor(opts) {
-    opts = opts || {};
-    if (!opts.sandboxRunner) throw new Error('canary: sandboxRunner required');
-    this._runner = opts.sandboxRunner;
-    this._intervalMs = opts.intervalMs || CANARY_DEFAULT_INTERVAL_MS;
-    this._results = new Map();
-    this._inProgress = new Set();
-  }
-
-  get intervalMs() { return this._intervalMs; }
-
-  async probe(ref, key) {
-    if (!ref || this._inProgress.has(ref)) return null;
-    this._inProgress.add(ref);
-    try {
-      const result = await this._runner.probeModels(ref, key);
-      this._results.set(ref, Object.assign({}, result, { at: Date.now() }));
-      return result;
-    } catch (e) {
-      return { ok: false, code: 'error', at: Date.now() };
-    } finally {
-      this._inProgress.delete(ref);
-    }
-  }
-
-  lastResult(ref) {
-    return this._results.get(ref) || null;
-  }
-
-  isHealthy(ref) {
-    const r = this._results.get(ref);
-    return Boolean(r && r.ok);
-  }
-
-  clear(ref) {
-    if (ref) {
-      this._results.delete(ref);
-      this._inProgress.delete(ref);
-    } else {
-      this._results.clear();
-      this._inProgress.clear();
-    }
-  }
-
-  snapshot() {
-    const out = {};
-    for (const [k, v] of this._results) out[k] = v;
-    return out;
-  }
-}
+// canary.js — canary probing before releasing a key from cooldown (issue #196).
+
+export const CANARY_PROBE_TIMEOUT_MS = 5000;
+export const CANARY_DEFAULT_INTERVAL_MS = 30 * 1000;
+
+export class CanaryProber {
+  constructor(opts) {
+    opts = opts || {};
+    if (!opts.sandboxRunner) throw new Error('canary: sandboxRunner required');
+    this._runner = opts.sandboxRunner;
+    this._intervalMs = opts.intervalMs || CANARY_DEFAULT_INTERVAL_MS;
+    this._results = new Map();
+    this._inProgress = new Set();
+  }
+
+  get intervalMs() { return this._intervalMs; }
+
+  async probe(ref, key) {
+    if (!ref || this._inProgress.has(ref)) return null;
+    this._inProgress.add(ref);
+    try {
+      const result = await this._runner.probeModels(ref, key);
+      this._results.set(ref, Object.assign({}, result, { at: Date.now() }));
+      return result;
+    } catch (e) {
+      return { ok: false, code: 'error', at: Date.now() };
+    } finally {
+      this._inProgress.delete(ref);
+    }
+  }
+
+  lastResult(ref) {
+    return this._results.get(ref) || null;
+  }
+
+  isHealthy(ref) {
+    const r = this._results.get(ref);
+    return Boolean(r && r.ok);
+  }
+
+  clear(ref) {
+    if (ref) {
+      this._results.delete(ref);
+      this._inProgress.delete(ref);
+    } else {
+      this._results.clear();
+      this._inProgress.clear();
+    }
+  }
+
+  snapshot() {
+    const out = {};
+    for (const [k, v] of this._results) out[k] = v;
+    return out;
+  }
+}

package/lib/cascade.js

@@ -1,39 +1,39 @@
-// cascade.js — cross-provider failover cascade (issue #194).
-// ponytail: minimal — pick fallback provider from a RegionMap-like config.
-
-export const CASCADE_MAX_DEPTH = 1;
-
-export function pickCascadeFallback(provider, cfg, pools) {
-  const list = Array.isArray(cfg && cfg.cascade) ? cfg.cascade : [];
-  for (const entry of list) {
-    const fb = typeof entry === 'string' ? { provider: entry } : entry;
-    if (!fb || !fb.provider || fb.provider === provider) continue;
-    const pool = pools instanceof Map ? pools.get(fb.provider) : (pools ? pools[fb.provider] : null);
-    if (!pool) continue;
-    const now = Date.now();
-    let healthy = 0;
-    for (const ref of pool.refs) {
-      const failedUntil = (pool.state && pool.state.failedUntil && pool.state.failedUntil.get(ref)) || 0;
-      if (failedUntil > now) continue;
-      const exp = pool.expiresAt ? pool.expiresAt[ref] : undefined;
-      if (exp !== undefined && now >= exp) continue;
-      healthy += 1;
-    }
-    if (healthy === 0) continue;
-    return { provider: fb.provider, pool, model: fb.model || null };
-  }
-  return null;
-}
-
-export function hasHealthyKey(pool, now) {
-  now = now || Date.now();
-  if (!pool || !Array.isArray(pool.refs)) return false;
-  for (const ref of pool.refs) {
-    const failedUntil = (pool.state && pool.state.failedUntil && pool.state.failedUntil.get(ref)) || 0;
-    if (failedUntil > now) continue;
-    const exp = pool.expiresAt ? pool.expiresAt[ref] : undefined;
-    if (exp !== undefined && now >= exp) continue;
-    return true;
-  }
-  return false;
-}
+// cascade.js — cross-provider failover cascade (issue #194).
+// ponytail: minimal — pick fallback provider from a RegionMap-like config.
+
+export const CASCADE_MAX_DEPTH = 1;
+
+export function pickCascadeFallback(provider, cfg, pools) {
+  const list = Array.isArray(cfg && cfg.cascade) ? cfg.cascade : [];
+  for (const entry of list) {
+    const fb = typeof entry === 'string' ? { provider: entry } : entry;
+    if (!fb || !fb.provider || fb.provider === provider) continue;
+    const pool = pools instanceof Map ? pools.get(fb.provider) : (pools ? pools[fb.provider] : null);
+    if (!pool) continue;
+    const now = Date.now();
+    let healthy = 0;
+    for (const ref of pool.refs) {
+      const failedUntil = (pool.state && pool.state.failedUntil && pool.state.failedUntil.get(ref)) || 0;
+      if (failedUntil > now) continue;
+      const exp = pool.expiresAt ? pool.expiresAt[ref] : undefined;
+      if (exp !== undefined && now >= exp) continue;
+      healthy += 1;
+    }
+    if (healthy === 0) continue;
+    return { provider: fb.provider, pool, model: fb.model || null };
+  }
+  return null;
+}
+
+export function hasHealthyKey(pool, now) {
+  now = now || Date.now();
+  if (!pool || !Array.isArray(pool.refs)) return false;
+  for (const ref of pool.refs) {
+    const failedUntil = (pool.state && pool.state.failedUntil && pool.state.failedUntil.get(ref)) || 0;
+    if (failedUntil > now) continue;
+    const exp = pool.expiresAt ? pool.expiresAt[ref] : undefined;
+    if (exp !== undefined && now >= exp) continue;
+    return true;
+  }
+  return false;
+}

package/lib/client-helpers.js

@@ -1,21 +1,21 @@
-export function formatAgo(t, at) {
-  if (!at) return '';
-  const sec = Math.max(0, Math.round((Date.now() - at) / 1000));
-  if (sec < 60) return t('justNow');
-  if (sec < 3600) return t('minutesAgo').replace('{n}', String(Math.round(sec / 60)));
-  return t('hoursAgo').replace('{n}', String(Math.round(sec / 3600)));
-}
-
-export function nextKeyRef(providerId, existingKeys, allRefs) {
-  const fromExisting = (existingKeys || []).find((k) => typeof k === 'string' && k.length > 0);
-  const base = fromExisting
-    ? fromExisting.replace(/_\d+$/, '')
-    : String(providerId || 'provider').toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '') + '_API_KEY';
-  const taken = new Set(allRefs);
-  if (!taken.has(base)) return base;
-  for (let n = 2; n < 1000; n++) {
-    const candidate = base + '_' + n;
-    if (!taken.has(candidate)) return candidate;
-  }
-  return base + '_' + Date.now();
-}
+export function formatAgo(t, at) {
+  if (!at) return '';
+  const sec = Math.max(0, Math.round((Date.now() - at) / 1000));
+  if (sec < 60) return t('justNow');
+  if (sec < 3600) return t('minutesAgo').replace('{n}', String(Math.round(sec / 60)));
+  return t('hoursAgo').replace('{n}', String(Math.round(sec / 3600)));
+}
+
+export function nextKeyRef(providerId, existingKeys, allRefs) {
+  const fromExisting = (existingKeys || []).find((k) => typeof k === 'string' && k.length > 0);
+  const base = fromExisting
+    ? fromExisting.replace(/_\d+$/, '')
+    : String(providerId || 'provider').toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '') + '_API_KEY';
+  const taken = new Set(allRefs);
+  if (!taken.has(base)) return base;
+  for (let n = 2; n < 1000; n++) {
+    const candidate = base + '_' + n;
+    if (!taken.has(candidate)) return candidate;
+  }
+  return base + '_' + Date.now();
+}

package/lib/client.js

@@ -63,6 +63,10 @@ window.__ModuleLoader__.load({
       keySaved: 'saved',
       keyFromEnv: 'from the environment, read-only here',
       keyWriteFailed: 'could not store the key: {msg}',
+      notSecretShape: 'saved, but the value does not look like an API key - check for a typo',
+      rpmTitle: 'requests/min: {u} used, {r} remaining',
+      budgetLabel: 'budget:',
+      exportCsv: 'Export CSV',
       keyHint: 'The value is stored in DSH credentials and never sent back to the browser — only its last 5 characters are shown. Names are generated for you; hover a key to see the one it uses.',
       brokenKey: 'broken (3× AUTH)',
       keyExpired: 'expired',
@@ -119,6 +123,10 @@ window.__ModuleLoader__.load({
       keySaved: 'сохранён',
       keyFromEnv: 'задан в окружении, отсюда не меняется',
       keyWriteFailed: 'не удалось сохранить ключ: {msg}',
+      notSecretShape: 'сохранено, но значение не похоже на API-ключ — проверьте опечатки',
+      rpmTitle: 'запросов/мин: {u} использовано, {r} осталось',
+      budgetLabel: 'бюджет:',
+      exportCsv: 'CSV',
       keyHint: 'Значение хранится в учётных данных DSH и обратно в браузер не отдаётся — показываются только последние 5 символов. Имена переменных создаются автоматически; наведите на ключ, чтобы увидеть используемое имя.',
       brokenKey: 'сломан (3× AUTH)',
       keyExpired: 'истёк',
@@ -292,7 +300,8 @@ window.__ModuleLoader__.load({
       }); };
       const doTest = (ref) => {
         setTesting(ref); setTestResult((m) => ({ ...m, [ref]: null }));
-        fetch('/dsh-key-rotation/test', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ref }) })
+        // #212: real API probe (models is free on most providers), not just presence
+        fetch('/dsh-key-rotation/test', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ref, probe: 'models' }) })
           .then((r) => r.json())
           .then((data) => setTestResult((m) => ({ ...m, [ref]: data })))
           .catch((e) => setTestResult((m) => ({ ...m, [ref]: { ok: false, message: String(e?.message ?? e) } })))
@@ -390,6 +399,11 @@ window.__ModuleLoader__.load({
           .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
+            // API-key shape - probably a placeholder or a typo.
+            if (data?.looksLikeSecret === false) {
+              setSecretError(t('notSecretShape'));
+            }
             setSecretDraft((cur) => {
               const next = { ...cur };
               delete next[rowKey];
@@ -510,7 +524,8 @@ window.__ModuleLoader__.load({
         if (hit.expired) return { color: 'var(--dsw-alias-state-error-primary)', text: t('keyExpired') };
         if (hit.expiresAt && !hit.expired) {
           const days = Math.ceil((hit.expiresAt - Date.now()) / 86400000);
-          if (days <= 7) return { color: 'var(--dsw-alias-state-warning-primary)', text: t('keyExpiringSoon').replace('{n}', String(days)) };
+          const warnDays = Number(val?.expiryWarnDays) || 7; // #207: configurable horizon
+          if (days <= warnDays) return { color: 'var(--dsw-alias-state-warning-primary)', text: t('keyExpiringSoon').replace('{n}', String(days)) };
         }
         if (hit.broken) return { color: 'var(--dsw-alias-state-error-primary)', text: t('brokenKey') };
         if (!hit.present) return { color: 'var(--dsw-alias-state-error-primary)', text: t('keyMissing') };
@@ -586,12 +601,19 @@ 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)));
+          // #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 },
+            '⏱' + info.rpm.remaining));
           if (info && typeof info.cost === 'number' && info.cost > 0) meta.push(h('span', { key: 'c', className: 'krot-tail', title: 'cost' }, '$' + info.cost.toFixed(2)));
           const tr = testResult[key];
           if (tr) meta.push(h('span', { key: 'tr', className: 'krot-tail',
-            title: tr.message || (tr.ok ? t('testOk') : t('testFail')),
+            title: (tr.message || (tr.ok ? t('testOk') : t('testFail')))
+              + (tr.ok && tr.modelsCount ? ' · ' + tr.modelsCount + ' models' : '')
+              + (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.ok ? (tr.modelsCount ? tr.modelsCount + 'm' : '✓') : '✕'));
           meta.push(h('button', { key: 't', className: 'krot-btn', onClick: () => doTest(key), disabled: testing === key, title: t('testKey') }, testing === key ? '…' : t('testKey')));
           meta.push(h('span', { key: 'a', className: 'krot-acts' },
             btn('↑', () => moveKey(pIndex, kIndex, -1), { disabled: kIndex === 0, title: t('moveUp') }),
@@ -616,6 +638,28 @@ 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%)
+        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 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');
+              return h('p', { className: 'krot-hint', style: { color } }, t('budgetLabel') + ' ' + parts.join(' · '));
+            })()
+          : null;
+        // #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);
+            const a = document.createElement('a');
+            a.href = url; a.download = 'usage-' + entry.provider + '.csv';
+            document.body.appendChild(a); a.click(); a.remove();
+          } }, t('exportCsv'));
 
         return h('div', { key: pIndex, className: 'krot-prov' },
           h('div', { className: 'krot-prov-head' },
@@ -653,11 +697,13 @@ window.__ModuleLoader__.load({
           h('div', { className: 'krot-foot' },
             btn(t('addKey'), () => addKey(pIndex), { title: t('addKeyTitle') }),
             switchesLine,
+            budgetLine,
             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),
             (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),
             btn(t('resetCooldown'), () => doReset(entry.provider), { disabled: !(providerStatus && providerStatus.switches > 0) || resetting === entry.provider, title: t('resetCooldown') }),
             btn(testAllProvider === entry.provider ? t('testing') : t('testAll'), () => doTestAll(entry.provider), { disabled: testAllProvider === entry.provider, title: t('testAll') }),
+            exportCsv,
           ),
         );
       });
@@ -803,10 +849,54 @@ window.__ModuleLoader__.load({
   if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', init); else init();
 }
 
-function apply(ctx) {
+    // #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() {
+      const [snap, setSnap] = React.useState(null);
+      React.useEffect(() => {
+        let alive = true;
+        const load = () => {
+          fetch('/dsh-key-rotation/health', { headers: { accept: 'application/json' }, credentials: 'same-origin' })
+            .then((r) => (r.ok ? r.json() : null))
+            .then((d) => { if (alive) setSnap(d); })
+            .catch(() => {});
+        };
+        load();
+        const id = setInterval(load, 4000);
+        return () => { alive = false; clearInterval(id); };
+      }, []);
+      const pools = Object.values((snap && snap.pools) || {});
+      const total = pools.reduce((a, p) => a + (p.total || 0), 0);
+      const healthy = pools.reduce((a, p) => a + (p.healthy || 0), 0);
+      const anyExhausted = pools.some((p) => p.exhausted);
+      const color = !pools.length ? 'var(--dsw-alias-label-tertiary)' : anyExhausted ? '#e5484d' : healthy < total ? '#f5a623' : '#30a46c';
+      const label = pools.length ? `${healthy}/${total}` : 'rot';
+      return h('span', {
+        className: 'krot-chip',
+        title: 'Key Rotation',
+        style: { display: 'inline-flex', alignItems: 'center', gap: '5px', fontSize: '11px', color: 'var(--dsw-alias-label-secondary)', cursor: 'default' },
+      },
+        h('span', { style: { width: '8px', height: '8px', borderRadius: '50%', background: color, flex: 'none' } }),
+        label);
+    }
+
+    function apply(ctx) {
       ctx.effect(() => ctx.locale.register(NS, { en, ru }), 'dsh-key-rotation: dictionaries');
       // Dashboard widget: lives on every page, polls /health (#152).
       ctx.effect(() => mountDashboard(), 'dsh-key-rotation: dashboard widget');
+      // Header chip (#201): status dot in the session header utilities slot,
+      // same slot dsh-gitea / dsh-subscriptions use for their header widgets.
+      ctx.effect(() => {
+        if (!ctx.slots) return;
+        try {
+          ctx.slots.inject('conversation.session.header.utilities', () =>
+            ctx.slots.register(
+              { name: 'conversation.session.header.utilities', id: 'dsh-key-rotation-header-chip', order: 6 },
+              KeyRotationHeaderChip,
+            ));
+        } catch { /* slot not available in this build */ }
+      }, 'dsh-key-rotation: header chip');
       function useLocale() {
         return useActiveLocale(ctx);
       }

package/lib/concurrency.js

@@ -1,72 +1,72 @@
-// concurrency.js — per-key in-flight counter + least-connections picking (issue #193).
-
-export const CONCURRENCY_DEFAULT_LIMIT = 0;
-export const CONCURRENCY_STALE_LOCK_MS = 5 * 60 * 1000;
-
-export class ConcurrencyTracker {
-  constructor(opts) {
-    opts = opts || {};
-    const limit = opts.limit !== undefined ? opts.limit : CONCURRENCY_DEFAULT_LIMIT;
-    this._limit = (Number.isFinite(limit) && limit >= 0) ? Math.floor(limit) : 0;
-    this._staleMs = opts.staleMs || CONCURRENCY_STALE_LOCK_MS;
-    this._inFlight = new Map();
-  }
-
-  isEnabled() { return this._limit > 0; }
-  get limit() { return this._limit; }
-
-  acquire(ref, now) {
-    now = now || Date.now();
-    if (!this.isEnabled()) return true;
-    let e = this._inFlight.get(ref);
-    if (!e) {
-      e = { count: 0, lastAcquired: now };
-      this._inFlight.set(ref, e);
-    }
-    if (now - e.lastAcquired > this._staleMs) {
-      e.count = 0;
-    }
-    if (e.count >= this._limit) return false;
-    e.count += 1;
-    e.lastAcquired = now;
-    return true;
-  }
-
-  release(ref, now) {
-    now = now || Date.now();
-    const e = this._inFlight.get(ref);
-    if (!e) return;
-    e.count = Math.max(0, e.count - 1);
-    e.lastAcquired = now;
-  }
-
-  snapshot() {
-    const out = {};
-    for (const [k, v] of this._inFlight) out[k] = { count: v.count };
-    return out;
-  }
-
-  pickLeastLoaded(candidates, now) {
-    now = now || Date.now();
-    if (!Array.isArray(candidates) || candidates.length === 0) return null;
-    let best = null;
-    let bestCount = Infinity;
-    for (const ref of candidates) {
-      const e = this._inFlight.get(ref);
-      const count = e ? e.count : 0;
-      if (this.isEnabled() && count >= this._limit) continue;
-      if (count < bestCount) {
-        best = ref;
-        bestCount = count;
-      }
-    }
-    return best;
-  }
-
-  clear(ref) {
-    if (ref) this._inFlight.delete(ref);
-    else this._inFlight.clear();
-  }
-
-  get size() { return this._inFlight.size; }
-}
+// concurrency.js — per-key in-flight counter + least-connections picking (issue #193).
+
+export const CONCURRENCY_DEFAULT_LIMIT = 0;
+export const CONCURRENCY_STALE_LOCK_MS = 5 * 60 * 1000;
+
+export class ConcurrencyTracker {
+  constructor(opts) {
+    opts = opts || {};
+    const limit = opts.limit !== undefined ? opts.limit : CONCURRENCY_DEFAULT_LIMIT;
+    this._limit = (Number.isFinite(limit) && limit >= 0) ? Math.floor(limit) : 0;
+    this._staleMs = opts.staleMs || CONCURRENCY_STALE_LOCK_MS;
+    this._inFlight = new Map();
+  }
+
+  isEnabled() { return this._limit > 0; }
+  get limit() { return this._limit; }
+
+  acquire(ref, now) {
+    now = now || Date.now();
+    if (!this.isEnabled()) return true;
+    let e = this._inFlight.get(ref);
+    if (!e) {
+      e = { count: 0, lastAcquired: now };
+      this._inFlight.set(ref, e);
+    }
+    if (now - e.lastAcquired > this._staleMs) {
+      e.count = 0;
+    }
+    if (e.count >= this._limit) return false;
+    e.count += 1;
+    e.lastAcquired = now;
+    return true;
+  }
+
+  release(ref, now) {
+    now = now || Date.now();
+    const e = this._inFlight.get(ref);
+    if (!e) return;
+    e.count = Math.max(0, e.count - 1);
+    e.lastAcquired = now;
+  }
+
+  snapshot() {
+    const out = {};
+    for (const [k, v] of this._inFlight) out[k] = { count: v.count };
+    return out;
+  }
+
+  pickLeastLoaded(candidates, now) {
+    now = now || Date.now();
+    if (!Array.isArray(candidates) || candidates.length === 0) return null;
+    let best = null;
+    let bestCount = Infinity;
+    for (const ref of candidates) {
+      const e = this._inFlight.get(ref);
+      const count = e ? e.count : 0;
+      if (this.isEnabled() && count >= this._limit) continue;
+      if (count < bestCount) {
+        best = ref;
+        bestCount = count;
+      }
+    }
+    return best;
+  }
+
+  clear(ref) {
+    if (ref) this._inFlight.delete(ref);
+    else this._inFlight.clear();
+  }
+
+  get size() { return this._inFlight.size; }
+}

package/lib/heal.js

@@ -1,35 +1,35 @@
-// heal.js — self-healing idle cooldowns.
-// ponytail: pure function, easy to test, no side effects beyond mutation of passed-in state.
-
-// Returns array of { ref, poolBase } entries that were healed in this tick.
-// Mutates `pools` (removes from failedUntil, pushes heal event into events).
-// `now` parameter is injectable for tests.
-export function healIdleCooldowns(pools, idleMs, now = Date.now()) {
-  if (!Array.isArray(pools) || pools.length === 0) return [];
-  if (!Number.isFinite(idleMs) || idleMs <= 0) return [];
-  const healed = [];
-  for (const pool of pools) {
-    if (!pool || !pool.state || !pool.base) continue;
-    const fu = pool.state.failedUntil;
-    const lu = pool.state.lastUsed;
-    if (!fu || fu.size === 0) continue;
-    const expiredRefs = [];
-    for (const [ref, until] of fu.entries()) {
-      if (!Number.isFinite(until)) continue;
-      if (until > now) continue; // cooldown still active
-      const last = lu ? lu.get(ref) : undefined;
-      if (!Number.isFinite(last)) continue; // never used → no signal, skip
-      if (now - last < idleMs) continue; // used recently → don't heal
-      expiredRefs.push(ref);
-    }
-    for (const ref of expiredRefs) {
-      fu.delete(ref);
-      if (Array.isArray(pool.state.events)) {
-        pool.state.events.push({ at: now, ref, reason: 'self-heal', cooldownMs: 0, type: 'heal' });
-        if (pool.state.events.length > 50) pool.state.events.shift();
-      }
-      healed.push({ ref, poolBase: pool.base });
-    }
-  }
-  return healed;
-}
+// heal.js — self-healing idle cooldowns.
+// ponytail: pure function, easy to test, no side effects beyond mutation of passed-in state.
+
+// Returns array of { ref, poolBase } entries that were healed in this tick.
+// Mutates `pools` (removes from failedUntil, pushes heal event into events).
+// `now` parameter is injectable for tests.
+export function healIdleCooldowns(pools, idleMs, now = Date.now()) {
+  if (!Array.isArray(pools) || pools.length === 0) return [];
+  if (!Number.isFinite(idleMs) || idleMs <= 0) return [];
+  const healed = [];
+  for (const pool of pools) {
+    if (!pool || !pool.state || !pool.base) continue;
+    const fu = pool.state.failedUntil;
+    const lu = pool.state.lastUsed;
+    if (!fu || fu.size === 0) continue;
+    const expiredRefs = [];
+    for (const [ref, until] of fu.entries()) {
+      if (!Number.isFinite(until)) continue;
+      if (until > now) continue; // cooldown still active
+      const last = lu ? lu.get(ref) : undefined;
+      if (!Number.isFinite(last)) continue; // never used → no signal, skip
+      if (now - last < idleMs) continue; // used recently → don't heal
+      expiredRefs.push(ref);
+    }
+    for (const ref of expiredRefs) {
+      fu.delete(ref);
+      if (Array.isArray(pool.state.events)) {
+        pool.state.events.push({ at: now, ref, reason: 'self-heal', cooldownMs: 0, type: 'heal' });
+        if (pool.state.events.length > 50) pool.state.events.shift();
+      }
+      healed.push({ ref, poolBase: pool.base });
+    }
+  }
+  return healed;
+}