fix(watcher): degrade cleanly on watch exhaustion and prolonged lock contention (#891)

The live file watcher could stay "alive" after it had stopped being
trustworthy. EMFILE/ENFILE watch-resource exhaustion only logged (and was
silently tolerated on the Linux per-directory path), and prolonged
LockUnavailableError retried forever at the normal debounce cadence — both
left auto-sync dead while the index silently drifted stale. Especially bad
for long-running MCP/daemon sessions.

Add a one-way degrade(): on watch-resource exhaustion (any watch strategy)
or on lock contention past a bounded exponential-backoff budget, log once,
fire a new onDegraded callback, and stop. start() now returns false
consistently when the per-directory path degrades at startup — it previously
returned true on Linux, so the MCP server reported the watcher "active" when
it had degraded. Wire onDegraded into the MCP server so callers are actually
told, and expose isDegraded()/getDegradedReason().

Builds on the approach in #877 by @thismilktea. Validated on macOS
(recursive), Linux (per-directory, Docker) and Windows (recursive) — 30/30
watcher + watch-policy tests on each.

Closes #876

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

__tests__/watcher.test.ts

@@ -18,6 +18,7 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { EventEmitter } from 'events';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -25,6 +26,7 @@ import {
   FileWatcher,
   LockUnavailableError,
   __emitWatchEventForTests,
+  __setFsWatchForTests,
   type WatchOptions,
 } from '../src/sync/watcher';
 import CodeGraph from '../src/index';
@@ -69,6 +71,8 @@ describe('FileWatcher', () => {
   });
 
   afterEach(() => {
+    __setFsWatchForTests(null); // reset the injected fs.watch seam
+    vi.restoreAllMocks();
     if (fs.existsSync(testDir)) {
       fs.rmSync(testDir, { recursive: true, force: true });
     }
@@ -110,6 +114,159 @@ describe('FileWatcher', () => {
     });
   });
 
+  describe('watch-resource exhaustion (#876)', () => {
+    // These exercise the REAL fs.watch path (not inert) with an injected watch
+    // that throws / emits EMFILE, covering whichever strategy the host platform
+    // uses — recursive on macOS/Windows, per-directory on Linux. Each uses its
+    // OWN EMPTY temp dir so exactly one watch is installed and the close-count
+    // is deterministic across platforms.
+    const mkEmptyDir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-exhaust-'));
+
+    it('fails to start and degrades when fs.watch setup exhausts watch resources', () => {
+      const dir = mkEmptyDir();
+      const onDegraded = vi.fn();
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      __setFsWatchForTests(() => {
+        const err = new Error('too many open files') as NodeJS.ErrnoException;
+        err.code = 'EMFILE';
+        throw err;
+      });
+      const watcher = new FileWatcher(
+        dir,
+        vi.fn().mockResolvedValue({ filesChanged: 0, durationMs: 0 }),
+        { debounceMs: 100, onDegraded }
+      );
+
+      try {
+        // Both watch strategies must report startup exhaustion identically.
+        expect(watcher.start()).toBe(false);
+        expect(watcher.isActive()).toBe(false);
+        expect(watcher.isDegraded()).toBe(true);
+        expect(watcher.getDegradedReason()).toContain('auto-sync disabled');
+        expect(onDegraded).toHaveBeenCalledTimes(1);
+        expect(onDegraded).toHaveBeenCalledWith(expect.stringContaining('auto-sync disabled'));
+        const disableWarnings = warnSpy.mock.calls.filter(
+          (c) => typeof c[0] === 'string' && c[0].includes('File watcher disabled')
+        );
+        expect(disableWarnings).toHaveLength(1);
+      } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    it('degrades exactly once when the live watcher emits EMFILE at runtime', () => {
+      const dir = mkEmptyDir();
+      const onDegraded = vi.fn();
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const emitter = new EventEmitter();
+      let closed = 0;
+      const fakeWatcher = {
+        on: (event: string, handler: (...a: unknown[]) => void) => {
+          emitter.on(event, handler);
+          return fakeWatcher;
+        },
+        close: () => {
+          closed += 1;
+        },
+      } as unknown as fs.FSWatcher;
+      __setFsWatchForTests(() => fakeWatcher);
+      const watcher = new FileWatcher(
+        dir,
+        vi.fn().mockResolvedValue({ filesChanged: 0, durationMs: 0 }),
+        { debounceMs: 100, onDegraded }
+      );
+
+      try {
+        expect(watcher.start()).toBe(true);
+        expect(watcher.isActive()).toBe(true);
+
+        const err = new Error('too many open files') as NodeJS.ErrnoException;
+        err.code = 'EMFILE';
+        emitter.emit('error', err);
+        emitter.emit('error', err); // a second burst must NOT degrade / close again
+
+        expect(watcher.isActive()).toBe(false);
+        expect(watcher.isDegraded()).toBe(true);
+        expect(onDegraded).toHaveBeenCalledTimes(1);
+        expect(closed).toBe(1);
+        const disableWarnings = warnSpy.mock.calls.filter(
+          (c) => typeof c[0] === 'string' && c[0].includes('File watcher disabled')
+        );
+        expect(disableWarnings).toHaveLength(1);
+      } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    it('reports isDegraded false / null reason while healthy', () => {
+      const watcher = newWatcher(vi.fn().mockResolvedValue({ filesChanged: 0, durationMs: 0 }));
+      watcher.start();
+      expect(watcher.isDegraded()).toBe(false);
+      expect(watcher.getDegradedReason()).toBeNull();
+      watcher.stop();
+    });
+  });
+
+  describe('lock contention degradation (#876)', () => {
+    it('disables auto-sync after prolonged lock contention, with bounded retries', async () => {
+      const syncFn = vi.fn().mockRejectedValue(new LockUnavailableError());
+      const onSyncComplete = vi.fn();
+      const onSyncError = vi.fn();
+      const onDegraded = vi.fn();
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const watcher = newWatcher(syncFn, {
+        debounceMs: 25,
+        onSyncComplete,
+        onSyncError,
+        onDegraded,
+      });
+      watcher.start();
+      await watcher.waitUntilReady();
+      __emitWatchEventForTests(testDir, 'src/long-lock.ts');
+
+      // 5 backoff retries (25·1,2,4,8,16 ms), then degrade on the 6th attempt.
+      await waitFor(() => !watcher.isActive(), 8000, 20);
+
+      expect(syncFn.mock.calls.length).toBeGreaterThanOrEqual(6); // MAX_LOCK_RETRIES + 1
+      expect(watcher.isDegraded()).toBe(true);
+      expect(onDegraded).toHaveBeenCalledTimes(1);
+      expect(onDegraded).toHaveBeenCalledWith(expect.stringContaining('auto-sync disabled'));
+      // A held lock is neither a sync error nor a completion.
+      expect(onSyncError).not.toHaveBeenCalled();
+      expect(onSyncComplete).not.toHaveBeenCalled();
+      // Degrade stops the watcher, which clears pending state.
+      expect(watcher.getPendingFiles()).toEqual([]);
+      const disableWarnings = warnSpy.mock.calls.filter(
+        (c) => typeof c[0] === 'string' && c[0].includes('File watcher disabled')
+      );
+      expect(disableWarnings).toHaveLength(1);
+    });
+
+    it('does NOT degrade on brief contention — backoff resets after a clean sync', async () => {
+      const syncFn = vi
+        .fn()
+        .mockRejectedValueOnce(new LockUnavailableError())
+        .mockRejectedValueOnce(new LockUnavailableError())
+        .mockRejectedValueOnce(new LockUnavailableError())
+        .mockResolvedValue({ filesChanged: 1, durationMs: 5 });
+      const onDegraded = vi.fn();
+      const onSyncComplete = vi.fn();
+      const watcher = newWatcher(syncFn, { debounceMs: 25, onDegraded, onSyncComplete });
+      watcher.start();
+      await watcher.waitUntilReady();
+      __emitWatchEventForTests(testDir, 'src/brief-lock.ts');
+
+      await waitFor(() => onSyncComplete.mock.calls.length > 0, 4000, 20);
+
+      expect(onDegraded).not.toHaveBeenCalled();
+      expect(watcher.isDegraded()).toBe(false);
+      expect(watcher.isActive()).toBe(true);
+      expect(watcher.getPendingFiles().some((p) => p.path === 'src/brief-lock.ts')).toBe(false);
+
+      watcher.stop();
+    });
+  });
+
   describe('debounced sync', () => {
     it('should trigger sync after file change', async () => {
       const syncFn = vi.fn().mockResolvedValue({ filesChanged: 1, durationMs: 10 });