The lifecycle model follows the organization-neutral AI Guide playbook mosaicstack/aiguide:playbooks/tmux-fleet.md (commit 2a0b0b5): a dedicated holder owns the tmux server/socket; agent units join it and stop only their own exact-match session.

Layout

mosaic-tmux-holder.service — user-mode holder that owns the named tmux server.
[email protected] — user-mode template for one reusable agent session.
[email protected] — generic Pi operator-interaction template that fails fast when its pinned runtime policy is incomplete or changed.
test-fleet-units.sh — validates unit syntax and required relationships.

The agent template calls:

~/.config/mosaic/tools/fleet/start-agent-session.sh <agent-name>

which starts or reuses a tmux session on MOSAIC_TMUX_SOCKET.

Generated environment and local data

The roster-derived projection is written outside the package at:

~/.config/mosaic/fleet/agents/<agent>.env.generated

Systemd does not read either environment file. It starts the launcher with a fixed cleared bootstrap environment; before it creates, queries, or stops an exact agent tmux session, start-agent-session.sh strictly parses the generated projection and the optional local data file:

~/.config/mosaic/fleet/agents/<agent>.env.local

The local file may contain only safe machine-specific data (MOSAIC_RUNTIME_BIN, heartbeat paths or interval, and Claude configuration paths). It cannot override roster-derived keys, carry a command, or contain secret-like/unknown keys. Both files must be private regular files. Do not hand-edit the generated projection; update the roster and regenerate it instead. A legacy <agent>.env is consumed only for regeneration, strict relocation, or private quarantine and is never launch input.

See docs/fleet/reference/generated-env-boundary.md for the full contract.

Manual canary sequence

Use the roster and the supported installer; do not pre-create the agent environment directory or edit a generated projection. Before it writes any holder identity, tool, projection, or unit file, mosaic fleet install validates the fleet CLI and every distinct roster runtime through the exact pane PATH. The shared helper also unwraps /usr/bin/env shebangs, so a resolved Node script with no pane-visible Node fails before effects. mosaic fleet doctor reports the same named executable checks without mutation. After that preflight, install places the units and helpers and writes private roster-derived projections before any service starts.

# Create a site-owned canary roster. Inspect an existing roster before using --force.
mosaic fleet init --profile minimal --write
mosaic fleet install
systemctl --user daemon-reload
mosaic fleet start canary-pi
tmux -L mosaic-fleet ls

For an operator-interaction service, first put <agent-name> in the roster with the pinned Pi runtime, model, reasoning, and operator-interaction tool policy. Re-run mosaic fleet install after that roster change so it writes <agent-name>.env.generated; ambient MOSAIC_AGENT_* values are not launch authority. The generic unit instance uses that generated identity, and no service source is renamed for an instance:

mosaic fleet install
systemctl --user daemon-reload
systemctl --user start mosaic-interaction-agent@<agent-name>.service
~/.config/mosaic/tools/fleet/print-interaction-effective-policy.sh <agent-name>

Do not use tmux kill-server without -L mosaic-fleet; this pattern is meant to avoid disturbing the user's default tmux server.