feat(fleet): F4 Phase 1 — orchestrator chat connector abstraction + Matrix design (#616 )

From the north-star (#613) orchestrator-chat-connector decision: make the orchestrator's chat channel a pluggable, user-chosen connector (tmux | discord | matrix peers) and add Matrix (local homeserver) — starting with the small uniform abstraction so connectors drop in without touching fleet core. Phase 1 (this PR — design + scaffold): - src/fleet/connectors/types.ts: OrchestratorConnector interface (send / subscribe / health per the Lead's spec) + message/config types; thread-aware via optional threadId so Matrix threads + the future first-party Mosaic Discord plugin fit without an interface change. 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 (gateway pattern), never the roster. - docs/fleet/f4-matrix-connector.md: interface, config, Matrix client-server API mapping, Conduit-default local homeserver, phasing, back-compat. Self-contained connectors/ module — NO fleet.ts changes, so independent of the in-flight stacked fleet-config PR (#615). Verified: 7 connector tests green; tsc/eslint/prettier/sanitize clean; schema valid JSON. Refs #616, #613 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83
feat(fleet): enhancer role + two-agent floor (orchestrator + enhancer) (#615 )
2026-06-22 08:17:23 -05:00 · 2026-06-22 13:15:59 +00:00 · 2026-06-22 13:15:05 +00:00 · 2026-06-22 13:14:31 +00:00 · 2026-06-22 08:12:58 +00:00 · 2026-06-22 03:34:05 +00:00
28 changed files with 1539 additions and 26 deletions
--- a/.woodpecker/ci.yml
+++ b/.woodpecker/ci.yml
@@ -25,12 +25,10 @@ steps:
    commands:
      - apk add --no-cache bash
      - bash packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh
-      # L0 resident-token budget: keep the Constitution + dispatcher small.
+      # Resident line-count ceiling over framework-owned resident files
-      - |
+      # (Constitution + dispatcher + each RUNTIME.md slice). See DESIGN §7 / R9.
-        for f in CONSTITUTION.md AGENTS.md; do
+      - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh --self-test
-          n=$(wc -l < "packages/mosaic/framework/defaults/$f")
+      - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh
          if [ "$n" -gt 120 ]; then echo "L0 budget exceeded: defaults/$f is $n lines (max 120)"; exit 1; fi
        done
  typecheck:
    image: *node_image
--- a/.woodpecker/publish.yml
+++ b/.woodpecker/publish.yml
@@ -4,6 +4,23 @@
 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]
@@ -26,6 +43,15 @@ 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
@@ -91,6 +117,7 @@ steps:
  build-gateway:
    image: gcr.io/kaniko-project/executor:debug
    when: *image_build_when
    environment:
      REGISTRY_USER:
        from_secret: gitea_username
@@ -116,6 +143,7 @@ steps:
  build-appservice:
    image: gcr.io/kaniko-project/executor:debug
    when: *image_build_when
    environment:
      REGISTRY_USER:
        from_secret: gitea_username
@@ -141,6 +169,7 @@ 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
@@ -48,6 +48,25 @@ Active workstream is **W1 — Federation v1**. Workers should:
 ## P5 — Overlay composer + cross-harness (#604) — feat/p5-overlay-composer
- Status: in progress. R7 (compose-contract) + R8 (cross-harness) + R9 (composer test).
+- 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.
- Defer to P6: CONTRIBUTING.md + compliance matrix; line-count CI ceiling; aiguide; alpha tag.
+
 ## 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.
 ## 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 done (abstraction + scaffold). Connector interface (send/subscribe/health) + registry + roster connector schema + design doc; tmux default/back-compat; matrix/discord factories are Phase 2. 7 tests green; no fleet.ts changes. Detail: scratchpads/f4-matrix-connector.md.
--- a/docs/design/framework-constitution/ALPHA-DOD.md
+++ b/docs/design/framework-constitution/ALPHA-DOD.md
@@ -0,0 +1,75 @@
 # Constitution Alpha — Definition-of-Done checklist + release notes
 Drafted for the `v0.0.39-alpha` tag (Lead cuts after P5 #605 → P6 #607 → aiguide #8 merge).
 Maps every DoD §8 acceptance criterion to its merged evidence. Legend:
 **✅ merged on main** · **⏳ review-ready PR (pending merge)** · **🔲 Lead action**.
 ## DoD §8 green-checklist
 | #   | Acceptance criterion (DESIGN §8)                                                                       | Status | Evidence / PR     |
 | --- | ------------------------------------------------------------------------------------------------------ | ------ | ----------------- |
 | 1   | MIT `LICENSE` (root + framework) + `"license":"MIT"` in package.json                                   | ✅     | P0 #570           |
 | 2   | Three credential-path sites + hook URL fast-failed (no private paths in `*.sh`/hooks)                  | ✅     | P0 #570           |
 | 3   | `verify-sanitized.sh` (two-class, `*.sh`+`*.md`, self-tested) wired **blocking** in CI                 | ✅     | P1 #572           |
 | 4   | Operator data purged from the full set (guides / tools / init-generator)                               | ✅     | P2 #572           |
 | 5   | `rails/`→`tools/` in **both** template families                                                        | ✅     | P2 #572           |
 | 6   | `jarvis-loop.json` deleted; `defaults/SOUL.md` → **neutral sanitized persona** (Q10 decision)          | ✅     | P2 #572           |
 | 7   | `CONSTITUTION.md` extracted (gates one place, capability-verb, §1.4 split, no false "already loaded")  | ✅     | P3 #575 / #577    |
 | 8   | `AGENTS.md`/`STANDARDS.md` out of `PRESERVE_PATHS` + seed-semantics → overwrite in **both** installers | ✅     | P4 #590           |
 | 9   | Snapshot + v2→v3 migration moving user edits to `.local`/`.bak`; `FRAMEWORK_VERSION=3`                 | ✅     | P4 #590 / #593    |
 | 10  | `mosaic-init --non-interactive` fail-closed persona                                                    | ✅     | P4 #590           |
 | 11  | **5-fixture migration matrix** green against **both** installers asserting **injected bytes**          | ✅     | P4 #590 / #593    |
 | 12  | `compose-contract` built + composer unit test (per-tier anchor + Tier-3 byte-equality)                 | ⏳     | P5 #605           |
 | 13  | Resident line-count ceiling enforced (framework-owned resident files)                                  | ⏳     | P6 #607           |
 | 14  | `CONTRIBUTING.md` + harness×gate compliance matrix                                                     | ⏳     | P6 #607           |
 | 15  | `aiguide` reconciled with the Constitution                                                             | ⏳     | aiguide #8        |
 | 16  | Each phase PR CI-green; alpha tag pushed + Gitea release published                                     | 🔲     | Lead (post-merge) |
 **Note on #6:** the DoD's literal "delete `defaults/SOUL.md`" was superseded by the resolved
 **Q10** decision — ship a _neutral, operator-agnostic_ example persona instead of deleting it. Main
 carries the sanitized 2.6 KB neutral SOUL.md ("Mosaic agent", no operator identity); the sanitization
 gate confirms it is PII-clean. Criterion met in spirit (no operator persona leaks) via the better option.
 **Gate to flip 12–14 → ✅:** merge P5 #605 → P6 #607 (rebase auto-drops the dup format fix
 `adc7df2`/`9f6da92`) → aiguide #8, with `ci.yml` terminal-green on the merged head.
 ---
 ## Release notes — `v0.0.39-alpha` (Mosaic Framework Constitution, alpha)
 ### Mosaic Framework Constitution — Alpha
 This release makes the Mosaic framework a **safe-to-open-source, fork-and-customize agent
 operating layer**. It separates the non-negotiable law from operator identity, makes
 customization survive upgrades, and wires the guarantees into CI.
 **Highlights**
 - **Constitution (L0).** The hard gates now live in one place — `CONSTITUTION.md` — authored in
  capability verbs, with a thin `AGENTS.md` dispatcher that references the law instead of restating
  it. Governance model in `constitution/LAYER-MODEL.md`.
 - **Public & sanitized.** MIT-licensed; all operator identity, private paths, and credential sites
  removed from shipped files. A self-tested `verify-sanitized.sh` gate (two rule classes) runs
  **blocking** in CI so re-contamination can't merge.
 - **Upgrade-safe customization.** Framework-owned files overwrite cleanly on upgrade while
  `SOUL.md`/`USER.md`/`*.local.md`/`credentials` are preserved. The v2→v3 migration snapshots first
  and moves any user-edited `AGENTS.md`/`STANDARDS.md` to `.pre-constitution.bak`/`.local.md` —
  never silently lost. Verified by a 5-fixture matrix across **both** installers.
 - **Operator overlays.** `mosaic compose-contract <harness>` merges your `*.local.md` deltas into
  the contract per harness, so customization reaches the model as one pre-merged blob.
 - **Cross-harness.** Single L0 source referenced (never restated) by Claude / Codex / OpenCode / Pi;
  tiered injection with a byte-equal Tier-3 fallback read.
 - **Guardrails in CI.** Resident line-count ceiling over framework-owned resident files; composer
  unit test; sanitization gate — all blocking.
 - **Docs.** `CONTRIBUTING.md` with the layer model, dual-installer parity rule, and a harness×gate
  **compliance matrix** (the Codex/OpenCode/Pi hook-parity gap is tracked for v2).
 **Known limitations (accepted, documented in `CONTRIBUTING.md` §9)**
 - Bare launches that bypass `mosaic` get base contracts only (no `*.local` overlays) and are not
  drift-checked by `mosaic doctor` — mitigated by the unconditional Tier-3 self-load + a nudge.
 - Codex/OpenCode/Pi mechanical hook parity, `policy/*.md` composition, and live-launch cross-harness
  verification are **v2**.
 **Phase lineage:** P0 #570 · P1+P2 #572 · P3 #575/#577 · P4 #590/#593 · P5 #605 · P6 #607 ·
 aiguide #8 (umbrella #542).
--- a/docs/fleet/f4-matrix-connector.md
+++ b/docs/fleet/f4-matrix-connector.md
@@ -0,0 +1,92 @@
 # 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,6 +73,37 @@ 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:
@@ -102,7 +133,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+reviewer; ephemeral workers per lane)          | planned |
+| 3 — Real runtimes      | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: **orchestrator + enhancer**; 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 |
@@ -121,6 +152,28 @@ 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
@@ -0,0 +1,29 @@
 # 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
@@ -0,0 +1,19 @@
 # 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.
--- a/docs/scratchpads/fleet-enhancer-floor.md
+++ b/docs/scratchpads/fleet-enhancer-floor.md
@@ -0,0 +1,26 @@
 # 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
@@ -0,0 +1,20 @@
 # 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/p6-docs-compliance-alpha.md
+++ b/docs/scratchpads/p6-docs-compliance-alpha.md
@@ -0,0 +1,29 @@
 # P6 — Docs, compliance matrix, alpha tag (constitution capstone)
 - **Issue:** #606 · **Branch:** `feat/p6-docs-compliance-alpha` · **Lineage:** #542
 - **Requirements:** R9 (resident line-count ceiling) + R10 (CONTRIBUTING + compliance matrix + aiguide) + alpha tag
 ## Delivered (in-repo)
 - `framework/CONTRIBUTING.md` — layer model, operator-hygiene/PII prohibition, dedup rule, resident
  budget, **dual-installer parity rule**, adding-a-harness, re-contamination rule, **harness×gate
  compliance matrix** (hook-parity gap marked ⚠️ tracked-v2), known-limitations (§9 residuals), PR checklist.
 - `framework/tools/quality/scripts/check-resident-budget.sh` — line-count ceiling over framework-owned
  resident files (CONSTITUTION + AGENTS + each runtime/\*/RUNTIME.md); `--self-test`; replaces the crude
  inline ci.yml loop. Wired blocking in `.woodpecker/ci.yml`.
 - Composer unit test (R9) already runs via `pnpm test`; `verify-sanitized.sh` (P1) already wired.
 ## Verification
 - Sanitization gate green (CONTRIBUTING is operator-neutral). Resident-budget self-test + real run green.
 - prettier clean. Current resident counts: CONSTITUTION 96, AGENTS 83, RUNTIME max 75 — all < ceiling.
 ## Remaining
 - [ ] `aiguide` reconcile (separate repo `~/src/aiguide` / mosaicstack/aiguide) — consistency pass vs Constitution.
 - [ ] Alpha tag `mosaic-vX.Y.Z-alpha` — propose version; Lead cuts after full DoD §8 green + all phases merged.
 ## Notes
 - Alpha DoD (DESIGN §8): all phases P0–P6 merged + CI green. P5 (#605) pending merge after 0.0.38 publish.
 - Hook parity (codex/opencode/pi) = tracked v2 gap, documented in the matrix, not closed here.
--- a/packages/mosaic/framework/CONTRIBUTING.md
+++ b/packages/mosaic/framework/CONTRIBUTING.md
@@ -0,0 +1,185 @@
 # Contributing to the Mosaic Framework
 The Mosaic framework is the open-source agent-operating layer that deploys to
 `~/.config/mosaic/`. It is designed to be **forked and customized** — but the
 shared core must stay operator-neutral, deduplicated, and upgrade-safe. This
 guide is the contract for changing framework-owned files.
 > Governance model and layer rationale: `constitution/LAYER-MODEL.md` (source-only).
 > Requirements & phase history: `docs/design/framework-constitution/`.
 ---
 ## 1. The layer model (where does my change go?)
 | Layer  | What                                                          | Owner            | On upgrade                              | File(s)                                      |
 | ------ | ------------------------------------------------------------- | ---------------- | --------------------------------------- | -------------------------------------------- |
 | **L0** | Constitution — the non-negotiable law (hard gates)            | Framework        | **Overwritten**                         | `CONSTITUTION.md`                            |
 | **L1** | Standards & guides — how to do the work well                  | Framework        | Overwritten; user delta → `*.local.md`  | `STANDARDS.md`, `guides/*`                   |
 | **L2** | Persona (SOUL) — agent name, tone, role                       | User (init)      | **Never overwritten**                   | `SOUL.md` (+ optional `SOUL.local.md`)       |
 | **L3** | Operator (USER) — human identity, prefs, policy               | User (init)      | **Never overwritten**                   | `USER.md` (+ optional `USER.local.md`)       |
 | **L4** | Project / runtime mechanism — per-repo deltas; harness wiring | Repo / framework | Project user-owned; runtime overwritten | `<repo>/AGENTS.md`, `runtime/<h>/RUNTIME.md` |
 **The one sentence a user can rely on:** edit `SOUL.md` / `USER.md` and the
 `.local.md` overlays — they survive every upgrade. To change framework behavior,
 add a `.local.md` overlay; never edit a framework-owned file in place.
 ---
 ## 2. Operator hygiene (PII / secrets prohibition) — **blocking**
 Framework-owned files ship publicly. They **must not** contain:
 - Operator or personal identity (names, handles, pronouns, accessibility notes).
 - Private `$HOME` paths, private hostnames, or domains.
 - Secrets, tokens, or credentials (use `~/.config/mosaic/credentials.json`; the
  hook URL soft-degrades via `${OPENBRAIN_URL}`).
 This is enforced by `tools/quality/scripts/verify-sanitized.sh`, wired **blocking**
 in CI (`.woodpecker/ci.yml`). It runs two rule classes: structural (private-`$HOME`
 defaults, dead paths, unrendered tokens) and a labeled current-contaminant denylist.
 Run it locally before pushing:
 ```bash
 bash packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh
 ```
 Operator-specific behavior belongs in **your** `SOUL.md`/`USER.md`/`*.local.md`,
 never in the shared core. (The "framework-PR firewall" in `CONSTITUTION.md` §4
 states this as law for agents opening framework PRs.)
 ---
 ## 3. Dedup rule — one source, everyone references it
 Hard gates live in **`CONSTITUTION.md` (L0) only**. `AGENTS.md`, `STANDARDS.md`,
 and every `runtime/<h>/RUNTIME.md` **reference** the law — they never restate it.
 Restating a gate is a defect: it creates two sources that drift. If you find a
 gate duplicated outside L0, delete the copy and point to L0.
 `AGENTS.md` is a thin dispatcher (load order + guide router + the tier-aware
 self-load). Keep it that way; new procedure goes in `guides/*` (on-demand), not
 in the resident core.
 ---
 ## 4. Resident line-count ceiling — **blocking**
 The framework-owned files injected by value (`CONSTITUTION.md`, `AGENTS.md`, each
 `runtime/<h>/RUNTIME.md`) are budgeted by **line count** — never by word count
 (a word cap forces paraphrasing the law, the exact drift vector we removed).
 ```bash
 bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh
 ```
 Wired blocking in CI. Gate **wording** stays intact; if a file legitimately needs
 more lines, raise its ceiling in the script deliberately (in the same PR, with
 rationale). The per-harness _total_ resident prompt (which also sums the user's
 `SOUL.md`/`USER.md`) is a `mosaic doctor` runtime advisory — CI cannot see user
 files, so it is out of CI scope by design (DESIGN §7).
 ---
 ## 5. Dual-installer parity rule
 Two installers seed and migrate `~/.config/mosaic/`:
 - **`framework/install.sh`** (bash) — the canonical installer.
 - **`packages/mosaic/src/config/file-adapter.ts`** (TS) — the wizard path.
 **Any change to seed lists, overwrite/preserve semantics, or migration MUST land
 in BOTH**, validated by the **shared fixture suite**:
 - `framework/tools/quality/scripts/test-install-migration.sh` (bash matrix)
 - `packages/mosaic/src/config/file-adapter.test.ts` (vitest)
 Both assert the same behavior: framework-owned files overwrite (backup-once to
 `*.pre-constitution.bak`); user-seeded files seed-if-absent; `SOUL.md`/`USER.md`/
 `*.local.md`/`credentials` are preserved. A change in one installer without the
 other (and its fixtures) is incomplete.
 ---
 ## 6. Adding a harness adapter
 A harness (runtime) is wired by:
 1. `runtime/<h>/RUNTIME.md` — **mechanism only** (subagent syntax, hook/MCP wiring,
   injection method). No restated gates (see §3).
 2. Launcher emission in `src/commands/launch.ts` — how the composed contract reaches
   the harness (system-prompt append vs. instructions file). Add the harness to the
   `RuntimeName` union and the runtime-path map.
 3. `mosaic compose-contract <harness>` works automatically once the runtime path
   exists (it composes base + `*.local.md` overlays for that harness).
 Then add a row to the compliance matrix (§8) and mark which gates are mechanical
 vs. resident-only for the new harness.
 ---
 ## 7. Re-contamination rule
 A green sanitization gate is not permanent. Before every PR:
 - Do not reintroduce operator identity, private paths, or secrets (§2).
 - Do not copy a gate out of L0 (§3).
 - Do not add an unrendered template token or a dead path to a shipped file.
 If `verify-sanitized.sh` goes red, that diff **is** your worklist — fix it, don't
 suppress it.
 ---
 ## 8. Harness × gate compliance matrix
 How each gate is enforced per harness. **Mechanical** = a hook/CI check the agent
 cannot bypass. **Resident** = injected contract prose (strong, but not a hard stop).
 **CI** = repo-side, harness-independent.
 | Gate / mechanism                              | Claude      | Codex            | OpenCode         | Pi               |
 | --------------------------------------------- | ----------- | ---------------- | ---------------- | ---------------- |
 | Contract injection (resident-by-value)        | append SP   | instructions     | `AGENTS.md`      | append SP        |
 | Operator overlays (`*.local`, composed)       | ✅          | ✅               | ✅               | ✅               |
 | Bare-launch self-load (Tier-3, read L0)       | ✅          | ✅               | ✅               | ✅               |
 | Sanitization (no PII) — `verify-sanitized`    | CI ✅       | CI ✅            | CI ✅            | CI ✅            |
 | Resident budget ceiling                       | CI ✅       | CI ✅            | CI ✅            | CI ✅            |
 | Migration parity (5-fixture, both installers) | CI ✅       | CI ✅            | CI ✅            | CI ✅            |
 | `no-memory-write` (PreToolUse hook)           | **mech ✅** | resident-only ⚠️ | resident-only ⚠️ | resident-only ⚠️ |
 | QA / typecheck (PostToolUse hooks)            | **mech ✅** | resident-only ⚠️ | resident-only ⚠️ | resident-only ⚠️ |
 | Native heartbeat (fleet `ps` model/status)    | sidecar     | sidecar          | sidecar          | **native ✅**    |
 ⚠️ **Hook-parity gap (tracked, v2):** the mechanical PreToolUse/PostToolUse hooks
 exist for Claude Code only. On Codex/OpenCode/Pi those gates are currently enforced
 by the resident contract + CI, not by a per-tool hook. Closing hook parity is a
 **v2** item, not part of this alpha.
 ---
 ## 9. Known limitations (accepted residual risks)
 These are accepted with rationale (DESIGN §9); they are documented, not bugs:
 - **Bare-launch overlays are base-only.** A harness started without `mosaic` never
  ran the composer, so `*.local.md` overlays are not applied. Mitigated by the
  unconditional Tier-3 self-load + the `mosaic doctor` nudge in `AGENTS.md`; not
  eliminated. Relaunch via `mosaic <harness>` to pick up overlays.
 - **Bare-launch drift is undetected by `mosaic doctor`** (the launcher never ran).
 - **Codex/OpenCode/Pi hook parity** is a tracked v2 gap (§8).
 - **Live-launch cross-harness verification** is v2; the alpha verifies the composer
  by unit test (per-tier anchor + Tier-3 byte-equality), not a live launch.
 **Deferred to v2 (explicit):** `constitution/` deploy directory; capability JSON
 adapters; 3-way merge; `policy/*.md` composition; per-layer version stamps as a
 migration driver.
 ---
 ## 10. PR checklist
 - [ ] No operator identity / private paths / secrets (`verify-sanitized.sh` green).
 - [ ] No gate restated outside `CONSTITUTION.md` (§3).
 - [ ] Resident budget green (`check-resident-budget.sh`).
 - [ ] Seed/migration changes landed in **both** installers + shared fixtures (§5).
 - [ ] New harness → compliance-matrix row updated (§8).
 - [ ] `prettier --check` + `pnpm lint` + `pnpm typecheck` + `pnpm test` green.
--- a/packages/mosaic/framework/fleet/examples/coding.yaml
+++ b/packages/mosaic/framework/fleet/examples/coding.yaml
@@ -15,6 +15,10 @@ 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,6 +15,10 @@ 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,6 +15,10 @@ 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,6 +15,10 @@ 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
@@ -0,0 +1,41 @@
 # 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,6 +113,35 @@
          }
        }
      }
    },
    "connector": {
      "description": "Orchestrator chat connector (F4). Optional — absent means tmux (back-compat). Secrets (access/bot tokens) come from the environment, never this file.",
      "type": "object",
      "additionalProperties": false,
      "required": ["kind"],
      "properties": {
        "kind": {
          "enum": ["tmux", "discord", "matrix"]
        },
        "matrix": {
          "type": "object",
          "additionalProperties": false,
          "required": ["homeserver_url", "user_id", "room_id"],
          "properties": {
            "homeserver_url": { "type": "string" },
            "user_id": { "type": "string" },
            "room_id": { "type": "string" }
          }
        },
        "discord": {
          "type": "object",
          "additionalProperties": false,
          "required": ["channel_id"],
          "properties": {
            "channel_id": { "type": "string" }
          }
        }
      }
    }
  }
 }
