feat(fleet): comms-block emitter + FLEET-LAUNCH runbook (#633) (#638)

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

packages/mosaic/src/fleet/comms-onboarding.spec.ts

@@ -7,6 +7,7 @@ import {
   buildFleetCommsBlock,
   renderPeerReach,
   readFleetCommsBlock,
+  resolveCommsBlock,
   type CommsPeer,
 } from './comms-onboarding.js';
 
@@ -185,3 +186,53 @@ describe('readFleetCommsBlock — situational (the context a spawned agent gets)
     expect(readFleetCommsBlock(mkdtempSync(join(tmpdir(), 'noroster-')), 'orchestrator')).toBe('');
   });
 });
+
+describe('resolveCommsBlock — `mosaic fleet comms-block <role>` emitter semantics', () => {
+  // The emitter wraps readFleetCommsBlock but must NEVER print an empty string silently:
+  // an unknown role / missing roster has to fail loud (caller maps !ok → stderr + exit 1)
+  // so `mosaic fleet comms-block bogus` is a visible error, not a confusing no-op. The
+  // success path returns the block verbatim for `mosaic fleet comms-block <peer>` previews.
+  let home: string;
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'mosaic-commsblk-'));
+    mkdirSync(join(home, 'fleet'), { recursive: true });
+    writeFileSync(join(home, 'fleet', 'roster.yaml'), ROSTER);
+  });
+  afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+  it('returns ok + the cheat-sheet for a roster member', () => {
+    const res = resolveCommsBlock(home, 'orchestrator', 'w-jarvis');
+    expect(res.ok).toBe(true);
+    expect(res.output).toContain('# Fleet Comms');
+    expect(res.output).toContain('| enhancer |');
+    expect(res.error).toBeUndefined();
+  });
+
+  it('fails loud (not ok + error naming the role) for a non-member — never silently empty', () => {
+    const res = resolveCommsBlock(home, 'stranger', 'w-jarvis');
+    expect(res.ok).toBe(false);
+    expect(res.output).toBe('');
+    expect(res.error).toContain('stranger');
+  });
+
+  it('fails loud when no roster exists at the mosaic home', () => {
+    const noRoster = mkdtempSync(join(tmpdir(), 'mosaic-noroster-'));
+    const res = resolveCommsBlock(noRoster, 'orchestrator', 'w-jarvis');
+    expect(res.ok).toBe(false);
+    expect(res.error).toBeTruthy();
+    rmSync(noRoster, { recursive: true, force: true });
+  });
+
+  it('fails loud for a missing role argument', () => {
+    const res = resolveCommsBlock(home, undefined, 'w-jarvis');
+    expect(res.ok).toBe(false);
+    expect(res.error).toBeTruthy();
+  });
+
+  it('honors a host override so a peer can preview its own cross-host view', () => {
+    // coder0-0 viewing with its own host → its self-identity line uses that host.
+    const res = resolveCommsBlock(home, 'coder0-0', '10.1.10.37');
+    expect(res.ok).toBe(true);
+    expect(res.output).toContain('`[10.1.10.37:coder0-0]`');
+  });
+});