@goodandready/dsh-key-rotation 0.8.8 → 0.8.11

package/README.md

@@ -22,12 +22,41 @@
   <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
 </p>
 
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>If you like this plugin, please star it on GitHub</strong> — it shows me that the plugin is useful to you and motivates me to keep developing it.
+      <br><br>
+      🐛 <strong>If you find a bug or would like to request a feature</strong>, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
+    </td>
+  </tr>
+</table>
+
 </div>
 
 ---
 
 ## ⚡ Overview & The Problem
 
+### 🚀 What's New in v0.8.11 (One-click Updater & Quality Gate)
+
+- **Plugin updater in Settings**: see current/latest version and update from the card without leaving DSH (`#307`).
+- **Safer best-effort side effects**: intentional non-critical failures log at debug instead of silent empty `catch` (`#315`).
+- **Theme-only client colors** and production-path test cleanup (`#311`, `#314`).
+- **Leaner publication set**: agent-only files no longer ship in git/npm (`#308`).
+
+### 🚀 What's New in v0.8.10 (Stream Concurrency Hardening & Auto-Pruning)
+- **Zero Concurrency Leaks**: Guaranteed release of stream concurrency slots via deterministic `try ... finally` block, preventing key starvation during clean finishes or client stream aborts.
+- **Robust Probe Retry**: Added transient network socket error retry (`PROBE_RETRY_DELAY_MS`) in `SandboxRunner.probeModels` before marking keys as broken.
+- **Memory & State Pruning**: Automated pruning of removed/stale keys from internal pool maps during periodic sweep cycles.
+
+### 🚀 What's New in v0.8.9 (Routing Evolution & UI)
+- **Proactive Rate-Limit Guard**: Automatic key pausing based on `x-ratelimit-remaining-*` and `Retry-After` headers before hitting 429 errors.
+- **Self-Healing / Auto-Unbreak**: Periodic background probe via free `/models` endpoint to automatically revive broken keys without token burn.
+- **Latency-Aware Routing**: Selectable strategies: `round-robin`, `least-loaded` (concurrency), and `lowest-latency` (p95 latency).
+- **UI Evolution in `dsh-clinebot` Style**: Sequential batch "Test All Keys" runner with live progress, Live Event Stream drawer, and Quota Reset countdown badge.
+- **Native Dual Language Support**: Native English (`en`) and Chinese (`zh`) UI dictionaries.
+
 ### 🛠️ What's New in v0.8.0 (Stability)
 - **🔌 Circuit breaker**: after N consecutive provider failures the circuit opens and requests fail fast (`CIRCUIT_OPEN`) until a cool-down; half-open probes recover automatically.
 - **🕒 Monotonic clock**: cooldown/breaker durations use process monotonic time so NTP steps cannot invert remaining times.
@@ -38,7 +67,6 @@
 - **📡 Status extras**: per-provider `circuit` plus `meta.expectedClones` / `meta.notifyQueue`.
 - **🧪 Smoke harness**: scripted 429 → next-key → success path in `test/smoke-rotation-080.test.mjs`.
 
-
 ### 🛠️ What's New in v0.7.33 (Stability & Bugfix Release)
 - **🔍 Resolved Key Probing BaseURL**: Fixed `resolveBaseUrl` to map key credential refs to owning provider pools, restoring live `probeModels` testing.
 - **🛡️ Guarded Cascade Recursion**: Prevented call stack overflow in cross-provider failover when circular cascade chains occur.
