Found by rehearsing the full install on a greenfield Debian 13 VM
(mosaic-sbx-dev) rather than on a host that already had a working Mosaic
tree. Each one is invisible on a developer machine and fatal on a new host.
1. Required system settings layer. The framework ships runtime/<harness>/
for claude, codex, opencode and pi but a settings.json only for claude,
so requiring the file made every pi, codex and opencode seat refuse to
compose. The system layer is now optional; what must exist is the
harness runtime directory, which is the thing that actually proves the
framework is installed and carries that harness.
2. Required mcpServers in canonical Claude settings. The shipped
settings.json has no such key, so `fleet agent new` refused to scaffold
any Claude seat. Absent now means the same as empty. A present but
wrong-typed value is still an error.
3. Never-enrolled hosts were told their auth directory "must be a real,
non-symlink directory", which reads as a tampering report when the real
situation is that nobody has logged in yet. Absent and wrong-shaped are
now separate messages, and the absent one names `mosaic auth enroll`.
4. A fleet seat whose host had no system SOUL.md reached checkSoul(),
which spawns the interactive `mosaic wizard` with inherited stdio. On a
detached tmux seat that parks the pane on a menu with nobody at it: the
session is live, the systemd unit reports fine, and no agent ever
starts. A seat's identity is its own SOUL.md, written by `fleet agent
new`, so the fleet path checks that and fails loudly instead.
Each fix has a regression test verified red against the unfixed source.
The launch.spec.ts seat fixtures gained a SOUL.md they always should have
had -- without it those tests were satisfied by whatever SOUL.md the
developer's real ~/.config/mosaic happened to contain.
Full suite before and after: the same 5 pre-existing failures in
mutator-gate.acceptance.spec.ts and install-ordering-guard.spec.ts,
1585 -> 1591 passing. typecheck and eslint clean.
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01WYgWocp36goy8hj2ui6ps1
