milens 0.6.4 → 0.6.6

package/dist/server/mcp.js

@@ -4,9 +4,9 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { z } from 'zod';
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
-import { resolve, relative, join, dirname } from 'node:path';
+import { resolve, relative, join, dirname, basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { readFileSync, readdirSync, statSync, mkdirSync } from 'node:fs';
+import { readFileSync, readdirSync, statSync, mkdirSync, existsSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import ignore from 'ignore';
 import { Database } from '../store/db.js';
@@ -18,6 +18,10 @@ 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 { FileWatcher } from './watcher.js';
+import { reviewPr } from '../analyzer/review.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 ──
@@ -35,7 +39,7 @@ class LazyDb {
     }
     get() {
         this.resetTimer();
-        if (!this.instance) {
+        if (!this.instance || !this.instance.isOpen()) {
             this.instance = new Database(this.dbPath);
             this.statsCache = null;
             this.domainCache = null;
@@ -86,6 +90,30 @@ class LazyDb {
         this.instance = null;
     }
 }
+// ── Session-level edit safety guard ──
+class SessionGuard {
+    /** sessionId → Set of symbol names that had safety checks performed */
+    checks = new Map();
+    /** sessionId → total edit operations attempted (reported by agent) */
+    editOps = new Map();
+    recordCheck(sessionId, symbolName) {
+        if (!this.checks.has(sessionId))
+            this.checks.set(sessionId, new Set());
+        this.checks.get(sessionId).add(symbolName);
+    }
+    recordEditOp(sessionId) {
+        this.editOps.set(sessionId, (this.editOps.get(sessionId) ?? 0) + 1);
+    }
+    getAudit(sessionId) {
+        const checked = [...(this.checks.get(sessionId) ?? [])];
+        const ops = this.editOps.get(sessionId) ?? 0;
+        return { checked, editOps: ops };
+    }
+    clear(sessionId) {
+        this.checks.delete(sessionId);
+        this.editOps.delete(sessionId);
+    }
+}
 // ── Tool usage tracking ──
 // Estimated tokens an agent would spend WITHOUT milens (manual exploration cost per tool)
 const TOKEN_SAVINGS_MULTIPLIER = {
@@ -314,7 +342,24 @@ function loadGrepIgnoreRules(rootPath) {
     return ig;
 }
 // ── Server instructions (sent to client via MCP protocol on initialize) ──
-const MILENS_INSTRUCTIONS = `milens — code intelligence engine. Indexes codebases into symbol graphs.
+const MILENS_INSTRUCTIONS = `⚠️ CRITICAL: This project is indexed by milens (knowledge graph). Use milens MCP tools BEFORE reading files directly.
+
+WHY: The knowledge graph already knows every symbol, dependency, and reference. Reading files manually = slower, more expensive, and misses hidden connections.
+
+RULE: Before opening ANY file to understand code, call the appropriate milens tool:
+- overview({name: "X"}) — understand a symbol (context + impact + grep). Replaces 3-5 file reads.
+- impact({target: "X", mode: "strict"}) — check blast radius BEFORE editing. strict mode BLOCKS if >5 deps.
+- guard_edit_check({name: "X", session_id}) — HARD safety gate. Call BEFORE every edit. Returns BLOCKED if high risk.
+- grep({pattern: "X"}) — find ALL text references (code, templates, docs, configs, styles).
+- codebase_summary() — 500-token project overview. Use INSTEAD of reading README or exploring directories.
+- detect_changes() — verify changes before committing. Shows changed symbols + risk scores.
+- query({query: "X"}) — find symbol definitions by name. FTS5 instant search.
+
+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.
+
+milens — code intelligence engine. Indexes codebases into symbol graphs.
 
 ## Tool selection
 - \`query\` — find symbol definitions (code identifiers only)
@@ -322,6 +367,7 @@ const MILENS_INSTRUCTIONS = `milens — code intelligence engine. Indexes codeba
 - \`context\` — 360° view: incoming + outgoing for a symbol
 - \`impact\` — blast radius: what breaks if symbol changes
 - \`overview\` — combined context + impact + grep in one call (preferred for editing workflows)
+- \`guard_edit_check\` — HARD pre-edit gate: blocks if dependents > 5, tracks checks for session audit
 - \`edit_check\` — pre-edit safety: callers + export status + re-export chains + test coverage + ⚠ warnings (fastest for edits)
 - \`trace\` — execution flow: call chains from entrypoints to a symbol (or downstream from it)
 - \`routes\` — detect framework routes/endpoints (Express, FastAPI, NestJS, Flask, Go, PHP, Rails)
@@ -335,7 +381,9 @@ const MILENS_INSTRUCTIONS = `milens — code intelligence engine. Indexes codeba
 - \`get_type_hierarchy\` — inheritance tree
 
 ## Rules
-- Before editing a symbol: run \`edit_check\` or \`smart_context\` with intent=edit
+- Before editing a symbol: run \`guard_edit_check\` or \`edit_check\` or \`smart_context\` with intent=edit
+- \`guard_edit_check({name, session_id})\` — HARD gate: records check for audit, blocks if dependents > 5
+- \`impact({mode: "strict"})\` — strict mode returns BLOCKED when depth-1 deps > 5
 - For debugging: run \`smart_context\` with intent=debug or \`trace\` to=symbol
 - For writing tests: run \`smart_context\` with intent=test — shows deps to mock + callers to cover
 - \`impact\` only tracks code deps — always pair with \`grep\` for templates/configs
@@ -356,6 +404,7 @@ export function createMcpServer(rootPath) {
     const registry = new RepoRegistry();
     const pools = new Map();
     const trackDb = getTrackingDb();
+    const guard = new SessionGuard();
     function normalizePath(p) {
         const abs = resolve(p);
         if (process.platform === 'win32') {
@@ -394,11 +443,13 @@ export function createMcpServer(rootPath) {
         if (!pools.has(root))
             pools.set(root, new LazyDb(dbPath));
         const lazy = pools.get(root);
-        return { db: lazy.get(), root, lazy };
+        return { db: lazy.get(), root, dbPath, lazy };
     }
     const server = new McpServer({ name: 'milens', version: PKG_VERSION }, { instructions: MILENS_INSTRUCTIONS });
-    // Auto-wrap every tool handler with usage tracking
+    // Auto-wrap every tool handler with usage tracking + background decay tick
     const origTool = server.tool.bind(server);
+    let lastDecayTick = 0;
+    const DECAY_INTERVAL = 5 * 60_000; // 5 minutes between decay ticks
     server.tool = ((...args) => {
         const toolName = args[0];
         const handler = args[args.length - 1];
@@ -409,6 +460,21 @@ export function createMcpServer(rootPath) {
                 const responseText = result?.content?.map((c) => c.text).join('\n') ?? '';
                 const repo = handlerArgs[0]?.repo;
                 trackToolCall(trackDb, toolName, start, responseText, repo);
+                // Background confidence decay tick (real-time, every 5 min)
+                if (Date.now() - lastDecayTick > DECAY_INTERVAL) {
+                    lastDecayTick = Date.now();
+                    try {
+                        for (const [, pool] of pools) {
+                            const db = pool.get();
+                            const store = new AnnotationStore(db.connection);
+                            if (store.getAnnotationCount() >= 100) {
+                                const { runDecayPass } = await import('../store/confidence.js');
+                                runDecayPass(store);
+                            }
+                        }
+                    }
+                    catch { /* decay is best-effort */ }
+                }
                 return result;
             };
         }
@@ -438,7 +504,7 @@ export function createMcpServer(rootPath) {
         });
     }
     // ── Tool: query ──
-    server.tool('query', 'Search indexed symbol definitions by name/kind. For text in templates/configs/docs, use `grep`.', {
+    server.tool('query', 'Find symbol definitions by name (FTS5 instant search). Use instead of reading files to find where a function/class is defined. For text in templates/configs/docs, use `grep`.', {
         query: z.string().describe('Symbol name, kind, or keyword to search'),
         repo: z.string().optional().describe('Repository root path (optional if only one indexed)'),
         limit: z.number().optional().default(15).describe('Max results'),
@@ -452,10 +518,10 @@ export function createMcpServer(rootPath) {
         return { content: [{ type: 'text', text }] };
     });
     // ── Tool: grep ──
-    server.tool('grep', 'Text search ALL project files (templates, styles, configs, docs). Finds every text occurrence, not just symbols.', {
-        pattern: z.string().describe('Text or regex pattern to search for'),
+    server.tool('grep', 'Find EVERY text occurrence across ALL project files. Searches code, templates, styles, configs, docs — not just symbol definitions. Use INSTEAD of built-in search tools which may miss non-code files. ⚠️ IMPORTANT: Default is LITERAL mode (isRegex: false). Characters like | . * + ? are treated as literal text, NOT regex. To use regex alternation or wildcards, set isRegex: true.', {
+        pattern: z.string().describe('Text OR regex pattern to search for. ⚠️ Default is LITERAL: characters | . * + ? ( ) are escaped as plain text. To use regex, set isRegex: true.'),
         repo: z.string().optional().describe('Repository root path (optional)'),
-        isRegex: z.boolean().optional().default(false).describe('Treat pattern as regex'),
+        isRegex: z.boolean().optional().default(false).describe('Set to true for regex patterns. Default false: special chars like | . * are treated as literal text.'),
         caseSensitive: z.boolean().optional().default(false),
         include: z.string().optional().describe('Glob filter for file paths (e.g. "**/*.vue", "*.scss")'),
         scope: z.enum(['all', 'code', 'imports', 'definitions']).optional().default('all')
@@ -473,8 +539,14 @@ export function createMcpServer(rootPath) {
         const filtered = scope === 'all' || scope === 'code'
             ? matches
             : matches.filter(m => matchesScope(m.text, scope));
+        // Detect regex-like patterns used in literal mode (hint BEFORE result output)
+        const regexChars = /[|.*+?(){}\[\]]/;
+        const regexHint = (!isRegex && regexChars.test(pattern))
+            ? `⚠️ HINT: Pattern "${pattern}" contains special regex characters (${pattern.match(regexChars).join(' ')}). Default is LITERAL mode — these are escaped as plain text. To use as regex, add isRegex: true.\n\n`
+            : '';
         if (filtered.length === 0) {
-            return { content: [{ type: 'text', text: `No matches for "${pattern}"${scope !== 'all' ? ` (scope: ${scope})` : ''}` }] };
+            const hintBlock = regexHint + `No matches for "${pattern}"${scope !== 'all' ? ` (scope: ${scope})` : ''}`;
+            return { content: [{ type: 'text', text: hintBlock }] };
         }
         // Group by file for compact output
         const grouped = new Map();
@@ -483,7 +555,10 @@ export function createMcpServer(rootPath) {
             arr.push({ line: m.line, text: m.text });
             grouped.set(m.file, arr);
         }
-        const lines = [`${filtered.length} matches in ${grouped.size} files${scope !== 'all' ? ` (scope: ${scope})` : ''}:\n`];
+        const lines = [];
+        if (regexHint)
+            lines.push(regexHint);
+        lines.push(`${filtered.length} matches in ${grouped.size} files${scope !== 'all' ? ` (scope: ${scope})` : ''}:\n`);
         for (const [file, hits] of grouped) {
             lines.push(file);
             for (const h of hits) {
@@ -496,7 +571,7 @@ export function createMcpServer(rootPath) {
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: context ──
-    server.tool('context', 'Symbol 360°: incoming refs + outgoing deps. Use `overview` for combined context+impact+grep.', {
+    server.tool('context', '360° view of a symbol: who calls it + what it depends on. Instant dependency graph. Use INSTEAD of reading multiple files to trace call chains manually — catches cross-file imports you would miss.', {
         name: z.string().describe('Symbol name to inspect'),
         repo: z.string().optional(),
         detail: z.enum(['L0', 'L1', 'L2']).optional().default('L1').describe('Output detail: L0=names only, L1=default, L2=full metadata'),
@@ -534,13 +609,14 @@ export function createMcpServer(rootPath) {
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: impact ──
-    server.tool('impact', 'Blast radius: what symbols break if target changes. Code deps only — pair with `grep` for templates/configs.', {
+    server.tool('impact', 'Exact blast radius BEFORE you edit. Shows which symbols WILL BREAK if you change a target. Use instead of guessing or manually tracing dependencies. Code deps only — pair with `grep` for templates/configs.', {
         target: z.string().describe('Symbol name to analyze'),
         direction: z.enum(['upstream', 'downstream']).default('upstream'),
         depth: z.number().optional().default(3),
         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 ({ target, direction, depth, repo, detail }) => {
+        mode: z.enum(['normal', 'strict']).optional().default('normal').describe('strict=BLOCKED if depth-1 dependents > 5, normal=report only'),
+    }, async ({ target, direction, depth, repo, detail, mode }) => {
         const { db } = getDb(repo);
         const symbols = db.findSymbolByName(target);
         if (symbols.length === 0) {
@@ -556,8 +632,18 @@ export function createMcpServer(rootPath) {
                 lines.push(`No ${direction} deps found.`);
             }
             else {
-                lines.push(`${direction} (${refs.length} symbols):`);
+                const depth1Count = refs.filter(r => r.depth === 1).length;
+                lines.push(`${direction} (${refs.length} symbols, depth-1: ${depth1Count}):`);
                 lines.push(fmtImpact(refs, detail));
+                // Strict mode: hard stop if depth-1 dependents > 5
+                if (mode === 'strict' && direction === 'upstream' && depth1Count > 5) {
+                    lines.push('');
+                    lines.push('---');
+                    lines.push(`⚠️ BLOCKED: ${depth1Count} direct dependents (>5 threshold).`);
+                    lines.push('Editing this symbol may cause cascading breakage.');
+                    lines.push('To proceed: re-run with mode="normal" or explicitly acknowledge the risk.');
+                    lines.push('---');
+                }
             }
             lines.push('');
         }
@@ -628,7 +714,7 @@ export function createMcpServer(rootPath) {
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: overview ──
-    server.tool('overview', 'Combined context + impact + grep in ONE call. Preferred before editing/deleting/renaming a symbol. Saves 2-3 round trips.', {
+    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.', {
         name: z.string().describe('Symbol name'),
         repo: z.string().optional(),
         depth: z.number().optional().default(2).describe('Impact traversal depth (default: 2)'),
@@ -742,12 +828,11 @@ export function createMcpServer(rootPath) {
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: detect_changes ──
-    server.tool('detect_changes', 'Git diff → affected symbols + direct dependents.', {
+    server.tool('detect_changes', 'Pre-commit safety check. Uses git diff to show which symbols changed + their direct dependents + risk. Use INSTEAD of manually running `git diff` before every commit.', {
         ref: z.string().optional().default('HEAD').describe('Git ref to diff against (default: HEAD)'),
         repo: z.string().optional(),
     }, async ({ ref, repo }) => {
         const { db, root } = getDb(repo);
-        // Validate ref: only allow safe git ref characters (alphanumeric, /, ., -, _, ~, ^)
         if (!/^[a-zA-Z0-9\/._~^\-]+$/.test(ref)) {
             return { content: [{ type: 'text', text: 'Invalid git ref.' }] };
         }
@@ -763,24 +848,70 @@ export function createMcpServer(rootPath) {
         if (changedFiles.length === 0) {
             return { content: [{ type: 'text', text: 'No changed files detected.' }] };
         }
+        // Get changed line ranges per file (git diff -U0 gives hunk headers with @@ -old,new +old,new @@)
+        const changedLinesByFile = new Map();
+        for (const file of changedFiles) {
+            try {
+                const diffOut = execFileSync('git', ['diff', '-U0', ref, '--', file], { cwd: root, encoding: 'utf-8' });
+                const changedLines = new Set();
+                for (const line of diffOut.split('\n')) {
+                    const m = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+                    if (m) {
+                        const start = parseInt(m[1], 10);
+                        const count = m[2] ? parseInt(m[2], 10) : 1;
+                        for (let i = start; i < start + count; i++) {
+                            changedLines.add(i);
+                        }
+                    }
+                }
+                if (changedLines.size > 0)
+                    changedLinesByFile.set(file, changedLines);
+            }
+            catch { /* file may not exist at ref */ }
+        }
         const lines = [`${changedFiles.length} changed files:\n`];
         let totalAffected = 0;
+        let totalChanged = 0;
         for (const file of changedFiles) {
             const syms = db.getSymbolsByFile(file);
             if (syms.length === 0) {
                 lines.push(`${file}: (not indexed)`);
                 continue;
             }
-            lines.push(`${file}: ${syms.length} symbols`);
-            for (const sym of syms) {
+            const changedLines = changedLinesByFile.get(file);
+            // Filter to only symbols whose line range overlaps with changed lines
+            const changedSyms = changedLines
+                ? syms.filter(s => {
+                    for (let line = s.startLine; line <= s.endLine; line++) {
+                        if (changedLines.has(line))
+                            return true;
+                    }
+                    return false;
+                })
+                : syms; // fallback: no line-level diff available, report all
+            if (changedSyms.length === 0 && changedLines) {
+                // File changed but no symbols affected (e.g. whitespace, imports only)
+                lines.push(`${file}: (symbols unchanged)`);
+                continue;
+            }
+            const displaySyms = changedSyms.length > 0 ? changedSyms : syms;
+            const unchangedCount = changedSyms.length > 0 ? syms.length - changedSyms.length : 0;
+            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);
+                totalChanged++;
                 if (upstream.length > 0) {
-                    lines.push(`  ${sym.name} [${sym.kind}] → ${upstream.length} direct dependents`);
+                    lines.push(`  ${sym.name} [${sym.kind}] :${sym.startLine} → ${upstream.length} direct dependents`);
                     totalAffected += upstream.length;
                 }
+                else {
+                    lines.push(`  ${sym.name} [${sym.kind}] :${sym.startLine}`);
+                }
             }
         }
-        lines.push(`\nTotal direct dependents affected: ${totalAffected}`);
+        lines.push(`\nTotal changed symbols: ${totalChanged}`);
+        lines.push(`Total direct dependents affected: ${totalAffected}`);
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: explain_relationship ──
@@ -854,6 +985,20 @@ export function createMcpServer(rootPath) {
                 lines.push(`${sym.name} [${sym.kind}] L${sym.startLine}-${sym.endLine}${exp} ← ${incoming.length} refs, → ${outgoing.length} deps`);
             }
         }
+        // File-path auto-suggest: domain hint
+        const parts = file.replace(/\\/g, '/').split('/');
+        let areaName = 'root';
+        if (parts.length > 1) {
+            if (parts[0] === 'src') {
+                areaName = parts.length > 2 ? parts[1] : 'root';
+            }
+            else {
+                areaName = parts[0];
+            }
+        }
+        if (areaName !== 'root') {
+            lines.push(`\n💡 This file is in the '${areaName}' domain. Load skill 'milens-${areaName}' for key symbols and dependencies.`);
+        }
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: get_type_hierarchy ──
@@ -890,7 +1035,7 @@ export function createMcpServer(rootPath) {
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: edit_check ──
-    server.tool('edit_check', 'Pre-edit safety check: callers, export status, re-export chains, ⚠ warnings. Focused for editing intent — no downstream deps, no outgoing calls. Use BEFORE modifying a symbol.', {
+    server.tool('edit_check', 'Fast pre-edit safety. Shows callers, export status, re-export chains, test coverage, and ⚠ warnings. Use BEFORE modifying any function/class/method — catches hidden risks you would miss.', {
         name: z.string().describe('Symbol name to check before editing'),
         repo: z.string().optional(),
     }, async ({ name, repo }) => {
@@ -959,6 +1104,95 @@ export function createMcpServer(rootPath) {
         }
         return { content: [{ type: 'text', text: sections.join('\n') }] };
     });
+    // ── Tool: guard_edit_check ──
+    server.tool('guard_edit_check', 'HARD pre-edit safety gate. Call BEFORE every edit operation — tracks checks for session audit. If dependents > 5, returns BLOCKED status requiring explicit confirmation. Combines edit_check with enforcement tracking.', {
+        name: z.string().describe('Symbol name to check before editing'),
+        repo: z.string().optional(),
+        session_id: z.string().optional().describe('Session ID for audit tracking'),
+        confirm: z.string().optional().describe('Type "I understand the risk" to bypass a BLOCKED result'),
+    }, async ({ name, repo, session_id, confirm }) => {
+        const { db, root } = getDb(repo);
+        const symbols = db.findSymbolByName(name);
+        const sections = [];
+        if (symbols.length === 0) {
+            return { content: [{ type: 'text', text: `"${name}" not found in index. Try \`grep\` to find it in templates/docs first.` }] };
+        }
+        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;
+            if (session_id)
+                guard.recordCheck(session_id, name);
+            // Hard stop: if > 5 non-test dependents and no confirmation
+            if (depsCount > 5 && confirm !== 'I understand the risk') {
+                sections.push(`⚠️ BLOCKED: ${name} has ${depsCount} non-test dependents (>5 threshold).`);
+                sections.push(`Direct callers (${incoming.length} total):`);
+                for (const l of incoming) {
+                    const from = db.findSymbolById(l.fromId);
+                    sections.push(`  ${l.type}: ${from ? fmtSymbol(from) : l.fromId}`);
+                }
+                sections.push('');
+                sections.push(`To proceed, re-call with confirm: "I understand the risk"`);
+                sections.push(`Or: run \`impact({target: "${name}", depth: 2})\` to see full blast radius.`);
+            }
+            else {
+                // Safe to edit or explicitly confirmed
+                const status = depsCount > 5 ? '⚠️ CONFIRMED (high risk)' : '✅ Safe to edit';
+                sections.push(`${status} — ${depsCount} non-test dependents`);
+                if (incoming.length > 0) {
+                    sections.push(`callers (${incoming.length}):`);
+                    for (const l of incoming) {
+                        const from = db.findSymbolById(l.fromId);
+                        sections.push(`  ${l.type}: ${from ? fmtSymbol(from) : l.fromId}`);
+                    }
+                }
+                else {
+                    sections.push(`callers: none`);
+                }
+                // Export chain
+                const grepMatches = grepFiles(root, name, { maxResults: 5, includePattern: '**/index.{ts,js,mjs}' });
+                const reExportMatches = grepMatches.filter(m => /export\s*\{[^}]*/.test(m.text) && m.text.includes('from'));
+                if (reExportMatches.length > 0) {
+                    sections.push(`re-exported via:`);
+                    for (const m of reExportMatches) {
+                        sections.push(`  ${m.file}:${m.line}`);
+                    }
+                }
+                // Heritage
+                const descendants = db.getTypeHierarchy(sym.id).descendants;
+                if (descendants.length > 0) {
+                    sections.push(`⚠ inherited by ${descendants.length} types:`);
+                    for (const { symbol: d } of descendants) {
+                        sections.push(`  ${fmtSymbol(d)}`);
+                    }
+                }
+                // Test coverage
+                const testRefs = incoming.filter(l => {
+                    const from = db.findSymbolById(l.fromId);
+                    return from && isTestFilePath(from.filePath);
+                });
+                if (testRefs.length > 0) {
+                    const testFiles = [...new Set(testRefs.map(l => {
+                            const from = db.findSymbolById(l.fromId);
+                            return from?.filePath;
+                        }).filter(Boolean))];
+                    sections.push(`✓ tested from: ${testFiles.join(', ')}`);
+                }
+                else if (sym.exported) {
+                    sections.push(`⚠ no test coverage for this exported symbol`);
+                }
+            }
+        }
+        // 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`);
+        }
+        return { content: [{ type: 'text', text: sections.join('\n') }] };
+    });
     // ── Tool: trace ──
     server.tool('trace', 'Trace execution flow: find call chains from entrypoints to a target symbol, or from a symbol downstream. Shows HOW code gets executed.', {
         name: z.string().describe('Symbol name to trace'),
@@ -1336,7 +1570,7 @@ export function createMcpServer(rootPath) {
         }
     });
     // ═══ codebase_summary ═══
