@goodandready/dsh-subscriptions 0.6.71 → 0.6.82

package/lib/reset-clock.js

@@ -1,9 +1,12 @@
 import { parseHeaders } from './ratelimit.js'
+import { formatRelativeReset } from './relative-time.js'
 
 export const VENDOR_WINDOW_MS = {
   claude: 5 * 3600 * 1000,
   codex: 3 * 3600 * 1000,
   grok: 2 * 3600 * 1000,
+  copilot: 24 * 3600 * 1000,
+  antigravity: 24 * 3600 * 1000,
 }
 
 export function parseResetFromText(message, nowMs = Date.now()) {
@@ -85,3 +88,55 @@ export function resolveAccurateReset(err, account, provider, nowMs = Date.now(),
 
   return null
 }
+
+export function formatRollingCountdown(resetAt, lang = 'en', now = Date.now()) {
+  const ts = Number(resetAt)
+  if (!Number.isFinite(ts) || ts <= 0) return ''
+  const d = new Date(ts)
+  const pad = (n) => String(n).padStart(2, '0')
+  const timeStr = `${pad(d.getHours())}:${pad(d.getMinutes())}`
+  const relStr = formatRelativeReset(ts, lang, now)
+  if (lang === 'zh') {
+    return `额度重置于 ${timeStr} (${relStr})`
+  }
+  return `Window resets at ${timeStr} (${relStr})`
+}
+
+export function computeEffectiveResetAt(account, provider, now = Date.now()) {
+  if (!account) return null
+  const nowMs = Number(now) || Date.now()
+  const candidates = []
+
+  if (account.quota && account.quota.resetAt) {
+    const r = Number(account.quota.resetAt)
+    if (Number.isFinite(r) && r > nowMs) candidates.push(r)
+  }
+  if (account.cooldownUntil) {
+    const c = Number(account.cooldownUntil)
+    if (Number.isFinite(c) && c > nowMs) candidates.push(c)
+  }
+  if (account.quarantineUntil) {
+    const q = Number(account.quarantineUntil)
+    if (Number.isFinite(q) && q > nowMs) candidates.push(q)
+  }
+  if (Array.isArray(account.usage)) {
+    for (const w of account.usage) {
+      if (w && w.resetAt) {
+        const wr = Number(w.resetAt)
+        if (Number.isFinite(wr) && wr > nowMs) candidates.push(wr)
+      }
+    }
+  }
+
+  if (candidates.length > 0) {
+    return Math.min(...candidates)
+  }
+
+  const p = String(provider || (account && account.provider) || '').toLowerCase()
+  const windowDefault = VENDOR_WINDOW_MS[p]
+  if (windowDefault && account.usagePercent != null && Number(account.usagePercent) >= 100) {
+    return nowMs + windowDefault
+  }
+
+  return null
+}

package/lib/rotate.js

@@ -17,14 +17,28 @@ export function isRegionError(err) {
   return status === 400 && (/FAILED_PRECONDITION/i.test(msg) || /User location is not supported/i.test(msg))
 }
 
+export function isAuthError(err) {
+  if (!err || typeof err !== "object") return false
+  const status = Number(err.status || err.statusCode) || 0
+  if (status === 401) return true
+  const code = String(err.code || (err.failure && err.failure.code) || "").toUpperCase()
+  if (code === "AUTH" || code === "TOKEN_REVOKED" || code === "UNAUTHORIZED" || code === "INVALID_TOKEN" || code === "SESSION_EXPIRED") return true
+  const msg = String(err.message || "")
+  if (/invalid_grant/i.test(msg)) return true
+  if (/token (?:has been )?revoked/i.test(msg)) return true
+  if (/session (?:expired|revoked|invalid)/i.test(msg)) return true
+  if (/unauthorized/i.test(msg) && (status === 0 || status === 400 || status === 401)) return true
+  return false
+}
+
 export function isSwitchableError(err) {
-  if (!err || typeof err !== 'object') return false
-  if (err.name === 'TimeoutError' || err.code === 'TIMEOUT' || err.code === 'EMPTY_RESPONSE' || err.code === 'SOFT_FAILURE' || err.isSoftFailure) return true
-  if (err.name === 'AbortError' || err.code === 'ABORT_ERR' || err.code === 'ERR_ABORTED' || (err.message && /aborted/i.test(err.message))) return false
+  if (!err || typeof err !== "object") return false
+  if (err.name === "TimeoutError" || err.code === "TIMEOUT" || err.code === "EMPTY_RESPONSE" || err.code === "SOFT_FAILURE" || err.isSoftFailure) return true
+  if (err.name === "AbortError" || err.code === "ABORT_ERR" || err.code === "ERR_ABORTED" || (err.message && /aborted/i.test(err.message))) return false
   const code = err.code || (err.failure && err.failure.code)
   if (SWITCH_CODES.has(code)) return true
   if (isRegionError(err)) return true
-  const status = err.status || err.statusCode
+  const status = Number(err.status || err.statusCode) || 0
   return status === 401 || status === 403 || status === 429 || status === 500 || status === 502 || status === 503
 }
 

package/lib/routes/accounts.js

@@ -1,4 +1,6 @@
+import { diagnoseVendorError } from '../doctor.js'
 import { exportVault, importVault } from '../vault.js'
+import { syncVaultPush, syncVaultPull, getVaultSyncStatus } from '../vault-sync.js'
 import { normalizeSlots, vendorConfig } from '../accounts.js'
 import { getVendor } from '../vendors/index.js'
 import { notifyQuarantineEntered, notifyQuarantineReleased } from '../alerts.js'
@@ -445,6 +447,140 @@ export function registerAccountsRoutes(ctx, state) {
     }),
   }), 'dsh-subscriptions: /import-token')
 
