MCP watch mode needs resource guardrails and safer defaults on macOS

[AriaShishegaran]

Summary

CodeGraph currently requires users to discover OS-level file descriptor / watcher exhaustion and manually mitigate it by killing daemons or adding --no-watch. That is too fragile for normal agent workflows where a developer may have many MCP clients and many project roots open at once.

This is a guardrail/defaults issue related to, but distinct from, the raw FD leak reports in #496 / #555 and the stale-process accumulation report in #579.

Environment where observed

• macOS 26.5 / Darwin 25.5.0, Apple Silicon arm64
• CodeGraph 0.9.8 plus older 0.9.7 daemons from prior sessions
• kern.maxfiles: 491520
• kern.maxfilesperproc: 245760
• Several MCP-capable agent clients used across multiple project roots

What happened

Even after moving away from a huge root-level workspace index to per-project indexes, CodeGraph still created enough watcher / open-file pressure that daemon logs showed system-level ENFILE: file table overflow errors.

Sanitized live snapshot:

before cleanup:
  kern.num_files: 15771
  kern.maxfiles: 491520

project daemon FD counts:
  codegraph serve --mcp --path <large-go-project>:        2901 numeric FDs
  codegraph serve --mcp --path <medium-flutter-project>:   599 numeric FDs
  codegraph serve --mcp --path <small-swift-project>:       96 numeric FDs

The largest daemon was almost entirely regular-file descriptors:

REG      2887
PIPE        4
DIR         3
KQUEUE      3
CHR         2
unix        2
numeric_fds 2901

The daemon log contained repeated errors like:

[CodeGraph] File watcher error {
  error: "Error: ENFILE: file table overflow, realpath '<workspace>/internal/...'"
}
[CodeGraph] File watcher error {
  error: "Error: ENFILE: file table overflow, lstat '<workspace>/internal/.../client_test.go'"
}
[CodeGraph] File watcher error {
  error: "Error: ENFILE: file table overflow, scandir '<workspace>/internal/...'"
}

Killing stale/high-FD project daemons released pressure immediately:

after killing two stale project daemons:
  kern.num_files: 12164

after killing the remaining project watcher:
  kern.num_files: 12042

--no-watch was an effective local mitigation:

codegraph serve --mcp --no-watch

Why this needs product-level guardrails

This should not require manual OS debugging. On macOS, exhausting the global file table causes failures in unrelated processes. The user sees shells, browsers, IDEs, Docker, and background services behaving badly, not a clear CodeGraph error.

Also, powerful hardware does not make the failure mode acceptable. A machine with a high global FD limit still experienced CodeGraph-originated ENFILE logs. Developers using agents often have many repos and sessions active; CodeGraph should degrade gracefully under that workload.

Suggested behavior

I think CodeGraph should fail safe by default:

1. Budget-aware watcher startup

   • Estimate files/directories to watch before enabling the watcher.
   • Compare against OS limits (kern.maxfiles, kern.maxfilesperproc, current kern.num_files on macOS; inotify limits on Linux).
   • If the projected watcher/indexer cost is risky, refuse watch mode or auto-fallback to --no-watch with a clear warning.

2. FD telemetry in status/debug output

   • Add something like codegraph status --resources or codegraph debug resources.
   • Report current process FD count, watcher count if available, path root, client count, idle-timeout state, and OS budget percentage.

3. Default MCP install should be conservative

   • For stdio MCP installs on macOS, consider installing args = ["serve", "--mcp", "--no-watch"] until watcher FD usage is bounded.
   • Or ask during codegraph install: "Enable live watcher? This can be expensive on large workspaces."

4. Release resources when idle

   • If clients=0, close watchers and open file handles.
   • Rehydrate watcher state only when a client attaches or a query requires sync.

5. Hard cap and warning

   • A daemon should never be allowed to hold tens of thousands of file descriptors without a loud warning.
   • A configurable cap such as CODEGRAPH_MAX_OPEN_FDS / --max-open-fds would be better than letting the OS global table fail.

Expected outcome

Users who work across many projects should be able to install CodeGraph once and not periodically debug global OS file-table exhaustion. If watch mode is too expensive for a workspace, CodeGraph should detect that, explain it, and keep the index/query path usable in no-watch/manual-sync mode.

Related:

• macOS: indexer leaks ~64k open file descriptors per daemon (opens excluded files, never closes) → exhausts kern.maxfiles, system-wide "too many open files" #496
• macOS: codegraph serve opens excessive file descriptors and causes system instability #555
• Watch-budget exhaustion: ~90k inotify watches per instance + stale processes accumulate across MCP-client sessions #579

[AriaShishegaran]

I did a quick source pass on current main (8629f7a) and found a few code-level details that line up with the observed behavior.

Relevant pointers:

• src/sync/watch-policy.ts:82-98: watchDisabledReason() currently disables live watching only for CODEGRAPH_NO_WATCH=1 and WSL2 /mnt/* unless forced. There is no macOS resource-budget gate.
• src/mcp/engine.ts:184-229: startWatching() starts the watcher whenever opts.watch is true and watchDisabledReason() returns null. It logs active/unavailable, but does not inspect current FD pressure or projected watch cost.
• src/sync/watcher.ts:176-181: watch mode calls chokidar.watch(this.projectRoot, { ignored: ... }). Even with ignore pruning, initial traversal can still be large enough to create system pressure on macOS.
• src/mcp/daemon.ts:160-163 and 232-249: detached daemons arm a 5 minute idle timer, but the engine/watcher stay alive until full daemon stop. If a daemon is idle with clients=0, it can still hold watcher/file resources for the whole idle window.
• src/mcp/daemon.ts:13-18 documents that the detached daemon intentionally outlives individual clients. That design is good for sharing, but it also means the daemon itself needs resource limits because the user no longer has a simple parent/child lifetime to reason about.
• src/sync/watcher.ts:279-281: this.watcher.close() is called without awaiting the returned Promise from chokidar. If shutdown is immediately followed by process.exit(0) via Daemon.stop(), cleanup may rely on process teardown rather than an awaited close. This is probably not the primary FD leak, but it is worth tightening while working in this area.

Concrete patch directions that seem likely to help:

1. Extend watchDisabledReason() or add a sibling resource policy for macOS:
   • read kern.maxfiles, kern.maxfilesperproc, and kern.num_files via sysctl or a best-effort helper;
   • estimate project watch/index cost before starting chokidar;
   • auto-disable watch with a clear reason when the projected budget is risky.
2. When Daemon.clients.size drops to zero, call an engine method that stops only live watching while keeping the DB/query engine available, then restart watching on the next client attach if policy still allows it.
3. Make watcher shutdown async all the way up (FileWatcher.stop(): Promise<void>, CodeGraph.close(): Promise<void> or a separate closeAsync()), so graceful daemon shutdown actually waits for chokidar to release native resources.
4. Add a status/debug resources path that reports PID, project root, clients, watcher active/inactive, current process FD count, and OS budget. That would have made this incident obvious without running lsof manually.

The current code has good hooks for this: watch-policy.ts already centralizes the on/off decision, and daemon refcounting already knows when the last client disconnects.