---
kind: guide
status: active
---

# Reconcile and Recover a Local Fleet

## Safe sequence

1. Read mosaic fleet doctor and mosaic fleet status.
2. Run mosaic fleet apply --expected-generation <n> --dry-run.
3. Resolve stale generation, ownership mismatch, unsafe path, projection validation, or unmanaged-session findings before applying.
4. Run mosaic fleet apply --expected-generation <n> only after the plan is understood.

This is per-generation convergence, not a rolling canary. Executable canary cutover/rollback remains held for FCM-M4-002; rolling local release evidence remains FCM-M5-002. Do not approximate either with repeated live apply commands.

The reconciler uses the exact roster tmux socket, exact holder session, private installation holder identity, and the complete expected global environment. For mutations it acquires its exclusive lock before rereading the canonical roster and fencing its generation; only that under-lock roster drives validation, planning, projections, and lifecycle effects. Before effects, its exclusive lock proves real private `MOSAIC_HOME` and `fleet` ancestors, uses a private `0600` lock leaf, and binds cleanup to the created file identity and ownership token. A fake holder, contaminated global environment, missing identity, unsafe lock path, or unmanaged session fails closed. It does not adopt, kill, or rename any unproven session. A crash can leave a stale lock for explicit operator inspection; reconciliation deliberately does not guess ownership or remove it.

## Partial results

The roster is never changed by reconciliation. If derived projection application partially fails, JSON reports:

```json
{
  "applied": false,
  "authoritativeRoster": "unchanged",
  "projections": "incomplete",
  "lifecycle": "not-applied",
  "recovery": { "code": "projection-apply-failed", "action": "regenerate-projections-from-roster" }
}
```

If projections completed but lifecycle work failed, JSON reports projections: "complete", lifecycle: "incomplete", and the bounded action `rerun-after-inspecting-owned-resources`. If lock cleanup cannot be proven after an effect result, it adds cleanup: { "code": "lock-cleanup-failed", "action": "inspect-lock-before-retry" } without changing the known projection, lifecycle, or primary recovery truth. Inspect the retained lock before retrying; no rollback, release, or stale-lock removal is implied. Results do not include environment values, secrets, or privileged command content.
