grepmax 0.17.16 → 0.17.17

package/dist/commands/mcp.js

@@ -158,6 +158,14 @@ const TOOLS = [
                     type: "string",
                     description: "Project names to exclude (comma-separated)",
                 },
+                seed_files: {
+                    type: "string",
+                    description: "Bias results toward your working context: comma-separated paths you have open (e.g. 'src/lib/llm/server.ts'). On-topic chunks in these files get lifted; off-topic ones are not.",
+                },
+                seed_symbols: {
+                    type: "string",
+                    description: "Bias results toward identifiers you're working with: comma-separated symbol names. Chunks defining a seeded symbol are preferred over mere callers.",
+                },
             },
             required: ["query"],
         },
@@ -784,7 +792,22 @@ exports.mcp = new commander_1.Command("mcp")
                         }
                     }
                 }
-                const result = yield searcher.search(query, limit, { rerank: process.env.GMAX_RERANK === "1" }, Object.keys(filters).length > 0 ? filters : undefined, pathPrefix);
+                // Aider-style seeding: the agent passes its open files / discussed
+                // symbols; the searcher biases candidate generation toward them.
+                const parseSeedList = (v) => {
+                    const items = (Array.isArray(v)
+                        ? v.map((x) => String(x))
+                        : typeof v === "string"
+                            ? v.split(",")
+                            : [])
+                        .map((s) => s.trim())
+                        .filter((s) => s.length > 0);
+                    return items.length > 0 ? items : undefined;
+                };
+                const seedFiles = parseSeedList(args.seed_files);
+                const seedSymbols = parseSeedList(args.seed_symbols);
+                const seeds = seedFiles || seedSymbols ? { files: seedFiles, symbols: seedSymbols } : undefined;
+                const result = yield searcher.search(query, limit, { rerank: process.env.GMAX_RERANK === "1", seeds }, Object.keys(filters).length > 0 ? filters : undefined, pathPrefix);
                 if (!result.data || result.data.length === 0) {
                     return ok("No matches found. Try broadening your query, using fewer keywords, or check `gmax status` to verify the project is indexed.");
                 }

package/dist/commands/search.js

@@ -377,6 +377,8 @@ exports.search = new commander_1.Command("search")
     .option("--name <regex>", "Filter results by symbol name regex")
     .option("-C, --context <n>", "Include N lines before/after each result")
     .option("--agent", "Ultra-compact output for AI agents (one line per result)", false)
