diff --git a/docs/agent-lifecycle/approvals.md b/docs/agent-lifecycle/approvals.md index cb44e3ce..c0cebf14 100644 --- a/docs/agent-lifecycle/approvals.md +++ b/docs/agent-lifecycle/approvals.md @@ -68,7 +68,7 @@ request. config, not the tree to edit: authoring in place there produces no PR and no approval. (It is currently mounted read-write, which is a defect tracked separately, not an authoring path.) - Branch protection (push/merge whitelist = `core`, approvals whitelist + Branch protection (push/merge allowlist = `core`, approvals allowlist = operator team; see "Forge mirror" and #1787) makes the agent a write collaborator that **cannot merge its own config PR**. 2. hive-c0re's `/webhook/config-pr` endpoint receives the Forgejo diff --git a/docs/agent-lifecycle/persistence.md b/docs/agent-lifecycle/persistence.md index c2eb972f..7778acd4 100644 --- a/docs/agent-lifecycle/persistence.md +++ b/docs/agent-lifecycle/persistence.md @@ -155,7 +155,7 @@ the basename of the first real command, looking past `cd repo &&` prefixes, env-assignments, and prefix-runners like `sudo`/`env`. It backs the "favorite tools" view on the /stats page (aggregated host-side). Best-effort and created on first write -(`CREATE TABLE IF NOT EXISTS`), so it's simply absent until a bash +(`CREATE TABLE IF NOT EXISTS`), so it's absent until a bash task runs. turn-stats.sqlite has **no vacuum** — it's one tiny row per turn @@ -357,7 +357,7 @@ boundary a convention rather than a permission. approval resolves: 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 — -conflating them is an easy way to reason your way into thinking this +conflating them can lead you to reason your way into thinking this mount should be writable when it shouldn't. Per-child isolation still holds: a container only ever has its *own* diff --git a/docs/integrations/github.md b/docs/integrations/github.md index 194ea036..13754cfb 100644 --- a/docs/integrations/github.md +++ b/docs/integrations/github.md @@ -14,7 +14,7 @@ injected into the agent's state dir out of band. The integration is **on by default** for every agent (`hyperhive.github.enable = true`), inert until a PAT is provisioned. There is nothing per-agent to -declare — an agent gains GitHub simply by having a PAT written to its token +declare — an agent gains GitHub by having a PAT written to its token file. To turn it off for the whole hive, set the host option: @@ -81,7 +81,7 @@ When enabled, the container gets: Both scripts read the token from `/github-token` **at invocation time**, so a PAT written (or rotated) mid-session takes effect immediately — no container rebuild or restart. Until the file exists, `gh` / `git push` -simply fail unauthenticated. The token path is baked into the scripts at +fail unauthenticated. The token path is baked into the scripts at build time (not read from an env var), because claude's Bash tool runs in a minimal environment that wouldn't carry one. @@ -138,7 +138,7 @@ for `gh` + `git push` typically carries `repo` only, which is enough to push and open PRs but **not** to read the notification stream (nor to mark a thread read, which is the same scope). A PAT without it doesn't break anything: the poller logs the refusal and stays quiet, and the -agent simply never gets GitHub wakes. If an agent's GitHub +agent never gets GitHub wakes. If an agent's GitHub notifications never arrive, check the token's scopes first — the symptom is silence, not an error. diff --git a/docs/networking/snapshot-store.md b/docs/networking/snapshot-store.md index 8584fe13..efe30c33 100644 --- a/docs/networking/snapshot-store.md +++ b/docs/networking/snapshot-store.md @@ -4,8 +4,8 @@ The swarm's `btrfs receive` endpoint. Hives push agent snapshots to it over the WireGuard mesh; a destination hive later pulls one back to complete a migration. -Two things it is not, both worth stating because both are easy to -assume: +Two things it is not, both worth stating because both are common +assumptions: - **It is not the swarm controller**, and does not depend on one. It is a NixOS host role: a btrfs subvolume tree, a socket-activated @@ -53,7 +53,7 @@ services.hyperhive.swarm.snapshotStore = { }; ``` -Two deliberate asymmetries in that pair, both easy to misread as +Two deliberate asymmetries in that pair, both liable to be misread as inconsistency: - **`address` has no default.** It is a deployment fact a pushing hive @@ -114,9 +114,9 @@ The rule that matters: > **The receiver owns the destination root. The sender-supplied name is > validated, never used as a path.** -Validation is a whitelist --- `[A-Za-z0-9_-]+` and nothing else. No +Validation is an allowlist --- `[A-Za-z0-9_-]+` and nothing else. No slash and no dot means neither directory traversal nor an absolute path -can survive it. It is deliberately a whitelist and not a list of +can survive it. It is deliberately an allowlist and not a list of forbidden characters: a blocklist only ever excludes the attacks somebody already thought of. diff --git a/docs/process/gotchas.md b/docs/process/gotchas.md index bf505dcd..875ccbdb 100644 --- a/docs/process/gotchas.md +++ b/docs/process/gotchas.md @@ -19,7 +19,7 @@ rewrites this line. `nixos-container`'s start script builds the nspawn command line directly. Dropping a `.nspawn` file under `/run/systemd/nspawn/` -looks like the obvious extension point and does nothing. Use +looks like a natural extension point and does nothing. Use `EXTRA_NSPAWN_FLAGS` (above). ### `boot.isNspawnContainer = true` @@ -113,7 +113,7 @@ socket without needing a clean reinstall. `claude-code` comes from the flake's main `nixpkgs` (nixos-26.05). It's unfree, so the agent modules set `config.allowUnfreePredicate` -at the container level to whitelist `claude-code` specifically — +at the container level to allowlist `claude-code` specifically — scoped, only this one package. This is needed because each per-agent `nixosConfiguration` evaluates its own nixpkgs instance and the operator's host-level `allowUnfree` does **not** propagate in. @@ -131,7 +131,7 @@ What crosses is the **store path**, not the derivation. Containers share the host's `/nix/store`, so the binary is already reachable inside them with its whole closure; hive-c0re writes the path into each agent's flake as a string literal and the agent module symlinks -`bin/claude` onto PATH. Two things rule out the obvious alternatives: a +`bin/claude` onto PATH. Two things rule out the natural-seeming alternatives: a `path:/nix/store/` flake input is re-copied into the store as a reference-less `-source` (so the runtime closure never arrives), and `lib.types.package` fed a bare path runs `builtins.storePath`, which diff --git a/docs/swarm/README.md b/docs/swarm/README.md index 0cbf3d6d..88ea7d3b 100644 --- a/docs/swarm/README.md +++ b/docs/swarm/README.md @@ -161,7 +161,7 @@ evaluates cleanly points at a real machine that isn't the one you meant. ⚠️ **That container currently trusts no swarm-internal CA**, so a self-signed gateway certificate does not federate. The swarm root - can't simply be listed there: `security.pki.certificateFiles` is + can't be listed there: `security.pki.certificateFiles` is read when the system is _built_, and the root is a runtime file (its key must never enter the store), so there is no build-time name for it. Bridging that needs a runtime mechanism and is tracked as its own diff --git a/docs/swarm/ca.md b/docs/swarm/ca.md index e526a4e0..611bd99c 100644 --- a/docs/swarm/ca.md +++ b/docs/swarm/ca.md @@ -28,7 +28,7 @@ It defaults from `services.hyperhive.deploy.singleHostSwarm`, the single switch that says "this box is the whole deployment". **A hive given neither artifact keeps the self-signed CA it has always -had.** It serves TLS exactly as before and simply isn't part of a +had.** It serves TLS exactly as before and isn't part of a swarm's trust hierarchy — the right outcome for a hive nobody has federated yet. Only `autoConfigure` issues a hive sub-CA, because only that case can: signing one needs the root's private key. diff --git a/docs/swarm/ui.md b/docs/swarm/ui.md index e7fa1e11..431c3e1e 100644 --- a/docs/swarm/ui.md +++ b/docs/swarm/ui.md @@ -82,7 +82,7 @@ the surface the hive's own domain serves (dashboard, per-agent routing, matrix discovery); a swarm service declares its own vhost next to its own options, the way `swarm-ui.nix` and `swarm-authelia.nix` do. -⚠️ The certificate one is the least obvious and the most visible when +⚠️ The certificate one is the hardest to predict and the most visible when missed. `serviceDomains` is _both_ the services sub-CA's `nameConstraints` set and the leaf's SAN list, and the apex is a **sibling** of `forge.` / `chat.` / `auth.`, not a diff --git a/docs/turn-loop/README.md b/docs/turn-loop/README.md index d1a8a66c..ee40bd4e 100644 --- a/docs/turn-loop/README.md +++ b/docs/turn-loop/README.md @@ -164,7 +164,7 @@ The rest lives alongside this page, in three topic files: filtering). - **[mcp.md](mcp.md)** — the MCP tool surface claude sees: core tools, privileged tool groups, self-wake, authoritative state, the tool envelope, - and the built-in tool whitelist. + and the built-in tool allowlist. Per-subsystem impl detail lives in each module's `//!` doc-comment; these pages describe present-state behaviour + wiring, not line-level mechanics. diff --git a/docs/turn-loop/mcp.md b/docs/turn-loop/mcp.md index 2011da39..a3a61198 100644 --- a/docs/turn-loop/mcp.md +++ b/docs/turn-loop/mcp.md @@ -196,7 +196,7 @@ than deriving from SSE events. runs the body, logs the result. Pre-/post-log only — the inbox status hint lives in the wake prompt + UI header, not here. -## Tool whitelist (`mcp_config::ALLOWED_BUILTIN_TOOLS`) +## Tool allowlist (`mcp_config::ALLOWED_BUILTIN_TOOLS`) - Allowed built-ins: `Edit`, `Glob`, `Grep`, `Read`, `Skill`, `Write`. `Skill` is what makes an installed plugin's `SKILL.md` invokable —