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.

Local customization

Per-agent overrides live outside the package in:

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

Example:

MOSAIC_TMUX_SOCKET=mosaic-fleet
MOSAIC_AGENT_RUNTIME=claude
MOSAIC_AGENT_WORKDIR=$HOME/src/your-project
# Optional escape hatch for PoC/canary agents:
# MOSAIC_AGENT_COMMAND=mosaic yolo claude

Manual canary sequence

mkdir -p ~/.config/systemd/user ~/.config/mosaic/tools/fleet ~/.config/mosaic/fleet/agents
cp packages/mosaic/framework/systemd/user/mosaic-*.service ~/.config/systemd/user/
cp packages/mosaic/framework/tools/fleet/*.sh ~/.config/mosaic/tools/fleet/
chmod +x ~/.config/mosaic/tools/fleet/*.sh
systemctl --user daemon-reload
systemctl --user start mosaic-tmux-holder.service
systemctl --user start mosaic-agent@canary.service
tmux -L mosaic-fleet ls

# For an operator-interaction service, the roster/env identity selects the
# generic unit instance; no service source is renamed for an instance.
systemctl --user start mosaic-interaction-agent@<agent-name>.service
MOSAIC_AGENT_NAME=<agent-name> \
MOSAIC_AGENT_RUNTIME=pi \
MOSAIC_AGENT_MODEL=openai/gpt-5.6-sol \
MOSAIC_AGENT_REASONING=high \
MOSAIC_AGENT_TOOL_POLICY=operator-interaction \
  ~/.config/mosaic/tools/fleet/print-interaction-effective-policy.sh

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