# Local Fleet Lifecycle Transitions

Roster-v2 `lifecycle.enabled` and `lifecycle.desired_state` are the only persisted lifecycle authority. Systemd, tmux, generated environment, and heartbeat state are derived or observed.

| Event                       | Desired-state write                                                        | Runtime effect                                                                              | Safety boundary                                                                                                                                             |
| --------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fleet create`              | Adds enabled/stopped by default; `--persisted-start` records running       | None                                                                                        | Generation-guarded; validates full roster/projections.                                                                                                      |
| `fleet update`              | Preserves the existing enabled/desired state; updates other mutable fields | None                                                                                        | Generation-guarded; stable name and lifecycle are immutable on this path.                                                                                   |
| `fleet delete`              | Removes exact roster member                                                | None                                                                                        | Removes only generated projection; retains local/quarantine evidence.                                                                                       |
| `fleet apply` / `reconcile` | Never                                                                      | Rebuilds projections; starts only enabled/running; stops disabled or stopped roster members | Current generation, private lock/paths, semantic validity, holder ownership, no unmanaged named-socket sessions.                                            |
| `fleet start <name>`        | Never                                                                      | One-shot exact service start                                                                | Exact enabled roster name and proven ownership.                                                                                                             |
| `fleet stop <name>`         | Never                                                                      | One-shot exact service stop                                                                 | Exact roster name and proven ownership.                                                                                                                     |
| `fleet restart <name>`      | Never                                                                      | One-shot exact service restart                                                              | Exact enabled roster name and proven ownership.                                                                                                             |
| Reboot/service activation   | Never                                                                      | Current installation may activate enabled units without honoring roster lifecycle           | **Held for FCM-M3-002:** boot preservation for stopped/disabled agents is not yet proven; inspect/disable units rather than assuming lifecycle-safe reboot. |
| v1 migration preview        | Never                                                                      | None                                                                                        | Observed active+present maps running; inactive+missing maps stopped; ambiguity blocks.                                                                      |
| Cutover/canary              | Held for FCM-M4-002                                                        | Not implemented by preview                                                                  | Must preserve every observed stopped state.                                                                                                                 |
| Rollback                    | Held for FCM-M4-002                                                        | Not implemented                                                                             | Must restore selected authority/projections without surprise starts or unmanaged targeting.                                                                 |

Explicit apply/reconcile never starts a stopped roster agent. Direct lifecycle commands are explicit one-shot actions and do not persist intent. The current update operation preserves `existing.lifecycle`; there is no delivered generation-guarded CRUD operation for changing durable lifecycle after creation. Reboot preservation for stopped/disabled agents is not yet guaranteed because current enabled units and launcher projections do not carry the persisted lifecycle fence; that acceptance evidence remains FCM-M3-002.

Missing/stale generation, concurrent writer, unsafe path, ownership mismatch, unmanaged session, unsupported runtime, invalid projection, and lifecycle precondition failures return stable redacted JSON and non-zero status. No command targets fuzzy names, arbitrary sockets/commands/channels/secrets, or generated files as authority. Legacy sensitive values are never printed.