# Previewing a Fleet Roster v1-to-v2 Migration **Issue:** #758 · **Card:** FCM-M4-001 · **Effect boundary:** preview only `mosaic fleet migrate-v1 preview` inventories a v1 roster and emits a canonical v2 candidate plus recovery evidence. It does not write a roster, apply environment projections, invoke systemd or `tmux`, contact connectors or remote hosts, launch an agent, run a canary, or execute rollback. FCM-M4-002 owns reversible cutover and rollback. ## Inputs ```bash mosaic fleet migrate-v1 preview \ --source roster-v1.yaml \ --decisions migration-decisions.json \ --observations reviewed-observations.json ``` The command emits one JSON object and exits nonzero when the preview is blocked, including when any of `--source`, `--decisions`, or `--observations` is omitted, passed without a path value, or passed an empty path value. These request-shape failures are reported before any input file is read. Decision and observation JSON is validated fail-closed: unknown fields, malformed values, and records for non-local agents are rejected. Decisions must supply a positive v2 `generation`, a reviewed `fleetHost` whenever v1 agents include `host` or `ssh`, explicit `defaultRuntime`, and per-local-agent provider, model, reasoning, enabled state, and launch policy. A supported socket field declared by v1 remains authoritative, including an explicit empty value representing the default tmux server; a matching `socketName` decision is accepted, an incompatible decision blocks, and a decision supplies the socket only when both supported v1 socket fields are genuinely absent. If v1 omitted `tool_policy`, decisions must supply an explicit replacement; it is never derived from `class`. `model_hint` is never split or treated as authority. Observations are separate reviewed evidence keyed by local agent name: ```json { "coder0": { "systemd": "inactive", "tmux": "missing" } } ``` Only `active` plus `present` maps to `running`; only `inactive` plus `missing` maps to `stopped`. Missing, extra, unknown, or contradictory evidence blocks output. An observed-running agent cannot be marked disabled. Observed-stopped agents always remain stopped. ## Field disposition | v1 field | v2 disposition | | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `version`, `transport`, `tmux`, `defaults`, `runtimes` | Inventoried and structurally compiled; omitted runtimes retain v1 built-in defaults, while each explicitly declared runtime without a reset field follows the production v1 `/clear` fallback; present-empty holder/work-directory/reset values block | | agent `name`, `alias`, `runtime`, working directory, persona/reset flags | Copied or explicitly defaulted only when absent; present-empty alias/work-directory values block for explicit disposition. Canonical `~`/`~/...` values stay unchanged in roster evidence and traversal-free forms expand only at the shared production environment-projection boundary before unchanged absolute-path validation | | `provider`, `model_hint`, `reasoning_level` | Explicit provider/model/reasoning decisions; no model-hint inference | | `class`, `tool_policy` | Only approved aliases canonicalize automatically; other classes require explicit preserve/replace disposition and shared-resolver validation | | `kickstart_template` | No v2 field; explicit inventory-only disposition required | | agent `host`, `ssh` | `host != fleetHost` is demonstrably remote and inventory-only; `host == fleetHost` stays local; ssh-only, missing fleet-host evidence, or contradictory targets block | | agent `socket` | Same-host candidate only when it matches the canonical fleet socket; conflicts block for explicit future disposition | | root `connector` | Inventory-only; never contacted or reconciled | | unknown fields or snake/camel synonym collisions | Inventoried and block readiness | | `.env.generated` | Rebuild from canonical roster data | | no legacy `.env` | `absent`; no legacy action required | | legacy `.env` containing generated keys only | `regenerate-only`; replace later from canonical roster data | | legacy `.env` containing strict local keys | `relocate-local`; preserve those keys in `.env.local` during a later reviewed cutover | | legacy `.env` containing forbidden/unsafe/sensitive/malformed keys | `quarantine`; private input only, with diagnostics limited to code, key, and SHA-256 | The only automatic aliases are `implementer → code`, `reviewer → review`, and `operator-interaction → interaction`. Similar or domain-specific names are never inferred. Automatic classes do not accept competing disposition records. Semantic validation delegates to the existing baseline-plus-`roles.local` resolver after the candidate is compiled by the existing v2 compiler. ## Evidence and recovery boundary Ready output includes source and candidate SHA-256 identities, value-free field inventory, excluded remote/connector entries, explicit environment dispositions with sanitized diagnostics, and the lifecycle evidence used for each local candidate. Canonical lifecycle and remote-exclusion evidence ordering compares Unicode code points directly and does not depend on source-agent order or process locale. Source field inventory remains position-addressed evidence of the exact input. Recovery is marked non-executable and assigns the executable gate to FCM-M4-002. Before any later cutover, preserve these artifacts: 1. authoritative v1 roster backup; 2. agent environment backup, including `.env.local` and private quarantine inputs; 3. reviewed lifecycle observations; 4. canonical candidate v2 roster and its SHA-256. See [backup and restore](../operations/backup-restore.md). Preview output is migration-readiness evidence, not proof that migration, canary, or rollback occurred.