free-coding-models 0.1.83 → 0.1.85

package/src/token-usage-reader.js

@@ -0,0 +1,63 @@
+/**
+ * @file token-usage-reader.js
+ * @description Reads historical token usage from request-log.jsonl and aggregates it by exact provider + model pair.
+ *
+ * @details
+ *   The TUI already shows live latency and quota state, but that does not tell
+ *   you how much you've actually consumed on a given Origin. This module reads
+ *   the persistent JSONL request log once at startup and builds a compact
+ *   `provider::model -> totalTokens` map for table display.
+ *
+ *   Why this exists:
+ *   - `token-stats.json` keeps convenience aggregates, but not the exact
+ *     provider+model sum needed for the new table column.
+ *   - `request-log.jsonl` is the source of truth because every proxied request
+ *     records prompt and completion token counts with provider context.
+ *   - Startup-only parsing keeps runtime overhead negligible during TUI redraws.
+ *
+ * @functions
+ *   → `buildProviderModelTokenKey` — creates a stable aggregation key
+ *   → `loadTokenUsageByProviderModel` — reads request-log.jsonl and returns total tokens by provider+model
+ *   → `formatTokenTotalCompact` — renders totals as integer K / M strings for narrow columns
+ *
+ * @exports buildProviderModelTokenKey, loadTokenUsageByProviderModel, formatTokenTotalCompact
+ *
+ * @see src/log-reader.js
+ * @see src/render-table.js
+ */
+
+import { loadRecentLogs } from './log-reader.js'
+
+// 📖 buildProviderModelTokenKey keeps provider-scoped totals isolated even when
+// 📖 multiple Origins expose the same model ID.
+export function buildProviderModelTokenKey(providerKey, modelId) {
+  return `${providerKey}::${modelId}`
+}
+
+// 📖 loadTokenUsageByProviderModel reads the full bounded log history available
+// 📖 through log-reader and sums tokens per exact provider+model pair.
+export function loadTokenUsageByProviderModel({ logFile, limit = 50_000 } = {}) {
+  const rows = loadRecentLogs({ logFile, limit })
+  const totals = {}
+
+  for (const row of rows) {
+    const providerKey = typeof row.provider === 'string' ? row.provider : 'unknown'
+    const modelId = typeof row.model === 'string' ? row.model : 'unknown'
+    const tokens = Number(row.tokens) || 0
+    if (tokens <= 0) continue
+
+    const key = buildProviderModelTokenKey(providerKey, modelId)
+    totals[key] = (totals[key] || 0) + tokens
+  }
+
+  return totals
+}
+
+// 📖 formatTokenTotalCompact keeps the new column narrow and scannable:
+// 📖 0-999 => raw integer, 1k-999k => Nk, 1m+ => NM, no decimals.
+export function formatTokenTotalCompact(totalTokens) {
+  const safeTotal = Number(totalTokens) || 0
+  if (safeTotal >= 1_000_000) return `${Math.floor(safeTotal / 1_000_000)}M`
+  if (safeTotal >= 1_000) return `${Math.floor(safeTotal / 1_000)}k`
+  return String(Math.floor(safeTotal))
+}

package/src/updater.js

