grepmax 0.26.73 → 0.26.75

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

package/README.md

@@ -528,7 +528,7 @@ The package includes a separate prune-only helper with pinned Lance 12 dependenc
 
 `gmax recover --table /path/to/lancedb/chunks.lance --json` reads the durable recovery receipt without starting a daemon or preparing Python. `--check` samples admission without pruning. `--prune --version <current-version> --cutoff <absolute-ISO-timestamp>` explicitly requests one offline prune. A prior uncertain attempt requires `--acknowledge-uncertain <attempt-id>` after inspection. Recovery never creates/clears quarantine, stops other owners, retries automatically or enables rewriting.
 
-Production recovery currently requires macOS, a persistent `autostart-disabled` file in the selected store home, and closed store owners. Recovery alone uses known healthy memory/kernel pressure, measured physical headroom and the shared aggregate resource budget; normal development retains its configured guard policy. The helper reserves 512 MiB of admission capacity; this is not an OS-enforced footprint cap. Recovery samples have an eight-second total ceiling, including the established five-second kernel probe allowance, with fresh sampling at deletion admission and five-second heartbeat scheduling. Unknown, stale, warning or critical measurements refuse/interrupt recovery. Pruning needs at least 1 MiB of measured metadata disk headroom, not full-table rewrite space. Initial wheel setup requires 512 MiB; an existing environment is checked against the lock offline without that download-space requirement.
+Production recovery currently requires macOS, a persistent `autostart-disabled` file in the selected store home, and closed store owners. Recovery alone uses known healthy memory/kernel pressure and the shared aggregate resource budget; normal development retains its configured guard policy. Immediately free RAM is measured for diagnostics but has no fixed minimum: macOS can reclaim cached memory, so a low free-page count alone must not prevent cleanup. The helper reserves 512 MiB of admission capacity; this is not an OS-enforced footprint cap. Recovery samples have an eight-second total ceiling, including the established five-second kernel probe allowance, with fresh sampling at deletion admission and five-second heartbeat scheduling. Unknown, stale, warning or critical measurements refuse/interrupt recovery. Pruning needs at least 1 MiB of measured metadata disk headroom, not full-table rewrite space. Initial wheel setup requires 512 MiB; an existing environment is checked against the lock offline without that download-space requirement.
 
 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.
 

package/dist/commands/watch.js

@@ -365,9 +365,10 @@ exports.watch = new commander_1.Command("watch")
         },
     });
     console.log(`[watch:${projectName}] File watcher active`);
+    (0, watcher_store_1.heartbeat)(process.pid, watcher.health);
     // Heartbeat — update LMDB every 60s so other processes can detect liveliness
     const heartbeatInterval = setInterval(() => {
-        (0, watcher_store_1.heartbeat)(process.pid);
+        (0, watcher_store_1.heartbeat)(process.pid, watcher.health);
     }, IDLE_CHECK_INTERVAL_MS);
     // Idle timeout
     let lastActivity = Date.now();
