milens 0.7.0 → 0.7.2

package/dist/server/mcp.js

@@ -1,12 +1,12 @@
-import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { z } from 'zod';
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
-import { resolve, relative, join, dirname, basename } from 'node:path';
+import { resolve, relative, join, dirname } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { readFileSync, readdirSync, statSync, mkdirSync, existsSync, writeFileSync } from 'node:fs';
+import { readFileSync, readdirSync, statSync, mkdirSync, existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import ignore from 'ignore';
 import { Database } from '../store/db.js';
@@ -14,14 +14,19 @@ import { RepoRegistry } from '../store/registry.js';
 import { getParser, loadLanguage } from '../parser/loader.js';
 import { ALL_LANGS } from '../parser/languages.js';
 import { fileURLToPath } from 'node:url';
-import { generateTestPlan } from './test-plan.js';
 import { AnnotationStore } from '../store/annotations.js';
 import { registerAllPrompts } from './mcp-prompts.js';
-import { loadRules } from '../security/rules.js';
-import { HookManager, defaultOnSessionStart, defaultOnSessionEnd, defaultOnPreCommit, defaultOnFileChange, defaultOnPreCompact, defaultOnPostCompact } from './hooks.js';
 import { Orchestrator } from '../orchestrator/orchestrator.js';
+import { registerResources } from './tools/resources.js';
+import { countDependentFiles } from '../analyzer/risk.js';
+import { registerSessionTools } from './tools/session.js';
+import { registerTestingTools } from './tools/testing.js';
+import { registerSecurityTools } from './tools/security.js';
+import { registerFindingsReportTools } from './tools/findings-report.js';
 import { FileWatcher } from './watcher.js';
 import { reviewPr } from '../analyzer/review.js';
+import { globToRegex } from '../utils.js';
+import { BUILD_SHA, BUILT_AT } from '../build-info.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_VERSION = process.env.MILENS_VERSION ?? JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf-8')).version;
 // ── Lazy DB connection with idle eviction ──
@@ -147,7 +152,10 @@ class SessionGuard {
     }
 }
 // ── Tool usage tracking ──
