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

package/README.md

@@ -36,6 +36,8 @@ Natural-language search that works like `grep`. Fast, local, and built for codin
 
 ## Quick Start
 
+Requires **Node.js 22.12.0 or newer**.
+
 ```bash
 npm install -g grepmax        # 1. Install
 cd my-repo && gmax add        # 2. Add + index
@@ -89,7 +91,7 @@ gmax status                   # All indexed projects + chunk counts
 gmax status --json            # The same plus daemon, settings and workers, as JSON
 ```
 
-In our public benchmarks, `grepmax` can save about 20% of your LLM tokens and deliver a 30% speedup.
+The recorded benchmark below showed about 20% fewer LLM tokens and a 30% speedup on its workload. Results depend on the repository, query and agent workflow.
 
 <div align="center">
   <img src="public/bench.png" alt="gmax benchmark" width="100%" style="border-radius: 8px; margin: 20px 0;" />
@@ -115,11 +117,11 @@ gmax plugin add droid          # Factory Droid only
 gmax plugin remove claude      # Remove specific plugin
 ```
 
-Plugins auto-update when you run `npm install -g grepmax@latest` — no need to re-run `gmax plugin add`.
+After upgrading with `npm install -g grepmax@latest`, run `gmax plugin update` (or `gmax plugin update <client>`) to refresh integrations. Package installation does not modify your agent configuration; its postinstall script only prints this reminder.
 
 ### How it works per client
 
-- **Claude Code:** Plugin with hooks (SessionStart, CwdChanged, SubagentStart, PreToolUse). Model uses CLI via `Bash(gmax ... --agent)`.
+- **Claude Code:** Plugin with hooks (SessionStart, SessionEnd, CwdChanged, SubagentStart, PreToolUse). Model uses CLI via `Bash(gmax ... --agent)`.
 - **OpenCode:** Tool shim with dynamic SKILL + session plugin for daemon startup. Model calls gmax tool directly.
 - **Codex:** MCP server registration + AGENTS.md skill instructions.
 - **Factory Droid:** Skills + SessionStart/SessionEnd hooks for daemon lifecycle.
@@ -153,7 +155,7 @@ Clients requesting progress receive operation-stage messages with increasing sta
 | `list_projects` | List every indexed project (name, root, status, chunks) to pick a search scope. |
 | `index_status` | Index health: chunks, files, projects, watcher status. |
 | `summarize_project` | Project overview: languages, structure, key symbols, entry points. |
-| `summarize_directory` | Generate LLM summaries for indexed chunks. |
+| `summarize_directory` | Compatibility entry; summarization is disabled and generates no summaries. |
 | `related_files` | Dependencies and dependents by shared symbols. |
 | `recent_changes` | Recently modified indexed files. |
 | `diff_changes` | Search scoped to git changes. |
@@ -189,18 +191,6 @@ 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` |
@@ -213,7 +203,21 @@ The CLI and MCP output include score, max similarity, pair count, representative
 | `--all-projects` | Search every indexed project; results grouped by project. | `false` |
 | `--projects <list>` | Search only these projects (comma-separated names). | — |
 | `--exclude-projects <list>` | With `--all-projects`, skip these projects. | — |
-| `--min-score <n>` | Minimum relevance score. | `0` |
+| `--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.
+
+```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.
 
 ## Background Daemon
 
@@ -228,7 +232,7 @@ gmax watch restart            # Stop it, wait for it to exit, start a fresh one
 gmax status                   # See all projects + watcher status
 ```
 
-The daemon auto-starts when you run `gmax add`, `gmax index`, `gmax remove`, `gmax summarize`, or `gmax mcp`. It shuts down after 4 hours of inactivity, and hands off to a fresh daemon after 24 hours or once its memory footprint passes 2.5 GB. File-change batches are processed on at most four worker processes, added only when work backs up, with one kept free for searches; LanceDB compaction runs after writes rather than on every maintenance tick.
+Adding or indexing a project can start the daemon automatically. MCP acquires primary-project watch leases lazily when an index-reading tool is used; discovery and catalog listing start no background work. It shuts down after 4 hours of inactivity, and hands off to a fresh daemon after 24 hours or once its memory footprint passes 2.5 GB. File-change batches are processed on up to four worker processes by default, added only when work backs up, with one kept free for searches; LanceDB compaction runs after writes rather than on every maintenance tick.
 
 `gmax watch status` reports failed files, native watcher recovery or polling, dropped-event counts, and the last complete filesystem reconciliation. Polling scans run every five minutes, so recent edits can lag. Search and MCP responses retain health warnings even after the file queue drains. A complete reconciliation means the filesystem scan completed; queued embedding work can still be pending.
 
@@ -277,14 +281,14 @@ On Linux the per-socket list does not exist; the only option is
 
 gmax can use a local LLM (via llama-server) for agentic codebase investigation. This is entirely opt-in and disabled by default — gmax works fine without it.
 
-> **Memory footprint.** `gmax llm start`, `investigate`, `review`, and `summarize` load a multi-GB
+> **Memory footprint.** `gmax llm start`, `investigate`, and `review` can load a multi-GB
 > GGUF model (typical coding models run 16–21 GB). On a memory-constrained machine that can stall
 > or hang the host. Start it deliberately, not as a reflex — and if you run coding agents against
 > this repo, they should be told not to invoke these on their own initiative. The bundled skill
 > already carries that instruction.
 >
-> Everything else in gmax — search, `trace`, `impact`, `context`, `--context-for-llm` — runs off
-> the local index with no model load.
+> Everything else in gmax — search, `trace`, `impact`, `context`, `--context-for-llm` — uses
+> local embeddings and the index without a generative LLM.
 
 ```bash
 gmax llm on                   # Enable LLM features (persists to config)
