fix(#1264): bootstrap fleet identity without a TTY

2026-08-16 17:37:32 -05:00
parent 476db12b92
commit 43fa047787
21 changed files with 1255 additions and 11 deletions
@@ -0,0 +1,59 @@
+# Fleet Unattended First Start
+
+> **Status:** Current for roster-owned local fleet launches after issue #1264 lands. Runtime
+> installation and provider authentication remain separate prerequisites.
+
+A fleet seat started by systemd has no operator at its pane. On its first launch, Mosaic must not
+stop at the interactive identity wizard.
+
+## What happens on first start
+
+When `MOSAIC_AGENT_NAME` names an exact member of the installed fleet roster and top-level identity
+contracts are absent, the launcher:
+
+1. validates the exact roster member and installed fleet communications helper;
+2. reads the shipped generic contracts from
+   `~/.config/mosaic/defaults/SOUL.md` and `defaults/USER.md`;
+3. creates only the missing top-level `SOUL.md` and `USER.md` as owner-private files;
+4. preserves any existing top-level identity file byte-for-byte; and
+5. launches the runtime with the roster member's exact agent/session name and role/class in composed
+   context.
+
+The generic defaults do **not** make every seat the same identity. They provide a shared behavioral
+base. The canonical roster row supplies each seat's exact name, class, peers, socket, and authority.
+
+## Operator behavior
+
+A normal standalone launch without a fleet identity still uses the interactive wizard when
+`SOUL.md` is absent:
+
+```bash
+mosaic pi
+```
+
+A roster-owned seat may be started without attaching to its pane:
+
+```bash
+mosaic fleet start <exact-roster-name>
+```
+
+Mosaic refuses before runtime execution if the requested member is absent, a required default is
+missing or unsafe, or an existing identity contract is not a safe regular file. Repair the named
+path and retry the same exact roster member; do not copy another seat's personalized identity.
+
+## Separate prerequisites
+
+This behavior clears the Mosaic identity-wizard wall only. A clean host still needs:
+
+- the declared runtime installed on the pane PATH;
+- the fleet transport and generated unit assets; and
+- runtime/provider authentication appropriate to that seat.
+
+Those checks are separate so a successful identity bootstrap is not reported as a fully authenticated
+agent session.
+
+## Related
+
+- [Administrator runbook](../../ADMIN-GUIDE/operations/fleet-unattended-first-start.md)
+- [Developer architecture](../../DEVELOPER-GUIDE/architecture/fleet-first-start-identity.md)
+- [Verification report](../../reports/qa/2026-08-16-1264-unattended-first-start.md)