@quolu/lattice 0.69.5 → 0.71.0

package/sensor/dist/sync/watcher.js

@@ -9,7 +9,8 @@
  * addon) with a per-platform strategy chosen to keep the open-descriptor /
  * kernel-watch cost BOUNDED rather than growing with the number of files:
  *
- *   - macOS / Windows: a SINGLE recursive `fs.watch(root, {recursive:true})`.
+ *   - macOS / Windows: a recursive `fs.watch(root, {recursive:true})`, plus
+ *     bounded supplemental streams for directory symlinks (#770).
  *     libuv maps this to one FSEvents stream (macOS) / one
  *     ReadDirectoryChangesW handle (Windows), so it costs O(1) descriptors no
  *     matter how large the tree. This is the fix for the macOS file-table
@@ -25,11 +26,12 @@
  *     per-file watches are never needed.
  *
  * Excluded trees (node_modules/, dist/, .git/, …) are filtered via the
- * indexer's `buildScopeIgnore` (built-in default-ignore dirs + the project's
- * .gitignore) — on Linux they're never descended into (so they cost no watch),
- * and on macOS/Windows the single recursive stream still covers them but their
+ * indexer's `buildScopeIgnore` (built-in defaults + root `.gitignore` +
+ * `.git/info/exclude` + `core.excludesFile` + git ignored-untracked dirs) —
+ * on Linux they're never descended into (so they cost no watch), and on
+ * macOS/Windows the single recursive stream still covers them but their
  * events are dropped before any sync is scheduled. Either way the watcher's
- * scope matches the indexer's (#276 / #407).
+ * scope matches `git ls-files --exclude-standard` (#276 / #407 / #1728).
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -82,6 +84,8 @@ const watch_policy_1 = require("./watch-policy");
  * few cycles) stays under this; a long-lived external writer crosses it.
  */
 const MAX_LOCK_RETRIES = 5;
+/** A failed re-arm must not turn frequent MCP calls into a lock-polling loop. */
+const LOCK_REARM_COOLDOWN_MS = 30_000;
 /**
  * Number of consecutive GENERIC (non-lock) sync failures the watcher tolerates
  * before it degrades auto-sync. A deterministic failure — a tree-sitter
@@ -205,8 +209,8 @@ exports.LockUnavailableError = LockUnavailableError;
  * debounced sync operations via a provided callback.
  *
  * Design goals:
- * - Bounded resource usage: O(1) descriptors on macOS/Windows (one recursive
- *   watch), O(directories) inotify watches on Linux — never O(files), which
+ * - Bounded resource usage: one recursive stream plus capped symlink streams
+ *   on macOS/Windows, O(directories) inotify watches on Linux — never O(files), which
  *   was the system-crashing fd leak on macOS (#644/#496/#555/#628).
  * - Debounced to avoid thrashing on rapid saves
  * - Filters to supported source files by extension
@@ -217,7 +221,7 @@ exports.LockUnavailableError = LockUnavailableError;
 class FileWatcher {
     /** macOS/Windows: the single recursive watcher. Null on Linux. */
     recursiveWatcher = null;
-    /** Linux: one watcher per watched directory (keyed by absolute path). */
+    /** Linux directory watches / macOS and Windows supplemental symlink streams. */
     dirWatchers = new Map();
     /** Set once the per-directory watch cap is hit, so we log only once. */
     dirCapWarned = false;
