matrix: mint the appservice sender token in the matrix container

A swarm runs one homeserver and a homeserver has one appservice sender
account, so "mint it once" is a property of the thing being minted
rather than something a lock has to enforce. That is what makes this
account the one to move first: no trigger route, no controller change
and no agent list — a boot-time oneshot beside tuwunel is the whole
mechanism.

`swarm-matrix-minter` runs inside `containers.hive-matrix`, which
already holds the appservice token: the rendered registration is bound
in read-only because that is how tuwunel is handed it. What the
container lacked was an identity of its own, so this adds one — a leaf
from the store's CA with a grant of exactly one path, not the hive's
leaf, which reads every secret in the store.

Both ends of the credential ship here. The minter reads the path it
publishes to before it touches the homeserver, and returning on a
non-empty read IS the "only once"; `hive-c0re`'s `ensure_hive_user`
reads the same path, authenticating with the hive name already in
`HYPERHIVE_HIVE_NAME`. The existing mint-then-`M_USER_IN_USE`-login
ladder stays as the fallback for a store that is empty, unconfigured or
unreachable, which is every swarm deployed before this — so nothing
needs backfilling and nothing breaks if the rest of the sequence never
lands.

The credential is not an admin credential, and is not named like one.
It is the access token of the appservice registration's own
`sender_localpart` — `@hive:<server_name>`, an account the homeserver
creates for itself when it loads the registration. The store path is
`swarm/services/matrix/sender-token`, the host path is
`matrix/access-token`, and the homeserver no longer runs an
`admin_execute` promotion for that account at boot. Everything the hive
provisions with it — the Space, the chat room, their hierarchy and join
rules, the invites — rides on being the creator of those rooms at power
level 100, not on homeserver admin; there is no Synapse admin API here
to need, tuwunel has none.

Two operations do need an admin *sender* and therefore stop working:
`hivectl matrix promote-user` and `hivectl matrix reset-password`, both
`!admin …` messages into `#admins:<server>`, plus the password-reset
recovery path that an agent with a lost password file falls back to.
They are swarm-level operations and are left failing loudly rather than
served by an over-privileged token every other call site would also
carry. The sweep's own admin-rights check and self-repair go with them:
an account that is deliberately not an admin has nothing to check.

`ephemeral = false` stays, and hive root can still read the container's
filesystem. Accepted: what this buys is identity separation — no hive
*process* holds or reads the appservice token — not physical isolation.

Refs #4345

docs/getting-started/setup.md

@@ -229,7 +229,7 @@ control: [`swarm/ui.md`](../swarm/ui.md).
 ### 6 · Matrix
 
 ```bash
-# Ensure the hive-internal admin account exists first
+# Ensure the hive's own `@hive:` account exists first
 hivectl matrix sync-admin
 
 # Provision ruth's own matrix account — same bootstrap-bypass reasoning
@@ -293,7 +293,7 @@ See [`tools/hivectl.md`](../tools/hivectl.md) for every `hivectl` verb.
 
 - **No forge admin token is stored in any agent state dir.** Agents
   hold a regular agent token in their `forge-token` file; sensitive
-  creds (the core token, the matrix admin token) live on the host.
+  creds (the core token, the `@hive:` matrix access token) live on the host.
 - All config changes (forge PRs on `agent-configs/<name>`) go through
   operator approval — agents can't unilaterally rebuild containers, by design.
   See [`boundary.md`](../trust-boundary/boundary.md) and [`security.md`](../trust-boundary/security.md).

docs/integrations/matrix.md

@@ -147,29 +147,31 @@ a token.
    (`hive-matrix-daemon.path` watching for `matrix-token` appearance)
    brings the daemon up on the same boot cycle anyway.
 
-### The admin account, and why it needs no first-user luck
+### The `@hive:` account, and why it is not an admin
 
 `@hive:<server_name>` is the appservice's own `sender_localpart`, which
 the homeserver creates itself when it loads the registration — on a
 zero-user database, inside startup, before the HTTP listener accepts
-anything. Its **admin rights** then come from an explicit
-`make_user_admin`, run by tuwunel's `admin_execute` in the same startup
-and likewise before the listener — so a fresh hive has a joined,
-power-level-100 admin on its first boot.
+anything. It is an **ordinary account**: nothing promotes it, and the
+homeserver runs no `admin_execute` for it.
 
-This replaces a dependency on being the first account ever registered,
-which was fragile in both directions: the design excludes an
-appservice-created account from that automatic grant, and on a homeserver that
-already had users the rule never fired at all.
+It needs no promotion for what the hive does with it. Creating the hive
+Space and the chat room, writing their hierarchy and join rules, and
+inviting agents into them are all ordinary client calls that ride on
+being the rooms' own creator at power level 100 — there is no homeserver
+admin in any of it. (There is no Synapse admin API here either; tuwunel
+has none.)
 
-Tuwunel doesn't support bootstrapping promotion over the API, and
-that's upstream's design rather than a gap: it only treats an admin-room message as a
-command when its sender is already an admin. `admin_execute` is the one
-lever with no sender to check. hive-c0re re-checks the result on every
-sweep by reading the admin account's own joined-rooms list; if the rights
-are missing it says so, names
-`systemctl restart container@hive-matrix` as the fix, and carries on —
-agent accounts, the hive Space and the chat room need no admin.
+Two operations do need an admin **sender**, and neither works today:
+`hivectl matrix promote-user` and `hivectl matrix reset-password`. Both
+are `!admin …` messages into `#admins:<server_name>`, and tuwunel only
+treats a message as a command when its sender is already an admin. They
+are swarm-level operations and are being rehomed as such; until then
+they fail with the admin room's refusal rather than being served by an
+over-privileged credential that every other call site would also carry.
+The one hive-side path that depends on them is the password-reset
+auto-recovery for an agent whose stored password is gone — the ordinary
+appservice re-login above is unaffected.
 
 <details><summary>Upgrading a hive that used the registration token</summary>
 
