From ffc062707bb872b50d89756af138e629b6ce6923 Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 20 Sep 2026 13:24:11 +0200 Subject: [PATCH 1/4] docs: clear write-good.Passive hits in docs/tools/hivectl.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 5 genuine passive-voice rewrites (actor named — create-user, hivectl, the operator, claude, you the CLI user); 2 false positives left untouched — predicate-adjective necessity descriptions ('is needed', 'is required'), same category already established across this sweep. --- docs/tools/hivectl.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/tools/hivectl.md b/docs/tools/hivectl.md index 2bfbfb24..51f8f1a8 100644 --- a/docs/tools/hivectl.md +++ b/docs/tools/hivectl.md @@ -43,7 +43,7 @@ hivectl forge reconcile-config iris --verbose # include the full diff, not `create-user` persists the token to `/forge-token`. Re-running refreshes the token (idempotent — scope always matches current `TOKEN_SCOPES`). - For **non-agents** (humans): creates the account and prints the token to - stdout; no state dir is created. Re-running after account already exists + stdout, creating no state dir. Re-running after account already exists re-mints the token and prints it again — safe for password resets. - Without `--password` / `--password-stdin` `create-user` uses a random throwaway password (fine for agents — they auth by token). @@ -133,8 +133,8 @@ username updates the password hash in place. Container lifecycle shortcuts that go through the host admin socket. Requires the `hive-c0re` daemon to be running. Everything scoped to a -single agent lives under `hivectl agent ` — the name is -hoisted onto the parent command, so none of the verbs below repeat it. +single agent lives under `hivectl agent ` — `hivectl` hoists +the name onto the parent command, so none of the verbs below repeat it. ```bash hivectl list-agents # roster: every agent's status + technical state @@ -221,8 +221,8 @@ granting that group the one action `machinectl shell` needs); `choom` checks this itself and refuses up front with a message naming the requirement rather than letting systemd reject the exec later with an opaque polkit prompt. Same caveat as the socket grant: a shell opened -before you were added to `hive-admin` won't see it until you log back in -— secondary group membership applies at login. +before the operator added you to `hive-admin` won't see it until you log +back in — secondary group membership applies at login. It also needs the daemon socket, unlike the other exec-into-a-container paths: the "is this actually an agent?" pre-flight reads the agents root, @@ -241,9 +241,9 @@ through as `claude --resume ` to rejoin a prior session by its session id — the flag name deliberately matches the claude flag it maps to. (choom never uses claude's `--continue`: that's a bare flag that takes no argument and resumes the cwd's _latest_ session, that is, the -harness's; a value after it would be consumed as the first prompt, -silently poking the live harness session.) A value is required when the -flag is given. Either way choom never collides with the harness's live +harness's; claude would consume a value after it as the first prompt, +silently poking the live harness session.) A value is required when you +pass the flag. Either way choom never collides with the harness's live session in the same project dir: the harness pins its own id via `--resume`, so a blank choom session is invisible to it. The container must be running. From d4f469133690393a568242f1da8dceff82c035a9 Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 20 Sep 2026 13:25:43 +0200 Subject: [PATCH 2/4] docs: clear write-good.Passive hits in docs/swarm/ca.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 4 genuine passive-voice rewrites (actor named — you, the swarm, nix); 3 false positives left untouched — a design-constraint description with no single correct actor across both provisioning modes ('is issued with pathlen:1'), a governance/definitional statement ('who is allowed to decide'), and the already-established predicate-adjective classification ('is misconfigured'). --- docs/swarm/ca.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/swarm/ca.md b/docs/swarm/ca.md index 2f3239ec..ec21ec5d 100644 --- a/docs/swarm/ca.md +++ b/docs/swarm/ca.md @@ -52,8 +52,8 @@ and every client sees a name mismatch. It's deliberately not an assertion: this module can see what _it_ is able to issue, but not an operator-installed sub-CA in `swarm.ca.stateDir`, an external ACME setup, or a certificate delivered -by any other means. If you have arranged one, the warning is expected -and can be ignored. Otherwise either install the sub-CA, or pin the +by any other means. If you have arranged one, expect the warning and +ignore it. Otherwise either install the sub-CA, or pin the names back under the hive domain — a supported migration, since the sub-CA carries a name constraint on the _configured_ names and the swarm root carries no name constraints at all. @@ -62,8 +62,8 @@ swarm root carries no name constraints at all. The root's private key never reaches the nix store: the store is world-readable and content-addressed, so a key committed to a flake is a -key published to everyone who builds it. Only certificates are -distributed. +key published to everyone who builds it. The swarm distributes only +certificates. Each hive CA is **name-constrained** (X.509 `nameConstraints`) to that hive's own domain, so a hive CA that leaks can only mint names inside @@ -161,7 +161,7 @@ The root **certificate** is a runtime file as a _consequence_ — it lives beside the key under `swarm.ca.stateDir` — and that has a cost worth naming, because it's subtle and it bites at a distance: -> **Nothing whose trust store is assembled at build time can reference +> **Nothing whose trust store nix assembles at build time can reference > the swarm root.** The derivation reads `security.pki.certificateFiles` > inside itself; the root doesn't exist there. From 07ec84ad2d70c6637ff07eaa1497240ebc0b3b0f Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 20 Sep 2026 13:34:51 +0200 Subject: [PATCH 3/4] docs: clear write-good.Passive hits in docs/process/conventions.md --- docs/process/conventions.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/process/conventions.md b/docs/process/conventions.md index 5c69f540..4ea19ec5 100644 --- a/docs/process/conventions.md +++ b/docs/process/conventions.md @@ -185,8 +185,8 @@ it directly as a bulleted list, no follow-up fetch needed. rows, on both the agent and manager sockets alike (the manager, `ruth`, is a normal agent here, just deployed automatically with different default capabilities). `Approval` rows only appear when the calling agent is -the manager (sub-agents don't submit approvals). `Reminder` rows are -scoped to `owner == self`. +the manager (sub-agents don't submit approvals). `Reminder` rows always +carry `owner == self`. Per-variant fields: @@ -242,8 +242,8 @@ status_text, status_set_at, hive_name, swarm_name, matrix_accounts }`: currently pinned at. - `running`: whether the target's container is currently up. When `false`, the host clears `status_text` / `status_set_at` — - on-disk values from before the stop are stale snapshots and - shouldn't be shown as live status. Defaults to `true` on the + on-disk values from before the stop are stale snapshots, not + live status. Defaults to `true` on the wire (older harnesses never serialised it, and the host only knew how to ask about live containers — keeps backwards-compat with pre-running-field payloads). @@ -321,7 +321,7 @@ being able to report its status chip, and the server-side `SetStatus` handler has no tool-group check (only length validation), so gating it would only desync the `--allowedTools` list from what the host actually accepts. Revoking `meta` therefore drops `get_agent_meta` but never `set_status`. -`mark_todos_done` is here because todos are pushed to an agent independent of +`mark_todos_done` is here because producers push todos to an agent independent of whether it holds `inbox` — an agent without that group still needs a way to clear them. @@ -427,7 +427,7 @@ Anything that changes per-container state on the host should be re-applied here so a manual `↻ R3BU1LD` from the dashboard is sufficient to recover. -## Actions are factored +## Actions live in one place `approve` / `deny` / `destroy` (and the lifecycle helper) live in `actions.rs` / `hive-c0re/src/dashboard/`. The admin socket and the dashboard From 02e3fa5afc24afa8ea307d8367e9d4c984ab5ab6 Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 20 Sep 2026 13:36:22 +0200 Subject: [PATCH 4/4] docs: clear write-good.Passive hits in docs/networking/snapshot-store.md --- docs/networking/snapshot-store.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/networking/snapshot-store.md b/docs/networking/snapshot-store.md index 72adf238..d06f171b 100644 --- a/docs/networking/snapshot-store.md +++ b/docs/networking/snapshot-store.md @@ -123,8 +123,8 @@ somebody already thought of. ## Reachability The receiver is socket-activated, and the socket binds **this host's -mesh address**, never a wildcard. Both the mesh being enabled and the -address being set are assertions, not documentation --- bound to +mesh address**, never a wildcard. The module asserts two things: the +mesh is on, and the address isn't empty --- neither is just documentation: bound to `0.0.0.0` this socket is an unauthenticated remote write into agent state. @@ -161,7 +161,7 @@ The boundary is the machine. The intended deployments are: The second is worth keeping deliberately, and not only for convenience: it means every local deployment exercises the confined path. The usual failure mode for an isolated variant is that -nobody runs it day to day, so it rots and is discovered broken in +nobody runs it day to day, so it rots and turns up broken in production. ⚠️ **The assumption to keep true over time:** the store host runs @@ -175,8 +175,8 @@ Which makes it the highest-value target in the swarm by a wide margin, and means it should get the treatment a backup host gets --- restricted access, and a decision (rather than an omission) on encryption at rest. -The trap is the label: this box holds backup-grade data while not being -called a backup, so it can end up with backup-grade _exposure_ and +The trap is the label: this box holds backup-grade data while nobody +calls it a backup, so it can end up with backup-grade _exposure_ and non-backup-grade _controls_. Nobody puts a migration staging area on the access-review list.