@@ -230,18 +234,31 @@ class FileWatcher {
      */
     inotifyLimitWarned = false;
     /**
-     * One-way latch: the reason live watching was permanently disabled at runtime
+     * The reason live watching was disabled at runtime
      * (watch-resource exhaustion, lock contention past the retry budget, or a
      * persistent generic sync failure past the retry budget), or null while
-     * healthy. Set by {@link degrade}; cleared only by a fresh start().
+     * healthy. Set by {@link degrade}; a lock-contention recovery keeps it until
+     * a full reconciliation succeeds.
      */
     degradedReason = null;
+    degradedByLock = false;
+    recoveringFromLock = false;
+    lastLockRearmMs = 0;
     /** Consecutive lock-contention retries for watcher-triggered syncs. */
     lockRetryCount = 0;
     /** Consecutive generic (non-lock) sync failures; reset only by a clean sync. */
     syncFailureRetryCount = 0;
     /** Test-only inert mode: started, but with no OS watcher installed. */
     inert = false;
+    /**
+     * Resolved realpath of directories already watched (or skipped). Prevents
+     * infinite recursion via symlink cycles — mirrors the same guard used in
+     * the indexer's `walk()` (extraction/index.ts).
+     */
+    visitedRealDirs = new Set();
+    knownDirs = new Map();
+    watchedRealDirs = new Map();
+    treeRefreshTimer = null;
     debounceTimer = null;
     /**
      * True when the pending set does NOT exactly describe the change (a
@@ -282,11 +299,15 @@ class FileWatcher {
      * deterministically gate on watcher readiness.
      */
     readyWaiters = [];
-    // The shared scope matcher (built-in defaults + project .gitignore, with
-    // embedded child repos matched by their OWN rules — #514), built once at
-    // start(). Same source of truth the indexer uses, so watcher scope can
-    // never diverge from index scope. An embedded repo created after start()
-    // joins the scope on the next watcher restart / re-index.
+    // The shared scope matcher from `buildScopeIgnore` (built-in defaults +
+    // root `.gitignore` + `.git/info/exclude` + `core.excludesFile` + dirs
+    // `git ls-files --exclude-standard` reports ignored + `lattice-sensor.json`
+    // exclude/include, with embedded child repos matched by their OWN rules —
+    // #514), built at start() and REBUILT whenever one of the files it is
+    // derived from changes (see `refreshScope`, #1590). Same construction the
+    // indexer uses for scoped sync, so watcher scope cannot diverge from index
+    // scope (#1728). An embedded repo created after start() joins the scope on
+    // the next scope refresh / watcher restart / re-index.
     ignoreMatcher = null;
     projectRoot;
     debounceMs;
@@ -295,7 +316,14 @@ class FileWatcher {
     onSyncError;
     onDegraded;
     inertForTests;
-    constructor(projectRoot, syncFn, options = {}) {
+    /**
+     * Optional metadata guard supplied by the LatticeSensor facade. Windows'
+     * ReadDirectoryChangesW stream includes last-access updates, so a read can
+     * otherwise look exactly like an edit. Returning true means the file's
+     * current size/mtime still match the indexed record and the event is noise.
+     */
+    isFileStateCurrent;
+    constructor(projectRoot, syncFn, options = {}, isFileStateCurrent) {
         this.projectRoot = projectRoot;
         this.syncFn = syncFn;
         this.debounceMs = options.debounceMs ?? 2000;
@@ -303,6 +331,7 @@ class FileWatcher {
         this.onSyncError = options.onSyncError;
         this.onDegraded = options.onDegraded;
         this.inertForTests = options.inertForTests ?? false;
+        this.isFileStateCurrent = isFileStateCurrent;
     }
     /**
      * Start watching for file changes.
@@ -313,8 +342,11 @@ class FileWatcher {
             return true; // Already watching
         this.stopped = false;
         this.degradedReason = null;
+        this.degradedByLock = false;
+        this.recoveringFromLock = false;
         this.lockRetryCount = 0;
         this.syncFailureRetryCount = 0;
+        this.needsFullScan = false;
         // Some environments make filesystem watching unusable — most notably
         // WSL2 /mnt/ drives, where the underlying fs.watch calls block long
         // enough to break MCP startup handshakes (issue #199). Skip watching
@@ -335,10 +367,10 @@ class FileWatcher {
                 this.startRecursive();
             }
             else {
-                this.startPerDirectory();
+                this.refreshWatchTree();
             }
             // The per-directory (Linux) path catches watch-resource exhaustion inside
-            // watchTree and degrades synchronously rather than throwing, so it never
+            // watchDirectory and degrades synchronously rather than throwing, so it never
             // reaches the catch below. Surface that as a failed start here so both
             // strategies report exhaustion identically (start() === false).
             if (this.degradedReason)
@@ -377,16 +409,12 @@ class FileWatcher {
         }
     }
     /**
-     * macOS/Windows: one recursive watcher for the whole tree. O(1) descriptors.
+     * macOS/Windows: one root stream, supplemented for directory symlinks.
      * `filename` arrives relative to the project root (with subdirectories), so
      * it maps straight to a project-relative path.
      */
     startRecursive() {
-        this.recursiveWatcher = watchImpl(this.projectRoot, { recursive: true, persistent: true }, (_event, filename) => {
-            if (this.stopped || filename == null)
-                return;
-            this.handleChange((0, utils_1.normalizePath)(String(filename)));
-        });
+        this.recursiveWatcher = watchImpl(this.projectRoot, { recursive: true, persistent: true }, (_event, filename) => this.handleDirEvent(this.projectRoot, filename));
         this.recursiveWatcher.on('error', (err) => {
             if (isWatchResourceExhaustion(err)) {
                 this.degrade(EXHAUSTION_REASON, { error: String(err) });
@@ -394,46 +422,88 @@ class FileWatcher {
             }
             (0, errors_1.logWarn)('File watcher error', { error: String(err) });
         });
+        this.refreshWatchTree();
     }
-    /**
-     * Linux: walk the (non-ignored) tree and watch each directory. One inotify
-     * watch per directory reports create/modify/delete for that directory's
-     * direct children, so we never watch individual files.
-     */
-    startPerDirectory() {
-        this.watchTree(this.projectRoot, /* markExisting */ false);
+    /** Reconcile logical directory paths with real targets, including retargeted links. */
+    refreshWatchTree() {
+        if (this.stopped || this.inert)
+            return;
+        this.visitedRealDirs.clear();
+        const directories = new Map();
+        const desired = new Map();
+        const recursive = supportsRecursiveWatch();
+        const walk = (dir, linked) => {
+            if (this.shouldIgnoreDir(dir))
+                return;
+            let real;
+            try {
+                real = fs.realpathSync(dir);
+                if (this.visitedRealDirs.has(real))
+                    return;
+                this.visitedRealDirs.add(real);
+                directories.set(dir, real);
+                if (!recursive || linked)
+                    desired.set(dir, real);
+                for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                    const child = path.join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        walk(child, false);
+                    }
+                    else if (entry.isSymbolicLink()) {
+                        // Follow directory symlinks just like the indexer's walk. Realpath
+                        // deduplication includes ordinary directories and the root itself.
+                        try {
+                            if (fs.statSync(child).isDirectory())
+                                walk(child, true);
+                        }
+                        catch { /* broken link */ }
+                    }
+                }
+            }
+            catch { /* removed or unreadable directory */ }
+        };
+        walk(this.projectRoot, false);
+        this.knownDirs = directories;
+        for (const dir of this.dirWatchers.keys()) {
+            if (desired.get(dir) !== this.watchedRealDirs.get(dir))
+                this.unwatchDir(dir);
+        }
+        for (const [dir, real] of desired)
+            this.watchDirectory(dir, real, recursive);
     }
-    /**
-     * Add an inotify watch for `dir` and recurse into its non-ignored
-     * subdirectories. When `markExisting` is true (a directory that appeared
-     * AFTER startup), the source files already inside it are recorded as pending
-     * — this closes the `mkdir + write` race where files created before the new
-     * directory's watch is installed would otherwise be missed until the next
-     * full sync. The initial startup walk passes false (the engine's catch-up
-     * sync owns the baseline).
-     */
-    watchTree(dir, markExisting) {
-        // A degrade() mid-walk (exhaustion on an earlier directory) calls stop(),
-        // which sets `stopped`; bail so the recursion unwinds without adding more
-        // watches to a watcher that is shutting down. `inotifyLimitWarned` does the
-        // same after ENOSPC — the kernel budget is gone, so stop trying the rest of
-        // the tree (every add would fail) while keeping the watches already set.
-        if (this.stopped || this.degradedReason || this.inotifyLimitWarned)
+    /** Coalesce directory topology events before walking; file edits never walk the tree. */
+    scheduleTreeRefresh() {
+        if (this.treeRefreshTimer || this.inert || this.stopped)
+            return;
+        this.treeRefreshTimer = setTimeout(() => {
+            this.treeRefreshTimer = null;
+            this.refreshWatchTree();
+            if (this.stopped)
+                return;
+            // A new/retargeted directory can already contain files before its watch
+            // is installed; a full reconcile closes that race and removes old paths.
+            this.needsFullScan = true;
+            this.scheduleSync();
+        }, 50);
+    }
+    watchDirectory(dir, real, recursive) {
+        if (this.stopped || (this.degradedReason && !this.recoveringFromLock) || this.inotifyLimitWarned)
             return;
         if (this.dirWatchers.has(dir))
             return;
-        if (this.dirWatchers.size >= maxDirWatches()) {
+        // Recursive streams cost more than inotify entries. Keep a separate hard
+        // ceiling while honouring a lower user-configured directory watch budget.
+        const cap = recursive ? Math.min(256, maxDirWatches()) : maxDirWatches();
+        if (this.dirWatchers.size >= cap) {
             if (!this.dirCapWarned) {
                 this.dirCapWarned = true;
-                (0, errors_1.logWarn)('File watcher hit directory-watch cap; remaining subtrees rely on manual/periodic sync', {
-                    cap: maxDirWatches(),
-                });
+                (0, errors_1.logWarn)('File watcher hit directory-watch cap; remaining subtrees rely on manual/periodic sync', { cap });
             }
             return;
         }
         let w;
         try {
-            w = watchImpl(dir, { persistent: true }, (_event, filename) => this.handleDirEvent(dir, filename));
+            w = watchImpl(dir, { persistent: true, recursive }, (_event, filename) => this.handleDirEvent(dir, filename));
         }
         catch (err) {
             // EMFILE/ENFILE means the PROCESS is out of descriptors — every further
@@ -461,49 +531,41 @@ class FileWatcher {
             this.unwatchDir(dir);
         });
         this.dirWatchers.set(dir, w);
-        let entries;
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            const child = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                if (this.shouldIgnoreDir(child))
-                    continue;
-                this.watchTree(child, markExisting);
-            }
-            else if (markExisting && entry.isFile()) {
-                this.handleChange((0, utils_1.normalizePath)(path.relative(this.projectRoot, child)));
-            }
-        }
+        this.watchedRealDirs.set(dir, real);
     }
-    /**
-     * Linux per-directory event handler. `filename` is relative to `dir`. A new
-     * sub-directory is picked up by extending the watch tree; everything else is
-     * routed through the shared change handler.
-     */
+    /** Events are relative to a watch's logical path, even for an external target. */
     handleDirEvent(dir, filename) {
-        if (this.stopped || filename == null)
+        if (this.stopped)
             return;
+        if (filename == null) {
+            this.scheduleTreeRefresh();
+            return;
+        }
         const full = path.join(dir, String(filename));
-        // A newly-created directory needs its own watch (recursive isn't available
-        // on Linux). statSync is cheap and these events are rare relative to file
-        // edits. If the path vanished (rapid create/delete) the stat throws and we
-        // fall through to the change handler, which no-ops on a non-source path.
+        const rel = (0, utils_1.normalizePath)(path.relative(this.projectRoot, full));
+        if (!rel || rel === '.') {
+            this.scheduleTreeRefresh();
+            return;
+        }
+        // Churn under an ignored directory (node_modules, dist, .git) is dropped
+        // before any per-event fs call; `.git/info/exclude` still reaches the scope
+        // refresh in handleChange (#1728).
+        if (rel !== '.git/info/exclude' && this.shouldIgnoreDir(path.dirname(full)))
+            return;
         try {
             if (fs.statSync(full).isDirectory()) {
-                if (!this.shouldIgnoreDir(full))
-                    this.watchTree(full, /* markExisting */ true);
+                if (this.shouldIgnoreDir(full))
+                    return;
+                // Existing directory notifications can represent a retargeted link.
+                if (this.knownDirs.get(full) !== fs.realpathSync(full))
+                    this.scheduleTreeRefresh();
                 return;
             }
         }
-        catch {
-            // deleted/inaccessible — treat as a normal change below
-        }
-        this.handleChange((0, utils_1.normalizePath)(path.relative(this.projectRoot, full)));
+        catch { /* deleted/inaccessible */ }
+        if (this.knownDirs.has(full) && !this.shouldIgnoreDir(full))
+            this.scheduleTreeRefresh();
+        this.handleChange(rel);
     }
     /**
      * Shared change handler for both watch strategies. `rel` is a
@@ -518,14 +580,53 @@ class FileWatcher {
     handleChange(rel) {
         if (!rel || rel === '.' || rel.startsWith('..'))
             return;
+        // `.git/info/exclude` is otherwise always-ignored with the rest of `.git/`,
+        // but it feeds `buildScopeIgnore` — allow it through as a scope refresh
+        // when the platform delivers the event (recursive watchers may; Linux
+        // per-directory watching does not descend into `.git/`) (#1728).
+        if (rel === '.git/info/exclude') {
+            this.refreshScope(rel);
+            return;
+        }
         if (this.isAlwaysIgnored(rel))
             return;
+        // The two root files the scope matcher is derived from are handled BEFORE
+        // the matcher is consulted: a user `exclude` pattern that happens to cover
+        // them (`*.json`, `.*`) must not be able to hide their own edits (#1590).
+        if (rel === project_config_1.PROJECT_CONFIG_FILENAME || rel === '.gitignore') {
+            this.refreshScope(rel);
+            return;
+        }
         if (this.ignoreMatcher && this.ignoreMatcher.ignores(rel))
             return;
+        // A nested `.gitignore` (an embedded child repo's own rules, #514, or a
+        // subdirectory rule the git-backed full scan honors) is only a scope
+        // change when it sits INSIDE the current scope — checked after the matcher
+        // on purpose, so the thousands of package-local `.gitignore`s an
+        // `npm install` writes under an ignored `node_modules/` never trigger a
+        // rebuild storm.
+        if (rel.endsWith('/.gitignore')) {
+            this.refreshScope(rel);
+            return;
+        }
         if (!(0, extraction_1.isSourceFile)(rel, (0, project_config_1.loadExtensionOverrides)(this.projectRoot))) {
             this.maybeScheduleForRemovedDir(rel);
             return;
         }
+        try {
+            if (this.isFileStateCurrent?.(rel)) {
+                (0, errors_1.logDebug)('Ignoring file event with unchanged indexed metadata', { file: rel });
+                return;
+            }
+        }
+        catch (error) {
+            // The guard is an optimization, never a correctness boundary. If the
+            // stat/DB lookup fails, keep the event so a sync can reconcile it.
+            (0, errors_1.logDebug)('Could not verify file event metadata; treating it as a change', {
+                file: rel,
+                error: String(error),
+            });
+        }
         (0, errors_1.logDebug)('File change detected', { file: rel });
         if (this.ready) {
             const now = Date.now();
@@ -537,6 +638,34 @@ class FileWatcher {
         }
         this.scheduleSync();
     }
+    /**
+     * A scope-defining file changed (`lattice-sensor.json`, a `.gitignore`): rebuild
+     * the ignore matcher and make the next sync a FULL reconcile (#1590).
+     *
+     * The matcher used to be built once in `start()` and kept for the watcher's
+     * lifetime — in a long-lived MCP daemon that meant a `lattice-sensor.json`
+     * created or edited after startup was invisible to the live watcher, while
+     * `lattice sensor sync` (a fresh process) honoured it immediately: the CLI
+     * removed a newly excluded file and the watcher re-added it seconds later.
+     * `loadExtensionOverrides()` on the same filter line was already read live
+     * (mtime-cached), so two fields of the same config file disagreed.
+     *
+     * Rebuilding costs one `git ls-files` pass (embedded-repo discovery), which
+     * is fine per config edit — never per event. Replacing the field is enough
+     * for both strategies: the recursive handler and the per-directory
+     * `shouldIgnoreDir` walk read `this.ignoreMatcher` on every call. The full
+     * scan is required because a scope change has no per-file events: newly
+     * excluded files must be REMOVED from the index and newly included ones
+     * added, and only the scan-diff (which builds its own fresh matcher) knows
+     * which those are.
+     */
+    refreshScope(rel) {
+        (0, errors_1.logDebug)('Scope config changed; rebuilding watcher scope', { file: rel });
+        this.ignoreMatcher = (0, extraction_1.buildScopeIgnore)(this.projectRoot);
+        this.scheduleTreeRefresh();
+        this.needsFullScan = true;
+        this.scheduleSync();
+    }
     /**
      * A deleted DIRECTORY arrives as one event on the directory's own path —
      * no source extension, so the source-file filter drops it, and the files
@@ -578,16 +707,15 @@ class FileWatcher {
                 /* already closed */
             }
             this.dirWatchers.delete(dir);
+            this.watchedRealDirs.delete(dir);
         }
     }
     /** Our own dirs are always ignored, regardless of .gitignore. */
     isAlwaysIgnored(rel) {
-        // First path segment. Ignore any LatticeSensor data dir — the active one AND a
+        // Ignore any LatticeSensor data dir — the active one AND a
         // sibling like `.lattice/sensor-win` a second environment (Windows/WSL) created
         // in the same tree, so neither side watches the other's index (#636).
-        const top = rel.split('/')[0] ?? rel;
-        return ((0, directory_1.isLatticeStateDir)(top) ||
-            rel === '.git' || rel.startsWith('.git/'));
+        return rel.split('/').some(part => (0, directory_1.isLatticeStateDir)(part) || part === '.git');
     }
     /**
      * True for any directory that should NOT be watched (used while building the
@@ -605,16 +733,18 @@ class FileWatcher {
         return this.ignoreMatcher.ignores(rel + '/');
     }
     /**
-     * Permanently disable live watching after a terminal runtime failure
+     * Disable live watching after a terminal runtime failure
      * (watch-resource exhaustion, lock contention past the retry budget, or a
      * persistent generic sync failure past the retry budget).
      * Idempotent: logs one actionable warning, fires {@link WatchOptions.onDegraded}
      * once, and stops the watcher. A subsequent start() clears the latch.
      */
-    degrade(reason, context = {}) {
-        if (this.degradedReason)
+    degrade(reason, context = {}, byLock = false) {
+        if (this.degradedReason && !this.recoveringFromLock)
             return;
         this.degradedReason = reason;
+        this.degradedByLock = byLock;
+        this.recoveringFromLock = false;
         (0, errors_1.logWarn)('File watcher disabled', { projectRoot: this.projectRoot, reason, ...context });
         this.onDegraded?.(reason);
         this.stop();
@@ -634,7 +764,7 @@ class FileWatcher {
         (0, errors_1.logWarn)(INOTIFY_LIMIT_REASON, { watchedDirs: this.dirWatchers.size, ...context });
     }
     /**
-     * Whether live watching has degraded permanently (until the next start()).
+     * Whether live watching has degraded or is still catching up after re-arm.
      * Distinct from {@link isActive}: a degraded watcher is inactive, but an
      * inactive watcher is not necessarily degraded (it may simply be stopped or
      * never started). Hosts use this to tell the user auto-sync is off.
@@ -646,11 +776,52 @@ class FileWatcher {
     getDegradedReason() {
         return this.degradedReason;
     }
+    /** Watches are live again, but the full catch-up has not committed yet. */
+    isRecoveringFromLock() {
+        return this.recoveringFromLock;
+    }
+    /**
+     * Re-arm a watcher disabled by lock contention when a caller next uses the
+     * graph. Keep the whole-index stale banner until a FULL scan reconciles edits
+     * missed while watches were off. Resource exhaustion and deterministic sync
+     * failures are not automatically retried. Repeated unsuccessful re-arms are
+     * throttled so many MCP sessions cannot hammer a long-lived writer.
+     */
+    rearmAfterLockContention() {
+        if (!this.degradedByLock || this.isActive())
+            return false;
+        const now = Date.now();
+        if (this.lastLockRearmMs && now - this.lastLockRearmMs < LOCK_REARM_COOLDOWN_MS)
+            return false;
+        const reason = this.degradedReason;
+        this.lastLockRearmMs = now;
+        if (!this.start()) {
+            // A disabled platform can reject start() without calling degrade().
+            // Preserve the old stale-index signal in that case; a new resource
+            // failure has its own more precise degraded reason.
+            if (!this.degradedReason) {
+                this.degradedReason = reason;
+                this.degradedByLock = true;
+            }
+            return false;
+        }
+        this.degradedReason = reason;
+        this.recoveringFromLock = true;
+        this.needsFullScan = true;
+        this.scheduleSync();
+        return true;
+    }
     /**
      * Stop watching for file changes.
      */
     stop() {
         this.stopped = true;
+        if (this.treeRefreshTimer)
+            clearTimeout(this.treeRefreshTimer);
+        this.treeRefreshTimer = null;
+        this.knownDirs.clear();
+        this.watchedRealDirs.clear();
+        this.recoveringFromLock = false;
         if (this.debounceTimer) {
             clearTimeout(this.debounceTimer);
             this.debounceTimer = null;
@@ -679,6 +850,7 @@ class FileWatcher {
         this.syncFailureRetryCount = 0;
         // NB: degradedReason is intentionally NOT reset here — it must survive the
         // stop() that degrade() triggers so isDegraded() stays true. start() clears it.
+        this.visitedRealDirs.clear();
         this.inert = false;
         this.pendingFiles.clear();
         this.ready = false;
@@ -788,10 +960,16 @@ class FileWatcher {
         const scoped = !this.needsFullScan && this.pendingFiles.size > 0 && this.pendingFiles.size <= SCOPED_SYNC_MAX_PENDING
             ? [...this.pendingFiles.keys()]
             : undefined;
+        // Consume this request before yielding so a topology/scope change during
+        // the full sync remains pending for the next reconcile.
+        if (!scoped)
+            this.needsFullScan = false;
         try {
             const result = await this.syncFn(scoped);
-            if (!scoped)
-                this.needsFullScan = false;
+            if (this.recoveringFromLock && !scoped && !this.needsFullScan) {
+                this.degradedReason = null;
+                this.recoveringFromLock = false;
+            }
             this.lockRetryCount = 0; // a clean sync clears any contention backoff
             this.syncFailureRetryCount = 0; // ...and any generic-failure backoff
             // Remove entries whose most recent event predates this sync — those
@@ -809,6 +987,8 @@ class FileWatcher {
             this.onSyncComplete?.(result);
         }
         catch (err) {
+            if (!scoped)
+                this.needsFullScan = true;
             if (err instanceof LockUnavailableError) {
                 this.lockRetryCount += 1;
                 // Lock-failure no-op (another writer holds the lock). pendingFiles
@@ -823,7 +1003,7 @@ class FileWatcher {
                 if (this.lockRetryCount > MAX_LOCK_RETRIES) {
                     this.degrade('LatticeSensor file lock held by another process past the retry budget; ' +
                         'auto-sync disabled. Run `lattice sensor sync` once the other writer finishes ' +
-                        '(or install git sync hooks) to refresh the graph.', { pendingFiles: this.pendingFiles.size, retryCount: this.lockRetryCount });
+                        '(or install git sync hooks) to refresh the graph.', { pendingFiles: this.pendingFiles.size, retryCount: this.lockRetryCount }, true);
                 }
             }
             else {
@@ -861,8 +1041,10 @@ class FileWatcher {
             // sync resets both counters so normal edits keep the fast debounce. Use
             // the larger streak so interleaved failures still back off. A degrade()
             // above already set `stopped`, so this won't reschedule a watcher that
-            // has given up.
-            if (this.pendingFiles.size > 0 && !this.stopped) {
+            // has given up. A directory removal whose full sync failed adds no
+            // pending file, only `needsFullScan` — it still owes the full reconcile
+            // it asked for (#1964).
+            if ((this.pendingFiles.size > 0 || this.needsFullScan) && !this.stopped) {
                 const retryCount = Math.max(this.lockRetryCount, this.syncFailureRetryCount);
                 if (retryCount > 0) {
                     const retryDelayMs = Math.min(this.debounceMs * 2 ** Math.max(0, retryCount - 1), MAX_RETRY_BACKOFF_MS);