feat(mosaic): mosaic update re-seeds framework + relaunches agents (#609 )

Closes R13 (F3-m3). mosaic update installed the new npm CLI but never re-seeded ~/.config/mosaic from the package's bundled framework/, so shipped launcher/runtime changes (agent-name export + native HB) stayed DORMANT until a manual re-seed — operators got the new CLI on a stale framework. - update-checker.ts: resolveBundledFrameworkRoot, buildReseedCommand (install.sh in MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep — the P4 data-safe reconcile: framework-owned overwrite + backup-once; SOUL/USER/*.local/credentials kept), runFrameworkReseed, readRosterAgentNames, buildRelaunchCommands. - cli.ts update: after a successful CLI install that includes @mosaicstack/mosaic, re-seed the framework (default-on; --no-reseed to skip). Then --relaunch restarts rostered agents (systemctl --user restart mosaic-agent@<name>), else prints clear activation guidance. Only re-seeds when the framework-bearing package updated. Flow: update CLI -> re-seed framework (data-safe) -> relaunch agents (opt-in). Verified: 6 new unit tests + 19 runtime + 26 launch tests green; tsc/eslint/ prettier clean. Sync data-safety already proven (P4 matrix + live validation). Refs #609 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83
2026-06-21 22:29:03 -05:00
37 changed files with 103 additions and 2191 deletions
--- a/.woodpecker/publish.yml
+++ b/.woodpecker/publish.yml
@@ -4,23 +4,6 @@
 variables:
  - &node_image 'node:22-alpine'
  - &enable_pnpm 'corepack enable'
  # Heavy kaniko image builds (~25 min) — gate them so a merge that only touches
  # the npm-only CLI (@mosaicstack/mosaic) or docs does NOT rebuild the platform
  # images (gateway/appservice/web do not depend on @mosaicstack/mosaic). Releases
  # (tags) always build everything. Exclude-list keeps the default SAFE: any
  # non-excluded change still builds, so no transitive dep can silently go stale.
  # (Woodpecker: `when` entries are OR'd; `path` applies to push/PR only — hence
  # the separate `event: tag` entry.)
  - &image_build_when
    - event: tag
    - event: [push, manual]
      branch: main
      path:
        exclude:
          - 'packages/mosaic/**'
          - 'docs/**'
          - '**/*.md'
          - '.woodpecker/**'
 when:
  - branch: [main]
@@ -43,15 +26,6 @@ steps:
  publish-npm:
    image: *node_image
    # Publish only when a publishable package changed (or on a release tag); a
    # pure-docs merge runs no publish. Cheap step, but gated for cleanliness.
    when:
      - event: tag
      - event: [push, manual]
        branch: main
        path:
          include:
            - 'packages/**'
    environment:
      NPM_TOKEN:
        from_secret: gitea_token
@@ -117,7 +91,6 @@ steps:
  build-gateway:
    image: gcr.io/kaniko-project/executor:debug
    when: *image_build_when
    environment:
      REGISTRY_USER:
        from_secret: gitea_username
@@ -143,7 +116,6 @@ steps:
  build-appservice:
    image: gcr.io/kaniko-project/executor:debug
    when: *image_build_when
    environment:
      REGISTRY_USER:
        from_secret: gitea_username
@@ -169,7 +141,6 @@ steps:
  build-web:
    image: gcr.io/kaniko-project/executor:debug
    when: *image_build_when
    environment:
      REGISTRY_USER:
        from_secret: gitea_username
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -58,27 +58,3 @@ Active workstream is **W1 — Federation v1**. Workers should:
 ## F3-m3 — mosaic update re-seeds framework + relaunches agents (#609) — feat/f3-m3-update-reseed
 - Status: implemented + tested. Closes R13: `mosaic update` now re-seeds the framework (data-safe MOSAIC_SYNC_ONLY) after the CLI install so shipped launcher/runtime changes activate; `--relaunch` restarts rostered agents; `--no-reseed` opts out. Detail: scratchpads/f3-m3-update-reseed.md.
 ## Fleet-polish bundle — boot-survival symmetry (#611) — feat/fleet-polish-bundle
 - Status: MERGED to main. disable-on-remove (boot-resurrection bug, TDD) + add-enable + init-R5 hard guarantee. 4 new + 147 existing fleet tests green. Detail: scratchpads/fleet-polish-bundle.md.
 ## Fleet enhancer role + two-agent floor (#614) — feat/fleet-enhancer-floor
 - Status: MERGED to main. enhancer added to 4 presets; init guarantees 1 orchestrator + >=1 enhancer; remove protects the sole enhancer; enhancer role doc. 155 fleet tests green. Detail: scratchpads/fleet-enhancer-floor.md.
 ## F4 — Orchestrator chat connector + Matrix (#616) — feat/f4-matrix-connector
 - Status: Phase 1 MERGED (#617: connector interface send/subscribe/health + registry + roster schema + design). Phase 2a (#618): Matrix CS-API client + factory. 20 connector tests green; no fleet.ts changes. Remaining Phase 2: init/configure connector-selection UX + roster wiring, systemd launch wiring, Conduit deploy guide. Detail: scratchpads/f4-matrix-connector.md.
 ## Fleet onboarding-injection — comms cheat-sheet + peer roster (#620) — feat/fleet-comms-onboarding
 - Status: implemented + tested. Injects # Fleet Comms (peer roster + cross-host agent-send commands + FLIP-reply + --verify) into each spawned fleet agent via composeContract; optional per-agent host/ssh/socket roster fields (socket: named → -L, unset → default socket no -L). 10 + 2 tests green. Detail: scratchpads/fleet-comms-onboarding.md.
 ## Fleet stand-up fixes — model_hint→--model + socket-default trap (#626) — feat/fleet-standup-fixes
 - Status: implemented + tested. FIX1 model_hint→MOSAIC_AGENT_MODEL→--model. FIX2 absent socket = default tmux socket (no -L) across parse/spawn/systemd-unit/observe (socketArgs helper, bare-empty shellEnvValue, conditional -L). 158 fleet tests green; shipped presets unaffected (explicit socket_name). Detail: scratchpads/fleet-standup-fixes.md.
 ## #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.
--- a/docs/fleet/f4-matrix-connector.md
+++ b/docs/fleet/f4-matrix-connector.md
@@ -1,92 +0,0 @@
 # F4 — Orchestrator chat connector + Matrix (local homeserver)
 > **Issue:** #616 · **Doctrine:** `docs/fleet/north-star.md` (#613) — orchestrator-chat-connector decision.
 > **Status:** Phase 1 (abstraction + scaffold) in this PR; Phase 2+ are follow-ups (below).
 ## Goal
 The fleet **orchestrator** is the operator's single point of contact. The north-star makes the
 chat channel a **user-chosen connector** — tmux today, Discord live ("Mos"), with Matrix /
 Telegram / Slack configurable. F4 adds **Matrix** (local homeserver) as a **peer** connector and,
 first, the small **connector abstraction** that makes connectors pluggable without touching fleet
 core.
 ## The abstraction (Phase 1 — this PR)
 Connectors implement one small, uniform interface (`src/fleet/connectors/types.ts`):
 ```ts
 interface OrchestratorConnector {
  readonly kind: 'tmux' | 'discord' | 'matrix';
  send(message: OutboundMessage): Promise<SendResult>; // orchestrator → human
  subscribe(handler: (m: InboundMessage) => void): Unsubscribe; // human → orchestrator
  health(): Promise<ConnectorHealth>; // reachable + authenticated
 }
 ```
 - **send / subscribe / health** — the only surface fleet core depends on. `SendResult` is the
  ack half; `health()` is the liveness half.
 - **Thread-aware by metadata** — `OutboundMessage.threadId` / `InboundMessage.threadId` are
  optional, so thread-capable connectors (Matrix rooms/threads, the future first-party Mosaic
  Discord plugin) fit **without an interface change**.
 - **Registry** (`registry.ts`) — implementations register a factory by kind; `createConnector(config)`
  resolves one from roster config. Phase 1 ships the registry + `resolveConnectorKind` (defaults
  `tmux` when a roster declares no connector — **back-compat**); the factories land in Phase 2.
 ### Config model
 A roster may carry an optional `connector` block (`roster.schema.json`); absent ⇒ tmux.
 ```yaml
 connector:
  kind: matrix # tmux | discord | matrix
  matrix:
    homeserver_url: https://matrix.example.internal
    user_id: '@mos:example.internal'
    room_id: '!abc:example.internal'
 ```
 **Secrets are never in the roster.** `MATRIX_ACCESS_TOKEN` / `DISCORD_BOT_TOKEN` come from the
 environment (the gateway env-config pattern that already masks them). The sanitization gate would
 reject a token committed to a shipped file anyway.
 ## Matrix connector (Phase 2)
 The connector speaks the **Matrix client-server API** directly over HTTPS (`fetch` — no SDK needed
 for MVP), so it is **homeserver-agnostic**:
 | Op          | Matrix CS-API                                                            |
 | ----------- | ------------------------------------------------------------------------ |
 | `send`      | `PUT /_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}`      |
 | `subscribe` | `GET /_matrix/client/v3/sync` (long-poll, `since` token) → room timeline |
 | `health`    | `GET /_matrix/client/versions` (reachable) + `…/account/whoami` (authed) |
 | threads     | `m.thread` relations ↔ `threadId`                                        |
 ## Local homeserver (infra, not connector code)
 Strategic default: a **self-hosted** homeserver on our own infra — no third-party gateway.
 - **Default: Conduit** (Rust, single binary, low resource) — trivial to stand up for a fleet/dev
  homeserver.
 - **Alternative: Synapse** (mature, feature-complete) for scale.
 The connector only needs `homeserver_url` + `user_id` + `room_id` + an access token, so the
 homeserver choice is a **deployment** concern (a Phase-2 deploy guide), not connector code.
 ## Phasing
 | Phase | Scope                                                                                   | This PR |
 | ----- | --------------------------------------------------------------------------------------- | ------- |
 | **1** | Connector interface + types, registry + kind resolution, roster `connector` schema, doc | ✅ yes  |
 | 2     | Matrix CS-API client (fetch-based send/sync/health) + registered factory + tests        | follow  |
 | 2     | `fleet init` / `configure` connector-selection UX; roster parse wires the block         | follow  |
 | 2     | systemd launch wiring so the orchestrator starts on the chosen connector                | follow  |
 | 3     | Conduit deploy guide; first-party Mosaic Discord (threads) registers as a connector     | follow  |
 ## Back-compat & boundaries
 - Existing rosters (no `connector`) resolve to tmux — **zero change**.
 - Fleet core never branches on connector kind; it depends only on the interface.
 - Cross-host reach rides the **federation** layer (W1), not a bespoke broker (north-star assumption).
 - Phase 1 touches **no** `fleet.ts` core (a self-contained `connectors/` module), so it is
  independent of the in-flight fleet-config PRs.
--- a/docs/fleet/north-star.md
+++ b/docs/fleet/north-star.md
@@ -73,37 +73,6 @@ diff-sanity → squash-merge → verify), **decide-and-inform** cadence, and a d
 this model. See `mosaicstack-aiguide` whitepapers 01 (inter-agent comms) and 03
 (orchestration model) for the rationale.
 ## Fleet roster — the two-agent floor and the role library
 A fleet is **never a single agent**. The minimum viable fleet is **two**:
 | Role             | Mandate                                                                                                                                                                                                                                                                                                                                                                 | Boundaries                                                                                 |
 | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
 | **Orchestrator** | The user's **single point of contact**. Owns the general flow, keeps agentic actions on-target, and **adds/removes agents from the fleet at will** to meet goals and user needs. Exactly **one** per fleet (the existing R5 invariant).                                                                                                                                 | Delegates source work; never the sole worker.                                              |
 | **Enhancer**     | The fleet's **continuous-improvement loop**. Monitors fleet activity, analyzes for enhancements/optimizations, builds a **plan of remediation**, and — **with the orchestrator** — upgrades fleet capability: tool creation/repair, skills, harness improvements, and **bug reports filed to Mosaic Stack** for proper remediation. Recommends which agents are needed. | **Does not code, review code, or perform delivery tasks.** Improvement and diagnosis only. |
 > **Why two, not one:** the orchestrator drives delivery; the enhancer makes the fleet
 > _get better at delivering_ over time. The enhancer is how the fleet self-heals its tools,
 > skills, and harnesses, and how real defects flow back to Mosaic Stack as bug reports.
 > Together they are the irreducible core — every other role is added on demand.
 A **general** fleet starts at this floor: the orchestrator (advised by the enhancer)
 materializes whatever roles prove necessary over the mission's life. Specialized presets
 (coding, research, etc.) seed additional roles up front, but all reduce to the same two-agent
 spine plus an on-demand **role library**:
 | Role profile        | Purpose                                                                           |
 | ------------------- | --------------------------------------------------------------------------------- |
 | **orchestrator**    | point of contact, flow control, fleet composition (1 per fleet)                   |
 | **enhancer**        | fleet monitoring, optimization, tool/skill/harness upgrades, upstream bug reports |
 | **coder**           | implementation (worker; stops at PR-open)                                         |
 | **code review**     | independent code review gate                                                      |
 | **security review** | security/auth/secret review gate                                                  |
 | **research**        | investigation, synthesis, options analysis                                        |
 | **board**           | deliberation panel — moonshot, contrarian, technical, business, financial lenses  |
 | **operations**      | infra, deploy, health, incident response                                          |
 | _…extensible_       | new profiles added as missions demand (orchestrator + enhancer decide)            |
 ## Invariants — "maximal vision, incremental delivery, zero foreclosure"
 Every artifact, starting Phase 2, MUST:
@@ -133,7 +102,7 @@ Every artifact, starting Phase 2, MUST:
 | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
 | 0–1                    | tmux PoC, hardening, published CLI v0.0.34 (#565–#568)                                                                                       | ✅ done |
 | **2 — Observability**  | `fleet ps` (host+tenant aware join), heartbeat protocol + dogfood stub answers it, `agent watch` (read-only), `agent send --verify` receipts | ▶ now   |
-| 3 — Real runtimes      | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: **orchestrator + enhancer**; ephemeral workers per lane)    | planned |
+| 3 — Real runtimes      | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: orchestrator+reviewer; ephemeral workers per lane)          | planned |
 | 4 — Unified definition | one agent schema in gateway; `mosaic agent --new` → materialized per-tenant session; uid-tenant provisioning                                 | planned |
 | 5 — Control plane      | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity                                    | planned |
