2.5 KiB
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:
- validates the exact roster member, its canonical class, and the installed fleet communications helper;
- reads the shipped generic contracts from
~/.config/mosaic/defaults/SOUL.mdanddefaults/USER.md; - creates only the missing top-level
SOUL.mdandUSER.mdas owner-private files; - preserves any existing top-level identity file byte-for-byte; and
- 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 retains its portable configuration path and still
uses the interactive wizard when SOUL.md is absent:
mosaic pi
A roster-owned seat may be started without attaching to its pane:
mosaic fleet start <exact-roster-name>
Mosaic refuses before runtime execution if the requested member is absent, its explicitly supplied ambient class is blank or conflicts with the roster, a required default is missing or unsafe, or an existing identity contract is not a safe regular file. Repair the named component 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.