fred
61a907a12f
`mosaic fleet start` returned 0 over three dead panes. The launcher knew, and said the wrong thing at the wrong severity to the wrong layer. The pane runs `mosaic yolo <runtime>` under PANE_PATH with a cleared environment. When that binary is absent the pane dies in under a second, tmux destroys the session, and the diagnostic goes with it. The launcher then found no PANE_PID, printed a WARNING about the *heartbeat sidecar*, and exited 0 — so systemd logged "Finished ... successfully" and `fleet start` reported success. `fleet ps` was the only component telling the truth. Two changes, both in start-agent-session.sh: 1. Before any effect, resolve `mosaic` and the roster's runtime against PANE_PATH — the pane's own view of the path, not the launcher's. `mosaic yolo <runtime>` calls checkRuntime(runtime) and looks for a binary named exactly like the runtime, so this asks the same question the pane will ask a moment later, while an operator can still see the answer. Absent binary -> exit 69, code=missing-binary, no session created. 2. Replace the dead-pane WARNING+exit-0. An absent session one second after new-session is a runtime that died on startup, not a heartbeat problem -> exit 69, code=pane-did-not-survive, with the command to run by hand to see why. A present session with no pane PID after five attempts -> code=pane-pid-unresolved. Neither branch kills the session; destroying a possibly-live pane on a guess is worse than leaving it for inspection. Exit 69 (EX_UNAVAILABLE) is deliberate: the 64s already in this file mean the projection was bad, and here the data is fine and the host is not ready. Callers separate the cases by `code=`, the same way fail_env's codes share 64. This propagates for free. `fleet start` calls runChecked() for the holder and each agent, and runChecked throws on non-zero, so layers 4 and 5 stop lying without a TypeScript change. Two adjacent defects are left for a follow-up issue rather than widened into this diff: the per-agent loop aborts on the first failure instead of attempting all and reporting an aggregate, and runChecked's bare throw surfaces the launcher's message under a Node unhandled-rejection stack trace because program.parse() is synchronous. Tests: - test-start-agent-session.sh gains three cases: `mosaic` absent from the pane path, the runtime absent from the pane path, and a pane that does not survive. Each was verified individually red against the unmodified origin/next launcher. - The two cases asserting a valid launch now supply a pane PID. Until now the suite's one success path was itself a dead pane the launcher reported as fine. - The harness fakes `npm` so PANE_PATH stops depending on whatever the host has installed, and fails loudly if the host provides `mosaic` or `pi` in the system path, where the missing-binary cases would not be measurable at all. - test-fleet-units.sh gains a `pi` shim in its runtime bin. The real-tmux harness named `pi` in its roster and never installed it; the new preflight caught it. Refs #1241
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.