grepmax 0.20.0 → 0.21.1

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

package/README.md

@@ -289,6 +289,45 @@ All data lives in `~/.gmax/`:
 }
 ```
 
+### Model Tier
+
+gmax embeds with IBM's Granite r2 code-embedding models. Two tiers are available:
+
+| Tier | Model | Dim | Params |
+| --- | --- | --- | --- |
+| `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
+*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 |
+| --- | --- | --- |
+| `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>
+
+Bigger isn't better for this workload: 768d roughly doubles embedding compute,
+worker RAM, and dense-vector storage while *lowering* recall on code search.
+Unless you have a measured reason to switch (e.g. a recall complaint on a very
+large repo — benchmark it first), stay on 384d.
+
+To change tiers:
+
+```bash
+gmax config --model-tier standard   # a dim change needs a full re-embed
+gmax repair --rebuild               # drops the shared table, re-embeds every project at the new dim
+```
+
+A vector-dimension change can't be applied by a per-project `gmax index --reset`
+— the shared `chunks` table is fixed-width, so `gmax repair --rebuild` is the
+sanctioned path.
+
 ### Ignoring Files
 
 gmax respects `.gitignore` and `.gmaxignore`:
@@ -339,6 +378,8 @@ 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.
 
+`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.
+
 ## Attribution
 
 grepmax is built upon the foundation of [mgrep](https://github.com/mixedbread-ai/mgrep) by MixedBread. See the [NOTICE](NOTICE) file for details.

package/dist/commands/codex.js

@@ -69,8 +69,11 @@ function writeSkillToAgents(skill) {
 function installPlugin() {
     return __awaiter(this, void 0, void 0, function* () {
         try {
-            // 1. Register MCP tool
-            yield execAsync("codex mcp add gmax gmax mcp", {
+            // 1. Register MCP tool. Codex requires the stdio command after `--`:
+            //   codex mcp add [OPTIONS] <NAME> -- <COMMAND>...
+            // Without the separator the launch command is misparsed. AGENTS.md is only
+            // written after this resolves, so a failed registration leaves it untouched.
+            yield execAsync("codex mcp add gmax -- gmax mcp", {
                 shell,
                 env: process.env,
             });

package/dist/commands/config.js

@@ -84,6 +84,7 @@ Examples:
     const newMode = (_c = options.embedMode) !== null && _c !== void 0 ? _c : globalConfig.embedMode;
     const tier = (_d = config_1.MODEL_TIERS[newTier]) !== null && _d !== void 0 ? _d : config_1.MODEL_TIERS.small;
     const tierChanged = newTier !== globalConfig.modelTier;
+    const dimChanged = tier.vectorDim !== globalConfig.vectorDim;
     (0, index_config_1.writeGlobalConfig)({
         modelTier: newTier,
         vectorDim: tier.vectorDim,
@@ -98,7 +99,12 @@ Examples:
     });
     console.log(`Updated: embed-mode=${newMode}, model-tier=${newTier} (${tier.vectorDim}d)`);
     if (tierChanged) {
-        console.log("⚠️  Model tier changed — run `gmax index --reset` to rebuild with new dimensions.");
+        // A dimension change can't be fixed by a per-project `gmax index --reset`:
+        // the shared `chunks` table is fixed-width, so it must be dropped and
+        // rebuilt. A same-dim model swap (future tiers) can use a per-project reset.
+        console.log(dimChanged
+            ? `⚠️  Model tier changed (${globalConfig.vectorDim}d → ${tier.vectorDim}d). The shared vector table is fixed-width — run \`${config_1.REBUILD_COMMAND}\` to drop it and re-embed every project at the new dim.`
+            : "⚠️  Model tier changed — run `gmax index --reset` per project to re-embed with the new model.");
     }
     yield (0, exit_1.gracefulExit)();
 }));

package/dist/commands/doctor.js

@@ -179,6 +179,13 @@ exports.doctor = new commander_1.Command("doctor")
         const db = new VectorDB(config_1.PATHS.lancedbDir);
         const table = yield db.ensureTable();
         const totalChunks = yield table.countRows();
+        // Physical schema-width check: the shared `chunks` table is fixed-width at
+        // creation, so a tier/dim change strands it at the old width and every
+        // write throws. This is independent of the per-project registry drift
+        // checked below — the table can match the registry yet still be physically
+        // stranded — so we surface it as its own line.
+        const physicalDim = yield db.getSchemaVectorDim();
+        const schemaGap = (0, config_1.describeSchemaDimGap)(physicalDim, globalConfig.vectorDim);
         // Summary coverage (existing check)
         if (!opts.agent && totalChunks > 0) {
             const withSummary = (yield table
@@ -275,8 +282,13 @@ exports.doctor = new commander_1.Command("doctor")
                 `orphaned=${orphanedProjects.length}`,
                 `stale_chunker=${staleChunkerProjects.length}`,
                 `stale_embedding=${staleEmbeddingProjects.length}`,
+                `schema_dim=${physicalDim !== null && physicalDim !== void 0 ? physicalDim : "none"}`,
+                `schema_dim_ok=${schemaGap ? "false" : "true"}`,
             ];
             console.log(fields.join("\t"));
+            if (schemaGap) {
+                console.log((0, config_1.schemaDimAgentRow)(schemaGap));
+            }
             for (const p of staleChunkerProjects) {
                 const gap = (0, config_1.describeChunkerGap)(p.chunkerVersion);
                 if (!gap)
@@ -307,12 +319,24 @@ exports.doctor = new commander_1.Command("doctor")
                     `current_dim=${gap.toDim}`,
                     `dim_changed=${gap.dimChanged}`,
                     `severity=${gap.severity}`,
-                    `fix=gmax index --reset (in ${p.root})`,
+                    // A dim change can't be fixed by a per-project reset (the shared
+                    // table is fixed-width) — point at the global rebuild instead.
+                    `fix=${gap.dimChanged ? config_1.REBUILD_COMMAND : `gmax index --reset (in ${p.root})`}`,
                 ].join("\t"));
             }
         }
         else {
             console.log("\nIndex Health\n");
+            // Physical schema width — a mismatch means every write throws until a
+            // global rebuild (the shared fixed-width table can't be reshaped by a
+            // per-project reset). Surfaced first because it's the most severe.
+            if (schemaGap) {
+                console.log(`FAIL  Schema: vector table is ${schemaGap.tableDim}d, config expects ${schemaGap.configDim}d`);
+                console.log(`       run '${config_1.REBUILD_COMMAND}' (drops + reindexes all projects at the new width)`);
+            }
+            else if (physicalDim) {
+                console.log(`ok  Schema: vector table is ${physicalDim}d`);
+            }
             // Disk space
             if (diskLevel !== "ok") {
                 console.log(`WARN  Disk: ${formatSize(availBytes)} available (${diskLevel})`);
@@ -370,17 +394,21 @@ exports.doctor = new commander_1.Command("doctor")
             }
             // Index built with a different embedding model/dim than the current
             // config. A dim change is breaking (search scores are invalid until a
-            // re-embed); a same-dim model swap is additive. Unlike the stale-chunker
-            // case this is NOT auto-fixed by `--fix`: a dim change can't coexist in
-            // the shared fixed-dim table (deferred Phase 1B), so we point at the
-            // manual reset instead.
+            // re-embed); a same-dim model swap is additive. Recovery differs by kind:
+            // a same-dim model swap is fixed by a per-project `gmax index --reset`,
+            // but a dim change can't be — the shared table is fixed-width, so it
+            // needs the global rebuild (see the Schema check above).
             if (staleEmbeddingProjects.length > 0) {
                 const gaps = staleEmbeddingProjects.map((p) => (0, config_1.describeEmbeddingGap)({ modelTier: p.modelTier, vectorDim: p.vectorDim }, {
                     modelTier: globalConfig.modelTier,
                     vectorDim: globalConfig.vectorDim,
                 }));
                 const anyBreaking = gaps.some((g) => (g === null || g === void 0 ? void 0 : g.severity) === "breaking");
-                console.log(`${anyBreaking ? "WARN" : "INFO"}  Stale embedding: ${staleEmbeddingProjects.length} project(s) indexed with a different embedding model/dim — run 'gmax index --reset' per project`);
+                const anyDimChange = gaps.some((g) => g === null || g === void 0 ? void 0 : g.dimChanged);
+                const headerFix = anyDimChange
+                    ? `run '${config_1.REBUILD_COMMAND}' (dim change needs a full rebuild)`
+                    : "run 'gmax index --reset' per project";
+                console.log(`${anyBreaking ? "WARN" : "INFO"}  Stale embedding: ${staleEmbeddingProjects.length} project(s) indexed with a different embedding model/dim — ${headerFix}`);
                 staleEmbeddingProjects.forEach((p, i) => {
                     const gap = gaps[i];
                     if (!gap)
@@ -389,7 +417,9 @@ exports.doctor = new commander_1.Command("doctor")
                         ? `${gap.fromDim}d→${gap.toDim}d`
                         : `model ${gap.fromModel}→${gap.toModel}`;
                     console.log(`       - ${p.name || path.basename(p.root)} (${change}, ${gap.severity})`);
-                    console.log(`         run 'gmax index --reset' in ${p.root}`);
+                    console.log(gap.dimChanged
+                        ? `         run '${config_1.REBUILD_COMMAND}'`
+                        : `         run 'gmax index --reset' in ${p.root}`);
                 });
             }
             // Projects

package/dist/commands/droid.js

@@ -69,17 +69,50 @@ function parseJsonWithComments(content) {
         .split("\n")
         .map((line) => line.replace(/^\s*\/\/.*$/, ""))
         .join("\n");
-    try {
-        return JSON.parse(stripped);
-    }
-    catch (_a) {
+    // An empty / whitespace-only file is a legitimate "no settings yet" -> {}.
+    // Anything else that fails to parse is a real, user-owned file we must NOT
+    // silently coerce to {} (that would clobber it on the next save) — let the
+    // caller decide.
+    if (stripped.trim() === "")
         return {};
-    }
+    return JSON.parse(stripped);
 }
 function loadSettings(settingsPath) {
     if (!node_fs_1.default.existsSync(settingsPath))
         return {};
-    return parseJsonWithComments(node_fs_1.default.readFileSync(settingsPath, "utf-8"));
+    const raw = node_fs_1.default.readFileSync(settingsPath, "utf-8");
+    try {
+        return parseJsonWithComments(raw);
+    }
+    catch (err) {
+        throw new Error(`Refusing to touch ${settingsPath}: it contains invalid JSON ` +
+            `(${err.message}). Fix or remove the file, then re-run.`);
+    }
+}
+/** True when a hook entry was installed by gmax — its command points at our
+ *  hooks dir. Used to remove only gmax entries on uninstall. */
+function isGmaxHookEntry(entry, hooksDir) {
+    var _a, _b;
+    return (_b = (_a = entry.hooks) === null || _a === void 0 ? void 0 : _a.some((h) => { var _a; return (_a = h.command) === null || _a === void 0 ? void 0 : _a.includes(hooksDir); })) !== null && _b !== void 0 ? _b : false;
+}
+/** Strip gmax hook entries from settings.hooks in place, preserving unrelated
+ *  user hooks. Returns true if anything was removed. */
+function removeGmaxHooks(settings, hooksDir) {
+    if (!settings.hooks)
+        return false;
+    let changed = false;
+    for (const [event, entries] of Object.entries(settings.hooks)) {
+        const kept = entries.filter((e) => !isGmaxHookEntry(e, hooksDir));
+        if (kept.length !== entries.length)
+            changed = true;
+        if (kept.length > 0)
+            settings.hooks[event] = kept;
+        else
+            delete settings.hooks[event];
+    }
+    if (Object.keys(settings.hooks).length === 0)
+        delete settings.hooks;
+    return changed;
 }
 function saveSettings(settingsPath, settings) {
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(settingsPath), { recursive: true });
@@ -103,10 +136,14 @@ function mergeHooks(existing, incoming) {
 function installPlugin() {
     return __awaiter(this, void 0, void 0, function* () {
         const root = resolveDroidRoot();
+        const settingsPath = node_path_1.default.join(root, "settings.json");
+        // Validate/parse settings BEFORE writing anything. A malformed, user-owned
+        // settings.json aborts the install here — otherwise we'd either clobber it
+        // with {} or leave half-written hook scripts behind on the failure path.
+        const settings = loadSettings(settingsPath);
         const gmaxBin = resolveGmaxBin();
         const hooksDir = node_path_1.default.join(root, "hooks", "gmax");
         const skillsDir = node_path_1.default.join(root, "skills", "gmax");
-        const settingsPath = node_path_1.default.join(root, "settings.json");
         // 1. Install hook scripts (start/stop daemon)
         const startScript = `
 const { execFileSync } = require("child_process");
@@ -166,7 +203,6 @@ try { execFileSync("gmax", ["watch", "stop", "--all"], { stdio: "ignore", timeou
                 },
             ],
         };
-        const settings = loadSettings(settingsPath);
         settings.enableHooks = true;
         settings.allowBackgroundProcesses = true;
         settings.hooks = mergeHooks(settings.hooks, hookConfig);
@@ -179,12 +215,28 @@ function uninstallPlugin() {
         const root = resolveDroidRoot();
         const hooksDir = node_path_1.default.join(root, "hooks", "gmax");
         const skillsDir = node_path_1.default.join(root, "skills", "gmax");
+        const settingsPath = node_path_1.default.join(root, "settings.json");
         if (node_fs_1.default.existsSync(hooksDir))
             node_fs_1.default.rmSync(hooksDir, { recursive: true, force: true });
         if (node_fs_1.default.existsSync(skillsDir))
             node_fs_1.default.rmSync(skillsDir, { recursive: true, force: true });
+        // Remove only gmax hook entries from settings.json, preserving unrelated user
+        // hooks. enableHooks/allowBackgroundProcesses are left alone — other hooks may
+        // depend on them.
+        if (node_fs_1.default.existsSync(settingsPath)) {
+            try {
+                const settings = loadSettings(settingsPath);
+                if (removeGmaxHooks(settings, hooksDir)) {
+                    saveSettings(settingsPath, settings);
+                    console.log("✅ Removed gmax hooks from settings.json");
+                }
+            }
+            catch (err) {
+                // Don't clobber an invalid settings file on uninstall either.
+                console.warn(`⚠️  Skipped settings cleanup: ${err.message}`);
+            }
+        }
         console.log("✅ gmax removed from Factory Droid");
-        console.log("NOTE: You may want to manually clean up 'hooks' in ~/.factory/settings.json");
     });
 }
 exports.installDroid = new commander_1.Command("install-droid")

package/dist/commands/repair.js

@@ -0,0 +1,186 @@
+"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());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.repair = void 0;
+const readline = __importStar(require("node:readline"));
+const commander_1 = require("commander");
+const ora_1 = __importDefault(require("ora"));
+const config_1 = require("../config");
+const index_config_1 = require("../lib/index/index-config");
+const vector_db_1 = require("../lib/store/vector-db");
+const exit_1 = require("../lib/utils/exit");
+const project_registry_1 = require("../lib/utils/project-registry");
+function confirm(message) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(answer.toLowerCase() === "y");
+        });
+    });
+}
+exports.repair = new commander_1.Command("repair")
+    .description("Repair the centralized index (recover from a schema mismatch)")
+    .option("--rebuild", "Drop the shared vector table and re-index every project at the configured embedding dim", false)
+    .option("-y, --yes", "Skip the confirmation prompt", false)
+    .addHelpText("after", `
+The shared LanceDB \`chunks\` table is fixed-width at creation. Switching model
+tiers (e.g. small 384d -> standard 768d) strands the table at the old width, so
+every write then fails. A per-project \`gmax index --reset\` only deletes rows —
+it can't change the table width. \`${config_1.REBUILD_COMMAND}\` drops the table and
+re-embeds all projects at the current dim.
+
+Examples:
+  gmax repair             Show schema status and what a rebuild would do
+  gmax repair --rebuild   Drop the table and re-index every project
+  gmax repair --rebuild -y  Rebuild without the confirmation prompt
+`)
+    .action((opts) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c;
+    try {
+        const globalConfig = (0, index_config_1.readGlobalConfig)();
+        const configDim = globalConfig.vectorDim;
+        // Physical width of the on-disk table (null if no table yet). Opened
+        // read-only; safe to inspect even while the daemon holds the table.
+        let physicalDim = null;
+        const probe = new vector_db_1.VectorDB(config_1.PATHS.lancedbDir);
+        try {
+            physicalDim = yield probe.getSchemaVectorDim();
+        }
+        finally {
+            yield probe.close();
+        }
+        const projects = (0, project_registry_1.listProjects)().filter((p) => p.status === "indexed" || p.status === "pending");
+        const dimLine = physicalDim == null
+            ? "Vector table: none yet"
+            : physicalDim === configDim
+                ? `Vector table: ${physicalDim}d (matches config)`
+                : `Vector table: ${physicalDim}d, config expects ${configDim}d (MISMATCH)`;
+        console.log(dimLine);
+        if (!opts.rebuild) {
+            if (physicalDim != null && physicalDim !== configDim) {
+                console.log(`\nRun '${config_1.REBUILD_COMMAND}' to drop the table and re-index ` +
+                    `${projects.length} project(s) at ${configDim}d.`);
+            }
+            else {
+                console.log(`\nNothing to repair. Pass --rebuild to force a full drop + re-index anyway.`);
+            }
+            return;
+        }
+        if (projects.length === 0) {
+            console.log("\nNo indexed projects to rebuild.");
+            return;
+        }
+        const totalChunks = projects.reduce((sum, p) => { var _a; return sum + ((_a = p.chunkCount) !== null && _a !== void 0 ? _a : 0); }, 0);
+        console.log(`\nThis will DROP the shared vector table and re-embed ${projects.length} project(s)` +
+            (totalChunks > 0
+                ? ` (~${totalChunks.toLocaleString()} chunks).`
+                : "."));
+        for (const p of projects) {
+            console.log(`  - ${p.name}`);
+        }
+        if (!opts.yes) {
+            const ok = yield confirm("\nContinue?");
+            if (!ok) {
+                console.log("Cancelled.");
+                return;
+            }
+        }
+        // The rebuild must run through the daemon — it is the single writer for
+        // the shared table. Refuse rather than risk a torn drop alongside a
+        // daemon mid-flush.
+        const { ensureDaemonRunning, sendStreamingCommand } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-client")));
+        if (!(yield ensureDaemonRunning())) {
+            console.error("Could not start the gmax daemon. Start it with 'gmax watch --daemon -b' and retry.");
+            process.exitCode = 1;
+            return;
+        }
+        const spinner = (0, ora_1.default)({
+            text: "Dropping vector table...",
+            isSilent: !process.stdout.isTTY,
+        }).start();
+        try {
+            const done = yield sendStreamingCommand({ cmd: "repair" }, (msg) => {
+                var _a, _b, _c, _d;
+                if (msg.phase === "drop") {
+                    spinner.text = "Dropping vector table...";
+                }
+                else if (msg.phase === "reindex") {
+                    const doneN = (_a = msg.projectsDone) !== null && _a !== void 0 ? _a : 0;
+                    const totalN = (_b = msg.projectsTotal) !== null && _b !== void 0 ? _b : projects.length;
+                    const processed = (_c = msg.processed) !== null && _c !== void 0 ? _c : 0;
+                    const total = (_d = msg.total) !== null && _d !== void 0 ? _d : 0;
+                    const counts = total > 0 ? ` ${processed}/${total}` : "";
+                    spinner.text = `Re-indexing ${msg.project} (${doneN + 1}/${totalN})${counts}`;
+                }
+            });
+            if (!done.ok) {
+                spinner.fail("Rebuild failed");
+                throw new Error((_a = done.error) !== null && _a !== void 0 ? _a : "daemon repair failed");
+            }
+            const rebuilt = (_b = done.projects) !== null && _b !== void 0 ? _b : 0;
+            const indexed = (_c = done.indexed) !== null && _c !== void 0 ? _c : 0;
+            spinner.succeed(`Rebuilt ${rebuilt} project(s) at ${configDim}d • ${indexed.toLocaleString()} chunks`);
+        }
+        catch (e) {
+            if (spinner.isSpinning)
+                spinner.fail("Rebuild failed");
+            throw e;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        console.error("Failed to repair:", message);
+        process.exitCode = 1;
+    }
+    finally {
+        yield (0, exit_1.gracefulExit)();
+    }
+}));

package/dist/commands/search-run.js

@@ -130,7 +130,18 @@ function runSearch(params) {
                 if (!indexState && (locked || projectStatus === "pending")) {
                     indexState = { indexing: true, pendingFiles: 0 };
                 }
-                const hasRows = yield vectorDb.hasAnyRows();
+                // Decide first-run auto-index by whether the project being searched has
+                // rows — NOT whether the shared store has any rows at all. The store is
+                // centralized, so a global hasAnyRows() lets a sibling project's rows
+                // suppress this project's first-run index. Cross-project mode keeps the
+                // global check: it spans already-indexed projects and must not first-run
+                // a single directory just because the cwd happens to be unindexed.
+                const crossProject = !!options.allProjects ||
+                    !!options.projects ||
+                    !!options.excludeProjects;
+                const hasRows = crossProject
+                    ? yield vectorDb.hasAnyRows()
+                    : yield vectorDb.hasRowsForPath(effectiveRoot);
                 const needsSync = options.sync || !hasRows;
                 if (needsSync) {
                     const isTTY = process.stdout.isTTY;

package/dist/commands/watch.js

@@ -106,7 +106,8 @@ exports.watch = new commander_1.Command("watch")
                 if (oldPid) {
                     const exited = yield waitForProcessExit(oldPid, 20000);
                     if (!exited) {
-                        console.log(`Old daemon (PID ${oldPid}) still draining after 20s — starting anyway`);
+                        console.log(`Old daemon (PID ${oldPid}) still draining after 20s — starting anyway ` +
+                            `(its draining marker keeps the successor from killing it mid-cleanup)`);
                     }
                 }
                 else {

package/dist/config.js

@@ -33,9 +33,11 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INDEXABLE_EXTENSIONS = exports.FRAGMENT_COMPACT_THRESHOLD = exports.DISK_LOW_BYTES = exports.DISK_CRITICAL_BYTES = exports.MAX_FILE_SIZE_BYTES = exports.PATHS = exports.MAX_WORKER_MEMORY_MB = exports.WORKER_BOOT_TIMEOUT_MS = exports.WORKER_TIMEOUT_MS = exports.CHUNKER_VERSION_HISTORY = exports.CONFIG = exports.MODEL_IDS = exports.DEFAULT_MODEL_TIER = exports.MODEL_TIERS = void 0;
+exports.INDEXABLE_EXTENSIONS = exports.FRAGMENT_COMPACT_THRESHOLD = exports.DISK_LOW_BYTES = exports.DISK_CRITICAL_BYTES = exports.MAX_FILE_SIZE_BYTES = exports.PATHS = exports.MAX_WORKER_MEMORY_MB = exports.WORKER_BOOT_TIMEOUT_MS = exports.WORKER_TIMEOUT_MS = exports.REBUILD_COMMAND = exports.CHUNKER_VERSION_HISTORY = exports.CONFIG = exports.MODEL_IDS = exports.DEFAULT_MODEL_TIER = exports.MODEL_TIERS = void 0;
 exports.describeChunkerGap = describeChunkerGap;
 exports.describeEmbeddingGap = describeEmbeddingGap;
+exports.describeSchemaDimGap = describeSchemaDimGap;
+exports.schemaDimAgentRow = schemaDimAgentRow;
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 exports.MODEL_TIERS = {
@@ -157,6 +159,43 @@ function describeEmbeddingGap(stored, current) {
         severity: dimChanged ? "breaking" : "additive",
     };
 }
+/**
+ * The single sanctioned recovery for a physical table-width mismatch. The shared
+ * `chunks` table is fixed-width at creation, so a tier/dim change strands it at
+ * the old width and every write throws. A per-project `gmax index --reset` only
+ * deletes rows — it can't change the shared table's width — so the real fix is a
+ * global drop-and-rebuild. doctor, the insertBatch failure, and the staleness
+ * hint all point here so the guidance never contradicts itself.
+ */
+exports.REBUILD_COMMAND = "gmax repair --rebuild";
+/**
+ * Describe the gap between the LanceDB table's PHYSICAL `vector` width and the
+ * width the current global config would produce, or null when they agree (or no
+ * table exists yet). This is distinct from {@link describeEmbeddingGap}: that one
+ * compares the project REGISTRY's recorded `{modelTier, vectorDim}` to config
+ * (logical drift, fixable per project), while this compares the actual on-disk
+ * table schema to config (physical drift — every write throws until a global
+ * rebuild). A table can match the registry yet still be physically stranded, so
+ * doctor reports both independently.
+ */
+function describeSchemaDimGap(tableDim, configDim) {
+    if (tableDim == null)
+        return null; // no table on disk yet — nothing to compare
+    if (tableDim === configDim)
+        return null;
+    return { tableDim, configDim };
+}
+/** Stable, tab-delimited doctor `--agent` row for a physical schema-dim
+ * mismatch. Kept here (pure) so the wire format is testable without running the
+ * full doctor command. */
+function schemaDimAgentRow(gap) {
+    return [
+        "schema_dim_mismatch",
+        `table_dim=${gap.tableDim}`,
+        `current_dim=${gap.configDim}`,
+        `fix=${exports.REBUILD_COMMAND}`,
+    ].join("\t");
+}
 exports.WORKER_TIMEOUT_MS = Number.parseInt(process.env.GMAX_WORKER_TIMEOUT_MS || "60000", 10);
 exports.WORKER_BOOT_TIMEOUT_MS = Number.parseInt(process.env.GMAX_WORKER_BOOT_TIMEOUT_MS || "300000", 10);
 exports.MAX_WORKER_MEMORY_MB = (() => {
@@ -177,6 +216,11 @@ exports.PATHS = {
     daemonSocket: path.join(GLOBAL_ROOT, "daemon.sock"),
     daemonPidFile: path.join(GLOBAL_ROOT, "daemon.pid"),
     daemonLockFile: path.join(GLOBAL_ROOT, "daemon.lock"),
+    // Written by a daemon while it is gracefully shutting down (draining workers,
+    // closing LanceDB). A successor's killStaleProcesses() respects this so it
+    // never SIGKILLs a peer mid-cleanup once the peer has already dropped its
+    // socket/PID/lock liveness markers.
+    daemonDrainingFile: path.join(GLOBAL_ROOT, "daemon.draining"),
     // Centralized index storage — one database for all indexed directories
     lancedbDir: path.join(GLOBAL_ROOT, "lancedb"),
     cacheDir: path.join(GLOBAL_ROOT, "cache"),

package/dist/index.js

@@ -64,6 +64,7 @@ const project_1 = require("./commands/project");
 const recent_1 = require("./commands/recent");
 const related_1 = require("./commands/related");
 const remove_1 = require("./commands/remove");
+const repair_1 = require("./commands/repair");
 const review_1 = require("./commands/review");
 const search_1 = require("./commands/search");
 const serve_1 = require("./commands/serve");
@@ -141,6 +142,7 @@ commander_1.program.addCommand(review_1.review);
 commander_1.program.addCommand(setup_1.setup);
 commander_1.program.addCommand(config_1.config);
 commander_1.program.addCommand(doctor_1.doctor);
+commander_1.program.addCommand(repair_1.repair);
 // Plugins
 commander_1.program.addCommand(plugin_1.plugin);
 // Legacy plugin installers (hidden — use `gmax plugin` instead)

package/dist/lib/daemon/daemon.js

@@ -56,6 +56,7 @@ const syncer_1 = require("../index/syncer");
 const server_1 = require("../llm/server");
 const meta_cache_1 = require("../store/meta-cache");
 const vector_db_1 = require("../store/vector-db");
+const daemon_client_1 = require("../utils/daemon-client");
 const daemon_launcher_1 = require("../utils/daemon-launcher");
 const log_rotate_1 = require("../utils/log-rotate");
 const logger_1 = require("../utils/logger");
@@ -600,6 +601,66 @@ class Daemon {
             }));
         });
     }
+    /**
+     * Core full-(re)index of one project: quiesce its batch processor + watcher,
+     * run initialSync, then re-watch in the finally. Shared by indexProject (one
+     * project per IPC connection) and repairRebuild (all projects after a global
+     * table drop). The caller owns the project lock, the maintenance pause, the
+     * heartbeat, and the AbortController; this method owns the watcher handoff and
+     * the indexProgress bookkeeping (so concurrent searches get a partial-result
+     * footer while it runs — Phase 6).
+     */
+    reindexOneProject(root, opts, signal, onProgress) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.vectorDb || !this.metaCache) {
+                throw new Error("daemon resources not ready");
+            }
+            // Pause the project's batch processor during full index
+            const processor = this.processors.get(root);
+            if (processor) {
+                yield processor.close();
+                this.processors.delete(root);
+            }
+            const sub = this.subscriptions.get(root);
+            if (sub) {
+                yield sub.unsubscribe();
+                this.subscriptions.delete(root);
+            }
+            // Mark this root as full-indexing so concurrent searches get a
+            // partial-result footer (Phase 6); seeded at 0/0 until the first tick.
+            this.indexProgress.set(root, { processed: 0, total: 0 });
+            try {
+                return yield (0, syncer_1.initialSync)({
+                    projectRoot: root,
+                    reset: opts.reset,
+                    dryRun: opts.dryRun,
+                    vectorDb: this.vectorDb,
+                    metaCache: this.metaCache,
+                    signal,
+                    onProgress: (info) => {
+                        this.resetActivity();
+                        this.indexProgress.set(root, {
+                            processed: info.processed,
+                            total: info.total,
+                        });
+                        onProgress(info);
+                    },
+                });
+            }
+            finally {
+                this.indexProgress.delete(root);
+                // Re-enable watcher (skip if shutting down)
+                if (!this.shuttingDown) {
+                    try {
+                        yield this.watchProject(root);
+                    }
+                    catch (err) {
+                        console.error(`[daemon] Failed to re-watch ${path.basename(root)}:`, err);
+                    }
+                }
+            }
+        });
+    }
     indexProject(root, conn, opts) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.withProjectLock(root, () => __awaiter(this, void 0, void 0, function* () {
@@ -608,51 +669,24 @@ class Daemon {
                     (0, ipc_handler_1.writeDone)(conn, { ok: false, error: "daemon resources not ready" });
                     return;
                 }
-                // Pause the project's batch processor during full index
-                const processor = this.processors.get(root);
-                if (processor) {
-                    yield processor.close();
-                    this.processors.delete(root);
-                }
-                const sub = this.subscriptions.get(root);
-                if (sub) {
-                    yield sub.unsubscribe();
-                    this.subscriptions.delete(root);
-                }
                 const ac = new AbortController();
                 conn.on("close", () => ac.abort());
                 this.shutdownAbortControllers.add(ac);
                 this.vectorDb.pauseMaintenanceLoop();
                 const stopHeartbeat = (0, ipc_handler_1.startHeartbeat)(conn);
                 let lastProgressTime = 0;
-                // Mark this root as full-indexing so concurrent searches get a
-                // partial-result footer (Phase 6); seeded at 0/0 until the first tick.
-                this.indexProgress.set(root, { processed: 0, total: 0 });
                 try {
-                    const result = yield (0, syncer_1.initialSync)({
-                        projectRoot: root,
-                        reset: opts.reset,
-                        dryRun: opts.dryRun,
-                        vectorDb: this.vectorDb,
-                        metaCache: this.metaCache,
-                        signal: ac.signal,
-                        onProgress: (info) => {
-                            this.resetActivity();
-                            this.indexProgress.set(root, {
-                                processed: info.processed,
-                                total: info.total,
-                            });
-                            const now = Date.now();
-                            if (now - lastProgressTime < 100)
-                                return;
-                            lastProgressTime = now;
-                            (0, ipc_handler_1.writeProgress)(conn, {
-                                processed: info.processed,
-                                indexed: info.indexed,
-                                total: info.total,
-                                filePath: info.filePath,
-                            });
-                        },
+                    const result = yield this.reindexOneProject(root, opts, ac.signal, (info) => {
+                        const now = Date.now();
+                        if (now - lastProgressTime < 100)
+                            return;
+                        lastProgressTime = now;
+                        (0, ipc_handler_1.writeProgress)(conn, {
+                            processed: info.processed,
+                            indexed: info.indexed,
+                            total: info.total,
+                            filePath: info.filePath,
+                        });
                     });
                     stopHeartbeat();
                     (0, ipc_handler_1.writeDone)(conn, {
@@ -671,22 +705,100 @@ class Daemon {
                 }
                 finally {
                     stopHeartbeat();
-                    this.indexProgress.delete(root);
                     this.shutdownAbortControllers.delete(ac);
                     (_a = this.vectorDb) === null || _a === void 0 ? void 0 : _a.resumeMaintenanceLoop();
-                    // Re-enable watcher (skip if shutting down)
-                    if (!this.shuttingDown) {
-                        try {
-                            yield this.watchProject(root);
-                        }
-                        catch (err) {
-                            console.error(`[daemon] Failed to re-watch ${path.basename(root)}:`, err);
-                        }
-                    }
                 }
             }));
         });
     }
+    /**
+     * Global recovery for a physical table-width mismatch (the chosen "global
+     * rebuild" strategy): drop the shared `chunks` table and re-index every
+     * registered project at the configured dim. The table is fixed-width at
+     * creation, so this is the only way to move it from e.g. 384d to 768d after a
+     * tier change. Streams per-project progress over `conn`. Each project is
+     * reindexed under its own lock with `reset: true`, which also clears that
+     * project's stale MetaCache entries so everything re-embeds into the freshly
+     * recreated (lazily, at config width) table.
+     */
+    repairRebuild(conn) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (!this.vectorDb || !this.metaCache) {
+                (0, ipc_handler_1.writeDone)(conn, { ok: false, error: "daemon resources not ready" });
+                return;
+            }
+            const ac = new AbortController();
+            conn.on("close", () => ac.abort());
+            this.shutdownAbortControllers.add(ac);
+            this.vectorDb.pauseMaintenanceLoop();
+            const stopHeartbeat = (0, ipc_handler_1.startHeartbeat)(conn);
+            // Reindex every project the daemon would normally index on startup.
+            const projects = (0, project_registry_1.listProjects)().filter((p) => p.status === "indexed" || p.status === "pending");
+            const globalConfig = (0, index_config_1.readGlobalConfig)();
+            let rebuilt = 0;
+            let totalIndexed = 0;
+            let lastProgressTime = 0;
+            try {
+                // Drop the shared table — recreated lazily at the configured width on the
+                // first insert of the reindex below.
+                (0, ipc_handler_1.writeProgress)(conn, { phase: "drop", projectsTotal: projects.length });
+                yield this.vectorDb.drop();
+                for (const p of projects) {
+                    if (ac.signal.aborted)
+                        break;
+                    const name = p.name || path.basename(p.root);
+                    yield this.withProjectLock(p.root, () => __awaiter(this, void 0, void 0, function* () {
+                        const result = yield this.reindexOneProject(p.root, { reset: true }, ac.signal, (info) => {
+                            const now = Date.now();
+                            if (now - lastProgressTime < 100)
+                                return;
+                            lastProgressTime = now;
+                            (0, ipc_handler_1.writeProgress)(conn, {
+                                phase: "reindex",
+                                project: name,
+                                projectsDone: rebuilt,
+                                projectsTotal: projects.length,
+                                processed: info.processed,
+                                indexed: info.indexed,
+                                total: info.total,
+                                filePath: info.filePath,
+                            });
+                        });
+                        totalIndexed += result.indexed;
+                        const proj = (0, project_registry_1.getProject)(p.root);
+                        if (proj) {
+                            (0, project_registry_1.registerProject)(Object.assign(Object.assign({}, proj), { vectorDim: globalConfig.vectorDim, modelTier: globalConfig.modelTier, embedMode: globalConfig.embedMode, lastIndexed: new Date().toISOString(), chunkCount: result.indexed, status: "indexed", chunkerVersion: config_1.CONFIG.CHUNKER_VERSION }));
+                        }
+                    }));
+                    rebuilt++;
+                }
+                stopHeartbeat();
+                (0, ipc_handler_1.writeDone)(conn, {
+                    ok: true,
+                    projects: rebuilt,
+                    projectsTotal: projects.length,
+                    indexed: totalIndexed,
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error("[daemon] repairRebuild failed:", msg);
+                stopHeartbeat();
+                (0, ipc_handler_1.writeDone)(conn, {
+                    ok: false,
+                    error: msg,
+                    projects: rebuilt,
+                    indexed: totalIndexed,
+                });
+            }
+            finally {
+                stopHeartbeat();
+                this.shutdownAbortControllers.delete(ac);
+                (_a = this.vectorDb) === null || _a === void 0 ? void 0 : _a.resumeMaintenanceLoop();
+            }
+        });
+    }
     removeProject(root, conn) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.withProjectLock(root, () => __awaiter(this, void 0, void 0, function* () {
@@ -849,6 +961,10 @@ class Daemon {
                 return;
             this.shuttingDown = true;
             console.log("[daemon] Shutting down...");
+            // Announce graceful shutdown BEFORE dropping the liveness markers below, so a
+            // successor spawned during the (possibly long) drain sees the draining marker
+            // and defers instead of SIGKILLing us mid-cleanup.
+            (0, daemon_client_1.writeDrainingMarker)(process.pid);
             // Drop external liveness markers FIRST so the next daemon start isn't
             // fooled by leftover state if the long cleanup below is interrupted
             // (uncaught exception, second SIGTERM, OOM kill mid-shutdown). The
@@ -926,6 +1042,9 @@ class Daemon {
                 const pid = (0, daemon_launcher_1.spawnDaemon)();
                 console.log(`[daemon] Spawned successor daemon${pid ? ` (PID: ${pid})` : " (spawn failed)"}`);
             }
+            // Cleanly drained — drop the marker so a later start doesn't defer to a
+            // process that's already gone (it self-expires after DRAIN_GRACE_MS anyway).
+            (0, daemon_client_1.clearDrainingMarker)();
             console.log("[daemon] Shutdown complete");
         });
     }

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

@@ -228,6 +228,12 @@ function handleCommand(daemon, cmd, conn) {
                     daemon.removeProject(root, conn);
                     return null;
                 }
+                case "repair": {
+                    // Global drop-and-rebuild recovery for a physical table-width mismatch.
+                    // Streams per-project progress; daemon manages the connection.
+                    daemon.repairRebuild(conn);
+                    return null;
+                }
                 case "summarize": {
                     const root = String(cmd.root || "");
                     if (!root)

package/dist/lib/daemon/process-manager.js

@@ -89,8 +89,19 @@ class ProcessManager {
                 (0, logger_1.log)("daemon", "No stale processes found");
                 return;
             }
+            // A peer that's gracefully shutting down has already dropped its
+            // socket/PID/lock (so the liveness probes below read "stale") yet is still
+            // mid-cleanup — destroying workers, closing LanceDB. Killing it now corrupts
+            // that teardown. Defer to its draining marker: don't kill it, and don't
+            // sweep its workers (it's reaping them itself); just take over the free lock.
+            let anyDraining = false;
             for (const pid of daemonPids) {
                 (0, logger_1.log)("daemon", `found daemon PID:${pid}, checking liveness...`);
+                if ((0, daemon_client_1.isDaemonDraining)(pid)) {
+                    anyDraining = true;
+                    (0, logger_1.log)("daemon", `daemon PID:${pid} is gracefully draining — leaving it to exit, taking over`);
+                    continue;
+                }
                 // A busy daemon (mid-index, compaction, big LMDB write) can block the
                 // event loop long enough to miss a ping. Two independent liveness
                 // probes — if either says "alive", defer to the running peer instead
@@ -109,9 +120,16 @@ class ProcessManager {
             }
             // 2. Kill orphaned workers from previous daemon instances.
             // Safe because this runs before the new daemon's worker pool is initialized.
-            for (const pid of workerPids) {
-                (0, logger_1.log)("daemon", `killing orphaned worker PID:${pid}`);
-                yield (0, process_1.killProcess)(pid);
+            // Skipped while a peer is draining — those workers belong to it and it's
+            // tearing them down; sweeping them here would race its own cleanup.
+            if (anyDraining) {
+                (0, logger_1.log)("daemon", "skipping orphan-worker sweep — a peer is draining its own workers");
+            }
+            else {
+                for (const pid of workerPids) {
+                    (0, logger_1.log)("daemon", `killing orphaned worker PID:${pid}`);
+                    yield (0, process_1.killProcess)(pid);
+                }
             }
             (0, logger_1.log)("daemon", `Cleaned up ${daemonPids.length} stale daemon(s), ${workerPids.length} orphaned worker(s)`);
         });

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

@@ -279,6 +279,32 @@ class VectorDB {
             summary: "",
         };
     }
+    /**
+     * Read the physical width of the on-disk `vector` column, or null if the
+     * table doesn't exist yet. Non-throwing and validation-free on purpose: doctor
+     * uses it to detect a table stranded at an old width after a tier change, and
+     * must see the truth even when the table is incompatible with the current
+     * config (a throwing ensureTable would mask exactly the mismatch we're hunting).
+     */
+    getSchemaVectorDim() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const db = yield this.getDb();
+            let table;
+            try {
+                table = yield db.openTable(TABLE_NAME);
+            }
+            catch (_a) {
+                return null; // no table on disk yet
+            }
+            const schema = yield table.schema();
+            const field = schema.fields.find((f) => f.name === "vector");
+            if (!field)
+                return null;
+            // The `vector` column is a FixedSizeList; its listSize is the vector width.
+            const listSize = field.type.listSize;
+            return typeof listSize === "number" ? listSize : null;
+        });
+    }
     validateSchema(table) {
         return __awaiter(this, void 0, void 0, function* () {
             const schema = yield table.schema();
@@ -421,7 +447,9 @@ class VectorDB {
                 // Fail loudly and point at the fix instead.
                 if (vec.length !== this.vectorDim) {
                     throw new Error(`Vector dimension mismatch: got ${vec.length}d, expected ${this.vectorDim}d. ` +
-                        "The embedding model tier likely changed without a rebuild — run `gmax index --reset`.");
+                        "The embedding model tier likely changed without a rebuild — the shared " +
+                        `table is fixed-width, so run \`${config_1.REBUILD_COMMAND}\` (a per-project ` +
+                        "`gmax index --reset` cannot change the table width).");
                 }
                 rec.vector = vec;
                 rec.colbert = toBuffer(rec.colbert);

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

@@ -47,6 +47,9 @@ exports.isDaemonRunning = isDaemonRunning;
 exports.isDaemonHeartbeatFresh = isDaemonHeartbeatFresh;
 exports.readDaemonPid = readDaemonPid;
 exports.waitForProcessExit = waitForProcessExit;
+exports.writeDrainingMarker = writeDrainingMarker;
+exports.clearDrainingMarker = clearDrainingMarker;
+exports.isDaemonDraining = isDaemonDraining;
 exports.ensureDaemonRunning = ensureDaemonRunning;
 exports.sendStreamingCommand = sendStreamingCommand;
 const fs = __importStar(require("node:fs"));
@@ -186,6 +189,56 @@ function waitForProcessExit(pid, timeoutMs) {
         return false;
     });
 }
+// A daemon's graceful shutdown can run well past the 20s restart wait — worker
+// SIGTERM→SIGKILL escalation (5s), maintenance drain (10s), LanceDB close (5s),
+// LLM/MLX teardown. Treat a draining marker as authoritative for this long; past
+// it, assume the draining daemon wedged and let killStaleProcesses reclaim it.
+const DRAIN_GRACE_MS = 90000;
+/**
+ * Record that this daemon (pid) has begun graceful shutdown, so a successor's
+ * killStaleProcesses() won't SIGKILL it mid-cleanup after it drops its
+ * socket/PID/lock liveness markers. Best-effort; cleared by clearDrainingMarker
+ * on a clean exit and otherwise self-expires after DRAIN_GRACE_MS.
+ */
+function writeDrainingMarker(pid) {
+    try {
+        fs.mkdirSync(config_1.PATHS.globalRoot, { recursive: true });
+        fs.writeFileSync(config_1.PATHS.daemonDrainingFile, JSON.stringify({ pid, ts: Date.now() }));
+    }
+    catch (_a) { }
+}
+/** Remove the draining marker (clean end of shutdown). */
+function clearDrainingMarker() {
+    try {
+        fs.unlinkSync(config_1.PATHS.daemonDrainingFile);
+    }
+    catch (_a) { }
+}
+/**
+ * True if `pid` is a daemon currently inside graceful shutdown: a fresh draining
+ * marker naming that exact PID, and the process is still alive. A stale marker
+ * (older than DRAIN_GRACE_MS), a mismatched PID, or a dead process all read as
+ * "not draining" so a wedged or already-exited predecessor is still reclaimable.
+ */
+function isDaemonDraining(pid) {
+    try {
+        const { pid: markerPid, ts } = JSON.parse(fs.readFileSync(config_1.PATHS.daemonDrainingFile, "utf-8"));
+        if (markerPid !== pid)
+            return false;
+        if (typeof ts !== "number" || Date.now() - ts > DRAIN_GRACE_MS)
+            return false;
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (_a) {
+            return false; // process already gone — done draining
+        }
+    }
+    catch (_b) {
+        return false; // no marker / unreadable
+    }
+}
 /**
  * Ensure the daemon is running — start it if needed, poll up to 5s.
  * Returns true if daemon is ready, false if it couldn't be started.

package/dist/lib/utils/stale-hint.js

@@ -104,7 +104,9 @@ function maybeWarnStaleEmbedding(projectRoot, opts) {
             `current_dim=${gap.toDim}`,
             `dim_changed=${gap.dimChanged}`,
             `severity=${gap.severity}`,
-            "fix=gmax index --reset",
+            // A dim change needs the global rebuild (shared table is fixed-width); a
+            // same-dim model swap can use a per-project reset.
+            `fix=${gap.dimChanged ? config_1.REBUILD_COMMAND : "gmax index --reset"}`,
         ].join("\t");
         process.stderr.write(`${fields}\n`);
         return;
@@ -113,7 +115,10 @@ function maybeWarnStaleEmbedding(projectRoot, opts) {
     const detail = gap.dimChanged
         ? `vector dim ${gap.fromDim}→${gap.toDim} (incompatible — scores invalid until re-embed)`
         : `model '${gap.fromModel}'→'${gap.toModel}' (same dim; results mix models until re-embed)`;
-    process.stderr.write(`${label}  gmax: '${name}' indexed with embedding ${detail}. Run 'gmax index --reset'. (silence: GMAX_NO_STALE_HINT=1)\n`);
+    const fix = gap.dimChanged
+        ? `Run '${config_1.REBUILD_COMMAND}'`
+        : "Run 'gmax index --reset'";
+    process.stderr.write(`${label}  gmax: '${name}' indexed with embedding ${detail}. ${fix}. (silence: GMAX_NO_STALE_HINT=1)\n`);
 }
 /**
  * Cross-project guard: when a `--all-projects` / `--projects` search spans

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "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.20.0",
+  "version": "0.21.1",
   "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

@@ -41,7 +41,7 @@ gmax trace handleAuth -d 2
 
 **File structure** — collapsed signatures (~4x fewer tokens than reading):
 ```
-gmax skeleton src/lib/auth/
+gmax skeleton src/lib/auth.ts
 ```
 
 **Project overview** — languages, structure, key entry points:

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

@@ -116,7 +116,7 @@ Agent output ends with `t: <test-file>:line\t<test-symbol>\t<hop-label>` rows wh
 ### Skeleton — `gmax skeleton <target>`
 ```
 gmax skeleton src/lib/auth.ts              # single file
-gmax skeleton src/lib/search/              # entire directory
+gmax skeleton handleAuth                   # by symbol name (finds its file)
 gmax skeleton src/a.ts,src/b.ts            # batch
 gmax skeleton src/lib/auth.ts --json       # structured JSON output
 ```