grepmax 0.26.69 → 0.26.71

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.26.69",
+      "version": "0.26.71",
       "author": {
         "name": "Robert Owens",
         "email": "robowens@me.com"

package/DOCUMENT-SEARCH.md

@@ -0,0 +1,113 @@
+# Existing-index document search (contract v1)
+
+`gmax mcp --existing-index-only` serves two read-only stdio MCP tools. The exact
+entry dispatch precedes the normal CLI. Server identity is
+`gmax-document-search`; the 2025-06-18 initialize exchange is supported by the
+current MCP SDK. Contract version is independent of package version.
+
+Every tool returns `structuredContent` with `contractVersion: 1` and capabilities
+`{existingIndexOnly: 1, queryLogging: false, watch: false, runtimeStartup: false}`.
+The text content contains only the result state. No source/snippet bodies are
+returned. Runlist has no gmax, model or SDK runtime dependency.
+
+- `document_search_status({paths})` returns `state: ready`, a required positive
+  safe-integer `generation`, `project: {root,store,lastIndexed}`,
+  actual metadata `covered` paths, `coverage: {requested,indexed,partial}`,
+  `embeddingReady`, `queryState` and index state. Readiness does not guarantee
+  worker availability when the subsequent query arrives. Coverage is not a
+  registry/store-wide chunk count and does not prove current source freshness.
+  Covered paths retain a validated `indexedMtimeMs` where available. A missing
+  sampled Markdown file reduces coverage instead of discarding other paths;
+  malformed or out-of-scope paths still refuse. Counts are recomputed, and
+  metadata uses a bounded field allowlist without free-form diagnostics.
+- `semantic_search({query,prefixes})` returns `state: ready`, canonical `root`,
+  selected `store`, required `generation`, `matches` and index state. Each pointer is
+  `{path,startLine,endLine,score,hash?,hashAlgorithm?}`. Ranges are one-based full
+  source ranges, converted from indexed zero-based lines. Score is
+  `1/(1+max(0,cosineDistance))`, not a relevance probability.
+- `hashAlgorithm: sha256-bytes` is declared only when the vector row digest agrees
+  with current version-1 metadata whose digest hashes the exact indexed bytes.
+  Legacy/mismatched provenance retains document-only pointers. Consumers must
+  reread and authorize current source, verify the digest and map body lines before
+  jumping to a section. This bridge never hashes new bytes to bless old lines.
+
+Limits: 500 query characters, 32 explicit prefixes, 2,000 coverage paths and a
+512 KiB serialized path budget, 50 vector candidates, 1 MiB transport frames and
+a 10-second bridge operation deadline. The most specific registered ancestor
+of the canonical checkout selects the primary store; registered spelling is
+preserved for daemon/row lookups. Coverage and prefixes must resolve inside the
+checkout and selected project. Secondary stores are unavailable. No candidate
+refill broadens scope. Symlink targets are rechecked before pointers are returned.
+
+Unavailable states: `unsupported_tool`, `unsupported_daemon`, `no_index`,
+`index_unavailable`, `daemon_unavailable`, `store_unavailable`,
+`embedding_unavailable`, `embedding_mismatch`, `host_pressure`, `busy`,
+`cancelled`, `timeout`, `no_coverage`, `search_unavailable`. Envelopes contain
+stable states, never raw query-bearing diagnostics. Schema/unknown-tool errors
+remain standard MCP errors.
+
+The supported bridge negotiates daemon `existingIndexOnlySearch: 1` and resource
+generation. Missing, null, non-integer and changed generations refuse; Runlist
+also fences status against subsequent retrieval. Private daemon commands are `documents.status` and `documents.search`;
+Runlist does not call the socket API. The daemon validates roots, stores, bounds
+and generation again under its shared-operation coordinator, including after
+encoding and native retrieval. Paused/contained resources refuse rather than
+return keyword results.
+
+Retrieval in this first slice is **dense-only** against an already-open LanceDB
+connection/table. It never invokes normal hybrid search, FTS creation, reranking,
+ColBERT inference, `ensureTable`, schema evolution, index mutation or local-store
+fallback. Query encoding uses a currently idle, already-warm compatible worker:
+CPU requires a loaded Granite tokenizer/session; GPU requires cached positive
+confirmation of the existing configured MLX model. Idle time alone does not revoke
+that identity: each bounded `/embed` response revalidates model and dimensions,
+and successful inference renews the normal health cache. Failure revokes restricted
+eligibility until external work confirms readiness. A worker rechecks before inference;
+no initialization, health polling, retry or backend fallback is allowed. Cold or
+busy workers refuse immediately without queueing, spawning or scaling.
+
+Read-only admission samples existing host/ledger state without creating locks,
+reservations, pruning records or changing containment markers. Existing Darwin
+inference requires known-normal aggregate resources even if ordinary expansion
+uses a looser policy. Other platforms retain the existing no-footprint-probe
+policy; this is not a cross-platform native qualification claim.
+An absent ledger in a fresh `critical-only` home is sampled as empty without being
+created; existing corrupt or symlinked ledgers still refuse. Markdown coverage
+and returned pointers require regular files, including after symlink resolution;
+a directory whose name ends in `.md` can be a prefix but never a source pointer.
+
+Cancellation closes only the request/owned bridge. It rejects the caller and
+discards late results; an already executing shared worker remains assigned until
+its terminal response or exit. Caller deadlines/heartbeats cannot trigger worker
+replacement or native session initialization. Idle RSS retirement and consecutive
+oversized completions remain enforced, including after restricted work, without
+filling the worker floor on that path. Further restricted calls then report
+unavailable; ordinary work may expand under ordinary admission. Busy inference is
+never interrupted by RSS retirement. The daemon's independent safety/shutdown
+machinery remains authoritative.
+
+Native retrieval receives the remaining overall deadline and holds its shared
+operation until the actual native promise settles. A JavaScript timer cannot
+release resources that native code still uses. Caller cancellation/bridge timeout
+remains bounded and late results are discarded. If the SDK fails to settle even
+after its native deadline, exclusive resource teardown stays blocked rather than
+closing underneath the read; no worker/store replacement is induced to hide the
+failure. Cancellation cannot interrupt an already running ONNX native call.
+Global logging settings are unchanged, and this path never logs query text.
+
+## Isolated qualification
+
+Use `node scripts/build-document-search-candidate.cjs /absolute/new/output` to
+compile/package without overwriting `dist`, installing, publishing, or invoking
+lifecycle scripts. The script copies the pinned native JS runtime with provenance.
+`node scripts/audit-document-search.cjs /absolute/extracted/package` exercises a
+synthetic daemon and checks packaged files/import boundaries. The normal consumer
+audit invokes that check against its freshly installed tarball too.
+
+The optional Runlist fixture is
+`RUNLIST_GMAX_QUALIFICATION_ENTRY=/absolute/extracted/package/dist/bin.js node --test desktop/test/semantic-gmax-contract.test.mjs`.
+Fixture homes/IPC are private temporary directories; no real daemon, index,
+watcher, model or grammar download is used. Reusing checkout dependencies for a
+local package probe must be reported separately from fresh dependency resolution.
+Installation, a shared-daemon restart, watcher recovery and live retrieval require
+separate explicit actions. Source/package fixture success proves none of those.

package/README.md

@@ -223,6 +223,30 @@ 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.
 
+Surprises excludes generated code, bindings, fixtures and GraphQL schema/operation output by default. Use CLI `--include-generated` or MCP `include_generated: true` to include these families; `--include-tests` / `include_tests` controls test files separately.
+
+### Analysis coverage and compact output
+
+Project overviews disclose when their language, directory, role and symbol breakdowns cover the first 200,000 chunks. CLI and MCP output label sampled chunk/file counts and show the full project chunk inventory separately. Inventory counting streams only paths in small batches with an execution deadline.
+
+Architecture audits omit unresolved same-name definitions from rankings, cycles and dead-code claims, and report the number omitted. Compact CLI audit and MCP cycle rows retain total file/edge counts and show up to eight complete paths within 1,000 characters, with an explicit omitted-file count.
+
+CLI `gmax skeleton --agent` and MCP `code_skeleton` text show at most 120 lines / 6,000 characters per file and report omitted lines and characters. CLI human output and JSON structure remain complete.
+
+## Existing-index document search
+
+`gmax mcp --existing-index-only` exposes a separate read-only stdio MCP contract
+for Markdown document coverage and semantic pointers. It uses an existing daemon,
+index and already-warm compatible query worker. It cannot start a daemon, watch a
+project, initialize a model, fall back to another backend or mutate the index.
+Cold, busy or unavailable resources return an explicit unavailable state.
+
+Results contain canonical paths and one-based source ranges, without cached source
+bodies. The first slice uses dense retrieval with explicit path scope and bounded
+deadlines. Consumers must reread and authorize current source before using a
+pointer. See [the document-search contract](DOCUMENT-SEARCH.md) for tool schemas,
+limits, hash provenance and isolated qualification.
+
 ## Background Daemon
 
 A single daemon watches your projects via native OS file events (FSEvents/inotify). Changes are detected in sub-second and incrementally reindexed. All writes to LanceDB are routed through the daemon via IPC, eliminating lock contention.

package/dist/bin.js

@@ -152,6 +152,15 @@ function seedConfig(home) {
     }
 }
 if (require.main === module) {
-    selectHome();
-    require("./index");
+    if (process.argv.slice(2).join(" ") === "mcp --existing-index-only") {
+        require("./lib/mcp/document-search").runDocumentSearchBridge();
+    }
+    else if (process.argv.includes("--existing-index-only")) {
+        process.stderr.write("gmax: use exactly mcp --existing-index-only\n");
+        process.exitCode = 2;
+    }
+    else {
+        selectHome();
+        require("./index");
+    }
 }