@@ -0,0 +1,237 @@
+/**
+ * @file updater.js
+ * @description Update detection and installation helpers, extracted from bin/free-coding-models.js.
+ *
+ * @details
+ *   This module handles all npm version-check and auto-update logic:
+ *
+ *   - `checkForUpdateDetailed()` — hits the npm registry to compare the published version
+ *     against the locally installed one.  Returns `{ latestVersion, error }` so callers
+ *     can surface meaningful status text in the Settings overlay.
+ *
+ *   - `checkForUpdate()` — thin backward-compatible wrapper used at startup for the
+ *     auto-update guard.  Returns `latestVersion` (string) or `null`.
+ *
+ *   - `runUpdate(latestVersion)` — runs `npm i -g free-coding-models@<version> --prefer-online`,
+ *     retrying with `sudo` on EACCES/EPERM.  On success, relaunches the process with the
+ *     same argv.  On failure, prints manual instructions and exits with code 1.
+ *     Uses `require('child_process').execSync` inline because ESM dynamic import is async
+ *     but `execSync` must block to give `stdio: 'inherit'` feedback in the terminal.
+ *
+ *   - `promptUpdateNotification(latestVersion)` — renders a small centered interactive menu
+ *     that lets the user choose: Update Now / Read Changelogs / Continue without update.
+ *     Uses raw mode readline keypress events (same pattern as the main TUI).
+ *     This function is called BEFORE the alt-screen is entered, so it writes to the
+ *     normal terminal buffer.
+ *
+ *   ⚙️ Notes:
+ *   - `LOCAL_VERSION` is resolved from package.json via `createRequire` so this module
+ *     can be imported independently from the bin entry point.
+ *   - The auto-update flow in `main()` skips update if `isDevMode` is detected (presence of
+ *     a `.git` directory next to the package root) to avoid an infinite update loop in dev.
+ *
+ * @functions
+ *   → checkForUpdateDetailed()           — Fetch npm latest with explicit error info
+ *   → checkForUpdate()                   — Startup wrapper, returns version string or null
+ *   → runUpdate(latestVersion)           — Install new version via npm global + relaunch
+ *   → promptUpdateNotification(version)  — Interactive pre-TUI update menu
+ *
+ * @exports
+ *   checkForUpdateDetailed, checkForUpdate, runUpdate, promptUpdateNotification
+ *
+ * @see bin/free-coding-models.js — calls checkForUpdate() at startup and runUpdate() on confirm
+ */
+
+import chalk from 'chalk'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+const readline = require('readline')
+const pkg = require('../package.json')
+const LOCAL_VERSION = pkg.version
+
+/**
+ * 📖 checkForUpdateDetailed: Fetch npm latest version with explicit error details.
+ * 📖 Used by settings manual-check flow to display meaningful status in the UI.
+ * @returns {Promise<{ latestVersion: string|null, error: string|null }>}
+ */
+export async function checkForUpdateDetailed() {
+  try {
+    const res = await fetch('https://registry.npmjs.org/free-coding-models/latest', { signal: AbortSignal.timeout(5000) })
+    if (!res.ok) return { latestVersion: null, error: `HTTP ${res.status}` }
+    const data = await res.json()
+    if (data.version && data.version !== LOCAL_VERSION) return { latestVersion: data.version, error: null }
+    return { latestVersion: null, error: null }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error'
+    return { latestVersion: null, error: message }
+  }
+}
+
+/**
+ * 📖 checkForUpdate: Backward-compatible wrapper for startup update prompt.
+ * @returns {Promise<string|null>}
+ */
+export async function checkForUpdate() {
+  const { latestVersion } = await checkForUpdateDetailed()
+  return latestVersion
+}
+
+/**
+ * 📖 runUpdate: Run npm global install to update to latestVersion.
+ * 📖 Retries with sudo on permission errors.
+ * 📖 Relaunches the process on success, exits with code 1 on failure.
+ * @param {string} latestVersion
+ */
+export function runUpdate(latestVersion) {
+  const { execSync } = require('child_process')
+  console.log()
+  console.log(chalk.bold.cyan('  ⬆ Updating free-coding-models to v' + latestVersion + '...'))
+  console.log()
+
+  try {
+    // 📖 Force install from npm registry (ignore local cache)
+    // 📖 Use --prefer-online to ensure we get the latest published version
+    execSync(`npm i -g free-coding-models@${latestVersion} --prefer-online`, { stdio: 'inherit' })
+    console.log()
+    console.log(chalk.green('  ✅ Update complete! Version ' + latestVersion + ' installed.'))
+    console.log()
+    console.log(chalk.dim('  🔄 Restarting with new version...'))
+    console.log()
+
+    // 📖 Relaunch automatically with the same arguments
+    const args = process.argv.slice(2)
+    execSync(`node ${process.argv[1]} ${args.join(' ')}`, { stdio: 'inherit' })
+    process.exit(0)
+  } catch (err) {
+    console.log()
+    // 📖 Check if error is permission-related (EACCES or EPERM)
+    const isPermissionError = err.code === 'EACCES' || err.code === 'EPERM' ||
+                             (err.stderr && (err.stderr.includes('EACCES') || err.stderr.includes('permission') ||
+                                              err.stderr.includes('EACCES'))) ||
+                             (err.message && (err.message.includes('EACCES') || err.message.includes('permission')))
+
+    if (isPermissionError) {
+      console.log(chalk.yellow('  ⚠️ Permission denied. Retrying with sudo...'))
+      console.log()
+      try {
+        execSync(`sudo npm i -g free-coding-models@${latestVersion} --prefer-online`, { stdio: 'inherit' })
+        console.log()
+        console.log(chalk.green('  ✅ Update complete with sudo! Version ' + latestVersion + ' installed.'))
+        console.log()
+        console.log(chalk.dim('  🔄 Restarting with new version...'))
+        console.log()
+
+        // 📖 Relaunch automatically with the same arguments
+        const args = process.argv.slice(2)
+        execSync(`node ${process.argv[1]} ${args.join(' ')}`, { stdio: 'inherit' })
+        process.exit(0)
+      } catch (sudoErr) {
+        console.log()
+        console.log(chalk.red('  ✖ Update failed even with sudo. Try manually:'))
+        console.log(chalk.dim('    sudo npm i -g free-coding-models@' + latestVersion))
+        console.log()
+      }
+    } else {
+      console.log(chalk.red('  ✖ Update failed. Try manually: npm i -g free-coding-models@' + latestVersion))
+      console.log()
+    }
+  }
+  process.exit(1)
+}
+
+/**
+ * 📖 promptUpdateNotification: Show a centered interactive menu when a new version is available.
+ * 📖 Returns 'update', 'changelogs', or null (continue without update).
+ * 📖 Called BEFORE entering the alt-screen so it renders in the normal terminal buffer.
+ * @param {string|null} latestVersion
+ * @returns {Promise<'update'|'changelogs'|null>}
+ */
+export async function promptUpdateNotification(latestVersion) {
+  if (!latestVersion) return null
+
+  return new Promise((resolve) => {
+    let selected = 0
+    const options = [
+      {
+        label: 'Update now',
+        icon: '⬆',
+        description: `Update free-coding-models to v${latestVersion}`,
+      },
+      {
+        label: 'Read Changelogs',
+        icon: '📋',
+        description: 'Open GitHub changelog',
+      },
+      {
+        label: 'Continue without update',
+        icon: '▶',
+        description: 'Use current version',
+      },
+    ]
+
+    // 📖 Centered render function
+    const render = () => {
+      process.stdout.write('\x1b[2J\x1b[H') // clear screen + cursor home
+
+      // 📖 Calculate centering
+      const terminalWidth = process.stdout.columns || 80
+      const maxWidth = Math.min(terminalWidth - 4, 70)
+      const centerPad = ' '.repeat(Math.max(0, Math.floor((terminalWidth - maxWidth) / 2)))
+
+      console.log()
+      console.log(centerPad + chalk.bold.red('  ⚠ UPDATE AVAILABLE'))
+      console.log(centerPad + chalk.red(`  Version ${latestVersion} is ready to install`))
+      console.log()
+      console.log(centerPad + chalk.bold('  ⚡ Free Coding Models') + chalk.dim(` v${LOCAL_VERSION}`))
+      console.log()
+
+      for (let i = 0; i < options.length; i++) {
+        const isSelected = i === selected
+        const bullet = isSelected ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
+        const label = isSelected
+          ? chalk.bold.white(options[i].icon + ' ' + options[i].label)
+          : chalk.dim(options[i].icon + ' ' + options[i].label)
+
+        console.log(centerPad + bullet + label)
+        console.log(centerPad + chalk.dim('       ' + options[i].description))
+        console.log()
+      }
+
+      console.log(centerPad + chalk.dim('  ↑↓ Navigate  •  Enter Select  •  Ctrl+C Continue'))
+      console.log()
+    }
+
+    render()
+
+    readline.emitKeypressEvents(process.stdin)
+    if (process.stdin.isTTY) process.stdin.setRawMode(true)
+
+    const onKey = (_str, key) => {
+      if (!key) return
+      if (key.ctrl && key.name === 'c') {
+        if (process.stdin.isTTY) process.stdin.setRawMode(false)
+        process.stdin.removeListener('keypress', onKey)
+        resolve(null) // Continue without update
+        return
+      }
+      if (key.name === 'up' && selected > 0) {
+        selected--
+        render()
+      } else if (key.name === 'down' && selected < options.length - 1) {
+        selected++
+        render()
+      } else if (key.name === 'return') {
+        if (process.stdin.isTTY) process.stdin.setRawMode(false)
+        process.stdin.removeListener('keypress', onKey)
+        process.stdin.pause()
+
+        if (selected === 0) resolve('update')
+        else if (selected === 1) resolve('changelogs')
+        else resolve(null) // Continue without update
+      }
+    }
+
+    process.stdin.on('keypress', onKey)
+  })
+}