@@ -152,28 +121,6 @@ Every artifact, starting Phase 2, MUST:
  runtime-bin on PATH (baked into the pane command) + boot-survival (`enable` + linger),
  which `fleet init` should automate.
 ## Decisions of record (2026-06-22, with Jason)
 - **Two-agent floor:** every fleet has, at minimum, an **orchestrator** and an **enhancer**.
  The orchestrator is the user's point of contact and composes the fleet; the enhancer runs the
  continuous-improvement loop (monitor → analyze → remediate → upgrade tools/skills/harness →
  file Mosaic Stack bug reports) and **does not code or review**.
 - **Role library:** orchestrator, enhancer, coder, code review, security review, research,
  board (moonshot/contrarian/technical/business/financial), operations — extensible; the
  orchestrator (advised by the enhancer) adds roles as missions demand.
 - **Orchestrator chat connector:** the orchestrator is reachable over a user-chosen connector
  (tmux now; Telegram/Discord/Matrix/Slack configurable). Validated live: **"Mos" orchestrator
  on Discord** via the Claude Code discord channel plugin (w-jarvis).
 ## Future enhancements (north-star, post-MVP — not on the MVP track)
 - **Mosaic Claude Discord Plugin** — a first-party Mosaic Discord connector that properly
  implements the basic Discord functions **and native Discord threads**. Threads let a user
  separate conversation topics with the orchestrator (the pattern proven by the Hermes agent).
  A major enhancement over the current third-party channel plugin; **not required for the MVP**,
  but a committed north-star target. `ASSUMPTION:` ships as a Mosaic-owned plugin so the fleet
  controls Discord UX (threads, reactions, attachments, per-thread context) end-to-end.
 ## Assumptions (veto-able)
 - `ASSUMPTION:` first-class runtimes = claude, codex, pi, opencode; a "role" (analyst,
--- a/docs/scratchpads/631-reseed-preserves-fleet.md
+++ b/docs/scratchpads/631-reseed-preserves-fleet.md
@@ -1,32 +0,0 @@
 # #631 — re-seed must preserve user fleet data (CRITICAL data-loss)
 - **Issue:** #631 · **Branch:** `fix/631-reseed-preserves-fleet-data`
 ## Root cause
 `mosaic update` auto-runs `install.sh` keep-mode sync (#610). install.sh's rsync `--delete` (keep mode)
 honored PRESERVE_PATHS, but `fleet/` wasn't listed → the sync WIPED `~/.config/mosaic/fleet/roster.yaml`
 (+ run/, agents/). Any user running `mosaic update` lost their roster. (overwrite mode wipes by design;
 the live loss was keep mode.)
 ## Fix (PRIMARY)
 - install.sh PRESERVE_PATHS += `fleet/*.yaml`, `fleet/agents`, `fleet/run` — the framework still SEEDS
  fleet/examples + fleet/roles + fleet/roster.schema.json (synced), but user files survive.
 - Made the cp-fallback (no-rsync) GLOB-AWARE so `fleet/*.yaml` preserves every user roster there too;
  fixed the restore to re-glob per-pattern (so only the user file is restored, not the whole fleet/ dir).
 - file-adapter.ts (TS installer): mirrored the preserve list for parity. (TS syncDirectory is copy-only,
  never --delete, so it never had the bug — belt-and-suspenders + parity.)
 ## Fix (SECONDARY)
 - `refreshActiveFleetUnits()` (update-checker.ts): the re-seed updates ~/.config/mosaic/systemd/user but
  systemd runs ~/.config/systemd/user, so unit fixes (#627) didn't take effect. After the re-seed,
  `mosaic update` now copies the fresh mosaic-\*.service → the active dir + daemon-reload (best-effort,
  only when a fleet is already installed). Wired into the cli.ts update flow.
 ## Verification
 - bash F6 fixture (6 checks: roster/custom-yaml/agents/run survive + examples refreshed + schema seeded);
  20/20 migration matrix green. TS file-adapter test (roster/run/agents survive keep sync). 2 unit tests
  for refreshActiveFleetUnits. tsc/eslint/prettier/sanitize clean.
--- a/docs/scratchpads/f4-matrix-connector.md
+++ b/docs/scratchpads/f4-matrix-connector.md
@@ -1,30 +0,0 @@
 # F4 — Orchestrator chat connector + Matrix (#616)
 - **Issue:** #616 · **Branch:** `feat/f4-matrix-connector` (off main; independent of #615) · **Doctrine:** north-star #613.
 ## Phase 1 (this PR) — abstraction + scaffold
 - `src/fleet/connectors/types.ts`: `OrchestratorConnector` (send/subscribe/health) + message/config types; thread-aware via optional `threadId`; `DEFAULT_CONNECTOR_KIND=tmux`.
 - `src/fleet/connectors/registry.ts`: extensible factory registry; `resolveConnectorKind` (defaults tmux, back-compat); `createConnector` throws `ConnectorNotImplementedError` until Phase 2 registers factories.
 - `roster.schema.json`: optional `connector` block (tmux|discord|matrix; matrix homeserver/user/room; secrets via env, never roster).
 - Design doc `docs/fleet/f4-matrix-connector.md`: interface, config, Matrix CS-API mapping, Conduit-default infra, phasing.
 - **No fleet.ts changes** → self-contained, zero conflict with stacked #615.
 ## Verification
 - 7 connector tests green; tsc/eslint/prettier/sanitize clean; schema valid JSON.
 ## Phase 2+ (follow-ups, in the doc)
 Matrix CS-API client (fetch send/sync/health) + factory; init/configure connector-selection UX + roster-parse wiring; systemd launch wiring; Conduit deploy guide; first-party Mosaic Discord (threads) as a connector.
 ## Phase 2a (feat/f4-matrix-client, stacked on #617) — Matrix CS-API client
 - `src/fleet/connectors/matrix.ts`: `MatrixConnector implements OrchestratorConnector` over the Matrix
  client-server API (injectable fetch, no SDK). `send` → PUT m.room.message (thread-aware); `subscribe`
  → /sync long-poll loop using the pure `parseSyncResponse`; `health` → /versions + /whoami.
  `registerMatrixConnector(env)` registers the factory (token from MATRIX_ACCESS_TOKEN, never roster).
 - Pure helpers `buildMessageBody` + `parseSyncResponse` make send/receive unit-testable.
 - 13 Matrix tests + 7 registry = 20 connector tests green; tsc/eslint/prettier clean.
 - Remaining Phase 2: init/configure connector-selection UX + roster-parse wiring (touches fleet.ts —
  after #615); systemd launch wiring; Conduit deploy guide.
--- a/docs/scratchpads/fleet-comms-onboarding.md
+++ b/docs/scratchpads/fleet-comms-onboarding.md
@@ -1,31 +0,0 @@
 # Fleet onboarding-injection — comms cheat-sheet + peer roster (#620)
 - **Issue:** #620 · **Branch:** `feat/fleet-comms-onboarding` (off main). Root cause of Mos's failed first send.
 ## What
 Inject a `# Fleet Comms` block into each spawned fleet agent's system prompt (via composeContract — the
 runtime-agnostic path every `mosaic yolo <runtime>` agent hits), so it boots knowing how to reach peers.
 - `src/fleet/comms-onboarding.ts` (standalone, no fleet.ts coupling):
  - `parseRosterAgents` (name/class/host/ssh, lenient), `renderPeerReach` (same-host `-s` vs cross-host
    `-H <ssh> -s`), `buildFleetCommsBlock` (self [host:session] identity + agent-send path + peer table +
    FLIP-to-reply + `agent send --verify`=ACCEPTED), `readFleetCommsBlock` (reads roster.yaml; '' if not a member).
  - `composeContract` appends it only when MOSAIC_AGENT_NAME is set + the agent is in the roster.
 - `roster.schema.json`: optional per-agent `host` + `ssh` (cross-host addresses; manual = pre-federation
  stopgap, federation/W1 auto-discovers later).
 ## Acceptance criteria (Mos) — all covered
 1. own [host:session] + agent-send path + peer roster ✓
 2. cross-host correctness: local→`-s` (no -H); remote→`-H <ssh> -s` ✓ (concrete coder0-0@dragon-lin)
 3. FLIP-the-preamble reply rule ✓
 4. `agent send --verify` = ACCEPTED ✓
 5. no `-L` (default socket); matches live tooling ✓
 ## Verification
 - 10 onboarding unit tests (parse, render local/remote/fallback/equal-host, build, situational read) +
  2 composeContract situational tests (injects for fleet agent w/ correct cross-host addr; no-op when
  MOSAIC_AGENT_NAME unset). tsc/eslint/prettier/sanitize clean.
 - Post-merge validation: Mos spawns a real w-jarvis agent → first-try reach to coder0-0@dragon-lin + a local peer.
--- a/docs/scratchpads/fleet-enhancer-floor.md
+++ b/docs/scratchpads/fleet-enhancer-floor.md
@@ -1,26 +0,0 @@
 # Fleet enhancer role + two-agent floor (#614)
 - **Issue:** #614 · **Branch:** `feat/fleet-enhancer-floor` (stacked on #612 `feat/fleet-polish-bundle`)
 - **Doctrine:** `docs/fleet/north-star.md` (PR #613) — every fleet = orchestrator + enhancer minimum.
 ## Changes
 - **Presets** (general, coding, research, hybrid): add `enhancer` (claude, `class: enhancer`,
  `persistent_persona: true`) as a core always-on agent alongside the orchestrator. minimal/local-canary
  unchanged.
 - **fleet.ts**: `countEnhancers` helper; init guarantee extended — non-minimal profiles must yield
  exactly 1 orchestrator AND >=1 enhancer (hard-fail otherwise); `removeAgentFromRoster` refuses to drop
  the sole enhancer (symmetric with the sole-orchestrator guard) so the floor holds at runtime, not just init.
 - **Role doc**: `framework/fleet/roles/enhancer.md` — the enhancer mandate (monitor → analyze → plan →
  upgrade tools/skills/harness WITH orchestrator → file Mosaic Stack bug reports) + boundaries (does NOT
  code or review).
 ## Verification
 - 155 fleet tests green (new: countEnhancers; remove-sole-enhancer guard; remove-allows-when-another;
  init two-agent-floor; every-non-minimal-preset-has-enhancer; updated preset rosters). tsc/eslint/
  prettier/sanitize clean. TDD on the init guarantee + remove protection.
 ## Stacking
 Built on #612's init-R5 code. PR shows #612 + enhancer until #612 merges; then rebase onto main → clean.
--- a/docs/scratchpads/fleet-polish-bundle.md
+++ b/docs/scratchpads/fleet-polish-bundle.md
@@ -1,20 +0,0 @@
 # Fleet-polish bundle — boot-survival symmetry (#611)
 - **Issue:** #611 · **Branch:** `feat/fleet-polish-bundle` · From the Lead's Codex symmetry-gap finding.
 ## Three fixes
 1. **disable-on-remove (BUG, TDD).** `fleet remove` stopped + deleted roster/env/heartbeat but never
   `systemctl --user disable mosaic-agent@NAME.service` → a removed-but-enabled unit could resurrect on
   reboot pointing at deleted config. Fix: `buildSystemdDisableCommand` + disable in `remove`
   (best-effort, gated on !--keep-files).
 2. **add-enable.** `fleet add` now enables the new agent's unit for boot-survival (best-effort,
   independent of --start) — symmetry with disable-on-remove.
 3. **init-R5 guarantee.** `fleet init --write` now FAILS HARD when a non-minimal profile doesn't yield
   exactly one orchestrator (was a soft warning). `minimal` (sanctioned no-orchestrator) still allowed.
 ## Verification
 - 4 new tests (disable builder; remove-invokes-disable; add-invokes-enable; init general → exactly 1
  orchestrator) + 147 existing fleet tests green (151 total). tsc/eslint/prettier clean.
 - TDD on the disable bug per contract.
--- a/docs/scratchpads/fleet-standup-fixes.md
+++ b/docs/scratchpads/fleet-standup-fixes.md
@@ -1,28 +0,0 @@
 # Fleet stand-up fixes — model_hint→--model + socket-default trap (#626)
 - **Issue:** #626 · **Branch:** `feat/fleet-standup-fixes` (off main). PoC-blocking, before doctrine doc.
 ## FIX 1 — model_hint consumed
 - generateAgentEnv emits `MOSAIC_AGENT_MODEL=<modelHint>` (bare empty when unset).
 - start-agent-session.sh default command → `mosaic yolo $RUNTIME ${MOSAIC_AGENT_MODEL:+--model $MOSAIC_AGENT_MODEL}`.
  → pi workers launch with `--model openai-codex/gpt-5.5:high`.
 ## FIX 2 — socket default trap (absent ⇒ literal default socket, no -L everywhere)
 - THE TRAP (3 sites): parseRosterText fallback was DEFAULT_SOCKET_NAME; systemd unit had
  `Environment=MOSAIC_TMUX_SOCKET=mosaic-factory` + `ExecStop ${…:-mosaic-factory}`; start-agent-session
  defaulted `:-mosaic-factory`. All fixed → absent socket = '' = default tmux socket (no -L).
 - `socketArgs(name)` helper → `name ? ['-L', name] : []`; replaced all ~15 -L render sites in fleet.ts.
 - shellEnvValue('') now emits a **bare** `VAR=` (not `''`) — unambiguous empty in systemd EnvironmentFile
  (a quoted '' could become a literal socket named "''").
 - start-agent-session.sh: `_tmux` wrapper passes -L only when socket set; mosaic-agent@.service: dropped the
  socket default + conditional ExecStop. So spawn == observe == onboarding cheat-sheet.
 - CONTAINMENT: all 6 shipped presets set socket_name: mosaic-factory explicitly → unaffected; only
  socket-less rosters (the PoC) get default-socket behavior. DEFAULT_SOCKET_NAME exported for explicit use.
 ## Verification
 - 158 fleet + 201 fleet-adjacent tests green; new: socketArgs none/named, model_hint→env, explicit-socket
  renders -L, socket-less env bare. tsc/eslint/prettier/sanitize clean. Shell bash -n + end-to-end sim
  (socket-less→no -L, model→--model).
--- a/packages/mosaic/framework/fleet/examples/coding.yaml
+++ b/packages/mosaic/framework/fleet/examples/coding.yaml
@@ -15,10 +15,6 @@ agents:
    runtime: claude
    class: orchestrator
    persistent_persona: true
  - name: enhancer
    runtime: claude
    class: enhancer
    persistent_persona: true
  - name: coder0
    runtime: pi
    class: implementer
--- a/packages/mosaic/framework/fleet/examples/general.yaml
+++ b/packages/mosaic/framework/fleet/examples/general.yaml
@@ -15,10 +15,6 @@ agents:
    runtime: claude
    class: orchestrator
    persistent_persona: true
  - name: enhancer
    runtime: claude
    class: enhancer
    persistent_persona: true
  - name: generalist
    runtime: pi
    class: worker
--- a/packages/mosaic/framework/fleet/examples/hybrid.yaml
+++ b/packages/mosaic/framework/fleet/examples/hybrid.yaml
@@ -15,10 +15,6 @@ agents:
    runtime: claude
    class: orchestrator
    persistent_persona: true
  - name: enhancer
    runtime: claude
    class: enhancer
    persistent_persona: true
  - name: coder0
    runtime: pi
    class: implementer
--- a/packages/mosaic/framework/fleet/examples/research.yaml
+++ b/packages/mosaic/framework/fleet/examples/research.yaml
@@ -15,10 +15,6 @@ agents:
    runtime: claude
    class: orchestrator
    persistent_persona: true
  - name: enhancer
    runtime: claude
    class: enhancer
    persistent_persona: true
  - name: researcher0
    runtime: pi
    class: researcher
--- a/packages/mosaic/framework/fleet/roles/enhancer.md
+++ b/packages/mosaic/framework/fleet/roles/enhancer.md
@@ -1,41 +0,0 @@
 # Enhancer — fleet role definition
 The **enhancer** is one half of the fleet's two-agent floor: every fleet runs, at
 minimum, an **orchestrator** and an **enhancer**. The orchestrator drives delivery;
 the enhancer makes the fleet _get better at delivering_ over time.
 It is a **core, always-on** agent (`class: enhancer`, `persistent_persona: true`),
 not an ephemeral per-lane worker.
 ## Mandate
 The enhancer runs the fleet's **continuous-improvement loop**:
 1. **Monitor** fleet activity — agents, heartbeats, sessions, throughput, failures.
 2. **Analyze** for enhancements and optimizations — friction, gaps, recurring defects,
   missing or broken tools, skill/harness shortfalls.
 3. **Plan** a remediation: a concrete improvement with rationale and expected effect.
 4. **Upgrade fleet capability — with the orchestrator** — tool creation/repair, skills,
   harness improvements. The orchestrator owns fleet composition; the enhancer advises and
   implements improvements to the _means of production_, not the product.
 5. **File upstream bug reports** to Mosaic Stack for real defects, so they flow back to the
   framework for proper remediation rather than being patched over locally.
 6. **Recommend which agents are needed** — advise the orchestrator on roles to add/remove as
   the mission evolves.
 ## Boundaries
 - **Does NOT write product/source code.**
 - **Does NOT review code** (that is the code-review / security-review roles).
 - **Does NOT perform delivery tasks.**
 Improvement and diagnosis only. When the enhancer finds work that requires coding or review,
 it files it (bug report / recommendation) and the orchestrator materializes the right worker.
 ## Why two, not one
 The orchestrator alone optimizes for _this_ delivery; the enhancer optimizes for _every future_
 delivery — self-healing the fleet's tools, skills, and harnesses, and routing real defects
 upstream. Together they are the irreducible core; every other role is added on demand.
 > Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).
--- a/packages/mosaic/framework/fleet/roster.schema.json
+++ b/packages/mosaic/framework/fleet/roster.schema.json
@@ -81,18 +81,6 @@
          "class": {
            "type": "string"
          },
          "host": {
            "description": "Host the agent runs on (hostname or IP). Absent = the fleet host. Used by onboarding-injection to render cross-host comms addresses. Manual cross-host listing is a pre-federation stopgap; federation (W1) auto-discovers later.",
            "type": "string"
          },
          "ssh": {
            "description": "SSH target (user@host) for a cross-host peer, so onboarding renders the `agent-send.sh -H <user@host>` form. Optional; only needed for agents on a different host than the fleet.",
            "type": "string"
          },
          "socket": {
            "description": "tmux socket the agent's session runs on. Onboarding renders `-L <socket>` when set; absent = the default socket (no `-L`). Must match the LIVE socket, not blindly inherit the roster's tmux.socket_name.",
            "type": "string"
          },
          "working_directory": {
            "type": "string"
          },
@@ -125,35 +113,6 @@
          }
        }
      }
    },
    "connector": {
      "description": "Orchestrator chat connector (F4). Optional — absent means tmux (back-compat). Secrets (access/bot tokens) come from the environment, never this file.",
      "type": "object",
      "additionalProperties": false,
      "required": ["kind"],
      "properties": {
        "kind": {
          "enum": ["tmux", "discord", "matrix"]
        },
        "matrix": {
          "type": "object",
          "additionalProperties": false,
          "required": ["homeserver_url", "user_id", "room_id"],
          "properties": {
            "homeserver_url": { "type": "string" },
            "user_id": { "type": "string" },
            "room_id": { "type": "string" }
          }
        },
        "discord": {
          "type": "object",
          "additionalProperties": false,
          "required": ["channel_id"],
          "properties": {
            "channel_id": { "type": "string" }
          }
        }
      }
    }
  }
 }
