From b0f6ccaa64a039b17592dfa8f9c6711860e87102 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Sat, 7 Nov 2026 07:32:28 +0100
Subject: [PATCH] attic-init: replace the stored public key with the one the
 cache reports

a re-created cache signs with a new key; the fact was only created once, so
every hive then rejected the swarm's closures. the cache's grant gains update
on that one leaf, and a store that refuses it leaves the key as it was.

Closes #6181
---
 .../2-handbook/swarm/credentials-reference.md | 86 +++++++++----------
 docs/4-implementation/swarm/builder.md        | 11 ++-
 nix/host-modules/lib/attic-init.nix           | 37 ++++++--
 nix/host-modules/swarm-attic.nix              |  5 +-
 nix/host-modules/swarm-bao.nix                | 20 +++--
 nix/module-eval/bao-grants.nix                | 10 +--
 nix/script-tests/attic-init.sh                | 65 ++++++++++++--
 7 files changed, 159 insertions(+), 75 deletions(-)

diff --git a/docs/2-handbook/swarm/credentials-reference.md b/docs/2-handbook/swarm/credentials-reference.md
index 0bba22dd..c427ea3b 100644
--- a/docs/2-handbook/swarm/credentials-reference.md
+++ b/docs/2-handbook/swarm/credentials-reference.md
@@ -16,49 +16,49 @@ the rest of the cell says how.
 
 <!-- vale write-good.Passive = NO -->
 