@@ -49,7 +77,6 @@
 - **🎨 Native Design System (Changed in v0.8.3)**: Unified with `dsh-clinebot` baseline: modular section cards, live pool telemetry stat boxes, pill badges, and complete semantic theme token styling (#281).
 - **🌐 Localization (Changed in v0.8.2)**: Source strings are English-only. Russian/Chinese UI comes from the DSH core locale service and translation plugins (`props.t`). Active locale: host snapshot → first `navigator.languages` entry → `en` (#277).
 
-
 ### 🚀 What's New in v0.7.31
 - **⚡ O(1) TokenBucket Accumulator**: Upgraded rate limiting math to O(1) time and zero-allocation memory with adaptive header synchronization.
 - **🛡️ Soft vs Hard Backoff**: Differentiates transient infrastructure drops (502/503/timeouts: 10s flat cooldown) from hard quota errors (progressive doubling).
@@ -61,7 +88,6 @@
 - **🧹 30-Day Usage Compaction**: Automatic bounded memory management with 30-day rolling window data pruning.
 - **✨ Optimistic UI & Filter Pills**: Instant zero-latency UI updates on reset, plus `All`, `Ready`, `In Cooldown`, and `With Errors` quick filter chips.
 
-
 High-throughput autonomous agent workflows, parallel subagent swarms, and multi-turn tool loops inevitably hit upstream API rate limits (HTTP 429, RPM/TPM exhaustion, daily quotas, or sudden provider outages). In standard DeepSeek Harness deployments, a single exhausted API key breaks the entire agent execution chain, requiring manual intervention and destroying the session's replay state.
 
 **`dsh-key-rotation`** provides a seamless, enterprise-ready **transparent API key pooling, pre-emptive rate-limiting, and cross-provider failover engine** built natively on the Cordis microkernel architecture.
@@ -145,6 +171,17 @@ graph LR
 
 ---
 
+
+### 🔁 8. One-click Plugin Updater
+
+The settings card includes an **Updater** section:
+
+1. **Check for updates** — `GET /api/dsh-key-rotation/update` returns `currentVersion`, `latestVersion`, `updateAvailable`, `canAutoUpdate` (version metadata only; no secrets).
+2. **Update now** — `POST` with the same path installs the exact latest npm version through the standard `dsh plugin add` flow. The request is accepted only from loopback with a matching same-origin `Origin`/`Host` (and the dedicated header). Cross-origin or missing-origin POST is rejected with `403`.
+3. After a successful install the UI tells you to **restart DSH** so the new host code loads.
+
+No `--force`, no raw shell, no install from worktree/DEV paths. Update runs only after an explicit click.
+
 ## 🖥️ Rich Web GUI & Dashboard
 
 Access full visual management under **Settings → Key Rotation** or via the Header quick-widget.

package/README.ru.md

@@ -22,12 +22,41 @@
   <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
 </p>
 
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>Если вам нравится этот плагин, поставьте ему звезду на GitHub</strong> — это покажет мне, что плагин вам полезен, и будет мотивировать меня развивать его дальше.
+      <br><br>
+      🐛 <strong>Если вы нашли баг или хотите предложить новый функционал</strong>, создайте issue на GitHub на любом языке — я рассмотрю ваше предложение и реализую полезные идеи в одной из следующих версий плагина.
+    </td>
+  </tr>
+</table>
+
 </div>
 
 ---
 
+### 🚀 Что нового в v0.8.11 (обновление в один клик и quality gate)
+
+- **Обновление плагина в карточке настроек**: текущая/последняя версия и кнопка установки без выхода из DSH (#307).
+- **bestEffort вместо пустых catch**: осознанные побочные эффекты логируются на debug, а не глотаются (#315).
+- **Цвета клиента только из токенов темы** и чистка production-path тестов (#311, #314).
+- **Публикационный набор без служебных файлов агентов** (#308).
+
 ## ⚡ Обзор и решаемая проблема
 
+### 🚀 Что нового в версии 0.8.10 (Надёжность стриминга и очистка памяти)
+- **Устранение утечек счётчика соединений**: Гарантированное освобождение слота конкурентности в `try ... finally`, исключающее блокировку ключей при успешном завершении стрима или прерывании клиентом.
+- **Повтор при сетевых сбоях проверки**: 1 автоматический повтор при кратковременных сокетных ошибках в `probeModels` перед дисквалификацией ключа.
+- **Очистка устаревших ключей**: Периодическая автоматическая очистка удалённых ключей из внутренних карт состояния пула при регулярном цикле `sweep`.
+
+### 🚀 Что нового в версии 0.8.9 (Развитие маршрутизации и UI)
+- **Превентивная защита от лимитов (Proactive Rate-Limit Guard)**: Автоматическая пауза ключей по заголовкам `x-ratelimit-remaining-*` и `Retry-After` до наступления ошибки 429.
+- **Авто-восстановление (Self-Healing / Auto-Unbreak)**: Периодический фоновый опрос эндпоинта `/models` для автоматического снятия статуса `broken` без расхода чат-токенов.
+- **Маршрутизация по задержке (Latency-Aware Routing)**: Выбор стратегии балансировки: `round-robin`, `least-loaded` (по активным запросам) и `lowest-latency` (по p95 задержки).
+- **Обновление интерфейса в стиле `dsh-clinebot`**: Пакетное тестирование всех ключей («Test All Keys») с прогрессом, аккордеон живого потока событий ротации (`.krot-event-stream`) и таймер обратного отсчета сброса квот.
+- **Встроенная поддержка двух языков**: Готовые словари интерфейса на английском (`en`) и китайском (`zh`).
+
 ### 🛠️ Что нового в версии 0.8.0 (Стабильность)
 - **🔌 Автомат выключения провайдера**: после N подряд ошибок контур открывается, запросы быстро завершаются (`CIRCUIT_OPEN`); half-open пробы восстанавливают сервис.
 - **🕒 Монотонные часы**: cooldown/breaker считаются по процессным часам, NTP не ломает оставшееся время.
@@ -38,7 +67,6 @@
 - **📡 Status**: `circuit` у провайдера + `meta.expectedClones` / `meta.notifyQueue`.
 - **🧪 Smoke**: сценарий 429 → следующий ключ → успех.
 
-
 ### 🛠️ Что нового в версии 0.7.33 (Хотфикс и повышение стабильности)
 - **🔍 Исправление проверки ключей**: Функция `resolveBaseUrl` теперь сопоставляет ref ключа с его пулом, восстанавливая работу живого тестирования моделей.
 - **🛡️ Защита от зацикливания каскада**: Устранена возможность переполнения стека при взаимных кольцевых цепочках failover.
@@ -47,7 +75,6 @@
 - **⚡ Сброс зависших блокировок**: Алгоритм `pickLeastLoaded` теперь учитывает протухшие блокировки при выборе наименее нагруженного ключа.
 - **🌐 Полная китайская локализация**: Добавлен словарь `zh` в веб-интерфейс настроек для соблюдения стандарта трёх языков (EN/RU/ZH).
 
-
 ### 🚀 Что нового в версии 0.7.31
 - **⚡ $O(1)$ Накопитель TokenBucket**: Оптимизация математики лимитов до $O(1)$ по времени и без аллокаций памяти с адаптивной синхронизацией по заголовкам.
 - **🛡️ Разделение Soft / Hard сбоев**: Кратковременные сетевые сбои (502/503/таймауты) получают короткий 10-секундный кулдаун без штрафного удвоения.
@@ -59,7 +86,6 @@
 - **🧹 30-дневная компактизация**: Автоматическая очистка истории старше 30 дней для защиты от утечек памяти.
 - **✨ Оптимистичный UI и фильтры**: Мгновенный отклик кнопок сброса и статус-пилюли (`Все`, `Готовы`, `В кулдауне`, `С ошибками`) над списком ключей.
 
-
 При активной работе автономных агентов, параллельном запуске субагентов и циклических вызовах инструментов запросы неизбежно упираются в ограничения провайдеров (ошибки HTTP 429 Too Many Requests, исчерпание суточных квот или временные сбои на стороне апстрима). В стандартной конфигурации DeepSeek Harness исчерпание одного API-ключа полностью блокирует цепочку рассуждений агента, ломает сохранённое состояние диалога (Replay State) и требует ручного вмешательства администратора.
 
 **`dsh-key-rotation`** реализует отказоустойчивую корпоративную архитектуру **пулов API-ключей с предиктивным контролем лимитов (Token Bucket) и каскадным переключением на резервных провайдеров**, нативно интегрированную в микроядро Cordis.
@@ -171,6 +197,17 @@ graph LR
 
 ---
 
+
+### 🔁 8. Обновление плагина в один клик
+
+В карточке настроек есть раздел **Updater**:
+
+1. **Проверить обновления** — `GET /api/dsh-key-rotation/update` возвращает `currentVersion`, `latestVersion`, `updateAvailable`, `canAutoUpdate` (только метаданные версии).
+2. **Обновить сейчас** — `POST` ставит точную последнюю npm-версию штатным `dsh plugin add`. Запрос принимается только с loopback и совпадающим same-origin `Origin`/`Host`; иначе `403`.
+3. После установки UI предлагает **перезапустить DSH**.
+
+Без `--force`, без raw shell и установки из worktree/DEV. Обновление — только по явному нажатию.
+
 ## 📦 Установка
 
 ```bash

package/README.zh.md

@@ -22,12 +22,41 @@
   <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
 </p>
 
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。
+      <br><br>
+      🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。
+    </td>
+  </tr>
+</table>
+
 </div>
 
 ---
 
 ## ⚡ 概述与核心痛点
 
+### 🚀 v0.8.11 新特性（一键更新与质量门禁）
+
+- **设置卡片中的插件更新器**：查看当前/最新版本并一键安装（#307）。
+- **bestEffort 替代空 catch**：非关键副作用在 debug 级别记录，不再被静默吞掉（#315）.
+- **客户端颜色仅使用主题变量**，并清理 production-path 测试（#311、#314）。
+- **发布集不再包含代理专用文件**（#308）。
+
+### 🚀 v0.8.10 版本新特性（流并发加固与状态自动修剪）
+- **杜绝并发计数泄漏**：在 `try ... finally` 中强制释放流并发占用，防止在正常完成或客户端中断时密钥被永久锁定。
+- **探测抗网络抖动重试**：在 `probeModels` 中遇到套接字网络临时错误时自动重试一次，避免密钥被误判损坏。
+- **内存与过期状态自动清理**：在定期清理周期中自动清除已删除密钥的内部映射记录。
+
+### 🚀 v0.8.9 版本新特性（智能路由与界面升级）
+- **前瞻性限流防护 (Proactive Rate-Limit Guard)**：根据 `x-ratelimit-remaining-*` 和 `Retry-After` 响应头在触发 429 错误前自动预冷密钥。
+- **自愈恢复 (Self-Healing / Auto-Unbreak)**：通过免费的 `/models` 接口进行定期后台探测，自动恢复处于 `broken` 状态的密钥，无需消耗聊天代币。
+- **延迟感知路由 (Latency-Aware Routing)**：可选路由策略：`round-robin`（轮询）、`least-loaded`（并发负载最低）与 `lowest-latency`（p95 延迟最低）。
+- **`dsh-clinebot` 风格界面升级**：支持带进度提示的批量“测试所有密钥”（Test All Keys）、实时事件流折叠抽屉（Live Event Stream）及配额重置倒计时徽标。
+- **原生中英文双语支持**：内置英文（`en`）与中文（`zh`）用户界面词典。
+
 ### 🛠️ v0.8.0 版本新特性（稳定性）
 - **🔌 熔断器**：连续失败后快速失败（`CIRCUIT_OPEN`），半开探测自动恢复。
 - **🕒 单调时钟**：冷却/熔断使用进程单调时间，NTP 校时不会颠倒剩余时间。
@@ -38,7 +67,6 @@
 - **📡 Status**：提供商 `circuit` + `meta`。
 - **🧪 Smoke**：429 → 切换密钥 → 成功。
 
-
 ### 🛠️ v0.7.33 版本新特性 (稳定性与问题修复)
 - **🔍 修复密钥探测 BaseURL 解析**：`resolveBaseUrl` 现已支持从密钥 ref 反查归属提供商池，恢复在线模型连通性探测。
 - **🛡️ 防御级联无限递归**：在跨提供商故障转移中增加递归深度防护，彻底杜绝循环级联导致的堆栈溢出。
@@ -47,7 +75,6 @@
 - **⚡ 负载均衡超时锁自动释放**：`pickLeastLoaded` 算法现已检测过期连接锁，确保最小连接调度不发生偏移。
 - **🌐 完整中文界面本地化**：为 React 设置面板补充全部 `zh` 语言包，实现标准的三语（英/俄/中）无缝对齐。
 
-
 ### 🚀 v0.7.31 版本新特性
 - **⚡ O(1) 令牌桶累加器**：将速率限制计算升级为 O(1) 时间复杂度与零内存分配，并支持响应头自适应同步。
 - **🛡️ 软/硬故障分级退避**：区分临时网络抖动（502/503/超时获得 10 秒平缓冷却）与硬性配额超限（指数退避倍增）。
@@ -59,7 +86,6 @@
 - **🧹 30 天用量压缩**：自动清理超过 30 天的历史统计数据，保障长期运行内存上限。
 - **✨ 乐观 UI 与快速筛选标签**：一键重置即时生效，密钥列表新增 `全部`、`就绪`、`冷却中`、`故障` 状态筛选胶囊。
 
-
 在高吞吐量自主智能体运行、多子智能体并行执行与多轮工具调用场景下，API 极易触发上游服务商的速率限制（HTTP 429 Too Many Requests、RPM/TPM 耗尽、每日配额限制或网络抖动）。在原生的 DeepSeek Harness 中，单个密钥耗尽会导致整个智能体执行链路崩溃，破坏会话的 Replay 状态并要求人工干预。
 
 **`dsh-key-rotation`** 基于 Cordis 微内核架构构建，提供了无缝透明的 **API 密钥池轮换、客户端预判限流（Token Bucket）与跨提供商故障转移（Failover Cascade）** 解决方案。
@@ -263,7 +289,6 @@ MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
 - **本地化与文案 (Changed in v0.8.2)**: 插件仅注册英文源字符串 `en`；俄文/中文由 DSH 核心 locale 与 translation 插件通过 `props.t` 提供。活动语言回退：snapshot → 首个 `navigator.languages` → `en`。已移除 `settings.section` 回退与内置 `ru`/`zh` 表 (#236, #275, #277)。
 - **死代码清理**: 移除 header-chip 迁移后残留的废弃 `mountDashboard` 函数 (#240)。
 
-
 ### 熔断器参数（v0.8.0）
 
 | 参数 | 类型 | 默认 | 说明 |

package/lib/best-effort.js

@@ -0,0 +1,26 @@
+/** Run a non-critical side effect; never throw. Logs at debug when a logger is provided. */
+export function bestEffort(label, fn, logger) {
+  const log = (err) => {
+    try {
+      logger?.debug?.(`dsh-key-rotation: best-effort ${label}`, err);
+    } catch {
+      /* logger itself must not throw */
+    }
+  };
+  try {
+    const result = fn();
+    if (result && typeof result.then === 'function') {
+      return result.then(
+        (value) => value,
+        (err) => {
+          log(err);
+          return undefined;
+        },
+      );
+    }
+    return result;
+  } catch (err) {
+    log(err);
+    return undefined;
+  }
+}

package/lib/bucket.js

@@ -1,65 +1,6 @@
-// lib/bucket.js - per-key RPM token bucket (#192) + O(1) accumulator and adaptive tuning.
+// lib/bucket.js - per-key RPM token bucket (#192).
 const WINDOW_MS = 60000;
 
-/**
- * O(1) Mathematical Token Bucket Accumulator.
- * tokens = min(capacity, tokens + (now - lastRefill) * refillRate)
- */
-export class TokenBucketAccumulator {
-  constructor(capacity, windowMs = WINDOW_MS, now = Date.now()) {
-    this.capacity = Math.max(1, capacity);
-    this.tokens = this.capacity;
-    this.windowMs = windowMs;
-    this.refillRate = this.capacity / this.windowMs; // tokens per ms
-    this.lastRefill = now;
-  }
-
-  refill(now = Date.now()) {
-    const elapsed = Math.max(0, now - this.lastRefill);
-    if (elapsed > 0) {
-      this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate);
-      this.lastRefill = now;
-    }
-  }
-
-  allow(cost = 1, now = Date.now()) {
-    this.refill(now);
-    if (this.tokens >= cost) {
-      this.tokens -= cost;
-      return true;
-    }
-    return false;
-  }
-
-  retryMs(cost = 1, now = Date.now()) {
-    this.refill(now);
-    if (this.tokens >= cost) return 0;
-    const needed = cost - this.tokens;
-    return Math.ceil(needed / this.refillRate);
-  }
-
-  updateCapacity(newCapacity, now = Date.now()) {
-    this.refill(now);
-    const prevCap = this.capacity;
-    this.capacity = Math.max(1, newCapacity);
-    this.refillRate = this.capacity / this.windowMs;
-    // Scale current tokens proportionally or clamp
-    this.tokens = Math.min(this.capacity, Math.max(0, this.tokens + (this.capacity - prevCap)));
-  }
-
-  info(now = Date.now()) {
-    this.refill(now);
-    const used = Math.max(0, Math.round(this.capacity - this.tokens));
-    const remaining = Math.max(0, Math.floor(this.tokens));
-    return {
-      used,
-      remaining,
-      resetMs: this.retryMs(1, now),
-      capacity: this.capacity,
-    };
-  }
-}
-
 /** Sliding-window check: true if `ref` is under `limit` requests/min. */
 export function bucketAllow(windows, ref, limit, now = Date.now()) {
   if (!limit || limit <= 0) return true;
@@ -74,14 +15,6 @@ export function bucketAllow(windows, ref, limit, now = Date.now()) {
   return true;
 }
 
-/** Record a hit without checking (use after a successful resolve). */
-export function bucketHit(windows, ref, now = Date.now()) {
-  const cut = now - WINDOW_MS;
-  const hits = (windows.get(ref) ?? []).filter((t) => t > cut);
-  hits.push(now);
-  windows.set(ref, hits);
-}
-
 /** ms until `ref` may retry again (0 = now). */
 export function bucketRetryMs(windows, ref, limit, now = Date.now()) {
   if (!limit || limit <= 0) return 0;
@@ -108,22 +41,3 @@ export function bucketInfo(windows, ref, limit, now = Date.now()) {
   };
 }
 
-/**
- * Adaptive limit computation from HTTP headers with manual limit precedence.
- * If manualLimit is given (> 0), it acts as the upper ceiling.
- * If adaptive is enabled and upstream reports a lower limit/remaining, adapt downwards.
- */
-export function computeEffectiveLimit(headerRateLimit, manualLimit, adaptiveEnabled = true) {
-  const manual = (Number.isFinite(manualLimit) && manualLimit > 0) ? manualLimit : null;
-  if (!adaptiveEnabled || !headerRateLimit) {
-    return manual;
-  }
-  const headerLimit = headerRateLimit.limit;
-  if (Number.isFinite(headerLimit) && headerLimit > 0) {
-    if (manual) {
-      return Math.min(manual, headerLimit); // manual acts as upper ceiling
-    }
-    return headerLimit;
-  }
-  return manual;
-}

package/lib/cascade.js

@@ -1,39 +1,27 @@
-// 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;
+}
+