chore: consolidate new foundation and archive v1 (#1495)

2026-09-07 12:32:57 -05:00
parent 9a5fbdbda7 5d27700026
commit 127a54fdff
3511 changed files with 727899 additions and 10 deletions
@@ -0,0 +1,80 @@
+# 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.
+- `[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:
+
+```text
+~/.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:
+
+```text
+~/.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:
+
+```text
+~/.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.
+
+```bash
+# 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:
+
+```bash
+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.