grepmax 0.23.0 → 0.25.0

package/dist/commands/mcp.js

@@ -53,11 +53,18 @@ exports.mcp = void 0;
 exports.toStringArray = toStringArray;
 exports.ok = ok;
 exports.err = err;
+exports.isExplicitCrossProjectSearch = isExplicitCrossProjectSearch;
+exports.resolveMcpProject = resolveMcpProject;
+exports.containMcpTarget = containMcpTarget;
+exports.mcpRootPrefix = mcpRootPrefix;
+exports.resolveMcpSourceFile = resolveMcpSourceFile;
 exports.searchResultPath = searchResultPath;
 exports.searchResultStartLine = searchResultStartLine;
 exports.searchResultEndLine = searchResultEndLine;
 exports.filterMcpSearchResults = filterMcpSearchResults;
 exports.formatMcpPointerSearchResults = formatMcpPointerSearchResults;
+exports.formatMcpSurprisingConnections = formatMcpSurprisingConnections;
+exports.mcpLogQuery = mcpLogQuery;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
@@ -65,8 +72,10 @@ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const commander_1 = require("commander");
 const zod_1 = require("zod");
 const config_1 = require("../config");
+const surprising_connections_1 = require("../lib/analysis/surprising-connections");
 const languages_1 = require("../lib/core/languages");
 const graph_builder_1 = require("../lib/graph/graph-builder");
+const embedding_status_1 = require("../lib/index/embedding-status");
 const index_config_1 = require("../lib/index/index-config");
 const syncer_1 = require("../lib/index/syncer");
 const agent_search_formatter_1 = require("../lib/output/agent-search-formatter");
@@ -77,12 +86,15 @@ const skeletonizer_1 = require("../lib/skeleton/skeletonizer");
 const symbol_extractor_1 = require("../lib/skeleton/symbol-extractor");
 const meta_cache_1 = require("../lib/store/meta-cache");
 const vector_db_1 = require("../lib/store/vector-db");
+const cross_project_1 = require("../lib/utils/cross-project");
 const file_utils_1 = require("../lib/utils/file-utils");
 const filter_builder_1 = require("../lib/utils/filter-builder");
 const format_helpers_1 = require("../lib/utils/format-helpers");
 const import_extractor_1 = require("../lib/utils/import-extractor");
+const path_containment_1 = require("../lib/utils/path-containment");
 const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
+const scope_filter_1 = require("../lib/utils/scope-filter");
 const watcher_launcher_1 = require("../lib/utils/watcher-launcher");
 const watcher_store_1 = require("../lib/utils/watcher-store");
 const audit_1 = require("./audit");
@@ -109,6 +121,51 @@ function ok(text) {
 function err(text) {
     return { content: [{ type: "text", text }], isError: true };
 }
+function isExplicitCrossProjectSearch(args, isSearchAll = false) {
+    return (isSearchAll ||
+        args.scope === "all" ||
+        (typeof args.projects === "string" && args.projects.trim() !== "") ||
+        (typeof args.exclude_projects === "string" &&
+            args.exclude_projects.trim() !== ""));
+}
+function resolveMcpProject(requested, currentRoot, projects = (0, project_registry_1.listProjects)()) {
+    if (typeof requested === "string" && requested.trim()) {
+        const value = requested.trim();
+        const byName = projects.filter((project) => project.name === value);
+        if (byName.length === 1)
+            return byName[0];
+        if (byName.length > 1)
+            return undefined;
+        const resolved = path.resolve(value);
+        return projects.find((project) => path.resolve(project.root) === resolved);
+    }
+    const resolvedCurrent = path.resolve(currentRoot);
+    const exact = projects.find((project) => path.resolve(project.root) === resolvedCurrent);
+    if (exact)
+        return exact;
+    return projects
+        .filter((project) => (0, path_containment_1.isPathWithin)(project.root, resolvedCurrent))
+        .sort((a, b) => b.root.length - a.root.length)[0];
+}
+function containMcpTarget(root, target) {
+    return path.isAbsolute(target) ||
+        target.includes("/") ||
+        target.includes("\\")
+        ? (0, path_containment_1.resolveContainedPath)(root, target)
+        : target;
+}
+function mcpRootPrefix(root) {
+    return root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+}
+function resolveMcpSourceFile(roots, candidate) {
+    for (const root of roots) {
+        try {
+            return (0, path_containment_1.resolveContainedFile)(root, candidate);
+        }
+        catch (_a) { }
+    }
+    return undefined;
+}
 function chunkAbsPath(chunk) {
     const metadata = chunk.metadata;
     return String(chunk.path || (metadata === null || metadata === void 0 ? void 0 : metadata.path) || "");
@@ -171,6 +228,59 @@ function formatMcpPointerSearchResults(data, displayRoot, options = {}) {
         query: options.query,
     });
 }
+function formatMcpSurprisingConnections(result, top = 10) {
+    const { summary, findings } = result;
+    const lines = [
+        [
+            "summary",
+            `sampled=${summary.sampledAnchors}`,
+            `code=${summary.codeRows}`,
+            `pairs=${summary.acceptedPairs}`,
+            `file_pairs=${summary.acceptedFilePairs}`,
+            `score_p90=${summary.actionabilityScore.p90}`,
+        ].join("\t"),
+    ];
+    for (const finding of findings.slice(0, top)) {
+        const pair = finding.representative;
+        lines.push([
+            "surprise",
+            finding.score.toFixed(3),
+            finding.maxSimilarity.toFixed(3),
+            String(finding.pairCount),
+            finding.fileA,
+            finding.fileB,
+            (0, surprising_connections_1.lineLabel)(pair.source),
+            (0, surprising_connections_1.lineLabel)(pair.target),
+            finding.reasons.join(","),
+            `buckets=${(0, surprising_connections_1.findingBucketLabel)(finding, summary.options.dirDepth)}`,
+            `top_sims=${finding.topSimilarities.join(",")}`,
+            `penalties=${(0, surprising_connections_1.formatPenaltySummary)(pair.scoreParts)}`,
+            `next=${(0, surprising_connections_1.skeletonHint)(finding)}`,
+        ].join("\t"));
+    }
+    if (findings.length === 0)
+        lines.push("none");
+    return lines.join("\n");
+}
+function mcpLogQuery(name, args) {
+    var _a, _b;
+    const direct = (_b = (_a = args.query) !== null && _a !== void 0 ? _a : args.symbol) !== null && _b !== void 0 ? _b : args.target;
+    if (direct !== undefined && direct !== null && String(direct) !== "") {
+        return String(direct);
+    }
+    if (name === "surprising_connections") {
+        const parts = [
+            "surprising_connections",
+            typeof args.root === "string" && args.root ? `root=${args.root}` : "",
+            typeof args.in === "string" && args.in ? `in=${args.in}` : "",
+            typeof args.exclude === "string" && args.exclude
+                ? `exclude=${args.exclude}`
+                : "",
+        ].filter(Boolean);
+        return parts.join(" ");
+    }
+    return "";
+}
 // ---------------------------------------------------------------------------
 // Command
 // ---------------------------------------------------------------------------
@@ -251,12 +361,16 @@ exports.mcp = new commander_1.Command("mcp")
         });
     }
     // --- Background watcher ---
-    function ensureWatcher() {
+    function ensureWatcher(root) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             try {
-                const result = yield (0, watcher_launcher_1.launchWatcher)(projectRoot);
+                const watchRoot = root !== null && root !== void 0 ? root : (_a = resolveMcpProject(undefined, projectRoot)) === null || _a === void 0 ? void 0 : _a.root;
+                if (!watchRoot)
+                    return;
+                const result = yield (0, watcher_launcher_1.launchWatcher)(watchRoot);
                 if (result.ok && !result.reused) {
-                    console.log(`[MCP] Started background watcher for ${projectRoot} (PID: ${result.pid})`);
+                    console.log(`[MCP] Started background watcher for ${watchRoot} (PID: ${result.pid})`);
                 }
             }
             catch (err) {
@@ -264,66 +378,78 @@ exports.mcp = new commander_1.Command("mcp")
             }
         });
     }
