stack/docs/fleet/reference/status-and-drift.md

Local Fleet Status and Drift

mosaic fleet status [name], verify, and doctor are observational roster-v2 commands. They emit one JSON result and do not write projections, mutate desired state, operate lifecycle, or change tmux.

State dimensions

• Desired: roster membership, generation, enabled flag, and persisted running/stopped target.
• Managed/derived: generated environment and expected exact service/session topology.
• Observed by current roster-v2 commands: systemd active state, tmux presence, exact holder ownership, and unmanaged sessions.

Implemented drift classifications include:

• missing-session: enabled/desired-running agent lacks its exact session;
• unexpected-session: desired-stopped agent has its exact session;
• disabled-running: disabled roster agent has its exact session;
• unmanagedSessions: named-socket sessions that are neither exact holder nor roster agent;
• holder: owned, missing, or ownership-mismatch after private identity and global environment checks.

Generated projection failures/staleness are surfaced by plan/apply preparation and bounded recovery fields rather than adopted as configuration. Heartbeat remains wider-fleet observational evidence, never desired state, but the current roster-v2 status, doctor, and verify commands do not read heartbeat files. A provable removed-agent projection may be treated as stale derived state during deletion, but general projection-orphan classification and installed source-versus-asset revision mismatch remain FCM-M4-002/M5-002 holds; current commands must not claim those future checks.

Command behavior

status and doctor classify rather than adopt, destroy, or repair. verify is observational too, but exits non-zero if ownership cannot be proven, unmanaged sessions exist, or drift is present. Reconciliation fails closed under those conditions and never kills or adopts an unmanaged session.

Doctor/error output uses stable codes and bounded recovery context. Migration, quarantine, lifecycle, status, and troubleshooting output never prints a legacy sensitive value, credential, or privileged command text.