feat(fleet): onboarding-injection — comms cheat-sheet + peer roster per agent (#621)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

docs/scratchpads/fleet-comms-onboarding.md

@@ -0,0 +1,31 @@
+# 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.