stack/docs/scratchpads/fleet-comms-onboarding.md

Fleet onboarding-injection — comms cheat-sheet + peer roster (#620)

• Issue: #620 · Branch: feat/fleet-comms-onboarding (off main). Root cause of Mos's failed first send.

What

Inject a # Fleet Comms block into each spawned fleet agent's system prompt (via composeContract — the runtime-agnostic path every mosaic yolo <runtime> agent hits), so it boots knowing how to reach peers.

• src/fleet/comms-onboarding.ts (standalone, no fleet.ts coupling):
  • parseRosterAgents (name/class/host/ssh, lenient), renderPeerReach (same-host -s vs cross-host -H <ssh> -s), buildFleetCommsBlock (self [host:session] identity + agent-send path + peer table + FLIP-to-reply + agent send --verify=ACCEPTED), readFleetCommsBlock (reads roster.yaml; '' if not a member).
  • composeContract appends it only when MOSAIC_AGENT_NAME is set + the agent is in the roster.
• roster.schema.json: optional per-agent host + ssh (cross-host addresses; manual = pre-federation stopgap, federation/W1 auto-discovers later).

Acceptance criteria (Mos) — all covered

1. own [host:session] + agent-send path + peer roster ✓
2. cross-host correctness: local→-s (no -H); remote→-H <ssh> -s ✓ (concrete coder0-0@dragon-lin)
3. FLIP-the-preamble reply rule ✓
4. agent send --verify = ACCEPTED ✓
5. no -L (default socket); matches live tooling ✓

Verification

• 10 onboarding unit tests (parse, render local/remote/fallback/equal-host, build, situational read) + 2 composeContract situational tests (injects for fleet agent w/ correct cross-host addr; no-op when MOSAIC_AGENT_NAME unset). tsc/eslint/prettier/sanitize clean.
• Post-merge validation: Mos spawns a real w-jarvis agent → first-try reach to coder0-0@dragon-lin + a local peer.