-| store path                                                                                                             | minter                                                                                                                                                                                                                                                         | reader                                                                                                                             | automatic re-mint                                                                                                                                            | automatic re-pull                                                                                                                                                                                                                                            |
-| ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `swarm/agents/<agent>/matrix/main`                                                                                     | `swarm-controller`, at agent creation and every 5 minutes                                                                                                                                                                                                      | the agent                                                                                                                          | ✅ when missing or rejected by the homeserver                                                                                                                | ✅ the daemon restarts within 5 minutes of a rejection                                                                                                                                                                                                       |
-| `swarm/agents/<agent>/matrix/<account>`                                                                                | `swarm-controller`, from a credential you hand it                                                                                                                                                                                                              | the agent                                                                                                                          | must be stated                                                                                                                                               | ✅ retried within 2 to 16 minutes after a rejection                                                                                                                                                                                                          |
-| `swarm/agents/<agent>/matrix-recovery/<account>`                                                                       | `swarm-controller`, a random passphrase per account                                                                                                                                                                                                            | the agent                                                                                                                          | ❌ never replaced: the account's key backup opens only with this passphrase                                                                                  | ❌ read when the account comes up                                                                                                                                                                                                                            |
-| `swarm/controller/swarm-controller/matrix/appservice-token`                                                            | `swarm-matrix-ctl appservice sync` in `hive-matrix`, from the registration's `as_token`                                                                                                                                                                        | `swarm-controller`                                                                                                                 | ❌ follows the registration below                                                                                                                            | ✅ read every 5 minutes                                                                                                                                                                                                                                      |
-| `swarm/controller/swarm-controller/matrix/appservice-registration`                                                     | `swarm-matrix-ctl appservice render` in `hive-matrix`, when the store answers and holds none; before that, the tokens an earlier version kept in the container, stored unchanged                                                                               | `swarm-matrix-ctl` in `hive-matrix`; the controller has no grant to it                                                             | ❌ minted once; an operator who replaces it makes `sync` render the new pair and restart the homeserver                                                      | ✅ `sync` re-reads it every 10 minutes                                                                                                                                                                                                                       |
-| `swarm/controller/swarm-controller/oidc/client`                                                                        | authelia, first boot                                                                                                                                                                                                                                           | `swarm-controller`                                                                                                                 | ❌ minted once, straight into the store; minted again only when the store holds none                                                                         | ✅ re-read when authelia refuses it                                                                                                                                                                                                                          |
-| `swarm/controller/swarm-controller/forge/token`                                                                        | the forge, once                                                                                                                                                                                                                                                | `swarm-controller`                                                                                                                 | ❌ minted once; delete `/var/lib/forgejo/swarm-controller-token-name` in the forge container to mint a new one                                               | ✅ re-read on a 401                                                                                                                                                                                                                                          |
-| `swarm/controller/swarm-controller/grafana/token`                                                                      | `swarm-bao-grafana-controller-token` on Grafana's host                                                                                                                                                                                                         | `swarm-controller`                                                                                                                 | ✅ every 10 minutes, when Grafana refuses it or none is stored                                                                                               | ✅ re-read on a 401                                                                                                                                                                                                                                          |
-| `swarm/controller/swarm-controller/forge/webhook-secret`                                                               | `swarm-controller`, at start, from its old `webhook-secret` file; a new one only when there is no file                                                                                                                                                         | `swarm-controller`                                                                                                                 | ❌ minted once; a rotated secret fails every delivery until the forge hooks are re-registered                                                                | ❌ read once; a store down at start is re-read in the background until it answers                                                                                                                                                                            |
-| `swarm/agents/<agent>/bao-mtls`                                                                                        | the store's agent PKI mount (`deploy.bao.agentPkiMountPath`), at agent creation, and by the renewal pass when none is stored or its cert-auth role is missing                                                                                                  | `hive-c0re`, then the agent                                                                                                        | ✅ re-issued every 5 minutes once past half its 7-day validity; minted when none is stored or its cert-auth role is missing, for agents not `Destroyed`      | ✅ the agent re-reads every 10 minutes; it renews only while its current leaf is valid                                                                                                                                                                       |
-| `swarm/agents/<agent>/queue`                                                                                           | `swarm-controller`, at agent creation                                                                                                                                                                                                                          | the agent; the queue, log and metrics auth services                                                                                | ✅ re-minted at 45 days; skipped for `Destroyed` agents, whose path is deleted                                                                               | ✅ read on every reconnect; an open connection keeps the old secret for up to an hour; the log and metrics stores honour a replaced secret for up to `deploy.victorialogs.authVerdictTtl` and `deploy.victoriametrics.agentAuthVerdictTtl` (60 s by default) |
-| `swarm/agents/<agent>/observability`                                                                                   | `swarm-controller`, when an operator sets, clears or creates an agent's permissions with `logs` or `metrics` in the old or new list, and when it destroys the agent; the leaf stays absent for an agent that never held either                                 | the agent (read-only, its own prefix); `swarm-logs-auth` and `swarm-metrics-agent-auth`, which deny when it's absent or unreadable | ✅ the controller rewrites it with the permission, and every five minutes makes it equal the record's                                                        | ✅ the stores honour a changed grant for up to `deploy.victorialogs.authVerdictTtl` and `deploy.victoriametrics.agentAuthVerdictTtl` (60 s by default)                                                                                                       |
-| `swarm/agents/<agent>/forge-token`                                                                                     | `swarm-controller`, at agent creation and every 5 minutes                                                                                                                                                                                                      | the agent                                                                                                                          | ✅ when missing or no longer matching the forge                                                                                                              | ✅ every 10 minutes                                                                                                                                                                                                                                          |
-| `swarm/agents/<agent>/forge/<label>`                                                                                   | `swarm-controller`, when you link an external forge account in the swarm UI                                                                                                                                                                                    | the agent                                                                                                                          | ❌ your token; delete it and link the label again                                                                                                            | ✅ every 2 minutes                                                                                                                                                                                                                                           |
-| `swarm/agents/<agent>/gitlab/<label>`                                                                                  | `swarm-controller`, when you link a GitLab account through the API                                                                                                                                                                                             | the agent                                                                                                                          | ❌ your token; delete it and link the label again                                                                                                            | ✅ every 2 minutes; a deleted account leaves the agent's `glab` configuration on the next run                                                                                                                                                                |
-| `swarm/agents/<agent>/github-token`                                                                                    | `swarm-controller`, when you link a GitHub account in the swarm UI                                                                                                                                                                                             | the agent                                                                                                                          | ❌ your token; delete it and link again                                                                                                                      | ✅ every 2 minutes                                                                                                                                                                                                                                           |
-| `swarm/agents/<agent>/backend-env`                                                                                     | `hive-agent-backend-env`, in the agent's container, from the agent's `backendEnvironmentFile` when the leaf holds nothing (field `env`, the file's exact text); or `swarm-controller`, when you set the API-key environment in the swarm UI                    | the agent                                                                                                                          | ❌ nothing replaces it without you; a save in the swarm UI overwrites it, including text an agent wrote into an empty leaf; the agent's file stays as it was | ❌ the file in `/run` refreshes every 2 minutes, and the harness and the subagent daemon load it at their next start                                                                                                                                         |
-| `swarm/agents/<agent>/claude-credentials`                                                                              | `swarm-claude-login`, when you log the agent in from its card; one version per login                                                                                                                                                                           | the agent, while it waits for a login                                                                                              | ❌ log in again                                                                                                                                              | ✅ every 30 seconds while waiting                                                                                                                                                                                                                            |
-| `swarm/hives/<hive>/matrix/sender-token`                                                                               | `swarm-controller`, every 5 minutes                                                                                                                                                                                                                            | `swarm-controller` and the hive                                                                                                    | ✅ when missing or rejected by the homeserver                                                                                                                | ✅ the hive re-reads on every sweep                                                                                                                                                                                                                          |
-| `swarm/hives/<hive>/forge/token`                                                                                       | `swarm-controller`, every 5 minutes                                                                                                                                                                                                                            | `swarm-controller` and the hive                                                                                                    | ✅ when missing or no longer matching the forge                                                                                                              | ✅ read on every forge call                                                                                                                                                                                                                                  |
-| `swarm/agents/<agent>/proxy-credential`                                                                                | `swarm-controller`: 32 random bytes, at start and every 5 minutes for every agent that holds a store identity                                                                                                                                                  | the hive (`hive-c0re`) and the agent, which fetches it                                                                             | ❌ never replaced: written only while the path holds nothing                                                                                                 | ✅ `hive-c0re` re-reads it every 30 seconds                                                                                                                                                                                                                  |
-| `swarm/hives/<hive>/squid-selfcheck`                                                                                   | `swarm-controller`, in the same pass as the agents' credentials                                                                                                                                                                                                | the hive: `hive-c0re` and `squid-selfcheck-credential` (root)                                                                      | ❌ never replaced: written only while the path holds nothing                                                                                                 | ✅ `hive-c0re` every 30 seconds, the root unit every 10 minutes                                                                                                                                                                                              |
-| `swarm/hives/<hive>/oidc/client`                                                                                       | authelia, first boot, straight into the store                                                                                                                                                                                                                  | the hive                                                                                                                           | ❌ minted once, straight into the store; minted again only when the store holds none                                                                         | ✅ re-read when authelia refuses it                                                                                                                                                                                                                          |
-| `swarm/services/<clientId>/oidc/client`                                                                                | authelia                                                                                                                                                                                                                                                       | that service                                                                                                                       | must be stated                                                                                                                                               | must be stated                                                                                                                                                                                                                                               |
-| `swarm/services/ci-runner/registration-token`                                                                          | `swarm-controller`, from the forge, at start and every 5 minutes                                                                                                                                                                                               | `swarm-bao-ci-runner` on the runner's host                                                                                         | ❌ the forge keeps one token until an admin resets it; the controller then writes the new one within 5 minutes                                               | ✅ every 10 minutes; restarts the runner on a change                                                                                                                                                                                                         |
-| `swarm/services/<grafana client id>/metrics/bearer`                                                                    | `swarm-bao-grafana-metrics-bearer` on Grafana's host, when none is stored                                                                                                                                                                                      | `swarm-metrics-auth` and `swarm-logs-grafana-auth`                                                                                 | ❌ delete it and restart `swarm-bao-grafana-metrics-bearer`                                                                                                  | ✅ the auth services re-read within a minute, and while they can't reach the store they keep accepting the value they last read, for an hour at most; ❌ Grafana restarts when its copy changes                                                              |
-| `swarm/services/<grafana client id>/secret-key`                                                                        | `swarm-bao-grafana-secret-key` on Grafana's host, from the key an earlier release generated; a new one only when there is none                                                                                                                                 | Grafana                                                                                                                            | ❌ minted once; a different key leaves Grafana unable to read its stored datasource secrets                                                                  | ❌ Grafana reads it at start; the unit restarts Grafana when the file changes                                                                                                                                                                                |
-| `swarm/services/swarm-authelia/keys/<name>`, for `jwt`, `session`, `storage-encryption`, `oidc-hmac` and `oidc-issuer` | authelia's `authelia-swarm-secrets` unit in its container, under the secret publisher's identity, from the key file an earlier release generated; a new one only when there is none                                                                            | authelia                                                                                                                           | ❌ minted once; a different storage-encryption key leaves authelia's database unreadable and a different issuer key invalidates every issued token           | ❌ read when the unit runs; the unit restarts authelia when the file changes                                                                                                                                                                                 |
-| `swarm/services/review-classifier/anthropic-api-key`                                                                   | you, in the store's UI, field `api_key`                                                                                                                                                                                                                        | `swarm-review-classifier`                                                                                                          | ❌ write a new key                                                                                                                                           | ✅ read on every run                                                                                                                                                                                                                                         |
-| `swarm/services/review-classifier/acp-provider`                                                                        | you, in the store's UI, field `api_key`                                                                                                                                                                                                                        | `swarm-review-classifier`                                                                                                          | ❌ write a new key                                                                                                                                           | ✅ read on every run                                                                                                                                                                                                                                         |
-| `swarm/services/review-classifier/forge/token`                                                                         | `swarm-controller`, at start and every 5 minutes                                                                                                                                                                                                               | `swarm-controller`                                                                                                                 | ✅ when missing or no longer matching the forge                                                                                                              | ✅ read on every review                                                                                                                                                                                                                                      |
-| `swarm/services/builder/forge/token`                                                                                   | `swarm-controller`, at start and every 5 minutes                                                                                                                                                                                                               | `swarm-builder`, `swarm-controller`                                                                                                | ✅ when missing or no longer matching the forge                                                                                                              | ✅ read on every build                                                                                                                                                                                                                                       |
-| `swarm/services/attic/push-token`                                                                                      | `swarm-bao-attic-tokens` on the cache's host, when none is stored; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the token on stdin                                                                       | `swarm-builder`                                                                                                                    | ❌ write a new token; a token the cache refuses fails the push, and the build stays green with `cached` false                                                | ✅ read on every push; with both `swarm.attic` options null, nothing reads it                                                                                                                                                                                |
-| `swarm/services/attic/pull-token`                                                                                      | `swarm-bao-attic-tokens` on the cache's host, when none is stored; read-only, ten years; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin                                                 | `swarm-controller`, to copy it and to check narinfos                                                                               | ❌ write a new token                                                                                                                                         | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
-| `swarm/services/attic/url`                                                                                             | `swarm-bao-attic-tokens` on the cache's host, when none is stored (`https://<swarm.attic.domain>`); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin (scheme included, no trailing slash) | `swarm-controller`, which copies it to each hive                                                                                   | ❌ delete it and restart `swarm-bao-attic-tokens`, or write the new value                                                                                    | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
-| `swarm/services/attic/cache`                                                                                           | `swarm-bao-attic-tokens` on the cache's host, when none is stored (`swarm.attic.cache`); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin                                                 | `swarm-controller`, which copies it to each hive                                                                                   | ❌ as the URL                                                                                                                                                | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
-| `swarm/services/attic/public-key`                                                                                      | `swarm-bao-attic-tokens` on the cache's host, when none is stored (the key `attic cache info` prints); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin (`<name>:<base64>`)               | `swarm-controller`, which copies it to each hive                                                                                   | ❌ as the URL. A cache recreated with a new key leaves the stored one stale: every hive then reports `bad-signature`                                         | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
-| `swarm/hives/<hive>/attic/{pull-token,url,cache,public-key}`                                                           | `swarm-controller`, from the four `swarm/services/attic/` leaves, every 5 minutes; it skips a leaf whose source holds nothing, and a copy whose source is gone stays                                                                                           | the hive (`hive-c0re`)                                                                                                             | ✅ a changed source is written over the copy in the next pass                                                                                                | ✅ read every 5 minutes                                                                                                                                                                                                                                      |
-| `swarm/services/attic/jwt-secret`                                                                                      | `swarm-bao-attic-secret` on the cache's host, when none is stored                                                                                                                                                                                              | `swarm-bao-attic-secret`, `swarm-bao-attic-tokens`                                                                                 | ❌ a new key invalidates both tokens                                                                                                                         | ❌ atticd restarts when the file changes                                                                                                                                                                                                                     |
-| `swarm/services/ci-metrics/forge/token`                                                                                | `swarm-controller`, at start and every 5 minutes                                                                                                                                                                                                               | `swarm-ci-metrics`, `swarm-controller`                                                                                             | ✅ when missing or no longer matching the forge                                                                                                              | ✅ read on every pass                                                                                                                                                                                                                                        |
-| _(not in the store)_ a hive's mTLS leaf                                                                                | the store's PKI, or you by hand                                                                                                                                                                                                                                | the hive itself, from disk                                                                                                         | must be stated                                                                                                                                               | must be stated                                                                                                                                                                                                                                               |
+| store path                                                                                                             | minter                                                                                                                                                                                                                                                                                            | reader                                                                                                                             | automatic re-mint                                                                                                                                            | automatic re-pull                                                                                                                                                                                                                                            |
+| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `swarm/agents/<agent>/matrix/main`                                                                                     | `swarm-controller`, at agent creation and every 5 minutes                                                                                                                                                                                                                                         | the agent                                                                                                                          | ✅ when missing or rejected by the homeserver                                                                                                                | ✅ the daemon restarts within 5 minutes of a rejection                                                                                                                                                                                                       |
+| `swarm/agents/<agent>/matrix/<account>`                                                                                | `swarm-controller`, from a credential you hand it                                                                                                                                                                                                                                                 | the agent                                                                                                                          | must be stated                                                                                                                                               | ✅ retried within 2 to 16 minutes after a rejection                                                                                                                                                                                                          |
+| `swarm/agents/<agent>/matrix-recovery/<account>`                                                                       | `swarm-controller`, a random passphrase per account                                                                                                                                                                                                                                               | the agent                                                                                                                          | ❌ never replaced: the account's key backup opens only with this passphrase                                                                                  | ❌ read when the account comes up                                                                                                                                                                                                                            |
+| `swarm/controller/swarm-controller/matrix/appservice-token`                                                            | `swarm-matrix-ctl appservice sync` in `hive-matrix`, from the registration's `as_token`                                                                                                                                                                                                           | `swarm-controller`                                                                                                                 | ❌ follows the registration below                                                                                                                            | ✅ read every 5 minutes                                                                                                                                                                                                                                      |
+| `swarm/controller/swarm-controller/matrix/appservice-registration`                                                     | `swarm-matrix-ctl appservice render` in `hive-matrix`, when the store answers and holds none; before that, the tokens an earlier version kept in the container, stored unchanged                                                                                                                  | `swarm-matrix-ctl` in `hive-matrix`; the controller has no grant to it                                                             | ❌ minted once; an operator who replaces it makes `sync` render the new pair and restart the homeserver                                                      | ✅ `sync` re-reads it every 10 minutes                                                                                                                                                                                                                       |
+| `swarm/controller/swarm-controller/oidc/client`                                                                        | authelia, first boot                                                                                                                                                                                                                                                                              | `swarm-controller`                                                                                                                 | ❌ minted once, straight into the store; minted again only when the store holds none                                                                         | ✅ re-read when authelia refuses it                                                                                                                                                                                                                          |
+| `swarm/controller/swarm-controller/forge/token`                                                                        | the forge, once                                                                                                                                                                                                                                                                                   | `swarm-controller`                                                                                                                 | ❌ minted once; delete `/var/lib/forgejo/swarm-controller-token-name` in the forge container to mint a new one                                               | ✅ re-read on a 401                                                                                                                                                                                                                                          |
+| `swarm/controller/swarm-controller/grafana/token`                                                                      | `swarm-bao-grafana-controller-token` on Grafana's host                                                                                                                                                                                                                                            | `swarm-controller`                                                                                                                 | ✅ every 10 minutes, when Grafana refuses it or none is stored                                                                                               | ✅ re-read on a 401                                                                                                                                                                                                                                          |
+| `swarm/controller/swarm-controller/forge/webhook-secret`                                                               | `swarm-controller`, at start, from its old `webhook-secret` file; a new one only when there is no file                                                                                                                                                                                            | `swarm-controller`                                                                                                                 | ❌ minted once; a rotated secret fails every delivery until the forge hooks are re-registered                                                                | ❌ read once; a store down at start is re-read in the background until it answers                                                                                                                                                                            |
+| `swarm/agents/<agent>/bao-mtls`                                                                                        | the store's agent PKI mount (`deploy.bao.agentPkiMountPath`), at agent creation, and by the renewal pass when none is stored or its cert-auth role is missing                                                                                                                                     | `hive-c0re`, then the agent                                                                                                        | ✅ re-issued every 5 minutes once past half its 7-day validity; minted when none is stored or its cert-auth role is missing, for agents not `Destroyed`      | ✅ the agent re-reads every 10 minutes; it renews only while its current leaf is valid                                                                                                                                                                       |
+| `swarm/agents/<agent>/queue`                                                                                           | `swarm-controller`, at agent creation                                                                                                                                                                                                                                                             | the agent; the queue, log and metrics auth services                                                                                | ✅ re-minted at 45 days; skipped for `Destroyed` agents, whose path is deleted                                                                               | ✅ read on every reconnect; an open connection keeps the old secret for up to an hour; the log and metrics stores honour a replaced secret for up to `deploy.victorialogs.authVerdictTtl` and `deploy.victoriametrics.agentAuthVerdictTtl` (60 s by default) |
+| `swarm/agents/<agent>/observability`                                                                                   | `swarm-controller`, when an operator sets, clears or creates an agent's permissions with `logs` or `metrics` in the old or new list, and when it destroys the agent; the leaf stays absent for an agent that never held either                                                                    | the agent (read-only, its own prefix); `swarm-logs-auth` and `swarm-metrics-agent-auth`, which deny when it's absent or unreadable | ✅ the controller rewrites it with the permission, and every five minutes makes it equal the record's                                                        | ✅ the stores honour a changed grant for up to `deploy.victorialogs.authVerdictTtl` and `deploy.victoriametrics.agentAuthVerdictTtl` (60 s by default)                                                                                                       |
+| `swarm/agents/<agent>/forge-token`                                                                                     | `swarm-controller`, at agent creation and every 5 minutes                                                                                                                                                                                                                                         | the agent                                                                                                                          | ✅ when missing or no longer matching the forge                                                                                                              | ✅ every 10 minutes                                                                                                                                                                                                                                          |
+| `swarm/agents/<agent>/forge/<label>`                                                                                   | `swarm-controller`, when you link an external forge account in the swarm UI                                                                                                                                                                                                                       | the agent                                                                                                                          | ❌ your token; delete it and link the label again                                                                                                            | ✅ every 2 minutes                                                                                                                                                                                                                                           |
+| `swarm/agents/<agent>/gitlab/<label>`                                                                                  | `swarm-controller`, when you link a GitLab account through the API                                                                                                                                                                                                                                | the agent                                                                                                                          | ❌ your token; delete it and link the label again                                                                                                            | ✅ every 2 minutes; a deleted account leaves the agent's `glab` configuration on the next run                                                                                                                                                                |
+| `swarm/agents/<agent>/github-token`                                                                                    | `swarm-controller`, when you link a GitHub account in the swarm UI                                                                                                                                                                                                                                | the agent                                                                                                                          | ❌ your token; delete it and link again                                                                                                                      | ✅ every 2 minutes                                                                                                                                                                                                                                           |
+| `swarm/agents/<agent>/backend-env`                                                                                     | `hive-agent-backend-env`, in the agent's container, from the agent's `backendEnvironmentFile` when the leaf holds nothing (field `env`, the file's exact text); or `swarm-controller`, when you set the API-key environment in the swarm UI                                                       | the agent                                                                                                                          | ❌ nothing replaces it without you; a save in the swarm UI overwrites it, including text an agent wrote into an empty leaf; the agent's file stays as it was | ❌ the file in `/run` refreshes every 2 minutes, and the harness and the subagent daemon load it at their next start                                                                                                                                         |
+| `swarm/agents/<agent>/claude-credentials`                                                                              | `swarm-claude-login`, when you log the agent in from its card; one version per login                                                                                                                                                                                                              | the agent, while it waits for a login                                                                                              | ❌ log in again                                                                                                                                              | ✅ every 30 seconds while waiting                                                                                                                                                                                                                            |
+| `swarm/hives/<hive>/matrix/sender-token`                                                                               | `swarm-controller`, every 5 minutes                                                                                                                                                                                                                                                               | `swarm-controller` and the hive                                                                                                    | ✅ when missing or rejected by the homeserver                                                                                                                | ✅ the hive re-reads on every sweep                                                                                                                                                                                                                          |
+| `swarm/hives/<hive>/forge/token`                                                                                       | `swarm-controller`, every 5 minutes                                                                                                                                                                                                                                                               | `swarm-controller` and the hive                                                                                                    | ✅ when missing or no longer matching the forge                                                                                                              | ✅ read on every forge call                                                                                                                                                                                                                                  |
+| `swarm/agents/<agent>/proxy-credential`                                                                                | `swarm-controller`: 32 random bytes, at start and every 5 minutes for every agent that holds a store identity                                                                                                                                                                                     | the hive (`hive-c0re`) and the agent, which fetches it                                                                             | ❌ never replaced: written only while the path holds nothing                                                                                                 | ✅ `hive-c0re` re-reads it every 30 seconds                                                                                                                                                                                                                  |
+| `swarm/hives/<hive>/squid-selfcheck`                                                                                   | `swarm-controller`, in the same pass as the agents' credentials                                                                                                                                                                                                                                   | the hive: `hive-c0re` and `squid-selfcheck-credential` (root)                                                                      | ❌ never replaced: written only while the path holds nothing                                                                                                 | ✅ `hive-c0re` every 30 seconds, the root unit every 10 minutes                                                                                                                                                                                              |
+| `swarm/hives/<hive>/oidc/client`                                                                                       | authelia, first boot, straight into the store                                                                                                                                                                                                                                                     | the hive                                                                                                                           | ❌ minted once, straight into the store; minted again only when the store holds none                                                                         | ✅ re-read when authelia refuses it                                                                                                                                                                                                                          |
+| `swarm/services/<clientId>/oidc/client`                                                                                | authelia                                                                                                                                                                                                                                                                                          | that service                                                                                                                       | must be stated                                                                                                                                               | must be stated                                                                                                                                                                                                                                               |
+| `swarm/services/ci-runner/registration-token`                                                                          | `swarm-controller`, from the forge, at start and every 5 minutes                                                                                                                                                                                                                                  | `swarm-bao-ci-runner` on the runner's host                                                                                         | ❌ the forge keeps one token until an admin resets it; the controller then writes the new one within 5 minutes                                               | ✅ every 10 minutes; restarts the runner on a change                                                                                                                                                                                                         |
+| `swarm/services/<grafana client id>/metrics/bearer`                                                                    | `swarm-bao-grafana-metrics-bearer` on Grafana's host, when none is stored                                                                                                                                                                                                                         | `swarm-metrics-auth` and `swarm-logs-grafana-auth`                                                                                 | ❌ delete it and restart `swarm-bao-grafana-metrics-bearer`                                                                                                  | ✅ the auth services re-read within a minute, and while they can't reach the store they keep accepting the value they last read, for an hour at most; ❌ Grafana restarts when its copy changes                                                              |
+| `swarm/services/<grafana client id>/secret-key`                                                                        | `swarm-bao-grafana-secret-key` on Grafana's host, from the key an earlier release generated; a new one only when there is none                                                                                                                                                                    | Grafana                                                                                                                            | ❌ minted once; a different key leaves Grafana unable to read its stored datasource secrets                                                                  | ❌ Grafana reads it at start; the unit restarts Grafana when the file changes                                                                                                                                                                                |
+| `swarm/services/swarm-authelia/keys/<name>`, for `jwt`, `session`, `storage-encryption`, `oidc-hmac` and `oidc-issuer` | authelia's `authelia-swarm-secrets` unit in its container, under the secret publisher's identity, from the key file an earlier release generated; a new one only when there is none                                                                                                               | authelia                                                                                                                           | ❌ minted once; a different storage-encryption key leaves authelia's database unreadable and a different issuer key invalidates every issued token           | ❌ read when the unit runs; the unit restarts authelia when the file changes                                                                                                                                                                                 |
+| `swarm/services/review-classifier/anthropic-api-key`                                                                   | you, in the store's UI, field `api_key`                                                                                                                                                                                                                                                           | `swarm-review-classifier`                                                                                                          | ❌ write a new key                                                                                                                                           | ✅ read on every run                                                                                                                                                                                                                                         |
+| `swarm/services/review-classifier/acp-provider`                                                                        | you, in the store's UI, field `api_key`                                                                                                                                                                                                                                                           | `swarm-review-classifier`                                                                                                          | ❌ write a new key                                                                                                                                           | ✅ read on every run                                                                                                                                                                                                                                         |
+| `swarm/services/review-classifier/forge/token`                                                                         | `swarm-controller`, at start and every 5 minutes                                                                                                                                                                                                                                                  | `swarm-controller`                                                                                                                 | ✅ when missing or no longer matching the forge                                                                                                              | ✅ read on every review                                                                                                                                                                                                                                      |
+| `swarm/services/builder/forge/token`                                                                                   | `swarm-controller`, at start and every 5 minutes                                                                                                                                                                                                                                                  | `swarm-builder`, `swarm-controller`                                                                                                | ✅ when missing or no longer matching the forge                                                                                                              | ✅ read on every build                                                                                                                                                                                                                                       |
+| `swarm/services/attic/push-token`                                                                                      | `swarm-bao-attic-tokens` on the cache's host, when none is stored; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the token on stdin                                                                                                          | `swarm-builder`                                                                                                                    | ❌ write a new token; a token the cache refuses fails the push, and the build stays green with `cached` false                                                | ✅ read on every push; with both `swarm.attic` options null, nothing reads it                                                                                                                                                                                |
+| `swarm/services/attic/pull-token`                                                                                      | `swarm-bao-attic-tokens` on the cache's host, when none is stored; read-only, ten years; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin                                                                                    | `swarm-controller`, to copy it and to check narinfos                                                                               | ❌ write a new token                                                                                                                                         | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
+| `swarm/services/attic/url`                                                                                             | `swarm-bao-attic-tokens` on the cache's host, when none is stored (`https://<swarm.attic.domain>`); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin (scheme included, no trailing slash)                                    | `swarm-controller`, which copies it to each hive                                                                                   | ❌ delete it and restart `swarm-bao-attic-tokens`, or write the new value                                                                                    | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
+| `swarm/services/attic/cache`                                                                                           | `swarm-bao-attic-tokens` on the cache's host, when none is stored (`swarm.attic.cache`); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin                                                                                    | `swarm-controller`, which copies it to each hive                                                                                   | ❌ as the URL                                                                                                                                                | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
+| `swarm/services/attic/public-key`                                                                                      | `swarm-bao-attic-tokens` on the cache's host, when none is stored and again whenever the cache reports another key (the key `attic cache info` prints); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin (`<name>:<base64>`) | `swarm-controller`, which copies it to each hive                                                                                   | ✅ on the cache's host, a re-created cache's key replaces it at the unit's next run; with an external cache, replace it yourself                             | ✅ copied to the hives every 5 minutes                                                                                                                                                                                                                       |
+| `swarm/hives/<hive>/attic/{pull-token,url,cache,public-key}`                                                           | `swarm-controller`, from the four `swarm/services/attic/` leaves, every 5 minutes; it skips a leaf whose source holds nothing, and a copy whose source is gone stays                                                                                                                              | the hive (`hive-c0re`)                                                                                                             | ✅ a changed source is written over the copy in the next pass                                                                                                | ✅ read every 5 minutes                                                                                                                                                                                                                                      |
+| `swarm/services/attic/jwt-secret`                                                                                      | `swarm-bao-attic-secret` on the cache's host, when none is stored                                                                                                                                                                                                                                 | `swarm-bao-attic-secret`, `swarm-bao-attic-tokens`                                                                                 | ❌ a new key invalidates both tokens                                                                                                                         | ❌ atticd restarts when the file changes                                                                                                                                                                                                                     |
+| `swarm/services/ci-metrics/forge/token`                                                                                | `swarm-controller`, at start and every 5 minutes                                                                                                                                                                                                                                                  | `swarm-ci-metrics`, `swarm-controller`                                                                                             | ✅ when missing or no longer matching the forge                                                                                                              | ✅ read on every pass                                                                                                                                                                                                                                        |
+| _(not in the store)_ a hive's mTLS leaf                                                                                | the store's PKI, or you by hand                                                                                                                                                                                                                                                                   | the hive itself, from disk                                                                                                         | must be stated                                                                                                                                               | must be stated                                                                                                                                                                                                                                               |
 
 <!-- vale write-good.Passive = YES -->
 
diff --git a/docs/4-implementation/swarm/builder.md b/docs/4-implementation/swarm/builder.md
index e7be76d8..e99ee2b1 100644
--- a/docs/4-implementation/swarm/builder.md
+++ b/docs/4-implementation/swarm/builder.md
@@ -419,10 +419,13 @@ mints nothing. Both tokens last ten years and nothing renews them. To replace on
 write the new token to its path in the store, in its UI under the OIDC login:
 nothing mints over a value that exists. A new signing key invalidates both tokens.
 
-The unit creates the address, name and key once and never updates them. After
-you change `swarm.attic.domain`, or after the server's database goes and the
-cache gets a new key, delete the stale leaf and restart
-`swarm-bao-attic-tokens`.
+The unit creates the address and the name once and never updates them. After
+you change `swarm.attic.domain`, delete the stale `url` leaf and restart
+`swarm-bao-attic-tokens`. The unit checks the public key on every run and
+replaces the stored one with the key `attic cache info` prints, so a cache
+that loses its database and gets a new key needs no step: the next run of the
+unit stores the new key, the controller copies it to the hives within five
+minutes, and `hive-priv-cache-facts` reads it within ten.
 
 `swarm.attic.domain` and `swarm.attic.cache` default to `attic.<swarm domain>`
 and `swarm` on every host, whether or not it runs the cache, so a builder on any
diff --git a/nix/host-modules/lib/attic-init.nix b/nix/host-modules/lib/attic-init.nix
index 91c71bfe..c3b62a7f 100644
--- a/nix/host-modules/lib/attic-init.nix
+++ b/nix/host-modules/lib/attic-init.nix
@@ -1,7 +1,8 @@
 # The shell for the in-swarm cache's first start: what its two host units run
 # after they log in to the secret store under the cache's own certificate.
 # Each secret is created only while the store holds none, so a second run reads
-# what the first one stored and mints nothing.
+# what the first one stored and mints nothing. The cache's public key is the
+# exception: the store is brought to the key the cache reports.
 #
 # Pure function — NOT a NixOS module. Call it from a module's `let`:
 #
@@ -21,9 +22,10 @@
   jwtPath,
   pullPath,
   pushPath,
-  # The cache's public facts, created only while absent: the server's address
-  # (scheme included), the cache's name, and the key its narinfo are signed
-  # with. Hives pull with them.
+  # The cache's public facts: the server's address (scheme included), the
+  # cache's name, and the key its narinfo are signed with. Hives pull with
+  # them. The address and the name are created only while absent; the key is
+  # replaced whenever the cache reports another.
   urlPath,
   cachePath,
   publicKeyPath,
@@ -187,6 +189,31 @@ in
     }
     ensure_secret ${q urlPath} mint_url >/dev/null || exit 1
     ensure_secret ${q cachePath} mint_cache >/dev/null || exit 1
-    ensure_secret ${q publicKeyPath} mint_public_key >/dev/null || exit 1
+    stored_key="$(ensure_secret ${q publicKeyPath} mint_public_key)" || exit 1
+
+    # A cache created again has a new signing key, so the stored key is
+    # replaced by the one the cache reports. Only the cache's own grant on this
+    # path allows an update; a store whose policy lacks it refuses, and the
+    # stored key stays.
+    live_key="$(mint_public_key)"
+    if [ -z "$live_key" ]; then
+      echo "the cache ${cache} reported no public key." >&2
+      exit 1
+    fi
+    if [ "$stored_key" != "$live_key" ]; then
+      if printf '%s' "$live_key" | bao kv put ${q publicKeyPath} value=- >/dev/null 2>"$err"; then
+        echo "replaced the stored public key with the one the cache ${cache} reports."
+      else
+        case "$(cat "$err")" in
+          *"permission denied"*)
+            echo "the store refuses to update ${publicKeyPath}; the stored key is not the cache's." >&2
+            ;;
+          *)
+            cat "$err" >&2
+            exit 1
+            ;;
+        esac
+      fi
+    fi
   '';
 }
