free-coding-models 0.3.11 → 0.3.12

package/src/product-flags.js

@@ -0,0 +1,14 @@
+/**
+ * @file src/product-flags.js
+ * @description Product-level copy for temporarily unavailable surfaces.
+ *
+ * @details
+ *   📖 The proxy bridge is being rebuilt from scratch. The main TUI still
+ *   📖 shows a clear status line so users know the missing integration is
+ *   📖 intentional instead of silently broken.
+ *
+ * @exports PROXY_DISABLED_NOTICE
+ */
+
+// 📖 Public note rendered in the main TUI footer and reused in CLI/runtime guards.
+export const PROXY_DISABLED_NOTICE = 'ℹ️ Proxy is temporarily disabled while we rebuild it into a much more stable bridge for external tools.'

package/src/render-helpers.js

@@ -10,7 +10,6 @@
  *   - Overlay viewport management (scrolling, clamping, visibility)
  *   - Table viewport calculation
  *   - Sorting with pinned favorites and recommendations
- *   - Proxy status rendering
  *
  *   🎯 Key features:
  *   - Emoji-aware display width calculation without external dependencies
@@ -19,7 +18,6 @@
  *   - Overlay viewport helpers (clamp, slice, scroll target visibility)
  *   - Table viewport calculation with scroll indicators
  *   - Sorting with pinned favorites/recommendations at top
- *   - Proxy status formatting
  *
  *   → Functions:
  *   - `stripAnsi`: Remove ANSI color codes to estimate visible text width
@@ -32,13 +30,12 @@
  *   - `sliceOverlayLines`: Slice lines to viewport and pad with blanks
  *   - `calculateViewport`: Compute visible slice of model rows
  *   - `sortResultsWithPinnedFavorites`: Sort with pinned items at top
- *   - `renderProxyStatusLine`: Format proxy status for footer display
  *   - `adjustScrollOffset`: Clamp scrollOffset so cursor stays visible
  *
  *   📦 Dependencies:
  *   - chalk: Terminal colors and formatting
  *   - ../src/constants.js: OVERLAY_PANEL_WIDTH, TABLE_FIXED_LINES
- *   - ../src/utils.js: sortResults, getProxyStatusInfo
+ *   - ../src/utils.js: sortResults
  *
  *   ⚙️ Configuration:
  *   - OVERLAY_PANEL_WIDTH: Fixed width for overlay panels (from constants.js)
@@ -50,7 +47,7 @@
 
 import chalk from 'chalk'
 import { OVERLAY_PANEL_WIDTH, TABLE_FIXED_LINES } from './constants.js'
-import { sortResults, getProxyStatusInfo } from './utils.js'
+import { sortResults } from './utils.js'
 
 // 📖 stripAnsi: Remove ANSI color/control sequences to estimate visible text width before padding.
 // 📖 Strips CSI sequences (SGR colors) and OSC sequences (hyperlinks).
@@ -189,35 +186,6 @@ export function sortResultsWithPinnedFavorites(results, sortColumn, sortDirectio
   return [...bothRows, ...recommendedRows, ...favoriteRows, ...nonSpecialRows]
 }
 
