grepmax 0.23.0 → 0.24.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "grepmax",
       "source": "./plugins/grepmax",
       "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
-      "version": "0.23.0",
+      "version": "0.24.0",
       "author": {
         "name": "Robert Owens",
         "email": "robowens@me.com"

package/README.md

@@ -73,6 +73,7 @@ gmax test handleAuth                     # Find tests via reverse call graph
 gmax impact handleAuth                   # Dependents + affected tests
 gmax similar handleAuth                  # Find similar code patterns
 gmax audit --top 10                      # God nodes, hub files, file cycles, dead candidates
+gmax surprises --experimental --agent    # Experimental: similar but graph-disconnected file pairs
 gmax dead handleAuth                     # Unused-symbol check via call graph (DEAD / PUBLIC EXPORT / LIVE)
 gmax context "auth system" --budget 4000 # Token-budgeted topic summary
 gmax context src/lib/auth.ts --budget 4000 # Deterministic file/path context
@@ -134,6 +135,7 @@ Plugins auto-update when you run `npm install -g grepmax@latest` — no need to
 | `peek_symbol` | Compact overview: signature + callers + callees. |
 | `dead` | Unused-symbol check via call graph. Returns `DEAD`, `PUBLIC EXPORT`, or `LIVE` with caller count. |
 | `audit` | Graph summary: god nodes, hub files, symbol-derived file dependency cycles, and dead-code candidates. |
+| `surprising_connections` | Experimental orientation signal: embedding-similar file pairs with no direct indexed static file edge. Requires `experimental:true`. |
 | `get_neighbors` | Graph primitive: symbols reachable from a node along call edges within N hops. |
 | `find_paths` | Graph primitive: shortest call-graph path between two symbols. |
 | `subgraph_for_files` | Graph primitive: local dependency subgraph for a set of files. |
@@ -177,6 +179,18 @@ gmax "query" [options]
 | `--seed-symbol <name>` | Bias results toward an identifier you're working with (repeatable). | — |
 | `--skeleton` | Show file skeletons for top matches. | `false` |
 | `--context-for-llm` | Full function bodies + imports per result. | `false` |
+
+## Experimental Orientation
+
+`gmax surprises --experimental` finds file pairs that are semantically similar but not already connected by the indexed static graph. Use it for architecture orientation, duplicate-logic sweeps, and cross-package drift checks, not as proof that two files are unrelated.
+
+```bash
+gmax surprises --experimental --agent
+gmax surprises --experimental --in packages/app/src --dir-depth 4 --agent
+gmax surprises --experimental --exclude generated --top 10
+```
+
+The CLI and MCP output include score, max similarity, pair count, representative symbols, directory buckets, top similarities, applied penalties, and `gmax skeleton` follow-up hints. On large monorepos, prefer `--in`/`--exclude`; the default scan is capped at 50,000 rows and user-provided `--max-rows` is capped at 100,000. If a narrow `--in` scope returns no findings, increase `--dir-depth` so subdirectories are compared inside the scope.
 | `--budget <tokens>` | Cap output tokens (for `--context-for-llm`). | `8000` |
 | `--explain` | Show scoring breakdown per result. | `false` |
 | `--scores` | Show relevance scores. | `false` |

package/dist/commands/impact.js

@@ -46,6 +46,7 @@ exports.impact = void 0;
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const impact_1 = require("../lib/graph/impact");
+const impact_rollup_1 = require("../lib/graph/impact-rollup");
 const test_hits_1 = require("../lib/graph/test-hits");
 const vector_db_1 = require("../lib/store/vector-db");
 const agent_errors_1 = require("../lib/utils/agent-errors");
@@ -61,12 +62,16 @@ exports.impact = new commander_1.Command("impact")
     .option("--in <subpath>", "Restrict to a sub-path of the project (repeatable)", (value, prev) => prev ? [...prev, value] : [value])
     .option("--exclude <subpath>", "Exclude a sub-path of the project (repeatable)", (value, prev) => prev ? [...prev, value] : [value])
     .option("--no-tests", "Skip affected-test analysis; show production blast radius only")
+    .option("--rollup", "Show export/package rollup (default for file targets in human output)", false)
+    .option("--flat", "Use the legacy flat dependent/test list", false)
+    .option("--top <n>", "Max rows per rollup section", "10")
     .option("--agent", "Compact output for AI agents", false)
     .action((target, opts) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const depth = Math.min(Math.max(Number.parseInt(opts.depth || "1", 10), 1), 3);
     // commander maps --no-tests → opts.tests === false (defaults true).
     const includeTests = opts.tests !== false;
+    const top = Math.min(Math.max(Number.parseInt(opts.top || "10", 10) || 10, 1), 100);
     let vectorDb = null;
     try {
         const root = (0, project_registry_1.resolveRootOrExit)(opts.root);
@@ -105,15 +110,42 @@ exports.impact = new commander_1.Command("impact")
         const queryRoot = opts.in && opts.in.length > 0
             ? scope.pathPrefix.replace(/\/$/, "")
             : projectRoot;
+        const useRollup = !opts.flat && ((resolvedAsFile && !opts.agent) || opts.rollup === true);
+        const rollupLimit = Math.min(Math.max(top * 10, 100), 500);
         // Run dependents and tests in parallel. --no-tests skips the test
         // traversal entirely so the affected-tests section is omitted (not just
         // empty) below.
         const [dependents, tests] = yield Promise.all([
-            (0, impact_1.findDependents)(symbols, vectorDb, queryRoot, excludePaths, undefined, scope.excludePrefixes, symbolFamilies),
+            useRollup
+                ? (0, impact_1.findDependentsDetailed)(symbols, vectorDb, queryRoot, excludePaths, rollupLimit, scope.excludePrefixes, symbolFamilies)
+                : (0, impact_1.findDependents)(symbols, vectorDb, queryRoot, excludePaths, undefined, scope.excludePrefixes, symbolFamilies),
             includeTests
                 ? (0, impact_1.findTests)(symbols, vectorDb, queryRoot, depth, scope.excludePrefixes, symbolFamilies)
                 : Promise.resolve([]),
         ]);
+        if (useRollup) {
+            const detailedDependents = dependents;
+            const rollup = (0, impact_rollup_1.buildImpactRollup)({
+                targetSymbols: symbols,
+                dependents: detailedDependents,
+                tests,
+                projectRoot,
+                top,
+            });
+            const formatted = opts.agent
+                ? (0, impact_rollup_1.formatImpactRollupAgent)(rollup, {
+                    target,
+                    projectRoot,
+                    includeTests,
+                })
+                : (0, impact_rollup_1.formatImpactRollupHuman)(rollup, {
+                    target,
+                    projectRoot,
+                    includeTests,
+                });
+            console.log(formatted);
+            return;
+        }
         // Separate test files from non-test dependents
         const nonTestDeps = dependents.filter((d) => !(0, impact_1.isTestPath)(d.file));
         // One line per test file; caller symbols inside it become `via` detail.

package/dist/commands/mcp.js

@@ -53,11 +53,14 @@ exports.mcp = void 0;
 exports.toStringArray = toStringArray;
 exports.ok = ok;
 exports.err = err;
+exports.isExplicitCrossProjectSearch = isExplicitCrossProjectSearch;
 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,6 +68,7 @@ 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 index_config_1 = require("../lib/index/index-config");
@@ -109,6 +113,13 @@ 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 chunkAbsPath(chunk) {
     const metadata = chunk.metadata;
     return String(chunk.path || (metadata === null || metadata === void 0 ? void 0 : metadata.path) || "");
@@ -171,6 +182,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
 // ---------------------------------------------------------------------------
@@ -264,38 +328,56 @@ 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() {
+        const exact = (0, project_registry_1.getProject)(projectRoot);
+        if (exact)
+            return { proj: exact, root: projectRoot };
+        const parent = (0, project_registry_1.getParentProject)(projectRoot);
+        if (parent)
+            return { proj: parent, root: parent.root };
+        return { proj: undefined, root: projectRoot };
+    }
     // --- Tool handlers ---
     function handleSemanticSearch(args_1) {
         return __awaiter(this, arguments, void 0, function* (args, isSearchAll = false) {
             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();
+            // 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.");
+                }
             }
             try {
                 const searcher = getSearcher();
@@ -305,7 +387,7 @@ exports.mcp = new commander_1.Command("mcp")
                 if (!searchAll) {
                     const searchRoot = typeof args.root === "string"
                         ? path.resolve(args.root)
-                        : path.resolve(projectRoot);
+                        : path.resolve(resolvedRoot);
                     if (typeof args.root === "string" && !fs.existsSync(searchRoot)) {
                         return err(`Directory not found: ${args.root}`);
                     }
@@ -372,11 +454,10 @@ 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.
+                // 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) {
@@ -676,7 +757,7 @@ exports.mcp = new commander_1.Command("mcp")
             const symbol = String(args.symbol || "");
             if (!symbol)
                 return err("Missing required parameter: symbol");
-            const proj = (0, project_registry_1.getProject)(projectRoot);
+            const { proj } = resolveRegisteredProject();
             if (!proj) {
                 return err("Project not added to gmax yet. Run `gmax add` to index it first.");
             }
@@ -1106,6 +1187,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 root = typeof args.root === "string" && args.root
+                ? path.resolve(args.root)
+                : projectRoot;
+            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();
@@ -1218,7 +1336,7 @@ 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 } = resolveRegisteredProject();
             if (!proj) {
                 return err("Project not added to gmax yet. Run `gmax add` to index it first.");
             }
@@ -1759,8 +1877,11 @@ 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 { 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);
                 if (symbols.length === 0)
@@ -1769,10 +1890,28 @@ exports.mcp = new commander_1.Command("mcp")
                     ? path.resolve(projectRoot, target)
                     : 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),
+                    rollup
+                        ? findDependentsDetailed(symbols, db, projectRoot, excludePaths, rollupLimit, undefined, symbolFamilies)
+                        : findDependents(symbols, db, projectRoot, excludePaths, undefined, undefined, symbolFamilies),
                     findTests(symbols, db, projectRoot, depth, undefined, symbolFamilies),
                 ]);
+                if (rollup) {
+                    const detailedDependents = dependents;
+                    const impactRollup = buildImpactRollup({
+                        targetSymbols: symbols,
+                        dependents: detailedDependents,
+                        tests,
+                        projectRoot,
+                        top,
+                    });
+                    return ok(formatImpactRollupAgent(impactRollup, {
+                        target,
+                        projectRoot,
+                        includeTests: true,
+                    }));
+                }
                 const nonTestDeps = dependents.filter((d) => !isTestPath(d.file));
                 const rel = (p) => p.startsWith(`${projectRoot}/`) ? p.slice(projectRoot.length + 1) : p;
                 const sections = [`Impact analysis for ${target}:\n`];
@@ -2045,15 +2184,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,14 +2202,14 @@ 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
@@ -2229,6 +2369,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 +2560,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", {