+  // Issue #541: Dynamic model catalog discovery & sync
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/accounts/sync-models',
+    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 payload = {}
+      try { payload = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}') } catch { /* ignore */ }
+      const provider = payload.provider
+      const index = payload.index || 1
+      if (!provider || !isProvider(provider)) {
+        writeJson(res, 400, { ok: false, error: { code: 'invalid_provider', message: 'Invalid or missing provider' } })
+        return
+      }
+      const ref = oauthRef(provider, index)
+      const info = await store.describeRef(ref)
+      if (!info.configured) {
+        writeJson(res, 400, { ok: false, error: { code: 'not_configured', message: 'Account is not configured' } })
+        return
+      }
+      try {
+        let blob = await store.loadBlob(ref)
+        blob = await store.ensureFresh(provider, blob, ref)
+        const vendor = getVendor(provider)
+        const cfg = vendorConfig(provider, live())
+        const doFetch = (typeof state.fetchForRef === 'function' && state.fetchForRef(ref)) || fetch
+        let models = []
+        if (typeof vendor.listModels === 'function') {
+          const cat = await vendor.listModels(blob, cfg, doFetch)
+          if (Array.isArray(cat)) {
+            models = cat.map((m) => (typeof m === 'string' ? m : (m.id || m.slug || m.name))).filter(Boolean)
+          } else if (cat && Array.isArray(cat.models)) {
+            models = cat.models.map((m) => (typeof m === 'string' ? m : (m.id || m.slug || m.name))).filter(Boolean)
+          }
+        }
+        if (!models.length && vendor.defaults) {
+          models = (vendor.defaults().models || []).map((m) => (typeof m === 'string' ? m : (m.id || m.slug || m.name))).filter(Boolean)
+        }
+        if (typeof store.rememberDynamicModels === 'function') {
+          store.rememberDynamicModels(ref, models)
+        }
+        writeJson(res, 200, {
+          ok: true,
+          provider,
+          index,
+          ref,
+          count: models.length,
+          models,
+        })
+      } catch (err) {
+        const doc = diagnoseVendorError(err, provider)
+        writeJson(res, 502, {
+          ok: false,
+          provider,
+          index,
+          ref,
+          doctor: doc,
+          error: { code: 'sync_failed', message: String(err && err.message || err) },
+        })
+      }
+    }),
+  }), 'dsh-subscriptions: /accounts/sync-models')
+
+
+
+  // Issue #549: Switch active organization/workspace for an account slot
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/accounts/switch-organization',
+    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 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 provider = String(payload.provider || '')
+      const index = Number(payload.index || 1)
+      const organizationId = String(payload.organizationId || payload.selectedOrgId || '').trim()
+      if (!isProvider(provider)) {
+        writeJson(res, 400, { ok: false, error: { code: 'provider', message: 'unknown provider' } })
+        return
+      }
+      const ref = refForSlot(provider, index)
+      if (!ref) {
+        writeJson(res, 404, { ok: false, error: { code: 'slot', message: 'slot not found' } })
+        return
+      }
+      let blob
+      try { blob = await store.loadBlob(ref) } catch {
+        writeJson(res, 404, { ok: false, error: { code: 'blob', message: 'credentials not configured' } })
+        return
+      }
+
+      blob.selectedOrgId = organizationId
+      if (provider === 'codex') blob.accountId = organizationId
+      if (provider === 'antigravity') blob.projectId = organizationId
+      if (provider === 'claude') blob.organizationId = organizationId
+      if (provider === 'copilot') blob.organization = organizationId
+
+      if (Array.isArray(blob.organizations)) {
+        const found = blob.organizations.find((o) => o && o.id === organizationId)
+        if (found) blob.selectedOrgName = found.name
+        else if (organizationId) blob.selectedOrgName = organizationId
+      } else if (organizationId) {
+        blob.selectedOrgName = organizationId
+      }
+
+      await store.saveBlob(ref, blob)
+      await syncAdapter()
+
+      writeJson(res, 200, {
+        ok: true,
+        ref,
+        selectedOrgId: organizationId,
+        selectedOrgName: blob.selectedOrgName || organizationId,
+        accounts: await accountsView(),
+      })
+    }),
+  }), 'dsh-subscriptions: /accounts/switch-organization')
 
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
@@ -588,4 +724,71 @@ export function registerAccountsRoutes(ctx, state) {
     handler: handleVaultImport,
   }), 'dsh-subscriptions: /import-backup')
 
