@goodandready/dsh-subscriptions 0.6.15 → 0.6.17

package/lib/accounts.js

@@ -2,7 +2,7 @@ import { fetchWithTimeout } from "./http.js"
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import { oauthRef, isProvider } from './refs.js'
 import { parseBlob, serializeBlob } from './blob.js'
-import { recordSwitch, recordExhaust, recordBroken } from './health.js'
+import { recordSwitch, recordExhaust, recordBroken, computeHealthScore } from './health.js'
 import { executeWithRetry } from './backoff.js'
 import { getVendor } from './vendors/index.js'
 
@@ -177,6 +177,7 @@ export function createAccountStore({ credentials, getConfig, fetchImpl, fetchFor
         cooldownUntil: info.cooldownUntil,
         cooldownFamilies: info.cooldownFamilies || null,
         quota: info.quota || null,
+        healthScore: computeHealthScore(info.health),
         quarantineUntil: inQ ? q.until : 0,
         quarantineReason: inQ ? q.reason : null,
         label: slot.label || info.label,

package/lib/adapter.js

@@ -99,7 +99,10 @@ export class SubscriptionAdapter extends LlmAdapter {
     let yieldedAny = false
     try {
       if (typeof deps.refreshUsage === 'function') {
-        await deps.refreshUsage(provider)
+        try {
+          const p = deps.refreshUsage(provider)
+          if (p && typeof p.catch === 'function') p.catch(() => {})
+        } catch { /* fire-and-forget background usage refresh */ }
       }
       for await (const event of streamWithRotation({
         accounts: await deps.listAccounts(provider),
@@ -108,7 +111,7 @@ export class SubscriptionAdapter extends LlmAdapter {
         switchAtRemaining: typeof deps.switchAtRemaining === 'function' ? deps.switchAtRemaining() : (deps.switchAtRemaining ?? 0),
         options,
         onCooldown: (account) => {
-          deps.rememberCooldown(account.ref, account.cooldownUntil, account.cooldownFamilies || null)
+          if (typeof deps.rememberCooldown === 'function') deps.rememberCooldown(account.ref, account.cooldownUntil, account.cooldownFamilies || null)
           if (typeof deps.recordSwitch === 'function') deps.recordSwitch(account.ref)
         },
         streamOnce: async function* (account, opts) {
@@ -190,6 +193,15 @@ export class SubscriptionAdapter extends LlmAdapter {
       }
       return
     } catch (err) {
+      // #349: opt-in cascading cross-vendor fallback when all accounts are exhausted
+      if (!yieldedAny && typeof deps.cascadingFallback === 'function') {
+        try {
+          yield* deps.cascadingFallback({ options, provider, err })
+          return
+        } catch (cascadeErr) {
+          /* proceed to ollama fallback or error rethrow */
+        }
+      }
       // #91: when the whole pool is exhausted and nothing has been streamed
       // yet, continue seamlessly on local Ollama instead of failing the chat.
       if (!yieldedAny && typeof deps.ollamaFallback === 'function') {

package/lib/alerts.js

@@ -0,0 +1,147 @@
+// #351: Proactive Quota Alerts & Webhook Dispatcher
+// Manages quota threshold warnings, session expiry notifications,
+// and webhook dispatch (e.g. Telegram/Discord or external monitoring).
+
+const MAX_ALERTS = 100
+const DEDUP_WINDOW_MS = 10 * 60 * 1000 // 10 minutes cooldown per (ref + type)
+
+const alertBuffer = []
+const lastAlertTime = new Map()
+
+export function clearAlertsForTesting() {
+  alertBuffer.length = 0
+  lastAlertTime.clear()
+}
+
+/**
+ * Records an alert into the in-memory buffer with deduplication.
+ * @returns {object|null} the created alert, or null if deduped
+ */
+export function recordAlert({ type, ref, provider, message, severity = 'warn', details = null, nowMs = Date.now() }) {
+  const dedupKey = `${type}:${ref || provider}`
+  const prev = lastAlertTime.get(dedupKey) || 0
+  if (nowMs - prev < DEDUP_WINDOW_MS) {
+    return null // Deduplicate to avoid alert floods
+  }
+  lastAlertTime.set(dedupKey, nowMs)
+
+  const alert = {
+    id: `alt_${nowMs.toString(36)}_${Math.random().toString(36).slice(2, 6)}`,
+    type,
+    ref: ref || null,
+    provider: provider || 'unknown',
+    message: String(message || ''),
+    severity,
+    details,
+    timestamp: nowMs,
+  }
+
+  alertBuffer.push(alert)
+  if (alertBuffer.length > MAX_ALERTS) {
+    alertBuffer.shift()
+  }
+  return alert
+}
+
+/**
+ * Returns recent alerts from the in-memory buffer.
+ */
+export function getRecentAlerts(limit = 50) {
+  return alertBuffer.slice(-Math.max(1, Math.min(limit, MAX_ALERTS))).reverse()
+}
+
+/**
+ * Dispatches an alert asynchronously to an external webhookUrl if provided.
+ */
+export async function dispatchWebhookAlert(alert, webhookUrl, fetchImpl = fetch) {
+  if (!alert || !webhookUrl || typeof webhookUrl !== 'string' || !webhookUrl.startsWith('http')) {
+    return false
+  }
+
+  const payload = {
+    event: 'subscription_alert',
+    alert,
+    source: 'dsh-subscriptions',
+    sentAt: new Date().toISOString(),
+  }
+
+  try {
+    const res = await fetchImpl(webhookUrl, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'user-agent': 'dsh-subscriptions/0.6.17',
+      },
+      body: JSON.stringify(payload),
+    })
+    return res.ok
+  } catch (err) {
+    // Non-blocking fire-and-forget
+    return false
+  }
+}
+
+/**
+ * Evaluates used percent against configured thresholds and fires alerts if triggered.
+ */
+export function checkQuotaThresholds({
+  ref,
+  provider,
+  usedPercent,
+  thresholds = [80, 90, 95],
+  webhookUrl = '',
+  fetchImpl = fetch,
+  nowMs = Date.now(),
+}) {
+  const pct = Number(usedPercent) || 0
+  if (pct <= 0) return null
+
+  // Find the highest threshold that was exceeded
+  const sorted = [...thresholds].sort((a, b) => b - a)
+  const matchedThreshold = sorted.find((th) => pct >= th)
+  if (!matchedThreshold) return null
+
+  const severity = pct >= 95 ? 'error' : 'warn'
+  const message = `[Quota Alert] ${provider || 'Account'} (${ref || 'slot'}) has reached ${Math.round(pct)}% used (threshold: ${matchedThreshold}%)`
+
+  const alert = recordAlert({
+    type: 'quota_threshold',
+    ref,
+    provider,
+    message,
+    severity,
+    details: { usedPercent: pct, threshold: matchedThreshold },
+    nowMs,
+  })
+
+  if (alert && webhookUrl) {
+    dispatchWebhookAlert(alert, webhookUrl, fetchImpl).catch(() => {})
+  }
+  return alert
+}
+
+/**
+ * Fires an alert when a session token expires or is revoked.
+ */
+export function notifySessionExpired({
+  ref,
+  provider,
+  message,
+  webhookUrl = '',
+  fetchImpl = fetch,
+  nowMs = Date.now(),
+}) {
+  const alert = recordAlert({
+    type: 'token_expired',
+    ref,
+    provider,
+    message: message || `Session for ${provider || 'account'} (${ref || 'slot'}) has expired and requires re-authentication.`,
+    severity: 'error',
+    nowMs,
+  })
+
+  if (alert && webhookUrl) {
+    dispatchWebhookAlert(alert, webhookUrl, fetchImpl).catch(() => {})
+  }
+  return alert
+}

package/lib/cascade.js

@@ -0,0 +1,51 @@
+// #349: Cascading Cross-Vendor Fallback Engine
+// When a primary vendor's accounts are all exhausted (or return 429/503),
+// route seamlessly to a compatible alternative vendor.
+
+export const DEFAULT_CASCADE_CHAINS = {
+  claude: ['copilot', 'cursor', 'antigravity'],
+  codex: ['copilot', 'cursor'],
+  grok: ['copilot', 'antigravity'],
+  copilot: ['cursor', 'codex'],
+  cursor: ['copilot', 'claude'],
+  antigravity: ['copilot', 'claude'],
+}
+
+/**
+ * Resolves the next candidate fallback provider from the cascade chain.
+ * @param {string} currentProvider - currently failing provider
+ * @param {Set<string>|Array<string>} availableProviders - providers that currently have logged-in accounts
+ * @param {Record<string, string[]>} [customChains] - user-configured custom chains
+ * @param {Set<string>} [visited] - set of already attempted providers in this request cascade
+ * @returns {string|null} - the next candidate provider or null if none available
+ */
+export function resolveFallbackVendor(currentProvider, availableProviders, customChains = {}, visited = new Set()) {
+  const availSet = new Set(availableProviders || [])
+  const chain = (customChains && customChains[currentProvider]) || DEFAULT_CASCADE_CHAINS[currentProvider] || []
+
+  for (const candidate of chain) {
+    if (candidate !== currentProvider && !visited.has(candidate) && availSet.has(candidate)) {
+      return candidate
+    }
+  }
+  return null
+}
+
+/**
+ * Maps a model identifier across vendors if needed.
+ * @param {string} sourceProvider
+ * @param {string} sourceModel
+ * @param {string} targetProvider
+ * @returns {string} target model name
+ */
+export function mapFallbackModel(sourceProvider, sourceModel, targetProvider) {
+  const model = String(sourceModel || '').toLowerCase()
+  // If fallback to copilot/cursor from claude, prefer claude-compatible tag if requested
+  if ((targetProvider === 'copilot' || targetProvider === 'cursor') && model.includes('claude')) {
+    return 'claude-3-5-sonnet'
+  }
+  if (targetProvider === 'codex' && model.includes('claude')) {
+    return 'gpt-4o'
+  }
+  return sourceModel
+}

package/lib/client.js

@@ -1226,6 +1226,38 @@ const cssId = 'dsh-subscriptions/settings.module.css'
             React.createElement('div', { className: 'dsub-stat-lbl' }, t('statsLastActivity')),
           ),
         ) : null,
+        accounts && accounts.length ? React.createElement('details', { className: 'dsub-group', open: true, style: { marginBottom: '14px' } },
+          React.createElement('summary', { className: 'dsub-groupHead' }, '📊 ' + (t('healthMatrix') || 'Health Matrix & Quota Runway')),
+          React.createElement('div', { style: { padding: '8px 0', overflowX: 'auto' } },
+            React.createElement('table', { style: { width: '100%', fontSize: '12px', borderCollapse: 'collapse' } },
+              React.createElement('thead', null,
+                React.createElement('tr', { style: { borderBottom: '1px solid var(--dsw-alias-border-primary, rgba(255,255,255,0.1))', textAlign: 'left', opacity: 0.7 } },
+                  React.createElement('th', { style: { padding: '6px' } }, 'Account'),
+                  React.createElement('th', { style: { padding: '6px' } }, 'Health'),
+                  React.createElement('th', { style: { padding: '6px' } }, 'Latency'),
+                  React.createElement('th', { style: { padding: '6px' } }, 'Status'),
+                  React.createElement('th', { style: { padding: '6px' } }, 'Quota / Runway'),
+                ),
+              ),
+              React.createElement('tbody', null,
+                accounts.map((acc, idx) => {
+                  const sc = acc.healthScore != null ? acc.healthScore : 100
+                  const healthColor = sc >= 80 ? '#10b981' : (sc >= 50 ? '#f59e0b' : '#ef4444')
+                  const isQ = acc.status === 'quarantine' || (acc.quarantineUntil && Number(acc.quarantineUntil) > Date.now())
+                  const statusLabel = isQ ? '⛔ Quarantine' : (acc.status === 'probing' ? '🟡 Warmup' : (acc.configured ? '🟢 Active' : '⚪ Idle'))
+                  const pct = acc.usagePercent != null ? Math.round(acc.usagePercent) : null
+                  return React.createElement('tr', { key: (acc.ref || acc.provider + acc.index || idx), style: { borderBottom: '1px solid var(--dsw-alias-border-secondary, rgba(255,255,255,0.05))' } },
+                    React.createElement('td', { style: { padding: '6px', fontWeight: 600 } }, (acc.provider ? acc.provider.toUpperCase() : 'LLM') + ' #' + (acc.index || 1) + (acc.label ? ' (' + acc.label + ')' : '')),
+                    React.createElement('td', { style: { padding: '6px', color: healthColor } }, sc + '%'),
+                    React.createElement('td', { style: { padding: '6px' } }, acc.latencyMs ? acc.latencyMs + ' ms' : '—'),
+                    React.createElement('td', { style: { padding: '6px' } }, statusLabel),
+                    React.createElement('td', { style: { padding: '6px' } }, pct != null ? (pct + '% used') : '—'),
+                  )
+                }),
+              ),
+            ),
+          ),
+        ) : null,
         React.createElement('div', { className: 'dsub-block' },
           React.createElement('div', { className: 'dsub-h' }, t('title')),
           React.createElement('div', { className: 'dsub-sub' },

package/lib/config-schema.js

@@ -67,6 +67,16 @@ export const Config = z.object({
   antigravityClientSecret: z.string().default('')
     .description('Google Cloud OAuth Client Secret for Antigravity.'),
   antigravityRedirectUri: z.string().default(''),
+    cascadingFallback: z.boolean().default(false)
+    .description('#349 Opt-in cross-vendor fallback when all accounts of a provider are exhausted or rate limited.'),
+  cascadingChain: z.any().default({})
+    .description('#349 Custom cross-vendor fallback chains (e.g. { claude: ["copilot", "cursor"] }).'),
+  webhookUrl: z.string().default('')
+    .description('#351 External webhook URL to receive quota and session alerts (JSON POST).'),
+  alertThresholds: z.array(z.number()).default([80, 90, 95])
+    .description('#351 Quota usage percentage thresholds for firing alerts.'),
+  autoPacing: z.boolean().default(true)
+    .description('#352 Predictive burn-rate load balancing between accounts.'),
   customVendors: z.array(z.any()).default([])
     .description('Declarative OpenAI-Responses-compatible providers. See README.'),
 })

package/lib/forecast.js

@@ -69,3 +69,45 @@ export function estimateForecast(state, key, remainingPercent, resetsAt, now) {
     sampleCount: samples.length,
   }
 }
+
+// #352: Burn-rate calculation & Pacing risk estimator
+export function calculateBurnRatePerHour(samples, now = Date.now()) {
+  if (!Array.isArray(samples) || samples.length < 2) return 0
+  const recent = samples.filter((s) => s.at >= now - 6 * HOUR_MS)
+  if (recent.length < 2) return 0
+  const first = recent[0]
+  const last = recent[recent.length - 1]
+  const hours = (last.at - first.at) / HOUR_MS
+  if (hours <= 0.05) return 0
+  const consumed = Math.max(0, first.pct - last.pct)
+  return consumed / hours
+}
+
+export function computePacingRisk(remainingPercent, pacePerHour, resetsAt, now = Date.now()) {
+  const rem = Number(remainingPercent) || 0
+  const pace = Number(pacePerHour) || 0
+  if (pace <= 0.02 || rem <= 0) {
+    return { pacePerHour: 0, hoursUntilExhaustion: Infinity, survivesReset: true, pacingRisk: 0 }
+  }
+
+  const hoursUntilExhaustion = rem / pace
+  const reset = Number(resetsAt) || 0
+  if (reset > now) {
+    const hoursUntilReset = (reset - now) / HOUR_MS
+    if (hoursUntilExhaustion < hoursUntilReset) {
+      // Risk: will exhaust before reset
+      const deficitHours = hoursUntilReset - hoursUntilExhaustion
+      const pacingRisk = Math.min(100, Math.round(deficitHours * 25))
+      return { pacePerHour: pace, hoursUntilExhaustion, survivesReset: false, pacingRisk }
+    } else {
+      return { pacePerHour: pace, hoursUntilExhaustion, survivesReset: true, pacingRisk: 0 }
+    }
+  }
+
+  return {
+    pacePerHour: pace,
+    hoursUntilExhaustion,
+    survivesReset: null,
+    pacingRisk: hoursUntilExhaustion < 1 ? 50 : 0,
+  }
+}

package/lib/http.js

@@ -42,7 +42,35 @@ export function isLoopback(value) {
  * @returns {boolean}
  * Reject cross-site writes. Do not require loopback: Web UI is used over LAN and reverse proxies. */
 export function isTrustedSettingsRequest(request) {
-  return request.headers['sec-fetch-site'] !== 'cross-site'
+  const headers = request?.headers || {}
+  const secFetchSite = headers['sec-fetch-site']
+  if (secFetchSite) {
+    return secFetchSite !== 'cross-site'
+  }
+  const host = headers.host || headers['x-forwarded-host']
+  const origin = headers.origin
+  if (origin) {
+    try {
+      const u = new URL(origin)
+      if (host && u.host.toLowerCase() !== host.toLowerCase()) {
+        return false
+      }
+    } catch {
+      return false
+    }
+  }
+  const referer = headers.referer
+  if (!origin && referer) {
+    try {
+      const u = new URL(referer)
+      if (host && u.host.toLowerCase() !== host.toLowerCase()) {
+        return false
+      }
+    } catch {
+      return false
+    }
+  }
+  return true
 }
 
 export function queryOf(req) {

package/lib/index.js

@@ -26,13 +26,25 @@ import { OllamaAdapter, ollamaAlive, ollamaModels, ollamaBase } from './ollama.j
 import { createResetCreditService } from './reset-credits.js'
 import { maskEmail, maskLabel, maskText } from './mask.js'
 import { proxyFetch, pickFetch } from './proxy.js'
-import { HistoryStore } from './history.js'
+import { HistoryStore, DEFAULT_HISTORY_DIR } from './history.js'
+export { observeForecast, estimateForecast } from './forecast.js'
+export { formatRelativeReset } from './relative-time.js'
 import {
   inspectGoogleAccount,
   antigravityMetadata,
   antigravityIdentityHeaders,
 } from './code-assist.js'
 
+import { resolveFallbackVendor, mapFallbackModel, DEFAULT_CASCADE_CHAINS } from './cascade.js'
+import { exportVault, importVault } from './vault.js'
+import { recordAlert, getRecentAlerts, checkQuotaThresholds, notifySessionExpired } from './alerts.js'
+import { calculateBurnRatePerHour, computePacingRisk } from './forecast.js'
+import { needsWarmupProbe, enterProbing, resolveWarmupSuccess, resolveWarmupFailure } from './quarantine.js'
+export { resolveFallbackVendor, mapFallbackModel, DEFAULT_CASCADE_CHAINS } from './cascade.js'
+export { exportVault, importVault } from './vault.js'
+export { recordAlert, getRecentAlerts, checkQuotaThresholds, notifySessionExpired } from './alerts.js'
+export { calculateBurnRatePerHour, computePacingRisk } from './forecast.js'
+export { needsWarmupProbe, enterProbing, resolveWarmupSuccess, resolveWarmupFailure } from './quarantine.js'
 export const name = '@goodandready/dsh-subscriptions'
 export const inject = ['llm', 'credentials', 'webServer', 'settings']
 
@@ -116,7 +128,7 @@ export function apply(ctx, config) {
       bestEffort('emit limit-notice', () => ctx.emit && ctx.emit('subscriptions.limit-notice', { provider, ref, window: win.id, usedPercent: win.usedPercent, threshold }), undefined, logger)
     },
   })
-  const history = new HistoryStore()
+  const history = new HistoryStore(DEFAULT_HISTORY_DIR, 7 * 24 * 60 * 60 * 1000, 1000)
   const recordHistory = (entry) => history.add(entry)
 
   // #85: host-only reset credit service for Codex accounts.
@@ -186,6 +198,7 @@ export function apply(ctx, config) {
     fetchImpl: fetch,
     fetchForRef,
     ollamaFallback: ollamaFallbackStream,
+    cascadingFallback: cascadeFallbackStream,
     hideDeprecatedModels: () => !!live().hideDeprecatedModels,
   })
 
@@ -230,6 +243,31 @@ export function apply(ctx, config) {
     },
   }), 'dsh-subscriptions: image generation service')
   const pending = new Map()
+    async function* cascadeFallbackStream({ options, provider, err }) {
+    const cfg = live()
+    if (!cfg.cascadingFallback) throw err
+    const logged = await store.loggedInProviders()
+    const available = Object.keys(logged || {}).filter((p) => logged[p] && p !== provider)
+    const nextVendor = resolveFallbackVendor(provider, available, cfg.cascadingChain)
+    if (!nextVendor) throw err
+    const targetModel = mapFallbackModel(provider, options && options.model, nextVendor)
+    if (logger && logger.warn) {
+      logger.warn('[dsh-subscriptions] ' + provider + ': all accounts exhausted, cascading fallback to ' + nextVendor + '/' + targetModel)
+    }
+    try {
+      recordHistory({
+        provider: nextVendor,
+        ref: String(nextVendor).toUpperCase() + '_CASCADE_FALLBACK',
+        model: targetModel,
+        path: '/v1/chat/completions',
+        method: 'POST',
+        status: 200,
+        kind: 'cascade',
+      })
+    } catch (e) { /* ignore cascade history recording error */ }
+    yield* adapter.stream({ ...options, provider: nextVendor, model: targetModel })
+  }
+
   const adapter = new SubscriptionAdapter({
     listAccounts: (provider) => store.listAccounts(provider),
     loadBlob: (ref) => store.loadBlob(ref),
@@ -324,18 +362,24 @@ export function apply(ctx, config) {
       const existing = normalizeSlots(live().slots)
       const existingRefs = new Set(existing.map((s) => s.ref))
       const candidateProviders = PROVIDERS.filter((p) => isProvider(p))
-      const additions = []
-
+      const candidates = []
       for (const provider of candidateProviders) {
         for (let index = 1; index <= 10; index++) {
           const ref = oauthRef(provider, index)
-          if (existingRefs.has(ref)) continue
+          if (!existingRefs.has(ref)) {
+            candidates.push({ provider, index, ref })
+          }
+        }
+      }
+
+      const additionResults = await Promise.all(
+        candidates.map(async ({ provider, index, ref }) => {
           let d
           try {
             d = await creds.describe(credentialRef(ref))
           } catch (err) {
             if (logger && logger.debug) logger.debug(`[dsh-subscriptions reconcile] describe ${ref} error: ` + (err && err.message || err))
-            continue
+            return null
           }
           if (d && d.configured) {
             let label = d.label || ''
@@ -347,10 +391,12 @@ export function apply(ctx, config) {
             } catch (loadErr) {
               if (logger && logger.debug) logger.debug(`[dsh-subscriptions reconcile] loadBlob ${ref} error: ` + (loadErr && loadErr.message || loadErr))
             }
-            additions.push({ provider, index, label })
+            return { provider, index, label }
           }
-        }
-      }
+          return null
+        })
+      )
+      const additions = additionResults.filter(Boolean)
 
       if (!additions.length) return
       if (logger && logger.info) {
@@ -700,7 +746,7 @@ export function apply(ctx, config) {
           const vendor = getVendor(slot.provider)
           if (typeof vendor.check !== 'function') continue
           const cfg2 = vendorConfig(slot.provider, live())
-          const probeFetch = async (u, i) => fetch(u, i)
+          const probeFetch = async (u, i) => ((typeof fetchForRef === 'function' && fetchForRef(ref)) || fetch)(u, i)
           await vendor.check(fresh, cfg2, probeFetch).catch((e) => {
             if (logger && logger.warn) logger.warn("[dsh-subscriptions] probe " + ref + ": " + String(e && e.message || e).slice(0, 200))
           })

package/lib/quarantine.js

@@ -1,7 +1,12 @@
+// #350: Self-healing & Warm-up probe before returning from quarantine.
 export const REASON_RATE_LIMIT = 'RATE_LIMIT'
 export const REASON_HARD_LIMIT = 'HARD_LIMIT'
 export const REASON_REVOKED = 'TOKEN_REVOKED'
 
+export const STATUS_ACTIVE = 'active'
+export const STATUS_QUARANTINE = 'quarantine'
+export const STATUS_PROBING = 'probing'
+
 export function quarantineDuration(reason) {
   switch (reason) {
     case REASON_HARD_LIMIT:
@@ -20,12 +25,64 @@ export function putInQuarantine(account, reason, nowMs = Date.now()) {
     ...account,
     quarantineReason: reason,
     quarantineUntil: nowMs + duration,
-    status: 'quarantine'
+    status: STATUS_QUARANTINE,
   }
 }
 
 export function isQuarantined(account, nowMs = Date.now()) {
-  if (!account || !account.quarantineUntil) return false
+  if (!account) return false
+  if (account.status === STATUS_PROBING) return true
+  if (!account.quarantineUntil) return false
   return Number(account.quarantineUntil) > Number(nowMs)
 }
 
+/**
+ * Checks whether an account has expired its quarantine period and needs a warm-up probe.
+ */
+export function needsWarmupProbe(account, nowMs = Date.now()) {
+  if (!account) return false
+  const until = Number(account.quarantineUntil) || 0
+  if (until === 0) return false
+  return until <= Number(nowMs) && (account.status === STATUS_QUARANTINE || account.status === STATUS_PROBING)
+}
+
+/**
+ * Transitions account to probing state for warm-up.
+ */
+export function enterProbing(account) {
+  return {
+    ...account,
+    status: STATUS_PROBING,
+  }
+}
+
+/**
+ * Restores an account back to active service after a successful warm-up probe.
+ */
+export function resolveWarmupSuccess(account, nowMs = Date.now()) {
+  return {
+    ...account,
+    status: STATUS_ACTIVE,
+    quarantineUntil: 0,
+    quarantineReason: null,
+    quarantineAttempts: 0,
+    probePassedAt: nowMs,
+  }
+}
+
+/**
+ * Extends quarantine with exponential backoff if warmup probe failed.
+ */
+export function resolveWarmupFailure(account, reason, nowMs = Date.now()) {
+  const baseDuration = quarantineDuration(reason || account?.quarantineReason || REASON_RATE_LIMIT)
+  const attempts = Math.min((Number(account?.quarantineAttempts) || 1) * 2, 8)
+  const extendedDuration = Math.min(baseDuration * attempts, 48 * 60 * 60 * 1000) // max 48h
+  return {
+    ...account,
+    status: STATUS_QUARANTINE,
+    quarantineReason: reason || account?.quarantineReason || REASON_RATE_LIMIT,
+    quarantineUntil: nowMs + extendedDuration,
+    quarantineAttempts: attempts,
+    probeFailedAt: nowMs,
+  }
+}

package/lib/reset-credits.js

@@ -64,6 +64,14 @@ export function parseConsumeResult(raw) {
 export function createResetCreditService({ loadBlob, fetchImpl, now = Date.now, randomId = randomUUID }) {
   const challenges = new Map()
 
+  function pruneChallenges(nowMs = now()) {
+    for (const [id, ch] of challenges.entries()) {
+      if (nowMs > ch.expiresAt) {
+        challenges.delete(id)
+      }
+    }
+  }
+
   async function readDetails(ref) {
     const blob = await loadBlob(ref)
     const access = blob && blob.accessToken
@@ -101,6 +109,7 @@ export function createResetCreditService({ loadBlob, fetchImpl, now = Date.now,
     async prepare(ref) {
       const { accountId, details } = await readDetails(ref)
       const preparedAt = now()
+      pruneChallenges(preparedAt)
       const readyAt = preparedAt + CONFIRM_DELAY_MS
       const expiresAt = Math.min(preparedAt + CHALLENGE_TTL_MS, details.creditExpiresAt === undefined ? Number.MAX_SAFE_INTEGER : details.creditExpiresAt)
       if (expiresAt <= readyAt) throw new Error('the available reset expires too soon')

package/lib/rotate.js

@@ -112,6 +112,11 @@ export function pickAccount(accounts, nowMs, opts) {
   for (const tier of tiers) {
     if (tier.length) {
       tier.sort((a, b) => {
+        // 0. Auto-Pacing: lower pacing risk preferred (#352)
+        const aRisk = Number(a.pacingRisk) || 0
+        const bRisk = Number(b.pacingRisk) || 0
+        if (Math.abs(aRisk - bRisk) >= 20) return aRisk - bRisk
+
         // 1. Least Remaining Window (#167)
         if (a.quota && b.quota && a.quota.resetAt && b.quota.resetAt) {
           const aReset = Number(a.quota.resetAt)

package/lib/routes/accounts.js

@@ -1,3 +1,4 @@
+import { exportVault, importVault } from '../vault.js'
 import { normalizeSlots } from '../accounts.js'
 import { Config, publicConfig } from '../config-schema.js'
 import { decryptWithPassphrase, encryptWithPassphrase } from '../crypto.js'
@@ -339,4 +340,102 @@ export function registerAccountsRoutes(ctx, state) {
       }
     }),
   }), 'dsh-subscriptions: /logout')
+
+  // #353: Encrypted Vault export
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/vault/export',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'POST') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'POST only' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'same-origin only' } })
+        return
+      }
+      let payload
+      try { payload = JSON.parse((await readBody(req, 8 * 1024)).toString('utf8') || '{}') } catch {
+        writeJson(res, 400, { ok: false, error: { code: 'json', message: 'invalid json' } })
+        return
+      }
+      const passphrase = payload.passphrase
+      try {
+        const slots = live().slots || []
+        const blobs = {}
+        for (const slot of normalizeSlots(slots)) {
+          try {
+            const blob = await store.loadBlob(slot.ref)
+            if (blob) blobs[slot.ref] = blob
+          } catch { /* ignore */ }
+        }
+        const result = exportVault({ slots, blobs }, passphrase)
+        writeJson(res, 200, result)
+      } catch (e) {
+        writeJson(res, 400, { ok: false, error: { code: 'vault_export', message: String(e && e.message || e) } })
+      }
+    }),
+  }), 'dsh-subscriptions: /vault/export')
+
+  // #353: Encrypted Vault import
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/vault/import',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'POST') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'POST only' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'same-origin only' } })
+        return
+      }
+      let payload
+      try { payload = JSON.parse((await readBody(req, 2 * 1024 * 1024)).toString('utf8') || '{}') } catch {
+        writeJson(res, 400, { ok: false, error: { code: 'json', message: 'invalid json' } })
+        return
+      }
+      const { passphrase, vault } = payload
+      try {
+        const result = importVault(vault, passphrase)
+        // Save imported blobs
+        let blobCount = 0
+        if (result.blobs && typeof result.blobs === 'object') {
+          for (const [ref, blob] of Object.entries(result.blobs)) {
+            try {
+              await store.saveBlob(ref, blob)
+              blobCount++
+            } catch { /* ignore */ }
+          }
+        }
+        // Merge imported slots into configuration
+        if (Array.isArray(result.slots) && result.slots.length && getSettingsApi()) {
+          const curSlots = Array.isArray(live().slots) ? live().slots.slice() : []
+          for (const s of result.slots) {
+            const idx = curSlots.findIndex((c) => c.provider === s.provider && Number(c.index) === Number(s.index))
+            if (idx >= 0) {
+              curSlots[idx] = { ...curSlots[idx], ...s }
+            } else {
+              curSlots.push(s)
+            }
+          }
+          const parsed = Config({ ...live(), slots: stripLegacySlots(curSlots) })
+          await getSettingsApi().replace(parsed)
+          syncCustomVendors()
+        }
+        await syncAdapter()
+        refreshModels().catch(() => {})
+        writeJson(res, 200, {
+          ok: true,
+          slotCount: result.slots.length,
+          blobCount,
+          exportedAt: result.exportedAt,
+          accounts: await accountsView(),
+        })
+      } catch (e) {
+        writeJson(res, 400, { ok: false, error: { code: 'vault_import', message: String(e && e.message || e) } })
+      }
+    }),
+  }), 'dsh-subscriptions: /vault/import')
+
 }

package/lib/routes/status.js

@@ -1,3 +1,4 @@
+import { getRecentAlerts } from '../alerts.js'
 import { normalizeSlots, vendorConfig } from '../accounts.js'
 import { Config, publicConfig } from '../config-schema.js'
 import { isTrustedSettingsRequest, queryOf, readBody, safeJsonHandler, writeJson } from '../http.js'
@@ -18,6 +19,7 @@ export function registerStatusRoutes(ctx, state) {
     diagnosticsReport,
     pmL = (s) => s,
     pmE = (s) => s,
+    fetchForRef,
   } = state
 
   async function configResponse() {
@@ -213,7 +215,8 @@ export function registerStatusRoutes(ctx, state) {
       const probeFetch = async (url, init = {}) => {
         const timeoutSignal = AbortSignal.timeout(15_000)
         const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal
-        const res2 = await fetch(url, { ...init, signal })
+        const doFetch = (typeof fetchForRef === "function" && fetchForRef(ref)) || fetch
+        const res2 = await doFetch(url, { ...init, signal })
         try {
           const snap = quotaSnapshot(provider, res2.headers, null, Date.now())
           if (snap) { capturedQuota = snap; store.rememberQuota(ref, snap) }
@@ -327,7 +330,8 @@ export function registerStatusRoutes(ctx, state) {
         const probeFetch = async (url, init = {}) => {
           const timeoutSignal = AbortSignal.timeout(15_000)
           const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal
-          const res2 = await fetch(url, { ...init, signal })
+          const doFetch = (typeof fetchForRef === "function" && fetchForRef(ref)) || fetch
+          const res2 = await doFetch(url, { ...init, signal })
           try {
             const snap = quotaSnapshot(provider, res2.headers, null, Date.now())
             if (snap) { capturedQuota = snap; store.rememberQuota(ref, snap) }
@@ -379,4 +383,19 @@ export function registerStatusRoutes(ctx, state) {
       })
     }),
   }), 'dsh-subscriptions: /smoke')
+
+  // #351: Quota and session alerts API
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/alerts',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'GET') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'GET only' } })
+        return
+      }
+      const limit = Math.min(Number(queryOf(req).get('limit') || '50'), 100)
+      writeJson(res, 200, { ok: true, alerts: getRecentAlerts(limit) })
+    }),
+  }), 'dsh-subscriptions: /alerts')
+
 }

