feat(fleet): brain-home split — fleet state under ~/.mosaic, templates stay config-home
ci/woodpecker/pr/ci Pipeline was successful

Three-tree model per canon STRUCTURE-CANON §2 (first carried by the USC
estate brain): seat launch envs, roles.local overrides, and profile
working copies are user-owned fleet state and resolve from the brain home
(~/.mosaic) when one is active; roster.yaml, baseline roles, run/, and
services stay under the config home (~/.config/mosaic).

Resolution (packages/mosaic/src/fleet/brain-home.ts, mirrored in
tools/fleet/start-agent-session.sh):
1. MOSAIC_BRAIN_HOME env — explicit, always wins
2. canonical ~/.mosaic — adopted only when MOSAIC_HOME is the default
   ~/.config/mosaic AND ~/.mosaic/fleet/agents exists (custom
   --mosaic-home never adopts: tests/sandboxes stay hermetic)
3. else legacy single-tree behavior

Call sites wired: resolveFleetPaths, fleet regen, fleet-agent-crud,
fleet-migration, personas overrideDir, profiles dir, reconciler
projections, generated-env boundary (validate + ensure + reject split
state across trees).

Tests: brain-home.spec (8), generated-env-boundary brain case, bash
launcher brain + no-brain control cases; full fleet surface 733 green.
Pre-existing unrelated failure noted: uninstall.spec 'missing mosaicHome'
throws EACCES on this host with and without this change.
This commit is contained in:
Zane
2026-08-17 21:27:05 -05:00
parent 8199261caa
commit d04ff3b9f1
14 changed files with 362 additions and 17 deletions
@@ -80,6 +80,26 @@ safe_path "$MOSAIC_HOME" || fail_env unsafe-path MOSAIC_HOME "$MOSAIC_HOME"
FLEET_DIR="$MOSAIC_HOME/fleet"
AGENT_ENV_DIR="$FLEET_DIR/agents"
# Brain-home split (canon docs/STRUCTURE-CANON.md §2): seat launch envs live
# under the brain home's fleet/agents when a brain is active; roster, roles
# baseline, and runtime state (fleet/run) stay under MOSAIC_HOME.
# Resolution mirrors packages/mosaic/src/fleet/brain-home.ts:
# 1. MOSAIC_BRAIN_HOME env (explicit, always wins)
# 2. ~/.mosaic — adopted only when MOSAIC_HOME is the default config home AND
# ~/.mosaic/fleet/agents exists
# 3. MOSAIC_HOME (legacy single-tree)
BRAIN_HOME="${MOSAIC_BRAIN_HOME:-}"
if [ -z "$BRAIN_HOME" ]; then
BRAIN_HOME="$MOSAIC_HOME"
if [ "$(cd "$MOSAIC_HOME" 2>/dev/null && pwd -P)" = "$HOME/.config/mosaic" ] \
&& [ -d "$HOME/.mosaic/fleet/agents" ]; then
BRAIN_HOME="$HOME/.mosaic"
fi
fi
if [ "$BRAIN_HOME" != "$MOSAIC_HOME" ]; then
AGENT_ENV_DIR="$BRAIN_HOME/fleet/agents"
fi
assert_managed_directory "$MOSAIC_HOME"
assert_managed_directory "$FLEET_DIR"
assert_private_directory "$AGENT_ENV_DIR"