+
+  // #562: Remote Vault Sync Push
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/vault/sync/push',
+    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
+      }
+      try {
+        const result = await syncVaultPush({ live: live(), store })
+        writeJson(res, 200, { ok: true, result, status: getVaultSyncStatus() })
+      } catch (e) {
+        writeJson(res, 400, { ok: false, error: { code: 'vault_sync_push', message: String(e && e.message || e) } })
+      }
+    }),
+  }), 'dsh-subscriptions: /vault/sync/push')
+
+  // #562: Remote Vault Sync Pull
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/vault/sync/pull',
+    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
+      }
+      try {
+        const result = await syncVaultPull({
+          live: live(),
+          store,
+          settingsApi: getSettingsApi(),
+          syncAdapter,
+          refreshModels,
+        })
+        writeJson(res, 200, { ok: true, result, status: getVaultSyncStatus(), accounts: await accountsView() })
+      } catch (e) {
+        writeJson(res, 400, { ok: false, error: { code: 'vault_sync_pull', message: String(e && e.message || e) } })
+      }
+    }),
+  }), 'dsh-subscriptions: /vault/sync/pull')
+
+  // #562: Remote Vault Sync Status
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/vault/sync/status',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'GET') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'GET only' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req, ctx)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'same-origin only' } })
+        return
+      }
+      writeJson(res, 200, { ok: true, status: getVaultSyncStatus() })
+    }),
+  }), 'dsh-subscriptions: /vault/sync/status')
 }

package/lib/routes/oauth.js

@@ -5,6 +5,8 @@ import { parseCallbackInput, requestOrigin } from '../oauth.js'
 import { createPkce } from '../pkce.js'
 import { displayName, isProvider, oauthRef } from '../refs.js'
 import { getVendor } from '../vendors/index.js'
+import { getHeadlessAuthInfo, handleHeadlessRedirect } from '../headless-auth.js'
+import { syncVaultPush } from '../vault-sync.js'
 
 export function registerOauthRoutes(ctx, state) {
   const {
@@ -44,6 +46,7 @@ export function registerOauthRoutes(ctx, state) {
       }
       const origin = requestOrigin(req)
       const redirectUri = redirectFor(provider, `${provider}:${index}`, origin)
+      sweepPending(Date.now())
       const pkce = await createPkce()
       pending.set(pkce.state, {
         provider,
@@ -89,7 +92,10 @@ export function registerOauthRoutes(ctx, state) {
           }
         } catch { autoCatch = false }
       }
-      writeJson(res, 200, { ok: true, url, state: pkce.state, redirectUri, autoCatch })
+      const host = (req.headers && req.headers.host) || ''
+      const user = process.env.USER || process.env.USERNAME || 'user'
+      const headless = getHeadlessAuthInfo({ provider, redirectUri, authUrl: url, host, user })
+      writeJson(res, 200, { ok: true, url, state: pkce.state, redirectUri, autoCatch, headless })
     }),
   }), 'dsh-subscriptions: /oauth/start')
 
