ci: eliminate cold pnpm install via pre-baked CI base image (Phase 1)

Every pipeline ran a cold pnpm install (network fetch + musl native
rebuilds + apk add python3 make g++), median ~731s, paid twice per push.

Phase 1 (no cluster access, repo commits only):
- Dockerfile.ci: node:22-alpine + python3/make/g++/postgresql-client +
  pnpm@10.6.2 + pnpm fetch to warm the store and compile natives once.
- .woodpecker/ci-image.yml: kaniko build/push of ci-base:latest + a
  lockfile-hash tag, triggered only when pnpm-lock.yaml or Dockerfile.ci
  change. Reuses the publish.yml kaniko/auth pattern.
- ci.yml + publish.yml: install from the baked ci-base:latest, drop the
  per-run apk add, use pnpm install --frozen-lockfile --prefer-offline.
- Framework monorepo template: single cached install other steps depend
  on instead of re-running npm ci across 6 steps.

Node 22->24 bump is a separate follow-up PR. Phase 2 (RWX Longhorn PVC)
is out of scope. Expected install ~731s -> ~30-60s.

Refs #634

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.npmrc

@@ -1,5 +1 @@
 @mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/
-# Pin the pnpm store to the same path the ci-base image warms (Dockerfile.ci),
-# so the pipeline `pnpm install --prefer-offline` consumes the baked store
-# instead of repopulating a fresh one.
-store-dir=/root/.local/share/pnpm/store

.woodpecker/ci.yml

@@ -1,5 +1,5 @@
 # &node_image is the pre-baked CI base built by .woodpecker/ci-image.yml:
-# node:24-alpine + python3/make/g++/postgresql-client + pnpm + a warm pnpm
+# node:22-alpine + python3/make/g++/postgresql-client + pnpm + a warm pnpm
 # store. The install step resolves from the baked store (--prefer-offline)
 # instead of paying a ~731s cold fetch + native compile every run.
 variables:

.woodpecker/publish.yml

@@ -2,7 +2,7 @@
 # Runs only on main branch push/tag
 
 variables:
-  # Pre-baked CI base (see .woodpecker/ci-image.yml): node:24-alpine +
+  # Pre-baked CI base (see .woodpecker/ci-image.yml): node:22-alpine +
   # toolchain + warm pnpm store. Kills the second cold install publish pays.
   - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:latest'
   - &enable_pnpm 'corepack enable'

Dockerfile.ci

@@ -2,30 +2,23 @@
 #
 # Purpose: eliminate the cold `pnpm install` that dominates every pipeline
 # (~731s median). This image ships the native toolchain (no per-run `apk add`)
-# AND a warm, content-addressable pnpm store with the dependency-tree tarballs
+# AND a warm, content-addressable pnpm store with the dependency tree already
-# already fetched at build time. `pnpm fetch` only populates the store from the
+# fetched and its musl native modules (better-sqlite3, node-pty, sqlite3,
-# lockfile — it does NOT run the native node-gyp builds (better-sqlite3,
+# canvas, sharp) compiled ONCE at build time. A pipeline `pnpm install
-# node-pty, sqlite3, canvas, sharp); those still compile at `pnpm install`,
+# --frozen-lockfile --prefer-offline` then resolves from local hard-links in
-# which is exactly why the musl toolchain stays baked into this image. A
+# tens of seconds.
-# pipeline `pnpm install --frozen-lockfile --prefer-offline` then resolves
-# tarballs from local hard-links (no network) and compiles natives against the
-# already-present toolchain, in tens of seconds instead of ~731s.
 #
 # Rebuilt only when `pnpm-lock.yaml` or this Dockerfile change
 # (see .woodpecker/ci-image.yml).
 #
