Background watcher

The watcher is a local background process that imports new history from the configured sources. It also refreshes indexes and runs enabled scheduled tasks such as memory backup, plan-usage sampling, and remote sync.

Configure and start it

Choose the sources to monitor.
Terminal window
```
hansard config sources edit
```
For unattended setup, pass an explicit list:
Terminal window
```
hansard config setup --watch-sources codex-cli,claude,cursor
```
Set the rolling import window if the default is not appropriate.
Terminal window
```
hansard config set imports.defaultSinceDays 90
```
Start the watcher and verify its state.
Terminal window
```
hansard watcher start
hansard watcher status
```

The rolling window bounds routine scans; it does not delete older archived sessions. Use an explicit --since all manual import for a complete backfill.

Lifecycle commands

Command	Purpose
`hansard watcher status`	Report whether the watcher is running and show its process ID.
`hansard watcher start`	Start the watcher as a detached local process.
`hansard watcher start --foreground`	Run it in the current terminal for direct diagnostics.
`hansard watcher stop`	Stop the running watcher.
`hansard watcher restart`	Stop it if necessary, then start a new process.
`hansard watcher logs`	Print watcher logs.
`hansard watcher logs --follow`	Continue streaming new log entries.

Enable a user-level login item when the watcher should start after sign-in:

hansard watcher login enable
hansard watcher login status

Remove it without changing the archive or watcher configuration:

hansard watcher login disable

How freshness works

The watcher combines filesystem events with periodic checks:

Watched source roots trigger targeted imports after nearby writes settle.
A 30-second supervisor pass schedules work, handles sources without usable filesystem events, and retries interrupted tasks.
Watched sources receive a periodic safety check even when no event arrives.
Repeated empty polling for a source slows down to avoid unnecessary work.
Failed source imports use increasing retry delays instead of looping rapidly.

Imports share one serialized lane so two provider scans cannot write overlapping archive state concurrently. If activity arrives while an import is running, it remains pending for a following pass.

Scheduled work

When configured, the same process also:

refreshes the search and session-list indexes after imports;
backs up reachable provider memories every 15 minutes;
samples signed-in Codex and Claude plan limits every 15 minutes when usage tracking is enabled;
runs remote sync at the configured interval; and
processes enabled notification work.

These jobs are independent preferences. Starting the watcher does not enable remote sync, plan tracking, or notifications by itself.

Diagnose delayed imports

Start with runtime state and the live log:

hansard status
hansard watcher status
hansard watcher logs --follow

Then compare automatic behavior with a direct source import:

hansard import --source cursor --since 30d --dry-run --explain-skips
hansard import --source cursor --since 30d

If the direct import works, restart the watcher to recreate its process and filesystem watches:

hansard watcher restart

A log entry saying tick skipped: previous tick still running means the prior supervisor pass has not finished. It usually indicates an import backlog or a slow provider scan rather than a stopped process. Follow the log to the source that is still running, then use hansard doctor to check dependencies and source availability.