Function watchDisabledReason

src/sync/watch-policy.ts:82–98

(projectRoot: string, probe: WatchProbe = {})

 *  3. WSL2 + `/mnt/*` drive     → off  (recursive fs.watch is too slow; #199)
 */
export function watchDisabledReason(projectRoot: string, probe: WatchProbe = {}): string | null {
  const env = probe.env ?? process.env;

  if (env.CODEGRAPH_NO_WATCH === '1') {
    return 'CODEGRAPH_NO_WATCH=1 is set';
  }
  if (env.CODEGRAPH_FORCE_WATCH === '1') {
    return null;
  }

  const isWsl = probe.isWsl ?? detectWsl();
  if (isWsl && isWindowsDriveMount(projectRoot)) {
    return 'project is on a WSL2 /mnt/ drive, where recursive fs.watch is too slow to be reliable';
  }

  return null;
}

/** Test-only: reset the cached WSL detection. */
export function __resetWslCacheForTests(): void {