-# Node version is pinned to 24 (Active LTS). This is the follow-up bump from
+# Node version is intentionally pinned to 22 (Active LTS at time of writing).
-# node:22 — sequenced AFTER the CI cache work landed so the runtime change
+# The node:22 -> node:24 bump lands as a SEPARATE follow-up PR so the cache
-# carries zero cache variables. node:26 stays held until it reaches LTS
+# change carries zero runtime-version variables.
-# (Oct 2026); the Current line risks native-module (node-gyp) breakage on a
+FROM node:22-alpine
-# runner that compiles better-sqlite3 / canvas / sharp / node-pty from source.
-FROM node:24-alpine
 
 # Native toolchain required to compile node-gyp deps on musl, plus the
-# postgresql-client used by the test step's pg_isready readiness probe. `bash`
+# postgresql-client used by the test step's pg_isready readiness probe.
-# is baked here too — the sanitization step in ci.yml otherwise does a per-run
+RUN apk add --no-cache python3 make g++ postgresql-client
-# `apk add bash`.
-RUN apk add --no-cache python3 make g++ postgresql-client bash
 
 # Pin pnpm to the repo's packageManager version via corepack.
 RUN corepack enable && corepack prepare pnpm@10.6.2 --activate
@@ -36,10 +29,8 @@ WORKDIR /app
 ENV PNPM_HOME=/root/.local/share/pnpm
 RUN pnpm config set store-dir /root/.local/share/pnpm/store
 
-# Warm the store. `pnpm fetch` populates the content-addressable store with the
+# Warm the store + compile native modules once. `pnpm fetch` populates the
-# dependency tarballs directly from the lockfile (no package.json / workspace
+# content-addressable store directly from the lockfile (no package.json /
-# needed), so a baked store stays valid until the lockfile changes. Note:
+# workspace needed), so a baked store stays valid until the lockfile changes.
-# `fetch` does NOT compile native modules — that happens later at `pnpm install`
-# in the pipeline, against the toolchain baked above.
 COPY pnpm-lock.yaml ./
 RUN pnpm fetch --frozen-lockfile

docs/TASKS.md

@@ -86,7 +86,3 @@ Active workstream is **W1 — Federation v1**. Workers should:
 ## #631 — re-seed preserves user fleet data (CRITICAL) — fix/631-reseed-preserves-fleet-data
 
 - Status: implemented + tested. PRIMARY: install.sh PRESERVE_PATHS += fleet/\*.yaml + fleet/agents + fleet/run (glob-aware cp-fallback); TS parity. SECONDARY: refreshActiveFleetUnits propagates unit fixes to ~/.config/systemd/user on mosaic update. bash F6 + TS + unit tests green. Detail: scratchpads/631-reseed-preserves-fleet.md.
-
-## #633 — comms-block emitter + FLEET-LAUNCH runbook — feat/633-comms-block-runbook
-
-- Status: implemented + tested (TDD). `mosaic fleet comms-block <role> [--host]` wraps resolveCommsBlock → readFleetCommsBlock; fails loud (stderr + exit 1) on unknown role / missing roster instead of silent empty. docs/fleet/FLEET-LAUNCH.md runbook: worker path + orchestrator .env fold (MOSAIC_AGENT_COMMAND; line-41 [-z] short-circuits line-44 yolo hardcode) + 3 launch gotchas + #632 preserve note + North-Star 4-field arc (harness ✅/model ✅ roster-native today; yolo + command/channels = PATH B #636). 177 fleet+comms tests green (6 new resolveCommsBlock cases). PATH A of the A→B→webUI arc. Detail: scratchpads/633-comms-block-runbook.md.

docs/fleet/FLEET-LAUNCH.md

