feat(watch): impl poll mode

[gaojunran]

addresses #351.

[gemini-code-assist]

Code Review

This pull request introduces configurable file-watching backends, allowing users to choose between platform-native notifications, polling, or an automatic fallback mode. This is particularly useful for environments like network filesystems where native notifications may fail. The changes include updates to the configuration schema, documentation, and a refactor of the internal watcher logic to support multiple backends simultaneously. However, a critical bug was identified in the supervisor's main watch loop: the tokio::select! block will enter a 100% CPU busy loop if any watcher backend is uninitialized, as the branches return immediately instead of pending.

[greptile-apps]

Greptile Summary

This PR implements per-daemon watch_mode configuration (native | poll | auto) backed by separate WatchFiles instances for each backend, with auto-mode falling back per-directory to polling when native registration fails. The watcher loop, settings, schema, docs, and E2E tests are all updated consistently.

Confidence Score: 5/5

Safe to merge — no correctness or security issues found; all findings are style suggestions.

Only P2 findings: submodule init ordering in mise.toml, runtime vs compile-time enforcement of the Auto-mode restriction in WatchFiles::new, and duplicated match arms. The core watcher loop logic is sound, the auto-fallback state machine handles creation failure and per-dir failure correctly, and watched_native_dirs/watched_poll_dirs are only assigned after target sets are adjusted to reflect what was actually registered.

src/watch_files.rs — WatchMode::Auto runtime error and duplicated match arms; mise.toml — submodule init placement

Important Files Changed

Filename	Overview
src/supervisor/watchers.rs	Core watcher loop refactored to support separate native/poll WatchFiles instances with auto-fallback per-dir tracking; logic is sound but complex
src/watch_files.rs	Adds WatchFilesBackend enum for native/poll dispatch; WatchMode::Auto returns a runtime error instead of compile-time enforcement; match arms are duplicated
src/pitchfork_toml.rs	Adds WatchMode enum (Native default, Poll, Auto) with serde/schemars derives; cleanly integrated into PitchforkTomlDaemon and serialization round-trip
src/daemon.rs	Adds watch_mode field to Daemon and RunOptions structs with correct Default and clone implementations
mise.toml	Adds git submodule init after cargo nextest run but before bats; functional today but could silently break if Rust tests gain submodule dependencies
tests/test_e2e_watch.rs	Adds E2E tests for poll and auto watch modes; covers PID change detection, state persistence of watch_mode, and daemon restart on file change
settings.toml	Adds watch_poll_interval setting (500ms default) and clarifies watch_interval is for config refresh, not polling scan cadence

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Loop iteration: get_all_watch_configs] --> B[Partition dirs by WatchMode]
    B --> C{required_auto_dirs?}
    C -- yes --> D{dir in auto_fallback_dirs?}
    D -- yes --> E[→ target_poll_dirs]
    D -- no --> F[→ target_native_dirs]
    C -- no --> G[Skip]
    F --> H[unwatch_removed_dirs native]
    H --> I{native_wf exists?}
    I -- no --> J[Create native WatchFiles]
    J -- ok --> K[native_wf = Some]
    J -- err --> L[Move all target_native → target_poll, clear target_native]
    K --> M[watch_new_dirs native, returns new_fallback_dirs]
    I -- yes --> M
    M --> N{fallback dirs?}
    N -- yes --> O[Remove from target_native, Add to target_poll, Record in auto_fallback_dirs]
    O --> P[unwatch_removed_dirs poll]
    L --> P
    E --> P
    P --> Q{poll_wf exists?}
    Q -- no --> R[Create poll WatchFiles]
    R -- ok --> S[poll_wf = Some]
    R -- err --> T[clear target_poll]
    S --> U[watch_new_dirs poll]
    Q -- yes --> U
    U --> V[watched_native = target_native, watched_poll = target_poll]
    T --> V
    V --> W[Prune stale auto_fallback_dirs]
    W --> X{tokio::select!}
    X -- native change --> Y[restart_for_changed_paths]
    X -- poll change --> Z[restart_for_changed_paths]
    X -- watch_interval timeout --> A

Loading

_{Reviews (11): Last reviewed commit: "feat(watch): impl poll mode" | Re-trigger Greptile}