@duckmind/dm-linux-x64 0.63.9 → 0.64.6

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

@@ -0,0 +1,1205 @@
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { AstGrepClient } from "../clients/ast-grep-client.js";
+import { CacheManager } from "../clients/cache-manager.js";
+import {
+  getDegradationSummary,
+  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 { createAstGrepSearchTool } from "../tools/ast-grep-search.js";
+import { createLensDiagnosticsTool } from "../tools/lens-diagnostics.js";
+import { peekMcpSessionRuntime } from "../clients/mcp/session.js";
+import { createLspDiagnosticsTool } from "../tools/lsp-diagnostics.js";
+import { createLspNavigationTool } from "../tools/lsp-navigation.js";
+import { shouldInitializeSessionRoot } from "../clients/lsp/session-roots.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) })}
+`);
+        }
+      });
+    }));
+    socket.on("error", () => socket.destroy());
+  });
+  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 } });
+}
+function toolText(summary, structured, compact = false) {
+  const text = structured === undefined ? summary : `${summary}
+
+\`\`\`json
+${JSON.stringify(structured, compact ? undefined : null, compact ? undefined : 2)}
+\`\`\``;
+  return { content: [{ type: "text", text }] };
+}
+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.";
+}
+const cacheManager = new CacheManager;
+const lensDiagnosticsTool = createLensDiagnosticsTool(cacheManager, () => DEFAULT_CWD, undefined, undefined, undefined, undefined, () => peekMcpSessionRuntime());
+const astGrepClient = new AstGrepClient;
+const astGrepSearchTool = createAstGrepSearchTool(astGrepClient);
+const astGrepReplaceTool = createAstGrepReplaceTool(astGrepClient);
+const lspNavigationTool = createLspNavigationTool((name, cwd) => createMcpHost(undefined, cwd ?? DEFAULT_CWD).getFlag(name));
+const lspDiagnosticsTool = createLspDiagnosticsTool();
+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 (LSP + linters + structural " + "rules) on a single file and return its diagnostics plus the latency " + "record for that dispatch (same schema as latency.log). The core review " + "probe: shows a change's real behavioral + perf impact on a real file.",
+    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: "Query dm-lens's diagnostic state across ALL runners (not just LSP). " + "mode=delta (current turn, instant), mode=all (every dispatched file this " + "session), mode=full (expensive project-wide active scan).",
+    inputSchema: schemaWithCwd(lensDiagnosticsTool.parameters)
+  },
+  {
+    name: "dmlens_latency",
+    description: "Return recent dispatch latency reports (latency.log schema: per-file " + "total duration + per-runner timings). The review-loop measurement surface.",
+    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 subsequent `dmlens_analyze mode=fresh` runs reflect " + "the latest commit. Runs `npm run build` (in-place dev layout) or " + "`npm run build:dist` (precompiled dist layout), matching how this server " + "was launched. The missing link that makes the review loop honest: " + "commit → dmlens_rebuild → dmlens_analyze mode=fresh.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "dmlens_project_scan",
+    description: "Cheap project-wide scan (tree-sitter + fact rules) across source files, " + "returning structural/quality diagnostics. Complements dmlens_diagnostics " + "mode=full (which adds active LSP).",
+    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: "Ranked identifier search over the persisted word index (BM25 + priors " + "that demote tests/vendor and doc files). Answers 'which files are most " + "relevant to <query>' by identifier — first step of the discovery funnel: " + "symbol_search finds candidate files, dmlens_module_report explains one, " + "dmlens_read_symbol reads a body. Complements grep (raw substrings) and " + "LSP (exact symbols). Each hit's `startLine`/`endLine` mark its best-matching " + "line (offset=startLine, limit=endLine-startLine+1 for a one-line peek) — " + "use dmlens_module_report on `file` for the real outline. Returns " + "`available: false` with a retry hint if the index isn't built yet for this " + "workspace (dmlens_session_start builds it, or it self-builds in the background " + "on first query).",
+    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: "Structured, navigable overview of a source module — a token-efficient " + "substitute for reading the whole file. Returns each symbol's " + "name/kind/signature/line-range (plus a first-line `doc` summary when a " + "doc comment is attached), plus who-uses-this, risk flags, and ranked " + "recommendedReads. To read a symbol's body: call dmlens_read_symbol (or " + "read) with offset=startLine, limit=endLine-startLine+1 on THIS report's " + "`file` — those aren't repeated per symbol. Prefer this before a full " + "read; then use dmlens_read_symbol for the exact body. Single mode: " + "tree-sitter outline + review-graph who-uses-this + inline executable " + "extraction; degrades to outline-only when no cached graph is available " + "(this path never calls LSP). `semantic.source` reports whether graph " + "data was used. Pass `blastRadius: true` for the cross-file blast radius " + "(transitive dependents as ranked file reads, read-only over the cached " + "graph). Pass `callGraph: true` for bounded derived callers/callees; a " + "cold or stale call-graph cache is reported explicitly, never as zero calls. " + '`view: "compact"` returns a line-oriented text rendering ' + "(cheapest option) instead of JSON. An outline shows shape, not bodies.",
+    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: "Project-level orientation from the review graph — 'orient me in this " + "project' before drilling into any one file. First step of a wider " + "discovery funnel: dmlens_project_report orients, dmlens_module_report " + "explains a file, dmlens_read_symbol reads a body. Six capped, ranked " + "sections: a trust header (graph freshness, file coverage, " + "edge-resolution-quality mix), hubs (top fan-in files — the repo's " + "contract surface), entry points (near-zero fan-in / high fan-out files " + "— activation/CLI/mains), a directory-level subsystem map (import " + "cycles + layering violations, e.g. a forbidden clients/ -> tools/ " + "edge), risk hotspots (fan-in × max per-symbol cyclomatic complexity), " + "and suspected dead weight (zero-importer files, shipped with a " + "low-confidence disclaimer). Every file line carries a `suggestedNext` " + "module_report call. No per-symbol detail and no prose summary — " + "structural facts only. Read-only over the cached graph: returns " + "`available: false` with a retry hint on a cold cache and kicks off a " + 'background build (never blocks this call). `view: "compact"` returns ' + "a line-oriented text rendering instead of JSON. Pass `focus` to " + "re-rank every section toward a task hint.",
+    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 the verbatim source of a single named symbol " + "(function/class/method/interface/type) in a file — a targeted, cheap " + "alternative to reading the whole file. Pair with dmlens_module_report: it " + "finds the symbol, this shows its body. Includes an attached doc comment " + "when one exists. Accepts a dotted `Class.method` name to resolve a " + "member, falling back to a plain lookup when the qualifier doesn't " + "resolve. A miss embeds the ~3 nearest symbol names in the file. When " + "multiple same-file symbols share a name, the first is returned with an " + "ambiguity note; pass `kind` to pick a specific one.",
+    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 verbatim source for the smallest useful symbol/callback " + "enclosing a line in a file. Use after dmlens_ast_grep_search, " + "dmlens_diagnostics, or dmlens_lsp_navigation locations when you need " + "exact body text without reading the whole file. Uses tree-sitter only — " + "no LSP or graph build. MCP has no read-guard, so unlike the pi tool this " + "does not record edit-coverage.",
+    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: "dm-lens runtime health for THIS server: alive LSP servers, last dispatch " + "summary, session diagnostic counts, how many resolved config leaves each " + "source tier decided, and the total CPU/RAM footprint attributable to " + "dm-lens across every process it owns (host + LSP children) machine-wide, " + "from the shared instance registry.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "dmlens_effective_config",
+    description: "The resolved dm-lens configuration with the provenance of every " + "decision: which file and source tier each setting came from, the trust " + "decision that applied, and which config files contributed. Pass `file` " + "to also get, for that path, its canonical language, EVERY LSP server " + "with the reason it was selected or denied — including which tier's " + "config denied it, which a nearer file cannot lift — and the lint/format " + "runners that would dispatch. This is the answer to 'why is X running / " + "why is X not running' without reading logs. Redacted by construction: " + "it reports sources, never values — no environment values, no command " + "arguments beyond the binary itself, and config paths are home-relative.",
+    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: "Run dm-lens's real session_start lifecycle: warm the dominant-language " + "LSP (so subsequent dmlens_analyze is LSP-complete), establish the " + "error-debt baseline (tests/build pass-state) + complexity baselines, and " + "kick off knip/jscpd/type-coverage/dep/secrets project scans. Returns " + "project guidance + baseline; scan results land in caches (query via " + "dmlens_diagnostics afterwards). Run once per workspace before reviewing.",
+    inputSchema: {
+      type: "object",
+      properties: { cwd: { type: "string" } }
+    }
+  },
+  {
+    name: "dmlens_turn_end",
+    description: "Run dm-lens's real turn_end lifecycle over the files changed this turn: " + "knip dead-code + jscpd duplication (incremental), circular-dep checks, " + "tests on affected targets, cascade to dependents, and the actionable/" + "code-quality warning aggregation. Returns the turn-end advisory + test " + "findings. `files` is OPTIONAL — dmlens_analyze (and the PostToolUse hook) " + "auto-register edited files into turn-state, so you can call this with no " + "args after a series of edits; pass `files` to add any not analyzed.",
+    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_ast_grep_search",
+    description: "Structural (AST) code search via ast-grep — match by code structure, not " + "text. Use complete patterns with arguments (e.g. 'console.log($MSG)', " + "'function $NAME($$$ARGS) { $$$BODY }'), or use nodeKind to find every " + "node of a known grammar kind. Metavariables do not match text inside " + "quoted string literals; use an exact string or grep for wildcard text. " + "This is the same schema and synthesis path as the pi tool.",
+    inputSchema: schemaWithCwd(astGrepSearchTool.parameters)
+  },
+  {
+    name: "dmlens_ast_grep_replace",
+    description: "Structural (AST) find-and-rewrite via ast-grep, e.g. pattern='var $X' " + "rewrite='let $X'. DRY-RUN by default (apply=false shows the diff); set " + "apply=true to write the changes to disk.",
+    inputSchema: schemaWithCwd(astGrepReplaceTool.parameters)
+  },
+  {
+    name: "dmlens_lsp_navigation",
+    description: "LSP code navigation: definition, typeDefinition, declaration, " + "references, hover, documentSymbol, " + "workspaceSymbol, implementation, call hierarchy (prepareCallHierarchy/" + "incomingCalls/outgoingCalls), rename, codeAction, executeCommand " + "(allowlisted, dry-run by default) — exact + type-aware, " + "~50ms. Use before changing a signature to see every caller.",
+    inputSchema: schemaWithCwd(lspNavigationTool.parameters)
+  },
+  {
+    name: "dmlens_lsp_diagnostics",
+    description: "Pure LSP diagnostics for a file, directory, or batch of files (type " + "errors only — narrower than dmlens_diagnostics, which spans all runners).",
+    inputSchema: schemaWithCwd(lspDiagnosticsTool.parameters)
+  }
+];
+const TOOLS = canRebuildDmLens(REPO_ROOT) ? ALL_TOOLS : ALL_TOOLS.filter((tool) => tool.name !== "dmlens_rebuild");
+function formatAnalyze(result, cwd, mode, servedBy) {
+  const lspNote = result.lsp ? ` · lsp ${result.lsp.diagnosticCount} (${result.lsp.status}, ${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_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);
+    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)",
+      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 });
+    return { content: out.content };
+  }
+  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_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 });
+    return { content: out.content };
+  }
+  if (name === "dmlens_lsp_navigation" || name === "dmlens_lsp_diagnostics") {
+    const cwd = typeof args.cwd === "string" ? args.cwd : DEFAULT_CWD;
+    await ensureReady(cwd);
+    const tool = name === "dmlens_lsp_navigation" ? lspNavigationTool : lspDiagnosticsTool;
+    const out = await tool.execute("mcp", args, new AbortController().signal, undefined, { cwd });
+    return { content: out.content };
+  }
+  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_lsp_diagnostics",
+  "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": {
+      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: TOOLS });
+      return;
+    case "tools/call": {
+      const name = params?.name;
+      const args = params?.arguments && typeof params.arguments === "object" ? params.arguments : {};
+      if (typeof name !== "string") {
+        sendError(id ?? null, -32602, "tools/call requires a string 'name'");
+        return;
+      }
+      maybeAutoSessionStart();
+      try {
+        let result = await callTool(name, args);
+        if (WARN_ONLY_STALE_TOOLS.has(name) && !result.isError && isWarmBuildStale()) {
+          result = withStaleWarning(result);
+        }
+        sendResult(id ?? null, result);
+      } catch (err) {
+        sendResult(id ?? null, {
+          ...toolText(`dm-lens tool '${name}' failed: ${err.message}`),
+          isError: true
+        });
+      }
+      return;
+    }
+    default:
+      if (!isNotification)
+        sendError(id ?? null, -32601, `Method not found: ${method}`);
+      return;
+  }
+}
+let buffer = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  let newlineIndex = buffer.indexOf(`
+`);
+  while (newlineIndex !== -1) {
+    const line = buffer.slice(0, newlineIndex).trim();
+    buffer = buffer.slice(newlineIndex + 1);
+    if (line.length > 0) {
+      let request;
+      try {
+        request = JSON.parse(line);
+      } catch {
+        sendError(null, -32700, "Parse error");
+      }
+      if (request)
+        handleRequest(request);
+    }
+    newlineIndex = buffer.indexOf(`
+`);
+  }
+});
+process.stdin.on("end", () => process.exit(0));
+startIpcServer();
+console.error(`[dm-lens-mcp] ready (cwd=${DEFAULT_CWD})`);