diff --git a/nix/host-modules/swarm-attic.nix b/nix/host-modules/swarm-attic.nix
index 1c8ad68f..5bd310a8 100644
--- a/nix/host-modules/swarm-attic.nix
+++ b/nix/host-modules/swarm-attic.nix
@@ -7,8 +7,9 @@
 # ./swarm-grafana.nix gives its admin password. One creates the key atticd signs
 # tokens with, if the store holds none, and hands it to the container. The other
 # creates the cache, the push and pull tokens, and the facts hives pull with
-# (its address, name and public key), each only while absent
-# (./lib/attic-init.nix). Neither needs a manual step.
+# (its address and name, created only while absent, and its public key, which
+# follows what the cache reports; ./lib/attic-init.nix). Neither needs a manual
+# step.
 #
 # The container has a network namespace of its own on the hive bridge. atticd
 # listens on that namespace's loopback only, because it cannot listen on a unix
diff --git a/nix/host-modules/swarm-bao.nix b/nix/host-modules/swarm-bao.nix
index 274e5e69..66feefb1 100644
--- a/nix/host-modules/swarm-bao.nix
+++ b/nix/host-modules/swarm-bao.nix
@@ -1307,11 +1307,11 @@ let
     }
   ];
 
-  # The in-swarm cache's six secrets, create and read and nothing more: its
-  # host units create each one only while it is absent, so none needs `update`,
-  # and a rewrite of a signing key or a token an operator holds is refused. The
-  # cache container's journal forwarder reads its client secret under the same
-  # leaf.
+  # The in-swarm cache's six secrets: create and read, so a rewrite of a signing
+  # key or a token an operator holds is refused. The public key also gets
+  # `update`: the cache's host unit replaces it when a re-created cache signs
+  # with another. The cache container's journal forwarder reads its client
+  # secret under the same leaf.
   atticWriters = [
     {
       name = "swarm-attic";
@@ -1328,8 +1328,13 @@ let
               atticJwtLeaf
               atticPushTokenLeaf
             ]
-            ++ atticFactLeaves
+            ++ lib.remove atticPublicKeyLeaf atticFactLeaves
           )