+    .option("--seed-file <path>", "Bias results toward your working context (repeatable; comma-separated also accepted)", (value, prev) => (prev ? [...prev, value] : [value]))
+    .option("--seed-symbol <name>", "Bias results toward an identifier you're working with (repeatable; comma-separated also accepted)", (value, prev) => (prev ? [...prev, value] : [value]))
     .argument("<pattern>", 'Natural language query (e.g. "where do we handle auth?")')
     .argument("[path]", "Restrict search to this path prefix")
     .addHelpText("after", `
@@ -569,6 +571,19 @@ Examples:
             searchFilters.inPrefixes = scope.inPrefixes;
         if (scope.excludePrefixes.length > 0)
             searchFilters.excludePrefixes = scope.excludePrefixes;
+        // Aider-style seeding: --seed-file / --seed-symbol (repeatable, also
+        // comma-separated) bias candidate generation toward the caller's working
+        // context. Absent → undefined → inert.
+        const splitSeeds = (vals) => {
+            const items = (vals !== null && vals !== void 0 ? vals : [])
+                .flatMap((v) => v.split(","))
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            return items.length > 0 ? items : undefined;
+        };
+        const seedFiles = splitSeeds(options.seedFile);
+        const seedSymbols = splitSeeds(options.seedSymbol);
+        const seeds = seedFiles || seedSymbols ? { files: seedFiles, symbols: seedSymbols } : undefined;
         // Daemon-mediated search: ships query+args over IPC, daemon runs the
         // hybrid+rerank against its already-warm VectorDB and worker pool.
         // Drops cold-start cost (~17s wall, 6GB RAM in the CLI) to <1s. Falls
@@ -592,6 +607,7 @@ Examples:
                         pathPrefix: pathFilter,
                         rerank: process.env.GMAX_RERANK === "1",
                         explain: options.explain,
+                        seeds,
                         includeSkeletons: options.skeleton,
                         includeGraph: options.symbol,
                     }, { timeoutMs: 60000 });
@@ -695,7 +711,7 @@ Examples:
                 }
             }
             const searcher = new searcher_1.Searcher(vectorDb);
-            searchResult = yield searcher.search(pattern, parseInt(options.m, 10), { rerank: process.env.GMAX_RERANK === "1", explain: options.explain }, Object.keys(searchFilters).length > 0
+            searchResult = yield searcher.search(pattern, parseInt(options.m, 10), { rerank: process.env.GMAX_RERANK === "1", explain: options.explain, seeds }, Object.keys(searchFilters).length > 0
                 ? searchFilters
                 : undefined, pathFilter);
         } // end if (!searchResult) — in-process fallback

package/dist/eval-seed.js

@@ -0,0 +1,284 @@
+"use strict";
+/**
+ * Seed-eval harness — measures Aider-style chat/file seeding (Phase 4).
+ *
+ * WHY A SEPARATE HARNESS. `bench:oss` (src/eval-oss.ts) uses bare-symbol P1
+ * lookups with NO seed context, so it can only serve as a *no-seed regression
+ * guard* for seeding (seeded path absent → results must be unchanged). It
+ * cannot demonstrate that seeding *helps*: attaching a seed equal to the answer
+ * file would be circular, and the fixtures carry no realistic "open files"
+ * annotation.
+ *
+ * THE HONEST DESIGN. Every case here uses an *ambiguous* natural-language query
+ * that legitimately matches several subsystems, plus a realistic seed (a file
+ * an agent would have open, or a symbol they're discussing). The metric is the
+ * rank of the *contextually-correct* answer file, measured twice: baseline (no
+ * seed) vs seeded. Three case kinds:
+ *
+ *   - route:   same query, seed points at subsystem A → answer should be A's
+ *              file (which a no-seed search ranks below a different subsystem).
+ *              Non-circular because the SAME query under a DIFFERENT seed must
+ *              route to a DIFFERENT, independently-valid answer — something no
+ *              static ranking can do.
+ *   - recover: the contextually-correct file is OUT of the no-seed top-K
+ *              entirely; seeding must pull it back via candidate-generation
+ *              weight (a rerank-only seed could never recover an out-of-pool
+ *              item — this case is the load-bearing proof of "weight in
+ *              candidate generation, not rerank").
+ *   - guard:   the seed is IRRELEVANT to the query; the no-seed rank-1 file must
+ *              stay rank 1. Catches seeding doing harm.
+ *
+ * Baselines below were measured live against the gmax index on 2026-06-02
+ * (granite-small, gpu) and are quoted per case. They are documentation, not
+ * assertions — the harness recomputes them every run.
+ *
+ * Usage:
+ *   npx tsx src/eval-seed.ts            # table output
+ *   npx tsx src/eval-seed.ts --json     # machine-readable
+ */
+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());
+    });
+};
+var _a, _b, _c;
+var _d;
+Object.defineProperty(exports, "__esModule", { value: true });
+(_a = (_d = process.env).GMAX_WORKER_COUNT) !== null && _a !== void 0 ? _a : (_d.GMAX_WORKER_COUNT = "1");
+const path = __importStar(require("node:path"));
+const searcher_1 = require("./lib/search/searcher");
+const vector_db_1 = require("./lib/store/vector-db");
+const exit_1 = require("./lib/utils/exit");
+const config_1 = require("./config");
+// Route/recover cases target the gmax repo itself — the corpus whose graph the
+// author can verify by hand. The "idle timeout" concept lives in three
+// subsystems (worker reap / LLM server / daemon); "health check" in three more.
+// That natural polysemy is what makes the routing test honest.
+//
+// The no-harm guards instead target the immutable express fixture: querying
+// gmax for "rank fusion" is contaminated by this harness's own source (which is
+// full of "fusion" prose and gets live-indexed), so a stable external corpus is
+// the honest place to assert "an irrelevant seed must not displace the winner".
+const REPO_ROOTS = {
+    gmax: path.join((_b = process.env.HOME) !== null && _b !== void 0 ? _b : "", "Development/beyond/tools/gmax"),
+    express: path.join((_c = process.env.HOME) !== null && _c !== void 0 ? _c : "", "Development/sandbox/bench-fixtures/express"),
+};
+const GMAX_CASES = [
+    // ── Triple A: "idle timeout shutdown" routes to worker / LLM / daemon ──────
+    {
+        id: "idle-pool",
+        query: "idle timeout shutdown",
+        seedFiles: ["src/lib/workers/pool.ts"],
+        expectedFile: "src/lib/workers/pool.ts",
+        kind: "guard", // already rank 1 without seeds — seeding must not demote it
+        baselineRankNote: 1,
+        note: "worker-reap is the no-seed winner; seeding its own file keeps it #1",
+    },
+    {
+        id: "idle-llm",
+        query: "idle timeout shutdown",
+        seedFiles: ["src/lib/llm/server.ts"],
+        expectedFile: "src/lib/llm/server.ts",
+        kind: "route",
+        baselineRankNote: 5,
+        note: "LLM idle watchdog at #5 behind worker-reap chunks; seed should lift it to #1",
+    },
+    {
+        id: "idle-daemon",
+        query: "idle timeout shutdown",
+        seedFiles: ["src/lib/daemon/daemon.ts"],
+        expectedFile: "src/lib/daemon/daemon.ts",
+        kind: "recover",
+        baselineRankNote: 0,
+        note: "daemon idle checker is OUT of the no-seed top-25; candidate-gen weight must recover it",
+    },
+    // ── Triple B: "health check probe" routes to doctor / mlx / llm ────────────
+    {
+        id: "health-doctor",
+        query: "health check probe",
+        seedFiles: ["src/commands/doctor.ts"],
+        expectedFile: "src/commands/doctor.ts",
+        kind: "guard",
+        baselineRankNote: 1,
+        note: "doctor is the no-seed winner; seeding its own file keeps it #1",
+    },
+    {
+        id: "health-mlx",
+        query: "health check probe",
+        seedFiles: ["src/lib/workers/embeddings/mlx-client.ts"],
+        expectedFile: "src/lib/workers/embeddings/mlx-client.ts",
+        kind: "route",
+        baselineRankNote: 3,
+        note: "mlx checkHealth at #3; seed should lift the embed-server probe to #1",
+    },
+    {
+        id: "health-llm",
+        query: "health check probe",
+        seedFiles: ["src/lib/llm/server.ts"],
+        expectedFile: "src/lib/llm/server.ts",
+        kind: "route",
+        baselineRankNote: 5,
+        note: "llm-server healthy() at #5; seed should lift it to #1",
+    },
+    // ── Symbol seeding: discussed identifier instead of open file ──────────────
+    {
+        id: "idle-llm-sym",
+        query: "idle timeout shutdown",
+        seedSymbols: ["LlmServer"],
+        expectedFile: "src/lib/llm/server.ts",
+        kind: "route",
+        baselineRankNote: 5,
+        note: "symbol-seed analog of idle-llm: discussing LlmServer biases toward its file",
+    },
+    // ── Guards: irrelevant seed must not perturb a strong no-seed winner.
+    //    On the immutable express fixture so the assertion can't be polluted by
+    //    live-indexing this harness's own source. ────────────────────────────────
+    {
+        id: "guard-express-file",
+        repo: "express",
+        query: "create the application factory",
+        seedFiles: ["lib/view.js"],
+        expectedFile: "lib/express.js",
+        kind: "guard",
+        baselineRankNote: 1,
+        note: "view.js (rank ~150 for this query) is off-topic; express.js must stay #1",
+    },
+    {
+        id: "guard-express-sym",
+        repo: "express",
+        query: "create the application factory",
+        seedSymbols: ["View"],
+        expectedFile: "lib/express.js",
+        kind: "guard",
+        baselineRankNote: 1,
+        note: "View is defined in the off-topic view.js; express.js must stay #1",
+    },
+];
+/** Rank (1-indexed) of the first result whose path matches expectedFile; 0 = miss. */
+function rankOf(response, expectedFile) {
+    const want = expectedFile.toLowerCase();
+    const idx = response.data.findIndex((chunk) => {
+        var _a;
+        const p = String(((_a = chunk.metadata) === null || _a === void 0 ? void 0 : _a.path) || "").toLowerCase();
+        return p.endsWith(`/${want}`) || p.endsWith(want);
+    });
+    return idx + 1;
+}
+function judge(kind, baseline, seeded) {
+    // 0 means "not found in top-K"; treat as worse than any found rank.
+    const b = baseline === 0 ? Infinity : baseline;
+    const s = seeded === 0 ? Infinity : seeded;
+    switch (kind) {
+        case "route":
+            // Seeding must improve (or already hold) the contextually-correct file's
+            // rank — and land it at the top.
+            return s <= b && s === 1;
+        case "recover":
+            // Out-of-pool baseline must be pulled into the results and to the top.
+            return baseline === 0 && s === 1;
+        case "guard":
+            // No harm: the file must not lose rank (and a rank-1 stays rank-1).
+            return s <= b;
+    }
+}
+function run() {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const jsonMode = process.argv.includes("--json") || process.env.GMAX_EVAL_JSON === "1";
+        const topK = 25;
+        const rerank = process.env.GMAX_EVAL_RERANK === "1";
+        const vectorDb = new vector_db_1.VectorDB(config_1.PATHS.lancedbDir);
+        const searcher = new searcher_1.Searcher(vectorDb);
+        const results = [];
+        for (const c of GMAX_CASES) {
+            const pathPrefix = `${REPO_ROOTS[(_a = c.repo) !== null && _a !== void 0 ? _a : "gmax"]}/`;
+            const baseRes = yield searcher.search(c.query, topK, { rerank }, undefined, pathPrefix);
+            const seededRes = yield searcher.search(c.query, topK, { rerank, seeds: { files: c.seedFiles, symbols: c.seedSymbols } }, undefined, pathPrefix);
+            const baselineRank = rankOf(baseRes, c.expectedFile);
+            const seededRank = rankOf(seededRes, c.expectedFile);
+            results.push({
+                id: c.id,
+                kind: c.kind,
+                query: c.query,
+                expectedFile: c.expectedFile,
+                baselineRank,
+                seededRank,
+                pass: judge(c.kind, baselineRank, seededRank),
+                note: c.note,
+            });
+        }
+        yield vectorDb.close();
+        const passes = results.filter((r) => r.pass).length;
+        const byKind = (k) => results.filter((r) => r.kind === k);
+        const summary = {
+            cases: results.length,
+            passes,
+            route: { total: byKind("route").length, pass: byKind("route").filter((r) => r.pass).length },
+            recover: { total: byKind("recover").length, pass: byKind("recover").filter((r) => r.pass).length },
+            guard: { total: byKind("guard").length, pass: byKind("guard").filter((r) => r.pass).length },
+        };
+        if (jsonMode) {
+            process.stdout.write(`${JSON.stringify({ rerank, summary, results }, null, 2)}\n`);
+        }
+        else {
+            console.log(`Seed eval (rerank=${rerank ? "on" : "off"})\n`);
+            const fmtRank = (r) => (r === 0 ? "—" : `#${r}`);
+            for (const r of results) {
+                const arrow = `${fmtRank(r.baselineRank)} → ${fmtRank(r.seededRank)}`;
+                const mark = r.pass ? "✓" : "✗";
+                const seed = `[${r.kind}]`;
+                console.log(`  ${mark} ${r.id.padEnd(18)} ${seed.padEnd(10)} ${arrow.padEnd(12)} ${r.expectedFile}`);
+                if (r.note)
+                    console.log(`      ${r.note}`);
+            }
+            console.log(`\n  → ${passes}/${results.length} pass  ` +
+                `(route ${summary.route.pass}/${summary.route.total}, ` +
+                `recover ${summary.recover.pass}/${summary.recover.total}, ` +
+                `guard ${summary.guard.pass}/${summary.guard.total})`);
+        }
+        yield (0, exit_1.gracefulExit)(0);
+    });
+}
+if (require.main === module && process.env.GMAX_EVAL_AUTORUN !== "0") {
+    run().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/dist/lib/daemon/daemon.js

@@ -867,7 +867,11 @@ class Daemon {
             this.lastActivity = Date.now();
             let result;
             try {
-                result = yield searcher.search(payload.query, payload.limit, { rerank: payload.rerank === true, explain: payload.explain === true }, payload.filters, payload.pathPrefix, undefined, signal);
+                result = yield searcher.search(payload.query, payload.limit, {
+                    rerank: payload.rerank === true,
+                    explain: payload.explain === true,
+                    seeds: payload.seeds,
+                }, payload.filters, payload.pathPrefix, undefined, signal);
             }
             catch (err) {
                 if ((err === null || err === void 0 ? void 0 : err.name) === "AbortError") {

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

@@ -171,6 +171,9 @@ function handleCommand(daemon, cmd, conn) {
                             pathPrefix: typeof cmd.pathPrefix === "string" ? cmd.pathPrefix : undefined,
                             rerank: cmd.rerank === true,
                             explain: cmd.explain === true,
+                            seeds: cmd.seeds && typeof cmd.seeds === "object" && !Array.isArray(cmd.seeds)
+                                ? cmd.seeds
+                                : undefined,
                             includeSkeletons: cmd.includeSkeletons === true,
                             skeletonLimit: skeletonLimitRaw,
                             includeGraph: cmd.includeGraph === true,

package/dist/lib/search/searcher.js

@@ -17,6 +17,7 @@ const filter_builder_1 = require("../utils/filter-builder");
 const pool_1 = require("../workers/pool");
 const intent_1 = require("./intent");
 const pagerank_1 = require("./pagerank");
+const seed_weight_1 = require("./seed-weight");
 // Reads a defined_symbols / referenced_symbols column that may arrive as a plain
 // array or a LanceDB Arrow proxy (.toArray()).
 function readSymbolArray(val) {
@@ -367,7 +368,7 @@ class Searcher {
     }
     search(query, top_k, _search_options, _filters, pathPrefix, intent, signal) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
             const finalLimit = top_k !== null && top_k !== void 0 ? top_k : 10;
             // ColBERT rerank is opt-in as of v0.17.1. On the 97-case eval it
             // regresses MRR@10 by ~3% and doubles query latency; sweep across
@@ -375,6 +376,10 @@ 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;
+            // 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.
+            const seedCtx = (0, seed_weight_1.buildSeedContext)(_search_options === null || _search_options === void 0 ? void 0 : _search_options.seeds);
             const searchIntent = intent || (0, intent_1.detectIntent)(query);
             // Bare-identifier queries get symbol-definition promotion (see below).
             const symbolQuery = asSymbolQuery(query);
@@ -402,7 +407,7 @@ class Searcher {
             try {
                 table = yield this.db.ensureTable();
             }
-            catch (_o) {
+            catch (_q) {
                 return { data: [] };
             }
             // Ensure FTS index exists (lazy init, retry periodically on failure)
@@ -428,7 +433,9 @@ class Searcher {
             const pagerankEnabled = process.env.GMAX_PAGERANK === "1" && !!pathPrefix;
             // Symbol-definition promotion needs defined_symbols on every candidate, not
             // just the final display set — load it for bare-symbol queries too.
-            const needDefinedSymbols = pagerankEnabled || symbolQuery !== null;
+            // Seed-symbol matching reads defined_symbols (referenced_symbols is always
+            // loaded), so pull it into the lightweight path when symbols were seeded.
+            const needDefinedSymbols = pagerankEnabled || symbolQuery !== null || seedCtx.symbols.size > 0;
             const LIGHTWEIGHT_COLUMNS = [
                 "id", "path", "hash", "chunk_index", "start_line", "end_line",
                 "is_anchor", "chunk_type", "role", "complexity", "is_exported",
@@ -471,7 +478,7 @@ class Searcher {
                             this.ftsAvailable = true;
                             console.warn("[Searcher] Rebuilt FTS index with position support — retry search");
                         }
-                        catch (_p) { }
+                        catch (_r) { }
                     }
                     else {
                         console.warn(`[Searcher] FTS search failed (will retry later): ${msg}`);
@@ -487,11 +494,23 @@ class Searcher {
             const RRF_K = 60;
             const candidateScores = new Map();
             const docMap = new Map();
+            // Best (lowest) 1-indexed rank each candidate reached in any retriever —
+            // the relevance gate for seeding (see the seed block below). Only tracked
+            // when seeding is active; otherwise it stays empty and costs nothing.
+            const bestRank = new Map();
+            const noteRank = seedCtx.active
+                ? (key, rank) => {
+                    const prev = bestRank.get(key);
+                    if (prev === undefined || rank + 1 < prev)
+                        bestRank.set(key, rank + 1);
+                }
+                : () => { };
             vectorResults.forEach((doc, rank) => {
                 const key = doc.id || `${doc.path}:${doc.chunk_index}`;
                 docMap.set(key, doc);
                 const score = 1.0 / (RRF_K + rank + 1);
                 candidateScores.set(key, (candidateScores.get(key) || 0) + score);
+                noteRank(key, rank);
             });
             ftsResults.forEach((doc, rank) => {
                 const key = doc.id || `${doc.path}:${doc.chunk_index}`;
@@ -499,6 +518,7 @@ class Searcher {
                     docMap.set(key, doc);
                 const score = 1.0 / (RRF_K + rank + 1);
                 candidateScores.set(key, (candidateScores.get(key) || 0) + score);
+                noteRank(key, rank);
             });
             const fused = Array.from(candidateScores.entries())
                 .sort((a, b) => b[1] - a[1])
@@ -507,6 +527,45 @@ class Searcher {
             // Free raw search results — docMap holds the only needed references
             vectorResults.length = 0;
             ftsResults.length = 0;
+            // Aider-style seeding (Phase 4): bump the RRF score of candidates matching
+            // the agent's working context, gated by each candidate's own relevance so
+            // off-topic seed files are never injected (the safety invariant). Because
+            // the final ordering also reads candidateScores, this one bump propagates
+            // through the stage-1 cosine cut, the stage-2 window, the rerank set, AND
+            // the final score — and can recover a candidate fusion buried below the
+            // display cut, which a rerank-only seed could not. See ./seed-weight.ts.
+            if (seedCtx.active) {
+                // Bound the scan to the relevant head of the pool. The gate is each
+                // candidate's best retriever rank (bestRank), so off-topic seed chunks
+                // that only appear deep in the pool are never lifted.
+                const SEED_WINDOW = 200;
+                const seedParams = (0, seed_weight_1.seedParamsFromEnv)();
+                let boosted = false;
+                for (const doc of fused.slice(0, SEED_WINDOW)) {
+                    const sym = seedCtx.symbols.size > 0
+                        ? (0, seed_weight_1.matchesSeedSymbol)(seedCtx, readSymbolArray(doc.defined_symbols), readSymbolArray(doc.referenced_symbols))
+                        : { def: false, ref: false };
+                    const match = {
+                        file: (0, seed_weight_1.matchesSeedFile)(seedCtx, doc.path),
+                        symbolDef: sym.def,
+                        symbolRef: sym.ref && !sym.def,
+                    };
+                    const key = doc.id || `${doc.path}:${doc.chunk_index}`;
+                    const bonus = (0, seed_weight_1.seedBoost)(match, (_d = bestRank.get(key)) !== null && _d !== void 0 ? _d : Infinity, seedParams);
+                    if (bonus > 0) {
+                        candidateScores.set(key, ((_e = candidateScores.get(key)) !== null && _e !== void 0 ? _e : 0) + bonus);
+                        boosted = true;
+                    }
+                }
+                if (boosted) {
+                    fused.sort((a, b) => {
+                        var _a, _b;
+                        const ka = a.id || `${a.path}:${a.chunk_index}`;
+                        const kb = b.id || `${b.path}:${b.chunk_index}`;
+                        return ((_a = candidateScores.get(kb)) !== null && _a !== void 0 ? _a : 0) - ((_b = candidateScores.get(ka)) !== null && _b !== void 0 ? _b : 0);
+                    });
+                }
+            }
             // Candidate-concentration gate (Bundle B, v0.17.2 OSS-fixture finding):
             // ColBERT rerank is shape-sensitive. When the post-fusion pool clusters
             // into one file (single-file-repo / concentrated shape, e.g. lodash) rerank
@@ -515,7 +574,7 @@ class Searcher {
             // 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.
             if (!doRerank) {
-                const envConcThreshold = Number.parseFloat((_d = process.env.GMAX_CONCENTRATION_THRESHOLD) !== null && _d !== void 0 ? _d : "");
+                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
@@ -531,7 +590,7 @@ class Searcher {
                 if (window.length > 0 && CONCENTRATION_THRESHOLD <= 1) {
                     const buckets = new Map();
                     for (const doc of window) {
-                        buckets.set(doc.path, ((_e = buckets.get(doc.path)) !== null && _e !== void 0 ? _e : 0) + 1);
+                        buckets.set(doc.path, ((_g = buckets.get(doc.path)) !== null && _g !== void 0 ? _g : 0) + 1);
                     }
                     let maxBucket = 0;
                     for (const count of buckets.values()) {
@@ -546,7 +605,7 @@ class Searcher {
             }
             // Item 8: Widen PRE_RERANK_K
             // Retrieve a wide set for Stage 1 filtering
-            const envStage1 = Number.parseInt((_f = process.env.GMAX_STAGE1_K) !== null && _f !== void 0 ? _f : "", 10);
+            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);
             // Free docMap — topCandidates already holds record references
@@ -554,11 +613,11 @@ class Searcher {
             // Item 9: Two-stage rerank
             // Stage 1: Cheap pooled cosine filter
             let stage2Candidates = topCandidates;
-            const envStage2K = Number.parseInt((_g = process.env.GMAX_STAGE2_K) !== null && _g !== void 0 ? _g : "", 10);
+            const envStage2K = Number.parseInt((_j = process.env.GMAX_STAGE2_K) !== null && _j !== void 0 ? _j : "", 10);
             const STAGE2_K = Number.isFinite(envStage2K) && envStage2K > 0 ? envStage2K : 40;
-            const envRerankTop = Number.parseInt((_h = process.env.GMAX_RERANK_TOP) !== null && _h !== void 0 ? _h : "", 10);
+            const envRerankTop = Number.parseInt((_k = process.env.GMAX_RERANK_TOP) !== null && _k !== void 0 ? _k : "", 10);
             const RERANK_TOP = Number.isFinite(envRerankTop) && envRerankTop > 0 ? envRerankTop : 20;
-            const envBlend = Number.parseFloat((_j = process.env.GMAX_RERANK_BLEND) !== null && _j !== void 0 ? _j : "");
+            const envBlend = Number.parseFloat((_l = process.env.GMAX_RERANK_BLEND) !== null && _l !== void 0 ? _l : "");
             const FUSED_WEIGHT = Number.isFinite(envBlend) && envBlend >= 0 ? envBlend : 0.5;
             if (queryPooled && topCandidates.length > STAGE2_K) {
                 const cosineScores = topCandidates.map((doc) => {
@@ -662,7 +721,7 @@ class Searcher {
             // constructor/toJSON, which otherwise score higher on the literal and evict
             // the parent in overlap dedup). Multiplicative keeps it scale-invariant
             // across the rerank-on (ColBERT maxsim) and rerank-off (fusion) score ranges.
-            const envDefBoost = Number.parseFloat((_k = process.env.GMAX_DEF_BOOST) !== null && _k !== void 0 ? _k : "");
+            const envDefBoost = Number.parseFloat((_m = process.env.GMAX_DEF_BOOST) !== null && _m !== void 0 ? _m : "");
             const DEF_MATCH_BOOST = Number.isFinite(envDefBoost) && envDefBoost >= 1 ? envDefBoost : 5;
             const scored = rerankCandidates.map((doc, idx) => {
                 var _a, _b;
@@ -691,7 +750,7 @@ class Searcher {
                 try {
                     const { scores: prScores, max: prMax } = yield (0, pagerank_1.loadOrComputePageRank)(this.db, pathPrefix);
                     if (prMax > 0) {
-                        const envWeight = Number.parseFloat((_l = process.env.GMAX_PR_WEIGHT) !== null && _l !== void 0 ? _l : "");
+                        const envWeight = Number.parseFloat((_o = process.env.GMAX_PR_WEIGHT) !== null && _o !== void 0 ? _o : "");
                         const PR_WEIGHT = Number.isFinite(envWeight) && envWeight >= 0 ? envWeight : 0.05;
                         for (const item of scored) {
                             const raw = item.record.defined_symbols;
@@ -706,7 +765,7 @@ class Searcher {
                                         defs = arr.filter((v) => typeof v === "string");
                                     }
                                 }
-                                catch (_q) { }
+                                catch (_s) { }
                             }
                             const norm = (0, pagerank_1.pageRankBoostForSymbols)(defs, prScores, prMax);
                             item.score += PR_WEIGHT * norm;
@@ -724,7 +783,7 @@ class Searcher {
             // Item 10: Per-file diversification
             const seenFiles = new Map();
             const diversified = [];
-            const envMaxPerFile = Number.parseInt((_m = process.env.GMAX_MAX_PER_FILE) !== null && _m !== void 0 ? _m : "", 10);
+            const envMaxPerFile = Number.parseInt((_p = process.env.GMAX_MAX_PER_FILE) !== null && _p !== void 0 ? _p : "", 10);
             const MAX_PER_FILE = Number.isFinite(envMaxPerFile) && envMaxPerFile > 0 ? envMaxPerFile : 3;
             for (const item of uniqueScored) {
                 const path = item.record.path || "";

package/dist/lib/search/seed-weight.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Aider-style chat/file seeding (Phase 4) — pure scoring helpers.
+ *
+ * Seeding biases search toward the agent's *working context*: files it has open
+ * ("chat files", weighted heavily in Aider's repo-map) and identifiers it is
+ * discussing. gmax applies the bias in **candidate generation** — it bumps the
+ * Reciprocal Rank Fusion score of seed-matching candidates — NOT as a post-hoc
+ * rerank tiebreaker. Bundle B (see docs/plans/2026-05-25-semantic-search-
+ * landscape.md) showed a tiebreaker over a saturated rerank pool is a no-op;
+ * lifting the fusion score instead lets a seeded candidate climb through the
+ * stage-1 cosine cut, the stage-2 window, and the final ordering in one move,
+ * and can even *recover* a candidate that fusion alone buried below the display
+ * cut (something a rerank-only seed could never do).
+ *
+ * THE SAFETY INVARIANT. Seeding must never inject *off-topic* context: an agent
+ * working in `pool.ts` who searches for "rank fusion scoring" should still get
+ * `searcher.ts`, because `pool.ts` has nothing relevant to say. So the bonus is
+ * **relevance-gated** — a seed match is only boosted when the candidate already
+ * ranked highly in at least one retriever (vector OR full-text). A genuinely
+ * on-topic seed chunk surfaces near the top of some retriever; an off-topic one
+ * sits deep in every retriever and is left exactly where the query put it. We
+ * gate on retriever rank (always available, even for an FTS-only hit) rather
+ * than pooled-ColBERT cosine, which is not reliably populated on every index.
+ *
+ * All functions here are pure so the gating/weighting math can be unit-tested
+ * (tests/seed-weight.test.ts) independently of the LanceDB-backed searcher.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SEED_PARAMS = void 0;
+exports.seedParamsFromEnv = seedParamsFromEnv;
+exports.buildSeedContext = buildSeedContext;
+exports.matchesSeedFile = matchesSeedFile;
+exports.matchesSeedSymbol = matchesSeedSymbol;
+exports.seedBoost = seedBoost;
+exports.DEFAULT_SEED_PARAMS = {
+    // RRF scores live around 1/(60+rank) ≈ 0.008–0.016, so a ~0.02 bonus is
+    // strong enough to lift a genuinely-relevant seed match several ranks while
+    // staying in the same order of magnitude as the fusion signal it augments.
+    fileWeight: 0.02,
+    symbolDefWeight: 0.02,
+    symbolRefWeight: 0.006,
+    // A genuinely on-topic seed chunk reaches the top handful of some retriever
+    // (the route/recover fixtures land at ranks 1–7); an off-topic one sits mid-
+    // pool or deeper (an irrelevant express seed file is rank ~150 for an
+    // unrelated query). 8 is the eligibility ceiling separating the two without
+    // boosting mid-pool noise (see tests/seed-weight.test.ts and eval-seed.ts).
+    maxRank: 8,
+};
+/** Resolve params from env, falling back to DEFAULT_SEED_PARAMS per field. */
+function seedParamsFromEnv(env = process.env) {
+    const num = (raw, fallback, min) => {
+        const v = Number.parseFloat(raw !== null && raw !== void 0 ? raw : "");
+        return Number.isFinite(v) && v >= min ? v : fallback;
+    };
+    return {
+        fileWeight: num(env.GMAX_SEED_FILE_W, exports.DEFAULT_SEED_PARAMS.fileWeight, 0),
+        symbolDefWeight: num(env.GMAX_SEED_SYMBOL_DEF_W, exports.DEFAULT_SEED_PARAMS.symbolDefWeight, 0),
+        symbolRefWeight: num(env.GMAX_SEED_SYMBOL_REF_W, exports.DEFAULT_SEED_PARAMS.symbolRefWeight, 0),
+        maxRank: num(env.GMAX_SEED_MAX_RANK, exports.DEFAULT_SEED_PARAMS.maxRank, 1),
+    };
+}
+/** Normalize a seed spec into a matchable context. */
+function buildSeedContext(spec) {
+    var _a, _b;
+    const fileSuffixes = ((_a = spec === null || spec === void 0 ? void 0 : spec.files) !== null && _a !== void 0 ? _a : [])
+        .map((f) => f.trim().toLowerCase().replace(/^\.?\//, ""))
+        .filter((f) => f.length > 0);
+    const symbols = new Set(((_b = spec === null || spec === void 0 ? void 0 : spec.symbols) !== null && _b !== void 0 ? _b : []).map((s) => s.trim()).filter((s) => s.length > 0));
+    return {
+        fileSuffixes,
+        symbols,
+        active: fileSuffixes.length > 0 || symbols.size > 0,
+    };
+}
+/** Does a candidate match any seed file (by path suffix)? */
+function matchesSeedFile(ctx, candidatePath) {
+    if (ctx.fileSuffixes.length === 0)
+        return false;
+    const p = candidatePath.toLowerCase();
+    return ctx.fileSuffixes.some((suffix) => p.endsWith(`/${suffix}`) || p === suffix || p.endsWith(suffix));
+}
+/**
+ * Classify a candidate's relationship to the seed symbols: does it define one,
+ * or merely reference one? Definition wins when both are true.
+ */
+function matchesSeedSymbol(ctx, definedSymbols, referencedSymbols) {
+    if (ctx.symbols.size === 0)
+        return { def: false, ref: false };
+    let def = false;
+    for (const s of definedSymbols) {
+        if (ctx.symbols.has(s)) {
+            def = true;
+            break;
+        }
+    }
+    let ref = false;
+    for (const s of referencedSymbols) {
+        if (ctx.symbols.has(s)) {
+            ref = true;
+            break;
+        }
+    }
+    return { def, ref };
+}
+/**
+ * The additive RRF-score bonus for a candidate. Returns 0 when the candidate
+ * matches no seed, or when it matches but its best retriever rank is deeper
+ * than the ceiling (the safety invariant). `bestRank` is the 1-indexed best
+ * position the candidate reached across retrievers; 0/Infinity means it was
+ * never retrieved near the top and is therefore ineligible. File and symbol
+ * bonuses are additive; a definition match supersedes a reference match.
+ */
+function seedBoost(match, bestRank, params) {
+    if (!match.file && !match.symbolDef && !match.symbolRef)
+        return 0;
+    if (!(bestRank >= 1) || bestRank > params.maxRank)
+        return 0;
+    let bonus = match.file ? params.fileWeight : 0;
+    if (match.symbolDef)
+        bonus += params.symbolDefWeight;
+    else if (match.symbolRef)
+        bonus += params.symbolRefWeight;
+    return bonus;
+}

package/package.json

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

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

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