-// ─── Proxy status rendering ───────────────────────────────────────────────────
-
-// 📖 renderProxyStatusLine: Maps proxyStartupStatus + active proxy into a chalk-coloured footer line.
-// 📖 Always returns a non-empty string (no hidden states) so the footer row is always present.
-// 📖 Delegates state classification to the pure getProxyStatusInfo helper (testable in utils.js).
-export function renderProxyStatusLine(proxyStartupStatus, proxyInstance, proxyEnabled = false) {
-  const activeStatus = typeof proxyInstance?.getStatus === 'function' ? proxyInstance.getStatus() : null
-  const hasLiveProxy = Boolean(proxyInstance) && activeStatus?.running !== false
-  const info = getProxyStatusInfo(proxyStartupStatus, hasLiveProxy, proxyEnabled)
-  const neonGreen = chalk.rgb(57, 255, 20)
-  switch (info.state) {
-    case 'starting':
-      return chalk.dim('  ') + chalk.yellow('⟳ Proxy') + chalk.dim(' starting…')
-    case 'running': {
-      const resolvedPort = info.port ?? activeStatus?.port ?? activeStatus?.listeningPort ?? null
-      const resolvedAccountCount = info.accountCount ?? activeStatus?.accountCount ?? proxyInstance?._accounts?.length ?? null
-      const portPart  = resolvedPort ? chalk.dim(` :${resolvedPort}`) : ''
-      const acctPart  = resolvedAccountCount != null ? chalk.dim(` · ${resolvedAccountCount} account${resolvedAccountCount === 1 ? '' : 's'}`) : ''
-      return chalk.dim('  ') + neonGreen('🔀 Proxy running') + portPart + acctPart
-    }
-    case 'failed':
-      return chalk.dim('  ') + chalk.red('🔀 Proxy Stopped') + chalk.dim(` — ${info.reason}`)
-    case 'configured':
-      return chalk.dim('  ') + chalk.cyan('🔀 Proxy configured') + chalk.dim(' — OpenCode rotation')
-    default:
-      return chalk.dim('  ') + chalk.red('🔀 Proxy Stopped')
-  }
-}
-
 // ─── Scroll offset adjustment ──────────────────────────────────────────────────
 
 // 📖 adjustScrollOffset: Clamp scrollOffset so cursor is always within the visible viewport window.

package/src/render-table.js

@@ -13,13 +13,11 @@
  *   - Emoji-aware padding via padEndDisplay for aligned verdict/status cells
  *   - Viewport clipping with above/below indicators
  *   - Smart badges (mode, tier filter, origin filter)
- *   - Footer J badge: green "Proxy On" / red "Proxy Off" indicator with direct overlay access
  *   - Install-endpoints shortcut surfaced directly in the footer hints
  *   - Full-width red outdated-version banner when a newer npm release is known
  *   - Distinct auth-failure vs missing-key health labels so configured providers stay honest
  *
  *   → Functions:
- *   - `setActiveProxy` — Provide the active proxy instance for footer status rendering
  *   - `renderTable` — Render the full TUI table as a string (no side effects)
  *
  *   📦 Dependencies:
@@ -28,7 +26,7 @@
  *   - ../src/tier-colors.js: TIER_COLOR
  *   - ../src/utils.js: getAvg, getVerdict, getUptime, getStabilityScore
  *   - ../src/ping.js: usagePlaceholderForProvider
- *   - ../src/render-helpers.js: calculateViewport, sortResultsWithPinnedFavorites, renderProxyStatusLine, padEndDisplay
+ *   - ../src/render-helpers.js: calculateViewport, sortResultsWithPinnedFavorites, padEndDisplay
  *
  *   @see bin/free-coding-models.js — main entry point that calls renderTable
  */
@@ -43,6 +41,7 @@ import { usagePlaceholderForProvider } from './ping.js'
 import { formatTokenTotalCompact } from './token-usage-reader.js'
 import { calculateViewport, sortResultsWithPinnedFavorites, padEndDisplay, displayWidth } from './render-helpers.js'
 import { getToolMeta } from './tool-metadata.js'
