stack/docs/scratchpads/f3-m3-update-reseed.md

F3-m3 — mosaic update re-seeds framework + relaunches agents (R13)

• Issue: #609 · Branch: feat/f3-m3-update-reseed

Gap (found in 0.0.39 production validation)

mosaic update installs the new npm CLI but never re-seeds ~/.config/mosaic/ from the package's bundled framework/. So the shipped custom Pi harness (agent-name export + native HB, 0.0.39) stays DORMANT until a re-seed — operators get the new CLI on a stale framework.

Implementation

• update-checker.ts: resolveBundledFrameworkRoot(), buildReseedCommand() (install.sh in MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep — the P4 data-safe reconcile), runFrameworkReseed(), readRosterAgentNames(), buildRelaunchCommands() (systemctl --user restart per agent).
• cli.ts update: after a successful CLI install that includes @mosaicstack/mosaic, re-seed the framework (default-on; --no-reseed to skip). Then either --relaunch (restart rostered agents) or print clear guidance to run mosaic update --relaunch / mosaic fleet restart.

Flow

update CLI → re-seed framework (data-safe) → relaunch agents (opt-in) — closes R13, activates the native harness for every operator.

Verification

• 6 new unit tests (reseed command/env, relaunch commands, roster parse, missing-installer guard).
• 19 runtime + 26 launch tests still green; tsc/eslint/prettier clean.
• Data-safety of the sync is already proven (P4 5-fixture matrix + live dragon-lin validation).