@@ -1,114 +0,0 @@
-# Fleet Launch Runbook
-
-How every Mosaic fleet agent — workers **and** the orchestrator — is launched, and how to
-configure each one. The guiding principle: **one roster-driven launcher**. There is no bespoke
-per-agent launch script; the roster plus per-agent `.env` files are the single source of launch
-config.
-
-## The launch chain
-
-| Layer            | File                                              | Responsibility                                                                                                                                              |
-| ---------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| systemd unit     | `mosaic-agent@<role>.service`                     | One templated unit per role; `ExecStart` runs the session launcher with the instance name `%i`. Defaults `MOSAIC_AGENT_RUNTIME=pi`, `MOSAIC_AGENT_NAME=%i`. |
-| session launcher | `tools/fleet/start-agent-session.sh <role>`       | Builds the launch command, opens the tmux pane, wires the heartbeat.                                                                                        |
-| launch command   | `mosaic yolo <runtime>` (or a per-agent override) | Replaces the pane's foreground process with the runtime, fully seeded.                                                                                      |
-| seeding          | `mosaic`'s `composeContract()`                    | Injects the Constitution/USER/TOOLS/runtime contract, `*.local` overlays, **and** the Fleet-Comms cheat-sheet — all via `--append-system-prompt`.           |
-
-Per-agent overrides live in `fleet/agents/<role>.env`, generated from `roster.yaml` by
-`generateAgentEnv` (`packages/mosaic/src/commands/fleet.ts`) and consumed by the launcher.
-
-## Worker launch path (default)
-
-1. `roster.yaml` carries each agent's `runtime` and optional `model_hint`.
-2. `generateAgentEnv` emits `fleet/agents/<role>.env` with `MOSAIC_AGENT_NAME`,
-   `MOSAIC_AGENT_RUNTIME`, and `MOSAIC_AGENT_MODEL`.
-3. `start-agent-session.sh` has no `MOSAIC_AGENT_COMMAND` set, so it falls through to the default
-   (line ~44):
-   ```sh
-   MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME${MOSAIC_AGENT_MODEL:+ --model $MOSAIC_AGENT_MODEL}"
-   ```
-4. The launcher bakes `MOSAIC_AGENT_NAME` into the pane command (line ~118), so `composeContract`
-   can inject the Fleet-Comms cheat-sheet for that role.
-
-That is the whole worker path: roster → `.env` → `mosaic yolo <runtime>` → seeded pane.
-
-## Orchestrator fold (PATH A — ships today)
-
-The orchestrator is **just another roster agent** launched through the canonical path — not a
-snowflake script.
-
-| Piece              | Value                               |
-| ------------------ | ----------------------------------- |
-| host-side launcher | `orchestrator-launch.sh`            |
-| systemd unit       | `mosaic-fleet-orchestrator.service` |
-| tmux session       | `orchestrator` (role-named)         |
-
-Set its launch command via `fleet/agents/orchestrator.env`:
-
-```sh
-MOSAIC_AGENT_COMMAND='mosaic yolo claude --channels plugin:discord@<channel>'
-```
-
-When `MOSAIC_AGENT_COMMAND` is set, `start-agent-session.sh`'s `if [ -z "$MOSAIC_AGENT_COMMAND" ]`
-guard (line ~41) is false, so the line-44 default — **including its hardcoded `yolo`** — is skipped
-entirely. The override fully controls the runtime and flags. Routing through `mosaic yolo claude`
-(rather than a raw `claude` invocation) is what gives the orchestrator the same full
-`composeContract` seeding + Fleet-Comms cheat-sheet as every worker, with `--channels` and any
-other flags passed straight through to the `claude` binary.
-
-## Launch gotchas
-
-1. **Flag conflict.** `mosaic yolo claude` already injects `--dangerously-skip-permissions`. Do
-   **not** also pass `--permission-mode bypassPermissions` — the `claude` binary would receive both.
-   Use `mosaic yolo claude …` alone (yolo covers the unattended posture), **or** non-yolo
-   `mosaic claude --permission-mode bypassPermissions …`. Never mix the two.
-2. **`MOSAIC_AGENT_NAME` must reach the pane.** The launcher bakes it from the instance name, and
-   `composeContract` gates the Fleet-Comms block on it (`launch.ts`, in `composeContract`) — **and**
-   the role must be a member of `roster.yaml`, or the block resolves empty.
-3. **`launchRuntime` guards.** `mosaic yolo claude` runs `checkSoul` / `checkRuntime` /
-   `checkSequentialThinking`. The host needs `SOUL.md` and the sequential-thinking MCP, or the
-   launch aborts (a raw `claude` invocation skipped these checks). Dry-run the composed command in a
-   throwaway tmux session before swapping a live launcher.
-
-## Why per-agent `.env` survives upgrades (#632)
-
-`install.sh` `PRESERVE_PATHS` includes `fleet/*.yaml`, `fleet/agents`, and `fleet/run`, so
-`mosaic update`'s framework re-seed **preserves** your roster and per-agent `.env` overrides
-(glob-aware `cp` fallback; matching TS parity in `file-adapter.ts`). Before #632, an auto re-seed
-could wipe them — which is exactly why PATH A's `.env` override is safe to rely on now.
-
-## Inspecting the comms wiring
-
-- `mosaic fleet comms-block <role>` prints the Fleet-Comms cheat-sheet a given role receives at
-  launch — its `[host:session]` identity, the exact `agent-send.sh` command for each peer, and the
-  FLIP / `--verify` conventions. `--host <h>` previews a cross-host view. An unknown role or missing
-  roster **fails loud** (stderr + non-zero exit), so a typo is never a silent no-op.
-- Versus `mosaic compose-contract <runtime>`: that emits the **whole** system prompt and reads the
-  role from `MOSAIC_AGENT_NAME` (a full-prompt smoke test). `comms-block` is the targeted,
-  explicit-arg, comms-only view — e.g. `mosaic fleet comms-block coder0-0` to preview a peer.
-
-## North Star / future direction
-
-**Vision:** a webUI lets the user edit each agent's launch config — switch **harness**
-(claude / pi / codex / opencode), toggle **yolo**, pick a **model**, set a **command/channels**
-override — with no terminal.
-
-**Continuity — this is not a new launch path.** It is a data-model + UI-binding layer over the
-existing roster-driven launcher. Field-by-field status today:
-
-| Launch-config field      | Roster-native today? | Mechanism / gap                                                                                                                                          |
-| ------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **harness** (`runtime`)  | ✅ end-to-end        | `roster.runtime` → `generateAgentEnv` emits `MOSAIC_AGENT_RUNTIME` → launcher line 44. UI just writes the field.                                         |
-| **model** (`model_hint`) | ✅ end-to-end        | `roster.model_hint` → `MOSAIC_AGENT_MODEL` → launcher line 44 `--model`. UI just writes the field.                                                       |
-| **yolo**                 | ❌ new               | Launcher line 44 **hardcodes** `mosaic yolo`. A non-yolo toggle needs a roster `yolo` field → emit `MOSAIC_AGENT_YOLO` → make line 44 conditional.       |
-| **command / channels**   | ❌ new               | `MOSAIC_AGENT_COMMAND` is **consumed** (launcher line ~12) but `generateAgentEnv` does not emit it. Needs a roster `command`/`channels` field → emitted. |
-
-**The arc:**
-
-- **A** — `.env` `MOSAIC_AGENT_COMMAND` hatch: manual, ships now, kept safe across upgrades by #632.
-- **B** — roster-native launch-config: harness + model are already there; add the **yolo** toggle
-  (line-44 conditional) and **command/channels** emission to complete the data model.
-- **webUI** — binds dropdowns/toggles directly to those four roster fields.
-
-PATH A's `.env` override is the **manual form** of exactly what PATH B makes roster-native and the
-webUI edits — one continuous arc, not three separate features. PATH B is tracked as #636.

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

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

