grepmax 0.26.62 → 0.26.63

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

package/README.md

@@ -227,6 +227,8 @@ The CLI and MCP output include score, max similarity, pair count, representative
 
 A single daemon watches your projects via native OS file events (FSEvents/inotify). Changes are detected in sub-second and incrementally reindexed. All writes to LanceDB are routed through the daemon via IPC, eliminating lock contention.
 
+Filesystem watching belongs to gmax, in both daemon and standalone watch modes. Hetchy Developer is an optional monitor/controller that reads gmax status and invokes gmax commands. Watching, indexing and search must work with the dev app and its helper absent or stopped. Any future shared watcher extraction must be an independent component or package with an interface and lifecycle usable without Hetchy Developer; the dev app cannot become a gmax runtime dependency.
+
 The daemon watches only projects that are in use: each Claude Code session (its MCP server and session hooks) holds a lease on its project, and `gmax add` / `gmax index` take a short one. When the last lease ends the project is unwatched; its index stays searchable, and the next session's catch-up scan picks up whatever changed in between. Set `GMAX_WATCH_ALL=1` to watch every registered project instead.
 
 ```bash
@@ -240,6 +242,10 @@ Adding or indexing a project can start the daemon automatically. MCP acquires pr
 
 `gmax watch status` reports failed files, native watcher recovery or polling, dropped-event counts, and the last complete filesystem reconciliation. Polling scans run every five minutes, so recent edits can lag. Search and MCP responses retain health warnings even after the file queue drains. A complete reconciliation means the filesystem scan completed; queued embedding work can still be pending.
 
+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.
+
+`gmax status --json` exposes `projects[].health.queue`; daemon IPC and MCP `index_status` expose the same `indexState.queue`. Counts `live`, `catchup` and `cleanup` cover waiting paths; `activeFiles` covers the selected current batch, including files not yet dispatched. `oldestLiveEditAgeMs` includes both waiting and current-batch live edits until commit, and is null when none remain. Human/agent status, `gmax watch status` and MCP health text show these measures separately. Initial full indexing uses its existing progress counters rather than these watcher queues. Older daemons may omit queue diagnostics.
+
 Temporary embedding backend outages preserve existing indexed rows and retry with backoff from five seconds up to one minute, without exhausting individual files' retry budgets. MLX failures report bounded transport/protocol details in the daemon log. `gmax status --json` includes the most recent resource snapshot when a recycle threshold has been reached; these counters help investigate memory growth, whose cause requires measurement over time.
 
 ## Running under the Claude Code sandbox

package/dist/commands/mcp.js

@@ -1842,7 +1842,8 @@ exports.mcp = new commander_1.Command("mcp")
     }
     function handleIndexStatus() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e;
+            var _a;
+            var _b, _c, _d, _e, _f;
             try {
                 const globalConfig = storeConfig();
                 const projects = storeProjects();
@@ -1860,7 +1861,7 @@ exports.mcp = new commander_1.Command("mcp")
                     : (0, watcher_store_1.getWatcherCoveringPath)(currentRoot());
                 let watcherLine = "Watcher: not running";
                 if (watcher) {
-                    const status = (_a = watcher.status) !== null && _a !== void 0 ? _a : "unknown";
+                    const status = (_b = watcher.status) !== null && _b !== void 0 ? _b : "unknown";
                     const root = path.basename(watcher.projectRoot);
                     const reindex = watcher.lastReindex
                         ? `last reindex: ${Math.round((Date.now() - watcher.lastReindex) / 60000)}m ago`
@@ -1871,12 +1872,14 @@ exports.mcp = new commander_1.Command("mcp")
                     }
                 }
                 if (daemonProject) {
-                    watcherLine = `Watcher: ${(_b = daemonProject.status) !== null && _b !== void 0 ? _b : "unknown"} (${path.basename(daemonProject.root)}/)`;
+                    watcherLine = `Watcher: ${(_c = daemonProject.status) !== null && _c !== void 0 ? _c : "unknown"} (${path.basename(daemonProject.root)}/)`;
                     const health = (0, index_state_footer_1.formatIndexStateFooter)(daemonProject.indexState, {
                         agent: true,
                     });
                     if (health)
                         watcherLine += `\n${health}`;
+                    if ((_a = daemonProject.indexState) === null || _a === void 0 ? void 0 : _a.queue)
+                        watcherLine += `\nQueue: ${(0, index_state_footer_1.formatWatchQueue)(daemonProject.indexState.queue)}`;
                 }
                 // Health overview only. The per-project listing (names, roots,
                 // per-project chunk counts) lives in `list_projects` — keep this tool
@@ -1919,8 +1922,8 @@ exports.mcp = new commander_1.Command("mcp")
                             : null,
                     },
                     watcher: {
-                        status: (_d = (_c = daemonProject === null || daemonProject === void 0 ? void 0 : daemonProject.status) !== null && _c !== void 0 ? _c : watcher === null || watcher === void 0 ? void 0 : watcher.status) !== null && _d !== void 0 ? _d : (secondary() || !daemonStatus.ok ? "unobserved" : "not_running"),
-                        indexState: (_e = daemonProject === null || daemonProject === void 0 ? void 0 : daemonProject.indexState) !== null && _e !== void 0 ? _e : null,
+                        status: (_e = (_d = daemonProject === null || daemonProject === void 0 ? void 0 : daemonProject.status) !== null && _d !== void 0 ? _d : watcher === null || watcher === void 0 ? void 0 : watcher.status) !== null && _e !== void 0 ? _e : (secondary() || !daemonStatus.ok ? "unobserved" : "not_running"),
+                        indexState: (_f = daemonProject === null || daemonProject === void 0 ? void 0 : daemonProject.indexState) !== null && _f !== void 0 ? _f : null,
                     },
                     compaction: compaction.success ? compaction.data : null,
                 });

package/dist/commands/status.js

@@ -273,8 +273,8 @@ Examples:
   gmax status --json       The same, plus daemon and settings, as JSON
 `)
     .action((opts) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d;
-    var _e, _f, _g, _h, _j, _k, _l, _m;
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _j, _k, _l, _m, _o, _p, _q, _r;
     const globalConfig = (0, index_config_1.readGlobalConfig)();
     const projects = (0, project_registry_1.listProjects)();
     const indexing = (0, lock_1.isLocked)(config_1.PATHS.globalRoot);
@@ -316,7 +316,7 @@ Examples:
         console.log(`\n${style.bold("gmax")} · ${globalConfig.modelTier} (${globalConfig.vectorDim}d, ${globalConfig.embedMode})${indexing ? style.yellow(" · indexing...") : ""}`);
     }
     if (((_b = (_a = view.daemon) === null || _a === void 0 ? void 0 : _a.service) === null || _b === void 0 ? void 0 : _b.mode) === "paused") {
-        const reason = ((_e = view.daemon.service.reason) !== null && _e !== void 0 ? _e : "host pressure").replace(/[\r\n\t]/g, " ");
+        const reason = ((_j = view.daemon.service.reason) !== null && _j !== void 0 ? _j : "host pressure").replace(/[\r\n\t]/g, " ");
         console.log(opts.agent
             ? `daemon_service\tmode=paused\treason=${reason}`
             : style.yellow(`Bounded reads available; indexing and embeddings paused: ${reason}`));
@@ -331,14 +331,14 @@ Examples:
         if (opts.agent) {
             console.log(`store\t${store.home}\t${store.state}\tprefixes=${store.prefixes.join(",")}${store.error ? `\terror=${store.error}` : ""}`);
             for (const project of store.projects)
-                console.log(`store_project\t${store.home}\t${project.name}\t${(_f = project.chunkCount) !== null && _f !== void 0 ? _f : 0}\t${(_g = project.status) !== null && _g !== void 0 ? _g : "indexed"}\tcounts=cached`);
+                console.log(`store_project\t${store.home}\t${project.name}\t${(_k = project.chunkCount) !== null && _k !== void 0 ? _k : 0}\t${(_l = project.status) !== null && _l !== void 0 ? _l : "indexed"}\tcounts=cached`);
         }
         else {
             console.log(`\nStore: ${shortenPath(store.home)} — ${store.state}${store.error ? ` (${store.error})` : ""}`);
             if (store.state === "offline")
                 console.log("  Connect the drive to list its projects.");
             for (const project of store.projects)
-                console.log(`  ${project.name}  ${formatChunks(project.chunkCount)} chunks (cached)  ${(_h = project.status) !== null && _h !== void 0 ? _h : "indexed"}`);
+                console.log(`  ${project.name}  ${formatChunks(project.chunkCount)} chunks (cached)  ${(_m = project.status) !== null && _m !== void 0 ? _m : "indexed"}`);
         }
     }
     if (projects.length === 0) {
@@ -355,9 +355,10 @@ Examples:
         for (const project of projects) {
             const st = projectState(project, watchers.get(project.root));
             const isCurrent = project.root === currentRoot;
-            const count = (_j = chunkCounts.get(project.root)) !== null && _j !== void 0 ? _j : project.chunkCount;
+            const count = (_o = chunkCounts.get(project.root)) !== null && _o !== void 0 ? _o : project.chunkCount;
             const identity = (0, embedding_status_1.projectEmbeddingStatus)(project, globalConfig);
-            console.log(`${project.name}\t${formatChunks(count)}\t${formatAge(project.lastIndexed)}\t${st}\tembedding=${identity.state}${isCurrent ? "\tcurrent" : ""}${((_c = view.health) === null || _c === void 0 ? void 0 : _c.get(project.root)) ? `\t${(_k = (0, index_state_footer_1.formatIndexStateFooter)(view.health.get(project.root), { agent: true })) !== null && _k !== void 0 ? _k : ""}` : ""}`);
+            const queue = (_d = (_c = view.health) === null || _c === void 0 ? void 0 : _c.get(project.root)) === null || _d === void 0 ? void 0 : _d.queue;
+            console.log(`${project.name}\t${formatChunks(count)}\t${formatAge(project.lastIndexed)}\t${st}\tembedding=${identity.state}${isCurrent ? "\tcurrent" : ""}${((_e = view.health) === null || _e === void 0 ? void 0 : _e.get(project.root)) ? `\t${(_p = (0, index_state_footer_1.formatIndexStateFooter)(view.health.get(project.root), { agent: true })) !== null && _p !== void 0 ? _p : ""}` : ""}${queue ? `\t${(0, index_state_footer_1.formatWatchQueue)(queue)}` : ""}`);
         }
         const legacyNotice = (0, embedding_status_1.formatLegacyEmbeddingNotice)((0, embedding_status_1.countLegacyEmbeddingProjects)(projects, globalConfig), { agent: true });
         if (legacyNotice)
@@ -373,7 +374,7 @@ Examples:
         const watcher = watchers.get(project.root);
         // Status column
         let statusStr;
-        const projectStatus = (_l = project.status) !== null && _l !== void 0 ? _l : "indexed";
+        const projectStatus = (_q = project.status) !== null && _q !== void 0 ? _q : "indexed";
         if (projectStatus === "pending") {
             statusStr = style.yellow("pending");
         }
@@ -393,7 +394,7 @@ Examples:
             statusStr = style.dim("idle");
         }
         // Chunks column
