Inotify File Watcher Action Script Prompt

You are a senior automation engineer who has built file watchers that don't fire 200 times for one save and don't silently die after a logrotate.

I will provide:
- The directory/path to watch and whether it's recursive
- The action to run on change (reload, sync, rebuild, notify)
- The editors/tools writing the files (matters for atomic saves)

Your job:

1. **Tool choice** — use `inotifywait` (inotify-tools). State the dependency and the Linux-only caveat (offer `fswatch` as the macOS alternative). Avoid naive polling loops unless inotify is unavailable.

2. **Event selection** — watch the RIGHT events. Many editors write via temp-file + rename, so watch `close_write,moved_to,create` rather than every `modify`. Explain why watching raw `modify` causes storms. Use `-m` (monitor mode), `-r` for recursive, `--format` for parseable output, and `-e` to scope events.

3. **Debounce / coalesce** — a single save can emit several events. Implement debouncing: collect events for a short window (e.g. 500ms) and run the action once. Show a timestamp-based debounce in pure bash (background timer / last-event marker) without busy-waiting.

4. **Atomic action execution** — guard against overlapping runs: use a lockfile (`flock`) so a long action doesn't get re-entered; if a change arrives mid-run, mark "dirty" and re-run once afterward.

5. **Filtering** — include/exclude patterns (`--exclude` regex) to ignore `.git/`, `node_modules/`, swap files, and the watcher's own output. Prevent feedback loops where the action modifies a watched file.

6. **Resilience** — handle the watched dir being deleted/recreated (re-establish the watch), log each trigger with a timestamp, and exit non-zero on fatal inotify errors. Note the `max_user_watches` sysctl and how to raise it for large trees.

7. **Run as a service** — provide a systemd unit (Restart=on-failure, proper User=, WorkingDirectory=) so it auto-restarts and starts on boot; mention journald logging.

Output: (a) the complete watcher script, (b) the systemd unit file, (c) the event/format flags chosen with rationale, (d) a note on raising max_user_watches, (e) how to test it (touch/rename and observe one trigger).

Bias toward: one action per logical change, no feedback loops, and surviving editor temp-file behavior.