grepmax 0.26.7 → 0.26.9

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

package/README.md

@@ -221,6 +221,15 @@ The daemon auto-starts when you run `gmax add`, `gmax index`, `gmax remove`, `gm
 
 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
+> 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.
+
 ```bash
 gmax llm on                   # Enable LLM features (persists to config)
 gmax llm start                # Start llama-server (auto-starts daemon too)
@@ -393,6 +402,19 @@ gmax watch stop && gmax watch --daemon -b  # Restart daemon
 
 `gmax doctor` reports ANN index state. `ANN: vector index not built` is normal with the default exact-search configuration.
 
+### Known issues
+
+Some log output looks alarming but is expected and self-healing. Before filing a bug, 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. |
+| `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. |
+| `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. |
+
 ## Contributing
 
 See [CLAUDE.md](CLAUDE.md) for development setup, commands, and architecture details.

package/dist/config.js

@@ -251,8 +251,28 @@ exports.DISK_LOW_BYTES = (() => {
     const gb = Number.parseFloat((_a = process.env.GMAX_DISK_LOW_GB) !== null && _a !== void 0 ? _a : "20");
     return (Number.isFinite(gb) && gb > 0 ? gb : 20) * 1024 * 1024 * 1024;
 })();
-// Trigger compaction when small (uncompacted) fragment count exceeds this
-exports.FRAGMENT_COMPACT_THRESHOLD = 50;
+// Trigger compaction when small (uncompacted) fragment count exceeds this.
+//
+// Deliberately high. Lance's optimize() merges the *whole* table into ~2
+// fragments regardless of how many small ones it absorbs, so a compaction costs
+// the same full-table rewrite at 51 fragments as at 400 — the threshold only
+// decides how far that fixed cost is amortized. At 50 it was amortized as little
+// as possible: on a continuously-watched project this fired every ~15-25min and
+// rewrote ~10-14GB each time, measured at 40 compactions / 586GB over 26h.
+//
+// Fragmentation also does not cost what you would expect. With ANN off (the
+// default), vector search is a brute-force scan that Lance parallelizes across
+// fragments, so compacting to 2 fragments collapses it to 2-way parallelism.
+// Interleaved benchmark, 395k rows / 384d, 96 samples per config:
+//
+//   fragments |   2   |  50  | 200  | 800
+//   vector p50| 165.6 | 73.4 | 61.6 | 66.8   (ms)
+//
+// Flat from 50-800; 2 is 2.5x slower. So raising this wins on writes *and*
+// latency. 400 sits inside the measured range with margin at both ends.
+// Caveat: measured on the no-ANN path — revisit if GMAX_ANN=1 becomes default,
+// since an ANN index partitions independently of fragments.
+exports.FRAGMENT_COMPACT_THRESHOLD = 400;
 // Extensions we consider for indexing to avoid binary noise and improve relevance.
 exports.INDEXABLE_EXTENSIONS = new Set([
     ".ts",

package/dist/lib/daemon/daemon.js

@@ -174,7 +174,11 @@ class Daemon {
         return new pool_1.WorkerPool(generation, embedMode);
     }
     createVectorDb(vectorDim, lease) {
-        return new vector_db_1.VectorDB(config_1.PATHS.lancedbDir, vectorDim, lease);
+        const db = new vector_db_1.VectorDB(config_1.PATHS.lancedbDir, vectorDim, lease);
+        // The daemon owns the store, so it is the one process allowed to create or
+        // rebuild the shared FTS index. Readers adopt it; see VectorDB.adoptFTSIndex.
+        db.markIndexOwner();
+        return db;
     }
     mlxMode(config) {
         if (config.embedMode !== "gpu")
@@ -318,6 +322,7 @@ class Daemon {
                 this.activeConfig = (0, index_config_1.readGlobalConfig)();
                 this.activeGeneration = (0, embedding_generation_1.resolveEmbeddingGeneration)(this.activeConfig);
                 this.vectorDb = new vector_db_1.VectorDB(config_1.PATHS.lancedbDir, this.activeGeneration.vectorDim);
+                this.vectorDb.markIndexOwner();
                 this.workerPool = this.createWorkerPool(this.activeGeneration, this.activeConfig.embedMode);
                 this.vectorDb.startMaintenanceLoop((fn) => this.runSharedOperation("store-maintenance", undefined, () => fn()));
                 console.log("[daemon] Opening MetaCache:", config_1.PATHS.lmdbPath);

package/dist/lib/search/searcher.js

@@ -15,6 +15,7 @@ exports.buildWhereClause = buildWhereClause;
 const config_1 = require("../../config");
 const ann_config_1 = require("../store/ann-config");
 const filter_builder_1 = require("../utils/filter-builder");
+const logger_1 = require("../utils/logger");
 const pool_1 = require("../workers/pool");
 const intent_1 = require("./intent");
 const pagerank_1 = require("./pagerank");
@@ -436,12 +437,15 @@ class Searcher {
                 this.ftsIndexChecked = true;
                 this.ftsLastCheckedAt = now;
                 try {
-                    yield this.db.createFTSIndex();
+                    // Adopt-only: search runs in every process, so building here raced
+                    // CreateIndex across processes and duplicated a full-size index per
+                    // winner. Owners build it (daemon pre-warm, `gmax index`, maintenance).
+                    yield this.db.adoptFTSIndex();
                     this.ftsAvailable = true;
                 }
                 catch (e) {
                     this.ftsAvailable = false;
-                    console.warn("[Searcher] Failed to ensure FTS index:", e);
+                    (0, logger_1.debug)("searcher", `FTS index unavailable, vector-only search: ${e}`);
                 }
             }
             // Phase A: Lightweight retrieval — only columns needed for RRF, cosine, boost, dedup
@@ -501,13 +505,23 @@ class Searcher {
                     this.ftsAvailable = false;
                     const msg = e instanceof Error ? e.message : String(e);
                     if (msg.includes("position")) {
-                        // FTS index lacks positional data — rebuild it
-                        try {
-                            yield this.db.createFTSIndex(true);
-                            this.ftsAvailable = true;
-                            console.warn("[Searcher] Rebuilt FTS index with position support — retry search");
+                        // FTS index lacks positional data — rebuild it, but only from the
+                        // index owner. This drops the index before recreating it, so a
+                        // non-owner (CLI fallback, MCP session) would yank the shared index
+                        // out from under every other process and, with several running at
+                        // once, race CreateIndex on the way back up. Non-owners degrade to
+                        // vector-only and let the daemon repair it.
+                        if (this.db.canBuildIndexes()) {
+                            try {
+                                yield this.db.createFTSIndex(true);
+                                this.ftsAvailable = true;
+                                console.warn("[Searcher] Rebuilt FTS index with position support — retry search");
+                            }
+                            catch (_r) { }
+                        }
+                        else {
+                            (0, logger_1.debug)("searcher", "FTS index lacks positions; deferring rebuild to the index owner");
                         }
-                        catch (_r) { }
                     }
                     else {
                         console.warn(`[Searcher] FTS search failed (will retry later): ${msg}`);

package/dist/lib/store/vector-db.js

@@ -102,6 +102,8 @@ class VectorDB {
         this.maintainedTableVersion = null;
         this.lastMaintenanceMs = 0;
         this.ftsIndexEnsured = false;
+        /** Only an index owner may create/rebuild shared indexes — see markIndexOwner. */
+        this.indexOwner = false;
         this.lastOptimizeDidWork = false;
         this.maintenanceRunner = (fn) => fn();
         /** Latched when a from-scratch FTS rebuild failed to stop an optimize
@@ -735,6 +737,48 @@ class VectorDB {
             return this.withWriteGate(() => this.createFTSIndexUnsafe(rebuild, retries));
         });
     }
+    /**
+     * Mark this instance as the store's index owner — the daemon, or a
+     * deliberately exclusive CLI operation. Only an owner may create or rebuild
+     * the shared FTS index; see `adoptFTSIndex`.
+     */
+    markIndexOwner() {
+        this.indexOwner = true;
+    }
+    /** Whether this instance may create or rebuild shared indexes. */
+    canBuildIndexes() {
+        return this.indexOwner;
+    }
+    /**
+     * Adopt the FTS index if one already exists, without ever building it.
+     *
+     * Search runs in *every* process — the daemon, each CLI invocation that falls
+     * back in-process, each MCP session. `createFTSIndex` on a miss meant N
+     * processes could issue `CreateIndex` against the same table version
+     * concurrently: Lance rejects the losers with a retryable commit conflict
+     * (observed 2026-08-17T00:03, all 5 retries lost) and every winner writes a
+     * full-size inverted index — ~1.4GB each on this store, which is how
+     * `_indices` reached 47GB across 35 near-identical copies.
+     *
+     * Building is therefore reserved for the explicit paths that already run
+     * under an owner: daemon pre-warm, `gmax index`, and post-optimize
+     * maintenance. Throws when no index exists so callers set `ftsAvailable =
+     * false` and degrade to vector-only search — never silently reports FTS as
+     * ready.
+     */
+    adoptFTSIndex() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.ftsIndexEnsured)
+                return;
+            const table = yield this.ensureTable();
+            const indices = yield table.listIndices();
+            const existing = indices.find((index) => index.name === "content_idx" || index.columns.includes("content"));
+            if (!existing) {
+                throw new Error("[vector-db] FTS index not built yet; this process is not the index owner");
+            }
+            this.ftsIndexEnsured = true;
+        });
+    }
     createVectorIndex() {
         return __awaiter(this, arguments, void 0, function* (rebuild = false, retries = 5, checkOnly = false) {
             if (this.checkDiskPressure() !== "ok") {

package/package.json

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

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

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

package/plugins/grepmax/agents/semantic-explore.md

@@ -49,11 +49,26 @@ gmax skeleton src/lib/auth.ts
 gmax project
 ```
 
+**Dependency shape** — god nodes, hub files, cycles, dead candidates in one pass:
+```
+gmax audit --agent --top 10
+```
+Start here for "explain this codebase" and "what's central here" questions. Rows are
+`god <symbol> <path:line> <refs> <chunks>`, `hub <file> <refs> <deps>`, `cycle <files> <n>`,
+`dead <symbol> <path:line>`. Dead candidates are hypotheses — dynamic dispatch and reflection
+are invisible to the static graph.
+
 **Related files** — dependencies and dependents:
 ```
 gmax related src/lib/auth.ts
 ```
 
+**Blast radius / test coverage** — before reporting on the risk of a change:
+```
+gmax impact handleAuth --agent          # dependents + affected tests
+gmax test handleAuth --agent            # tests exercising the symbol
+```
+
 ### Secondary: Standard tools
 
 - `Grep` — for exact string matches (identifiers, error codes, imports)
@@ -62,13 +77,18 @@ gmax related src/lib/auth.ts
 
 ## Strategy
 
+0. **Never start a local model.** `gmax investigate`, `review`, `summarize`, and `llm start` load a
+   multi-GB LLM and can stall the machine. They are not part of your toolkit — the index answers
+   these questions without them.
 1. **Start semantic** — use `gmax "query" --agent` first. Be specific (5+ words).
 2. **Peek before reading** — `gmax peek <symbol>` gives you signature + context in one call. Only `Read` the file if you need more.
 3. **Skeleton before reading** — `gmax skeleton <path>` before reading large files.
 4. **Trace for flow** — `gmax trace <symbol>` to understand call chains.
 5. **Use `--role ORCHESTRATION`** to skip type definitions and find actual logic.
 6. **Use `--agent` on everything** — compact output saves tokens.
-7. **Parallelize** — fire multiple gmax/grep/read calls in parallel when independent.
+7. **Scope big repos** — `--in <subpath>` / `--exclude <subpath>` (repeatable) on audit, dead, log,
+   surprises, and search.
+8. **Parallelize** — fire multiple gmax/grep/read calls in parallel when independent.
 
 ## If gmax search returns nothing
 

package/plugins/grepmax/skills/grepmax/SKILL.md

@@ -9,6 +9,7 @@ allowed-tools: "Bash(gmax:*), Read"
 - **Know the exact string/symbol?** → `Grep` tool (fastest, zero overhead)
 - **Know the file already?** → `Read` tool directly
 - **Searching by concept/behavior?** → `Bash(gmax "query" --agent)` (semantic search)
+- **New to the codebase?** → `Bash(gmax audit --agent)` (god nodes, hubs, cycles in one pass)
 - **Need full function body?** → `Bash(gmax extract <symbol>)` (complete source with line numbers)
 - **Quick symbol overview?** → `Bash(gmax peek <symbol>)` (signature + callers + callees)
 - **Need file structure?** → `Bash(gmax skeleton <path>)`
@@ -186,6 +187,25 @@ gmax dead handleAuth --in src/         # restrict to a sub-path
 ```
 Status is `DEAD` (no callers, not exported), `PUBLIC EXPORT` (no internal callers but the defining chunk is exported — check external usage), or `LIVE` (with caller count + top-3 file:line). The call graph reflects what tree-sitter chunked: dynamic dispatch, reflection, eval, and string-built call sites won't show up — `DEAD` is a hypothesis, not a proof.
 
+### Audit — `gmax audit`
+```
+gmax audit                             # god nodes, hub files, cycles, dead candidates
+gmax audit --agent --top 5             # compact TSV, 5 per category
+gmax audit --in src/ --exclude tests/  # scope to a sub-path
+```
+One pass over the static reference graph — the fastest way to get the shape of an unfamiliar
+codebase. Agent rows are `god <symbol> <path:line> <refs> <chunks>`, `hub <file> <refs> <deps>`,
+`cycle <comma-separated files> <n>`, `dead <symbol> <path:line>`, plus `scanned`/`dead_total`.
+Dynamic dispatch, reflection, and eval are invisible to it, so dead candidates are hypotheses.
+
+### Surprises — `gmax surprises` (experimental)
+```
+gmax surprises --agent                 # embedding-similar file pairs the static graph misses
+gmax surprises --top 10 --min-sim 0.7  # tighten the similarity floor
+```
+Orientation only — surfaces cross-directory pairs that look related by embedding but share no
+static edge. Useful for spotting duplication or missing abstractions, not for proving anything.
+
 ### Context — `gmax context <topic-or-path> --budget <tokens>`
 ```
 gmax context "authentication system" --budget 4000
@@ -195,7 +215,16 @@ gmax context src/lib/auth/ --budget 3000
 ```
 Use the path form when you already know the file or directory; it skips semantic search and gives deterministic structure/excerpt context.
 
-### Investigate — `gmax investigate "question"` (requires LLM)
+### Investigate — `gmax investigate "question"` (loads a multi-GB local LLM)
+
+> **Ask the user first.** `investigate`, `review`, and `summarize` start `llama-server` with a
+> multi-GB local model. On memory-constrained machines that can stall or hang the host. Never run
+> them — or `gmax llm start` — on your own initiative, including "just to check" or as a fallback
+> when search seems insufficient. Run them only when the user asks for that command in the moment.
+>
+> You almost never need them: `gmax context`, `--context-for-llm`, and `trace`/`impact` answer the
+> same questions using the index you already have, with no model load.
+
 ```
 gmax investigate "how does authentication work?"
 gmax investigate "what would break if I changed VectorDB?" -v
@@ -210,16 +239,19 @@ gmax status --agent                        # compact: name\tchunks\tage\tstatus
 gmax related src/file.ts --agent           # compact: dep:/rev: path\tcount
 gmax project --agent                       # compact: key\tvalue pairs
 gmax index                                 # reindex current directory
+gmax help-agent                            # reprint this cheatsheet in the terminal
 gmax config                                # view/change settings
 gmax doctor                                # health check
 gmax doctor --fix                          # auto-repair (compact, prune, clear stale locks)
-gmax llm on/off/start/stop/status          # manage local LLM server
+gmax repair --rebuild                      # last resort: destructive whole-store rebuild
+gmax llm on/off/start/stop/status          # local LLM server — see the warning above; ask first
 ```
 
 ## Workflow
 
 1. **Add** — `Bash(gmax add)` to register and index a new project
-2. **Explore** — `Bash(gmax project)` for overview of a new codebase
+2. **Explore** — `Bash(gmax project)` for overview of a new codebase, then
+   `Bash(gmax audit --agent)` for the dependency shape (god nodes, hubs, cycles)
 3. **Search** — `Bash(gmax "query" --agent)` to find code. Add `--symbol` for function/class names.
 4. **Peek** — `Bash(gmax peek <symbol>)` for a quick overview (signature + callers + callees)
 5. **Extract** — `Bash(gmax extract <symbol>)` for the full function body with line numbers
@@ -244,6 +276,8 @@ gmax llm on/off/start/stop/status          # manage local LLM server
 - **Use `--skeleton`** when `--agent` results aren't enough — shows file structure for top matches.
 - **Use `--imports`** when you need to understand a file's dependencies.
 - **Use `--root <dir>`** to search/trace/query a different project from your current directory.
+- **Scope with `--in <subpath>` / `--exclude <subpath>`** (both repeatable) on `audit`, `surprises`,
+  `dead`, `log`, and search — narrows a big repo to the area you care about.
 - **Don't search for exact strings** — use grep/Grep for that. gmax finds concepts.
 
 ## If search fails or returns nothing