Watch
0
0
Fork
You've already forked hyperhive
0

docs: state current behaviour, drop change-log wording

Refs #3902
This commit is contained in:
atlas 2026-10-02 08:22:09 +02:00 • committed by mara
commit 9545151b8d
10 changed files with 62 additions and 112 deletions

View file

@ -52,11 +52,10 @@ power-intent registry:
- `kv` — small persistent key/value store (`key PK / value`) for
host-side bookkeeping that doesn't warrant its own table.
⚠️ The `mcp__hyperhive__remind` queue is **not** here any more: it
moved to a harness-local, per-agent store as part of the
loose-ends-v2 migration — see [`/harness/` contents
⚠️ The `mcp__hyperhive__remind` queue lives in a harness-local,
per-agent store — see [`/harness/` contents
below](#state-dirs-per-agent) for where reminders (and todos)
actually live now.
live.
- `approvals` — the queue. `agent / kind (merge_config_pr | spawn |
update_meta_inputs | schedule_prompt) /
commit_ref / requested_at / status / resolved_at / note`.
@ -109,11 +108,11 @@ One table:
harness emits during turn loop execution.
<!-- vale write-good.Passive = NO -->
The harness both writes and vacuums it — this used to be a host-side
sweep, but hive-c0re runs as the unprivileged `hive-core` user under
The harness both writes and vacuums it. Cleanup runs in-container
because hive-c0re runs as the unprivileged `hive-core` user under
privsep and can't delete agent-owned files (host-side deletes hit
`PermissionDenied` on the bash-task trio and a readonly database error
here), so cleanup moved in-container. `hive-agent`'s `vacuum::run`
here). `hive-agent`'s `vacuum::run`
(`hive-agent/src/vacuum.rs`) sweeps hourly. Retention is
**type-scoped**: it deletes only the verbose `stream` rows (the raw
claude `stream-json` deltas — one per text chunk / tool use, the bulk
@ -192,10 +191,9 @@ is in-process only, so it wouldn't serialise a writer running as a
separate process; none of today's writers are.
hive-c0re reads this file on each `build_all` sweep (~10s) via
`container_view::read_harness_flags`. Falls back to the legacy individual
sentinel files (`hyperhive-rate-limited`, `hyperhive-needs-login`) if the
JSON is absent, so existing containers keep working through the transition
window before their next rebuild.
`container_view::read_harness_flags`. Falls back to the individual
sentinel files (`hyperhive-rate-limited`, `hyperhive-needs-login`) when the
JSON is absent.
### `/var/lib/hyperhive/db/build_logs.sqlite` (host)
@ -218,7 +216,7 @@ Three indices:
- `(node_id)` — added by a later migration so a build log row can be
looked up by the job-queue node it belongs to (a `hive_jobq` node is
immutable after insert, so hive-c0re records the link on the log row
instead); legacy rows predating the column keep `node_id IS NULL`.
instead); rows predating the column have `node_id IS NULL`.
Writes are best-effort: `append_stdout` / `append_stderr` / `finish`
log a warning on sqlite error and let the build continue. A failed
@ -293,22 +291,19 @@ Under `/var/lib/hyperhive/agents/<name>/`:
(`hive-agent`'s `vacuum::run`, same one that ages out `stream`
event rows above) deletes terminal task trios older than 48
hours; non-terminal (still-running) tasks are never deleted. This
used to be a host-side `hive-c0re` vacuum, moved in-container for
the same privsep-ownership reason as the events vacuum above.
sweep runs in-container, for the same privsep-ownership reason as
the events vacuum above.
- `hyperhive-state.sqlite` — consolidated loose-ends-v2 store: todos
and reminders, one small table each in a single file (in-container
daemons — `hive-bash-daemon`, `hive-matrix-daemon`,
`hive-forge-notify` — upsert keyed todos here over the harness's
in-agent socket, `HIVE_AGENT_SOCKET`; the harness merges them into
`get_loose_ends` output and clears a row on `mark_todo_done`).
Replaces three formerly separate files
(`hyperhive-todos.sqlite`, `hyperhive-reminders.sqlite`, and the
old file-based `mcp-loose-ends/` scanner before that) — a one-time
boot migration (`db_migrate::run`) folds the legacy files into this
path the first time a harness boots after the upgrade. Also backs
the `mcp__hyperhive__remind` queue, which moved from a host-side
`broker.sqlite` table to this per-agent store as part of the same
migration.
Consolidates todos and reminders into one file. A one-time boot
migration (`db_migrate::run`) folds any pre-existing files
(`hyperhive-todos.sqlite`, `hyperhive-reminders.sqlite`, the older
file-based `mcp-loose-ends/` scanner) into this path the first time
a harness boots. Also backs the `mcp__hyperhive__remind` queue.
The harness itself is also a producer, not just the socket server:
boot wiring's `spawn_todo_socket` starts `todo_server::run` (the
@ -344,9 +339,7 @@ The RW on `state` is deliberate, not an oversight: the holder recovers
other agents, which includes writing into their state (for example
seeding notes, clearing a stuck sentinel) as well as reading it.
This is the **only** cross-agent mount. Dropping the topology parent
field took with it the unconditional grant every agent used to
get over its own direct children — an agent holding no capability now
This is the **only** cross-agent mount. An agent holding no capability
sees its own dirs and nothing else.
**`harness` isn't mounted at all.** It holds that agent's own runtime
@ -395,8 +388,8 @@ Contents:
- `topology.json` — the agent roster (`["alice", "bob", "ruth"]`).
Written by `topology::reconcile` on every meta sync; read by
`topology::all_agents`, which is the set the `ManageRootAgent`
capability grants mounts over. Carried a `parent` per agent in the
legacy format; the reader still accepts that shape and keeps its keys.
capability grants mounts over. The reader also accepts a map-shaped
file carrying a `parent` per agent, and keeps its keys.
- `tool-groups.json` — per-agent MCP tool group grants
(`{ "alice": ["messaging", "inbox", "execution"] }`). Written by
`tool_groups::set_groups`; injected as `HIVE_TOOL_GROUPS` env
@ -420,9 +413,8 @@ Contents:
The root agent has the meta dir RO-mounted at `/meta/`.
The `.meta-migration-done` marker no longer exists: the
one-shot container repoint it guarded no longer exists either, since
hive-c0re renders containers onto `meta#<n>` at creation. A stale
hive-c0re renders containers onto `meta#<n>` at creation, so there is
no `.meta-migration-done` marker to guard a one-shot repoint. A stale
marker file left over from an older hive is inert and the operator can
delete it.
@ -519,7 +511,7 @@ reinstall.
The harness runs as a per-agent unix user inside the container
(`services.hyperhive.agent.user.name`, defaults to the agent's logical label so each
container has a uniquely named user). Operators with legacy root-owned
container has a uniquely named user). Operators with root-owned
state dirs need a one-time data shuffle so they don't lose their claude
session.
@ -533,8 +525,7 @@ container lifetime:
chance to chown. Also re-applies on every rebuild in case the
meta-flake's per-agent name evolves (rare).
2. **Migrate any leftover `/root/.claude` content into
`${homeDir}/.claude`** — legacy `claude` wrote to root's
empty home; the bind mount didn't exist yet. Marker
`${homeDir}/.claude`.** Marker
(`/var/lib/hive-agent-user-migrated`) guards single-shot; it's
only written once there's nothing left to migrate, so a `cp`
failure leaves it absent and the next boot retries.
@ -557,9 +548,7 @@ container lifetime:
there as the agent user. Why the mode matters:
[`boundary.md`](../trust-boundary/boundary.md#the-per-agent-socket-dir).
The activation script will eventually become unnecessary once no
operators have legacy root-owned state dirs left to migrate; drop
the body + marker check at that point.
The activation script migrates any root-owned state dir still present.
## Matrix per-agent daemon + token-arrival trigger