fix: default watcher to polling on Windows to avoid ReFS BSOD

[carlos-alm]

Summary

• fs.watch with recursive: true calls NtNotifyChangeDirectoryFileEx on Windows, which can crash the ReFS driver on Dev Drives causing HYPERVISOR_ERROR (20001) blue screens
• Default to stat-based mtime polling on Windows (process.platform === 'win32'), native fs.watch remains default on macOS/Linux
• Added --poll flag to force polling on any platform, --native to force OS watchers, and --poll-interval <ms> to tune polling frequency

Test plan

• Existing watcher tests pass (watcher-incremental, watcher-rebuild)
• TypeScript compiles cleanly
• Biome lint passes
• Manual: codegraph watch on Windows uses polling by default
• Manual: codegraph watch --native on Windows uses fs.watch
• Manual: codegraph watch --poll on macOS/Linux uses polling

[greptile-apps]

Greptile Summary

This PR defaults codegraph watch to mtime-based polling on Windows to avoid NtNotifyChangeDirectoryFileEx-triggered ReFS kernel crashes (HYPERVISOR_ERROR BSOD), while preserving the native fs.watch path on macOS/Linux. Three new CLI flags (--poll, --native, --poll-interval) are wired through to watchProject, and previously flagged issues (Commander default injection, conflicting-flag silencing) have been cleanly resolved.

Confidence Score: 5/5

Safe to merge; the core fix is correct and previous P1 concerns are resolved — remaining findings are P2 style issues.

Both open findings are P2: one is an edge case for invalid CLI input (NaN poll interval), the other is a minor hidden-directory filtering inconsistency between modes. Neither affects correctness or data integrity for typical usage. Prior P1 concerns (Commander default injection, silent flag conflict) are fully addressed.

src/domain/graph/watcher.ts — collectTrackedFiles hidden-directory filtering differs from native mode

Important Files Changed

Filename	Overview
src/cli/commands/watch.ts	Adds --poll, --native, and --poll-interval CLI flags; mutual exclusion guard for conflicting flags; delegates resolved options to watchProject.
src/domain/graph/watcher.ts	Adds polling mode (mtime-based setInterval) as Windows default to avoid ReFS BSOD; introduces collectTrackedFiles for recursive file discovery; minor hidden-directory filtering inconsistency vs. native mode and no validation on user-supplied poll interval.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[codegraph watch] --> B{--poll AND --native?}
    B -- yes --> ERR[program.error: mutually exclusive]
    B -- no --> C{resolve poll mode}
    C -- "--poll" --> POLL[poll = true]
    C -- "--native" --> NATIVE[poll = false]
    C -- neither --> AUTO{process.platform === 'win32'?}
    AUTO -- yes --> POLL
    AUTO -- no --> NATIVE
    POLL --> D[Polling mode\nsetInterval every POLL_INTERVAL_MS]
    D --> E[collectTrackedFiles: sync recursive readdirSync]
    E --> F[Diff mtimes vs mtimeMap]
    F --> G[Add changed/new/deleted files to pending]
    G --> H{pending.size > 0?}
    H -- yes --> I[debounce 300ms → processPendingFiles]
    H -- no --> D
    NATIVE --> J[fs.watch recursive\nnative OS watcher]
    J --> K[shouldIgnore + isTrackedExt filter]
    K --> L[Add to pending]
    L --> M[debounce 300ms → processPendingFiles]
    I --> N[rebuildFile → journal → changeEvents]
    M --> N
    N --> O[SIGINT → cleanup + closeDb + exit]

Loading

_{Reviews (2): Last reviewed commit: "fix: add --poll/--native mutual exclusio..." | Re-trigger Greptile}

[greptile-apps]

--poll-interval default is always truthy, undefined is never passed

Because Commander.js injects the third argument ('2000') as the option's default, opts.pollInterval is always the string '2000' — it is never undefined or empty. The opts.pollInterval ? ... : undefined guard on line 21 is therefore always true, and pollInterval: 2000 is always forwarded to watchProject. This is harmless today (both defaults match), but it means the watcher's internal default can never take precedence via the CLI if it changes later. The cleanest fix is to remove the default from the Commander option definition.

[carlos-alm]

Fixed — removed the Commander.js default value from the --poll-interval option definition so opts.pollInterval is undefined when not explicitly passed by the user, allowing the watcher's internal default (2000ms) to take precedence.

[greptile-apps]

Conflicting --poll and --native flags are silently resolved

When a user passes both --poll and --native, --poll wins without any warning. A simple guard or Commander's .conflicts() API would make this explicit and prevent user confusion:

if (opts.poll && opts.native) {
  ctx.program.error('--poll and --native are mutually exclusive');
}

[carlos-alm]

Fixed — added a mutual exclusion guard that calls ctx.program.error() when both --poll and --native are passed, giving users a clear error message instead of silently picking one.

[carlos-alm]

@greptileai