package/{lib → src}/usage-reader.js

@@ -1,9 +1,13 @@
 /**
  * @file lib/usage-reader.js
- * @description Pure functions to read model quota usage from token-stats.json.
+ * @description Pure functions to read provider-scoped Usage snapshots from token-stats.json.
  *
- * Designed for TUI consumption: reads the pre-computed `quotaSnapshots.byModel`
- * section from the JSON file written by TokenStats.  Never reads the JSONL log.
+ * Designed for TUI consumption: reads the pre-computed provider-scoped quota
+ * snapshots written by TokenStats. Never reads the JSONL log.
+ *
+ * The UI must distinguish the same model served by different Origins
+ * (for example NVIDIA vs Groq). Because of that, the canonical snapshot source
+ * is `quotaSnapshots.byProviderModel`, not the legacy `byModel` aggregate.
  *
  * All functions are pure (no shared mutable state) and handle missing/malformed
  * files gracefully by returning safe fallback values.
@@ -30,6 +34,7 @@
  * @exports CACHE_TTL_MS
  * @exports clearUsageCache
  * @exports loadUsageSnapshot
+ * @exports buildUsageSnapshotKey
  * @exports loadUsageMap
  * @exports usageForModelId
  * @exports usageForRow
@@ -38,6 +43,7 @@
 import { readFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
+import { supportsUsagePercent, usageResetsDaily } from './quota-capabilities.js'
 
 const DEFAULT_STATS_FILE = join(homedir(), '.free-coding-models', 'token-stats.json')
 
@@ -57,7 +63,7 @@ export const CACHE_TTL_MS = 750
 
 /**
  * Module-level cache: path → { snapshot, expiresAt }
- * @type {Map<string, { snapshot: { byModel: Record<string, number>, byProvider: Record<string, number> }, expiresAt: number }>}
+ * @type {Map<string, { snapshot: { byProviderModel: Record<string, number>, byProvider: Record<string, number>, legacyByModel: Record<string, number> }, expiresAt: number }>}
  */
 const _cache = new Map()
 
