Watcher
The watcher keeps the ledger current without a nightly full walk.
It is in skills/auwai/scripts/watch.py.
Flow
An idle watcher does not walk the tree. A native event wakes the refresh path; polling remains the fallback when no native API is available.
Backends
| Platform | Backend | How it works |
|---|---|---|
| Linux | inotify | Recursive directory watches through ctypes |
| macOS | FSEvents | File-level event stream through ctypes |
| Other | polling | Stat walk on an interval |
| Any | --backend poll |
Explicit portable fallback |
--backend auto is the default. If a native backend cannot initialize, the
watcher prints one warning and falls back to polling. An explicit
--backend inotify or --backend fsevents fails with a clear error when the
API is unavailable.
Update path
file change
-> native event or polling snapshot
-> refresh_if_stale.py
-> store.sync_changed
-> watch-state.json
auwai watch --repo PATH waits for changes.
auwai watch --repo PATH --once performs one stat scan.
auwai watch --repo PATH --max-seconds N stops after N seconds.
auwai watch --repo PATH --backend poll --interval 2 selects the fallback.
The watcher uses lib.scan_file_stats, which skips ignored and noise paths.
It compares mtime and size with the last snapshot.
When a path changes, it runs the existing incremental refresh and updates only
the changed chunk rows.
Native details
The Linux backend watches every included directory with create, delete, modify,
attrib, close-write, and move events. A new directory gets a watch immediately.
An event queue overflow, a self-delete, or a directory event uses the full
scan_once path.
The macOS backend creates a file-level FSEvents stream for the repository root
and drains it in bounded run-loop calls so --max-seconds still exits.
Absolute event paths are reduced to repository-relative paths.
The event batch is coalesced. More than 50 changed paths use the full rebuild path and a full ledger sync.
Audit
The watcher is not the only check.
auwai audit --repo PATH compares the saved file hashes with the working tree.
It reports changed, added, and removed files.
auwai audit --repo PATH --repair runs the refresh and ledger sync.
The audit is the periodic integrity check. The watcher is the fast path.
Current limits
Native events are available on Linux with inotify and macOS with FSEvents. Polling remains the fallback for other platforms. A network filesystem that does not deliver native events still needs polling. A branch switch can produce a large change set; use the audit and repair path. The watcher does not run as a service by itself.
Tests
tests/test_watch_native.py covers the inotify event path, ignored
directories, fallback selection, and the incremental ledger refresh. The
--once CLI path remains covered by tests/test_ledger.py.