lynkr 9.7.2 → 9.9.0

package/src/routing/intent-score.js

@@ -0,0 +1,339 @@
+/**
+ * WS7 — payload-invariant intent scoring via embedding anchors.
+ *
+ * The lexical scorer's noise exceeds its band width (same semantic ask
+ * measured 31 offline vs 56 live once the payload envelope — tool schemas,
+ * history, injected reminders — is attached; paraphrase-only noise is still
+ * ±10-12 on a 24-point band). This module replaces the ex-ante difficulty
+ * signal with something the evidence supports:
+ *
+ *   - Score CLEANED USER TEXT ONLY. Tool schemas, conversation history,
+ *     <system-reminder> blocks and tool_result payloads never touch the
+ *     score. Envelope concerns (agentic detection, context guard, client
+ *     profiles) keep their own triggers — they escalate tiers, they don't
+ *     inflate this score.
+ *   - Classify against embedding centroids built from ~10 REAL session
+ *     texts (data/difficulty-anchors.json): {trivial, substantive,
+ *     heavyweight}. The query embedding is already computed per request
+ *     (WS5.5, nomic-embed-text via local Ollama, cache-backed), so the
+ *     three cosine sims cost microseconds and no new I/O.
+ *   - Blend sims → a continuous 0-100 score (softmax over class values)
+ *     so the existing band mapping, calibration, pins and drift margin all
+ *     keep working unchanged.
+ *
+ * Contracts (tested in test/intent-score.test.js):
+ *   - Envelope invariance: score(text) === score(text + schemas + reminders
+ *     + history).
+ *   - REASONING (76+) is unreachable from text alone — trigger-only
+ *     (risk / force phrase / agentic / kNN / tier-fallback). CLASS_VALUES
+ *     top out at heavyweight=68 and the lexical fallback clamps at 75.
+ *   - embed() failure never throws — falls back to a lexical score of the
+ *     SAME cleaned text (still envelope-invariant, just noisier).
+ *
+ * Escape hatch: LYNKR_INTENT_SCORE_MODE=legacy restores the pre-WS7
+ * full-payload lexical score.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const logger = require('../logger');
+
+// data/ (user-editable, gitignored) wins; config/ is the bundled default —
+// data/ is excluded from the npm tarball, so installs load from config/.
+const ANCHORS_PATHS = [
+  path.join(__dirname, '../../data/difficulty-anchors.json'),
+  path.join(__dirname, '../../config/difficulty-anchors.json'),
+];
+const VECTORS_CACHE_PATH = path.join(__dirname, '../../data/difficulty-anchors.vectors.json');
+
+// Class → representative score. Chosen so each class lands inside an
+// existing default band (SIMPLE 0-25, MEDIUM 26-50, COMPLEX 51-75) and the
+// blend can NEVER reach REASONING (76+). Calibration may later collapse
+// bands into degenerate ranges without touching these.
+const CLASS_VALUES = {
+  trivial: 10,
+  substantive: 45,
+  heavyweight: 68,
+};
+
+// Softmax temperature over cosine sims. Real inter-class sim gaps on
+// nomic-embed-text run ~0.05-0.15, so 0.05 is sharp enough to commit to a
+// class when the winner is clear, soft enough to interpolate borderline
+// asks instead of cliffing between bands.
+const BLEND_TEMPERATURE = 0.05;
+
+// The CLASS is the decision; the blend only positions within the class's
+// band — without the clamp, a close runner-up sim leaks trivial asks
+// across the band edge.
+//
+// NOTE: the trivial band [0,25] deliberately overlaps the MEDIUM tier
+// (which starts at 20 — see model-tiers.js). Trivial-classified asks whose
+// blend lands in the top of the band (20-25) route MEDIUM: RouterArena
+// optimality data (2026-07-16) showed cheap-model failures cluster exactly
+// there (miss median 23 vs hit median 14). Clamping trivial to [0,19]
+// would erase that signal — do not "fix" the mismatch.
+const CLASS_BANDS = {
+  trivial: [0, 25],
+  substantive: [26, 50],
+  heavyweight: [51, 75],
+};
+
+function intentScoreMode() {
+  const m = (process.env.LYNKR_INTENT_SCORE_MODE || 'anchor').toLowerCase();
+  return m === 'legacy' ? 'legacy' : 'anchor';
+}
+
+/**
+ * Extract the text the USER actually authored this turn: the latest user
+ * message that has real text after stripping harness-injected content.
+ * Returns null when there is nothing to score (e.g. tool-result-only turn).
+ */
+function extractCleanUserText(payload) {
+  const msgs = payload?.messages;
+  if (!Array.isArray(msgs)) return null;
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const msg = msgs[i];
+    if (msg?.role !== 'user') continue;
+    let text = null;
+    if (typeof msg.content === 'string') {
+      text = msg.content;
+    } else if (Array.isArray(msg.content)) {
+      text = msg.content
+        .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join(' ');
+    }
+    if (text == null) continue;
+    text = text
+      .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '')
+      // Harness task/background-agent notifications — not user-authored.
+      .replace(/<task-notification>[\s\S]*?<\/task-notification>/g, '')
+      // Codex harness blocks (merged into the typed text upstream):
+      // sandbox/permission profile and AGENTS.md contents.
+      .replace(/<environment_context>[\s\S]*?<\/environment_context>/g, '')
+      .replace(/<user_instructions>[\s\S]*?<\/user_instructions>/g, '')
+      // Goose harness block wrapping every typed message (time, cwd, todo
+      // notes) — its "tasks"/"update"/"requirements" vocabulary scored a
+      // bare "Hi" as substantive/MEDIUM.
+      .replace(/<turn-context>[\s\S]*?<\/turn-context>/g, '')
+      // Lynkr's own injected notices (quota banners, badges) start with the
+      // [Lynkr] marker — the user didn't type those.
+      .replace(/^\s*\[Lynkr\][^\n]*$/gm, '')
+      .trim();
+    // Whole-message harness content: compaction/continuation summaries and
+    // system notifications arrive as user-role messages the user never
+    // typed. Treat as empty and keep walking back.
+    if (/^\s*(\[SYSTEM NOTIFICATION|<conversation[\s>]|<session[\s>]|\[Request interrupted|This session is being continued from a previous conversation)/i.test(text)) {
+      // Continuation summaries PARAPHRASE the prior session, so they carry
+      // force-phrase vocabulary the user typed hours ago.
+      text = '';
+    }
+    if (text) return text;
+    // A user message that was ALL injected content (or all tool_results)
+    // doesn't end the search — keep walking back for the real user turn.
+  }
+  return null;
+}
+
+function cosine(a, b) {
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  return denom > 0 ? dot / denom : 0;
+}
+
+/**
+ * Embed every anchor text and mean them per class.
+ * @param {Object<string,string[]>} anchorsByClass
+ * @param {(text:string)=>Promise<number[]|null>} embedFn
+ * @returns {Promise<Object<string,number[]>|null>} null if any class has no vectors
+ */
+async function buildCentroids(anchorsByClass, embedFn) {
+  const centroids = {};
+  for (const [cls, texts] of Object.entries(anchorsByClass)) {
+    if (cls.startsWith('_') || !Array.isArray(texts)) continue;
+    const vectors = [];
+    for (const t of texts) {
+      try {
+        const v = await embedFn(t);
+        if (Array.isArray(v) && v.length > 0) vectors.push(v);
+      } catch { /* embed never throws by contract, belt-and-braces */ }
+    }
+    if (vectors.length === 0) return null; // a class with no anchors is unusable
+    const dim = vectors[0].length;
+    const mean = new Array(dim).fill(0);
+    for (const v of vectors) for (let i = 0; i < dim; i++) mean[i] += v[i] / vectors.length;
+    centroids[cls] = mean;
+  }
+  return Object.keys(centroids).length === Object.keys(CLASS_VALUES).length ? centroids : null;
+}
+
+/**
+ * Cosine sims against each class centroid.
+ * @returns {{cls:string, sims:Object<string,number>}}
+ */
+function classify(embedding, centroids) {
+  const sims = {};
+  let best = null;
+  for (const cls of Object.keys(CLASS_VALUES)) {
+    const c = centroids[cls];
+    sims[cls] = Array.isArray(c) ? cosine(embedding, c) : -1;
+    if (best === null || sims[cls] > sims[best]) best = cls;
+  }
+  return { cls: best, sims };
+}
+
+/**
+ * Softmax-blend class sims into a continuous score. Bounded by construction
+ * to [min(CLASS_VALUES), max(CLASS_VALUES)] — REASONING stays unreachable.
+ */
+function blendScore(sims) {
+  const classes = Object.keys(CLASS_VALUES);
+  const max = Math.max(...classes.map((c) => sims[c] ?? -1));
+  let totalW = 0;
+  let total = 0;
+  for (const cls of classes) {
+    const w = Math.exp(((sims[cls] ?? -1) - max) / BLEND_TEMPERATURE);
+    totalW += w;
+    total += w * CLASS_VALUES[cls];
+  }
+  const score = totalW > 0 ? total / totalW : CLASS_VALUES.substantive;
+  return Math.round(Math.max(0, Math.min(75, score)));
+}
+
+// --- default centroids (lazy singleton, disk-cached) ------------------------
+
+let _centroidsPromise = null;
+
+function _anchorsHash(anchors, model) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify(anchors) + '|' + model)
+    .digest('hex');
+}
+
+async function _loadDefaultCentroids() {
+  let anchors = null;
+  for (const p of ANCHORS_PATHS) {
+    try {
+      anchors = JSON.parse(fs.readFileSync(p, 'utf8'));
+      break;
+    } catch { /* try next path */ }
+  }
+  if (!anchors) {
+    logger.warn('[IntentScore] No difficulty-anchors.json — anchor mode unavailable');
+    return null;
+  }
+  const config = require('../config');
+  const model = config.ollama?.embeddingsModel || 'unknown';
+  const hash = _anchorsHash(anchors, model);
+
+  // Disk cache: survives Ollama being down at boot.
+  try {
+    const cached = JSON.parse(fs.readFileSync(VECTORS_CACHE_PATH, 'utf8'));
+    if (cached?.hash === hash && cached.centroids) {
+      logger.debug('[IntentScore] Anchor centroids loaded from disk cache');
+      return cached.centroids;
+    }
+  } catch { /* no cache yet */ }
+
+  const { getKnnRouter } = require('./knn-router');
+  const router = getKnnRouter();
+  const centroids = await buildCentroids(anchors, (t) => router.embed(t));
+  if (!centroids) {
+    logger.warn('[IntentScore] Anchor embedding failed (Ollama down?) — lexical fallback until next attempt');
+    return null;
+  }
+  try {
+    fs.writeFileSync(VECTORS_CACHE_PATH, JSON.stringify({ hash, model, centroids }));
+  } catch (err) {
+    logger.debug({ err: err.message }, '[IntentScore] Could not persist centroid cache');
+  }
+  logger.info({ classes: Object.keys(centroids) }, '[IntentScore] Anchor centroids built');
+  return centroids;
+}
+
+function getDefaultCentroids() {
+  if (!_centroidsPromise) {
+    _centroidsPromise = _loadDefaultCentroids().catch((err) => {
+      logger.warn({ err: err.message }, '[IntentScore] Centroid load failed');
+      return null;
+    });
+    // A failed load should retry on the next request, not stick forever.
+    _centroidsPromise.then((c) => { if (!c) _centroidsPromise = null; });
+  }
+  return _centroidsPromise;
+}
+
+/**
+ * Lexical fallback: the OLD scorer's content dimensions, but fed ONLY the
+ * cleaned user text (fresh single-message payload — no tools, no history),
+ * so it stays envelope-invariant. Clamped below the REASONING band.
+ */
+function _lexicalCleanScore(text) {
+  const { calculateWeightedScore } = require('./complexity-analyzer');
+  const minimal = { messages: [{ role: 'user', content: text }] };
+  const { score } = calculateWeightedScore(minimal, text);
+  return Math.max(0, Math.min(75, Math.round(score)));
+}
+
+/**
+ * Score the user's intent for this turn.
+ *
+ * @param {object} payload — full request payload (only cleaned user text is used)
+ * @param {object} [opts]
+ * @param {(text:string)=>Promise<number[]|null>} [opts.embedFn] — injected for tests
+ * @param {Object<string,number[]>} [opts.centroids] — injected for tests
+ * @param {string} [opts.mode] — 'anchor' | 'legacy' (default: env LYNKR_INTENT_SCORE_MODE)
+ * @returns {Promise<{score:number, mode:'anchor'|'lexical', class?:string, sims?:object, text:string}|null>}
+ *   null → caller keeps its legacy score (legacy mode, or nothing to score)
+ */
+async function scoreIntent(payload, opts = {}) {
+  const mode = opts.mode ?? intentScoreMode();
+  if (mode === 'legacy') return null;
+
+  const text = extractCleanUserText(payload);
+  if (!text) return null;
+
+  try {
+    const centroids = opts.centroids !== undefined ? opts.centroids : await getDefaultCentroids();
+    if (centroids) {
+      let embedFn = opts.embedFn;
+      if (!embedFn) {
+        const { getKnnRouter } = require('./knn-router');
+        const router = getKnnRouter();
+        embedFn = (t) => router.embed(t);
+      }
+      const embedding = await embedFn(text);
+      if (Array.isArray(embedding) && embedding.length > 0) {
+        const { cls, sims } = classify(embedding, centroids);
+        const [lo, hi] = CLASS_BANDS[cls];
+        const score = Math.max(lo, Math.min(hi, blendScore(sims)));
+        return { score, mode: 'anchor', class: cls, sims, text };
+      }
+    }
+  } catch (err) {
+    logger.debug({ err: err.message }, '[IntentScore] anchor scoring failed — lexical fallback');
+  }
+
+  return { score: _lexicalCleanScore(text), mode: 'lexical', text };
+}
+
+module.exports = {
+  CLASS_VALUES,
+  intentScoreMode,
+  extractCleanUserText,
+  cosine,
+  buildCentroids,
+  classify,
+  blendScore,
+  scoreIntent,
+  // exposed for the replay script
+  getDefaultCentroids,
+};

