> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # NIIA Watcher > Persist ordered filesystem evidence and trigger retry-safe NIIA dirty indexing, including a Git-ref freshness backstop. `monolex-niia-watcher` is the cross-platform filesystem daemon behind NIIA's event freshness path. It persists accepted file events in order, reloads effective Monogram and Monomento policies when their registry state changes, and triggers `niia index --dirty` only after a settled batch. *Published contract: `monolex-niia-watcher 0.4.0`, OpenCLIs build `2026-07-12-192934`. The executing binary, registry, and public CDN metadata agree on this release.* ## Quick Start ```bash theme={null} openclis install monolex-niia-watcher monolex-niia-watcher --version monolex-niia-watcher # foreground diagnosis niia watcher status # durable event + heartbeat summary niia watcher help # lifecycle/path/filter controls ``` Normal lifecycle ownership belongs to the Monolex/OpenCLIs service bootstrap. Run the watcher directly only when foreground logs are needed for diagnosis. ## Complete Command Reference | Invocation | What it does | Effect | | -------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------- | | `monolex-niia-watcher` | Starts the long-running watcher daemon. | Subscribes to validated roots, persists event batches, and drives dirty indexing. | | `monolex-niia-watcher --help` | Prints the public CLI contract without starting the daemon. | Read-only. | | `monolex-niia-watcher --version` | Prints the installed payload version. | Read-only. | Lifecycle commands intentionally live in the service owner rather than this binary. The watcher's small argv surface prevents a second configuration and supervision plane. ## NIIA Control Surface The daemon binary owns only foreground execution. NIIA owns the operator surface around it: | Command | Purpose | Effect | | | ------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------- | | `niia watcher start` | Starts the installed watcher through NIIA's lifecycle path. | Process mutation. | | | `niia watcher stop` | Stops the pid-file owner. | Process mutation. | | | `niia watcher status` | Shows event count, watch paths, exclusions, latest event, and newest worker heartbeat. | Read-only. | | | `niia watcher paths` | Lists watched roots, depth, and active state. | Read-only. | | | `niia watcher add ` | Adds a canonical watch root at default depth 5. | Database configuration write. | | | `niia watcher remove ` | Removes a configured root. | Database configuration write. | | | `niia watcher activate ` | Re-enables a configured root. | Database configuration write. | | | `niia watcher deactivate ` | Disables a root without deleting it. | Database configuration write. | | | \`niia watcher exclude PATTERN \[extension | folder]\` | Adds a user exclusion; type defaults to `extension`. | Database configuration write. | | `niia watcher exclusions` | Lists user exclusions. | Read-only. | | | `niia watcher stats` | Aggregates persisted events by event type. | Read-only. | | `niia watcher --help` shows the compact Clap entry point, while `niia watcher help` prints the full action list above. ## Freshness Contract ```text theme={null} filesystem notifications ↓ 500 ms ordered batch policy reload + filtering + durable event rows ↓ 30 s quiet window niia index --dirty ↓ cursor advances or retryable result ``` Only one in-process trigger runs at once, and NIIA's cross-process lock prevents overlap with manual or service runs. Deferred, failed, spawn-error, and hard-timeout results retry with exponential backoff capped at five minutes. New file events reset the backoff and arm a new settle window. Because `.git` is excluded from native filesystem events, startup and a 60-second periodic probe arm the same dirty driver. NIIA fingerprints the refs and returns a no-op when nothing changed. This is how ref-only changes remain fresh without watching Git internals. ## Environment Controls | Variable | Default | Purpose | | ----------------------------------- | ------: | ------------------------------------------------------------------------- | | `NIIA_WATCHER_DIRTY_DRIVER` | enabled | Set `off` or `0` to disable NIIA dirty triggers. | | `NIIA_WATCHER_DIRTY_SETTLE_SECS` | `30` | Quiet interval after the most recent accepted event. | | `NIIA_WATCHER_DIRTY_PROBE_SECS` | `60` | Git-ref backstop interval; `off` or `0` disables it. | | `NIIA_WATCHER_DIRTY_RETRY_MAX_SECS` | `300` | Maximum exponential retry delay. | | `NIIA_WATCHER_DIRTY_TIMEOUT_SECS` | `3600` | Hard NIIA run deadline before process-tree termination, drain, and retry. | The daemon resolves `~/.openclis/bin/niia` (or `niia.exe` on Windows) before falling back to `PATH`. Registry policies can refine filtering only inside roots that already have filesystem subscriptions; they never create a new subscription implicitly. ## Durable Verification ```bash theme={null} monolex-niia-watcher --version monolex-niia-watcher --help niia watcher status niia watcher paths niia index --dirty ``` A complete live check proves all four layers: the lifecycle/control owner, a fresh one-minute `worker_status.last_ping` heartbeat, a persisted `file_events` row from a real project edit, and the matching `index_cursors` advance. `niia watcher status` intentionally reports the row with the newest `last_ping`; it does not prove that no older duplicate process exists. Pair it with the OS service status or process listing and require one expected owner. A running process alone is insufficient. During this audit `niia watcher status` reported five active roots, a current file event, and the OpenCLIs watcher PID with a 25-second heartbeat. That is a point-in-time proof of the newest owner row, not a substitute for the duplicate owner check above. ## Release Platforms | Artifact | Public binary | Runtime boundary | | ----------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------- | | `darwin-aarch64` | `monolex-niia-watcher` | Native notifications and Unix process-group cleanup; strict code-signature verification passed. | | `linux-x86_64`, `linux-aarch64` | `monolex-niia-watcher` | Native notifications and Unix process-group cleanup. | | `windows-x86_64`, `windows-aarch64` | `monolex-niia-watcher.exe` | Resolves `niia.exe`; hard timeout cleanup uses the Windows process-tree ownership path. | ## Relationships | Tool | Ownership | | ------------------------------- | -------------------------------------------------------------------------------- | | [NIIA](/ai-clis/niia) | Owns dirty indexing, locks, cursors, unified status, and service bootstrap | | [Monogram](/ai-clis/monogram) | Supplies indexed-code roots and add-root policies consumed by the watcher | | [Monomento](/ai-clis/monomento) | Supplies document-project policies and custom extensions consumed by the watcher | | [MonoFlow](/ai-clis/monoflow) | Reads temporal evidence after the watcher and source owners have persisted it |