stack/docs/fleet/reference/lifecycle-transitions.md

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	May change enabled/desired state in complete payload	None	Generation-guarded; stable name immutable.
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. Change durable lifecycle only through generation-guarded CRUD and then review reconciliation. 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.