+        + ''
+          path "${credentialMountPath}/data/${atticPublicKeyLeaf}" {
+            capabilities = ["create", "read", "update"]
+          }
+        ''
         + readStanza "${credentialMountPath}/data/swarm/services/${hyperhiveCfg.swarm.attic.otel.clientId}/oidc/client";
     }
   ];
@@ -2592,7 +2597,8 @@ in
         Subject the store's `swarm-attic` cert-auth role accepts: the identity
         the in-swarm cache's host units present. Its grant is create and read on
         six paths under `swarm/services/attic/`, `jwt-secret`, `push-token`,
-        `pull-token`, `url`, `cache` and `public-key`, and nothing else.
+        `pull-token`, `url`, `cache` and `public-key`, plus `update` on
+        `public-key`, and nothing else.
 
         ⚠️ Reserved as a hive name by ./swarm.nix, like its siblings.
       '';
diff --git a/nix/module-eval/bao-grants.nix b/nix/module-eval/bao-grants.nix
index 727281cd..76844985 100644
--- a/nix/module-eval/bao-grants.nix
+++ b/nix/module-eval/bao-grants.nix
@@ -2129,10 +2129,10 @@ let
     }
     {
       # The cache's host units create each of its six secrets and read them
-      # back, and may not replace one: no `update`. Its container's journal
-      # forwarder reads its own client secret, read only. The notification
-      # router's grant is the control that `grantsIn` reads a one-path grant too.
-      name = "the cache's grant is create and read on its signing key, its two tokens and its three public facts, read on its forwarder client, and nothing else";
+      # back, and replace only the public key: `update` there and nowhere else.
+      # Its container's journal forwarder reads its own client secret, read
+      # only. The notification router's grant is the control that `grantsIn` reads a one-path grant too.
+      name = "the cache's grant is create and read on its signing key, its two tokens and its three public facts, update on its public key only, read on its forwarder client, and nothing else";
       ok =
         let
           s = baoGrantHere.systemd.services.swarm-bao-attic-policy.script;
@@ -2147,7 +2147,7 @@ let
         && (grantFor grants "secret/data/swarm/services/attic/pull-token").caps == caps
         && (grantFor grants "secret/data/swarm/services/attic/url").caps == caps
         && (grantFor grants "secret/data/swarm/services/attic/cache").caps == caps
-        && (grantFor grants "secret/data/swarm/services/attic/public-key").caps == caps
+        && (grantFor grants "secret/data/swarm/services/attic/public-key").caps == caps ++ [ "update" ]
         &&
           (grantFor grants "secret/data/swarm/services/swarm-attic-collector/oidc/client").caps == [ "read" ]
         && lib.length grants == 7
diff --git a/nix/script-tests/attic-init.sh b/nix/script-tests/attic-init.sh
index db53dd5f..4913314f 100644
--- a/nix/script-tests/attic-init.sh
+++ b/nix/script-tests/attic-init.sh
@@ -48,6 +48,8 @@ case "\$1 \$2" in
     f=\$(file "\$path")
     echo "bao put cas=\$cas \$path" >>"$calls"
     value=\$(cat)
+    # UPDATE_FAIL is what the store says to a put that replaces a value.
+    if [ "\$cas" = 0 ] && [ -n "\${UPDATE_FAIL:-}" ]; then echo "\$UPDATE_FAIL" >&2; exit 1; fi
     if [ "\${RACE_PATH:-}" = "\$path" ] && [ ! -f "\$f" ]; then
       printf '%s' raced >"\$f"
     fi
@@ -85,7 +87,7 @@ token=\$(cat "\$tokenfile")
 echo "attic \$* | token=\$token" >>"$calls"
 case "\$1 \$2" in
   "cache info")