--- a/packages/mosaic/framework/install.sh
+++ b/packages/mosaic/framework/install.sh
@@ -23,15 +23,7 @@ INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 # entries (CONSTITUTION/AGENTS/STANDARDS) ARE re-applied afterward by
 # reconcile_framework_files (overwrite + backup-once); the rest stay user-owned.
 # User-created content in these paths survives rsync --delete.
-#
+PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials")
 # fleet/* — the framework SEEDS only fleet/examples, fleet/roles, and
 # fleet/roster.schema.json (synced normally). The user's own fleet files MUST
 # survive `mosaic update` (which runs this sync automatically): the active
 # roster (`fleet/roster.yaml` + any other `fleet/*.yaml`), per-agent env
 # (`fleet/agents/`), and heartbeat run dir (`fleet/run/`). Without these, an
 # update wipes the operator's fleet. Glob entries are honored by both the rsync
 # path (`--exclude`) and the glob-aware cp fallback below.
 PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials" "fleet/*.yaml" "fleet/agents" "fleet/run")
 # Framework-owned contract files: re-copied from defaults/ on every upgrade (the
 # user must not edit them; a divergent copy is backed up once before overwrite).
@@ -187,23 +179,15 @@ sync_framework() {
    return
  fi
-  # Fallback: cp-based sync. Glob-aware so entries like "fleet/*.yaml" preserve
+  # Fallback: cp-based sync
  # every matching user file (parity with the rsync --exclude path above).
  local preserve_tmp=""
  if [[ "$INSTALL_MODE" == "keep" ]]; then
    preserve_tmp="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-preserve-XXXXXX")"
    local match rel
    for path in "${PRESERVE_PATHS[@]}"; do
-      # Unquoted $path lets the glob expand against TARGET_DIR; nullglob makes a
+      if [[ -e "$TARGET_DIR/$path" ]]; then
-      # non-matching pattern vanish instead of staying literal.
+        mkdir -p "$preserve_tmp/$(dirname "$path")"
-      shopt -s nullglob
+        cp -R "$TARGET_DIR/$path" "$preserve_tmp/$path"
-      for match in "$TARGET_DIR/"$path; do
+      fi
        [[ -e "$match" ]] || continue
        rel="${match#"$TARGET_DIR/"}"
        mkdir -p "$preserve_tmp/$(dirname "$rel")"
        cp -R "$match" "$preserve_tmp/$rel"
      done
      shopt -u nullglob
    done
  fi
@@ -212,19 +196,12 @@ sync_framework() {
  rm -rf "$TARGET_DIR/.git"
  if [[ -n "$preserve_tmp" ]]; then
    # Restore by re-globbing the SAME patterns against preserve_tmp, so each
    # preserved item is restored at its own relative path (e.g. only
    # fleet/roster.yaml is replaced — the freshly-synced fleet/examples stays).
    for path in "${PRESERVE_PATHS[@]}"; do
-      shopt -s nullglob
+      if [[ -e "$preserve_tmp/$path" ]]; then
-      for match in "$preserve_tmp/"$path; do
+        rm -rf "$TARGET_DIR/$path"
-        [[ -e "$match" ]] || continue
+        mkdir -p "$TARGET_DIR/$(dirname "$path")"
-        rel="${match#"$preserve_tmp/"}"
+        cp -R "$preserve_tmp/$path" "$TARGET_DIR/$path"
-        rm -rf "$TARGET_DIR/$rel"
+      fi
        mkdir -p "$TARGET_DIR/$(dirname "$rel")"
        cp -R "$match" "$TARGET_DIR/$rel"
      done
      shopt -u nullglob
    done
    rm -rf "$preserve_tmp"
  fi
--- a/packages/mosaic/framework/systemd/user/mosaic-agent@.service
+++ b/packages/mosaic/framework/systemd/user/mosaic-agent@.service
@@ -8,15 +8,13 @@ PartOf=mosaic-tmux-holder.service
 [Service]
 Type=oneshot
 RemainAfterExit=yes
-# No default MOSAIC_TMUX_SOCKET: an absent roster socket means the literal
+Environment=MOSAIC_TMUX_SOCKET=mosaic-factory
 # default tmux socket (no -L). The per-agent .env sets it when the roster names
 # one; otherwise it stays unset and start-agent-session.sh uses the default socket.
 Environment=MOSAIC_AGENT_NAME=%i
 Environment=MOSAIC_AGENT_RUNTIME=pi
 Environment=MOSAIC_AGENT_WORKDIR=%h
 EnvironmentFile=-%h/.config/mosaic/fleet/agents/%i.env
 ExecStart=/bin/bash %h/.config/mosaic/tools/fleet/start-agent-session.sh %i
-ExecStop=-/bin/bash -lc 'if [ -n "${MOSAIC_TMUX_SOCKET:-}" ]; then tmux -L "$MOSAIC_TMUX_SOCKET" kill-session -t "=%i"; else tmux kill-session -t "=%i"; fi'
+ExecStop=-/bin/bash -lc 'tmux -L "${MOSAIC_TMUX_SOCKET:-mosaic-factory}" kill-session -t "=%i"'
 [Install]
 WantedBy=default.target
--- a/packages/mosaic/framework/tools/fleet/start-agent-session.sh
+++ b/packages/mosaic/framework/tools/fleet/start-agent-session.sh
@@ -2,12 +2,8 @@
 set -euo pipefail
 AGENT_NAME=${1:-${MOSAIC_AGENT_NAME:-}}
-# Absent socket ⇒ the LITERAL default tmux socket (no -L). The roster's
+MOSAIC_TMUX_SOCKET=${MOSAIC_TMUX_SOCKET:-mosaic-factory}
 # socket_name is honored when set; absent never silently becomes mosaic-factory
 # (spawn stays consistent with the onboarding cheat-sheet + fleet ps observe).
 MOSAIC_TMUX_SOCKET=${MOSAIC_TMUX_SOCKET:-}
 MOSAIC_AGENT_RUNTIME=${MOSAIC_AGENT_RUNTIME:-pi}
 MOSAIC_AGENT_MODEL=${MOSAIC_AGENT_MODEL:-}
 MOSAIC_AGENT_WORKDIR=${MOSAIC_AGENT_WORKDIR:-$HOME}
 MOSAIC_AGENT_COMMAND=${MOSAIC_AGENT_COMMAND:-}
 MOSAIC_HEARTBEAT_RUN_DIR=${MOSAIC_HEARTBEAT_RUN_DIR:-${MOSAIC_HOME:-$HOME/.config/mosaic}/fleet/run}
@@ -23,25 +19,13 @@ if ! command -v tmux >/dev/null 2>&1; then
  exit 69
 fi
-# tmux wrapper: pass -L only when a socket is configured. An absent/empty socket
+if tmux -L "$MOSAIC_TMUX_SOCKET" has-session -t "=${AGENT_NAME}:0.0" 2>/dev/null; then
-# means the default tmux socket (no -L), keeping spawn == observe == cheat-sheet.
+  echo "Mosaic agent session already running: $AGENT_NAME on socket $MOSAIC_TMUX_SOCKET"
 _tmux() {
  if [ -n "$MOSAIC_TMUX_SOCKET" ]; then
    tmux -L "$MOSAIC_TMUX_SOCKET" "$@"
  else
    tmux "$@"
  fi
 }
 if _tmux has-session -t "=${AGENT_NAME}:0.0" 2>/dev/null; then
  echo "Mosaic agent session already running: $AGENT_NAME on socket ${MOSAIC_TMUX_SOCKET:-(default)}"
  exit 0
 fi
 if [ -z "$MOSAIC_AGENT_COMMAND" ]; then
-  # Map the roster's per-agent model_hint to `--model` so workers launch on the
+  MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME"
  # configured model (e.g. pi on openai-codex/gpt-5.5:high). Omitted when unset.
  MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME${MOSAIC_AGENT_MODEL:+ --model $MOSAIC_AGENT_MODEL}"
 fi
 # ── Derive a runtime-bin PATH prefix ─────────────────────────────────────────
@@ -123,13 +107,13 @@ fi
 mkdir -p "$MOSAIC_AGENT_WORKDIR"
 # ── Launch the tmux session (no exec — we continue to wire the heartbeat) ────
-_tmux new-session -d -s "$AGENT_NAME" -c "$MOSAIC_AGENT_WORKDIR" \
+tmux -L "$MOSAIC_TMUX_SOCKET" new-session -d -s "$AGENT_NAME" -c "$MOSAIC_AGENT_WORKDIR" \
  bash -c "$PANE_SHELL_SNIPPET"
 # ── Resolve the pane PID (retry briefly to let the session initialise) ────────
 PANE_PID=""
 for _retry in 1 2 3 4 5; do
-  PANE_PID=$(_tmux list-panes \
+  PANE_PID=$(tmux -L "$MOSAIC_TMUX_SOCKET" list-panes \
    -t "=${AGENT_NAME}:0.0" -F '#{pane_pid}' 2>/dev/null || true)
  [ -n "$PANE_PID" ] && break
  sleep 0.2
--- a/packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
+++ b/packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
@@ -61,25 +61,7 @@ MOSAIC_HOME="$T5" MOSAIC_INSTALL_MODE=bogus MOSAIC_SYNC_ONLY=1 bash "$INSTALL" >
 chk "F5 failure: invalid mode rejected (nonzero exit)" "[ $rc -ne 0 ]"
 chk "F5 failure: SOUL + credentials intact" "grep -q orig '$T5/SOUL.md' && grep -q keepme '$T5/credentials/c.json'"
-# F6 — keep-mode re-seed (the `mosaic update` path) MUST NOT wipe user fleet data.
+rm -rf "$T1" "$T2" "$T3" "$T4" "$T5"
 # Regression for the roster-loss bug: fleet/ was not in PRESERVE_PATHS.
 T6=$(mktemp -d); mkdir -p "$T6/fleet/examples" "$T6/fleet/run" "$T6/fleet/agents"
 printf '# persona\n' > "$T6/SOUL.md"   # makes it a recognized existing install (→ keep mode)
 printf 'version: 1\nagents:\n  - name: coder0\n' > "$T6/fleet/roster.yaml"
 printf 'version: 1\nagents:\n  - name: custom\n' > "$T6/fleet/my-fleet.yaml"
 printf 'ts=x\n' > "$T6/fleet/run/coder0.hb"
 printf 'MOSAIC_AGENT_NAME=coder0\n' > "$T6/fleet/agents/coder0.env"
 printf '# stale preset\n' > "$T6/fleet/examples/general.yaml"
 echo 3 > "$T6/.framework-version"
 run "$T6" keep
 chk "F6 reseed: user roster.yaml SURVIVES keep-mode sync" "grep -q coder0 '$T6/fleet/roster.yaml'"
 chk "F6 reseed: other user fleet/*.yaml survives (glob)" "[ -f '$T6/fleet/my-fleet.yaml' ]"
 chk "F6 reseed: per-agent env (fleet/agents) survives" "[ -f '$T6/fleet/agents/coder0.env' ]"
 chk "F6 reseed: heartbeat run dir (fleet/run) survives" "[ -f '$T6/fleet/run/coder0.hb' ]"
 chk "F6 reseed: framework examples ARE refreshed (not preserved stale)" "grep -q orchestrator '$T6/fleet/examples/general.yaml'"
 chk "F6 reseed: framework roster.schema.json seeded" "[ -f '$T6/fleet/roster.schema.json' ]"
 rm -rf "$T1" "$T2" "$T3" "$T4" "$T5" "$T6"
 echo
 echo "RESULT: $pass passed, $fail failed"
 [ "$fail" -eq 0 ]
--- a/packages/mosaic/package.json
+++ b/packages/mosaic/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@mosaicstack/mosaic",
-  "version": "0.0.40",
+  "version": "0.0.39",
  "repository": {
    "type": "git",
    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
--- a/packages/mosaic/src/cli.ts
+++ b/packages/mosaic/src/cli.ts
@@ -27,7 +27,6 @@ import {
  formatAllPackagesTable,
  getInstallAllCommand,
  runFrameworkReseed,
  refreshActiveFleetUnits,
  readRosterAgentNames,
  buildRelaunchCommands,
  FRAMEWORK_RESEED_PACKAGE,
@@ -467,12 +466,6 @@ program
      const reseed = runFrameworkReseed();
      if (reseed.ok) {
        console.log('✔ Framework re-seeded.');
        // Propagate shipped systemd unit fixes to the ACTIVE units (re-seed only
        // touches ~/.config/mosaic/systemd/user; systemd runs ~/.config/systemd/user).
        const units = refreshActiveFleetUnits();
        if (units.refreshed.length > 0) {
          console.log(`✔ Refreshed ${units.refreshed.length} active systemd unit(s).`);
        }
        const agents = readRosterAgentNames();
        if (agents.length > 0) {
          if (opts.relaunch) {
--- a/packages/mosaic/src/commands/compose-contract.spec.ts
+++ b/packages/mosaic/src/commands/compose-contract.spec.ts
@@ -56,55 +56,6 @@ describe('composeContract — overlay composer', () => {
    rmSync(cwdDir, { recursive: true, force: true });
  });
  it('injects the fleet comms cheat-sheet for a spawned fleet agent (situational)', () => {
    // A spawned agent has MOSAIC_AGENT_NAME set + is a member of the roster.
    mkdirSync(join(fixture.home, 'fleet'), { recursive: true });
    writeFileSync(
      join(fixture.home, 'fleet', 'roster.yaml'),
      [
        'version: 1',
        'transport: tmux',
        'agents:',
        '  - name: orchestrator',
        '    runtime: claude',
        '    class: orchestrator',
        '  - name: enhancer',
        '    runtime: claude',
        '    class: enhancer',
        '  - name: coder0-0',
        '    runtime: claude',
        '    class: implementer',
        '    host: 10.1.10.37',
        '    ssh: jwoltje@10.1.10.37',
        '',
      ].join('\n'),
    );
    const prev = process.env['MOSAIC_AGENT_NAME'];
    try {
      process.env['MOSAIC_AGENT_NAME'] = 'enhancer';
      const out = composeContract('claude', fixture.home);
      expect(out).toContain('# Fleet Comms');
      expect(out).toMatch(/`\[[^\]]+:enhancer\]`/); // own [host:session] identity (host machine-dependent)
      // local peer → no -H; cross-host peer → -H ssh
      expect(out).toContain('-s orchestrator -m "…"');
      expect(out).toContain('-H jwoltje@10.1.10.37 -s coder0-0 -m "…"');
      expect(out).not.toContain('-H jwoltje@10.1.10.37 -s orchestrator'); // local stays local
    } finally {
      if (prev === undefined) delete process.env['MOSAIC_AGENT_NAME'];
      else process.env['MOSAIC_AGENT_NAME'] = prev;
    }
  });
  it('does NOT inject fleet comms when MOSAIC_AGENT_NAME is unset (non-fleet launch)', () => {
    const prev = process.env['MOSAIC_AGENT_NAME'];
    try {
      delete process.env['MOSAIC_AGENT_NAME'];
      expect(composeContract('claude', fixture.home)).not.toContain('# Fleet Comms');
    } finally {
      if (prev !== undefined) process.env['MOSAIC_AGENT_NAME'] = prev;
    }
  });
  it('includes the per-tier anchors and the selected harness runtime', () => {
    const out = composeContract('claude', fixture.home);
    expect(out).toContain('GATE-1: the non-negotiable law.'); // L0
--- a/packages/mosaic/src/commands/fleet.spec.ts
+++ b/packages/mosaic/src/commands/fleet.spec.ts
@@ -14,14 +14,11 @@ import {
  buildEnableLingerCommand,
  buildFleetServiceCommand,
  buildSystemdEnableCommand,
  buildSystemdDisableCommand,
  socketArgs,
  buildSystemdShowCommand,
  buildTmuxListPanesCommand,
  buildTmuxListSessionsCommand,
  classifySendResult,
  countOrchestrators,
  countEnhancers,
  detectDrift,
  enableFleetUnits,
  FLEET_PROFILES,
@@ -115,7 +112,7 @@ describe('fleet roster parsing', () => {
    }
  });
-  it('defaults a socket-less roster to the literal default tmux socket (empty, no -L)', async () => {
+  it('defaults local canary rosters to the isolated mosaic-factory socket', async () => {
    cleanup = await tempDir();
    const rosterPath = join(cleanup, 'roster.yaml');
    await writeFile(
@@ -132,55 +129,12 @@ describe('fleet roster parsing', () => {
    const roster = await loadFleetRoster(rosterPath);
-    expect(roster.tmux.socketName).toBe(''); // absent ⇒ default socket (no -L), not mosaic-factory
+    expect(roster.tmux.socketName).toBe('mosaic-factory');
    expect(roster.tmux.holderSession).toBe('_holder');
    expect(roster.agents).toHaveLength(1);
    expect(getRosterAgent(roster, 'canary-pi').runtime).toBe('pi');
  });
  it('socketArgs: named socket → -L <name>; empty → no -L (default socket)', () => {
    expect(socketArgs('mosaic-factory')).toEqual(['-L', 'mosaic-factory']);
    expect(socketArgs('')).toEqual([]);
  });
  it('honors an explicit socket_name (renders -L) — containment for shipped presets', async () => {
    cleanup = await tempDir();
    const rosterPath = join(cleanup, 'roster.yaml');
    await writeFile(
      rosterPath,
      [
        'version: 1',
        'transport: tmux',
        'tmux:',
        '  socket_name: mosaic-factory',
        'agents:',
        '  - name: canary-pi',
        '    runtime: pi',
      ].join('\n'),
    );
    const roster = await loadFleetRoster(rosterPath);
    expect(roster.tmux.socketName).toBe('mosaic-factory');
    expect(buildTmuxListSessionsCommand(roster.tmux.socketName)).toContain('-L');
  });
  it('maps a per-agent model_hint into MOSAIC_AGENT_MODEL', async () => {
    cleanup = await tempDir();
    const rosterPath = join(cleanup, 'roster.json');
    await writeFile(
      rosterPath,
      JSON.stringify({
        version: 1,
        transport: 'tmux',
        agents: [{ name: 'coder0', runtime: 'pi', model_hint: 'openai-codex/gpt-5.5:high' }],
      }),
    );
    const roster = await loadFleetRoster(rosterPath);
    const env = generateAgentEnv(roster, getRosterAgent(roster, 'coder0'));
    expect(env).toContain('MOSAIC_AGENT_MODEL=openai-codex/gpt-5.5:high');
    // socket-less roster ⇒ a bare empty socket (no quotes), so spawn uses no -L
    expect(env).toContain('MOSAIC_TMUX_SOCKET=\n');
  });
  it('generates deterministic per-agent EnvironmentFile content', async () => {
    cleanup = await tempDir();
    const rosterPath = join(cleanup, 'roster.json');
@@ -200,7 +154,6 @@ describe('fleet roster parsing', () => {
      [
        'MOSAIC_AGENT_NAME=coder0',
        'MOSAIC_AGENT_RUNTIME=codex',
        'MOSAIC_AGENT_MODEL=',
        'MOSAIC_AGENT_WORKDIR=/srv/mosaic',
        'MOSAIC_TMUX_SOCKET=mosaic-factory',
        '',
@@ -400,9 +353,8 @@ describe('fleet command construction', () => {
    try {
      await program.parseAsync(['node', 'mosaic', 'fleet', 'verify']);
      expect(calls).toEqual([
-        // socket-less roster ⇒ default tmux socket (no -L)
+        ['tmux', '-L', 'mosaic-factory', 'has-session', '-t', '=_holder:0.0'],
-        ['tmux', 'has-session', '-t', '=_holder:0.0'],
+        ['tmux', '-L', 'mosaic-factory', 'has-session', '-t', '=coder0:0.0'],
        ['tmux', 'has-session', '-t', '=coder0:0.0'],
      ]);
    } finally {
      await rm(home, { recursive: true, force: true });
@@ -683,7 +635,7 @@ describe('fleet command construction', () => {
    try {
      await program.parseAsync(['node', 'mosaic', 'agent', 'status', 'json-agent']);
      expect(calls).toEqual([
-        ['tmux', 'has-session', '-t', '=json-agent:0.0'], // socket-less ⇒ no -L
+        ['tmux', '-L', 'mosaic-factory', 'has-session', '-t', '=json-agent:0.0'],
      ]);
    } finally {
      await rm(home, { recursive: true, force: true });
@@ -723,6 +675,8 @@ describe('fleet command construction', () => {
      expect(calls).toEqual([
        [
          join(home, 'tools', 'tmux', 'agent-send.sh'),
          '-L',
          'mosaic-factory',
          '-S',
          getDefaultOperatorSourceLabel(),
          '-s',
@@ -771,6 +725,8 @@ describe('fleet command construction', () => {
      expect(calls).toEqual([
        [
          join(home, 'tools', 'tmux', 'agent-send.sh'),
          '-L',
          'mosaic-factory',
          '-S',
          'lead:manual',
          '-s',
@@ -853,11 +809,9 @@ describe('fleet ps — command construction', () => {
    ]);
  });
-  it('uses the default tmux socket (no -L) when socket is omitted from list-panes', () => {
+  it('uses DEFAULT_SOCKET_NAME when socket is omitted from list-panes', () => {
    const cmd = buildTmuxListPanesCommand('canary-pi');
-    expect(cmd).not.toContain('-L'); // omitted socket ⇒ default socket
+    expect(cmd[2]).toBe('mosaic-factory');
    expect(cmd[0]).toBe('tmux');
    expect(cmd[1]).toBe('list-panes');
  });
  it('derives heartbeat path under ~/.config/mosaic/fleet/run/', () => {
@@ -1029,129 +983,6 @@ describe('fleet ps — drift detection', () => {
  });
 });
 describe('fleet-polish bundle — boot-survival symmetry', () => {
  async function rosterHome(agents: string): Promise<string> {
    const home = await tempDir();
    await mkdir(join(home, 'fleet'), { recursive: true });
    await writeFile(join(home, 'fleet', 'roster.yaml'), agents);
    return home;
  }
  it('buildSystemdDisableCommand returns the systemctl --user disable array', () => {
    expect(buildSystemdDisableCommand('mosaic-agent@coder0.service')).toEqual([
      'systemctl',
      '--user',
      'disable',
      'mosaic-agent@coder0.service',
    ]);
  });
  it('fleet remove DISABLES the unit so a removed agent cannot resurrect on boot', async () => {
    const home = await rosterHome(
      [
        'version: 1',
        'transport: tmux',
        'agents:',
        '  - name: orchestrator',
        '    runtime: pi',
        '    class: orchestrator',
        '  - name: coder0',
        '    runtime: codex',
        '    class: worker',
      ].join('\n') + '\n',
    );
    const calls: string[][] = [];
    const runner: CommandRunner = async (command, args) => {
      calls.push([command, ...args]);
      return { stdout: '', stderr: '', exitCode: 0 };
    };
    const program = new Command();
    program.exitOverride();
    registerFleetCommand(program, { runner, mosaicHome: home });
    try {
      await program.parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder0']);
      expect(calls).toContainEqual([
        'systemctl',
        '--user',
        'disable',
        'mosaic-agent@coder0.service',
      ]);
      // stop must still happen too
      expect(calls).toContainEqual(['systemctl', '--user', 'stop', 'mosaic-agent@coder0.service']);
    } finally {
      await rm(home, { recursive: true, force: true });
    }
  });
  it('fleet add ENABLES the new agent unit for boot-survival', async () => {
    const home = await rosterHome(
      ['version: 1', 'transport: tmux', 'agents:', '  - name: coder0', '    runtime: codex'].join(
        '\n',
      ) + '\n',
    );
    const calls: string[][] = [];
    const runner: CommandRunner = async (command, args) => {
      calls.push([command, ...args]);
      return { stdout: '', stderr: '', exitCode: 0 };
    };
    const program = new Command();
    program.exitOverride();
    registerFleetCommand(program, { runner, mosaicHome: home });
    try {
      await program.parseAsync([
        'node',
        'mosaic',
        'fleet',
        'add',
        'coder1',
        '--runtime',
        'codex',
        '--class',
        'worker',
        '--no-start',
      ]);
      expect(calls).toContainEqual([
        'systemctl',
        '--user',
        'enable',
        'mosaic-agent@coder1.service',
      ]);
    } finally {
      await rm(home, { recursive: true, force: true });
    }
  });
  it('fleet init --write enforces the two-agent floor (1 orchestrator + >=1 enhancer)', async () => {
    // The general profile must yield exactly one orchestrator AND at least one
    // enhancer; the guarantee is enforced (not just warned). Happy path writes cleanly.
    const home = await tempDir();
    const program = new Command();
    program.exitOverride();
    registerFleetCommand(program, {
      runner: async () => ({ stdout: '', stderr: '', exitCode: 0 }),
      mosaicHome: home,
    });
    try {
      await program.parseAsync([
        'node',
        'mosaic',
        'fleet',
        'init',
        '--profile',
        'general',
        '--write',
      ]);
      const written = await readFile(join(home, 'fleet', 'roster.yaml'), 'utf8');
      const orchestrators = (written.match(/class:\s*orchestrator/g) ?? []).length;
      const enhancers = (written.match(/class:\s*enhancer/g) ?? []).length;
      expect(orchestrators).toBe(1);
      expect(enhancers).toBeGreaterThanOrEqual(1);
    } finally {
      await rm(home, { recursive: true, force: true });
    }
  });
 });
 describe('fleet install — auto-enable units for boot-survival', () => {
  it('buildSystemdEnableCommand and buildEnableLingerCommand return correct command arrays', () => {
    expect(buildSystemdEnableCommand('mosaic-tmux-holder.service')).toEqual([
@@ -1375,9 +1206,8 @@ describe('fleet ps — command sequences issued', () => {
      await program.parseAsync(['node', 'mosaic', 'fleet', 'ps']);
      expect(calls).toEqual([
        buildSystemdShowCommand('coder0'),
-        // socket-less roster ⇒ default socket (no -L)
+        buildTmuxListPanesCommand('coder0', 'mosaic-factory'),
-        buildTmuxListPanesCommand('coder0'),
+        buildTmuxListSessionsCommand('mosaic-factory'),
        buildTmuxListSessionsCommand(),
      ]);
    } finally {
      console.log = origLog;
@@ -1398,10 +1228,9 @@ describe('buildTmuxListSessionsCommand', () => {
    ]);
  });
-  it('uses the default tmux socket (no -L) when socket is omitted', () => {
+  it('uses DEFAULT_SOCKET_NAME when socket is omitted', () => {
    const cmd = buildTmuxListSessionsCommand();
-    expect(cmd).not.toContain('-L');
+    expect(cmd[2]).toBe('mosaic-factory');
    expect(cmd).toEqual(['tmux', 'list-sessions', '-F', '#{session_name}']);
  });
 });
@@ -1679,10 +1508,9 @@ describe('agent watch', () => {
    ]);
  });
-  it('buildAgentWatchCommand (deprecated) uses the default tmux socket (no -L) when socket is omitted', () => {
+  it('buildAgentWatchCommand (deprecated) still uses DEFAULT_SOCKET_NAME when socket is omitted', () => {
    const cmd = buildAgentWatchCommand('canary-pi');
-    expect(cmd).not.toContain('-L'); // omitted socket ⇒ default socket
+    expect(cmd[2]).toBe('mosaic-factory');
    expect(cmd[0]).toBe('tmux');
    expect(cmd).toContain('-r');
  });
@@ -1876,10 +1704,9 @@ describe('agent send --verify', () => {
      // 3 calls: BEFORE-capture, send, AFTER-capture (pane changed on first poll → accepted immediately)
      expect(calls).toHaveLength(3);
-      // socket-less roster ⇒ default socket (no -L)
+      expect(calls[0]).toEqual(buildAgentVerifyAcceptedCommand('coder0', 'mosaic-factory', 5));
      expect(calls[0]).toEqual(buildAgentVerifyAcceptedCommand('coder0', '', 5));
      expect(calls[1]![0]).toContain('agent-send.sh');
-      expect(calls[2]).toEqual(buildAgentVerifyAcceptedCommand('coder0', '', 5));
+      expect(calls[2]).toEqual(buildAgentVerifyAcceptedCommand('coder0', 'mosaic-factory', 5));
    } finally {
      await rm(home, { recursive: true, force: true });
    }
@@ -2361,63 +2188,47 @@ describe('fleet preset rosters', () => {
    },
  );
-  it('general preset: orchestrator + enhancer + one generalist worker', async () => {
+  it('general preset: orchestrator + one generalist worker', async () => {
    const roster = await loadFleetRoster(join(examplesDir, 'general.yaml'));
-    expect(roster.agents.map((a) => a.name)).toEqual(['orchestrator', 'enhancer', 'generalist']);
+    expect(roster.agents.map((a) => a.name)).toEqual(['orchestrator', 'generalist']);
    expect(roster.agents.find((a) => a.name === 'orchestrator')?.runtime).toBe('claude');
    expect(roster.agents.find((a) => a.name === 'enhancer')?.className).toBe('enhancer');
    expect(roster.agents.find((a) => a.name === 'generalist')?.runtime).toBe('pi');
  });
-  it('coding preset: orchestrator + enhancer + coder0 + coder1 + reviewer', async () => {
+  it('coding preset: orchestrator + coder0 + coder1 + reviewer', async () => {
    const roster = await loadFleetRoster(join(examplesDir, 'coding.yaml'));
    expect(roster.agents.map((a) => a.name)).toEqual([
      'orchestrator',
      'enhancer',
      'coder0',
      'coder1',
      'reviewer',
    ]);
  });
-  it('research preset: orchestrator + enhancer + researcher0 + researcher1 + analyst', async () => {
+  it('research preset: orchestrator + researcher0 + researcher1 + analyst', async () => {
    const roster = await loadFleetRoster(join(examplesDir, 'research.yaml'));
    expect(roster.agents.map((a) => a.name)).toEqual([
      'orchestrator',
      'enhancer',
      'researcher0',
      'researcher1',
      'analyst',
    ]);
  });
-  it('hybrid preset: orchestrator + enhancer + coder0 + researcher0 + reviewer', async () => {
+  it('hybrid preset: orchestrator + coder0 + researcher0 + reviewer', async () => {
    const roster = await loadFleetRoster(join(examplesDir, 'hybrid.yaml'));
    expect(roster.agents.map((a) => a.name)).toEqual([
      'orchestrator',
      'enhancer',
      'coder0',
      'researcher0',
      'reviewer',
    ]);
  });
  it('every non-minimal preset carries an enhancer (two-agent floor)', async () => {
    for (const preset of ['general', 'coding', 'research', 'hybrid'] as FleetProfile[]) {
      const roster = await loadFleetRoster(join(examplesDir, `${preset}.yaml`));
      expect(countOrchestrators(roster)).toBe(1);
      expect(countEnhancers(roster)).toBeGreaterThanOrEqual(1);
      expect(roster.agents.find((a) => a.className === 'enhancer')?.runtime).toBe('claude');
    }
  });
  it('worker agents in new presets use pi runtime with model_hint openai-codex/gpt-5.5:high', async () => {
    for (const preset of ['general', 'coding', 'research', 'hybrid'] as FleetProfile[]) {
      const roster = await loadFleetRoster(join(examplesDir, `${preset}.yaml`));
-      // Core agents (orchestrator + enhancer) run claude; only ephemeral workers are pi.
+      const workers = roster.agents.filter((a) => a.name !== 'orchestrator');
      const workers = roster.agents.filter(
        (a) => a.className !== 'orchestrator' && a.className !== 'enhancer',
      );
      for (const worker of workers) {
        expect(worker.runtime).toBe('pi');
        expect(worker.modelHint).toBe('openai-codex/gpt-5.5:high');
@@ -2559,43 +2370,6 @@ describe('fleet add/remove — pure helpers', () => {
    expect(updated.agents.map((a) => a.name)).toEqual(['orchestrator2', 'coder0']);
  });
  it('countEnhancers counts enhancer-class agents (two-agent floor)', () => {
    const roster: FleetRoster = {
      ...baseRoster,
      agents: [
        { name: 'orchestrator', runtime: 'claude', className: 'orchestrator' },
        { name: 'enhancer', runtime: 'claude', className: 'enhancer' },
        { name: 'coder0', runtime: 'codex', className: 'worker' },
      ],
    };
    expect(countEnhancers(roster)).toBe(1);
    expect(countEnhancers(baseRoster)).toBe(0);
  });
  it('removeAgentFromRoster throws when removing the sole enhancer (two-agent floor)', () => {
    const roster: FleetRoster = {
      ...baseRoster,
      agents: [
        { name: 'orchestrator', runtime: 'claude', className: 'orchestrator' },
        { name: 'enhancer', runtime: 'claude', className: 'enhancer' },
      ],
    };
    expect(() => removeAgentFromRoster(roster, 'enhancer')).toThrow('sole enhancer');
  });
  it('removeAgentFromRoster allows removing an enhancer when another remains', () => {
    const roster: FleetRoster = {
      ...baseRoster,
      agents: [
        { name: 'orchestrator', runtime: 'claude', className: 'orchestrator' },
        { name: 'enhancer', runtime: 'claude', className: 'enhancer' },
        { name: 'enhancer2', runtime: 'claude', className: 'enhancer' },
      ],
    };
    const updated = removeAgentFromRoster(roster, 'enhancer');
    expect(updated.agents.map((a) => a.name)).toEqual(['orchestrator', 'enhancer2']);
  });
  it('serializeRosterToYaml produces YAML that round-trips through loadFleetRoster', async () => {
    const yaml = serializeRosterToYaml(baseRoster);
    expect(typeof yaml).toBe('string');
--- a/packages/mosaic/src/commands/fleet.ts
+++ b/packages/mosaic/src/commands/fleet.ts
@@ -117,26 +117,10 @@ export interface FleetPaths {
 type FleetServiceAction = 'start' | 'stop' | 'restart' | 'status';
-/**
+const DEFAULT_SOCKET_NAME = 'mosaic-factory';
 * The named tmux socket the canonical fleet uses. Kept as a public constant for
 * rosters/callers that explicitly want isolation; it is NO LONGER the silent
 * fallback for a socket-less roster (that now resolves to the default socket).
 */
 export const DEFAULT_SOCKET_NAME = 'mosaic-factory';
 const DEFAULT_HOLDER_SESSION = '_holder';
 const DEFAULT_WORKING_DIRECTORY = '~/src';
 /**
 * tmux `-L` args for a socket name. An empty/absent socket ⇒ the LITERAL default
 * tmux socket (no `-L`), so spawn, observe (`fleet ps`/watch), and the onboarding
 * cheat-sheet all agree. A named socket ⇒ `-L <name>`. `DEFAULT_SOCKET_NAME`
 * remains a constant for callers that explicitly want mosaic-factory; it is no
 * longer the silent fallback for a socket-less roster.
 */
 export function socketArgs(socketName: string): string[] {
  return socketName ? ['-L', socketName] : [];
 }
 /**
 * Default poll interval (ms) between capture-pane checks in `send --verify`.
 * Kept short enough to react quickly while not hammering tmux on busy hosts.
@@ -201,10 +185,6 @@ export function generateAgentEnv(roster: FleetRoster, agent: FleetAgent): string
  return [
    `MOSAIC_AGENT_NAME=${shellEnvValue(agent.name)}`,
    `MOSAIC_AGENT_RUNTIME=${shellEnvValue(agent.runtime)}`,
    // Per-agent model hint → start-agent-session.sh appends `--model <hint>` to
    // the `mosaic yolo` launch so workers run on the roster's model (e.g. pi on
    // openai-codex/gpt-5.5:high). Empty when the agent declares no model_hint.
    `MOSAIC_AGENT_MODEL=${shellEnvValue(agent.modelHint ?? '')}`,
    `MOSAIC_AGENT_WORKDIR=${shellEnvValue(expandHome(workingDirectory))}`,
    `MOSAIC_TMUX_SOCKET=${shellEnvValue(roster.tmux.socketName)}`,
    '',
@@ -247,15 +227,6 @@ export function buildSystemdEnableCommand(unit: string): string[] {
  return ['systemctl', '--user', 'enable', unit];
 }
 /**
 * Returns the systemctl --user disable command for a given unit.
 * Used by `fleet remove` so a removed agent's enabled unit cannot resurrect on
 * boot pointing at deleted config (boot-survival symmetry with enable-on-add).
 */
 export function buildSystemdDisableCommand(unit: string): string[] {
  return ['systemctl', '--user', 'disable', unit];
 }
 /**
 * Returns the loginctl enable-linger command for a given user.
 * Linger allows user systemd services to survive logout.
@@ -339,12 +310,13 @@ export function buildAgentSendCommand(
  paths: FleetPaths,
  agentName: string,
  message: string,
-  socketName = '',
+  socketName = DEFAULT_SOCKET_NAME,
  sourceLabel = getDefaultOperatorSourceLabel(),
 ): string[] {
  return [
    join(paths.tmuxToolsDir, 'agent-send.sh'),
-    ...socketArgs(socketName),
+    '-L',
    socketName,
    '-S',
    sourceLabel,
    '-s',
@@ -363,11 +335,12 @@ export function buildAgentResetCommand(
  paths: FleetPaths,
  agentName: string,
  resetCommand: string,
-  socketName = '',
+  socketName = DEFAULT_SOCKET_NAME,
 ): string[] {
  return [
    join(paths.tmuxToolsDir, 'send-message.sh'),
-    ...socketArgs(socketName),
+    '-L',
    socketName,
    '-t',
    `=${agentName}`,
    '-m',
@@ -375,10 +348,15 @@ export function buildAgentResetCommand(
  ];
 }
-export function buildAgentTailCommand(agentName: string, lines: number, socketName = ''): string[] {
+export function buildAgentTailCommand(
  agentName: string,
  lines: number,
  socketName = DEFAULT_SOCKET_NAME,
 ): string[] {
  return [
    'tmux',
-    ...socketArgs(socketName),
+    '-L',
    socketName,
    'capture-pane',
    '-t',
    `=${agentName}:0.0`,
@@ -462,10 +440,14 @@ export function buildSystemdShowCommand(agentName: string): string[] {
 * Returns the tmux list-panes command for an agent pane.
 * Format: `#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity}`
 */