package/dist/commands/audit.js

@@ -43,8 +43,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.audit = void 0;
+exports.formatHuman = formatHuman;
+exports.formatAgent = formatAgent;
 const commander_1 = require("commander");
 const graph_handler_1 = require("../lib/daemon/graph-handler");
+const agent_budget_1 = require("../lib/output/agent-budget");
 const vector_db_1 = require("../lib/store/vector-db");
 const exit_1 = require("../lib/utils/exit");
 const project_registry_1 = require("../lib/utils/project-registry");
@@ -67,6 +70,8 @@ function formatCycle(files) {
 function formatHuman(r) {
     const out = [];
     out.push(`${style.bold("Audit")} ${style.dim(`— ${r.scannedChunks} chunks across ${r.scannedFiles} files`)}`);
+    if (r.ambiguousSymbols)
+        out.push(`Unresolved symbol names omitted: ${r.ambiguousSymbols}`);
     out.push("");
     out.push(style.bold("God nodes") + style.dim(" (most depended-upon symbols)"));
     if (r.godNodes.length === 0) {
@@ -122,8 +127,10 @@ function formatHuman(r) {
     return out.join("\n");
 }
 function formatAgent(r) {
+    var _a;
     const lines = [];
     lines.push(`scanned\t${r.scannedChunks}\t${r.scannedFiles}`);
+    lines.push(`ambiguous_symbols_omitted\t${(_a = r.ambiguousSymbols) !== null && _a !== void 0 ? _a : 0}`);
     for (const g of r.godNodes) {
         const ambiguous = g.defFiles > 1 ? `\tdefs=${g.defFiles}` : "";
         lines.push(`god\t${g.symbol}\t${g.file}:${g.line + 1}\t${g.inboundFiles}\t${g.totalRefs}${ambiguous}`);
@@ -132,7 +139,8 @@ function formatAgent(r) {
         lines.push(`hub\t${h.file}\t${h.dependents}\t${h.defines}\t${h.fanOut}`);
     }
     for (const c of r.fileCycles) {
-        lines.push(`cycle\t${c.files.join(",")}\t${c.files.length}\t${c.edgeCount}`);
+        const shown = (0, agent_budget_1.boundedAgentList)(c.files);
+        lines.push(`cycle\t${shown.text}\t${c.files.length}\t${c.edgeCount}\tomitted_files=${shown.omitted}`);
     }
     for (const d of r.deadCandidates) {
         lines.push(`dead\t${d.symbol}\t${d.file}:${d.line + 1}`);

package/dist/commands/mcp.js

@@ -83,9 +83,11 @@ const embedding_generation_1 = require("../lib/index/embedding-generation");
 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_budget_1 = require("../lib/output/agent-budget");
 const agent_search_formatter_1 = require("../lib/output/agent-search-formatter");
 const index_state_footer_1 = require("../lib/output/index-state-footer");
 const mcp_results_1 = require("../lib/output/mcp-results");
+const project_coverage_1 = require("../lib/output/project-coverage");
 const searcher_1 = require("../lib/search/searcher");
 const annotator_1 = require("../lib/skeleton/annotator");
 const skeletonizer_1 = require("../lib/skeleton/skeletonizer");
@@ -1133,7 +1135,7 @@ exports.mcp = new commander_1.Command("mcp")
                     const annotated = sourceContent
                         ? (0, annotator_1.annotateSkeletonLines)(skeleton, sourceContent)
                         : skeleton;
-                    parts.push(`// ${t} (~${tokenEstimate} tokens)\n\n${annotated}`);
+                    parts.push(`// ${t} (~${tokenEstimate} tokens)\n\n${(0, agent_budget_1.boundedAgentText)(annotated)}`);
                 }
             }
             if (fmt === "json") {
@@ -1518,6 +1520,8 @@ exports.mcp = new commander_1.Command("mcp")
                 }
                 const lines = [];
                 lines.push(`Audit — ${audit.scannedChunks} chunks across ${audit.scannedFiles} files`);
+                if (audit.ambiguousSymbols)
+                    lines.push(`Unresolved symbol names omitted: ${audit.ambiguousSymbols}`);
                 lines.push("");
                 lines.push("God nodes (most depended-upon symbols):");
                 for (const g of audit.godNodes) {
@@ -1535,7 +1539,8 @@ exports.mcp = new commander_1.Command("mcp")
                 lines.push("");
                 lines.push("File dependency cycles (symbol-derived):");
                 for (const c of audit.fileCycles) {
-                    lines.push(`  ${c.files.join(", ")} - ${c.files.length} files, ${c.edgeCount} internal edges`);
+                    const shown = (0, agent_budget_1.boundedAgentList)(c.files);
+                    lines.push(`  ${shown.text} - ${c.files.length} files, ${c.edgeCount} internal edges; omitted_files=${shown.omitted}`);
                 }
                 if (audit.fileCycles.length === 0)
                     lines.push("  none");
@@ -1581,6 +1586,7 @@ exports.mcp = new commander_1.Command("mcp")
                 maxRows,
                 includeTests: Boolean(args.include_tests),
                 includeEval: Boolean(args.include_eval),
+                includeGenerated: Boolean(args.include_generated),
                 in: typeof args.in === "string" ? [args.in] : undefined,
                 exclude: typeof args.exclude === "string" ? [args.exclude] : undefined,
             };
@@ -1990,7 +1996,10 @@ exports.mcp = new commander_1.Command("mcp")
                 const pct = (count) => Math.round((count / overview.chunks) * 100);
                 const lines = [];
                 lines.push(`Project: ${projectName} (${root})`);
-                lines.push(`Last indexed: ${(_a = proj.lastIndexed) !== null && _a !== void 0 ? _a : "unknown"} • ${overview.chunks} chunks • ${overview.files} files`);
+                lines.push(`Last indexed: ${(_a = proj.lastIndexed) !== null && _a !== void 0 ? _a : "unknown"} • ${(0, project_coverage_1.projectCounts)(overview)}`);
+                const coverage = (0, project_coverage_1.projectCoverageNotice)(overview);
+                if (coverage)
+                    lines.push(`Coverage: ${coverage}`);
                 lines.push("");
                 lines.push(`Languages: ${overview.extEntries
                     .map(([ext, count]) => `${ext} (${pct(count)}%)`)
@@ -2976,6 +2985,10 @@ exports.mcp = new commander_1.Command("mcp")
                     .boolean()
                     .describe("Include eval/experiment/script files")
                     .optional(),
+                include_generated: zod_1.z
+                    .boolean()
+                    .describe("Include generated code, bindings and fixtures")
+                    .optional(),
             },
         }, handleSurprisingConnections);
         tool("get_neighbors", {

package/dist/commands/project.js

@@ -46,6 +46,7 @@ exports.project = void 0;
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const rows_handler_1 = require("../lib/daemon/rows-handler");
+const project_coverage_1 = require("../lib/output/project-coverage");
 const daemon_client_1 = require("../lib/utils/daemon-client");
 const exit_1 = require("../lib/utils/exit");
 const project_registry_1 = require("../lib/utils/project-registry");
@@ -80,9 +81,12 @@ exports.project = new commander_1.Command("project")
         const projects = (0, project_registry_1.listProjects)();
         const proj = projects.find((p) => p.root === root);
         const { chunks, files, extEntries, dirEntries, roleEntries, topSymbols, entryPoints, } = overview;
+        const coverage = (0, project_coverage_1.projectCoverageNotice)(overview);
         if (opts.agent) {
             console.log(`name\t${projectName}`);
             console.log(`root\t${root}`);
+            if (coverage)
+                console.log(`coverage\t${coverage}`);
             console.log(`chunks\t${chunks}`);
             console.log(`files\t${files}`);
             console.log(`last_indexed\t${(_b = proj === null || proj === void 0 ? void 0 : proj.lastIndexed) !== null && _b !== void 0 ? _b : "unknown"}`);
@@ -100,7 +104,9 @@ exports.project = new commander_1.Command("project")
         }
         else {
             console.log(`Project: ${projectName} (${root})`);
-            console.log(`Last indexed: ${(_c = proj === null || proj === void 0 ? void 0 : proj.lastIndexed) !== null && _c !== void 0 ? _c : "unknown"} • ${chunks} chunks • ${files} files\n`);
+            console.log(`Last indexed: ${(_c = proj === null || proj === void 0 ? void 0 : proj.lastIndexed) !== null && _c !== void 0 ? _c : "unknown"} • ${(0, project_coverage_1.projectCounts)(overview)}\n`);
+            if (coverage)
+                console.log(`Coverage: ${coverage}\n`);
             console.log(`Languages: ${extEntries.map(([ext, count]) => `${ext} (${Math.round((count / chunks) * 100)}%)`).join(", ")}\n`);
             console.log("Directory structure:");
             for (const [dir, data] of dirEntries) {

package/dist/commands/skeleton.js

@@ -1,12 +1,4 @@
 "use strict";
-/**
- * gmax skeleton - Show code skeleton (signatures without implementation)
- *
- * Usage:
- *   gmax skeleton <file>           # Skeleton of a file
- *   gmax skeleton <symbol>         # Find symbol and skeleton its file
- *   gmax skeleton "query"          # Search and skeleton top results
- */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -51,6 +43,15 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.skeleton = void 0;
+const agent_budget_1 = require("../lib/output/agent-budget");
+/**
+ * gmax skeleton - Show code skeleton (signatures without implementation)
+ *
+ * Usage:
+ *   gmax skeleton <file>           # Skeleton of a file
+ *   gmax skeleton <symbol>         # Find symbol and skeleton its file
+ *   gmax skeleton "query"          # Search and skeleton top results
+ */
 const fs = __importStar(require("node:fs"));
 const commander_1 = require("commander");
 const config_1 = require("../config");
@@ -392,7 +393,9 @@ Examples:
             }
             else {
                 for (const result of results) {
-                    console.log(result.skeleton);
+                    console.log(options.agent
+                        ? (0, agent_budget_1.boundedAgentText)(result.skeleton)
+                        : result.skeleton);
                     console.log(""); // Blank line between files
                 }
             }
@@ -423,6 +426,6 @@ function outputResult(result, options) {
         }, null, 2));
     }
     else {
-        console.log(result.skeleton);
+        console.log(options.agent ? (0, agent_budget_1.boundedAgentText)(result.skeleton) : result.skeleton);
     }
 }

package/dist/commands/surprises.js

@@ -132,6 +132,7 @@ exports.surprises = new commander_1.Command("surprises")
     .option("--min-sim <n>", "Minimum similarity 0-1", String(surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.minSimilarity))
     .option("--max-rows <n>", `Maximum indexed rows to scan (capped at ${surprising_connections_1.MAX_SURPRISE_ROWS})`, String(surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.maxRows))
     .option("--include-tests", "Include test files", false)
+    .option("--include-generated", "Include generated code, bindings and fixtures", false)
     .option("--include-eval", "Include eval/experiment/script files", false)
     .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])
@@ -180,6 +181,7 @@ exports.surprises = new commander_1.Command("surprises")
             maxRows: parseIntOption(opts.maxRows, surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.maxRows, surprising_connections_1.MAX_SURPRISE_ROWS),
             includeTests: Boolean(opts.includeTests),
             includeEval: Boolean(opts.includeEval),
+            includeGenerated: Boolean(opts.includeGenerated),
             in: analysisIn,
             exclude: analysisExclude,
         };

package/dist/lib/analysis/surprising-connections.js

@@ -45,6 +45,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SURPRISE_COLUMNS = exports.MAX_SURPRISE_ROWS = exports.DEFAULT_SURPRISE_OPTIONS = void 0;
 exports.normalizeSurpriseOptions = normalizeSurpriseOptions;
 exports.isTestPath = isTestPath;
+exports.isGeneratedPath = isGeneratedPath;
 exports.isEvalPath = isEvalPath;
 exports.relPath = relPath;
 exports.lineLabel = lineLabel;
@@ -73,6 +74,7 @@ exports.DEFAULT_SURPRISE_OPTIONS = {
     maxRows: 50000,
     includeTests: false,
     includeEval: false,
+    includeGenerated: false,
 };
 exports.MAX_SURPRISE_ROWS = 100000;
 /**
@@ -152,8 +154,8 @@ const TEST_FILE_RE = /\.(test|spec)\.[cm]?[jt]sx?$/i;
 const NATIVE_TEST_DIR_RE = /(^|\/)\w+Tests?(\/|$)/;
 const NATIVE_TEST_FILE_RE = /Tests?\.(swift|kt|java)$/;
 function normalizeSurpriseOptions(opts = {}) {
-    var _a, _b, _c, _d, _e, _f, _g;
-    return Object.assign(Object.assign(Object.assign({}, exports.DEFAULT_SURPRISE_OPTIONS), opts), { sample: Math.max(1, Math.floor((_a = opts.sample) !== null && _a !== void 0 ? _a : exports.DEFAULT_SURPRISE_OPTIONS.sample)), neighbors: Math.max(1, Math.floor((_b = opts.neighbors) !== null && _b !== void 0 ? _b : exports.DEFAULT_SURPRISE_OPTIONS.neighbors)), dirDepth: Math.max(1, Math.floor((_c = opts.dirDepth) !== null && _c !== void 0 ? _c : exports.DEFAULT_SURPRISE_OPTIONS.dirDepth)), minSimilarity: Math.max(0, (_d = opts.minSimilarity) !== null && _d !== void 0 ? _d : exports.DEFAULT_SURPRISE_OPTIONS.minSimilarity), maxRows: Math.max(1, Math.min(exports.MAX_SURPRISE_ROWS, Math.floor((_e = opts.maxRows) !== null && _e !== void 0 ? _e : exports.DEFAULT_SURPRISE_OPTIONS.maxRows))), includeTests: (_f = opts.includeTests) !== null && _f !== void 0 ? _f : exports.DEFAULT_SURPRISE_OPTIONS.includeTests, includeEval: (_g = opts.includeEval) !== null && _g !== void 0 ? _g : exports.DEFAULT_SURPRISE_OPTIONS.includeEval });
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    return Object.assign(Object.assign(Object.assign({}, exports.DEFAULT_SURPRISE_OPTIONS), opts), { sample: Math.max(1, Math.floor((_a = opts.sample) !== null && _a !== void 0 ? _a : exports.DEFAULT_SURPRISE_OPTIONS.sample)), neighbors: Math.max(1, Math.floor((_b = opts.neighbors) !== null && _b !== void 0 ? _b : exports.DEFAULT_SURPRISE_OPTIONS.neighbors)), dirDepth: Math.max(1, Math.floor((_c = opts.dirDepth) !== null && _c !== void 0 ? _c : exports.DEFAULT_SURPRISE_OPTIONS.dirDepth)), minSimilarity: Math.max(0, (_d = opts.minSimilarity) !== null && _d !== void 0 ? _d : exports.DEFAULT_SURPRISE_OPTIONS.minSimilarity), maxRows: Math.max(1, Math.min(exports.MAX_SURPRISE_ROWS, Math.floor((_e = opts.maxRows) !== null && _e !== void 0 ? _e : exports.DEFAULT_SURPRISE_OPTIONS.maxRows))), includeTests: (_f = opts.includeTests) !== null && _f !== void 0 ? _f : exports.DEFAULT_SURPRISE_OPTIONS.includeTests, includeEval: (_g = opts.includeEval) !== null && _g !== void 0 ? _g : exports.DEFAULT_SURPRISE_OPTIONS.includeEval, includeGenerated: (_h = opts.includeGenerated) !== null && _h !== void 0 ? _h : false });
 }
 function isTestPath(filePath) {
     return (TEST_DIR_RE.test(filePath) ||
@@ -161,6 +163,11 @@ function isTestPath(filePath) {
         NATIVE_TEST_DIR_RE.test(filePath) ||
         NATIVE_TEST_FILE_RE.test(filePath));
 }
+function isGeneratedPath(filePath) {
+    return (/(^|\/)(?:generated|__generated__|bindings|fixtures|__fixtures__)(\/|$)/i.test(filePath) ||
+        /\.generated\.[^.]+$/i.test(filePath) ||
+        /\/[^/]*GraphQL\/Sources\/(?:Schema|Operations)\//i.test(filePath));
+}
 function isEvalPath(filePath) {
     return (/(^|\/)src\/eval[^/]*\.ts$/i.test(filePath) ||
         /(^|\/)(benchmarks?|experiments|scripts)(\/|$)/i.test(filePath));
@@ -477,6 +484,8 @@ function filterableCodeMeta(row, opts) {
         return false;
     if (!opts.includeEval && isEvalPath(row.relPath))
         return false;
+    if (!opts.includeGenerated && isGeneratedPath(row.relPath))
+        return false;
     return row.definedSymbols.length > 0;
 }
 function hasCodeContent(content) {
@@ -633,6 +642,7 @@ function analyzeSurprisingConnections(table_1, projectRoot_1) {
             weakCode: 0,
             tests: 0,
             evalHarness: 0,
+            generated: 0,
             sameDirBucket: 0,
             graphEdge: 0,
             belowThreshold: 0,
@@ -671,6 +681,10 @@ function analyzeSurprisingConnections(table_1, projectRoot_1) {
                     filters.tests++;
                     continue;
                 }
+                if (!opts.includeGenerated && isGeneratedPath(target.relPath)) {
+                    filters.generated++;
+                    continue;
+                }
                 if (!opts.includeEval && isEvalPath(target.relPath)) {
                     filters.evalHarness++;
                     continue;

package/dist/lib/daemon/daemon.js

@@ -84,6 +84,7 @@ const root_availability_1 = require("../utils/root-availability");
 const safety_latch_1 = require("../utils/safety-latch");
 const watcher_store_1 = require("../utils/watcher-store");
 const pool_1 = require("../workers/pool");
+const document_search_handler_1 = require("./document-search-handler");
 const ipc_handler_1 = require("./ipc-handler");
 const mlx_server_manager_1 = require("./mlx-server-manager");
 const paused_reads_1 = require("./paused-reads");
@@ -1021,6 +1022,55 @@ class Daemon {
             ? { queue: progress.queue }
             : {})), { failedFiles: Math.max((_d = progress === null || progress === void 0 ? void 0 : progress.failedFiles) !== null && _d !== void 0 ? _d : 0, (_e = health.failedFiles) !== null && _e !== void 0 ? _e : 0) });
     }
+    /** Separate shared-operation path: never paused keyword fallback or runtime setup. */
+    documentSearch(cmd, signal) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const state = () => this.pausedReason !== null || (0, autostart_1.daemonStartDeniedReason)()
+                ? "host_pressure"
+                : this.shuttingDown || this.recycling
+                    ? "busy"
+                    : !this.vectorDb || !this.metaCache
+                        ? "store_unavailable"
+                        : this.activeConfigurationError()
+                            ? "embedding_mismatch"
+                            : "ready";
+            return this.operations.runShared("documents", signal, (operationSignal) => (0, document_search_handler_1.handleDocumentSearch)({
+                home: config_1.PATHS.globalRoot,
+                state,
+                generation: () => this.resourceGenerationId(),
+                embeddingState: (root) => {
+                    const project = (0, project_registry_1.getProject)(root);
+                    if ((project === null || project === void 0 ? void 0 : project.status) !== "indexed")
+                        return "no_index";
+                    if (!this.activeGeneration)
+                        return "embedding_unavailable";
+                    if (this.workerPool &&
+                        this.workerPool.generation.fingerprint !==
+                            this.activeGeneration.fingerprint)
+                        return "embedding_mismatch";
+                    try {
+                        return (0, embedding_generation_1.compareEmbeddingGeneration)(project, this.activeGeneration)
+                            .state === "stale"
+                            ? "embedding_mismatch"
+                            : "ready";
+                    }
+                    catch (_a) {
+                        return "embedding_mismatch";
+                    }
+                },
+                meta: (file) => { var _a; return (_a = this.metaCache) === null || _a === void 0 ? void 0 : _a.get(file); },
+                queryState: () => { var _a; var _b; return (_b = (_a = this.workerPool) === null || _a === void 0 ? void 0 : _a.existingQueryState()) !== null && _b !== void 0 ? _b : "embedding_unavailable"; },
+                encode: (query, requestSignal) => this.workerPool
+                    ? this.workerPool.encodeQueryExisting(query, requestSignal)
+                    : Promise.reject(new Error("embedding_unavailable")),
+                table: () => this.vectorDb
+                    ? this.vectorDb.existingTableForRead()
+                    : Promise.reject(new Error("store_unavailable")),
+                indexState: (root) => this.indexState(root),
+                lastIndexed: (root) => { var _a; return (_a = (0, project_registry_1.getProject)(root)) === null || _a === void 0 ? void 0 : _a.lastIndexed; },
+            }, cmd, operationSignal));
+        });
+    }
     search(payload, signal) {
         return __awaiter(this, void 0, void 0, function* () {
             // Search handling lives in search-handler.ts (Phase 12 split). The daemon