@@ -143,7 +149,13 @@ export function registerOauthRoutes(ctx, state) {
           intervalMs: start.intervalMs,
           createdAt: Date.now(),
         })
-        writeJson(res, 200, { ok: true, state, userCode: start.userCode, authUrl: start.authUrl, intervalMs: start.intervalMs })
+        const host = (req.headers && req.headers.host) || ''
+        const user = process.env.USER || process.env.USERNAME || 'user'
+        const headless = getHeadlessAuthInfo({ provider, redirectUri: '', authUrl: start.authUrl, host, user })
+        if (headless.terminalQr) {
+          console.log('[dsh-subscriptions] Device OAuth initiated for ' + provider + ':\n' + headless.terminalQr)
+        }
+        writeJson(res, 200, { ok: true, state, userCode: start.userCode, authUrl: start.authUrl, intervalMs: start.intervalMs, headless })
       } catch (e) {
         writeJson(res, 502, { ok: false, error: { code: e && e.code || 'DEVICE', message: String(e && e.message || e).slice(0, 300) } })
       }
@@ -193,6 +205,9 @@ export function registerOauthRoutes(ctx, state) {
         pending.delete(state)
         await syncAdapter()
         refreshModels().catch(() => {})
+        if (live().vaultSyncEnabled && live().vaultSyncAutoPush) {
+          syncVaultPush({ live: live(), store }).catch(() => {})
+        }
         writeJson(res, 200, { ok: true, status: 'authorized', ref: row.ref, label: pmL(blob.label || blob.email) || displayName(row.provider) })
       } catch (e) {
         writeJson(res, 502, { ok: false, error: { code: e && e.code || 'DEVICE', message: String(e && e.message || e).slice(0, 300) } })
@@ -261,4 +276,31 @@ export function registerOauthRoutes(ctx, state) {
       }
     }),
   }), 'dsh-subscriptions: /oauth/complete')
+
+  // #557: Headless auth info helper endpoint
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/oauth/headless-info',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'GET') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'GET only' } })
+        return
+      }
+      const q = queryOf(req)
+      const provider = q.get('provider') || ''
+      const redirectUri = q.get('redirectUri') || ''
+      const authUrl = q.get('authUrl') || ''
+      const host = (req.headers && req.headers.host) || ''
+      const user = process.env.USER || process.env.USERNAME || 'user'
+      const info = getHeadlessAuthInfo({ provider, redirectUri, authUrl, host, user })
+      writeJson(res, 200, { ok: true, ...info })
+    }),
+  }), 'dsh-subscriptions: /oauth/headless-info')
+
+  // #557: Headless re-auth callback redirector
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/oauth/headless-redirect',
+    handler: (req, res) => handleHeadlessRedirect(req, res, { pending, completeOAuth, accountsView }),
+  }), 'dsh-subscriptions: /oauth/headless-redirect')
 }

package/lib/routes/proxy.js

@@ -58,6 +58,20 @@ export function registerProxyRoutes(ctx, state) {
         writeJson(res, 404, { ok: false, error: { code: 'provider', message: 'unknown provider' } })
         return
       }