package/src/routing/interaction.js

@@ -137,6 +137,9 @@ function buildInteractionBlock(decision) {
       ...(decision.risk?.pathHits || []),
     ])),
     complexity_score: typeof decision.score === 'number' ? decision.score : null,
+    // Pin-serve turns: the score that originally created the session pin.
+    // Lets the badge show both this turn's fresh score and the pin's.
+    pin_score: typeof decision._pinScore === 'number' ? decision._pinScore : null,
     estimated_savings_percent: estimateSavingsPercent(decision.tier, decision.provider),
     next_step,
   };

package/src/routing/knn-router.js

@@ -29,10 +29,16 @@ const META_FILE = path.join(INDEX_DIR, 'meta.json');
 const MAX_ELEMENTS = 50000;
 const DIM = 768; // nomic-embed-text default
 const K = 10;
-// Default 1000 is a safety floor for quality; override via env when you
-// want to activate kNN with less data (e.g. bootstrapping from your own
-// telemetry before reaching 1k entries).
-const MIN_INDEX_SIZE = Number.parseInt(process.env.LYNKR_KNN_MIN_INDEX_SIZE, 10) || 1000;
+// WS5.2 — lowered from 1000 → 100 so kNN advises earlier. The `query()`
+// path dampens confidence by `min(1, size/1000)` when the index is small,
+// so the HIGH/LOW thresholds in `src/routing/index.js` still gate strong
+// advice properly. Override with LYNKR_KNN_MIN_INDEX_SIZE.
+const MIN_INDEX_SIZE = Number.parseInt(process.env.LYNKR_KNN_MIN_INDEX_SIZE, 10) || 100;
+// Cold-start confidence damping — under this many entries, confidence is
+// linearly damped; at DAMP_FULL_SIZE and above, damping is a no-op.
+const DAMP_FULL_SIZE = 1000;
+// Persist the index every N `add()` calls so online growth survives crashes.
+const SAVE_EVERY_N_ADDS = 50;
 
 let _hnsw = null;
 let _hnswLoaded = false;
