From 78923048273fbce08f36f3f0902f3943b4d5a823 Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 3 Aug 2026 00:01:10 +0200 Subject: [PATCH] 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. --- docs/persistence.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/persistence.md b/docs/persistence.md index 871a45f8..4d138404 100644 --- a/docs/persistence.md +++ b/docs/persistence.md @@ -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 + 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)