@@ -330,16 +334,23 @@ The hook sends an IPC message to the daemon and returns instantly — it never b
 
 ### LLM Configuration
 
+Set `GMAX_LLM_MODEL` to a GGUF file on your machine before starting; the built-in fallback path is machine-specific and may not exist. The server accepts loopback addresses only.
+
 | Variable | Description | Default |
 | --- | --- | --- |
-| `GMAX_LLM_MODEL` | Path to GGUF model file | (none) |
+| `GMAX_LLM_MODEL` | Path to GGUF model file | Machine-specific fallback |
+| `GMAX_LLM_HOST` | Loopback address (`localhost` maps to IPv4 loopback) | `127.0.0.1` |
 | `GMAX_LLM_BINARY` | llama-server binary | `llama-server` |
 | `GMAX_LLM_PORT` | Server port | `8079` |
 | `GMAX_LLM_IDLE_TIMEOUT` | Minutes before auto-stop | `30` |
 
+### Summary compatibility commands
+
+The summarizer is decommissioned. `gmax summarize` and MCP `summarize_directory` remain compatibility entries backed by a no-op; they do not generate summaries. `GMAX_SUMMARIZER` does not enable them. Investigation and review use the separate optional LLM described above.
+
 ## Architecture
 
-All data lives in `~/.gmax/`:
+Default shared data lives in `~/.gmax/`; configured secondary stores retain their own project indexes:
 - `lancedb/` — LanceDB vector store (centralized, all projects)
 - `cache/meta.lmdb` — file metadata cache (hashes, mtimes)
 - `cache/watchers.lmdb` — watcher/daemon registry (LMDB, crash-safe)
@@ -347,7 +358,9 @@ All data lives in `~/.gmax/`:
 - `daemon.pid` — PID file for daemon dedup
 - `logs/` — daemon and server logs (5MB rotation)
 - `config.json` — global config (model tier, embed mode)
-- `models/` — embedding models
+- `models/` — ONNX embedding models
+- `hf/` — pinned Hugging Face cache for MLX embedding models
+- `watch-leases.json` — active session/CLI watch leases
 - `grammars/` — Tree-sitter grammars
 - `projects.json` — registry of indexed directories
 
@@ -378,22 +391,19 @@ gmax embeds with IBM's Granite r2 code-embedding models. Two tiers are available
 | `small` (default) | `granite-embedding-small-english-r2` | 384 | 47M |
 | `standard` | `granite-embedding-english-r2` | 768 | 149M |
 
-**384d is the default — and benchmarking says keep it.** On gmax's own 97-case
-retrieval eval (`pnpm bench:recall`), the larger 768d model scored **~10 points
+**384d remains the default.** In the recorded 97-case model-tier comparison
+on gmax's own repo, the larger 768d model scored **~10 points
 *worse* on Recall@10** than 384d, consistently on both the MLX GPU and ONNX CPU
 embedding paths, with and without ColBERT rerank:
 
-| Model | Recall@10 | MRR@10 |
+| Model | Recall@10 | Reported MRR |
 | --- | --- | --- |
 | `small` / 384d | **0.72** | **0.51** |
 | `standard` / 768d | 0.62 | 0.44 |
 
-<sub>gmax repo, 97 cases, MLX GPU, rerank off (the shipped default). The CPU/q4
-path and the rerank-on path show the same ~0.10 Recall@10 gap, so it isn't a
-quantization artifact — the bigger model just retrieves worse on code here.</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>
 
-Bigger isn't better for this workload: 768d roughly doubles embedding compute,
-worker RAM, and dense-vector storage while *lowering* recall on code search.
+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
 large repo — benchmark it first), stay on 384d.
 
@@ -438,11 +448,11 @@ fixtures/
 | Variable | Description | Default |
 | --- | --- | --- |
 | `GMAX_EMBED_MODE` | Force `cpu` or `gpu` | Auto-detect |
-| `GMAX_WORKER_THREADS` | Worker processes for embedding; overrides `gmax config --worker-threads` | `min(4, max(2, cores/2))` |
+| `GMAX_WORKER_THREADS` | Worker processes for embedding; overrides `gmax config --worker-threads` | `min(cores, 4, max(2, floor(cores/2)))` |
 | `GMAX_WORKER_RSS_RECYCLE_MB` | Recycle workers that remain above this RSS; `0` disables the check | `1536` |
 | `GMAX_DEBUG` | Debug logging | Off |
