Class FileWatcher

src/sync/watcher.ts:263–974

 *   without blocking on a sync (issue #403)
 */
export class FileWatcher {
  /** macOS/Windows: the single recursive watcher. Null on Linux. */
  private recursiveWatcher: fs.FSWatcher | null = null;
  /** Linux: one watcher per watched directory (keyed by absolute path). */
  private dirWatchers = new Map<string, fs.FSWatcher>();
  /** Set once the per-directory watch cap is hit, so we log only once. */
  private dirCapWarned = false;
  /**
   * Set once the Linux inotify watch limit (ENOSPC) is hit. Double duty: we
   * warn only once, AND we stop attempting new directory watches for the rest
   * of the session — once the kernel budget is exhausted every further
   * `inotify_add_watch` fails too, so trying the rest of the tree is pure
   * waste. NON-fatal (does not degrade): installed watches keep working.
   */
  private inotifyLimitWarned = false;
  /**
   * One-way latch: the reason live watching was permanently 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().
   */
  private degradedReason: string | null = null;
  /** Consecutive lock-contention retries for watcher-triggered syncs. */
  private lockRetryCount = 0;
  /** Consecutive generic (non-lock) sync failures; reset only by a clean sync. */
  private syncFailureRetryCount = 0;
  /** Test-only inert mode: started, but with no OS watcher installed. */
  private inert = false;
  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
  /**
   * True when the pending set does NOT exactly describe the change (a
   * directory removal's children are unknown from the event, #1285) — the
   * next sync must be a full scan-diff. Cleared only after a successful FULL
   * sync reconciles the tree.
   */
  private needsFullScan = false;
  /**
   * Files seen by the watcher since the last successful sync — populated on
   * every change event, cleared at the start of a sync, and re-populated by
   * events that arrive mid-sync (or restored on sync failure). Keyed by the
   * same project-relative POSIX path the rest of the codebase uses, so a
   * caller can intersect tool-response file paths against this map cheaply.
   */
  private pendingFiles = new Map<string, { firstSeenMs: number; lastSeenMs: number }>();
  /**
   * Wall-clock ms at which the in-flight sync began. Combined with
   * {@link pendingFiles}'s `lastSeenMs`, this distinguishes "still in the
   * debounce window" (lastSeen > syncStarted, sync hasn't started yet for
   * this edit) from "currently being indexed" (lastSeen <= syncStarted).
   */
  private syncStartedMs = 0;
  private syncing = false;
  private stopped = false;
  /**
   * True once the initial watch set is established. Unlike the previous
   * chokidar implementation there is no asynchronous initial "crawl" emitting
   * an `add` per existing file — `fs.watch` only reports changes from the
   * moment it's installed — so this flips to true synchronously at the end of