feat(bin): wake instantly on glasses file events

[Amplify-Logic]

Intent

Instant firstmate wake on glasses events: a file-event nudger on the mailbox DB and bridge inbox must interrupt the watcher wait instead of waiting for the next poll. When data/glasses-voice-runtime/mailbox.db (including WAL/SHM siblings) or data/bridge-inbox/ changes, the watcher's terminal wait must return immediately and expire the slow-check timer so the next authenticated check sweep, including the home-local glasses pending/photo check, runs now rather than sitting until FM_CHECK_INTERVAL. Homes without those paths must keep today's sleep POLL behavior. Herdr blocked-wake must still work when glasses paths are also watched; a file event must not count as a herdr connect failure or disable the herdr fast path. The poll loop remains the permanent fail-closed backstop. A missing or unusable file-wait falls back to sleep. This is firstmate shared tracked material.

What Changed

• Add portable file-event watching for glasses mailbox database/WAL/SHM changes and bridge inbox updates.
• Interrupt the watcher’s terminal wait, expire the slow-check timer, and safely race Herdr events while preserving polling and sleep fallbacks.
• Add regression coverage for file events, fractional poll intervals, Herdr races, and fallback behavior, with accompanying architecture and operations documentation.

Risk Assessment

✅ Low: Captain, the follow-up cleanly addresses all three prior race defects while preserving the required herdr failure accounting, file-wake behavior, and polling fallback.

Testing

No pre-supplied baseline commands were available; focused and broader watcher tests passed, including mailbox/WAL/directory events, unusable-wait fallback, Herdr blocked-wake coexistence, race stderr suppression, and fast-path failure handling, while a timed manual transcript demonstrated a real bridge-inbox event returning in 0.381 seconds against a 4-second poll and homes without glasses paths retaining POLL sleep behavior.

Evidence: Timed instant-wake CLI transcript

/var/folders/1g/hctp3vpn27b1zrlsn4nsfg680000gn/T/no-mistakes-evidence/01M0Q1JRHK9GNRG2NZMN4K80YP/manual-run/home/data/bridge-inbox
CASE instant bridge-inbox wake
configured_poll_seconds=4
observed_return_seconds=0.381
last_check_exists_after_event=no
triage=[2026-08-23T12:20:02+0200] glasses file event; next cycle runs checks immediately

CASE home without glasses paths
configured_poll_seconds=0.4
observed_return_seconds=0.588
behavior=sleep POLL backstop

- Outcome: 🔧 1 issue found → auto-fixed ✅ across 2 runs (4m29s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 3 issues found → auto-fixed ✅

• 🚨 bin/fm-watch.sh:976 - Intent contradiction: the requirement says “a file event must not count as a herdr connect failure or disable the herdr fast path” and file changes “must interrupt the watcher wait.” If herdr returns 2 first, this branch kills the concurrent file waiter and apply_push_wait_result performs a blind sleep "$POLL"; a glasses event during that sleep cannot interrupt it. Preserve the failure count, but continue the remaining wait with the file-event waiter.
• 🚨 bin/fm-watch.sh:1035 - The race watchdog assumes POLL is an integer in arithmetic expansion. Existing supported usage sets FM_POLL=0.2; when glasses paths and herdr are both active, $((POLL * 20 + 40)) raises a shell arithmetic error and can terminate the watcher. Compute the deadline without integer shell arithmetic or normalize fractional values safely.
• ⚠️ bin/fm-watch.sh:1049 - The post-race catch-up signature uses second-resolution mtime and size. If herdr wins while SQLite updates a mailbox file within the same second without changing its size, the killed file waiter’s event is missed and .last-check remains unexpired. Use nanosecond metadata or preserve the file waiter’s event result before terminating it.

🔧 Fix: Preserve glasses wake race across herdr failures
✅ Re-checked - no issues remain.

🔧 **Test** - 1 issue found → auto-fixed ✅

• ⚠️ bin/fm-watch.sh:1024 - When the file and Herdr waiters finish concurrently, the losing noclobber write can emit cannot overwrite existing file to watcher stderr. The focused test reproduced this diagnostic even though the race completed correctly. Suppress the shell-level redirection error so ordinary wake races do not pollute watcher logs.
• Inspected git diff 361861c0e30c76bd5e541d3866fc53084ccc3a79..dd6d275bc7c4c0ba97c04e40fd5e3bdedb42341a against every authoritative acceptance constraint.
• bin/fm-test-run.sh tests/fm-file-eventwait.test.sh tests/fm-supervision-events.test.sh
• Manual Bash verification using the real event_wait_or_sleep: configured an 8-second poll, created a pending bridge-inbox photo after 350ms, measured the wait returning in 415ms, and verified .last-check was removed.
• git status --short confirmed testing left the worktree unchanged.

🔧 Fix: Suppress noclobber noise in watcher wake races
✅ Re-checked - no issues remain.

• bash tests/fm-file-eventwait.test.sh
• bash tests/fm-supervision-events.test.sh && bash tests/fm-watch-triage.test.sh
• Manual watcher-level check using the real event_wait_or_sleep and fm-file-eventwait.py: mutated data/bridge-inbox/ during a 4-second wait, measured return latency, verified .last-check removal and triage logging, then removed glasses paths and measured the sleep/POLL fallback.
• git status --short after testing to confirm no working-tree artifacts remained.

✅ **Document** - passed

✅ No issues found.

🔧 **Lint** - 1 issue found → auto-fixed ✅

• ⚠️ linter found issues (exit code 1)

🔧 Fix: Captain: assert fractional poll propagation in file-wait race
✅ Re-checked - no issues remain.

✅ **Push** - passed

✅ No issues found.