-export function buildTmuxListPanesCommand(agentName: string, socketName = ''): string[] {
+export function buildTmuxListPanesCommand(
  agentName: string,
  socketName = DEFAULT_SOCKET_NAME,
 ): string[] {
  return [
    'tmux',
-    ...socketArgs(socketName),
+    '-L',
    socketName,
    'list-panes',
    '-t',
    `=${agentName}:0.0`,
@@ -479,8 +461,8 @@ export function buildTmuxListPanesCommand(agentName: string, socketName = ''): s
 * Format: `tmux -L <socket> list-sessions -F '#{session_name}'`
 * Used to discover ad-hoc sessions that are not in the roster.
 */
-export function buildTmuxListSessionsCommand(socketName = ''): string[] {
+export function buildTmuxListSessionsCommand(socketName = DEFAULT_SOCKET_NAME): string[] {
-  return ['tmux', ...socketArgs(socketName), 'list-sessions', '-F', '#{session_name}'];
+  return ['tmux', '-L', socketName, 'list-sessions', '-F', '#{session_name}'];
 }
 /**
@@ -662,11 +644,12 @@ export function getDefaultTenantAndHost(): { tenant_id: string; host: string } {
 export function buildAgentWatchCreateViewerCommand(
  agentName: string,
  viewerSessionName: string,
-  socketName = '',
+  socketName = DEFAULT_SOCKET_NAME,
 ): string[] {
  return [
    'tmux',
-    ...socketArgs(socketName),
+    '-L',
    socketName,
    'new-session',
    '-d',
    '-t',
@@ -680,8 +663,11 @@ export function buildAgentWatchCreateViewerCommand(
 * Builds the interactive attach command for a viewer session (read-only).
 * Must be run via interactiveRunner (stdio: 'inherit').
 */
-export function buildAgentWatchAttachCommand(viewerSessionName: string, socketName = ''): string[] {
+export function buildAgentWatchAttachCommand(
-  return ['tmux', ...socketArgs(socketName), 'attach', '-r', '-t', viewerSessionName];
+  viewerSessionName: string,
  socketName = DEFAULT_SOCKET_NAME,
 ): string[] {
  return ['tmux', '-L', socketName, 'attach', '-r', '-t', viewerSessionName];
 }
 /**
@@ -690,9 +676,9 @@ export function buildAgentWatchAttachCommand(viewerSessionName: string, socketNa
 */
 export function buildAgentWatchKillViewerCommand(
  viewerSessionName: string,
-  socketName = '',
+  socketName = DEFAULT_SOCKET_NAME,
 ): string[] {
-  return ['tmux', ...socketArgs(socketName), 'kill-session', '-t', viewerSessionName];
+  return ['tmux', '-L', socketName, 'kill-session', '-t', viewerSessionName];
 }
 /**
@@ -710,8 +696,11 @@ export function buildViewerSessionName(agentName: string): string {
 *
 * Kept for backward compatibility only.
 */
-export function buildAgentWatchCommand(agentName: string, socketName = ''): string[] {
+export function buildAgentWatchCommand(
-  return ['tmux', ...socketArgs(socketName), 'attach', '-r', '-t', `=${agentName}`];
+  agentName: string,
  socketName = DEFAULT_SOCKET_NAME,
 ): string[] {
  return ['tmux', '-L', socketName, 'attach', '-r', '-t', `=${agentName}`];
 }
 /**
@@ -721,12 +710,13 @@ export function buildAgentWatchCommand(agentName: string, socketName = ''): stri
 */
 export function buildAgentVerifyAcceptedCommand(
  agentName: string,
-  socketName = '',
+  socketName = DEFAULT_SOCKET_NAME,
  lines = 5,
 ): string[] {
  return [
    'tmux',
-    ...socketArgs(socketName),
+    '-L',
    socketName,
    'capture-pane',
    '-t',
    `=${agentName}:0.0`,
@@ -882,33 +872,20 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
      await mkdir(dirname(destination), { recursive: true });
      await writeFile(destination, content);
-      // Guarantee the two-agent floor: exactly one orchestrator AND at least
+      // Validate: exactly one orchestrator required (R5) — friendly summary on success.
      // one enhancer for every profile except the sanctioned no-orchestrator
      // `minimal` preset. A mismatch means a corrupted/edited preset — fail hard
      // rather than write a malformed fleet.
      const written = await loadFleetRoster(destination);
      const orchCount = countOrchestrators(written);
-      const enhancerCount = countEnhancers(written);
+      if (orchCount !== 1) {
-      if (profile === 'minimal') {
+        process.stderr.write(
          `Warning: fleet roster at ${destination} has ${orchCount} orchestrator agent(s) (expected exactly 1).\n`,
        );
        console.log(
-          `Initialized ${profile} fleet: ${written.agents.length} agent(s) (no orchestrator). Next: mosaic fleet install`,
+          `Initialized ${profile} fleet: ${written.agents.length} agent(s). Next: mosaic fleet install`,
        );
      } else if (orchCount !== 1) {
        throw new Error(
          `Fleet init failed: the "${profile}" roster has ${orchCount} orchestrator agent(s), ` +
            `expected exactly 1 (R5). The preset may be corrupted — re-install the framework.`,
        );
      } else if (enhancerCount < 1) {
        throw new Error(
          `Fleet init failed: the "${profile}" roster has no enhancer agent. Every fleet keeps an ` +
            `orchestrator + enhancer minimum (two-agent floor). The preset may be corrupted — ` +
            `re-install the framework.`,
        );
      } else {
-        const workerCount = written.agents.length - 1 - enhancerCount;
+        const workerCount = written.agents.length - 1;
        console.log(
-          `Initialized ${profile} fleet: 1 orchestrator + ${enhancerCount} enhancer(s) + ` +
+          `Initialized ${profile} fleet: 1 orchestrator + ${workerCount} agent(s). Next: mosaic fleet install`,
            `${workerCount} worker(s). Next: mosaic fleet install`,
        );
      }
    });
@@ -990,7 +967,8 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
      const socketName = roster.tmux.socketName;
      await runChecked(runner, [
        'tmux',
-        ...socketArgs(socketName),
+        '-L',
        socketName,
        'has-session',
        '-t',
        `=${roster.tmux.holderSession}:0.0`,
@@ -998,7 +976,8 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
      for (const agent of roster.agents) {
        await runChecked(runner, [
          'tmux',
-          ...socketArgs(socketName),
+          '-L',
          socketName,
          'has-session',
          '-t',
          `=${agent.name}:0.0`,
@@ -1239,24 +1218,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
        console.log(`Added ${name} (${opts.runtime}/${opts.class}) to the fleet.`);
        // Enable the unit for boot-survival (non-fatal) — symmetry with
        // disable-on-remove. Independent of --start so a queued agent still
        // survives a reboot once its unit exists.
        try {
          const enableResult = await runner(
            ...splitCommand(buildSystemdEnableCommand(`mosaic-agent@${name}.service`)),
          );
          if (enableResult.exitCode !== 0) {
            process.stderr.write(
              `Warning: could not enable mosaic-agent@${name}.service: ${enableResult.stderr || enableResult.stdout || 'non-zero exit'}\n`,
            );
          }
        } catch (err) {
          process.stderr.write(
            `Warning: enable command failed for ${name}: ${err instanceof Error ? err.message : String(err)}\n`,
          );
        }
        if (opts.start !== false) {
          await runChecked(runner, buildFleetServiceCommand('start', name));
          console.log(`Started mosaic-agent@${name}.service.`);
@@ -1293,26 +1254,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
        );
      }
      // Disable the unit (non-fatal) so an enabled instance cannot resurrect on
      // boot pointing at the now-deleted config — boot-survival symmetry with
      // enable-on-add. Skipped only when --keep-files keeps the config in place.
      if (!opts.keepFiles) {
        try {
          const disableResult = await runner(
            ...splitCommand(buildSystemdDisableCommand(`mosaic-agent@${name}.service`)),
          );
          if (disableResult.exitCode !== 0) {
            process.stderr.write(
              `Warning: could not disable mosaic-agent@${name}.service: ${disableResult.stderr || disableResult.stdout || 'non-zero exit'}\n`,
            );
          }
        } catch (err) {
          process.stderr.write(
            `Warning: disable command failed for ${name}: ${err instanceof Error ? err.message : String(err)}\n`,
          );
        }
      }
      // Write updated roster
      await writeFile(rosterPath, serializeRosterToYaml(updatedRoster));
@@ -1369,8 +1310,8 @@ export function registerFleetAgentCommands(
        getRosterAgent(roster, agent);
      }
      const command = agent
-        ? ['tmux', ...socketArgs(roster.tmux.socketName), 'has-session', '-t', `=${agent}:0.0`]
+        ? ['tmux', '-L', roster.tmux.socketName, 'has-session', '-t', `=${agent}:0.0`]
-        : ['tmux', ...socketArgs(roster.tmux.socketName), 'ls'];
+        : ['tmux', '-L', roster.tmux.socketName, 'ls'];
      const result = await runner(...splitCommand(command));
      if (opts.json) {
        console.log(
@@ -1688,12 +1629,9 @@ function normalizeRoster(raw: RawFleetRoster): FleetRoster {
    version: 1,
    transport: 'tmux',
    tmux: {
      // Absent socket_name ⇒ '' (the literal default tmux socket, no -L) — NOT
      // mosaic-factory. Shipped presets set socket_name explicitly, so they are
      // unaffected; only socket-less rosters get default-socket behavior.
      socketName: stringValue(
        raw.tmux?.socket_name ?? raw.tmux?.socketName,
-        '',
+        DEFAULT_SOCKET_NAME,
        'Fleet roster tmux socket_name',
      ),
      holderSession: stringValue(
@@ -1859,12 +1797,6 @@ function expandHome(path: string): string {
 }
 function shellEnvValue(value: string): string {
  // Empty ⇒ a bare `VAR=` (unambiguous empty in a systemd EnvironmentFile and
  // when shell-sourced). Quoting it as '' risks a literal two-char value (e.g.
  // a tmux socket named "''"), which would defeat the default-socket behavior.
  if (value === '') {
    return '';
  }
  if (/^[A-Za-z0-9_./:=@+-]+$/.test(value)) {
    return value;
  }
@@ -1962,15 +1894,6 @@ export function countOrchestrators(roster: FleetRoster): number {
  return roster.agents.filter((a) => a.className === 'orchestrator').length;
 }
 /**
 * Count enhancer agents in a parsed roster. The two-agent floor (north-star)
 * requires every non-minimal fleet to carry at least one enhancer alongside the
 * sole orchestrator.
 */
 export function countEnhancers(roster: FleetRoster): number {
  return roster.agents.filter((a) => a.className === 'enhancer').length;
 }
 /** Valid runtime identifiers for fleet agents. */
 export const VALID_FLEET_RUNTIMES: readonly string[] = [
  'pi',
@@ -2013,15 +1936,6 @@ export function removeAgentFromRoster(roster: FleetRoster, name: string): FleetR
      `Cannot remove agent "${name}": it is the sole orchestrator. Add another orchestrator first (R5).`,
    );
  }
  // Two-agent floor: never drop the last enhancer (the continuous-improvement
  // loop). Symmetric with the sole-orchestrator guard.
  const remainingEnhancerCount = remaining.filter((a) => a.className === 'enhancer').length;
  if (remainingEnhancerCount === 0 && agent.className === 'enhancer') {
    throw new Error(
      `Cannot remove agent "${name}": it is the sole enhancer. Every fleet keeps at least one ` +
        `enhancer (two-agent floor). Add another enhancer first.`,
    );
  }
  return {
    ...roster,
    agents: remaining,
--- a/packages/mosaic/src/commands/launch.ts
+++ b/packages/mosaic/src/commands/launch.ts
@@ -19,7 +19,6 @@ import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import type { Command } from 'commander';
 import { readFleetCommsBlock } from '../fleet/comms-onboarding.js';
 const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
@@ -384,12 +383,6 @@ For required push/merge/issue-close/release actions, execute without routine con
  // Runtime-specific contract
  parts.push('\n\n# Runtime-Specific Contract\n\n' + readFileSync(runtimeFile, 'utf-8'));
  // Fleet onboarding: when this is a spawned fleet agent (MOSAIC_AGENT_NAME set
  // and present in the roster), inject a comms cheat-sheet + peer roster so it
  // knows how to reach the orchestrator and its peers from its first turn.
  const fleetComms = readFleetCommsBlock(mosaicHome, process.env['MOSAIC_AGENT_NAME']);
  if (fleetComms) parts.push('\n\n' + fleetComms);
  return parts.join('\n');
 }
--- a/packages/mosaic/src/config/file-adapter.test.ts
+++ b/packages/mosaic/src/config/file-adapter.test.ts
@@ -153,30 +153,6 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => {
    expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md'), 'utf-8')).toBe('# AGENTS default\n');
  });
  it('preserves user fleet data (roster.yaml, agents/, run/) through a keep-mode sync', async () => {
    // Regression for the roster-loss bug (#631): user-authored fleet files must
    // survive the framework re-seed that `mosaic update` runs.
    mkdirSync(join(fixture.mosaicHome, 'fleet', 'run'), { recursive: true });
    mkdirSync(join(fixture.mosaicHome, 'fleet', 'agents'), { recursive: true });
    writeFileSync(join(fixture.mosaicHome, 'fleet', 'roster.yaml'), 'version: 1\nMINE\n');
    writeFileSync(join(fixture.mosaicHome, 'fleet', 'run', 'a.hb'), 'ts=x\n');
    writeFileSync(join(fixture.mosaicHome, 'fleet', 'agents', 'a.env'), 'X=1\n');
    // The framework ships fleet/examples — it should still seed/refresh.
    mkdirSync(join(fixture.sourceDir, 'fleet', 'examples'), { recursive: true });
    writeFileSync(join(fixture.sourceDir, 'fleet', 'examples', 'general.yaml'), '# preset\n');
    const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
    await adapter.syncFramework('keep');
    expect(readFileSync(join(fixture.mosaicHome, 'fleet', 'roster.yaml'), 'utf-8')).toBe(
      'version: 1\nMINE\n',
    );
    expect(existsSync(join(fixture.mosaicHome, 'fleet', 'run', 'a.hb'))).toBe(true);
    expect(existsSync(join(fixture.mosaicHome, 'fleet', 'agents', 'a.env'))).toBe(true);
    // framework-owned fleet/examples is seeded
    expect(existsSync(join(fixture.mosaicHome, 'fleet', 'examples', 'general.yaml'))).toBe(true);
  });
  it('is a no-op for seeding when defaults/ dir does not exist', async () => {
    rmSync(fixture.defaultsDir, { recursive: true });
--- a/packages/mosaic/src/config/file-adapter.ts
+++ b/packages/mosaic/src/config/file-adapter.ts
@@ -173,13 +173,6 @@ export class FileConfigAdapter implements ConfigService {
            'memory',
            'sources',
            'credentials',
            // User-authored fleet data MUST survive `mosaic update`'s re-seed.
            // The framework seeds only fleet/examples + fleet/roles +
            // fleet/roster.schema.json; the operator's roster, per-agent env, and
            // heartbeat run dir stay user-owned. (Mirror of install.sh PRESERVE_PATHS.)
            'fleet/*.yaml',
            'fleet/agents',
            'fleet/run',
          ]
        : [];
--- a/packages/mosaic/src/fleet/comms-onboarding.spec.ts
+++ b/packages/mosaic/src/fleet/comms-onboarding.spec.ts
@@ -1,187 +0,0 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
  parseRosterAgents,
  buildFleetCommsBlock,
  renderPeerReach,
  readFleetCommsBlock,
  type CommsPeer,
 } from './comms-onboarding.js';
 const ROSTER = [
  'version: 1',
  'transport: tmux',
  'agents:',
  '  - name: orchestrator',
  '    runtime: claude',
  '    class: orchestrator',
  '  - name: enhancer',
  '    runtime: claude',
  '    class: enhancer',
  '  - name: coder0',
  '    runtime: pi',
  '    class: implementer',
  '  # a manually-listed cross-host peer (pre-federation stopgap)',
  '  - name: coder0-0',
  '    runtime: claude',
  '    class: implementer',
  '    host: 10.1.10.37',
  '    ssh: jwoltje@10.1.10.37',
  '',
 ].join('\n');
 describe('parseRosterAgents', () => {
  it('parses name + class + optional host/ssh', () => {
    const peers = parseRosterAgents(ROSTER);
    expect(peers.map((p) => p.name)).toEqual(['orchestrator', 'enhancer', 'coder0', 'coder0-0']);
    expect(peers.find((p) => p.name === 'coder0')).toMatchObject({ className: 'implementer' });
    expect(peers.find((p) => p.name === 'coder0-0')).toMatchObject({
      className: 'implementer',
      host: '10.1.10.37',
      ssh: 'jwoltje@10.1.10.37',
    });
    // local agents have no host/ssh
    expect(peers.find((p) => p.name === 'orchestrator')!.host).toBeUndefined();
  });
  it('parses an optional per-agent socket', () => {
    const peers = parseRosterAgents(
      ['agents:', '  - name: a', '    class: worker', '    socket: mosaic-factory'].join('\n'),
    );
    expect(peers[0]).toMatchObject({ name: 'a', socket: 'mosaic-factory' });
  });
  it('stops at the next top-level key', () => {
    const peers = parseRosterAgents(
      ['agents:', '  - name: a', '    class: worker', 'defaults:', '  working_directory: ~'].join(
        '\n',
      ),
    );
    expect(peers.map((p) => p.name)).toEqual(['a']);
  });
 });
 describe('renderPeerReach — same-host vs cross-host', () => {
  const send = '/home/u/.config/mosaic/tools/tmux/agent-send.sh';
  it('renders the short form for a same-host peer', () => {
    const peer: CommsPeer = { name: 'enhancer', className: 'enhancer' };
    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(`${send} -s enhancer -m "…"`);
  });
  it('renders the -H form for a cross-host peer using ssh', () => {
    const peer: CommsPeer = {
      name: 'coder0-0',
      className: 'implementer',
      host: '10.1.10.37',
      ssh: 'jwoltje@10.1.10.37',
    };
    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
      `${send} -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`,
    );
  });
  it('falls back to host when a cross-host peer has no ssh', () => {
    const peer: CommsPeer = { name: 'x', className: 'worker', host: '10.0.0.9' };
    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(`${send} -H 10.0.0.9 -s x -m "…"`);
  });
  it('treats a peer whose host equals the fleet host as same-host', () => {
    const peer: CommsPeer = { name: 'y', className: 'worker', host: 'w-jarvis' };
    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(`${send} -s y -m "…"`);
  });
  it('emits NO -L for an unset/default socket', () => {
    const peer: CommsPeer = { name: 'lead', className: 'orchestrator' };
    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(`${send} -s lead -m "…"`);
  });
  it('emits -L <socket> for a named socket', () => {
    const peer: CommsPeer = { name: 'coder0', className: 'implementer', socket: 'mosaic-factory' };
    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
      `${send} -L mosaic-factory -s coder0 -m "…"`,
    );
  });
  it('combines -L (named socket) and -H (cross-host) in order', () => {
    const peer: CommsPeer = {
      name: 'coder0-0',
      className: 'implementer',
      host: '10.1.10.37',
      ssh: 'jwoltje@10.1.10.37',
      socket: 'mosaic-factory',
    };
    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
      `${send} -L mosaic-factory -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`,
    );
  });
 });
 describe('buildFleetCommsBlock', () => {
  const send = '/h/.config/mosaic/tools/tmux/agent-send.sh';
  const agents = parseRosterAgents(ROSTER);
  it('excludes self, lists peers, flags the orchestrator, and emits both address forms', () => {
    const block = buildFleetCommsBlock({
      selfName: 'enhancer',
      agents,
      fleetHost: 'w-jarvis',
      agentSendPath: send,
    });
    expect(block).toContain('# Fleet Comms');
    expect(block).toContain('You are **enhancer**');
    // criterion 1: agent's own [host:session] identity
    expect(block).toContain('`[w-jarvis:enhancer]`');
    // self excluded
    expect(block).not.toMatch(/\|\s*enhancer\s*\|/);
    // peers present
    expect(block).toContain('| orchestrator |');
    expect(block).toContain('point of contact');
    // same-host peer short form
    expect(block).toContain(`${send} -s coder0 -m "…"`);
    // cross-host peer -H form + host annotation
    expect(block).toContain(`${send} -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`);
    expect(block).toContain('host `10.1.10.37`');
    // conventions
    expect(block).toContain('FLIP the preamble');
    expect(block).toContain('ACCEPTED');
  });
  it('returns empty when the agent has no peers', () => {
    expect(
      buildFleetCommsBlock({
        selfName: 'solo',
        agents: [{ name: 'solo', className: 'orchestrator' }],
        fleetHost: 'h',
        agentSendPath: send,
      }),
    ).toBe('');
  });
 });
 describe('readFleetCommsBlock — situational (the context a spawned agent gets)', () => {
  let home: string;
  beforeEach(() => {
    home = mkdtempSync(join(tmpdir(), 'mosaic-comms-'));
    mkdirSync(join(home, 'fleet'), { recursive: true });
    writeFileSync(join(home, 'fleet', 'roster.yaml'), ROSTER);
  });
  afterEach(() => rmSync(home, { recursive: true, force: true }));
  it('builds the cheat-sheet with correct peer addresses for a fleet member', () => {
    const block = readFleetCommsBlock(home, 'orchestrator', 'w-jarvis');
    expect(block).toContain('# Fleet Comms');
    expect(block).toContain('| enhancer |');
    expect(block).toContain(`${join(home, 'tools', 'tmux', 'agent-send.sh')} -s coder0 -m "…"`);
    expect(block).toContain('-H jwoltje@10.1.10.37 -s coder0-0');
    expect(block).not.toMatch(/\|\s*orchestrator\s*\|/); // self excluded
  });
  it('returns empty when MOSAIC_AGENT_NAME is unset, no roster, or agent not a member', () => {
    expect(readFleetCommsBlock(home, undefined, 'w-jarvis')).toBe('');
    expect(readFleetCommsBlock(home, 'stranger', 'w-jarvis')).toBe('');
    expect(readFleetCommsBlock(mkdtempSync(join(tmpdir(), 'noroster-')), 'orchestrator')).toBe('');
  });
 });
--- a/packages/mosaic/src/fleet/comms-onboarding.ts
+++ b/packages/mosaic/src/fleet/comms-onboarding.ts
@@ -1,183 +0,0 @@
 /**
 * Fleet onboarding-injection (#620).
 *
 * Fleet agents are born not knowing how to reach their peers — the root cause of
 * a spawned agent's failed first send. When an agent boots via `mosaic yolo
 * <runtime>` (→ composeContract → system prompt), we append a comms cheat-sheet
 * + peer roster so it can talk to the orchestrator and other agents immediately.
 *
 * Cross-host aware: a peer may carry `host`/`ssh` (a deliberate pre-federation
 * stopgap — manual cross-host listing; federation/W1 auto-discovers later), so a
 * w-jarvis agent is born knowing the exact `-H` command to reach a dragon-lin
 * peer. Same-host peers render the short form.
 *
 * Standalone (no fleet.ts import) to keep launch.ts's prompt path free of the
 * heavy fleet command module. The roster is parsed leniently — the cheat-sheet
 * is best-effort onboarding, never a hard dependency.
 */
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir, hostname } from 'node:os';
 import { join } from 'node:path';
 export interface CommsPeer {
  name: string;
  /** Roster `class` (orchestrator | enhancer | implementer | worker | …). */
  className: string;
  /** Host the peer runs on; absent ⇒ the fleet host (same host). */
  host?: string;
  /** SSH target (user@host) for a cross-host peer; renders the `-H` form. */
  ssh?: string;
  /** tmux socket the peer's session lives on; absent ⇒ default socket (no `-L`). */
  socket?: string;
 }
 /**
 * Lenient parse of a fleet `roster.yaml` for agent name/class/host/ssh. Avoids a
 * dependency on the full fleet roster parser; the format is `- name:` list items
 * with `class:`/`host:`/`ssh:` siblings under `agents:`.
 */
 export function parseRosterAgents(yamlText: string): CommsPeer[] {
  const peers: CommsPeer[] = [];
  let current: CommsPeer | null = null;
  let inAgents = false;
  const scalar = (line: string, key: string): string | null => {
    const m = line.match(new RegExp(`^\\s*${key}:\\s*["']?([^"'#]+?)["']?\\s*$`));
    return m ? (m[1] as string).trim() : null;
  };
  for (const rawLine of yamlText.split('\n')) {
    const line = rawLine.replace(/\s+$/, '');
    if (/^agents:\s*$/.test(line)) {
      inAgents = true;
      continue;
    }
    if (!inAgents) continue;
    // A new top-level key (no leading space) ends the agents block.
    if (/^\S/.test(line)) break;
    const nameMatch = line.match(/^\s*-\s*name:\s*["']?([A-Za-z0-9._-]+)["']?\s*$/);
    if (nameMatch) {
      if (current) peers.push(current);
      current = { name: nameMatch[1] as string, className: 'worker' };
      continue;
    }
    if (!current) continue;
    const cls = scalar(line, 'class');
    if (cls) current.className = cls;
    const host = scalar(line, 'host');
    if (host) current.host = host;
    const ssh = scalar(line, 'ssh');
    if (ssh) current.ssh = ssh;
    const socket = scalar(line, 'socket');
    if (socket) current.socket = socket;
  }
  if (current) peers.push(current);
  return peers;
 }
 export interface FleetCommsOptions {
  /** This agent's name (it is excluded from its own peer list). */
  selfName: string;
  /** All roster agents (including self; filtered out internally). */
  agents: CommsPeer[];
  /** Host the fleet runs on (short hostname) — the same-host baseline. */
  fleetHost: string;
  /** Absolute path to agent-send.sh in this install. */
  agentSendPath: string;
 }
 /** Is this peer on a different host than the fleet baseline? */
 function isRemote(peer: CommsPeer, fleetHost: string): boolean {
  return peer.host !== undefined && peer.host !== fleetHost;
 }
 /**
 * Render the exact agent-send command to reach a peer (session = agent name).
 * Data-driven per peer: a named `socket` → `-L <socket>`; an unset socket → the
 * default tmux socket (no `-L`). A cross-host peer adds `-H <ssh|host>`.
 */
 export function renderPeerReach(peer: CommsPeer, fleetHost: string, agentSendPath: string): string {
  const parts = [agentSendPath];
  if (peer.socket) parts.push('-L', peer.socket); // unset ⇒ default socket, no -L
  if (isRemote(peer, fleetHost)) parts.push('-H', peer.ssh ?? (peer.host as string));
  parts.push('-s', peer.name, '-m', '"…"');
  return parts.join(' ');
 }
 /**
 * Build the `# Fleet Comms` onboarding block (pure markdown). Returns '' when
 * the agent has no peers (a single-agent roster has no one to talk to).
 */
 export function buildFleetCommsBlock(opts: FleetCommsOptions): string {
  const peers = opts.agents.filter((a) => a.name !== opts.selfName);
  if (peers.length === 0) return '';
  const orchestrator = peers.find((p) => p.className === 'orchestrator');
  const rows = peers
    .map((p) => {
      const where = isRemote(p, opts.fleetHost)
        ? `${p.className} · host \`${p.host}\``
        : p.className;
      const role = p.className === 'orchestrator' ? `${where} ← point of contact` : where;
      return `| ${p.name} | ${role} | \`${renderPeerReach(p, opts.fleetHost, opts.agentSendPath)}\` |`;
    })
    .join('\n');
  const orchLine = orchestrator
    ? `Your point of contact is **${orchestrator.name}** (the orchestrator) — route questions, ` +
      `status, and decisions there.`
    : `This fleet has no orchestrator in its roster; coordinate with your peers directly.`;
  return `# Fleet Comms — reach your peers
 You are **${opts.selfName}** in this fleet. Your comms identity is \`[${opts.fleetHost}:${opts.selfName}]\` —
 that is the \`<src>\` other agents see and reply to. Reach other agents (durable tmux sessions) with the
 Mosaic comms tool at \`${opts.agentSendPath}\`. The **Reach** column below is the exact command per peer:
 same-host peers use the short form (no \`-H\`); cross-host peers include \`-H <user@host>\`.
 ## Peers
 | Agent | Role | Reach (session = agent name) |
 | ----- | ---- | ---------------------------- |
 ${rows}
 ${orchLine}
 ## Conventions
 - Every message carries a self-identifying preamble \`[<src_host>:<src_session> -> <dst_host>:<dst_session>]\` — \`agent-send.sh\` adds it automatically.
 - **To reply, FLIP the preamble:** address your reply to the sender's \`src\` (their host:session becomes your \`-s\`/\`-H\`).
 - \`agent-send.sh\` (a.k.a. \`agent send --verify\`) confirms the message was **ACCEPTED** at the destination prompt — not merely injected. Prefer it for anything that matters.`;
 }
 /**
 * Read the fleet roster from `mosaicHome` and build the comms block for
 * `selfName`. Returns '' when there is no roster, the agent is not in it, or
 * there are no peers — onboarding is best-effort and never throws.
 */
 export function readFleetCommsBlock(
  mosaicHome: string,
  selfName: string | undefined,
  fleetHost: string = hostname().split('.')[0] || 'localhost',
 ): string {
  if (!selfName) return '';
  const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
  if (!existsSync(rosterPath)) return '';
  let text: string;
  try {
    text = readFileSync(rosterPath, 'utf-8');
  } catch {
    return '';
  }
  const agents = parseRosterAgents(text);
  if (!agents.some((a) => a.name === selfName)) return ''; // not a member of this fleet
  return buildFleetCommsBlock({
    selfName,
    agents,
    fleetHost,
    agentSendPath: join(mosaicHome, 'tools', 'tmux', 'agent-send.sh'),
  });
 }
 /** Default mosaic home (mirrors launch.ts), for callers that don't pass one. */
 export const DEFAULT_MOSAIC_HOME_FOR_COMMS = join(homedir(), '.config', 'mosaic');
--- a/packages/mosaic/src/fleet/connectors/matrix.spec.ts
+++ b/packages/mosaic/src/fleet/connectors/matrix.spec.ts
@@ -1,184 +0,0 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import {
  MatrixConnector,
  buildMessageBody,
  parseSyncResponse,
  registerMatrixConnector,
  type FetchLike,
 } from './matrix.js';
 import { createConnector, _resetConnectorRegistry } from './registry.js';
 import type { MatrixConnectorConfig } from './types.js';
 const CONFIG: MatrixConnectorConfig = {
  homeserverUrl: 'https://matrix.internal/',
  userId: '@mos:internal',
  roomId: '!room:internal',
 };
 /** A fetch mock that returns queued responses and records calls. */
 function mockFetch(responses: Array<{ ok?: boolean; status?: number; body?: unknown }>): {
  fetchImpl: FetchLike;
  calls: Array<{ url: string; method?: string; body?: string }>;
 } {
  const calls: Array<{ url: string; method?: string; body?: string }> = [];
  let i = 0;
  const fetchImpl: FetchLike = async (url, init) => {
    calls.push({ url, method: init?.method, body: init?.body });
    const r = responses[Math.min(i, responses.length - 1)] ?? {};
    i += 1;
    return {
      ok: r.ok ?? true,
      status: r.status ?? 200,
      json: async () => r.body ?? {},
      text: async () => JSON.stringify(r.body ?? {}),
    };
  };
  return { fetchImpl, calls };
 }
 describe('buildMessageBody', () => {
  it('builds an m.text event', () => {
    expect(buildMessageBody({ text: 'hi' })).toEqual({ msgtype: 'm.text', body: 'hi' });
  });
  it('adds an m.thread relation when threadId is set', () => {
    expect(buildMessageBody({ text: 'hi', threadId: '$evt' })).toEqual({
      msgtype: 'm.text',
      body: 'hi',
      'm.relates_to': { rel_type: 'm.thread', event_id: '$evt' },
    });
  });
 });
 describe('parseSyncResponse', () => {
  it('extracts operator messages and skips the orchestrator’s own echoes', () => {
    const data = {
      next_batch: 's2',
      rooms: {
        join: {
          '!room:internal': {
            timeline: {
              events: [
                {
                  type: 'm.room.message',
                  sender: '@jason:internal',
                  origin_server_ts: 1_700_000_000_000,
                  content: { body: 'status?' },
                },
                {
                  type: 'm.room.message',
                  sender: '@mos:internal', // self — skipped
                  origin_server_ts: 1_700_000_001_000,
                  content: { body: 'working on it' },
                },
                { type: 'm.reaction', sender: '@jason:internal', content: {} }, // non-message
              ],
            },
          },
        },
      },
    };
    const msgs = parseSyncResponse(data, '!room:internal', '@mos:internal');
    expect(msgs).toHaveLength(1);
    expect(msgs[0]).toMatchObject({ text: 'status?', sender: '@jason:internal' });
    expect(msgs[0]!.ts).toBe(new Date(1_700_000_000_000).toISOString());
  });
  it('carries threadId through thread-relments', () => {
    const data = {
      rooms: {
        join: {
          '!room:internal': {
            timeline: {
              events: [
                {
                  type: 'm.room.message',
                  sender: '@jason:internal',
                  origin_server_ts: 1,
                  content: {
                    body: 'in thread',
                    'm.relates_to': { rel_type: 'm.thread', event_id: '$root' },
                  },
                },
              ],
            },
          },
        },
      },
    };
    expect(parseSyncResponse(data, '!room:internal', '@mos:internal')[0]!.threadId).toBe('$root');
  });
  it('returns [] for an empty/foreign sync', () => {
    expect(parseSyncResponse({}, '!room:internal', '@mos:internal')).toEqual([]);
  });
 });
 describe('MatrixConnector', () => {
  it('throws without an access token', () => {
    expect(() => new MatrixConnector(CONFIG, { accessToken: '' })).toThrow(/access token/i);
  });
  it('send PUTs an m.text event and returns the event id', async () => {
    const { fetchImpl, calls } = mockFetch([{ body: { event_id: '$abc' } }]);
    const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
    const res = await c.send({ text: 'pong' }, 1234);
    expect(res).toEqual({ delivered: true, messageId: '$abc' });
    expect(calls[0]!.method).toBe('PUT');
    expect(calls[0]!.url).toContain(
      '/_matrix/client/v3/rooms/!room%3Ainternal/send/m.room.message/mosaic-1234-1',
    );
    expect(JSON.parse(calls[0]!.body!)).toEqual({ msgtype: 'm.text', body: 'pong' });
  });
  it('send reports not-delivered on a non-2xx', async () => {
    const { fetchImpl } = mockFetch([{ ok: false, status: 403 }]);
    const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
    const res = await c.send({ text: 'x' });
    expect(res.delivered).toBe(false);
    expect(res.error).toContain('403');
  });
  it('health reports reachable + authenticated when whoami matches', async () => {
    const { fetchImpl } = mockFetch([
      { body: { versions: ['v1.11'] } }, // /versions
      { body: { user_id: '@mos:internal' } }, // /whoami
    ]);
    const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
    const h = await c.health();
    expect(h.reachable).toBe(true);
    expect(h.authenticated).toBe(true);
  });
  it('health flags auth mismatch', async () => {
    const { fetchImpl } = mockFetch([
      { body: {} },
      { body: { user_id: '@someone-else:internal' } },
    ]);
    const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
    const h = await c.health();
    expect(h.reachable).toBe(true);
    expect(h.authenticated).toBe(false);
  });
  it('health reports unreachable when /versions fails', async () => {
    const { fetchImpl } = mockFetch([{ ok: false, status: 502 }]);
    const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
    const h = await c.health();
    expect(h.reachable).toBe(false);
  });
 });
 describe('registerMatrixConnector', () => {
  beforeEach(() => _resetConnectorRegistry());
  it('registers a matrix factory createConnector can build', () => {
    registerMatrixConnector({ MATRIX_ACCESS_TOKEN: 'tok' } as NodeJS.ProcessEnv);
    const c = createConnector({ kind: 'matrix', matrix: CONFIG });
    expect(c.kind).toBe('matrix');
  });
  it('the factory rejects config missing the matrix block', () => {
    registerMatrixConnector({ MATRIX_ACCESS_TOKEN: 'tok' } as NodeJS.ProcessEnv);
    expect(() => createConnector({ kind: 'matrix' })).toThrow(/missing the .matrix. block/i);
  });
 });
--- a/packages/mosaic/src/fleet/connectors/matrix.ts
+++ b/packages/mosaic/src/fleet/connectors/matrix.ts
@@ -1,246 +0,0 @@
 /**
 * Matrix connector (F4 Phase 2) — speaks the Matrix client-server API directly
 * over HTTPS so it is homeserver-agnostic (Conduit default, Synapse alt). No
 * SDK: a small injectable fetch keeps it dependency-light and unit-testable.
 *
 * The access token is supplied by the caller (from the environment —
 * MATRIX_ACCESS_TOKEN — per the gateway secret pattern), never the roster.
 */
 import {
  type OrchestratorConnector,
  type OutboundMessage,
  type InboundMessage,
  type SendResult,
  type ConnectorHealth,
  type MatrixConnectorConfig,
  type Unsubscribe,
 } from './types.js';
 import { registerConnector } from './registry.js';
 /** Minimal fetch surface — avoids a lib.dom dependency and is trivial to mock. */
 export interface FetchLike {
  (
    url: string,
    init?: { method?: string; headers?: Record<string, string>; body?: string },
  ): Promise<{
    ok: boolean;
    status: number;
    json: () => Promise<unknown>;
    text: () => Promise<string>;
  }>;
 }
 export interface MatrixConnectorOptions {
  accessToken: string;
  /** Injectable fetch (defaults to global fetch). */
  fetchImpl?: FetchLike;
  /** Long-poll timeout for /sync, ms. */
  syncTimeoutMs?: number;
 }
 /** Build the `m.room.message` event content, threading when a threadId is set. */
 export function buildMessageBody(message: OutboundMessage): Record<string, unknown> {
  const content: Record<string, unknown> = {
    msgtype: 'm.text',
    body: message.text,
  };
  if (message.threadId) {
    content['m.relates_to'] = { rel_type: 'm.thread', event_id: message.threadId };
  }
  return content;
 }
 /** Shape of the bits of a /sync response we consume. */
 interface SyncResponse {
  next_batch?: string;
  rooms?: {
    join?: Record<
      string,
      {
        timeline?: {
          events?: Array<{
            type?: string;
            sender?: string;
            origin_server_ts?: number;
            content?: {
              body?: string;
              ['m.relates_to']?: { rel_type?: string; event_id?: string };
            };
          }>;
        };
      }
    >;
  };
 }
 /**
 * Extract inbound operator messages from a /sync response for one room,
 * skipping the orchestrator's own echoes. Pure — the testable core of receive.
 */
 export function parseSyncResponse(
  data: unknown,
  roomId: string,
  selfUserId: string,
 ): InboundMessage[] {
  const sync = data as SyncResponse;
  const events = sync.rooms?.join?.[roomId]?.timeline?.events ?? [];
  const out: InboundMessage[] = [];
  for (const ev of events) {
    if (ev.type !== 'm.room.message') continue;
    if (!ev.sender || ev.sender === selfUserId) continue; // skip our own messages
    const body = ev.content?.body;
    if (typeof body !== 'string') continue;
    const rel = ev.content?.['m.relates_to'];
    out.push({
      text: body,
      sender: ev.sender,
      ts: new Date(ev.origin_server_ts ?? 0).toISOString(),
      ...(rel?.rel_type === 'm.thread' && rel.event_id ? { threadId: rel.event_id } : {}),
    });
  }
  return out;
 }
 export class MatrixConnector implements OrchestratorConnector {
  readonly kind = 'matrix' as const;
  private readonly fetchImpl: FetchLike;
  private readonly token: string;
  private readonly syncTimeoutMs: number;
  private txnCounter = 0;
  private stopped = false;
  constructor(
    private readonly config: MatrixConnectorConfig,
    opts: MatrixConnectorOptions,
  ) {
    this.token = opts.accessToken;
    this.fetchImpl = opts.fetchImpl ?? (globalThis.fetch as unknown as FetchLike);
    this.syncTimeoutMs = opts.syncTimeoutMs ?? 30_000;
    if (!this.token) {
      throw new Error('MatrixConnector requires an access token (set MATRIX_ACCESS_TOKEN).');
    }
  }
  private url(path: string): string {
    return `${this.config.homeserverUrl.replace(/\/$/, '')}${path}`;
  }
  private authHeaders(): Record<string, string> {
    return { Authorization: `Bearer ${this.token}`, 'Content-Type': 'application/json' };
  }
  /** Monotonic, unique-per-instance transaction id for idempotent sends. */
  private nextTxnId(nowMs: number): string {
    this.txnCounter += 1;
    return `mosaic-${nowMs}-${this.txnCounter}`;
  }
  async send(message: OutboundMessage, nowMs = Date.now()): Promise<SendResult> {
    const txnId = this.nextTxnId(nowMs);
    const path = `/_matrix/client/v3/rooms/${encodeURIComponent(
      this.config.roomId,
    )}/send/m.room.message/${encodeURIComponent(txnId)}`;
    try {
      const res = await this.fetchImpl(this.url(path), {
        method: 'PUT',
        headers: this.authHeaders(),
        body: JSON.stringify(buildMessageBody(message)),
      });
      if (!res.ok) {
        return { delivered: false, error: `Matrix send failed: HTTP ${res.status}` };
      }
      const json = (await res.json()) as { event_id?: string };
      return { delivered: true, ...(json.event_id ? { messageId: json.event_id } : {}) };
    } catch (err) {
      return { delivered: false, error: err instanceof Error ? err.message : String(err) };
    }
  }
  subscribe(handler: (message: InboundMessage) => void): Unsubscribe {
    this.stopped = false;
    let since: string | undefined;
    const loop = async (): Promise<void> => {
      while (!this.stopped) {
        try {
          const q = new URLSearchParams({ timeout: String(this.syncTimeoutMs) });
          if (since) q.set('since', since);
          const res = await this.fetchImpl(this.url(`/_matrix/client/v3/sync?${q.toString()}`), {
            method: 'GET',
            headers: this.authHeaders(),
          });
          if (!res.ok) {
            await this.backoff();
            continue;
          }
          const data = await res.json();
          since = (data as SyncResponse).next_batch ?? since;
          for (const msg of parseSyncResponse(data, this.config.roomId, this.config.userId)) {
            handler(msg);
          }
        } catch {
          await this.backoff();
        }
      }
    };
    void loop();
    return () => {
      this.stopped = true;
    };
  }
  private backoff(): Promise<void> {
    return new Promise((resolve) => setTimeout(resolve, 2_000));
  }
  async health(): Promise<ConnectorHealth> {
    try {
      const versions = await this.fetchImpl(this.url('/_matrix/client/versions'), {
        method: 'GET',
      });
      if (!versions.ok) {
        return {
          reachable: false,
          authenticated: false,
          detail: `versions HTTP ${versions.status}`,
        };
      }
      const who = await this.fetchImpl(this.url('/_matrix/client/v3/account/whoami'), {
        method: 'GET',
        headers: this.authHeaders(),
      });
      if (!who.ok) {
        return { reachable: true, authenticated: false, detail: `whoami HTTP ${who.status}` };
      }
      const json = (await who.json()) as { user_id?: string };
      const authenticated = json.user_id === this.config.userId;
      return {
        reachable: true,
        authenticated,
        lastSeen: new Date().toISOString(),
        ...(authenticated
          ? {}
          : { detail: `whoami user ${json.user_id} != ${this.config.userId}` }),
      };
    } catch (err) {
      return {
        reachable: false,
        authenticated: false,
        detail: err instanceof Error ? err.message : String(err),
      };
    }
  }
 }
 /**
 * Register the Matrix connector factory. The token is read from the environment
 * (MATRIX_ACCESS_TOKEN) at build time, never the roster.
 */
 export function registerMatrixConnector(env: NodeJS.ProcessEnv = process.env): void {
  registerConnector('matrix', (config) => {
    if (!config.matrix) {
      throw new Error('Matrix connector config missing the `matrix` block (homeserver/user/room).');
    }
    return new MatrixConnector(config.matrix, { accessToken: env['MATRIX_ACCESS_TOKEN'] ?? '' });
  });
 }
--- a/packages/mosaic/src/fleet/connectors/registry.spec.ts
+++ b/packages/mosaic/src/fleet/connectors/registry.spec.ts
@@ -1,85 +0,0 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import {
  KNOWN_CONNECTOR_KINDS,
  isKnownConnectorKind,
  resolveConnectorKind,
  registerConnector,
  hasConnector,
  createConnector,
  ConnectorNotImplementedError,
  _resetConnectorRegistry,
 } from './registry.js';
 import type { ConnectorConfig, OrchestratorConnector } from './types.js';
 function fakeConnector(kind: 'tmux' | 'discord' | 'matrix'): OrchestratorConnector {
  return {
    kind,
    send: async () => ({ delivered: true, messageId: 'x' }),
    subscribe: () => () => {},
    health: async () => ({ reachable: true, authenticated: true }),
  };
 }
 describe('connector registry (F4 Phase 1)', () => {
  beforeEach(() => {
    _resetConnectorRegistry();
  });
  it('knows the three peer connector kinds', () => {
    expect(KNOWN_CONNECTOR_KINDS).toEqual(['tmux', 'discord', 'matrix']);
  });
  it('isKnownConnectorKind guards correctly', () => {
    expect(isKnownConnectorKind('matrix')).toBe(true);
    expect(isKnownConnectorKind('irc')).toBe(false);
    expect(isKnownConnectorKind(42)).toBe(false);
  });
  it('resolveConnectorKind defaults to tmux when config is absent (back-compat)', () => {
    expect(resolveConnectorKind(undefined)).toBe('tmux');
    expect(resolveConnectorKind({ kind: 'matrix' })).toBe('matrix');
  });
  it('createConnector throws ConnectorNotImplementedError for an unregistered kind', () => {
    const cfg: ConnectorConfig = { kind: 'matrix' };
    expect(() => createConnector(cfg)).toThrow(ConnectorNotImplementedError);
    expect(() => createConnector(cfg)).toThrow(/not implemented yet/i);
  });
  it('createConnector with no config resolves the default kind (tmux) and reports it unimplemented in Phase 1', () => {
    try {
      createConnector();
      throw new Error('expected throw');
    } catch (err) {
      expect(err).toBeInstanceOf(ConnectorNotImplementedError);
      expect((err as ConnectorNotImplementedError).kind).toBe('tmux');
    }
  });
  it('register → has → create resolves a registered factory', () => {
    expect(hasConnector('matrix')).toBe(false);
    registerConnector('matrix', (cfg) => fakeConnector(cfg.kind));
    expect(hasConnector('matrix')).toBe(true);
    const connector = createConnector({ kind: 'matrix' });
    expect(connector.kind).toBe('matrix');
  });
  it('passes the config through to the factory', () => {
    let received: ConnectorConfig | null = null;
    registerConnector('matrix', (cfg) => {
      received = cfg;
      return fakeConnector(cfg.kind);
    });
    const cfg: ConnectorConfig = {
      kind: 'matrix',
      matrix: {
        homeserverUrl: 'https://matrix.internal',
        userId: '@mos:internal',
        roomId: '!room:internal',
      },
    };
    createConnector(cfg);
    expect(received).toEqual(cfg);
  });
 });
--- a/packages/mosaic/src/fleet/connectors/registry.ts
+++ b/packages/mosaic/src/fleet/connectors/registry.ts
@@ -1,76 +0,0 @@
 /**
 * Connector registry (F4 Phase 1).
 *
 * A tiny extensible registry so connector implementations (Phase 2: tmux,
 * Discord, Matrix) register a factory by kind and fleet core resolves one from
 * roster config without branching on kind. Phase 1 ships the registry + the
 * config→kind resolution; the connector factories land in Phase 2.
 */
 import {
  type ConnectorConfig,
  type ConnectorKind,
  type OrchestratorConnector,
  DEFAULT_CONNECTOR_KIND,
 } from './types.js';
 /** The set of connector kinds the framework recognizes. */
 export const KNOWN_CONNECTOR_KINDS: readonly ConnectorKind[] = ['tmux', 'discord', 'matrix'];
 /** Type guard: is `value` a known connector kind? */
 export function isKnownConnectorKind(value: unknown): value is ConnectorKind {
  return typeof value === 'string' && (KNOWN_CONNECTOR_KINDS as readonly string[]).includes(value);
 }
 /**
 * Resolve the connector kind from roster config. Absent config ⇒ the default
 * (tmux) so existing rosters keep working unchanged (back-compat).
 */
 export function resolveConnectorKind(config?: ConnectorConfig): ConnectorKind {
  return config?.kind ?? DEFAULT_CONNECTOR_KIND;
 }
 /** A factory builds a live connector from its validated config. */
 export type ConnectorFactory = (config: ConnectorConfig) => OrchestratorConnector;
 /** Thrown when no factory is registered for a requested kind. */
 export class ConnectorNotImplementedError extends Error {
  constructor(public readonly kind: ConnectorKind) {
    super(
      `Connector "${kind}" is not implemented yet. ` +
        `Register a factory via registerConnector('${kind}', …) (F4 Phase 2).`,
    );
    this.name = 'ConnectorNotImplementedError';
  }
 }
 const registry = new Map<ConnectorKind, ConnectorFactory>();
 /** Register a connector factory for a kind (idempotent — last registration wins). */
 export function registerConnector(kind: ConnectorKind, factory: ConnectorFactory): void {
  registry.set(kind, factory);
 }
 /** True when a factory is registered for `kind`. */
 export function hasConnector(kind: ConnectorKind): boolean {
  return registry.has(kind);
 }
 /**
 * Build a connector from roster config. Throws `ConnectorNotImplementedError`
 * when no factory is registered for the resolved kind (the Phase-1 default for
 * every kind until Phase 2 registers them).
 */
 export function createConnector(config?: ConnectorConfig): OrchestratorConnector {
  const kind = resolveConnectorKind(config);
  const factory = registry.get(kind);
  if (!factory) {
    throw new ConnectorNotImplementedError(kind);
  }
  return factory(config ?? { kind });
 }
 /** Test/runtime helper: drop all registrations. */
 export function _resetConnectorRegistry(): void {
  registry.clear();
 }
--- a/packages/mosaic/src/fleet/connectors/types.ts
+++ b/packages/mosaic/src/fleet/connectors/types.ts
@@ -1,111 +0,0 @@
 /**
 * Orchestrator chat connectors (F4).
 *
 * A connector mediates the chat channel between the fleet **orchestrator** and
 * its human operator. Connectors are PEERS — tmux (default), Discord, Matrix,
 * and future first-party plugins — selected per fleet, never hardwired. Fleet
 * core depends only on the small uniform interface below, so a new connector
 * drops in without touching the fleet.
 *
 * The interface is deliberately minimal: send (orchestrator → human),
 * subscribe (human → orchestrator), health (reachable/authed liveness). Thread
 * support is optional metadata (`threadId`) so thread-capable connectors
 * (Matrix rooms/threads, the future Mosaic Discord plugin) fit without an
 * interface change.
 */
 /** The connector kinds shipped/known to the framework. */
 export type ConnectorKind = 'tmux' | 'discord' | 'matrix';
 /** A message the orchestrator sends out to the human operator. */
 export interface OutboundMessage {
  /** Message body (markdown where the connector supports it). */
  text: string;
  /** Optional thread/topic id for thread-capable connectors. */
  threadId?: string;
  /** Optional attachment references (paths or URLs); connector-dependent. */
  attachments?: string[];
 }
 /** A message received from the human operator. */
 export interface InboundMessage {
  /** Message body. */
  text: string;
  /** Thread/topic id if the connector carries one. */
  threadId?: string;
  /** Opaque sender identifier (connector-scoped). */
  sender: string;
  /** ISO-8601 timestamp the connector assigns/observes. */
  ts: string;
 }
 /** Result of a send — the "ack" half of ack/health. */
 export interface SendResult {
  /** True when the connector accepted/delivered the message. */
  delivered: boolean;
  /** Connector-assigned message id when available. */
  messageId?: string;
  /** Reason when `delivered` is false. */
  error?: string;
 }
 /** Liveness of a connector — the "health" half of ack/health. */
 export interface ConnectorHealth {
  /** The transport endpoint is reachable. */
  reachable: boolean;
  /** Credentials are valid / the connector is authenticated. */
  authenticated: boolean;
  /** ISO-8601 of the last successful interaction, if any. */
  lastSeen?: string;
  /** Human-readable detail (e.g. failure reason). */
  detail?: string;
 }
 /** Unsubscribe handle returned by `subscribe`. */
 export type Unsubscribe = () => void;
 /**
 * The uniform contract every orchestrator chat connector implements. Small by
 * design — send / subscribe / health — so connectors are interchangeable and
 * fleet core never branches on connector kind.
 */
 export interface OrchestratorConnector {
  /** Which kind of connector this is. */
  readonly kind: ConnectorKind;
  /** Send a message from the orchestrator to the operator. */
  send(message: OutboundMessage): Promise<SendResult>;
  /** Subscribe to inbound operator messages; returns an unsubscribe handle. */
  subscribe(handler: (message: InboundMessage) => void): Unsubscribe;
  /** Report connector liveness (reachable + authenticated). */
  health(): Promise<ConnectorHealth>;
 }
 /**
 * Connector configuration carried by the roster (the `connector` block).
 * Secrets (access tokens, bot tokens) are NEVER stored here — they come from
 * the environment (the gateway env-config pattern). Absent config ⇒ tmux.
 */
 export interface ConnectorConfig {
  kind: ConnectorKind;
  /** Matrix connector settings (homeserver + room); token via env. */
  matrix?: MatrixConnectorConfig;
  /** Discord connector settings (channel); token via env. */
  discord?: DiscordConnectorConfig;
 }
 export interface MatrixConnectorConfig {
  /** Local homeserver base URL, e.g. https://matrix.example.internal */
  homeserverUrl: string;
  /** Full Matrix user id of the orchestrator, e.g. @mos:example.internal */
  userId: string;
  /** Room id/alias the orchestrator converses in. */
  roomId: string;
 }
 export interface DiscordConnectorConfig {
  /** Channel id the orchestrator converses in. */
  channelId: string;
 }
 /** The default connector when a roster declares none (back-compat). */
 export const DEFAULT_CONNECTOR_KIND: ConnectorKind = 'tmux';
--- a/packages/mosaic/src/runtime/update-checker.reseed.spec.ts
+++ b/packages/mosaic/src/runtime/update-checker.reseed.spec.ts
@@ -7,9 +7,7 @@ import {
  buildRelaunchCommands,
  readRosterAgentNames,
  runFrameworkReseed,
  refreshActiveFleetUnits,
 } from './update-checker.js';
 import { existsSync, readFileSync } from 'node:fs';
 /**
 * F3-m3 / R13: `mosaic update` re-seeds the framework + (opt-in) relaunches
@@ -85,41 +83,3 @@ describe('runFrameworkReseed', () => {
    rmSync(missing, { recursive: true, force: true });
  });
 });
 describe('refreshActiveFleetUnits', () => {
  let root: string;
  let mosaicHome: string;
  let configHome: string;
  beforeEach(() => {
    root = mkdtempSync(join(tmpdir(), 'mosaic-units-'));
    mosaicHome = join(root, 'mosaic');
    configHome = join(root, 'config');
    mkdirSync(join(mosaicHome, 'systemd', 'user'), { recursive: true });
    mkdirSync(join(configHome, 'systemd', 'user'), { recursive: true });
    // Freshly re-seeded units (new content).
    writeFileSync(join(mosaicHome, 'systemd', 'user', 'mosaic-agent@.service'), 'NEW\n');
    writeFileSync(join(mosaicHome, 'systemd', 'user', 'mosaic-tmux-holder.service'), 'NEW\n');
  });
  afterEach(() => rmSync(root, { recursive: true, force: true }));
  it('refreshes active units when a fleet is already installed', () => {
    // Active dir already carries mosaic units (stale) → fleet is installed.
    writeFileSync(join(configHome, 'systemd', 'user', 'mosaic-agent@.service'), 'OLD\n');
    const res = refreshActiveFleetUnits(mosaicHome, {
      XDG_CONFIG_HOME: configHome,
    } as NodeJS.ProcessEnv);
    expect(res.refreshed).toContain('mosaic-agent@.service');
    expect(
      readFileSync(join(configHome, 'systemd', 'user', 'mosaic-agent@.service'), 'utf-8'),
    ).toBe('NEW\n');
  });
  it('is a no-op when no fleet is installed (active dir has no mosaic units)', () => {
    const res = refreshActiveFleetUnits(mosaicHome, {
      XDG_CONFIG_HOME: configHome,
    } as NodeJS.ProcessEnv);
    expect(res.refreshed).toEqual([]);
    expect(existsSync(join(configHome, 'systemd', 'user', 'mosaic-agent@.service'))).toBe(false);
  });
 });
--- a/packages/mosaic/src/runtime/update-checker.ts
+++ b/packages/mosaic/src/runtime/update-checker.ts
@@ -14,14 +14,7 @@
 */
 import { execSync } from 'node:child_process';
-import {
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
  existsSync,
  mkdirSync,
  readFileSync,
  writeFileSync,
  readdirSync,
  copyFileSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -543,47 +536,6 @@ export function readRosterAgentNames(mosaicHome = join(homedir(), '.config', 'mo
  return names;
 }
 /**
 * Refresh the ACTIVE systemd user units from the freshly re-seeded copies.
 *
 * The re-seed updates `~/.config/mosaic/systemd/user/*.service`, but the units
 * systemd actually runs live at `~/.config/systemd/user/`. Without this copy,
 * shipped unit fixes (e.g. the socket-env change) never take effect after
 * `mosaic update` until `mosaic fleet install` is re-run. Best-effort + scoped:
 * only refreshes when a fleet is already installed (the active dir already
 * carries `mosaic-*` units), so non-fleet hosts are untouched.
 */
 export function refreshActiveFleetUnits(
  mosaicHome = join(homedir(), '.config', 'mosaic'),
  env: NodeJS.ProcessEnv = process.env,
 ): { refreshed: string[]; ok: boolean; reason?: string } {
  const src = join(mosaicHome, 'systemd', 'user');
  const configHome = env['XDG_CONFIG_HOME'] ?? join(homedir(), '.config');
  const dest = join(configHome, 'systemd', 'user');
  if (!existsSync(src)) return { refreshed: [], ok: true };
  // Only refresh when a fleet is already installed (active dir has mosaic units).
  const fleetInstalled =
    existsSync(dest) &&
    readdirSync(dest).some((f) => f.startsWith('mosaic-') && f.endsWith('.service'));
  if (!fleetInstalled) return { refreshed: [], ok: true };
  const units = readdirSync(src).filter((f) => f.startsWith('mosaic-') && f.endsWith('.service'));
  const refreshed: string[] = [];
  for (const unit of units) {
    try {
      copyFileSync(join(src, unit), join(dest, unit));
      refreshed.push(unit);
    } catch {
      // best-effort per unit
    }
  }
  try {
    execSync('systemctl --user daemon-reload', { stdio: 'ignore', timeout: 15_000 });
  } catch {
    // non-systemd host or no session bus — non-fatal
  }
  return { refreshed, ok: true };
 }
 /** Build the per-agent systemd relaunch commands (drain+relaunch via restart). */
 export function buildRelaunchCommands(agentNames: string[]): string[][] {
  return agentNames.map((name) => [