SouveraineOS/docs/provisioning-gaps.md

# Provisioning gaps — what got hand-filled on 2026-07-16

Every item here is a manual intervention performed during the first live
federation test (laptop + Pixel 3, agent Souveraine). Each one is a gap the
real setup flow — the node commission ceremony FEDERATION.md parks — must
close. This file is the evidence log: if we don't record what we did by hand,
the ceremony gets designed from memory and misses them.

Ordering is by how badly the gap bit, not by build order.

## 1. Agent provider config drift — silent until b4dc39e

**What happened:** Souveraine's `agent.json` carried `provider: claude` with an
empty key while its model said `glm-5.2`. A model sweep updates `model`; nothing
polices `provider`. Every turn 401'd against Anthropic's OpenAI-compat endpoint
and, before the error-event fix, rendered as the agent going mute.

**What the system must do:** a preflight at agent load (or config write):
resolve the agent's provider chain and fail loudly if the key is empty or the
provider unreachable. "Can this agent speak?" is a checkable invariant, not a
runtime surprise.

## 2. Memfs remote naming — `gitea` vs `origin`

**What happened:** `memory sync` requires an `origin` remote. Existing memfs
checkouts carried the same URL under the name `gitea`. Fixed by aliasing on
both machines by hand.

**What the system must do:** commission-time provisioning names the shared
remote `origin`, and/or `sync` accepts a configured remote name. Existing
checkouts need a migration nudge, not a silent error.

## 3. Cloned machine identity — the shared-seed trap

**What happened:** the phone's `~/.souveraine` was cloned from the laptop, so
both machines held the same `seed-id` (6344f24e…) for months. Left alone, both
would have pushed the same `instance/` branch and the federation test would
have proven nothing. Split by hand: laptop `machine init --migrate-from`,
phone `machine init --fresh`.

**What the system must do:** commission ceremony detects a seed that already
exists in the federation (registry or remote branch collision) and forces the
fresh-mint path. A cloned filesystem must not silently become a cloned
identity.

## 4. Agent server is a hand-started process

**What happened:** on both machines `souveraine server` runs as a
`setsid`/nohup user process logging to `/tmp`. The phone hard-reset and the
server simply didn't exist afterward; restart was manual over SSH. Its logs
die with `/tmp`.

**What the system must do:** a user systemd unit (`souveraine-server.service`)
with journal logging and restart policy, installed by packaging, enabled at
commission. The machined precedent already exists — mirror it.

## 5. No crash forensics on the phone

**What happened:** the phone hard-reset mid-`souveraine chat` (14:11). No
shutdown record, no coredumps, journal stops mid-write, `/sys/fs/pstore` is
empty. The reset is unattributable — thermal, watchdog, TZ/remoteproc wedge —
because nothing was configured to remember it.

**What the system must do:** wire ramoops/pstore (Android configures it on
this exact hardware — the reference answer, per the Android-is-the-reference
rule). Belongs in Pixel3Arch kernel/DT work, not the ceremony, but the
ceremony should *verify* pstore is live on phone-class nodes.

## 6. machined socket ACL doesn't survive restart

**What happened:** `usermod -aG souveraine` lands at next login; until then a
manual `setfacl` on `/run/souveraine` is needed after every machined restart.
Done by hand twice today.

**What the system must do:** packaging owns it — tmpfiles.d or group-writable
socket creation in machined itself, so a restart never strands the user
session.

## 7. Instance label ↔ glyph mapping doesn't exist agent-side

**What happened:** sync reports branches as machine-pubkey prefixes
(`instance/69bf24d7b185`). The laptop agent, asked whether the peer branch was
the phone, correctly refused to confirm — it has no stored association between
glyphs (▽●△△ / ▽■◑★) and instance labels, and said recording Casey's
assertion isn't verification. It was right.

**What the system must do:** the `memfs_commit` payload and `sync` output
should carry the glyph alongside the pubkey; the in-memfs `system/instances.md`
(which the phone agent wrote unprompted after reading the briefing) is the
durable half. Commission stamps the mapping; the agent never has to take it on
faith.

## 8. Binary deploys are scp + pkill by hand

**What happened:** deploy = scp from archdev, `sudo install`, then kill and
restart the server — including the recurring pkill-matches-own-ssh-cmdline
footgun, hit twice this session.

**What the system must do:** packaging (PKGBUILD or a deploy script in-repo)
plus the systemd unit from §4 makes deploy = install + `systemctl restart`.

## 9. New system files aren't surfaced to the agent

**What happened:** a briefing file written directly into the phone memfs was
invisible to the primary until the subconscious caught the false "no such
file" claim and corrected it mid-thread ([intrusive] surfacing — the
architecture working as designed, but as a backstop, not a flow).

**What the system must do:** memfs writes that arrive from outside the agent's
own tool path (human edits, sync merges) should generate the same felt signal
as local compaction — this is FEDERATION.md's receive-side doctrine; the local
case (files appearing on disk between turns) needs it too.

---

Resolved during the same session, recorded for completeness: `hosted_agents`
announce read the wrong tree (`server/agents/` vs `agents/`) — fixed with a
regression test in `da410b1`; silent turn-death — fixed end-to-end error
events in `33068d6`/`b4dc39e`.