stack/docs/fleet/concepts/generated-env-launch-chain.md

Generated Environment Launch Chain

The launcher consumes validated data, not shell configuration.

1. Read and validate the canonical roster.
2. Render deterministic <name>.env.generated data from that roster.
3. Parse optional <name>.env.local through a strict allowlist.
4. Reject generated-key shadowing, unknown or sensitive-looking keys, unsafe paths/values, duplicates, malformed lines, shell syntax, and command overrides.
5. Derive the runtime command from validated runtime/model/reasoning data.
6. Target only the exact configured tmux socket and roster session after ownership checks.

File precedence and ownership

File	Owner	Use
.env.generated	Mosaic projection writer	Complete deterministic roster projection. Rebuild; do not edit.
.env.local	Operator	Optional, private, strict machine-local data. Cannot shadow generated keys.
.env	Legacy input	One-time migration input only; never launch authority.
.env.quarantine	Private quarantine	Retained unsafe legacy evidence; never loaded by the launcher.

Neither systemd nor the launcher sources these files. No eval, shell expansion, arbitrary MOSAIC_AGENT_COMMAND, channel, or secret-reference compatibility path exists. Safe legacy generated keys are regenerated, allowed local keys are relocated, and unsafe material is quarantined.

Diagnostics never expose the rejected value, credential material, or command text. They are bounded to stable rule code, key name where safe, and SHA-256 content identity. See generated environment reference and quarantine operations.