docs(persistence): add a For operators section
persistence.md is exhaustive schema/impl reference (sqlite table columns, systemd unit internals, marker files, btrfs subvolume mechanics) with the one thing an operator actually needs - what happens to my stuff when I destroy or purge an agent - scattered across several sections rather than answered up front. Adds a short synthesis at the top: destroy keeps everything (revivable, no re-login), purge wipes it all (no undo), approvals and questions never age out, message history vacuums acked rows at 30 days, an agent's own /state/ and claude login survive every restart/ rebuild, and the root agent auto-recreates if it's ever destroyed. Every claim checked against the existing detail further down in this same file before writing it. Part of hyperhive#1898.
This commit is contained in:
parent
601cd295e5
commit
7892304827
1 changed files with 34 additions and 0 deletions
|
|
@ -2,6 +2,40 @@
|
|||
|
||||
Where state lives, what survives what, and how it's bounded.
|
||||
|
||||
## For operators
|
||||
|
||||
The short answer to "will I lose anything": **destroying an agent
|
||||
keeps its state, purging it doesn't.**
|
||||
|
||||
- **`DESTR0Y`** (the default action) stops and removes the container
|
||||
but keeps everything on disk — config history, claude login, `/state/`
|
||||
notes, harness data. The agent shows up as a tombstone (K3PT ST4T3 on
|
||||
the C0R3 page) with a `⊕ R3V1V3` button that recreates it from the
|
||||
kept state, **no re-login needed**.
|
||||
- **`PURG3`** (opt-in, from the dashboard or `hivectl agent <name>
|
||||
destroy --purge`) is `DESTR0Y` plus wiping all of it — config
|
||||
history, claude credentials, `/state/` notes, everything. **No
|
||||
undo.** Only reach for this when you actually want the agent gone
|
||||
for good.
|
||||
|
||||
Beyond that:
|
||||
|
||||
- **Approvals and questions are kept forever** — they're audit trails,
|
||||
not caches. Nothing about them ever ages out.
|
||||
- **Broker messages**: acked ones vacuum after 30 days; anything
|
||||
undelivered or delivered-but-not-yet-acked is always kept, however
|
||||
old.
|
||||
- **An agent's own `/state/` notes and claude login survive every
|
||||
restart and rebuild** — only an explicit purge (or a hive
|
||||
`--purge`-style host operation, or the agent's own choices) touches
|
||||
them.
|
||||
- The **root/bootstrap agent is special**: it isn't really destroyable
|
||||
in practice — hive-c0re recreates it automatically on its next
|
||||
startup if it's ever gone.
|
||||
|
||||
Everything below this point is implementation detail: exact table
|
||||
schemas, file layouts, and internal migration mechanics.
|
||||
|
||||
## Sqlite databases
|
||||
|
||||
### `/var/lib/hyperhive/db/broker.sqlite` (host)
|
||||
|
|
|
|||
Loading…
Reference in a new issue