+      const hasBackslashOrInvalid = parts.some((p) => {
+        if (p.includes("\\")) return true
+        try {
+          const dec = decodeURIComponent(p)
+          if (dec.includes("\\")) return true
+        } catch {
+          return true
+        }
+        return false
+      })
+      if (hasBackslashOrInvalid) {
+        writeJson(res, 400, { ok: false, error: { code: 'path', message: 'invalid path' } })
+        return
+      }
       let body
       if (req.method === 'POST') {
         try {

package/lib/routes/status.js

@@ -1,3 +1,5 @@
+import { diagnoseVendorError } from '../doctor.js'
+import { INSTRUCTIONS } from '../instructions.js'
 import {
   getModelReasoningCapabilities,
   setSessionReasoning,
@@ -505,9 +507,13 @@ export function registerStatusRoutes(ctx, state) {
         blob = await store.loadBlob(ref)
         blob = await store.ensureFresh(provider, blob, ref)
       } catch (e) {
-        const latencyMs = Date.now() - t0
+        const latencyMs = Math.max(1, Date.now() - t0)
+        const latencyGrade = latencyMs < 250 ? 'good' : (latencyMs < 750 ? 'fair' : 'poor')
+        if (typeof store.rememberPing === "function") store.rememberPing(ref, { latencyMs, latencyGrade })
+        const docVerdict = diagnoseVendorError(e, provider, blob)
+        if (typeof store.rememberDoctorVerdict === "function") store.rememberDoctorVerdict(ref, docVerdict)
         history.add({ provider, ref, path: "/smoke", status: 401, ms: latencyMs })
-        writeJson(res, 502, { ok: false, provider, index, ref, latencyMs, error: { code: 'auth_failed', message: String(e && e.message || e) } })
+        writeJson(res, 502, { ok: false, provider, index, ref, latencyMs, latencyGrade, doctor: docVerdict, error: { code: 'auth_failed', message: String(e && e.message || e) } })
         return
       }
 
@@ -525,7 +531,10 @@ export function registerStatusRoutes(ctx, state) {
         }
         try {
           await vendor.check(blob, vendorConfig(provider, live()), probeFetch)
-          const latencyMs = Date.now() - t0
+          const latencyMs = Math.max(1, Date.now() - t0)
+          const latencyGrade = latencyMs < 250 ? 'good' : (latencyMs < 750 ? 'fair' : 'poor')
+          if (typeof store.rememberPing === "function") store.rememberPing(ref, { latencyMs, latencyGrade })
+          if (typeof store.rememberDoctorVerdict === "function") store.rememberDoctorVerdict(ref, null)
           history.add({ provider, ref, path: "/smoke", status: 200, ms: latencyMs })
           writeJson(res, 200, {
             ok: true,
@@ -533,6 +542,7 @@ export function registerStatusRoutes(ctx, state) {
             index,
             ref,
             latencyMs,
+            latencyGrade,
             label: pmL(blob.label),
             email: pmE(blob.email),
             quota: capturedQuota || info.quota || null,
@@ -540,7 +550,11 @@ export function registerStatusRoutes(ctx, state) {
           })
           return
         } catch (e) {
-          const latencyMs = Date.now() - t0
+          const latencyMs = Math.max(1, Date.now() - t0)
+          const latencyGrade = latencyMs < 250 ? 'good' : (latencyMs < 750 ? 'fair' : 'poor')
+          if (typeof store.rememberPing === "function") store.rememberPing(ref, { latencyMs, latencyGrade })
+          const docVerdict = diagnoseVendorError(e, provider, blob)
+          if (typeof store.rememberDoctorVerdict === "function") store.rememberDoctorVerdict(ref, docVerdict)
           history.add({ provider, ref, path: "/smoke", status: 502, ms: latencyMs })
           writeJson(res, 502, {
             ok: false,
@@ -548,13 +562,18 @@ export function registerStatusRoutes(ctx, state) {
             index,
             ref,
             latencyMs,
+            latencyGrade,
+            doctor: docVerdict,
             error: { code: e && e.code ? e.code : 'VENDOR', message: String(e && e.message || e).slice(0, 300) },
           })
           return
         }
       }
 
-      const latencyMs = Date.now() - t0
+      const latencyMs = Math.max(1, Date.now() - t0)
+      const latencyGrade = latencyMs < 250 ? 'good' : (latencyMs < 750 ? 'fair' : 'poor')
+      if (typeof store.rememberPing === "function") store.rememberPing(ref, { latencyMs, latencyGrade })
+      if (typeof store.rememberDoctorVerdict === "function") store.rememberDoctorVerdict(ref, null)
       history.add({ provider, ref, path: "/smoke", status: 200, ms: latencyMs })
       writeJson(res, 200, {
         ok: true,
@@ -562,6 +581,7 @@ export function registerStatusRoutes(ctx, state) {
         index,
         ref,
         latencyMs,
+        latencyGrade,
         label: pmL(blob.label),
         email: pmE(blob.email),
         quota: info.quota || null,
@@ -569,6 +589,80 @@ export function registerStatusRoutes(ctx, state) {
     }),
   }), 'dsh-subscriptions: /smoke')
 
+  // Issue #542: Latency RTT ping test endpoint
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/ping',
+    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 payload = {}
+      try { payload = JSON.parse((await readBody(req, 64 * 1024)).toString('utf8') || '{}') } catch { /* ignore ping payload */ }
+      const provider = payload.provider
+      const index = payload.index || 1
+      if (!provider || !isProvider(provider)) {
+        writeJson(res, 400, { ok: false, error: { code: 'invalid_provider', message: 'Provider required' } })
+        return
+      }
+      const ref = oauthRef(provider, index)
+      const info = await store.describeRef(ref)
+      if (!info.configured) {
+        writeJson(res, 400, { ok: false, error: { code: 'not_configured', message: 'Account is not configured' } })
+        return
+      }
+      const t0 = Date.now()
+      let latencyMs = 0
+      let latencyGrade = 'good'
+      try {
+        const blob = await store.loadBlob(ref)
+        const vendor = getVendor(provider)
+        const cfg = vendorConfig(provider, live())
+        const doFetch = (typeof fetchForRef === 'function' && fetchForRef(ref)) || fetch
+        if (typeof vendor.check === 'function') {
+          await vendor.check(blob, cfg, doFetch)
+        } else if (typeof vendor.listModels === 'function') {
+          await vendor.listModels(blob, cfg, doFetch)
+        }
+        latencyMs = Math.max(1, Date.now() - t0)
+        latencyGrade = latencyMs < 250 ? 'good' : (latencyMs < 750 ? 'fair' : 'poor')
+        if (typeof store.rememberPing === 'function') store.rememberPing(ref, { latencyMs, latencyGrade })
+        if (typeof store.rememberDoctorVerdict === 'function') store.rememberDoctorVerdict(ref, null)
+        writeJson(res, 200, { ok: true, provider, index, ref, latencyMs, latencyGrade })
+      } catch (err) {
+        latencyMs = Math.max(1, Date.now() - t0)
+        latencyGrade = 'poor'
+        const doc = diagnoseVendorError(err, provider)
+        if (typeof store.rememberPing === 'function') store.rememberPing(ref, { latencyMs, latencyGrade })
+        if (typeof store.rememberDoctorVerdict === 'function') store.rememberDoctorVerdict(ref, doc)
+        writeJson(res, 502, { ok: false, provider, index, ref, latencyMs, latencyGrade, doctor: doc, error: { message: String(err && err.message || err) } })
+      }
+    }),
+  }), 'dsh-subscriptions: /ping')
+
+  // Issue #540: Dynamic vendor instructions API
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/instructions',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'GET') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'GET only' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req, ctx)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'same-origin only' } })
+        return
+      }
+      writeJson(res, 200, { ok: true, instructions: INSTRUCTIONS })
+    }),
+  }), 'dsh-subscriptions: /instructions')
+
+
   // #351: Quota and session alerts API
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',

