stack/docs/fleet/migration/v1-to-v2.md

kind, status

kind	status
guide	active

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

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. The v1 source remains authoritative for socket semantics: a supported declared socket field, including an explicit empty value for the default tmux server, is preserved; if both supported root aliases are absent, the production v1 default is the literal empty socket. A matching socketName decision is accepted and an incompatible decision blocks, but a decision never supplies or repairs a missing source socket. 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:

{
  "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 targets with or without an explicit user must agree with host; 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. Preview output is migration-readiness evidence, not proof that migration, canary, or rollback occurred.