@goodandready/dsh-subscriptions 0.6.16 → 0.6.18

package/lib/adapter.js

@@ -7,6 +7,7 @@ import { streamWithRotation } from './stream-rotate.js'
 import { pickFetch } from './proxy.js'
 import { quotaSnapshot, parseBody } from './ratelimit.js'
 import { toTokenUsage } from './wire.js'
+import { isSwitchableError } from './rotate.js'
 
 // #94: heuristic for test/preview/beta/legacy model ids.
 function isDeprecatedId(id) {
@@ -93,7 +94,7 @@ export class SubscriptionAdapter extends LlmAdapter {
     }
   }
 
-  async *stream(options) {
+  async *stream(options, visited = new Set()) {
     const provider = options.provider
     const deps = this.deps
     let yieldedAny = false
@@ -193,6 +194,18 @@ export class SubscriptionAdapter extends LlmAdapter {
       }
       return
     } catch (err) {
+      // #349 & #361: opt-in cascading cross-vendor fallback with abort and cycle checks
+      if (!yieldedAny && !options.signal?.aborted && isSwitchableError(err) && typeof deps.cascadingFallback === 'function') {
+        try {
+          for await (const event of deps.cascadingFallback({ options, provider, err, visited })) {
+            yieldedAny = true
+            yield event
+          }
+          return
+        } catch (cascadeErr) {
+          err = cascadeErr
+        }
+      }
       // #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

@@ -493,7 +493,17 @@ const cssId = 'dsh-subscriptions/settings.module.css'
       "updateNow": "Update",
       "updating": "Updating…",
       "updateSuccessRestart": "Update complete. Restarting service…",
-      "updateFailed": "Update failed"
+      "updateFailed": "Update failed",
+      "healthMatrix": "Health Matrix & Quota Runway",
+      "healthAccount": "Account",
+      "healthScore": "Health",
+      "healthLatency": "Latency",
+      "healthStatus": "Status",
+      "healthQuota": "Quota / Runway",
+      "healthQuarantine": "Quarantine",
+      "healthWarmup": "Warmup",
+      "healthActive": "Active",
+      "healthIdle": "Idle"
 };
 
     const zh = {
@@ -663,7 +673,17 @@ const cssId = 'dsh-subscriptions/settings.module.css'
       "updateNow": "立即更新",
       "updating": "正在更新…",
       "updateSuccessRestart": "更新成功，服务重启中…",
-      "updateFailed": "更新失败"
+      "updateFailed": "更新失败",
+      "healthMatrix": "健康矩阵与配额预测",
+      "healthAccount": "账户",
+      "healthScore": "健康度",
+      "healthLatency": "延迟",
+      "healthStatus": "状态",
+      "healthQuota": "额度 / 余量",
+      "healthQuarantine": "隔离期",
+      "healthWarmup": "预热中",
+      "healthActive": "活跃",
+      "healthIdle": "空闲"
 };
     // #51: live countdown to the quota window reset (account.quota.resetAt).
                 function cleanErrorMessage(raw) {
@@ -1226,6 +1246,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' } }, t('healthAccount')),
+                  React.createElement('th', { style: { padding: '6px' } }, t('healthScore')),
+                  React.createElement('th', { style: { padding: '6px' } }, t('healthLatency')),
+                  React.createElement('th', { style: { padding: '6px' } }, t('healthStatus')),
+                  React.createElement('th', { style: { padding: '6px' } }, t('healthQuota')),
+                ),
+              ),
+              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 ? ('⛔ ' + t('healthQuarantine')) : (acc.status === 'probing' ? ('🟡 ' + t('healthWarmup')) : (acc.configured ? ('🟢 ' + t('healthActive')) : ('⚪ ' + t('healthIdle'))))
+                  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' },
@@ -1847,7 +1899,7 @@ const cssId = 'dsh-subscriptions/settings.module.css'
             name: 'plugins.item',
             id: ROW_ID,
             order: 60,
-            label: () => 'Subscriptions',
+            label: () => t('title') || 'Subscriptions',
             locale: NS,
             inject: () => ({ ctx: ctx }),
           },

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/index.js

@@ -35,6 +35,16 @@ import {
   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']
 
@@ -188,6 +198,7 @@ export function apply(ctx, config) {
     fetchImpl: fetch,
     fetchForRef,
     ollamaFallback: ollamaFallbackStream,
+    cascadingFallback: cascadeFallbackStream,
     hideDeprecatedModels: () => !!live().hideDeprecatedModels,
   })
 
