docs: suppress reviewed write-good.Passive false positives

133 hits across 38 files, all previously classified during #4548's sweep
and deliberately left un-rewritten (predicate-adjective state/necessity
description, design-intent idiom, structural/type-description idiom,
no-single-actor topology claim, parallel-triple exception, vale
substring-match artifact — see hyperhive#4548's per-PR bodies for the
per-hit reasoning).

Wraps each one in a scoped <!-- vale write-good.Passive = NO/YES -->
pair (the supported mechanism — TokenIgnores has a known offset-drift
bug) rather than a blanket per-file or per-rule silence, so a *new*
passive-voice hit anywhere in these files still fails once the rule
gates CI (next commit). Table/list false positives (docs/swarm/credentials.md's
renewal-table cells) wrap the whole block, not each cell.

Part of #4546.
This commit is contained in:
iris 2026-09-20 15:07:46 +02:00
commit 04e27c4fb6
38 changed files with 368 additions and 71 deletions

View file

@ -10,6 +10,8 @@ agent capability X?."
### The trust boundary is the container, not credential storage
<!-- vale write-good.Passive = NO -->
An agent is **trusted code running inside its own nspawn container**. The
boundary that matters is the container: a sub-agent can't see the host
netns, another agent's container, or another agent's state dir. Within its
@ -22,10 +24,16 @@ below stops a build's nixbld user reading the agent's own forge token, and the
state-file endpoint stops one agent proxying another's files. Those harden the
boundary; they don't sandbox the agent from itself.)
<!-- vale write-good.Passive = YES -->
<!-- vale write-good.Passive = NO -->
The corollary: **don't reason about security as "can the agent be stopped from
touching its credentials." Reason about it as "what's the blast radius if this
agent does the worst possible thing with everything it can reach."**
<!-- vale write-good.Passive = YES -->
### Scoped tokens bound the blast radius
Each agent gets its own scoped credentials, never shared:
@ -34,10 +42,14 @@ Each agent gets its own scoped credentials, never shared:
collaborator grants; can't act as another agent or as `core`).
- **matrix token** → that agent's matrix account only.
<!-- vale write-good.Passive = NO -->
_Its own_ account's scope bounds a compromised/confused agent's reach on the
forge or matrix, not the swarm's. This is the main thing standing
between "one agent does something dumb" and "the whole hive is affected."
<!-- vale write-good.Passive = YES -->
**Identity vs. secret (matrix).** The scoping is on the _secret_, not the
_identity_: an agent's matrix **token** is private to its own account, but its
matrix **identities** — the public handles (`name`, `user_id` `@user:server`,
@ -222,7 +234,7 @@ token policy bounds file reads; network isolation bounds network reach.
The proper fix is to enable user namespaces inside nspawn containers
(`--private-users=inherit` in `EXTRA_NSPAWN_FLAGS`) so nix can set up its real
sandbox and `sandbox-fallback` becomes a true last resort. This requires verifying
bind-mount compatibility with user namespace UID mapping and is tracked as a TODO.
bind-mount compatibility with user namespace UID mapping first.
## hive-c0re privilege separation