swarm-builder: an agent option whose eval failed is left out of the reply, not read as its default

docs/agent-lifecycle/persistence.md

@@ -476,9 +476,11 @@ first start afterwards has hive-priv, as root, chown the agent's `state`,
 builder reads `config.services.hyperhive.agent.user.privateUsers` from the
 config it evaluates in its sandbox and puts it in the agent's closure record
 (`private_users`). hive-c0re reads the record when it writes the container's
-flags and sends the value to hive-priv with each start. A record or builder
-from before the field reads false; a record hive-c0re can't read, or none,
-leaves the agent as it is.
+flags and sends the value to hive-priv with each start. An agent whose module
+doesn't declare the option reads false. When the builder can't read the
+option (its eval fails or times out), the record carries no flag, and so does a
+record or builder from before the field. A record without a flag, a record
+hive-c0re can't read, or none, leaves the agent as it is.
 
 - **On disk the data belongs to one host uid:gid**,
   `services.hyperhive.deploy.hive-controller.userns.dataOwner`

docs/swarm/builder.md

@@ -282,6 +282,30 @@ The record's `cached` field says whether the builder pushed the closure to
 [the binary cache](#binary-cache). Each hive reads its own agents' keys to
 [report whether it can pull them and download them in a rebuild](#what-hives-do-with-the-cache). The closure stays unrooted in the builder host's store.
 
+The built reply and the record also carry two options of the agent's evaluated
+config, `private_users` (`services.hyperhive.agent.user.privateUsers`) and
+`nix_builds` (`services.hyperhive.agent.nixBuilds`). The builder reads each with
+a `nix eval` in its sandbox, and an eval has three outcomes:
+
+- **A value:** the field holds it.
+- **The module doesn't declare the option** (`nix` says the flake doesn't
+  provide the attribute): the field holds the option's default, off for
+  `private_users` and `host` for `nix_builds`.
+- **Any other failure, or a timeout:** the value is unknown, and the reply and
+  the record leave the field out. hive-c0re then sends nothing for that option,
+  and hive-priv keeps what the container's last write chose, as it does for an
+  agent with no record.
+
+Mixed versions:
+
+| builder | controller and hive-c0re | what happens                                                                                                   |
+| ------- | ------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| new     | new                      | an unread option leaves the field out, and the last write stands                                               |
+| old     | new                      | the old builder always sends a value, which the record carries                                                 |
+| new     | old                      | the old side reads a missing field as the default, so an unread option behaves as it did before this behaviour |
+
+A record or reply from before the fields reads as unknown.
+
 The controller gives the `builder` forge account read on `internal/meta` when it
 updates the flake, and again before each build, since the repo is private. A
 grant the forge refuses fails the build with no verdict.

docs/trust-boundary/security.md

@@ -211,12 +211,15 @@ the option from the evaluated config into the agent's closure record
 flags and sends the mode to hive-priv, and the flags apply at the container's
 next start.
 
-- A record or builder from before the field reads `host`.
+- An agent whose module doesn't declare the option reads `host`. When the builder
+  can't read the option (its eval fails or times out), the record carries no
+  mode, and so does a record or builder from before the field. hive-c0re then
+  sends no mode, and hive-priv keeps what the container's last write chose.
 - A mode this build doesn't know (a record written by a newer swarm) reads as
   `none`, never `host`: an agent that asked for a mode its hive can't give gets
   no builds, not builds outside its limits.
-- A record hive-c0re can't read, or none, sends no mode, and hive-priv keeps
-  what the container's last write chose.
+- A record hive-c0re can't read, or none, sends no mode either, and hive-priv
+  keeps what the container's last write chose.
 - A hive-c0re or hive-priv from before the option ignores it, so the agent keeps
   host builds until you upgrade both.