-    server.tool('codebase_summary', 'Compact ~500 token codebase overview: domains, top hubs, test coverage, annotations count. Use at the start of every session.', { repo: z.string().optional() }, async ({ repo }) => {
+    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();
         const lines = [
@@ -1366,43 +1600,23 @@ export function createMcpServer(rootPath) {
     // ═══ 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);
-        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) {
+        const result = reviewPr(db, root, ref);
+        if (result.changedFiles.length === 0) {
             return { content: [{ type: 'text', text: 'No changed files detected.' }] };
         }
         const allAffected = [];
-        for (const file of changedFiles) {
-            const syms = db.getSymbolsByFile(file);
-            if (syms.length === 0)
-                continue;
-            for (const sym of syms) {
-                const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
-                const depsCount = incoming.length;
-                const heat = sym.heat ?? 0;
-                const hasTest = db.getSymbolTestCoverage(sym.id);
-                const score = Math.round((heat / 100) * 40 + Math.min(depsCount / 10, 1) * 35 + (hasTest ? 0 : 25));
-                let level = 'LOW';
-                if (score > 75)
-                    level = 'CRITICAL';
-                else if (score > 50)
-                    level = 'HIGH';
-                else if (score > 25)
-                    level = 'MEDIUM';
-                allAffected.push({ symbol: sym.name, kind: sym.kind, file: sym.filePath, heat, dependents: depsCount, hasTest, riskScore: score, riskLevel: level });
-            }
-        }
-        allAffected.sort((a, b) => b.riskScore - a.riskScore);
+        for (const s of result.symbols) {
+            allAffected.push({
+                symbol: s.symbol.name, kind: s.symbol.kind, file: s.symbol.filePath,
+                heat: s.symbol.heat ?? 0, dependents: s.dependents,
+                hasTest: s.tested, riskScore: s.riskScore, riskLevel: s.riskLevel,
+            });
+        }
         const summary = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
         for (const a of allAffected)
             summary[a.riskLevel]++;
         const lines = [`PR Risk Assessment (vs ${ref}):\n`];
-        lines.push(`${changedFiles.length} changed files, ${allAffected.length} affected symbols\n`);
+        lines.push(`${result.changedFiles.length} changed files, ${allAffected.length} affected symbols\n`);
         for (const a of allAffected.slice(0, 30)) {
             lines.push(`  ${a.symbol} [${a.kind}] ${a.file} — heat:${a.heat} deps:${a.dependents} test:${a.hasTest ? 'yes' : 'no'} → ${a.riskLevel}(${a.riskScore})`);
         }
@@ -1539,10 +1753,20 @@ export function createMcpServer(rootPath) {
     });
     // ═══ 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 } = getDb();
+        const { db, root, dbPath } = getDb();
         const store = new AnnotationStore(db.connection);
         const sessionId = store.sessionStart(agent);
-        return { content: [{ type: 'text', text: `Session started: ${sessionId}\nAgent: ${agent}\nUse this ID with annotate() and session_end().` }] };
+        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 }) => {
@@ -1569,11 +1793,35 @@ export function createMcpServer(rootPath) {
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ═══ session_end ═══
-    server.tool('session_end', 'End a session and record its stats. 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 } = getDb();
+    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);
-        return { content: [{ type: 'text', text: `Session ended: ${session_id}\nStatus: ${status}\nAnnotations: ${summary.annotationCount}` }] };
+        // 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.', {
@@ -1585,6 +1833,33 @@ export function createMcpServer(rootPath) {
         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 ═══
     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);
@@ -1946,18 +2221,320 @@ export function createMcpServer(rootPath) {
                 }],
         };
     });
