@goodandready/dsh-clinebot 0.3.8 → 0.3.9

package/lib/client.js

@@ -9,7 +9,7 @@ window.__ModuleLoader__.load({
     const SUBTITLE = 'ClinePass subscription ($9.99/mo) with curated & custom models.'
     const ROUTE_PREFIX = '/dsh-clinebot'
 
-    const en = {
+const en = {
       title: 'ClineBot',
       subtitle: 'ClinePass subscription ($9.99/mo) with curated & custom models.',
       'settings.loading': 'Loading ClineBot settings…',
@@ -89,88 +89,98 @@ window.__ModuleLoader__.load({
       'diag.unregister_btn': 'Unregister from DSH',
       'diag.unregistering': 'Removing…',
       'diag.unregistered_msg': 'Provider removed from DSH Models',
+      'update.available': 'Update available: v{latestVersion} (current: v{currentVersion})',
+      'update.btn': 'Update Now',
+      'update.updating': 'Updating…',
+      'update.done': 'Successfully updated to v{version}! Please restart DSH.',
+      'update.failed': 'Update failed: {error}',
     }
 
-    const ru = {
+    const zh = {
       title: 'ClineBot',
-      subtitle: 'Подписка ClinePass ($9.99/мес) с каталогом проверенных моделей.',
-      'settings.loading': 'Загрузка настроек ClineBot…',
-      'settings.retry': 'Повторить попытку',
-      'settings.unavailable': 'Настройки ClineBot недоступны (пространство хоста ещё не готово).',
-      'header.title': 'Провайдер ClineBot (ClinePass)',
-      'header.sub': 'Подключение моделей по подписке ClinePass ($9.99/мес). OpenAI API совместимый, автоматическое отслеживание лимитов и моментальная авторегистрация в DSH.',
-      'badge.online': 'Сервер доступен ({latency} мс)',
-      'badge.offline': 'Недоступен',
-      'badge.key_ok': 'Ключ ✓ ({source})',
-      'badge.key_missing': 'Ключ отсутствует',
-      'badge.registered': 'Зарегистрирован в DSH ({count} мод.)',
-      'badge.not_registered': 'Не зарегистрирован',
-      'key.title': '🔑 Авторизация и API-ключ',
-      'key.desc': 'Ключ сохраняется в системное хранилище DSH Credentials (~/.dsh/.credentials.yaml) и никогда не попадает в открытые файлы настроек.',
+      subtitle: 'ClinePass 订阅服务 ($9.99/月)，包含精选与自定义模型。',
+      'settings.loading': '正在加载 ClineBot 设置…',
+      'settings.retry': '重试',
+      'settings.unavailable': 'ClineBot 设置不可用（宿主命名空间尚未就绪）。',
+      'header.title': 'ClineBot (ClinePass) 模型服务商',
+      'header.sub': '通过 ClinePass 订阅 ($9.99/月) 连接主流推理与编程模型。完全兼容 OpenAI 接口，自动追踪滚动限额并在 DSH 中即时生效。',
+      'badge.online': '服务在线 ({latency} ms)',
+      'badge.offline': '主机无法连接',
+      'badge.key_ok': '密钥正常 ({source})',
+      'badge.key_missing': '未配置密钥',
+      'badge.registered': '已接入 DSH ({count} 个模型)',
+      'badge.not_registered': '未接入 DSH',
+      'key.title': '🔑 授权与 API 密钥',
+      'key.desc': '密钥直接加密保存在 DSH 凭据管理器 (~/.dsh/.credentials.yaml)，绝不会以明文形式暴露在普通配置文件中。',
       'key.placeholder_has': '••••••••••••••••••••••••',
-      'key.placeholder_empty': 'Вставьте ключ ClinePass (cline_...)',
-      'key.show': 'Показать',
-      'key.hide': 'Скрыть',
-      'key.save': 'Сохранить ключ',
-      'key.saving': 'Сохранение…',
-      'key.login_fast': '🚀 Быстрый вход через браузер',
-      'key.login_waiting': 'Ожидание авторизации в браузере…',
-      'key.env_label': 'Переменная учётных данных: ',
-      'key.get_key': 'Получить ключ в консоли app.cline.bot ↗',
-      'key.saved_msg': 'Ключ сохранён в DSH Credentials. Валидация: {status}',
-      'key.empty_err': 'Введите API-ключ перед сохранением',
-      'accounts.title': '👥 Пул аккаунтов и авторотация (Failover)',
-      'accounts.desc': 'Добавьте запасные аккаунты. При исчерпании лимитов (429) ClineBot автоматически переключит запрос на следующий доступный аккаунт.',
-      'accounts.active_badge': 'Активен',
-      'accounts.pinned_badge': 'Закреплен',
-      'accounts.pin_btn': 'Сделать активным',
-      'accounts.add_btn': '+ Добавить аккаунт',
-      'accounts.label_placeholder': 'Название (например, Work)',
+      'key.placeholder_empty': '粘贴 ClinePass 密钥 (cline_...)',
+      'key.show': '显示',
+      'key.hide': '隐藏',
+      'key.save': '保存密钥',
+      'key.saving': '正在保存…',
+      'key.login_fast': '🚀 浏览器快速登录',
+      'key.login_waiting': '等待在浏览器中完成授权…',
+      'key.env_label': '凭据环境变量名称：',
+      'key.get_key': '前往 app.cline.bot 控制台获取密钥 ↗',
+      'key.saved_msg': '密钥已成功保存至 DSH 凭据服务。验证状态：{status}',
+      'key.empty_err': '保存前请输入 API 密钥',
+      'accounts.title': '👥 多账号故障转移与轮换池 (Failover)',
+      'accounts.desc': '添加备用账号。当某个账号触发 429 速率限制或配额耗尽时，ClineBot 会智能无缝切换至剩余额度最高的备用账号。',
+      'accounts.active_badge': '当前活动',
+      'accounts.pinned_badge': '固定使用',
+      'accounts.pin_btn': '设为活动',
+      'accounts.add_btn': '+ 添加账号',
+      'accounts.label_placeholder': '账号标签（例如：工作账号）',
       'accounts.env_placeholder': 'CLINEBOT_API_KEY_2',
-      'quota.title': '📊 Остаток лимитов подписки (ClinePass Quota)',
-      'quota.desc': 'Официальные лимиты скользящих окон запросов ClinePass',
-      'quota.account': 'Аккаунт: {email} · Тариф: {plan}',
-      'quota.refresh': 'Обновить квоты',
-      'quota.refreshing': 'Обновление…',
-      'quota.refreshed_msg': 'Лимиты подписки обновлены',
-      'quota.window_5h': '⏱ 5-часовое скользящее окно (Rolling Limit)',
-      'quota.window_weekly': '📅 Недельное окно (Weekly Window)',
-      'quota.used': '{pct}% использовано',
-      'quota.remaining': 'Осталось: {pct}%',
-      'quota.reset_at': 'Сброс: {time}',
-      'models.title': '🎯 Модели в пикере DSH ({enabled} из {total} включено)',
-      'models.desc': 'Список синхронизируется напрямую из подписки ClinePass. Новые модели появляются автоматически. Снимите галочку, чтобы скрыть ненужную модель из чата.',
-      'models.sync': '🔄 Проверить модели плана',
-      'models.syncing': 'Проверка…',
-      'models.synced_msg': 'Синхронизировано моделей подписки: {total} ({discovered} получено напрямую из плана)',
-      'models.all': 'Все',
-      'models.vision': 'Только Vision',
-      'models.coding': 'Только Кодинг',
-      'models.recommended': 'Рекомендованные',
-      'models.th_active': 'Вкл',
-      'models.th_name': 'Название модели',
-      'models.th_id': 'Model ID',
-      'models.th_ctx': 'Контекст',
-      'models.th_caps': 'Возможности',
-      'models.star': 'Star',
-      'models.auto_new': 'Новая',
-      'stats.title': '📈 Статистика текущей сессии DSH',
-      'stats.desc': 'Локальный мониторинг запросов, задержек сети и ориентировочного расхода токенов через ClinePass.',
-      'stats.requests': 'Успешных запросов / Всего',
-      'stats.tokens': 'Оценка токенов сессии',
-      'stats.latency': 'Последняя задержка (Latency)',
-      'stats.last_req': 'Время последнего запроса',
-      'diag.title': '⚡ Диагностика и авторегистрация в DSH',
-      'diag.desc': 'ClineBot автоматически регистрируется в DSH Models при наличии ключа. Вы можете запустить проверку связи или принудительно пересинхронизировать модели.',
-      'diag.smoke_btn': 'Запустить Smoke Test (Ping)',
-      'diag.smoke_testing': 'Тестирование…',
-      'diag.smoke_ok': 'Smoke тест пройден! Задержка: {latency} мс',
-      'diag.resync_btn': 'Принудительно обновить в DSH',
-      'diag.resyncing': 'Обновление…',
-      'diag.resynced_msg': 'Провайдер обновлен в DSH Models ({count} моделей)',
-      'diag.unregister_btn': 'Удалить из DSH Models',
-      'diag.unregistering': 'Удаление…',
-      'diag.unregistered_msg': 'Провайдер удален из DSH Models',
+      'quota.title': '📊 ClinePass 用量配额与限额监控',
+      'quota.desc': '来自 ClinePass 官方的实时滚动窗口用量限额',
+      'quota.account': '账号：{email} · 套餐：{plan}',
+      'quota.refresh': '刷新配额',
+      'quota.refreshing': '正在刷新…',
+      'quota.refreshed_msg': '订阅用量配额已刷新',
+      'quota.window_5h': '⏱ 5 小时滚动限额',
+      'quota.window_weekly': '📅 每周滚动窗口',
+      'quota.used': '已使用 {pct}%',
+      'quota.remaining': '剩余可用：{pct}%',
+      'quota.reset_at': '重置时间：{time}',
+      'models.title': '🎯 DSH 模型选择列表（已启用 {enabled}/{total}）',
+      'models.desc': '模型目录与 ClinePass 官方订阅实时同步。新订阅模型默认自动启用。取消勾选可在 DSH 对话模型列表中隐藏不需要的模型。',
+      'models.sync': '🔄 同步订阅模型',
+      'models.syncing': '正在同步…',
+      'models.synced_msg': '已成功同步订阅模型：共 {total} 个（发现 {discovered} 个新模型）',
+      'models.all': '全部模型',
+      'models.vision': '仅视觉 (Vision)',
+      'models.coding': '仅编程 (Coding)',
+      'models.recommended': '推荐模型',
+      'models.th_active': '启用',
+      'models.th_name': '模型名称',
+      'models.th_id': '模型标识符 (ID)',
+      'models.th_ctx': '上下文窗口',
+      'models.th_caps': '特性能力',
+      'models.star': '推荐',
+      'models.auto_new': '新上线',
+      'stats.title': '📈 当前 DSH 会话请求遥测',
+      'stats.desc': '本地实时监控请求次数、网络延迟以及通过 ClinePass 消耗的估算 Token 数量。',
+      'stats.requests': '成功 / 总请求次数',
+      'stats.tokens': '会话累计 Token 估算',
+      'stats.latency': '最近一次请求延迟',
+      'stats.last_req': '最近请求时间',
+      'diag.title': '⚡ 诊断工具与服务接入',
+      'diag.desc': '配置 API 密钥后，ClineBot 会自动向 DSH 注册模型服务。您可以在此进行连通性测试或强制重新同步。',
+      'diag.smoke_btn': '执行连通性冒烟测试 (Ping)',
+      'diag.smoke_testing': '正在测试…',
+      'diag.smoke_ok': '冒烟测试通过！网络延迟：{latency} ms',
+      'diag.resync_btn': '强制重新同步到 DSH',
+      'diag.resyncing': '正在同步…',
+      'diag.resynced_msg': '模型服务已重新同步到 DSH ({count} 个模型)',
+      'diag.unregister_btn': '从 DSH 注销该服务',
+      'diag.unregistering': '正在注销…',
+      'diag.unregistered_msg': '已从 DSH 模型注册表中移除',
+      'update.available': '发现新版本 v{latestVersion}（当前版本 v{currentVersion}）',
+      'update.btn': '立即更新',
+      'update.updating': '正在更新…',
+      'update.done': '更新成功至 v{version}！请重启 DSH 服务生效。',
+      'update.failed': '更新失败：{error}',
     }
 
     function makeT(dict, fallback) {
@@ -353,7 +363,7 @@ window.__ModuleLoader__.load({
 
     function SettingsPage(props) {
       const ctx = props?.ctx
-      const t = props?.t || makeT(ru, en)
+      const t = props?.t || makeT(en, en)
 
       const scope = React.useMemo(() => {
         const s = (ctx?.get && ctx.get('lanSettings')) || ctx?.settingsScope
@@ -1178,7 +1188,7 @@ window.__ModuleLoader__.load({
     // Accordion item for Plugins section
     function PluginCard(props) {
       const [open, setOpen] = React.useState(false)
-      const t = props?.t || makeT(ru, en)
+      const t = props?.t || makeT(en, en)
       React.useEffect(() => {
         ensureCss()
       }, [])
@@ -1261,7 +1271,7 @@ window.__ModuleLoader__.load({
       if (ctx.locale && ctx.locale.register) {
         if (typeof ctx.effect === 'function') {
           ctx.effect(() => {
-            const undo = [addLocale('en', en), addLocale('ru', ru)]
+            const undo = [addLocale('en', en), addLocale('zh', zh)]
             return () => { for (const off of undo) off() }
           }, 'dsh-clinebot: dictionaries')
         } else {

package/lib/cline-client.js

@@ -2,7 +2,7 @@
  * ClineBot / ClinePass client helpers for DeepSeek Harness.
  *
  * Implements OpenAI-compatible chat completions interface, usage quota tracking,
- * and secure credential storage via DSH credentials service.
+ * Stale-While-Revalidate caching, smart failover, and secure credential storage.
  */
 
 import {
@@ -19,6 +19,7 @@ export const DEFAULT_BASE_URL = 'https://api.cline.bot/api/v1'
 export const DEFAULT_API_KEY_ENV = 'CLINEBOT_API_KEY'
 export const DEFAULT_TIMEOUT_MS = 15000
 export const DEFAULT_SMOKE_TIMEOUT_MS = 25000
+export const USAGE_CACHE_TTL_MS = 60000
 
 export { PROVIDER_ID, PROVIDER_DISPLAY_NAME, DEFAULT_MODEL_ID }
 
@@ -130,8 +131,8 @@ function abortAfter(ms) {
   return { signal: ac.signal, cancel: () => clearTimeout(timer) }
 }
 
-// In-memory cache for quota queries to avoid hammering the ClinePass endpoint
-const usageCache = new Map()
+// In-memory caches for quota queries and host health probes
+export const usageCache = new Map()
 export const probeCache = new Map()
 
 export function clearProbeCache() {
@@ -155,7 +156,6 @@ export async function retryWithBackoff(fn, {
   while (true) {
     try {
       const res = await fn()
-      // If HTTP response-like object with 5xx or 429 status and can retry
       if (res && typeof res.status === 'number' && [429, 502, 503, 504].includes(res.status) && attempt < maxRetries) {
         attempt++
         const retryAfter = res.headers?.get ? Number(res.headers.get('retry-after')) * 1000 : 0
@@ -179,14 +179,13 @@ export async function retryWithBackoff(fn, {
 
 /**
  * Fetch official ClinePass rate limits and account quota.
- * Endpoints:
- * - GET /users/me/plan/usage-limits (5-hour, weekly, monthly rolling limits)
- * - GET /users/me (account metadata)
+ * Uses Stale-While-Revalidate (SWR) caching with keep-alive and network retry.
  */
 export async function fetchUsageLimits(baseUrl, apiKey, {
   timeoutMs = DEFAULT_TIMEOUT_MS,
   fetchImpl = fetch,
   bypassCache = false,
+  ttlMs = USAGE_CACHE_TTL_MS,
 } = {}) {
   const base = normalizeBaseUrl(baseUrl)
   if (!apiKey) {
@@ -196,126 +195,144 @@ export async function fetchUsageLimits(baseUrl, apiKey, {
   const cacheKey = `cline:usage:${apiKey.slice(-8)}`
   const now = Date.now()
 
-  if (!bypassCache && usageCache.has(cacheKey)) {
-    const cached = usageCache.get(cacheKey)
-    if (cached.expiresAt > now) {
-      return cached.data
-    }
-  }
-
-  const { signal, cancel } = abortAfter(timeoutMs)
-  try {
-    const headers = {
-      Authorization: `Bearer ${apiKey}`,
-      Accept: 'application/json',
-    }
-
-    // 1. Fetch usage limits
-    const limitsRes = await fetchImpl(`${base}/users/me/plan/usage-limits`, {
-      method: 'GET',
-      headers,
-      signal,
-    })
+  const doFetch = async () => {
+    const { signal, cancel } = abortAfter(timeoutMs)
+    try {
+      const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: 'application/json',
+      }
 
-    if (!limitsRes.ok) {
-      const errText = await limitsRes.text().catch(() => '')
-      return {
-        ok: false,
-        status: limitsRes.status,
-        error: `ClinePass limits error (HTTP ${limitsRes.status}): ${errText.slice(0, 150)}`,
+      let limitsRes
+      try {
+        limitsRes = await fetchImpl(`${base}/users/me/plan/usage-limits`, {
+          method: 'GET',
+          headers,
+          signal,
+          keepalive: true,
+        })
+      } catch (netErr) {
+        // Quick 1-retry fallback on transient network drop
+        await new Promise((r) => setTimeout(r, 250))
+        limitsRes = await fetchImpl(`${base}/users/me/plan/usage-limits`, {
+          method: 'GET',
+          headers,
+          signal,
+          keepalive: true,
+        })
       }
-    }
 
-    const limitsData = await limitsRes.json().catch(() => ({}))
-    const rawLimits = limitsData?.data?.limits || limitsData?.limits || []
+      if (!limitsRes.ok) {
+        const errText = await limitsRes.text().catch(() => '')
+        const outcome = {
+          ok: false,
+          status: limitsRes.status,
+          error: `ClinePass limits error (HTTP ${limitsRes.status}): ${errText.slice(0, 150)}`,
+          checkedAt: Date.now(),
+        }
+        if (!usageCache.has(cacheKey)) {
+          usageCache.set(cacheKey, { data: outcome, expiresAt: Date.now() + 5000, isRevalidating: false })
+        }
+        return outcome
+      }
 
-    const parseWindow = (type) => {
-      const found = Array.isArray(rawLimits) ? rawLimits.find((l) => l.type === type) : null
-      if (!found) return null
-      const percentUsed = typeof found.percentUsed === 'number'
-        ? Math.max(0, Math.min(100, Math.round(found.percentUsed * 10) / 10))
-        : 0
-      const remainingPercent = Math.max(0, Math.round((100 - percentUsed) * 10) / 10)
-      return {
-        type,
-        percentUsed,
-        remainingPercent,
-        resetsAt: found.resetsAt || null,
+      const limitsData = await limitsRes.json().catch(() => ({}))
+      const rawLimits = limitsData?.data?.limits || limitsData?.limits || []
+
+      const parseWindow = (type) => {
+        const found = Array.isArray(rawLimits) ? rawLimits.find((l) => l.type === type) : null
+        if (!found) return null
+        const percentUsed = typeof found.percentUsed === 'number'
+          ? Math.max(0, Math.min(100, Math.round(found.percentUsed * 10) / 10))
+          : 0
+        const remainingPercent = Math.max(0, Math.round((100 - percentUsed) * 10) / 10)
+        return {
+          type,
+          percentUsed,
+          remainingPercent,
+          resetsAt: found.resetsAt || null,
+        }
       }
-    }
 
-    const fiveHour = parseWindow('5-hour')
-    const weekly = parseWindow('weekly')
-    const monthly = parseWindow('monthly')
+      const fiveHour = parseWindow('5-hour')
+      const weekly = parseWindow('weekly')
+      const monthly = parseWindow('monthly')
 
-    // 2. Fetch user metadata and plan details (optional, best-effort)
-    let userEmail = null
-    let createdAt = null
-    let planDisplayName = 'ClinePass ($9.99/mo)'
-    let dynamicModels = []
+      let userEmail = null
+      let createdAt = null
+      let planDisplayName = 'ClinePass ($9.99/mo)'
+      let dynamicModels = []
 
-    try {
-      const [meRes, planRes] = await Promise.all([
-        fetchImpl(`${base}/users/me`, { method: 'GET', headers, signal }).catch(() => null),
-        fetchImpl(`${base}/users/me/plan`, { method: 'GET', headers, signal }).catch(() => null),
-      ])
-
-      if (meRes && meRes.ok) {
-        const meData = await meRes.json().catch(() => ({}))
-        const me = meData?.data || meData?.user || meData
-        userEmail = me?.email || null
-        createdAt = me?.createdAt || null
-      }
+      try {
+        const [meRes, planRes] = await Promise.all([
+          fetchImpl(`${base}/users/me`, { method: 'GET', headers, signal, keepalive: true }).catch(() => null),
+          fetchImpl(`${base}/users/me/plan`, { method: 'GET', headers, signal, keepalive: true }).catch(() => null),
+        ])
 
-      if (planRes && planRes.ok) {
-        const planData = await planRes.json().catch(() => ({}))
-        const planObj = planData?.data?.plan || planData?.plan
-        if (planObj?.displayName) {
-          planDisplayName = planObj.displayName
+        if (meRes?.ok) {
+          const meData = await meRes.json().catch(() => ({}))
+          userEmail = meData?.data?.email || meData?.email || null
+          createdAt = meData?.data?.createdAt || meData?.createdAt || null
         }
-        const includedArr = planObj?.features?.included
-        if (Array.isArray(includedArr)) {
-          const incStr = includedArr.find((s) => typeof s === 'string' && s.toLowerCase().includes('includes'))
-          if (incStr) {
-            dynamicModels = parsePlanIncludedModels(incStr)
+
+        if (planRes?.ok) {
+          const planData = await planRes.json().catch(() => ({}))
+          const plan = planData?.data || planData
+          if (plan?.title || plan?.name) {
+            planDisplayName = `${plan.title || plan.name} ($${((plan.priceInCents || 999) / 100).toFixed(2)}/mo)`
+          }
+          if (Array.isArray(plan?.includedModels)) {
+            dynamicModels = parsePlanIncludedModels(plan.includedModels)
           }
         }
+      } catch {
+        /* best-effort secondary details */
       }
-    } catch {
-      /* ignore user metadata / plan failure */
-    }
 
-    const result = {
-      ok: true,
-      plan: planDisplayName,
-      user: {
-        email: userEmail,
-        createdAt,
-      },
-      windows: {
-        fiveHour: fiveHour || { type: '5-hour', percentUsed: 0, remainingPercent: 100, resetsAt: null },
-        weekly: weekly || { type: 'weekly', percentUsed: 0, remainingPercent: 100, resetsAt: null },
-        monthly: monthly || { type: 'monthly', percentUsed: 0, remainingPercent: 100, resetsAt: null },
-      },
-      dynamicModels,
-      checkedAt: now,
+      const result = {
+        ok: true,
+        plan: planDisplayName,
+        user: { email: userEmail, createdAt },
+        windows: { fiveHour, weekly, monthly },
+        dynamicModels,
+        checkedAt: Date.now(),
+      }
+
+      usageCache.set(cacheKey, { data: result, expiresAt: Date.now() + ttlMs, isRevalidating: false })
+      return result
+    } catch (err) {
+      const outcome = {
+        ok: false,
+        error: String(err?.message || err),
+        checkedAt: Date.now(),
+      }
+      if (!usageCache.has(cacheKey)) {
+        usageCache.set(cacheKey, { data: outcome, expiresAt: Date.now() + 5000, isRevalidating: false })
+      }
+      return outcome
+    } finally {
+      cancel()
     }
+  }
 
-    // Cache for 60 seconds
-    usageCache.set(cacheKey, { expiresAt: now + 60000, data: result })
-    return result
-  } catch (err) {
-    return {
-      ok: false,
-      error: String(err?.message || err),
+  if (!bypassCache && usageCache.has(cacheKey)) {
+    const cached = usageCache.get(cacheKey)
+    if (cached.expiresAt > now) {
+      return cached.data
     }
-  } finally {
-    cancel()
+    // SWR: return stale data immediately, revalidate asynchronously
+    if (!cached.isRevalidating) {
+      cached.isRevalidating = true
+      doFetch().catch(() => {})
+    }
+    return cached.data
   }
+
+  return doFetch()
 }
 
 /**
- * Quick network probe to verify server availability with Stale-While-Revalidate caching.
+ * Health check probe with SWR caching.
  */
 export async function probeHealth(baseUrl, {
   timeoutMs = DEFAULT_TIMEOUT_MS,
@@ -323,15 +340,16 @@ export async function probeHealth(baseUrl, {
   bypassCache = false,
   ttlMs = 25000,
 } = {}) {
-  const root = normalizeBaseUrl(baseUrl)
-  const cacheKey = `probe:${root}`
+  const base = normalizeBaseUrl(baseUrl)
+  const root = base.replace(/\/api\/v1$/i, '')
+  const cacheKey = `cline:health:${root}`
   const now = Date.now()
 
   const doProbe = async () => {
     const { signal, cancel } = abortAfter(timeoutMs)
     const start = Date.now()
     try {
-      const res = await fetchImpl(root, { method: 'GET', signal, keepalive: true }).catch(async () => {
+      const res = await retryWithBackoff(async () => {
         return await fetchImpl(root, { method: 'HEAD', signal, keepalive: true })
       })
       const latencyMs = Date.now() - start
@@ -365,7 +383,6 @@ export async function probeHealth(baseUrl, {
     if (cached.expiresAt > now) {
       return cached.data
     }
-    // Stale-While-Revalidate: trigger async refresh and return stale snapshot immediately
     if (!cached.isRevalidating) {
       cached.isRevalidating = true
       doProbe().catch(() => {})
@@ -492,7 +509,7 @@ export function buildPiAiProvider({
 }
 
 /**
- * Safely resolve key value from DSH credentials or process.env.
+ * Safely resolve key value from DSH credentials service or process.env.
  */
 export async function resolveKeyValue(ctx, apiKeyEnv) {
   const refName = String(apiKeyEnv || DEFAULT_API_KEY_ENV).trim() || DEFAULT_API_KEY_ENV
@@ -551,7 +568,28 @@ export async function resolveAccountPool(ctx, cfg) {
 }
 
 /**
- * Rotate active account to next available configured account upon rate-limiting (429) or quota exhaustion.
+ * Check if a cached quota entry is currently exhausted.
+ * Checks 5-hour rolling limit and verifies if resetsAt timestamp has already elapsed.
+ */
+export function isAccountQuotaExhausted(usage) {
+  if (!usage?.windows?.fiveHour) return false
+  const fiveHour = usage.windows.fiveHour
+  if (typeof fiveHour.percentUsed !== 'number' || fiveHour.percentUsed < 95) {
+    return false
+  }
+  // Auto-recovery: if resetsAt is present and in the past, the account is recovered
+  if (fiveHour.resetsAt) {
+    const resetTime = new Date(fiveHour.resetsAt).getTime()
+    if (!Number.isNaN(resetTime) && Date.now() >= resetTime) {
+      return false
+    }
+  }
+  return true
+}
+
+/**
+ * Smart Quota-Aware Failover: rotates active account upon 429 or quota exhaustion.
+ * Prioritizes accounts with lowest percentUsed and respects resetsAt recovery.
  */
 export async function rotateToNextAccount(ctx, cfg, reason = 'rate_limit', settingsApi = null) {
   const pool = await resolveAccountPool(ctx, cfg)
@@ -562,8 +600,33 @@ export async function rotateToNextAccount(ctx, cfg, reason = 'rate_limit', setti
 
   const active = String(cfg?.activeAccount || configured[0].apiKeyEnv)
   const currentIndex = configured.findIndex((acc) => acc.apiKeyEnv === active)
-  const nextIndex = (currentIndex + 1) % configured.length
-  const nextAcc = configured[nextIndex]
+
+  // Candidate pool excluding current account if possible
+  const candidates = configured.filter((acc) => acc.apiKeyEnv !== active)
+  if (!candidates.length) {
+    return { rotated: false, reason, message: 'No alternative accounts configured' }
+  }
+
+  // Assess quota for candidates if cached in memory
+  let bestCandidate = null
+  let lowestUsagePct = Infinity
+
+  for (const cand of candidates) {
+    const cacheKey = `cline:usage:${cand.value.slice(-8)}`
+    const cached = usageCache.get(cacheKey)?.data
+    const isExhausted = isAccountQuotaExhausted(cached)
+
+    if (!isExhausted) {
+      const pct = cached?.windows?.fiveHour?.percentUsed ?? 50
+      if (pct < lowestUsagePct) {
+        lowestUsagePct = pct
+        bestCandidate = cand
+      }
+    }
+  }
+
+  // Fallback if all candidates are either exhausted or uncached: pick next in round-robin
+  const nextAcc = bestCandidate || candidates[currentIndex % candidates.length] || candidates[0]
 
   let updated = false
   if (settingsApi?.replace) {