# #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.