@@ -81,13 +87,29 @@ export function clearUsageCache() {
  * @param {number} [nowMs] - optional current time (ms) for testability
  * @returns {boolean}
  */
-function isSnapshotFresh(entry, nowMs = Date.now()) {
+function isSnapshotFresh(entry, nowMs = Date.now(), providerKey = null) {
   if (!entry || typeof entry.updatedAt !== 'string') return true // backward compat
   const updatedMs = Date.parse(entry.updatedAt)
   if (!Number.isFinite(updatedMs)) return true // unparseable: be generous
+  if (providerKey && usageResetsDaily(providerKey)) {
+    const nowDay = new Date(nowMs).toISOString().slice(0, 10)
+    const updatedDay = entry.updatedAt.slice(0, 10)
+    if (updatedDay !== nowDay) return false
+  }
   return nowMs - updatedMs < SNAPSHOT_TTL_MS
 }
 
+/**
+ * Build the canonical map key for one Origin + model pair.
+ *
+ * @param {string} providerKey
+ * @param {string} modelId
+ * @returns {string}
+ */
+export function buildUsageSnapshotKey(providerKey, modelId) {
+  return `${providerKey}::${modelId}`
+}
+
 /**
  * Load token-stats.json and return model/provider usage maps.
  * Entries with stale `updatedAt` (older than SNAPSHOT_TTL_MS) are excluded.
@@ -96,7 +118,7 @@ function isSnapshotFresh(entry, nowMs = Date.now()) {
  * The 30-minute data freshness filter is re-applied on every cache miss (parse).
  *
  * @param {string} [statsFile]
- * @returns {{ byModel: Record<string, number>, byProvider: Record<string, number> }}
+ * @returns {{ byProviderModel: Record<string, number>, byProvider: Record<string, number>, legacyByModel: Record<string, number> }}
  */
 export function loadUsageSnapshot(statsFile = DEFAULT_STATS_FILE) {
   const now = Date.now()
@@ -118,23 +140,40 @@ export function loadUsageSnapshot(statsFile = DEFAULT_STATS_FILE) {
  *
  * @param {string} statsFile
  * @param {number} now - current time in ms (for freshness checks)
- * @returns {{ byModel: Record<string, number>, byProvider: Record<string, number> }}
+ * @returns {{ byProviderModel: Record<string, number>, byProvider: Record<string, number>, legacyByModel: Record<string, number> }}
  */
 function _parseSnapshot(statsFile, now) {
   try {
-    if (!existsSync(statsFile)) return { byModel: {}, byProvider: {} }
+    if (!existsSync(statsFile)) return { byProviderModel: {}, byProvider: {}, legacyByModel: {} }
     const raw = readFileSync(statsFile, 'utf8')
     const data = JSON.parse(raw)
 
+    const byProviderModelSrc = data?.quotaSnapshots?.byProviderModel
     const byModelSrc = data?.quotaSnapshots?.byModel
     const byProviderSrc = data?.quotaSnapshots?.byProvider
 
-    const byModel = {}
+    const byProviderModel = {}
+    if (byProviderModelSrc && typeof byProviderModelSrc === 'object') {
+      for (const [snapshotKey, entry] of Object.entries(byProviderModelSrc)) {
+        const providerKey = typeof entry?.providerKey === 'string'
+          ? entry.providerKey
+          : snapshotKey.split('::', 1)[0]
+        if (!supportsUsagePercent(providerKey)) continue
+        if (entry && typeof entry.quotaPercent === 'number' && Number.isFinite(entry.quotaPercent)) {
+          if (isSnapshotFresh(entry, now, providerKey)) {
+            byProviderModel[snapshotKey] = entry.quotaPercent
+          }
+        }
+      }
+    }
+
+    // 📖 Legacy map kept only for backward compatibility helpers/tests.
+    const legacyByModel = {}
     if (byModelSrc && typeof byModelSrc === 'object') {
       for (const [modelId, entry] of Object.entries(byModelSrc)) {
         if (entry && typeof entry.quotaPercent === 'number' && Number.isFinite(entry.quotaPercent)) {
           if (isSnapshotFresh(entry, now)) {
-            byModel[modelId] = entry.quotaPercent
+            legacyByModel[modelId] = entry.quotaPercent
           }
         }
       }
@@ -143,44 +182,45 @@ function _parseSnapshot(statsFile, now) {
     const byProvider = {}
     if (byProviderSrc && typeof byProviderSrc === 'object') {
       for (const [providerKey, entry] of Object.entries(byProviderSrc)) {
+        if (!supportsUsagePercent(providerKey)) continue
         if (entry && typeof entry.quotaPercent === 'number' && Number.isFinite(entry.quotaPercent)) {
-          if (isSnapshotFresh(entry, now)) {
+          if (isSnapshotFresh(entry, now, providerKey)) {
             byProvider[providerKey] = entry.quotaPercent
           }
         }
       }
     }
 
-    return { byModel, byProvider }
+    return { byProviderModel, byProvider, legacyByModel }
   } catch {
-    return { byModel: {}, byProvider: {} }
+    return { byProviderModel: {}, byProvider: {}, legacyByModel: {} }
   }
 }
 
 /**
- * Load token-stats.json and return a plain object mapping modelId → quotaPercent.
+ * Load token-stats.json and return a plain object mapping provider+model → quotaPercent.
  *
  * Only includes models whose `quotaPercent` is a finite number and whose
  * snapshot is fresh (within SNAPSHOT_TTL_MS).
  * Returns an empty object on any error (missing file, bad JSON, missing keys).
  *
  * @param {string} [statsFile] - Path to token-stats.json (defaults to ~/.free-coding-models/token-stats.json)
- * @returns {Record<string, number>}  e.g. { 'claude-3-5': 80, 'gpt-4o': 45 }
+ * @returns {Record<string, number>}  e.g. { 'groq::openai/gpt-oss-120b': 37 }
  */
 export function loadUsageMap(statsFile = DEFAULT_STATS_FILE) {
-  return loadUsageSnapshot(statsFile).byModel
+  return loadUsageSnapshot(statsFile).byProviderModel
 }
 
 /**
- * Return the quota percent remaining for a specific model.
- * Returns null if the model has no snapshot or its snapshot is stale.
+ * Return the legacy quota percent remaining for a specific modelId.
+ * This helper is retained for backward compatibility tests only.
  *
  * @param {string} modelId
  * @param {string} [statsFile] - Path to token-stats.json (defaults to ~/.free-coding-models/token-stats.json)
  * @returns {number | null}  quota percent (0–100), or null if unknown/stale
  */
 export function usageForModelId(modelId, statsFile = DEFAULT_STATS_FILE) {
-  const map = loadUsageMap(statsFile)
+  const map = loadUsageSnapshot(statsFile).legacyByModel
   const value = map[modelId]
   return value !== undefined ? value : null
 }
@@ -196,8 +236,10 @@ export function usageForModelId(modelId, statsFile = DEFAULT_STATS_FILE) {
  * @returns {number | null}
  */
 export function usageForRow(providerKey, modelId, statsFile = DEFAULT_STATS_FILE) {
-  const { byModel, byProvider } = loadUsageSnapshot(statsFile)
-  if (byModel[modelId] !== undefined) return byModel[modelId]
+  if (!supportsUsagePercent(providerKey)) return null
+  const { byProviderModel, byProvider } = loadUsageSnapshot(statsFile)
+  const providerModelKey = buildUsageSnapshotKey(providerKey, modelId)
+  if (byProviderModel[providerModelKey] !== undefined) return byProviderModel[providerModelKey]
   if (byProvider[providerKey] !== undefined) return byProvider[providerKey]
   return null
 }

package/{lib → src}/utils.js

@@ -74,18 +74,23 @@ export const TIER_LETTER_MAP = {
 
 // ─── Core Logic Functions ────────────────────────────────────────────────────
 
-// 📖 getAvg: Calculate average latency from ONLY successful pings (HTTP 200).
-// 📖 Failed pings (timeouts, 429s, 500s) are excluded to avoid skewing the average.
-// 📖 Returns Infinity when no successful pings exist — this sorts "unknown" models to the bottom.
+// 📖 measureablePingCodes: HTTP codes that still give us a real round-trip latency sample.
+// 📖 200 = normal success, 401 = no key / bad key but the provider endpoint is reachable.
+const measurablePingCodes = new Set(['200', '401'])
+
+// 📖 getAvg: Calculate average latency from pings that produced a real latency sample.
+// 📖 HTTP 200 and 401 both count because a 401 still proves the endpoint responded in X ms.
+// 📖 Timeouts and server failures are excluded to avoid mixing availability with raw latency.
+// 📖 Returns Infinity when no measurable pings exist — this sorts "unknown" models to the bottom.
 // 📖 The rounding to integer avoids displaying fractional milliseconds in the TUI.
 //
 // 📖 Example:
-//   pings = [{ms: 200, code: '200'}, {ms: 0, code: '429'}, {ms: 400, code: '200'}]
-//   → getAvg returns 300 (only the two 200s count: (200+400)/2)
+//   pings = [{ms: 200, code: '200'}, {ms: 320, code: '401'}, {ms: 999, code: '500'}]
+//   → getAvg returns 260 (only the measurable pings count: (200+320)/2)
 export const getAvg = (r) => {
-  const successfulPings = (r.pings || []).filter(p => p.code === '200')
-  if (successfulPings.length === 0) return Infinity
-  return Math.round(successfulPings.reduce((a, b) => a + b.ms, 0) / successfulPings.length)
+  const measurablePings = (r.pings || []).filter(p => measurablePingCodes.has(p.code))
+  if (measurablePings.length === 0) return Infinity
+  return Math.round(measurablePings.reduce((a, b) => a + b.ms, 0) / measurablePings.length)
 }
 
 // 📖 getVerdict: Determine a human-readable health verdict for a model.
@@ -120,16 +125,16 @@ export const getVerdict = (r) => {
   if (avg === Infinity) return 'Pending'
 
   // 📖 Stability-aware verdict: penalize models with good avg but terrible tail latency
-  const successfulPings = (r.pings || []).filter(p => p.code === '200')
+  const measurablePings = (r.pings || []).filter(p => measurablePingCodes.has(p.code))
   const p95 = getP95(r)
 
   if (avg < 400) {
     // 📖 Only flag as "Spiky" when we have enough data (≥3 pings) to judge stability
-    if (successfulPings.length >= 3 && p95 > 3000) return 'Spiky'
+    if (measurablePings.length >= 3 && p95 > 3000) return 'Spiky'
     return 'Perfect'
   }
   if (avg < 1000) {
-    if (successfulPings.length >= 3 && p95 > 5000) return 'Spiky'
+    if (measurablePings.length >= 3 && p95 > 5000) return 'Spiky'
     return 'Normal'
   }
   if (avg < 3000) return 'Slow'
@@ -148,30 +153,30 @@ export const getUptime = (r) => {
   return Math.round((successful / r.pings.length) * 100)
 }
 
-// 📖 getP95: Calculate the 95th percentile latency from successful pings (HTTP 200).
+// 📖 getP95: Calculate the 95th percentile latency from measurable pings (HTTP 200/401).
 // 📖 The p95 answers: "95% of requests are faster than this value."
 // 📖 A low p95 means consistently fast responses — a high p95 signals tail-latency spikes.
-// 📖 Returns Infinity when no successful pings exist.
+// 📖 Returns Infinity when no measurable pings exist.
 //
 // 📖 Algorithm: sort latencies ascending, pick the value at ceil(N * 0.95) - 1.
 // 📖 Example: [100, 200, 300, 400, 5000] → p95 index = ceil(5 * 0.95) - 1 = 4 → 5000ms
 export const getP95 = (r) => {
-  const successfulPings = (r.pings || []).filter(p => p.code === '200')
-  if (successfulPings.length === 0) return Infinity
-  const sorted = successfulPings.map(p => p.ms).sort((a, b) => a - b)
+  const measurablePings = (r.pings || []).filter(p => measurablePingCodes.has(p.code))
+  if (measurablePings.length === 0) return Infinity
+  const sorted = measurablePings.map(p => p.ms).sort((a, b) => a - b)
   const idx = Math.ceil(sorted.length * 0.95) - 1
   return sorted[Math.max(0, idx)]
 }
 
-// 📖 getJitter: Calculate latency standard deviation (σ) from successful pings.
+// 📖 getJitter: Calculate latency standard deviation (σ) from measurable pings.
 // 📖 Low jitter = predictable response times. High jitter = erratic, spiky latency.
-// 📖 Returns 0 when fewer than 2 successful pings (can't compute variance from 1 point).
+// 📖 Returns 0 when fewer than 2 measurable pings (can't compute variance from 1 point).
 // 📖 Uses population σ (divides by N, not N-1) since we have ALL the data, not a sample.
 export const getJitter = (r) => {
-  const successfulPings = (r.pings || []).filter(p => p.code === '200')
-  if (successfulPings.length < 2) return 0
-  const mean = successfulPings.reduce((a, b) => a + b.ms, 0) / successfulPings.length
-  const variance = successfulPings.reduce((sum, p) => sum + (p.ms - mean) ** 2, 0) / successfulPings.length
+  const measurablePings = (r.pings || []).filter(p => measurablePingCodes.has(p.code))
+  if (measurablePings.length < 2) return 0
+  const mean = measurablePings.reduce((a, b) => a + b.ms, 0) / measurablePings.length
+  const variance = measurablePings.reduce((sum, p) => sum + (p.ms - mean) ** 2, 0) / measurablePings.length
   return Math.round(Math.sqrt(variance))
 }
 
@@ -190,14 +195,14 @@ export const getJitter = (r) => {
 //   Model B: avg 400ms, p95 650ms (boringly consistent) → score ~85
 //   In real usage, Model B FEELS faster because it doesn't randomly stall.
 export const getStabilityScore = (r) => {
-  const successfulPings = (r.pings || []).filter(p => p.code === '200')
-  if (successfulPings.length === 0) return -1
+  const measurablePings = (r.pings || []).filter(p => measurablePingCodes.has(p.code))
+  if (measurablePings.length === 0) return -1
 
   const p95 = getP95(r)
   const jitter = getJitter(r)
   const uptime = getUptime(r)
-  const spikeCount = successfulPings.filter(p => p.ms > 3000).length
-  const spikeRate = spikeCount / successfulPings.length
+  const spikeCount = measurablePings.filter(p => p.ms > 3000).length
+  const spikeRate = spikeCount / measurablePings.length
 
   // 📖 Normalize each component to 0–100 (higher = better)
   const p95Score = Math.max(0, Math.min(100, 100 * (1 - p95 / 5000)))