feat(internal): add stat-based file change poller

[kinyoklion]

Adds a Poller to internal/filedata that detects file changes by examining modification time and size on a fixed interval. It exists for environments where filesystem notifications are unavailable or unreliable (network mounts, some containers, Kubernetes ConfigMap symlink swaps): the file-based override source will offer it as a configurable alternative or supplement to watching, and it can later back a polling option on the file data sources if wanted.

A file appearing, disappearing, or becoming unreadable all count as changes. Detection is deliberately generous — the callback feeds a Reloader.Trigger, whose debouncing and skip-unchanged handling absorb spurious detections, so the poller itself stays trivial. The known blind spot (a same-size rewrite within the filesystem's timestamp granularity) is acceptable for the same reason: the retry path covers the failure half of that window, and tests sidestep it by explicitly bumping mtimes.

Internal only; nothing consumes it yet.

SDK-2654

---

Note

Low Risk
New internal-only utility with no callers yet; behavior is isolated behind tests and designed to pair with existing Reloader debouncing.

Overview
Adds an internal/filedata Poller that watches a list of paths on a fixed interval via os.Stat (existence, mod time, size) and calls onChange when any observed state changes, including create/delete/unreadable transitions. It is meant as a fallback or complement to fsnotify for unreliable mounts/containers, with Reloader.Trigger expected to debounce and skip no-op reloads.

Lifecycle is NewPoller (immediate baseline snapshot, goroutine + ticker) and idempotent Close that waits for shutdown. Tests cover modification, file appearing/disappearing, multi-path watching, and that callbacks stop after close (tests force distinct mtimes to avoid timestamp granularity blind spots).

^{Reviewed by Cursor Bugbot for commit a693af0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a693af0. Configure here.}

[cursor]

Unicode dashes in poller comments

Low Severity

The new Poller godoc uses Unicode em dashes (—) in two phrases. Project Go comment style expects ASCII -- instead of em dashes for readability across editors and terminals.

Additional Locations (1)

• internal/filedata/poller.go#L18-L19

 

^{Triggered by learned rule: Go comments: use ASCII dashes and arrows, not Unicode}

^{Reviewed by Cursor Bugbot for commit a693af0. Configure here.}