+import { PROXY_DISABLED_NOTICE } from './product-flags.js'
 
 const ACTIVE_FILTER_BG_BY_TIER = {
   'S+': [57, 255, 20],
@@ -84,16 +83,8 @@ export const PROVIDER_COLOR = {
   iflow: [220, 231, 117],
 }
 
-// 📖 Active proxy reference for footer status line (set by bin/free-coding-models.js).
-let activeProxyRef = null
-
-// 📖 setActiveProxy: Store active proxy instance for renderTable footer line.
-export function setActiveProxy(proxyInstance) {
-  activeProxyRef = proxyInstance
-}
-
 // ─── renderTable: mode param controls footer hint text (opencode vs openclaw) ─────────
-export function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, terminalCols = 0, originFilterMode = 0, proxyStartupStatus = null, pingMode = 'normal', pingModeSource = 'auto', hideUnconfiguredModels = false, widthWarningStartedAt = null, widthWarningDismissed = false, widthWarningShowCount = 0, settingsUpdateState = 'idle', settingsUpdateLatestVersion = null, proxyEnabled = false, startupLatestVersion = null, versionAlertsEnabled = true, disableWidthsWarning = false) {
+export function renderTable(results, pendingPings, frame, cursor = null, sortColumn = 'avg', sortDirection = 'asc', pingInterval = PING_INTERVAL, lastPingTime = Date.now(), mode = 'opencode', tierFilterMode = 0, scrollOffset = 0, terminalRows = 0, terminalCols = 0, originFilterMode = 0, legacyStatus = null, pingMode = 'normal', pingModeSource = 'auto', hideUnconfiguredModels = false, widthWarningStartedAt = null, widthWarningDismissed = false, widthWarningShowCount = 0, settingsUpdateState = 'idle', settingsUpdateLatestVersion = null, legacyFlag = false, startupLatestVersion = null, versionAlertsEnabled = true, disableWidthsWarning = false) {
   // 📖 Filter out hidden models for display
   const visibleResults = results.filter(r => !r.hidden)
 
@@ -561,7 +552,7 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     const usageCell = ''
 
     // 📖 Used column — total historical prompt+completion tokens consumed for this
-    // 📖 exact provider/model pair, loaded once from request-log.jsonl at startup.
+    // 📖 exact provider/model pair, loaded from the local usage snapshot file at startup.
     const tokenTotal = Number(r.totalTokens) || 0
     const tokensCell = tokenTotal > 0
       ? chalk.rgb(120, 210, 255)(formatTokenTotalCompact(tokenTotal).padEnd(W_TOKENS))
@@ -595,8 +586,6 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
   const activeHotkey = (keyLabel, text, bg = [57, 255, 20], fg = [0, 0, 0]) => chalk.bgRgb(...bg).rgb(...fg)(` ${keyLabel}${text} `)
   // 📖 Line 1: core navigation + filtering shortcuts
   lines.push(
-    (proxyEnabled ? activeHotkey('J', ' 📡 FCM Proxy V2 On') : activeHotkey('J', ' 📡 FCM Proxy V2 Off', [180, 30, 30], [255, 255, 255])) +
-    chalk.dim(`  •  `) +
     hotkey('F', ' Toggle Favorite') +
     chalk.dim(`  •  `) +
     (tierFilterMode > 0
@@ -609,13 +598,11 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     chalk.dim(`  •  `) +
     (hideUnconfiguredModels ? activeHotkey('E', ' Configured Models Only') : hotkey('E', ' Configured Models Only')) +
     chalk.dim(`  •  `) +
-    hotkey('X', ' Token Logs') +
-    chalk.dim(`  •  `) +
     hotkey('P', ' Settings') +
     chalk.dim(`  •  `) +
     hotkey('K', ' Help')
   )
-  // 📖 Line 2: install flow, recommend, proxy shortcut, feedback, and extended hints.
+  // 📖 Line 2: install flow, recommend, feedback, and extended hints.
   lines.push(
     chalk.dim(`  `) +
     hotkey('Y', ' Install endpoints') + chalk.dim(`  •  `) +
@@ -654,6 +641,11 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
     lines.push(chalk.bgRed.white.bold(paddedBanner))
   }
 
+  // 📖 Stable release notice: keep the bridge rebuild status explicit in the main UI
+  // 📖 so users do not go hunting for hidden controls that are disabled on purpose.
+  const bridgeNotice = chalk.magentaBright.italic(`  ${PROXY_DISABLED_NOTICE}`)
+  lines.push(bridgeNotice)
+
   // 📖 Append \x1b[K (erase to EOL) to each line so leftover chars from previous
   // 📖 frames are cleared. Then pad with blank cleared lines to fill the terminal,
   // 📖 preventing stale content from lingering at the bottom after resize.

package/src/testfcm.js

@@ -18,13 +18,14 @@
  *   → `hasConfiguredKey` — decide whether a config entry really contains an API key
  *   → `createTestfcmRunId` — build a stable timestamp-based run id for artifacts
  *   → `extractJsonPayload` — recover JSON mode output even when logs prefix stdout
+ *   → `pickTestfcmSelectionIndex` — pick the most promising preflight row before sending Enter
  *   → `detectTranscriptFindings` — map raw tool output to actionable failure findings
  *   → `classifyToolTranscript` — classify a run as passed, failed, or inconclusive
  *   → `buildFixTasks` — convert findings into concrete follow-up work items
  *   → `buildTestfcmReport` — render the final Markdown report written under `task/`
  *
  * @exports TESTFCM_TOOL_SPECS, normalizeTestfcmToolName, resolveTestfcmToolSpec
- * @exports hasConfiguredKey, createTestfcmRunId, extractJsonPayload
+ * @exports hasConfiguredKey, createTestfcmRunId, extractJsonPayload, pickTestfcmSelectionIndex
  * @exports detectTranscriptFindings, classifyToolTranscript, buildFixTasks
  * @exports buildTestfcmReport
  */
@@ -35,39 +36,15 @@ export const TESTFCM_TOOL_SPECS = {
     label: 'Crush',
     command: 'crush',
     flag: '--crush',
-    prefersProxy: true,
+    prefersProxy: false,
     configPaths: ['.config/crush/crush.json'],
   },
-  codex: {
-    mode: 'codex',
-    label: 'Codex CLI',
-    command: 'codex',
-    flag: '--codex',
-    prefersProxy: true,
-    configPaths: [],
-  },
-  'claude-code': {
-    mode: 'claude-code',
-    label: 'Claude Code',
-    command: 'claude',
-    flag: '--claude-code',
-    prefersProxy: true,
-    configPaths: [],
-  },
-  gemini: {
-    mode: 'gemini',
-    label: 'Gemini CLI',
-    command: 'gemini',
-    flag: '--gemini',
-    prefersProxy: true,
-    configPaths: ['.gemini/settings.json'],
-  },
   goose: {
     mode: 'goose',
     label: 'Goose',
     command: 'goose',
     flag: '--goose',
-    prefersProxy: true,
+    prefersProxy: false,
     configPaths: ['.config/goose/config.yaml'],
   },
   aider: {
@@ -121,13 +98,17 @@ export const TESTFCM_TOOL_SPECS = {
 }
 
 const TESTFCM_TOOL_ALIASES = {
-  claude: 'claude-code',
-  claudecode: 'claude-code',
-  codexcli: 'codex',
   opencodecli: 'opencode',
 }
 
 const TRANSCRIPT_FINDING_RULES = [
+  {
+    id: 'terminal_too_small',
+    title: 'PTY width warning blocked the TUI flow',
+    severity: 'high',
+    regex: /please maximize your terminal|terminal is too small|reduce font size or maximize width/i,
+    task: 'Run `/testfcm` with the width warning disabled in the isolated config or force a wider PTY before sending Enter.',
+  },
   {
     id: 'tool_missing',
     title: 'Tool binary missing',
@@ -140,21 +121,14 @@ const TRANSCRIPT_FINDING_RULES = [
     title: 'Invalid or missing API auth',
     severity: 'high',
     regex: /invalid api|bad api key|incorrect api key|authentication failed|unauthorized|forbidden|missing api key|no api key|anthropic_auth_token|401\b|403\b/i,
-    task: 'Validate the provider key used by the selected model, then re-run `/testfcm` and inspect the proxy request log for the failing request.',
+    task: 'Validate the provider key used by the selected model, then re-run `/testfcm` and inspect the generated tool config and transcript.',
   },
   {
     id: 'rate_limited',
     title: 'Provider rate limited',
     severity: 'medium',
     regex: /rate limit|too many requests|quota exceeded|429\b/i,
-    task: 'Retry with another configured provider or inspect the retry-after and cooldown handling in the proxy/tool launch flow.',
-  },
-  {
-    id: 'proxy_failure',
-    title: 'Proxy startup or routing failure',
-    severity: 'high',
-    regex: /failed to start proxy|proxy mode .* required|selected model may not exist|routing reload is taking longer than expected|proxy launch is blocked/i,
-    task: 'Inspect `request-log.jsonl`, proxy startup messages, and the isolated config to verify the tool can reach the local FCM proxy.',
+    task: 'Retry with another configured provider or inspect cooldown handling in the direct launcher flow.',
   },
   {
     id: 'tool_launch_failed',
@@ -211,7 +185,9 @@ export function hasConfiguredKey(value) {
 }
 
 /**
- * 📖 Build an artifact-friendly run id such as `20260316-184512`.
+ * 📖 Build an artifact-friendly run id such as `20260316-184512-123`.
+ * 📖 Milliseconds keep concurrent `/testfcm` runs from clobbering each other's
+ * 📖 reports and isolated HOME directories when they start in the same second.
  *
  * @param {Date} [date]
  * @returns {string}
@@ -219,10 +195,11 @@ export function hasConfiguredKey(value) {
 export function createTestfcmRunId(date = new Date()) {
   const iso = date.toISOString()
   return iso
-    .replace(/\.\d{3}Z$/, '')
+    .replace(/Z$/, '')
     .replace(/:/g, '')
     .replace(/-/g, '')
     .replace('T', '-')
+    .replace(/\.(\d{3})$/, '-$1')
 }
 
 /**
@@ -246,6 +223,76 @@ export function extractJsonPayload(text) {
   return null
 }
 
+/**
+ * 📖 Pick the best row to highlight before the runner presses Enter.
+ * 📖 The TUI and `--json` share the same sorted result order, so picking the
+ * 📖 first clearly healthy row from the preflight is a cheap way to avoid
+ * 📖 wasting E2E runs on obviously dead or auth-failing models.
+ *
+ * @param {Array<{ label?: string, status?: string, httpCode?: string }>} results
+ * @param {{ preferProxy?: boolean }} [options]
+ * @returns {number}
+ */
+export function pickTestfcmSelectionIndex(results, options = {}) {
+  if (!Array.isArray(results) || results.length === 0) return 0
+
+  if (options.preferProxy === true) {
+    const groups = new Map()
+
+    for (let index = 0; index < results.length; index++) {
+      const row = results[index]
+      const label = typeof row?.label === 'string' ? row.label.trim() : ''
+      if (!label) continue
+
+      if (!groups.has(label)) {
+        groups.set(label, {
+          rows: [],
+          hasUp: false,
+          hasAuthFailure: false,
+          hasRateLimit: false,
+          hasNotFound: false,
+        })
+      }
+
+      const group = groups.get(label)
+      const httpCode = String(row?.httpCode || '')
+      group.rows.push({ index, row })
+      if (row?.status === 'up') group.hasUp = true
+      if (row?.status === 'auth_error' || httpCode === '401' || httpCode === '403') group.hasAuthFailure = true
+      if (httpCode === '429') group.hasRateLimit = true
+      if (httpCode === '404') group.hasNotFound = true
+    }
+
+    for (const row of results) {
+      const label = typeof row?.label === 'string' ? row.label.trim() : ''
+      const group = groups.get(label)
+      if (!group?.hasUp) continue
+      if (group.hasAuthFailure || group.hasRateLimit || group.hasNotFound) continue
+      const target = group.rows.find((entry) => entry.row?.status === 'up')
+      if (target) return target.index
+    }
+
+    for (const row of results) {
+      const label = typeof row?.label === 'string' ? row.label.trim() : ''
+      const group = groups.get(label)
+      if (!group?.hasUp || group.hasAuthFailure) continue
+      const target = group.rows.find((entry) => entry.row?.status === 'up')
+      if (target) return target.index
+    }
+  }
+
+  const exactUpIndex = results.findIndex((row) => row?.status === 'up' && String(row?.httpCode || '') === '200')
+  if (exactUpIndex >= 0) return exactUpIndex
+
+  const upIndex = results.findIndex((row) => row?.status === 'up')
+  if (upIndex >= 0) return upIndex
+
+  const okCodeIndex = results.findIndex((row) => String(row?.httpCode || '') === '200')
+  if (okCodeIndex >= 0) return okCodeIndex
+
+  return 0
+}
+
 /**
  * 📖 Detect known failure patterns in the raw tool transcript.
  *
@@ -409,14 +456,14 @@ export function buildTestfcmReport(input) {
   }
   lines.push('')
 
-  lines.push('## Request Log Summary')
+  lines.push('## Runtime Diagnostics')
   lines.push('')
   if (requestLogSummary.length > 0) {
     for (const entry of requestLogSummary) {
       lines.push(`- ${entry}`)
     }
   } else {
-    lines.push('- No proxy request log entry was captured for this run.')
+    lines.push('- No extra runtime diagnostic summary was captured for this run.')
   }
   lines.push('')
 

package/src/token-usage-reader.js

@@ -1,6 +1,6 @@
 /**
  * @file token-usage-reader.js
- * @description Reads historical token usage from request-log.jsonl and aggregates it by exact provider + model pair.
+ * @description Reads historical token usage snapshots and aggregates them by exact provider + model pair.
  *
  * @details
  *   The TUI already shows live latency and quota state, but that does not tell
@@ -9,27 +9,22 @@
  *   `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.
+ *   - `token-stats.json` is the only remaining source of truth for historical
+ *     totals now that the older JSONL accounting pipeline has been removed.
  *   - 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
+ *   → `loadTokenUsageByProviderModel` — reads token snapshots and returns total tokens by provider+model
  *   → `formatTokenTotalCompact` — renders totals as raw ints or compact K / M strings with 2 decimals
  *
  * @exports buildProviderModelTokenKey, loadTokenUsageByProviderModel, formatTokenTotalCompact
- *
- * @see src/log-reader.js
  * @see src/render-table.js
  */
 
 import { readFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
-import { loadRecentLogs } from './log-reader.js'
 
 const DEFAULT_DATA_DIR = join(homedir(), '.free-coding-models')
 const STATS_FILE = join(DEFAULT_DATA_DIR, 'token-stats.json')
@@ -40,23 +35,11 @@ export function buildProviderModelTokenKey(providerKey, modelId) {
   return `${providerKey}::${modelId}`
 }
 
-// 📖 loadTokenUsageByProviderModel prioritizes token-stats.json for accurate
-// 📖 historical totals. If missing, it falls back to parsing the bounded log history.
-export function loadTokenUsageByProviderModel({ logFile, statsFile = STATS_FILE, limit = 50_000 } = {}) {
-  // 📖 If a custom logFile is provided (Test Mode), ONLY use that file.
-  if (logFile) {
-    const testTotals = {}
-    const rows = loadRecentLogs({ logFile, limit })
-    for (const row of rows) {
-      const key = buildProviderModelTokenKey(row.provider, row.model)
-      testTotals[key] = (testTotals[key] || 0) + (Number(row.tokens) || 0)
-    }
-    return testTotals
-  }
-
+// 📖 loadTokenUsageByProviderModel reads the aggregated stats file produced by
+// 📖 the quota/accounting pipeline. Missing or malformed files are treated as empty.
+export function loadTokenUsageByProviderModel({ statsFile = STATS_FILE } = {}) {
   const totals = {}
 
-  // 📖 Phase 1: Try to load from the aggregated stats file (canonical source for totals)
   try {
     if (existsSync(statsFile)) {
       const stats = JSON.parse(readFileSync(statsFile, 'utf8'))
@@ -78,24 +61,12 @@ export function loadTokenUsageByProviderModel({ logFile, statsFile = STATS_FILE,
         }
       }
     }
-  } catch (err) {
-    // 📖 Silently fall back to log parsing if stats file is corrupt or unreadable
-  }
-
-  // 📖 Phase 2: Supplement with recent log entries if totals are still empty
-  // 📖 (e.g. fresh install or token-stats.json deleted)
-  if (Object.keys(totals).length === 0) {
-    const rows = loadRecentLogs({ limit })
-    for (const row of rows) {
-      const key = buildProviderModelTokenKey(row.provider, row.model)
-      totals[key] = (totals[key] || 0) + (Number(row.tokens) || 0)
-    }
-  }
+  } catch {}
 
   return totals
 }
 
-// 📖 formatTokenTotalCompact keeps token counts readable in both the table and log view:
+// 📖 formatTokenTotalCompact keeps token counts readable in the table:
 // 📖 0-999 => raw integer, 1k-999k => N.NNk, 1m+ => N.NNM.
 export function formatTokenTotalCompact(totalTokens) {
   const safeTotal = Number(totalTokens) || 0