packages/mosaic/framework/tools/tmux/agent-send.sh

@@ -12,10 +12,6 @@
 #   ambiguity about lanes or origin. Recipients replying should FLIP the
 #   preamble: [<dst> -> <src>] ... (this tool sends; it does not auto-reply).
 #
-#   Optionally tags the message with a TRIAGE CLASS (see -C / --class) so a
-#   comms daemon can route it (deliver-to-agent vs log-and-drop) from an exact
-#   field instead of re-deriving intent from the body.
-#
 # WHY A WRAPPER
 #   Reliable submission into an interactive REPL (Claude Code / Codex) is fiddly:
 #   a trailing Enter is often swallowed and the message sits as an unsubmitted
@@ -30,7 +26,6 @@
 #   agent-send.sh [-L socket] -s <dst_session> -m "message"                 # local target
 #   agent-send.sh [-L socket] -H user@host -s <dst_session> -m "message"    # remote target
 #   agent-send.sh [-L socket] -H user@host -n <dst_hostname> -s <sess> -f msg.txt
-#   agent-send.sh -s mos-claude --class terminal-log -m "ACK — received"
 #   echo "msg" | agent-send.sh [-L socket] -H user@host -s <dst_session>
 #
 # OPTIONS
@@ -41,61 +36,27 @@
 #                   Default: local hostname, or (remote) resolved via one ssh.
 #   -m MESSAGE      message text (single- or multi-line)
 #   -f FILE         read message from FILE instead of -m
