grepmax 0.26.66 → 0.26.68

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

package/README.md

@@ -57,7 +57,7 @@ gmax doctor                   # Health check
 gmax doctor --fix             # Repair checks; full-table maintenance is disabled
 ```
 
-**Storage containment:** full-table compaction is disabled, including forced maintenance and doctor repair. Existing retained index copies are not reclaimed by this release. The verified prune-only recovery path is separate work; normal incremental indexing remains available when the host is healthy and not quarantined. A persistent host safety stop blocks mutation and normal daemon restart; an explicit read-only start can serve the retained index. Installing an update preserves existing quarantine. Speculative embedding warmup and maintenance timers are disabled. On macOS, startup, heavy queries, worker forks and MLX launches require known normal OS memory pressure and a healthy kernel-zone sample; warning or unavailable probes pause heavy work while the daemon serves bounded reads. Known critical pressure still stops the daemon.
+**Storage containment:** full-table compaction is disabled, including forced maintenance and doctor repair. Existing retained index copies are not reclaimed by this release. The verified prune-only recovery path is separate work; normal incremental indexing remains available when the host is healthy and not quarantined. A persistent host safety stop blocks mutation and normal daemon restart; an explicit read-only start can serve the retained index. Installing an update preserves existing quarantine. Speculative embedding warmup and maintenance timers are disabled. Under the default `strict` host policy on macOS, startup, heavy queries, worker forks and MLX launches require known normal OS memory pressure and a healthy kernel-zone sample; warning or unavailable probes pause heavy work while the daemon serves bounded reads. The explicit `critical-only` policy keeps semantic search and indexing available under warning or unavailable probes. Known critical pressure still stops the daemon.
 
 ### Core Commands
 
@@ -240,7 +240,7 @@ gmax status                   # See all projects + watcher status
 
 Adding or indexing a project can start the daemon automatically. MCP acquires primary-project watch leases lazily when an index-reading tool is used; discovery and catalog listing start no background work. It shuts down after 4 hours of inactivity, and hands off to a fresh daemon after 24 hours or once its memory footprint passes 2.5 GB. File-change batches are processed on up to four worker processes by default, added only when work backs up, with one kept free for searches; full-table compaction and new FTS/ANN index builds are disabled by containment. Existing indexes remain readable. Host safety stops persist across restart and block heavy operations.
 
-`gmax watch status` reports failed files, native watcher recovery or polling, dropped-event counts, and the last complete filesystem reconciliation. FSEvents dropped-event warnings keep the native stream attached and preserve the accompanying events. A reconciliation covers the gap; repeated warnings coalesce into one later scan, with a 30-second scan interval. Recovery stays visible until a complete scan covers the latest gap. Other backend errors still trigger subscription recovery; repeated terminal failures fall back to five-minute polling, where recent edits can lag. Search and MCP responses retain health warnings even after the file queue drains. A complete reconciliation means the filesystem scan completed; queued embedding work can still be pending.
+`gmax watch status` reports failed files, native watcher recovery or polling, dropped-event counts, and the last complete filesystem reconciliation. FSEvents dropped-event warnings keep the native stream attached and preserve the accompanying events. A reconciliation covers the gap; repeated warnings coalesce into one later scan, with a 30-second scan interval. Recovery stays visible until a complete scan covers the latest gap. Other backend errors still trigger subscription recovery; repeated terminal failures fall back to five-minute polling, where recent edits can lag. Search and MCP responses retain health warnings even after the file queue drains. Live edit batches can run during reconciliation instead of waiting for the full filesystem walk. Whole-project reindex and removal still quiesce the watcher and drain its work before changing the project. A complete reconciliation means the filesystem scan completed; queued embedding work can still be pending.
 
 Live filesystem edits take priority over background catchup and cleanup. Background batches dispatch one file at a time, with at most four catchup files or 50 cleanup paths. They yield between files when a live edit arrives or the two-second dispatch window is reached; an active file or store commit finishes before yielding. Catchup and cleanup alternate, and one background file is admitted after three consecutive live batches so cleanup continues during sustained editing. Existing retry backoff and worker limits remain in effect.
 
@@ -495,6 +495,14 @@ Production recovery currently requires macOS, a persistent `autostart-disabled`
 
 The child waits for launch and deletion admission tokens, with verified helper PID/start identity recorded as the primary exclusive owner. Existing readers retain exclusion if the parent dies while the helper is alive. Current/tagged/post-cutoff metadata is verified after pruning; recovery refuses more than 256 protected versions before deletion to bound verification. Interrupted attempts require verification and explicit acknowledgement before retry. Linux/APFS fixtures exercise native retention and interruption; supported production host admission is tested separately and still runs freshly for each operation.
 
+For an operator-coordinated recovery window:
+
+1. Check live host pressure and service availability first. Keep development online when recovery admission is already known to refuse. Preserve the configured normal-service policy and any pre-existing safety markers.
+2. Once admission is plausible, create a private, durable task-owned autostart marker and gracefully close the identified daemon and its managed children. Verify shared store owners have drained. `--check` samples resource admission; it does not drain owners or acquire the exclusive prune lease.
+3. Take a fresh bounded version/tag inventory after draining, with a shared lease and small native Session caches. Close that reader before pruning. Choose an explicit real-clock cutoff and verify the union of current, tagged and post-cutoff versions fits the 256-version verification bound. A snapshot from before resumed indexing is unsuitable; never silently move the cutoff to fit the bound.
+4. Run one `recover --prune` with that current version and cutoff. Both `--store <value> recover` and `--store=<value> recover` preserve recovery's table-version option; the explicit `--table` selects the recovery store. Require a verified result and completed receipt before claiming recovery. Record signed table allocated-byte recovery separately from global filesystem free-space change.
+5. Wait for the recovery child and helper to close before lifting exclusion. Clear only the unchanged marker created by this operation, then restore normal service and verify search/watcher health and unchanged configuration. If ownership or the marker changed, preserve containment and inspect it. An uncertain receipt requires retained-state inspection and explicit acknowledgement before another attempt; never automatically retry.
+
 Explicit helper calls persist a private `.gmax-prune-state.json` receipt outside the table before deletion. Cancellation, invalid results, lost ownership and abandoned running receipts remain uncertain; a verified explicit retry records the prior uncertain attempt. Successful receipts include before/after file lengths, allocated bytes and filesystem free space. These measurements do not imply zero retained copies or a macOS physical-footprint cap. Current, tagged and post-cutoff versions are protected; unverified files are retained. Full-table rewriting remains disabled regardless of receipt state.
 
 `~/.gmax/logs/daemon.log` records containment skips and retained historical compaction outcomes, including duration, logical size, disk size before/after, free space, and bytes reclaimed. `gmax status --json` exposes the last outcome under `daemon.compaction`; its `at` timestamp identifies when it was recorded. Five-minute resource snapshots track footprint, RSS, heap, external/ArrayBuffer memory, Lance cache, workers and pending work for memory investigations. Reading status uses retained snapshots and does not scan the index directory. Logs rotate to `daemon.log.prev`.
@@ -570,7 +578,7 @@ grepmax is built upon the foundation of [mgrep](https://github.com/mixedbread-ai
 
 Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).
 
-On macOS, heavy work uses a shared resource ledger and a bounded batch footprint probe covering every gmax process and its children. Native stores, workers and model launches reserve headroom before allocating it. Warning or unknown measurements pause heavy work; known critical pressure persists a stop. The 6 GiB admission budget is a conservative scheduling threshold, not an OS-enforced memory cap. It may be lowered with `GMAX_RESOURCE_BUDGET_MB`. Existing safety markers remain in place after upgrades.
+On macOS, heavy work uses a shared resource ledger and a bounded batch footprint probe covering every gmax process and its children. Native stores, workers and model launches reserve headroom before allocating it. Under the default `strict` policy, warning or unknown measurements pause heavy work; known critical pressure persists a stop under either policy. The 6 GiB admission budget is a conservative scheduling threshold, not an OS-enforced memory cap. It may be lowered with `GMAX_RESOURCE_BUDGET_MB`. Existing safety markers remain in place after upgrades.
 
 MCP sessions started before this resource policy must reconnect after upgrading before heavy work can resume. Keyword search through the bounded read service stays available while those sessions are running. Cached resource snapshots in `gmax status --json` distinguish aggregate physical footprint from daemon RSS.
 

package/dist/bin.js

@@ -39,9 +39,10 @@ exports.registeredForm = registeredForm;
 // Entry point. Picks the gmax home before anything reads config.ts: a command
 // aimed at a project under a secondary store's prefix (src/lib/utils/stores.ts)
 // runs against that store, in-process, so the drive it lives on can always
-// eject. Only Node built-ins and stores.ts may be imported here.
+// eject. Only Node built-ins and dependency-free routing helpers may load here.
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const cli_command_1 = require("./lib/utils/cli-command");
 const stores_1 = require("./lib/utils/stores");
 const DIR_ARG_COMMANDS = new Set(["add", "remove"]);
 function optionValue(argv, names) {
@@ -77,7 +78,9 @@ function selectHome() {
     const argv = process.argv.slice(2);
     // These enumerate/route stores per request rather than pinning the process
     // to its launch cwd's store. In particular an MCP session can serve both.
-    if (argv[0] === "mcp" || argv[0] === "status" || argv[0] === "recover")
+    if (argv[0] === "mcp" ||
+        argv[0] === "status" ||
+        (0, cli_command_1.explicitCommand)(argv) === "recover")
         return;
     const match = (0, stores_1.matchStore)(commandTarget(argv, process.cwd()));
     if (match.kind === "primary")

package/dist/index.js

@@ -79,6 +79,7 @@ const symbols_1 = require("./commands/symbols");
 const test_find_1 = require("./commands/test-find");
 const trace_1 = require("./commands/trace");
 const watch_1 = require("./commands/watch");
+const cli_command_1 = require("./lib/utils/cli-command");
 commander_1.program
     .name("gmax")
     .description("Semantic code search — finds code by meaning, not just strings")
@@ -165,6 +166,6 @@ opencode_1.uninstallOpencode._hidden = true;
 commander_1.program.addCommand(opencode_1.uninstallOpencode);
 // Recovery owns --version as a required table-version value. Keep the root
 // package-version flag from consuming it; other commands retain global options.
-if (process.argv[2] === "recover")
+if ((0, cli_command_1.explicitCommand)(process.argv.slice(2)) === "recover")
     commander_1.program.enablePositionalOptions();
 commander_1.program.parse();

package/dist/lib/daemon/daemon.js

@@ -192,7 +192,14 @@ class Daemon {
             evictSearcher: (root) => {
                 this.searchers.delete(root);
             },
-            runProjectOperation: (root, name, signal, fn) => this.withProjectLock(root, signal, () => this.runSharedOperation(name, signal, fn)),
+            runProjectOperation: (root, name, signal, fn) => {
+                // A filesystem walk can take minutes. Keep it lifecycle-tracked and
+                // admitted, but let live batches hold the project's write lock while
+                // the scan yields. Project removal/reindex quiesces the watcher first.
+                if (name === "watch-catchup")
+                    return this.runSharedOperation(name, signal, fn);
+                return this.withProjectLock(root, signal, () => this.runSharedOperation(name, signal, fn));
+            },
         });
         this.projectMutex = new keyed_mutex_1.KeyedMutex();
         // Tests construct daemons against the real HOME; keep their leases in memory.
@@ -1237,7 +1244,15 @@ class Daemon {
             this.vectorDb.pauseMaintenanceLoop();
             const stopHeartbeat = (0, ipc_handler_1.startHeartbeat)(conn);
             let lastProgressTime = 0;
+            const wasWatching = this.processors.has(root);
+            let watcherQuiesced = false;
             try {
+                // Re-adding a watched project is also a full sync. A catchup scan no
+                // longer holds the write lock, so explicitly drain it before syncing.
+                if (wasWatching) {
+                    yield this.unwatchProjectWithinOperation(root);
+                    watcherQuiesced = true;
+                }
                 const result = yield (0, syncer_1.initialSync)({
                     projectRoot: root,
                     vectorDb: this.vectorDb,
@@ -1287,6 +1302,7 @@ class Daemon {
                     });
                 }
                 yield this.watchProjectWithinOperation(root);
+                watcherQuiesced = false;
                 (0, ipc_handler_1.writeDone)(conn, {
                     ok: true,
                     processed: result.processed,
@@ -1316,6 +1332,15 @@ class Daemon {
             }
             finally {
                 stopHeartbeat();
+                if (watcherQuiesced && !this.shuttingDown) {
+                    try {
+                        this.assertHeavyOperationAdmission("watch");
+                        yield this.watchProjectWithinOperation(root);
+                    }
+                    catch (error) {
+                        console.error("[daemon] Could not restore watcher after add:", error);
+                    }
+                }
                 (_a = this.vectorDb) === null || _a === void 0 ? void 0 : _a.resumeMaintenanceLoop();
             }
         });

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

@@ -653,6 +653,7 @@ class WatcherManager {
                             // Fast path: if only mtime changed but size is identical and we have a hash,
                             // just verify the hash in-process instead of sending to a worker.
                             if ((cached === null || cached === void 0 ? void 0 : cached.hash) && cached.size === stats.size) {
+                                const observed = Object.assign({}, cached);
                                 const snapshot = yield (0, file_utils_1.readFileSnapshot)(absPath, {
                                     projectRoot: root,
                                 });
@@ -664,11 +665,21 @@ class WatcherManager {
                                     continue;
                                 }
                                 const hash = (0, file_utils_1.computeContentHash)(snapshot.buffer, absPath);
-                                if (hash === cached.hash) {
+                                if (hash === observed.hash) {
                                     // Content unchanged — update mtime in cache and skip worker
                                     if (signal.aborted)
                                         return false;
-                                    metaCache.put(absPath, Object.assign(Object.assign({}, cached), { mtimeMs: stats.mtimeMs }));
+                                    // A live batch can finish while this read yields. Never replace
+                                    // newer metadata or resurrect a cache entry it removed.
+                                    const current = metaCache.get(absPath);
+                                    if (current &&
+                                        current.hash === observed.hash &&
+                                        current.mtimeMs === observed.mtimeMs &&
+                                        current.size === observed.size &&
+                                        current.hashVersion === observed.hashVersion &&
+                                        current.hasVectors === observed.hasVectors) {
+                                        metaCache.put(absPath, Object.assign(Object.assign({}, observed), { mtimeMs: stats.mtimeMs }));
+                                    }
                                     skipped++;
                                     continue;
                                 }

package/dist/lib/utils/cli-command.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explicitCommand = explicitCommand;
+/** Find an explicit command after the root's --store option, without treating
+ * its value (which can itself be a command name) as the command. Root help and
+ * version flags retain their normal early-exit behavior. */
+function explicitCommand(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--store") {
+            if (argv[i + 1] === undefined)
+                return undefined;
+            i++;
+        }
+        else if (arg.startsWith("--store=")) {
+        }
+        else if (arg === "--") {
+            return argv[i + 1];
+        }
+        else {
+            return arg.startsWith("-") ? undefined : arg;
+        }
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.26.66",
+  "version": "0.26.68",
   "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.66",
+  "version": "0.26.68",
   "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
   "author": {
     "name": "Robert Owens",