package/lib/session-pin.js

@@ -8,8 +8,19 @@ const DEFAULT_TTL_MS = 30 * 60 * 1000 // 30 mins
  * @param {number} [ttlMs]
  * @returns {void}
  */
+export function pruneSessionPins(now = Date.now()) {
+  for (const [id, entry] of sessionPins.entries()) {
+    if (now > entry.expiresAt) {
+      sessionPins.delete(id)
+    }
+  }
+}
+
 export function pinSession(sessionId, accountRef, ttlMs = DEFAULT_TTL_MS) {
   if (!sessionId || !accountRef) return
+  if (sessionPins.size >= 50) {
+    pruneSessionPins()
+  }
   sessionPins.set(sessionId, {
     accountRef,
     expiresAt: Date.now() + ttlMs

package/lib/stream-rotate.js

@@ -9,6 +9,7 @@ export async function* streamWithRotation({
   streamOnce,
   options,
   onCooldown,
+  cascadeFallback, // #349: optional cross-vendor cascading fallback generator
   offlineFallback, // #174: optional fallback generator if all accounts exhausted
 }) {
   const pool = (accounts || []).map((account) => ({ ...account }))
@@ -25,6 +26,11 @@ export async function* streamWithRotation({
     })
 
     if (!account || tried.has(account.ref || account.id)) {
+      if (cascadeFallback) {
+        // #349 Cascading Cross-Vendor Fallback
+        yield* cascadeFallback(options, lastError)
+        return
+      }
       if (offlineFallback) {
         // #174 Local Mock Server Offline Fallback
         yield* offlineFallback(options, lastError)

package/lib/vault.js

@@ -0,0 +1,74 @@
+// #353: Encrypted Vault Export/Import for Subscriptions
+// Secure migration and backup of slots and credentials using AES-256-GCM.
+
+import { encryptWithPassphrase, decryptWithPassphrase } from './crypto.js'
+
+export const VAULT_FORMAT = 'dsh-subscriptions-vault-v1'
+
+/**
+ * Encrypts slots configuration and credential blobs into a portable vault string.
+ */
+export function exportVault({ slots = [], blobs = {}, exportedBy = 'dsh-subscriptions' }, passphrase) {
+  const pass = String(passphrase || '').trim()
+  if (!pass || pass.length < 4) {
+    throw new Error('passphrase must be at least 4 characters')
+  }
+
+  const payload = {
+    format: VAULT_FORMAT,
+    version: '0.6.17',
+    exportedAt: new Date().toISOString(),
+    exportedBy,
+    slots: Array.isArray(slots) ? slots : [],
+    blobs: blobs && typeof blobs === 'object' ? blobs : {},
+  }
+
+  const encrypted = encryptWithPassphrase(JSON.stringify(payload), pass)
+  return {
+    ok: true,
+    vault: encrypted,
+    slotCount: payload.slots.length,
+    blobCount: Object.keys(payload.blobs).length,
+  }
+}
+
+/**
+ * Decrypts and validates an encrypted vault string.
+ */
+export function importVault(encryptedPayload, passphrase) {
+  const pass = String(passphrase || '').trim()
+  if (!pass) {
+    throw new Error('passphrase is required')
+  }
+
+  const raw = String(encryptedPayload || '').trim()
+  if (!raw.startsWith('DSHE1:')) {
+    throw new Error('invalid vault format: missing DSHE1 header')
+  }
+
+  let jsonStr
+  try {
+    jsonStr = decryptWithPassphrase(raw, pass)
+  } catch (err) {
+    throw new Error('failed to decrypt vault: invalid passphrase or corrupted payload')
+  }
+
+  let data
+  try {
+    data = JSON.parse(jsonStr)
+  } catch (err) {
+    throw new Error('malformed vault content: invalid JSON')
+  }
+
+  if (!data || data.format !== VAULT_FORMAT || !Array.isArray(data.slots) || typeof data.blobs !== 'object') {
+    throw new Error('invalid vault schema: unsupported structure')
+  }
+
+  return {
+    ok: true,
+    slots: data.slots,
+    blobs: data.blobs,
+    version: data.version,
+    exportedAt: data.exportedAt,
+  }
+}

package/lib/vendors/copilot.js

@@ -111,6 +111,85 @@ export async function pollDeviceToken(deviceCode, fetchImpl) {
   return readJson(res)
 }
 
+
+export async function deviceStart(cfg, fetchImpl) {
+  const json = await requestDeviceCode(fetchImpl)
+  if (!json || !json.user_code || !json.device_code) {
+    throw httpError(502, "GitHub device code response is incomplete", "DEVICE")
+  }
+  return {
+    userCode: json.user_code,
+    deviceAuthId: json.device_code,
+    intervalMs: Math.max(parseInt(json.interval, 10) || 5, 1) * 1000,
+    authUrl: json.verification_uri || "https://github.com/login/device",
+  }
+}
+
+export async function devicePoll(cfg, session, fetchImpl) {
+  const impl = fetchImpl || fetch
+  let json
+  try {
+    json = await pollDeviceToken(session.deviceAuthId, impl)
+  } catch (err) {
+    throw httpError(502, String(err && err.message || err), "DEVICE")
+  }
+  if (json.error === "authorization_pending" || json.error === "slow_down") {
+    return { status: "pending" }
+  }
+  if (json.error) {
+    throw httpError(400, json.error_description || json.error, "DEVICE")
+  }
+  if (!json.access_token) {
+    return { status: "pending" }
+  }
+  const githubToken = json.access_token
+  const exchange = await exchangeCopilotToken(githubToken, impl)
+  const copilotToken = exchange && exchange.token
+  const expiresAt = exchange && exchange.expires_at ? exchange.expires_at * 1000 : Date.now() + 30 * 60 * 1000
+
+  let label = "copilot"
+  let email = ""
+  try {
+    const userRes = await impl(COPILOT_USER_URL, {
+      headers: {
+        Authorization: `Bearer ${githubToken}`,
+        "User-Agent": "GitHubCopilotChat/0.24.0",
+      },
+    })
+    if (userRes.ok) {
+      const user = await readJson(userRes)
+      if (user && user.login) {
+        label = user.login
+        if (user.email) email = user.email
+      }
+    }
+  } catch { /* best-effort */ }
+
+  return {
+    status: "authorized",
+    blob: {
+      accessToken: copilotToken || githubToken,
+      refreshToken: githubToken,
+      githubToken,
+      expiresAt,
+      label,
+      email,
+    },
+  }
+}
+
+export async function refresh(cfg, blob, fetchImpl) {
+  const impl = fetchImpl || fetch
+  const githubToken = blob && (blob.refreshToken || blob.githubToken)
+  if (!githubToken) return blob
+  const exchange = await exchangeCopilotToken(githubToken, impl)
+  return {
+    ...blob,
+    accessToken: exchange.token || blob.accessToken,
+    expiresAt: exchange.expires_at ? exchange.expires_at * 1000 : Date.now() + 30 * 60 * 1000,
+  }
+}
+
 export async function exchangeCopilotToken(githubToken, fetchImpl) {
   const impl = fetchImpl || fetch
   const res = await impl(COPILOT_TOKEN_URL, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-subscriptions",
-  "version": "0.6.15",
+  "version": "0.6.17",
   "description": "Use ChatGPT Codex, Claude, Grok, Antigravity, Kimi, GLM, Cursor, Kiro, Copilot, Qwen, ERNIE, Spark, JetBrains, Perplexity, Replit, and Cody subscriptions as DeepSeek Harness LLM providers via OAuth.",
   "license": "MIT",
   "type": "module",