-    [ -f "\$DIR/cache-exists" ] && echo "           Public Key: grid:FAKEKEY" >&2
+    [ -f "\$DIR/cache-exists" ] && echo "           Public Key: \$(cat "\$DIR/live-key" 2>/dev/null || echo grid:FAKEKEY)" >&2
     ;;
   "cache create") touch "\$DIR/cache-exists" ;;
   *) exit 1 ;;
@@ -122,7 +124,7 @@ run() {
 }
 
 reset() {
-  rm -rf "$dir/store" "$dir/secrets" "$dir/cache-exists" "$calls"
+  rm -rf "$dir/store" "$dir/secrets" "$dir/cache-exists" "$dir/live-key" "$calls"
   mkdir -p "$dir/store" "$dir/secrets"
   : >"$calls"
 }
@@ -134,6 +136,7 @@ PUSH=secret_swarm_services_attic_push-token
 URL=secret_swarm_services_attic_url
 CACHE=secret_swarm_services_attic_cache
 KEY=secret_swarm_services_attic_public-key
+KEY_PATH=secret/swarm/services/attic/public-key
 ENVFILE=$dir/secrets/server.env
 
 expect() { # <description> <got> <want>
@@ -208,12 +211,12 @@ expect "exit status" $? 0
 expect "no token minted" "$(n '^atticadm')" 0
 expect "no create call" "$(n '^bao put')" 0
 expect "no cache create" "$(n '^attic cache create')" 0
-expect "the pull token looked the cache up" "$(n "^attic cache info local:grid | token=$pull")" 1
+expect "the pull token looked the cache up, and read its key" "$(n "^attic cache info local:grid | token=$pull")" 2
 expect "pull token unchanged" "$(stored $PULL)" "$pull"
 expect "push token unchanged" "$(stored $PUSH)" "$push"
 expect "address, name and key unchanged" "$(stored $URL)$(stored $CACHE)$(stored $KEY)" "http://cache.examplegridgrid:FAKEKEY"
 
-case="values the operator stored over the minted ones are kept"
+case="values the operator stored over the minted ones are kept, except the public key"
 for leaf in $PULL $PUSH $URL $CACHE $KEY; do
   printf '%s' "operator-$leaf" >"$dir/store/$leaf"
 done
@@ -221,12 +224,14 @@ done
 run "$PROVISION"
 expect "exit status" $? 0
 expect "no token minted" "$(n '^atticadm')" 0
-expect "nothing written" "$(n '^bao put')" 0
+expect "only the public key is written" "$(n '^bao put')" 1
+expect "the put replaces, it does not create" "$(n "^bao put cas=0 $KEY_PATH")" 1
 expect "the operator's push token is still stored" "$(stored $PUSH)" "operator-$PUSH"
 expect "the operator's pull token is still stored" "$(stored $PULL)" "operator-$PULL"
-expect "the operator's address, name and key are still stored" \
-  "$(stored $URL)$(stored $CACHE)$(stored $KEY)" "operator-${URL}operator-${CACHE}operator-${KEY}"
-expect "the cache lookup used the operator's pull token" "$(n "^attic cache info local:grid | token=operator-$PULL")" 1
+expect "the operator's address and name are still stored" \
+  "$(stored $URL)$(stored $CACHE)" "operator-${URL}operator-${CACHE}"
+expect "the key is the cache's, not the operator's" "$(stored $KEY)" "grid:FAKEKEY"
+expect "the cache lookup used the operator's pull token, twice" "$(n "^attic cache info local:grid | token=operator-$PULL")" 2
 printf '%s' "$pull" >"$dir/store/$PULL"
 printf '%s' "$push" >"$dir/store/$PUSH"
 printf '%s' http://cache.example >"$dir/store/$URL"
@@ -243,6 +248,48 @@ expect "no secret rewritten" "$(n '^bao put')" 0
 expect "cache created" "$(n '^attic cache create')" 1
 expect "pull token unchanged" "$(stored $PULL)" "$pull"
 
+case="a cache created again with another key replaces the stored key"
+rm -f "$dir/cache-exists"
+printf '%s' grid:NEWKEY >"$dir/live-key"
+: >"$calls"
+run "$PROVISION"
+expect "exit status" $? 0
+expect "cache created" "$(n '^attic cache create')" 1
+expect "the stored key is the new cache's" "$(stored $KEY)" "grid:NEWKEY"
+expect "one key written, replacing" "$(n "^bao put cas=0 $KEY_PATH")" 1
+expect "nothing else written" "$(n '^bao put')" 1
+expect "pull token unchanged" "$(stored $PULL)" "$pull"
+
+case="a stored key equal to the cache's is not written again"
+: >"$calls"
+run "$PROVISION"
+expect "exit status" $? 0
+expect "nothing written" "$(n '^bao put')" 0
+expect "the key is still the new one" "$(stored $KEY)" "grid:NEWKEY"
+
+case="a store that refuses the update keeps the key and the unit succeeds"
+printf '%s' grid:FAKEKEY >"$dir/store/$KEY"
+: >"$calls"
+run "$PROVISION" 'UPDATE_FAIL=Error making API request. Code: 403. Errors: * 1 error occurred: * permission denied'
+expect "exit status" $? 0
+expect "the update was tried" "$(n "^bao put cas=0 $KEY_PATH")" 1
+expect "the old key stays" "$(stored $KEY)" "grid:FAKEKEY"
+expect "the refusal is said" "$(grep -c 'refuses to update' "$dir/err" || true)" 1
+
+case="any other failure of the update fails the unit"
+: >"$calls"
+run "$PROVISION" UPDATE_FAIL="connection refused"
+expect "exit status" $? 1
+expect "the old key stays" "$(stored $KEY)" "grid:FAKEKEY"
+
+case="a cache that reports no key fails the unit and writes nothing"
+printf '' >"$dir/live-key"
+: >"$calls"
+run "$PROVISION"
+expect "exit status" $? 1
+expect "nothing written" "$(n '^bao put')" 0
+rm -f "$dir/live-key"
+
 case="no tokens are minted while the server is down"
 reset
 run "$ENSURE_JWT"
@@ -277,7 +324,7 @@ run "$ENSURE_JWT"
 run "$PROVISION"
 expect "no token among the client's arguments" "$(grep -c -- '^attic [^|]*tok-' "$calls" || true)" 0
 # The control: the client did see tokens, through its config file.
-expect "tokens seen through the config file" "$(grep -c -- '| token=tok-' "$calls" || true)" 4
+expect "tokens seen through the config file" "$(grep -c -- '| token=tok-' "$calls" || true)" 5
 
 if [ "$failures" -ne 0 ]; then
   echo "$failures of $count checks failed" >&2