@ipv9/tokentracker-cli 0.39.39 → 0.39.41

package/src/lib/fs.js

@@ -1,4 +1,5 @@
 const fs = require("node:fs/promises");
+const os = require("node:os");
 const path = require("node:path");
 
 async function ensureDir(p) {
@@ -47,37 +48,157 @@ async function chmod600IfPossible(filePath) {
   } catch (_e) {}
 }
 
-const LOCK_STALE_MS = 5 * 60 * 1000; // 5 minutes
+// The holder heartbeats the lock's mtime, so "stale" now means "the holder
+// died", not "the holder is slow". That lets the threshold be generous: the old
+// 5-minute window silently stole the lock from any sync that ran longer than
+// one local-sync tick (full-corpus rebuilds and migration reparses do — see the
+// post-mortem at src/commands/sync.js:74-123), letting two writers interleave
+// appends into queue.jsonl. A torn line is skipped by the reader, and a skipped
+// retraction row is a permanent silent overcount. Issue #89.
+const LOCK_STALE_MS = 30 * 60 * 1000; // 30 minutes
+const LOCK_HEARTBEAT_MS = 30 * 1000; // touch mtime every 30s while held
+const MAX_LOCK_ATTEMPTS = 3;
 
-async function openLock(lockPath, { quietIfLocked }) {
+// mkdir is atomic and exclusive, which makes it a usable mutex on every
+// filesystem we care about. Held only for the few syscalls of a takeover.
+const TAKEOVER_ABANDONED_MS = 60 * 1000;
+
+function takeoverMutexPath(lockPath) {
+  return `${lockPath}.takeover`;
+}
+
+async function acquireTakeoverMutex(lockPath) {
+  const mutexPath = takeoverMutexPath(lockPath);
   try {
-    const handle = await fs.open(lockPath, "wx");
-    return {
-      async release() {
-        await handle.close().catch(() => {});
-        await fs.unlink(lockPath).catch(() => {});
-      },
-    };
+    await fs.mkdir(mutexPath);
+    return true;
   } catch (e) {
-    if (e && e.code === "EEXIST") {
-      // Check if lock is stale
-      try {
-        const stat = await fs.stat(lockPath);
-        if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
-          await fs.unlink(lockPath).catch(() => {});
-          return openLock(lockPath, { quietIfLocked });
-        }
-      } catch (_statErr) {
-        // Lock file disappeared between checks, retry
-        return openLock(lockPath, { quietIfLocked });
-      }
-      if (!quietIfLocked) {
-        process.stdout.write("Another sync is already running.\n");
-      }
-      return null;
+    if (!e || e.code !== "EEXIST") return false;
+  }
+  // A process that died mid-takeover would otherwise block every future
+  // takeover forever. The window is milliseconds, so anything this old is dead.
+  try {
+    const stat = await fs.stat(mutexPath);
+    if (Date.now() - stat.mtimeMs > TAKEOVER_ABANDONED_MS) {
+      await fs.rmdir(mutexPath).catch(() => {});
     }
+  } catch (_e) {
+    // Vanished under us — the caller retries either way.
+  }
+  return false;
+}
+
+async function readLockOwner(lockPath) {
+  try {
+    const raw = await fs.readFile(lockPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return parsed;
+  } catch (_e) {
+    // Empty, truncated, or pre-upgrade lock file — fall back to the mtime rule.
+  }
+  return null;
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM means the process exists but belongs to someone else.
+    return Boolean(e && e.code === "EPERM");
+  }
+}
+
+// A lock whose owner process is gone is stale immediately — no need to wait out
+// the full window. Only trust the pid when the lock was taken on this host, and
+// never when it is our own pid (a recycled pid would look alive forever).
+function isOwnerGone(owner) {
+  if (!owner || typeof owner.pid !== "number" || !Number.isInteger(owner.pid)) return false;
+  if (owner.host !== os.hostname()) return false;
+  if (owner.pid === process.pid) return false;
+  return !isProcessAlive(owner.pid);
+}
+
+// Throws EEXIST when the lock is already held — that is the caller's signal to
+// decide whether the existing lock is stale.
+async function createHeldLock(lockPath, heartbeatMs) {
+  const handle = await fs.open(lockPath, "wx");
+  const owner = { pid: process.pid, host: os.hostname(), startedAt: new Date().toISOString() };
+
+  try {
+    await handle.writeFile(`${JSON.stringify(owner, null, 2)}\n`, { encoding: "utf8" });
+  } catch (e) {
+    // A write failure would otherwise leave a leaked fd plus an empty lock file
+    // that nothing releases — blocking every sync until the stale window elapses.
+    await handle.close().catch(() => {});
+    await fs.unlink(lockPath).catch(() => {});
     throw e;
   }
+
+  // unref'd so a held lock can never keep the CLI process alive on its own.
+  const heartbeat = setInterval(() => {
+    const now = new Date();
+    fs.utimes(lockPath, now, now).catch(() => {});
+  }, heartbeatMs);
+  if (typeof heartbeat.unref === "function") heartbeat.unref();
+
+  return {
+    owner,
+    async release() {
+      clearInterval(heartbeat);
+      await handle.close().catch(() => {});
+      await fs.unlink(lockPath).catch(() => {});
+    },
+  };
+}
+
+// Removing a stale lock is a check-then-act, and the caller's check ran outside
+// any mutual exclusion: by now another waiter may already have reclaimed it and
+// be holding a *fresh* lock. Deleting (or renaming) the path blind would drop
+// that winner's lock and let two syncs run at once. The mkdir mutex makes the
+// re-check and the delete atomic with respect to other waiters.
+async function reclaimStaleLock(lockPath) {
+  if (!(await acquireTakeoverMutex(lockPath))) return;
+  try {
+    const current = await fs.stat(lockPath).catch(() => null);
+    if (!current) return;
+    const currentOwner = await readLockOwner(lockPath);
+    const stillStale = Date.now() - current.mtimeMs > LOCK_STALE_MS || isOwnerGone(currentOwner);
+    if (stillStale) await fs.unlink(lockPath).catch(() => {});
+  } finally {
+    await fs.rmdir(takeoverMutexPath(lockPath)).catch(() => {});
+  }
+}
+
+async function openLock(lockPath, { quietIfLocked, heartbeatMs = LOCK_HEARTBEAT_MS } = {}, attempt = 1) {
+  try {
+    return await createHeldLock(lockPath, heartbeatMs);
+  } catch (e) {
+    if (!e || e.code !== "EEXIST") throw e;
+
+    const retry = () => openLock(lockPath, { quietIfLocked, heartbeatMs }, attempt + 1);
+    const giveUp = () => {
+      if (!quietIfLocked) process.stdout.write("Another sync is already running.\n");
+      return null;
+    };
+
+    if (attempt >= MAX_LOCK_ATTEMPTS) return giveUp();
+
+    let stat;
+    try {
+      stat = await fs.stat(lockPath);
+    } catch (_statErr) {
+      return retry(); // Lock file disappeared between checks.
+    }
+
+    const owner = await readLockOwner(lockPath);
+    const expired = Date.now() - stat.mtimeMs > LOCK_STALE_MS;
+    // A live holder heartbeats its lock, so a fresh mtime means "still working".
+    if (!expired && !isOwnerGone(owner)) return giveUp();
+
+    await reclaimStaleLock(lockPath);
+    return retry();
+  }
 }
 
 module.exports = {
@@ -88,4 +209,7 @@ module.exports = {
   writeJson,
   chmod600IfPossible,
   openLock,
+  // Exported for tests.
+  LOCK_STALE_MS,
+  LOCK_HEARTBEAT_MS,
 };

package/src/lib/local-api.js

@@ -30,6 +30,8 @@ const avatarProxyCache = new Map();
 const {
   MODEL_PRICING,
   getModelPricing,
+  getModelPricingMeta,
+  getPricingDiagnostics,
   computeRowCost,
   ensurePricingLoaded,
 } = require("./pricing");
@@ -1147,7 +1149,15 @@ function createLocalApiHandler({ queuePath }) {
               model: m.model,
               source: s.source,
             });
-            return { ...m, totals: { ...m.totals, total_cost_usd: cost.toFixed(6) } };
+            // How the price was resolved, so the dashboard can say "unpriced"
+            // or "matched by substring" instead of inferring it from a $0 cost
+            // — a genuinely free model and an unknown one both cost $0.
+            const { tier } = getModelPricingMeta(m.model, { source: s.source });
+            return {
+              ...m,
+              pricing_tier: tier,
+              totals: { ...m.totals, total_cost_usd: cost.toFixed(6) },
+            };
           })
           .sort((a, b) => b.totals.total_tokens - a.totals.total_tokens);
         const sourceCost = s.models.reduce((sum, m) => sum + Number(m.totals.total_cost_usd), 0);