-#   -C CLASS        triage class for a comms daemon. One of:
-#                     terminal-log  log-only; never needs the agent's attention
-#                     actionable    carries a decision/blocker/gate — deliver
-#                     human         from a human operator — deliver
-#                     reaction      an emoji/ack reaction
-#                   Long form: --class CLASS (or --class=CLASS). When SET, the
-#                   preamble carries a ` class=<CLASS>` token INSIDE the bracket:
-#                       [<src> -> <dst> class=terminal-log] <message>
-#                   When OMITTED, NO token is emitted and the preamble is
-#                   byte-for-byte identical to the classic format. Consumers MUST
-#                   treat an absent class as 'actionable' (fail-safe: agent sees it).
 #   -S SRC_LABEL    override source label "<host>:<session>" (default: auto)
 #   -r N            Enter-flush attempts passed through (default 2)
 #   -v              verbose: print pane tail after delivery
 #   -h              help
 #
-# PREAMBLE GRAMMAR  (for consumers / daemons mirroring this producer)
-#   ^\[(\S+) -> (\S+?)(?: class=(terminal-log|actionable|human|reaction))?\] (.*)$
-#     group 1 = src label   group 2 = dst host:session
-#     group 3 = class (absent => actionable)   group 4 = message body
-#
 # EXIT CODES  (passed through from send-message.sh)
 #   0 delivered/queued · 1 target not found · 2 still draft · 3 usage error
 set -uo pipefail
 
 SELF_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
-# Sender is overridable via env purely for testing (inject a capture stub). The
+SENDER="$SELF_DIR/send-message.sh"
-# default is the canonical send-message.sh beside this script; production callers
-# never set AGENT_SEND_SENDER, so behavior is unchanged.
-SENDER="${AGENT_SEND_SENDER:-$SELF_DIR/send-message.sh}"
-
-# Translate the long option --class[=value] into "-C value" so getopts (which is
-# short-option-only) can parse it. Every other argument passes through untouched,
-# so callers that never use --class hit the exact original getopts path.
-args=()
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --class)   [ $# -ge 2 ] || { echo "ERROR: --class requires a value" >&2; exit 3; }
-               args+=(-C "$2"); shift 2 ;;
-    --class=*) args+=(-C "${1#*=}"); shift ;;
-    *)         args+=("$1"); shift ;;
-  esac
-done
-set -- ${args[@]+"${args[@]}"}
 
 DST_SESSION=""; SSH_TARGET=""; DST_HOST=""; MSG=""; FILE=""; SOCKET_NAME=""
-SRC_LABEL=""; RETRIES=2; VERBOSE=0; CLASS=""
+SRC_LABEL=""; RETRIES=2; VERBOSE=0
-usage() { sed -n '2,/^set -uo pipefail/{/^set -uo pipefail/d;p}' "$0"; exit "${1:-3}"; }
+usage() { sed -n '2,44p' "$0"; exit "${1:-3}"; }
 
