@duckmind/dm-darwin-x64 0.66.4 → 0.66.6

package/extensions/dm-lens/dist/mcp/server.js

@@ -0,0 +1,1239 @@
+import { setProjectTrustState } from "../clients/project-trust.js";
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { finalizeToolResult, finalizeToolResultWithDelivery, renderToolText as toolText, stripResultDetails } from "../tools/render-compact.js";
+import { AstGrepClient } from "../clients/ast-grep-client.js";
+import { CacheManager } from "../clients/cache-manager.js";
+import { getDegradationSummary, incrementDegradationCount, recordDegradationOnce, renderDegradationLines } from "../clients/degradation-ledger.js";
+import { acknowledgeTurnEnd, analyzeFile, analyzeFileFresh, canRebuildDmLens, createMcpHost, createWarmIpcLineReader, createWarmIpcRequestQueue, diagnosticStats, effectiveConfig, ensureLspConfig, generatedSkipNotice, ipcPathForCwd, isEffectiveFileViewError, lspStatus, moduleReport, projectReport, projectScan, readEnclosing, readSymbol, readTurnEndStatus, recentLatency, renderCompactModuleReport, renderCompactProjectReport, renderLspBrokenStatusLines, resolveRebuildScript, resourceFootprint, runRebuild, runSessionStart, runTurnEnd, runTurnEndForIpc, scanTruncationNotice, summarizeScan, symbolSearch, treeSitterRuntimeStatus, WARM_TURN_END_SCHEMA_VERSION } from "../clients/lens-engine.js";
+import { createAstGrepReplaceTool } from "../tools/ast-grep-replace.js";
+import { astGrepDumpCompatibilityResult, createAstGrepSearchTool } from "../tools/ast-grep-search.js";
+import { createLensDiagnosticsTool } from "../tools/lens-diagnostics.js";
+import { peekMcpSessionRuntime } from "../clients/mcp/session.js";
+import { loadDmLensGlobalConfig } from "../clients/lens-config.js";
+import { loadDmLensProjectConfig } from "../clients/project-lens-config.js";
+import { resolveLensToolEnabled, toolRegistryEntryForMcp } from "../clients/tool-config.js";
+import { endSituationalToolTelemetry, observeSituationalToolCall, startSituationalToolTelemetrySession } from "../clients/situational-tool-telemetry.js";
+import { logExtension, flushExtensionLog } from "../clients/extension-log.js";
+import { createLspNavigationTool } from "../tools/lsp-navigation.js";
+import { shouldInitializeSessionRoot } from "../clients/lsp/session-roots.js";
+import { findIgnoredArguments, ignoredArgumentsStructured, refusalResult, withIgnoredArguments } from "./tool-arguments.js";
+import { computeBuildStamp, STALE_SERVED_BY_FRESH, STALE_WARN_ONLY, StalenessGate, stalenessCheckEnabled } from "./build-staleness.js";
+console.log = (...args) => {
+  console.error(...args);
+};
+const SERVER_NAME = "dm-lens-mcp";
+const SERVER_VERSION = "0.1.0";
+const FALLBACK_PROTOCOL_VERSION = "2025-06-18";
+function resolveDefaultCwd() {
+  const fromArg = process.argv.find((arg) => arg.startsWith("--cwd="))?.slice("--cwd=".length);
+  return fromArg ?? process.env.DM_LENS_MCP_CWD ?? process.cwd();
+}
+const DEFAULT_CWD = path.resolve(resolveDefaultCwd());
+const lspReadyCwds = new Set;
+const SERVER_FILE = fileURLToPath(import.meta.url);
+const SERVER_DIR = path.dirname(SERVER_FILE);
+const WORKER_PATH = path.join(SERVER_DIR, "worker.js");
+const REBUILD_SCRIPT = resolveRebuildScript(SERVER_FILE);
+const STALENESS_STAT_PATH = process.env.DM_LENS_MCP_STALENESS_STAT_PATH ?? SERVER_FILE;
+const BUILD_STAMP = computeBuildStamp(STALENESS_STAT_PATH);
+const stalenessIntervalOverride = (() => {
+  const raw = process.env.DM_LENS_MCP_STALENESS_INTERVAL_MS;
+  if (raw === undefined)
+    return;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+})();
+const STALENESS_GATE = new StalenessGate(BUILD_STAMP, {
+  checkIntervalMs: stalenessIntervalOverride
+});
+function isWarmBuildStale() {
+  if (!stalenessCheckEnabled())
+    return false;
+  return STALENESS_GATE.isStale();
+}
+function findRepoRoot(start) {
+  let dir = start;
+  for (let depth = 0;depth < 6; depth++) {
+    const pkgPath = path.join(dir, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        if (pkg.name === "dm-lens")
+          return dir;
+      } catch {}
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return path.resolve(start, "..", "..");
+}
+const REPO_ROOT = process.env.DM_LENS_MCP_REPO_ROOT ? path.resolve(process.env.DM_LENS_MCP_REPO_ROOT) : findRepoRoot(SERVER_DIR);
+async function ensureReady(cwd) {
+  const normalized = path.resolve(cwd);
+  if (!shouldInitializeSessionRoot(normalized, lspReadyCwds)) {
+    return;
+  }
+  try {
+    await ensureLspConfig(normalized);
+  } catch (err) {
+    console.error(`[dm-lens-mcp] initLSPConfig failed for ${normalized}: ${err}`);
+  }
+  lspReadyCwds.add(normalized);
+}
+let autoSessionState = {
+  attempted: false,
+  succeeded: false,
+  firedAt: null,
+  error: null
+};
+let autoSessionInFlight = null;
+function maybeAutoSessionStart() {
+  if (process.env.DM_LENS_MCP_AUTO_SESSION !== "1")
+    return;
+  if (autoSessionInFlight || autoSessionState.succeeded)
+    return;
+  autoSessionState = {
+    attempted: true,
+    succeeded: false,
+    firedAt: new Date().toISOString(),
+    error: null
+  };
+  autoSessionInFlight = ensureReady(DEFAULT_CWD).then(() => runSessionStart(DEFAULT_CWD)).then(() => {
+    autoSessionState = { ...autoSessionState, succeeded: true };
+    console.error("[dm-lens-mcp] auto session_start complete");
+  }).catch((err) => {
+    autoSessionState = { ...autoSessionState, error: String(err) };
+    console.error(`[dm-lens-mcp] auto session_start failed: ${err}`);
+  }).finally(() => {
+    autoSessionInFlight = null;
+  });
+}
+function getAutoSessionStatus() {
+  if (process.env.DM_LENS_MCP_AUTO_SESSION !== "1")
+    return null;
+  return { ...autoSessionState };
+}
+const IPC_PATH = ipcPathForCwd(DEFAULT_CWD);
+function rejectForeignTurnCwd(route, cwd) {
+  const message = `${route} cwd outside this server's workspace: ${path.resolve(cwd)} not within ${DEFAULT_CWD}`;
+  console.error(`[dm-lens-mcp] rejected ${message}`);
+  return message;
+}
+function isWithinServerWorkspace(cwd) {
+  const target = path.resolve(cwd);
+  const rel = path.relative(DEFAULT_CWD, target);
+  return !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+function startIpcServer() {
+  if (process.platform !== "win32") {
+    try {
+      fs.unlinkSync(IPC_PATH);
+    } catch {}
+  }
+  const requestQueue = createWarmIpcRequestQueue();
+  const ipc = net.createServer((socket) => {
+    socket.setEncoding("utf8");
+    socket.on("data", createWarmIpcLineReader((line) => {
+      requestQueue.enqueue(async () => {
+        try {
+          if (isWarmBuildStale()) {
+            console.error("[dm-lens-mcp] warm request: build stale, replying with an error");
+            socket.end(`${JSON.stringify({ error: "warm build stale" })}
+`);
+            return;
+          }
+          const parsed = JSON.parse(line);
+          if (parsed.route === "turn-end-ack") {
+            if (parsed.version !== WARM_TURN_END_SCHEMA_VERSION || typeof parsed.deliveryId !== "string") {
+              socket.end(`${JSON.stringify({ error: `turn-end ack schema ${parsed.version} != ${WARM_TURN_END_SCHEMA_VERSION}` })}
+`);
+              return;
+            }
+            const turnCwd = parsed.cwd ?? DEFAULT_CWD;
+            if (!isWithinServerWorkspace(turnCwd)) {
+              socket.end(`${JSON.stringify({ error: rejectForeignTurnCwd("turn-end-ack", turnCwd) })}
+`);
+              return;
+            }
+            const acknowledged = acknowledgeTurnEnd(turnCwd, parsed.deliveryId);
+            socket.end(`${JSON.stringify({
+              result: {
+                route: "turn-end-ack",
+                version: WARM_TURN_END_SCHEMA_VERSION,
+                acknowledged
+              }
+            })}
+`);
+            return;
+          }
+          if (parsed.route === "turn-end") {
+            if (parsed.version !== WARM_TURN_END_SCHEMA_VERSION) {
+              socket.end(`${JSON.stringify({ error: `turn-end schema ${parsed.version} != ${WARM_TURN_END_SCHEMA_VERSION}` })}
+`);
+              return;
+            }
+            const turnCwd = parsed.cwd ?? DEFAULT_CWD;
+            if (!isWithinServerWorkspace(turnCwd)) {
+              socket.end(`${JSON.stringify({ error: rejectForeignTurnCwd("turn-end", turnCwd) })}
+`);
+              return;
+            }
+            if (socket.destroyed) {
+              console.error(`[dm-lens-mcp] warm turn-end: client gone before the pass started (${turnCwd})`);
+              return;
+            }
+            console.error(`[dm-lens-mcp] warm turn-end: ${turnCwd}`);
+            await ensureReady(turnCwd);
+            const delivery = await runTurnEndForIpc(turnCwd);
+            const result = {
+              route: "turn-end",
+              version: WARM_TURN_END_SCHEMA_VERSION,
+              turnEnd: delivery.outcome.turnEnd,
+              tests: delivery.outcome.tests,
+              deliveryId: delivery.deliveryId
+            };
+            socket.end(`${JSON.stringify({ result })}
+`);
+            return;
+          }
+          const req = parsed;
+          console.error(`[dm-lens-mcp] warm analyze: ${req.file}`);
+          const result = await analyzeFile(req.file, req.cwd, {
+            registerTurnState: true,
+            updateGraph: true
+          });
+          socket.end(`${JSON.stringify({ result })}
+`);
+        } catch (err) {
+          socket.end(`${JSON.stringify({ error: String(err) })}
+`);
+        }
+      });
+    }, {
+      label: "mcp-warm-server",
+      onOverflow: () => socket.end(`${JSON.stringify({ error: "warm request line exceeded the framing limit" })}
+`)
+    }));
+    socket.on("error", () => {});
+  });
+  ipc.on("error", (err) => {
+    console.error(`[dm-lens-mcp] IPC listener unavailable: ${err}`);
+  });
+  ipc.listen(IPC_PATH, () => {
+    console.error(`[dm-lens-mcp] warm side-channel listening at ${IPC_PATH}`);
+  });
+  const cleanup = () => {
+    try {
+      ipc.close();
+    } catch {}
+    if (process.platform !== "win32") {
+      try {
+        fs.unlinkSync(IPC_PATH);
+      } catch {}
+    }
+  };
+  process.on("exit", cleanup);
+}
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}
+`);
+}
+function sendResult(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+function sendError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+const GRAPH_STALENESS_THRESHOLD_MS = 10 * 60000;
+function formatRelativeAge(ms) {
+  if (ms < 60000)
+    return `${Math.round(ms / 1000)}s ago`;
+  if (ms < 60 * 60000)
+    return `${Math.round(ms / 60000)}m ago`;
+  if (ms < 24 * 60 * 60000)
+    return `${Math.round(ms / (60 * 60000))}h ago`;
+  return `${Math.round(ms / (24 * 60 * 60000))}d ago`;
+}
+function graphStalenessNote(builtAtIso, label) {
+  if (!builtAtIso)
+    return;
+  const builtAtMs = Date.parse(builtAtIso);
+  if (!Number.isFinite(builtAtMs))
+    return;
+  const ageMs = Date.now() - builtAtMs;
+  if (ageMs < GRAPH_STALENESS_THRESHOLD_MS)
+    return;
+  return `${label} last updated ${formatRelativeAge(ageMs)}; run dmlens_analyze ` + "on recently-changed files, dmlens_session_start, or dmlens_rebuild to refresh it.";
+}
+setProjectTrustState("trusted");
+logExtension({
+  subsystem: "project-trust",
+  level: "debug",
+  message: "mcp: workspace trust belongs to the MCP client; pi trust not consulted"
+});
+const cacheManager = new CacheManager;
+const isLensGuardEnabled = () => Boolean(createMcpHost(undefined, DEFAULT_CWD).getFlag("lens-guard"));
+const lensDiagnosticsTool = createLensDiagnosticsTool(cacheManager, () => DEFAULT_CWD, undefined, undefined, undefined, undefined, () => peekMcpSessionRuntime(), () => isLensGuardEnabled());
+const astGrepClient = new AstGrepClient;
+const astGrepSearchTool = createAstGrepSearchTool(astGrepClient);
+const astGrepReplaceTool = createAstGrepReplaceTool(astGrepClient);
+const lspNavigationTool = createLspNavigationTool((name, cwd) => createMcpHost(undefined, cwd ?? DEFAULT_CWD).getFlag(name));
+function schemaWithCwd(parameters) {
+  const p = parameters;
+  return {
+    type: "object",
+    properties: {
+      ...p.properties,
+      cwd: {
+        type: "string",
+        description: "Project root (defaults to the server workspace)."
+      }
+    },
+    ...p.required ? { required: p.required } : {}
+  };
+}
+const ALL_TOOLS = [
+  {
+    name: "dmlens_analyze",
+    description: "Run dm-lens's per-edit dispatch pipeline on one file. Example: analyze `src/app.ts` after an edit.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file: {
+          type: "string",
+          description: "Path to the file to analyze (absolute, or relative to cwd)."
+        },
+        cwd: {
+          type: "string",
+          description: "Project root. Defaults to the server's workspace."
+        },
+        mode: {
+          type: "string",
+          enum: ["warm", "fresh"],
+          description: "warm (default): run in this server process — fast, warm LSP, but reflects the code the server was started with. fresh: fork a worker that loads the freshly-built code from disk — slower, but reflects the latest commit (the honest review loop; pair with dmlens_rebuild)."
+        },
+        flags: {
+          type: "object",
+          description: 'Optional dm-lens flag overrides for this run, e.g. {"no-lsp": true} to bench the non-LSP path.'
+        }
+      },
+      required: ["file"]
+    }
+  },
+  {
+    name: "dmlens_diagnostics",
+    description: lensDiagnosticsTool.description,
+    inputSchema: schemaWithCwd(lensDiagnosticsTool.parameters)
+  },
+  {
+    name: "dmlens_latency",
+    description: "Return recent dispatch latency reports. Example: limit results to 5.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "number",
+          description: "Max reports to return (default 5)."
+        },
+        file: {
+          type: "string",
+          description: "Only reports whose path ends with this."
+        }
+      }
+    }
+  },
+  {
+    name: "dmlens_rebuild",
+    description: "Rebuild dm-lens so later fresh analyses use the latest commit. Example: rebuild after changing a tool.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "dmlens_project_scan",
+    description: "Scan project files for structural and quality diagnostics. Example: cap the scan with `maxFiles: 20`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: { type: "string" },
+        maxFiles: { type: "number", description: "Cap files scanned." },
+        includeGenerated: {
+          type: "boolean",
+          description: "Scan WITHOUT the generated/artifact NAME-heuristic filter " + "(lockfiles, gen.ts-style names, generated/ dirs, …). Default " + "false. Use when a scan's 'excluded by generated-name " + "heuristics' notice suggests a real file was skipped."
+        }
+      }
+    }
+  },
+  {
+    name: "dmlens_symbol_search",
+    description: "Find relevant files by ranked identifier search. On a cold cache, project_report and symbol_search return available: false with a retry hint and start a non-blocking background build; module_report degrades to outline-only with cache freshness explicit. Example: search `authenticate user` before dmlens_module_report.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Identifier-ish query, e.g. 'authenticate user'. Mix in composable prefix filters: lang:<kind> (e.g. lang:jsts, lang:python — kinds from file-kinds.ts), file:<substr> (path substring), ext:<ext> (e.g. ext:ts or ext:.ts), each optionally negated with a leading '-' (-file:test). Filters apply before ranking; e.g. 'lang:jsts file:clients/ -file:test rank'. Unknown prefixes/kinds error with the supported list."
+        },
+        cwd: { type: "string" },
+        limit: {
+          type: "number",
+          description: "Max files to return (default 20)."
+        },
+        paths: {
+          type: "array",
+          items: { type: "string" },
+          description: "Glob array scoping hits to matching files — same shape/semantics as dmlens_ast_grep_search's `paths` (a bare directory/file entry scopes its whole subtree). Filters before ranking, so scores within the scoped set are unaffected."
+        },
+        lang: {
+          type: "string",
+          description: "Restrict hits to one language, using the same identifiers as dmlens_ast_grep_search's `lang` param (e.g. 'typescript', 'python', 'go')."
+        }
+      },
+      required: ["query"]
+    }
+  },
+  {
+    name: "dmlens_module_report",
+    description: "Return a navigable source-module outline with references and read handles. An outline shows shape, not bodies, and does not satisfy read-before-edit; `read_symbol` and `read_enclosing` return body text and record read coverage. On a cold cache, project_report and symbol_search return available: false with a retry hint and start a non-blocking background build; module_report degrades to outline-only with cache freshness explicit. Example: use dmlens_module_report on `src/app.ts` before dmlens_read_symbol.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file: {
+          type: "string",
+          description: "File to report on (absolute or relative to cwd)."
+        },
+        cwd: { type: "string" },
+        maxRefsPerSymbol: {
+          type: "number",
+          description: "Cap who-uses-this entries per symbol (default 10)."
+        },
+        focus: {
+          type: "string",
+          description: "Optional task hint used only to rank recommendedReads (does not expand scope or trigger scans)."
+        },
+        view: {
+          type: "string",
+          enum: ["summary", "default", "compact"],
+          description: "Payload tier. summary returns top-level entries/recommendedReads with heavy callback/usedBy/blast-radius payloads omitted. compact (cheapest) returns a line-oriented TEXT rendering of the full report instead of JSON."
+        },
+        blastRadius: {
+          type: "boolean",
+          description: "Include the cross-file blast radius: transitive dependents aggregated to ranked file reads. Read-only over the cached graph (omitted when cold)."
+        },
+        blastRadiusDepth: {
+          type: "number",
+          description: "Max hops for the blast-radius walk (default 3). Only used with blastRadius."
+        },
+        callGraph: {
+          type: "boolean",
+          description: "Include bounded derived callers/callees from the cached FunctionCallGraph; cold or stale cache state is explicit."
+        },
+        maxCallGraphEntries: {
+          type: "number",
+          description: "Per-direction cap for call-graph relations (default 20)."
+        }
+      },
+      required: ["file"]
+    }
+  },
+  {
+    name: "dmlens_project_report",
+    description: "Orient in a project from its review graph. On a cold cache, project_report and symbol_search return available: false with a retry hint and start a non-blocking background build; module_report degrades to outline-only with cache freshness explicit. Example: use dmlens_project_report before choosing a file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: { type: "string" },
+        limit: {
+          type: "number",
+          description: "Scales every ranked section's cap (default 10) — a single knob for all sections."
+        },
+        focus: {
+          type: "string",
+          description: "Optional task hint used only to re-rank sections toward relevant subsystems (does not expand scope or trigger scans)."
+        },
+        view: {
+          type: "string",
+          enum: ["default", "compact"],
+          description: "Payload tier. compact (cheapest) returns a line-oriented TEXT rendering instead of JSON. Default returns JSON."
+        }
+      }
+    }
+  },
+  {
+    name: "dmlens_read_symbol",
+    description: "Return one symbol's verbatim source. An outline shows shape, not bodies, and does not satisfy read-before-edit; `read_symbol` and `read_enclosing` return body text and record read coverage. Example: use dmlens_read_symbol after dmlens_module_report identifies `parseConfig`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file: { type: "string", description: "File containing the symbol." },
+        symbol: {
+          type: "string",
+          description: "Exact symbol name to read, or a dotted `Class.method` to disambiguate a member."
+        },
+        kind: {
+          type: "string",
+          description: "Optional kind filter (e.g. function, interface, class) to disambiguate when multiple same-file symbols share the requested name."
+        },
+        cwd: { type: "string" }
+      },
+      required: ["file", "symbol"]
+    }
+  },
+  {
+    name: "dmlens_read_enclosing",
+    description: "Return the smallest symbol or callback enclosing a line. An outline shows shape, not bodies, and does not satisfy read-before-edit; `read_symbol` and `read_enclosing` return body text and record read coverage. Example: use dmlens_read_enclosing after a diagnostic points to line 42.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file: {
+          type: "string",
+          description: "Absolute or workspace-relative path to the source file."
+        },
+        line: {
+          type: "number",
+          description: "1-based line number inside the desired symbol/callback."
+        },
+        cwd: { type: "string" },
+        kinds: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional kind filter, e.g. function, method, callback, class."
+        },
+        maxLines: {
+          type: "number",
+          description: "Optional maximum body size to return. Oversized matches obey onOversize."
+        },
+        onOversize: {
+          type: "string",
+          enum: ["error", "slice", "outline"],
+          description: "Behavior when the enclosing body exceeds maxLines. error (default) returns metadata only; slice returns a bounded partial read around line; outline returns nested symbols/callbacks with read handles."
+        },
+        aroundLine: {
+          type: "number",
+          description: "Maximum lines for onOversize=slice; defaults to maxLines, then 80."
+        }
+      },
+      required: ["file", "line"]
+    }
+  },
+  {
+    name: "dmlens_health",
+    description: "Return dm-lens runtime health for this server. Example: call it after a slow analysis.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "dmlens_effective_config",
+    description: "Explain resolved configuration and provenance. Response is redacted by construction: it contains no environment values, no command arguments beyond the binary, and home-relative paths; a tier-denied LSP decision cannot be lifted by a nearer config. Example: pass `file` to explain one selection.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: { type: "string" },
+        file: {
+          type: "string",
+          description: "Path to explain: adds the resolved language plus the per-server and " + "per-runner selection decisions for it. Must resolve inside `cwd` " + "(a sibling package in the same monorepo does not count) — a file " + "outside it is rejected with the `cwd` it was measured against; " + "re-query with `cwd` set to that file's own workspace instead."
+        }
+      }
+    }
+  },
+  {
+    name: "dmlens_session_start",
+    description: "Initialize dm-lens for a workspace. Example: run once before reviewing a project.",
+    inputSchema: {
+      type: "object",
+      properties: { cwd: { type: "string" } }
+    }
+  },
+  {
+    name: "dmlens_turn_end",
+    description: "Summarize checks for files changed this turn. Example: pass `files` for an unanalysed file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: { type: "string" },
+        files: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional extra files to include (auto-registered ones are already picked up)."
+        }
+      }
+    }
+  },
+  {
+    name: "dmlens_session_end",
+    description: "End the MCP connection's telemetry session and write its bounded situational-tool telemetry line. This is terminal for the connection.",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  {
+    name: "dmlens_ast_grep_search",
+    description: "Search code by AST structure rather than text. Example: find calls with `console.log($MSG)`.",
+    inputSchema: schemaWithCwd(astGrepSearchTool.parameters)
+  },
+  {
+    name: "dmlens_ast_grep_replace",
+    description: "Find and rewrite code by AST structure; preview by default. Example: set `apply: false` to inspect a diff.",
+    inputSchema: schemaWithCwd(astGrepReplaceTool.parameters)
+  },
+  {
+    name: "dmlens_lsp_navigation",
+    description: 'Navigate source with language-server operations. Example: use `{operation: "references", path: "src/app.ts", line: 12}`.',
+    inputSchema: schemaWithCwd(lspNavigationTool.parameters)
+  }
+];
+const TOOLS = canRebuildDmLens(REPO_ROOT) ? ALL_TOOLS : ALL_TOOLS.filter((tool) => tool.name !== "dmlens_rebuild");
+function enabledToolsForCwd(cwd) {
+  const global = loadDmLensGlobalConfig();
+  const project = loadDmLensProjectConfig(cwd);
+  return TOOLS.filter((tool) => {
+    const entry = toolRegistryEntryForMcp(tool.name);
+    return entry !== undefined && resolveLensToolEnabled(entry.name, global, project.raw);
+  });
+}
+function formatAnalyze(result, cwd, mode, servedBy) {
+  const lspNote = result.lsp ? ` · lsp ${result.lsp.diagnosticCount} (${result.lsp.status}${result.lsp.failureKind ? `: ${result.lsp.failureKind}` : ""}, ${result.lsp.durationMs}ms)` : "";
+  const summary = `${path.relative(cwd, result.filePath) || result.filePath} [${mode}] — ` + `${result.counts.blockers} blocking, ${result.counts.warnings} warning(s), ` + `${result.counts.advisories} advisory(ies), ` + `${result.counts.diagnostics} total` + (result.latency ? ` · ${result.latency.totalDurationMs}ms` : "") + lspNote + (result.counts.fixed > 0 ? ` · ${result.counts.fixed} auto-fixed` : "") + (servedBy ? `
+
+servedBy: ${servedBy}` : "");
+  return toolText(summary, servedBy ? { ...result, servedBy } : result);
+}
+function healthConfigLine(provenance) {
+  if (!provenance)
+    return "Config: unavailable (resolution failed)";
+  const tiers = Object.entries(provenance.tiers).filter(([, count]) => count > 0).map(([tier, count]) => `${tier} ${count}`).join(" · ");
+  const codes = Object.entries(provenance.codes).map(([code, count]) => `${code}×${count}`).join(", ");
+  const notices = codes.length > 0 ? ` · notices ${codes}` : "";
+  const documents = `${provenance.documents} file(s)`;
+  return `Config: ${documents} · ${tiers} leaf/leaves${notices}`;
+}
+function effectiveServerLine(server) {
+  const mark = server.selected ? "✓" : "✗";
+  const decided = server.decidedBy;
+  if (!decided)
+    return `  ${mark} ${server.id} — ${server.reason}`;
+  const file = decided.file === undefined ? "" : ` ${decided.file}`;
+  const source = `${decided.tier}${file} → ${decided.key}`;
+  return `  ${mark} ${server.id} — ${server.reason} (${source})`;
+}
+function effectiveFileHeading(file) {
+  const language = file.language === undefined ? "" : ` — ${file.language}`;
+  const kind = file.kind === undefined ? "" : ` (kind ${file.kind})`;
+  return `File: ${file.path}${language}${kind}`;
+}
+function effectiveDocumentLine(document) {
+  const legacy = document.legacy ? " (legacy location — scheduled for removal)" : "";
+  return `  ${document.tier}: ${document.file}${legacy}`;
+}
+async function callTool(name, args) {
+  if (name === "dmlens_lsp_diagnostics") {
+    recordDegradationOnce({
+      kind: "lsp-diagnostics-compatibility",
+      subject: "lsp_diagnostics",
+      reason: "retired tool name redirected to dmlens_diagnostics source=lsp"
+    });
+    name = "dmlens_diagnostics";
+    args = {
+      ...args,
+      source: "lsp",
+      scope: "paths"
+    };
+  }
+  if (name === "dmlens_ast_grep_dump") {
+    recordDegradationOnce({
+      kind: "ast-grep-dump-compatibility",
+      subject: "ast_grep_dump",
+      reason: "retired tool name redirected to ast_grep_search dump mode"
+    });
+    return astGrepDumpCompatibilityResult(args, "mcp");
+  }
+  if (name === "dmlens_analyze") {
+    const file = args.file;
+    if (typeof file !== "string" || file.length === 0) {
+      return {
+        ...toolText("dmlens_analyze requires a 'file' string."),
+        isError: true
+      };
+    }
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    const requestedMode = args.mode === "fresh" ? "fresh" : "warm";
+    const flags = args.flags && typeof args.flags === "object" ? args.flags : undefined;
+    const forcedFresh = requestedMode === "warm" && isWarmBuildStale();
+    const mode = requestedMode === "fresh" || forcedFresh ? "fresh" : "warm";
+    if (mode === "fresh") {
+      const outcome = await analyzeFileFresh(WORKER_PATH, file, cwd, { flags });
+      if (outcome.error || !outcome.result) {
+        return {
+          ...toolText(`fresh analyze failed: ${outcome.error ?? "no result"}`),
+          isError: true
+        };
+      }
+      return formatAnalyze(outcome.result, cwd, "fresh", forcedFresh ? STALE_SERVED_BY_FRESH : undefined);
+    }
+    await ensureReady(cwd);
+    const result = await analyzeFile(file, cwd, {
+      flags,
+      registerTurnState: true,
+      updateGraph: true
+    });
+    return formatAnalyze(result, cwd, "warm");
+  }
+  if (name === "dmlens_rebuild") {
+    const outcome = await runRebuild(REPO_ROOT, REBUILD_SCRIPT);
+    if (!outcome.packageManager) {
+      return {
+        ...toolText(outcome.output, {
+          ok: false,
+          script: outcome.script,
+          repoRoot: REPO_ROOT
+        }),
+        isError: true
+      };
+    }
+    const runCmd = `${outcome.packageManager} run ${outcome.script}`;
+    const headline = outcome.ok ? `✓ rebuild succeeded (${runCmd}, ${outcome.durationMs}ms). Fresh analyses now reflect the latest build.` : `✗ rebuild FAILED (${runCmd}, ${outcome.durationMs}ms).`;
+    return {
+      ...toolText(outcome.ok ? headline : `${headline}
+
+${outcome.output}`, {
+        ok: outcome.ok,
+        script: outcome.script,
+        packageManager: outcome.packageManager,
+        durationMs: outcome.durationMs,
+        repoRoot: REPO_ROOT
+      }),
+      isError: !outcome.ok
+    };
+  }
+  if (name === "dmlens_project_scan") {
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    await ensureReady(cwd);
+    const maxFiles = typeof args.maxFiles === "number" && Number.isFinite(args.maxFiles) ? Math.max(1, Math.floor(args.maxFiles)) : undefined;
+    const includeGenerated = args.includeGenerated === true;
+    const snapshot = await projectScan(cwd, maxFiles, includeGenerated);
+    if (snapshot.unsafeRoot) {
+      return toolText(`Refused to scan: the working directory (${cwd}) resolves at or above the home directory, so a project scan would walk every unrelated tree under it. Run dmlens_project_scan from inside a project directory. This is NOT a clean result — nothing was scanned.`, { filesScanned: 0, unsafeRoot: true, cwd }, true);
+    }
+    const { deduped, byRule, byFile } = summarizeScan(snapshot.diagnostics);
+    const topRules = Object.entries(byRule).sort((a, b) => b[1] - a[1]);
+    const topFiles = Object.entries(byFile).sort((a, b) => b[1] - a[1]).slice(0, 15).map(([file, count]) => ({ file: path.relative(cwd, file), count }));
+    const summaryLines = [
+      `Scanned ${snapshot.filesScanned} file(s) [${snapshot.runners.join(", ")}] → ` + `${deduped.length} unique diagnostic(s)` + (snapshot.diagnostics.length !== deduped.length ? ` (${snapshot.diagnostics.length} raw, ${snapshot.diagnostics.length - deduped.length} duplicate)` : ""),
+      ...topRules.slice(0, 12).map(([rule, count]) => `  ${count}× ${rule}`)
+    ];
+    const truncationNotice = scanTruncationNotice(snapshot);
+    if (truncationNotice)
+      summaryLines.push(truncationNotice);
+    const skipNotice = generatedSkipNotice(snapshot, "mcp");
+    if (skipNotice)
+      summaryLines.push(skipNotice);
+    return toolText(summaryLines.join(`
+`), {
+      filesScanned: snapshot.filesScanned,
+      runners: snapshot.runners,
+      uniqueDiagnostics: deduped.length,
+      rawDiagnostics: snapshot.diagnostics.length,
+      byRule,
+      topFiles,
+      sample: deduped.slice(0, 40),
+      ...snapshot.scanTruncated ? { scanTruncated: true } : {},
+      ...snapshot.treeSitterStatus ? { treeSitterStatus: snapshot.treeSitterStatus } : {},
+      ...snapshot.generatedFileSkips ? { generatedFileSkips: snapshot.generatedFileSkips } : {},
+      ...snapshot.generatedNameOnlySkips ? { generatedNameOnlySkips: snapshot.generatedNameOnlySkips } : {},
+      ...snapshot.generatedDirSkips ? { generatedDirSkips: snapshot.generatedDirSkips } : {}
+    });
+  }
+  if (name === "dmlens_symbol_search") {
+    const query = typeof args.query === "string" ? args.query : "";
+    if (!query.trim())
+      return toolText("Provide a non-empty `query`.");
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    const limit = typeof args.limit === "number" && Number.isFinite(args.limit) ? Math.max(1, Math.floor(args.limit)) : 20;
+    const paths = Array.isArray(args.paths) ? args.paths.filter((p) => typeof p === "string") : undefined;
+    const lang = typeof args.lang === "string" ? args.lang : undefined;
+    const { available, results, hint, unavailableReason, coverage, snapshotGeneratedAt } = await symbolSearch(query, cwd, limit, { paths, lang });
+    if (!available) {
+      return toolText(hint ?? "No word index for this workspace yet — run dmlens_session_start first.", { available: false, query, hint, unavailableReason }, true);
+    }
+    const stalenessNote = graphStalenessNote(snapshotGeneratedAt, "Project snapshot");
+    if (results.length === 0) {
+      return toolText(`No files matched "${query}".` + (coverage ? `
+Index covers ${coverage.files} files${coverage.truncated ? " (capped — results may be incomplete)" : ""}.` : "") + (stalenessNote ? `
+
+${stalenessNote}` : ""), {
+        available: true,
+        query,
+        results: [],
+        coverage,
+        ...stalenessNote ? { staleness: stalenessNote } : {}
+      }, true);
+    }
+    const lines = [
+      `Top ${results.length} file(s) for "${query}":`,
+      ...results.map((result, i) => `  ${i + 1}. ${path.relative(cwd, result.file)} ` + `(score ${result.score.toFixed(2)}, ${result.hits} hit(s), ` + `line ${result.startLine})`),
+      ...stalenessNote ? ["", stalenessNote] : [],
+      ...coverage ? [
+        `Index covers ${coverage.files} files${coverage.truncated ? " (capped — results may be incomplete)" : ""}.`
+      ] : []
+    ];
+    return toolText(lines.join(`
+`), {
+      query,
+      coverage,
+      results: results.map((result) => {
+        const relFile = path.relative(cwd, result.file);
+        return {
+          file: relFile,
+          score: result.score,
+          hits: result.hits,
+          startLine: result.startLine,
+          endLine: result.endLine,
+          ...result.annotations ? { annotations: result.annotations } : {},
+          suggestedNext: { tool: "dmlens_module_report", path: relFile }
+        };
+      }),
+      ...stalenessNote ? { staleness: stalenessNote } : {}
+    }, true);
+  }
+  if (name === "dmlens_module_report") {
+    const file = typeof args.file === "string" ? args.file : "";
+    if (!file.trim())
+      return { ...toolText("Provide a `file`."), isError: true };
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    const maxRefsPerSymbol = typeof args.maxRefsPerSymbol === "number" && Number.isFinite(args.maxRefsPerSymbol) ? Math.max(1, Math.floor(args.maxRefsPerSymbol)) : undefined;
+    const blastRadius = args.blastRadius === true;
+    const blastRadiusDepth = typeof args.blastRadiusDepth === "number" && Number.isFinite(args.blastRadiusDepth) ? Math.max(1, Math.floor(args.blastRadiusDepth)) : undefined;
+    const callGraph = args.callGraph === true;
+    const maxCallGraphEntries = typeof args.maxCallGraphEntries === "number" && Number.isFinite(args.maxCallGraphEntries) ? Math.max(1, Math.floor(args.maxCallGraphEntries)) : undefined;
+    const view = args.view === "summary" || args.view === "compact" ? args.view : undefined;
+    const focus = typeof args.focus === "string" ? args.focus : undefined;
+    const report = await moduleReport(file, cwd, {
+      maxRefsPerSymbol,
+      blastRadius,
+      blastRadiusDepth,
+      callGraph,
+      maxCallGraphEntries,
+      view,
+      focus
+    });
+    if (!report.available) {
+      return {
+        ...toolText(`No module report for ${path.relative(cwd, path.resolve(cwd, file))} — not a symbol-bearing file, or unreadable.`, report, true),
+        isError: true
+      };
+    }
+    const graphStaleness = graphStalenessNote(report.graphBuiltAt, "Review graph");
+    const summary = `${path.relative(cwd, report.path) || report.path} [${report.staleness}] — ` + `${report.summary.symbols} symbol(s), ${report.summary.exports} exported, ` + `${report.api.length} in public API` + (graphStaleness ? `
+
+${graphStaleness}` : "");
+    if (view === "compact") {
+      const compactText = renderCompactModuleReport(report);
+      return {
+        content: [
+          {
+            type: "text",
+            text: graphStaleness ? `${compactText}
+
+${graphStaleness}` : compactText
+          }
+        ]
+      };
+    }
+    return toolText(summary, graphStaleness ? { ...report, graphStalenessNote: graphStaleness } : report, true);
+  }
+  if (name === "dmlens_project_report") {
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    const limit = typeof args.limit === "number" && Number.isFinite(args.limit) ? Math.max(1, Math.floor(args.limit)) : undefined;
+    const focus = typeof args.focus === "string" ? args.focus : undefined;
+    const view = args.view === "compact" ? "compact" : undefined;
+    const report = await projectReport(cwd, { limit, focus, view });
+    if (!report.available) {
+      return {
+        ...toolText(report.hint ?? "No review graph cached for this workspace yet.", report),
+        isError: true
+      };
+    }
+    const graphStaleness = report.trust ? graphStalenessNote(report.trust.graphBuiltAt, "Review graph") : undefined;
+    if (view === "compact") {
+      const compactText = renderCompactProjectReport(report);
+      return {
+        content: [
+          {
+            type: "text",
+            text: graphStaleness ? `${compactText}
+
+${graphStaleness}` : compactText
+          }
+        ]
+      };
+    }
+    const summary = `Project report — ${report.hubs?.length ?? 0} hub(s), ` + `${report.entryPoints?.length ?? 0} entry point(s), ` + `${report.riskHotspots?.length ?? 0} risk hotspot(s)` + (graphStaleness ? `
+
+${graphStaleness}` : "");
+    return toolText(summary, graphStaleness ? { ...report, graphStalenessNote: graphStaleness } : report, true);
+  }
+  if (name === "dmlens_read_symbol") {
+    const file = typeof args.file === "string" ? args.file : "";
+    const symbol = typeof args.symbol === "string" ? args.symbol : "";
+    if (!file.trim() || !symbol.trim()) {
+      return { ...toolText("Provide `file` and `symbol`."), isError: true };
+    }
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    const kind = typeof args.kind === "string" ? args.kind : undefined;
+    const result = await readSymbol(file, symbol, cwd, { kind });
+    if (!result.found) {
+      const suggestionSuffix = result.suggestions?.length ? ` Did you mean: ${result.suggestions.join(", ")}?` : " Use dmlens_module_report to list symbols.";
+      return {
+        ...toolText(`Symbol "${symbol}" not found in ${path.basename(file)}.${suggestionSuffix}`, {
+          found: false,
+          ...result.suggestions ? { suggestions: result.suggestions } : {}
+        }),
+        isError: true
+      };
+    }
+    const sigSuffix = result.signature ? `  ${result.signature}` : "";
+    const ambiguityNote = result.ambiguous ? ` (${result.ambiguous.count} matches — returned the ${result.kind}; pass \`kind\` to disambiguate: ${result.ambiguous.kinds.join(", ")})` : "";
+    const header = `${result.kind} ${result.name}${ambiguityNote}${sigSuffix}  ${path.relative(cwd, result.path)}:${result.startLine}-${result.endLine}`;
+    return {
+      content: [
+        {
+          type: "text",
+          text: `${header}
+
+${result.source ?? ""}`
+        }
+      ]
+    };
+  }
+  if (name === "dmlens_read_enclosing") {
+    const file = typeof args.file === "string" ? args.file : "";
+    const line = typeof args.line === "number" ? args.line : Number.NaN;
+    if (!file.trim() || !Number.isFinite(line)) {
+      return {
+        ...toolText("Provide `file` and a numeric `line`."),
+        isError: true
+      };
+    }
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    const kinds = Array.isArray(args.kinds) ? args.kinds.filter((k) => typeof k === "string") : undefined;
+    const maxLines = typeof args.maxLines === "number" && Number.isFinite(args.maxLines) ? Math.max(1, Math.floor(args.maxLines)) : undefined;
+    const onOversize = args.onOversize === "error" || args.onOversize === "slice" || args.onOversize === "outline" ? args.onOversize : undefined;
+    const aroundLine = typeof args.aroundLine === "number" && Number.isFinite(args.aroundLine) ? Math.max(1, Math.floor(args.aroundLine)) : undefined;
+    const result = await readEnclosing(file, line, cwd, {
+      kinds,
+      maxLines,
+      onOversize,
+      aroundLine
+    });
+    if (!result.found) {
+      const warningSuffix = result.warnings?.length ? ` Warnings: ${result.warnings.join("; ")}` : "";
+      const outlineSuffix = result.outline?.length ? `
+
+Nested outline:
+${JSON.stringify(result.outline)}` : "";
+      const text = result.error ? `Could not read enclosing range in ${path.basename(file)}:${result.line}: ${result.error}${warningSuffix}${outlineSuffix}` : `No enclosing symbol/callback found in ${path.basename(file)}:${result.line}.${warningSuffix}`;
+      return {
+        ...toolText(text, { found: false, line: result.line }),
+        isError: true
+      };
+    }
+    const range = result.partial ? `${result.startLine}-${result.endLine} (partial of ${result.enclosingStartLine}-${result.enclosingEndLine})` : `${result.startLine}-${result.endLine}`;
+    const header = `${result.kind} ${result.name}  ${path.relative(cwd, result.path)}:${range}`;
+    return {
+      content: [
+        {
+          type: "text",
+          text: `${header}
+
+${result.source ?? ""}`
+        }
+      ]
+    };
+  }
+  if (name === "dmlens_health") {
+    const { aliveClients, servers, brokenServers } = lspStatus();
+    const last = recentLatency(1)[0];
+    const stats = diagnosticStats();
+    const autoSession = getAutoSessionStatus();
+    const treeSitter = treeSitterRuntimeStatus();
+    const degradations = getDegradationSummary();
+    const turnEnd = readTurnEndStatus(DEFAULT_CWD) ?? null;
+    const configProvenance = await effectiveConfig({ cwd: DEFAULT_CWD }).then((view) => ({
+      documents: view.documents.length,
+      tiers: view.provenanceCounts,
+      codes: view.recordCounts
+    })).catch(() => null);
+    const footprint = await resourceFootprint().catch(() => null);
+    const lines = [
+      treeSitter.wasmAborted ? `Tree-sitter: DEGRADED — WASM runtime aborted${treeSitter.abortedAt ? ` at ${treeSitter.abortedAt}` : ""}; restart this server to recover` : "Tree-sitter: available",
+      `LSP: ${aliveClients} alive client(s)`,
+      ...servers.flatMap((server) => [
+        `  ${server.connected ? "✓" : "✗"} ${server.serverId} (${server.root})`,
+        ...server.pullFailureHistory.slice(-1).map((failure) => `    ⚠ diagnostics pull failed: ${failure.method}${failure.code !== undefined ? ` (${failure.code})` : ""} — ${failure.message.length > 200 ? `${failure.message.slice(0, 200)}…` : failure.message}`)
+      ]),
+      ...renderLspBrokenStatusLines(brokenServers),
+      ...renderDegradationLines(degradations),
+      last ? `Last dispatch: ${path.basename(last.filePath)} — ${last.totalDurationMs}ms, ${last.totalDiagnostics} diagnostic(s)` : "Last dispatch: none yet",
+      `Diagnostics this session: ${stats.totalShown} shown · ${stats.totalAutoFixed} auto-fixed · ${stats.totalUnresolved} unresolved`,
+      autoSession ? `Auto session_start: ${autoSession.succeeded ? "succeeded" : autoSession.error ? "FAILED" : autoSession.attempted ? "in progress" : "not yet attempted"}${autoSession.firedAt ? ` (fired ${autoSession.firedAt})` : ""}${autoSession.error ? ` — ${autoSession.error}` : ""}` : "Auto session_start: disabled (DM_LENS_MCP_AUTO_SESSION not set)",
+      turnEnd ? `Stop-hook turn-end: ${turnEnd.ran} ran · ${turnEnd.skipped} skipped` + `${turnEnd.lastRunAt ? ` (last ran ${turnEnd.lastRunAt})` : ""}` + `${turnEnd.lastSkipReason ? ` — last skip: ${turnEnd.lastSkipReason}${turnEnd.lastSkipAt ? ` at ${turnEnd.lastSkipAt}` : ""}` : ""}` : "Stop-hook turn-end: no activity recorded (hook not installed, or no Stop yet)",
+      turnEnd?.failed ? `Analyzer invocations: ${turnEnd.failed} failed; last ${turnEnd.lastFailureOperation} failure at ${turnEnd.lastFailureAt}: ${turnEnd.lastFailureReason}` : "Analyzer invocations: no failures recorded",
+      healthConfigLine(configProvenance),
+      footprint ? `Resource footprint: ${footprint.instanceCount} dm-lens instance(s) · ` + `${(footprint.totalRssBytes / 1024 / 1024).toFixed(0)}MB RSS · ` + `${footprint.totalCpuPercent.toFixed(1)}% CPU · ` + `${footprint.totalLspChildCount} LSP child process(es)` : "Resource footprint: unavailable (instance registry unreadable)"
+    ];
+    return toolText(lines.join(`
+`), {
+      aliveClients,
+      servers,
+      brokenServers,
+      lastDispatch: last ? {
+        filePath: last.filePath,
+        totalDurationMs: last.totalDurationMs,
+        totalDiagnostics: last.totalDiagnostics
+      } : undefined,
+      diagnostics: {
+        shown: stats.totalShown,
+        autoFixed: stats.totalAutoFixed,
+        unresolved: stats.totalUnresolved
+      },
+      autoSession,
+      treeSitter,
+      turnEnd,
+      resourceFootprint: footprint,
+      degradations,
+      configProvenance
+    });
+  }
+  if (name === "dmlens_effective_config") {
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    const view = await effectiveConfig({
+      cwd,
+      ...typeof args.file === "string" ? { file: args.file } : {},
+      redact: true
+    });
+    const fileLines = view.file === undefined ? [] : isEffectiveFileViewError(view.file) ? [`File: ${view.file.error}`] : [
+      effectiveFileHeading(view.file),
+      ...view.file.servers.filter((server) => server.reason !== "extension-mismatch").map(effectiveServerLine),
+      ...view.file.tools.map((tool) => `  ${tool.selected ? "✓" : "✗"} ${tool.id} — ${tool.reason}`)
+    ];
+    const lines = [
+      `Config: ${view.documents.length} file(s) contributing, ${view.provenance.length} resolved leaf/leaves`,
+      ...view.documents.map(effectiveDocumentLine),
+      ...fileLines
+    ];
+    return toolText(lines.join(`
+`), view);
+  }
+  if (name === "dmlens_diagnostics") {
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    await ensureReady(cwd);
+    const out = await lensDiagnosticsTool.execute("mcp", args, new AbortController().signal, undefined, { cwd, host: "mcp" });
+    return out;
+  }
+  if (name === "dmlens_latency") {
+    const limit = typeof args.limit === "number" && Number.isFinite(args.limit) ? Math.max(1, Math.floor(args.limit)) : 5;
+    const fileFilter = typeof args.file === "string" ? args.file : undefined;
+    const recent = recentLatency(limit, fileFilter);
+    const summary = recent.length === 0 ? "No dispatch latency reports yet." : recent.map((report) => `${path.basename(report.filePath)}: ${report.totalDurationMs}ms ` + `(${report.totalDiagnostics} diag${report.stoppedEarly ? ", stopped early" : ""})`).join(`
+`);
+    return toolText(summary, recent);
+  }
+  if (name === "dmlens_session_start") {
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    await ensureReady(cwd);
+    const outcome = await runSessionStart(cwd);
+    const lines = [
+      `Session started for ${cwd}.`,
+      `LSP: ${outcome.aliveLspClients} alive client(s) (warming continues in background).`,
+      outcome.errorDebtBaseline ? `Error-debt baseline: tests ${outcome.errorDebtBaseline.testsPassed ? "pass" : "FAIL"}, build ${outcome.errorDebtBaseline.buildPassed ? "pass" : "FAIL"}.` : "Error-debt baseline: computing in background.",
+      "knip/jscpd/type-coverage/dep scans run in background — query dmlens_diagnostics shortly.",
+      outcome.guidance ? `
+${outcome.guidance}` : ""
+    ];
+    return toolText(lines.filter(Boolean).join(`
+`), outcome);
+  }
+  if (name === "dmlens_session_end") {
+    endSituationalToolTelemetry();
+    return toolText("Session ended.");
+  }
+  if (name === "dmlens_turn_end") {
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    await ensureReady(cwd);
+    const files = Array.isArray(args.files) ? args.files.filter((file) => typeof file === "string") : [];
+    const outcome = await runTurnEnd(cwd, files);
+    const parts = [
+      `Turn-end over ${outcome.filesRegistered} file(s).`,
+      outcome.turnEnd ?? "No turn-end advisory.",
+      outcome.tests ? `
+Tests:
+${outcome.tests}` : ""
+    ];
+    return toolText(parts.filter(Boolean).join(`
+`), outcome);
+  }
+  if (name === "dmlens_ast_grep_search" || name === "dmlens_ast_grep_replace") {
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    const tool = name === "dmlens_ast_grep_search" ? astGrepSearchTool : astGrepReplaceTool;
+    const out = await tool.execute("mcp", args, new AbortController().signal, undefined, { cwd, resultMaxItems: Number.POSITIVE_INFINITY });
+    return out;
+  }
+  if (name === "dmlens_lsp_navigation") {
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    await ensureReady(cwd);
+    const tool = lspNavigationTool;
+    const out = await tool.execute("mcp", args, new AbortController().signal, undefined, { cwd });
+    return out;
+  }
+  return { ...toolText(`Unknown tool: ${name}`), isError: true };
+}
+const WARN_ONLY_STALE_TOOLS = new Set([
+  "dmlens_module_report",
+  "dmlens_project_report",
+  "dmlens_symbol_search",
+  "dmlens_project_scan",
+  "dmlens_health",
+  "dmlens_latency",
+  "dmlens_session_start",
+  "dmlens_turn_end",
+  "dmlens_ast_grep_search",
+  "dmlens_ast_grep_replace",
+  "dmlens_lsp_navigation",
+  "dmlens_read_symbol",
+  "dmlens_read_enclosing",
+  "dmlens_effective_config"
+]);
+function withStaleWarning(result) {
+  if (result.content.length === 0)
+    return result;
+  const last = result.content[result.content.length - 1];
+  return {
+    ...result,
+    content: [
+      ...result.content.slice(0, -1),
+      {
+        ...last,
+        text: `${last.text}
+
+warmCodeStale: true
+${STALE_WARN_ONLY}`
+      }
+    ]
+  };
+}
+async function handleRequest(request) {
+  const { id, method, params } = request;
+  const isNotification = id === undefined;
+  switch (method) {
+    case "initialize": {
+      startSituationalToolTelemetrySession("mcp");
+      const requested = params?.protocolVersion;
+      sendResult(id ?? null, {
+        protocolVersion: typeof requested === "string" ? requested : FALLBACK_PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION }
+      });
+      maybeAutoSessionStart();
+      return;
+    }
+    case "notifications/initialized":
+    case "initialized":
+      return;
+    case "ping":
+      if (!isNotification)
+        sendResult(id ?? null, {});
+      return;
+    case "tools/list":
+      sendResult(id ?? null, { tools: enabledToolsForCwd(DEFAULT_CWD) });
+      return;
+    case "tools/call": {
+      const name = params?.name;
+      const rawArguments = params?.arguments;
+      const argumentsAreObject = typeof rawArguments === "object" && rawArguments !== null && !Array.isArray(rawArguments);
+      const args = argumentsAreObject ? rawArguments : {};
+      if (typeof name !== "string") {
+        sendError(id ?? null, -32602, "tools/call requires a string 'name'");
+        return;
+      }
+      if (!argumentsAreObject && rawArguments !== undefined && rawArguments !== null && !(Array.isArray(rawArguments) && rawArguments.length === 0)) {
+        sendError(id ?? null, -32602, "tools/call 'arguments' must be an object");
+        return;
+      }
+      const enabledName = name === "dmlens_lsp_diagnostics" ? "dmlens_diagnostics" : name;
+      if (name !== "dmlens_ast_grep_dump" && name !== "dmlens_rebuild" && !enabledToolsForCwd(typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD).some((tool) => tool.name === enabledName)) {
+        sendResult(id ?? null, stripResultDetails(finalizeToolResult({
+          ...toolText(`Unknown or disabled tool: ${name}`),
+          isError: true
+        })));
+        return;
+      }
+      const inputSchema = ALL_TOOLS.find((tool) => tool.name === enabledName)?.inputSchema;
+      const argumentReport = inputSchema ? findIgnoredArguments(inputSchema, args) : undefined;
+      if (argumentReport) {
+        incrementDegradationCount({
+          kind: "mcp-ignored-arguments",
+          subject: name,
+          reason: `ignored argument(s): ${ignoredArgumentsStructured(argumentReport).ignoredArguments.join(", ")}`
+        });
+        const refused = refusalResult(name, argumentReport);
+        if (refused) {
+          sendResult(id ?? null, stripResultDetails(finalizeToolResult(refused)));
+          return;
+        }
+      }
+      const entry = toolRegistryEntryForMcp(name);
+      if (entry && "situational" in entry && entry.situational) {
+        startSituationalToolTelemetrySession("mcp");
+        observeSituationalToolCall(entry.name);
+      }
+      maybeAutoSessionStart();
+      try {
+        let result = await callTool(name, args);
+        if (WARN_ONLY_STALE_TOOLS.has(name) && !result.isError && isWarmBuildStale()) {
+          result = withStaleWarning(result);
+        }
+        if (argumentReport)
+          result = withIgnoredArguments(result, name, argumentReport);
+        const delivery = finalizeToolResultWithDelivery(result);
+        sendResult(id ?? null, stripResultDetails(delivery.result));
+      } catch (err) {
+        sendResult(id ?? null, stripResultDetails(finalizeToolResult({
+          ...toolText(`dm-lens tool '${name}' failed: ${err.message}`),
+          isError: true
+        })));
+      }
+      return;
+    }
+    default:
+      if (!isNotification)
+        sendError(id ?? null, -32601, `Method not found: ${method}`);
+      return;
+  }
+}
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", createWarmIpcLineReader((raw) => {
+  const line = raw.trim();
+  if (line.length === 0)
+    return;
+  let request;
+  try {
+    request = JSON.parse(line);
+  } catch {
+    sendError(null, -32700, "Parse error");
+  }
+  if (request)
+    handleRequest(request);
+}, {
+  label: "mcp-stdio",
+  continuous: true,
+  onOverflow: () => sendError(null, -32700, "Parse error: request line exceeded the framing limit")
+}));
+process.stdin.on("end", () => {
+  endSituationalToolTelemetry();
+  flushExtensionLog().finally(() => process.exit(0));
+});
+startIpcServer();
+console.error(`[dm-lens-mcp] ready (cwd=${DEFAULT_CWD})`);