docs(framework): alpha DoD §8 green-checklist + v0.0.39-alpha release notes

Maps every Constitution-alpha acceptance criterion (DESIGN §8) to its merged PR, and drafts the Gitea release notes for the v0.0.39-alpha tag. For the Lead to use when cutting the tag after P5 #605 -> P6 #607 -> aiguide #8 merge. Refs #606, #542 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83
chore(format): prettier docs/fleet/PRD-fleet-suite.md (pre-existing main violation)
2026-06-21 21:13:38 -05:00 · 2026-06-21 21:07:32 -05:00 · 2026-06-21 21:05:44 -05:00
29 changed files with 31 additions and 1826 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
@@ -46,27 +46,6 @@ Active workstream is **W1 — Federation v1**. Workers should:
 - Cut always-injected contract AGENTS+TOOLS+RUNTIME 8,827→4,122 tok (−53%); all 12 hard gates intact.
 - Validation: deterministic gate-checklist PASS; headless A/B thin 7/9 vs monolith 5/9. Detail: scratchpads/contract-thin-core.md.
 ## P5 — Overlay composer + cross-harness (#604) — feat/p5-overlay-composer
 - Status: MERGED to main (#605). R7 (compose-contract) + R8 (cross-harness) + R9 (composer test).
 - `composeContract({harness, mosaicHome})` pure fn + `.local` overlay deltas-by-value; `mosaic compose-contract <harness>` command; AGENTS bare-launch nudge; composer spec (per-tier anchor + Tier-3 byte-equality). Detail: scratchpads/p5-overlay-composer.md.
 ## P6 — Docs, compliance matrix, alpha tag (#606) — feat/p6-docs-compliance-alpha
- Status: in-repo deliverables done (CONTRIBUTING.md + harness×gate compliance matrix + check-resident-budget.sh + CI wiring + ALPHA-DOD.md). Remaining: alpha tag v0.0.39-alpha (Lead, post-merge). aiguide reconcile merged (#8). Detail: scratchpads/p6-docs-compliance-alpha.md.
+- Status: in-repo deliverables done (CONTRIBUTING.md + harness×gate compliance matrix + check-resident-budget.sh + CI wiring). Remaining: aiguide reconcile (separate repo), alpha tag (Lead, post-merge). Detail: scratchpads/p6-docs-compliance-alpha.md.
 ## 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.
--- 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/f3-m3-update-reseed.md
+++ b/docs/scratchpads/f3-m3-update-reseed.md
@@ -1,29 +0,0 @@
 # F3-m3 — `mosaic update` re-seeds framework + relaunches agents (R13)
 - **Issue:** #609 · **Branch:** `feat/f3-m3-update-reseed`
 ## Gap (found in 0.0.39 production validation)
 `mosaic update` installs the new npm CLI but never re-seeds `~/.config/mosaic/` from the package's
 bundled `framework/`. So the shipped custom Pi harness (agent-name export + native HB, 0.0.39) stays
 DORMANT until a re-seed — operators get the new CLI on a stale framework.
 ## Implementation
 - `update-checker.ts`: `resolveBundledFrameworkRoot()`, `buildReseedCommand()` (install.sh in
  `MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep` — the P4 data-safe reconcile), `runFrameworkReseed()`,
  `readRosterAgentNames()`, `buildRelaunchCommands()` (systemctl --user restart per agent).
 - `cli.ts` `update`: after a successful CLI install that includes `@mosaicstack/mosaic`, re-seed the
  framework (default-on; `--no-reseed` to skip). Then either `--relaunch` (restart rostered agents) or
  print clear guidance to run `mosaic update --relaunch` / `mosaic fleet restart`.
 ## Flow
 `update CLI → re-seed framework (data-safe) → relaunch agents (opt-in)` — closes R13, activates the
 native harness for every operator.
 ## Verification
 - 6 new unit tests (reseed command/env, relaunch commands, roster parse, missing-installer guard).
 - 19 runtime + 26 launch tests still green; tsc/eslint/prettier clean.
 - Data-safety of the sync is already proven (P4 5-fixture matrix + live dragon-lin validation).
--- 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-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/p5-overlay-composer.md
+++ b/docs/scratchpads/p5-overlay-composer.md
@@ -1,43 +0,0 @@
 # P5 — Overlay composer + cross-harness (compose-contract)
 - **Issue:** #604 · **Branch:** `feat/p5-overlay-composer` · **Lineage:** #542 → constitution alpha
 - **Requirements:** R7 (compose-contract) + R8 (cross-harness) + R9 (composer test)
 - **Design of record:** `docs/design/framework-constitution/{DESIGN.md §3.2, PRD.md §4}` (on `feat/framework-constitution-alpha`)
 ## Locked design (sequential-thinking)
 Current `launch.ts` assembly (`buildComposedPrompt`) injects by value: mission + PRD + hard-gate +
 CONSTITUTION + AGENTS + USER + TOOLS + runtime. It does **not** inject SOUL or STANDARDS (those are
 read-on-demand per the gutted AGENTS dispatcher), and has no `.local` overlay support.
 **Decision (ASSUMPTION — recorded for the PR):** overlays are injected as **deltas by value** under
 labeled sections; base files keep their existing residency.
 - `USER.local.md` → appended directly under the `# User Profile` block (USER is injected).
 - `SOUL.local.md` + `STANDARDS.local.md` → a trailing `# Operator Overlays` section (their bases are
  load-on-demand, so only the small delta is injected — not the full base prose).
 - **Why:** honors DESIGN §3.2 ("model gets one pre-merged blob, no read-merge ritual") while preserving
  the P3 byte-budget tiering (don't re-inject large SOUL/STANDARDS prose). Precedence order kept: base
  layers first, operator overlays at recency.
 - Base-only is automatic when a `.local` file is absent (`readOptional`).
 ## Plan
 | #   | Task                                                                                                   | File                                    |
 | --- | ------------------------------------------------------------------------------------------------------ | --------------------------------------- |
 | 1   | Extract `composeContract({harness, mosaicHome})` pure fn; `buildComposedPrompt` delegates              | `src/commands/launch.ts`                |
 | 2   | Overlay logic (USER.local under profile; SOUL/STANDARDS.local in `# Operator Overlays`)                | `src/commands/launch.ts`                |
 | 3   | `mosaic compose-contract <harness>` command → prints blob to stdout                                    | `src/commands/launch.ts`                |
 | 4   | Bare-launch overlay nudge in self-load fallback                                                        | `framework/defaults/AGENTS.md`          |
 | 5   | `compose-contract.spec.ts`: per-tier anchor, Tier-3 byte-equality, overlay present/absent, per-harness | `src/commands/compose-contract.spec.ts` |
 ## Deferred to P6
 CONTRIBUTING.md + harness×gate compliance matrix; resident line-count CI ceiling; `aiguide` reconcile;
 alpha tag `mosaic-vX.Y.Z-alpha`.
 ## Status
 - [x] Phase scaffold (branch, issue #604, scratchpad, TASKS)
 - [ ] Implementation (tasks 1–5)
 - [ ] prettier + vitest green; PR via wrapper → Lead (rides 0.0.39; 0.0.38 mid-cut)
--- a/packages/mosaic/framework/defaults/AGENTS.md
+++ b/packages/mosaic/framework/defaults/AGENTS.md
@@ -9,10 +9,7 @@ overwritten on upgrade. (Layer model: `constitution/LAYER-MODEL.md`.)
 1. Your context already includes `CONSTITUTION.md` + `USER.md` + the TOOLS index + the runtime
   contract (injected by `mosaic` launch) — do not re-read those. **If you were launched bare**
   (a harness started without `mosaic`, so the law is NOT in your context), read
-   `~/.config/mosaic/CONSTITUTION.md` now, before your first action. A bare launch also gets
+   `~/.config/mosaic/CONSTITUTION.md` now, before your first action.
   **base contracts only** — operator overlays (`*.local.md`) are composed by the launcher, so if
   `SOUL.local.md`/`USER.local.md`/`STANDARDS.local.md` exist, relaunch via `mosaic <harness>` (or run
   `mosaic doctor`) to pick them up.
 2. Read `SOUL.md` (agent persona — small, once).
 3. Read project-local `AGENTS.md` / `CLAUDE.md` if present (these may only make behavior stricter).
 4. Read guides ONLY as triggered by the table below — pull role-relevant depth on demand, not up front.
--- 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
@@ -113,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/package.json
+++ b/packages/mosaic/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@mosaicstack/mosaic",
-  "version": "0.0.39",
+  "version": "0.0.37",
  "repository": {
    "type": "git",
    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
--- a/packages/mosaic/src/cli.ts
+++ b/packages/mosaic/src/cli.ts
@@ -26,10 +26,6 @@ import {
  checkForAllUpdates,
  formatAllPackagesTable,
  getInstallAllCommand,
  runFrameworkReseed,
  readRosterAgentNames,
  buildRelaunchCommands,
  FRAMEWORK_RESEED_PACKAGE,
 } from './runtime/update-checker.js';
 import { runWizard } from './wizard.js';
 import { ClackPrompter } from './prompter/clack-prompter.js';
@@ -408,12 +404,7 @@ program
  .command('update')
  .description('Check for and install Mosaic CLI updates')
  .option('--check', 'Check only, do not install')
-  .option(
+  .action(async (opts: { check?: boolean }) => {
    '--no-reseed',
    'Skip re-seeding framework files into ~/.config/mosaic after the CLI update',
  )
  .option('--relaunch', 'Restart durable fleet agents so the new launcher/runtime takes effect')
  .action(async (opts: { check?: boolean; reseed?: boolean; relaunch?: boolean }) => {
    // checkForAllUpdates imported statically above
    const { execSync } = await import('node:child_process');
@@ -451,51 +442,6 @@ program
      console.error('\nUpdate failed. Try manually: bash tools/install.sh');
      process.exit(1);
    }
    // F3-m3 / R13: the CLI is updated, but the framework files in
    // ~/.config/mosaic/ are still the previous version. Re-seed them from the
    // freshly-installed package so shipped launcher/runtime changes ACTIVATE.
    // Only when the framework-bearing package itself updated.
    const mosaicUpdated = outdated.some(
      (r: { package: string }) => r.package === FRAMEWORK_RESEED_PACKAGE,
    );
    if (mosaicUpdated && opts.reseed !== false) {
      console.log(
        '\nRe-seeding framework files into ~/.config/mosaic (data-safe; keeps your edits)…',
      );
      const reseed = runFrameworkReseed();
      if (reseed.ok) {
        console.log('✔ Framework re-seeded.');
        const agents = readRosterAgentNames();
        if (agents.length > 0) {
          if (opts.relaunch) {
            console.log(
              `\nRelaunching ${agents.length} fleet agent(s) to pick up the new runtime…`,
            );
            for (const restart of buildRelaunchCommands(agents)) {
              try {
                execSync(restart.join(' '), { stdio: 'inherit', timeout: 30_000 });
              } catch {
                console.error(`  ⚠ failed to restart agent — run: ${restart.join(' ')}`);
              }
            }
            console.log('✔ Agents relaunched.');
          } else {
            console.log(
              `\nℹ ${agents.length} fleet agent(s) are still running the previous runtime. ` +
                'Restart them to activate the update:\n    mosaic update --relaunch   ' +
                '(or: mosaic fleet restart <agent>)',
            );
          }
        }
      } else {
        console.error(
          `\n⚠ Framework re-seed skipped: ${reseed.reason ?? 'unknown'}.\n` +
            '  Activate manually: bash "$(npm root -g)/@mosaicstack/mosaic/framework/install.sh" ' +
            '(MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep)',
        );
      }
    }
  });
 // ─── wizard ─────────────────────────────────────────────────────────────
--- a/packages/mosaic/src/commands/compose-contract.spec.ts
+++ b/packages/mosaic/src/commands/compose-contract.spec.ts
@@ -1,118 +0,0 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { composeContract } from './launch.js';
 /**
 * Composer unit test (R7/R8/R9): asserts the launcher-composed runtime contract
 *
 *   - includes the per-tier anchors (CONSTITUTION / AGENTS / USER / runtime),
 *   - keeps the CONSTITUTION block byte-equal to the on-disk file (Tier-3
 *     byte-equality — the bare-launch fallback read must match what is injected),
 *   - merges `*.local.md` operator overlays as deltas-by-value, and omits them
 *     entirely when absent (base-only),
 *   - selects the correct per-harness RUNTIME.md.
 *
 * `composeContract` takes `mosaicHome` as a param, so each test runs against an
 * isolated fixture home. We also chdir to an empty temp cwd so the cwd-relative
 * mission/PRD blocks contribute nothing (deterministic output).
 */
 const CONSTITUTION = '# CONSTITUTION\n\nGATE-1: the non-negotiable law.\n';
 const AGENTS = '# Mosaic Agent Dispatcher\n\nLoad order + guide router.\n';
 const USER = '# operator\n\nName: Test Operator\n';
 const TOOLS = '# tools index\n';
 function makeHome(): { home: string; root: string } {
  const root = mkdtempSync(join(tmpdir(), 'mosaic-compose-'));
  const home = join(root, 'mosaic-home');
  for (const h of ['claude', 'codex', 'opencode', 'pi']) {
    mkdirSync(join(home, 'runtime', h), { recursive: true });
    writeFileSync(join(home, 'runtime', h, 'RUNTIME.md'), `# ${h} runtime contract\n`);
  }
  writeFileSync(join(home, 'CONSTITUTION.md'), CONSTITUTION);
  writeFileSync(join(home, 'AGENTS.md'), AGENTS);
  writeFileSync(join(home, 'USER.md'), USER);
  writeFileSync(join(home, 'TOOLS.md'), TOOLS);
  return { home, root };
 }
 describe('composeContract — overlay composer', () => {
  let fixture: ReturnType<typeof makeHome>;
  let prevCwd: string;
  let cwdDir: string;
  beforeEach(() => {
    fixture = makeHome();
    prevCwd = process.cwd();
    cwdDir = mkdtempSync(join(tmpdir(), 'mosaic-cwd-'));
    process.chdir(cwdDir); // neutralize cwd-relative mission/PRD blocks
  });
  afterEach(() => {
    process.chdir(prevCwd);
    rmSync(fixture.root, { recursive: true, force: true });
    rmSync(cwdDir, { recursive: true, force: true });
  });
  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
    expect(out).toContain('Mosaic Agent Dispatcher'); // AGENTS
    expect(out).toContain('# User Profile'); // USER header
    expect(out).toContain('Name: Test Operator'); // USER body
    expect(out).toContain('# Runtime-Specific Contract');
    expect(out).toContain('# claude runtime contract');
  });
  it('keeps the CONSTITUTION block byte-equal to the on-disk file (Tier-3)', () => {
    const out = composeContract('pi', fixture.home);
    const onDisk = readFileSync(join(fixture.home, 'CONSTITUTION.md'), 'utf-8');
    // The injected L0 must be a byte-equal substring of the composed blob, so a
    // bare-launch fallback read of CONSTITUTION.md matches what was injected.
    expect(out.includes(onDisk)).toBe(true);
  });
  it('is base-only when no *.local overlays exist', () => {
    const out = composeContract('claude', fixture.home);
    expect(out).not.toContain('# Operator Overlays');
    expect(out).not.toContain('Operator Overlay (USER.local.md)');
    expect(out).not.toContain('Persona Overlay');
    expect(out).not.toContain('Standards Overlay');
  });
  it('merges USER.local.md directly under the operator profile', () => {
    writeFileSync(join(fixture.home, 'USER.local.md'), 'Prefer terse status updates.\n');
    const out = composeContract('claude', fixture.home);
    expect(out).toContain('## Operator Overlay (USER.local.md)');
    expect(out).toContain('Prefer terse status updates.');
    // Overlay appears AFTER its base profile.
    expect(out.indexOf('# User Profile')).toBeLessThan(
      out.indexOf('## Operator Overlay (USER.local.md)'),
    );
  });
  it('merges SOUL.local.md + STANDARDS.local.md as deltas in the Operator Overlays block', () => {
    writeFileSync(join(fixture.home, 'SOUL.local.md'), 'Tone: dry and direct.\n');
    writeFileSync(join(fixture.home, 'STANDARDS.local.md'), 'Require 90% coverage on auth code.\n');
    const out = composeContract('claude', fixture.home);
    expect(out).toContain('# Operator Overlays');
    expect(out).toContain('## Persona Overlay (SOUL.local.md)');
    expect(out).toContain('Tone: dry and direct.');
    expect(out).toContain('## Standards Overlay (STANDARDS.local.md)');
    expect(out).toContain('Require 90% coverage on auth code.');
  });
  it('ignores whitespace-only *.local overlays (no empty overlay section)', () => {
    writeFileSync(join(fixture.home, 'SOUL.local.md'), '   \n\n');
    const out = composeContract('claude', fixture.home);
    expect(out).not.toContain('# Operator Overlays');
  });
  it('selects a different RUNTIME.md per harness', () => {
    expect(composeContract('codex', fixture.home)).toContain('# codex runtime contract');
    expect(composeContract('pi', fixture.home)).toContain('# pi runtime contract');
    expect(composeContract('codex', fixture.home)).not.toContain('# pi runtime contract');
  });
 });
--- a/packages/mosaic/src/commands/fleet.spec.ts
+++ b/packages/mosaic/src/commands/fleet.spec.ts
@@ -14,13 +14,11 @@ import {
  buildEnableLingerCommand,
  buildFleetServiceCommand,
  buildSystemdEnableCommand,
  buildSystemdDisableCommand,
  buildSystemdShowCommand,
  buildTmuxListPanesCommand,
  buildTmuxListSessionsCommand,
  classifySendResult,
  countOrchestrators,
  countEnhancers,
  detectDrift,
  enableFleetUnits,
  FLEET_PROFILES,
@@ -985,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([
@@ -2313,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');
@@ -2511,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
@@ -227,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.
@@ -881,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`,
        );
      }
    });
@@ -1240,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.`);
@@ -1294,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));
@@ -1954,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',
@@ -2005,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
@@ -291,23 +291,12 @@ function buildPrdBlock(): string {
 // ─── Runtime prompt builder ──────────────────────────────────────────────────
-/**
+function buildRuntimePrompt(runtime: RuntimeName): string {
 * Compose the full runtime contract for a harness: the resident-by-value core
 * (CONSTITUTION + AGENTS + USER + TOOLS + runtime) plus operator overlays
 * (`*.local.md` deltas), merged in precedence order so the model gets one
 * pre-merged blob (DESIGN §3.2 / R7). Overlays are injected as deltas by value;
 * base files keep their existing residency (USER injected; SOUL/STANDARDS are
 * load-on-demand, so only their small `.local` deltas are injected here).
 *
 * `mosaicHome` is parameterized for testability; production callers use the
 * module-level default.
 */
 export function composeContract(runtime: RuntimeName, mosaicHome: string = MOSAIC_HOME): string {
  const runtimeContractPaths: Record<RuntimeName, string> = {
-    claude: join(mosaicHome, 'runtime', 'claude', 'RUNTIME.md'),
+    claude: join(MOSAIC_HOME, 'runtime', 'claude', 'RUNTIME.md'),
-    codex: join(mosaicHome, 'runtime', 'codex', 'RUNTIME.md'),
+    codex: join(MOSAIC_HOME, 'runtime', 'codex', 'RUNTIME.md'),
-    opencode: join(mosaicHome, 'runtime', 'opencode', 'RUNTIME.md'),
+    opencode: join(MOSAIC_HOME, 'runtime', 'opencode', 'RUNTIME.md'),
-    pi: join(mosaicHome, 'runtime', 'pi', 'RUNTIME.md'),
+    pi: join(MOSAIC_HOME, 'runtime', 'pi', 'RUNTIME.md'),
  };
  const runtimeFile = runtimeContractPaths[runtime];
@@ -342,55 +331,27 @@ For required push/merge/issue-close/release actions, execute without routine con
 `);
  // CONSTITUTION.md (L0 — the non-negotiable law; lead with it). Tolerant of
-  // pre-constitution installs that have not been re-seeded yet. Injected by
+  // pre-constitution installs that have not been re-seeded yet.
-  // value verbatim so the bare-launch fallback read is byte-equal (R8).
+  const constitution = readOptional(join(MOSAIC_HOME, 'CONSTITUTION.md'));
  const constitution = readOptional(join(mosaicHome, 'CONSTITUTION.md'));
  if (constitution) parts.push(constitution);
  // AGENTS.md
-  parts.push(readFileSync(join(mosaicHome, 'AGENTS.md'), 'utf-8'));
+  parts.push(readFileSync(join(MOSAIC_HOME, 'AGENTS.md'), 'utf-8'));
-  // USER.md (+ USER.local.md operator overlay, appended directly under the
+  // USER.md
-  // profile its base owns).
+  const user = readOptional(join(MOSAIC_HOME, 'USER.md'));
  const user = readOptional(join(mosaicHome, 'USER.md'));
  if (user) parts.push('\n\n# User Profile\n\n' + user);
  const userLocal = readOptional(join(mosaicHome, 'USER.local.md'));
  if (userLocal.trim()) {
    parts.push('\n\n## Operator Overlay (USER.local.md)\n\n' + userLocal);
  }
  // TOOLS.md
-  const tools = readOptional(join(mosaicHome, 'TOOLS.md'));
+  const tools = readOptional(join(MOSAIC_HOME, 'TOOLS.md'));
  if (tools) parts.push('\n\n# Machine Tools\n\n' + tools);
  // Operator overlays whose base layers are load-on-demand (SOUL, STANDARDS):
  // inject only the small `.local` delta by value so the customization reaches
  // the model without re-injecting the full base prose (preserves the byte
  // budget). Absent `.local` files → base-only, automatically (R7 §3.2).
  const overlayBlocks: string[] = [];
  const soulLocal = readOptional(join(mosaicHome, 'SOUL.local.md'));
  if (soulLocal.trim()) {
    overlayBlocks.push('## Persona Overlay (SOUL.local.md)\n\n' + soulLocal.trim());
  }
  const standardsLocal = readOptional(join(mosaicHome, 'STANDARDS.local.md'));
  if (standardsLocal.trim()) {
    overlayBlocks.push('## Standards Overlay (STANDARDS.local.md)\n\n' + standardsLocal.trim());
  }
  if (overlayBlocks.length > 0) {
    parts.push('\n\n# Operator Overlays\n\n' + overlayBlocks.join('\n\n'));
  }
  // Runtime-specific contract
  parts.push('\n\n# Runtime-Specific Contract\n\n' + readFileSync(runtimeFile, 'utf-8'));
  return parts.join('\n');
 }
 /** @deprecated internal alias — use composeContract. Retained for call-site clarity. */
 function buildRuntimePrompt(runtime: RuntimeName): string {
  return composeContract(runtime);
 }
 // ─── Session lock ────────────────────────────────────────────────────────────
 function writeSessionLock(runtime: string): void {
@@ -1015,22 +976,6 @@ export function registerLaunchCommands(program: Command): void {
    launchRuntime(runtime, extraArgs, yolo);
  });
  // compose-contract — emit the composed runtime contract (base + operator
  // overlays) for a harness to stdout, without launching. For inspection,
  // `mosaic doctor`, diffing, and the composer test (R7).
  program
    .command('compose-contract <harness>')
    .description('Print the composed runtime contract (base + *.local overlays) for a harness')
    .action((harness: string) => {
      const valid: RuntimeName[] = ['claude', 'codex', 'opencode', 'pi'];
      if (!valid.includes(harness as RuntimeName)) {
        console.error(`Unknown harness '${harness}'. Expected one of: ${valid.join(', ')}.`);
        process.exitCode = 64;
        return;
      }
      process.stdout.write(composeContract(harness as RuntimeName));
    });
  // Coord (mission orchestrator)
  program
    .command('coord')
--- 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
@@ -1,85 +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 {
  buildReseedCommand,
  buildRelaunchCommands,
  readRosterAgentNames,
  runFrameworkReseed,
 } from './update-checker.js';
 /**
 * F3-m3 / R13: `mosaic update` re-seeds the framework + (opt-in) relaunches
 * durable agents so shipped launcher/runtime changes activate. These cover the
 * pure builders + the missing-installer guard (the exec path is integration).
 */
 describe('buildReseedCommand', () => {
  it('invokes the package install.sh in data-safe sync-only keep mode', () => {
    const out = buildReseedCommand('/pkg/framework', '/home/u/.config/mosaic');
    expect(out.installer).toBe('/pkg/framework/install.sh');
    expect(out.command).toBe('bash /pkg/framework/install.sh');
    expect(out.env).toEqual({
      MOSAIC_SYNC_ONLY: '1',
      MOSAIC_INSTALL_MODE: 'keep',
      MOSAIC_HOME: '/home/u/.config/mosaic',
    });
  });
 });
 describe('buildRelaunchCommands', () => {
  it('builds a systemctl --user restart per agent unit', () => {
    expect(buildRelaunchCommands(['orchestrator', 'coder0'])).toEqual([
      ['systemctl', '--user', 'restart', 'mosaic-agent@orchestrator.service'],
      ['systemctl', '--user', 'restart', 'mosaic-agent@coder0.service'],
    ]);
  });
  it('is empty for an empty roster', () => {
    expect(buildRelaunchCommands([])).toEqual([]);
  });
 });
 describe('readRosterAgentNames', () => {
  let home: string;
  beforeEach(() => {
    home = mkdtempSync(join(tmpdir(), 'mosaic-roster-'));
  });
  afterEach(() => {
    rmSync(home, { recursive: true, force: true });
  });
  it('returns [] when no roster exists', () => {
    expect(readRosterAgentNames(home)).toEqual([]);
  });
  it('extracts agent names from roster.yaml', () => {
    mkdirSync(join(home, 'fleet'), { recursive: true });
    writeFileSync(
      join(home, 'fleet', 'roster.yaml'),
      [
        'version: 1',
        'agents:',
        '  - name: orchestrator',
        '    runtime: pi',
        '  - name: coder0',
        '    runtime: claude',
        '  - name: "reviewer-1"',
        '    runtime: codex',
      ].join('\n') + '\n',
    );
    expect(readRosterAgentNames(home)).toEqual(['orchestrator', 'coder0', 'reviewer-1']);
  });
 });
 describe('runFrameworkReseed', () => {
  it('reports not-ok (not throw) when the installer is absent', () => {
    const missing = mkdtempSync(join(tmpdir(), 'mosaic-noinstaller-'));
    const res = runFrameworkReseed(missing, join(missing, 'home'));
    expect(res.ok).toBe(false);
    expect(res.reason).toContain('installer not found');
    rmSync(missing, { recursive: true, force: true });
  });
 });
--- a/packages/mosaic/src/runtime/update-checker.ts
+++ b/packages/mosaic/src/runtime/update-checker.ts
@@ -16,8 +16,7 @@
 import { execSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // ─── Types ──────────────────────────────────────────────────────────────────
@@ -454,98 +453,6 @@ export function getInstallAllCommand(outdated: PackageUpdateResult[]): string {
  return `npm i -g ${pkgs.join(' ')}`;
 }
 // ─── Post-update framework re-seed + agent relaunch (F3-m3 / R13) ─────────────
 //
 // `mosaic update` installs the new npm CLI but, on its own, leaves the framework
 // files in ~/.config/mosaic/ stale — so shipped launcher/runtime changes (e.g.
 // the agent-name export + native heartbeat) never ACTIVATE until a re-seed.
 // These helpers run the package's own install.sh in sync-only mode (the P4
 // data-safe reconcile: framework-owned overwrite + backup-once; SOUL/USER/
 // *.local/credentials preserved) and, opt-in, relaunch durable agents.
 /** Resolve the framework/ directory bundled in the installed package. */
 export function resolveBundledFrameworkRoot(): string {
  // dist/runtime/update-checker.js → ../../framework (package files: dist + framework)
  return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'framework');
 }
 export const FRAMEWORK_RESEED_PACKAGE = PKG;
 /**
 * Build the framework re-seed invocation: the package's install.sh in
 * sync-only mode (file phase only — no environment-touching post-install),
 * keep mode (never overwrite user files). Returned as data so it is unit
 * testable; `runFrameworkReseed` executes it.
 */
 export function buildReseedCommand(
  frameworkRoot: string,
  mosaicHome: string,
 ): { installer: string; command: string; env: Record<string, string> } {
  const installer = join(frameworkRoot, 'install.sh');
  return {
    installer,
    command: `bash ${installer}`,
    env: {
      MOSAIC_SYNC_ONLY: '1',
      MOSAIC_INSTALL_MODE: 'keep',
      MOSAIC_HOME: mosaicHome,
    },
  };
 }
 /**
 * Re-seed the framework from the freshly-installed package. Returns a result
 * describing what happened (so callers can message + decide on relaunch).
 * Best-effort: a missing installer or a non-zero exit is reported, not thrown.
 */
 export function runFrameworkReseed(
  frameworkRoot = resolveBundledFrameworkRoot(),
  mosaicHome = join(homedir(), '.config', 'mosaic'),
 ): { ok: boolean; reason?: string } {
  const { installer, command, env } = buildReseedCommand(frameworkRoot, mosaicHome);
  if (!existsSync(installer)) {
    return { ok: false, reason: `installer not found: ${installer}` };
  }
  try {
    execSync(command, { stdio: 'inherit', env: { ...process.env, ...env }, timeout: 120_000 });
    return { ok: true };
  } catch (err) {
    return { ok: false, reason: err instanceof Error ? err.message : String(err) };
  }
 }
 /**
 * Best-effort parse of the fleet roster for agent names (used to relaunch
 * durable agents after a re-seed). Returns [] when no roster exists.
 */
 export function readRosterAgentNames(mosaicHome = join(homedir(), '.config', 'mosaic')): string[] {
  const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
  if (!existsSync(rosterPath)) return [];
  let text: string;
  try {
    text = readFileSync(rosterPath, 'utf-8');
  } catch {
    return [];
  }
  // Roster agents are listed as `- name: <id>` entries under `agents:`.
  const names: string[] = [];
  for (const line of text.split('\n')) {
    const m = line.match(/^\s*-?\s*name:\s*["']?([A-Za-z0-9._-]+)["']?\s*$/);
    if (m && m[1]) names.push(m[1]);
  }
  return names;
 }
 /** Build the per-agent systemd relaunch commands (drain+relaunch via restart). */
 export function buildRelaunchCommands(agentNames: string[]): string[][] {
  return agentNames.map((name) => [
    'systemctl',
    '--user',
    'restart',
    `mosaic-agent@${name}.service`,
  ]);
 }
 /**
 * Format a table showing all packages with their current/latest versions.
 */