--- a/packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh
+++ b/packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh
@@ -0,0 +1,93 @@
 #!/usr/bin/env bash
 # check-resident-budget.sh — resident line-count ceiling (R9 / DESIGN §7).
 #
 # Budgets the *container* (line count) of the framework-owned files that are
 # injected into every agent's context by value — the Constitution (L0), the
 # AGENTS dispatcher, and each runtime RUNTIME.md slice. Gate *wording* is never
 # capped (a word cap forces paraphrasing law — the exact drift vector P3 killed);
 # only the file's line count is bounded, so prose creep is caught in review.
 #
 # This is the CI-enforceable half of the budget. The per-harness *total* resident
 # prompt (which also includes user-generated SOUL.md/USER.md and the per-tier
 # slice) is summed by `mosaic doctor` as a runtime advisory — CI cannot see user
 # files, so it is deliberately out of scope here (DESIGN §7).
 #
 # Usage:  check-resident-budget.sh [--self-test]
 # Exit:   0 = all within budget · 1 = a file exceeds its ceiling · 2 = self-test failed
 set -uo pipefail
 FW="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)" # packages/mosaic/framework
 # Per-file ceilings (lines). Headroom above current counts; tighten as files settle.
 # Format: "<relative-path>:<max-lines>"
 CEILINGS=(
  "defaults/CONSTITUTION.md:120"
  "defaults/AGENTS.md:120"
  "runtime/claude/RUNTIME.md:90"
  "runtime/codex/RUNTIME.md:90"
  "runtime/opencode/RUNTIME.md:90"
  "runtime/pi/RUNTIME.md:90"
 )
 # check_file <abs-path> <max> → echoes "<n>"; returns 0 if n<=max, 1 otherwise.
 check_file() {
  local path="$1" max="$2" n
  n=$(wc -l <"$path" 2>/dev/null || echo 0)
  n=$((n + 0))
  echo "$n"
  [ "$n" -le "$max" ]
 }
 run_budget() {
  local fail=0 rel max abs n
  printf '%-32s %8s %8s   %s\n' "FILE" "LINES" "CEILING" "STATUS"
  for entry in "${CEILINGS[@]}"; do
    rel="${entry%%:*}"
    max="${entry##*:}"
    abs="$FW/$rel"
    if [ ! -f "$abs" ]; then
      printf '%-32s %8s %8s   %s\n' "$rel" "-" "$max" "MISSING"
      fail=1
      continue
    fi
    n=$(check_file "$abs" "$max")
    if [ "$n" -le "$max" ]; then
      printf '%-32s %8s %8s   %s\n' "$rel" "$n" "$max" "ok"
    else
      printf '%-32s %8s %8s   %s\n' "$rel" "$n" "$max" "OVER BUDGET"
      fail=1
    fi
  done
  return "$fail"
 }
 self_test() {
  local tmp rc
  tmp=$(mktemp)
  # 3 lines, ceiling 5 → within budget (rc 0)
  printf 'a\nb\nc\n' >"$tmp"
  check_file "$tmp" 5 >/dev/null
  rc=$?
  if [ "$rc" -ne 0 ]; then echo "self-test FAIL: under-budget file flagged"; rm -f "$tmp"; return 2; fi
  # 6 lines, ceiling 5 → over budget (rc 1)
  printf 'a\nb\nc\nd\ne\nf\n' >"$tmp"
  check_file "$tmp" 5 >/dev/null
  rc=$?
  if [ "$rc" -ne 1 ]; then echo "self-test FAIL: over-budget file not flagged"; rm -f "$tmp"; return 2; fi
  rm -f "$tmp"
  echo "self-test OK"
  return 0
 }
 if [ "${1:-}" = "--self-test" ]; then
  self_test
  exit $?
 fi
 if run_budget; then
  echo "Resident budget: all framework-owned resident files within ceiling."
  exit 0
 else
  echo "Resident budget EXCEEDED — trim prose or raise the ceiling deliberately (see DESIGN §7)." >&2
  exit 1
 fi
