lynkr 9.9.1 → 9.11.0

package/src/routing/session-affinity.js

@@ -114,12 +114,18 @@ function getPin(sessionId) {
  * Accepts a routing decision plus session-scoped stats used by the re-pin
  * heuristics.
  *
+ * `hasToolHistory` is sticky-true: once set to true it stays true for the
+ * pin's lifetime — a follow-up refresh that didn't carry tool blocks (e.g.
+ * a plain-text turn between tool exchanges) must not clear the flag, or the
+ * Signal-2 side-channel check would flip open again.
+ *
  * @param {string} sessionId
  * @param {{provider:string, model?:string|null, tier?:string|null}} decision
- * @param {{messageCount?:number|null, promptTokensEst?:number|null}} [stats]
+ * @param {{messageCount?:number|null, promptTokensEst?:number|null, hasToolHistory?:boolean}} [stats]
  */
 function setPin(sessionId, decision, stats = {}) {
   if (!sessionId || !decision?.provider) return;
+  const prev = pins.get(sessionId);
   const pin = {
     provider: decision.provider,
     model: decision.model ?? null,
@@ -127,6 +133,7 @@ function setPin(sessionId, decision, stats = {}) {
     score: typeof decision.score === 'number' ? decision.score : null,
     messageCount: stats.messageCount ?? null,
     promptTokensEst: stats.promptTokensEst ?? null,
+    hasToolHistory: !!(stats.hasToolHistory || prev?.hasToolHistory),
     ts: Date.now(),
   };
   // Refresh insertion order so active sessions aren't evicted.
@@ -165,6 +172,64 @@ function shouldRepin(pin, payload) {
   return { repin: false, reason: null };
 }
 
+// ---------------------------------------------------------------------------
+// Cache-aware routing (Phase 1) — per-session prompt-cache state.
+//
+// After every upstream response we record how much of the session's prefix
+// is warm on the provider side: cache_read + cache_creation tokens together
+// describe the cached prefix as of that response. Anthropic-style explicit
+// caches refresh their TTL on every read, so `lastRequestAt + ttlMs` is a
+// live cache clock the switch-timing logic (Phase 2) can consult.
+// ---------------------------------------------------------------------------
+
+/**
+ * Record prompt-cache usage from an upstream response. No-ops when the
+ * response carried no cache signal (both counters zero/absent) so providers
+ * without cache reporting simply never accrue state.
+ *
+ * Overwrites unconditionally on signal: if the session switched models, the
+ * new response's numbers ARE the new model's cache state (caches are
+ * model-scoped — never carry a warm-prefix figure across a switch).
+ *
+ * @param {string} sessionId
+ * @param {{provider:string, model?:string|null, cacheReadTokens?:number, cacheCreationTokens?:number}} usage
+ */
+function recordCacheUsage(sessionId, usage) {
+  if (!sessionId || !usage?.provider) return;
+  const read = Number(usage.cacheReadTokens) || 0;
+  const created = Number(usage.cacheCreationTokens) || 0;
+  const warm = read + created;
+  if (warm <= 0) return; // no cache signal — state stays absent
+
+  let ttlMs = 5 * 60 * 1000;
+  try {
+    const { resolveCacheEconomics } = require("./cache-economics");
+    ttlMs = resolveCacheEconomics(usage.provider, usage.model ?? null).ttlMs;
+  } catch { /* keep default */ }
+
+  store.saveCacheState(sessionId, {
+    warmPrefixTokens: warm,
+    provider: usage.provider,
+    model: usage.model ?? null,
+    lastRequestAt: Date.now(),
+    ttlMs,
+  });
+}
+
+/**
+ * Load the session's cache state, annotated with liveness. Returns null when
+ * no state exists (provider reports no cache usage, or no response yet).
+ *
+ * @param {string} sessionId
+ * @returns {({warmPrefixTokens:number, provider:string, model:string|null, lastRequestAt:number, ttlMs:number, cold:boolean})|null}
+ */
+function getCacheState(sessionId) {
+  const state = store.loadCacheState(sessionId);
+  if (!state || typeof state.lastRequestAt !== "number") return null;
+  const ttl = typeof state.ttlMs === "number" ? state.ttlMs : 5 * 60 * 1000;
+  return { ...state, cold: Date.now() - state.lastRequestAt > ttl };
+}
+
 /** Test/maintenance helper — clear the in-memory Map only. */
 function _clear() {
   pins.clear();
@@ -216,6 +281,8 @@ module.exports = {
   setPin,
   removePin,
   shouldRepin,
+  recordCacheUsage,
+  getCacheState,
   // legacy
   getPinned,
   setPinned,

package/src/routing/side-channel-detector.js

@@ -0,0 +1,103 @@
+/**
+ * Side-Channel Detector — first-user-message fingerprint drift
+ *
+ * Complements the pin-based side-channel signals in router.js:
+ *   1. Message-count regression   → needs pin
+ *   2. Tool-history mismatch      → needs pin with hasToolHistory
+ *   3. First-message fingerprint  → THIS module — works before any pin exists
+ *
+ * Purpose: on a session's first request, cache a fingerprint of messages[0].
+ * On later requests within the TTL, if messages[0] no longer matches, the
+ * payload has been replayed by a background utility caller (Claude Code
+ * wraps the original user text in `<session>...</session>` for title-gen,
+ * substitutes recap prompts, etc.).
+ *
+ * Trade-off: if a background call fires BEFORE the first real user turn
+ * lands, its wrapper prompt becomes the anchor. That's rare in practice —
+ * observed order in real traffic is user turn first, background call after.
+ * If it does happen, the real user's next request will be mislabelled once,
+ * then the anchor will "settle" once ttl expires.
+ *
+ * @module routing/side-channel-detector
+ */
+
+const crypto = require('crypto');
+const logger = require('../logger');
+
+const TTL_MS = 30 * 60 * 1000;   // 30 min — matches an interactive Claude Code session
+const MAX_ENTRIES = 2000;         // LRU cap (same order of magnitude as session-affinity)
+
+/** @type {Map<string, {hash:string, ts:number}>} */
+const anchors = new Map();
+
+function _evictIfNeeded() {
+  if (anchors.size <= MAX_ENTRIES) return;
+  const oldest = anchors.keys().next().value;
+  if (oldest !== undefined) anchors.delete(oldest);
+}
+
+function _firstUserText(messages) {
+  if (!Array.isArray(messages)) return null;
+  for (const m of messages) {
+    if (m?.role !== 'user') continue;
+    if (typeof m.content === 'string') return m.content;
+    if (Array.isArray(m.content)) {
+      const t = m.content.filter(b => b?.type === 'text').map(b => b.text || '').join('');
+      if (t) return t;
+    }
+  }
+  return null;
+}
+
+function _hash(str) {
+  return crypto.createHash('sha1').update(str).digest('hex').slice(0, 16);
+}
+
+/**
+ * Check whether the payload's first user message drifts from the cached
+ * anchor for this session. Returns true only when we have an anchor AND
+ * it disagrees; returns false when no anchor exists yet (bootstrap case)
+ * and stores this payload's hash as the new anchor.
+ *
+ * @param {string|null} sessionId
+ * @param {Array} messages
+ * @returns {boolean} true if drift detected (caller should treat as side channel)
+ */
+function check(sessionId, messages) {
+  if (!sessionId) return false;
+  const text = _firstUserText(messages);
+  if (!text) return false;
+  const hash = _hash(text);
+  const now = Date.now();
+
+  const cached = anchors.get(sessionId);
+  if (cached) {
+    // Refresh insertion order for LRU
+    anchors.delete(sessionId);
+    if (now - cached.ts > TTL_MS) {
+      // Expired — reset the anchor, no drift claim.
+      anchors.set(sessionId, { hash, ts: now });
+      _evictIfNeeded();
+      return false;
+    }
+    anchors.set(sessionId, cached);
+    if (cached.hash !== hash) {
+      logger.debug({ sessionId, cachedHash: cached.hash, newHash: hash },
+        '[SideChannel] First-message fingerprint drift');
+      return true;
+    }
+    return false;
+  }
+
+  // Bootstrap — first sighting of this session, store and pass.
+  anchors.set(sessionId, { hash, ts: now });
+  _evictIfNeeded();
+  return false;
+}
+
+/** Test/maintenance helper — clear the in-memory anchors. */
+function _clear() {
+  anchors.clear();
+}
+
+module.exports = { check, _clear };

package/src/routing/telemetry.js

@@ -165,6 +165,11 @@ function init() {
       ["candidates", "TEXT"],
       ["pinned", "INTEGER DEFAULT 0"],
       ["switch_reason", "TEXT"],
+      // Phase 6 (cache-aware routing) — per-decision cache economics
+      // receipt: {decision, reason, warmPrefixTokens, breakEvenTurns,
+      // projectedSwitchCostUsd, projectedStaySavingsUsd,
+      // expectedRemainingTurns} as JSON.
+      ["cache_decision", "TEXT"],
     ];
     for (const [col, type] of additiveCols) {
       if (!existingCols.has(col)) {
@@ -226,7 +231,8 @@ function record(data) {
           latency_ms, status_code, error_type, cost_usd, tool_calls_made,
           retry_count, circuit_breaker_state, quality_score, tokens_per_second,
           cost_efficiency, request_text, response_text,
-          base_tier, escalation_source, propensity, candidates, pinned, switch_reason
+          base_tier, escalation_source, propensity, candidates, pinned, switch_reason,
+          cache_decision
         ) VALUES (
           @request_id, @session_id, @timestamp, @complexity_score, @tier,
           @agentic_type, @tool_count, @input_tokens, @message_count, @request_type,
@@ -234,7 +240,8 @@ function record(data) {
           @latency_ms, @status_code, @error_type, @cost_usd, @tool_calls_made,
           @retry_count, @circuit_breaker_state, @quality_score, @tokens_per_second,
           @cost_efficiency, @request_text, @response_text,
-          @base_tier, @escalation_source, @propensity, @candidates, @pinned, @switch_reason
+          @base_tier, @escalation_source, @propensity, @candidates, @pinned, @switch_reason,
+          @cache_decision
         )`
       );
       if (!insert) return;
@@ -280,6 +287,11 @@ function record(data) {
         candidates: candidatesJson,
         pinned: data.pinned ? 1 : 0,
         switch_reason: data.switch_reason ?? null,
+        cache_decision: data.cache_decision == null
+          ? null
+          : (typeof data.cache_decision === "string"
+            ? data.cache_decision
+            : JSON.stringify(data.cache_decision)),
       });
     } catch (err) {
       logger.debug({ err: err.message }, "Telemetry record failed");
@@ -791,6 +803,129 @@ function _resetForTests() {
   _testDbDisabled = false;
 }
 
+// Cache-aware routing (Phase 6) — "cache dollars saved / burned by routing".
+//
+// Every gated switch/hold decision carries a receipt. Aggregating them
+// answers the public question "does model routing break prefix caching?"
+// with a dollar figure:
+//   - a HOLD avoided a switch whose one-time cache write exceeded its
+//     projected per-turn savings over the expected horizon
+//     (saved = switchOnce − savings × remainingTurns)
+//   - a SWITCH cleared break-even; its projected net gain is
+//     (savings × remainingTurns − switchOnce)
+/**
+ * @param {Object} [opts]
+ * @param {number} [opts.since] - default: last 7 days.
+ * @returns {{decisions:number, holds:number, switches:number,
+ *   dollarsSavedByHolds:number, dollarsSavedBySwitches:number,
+ *   totalDollarsSaved:number, byReason:Object}|null}
+ */
+function getCacheEconomics(opts = {}) {
+  if (!init()) return null;
+  const since = opts.since ?? Date.now() - 7 * 24 * 60 * 60 * 1000;
+  try {
+    const rows = db
+      .prepare(
+        `SELECT cache_decision FROM routing_telemetry
+         WHERE timestamp > ? AND cache_decision IS NOT NULL
+         LIMIT 20000`
+      )
+      .all(since);
+
+    const out = {
+      decisions: 0,
+      holds: 0,
+      switches: 0,
+      dollarsSavedByHolds: 0,
+      dollarsSavedBySwitches: 0,
+      totalDollarsSaved: 0,
+      byReason: {},
+    };
+
+    for (const row of rows) {
+      let d;
+      try {
+        d = JSON.parse(row.cache_decision);
+      } catch {
+        continue;
+      }
+      if (!d || typeof d !== "object") continue;
+      out.decisions++;
+      out.byReason[d.reason ?? "unknown"] = (out.byReason[d.reason ?? "unknown"] ?? 0) + 1;
+
+      const savings = typeof d.projectedStaySavingsUsd === "number" ? d.projectedStaySavingsUsd : null;
+      const once = typeof d.projectedSwitchCostUsd === "number" ? d.projectedSwitchCostUsd : null;
+      const horizon = typeof d.expectedRemainingTurns === "number" ? d.expectedRemainingTurns : null;
+
+      if (d.decision === "hold") {
+        out.holds++;
+        if (savings != null && once != null && horizon != null) {
+          out.dollarsSavedByHolds += Math.max(0, once - savings * horizon);
+        }
+      } else if (d.decision === "switch") {
+        out.switches++;
+        if (savings != null && once != null && horizon != null) {
+          out.dollarsSavedBySwitches += Math.max(0, savings * horizon - once);
+        }
+      }
+    }
+
+    out.totalDollarsSaved = out.dollarsSavedByHolds + out.dollarsSavedBySwitches;
+    return out;
+  } catch (err) {
+    logger.debug({ err: err.message }, "Telemetry getCacheEconomics failed");
+    return null;
+  }
+}
+
+// Cache-aware routing (Phase 3) — expected remaining turns.
+//
+// Conditional median: given a session has already reached `currentTurns`
+// messages, how many MORE messages do comparable sessions run? Uses the max
+// message_count each recent session reached. Conditional (len > current)
+// rather than a global median because long sessions systematically outlive
+// the average — exactly the sessions whose warm prefixes are worth pricing.
+const _remainingTurnsCache = new Map();
+const REMAINING_TURNS_CACHE_TTL_MS = 60 * 1000;
+const REMAINING_TURNS_MIN_SESSIONS = 20;
+
+/**
+ * @param {number} currentTurns - message_count the session has reached now.
+ * @returns {number|null} median remaining messages, or null when telemetry
+ *   is too sparse (< 20 comparable sessions in the last 7 days).
+ */
+function getExpectedRemainingTurns(currentTurns = 0) {
+  if (!init()) return null;
+  const bucket = Math.max(0, Math.floor((Number(currentTurns) || 0) / 5) * 5);
+  const cached = _remainingTurnsCache.get(bucket);
+  if (cached && Date.now() - cached.ts < REMAINING_TURNS_CACHE_TTL_MS) {
+    return cached.value;
+  }
+  try {
+    const since = Date.now() - 7 * 24 * 60 * 60 * 1000;
+    const rows = db
+      .prepare(
+        `SELECT MAX(message_count) AS len
+         FROM routing_telemetry
+         WHERE timestamp > ? AND session_id IS NOT NULL AND message_count IS NOT NULL
+         GROUP BY session_id
+         HAVING len > ?
+         LIMIT 5000`
+      )
+      .all(since, bucket);
+    let value = null;
+    if (rows.length >= REMAINING_TURNS_MIN_SESSIONS) {
+      const remaining = rows.map((r) => r.len - bucket).sort((a, b) => a - b);
+      value = remaining[Math.floor(remaining.length / 2)];
+    }
+    _remainingTurnsCache.set(bucket, { value, ts: Date.now() });
+    return value;
+  } catch (err) {
+    logger.debug({ err: err.message }, "Telemetry getExpectedRemainingTurns failed");
+    return null;
+  }
+}
+
 module.exports = {
   record,
   query,
@@ -799,6 +934,8 @@ module.exports = {
   getRoutingAccuracy,
   getEscalationStats,
   getQualityByTierAndType,
+  getExpectedRemainingTurns,
+  getCacheEconomics,
   recordSavings,
   getSavingsSummary,
   cleanup,

package/src/routing/verifier.js

@@ -204,6 +204,28 @@ function contentScore(userText, answerText, responseBody) {
   return Math.max(0, Math.min(100, score));
 }
 
+// ---------------------------------------------------------------------------
+// Caveman detection
+// ---------------------------------------------------------------------------
+
+// context/caveman.js appends a brevity instruction tagged with this literal
+// marker whenever CAVEMAN is enabled. Presence in the outbound system prompt
+// is a reliable, config-independent signal that the model was told to be
+// terse — so the length-based effort penalty in contentScore() is a false
+// negative here (short answer = compliant, not lazy) and must not fire.
+const CAVEMAN_MARKER = "[brevity]";
+
+function _cavemanActive(payload) {
+  const s = payload?.system;
+  if (typeof s === "string") return s.includes(CAVEMAN_MARKER);
+  if (Array.isArray(s)) {
+    for (const b of s) {
+      if (typeof b?.text === "string" && b.text.includes(CAVEMAN_MARKER)) return true;
+    }
+  }
+  return false;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -240,11 +262,26 @@ function verify({ payload, responseBody } = {}) {
     ].filter(Boolean);
 
     const score = contentScore(userText, answerText, responseBody);
-    if (reasons.length === 0 && score < CONTENT_SCORE_FAIL_THRESHOLD) {
+    const cavemanActive = _cavemanActive(payload);
+    // When caveman brevity is active the model was explicitly told to be
+    // terse; a short answer is compliant, not lazy, so the length-driven
+    // low-score check would misfire and thrash the cascade. Structural
+    // checks above (language drift, degeneration, truncation, malformed
+    // tools, echo) still run — those catch real failures regardless.
+    if (
+      reasons.length === 0 &&
+      score < CONTENT_SCORE_FAIL_THRESHOLD &&
+      !cavemanActive
+    ) {
       reasons.push(`low-content-score (${score} < ${CONTENT_SCORE_FAIL_THRESHOLD})`);
     }
 
-    return { verdict: reasons.length ? 'fail' : 'pass', score, reasons };
+    return {
+      verdict: reasons.length ? 'fail' : 'pass',
+      score,
+      reasons,
+      cavemanActive,
+    };
   } catch (err) {
     // Fail-open: a broken verifier must never block serving.
     logger.debug({ err: err.message }, '[Verifier] error — failing open');
@@ -263,5 +300,7 @@ module.exports = {
     checkMalformedToolCalls,
     checkEmptyOrEcho,
     contentScore,
+    _cavemanActive,
+    CAVEMAN_MARKER,
   },
 };

package/src/server.js

@@ -1,5 +1,4 @@
 const express = require("express");
-const compression = require("compression");
 const config = require("./config");
 const loggingMiddleware = require("./api/middleware/logging");
 const router = require("./api/router");
@@ -18,52 +17,13 @@ const { getCircuitBreakerRegistry } = require("./clients/circuit-breaker");
 const metrics = require("./metrics");
 const logger = require("./logger");
 const { initialiseMcp } = require("./mcp");
-const { registerStubTools } = require("./tools/stubs");
-const { registerWorkspaceTools } = require("./tools/workspace");
-const { registerExecutionTools } = require("./tools/execution");
-const { registerWebTools } = require("./tools/web");
-const { registerIndexerTools } = require("./tools/indexer");
-const { registerEditTools } = require("./tools/edits");
-const { registerGitTools } = require("./tools/git");
-const { registerTaskTools } = require("./tools/tasks");
-const { registerTestTools } = require("./tools/tests");
-const { registerMcpTools } = require("./tools/mcp");
-const { registerAgentTaskTool } = require("./tools/agent-task");
-const { registerDecomposeTool } = require("./tools/decompose");
 const { initConfigWatcher, getConfigWatcher } = require("./config/watcher");
-const { initializeHeadroom, shutdownHeadroom, getHeadroomManager } = require("./headroom");
+const { initializeHeadroom, shutdownHeadroom } = require("./headroom");
 const { getWorkerPool, isWorkerPoolReady } = require("./workers/pool");
-const lazyLoader = require("./tools/lazy-loader");
-const { setLazyLoader } = require("./tools");
 const { waitForOllama } = require("./clients/ollama-startup");
 
 initialiseMcp();
 
-setLazyLoader(lazyLoader);
-
-const LAZY_TOOLS_ENABLED = process.env.LAZY_TOOLS_ENABLED !== "false";
-
-if (LAZY_TOOLS_ENABLED) {
-  // Only load core tools at startup (stubs, workspace, execution)
-  lazyLoader.loadCoreTools();
-  logger.info({ mode: "lazy" }, "Lazy tool loading enabled - other tools will load on demand");
-} else {
-  // Backwards compatibility: load all tools at startup
-  registerStubTools();
-  registerWorkspaceTools();
-  registerExecutionTools();
-  registerWebTools();
-  registerIndexerTools();
-  registerEditTools();
-  registerGitTools();
-  registerTaskTools();
-  registerTestTools();
-  registerMcpTools();
-  registerAgentTaskTool();
-  registerDecomposeTool();
-  logger.info({ mode: "eager" }, "All tools loaded at startup");
-}
-
 function createApp() {
   const app = express();
   const path = require('path');
@@ -171,13 +131,6 @@ function createApp() {
     res.json({ enabled: true, ...cache.getStats() });
   });
 
-  app.get("/metrics/lazy-tools", (req, res) => {
-    res.json({
-      enabled: LAZY_TOOLS_ENABLED,
-      ...lazyLoader.getLoaderStats(),
-    });
-  });
-
   app.use(router);
 
   app.use('/dashboard', require('./dashboard/router'));
@@ -242,10 +195,44 @@ async function start() {
     }
   }
 
-  const server = app.listen(config.port, () => {
+  const server = app.listen(config.port, (err) => {
+    // Express 5 invokes this callback on bind errors too (it wires the
+    // callback to the server 'error' event) — without the guard, a failed
+    // bind prints "listening" right before the EADDRINUSE failure.
+    if (err) return;
     console.log(`Claude→Databricks proxy listening on http://localhost:${config.port}`);
   });
 
+  // Surface bind failures to the caller. Without this, EADDRINUSE from a
+  // stale instance is swallowed, and `lynkr wrap`'s readiness probe then
+  // gets answered by the OLD server still holding the port — the new
+  // session silently runs against stale code.
+  await new Promise((resolve, reject) => {
+    server.once("listening", resolve);
+    server.once("error", reject);
+  });
+
+  // TencentDB-Agent-Memory sidecar — non-blocking (first start pulls two
+  // Docker images). Launched after listen so the proxy is usable immediately;
+  // the memory stack's LLM calls route back through Lynkr, which is why
+  // Lynkr must already be accepting requests when the containers come up.
+  if (config.tencentdbMemory?.enabled) {
+    (async () => {
+      try {
+        const tencentdbLauncher = require("./memory/tencentdb-launcher");
+        const result = await tencentdbLauncher.ensureRunning();
+        if (result.started) {
+          logger.info(result.endpoints, "[tdai] TencentDB Agent Memory stack ready");
+          console.log(`TencentDB Agent Memory ready — Panel UI: ${result.endpoints.panel}`);
+        } else {
+          logger.debug({ reason: result.reason }, "[tdai] Sidecar not started");
+        }
+      } catch (err) {
+        logger.warn({ err }, "[tdai] TencentDB memory sidecar failed to start — continuing without it");
+      }
+    })();
+  }
+
   // Classifier bootstrap check — non-blocking, log-only.
   // Detects ollama + confirms the classifier model is pulled. Never auto-
   // installs (that's `lynkr init`'s job); warns and lets scoring fall back

package/src/tools/code-graph.js

@@ -313,9 +313,10 @@ async function getBlastRadius(filePaths, options = {}) {
   if (cached) return cached;
 
   // Query neighbors for each file to estimate blast radius
+  const depth = String(config.codeGraph?.maxDepth ?? 2);
   const result = await execGraph(
     "query",
-    ["get_neighbors", "--files", ...filePaths, "--depth", "2", "--json"],
+    ["get_neighbors", "--files", ...filePaths, "--depth", depth, "--json"],
     ws
   );
   if (!result) return null;
@@ -364,11 +365,11 @@ async function getBlastRadius(filePaths, options = {}) {
  * Uses Graphify's BFS-based query to find related nodes.
  *
  * @param {string[]} filePaths — seed file paths
- * @param {number} [maxFiles=20] — maximum files to return
+ * @param {number} [maxFiles] — maximum files to return (default from config.codeGraph.maxFiles)
  * @param {CodeGraphOptions} [options]
  * @returns {Promise<string[]|null>}
  */
-async function getRelevantContext(filePaths, maxFiles = 20, options = {}) {
+async function getRelevantContext(filePaths, maxFiles = config.codeGraph?.maxFiles ?? 5, options = {}) {
   if (!Array.isArray(filePaths) || filePaths.length === 0) return null;
 
   const ws = resolveWorkspace({ ...options, filePaths });
@@ -419,8 +420,9 @@ async function getComplexitySignals(filePaths, options = {}) {
   if (cached) return cached;
 
   // Run parallel queries: neighbors (blast radius) + god_nodes + graph_stats
+  const signalDepth = String(config.codeGraph?.maxDepth ?? 2);
   const [neighborsResult, godNodesResult, statsResult] = await Promise.all([
-    execGraph("query", ["get_neighbors", "--files", ...filePaths, "--depth", "2", "--json"], ws),
+    execGraph("query", ["get_neighbors", "--files", ...filePaths, "--depth", signalDepth, "--json"], ws),
     execGraph("query", ["god_nodes", "--json"], ws),
     execGraph("query", ["graph_stats", "--json"], ws),
   ]);