-while getopts "L:s:H:n:m:f:S:r:C:vh" o; do
+while getopts "L:s:H:n:m:f:S:r:vh" o; do
   case "$o" in
     L) SOCKET_NAME=$OPTARG ;;
     s) DST_SESSION=$OPTARG ;; H) SSH_TARGET=$OPTARG ;; n) DST_HOST=$OPTARG ;;
     m) MSG=$OPTARG ;; f) FILE=$OPTARG ;; S) SRC_LABEL=$OPTARG ;;
-    C) CLASS=$OPTARG ;;
     r) RETRIES=$OPTARG ;; v) VERBOSE=1 ;; h) usage 0 ;; *) usage 3 ;;
   esac
 done
@@ -103,17 +64,6 @@ done
 [ -n "$DST_SESSION" ] || { echo "ERROR: -s DST_SESSION is required" >&2; usage 3; }
 [ -x "$SENDER" ] || { echo "ERROR: send-message.sh not found beside this script" >&2; exit 3; }
 
-# Validate the triage class only when one was given. An absent class emits NO
-# token (preamble byte-identical to the classic format); the consumer defaults
-# absent => actionable.
-CLASS_TOKEN=""
-if [ -n "$CLASS" ]; then
-  case "$CLASS" in
-    terminal-log|actionable|human|reaction) CLASS_TOKEN=" class=${CLASS}" ;;
-    *) echo "ERROR: invalid --class '$CLASS' (allowed: terminal-log, actionable, human, reaction)" >&2; exit 3 ;;
-  esac
-fi
-
 # Message body from -f / -m / stdin.
 if   [ -n "$FILE" ]; then [ -r "$FILE" ] || { echo "ERROR: cannot read $FILE" >&2; exit 3; }; MSG=$(cat -- "$FILE")
 elif [ -z "$MSG" ] && [ ! -t 0 ]; then MSG=$(cat)
@@ -140,7 +90,7 @@ if [ -z "$DST_HOST" ]; then
   fi
 fi
 
-PREAMBLE="[${SRC_LABEL} -> ${DST_HOST}:${DST_SESSION}${CLASS_TOKEN}]"
+PREAMBLE="[${SRC_LABEL} -> ${DST_HOST}:${DST_SESSION}]"
 FULL="${PREAMBLE} ${MSG}"
 B64=$(printf '%s' "$FULL" | base64 -w0)
 

packages/mosaic/framework/tools/tmux/agent-send.test.sh