@@ -1157,7 +1167,13 @@ function createLocalApiHandler({ queuePath }) {
 
       json(res, {
         from, to, days: 0, scope, excluded_sources: excludedSources, sources,
-        pricing: { model: "per-model", pricing_mode: "per_token_type", source: "litellm", effective_from: new Date().toISOString().slice(0, 10) },
+        pricing: {
+          model: "per-model",
+          pricing_mode: "per_token_type",
+          source: "litellm",
+          effective_from: new Date().toISOString().slice(0, 10),
+          ...getPricingDiagnostics(),
+        },
       });
       return true;
     }
@@ -1522,6 +1538,8 @@ module.exports = {
   resolveQueuePath,
   // Exported for cross-consumer tests (pricing + native contract lock).
   MODEL_PRICING,
+  // Shared with serve.js so the Host allowlist and the Origin allowlist agree.
+  isLoopbackHostname,
   getModelPricing,
   computeRowCost,
   ensurePricingLoaded,

package/src/lib/pricing/curated-overrides.json

@@ -2,8 +2,15 @@
   "_meta": {
     "note": "Curated price overrides. Always wins over LiteLLM. Two reasons to live here: (1) self-defined alias names that LiteLLM will never carry (kiro-*, hy3-*, composer-*, kimi-for-coding, free-tier OpenRouter routes); (2) prices we want to pin even if LiteLLM has the model (e.g. cache_write fields LiteLLM often omits). Units: USD per million tokens. Edit this file to override pricing without redeploying.",
     "units": "usd_per_million_tokens",
-    "deepseek_v4_pro_discount_expiry": "2026-05-31T15:59:00Z — DeepSeek v4-pro is currently at a 75% promotional discount. After expiry the prices revert to 4x: input $1.74/M, output $3.48/M, cache_read $0.0145/M, cache_write $1.74/M. Update this file before the cutover.",
-    "sonnet5_intro_price_expiry": "2026-08-31 — Sonnet 5 intro price 2/10 reverts to 3/15 sticker. The src pricing path auto-tracks LiteLLM (no edit needed); re-vendor the seed after the cutover. See issue #16."
+    "expiries_note": "Time-boxed pricing facts. Machine-checked by scripts/validate-curated-expiry.cjs (npm run validate:curated-expiry, part of ci:local): once expires_at has passed, the check FAILS until a human applies `action` and then removes or advances the entry. Free-text expiry notes are not allowed here — a date nobody checks is how deepseek-v4-pro stayed on a 75%-off promo price for 55 days past its cutover (issue #87).",
+    "expiries": [
+      {
+        "id": "sonnet5-intro-price",
+        "expires_at": "2026-08-31",
+        "what": "Sonnet 5 introductory pricing (2/10) reverts to the 3/15 sticker price.",
+        "action": "No curated entry to edit — the src pricing path auto-tracks LiteLLM. Re-vendor the bundled seed (npm run pricing:build-seed) so a cold start also prices Sonnet 5 correctly, then delete this entry. See issue #16."
+      }
+    ]
   },
   "exact": {
     "claude-fable-5": { "input": 10, "output": 50, "cache_read": 1, "cache_write": 12.5, "note": "Pinned from Anthropic public pricing until bundled LiteLLM seed carries Fable 5." },
@@ -20,7 +27,7 @@
     "MiniMax-M2.7":     { "input": 0.3,  "output": 1.2,  "cache_read": 0.06,  "cache_write": 0.375 },
     "MiniMax-M2.7-highspeed":{ "input": 0.6, "output": 2.4, "cache_read": 0.06, "cache_write": 0.375 },
     "deepseek-v4-flash":{ "input": 0.14, "output": 0.28, "cache_read": 0.0028, "cache_write": 0.14 },
-    "deepseek-v4-pro":  { "input": 0.435,"output": 0.87, "cache_read": 0.003625, "cache_write": 0.435 },
+    "deepseek-v4-pro":  { "input": 1.74, "output": 3.48, "cache_read": 0.0145, "cache_write": 1.74, "note": "Standard (post-promo) pricing. The 75%-off launch promo expired 2026-05-31; these rates applied 2026-07-25 (issue #87)." },
     "deepseek-chat":    { "input": 0.14, "output": 0.28, "cache_read": 0.0028, "cache_write": 0.14 },
     "grok-build":       { "input": 1.25, "output": 2.50, "cache_read": 0.20, "note": "Grok Build TUI estimate. Local telemetry currently exposes totalTokens without a stable prompt/output/cache split, so TokenTracker estimates input/output split until Grok exposes per-call usage details." },
     "grok-4-0709":      { "input": 3.00, "output": 15.00, "cache_read": 0.75 },

package/src/lib/pricing/index.js

@@ -34,34 +34,105 @@ function loadSeedSync() {
 
 const seedRaw = loadSeedSync();
 
+// How long a loaded snapshot is trusted before a lookup is allowed to trigger a
+// background refresh. Mirrors the fetcher's disk-cache TTL: before this change
+// that TTL only chose which snapshot to load *at startup*, so a dashboard that
+// stayed up (the LaunchAgent stays up for days) never saw a new model or a
+// price change — claude-opus-5 billed $0 for 21 hours that way. Issue #90.
+const RELOAD_AFTER_MS = 24 * 60 * 60 * 1000;
+
+// Floor between background refreshes, so a permanently-unknown model cannot
+// turn every request into an upstream fetch.
+const RELOAD_COOLDOWN_MS = 5 * 60 * 1000;
+
+// Resolution tiers that mean "we guessed": the model matched a substring or a
+// curated fuzzy rule rather than an exact id, so the price is plausible but may
+// belong to a different model. Worth surfacing — a wrong price never looks
+// wrong, unlike a $0 one.
+const FUZZY_SOURCES = new Set(["curated:fuzzy", "litellm:fuzzy", "litellm:prefix-strip"]);
+
+// `last_refresh_error` is served over HTTP to the dashboard, so it is built
+// from CLOSED sets, never from an arbitrary value. A previous version accepted
+// anything symbol-shaped, which a QA pass broke immediately: a 32-character
+// token like `sk_live_AAAA…` is symbol-shaped. There is no pattern that
+// separates "a short error symbol" from "a short secret" — only an allowlist.
+const KNOWN_ERROR_CODES = new Set([
+  // fs
+  "ENOENT", "EACCES", "EPERM", "EEXIST", "ENOSPC", "EROFS", "EISDIR", "ENOTDIR", "EMFILE", "EBUSY",
+  // network
+  "ECONNREFUSED", "ECONNRESET", "ETIMEDOUT", "ENOTFOUND", "EAI_AGAIN", "EPIPE",
+  "EHOSTUNREACH", "ENETUNREACH", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT",
+  // error classes
+  "AbortError", "TypeError", "SyntaxError", "RangeError", "FetchError", "Error",
+]);
+
+// Whatever loadLitellmData can report as the origin of the data it returned.
+const KNOWN_SOURCES = new Set(["upstream", "disk-cache", "stale-cache", "seed-snapshot"]);
+
+function labelFrom(allowed, candidates) {
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && allowed.has(candidate)) return candidate;
+  }
+  return "unknown";
+}
+
 const state = {
   loaded: false,
   loadingPromise: null,
+  loadedAt: 0,
+  reloadPromise: null,
+  lastReloadAt: 0,
+  lastReloadError: null,
   litellmRawMap: seedRaw, // raw per-token; field shape from LiteLLM JSON
   litellmPerMillionMap: buildLitellmPerMillionMap(seedRaw), // USD/MTok
   source: Object.keys(seedRaw).length ? "seed-snapshot:sync" : null,
   // negativeCache prevents re-walking the LiteLLM map for models we've already
   // determined are unknown. Cleared on every reload.
   negativeCache: new Set(),
+  // model -> resolution tier, for the diagnostics surface. Cleared on reload.
+  tiers: new Map(),
+  // Models already warned about, so a hot path logs once, not once per row.
+  warned: new Set(),
+  reloadOptions: {},
 };
 
 function defaultCachePath() {
   return path.join(os.homedir(), ".tokentracker", "cache", "pricing.json");
 }
 
+// `requireUpstream` guards the background path. loadLitellmData falls back on
+// its own (upstream → stale disk cache → bundled seed), so a refresh that fails
+// to reach upstream would otherwise REPLACE good in-memory data with the older
+// seed — re-introducing exactly the "new model bills $0" bug this reload exists
+// to fix. Verified: with the disk cache deleted and upstream down, a model
+// priced at $5/$25 dropped to $0 after a failed refresh.
+async function loadInto(opts, { requireUpstream = false } = {}) {
+  const cachePath = opts.cachePath || defaultCachePath();
+  const { data, source } = await loadLitellmData({ ...opts, cachePath });
+  if (requireUpstream && source !== "upstream") {
+    state.lastReloadError = `refresh-fell-back-to-${labelFrom(KNOWN_SOURCES, [source])}`;
+    return;
+  }
+  state.litellmRawMap = data || {};
+  state.litellmPerMillionMap = buildLitellmPerMillionMap(state.litellmRawMap);
+  state.source = source;
+  state.loaded = true;
+  state.loadedAt = Date.now();
+  state.negativeCache.clear();
+  state.tiers.clear();
+}
+
 async function ensurePricingLoaded(opts = {}) {
   if (state.loaded) return state;
   if (state.loadingPromise) return state.loadingPromise;
 
+  // Remembered so a later background reload can reach the same cache path and
+  // fetch options without the caller having to plumb them through again.
+  state.reloadOptions = opts;
+
   state.loadingPromise = (async () => {
     try {
-      const cachePath = opts.cachePath || defaultCachePath();
-      const { data, source } = await loadLitellmData({ ...opts, cachePath });
-      state.litellmRawMap = data || {};
-      state.litellmPerMillionMap = buildLitellmPerMillionMap(state.litellmRawMap);
-      state.source = source;
-      state.loaded = true;
-      state.negativeCache.clear();
+      await loadInto(opts);
       return state;
     } finally {
       state.loadingPromise = null;
@@ -71,37 +142,141 @@ async function ensurePricingLoaded(opts = {}) {
   return state.loadingPromise;
 }
 
+// Fire-and-forget refresh. Single-flight, never awaited by a lookup: the caller
+// keeps whatever price it already has for this request and the next request
+// benefits. A failed reload leaves the existing snapshot in place.
+//
+// The cooldown matters because a model that is genuinely absent upstream (a
+// local or unlisted model) misses on every row it appears in. Without it, each
+// of those rows would queue another upstream fetch the moment the previous one
+// finished.
+function scheduleReload(nowMs = Date.now()) {
+  if (!state.loaded || state.reloadPromise) return state.reloadPromise;
+  if (nowMs - state.lastReloadAt < RELOAD_COOLDOWN_MS) return null;
+  state.lastReloadAt = nowMs;
+  state.reloadPromise = (async () => {
+    try {
+      // forceRefresh skips the disk cache; without it a reload would just
+      // re-read the same stale snapshot we already hold.
+      state.lastReloadError = null;
+      // forceRefresh skips the disk cache; without it a reload would just
+      // re-read the same stale snapshot we already hold.
+      await loadInto({ ...state.reloadOptions, forceRefresh: true }, { requireUpstream: true });
+    } catch (e) {
+      // Reached when loadLitellmData itself throws rather than falling back —
+      // statSafe rethrows a non-ENOENT stat error, so an unusable cache path
+      // lands here (QA probe: refresh-failed:TypeError). Only
+      // the error CODE is kept: messages from fs/fetch carry absolute paths and
+      // this string is served over HTTP to the dashboard.
+      state.lastReloadError = `refresh-failed:${labelFrom(KNOWN_ERROR_CODES, [e?.code, e?.name])}`;
+    } finally {
+      state.reloadPromise = null;
+    }
+  })();
+  return state.reloadPromise;
+}
+
+function isSnapshotStale(nowMs = Date.now()) {
+  return state.loaded && nowMs - state.loadedAt > RELOAD_AFTER_MS;
+}
+
 // For tests: drop loaded state so a fresh call can re-load. Seeds with the
 // bundled snapshot so getModelPricing() still works without ensurePricingLoaded.
 function resetPricingForTests() {
   state.loaded = false;
   state.loadingPromise = null;
+  state.loadedAt = 0;
+  state.reloadPromise = null;
+  state.lastReloadAt = 0;
+  state.lastReloadError = null;
   state.litellmRawMap = seedRaw;
   state.litellmPerMillionMap = buildLitellmPerMillionMap(seedRaw);
   state.source = Object.keys(seedRaw).length ? "seed-snapshot:sync" : null;
   state.negativeCache.clear();
+  state.tiers.clear();
+  state.warned.clear();
+  state.reloadOptions = {};
 }
 
-function getModelPricing(model, opts = {}) {
-  if (!model) return ZERO_PRICING;
-  let lookupSource = null;
-  if (typeof opts === "string") {
-    lookupSource = opts.toLowerCase();
-  } else if (typeof opts.source === "string") {
-    lookupSource = opts.source.toLowerCase();
-  }
+function resolveLookupSource(opts) {
+  if (typeof opts === "string") return opts.toLowerCase();
+  if (opts && typeof opts.source === "string") return opts.source.toLowerCase();
+  return null;
+}
+
+// Returns the price AND how it was resolved. getModelPricing keeps the old
+// bare-numbers contract for the many existing callers; anything that wants to
+// show the user how much to trust the number uses this.
+function getModelPricingMeta(model, opts = {}) {
+  if (!model) return { pricing: ZERO_PRICING, tier: "empty" };
+
+  const lookupSource = resolveLookupSource(opts);
   const cacheKey = lookupSource ? `${lookupSource}\0${model}` : model;
-  if (state.negativeCache.has(cacheKey)) return ZERO_PRICING;
+
+  if (state.negativeCache.has(cacheKey)) {
+    // Still unknown as of the current snapshot. If that snapshot has aged out,
+    // a new model may have appeared upstream — refresh for the next caller.
+    if (isSnapshotStale()) scheduleReload();
+    return { pricing: ZERO_PRICING, tier: "miss" };
+  }
 
   const result = lookupPricing(model, {
     curated: curatedOverrides,
     litellm: state.litellmPerMillionMap,
     source: lookupSource,
   });
-  if (result.hit) return result.value;
+
+  if (result.hit) {
+    state.tiers.set(cacheKey, { model, source: lookupSource, tier: result.source });
+    return { pricing: result.value, tier: result.source };
+  }
 
   state.negativeCache.add(cacheKey);
-  return ZERO_PRICING;
+  state.tiers.set(cacheKey, { model, source: lookupSource, tier: "miss" });
+
+  // A miss is the strongest signal that our snapshot predates a model launch —
+  // exactly the claude-opus-5 case. Refresh in the background so the next
+  // request prices it, instead of waiting for a process restart.
+  scheduleReload();
+
+  if (!state.warned.has(cacheKey)) {
+    state.warned.add(cacheKey);
+    console.warn(
+      `[pricing] no price for model "${model}"${lookupSource ? ` (source: ${lookupSource})` : ""}`
+        + " — its cost is being counted as $0. Refreshing pricing data in the background;"
+        + " if it stays unpriced, add it to src/lib/pricing/curated-overrides.json.",
+    );
+  }
+
+  return { pricing: ZERO_PRICING, tier: "miss" };
+}
+
+function getModelPricing(model, opts = {}) {
+  return getModelPricingMeta(model, opts).pricing;
+}
+
+// Snapshot of what the pricing layer knows it got wrong or guessed at, for the
+// API to hand to the dashboard.
+function getPricingDiagnostics() {
+  // Keyed by source+model, matching the lookup itself: the same model id can
+  // resolve differently per provider (Antigravity normalises names before the
+  // lookup), so a model-only key would let one provider's exact hit hide
+  // another's miss.
+  const unpriced = new Set();
+  const fuzzy = [];
+  for (const entry of state.tiers.values()) {
+    if (entry.tier === "miss") unpriced.add(entry.model);
+    else if (FUZZY_SOURCES.has(entry.tier)) fuzzy.push({ model: entry.model, tier: entry.tier });
+  }
+  return {
+    source: state.source,
+    loaded_at: state.loadedAt ? new Date(state.loadedAt).toISOString() : null,
+    stale: isSnapshotStale(),
+    refreshing: Boolean(state.reloadPromise),
+    last_refresh_error: state.lastReloadError,
+    unpriced_models: Array.from(unpriced).sort(),
+    fuzzy_priced_models: fuzzy.sort((a, b) => a.model.localeCompare(b.model)),
+  };
 }
 
 // Same formula and Codex/every-code reasoning-folding rule as the previous
@@ -134,10 +309,14 @@ const MODEL_PRICING = curatedOverrides.exact;
 module.exports = {
   ensurePricingLoaded,
   getModelPricing,
+  getModelPricingMeta,
+  getPricingDiagnostics,
   computeRowCost,
   resetPricingForTests,
   MODEL_PRICING,
   ZERO_PRICING,
   // Internal hooks for tests.
   __getStateForTests: () => state,
+  __labelFromForTests: labelFrom,
+  __KNOWN_ERROR_CODES: KNOWN_ERROR_CODES,
 };

package/src/lib/pricing/litellm-fetcher.js

@@ -112,6 +112,11 @@ async function writeCache(cachePath, data) {
 async function loadLitellmData({
   cachePath,
   ttlMs = DEFAULT_TTL_MS,
+  // Skip the disk cache and go upstream. Needed because `ttlMs: 0` does NOT
+  // reliably force a refetch: mtime carries sub-millisecond precision while
+  // Date.now() does not, so a cache file written moments ago can compare as
+  // "written in the future" and still count as fresh.
+  forceRefresh = false,
   fetchTimeoutMs = DEFAULT_FETCH_TIMEOUT_MS,
   fetchImpl = fetchUpstream,
   url = LITELLM_PRICING_URL,
@@ -126,7 +131,7 @@ async function loadLitellmData({
 
   // 1. Fresh disk cache
   const stat = await statSafe(cachePath);
-  if (isFresh(stat, ttlMs)) {
+  if (!forceRefresh && isFresh(stat, ttlMs)) {
     try {
       const data = await readJsonAsync(cachePath);
       delete data._meta;