+    // Resolve the registered project this server scopes to. The server pins to
+    // its launch cwd (findProjectRoot, .git-only), but a registered project may
+    // be an umbrella with no .git of its own — so a session launched in a
+    // subdirectory resolves to a path that isn't the registered root. Prefer an
+    // exact registry match; otherwise walk the registry for an ancestor that
+    // covers the cwd, and scope to it instead of silently widening to the whole
+    // index. `root` is the registered project root to scope to.
+    function resolveRegisteredProject(requested) {
+        const project = resolveMcpProject(requested, projectRoot);
+        if (project)
+            return { proj: project, root: project.root };
+        return { proj: undefined, root: projectRoot };
+    }
     // --- Tool handlers ---
     function handleSemanticSearch(args_1) {
         return __awaiter(this, arguments, void 0, function* (args, isSearchAll = false) {
+            var _a, _b;
             const query = String(args.query || "");
             if (!query)
                 return err("Missing required parameter: query");
-            let searchAll = isSearchAll || args.scope === "all";
+            const searchAll = isExplicitCrossProjectSearch(args, isSearchAll);
             const limit = Math.min(Math.max(Number(args.limit) || 3, 1), 50);
-            ensureWatcher();
             // Project resolution. The server is pinned to whatever cwd it launched in
-            // (resolved once at startup). When that cwd ISN'T an indexed project and
-            // the caller hasn't pinned an explicit --root, fall back to cross-project
-            // search instead of dead-ending — this is what makes the server usable
-            // from a session that isn't sitting inside a registered repo.
-            let scopeNote = "";
-            const proj = (0, project_registry_1.getProject)(projectRoot);
-            if (!proj && typeof args.root !== "string") {
-                const indexed = (0, project_registry_1.listProjects)().filter((p) => { var _a; return p.status !== "pending" && ((_a = p.chunkCount) !== null && _a !== void 0 ? _a : 0) > 0; });
-                if (indexed.length === 0) {
-                    return err("No indexed projects yet. cd into a repo and run `gmax add` to index it first.");
-                }
-                searchAll = true;
-                scopeNote =
-                    `Note: ${path.basename(projectRoot)}/ isn't an indexed gmax project — ` +
-                        `searching all ${indexed.length} indexed project(s). ` +
-                        `Call list_projects to see them, then pass projects:"name" to narrow.`;
-            }
-            else if (!proj) {
-                return err("Project not added to gmax yet. Run `gmax add` to index it first.");
-            }
-            else if (proj.status === "pending" || proj.chunkCount === 0) {
-                return err("Project not indexed yet. Run `gmax add` to index it first.");
+            // (resolved once at startup). Resolve that cwd to its registered project —
+            // exact match, or a registered ancestor when the cwd is a subdirectory of
+            // an umbrella project. Searches scope to `resolvedRoot`.
+            const { proj, root: resolvedRoot } = resolveRegisteredProject(args.root);
+            if (searchAll &&
+                (args.root !== undefined ||
+                    args.path !== undefined ||
+                    args.exclude !== undefined)) {
+                return err("root, path, and exclude are single-project filters; omit them for cross-project search.");
+            }
+            // Cross-project search (the whole index) is opt-in: it happens only when
+            // the caller passes scope:"all" or projects:"…". Otherwise we require a
+            // resolved project and error loudly when there isn't one — never silently
+            // widen a scoped query to every indexed project.
+            if (!searchAll) {
+                if (!proj) {
+                    if (typeof args.root === "string") {
+                        return err("Project not added to gmax yet. Run `gmax add` to index it first.");
+                    }
+                    const indexed = (0, project_registry_1.listProjects)().filter((p) => { var _a; return p.status !== "pending" && ((_a = p.chunkCount) !== null && _a !== void 0 ? _a : 0) > 0; });
+                    if (indexed.length === 0) {
+                        return err("No indexed projects yet. cd into a repo and run `gmax add` to index it first.");
+                    }
+                    return err(`${path.basename(projectRoot)}/ isn't an indexed gmax project. ` +
+                        `Pass scope:"all" to search all ${indexed.length} indexed project(s), ` +
+                        `projects:"name" to target specific ones, or cd into an indexed project.`);
+                }
+                if (proj.status === "pending" || proj.chunkCount === 0) {
+                    return err("Project not indexed yet. Run `gmax add` to index it first.");
+                }
+                void ensureWatcher(resolvedRoot);
             }
             try {
-                const searcher = getSearcher();
                 // Determine path prefix and display root for relative paths
                 let pathPrefix;
-                let displayRoot = projectRoot;
+                const displayRoot = resolvedRoot;
+                let projectScope;
                 if (!searchAll) {
-                    const searchRoot = typeof args.root === "string"
-                        ? path.resolve(args.root)
-                        : path.resolve(projectRoot);
-                    if (typeof args.root === "string" && !fs.existsSync(searchRoot)) {
-                        return err(`Directory not found: ${args.root}`);
-                    }
-                    displayRoot = searchRoot;
-                    pathPrefix = searchRoot.endsWith("/") ? searchRoot : `${searchRoot}/`;
-                    if (typeof args.path === "string") {
-                        pathPrefix = path.join(searchRoot, args.path);
-                        if (!pathPrefix.endsWith("/"))
-                            pathPrefix += "/";
-                    }
+                    projectScope = (0, scope_filter_1.resolveScope)({
+                        projectRoot: resolvedRoot,
+                        in: typeof args.path === "string" ? args.path : undefined,
+                        exclude: typeof args.exclude === "string" ? args.exclude : undefined,
+                    });
+                    pathPrefix = projectScope.pathPrefix;
                 }
                 const filters = {};
                 if (typeof args.file === "string" && args.file) {
                     filters.file = args.file;
                 }
-                if (typeof args.exclude === "string" && args.exclude) {
-                    filters.exclude = args.exclude;
-                }
                 if (typeof args.language === "string" && args.language) {
                     filters.language = args.language;
                 }
@@ -331,29 +457,32 @@ exports.mcp = new commander_1.Command("mcp")
                     filters.role = args.role;
                 }
                 if (searchAll) {
-                    const allProjects = (0, project_registry_1.listProjects)();
-                    if (typeof args.projects === "string" && args.projects) {
-                        const names = args.projects.split(",").map((s) => s.trim());
-                        const roots = names
-                            .map((n) => { var _a; return (_a = allProjects.find((p) => p.name === n)) === null || _a === void 0 ? void 0 : _a.root; })
-                            .filter(Boolean);
-                        if (roots.length > 0) {
-                            filters.project_roots = roots.join(",");
-                        }
+                    const crossScope = (0, cross_project_1.resolveCrossProjectScope)({
+                        allProjects: searchAll &&
+                            !(typeof args.projects === "string" && args.projects.trim()),
+                        projects: typeof args.projects === "string" ? args.projects : undefined,
+                        excludeProjects: typeof args.exclude_projects === "string"
+                            ? args.exclude_projects
+                            : undefined,
+                    });
+                    if (crossScope.projectRoots.length === 0) {
+                        return err("No matching indexed projects.");
                     }
-                    if (typeof args.exclude_projects === "string" &&
-                        args.exclude_projects) {
-                        const names = args.exclude_projects
-                            .split(",")
-                            .map((s) => s.trim());
-                        const roots = names
-                            .map((n) => { var _a; return (_a = allProjects.find((p) => p.name === n)) === null || _a === void 0 ? void 0 : _a.root; })
-                            .filter(Boolean);
-                        if (roots.length > 0) {
-                            filters.exclude_project_roots = roots.join(",");
-                        }
+                    filters.projectRoots = crossScope.projectRoots;
+                }
+                else if (projectScope) {
+                    if (projectScope.inPrefixes.length > 0) {
+                        filters.inPrefixes = projectScope.inPrefixes;
+                    }
+                    if (projectScope.excludePrefixes.length > 0) {
+                        filters.excludePrefixes = projectScope.excludePrefixes;
                     }
                 }
+                const selectedRoots = searchAll
+                    ? new Set((_a = filters.projectRoots) !== null && _a !== void 0 ? _a : [])
+                    : new Set([resolvedRoot]);
+                (0, embedding_status_1.assertEmbeddingSearchCompatible)((0, project_registry_1.listProjects)().filter((project) => selectedRoots.has(project.root)), (0, index_config_1.readGlobalConfig)());
+                const searcher = getSearcher();
                 // Aider-style seeding: the agent passes its open files / discussed
                 // symbols; the searcher biases candidate generation toward them.
                 const parseSeedList = (v) => {
@@ -372,11 +501,18 @@ exports.mcp = new commander_1.Command("mcp")
                     ? { files: seedFiles, symbols: seedSymbols }
                     : undefined;
                 const result = yield searcher.search(query, limit, { rerank: process.env.GMAX_RERANK === "1", seeds }, Object.keys(filters).length > 0 ? filters : undefined, pathPrefix);
-                // Prepend the scope-fallback note (if any) + searcher warnings to
-                // whatever body we return, so the agent learns it searched all projects.
+                const allowedRoots = searchAll
+                    ? ((_b = filters.projectRoots) !== null && _b !== void 0 ? _b : [])
+                    : [resolvedRoot];
+                result.data = result.data.filter((chunk) => {
+                    const candidate = chunkAbsPath(chunk);
+                    return (candidate.length > 0 &&
+                        allowedRoots.some((root) => (0, path_containment_1.isPathWithin)(root, candidate)));
+                });
+                // Prepend any searcher warnings to whatever body we return.
                 const prefixNotes = (body) => {
                     var _a;
-                    const notes = [scopeNote, ...((_a = result.warnings) !== null && _a !== void 0 ? _a : [])].filter(Boolean);
+                    const notes = ((_a = result.warnings) !== null && _a !== void 0 ? _a : []).filter(Boolean);
                     return notes.length ? `${notes.join("\n")}\n\n${body}` : body;
                 };
                 if (!result.data || result.data.length === 0) {
@@ -393,8 +529,11 @@ exports.mcp = new commander_1.Command("mcp")
                     var _a;
                     if (!includeImports || !absPath)
                         return "";
+                    const sourcePath = resolveMcpSourceFile(allowedRoots, absPath);
+                    if (!sourcePath)
+                        return "";
                     if (!importCache.has(absPath)) {
-                        importCache.set(absPath, (0, import_extractor_1.extractImports)(absPath));
+                        importCache.set(absPath, (0, import_extractor_1.extractImports)(sourcePath));
                     }
                     return (_a = importCache.get(absPath)) !== null && _a !== void 0 ? _a : "";
                 };
@@ -438,7 +577,10 @@ exports.mcp = new commander_1.Command("mcp")
                         if (contextN > 0 && absPath) {
                             // Read surrounding context from file
                             try {
-                                const fileContent = fs.readFileSync(absPath, "utf-8");
+                                const sourcePath = resolveMcpSourceFile(allowedRoots, absPath);
+                                if (!sourcePath)
+                                    throw new Error("indexed path is outside scope");
+                                const fileContent = fs.readFileSync(sourcePath, "utf-8");
                                 const fileLines = fileContent.split("\n");
                                 const ctxStart = Math.max(0, startLine - contextN);
                                 const ctxEnd = Math.min(fileLines.length, endLine + 1 + contextN);
@@ -503,7 +645,7 @@ exports.mcp = new commander_1.Command("mcp")
                         const regex = new RegExp(namePattern, "i");
                         results = results.filter((r) => r.symbols.some((s) => regex.test(s)));
                     }
-                    catch (_a) {
+                    catch (_c) {
                         // Invalid regex — skip filter
                     }
                 }
@@ -512,19 +654,19 @@ exports.mcp = new commander_1.Command("mcp")
                 if (mode === "symbol" && !searchAll) {
                     try {
                         const db = getVectorDb();
-                        const builder = new graph_builder_1.GraphBuilder(db);
+                        const builder = new graph_builder_1.GraphBuilder(db, resolvedRoot);
                         const graph = yield builder.buildGraph(query);
                         if (graph.center) {
                             const traceLines = ["", "--- Call graph ---"];
-                            const centerRel = graph.center.file.startsWith(projectRoot)
-                                ? graph.center.file.slice(projectRoot.length + 1)
+                            const centerRel = graph.center.file.startsWith(resolvedRoot)
+                                ? graph.center.file.slice(resolvedRoot.length + 1)
                                 : graph.center.file;
                             traceLines.push(`${graph.center.symbol} [${graph.center.role}] ${centerRel}:${graph.center.line + 1}`);
                             if (graph.callers.length > 0) {
                                 traceLines.push("Callers:");
                                 for (const caller of graph.callers) {
-                                    const rel = caller.file.startsWith(projectRoot)
-                                        ? caller.file.slice(projectRoot.length + 1)
+                                    const rel = caller.file.startsWith(resolvedRoot)
+                                        ? caller.file.slice(resolvedRoot.length + 1)
                                         : caller.file;
                                     traceLines.push(`  <- ${caller.symbol} ${rel}:${caller.line + 1}`);
                                 }
@@ -533,8 +675,8 @@ exports.mcp = new commander_1.Command("mcp")
                                 traceLines.push("Calls:");
                                 for (const callee of graph.callees.slice(0, 15)) {
                                     if (callee.file) {
-                                        const rel = callee.file.startsWith(projectRoot)
-                                            ? callee.file.slice(projectRoot.length + 1)
+                                        const rel = callee.file.startsWith(resolvedRoot)
+                                            ? callee.file.slice(resolvedRoot.length + 1)
                                             : callee.file;
                                         traceLines.push(`  -> ${callee.symbol} ${rel}:${callee.line + 1}`);
                                     }
@@ -546,7 +688,7 @@ exports.mcp = new commander_1.Command("mcp")
                             output += `\n${traceLines.join("\n")}`;
                         }
                     }
-                    catch (_b) {
+                    catch (_d) {
                         // Trace failed — return search results without trace
                     }
                 }
@@ -560,10 +702,14 @@ exports.mcp = new commander_1.Command("mcp")
     }
     function handleCodeSkeleton(args) {
         return __awaiter(this, void 0, void 0, function* () {
-            ensureWatcher();
             const target = String(args.target || "");
             if (!target)
                 return err("Missing required parameter: target");
+            const { proj, root } = resolveRegisteredProject();
+            if (!proj) {
+                return err("Project not added to gmax yet. Run `gmax add` to index it first.");
+            }
+            void ensureWatcher(root);
             const fileLimit = Math.min(Math.max(Number(args.limit) || 10, 1), 20);
             // Determine targets: comma-separated, directory, or single file
             let targets;
@@ -574,12 +720,14 @@ exports.mcp = new commander_1.Command("mcp")
                     .filter(Boolean);
             }
             else {
-                const absPath = path.resolve(projectRoot, target);
+                const absPath = (0, path_containment_1.resolveContainedPath)(root, target, {
+                    verifyExistingTarget: true,
+                });
                 if (fs.existsSync(absPath) && fs.statSync(absPath).isDirectory()) {
                     const entries = fs.readdirSync(absPath, { withFileTypes: true });
                     targets = entries
                         .filter((e) => e.isFile() && (0, file_utils_1.isIndexableFile)(path.join(absPath, e.name)))
-                        .map((e) => path.relative(projectRoot, path.join(absPath, e.name)))
+                        .map((e) => path.relative(root, path.join(absPath, e.name)))
                         .slice(0, fileLimit);
                     if (targets.length === 0) {
                         return err(`No indexable files found in ${target}`);
@@ -595,8 +743,11 @@ exports.mcp = new commander_1.Command("mcp")
             const jsonFiles = [];
             const skel = yield getSkeletonizer();
             for (const t of targets) {
-                const absPath = path.resolve(projectRoot, t);
-                if (!fs.existsSync(absPath)) {
+                let absPath;
+                try {
+                    absPath = (0, path_containment_1.resolveContainedFile)(root, t);
+                }
+                catch (_a) {
                     if (fmt !== "json")
                         parts.push(`// ${t} — file not found`);
                     continue;
@@ -606,7 +757,7 @@ exports.mcp = new commander_1.Command("mcp")
                 try {
                     sourceContent = fs.readFileSync(absPath, "utf-8");
                 }
-                catch (_a) { }
+                catch (_b) { }
                 let skeleton = "";
                 let language = "";
                 let tokenEstimate = 0;
@@ -619,7 +770,7 @@ exports.mcp = new commander_1.Command("mcp")
                         tokenEstimate = Math.ceil(cached.length / 4);
                     }
                 }
-                catch (_b) { }
+                catch (_c) { }
                 // Generate live if no cache
                 if (!skeleton) {
                     try {
@@ -672,17 +823,17 @@ exports.mcp = new commander_1.Command("mcp")
     }
     function handleTraceCalls(args) {
         return __awaiter(this, void 0, void 0, function* () {
-            ensureWatcher();
             const symbol = String(args.symbol || "");
             if (!symbol)
                 return err("Missing required parameter: symbol");
-            const proj = (0, project_registry_1.getProject)(projectRoot);
+            const { proj, root } = resolveRegisteredProject();
             if (!proj) {
                 return err("Project not added to gmax yet. Run `gmax add` to index it first.");
             }
+            void ensureWatcher(root);
             try {
                 const db = getVectorDb();
-                const builder = new graph_builder_1.GraphBuilder(db);
+                const builder = new graph_builder_1.GraphBuilder(db, root);
                 const depth = Math.min(Math.max(Number(args.depth) || 1, 1), 3);
                 const graph = yield builder.buildGraphMultiHop(symbol, depth);
                 if (!graph.center) {
@@ -699,8 +850,8 @@ exports.mcp = new commander_1.Command("mcp")
                     if (filteredImporters.length > 0) {
                         lines.push("Imported by:");
                         for (const imp of filteredImporters.slice(0, 10)) {
-                            const rel = imp.startsWith(projectRoot)
-                                ? imp.slice(projectRoot.length + 1)
+                            const rel = imp.startsWith(root)
+                                ? imp.slice(root.length + 1)
                                 : imp;
                             lines.push(`  ${rel}`);
                         }
@@ -709,8 +860,8 @@ exports.mcp = new commander_1.Command("mcp")
                 // Callers (recursive tree)
                 function formatCallerTree(trees, indent) {
                     for (const t of trees) {
-                        const rel = t.node.file.startsWith(projectRoot)
-                            ? t.node.file.slice(projectRoot.length + 1)
+                        const rel = t.node.file.startsWith(root)
+                            ? t.node.file.slice(root.length + 1)
                             : t.node.file;
                         const pad = "  ".repeat(indent);
                         lines.push(`${pad}<- ${t.node.symbol} ${rel}:${t.node.line + 1}`);
@@ -729,8 +880,8 @@ exports.mcp = new commander_1.Command("mcp")
                     lines.push("Calls:");
                     for (const callee of graph.callees.slice(0, 15)) {
                         if (callee.file) {
-                            const rel = callee.file.startsWith(projectRoot)
-                                ? callee.file.slice(projectRoot.length + 1)
+                            const rel = callee.file.startsWith(root)
+                                ? callee.file.slice(root.length + 1)
                                 : callee.file;
                             lines.push(`  -> ${callee.symbol} ${rel}:${callee.line + 1}`);
                         }
@@ -760,7 +911,9 @@ exports.mcp = new commander_1.Command("mcp")
             if (!symbol)
                 return err("Missing required parameter: symbol");
             try {
-                const root = typeof args.root === "string" && args.root ? args.root : projectRoot;
+                const { proj, root } = resolveRegisteredProject(args.root);
+                if (!proj)
+                    return err("Project not added to gmax yet.");
                 const db = getVectorDb();
                 const table = yield db.ensureTable();
                 const prefix = root.endsWith("/") ? root : `${root}/`;
@@ -800,7 +953,7 @@ exports.mcp = new commander_1.Command("mcp")
                     return ((ROLE_PRI[String(b.role)] || 0) - (ROLE_PRI[String(a.role)] || 0));
                 });
                 const best = sorted[0];
-                const filePath = String(best.path);
+                const filePath = (0, path_containment_1.resolveContainedFile)(root, String(best.path));
                 const startLine = Number(best.start_line || 0);
                 const endLine = Number(best.end_line || 0);
                 const role = String(best.role || "IMPLEMENTATION");
@@ -851,7 +1004,9 @@ exports.mcp = new commander_1.Command("mcp")
             if (!symbol)
                 return err("Missing required parameter: symbol");
             try {
-                const root = typeof args.root === "string" && args.root ? args.root : projectRoot;
+                const { proj, root } = resolveRegisteredProject(args.root);
+                if (!proj)
+                    return err("Project not added to gmax yet.");
                 const depth = Math.min(Math.max(Number(args.depth || 1), 1), 3);
                 const db = getVectorDb();
                 const { GraphBuilder } = yield Promise.resolve().then(() => __importStar(require("../lib/graph/graph-builder")));
@@ -883,7 +1038,8 @@ exports.mcp = new commander_1.Command("mcp")
                 let sigText = "(source not available)";
                 let bodyLines = 0;
                 try {
-                    const content = fs.readFileSync(center.file, "utf-8");
+                    const centerPath = (0, path_containment_1.resolveContainedFile)(root, center.file);
+                    const content = fs.readFileSync(centerPath, "utf-8");
                     const lines = content.split("\n");
                     const chunk = lines.slice(startLine, endLine + 1);
                     bodyLines = chunk.length;
@@ -982,7 +1138,9 @@ exports.mcp = new commander_1.Command("mcp")
             if (!symbol)
                 return err("Missing required parameter: symbol");
             try {
-                const root = typeof args.root === "string" && args.root ? args.root : projectRoot;
+                const { proj, root } = resolveRegisteredProject(args.root);
+                if (!proj)
+                    return err("Project not added to gmax yet.");
                 const db = getVectorDb();
                 const table = yield db.ensureTable();
                 const prefix = root.endsWith("/") ? root : `${root}/`;
@@ -1027,9 +1185,9 @@ exports.mcp = new commander_1.Command("mcp")
     function handleAudit(args) {
         return __awaiter(this, void 0, void 0, function* () {
             ensureWatcher();
-            const root = typeof args.root === "string" && args.root
-                ? path.resolve(args.root)
-                : projectRoot;
+            const { proj, root } = resolveRegisteredProject(args.root);
+            if (!proj)
+                return err("Project not added to gmax yet.");
             const prefix = root.endsWith("/") ? root : `${root}/`;
             const top = Math.min(Math.max(Number(args.top) || 10, 1), 50);
             try {
@@ -1106,6 +1264,43 @@ exports.mcp = new commander_1.Command("mcp")
             }
         });
     }
+    function handleSurprisingConnections(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            ensureWatcher();
+            if (args.experimental !== true) {
+                return err("surprising_connections is experimental; pass experimental:true.");
+            }
+            const { proj, root } = resolveRegisteredProject(args.root);
+            if (!proj)
+                return err("Project not added to gmax yet.");
+            const top = Math.min(Math.max(Number(args.top) || 10, 1), 100);
+            const sample = Math.min(Math.max(Number(args.sample) || surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.sample, 1), 10000);
+            const neighbors = Math.min(Math.max(Number(args.neighbors) || surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.neighbors, 1), 200);
+            const dirDepth = Math.min(Math.max(Number(args.dir_depth) || surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.dirDepth, 1), 20);
+            const minSimilarity = Math.max(Number(args.min_similarity) || surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.minSimilarity, 0);
+            const maxRows = Math.min(Math.max(Number(args.max_rows) || surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.maxRows, 1), surprising_connections_1.MAX_SURPRISE_ROWS);
+            try {
+                const db = getVectorDb();
+                const table = yield db.ensureTable();
+                const result = yield (0, surprising_connections_1.analyzeSurprisingConnections)(table, root, {
+                    sample,
+                    neighbors,
+                    dirDepth,
+                    minSimilarity,
+                    maxRows,
+                    includeTests: Boolean(args.include_tests),
+                    includeEval: Boolean(args.include_eval),
+                    in: typeof args.in === "string" ? args.in : undefined,
+                    exclude: typeof args.exclude === "string" ? args.exclude : undefined,
+                });
+                return ok(formatMcpSurprisingConnections(result, top));
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return err(`Surprising connections failed: ${msg}`);
+            }
+        });
+    }
     function handleGetNeighbors(args) {
         return __awaiter(this, void 0, void 0, function* () {
             ensureWatcher();
@@ -1115,7 +1310,9 @@ exports.mcp = new commander_1.Command("mcp")
             const direction = args.direction === "callers" ? "callers" : "callees";
             const maxHops = Math.min(Math.max(Number(args.max_hops) || 2, 1), 5);
             try {
-                const root = typeof args.root === "string" && args.root ? args.root : projectRoot;
+                const { proj, root } = resolveRegisteredProject(args.root);
+                if (!proj)
+                    return err("Project not added to gmax yet.");
                 const builder = new graph_builder_1.GraphBuilder(getVectorDb(), root);
                 const hits = yield builder.getNeighbors(symbol, direction, maxHops);
                 if (hits.length === 0) {
@@ -1150,7 +1347,9 @@ exports.mcp = new commander_1.Command("mcp")
             const direction = args.direction === "callers" ? "callers" : "callees";
             const maxHops = Math.min(Math.max(Number(args.max_hops) || 6, 1), 10);
             try {
-                const root = typeof args.root === "string" && args.root ? args.root : projectRoot;
+                const { proj, root } = resolveRegisteredProject(args.root);
+                if (!proj)
+                    return err("Project not added to gmax yet.");
                 const builder = new graph_builder_1.GraphBuilder(getVectorDb(), root);
                 const pathSyms = yield builder.findPaths(from, to, direction, maxHops);
                 if (!pathSyms) {
@@ -1176,8 +1375,10 @@ exports.mcp = new commander_1.Command("mcp")
                 return err("Missing required parameter: files (non-empty array)");
             }
             try {
-                const root = typeof args.root === "string" && args.root ? args.root : projectRoot;
-                const abs = filesIn.map((f) => path.isAbsolute(f) ? f : path.resolve(root, f));
+                const { proj, root } = resolveRegisteredProject(args.root);
+                if (!proj)
+                    return err("Project not added to gmax yet.");
+                const abs = filesIn.map((f) => (0, path_containment_1.resolveContainedPath)(root, f, { verifyExistingTarget: true }));
                 const builder = new graph_builder_1.GraphBuilder(getVectorDb(), root);
                 const sg = yield builder.subgraphForFiles(abs);
                 if (sg.symbols.length === 0) {
@@ -1218,14 +1419,20 @@ exports.mcp = new commander_1.Command("mcp")
             const pattern = typeof args.pattern === "string" ? args.pattern : undefined;
             const limit = Math.min(Math.max(Number(args.limit) || 20, 1), 100);
             const pathPrefix = typeof args.path === "string" ? args.path : undefined;
-            const proj = (0, project_registry_1.getProject)(projectRoot);
+            const { proj, root } = resolveRegisteredProject();
             if (!proj) {
                 return err("Project not added to gmax yet. Run `gmax add` to index it first.");
             }
             try {
                 const db = getVectorDb();
                 const table = yield db.ensureTable();
-                let query = table
+                const rootPrefix = root.endsWith("/") ? root : `${root}/`;
+                let where = `array_length(defined_symbols) > 0 AND ${(0, filter_builder_1.pathStartsWith)(rootPrefix)}`;
+                if (pathPrefix) {
+                    const absPrefix = (0, path_containment_1.resolveContainedPath)(root, pathPrefix);
+                    where += ` AND ${(0, filter_builder_1.pathStartsWith)((0, filter_builder_1.normalizePath)(absPrefix))}`;
+                }
+                const query = table
                     .query()
                     .select([
                     "defined_symbols",
@@ -1234,15 +1441,8 @@ exports.mcp = new commander_1.Command("mcp")
                     "role",
                     "is_exported",
                 ])
-                    .where("array_length(defined_symbols) > 0")
+                    .where(where)
                     .limit(pattern ? 10000 : Math.max(limit * 50, 2000));
-                if (pathPrefix) {
-                    // Support both absolute and relative path prefixes
-                    const absPrefix = path.isAbsolute(pathPrefix)
-                        ? pathPrefix
-                        : path.resolve(projectRoot, pathPrefix);
-                    query = query.where((0, filter_builder_1.pathStartsWith)((0, filter_builder_1.normalizePath)(absPrefix)));
-                }
                 const rows = yield query.toArray();
                 const map = new Map();
                 for (const row of rows) {
@@ -1282,8 +1482,8 @@ exports.mcp = new commander_1.Command("mcp")
                     return ok("No symbols found. Run `gmax status` to verify the project is indexed, or `gmax index` to rebuild.");
                 }
                 const lines = entries.map((e) => {
-                    const rel = e.path.startsWith(projectRoot)
-                        ? e.path.slice(projectRoot.length + 1)
+                    const rel = e.path.startsWith(root)
+                        ? e.path.slice(root.length + 1)
                         : e.path;
                     const roleTag = e.role ? ` [${e.role.slice(0, 4)}]` : "";
                     const expTag = e.exported ? " exported" : "";
@@ -1305,13 +1505,15 @@ exports.mcp = new commander_1.Command("mcp")
                 if (projects.length === 0) {
                     return ok("No projects indexed yet. cd into a repo and run `gmax add` to index it.");
                 }
-                const currentName = (_a = (0, project_registry_1.getProject)(projectRoot)) === null || _a === void 0 ? void 0 : _a.name;
+                const currentName = (_a = resolveMcpProject(undefined, projectRoot)) === null || _a === void 0 ? void 0 : _a.name;
+                const globalConfig = (0, index_config_1.readGlobalConfig)();
                 const lines = projects.map((p) => {
                     const here = p.name === currentName ? " (current)" : "";
                     const chunks = typeof p.chunkCount === "number"
                         ? `\t(${p.chunkCount} chunks)`
                         : "";
-                    return `${p.name}${here}\t${p.root}\t${p.status}${chunks}`;
+                    const identity = (0, embedding_status_1.projectEmbeddingStatus)(p, globalConfig);
+                    return `${p.name}${here}\t${p.root}\t${p.status}\tembedding=${identity.state}${chunks}`;
                 });
                 return ok(`${projects.length} indexed project(s). ` +
                     `Pass a name to semantic_search via projects:"name", or use scope:"all".\n\n` +
@@ -1325,11 +1527,12 @@ exports.mcp = new commander_1.Command("mcp")
     }
     function handleIndexStatus() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f;
+            var _a;
             try {
-                const config = (0, index_config_1.readIndexConfig)(config_1.PATHS.configPath);
                 const globalConfig = (0, index_config_1.readGlobalConfig)();
                 const projects = (0, project_registry_1.listProjects)();
+                const currentProject = resolveMcpProject(undefined, projectRoot);
+                const identity = (0, embedding_status_1.projectEmbeddingStatus)(currentProject, globalConfig);
                 const db = getVectorDb();
                 const stats = yield db.getStats();
                 const fileCount = yield db.getDistinctFileCount();
@@ -1352,8 +1555,13 @@ exports.mcp = new commander_1.Command("mcp")
                 // focused on index health and avoid the N-project LanceDB scans.
                 const lines = [
                     `Index: ~/.gmax/lancedb (${stats.chunks} chunks, ${fileCount} files)`,
-                    `Model: ${globalConfig.embedMode === "gpu" ? ((_d = (_c = (_b = config_1.MODEL_TIERS[globalConfig.modelTier]) === null || _b === void 0 ? void 0 : _b.mlxModel) !== null && _c !== void 0 ? _c : config === null || config === void 0 ? void 0 : config.embedModel) !== null && _d !== void 0 ? _d : "unknown") : ((_e = config === null || config === void 0 ? void 0 : config.embedModel) !== null && _e !== void 0 ? _e : "unknown")} (${(_f = config === null || config === void 0 ? void 0 : config.vectorDim) !== null && _f !== void 0 ? _f : "?"}d, ${globalConfig.embedMode})`,
-                    (config === null || config === void 0 ? void 0 : config.indexedAt) ? `Last indexed: ${config.indexedAt}` : "",
+                    `Configured embedding: ${identity.configured.tier} ${identity.configured.vectorDim}d [${(0, embedding_status_1.embeddingFingerprintLabel)(identity.configured.fingerprint)}] (${globalConfig.embedMode})`,
+                    identity.built
+                        ? `Built embedding: ${identity.built.tier} ${identity.built.vectorDim}d [${(0, embedding_status_1.embeddingFingerprintLabel)(identity.built.fingerprint)}] (${identity.state})`
+                        : "Built embedding: unbuilt",
+                    (currentProject === null || currentProject === void 0 ? void 0 : currentProject.lastIndexed)
+                        ? `Last indexed: ${currentProject.lastIndexed}`
+                        : "",
                     watcherLine,
                     `Projects: ${projects.length} indexed (call list_projects for names + per-project chunk counts)`,
                 ].filter(Boolean);
@@ -1367,7 +1575,12 @@ exports.mcp = new commander_1.Command("mcp")
     }
     function handleSummarizeDirectory(args) {
         return __awaiter(this, void 0, void 0, function* () {
-            const dir = typeof args.path === "string" ? path.resolve(args.path) : projectRoot;
+            const { proj, root } = resolveRegisteredProject();
+            if (!proj)
+                return err("Project not added to gmax yet.");
+            const dir = typeof args.path === "string"
+                ? (0, path_containment_1.resolveContainedPath)(root, args.path)
+                : root;
             const prefix = dir.endsWith("/") ? dir : `${dir}/`;
             const limit = Math.min(Math.max(Number(args.limit) || 200, 1), 5000);
             try {
@@ -1392,7 +1605,9 @@ exports.mcp = new commander_1.Command("mcp")
     function handleSummarizeProject(args) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
-            const root = typeof args.root === "string" ? path.resolve(args.root) : projectRoot;
+            const { proj, root } = resolveRegisteredProject(args.root);
+            if (!proj)
+                return err("Project not added to gmax yet.");
             const prefix = root.endsWith("/") ? root : `${root}/`;
             const projectName = path.basename(root);
             try {
@@ -1514,7 +1729,13 @@ exports.mcp = new commander_1.Command("mcp")
             if (!file)
                 return err("Missing required parameter: file");
             const limit = Math.min(Math.max(Number(args.limit) || 10, 1), 25);
-            const absPath = path.resolve(projectRoot, file);
+            const { proj, root } = resolveRegisteredProject();
+            if (!proj)
+                return err("Project not added to gmax yet.");
+            const absPath = (0, path_containment_1.resolveContainedPath)(root, file, {
+                verifyExistingTarget: true,
+            });
+            const rootPrefix = root.endsWith("/") ? root : `${root}/`;
             try {
                 const db = getVectorDb();
                 const table = yield db.ensureTable();
@@ -1542,7 +1763,7 @@ exports.mcp = new commander_1.Command("mcp")
                     const rows = yield table
                         .query()
                         .select(["path"])
-                        .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(sym)}')`)
+                        .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(sym)}') AND ${(0, filter_builder_1.pathStartsWith)(rootPrefix)}`)
                         .limit(3)
                         .toArray();
                     for (const row of rows) {
@@ -1558,7 +1779,7 @@ exports.mcp = new commander_1.Command("mcp")
                     const rows = yield table
                         .query()
                         .select(["path"])
-                        .where(`array_contains(referenced_symbols, '${(0, filter_builder_1.escapeSqlString)(sym)}')`)
+                        .where(`array_contains(referenced_symbols, '${(0, filter_builder_1.escapeSqlString)(sym)}') AND ${(0, filter_builder_1.pathStartsWith)(rootPrefix)}`)
                         .limit(20)
                         .toArray();
                     for (const row of rows) {
@@ -1576,8 +1797,8 @@ exports.mcp = new commander_1.Command("mcp")
                 if (topDeps.length > 0) {
                     lines.push("Dependencies (files this imports/calls):");
                     for (const [p, count] of topDeps) {
-                        const rel = p.startsWith(`${projectRoot}/`)
-                            ? p.slice(projectRoot.length + 1)
+                        const rel = p.startsWith(rootPrefix)
+                            ? p.slice(rootPrefix.length)
                             : p;
                         lines.push(`  ${rel.padEnd(40)} (${count} shared symbol${count > 1 ? "s" : ""})`);
                     }
@@ -1592,8 +1813,8 @@ exports.mcp = new commander_1.Command("mcp")
                 if (topRevs.length > 0) {
                     lines.push("Dependents (files that call this):");
                     for (const [p, count] of topRevs) {
-                        const rel = p.startsWith(`${projectRoot}/`)
-                            ? p.slice(projectRoot.length + 1)
+                        const rel = p.startsWith(rootPrefix)
+                            ? p.slice(rootPrefix.length)
                             : p;
                         lines.push(`  ${rel.padEnd(40)} (${count} shared symbol${count > 1 ? "s" : ""})`);
                     }
@@ -1614,7 +1835,9 @@ exports.mcp = new commander_1.Command("mcp")
             var _a, e_1, _b, _c;
             ensureWatcher();
             const limit = Math.min(Math.max(Number(args.limit) || 20, 1), 50);
-            const root = typeof args.root === "string" ? path.resolve(args.root) : projectRoot;
+            const { proj, root } = resolveRegisteredProject(args.root);
+            if (!proj)
+                return err("Project not added to gmax yet.");
             const prefix = root.endsWith("/") ? root : `${root}/`;
             try {
                 const metaCache = new meta_cache_1.MetaCache(config_1.PATHS.lmdbPath);
@@ -1675,16 +1898,20 @@ exports.mcp = new commander_1.Command("mcp")
             const limit = Math.min(Math.max(Number(args.limit) || 10, 1), 50);
             const role = typeof args.role === "string" ? args.role.toUpperCase() : undefined;
             try {
-                const changedFiles = getChangedFiles(ref, projectRoot);
+                const { proj, root } = resolveRegisteredProject();
+                if (!proj)
+                    return err("Project not added to gmax yet.");
+                (0, embedding_status_1.assertEmbeddingSearchCompatible)([proj], (0, index_config_1.readGlobalConfig)());
+                const changedFiles = getChangedFiles(ref, root);
                 if (changedFiles.length === 0) {
                     return ok(ref
                         ? `No changes found relative to ${ref}.`
                         : "No uncommitted changes found.");
                 }
-                const rel = (p) => p.startsWith(`${projectRoot}/`) ? p.slice(projectRoot.length + 1) : p;
+                const rel = (p) => p.startsWith(`${root}/`) ? p.slice(root.length + 1) : p;
                 if (query) {
                     const searcher = getSearcher();
-                    const response = yield searcher.search(query, limit, { rerank: process.env.GMAX_RERANK === "1" }, {}, projectRoot);
+                    const response = yield searcher.search(query, limit, { rerank: process.env.GMAX_RERANK === "1" }, {}, root);
                     const changedSet = new Set(changedFiles);
                     // searcher.search() returns mapped chunks (path under metadata.path);
                     // changedFiles are absolute, so match on the resolved absolute path.
@@ -1732,15 +1959,19 @@ exports.mcp = new commander_1.Command("mcp")
                 return err("Missing required parameter: target");
             const depth = Math.min(Math.max(Number(args.depth) || 1, 1), 3);
             try {
+                const { proj, root } = resolveRegisteredProject();
+                if (!proj)
+                    return err("Project not added to gmax yet.");
+                const scopedTarget = containMcpTarget(root, target);
                 const { resolveTargetSymbols, findTests } = yield Promise.resolve().then(() => __importStar(require("../lib/graph/impact")));
                 const db = getVectorDb();
-                const { symbols, symbolFamilies } = yield resolveTargetSymbols(target, db, projectRoot);
+                const { symbols, symbolFamilies } = yield resolveTargetSymbols(scopedTarget, db, mcpRootPrefix(root));
                 if (symbols.length === 0)
                     return ok(`No symbols found for: ${target}`);
-                const tests = yield findTests(symbols, db, projectRoot, depth, undefined, symbolFamilies);
+                const tests = yield findTests(symbols, db, root, depth, undefined, symbolFamilies);
                 if (tests.length === 0)
                     return ok(`No tests found for ${target}.`);
-                const rel = (p) => p.startsWith(`${projectRoot}/`) ? p.slice(projectRoot.length + 1) : p;
+                const rel = (p) => p.startsWith(`${root}/`) ? p.slice(root.length + 1) : p;
                 const lines = tests.map((t) => {
                     const hop = t.hops === 0 ? "direct" : `${t.hops}-hop`;
                     return `${rel(t.file)}:${t.line + 1} ${t.symbol} (${hop})`;
@@ -1759,22 +1990,47 @@ exports.mcp = new commander_1.Command("mcp")
             if (!target)
                 return err("Missing required parameter: target");
             const depth = Math.min(Math.max(Number(args.depth) || 1, 1), 3);
+            const rollup = args.rollup === true;
+            const top = Math.min(Math.max(Number(args.top) || 10, 1), 100);
             try {
-                const { resolveTargetSymbols, findTests, findDependents, isTestPath } = yield Promise.resolve().then(() => __importStar(require("../lib/graph/impact")));
+                const { proj, root } = resolveRegisteredProject();
+                if (!proj)
+                    return err("Project not added to gmax yet.");
+                const scopedTarget = containMcpTarget(root, target);
+                const { resolveTargetSymbols, findTests, findDependents, findDependentsDetailed, isTestPath, } = yield Promise.resolve().then(() => __importStar(require("../lib/graph/impact")));
+                const { buildImpactRollup, formatImpactRollupAgent } = yield Promise.resolve().then(() => __importStar(require("../lib/graph/impact-rollup")));
                 const db = getVectorDb();
-                const { symbols, resolvedAsFile, symbolFamilies } = yield resolveTargetSymbols(target, db, projectRoot);
+                const { symbols, resolvedAsFile, symbolFamilies } = yield resolveTargetSymbols(scopedTarget, db, root);
                 if (symbols.length === 0)
                     return ok(`No symbols found for: ${target}`);
                 const targetPath = resolvedAsFile
-                    ? path.resolve(projectRoot, target)
+                    ? (0, path_containment_1.resolveContainedPath)(root, scopedTarget)
                     : undefined;
                 const excludePaths = targetPath ? new Set([targetPath]) : undefined;
+                const rollupLimit = Math.min(Math.max(top * 10, 100), 500);
                 const [dependents, tests] = yield Promise.all([
-                    findDependents(symbols, db, projectRoot, excludePaths, undefined, undefined, symbolFamilies),
-                    findTests(symbols, db, projectRoot, depth, undefined, symbolFamilies),
+                    rollup
+                        ? findDependentsDetailed(symbols, db, root, excludePaths, rollupLimit, undefined, symbolFamilies)
+                        : findDependents(symbols, db, root, excludePaths, undefined, undefined, symbolFamilies),
+                    findTests(symbols, db, root, depth, undefined, symbolFamilies),
                 ]);
+                if (rollup) {
+                    const detailedDependents = dependents;
+                    const impactRollup = buildImpactRollup({
+                        targetSymbols: symbols,
+                        dependents: detailedDependents,
+                        tests,
+                        projectRoot: root,
+                        top,
+                    });
+                    return ok(formatImpactRollupAgent(impactRollup, {
+                        target,
+                        projectRoot: root,
+                        includeTests: true,
+                    }));
+                }
                 const nonTestDeps = dependents.filter((d) => !isTestPath(d.file));
-                const rel = (p) => p.startsWith(`${projectRoot}/`) ? p.slice(projectRoot.length + 1) : p;
+                const rel = (p) => p.startsWith(`${root}/`) ? p.slice(root.length + 1) : p;
                 const sections = [`Impact analysis for ${target}:\n`];
                 if (nonTestDeps.length > 0) {
                     sections.push(`Dependents (${nonTestDeps.length}):`);
@@ -1811,13 +2067,17 @@ exports.mcp = new commander_1.Command("mcp")
             const limit = Math.min(Math.max(Number(args.limit) || 5, 1), 25);
             const threshold = Number(args.threshold) || 0;
             try {
+                const { proj, root } = resolveRegisteredProject();
+                if (!proj)
+                    return err("Project not added to gmax yet.");
+                (0, embedding_status_1.assertEmbeddingSearchCompatible)([proj], (0, index_config_1.readGlobalConfig)());
                 const db = getVectorDb();
                 const table = yield db.ensureTable();
                 const isFile = target.includes("/") ||
                     (target.includes(".") && !target.includes(" "));
                 let sourceRows;
                 if (isFile) {
-                    const absPath = path.resolve(projectRoot, target);
+                    const absPath = (0, path_containment_1.resolveContainedPath)(root, target);
                     sourceRows = yield table
                         .query()
                         .select(["vector", "path", "start_line"])
@@ -1829,7 +2089,7 @@ exports.mcp = new commander_1.Command("mcp")
                     sourceRows = yield table
                         .query()
                         .select(["vector", "path", "start_line"])
-                        .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(target)}')`)
+                        .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(target)}') AND ${(0, filter_builder_1.pathStartsWith)(`${root}/`)}`)
                         .limit(1)
                         .toArray();
                 }
@@ -1849,7 +2109,7 @@ exports.mcp = new commander_1.Command("mcp")
                     "role",
                     "_distance",
                 ])
-                    .where((0, filter_builder_1.pathStartsWith)(`${projectRoot}/`))
+                    .where((0, filter_builder_1.pathStartsWith)(`${root}/`))
                     .limit(limit + 5)
                     .toArray();
                 let filtered = results.filter((r) => !(r.path === source.path && r.start_line === source.start_line));
@@ -1857,7 +2117,7 @@ exports.mcp = new commander_1.Command("mcp")
                     filtered = filtered.filter((r) => { var _a; return 1 / (1 + ((_a = r._distance) !== null && _a !== void 0 ? _a : 0)) >= threshold; });
                 if (filtered.length === 0)
                     return ok(`No similar code found for ${target}.`);
-                const rel = (p) => p.startsWith(`${projectRoot}/`) ? p.slice(projectRoot.length + 1) : p;
+                const rel = (p) => p.startsWith(`${root}/`) ? p.slice(root.length + 1) : p;
                 const lines = filtered.slice(0, limit).map((r) => {
                     var _a, _b, _c, _d;
                     const sym = (_b = (_a = toStringArray(r.defined_symbols)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : "";
@@ -1880,11 +2140,15 @@ exports.mcp = new commander_1.Command("mcp")
             const budget = Math.max(Number(args.budget) || 4000, 500);
             const limit = Math.min(Math.max(Number(args.limit) || 10, 1), 25);
             try {
+                const { proj, root } = resolveRegisteredProject();
+                if (!proj)
+                    return err("Project not added to gmax yet.");
+                (0, embedding_status_1.assertEmbeddingSearchCompatible)([proj], (0, index_config_1.readGlobalConfig)());
                 const searcher = getSearcher();
-                const response = yield searcher.search(topic, limit, { rerank: process.env.GMAX_RERANK === "1" }, {}, projectRoot);
+                const response = yield searcher.search(topic, limit, { rerank: process.env.GMAX_RERANK === "1" }, {}, root);
                 if (response.data.length === 0)
                     return ok(`No results found for "${topic}".`);
-                const rel = (p) => p.startsWith(`${projectRoot}/`) ? p.slice(projectRoot.length + 1) : p;
+                const rel = (p) => p.startsWith(`${root}/`) ? p.slice(root.length + 1) : p;
                 const estTokens = (s) => Math.ceil(s.length / 4);
                 let tokensUsed = 0;
                 const sections = [];
@@ -1905,7 +2169,8 @@ exports.mcp = new commander_1.Command("mcp")
                     const endLine = searchResultEndLine(r, startLine);
                     const sym = (_b = (_a = toStringArray(r.defined_symbols)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : "";
                     try {
-                        const content = fs.readFileSync(absP, "utf-8");
+                        const sourcePath = (0, path_containment_1.resolveContainedFile)(root, absP);
+                        const content = fs.readFileSync(sourcePath, "utf-8");
                         const body = content
                             .split("\n")
                             .slice(startLine, endLine + 1)
@@ -2045,15 +2310,16 @@ exports.mcp = new commander_1.Command("mcp")
             "If you are NOT inside a specific repo, or want a different one: call " +
             '`list_projects` to see what\'s indexed, then pass `projects:"name"` (or ' +
             '`scope:"all"`) to `semantic_search`. When the working directory isn\'t an ' +
-            "indexed project, `semantic_search` automatically searches all of them and " +
-            "says so. Prefer `semantic_search` (detail:'pointer') for discovery, then " +
+            "indexed project, `semantic_search` errors instead of searching everything " +
+            "implicitly. Prefer `semantic_search` (detail:'pointer') for discovery, then " +
             "`extract_symbol`/`peek_symbol`/`code_skeleton` to read, and " +
-            "`trace_calls`/`impact_analysis`/`find_tests` for call-graph questions.",
+            "`trace_calls`/`impact_analysis`/`find_tests` for call-graph questions. " +
+            "Use `audit` and experimental `surprising_connections` for project orientation.",
     });
     // Best-effort query logging, applied uniformly to every tool exactly as the
     // old single CallToolRequestSchema dispatch did before each return.
     const logToolCall = (name, toolArgs, startMs, result) => __awaiter(void 0, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c;
         try {
             const { logQuery } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/query-log")));
             const text = (_c = (_b = (_a = result.content) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.text) !== null && _c !== void 0 ? _c : "";
@@ -2062,22 +2328,31 @@ exports.mcp = new commander_1.Command("mcp")
                 ts: new Date().toISOString(),
                 source: "mcp",
                 tool: name,
-                query: String((_f = (_e = (_d = toolArgs.query) !== null && _d !== void 0 ? _d : toolArgs.symbol) !== null && _e !== void 0 ? _e : toolArgs.target) !== null && _f !== void 0 ? _f : ""),
+                query: mcpLogQuery(name, toolArgs),
                 project: projectRoot,
                 results: resultLines,
                 ms: Date.now() - startMs,
                 error: result.isError ? text.slice(0, 200) : undefined,
             });
         }
-        catch (_g) { }
+        catch (_d) { }
     });
     // Register a tool, wrapping its handler with timing + query logging. Zod raw
     // shapes give us free input validation (the SDK rejects calls that violate
     // the schema before the handler runs); handlers stay defensively coded.
     function tool(name, config, handler) {
         server.registerTool(name, config, (rawArgs) => __awaiter(this, void 0, void 0, function* () {
-            const args = (rawArgs !== null && rawArgs !== void 0 ? rawArgs : {});
+            let args = (rawArgs !== null && rawArgs !== void 0 ? rawArgs : {});
             const startMs = Date.now();
+            if (typeof args.root === "string" && args.root.trim()) {
+                const selected = resolveMcpProject(args.root, projectRoot);
+                if (!selected) {
+                    const result = err(`Unknown registered project: ${args.root}. Use list_projects to select a project name or exact root.`);
+                    yield logToolCall(name, args, startMs, result);
+                    return result;
+                }
+                args = Object.assign(Object.assign({}, args), { root: selected.root });
+            }
             const result = yield handler(args);
             yield logToolCall(name, args, startMs, result);
             return result;
@@ -2095,7 +2370,7 @@ exports.mcp = new commander_1.Command("mcp")
                 .optional(),
             root: zod_1.z
                 .string()
-                .describe("Search a different directory (absolute path)")
+                .describe("Registered project name or exact root")
                 .optional(),
             path: zod_1.z
                 .string()
@@ -2229,6 +2504,55 @@ exports.mcp = new commander_1.Command("mcp")
                 .optional(),
         },
     }, handleAudit);
+    tool("surprising_connections", {
+        description: "Experimental orientation signal: embedding-similar cross-directory file pairs that are not directly connected by the static symbol graph. Useful for spotting duplicate or parallel logic. Requires experimental:true.",
+        inputSchema: {
+            experimental: zod_1.z
+                .boolean()
+                .describe("Must be true to acknowledge experimental signal quality"),
+            root: zod_1.z
+                .string()
+                .describe("Project root (default: current)")
+                .optional(),
+            sample: zod_1.z
+                .number()
+                .describe("Indexed code chunks to sample (default 160, max 10000)")
+                .optional(),
+            neighbors: zod_1.z
+                .number()
+                .describe("Nearest neighbors per sampled chunk (default 20, max 200)")
+                .optional(),
+            top: zod_1.z
+                .number()
+                .describe("Grouped findings to return (default 10, max 100)")
+                .optional(),
+            dir_depth: zod_1.z
+                .number()
+                .describe("Directory bucket depth considered unsurprising")
+                .optional(),
+            min_similarity: zod_1.z
+                .number()
+                .describe("Minimum similarity 0-1 (default 0)")
+                .optional(),
+            max_rows: zod_1.z
+                .number()
+                .describe(`Maximum indexed rows to scan (default 50000, max ${surprising_connections_1.MAX_SURPRISE_ROWS})`)
+                .optional(),
+            in: zod_1.z
+                .string()
+                .describe("Restrict to a sub-path of the project")
+                .optional(),
+            exclude: zod_1.z
+                .string()
+                .describe("Exclude a sub-path of the project")
+                .optional(),
+            include_tests: zod_1.z.boolean().describe("Include test files").optional(),
+            include_eval: zod_1.z
+                .boolean()
+                .describe("Include eval/experiment/script files")
+                .optional(),
+        },
+    }, handleSurprisingConnections);
     tool("get_neighbors", {
         description: "Graph primitive: symbols reachable from a node along call edges within N hops. direction 'callees' = what it calls (outbound), 'callers' = what calls it (inbound). Each result carries its hop distance and definition location. Static call graph — same caveats as `dead`/`audit`.",
         inputSchema: {
@@ -2371,6 +2695,14 @@ exports.mcp = new commander_1.Command("mcp")
                 .number()
                 .describe("Caller traversal depth 1-3 (default 1)")
                 .optional(),
+            rollup: zod_1.z
+                .boolean()
+                .describe("Return export/package rollup TSV rows")
+                .optional(),
+            top: zod_1.z
+                .number()
+                .describe("Max rows per rollup section (default 10)")
+                .optional(),
         },
     }, handleImpactAnalysis);
     tool("find_similar", {