lynkr 9.10.0 → 9.11.0

package/src/orchestrator/index.js

@@ -21,6 +21,7 @@ const crypto = require("crypto");
 const { getSemanticCache, isSemanticCacheEnabled } = require("../cache/semantic");
 const { areSimilarToolCalls } = require("../clients/gpt-utils");
 const { getModelRegistrySync } = require("../routing/model-registry");
+const sessionAffinity = require("../routing/session-affinity");
 
 /**
  * Get destination URL for audit logging based on provider type
@@ -433,7 +434,7 @@ function injectToolLoopStopInstruction(messages, threshold = 5) {
     // Inject instruction to stop tool calls and provide a final answer
     const stopInstruction = {
       role: "user",
-      content: `⚠️ IMPORTANT: You have already executed ${toolResultCount} tool calls in this conversation. This is likely an infinite loop. STOP calling tools immediately and provide a direct text response to the user based on the information you have gathered. If you cannot complete the task, explain why. DO NOT call any more tools.`,
+      content: `⚠️ IMPORTANT: You have already executed ${toolResultCount} tool calls in this conversation. This is likely an infinite loop. STOP calling tools immediately and provide a direct text response to the user based on the information you have gathered. If you cannot complete the task, explain why. DO NOT call any more tools. Your response must contain your actual findings — NOT an acknowledgment or restatement of this warning.`,
     };
 
     return [...messages, stopInstruction];
@@ -452,6 +453,23 @@ const DEDUP_MAX_SIGNATURES = 50;
 const DEDUP_WARN_THRESHOLD = 5;
 const DEDUP_TERMINATE_THRESHOLD = 8;
 
+/**
+ * State-management tools are called repeatedly with similar args BY DESIGN —
+ * that's their job, not a loop. Opencode calls `todowrite` after every step;
+ * Claude Code uses `TodoWrite`; OpenWorker uses `todo_write`/`propose_plan`.
+ * Counting them in the dedup tracker produced false-positive loop warnings
+ * and force-terminations on healthy agent sessions (live incident: an
+ * opencode analysis run was force-terminated into a raw tool-result dump
+ * because its todo updates hit the terminate threshold).
+ * @param {Object} toolCall - tool_use block
+ * @returns {boolean}
+ */
+function isDedupExemptTool(toolCall) {
+  const raw = toolCall?.function?.name ?? toolCall?.name ?? '';
+  const name = String(raw).toLowerCase().replace(/[_-]/g, '');
+  return name.includes('todo') || name === 'updateplan' || name === 'proposeplan';
+}
+
 /**
  * Initialise session.metadata.toolCallDedup if missing.
  * @param {Object} session
@@ -462,6 +480,7 @@ function ensureDedupStructure(session) {
     session.metadata.toolCallDedup = {
       signatures: {},
       similarGroups: {},
+      seenIds: {},
       lastResetAt: Date.now(),
       warningInjected: false,
     };
@@ -476,9 +495,26 @@ function ensureDedupStructure(session) {
  */
 function recordCrossRequestToolCall(session, toolCall) {
   if (!session?.metadata) return;
+  if (isDedupExemptTool(toolCall)) return; // repeat-by-design tools never count toward loop detection
   ensureDedupStructure(session);
 
   const dedup = session.metadata.toolCallDedup;
+
+  // Stateless HTTP agents (opencode, Cursor, OpenWorker) replay the FULL
+  // conversation history on every agent-loop step, so the same tool_use block
+  // arrives again on step 2, 3, 4… Counting each replay made counts grow
+  // quadratically with turn length — any exploration past ~5 steps hit the
+  // terminate threshold regardless of what it was doing (live incident:
+  // a 7-step opencode code-trace was force-terminated as a "loop").
+  // Each tool_use block carries a unique id: count each id exactly once.
+  const blockId = toolCall?.id;
+  if (blockId) {
+    if (!dedup.seenIds) dedup.seenIds = {};
+    if (dedup.seenIds[blockId]) return; // already counted this exact call
+    dedup.seenIds[blockId] = 1;
+    // Bounded: reset wipes this on each new user question; cap as a backstop.
+    if (Object.keys(dedup.seenIds).length > 500) dedup.seenIds = { [blockId]: 1 };
+  }
   const signature = getToolCallSignature(toolCall);
   const toolName = toolCall.function?.name ?? toolCall.name ?? 'unknown';
   const args = toolCall.function?.arguments ?? toolCall.input;
@@ -620,6 +656,7 @@ function resetDedupTracking(session) {
   session.metadata.toolCallDedup = {
     signatures: {},
     similarGroups: {},
+    seenIds: {},
     lastResetAt: Date.now(),
     warningInjected: false,
   };
@@ -1421,6 +1458,30 @@ async function runAgentLoop({
 
 
     if (steps === 1 && agentTimer) agentTimer.mark("preCompression");
+
+    // === CONVERSATION DISTILLATION (TencentDB-inspired L0-L3 pipeline) ===
+    // Long conversations collapse older turns into one distilled block
+    // (persona + scenario summary) before history compression runs.
+    if (steps === 1 && config.memory?.enabled !== false && config.memory?.distillation?.enabled !== false) {
+      try {
+        const distiller = require('../memory/distiller');
+        if (distiller.needsDistillation(cleanPayload.messages)) {
+          const result = distiller.distillMessages(cleanPayload.messages, {
+            sessionId: session?.id,
+          });
+          if (result.applied) {
+            cleanPayload.messages = result.messages;
+            logger.debug({
+              sessionId: session?.id ?? null,
+              ...result.stats,
+            }, '[distiller] Conversation distillation applied');
+          }
+        }
+      } catch (err) {
+        logger.warn({ err, sessionId: session?.id }, 'Distillation failed, continuing with full history');
+      }
+    }
+
     if (steps === 1 && config.historyCompression?.enabled !== false) {
       try {
         if (historyCompression.needsCompression(cleanPayload.messages)) {
@@ -1883,6 +1944,28 @@ IMPORTANT TOOL USAGE RULES:
     }
   }
 
+  // Cache-aware routing (Phase 1): persist the session's warm-prefix state
+  // from the response's cache counters so the router can price a mid-session
+  // model switch against the live cache clock. Best-effort — never blocks
+  // the response path.
+  if (session?.id && actualUsage) {
+    try {
+      // Prefer the ROUTED provider/model over the request-level default:
+      // the tier router inside invokeModel may have diverged from
+      // providerType, and the cache lives with whoever actually served
+      // (verified live: databricks default label on ollama-served turns).
+      const served = databricksResponse.routingDecision || {};
+      sessionAffinity.recordCacheUsage(session.id, {
+        provider: served.provider || providerType,
+        model: served.model || cleanPayload.model,
+        cacheReadTokens: actualUsage.cacheReadTokens,
+        cacheCreationTokens: actualUsage.cacheCreationTokens,
+      });
+    } catch (err) {
+      logger.debug({ err: err.message }, "[Orchestrator] cache-state update failed");
+    }
+  }
+
   if (auditLogger.enabled) {
     const latencyMs = Date.now() - start;
 
@@ -2879,7 +2962,7 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
         if (Array.isArray(payload?.messages)) {
           payload.messages.push({
             role: "user",
-            content: `⚠️ CRITICAL SYSTEM WARNING: You have called the "${dedupToolName}" tool ${maxCount} times with identical or similar parameters across multiple requests. This IS an infinite loop. STOP calling this tool immediately. You MUST now provide a direct text response based on the results you have received. If the tool returned "no results" or empty output, that IS the final answer - do not retry. Summarize your findings and respond.`,
+            content: `⚠️ CRITICAL SYSTEM WARNING: You have called the "${dedupToolName}" tool ${maxCount} times with identical or similar parameters across multiple requests. This IS an infinite loop. STOP calling this tool immediately. You MUST now provide a direct text response based on the results you have received. If the tool returned "no results" or empty output, that IS the final answer - do not retry. Your response must contain your actual findings from the tool results gathered so far — NOT an acknowledgment or restatement of this warning. Do not mention this warning in your response.`,
           });
         }
       }

package/src/prompts/system.js

@@ -70,13 +70,27 @@ function compressToolDescriptions(tools, mode = null) {
     return tools; // Return unmodified if not in minimal mode
   }
 
+  // Normalize to Anthropic shape: OpenAI-format callers (OpenWorker, aisuite,
+  // any OpenAI SDK) send {type:"function", function:{name, description, parameters}}.
+  // Unwrap once here so the compression logic below can assume input_schema exists.
+  tools = tools.map(tool =>
+    tool?.type === "function" && tool.function
+      ? {
+          name: tool.function.name,
+          description: tool.function.description,
+          input_schema: tool.function.parameters || { type: "object", properties: {} },
+        }
+      : tool
+  );
+
   return tools.map(tool => {
+    const input_schema = tool.input_schema || { type: "object", properties: {} };
     const compressed = {
       name: tool.name,
       input_schema: {
-        type: tool.input_schema.type,
+        type: input_schema.type || "object",
         properties: {},
-        required: tool.input_schema.required || [],
+        required: input_schema.required || [],
       }
     };
 
@@ -86,8 +100,8 @@ function compressToolDescriptions(tools, mode = null) {
     }
 
     // Compress property descriptions
-    if (tool.input_schema.properties) {
-      for (const [key, value] of Object.entries(tool.input_schema.properties)) {
+    if (input_schema.properties) {
+      for (const [key, value] of Object.entries(input_schema.properties)) {
         compressed.input_schema.properties[key] = {
           type: value.type,
         };
@@ -108,8 +122,8 @@ function compressToolDescriptions(tools, mode = null) {
     }
 
     // Preserve additionalProperties if set
-    if (tool.input_schema.additionalProperties !== undefined) {
-      compressed.input_schema.additionalProperties = tool.input_schema.additionalProperties;
+    if (input_schema.additionalProperties !== undefined) {
+      compressed.input_schema.additionalProperties = input_schema.additionalProperties;
     }
 
     return compressed;

package/src/routing/affinity-store.js

@@ -56,6 +56,12 @@ function _db() {
       if (!cols.has("has_tool_history")) {
         db.exec("ALTER TABLE session_pins ADD COLUMN has_tool_history INTEGER DEFAULT 0");
       }
+      // Additive migration for cache-aware routing (Phase 1): JSON blob
+      // holding {warmPrefixTokens, provider, model, lastRequestAt, ttlMs},
+      // updated after every upstream response that reports cache usage.
+      if (!cols.has("cache_state")) {
+        db.exec("ALTER TABLE session_pins ADD COLUMN cache_state TEXT");
+      }
       schemaEnsured = true;
     } catch (err) {
       degradation.record("feedback", err);
@@ -160,6 +166,67 @@ function save(sessionId, pin) {
   }
 }
 
+/**
+ * Persist per-session prompt-cache state (Phase 1, cache-aware routing).
+ * Piggybacks on the session_pins row; creates a minimal row when the session
+ * has no pin yet (possible when sticky sessions are disabled but tracking
+ * is on). Best-effort like everything else in this module.
+ *
+ * @param {string} sessionId
+ * @param {{warmPrefixTokens:number, provider:string, model:string|null, lastRequestAt:number, ttlMs:number}} state
+ */
+function saveCacheState(sessionId, state) {
+  if (!sessionId || !state?.provider) return;
+  const db = _db();
+  if (!db) return;
+  try {
+    const json = JSON.stringify(state);
+    const res = _stmt(
+      db,
+      "cache_state_update",
+      "UPDATE session_pins SET cache_state = ? WHERE session_id = ?"
+    ).run(json, sessionId);
+    if (res.changes === 0) {
+      _stmt(
+        db,
+        "cache_state_insert",
+        `INSERT INTO session_pins (session_id, provider, model, ts, cache_state)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(session_id) DO UPDATE SET cache_state = excluded.cache_state`
+      ).run(sessionId, state.provider, state.model ?? null, Date.now(), json);
+    }
+  } catch (err) {
+    degradation.record("feedback", err);
+  }
+}
+
+/**
+ * Load per-session cache state. Returns null when absent, unparsable, or the
+ * DB is unavailable — callers treat null as "no cache signal for this
+ * session" (provider doesn't report cache usage, or no response seen yet).
+ *
+ * @param {string} sessionId
+ * @returns {{warmPrefixTokens:number, provider:string, model:string|null, lastRequestAt:number, ttlMs:number}|null}
+ */
+function loadCacheState(sessionId) {
+  if (!sessionId) return null;
+  const db = _db();
+  if (!db) return null;
+  try {
+    const row = _stmt(
+      db,
+      "cache_state_load",
+      "SELECT cache_state FROM session_pins WHERE session_id = ?"
+    ).get(sessionId);
+    if (!row?.cache_state) return null;
+    const parsed = JSON.parse(row.cache_state);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch (err) {
+    degradation.record("feedback", err);
+    return null;
+  }
+}
+
 /**
  * Remove a pin.
  * @param {string} sessionId
@@ -205,4 +272,4 @@ function _clear() {
   } catch { /* best-effort */ }
 }
 
-module.exports = { load, save, remove, cleanup, _clear };
+module.exports = { load, save, remove, cleanup, saveCacheState, loadCacheState, _clear };

package/src/routing/agentic-detector.js

@@ -224,13 +224,21 @@ class AgenticDetector {
     const agentType = this._classifyAgentType(score, signals);
     const isAgentic = score >= 25;
 
+    // AGENTIC_DISABLE_FLOOR=1 bypasses the per-agent-type minTier — the raw
+    // complexity score decides the tier without the tools-based bump. Useful
+    // for demos/tests where tool-heavy clients (OpenWorker, aisuite) send 25+
+    // tools on every request and otherwise floor everything to MEDIUM+.
+    const flooredMinTier = process.env.AGENTIC_DISABLE_FLOOR === '1'
+      ? 'SIMPLE'
+      : AGENT_TYPES[agentType].minTier;
+
     const result = {
       isAgentic,
       agentType,
       confidence: Math.min(score / 100, 1),
       score,
       signals,
-      minTier: AGENT_TYPES[agentType].minTier,
+      minTier: flooredMinTier,
       scoreBoost: AGENT_TYPES[agentType].scoreBoost,
       description: AGENT_TYPES[agentType].description,
       clientProfile: profile?.name ?? null,

package/src/routing/cache-economics.js

@@ -0,0 +1,123 @@
+/**
+ * Per-provider prompt-cache economics.
+ *
+ * Single resolution point for "what does the prompt cache cost on this
+ * provider/model": read price, write price, TTL, and mechanism. The
+ * switch-cost math in `cache-switch-cost.js` and the cache-state tracker in
+ * `session-affinity.js` read from here — decision code never hardcodes
+ * per-model numbers.
+ *
+ * Resolution order per field:
+ *   1. model-registry entry (models.dev carries absolute cacheRead/cacheWrite
+ *      $/1M for many models)
+ *   2. provider-type fallback table below (multipliers of the model's input
+ *      price), researched Aug 2026.
+ *
+ * Mechanisms:
+ *   - 'explicit'  — cache_control breakpoints, paid writes (Anthropic-style).
+ *     TTL refreshes on every read, so lastRequestAt + ttlMs is a live clock.
+ *   - 'automatic' — provider caches transparently, writes are free
+ *     (OpenAI/DeepSeek/Gemini-style). TTL is best-effort.
+ *   - 'local'     — no dollar cost at all; the "cost" of a cold prefix is
+ *     prefill latency, handled separately in cache-switch-cost.js.
+ *
+ * @module routing/cache-economics
+ */
+
+const logger = require('../logger');
+
+// Fallback economics keyed by Lynkr provider type. `readMult`/`writeMult`
+// are multipliers of the model's per-1M input price.
+const PROVIDER_CACHE_DEFAULTS = {
+  // Anthropic-hosted (explicit cache_control, 1.25x write for the 5-min TTL,
+  // TTL refreshed on every read).
+  'azure-anthropic': { readMult: 0.1, writeMult: 1.25, ttlMs: 5 * 60 * 1000, mechanism: 'explicit' },
+  bedrock:           { readMult: 0.1, writeMult: 1.25, ttlMs: 5 * 60 * 1000, mechanism: 'explicit' },
+  databricks:        { readMult: 0.1, writeMult: 1.25, ttlMs: 5 * 60 * 1000, mechanism: 'explicit' },
+
+  // OpenAI automatic prefix caching: writes free, ~5-10 min idle eviction.
+  openai:         { readMult: 0.1, writeMult: 0, ttlMs: 10 * 60 * 1000, mechanism: 'automatic' },
+  'azure-openai': { readMult: 0.1, writeMult: 0, ttlMs: 10 * 60 * 1000, mechanism: 'automatic' },
+
+  // Gemini implicit caching / GLM / Kimi / aggregators: free automatic
+  // caching, best-effort TTL. Aggregators (openrouter/edenai) depend on the
+  // underlying model; models.dev per-model data wins when present.
+  vertex:     { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  zai:        { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  moonshot:   { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  openrouter: { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  edenai:     { readMult: 0.1,  writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+  // DeepSeek direct (via aggregators today, kept for model-level matches):
+  deepseek:   { readMult: 0.02, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' },
+
+  // Local runtimes: no dollars; KV cache lives as long as the model stays
+  // loaded (ollama keep_alive default ~5 min).
+  ollama:   { readMult: 0, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'local' },
+  llamacpp: { readMult: 0, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'local' },
+  lmstudio: { readMult: 0, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'local' },
+};
+
+const GENERIC_DEFAULT = { readMult: 0.1, writeMult: 0, ttlMs: 5 * 60 * 1000, mechanism: 'automatic' };
+
+/**
+ * Fallback cache economics for a provider type (no model lookup).
+ * @param {string|null} providerType
+ * @returns {{readMult:number, writeMult:number, ttlMs:number, mechanism:string}}
+ */
+function getProviderCacheDefaults(providerType) {
+  return PROVIDER_CACHE_DEFAULTS[providerType] || GENERIC_DEFAULT;
+}
+
+/**
+ * Resolve full cache economics for a provider/model pair.
+ *
+ * @param {string|null} providerType - Lynkr provider type (e.g. 'databricks')
+ * @param {string|null} model - model name for registry lookup
+ * @returns {{
+ *   inputPerM:number, outputPerM:number,
+ *   cacheReadPerM:number, cacheWritePerM:number,
+ *   ttlMs:number, mechanism:string, unknownPricing:boolean
+ * }} All prices are USD per 1M tokens.
+ */
+function resolveCacheEconomics(providerType, model) {
+  const defaults = getProviderCacheDefaults(providerType);
+
+  let cost = null;
+  try {
+    const { getModelRegistrySync } = require('./model-registry');
+    cost = model ? getModelRegistrySync().getCost(model) : null;
+  } catch (err) {
+    logger.debug({ err: err.message }, '[CacheEconomics] registry lookup failed');
+  }
+
+  const inputPerM = typeof cost?.input === 'number' ? cost.input : 0;
+  const outputPerM = typeof cost?.output === 'number' ? cost.output : 0;
+
+  // Registry cacheTtlMs/cacheMechanism (Phase 4 entries) win over the
+  // provider fallback; models.dev absolute cache prices win over multipliers.
+  const mechanism = cost?.cacheMechanism || defaults.mechanism;
+  const ttlMs = typeof cost?.cacheTtlMs === 'number' ? cost.cacheTtlMs : defaults.ttlMs;
+
+  const cacheReadPerM = mechanism === 'local'
+    ? 0
+    : (typeof cost?.cacheRead === 'number' ? cost.cacheRead : inputPerM * defaults.readMult);
+  const cacheWritePerM = mechanism === 'local'
+    ? 0
+    : (typeof cost?.cacheWrite === 'number' ? cost.cacheWrite : inputPerM * defaults.writeMult);
+
+  return {
+    inputPerM,
+    outputPerM,
+    cacheReadPerM,
+    cacheWritePerM,
+    ttlMs,
+    mechanism,
+    unknownPricing: !!cost?.unknown,
+  };
+}
+
+module.exports = {
+  PROVIDER_CACHE_DEFAULTS,
+  getProviderCacheDefaults,
+  resolveCacheEconomics,
+};

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

@@ -795,7 +795,13 @@ 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,