package/lib/scope-inspector.js

@@ -0,0 +1,51 @@
+export const REQUIRED_SCOPES = {
+  antigravity: [
+    { scope: "https://www.googleapis.com/auth/cloud-platform", description: "Google Cloud Platform & Code Assist" },
+  ],
+  codex: [
+    { scope: "openid", description: "OpenID authentication" },
+    { scope: "https://api.openai.com/auth", description: "ChatGPT API authorization" },
+  ],
+  claude: [
+    { scope: "user:profile", description: "Anthropic user profile" },
+  ],
+  copilot: [
+    { scope: "read:user", description: "GitHub user read" },
+  ],
+  grok: [
+    { scope: "openid", description: "OpenID authentication" },
+  ],
+}
+
+/**
+ * Inspect scopes granted by provider against required scopes.
+ * @param {string} provider
+ * @param {string[]|string} rawScopes
+ * @returns {{ scopes: string[], valid: boolean, missing: string[], warning: string, scopeWarning: string }}
+ */
+export function inspectScopes(provider, rawScopes) {
+  const scopes = Array.isArray(rawScopes)
+    ? rawScopes.map(String).filter(Boolean)
+    : String(rawScopes || "").split(/[\s,]+/).filter(Boolean)
+
+  const reqList = REQUIRED_SCOPES[provider] || []
+  if (reqList.length === 0 || scopes.length === 0) {
+    return { scopes, valid: true, missing: [], warning: "", scopeWarning: "" }
+  }
+
+  const missing = reqList.filter((r) =>
+    !scopes.some((s) => s.toLowerCase() === r.scope.toLowerCase())
+  )
+
+  const warning = missing.length > 0
+    ? `Missing required OAuth scope: ${missing.map((m) => m.description || m.scope).join(", ")}`
+    : ""
+
+  return {
+    scopes,
+    valid: missing.length === 0,
+    missing: missing.map((m) => m.scope),
+    warning,
+    scopeWarning: warning,
+  }
+}