-// Estimated tokens an agent would spend WITHOUT milens (manual exploration cost per tool)
+// Hand-picked heuristic estimates of tokens an agent would spend WITHOUT milens
+// (manual exploration cost per tool). Not derived from measurement — these feed
+// the "tokens saved" numbers in usage tracking/dashboards, so treat them as a
+// rough directional signal, not a validated benchmark.
 const TOKEN_SAVINGS_MULTIPLIER = {
     query: 3, // vs 3+ separate grep/file reads
     grep: 2, // vs terminal grep + manual filtering
@@ -233,10 +241,10 @@ function isTestFilePath(filePath) {
 // ── Text grep across project files ──
 const GREP_SKIP_DIRS = new Set([
     'node_modules', '.git', 'dist', 'build', 'out',
-    '.next', '.nuxt', '.svelte-kit',
+    '.next', '.nuxt', '.svelte-kit', '.turbo', '.cache', '.parcel-cache',
     '__pycache__', '.venv', 'venv', 'env',
     'vendor', 'target',
-    '.idea', '.vscode',
+    '.idea',
     'coverage', '.nyc_output',
 ]);
 const BINARY_EXTENSIONS = new Set([
@@ -276,8 +284,6 @@ function grepFiles(rootPath, pattern, options) {
                 return;
             const abs = join(dir, entry);
             const rel = relative(rootPath, abs).replace(/\\/g, '/');
-            if (entry.startsWith('.') && entry !== '.')
-                continue;
             if (GREP_SKIP_DIRS.has(entry))
                 continue;
             if (ig.ignores(rel))
@@ -328,7 +334,11 @@ function matchesScope(lineText, scope) {
     // definitions: function, class, interface, struct, trait, enum, type, def, fn, pub fn, etc.
     return /^(export\s+)?(async\s+)?(function|class|interface|type|enum|struct|trait|const|let|var|def|fn|pub\s+fn|pub\s+struct|pub\s+enum|module)\s/.test(trimmed);
 }
-/** Validate user-supplied regex is safe from catastrophic backtracking (ReDoS). */
+/**
+ * Validate user-supplied regex is safe from catastrophic backtracking (ReDoS).
+ * This is a heuristic blocklist of known-dangerous constructs, not a formal
+ * proof of safety — it catches common patterns but isn't exhaustive.
+ */
 function safeRegex(pattern, flags) {
     if (pattern.length > 200)
         throw new Error('Pattern too long');
@@ -355,14 +365,6 @@ function safeRegex(pattern, flags) {
         throw new Error('Unsafe regex pattern');
     return new RegExp(pattern, flags);
 }
-function globToRegex(glob) {
-    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&')
-        .replace(/\*\*/g, '§STARSTAR§')
-        .replace(/\*/g, '[^/]*')
-        .replace(/§STARSTAR§/g, '.*')
-        .replace(/\?/g, '.');
-    return new RegExp(`^${escaped}$`, 'i');
-}
 function loadGrepIgnoreRules(rootPath) {
     const ig = ignore();
     ig.add(['node_modules', 'dist', 'build', '.git', '__pycache__', 'vendor', 'target']);
@@ -389,7 +391,7 @@ RULE: Before opening ANY file to understand code, call the appropriate milens to
 
 AUDIT: session_end reports which symbols were safety-checked. Editing without checks = audit gap.
 
-TOKEN SAVINGS: Using milens first = 70% fewer tokens, zero missed dependencies.
+TOKEN SAVINGS: Using milens first typically means far fewer tokens than manual exploration, and fewer missed dependencies — impact/context track code-level references; pair with grep for templates/configs/docs.
 
 milens — code intelligence engine. Indexes codebases into symbol graphs.
 
@@ -438,6 +440,9 @@ export function createMcpServer(rootPath) {
     const toolCallCounts = new Map(); // In-memory counter per repo
     const trackDb = getTrackingDb();
     const guard = new SessionGuard();
+    // On Windows, the same path can arrive as "c:\..." or "C:\..." depending on the
+    // caller — without normalizing the drive letter, those resolve to different
+    // registry keys and split one repo's index across two entries.
     function normalizePath(p) {
         const abs = resolve(p);
         if (process.platform === 'win32') {
@@ -445,6 +450,19 @@ export function createMcpServer(rootPath) {
         }
         return abs;
     }
+    function isInsideDocstring(content, lineNumber) {
+        const lines = content.split('\n');
+        let inside = false;
+        for (let i = 0; i < lineNumber; i++) {
+            if (i >= lines.length)
+                break;
+            const trimmed = lines[i].trim();
+            const tripleCount = (trimmed.match(/"""|'''/g) || []).length;
+            for (let j = 0; j < tripleCount; j++)
+                inside = !inside;
+        }
+        return inside;
+    }
     function resolveRoot(repoPath) {
         if (repoPath) {
             const root = normalizePath(repoPath);
@@ -487,7 +505,11 @@ export function createMcpServer(rootPath) {
         return toolCallCounts.get(root) ?? 0;
     }
     const server = new McpServer({ name: 'milens', version: PKG_VERSION }, { instructions: MILENS_INSTRUCTIONS });
-    // Auto-wrap every tool handler with usage tracking + background decay tick
+    // Auto-wrap every tool handler with usage tracking + background decay tick.
+    // This replaces `server.tool` itself, so every `server.tool(...)` call below —
+    // including the ones inside registerTestingTools/registerSessionTools/
+    // registerSecurityTools/registerResources in other files, which all receive
+    // this same `server` instance — goes through this wrapper too.
     const origTool = server.tool.bind(server);
     let lastDecayTick = 0;
     const DECAY_INTERVAL = 5 * 60_000; // 5 minutes between decay ticks
@@ -521,13 +543,15 @@ export function createMcpServer(rootPath) {
         }
         return origTool(...args);
     });
-    // ── Selective tool profiles (W4) ──
+    // ── Selective tool profiles ──
     const profile = process.env.MILENS_PROFILE || undefined;
     if (profile && profile !== 'full') {
         const minimal = new Set(['query', 'grep', 'context', 'impact', 'status', 'codebase_summary', 'edit_check', 'detect_changes', 'get_file_symbols', 'overview']);
-        const standard = new Set([...minimal, 'domains', 'repos', 'explain_relationship', 'find_dead_code', 'get_type_hierarchy', 'trace', 'routes', 'smart_context', 'review_pr', 'review_symbol', 'test_coverage_gaps', 'test_plan', 'test_impact', 'session_start', 'recall']);
+        const standard = new Set([...minimal, 'domains', 'repos', 'explain_relationship', 'find_dead_code', 'get_type_hierarchy', 'trace', 'routes', 'smart_context', 'review_pr', 'review_symbol', 'test_coverage_gaps', 'test_plan', 'test_impact', 'session_start', 'recall', 'generate_findings_report']);
         const allowed = profile === 'minimal' ? minimal : standard;
-        // Wrap server.tool again to gate by profile
+        // Wrap the tracking-wrapped server.tool again, so profile gating sits on
+        // top: disabled tools still get registered (via the no-op handler below)
+        // and still get tracked, they just short-circuit to the disabled message.
         const profileWrappedTool = server.tool.bind(server);
         server.tool = ((...args) => {
             const toolName = args[0];
@@ -673,7 +697,8 @@ export function createMcpServer(rootPath) {
                 lines.push(`No ${direction} deps found.`);
             }
             else {
-                const depth1Count = refs.filter(r => r.depth === 1).length;
+                // Dedupe depth-1 by calling file — same real dependent, same blast radius
+                const depth1Count = countDependentFiles(db, sym.id).count;
                 lines.push(`${direction} (${refs.length} symbols, depth-1: ${depth1Count}):`);
                 lines.push(fmtImpact(refs, detail));
                 // Strict mode: hard stop if depth-1 dependents > 5
@@ -698,7 +723,19 @@ export function createMcpServer(rootPath) {
         const stats = lazy.getCachedStats();
         const unresolved = db.getUnresolvedStats();
         const coverage = db.getTestCoverage();
-        let text = `repo: ${root}\nsymbols: ${stats.symbols}\nlinks: ${stats.links}\nfiles: ${stats.files}`;
+        let text = `repo: ${root}\nbuild: ${BUILD_SHA} (built: ${BUILT_AT})\nversion: ${PKG_VERSION}\nsymbols: ${stats.symbols}\nlinks: ${stats.links}\nfiles: ${stats.files}`;
+        // Warn if the running server build differs from the on-disk build
+        try {
+            const distBuildPath = join(__dirname, '..', 'build-info.js');
+            if (existsSync(distBuildPath)) {
+                const diskBuild = readFileSync(distBuildPath, 'utf-8');
+                const m = diskBuild.match(/export const BUILD_SHA = '([^']+)'/);
+                if (m && m[1] !== BUILD_SHA) {
+                    text += `\n⚠ Running server build (${BUILD_SHA}) differs from on-disk build (${m[1]}) — restart the MCP server to pick up recent changes.`;
+                }
+            }
+        }
+        catch { /* best-effort */ }
         if (unresolved.imports > 0 || unresolved.calls > 0) {
             text += `\n⚠ unresolved (internal): ${unresolved.imports} imports, ${unresolved.calls} calls — callers may be incomplete`;
         }
@@ -719,13 +756,13 @@ export function createMcpServer(rootPath) {
         if (staleFiles.length > 0) {
             text += `\n⏳ ${staleFiles.length} files not analyzed in 24h`;
         }
-        // Accuracy report — confidence distribution of resolved links
+        // Resolution confidence distribution (heuristic self-ratings, not validated accuracy)
         const conf = db.getConfidenceDistribution();
         if (conf.total > 0) {
             const highPct = Math.round(conf.high / conf.total * 100);
             const medPct = Math.round(conf.medium / conf.total * 100);
             const lowPct = Math.round(conf.low / conf.total * 100);
-            text += `\naccuracy: ${conf.total} links — ≥0.9: ${conf.high} (${highPct}%) | 0.7-0.9: ${conf.medium} (${medPct}%) | <0.7: ${conf.low} (${lowPct}%)`;
+            text += `\nresolution confidence: ${conf.total} links — ≥0.9: ${conf.high} (${highPct}%) | 0.7-0.9: ${conf.medium} (${medPct}%) | <0.7: ${conf.low} (${lowPct}%)`;
             if (lowPct > 15) {
                 text += `\n⚠ ${lowPct}% low-confidence links — consider re-analyzing with \`--force\` or reviewing unresolved calls`;
             }
@@ -755,7 +792,7 @@ export function createMcpServer(rootPath) {
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: overview ──
-    server.tool('overview', 'ONE call replaces 3-5 file reads. Combined context + impact + grep. Use BEFORE reading any source file. Saves 70% tokens vs reading files individually. Preferred before editing/deleting/renaming a symbol.', {
+    server.tool('overview', 'ONE call replaces 3-5 file reads. Combined context + impact + grep. Use BEFORE reading any source file. Typically far fewer tokens than reading files individually. Preferred before editing/deleting/renaming a symbol.', {
         name: z.string().describe('Symbol name'),
         repo: z.string().optional(),
         depth: z.number().optional().default(2).describe('Impact traversal depth (default: 2)'),
@@ -776,8 +813,11 @@ export function createMcpServer(rootPath) {
         // Section 2: Context (incoming + outgoing) for each symbol
         if (symbols.length > 0) {
             for (const sym of symbols) {
-                const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
-                const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
+                const incoming = db.getIncomingLinks(sym.id);
+                const outgoing = db.getOutgoingLinks(sym.id);
+                if (symbols.length > 1) {
+                    sections.push(`─── ${fmtSymbol(sym, detail)} ---`);
+                }
                 if (incoming.length > 0) {
                     sections.push(`[incoming] ${incoming.length} refs:`);
                     const inSyms = incoming.map(l => {
@@ -855,7 +895,8 @@ export function createMcpServer(rootPath) {
                         lines.push(`  domains: ${summary.domains.join(', ')}`);
                     }
                     if (summary.staleCount > 0) {
-                        lines.push(`  ⏳ ${summary.staleCount} stale files`);
+                        const stalePct = summary.files > 0 ? Math.round(summary.staleCount / summary.files * 100) : 0;
+                        lines.push(`  ⏳ ${summary.staleCount} stale files (>24h)${stalePct > 20 ? ' — ⚠ run `milens analyze` to refresh' : ''}`);
                     }
                     if (!pools.has(entry.rootPath))
                         tempDb.close();
@@ -874,6 +915,9 @@ export function createMcpServer(rootPath) {
         repo: z.string().optional(),
     }, async ({ ref, repo }) => {
         const { db, root } = getDb(repo);
+        // `ref` is passed straight to `git diff` below. Restrict it to characters
+        // valid in a git ref so it can't be crafted as a flag (e.g. a leading "-")
+        // and get interpreted as a git option instead of a revision.
         if (!/^[a-zA-Z0-9\/._~^\-]+$/.test(ref)) {
             return { content: [{ type: 'text', text: 'Invalid git ref.' }] };
         }
@@ -940,11 +984,11 @@ export function createMcpServer(rootPath) {
             const unchangedNote = unchangedCount > 0 ? ` (${unchangedCount} unchanged not shown)` : '';
             lines.push(`${file}: ${displaySyms.length} changed symbols${unchangedNote}`);
             for (const sym of displaySyms) {
-                const upstream = db.findUpstream(sym.id, 1);
+                const depsCount = countDependentFiles(db, sym.id).count;
                 totalChanged++;
-                if (upstream.length > 0) {
-                    lines.push(`  ${sym.name} [${sym.kind}] :${sym.startLine} → ${upstream.length} direct dependents`);
-                    totalAffected += upstream.length;
+                if (depsCount > 0) {
+                    lines.push(`  ${sym.name} [${sym.kind}] :${sym.startLine} → ${depsCount} direct dependents`);
+                    totalAffected += depsCount;
                 }
                 else {
                     lines.push(`  ${sym.name} [${sym.kind}] :${sym.startLine}`);
@@ -962,12 +1006,32 @@ export function createMcpServer(rootPath) {
         repo: z.string().optional(),
     }, async ({ from, to, repo }) => {
         const { db } = getDb(repo);
-        const path = db.findPath(from, to);
+        let fromSyms = db.findSymbolByName(from);
+        const toSyms = db.findSymbolByName(to);
+        if (fromSyms.length === 0) {
+            return { content: [{ type: 'text', text: `Symbol "${from}" not found in index. Try \`grep\`.` }] };
+        }
+        if (toSyms.length === 0) {
+            return { content: [{ type: 'text', text: `Symbol "${to}" not found in index. Try \`grep\`.` }] };
+        }
+        // Vue SFC: class-kind symbols have no call edges; resolve to file's _top module
+        const fromSym = fromSyms[0];
+        if (fromSym.kind === 'class' && fromSym.filePath.endsWith('.vue')) {
+            const topId = `${fromSym.filePath}#module:_top:0`;
+            const topSym = db.findSymbolById(topId);
+            if (topSym)
+                fromSyms = [topSym];
+        }
+        // Use the id-based lookup once a symbol has been disambiguated above —
+        // findPath(name, ...) would re-resolve by name and could pick a
+        // different same-named symbol (e.g. some other file's "_top"),
+        // silently undoing the disambiguation.
+        const path = db.findPathFromId(fromSyms[0].id, to);
         if (!path) {
             return { content: [{ type: 'text', text: `No path between "${from}" and "${to}".` }] };
         }
-        const fromSym = db.findSymbolByName(from)[0];
-        const lines = [`FROM: ${fmtSymbol(fromSym)}`, ''];
+        const displaySym = fromSyms[0];
+        const lines = [`FROM: ${fmtSymbol(displaySym)}`, ''];
         for (const { symbol, depth, via } of path) {
             lines.push(`  ${'→'.repeat(depth)} [${via}] ${fmtSymbol(symbol)}`);
         }
@@ -981,12 +1045,25 @@ export function createMcpServer(rootPath) {
     }, async ({ kind, limit, repo }) => {
         const { db } = getDb(repo);
         const dead = db.findDeadCode(kind, limit);
-        if (dead.length === 0) {
+        const testOnly = db.findTestOnlyReferenced(limit);
+        const lines = [];
+        if (dead.length === 0 && testOnly.length === 0) {
             return { content: [{ type: 'text', text: 'No unreferenced exported symbols found.' }] };
         }
-        const lines = [`${dead.length} unreferenced exported symbols (code-level only — verify with grep before removing):\n`];
-        for (const sym of dead) {
-            lines.push(fmtSymbol(sym));
+        if (dead.length > 0) {
+            const cappedNote = dead.length >= limit ? ` (showing ${dead.length}, may be more — increase limit to see all)` : '';
+            lines.push(`${dead.length} unreferenced exported symbols (code-level only — verify with grep before removing)${cappedNote}:\n`);
+            for (const sym of dead) {
+                lines.push(fmtSymbol(sym));
+            }
+        }
+        if (testOnly.length > 0) {
+            if (dead.length > 0)
+                lines.push('');
+            lines.push(`─── Symbols referenced only by test files (likely orphaned) — ${testOnly.length} found:\n`);
+            for (const sym of testOnly) {
+                lines.push(fmtSymbol(sym));
+            }
         }
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
@@ -995,7 +1072,11 @@ export function createMcpServer(rootPath) {
         file: z.string().describe('File path (relative to repo root)'),
         repo: z.string().optional(),
         detail: z.enum(['L0', 'L1', 'L2']).optional().default('L1').describe('Output detail: L0=names only, L1=default, L2=full metadata'),
-    }, async ({ file, repo, detail }) => {
+        limit: z.number().optional().default(100).describe('Max symbols to return'),
+        offset: z.number().optional().default(0).describe('Offset for pagination'),
+    }, async ({ file, repo, detail, limit, offset }) => {
+        limit = limit ?? 100;
+        offset = offset ?? 0;
         const { db } = getDb(repo);
         const symbols = db.getSymbolsByFile(file);
         if (symbols.length === 0) {
@@ -1005,8 +1086,13 @@ export function createMcpServer(rootPath) {
         const sorted = detail === 'L2'
             ? [...symbols].sort((a, b) => (b.heat ?? 0) - (a.heat ?? 0))
             : symbols;
-        const lines = [`${file}: ${symbols.length} symbols\n`];
-        for (const sym of sorted) {
+        const paginated = sorted.slice(offset, offset + limit);
+        const total = sorted.length;
+        const pageInfo = total > limit || offset > 0
+            ? ` (showing ${offset + 1}-${Math.min(offset + limit, total)} of ${total}; use offset/limit to paginate)`
+            : '';
+        const lines = [`${file}: ${total} symbols${pageInfo}\n`];
+        for (const sym of paginated) {
             const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
             const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
             const exp = sym.exported ? ' (exported)' : '';
@@ -1059,13 +1145,17 @@ export function createMcpServer(rootPath) {
             if (ancestors.length > 0) {
                 lines.push('extends/implements:');
                 for (const { symbol: a, depth } of ancestors) {
-                    lines.push(`  ${'↑'.repeat(depth)} ${fmtSymbol(a)}`);
+                    const isExternal = a.filePath === '(external)';
+                    const label = isExternal ? ` ${fmtSymbol(a)} (external)` : ` ${fmtSymbol(a)}`;
+                    lines.push(`  ${'↑'.repeat(depth)}${label}`);
                 }
             }
             if (descendants.length > 0) {
                 lines.push('extended/implemented by:');
                 for (const { symbol: d, depth } of descendants) {
-                    lines.push(`  ${'↓'.repeat(depth)} ${fmtSymbol(d)}`);
+                    const isExternal = d.filePath === '(external)';
+                    const label = isExternal ? ` ${fmtSymbol(d)} (external)` : ` ${fmtSymbol(d)}`;
+                    lines.push(`  ${'↓'.repeat(depth)}${label}`);
                 }
             }
             if (ancestors.length === 0 && descendants.length === 0) {
@@ -1123,7 +1213,7 @@ export function createMcpServer(rootPath) {
         // 5. Unresolved warning (only for internal)
         const unresolved = db.getUnresolvedStats();
         if (unresolved.imports > 0 || unresolved.calls > 0) {
-            sections.push(`⚠ index has ${unresolved.imports} unresolved internal imports, ${unresolved.calls} unresolved internal calls — callers list may be incomplete`);
+            sections.push(`⚠ this repo's index has ${unresolved.imports} unresolved internal imports, ${unresolved.calls} unresolved internal calls repo-wide — this symbol's callers list may be incomplete`);
         }
         // 6. Test coverage for this symbol
         for (const sym of symbols) {
@@ -1161,10 +1251,7 @@ export function createMcpServer(rootPath) {
         for (const sym of symbols) {
             sections.push(`${fmtSymbol(sym)}${sym.exported ? ' (exported)' : ''}`);
             const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
-            const depsCount = incoming.filter(l => {
-                const from = db.findSymbolById(l.fromId);
-                return from && !isTestFilePath(from.filePath);
-            }).length;
+            const depsCount = countDependentFiles(db, sym.id, { excludeTestFiles: true }).count;
             if (session_id)
                 guard.recordCheck(session_id, name);
             // Hard stop: if > 5 non-test dependents and no confirmation
@@ -1230,7 +1317,7 @@ export function createMcpServer(rootPath) {
         // Unresolved warning
         const unresolved = db.getUnresolvedStats();
         if (unresolved.imports > 0 || unresolved.calls > 0) {
-            sections.push(`⚠ index has ${unresolved.imports} unresolved internal imports, ${unresolved.calls} unresolved internal calls — callers list may be incomplete`);
+            sections.push(`⚠ this repo's index has ${unresolved.imports} unresolved internal imports, ${unresolved.calls} unresolved internal calls repo-wide — this symbol's callers list may be incomplete`);
         }
         return { content: [{ type: 'text', text: sections.join('\n') }] };
     });
@@ -1254,7 +1341,7 @@ export function createMcpServer(rootPath) {
                 const traces = db.traceToEntrypoints(sym.id, depth);
                 sections.push(`## Execution paths TO ${fmtSymbol(sym)}\n`);
                 if (traces.length === 0) {
-                    sections.push('No call chains found (symbol may be an entrypoint itself or unreachable).');
+                    sections.push('No call chain found — verify with `context()` before treating this symbol as dead code.');
                 }
                 else {
                     for (let i = 0; i < traces.length; i++) {
@@ -1295,17 +1382,20 @@ export function createMcpServer(rootPath) {
     // ── Tool: routes ──
     server.tool('routes', 'Detect framework routes/endpoints and map them to handler symbols. Scans for Express, FastAPI, NestJS, Flask, Go HTTP, PHP, Rails patterns.', {
         repo: z.string().optional(),
-        framework: z.string().optional().describe('Filter by framework (express, fastapi, nestjs, flask, go, php, rails). Default: auto-detect all.'),
-        limit: z.number().optional().default(50),
+        framework: z.string().optional().describe('Filter by framework (express, fastapi, nestjs, nestjs-gateway, flask, go, php, rails). Default: auto-detect all.'),
+        limit: z.number().optional().default(200).describe('Max routes to display. Internal search always scans up to 500 matches per framework, so a low limit only affects display truncation, not detection accuracy.'),
     }, async ({ repo, framework, limit }) => {
         const root = resolveRoot(repo);
         const { db } = getDb(repo);
-        // Route patterns for different frameworks
+        // Route patterns for different frameworks. Best-effort, single-line regex
+        // matching — route declarations split across multiple lines (e.g. a decorator
+        // and its path on separate lines) will not be detected.
         const routePatterns = [
             { name: 'express', pattern: /\b(?:app|router)\.(get|post|put|patch|delete|use|all)\s*\(\s*['"`]([^'"`]+)['"`]/, fileGlob: '**/*.{ts,js,mjs,cjs}' },
             { name: 'fastapi', pattern: /@(?:app|router)\.(get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.py' },
-            { name: 'flask', pattern: /@(?:app|bp|blueprint)\.(route|get|post|put|delete)\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.py' },
+            { name: 'flask', pattern: /@(?:app|bp|blueprint)\.route\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.py' },
             { name: 'nestjs', pattern: /@(Get|Post|Put|Patch|Delete)\s*\(\s*['"]?([^'")]*?)['"]?\s*\)/, fileGlob: '**/*.ts' },
+            { name: 'nestjs-gateway', pattern: /@SubscribeMessage\s*\(\s*['"]([^'"]+)['"]\s*\)/, fileGlob: '**/*.ts' },
             { name: 'go', pattern: /\b(?:mux|router|http)\.(HandleFunc|Handle|Get|Post|Put|Delete)\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.go' },
             { name: 'php', pattern: /Route::(get|post|put|patch|delete|any)\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.php' },
             { name: 'rails', pattern: /\b(get|post|put|patch|delete|resources?|root)\s+['"]([^'"]+)['"]/, fileGlob: '**/*.rb' },
@@ -1314,19 +1404,29 @@ export function createMcpServer(rootPath) {
             ? routePatterns.filter(p => p.name === framework.toLowerCase())
             : routePatterns;
         if (activePatterns.length === 0) {
-            return { content: [{ type: 'text', text: `Unknown framework "${framework}". Available: express, fastapi, nestjs, flask, go, php, rails` }] };
+            return { content: [{ type: 'text', text: `Unknown framework "${framework}". Available: express, fastapi, nestjs, nestjs-gateway, flask, go, php, rails` }] };
         }
         const routes = [];
         for (const rp of activePatterns) {
             const matches = grepFiles(root, rp.pattern.source, {
-                isRegex: true, maxResults: limit, includePattern: rp.fileGlob,
+                isRegex: true, maxResults: 500, includePattern: rp.fileGlob,
             });
             for (const m of matches) {
                 const match = rp.pattern.exec(m.text);
                 if (!match)
                     continue;
-                const method = match[1].toUpperCase();
-                const path = match[2] || '/';
+                // Skip matches inside Python docstrings (triple-quoted strings)
+                if (rp.fileGlob === '**/*.py') {
+                    try {
+                        const filePath = resolve(root, m.file);
+                        const content = readFileSync(filePath, 'utf-8');
+                        if (isInsideDocstring(content, m.line))
+                            continue;
+                    }
+                    catch { /* can't read file — skip filtering */ }
+                }
+                const method = rp.name === 'nestjs-gateway' ? 'WS' : match[1].toUpperCase();
+                const path = rp.name === 'nestjs-gateway' ? match[1] : (match[2] || '/');
                 // Try to find the handler symbol on this line or nearby
                 const fileSymbols = db.getSymbolsByFile(m.file);
                 const handler = fileSymbols.find(s => s.startLine <= m.line && s.endLine >= m.line && s.kind === 'method') ?? fileSymbols.find(s => s.startLine <= m.line && s.endLine >= m.line) ?? fileSymbols.find(s => Math.abs(s.startLine - m.line) <= 3 && (s.kind === 'function' || s.kind === 'method'));
@@ -1343,6 +1443,71 @@ export function createMcpServer(rootPath) {
         if (routes.length === 0) {
             return { content: [{ type: 'text', text: 'No framework routes detected.' }] };
         }
+        // NestJS: join controller prefix with method path
+        const nestjsRoutes = routes.filter(r => r.framework === 'nestjs');
+        if (nestjsRoutes.length > 0) {
+            const nestjsByFile = new Map();
+            for (const r of nestjsRoutes) {
+                const arr = nestjsByFile.get(r.file) ?? [];
+                arr.push(r);
+                nestjsByFile.set(r.file, arr);
+            }
+            for (const [file, fileRoutes] of nestjsByFile) {
+                try {
+                    const content = readFileSync(resolve(root, file), 'utf-8');
+                    const lines = content.split('\n');
+                    // Find @Controller decorators with their class body line ranges
+                    const controllers = [];
+                    const ctrlRe = /@Controller\s*\(\s*['"]?([^'")]*?)['"]?\s*\)/;
+                    const classRe = /export\s+(?:abstract\s+)?class\s+\w+/;
+                    for (let i = 0; i < lines.length; i++) {
+                        const cm = ctrlRe.exec(lines[i]);
+                        if (!cm)
+                            continue;
+                        // Find the class declaration within next 5 lines
+                        let classLine = -1;
+                        for (let j = i; j < Math.min(i + 5, lines.length); j++) {
+                            if (classRe.test(lines[j])) {
+                                classLine = j;
+                                break;
+                            }
+                        }
+                        if (classLine === -1)
+                            continue;
+                        // Track brace depth to find end of class body
+                        let depth = 0;
+                        let started = false;
+                        let endLine = classLine;
+                        for (let k = classLine; k < lines.length; k++) {
+                            for (const ch of lines[k]) {
+                                if (ch === '{') {
+                                    depth++;
+                                    started = true;
+                                }
+                                else if (ch === '}') {
+                                    depth--;
+                                }
+                            }
+                            if (started && depth === 0) {
+                                endLine = k;
+                                break;
+                            }
+                        }
+                        controllers.push({ prefix: cm[1] || '', startLine: classLine + 1, endLine: endLine + 1 });
+                    }
+                    // Map each route to its controller prefix
+                    for (const r of fileRoutes) {
+                        const ctrl = controllers.find(c => r.line >= c.startLine && r.line <= c.endLine);
+                        if (ctrl && ctrl.prefix) {
+                            const methodPath = r.path === '/' ? '' : r.path;
+                            const joinPath = ctrl.prefix + (methodPath.startsWith('/') || methodPath === '' ? methodPath : '/' + methodPath);
+                            r.path = joinPath || '/';
+                        }
+                    }
+                }
+                catch { /* can't read file */ }
+            }
+        }
         // Group by framework
         const grouped = new Map();
         for (const r of routes) {
@@ -1350,10 +1515,13 @@ export function createMcpServer(rootPath) {
             arr.push(r);
             grouped.set(r.framework, arr);
         }
-        const lines = [`${routes.length} routes detected:\n`];
+        const displayRoutes = routes.slice(0, limit);
+        const lines = [`${routes.length} routes detected${routes.length > limit ? ` (showing first ${limit})` : ''}:\n`];
         for (const [fw, fwRoutes] of grouped) {
             lines.push(`[${fw}]`);
             for (const r of fwRoutes) {
+                if (!displayRoutes.includes(r))
+                    break;
                 const handlerInfo = r.handler ? ` → ${r.handler}` : '';
                 lines.push(`  ${r.method.padEnd(7)} ${r.path}  (${r.file}:${r.line})${handlerInfo}`);
             }
@@ -1452,10 +1620,19 @@ export function createMcpServer(rootPath) {
                 // Execution paths + data flow
                 const traces = db.traceToEntrypoints(sym.id, 6);
                 if (traces.length > 0) {
+                    const seenChains = new Set();
                     sections.push(`execution paths (${traces.length}):`);
-                    for (let i = 0; i < Math.min(traces.length, 3); i++) {
+                    let shown = 0;
+                    for (let i = 0; i < traces.length && shown < 3; i++) {
                         const chain = traces[i].path;
-                        sections.push(`  ${chain.map(s => s.symbol.name).join(' → ')}`);
+                        const firstFile = chain[0]?.symbol?.filePath?.split('/').pop() ?? '';
+                        const rendered = chain.map(s => s.symbol.name).join(' → ');
+                        const key = `${firstFile}: ${rendered}`;
+                        if (seenChains.has(key))
+                            continue;
+                        seenChains.add(key);
+                        sections.push(`  ${key}`);
+                        shown++;
                     }
                 }
                 else {
@@ -1610,7 +1787,7 @@ export function createMcpServer(rootPath) {
             return { content: [{ type: 'text', text: `Query error: ${err.message}` }] };
         }
     });
-    // ═══ codebase_summary ═══
+    // ── Tool: codebase_summary ──
     server.tool('codebase_summary', '500-token project overview. Use at session start INSTEAD of reading README, exploring directory structure, or reading multiple files to understand the codebase. Returns domains, key symbols, coverage %.', { repo: z.string().optional() }, async ({ repo }) => {
         const { db } = getDb(repo);
         const summary = db.getCodebaseSummary();
@@ -1638,7 +1815,7 @@ export function createMcpServer(rootPath) {
         }
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
-    // ═══ review_pr ═══
+    // ── Tool: review_pr ──
     server.tool('review_pr', 'PR risk assessment: git diff -> affected symbols with risk scores (LOW/MEDIUM/HIGH/CRITICAL).', { ref: z.string().optional().default('HEAD'), repo: z.string().optional() }, async ({ ref, repo }) => {
         const { db, root } = getDb(repo);
         const result = reviewPr(db, root, ref);
@@ -1664,7 +1841,7 @@ export function createMcpServer(rootPath) {
         lines.push(`\nSummary: CRITICAL=${summary.CRITICAL} HIGH=${summary.HIGH} MEDIUM=${summary.MEDIUM} LOW=${summary.LOW}`);
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
-    // ═══ review_symbol ═══
+    // ── Tool: review_symbol ──
     server.tool('review_symbol', 'Deep-dive single symbol risk: role, heat, dependents, test status, risk level.', { name: z.string(), repo: z.string().optional() }, async ({ name, repo }) => {
         const { db, root } = getDb(repo);
         const syms = db.findSymbolByName(name);
@@ -1672,9 +1849,19 @@ export function createMcpServer(rootPath) {
             return { content: [{ type: 'text', text: `"${name}" not found.` }] };
         const lines = [];
         for (const sym of syms) {
-            const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
+            const incomingRaw = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
+            // Dedupe by calling file — imports + calls from the same file is 1 real dependent
+            const seenCallerFiles = new Set();
+            const incoming = incomingRaw.filter(l => {
+                const from = db.findSymbolById(l.fromId);
+                const key = from?.filePath ?? l.fromId;
+                if (seenCallerFiles.has(key))
+                    return false;
+                seenCallerFiles.add(key);
+                return true;
+            });
             const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
-            const depsCount = incoming.length;
+            const depsCount = countDependentFiles(db, sym.id).count;
             const depsTop = incoming.slice(0, 5).map(l => { const s = db.findSymbolById(l.fromId); return s?.name ?? l.fromId; });
             const outCount = outgoing.length;
             const outTop = outgoing.slice(0, 5).map(l => { const s = db.findSymbolById(l.toId); return s?.name ?? l.toId; });
@@ -1702,208 +1889,9 @@ export function createMcpServer(rootPath) {
         }
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
-    // ═══ test_coverage_gaps ═══
-    server.tool('test_coverage_gaps', 'Untested exported symbols sorted by risk. Prioritize writing tests for these.', { limit: z.number().optional().default(20), repo: z.string().optional() }, async ({ limit, repo }) => {
-        const { db } = getDb(repo);
-        const coverage = db.getTestCoverage();
-        const gaps = db.getTestCoverageGaps(limit);
-        const lines = [`Test Coverage: ${coverage.testedSymbols}/${coverage.exportedProductionSymbols} (${coverage.exportedProductionSymbols > 0 ? Math.round(coverage.testedSymbols / coverage.exportedProductionSymbols * 100) : 0}%) from ${coverage.testFiles} test files\n`];
-        if (gaps.length === 0) {
-            lines.push('All exported symbols have test coverage!');
-        }
-        else {
-            lines.push(`Top ${gaps.length} untested symbols:\n`);
-            for (const g of gaps) {
-                const incoming = db.getIncomingLinks(g.id).filter(l => l.type !== 'contains');
-                const risk = (g.heat ?? 0) > 80 ? 'CRITICAL' : (g.heat ?? 0) > 50 ? 'HIGH' : (g.heat ?? 0) > 30 ? 'MEDIUM' : 'LOW';
-                lines.push(`  ${g.name} [${g.kind}] ${g.filePath}:${g.startLine} — heat:${g.heat ?? 0} deps:${incoming.length} risk:${risk}`);
-            }
-        }
-        return { content: [{ type: 'text', text: lines.join('\n') }] };
-    });
-    // ═══ test_impact ═══
-    server.tool('test_impact', 'Map changed code -> which test files to run. Use after making changes.', { ref: z.string().optional().default('HEAD'), repo: z.string().optional() }, async ({ ref, repo }) => {
-        const { db, root } = getDb(repo);
-        let changedFiles = [];
-        try {
-            const { execSync } = await import('node:child_process');
-            const diff = execSync(`git diff --name-only ${ref}`, { cwd: root, encoding: 'utf-8' }).trim();
-            changedFiles = diff ? diff.split('\n').filter(Boolean) : [];
-        }
-        catch { }
-        if (changedFiles.length === 0)
-            return { content: [{ type: 'text', text: 'No changed files.' }] };
-        const changedIds = [];
-        const changedNames = [];
-        for (const file of changedFiles) {
-            for (const sym of db.getSymbolsByFile(file)) {
-                changedIds.push(sym.id);
-                changedNames.push(sym.name);
-            }
-        }
-        if (changedIds.length === 0)
-            return { content: [{ type: 'text', text: 'No symbols in changed files.' }] };
-        const impact = db.getTestImpact(changedIds);
-        const lines = [`Changed symbols (${changedNames.length}): ${changedNames.join(', ')}`];
-        lines.push(`\nAffected test files (${impact.testFiles.length}):`);
-        for (const f of impact.testFiles)
-            lines.push(`  ${f}`);
-        if (impact.testFiles.length > 0) {
-            lines.push(`\nSuggested command: npx vitest run ${impact.testFiles.join(' ')}`);
-        }
-        return { content: [{ type: 'text', text: lines.join('\n') }] };
-    });
-    // ═══ test_plan ═══
-    server.tool('test_plan', 'Generate a test strategy for a symbol: mock plan + >=3 test scenarios.', { name: z.string(), repo: z.string().optional() }, async ({ name, repo }) => {
-        const { db, root } = getDb(repo);
-        const plan = generateTestPlan(db, name, root);
-        if (!plan)
-            return { content: [{ type: 'text', text: `"${name}" not found.` }] };
-        return { content: [{ type: 'text', text: plan.planText }] };
-    });
-    // ═══ annotate ═══
-    server.tool('annotate', 'Record a note about a symbol for future sessions. Use after discovering bugs, patterns, or important caveats.', {
-        symbol: z.string(),
-        key: z.enum(['note', 'bug', 'security', 'architecture', 'workflow', 'test', 'dependency', 'refactor']),
-        value: z.string(),
-        agent: z.string().optional(),
-        session_id: z.string().optional(),
-        confidence: z.number().optional().default(0.5),
-    }, async ({ symbol, key, value, agent, session_id, confidence }) => {
-        const { db } = getDb();
-        const store = new AnnotationStore(db.connection);
-        const ann = store.annotate(symbol, key, value, { agent, sessionId: session_id });
-        return { content: [{ type: 'text', text: `Annotation saved: ${ann.id}\n  symbol: ${ann.symbol}\n  key: ${ann.key}\n  confidence: ${ann.confidence}` }] };
-    });
-    // ═══ recall ═══
-    server.tool('recall', 'Retrieve annotations saved in previous sessions. Filter by symbol, key, or agent.', {
-        symbol: z.string().optional(), key: z.enum(['note', 'bug', 'security', 'architecture', 'workflow', 'test', 'dependency', 'refactor']).optional(),
-        agent: z.string().optional(), limit: z.number().optional().default(50),
-    }, async ({ symbol, key, agent, limit }) => {
-        const { db } = getDb();
-        const store = new AnnotationStore(db.connection);
-        const results = store.recall({ symbol, key, agent, limit });
-        if (results.length === 0)
-            return { content: [{ type: 'text', text: 'No annotations found.' }] };
-        const lines = [`${results.length} annotation(s):\n`];
-        for (const a of results) {
-            lines.push(`[${a.key}] ${a.symbol} — ${a.value.slice(0, 120)}`);
-            lines.push(`  confidence: ${a.confidence.toFixed(1)} | agent: ${a.agent ?? '?'} | ${a.updatedAt}\n`);
-        }
-        return { content: [{ type: 'text', text: lines.join('\n') }] };
-    });
-    // ═══ session_start ═══
-    server.tool('session_start', 'Start a new session. Returns a session ID to use with annotate, session_end, and handoff.', { agent: z.string().describe('Agent name (e.g. vibe-coder, reviewer)') }, async ({ agent }) => {
-        const { db, root, dbPath } = getDb();
-        const store = new AnnotationStore(db.connection);
-        const sessionId = store.sessionStart(agent);
-        let hookOutput = '';
-        try {
-            const manager = new HookManager();
-            const config = manager.loadConfig(root);
-            if (config.enabled && config.onSessionStart) {
-                hookOutput = await defaultOnSessionStart({ agent, sessionId, rootPath: root }, dbPath);
-            }
-        }
-        catch { /* hooks are best-effort */ }
-        const text = `Session started: ${sessionId}\nAgent: ${agent}\nUse this ID with annotate() and session_end().`;
-        return { content: [{ type: 'text', text: hookOutput ? `${hookOutput}\n\n${text}` : text }] };
-    });
-    // ═══ session_context ═══
-    server.tool('session_context', 'Get metadata about a session: annotations, tool calls, duration.', { session_id: z.string() }, async ({ session_id }) => {
-        const { db, root } = getDb();
-        const store = new AnnotationStore(db.connection);
-        const ctx = store.sessionContext(session_id);
-        if (!ctx.session)
-            return { content: [{ type: 'text', text: `Session "${session_id}" not found.` }] };
-        const s = ctx.session;
-        const liveCalls = getToolCallCount(root);
-        const displayCalls = s.toolCallsCount > 0 ? s.toolCallsCount : liveCalls;
-        const lines = [
-            `Session: ${s.id}`,
-            `Agent: ${s.agent} | Status: ${s.status}`,
-            `Started: ${s.startedAt} | Ended: ${s.endedAt ?? 'in progress'}`,
-            `Tool calls: ${displayCalls}${s.toolCallsCount === 0 ? ' (live count, resets on restart)' : ''} | Annotations: ${s.annotationsCount}`,
-        ];
-        if (s.context)
-            lines.push(`Context: ${s.context}`);
-        if (ctx.annotations.length > 0) {
-            lines.push(`\nAnnotations (${ctx.annotations.length}):`);
-            for (const a of ctx.annotations) {
-                lines.push(`  [${a.key}] ${a.symbol}: ${a.value.slice(0, 80)}`);
-            }
-        }
-        return { content: [{ type: 'text', text: lines.join('\n') }] };
-    });
-    // ═══ session_end ═══
-    server.tool('session_end', 'End a session and record its stats. Shows audit trail: which symbols were safety-checked vs total edit operations. Use at the end of every session.', { session_id: z.string(), status: z.enum(['completed', 'failed']).optional().default('completed') }, async ({ session_id, status }) => {
-        const { db, root, dbPath } = getDb();
-        const store = new AnnotationStore(db.connection);
-        const summary = store.sessionEnd(session_id, status);
-        // Audit trail from SessionGuard
-        const audit = guard.getAudit(session_id);
-        guard.clear(session_id);
-        let hookOutput = '';
-        try {
-            const ctx = store.sessionContext(session_id);
-            const manager = new HookManager();
-            const config = manager.loadConfig(root);
-            if (config.enabled && config.onSessionEnd) {
-                hookOutput = await defaultOnSessionEnd({ agent: ctx.session.agent, sessionId: session_id, rootPath: root }, dbPath);
-            }
-        }
-        catch { /* hooks are best-effort */ }
-        const lines = [
-            `Session ended: ${session_id}`,
-            `Status: ${status}`,
-            `Annotations: ${summary.annotationCount}`,
-            `───`,
-            `Audit Trail:`,
-            `  safety checks performed: ${audit.checked.length}`,
-            audit.checked.length > 0 ? `  symbols checked: ${audit.checked.join(', ')}` : '  ⚠ no symbols were checked via guard_edit_check',
-            audit.editOps > 0 ? `  edit operations reported: ${audit.editOps}` : null,
-        ].filter(Boolean);
-        const text = lines.join('\n');
-        return { content: [{ type: 'text', text: hookOutput ? `${text}\n\n${hookOutput}` : text }] };
-    });
-    // ═══ handoff ═══
-    server.tool('handoff', 'Transfer context from one agent session to another. Ends the source session and creates a new one for the target agent.', {
-        from_session: z.string(), to_agent: z.string(),
-        context: z.string().describe('Summary of what was done, key decisions, and caveats for the next agent'),
-    }, async ({ from_session, to_agent, context }) => {
-        const { db } = getDb();
-        const store = new AnnotationStore(db.connection);
-        const result = store.handoff(from_session, to_agent, context);
-        return { content: [{ type: 'text', text: `Handoff complete.\nNew session: ${result.newSessionId}\nAgent: ${to_agent}\nAnnotations copied: ${result.annotationsCopied}` }] };
-    });
-    // ═══ pre_commit_check ═══
-    server.tool('pre_commit_check', 'Run pre-commit risk analysis: detect_changes + review_pr + dead code + coverage gaps. Use before committing.', { repo: z.string().optional().describe('Repository root path') }, async ({ repo }) => {
-        const { root } = getDb(repo);
-        const report = await defaultOnPreCommit(root);
-        return { content: [{ type: 'text', text: report }] };
-    });
-    // ═══ hook_onFileChange ═══
-    server.tool('hook_onFileChange', 'Trigger the onFileChange hook. Call this when files are modified to get impact summary.', {
-        files: z.array(z.string()).describe('List of changed file paths'),
-        repo: z.string().optional(),
-    }, async ({ files, repo }) => {
-        const { root } = getDb(repo);
-        const report = await defaultOnFileChange(files, root);
-        return { content: [{ type: 'text', text: report }] };
-    });
-    // ═══ hook_preCompact ═══
-    server.tool('hook_preCompact', 'Trigger pre-compaction hook. Saves a metrics snapshot before context window compaction.', { repo: z.string().optional() }, async ({ repo }) => {
-        const { root, dbPath } = getDb(repo);
-        const report = await defaultOnPreCompact(root, dbPath);
-        return { content: [{ type: 'text', text: report }] };
-    });
-    // ═══ hook_postCompact ═══
-    server.tool('hook_postCompact', 'Trigger post-compaction hook. Recalls annotations to restore context after compaction.', { repo: z.string().optional() }, async ({ repo }) => {
-        const { root } = getDb(repo);
-        const report = await defaultOnPostCompact(root);
-        return { content: [{ type: 'text', text: report }] };
-    });
-    // ═══ semantic_search ═══
+    registerTestingTools(server, { getDb, fmtSymbol, fmtImpact, rootPath, toolCallCounts, resolveRoot, guard, getToolCallCount });
+    registerSessionTools(server, { getDb, fmtSymbol, fmtImpact, rootPath, toolCallCounts, resolveRoot, guard, getToolCallCount });
+    // ── Tool: semantic_search ──
     server.tool('semantic_search', 'Search symbols by semantic meaning (falls back to FTS5 keyword search when embeddings unavailable).', { query: z.string(), limit: z.number().optional().default(10), repo: z.string().optional() }, async ({ query, limit, repo }) => {
         const { db } = getDb(repo);
         const results = db.searchSymbols(query, limit);
@@ -1916,7 +1904,7 @@ export function createMcpServer(rootPath) {
         }
         return { content: [{ type: 'text', text: `No results for "${query}".\n\nTip: Run \`milens analyze --embeddings\` to enable semantic (vector) search. Currently using FTS5 keyword fallback which only matches exact symbol names.` }] };
     });
-    // ═══ find_similar ═══
+    // ── Tool: find_similar ──
     server.tool('find_similar', 'Find symbols topologically similar to a given symbol (shared callers/callees). Useful for finding patterns to copy or refactor together.', { name: z.string(), limit: z.number().optional().default(10), repo: z.string().optional() }, async ({ name, limit, repo }) => {
         const { db } = getDb(repo);
         const syms = db.findSymbolByName(name);
@@ -1931,111 +1919,16 @@ export function createMcpServer(rootPath) {
         }
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
-    // ══════════════════════════════════════════════
     // ── MCP Resources ──
-    // ══════════════════════════════════════════════
-    // ── Resource: milens://symbol/{name} ──
-    server.resource('symbol', new ResourceTemplate('milens://symbol/{name}', { list: undefined }), { description: 'Symbol context: definition, incoming refs, outgoing deps, role/heat metadata' }, async (uri, { name }) => {
-        const { db } = getDb();
-        const symbols = db.findSymbolByName(name);
-        if (symbols.length === 0) {
-            return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: `"${name}" not found.` }] };
-        }
-        const lines = [];
-        for (const sym of symbols) {
-            lines.push(`${fmtSymbol(sym, 'L2')}${sym.exported ? ' (exported)' : ''}`);
-            const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
-            if (incoming.length > 0) {
-                lines.push(`incoming (${incoming.length}):`);
-                for (const l of incoming) {
-                    const from = db.findSymbolById(l.fromId);
-                    lines.push(`  ${l.type}: ${from ? fmtSymbol(from) : l.fromId}`);
-                }
-            }
-            const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
-            if (outgoing.length > 0) {
-                lines.push(`outgoing (${outgoing.length}):`);
-                for (const l of outgoing) {
-                    const to = db.findSymbolById(l.toId);
-                    lines.push(`  ${l.type}: ${to ? fmtSymbol(to) : l.toId}`);
-                }
-            }
-            lines.push('');
-        }
-        return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: lines.join('\n') }] };
-    });
-    // ── Resource: milens://file/{path} ──
-    server.resource('file-symbols', new ResourceTemplate('milens://file/{+path}', { list: undefined }), { description: 'All symbols in a file with ref/dep counts' }, async (uri, { path }) => {
-        const { db } = getDb();
-        const filePath = decodeURIComponent(path);
-        const symbols = db.getSymbolsByFile(filePath);
-        if (symbols.length === 0) {
-            return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: `No symbols in "${filePath}".` }] };
-        }
-        const lines = [`${filePath}: ${symbols.length} symbols\n`];
-        for (const sym of symbols) {
-            const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
-            const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
-            const exp = sym.exported ? ' (exported)' : '';
-            lines.push(`${fmtSymbol(sym, 'L2')}${exp} ← ${incoming.length} refs, → ${outgoing.length} deps`);
-        }
-        return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: lines.join('\n') }] };
-    });
-    // ── Resource: milens://domain/{name} ──
-    server.resource('domain', new ResourceTemplate('milens://domain/{name}', { list: undefined }), { description: 'Domain cluster details: files and top symbols in a domain' }, async (uri, { name }) => {
-        const { db } = getDb();
-        const domainName = name;
-        // Find files in this domain
-        const allFiles = db.db_getFilesByZone(domainName);
-        if (allFiles.length === 0) {
-            return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: `Domain "${domainName}" not found.` }] };
-        }
-        const lines = [`domain: ${domainName} (${allFiles.length} files)\n`];
-        let totalSymbols = 0;
-        for (const file of allFiles) {
-            const syms = db.getSymbolsByFile(file);
-            totalSymbols += syms.length;
-            const exported = syms.filter(s => s.exported);
-            lines.push(`${file}: ${syms.length} symbols (${exported.length} exported)`);
-        }
-        lines.push(`\ntotal: ${totalSymbols} symbols in ${allFiles.length} files`);
-        return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: lines.join('\n') }] };
-    });
-    // ── Resource: milens://overview ──
-    server.resource('overview', 'milens://overview', { description: 'Index overview: stats, domains, unresolved, test coverage, staleness' }, async (uri) => {
-        const { db, root, lazy } = getDb();
-        const stats = lazy.getCachedStats();
-        const unresolved = db.getUnresolvedStats();
-        const coverage = db.getTestCoverage();
-        const domains = lazy.getCachedDomainStats();
-        const staleFiles = db.getStaleFiles(24);
-        const lines = [
-            `repo: ${root}`,
-            `symbols: ${stats.symbols}`,
-            `links: ${stats.links}`,
-            `files: ${stats.files}`,
-        ];
-        if (unresolved.imports > 0 || unresolved.calls > 0) {
-            lines.push(`⚠ unresolved (internal): ${unresolved.imports} imports, ${unresolved.calls} calls`);
-        }
-        if (unresolved.externalImports > 0 || unresolved.externalCalls > 0) {
-            lines.push(`external (expected): ${unresolved.externalImports} imports, ${unresolved.externalCalls} calls`);
-        }
-        if (coverage.testFiles > 0) {
-            const pct = coverage.exportedProductionSymbols > 0
-                ? Math.round(coverage.testedSymbols / coverage.exportedProductionSymbols * 100) : 0;
-            lines.push(`test coverage: ${coverage.testedSymbols}/${coverage.exportedProductionSymbols} (${pct}%) from ${coverage.testFiles} test files`);
-        }
-        if (domains.length > 0) {
-            lines.push(`\ndomains (${domains.length}):`);
-            for (const d of domains) {
-                lines.push(`  ${d.domain}: ${d.files} files, ${d.symbols} symbols`);
-            }
-        }
-        if (staleFiles.length > 0) {
-            lines.push(`\n⏳ ${staleFiles.length} stale files (>24h)`);
-        }
-        return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: lines.join('\n') }] };
+    registerResources(server, {
+        getDb,
+        fmtSymbol,
+        fmtImpact,
+        rootPath,
+        toolCallCounts,
+        resolveRoot,
+        guard,
+        getToolCallCount,
     });
     // ── Prompt: delete-feature ──
     server.prompt('delete-feature', 'Step-by-step workflow for safely deleting a feature from the codebase', { name: z.string().describe('Feature or symbol name to delete') }, ({ name }) => ({
@@ -2158,131 +2051,11 @@ export function createMcpServer(rootPath) {
                 },
             }],
     }));
-    // ── Register MCP Prompts (W1) ──
+    // ── Register MCP Prompts ──
     registerAllPrompts(server);
-    // ── Tool: security_scan (S2) ──
-    server.tool('security_scan', 'Scan codebase for security vulnerabilities using 190+ built-in rules across 25 categories. Replaces multiple manual grep() calls. Categories: secrets, injection, rce, xss, deserialization, ssrf, xxe, path-traversal, file-upload, unicode, dangerous, config, data-leak, crypto, auth, jwt, cors-headers, dependency, cloud, docker, kubernetes, iac, business-logic, api-security, misc, file-access.', {
-        scope: z.enum(['all', 'secrets', 'injection', 'rce', 'xss', 'deserialization', 'ssrf', 'xxe', 'path-traversal', 'file-upload', 'unicode', 'dangerous', 'config', 'data-leak', 'crypto', 'auth', 'jwt', 'cors-headers', 'dependency', 'cloud', 'docker', 'kubernetes', 'iac', 'business-logic', 'api-security', 'misc', 'file-access']).optional().default('all').describe('Scan scope'),
-        repo: z.string().optional().describe('Repository root path'),
-        severity: z.enum(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']).optional().describe('Minimum severity filter'),
-        limit: z.number().optional().default(50).describe('Max findings'),
-    }, async ({ scope, repo, severity, limit }) => {
-        const { db, root } = getDb(repo);
-        const rules = loadRules();
-        // Filter rules by scope and severity
-        const filtered = rules.filter(r => {
-            if (scope !== 'all' && r.category !== scope)
-                return false;
-            if (severity) {
-                const sevOrder = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
-                if ((sevOrder[r.severity] || 0) < (sevOrder[severity] || 0))
-                    return false;
-            }
-            return r.enabled;
-        });
-        // Get all source files from the DB
-        const symbols = db.getAllSymbols();
-        const fileSet = new Set();
-        for (const s of symbols) {
-            if (s.filePath && !s.filePath.includes('node_modules') && !s.filePath.includes('.git')) {
-                fileSet.add(s.filePath);
-            }
-        }
-        const files = [...fileSet].slice(0, 1000); // cap at 1000 files
-        const { readFileSync: rfs, existsSync: es } = await import('node:fs');
-        const { resolve: resolvePath } = await import('node:path');
-        const findings = [];
-        const byCategory = {};
-        const bySeverity = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
-        for (const file of files) {
-            const fullPath = resolvePath(root, file);
-            if (!es(fullPath))
-                continue;
-            // Apply excludeGlob from each rule's exclusion pattern
-            let shouldExclude = false;
-            for (const rule of filtered) {
-                if (rule.excludeGlob) {
-                    const excludePatterns = rule.excludeGlob.split(',');
-                    for (const pattern of excludePatterns) {
-                        const regex = new RegExp('^' + pattern.replace(/\./g, '\\.').replace(/\*/g, '.*').replace(/\*\*/g, '.*') + '$');
-                        if (regex.test(file) || regex.test('/' + file)) {
-                            shouldExclude = true;
-                            break;
-                        }
-                    }
-                }
-                if (shouldExclude)
-                    break;
-            }
-            if (shouldExclude)
-                continue;
-            // Skip files that don't match rule fileGlobs (simple check)
-            const applicableRules = filtered.filter(r => {
-                if (!r.fileGlob)
-                    return true;
-                // Simple glob: just check extension
-                const ext = r.fileGlob.replace('**/*.', '').replace('**/*', '');
-                return file.endsWith(ext) || r.fileGlob === '**/*';
-            });
-            if (applicableRules.length === 0)
-                continue;
-            try {
-                const content = rfs(fullPath, 'utf-8');
-                const lines = content.split('\n');
-                for (const rule of applicableRules) {
-                    for (const pattern of rule.patterns) {
-                        let match;
-                        // Reset regex lastIndex for global patterns
-                        pattern.lastIndex = 0;
-                        while ((match = pattern.exec(content)) !== null) {
-                            const lineNum = content.substring(0, match.index).split('\n').length;
-                            const ctxStart = Math.max(0, lineNum - 3);
-                            const ctxEnd = Math.min(lines.length, lineNum + 2);
-                            const context = lines.slice(ctxStart, ctxEnd).join('\n');
-                            findings.push({
-                                ruleId: rule.id,
-                                category: rule.category,
-                                severity: rule.severity,
-                                owasp: rule.owasp,
-                                file,
-                                line: lineNum,
-                                match: match[0].length > 100 ? match[0].slice(0, 97) + '...' : match[0],
-                                context,
-                                fix: rule.fix,
-                            });
-                            byCategory[rule.category] = (byCategory[rule.category] || 0) + 1;
-                            bySeverity[rule.severity] = (bySeverity[rule.severity] || 0) + 1;
-                        }
-                    }
-                }
-            }
-            catch {
-                // Skip unreadable files
-            }
-        }
-        // Calculate security score (100 - deductions)
-        const deduction = findings.filter((f) => f.severity === 'CRITICAL').length * 5 +
-            findings.filter((f) => f.severity === 'HIGH').length * 2 +
-            findings.filter((f) => f.severity === 'MEDIUM').length * 0.5;
-        const score = Math.max(0, Math.round(100 - deduction));
-        const limited = findings.slice(0, limit);
-        return {
-            content: [{
-                    type: 'text',
-                    text: JSON.stringify({
-                        summary: {
-                            totalScanned: files.length,
-                            findings: findings.length,
-                            byCategory,
-                            bySeverity,
-                            score,
-                        },
-                        findings: limited,
-                    }, null, 2),
-                }],
-        };
-    });
-    // ═══ compare_impact ═══
+    registerSecurityTools(server, { getDb, fmtSymbol, fmtImpact, rootPath, toolCallCounts, resolveRoot, guard, getToolCallCount });
+    registerFindingsReportTools(server, { getDb, fmtSymbol, fmtImpact, rootPath, toolCallCounts, resolveRoot, guard, getToolCallCount });
+    // ── Tool: compare_impact ──
     server.tool('compare_impact', 'Compare impact graph before/after an edit. Takes a snapshot first, then call again to see the diff. Returns new/removed dependents and heat changes.', {
         name: z.string().describe('Symbol name to compare'),
         action: z.enum(['snapshot', 'compare']).describe("'snapshot' to save current state, 'compare' to diff against last snapshot"),
@@ -2329,88 +2102,13 @@ export function createMcpServer(rootPath) {
             db.close();
         }
     });
-    // ═══ orchestrate ═══
+    // ── Tool: orchestrate ──
     server.tool('orchestrate', 'Run full orchestration cycle: detect_changes → review_pr → impact → coverage gaps → dead code. Returns structured action plan.', { repo: z.string().optional() }, async ({ repo }) => {
         const { root, dbPath } = getDb(repo);
         const orchestrator = new Orchestrator({ rootPath: root, dbPath, useEmoji: false });
         const report = await orchestrator.runAndFormat();
         return { content: [{ type: 'text', text: report }] };
     });
-    // ═══ fix_apply ═══
-    server.tool('fix_apply', 'Apply a security fix suggestion to a file. Creates a backup before modifying. CRITICAL rules require confirm: true.', {
-        ruleId: z.string().describe('Security rule ID (e.g. "hardcoded_secret")'),
-        file: z.string().describe('File path relative to repo root'),
-        line: z.number().describe('Line number where the issue was found'),
-        confirm: z.boolean().optional().default(false).describe('Confirmation required for CRITICAL rules'),
-        repo: z.string().optional(),
-    }, async ({ ruleId, file, line, confirm, repo }) => {
-        const { root } = getDb(repo);
-        const rules = loadRules();
-        const rule = rules.find(r => r.id === ruleId);
-        if (!rule)
-            return { content: [{ type: 'text', text: `Rule not found: "${ruleId}"` }] };
-        if (rule.severity === 'CRITICAL' && !confirm) {
-            return { content: [{ type: 'text', text: `CRITICAL rule "${ruleId}" requires confirmation. Set confirm: true to proceed.` }] };
-        }
-        const fullPath = resolve(root, file);
-        if (!existsSync(fullPath))
-            return { content: [{ type: 'text', text: `File not found: ${file}` }] };
-        const content = readFileSync(fullPath, 'utf-8');
-        const lines = content.split('\n');
-        if (line < 1 || line > lines.length)
-            return { content: [{ type: 'text', text: `Line ${line} out of range (file has ${lines.length} lines).` }] };
-        // Backup original
-        const backupDir = join(root, '.milens', 'backups');
-        mkdirSync(backupDir, { recursive: true });
-        const backupPath = join(backupDir, `${file.replace(/[\\/]/g, '_')}_${Date.now()}.bak`);
-        writeFileSync(backupPath, content, 'utf-8');
-        // Apply fix: add comment above the affected line with the fix suggestion
-        const targetLine = lines[line - 1];
-        const indent = targetLine.match(/^(\s*)/)?.[1] ?? '';
-        const fixComment = `${indent}// milens(fix): rule=${rule.id} — ${rule.fix ?? 'Review manually'}`;
-        lines.splice(line - 1, 0, fixComment);
-        const newContent = lines.join('\n');
-        writeFileSync(fullPath, newContent, 'utf-8');
-        return { content: [{ type: 'text', text: `Fix applied for rule "${ruleId}" at ${file}:${line}\nSeverity: ${rule.severity}\nBackup: ${relative(root, backupPath)}\nFix: ${rule.fix ?? 'Manual review needed'}\n\nAdded fix comment above line ${line}.` }] };
-    });
-    // ═══ test_generate ═══
-    server.tool('test_generate', 'Generate a test file for a symbol using its test plan. Detects test framework and follows project conventions.', {
-        symbol: z.string().describe('Symbol name to generate tests for'),
-        repo: z.string().optional(),
-    }, async ({ symbol, repo }) => {
-        const { db, root } = getDb(repo);
-        const plan = generateTestPlan(db, symbol, root);
-        if (!plan)
-            return { content: [{ type: 'text', text: `Symbol not found: "${symbol}"` }] };
-        // Detect test framework
-        const framework = detectTestFramework(root);
-        const testExt = framework === 'pytest' ? '.py' : '.test.ts';
-        // Determine test file path
-        const srcFile = plan.file;
-        const srcDir = dirname(srcFile);
-        const srcName = basename(srcFile, srcFile.includes('.') ? '.' + srcFile.split('.').pop() : '');
-        const testFileName = `${srcName}${testExt}`;
-        const testDir = join(srcDir, '__tests__');
-        const testPath = join(testDir, testFileName);
-        // Don't overwrite existing test files
-        if (existsSync(join(root, testPath))) {
-            return { content: [{ type: 'text', text: `Test file already exists at ${testPath}. Skipping to avoid overwrite.` }] };
-        }
-        // Check if a sister test file exists alongside the source
-        const altTestPath = join(srcDir, testFileName);
-        const existingTestDir = existsSync(join(root, testDir));
-        const altExists = existsSync(join(root, altTestPath));
-        if (altExists) {
-            return { content: [{ type: 'text', text: `Test file exists at ${altTestPath}. Skipping to avoid overwrite.` }] };
-        }
-        // Generate test code
-        const testCode = generateTestCode(plan, framework, srcFile);
-        // Write the test file
-        const writePath = existingTestDir ? testPath : altTestPath;
-        mkdirSync(dirname(join(root, writePath)), { recursive: true });
-        writeFileSync(join(root, writePath), testCode, 'utf-8');
-        return { content: [{ type: 'text', text: `Test file generated: ${writePath}\nFramework: ${framework}\nScenarios: ${plan.testScenarios.length}\nMock deps: ${plan.mockStrategy.length}` }] };
-    });
     // ── Prompt: dead_code_remove ──
     server.prompt('dead_code_remove', 'Safe dead code removal workflow: detect → verify → remove → test.', { repo: z.string().optional().describe('Repository root path') }, ({ repo }) => ({
         messages: [{
@@ -2435,103 +2133,6 @@ export function createMcpServer(rootPath) {
     }));
     return server;
 }
-// ── Helpers ──
-function detectTestFramework(rootPath) {
-    try {
-        const pkgPath = resolve(rootPath, 'package.json');
-        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-        const deps = { ...pkg.devDependencies, ...pkg.dependencies };
-        if (deps.vitest)
-            return 'vitest';
-        if (deps.jest)
-            return 'jest';
-        if (deps.mocha)
-            return 'mocha';
-    }
-    catch { }
-    // Check for Python
-    try {
-        const cfg = readFileSync(resolve(rootPath, 'pytest.ini'), 'utf-8');
-        return 'pytest';
-    }
-    catch { }
-    try {
-        const cfg = readFileSync(resolve(rootPath, 'setup.cfg'), 'utf-8');
-        if (cfg.includes('[tool:pytest]'))
-            return 'pytest';
-    }
-    catch { }
-    return 'vitest'; // default (Vitest is most common for TS projects)
-}
-function generateTestCode(plan, framework, srcFile) {
-    const lines = [];
-    if (framework === 'pytest') {
-        lines.push(`# Generated by milens — test plan for ${plan.symbol}`);
-        lines.push(`import pytest`);
-        lines.push(`from ${srcFile.replace(/[/\\]/g, '.').replace(/\.(ts|tsx|js|jsx|py)$/, '')} import ${plan.symbol}`);
-        lines.push('');
-        lines.push(`class Test${capitalize(plan.symbol)}:`);
-        for (const s of plan.testScenarios) {
-            lines.push(`    def test_${s.name.toLowerCase().replace(/\s+/g, '_')}(self):`);
-            lines.push(`        """${s.description}"""`);
-            lines.push(`        pass  # TODO: implement`);
-            lines.push('');
-        }
-    }
-    else {
-        const hasTypescript = srcFile.endsWith('.ts') || srcFile.endsWith('.tsx');
-        const ext = hasTypescript ? '.ts' : '.js';
-        lines.push(`// Generated by milens — test plan for ${plan.symbol}`);
-        if (framework === 'vitest') {
-            lines.push(`import { describe, it, expect${plan.mockStrategy.length > 0 ? ', vi' : ''} } from 'vitest';`);
-            lines.push(`import { ${plan.symbol} } from '${relativeImport(srcFile, hasTypescript)}';`);
-        }
-        else if (framework === 'mocha') {
-            lines.push(`import { expect } from 'chai';`);
-            lines.push(`import { ${plan.symbol} } from '${relativeImport(srcFile, hasTypescript)}';`);
-        }
-        else {
-            lines.push(`import { ${plan.symbol} } from '${relativeImport(srcFile, hasTypescript)}';`);
-        }
-        // Mock imports
-        for (const m of plan.mockStrategy) {
-            if (framework === 'vitest') {
-                lines.push(`vi.mock('${m.dependency}');`);
-            }
-            else if (framework === 'jest') {
-                lines.push(`jest.mock('${m.dependency}');`);
-            }
-        }
-        lines.push('');
-        const describeFn = framework === 'mocha' ? `describe('${plan.symbol}'` : framework === 'vitest' ? `describe('${plan.symbol}', () =>` : `describe('${plan.symbol}', () =>`;
-        const beforeEachHook = framework === 'mocha' ? `  beforeEach(() => {` : `  beforeEach(() => {`;
-        const endBrace = framework === 'mocha' ? `});` : `});`;
-        lines.push(`${describeFn} {`);
-        lines.push(`${beforeEachHook}`);
-        lines.push(`    // Setup mocks`);
-        lines.push(`  });`);
-        lines.push('');
-        for (const s of plan.testScenarios) {
-            const testFn = framework === 'mocha' ? `it('${s.name}'` : `it('${s.name}', () =>`;
-            lines.push(`    ${testFn} {`);
-            lines.push(`      // ${s.description}`);
-            lines.push(`      const result = ${plan.symbol}();`);
-            lines.push(`      expect(result).toBeDefined();`);
-            lines.push(`    });`);
-            lines.push('');
-        }
-        lines.push(`});`);
-    }
-    return lines.join('\n');
-}
-function capitalize(s) {
-    return s.charAt(0).toUpperCase() + s.slice(1);
-}
-function relativeImport(srcFile, hasTypescript) {
-    // Convert src/foo/bar.ts → ../foo/bar (relative import for __tests__/bar.test.ts)
-    const withoutExt = srcFile.replace(/\.(ts|tsx|js|jsx)$/, '');
-    return `.${hasTypescript ? '' : '.js'}/${withoutExt.split('/').pop()}`;
-}
 // ── Transport: stdio ──
 export async function startStdio(rootPath) {
     const server = createMcpServer(rootPath);
@@ -2558,14 +2159,33 @@ export async function startStdio(rootPath) {
             }
         }
     }
-    // Cleanup on exit
+    // Cleanup on exit — registering a custom SIGINT/SIGTERM handler replaces
+    // Node's default terminate-on-signal behavior, so we must exit explicitly
+    // or the process hangs forever waiting for the (already-closed) stdio transport.
     const cleanup = () => {
         if (watcher)
             watcher.stop();
+        process.exit(0);
     };
     process.on('SIGINT', cleanup);
     process.on('SIGTERM', cleanup);
-    await server.connect(transport);
+    // Many MCP hosts tear down the child by closing the stdio pipe (EOF) instead
+    // of sending a signal — StdioServerTransport doesn't detect this on its own,
+    // so without this the process leaks forever with no parent left to talk to.
+    process.stdin.on('end', cleanup);
+    process.stdin.on('close', cleanup);
+    try {
+        await server.connect(transport);
+    }
+    catch (err) {
+        server.server.sendLoggingMessage({
+            level: 'error',
+            data: `[milens:stdio] Failed to start: ${err.message}`,
+        });
+        if (watcher)
+            watcher.stop();
+        process.exit(1);
+    }
 }
 // ── Transport: HTTP (Streamable) ──
 export async function startHttp(port, rootPath) {
@@ -2593,10 +2213,20 @@ export async function startHttp(port, rootPath) {
             }
         }
     }
-    // Cleanup on exit
+    // Cleanup on exit — registering a custom SIGINT/SIGTERM handler replaces
+    // Node's default terminate-on-signal behavior, so we must exit explicitly
+    // or the process hangs forever with the HTTP server still listening.
+    let shuttingDown = false;
     const cleanup = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
         if (watcher)
             watcher.stop();
+        clearInterval(evictTimer);
+        httpServer.close(() => process.exit(0));
+        // Force-exit if some connection keeps the server from closing in time
+        setTimeout(() => process.exit(0), 3000).unref();
     };
     process.on('SIGINT', cleanup);
     process.on('SIGTERM', cleanup);
@@ -2649,7 +2279,20 @@ export async function startHttp(port, rootPath) {
                             sessions.set(id, { transport: transport, lastActive: Date.now() });
                         },
                     });
-                    await server.connect(transport);
+                    try {
+                        await server.connect(transport);
+                    }
+                    catch (err) {
+                        server.server.sendLoggingMessage({
+                            level: 'error',
+                            data: `[milens:http] Failed to connect transport: ${err.message}`,
+                        });
+                        if (!res.headersSent) {
+                            res.writeHead(500);
+                            res.end('Internal server error');
+                        }
+                        return;
+                    }
                 }
                 await transport.handleRequest(req, res, parsed);
             }
@@ -2667,7 +2310,7 @@ export async function startHttp(port, rootPath) {
     });
     // Bind to localhost only — prevents network exposure without auth
     httpServer.listen(port, '127.0.0.1', () => {
-        console.log(`milens MCP server listening on http://127.0.0.1:${port}/mcp`);
+        process.stderr.write(`milens MCP server listening on http://127.0.0.1:${port}/mcp\n`);
     });
 }
 function readBody(req) {