4.5 KiB
Fleet Launch Runbook
The local fleet roster is the sole writable desired-state authority for membership and launch policy. Generated environment files are rebuildable projections, not an operator-editable command surface.
Launch chain
| Layer | Responsibility |
|---|---|
| Roster | fleet/roster.yaml supplies the agent name, class, supported runtime, model, reasoning, tool policy, workdir, and tmux socket. |
| Projection writer | Renders deterministic fleet/agents/<name>.env.generated from the roster. |
| Optional local data | Reads a strict, data-only fleet/agents/<name>.env.local; it cannot shadow generated keys. |
| systemd | Starts the launcher with env -i and fixed bootstrap data. It does not preload either environment file. |
| session launcher | Validates generated and local data before it queries, creates, or stops an exact tmux session. |
| runtime launch | Derives the fixed mosaic yolo <runtime> argument array from validated roster data, then seeds the runtime contract. |
The launcher never sources or evals an environment file and never accepts an environment-supplied
command. MOSAIC_AGENT_COMMAND, command/channel overrides, unknown keys, generated-key shadowing,
secret-like key names, duplicate keys, comments, quoted/export syntax, and unsafe values are rejected.
Generated and local files
<name>.env.generated is complete, deterministic, and written only by Mosaic. Its ordered keys are:
MOSAIC_AGENT_NAME=<roster name>
MOSAIC_AGENT_CLASS=<roster class>
MOSAIC_AGENT_RUNTIME=<roster runtime>
MOSAIC_AGENT_MODEL=<roster model hint>
MOSAIC_AGENT_REASONING=<roster reasoning>
MOSAIC_AGENT_TOOL_POLICY=<roster tool policy>
MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
MOSAIC_TMUX_SOCKET=<roster socket or empty>
The generated launch contract supports claude, codex, opencode, and pi. mosaic fleet add
rejects another runtime before it writes the roster or modifies generated, local, or quarantine state.
The legacy dogfood stub remains an observability-only canary on its separate mosaic-factory socket;
it has no generated-launch adapter and cannot be added through this path.
<name>.env.local is optional and may contain only non-secret machine data:
MOSAIC_RUNTIME_BINMOSAIC_HEARTBEAT_RUN_DIRMOSAIC_HEARTBEAT_INTERVALMOSAIC_CLAUDE_JSONCLAUDE_CONFIG_DIR
Paths must be safe absolute paths and the heartbeat interval must be a positive integer. Projection, local, and quarantine files must be private regular files; the managed directories must be real, private, non-symlink paths. Violations fail closed before tmux interaction.
Legacy input and diagnostics
A legacy <name>.env is input only during projection generation. Roster-owned keys are regenerated;
valid allowed local data can move to .env.local; invalid legacy input is privately retained at
<name>.env.quarantine. Neither legacy nor quarantine files are launch authority.
Diagnostics expose only rule code, key name, and a SHA-256 content hash. They do not reveal command text, credentials, or other values.
Launch and stop behavior
The launcher obtains the agent's socket only from the validated generated projection. It creates or
checks the exact =<agent-name> tmux target; it never uses an ambient socket or fuzzy session match.
The same strict parser runs before exact-stop behavior. A fresh native Pi heartbeat remains authoritative;
the shell sidecar only provides fallback state when the native marker is stale or absent.
mosaic fleet comms-block <role> can inspect the role's resolved Fleet-Comms block. It is a read-only
inspection tool and fails loudly for an unknown role or missing roster.
Current M2 boundary
FCM-M2-001 supplies generated/local parsing, validation, projection, quarantine, and launch-boundary evidence only. It does not authorize roster CRUD expansion, reconciliation, lifecycle changes, remote or connector mutation, site canaries, or migration. M3 must establish the local reconcile/lifecycle path; M4 separately provides migration preview, canary, and rollback gates.