fix(doctor): greenfield brain lock-in note (#1288, fred's finding 1)
ci/woodpecker/pr/ci Pipeline was successful

On a host with ~/.mosaic but no ~/.mosaic/fleet/agents, the implicit
resolution path passes silently with output byte-identical to a host with
no brain at all. fred traced why this is the shape web1 will be in
(#1288 comment 23133): nothing in product code ever creates
~/.mosaic/fleet/agents — the first fleet write resolves BEFORE creating
(generated-env-boundary), decides legacy, then manufactures the evidence
that keeps the host legacy. The three operator checks all agree and all
point the wrong way; the doctor is the only one that can disagree.

check_brain_home now emits a [NOTE] (not a WARN — nothing is broken yet)
when ~/.mosaic exists at the default config home without fleet/agents,
telling the operator the first 'mosaic fleet regen' locks in the legacy
tree. Explicit MOSAIC_BRAIN_HOME misconfiguration still warns (behavior
unchanged); custom homes stay silent (hermetic).

test-brain-home-check.sh: +3 cases (greenfield note, no-mosaic pass,
stray-mosaic-at-custom-home silence) — 11 total.
This commit is contained in:
Zane
2026-08-18 02:13:26 -05:00
parent f5ba042dfa
commit 4dec7875ba
2 changed files with 38 additions and 5 deletions
@@ -51,6 +51,8 @@ fix() { fix_count=$((fix_count + 1)); echo "[FIX] $*"; }
warn_count=0
warn() { warn_count=$((warn_count + 1)); echo "[WARN] $*"; }
note() { echo "[NOTE] $*"; return 0; }
pass() {
if [[ $VERBOSE -eq 1 ]]; then
echo "[OK] $*"
@@ -288,6 +290,18 @@ check_brain_home() {
brain="$(resolve_brain_home)"
if [[ "$brain" == "$MOSAIC_HOME" ]]; then
# Implicit-path greenfield case (#1288 comment 23133, fred's trace): nothing
# in product code creates ~/.mosaic/fleet/agents — the first fleet write
# resolves legacy (generated-env-boundary resolves before creating) and
# then manufactures the evidence that keeps the host legacy. On a host with
# ~/.mosaic but no fleet/agents, the three operator checks all agree and all
# point the wrong way; this doctor is the only one that can disagree, so it
# must say it — as a note, not a warn: nothing is broken yet.
if [[ "$(cd "$MOSAIC_HOME" 2>/dev/null && pwd -P)" == "$HOME/.config/mosaic" \
&& -d "$HOME/.mosaic" && ! -d "$HOME/.mosaic/fleet/agents" ]]; then
note "Fleet state home: $MOSAIC_HOME (legacy). NOTE: ~/.mosaic exists but carries no fleet/agents — the first 'mosaic fleet regen' on this host locks in the legacy tree. Create ~/.mosaic/fleet/agents first to adopt the brain."
return
fi
pass "Fleet state home: $MOSAIC_HOME (legacy single-tree; no brain adopted)"
return
fi