@@ -232,6 +243,33 @@ export function apply(ctx, config) {
     },
   }), 'dsh-subscriptions: image generation service')
   const pending = new Map()
+    async function* cascadeFallbackStream({ options, provider, err, visited = new Set() }) {
+    const cfg = live()
+    if (!cfg.cascadingFallback) throw err
+    const logged = await store.loggedInProviders()
+    const available = Object.keys(logged || {}).filter((p) => logged[p] && p !== provider)
+    visited.add(provider)
+    const nextVendor = resolveFallbackVendor(provider, available, cfg.cascadingChain, visited)
+    if (!nextVendor) throw err
+    visited.add(nextVendor)
+    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)
+    }
+    yield* adapter.stream({ ...options, provider: nextVendor, model: targetModel }, visited)
+    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 */ }
+  }
+
   const adapter = new SubscriptionAdapter({
     listAccounts: (provider) => store.listAccounts(provider),
     loadBlob: (ref) => store.loadBlob(ref),
@@ -251,6 +289,7 @@ export function apply(ctx, config) {
   })
 
   let handle
+  let adapterDisposed = false
   let registeredByUs = new Set()
   function disposeAdapterHandle(h) {
     if (!h) return
@@ -263,6 +302,7 @@ export function apply(ctx, config) {
   }
 
   async function syncAdapter() {
+    if (adapterDisposed) return
     const desired = await store.loggedInProviders()
     const globalProviders = ctx.llm && typeof ctx.llm.listProviders === 'function'
       ? ctx.llm.listProviders().map((p) => p.id)
@@ -603,11 +643,12 @@ export function apply(ctx, config) {
     let retries = 0
     let retryTimer
     const scheduleRetry = () => {
-      if (retries >= 30) return
+      if (adapterDisposed || retries >= 30) return
       retryTimer = setTimeout(retrySync, 1000)
       if (retryTimer && typeof retryTimer.unref === 'function') retryTimer.unref()
     }
     const retrySync = async () => {
+      if (adapterDisposed) return
       try {
         const loggedIn = await store.loggedInProviders()
         if (!loggedIn.length) return
@@ -646,6 +687,7 @@ export function apply(ctx, config) {
     }
     eager()
     return () => {
+      adapterDisposed = true
       if (retryTimer) clearTimeout(retryTimer)
       if (handle) {
         disposeAdapterHandle(handle)

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/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,101 @@ 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)
+        const settings = getSettingsApi()
+        let parsed
+        if (result.slots.length) {
+          if (!settings) throw new Error('settings are unavailable for vault import')
+          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)
+            }
+          }
+          parsed = Config({ ...live(), slots: stripLegacySlots(curSlots) })
+        }
+        let blobCount = 0
+        for (const [ref, blob] of Object.entries(result.blobs)) {
+          await store.saveBlob(ref, blob)
+          blobCount++
+        }
+        if (parsed) {
+          await settings.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'
@@ -382,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/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,92 @@
+// #353 & #360: Encrypted Vault Export/Import for Subscriptions
+// Secure migration and backup of slots and credentials using AES-256-GCM.
+
+import { encryptWithPassphrase, decryptWithPassphrase } from './crypto.js'
+import { isProvider, oauthRef } from './refs.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.18',
+    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 with strict schema and injection protection.
+ */
+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)
+    || !data.blobs || typeof data.blobs !== 'object' || Array.isArray(data.blobs)) {
+    throw new Error('invalid vault schema: unsupported structure')
+  }
+
+  const refs = new Set()
+  for (const slot of data.slots) {
+    if (!slot || !isProvider(slot.provider) || !Number.isSafeInteger(slot.index) || slot.index < 1) {
+      throw new Error('invalid vault slot')
+    }
+    const ref = oauthRef(slot.provider, slot.index)
+    if (refs.has(ref)) throw new Error('duplicate vault slot')
+    refs.add(ref)
+  }
+
+  for (const [ref, blob] of Object.entries(data.blobs)) {
+    if (!refs.has(ref) || !blob || typeof blob !== 'object' || Array.isArray(blob)) {
+      throw new Error('invalid vault credential: expected a declared slot and an object')
+    }
+  }
+
+  return {
+    ok: true,
+    slots: data.slots,
+    blobs: data.blobs,
+    version: data.version,
+    exportedAt: data.exportedAt,
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-subscriptions",
-  "version": "0.6.16",
+  "version": "0.6.18",
   "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",