stack/packages/mosaic/framework/systemd/user/README.md

Mosaic tmux Fleet PoC

This directory contains the first durable tmux-backed fleet primitives for the Mosaic software-factory model.

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.
• mosaic-agent@.service — user-mode template for one reusable agent session.
• mosaic-interaction-agent@.service — 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. mosaic fleet install validates the roster, installs the units and helpers, and writes private roster-derived projections before any service is started.

# 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.