# Mosaic Fleet Rosters

The local fleet canary uses a product-owned roster schema with site-owned roster
files. Product examples live here; active local rosters should live outside the
package, normally at:

```text
~/.config/mosaic/fleet/roster.yaml
```

The default tmux socket is `mosaic-fleet` so fleet commands do not touch the
default tmux server. The roster is the desired-state authority; generated environment files are
rebuildable projections, never a second source of configuration.

## Brain-home split (fleet state vs framework templates)

When a mosaic-brain clone is present, fleet **state** resolves from the brain
home while framework templates and dispatch state stay in the config home
(three-tree model, canon `docs/STRUCTURE-CANON.md` §2):

| Path                                                                            | Without brain (legacy)                | With brain                     |
| ------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------ |
| `fleet/agents/<seat>.env.*`                                                     | `~/.config/mosaic/fleet/agents/`      | `~/.mosaic/fleet/agents/`      |
| `fleet/roles.local/` (overrides)                                                | `~/.config/mosaic/fleet/roles.local/` | `~/.mosaic/fleet/roles.local/` |
| `fleet/profiles/` (working copies)                                              | `~/.config/mosaic/fleet/profiles/`    | `~/.mosaic/fleet/profiles/`    |
| `fleet/roster.yaml`, `fleet/roles/` (baseline), `fleet/run/`, `fleet/services/` | `~/.config/mosaic/fleet/…`            | unchanged (config home)        |

Activation (`packages/mosaic/src/fleet/brain-home.ts`, mirrored in
`tools/fleet/start-agent-session.sh`):

1. `MOSAIC_BRAIN_HOME` env var — explicit, always wins.
2. Canonical `~/.mosaic` — adopted only when `MOSAIC_HOME` is the default
   `~/.config/mosaic` AND `~/.mosaic/fleet/agents` exists. Custom
   `--mosaic-home` values (tests, sandboxes, canaries) never adopt, keeping
   them hermetic.
3. Otherwise the config home (legacy single-tree behavior).

Seat env dirs under a brain are subject to the same privacy boundary (0700
dirs, 0600 files); `.env.generated` files are structure-valuable and tracked
in the brain repo, hand-maintained `.env`/`.env.local` stay ignored and private.

## Examples

- `examples/minimal.yaml` starts one local canary slot.
- `examples/local-canary.yaml` starts a small generic dogfood fleet.
- `examples/operator-interaction.yaml` is an example Pi operator-interaction
  service; replace its example agent name before provisioning.

## Operator interaction service

`services/operator-interaction.yaml` pins the Pi runtime, GPT-5.6 Sol model,
high reasoning, and the `operator-interaction` tool policy. The agent identity
is provisioning data: choose a roster name, generate its per-agent environment
file, then start the matching generic systemd instance. The service fails before
launch if the configured identity does not match the instance or any pinned
policy field drifts.

The installed `tools/fleet/print-interaction-effective-policy.sh` prints only
the resolved name, runtime, model, reasoning, and tool policy. It never reads
or prints credential variables.

## Generated agent environment boundary

`mosaic fleet install` writes a private deterministic projection at
`~/.config/mosaic/fleet/agents/<agent>.env.generated`. It may relocate only approved local machine
data to `<agent>.env.local`; generated keys, arbitrary commands, secret-like keys, duplicate keys,
unknown keys, and unsafe permissions fail before a tmux session is created. Legacy `.env` input is
regenerated, relocated, or quarantined and is not a launch authority.

See [`docs/fleet/reference/generated-env-boundary.md`](../../../../docs/fleet/reference/generated-env-boundary.md)
for allowed local keys and the USC downstream interface evidence.

Initialize a roster:

```bash
mosaic fleet init --profile minimal --write
mosaic fleet install-systemd
mosaic fleet start
mosaic fleet verify
```