grepmax 0.26.63 → 0.26.65

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

package/README.md

@@ -240,7 +240,7 @@ gmax status                   # See all projects + watcher status
 
 Adding or indexing a project can start the daemon automatically. MCP acquires primary-project watch leases lazily when an index-reading tool is used; discovery and catalog listing start no background work. It shuts down after 4 hours of inactivity, and hands off to a fresh daemon after 24 hours or once its memory footprint passes 2.5 GB. File-change batches are processed on up to four worker processes by default, added only when work backs up, with one kept free for searches; full-table compaction and new FTS/ANN index builds are disabled by containment. Existing indexes remain readable. Host safety stops persist across restart and block heavy operations.
 
-`gmax watch status` reports failed files, native watcher recovery or polling, dropped-event counts, and the last complete filesystem reconciliation. 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.
+`gmax watch status` reports failed files, native watcher recovery or polling, dropped-event counts, and the last complete filesystem reconciliation. FSEvents dropped-event warnings keep the native stream attached and preserve the accompanying events. A reconciliation covers the gap; repeated warnings coalesce into one later scan, with a 30-second scan interval. Recovery stays visible until a complete scan covers the latest gap. Other backend errors still trigger subscription recovery; repeated terminal failures fall back to five-minute polling, where recent edits can lag. Search and MCP responses retain health warnings even after the file queue drains. A complete reconciliation means the filesystem scan completed; queued embedding work can still be pending.
 
 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.
 
@@ -485,7 +485,17 @@ When heavy work is paused, the daemon keeps metadata, bounded symbol/file lookup
 
 To serve bounded reads under an existing startup quarantine, run `gmax watch --daemon --read-only -b`. This preserves the safety markers. `status --json` reports `daemon.service.mode` and its reason; `doctor` reports paused availability and skips native corpus diagnostics. Pausing is sticky for that daemon process. Full service requires a deliberate restart after host recovery and quarantine review. Known critical OS or kernel pressure still stops even the read-only service.
 
