grepmax 0.26.49 → 0.26.50

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

package/README.md

@@ -205,6 +205,8 @@ gmax "query" [options]
 | `--exclude-projects <list>` | With `--all-projects`, skip these projects. | — |
 | `--min-score <n>` | Minimum score relative to this query’s top match, not an absolute confidence threshold. | `0` |
 
+v0.26.50 carries an explicit `--per-file` value into retrieval as well as formatting. Values must be positive safe integers. Omitted requests retain the searcher's configured `GMAX_MAX_PER_FILE` cap or three; larger explicit values still respect `-m` and the existing candidate/rerank bounds. Explicit overrides require a daemon advertising `capabilities.perFileSearch: 1`; older live daemons are refused with an update/restart hint, without opening a fallback reader. An incompatible optional local HTTP fast path is skipped. v0.26.49 and older releases do not support this retrieval override.
+
 ## 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.
@@ -399,7 +401,7 @@ embedding paths, with and without ColBERT rerank:
 | `small` / 384d | **0.72** | **0.51** |
 | `standard` / 768d | 0.62 | 0.44 |
 
-<sub>Historical gmax-repo comparison: 97 cases, MLX GPU, rerank off. CPU/q4 and rerank-on comparisons showed a similar gap. These figures are not a v0.26.48 benchmark; see the evaluation caveats below.</sub>
+<sub>Historical gmax-repo comparison: 97 cases, MLX GPU, rerank off. CPU/q4 and rerank-on comparisons showed a similar gap. These figures are not a current-release benchmark; see the evaluation caveats below.</sub>
 
 The larger tier performed worse on that fixture and doubles dense-vector width; compute and memory costs depend on the backend.
 Unless you have a measured reason to switch (e.g. a recall complaint on a very
@@ -484,7 +486,7 @@ whether you need to act.
 | `disabling auto-rebuild until an optimize succeeds` | Transient, not a wedge. The next successful optimize clears it. Search stays available. |
 | `ANN: vector index not built` | Normal — exact search is the default. |
 | `cannot reach the daemon socket from this sandbox` (exit 2) | The shell is sandboxed. Add the two keys in [Running under the Claude Code sandbox](#running-under-the-claude-code-sandbox); `gmax doctor` warns about the same gap. |
-| `npm audit` reports advisories on install | v0.26.48 passed production and fresh packed-consumer audits. Audit findings can change: record the installed version and dependency path and report new findings; do not assume historical advisories still apply. |
+| `npm audit` reports advisories on install | v0.26.49 passed production and fresh packed-consumer audits. Audit findings can change: record the installed version and dependency path and report new findings; do not assume historical advisories still apply. |
 
 ## Contributing
 
@@ -504,7 +506,7 @@ GMAX_EVAL_RERANK=1 pnpm bench:oss   # toggle ColBERT rerank
 
 The OSS harness expects indexed express, lodash and platform fixtures at the paths defined in [src/eval-oss.ts](src/eval-oss.ts). The historical comparison in [known limitations](docs/known-limitations.md#colbert-rerank-is-opt-in-shape-sensitive-helps-monolithic-files-hurts-modular-repos) combines these with the internal fixture: four datasets / 131 cases. It is not a current release acceptance run.
 
-Both retrieval harnesses request 20 results for diagnostics, but `mrrAt10` and Recall@10 credit only ranks 1–10. Later matches retain their actual ranks and count as found/hits, with zero reciprocal-rank credit. This cutoff was corrected in source after v0.26.48; historical MRR figures recorded before the correction may include ranks 11–20 and require a new run or rescoring before comparison. Also set `GMAX_CONCENTRATION_THRESHOLD=2` for a true rerank-off comparison: `GMAX_EVAL_RERANK=0` alone does not disable automatic concentration gating. Freeze fixtures and record source, embedding/index identity and ranking configuration before drawing conclusions.
+Both retrieval harnesses request 20 results for diagnostics, but `mrrAt10` and Recall@10 credit only ranks 1–10. Later matches retain their actual ranks and count as found/hits, with zero reciprocal-rank credit. This cutoff correction shipped in v0.26.49; historical MRR figures recorded before the correction may include ranks 11–20 and require a new run or rescoring before comparison. Also set `GMAX_CONCENTRATION_THRESHOLD=2` for a true rerank-off comparison: `GMAX_EVAL_RERANK=0` alone does not disable automatic concentration gating. Freeze fixtures and record source, embedding/index identity and ranking configuration before drawing conclusions.
 
 `pnpm bench:recall` also drives the model-tier comparison behind the 384d default — see [Model Tier](#model-tier) for why the larger 768d model is *not* the default.
 
@@ -521,13 +523,13 @@ pnpm bench:relevance --fixture docs/measurements/relevance/fixture-v1.json \
 
 The fixture schema is in [relevance-baseline.ts](src/lib/eval/relevance-baseline.ts). Its JSON contains `schemaVersion: 1`, `createdAt`, `purpose`, `corpora` and `cases`. Each corpus has an `id`, `root` (absolute or relative to the fixture) and `language`. Each case declares an `id`, `corpus`, `split` (`dev` or `heldout`), `origin` (`curated-source` or `observed-session`), `intent`, `query` and one or more `expected` targets. Targets require an exact relative `file`, definition `symbol`, one-based `startLine`/`endLine` and the SHA-256 of the source file.
 
-A hit requires the exact file and either the definition symbol or overlap with the declared line range. Choose answer-bearing ranges and reviewed alternatives: a declaration-only target can miss a useful function-body chunk. The October 4 baseline intentionally preserves its frozen declaration targets, so its 57.5% Recall@10 / 0.3275 MRR@10 describes target retrieval, not general answer quality. It covers 40 curated cases across TypeScript, JavaScript, Python and Swift; both repetitions produced identical ranks. These are not observed user-session misses or a ranking acceptance gate.
+A hit requires the exact file and either the definition symbol or overlap with the declared line range. The source runner also accepts target `match: "range"` to require range overlap without a symbol shortcut; omitted or `"symbol-or-range"` preserves legacy matching. Range overlap measures useful context discovery, not complete answer coverage. Choose answer-bearing ranges and reviewed alternatives: a declaration-only target can miss a useful function-body chunk. The October 4 baseline intentionally preserves its frozen declaration targets, so its 57.5% Recall@10 / 0.3275 MRR@10 describes target retrieval, not general answer quality. It covers 40 curated cases across TypeScript, JavaScript, Python and Swift; both repetitions produced identical ranks. These are not observed user-session misses or a ranking acceptance gate. Previously inspected cases must be treated as exposed development cases in successor measurements.
 
 The report records source/index hashes, registry embedding identity, daemon snapshots, exclusions, per-case ranks, aggregate metrics and ordinary-session latency. A sibling `.samples.jsonl` checkpoints each completed request; the final JSON applies run-wide exclusions and is authoritative. Changed source/cache hashes, missing targets, unsettled indexes, search warnings and daemon replacement invalidate samples. The runner refuses to overwrite artifacts and exits 2 when any samples are excluded.
 
 Requests use `rerank: false`, but the daemon's concentration gate can still enable reranking. Client environment settings cannot change an existing daemon's settings, and `scoreBreakdown.rerank` also holds the fallback base score when reranking is off.
 
-Source now supports `--diagnostics`. This requires a ready daemon advertising `capabilities.searchDiagnostics: 1`; v0.26.48's installed release does not advertise it. The evaluator refuses incompatible daemons before measuring and excludes responses missing requested diagnostics. Each sample records FTS availability/failure, effective settings and allowlisted daemon ranking environment, concentration-gate evaluation/activation and whether reranking was actually invoked.
+v0.26.49 supports `--diagnostics`. This requires a ready daemon advertising `capabilities.searchDiagnostics: 1`; older daemons without that capability require an update. The evaluator refuses incompatible daemons before measuring and excludes responses missing requested diagnostics. Each sample records FTS availability/failure, effective settings and allowlisted daemon ranking environment, concentration-gate evaluation/activation and whether reranking was actually invoked.
 
 The candidate trace contains pointers and stage ranks for at most the first 200 post-seed fusion candidates, plus full stage counts and an explicit truncation flag. Ranks cover vector/FTS, RRF, seeded fusion, stage-one selection, pooled filtering, selected rerank batch, final scoring, overlap deduplication and final display. Rerank-batch membership does not imply execution; use `gate.rerankInvoked`. Zero at a later stage means a traced candidate was removed; a target missing from a truncated trace may lie outside the reported head. Diagnostics add no database reads and preserve ranking/results. The frozen October 4 artifacts retain their original unknowns. Review ground truth and collect new diagnostic artifacts before tuning.
 

package/dist/commands/search-output.js

@@ -48,6 +48,7 @@ const path = __importStar(require("node:path"));
 const agent_search_formatter_1 = require("../lib/output/agent-search-formatter");
 const compact_results_1 = require("../lib/output/compact-results");
 const index_state_footer_1 = require("../lib/output/index-state-footer");
+const per_file_1 = require("../lib/search/per-file");
 const cross_project_1 = require("../lib/utils/cross-project");
 const formatter_1 = require("../lib/utils/formatter");
 const import_extractor_1 = require("../lib/utils/import-extractor");
@@ -69,14 +70,26 @@ const search_skeletons_1 = require("./search-skeletons");
  */
 function executeServerSearch(params) {
     return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        var _b;
         const { server, pattern, exec_path, projectRootForServer, options, minScore, } = params;
+        const maxPerFile = (0, per_file_1.parseCliPerFile)(options.perFile);
         try {
+            if (maxPerFile !== undefined) {
+                const health = yield fetch(`http://127.0.0.1:${server.port}/health`);
+                if (!health.ok)
+                    return false;
+                const info = (yield health.json());
+                if (((_a = info.capabilities) === null || _a === void 0 ? void 0 : _a.perFileSearch) !== 1)
+                    return false;
+            }
             const response = yield fetch(`http://127.0.0.1:${server.port}/search`, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({
                     query: pattern,
                     limit: parseInt(options.m, 10),
+                    maxPerFile,
                     path: exec_path
                         ? path.relative(projectRootForServer, path.resolve(exec_path))
                         : undefined,
@@ -161,7 +174,7 @@ function executeServerSearch(params) {
                         isPlain: true,
                         compact: options.compact,
                         content: options.content,
-                        perFile: parseInt(options.perFile, 10),
+                        perFile: parseInt((_b = options.perFile) !== null && _b !== void 0 ? _b : "3", 10),
                         showScores: options.scores,
                     });
                     console.log(output);
@@ -195,7 +208,7 @@ function executeServerSearch(params) {
 function renderSearchOutput(params) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c;
-        var _d, _e, _f, _g;
+        var _d, _e, _f, _g, _h, _j;
         const { searchResult, options, minScore, crossProject, pattern, effectiveRoot, projectRoot, vectorDb, precomputedSkeletons, precomputedGraph, indexState, } = params;
         if (!options.agent && ((_a = searchResult.warnings) === null || _a === void 0 ? void 0 : _a.length)) {
             for (const w of searchResult.warnings) {
@@ -220,7 +233,7 @@ function renderSearchOutput(params) {
                     return defs.some((d) => regex.test(d));
                 });
             }
-            catch (_h) {
+            catch (_k) {
                 // Invalid regex — skip
             }
         }
@@ -293,7 +306,7 @@ function renderSearchOutput(params) {
                         isPlain: true,
                         compact: options.compact,
                         content: options.content,
-                        perFile: parseInt(options.perFile, 10),
+                        perFile: parseInt((_d = options.perFile) !== null && _d !== void 0 ? _d : "3", 10),
                         showScores: options.scores,
                     });
                 }
@@ -355,7 +368,7 @@ function renderSearchOutput(params) {
                         }
                     }
                 }
-                catch (_j) { }
+                catch (_l) { }
             }
             // Partial-index footer last, so it's the final line the agent reads —
             // and emitted even on "(none)", where an empty result may just mean the
@@ -453,7 +466,7 @@ function renderSearchOutput(params) {
         if (options.imports) {
             const seenFiles = new Set();
             for (const r of filteredData) {
-                const absP = (_e = (_d = r.path) !== null && _d !== void 0 ? _d : (_b = r.metadata) === null || _b === void 0 ? void 0 : _b.path) !== null && _e !== void 0 ? _e : "";
+                const absP = (_f = (_e = r.path) !== null && _e !== void 0 ? _e : (_b = r.metadata) === null || _b === void 0 ? void 0 : _b.path) !== null && _f !== void 0 ? _f : "";
                 if (absP && !seenFiles.has(absP)) {
                     seenFiles.add(absP);
                     const imports = getImportsForFile(absP);
@@ -472,7 +485,7 @@ function renderSearchOutput(params) {
                 isPlain: true,
                 compact: options.compact,
                 content: options.content,
-                perFile: parseInt(options.perFile, 10),
+                perFile: parseInt((_g = options.perFile) !== null && _g !== void 0 ? _g : "3", 10),
                 showScores: options.scores,
             });
             console.log(output);
@@ -480,7 +493,7 @@ function renderSearchOutput(params) {
                 for (const r of filteredData) {
                     const b = r.scoreBreakdown;
                     if (b) {
-                        const absP = (_g = (_f = r.path) !== null && _f !== void 0 ? _f : (_c = r.metadata) === null || _c === void 0 ? void 0 : _c.path) !== null && _g !== void 0 ? _g : "";
+                        const absP = (_j = (_h = r.path) !== null && _h !== void 0 ? _h : (_c = r.metadata) === null || _c === void 0 ? void 0 : _c.path) !== null && _j !== void 0 ? _j : "";
                         const relPath = absP.startsWith(projectRoot)
                             ? absP.slice(projectRoot.length + 1)
                             : absP;
@@ -542,7 +555,7 @@ function renderSearchOutput(params) {
                     console.log(lines.join("\n"));
                 }
             }
-            catch (_k) {
+            catch (_m) {
                 // Trace failed — skip silently
             }
         }

package/dist/commands/search-run.js

@@ -51,6 +51,7 @@ const grammar_loader_1 = require("../lib/index/grammar-loader");
 const index_config_1 = require("../lib/index/index-config");
 const sync_helpers_1 = require("../lib/index/sync-helpers");
 const syncer_1 = require("../lib/index/syncer");
+const per_file_1 = require("../lib/search/per-file");
 const searcher_1 = require("../lib/search/searcher");
 const vector_db_1 = require("../lib/store/vector-db");
 const lock_1 = require("../lib/utils/lock");
@@ -76,6 +77,7 @@ function runSearch(params) {
         var _a, _b;
         var _c;
         const { pattern, options, projectRoot, effectiveRoot, paths, projectStatus, searchFilters, pathFilter, seeds, } = params;
+        const maxPerFile = (0, per_file_1.parseCliPerFile)(options.perFile);
         // Tracks a DB opened by the in-process path so it can be (a) returned to the
         // caller for closing after render, or (b) closed here if indexing throws.
         let openedDb = null;
@@ -96,13 +98,14 @@ function runSearch(params) {
             let indexState;
             if (!options.sync && !options.dryRun) {
                 try {
-                    const { sendDaemonCommand } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-client")));
+                    const { sendSearchCommand } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-search")));
                     const crossProject = Array.isArray(searchFilters.projectRoots);
-                    const resp = yield sendDaemonCommand({
+                    const resp = yield sendSearchCommand({
                         cmd: crossProject ? "search-v2" : "search",
                         projectRoot: effectiveRoot,
                         query: pattern,
                         limit: parseInt(options.m, 10),
+                        maxPerFile,
                         filters: Object.keys(searchFilters).length > 0 ? searchFilters : undefined,
                         pathPrefix: pathFilter,
                         rerank: process.env.GMAX_RERANK === "1",
@@ -253,6 +256,7 @@ function runSearch(params) {
                 const searcher = new searcher_1.Searcher(vectorDb);
                 searchResult = yield searcher.search(pattern, parseInt(options.m, 10), {
                     rerank: process.env.GMAX_RERANK === "1",
+                    maxPerFile,
                     explain: options.explain,
                     seeds,
                 }, Object.keys(searchFilters).length > 0

package/dist/commands/search.js

@@ -45,6 +45,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.search = void 0;
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
+const per_file_1 = require("../lib/search/per-file");
 const setup_helpers_1 = require("../lib/setup/setup-helpers");
 const cross_project_1 = require("../lib/utils/cross-project");
 const exit_1 = require("../lib/utils/exit");
@@ -61,7 +62,7 @@ exports.search = new commander_1.Command("search")
     .description("Search code by meaning (default command)")
     .option("-m <max_count>, --max-count <max_count>", "The maximum number of results to return (total)", "5")
     .option("-c, --content", "Show full chunk content instead of snippets", false)
-    .option("--per-file <n>", "Number of matches to show per file", "3")
+    .option("--per-file <n>", "Maximum retrieved matches per file (default: configured cap or 3)")
     .option("--scores", "Show relevance scores", false)
     .option("--explain", "Show scoring breakdown per result", false)
     .option("--context-for-llm", "Return full function body + imports per result", false)
@@ -105,6 +106,14 @@ Examples:
     var _a, _b, _c;
     var _d, _e, _f, _g;
     const options = cmd.optsWithGlobals();
+    try {
+        (0, per_file_1.parseCliPerFile)(options.perFile);
+    }
+    catch (error) {
+        console.error(error.message);
+        process.exitCode = 1;
+        return;
+    }
     const root = process.cwd();
     const minScore = Number.isFinite(Number.parseFloat(options.minScore))
         ? Number.parseFloat(options.minScore)

package/dist/commands/serve.js

@@ -64,8 +64,10 @@ const http = __importStar(require("node:http"));
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const config_1 = require("../config");
+const per_file_1 = require("../lib/search/per-file");
 const blocked_roots_1 = require("../lib/utils/blocked-roots");
 const daemon_client_1 = require("../lib/utils/daemon-client");
+const daemon_search_1 = require("../lib/utils/daemon-search");
 const exit_1 = require("../lib/utils/exit");
 const log_rotate_1 = require("../lib/utils/log-rotate");
 const path_containment_1 = require("../lib/utils/path-containment");
@@ -194,7 +196,7 @@ function createServeHttpServer(projectRoot, deps) {
         var _b, _c, _d;
         (_a = deps.onActivity) === null || _a === void 0 ? void 0 : _a.call(deps);
         if (req.method === "GET" && req.url === "/health") {
-            writeJson(res, 200, { status: "ok" });
+            writeJson(res, 200, { status: "ok", capabilities: { perFileSearch: 1 } });
             return;
         }
         const ac = new AbortController();
@@ -223,6 +225,13 @@ function createServeHttpServer(projectRoot, deps) {
                 const query = typeof body.query === "string" ? body.query.trim() : "";
                 if (!query)
                     throw new HttpRequestError(400, "invalid_query");
+                let maxPerFile;
+                try {
+                    maxPerFile = (0, per_file_1.validateMaxPerFile)(body.maxPerFile);
+                }
+                catch (_e) {
+                    throw new HttpRequestError(400, "invalid_maxPerFile");
+                }
                 const limit = body.limit === undefined ? 10 : body.limit;
                 if (typeof limit !== "number" ||
                     !Number.isInteger(limit) ||
@@ -262,12 +271,8 @@ function createServeHttpServer(projectRoot, deps) {
                 if (scope.excludePrefixes.length > 0) {
                     filters.excludePrefixes = scope.excludePrefixes;
                 }
-                const response = yield deps.search({
-                    query,
-                    limit,
-                    pathPrefix: scope.pathPrefix,
-                    filters: Object.keys(filters).length ? filters : undefined,
-                }, ac.signal);
+                const response = yield deps.search(Object.assign(Object.assign({ query,
+                    limit }, (maxPerFile === undefined ? {} : { maxPerFile })), { pathPrefix: scope.pathPrefix, filters: Object.keys(filters).length ? filters : undefined }), ac.signal);
                 if (!response.ok) {
                     writeJson(res, daemonErrorStatus(response.error), {
                         error: (_c = response.error) !== null && _c !== void 0 ? _c : "search_failed",
@@ -453,11 +458,12 @@ exports.serve = new commander_1.Command("serve")
             onActivity: () => {
                 lastActivity = Date.now();
             },
-            search: (input, signal) => (0, daemon_client_1.sendDaemonCommand)({
+            search: (input, signal) => (0, daemon_search_1.sendSearchCommand)({
                 cmd: "search",
                 projectRoot,
                 query: input.query,
                 limit: input.limit,
+                maxPerFile: input.maxPerFile,
                 pathPrefix: input.pathPrefix,
                 filters: input.filters,
                 rerank: true,

package/dist/lib/daemon/ipc-handler.js

@@ -50,6 +50,7 @@ exports.handleCommand = handleCommand;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const config_1 = require("../../config");
+const per_file_1 = require("../search/per-file");
 const logger_1 = require("../utils/logger");
 const operation_coordinator_1 = require("../utils/operation-coordinator");
 const path_containment_1 = require("../utils/path-containment");
@@ -153,6 +154,7 @@ function handleCommand(daemon, cmd, conn) {
                             exclusiveGenerationRebuild: exports.EXCLUSIVE_GENERATION_REBUILD_PROTOCOL,
                             readVerbs: read_verbs_1.READ_VERBS_PROTOCOL,
                             searchDiagnostics: 1,
+                            perFileSearch: 1,
                             // `watch`/`unwatch` accept holder/pid/ttlMs. A daemon without this
                             // treats `unwatch` as unwatch-for-everyone, so clients releasing a
                             // single lease must check it first.
@@ -232,6 +234,13 @@ function handleCommand(daemon, cmd, conn) {
                     conn.on("close", onClose);
                     try {
                         const limitRaw = typeof cmd.limit === "number" ? cmd.limit : 10;
+                        let maxPerFile;
+                        try {
+                            maxPerFile = (0, per_file_1.validateMaxPerFile)(cmd.maxPerFile);
+                        }
+                        catch (_m) {
+                            return { ok: false, error: "invalid maxPerFile" };
+                        }
                         if (!Number.isInteger(limitRaw) || limitRaw < 1 || limitRaw > 1000) {
                             return { ok: false, error: "invalid limit" };
                         }
@@ -296,6 +305,7 @@ function handleCommand(daemon, cmd, conn) {
                             projectRoot,
                             query,
                             limit: limitRaw,
+                            maxPerFile,
                             filters,
                             pathPrefix,
                             rerank: cmd.rerank === true,

package/dist/lib/daemon/search-handler.js

@@ -45,6 +45,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleDaemonSearch = handleDaemonSearch;
 const embedding_generation_1 = require("../index/embedding-generation");
 const index_state_footer_1 = require("../output/index-state-footer");
+const per_file_1 = require("../search/per-file");
 const searcher_1 = require("../search/searcher");
 const retriever_1 = require("../skeleton/retriever");
 const project_registry_1 = require("../utils/project-registry");
@@ -57,6 +58,13 @@ function handleDaemonSearch(deps, payload, signal) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c, _d;
         var _e, _f, _g;
+        let maxPerFile;
+        try {
+            maxPerFile = (0, per_file_1.validateMaxPerFile)(payload.maxPerFile);
+        }
+        catch (_h) {
+            return { ok: false, error: "invalid maxPerFile" };
+        }
         const { vectorDb, workerPool } = deps;
         if (!vectorDb || !workerPool) {
             return { ok: false, error: "daemon not ready" };
@@ -104,6 +112,7 @@ function handleDaemonSearch(deps, payload, signal) {
                 rerank: payload.rerank === true,
                 explain: payload.explain === true,
                 diagnostics: payload.diagnostics === true,
+                maxPerFile,
                 seeds: payload.seeds,
             }, payload.filters, payload.pathPrefix, undefined, signal);
         }
@@ -155,7 +164,7 @@ function handleDaemonSearch(deps, payload, signal) {
                     if (sk)
                         skeletons[p] = sk;
                 }
-                catch (_h) {
+                catch (_j) {
                     // best-effort — drop the entry, keep the search result
                 }
             }
@@ -170,7 +179,7 @@ function handleDaemonSearch(deps, payload, signal) {
                 const builder = new GraphBuilder(vectorDb, root);
                 response.graph = yield builder.buildGraphMultiHop(payload.query, 1);
             }
-            catch (_j) {
+            catch (_k) {
                 // best-effort — drop graph, keep results
             }
         }

package/dist/lib/eval/relevance-baseline.js

@@ -48,6 +48,7 @@ const targetSchema = zod_1.z
     .object({
     file: zod_1.z.string().min(1),
     symbol: zod_1.z.string().min(1),
+    match: zod_1.z.enum(["symbol-or-range", "range"]).optional(),
     startLine: zod_1.z.number().int().positive(),
     endLine: zod_1.z.number().int().positive(),
     sourceSha256: digest,
@@ -117,14 +118,15 @@ function parseFrozenFixture(bytes, expectedSha256) {
     }
     return exports.relevanceFixtureSchema.parse(JSON.parse(bytes.toString("utf8")));
 }
-/** Exact file plus definition symbol OR overlap with a source-grounded line range. */
+/** Exact file plus the frozen matching rule; legacy fixtures allow symbol or range. */
 function matchesTarget(chunk, root, target) {
     var _a, _b, _c, _d;
     if (typeof ((_a = chunk.metadata) === null || _a === void 0 ? void 0 : _a.path) !== "string")
         return false;
     if (path.resolve(chunk.metadata.path) !== path.resolve(root, target.file))
         return false;
-    if ((_b = chunk.defined_symbols) === null || _b === void 0 ? void 0 : _b.includes(target.symbol))
+    if (target.match !== "range" &&
+        ((_b = chunk.defined_symbols) === null || _b === void 0 ? void 0 : _b.includes(target.symbol)))
         return true;
     const start = (_c = chunk.generated_metadata) === null || _c === void 0 ? void 0 : _c.start_line;
     const count = (_d = chunk.generated_metadata) === null || _d === void 0 ? void 0 : _d.num_lines;

package/dist/lib/search/per-file.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateMaxPerFile = validateMaxPerFile;
+exports.parseCliPerFile = parseCliPerFile;
+/** Omitted requests retain the daemon's configured default. */
+function validateMaxPerFile(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
+        throw new Error("maxPerFile must be a positive safe integer");
+    return value;
+}
+function parseCliPerFile(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value))
+        throw new Error("--per-file must be a positive safe integer");
+    try {
+        return validateMaxPerFile(Number(value));
+    }
+    catch (_a) {
+        throw new Error("--per-file must be a positive safe integer");
+    }
+}

package/dist/lib/search/searcher.js

@@ -21,6 +21,7 @@ const pool_1 = require("../workers/pool");
 const diagnostics_1 = require("./diagnostics");
 const intent_1 = require("./intent");
 const pagerank_1 = require("./pagerank");
+const per_file_1 = require("./per-file");
 const seed_weight_1 = require("./seed-weight");
 // Reads a defined_symbols / referenced_symbols column that may arrive as a plain
 // array or a LanceDB Arrow proxy (.toArray()).
@@ -397,6 +398,7 @@ class Searcher {
     search(query, top_k, _search_options, _filters, pathPrefix, intent, signal) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+            const requestedMaxPerFile = (0, per_file_1.validateMaxPerFile)(_search_options === null || _search_options === void 0 ? void 0 : _search_options.maxPerFile);
             const finalLimit = top_k !== null && top_k !== void 0 ? top_k : 10;
             // ColBERT rerank is opt-in as of v0.17.1. On the 97-case eval it
             // regresses MRR@10 by ~3% and doubles query latency; sweep across
@@ -742,7 +744,7 @@ class Searcher {
                     : {}));
             }
             const envMaxPerFile = Number.parseInt((_m = process.env.GMAX_MAX_PER_FILE) !== null && _m !== void 0 ? _m : "", 10);
-            const MAX_PER_FILE = Number.isFinite(envMaxPerFile) && envMaxPerFile > 0 ? envMaxPerFile : 3;
+            const MAX_PER_FILE = requestedMaxPerFile !== null && requestedMaxPerFile !== void 0 ? requestedMaxPerFile : (Number.isFinite(envMaxPerFile) && envMaxPerFile > 0 ? envMaxPerFile : 3);
             // Rank the entire bounded candidate pool before trimming the result count.
             // A limit-dependent cut here discarded contenders before structure boosts
             // and dedup, so requesting three results could hide the top match returned

package/dist/lib/utils/daemon-search.js

@@ -0,0 +1,34 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendSearchCommand = sendSearchCommand;
+const per_file_1 = require("../search/per-file");
+const daemon_client_1 = require("./daemon-client");
+/** An old live daemon must not silently ignore a request-scoped override. */
+function sendSearchCommand(command, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const maxPerFile = (0, per_file_1.validateMaxPerFile)(command.maxPerFile);
+        if (maxPerFile !== undefined) {
+            const ping = yield (0, daemon_client_1.sendDaemonCommand)({ cmd: "ping" }, options);
+            if (!ping.ok)
+                return ping;
+            if (((_a = ping.capabilities) === null || _a === void 0 ? void 0 : _a.perFileSearch) !== 1) {
+                return {
+                    ok: false,
+                    error: "unsupported per-file retrieval control",
+                    hint: "run gmax watch restart with the updated CLI",
+                };
+            }
+        }
+        return (0, daemon_client_1.sendDaemonCommand)(command, options);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.26.49",
+  "version": "0.26.50",
   "author": "Robert Owens <78518764+reowens@users.noreply.github.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {

package/plugins/grepmax/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.26.49",
+  "version": "0.26.50",
   "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
   "author": {
     "name": "Robert Owens",