vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs/persistence.md: scrub self-ref cookies (#719 batch 4)

Browse source
This commit is contained in:
iris 2026-05-31 15:42:14 +02:00 • committed by mara
commit bd6b48a883
1 changed files with 22 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

46
docs/persistence.md
View file

@ -32,8 +32,8 @@ header/targets split:
Q&A (`HelperEvent::QuestionAsked` pushed into target's inbox, Q&A (`HelperEvent::QuestionAsked` pushed into target's inbox,
answered via `Answer` request). Migrated via `ALTER TABLE ADD answered via `Answer` request). Migrated via `ALTER TABLE ADD
COLUMN` against `pragma_table_info`. COLUMN` against `pragma_table_info`.
- `scheduled_prompts` — recurring + one-shot prompt queue - `scheduled_prompts` — recurring + one-shot prompt queue.
(closes #444). `owner / body / interval_seconds (NULL = one-shot) / `owner / body / interval_seconds (NULL = one-shot) /
next_fire_at_unix / created_at_unix / source ("operator" or next_fire_at_unix / created_at_unix / source ("operator" or
"approval:<id>") / cancelled_at_unix / description`. `owner` "approval:<id>") / cancelled_at_unix / description`. `owner`
drives cancel-permission checks (operator vs the submitting drives cancel-permission checks (operator vs the submitting
@ -101,9 +101,8 @@ Bin-loop helpers `build_row` + `record` land each row at
`turn_end`; writes are best-effort, a sqlite hiccup logs + lets `turn_end`; writes are best-effort, a sqlite hiccup logs + lets
the turn loop continue. the turn loop continue.
No host-side vacuum yet — tracked as forge issue No host-side vacuum yet — tracked separately. Target retention
[#10](http://localhost:3000/hyperhive/hyperhive/issues/10) ~90 days, age-only sweep like events_vacuum.
(target retention ~90 days, age-only sweep like events_vacuum).
### `/state/hyperhive-rate-limited` (per agent) ### `/state/hyperhive-rate-limited` (per agent)
@ -136,13 +135,12 @@ Under `/var/lib/hyperhive/agents/<name>/`:
precise changes from the manager; RW into the manager via the precise changes from the manager; RW into the manager via the
`/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 (post-#658 — was `/home/<name>/.claude` inside the container.
`/root/.claude` pre-#658 when every harness ran as root).
- `state/` — durable notes, the events.sqlite db, and the - `state/` — durable notes, the events.sqlite db, and the
turn-stats sqlite db. Bind-mounted to `/agents/<name>/state` turn-stats sqlite db. Bind-mounted to `/agents/<name>/state`
inside the container (uniform for sub-agents + manager inside the container (uniform for sub-agents + manager).
post-#604). The `$HYPERHIVE_STATE_DIR` env var exposes the The `$HYPERHIVE_STATE_DIR` env var exposes the same path to
same path to in-container scripts. in-container scripts.
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
@ -199,13 +197,13 @@ task before rebinding — idempotent so a hive-c0re restart followed
by `rebuild alice` recreates the agent's socket without a clean by `rebuild alice` recreates the agent's socket without a clean
reinstall. reinstall.
## First-boot agent-user migration (post-#658) ## First-boot agent-user migration
Pre-#658 the harness ran as root inside the container. #658 dropped The harness runs as a per-agent unix user inside the container
to a per-agent unix user (`hyperhive.user.name`, defaults to the (`hyperhive.user.name`, defaults to the agent's logical label so each
agent's logical label so each container has a uniquely-named user). container has a uniquely-named user). Operators with legacy root-owned
The transition needs a one-time data shuffle so existing operators state dirs need a one-time data shuffle so they don't lose their claude
who deployed pre-#658 don't lose their claude session. session.
`system.activationScripts.hive-agent-user-migrate` (in `system.activationScripts.hive-agent-user-migrate` (in
`nix/templates/harness-base.nix`) runs on every activation, `nix/templates/harness-base.nix`) runs on every activation,
@ -217,25 +215,25 @@ container lifetime:
chance to chown. Also re-applies on every rebuild in case the chance to chown. Also re-applies on every rebuild in case the
meta-flake's per-agent name evolves (rare). meta-flake's per-agent name evolves (rare).
2. **Migrate any leftover `/root/.claude` content into 2. **Migrate any leftover `/root/.claude` content into
`${homeDir}/.claude`** — pre-#658 `claude` wrote to root's `${homeDir}/.claude`** — legacy `claude` wrote to root's
empty home; the bind mount didn't exist yet. Marker empty home; the bind mount didn't exist yet. Marker
(`/var/lib/hive-agent-user-migrated`) guards single-shot. (`/var/lib/hive-agent-user-migrated`) guards single-shot.
`cp -an` (no-clobber) so any pre-existing files at the new `cp -an` (no-clobber) so any pre-existing files at the new
location win — never blow over data already there. location win — never blow over data already there.
3. **Chown the bind-mounted state dir** (`/agents/*/state`) 3. **Chown the bind-mounted state dir** (`/agents/*/state`)
recursively so the new agent user can read/write it. Wildcard recursively so the agent user can read/write it. Wildcard
matches the single agent that container sees; `-h` skips matches the single agent that container sees; `-h` skips
symlinks the agent might have planted. symlinks the agent might have planted.
4. **Chown the `~/.claude/` bind-mount** recursively. Pre-#658 4. **Chown the `~/.claude/` bind-mount** recursively. Legacy
`claude` wrote `.credentials.json` 0600 root:root; post-#658 `claude` wrote `.credentials.json` 0600 root:root; the
the harness reads `~/.claude/` as the agent user to decide current harness reads `~/.claude/` as the agent user to decide
Online vs NeedsLogin in `login::has_session`. Without the Online vs NeedsLogin in `login::has_session`. Without the
chown the existing credentials get silently treated as "no chown the existing credentials get silently treated as "no
session" and the operator re-prompts every boot. session" and the operator re-prompts every boot.
The activation script will eventually become unnecessary once no The activation script will eventually become unnecessary once no
operators have pre-#658 state dirs left to migrate; drop the body operators have legacy root-owned state dirs left to migrate; drop
+ marker check at that point. the body + marker check at that point.
## Matrix per-agent daemon + token-arrival trigger ## Matrix per-agent daemon + token-arrival trigger
@ -260,4 +258,4 @@ first time it ran and the MCP would have no backend until the next
restart. The `.path` unit makes the appearance of the token re-fire restart. The `.path` unit makes the appearance of the token re-fire
the service so the daemon comes alive in the same boot cycle as the service so the daemon comes alive in the same boot cycle as
provisioning. `matrix-avatar-sync.path` uses the same pattern for provisioning. `matrix-avatar-sync.path` uses the same pattern for
the icon-upload oneshot (#571). the icon-upload oneshot.