lynkr 9.10.0 → 9.12.0

package/src/routing/cache-switch-cost.js

@@ -0,0 +1,194 @@
+/**
+ * Switch-cost break-even model (Phase 3, cache-aware routing).
+ *
+ * Answers one question for a session that holds a warm prompt-cache prefix
+ * on its pinned model: does switching to a cheaper target model pay for the
+ * cache it breaks, within the turns this session is expected to have left?
+ *
+ *   stayPerTurn    = warm*cacheRead(cur) + new*input(cur) + out*output(cur)
+ *   switchOnce     = (warm + new) * cacheWrite(target)     // one-time
+ *   switchPerTurn  = warm*cacheRead(tgt) + new*input(tgt) + out*output(tgt)
+ *   breakEvenTurns = switchOnce / (stayPerTurn - switchPerTurn)
+ *
+ * Switch iff breakEvenTurns <= expectedRemainingTurns.
+ *
+ * The output-token term is deliberately included: for de-escalation the
+ * dominant per-turn saving is often the output-price spread (e.g. Opus $25/M
+ * vs Haiku $5/M out), and omitting it makes the router hold expensive pins
+ * long past the point the economics justify.
+ *
+ * Scope: this module prices COST-MOTIVATED switches (de-escalator, bandit
+ * exploration, economic downgrades). Hard triggers — risk keywords, force
+ * phrases, context overflow, vision, upward drift — are never gated here;
+ * correctness beats cost and the math can never favor a pricier model anyway
+ * (savings would be negative).
+ *
+ * Local models have no dollar cost; the price of a cold prefix is prefill
+ * latency, so a warm local prefix above a size threshold holds the pin.
+ *
+ * All pricing comes from cache-economics.js (registry-first, provider
+ * fallback) — no per-model numbers live in this file.
+ *
+ * @module routing/cache-switch-cost
+ */
+
+const config = require('../config');
+const logger = require('../logger');
+
+const PER_TOKEN = 1 / 1_000_000; // registry prices are USD per 1M tokens
+
+function _cfg() {
+  const c = config.routing?.cacheAware || {};
+  return {
+    enabled: c.enabled !== false,
+    defaultRemainingTurns: c.defaultRemainingTurns ?? 10,
+    newTokensPerTurn: c.newTokensPerTurn ?? 2000,
+    outputTokensPerTurn: c.outputTokensPerTurn ?? 800,
+    localMaxSwitchPrefixTokens: c.localMaxSwitchPrefixTokens ?? 16000,
+  };
+}
+
+/**
+ * Evaluate whether a cost-motivated switch away from the session's warm
+ * prefix should be allowed.
+ *
+ * @param {Object} args
+ * @param {Object|null} args.cacheState - from sessionAffinity.getCacheState:
+ *   {warmPrefixTokens, provider, model, lastRequestAt, ttlMs, cold} or null.
+ * @param {{provider:string, model:string|null}} args.current - pinned target.
+ * @param {{provider:string, model:string|null}} args.target - proposed target.
+ * @param {number} [args.newTokensPerTurn] - est. fresh input tokens per turn.
+ * @param {number} [args.outputTokensPerTurn] - est. output tokens per turn.
+ * @param {number|null} [args.expectedRemainingTurns] - median remaining
+ *   turns; falls back to the conservative config default when null.
+ * @param {Object} [args.deps] - test injection: {resolveCacheEconomics}.
+ * @returns {{
+ *   switchAllowed: boolean,
+ *   reason: string,
+ *   breakEvenTurns: number|null,
+ *   expectedRemainingTurns: number,
+ *   warmPrefixTokens: number,
+ *   switchOnceUsd: number|null,
+ *   stayPerTurnUsd: number|null,
+ *   switchPerTurnUsd: number|null,
+ *   projectedStaySavingsUsd: number|null,
+ * }}
+ */
+function evaluateSwitch({
+  cacheState,
+  current,
+  target,
+  newTokensPerTurn,
+  outputTokensPerTurn,
+  expectedRemainingTurns,
+  deps = {},
+} = {}) {
+  const cfg = _cfg();
+  const remaining = Number.isFinite(expectedRemainingTurns) && expectedRemainingTurns > 0
+    ? expectedRemainingTurns
+    : cfg.defaultRemainingTurns;
+
+  const base = {
+    switchAllowed: true,
+    reason: 'no_cache_state',
+    breakEvenTurns: null,
+    expectedRemainingTurns: remaining,
+    warmPrefixTokens: cacheState?.warmPrefixTokens ?? 0,
+    switchOnceUsd: null,
+    stayPerTurnUsd: null,
+    switchPerTurnUsd: null,
+    projectedStaySavingsUsd: null,
+  };
+
+  if (!cfg.enabled) return { ...base, reason: 'feature_disabled' };
+  if (!current?.provider || !target?.provider) return base;
+  if (current.provider === target.provider && current.model === target.model) {
+    return { ...base, reason: 'same_model' };
+  }
+
+  // No tracked state → nothing warm to protect (provider reports no cache
+  // usage, or no response seen yet). Switching is cache-free.
+  if (!cacheState || !(cacheState.warmPrefixTokens > 0)) return base;
+
+  // State recorded for a different model than the pin we're defending —
+  // stale after a prior switch; treat as no protection.
+  if (cacheState.model && current.model && cacheState.model !== current.model) {
+    return { ...base, reason: 'stale_cache_state' };
+  }
+
+  // Phase 2 — TTL clock. Anthropic-style caches refresh on every read, so
+  // lastRequestAt + ttlMs going stale means the prefix is already cold and
+  // the switch costs nothing extra.
+  if (cacheState.cold) return { ...base, reason: 'cache_cold' };
+
+  let resolve = deps.resolveCacheEconomics;
+  if (typeof resolve !== 'function') {
+    ({ resolveCacheEconomics: resolve } = require('./cache-economics'));
+  }
+
+  const econCur = resolve(current.provider, current.model);
+  const econTgt = resolve(target.provider, target.model);
+
+  const W = cacheState.warmPrefixTokens;
+  const N = Number.isFinite(newTokensPerTurn) && newTokensPerTurn >= 0
+    ? newTokensPerTurn : cfg.newTokensPerTurn;
+  const O = Number.isFinite(outputTokensPerTurn) && outputTokensPerTurn >= 0
+    ? outputTokensPerTurn : cfg.outputTokensPerTurn;
+
+  // Local pin: no dollars in either column — the cost of abandoning the
+  // warm prefix is prefill latency on whatever serves the next turn.
+  // Hold while the prefix is large; small prefixes re-fill fast enough.
+  if (econCur.mechanism === 'local' && econTgt.mechanism === 'local') {
+    const allowed = W <= cfg.localMaxSwitchPrefixTokens;
+    return {
+      ...base,
+      switchAllowed: allowed,
+      reason: allowed ? 'local_prefix_small' : 'local_prefill_hold',
+    };
+  }
+
+  const stayPerTurn = (W * econCur.cacheReadPerM + N * econCur.inputPerM + O * econCur.outputPerM) * PER_TOKEN;
+  const switchOnce = (W + N) * econTgt.cacheWritePerM * PER_TOKEN;
+  const switchPerTurn = (W * econTgt.cacheReadPerM + N * econTgt.inputPerM + O * econTgt.outputPerM) * PER_TOKEN;
+  const savingsPerTurn = stayPerTurn - switchPerTurn;
+
+  const priced = {
+    ...base,
+    switchOnceUsd: switchOnce,
+    stayPerTurnUsd: stayPerTurn,
+    switchPerTurnUsd: switchPerTurn,
+    projectedStaySavingsUsd: savingsPerTurn,
+  };
+
+  // Switching to a same-or-more-expensive target never pays on economics.
+  // (Escalations don't route through this gate, so blocking is safe.)
+  if (savingsPerTurn <= 0) {
+    return {
+      ...priced,
+      switchAllowed: false,
+      reason: 'never_profitable',
+      breakEvenTurns: Infinity,
+    };
+  }
+
+  const breakEvenTurns = switchOnce / savingsPerTurn;
+  const allowed = breakEvenTurns <= remaining;
+
+  logger.debug({
+    current: `${current.provider}:${current.model}`,
+    target: `${target.provider}:${target.model}`,
+    warmPrefixTokens: W,
+    breakEvenTurns: Number(breakEvenTurns.toFixed(2)),
+    expectedRemainingTurns: remaining,
+    allowed,
+  }, '[CacheSwitchCost] break-even evaluated');
+
+  return {
+    ...priced,
+    switchAllowed: allowed,
+    reason: allowed ? 'break_even_cleared' : 'break_even_blocked',
+    breakEvenTurns,
+  };
+}
+
+module.exports = { evaluateSwitch };

