feat(fleet): add generation-guarded agent CRUD (#773)

docs/fleet/how-to/create-update-delete-agent.md

@@ -0,0 +1,74 @@
+# Create, Inspect, Update, and Delete a Local Fleet Agent
+
+Use the local roster-v2 control plane only. These commands change desired state and derived environment projections; they never start, stop, reconcile, inspect, or otherwise act on systemd, tmux, sessions, or runtimes.
+
+## Read and plan first
+
+```sh
+mosaic fleet get <name>
+mosaic fleet plan create --expected-generation <n> --agent '<json>'
+mosaic fleet plan update <name> --expected-generation <n> --agent '<json>'
+mosaic fleet plan delete <name> --expected-generation <n>
+```
+
+`plan create` takes the name from `--agent`. `plan update` and `plan delete` require the target name immediately after the operation. A plan is deterministic and side-effect free: it validates the complete proposed roster and projection targets without changing files. Use `--dry-run` on `create`, `update`, or `delete` for the same no-write result.
+
+Every successful command prints JSON. `get` returns `{ "generation", "agent" }`; mutation results contain `plan`, `applied`, `authoritativeRoster`, and `projections`.
+
+## Create safely
+
+```sh
+mosaic fleet create --expected-generation 7 --agent '{
+  "name":"coder0",
+  "alias":"Coder 0",
+  "className":"code",
+  "runtime":"pi",
+  "provider":"openai",
+  "model":"gpt-5.6-sol",
+  "reasoning":"high",
+  "toolPolicy":"code",
+  "workingDirectory":"/srv/mosaic",
+  "persistentPersona":false,
+  "resetBetweenTasks":true,
+  "launch":{"yolo":true}
+}'
+```
+
+Create defaults to `enabled: true` and `desired_state: stopped`. It does not start a process. Add `--persisted-start` only to persist `desired_state: running`; that still does not start a runtime in this M2 command. The JSON payload is an allowlist of the roster-v2 fields shown above plus `launch.yolo`; command, channel, secret-reference, and other unknown keys are rejected rather than ignored. The JSON error exposes only a stable code, never the rejected value.
+
+## Update and delete safely
+
+```sh
+mosaic fleet update coder0 --expected-generation 8 --agent '<complete JSON agent payload>'
+mosaic fleet delete coder0 --expected-generation 9
+```
+
+Updates require a complete agent JSON payload and preserve the stable name. Delete removes only the exact roster-owned `coder0.env.generated` projection. It retains `coder0.env.local`, legacy `coder0.env`, `coder0.env.quarantine`, and every unrelated projection. A delete dry-run leaves all of those files byte-identical.
+
+## Handle generation conflicts
+
+Every mutation requires the current authoritative `--expected-generation`. A stale value returns JSON `error.code: "stale-generation"` with a non-zero exit. Reload with `mosaic fleet get <name>` or reread the roster, plan again using the returned generation, then retry. A concurrent mutation returns `concurrent-mutation`; do not force or bypass the lock.
+
+## Interpret partial failures
+
+The roster is authoritative and is written before derived projections. A late projection I/O failure returns non-zero with redacted, actionable JSON:
+
+```json
+{
+  "applied": false,
+  "authoritativeRoster": "committed",
+  "projections": "incomplete",
+  "recovery": {
+    "code": "projection-apply-failed",
+    "action": "regenerate-projections-from-roster"
+  }
+}
+```
+
+This is not a rollback and not a no-op: reload the roster because its generation and membership were committed, regenerate projections from that roster, then plan a new mutation. Recovery output never contains environment values, credentials, or command text.
+
+## Exit and boundary behavior
+
+Handled validation errors and partial projection failures exit non-zero. `plan`/`--dry-run` and normal mutation JSON make the state explicit; scripts should use both the exit code and `authoritativeRoster`/`projections`, not `applied` alone.
+
+The commands operate only on `<mosaic-home>/fleet/roster.yaml`, the local roster desired-state authority. They do not accept arbitrary commands, channels, secrets, remote/connector actions, migration/canary actions, or runtime lifecycle operations.

docs/fleet/reference/agent-mutations.md

@@ -0,0 +1,43 @@
+# Local Fleet Agent Mutations
+
+FCM-M2-002 provides local roster-v2 create, get, update, delete, and plan operations. They only change desired state and derived environment projections. They never start, stop, inspect, reconcile, or otherwise act on runtimes, systemd units, tmux sessions, or heartbeats.
+
+## CLI contract
+
+The commands operate only on the canonical `<mosaic-home>/fleet/roster.yaml` v2 authority and print one JSON object to stdout. `--agent` is a JSON object with the roster agent fields expressed as `className`, `toolPolicy`, `workingDirectory`, `persistentPersona`, `resetBetweenTasks`, and `launch: { "yolo": boolean }`.
+
+```sh
+mosaic fleet get <name>
+mosaic fleet plan <create|update|delete> [name] --expected-generation <n> [--agent '<json>'] [--persisted-start]
+mosaic fleet create --expected-generation <n> --agent '<json>' [--dry-run] [--persisted-start]
+mosaic fleet update <name> --expected-generation <n> --agent '<json>' [--dry-run]
+mosaic fleet delete <name> --expected-generation <n> [--dry-run]
+```
+
+`get` returns the authoritative generation and the selected agent. `plan create` derives its name from `--agent`; `plan update <name>` and `plan delete <name>` require the target name. `--agent` accepts only the documented roster-v2 request fields and `launch.yolo`; unknown keys such as commands, channels, or secret references are rejected. Rejection diagnostics return only the stable `invalid-request` code and never echo a rejected value. `plan` and `--dry-run` validate the complete proposed roster and projections but write neither the roster nor projections. `--persisted-start` is available only for a create request: it records `desired_state: running`, but does not start a process. Without it, create records `enabled: true` and `desired_state: stopped`. Handled failures return JSON with `error.code` and exit non-zero; unclassified validation/projection failures use the redacted `mutation-failed` code.
+
+## Generation, validation, and idempotency
+
+Each create, update, or delete request includes `expectedGeneration`. A request whose expected value differs from the authoritative roster generation fails with `stale-generation`; reload and retry with a newly computed plan. A private mutation lock rejects concurrent writers with `concurrent-mutation`.
+
+`planFleetAgentMutation` is deterministic and side-effect free. `executeFleetAgentMutation` validates the complete proposed roster through the existing structural and shared persona resolver, prepares generated/local/quarantine projections, and writes the roster authority atomically before applying derived projections. Equivalent create retries and delete requests for an already-absent agent are idempotent no-ops.
+
+Delete removes only the exact `<name>.env.generated` projection for the removed roster entry. Operator-owned `<name>.env.local`, legacy `<name>.env`, quarantine records, and unrelated projections remain untouched. An already-absent generated projection is treated as stale derived state, not as a failed mutation.
+
+## Result and recovery
+
+Mutation results are JSON-safe objects with `applied`, `authoritativeRoster`, `projections`, `plan`, and—only if a derived projection write fails after the authoritative roster write—a recovery object. `applied` is true only when every roster and derived-projection write completed. The explicit state fields prevent a partial result from being mistaken for a rollback or a no-op:
+
+```json
+{
+  "applied": false,
+  "authoritativeRoster": "committed",
+  "projections": "incomplete",
+  "recovery": {
+    "code": "projection-apply-failed",
+    "action": "regenerate-projections-from-roster"
+  }
+}
+```
+
+Dry-runs and idempotent no-ops report `authoritativeRoster: "unchanged"` and `projections: "not-applied"`; a complete mutation reports `"committed"` and `"complete"`. Recovery output identifies the authoritative roster path and regeneration action only. It never contains generated/local/quarantine values, credentials, or command text. A recovery result exits non-zero because the authoritative roster was persisted but derived projections require regeneration. Regenerate projections from the roster before attempting another mutation.