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

jason.woltje · 2026-06-22T21:51:15Z

jason.woltje commented

2026-06-22 21:51:15 +00:00

Closes #633. Follow-up filed: #636 (PATH B).

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

What

mosaic fleet comms-block <role> [--host <h>] — explicit-arg, comms-only emitter.
- New resolveCommsBlock(mosaicHome, role, fleetHost?) → { ok, output, error } in fleet/comms-onboarding.ts.
- Fails loud: unknown role / missing roster → stderr + exit 1 (vs readFleetCommsBlock, which returns '' so composeContract can no-op silently during launch). Safe to preview any peer's view; a typo is never a silent no-op.
- Distinct from mosaic compose-contract <runtime> (whole prompt, env-coupled); this is the targeted comms-only view.
docs/fleet/FLEET-LAUNCH.md runbook — worker path + orchestrator .env fold (MOSAIC_AGENT_COMMAND, which short-circuits the line-44 yolo hardcode) + 3 launch gotchas + #632 preserve-list note + North-Star A→B→webUI launch-config arc.

Why no launch.ts change

mosaic yolo claude already forwards --channels/--permission-mode to the binary and injects the comms block via composeContract. PATH A is .env + doc only. PATH B (#636) makes the launch config (yolo + command/channels) roster-native for webUI binding.

Tests

TDD: 6 new resolveCommsBlock cases (member → block; non-member / missing-roster / missing-arg → fail loud; --host override preview).
fleet.spec.ts subcommand-list extended with comms-block.
177 fleet+comms tests green; typecheck, eslint, prettier clean.

Notes

Pre-existing local-only failure uninstall.spec.ts > removeFramework > handles missing mosaicHome gracefully (EACCES on /nonexistent as non-root) is unrelated to #633 and passes in CI as root.
No mosaic update / auto-reseed run (installed CLI still 0.0.40 — roster-wipe live until 0.0.41); all work is in-repo + vitest.

🤖 Generated with Claude Code

Closes #633. Follow-up filed: #636 (PATH B). PATH A of the orchestrator-launch fix: every launch path gets Fleet-Comms onboarding, and the canonical roster-driven launcher is documented so the orchestrator stops being a bespoke snowflake. ## What - **`mosaic fleet comms-block <role> [--host <h>]`** — explicit-arg, comms-only emitter. - New `resolveCommsBlock(mosaicHome, role, fleetHost?)` → `{ ok, output, error }` in `fleet/comms-onboarding.ts`. - **Fails loud**: unknown role / missing roster → stderr + `exit 1` (vs `readFleetCommsBlock`, which returns `''` so `composeContract` can no-op silently during launch). Safe to preview any peer's view; a typo is never a silent no-op. - Distinct from `mosaic compose-contract <runtime>` (whole prompt, env-coupled); this is the targeted comms-only view. - **`docs/fleet/FLEET-LAUNCH.md`** runbook — worker path + orchestrator `.env` fold (`MOSAIC_AGENT_COMMAND`, which short-circuits the line-44 `yolo` hardcode) + 3 launch gotchas + #632 preserve-list note + North-Star A→B→webUI launch-config arc. ## Why no launch.ts change `mosaic yolo claude` already forwards `--channels`/`--permission-mode` to the binary and injects the comms block via `composeContract`. PATH A is `.env` + doc only. PATH B (#636) makes the launch config (yolo + command/channels) roster-native for webUI binding. ## Tests - TDD: 6 new `resolveCommsBlock` cases (member → block; non-member / missing-roster / missing-arg → fail loud; `--host` override preview). - `fleet.spec.ts` subcommand-list extended with `comms-block`. - 177 fleet+comms tests green; typecheck, eslint, prettier clean. ## Notes - Pre-existing local-only failure `uninstall.spec.ts > removeFramework > handles missing mosaicHome gracefully` (EACCES on `/nonexistent` as non-root) is unrelated to #633 and passes in CI as root. - No `mosaic update` / auto-reseed run (installed CLI still 0.0.40 — roster-wipe live until 0.0.41); all work is in-repo + vitest. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jason.woltje added 1 commit 2026-06-22 21:51:16 +00:00

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

ci/woodpecker/push/ci Pipeline was successful

Details

ci/woodpecker/pr/ci Pipeline was successful

Details

1288c4bc2c

Add `mosaic fleet comms-block <role> [--host]` — an explicit-arg, comms-only
emitter wrapping a new resolveCommsBlock() over readFleetCommsBlock. Unlike the
launch-time reader (which returns '' on any miss so composeContract can no-op
silently), the emitter fails loud: unknown role / missing roster → stderr +
exit 1, so an operator can safely preview any peer's view and a typo is never
a silent no-op.

Add docs/fleet/FLEET-LAUNCH.md: the canonical roster-driven launch path
(worker + orchestrator .env fold via MOSAIC_AGENT_COMMAND, which short-circuits
the line-44 yolo hardcode), 3 launch gotchas (flag conflict, MOSAIC_AGENT_NAME
baking, launchRuntime guards), the #632 preserve-list note, and the North-Star
A→B→webUI launch-config arc.

PATH A of the orchestrator-launch fix; PATH B (roster-native launch-config:
yolo toggle + command/channels emission) tracked as #636.

TDD: 6 new resolveCommsBlock cases; 177 fleet+comms tests green; typecheck,
eslint, prettier clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83

jason.woltje merged commit 4e84f8e850 into main

2026-06-22 22:23:51 +00:00

jason.woltje referenced this issue from a commit

2026-06-22 22:23:52 +00:00

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

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#638