@@ -401,8 +402,8 @@ exports.watch
     .command("status")
     .description("Show running watchers")
     .action(() => __awaiter(void 0, void 0, void 0, function* () {
-    var _a;
-    var _b, _c, _d;
+    var _a, _b, _c, _d;
+    var _e, _f, _g;
     const { sendDaemonCommand } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-client")));
     const resp = yield sendDaemonCommand({ cmd: "status" });
     if (resp.ok) {
@@ -421,7 +422,10 @@ exports.watch
             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=${(_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"}`);
+                console.log(`    watcher=${(_e = p.indexState.watcherMode) !== null && _e !== void 0 ? _e : "unknown"} overflows=${(_f = p.indexState.overflowCount) !== null && _f !== void 0 ? _f : 0} lastReconciled=${p.indexState.lastReconciledAt ? new Date(p.indexState.lastReconciledAt).toISOString() : "unknown"} catchupMs=${(_g = p.indexState.catchupMs) !== null && _g !== void 0 ? _g : "unknown"}`);
+            const recovery = (0, index_state_footer_1.formatWatcherRecovery)((_b = p.indexState) === null || _b === void 0 ? void 0 : _b.watcherRecovery);
+            if (recovery)
+                console.log(`    recovery: ${recovery}`);
         }
         if (projects.length === 0) {
             console.log("  (no projects)");
@@ -434,6 +438,13 @@ exports.watch
         for (const w of watchers) {
             const age = Math.floor((Date.now() - w.startTime) / 60000);
             console.log(`  - PID: ${w.pid} | Root: ${w.projectRoot} | Running: ${age}m`);
+            const recovery = (0, index_state_footer_1.formatWatcherRecovery)((_c = w.indexState) === null || _c === void 0 ? void 0 : _c.watcherRecovery);
+            if (recovery) {
+                console.log(`    health sample: ${w.indexStateAt ? new Date(w.indexStateAt).toISOString() : "unknown"}`);
+                console.log(`    recovery: ${recovery}`);
+                if ((_d = w.indexState) === null || _d === void 0 ? void 0 : _d.queue)
+                    console.log(`    queue: ${(0, index_state_footer_1.formatWatchQueue)(w.indexState.queue)}`);
+            }
         }
     }
     if (!resp.ok && watchers.length === 0) {

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

@@ -58,6 +58,7 @@ const walker_1 = require("../index/walker");
 const watcher_1 = require("../index/watcher");
 const watcher_errors_1 = require("../index/watcher-errors");
 const watcher_ignore_1 = require("../index/watcher-ignore");
+const watcher_recovery_1 = require("../index/watcher-recovery");
 const file_utils_1 = require("../utils/file-utils");
 const logger_1 = require("../utils/logger");
 const project_registry_1 = require("../utils/project-registry");
@@ -97,6 +98,14 @@ function abortableDelay(ms, signal) {
  * thin watchProject/unwatchProject delegators over this manager.
  */
 class WatcherManager {
+    recovery(root) {
+        let tracker = this.recoveryStates.get(root);
+        if (!tracker) {
+            tracker = new watcher_recovery_1.WatcherRecoveryTracker();
+            this.recoveryStates.set(root, tracker);
+        }
+        return tracker;
+    }
     constructor(deps) {
         this.deps = deps;
         this.pendingOps = new Set();
@@ -117,14 +126,15 @@ class WatcherManager {
         this.degradedRoots = new Set();
         this.terminalFailures = new Map();
         this.watchLifecycles = new Map();
+        this.recoveryStates = new Map();
         this.subscriptionUpdates = new Map();
         this.watcherGenerations = new Map();
     }
     health(root) {
-        var _a;
-        var _b, _c;
+        var _a, _b;
+        var _c, _d;
         return {
-            failedFiles: (_b = (_a = this.terminalFailures.get(root)) === null || _a === void 0 ? void 0 : _a.size) !== null && _b !== void 0 ? _b : 0,
+            failedFiles: (_c = (_a = this.terminalFailures.get(root)) === null || _a === void 0 ? void 0 : _a.size) !== null && _c !== void 0 ? _c : 0,
             degraded: this.isRootDegraded(root),
             watcherMode: this.pollIntervals.has(root)
                 ? "polling"
@@ -135,8 +145,9 @@ class WatcherManager {
                     : "native",
             catchupRunning: this.catchups.has(root),
             lastReconciledAt: this.reconciledAt.get(root),
-            overflowCount: (_c = this.overflowCounts.get(root)) !== null && _c !== void 0 ? _c : 0,
+            overflowCount: (_d = this.overflowCounts.get(root)) !== null && _d !== void 0 ? _d : 0,
             catchupMs: this.catchupDurations.get(root),
+            watcherRecovery: (_b = this.recoveryStates.get(root)) === null || _b === void 0 ? void 0 : _b.snapshot(),
         };
     }
     watchProject(root_1) {
@@ -325,8 +336,9 @@ class WatcherManager {
                 }
                 catch (_c) { }
                 this.deps.subscriptions.delete(root);
+                this.recovery(root).detached();
             }
-            const { subscription: sub } = yield (0, watcher_ignore_1.subscribeWithNativeExclusions)(root, (err, events) => {
+            const { subscription: sub, policy } = yield (0, watcher_ignore_1.subscribeWithNativeExclusions)(root, (err, events) => {
                 var _a, _b;
                 var _c, _d;
                 if (this.deps.processors.get(root) !== processor ||
@@ -334,6 +346,7 @@ class WatcherManager {
                     ((_b = (_a = this.deps).getShuttingDown) === null || _b === void 0 ? void 0 : _b.call(_a)))
                     return;
                 if (err) {
+                    this.recovery(root).error(err);
                     this.overflowCounts.set(root, ((_c = this.overflowCounts.get(root)) !== null && _c !== void 0 ? _c : 0) + 1);
                     const now = Date.now();
                     if (!this.lastWatcherErrorLogMs.has(root) ||
@@ -366,6 +379,7 @@ class WatcherManager {
                 return;
             }
             this.deps.subscriptions.set(root, sub);
+            this.recovery(root).attached(policy);
         });
     }
     requestOverflowCatchup(root, processor) {
@@ -409,6 +423,7 @@ class WatcherManager {
             if (sub) {
                 sub.unsubscribe().catch(() => { });
                 this.deps.subscriptions.delete(root);
+                this.recovery(root).detached();
             }
             if (!this.pollIntervals.has(root)) {
                 console.error(`[daemon:${name}] Native watcher failed after ${fails} terminal errors — switching to poll mode (${POLL_INTERVAL_MS / 60000}min interval)`);
@@ -583,186 +598,199 @@ class WatcherManager {
             var _a, e_1, _b, _c;
             var _d;
             var _e, _f, _g;
-            const scanStart = Date.now();
-            const overflowCountAtStart = (_e = this.overflowCounts.get(root)) !== null && _e !== void 0 ? _e : 0;
-            const { isFileCached } = yield Promise.resolve().then(() => __importStar(require("../utils/cache-check")));
-            const metaCache = this.deps.getMetaCache();
-            const vectorDb = this.deps.getVectorDb();
-            processor.filePolicy.invalidateIgnoreCache();
-            const rootPrefix = root.endsWith("/") ? root : `${root}/`;
-            const cachedPaths = yield metaCache.getKeysWithPrefix(rootPrefix);
-            const vectorPaths = yield vectorDb.getDistinctPathsForPrefix(rootPrefix);
-            const knownPaths = new Set([...cachedPaths, ...vectorPaths]);
-            if (signal.aborted)
-                return false;
-            const seenPaths = new Set();
-            const walkState = (0, walker_1.createWalkState)();
-            let queued = 0;
-            let skipped = 0;
-            let debugSamples = 0;
+            const tracker = this.recovery(root);
+            const scan = tracker.beginScan();
+            let outcome = "failed";
             try {
-                for (var _h = true, _j = __asyncValues((0, walker_1.walk)(root, {
-                    policy: processor.filePolicy,
-                    state: walkState,
-                })), _k; _k = yield _j.next(), _a = _k.done, !_a; _h = true) {
-                    _c = _k.value;
-                    _h = false;
-                    const relPath = _c;
-                    if (signal.aborted)
-                        return false;
-                    const absPath = path.join(root, relPath);
-                    try {
-                        const classification = yield processor.filePolicy.classifyFile(absPath);
-                        if (classification.status === "error") {
-                            walkState.protectedPaths.add(classification.protectedPath);
-                            walkState.errors.push({
-                                path: classification.protectedPath,
-                                error: classification.error,
-                            });
-                            continue;
-                        }
-                        if (classification.status !== "indexable")
-                            continue;
-                        const stats = classification.stat;
-                        seenPaths.add(absPath);
-                        let cached = metaCache.get(absPath);
-                        const reconciliation = (0, cache_coherence_1.reconcileMetaEntry)(absPath, cached, vectorPaths.has(absPath));
-                        if (reconciliation.action === "stamp") {
-                            cached = reconciliation.entry;
-                            metaCache.put(absPath, cached);
-                        }
-                        else if (reconciliation.action === "reprocess") {
-                            processor.handleFileEvent("change", absPath, {
-                                forceReprocess: true,
-                                workKind: "catchup",
-                            });
-                            queued++;
-                            if (queued % 500 === 0) {
-                                (0, logger_1.debug)("catchup", `${path.basename(root)}: throttle pause at ${queued} queued`);
-                                yield abortableDelay(5000, signal);
+                const scanStart = Date.now();
+                const overflowCountAtStart = (_e = this.overflowCounts.get(root)) !== null && _e !== void 0 ? _e : 0;
+                const { isFileCached } = yield Promise.resolve().then(() => __importStar(require("../utils/cache-check")));
+                const metaCache = this.deps.getMetaCache();
+                const vectorDb = this.deps.getVectorDb();
+                processor.filePolicy.invalidateIgnoreCache();
+                const rootPrefix = root.endsWith("/") ? root : `${root}/`;
+                const cachedPaths = yield metaCache.getKeysWithPrefix(rootPrefix);
+                const vectorPaths = yield vectorDb.getDistinctPathsForPrefix(rootPrefix);
+                const knownPaths = new Set([...cachedPaths, ...vectorPaths]);
+                if (signal.aborted)
+                    return false;
+                const seenPaths = new Set();
+                const walkState = (0, walker_1.createWalkState)();
+                let queued = 0;
+                let skipped = 0;
+                let debugSamples = 0;
+                try {
+                    for (var _h = true, _j = __asyncValues((0, walker_1.walk)(root, {
+                        policy: processor.filePolicy,
+                        state: walkState,
+                    })), _k; _k = yield _j.next(), _a = _k.done, !_a; _h = true) {
+                        _c = _k.value;
+                        _h = false;
+                        const relPath = _c;
+                        if (signal.aborted)
+                            return false;
+                        const absPath = path.join(root, relPath);
+                        try {
+                            const classification = yield processor.filePolicy.classifyFile(absPath);
+                            if (classification.status === "error") {
+                                walkState.protectedPaths.add(classification.protectedPath);
+                                walkState.errors.push({
+                                    path: classification.protectedPath,
+                                    error: classification.error,
+                                });
+                                continue;
                             }
-                            continue;
-                        }
-                        if (!isFileCached(cached, stats)) {
-                            // 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,
+                            if (classification.status !== "indexable")
+                                continue;
+                            const stats = classification.stat;
+                            seenPaths.add(absPath);
+                            let cached = metaCache.get(absPath);
+                            const reconciliation = (0, cache_coherence_1.reconcileMetaEntry)(absPath, cached, vectorPaths.has(absPath));
+                            if (reconciliation.action === "stamp") {
+                                cached = reconciliation.entry;
+                                metaCache.put(absPath, cached);
+                            }
+                            else if (reconciliation.action === "reprocess") {
+                                processor.handleFileEvent("change", absPath, {
+                                    forceReprocess: true,
+                                    workKind: "catchup",
                                 });
-                                if (snapshot.size !== stats.size ||
-                                    snapshot.mtimeMs !== stats.mtimeMs) {
-                                    processor.handleFileEvent("change", absPath, {
-                                        workKind: "catchup",
-                                    });
-                                    continue;
+                                queued++;
+                                if (queued % 500 === 0) {
+                                    (0, logger_1.debug)("catchup", `${path.basename(root)}: throttle pause at ${queued} queued`);
+                                    yield abortableDelay(5000, signal);
                                 }
-                                const hash = (0, file_utils_1.computeContentHash)(snapshot.buffer, absPath);
-                                if (hash === observed.hash) {
-                                    // Content unchanged — update mtime in cache and skip worker
-                                    if (signal.aborted)
-                                        return false;
-                                    // 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 }));
+                                continue;
+                            }
+                            if (!isFileCached(cached, stats)) {
+                                // 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,
+                                    });
+                                    if (snapshot.size !== stats.size ||
+                                        snapshot.mtimeMs !== stats.mtimeMs) {
+                                        processor.handleFileEvent("change", absPath, {
+                                            workKind: "catchup",
+                                        });
+                                        continue;
+                                    }
+                                    const hash = (0, file_utils_1.computeContentHash)(snapshot.buffer, absPath);
+                                    if (hash === observed.hash) {
+                                        // Content unchanged — update mtime in cache and skip worker
+                                        if (signal.aborted)
+                                            return false;
+                                        // 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;
                                     }
-                                    skipped++;
-                                    continue;
+                                }
+                                // Debug: log first few misses to diagnose re-queue loops
+                                if (debugSamples < 5) {
+                                    (0, logger_1.debug)("catchup", `miss ${relPath}: cached=${cached ? `mtime=${Math.trunc(cached.mtimeMs)} size=${cached.size}` : "null"} stat=mtime=${Math.trunc(stats.mtimeMs)} size=${stats.size}`);
+                                    debugSamples++;
+                                }
+                                if (signal.aborted)
+                                    return false;
+                                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.
+                                if (queued % 500 === 0) {
+                                    (0, logger_1.debug)("catchup", `${path.basename(root)}: throttle pause at ${queued} queued`);
+                                    yield abortableDelay(5000, signal);
                                 }
                             }
-                            // Debug: log first few misses to diagnose re-queue loops
-                            if (debugSamples < 5) {
-                                (0, logger_1.debug)("catchup", `miss ${relPath}: cached=${cached ? `mtime=${Math.trunc(cached.mtimeMs)} size=${cached.size}` : "null"} stat=mtime=${Math.trunc(stats.mtimeMs)} size=${stats.size}`);
-                                debugSamples++;
-                            }
-                            if (signal.aborted)
-                                return false;
-                            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.
-                            if (queued % 500 === 0) {
-                                (0, logger_1.debug)("catchup", `${path.basename(root)}: throttle pause at ${queued} queued`);
-                                yield abortableDelay(5000, signal);
+                            else {
+                                skipped++;
                             }
                         }
-                        else {
-                            skipped++;
+                        catch (error) {
+                            walkState.protectedPaths.add(absPath);
+                            walkState.errors.push({ path: absPath, error });
                         }
                     }
-                    catch (error) {
-                        walkState.protectedPaths.add(absPath);
-                        walkState.errors.push({ path: absPath, error });
+                }
+                catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                finally {
+                    try {
+                        if (!_h && !_a && (_b = _j.return)) yield _b.call(_j);
                     }
+                    finally { if (e_1) throw e_1.error; }
                 }
-            }
-            catch (e_1_1) { e_1 = { error: e_1_1 }; }
-            finally {
-                try {
-                    if (!_h && !_a && (_b = _j.return)) yield _b.call(_j);
+                (0, logger_1.debug)("catchup", `${path.basename(root)}: ${queued} queued, ${skipped} skipped (cached ok), ${seenPaths.size} total`);
+                // Purge files deleted while daemon was offline
+                let purged = 0;
+                for (const cachedPath of knownPaths) {
+                    if (signal.aborted)
+                        return false;
+                    if (!seenPaths.has(cachedPath) &&
+                        !(0, walker_1.isPathProtectedByWalkState)(cachedPath, walkState)) {
+                        processor.handleFileEvent("unlink", cachedPath, {
+                            forceDelete: true,
+                            workKind: "cleanup",
+                        });
+                        purged++;
+                    }
                 }
-                finally { if (e_1) throw e_1.error; }
-            }
-            (0, logger_1.debug)("catchup", `${path.basename(root)}: ${queued} queued, ${skipped} skipped (cached ok), ${seenPaths.size} total`);
-            // Purge files deleted while daemon was offline
-            let purged = 0;
-            for (const cachedPath of knownPaths) {
-                if (signal.aborted)
-                    return false;
-                if (!seenPaths.has(cachedPath) &&
-                    !(0, walker_1.isPathProtectedByWalkState)(cachedPath, walkState)) {
-                    processor.handleFileEvent("unlink", cachedPath, {
-                        forceDelete: true,
-                        workKind: "cleanup",
+                const complete = walkState.rootComplete && walkState.errors.length === 0;
+                if (!complete) {
+                    this.degradedRoots.add(root);
+                    (0, watcher_store_1.registerWatcher)({
+                        pid: process.pid,
+                        projectRoot: root,
+                        startTime: Date.now(),
+                        status: "degraded",
+                        lastHeartbeat: Date.now(),
+                        lastError: `${walkState.errors.length} scan path(s) incomplete`,
                     });
-                    purged++;
                 }
+                else {
+                    this.degradedRoots.delete(root);
+                    const failedFiles = (_f = (_d = this.terminalFailures.get(root)) === null || _d === void 0 ? void 0 : _d.size) !== null && _f !== void 0 ? _f : 0;
+                    (0, watcher_store_1.registerWatcher)(Object.assign({ pid: process.pid, projectRoot: root, startTime: Date.now(), status: this.isRootDegraded(root) ? "degraded" : "watching", lastHeartbeat: Date.now() }, (failedFiles > 0
+                        ? {
+                            lastError: `${failedFiles} file(s) exhausted automatic retries`,
+                        }
+                        : {})));
+                }
+                if (queued > 0 || purged > 0) {
+                    const parts = [];
+                    if (queued > 0)
+                        parts.push(`${queued} changed`);
+                    if (purged > 0)
+                        parts.push(`${purged} deleted`);
+                    console.log(`[daemon:${path.basename(root)}] Catchup: ${parts.join(", ")} file(s) while offline`);
+                }
+                const ended = Date.now();
+                this.lastCatchupEndMs.set(root, ended);
+                this.catchupDurations.set(root, ended - scanStart);
+                if (complete) {
+                    this.reconciledAt.set(root, ended);
+                    // A later gap still needs its deferred scan, even if this walk succeeded.
+                    if (((_g = this.overflowCounts.get(root)) !== null && _g !== void 0 ? _g : 0) === overflowCountAtStart)
+                        this.overflowPendingRoots.delete(root);
+                }
+                outcome = complete ? "complete" : "incomplete";
+                return complete;
             }
-            const complete = walkState.rootComplete && walkState.errors.length === 0;
-            if (!complete) {
-                this.degradedRoots.add(root);
-                (0, watcher_store_1.registerWatcher)({
-                    pid: process.pid,
-                    projectRoot: root,
-                    startTime: Date.now(),
-                    status: "degraded",
-                    lastHeartbeat: Date.now(),
-                    lastError: `${walkState.errors.length} scan path(s) incomplete`,
-                });
-            }
-            else {
-                this.degradedRoots.delete(root);
-                const failedFiles = (_f = (_d = this.terminalFailures.get(root)) === null || _d === void 0 ? void 0 : _d.size) !== null && _f !== void 0 ? _f : 0;
-                (0, watcher_store_1.registerWatcher)(Object.assign({ pid: process.pid, projectRoot: root, startTime: Date.now(), status: this.isRootDegraded(root) ? "degraded" : "watching", lastHeartbeat: Date.now() }, (failedFiles > 0
-                    ? { lastError: `${failedFiles} file(s) exhausted automatic retries` }
-                    : {})));
-            }
-            if (queued > 0 || purged > 0) {
-                const parts = [];
-                if (queued > 0)
-                    parts.push(`${queued} changed`);
-                if (purged > 0)
-                    parts.push(`${purged} deleted`);
-                console.log(`[daemon:${path.basename(root)}] Catchup: ${parts.join(", ")} file(s) while offline`);
-            }
-            const ended = Date.now();
-            this.lastCatchupEndMs.set(root, ended);
-            this.catchupDurations.set(root, ended - scanStart);
-            if (complete) {
-                this.reconciledAt.set(root, ended);
-                // A later gap still needs its deferred scan, even if this walk succeeded.
-                if (((_g = this.overflowCounts.get(root)) !== null && _g !== void 0 ? _g : 0) === overflowCountAtStart)
-                    this.overflowPendingRoots.delete(root);
+            finally {
+                tracker.finishScan(scan, signal.aborted ? "aborted" : outcome);
             }
-            return complete;
         });
     }
     runCatchup(root, processor) {
@@ -792,9 +820,19 @@ class WatcherManager {
                 }
             } while (active.dirty && !signal.aborted);
         });
-        const run = (this.deps.runProjectOperation
-            ? this.deps.runProjectOperation(root, "watch-catchup", active.controller.signal, execute)
-            : execute(active.controller.signal)).finally(() => {
+        const tracker = this.recovery(root);
+        const scansBeforeAttempt = tracker.snapshot().scanCount;
+        const run = (() => __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield (this.deps.runProjectOperation
+                    ? this.deps.runProjectOperation(root, "watch-catchup", active.controller.signal, execute)
+                    : execute(active.controller.signal));
+            }
+            catch (error) {
+                tracker.attemptFailed(tracker.snapshot().scanCount > scansBeforeAttempt, active.controller.signal.aborted);
+                throw error;
+            }
+        }))().finally(() => {
             if (this.catchups.get(root) === active)
                 this.catchups.delete(root);
         });
@@ -855,6 +893,7 @@ class WatcherManager {
             this.overflowPendingRoots.delete(root);
             this.degradedRoots.delete(root);
             this.terminalFailures.delete(root);
+            this.recoveryStates.delete(root);
             (0, watcher_store_1.unregisterWatcherByRoot)(root);
             console.log(`[daemon] Unwatched ${root}`);
         });

package/dist/lib/index/watcher-recovery.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WatcherRecoveryTracker = void 0;
+const node_crypto_1 = require("node:crypto");
+const watcher_errors_1 = require("./watcher-errors");
+/** Fixed-size, process/lifecycle-local evidence. A completed walk covers only
+ * errors already observed when it began; queued ingestion is reported separately. */
+class WatcherRecoveryTracker {
+    constructor() {
+        this.gapCount = 0;
+        this.terminalErrorCount = 0;
+        this.coveredGapCount = 0;
+        this.coveredTerminalErrorCount = 0;
+        this.scanCount = 0;
+        this.scanIncomplete = false;
+    }
+    error(error) {
+        if ((0, watcher_errors_1.isFSEventsGap)(error)) {
+            this.gapCount++;
+            this.lastGapAt = Date.now();
+        }
+        else {
+            this.terminalErrorCount++;
+            this.lastTerminalErrorAt = Date.now();
+        }
+    }
+    beginScan() {
+        const scan = {
+            id: ++this.scanCount,
+            startedAt: Date.now(),
+            gapCountAtStart: this.gapCount,
+            terminalErrorCountAtStart: this.terminalErrorCount,
+            outcome: "running",
+        };
+        this.lastScan = scan;
+        return scan;
+    }
+    finishScan(scan, outcome) {
+        scan.finishedAt = Date.now();
+        scan.outcome = outcome;
+        if (outcome === "complete") {
+            this.scanIncomplete = false;
+            this.coveredGapCount = Math.max(this.coveredGapCount, scan.gapCountAtStart);
+            this.coveredTerminalErrorCount = Math.max(this.coveredTerminalErrorCount, scan.terminalErrorCountAtStart);
+            this.lastCompleteScan = Object.assign({}, scan);
+        }
+        else
+            this.scanIncomplete = true;
+    }
+    attemptFailed(scanStarted, aborted) {
+        this.scanIncomplete = true;
+        this.lastAttemptFailure = { at: Date.now(), scanStarted, aborted };
+    }
+    attached(policy) {
+        // The subscription helper returns the exact accepted policy, including its
+        // fallback. Summarize that value; never rediscover directories for health.
+        const patterns = JSON.parse(policy);
+        const literalCount = patterns.filter((pattern) => !pattern.startsWith("/") && !pattern.includes("*")).length;
+        this.exclusions = {
+            attached: true,
+            literalCount,
+            filterCount: patterns.length - literalCount,
+            fingerprint: (0, node_crypto_1.createHash)("sha256").update(policy).digest("hex"),
+        };
+    }
+    detached() {
+        if (this.exclusions)
+            this.exclusions.attached = false;
+    }
+    snapshot() {
+        var _a;
+        return {
+            gapCount: this.gapCount,
+            terminalErrorCount: this.terminalErrorCount,
+            coveredGapCount: this.coveredGapCount,
+            outstandingGapCount: this.gapCount - this.coveredGapCount,
+            reconciliationNeeded: this.scanIncomplete ||
+                ((_a = this.lastScan) === null || _a === void 0 ? void 0 : _a.outcome) === "running" ||
+                this.gapCount > this.coveredGapCount ||
+                this.terminalErrorCount > this.coveredTerminalErrorCount,
+            lastGapAt: this.lastGapAt,
+            lastTerminalErrorAt: this.lastTerminalErrorAt,
+            scanCount: this.scanCount,
+            lastScan: this.lastScan && Object.assign({}, this.lastScan),
+            lastCompleteScan: this.lastCompleteScan && Object.assign({}, this.lastCompleteScan),
+            lastAttemptFailure: this.lastAttemptFailure && Object.assign({}, this.lastAttemptFailure),
+            exclusions: this.exclusions && Object.assign({}, this.exclusions),
+        };
+    }
+}
+exports.WatcherRecoveryTracker = WatcherRecoveryTracker;

package/dist/lib/index/watcher.js

@@ -59,6 +59,7 @@ const ignore_patterns_1 = require("./ignore-patterns");
 const walker_1 = require("./walker");
 const watcher_errors_1 = require("./watcher-errors");
 const watcher_ignore_1 = require("./watcher-ignore");
+const watcher_recovery_1 = require("./watcher-recovery");
 // Directory names ignored at ANY depth. @parcel/watcher treats a non-glob
 // ignore entry as a literal path resolved against the watch root, so a bare
 // "dist" only covered <root>/dist — nested build dirs (packages/*/dist,
@@ -114,6 +115,7 @@ function startWatcher(opts) {
         const { projectRoot } = opts;
         const wtag = `watch:${projectRoot.split("/").pop()}`;
         const filePolicy = new file_policy_1.ProjectFilePolicy(projectRoot);
+        const recovery = new watcher_recovery_1.WatcherRecoveryTracker();
         let reconciliation = null;
         let reconcileRequested = false;
         let closing = false;
@@ -143,6 +145,7 @@ function startWatcher(opts) {
                 subscriptionFailed = false;
                 yield subscription === null || subscription === void 0 ? void 0 : subscription.unsubscribe();
                 subscription = null;
+                recovery.detached();
                 if (closing)
                     return;
                 const { subscription: next, policy: attachedPolicy } = yield (0, watcher_ignore_1.subscribeWithNativeExclusions)(projectRoot, (err, events) => {
@@ -150,6 +153,7 @@ function startWatcher(opts) {
                     if (closing || generation !== subscriptionGeneration)
                         return;
                     if (err) {
+                        recovery.error(err);
                         console.error(`[${wtag}] Watcher error:`, err);
                         scanHealthy = false;
                         (_a = opts.onHealthChange) === null || _a === void 0 ? void 0 : _a.call(opts, false, 1);
@@ -171,6 +175,7 @@ function startWatcher(opts) {
                 }
                 subscription = next;
                 subscriptionPolicy = attachedPolicy;
+                recovery.attached(attachedPolicy);
             }));
             subscriptionUpdate = update;
             return update;
@@ -199,76 +204,88 @@ function startWatcher(opts) {
                     reconcileRequested = false;
                     lastReconcileStart = Date.now();
                     const observedGapGeneration = gapGeneration;
-                    filePolicy.invalidateIgnoreCache();
-                    yield updateSubscription();
-                    if (closing)
-                        return;
-                    const rootPrefix = projectRoot.endsWith("/")
-                        ? projectRoot
-                        : `${projectRoot}/`;
-                    const cached = yield opts.metaCache.getKeysWithPrefix(rootPrefix);
-                    const vectorPaths = yield opts.vectorDb.getDistinctPathsForPrefix(rootPrefix);
-                    const knownPaths = new Set([...cached, ...vectorPaths]);
-                    const seen = new Set();
-                    const state = (0, walker_1.createWalkState)();
+                    const scan = recovery.beginScan();
+                    let outcome = "failed";
+                    let retryDelayMs = 0;
                     try {
-                        for (var _e = true, _f = (e_1 = void 0, __asyncValues((0, walker_1.walk)(projectRoot, {
-                            policy: filePolicy,
-                            state,
-                        }))), _g; _g = yield _f.next(), _a = _g.done, !_a; _e = true) {
-                            _c = _g.value;
-                            _e = false;
-                            const relative = _c;
+                        filePolicy.invalidateIgnoreCache();
+                        yield updateSubscription();
+                        if (closing)
+                            return;
+                        const rootPrefix = projectRoot.endsWith("/")
+                            ? projectRoot
+                            : `${projectRoot}/`;
+                        const cached = yield opts.metaCache.getKeysWithPrefix(rootPrefix);
+                        const vectorPaths = yield opts.vectorDb.getDistinctPathsForPrefix(rootPrefix);
+                        const knownPaths = new Set([...cached, ...vectorPaths]);
+                        const seen = new Set();
+                        const state = (0, walker_1.createWalkState)();
+                        try {
+                            for (var _e = true, _f = (e_1 = void 0, __asyncValues((0, walker_1.walk)(projectRoot, {
+                                policy: filePolicy,
+                                state,
+                            }))), _g; _g = yield _f.next(), _a = _g.done, !_a; _e = true) {
+                                _c = _g.value;
+                                _e = false;
+                                const relative = _c;
+                                if (closing)
+                                    return;
+                                const absolute = path.join(projectRoot, relative);
+                                seen.add(absolute);
+                                const reconciliation = (0, cache_coherence_1.reconcileMetaEntry)(absolute, opts.metaCache.get(absolute), vectorPaths.has(absolute));
+                                if (reconciliation.action === "stamp") {
+                                    opts.metaCache.put(absolute, reconciliation.entry);
+                                }
+                                processor.handleFileEvent("change", absolute, {
+                                    forceReprocess: reconciliation.action === "reprocess",
+                                    workKind: "catchup",
+                                });
+                            }
+                        }
+                        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                        finally {
+                            try {
+                                if (!_e && !_a && (_b = _f.return)) yield _b.call(_f);
+                            }
+                            finally { if (e_1) throw e_1.error; }
+                        }
+                        for (const cachedPath of knownPaths) {
                             if (closing)
                                 return;
-                            const absolute = path.join(projectRoot, relative);
-                            seen.add(absolute);
-                            const reconciliation = (0, cache_coherence_1.reconcileMetaEntry)(absolute, opts.metaCache.get(absolute), vectorPaths.has(absolute));
-                            if (reconciliation.action === "stamp") {
-                                opts.metaCache.put(absolute, reconciliation.entry);
+                            if (!seen.has(cachedPath) &&
+                                !(0, walker_1.isPathProtectedByWalkState)(cachedPath, state)) {
+                                processor.handleFileEvent("unlink", cachedPath, {
+                                    forceDelete: true,
+                                    workKind: "cleanup",
+                                });
                             }
-                            processor.handleFileEvent("change", absolute, {
-                                forceReprocess: reconciliation.action === "reprocess",
-                                workKind: "catchup",
-                            });
-                        }
-                    }
-                    catch (e_1_1) { e_1 = { error: e_1_1 }; }
-                    finally {
-                        try {
-                            if (!_e && !_a && (_b = _f.return)) yield _b.call(_f);
                         }
-                        finally { if (e_1) throw e_1.error; }
-                    }
-                    for (const cachedPath of knownPaths) {
-                        if (closing)
-                            return;
-                        if (!seen.has(cachedPath) &&
-                            !(0, walker_1.isPathProtectedByWalkState)(cachedPath, state)) {
-                            processor.handleFileEvent("unlink", cachedPath, {
-                                forceDelete: true,
-                                workKind: "cleanup",
-                            });
+                        if (!state.rootComplete || state.errors.length > 0) {
+                            outcome = "incomplete";
+                            scanHealthy = false;
+                            (_d = opts.onHealthChange) === null || _d === void 0 ? void 0 : _d.call(opts, false, state.errors.length);
+                            console.error(`[${wtag}] Reconciliation incomplete at ${state.errors.length} path(s)`);
+                            if (incompleteRetries < 3) {
+                                incompleteRetries++;
+                                reconcileRequested = true;
+                                retryDelayMs = 1000 * Math.pow(2, (incompleteRetries - 1));
+                            }
                         }
-                    }
-                    if (!state.rootComplete || state.errors.length > 0) {
-                        scanHealthy = false;
-                        (_d = opts.onHealthChange) === null || _d === void 0 ? void 0 : _d.call(opts, false, state.errors.length);
-                        console.error(`[${wtag}] Reconciliation incomplete at ${state.errors.length} path(s)`);
-                        if (incompleteRetries < 3) {
-                            incompleteRetries++;
-                            reconcileRequested = true;
-                            yield new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, (incompleteRetries - 1))));
+                        else {
+                            outcome = "complete";
+                            scanHealthy = observedGapGeneration === gapGeneration;
+                            if (ingestionDegraded && processor.progress.pendingFiles > 0) {
+                                degradedRepairQueued = true;
+                            }
+                            reportHealthyIfSettled();
+                            incompleteRetries = 0;
                         }
                     }
-                    else {
-                        scanHealthy = observedGapGeneration === gapGeneration;
-                        if (ingestionDegraded && processor.progress.pendingFiles > 0) {
-                            degradedRepairQueued = true;
-                        }
-                        reportHealthyIfSettled();
-                        incompleteRetries = 0;
+                    finally {
+                        recovery.finishScan(scan, closing ? "aborted" : outcome);
                     }
+                    if (retryDelayMs > 0)
+                        yield new Promise((resolve) => setTimeout(resolve, retryDelayMs));
                 } while (reconcileRequested && !closing);
             }))()
                 .catch((err) => console.error(`[${wtag}] Reconciliation failed:`, err))
@@ -313,6 +330,24 @@ function startWatcher(opts) {
         yield updateSubscription();
         reconcile();
         return {
+            get health() {
+                const progress = processor.progress;
+                const state = recovery.snapshot();
+                return {
+                    indexing: progress.processing || progress.pendingFiles > 0,
+                    pendingFiles: progress.pendingFiles,
+                    queue: progress.queue,
+                    failedFiles: Math.max(terminalFailures.size, progress.failedFiles),
+                    degraded: !scanHealthy || ingestionDegraded || terminalFailures.size > 0,
+                    watcherMode: closing
+                        ? undefined
+                        : subscriptionFailed || gapScanTimer || state.reconciliationNeeded
+                            ? "recovering"
+                            : "native",
+                    catchupRunning: reconciliation !== null,
+                    watcherRecovery: state,
+                };
+            },
             get progress() {
                 return processor.progress;
             },
@@ -322,6 +357,7 @@ function startWatcher(opts) {
                 clearTimeout(gapScanTimer);
                 yield subscriptionUpdate.catch(() => { });
                 yield subscription === null || subscription === void 0 ? void 0 : subscription.unsubscribe();
+                recovery.detached();
                 yield reconciliation;
                 yield processor.close();
             }),

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

@@ -7,6 +7,7 @@
 // agent can decide to caveat its answer or retry once indexing settles.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatWatchQueue = formatWatchQueue;
+exports.formatWatcherRecovery = formatWatcherRecovery;
 exports.formatIndexStateFooter = formatIndexStateFooter;
 function formatWatchQueue(queue) {
     const age = queue.oldestLiveEditAgeMs === null
@@ -14,6 +15,13 @@ function formatWatchQueue(queue) {
         : `${Math.ceil(queue.oldestLiveEditAgeMs / 1000)}s`;
     return `live=${queue.live} catchup=${queue.catchup} cleanup=${queue.cleanup} active=${queue.activeFiles} oldestLiveEdit=${age}`;
 }
+function formatWatcherRecovery(state) {
+    var _a, _b;
+    var _c, _d;
+    if (!state)
+        return null;
+    return `gaps=${state.gapCount} covered=${state.coveredGapCount} outstanding=${state.outstandingGapCount} terminalErrors=${state.terminalErrorCount} reconciliationNeeded=${state.reconciliationNeeded} scan=${(_c = (_a = state.lastScan) === null || _a === void 0 ? void 0 : _a.id) !== null && _c !== void 0 ? _c : "none"}/${(_d = (_b = state.lastScan) === null || _b === void 0 ? void 0 : _b.outcome) !== null && _d !== void 0 ? _d : "none"} exclusions=${state.exclusions ? `${state.exclusions.attached ? "attached" : "detached"}:${state.exclusions.literalCount}+${state.exclusions.filterCount}:${state.exclusions.fingerprint}` : "unknown"}`;
+}
 /**
  * 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/store/recovery-admission.js

@@ -65,10 +65,15 @@ function assertRecoveryAdmission(storeDir, budget) {
     const snapshot = budget.check();
     if ((snapshot === null || snapshot === void 0 ? void 0 : snapshot.platform) !== "darwin")
         throw new Error("Production recovery admission currently requires macOS host measurements");
+    // os.freemem() reports immediately free pages, not all memory macOS can
+    // reclaim. Requiring an idle 512MiB here refused cleanup on a healthy host
+    // as the file cache changed. Strict pressure/aggregate checks above and the
+    // shared 512MiB reservation below govern helper admission; free pages remain
+    // measured diagnostics, never a substitute for those checks.
     if (snapshot.physicalFreeMb === null ||
         !Number.isFinite(snapshot.physicalFreeMb) ||
-        snapshot.physicalFreeMb < resource_budget_1.HELPER_RESOURCE_RESERVE_MB)
-        throw new Error("Insufficient measured physical headroom for prune helper");
+        snapshot.physicalFreeMb < 0)
+        throw new Error("Measured physical free memory is unavailable");
     return snapshot;
 }
 function admitPrune(storeDir, budget = createRecoveryBudget()) {

package/dist/lib/utils/watcher-store.js

@@ -109,11 +109,12 @@ function updateWatcherStatus(pid, status, lastReindex, lastError) {
         }
     }
 }
-function heartbeat(pid) {
+function heartbeat(pid, indexState) {
     const db = getDb();
     for (const { key, value } of db.getRange()) {
         if (value && value.pid === pid) {
-            db.put(String(key), Object.assign(Object.assign({}, value), { lastHeartbeat: Date.now() }));
+            const now = Date.now();
+            db.put(String(key), Object.assign(Object.assign(Object.assign({}, value), { lastHeartbeat: now }), (indexState ? { indexState, indexStateAt: now } : {})));
         }
     }
 }

package/package.json

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