@@ -185,10 +187,10 @@ restarts, so the first boot after the switch already has both halves.
 - **The per-agent sweep honours existing token files.** It skips any
   agent that already has a `matrix-token`, so it re-registers no account
   and displaces no session.
-- **The admin account is already admin** on such a hive (it won the
-  first-user grant when the hive was new), so the startup promotion is a
-  no-op — upstream's `make_user_admin` short-circuits when the user is
-  already joined at power level 100.
+- **`@hive:` may already be an admin** on such a hive (it won the
+  first-user grant when the hive was new). Nothing here demotes it; the
+  homeserver simply no longer promotes it, so a hive built fresh has an
+  ordinary account and an older one keeps whatever standing it acquired.
 - **`/var/lib/hyperhive/matrix-register-token` stays on disk**, read by
   nothing. Delete it or leave it; neither does any harm.
 - **`registrationTokenFile` is a removed option.** A config that still
@@ -237,7 +239,7 @@ Initial rollout settings:
 ## Hive Matrix Space
 
 On first boot, after hive-c0re provisions all agent accounts, it
-creates a private **Matrix Space** named `"hive"` using the admin
+creates a private **Matrix Space** named `"hive"` using the `@hive:`
 account (`@hive:<server_name>`) and invites every provisioned agent
 into it. This gives the operator a single Space in FluffyChat or any
 Matrix client that groups all agent-to-agent + operator rooms in one

docs/tools/hivectl-cli.md

@@ -193,9 +193,9 @@ For an existing agent, persists the token to its state dir; for a human/other ac
 
 ## `hivectl matrix sync-admin`
 
-Provision (or re-provision) the hive system admin matrix account.
+Provision (or re-provision) the hive's own `@hive:` matrix account.
 
-Runs automatically on startup; run manually to recover a missing admin token.
+Runs automatically on startup; run manually to recover a missing access token.
 
 **Usage:** `hivectl matrix sync-admin`
 

docs/tools/hivectl.md

@@ -64,7 +64,7 @@ running (`services.hyperhive.deploy.matrix.enable = true`).
 hivectl matrix create-user iris         # provision (or re-provision) matrix account for agent `iris`
 hivectl matrix create-user mara         # create matrix account for a human; prints access_token to stdout
 hivectl matrix create-user mara --password hunter2  # set a client-login password
-hivectl matrix sync-admin               # provision / refresh the hive internal admin account
+hivectl matrix sync-admin               # provision / refresh the hive's own `@hive:` account
 hivectl matrix promote-user mara        # promote an existing matrix user to homeserver admin
 hivectl matrix reset-password iris      # generate and set a new random password for `iris`; prints it
 hivectl matrix invite mara              # invite a user to the hive Space
@@ -74,19 +74,21 @@ hivectl matrix invite @mara:server --room '#hive-chat:server'  # ...or to a spec
 - `create-user`: for agents, persists the `access_token` to
   `<state>/matrix-token`. Skips registration when the file already
   exists — delete it first to force re-registration.
-- `sync-admin`: ensures the hive's internal admin matrix user exists
-  (used by `hive-c0re` for admin-room commands). Token persisted to the
-  admin token path. Safe to run again — idempotent.
+- `sync-admin`: ensures the hive's own `@hive:` matrix user exists
+  (the account `hive-c0re` provisions rooms with). Token persisted to the
+  access token path. Safe to run again — idempotent.
 - `promote-user`: promotes an already-registered user to homeserver
-  admin via the matrix admin API. Requires `sync-admin` to have run
-  first (needs a valid admin token).
-- `reset-password`: calls the matrix admin API to set a new random
-  password and prints it to stdout. Useful if an agent or human lost
+  admin by an `!admin` command in `#admins`. ⚠️ Needs an admin **sender**,
+  which `@hive:` is not — this operation is being rehomed at swarm level
+  and does not work from the hive today.
+- `reset-password`: asks the admin room to set a new random
+  password and prints it to stdout. ⚠️ Needs an admin **sender** too, so
+  it does not work from the hive today either. Useful if an agent or human lost
   credentials.
 - `invite`: invites a matrix user (full `@user:server` or a bare
   localpart, qualified with the homeserver's `server_name`) to the hive
-  Space by default, or to a `--room` id / `#alias`. Uses the hive admin
-  token; the admin account must be a member of the target room with
+  Space by default, or to a `--room` id / `#alias`. Uses the `@hive:`
+  token; the account must be a member of the target room with
   invite power (it owns the hive Space, so that case always works).
   Idempotent — already-member / already-invited is a no-op.