78 lines
4.5 KiB
Markdown
78 lines
4.5 KiB
Markdown
# 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 `source`s or `eval`s 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:
|
|
|
|
```dotenv
|
|
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_BIN`
|
|
- `MOSAIC_HEARTBEAT_RUN_DIR`
|
|
- `MOSAIC_HEARTBEAT_INTERVAL`
|
|
- `MOSAIC_CLAUDE_JSON`
|
|
- `CLAUDE_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.
|