--- a/packages/mosaic/package.json
+++ b/packages/mosaic/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@mosaicstack/mosaic",
-  "version": "0.0.37",
+  "version": "0.0.39",
  "repository": {
    "type": "git",
    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
--- a/packages/mosaic/src/cli.ts
+++ b/packages/mosaic/src/cli.ts
@@ -26,6 +26,10 @@ 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';
@@ -404,7 +408,12 @@ program
  .command('update')
  .description('Check for and install Mosaic CLI updates')
  .option('--check', 'Check only, do not install')
-  .action(async (opts: { check?: boolean }) => {
+  .option(
    '--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');
@@ -442,6 +451,51 @@ 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/fleet.spec.ts
+++ b/packages/mosaic/src/commands/fleet.spec.ts
@@ -14,11 +14,13 @@ import {
  buildEnableLingerCommand,
  buildFleetServiceCommand,
  buildSystemdEnableCommand,
  buildSystemdDisableCommand,
  buildSystemdShowCommand,
  buildTmuxListPanesCommand,
  buildTmuxListSessionsCommand,
  classifySendResult,
  countOrchestrators,
  countEnhancers,
  detectDrift,
  enableFleetUnits,
  FLEET_PROFILES,
@@ -983,6 +985,129 @@ 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([
@@ -2188,47 +2313,63 @@ describe('fleet preset rosters', () => {
    },
  );
-  it('general preset: orchestrator + one generalist worker', async () => {
+  it('general preset: orchestrator + enhancer + one generalist worker', async () => {
    const roster = await loadFleetRoster(join(examplesDir, 'general.yaml'));
-    expect(roster.agents.map((a) => a.name)).toEqual(['orchestrator', 'generalist']);
+    expect(roster.agents.map((a) => a.name)).toEqual(['orchestrator', 'enhancer', '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 + coder0 + coder1 + reviewer', async () => {
+  it('coding preset: orchestrator + enhancer + 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 + researcher0 + researcher1 + analyst', async () => {
+  it('research preset: orchestrator + enhancer + 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 + coder0 + researcher0 + reviewer', async () => {
+  it('hybrid preset: orchestrator + enhancer + 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`));
-      const workers = roster.agents.filter((a) => a.name !== 'orchestrator');
+      // Core agents (orchestrator + enhancer) run claude; only ephemeral workers are pi.
      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');
@@ -2370,6 +2511,43 @@ 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,6 +227,15 @@ 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.
@@ -872,20 +881,33 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
      await mkdir(dirname(destination), { recursive: true });
      await writeFile(destination, content);
-      // Validate: exactly one orchestrator required (R5) — friendly summary on success.
+      // Guarantee the two-agent floor: exactly one orchestrator AND at least
      // 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);
-      if (orchCount !== 1) {
+      const enhancerCount = countEnhancers(written);
-        process.stderr.write(
+      if (profile === 'minimal') {
          `Warning: fleet roster at ${destination} has ${orchCount} orchestrator agent(s) (expected exactly 1).\n`,
        );
        console.log(
-          `Initialized ${profile} fleet: ${written.agents.length} agent(s). Next: mosaic fleet install`,
+          `Initialized ${profile} fleet: ${written.agents.length} agent(s) (no orchestrator). 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;
+        const workerCount = written.agents.length - 1 - enhancerCount;
        console.log(
-          `Initialized ${profile} fleet: 1 orchestrator + ${workerCount} agent(s). Next: mosaic fleet install`,
+          `Initialized ${profile} fleet: 1 orchestrator + ${enhancerCount} enhancer(s) + ` +
            `${workerCount} worker(s). Next: mosaic fleet install`,
        );
      }
    });
@@ -1218,6 +1240,24 @@ 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.`);
@@ -1254,6 +1294,26 @@ 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));
@@ -1894,6 +1954,15 @@ 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',
@@ -1936,6 +2005,15 @@ 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/fleet/connectors/registry.spec.ts
+++ b/packages/mosaic/src/fleet/connectors/registry.spec.ts
@@ -0,0 +1,85 @@
 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
@@ -0,0 +1,76 @@
 /**
 * 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
@@ -0,0 +1,111 @@
 /**
 * 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
@@ -0,0 +1,85 @@
 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,7 +16,8 @@
 import { execSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // ─── Types ──────────────────────────────────────────────────────────────────
@@ -453,6 +454,98 @@ 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.
 */
Author	SHA1	Message	Date
Jason Woltje	c6735d9949	feat(fleet): F4 Phase 1 — orchestrator chat connector abstraction + Matrix design (#616 ) Some checks are pending ci/woodpecker/push/ci Pipeline is running Details ci/woodpecker/pr/ci Pipeline is running Details From the north-star (#613) orchestrator-chat-connector decision: make the orchestrator's chat channel a pluggable, user-chosen connector (tmux \| discord \| matrix peers) and add Matrix (local homeserver) — starting with the small uniform abstraction so connectors drop in without touching fleet core. Phase 1 (this PR — design + scaffold): - src/fleet/connectors/types.ts: OrchestratorConnector interface (send / subscribe / health per the Lead's spec) + message/config types; thread-aware via optional threadId so Matrix threads + the future first-party Mosaic Discord plugin fit without an interface change. 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 (gateway pattern), never the roster. - docs/fleet/f4-matrix-connector.md: interface, config, Matrix client-server API mapping, Conduit-default local homeserver, phasing, back-compat. Self-contained connectors/ module — NO fleet.ts changes, so independent of the in-flight stacked fleet-config PR (#615). Verified: 7 connector tests green; tsc/eslint/prettier/sanitize clean; schema valid JSON. Refs #616, #613 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83	2026-06-22 08:17:23 -05:00
Jason Woltje	2bf66136e4	feat(fleet): enhancer role + two-agent floor (orchestrator + enhancer) (#615 ) Some checks are pending ci/woodpecker/push/ci Pipeline is running Details ci/woodpecker/push/publish Pipeline is running Details Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>	2026-06-22 13:15:59 +00:00
jason.woltje	4434c3c481	docs(fleet): orchestrator+enhancer two-agent floor + role library + Discord plugin north-star (#613 ) Some checks failed ci/woodpecker/push/publish Pipeline was canceled Details ci/woodpecker/push/ci Pipeline was canceled Details	2026-06-22 13:15:05 +00:00
Jason Woltje	dd0a0d38c6	ci(publish): gate kaniko image builds + publish on changed paths (CI throughput) (#619 ) Some checks failed ci/woodpecker/push/publish Pipeline was canceled Details ci/woodpecker/push/ci Pipeline was canceled Details Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>	2026-06-22 13:14:31 +00:00
Jason Woltje	d46ac40890	fix(fleet): boot-survival symmetry — disable-on-remove + add-enable + init-R5 (#612 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>	2026-06-22 08:12:58 +00:00
Jason Woltje	8ddd48c843	feat(mosaic): mosaic update re-seeds framework + relaunches agents (R13) (#610 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>	2026-06-22 03:34:05 +00:00
Jason Woltje	528700ceea	feat(framework): P6 — docs + compliance matrix + resident-budget CI (#607 ) Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was canceled Details ci/woodpecker/tag/publish Pipeline was successful Details Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>	2026-06-22 02:20:35 +00:00
jason.woltje	32f4215461	chore(release): bump @mosaicstack/mosaic 0.0.38 -> 0.0.39 (#608 ) Some checks are pending ci/woodpecker/push/ci Pipeline is pending Details ci/woodpecker/push/publish Pipeline is pending Details	2026-06-22 02:16:12 +00:00
Jason Woltje	23343bb7f0	feat(mosaic): P5 — overlay composer (compose-contract + *.local overlays) (#605 ) Some checks are pending ci/woodpecker/push/ci Pipeline is pending Details ci/woodpecker/push/publish Pipeline is pending Details Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>	2026-06-22 02:16:05 +00:00
jason.woltje	c8b2dab0ca	chore(release): bump @mosaicstack/mosaic 0.0.37 -> 0.0.38 (#603 ) Some checks failed ci/woodpecker/push/publish Pipeline was canceled Details ci/woodpecker/push/ci Pipeline was canceled Details	2026-06-22 01:48:27 +00:00