-| `GMAX_SUMMARIZER` | Enable summarizer auto-start (`1`) | Off |
-| `GMAX_RERANK` | Enable ColBERT rerank (`1`) — off by default since v0.17.1 ([why](docs/known-limitations.md)) | Off |
+| `GMAX_RERANK` | Force ColBERT rerank (`1`); concentrated candidates can also enable it automatically ([why](docs/known-limitations.md)) | Off |
+| `GMAX_CONCENTRATION_THRESHOLD` | Top-ten candidate share in one file that enables ColBERT; set above `1` for a true rerank-off baseline | `0.7` |
 | `GMAX_ANN` | Experimental IVF_FLAT vector index (`1`); leave off unless validating recall on your corpus | Off |
 
 ## Troubleshooting
@@ -466,17 +476,17 @@ Compaction pauses index writes, waits for pending writes to commit, and opens a
 
 ### Known issues
 
-Some log output looks alarming but is expected and self-healing. Before filing a bug, check
+For detection and recovery guidance, check
 [`docs/known-limitations.md`](docs/known-limitations.md) — it covers what each case means and
 whether you need to act.
 
 | You see | What it means |
 |---|---|
-| `Optimize panicked ... inverted/builder.rs` | Upstream Lance bug in incremental FTS merge ([lance#8310](https://github.com/lance-format/lance/issues/8310)). gmax rebuilds the index and retries automatically; no data loss, no action needed. |
+| `Optimize panicked ... inverted/builder.rs` | The historical FTS merge defect is fixed in the shipped LanceDB 0.38.0 runtime. If it recurs on a current release, preserve the version and logs and report a regression; the rebuild guard remains a recovery tripwire. |
 | `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 | Two transitive advisories (`sharp`, `adm-zip`) have no upstream fix yet; neither is on a code path gmax executes. |
+| `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
 
@@ -484,7 +494,7 @@ See [CLAUDE.md](CLAUDE.md) for development setup, commands, and architecture det
 
 ### Benchmarks
 
-Two evaluation harnesses live in the repo. Both emit stable JSON via `:json` variants.
+Two retrieval evaluation harnesses emit JSON via `:json` variants. Additional token and experimental-orientation harnesses are available as `bench:tokens` and `bench:surprises`.
 
 ```bash
 pnpm bench:recall          # 97-case internal eval against gmax's own repo
@@ -494,10 +504,37 @@ pnpm bench:oss:json
 GMAX_EVAL_RERANK=1 pnpm bench:oss   # toggle ColBERT rerank
 ```
 
-The OSS bench requires the fixture repos to be indexed first — see [`docs/known-limitations.md`](docs/known-limitations.md) for the most recent rerank-on-vs-off comparison across 4 datasets / 131 cases.
+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 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.
 
+#### Frozen multi-repository baseline
+
+`bench:relevance` measures reviewed local fixtures through an already-ready daemon. It does not autostart a daemon or open a fallback search store. Keep private queries, source evidence and results under the ignored `docs/measurements/` directory. Review and freeze the fixture before seeing rankings; use a new fixture version when changing ground truth.
+
+```bash
+shasum -a 256 docs/measurements/relevance/fixture-v1.json
+pnpm bench:relevance --fixture docs/measurements/relevance/fixture-v1.json \
+  --sha256 <reviewed-fixture-digest> \
+  --output docs/measurements/relevance/baseline-v1.json --repeats 2
+```
+
+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. 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.
+
+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.
+
+Each traced candidate also has an `outcome`: returned, stage-one/pooled cut, deduplicated, per-file limit or display limit. Display limit means the production loop filled its result window before examining that candidate; it does not assert that the candidate would pass the per-file cap.
+
 ## Attribution
 
 grepmax is built upon the foundation of [mgrep](https://github.com/mixedbread-ai/mgrep) by MixedBread. See the [NOTICE](NOTICE) file for details.

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/eval-oss.js

@@ -57,6 +57,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 var _a, _b, _c, _d;
 var _e;
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateOss = evaluateOss;
 // Same precaution as src/eval.ts — pin worker pool to 1 to avoid ONNX
 // concurrency issues during the back-to-back search runs.
 (_a = (_e = process.env).GMAX_WORKER_COUNT) !== null && _a !== void 0 ? _a : (_e.GMAX_WORKER_COUNT = "1");
@@ -346,8 +347,8 @@ function evaluateOss(response, c, timeMs) {
     // expected defined-symbol for the drift-robust match branch.
     chunkMatches(chunk, c.expectedFile, c.expectedLine, c.query));
     const rank = idx + 1; // 0 = miss
-    const rr = rank > 0 ? 1 / rank : 0;
     const recall10 = rank > 0 && rank <= 10 ? 1 : 0;
+    const rr = recall10 ? 1 / rank : 0;
     return {
         id: c.id,
         query: c.query,