-Full-table compaction and new FTS/ANN index builds are disabled in the containment release, including forced maintenance and doctor repair. Existing indexes remain readable; missing lexical indexes fall back to available retrieval. Retained copies are not recovered by this release. A separate exclusive prune-only path requires validation before deployment. Do not repeatedly force repair, use future cutoffs or manually remove index fragments.
+Full-table compaction and new FTS/ANN index builds are disabled in the containment release, including forced maintenance and doctor repair. Existing indexes remain readable; missing lexical indexes fall back to available retrieval. Do not repeatedly force repair, use future cutoffs or manually remove index fragments.
+
+The package includes a separate prune-only helper with pinned Lance 12 dependencies, plus an exclusively leased Node wrapper. Runtime preparation uses `uv >=0.12.18`, an existing Python interpreter and locked wheels; it does not download Python, build from source, load an embedding model or run during installation. The helper currently supports macOS and Linux. No timer, CLI repair or startup path calls it automatically. Explicit recovery has separate production admission; packaging does not authorize live cleanup.
+
+`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.
+
+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.
+
+Explicit helper calls persist a private `.gmax-prune-state.json` receipt outside the table before deletion. Cancellation, invalid results, lost ownership and abandoned running receipts remain uncertain; a verified explicit retry records the prior uncertain attempt. Successful receipts include before/after file lengths, allocated bytes and filesystem free space. These measurements do not imply zero retained copies or a macOS physical-footprint cap. Current, tagged and post-cutoff versions are protected; unverified files are retained. Full-table rewriting remains disabled regardless of receipt state.
 
 `~/.gmax/logs/daemon.log` records containment skips and retained historical compaction outcomes, including duration, logical size, disk size before/after, free space, and bytes reclaimed. `gmax status --json` exposes the last outcome under `daemon.compaction`; its `at` timestamp identifies when it was recorded. Five-minute resource snapshots track footprint, RSS, heap, external/ArrayBuffer memory, Lance cache, workers and pending work for memory investigations. Reading status uses retained snapshots and does not scan the index directory. Logs rotate to `daemon.log.prev`.
 

package/dist/bin.js

@@ -77,7 +77,7 @@ function selectHome() {
     const argv = process.argv.slice(2);
     // These enumerate/route stores per request rather than pinning the process
     // to its launch cwd's store. In particular an MCP session can serve both.
-    if (argv[0] === "mcp" || argv[0] === "status")
+    if (argv[0] === "mcp" || argv[0] === "status" || argv[0] === "recover")
         return;
     const match = (0, stores_1.matchStore)(commandTarget(argv, process.cwd()));
     if (match.kind === "primary")

package/dist/commands/recover.js

@@ -0,0 +1,117 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recover = void 0;
+exports.parseRecoveryCutoff = parseRecoveryCutoff;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const commander_1 = require("commander");
+const prune_state_1 = require("../lib/store/prune-state");
+const recovery_1 = require("../lib/store/recovery");
+function parseRecoveryCutoff(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/.exec(value);
+    if (!match)
+        throw new Error("--cutoff requires an absolute ISO timestamp with timezone");
+    const calendar = new Date(`${value.slice(0, 19)}Z`);
+    const parts = [
+        calendar.getUTCFullYear(),
+        calendar.getUTCMonth() + 1,
+        calendar.getUTCDate(),
+        calendar.getUTCHours(),
+        calendar.getUTCMinutes(),
+        calendar.getUTCSeconds(),
+    ];
+    const result = new Date(value);
+    if (parts.some((part, i) => part !== Number(match[i + 1])) ||
+        !Number.isFinite(result.getTime()))
+        throw new Error("--cutoff is not a valid calendar timestamp");
+    return result;
+}
+exports.recover = new commander_1.Command("recover")
+    .description("Inspect or explicitly prune an offline Lance store without rewriting it")
+    .requiredOption("--table <path>", "Existing .lance table directory")
+    .option("--check", "Check recovery admission without preparing or pruning")
+    .option("--prune", "Explicitly perform exclusively leased prune-only recovery")
+    .option("--version <number>", "Expected current table version", Number)
+    .option("--cutoff <timestamp>", "Real absolute ISO retention cutoff")
+    .option("--acknowledge-uncertain <attempt>", "Acknowledge an inspected uncertain attempt before explicit retry")
+    .option("--json", "Structured outcome and durable receipt")
+    .addHelpText("after", "\nStatus is metadata-only. Pruning requires a persistent autostart-disabled file in the store home, closed store owners, known healthy macOS resources, --version and --cutoff. Recovery does not stop services or clear containment. --check can refuse under unknown pressure without pausing normal service.")
+    .action((opts) => __awaiter(void 0, void 0, void 0, function* () {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.once("SIGINT", abort);
+    process.once("SIGTERM", abort);
+    try {
+        const report = yield (0, recovery_1.recoverStore)({
+            table: opts.table,
+            check: opts.check,
+            prune: opts.prune,
+            version: opts.version,
+            cutoff: opts.cutoff ? parseRecoveryCutoff(opts.cutoff) : undefined,
+            acknowledgeUncertain: opts.acknowledgeUncertain,
+            signal: controller.signal,
+        });
+        console.log(JSON.stringify(report, null, opts.json ? undefined : 2));
+    }
+    catch (error) {
+        let state = "unverified";
+        try {
+            state = (0, prune_state_1.readPruneState)(path.dirname(fs.realpathSync(opts.table)));
+        }
+        catch (_a) { }
+        console.error(JSON.stringify({
+            outcome: state === "unverified" || (state === null || state === void 0 ? void 0 : state.outcome) === "uncertain"
+                ? "uncertain"
+                : "refused",
+            error: error instanceof Error ? error.message : "Recovery failed",
+            state,
+        }));
+        process.exitCode = 1;
+    }
+    finally {
+        process.removeListener("SIGINT", abort);
+        process.removeListener("SIGTERM", abort);
+    }
+}));

package/dist/index.js

@@ -62,6 +62,7 @@ const peek_1 = require("./commands/peek");
 const plugin_1 = require("./commands/plugin");
 const project_1 = require("./commands/project");
 const recent_1 = require("./commands/recent");
+const recover_1 = require("./commands/recover");
 const related_1 = require("./commands/related");
 const remove_1 = require("./commands/remove");
 const repair_1 = require("./commands/repair");
@@ -146,6 +147,7 @@ commander_1.program.addCommand(setup_1.setup);
 commander_1.program.addCommand(config_1.config);
 commander_1.program.addCommand(doctor_1.doctor);
 commander_1.program.addCommand(repair_1.repair);
+commander_1.program.addCommand(recover_1.recover);
 // Plugins
 commander_1.program.addCommand(plugin_1.plugin);
 // Legacy plugin installers (hidden — use `gmax plugin` instead)

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

@@ -57,6 +57,7 @@ const cache_coherence_1 = require("../index/cache-coherence");
 const file_policy_1 = require("../index/file-policy");
 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 file_utils_1 = require("../utils/file-utils");
 const logger_1 = require("../utils/logger");
@@ -68,7 +69,7 @@ const watcher_store_1 = require("../utils/watcher-store");
 // overflows has passed. Probe often; a failed probe just drops back to polling.
 const FSEVENTS_RECOVERY_INTERVAL_MS = 15 * 60 * 1000;
 const FSEVENTS_HEALTH_WINDOW_MS = 5 * 60 * 1000; // 5 min of quiet = "healthy"
-// Overflows arrive in bursts (a build, a checkout, a venv install). Every
+// Terminal subscription failures can arrive in bursts. Every
 // recovery inside this window folds into one deferred catchup scan instead of
 // each rescanning the project (~25s on a 26k-file tree) or skipping outright
 // and leaving its drop window uncovered.
@@ -104,18 +105,21 @@ class WatcherManager {
         this.pollIntervals = new Map();
         this.pollRecoveryTimers = new Map();
         this.recoveryTimeouts = new Map();
-        this.lastOverflowMs = new Map();
+        this.lastWatcherFailureMs = new Map();
         this.lastWatcherErrorLogMs = new Map();
         this.overflowCounts = new Map();
         this.reconciledAt = new Map();
         this.catchupDurations = new Map();
         this.lastCatchupEndMs = new Map();
+        this.lastCatchupStartMs = new Map();
+        this.overflowPendingRoots = new Set();
         this.deferredCatchups = new Map();
         this.catchups = new Map();
         this.degradedRoots = new Set();
         this.terminalFailures = new Map();
         this.watchLifecycles = new Map();
         this.subscriptionUpdates = new Map();
+        this.watcherGenerations = new Map();
     }
     health(root) {
         var _a;
@@ -126,7 +130,8 @@ class WatcherManager {
             watcherMode: this.pollIntervals.has(root)
                 ? "polling"
                 : this.pendingOps.has(`recover:${root}`) ||
-                    this.deferredCatchups.has(root)
+                    this.deferredCatchups.has(root) ||
+                    this.overflowPendingRoots.has(root)
                     ? "recovering"
                     : "native",
             catchupRunning: this.catchups.has(root),
@@ -250,7 +255,7 @@ class WatcherManager {
                     const name = path.basename(root);
                     console.error(`[daemon:${name}] Subscribe failed at startup (${err instanceof Error ? err.message : err}) — switching to poll mode`);
                     this.watcherFailCount.set(root, 1000); // > MAX_WATCHER_RETRIES
-                    this.lastOverflowMs.set(root, Date.now());
+                    this.lastWatcherFailureMs.set(root, Date.now());
                     this.recoverWatcher(root, processor);
                 }
                 if (!ownsLifecycle())
@@ -311,6 +316,8 @@ class WatcherManager {
             if (this.deps.processors.get(root) !== processor ||
                 ((_b = (_a = this.deps).getShuttingDown) === null || _b === void 0 ? void 0 : _b.call(_a)))
                 return;
+            const generation = Symbol(root);
+            this.watcherGenerations.set(root, generation);
             // Unsubscribe existing watcher if any (e.g. during recovery)
             const existingSub = this.deps.subscriptions.get(root);
             if (existingSub) {
@@ -322,21 +329,30 @@ class WatcherManager {
             }
             const sub = yield watcher.subscribe(root, (err, events) => {
                 var _a, _b;
-                if (this.deps.processors.get(root) !== processor)
+                var _c, _d;
+                if (this.deps.processors.get(root) !== processor ||
+                    this.watcherGenerations.get(root) !== generation ||
+                    ((_b = (_a = this.deps).getShuttingDown) === null || _b === void 0 ? void 0 : _b.call(_a)))
                     return;
                 if (err) {
-                    this.overflowCounts.set(root, ((_a = this.overflowCounts.get(root)) !== null && _a !== void 0 ? _a : 0) + 1);
+                    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) ||
                         now - this.lastWatcherErrorLogMs.get(root) >= 60000) {
                         this.lastWatcherErrorLogMs.set(root, now);
                         console.error(`[daemon:${name}] Watcher error (total=${this.overflowCounts.get(root)}):`, err);
                     }
-                    this.recoverWatcher(root, processor);
-                    return;
+                    if ((0, watcher_errors_1.isFSEventsGap)(err)) {
+                        this.overflowPendingRoots.add(root);
+                        this.requestOverflowCatchup(root, processor);
+                    }
+                    else {
+                        this.recoverWatcher(root, processor);
+                    }
                 }
-                // Only reset fail counter after sustained health (5min since last overflow)
-                const lastOverflow = (_b = this.lastOverflowMs.get(root)) !== null && _b !== void 0 ? _b : 0;
+                // Gaps do not kill Parcel's stream. Only a terminal failure should
+                // reset the subscription health window or prevent leaving poll mode.
+                const lastOverflow = (_d = this.lastWatcherFailureMs.get(root)) !== null && _d !== void 0 ? _d : 0;
                 if (Date.now() - lastOverflow > 5 * 60 * 1000) {
                     this.watcherFailCount.delete(root);
                 }
@@ -350,13 +366,30 @@ class WatcherManager {
                     ...(yield (0, watcher_ignore_1.readProjectWatcherIgnores)(root)),
                 ],
             });
-            if (this.deps.processors.get(root) !== processor) {
+            if (this.deps.processors.get(root) !== processor ||
+                this.watcherGenerations.get(root) !== generation) {
                 yield sub.unsubscribe();
                 return;
             }
             this.deps.subscriptions.set(root, sub);
         });
     }
+    requestOverflowCatchup(root, processor) {
+        const started = this.lastCatchupStartMs.get(root);
+        const remaining = started === undefined
+            ? 0
+            : watcher_errors_1.FSEVENTS_GAP_SCAN_INTERVAL_MS - (Date.now() - started);
+        // A gap during a scan may concern a path already visited. Keep one later
+        // scan rather than treating the current walk as coverage of that gap.
+        if (this.catchups.has(root) || remaining > 0) {
+            this.deferCatchup(root, processor, Math.max(remaining, watcher_errors_1.FSEVENTS_GAP_SCAN_INTERVAL_MS));
+            return;
+        }
+        this.cancelDeferredCatchup(root);
+        this.runCatchup(root, processor).catch((err) => {
+            console.error(`[daemon:${path.basename(root)}] Overflow catchup failed:`, err);
+        });
+    }
     recoverWatcher(root, processor) {
         var _a;
         const name = path.basename(root);
@@ -370,11 +403,11 @@ class WatcherManager {
         this.pendingOps.add(recoveryKey);
         const fails = ((_a = this.watcherFailCount.get(root)) !== null && _a !== void 0 ? _a : 0) + 1;
         this.watcherFailCount.set(root, fails);
-        this.lastOverflowMs.set(root, Date.now());
+        this.lastWatcherFailureMs.set(root, Date.now());
         const MAX_WATCHER_RETRIES = 3;
         const POLL_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
         if (fails > MAX_WATCHER_RETRIES) {
-            // FSEvents can't handle this project — degrade to periodic catchup scans
+            // Repeated terminal subscription failures require periodic catchup scans.
             // Always tear down the broken sub, even if poll mode is already active —
             // this can happen if a recovery attempt resubscribed successfully then
             // re-overflowed during the 5-min health window.
@@ -384,7 +417,7 @@ class WatcherManager {
                 this.deps.subscriptions.delete(root);
             }
             if (!this.pollIntervals.has(root)) {
-                console.error(`[daemon:${name}] FSEvents unreliable after ${fails} failures — switching to poll mode (${POLL_INTERVAL_MS / 60000}min interval)`);
+                console.error(`[daemon:${name}] Native watcher failed after ${fails} terminal errors — switching to poll mode (${POLL_INTERVAL_MS / 60000}min interval)`);
                 // Run an immediate catchup, then schedule periodic ones
                 this.runCatchup(root, processor).catch((err) => {
                     console.error(`[daemon:${name}] Poll catchup failed:`, err);
@@ -416,7 +449,7 @@ class WatcherManager {
         }
         // Backoff: wait before re-subscribing (3s, 6s, 12s)
         const delayMs = 3000 * Math.pow(2, (fails - 1));
-        console.error(`[daemon:${name}] Recovering watcher (attempt ${fails}/${MAX_WATCHER_RETRIES}, backoff ${delayMs}ms)...`);
+        console.error(`[daemon:${name}] Recovering failed watcher (attempt ${fails}/${MAX_WATCHER_RETRIES}, backoff ${delayMs}ms)...`);
         const timeout = setTimeout(() => {
             this.recoveryTimeouts.delete(root);
             if (this.deps.getShuttingDown() ||
@@ -520,14 +553,14 @@ class WatcherManager {
                     if (this.deps.processors.get(root) !== processor)
                         return;
                     // Wait one health window — if the new subscription survives without
-                    // another overflow, we consider it recovered and tear down poll mode.
+                    // another terminal failure, we consider it recovered and tear down poll mode.
                     yield abortableDelay(FSEVENTS_HEALTH_WINDOW_MS, lifecycle.signal);
                     if (this.deps.getShuttingDown() ||
                         this.deps.processors.get(root) !== processor)
                         return;
-                    const lastOverflow = (_a = this.lastOverflowMs.get(root)) !== null && _a !== void 0 ? _a : 0;
+                    const lastOverflow = (_a = this.lastWatcherFailureMs.get(root)) !== null && _a !== void 0 ? _a : 0;
                     if (Date.now() - lastOverflow < FSEVENTS_HEALTH_WINDOW_MS) {
-                        console.log(`[daemon:${name}] FSEvents recovery aborted — fresh overflow within health window, staying in poll mode`);
+                        console.log(`[daemon:${name}] FSEvents recovery aborted — terminal failure within health window, staying in poll mode`);
                         return; // recoverWatcher will have re-armed poll mode if needed
                     }
                     // Healthy — drop poll mode.
@@ -555,8 +588,9 @@ class WatcherManager {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, e_1, _b, _c;
             var _d;
-            var _e;
+            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();
@@ -573,12 +607,12 @@ class WatcherManager {
             let skipped = 0;
             let debugSamples = 0;
             try {
-                for (var _f = true, _g = __asyncValues((0, walker_1.walk)(root, {
+                for (var _h = true, _j = __asyncValues((0, walker_1.walk)(root, {
                     policy: processor.filePolicy,
                     state: walkState,
-                })), _h; _h = yield _g.next(), _a = _h.done, !_a; _f = true) {
-                    _c = _h.value;
-                    _f = false;
+                })), _k; _k = yield _j.next(), _a = _k.done, !_a; _h = true) {
+                    _c = _k.value;
+                    _h = false;
                     const relPath = _c;
                     if (signal.aborted)
                         return false;
@@ -668,7 +702,7 @@ class WatcherManager {
             catch (e_1_1) { e_1 = { error: e_1_1 }; }
             finally {
                 try {
-                    if (!_f && !_a && (_b = _g.return)) yield _b.call(_g);
+                    if (!_h && !_a && (_b = _j.return)) yield _b.call(_j);
                 }
                 finally { if (e_1) throw e_1.error; }
             }
@@ -701,7 +735,7 @@ class WatcherManager {
             }
             else {
                 this.degradedRoots.delete(root);
-                const failedFiles = (_e = (_d = this.terminalFailures.get(root)) === null || _d === void 0 ? void 0 : _d.size) !== null && _e !== void 0 ? _e : 0;
+                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` }
                     : {})));
