docs(plans): environment profiles + host-to-host session teleport

[agentfleets]

What

A third design plan: docs/plans/env-profiles-and-session-teleport.md — two control-plane primitives from the cloud-agent comparison (Claude Code on the web / Codex cloud), grounded in the current codebase first. Docs-only.

Part 1 — Environment profiles (first-class env_profiles)

The gap: Claude/Codex web attach setup script + env vars + secrets + network policy to tasks as a reusable entity. Grounding showed termipod has no env/setup fields anywhere (templates, families, spawn spec — schema grep is zero), nothing but the hub-minted MCP token is injected into spawns, the egress proxy does URL-masking only, and the docs flag the gap themselves (multi-agent-harness-landscape.md:627).

The design, built around the zero-knowledge vault (ADR-052) instead of against it:

• Team-scoped env_profiles entity: setup_script (hub-visible) + plain env_vars (hub-visible) + secret_refs (references into the vault — never values) + declarative network_policy.
• Secret delivery honors forbidden-pattern deps(hub): bump modernc.org/sqlite from 1.34.4 to 1.50.1 in /hub #15: host device keys (X25519 keypair at registration, public key rides capabilities_json — same shape as ADR-052's per-device wrapping); the client resolves vault refs and seals a per-spawn envelope to the target host's key; the hub carries ciphertext it cannot decrypt.
• Snapshot semantics at spawn (profile id + rev), deterministic env merge order, setup script after workdir creation with fail-closed default.
• Wedges: E1 entity+plain env+setup script → E2 attach points (project config, spawn sheet) + UI (the vault's unused env/script item types finally get a consumer) → E3 secret envelopes (own ADR) → E4 network-policy enforcement via egress-proxy rules.

Part 2 — Session teleport between hub-registered hosts

Grounding: the resume primitive (resumePausedSession) already does terminate + respawn + keep session row + splice engine cursor — but hard-pinned to the same host (handlers_sessions.go:691), and engine session stores (~/.claude/projects, ~/.kimi-code/sessions, …) are host-local disk files (ADR-014's single-host assumption), so naive cross-host resume would cold-start. Transcripts are hub-side, so conversation history is portable for free.

The design: POST /sessions/{id}/teleport {target_host_id} —

1. Validate target (online via checkSpawnHostReachable, capability supports the family, repo reachable for worktree sessions).
2. Workdir handoff: branch push/pull for worktree sessions (hub/<handle>); tar-via-hub-blob relay for non-worktree (T2, size-capped).
3. Engine-state bundles: families declare state_paths globs in agent_families.yaml; source tars the engine store → hub blob → target restores with workdir-path remapping, so sessions.engine_session_id resolves on the target exactly as on the source. Degraded fallback: cold-start + session digest context file, explicit in UI.
4. Terminate-after-verify swap — source is only terminated after the target spawn reports ready; failure leaves the source untouched.
5. UX: teleport action with capability-filtered host picker and progress phases, on desktop first (T1), mobile in T2.

Wedges: T1 worktree sessions + kimi/claude state bundles → T2 non-worktree + remaining families + mobile → T3 failover/drain/bare-repo relay.

Security / ADR notes called out

New ADR for E3 (extends ADR-052 to hosts); engine-state blobs flagged as transcript-equivalent sensitivity (seal-to-host via E3 keys recommended in T3); workdir tar caps + blob TTL; setup scripts fail-closed.

Open questions (§end)

Profile scoping vs per-project key overrides; mobile as secret-ref resolver; engine-state blob sensitivity gate for T1; teleport of active-but-idle vs paused-only; non-git tar size cap.

Verification

• scripts/lint-docs.sh ✓ (cross-link to the now-merged transcript plan resolves)