lynkr 9.14.17 → 9.14.18

package/src/routing/client-profiles.js

@@ -34,6 +34,16 @@ const logger = require('../logger');
  * tool, add it here (or override via data/client-profiles.json).
  */
 const PROFILES = {
+  'terminus': {
+    name: 'terminus',
+    toolless: true,
+    baselineTools: new Set(),
+    detect: {
+      headerPatterns: [],
+      promptPatterns: [/You are an AI assistant tasked with solving command-line tasks/i],
+      minToolFingerprintMatch: 1,
+    },
+  },
   'claude-code': {
     name: 'claude-code',
     baselineTools: new Set([
@@ -257,6 +267,18 @@ function detectClient({ headers = {}, payload = {} } = {}) {
     }
   }
 
+  const firstUser = Array.isArray(payload.messages) ? payload.messages.find((m) => m?.role === 'user') : null;
+  if (firstUser) {
+    const txt = typeof firstUser.content === 'string' ? firstUser.content
+      : Array.isArray(firstUser.content) ? firstUser.content.filter((b) => b?.type === 'text').map((b) => b.text || '').join(' ') : '';
+    if (txt) {
+      for (const profile of Object.values(PROFILES)) {
+        for (const pattern of (profile.detect.promptPatterns || [])) {
+          if (pattern.test(txt)) return profile;
+        }
+      }
+    }
+  }
   const tools = Array.isArray(payload.tools) ? payload.tools : [];
   if (tools.length === 0) return null;
 

package/src/routing/complexity-analyzer.js

@@ -421,6 +421,11 @@ function extractContent(payload) {
   if (!payload?.messages || !Array.isArray(payload.messages)) {
     return '';
   }
+  {
+    const { harnessAskFromPayload } = require('./harness-envelope');
+    const ask = harnessAskFromPayload(payload);
+    if (ask) return ask.text;
+  }
 
   // Get last user message. Harness envelopes (Cursor's <user_info>/<rules>/
   // attached context inside the user message) are stripped so force patterns,
@@ -983,6 +988,7 @@ function shouldForceLocal(payload) {
  * Quick check if request should be forced to cloud
  */
 function shouldForceCloud(payload) {
+  if (process.env.FORCE_TIER_PATTERNS === "false") return false;
   const content = extractContent(payload);
   const matched = FORCE_CLOUD_PATTERNS.find(pattern => pattern.test(content));
   if (matched) {
@@ -997,6 +1003,7 @@ function shouldForceCloud(payload) {
  * from first principles, security audit.
  */
 function shouldForceReasoning(payload) {
+  if (process.env.FORCE_TIER_PATTERNS === "false") return false;
   const content = extractContent(payload);
   const matched = FORCE_REASONING_PATTERNS.find(pattern => pattern.test(content));
   if (matched) {

package/src/routing/decisions.js

@@ -0,0 +1,100 @@
+/**
+ * Decision engine: evaluate signals, walk decisions by priority, first match
+ * wins. Returns a result with a full trace so `lynkr route --preview` and
+ * telemetry can explain every choice.
+ *
+ * In "observe" mode the engine's tier is recorded but the legacy chain's tier
+ * is served. In "enforce" mode routing/index.js adopts the engine's tier when
+ * it differs. The default config has a single `legacy` decision whose tier is
+ * `from:legacy`, so a fresh install agrees with the legacy chain by
+ * construction and operators add decisions above it.
+ */
+'use strict';
+
+const rc = require('./routing-config');
+const signalsMod = require('./signals');
+
+function _evalRule(rule, signals) {
+  const op = String(rule.operator || 'AND').toUpperCase();
+  const conds = Array.isArray(rule.conditions) ? rule.conditions : [];
+  const results = conds.map((c) => (c && typeof c.operator === 'string') ? _evalRule(c, signals) : signalsMod.testCondition(c, signals));
+  if (op === 'NOT') return !results[0];
+  if (op === 'OR') return results.some(Boolean);
+  return results.every(Boolean); // AND; empty = true
+}
+
+function _resolveTier(spec, ctx, signals) {
+  if (!spec) return null;
+  if (spec === 'from:legacy') return ctx.legacy?.tier || null;
+  if (spec === 'from:anchor') return signals.anchor?.band || ctx.legacy?.tier || null;
+  if (spec === 'from:judge') return signals.judge?.tier || ctx.legacy?.tier || null;
+  return rc.TIERS.includes(spec) ? spec : null;
+}
+
+/**
+ * @param {object} ctx — see signals.js
+ * @returns {{ decision, tier, effort, hosts, plugins, mode, signals, trace }}
+ */
+async function evaluate(ctx, config) {
+  const cfg = config || rc.load();
+  const signals = await signalsMod.evaluateAll(ctx, cfg);
+  return decideFromSignals(signals, ctx, cfg);
+}
+
+/**
+ * Pure decision step over already-evaluated signals. Used by evaluate() and
+ * by the corpus regression test (fixtures store signal snapshots so the test
+ * is deterministic without embeddings or the judge).
+ */
+function decideFromSignals(signals, ctx, config) {
+  const cfg = config || rc.load();
+  const considered = [];
+  let matched = null;
+  for (const d of cfg.decisions) {
+    let ok = false;
+    try { ok = _evalRule(d.rules || { operator: 'AND', conditions: [] }, signals); } catch { ok = false; }
+    considered.push({ name: d.name, priority: d.priority, matched: ok });
+    if (ok) { matched = d; break; }
+  }
+  const tier = matched ? _resolveTier(matched.tier, ctx, signals) : (ctx.legacy?.tier || null);
+  // Cascade-on-ambiguity trigger: when the judge's top-two tier probabilities
+  // are within `trigger_margin`, the request is ambiguous. Observe mode only
+  // records the trigger (telemetry: cascade_trigger); enforce is wired later.
+  let cascade = null;
+  const cc = matched?.cascade && typeof matched.cascade === 'object' ? matched.cascade : (cfg.cascade || null);
+  if (cc) {
+    const probs = signals.judge?.probabilities || null;
+    if (probs) {
+      const sorted = Object.values(probs).map(Number).filter(Number.isFinite).sort((a, b) => b - a);
+      const margin = sorted.length >= 2 ? sorted[0] - sorted[1] : 1;
+      const thr = Number.isFinite(cc.trigger_margin) ? cc.trigger_margin : 0.15;
+      cascade = { triggered: margin < thr, margin: Math.round(margin * 1000) / 1000, mode: cc.mode || 'observe', escalate_to: cc.escalate_to || null };
+    }
+  }
+  return {
+    decision: matched ? matched.name : null,
+    tier,
+    effort: matched?.effort ?? null,
+    hosts: Array.isArray(matched?.hosts) ? matched.hosts : null,
+    plugins: matched?.plugins && typeof matched.plugins === 'object' ? matched.plugins : null,
+    mode: cfg.mode === 'enforce' ? 'enforce' : 'observe',
+    cascade,
+    agreesWithLegacy: !ctx.legacy?.tier || tier === ctx.legacy.tier,
+    signals: Object.fromEntries(Object.entries(signals).map(([k, v]) => [k, { matched: v.matched, value: v.value, confidence: v.confidence, band: v.band, tier: v.tier }])),
+    trace: { considered, legacy: ctx.legacy || null },
+  };
+}
+
+/** Compact header-safe summary. */
+function headerSummary(result) {
+  if (!result) return {};
+  const sig = Object.entries(result.signals || {}).filter(([, v]) => v.matched).map(([k, v]) => `${k}=${v.band || v.tier || (typeof v.value === 'object' ? 'y' : v.value)}`).join(',');
+  return {
+    'X-Lynkr-Decision': result.decision || 'none',
+    'X-Lynkr-Decision-Tier': result.tier || '',
+    'X-Lynkr-Decision-Mode': result.mode,
+    'X-Lynkr-Signals': sig.slice(0, 500),
+  };
+}
+
+module.exports = { evaluate, decideFromSignals, headerSummary, mode: rc.mode };

package/src/routing/grounding.js

@@ -0,0 +1,118 @@
+/**
+ * Grounding check for completion claims (HaluGate-style, local NLI).
+ *
+ * When a reply claims the task is done, check whether the evidence the model
+ * had — the most recent tool output / terminal snapshot — supports that claim.
+ * A small NLI cross-encoder (default Xenova/nli-deberta-v3-small, int8, CPU,
+ * ~25 ms per pair) labels each claim entailment / neutral / contradiction.
+ *
+ *   verdict: 'supported' | 'unverified' | 'contradicted' | 'skipped'
+ *
+ * Policy is per decision (routing.json → decisions[].plugins.grounding):
+ *   { mode: "observe" | "flag" | "veto", contradiction_threshold: 0.6 }
+ * observe: telemetry only; flag: + X-Lynkr-Grounding header; veto: caller
+ * re-asks once with the contradiction quoted (not enabled anywhere yet).
+ *
+ * The transformers runtime is loaded lazily from LYNKR_NLI_LIB_PATH or the
+ * normal module path; if absent the module reports 'skipped' and never
+ * throws. Model files cache under LYNKR_MODELS_DIR (default ~/lynkr-models/hf).
+ */
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const logger = require('../logger');
+
+const MODEL_ID = process.env.LYNKR_NLI_MODEL || 'Xenova/nli-deberta-v3-small';
+const MAX_EVIDENCE_CHARS = 4000;
+const MAX_CLAIM_CHARS = 400;
+let _loading = null; // Promise<{tok, model, labels}> | null
+let _unavailable = false;
+
+function _lib() {
+  const p = process.env.LYNKR_NLI_LIB_PATH;
+  try { return p ? require(path.join(p, '@huggingface', 'transformers')) : require('@huggingface/transformers'); } catch { return null; }
+}
+
+async function _load() {
+  if (_unavailable) return null;
+  if (_loading) return _loading;
+  _loading = (async () => {
+    const tf = _lib();
+    if (!tf) { _unavailable = true; logger.warn('[Grounding] @huggingface/transformers not available — grounding disabled'); return null; }
+    tf.env.cacheDir = process.env.LYNKR_MODELS_DIR || path.join(os.homedir(), 'lynkr-models', 'hf');
+    tf.env.allowLocalModels = true;
+    const t0 = Date.now();
+    const tok = await tf.AutoTokenizer.from_pretrained(MODEL_ID);
+    const model = await tf.AutoModelForSequenceClassification.from_pretrained(MODEL_ID, { dtype: process.env.LYNKR_NLI_DTYPE || 'q8' });
+    const labels = Object.fromEntries(Object.entries(model.config.id2label || {}).map(([i, l]) => [Number(i), String(l).toLowerCase()]));
+    logger.info({ model: MODEL_ID, ms: Date.now() - t0 }, '[Grounding] NLI model loaded');
+    return { tf, tok, model, labels };
+  })().catch((err) => { _unavailable = true; logger.warn({ err: err.message }, '[Grounding] model load failed — grounding disabled'); return null; });
+  return _loading;
+}
+
+/** Pull completion-bearing claims out of a reply (structured agents and prose). */
+function extractClaims(replyText) {
+  if (typeof replyText !== 'string' || !replyText.trim()) return { claimsDone: false, claims: [] };
+  const s = replyText.indexOf('{'), e = replyText.lastIndexOf('}');
+  if (s !== -1 && e > s) {
+    try {
+      const obj = JSON.parse(replyText.slice(s, e + 1));
+      if (obj && typeof obj === 'object' && 'is_task_complete' in obj) {
+        const claims = [];
+        for (const k of ['state_analysis', 'explanation', 'summary', 'result']) if (typeof obj[k] === 'string' && obj[k].trim()) claims.push(obj[k].trim().slice(0, MAX_CLAIM_CHARS));
+        return { claimsDone: obj.is_task_complete === true, claims };
+      }
+    } catch { /* fall through to prose */ }
+  }
+  const done = /\b(task (is )?(now )?complete|completed successfully|all (tests )?pass(ed)?|successfully (created|written|installed|fixed)|is now (working|fixed|done))\b/i.test(replyText);
+  const sentences = replyText.split(/(?<=[.!?])\s+/).filter((x) => /\b(complete|done|pass|success|written|created|fixed|installed|verified)\b/i.test(x)).slice(0, 4).map((x) => x.trim().slice(0, MAX_CLAIM_CHARS));
+  return { claimsDone: done, claims: sentences };
+}
+
+/** Evidence = the last user-turn text (tool results / terminal output), tail-truncated. */
+function extractEvidence(messages) {
+  if (!Array.isArray(messages)) return '';
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i]; if (m?.role !== 'user') continue;
+    let t = '';
+    if (typeof m.content === 'string') t = m.content;
+    else if (Array.isArray(m.content)) t = m.content.map((b) => typeof b?.text === 'string' ? b.text : (b?.type === 'tool_result' ? (typeof b.content === 'string' ? b.content : JSON.stringify(b.content || '')) : '')).join('\n');
+    if (t.trim()) return t.length > MAX_EVIDENCE_CHARS ? t.slice(-MAX_EVIDENCE_CHARS) : t;
+  }
+  return '';
+}
+
+/**
+ * @returns {Promise<{verdict, claimsDone, pairs:[{claim, entailment, neutral, contradiction}], maxContradiction, minEntailment, ms}>}
+ */
+async function check({ replyText, messages, evidence = null, onlyWhenDone = true, threshold = 0.6 }) {
+  const t0 = Date.now();
+  const { claimsDone, claims } = extractClaims(replyText);
+  if (onlyWhenDone && !claimsDone) return { verdict: 'skipped', reason: 'no_completion_claim', claimsDone, pairs: [], ms: Date.now() - t0 };
+  const ev = evidence != null ? String(evidence) : extractEvidence(messages);
+  if (!ev.trim()) return { verdict: 'unverified', reason: 'no_evidence', claimsDone, pairs: [], ms: Date.now() - t0 };
+  if (!claims.length) return { verdict: 'unverified', reason: 'no_claims', claimsDone, pairs: [], ms: Date.now() - t0 };
+  const rt = await _load();
+  if (!rt) return { verdict: 'skipped', reason: 'nli_unavailable', claimsDone, pairs: [], ms: Date.now() - t0 };
+  const pairs = [];
+  for (const claim of claims) {
+    const inputs = rt.tok(ev, { text_pair: claim, truncation: true, max_length: 512 });
+    const out = await rt.model(inputs);
+    const probs = rt.tf.softmax(Array.from(out.logits.data));
+    const row = { claim };
+    for (const [i, l] of Object.entries(rt.labels)) row[l] = Math.round(probs[i] * 1000) / 1000;
+    pairs.push(row);
+  }
+  const maxContradiction = Math.max(...pairs.map((p) => p.contradiction || 0));
+  const minEntailment = Math.min(...pairs.map((p) => p.entailment || 0));
+  const anyEntail = pairs.some((p) => (p.entailment || 0) >= 0.5);
+  const verdict = maxContradiction >= threshold ? 'contradicted' : (anyEntail ? 'supported' : 'unverified');
+  return { verdict, claimsDone, pairs, maxContradiction, minEntailment, ms: Date.now() - t0 };
+}
+
+function available() { return !_unavailable && !!_lib(); }
+function warm() { return _load(); }
+
+module.exports = { check, extractClaims, extractEvidence, available, warm, MODEL_ID };

package/src/routing/harness-envelope.js

@@ -48,6 +48,73 @@ const UNCLOSED_RES = ENVELOPE_TAGS.map(
 );
 const USER_QUERY_RE = /<user_query(?:\s[^>]*)?>([\s\S]*?)<\/user_query>/gi;
 
+const HARNESS_PREAMBLE_RES = [
+  /You are an AI assistant tasked with solving command-line tasks/i,
+  /"title":\s*"CommandBatchResponse"/,
+];
+const HARNESS_INSTRUCTION_RE = /(?:^|\n)Instruction:\s*\n([\s\S]*?)\n\s*\n(?:Your response must be|Your response|Respond)/i;
+
+function _patterns() {
+  try {
+    const pats = require('./routing-config').harnessPatterns();
+    if (pats.length) return pats;
+  } catch { /* fall back to built-ins */ }
+  return [{ name: 'harness', preamble: HARNESS_PREAMBLE_RES[0], instruction: HARNESS_INSTRUCTION_RE }];
+}
+
+function matchHarness(text) {
+  if (typeof text !== 'string') return null;
+  for (const p of _patterns()) if (p.preamble.test(text)) return p;
+  return HARNESS_PREAMBLE_RES.some((re) => re.test(text)) ? { name: 'harness', preamble: null, instruction: HARNESS_INSTRUCTION_RE } : null;
+}
+
+function isHarnessPrompt(text) {
+  return matchHarness(text) !== null;
+}
+
+/**
+ * @param {string} text - one user message's text
+ * @returns {string|null} the task instruction when `text` is a recognised
+ *   instruction-schema harness prompt; null otherwise (not a harness prompt,
+ *   or the instruction block could not be isolated).
+ */
+function extractHarnessInstruction(text) {
+  const p = matchHarness(text);
+  if (!p) return null;
+  const re = p.instruction || HARNESS_INSTRUCTION_RE;
+  const m = re.exec(text);
+  const instr = m ? m[1].trim() : '';
+  return instr.length > 0 ? instr : null;
+}
+
+function _msgText(msg) {
+  if (!msg) return '';
+  if (typeof msg.content === 'string') return msg.content;
+  if (Array.isArray(msg.content)) {
+    return msg.content.filter((b) => b?.type === 'text' && typeof b.text === 'string').map((b) => b.text).join(' ');
+  }
+  return '';
+}
+
+/**
+ * Harness-aware ask for a whole payload: when the FIRST user message is a
+ * recognised instruction-schema harness prompt, the task instruction is the
+ * ask for every turn of the session (later user turns are terminal output).
+ * @param {object} payload - { messages }
+ * @returns {{ text: string, index: number }|null}
+ */
+function harnessAskFromPayload(payload) {
+  const msgs = payload?.messages;
+  if (!Array.isArray(msgs)) return null;
+  for (let i = 0; i < msgs.length; i++) {
+    if (msgs[i]?.role !== 'user') continue;
+    const txt = _msgText(msgs[i]);
+    const instr = extractHarnessInstruction(txt);
+    return instr ? { text: instr, index: i, name: (matchHarness(txt) || {}).name || 'harness' } : null;
+  }
+  return null;
+}
+
 /**
  * @param {string} text - one user message's text content
  * @returns {string} the user's ask with harness envelope blocks removed;
@@ -55,6 +122,9 @@ const USER_QUERY_RE = /<user_query(?:\s[^>]*)?>([\s\S]*?)<\/user_query>/gi;
  */
 function stripHarnessEnvelope(text) {
   if (typeof text !== 'string' || text.length === 0) return typeof text === 'string' ? text : '';
+  // Instruction-schema harness prompt → the ask IS the instruction block.
+  const harnessInstr = extractHarnessInstruction(text);
+  if (harnessInstr) return harnessInstr;
   try {
     if (!text.includes('<')) return text;
     const queries = [...text.matchAll(USER_QUERY_RE)].map((m) => m[1].trim()).filter(Boolean);
@@ -68,4 +138,4 @@ function stripHarnessEnvelope(text) {
   }
 }
 
-module.exports = { stripHarnessEnvelope, ENVELOPE_TAGS };
+module.exports = { stripHarnessEnvelope, ENVELOPE_TAGS, isHarnessPrompt, matchHarness, extractHarnessInstruction, harnessAskFromPayload };

package/src/routing/index.js

@@ -680,6 +680,33 @@ async function checkPinScoreDrift(pin, payload) {
  * @returns {{serve:boolean, pin?:object, reason:string, sessionId:string|null}}
  */
 function checkSessionPin(payload, options = {}) {
+  const result = _checkSessionPinInner(payload, options);
+  // Switch gate (switch-gate.js): hysteresis over the session's attributable
+  // turn outcomes. Observe mode annotates; enforce mode drops the pin and
+  // sets a floor so the fresh route that follows lands on the target tier.
+  try {
+    if (result && result.serve && result.pin && result.sessionId) {
+      const gate = require('./switch-gate');
+      const ring = require('./outcomes').ring(result.sessionId);
+      const turns = Array.isArray(payload?.messages) ? payload.messages.filter((m) => m?.role === 'assistant').length : null;
+      const g = gate.evaluate({ sessionId: result.sessionId, currentTier: result.pin.tier, ring, turn: turns, baseTier: result.pin.baseTier || result.pin.tier });
+      result.gate = g;
+      if (g.action !== 'stay') {
+        logger.info({ sessionId: result.sessionId, action: g.action, target: g.target, reason: g.reason, enforced: g.enforced, pinnedTier: result.pin.tier }, g.enforced ? '[SwitchGate] switch enforced — pin dropped' : '[SwitchGate] would switch (observe)');
+        if (g.enforced) {
+          gate.commit(result.sessionId, g, turns);
+          sessionAffinity.removePin(result.sessionId);
+          return { serve: false, pin: result.pin, sessionId: result.sessionId, reason: `switch_gate_${g.action}`, gate: g };
+        }
+      }
+    }
+  } catch (err) {
+    logger.debug({ err: err.message }, '[SwitchGate] evaluation failed (ignored)');
+  }
+  return result;
+}
+
+function _checkSessionPinInner(payload, options = {}) {
   const sessionId = payload?._sessionId || null;
   const stickyEnabled = process.env.LYNKR_STICKY_SESSIONS !== 'false';
   if (!stickyEnabled || !sessionId || options.forceProvider) {
@@ -937,13 +964,18 @@ async function _determineProviderSmartInner(payload, options = {}) {
   // Ollama (~200ms). Both are best-effort and fall through as null.
   let queryText = null;
   let queryEmbedding = null;
-  if (config.routing?.knnEnabled !== false) {
+  if (config.routing?.knnEnabled !== false && process.env.LYNKR_KNN_ENABLED !== 'false') {
     try {
       const msgs = payload?.messages;
-      const lastMsg = Array.isArray(msgs) ? msgs[msgs.length - 1]?.content : null;
-      queryText = typeof lastMsg === 'string' ? lastMsg
-        : Array.isArray(lastMsg) ? lastMsg.filter(b => b?.type === 'text').map(b => b.text || '').join(' ')
-        : null;
+      const _harnessAsk = require('./harness-envelope').harnessAskFromPayload(payload);
+      if (_harnessAsk) {
+        queryText = _harnessAsk.text;
+      } else {
+        const lastMsg = Array.isArray(msgs) ? msgs[msgs.length - 1]?.content : null;
+        queryText = typeof lastMsg === 'string' ? lastMsg
+          : Array.isArray(lastMsg) ? lastMsg.filter(b => b?.type === 'text').map(b => b.text || '').join(' ')
+          : null;
+      }
       if (queryText) {
         queryEmbedding = await getKnnRouter().embed(queryText);
       }
@@ -967,7 +999,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
   // High-risk requests jump straight to COMPLEX and skip the rest of
   // the analysis. This is independent of complexity score — a one-line
   // edit to auth/middleware.ts should never go to a local model.
-  if (risk?.level === 'high' && isFallbackEnabled()) {
+  if (process.env.RISK_TIER_ESCALATION !== 'false' && risk?.level === 'high' && isFallbackEnabled()) {
     try {
       const selector = getModelTierSelector();
       // Config B (local → GLM → Claude): high-risk requests route to the
@@ -1399,7 +1431,9 @@ async function _determineProviderSmartInner(payload, options = {}) {
       && analysis?.mode === 'weighted' && analysis?.breakdown) {
       const { buildRequirementVector } = require('./capabilities');
       const sf = require('./shortfall');
-      const req = buildRequirementVector({ dimensions: analysis.breakdown, agenticResult });
+      const _structuralReq = buildRequirementVector({ dimensions: analysis.breakdown, agenticResult });
+      const _lifted = sf.liftRequirement(_structuralReq, { anchorScore: analysis.anchorScore, jev: analysis.jev });
+      const req = _lifted.req;
       // Candidates constrained to the user's TIER_* (same eligibility rule
       // as the bandit in decide.js) with tier labels attached for capability
       // resolution. Dedupe identical provider:model keeping the highest tier.
@@ -1452,6 +1486,8 @@ async function _determineProviderSmartInner(payload, options = {}) {
         const agreed = serveResult.selected.provider === provider && serveResult.selected.model === selectedModel;
         shortfallInfo = {
           req,
+          structuralReq: _structuralReq,
+          lift: _lifted.lift.applied,
           tau: result.tau,
           selected: serveResult.selected,
           wanted: result.selected,
@@ -1460,6 +1496,8 @@ async function _determineProviderSmartInner(payload, options = {}) {
         };
         logger.debug({
           req,
+          structuralReq: _structuralReq,
+          lift: _lifted.lift.applied,
           tau: result.tau,
           legacy: `${tier}:${provider}:${selectedModel}`,
           shortfall: `${result.selected.tier}:${result.selected.provider}:${result.selected.model}`,
@@ -1742,6 +1780,24 @@ async function _determineProviderSmartInner(payload, options = {}) {
         // Confidence thresholds (env-configurable; defaults 0.7 high / 0.4 low):
         const KNN_HIGH = Number.parseFloat(process.env.LYNKR_KNN_CONFIDENCE_HIGH) || 0.7;
         const KNN_LOW  = Number.parseFloat(process.env.LYNKR_KNN_CONFIDENCE_LOW)  || 0.4;
+        if (knnResult && process.env.LYNKR_KNN_ENABLED === 'false') {
+          knnResult = null;
+        }
+        if (knnResult && knnResult.model) {
+          try {
+            const _sel = getModelTierSelector();
+            const _allowed = new Set();
+            for (const _t of TIER_ORDER) for (const _m of (_sel.getModelsForTier(_t) || [])) _allowed.add(`${_m.provider}:${_m.model}`);
+            const _pick = `${knnResult.provider}:${knnResult.model}`;
+            if (_allowed.size > 0 && !_allowed.has(_pick)) {
+              logger.info({ pick: _pick, confidence: knnResult.confidence?.toFixed?.(3) }, '[Routing] kNN pick not in configured tiers — ignored');
+              knnResult = { ...knnResult, model: null, provider: null };
+            }
+          } catch (err) {
+            logger.debug({ err: err?.message }, '[Routing] kNN tier validation failed — pick ignored');
+            knnResult = { ...knnResult, model: null, provider: null };
+          }
+        }
         if (knnResult && knnResult.confidence > KNN_HIGH && knnResult.model && knnResult.model !== selectedModel) {
           // High confidence — trust kNN's model recommendation directly.
           logger.debug({
@@ -1898,6 +1954,46 @@ async function _determineProviderSmartInner(payload, options = {}) {
     }
   }
 
+  // Switch-gate floor: an enforced escalation set a per-session floor; the
+  // fresh route must not land below it.
+  try {
+    const _sid = payload?._sessionId || options?._sessionId || null;
+    const _floor = _sid ? require('./switch-gate').floor(_sid) : null;
+    if (_floor && (TIER_DEFINITIONS[_floor]?.priority ?? -1) > (TIER_DEFINITIONS[tier]?.priority ?? -1)) {
+      const _fsel = selector.selectModel(_floor, null);
+      if (_fsel && _fsel.provider && _fsel.model) {
+        escalations.push({ source: 'switch_gate_floor', fromTier: tier, toTier: _floor, fromModel: selectedModel, toModel: _fsel.model });
+        tier = _floor; provider = _fsel.provider; selectedModel = _fsel.model; analysis.tier = tier; method = method + '+gate_floor';
+      }
+    }
+  } catch (err) {
+    degradation.record('switch_gate', err);
+  }
+  // Declarative decision engine (config/routing.json). Observe mode records
+  // what it would do; enforce mode adopts its tier when it differs.
+  let engineInfo = null;
+  try {
+    const engine = require('./decisions');
+    engineInfo = await engine.evaluate({
+      payload, analysis, risk, agenticResult,
+      legacy: { tier, provider, model: selectedModel },
+      sessionId: payload?._sessionId || options?._sessionId || null,
+      prevTurns: payload?._sessionId ? require('./outcomes').ring(payload._sessionId) : [],
+    });
+    if (engineInfo && engineInfo.mode === 'enforce' && engineInfo.tier && engineInfo.tier !== tier) {
+      const _esel = selector.selectModel(engineInfo.tier, null);
+      if (_esel && _esel.provider && _esel.model) {
+        escalations.push({ source: `decision:${engineInfo.decision}`, fromTier: tier, toTier: engineInfo.tier, fromModel: selectedModel, toModel: _esel.model });
+        logger.info({ decision: engineInfo.decision, from: `${tier}:${selectedModel}`, to: `${engineInfo.tier}:${_esel.model}` }, '[Routing] Decision engine override');
+        tier = engineInfo.tier; provider = _esel.provider; selectedModel = _esel.model;
+        analysis.tier = tier; method = method + '+decision';
+      }
+    } else if (engineInfo && !engineInfo.agreesWithLegacy) {
+      logger.info({ decision: engineInfo.decision, engineTier: engineInfo.tier, legacyTier: tier }, '[Routing] Decision engine disagrees (observe mode)');
+    }
+  } catch (err) {
+    degradation.record('decisions', err);
+  }
   const decision = buildDecision({
     provider,
     model: selectedModel,
@@ -1924,6 +2020,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
     demoted_from: demotedFrom,
   });
 
+  if (engineInfo) decision.engine = engineInfo;
   // WS4.2 — propensity/candidates for off-policy evaluation from telemetry.
   // Collapse rule lives in decide.js (stampPropensity): if a deterministic
   // downstream override (deadline / tenant) swapped the served model out of

package/src/routing/intent-score.js

@@ -105,6 +105,11 @@ function intentScoreMode() {
 function _latestUserAsk(payload) {
   const msgs = payload?.messages;
   if (!Array.isArray(msgs)) return { text: null, index: -1 };
+  {
+    const { harnessAskFromPayload } = require('./harness-envelope');
+    const ask = harnessAskFromPayload(payload);
+    if (ask) return ask;
+  }
   const { cleanUserText } = require('./jev-router');
   for (let i = msgs.length - 1; i >= 0; i--) {
     const msg = msgs[i];