# State Hub Infrastructure

## Docker (PostgreSQL)

```bash
# Start postgres (required for API)
make db

# Start postgres + pgadmin
make db-tools
```

The compose file is `infra/docker-compose.yml`. Copy `.env.example` to `.env` and set
`POSTGRES_PASSWORD` before starting.

---

## Periodic Repo Sync — systemd user timer

The custodian sync timer runs `consistency_check.py --remote --all` every 15
minutes, keeping workplan file state in sync with the state-hub DB automatically
(belt-and-suspenders alongside the per-repo git post-commit hooks).

The all-repo remote sweep has two built-in load guards:

- A nonblocking process lock at `/tmp/custodian-consistency-remote-all.lock`;
  if a prior sweep is still active, the next timer run exits cleanly.
- A wall-clock budget, defaulting to 300 seconds. Remaining repos are skipped
  once the budget is exhausted. Override with `--max-seconds N` or set
  `CONSISTENCY_REMOTE_ALL_MAX_SECONDS`.
- Warn-only sweeps exit 0 in `--remote --all` mode so the systemd unit only
  goes failed for hard consistency failures.

### Installed unit files

| File | Location |
|------|----------|
| `custodian-sync.service` | `~/.config/systemd/user/custodian-sync.service` |
| `custodian-sync.timer`   | `~/.config/systemd/user/custodian-sync.timer`   |

### Management commands

```bash
# Check status
systemctl --user status custodian-sync.timer
systemctl --user list-timers custodian-sync.timer

# View recent logs
journalctl --user -u custodian-sync.service -n 50

# Trigger immediately (for testing)
systemctl --user start custodian-sync.service

# Disable
systemctl --user disable --now custodian-sync.timer

# Re-enable
systemctl --user enable --now custodian-sync.timer
```

### Guard condition

The service uses `ExecStartPre` to check the API is reachable before running:
```
ExecStartPre=/usr/bin/curl -sf http://127.0.0.1:8000/state/health
```
If the API is offline, the service exits cleanly without error (the timer will retry
in 15 minutes).

### WSL2 note

systemd user mode works in WSL2 when `systemd=true` is set in `/etc/wsl.conf`.
If systemd is not available, fall back to crontab:

```bash
# Crontab fallback (run crontab -e and add):
*/15 * * * * curl -sf http://127.0.0.1:8000/state/health && cd ~/state-hub && .venv/bin/python scripts/consistency_check.py --remote --all >> /tmp/custodian-sync.log 2>&1
```

---

## Post-commit hooks

Each registered repo can have a custodian sync hook installed that triggers
`fix-consistency` automatically after every commit:

```bash
# Install into one repo
make install-hooks REPO=marki-docx

# Install into all active registered repos
make install-hooks-all

# Remove from one repo
make remove-hooks REPO=marki-docx
```

The hook is idempotent (guarded by `# custodian-sync-hook` marker) and runs
in the background so it does not block the commit.