[watcher] add VaultWatcher, scan_vault, and self-write suppression

[Obsidian68]

Summary

• VaultWatcher class — watches ENGRAM_VAULT_PATH/engram/ recursively via watchfiles.awatch, handles file create/modify/delete on .md files, skips non-.md and unparseable files, self-write suppression via thread-safe register_write/unregister_write with threading.Lock
• scan_vault() function — incremental mtime-based vault scan, falls back to full reindex() on first start (when last_indexed is None), updates state file with current timestamp after scan
• VaultStore watcher integration — set_watcher() method, _atomic_write() registers self-writes with 2 * watcher_debounce_ms delay
• App lifecycle — scan_vault() runs before watcher starts, VaultWatcher created and started as background task if watcher_enabled, shutdown handler stops watcher
• Health endpoint — "watcher" component: "healthy" | "disabled" | "unhealthy", disabled components excluded from overall health status
• CLI state file — _write_state() preserves existing last_indexed across restarts, _remove_state() preserves last_indexed instead of deleting the file
• Config stubs — watcher_enabled: bool = True, watcher_debounce_ms: int = 2000 (stubs; feat/v1.3-config provides real fields)
• Path-to-memory-ID tracking — _path_to_memory_id dict in VaultWatcher ensures correct index key for delete events when filename stem differs from frontmatter id
• Version bump — 1.2.0 → 1.3.0

Known limitations

• Watcher uses deprecated FastAPI on_event lifecycle hooks (lifespan refactor is future scope)
• Blocking sync I/O in async watcher loop (file reads in _handle_add_or_update); acceptable for v1.3
• Config fields are stubs — real implementation comes from feat/v1.3-config

Test plan

• 311 tests pass, 90.37% coverage (≥90% threshold)
• Ruff lint and format clean
• Zero TODOs, FIXMEs, HACKs, XXXs
• Zero dead code
• Zero hardcoded secrets
• Version consistency: init.py 1.3.0, health.py 1.3.0, pyproject.toml 1.3.0
• VaultWatcher self-write suppression: register/unregister/is_self_write thread-safe
• scan_vault incremental reindex with mtime comparison
• scan_vault full reindex fallback when no last_indexed
• State file last_indexed preservation across restarts
• Health endpoint watcher component: healthy/disabled/unhealthy
• Config defaults and env overrides for watcher_enabled/watcher_debounce_ms

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a67188bcc8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep runtime keys when preserving state file

_remove_state() now rewrites the state file to only {"last_indexed": ...} when that field exists, but start() and stop() still unconditionally read state["pid"]. After any normal shutdown that preserves last_indexed, the next CLI invocation can crash with KeyError: 'pid' instead of starting/stopping cleanly, effectively blocking restart unless users manually delete the state file.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Delete indexed memory by tracked ID after restart

_handle_delete() falls back to path.stem when _path_to_memory_id has no entry, but that map is only filled by _handle_add_or_update() and is empty on process start. If an existing file was indexed under a different frontmatter id (supported by this feature), deleting it before a modify/add event in this process removes the wrong key and leaves stale rows in the search index until a full reindex.

Useful? React with 👍 / 👎.