grepmax 0.26.47 → 0.26.49

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.47",
+      "version": "0.26.49",
       "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,19 @@ 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` |
+
+## 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 +230,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 +279,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 +332,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 +356,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 +389,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 v0.26.48 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 +446,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 +474,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.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. |
 
 ## Contributing
 
@@ -484,7 +492,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 +502,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 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.
 
 `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. 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.
+
+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.
+
+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/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,

package/dist/eval-relevance.js

@@ -0,0 +1,337 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+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 });
+/** Frozen local multi-corpus baseline, using the existing daemon with no fallback. */
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_util_1 = require("node:util");
+const lmdb_1 = require("lmdb");
+const config_1 = require("./config");
+const relevance_baseline_1 = require("./lib/eval/relevance-baseline");
+const daemon_client_1 = require("./lib/utils/daemon-client");
+const project_registry_1 = require("./lib/utils/project-registry");
+function git(root) {
+    try {
+        return {
+            head: (0, node_child_process_1.execFileSync)("git", ["rev-parse", "HEAD"], {
+                cwd: root,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+            }).trim(),
+            dirty: (0, node_child_process_1.execFileSync)("git", ["status", "--porcelain"], {
+                cwd: root,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+            }).trim().length > 0,
+        };
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function run() {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        var _e, _f;
+        const { values } = (0, node_util_1.parseArgs)({
+            options: {
+                fixture: { type: "string" },
+                sha256: { type: "string" },
+                output: { type: "string" },
+                repeats: { type: "string", default: "2" },
+                help: { type: "boolean" },
+                diagnostics: { type: "boolean", default: false },
+            },
+        });
+        if (values.help) {
+            console.log("pnpm bench:relevance --fixture <json> --sha256 <frozen-sha256> --output <new-json> [--repeats 2] [--diagnostics]");
+            return;
+        }
+        if (!values.fixture || !values.sha256 || !values.output)
+            throw new Error("Required: --fixture, --sha256, --output");
+        if (fs.existsSync(values.output))
+            throw new Error("Output exists; use a new artifact path");
+        const checkpoint = `${values.output}.samples.jsonl`;
+        if (fs.existsSync(checkpoint))
+            throw new Error("Checkpoint exists; use a new artifact path");
+        const repeats = Number(values.repeats);
+        if (!Number.isInteger(repeats) || repeats < 1 || repeats > 5)
+            throw new Error("Repeats must be 1–5");
+        const fixturePath = path.resolve(values.fixture);
+        const fixture = (0, relevance_baseline_1.parseFrozenFixture)(fs.readFileSync(fixturePath), values.sha256);
+        const roots = new Map(fixture.corpora.map((r) => [
+            r.id,
+            fs.realpathSync(path.resolve(path.dirname(fixturePath), r.root)),
+        ]));
+        const startedAt = new Date().toISOString();
+        const ping = yield (0, daemon_client_1.sendDaemonCommand)({ cmd: "ping" }, { timeoutMs: 5000 });
+        if (!ping.ok || ping.ready !== true)
+            throw new Error("An already-ready daemon is required; no autostart/fallback");
+        if (values.diagnostics &&
+            ((_a = ping.capabilities) === null || _a === void 0 ? void 0 : _a.searchDiagnostics) !== 1)
+            throw new Error("Daemon lacks searchDiagnostics v1; install/restart a compatible daemon before measuring diagnostics");
+        const before = yield (0, daemon_client_1.sendDaemonCommand)({ cmd: "status" });
+        if (!before.ok)
+            throw new Error("Cannot capture daemon status");
+        const registry = (0, project_registry_1.listProjects)();
+        const cache = (0, lmdb_1.open)({
+            path: path.join(config_1.PATHS.globalRoot, "cache/meta.lmdb"),
+            compression: true,
+            readOnly: true,
+        });
+        const samples = [];
+        const preflight = [];
+        fs.writeFileSync(checkpoint, "", { flag: "wx" });
+        try {
+            for (const corpus of fixture.corpora) {
+                const root = roots.get(corpus.id);
+                const project = registry.find((p) => p.root === root);
+                if ((project === null || project === void 0 ? void 0 : project.status) !== "indexed")
+                    throw new Error(`Corpus is not indexed: ${corpus.id}`);
+                const files = [
+                    ...new Set(fixture.cases
+                        .filter((c) => c.corpus === corpus.id)
+                        .flatMap((c) => c.expected.map((t) => t.file))),
+                ];
+                const rows = yield (0, daemon_client_1.sendDaemonCommand)({
+                    cmd: "rows.locate",
+                    projectRoot: root,
+                    limit: 500,
+                    select: ["path", "defined_symbols", "start_line", "end_line"],
+                    matches: files.map((file) => ({ kind: "path", path: file })),
+                });
+                if (!rows.ok || !Array.isArray(rows.rows))
+                    throw new Error(`Target inventory failed: ${corpus.id}`);
+                preflight.push({
+                    corpus: corpus.id,
+                    root,
+                    git: git(root),
+                    project,
+                    files,
+                    targetRows: rows.rows,
+                    cache: files.map((file) => (Object.assign({ file }, cache.get(path.join(root, file))))),
+                });
+            }
+            // Sequential execution bounds load. Interleave corpora instead of running
+            // all of one corpus first; repetitions are reported separately from cases.
+            const ordered = [];
+            const groups = fixture.corpora.map((r) => fixture.cases.filter((c) => c.corpus === r.id));
+            for (let i = 0; i < Math.max(...groups.map((g) => g.length)); i++) {
+                for (const group of groups)
+                    if (group[i])
+                        ordered.push(group[i]);
+            }
+            for (let repetition = 1; repetition <= repeats; repetition++) {
+                for (const c of ordered) {
+                    const root = roots.get(c.corpus);
+                    const exclusions = new Set();
+                    const inventory = preflight.find((r) => r.corpus === c.corpus);
+                    for (const t of c.expected) {
+                        const file = path.join(root, t.file);
+                        if (fs.realpathSync(file) !== file)
+                            throw new Error(`Target aliases are not frozen: ${c.id}`);
+                        for (const reason of (0, relevance_baseline_1.sourceExclusions)(t.sourceSha256, (0, relevance_baseline_1.sha256)(fs.readFileSync(file)), (_b = cache.get(file)) === null || _b === void 0 ? void 0 : _b.hash))
+                            exclusions.add(reason);
+                        const indexed = inventory.targetRows
+                            .flat()
+                            .some((row) => (0, relevance_baseline_1.matchesTarget)({
+                            type: "text",
+                            score: 0,
+                            metadata: { path: String(row.path), hash: "" },
+                            defined_symbols: row.defined_symbols,
+                            generated_metadata: {
+                                start_line: Number(row.start_line),
+                                num_lines: Number(row.end_line) - Number(row.start_line) + 1,
+                            },
+                        }, root, t));
+                        if (!indexed)
+                            exclusions.add("target_not_in_index");
+                    }
+                    const start = performance.now();
+                    const response = exclusions.size === 0
+                        ? yield (0, daemon_client_1.sendDaemonCommand)({
+                            cmd: "search",
+                            projectRoot: root,
+                            query: c.query,
+                            limit: 20,
+                            pathPrefix: `${root}${path.sep}`,
+                            rerank: false,
+                            explain: true,
+                            diagnostics: values.diagnostics,
+                        }, { timeoutMs: 60000 })
+                        : { ok: false, error: "preflight_excluded" };
+                    const elapsedMs = performance.now() - start;
+                    if (values.diagnostics &&
+                        response.ok &&
+                        ((_c = response.diagnostics) === null || _c === void 0 ? void 0 : _c.schemaVersion) !== 1)
+                        exclusions.add("diagnostics_missing");
+                    if (!response.ok)
+                        exclusions.add(String((_e = response.error) !== null && _e !== void 0 ? _e : "search_failed"));
+                    const data = Array.isArray(response.data)
+                        ? response.data
+                        : [];
+                    const state = response.indexState;
+                    if (state &&
+                        (state.indexing ||
+                            state.verifying ||
+                            state.degraded ||
+                            Number(state.pendingFiles) > 0 ||
+                            Number(state.failedFiles) > 0))
+                        exclusions.add("index_unsettled");
+                    const warnings = Array.isArray(response.warnings)
+                        ? response.warnings
+                        : [];
+                    if (warnings.length)
+                        exclusions.add("search_warning");
+                    for (const t of c.expected) {
+                        const file = path.join(root, t.file);
+                        for (const reason of (0, relevance_baseline_1.sourceExclusions)(t.sourceSha256, (0, relevance_baseline_1.sha256)(fs.readFileSync(file)), (_d = cache.get(file)) === null || _d === void 0 ? void 0 : _d.hash))
+                            exclusions.add(reason);
+                        if (data.some((d) => { var _a; return ((_a = d.metadata) === null || _a === void 0 ? void 0 : _a.path) === file && d.metadata.hash !== t.sourceSha256; }))
+                            exclusions.add("returned_row_hash_mismatch");
+                    }
+                    const ranked = { data };
+                    samples.push(Object.assign(Object.assign({}, (0, relevance_baseline_1.scoreRelevance)(ranked, root, c)), { id: c.id, corpus: c.corpus, split: c.split, repetition,
+                        elapsedMs, exclusions: [...exclusions], query: c.query, intent: c.intent, origin: c.origin, warnings, indexState: state !== null && state !== void 0 ? state : null, error: response.ok ? null : response.error, diagnostics: (_f = response.diagnostics) !== null && _f !== void 0 ? _f : null, results: data.map((d) => { var _a, _b; var _c, _d, _e, _f, _g; return ({
+                            path: path.relative(root, String((_c = (_a = d.metadata) === null || _a === void 0 ? void 0 : _a.path) !== null && _c !== void 0 ? _c : "")),
+                            hash: (_d = (_b = d.metadata) === null || _b === void 0 ? void 0 : _b.hash) !== null && _d !== void 0 ? _d : null,
+                            symbols: (_e = d.defined_symbols) !== null && _e !== void 0 ? _e : [],
+                            range: (_f = d.generated_metadata) !== null && _f !== void 0 ? _f : null,
+                            score: d.score,
+                            scoreBreakdown: (_g = d.scoreBreakdown) !== null && _g !== void 0 ? _g : null,
+                        }); }) }));
+                    fs.appendFileSync(checkpoint, `${JSON.stringify(samples[samples.length - 1])}\n`);
+                    console.error(`${c.id} repeat=${repetition} rank=${samples[samples.length - 1].rank} excluded=${[...exclusions].join(",") || "none"}`);
+                }
+            }
+        }
+        finally {
+            cache.close();
+        }
+        const afterPing = yield (0, daemon_client_1.sendDaemonCommand)({ cmd: "ping" });
+        const after = yield (0, daemon_client_1.sendDaemonCommand)({ cmd: "status" });
+        if (!afterPing.ok ||
+            after.pid !== before.pid ||
+            afterPing.version !== ping.version) {
+            for (const sample of samples)
+                sample.exclusions.push("daemon_changed");
+        }
+        if ((0, relevance_baseline_1.sha256)(fs.readFileSync(fixturePath)) !== values.sha256)
+            throw new Error("Frozen fixture changed during execution");
+        const report = {
+            schemaVersion: 1,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            fixtureSha256: values.sha256,
+            fixture,
+            source: {
+                git: git(process.cwd()),
+                node: process.version,
+                evaluatorHash: (0, relevance_baseline_1.sha256)(fs.readFileSync(__filename)),
+                scoringHash: (0, relevance_baseline_1.sha256)(fs.readFileSync(path.join(__dirname, "lib/eval/relevance-baseline.ts"))),
+                searcherHash: (0, relevance_baseline_1.sha256)(fs.readFileSync(path.join(__dirname, "lib/search/searcher.ts"))),
+                diagnosticsHash: (0, relevance_baseline_1.sha256)(fs.readFileSync(path.join(__dirname, "lib/search/diagnostics.ts"))),
+            },
+            execution: {
+                transport: "existing-daemon-ipc",
+                requestedRerank: false,
+                explain: true,
+                requestedDiagnostics: values.diagnostics,
+                limit: 20,
+                repeats,
+                ping,
+                before,
+                afterPing,
+                after,
+                preflight,
+                diagnostics: {
+                    fusionPool: values.diagnostics
+                        ? "bounded-post-seed-head-200"
+                        : "unobserved",
+                    concentrationGate: values.diagnostics
+                        ? "per-sample-diagnostics"
+                        : "unobserved",
+                    daemonRankingEnvironment: values.diagnostics
+                        ? "allowlisted-per-sample-diagnostics"
+                        : "unobserved",
+                    ftsHealth: values.diagnostics
+                        ? "per-sample-diagnostics"
+                        : "warnings-and-score-breakdowns-only",
+                    trueRerankOff: "not-asserted",
+                },
+            },
+            summary: (0, relevance_baseline_1.summarizeRelevance)(samples),
+            byCorpus: fixture.corpora.map((r) => (Object.assign({ corpus: r.id }, (0, relevance_baseline_1.summarizeRelevance)(samples.filter((s) => s.corpus === r.id))))),
+            bySplit: ["dev", "heldout"].map((split) => (Object.assign({ split }, (0, relevance_baseline_1.summarizeRelevance)(samples.filter((s) => s.split === split))))),
+            byIntent: [...new Set(fixture.cases.map((c) => c.intent))].map((intent) => (Object.assign({ intent }, (0, relevance_baseline_1.summarizeRelevance)(samples.filter((s) => s.intent === intent))))),
+            samples,
+            researchGateReady: false,
+            limitations: [
+                "Curated source-grounded cases are not observed user-session misses",
+                values.diagnostics
+                    ? "Candidate trace is limited to the post-seed fusion head; absence from a truncated trace does not prove retrieval failure"
+                    : "Pipeline diagnostics were not requested",
+                "Client environment cannot change daemon ranking settings",
+                "Latencies mix ordinary daemon activity and first/repeated queries",
+            ],
+        };
+        fs.writeFileSync(values.output, `${JSON.stringify(report, null, 2)}\n`, {
+            flag: "wx",
+        });
+        console.log(JSON.stringify({
+            output: values.output,
+            summary: report.summary,
+            byCorpus: report.byCorpus,
+            bySplit: report.bySplit,
+        }, null, 2));
+        if (samples.some((s) => s.exclusions.length > 0))
+            process.exitCode = 2;
+    });
+}
+if (require.main === module)
+    run().catch((error) => {
+        console.error(error);
+        process.exitCode = 1;
+    });

package/dist/eval.js

@@ -527,9 +527,10 @@ function evaluateCase(response, evalCase, timeMs) {
     const avoidRank = response.data.findIndex((chunk) => { var _a, _b, _c; return (_b = (_a = chunk.metadata) === null || _a === void 0 ? void 0 : _a.path) === null || _b === void 0 ? void 0 : _b.toLowerCase().includes(((_c = evalCase.avoidPath) === null || _c === void 0 ? void 0 : _c.toLowerCase()) || "_____"); });
     const hitAvoid = evalCase.avoidPath && avoidRank >= 0 && (rank === -1 || avoidRank < rank);
     const found = rank >= 0 && !hitAvoid;
-    const rr = found ? 1 / (rank + 1) : 0;
     const recall = found && rank < 10 ? 1 : 0;
+    const rr = recall ? 1 / (rank + 1) : 0;
     return {
+        rank: rank + 1,
         rr,
         found,
         recall,
@@ -619,7 +620,7 @@ function run() {
             console.log(`Eval results for store at: ${paths.lancedbDir}`);
             console.log("=".repeat(80));
             results.forEach((r) => {
-                const status = r.found ? `rank ${(1 / r.rr).toFixed(0)}` : "❌ missed";
+                const status = r.found ? `rank ${r.rank}` : "❌ missed";
                 const emoji = r.found ? (r.rr === 1 ? "🎯" : "✓") : "❌";
                 console.log(`${emoji} ${r.query}`);
                 console.log(`   => ${status} (target: ${r.path}) [${r.timeMs.toFixed(0)}ms]`);
@@ -628,7 +629,7 @@ function run() {
                 }
             });
             console.log("=".repeat(80));
-            console.log(`MRR: ${mrr.toFixed(3)}`);
+            console.log(`MRR@10: ${mrr.toFixed(3)}`);
             console.log(`Recall@10: ${recallAt10.toFixed(3)}`);
             console.log(`Avg query time: ${avgTime.toFixed(0)}ms`);
             console.log(`Total time: ${totalTime.toFixed(0)}ms`);

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

@@ -152,6 +152,7 @@ function handleCommand(daemon, cmd, conn) {
                         capabilities: {
                             exclusiveGenerationRebuild: exports.EXCLUSIVE_GENERATION_REBUILD_PROTOCOL,
                             readVerbs: read_verbs_1.READ_VERBS_PROTOCOL,
+                            searchDiagnostics: 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.
@@ -299,6 +300,7 @@ function handleCommand(daemon, cmd, conn) {
                             pathPrefix,
                             rerank: cmd.rerank === true,
                             explain: cmd.explain === true,
+                            diagnostics: cmd.diagnostics === true,
                             seeds: cmd.seeds &&
                                 typeof cmd.seeds === "object" &&
                                 !Array.isArray(cmd.seeds)

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

@@ -103,6 +103,7 @@ function handleDaemonSearch(deps, payload, signal) {
             result = yield searcher.search(payload.query, payload.limit, {
                 rerank: payload.rerank === true,
                 explain: payload.explain === true,
+                diagnostics: payload.diagnostics === true,
                 seeds: payload.seeds,
             }, payload.filters, payload.pathPrefix, undefined, signal);
         }
@@ -116,6 +117,8 @@ function handleDaemonSearch(deps, payload, signal) {
         const response = { ok: true, data: result.data };
         if ((_c = result.warnings) === null || _c === void 0 ? void 0 : _c.length)
             response.warnings = result.warnings;
+        if (payload.diagnostics === true && result.diagnostics)
+            response.diagnostics = result.diagnostics;
         // Annotate partial results when the index is still catching up, so an
         // agent can caveat or retry. Settled failures remain visible too.
         const idx = deps.getIndexState(root);

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

@@ -0,0 +1,172 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relevanceFixtureSchema = void 0;
+exports.sha256 = sha256;
+exports.parseFrozenFixture = parseFrozenFixture;
+exports.matchesTarget = matchesTarget;
+exports.scoreRelevance = scoreRelevance;
+exports.summarizeRelevance = summarizeRelevance;
+exports.sourceExclusions = sourceExclusions;
+const node_crypto_1 = require("node:crypto");
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const digest = zod_1.z.string().regex(/^[a-f0-9]{64}$/);
+const targetSchema = zod_1.z
+    .object({
+    file: zod_1.z.string().min(1),
+    symbol: zod_1.z.string().min(1),
+    startLine: zod_1.z.number().int().positive(),
+    endLine: zod_1.z.number().int().positive(),
+    sourceSha256: digest,
+})
+    .strict()
+    .refine((t) => t.endLine >= t.startLine, "Reversed target range");
+exports.relevanceFixtureSchema = zod_1.z
+    .object({
+    schemaVersion: zod_1.z.literal(1),
+    createdAt: zod_1.z.string().min(1),
+    purpose: zod_1.z.string().min(1),
+    corpora: zod_1.z
+        .array(zod_1.z
+        .object({
+        id: zod_1.z.string().min(1),
+        root: zod_1.z.string().min(1),
+        language: zod_1.z.string().min(1),
+    })
+        .strict())
+        .min(1),
+    cases: zod_1.z
+        .array(zod_1.z
+        .object({
+        id: zod_1.z.string().min(1),
+        corpus: zod_1.z.string().min(1),
+        split: zod_1.z.enum(["dev", "heldout"]),
+        origin: zod_1.z.enum(["curated-source", "observed-session"]),
+        intent: zod_1.z.string().min(1),
+        query: zod_1.z.string().min(1),
+        expected: zod_1.z.array(targetSchema).min(1),
+    })
+        .strict())
+        .min(1),
+})
+    .strict()
+    .superRefine((fixture, ctx) => {
+    for (const values of [fixture.corpora, fixture.cases]) {
+        if (new Set(values.map((v) => v.id)).size !== values.length) {
+            ctx.addIssue({ code: "custom", message: "Duplicate fixture IDs" });
+        }
+    }
+    for (const c of fixture.cases) {
+        if (!fixture.corpora.some((r) => r.id === c.corpus)) {
+            ctx.addIssue({
+                code: "custom",
+                message: `Unknown corpus: ${c.corpus}`,
+            });
+        }
+        for (const target of c.expected) {
+            if (path.isAbsolute(target.file) ||
+                target.file.split(/[\\/]/).includes("..")) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: "Targets must be contained relative paths",
+                });
+            }
+        }
+    }
+});
+function sha256(bytes) {
+    return (0, node_crypto_1.createHash)("sha256").update(bytes).digest("hex");
+}
+function parseFrozenFixture(bytes, expectedSha256) {
+    if (!digest.safeParse(expectedSha256).success ||
+        sha256(bytes) !== expectedSha256) {
+        throw new Error("Fixture checksum mismatch; freeze the reviewed fixture before measuring");
+    }
+    return exports.relevanceFixtureSchema.parse(JSON.parse(bytes.toString("utf8")));
+}
+/** Exact file plus definition symbol OR overlap with a source-grounded line 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))
+        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;
+    if (typeof start !== "number" || typeof count !== "number" || count <= 0)
+        return false;
+    // SearchResponse ranges start at zero; source fixtures use one-based lines.
+    return start + 1 <= target.endLine && start + count >= target.startLine;
+}
+function scoreRelevance(response, root, c) {
+    const index = response.data.findIndex((chunk) => c.expected.some((t) => matchesTarget(chunk, root, t)));
+    const rank = index + 1;
+    return {
+        rank,
+        rrAt10: rank > 0 && rank <= 10 ? 1 / rank : 0,
+        recallAt10: rank > 0 && rank <= 10 ? 1 : 0,
+        hitAt1: rank === 1 ? 1 : 0,
+        found: rank > 0,
+    };
+}
+function summarizeRelevance(samples) {
+    const valid = samples.filter((s) => s.exclusions.length === 0);
+    const times = valid.map((s) => s.elapsedMs).sort((a, b) => a - b);
+    const mean = (key) => valid.length
+        ? valid.reduce((sum, s) => sum + s[key], 0) / valid.length
+        : null;
+    return {
+        cases: new Set(samples.map((s) => s.id)).size,
+        samples: samples.length,
+        validSamples: valid.length,
+        excludedSamples: samples.length - valid.length,
+        mrrAt10: mean("rrAt10"),
+        recallAt10: mean("recallAt10"),
+        hitsAt1: mean("hitAt1"),
+        medianMs: times.length ? times[Math.ceil(times.length / 2) - 1] : null,
+        p95Ms: times.length ? times[Math.ceil(times.length * 0.95) - 1] : null,
+    };
+}
+function sourceExclusions(frozenHash, sourceHash, cacheHash) {
+    const reasons = [];
+    if (sourceHash !== frozenHash)
+        reasons.push("source_changed");
+    if (cacheHash !== frozenHash)
+        reasons.push("index_cache_hash_mismatch");
+    return reasons;
+}

package/dist/lib/search/diagnostics.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchDiagnosticCollector = void 0;
+const stages = [
+    "vector",
+    "fts",
+    "rrf",
+    "fusion",
+    "stage1",
+    "pooled",
+    "rerank",
+    "scored",
+    "dedup",
+    "final",
+];
+const rankingKeys = [
+    "GMAX_PRE_K",
+    "GMAX_STAGE1_K",
+    "GMAX_STAGE2_K",
+    "GMAX_RERANK_TOP",
+    "GMAX_RERANK_BLEND",
+    "GMAX_MAX_PER_FILE",
+    "GMAX_DEF_BOOST",
+    "GMAX_CONCENTRATION_THRESHOLD",
+    "GMAX_ANCHOR_PENALTY",
+    "GMAX_TEST_PENALTY",
+    "GMAX_DOC_PENALTY",
+    "GMAX_PAGERANK",
+    "GMAX_PR_WEIGHT",
+    "GMAX_SEED_FILE_W",
+    "GMAX_SEED_SYMBOL_DEF_W",
+    "GMAX_SEED_SYMBOL_REF_W",
+    "GMAX_SEED_MAX_RANK",
+    "GMAX_ANN",
+    "GMAX_ANN_NPROBES",
+    "GMAX_ANN_MAX_NPROBES",
+];
+const key = (r) => r.id || `${r.path}:${r.chunk_index}`;
+/** Request-local pointer trace. No content, vectors or additional database reads. */
+class SearchDiagnosticCollector {
+    constructor() {
+        this.ranks = new Map();
+        this.cohort = [];
+        this.total = 0;
+        this.fileLimited = new Set();
+    }
+    noteFileLimit(record) {
+        this.fileLimited.add(key(record));
+    }
+    outcome(record) {
+        var _a, _b, _c, _d, _e, _f;
+        const id = key(record);
+        if ((_a = this.ranks.get("final")) === null || _a === void 0 ? void 0 : _a.has(id))
+            return "returned";
+        if (!((_b = this.ranks.get("stage1")) === null || _b === void 0 ? void 0 : _b.has(id)))
+            return "stage1-cut";
+        if (!((_c = this.ranks.get("pooled")) === null || _c === void 0 ? void 0 : _c.has(id)) &&
+            !((_d = this.ranks.get("scored")) === null || _d === void 0 ? void 0 : _d.has(id)))
+            return "pooled-cut";
+        if (!((_e = this.ranks.get("scored")) === null || _e === void 0 ? void 0 : _e.has(id)))
+            return "not-scored";
+        if (!((_f = this.ranks.get("dedup")) === null || _f === void 0 ? void 0 : _f.has(id)))
+            return "deduplicated";
+        if (this.fileLimited.has(id))
+            return "per-file-limit";
+        // After the display window fills, remaining candidates are unexamined.
+        return "display-limit";
+    }
+    capture(stage, records) {
+        this.ranks.set(stage, new Map(records.map((r, i) => [key(r), i + 1])));
+        if (stage === "fusion") {
+            this.total = records.length;
+            this.cohort = records.slice(0, 200);
+        }
+    }
+    finish(details) {
+        return Object.assign(Object.assign({ schemaVersion: 1 }, details), { rankingEnvironment: Object.fromEntries(rankingKeys.map((name) => { var _a; return [name, (_a = process.env[name]) !== null && _a !== void 0 ? _a : null]; })), stages: Object.fromEntries(stages.map((s) => { var _a; var _b; return [s, (_b = (_a = this.ranks.get(s)) === null || _a === void 0 ? void 0 : _a.size) !== null && _b !== void 0 ? _b : 0]; })), trace: {
+                cohort: "post-seed-fusion-head",
+                limit: 200,
+                total: this.total,
+                truncated: this.total > this.cohort.length,
+                candidates: this.cohort.map((r) => { var _a; return ({
+                    id: key(r),
+                    path: r.path,
+                    hash: r.hash,
+                    startLine: r.start_line + 1,
+                    endLine: r.end_line + 1,
+                    parentSymbol: (_a = r.parent_symbol) !== null && _a !== void 0 ? _a : "",
+                    outcome: this.outcome(r),
+                    ranks: Object.fromEntries(stages.map((s) => { var _a; var _b; return [s, (_b = (_a = this.ranks.get(s)) === null || _a === void 0 ? void 0 : _a.get(key(r))) !== null && _b !== void 0 ? _b : 0]; })),
+                }); }),
+            } });
+    }
+}
+exports.SearchDiagnosticCollector = SearchDiagnosticCollector;

package/dist/lib/search/searcher.js

@@ -18,6 +18,7 @@ const filter_builder_1 = require("../utils/filter-builder");
 const logger_1 = require("../utils/logger");
 const query_timeout_1 = require("../utils/query-timeout");
 const pool_1 = require("../workers/pool");
+const diagnostics_1 = require("./diagnostics");
 const intent_1 = require("./intent");
 const pagerank_1 = require("./pagerank");
 const seed_weight_1 = require("./seed-weight");
@@ -403,6 +404,14 @@ class Searcher {
             // fused scores ~30:1 so blend tuning can't recover the loss.
             let doRerank = (_a = _search_options === null || _search_options === void 0 ? void 0 : _search_options.rerank) !== null && _a !== void 0 ? _a : false;
             const explain = (_b = _search_options === null || _search_options === void 0 ? void 0 : _search_options.explain) !== null && _b !== void 0 ? _b : false;
+            const diagnostics = (_search_options === null || _search_options === void 0 ? void 0 : _search_options.diagnostics)
+                ? new diagnostics_1.SearchDiagnosticCollector()
+                : undefined;
+            const requestedRerank = doRerank;
+            let gateEvaluated = false;
+            let gateShare = null;
+            let gateActivated = false;
+            let rerankInvoked = false;
             // Aider-style seeding (Phase 4): bias candidate generation toward the
             // agent's working context. Inert unless the caller supplied seed files or
             // symbols, so the default search path is unchanged.
@@ -569,6 +578,9 @@ class Searcher {
                 .sort((a, b) => b[1] - a[1])
                 .map(([key]) => docMap.get(key))
                 .filter(Boolean);
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("vector", vectorResults);
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("fts", ftsResults);
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("rrf", fused);
             // Free raw search results — docMap holds the only needed references
             vectorResults.length = 0;
             ftsResults.length = 0;
@@ -618,16 +630,16 @@ class Searcher {
             // pools (express, platform) it regresses. So detect the concentrated regime
             // here and *add* rerank-on for it. This only ever flips doRerank false→true:
             // an explicit GMAX_RERANK=1 (doRerank already true) is never overridden off.
+            const envConcThreshold = Number.parseFloat((_f = process.env.GMAX_CONCENTRATION_THRESHOLD) !== null && _f !== void 0 ? _f : "");
+            // <= 0 (or NaN with the default) keeps the gate active at 0.7; a value > 1
+            // disables it (no possible share reaches it), giving a rerank-fully-off
+            // baseline for sweeps without touching the doRerank default. 0.7 is the
+            // sweep winner: highest threshold (least spurious firing) that still
+            // retains lodash's +0.15 MRR lift while leaving express/platform flat.
+            const CONCENTRATION_THRESHOLD = Number.isFinite(envConcThreshold) && envConcThreshold > 0
+                ? envConcThreshold
+                : 0.7;
             if (!doRerank) {
-                const envConcThreshold = Number.parseFloat((_f = process.env.GMAX_CONCENTRATION_THRESHOLD) !== null && _f !== void 0 ? _f : "");
-                // <= 0 (or NaN with the default) keeps the gate active at 0.7; a value > 1
-                // disables it (no possible share reaches it), giving a rerank-fully-off
-                // baseline for sweeps without touching the doRerank default. 0.7 is the
-                // sweep winner: highest threshold (least spurious firing) that still
-                // retains lodash's +0.15 MRR lift while leaving express/platform flat.
-                const CONCENTRATION_THRESHOLD = Number.isFinite(envConcThreshold) && envConcThreshold > 0
-                    ? envConcThreshold
-                    : 0.7;
                 // Histogram a fixed top-K window (not finalLimit) so the threshold stays
                 // calibrated across callers regardless of the result window they request.
                 const CONCENTRATION_K = 10;
@@ -643,16 +655,21 @@ class Searcher {
                             maxBucket = count;
                     }
                     const share = maxBucket / window.length;
+                    gateEvaluated = true;
+                    gateShare = share;
                     if (share >= CONCENTRATION_THRESHOLD) {
                         doRerank = true;
+                        gateActivated = true;
                     }
                 }
             }
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("fusion", fused);
             // Item 8: Widen PRE_RERANK_K
             // Retrieve a wide set for Stage 1 filtering
             const envStage1 = Number.parseInt((_h = process.env.GMAX_STAGE1_K) !== null && _h !== void 0 ? _h : "", 10);
             const STAGE1_K = Number.isFinite(envStage1) && envStage1 > 0 ? envStage1 : 200;
             const topCandidates = fused.slice(0, STAGE1_K);
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("stage1", topCandidates);
             // Free docMap — topCandidates already holds record references
             docMap.clear();
             // Item 9: Two-stage rerank
@@ -694,13 +711,44 @@ class Searcher {
                 withScore.sort((a, b) => b.score - a.score);
                 stage2Candidates = withScore.slice(0, STAGE2_K).map((x) => x.doc);
             }
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("pooled", stage2Candidates);
+            const diagnosticDetails = () => ({
+                settings: {
+                    finalLimit,
+                    preK: PRE_RERANK_K,
+                    rrfK: RRF_K,
+                    stage1K: STAGE1_K,
+                    stage2K: STAGE2_K,
+                    rerankTop: RERANK_TOP,
+                    fusedWeight: FUSED_WEIGHT,
+                    pagerankEnabled,
+                    seedsActive: seedCtx.active,
+                    symbolQuery,
+                    pooledFilterApplied: !!queryPooled && topCandidates.length > STAGE2_K,
+                },
+                gate: {
+                    requestedRerank,
+                    threshold: CONCENTRATION_THRESHOLD,
+                    evaluated: gateEvaluated,
+                    share: gateShare,
+                    activated: gateActivated,
+                    rerankInvoked,
+                },
+                fts: { available: this.ftsAvailable, searchFailed: ftsSearchFailed },
+            });
             if (stage2Candidates.length === 0) {
-                return { data: [] };
+                return Object.assign({ data: [] }, (diagnostics
+                    ? { diagnostics: diagnostics.finish(diagnosticDetails()) }
+                    : {}));
             }
             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 displayWindow = Math.min(stage2Candidates.length, Math.max(finalLimit * MAX_PER_FILE, finalLimit, RERANK_TOP));
-            const displayCandidates = stage2Candidates.slice(0, displayWindow);
+            // 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
+            // by a ten-result request. Expensive reranking stays independently bounded;
+            // display columns are still fetched only for the final results below.
+            const displayCandidates = [...stage2Candidates];
             const rerankCandidates = stage2Candidates.slice(0, RERANK_TOP);
             // Symbol-definition promotion (1/2): membership. For a bare-symbol query,
             // ensure the chunk(s) that actually DEFINE the symbol reach the rerank set
@@ -731,6 +779,8 @@ class Searcher {
                     }
                 }
             }
+            // Selected rerank membership is separate from actual batch execution.
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("rerank", rerankCandidates);
             // Phase B: Lazy-load colbert data only for the ~20 rerank candidates
             if (doRerank && rerankCandidates.length > 0) {
                 const rerankIds = rerankCandidates
@@ -757,6 +807,7 @@ class Searcher {
             }
             const rerankScoreByKey = new Map();
             if (doRerank && rerankCandidates.length > 0) {
+                rerankInvoked = true;
                 const scores = yield pool.rerank({
                     query: queryMatrixRaw,
                     docs: rerankCandidates.map((doc) => { var _a; return ({
@@ -843,8 +894,10 @@ class Searcher {
             }
             // Note: "boosted" was not previously declared -- fix to use "scored"
             scored.sort((a, b) => b.score - a.score);
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("scored", scored.map((item) => item.record));
             // Item 11: Intelligent Deduplication
             const uniqueScored = this.deduplicateResults(scored);
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("dedup", uniqueScored.map((item) => item.record));
             // Item 10: Per-file diversification
             const seenFiles = new Map();
             const diversified = [];
@@ -855,9 +908,13 @@ class Searcher {
                     diversified.push(item);
                     seenFiles.set(path, count + 1);
                 }
+                else {
+                    diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.noteFileLimit(item.record);
+                }
                 if (diversified.length >= finalLimit)
                     break;
             }
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("final", diversified.map((item) => item.record));
             // Phase C: Lazy-load display columns only for the final ~10 results
             const finalIds = diversified
                 .map((item) => item.record.id)
@@ -894,7 +951,7 @@ class Searcher {
             const finalResults = diversified.map((item) => (Object.assign(Object.assign({}, item.record), { _score: item.score, _breakdown: item.breakdown, vector: undefined, colbert: undefined })));
             // Item 12: Score Calibration
             const maxScore = finalResults.length > 0 ? finalResults[0]._score : 1.0;
-            return Object.assign({ data: finalResults.map((r) => {
+            return Object.assign(Object.assign({ data: finalResults.map((r) => {
                     const chunk = this.mapRecordToChunk(r, r._score || 0);
                     // Normalize score relative to top result
                     const normalized = maxScore > 0 ? r._score / maxScore : 0;
@@ -909,7 +966,11 @@ class Searcher {
                     }
                     chunk.confidence = confidence;
                     return chunk;
-                }) }, (!this.ftsAvailable || ftsSearchFailed
+                }) }, (diagnostics
+                ? {
+                    diagnostics: diagnostics.finish(Object.assign(Object.assign({}, diagnosticDetails()), { settings: Object.assign(Object.assign({}, diagnosticDetails().settings), { maxPerFile: MAX_PER_FILE, definitionBoost: DEF_MATCH_BOOST }) })),
+                }
+                : {})), (!this.ftsAvailable || ftsSearchFailed
                 ? {
                     warnings: [
                         "Full-text search unavailable — results may be less precise",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.26.47",
+  "version": "0.26.49",
   "author": "Robert Owens <78518764+reowens@users.noreply.github.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {
@@ -29,6 +29,7 @@
     "bench:recall:json": "GMAX_EVAL_JSON=1 npx tsx src/eval.ts",
     "bench:oss": "npx tsx src/eval-oss.ts all",
     "bench:oss:json": "GMAX_EVAL_JSON=1 npx tsx src/eval-oss.ts all",
+    "bench:relevance": "tsx src/eval-relevance.ts",
     "bench:tokens": "npx tsx src/eval-tokens.ts",
     "bench:tokens:json": "GMAX_EVAL_JSON=1 npx tsx src/eval-tokens.ts",
     "bench:surprises": "npx tsx src/eval-surprising-connections.ts",
@@ -76,7 +77,7 @@
     "NOTICE"
   ],
   "license": "Apache-2.0",
-  "description": "Semantic code search for coding agents. Local embeddings, LLM summaries, call graph tracing.",
+  "description": "Semantic code search for coding agents. Local embeddings, call graph tracing, compact code context.",
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "@huggingface/transformers": "^4.3.0",

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

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