@@ -717,8 +751,12 @@ class WatcherManager {
             const ended = Date.now();
             this.lastCatchupEndMs.set(root, ended);
             this.catchupDurations.set(root, ended - scanStart);
-            if (complete)
+            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);
+            }
             return complete;
         });
     }
@@ -737,6 +775,7 @@ class WatcherManager {
             let incompleteRetries = 0;
             do {
                 active.dirty = false;
+                this.lastCatchupStartMs.set(root, Date.now());
                 const complete = yield this.catchupScan(root, processor, signal);
                 if (!complete && !signal.aborted && incompleteRetries < 3) {
                     incompleteRetries++;
@@ -775,6 +814,7 @@ class WatcherManager {
             // independently of the processor, so clear them even on the early return.
             (_a = this.watchLifecycles.get(root)) === null || _a === void 0 ? void 0 : _a.abort();
             this.watchLifecycles.delete(root);
+            this.watcherGenerations.delete(root);
             const pollInterval = this.pollIntervals.get(root);
             if (pollInterval) {
                 clearInterval(pollInterval);
@@ -804,8 +844,10 @@ class WatcherManager {
                 this.deps.subscriptions.delete(root);
             }
             this.deps.evictSearcher(root);
-            this.lastOverflowMs.delete(root);
+            this.lastWatcherFailureMs.delete(root);
             this.lastCatchupEndMs.delete(root);
+            this.lastCatchupStartMs.delete(root);
+            this.overflowPendingRoots.delete(root);
             this.degradedRoots.delete(root);
             this.terminalFailures.delete(root);
             (0, watcher_store_1.unregisterWatcherByRoot)(root);

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

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FSEVENTS_GAP_SCAN_INTERVAL_MS = void 0;
+exports.isFSEventsGap = isFSEventsGap;
+/** Parcel reports these gaps without closing its FSEvents stream. Other errors
+ * may clear the native callbacks and still require subscription recovery. */
+function isFSEventsGap(error) {
+    return (error.message ===
+        "Events were dropped by the FSEvents client. File system must be re-scanned." ||
+        error.message ===
+            "Events were dropped by the kernel. File system must be re-scanned." ||
+        error.message === "Too many events. File system must be re-scanned.");
+}
+// Bound reconciliation under sustained churn without abandoning native edits
+// for the five-minute polling fallback used by a failed subscription.
+exports.FSEVENTS_GAP_SCAN_INTERVAL_MS = 30000;

package/dist/lib/index/watcher.js

@@ -58,6 +58,7 @@ const cache_coherence_1 = require("./cache-coherence");
 const file_policy_1 = require("./file-policy");
 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");
 // 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
@@ -125,6 +126,11 @@ function startWatcher(opts) {
         let subscription = null;
         let subscriptionUpdate = Promise.resolve();
         let subscriptionPolicy = "";
+        let subscriptionFailed = false;
+        let subscriptionGeneration = 0;
+        let gapScanTimer;
+        let lastReconcileStart;
+        let gapGeneration = 0;
         const updateSubscription = () => {
             const update = subscriptionUpdate
                 .catch(() => { })
@@ -134,16 +140,31 @@ function startWatcher(opts) {
                     ...(yield (0, watcher_ignore_1.readProjectWatcherIgnores)(projectRoot)),
                 ];
                 const policy = JSON.stringify(ignores);
-                if (closing || (subscription && subscriptionPolicy === policy))
+                if (closing ||
+                    (subscription && !subscriptionFailed && subscriptionPolicy === policy))
                     return;
+                const generation = ++subscriptionGeneration;
+                subscriptionFailed = false;
                 yield subscription === null || subscription === void 0 ? void 0 : subscription.unsubscribe();
                 subscription = null;
                 if (closing)
                     return;
                 const next = yield watcher.subscribe(projectRoot, (err, events) => {
+                    var _a;
+                    if (closing || generation !== subscriptionGeneration)
+                        return;
                     if (err) {
                         console.error(`[${wtag}] Watcher error:`, err);
-                        return;
+                        scanHealthy = false;
+                        (_a = opts.onHealthChange) === null || _a === void 0 ? void 0 : _a.call(opts, false, 1);
+                        gapGeneration++;
+                        if ((0, watcher_errors_1.isFSEventsGap)(err))
+                            requestGapScan();
+                        else {
+                            // Terminal backend errors can clear Parcel's callbacks.
+                            subscriptionFailed = true;
+                            reconcile();
+                        }
                     }
                     for (const event of events)
                         processor.handleFileEvent(event.type === "delete" ? "unlink" : "change", event.path);
@@ -180,6 +201,8 @@ function startWatcher(opts) {
                 let incompleteRetries = 0;
                 do {
                     reconcileRequested = false;
+                    lastReconcileStart = Date.now();
+                    const observedGapGeneration = gapGeneration;
                     filePolicy.invalidateIgnoreCache();
                     yield updateSubscription();
                     if (closing)
@@ -243,7 +266,7 @@ function startWatcher(opts) {
                         }
                     }
                     else {
-                        scanHealthy = true;
+                        scanHealthy = observedGapGeneration === gapGeneration;
                         if (ingestionDegraded && processor.progress.pendingFiles > 0) {
                             degradedRepairQueued = true;
                         }
@@ -257,6 +280,21 @@ function startWatcher(opts) {
                 reconciliation = null;
             });
         };
+        const requestGapScan = () => {
+            if (closing || gapScanTimer)
+                return;
+            const remaining = lastReconcileStart === undefined
+                ? 0
+                : watcher_errors_1.FSEVENTS_GAP_SCAN_INTERVAL_MS - (Date.now() - lastReconcileStart);
+            if (reconciliation || remaining > 0) {
+                gapScanTimer = setTimeout(() => {
+                    gapScanTimer = undefined;
+                    reconcile();
+                }, Math.max(remaining, watcher_errors_1.FSEVENTS_GAP_SCAN_INTERVAL_MS));
+                return;
+            }
+            reconcile();
+        };
         processor = new batch_processor_1.ProjectBatchProcessor(Object.assign(Object.assign({}, opts), { filePolicy, onPolicyChange: reconcile, onReindex: (files, durationMs) => {
                 var _a;
                 (_a = opts.onReindex) === null || _a === void 0 ? void 0 : _a.call(opts, files, durationMs);
@@ -284,6 +322,8 @@ function startWatcher(opts) {
             },
             close: () => __awaiter(this, void 0, void 0, function* () {
                 closing = true;
+                subscriptionGeneration++;
+                clearTimeout(gapScanTimer);
                 yield subscriptionUpdate.catch(() => { });
                 yield subscription === null || subscription === void 0 ? void 0 : subscription.unsubscribe();
                 yield reconciliation;