-        const count = (_m = chunkCounts.get(project.root)) !== null && _m !== void 0 ? _m : project.chunkCount;
+        const count = (_r = chunkCounts.get(project.root)) !== null && _r !== void 0 ? _r : project.chunkCount;
         const chunks = `${formatChunks(count)} chunks`;
         // Age column
         const age = formatAge(project.lastIndexed);
@@ -402,11 +403,14 @@ Examples:
         const marker = isCurrent ? style.cyan(" ←") : "";
         const name = project.name.padEnd(nameWidth);
         console.log(`  ${name}  ${chunks.padEnd(12)}  ${age.padEnd(10)}  ${statusStr}  embedding:${embedding}${marker}`);
-        const health = (0, index_state_footer_1.formatIndexStateFooter)((_d = view.health) === null || _d === void 0 ? void 0 : _d.get(project.root), {
+        const health = (0, index_state_footer_1.formatIndexStateFooter)((_f = view.health) === null || _f === void 0 ? void 0 : _f.get(project.root), {
             agent: false,
         });
         if (health)
             console.log(`    ${health}`);
+        const queue = (_h = (_g = view.health) === null || _g === void 0 ? void 0 : _g.get(project.root)) === null || _h === void 0 ? void 0 : _h.queue;
+        if (queue)
+            console.log(`    queue: ${(0, index_state_footer_1.formatWatchQueue)(queue)}`);
     }
     const legacyNotice = (0, embedding_status_1.formatLegacyEmbeddingNotice)((0, embedding_status_1.countLegacyEmbeddingProjects)(projects, globalConfig));
     if (legacyNotice)

package/dist/commands/watch.js

@@ -401,7 +401,8 @@ exports.watch
     .command("status")
     .description("Show running watchers")
     .action(() => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c;
+    var _a;
+    var _b, _c, _d;
     const { sendDaemonCommand } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-client")));
     const resp = yield sendDaemonCommand({ cmd: "status" });
     if (resp.ok) {
@@ -417,8 +418,10 @@ exports.watch
             const health = (0, index_state_footer_1.formatIndexStateFooter)(p.indexState, { agent: true });
             if (health)
                 console.log(`    ${health}`);
+            if ((_a = p.indexState) === null || _a === void 0 ? void 0 : _a.queue)
+                console.log(`    queue: ${(0, index_state_footer_1.formatWatchQueue)(p.indexState.queue)}`);
             if (p.indexState)
-                console.log(`    watcher=${(_a = p.indexState.watcherMode) !== null && _a !== void 0 ? _a : "unknown"} overflows=${(_b = p.indexState.overflowCount) !== null && _b !== void 0 ? _b : 0} lastReconciled=${p.indexState.lastReconciledAt ? new Date(p.indexState.lastReconciledAt).toISOString() : "unknown"} catchupMs=${(_c = p.indexState.catchupMs) !== null && _c !== void 0 ? _c : "unknown"}`);
+                console.log(`    watcher=${(_b = p.indexState.watcherMode) !== null && _b !== void 0 ? _b : "unknown"} overflows=${(_c = p.indexState.overflowCount) !== null && _c !== void 0 ? _c : 0} lastReconciled=${p.indexState.lastReconciledAt ? new Date(p.indexState.lastReconciledAt).toISOString() : "unknown"} catchupMs=${(_d = p.indexState.catchupMs) !== null && _d !== void 0 ? _d : "unknown"}`);
         }
         if (projects.length === 0) {
             console.log("  (no projects)");

package/dist/lib/daemon/daemon.js

@@ -980,13 +980,14 @@ class Daemon {
      * on every search to annotate partial-result responses (Phase 6).
      */
     indexState(root) {
-        var _a, _b, _c, _d;
-        var _e, _f, _g, _h, _j;
+        var _a;
+        var _b, _c, _d, _e;
         const processor = this.processors.get(root);
-        const batchPending = (_e = (_a = processor === null || processor === void 0 ? void 0 : processor.progress) === null || _a === void 0 ? void 0 : _a.pendingFiles) !== null && _e !== void 0 ? _e : 0;
-        const processing = (_f = (_b = processor === null || processor === void 0 ? void 0 : processor.progress) === null || _b === void 0 ? void 0 : _b.processing) !== null && _f !== void 0 ? _f : false;
+        const progress = processor === null || processor === void 0 ? void 0 : processor.progress;
+        const batchPending = (_b = progress === null || progress === void 0 ? void 0 : progress.pendingFiles) !== null && _b !== void 0 ? _b : 0;
+        const processing = (_c = progress === null || progress === void 0 ? void 0 : progress.processing) !== null && _c !== void 0 ? _c : false;
         // status === "pending" means the initial full index hasn't completed.
-        const initialPending = ((_c = (0, project_registry_1.getProject)(root)) === null || _c === void 0 ? void 0 : _c.status) === "pending";
+        const initialPending = ((_a = (0, project_registry_1.getProject)(root)) === null || _a === void 0 ? void 0 : _a.status) === "pending";
         // A full index (--reset / initial) bypasses the batch processor; its
         // onProgress feeds indexProgress, giving a real remaining count.
         const fullIdx = this.indexProgress.get(root);
@@ -998,7 +999,7 @@ class Daemon {
         // index genuinely has work outstanding; a post-FSEvents-drop catchup mostly
         // re-verifies unchanged files. Only claim "verifying" with a real sample and
         // no initial-index work pending.
-        const { recentFiles, recentReindexed } = (_g = processor === null || processor === void 0 ? void 0 : processor.progress) !== null && _g !== void 0 ? _g : {
+        const { recentFiles, recentReindexed } = progress !== null && progress !== void 0 ? progress : {
             recentFiles: 0,
             recentReindexed: 0,
         };
@@ -1008,8 +1009,10 @@ class Daemon {
             recentReindexed === 0 &&
             pendingFiles > 0;
         const health = this.watcherManager.health(root);
-        return Object.assign(Object.assign({ indexing: this.pausedReason == null &&
-                (!!fullIdx || processing || batchPending > 0 || initialPending), pendingFiles: this.pausedReason == null ? pendingFiles : 0, verifying: this.pausedReason == null && verifying }, health), { failedFiles: Math.max((_h = (_d = processor === null || processor === void 0 ? void 0 : processor.progress) === null || _d === void 0 ? void 0 : _d.failedFiles) !== null && _h !== void 0 ? _h : 0, (_j = health.failedFiles) !== null && _j !== void 0 ? _j : 0) });
+        return Object.assign(Object.assign(Object.assign({ indexing: this.pausedReason == null &&
+                (!!fullIdx || processing || batchPending > 0 || initialPending), pendingFiles: this.pausedReason == null ? pendingFiles : 0, verifying: this.pausedReason == null && verifying }, health), (this.pausedReason == null && (progress === null || progress === void 0 ? void 0 : progress.queue)
+            ? { queue: progress.queue }
+            : {})), { failedFiles: Math.max((_d = progress === null || progress === void 0 ? void 0 : progress.failedFiles) !== null && _d !== void 0 ? _d : 0, (_e = health.failedFiles) !== null && _e !== void 0 ? _e : 0) });
     }
     search(payload, signal) {
         return __awaiter(this, void 0, void 0, function* () {

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

@@ -606,6 +606,7 @@ class WatcherManager {
                         else if (reconciliation.action === "reprocess") {
                             processor.handleFileEvent("change", absPath, {
                                 forceReprocess: true,
+                                workKind: "catchup",
                             });
                             queued++;
                             if (queued % 500 === 0) {
@@ -623,7 +624,9 @@ class WatcherManager {
                                 });
                                 if (snapshot.size !== stats.size ||
                                     snapshot.mtimeMs !== stats.mtimeMs) {
-                                    processor.handleFileEvent("change", absPath);
+                                    processor.handleFileEvent("change", absPath, {
+                                        workKind: "catchup",
+                                    });
                                     continue;
                                 }
                                 const hash = (0, file_utils_1.computeContentHash)(snapshot.buffer, absPath);
@@ -643,7 +646,7 @@ class WatcherManager {
                             }
                             if (signal.aborted)
                                 return false;
-                            processor.handleFileEvent("change", absPath);
+                            processor.handleFileEvent("change", absPath, { workKind: "catchup" });
                             queued++;
                             // Throttle: pause periodically during large catchup scans to let the
                             // batch processor drain and compaction run between bursts.
@@ -677,7 +680,10 @@ class WatcherManager {
                     return false;
                 if (!seenPaths.has(cachedPath) &&
                     !(0, walker_1.isPathProtectedByWalkState)(cachedPath, walkState)) {
-                    processor.handleFileEvent("unlink", cachedPath, { forceDelete: true });
+                    processor.handleFileEvent("unlink", cachedPath, {
+                        forceDelete: true,
+                        workKind: "cleanup",
+                    });
                     purged++;
                 }
             }

package/dist/lib/index/batch-processor.js

@@ -58,6 +58,10 @@ const watcher_batch_1 = require("./watcher-batch");
 const DEBOUNCE_MS = 2000;
 const MAX_RETRIES = 5;
 const MAX_BATCH_SIZE = 50;
+const MAX_CATCHUP_BATCH_SIZE = 4;
+const BACKGROUND_DISPATCH_WINDOW_MS = 2000;
+const MAX_CONSECUTIVE_LIVE_BATCHES = 3;
+const WORK_PRIORITY = { live: 0, catchup: 1, cleanup: 2 };
 // Pool priority cannot preempt an active processFile, so keep one worker free
 // for latency-sensitive encodeQuery/rerank work during indexing bursts.
 const DEFAULT_BATCH_CONCURRENCY = Math.max(1, config_1.CONFIG.WORKER_THREADS - 1);
@@ -70,6 +74,10 @@ class ProjectBatchProcessor {
     constructor(opts) {
         var _a, _b, _c;
         this.pending = new Map();
+        this.pendingWork = new Map();
+        this.activeWork = new Map();
+        this.liveBatches = 0;
+        this.nextBackground = "catchup";
         this.retryCount = new Map();
         this.retryAt = new Map();
         this.terminalFailures = new Set();
@@ -110,6 +118,7 @@ class ProjectBatchProcessor {
     }
     handleFileEvent(event, absPath, options) {
         var _a, _b;
+        var _c;
         if (this.closed)
             return;
         const normalize = this.filePolicy.normalizeEventPath;
@@ -149,10 +158,35 @@ class ProjectBatchProcessor {
             this.forcedReprocess.set(normalized, ++this.forceGeneration);
         }
         this.retryAt.delete(normalized);
-        this.pending.set(normalized, event);
+        this.enqueueWork(normalized, event, {
+            kind: (_c = options === null || options === void 0 ? void 0 : options.workKind) !== null && _c !== void 0 ? _c : "live",
+            queuedAt: Date.now(),
+        });
         (_b = this.onActivity) === null || _b === void 0 ? void 0 : _b.call(this);
         this.scheduleBatch();
     }
+    enqueueWork(absPath, event, work) {
+        var _a;
+        const previous = (_a = this.pendingWork.get(absPath)) !== null && _a !== void 0 ? _a : this.activeWork.get(absPath);
+        this.pending.set(absPath, event);
+        this.pendingWork.set(absPath, !previous || WORK_PRIORITY[work.kind] < WORK_PRIORITY[previous.kind]
+            ? work
+            : {
+                kind: previous.kind,
+                queuedAt: previous.kind === work.kind
+                    ? Math.min(previous.queuedAt, work.queuedAt)
+                    : previous.queuedAt,
+            });
+    }
+    hasReadyLiveWork() {
+        var _a;
+        const now = Date.now();
+        for (const [file, work] of this.pendingWork) {
+            if (work.kind === "live" && ((_a = this.retryAt.get(file)) !== null && _a !== void 0 ? _a : 0) <= now)
+                return true;
+        }
+        return false;
+    }
     /** Live (re)index progress: files queued + whether a batch is running.
      *
      *  recentFiles/recentReindexed summarize the last few batches so callers can
@@ -162,18 +196,40 @@ class ProjectBatchProcessor {
      *  not pending work. Without this, a large pendingFiles alone reads as "the
      *  index is far behind" and search callers caveat correct results. */
     get progress() {
+        var _a;
         let recentFiles = 0;
         let recentReindexed = 0;
         for (const b of this.recentBatches) {
             recentFiles += b.files;
             recentReindexed += b.reindexed;
         }
+        const queue = {
+            live: 0,
+            catchup: 0,
+            cleanup: 0,
+            activeFiles: this.activeWork.size,
+            oldestLiveEditAgeMs: null,
+        };
+        let oldest = Number.POSITIVE_INFINITY;
+        for (const file of this.pending.keys()) {
+            const work = this.pendingWork.get(file);
+            queue[(_a = work === null || work === void 0 ? void 0 : work.kind) !== null && _a !== void 0 ? _a : "live"]++;
+            if ((work === null || work === void 0 ? void 0 : work.kind) === "live")
+                oldest = Math.min(oldest, work.queuedAt);
+        }
+        for (const work of this.activeWork.values()) {
+            if (work.kind === "live")
+                oldest = Math.min(oldest, work.queuedAt);
+        }
+        if (Number.isFinite(oldest))
+            queue.oldestLiveEditAgeMs = Math.max(0, Date.now() - oldest);
         return {
             pendingFiles: this.pending.size,
             processing: this.processing,
             failedFiles: this.terminalFailures.size,
             recentFiles,
             recentReindexed,
+            queue,
         };
     }
     loadReusableEmbeddings(absPath) {
@@ -253,8 +309,8 @@ class ProjectBatchProcessor {
     }
     processBatch(operationSignal) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d;
-            var _e, _f;
+            var _a, _b, _c, _d, _e;
+            var _f, _g, _h, _j;
             if (this.closed || this.processing || this.pending.size === 0)
                 return;
             const diskPressure = this.vectorDb.checkDiskPressure();
@@ -263,25 +319,55 @@ class ProjectBatchProcessor {
             }
             const batch = new Map();
             const batchForceGenerations = new Map();
+            const batchWork = new Map();
             const now = Date.now();
-            let taken = 0;
-            for (const [absPath, event] of this.pending) {
-                if (((_e = this.retryAt.get(absPath)) !== null && _e !== void 0 ? _e : 0) > now)
+            const ready = {
+                live: [],
+                catchup: [],
+                cleanup: [],
+            };
+            for (const absPath of this.pending.keys()) {
+                if (((_f = this.retryAt.get(absPath)) !== null && _f !== void 0 ? _f : 0) > now)
                     continue;
+                const kind = (_g = (_a = this.pendingWork.get(absPath)) === null || _a === void 0 ? void 0 : _a.kind) !== null && _g !== void 0 ? _g : "live";
+                if (ready[kind].length < MAX_BATCH_SIZE)
+                    ready[kind].push(absPath);
+            }
+            const background = ready[this.nextBackground].length
+                ? this.nextBackground
+                : this.nextBackground === "catchup"
+                    ? "cleanup"
+                    : "catchup";
+            const fairBackground = ready.live.length > 0 &&
+                ready[background].length > 0 &&
+                this.liveBatches >= MAX_CONSECUTIVE_LIVE_BATCHES;
+            const kind = ready.live.length > 0 && !fairBackground ? "live" : background;
+            const limit = fairBackground
+                ? 1
+                : kind === "catchup"
+                    ? MAX_CATCHUP_BATCH_SIZE
+                    : MAX_BATCH_SIZE;
+            for (const absPath of ready[kind].slice(0, limit)) {
+                const event = this.pending.get(absPath);
                 batch.set(absPath, event);
+                batchWork.set(absPath, (_h = this.pendingWork.get(absPath)) !== null && _h !== void 0 ? _h : { kind, queuedAt: now });
                 const forceGeneration = this.forcedReprocess.get(absPath);
                 if (forceGeneration !== undefined) {
                     batchForceGenerations.set(absPath, forceGeneration);
                 }
-                taken++;
-                if (taken >= MAX_BATCH_SIZE)
-                    break;
             }
             if (batch.size === 0) {
                 this.schedulePendingBatch(30000);
                 return;
             }
             this.processing = true;
+            this.activeWork = batchWork;
+            if (kind === "live")
+                this.liveBatches++;
+            else {
+                this.liveBatches = 0;
+                this.nextBackground = kind === "catchup" ? "cleanup" : "catchup";
+            }
             const batchAc = new AbortController();
             const abortBatch = () => batchAc.abort(operationSignal.reason);
             if (operationSignal.aborted)
@@ -295,6 +381,7 @@ class ProjectBatchProcessor {
             }, this.batchTimeoutMs);
             for (const key of batch.keys()) {
                 this.pending.delete(key);
+                this.pendingWork.delete(key);
                 this.retryAt.delete(key);
             }
             const filenames = [...batch.keys()].map((p) => path.basename(p));
@@ -331,7 +418,7 @@ class ProjectBatchProcessor {
                         this.retryCount.set(absPath, retry.failures);
                         this.retryAt.set(absPath, Date.now() + retry.backoffMs);
                     }
-                    this.pending.set(absPath, event);
+                    this.enqueueWork(absPath, event, batchWork.get(absPath));
                 };
                 let stopDispatch = false;
                 const processOne = (absPath, event) => __awaiter(this, void 0, void 0, function* () {
@@ -473,7 +560,7 @@ class ProjectBatchProcessor {
                         }
                     }
                 });
-                const batchConcurrency = Math.min(this.concurrency, Math.max(1, Math.ceil(batch.size / FILES_PER_BATCH_SLOT)));
+                const batchConcurrency = Math.min(kind === "live" ? this.concurrency : 1, Math.max(1, Math.ceil(batch.size / FILES_PER_BATCH_SLOT)));
                 const activeTasks = [];
                 const schedule = (task) => __awaiter(this, void 0, void 0, function* () {
                     const taskPromise = task();
@@ -491,6 +578,14 @@ class ProjectBatchProcessor {
                 for (const [absPath, event] of batch) {
                     if (batchAc.signal.aborted || stopDispatch)
                         break;
+                    // Do not enqueue a whole background batch into the worker pool. Finish
+                    // the current file, commit its results, then admit waiting live edits.
+                    // A single fairness file still runs during continuous live traffic.
+                    if (kind !== "live" &&
+                        settled > 0 &&
+                        (Date.now() - start >= BACKGROUND_DISPATCH_WINDOW_MS ||
+                            (!fairBackground && this.hasReadyLiveWork())))
+                        break;
                     yield schedule(() => processOne(absPath, event));
                 }
                 yield Promise.allSettled(activeTasks);
@@ -561,9 +656,9 @@ class ProjectBatchProcessor {
                 }
                 const duration = Date.now() - start;
                 if (reindexed > 0) {
-                    (_a = this.onReindex) === null || _a === void 0 ? void 0 : _a.call(this, reindexed, duration);
+                    (_b = this.onReindex) === null || _b === void 0 ? void 0 : _b.call(this, reindexed, duration);
                 }
-                this.recentBatches.push({ files: batch.size, reindexed });
+                this.recentBatches.push({ files: settled, reindexed });
                 if (this.recentBatches.length > ProjectBatchProcessor.RECENT_BATCH_WINDOW) {
                     this.recentBatches.shift();
                 }
@@ -578,7 +673,7 @@ class ProjectBatchProcessor {
                     this.retryCount.delete(absPath);
                     this.retryAt.delete(absPath);
                     this.terminalFailures.delete(absPath);
-                    (_b = this.onPathSuccess) === null || _b === void 0 ? void 0 : _b.call(this, absPath);
+                    (_c = this.onPathSuccess) === null || _c === void 0 ? void 0 : _c.call(this, absPath);
                 }
                 // Trigger compaction if fragments are accumulating
                 if (reindexed > 0 && diskPressure !== "critical") {
@@ -599,7 +694,7 @@ class ProjectBatchProcessor {
                         if (this.terminalFailures.has(absPath))
                             continue;
                         if (!this.pending.has(absPath)) {
-                            this.pending.set(absPath, event);
+                            this.enqueueWork(absPath, event, batchWork.get(absPath));
                         }
                     }
                     (0, logger_1.log)(this.wtag, "Disk pressure — requeued batch, will retry in 60s");
@@ -622,7 +717,7 @@ class ProjectBatchProcessor {
                         if (this.terminalFailures.has(absPath))
                             continue;
                         if (!this.pending.has(absPath))
-                            this.pending.set(absPath, event);
+                            this.enqueueWork(absPath, event, batchWork.get(absPath));
                     }
                     backoffOverrideMs = 30 * 60 * 1000;
                 }
@@ -635,19 +730,19 @@ class ProjectBatchProcessor {
                             continue;
                         if (this.pending.has(absPath))
                             continue;
-                        const retry = (0, watcher_batch_1.computePathRetry)((_f = this.retryCount.get(absPath)) !== null && _f !== void 0 ? _f : 0, MAX_RETRIES, DEBOUNCE_MS);
+                        const retry = (0, watcher_batch_1.computePathRetry)((_j = this.retryCount.get(absPath)) !== null && _j !== void 0 ? _j : 0, MAX_RETRIES, DEBOUNCE_MS);
                         if (!retry.retry) {
                             this.retryCount.delete(absPath);
                             this.retryAt.delete(absPath);
                             this.terminalFailures.add(absPath);
-                            (_c = this.onTerminalFailure) === null || _c === void 0 ? void 0 : _c.call(this, absPath);
+                            (_d = this.onTerminalFailure) === null || _d === void 0 ? void 0 : _d.call(this, absPath);
                             dropped++;
                             droppedPaths.push(absPath);
                             continue;
                         }
                         this.retryCount.set(absPath, retry.failures);
                         this.retryAt.set(absPath, Date.now() + retry.backoffMs);
-                        this.pending.set(absPath, event);
+                        this.enqueueWork(absPath, event, batchWork.get(absPath));
                     }
                     if (dropped > 0) {
                         (0, logger_1.log)(this.wtag, `Dropped ${dropped} file(s) after ${MAX_RETRIES} retries: ${droppedPaths.map((p) => path.basename(p)).join(", ")}`);
@@ -666,10 +761,11 @@ class ProjectBatchProcessor {
                         if (!this.pending.has(absPath)) {
                             this.retryCount.delete(absPath);
                             this.retryAt.delete(absPath);
-                            this.pending.set(absPath, "change");
+                            this.enqueueWork(absPath, "change", batchWork.get(absPath));
                         }
                     }
                 }
+                this.activeWork = new Map();
                 if (!this.closed && this.pending.size > 0) {
                     if (backoffOverrideMs > 0) {
                         if (this.debounceTimer)
@@ -686,7 +782,7 @@ class ProjectBatchProcessor {
                     }
                 }
                 if (!this.closed)
-                    (_d = this.onBatchSettled) === null || _d === void 0 ? void 0 : _d.call(this);
+                    (_e = this.onBatchSettled) === null || _e === void 0 ? void 0 : _e.call(this);
             }
         });
     }

package/dist/lib/index/watcher.js

@@ -210,6 +210,7 @@ function startWatcher(opts) {
                             }
                             processor.handleFileEvent("change", absolute, {
                                 forceReprocess: reconciliation.action === "reprocess",
+                                workKind: "catchup",
                             });
                         }
                     }
@@ -227,6 +228,7 @@ function startWatcher(opts) {
                             !(0, walker_1.isPathProtectedByWalkState)(cachedPath, state)) {
                             processor.handleFileEvent("unlink", cachedPath, {
                                 forceDelete: true,
+                                workKind: "cleanup",
                             });
                         }
                     }

package/dist/lib/output/index-state-footer.js

@@ -6,7 +6,14 @@
 // historically did not. This formats a single machine-readable footer so an
 // agent can decide to caveat its answer or retry once indexing settles.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatWatchQueue = formatWatchQueue;
 exports.formatIndexStateFooter = formatIndexStateFooter;
+function formatWatchQueue(queue) {
+    const age = queue.oldestLiveEditAgeMs === null
+        ? "none"
+        : `${Math.ceil(queue.oldestLiveEditAgeMs / 1000)}s`;
+    return `live=${queue.live} catchup=${queue.catchup} cleanup=${queue.cleanup} active=${queue.activeFiles} oldestLiveEdit=${age}`;
+}
 /**
  * One-line footer describing an in-progress index, or null when there's
  * nothing to say (no state, or the index is settled). Suppressing the

package/dist/lib/output/mcp-results.js

@@ -111,6 +111,15 @@ exports.MCP_READ_OUTPUT_SCHEMAS = {
                 .object({
                 indexing: zod_1.z.boolean(),
                 pendingFiles: zod_1.z.number(),
+                queue: zod_1.z
+                    .object({
+                    live: zod_1.z.number().int().nonnegative(),
+                    catchup: zod_1.z.number().int().nonnegative(),
+                    cleanup: zod_1.z.number().int().nonnegative(),
+                    activeFiles: zod_1.z.number().int().nonnegative(),
+                    oldestLiveEditAgeMs: zod_1.z.number().nonnegative().nullable(),
+                })
+                    .optional(),
                 verifying: zod_1.z.boolean().optional(),
                 failedFiles: zod_1.z.number().optional(),
                 degraded: zod_1.z.boolean().optional(),

package/package.json

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