Method start

src/sync/watcher.ts:327–391

* Start watching for file changes. * Returns true if watching started successfully, false otherwise.

()

   * Returns true if watching started successfully, false otherwise.
   */
  start(): boolean {
    if (this.recursiveWatcher || this.dirWatchers.size > 0 || this.inert) return true; // Already watching
    this.stopped = false;
    this.degradedReason = null;
    this.lockRetryCount = 0;

    // 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
    // there; callers fall back to manual `codegraph sync` or git sync hooks.
    const disabledReason = watchDisabledReason(this.projectRoot);
    if (disabledReason) {
      logDebug('File watcher disabled', { reason: disabledReason, projectRoot: this.projectRoot });
      return false;
    }

    // Reuse the indexer's ignore set so the watcher and indexer agree on scope.
    this.ignoreMatcher = buildScopeIgnore(this.projectRoot);

    try {
      if (this.inertForTests) {
        // Test-only: install no OS watcher; the seam drives events instead.
        this.inert = true;
      } else if (supportsRecursiveWatch()) {
        this.startRecursive();
      } else {
        this.startPerDirectory();
      }

      // The per-directory (Linux) path catches watch-resource exhaustion inside
      // watchTree 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) return false;

      // No async crawl to wait on: as soon as the watch set is installed we
      // have a clean baseline (pendingFiles is only populated by post-start
      // events). Clear defensively and flip ready.
      this.pendingFiles.clear();
      this.ready = true;
      for (const cb of this.readyWaiters) cb();
      this.readyWaiters.length = 0;
      if (IS_TEST_RUNTIME) liveWatchersForTests.set(this.projectRoot, this);

      logDebug('File watcher started', {
        projectRoot: this.projectRoot,
        debounceMs: this.debounceMs,
        mode: this.inertForTests ? 'inert' : supportsRecursiveWatch() ? 'recursive' : 'per-directory',
        watchedDirs: this.dirWatchers.size || undefined,
      });
      return true;
    } catch (err) {
      // Watcher setup failed. Watch-resource exhaustion (EMFILE/ENFILE on the
      // recursive path) is terminal — degrade cleanly with one actionable
      // warning instead of leaving a half-broken watcher. Everything else
      // (permission denied, missing directory) keeps the prior quiet-stop.
      if (isWatchResourceExhaustion(err)) {
        this.degrade(EXHAUSTION_REASON, { error: String(err) });