@@ -1,97 +0,0 @@
-#!/usr/bin/env bash
-# agent-send.test.sh — regression + grammar lock for agent-send.sh --class.
-#
-# Strategy: inject a capture stub via AGENT_SEND_SENDER that decodes the -b
-# base64 payload and prints the FULL message (preamble + body) so we can assert
-# the exact bytes on the wire. Local path only (no ssh), -n pins the dst host so
-# the preamble is deterministic across machines.
-#
-# Guarantees locked here:
-#   1. REGRESSION BAR — no --class => preamble byte-for-byte identical to classic.
-#   2. --class <c> => ` class=<c>` token emitted inside the bracket.
-#   3. --class=<c> (equals form) parses identically to the space form.
-#   4. -C <c> short form parses identically.
-#   5. invalid class => exit 3, nothing sent.
-#   6. --class with no value => exit 3.
-#   7. the documented consumer regex parses producer output for every class.
-set -uo pipefail
-
-HERE=$(cd -- "$(dirname -- "$0")" && pwd)
-TOOL="$HERE/agent-send.sh"
-
-# Capture stub: stands in for send-message.sh. Decodes -b and prints the payload.
-STUB=$(mktemp)
-trap 'rm -f "$STUB"' EXIT
-cat >"$STUB" <<'STUB_EOF'
-#!/usr/bin/env bash
-set -uo pipefail
-b64=""
-while getopts "t:b:r:v" o; do case "$o" in b) b64=$OPTARG ;; *) : ;; esac; done
-printf '%s' "$b64" | base64 -d
-STUB_EOF
-chmod +x "$STUB"
-
-PASS=0; FAIL=0
-ok()   { PASS=$((PASS+1)); printf 'ok   %s\n' "$1"; }
-no()   { FAIL=$((FAIL+1)); printf 'FAIL %s\n   %s\n' "$1" "$2"; }
-
-# Run the tool with the stub injected; echoes captured payload on stdout.
-run() { AGENT_SEND_SENDER="$STUB" bash "$TOOL" -S a:src -n dsthost "$@"; }
-
-# Documented consumer grammar — the daemon will mirror exactly this.
-GRAMMAR='^\[(\S+) -> (\S+) class=(terminal-log|actionable|human|reaction)\] (.*)$'
-GRAMMAR_NOCLASS='^\[(\S+) -> (\S+)\] (.*)$'
-
-# 1. REGRESSION BAR: classic preamble, byte-for-byte.
-got=$(run -s mos -m "hello world")
-want='[a:src -> dsthost:mos] hello world'
-[ "$got" = "$want" ] && ok "regression: no --class is byte-identical" \
-  || no "regression: no --class is byte-identical" "got=[$got] want=[$want]"
-
-# 2. --class space form emits the token.
-got=$(run -s mos --class terminal-log -m "ACK")
-want='[a:src -> dsthost:mos class=terminal-log] ACK'
-[ "$got" = "$want" ] && ok "--class terminal-log emits token" \
-  || no "--class terminal-log emits token" "got=[$got] want=[$want]"
-
-# 3. --class=value equals form.
-got=$(run -s mos --class=actionable -m "decide X")
-want='[a:src -> dsthost:mos class=actionable] decide X'
-[ "$got" = "$want" ] && ok "--class=actionable (equals form)" \
-  || no "--class=actionable (equals form)" "got=[$got] want=[$want]"
-
-# 4. -C short form.
-got=$(run -s mos -C human -m "from a person")
-want='[a:src -> dsthost:mos class=human] from a person'
-[ "$got" = "$want" ] && ok "-C human (short form)" \
-  || no "-C human (short form)" "got=[$got] want=[$want]"
-
-# 5. invalid class => exit 3, no send.
-if out=$(run -s mos --class bogus -m "x" 2>/dev/null); then
-  no "invalid class rejected" "expected non-zero exit, got 0 (out=[$out])"
-else
-  rc=$?
-  [ "$rc" = 3 ] && [ -z "$out" ] && ok "invalid class => exit 3, nothing sent" \
-    || no "invalid class => exit 3, nothing sent" "rc=$rc out=[$out]"
-fi
-
-# 6. --class with no value => exit 3.
-if run -s mos -m "x" --class 2>/dev/null; then
-  no "--class with no value rejected" "expected non-zero exit, got 0"
-else
-  [ "$?" = 3 ] && ok "--class with no value => exit 3" || no "--class with no value => exit 3" "wrong rc"
-fi
-
-# 7. consumer grammar parses every class + classic line.
-for c in terminal-log actionable human reaction; do
-  line=$(run -s mos --class "$c" -m "body $c")
-  [[ "$line" =~ $GRAMMAR ]] && [ "${BASH_REMATCH[3]}" = "$c" ] && [ "${BASH_REMATCH[4]}" = "body $c" ] \
-    && ok "grammar parses class=$c" || no "grammar parses class=$c" "line=[$line]"
-done
-classic=$(run -s mos -m "plain body")
-[[ "$classic" =~ $GRAMMAR_NOCLASS ]] && [ "${BASH_REMATCH[3]}" = "plain body" ] \
-  && ok "grammar (no-class) parses classic line" || no "grammar (no-class) parses classic line" "line=[$classic]"
-
-echo "---"
-echo "PASS=$PASS FAIL=$FAIL"
-[ "$FAIL" -eq 0 ]

packages/mosaic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicstack/mosaic",
-  "version": "0.0.41",
+  "version": "0.0.40",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",

packages/mosaic/src/commands/fleet.spec.ts

