Epic: FileWatch trigger — filesystem event-driven workflows

[geoffjay]

Summary

Implement a FileWatch trigger strategy that fires when files or directories matching configurable glob patterns change. Uses the notify crate for native OS filesystem events (inotify/FSEvents/kqueue) with an mtime polling fallback for environments where native watchers are unavailable.

Goals

• Evaluate and integrate the notify crate for cross-platform filesystem watching
• Implement FileWatchStrategy producing tasks on file change events
• Add mtime polling fallback mode for restricted environments
• Add FileWatch variant to TriggerConfig with path patterns, event types, and debounce
• Support glob patterns for flexible path matching (e.g., src/**/*.rs, config/*.toml)
• Wire into the strategy factory, API validation, and CLI

Design Notes

• The notify crate (v6+) provides RecommendedWatcher with native OS integration
• Debounce is essential — file saves often produce multiple events; use notify-debouncer-full or manual debounce
• Glob matching via the globset crate (already used by notify)
• Task source_id should encode the changed file path for deduplication
• Template variables should include {{file_path}}, {{event_type}}, {{file_name}}
• Polling fallback: periodically scan watched paths and compare mtime values

Acceptance Criteria

• FileWatchStrategy implements TriggerStrategy trait
• Native filesystem events via notify crate
• Mtime polling fallback with configurable interval
• Glob pattern matching for watched paths
• Debounce support to avoid duplicate triggers
• FileWatch variant added to TriggerConfig
• Template variables for file change context
• API and CLI support for creating file-watch workflows
• Unit and integration tests
• Documentation

Blocked By

• Phase 1-5 (Epic: Phase 1 — Introduce TriggerStrategy abstraction #326, Epic: Phase 2 — Cron and Delay triggers #327, Epic: Phase 4 — Webhook trigger #329, Epic: Phase 5 — Manual trigger and API dispatch #330) — all closed, foundation is ready

Stack Base

Stack on: feature/autonomous-pipeline — this epic's issues can be worked in parallel with other Phase 6 epics.

Key Files

• crates/orchestrator/src/scheduler/strategy.rs — add FileWatchStrategy
• crates/orchestrator/src/scheduler/types.rs — add FileWatch variant
• crates/orchestrator/src/scheduler/runner.rs — wire into create_strategy()
• crates/orchestrator/Cargo.toml — add notify, globset dependencies

[geoffjay]

All sub-issues implemented and PRs submitted as a stacked branch chain.

Stack Summary

• epic-804 → PR epic: FileWatch trigger — filesystem event-driven workflows (#804) #866 (rollup)
  • issue-810 → PR feat(scheduler): implement FileWatchStrategy with notify crate #867: FileWatchStrategy with notify crate (native OS events)
    • issue-811 → PR feat(scheduler): add WatchMode enum and mtime polling fallback for FileWatchStrategy #868: WatchMode enum and mtime polling fallback
      • issue-812 → PR feat(scheduler): add FileWatch TriggerConfig variant and wire into factory/API/CLI #875: FileWatch TriggerConfig variant + factory/API/CLI wiring
        • issue-813 → PR test(scheduler): add FileWatchStrategy and TriggerConfig::FileWatch tests #876: tests and documentation

Implementation Notes

The implementation was already complete. One clippy error was fixed on the issue-813 branch: the FileWatchHandle enum variants (Native and Polling) were flagged as dead_code. These fields are intentional drop-guards — the watcher stops watching when dropped and the polling task is cancelled when dropped. Fixed with #[allow(dead_code)] and an explanatory doc comment.

All 372 unit tests pass, cargo fmt and cargo clippy clean.

All PRs submitted with review-agent label.