package/src/routing/calibration.js

@@ -146,7 +146,8 @@ function runCalibration({ days = DEFAULT_DAYS, dryRun = false, dbPath, outputPat
       continue;
     }
     const ordered = Array.from(tierBuckets.entries()).sort((a, b) => a[0] - b[0]);
-    let suggestedUpper = DEFAULT_RANGES[tier][1];
+    const [defaultLower, defaultUpper] = DEFAULT_RANGES[tier];
+    let suggestedUpper = defaultUpper;
     const bucketsSummary = [];
     for (const [lo, vals] of ordered) {
       if (vals.length < 5) {
@@ -155,6 +156,12 @@ function runCalibration({ days = DEFAULT_DAYS, dryRun = false, dbPath, outputPat
       }
       const med = _median(vals);
       bucketsSummary.push({ bucket: lo, samples: vals.length, median: med });
+      // Buckets outside the tier's own default range come from fallback-served
+      // requests (another tier's scores recorded under the serving tier). They
+      // say nothing about this tier's real range, and letting them shrink the
+      // upper bound below the lower bound collapses the tier to a single point
+      // in re-stitching (observed 2026-07-26: MEDIUM → [20,20]).
+      if (lo + 4 < defaultLower || lo > defaultUpper) continue;
       if (med < floor && lo + 4 < suggestedUpper) {
         // shrink tier upper bound just below the failing bucket
         suggestedUpper = lo + 4;

package/src/routing/complexity-analyzer.js

@@ -16,6 +16,7 @@ const logger = require('../logger');
 const config = require('../config');
 const codeGraph = require('../tools/code-graph');
 const clientProfiles = require('./client-profiles');
+const { compressMessages, shouldCompress } = require('./context-compressor');
 
 /**
  * Return the tools the user actually added beyond the client harness's
@@ -769,13 +770,31 @@ function getThreshold() {
  * @returns {Object} Complexity analysis result
  */
 async function analyzeComplexity(payload, options = {}) {
-  const content = extractContent(payload);
-  const messageCount = payload?.messages?.length ?? 0;
+  // Phase 0: Context Compression (TencentDB-inspired)
+  // Compress conversation before scoring to account for token reduction
+  let workingPayload = payload;
+  let compressionStats = null;
+
+  const useCompression = options.compression ?? config.routing?.compression ?? true;
+  if (useCompression && shouldCompress(payload)) {
+    const { compressed, stats } = compressMessages(payload.messages);
+    compressionStats = stats;
+    workingPayload = { ...payload, messages: compressed };
+
+    logger.debug({
+      reduction: stats.reduction,
+      originalTokens: stats.original,
+      compressedTokens: stats.compressed,
+    }, '[complexity] Context compressed');
+  }
+
+  const content = extractContent(workingPayload);
+  const messageCount = workingPayload?.messages?.length ?? 0;
   const useWeighted = options.weighted ?? config.routing?.weightedScoring ?? false;
 
   // Use weighted scoring if enabled
   if (useWeighted) {
-    const weighted = calculateWeightedScore(payload, content);
+    const weighted = calculateWeightedScore(workingPayload, content);
     const threshold = getThreshold();
     const mode = config.smartToolSelection?.mode ?? 'heuristic';
 
@@ -795,12 +814,19 @@ async function analyzeComplexity(payload, options = {}) {
       threshold,
       mode: 'weighted',
       recommendation,
-      breakdown: weighted.dimensions,
+      // taskType rides alongside the numeric dimensions. The legacy path
+      // has always carried breakdown.taskType, and both the deescalator
+      // (tier + request_type evidence key) and the telemetry request_type
+      // column derive from it — without it here, weighted-mode requests
+      // (the default) recorded request_type NULL and could never
+      // accumulate demotion evidence.
+      breakdown: { ...weighted.dimensions, taskType: taskTypeResult },
       weights: weighted.weights,
       meta: weighted.meta,
       forceReason: taskTypeResult.reason?.startsWith('force_') ? taskTypeResult.reason : null,
       content: content.slice(0, 100) + (content.length > 100 ? '...' : ''),
       graphSignals: null,
+      compression: compressionStats, // Add compression stats
     };
 
     // Phase 5: Structural Analysis (code-review-graph, optional)
@@ -835,9 +861,9 @@ async function analyzeComplexity(payload, options = {}) {
     return result;
   }
 
-  // Standard scoring (original logic)
-  const tokenScore = scoreTokens(payload);
-  const toolScore = scoreTools(payload);
+  // Standard scoring (original logic) - use compressed payload
+  const tokenScore = scoreTokens(workingPayload);
+  const toolScore = scoreTools(workingPayload);
   const taskTypeResult = scoreTaskType(content);
   const codeComplexityResult = scoreCodeComplexity(content);
   const reasoningResult = scoreReasoning(content);
@@ -875,8 +901,8 @@ async function analyzeComplexity(payload, options = {}) {
     mode,
     recommendation,
     breakdown: {
-      tokens: { score: tokenScore, estimated: estimateTokens(payload) },
-      tools: { score: toolScore, count: _effectiveTools(payload).length },
+      tokens: { score: tokenScore, estimated: estimateTokens(workingPayload) },
+      tools: { score: toolScore, count: _effectiveTools(workingPayload).length },
       taskType: taskTypeResult,
       codeComplexity: codeComplexityResult,
       reasoning: reasoningResult,
@@ -884,11 +910,12 @@ async function analyzeComplexity(payload, options = {}) {
     },
     content: content.slice(0, 100) + (content.length > 100 ? '...' : ''),
     graphSignals: null,
+    compression: compressionStats, // Add compression stats
   };
 
   // Phase 5: Structural Analysis (code-review-graph, optional)
   try {
-    const filePaths = extractFilePaths(payload);
+    const filePaths = extractFilePaths(workingPayload);
     const graphOpts = { filePaths, workspace: options?.workspace };
     const graphAvailable = await codeGraph.isAvailable(graphOpts);
     if (graphAvailable && filePaths.length > 0) {

package/src/routing/context-compressor.js

@@ -0,0 +1,170 @@
+/**
+ * Context Compression Module
+ *
+ * Inspired by TencentDB Agent Memory's short-term memory compression.
+ * Reduces conversation context size before complexity scoring to enable
+ * more accurate tier routing.
+ *
+ * Key insight: Long conversations bloat context → force expensive routing
+ * even for simple follow-ups. By compressing tool outputs and previous
+ * turns, we keep more requests in SIMPLE/MEDIUM tiers.
+ *
+ * @module routing/context-compressor
+ */
+
+const logger = require('../logger');
+
+/**
+ * Compress conversation messages by:
+ * 1. Offloading verbose tool_result content
+ * 2. Summarizing repetitive patterns
+ * 3. Keeping only essential context for scoring
+ *
+ * Does NOT modify the actual request sent to LLM — only used for complexity scoring.
+ *
+ * @param {Array} messages - Conversation messages
+ * @returns {{ compressed: Array, stats: Object }} - Compressed messages + stats
+ */
+function compressMessages(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return { compressed: messages, stats: { original: 0, compressed: 0, ratio: 1.0 } };
+  }
+
+  const compressed = [];
+  let originalSize = 0;
+  let compressedSize = 0;
+  let toolResultsOffloaded = 0;
+  let messagesKept = 0;
+
+  // Keep system message always
+  const systemMsg = messages.find(m => m.role === 'system');
+  if (systemMsg) {
+    compressed.push(systemMsg);
+    const size = estimateMessageSize(systemMsg);
+    originalSize += size;
+    compressedSize += size;
+  }
+
+  // Keep last N user/assistant turns (sliding window)
+  const WINDOW_SIZE = 5;
+  const recentTurns = messages
+    .filter(m => m.role === 'user' || m.role === 'assistant')
+    .slice(-WINDOW_SIZE);
+
+  for (const msg of recentTurns) {
+    const original = estimateMessageSize(msg);
+    originalSize += original;
+
+    // Compress tool_result blocks (biggest token consumers)
+    if (Array.isArray(msg.content)) {
+      const compressedContent = msg.content.map(block => {
+        if (block?.type === 'tool_result') {
+          toolResultsOffloaded++;
+          // Keep only metadata, offload actual content
+          return {
+            type: 'tool_result',
+            tool_use_id: block.tool_use_id,
+            content: '[offloaded]', // Replaced with placeholder
+            _compressed: true,
+          };
+        }
+        return block;
+      });
+
+      const compressedMsg = { ...msg, content: compressedContent };
+      compressed.push(compressedMsg);
+      compressedSize += estimateMessageSize(compressedMsg);
+      messagesKept++;
+    } else {
+      // No compression needed for string content
+      compressed.push(msg);
+      compressedSize += original;
+      messagesKept++;
+    }
+  }
+
+  const ratio = originalSize > 0 ? compressedSize / originalSize : 1.0;
+
+  const stats = {
+    original: originalSize,
+    compressed: compressedSize,
+    ratio,
+    reduction: Math.round((1 - ratio) * 100),
+    toolResultsOffloaded,
+    messagesKept,
+    messagesDropped: messages.length - messagesKept - (systemMsg ? 1 : 0),
+  };
+
+  logger.debug({
+    ...stats,
+    originalMsgs: messages.length,
+    compressedMsgs: compressed.length,
+  }, '[context-compressor] Compression complete');
+
+  return { compressed, stats };
+}
+
+/**
+ * Estimate message size in tokens (rough heuristic: chars / 4)
+ */
+function estimateMessageSize(msg) {
+  if (!msg) return 0;
+
+  let size = 0;
+
+  // Role + metadata overhead
+  size += 10;
+
+  // Content
+  if (typeof msg.content === 'string') {
+    size += Math.ceil(msg.content.length / 4);
+  } else if (Array.isArray(msg.content)) {
+    for (const block of msg.content) {
+      if (block?.type === 'text' && block.text) {
+        size += Math.ceil(block.text.length / 4);
+      } else if (block?.type === 'tool_result') {
+        // Tool results are verbose (code, logs, errors)
+        const content = Array.isArray(block.content)
+          ? block.content.map(c => c?.text || '').join('')
+          : (block.content || '');
+        size += Math.ceil(content.length / 4);
+      } else if (block?.type === 'tool_use') {
+        // Tool use is compact (function name + args)
+        size += 50;
+      }
+    }
+  }
+
+  return size;
+}
+
+/**
+ * Check if compression is beneficial for this payload.
+ * Only compress if conversation is long enough to matter.
+ */
+function shouldCompress(payload) {
+  if (!payload?.messages || !Array.isArray(payload.messages)) {
+    return false;
+  }
+
+  const msgCount = payload.messages.length;
+
+  // Count total tool_result blocks (not just messages with tool results)
+  let toolResultCount = 0;
+  for (const msg of payload.messages) {
+    if (Array.isArray(msg.content)) {
+      toolResultCount += msg.content.filter(c => c?.type === 'tool_result').length;
+    }
+  }
+
+  // Compress if:
+  // 1. More than 10 messages (long conversation), OR
+  // 2. More than 3 tool_result blocks (verbose outputs)
+  return msgCount > 10 || toolResultCount > 3;
+}
+
+module.exports = {
+  compressMessages,
+  shouldCompress,
+  estimateMessageSize,
+};

package/src/routing/difficulty-classifier.js

@@ -7,14 +7,16 @@
  * hard problems. An LLM reading the actual sentence knows better.
  *
  * DESIGN:
- *  - Uses whatever model is configured for the SIMPLE tier (fetched at call
- *    time via getModelTierSelector). When the user later swaps in a
- *    fine-tuned classifier as SIMPLE, this picks it up automatically.
+ *  - Dedicated classifier model (CLASSIFIER_MODEL below), deliberately
+ *    decoupled from tier serving — swapping TIER_* env vars does not change
+ *    what classifies prompts. The tier DEPLOYMENT (which models the tiers
+ *    route to) is surfaced to the classifier as tie-breaker context; see
+ *    _buildTierContext.
  *  - Structured JSON output; parse failure → null → caller falls back.
- *  - Hard 2500ms timeout; on timeout → null → caller falls back.
+ *  - Hard timeout (TIMEOUT_MS); on timeout → null → caller falls back.
  *  - LRU cache keyed by sha256(text.trim().toLowerCase()); capacity 500.
  *  - Skip conditions surface via classifyDifficulty returning null with
- *    reason=skipped: text.length<15, force-pattern matched, risk=high,
+ *    reason=skipped: empty text, force-pattern matched, risk=high,
  *    cache hit is transparent (returns cached).
  *  - Hardcoded kill-switch CLASSIFIER_ENABLED — no env var per user policy.
  *
@@ -31,7 +33,6 @@ const CLASSIFIER_ENABLED = true;
 // LRU cache to keep amortized latency low.
 const TIMEOUT_MS = 10000;
 const CACHE_CAPACITY = 500;
-const MIN_TEXT_LENGTH = 15;
 
 // Classifier model — decoupled from tier serving so SIMPLE tier can run a
 // more capable model for real traffic while the classifier stays fast and
@@ -44,7 +45,7 @@ const CLASSIFIER_MODEL = 'qwen2.5:3b';
 
 const VALID_TIERS = ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING'];
 
-// One-shot classification prompt (v2). Kept in a const so drift is diffable.
+// One-shot classification prompt (v3). Kept in a const so drift is diffable.
 // Difficulty framing (not intent) — matches config B routing goals.
 //
 // v2 (2026-07-21): added the follow-up rule, negative examples under
@@ -54,11 +55,16 @@ const VALID_TIERS = ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING'];
 // flavored and nothing said surface vocabulary isn't the signal. Baseline
 // on data/difficulty-eval-followups.jsonl: 60% overall, 33% on SIMPLE,
 // 3 SIMPLE→REASONING criticals.
+//
+// v3 (2026-08-09): added trivial-arithmetic SIMPLE examples after a live
+// over-route: "12+21" scored anchor 25 (MEDIUM band) and qwen ALSO said
+// MEDIUM conf 1.0 — bare arithmetic read as "a specific mechanical task".
+// Any tiny model adds two numbers; it belongs in SIMPLE.
 const CLASSIFY_PROMPT = `You are a classifier for an LLM routing proxy. Classify the difficulty of the CURRENT user prompt into exactly one of four tiers. Reply with ONLY valid JSON on a single line, no other text.
 
 Tiers:
 - SIMPLE: casual acknowledgments, greetings, one-word answers, trivial factual lookups, and short conversational follow-up questions about people, stories, events, or everyday facts. Any tiny model handles.
-  examples: "hi", "ok thanks", "yes continue", "what time is it", "who is doctor doom?", "who kills him?", "why did he do that?", "and then what happened?", "does bleach kill mold?"
+  examples: "hi", "ok thanks", "yes continue", "what time is it", "who is doctor doom?", "who kills him?", "why did he do that?", "and then what happened?", "does bleach kill mold?", "12+21", "what is 15% of 80?", "convert 3km to miles"
 - MEDIUM: one specific mechanical task or a focused explanation. Mid-size local model suffices.
   examples: "list the exports from this file", "run the unit tests", "fix the linter warnings", "explain this regex", "add error handling to this block", "verify the file exists before reading it"
 - COMPLEX: multi-file design, systemic refactor, architecture review, debugging that requires broad code understanding. Needs a strong general model.
@@ -81,15 +87,101 @@ Reply format (strict): {"tier":"SIMPLE|MEDIUM|COMPLEX|REASONING","confidence":0.
 const CONTEXT_MAX_TEXT_LENGTH = 40;
 const CONTEXT_MAX_CHARS = 300;
 
+// --- Tier deployment context -------------------------------------------------
+//
+// Tells the classifier WHAT each tier routes to (model + coarse traits from
+// the registry), so borderline verdicts can weigh the actual fleet — e.g.
+// prefer MEDIUM when its configured model is a large cloud model, or lean
+// away from a tier whose model lacks the needed capability.
+//
+// Constraints that shape the design:
+//  - TIE-BREAKER ONLY. The difficulty rubric in CLASSIFY_PROMPT governs;
+//    the deployment block must not redefine what the tiers mean, or eval
+//    labels (data/difficulty-eval*.jsonl) stop being comparable.
+//  - BYTE-STABLE per process. Tier config is env-driven and fixed for the
+//    process lifetime, so the block is built once and memoized. It also
+//    participates in the LRU cache key (fingerprint) so a reconfigured
+//    deployment never serves verdicts cached under the old one.
+//  - FAIL-SAFE. Registry misses or config errors degrade to provider-type
+//    traits or to no block at all — classification proceeds regardless.
+// MEASURED OFF (2026-08-08): A/B on data/difficulty-eval-followups.jsonl —
+// baseline 84.0% overall / 0 SIMPLE→REASONING criticals; with the block
+// 76.0% / 1 critical ('prove me wrong lol' → REASONING conf 1.0, the exact
+// failure class prompt v2 was built to kill). qwen2.5:3b can't use fleet
+// info — it dilutes the rubric. Machinery kept dark for a future stronger
+// classifier: flip this flag, then re-run
+// scripts/validate-difficulty-classifier.js on BOTH eval files and hold
+// the ship bar (>=85% overall, zero MEDIUM→REASONING false positives).
+const TIER_CONTEXT_ENABLED = false;
+const LOCAL_PROVIDERS = new Set(['ollama', 'llamacpp', 'lmstudio']);
+
+/** Pure builder — exported for tests. @param {Object} tiers {TIER: 'provider:model'} */
+function _buildTierContext(tiers) {
+  const lines = [];
+  for (const tier of VALID_TIERS) {
+    const spec = tiers?.[tier];
+    if (typeof spec !== 'string' || !spec.includes(':')) continue;
+    const sep = spec.indexOf(':');
+    const provider = spec.slice(0, sep);
+    const model = spec.slice(sep + 1);
+    const traits = [LOCAL_PROVIDERS.has(provider) ? 'local' : 'cloud'];
+    try {
+      const { getModelRegistrySync } = require('./model-registry');
+      const cost = getModelRegistrySync().getCost(model);
+      if (cost && !cost.unknown) {
+        if (Number.isFinite(cost.context) && cost.context >= 1000) {
+          traits.push(`${Math.round(cost.context / 1000)}k ctx`);
+        }
+        if (cost.reasoning) traits.push('reasoning');
+        if (cost.vision) traits.push('vision');
+      }
+    } catch { /* registry unavailable — provider trait only */ }
+    lines.push(`- ${tier} routes to ${model} (${traits.join(', ')})`);
+  }
+  if (!lines.length) return null;
+  const block = `Deployment (what each tier currently routes to — use only as a tie-breaker between adjacent tiers; the tier definitions above still govern):
+${lines.join('\n')}`;
+  return {
+    block,
+    fingerprint: crypto.createHash('sha256').update(block).digest('hex').slice(0, 16),
+  };
+}
+
+/** @type {{block:string, fingerprint:string}|null|undefined} undefined = not built yet */
+let _tierContext;
+
+function _tierDeploymentContext() {
+  // Test override (set via _setTierContextForTests) wins over the flag so
+  // the machinery stays exercised while shipping dark.
+  if (_tierContext !== undefined) return _tierContext;
+  if (!TIER_CONTEXT_ENABLED) { _tierContext = null; return null; }
+  try {
+    const config = require('../config');
+    _tierContext = _buildTierContext(config.modelTiers);
+  } catch {
+    _tierContext = null;
+  }
+  return _tierContext;
+}
+
+/** Test helper — override or reset (pass undefined) the memoized block. */
+function _setTierContextForTests(tiers) {
+  _tierContext = tiers === undefined ? undefined : _buildTierContext(tiers);
+}
+
 function _buildPrompt(text, context) {
+  const tierCtx = _tierDeploymentContext();
+  const preamble = tierCtx ? `${CLASSIFY_PROMPT}
+${tierCtx.block}
+` : CLASSIFY_PROMPT;
   if (context) {
-    return `${CLASSIFY_PROMPT}
+    return `${preamble}
 Conversation so far (context only — classify the CURRENT prompt, inheriting topic difficulty per the rules):
 ${context}
 
 CURRENT user prompt: """${text}"""`;
   }
-  return `${CLASSIFY_PROMPT}
+  return `${preamble}
 User prompt: """${text}"""`;
 }
 
@@ -212,7 +304,12 @@ async function classifyDifficulty(text, opts = {}) {
   if (!CLASSIFIER_ENABLED) return null;
   if (typeof text !== 'string') return null;
   const trimmed = text.trim();
-  if (trimmed.length < MIN_TEXT_LENGTH) return null;
+  // No minimum length (removed 2026-08-09): short prompts are exactly what
+  // the v2 context feature was built for, and the 15-char gate meant the
+  // classifier could never rescue anchor over-reads like '12+21' -> MEDIUM.
+  // Greetings still skip upstream via force patterns (opts.forceMatched),
+  // and the LRU absorbs repeats, so the added model calls are bounded.
+  if (!trimmed) return null;
   if (opts.forceMatched) return null;
   if (opts.riskLevel === 'high') return null;
 
@@ -222,8 +319,11 @@ async function classifyDifficulty(text, opts = {}) {
       : null;
 
   // Context participates in the cache key: the same follow-up text means
-  // different things in different conversations.
-  const key = _cacheKey(context ? `${trimmed}${context}` : trimmed);
+  // different things in different conversations. The tier-deployment
+  // fingerprint participates too (NUL separators are collision-proof), so
+  // verdicts cached under one deployment never serve a reconfigured one.
+  const tierFp = _tierDeploymentContext()?.fingerprint ?? "";
+  const key = _cacheKey(`${tierFp}${context ? `${trimmed}${context}` : trimmed}`);
   const cached = _cache.get(key);
   if (cached) return { ...cached, source: 'cache' };
 
@@ -256,6 +356,8 @@ module.exports = {
   _parseResult,
   _cacheKey,
   _buildPrompt,
+  _buildTierContext,
+  _setTierContextForTests,
   _clearCacheForTests,
   _getCacheStats,
 };