stack/docs/scratchpads/633-comms-block-runbook.md

#633 — comms-block emitter + FLEET-LAUNCH runbook

Branch: feat/633-comms-block-runbook (off bf2a6745, post-#632 merge) Issue: #633 · Follow-up filed: #636 (PATH B)

Goal

PATH A of the orchestrator-launch fix: give every launch path the Fleet-Comms onboarding, and document the canonical roster-driven launcher so the orchestrator stops being a bespoke snowflake.

Deliverables

1. mosaic fleet comms-block <role> [--host <h>] — explicit-arg, comms-block-only emitter.
   • Backed by new resolveCommsBlock(mosaicHome, role, fleetHost?) in fleet/comms-onboarding.ts returning { ok, output, error }.
   • Unlike readFleetCommsBlock (returns '' on any miss so composeContract can no-op silently during launch), the emitter fails loud: unknown role / missing roster → ok:false → CLI prints to stderr + sets process.exitCode = 1. A typo is never a silent no-op.
   • Distinct from mosaic compose-contract <runtime> (whole prompt, env-coupled via MOSAIC_AGENT_NAME); comms-block is the targeted, explicit-arg, comms-only view.
2. docs/fleet/FLEET-LAUNCH.md — worker path + orchestrator .env fold + 3 launch gotchas + #632 preserve note + North-Star 4-field arc.

Key findings (drove the design)

• mosaic yolo claude already forwards --channels/--permission-mode to the binary (launch.ts claude case cliArgs.push(...args)) AND injects the comms block via composeContract → readFleetCommsBlock(home, env.MOSAIC_AGENT_NAME). So no launch.ts change was needed — PATH A is .env + doc only.
• start-agent-session.sh line ~41 [ -z "$MOSAIC_AGENT_COMMAND" ] short-circuits the line-44 default, so an .env MOSAIC_AGENT_COMMAND override bypasses the hardcoded yolo entirely — the yolo-conditional is therefore a PATH B (default-path) concern, not PATH A.
• generateAgentEnv (fleet.ts ~202-207) emits NAME/RUNTIME/MODEL but not MOSAIC_AGENT_COMMAND — the seam PATH B (#636) closes.

A → B → webUI arc (North Star)

• A = .env MOSAIC_AGENT_COMMAND hatch (manual, ships now, #632-safe).
• B (#636) = roster-native launch-config: harness ✅ + model ✅ already there; add yolo (line-44 conditional MOSAIC_AGENT_YOLO) + command/channels (generateAgentEnv emission).
• webUI binds dropdowns/toggles to those four roster fields. One launcher, no new launch path.

Results

• TDD: spec first (comms-onboarding.spec.ts, 6 new resolveCommsBlock cases) → red → implement → green.
• fleet.spec.ts subcommand-list assertion extended with comms-block.
• 177 fleet+comms tests green; typecheck clean; eslint clean; prettier clean.

Risks / notes

• Pre-existing local-only failure uninstall.spec.ts > removeFramework > handles missing mosaicHome gracefully (EACCES on /nonexistent as non-root) — unrelated to #633, passes in CI as root.
• Did NOT run mosaic update / anything auto-reseed: installed CLI still 0.0.40 (roster-wipe live until mos-claude-0 ships 0.0.41). All work is in-repo + vitest, never touches the live mosaic home.