docs: fix persistence.md paths for harness-state split

This commit is contained in:
damocles 2026-06-01 14:09:11 +02:00 committed by mara
commit 494a326029

View file

@ -64,17 +64,17 @@ Retention:
`cancelled_at_unix`, then `reap_cancelled` drops the row on `cancelled_at_unix`, then `reap_cancelled` drops the row on
the next worker pass. the next worker pass.
### `/state/hyperhive-events.sqlite` (per agent) ### `/harness/hyperhive-events.sqlite` (per agent)
Lives inside each container's bind-mounted `/state/` dir (host Lives inside each container's bind-mounted `/harness/` dir (host
path: `/var/lib/hyperhive/agents/<name>/state/hyperhive-events.sqlite`). path: `/var/lib/hyperhive/agents/<name>/harness/hyperhive-events.sqlite`).
One table: One table:
- `events(id, ts, kind, payload_json)` — every `LiveEvent` the - `events(id, ts, kind, payload_json)` — every `LiveEvent` the
harness emits during turn loop execution. harness emits during turn loop execution.
The harness writes; the host vacuums. `hive-c0re::events_vacuum` The harness writes; the host vacuums. `hive-c0re::events_vacuum`
runs hourly and sweeps every existing agent state dir, deleting runs hourly and sweeps every existing agent harness dir, deleting
rows older than 7 days. Age-only — no row cap — so a chatty turn rows older than 7 days. Age-only — no row cap — so a chatty turn
doesn't lose history sooner than a quiet one; disk pressure on a doesn't lose history sooner than a quiet one; disk pressure on a
sustained burst is the cheaper problem to have. Centralising sustained burst is the cheaper problem to have. Centralising
@ -82,12 +82,12 @@ retention on the host means a misbehaving harness can't disable
its own vacuum and agents don't need any cleanup wiring of their its own vacuum and agents don't need any cleanup wiring of their
own. own.
Path overridable via `HYPERHIVE_EVENTS_DB` (for dev / no-`/state` Path overridable via `HYPERHIVE_EVENTS_DB` (for dev / no-`/harness`
setups). On open failure the `Bus` falls back to no-store mode setups). On open failure the `Bus` falls back to no-store mode
rather than crashing the harness — events still broadcast over SSE, rather than crashing the harness — events still broadcast over SSE,
just nothing persisted. just nothing persisted.
### `/state/hyperhive-turn-stats.sqlite` (per agent) ### `/harness/hyperhive-turn-stats.sqlite` (per agent)
Per-turn analytics sink. One row per claude turn captures Per-turn analytics sink. One row per claude turn captures
identity (`model`, `wake_from`, `result_kind`), timing identity (`model`, `wake_from`, `result_kind`), timing
@ -149,7 +149,7 @@ Writes are best-effort: `append_stdout` / `append_stderr` / `finish`
log a warning on sqlite error and let the build continue. A failed log a warning on sqlite error and let the build continue. A failed
log row never blocks a rebuild. log row never blocks a rebuild.
### `/state/hyperhive-model` (per agent) ### `/harness/hyperhive-model` (per agent)
Single-line text file holding the claude model name currently Single-line text file holding the claude model name currently
selected for this agent (default `haiku` when absent). Written by selected for this agent (default `haiku` when absent). Written by
@ -169,11 +169,10 @@ Under `/var/lib/hyperhive/agents/<name>/`:
`/agents` tree bind. `/agents` tree bind.
- `claude/` — claude OAuth credentials, bind-mounted RW to - `claude/` — claude OAuth credentials, bind-mounted RW to
`/home/<name>/.claude` inside the container. `/home/<name>/.claude` inside the container.
- `state/` — durable notes, the events.sqlite db, and the - `state/` — durable notes and `hyperhive-harness.json`. Bind-mounted
turn-stats sqlite db. Bind-mounted to `/agents/<name>/state` to `/agents/<name>/state` inside the container (uniform for
inside the container (uniform for sub-agents + manager). sub-agents + manager). The `$HYPERHIVE_STATE_DIR` env var exposes
The `$HYPERHIVE_STATE_DIR` env var exposes the same path to the same path to in-container scripts.
in-container scripts.
- `harness/` — harness-internal ephemeral state; not intended for - `harness/` — harness-internal ephemeral state; not intended for
agent consumption. Bind-mounted to `/agents/<name>/harness` agent consumption. Bind-mounted to `/agents/<name>/harness`
inside the container (`$HYPERHIVE_HARNESS_DIR`). Contents: inside the container (`$HYPERHIVE_HARNESS_DIR`). Contents:
@ -184,8 +183,7 @@ Under `/var/lib/hyperhive/agents/<name>/`:
inspecting with `bash_status`. inspecting with `bash_status`.
- `hyperhive-events.sqlite` — turn-loop event log. - `hyperhive-events.sqlite` — turn-loop event log.
- `hyperhive-turn-stats.sqlite` — per-turn timing stats. - `hyperhive-turn-stats.sqlite` — per-turn timing stats.
- `hyperhive-harness.json` — consolidated flags (rate-limited, - `hyperhive-model` — single-line model name override file.
model override, etc.) written atomically on each turn.
Under `/var/lib/hyperhive/applied/<name>/` — the hive-c0re-only Under `/var/lib/hyperhive/applied/<name>/` — the hive-c0re-only
applied repo. Tracks `flake.nix` (module-only boilerplate; never applied repo. Tracks `flake.nix` (module-only boilerplate; never
@ -219,7 +217,7 @@ step would re-fire).
- `PURG3` (opt-in via the dashboard button or - `PURG3` (opt-in via the dashboard button or
`hive-c0re destroy --purge <name>`) — DESTR0Y plus wipes `hive-c0re destroy --purge <name>`) — DESTR0Y plus wipes
`/var/lib/hyperhive/{agents,applied}/<name>/`. Config history, `/var/lib/hyperhive/{agents,applied}/<name>/`. Config history,
claude creds, /state/ notes, and the events db are all gone. claude creds, /state/ notes, and the harness dir are all gone.
No undo. No undo.
The manager is non-destroyable from both paths (declarative The manager is non-destroyable from both paths (declarative