@@ -95,7 +95,6 @@ describe('registerFleetCommand', () => {
     expect(agent).toBeDefined();
     expect(agent!.options.map((option) => option.long)).toContain('--list');
     expect(agent!.commands.map((command) => command.name()).sort()).toEqual([
-      'comms-block',
       'reset',
       'roster',
       'send',

packages/mosaic/src/commands/fleet.ts

@@ -7,7 +7,6 @@ import { spawn } from 'node:child_process';
 import * as readline from 'node:readline';
 import type { Command } from 'commander';
 import YAML from 'yaml';
-import { resolveCommsBlock } from '../fleet/comms-onboarding.js';
 
 /**
  * A function that spawns a command with inherited stdio (TTY passthrough).
@@ -1360,23 +1359,6 @@ export function registerFleetAgentCommands(
       }
     });
 
-  agentCommand
-    .command('comms-block <role>')
-    .description(
-      "Print the Fleet Comms cheat-sheet for a roster role (preview a peer's peer-reach view)",
-    )
-    .option('--host <host>', 'Override the fleet host (preview a cross-host peer view)')
-    .action((role: string, opts: { host?: string }) => {
-      const mosaicHome = resolveMosaicHomeFromCommand(agentCommand, deps.mosaicHome);
-      const res = resolveCommsBlock(mosaicHome, role, opts.host);
-      if (!res.ok) {
-        console.error(`[mosaic] comms-block: ${res.error}`);
-        process.exitCode = 1;
-        return;
-      }
-      console.log(res.output);
-    });
-
   agentCommand
     .command('status [agent]')
     .description('Show tmux status for the local fleet or one agent')

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

@@ -7,7 +7,6 @@ import {
   buildFleetCommsBlock,
   renderPeerReach,
   readFleetCommsBlock,
-  resolveCommsBlock,
   type CommsPeer,
 } from './comms-onboarding.js';
 
@@ -186,53 +185,3 @@ 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]`');
-  });
-});

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

@@ -179,48 +179,5 @@ export function readFleetCommsBlock(
   });
 }
 
-/** Result of resolving a comms-block emit request — see `mosaic fleet comms-block`. */
-export interface CommsBlockResult {
-  /** True when a cheat-sheet was produced; false maps to stderr + non-zero exit. */
-  ok: boolean;
-  /** The Fleet-Comms cheat-sheet (empty unless ok). */
-  output: string;
-  /** Operator-facing reason when !ok. */
-  error?: string;
-}
-
-/**
- * Resolve the Fleet-Comms cheat-sheet for an explicit <role>, backing the
- * `mosaic fleet comms-block <role>` command. Unlike readFleetCommsBlock — which
- * returns '' on any miss so composeContract can no-op silently during a launch —
- * this NEVER silently emits empty: an unknown role or missing roster yields
- * ok:false + an operator-facing reason, so the CLI surfaces it (stderr + exit 1)
- * rather than printing nothing. That makes it safe to preview any peer's view,
- * e.g. `mosaic fleet comms-block coder0-0`.
- */
-export function resolveCommsBlock(
-  mosaicHome: string,
-  role: string | undefined,
-  fleetHost?: string,
-): CommsBlockResult {
-  if (!role) {
-    return { ok: false, output: '', error: 'comms-block requires a <role> argument' };
-  }
-  const block = fleetHost
-    ? readFleetCommsBlock(mosaicHome, role, fleetHost)
-    : readFleetCommsBlock(mosaicHome, role);
-  if (!block) {
-    const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
-    return {
-      ok: false,
-      output: '',
-      error: existsSync(rosterPath)
-        ? `role "${role}" is not a member of the fleet roster at ${rosterPath}`
-        : `no fleet roster at ${rosterPath}`,
-    };
-  }
-  return { ok: true, output: block };
-}
-
 /** Default mosaic home (mirrors launch.ts), for callers that don't pass one. */
 export const DEFAULT_MOSAIC_HOME_FOR_COMMS = join(homedir(), '.config', 'mosaic');