@@ -110,6 +116,35 @@ class KnnRouter {
     this.index.addPoint(embedding, this.size);
     this.meta.push(outcome);
     this.size++;
+    // WS5.2 — persist online growth incrementally so a crash doesn't lose
+    // the learning done since the last full-index rebuild.
+    if (this.size % SAVE_EVERY_N_ADDS === 0) this.save();
+  }
+
+  /**
+   * WS5.2 — expose the embedder to callers so the routing decision can
+   * capture the query's embedding at decision time and attach it to the
+   * decision object for the feedback path to consume without paying for a
+   * second embedding call. Returns null when the embedder is unavailable
+   * or the returned vector doesn't match the index dimension.
+   *
+   * @param {string} text
+   * @returns {Promise<number[]|null>}
+   */
+  async embed(text) {
+    if (!text || typeof text !== 'string') return null;
+    const cache = getEmbeddingCache();
+    const cached = cache.get(text);
+    if (cached) return cached;
+    try {
+      const embedding = await generateEmbedding(text);
+      if (!embedding || embedding.length !== this.dim) return null;
+      cache.set(text, embedding);
+      return embedding;
+    } catch (err) {
+      logger.debug({ err: err.message }, '[KnnRouter] embed() failed');
+      return null;
+    }
   }
 
   async query(text) {
@@ -117,21 +152,8 @@ class KnnRouter {
     if (!this.ready || !this.index || this.size < MIN_INDEX_SIZE) return null;
     if (!text || typeof text !== 'string') return null;
 
-    const cache = getEmbeddingCache();
-    let embedding = cache.get(text);
-    if (!embedding) {
-      try {
-        embedding = await generateEmbedding(text);
-        if (!embedding || embedding.length !== this.dim) {
-          // Skip if dim mismatch (embedder produced different dimensions)
-          return null;
-        }
-        cache.set(text, embedding);
-      } catch (err) {
-        logger.debug({ err: err.message }, '[KnnRouter] Embedding failed, skipping');
-        return null;
-      }
-    }
+    const embedding = await this.embed(text);
+    if (!embedding) return null;
 
     let result;
     try {
@@ -166,6 +188,13 @@ class KnnRouter {
       agg.count++;
     }
 
+    // WS5.2 — cold-start damping. Below DAMP_FULL_SIZE, multiply confidence
+    // by size/DAMP_FULL_SIZE so a small index advises weakly. The upstream
+    // HIGH/LOW thresholds in index.js then naturally treat sparse advice as
+    // ambiguous rather than trusting it. At/above DAMP_FULL_SIZE the factor
+    // is 1 (no damping).
+    const dampFactor = Math.min(1, this.size / DAMP_FULL_SIZE);
+
     let best = null;
     let bestScore = -Infinity;
     for (const [model, agg] of byModel) {
@@ -182,7 +211,7 @@ class KnnRouter {
           expectedQuality: avgQ,
           expectedCost: avgC,
           expectedLatency: agg.latency / agg.weight,
-          confidence: Math.min(1, agg.weight / K),
+          confidence: Math.min(1, agg.weight / K) * dampFactor,
           neighborCount: agg.count,
         };
       }
@@ -202,12 +231,32 @@ class KnnRouter {
 }
 
 let _instance = null;
+let _beforeExitBound = false;
 function getKnnRouter() {
   if (!_instance) {
     _instance = new KnnRouter();
     _instance.load();
+    // WS5.2 — best-effort persistence on graceful exit so any online
+    // learning done since the last incremental save isn't lost. Bound once
+    // per process; the save() call itself no-ops when the index isn't
+    // ready, so this is safe even in test environments that never populate
+    // the router.
+    if (!_beforeExitBound) {
+      _beforeExitBound = true;
+      try {
+        process.on('beforeExit', () => {
+          try { _instance && _instance.save(); } catch (_) { /* best-effort */ }
+        });
+      } catch (_) { /* not a node process (e.g. worker) */ }
+    }
   }
   return _instance;
 }
 
-module.exports = { KnnRouter, getKnnRouter };
+module.exports = {
+  KnnRouter,
+  getKnnRouter,
+  MIN_INDEX_SIZE,
+  DAMP_FULL_SIZE,
+  SAVE_EVERY_N_ADDS,
+};

package/src/routing/model-registry.js

@@ -15,6 +15,7 @@ const MODELS_DEV_URL = 'https://models.dev/api.json';
 // Cache settings
 const CACHE_FILE = path.join(__dirname, '../../data/model-prices-cache.json');
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const REFRESH_RETRY_MS = 5 * 60 * 1000; // backoff between failed refresh attempts
 
 // Databricks fallback pricing (based on Anthropic direct API prices)
 const DATABRICKS_FALLBACK = {
@@ -103,17 +104,17 @@ class ModelRegistry {
    * Initialize registry - load from cache or fetch fresh data
    */
   async initialize() {
-    if (this.loaded) return;
+    if (this.loaded) {
+      // The sync accessor marks the instance loaded without a staleness
+      // check, so the refresh must not hide behind this return.
+      this._refreshIfStale();
+      return;
+    }
 
     // Try cache first
     if (this._loadFromCache()) {
       this.loaded = true;
-      // Background refresh if stale
-      if (Date.now() - this.lastFetch > CACHE_TTL_MS) {
-        this._fetchAll().catch(err =>
-          logger.warn({ err: err.message }, '[ModelRegistry] Background refresh failed')
-        );
-      }
+      this._refreshIfStale();
       return;
     }
 
@@ -122,6 +123,25 @@ class ModelRegistry {
     this.loaded = true;
   }
 
+  /**
+   * Fire-and-forget background refresh when the cache is past its TTL.
+   * Safe to call from sync paths; concurrent calls coalesce onto one fetch.
+   */
+  _refreshIfStale() {
+    if (Date.now() - this.lastFetch <= CACHE_TTL_MS) return;
+    if (this._refreshInFlight) return;
+    // Failed attempts don't advance lastFetch — back off so a dead network
+    // doesn't turn every routed request into a fetch.
+    if (this._lastRefreshAttempt && Date.now() - this._lastRefreshAttempt < REFRESH_RETRY_MS) return;
+    this._lastRefreshAttempt = Date.now();
+    this._refreshInFlight = true;
+    this._fetchAll()
+      .catch(err =>
+        logger.warn({ err: err.message }, '[ModelRegistry] Background refresh failed')
+      )
+      .finally(() => { this._refreshInFlight = false; });
+  }
+
   /**
    * Fetch from both sources
    */
@@ -488,6 +508,7 @@ function getModelRegistrySync() {
     instance._buildIndex();
     instance.loaded = true;
   }
+  instance._refreshIfStale();
   return instance;
 }
 

package/src/routing/model-tiers.js

@@ -19,12 +19,19 @@ const CALIBRATED_PATH = path.join(__dirname, '../../data/calibrated-thresholds.j
 const TIER_DEFINITIONS = {
   SIMPLE: {
     description: 'Greetings, simple Q&A, confirmations',
-    range: [0, 25],
+    // Boundary at 20, not 25: the top of the trivial intent band (20-25) is
+    // where cheap-model failures cluster. Diagnosed 2026-07-16 from
+    // RouterArena optimality data — SIMPLE-routed queries the cheap model
+    // got wrong (but a bigger pool model got right) re-scored at median 23,
+    // while correctly-served SIMPLE traffic scored median 14. At 20 the
+    // split recovers ~70% of those misses while escalating ~12% of
+    // correct-cheap traffic (usually to a tier that is also local/free).
+    range: [0, 19],
     priority: 1,
   },
   MEDIUM: {
     description: 'Code reading, simple edits, research',
-    range: [26, 50],
+    range: [20, 50],
     priority: 2,
   },
   COMPLEX: {
@@ -330,6 +337,8 @@ class ModelTierSelector {
         return config.ollama?.model || null;
       case 'openrouter':
         return config.openrouter?.model || null;
+      case 'edenai':
+        return config.edenai?.model || null;
       case 'llamacpp':
         return config.llamacpp?.model || null;
       case 'lmstudio':
@@ -487,8 +496,22 @@ function getModelTierSelector() {
   return instance;
 }
 
+/**
+ * WS5.6 — re-read `data/calibrated-thresholds.json` into the singleton
+ * selector so an in-process calibration run takes effect immediately
+ * (no server restart required). Idempotent: safe to call repeatedly.
+ * When the file is missing or malformed, ranges fall back to defaults —
+ * same behaviour as the initial construction path.
+ */
+function reloadCalibratedThresholds() {
+  const selector = getModelTierSelector();
+  selector._loadCalibrated();
+  return selector.ranges;
+}
+
 module.exports = {
   ModelTierSelector,
   getModelTierSelector,
+  reloadCalibratedThresholds,
   TIER_DEFINITIONS,
 };