thumbgate 1.34.3 → 1.37.1

package/scripts/stealth-memory-injection-gate.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Stealth memory injection gate (MemGhost / WhisperBench 2026).
+ *
+ * Paper: "When Claws Remember but Do Not Tell: Stealthy Memory Injection in
+ * Persistent Personal Agents" (arXiv/HF 2607.05189).
+ *
+ * Threat: untrusted external content (email/IMAP/tool results) induces a
+ * persistent personal agent to write poisoned facts/preferences into durable
+ * memory carriers (MEMORY.md, AGENTS.md, SOUL.md, …) while staying silent in
+ * the user-visible response — later sessions then trust that state.
+ *
+ * ThumbGate role: pre-action deny when a write targets a durable carrier AND
+ * the action/content shows external untrusted provenance and/or stealth
+ * memory-injection language.
+ */
+
+const GATE_ID = 'block-stealth-memory-injection-from-external';
+const PAPER_ID = '2607.05189';
+const PAPER_URL = 'https://huggingface.co/papers/2607.05189';
+
+/** Omnipresent / high-availability carriers (paper: carrier availability). */
+const DURABLE_CARRIER_PATTERNS = [
+  /(?:^|\/)MEMORY\.md$/i,
+  /(?:^|\/)AGENTS\.md$/i,
+  /(?:^|\/)USER\.md$/i,
+  /(?:^|\/)IDENTITY\.md$/i,
+  /(?:^|\/)SOUL\.md$/i,
+  /(?:^|\/)HEARTBEAT\.md$/i,
+  /(?:^|\/)prevention-rules\.md$/i,
+  /(?:^|\/)memory\/\d{4}-\d{2}-\d{2}\.md$/i,
+  /(?:^|\/)\.thumbgate\/prevention-rules\.md$/i,
+  /(?:^|\/)\.claude\/memory\/feedback\/prevention-rules\.md$/i,
+  /(?:^|\/)BRAIN\.md$/i,
+];
+
+/** Episodic / retrieval-dependent paths still risky when stealth + external. */
+const EPISODIC_MEMORY_PATTERNS = [
+  /(?:^|\/)memory\//i,
+  /(?:^|\/)\.claude\/projects\/.*\/memory\//i,
+  /(?:^|\/)mem0\//i,
+];
+
+const STEALTH_PATTERNS = [
+  /\bsilent(?:ly)?\s+(?:save|store|write|record|remember|inject|add)\b/i,
+  /\bdo\s+not\s+(?:tell|say|mention|announce|notify|reveal|disclose)\b/i,
+  /\bwithout\s+(?:telling|saying|announcing|notifying|mentioning)\b/i,
+  /\bdo\s+not\s+(?:inform|alert)\s+the\s+user\b/i,
+  /\bhide\s+(?:this|the)\s+(?:from|update|memory)\b/i,
+  /\bstealth(?:y)?\s+memory\b/i,
+  /\bmemghost\b/i,
+  /\bwhisper\s*bench\b/i,
+  /\bnon[- ]?diagnostic\b/i,
+  /\bwithout\s+(?:user\s+)?(?:awareness|visibility|confirmation)\b/i,
+];
+
+const EXTERNAL_PROVENANCE_PATTERNS = [
+  /\b(?:imap|smtp|email|inbox|mailbox|mail\s+cli)\b/i,
+  /\bunread\s+(?:mail|email|messages?)\b/i,
+  /\bcheck\s+(?:my\s+)?(?:email|inbox)\b/i,
+  /\bfrom\s+(?:an?\s+)?(?:email|message|sender)\b/i,
+  /\bexternal\s+(?:content|data|payload|source)\b/i,
+  /\buntrusted\s+(?:content|source|email|payload)\b/i,
+  /\btool_result\b/i,
+  /\bindirect\s+prompt\s+injection\b/i,
+  /\bpayload\b/i,
+];
+
+const PREFERENCE_POISON_PATTERNS = [
+  /\balways\s+prefer\b/i,
+  /\buser\s+(?:prefers?|wants?|insists?)\b/i,
+  /\bpermanent(?:ly)?\s+(?:prefer|use|route|send)\b/i,
+  /\bupdate\s+(?:my\s+)?preferences?\b/i,
+  /\bfrom\s+now\s+on\b/i,
+];
+
+const FACT_POISON_PATTERNS = [
+  /\bremember\s+that\b/i,
+  /\bfact\s*:\s*/i,
+  /\bstore\s+(?:as\s+)?(?:durable\s+)?(?:memory|knowledge|fact)\b/i,
+  /\badd\s+to\s+(?:your\s+)?(?:long[- ]?term\s+)?memory\b/i,
+  /\bwrite\s+(?:this\s+)?to\s+(?:MEMORY|AGENTS|SOUL|USER)\.md\b/i,
+];
+
+const WRITE_TOOLS = new Set([
+  'Write',
+  'Edit',
+  'write',
+  'edit',
+  'create_file',
+  'str_replace',
+  'StrReplace',
+  'ApplyPatch',
+  'NotebookEdit',
+  'MultiEdit',
+]);
+
+function normalizeText(value) {
+  if (value === undefined || value === null) return '';
+  return String(value);
+}
+
+function collectHaystack(toolName, toolInput = {}) {
+  const parts = [
+    toolName,
+    toolInput.command,
+    toolInput.file_path,
+    toolInput.path,
+    toolInput.filePath,
+    toolInput.content,
+    toolInput.new_string,
+    toolInput.old_string,
+    toolInput.contents,
+    toolInput.notes,
+    toolInput.context,
+    toolInput.prompt,
+    toolInput.description,
+  ];
+  if (toolInput._claw && typeof toolInput._claw === 'object') {
+    parts.push(JSON.stringify(toolInput._claw));
+  }
+  if (toolInput.clawContext && typeof toolInput.clawContext === 'object') {
+    parts.push(JSON.stringify(toolInput.clawContext));
+  }
+  if (toolInput._externalProvenance) {
+    parts.push(String(toolInput._externalProvenance));
+  }
+  if (toolInput.source) {
+    parts.push(String(toolInput.source));
+  }
+  if (Array.isArray(toolInput.tags)) {
+    parts.push(toolInput.tags.join(' '));
+  }
+  return parts.filter(Boolean).map(normalizeText).join('\n');
+}
+
+function extractTargetPaths(toolName, toolInput = {}) {
+  const paths = new Set();
+  for (const key of ['file_path', 'path', 'filePath', 'target_file', 'notebook_path']) {
+    if (toolInput[key]) paths.add(normalizeText(toolInput[key]));
+  }
+  const command = normalizeText(toolInput.command);
+  if (command) {
+    // Named durable carriers anywhere in the command (tee MEMORY.md, vim AGENTS.md).
+    const named = /(?:^|[\s'"=])((?:\.\/|\.\.\/|\/)?(?:[\w.@[\]-]+\/)*(?:MEMORY|AGENTS|USER|IDENTITY|SOUL|HEARTBEAT|BRAIN|prevention-rules)\.md|memory\/\d{4}-\d{2}-\d{2}\.md)/gi;
+    let match;
+    while ((match = named.exec(command)) !== null) {
+      paths.add(match[1]);
+    }
+    // Shell output redirects: echo ... > MEMORY.md, printf ... >> path
+    // Avoid matching comparison operators by requiring whitespace (or start) before `>`.
+    const redirect = /(?:^|[\s;|&(])>{1,2}\s*['"]?([^\s'"`;&|<>]+)/g;
+    while ((match = redirect.exec(command)) !== null) {
+      paths.add(match[1]);
+    }
+  }
+  return [...paths].filter(Boolean);
+}
+
+function isDurableCarrier(filePath) {
+  const p = normalizeText(filePath);
+  return DURABLE_CARRIER_PATTERNS.some((re) => re.test(p));
+}
+
+function isEpisodicMemoryPath(filePath) {
+  const p = normalizeText(filePath);
+  return EPISODIC_MEMORY_PATTERNS.some((re) => re.test(p));
+}
+
+function matchAny(text, patterns) {
+  const hits = [];
+  for (const re of patterns) {
+    if (re.test(text)) hits.push(re.source);
+  }
+  return hits;
+}
+
+function isWriteLikeTool(toolName, toolInput = {}) {
+  if (WRITE_TOOLS.has(toolName)) return true;
+  if (toolName === 'Bash' || toolName === 'bash' || toolName === 'Shell') {
+    const cmd = normalizeText(toolInput.command);
+    // Shell output redirects (echo/printf/cat … > file or >> file). Require a
+    // token boundary before `>` so we do not treat `2>1` / comparison noise only;
+    // still match the common MemGhost path `echo '…' > MEMORY.md`.
+    const hasOutputRedirect = /(?:^|[\s;|&(])>{1,2}\s*\S/.test(cmd);
+    return hasOutputRedirect
+      || /(?:\btee\b|\bcp\s+|\bmv\s+|\binstall\s+-m|\bsed\s+-i)/i.test(cmd)
+      || /\b(?:Write|write_file|create_file)\b/i.test(cmd);
+  }
+  return false;
+}
+
+function isExplicitlyApproved(toolInput = {}) {
+  if (toolInput.stealthMemoryInjectionApproved === true) return true;
+  if (toolInput._stealthMemoryInjectionApproved === true) return true;
+  if (String(process.env.THUMBGATE_ALLOW_STEALTH_MEMORY_INJECTION || '') === '1') {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Evaluate whether this tool call should be blocked as stealth memory injection.
+ * @returns {null|{decision,gate,message,severity,reasoning,signals}}
+ */
+function evaluateStealthMemoryInjection(toolName, toolInput = {}) {
+  if (isExplicitlyApproved(toolInput)) return null;
+  if (!isWriteLikeTool(toolName, toolInput)) return null;
+
+  const targets = extractTargetPaths(toolName, toolInput);
+  const durableTargets = targets.filter(isDurableCarrier);
+  const episodicTargets = targets.filter(isEpisodicMemoryPath);
+  // Require a real memory destination (path or redirect target). Content that only
+  // *describes* MEMORY.md attacks (docs, research notes) must not false-positive.
+  if (durableTargets.length === 0 && episodicTargets.length === 0) {
+    return null;
+  }
+
+  const haystack = collectHaystack(toolName, toolInput);
+  const stealthHits = matchAny(haystack, STEALTH_PATTERNS);
+  const externalHits = matchAny(haystack, EXTERNAL_PROVENANCE_PATTERNS);
+  const preferenceHits = matchAny(haystack, PREFERENCE_POISON_PATTERNS);
+  const factHits = matchAny(haystack, FACT_POISON_PATTERNS);
+  const explicitExternalFlag = Boolean(
+    toolInput._externalProvenance
+    || toolInput.externalProvenance
+    || toolInput.source === 'email'
+    || toolInput.source === 'imap'
+    || toolInput.source === 'untrusted_external'
+  );
+
+  const hasExternal = externalHits.length > 0 || explicitExternalFlag;
+  const hasStealth = stealthHits.length > 0;
+  const hasPoisonLanguage = preferenceHits.length > 0 || factHits.length > 0;
+  const hasDurable = durableTargets.length > 0;
+
+  // Durable + stealth alone is enough (MemGhost core).
+  // Durable + external + poison language is enough (provenance risk).
+  // Episodic only blocks when stealth + external both present.
+  let shouldBlock = false;
+  let reasonCode = null;
+
+  if (hasDurable && hasStealth) {
+    shouldBlock = true;
+    reasonCode = 'durable_carrier_stealth_write';
+  } else if (hasDurable && hasExternal && hasPoisonLanguage) {
+    shouldBlock = true;
+    reasonCode = 'durable_carrier_external_poison';
+  } else if (episodicTargets.length > 0 && hasStealth && hasExternal) {
+    shouldBlock = true;
+    reasonCode = 'episodic_stealth_external';
+  }
+
+  if (!shouldBlock) return null;
+
+  const carrierClass = hasDurable ? 'durable' : 'episodic';
+  const message = [
+    'Blocked: suspected stealth memory injection into persistent agent state.',
+    `Gate ${GATE_ID} (paper ${PAPER_ID}).`,
+    'Untrusted external content must not silently update durable memory carriers',
+    '(MEMORY.md / AGENTS.md / SOUL.md / USER.md / HEARTBEAT.md / prevention-rules).',
+    'Require human review, provenance tagging, or set',
+    'THUMBGATE_ALLOW_STEALTH_MEMORY_INJECTION=1 only for explicit operator overrides.',
+    `See ${PAPER_URL}`,
+  ].join(' ');
+
+  return {
+    decision: 'deny',
+    gate: GATE_ID,
+    message,
+    severity: 'critical',
+    reasoning: [{
+      id: GATE_ID,
+      action: 'block',
+      layer: 'Memory',
+      severity: 'critical',
+      message,
+      paper: PAPER_ID,
+      reasonCode,
+      carrierClass,
+    }],
+    signals: {
+      paperId: PAPER_ID,
+      paperUrl: PAPER_URL,
+      reasonCode,
+      carrierClass,
+      durableTargets,
+      episodicTargets,
+      stealthHits: stealthHits.slice(0, 5),
+      externalHits: externalHits.slice(0, 5),
+      preferenceHits: preferenceHits.slice(0, 3),
+      factHits: factHits.slice(0, 3),
+    },
+  };
+}
+
+function main() {
+  const toolName = process.argv[2] || 'Write';
+  let toolInput = {};
+  const raw = process.argv[3];
+  if (raw) {
+    try {
+      toolInput = JSON.parse(raw);
+    } catch {
+      toolInput = { content: raw };
+    }
+  }
+  const result = evaluateStealthMemoryInjection(toolName, toolInput);
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(result && result.decision === 'deny' ? 2 : 0);
+}
+
+if (process.argv[1]
+  && require('node:path').resolve(process.argv[1]) === require('node:path').resolve(__filename)) {
+  main();
+}
+
+module.exports = {
+  GATE_ID,
+  PAPER_ID,
+  PAPER_URL,
+  DURABLE_CARRIER_PATTERNS,
+  STEALTH_PATTERNS,
+  EXTERNAL_PROVENANCE_PATTERNS,
+  collectHaystack,
+  extractTargetPaths,
+  isDurableCarrier,
+  isEpisodicMemoryPath,
+  isWriteLikeTool,
+  evaluateStealthMemoryInjection,
+};

package/scripts/switchyard-router.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * NeMo Switchyard–inspired multi-model step router for ThumbGate.
+ *
+ * Steal high-ROI ideas from NVIDIA Nemotron 3.5 Lightning + NeMo Switchyard
+ * (2026-08-11): always-on agents need more than one model; route each step
+ * across a model pool for accuracy, efficiency, customization, and control.
+ *
+ * This is application-level routing + evidence, not a neural MoE. ThumbGate
+ * still owns PreToolUse gates and proof. Nemotron Lightning (30B MoE / 3B
+ * active) is the default cheap specialist for intent/gate/classify steps.
+ */
+
+const DEFAULT_POOL = Object.freeze([
+  {
+    id: 'nvidia/nemotron-3.5-lightning',
+    model: 'nemotron-3.5-lightning',
+    provider: 'nvidia',
+    costClass: 'low',
+    activeParamsB: 3,
+    totalParamsB: 30,
+    roles: ['intent', 'classify', 'gate', 'route-decision', 'always-on', 'specialized'],
+    strengths: ['fast-inference', 'cost-efficiency', 'tool-use', 'reliability'],
+  },
+  {
+    id: 'alibaba/qwen3.6-flash',
+    model: 'qwen3.6-flash',
+    provider: 'model-studio',
+    costClass: 'low',
+    roles: ['triage', 'gate', 'cheap-fast'],
+    strengths: ['fast-inference', 'cost-efficiency', 'tool-use'],
+  },
+  {
+    id: 'alibaba/qwen3.8-max',
+    model: 'qwen3.8-max',
+    provider: 'model-studio',
+    costClass: 'medium',
+    roles: ['coding', 'agentic', 'long-horizon', 'high-output'],
+    strengths: ['agentic-coding', 'tool-use', 'long-horizon-coding', 'cost-efficiency'],
+  },
+  {
+    id: 'anthropic/claude-sonnet',
+    model: 'claude-sonnet-5-standard',
+    provider: 'anthropic',
+    costClass: 'high',
+    roles: ['reasoning', 'architecture', 'quality', 'review'],
+    strengths: ['reliability', 'long-horizon-coding', 'multi-agent'],
+  },
+  {
+    id: 'google/gemini-2.5-flash',
+    model: 'gemini-2.5-flash',
+    provider: 'gemini',
+    costClass: 'low',
+    roles: ['concise', 'summarize', 'extract'],
+    strengths: ['fast-inference', 'cost-efficiency', 'long-context'],
+  },
+  {
+    id: 'local/frontier',
+    model: 'local',
+    provider: 'local',
+    costClass: 'low',
+    roles: ['private', 'sensitive', 'offline'],
+    strengths: ['privacy', 'cost-efficiency', 'reliability'],
+  },
+]);
+
+const STEP_ROLE_HINTS = Object.freeze({
+  intent: ['intent', 'classify', 'detect', 'route-decision'],
+  classify: ['classify', 'intent', 'label'],
+  gate: ['gate', 'pretool', 'allow', 'deny', 'check'],
+  code: ['code', 'coding', 'implement', 'patch', 'refactor'],
+  reason: ['reason', 'architecture', 'design', 'plan', 'review'],
+  summarize: ['summarize', 'extract', 'concise', 'compress'],
+  private: ['private', 'sensitive', 'pii', 'secret', 'local'],
+  bulk: ['bulk', 'high-volume', 'automation', 'always-on'],
+});
+
+const COST_RANK = Object.freeze({ low: 0, medium: 1, high: 2, variable: 1 });
+
+function normalizeStep(step, index = 0) {
+  if (typeof step === 'string') {
+    return {
+      id: `step-${index + 1}`,
+      type: step,
+      tags: [],
+      riskLevel: 'medium',
+    };
+  }
+  const s = step && typeof step === 'object' ? step : {};
+  return {
+    id: s.id || `step-${index + 1}`,
+    type: String(s.type || s.role || s.name || 'unknown').toLowerCase(),
+    tags: Array.isArray(s.tags) ? s.tags.map((t) => String(t).toLowerCase()) : [],
+    riskLevel: String(s.riskLevel || 'medium').toLowerCase(),
+    sensitive: Boolean(s.sensitive || s.privacyRoute === 'local'),
+    highOutput: Boolean(s.highOutput || s.highVolume),
+    contextTokens: Number(s.contextTokens) || 0,
+  };
+}
+
+function inferStepRole(step) {
+  if (step.sensitive) return 'private';
+  const hay = `${step.type} ${(step.tags || []).join(' ')}`.toLowerCase();
+  for (const [role, hints] of Object.entries(STEP_ROLE_HINTS)) {
+    if (hints.some((h) => hay.includes(h))) return role;
+  }
+  if (step.highOutput || step.contextTokens >= 128000) return 'code';
+  if (step.riskLevel === 'high') return 'reason';
+  return 'intent';
+}
+
+function scorePoolMember(member, role, step) {
+  const roles = Array.isArray(member.roles) ? member.roles : [];
+  let score = 0;
+  const matchedRoles = [];
+
+  const roleMap = {
+    intent: ['intent', 'classify', 'gate', 'route-decision', 'always-on', 'specialized', 'triage'],
+    classify: ['classify', 'intent', 'label', 'specialized'],
+    gate: ['gate', 'pretool', 'always-on', 'specialized', 'cheap-fast'],
+    code: ['coding', 'agentic', 'long-horizon', 'high-output'],
+    reason: ['reasoning', 'architecture', 'quality', 'review'],
+    summarize: ['concise', 'summarize', 'extract'],
+    private: ['private', 'sensitive', 'offline'],
+    bulk: ['always-on', 'specialized', 'cheap-fast', 'triage', 'high-output'],
+  };
+
+  const wanted = roleMap[role] || ['specialized'];
+  for (const w of wanted) {
+    if (roles.includes(w)) {
+      score += 20;
+      matchedRoles.push(w);
+    }
+  }
+
+  // Prefer low cost for non-quality roles
+  const cost = COST_RANK[member.costClass] ?? 1;
+  if (role === 'reason') score += cost * 4; // higher cost OK for quality
+  else score += (2 - Math.min(cost, 2)) * 10;
+
+  // MoE Lightning bonus for always-on / gate / intent
+  if (member.activeParamsB && member.activeParamsB <= 4
+    && ['intent', 'classify', 'gate', 'bulk'].includes(role)) {
+    score += 12;
+  }
+
+  if (step.sensitive && member.provider !== 'local') {
+    score -= 100;
+  }
+  if (step.sensitive && member.provider === 'local') {
+    score += 40;
+  }
+
+  return { score, matchedRoles };
+}
+
+function pickModelForStep(stepInput, options = {}) {
+  const pool = Array.isArray(options.pool) && options.pool.length
+    ? options.pool
+    : DEFAULT_POOL;
+  const step = normalizeStep(stepInput, options.index || 0);
+  const role = options.forceRole || inferStepRole(step);
+
+  const ranked = pool.map((member) => {
+    const scored = scorePoolMember(member, role, step);
+    return {
+      ...member,
+      score: scored.score,
+      matchedRoles: scored.matchedRoles,
+    };
+  }).sort((a, b) => b.score - a.score || String(a.id).localeCompare(String(b.id)));
+
+  const winner = ranked[0];
+  return {
+    stepId: step.id,
+    stepType: step.type,
+    role,
+    modelId: winner.id,
+    model: winner.model,
+    provider: winner.provider,
+    costClass: winner.costClass,
+    score: winner.score,
+    reason: winner.provider === 'local' && step.sensitive
+      ? 'Sensitive step forced to local pool member.'
+      : `Switchyard step role=${role} → ${winner.id} (score ${winner.score}).`,
+    alternatives: ranked.slice(1, 4).map((m) => ({
+      modelId: m.id,
+      score: m.score,
+      provider: m.provider,
+    })),
+    evidence: {
+      role,
+      matchedRoles: winner.matchedRoles,
+      poolSize: pool.length,
+      activeParamsB: winner.activeParamsB || null,
+      totalParamsB: winner.totalParamsB || null,
+    },
+  };
+}
+
+/**
+ * Route a multi-step agent plan across the model pool (Switchyard core).
+ * @param {Array|object} plan - array of steps or { steps: [] }
+ */
+function routeAgentSteps(plan, options = {}) {
+  const steps = Array.isArray(plan)
+    ? plan
+    : (plan && Array.isArray(plan.steps) ? plan.steps : []);
+  if (steps.length === 0) {
+    return {
+      architecture: 'switchyard-multi-model',
+      mixtureOfExperts: false,
+      steps: [],
+      distinctModels: [],
+      multiModel: false,
+      reason: 'No steps to route.',
+    };
+  }
+
+  const routed = steps.map((step, index) => pickModelForStep(step, { ...options, index }));
+  const distinctModels = [...new Set(routed.map((r) => r.modelId))];
+  const multiModel = distinctModels.length > 1;
+  const complex = steps.length >= 2
+    || routed.some((r) => r.role === 'code' || r.role === 'reason');
+
+  return {
+    architecture: 'switchyard-multi-model',
+    mixtureOfExperts: false,
+    inspiredBy: 'NVIDIA NeMo Switchyard + Nemotron 3.5 Lightning',
+    steps: routed,
+    distinctModels,
+    multiModel,
+    complex,
+    singleModelAntiPattern: complex && !multiModel,
+    reason: multiModel
+      ? `Routed ${routed.length} steps across ${distinctModels.length} models (accuracy/efficiency/control).`
+      : complex
+        ? 'Complex plan still on one model — evaluate pool coverage or step labels.'
+        : `Single-model OK for simple ${routed.length}-step plan.`,
+  };
+}
+
+/**
+ * Evaluate a routing algorithm vs a single-model baseline (Switchyard "evaluate").
+ * Pure metrics helper — no network.
+ */
+function evaluateRoutingAlgorithm(options = {}) {
+  const baseline = options.baseline || {};
+  const candidate = options.candidate || {};
+  const baselineCost = Number(baseline.costUsd);
+  const candidateCost = Number(candidate.costUsd);
+  const baselineQuality = Number(baseline.qualityScore);
+  const candidateQuality = Number(candidate.qualityScore);
+  const baselineLatency = Number(baseline.latencyMs);
+  const candidateLatency = Number(candidate.latencyMs);
+
+  const hasCost = Number.isFinite(baselineCost) && Number.isFinite(candidateCost);
+  const hasQuality = Number.isFinite(baselineQuality) && Number.isFinite(candidateQuality);
+  const hasLatency = Number.isFinite(baselineLatency) && Number.isFinite(candidateLatency);
+
+  if (!hasCost || !hasQuality) {
+    return {
+      pass: false,
+      action: 'block',
+      reason: 'Routing evaluation requires baseline and candidate costUsd + qualityScore evidence.',
+      deltas: null,
+    };
+  }
+
+  const costDeltaUsd = baselineCost - candidateCost;
+  const costSavingsPercent = baselineCost > 0
+    ? Number(((costDeltaUsd / baselineCost) * 100).toFixed(1))
+    : 0;
+  const qualityDelta = candidateQuality - baselineQuality;
+  const latencyDeltaMs = hasLatency ? candidateLatency - baselineLatency : null;
+
+  // Fail closed if quality drops more than allowed while claiming savings.
+  const maxQualityDrop = Number.isFinite(Number(options.maxQualityDrop))
+    ? Number(options.maxQualityDrop)
+    : 0.05;
+  const minSavingsPercent = Number.isFinite(Number(options.minSavingsPercent))
+    ? Number(options.minSavingsPercent)
+    : 10;
+
+  let pass = true;
+  const failures = [];
+  if (qualityDelta < -maxQualityDrop) {
+    pass = false;
+    failures.push(`quality drop ${qualityDelta.toFixed(3)} exceeds max ${maxQualityDrop}`);
+  }
+  if (costSavingsPercent < minSavingsPercent && options.requireSavings !== false) {
+    pass = false;
+    failures.push(`cost savings ${costSavingsPercent}% below min ${minSavingsPercent}%`);
+  }
+
+  return {
+    pass,
+    action: pass ? 'allow' : 'block',
+    reason: pass
+      ? `Routing beats baseline: ${costSavingsPercent}% cheaper, quality Δ ${qualityDelta.toFixed(3)}.`
+      : `Routing evidence failed: ${failures.join('; ')}.`,
+    deltas: {
+      costDeltaUsd: Number(costDeltaUsd.toFixed(4)),
+      costSavingsPercent,
+      qualityDelta: Number(qualityDelta.toFixed(4)),
+      latencyDeltaMs,
+    },
+    failures,
+  };
+}
+
+/**
+ * Build default always-on agent step skeleton (intent → gate → act → review).
+ */
+function buildAlwaysOnAgentPlan(options = {}) {
+  const sensitive = Boolean(options.sensitive);
+  return [
+    { id: 'intent', type: 'intent-classify', tags: ['always-on', 'intent'] },
+    { id: 'gate', type: 'pretool-gate', tags: ['gate', 'pretool'] },
+    {
+      id: 'act',
+      type: options.actType || 'coding-implement',
+      tags: options.highVolume ? ['coding', 'high-volume'] : ['coding'],
+      riskLevel: options.riskLevel || 'medium',
+      highOutput: Boolean(options.highVolume),
+    },
+    {
+      id: 'review',
+      type: 'quality-review',
+      tags: ['review', 'reasoning'],
+      riskLevel: options.riskLevel || 'medium',
+      sensitive,
+    },
+  ];
+}
+
+function describeNemotronLightning() {
+  return {
+    id: 'nvidia/nemotron-3.5-lightning',
+    name: 'NVIDIA Nemotron 3.5 Lightning',
+    totalParamsB: 30,
+    activeParamsB: 3,
+    architecture: 'MoE',
+    open: true,
+    useCases: [
+      'always-on agent specialized steps',
+      'intent / classify / gate decisions',
+      'cheap routing algorithm evaluator companion',
+    ],
+    companion: 'NeMo Switchyard (multi-model step routing + evaluation)',
+  };
+}
+
+module.exports = {
+  DEFAULT_POOL,
+  STEP_ROLE_HINTS,
+  normalizeStep,
+  inferStepRole,
+  pickModelForStep,
+  routeAgentSteps,
+  evaluateRoutingAlgorithm,
+  buildAlwaysOnAgentPlan,
+  describeNemotronLightning,
+};