+    // ═══ 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"),
+        repo: z.string().optional(),
+    }, async ({ name, action, repo }) => {
+        const { db, root, dbPath } = getDb(repo);
+        const orchestrator = new Orchestrator({ rootPath: root, dbPath });
+        try {
+            if (action === 'snapshot') {
+                const snap = orchestrator.snapshot(name, db);
+                return { content: [{ type: 'text', text: `Snapshot saved for "${name}":\n  Heat: ${snap.heatScore}\n  Dependents: ${snap.dependents.length}\n  Timestamp: ${snap.timestamp}` }] };
+            }
+            const diff = orchestrator.compare(name, db);
+            if (!diff.before) {
+                return { content: [{ type: 'text', text: `No snapshot found for "${name}". Call compare_impact with action: 'snapshot' first.` }] };
+            }
+            const lines = [];
+            lines.push(`Impact diff for "${name}"\n`);
+            lines.push(`Before: ${diff.before.dependents.length} dependents, heat ${diff.heatBefore}`);
+            lines.push(`After:  ${diff.after.dependents.length} dependents, heat ${diff.heatAfter}`);
+            if (diff.newDependents.length > 0) {
+                lines.push(`\n+ ${diff.newDependents.length} new dependents:`);
+                for (const d of diff.newDependents)
+                    lines.push(`  + ${d.name} in ${d.filePath}`);
+            }
+            if (diff.removedDependents.length > 0) {
+                lines.push(`\n- ${diff.removedDependents.length} removed dependents:`);
+                for (const d of diff.removedDependents)
+                    lines.push(`  - ${d.name} in ${d.filePath}`);
+            }
+            if (diff.heatChanged) {
+                lines.push(`\nHeat changed: ${diff.heatBefore} → ${diff.heatAfter} (${diff.heatAfter > diff.heatBefore ? 'increased' : 'decreased'})`);
+            }
+            if (diff.newDependents.length === 0 && diff.removedDependents.length === 0 && !diff.heatChanged) {
+                lines.push(`\nNo changes detected in impact graph.`);
+            }
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+        finally {
+            db.close();
+        }
+    });
+    // ═══ 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);
+        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: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `I need to safely remove dead code. Follow this workflow:\n\n` +
+                        `1. Run \`find_dead_code()\` to list symbols with zero incoming references\n` +
+                        `2. For each candidate symbol, verify it's truly unused:\n` +
+                        `   a. Run \`context({name: "symbolName"})\` to check for hidden callers\n` +
+                        `   b. Run \`grep({pattern: "symbolName"})\` to find all text references (templates, configs, docs, routes)\n` +
+                        `   c. Run \`impact({target: "symbolName", direction: "downstream"})\` to confirm no downstream impact\n` +
+                        `3. If neither context nor grep finds references → safe to remove\n` +
+                        `4. Before removal: \`edit_check({name: "symbolName"})\` for final safety check\n` +
+                        `5. Remove the symbol and its definition\n` +
+                        `6. Run test suite to verify no regressions\n` +
+                        `7. Report: which symbols removed, which skipped (and why)\n\n` +
+                        `IMPORTANT: Never auto-remove. Always ask for confirmation before deleting each symbol.` +
+                        (repo ? `\nRepo: ${repo}` : ''),
+                },
+            }],
+    }));
     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);
     const transport = new StdioServerTransport();
