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

.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

docs/TASKS.md

@@ -48,6 +48,17 @@ 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.
+
+## 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 (independent of #615). Detail: scratchpads/f4-matrix-connector.md.

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).

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.

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).

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.

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.

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.

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" }
+          }
+        }
+      }
     }
   }
 }

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

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 ─────────────────────────────────────────────────────────────

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);
+  });
+});

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();
+}

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';

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 });
+  });
+});

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.
  */