diff --git a/docs/agent-lifecycle/persistence.md b/docs/agent-lifecycle/persistence.md index 1824171c..df72cc73 100644 --- a/docs/agent-lifecycle/persistence.md +++ b/docs/agent-lifecycle/persistence.md @@ -20,7 +20,7 @@ keeps its state, purging it doesn't.** Beyond that: -- **Approvals are kept forever** — they're an audit trail, not a +- **hive-c0re keeps approvals forever** — they're an audit trail, not a cache. 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 @@ -89,7 +89,7 @@ Retention: rows are always kept — the harness `ack_turn`s only after a successful turn, so `requeue_inflight` can still requeue an unacked row on a crash. -- Approvals are kept indefinitely — an audit trail. `actions::destroy` +- hive-c0re keeps approvals indefinitely — an audit trail. `actions::destroy` rows stay visible to anything that queries by id. - Scheduled prompts: the worker deletes one-shot rows on fire; recurring rows live until the operator cancels them @@ -275,7 +275,7 @@ Under `/var/lib/hyperhive/agents//`: by `set_status`; cleared on explicit `set_status("")`. Read by hive-c0re and the per-agent `/api/dashboard-state` endpoint to surface the status chip on the dashboard. Absent when no status - is set. + has a value. - `hyperhive-harness.json` — rate-limited / needs-login flags read by the dashboard's async container-state fetch. See `docs/web-ui/dashboard.md::Container row`. @@ -353,7 +353,7 @@ tree anyone edits in place. Mounting it writable would leave a second path to the same file that skips the review entirely, which makes the boundary a convention rather than a permission. -⚠️ Not to be confused with the config-repo seeding hive-c0re does at +⚠️ Don't confuse it with the config-repo seeding hive-c0re does at spawn (`lifecycle::setup_proposed`): that writes the child's initial config repo as **hive-c0re, against the host path**, and `read_only` on a bind constrains writers *inside* a container only. The two are unrelated — @@ -410,10 +410,10 @@ 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 has been removed, since +one-shot container repoint it guarded no longer exists either, since hive-c0re renders containers onto `meta#` at creation. A stale -marker file left over from an older hive is inert and can be -deleted. +marker file left over from an older hive is inert and the operator can +delete it. ## Destroy vs purge @@ -439,7 +439,7 @@ On a btrfs host, `lifecycle::ensure_agent_state_subvolume` creates a brand-new a **btrfs subvolume** instead of a plain directory (progressive enhancement). This is a no-op fallback on non-btrfs hosts and for any agent whose root already exists, so -nothing is automigrated: existing agents keep their plain dirs +hive-c0re automigrates nothing: existing agents keep their plain dirs until an explicit opt-in upgrade. - **Creation:** `lifecycle::ensure_agent_state_subvolume` runs before @@ -451,8 +451,8 @@ until an explicit opt-in upgrade. succeed inside it. - **DESTR0Y keeps the subvolume** exactly like a plain dir — revival reuses it untouched. -- **PURG3 deletes it correctly:** a subvolume root can't be removed - with `rmdir`/`remove_dir_all`, so purge first calls hive-priv +- **PURG3 deletes it correctly:** `rmdir`/`remove_dir_all` can't remove + a subvolume root, so purge first calls hive-priv (`DeleteAgentSubvolume`) which `btrfs subvolume delete`s it iff it's actually a subvolume, then the normal `remove_dir_all` sweep covers plain-dir agents + the applied dir. @@ -491,7 +491,7 @@ controller serves is unaffected. `/run/hyperhive/` is tmpfs-backed (systemd `RuntimeDirectory=`) but preserved across hive-c0re restarts via `RuntimeDirectoryPreserve=yes`. Without that, every restart wipes bind sources and existing -containers can't be started. +containers can't start. - `/run/hyperhive/host.sock` — admin socket (host-side CLI). - `/run/hyperhive/agents//mcp.sock` — per-agent socket @@ -585,7 +585,7 @@ bring-up loop, so it sets the avatar for **every** account. Nix rasterizes the SVG to a 512x512 PNG at build time (`iconPng`, via librsvg) and forwards its store path as `HIVE_ICON_PNG` on the daemon unit, gated on `services.hyperhive.agent.icon != null`. No icon configured → the env is -unset → `sync_avatar` returns early and no avatar is set. +unset → `sync_avatar` returns early and sets no avatar. Idempotency is **per-account**: an `avatar-icon-hash` file in each account's matrix-sdk `state_dir`. The daemon hashes the PNG bytes and diff --git a/docs/integrations/matrix.md b/docs/integrations/matrix.md index 497a1103..1802bc4b 100644 --- a/docs/integrations/matrix.md +++ b/docs/integrations/matrix.md @@ -31,7 +31,7 @@ Two distinct hostnames: - **`serverName`** — matrix-spec `server_name`, embedded *irrevocably* in every `@user:` and `!room:` - identifier minted on this homeserver. can't be changed later + identifier minted on this homeserver. You can't change it later without abandoning every account and chat history. Defaults to the bare `services.hyperhive.swarm.domain`; clients autodiscover the actual API endpoint via the `.well-known/matrix/{client,server}` @@ -73,7 +73,7 @@ A rebuild on a host that already has a homeserver prints a `hive-matrix: WARNING — … serverName is unset` line when this is missing, naming the value it's about to default to. That warning is why this section exists; it never fails the rebuild, so it's on you to act on it -before the ids are minted. +before the homeserver mints the ids. ## Default-closed firewall @@ -92,8 +92,8 @@ delegation (the latter lives in `gateway.md::Discovery flow`). ## Provisioning flow (appservice) -Registration is closed. Accounts are created by the hive's own -**appservice**: hive-c0re holds the appservice token, agents never see +Registration is closed. The hive's own **appservice** creates accounts: +hive-c0re holds the appservice token, agents never see it, and an agent only ever receives its own `access_token`. The appservice has no URL (`url: null` in its registration), so the @@ -108,7 +108,7 @@ a token. spec-required `hs_token` sibling, mode `0600 root:root`, then renders the registration to `/var/lib/hyperhive/matrix-appservice/hyperhive.yaml` (also `0600`). - The tokens are minted only when missing; the registration is + hive-c0re mints the tokens only when missing; the registration is re-rendered every time, because the token file can be overwritten in place by the swarm secret store and a registration naming a stale token authenticates nobody. Runs at activation time, before any @@ -156,12 +156,12 @@ and likewise before the listener — so a fresh hive has a joined, power-level-100 admin on its first boot. This replaces a dependency on being the first account ever registered, -which was fragile in both directions: an appservice-created account is -excluded from that automatic grant by design, and on a homeserver that +which was fragile in both directions: the design excludes an +appservice-created account from that automatic grant, and on a homeserver that already had users the rule never fired at all. -Promotion can't be bootstrapped over the API, and that's upstream's -design rather than a gap: tuwunel only treats an admin-room message as a +Tuwunel doesn't support bootstrapping promotion over the API, and +that's upstream's design rather than a gap: it only treats an admin-room message as a command when its sender is already an admin. `admin_execute` is the one lever with no sender to check. hive-c0re re-checks the result on every sweep by reading the admin account's own joined-rooms list; if the rights @@ -179,14 +179,14 @@ restarts, so the first boot after the switch already has both halves. device that minted it; removing the registration token touches no device, no account and no session. `login_with_password` stays on, so the password fallback is still there too. -- **Existing token files are honoured.** The per-agent sweep skips any - agent that already has a `matrix-token`, so no account is re-registered - and no session is displaced. +- **The per-agent sweep honours existing token files.** It skips any + agent that already has a `matrix-token`, so it re-registers no account + and displaces no session. - **The admin account is already admin** on such a hive (it won the first-user grant when the hive was new), so the startup promotion is a no-op — upstream's `make_user_admin` short-circuits when the user is already joined at power level 100. -- **`/var/lib/hyperhive/matrix-register-token` is left on disk**, read by +- **`/var/lib/hyperhive/matrix-register-token` stays on disk**, read by nothing. Delete it or leave it; neither does any harm. - **`registrationTokenFile` is a removed option.** A config that still sets it fails to evaluate with a message naming the appservice — a hive @@ -209,7 +209,7 @@ Initial rollout settings: until you list peers. - `allow_registration = false`. tuwunel checks this flag only for requests that arrive **without** an appservice token, so hive-c0re - provisions exactly as before and everyone else is refused. It's not a + provisions exactly as before and tuwunel refuses everyone else. It's not a hardening afterthought: with no registration token configured, `allow_registration = true` makes tuwunel refuse to start unless `yes_i_am_very_very_sure_…_open_registration_…` is also set. @@ -272,7 +272,7 @@ services.hyperhive.swarm.matrix = { **`trustedServers`** (default `[]`) — list of peer homeserver names whose signing keys tuwunel will fetch and trust. Federation is enabled at the protocol level from first boot (`allow_federation = true`) but -no remote homeserver is trusted until listed here. For a closed +tuwunel trusts no remote homeserver until you list it here. For a closed single-hive deployment the default empty list is correct — add peer hive domains here when connecting hives into a swarm (see [`docs/swarm/`](../swarm/README.md)).