+    // Start file watcher for auto re-index (respects hook config)
+    let watcher = null;
+    if (rootPath) {
+        const { RepoRegistry } = await import('../store/registry.js');
+        const { HookManager } = await import('./hooks.js');
+        const reg = new RepoRegistry();
+        const entry = reg.findByRoot(rootPath);
+        if (entry) {
+            const hookMgr = new HookManager();
+            const hookConfig = hookMgr.loadConfig(rootPath);
+            if (hookConfig.enabled && hookConfig.onFileChange) {
+                watcher = new FileWatcher({
+                    rootPath,
+                    dbPath: entry.dbPath,
+                    logger: (_level, msg) => {
+                        server.server.sendLoggingMessage({ level: 'info', data: msg });
+                    },
+                });
+                watcher.start();
+            }
+        }
+    }
+    // Cleanup on exit
+    const cleanup = () => {
+        if (watcher)
+            watcher.stop();
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
     await server.connect(transport);
 }
 // ── Transport: HTTP (Streamable) ──
 export async function startHttp(port, rootPath) {
     const server = createMcpServer(rootPath);
     const sessions = new Map();
+    // Start file watcher for auto re-index (respects hook config)
+    let watcher = null;
+    if (rootPath) {
+        const { RepoRegistry } = await import('../store/registry.js');
+        const { HookManager } = await import('./hooks.js');
+        const reg = new RepoRegistry();
+        const entry = reg.findByRoot(rootPath);
+        if (entry) {
+            const hookMgr = new HookManager();
+            const hookConfig = hookMgr.loadConfig(rootPath);
+            if (hookConfig.enabled && hookConfig.onFileChange) {
+                watcher = new FileWatcher({
+                    rootPath,
+                    dbPath: entry.dbPath,
+                    logger: (_level, msg) => {
+                        server.server.sendLoggingMessage({ level: 'info', data: msg });
+                    },
+                });
+                watcher.start();
+            }
+        }
+    }
+    // Cleanup on exit
+    const cleanup = () => {
+        if (watcher)
+            watcher.stop();
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
     // Evict idle sessions every 5 minutes
     const SESSION_TTL = 30 * 60_000; // 30 minutes
     const evictTimer = setInterval(() => {