@goodandready/dsh-subscriptions 0.6.62 → 0.6.63

package/README.md

@@ -100,6 +100,8 @@ graph LR
 * **Dynamic Cooldown Calculation**: Parses upstream headers (`Retry-After`, `x-ratelimit-reset`, ISO dates, epoch timestamps) and auto-restores cooled-down accounts when their window resets.
 * **Synchronous Decision Tracing & Routing Explanation (#517)**: Real-time decision traces capture every account selection, rotation step, failure reason, and cascade fallback without post-hoc reconstruction, exposed in WebUI telemetry and diagnostics.
 * **Dynamic Model Catalog & Live Quota Visualizer (#507)**: Dynamic model catalog with pool-level health calculation (individual quarantine degrades rather than disables the pool), context window badges, capability tags (`vision`, `tools`, `reasoning`, `coding`, `fast`), and live reset countdowns.
+* **Cache-Aware Session Pinning (#520)**: Retains session affinity for prompt-caching providers (Claude, Codex, Antigravity, Grok) to maximize token cache reuse while strictly releasing pins when an account enters cooldown, quarantine, or quota exhaustion.
+* **Guided Diagnostic Wizard (#519)**: Interactive step-by-step checklist verifying credentials, network/proxy connectivity, token freshness, and model catalog reachability without paid inference and with full secret redaction.
 
 ---
 

package/README.ru.md

@@ -100,6 +100,8 @@ graph LR
 * **Динамический расчёт Cooldown**: парсинг заголовков `Retry-After`, `x-ratelimit-reset`, дат ISO и миллисекундных меток с автоматическим возвратом остывших аккаунтов в строй.
 * **Трассировка решений ротации и объяснение маршрутизации (#517)**: Синхронная фиксация причин выбора аккаунтов, отказов и каскадных переходов в реальном времени с кодами причин без ретроспективной реконструкции; визуализация в телеметрии настроек и диагностике.
 * **Динамический каталог моделей с пуловой доступностью и квотами (#507)**: Обогащенная витрина моделей с расчетом здоровья пула (карантин одного аккаунта не блокирует модель при наличии живых), тегами возможностей (`vision`, `tools`, `reasoning`, `coding`, `fast`), размером контекста и таймером сброса квот.
+* **Cache-Aware Session Pinning (#520)**: Сохранение привязки сессии к подходящему аккаунту для провайдеров с поддержкой кэширования промптов (Claude, Codex, Antigravity, Grok) с гарантированным немедленным освобождением при кулдауне, карантине или исчерпании квоты.
+* **Мастер интерактивной диагностики (#519)**: Пошаговый чек-лист состояния аккаунтов (валидность ключей, прокси, токен, доступность каталога) без платного инференса и с автоматическим маскированием секретов.
 
 ---
 

package/lib/client.js

@@ -594,6 +594,21 @@ const cssId = 'dsh-subscriptions/settings.module.css'
       "forecastRunway": "Estimated runway",
       "forecastBurnRate": "Burn rate",
       "forecastExhaustWarning": "Quota projected to exhaust before reset window",
+      "wizardButton": "Diagnose",
+      "wizardTitle": "Diagnostic Wizard",
+      "wizardAll": "Account Wizard",
+      "wizardIncludeNetwork": "Include active network checks (proxy ping & model catalog discovery)",
+      "wizardRunning": "Running diagnostic checklist...",
+      "wizardStepCreds": "Credentials & Expiry",
+      "wizardStepProxy": "Proxy & Gateway",
+      "wizardStepToken": "Token Validation",
+      "wizardStepCatalog": "Model Catalog Reachability",
+      "wizardHealthy": "Healthy",
+      "wizardDegraded": "Degraded / Warnings",
+      "wizardFailing": "Issues Detected",
+      "wizardRecommendations": "Recommendations & Next Steps",
+      "wizardCopy": "Copy Masked Diagnostic Report",
+      "cachePinnedBadge": "Cache Pinned",
       "field.enableToasts": "Show popup toast notifications on quarantine or quota events"
 };
 
@@ -837,6 +852,21 @@ const cssId = 'dsh-subscriptions/settings.module.css'
       "forecastRunway": "预计可用时间",
       "forecastBurnRate": "消耗速率",
       "forecastExhaustWarning": "预计在额度重置前耗尽",
+      "wizardButton": "诊断",
+      "wizardTitle": "账户诊断向导",
+      "wizardAll": "诊断向导",
+      "wizardIncludeNetwork": "包含活跃网络探测（代理连通性与模型目录探测）",
+      "wizardRunning": "正在执行诊断检查清单...",
+      "wizardStepCreds": "凭据完整性与有效期",
+      "wizardStepProxy": "网络代理与网关",
+      "wizardStepToken": "令牌有效性验证",
+      "wizardStepCatalog": "模型目录可达性",
+      "wizardHealthy": "健康正常",
+      "wizardDegraded": "降级预警",
+      "wizardFailing": "发现故障",
+      "wizardRecommendations": "排查建议与修复步骤",
+      "wizardCopy": "复制脱敏诊断报告",
+      "cachePinnedBadge": "缓存粘性",
       "field.enableToasts": "当账户发生隔离或额度达到警戒线时显示即时弹窗提醒"
 };
     // #51: live countdown to the quota window reset (account.quota.resetAt).
@@ -1071,7 +1101,31 @@ const cssId = 'dsh-subscriptions/settings.module.css'
       const [backupErr, setBackupErr] = React.useState('')
       const [backupInfo, setBackupInfo] = React.useState('')
       const [backupLoading, setBackupLoading] = React.useState(false)
-
+      const [wizardModal, setWizardModal] = React.useState(null)
+
+            const runWizard = async (provider, index, ref, includeNetwork = false) => {
+        setWizardModal({
+          provider: provider || 'all',
+          index: index || 1,
+          ref: ref || null,
+          loading: true,
+          report: null,
+          includeNetwork,
+          error: '',
+        })
+        try {
+          const res = await fetch('/dsh-subscriptions/diagnostic-wizard', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ provider, index, ref, includeNetwork }),
+          })
+          const d = await res.json()
+          if (!d || !d.ok) throw new Error((d && d.error && d.error.message) || ('HTTP ' + res.status))
+          setWizardModal((m) => Object.assign({}, m, { loading: false, report: d.report, error: '' }))
+        } catch (e) {
+          setWizardModal((m) => Object.assign({}, m, { loading: false, error: cleanErrorMessage(e && e.message || e) }))
+        }
+      }
       const doExportBackup = async () => {
         setBackupErr(''); setBackupInfo(''); setBackupLoading(true)
         try {
@@ -1629,7 +1683,7 @@ const cssId = 'dsh-subscriptions/settings.module.css'
           React.createElement('div', { className: 'dsub-sub', style: { marginTop: '4px' } }, t('rotationDecisionsDesc')),
           React.createElement('div', { className: 'dsub-trace-box' },
             telemetry.recentDecisions.map((dec, idx) => {
-              const reasonBadge = dec.cascaded ? ('🔀 ' + t('rotationCascaded')) : (dec.decisionReason === 'session_pinned' ? '📌 Pinned' : ('⚡ ' + dec.decisionReason))
+              const reasonBadge = dec.cascaded ? ('🔀 ' + t('rotationCascaded')) : (dec.decisionReason === 'cache_pinned' ? ('📌 ' + t('cachePinnedBadge')) : (dec.decisionReason === 'session_pinned' ? '📌 Pinned' : ('⚡ ' + dec.decisionReason)))
               return React.createElement('div', { key: idx, className: 'dsub-trace-row' },
                 React.createElement('div', { style: { display: 'flex', alignItems: 'center', gap: '6px' } },
                   dec.provider ? React.createElement('span', { className: 'dsub-brand dsub-brand-' + dec.provider, style: { fontSize: '9px', padding: '1px 4px' } }, dec.provider.toUpperCase()) : null,
@@ -1960,6 +2014,7 @@ const cssId = 'dsh-subscriptions/settings.module.css'
         ),
         React.createElement('div', { className: 'dsub-block' },
           React.createElement('div', { className: 'dsub-row' },
+            React.createElement('button', { type: 'button', className: 'dsub-mini', onClick: () => runWizard(null, null, null, false) }, '🩺 ' + t('wizardAll')),
             React.createElement('button', { type: 'button', className: 'dsub-mini', onClick: genDiag }, t('diagGenerate')),
             React.createElement('button', { type: 'button', className: 'dsub-mini', onClick: runAnalyzeSession }, analyzingCache ? '…' : t('cacheAnalyze')),
             React.createElement('button', { type: 'button', className: 'dsub-mini', onClick: () => { setBackupModal('export'); setBackupErr(''); setBackupInfo('') } }, '🔒 ' + t('backupExport')),
@@ -1978,6 +2033,72 @@ const cssId = 'dsh-subscriptions/settings.module.css'
             }, t('diagCopy')),
             React.createElement('pre', { className: 'dsub-diag' }, diag),
           ) : null,
+          wizardModal ? React.createElement('div', { className: 'dsub-modalWrap', onClick: (e) => { if (e.target === e.currentTarget) setWizardModal(null) } },
+            React.createElement('div', { className: 'dsub-modal' },
+              React.createElement('div', { className: 'dsub-modalHead' },
+                React.createElement('div', { className: 'dsub-modalTitleWrap' },
+                  React.createElement('div', { className: 'dsub-modalIcon' }, '🩺'),
+                  React.createElement('div', null,
+                    React.createElement('div', { style: { fontWeight: 700, fontSize: '15px' } }, t('wizardTitle')),
+                    React.createElement('div', { style: { fontSize: '11.5px', opacity: 0.7 } },
+                      wizardModal.provider && wizardModal.provider !== 'all' ? (wizardModal.provider.toUpperCase() + ' #' + wizardModal.index + (wizardModal.ref ? ' (' + wizardModal.ref + ')' : '')) : t('wizardAll')
+                    ),
+                  ),
+                ),
+                React.createElement('button', { type: 'button', className: 'dsub-mini', onClick: () => setWizardModal(null) }, '✕ ' + t('closeModal')),
+              ),
+              React.createElement('div', { style: { marginTop: '14px' } },
+                React.createElement('label', { className: 'dsub-row', style: { marginBottom: '10px' } },
+                  React.createElement('input', {
+                    type: 'checkbox',
+                    checked: !!wizardModal.includeNetwork,
+                    onChange: (e) => runWizard(wizardModal.provider === 'all' ? null : wizardModal.provider, wizardModal.index, wizardModal.ref, e.target.checked),
+                  }),
+                  React.createElement('span', { style: { fontSize: '12px' } }, t('wizardIncludeNetwork')),
+                ),
+                wizardModal.loading ? React.createElement('div', { className: 'dsub-alert-ok', style: { marginBottom: '12px' } }, '⏳ ' + t('wizardRunning')) : null,
+                wizardModal.error ? React.createElement('div', { className: 'dsub-alert-bad', style: { marginBottom: '12px' } }, wizardModal.error) : null,
+                wizardModal.report ? React.createElement('div', null,
+                  React.createElement('div', { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: '12px' } },
+                    React.createElement('span', {
+                      className: 'dsub-badge ' + (wizardModal.report.overallStatus === 'healthy' ? 'dsub-badge-ok' : (wizardModal.report.overallStatus === 'degraded' ? 'dsub-badge-warn' : 'dsub-badge-bad'))
+                    }, (wizardModal.report.overallStatus === 'healthy' ? '🟢 ' + t('wizardHealthy') : (wizardModal.report.overallStatus === 'degraded' ? '🟡 ' + t('wizardDegraded') : '🔴 ' + t('wizardFailing')))),
+                    React.createElement('span', { style: { fontSize: '11.5px', opacity: 0.7 } },
+                      wizardModal.report.summary.passed + ' passed · ' + wizardModal.report.summary.warnings + ' warn · ' + wizardModal.report.summary.failed + ' fail'
+                    ),
+                  ),
+                  React.createElement('div', { className: 'dsub-trace-box', style: { marginBottom: '12px' } },
+                    wizardModal.report.steps.map((st, idx) => {
+                      const icon = st.status === 'pass' ? '✅' : (st.status === 'warn' ? '⚠️' : (st.status === 'fail' ? '❌' : '⚪'))
+                      const color = st.status === 'pass' ? 'var(--dsw-alias-state-success-primary)' : (st.status === 'warn' ? 'var(--dsw-alias-state-warn-primary)' : (st.status === 'fail' ? 'var(--dsw-alias-state-error-primary)' : 'var(--dsw-alias-label-secondary)'))
+                      return React.createElement('div', { key: idx, className: 'dsub-trace-row' },
+                        React.createElement('div', { style: { display: 'flex', alignItems: 'center', gap: '8px' } },
+                          React.createElement('span', null, icon),
+                          React.createElement('span', { style: { fontWeight: 600 } }, st.name),
+                          st.latencyMs != null ? React.createElement('span', { style: { fontSize: '10px', opacity: 0.6 } }, st.latencyMs + 'ms') : null,
+                        ),
+                        React.createElement('span', { style: { fontSize: '11px', color: color } }, st.message),
+                      )
+                    })
+                  ),
+                  wizardModal.report.recommendations && wizardModal.report.recommendations.length ? React.createElement('div', { style: { marginBottom: '12px' } },
+                    React.createElement('div', { style: { fontSize: '11.5px', fontWeight: 600, color: 'var(--dsw-alias-state-warn-primary)', marginBottom: '4px' } }, '💡 ' + t('wizardRecommendations')),
+                    wizardModal.report.recommendations.map((rec, rIdx) => React.createElement('div', { key: rIdx, className: 'dsub-alert-bad', style: { marginBottom: '4px', fontSize: '11.5px' } }, rec))
+                  ) : null,
+                  React.createElement('div', { style: { display: 'flex', justifyContent: 'flex-end', gap: '8px', marginTop: '10px' } },
+                    React.createElement('button', {
+                      type: 'button',
+                      className: 'dsub-mini',
+                      onClick: () => {
+                        const txt = JSON.stringify(wizardModal.report, null, 2)
+                        try { navigator.clipboard.writeText(txt) } catch { /* ignore */ }
+                      },
+                    }, '📋 ' + t('wizardCopy')),
+                  ),
+                ) : null,
+              ),
+            ),
+          ) : null,
           backupModal ? React.createElement('div', { className: 'dsub-panel-box', style: { marginTop: '10px' } },
             React.createElement('div', { className: 'dsub-panel-title' },
               React.createElement('span', null, backupModal === 'export' ? ('🔒 ' + t('backupExportTitle')) : ('📥 ' + t('backupImportTitle'))),
@@ -2078,6 +2199,12 @@ const cssId = 'dsh-subscriptions/settings.module.css'
                     disabled: checking[key],
                     onClick: () => doCheck(row.slot.provider, row.slot.index).catch((e) => setErr(cleanErrorMessage(e.message || e))),
                   }, checking[key] ? t('checking') : t('check')),
+                  React.createElement('button', {
+                    type: 'button', className: 'dsub-mini',
+                    title: t('wizardTitle'),
+                    onClick: () => runWizard(row.slot.provider, row.slot.index, row.slot.ref, false),
+                  }, '🩺 ' + t('wizardButton')),
+                  
                   (account && account.quarantineUntil && Number(account.quarantineUntil) > Date.now() ? React.createElement(React.Fragment, null,
                     React.createElement('button', {
                       type: 'button', className: 'dsub-mini', title: t('probeWarmupTitle'),

package/lib/diagnostic-wizard.js

@@ -0,0 +1,408 @@
+// Guided Diagnostic Wizard for accounts, credentials, and network connectivity (#519).
+// Enforces 0 Cyrillic characters.
+
+import { maskEmail, maskText, cleanErrorMessage } from './mask.js'
+import { getVendor } from './vendors/index.js'
+
+/**
+ * Mask sensitive credentials inside diagnostic reports.
+ * @param {any} val
+ * @returns {any}
+ */
+export function sanitizeDiagnosticData(val) {
+  if (typeof val === 'string') {
+    return maskText(val)
+      .replace(/Bearer\s+[A-Za-z0-9._~+/-]+=*/gi, 'Bearer [REDACTED]')
+      .replace(/key=[A-Za-z0-9._~+/-]+/gi, 'key=[REDACTED]')
+      .replace(/token=[A-Za-z0-9._~+/-]+/gi, 'token=[REDACTED]')
+  }
+  if (Array.isArray(val)) {
+    return val.map(sanitizeDiagnosticData)
+  }
+  if (val && typeof val === 'object') {
+    const out = {}
+    for (const [k, v] of Object.entries(val)) {
+      if (/secret|token|password|auth|refresh|access_token|key/i.test(k) && typeof v === 'string') {
+        out[k] = v.length > 8 ? v.slice(0, 4) + '...' + v.slice(-4) : '••••••'
+      } else {
+        out[k] = sanitizeDiagnosticData(v)
+      }
+    }
+    return out
+  }
+  return val
+}
+
+/**
+ * Run diagnostic checks on a specific subscription account.
+ *
+ * @param {Object} options
+ * @param {Object} options.account
+ * @param {string} [options.rawBlob]
+ * @param {Object} [options.store]
+ * @param {Function} [options.live]
+ * @param {boolean} [options.includeNetwork]
+ * @param {typeof fetch} [options.fetchImpl]
+ * @param {number} [options.timeoutMs]
+ * @returns {Promise<Object>}
+ */
+export async function runDiagnosticWizard(options = {}) {
+  const account = options.account || {}
+  const ref = account.ref || account.id || 'unknown'
+  const provider = account.provider || 'unknown'
+  const includeNetwork = Boolean(options.includeNetwork)
+  const fetchImpl = options.fetchImpl || globalThis.fetch || fetch
+  const timeoutMs = options.timeoutMs || 8000
+  const now = Date.now()
+
+  let raw = options.rawBlob || null
+  if (!raw && options.store && typeof options.store.resolveRaw === 'function') {
+    try {
+      raw = await options.store.resolveRaw(ref)
+    } catch { /* ignore resolve error */ }
+  }
+
+  const steps = []
+  const recommendations = []
+
+  // -------------------------------------------------------------
+  // STEP 1: Credentials & Expiry Check (Passive)
+  // -------------------------------------------------------------
+  let blob = null
+  let credStatus = 'pass'
+  let credCode = 'CREDENTIAL_OK'
+  let credMsg = 'Credentials present and formatted correctly'
+  let expiresAt = null
+
+  if (!raw) {
+    credStatus = 'fail'
+    credCode = 'MISSING_CREDENTIAL'
+    credMsg = 'No credential blob stored for this account'
+    recommendations.push('Connect this account using OAuth login or provide an API key.')
+  } else {
+    try {
+      blob = JSON.parse(raw)
+    } catch {
+      credStatus = 'fail'
+      credCode = 'CORRUPT_CREDENTIAL_DATA'
+      credMsg = 'Stored credential payload could not be parsed as JSON'
+      recommendations.push('Re-authenticate or re-import this account to fix corrupt data.')
+    }
+
+    if (blob) {
+      expiresAt = blob.expiresAt || blob.expires_at || null
+      const hasToken = Boolean(
+        blob.access_token || blob.accessToken || blob.token || blob.apiKey || blob.key || blob.sessionToken
+      )
+      const hasRefreshToken = Boolean(blob.refresh_token || blob.refreshToken)
+
+      if (!hasToken && !hasRefreshToken) {
+        credStatus = 'fail'
+        credCode = 'NO_TOKEN'
+        credMsg = 'Credential data exists but contains no access or refresh token'
+        recommendations.push('Re-authenticate this account to obtain an active access token.')
+      } else if (expiresAt && typeof expiresAt === 'number') {
+        const remainingMs = expiresAt - now
+        if (remainingMs <= 0) {
+          if (hasRefreshToken) {
+            credStatus = 'warn'
+            credCode = 'EXPIRED_ACCESS_TOKEN'
+            credMsg = `Access token expired ${Math.round(Math.abs(remainingMs) / 60000)}m ago; refresh token available`
+            recommendations.push('Run token refresh or reconnect account.')
+          } else {
+            credStatus = 'fail'
+            credCode = 'TOKEN_EXPIRED_NO_REFRESH'
+            credMsg = 'Access token is expired and no refresh token is present'
+            recommendations.push('Reconnect this account to obtain fresh credentials.')
+          }
+        } else if (remainingMs < 10 * 60 * 1000) {
+          credStatus = 'warn'
+          credCode = 'EXPIRING_SOON'
+          credMsg = `Access token expires in ${Math.round(remainingMs / 60000)}m`
+        }
+      }
+
+      if (blob.validationUrl) {
+        credStatus = 'warn'
+        credCode = 'VALIDATION_REQUIRED'
+        credMsg = blob.validationMessage ? cleanErrorMessage(blob.validationMessage) : 'Provider requires account verification'
+        recommendations.push(`Visit provider validation URL: ${blob.validationUrl}`)
+      }
+    }
+  }
+
+  steps.push({
+    step: 'credentials',
+    name: 'Credentials & Expiry',
+    status: credStatus,
+    code: credCode,
+    message: credMsg,
+    expiresAt,
+  })
+
+  // -------------------------------------------------------------
+  // STEP 2: Network & Proxy Verification
+  // -------------------------------------------------------------
+  const proxyUrl = account.proxyUrl || (options.live && options.live() && options.live().proxyUrl) || null
+  let proxyStatus = 'pass'
+  let proxyCode = 'DIRECT_CONNECTION'
+  let proxyMsg = 'Direct network connection configured'
+  let proxyLatencyMs = null
+
+  if (proxyUrl) {
+    let parsed = null
+    try {
+      parsed = new URL(proxyUrl)
+      if (!['http:', 'https:', 'socks5:', 'socks5h:'].includes(parsed.protocol)) {
+        proxyStatus = 'fail'
+        proxyCode = 'UNSUPPORTED_PROXY_PROTOCOL'
+        proxyMsg = `Unsupported proxy protocol: ${parsed.protocol}`
+        recommendations.push('Use http://, https://, or socks5:// for proxy URL.')
+      } else {
+        proxyCode = 'PROXY_CONFIG_VALID'
+        proxyMsg = `Proxy configured: ${parsed.protocol}//${parsed.host}`
+      }
+    } catch {
+      proxyStatus = 'fail'
+      proxyCode = 'INVALID_PROXY_URL'
+      proxyMsg = 'Proxy URL syntax is invalid'
+      recommendations.push('Check the proxyUrl setting for formatting errors.')
+    }
+
+    if (proxyStatus === 'pass' && includeNetwork) {
+      const t0 = Date.now()
+      try {
+        const controller = new AbortController()
+        const timer = setTimeout(() => controller.abort(), timeoutMs)
+        // Light probe: connect to target or HEAD request
+        await fetchImpl(proxyUrl, {
+          method: 'HEAD',
+          signal: controller.signal,
+        }).catch((e) => {
+          // If proxy accepts HTTP or rejects HEAD with 405/404, TCP connection succeeded
+          if (e && e.name !== 'AbortError' && e.code !== 'ECONNREFUSED' && e.code !== 'ENOTFOUND') {
+            return { ok: true }
+          }
+          throw e
+        })
+        clearTimeout(timer)
+        proxyLatencyMs = Date.now() - t0
+        proxyCode = 'PROXY_REACHABLE'
+        proxyMsg = `Proxy reachable (${proxyLatencyMs}ms)`
+      } catch (e) {
+        proxyStatus = 'fail'
+        proxyCode = 'PROXY_UNREACHABLE'
+        proxyMsg = `Proxy connection failed: ${cleanErrorMessage(e && e.message ? e.message : e)}`
+        recommendations.push('Verify that proxy server is running and accessible.')
+      }
+    }
+  } else {
+    proxyStatus = 'skipped'
+  }
+
+  steps.push({
+    step: 'proxy',
+    name: 'Proxy & Gateway',
+    status: proxyStatus,
+    code: proxyCode,
+    message: proxyMsg,
+    latencyMs: proxyLatencyMs,
+  })
+
+  // -------------------------------------------------------------
+  // STEP 3: Token Validation & Freshness
+  // -------------------------------------------------------------
+  let tokenStatus = 'skipped'
+  let tokenCode = 'NETWORK_CHECK_SKIPPED'
+  let tokenMsg = 'Token validation skipped (enable network checks to run)'
+  let tokenLatencyMs = null
+
+  if (!includeNetwork) {
+    // Passive: based on expiry from Step 1
+    if (credStatus === 'pass') {
+      tokenStatus = 'pass'
+      tokenCode = 'TOKEN_VALID_PASSIVE'
+      tokenMsg = 'Access token appears valid locally'
+    } else {
+      tokenStatus = credStatus
+      tokenCode = credCode
+      tokenMsg = credMsg
+    }
+  } else if (blob) {
+    const t0 = Date.now()
+    const remainingMs = expiresAt ? expiresAt - now : null
+    const isFresh = remainingMs !== null && remainingMs > 15 * 60 * 1000
+
+    if (isFresh && !blob.validationUrl) {
+      tokenStatus = 'pass'
+      tokenCode = 'TOKEN_FRESH'
+      tokenMsg = `Access token valid for another ${Math.round(remainingMs / 60000)}m; refresh not required`
+    } else {
+      // Attempt safe singleflight token refresh if vendor supports it
+      let vendor = null
+      try { vendor = getVendor(provider) } catch { /* unknown provider */ }
+      if (vendor && typeof vendor.refresh === 'function' && blob.refresh_token) {
+        try {
+          const controller = new AbortController()
+          const timer = setTimeout(() => controller.abort(), timeoutMs)
+          const refreshed = await vendor.refresh(blob, {
+            fetchImpl,
+            signal: controller.signal,
+            config: options.live ? options.live() : {},
+          })
+          clearTimeout(timer)
+          tokenLatencyMs = Date.now() - t0
+          if (refreshed && (refreshed.access_token || refreshed.token)) {
+            tokenStatus = 'pass'
+            tokenCode = 'TOKEN_REFRESH_OK'
+            tokenMsg = `Token refreshed successfully (${tokenLatencyMs}ms)`
+          } else {
+            tokenStatus = 'warn'
+            tokenCode = 'TOKEN_REFRESH_PARTIAL'
+            tokenMsg = 'Token refresh completed without new access_token'
+          }
+        } catch (e) {
+          const errStatus = Number(e && (e.status || e.statusCode) || 0)
+          tokenLatencyMs = Date.now() - t0
+          if (errStatus === 401 || errStatus === 403 || (e && e.code === 'INVALID_GRANT')) {
+            tokenStatus = 'fail'
+            tokenCode = 'TOKEN_REVOKED'
+            tokenMsg = 'Token refresh rejected by provider (invalid_grant or revoked)'
+            recommendations.push('Log in again with this provider to reauthorize.')
+          } else if (errStatus === 429) {
+            tokenStatus = 'warn'
+            tokenCode = 'RATE_LIMITED'
+            tokenMsg = 'Token refresh rate limited (429)'
+            recommendations.push('Wait before requesting further token refreshes.')
+          } else {
+            tokenStatus = 'fail'
+            tokenCode = 'REFRESH_ERROR'
+            tokenMsg = `Token refresh failed: ${cleanErrorMessage(e && e.message ? e.message : e)}`
+            recommendations.push('Verify network connection to provider authentication servers.')
+          }
+        }
+      } else {
+        tokenStatus = 'pass'
+        tokenCode = 'STATIC_CREDENTIAL_READY'
+        tokenMsg = 'Static credentials ready for use'
+      }
+    }
+  }
+
+  steps.push({
+    step: 'token_validation',
+    name: 'Token Validation',
+    status: tokenStatus,
+    code: tokenCode,
+    message: tokenMsg,
+    latencyMs: tokenLatencyMs,
+  })
+
+  // -------------------------------------------------------------
+  // STEP 4: Model Catalog Discovery (Passive or Active listModels)
+  // -------------------------------------------------------------
+  let catalogStatus = 'skipped'
+  let catalogCode = 'NETWORK_CHECK_SKIPPED'
+  let catalogMsg = 'Model catalog reachability check skipped'
+  let catalogLatencyMs = null
+  let modelCount = 0
+
+  if (!includeNetwork) {
+    catalogStatus = 'skipped'
+  } else {
+    const t0 = Date.now()
+    const vendor = getVendor(provider)
+    if (vendor && typeof vendor.listModels === 'function') {
+      try {
+        const controller = new AbortController()
+        const timer = setTimeout(() => controller.abort(), timeoutMs)
+        const models = await vendor.listModels(account, {
+          fetchImpl,
+          signal: controller.signal,
+          config: options.live ? options.live() : {},
+        })
+        clearTimeout(timer)
+        catalogLatencyMs = Date.now() - t0
+        modelCount = Array.isArray(models) ? models.length : 0
+        if (modelCount > 0) {
+          catalogStatus = 'pass'
+          catalogCode = 'CATALOG_OK'
+          catalogMsg = `${modelCount} models reachable and verified (${catalogLatencyMs}ms)`
+        } else {
+          catalogStatus = 'warn'
+          catalogCode = 'CATALOG_EMPTY'
+          catalogMsg = 'Catalog request succeeded but 0 models returned'
+          recommendations.push('Check provider plan features and permissions.')
+        }
+      } catch (e) {
+        catalogLatencyMs = Date.now() - t0
+        const status = Number(e && (e.status || e.statusCode) || 0)
+        if (status === 401 || status === 403) {
+          catalogStatus = 'fail'
+          catalogCode = 'CATALOG_UNAUTHORIZED'
+          catalogMsg = 'Provider rejected catalog request with 401/403'
+          recommendations.push('Account credentials do not have access to models catalog.')
+        } else {
+          catalogStatus = 'fail'
+          catalogCode = 'CATALOG_UNREACHABLE'
+          catalogMsg = `Failed to fetch model catalog: ${cleanErrorMessage(e && e.message ? e.message : e)}`
+          recommendations.push('Verify provider API endpoint reachability.')
+        }
+      }
+    } else {
+      catalogStatus = 'pass'
+      catalogCode = 'STATIC_CATALOG'
+      catalogMsg = 'Standard static catalog available'
+    }
+  }
+
+  steps.push({
+    step: 'models_catalog',
+    name: 'Model Catalog Reachability',
+    status: catalogStatus,
+    code: catalogCode,
+    message: catalogMsg,
+    latencyMs: catalogLatencyMs,
+    modelCount,
+  })
+
+  // -------------------------------------------------------------
+  // Overall Summary & Sanitization
+  // -------------------------------------------------------------
+  let passed = 0
+  let warnings = 0
+  let failed = 0
+  let skipped = 0
+
+  for (const s of steps) {
+    if (s.status === 'pass') passed++
+    else if (s.status === 'warn') warnings++
+    else if (s.status === 'fail') failed++
+    else skipped++
+  }
+
+  const overallStatus = failed > 0 ? 'failing' : (warnings > 0 ? 'degraded' : 'healthy')
+
+  const report = {
+    account: {
+      ref,
+      provider,
+      label: account.label ? maskEmail(account.label) : ref,
+      index: account.index || 1,
+    },
+    generatedAt: new Date(now).toISOString(),
+    networkChecksIncluded: includeNetwork,
+    overallStatus,
+    summary: {
+      totalSteps: steps.length,
+      passed,
+      warnings,
+      failed,
+      skipped,
+    },
+    steps,
+    recommendations,
+  }
+
+  return sanitizeDiagnosticData(report)
+}

package/lib/diagnostics.js

@@ -1,5 +1,6 @@
 import { defaultConcurrencyQueue } from './concurrency-queue.js'
 import { calculateCacheMetrics } from './analytics.js'
+import { getSessionPinStats } from './session-pin.js'
 import { maskText } from './mask.js'
 import { normalizeSlots } from './accounts.js'
 import { PROVIDERS } from './refs.js'
@@ -50,6 +51,7 @@ export async function createDiagnosticsReport({ live, store, history, NS, pkgVer
     requests: { total: rows.length, byStatus, lastErrors },
     cache: calculateCacheMetrics(rows),
     queue: defaultConcurrencyQueue.stats(),
+    pins: getSessionPinStats(),
     decisions: {
       recent: rows.filter((r) => r && r.decisionTrace).slice(0, 10).map((r) => ({
         ts: r.ts,

package/lib/rotate.js

@@ -1,6 +1,6 @@
 import { computePacingRisk, calculateBurnRatePerHour, calculateBurnUrgency } from "./forecast.js"
 import { isQuarantined } from './quarantine.js'
-import { getPinnedAccountRef, pinSession } from './session-pin.js'
+import { getPinnedAccountRef, pinSession, touchSessionPin, unpinSession, isCacheAwareProvider } from './session-pin.js'
 
 const SWITCH_CODES = new Set([
   'RATE_LIMIT',
@@ -98,9 +98,9 @@ export function pickAccountWithTrace(accounts, nowMs, opts) {
     return true
   }
 
-  // Sticky Session Pinning (#170, #517)
+  // Sticky & Cache-Aware Session Pinning (#170, #517, #520)
   if (targetSession) {
-    const pinnedRef = getPinnedAccountRef(targetSession)
+    const pinnedRef = getPinnedAccountRef(targetSession, now)
     if (pinnedRef) {
       const pinned = list.find((a) => (a.ref || a.id) === pinnedRef)
       if (pinned && pinned.hasToken && !isQuarantined(pinned, now)) {
@@ -110,42 +110,53 @@ export function pickAccountWithTrace(accounts, nowMs, opts) {
           (pinned.quota.remainingPercent != null && Number(pinned.quota.remainingPercent) <= 0)
         ) && (!pinned.quota.resetAt || Number(pinned.quota.resetAt) > now))
         if (!isCooldown && !isPinnedZero && !isQuotaExhausted(pinned) && !isUsageExhausted(pinned)) {
+          const cacheAware = isCacheAwareProvider(pinned.provider)
+          const decisionReason = cacheAware ? 'cache_pinned' : 'session_pinned'
+          touchSessionPin(targetSession, { provider: pinned.provider, model: opts && opts.model })
           evaluations.push({
             ref: pinnedRef,
             eligible: true,
             tier: 0,
-            reason: 'session_pinned',
+            reason: decisionReason,
             pinned: true,
+            cacheAware,
           })
           return {
             account: pinned,
             trace: {
               chosenRef: pinnedRef,
-              decisionReason: 'session_pinned',
+              decisionReason,
               tier: 0,
               evaluations,
               selectionMetrics: {
                 pinned: true,
+                cacheAware,
                 remainingPercent: getAccountRemainingPercent(pinned),
                 healthScore: pinned.healthScore ?? 100,
               },
             },
           }
         } else {
+          const releaseReason = isCooldown ? 'pinned_cooldown' : isPinnedZero ? 'pinned_zero_quota' : 'pinned_exhausted'
+          unpinSession(targetSession, releaseReason)
           evaluations.push({
             ref: pinnedRef,
             eligible: false,
-            reason: isCooldown ? 'pinned_cooldown' : isPinnedZero ? 'pinned_zero_quota' : 'pinned_exhausted',
+            reason: releaseReason,
             pinned: true,
           })
         }
       } else if (pinned) {
+        const releaseReason = !pinned.hasToken ? 'pinned_no_token' : 'pinned_quarantine'
+        unpinSession(targetSession, releaseReason)
         evaluations.push({
           ref: pinnedRef,
           eligible: false,
-          reason: !pinned.hasToken ? 'pinned_no_token' : 'pinned_quarantine',
+          reason: releaseReason,
           pinned: true,
         })
+      } else {
+        unpinSession(targetSession, 'pinned_not_found')
       }
     }
   }
@@ -277,7 +288,11 @@ export function pickAccountWithTrace(accounts, nowMs, opts) {
       const chosen = tier[0]
       const chosenRef = chosen.ref || chosen.id
       if (targetSession && chosen) {
-        pinSession(targetSession, chosenRef)
+        pinSession(targetSession, chosenRef, {
+          provider: chosen.provider,
+          model: opts && opts.model,
+          cacheAware: isCacheAwareProvider(chosen.provider),
+        })
       }
       return {
         account: chosen,

package/lib/routes/status.js

@@ -1,5 +1,6 @@
 import { defaultConcurrencyQueue } from '../concurrency-queue.js'
 import { calculateAnalytics } from '../analytics.js'
+import { runDiagnosticWizard } from '../diagnostic-wizard.js'
 import { buildEnrichedCatalog } from '../models-catalog.js'
 // #374: Sensitive GET routes protected by same-origin check
 import { readFileSync } from 'node:fs'
@@ -580,4 +581,37 @@ export function registerStatusRoutes(ctx, state) {
       writeJson(res, 200, { ok: true, queue: queueStats })
     }),
   }), 'dsh-subscriptions: /queue')
+
+  // #519: Interactive Diagnostic Wizard for accounts and connectivity
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/diagnostic-wizard',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'POST') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'POST only' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req, ctx)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'same-origin only' } })
+        return
+      }
+      let body = {}
+      try { body = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}') } catch { /* ignore */ }
+      const accounts = await accountsView()
+      const targetAccount = accounts.find((a) => {
+        if (body.ref && (a.ref === body.ref || a.id === body.ref)) return true
+        if (body.provider && body.index !== undefined && a.provider === body.provider && a.index === Number(body.index)) return true
+        return false
+      }) || (body.provider ? { provider: body.provider, index: Number(body.index) || 1 } : (accounts[0] || {}))
+
+      const report = await runDiagnosticWizard({
+        account: targetAccount,
+        store,
+        live,
+        includeNetwork: Boolean(body.includeNetwork),
+        fetchImpl: fetch,
+      })
+      writeJson(res, 200, { ok: true, report })
+    }),
+  }), 'dsh-subscriptions: /diagnostic-wizard')
 }

package/lib/session-pin.js

@@ -1,52 +1,258 @@
+// Cache-aware session affinity and pinning with lifecycle management (#170, #517, #520).
+// Enforces 0 Cyrillic characters.
+
+export const CACHE_AWARE_PROVIDERS = new Set(['claude', 'codex', 'antigravity', 'grok'])
+
+/**
+ * Check if a provider supports prompt/prefix caching where pinning benefits cache hit rates.
+ * @param {string|undefined} provider
+ * @returns {boolean}
+ */
+export function isCacheAwareProvider(provider) {
+  if (!provider || typeof provider !== 'string') return false
+  return CACHE_AWARE_PROVIDERS.has(provider.toLowerCase().trim())
+}
+
+const DEFAULT_TTL_MS = 30 * 60 * 1000 // 30 minutes
+const MAX_PINS = 200
+
+/**
+ * @typedef {Object} SessionPinEntry
+ * @property {string} accountRef
+ * @property {string} [provider]
+ * @property {string} [model]
+ * @property {number} pinnedAt
+ * @property {number} lastHitAt
+ * @property {number} expiresAt
+ * @property {number} hits
+ * @property {boolean} cacheAware
+ * @property {number} cacheHits
+ * @property {number} cacheTokensSaved
+ */
+
+/** @type {Map<string, SessionPinEntry>} */
 const sessionPins = new Map()
-const DEFAULT_TTL_MS = 30 * 60 * 1000 // 30 mins
+
+const stats = {
+  totalPins: 0,
+  retainedHits: 0,
+  cacheAwareHits: 0,
+  releasedCount: 0,
+  cacheTokensSaved: 0,
+  releasesByReason: {},
+}
+
+/**
+ * Record a release reason in statistics.
+ * @param {string} reason
+ */
+function recordReleaseReason(reason) {
+  const r = String(reason || 'manual')
+  stats.releasedCount++
+  stats.releasesByReason[r] = (stats.releasesByReason[r] || 0) + 1
+}
 
 /**
  * Prune expired session pin entries.
  * @param {number} [now]
- * @returns {void}
+ * @returns {number} count of pruned pins
  */
 export function pruneSessionPins(now = Date.now()) {
+  let pruned = 0
   for (const [id, entry] of sessionPins.entries()) {
     if (now > entry.expiresAt) {
       sessionPins.delete(id)
+      recordReleaseReason('pin_released_expired')
+      pruned++
     }
   }
+  return pruned
 }
 
 /**
- * Bind a session id to an account ref for ttlMs (default 30 minutes).
+ * Bind a session id to an account ref with cache awareness and metadata.
  * @param {string|undefined} sessionId
  * @param {string|undefined} accountRef
- * @param {number} [ttlMs]
+ * @param {Object} [options]
+ * @param {string} [options.provider]
+ * @param {string} [options.model]
+ * @param {number} [options.ttlMs]
+ * @param {boolean} [options.cacheAware]
  * @returns {void}
  */
-export function pinSession(sessionId, accountRef, ttlMs = DEFAULT_TTL_MS) {
+export function pinSession(sessionId, accountRef, options = {}) {
   if (!sessionId || !accountRef) return
-  if (sessionPins.size >= 50) {
+  if (sessionPins.size >= MAX_PINS) {
     pruneSessionPins()
   }
+
+  const now = Date.now()
+  const ttl = typeof options === 'number'
+    ? options
+    : (options && typeof options.ttlMs === 'number' ? options.ttlMs : DEFAULT_TTL_MS)
+  const provider = options.provider || undefined
+  const cacheAware = options.cacheAware !== undefined ? Boolean(options.cacheAware) : isCacheAwareProvider(provider)
+
+  const existing = sessionPins.get(sessionId)
+  if (existing && existing.accountRef === accountRef) {
+    // Sliding TTL on re-pinning same account
+    existing.lastHitAt = now
+    existing.expiresAt = now + ttl
+    if (options.model) existing.model = options.model
+    return
+  }
+
   sessionPins.set(sessionId, {
     accountRef,
-    expiresAt: Date.now() + ttlMs
+    provider,
+    model: options.model || undefined,
+    pinnedAt: now,
+    lastHitAt: now,
+    expiresAt: now + ttl,
+    hits: 0,
+    cacheAware,
+    cacheHits: 0,
+    cacheTokensSaved: 0,
   })
+  stats.totalPins++
 }
 
 /**
+ * Retrieve bound account ref or null if missing/expired.
  * @param {string|undefined} sessionId
- * @returns {string|null} the bound account ref, or null when absent/expired
+ * @param {number} [now]
+ * @returns {string|null}
  */
-export function getPinnedAccountRef(sessionId) {
+export function getPinnedAccountRef(sessionId, now = Date.now()) {
   if (!sessionId) return null
   const entry = sessionPins.get(sessionId)
   if (!entry) return null
-  if (Date.now() > entry.expiresAt) {
+  if (now > entry.expiresAt) {
     sessionPins.delete(sessionId)
+    recordReleaseReason('pin_released_expired')
     return null
   }
   return entry.accountRef
 }
 
+/**
+ * Retrieve full session pin details.
+ * @param {string|undefined} sessionId
+ * @param {number} [now]
+ * @returns {SessionPinEntry|null}
+ */
+export function getPinnedSessionDetails(sessionId, now = Date.now()) {
+  if (!sessionId) return null
+  const entry = sessionPins.get(sessionId)
+  if (!entry) return null
+  if (now > entry.expiresAt) {
+    sessionPins.delete(sessionId)
+    recordReleaseReason('pin_released_expired')
+    return null
+  }
+  return { ...entry }
+}
+
+/**
+ * Touch an active session pin (record hit, sliding TTL extension).
+ * @param {string|undefined} sessionId
+ * @param {Object} [options]
+ * @param {number} [options.ttlMs]
+ * @param {string} [options.model]
+ * @param {string} [options.provider]
+ * @returns {boolean} true if pin existed and was updated
+ */
+export function touchSessionPin(sessionId, options = {}) {
+  if (!sessionId) return false
+  const entry = sessionPins.get(sessionId)
+  if (!entry) return false
+
+  const now = Date.now()
+  if (now > entry.expiresAt) {
+    sessionPins.delete(sessionId)
+    recordReleaseReason('pin_released_expired')
+    return false
+  }
+
+  const ttl = typeof options === 'number'
+    ? options
+    : (options && typeof options.ttlMs === 'number' ? options.ttlMs : DEFAULT_TTL_MS)
+  entry.lastHitAt = now
+  entry.expiresAt = now + ttl
+  entry.hits++
+  if (options.provider) entry.provider = options.provider
+  if (options.model) entry.model = options.model
+
+  stats.retainedHits++
+  if (entry.cacheAware) {
+    stats.cacheAwareHits++
+  }
+  return true
+}
+
+/**
+ * Explicitly release a session pin with a documented reason code.
+ * @param {string|undefined} sessionId
+ * @param {string} [reason] e.g. 'pinned_cooldown', 'pinned_quarantine', 'pinned_quota', 'manual'
+ * @returns {boolean} true if a pin was removed
+ */
+export function unpinSession(sessionId, reason = 'manual') {
+  if (!sessionId) return false
+  const exists = sessionPins.has(sessionId)
+  if (exists) {
+    sessionPins.delete(sessionId)
+    recordReleaseReason(reason)
+    return true
+  }
+  return false
+}
+
+/**
+ * Record actual token caching metrics for a pinned session.
+ * @param {string|undefined} sessionId
+ * @param {number} cacheReadTokens
+ */
+export function recordSessionCacheUsage(sessionId, cacheReadTokens = 0) {
+  if (!sessionId || typeof cacheReadTokens !== 'number' || cacheReadTokens <= 0) return
+  const entry = sessionPins.get(sessionId)
+  if (!entry) return
+
+  entry.cacheHits++
+  entry.cacheTokensSaved += cacheReadTokens
+  stats.cacheTokensSaved += cacheReadTokens
+}
+
+/**
+ * Get cumulative statistics and current state of session pinning.
+ * @returns {Object}
+ */
+export function getSessionPinStats() {
+  let cacheAwareActive = 0
+  for (const entry of sessionPins.values()) {
+    if (entry.cacheAware) cacheAwareActive++
+  }
+
+  return {
+    totalPins: stats.totalPins,
+    activePins: sessionPins.size,
+    cacheAwareActivePins: cacheAwareActive,
+    retainedHits: stats.retainedHits,
+    cacheAwareHits: stats.cacheAwareHits,
+    releasedCount: stats.releasedCount,
+    cacheTokensSaved: stats.cacheTokensSaved,
+    releasesByReason: { ...stats.releasesByReason },
+  }
+}
+
+/**
+ * Reset all session pins and statistics (useful for tests and full resets).
+ */
 export function clearSessionPins() {
   sessionPins.clear()
+  stats.totalPins = 0
+  stats.retainedHits = 0
+  stats.cacheAwareHits = 0
+  stats.releasedCount = 0
+  stats.cacheTokensSaved = 0
+  stats.releasesByReason = {}
 }

package/lib/stream-rotate.js

@@ -1,4 +1,5 @@
 import { defaultConcurrencyQueue } from './concurrency-queue.js'
+import { recordSessionCacheUsage } from './session-pin.js'
 import { pickAccountWithTrace, markCooldown, isSwitchableError, isRegionError, modelFamily } from './rotate.js'
 import { putInQuarantine, REASON_RATE_LIMIT, REASON_HARD_LIMIT, REASON_REVOKED } from './quarantine.js'
 import { notifySessionExpired, notifyQuarantineEntered } from './alerts.js'
@@ -147,6 +148,14 @@ export async function* streamWithRotation({
         )
         for await (const chunk of guardedStream) {
           firstChunkDelivered = true
+          const cachedTokens = Number(
+            (chunk && chunk.usage && (chunk.usage.cacheReadTokens || chunk.usage.cachedTokens)) ||
+            (chunk && chunk.tokens && (chunk.tokens.cacheRead || chunk.tokens.cached)) ||
+            0
+          )
+          if (cachedTokens > 0 && options && options.sessionId) {
+            recordSessionCacheUsage(options.sessionId, cachedTokens)
+          }
           yield chunk
         }
         currentAttempt.status = 'success'

package/package.json

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