fred
67f5014cc0
Two follow-ups from the canary red->green run and scooby's review.
1. The v2 refusal in `add`/`remove` was a bare `throw`, which reaches the CLI
top level uncaught and prints the guidance under a Node stack trace. The
message *is* the point of the refusal, so it now goes through
`command.error()` — the same clean path the roster-config error uses.
Caught on canary, not in review: the unit tests asserted the message text
and passed either way.
2. The unit-template test asserted only that ConditionPathExists is present.
Presence is not effect. Added two tests for the parts that can drift in
code while that assertion still passes: the condition resolving to exactly
the file the fleet writes (%h/%i rendered against a real install), and the
launcher genuinely failing on an absent generated env (exit 64,
`missing-file`) — which is what makes the condition load-bearing rather
than decorative.
systemd is not available in the suite, so the effect itself was measured on
canary (2026-08-16), roster v2 generation 3:
with the condition: start rc=0, Result=success, ConditionResult=no,
journal "skipped, unmet condition check"
condition removed by
drop-in, nothing else: start rc=1, Result=exit-code, ExecMainStatus=64,
unit failed, "agent environment rejected: missing-file"
Canary red->green for the three commands, same v2 roster, side by side:
fleet ps 0.0.50-next.2413 rc=1 -> branch rc=0 (3 agents listed)
fleet install 0.0.50-next.2413 rc=1 -> branch rc=0
fleet remove <name> 0.0.50-next.2413 rc=1 -> branch rc=1, refusal naming
delete + apply
All three previously failed with "Fleet roster has unknown field(s):
generation." The #791 negative was measured too: the six existing
*.env.generated files were untouched by `install` (mtimes 20+ minutes older
than the run).
Gates: typecheck 0, eslint 0, prettier clean, fleet specs 382 passed, new spec
10/10 with the fix and 9/10 red against origin/next (the 10th passes there for
an unrelated reason and is annotated as such). Full suite: only
mutator-gate.acceptance.spec.ts fails, pre-existing on origin/next.
Still true and still worth saying: a correct fix here shows install rc=0 and
start rc=0 and STILL no live seat. #1240 (tmux absent) is upstream, #1241
(start reports lifecycle-complete over dead panes) and the missing agent
runtime are downstream.
Refs #1237
Reviewed-by: scooby (by git comms; cannot file a Gitea review from fomo-lin)
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:
~/.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.