fix(backlog): claim locks one ready row (LIMIT 1) to prevent claimer starvation

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

.gitignore

@@ -15,3 +15,10 @@ infra/step-ca/dev-password
 
 # Scratch dirs created by the framework git-wrapper shell test harnesses
 .mosaic-test-work/
+
+# Transient config files vite/vitest/esbuild write next to a *.config.ts while
+# loading it, then unlink. They are untracked but were not ignored, so turbo's
+# package traversal hashed them and intermittently failed CI with "Package
+# traversal error: ... .timestamp-*.mjs: No such file or directory" when the
+# file vanished mid-scan. Ignoring them removes the race.
+*.timestamp-*.mjs

.npmrc

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

.woodpecker/ci-image.yml

@@ -0,0 +1,40 @@
+# Build & push the pre-baked CI base image (Dockerfile.ci) to the Gitea
+# registry CI already publishes to. Reuses the exact kaniko + auth pattern
+# from publish.yml (REGISTRY_USER/REGISTRY_PASS from_secret, /kaniko/.docker
+# config.json). Other pipelines (ci.yml, publish.yml) pull `ci-base:latest`
+# for their install step.
+#
+# Rebuild ONLY when the dependency set or the image recipe changes — a normal
+# code push must not trigger a 25-min image build. `path` applies to push/PR
+# events; `event: tag` (releases) rebuilds unconditionally so a tagged release
+# always ships a fresh base.
+when:
+  - event: tag
+  - event: [push, manual]
+    branch: main
+    path:
+      include:
+        - 'pnpm-lock.yaml'
+        - 'Dockerfile.ci'
+
+steps:
+  build-ci-base:
+    image: gcr.io/kaniko-project/executor:debug
+    environment:
+      REGISTRY_USER:
+        from_secret: gitea_username
+      REGISTRY_PASS:
+        from_secret: gitea_password
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
+    commands:
+      - mkdir -p /kaniko/.docker
+      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
+      - |
+        # Lockfile-hash tag: an immutable identity for the exact dep set baked
+        # into this image. `:latest` is the mutable pointer pipelines consume.
+        LOCK_HASH=$(sha256sum pnpm-lock.yaml | cut -c1-12)
+        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/ci-base:latest"
+        DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/ci-base:lock-$LOCK_HASH"
+        /kaniko/executor --context . --dockerfile Dockerfile.ci $DESTINATIONS

.woodpecker/ci.yml

@@ -1,5 +1,9 @@
+# &node_image is the pre-baked CI base built by .woodpecker/ci-image.yml:
+# node:24-alpine + python3/make/g++/postgresql-client + pnpm + a warm pnpm
+# store. The install step resolves from the baked store (--prefer-offline)
+# instead of paying a ~731s cold fetch + native compile every run.
 variables:
-  - &node_image 'node:22-alpine'
+  - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:latest'
   - &enable_pnpm 'corepack enable'
 
 when:
@@ -15,8 +19,9 @@ steps:
     image: *node_image
     commands:
       - corepack enable
-      - apk add --no-cache python3 make g++
+      # python3/make/g++ are baked into ci-base; --prefer-offline resolves from
-      - pnpm install --frozen-lockfile
+      # the baked pnpm store.
+      - pnpm install --frozen-lockfile --prefer-offline
 
   # Blocking gate: public framework package must contain no operator-specific
   # personal data or private $HOME defaults. Runs early (no node_modules needed).
@@ -25,12 +30,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
@@ -66,8 +69,7 @@ steps:
       DATABASE_URL: postgresql://mosaic:mosaic@ci-postgres:5432/mosaic
     commands:
       - *enable_pnpm
-      # Install postgresql-client for pg_isready
+      # postgresql-client (pg_isready) is baked into ci-base.
-      - apk add --no-cache postgresql-client
       # Wait up to 60s for CI postgres to be ready; fail fast if it never comes up.
       - |
         ready=0

.woodpecker/publish.yml

@@ -2,8 +2,27 @@
 # Runs only on main branch push/tag
 
 variables:
-  - &node_image 'node:22-alpine'
+  # Pre-baked CI base (see .woodpecker/ci-image.yml): node:24-alpine +
+  # toolchain + warm pnpm store. Kills the second cold install publish pays.
+  - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:latest'
   - &enable_pnpm 'corepack enable'
+  # 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]
@@ -14,7 +33,8 @@ steps:
     image: *node_image
     commands:
       - corepack enable
-      - pnpm install --frozen-lockfile
+      # Resolve from the baked pnpm store instead of a cold network fetch.
+      - pnpm install --frozen-lockfile --prefer-offline
 
   build:
     image: *node_image
@@ -26,6 +46,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 +120,7 @@ steps:
 
   build-gateway:
     image: gcr.io/kaniko-project/executor:debug
+    when: *image_build_when
     environment:
       REGISTRY_USER:
         from_secret: gitea_username
@@ -116,6 +146,7 @@ steps:
 
   build-appservice:
     image: gcr.io/kaniko-project/executor:debug
+    when: *image_build_when
     environment:
       REGISTRY_USER:
         from_secret: gitea_username
@@ -141,6 +172,7 @@ steps:
 
   build-web:
     image: gcr.io/kaniko-project/executor:debug
+    when: *image_build_when
     environment:
       REGISTRY_USER:
         from_secret: gitea_username

Dockerfile.ci

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

docs/TASKS.md

@@ -45,3 +45,48 @@ Active workstream is **W1 — Federation v1**. Workers should:
 - Status: PR open, awaiting maintainer merge ratification (fleet-governing change).
 - Cut always-injected contract AGENTS+TOOLS+RUNTIME 8,827→4,122 tok (−53%); all 12 hard gates intact.
 - Validation: deterministic gate-checklist PASS; headless A/B thin 7/9 vs monolith 5/9. Detail: scratchpads/contract-thin-core.md.
+
+## P5 — Overlay composer + cross-harness (#604) — feat/p5-overlay-composer
+
+- Status: MERGED to main (#605). R7 (compose-contract) + R8 (cross-harness) + R9 (composer test).
+- `composeContract({harness, mosaicHome})` pure fn + `.local` overlay deltas-by-value; `mosaic compose-contract <harness>` command; AGENTS bare-launch nudge; composer spec (per-tier anchor + Tier-3 byte-equality). Detail: scratchpads/p5-overlay-composer.md.
+
+## P6 — Docs, compliance matrix, alpha tag (#606) — feat/p6-docs-compliance-alpha
+
+- Status: in-repo deliverables done (CONTRIBUTING.md + harness×gate compliance matrix + check-resident-budget.sh + CI wiring + ALPHA-DOD.md). Remaining: alpha tag v0.0.39-alpha (Lead, post-merge). aiguide reconcile merged (#8). Detail: scratchpads/p6-docs-compliance-alpha.md.
+
+## F3-m3 — mosaic update re-seeds framework + relaunches agents (#609) — feat/f3-m3-update-reseed
+
+- Status: implemented + tested. Closes R13: `mosaic update` now re-seeds the framework (data-safe MOSAIC_SYNC_ONLY) after the CLI install so shipped launcher/runtime changes activate; `--relaunch` restarts rostered agents; `--no-reseed` opts out. Detail: scratchpads/f3-m3-update-reseed.md.
+
+## Fleet-polish bundle — boot-survival symmetry (#611) — feat/fleet-polish-bundle
+
+- Status: MERGED to main. disable-on-remove (boot-resurrection bug, TDD) + add-enable + init-R5 hard guarantee. 4 new + 147 existing fleet tests green. Detail: scratchpads/fleet-polish-bundle.md.
+
+## Fleet enhancer role + two-agent floor (#614) — feat/fleet-enhancer-floor
+
+- Status: MERGED to main. enhancer added to 4 presets; init guarantees 1 orchestrator + >=1 enhancer; remove protects the sole enhancer; enhancer role doc. 155 fleet tests green. Detail: scratchpads/fleet-enhancer-floor.md.
+
+## F4 — Orchestrator chat connector + Matrix (#616) — feat/f4-matrix-connector
+
+- Status: Phase 1 MERGED (#617: connector interface send/subscribe/health + registry + roster schema + design). Phase 2a (#618): Matrix CS-API client + factory. 20 connector tests green; no fleet.ts changes. Remaining Phase 2: init/configure connector-selection UX + roster wiring, systemd launch wiring, Conduit deploy guide. Detail: scratchpads/f4-matrix-connector.md.
+
+## Fleet onboarding-injection — comms cheat-sheet + peer roster (#620) — feat/fleet-comms-onboarding
+
+- Status: implemented + tested. Injects # Fleet Comms (peer roster + cross-host agent-send commands + FLIP-reply + --verify) into each spawned fleet agent via composeContract; optional per-agent host/ssh/socket roster fields (socket: named → -L, unset → default socket no -L). 10 + 2 tests green. Detail: scratchpads/fleet-comms-onboarding.md.
+
+## Fleet stand-up fixes — model_hint→--model + socket-default trap (#626) — feat/fleet-standup-fixes
+
+- Status: implemented + tested. FIX1 model_hint→MOSAIC_AGENT_MODEL→--model. FIX2 absent socket = default tmux socket (no -L) across parse/spawn/systemd-unit/observe (socketArgs helper, bare-empty shellEnvValue, conditional -L). 158 fleet tests green; shipped presets unaffected (explicit socket_name). Detail: scratchpads/fleet-standup-fixes.md.
+
+## north-star doctrine consolidation — doc PR — feat/north-star-doctrine
+
+- Status: applied Mos's consolidated merge-map to docs/fleet/north-star.md (budget governance + control plane/central register + 200k cap + delegation + unified-identity Fleet + role-based naming + tmux security + drift re-captures). Doctrine only; #622/#623/#625/#628 out-of-scope. Conflict checklist green. Detail: scratchpads/north-star-doctrine.md.
+
+## #631 — re-seed preserves user fleet data (CRITICAL) — fix/631-reseed-preserves-fleet-data
+
+- Status: implemented + tested. PRIMARY: install.sh PRESERVE_PATHS += fleet/\*.yaml + fleet/agents + fleet/run (glob-aware cp-fallback); TS parity. SECONDARY: refreshActiveFleetUnits propagates unit fixes to ~/.config/systemd/user on mosaic update. bash F6 + TS + unit tests green. Detail: scratchpads/631-reseed-preserves-fleet.md.
+
+## #633 — comms-block emitter + FLEET-LAUNCH runbook — feat/633-comms-block-runbook
+
+- Status: implemented + tested (TDD). `mosaic fleet comms-block <role> [--host]` wraps resolveCommsBlock → readFleetCommsBlock; fails loud (stderr + exit 1) on unknown role / missing roster instead of silent empty. docs/fleet/FLEET-LAUNCH.md runbook: worker path + orchestrator .env fold (MOSAIC_AGENT_COMMAND; line-41 [-z] short-circuits line-44 yolo hardcode) + 3 launch gotchas + #632 preserve note + North-Star 4-field arc (harness ✅/model ✅ roster-native today; yolo + command/channels = PATH B #636). 177 fleet+comms tests green (6 new resolveCommsBlock cases). PATH A of the A→B→webUI arc. Detail: scratchpads/633-comms-block-runbook.md.

docs/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/FLEET-LAUNCH.md

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

docs/fleet/NORTH_STAR.md

@@ -0,0 +1,70 @@
+# Mosaic Fleet — NORTH STAR
+
+> **Generated file — do not edit by hand.**
+> Projected deterministically from [`NORTH_STAR.yaml`](./NORTH_STAR.yaml) by the pure
+> generator in `packages/mosaic/src/commands/fleet.ts` (`renderNorthStarMarkdown`).
+> Edit the YAML, then regenerate. Self-contained Mosaic — no Hermes dependency.
+
+## Mission
+
+A self-driving Mosaic delivery fleet that 24/7 unattended converts a machine-readable goal set into merged, CI-green, budget-bounded change — looping plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN native backlog/dispatch engine.
+
+## Substrate
+
+The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's native Postgres storage service (@mosaicstack/db drizzle; PGlite-embedded by default, full Postgres by config). NOT Hermes.
+
+## Standing objectives
+
+- **NS-1** — Single machine-readable source (this file) drives planning; prose docs are projections.
+- **NS-2** — Every backlog item is an independently-shippable unit with stable id, priority, depends_on DAG, represented as a Mosaic Backlog card; spend tracked as advisory projection.
+- **NS-3** — The supervisor guarantees movement: no idle agent while ready dependency-satisfied work exists; no empty backlog without a replan request; assignment via Mosaic native dispatch/claim.
+- **NS-4** — Exactly one merge-gate approver; nothing reaches main except via pr-merge.sh after pr-ci-wait.sh success; Gitea branch protection is the backstop.
+- **NS-5** — Every unit bounded by wall-clock TTL on its claim; token caps enforced only where a real meter exists, else advisory.
+- **NS-6** — Context cleared between tasks for ephemeral runners (reset_between_tasks); persona+mission re-injected per task.
+- **NS-7** — Meta-loop (session-review + enhancer) continuously proposes small fleet-improvement PRs.
+- **NS-8** — Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored before every dispatch and every merge.
+
+## Success criteria
+
+- **AC-NS-1** — The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer) healthy across reboot.
+- **AC-NS-2** — A goal added to this YAML is decomposed to cards and either merged or escalated, with no human in the loop.
+- **AC-NS-3** — No PR merges with failure/error/no-status/timeout CI, and none bypass pr-merge.sh.
+- **AC-NS-4** — TTL is enforced on claims; token caps remain advisory until a real meter exists.
+- **AC-NS-5** — Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
+
+## Workstreams
+
+| id  | title                                                            |
+| --- | ---------------------------------------------------------------- |
+| A   | Substrate — Mosaic Backlog on native Postgres storage service    |
+| B   | Supervisor — movement guarantee, two-agent floor, dispatch/claim |
+| C   | Planner — goal decomposition into independently-shippable cards  |
+| D   | Merge-gate — single approver, pr-merge.sh after CI wait          |
+| E   | Meta-loop — session-review + enhancer improvement PRs            |
+| F   | Safety-rails — TTL claims, advisory spend, PAUSE kill-switch     |
+
+## Goals (backlog projection)
+
+| id  | title                                                                  | phase | priority    | depends_on |
+| --- | ---------------------------------------------------------------------- | ----- | ----------- | ---------- |
+| A1  | Machine-readable NORTH_STAR.yaml + Markdown projection                 | 1     | must-have   | —          |
+| A2  | Mosaic Backlog schema + storage-service card store (drizzle/PGlite)    | 1     | must-have   | A1         |
+| A3a | Card lifecycle — create/claim/release with stable ids + depends_on DAG | 1     | must-have   | A2         |
+| A3b | TTL-bounded claim enforcement (wall-clock) on cards                    | 1     | must-have   | A3a        |
+| A4  | Advisory spend projection per card (degrades to TTL, no real meter)    | 1     | should-have | A3a        |
+| B1  | Supervisor tick — readiness scan, two-agent-floor health check         | 2     | must-have   | A3a        |
+| B2  | Native dispatch/claim — assign ready dependency-satisfied work         | 2     | must-have   | A3b, B1    |
+| B3a | Planner decompose — goal added to YAML → cards                         | 2     | must-have   | A2, B1     |
+| B3b | Replan request on empty backlog; escalate on no-decompose              | 2     | should-have | B3a        |
+| G1  | PAUSE kill-switch + merge-gate honored before dispatch and merge       | 2     | must-have   | B2         |
+
+## Assumptions (vetoable)
+
+- **ASM-1** (vetoable) — The Mosaic Backlog on the native Postgres storage service is the backlog of record.
+- **ASM-2** (vetoable) — Claude gate roles have no native busy status, so readiness = pane-idle + heartbeat.
+- **ASM-3** (vetoable) — Two-agent floor = 1 orchestrator + >=1 enhancer.
+
+## Spend
+
+- **advisory:** true
+- No per-task token meter yet; budgets degrade to TTL. Spend is tracked only as an advisory projection alongside each card.

docs/fleet/NORTH_STAR.yaml

@@ -0,0 +1,169 @@
+# Mosaic Fleet — NORTH_STAR (machine-readable source of truth)
+#
+# This file is the single machine-readable source of truth for fleet planning.
+# Prose docs (including NORTH_STAR.md) are deterministic PROJECTIONS of this file.
+# Regenerate the Markdown projection with the pure generator in
+# packages/mosaic/src/commands/fleet.ts (renderNorthStarMarkdown). Edit the YAML,
+# never the .md.
+#
+# Self-contained Mosaic. NO Hermes runtime dependency. The backlog of record is
+# the Mosaic Backlog on Mosaic's OWN native Postgres storage service.
+
+version: 1
+
+mission: >-
+  A self-driving Mosaic delivery fleet that 24/7 unattended converts a
+  machine-readable goal set into merged, CI-green, budget-bounded change —
+  looping plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN
+  native backlog/dispatch engine.
+
+substrate:
+  note: >-
+    The Mosaic Backlog is the backlog of record + dispatch engine, built on
+    Mosaic's native Postgres storage service (@mosaicstack/db drizzle;
+    PGlite-embedded by default, full Postgres by config). NOT Hermes.
+
+standing_objectives:
+  - id: NS-1
+    text: >-
+      Single machine-readable source (this file) drives planning; prose docs are
+      projections.
+  - id: NS-2
+    text: >-
+      Every backlog item is an independently-shippable unit with stable id,
+      priority, depends_on DAG, represented as a Mosaic Backlog card; spend
+      tracked as advisory projection.
+  - id: NS-3
+    text: >-
+      The supervisor guarantees movement: no idle agent while ready
+      dependency-satisfied work exists; no empty backlog without a replan
+      request; assignment via Mosaic native dispatch/claim.
+  - id: NS-4
+    text: >-
+      Exactly one merge-gate approver; nothing reaches main except via
+      pr-merge.sh after pr-ci-wait.sh success; Gitea branch protection is the
+      backstop.
+  - id: NS-5
+    text: >-
+      Every unit bounded by wall-clock TTL on its claim; token caps enforced
+      only where a real meter exists, else advisory.
+  - id: NS-6
+    text: >-
+      Context cleared between tasks for ephemeral runners
+      (reset_between_tasks); persona+mission re-injected per task.
+  - id: NS-7
+    text: >-
+      Meta-loop (session-review + enhancer) continuously proposes small
+      fleet-improvement PRs.
+  - id: NS-8
+    text: >-
+      Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored
+      before every dispatch and every merge.
+
+success_criteria:
+  - id: AC-NS-1
+    text: >-
+      The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer)
+      healthy across reboot.
+  - id: AC-NS-2
+    text: >-
+      A goal added to this YAML is decomposed to cards and either merged or
+      escalated, with no human in the loop.
+  - id: AC-NS-3
+    text: >-
+      No PR merges with failure/error/no-status/timeout CI, and none bypass
+      pr-merge.sh.
+  - id: AC-NS-4
+    text: >-
+      TTL is enforced on claims; token caps remain advisory until a real meter
+      exists.
+  - id: AC-NS-5
+    text: >-
+      Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
+
+workstreams:
+  - id: A
+    title: Substrate — Mosaic Backlog on native Postgres storage service
+  - id: B
+    title: Supervisor — movement guarantee, two-agent floor, dispatch/claim
+  - id: C
+    title: Planner — goal decomposition into independently-shippable cards
+  - id: D
+    title: Merge-gate — single approver, pr-merge.sh after CI wait
+  - id: E
+    title: Meta-loop — session-review + enhancer improvement PRs
+  - id: F
+    title: Safety-rails — TTL claims, advisory spend, PAUSE kill-switch
+
+goals:
+  - id: A1
+    title: Machine-readable NORTH_STAR.yaml + Markdown projection
+    phase: 1
+    priority: must-have
+    depends_on: []
+  - id: A2
+    title: Mosaic Backlog schema + storage-service card store (drizzle/PGlite)
+    phase: 1
+    priority: must-have
+    depends_on: [A1]
+  - id: A3a
+    title: Card lifecycle — create/claim/release with stable ids + depends_on DAG
+    phase: 1
+    priority: must-have
+    depends_on: [A2]
+  - id: A3b
+    title: TTL-bounded claim enforcement (wall-clock) on cards
+    phase: 1
+    priority: must-have
+    depends_on: [A3a]
+  - id: A4
+    title: Advisory spend projection per card (degrades to TTL, no real meter)
+    phase: 1
+    priority: should-have
+    depends_on: [A3a]
+  - id: B1
+    title: Supervisor tick — readiness scan, two-agent-floor health check
+    phase: 2
+    priority: must-have
+    depends_on: [A3a]
+  - id: B2
+    title: Native dispatch/claim — assign ready dependency-satisfied work
+    phase: 2
+    priority: must-have
+    depends_on: [A3b, B1]
+  - id: B3a
+    title: Planner decompose — goal added to YAML → cards
+    phase: 2
+    priority: must-have
+    depends_on: [A2, B1]
+  - id: B3b
+    title: Replan request on empty backlog; escalate on no-decompose
+    phase: 2
+    priority: should-have
+    depends_on: [B3a]
+  - id: G1
+    title: PAUSE kill-switch + merge-gate honored before dispatch and merge
+    phase: 2
+    priority: must-have
+    depends_on: [B2]
+
+assumptions:
+  - id: ASM-1
+    vetoable: true
+    text: >-
+      The Mosaic Backlog on the native Postgres storage service is the backlog
+      of record.
+  - id: ASM-2
+    vetoable: true
+    text: >-
+      Claude gate roles have no native busy status, so readiness = pane-idle +
+      heartbeat.
+  - id: ASM-3
+    vetoable: true
+    text: 'Two-agent floor = 1 orchestrator + >=1 enhancer.'
+
+spend:
+  advisory: true
+  note: >-
+    No per-task token meter yet; budgets degrade to TTL. Spend is tracked only
+    as an advisory projection alongside each card.

docs/fleet/PRD-fleet-suite.md

@@ -0,0 +1,109 @@
+# PRD — Mosaic Fleet Suite (init, configure, operate)
+
+> **Workstream:** W-FLEET (Fleet) under mission `mvp-20260312` · **Phase:** 3→4 productization
+> **North star:** [docs/fleet/north-star.md](./north-star.md) · prior: Phase-2 observability (#579), durable launch (#581), real-agent enablement (#583/#584/#586), releases 0.0.35–0.0.37
+> **Lead:** Jarvis @ `w-jarvis`. **Collaborator:** coder agent @ `dragon-lin` (jwoltje@10.1.10.37:coder0-0).
+> Owner of this file: Fleet workstream lead. Does not modify MVP single-writer control-plane files.
+
+## Mission
+
+Turn the proven fleet primitives into a **user-installable, AI-free-configurable fleet product**:
+a user runs `mosaic fleet init`, answers a few questions (general / coding / research / hybrid),
+gets a recommended set of agents plus one always-on orchestrator wired for chat-ops, and can
+operate, mutate, re-create, and observe the fleet — over tmux today and Matrix tomorrow — from
+CLI/TUI and (designed-for) the webUI.
+
+**Immediate tangible goal:** the **"Mos"** orchestrator agent running on `w-jarvis`, reachable
+in **Discord channel `1517622518662434996`** (server `1112631390438166618`). Once the fleet is
+functional, we use the fleet itself to continue the work.
+
+## Requirements
+
+### A. Configure-without-AI CLI
+
+| ID  | Requirement                                                                                                   |
+| --- | ------------------------------------------------------------------------------------------------------------- |
+| R1  | `mosaic fleet` command set is functional end-to-end (init/install/start/stop/status/ps/verify + agent verbs). |
+| R2  | `mosaic fleet init` is an interactive, **AI-free** CLI wizard.                                                |
+| R3  | Init asks the **configuration type**: `general`, `coding`, `research`, `hybrid`, … (extensible).              |
+| R4  | Based on the answer, the fleet is populated with a **recommended set of agents** (a preset).                  |
+| R5  | **Exactly one main orchestrator agent** is always configured, regardless of type.                             |
+| R10 | A set of **recommended configurations (presets)** ships for easy duplication.                                 |
+| R8  | User can **re-create** the fleet when config needs change (idempotent re-init / reconfigure).                 |
+| R17 | Fleet controls are **simple and intuitive**.                                                                  |
+
+### B. Comms & orchestrator chat-ops
+
+| ID  | Requirement                                                                                                                       |
+| --- | --------------------------------------------------------------------------------------------------------------------------------- |
+| R6  | Init can wire the orchestrator to a chat connector — **Telegram / Discord / Matrix / Slack** — for command + comms.               |
+| R7  | Designed with the end-goal of **Matrix comms on a locally-controlled server**.                                                    |
+| R16 | Fleet supports **tmux AND Matrix** comms, **user-configurable** at init or any time. Not all users want Matrix.                   |
+| R19 | **"Mos" orchestrator on Discord** (`chan 1517622518662434996` / `srv 1112631390438166618`) on `w-jarvis` — the first live target. |
+
+### C. Runtime, health, lifecycle
+
+| ID  | Requirement                                                                        |
+| --- | ---------------------------------------------------------------------------------- |
+| R9  | Fleet is **mutable by the orchestrator agent** — add/remove agents per need.       |
+| R13 | Fleet **gracefully handles Pi + Claude harness updates** — keep harnesses current. |
+| R14 | The **Pi harness is customized** for proper tool usage, etc.                       |
+| R15 | **Agent heartbeat** properly configured for **Claude AND GPT/Pi** agents.          |
+
+### D. Surfaces, testing, docs
+
+| ID  | Requirement                                                                         |
+| --- | ----------------------------------------------------------------------------------- |
+| R18 | Fleet built so the **webUI can view / monitor / terminate / butt-in** on a session. |
+| R11 | Installed and **tested on both `w-jarvis` and `dragon-lin`**.                       |
+| R12 | **Documentation**: how to install, configure, and use the fleet.                    |
+
+## Architecture / approach
+
+- **Config model:** `roster.yaml` is the source of truth (already exists). Add **presets** (`general`/`coding`/`research`/`hybrid`) as shipped example rosters; `init` selects a preset, always injects the orchestrator, and writes the roster. Re-init = regenerate roster (preserve user/site overrides — mirrors install env-merge from #567).
+- **Orchestrator agent:** always present; carries the chat connector config (connector type + target IDs) so it can be commanded over chat. tmux is the substrate; the connector bridges chat ↔ the orchestrator session.
+- **Comms layers (R16):** (1) **tmux** inter-agent (`agent-send`, proven) — default, always available. (2) **chat connector** for human↔orchestrator (Discord now; Matrix the strategic target). (3) **Matrix** as the locally-controlled cross-agent bus (future). Connector is pluggable + reconfigurable.
+- **Heartbeat (R15):** runtime-agnostic launcher sidecar already covers pi/claude/codex (#584). Refine per-runtime (native HB) with the **custom Pi harness** (R14) + a Claude path.
+- **Updates (R13):** `mosaic update` (CLI) + a fleet-aware harness-update step that refreshes pi/claude/codex and re-launches agents safely (drain → update → relaunch via the durable launcher).
+- **webUI (R18):** the fleet exposes machine-readable state (`fleet ps --json` already carries tenant/host/heartbeat/managed) + control verbs (start/stop/watch/send); webUI consumes these (control plane rides federation per north star). Ensure a stable JSON contract + a terminate/attach(butt-in) path.
+
+## Phases (incremental, each shippable)
+
+| Phase                             | Deliverable                                                                                                                         | Notes                                 |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| **F1 Presets + init wizard**      | preset rosters (general/coding/research/hybrid) + always-orchestrator + AI-free `fleet init` selecting a preset; re-init idempotent | R1–R5, R8, R10, R17                   |
+| **F2 Connector + Mos-on-Discord** | orchestrator chat-connector config (Discord first) + **Mos live on Discord `1517…`/`1112…`** on w-jarvis                            | R6, R19, partial R16                  |
+| **F3 Heartbeat + harness**        | HB confirmed for claude + pi/gpt; **custom Pi harness** (tool usage, native HB, model self-report); graceful harness updates        | R13, R14, R15                         |
+| **F4 Matrix + comms toggle**      | Matrix connector (local server) + user toggle tmux/Matrix at init/anytime                                                           | R7, R16                               |
+| **F5 Orchestrator-mutable fleet** | orchestrator can add/remove agents at runtime                                                                                       | R9                                    |
+| **F6 webUI hooks**                | stable JSON contract + terminate/attach surface for webUI view/monitor/terminate/butt-in                                            | R18                                   |
+| **F7 Test + docs**                | install+test on w-jarvis AND dragon-lin; user docs (install/configure/use)                                                          | R11, R12 (runs alongside every phase) |
+
+## Work division (proposed — confirm with dragon-lin)
+
+- **Jarvis @ w-jarvis (Lead):** F1 presets+wizard, F2 connector+Mos-on-Discord, F5 mutability, F6 webUI hooks; merge authority + dual-engine reviews; co-testing on w-jarvis.
+- **coder @ dragon-lin:** F3 custom Pi harness + harness-update flow (pi/codex-savvy); plus its in-flight constitution P4–P6 (P4 installer rework underpins `fleet init`/updates — coordinate the install path). Co-testing on dragon-lin (R11).
+- **Shared:** F4 Matrix (whoever has bandwidth); F7 testing/docs continuous.
+
+## Immediate target: Mos on Discord (F2 first slice)
+
+The discord plugin is available (`~/.claude.json`). Path: configure the **orchestrator** as a durable
+fleet session running Claude Code with the discord plugin bridged to channel `1517622518662434996`
+(server `1112631390438166618`) on w-jarvis, with the existing Discord Bridge Protocol (ack within
+~3s, reply via `mcp__discord__reply`, no `AskUserQuestion`). Heartbeat via the launcher sidecar.
+
+## Success criteria
+
+- A non-AI user can `mosaic fleet init`, pick a type, and get a working fleet + orchestrator.
+- **Mos answers in Discord `1517…`** on w-jarvis.
+- Fleet runs + is observable (`fleet ps`) on **both** w-jarvis and dragon-lin.
+- Harness updates handled gracefully; HB healthy for claude + pi/gpt agents.
+- Docs let a new operator install/configure/use the fleet.
+- Re-init + orchestrator mutation work.
+
+## Assumptions (veto-able)
+
+- `ASSUMPTION:` presets ship as example rosters under the framework (`fleet/examples/*.yaml`), selected by `init`.
+- `ASSUMPTION:` chat connectors are pluggable; Discord first (target exists), Matrix is the strategic default later.
+- `ASSUMPTION:` "Mos" = a Claude Code orchestrator session with the discord plugin (reuses the documented Discord Bridge Protocol).
+- `ASSUMPTION:` per north star, runtimes default to Codex/pi-on-Codex for workers; the orchestrator "Mos" runs Claude Code (in Claude Code, which is allowed).

docs/fleet/PRD.md

@@ -0,0 +1,109 @@
+# PRD — Fleet Phase 2: Operator Observability
+
+> **Workstream:** W-FLEET under `mvp-20260312` · **Phase:** 2
+> **North star:** [docs/fleet/north-star.md](./north-star.md)
+> **Source umbrella PRD:** [docs/PRD.md](../PRD.md) (Mosaic Stack v0.1.0)
+> **Tracks task:** `fleet-observability-1` — restore operator observability into fleet agent sessions.
+
+## Problem
+
+The durable tmux fleet runs on the isolated `mosaic-fleet` socket. That isolation
+(which protects the operator's default tmux) makes the fleet **invisible** to default
+tooling, and truth is split across three planes no single command joins — systemd
+(`systemctl --user`), tmux (`-L mosaic-fleet`), and the process tree (`pstree`).
+`agent tail` (`capture-pane`) returns **blank for full-screen TUIs**, and `agent send`
+confirms only keystroke injection, not acceptance. Net: the operator has near-zero
+observability and no safe way to watch a session.
+
+## Goals
+
+1. One command shows the **whole fleet's** real state, joining all three planes.
+2. **Liveness is truthful**: healthy = answered a heartbeat, not "pane alive".
+3. The operator can **watch** any session read-only without disrupting it.
+4. `send` reports **delivered-and-accepted**, not just injected.
+5. Every record/address carries **`tenant_id` + `host`** (zero foreclosure for multi-tenant/multi-host).
+
+## Non-goals (this phase)
+
+- No webUI (Phase 5; rides federation for cross-host).
+- No `fleetd` daemon or persistent history store.
+- No real-runtime swap (Phase 3) — instrument the live **dogfood stub** fleet.
+- No cross-host aggregation yet (addressing is host-tagged but queries stay local).
+
+## Functional requirements
+
+| ID   | Requirement                                                                                                                                                                                                                                                                                                    |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR-1 | `mosaic fleet ps [--json]` prints one row per roster agent joining: name · tenant · host · runtime · systemd(active/enabled) · pane(alive/dead) · pid · idle · **last-heartbeat age** · **drift** flag (roster runtime ≠ actual pane command) · **boot-enable** warning (active but `UnitFileState=disabled`). |
+| FR-2 | **Heartbeat protocol v1** (see below); `dogfood-agent.py` implements the responder. `fleet ps` issues probes (or reads last-seen) and reports health per FR-1.                                                                                                                                                 |
+| FR-3 | `mosaic agent watch <name>` opens a **read-only** view of the pane (grouped session or `tmux attach -r`) that cannot send keystrokes and does not shrink the agent's window.                                                                                                                                   |
+| FR-4 | `mosaic agent attach <name>` remains the **explicit** interactive-takeover path (separate verb, documented as the only one that can type).                                                                                                                                                                     |
+| FR-5 | `mosaic agent send <name> --verify` confirms the message was **accepted** (not left as an unsubmitted draft) and returns non-zero if delivery cannot be verified.                                                                                                                                              |
+| FR-6 | All structured output (`--json`) includes `tenant_id` and `host` fields.                                                                                                                                                                                                                                       |
+
+## Heartbeat protocol v1
+
+- **Probe:** operator/`fleet ps` writes a sentinel line to the agent's input or a
+  well-known per-agent heartbeat file path `~/.config/mosaic/fleet/run/<agent>.hb`.
+- **Response:** the runtime updates `<agent>.hb` with `ts=<iso8601> pid=<pid> status=<ok|busy>`
+  on a fixed interval (default 15s) and on demand when probed.
+- **Health rule:** `healthy` if `now - ts <= 3 × interval`; else `stale`; missing file = `unknown`.
+- **Contract:** every runtime (dogfood stub now; claude/codex/pi/opencode in Phase 3)
+  MUST emit the heartbeat. The protocol is file-based so it works for headless stubs and
+  full-screen TUIs alike (no `capture-pane` dependency).
+- `ASSUMPTION:` file-based heartbeat (vs in-pane echo) — chosen because it is TUI-safe and
+  uid-scoped, fitting per-tenant isolation. Open to an OTEL-span variant in Phase 3 (MVP-X6).
+
+## Acceptance criteria
+
+- `mosaic fleet ps` shows all 5 live sessions on `mosaic-fleet` with correct
+  pane/pid/idle and flags the dogfood **drift** (`canary-pi` runtime=pi but pane runs
+  `dogfood-agent.py`) and the **boot-enable** gap (active but disabled).
+- Killing one agent's pane flips its row to dead/stale within one `interval`.
+- `agent watch` shows live output and provably cannot type into the pane; detaching
+  leaves the agent's window size unchanged.
+- `agent send --verify` returns success on an accepting pane and non-zero on a wedged/draft pane.
+- Quality gates green: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, plus
+  `pnpm --filter @mosaicstack/mosaic test`.
+- Independent review passed; dogfood evidence captured against the live fleet.
+
+## Test plan
+
+- Unit/CLI specs in `packages/mosaic/src/commands/fleet.spec.ts` (and a new
+  `fleet-ps`/`watch`/`send-verify` spec) using the injected `CommandRunner` to assert
+  exact tmux/systemd command construction and JSON shape (tenant+host present).
+- Situational: run against the live `mosaic-fleet` fleet; capture `fleet ps` output,
+  a kill-and-detect cycle, a read-only `watch`, and a `send --verify` pass/fail pair.
+
+## Known limitations
+
+- **Verify heuristic is best-effort:** `agent send --verify` uses a `>` -prefix draft
+  heuristic that is specific to pi/claude TUIs. Draft detection for codex and opencode
+  TUIs is best-effort only; those runtimes may not use the same input-line indicator.
+- **Pane-change check is the best Phase-2 signal; verify now polls up to a bounded
+  timeout:** `agent send --verify` captures a BEFORE snapshot, sends the message, then
+  polls `capture-pane` every ~400 ms up to a configurable total timeout (default ~6 s,
+  controlled by `--verify-timeout <ms>`). On each poll it runs classifySendResult: if
+  the pane shows 'accepted' or 'draft' the loop exits immediately; while the result is
+  'unverifiable' (no pane change yet) it keeps polling. After the timeout with no
+  definitive result, it fails closed: exit 1 with "no pane change after send". This
+  eliminates false 'unverifiable' failures for slow/loaded TUIs that were previously
+  caused by the old fixed 300 ms single-capture. Definitive acceptance ultimately
+  requires a runtime acknowledgement (Phase-3 heartbeat-ack); the bounded pane-change
+  poll is the best signal available against an opaque TUI for Phase-2.
+- **Blank AFTER capture fails closed:** Full-screen TUIs (claude, codex, opencode, pi)
+  render blank for `tmux capture-pane`. When the AFTER snapshot is empty, `send --verify`
+  returns non-zero with an "unverifiable" message rather than silently succeeding. This
+  is an intentional fail-closed design (FR-5).
+- **`agent watch` uses a grouped viewer session:** `tmux attach -r` directly against the
+  agent session lets the viewer terminal shrink the agent's window. `agent watch` instead
+  creates a throwaway grouped session (`tmux new-session -d -t '=<agent>' -s
+'<agent>-watch-<pid>'`), attaches read-only to that session, and kills it on detach.
+  The grouped session shares the agent's windows but has independent sizing, so the
+  agent's window is never affected. `tmux attach` is still interactive and requires
+  inherited stdio; the `interactiveRunner` handles TTY passthrough.
+
+## Surfaces & parity (MVP-X1)
+
+CLI lands this phase. TUI surface follows in the `packages/mosaic` wizard; webUI in
+Phase 5 via federation. PRD records the parity debt explicitly so it is not lost.

docs/fleet/TASKS.md

@@ -0,0 +1,27 @@
+# Tasks — W-FLEET (Fleet) Phase 2: Observability
+
+> Workstream task file for the Fleet. Single-writer: Fleet workstream lead (orchestrator).
+> Workers read but never modify. This is **not** the MVP rollup (`docs/TASKS.md`) — a
+> rollup row is proposed to the MVP orchestrator, not written here.
+>
+> Mission: `mvp-20260312` · PRD: [docs/fleet/PRD.md](./PRD.md) · North star: [docs/fleet/north-star.md](./north-star.md)
+> Status: `not-started` | `in-progress` | `done` | `blocked` | `failed`
+
+| id            | status      | description                                                                                                        | depends_on            | agent       | pr  | notes                                                                                                                       |
+| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | --------------------- | ----------- | --- | --------------------------------------------------------------------------------------------------------------------------- |
+| FLEET-OBS-000 | done        | Plan: north-star + Phase-2 PRD + workstream scaffolding                                                            | —                     | lead        | —   | persisted 2026-06-20 on `feat/fleet-observability`                                                                          |
+| FLEET-OBS-001 | done        | Heartbeat protocol v1 spec finalized in PRD + framework doc                                                        | FLEET-OBS-000         | lead        | —   | file-based `~/.config/mosaic/fleet/run/<agent>.hb`; spec in PRD                                                             |
+| FLEET-OBS-002 | in-progress | Implement heartbeat responder in `dogfood-agent.py`                                                                | FLEET-OBS-001         | fleet-coder | —   | dispatched to ad-hoc `mosaic yolo` fleet agent (dogfood)                                                                    |
+| FLEET-OBS-003 | done        | `mosaic fleet ps` — join systemd+tmux+proc+idle+heartbeat; tenant+host tagged; drift + boot-enable flags; `--json` | FLEET-OBS-001         | worker      | —   | commit ab47831; LIVE-verified on mosaic-fleet; caught canary-pi DRIFT + BOOT-ENABLE. Polish: idleSeconds parse returns null |
+| FLEET-OBS-004 | done        | `mosaic agent watch <name>` — read-only join (no resize, no keystrokes)                                            | FLEET-OBS-000         | worker      | —   | `attach -r`; verb wired                                                                                                     |
+| FLEET-OBS-005 | done        | `mosaic agent send --verify` — delivery/acceptance receipt                                                         | FLEET-OBS-000         | worker      | —   | --verify flag; draft-heuristic verify                                                                                       |
+| FLEET-OBS-006 | done        | CLI specs for ps/watch/send-verify (tenant+host shape, command construction)                                       | FLEET-OBS-003,004,005 | worker      | —   | 62 tests green (31 new); re-verified by lead                                                                                |
+| FLEET-OBS-007 | not-started | Framework doc: fleet observability guide + verbs                                                                   | FLEET-OBS-003,004,005 | lead        | —   | `docs/guides/` or `framework/tools/.../README`                                                                              |
+| FLEET-OBS-008 | not-started | Independent review + dogfood verification on live fleet                                                            | FLEET-OBS-002..007    | reviewer    | —   | author ≠ reviewer; capture evidence in scratchpad                                                                           |
+| FLEET-OBS-009 | not-started | Open PR → green CI (queue guard) → squash-merge → close `fleet-observability-1`                                    | FLEET-OBS-008         | lead        | —   | trunk merge; no direct push to main                                                                                         |
+
+## Proposed MVP rollup row (for the MVP orchestrator — not written by this workstream)
+
+```
+| W-FLEET | in-progress | Fleet (agent-session execution layer) | Phase 2/5 | docs/fleet/TASKS.md | observability dogfooded on live stub fleet; control plane rides federation (W1) |
+```

docs/fleet/backlog-conventions.md

@@ -0,0 +1,138 @@
+# Fleet Backlog Conventions
+
+The **backlog** is Mosaic's native backlog-of-record for fleet work. It is built
+end-to-end on Mosaic's own storage layer (`@mosaicstack/db`, drizzle/Postgres)
+and surfaced as `mosaic fleet backlog <sub> --json`.
+
+> **Mosaic-native, no Hermes.** This backlog REPLACES the former Hermes adapter.
+> There is **no** runtime dependency on Hermes, `hermes kanban`, or `~/.hermes`
+> anywhere in this feature. Anything previously delegated to Hermes is recreated
+> here on Mosaic's own Postgres storage layer.
+
+## Storage tier — PGlite by default, Postgres by config
+
+The backlog uses the existing Mosaic storage layer; there is **no** new database
+engine (no sqlite, no raw client).
+
+| Condition                      | Tier                 | Data location                    |
+| ------------------------------ | -------------------- | -------------------------------- |
+| `DATABASE_URL` set             | Full server Postgres | the configured database          |
+| `PGLITE_DATA_DIR` set (no URL) | Embedded PGlite      | that directory                   |
+| neither (default)              | Embedded PGlite      | `~/.config/mosaic/fleet/backlog` |
+
+PGlite is real Postgres semantics in-process — including the row locks the atomic
+claim relies on — so the **same code** runs on a laptop (embedded, single-host
+default) and on a full Postgres deployment. Switching tiers is config-only.
+
+The schema (`backlog` table) is created automatically on first CLI use:
+`runMigrations()` for Postgres, `runPgliteMigrations()` for embedded PGlite.
+
+### Update safety
+
+The embedded PGlite store lives under `~/.config/mosaic/fleet/backlog`, which is
+listed in `PRESERVE_PATHS` in `packages/mosaic/framework/install.sh`. This means
+`mosaic update` (which runs the framework sync with `rsync --delete`) will **not**
+wipe the operator's backlog — same protection as the roster, per-agent env, and
+heartbeat run dir.
+
+## Card schema
+
+A card is one row in the `backlog` table:
+
+| Column              | Type                | Notes                                                         |
+| ------------------- | ------------------- | ------------------------------------------------------------- |
+| `id`                | text (PK)           | Stable, caller-supplied id (e.g. `A4`, `fleet-001`).          |
+| `title`             | text                | Required.                                                     |
+| `body`              | text (nullable)     | Free-form description.                                        |
+| `phase`             | text (nullable)     | Board/phase grouping (see below).                             |
+| `priority`          | int (default 0)     | **Higher = sooner.** Claim picks the max-priority ready card. |
+| `status`            | enum                | `ready` \| `claimed` \| `blocked` \| `done`.                  |
+| `depends_on`        | jsonb `string[]`    | DAG edges — ids of cards this one depends on.                 |
+| `claim_owner`       | text (nullable)     | Owner token of the active claim.                              |
+| `claim_ttl_seconds` | int (nullable)      | TTL of the active claim.                                      |
+| `claimed_at`        | timestamptz (null)  | When the claim was taken. `claimed_at + ttl` = expiry.        |
+| `attempts`          | int (default 0)     | Incremented each time the card is claimed.                    |
+| `idempotency_key`   | text (unique, null) | Dedups `create`; NULLs are distinct in Postgres.              |
+| `acceptance`        | jsonb (nullable)    | Acceptance criteria (array of strings or object).             |
+| `created_at`        | timestamptz         |                                                               |
+| `updated_at`        | timestamptz         |                                                               |
+
+`depends_on` is modeled as a `jsonb` array column rather than a separate edge
+table. Justification: it matches the repo's existing style (e.g. `tasks.tags`,
+`agents.skills`, `routing_rules.conditions` are all jsonb arrays), keeps a card
+self-contained, and the DAG is small (per-card dependency lists), so a join table
+would add ceremony without benefit.
+
+### Board / phase convention
+
+`phase` is a free-form grouping string used as the board column / milestone label
+(e.g. `M1`, `fleet`, `infra`). `list --phase <phase>` filters to one board lane.
+`priority` orders cards **within** the ready pool regardless of phase.
+
+## Status lifecycle
+
+```
+            create
+              │
+              ▼
+   ┌──────► ready ───── claim ─────► claimed ───── complete ─────► done
+   │          │                         │
+   │       block                  reclaim (TTL expiry or --id)
+   │          ▼                         │
+   │       blocked                      └──────────────────────────┘ (back to ready)
+   └──────────┘  (reclaim / re-create can return a card to ready)
+```
+
+- **ready** — eligible to be claimed once every `depends_on` card is `done`.
+- **claimed** — a worker holds it; `claim_owner` + `claimed_at` set.
+- **blocked** — explicitly parked; never auto-claimed.
+- **done** — completed; satisfies dependents.
+
+## Atomic claim (`FOR UPDATE SKIP LOCKED`) + TTL
+
+`claim` is atomic. Inside a single transaction it locks candidate `ready` rows
+with `SELECT ... FOR UPDATE SKIP LOCKED` (via the drizzle `sql` operator), picks
+the highest-priority deps-satisfied card, and flips it to `claimed`. Because a row
+already locked by a concurrent claimer is **skipped**, two claimers can **never**
+both win the same card — the loser falls through to the next candidate or gets
+`null`. (Proven by the concurrency tests in `packages/db/src/backlog.spec.ts`.)
+
+- **Deps gate:** a card is only claimable when every id in `depends_on` is `done`.
+- **TTL:** `claim --ttl <sec>` (default **900s**) records `claim_ttl_seconds`.
+- **reclaim:** releases claims whose `claimed_at + ttl` is in the past (expired)
+  back to `ready`, clearing the claim fields. `reclaim --id <id>` force-releases a
+  specific card regardless of expiry. This is how a crashed worker's card returns
+  to the pool.
+
+## CLI — `mosaic fleet backlog <sub> --json`
+
+All subcommands support `--json`.
+
+| Subcommand                                                                                    | Purpose                                                                                   |
+| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `create --id --title [--body --phase --priority --depends-on --acceptance --idempotency-key]` | Create a card; `idempotency_key` dedups (repeat returns the existing card).               |
+| `list [--status --phase --ready-only]`                                                        | List cards. `--ready-only` = status `ready` AND all deps `done`.                          |
+| `claim --owner [--ttl <sec> --id <id>]`                                                       | Atomically claim the highest-priority ready card (or `--id`). Returns the card or `null`. |
+| `reclaim [--id <id>]`                                                                         | Release expired claims (or a specific card) back to `ready`.                              |
+| `link --from --to`                                                                            | Add a `depends_on` edge (`--from` depends on `--to`).                                     |
+| `stats`                                                                                       | Counts by status, oldest-ready age, expired-claim count.                                  |
+| `block --id`                                                                                  | Set a card to `blocked`.                                                                  |
+| `complete --id`                                                                               | Set a card to `done` (releases any claim).                                                |
+
+### Example
+
+```sh
+# Seed two cards, the second depends on the first.
+mosaic fleet backlog create --id A1 --title "schema" --priority 5
+mosaic fleet backlog create --id A2 --title "service" --depends-on A1 --priority 9
+
+# A2 is gated on A1, so claim returns A1 first.
+mosaic fleet backlog claim --owner worker-1 --ttl 600 --json
+
+# Finish A1; now A2 is ready.
+mosaic fleet backlog complete --id A1
+mosaic fleet backlog list --ready-only --json
+
+# Recover stalled work.
+mosaic fleet backlog reclaim --json
+```

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/fleet/north-star.md

@@ -0,0 +1,411 @@
+# Mosaic Fleet — North Star
+
+> **Workstream:** W-FLEET (Fleet) under mission `mvp-20260312`
+> **Umbrella:** [docs/MISSION-MANIFEST.md](../MISSION-MANIFEST.md) · [docs/PRD.md](../PRD.md) (Mosaic Stack v0.1.0)
+> **Status:** doctrine — authored 2026-06-20. Owner of this file: Fleet workstream lead.
+> This document does **not** modify the MVP rollup; a rollup row is proposed, not written here.
+
+## Vision
+
+A **customizable, multi-tenant fleet of always-on AI agents** — each defined by role,
+materialized as a durable, joinable runtime session, coordinated by the proven
+orchestrator/worker model, and observable end-to-end across hosts. Coding today;
+finance, analytics, research as roster entries tomorrow — same primitives, different
+roster. The fleet is the **agent-session execution layer** of the Mosaic Stack MVP:
+the thing federation makes reachable across hosts and the webUI/TUI/CLI make visible.
+
+The USC tmux PoC (durable sessions + `agent-send` comms) proved the model. This
+workstream makes it an official, observable, multi-tenant Mosaic Stack capability.
+
+## The Fleet as means of production (bootstrapping)
+
+The Fleet has a **dual role**, and that is the point:
+
+- **As product** — a multi-tenant agent-fleet capability of Mosaic Stack (this workstream).
+- **As means of production** — the orchestrator/worker fleet that _actually builds the
+  entire MVP_ (federation W1, webUI, TUI, CLI, and the Fleet itself).
+
+We are **building the system that builds the system.** Every other MVP workstream is
+delivered _by_ the fleet, so fleet observability and control are not merely product
+features — they are the **operational floor of the whole delivery effort**. If we cannot
+see and steer the agents, we cannot trust what they ship. This is why Phase 2
+(observability) leads: it is the instrument panel for the factory, dogfooded on the live
+fleet that is, recursively, building Mosaic Stack.
+
+The discipline that makes great power safe is the same gate chain the fleet enforces:
+independent review before merge, green CI, honest completion, decide-and-inform cadence,
+and no irreversible action without authority. The bootstrap is only as trustworthy as
+those gates.
+
+## Alignment with MVP cross-cutting requirements
+
+The Fleet inherits — does not re-invent — the MVP's hard requirements:
+
+| MVP req                       | What it means for the Fleet                                                                                             |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| MVP-X1 three-surface parity   | fleet observability/control reachable via **CLI + TUI + webUI** (CLI first; webUI is required for parity, not optional) |
+| MVP-X2 multi-tenant isolation | one tenant = one **Linux uid** (own `systemd --user`, socket, `~/.config/mosaic`); no cross-tenant leakage              |
+| MVP-X3 auth (BetterAuth/SSO)  | operator→fleet and cross-host views are auth-gated through the platform's existing auth                                 |
+| MVP-X4 quality gates          | `pnpm typecheck`/`lint`/`format:check` green before any push                                                            |
+| MVP-X5 federated topology     | cross-host fleet visibility rides the **federation** boundary (W1), not a bespoke broker                                |
+| MVP-X6 OTEL tracing           | heartbeats, sends, and lifecycle events emit spans; `traceparent` crosses the federation boundary                       |
+| MVP-X7 trunk merge            | branch from `main`, squash-merge via PR, never push to `main`                                                           |
+
+## The stack — where every concern lives
+
+One **definition** is the source of truth; the **session** is how it runs.
+
+| Layer                            | Owner                                                                                       | Phase-2 reality                                        | Destination                                                                                                                         |
+| -------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **Definition + identity + auth** | gateway / `mosaic-as` (scoped tokens, #541)                                                 | `roster.yaml` (tenant-tagged)                          | one definition; `mosaic agent --new` materializes it                                                                                |
+| **Tenancy boundary**             | **Linux uid per tenant** (linger, own `systemd --user`, own socket, own `~/.config/mosaic`) | one tenant: `jarvis` = tenant zero                     | uid-per-tenant; federation aggregates across hosts                                                                                  |
+| **Runtime**                      | per-tenant tmux session on isolated socket                                                  | dogfood stub sessions (live now on `mosaic-factory`)   | claude/codex/pi/opencode TUIs                                                                                                       |
+| **Liveness**                     | **heartbeat protocol** every runtime answers                                                | protocol defined + dogfood stub answers it             | all runtimes answer; "healthy" ≠ "pane alive"                                                                                       |
+| **Observation**                  | read-only `watch` (native tmux) + `pipe-pane` stream                                        | CLI `watch`/`ps`; explicit opt-in `attach` for control | + auth-gated webUI streams                                                                                                          |
+| **Control plane**                | **federation** across hosts × tenants                                                       | records already carry `tenant_id` + `host`             | federated gateways expose fleet state; webUI in Phase 5                                                                             |
+| **Central register**             | Postgres `fleet` schema (gateway instance); access via gateway API only                     | _none in PoC_ (files + `roster.yaml`)                  | agents, missions, tasks, heartbeats, spend — single network-accessible SSOT; docs = generated projections                           |
+| **Budget / spend governance**    | **per-tenant budget policy** ingested by the orchestrator + routing layer                   | none today (spend is unmetered)                        | usage-vs-limit feedback ingested; spend auto-paced to the limit window; per-provider/per-account/concurrency/API-$ budgets enforced |
+
+> **PoC socket hygiene:** the PoC fleet runs on the **default tmux socket** (no `-L`).
+> The named production-isolation socket is **`mosaic-fleet`** (matches the product brand);
+> an absent roster `socket_name` means the default socket everywhere (spawn, `fleet ps`,
+> onboarding cheat-sheet). The legacy dogfood canary still runs on the old `mosaic-factory`
+> socket pending migration.
+
+## Operating model (inherited, not reinvented)
+
+The AI-guide law stands: one accountable **orchestrator**, isolated **workers** that
+stop at PR-open, the serialized **gate chain** (independent review → green CI →
+diff-sanity → squash-merge → verify), **decide-and-inform** cadence, and a durable
+**board** so missions survive session death. The Fleet is the infrastructure _under_
+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:
+
+1. Carry **`tenant_id` + `host`** in schema and message addressing — even with one of each today.
+2. Treat **isolation socket ≠ invisibility** — anything isolated is surfaced by one command.
+3. Define **healthy = answered a heartbeat within N seconds**, never just "pane alive".
+4. Make **observation read-only by default**; control is an explicit, separate, opt-in verb.
+
+> **OPS INVARIANT — runtime agents need a real TTY.** Claude/Codex/pi/opencode agents
+> cannot be bare-launched from a systemd `ExecStart`; a durable harness with a real PTY is
+> required. This is **why `start-agent-session.sh` launches into tmux** and uses a
+> `MOSAIC_AGENT_COMMAND` override rather than running the runtime directly under systemd.
+
+## Budget & token governance (first-class fleet concern)
+
+Spend is a fleet-level resource, not a per-agent afterthought. The fleet treats token
+and API-dollar budget the way it treats liveness: a signal every runtime exposes and the
+control plane is accountable for. This rides the same primitives as everything else —
+`tenant_id` + `host` on every spend record, **read-only metering by default**, and the
+**federation** layer as the cross-host aggregation point (W1) — so budgeting is zero-foreclosure
+from day one even while one tenant exists.
+
+**Two spend regimes, one policy surface:**
+
+| Regime                                                  | Feedback signal                                                          | Fleet obligation                                                                                        |
+| ------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| **OAuth-subscription runtimes** (Claude sub, Codex sub) | runtime exposes **current-usage-vs-limit** within a rolling limit window | **ingest** the signal per sub-account; **auto-pace** agentic spend so the window is not exhausted early |
+| **API-token runtimes** (metered per token)              | provider billing / token counts                                          | enforce **hard $-spend ceilings**; on breach, **downgrade → queue → refuse** (below)                    |
+
+**Auto-pacing law (OAuth subs) — EVEN-SPREAD default (Jason override, 2026-06-22):** the fleet
+paces agentic token spend to consume the limit window **evenly over remaining time**:
+target rate = _(remaining usage available)_ ÷ _(remaining time in the window)_. Example: 100% of
+a 7-day window = **~14.285%/day**; the system tracks current usage and continuously re-splits the
+remainder evenly to hold pace. **Anticipated token-spend-per-task is the budgeting informant** —
+tasks are scheduled against the daily pace, not run until the quota is gone. Rationale: spreading
+delivery evenly beats rapidly exhausting usage and losing **multiple days of momentum**.
+**Rapid pacing / overspend requires EXPLICIT user authorization;** absent it, even-spread holds.
+Pacing is a control-plane decision, surfaced read-only before it throttles a lane.
+
+**Hard-cap breach behavior (ladder):** when a budget ceiling is hit mid-work, the fleet
+**downgrades first** (opus → sonnet → haiku, then Claude → Codex), **queues** the lane at the
+cheapest floor until the window resets, and **refuses** only as a last resort. Refusal is never
+the first response to a breach.
+
+**Spend accounting, learning & telemetry:**
+
+- **Multi-subscription auto-routing:** a tenant with multiple subscriptions may let the fleet
+  **auto-route work to the account with the most available usage** (within budget policy).
+- **Historical spend learning:** every task's token spend is **recorded**; historical data
+  continuously updates known **spend-per-task**, **typical daily spend**, and projections — so
+  estimates self-correct and pacing stays on target.
+- **Projected + actual spend on artifacts (Mosaic Stack mandate):** PRDs, missions, and task
+  decomposition **MUST note projected AND actual token spend** — a Mosaic Stack process standard
+  (template-level), tracked separately as **#622**.
+- **Anonymized telemetry → mosaicstack.dev:** spend data is reported (anonymous) to the
+  mosaicstack.dev telemetry endpoint so other agents/fleets budget and optimize from real,
+  anonymized data. Product workstream, tracked separately as **#623**.
+
+**User-settable budgets (the policy surface).** A tenant operator can set budgets for every
+configured **provider** (per-provider ceilings), the **account-to-task mapping**, the **agentic
+routing flow**, **concurrency** (the spend multiplier), and **hard API-token $-limits**. Budgets
+are enforced at the orchestrator + routing boundary, not inside individual workers (a worker never
+decides its own budget — see delegation discipline).
+
+**Budget CLI UX (#558):** `mosaic budget set --reset-at` sets the window reset; reset-datetimes
+carry **confidence tags** (`user` / `provider` / `estimated` / `unknown`); and **urgency/criticality
+is a dispatch-gate modifier** — high-urgency work may override even-spread pacing **within
+authorization**. (Also feeds the budgeting workstream, not only this doc.)
+
+## Observation model
+
+| Verb                                | Behavior                                                                                           |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `mosaic fleet ps`                   | one table joining systemd + tmux + process + idle + last-heartbeat, with drift + boot-enable flags |
+| `mosaic agent watch <name>`         | **read-only** join (grouped session / `-r`), no resize tyranny, no keystrokes                      |
+| `mosaic agent attach <name>`        | explicit interactive takeover (the only path that can type)                                        |
+| `mosaic agent send <name> --verify` | confirms message **accepted**, not merely keystroke-injected                                       |
+
+> Why the current PoC blocks observation: sessions live on the isolated `mosaic-factory`
+> socket (invisible to default `tmux ls`), the only sanctioned read is `capture-pane`
+> (blank for full-screen TUIs), and `attach` is read-write + resizes the session. The
+> verbs above restore "join and observe" safely.
+
+## Control plane & central register
+
+### Why the register must be Postgres
+
+The fleet is multi-host (w-jarvis + dragon-lin + future). A SQLite file is a local
+file — it is not a network service and cannot be shared across hosts. Beyond topology,
+Postgres MVCC eliminates the concurrent-writer corruption class Hermes hit with SQLite
+under multi-agent access.
+
+Access is exclusively through the **gateway API** (`apps/gateway` — typed, auth-gated,
+scoped tokens). No agent or dispatcher pane ever holds a raw DB credential; a
+compromised pane cannot corrupt or exfiltrate the register.
+
+### Architecture (layers)
+
+| Layer                  | Responsibility                                                                                                | Implementation                                                                                                                                                                                            |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Register**           | Source of truth: agents, missions, tasks, heartbeats, spend                                                   | Postgres `fleet` schema — existing stack instance (`@mosaicstack/db`)                                                                                                                                     |
+| **Access**             | Typed, auth-gated API                                                                                         | Gateway `fleet/*` routes                                                                                                                                                                                  |
+| **Dispatcher**         | Brief classification, BOD review, planning/coding/review/test/deploy sequencing + gates → fleet task dispatch | **forge pipeline engine** (`runPipeline`/`resumePipeline`, brief classifier, BOD) **+ thin `forge-exec` adapter → `agent-send.sh`**; NOT a new daemon — forge is reused, only stage→agent dispatch is new |
+| **Orchestrator (Mos)** | Goals, missions, judgment, user/PA interface                                                                  | Context-light; sets intent → re-engages only for decisions                                                                                                                                                |
+
+### Dispatcher = forge (reuse, do not rebuild)
+
+The dispatcher is **not new work**: it is `@mosaicstack/forge`, a fully-implemented
+software-factory pipeline engine (brief → Board-of-Directors review → 3 planning stages →
+coding → review/remediation → testing → deploy). Forge already provides
+`runPipeline`/`resumePipeline`, a brief classifier, and a BOD persona loader, so the fleet
+does **not** re-implement sequencing, gate logic, or brief classification. The only new
+fleet-owned code is a thin **`forge-exec` TaskExecutor adapter** (`ForgeTask` →
+`agent-send.sh` to a named agent) — forge's single missing piece — tracked as a Gitea
+issue and built post-PoC. The Postgres register backs forge's pipeline state (durable
+`resumePipeline`, cross-host) in addition to cross-project missions/tasks/Kanban. The
+north-star **'board' role IS forge's Board-of-Directors** — reused from forge, not a new
+role implementation.
+
+### Docs as projections
+
+`docs/TASKS.md` and `MISSION-MANIFEST.md` are **generated projections** of the DB,
+not hand-maintained. The dispatcher (or a scheduled job) renders Markdown from
+`fleet.*` tables and commits the output. DB is authoritative; docs are for human
+reference.
+
+### Spend
+
+`fleet.spend_ledger` records projected and actual token spend per agent/mission/task
+(ties to issue #622). The dispatcher enforces budget caps before dispatching. Mos reads
+the roll-up via API — no raw DB access, no context-bloating dumps.
+
+### Federation
+
+Cross-host fleet state flows through federated gateway queries (existing
+`federation_peers` / `federation_grants` machinery). This is the existing north-star
+invariant: **control plane rides federation (W1), not a bespoke broker.** No new
+broker introduced.
+
+### Scope
+
+This is Phase 4–5 of this roadmap, materialized. It MUST NOT block the PoC (which
+runs correctly on files + `roster.yaml`). Begin when Phase 2 heartbeat protocol is
+stable and concurrent-agent count makes file coordination the bottleneck.
+
+### Open sub-decision
+
+Dedicated Postgres **instance** vs. dedicated **schema** in the existing instance.
+Recommendation: dedicated schema, existing instance (a migration file, not new infra);
+re-evaluate if isolation or write-volume demands it.
+
+## Phased roadmap
+
+| Phase                  | Outcome                                                                                                                                                                                                  | Status  |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| 0–1                    | tmux PoC, hardening, published CLI v0.0.34 (#565–#568)                                                                                                                                                   | ✅ done |
+| **2 — Observability**  | `fleet ps` (host+tenant aware join), heartbeat protocol + dogfood stub answers it, `agent watch` (read-only), `agent send --verify` receipts                                                             | ▶ now   |
+| 3 — Real runtimes      | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: **orchestrator + enhancer**; ephemeral workers per lane)                                                                | planned |
+| 4 — Unified definition | one agent schema in gateway; `mosaic agent --new` → materialized per-tenant session; uid-tenant provisioning; **`fleet` schema migration + `forge-exec` TaskExecutor adapter (forge → `agent-send.sh`)** | planned |
+| 5 — Control plane      | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity; **central register live (spend ledger, docs-as-projections, multi-host Kanban)**              | planned |
+
+## Decisions of record (2026-06-20, with Jason)
+
+- Agent model: **config defines, session runs** (gateway = definition/identity/auth; tmux = runtime).
+- Tenancy: **multi-tenant from the start**; isolation = **per-tenant Linux uid**.
+- Health: **heartbeat required** (dogfood stub implements the protocol now).
+- Lifecycle: **hybrid** — core always-on + ephemeral workers per lane.
+- Observation: **read-only default, opt-in takeover**.
+- Multi-host: **designed-for from day one**; control plane **rides federation (W1)**.
+- Delivery: **CLI-first now**, dogfood against the live stub fleet; webUI deferred to Phase 5.
+- Runtimes: fleet agents default to **Codex / pi-on-Codex**; **Claude is reserved for Claude
+  Code only** (avoid alternate-harness API pricing). Validated durable recipe:
+  `mosaic yolo pi --model openai-codex/gpt-5.5:high`. Durable detached launch requires the
+  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).
+- **Session context cap = 200k tokens (GLOBAL to all Claude sessions):** Claude Code sessions are
+  capped at a **max 200k-token context window**. Long-running sessions extended toward 1M tokens
+  have proven **worse in practice** (degraded steering, off-plan divergence); 200k is the standard.
+  **Enforcement split:** the _window_ lives in **`~/.claude/settings.json`** (host-global) as
+  `"autoCompactWindow": 200000` + `"autoCompactEnabled": true`; the _1M-disable_ lives in **launch
+  ENV** (`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`, plus `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`) wherever
+  a `[1m]` model can be selected (`mos-claude.service` + the fleet Claude launcher), so every Claude
+  agent is capped at spawn. (settings = window; env = 1M-disable.)
+- **Worker context bound (#8):** workers are kept context-bounded via the **ephemeral-per-lane
+  lifecycle + native compaction**, not via the 200k knob. The explicit `autoCompactWindow` 200k knob
+  **stays Claude-specific** — the _principle_ (bounded context) extends to workers, the _knob_ does not.
+- **Orchestrator delegation discipline:** the orchestrator **delegates all delivery work** to
+  subagents / workflows / ultracode / coder agents and confines its own context to \*\*orchestration
+  - the personal-assistant lane\*\*. Keeping delivery out of the orchestrator's window keeps its
+    context unpolluted and measurably reduces off-plan divergence. The orchestrator coordinates and
+    decides; it does not implement.
+- **Budget governance is fleet doctrine:** token/API-dollar budgeting is a first-class fleet concern
+  (see "Budget & token governance"). OAuth-sub usage-vs-limit feedback is ingested per account, spend
+  is **auto-paced EVEN-SPREAD over remaining time** (rapid/overspend only on explicit authorization),
+  spend is **tracked historically** to self-correct per-task/daily estimates, multi-sub tenants may
+  **auto-route by available usage**, and operators set budgets per provider, per account-to-task
+  mapping, per routing flow, per concurrency level, and as hard API-$ ceilings.
+- **Spend accounting is a Mosaic Stack process mandate:** PRDs, missions, and task decomposition
+  **MUST carry projected + actual token spend**; used locally for pacing and reported as **anonymized
+  telemetry to mosaicstack.dev**. The template standard (#622) and telemetry product (#623) are
+  tracked separately.
+- **Unified identity = "Fleet" (Jason, 2026-06-22):** the product is **Mosaic Fleet** — one unified
+  user-facing identity and CLI surface. **forge** is the Fleet's **internal** delivery/orchestration
+  engine (not a separate product); the control-plane **Postgres register is the Fleet's register**;
+  workers/runtime are the **Fleet substrate**. **"factory" is RETIRED as a product term** — it was
+  only ever the software-factory concept (which forge implements) and the old `mosaic-factory` tmux
+  socket name. The production-isolation socket is now **`mosaic-fleet`** (matches the product brand);
+  the legacy dogfood canary remains on the old `mosaic-factory` socket pending migration. **Code stays
+  layered** (forge + fleet + control-plane as internal layers);
+  only the **identity + CLI surface unify under Fleet.**
+- **Role-based session naming (Jason, 2026-06-22):** agent tmux sessions are named by **role**
+  (`orchestrator`, `enhancer`, `research`, `coder0-0`, …), not by persona. **Persona lives in
+  `SOUL.md`**; the front-end / Discord presents a **friendly alias** (e.g. "Mos" = the orchestrator's
+  alias). The session name is the stable addressing handle; the alias is presentation.
+
+### Control plane & central register
+
+- **Store:** Postgres (existing stack instance, dedicated `fleet` schema via `@mosaicstack/db`). SQLite rejected: (1) it is a local file — structurally incompatible with a multi-host fleet; (2) concurrent multi-agent writes caused repeated corruption in Hermes. "SQLite + access service" rejected as reinventing a DB server badly; "LLM agent gating DB access" rejected as slow, expensive, and a single point of failure.
+- **Access:** gateway API only (`apps/gateway`, `fleet/*` routes). No raw DB credentials in any agent/dispatcher pane — directly mitigates the tmux attack-surface concern.
+- **Dispatcher = forge (reuse, not a new build):** the dispatcher IS `@mosaicstack/forge`'s pipeline engine (`runPipeline`/`resumePipeline` + brief classifier + BOD persona loader), a fully-implemented software-factory pipeline (brief → BOD review → 3 planning stages → coding → review/remediation → testing → deploy). We do **not** design/build a new dispatcher and do **not** re-implement sequencing, gate logic, or brief classification. The only new fleet-owned piece is a thin **`forge-exec` TaskExecutor adapter** (suggested package `packages/forge-exec`) mapping a `ForgeTask` → `agent-send.sh` dispatch to a named fleet agent — forge's single missing piece. It is tracked as a Gitea issue and built **post-PoC** (not now).
+- **Register backs forge:** the Postgres `fleet` register is genuinely new (neither forge nor the fleet has cross-project state). It BACKS forge's pipeline state (durable `resumePipeline`, cross-host) plus cross-project missions/tasks/Kanban.
+- **'board' role = forge BOD:** the north-star role-library 'board' role IS forge's Board-of-Directors — reused, not reinvented.
+- **Orchestration vs. dispatch:** Orchestrator (Mos) sets intent and handles judgment; forge works the mechanical pipeline (sequencing, gates, status transitions, spend ledger). LLM escalation reserved for judgment: mission decomposition, re-planning on failure.
+- **Spend in the register:** `fleet.spend_ledger` tracks projected vs. actual tokens per agent/mission/task; ties to issue #622.
+- **Docs as projections:** `docs/TASKS.md` and `MISSION-MANIFEST.md` become generated exports of the DB, not hand-maintained.
+- **Sub-decision pending:** dedicated schema in existing PG instance (recommended) vs. dedicated PG instance. Revisit if isolation or write-volume demands it.
+
+## 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.
+- **Matrix on a local homeserver — strategic future transport.** **F4 (in progress) IS the Matrix
+  connector**: an orchestrator chat connector speaking the Matrix client-server API against a
+  self-hosted homeserver (Conduit default, Synapse alt). Matrix is named here as the strategic
+  future transport — peer to tmux/Discord, not superseded by them.
+- **tmux fleet attack-surface hardening.** Many always-on tmux sessions are an attack surface;
+  `tmux send-keys` / socket access could enable malicious action against agents directly.
+  Mitigations to build toward: socket ownership/perms, per-tenant socket isolation (already an
+  invariant), authenticated `agent-send`, and an audit of who can write to any pane. **Post-MVP
+  unless a P0 surfaces.** The control-plane register reinforces this (gateway-API access = no raw
+  DB creds in panes). A not-started risk-assessment + mitigation-plan task rides the Fleet `TASKS.md`.
+
+## Assumptions (veto-able)
+
+- `ASSUMPTION:` first-class runtimes = claude, codex, pi, opencode; a "role" (analyst,
+  finance, researcher) = persona + skills + tools on top of a runtime, shipped as a
+  starter role library in the framework.
+- `ASSUMPTION:` the cross-host control plane is the **federation** layer (W1), not a
+  separate `fleetd` daemon.
+- `ASSUMPTION:` Fleet is workstream **W-FLEET** under `mvp-20260312`; a rollup row in
+  `docs/TASKS.md` and a workstream declaration in `MISSION-MANIFEST.md` are proposed to
+  the MVP orchestrator, not written by this workstream.
+- `ASSUMPTION:` OAuth-subscription runtimes (Claude sub, Codex sub) expose a machine-readable
+  current-usage-vs-limit signal the fleet can poll/ingest; if a provider exposes no such signal,
+  that provider's accounts fall back to API-style hard-ceiling budgeting only (no auto-pacing).
+- `ASSUMPTION:` budget policy lives at the orchestrator + routing layer and is surfaced through the
+  same CLI→TUI→webUI parity (MVP-X1) as the rest of fleet state — not a separate budgeting daemon.
+- `ASSUMPTION:` the 200k session cap is enforced by Claude Code settings/env composition (model
+  variant + `autoCompactWindow`), not by a Mosaic wrapper; a wrapper is the fallback only if the
+  harness later removes those knobs.
+- `ASSUMPTION:` The central register (Postgres `fleet` schema + gateway API + forge as dispatcher) is
+  the Phase 4–5 control plane, begun after Phase 2 observability is proven. It is a dedicated
+  **W-FLEET** sub-workstream entry, not a separate mission. The dispatcher is `@mosaicstack/forge`
+  (reused, not a new daemon); the only new fleet-owned code is the thin **`forge-exec` TaskExecutor
+  adapter** (suggested package `packages/forge-exec`, `ForgeTask` → `agent-send.sh`), tracked as a
+  Gitea issue and built post-PoC.
+
+---
+
+> **Release procedure (drift re-capture, 2026-06-22):** `mosaic update` only propagates new fleet
+> commands when the **CLI version is bumped** — without a version bump, fleet command changes never
+> reach installed hosts. The release/version-bump procedure (bump → publish → `mosaic update`
+> [→ `--relaunch`]) must be documented so fleet changes actually land. (Also feeds the budgeting
+> workstream.)
+>
+> **Tracked separately (not in scope for this doc PR):** **#622** PRD/mission/task projected+actual
+> spend template standard · **#623** anonymized spend telemetry → mosaicstack.dev (product) ·
+> **#625** `tenant_id` roster-schema field (multi-tenant; invariant #1 home) · **#628** `forge-exec`
+> TaskExecutor adapter (post-PoC). This PR records **doctrine only** — no implementation.

docs/guides/fleet-local-canary.md

@@ -1,7 +1,7 @@
 # Local Fleet Canary
 
 The local fleet canary runs a small tmux-backed Mosaic agent fleet on an
-isolated tmux socket. The default socket is `mosaic-factory`; the commands do
+isolated tmux socket. The default socket is `mosaic-fleet`; the commands do
 not use or stop the default tmux server.
 
 ## Files
@@ -67,7 +67,7 @@ mosaic agent tail canary-pi -n 80
 
 These commands read the roster and target the configured tmux socket. The
 generated systemd agent services use `start-agent-session.sh`; message delivery
-uses the tmux send tools with `-L mosaic-factory`.
+uses the tmux send tools with `-L mosaic-fleet`.
 
 `mosaic agent send` is operator-origin traffic unless a caller explicitly says
 otherwise. The CLI always passes a deterministic source label to
@@ -82,7 +82,7 @@ impersonating a known handoff lane. The lower-level inter-agent wrapper
 Use these checks before expanding the roster:
 
 ```bash
-tmux -L mosaic-factory ls
+tmux -L mosaic-fleet ls
 tmux ls
 mosaic fleet verify
 systemctl --user status mosaic-tmux-holder.service
@@ -90,7 +90,7 @@ systemctl --user status mosaic-tmux-holder.service
 
 Expected results:
 
-- `tmux -L mosaic-factory ls` shows `_holder` and roster agent sessions.
+- `tmux -L mosaic-fleet ls` shows `_holder` and roster agent sessions.
 - `tmux ls` shows only the default tmux server sessions and is not changed by
   fleet start/stop operations.
 - `mosaic fleet verify` checks exact session targets on the isolated socket.
@@ -108,7 +108,7 @@ Run this checklist before cutting or dogfooding a fleet release:
   repeated `start` against the named socket; verify the default tmux server is
   unchanged.
 - Liveness verification: run `mosaic fleet verify` and confirm roster sessions
-  with `tmux -L mosaic-factory ls` or exact `has-session` checks.
+  with `tmux -L mosaic-fleet ls` or exact `has-session` checks.
 - Package dry-run: run `npm pack --dry-run --json` from `packages/mosaic` and
   confirm `framework/fleet`, `framework/systemd/user`,
   `framework/tools/fleet`, and `framework/tools/tmux` assets are included.
@@ -140,5 +140,5 @@ This rollback leaves the default tmux server untouched. If a canary session is
 still present after service stop, remove only the isolated socket server:
 
 ```bash
-tmux -L mosaic-factory kill-server
+tmux -L mosaic-fleet kill-server
 ```

docs/scratchpads/2026-06-20-fleet-cli-local-canary.md

@@ -17,7 +17,7 @@ Implement enough product surface to use the fleet locally:
 - roster schema and examples
 - local canary docs and rollback instructions
 - tests for CLI behavior where practical
-- canary verification on named tmux socket `mosaic-factory`
+- canary verification on named tmux socket `mosaic-fleet`
 
 ## Non-goals
 
@@ -30,7 +30,7 @@ Implement enough product surface to use the fleet locally:
 
 - CLI can initialize a minimal roster outside product defaults.
 - CLI can install user systemd units and fleet helper scripts to a configurable Mosaic home.
-- CLI can start/stop/status/verify a canary fleet using `mosaic-factory`.
+- CLI can start/stop/status/verify a canary fleet using `mosaic-fleet`.
 - `mosaic agent send` uses existing named-socket/exact-target tmux tooling.
 - `mosaic agent reset` targets only the named agent session on the named socket.
 - Verification proves default tmux sessions remain untouched.

docs/scratchpads/631-reseed-preserves-fleet.md

@@ -0,0 +1,32 @@
+# #631 — re-seed must preserve user fleet data (CRITICAL data-loss)
+
+- **Issue:** #631 · **Branch:** `fix/631-reseed-preserves-fleet-data`
+
+## Root cause
+
+`mosaic update` auto-runs `install.sh` keep-mode sync (#610). install.sh's rsync `--delete` (keep mode)
+honored PRESERVE_PATHS, but `fleet/` wasn't listed → the sync WIPED `~/.config/mosaic/fleet/roster.yaml`
+(+ run/, agents/). Any user running `mosaic update` lost their roster. (overwrite mode wipes by design;
+the live loss was keep mode.)
+
+## Fix (PRIMARY)
+
+- install.sh PRESERVE_PATHS += `fleet/*.yaml`, `fleet/agents`, `fleet/run` — the framework still SEEDS
+  fleet/examples + fleet/roles + fleet/roster.schema.json (synced), but user files survive.
+- Made the cp-fallback (no-rsync) GLOB-AWARE so `fleet/*.yaml` preserves every user roster there too;
+  fixed the restore to re-glob per-pattern (so only the user file is restored, not the whole fleet/ dir).
+- file-adapter.ts (TS installer): mirrored the preserve list for parity. (TS syncDirectory is copy-only,
+  never --delete, so it never had the bug — belt-and-suspenders + parity.)
+
+## Fix (SECONDARY)
+
+- `refreshActiveFleetUnits()` (update-checker.ts): the re-seed updates ~/.config/mosaic/systemd/user but
+  systemd runs ~/.config/systemd/user, so unit fixes (#627) didn't take effect. After the re-seed,
+  `mosaic update` now copies the fresh mosaic-\*.service → the active dir + daemon-reload (best-effort,
+  only when a fleet is already installed). Wired into the cli.ts update flow.
+
+## Verification
+
+- bash F6 fixture (6 checks: roster/custom-yaml/agents/run survive + examples refreshed + schema seeded);
+  20/20 migration matrix green. TS file-adapter test (roster/run/agents survive keep sync). 2 unit tests
+  for refreshActiveFleetUnits. tsc/eslint/prettier/sanitize clean.

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

@@ -0,0 +1,54 @@
+# #633 — comms-block emitter + FLEET-LAUNCH runbook
+
+Branch: `feat/633-comms-block-runbook` (off `bf2a6745`, post-#632 merge)
+Issue: #633 · Follow-up filed: #636 (PATH B)
+
+## Goal
+
+PATH A of the orchestrator-launch fix: give every launch path the Fleet-Comms onboarding, and
+document the canonical roster-driven launcher so the orchestrator stops being a bespoke snowflake.
+
+## Deliverables
+
+1. **`mosaic fleet comms-block <role> [--host <h>]`** — explicit-arg, comms-block-only emitter.
+   - Backed by new `resolveCommsBlock(mosaicHome, role, fleetHost?)` in `fleet/comms-onboarding.ts`
+     returning `{ ok, output, error }`.
+   - Unlike `readFleetCommsBlock` (returns `''` on any miss so `composeContract` can no-op silently
+     during launch), the emitter **fails loud**: unknown role / missing roster → `ok:false` → CLI
+     prints to stderr + sets `process.exitCode = 1`. A typo is never a silent no-op.
+   - Distinct from `mosaic compose-contract <runtime>` (whole prompt, env-coupled via
+     `MOSAIC_AGENT_NAME`); comms-block is the targeted, explicit-arg, comms-only view.
+2. **`docs/fleet/FLEET-LAUNCH.md`** — worker path + orchestrator `.env` fold + 3 launch gotchas +
+   #632 preserve note + North-Star 4-field arc.
+
+## Key findings (drove the design)
+
+- `mosaic yolo claude` **already** forwards `--channels`/`--permission-mode` to the binary
+  (`launch.ts` claude case `cliArgs.push(...args)`) AND injects the comms block via
+  `composeContract` → `readFleetCommsBlock(home, env.MOSAIC_AGENT_NAME)`. So no `launch.ts` change
+  was needed — PATH A is `.env` + doc only.
+- `start-agent-session.sh` line ~41 `[ -z "$MOSAIC_AGENT_COMMAND" ]` short-circuits the line-44
+  default, so an `.env` `MOSAIC_AGENT_COMMAND` override bypasses the hardcoded `yolo` entirely — the
+  yolo-conditional is therefore a PATH B (default-path) concern, not PATH A.
+- `generateAgentEnv` (`fleet.ts` ~202-207) emits NAME/RUNTIME/MODEL but **not** `MOSAIC_AGENT_COMMAND`
+  — the seam PATH B (#636) closes.
+
+## A → B → webUI arc (North Star)
+
+- A = `.env` `MOSAIC_AGENT_COMMAND` hatch (manual, ships now, #632-safe).
+- B (#636) = roster-native launch-config: harness ✅ + model ✅ already there; add **yolo** (line-44
+  conditional `MOSAIC_AGENT_YOLO`) + **command/channels** (`generateAgentEnv` emission).
+- webUI binds dropdowns/toggles to those four roster fields. One launcher, no new launch path.
+
+## Results
+
+- TDD: spec first (`comms-onboarding.spec.ts`, 6 new `resolveCommsBlock` cases) → red → implement → green.
+- `fleet.spec.ts` subcommand-list assertion extended with `comms-block`.
+- 177 fleet+comms tests green; typecheck clean; eslint clean; prettier clean.
+
+## Risks / notes
+
+- Pre-existing local-only failure `uninstall.spec.ts > removeFramework > handles missing mosaicHome
+gracefully` (EACCES on `/nonexistent` as non-root) — unrelated to #633, passes in CI as root.
+- Did NOT run `mosaic update` / anything auto-reseed: installed CLI still 0.0.40 (roster-wipe live
+  until mos-claude-0 ships 0.0.41). All work is in-repo + vitest, never touches the live mosaic home.

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,30 @@
+# F4 — Orchestrator chat connector + Matrix (#616)
+
+- **Issue:** #616 · **Branch:** `feat/f4-matrix-connector` (off main; independent of #615) · **Doctrine:** north-star #613.
+
+## Phase 1 (this PR) — abstraction + scaffold
+
+- `src/fleet/connectors/types.ts`: `OrchestratorConnector` (send/subscribe/health) + message/config types; thread-aware via optional `threadId`; `DEFAULT_CONNECTOR_KIND=tmux`.
+- `src/fleet/connectors/registry.ts`: extensible factory registry; `resolveConnectorKind` (defaults tmux, back-compat); `createConnector` throws `ConnectorNotImplementedError` until Phase 2 registers factories.
+- `roster.schema.json`: optional `connector` block (tmux|discord|matrix; matrix homeserver/user/room; secrets via env, never roster).
+- Design doc `docs/fleet/f4-matrix-connector.md`: interface, config, Matrix CS-API mapping, Conduit-default infra, phasing.
+- **No fleet.ts changes** → self-contained, zero conflict with stacked #615.
+
+## Verification
+
+- 7 connector tests green; tsc/eslint/prettier/sanitize clean; schema valid JSON.
+
+## Phase 2+ (follow-ups, in the doc)
+
+Matrix CS-API client (fetch send/sync/health) + factory; init/configure connector-selection UX + roster-parse wiring; systemd launch wiring; Conduit deploy guide; first-party Mosaic Discord (threads) as a connector.
+
+## Phase 2a (feat/f4-matrix-client, stacked on #617) — Matrix CS-API client
+
+- `src/fleet/connectors/matrix.ts`: `MatrixConnector implements OrchestratorConnector` over the Matrix
+  client-server API (injectable fetch, no SDK). `send` → PUT m.room.message (thread-aware); `subscribe`
+  → /sync long-poll loop using the pure `parseSyncResponse`; `health` → /versions + /whoami.
+  `registerMatrixConnector(env)` registers the factory (token from MATRIX_ACCESS_TOKEN, never roster).
+- Pure helpers `buildMessageBody` + `parseSyncResponse` make send/receive unit-testable.
+- 13 Matrix tests + 7 registry = 20 connector tests green; tsc/eslint/prettier clean.
+- Remaining Phase 2: init/configure connector-selection UX + roster-parse wiring (touches fleet.ts —
+  after #615); systemd launch wiring; Conduit deploy guide.

docs/scratchpads/fleet-comms-onboarding.md

@@ -0,0 +1,31 @@
+# Fleet onboarding-injection — comms cheat-sheet + peer roster (#620)
+
+- **Issue:** #620 · **Branch:** `feat/fleet-comms-onboarding` (off main). Root cause of Mos's failed first send.
+
+## What
+
+Inject a `# Fleet Comms` block into each spawned fleet agent's system prompt (via composeContract — the
+runtime-agnostic path every `mosaic yolo <runtime>` agent hits), so it boots knowing how to reach peers.
+
+- `src/fleet/comms-onboarding.ts` (standalone, no fleet.ts coupling):
+  - `parseRosterAgents` (name/class/host/ssh, lenient), `renderPeerReach` (same-host `-s` vs cross-host
+    `-H <ssh> -s`), `buildFleetCommsBlock` (self [host:session] identity + agent-send path + peer table +
+    FLIP-to-reply + `agent send --verify`=ACCEPTED), `readFleetCommsBlock` (reads roster.yaml; '' if not a member).
+  - `composeContract` appends it only when MOSAIC_AGENT_NAME is set + the agent is in the roster.
+- `roster.schema.json`: optional per-agent `host` + `ssh` (cross-host addresses; manual = pre-federation
+  stopgap, federation/W1 auto-discovers later).
+
+## Acceptance criteria (Mos) — all covered
+
+1. own [host:session] + agent-send path + peer roster ✓
+2. cross-host correctness: local→`-s` (no -H); remote→`-H <ssh> -s` ✓ (concrete coder0-0@dragon-lin)
+3. FLIP-the-preamble reply rule ✓
+4. `agent send --verify` = ACCEPTED ✓
+5. no `-L` (default socket); matches live tooling ✓
+
+## Verification
+
+- 10 onboarding unit tests (parse, render local/remote/fallback/equal-host, build, situational read) +
+  2 composeContract situational tests (injects for fleet agent w/ correct cross-host addr; no-op when
+  MOSAIC_AGENT_NAME unset). tsc/eslint/prettier/sanitize clean.
+- Post-merge validation: Mos spawns a real w-jarvis agent → first-try reach to coder0-0@dragon-lin + a local peer.

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.

docs/scratchpads/fleet-observability-phase2.md

@@ -0,0 +1,100 @@
+# Scratchpad — Fleet Phase 2: Observability (W-FLEET)
+
+> Append-only. Mission `mvp-20260312` / workstream W-FLEET.
+> Lead: Jarvis (Claude) at `W-jarvis:mos-claude-18`. Coordinating with `jwoltje@dragon-lin:coder0-0`.
+
+## Mission prompt (2026-06-20)
+
+Establish the north star for the Mosaic Fleet feature and prepare Phase-2 observability
+for delivery. The USC tmux PoC is the proven base. Jason granted lead authority:
+"The fleet is a great way to actually build the MVP — we are building the system that
+builds the system." Dogfood actual agent construction + ad-hoc deployment; coordinate
+with a second agent on `dragon-lin`.
+
+## Decisions of record (with Jason, 2026-06-20)
+
+- Agent model: config defines, session runs (gateway = definition/identity/auth; tmux = runtime).
+- Tenancy: multi-tenant from the start; isolation = per-tenant Linux uid.
+- Health: heartbeat required; dogfood stub implements protocol now.
+- Lifecycle: hybrid (core always-on + ephemeral workers).
+- Observation: read-only default, opt-in takeover.
+- Multi-host: designed-for day one; control plane rides federation (W1), not a bespoke broker.
+- Delivery: CLI-first, dogfood on the live stub fleet; webUI deferred to Phase 5.
+- Fleet is dual-role: product AND means of production (bootstrapping the MVP).
+- Code review = **dual-engine**: Claude **and** gpt-5.5/Codex, run together (Jason: the
+  combination produces the best results). Launch reviewers via `mosaic yolo pi` / `codex`
+  (proven path) or `~/.config/mosaic/tools/codex/codex-code-review.sh`. Applies to all
+  code-review gates incl. FLEET-OBS-008. Per Jason 2026-06-20.
+- Worktree discipline: do fleet work in `~/src/mosaicstack-stack-worktrees/<branch>`, NOT
+  the shared main checkout — concurrent processes mutate `main` there (learned 2026-06-20).
+
+## Environment facts (verified 2026-06-20)
+
+- Fleet is live on `W-jarvis` (uid 1000, `jarvis`, `Linger=yes`) on tmux socket
+  `mosaic-fleet`: `_holder`, `canary-pi`, `dogfood-coder`, `dogfood-orchestrator`,
+  `dogfood-reviewer`. All panes run `~/.config/mosaic/fleet/dogfood-agent.py` (stub),
+  including `canary-pi` (roster says runtime=pi → **drift**).
+- Holder + `mosaic-agent@*` units are `active (exited)` but `UnitFileState=disabled`
+  (reboot loses fleet → boot-enable gap to surface).
+- Observation blocked by: isolated socket (hidden from default `tmux ls`), `capture-pane`
+  blank for TUIs, `attach` being read-write + resizing.
+- Second agent: `jwoltje@dragon-lin`, session `coder0-0` (group `coder0`), running `node`,
+  default socket. ssh forward reach confirmed.
+
+## Governance / collision-safety
+
+- `mosaicstack-stack` has active mission `mvp-20260312` with single-writer locks on
+  `docs/MISSION-MANIFEST.md`, `docs/TASKS.md`, `docs/scratchpads/mvp-20260312.md`.
+- This workstream touches NONE of those. All Fleet docs scoped under `docs/fleet/` +
+  this scratchpad. Rollup row proposed, not written.
+
+## Session log
+
+- 2026-06-20: Researched AI guide + fleet code + live state. Established north star with
+  Jason (8 forks decided). Branched `feat/fleet-observability`. Persisted
+  `docs/fleet/{north-star.md,PRD.md,TASKS.md}` + this scratchpad. Next: establish comms
+  with dragon-lin coder, commit docs, begin Phase-2 delivery (heartbeat + `fleet ps`).
+- 2026-06-20 (session 2): Built Phase-2 CLI via worker (commit ab47831): `fleet ps`,
+  `agent watch`, `agent send --verify`, 62 tests. LIVE-verified `fleet ps` on
+  mosaic-fleet — correctly flagged canary-pi DRIFT + BOOT-ENABLE, tenant_id+host in JSON.
+  Heartbeat responder added to dogfood-agent.py (FLEET-OBS-002) — `fleet ps` HB now
+  `healthy` for all 4 agents.
+- Coordination: dual-engine-reviewed (Claude+Codex) and merged framework PRs #572
+  (sanitization gate) + #575 (CONSTITUTION extraction) as Lead. Codex caught an Alpine
+  blocker on #572 (refuted by CI); Claude caught a CI-breaking format failure on #575.
+- **FINDINGS (north-star / Phase-3 blockers):**
+  1. Ad-hoc `mosaic yolo {codex,pi}` via `start-agent-session.sh` DIE immediately in a
+     detached tmux pane (codex: "stdin is not a terminal"; pi: same). Only the python stub
+     survives. => Real runtimes have NEVER run durably in the fleet. Launch path (PATH/TTY
+     in the detached shell) must be fixed before Phase-3 real-runtime swap. `fleet ps`
+     caught both dead panes instantly (tool validated).
+  2. `MOSAIC_AGENT_NAME` (set in systemd EnvironmentFile) is NOT propagated into tmux's
+     global env, so agents defaulted to `unknown`. Worked around in dogfood-agent.py via
+     tmux session-name fallback; the systemd/tmux env handoff needs a real fix.
+- Next: rebase on merged main, open Phase-2 PR, dual-engine review, merge, close
+  `fleet-observability-1`. Defer launch-path + env-propagation fixes to Phase 3.
+- 2026-06-21 (session 3): Phase-2 PR #579 merged (3 dual-engine rounds hardened
+  verify+watch). Then closed the launch-path question with Jason's input — CORRECTING
+  earlier findings:
+  - The ad-hoc launch deaths were NOT a fundamental TTY blocker: (a) codex was a stale
+    version (Jason updated it); (b) pi was misconfigured to Claude auth (Jason removed it;
+    default is now Codex). The REAL durable-launch bug is **PATH**: the detached tmux
+    launch shell is login+non-interactive, so it misses `~/.npm-global/bin` (added only in
+    `~/.bashrc`) -> `mosaic: command not found` (127) -> pane dies. tmux panes inherit the
+    tmux _server_ env, so PATH must be baked into the pane command.
+  - **Durable real-agent recipe (validated live on gpt-5.5, Claude-free):**
+    `mosaic yolo pi --model openai-codex/gpt-5.5:high` — pi tolerates detached tmux; a raw
+    interactive TUI (codex CLI) exits without an attached client. Status line confirmed
+    `(openai-codex) gpt-5.5 • high`.
+  - PATH fix landed in `start-agent-session.sh` (commit 32efc13, branch
+    feat/fleet-launch-path): derive runtime-bin prefix (MOSAIC_RUNTIME_BIN | npm prefix |
+    ~/.npm-global/bin | ~/.local/bin), bake `export PATH=...; exec <cmd>` into the pane;
+    `exec` also fixes the drift false-positive. Live-tested under stripped PATH -> durable.
+  - Boot-survival: Jason ran `systemctl --user enable` (+ linger). TODO: auto-enable in
+    **fleet init** so operators never have to remember it (agentic-enhancement cycle).
+  - Future custom Pi harness build: pi cannot self-report its model (track
+    runtime/model/effort as fleet metadata); drift detection should recognize `node` as
+    pi's pane command (a node-wrapped pane can currently read as drift).
+  - Findings recorded in AI Guide playbooks/tmux-fleet.md (aiguide PR #7, merged).
+  - Policy: avoid Claude outside Claude Code (API pricing for alt-harness use) — fleet
+    runtimes default to Codex / pi-on-Codex; Claude stays in Claude Code only.

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.

docs/scratchpads/fleet-standup-fixes.md

@@ -0,0 +1,28 @@
+# Fleet stand-up fixes — model_hint→--model + socket-default trap (#626)
+
+- **Issue:** #626 · **Branch:** `feat/fleet-standup-fixes` (off main). PoC-blocking, before doctrine doc.
+
+## FIX 1 — model_hint consumed
+
+- generateAgentEnv emits `MOSAIC_AGENT_MODEL=<modelHint>` (bare empty when unset).
+- start-agent-session.sh default command → `mosaic yolo $RUNTIME ${MOSAIC_AGENT_MODEL:+--model $MOSAIC_AGENT_MODEL}`.
+  → pi workers launch with `--model openai-codex/gpt-5.5:high`.
+
+## FIX 2 — socket default trap (absent ⇒ literal default socket, no -L everywhere)
+
+- THE TRAP (3 sites): parseRosterText fallback was DEFAULT_SOCKET_NAME; systemd unit had
+  `Environment=MOSAIC_TMUX_SOCKET=mosaic-fleet` + `ExecStop ${…:-mosaic-fleet}`; start-agent-session
+  defaulted `:-mosaic-fleet`. All fixed → absent socket = '' = default tmux socket (no -L).
+- `socketArgs(name)` helper → `name ? ['-L', name] : []`; replaced all ~15 -L render sites in fleet.ts.
+- shellEnvValue('') now emits a **bare** `VAR=` (not `''`) — unambiguous empty in systemd EnvironmentFile
+  (a quoted '' could become a literal socket named "''").
+- start-agent-session.sh: `_tmux` wrapper passes -L only when socket set; mosaic-agent@.service: dropped the
+  socket default + conditional ExecStop. So spawn == observe == onboarding cheat-sheet.
+- CONTAINMENT: all 6 shipped presets set socket_name: mosaic-fleet explicitly → unaffected; only
+  socket-less rosters (the PoC) get default-socket behavior. DEFAULT_SOCKET_NAME exported for explicit use.
+
+## Verification
+
+- 158 fleet + 201 fleet-adjacent tests green; new: socketArgs none/named, model_hint→env, explicit-socket
+  renders -L, socket-less env bare. tsc/eslint/prettier/sanitize clean. Shell bash -n + end-to-end sim
+  (socket-less→no -L, model→--model).

docs/scratchpads/h1-heartbeat-readiness.md

@@ -0,0 +1,66 @@
+# H1 — heartbeat readiness detection
+
+## Objective
+
+Add runtime-agnostic readiness classification to `mosaic fleet ps` so an agent can be reported as working/idle/stuck/stale/dead/unknown instead of treating pane liveness as progress.
+
+## Scope
+
+- `packages/mosaic/src/commands/fleet.ts`
+  - exported readiness state/types/default thresholds/helpers/classifier
+  - `AgentPsRow.readiness` additive JSON field
+  - table HB column and IDLE/STUCK flags
+- `packages/mosaic/src/commands/fleet.spec.ts`
+  - pure classifier branch/boundary coverage
+  - threshold helper coverage
+  - legitimate render/JSON assertion updates for new HB text
+
+## Acceptance Criteria
+
+- Branches covered: dead, unknown, stale, busy working, null-idle working, stuck boundary, idle boundary, working below idle.
+- Threshold env helpers default to 300s/900s and honor positive integer env values.
+- `fleet ps` rows populate `readiness` for roster and unmanaged socket sessions.
+- Table HB text becomes `<age>s/<readiness>` when heartbeat age exists; remains `unknown` when absent.
+- Flags include `IDLE`/`STUCK` for matching readiness.
+- Local gates green: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, fleet vitest.
+- Pre-push queue guard passes; PR opened off `origin/main`; no merge by worker.
+
+## Constraints / Assumptions
+
+- Source branch: `origin/main` @ `e3adc6a`.
+- No scope creep beyond readiness detection.
+- `docs/TASKS.md` and `docs/fleet/TASKS.md` are orchestrator-owned; worker will not modify them.
+- PRD alignment source: `docs/fleet/PRD.md` Phase 2 observability; this is a refinement of heartbeat observability, preserving existing unknown/stale behavior.
+
+## Plan
+
+1. Install dependencies with requested PNPM environment.
+2. Add readiness types/helpers/classifier near heartbeat constants.
+3. Add `readiness` to `AgentPsRow` and populate both row paths.
+4. Update table render and flags.
+5. Add unit tests and update affected ps render/JSON assertions.
+6. Run build precheck + required gates.
+7. Run automated independent review, remediate findings.
+8. Queue guard, push, open PR.
+
+## Progress
+
+- 2026-06-24: Branch created from `origin/main` @ `e3adc6a`.
+- 2026-06-24: Implemented readiness thresholds/classifier, JSON row field, HB column label, and IDLE/STUCK flags.
+- 2026-06-24: Added classifier branch/boundary tests, threshold helper tests, JSON shape assertions, and readiness table rendering assertions.
+
+## Verification Evidence
+
+- `pnpm install --store-dir "$HOME/.pnpm-store"` — pass.
+- `npx turbo build --filter=@mosaicstack/mosaic^...` — pass, 12/12 tasks successful.
+- `pnpm typecheck` — pass, 41/41 tasks successful.
+- `pnpm lint` — pass, 23/23 tasks successful.
+- `pnpm format:check` — pass, all matched files use Prettier style.
+- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — pass, 171 tests.
+- `pnpm --filter @mosaicstack/mosaic test` — pass, 39 files / 547 tests; `fleet.spec.ts` 171 tests.
+- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings (reviewed supplied diff; sandbox file-inspection limitation noted by tool).
+
+## Risks / Blockers
+
+- No current blocker.
+- Review tool could not inspect repo files directly due sandbox wrapper limitation, but it reviewed the supplied diff and approved with no findings.

docs/scratchpads/h1b-pane-idle-signal.md

@@ -0,0 +1,53 @@
+# H1b — tmux pane idle signal wiring
+
+## Objective
+
+Feed `classifyReadiness()` a real idle signal on tmux 3.4 by deriving `idleSeconds` from the first available tmux timestamp source: pane activity, then window activity, then session activity.
+
+## Scope
+
+- `packages/mosaic/src/commands/fleet.ts`
+  - Extend `buildTmuxListPanesCommand()` format to include `#{window_activity}` and `#{session_activity}` after the existing fields.
+  - Update `parseTmuxListPanes()` to choose the first non-empty finite positive timestamp and clamp future idle values to 0.
+- `packages/mosaic/src/commands/fleet.spec.ts`
+  - Cover pane/window/session activity parsing behavior, empty-field index alignment, null idle, future clamping, math correctness, and exact tmux format.
+
+## Out of Scope
+
+- No changes to `classifyReadiness()`, thresholds, `AgentPsRow`, or `fleet ps` rendering.
+- No merge by worker; orchestrator routes review/merge.
+- Workers do not modify `docs/TASKS.md`.
+
+## PRD Alignment
+
+Aligned with `docs/fleet/PRD.md` FR-1 and acceptance criteria for truthful `mosaic fleet ps` pane/pid/idle observability.
+
+## Plan
+
+1. Sync branch from latest `origin/main` and install dependencies with required pnpm env.
+2. Add/confirm reproducer tests for tmux 3.4 empty `pane_activity` and new fallback behavior.
+3. Implement the focused parser/format change only.
+4. Run required build, baseline gates, fleet vitest, and independent review.
+5. Run pre-push queue guard, push branch, and open PR to `main` with Mosaic wrapper.
+
+## Progress
+
+- 2026-06-24: Branch `fix/fleet-pane-idle-activity` created from `origin/main` @ `ec8dd7c` after fetching.
+- 2026-06-24: Session-start generated local `.mosaic/orchestrator/*` changes on the previous release branch; stashed as `coder1 session-start state before H1b` to keep this branch clean.
+- 2026-06-24: Added TDD coverage for the tmux 3.4 production case (`pane_activity` empty, `window_activity` populated), exact new list-panes format, null/future/multiple-source behavior.
+- 2026-06-24: Implemented parser fallback without changing readiness classifier thresholds or render shape.
+
+## Verification Evidence
+
+- `pnpm install --store-dir "$HOME/.pnpm-store"` — pass.
+- Reproducer before implementation: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — failed as expected (old format, no fallback, negative future idle).
+- `npx turbo build --filter=@mosaicstack/mosaic^...` — pass, 12/12 tasks successful.
+- `pnpm typecheck` — pass, 41/41 tasks successful.
+- `pnpm lint` — pass, 23/23 tasks successful.
+- `pnpm format:check` — pass, all matched files use Prettier style.
+- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — pass, 176 tests.
+- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings (reviewed supplied diff; sandbox file-inspection limitation noted by tool).
+
+## Risks / Blockers
+
+- No current blocker.

docs/scratchpads/h2-readiness-available.md

@@ -0,0 +1,70 @@
+# H2 — readiness semantics: available, not stuck
+
+## Objective
+
+Correct fleet readiness semantics so a healthy long-idle agent is reported as `available` (good/assignable) instead of `stuck` (fault). Reserve `stuck` in the type/JSON value space for future positive block evidence.
+
+## Scope
+
+- `packages/mosaic/src/commands/fleet.ts`
+  - replace `idle` readiness state with `available`
+  - keep `stuck` in the union but stop emitting it from idle-only heuristics
+  - remove stuck threshold helper/env handling
+  - remove IDLE/STUCK alarm flags from table rendering
+- `packages/mosaic/src/commands/fleet.spec.ts`
+  - update classifier branch/boundary tests
+  - assert very long idle maps to `available`, not `stuck`
+  - update table/JSON assertions for available with no alarm flags
+  - remove stuck threshold helper tests
+
+## Acceptance Criteria
+
+- `classifyReadiness()` remains pure/total/never-throw and maps:
+  - dead/stale/unknown unchanged
+  - busy/null/undefined/non-finite idle to `working`
+  - idle >= activity threshold to `available`
+  - idle < activity threshold to `working`
+- No idle-derived path emits `stuck`.
+- `MOSAIC_HEARTBEAT_IDLE_THRESHOLD` remains backward compatible as the working→available activity threshold.
+- `MOSAIC_HEARTBEAT_STUCK_THRESHOLD` and helper/default are removed.
+- `fleet ps` keeps the idle-seconds column header `IDLE`, renders `available` in HB label, and does not add IDLE/STUCK warning flags.
+- Local gates green: build precheck, typecheck, lint, format:check, fleet vitest.
+- PR opened against `main`; no merge by worker.
+
+## Constraints / Assumptions
+
+- Source branch: `origin/main` @ `1020cfa`.
+- `docs/TASKS.md` is orchestrator-owned; worker will not modify it.
+- Documentation impact is captured in this scratchpad and PR description; no user/admin guide behavior beyond CLI readiness label semantics.
+
+## Plan
+
+1. Install dependencies with requested PNPM environment.
+2. Inspect current H1/H1b readiness implementation and tests.
+3. Update classifier types/helpers/rendering.
+4. Update focused tests.
+5. Run build precheck + required gates.
+6. Run automated code review, remediate any findings.
+7. Queue guard, push, open PR.
+
+## Progress
+
+- 2026-06-24: Branch created from `origin/main` @ `1020cfa`.
+- 2026-06-24: Replaced idle-derived `idle`/`stuck` outputs with `available`; retained `stuck` in type union for future positive block evidence.
+- 2026-06-24: Removed stuck threshold env/helper plumbing and IDLE/STUCK alarm flags.
+- 2026-06-24: Updated classifier and table-render tests for available semantics.
+
+## Verification Evidence
+
+- `pnpm install --store-dir "$HOME/.pnpm-store"` — pass.
+- `npx turbo build --filter=@mosaicstack/mosaic^...` — pass, 12/12 tasks successful.
+- `pnpm typecheck` — pass, 41/41 tasks successful.
+- `pnpm lint` — pass, 23/23 tasks successful.
+- `pnpm format:check` — pass, all matched files use Prettier style.
+- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — pass, 177 tests.
+- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings (reviewed supplied diff; sandbox file-inspection limitation noted by tool).
+
+## Risks / Blockers
+
+- No current blocker.
+- Review tool could not inspect repo files directly due sandbox wrapper limitation, but it reviewed the supplied diff and approved with no findings.

docs/scratchpads/north-star-doctrine.md

@@ -0,0 +1,19 @@
+# north-star doctrine consolidation (#620-adjacent doc PR)
+
+- **Branch:** `feat/north-star-doctrine` (off main). Source: Mos's consolidated handoff + 2 drafts (budgeting/200k/delegation + control-plane). ONE conflict-free PR per the merge-map.
+
+## Applied (merge-map, in order)
+
+1. Stack table: +2 rows (Central register, Budget/spend governance) after Control plane + PoC-socket-hygiene note.
+2. `## Budget & token governance` after Invariants (even-spread pacing [Jason override], hard-cap ladder, multi-sub auto-routing, historical learning, #558 CLI UX) + TTY OPS INVARIANT note.
+3. `## Control plane & central register` after Observation model (Postgres fleet schema, gateway-API access, dispatcher = forge pipeline engine + forge-exec adapter [NOT a daemon], register backs forge, board = forge BOD).
+4. Phased roadmap Phase 4/5 annotated (fleet schema migration + forge-exec; central register live).
+5. Decisions of record (2026-06-22): doctrine §1(c) bullets (200k cap, worker bound #8, delegation, budget, spend mandate, unified identity Fleet, role-based session naming) + control-plane 6c `### Control plane & central register` subgroup.
+6. Future enhancements: Matrix-future-transport (#10, F4 IS Matrix) + tmux security hardening (§5).
+7. Assumptions: doctrine §1(d) (3) + control-plane 6e (1) + release-procedure note + tracked-separately note.
+
+## Conflict checklist: all ✓
+
+1 Decisions-2026-06-22; order Invariants→Budget→Observation→Control plane→Roadmap; 2 stack rows; even-spread (no opportunistic/HOLD); control-plane UNHELD; forge-exec = tracked #628 post-PoC; §7 drift re-captures all present (#8/#10/#558/TTY/release).
+
+## Out of scope (cited in doc + PR): #622 (spend template std), #623 (telemetry product), #625 (tenant_id schema), #628 (forge-exec adapter). Doctrine only — no implementation.

docs/scratchpads/p5-overlay-composer.md

@@ -0,0 +1,43 @@
+# P5 — Overlay composer + cross-harness (compose-contract)
+
+- **Issue:** #604 · **Branch:** `feat/p5-overlay-composer` · **Lineage:** #542 → constitution alpha
+- **Requirements:** R7 (compose-contract) + R8 (cross-harness) + R9 (composer test)
+- **Design of record:** `docs/design/framework-constitution/{DESIGN.md §3.2, PRD.md §4}` (on `feat/framework-constitution-alpha`)
+
+## Locked design (sequential-thinking)
+
+Current `launch.ts` assembly (`buildComposedPrompt`) injects by value: mission + PRD + hard-gate +
+CONSTITUTION + AGENTS + USER + TOOLS + runtime. It does **not** inject SOUL or STANDARDS (those are
+read-on-demand per the gutted AGENTS dispatcher), and has no `.local` overlay support.
+
+**Decision (ASSUMPTION — recorded for the PR):** overlays are injected as **deltas by value** under
+labeled sections; base files keep their existing residency.
+
+- `USER.local.md` → appended directly under the `# User Profile` block (USER is injected).
+- `SOUL.local.md` + `STANDARDS.local.md` → a trailing `# Operator Overlays` section (their bases are
+  load-on-demand, so only the small delta is injected — not the full base prose).
+- **Why:** honors DESIGN §3.2 ("model gets one pre-merged blob, no read-merge ritual") while preserving
+  the P3 byte-budget tiering (don't re-inject large SOUL/STANDARDS prose). Precedence order kept: base
+  layers first, operator overlays at recency.
+- Base-only is automatic when a `.local` file is absent (`readOptional`).
+
+## Plan
+
+| #   | Task                                                                                                   | File                                    |
+| --- | ------------------------------------------------------------------------------------------------------ | --------------------------------------- |
+| 1   | Extract `composeContract({harness, mosaicHome})` pure fn; `buildComposedPrompt` delegates              | `src/commands/launch.ts`                |
+| 2   | Overlay logic (USER.local under profile; SOUL/STANDARDS.local in `# Operator Overlays`)                | `src/commands/launch.ts`                |
+| 3   | `mosaic compose-contract <harness>` command → prints blob to stdout                                    | `src/commands/launch.ts`                |
+| 4   | Bare-launch overlay nudge in self-load fallback                                                        | `framework/defaults/AGENTS.md`          |
+| 5   | `compose-contract.spec.ts`: per-tier anchor, Tier-3 byte-equality, overlay present/absent, per-harness | `src/commands/compose-contract.spec.ts` |
+
+## Deferred to P6
+
+CONTRIBUTING.md + harness×gate compliance matrix; resident line-count CI ceiling; `aiguide` reconcile;
+alpha tag `mosaic-vX.Y.Z-alpha`.
+
+## Status
+
+- [x] Phase scaffold (branch, issue #604, scratchpad, TASKS)
+- [ ] Implementation (tasks 1–5)
+- [ ] prettier + vitest green; PR via wrapper → Lead (rides 0.0.39; 0.0.38 mid-cut)

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.

eslint.config.mjs

@@ -28,6 +28,7 @@ export default tseslint.config(
             'apps/web/e2e/helpers/*.ts',
             'apps/web/playwright.config.ts',
             'apps/gateway/vitest.config.ts',
+            'packages/db/vitest.config.ts',
             'packages/storage/vitest.config.ts',
             'packages/mosaic/__tests__/*.ts',
             'tools/federation-harness/*.ts',

packages/db/drizzle/0011_bitter_gateway.sql

@@ -0,0 +1,22 @@
+CREATE TYPE "public"."backlog_status" AS ENUM('ready', 'claimed', 'blocked', 'done');--> statement-breakpoint
+CREATE TABLE "backlog" (
+	"id" text PRIMARY KEY NOT NULL,
+	"title" text NOT NULL,
+	"body" text,
+	"phase" text,
+	"priority" integer DEFAULT 0 NOT NULL,
+	"status" "backlog_status" DEFAULT 'ready' NOT NULL,
+	"depends_on" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"claim_owner" text,
+	"claim_ttl_seconds" integer,
+	"claimed_at" timestamp with time zone,
+	"attempts" integer DEFAULT 0 NOT NULL,
+	"idempotency_key" text,
+	"acceptance" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX "backlog_status_priority_idx" ON "backlog" USING btree ("status","priority");--> statement-breakpoint
+CREATE INDEX "backlog_status_claimed_at_idx" ON "backlog" USING btree ("status","claimed_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "backlog_idempotency_key_idx" ON "backlog" USING btree ("idempotency_key");

packages/db/drizzle/meta/_journal.json

@@ -78,6 +78,13 @@
       "when": 1745366400000,
       "tag": "0010_federation_enrollment_tokens",
       "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1782310438919,
+      "tag": "0011_bitter_gateway",
+      "breakpoints": true
     }
   ]
-}
+}

packages/db/src/backlog.spec.ts

@@ -0,0 +1,263 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { sql } from 'drizzle-orm';
+import { createPgliteDb } from './client-pglite.js';
+import { runPgliteMigrations } from './migrate.js';
+import type { DbHandle } from './client.js';
+import { BacklogService } from './backlog.js';
+import { backlog } from './schema.js';
+
+// Helper: backdate a claim's claimed_at by 1 hour so it is past any short TTL.
+function sqlBackdate(id: string) {
+  return sql`UPDATE ${backlog} SET claimed_at = now() - interval '1 hour' WHERE ${backlog.id} = ${id}`;
+}
+
+/**
+ * Real Postgres semantics, no external server: embedded in-memory PGlite.
+ * The migration path creates the `backlog` table (and every other table) so the
+ * service runs against the actual generated schema, including the row locks the
+ * atomic-claim path depends on.
+ */
+async function freshService(): Promise<{ handle: DbHandle; svc: BacklogService }> {
+  const handle = createPgliteDb('memory://');
+  await runPgliteMigrations(handle);
+  return { handle, svc: new BacklogService(handle.db) };
+}
+
+describe('BacklogService', () => {
+  let handle: DbHandle;
+  let svc: BacklogService;
+
+  beforeEach(async () => {
+    ({ handle, svc } = await freshService());
+  });
+
+  afterEach(async () => {
+    await handle.close();
+  });
+
+  it('create then list returns the card', async () => {
+    await svc.create({ id: 'c1', title: 'First card', phase: 'M1', priority: 5 });
+    const all = await svc.list();
+    expect(all).toHaveLength(1);
+    expect(all[0]).toMatchObject({ id: 'c1', title: 'First card', phase: 'M1', status: 'ready' });
+  });
+
+  it('idempotency_key dedups create', async () => {
+    const a = await svc.create({ id: 'c1', title: 'one', idempotencyKey: 'k-1' });
+    const b = await svc.create({ id: 'c2', title: 'two', idempotencyKey: 'k-1' });
+    expect(b.id).toBe(a.id);
+    const all = await svc.list();
+    expect(all).toHaveLength(1);
+  });
+
+  it('list filters by status and phase', async () => {
+    await svc.create({ id: 'c1', title: 'a', phase: 'M1' });
+    await svc.create({ id: 'c2', title: 'b', phase: 'M2' });
+    await svc.block('c2');
+    expect(await svc.list({ phase: 'M1' })).toHaveLength(1);
+    expect(await svc.list({ status: 'blocked' })).toHaveLength(1);
+    expect((await svc.list({ status: 'blocked' }))[0]!.id).toBe('c2');
+  });
+
+  describe('atomic claim', () => {
+    it('two concurrent claimers on one card => exactly one wins', async () => {
+      await svc.create({ id: 'only', title: 'the one', priority: 10 });
+
+      // Two independent claimers race for the single ready card on the same db.
+      // The atomic claim path (`FOR UPDATE SKIP LOCKED` inside a transaction)
+      // guarantees the loser's locked row is skipped, so it can never also flip
+      // the card to claimed — it gets the next candidate (none) and returns null.
+      const svcA = new BacklogService(handle.db);
+      const svcB = new BacklogService(handle.db);
+
+      const [a, b] = await Promise.all([
+        svcA.claim({ owner: 'worker-A' }),
+        svcB.claim({ owner: 'worker-B' }),
+      ]);
+
+      const winners = [a, b].filter((c) => c !== null);
+      expect(winners).toHaveLength(1);
+      expect(winners[0]!.id).toBe('only');
+      expect(winners[0]!.status).toBe('claimed');
+      expect(['worker-A', 'worker-B']).toContain(winners[0]!.claimOwner);
+
+      const card = await svc.get('only');
+      expect(card!.status).toBe('claimed');
+      expect(card!.attempts).toBe(1);
+    });
+
+    it('many concurrent claimers on N cards => no card is double-claimed', async () => {
+      // 5 ready cards, 8 concurrent claimers. Exactly 5 win, all distinct.
+      for (let i = 0; i < 5; i++) {
+        await svc.create({ id: `card-${i}`, title: `card ${i}`, priority: i });
+      }
+      const claimers = Array.from({ length: 8 }, (_, i) =>
+        new BacklogService(handle.db).claim({ owner: `w-${i}` }),
+      );
+      const results = await Promise.all(claimers);
+      const won = results.filter((c): c is NonNullable<typeof c> => c !== null);
+      const wonIds = won.map((c) => c.id);
+      expect(won).toHaveLength(5);
+      expect(new Set(wonIds).size).toBe(5); // all distinct — no double-claim
+    });
+
+    it('N concurrent claimers on N ready cards => every claimer wins a distinct card (no starvation)', async () => {
+      // This is the direct benefit of locking exactly ONE ready row per claim
+      // (`FOR UPDATE SKIP LOCKED LIMIT 1`): with as many ready cards as
+      // claimers, NONE should starve. The old "lock the whole ready set"
+      // behaviour let one claimer lock every row, forcing the rest to null even
+      // though cards were free.
+      const N = 6;
+      for (let i = 0; i < N; i++) {
+        await svc.create({ id: `n-${i}`, title: `card ${i}`, priority: i });
+      }
+      const results = await Promise.all(
+        Array.from({ length: N }, (_, i) =>
+          new BacklogService(handle.db).claim({ owner: `w-${i}` }),
+        ),
+      );
+      const won = results.filter((c): c is NonNullable<typeof c> => c !== null);
+      // No claimer starved: all N won.
+      expect(won).toHaveLength(N);
+      // Each won a distinct card.
+      expect(new Set(won.map((c) => c.id)).size).toBe(N);
+      // Every ready card was consumed.
+      expect(await svc.list({ status: 'ready' })).toHaveLength(0);
+    });
+
+    it('sequential claims drain ready cards in priority order and never null while ready remain', async () => {
+      // PGlite-stable fallback assertion of the same property without relying on
+      // true parallelism or wall-clock timing: each claim returns the next
+      // highest-priority distinct card and never spuriously returns null while
+      // ready cards remain.
+      const N = 4;
+      for (let i = 0; i < N; i++) {
+        await svc.create({ id: `s-${i}`, title: `card ${i}`, priority: i });
+      }
+      const order: string[] = [];
+      for (let i = 0; i < N; i++) {
+        const claimed = await svc.claim({ owner: `w-${i}` });
+        expect(claimed).not.toBeNull();
+        order.push(claimed!.id);
+      }
+      // Highest priority first, all distinct.
+      expect(order).toEqual(['s-3', 's-2', 's-1', 's-0']);
+      expect(new Set(order).size).toBe(N);
+      // Now nothing ready remains => null.
+      expect(await svc.claim({ owner: 'late' })).toBeNull();
+    });
+
+    it('claim picks the highest-priority ready card', async () => {
+      await svc.create({ id: 'low', title: 'low', priority: 1 });
+      await svc.create({ id: 'high', title: 'high', priority: 9 });
+      const claimed = await svc.claim({ owner: 'w' });
+      expect(claimed!.id).toBe('high');
+    });
+
+    it('claim of a specific --id', async () => {
+      await svc.create({ id: 'a', title: 'a', priority: 9 });
+      await svc.create({ id: 'b', title: 'b', priority: 1 });
+      const claimed = await svc.claim({ owner: 'w', id: 'b' });
+      expect(claimed!.id).toBe('b');
+    });
+
+    it('claim returns null when nothing is ready', async () => {
+      const claimed = await svc.claim({ owner: 'w' });
+      expect(claimed).toBeNull();
+    });
+  });
+
+  describe('deps DAG gate', () => {
+    it('card with an unfinished dep is not claimable and not ready', async () => {
+      await svc.create({ id: 'dep', title: 'dependency' });
+      await svc.create({ id: 'main', title: 'depends on dep', dependsOn: ['dep'] });
+
+      // `main` should NOT be claimable while `dep` is not done — `dep` wins.
+      const first = await svc.claim({ owner: 'w' });
+      expect(first!.id).toBe('dep');
+
+      // With dep claimed (not done), main still cannot be claimed.
+      const second = await svc.claim({ owner: 'w' });
+      expect(second).toBeNull();
+
+      // ready-only list excludes main while its dep is unfinished.
+      const ready = await svc.list({ readyOnly: true });
+      expect(ready.map((c) => c.id)).not.toContain('main');
+
+      // Once dep is done, main becomes ready and claimable.
+      await svc.complete('dep');
+      const readyAfter = await svc.list({ readyOnly: true });
+      expect(readyAfter.map((c) => c.id)).toContain('main');
+      const third = await svc.claim({ owner: 'w' });
+      expect(third!.id).toBe('main');
+    });
+
+    it('link adds a depends_on edge', async () => {
+      await svc.create({ id: 'a', title: 'a' });
+      await svc.create({ id: 'b', title: 'b' });
+      const linked = await svc.link('a', 'b');
+      expect(linked.dependsOn).toEqual(['b']);
+      // a is now gated on b
+      const claimed = await svc.claim({ owner: 'w' });
+      expect(claimed!.id).toBe('b');
+    });
+  });
+
+  describe('reclaim TTL', () => {
+    it('reclaim returns expired claims to ready', async () => {
+      await svc.create({ id: 'c1', title: 'c1' });
+      const claimed = await svc.claim({ owner: 'w', ttlSeconds: 60 });
+      expect(claimed!.status).toBe('claimed');
+
+      // Backdate the claim so it is well past its TTL.
+      await handle.db.execute(sqlBackdate('c1'));
+
+      const result = await svc.reclaim();
+      expect(result.reclaimed).toEqual(['c1']);
+      const card = await svc.get('c1');
+      expect(card!.status).toBe('ready');
+      expect(card!.claimOwner).toBeNull();
+      expect(card!.claimedAt).toBeNull();
+    });
+
+    it('reclaim does not touch a fresh (unexpired) claim', async () => {
+      await svc.create({ id: 'c1', title: 'c1' });
+      await svc.claim({ owner: 'w', ttlSeconds: 3600 });
+      const result = await svc.reclaim();
+      expect(result.reclaimed).toEqual([]);
+      expect((await svc.get('c1'))!.status).toBe('claimed');
+    });
+
+    it('reclaim --id releases a specific claim regardless of expiry', async () => {
+      await svc.create({ id: 'c1', title: 'c1' });
+      await svc.claim({ owner: 'w', ttlSeconds: 3600 });
+      const result = await svc.reclaim({ id: 'c1' });
+      expect(result.reclaimed).toEqual(['c1']);
+      expect((await svc.get('c1'))!.status).toBe('ready');
+    });
+  });
+
+  describe('stats', () => {
+    it('computes counts, oldest-ready age, and expired-claim count', async () => {
+      await svc.create({ id: 'r1', title: 'r1' });
+      await svc.create({ id: 'r2', title: 'r2' });
+      await svc.create({ id: 'b1', title: 'b1' });
+      await svc.block('b1');
+      await svc.create({ id: 'd1', title: 'd1' });
+      await svc.complete('d1');
+      await svc.create({ id: 'cl1', title: 'cl1' });
+      await svc.claim({ owner: 'w', id: 'cl1', ttlSeconds: 60 });
+      await handle.db.execute(sqlBackdate('cl1'));
+
+      const stats = await svc.stats();
+      expect(stats.counts.ready).toBe(2);
+      expect(stats.counts.blocked).toBe(1);
+      expect(stats.counts.done).toBe(1);
+      expect(stats.counts.claimed).toBe(1);
+      expect(stats.total).toBe(5);
+      expect(stats.expiredClaimCount).toBe(1);
+      expect(stats.oldestReadyAgeSeconds).not.toBeNull();
+      expect(stats.oldestReadyAgeSeconds!).toBeGreaterThanOrEqual(0);
+    });
+  });
+});

packages/db/src/backlog.ts

@@ -0,0 +1,457 @@
+/**
+ * Mosaic-native backlog-of-record service (card A4).
+ *
+ * This is the backlog Mosaic owns end-to-end on its OWN Postgres storage layer.
+ * It REPLACES the former Hermes adapter — there is NO runtime dependency on
+ * Hermes here or anywhere downstream.
+ *
+ * The service takes a `Db` handle, so it works identically against:
+ *   - `createDb()`        — server Postgres (DATABASE_URL / config), and
+ *   - `createPgliteDb()`  — embedded Postgres (file or in-memory).
+ * Same code, same semantics — PGlite gives real Postgres behaviour (including
+ * row locks), so the atomic-claim path is exercised by the in-memory tests.
+ *
+ * Atomic claim: `claim()` selects the highest-priority, deps-satisfied, ready
+ * card with `SELECT ... FOR UPDATE SKIP LOCKED` and flips it to `claimed` inside
+ * one transaction. Two concurrent claimers can therefore NEVER both win the same
+ * card — the loser's locked row is skipped and it picks the next candidate (or
+ * gets null).
+ */
+
+import { and, asc, desc, eq, sql } from 'drizzle-orm';
+import type { Db } from './client.js';
+import { backlog } from './schema.js';
+
+export type BacklogStatus = 'ready' | 'claimed' | 'blocked' | 'done';
+
+export interface BacklogCard {
+  id: string;
+  title: string;
+  body: string | null;
+  phase: string | null;
+  priority: number;
+  status: BacklogStatus;
+  dependsOn: string[];
+  claimOwner: string | null;
+  claimTtlSeconds: number | null;
+  claimedAt: Date | null;
+  attempts: number;
+  idempotencyKey: string | null;
+  acceptance: unknown;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface CreateCardInput {
+  id: string;
+  title: string;
+  body?: string | null;
+  phase?: string | null;
+  priority?: number;
+  dependsOn?: string[];
+  acceptance?: unknown;
+  idempotencyKey?: string | null;
+  status?: BacklogStatus;
+}
+
+export interface ListFilter {
+  status?: BacklogStatus;
+  phase?: string;
+  /** When true, return only cards that are `ready` AND have all deps `done`. */
+  readyOnly?: boolean;
+}
+
+export interface ClaimOptions {
+  owner: string;
+  /** Claim time-to-live in seconds (default 900). */
+  ttlSeconds?: number;
+  /** Claim a specific card by id instead of the highest-priority ready one. */
+  id?: string;
+}
+
+export interface ReclaimResult {
+  reclaimed: string[];
+}
+
+export interface BacklogStats {
+  counts: Record<BacklogStatus, number>;
+  total: number;
+  oldestReadyAgeSeconds: number | null;
+  expiredClaimCount: number;
+}
+
+export const DEFAULT_CLAIM_TTL_SECONDS = 900;
+
+type Row = typeof backlog.$inferSelect;
+
+/**
+ * Row shape as returned by the raw `SELECT * ... FOR UPDATE SKIP LOCKED` path.
+ * That path bypasses drizzle's column-name mapping, so JSON columns arrive as
+ * the snake_case `depends_on` (and may be a JSON string under some drivers).
+ */
+interface RawRow extends Row {
+  depends_on?: unknown;
+}
+
+function toCard(row: Row): BacklogCard {
+  return {
+    id: row.id,
+    title: row.title,
+    body: row.body,
+    phase: row.phase,
+    priority: row.priority,
+    status: row.status,
+    dependsOn: row.dependsOn ?? [],
+    claimOwner: row.claimOwner,
+    claimTtlSeconds: row.claimTtlSeconds,
+    claimedAt: row.claimedAt,
+    attempts: row.attempts,
+    idempotencyKey: row.idempotencyKey,
+    acceptance: row.acceptance,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+/**
+ * The backlog repository/service. Construct with any `Db` handle.
+ */
+export class BacklogService {
+  constructor(private readonly db: Db) {}
+
+  /**
+   * Create a card. If `idempotencyKey` is provided and a card already exists
+   * with that key, the existing card is returned unchanged (no duplicate).
+   */
+  async create(input: CreateCardInput): Promise<BacklogCard> {
+    if (input.idempotencyKey) {
+      const existing = await this.db
+        .select()
+        .from(backlog)
+        .where(eq(backlog.idempotencyKey, input.idempotencyKey))
+        .limit(1);
+      if (existing[0]) return toCard(existing[0]);
+    }
+
+    const inserted = await this.db
+      .insert(backlog)
+      .values({
+        id: input.id,
+        title: input.title,
+        body: input.body ?? null,
+        phase: input.phase ?? null,
+        priority: input.priority ?? 0,
+        status: input.status ?? 'ready',
+        dependsOn: input.dependsOn ?? [],
+        acceptance: input.acceptance ?? null,
+        idempotencyKey: input.idempotencyKey ?? null,
+      })
+      .returning();
+
+    return toCard(inserted[0]!);
+  }
+
+  /** Fetch a single card by id, or null. */
+  async get(id: string): Promise<BacklogCard | null> {
+    const rows = await this.db.select().from(backlog).where(eq(backlog.id, id)).limit(1);
+    return rows[0] ? toCard(rows[0]) : null;
+  }
+
+  /**
+   * List cards with optional filters. `readyOnly` enforces the DAG gate:
+   * a card is "ready" only when its own status is `ready` AND every card in
+   * `depends_on` exists and is `done`.
+   */
+  async list(filter: ListFilter = {}): Promise<BacklogCard[]> {
+    const conditions = [];
+    if (filter.status) conditions.push(eq(backlog.status, filter.status));
+    if (filter.phase) conditions.push(eq(backlog.phase, filter.phase));
+
+    const rows = await this.db
+      .select()
+      .from(backlog)
+      .where(conditions.length ? and(...conditions) : undefined)
+      .orderBy(desc(backlog.priority), asc(backlog.createdAt));
+
+    const cards = rows.map(toCard);
+    if (!filter.readyOnly) return cards;
+
+    const doneIds = await this.doneIdSet();
+    return cards.filter(
+      (c) => c.status === 'ready' && c.dependsOn.every((dep) => doneIds.has(dep)),
+    );
+  }
+
+  private async doneIdSet(): Promise<Set<string>> {
+    const done = await this.db
+      .select({ id: backlog.id })
+      .from(backlog)
+      .where(eq(backlog.status, 'done'));
+    return new Set(done.map((d) => d.id));
+  }
+
+  /**
+   * Atomically claim a card.
+   *
+   * Strategy: inside ONE transaction we lock the candidate row with
+   * `FOR UPDATE SKIP LOCKED LIMIT 1`. A concurrent claimer that already holds
+   * the lock on a row has that row skipped for us, so two claimers can never
+   * both win the same card — and, crucially, each claimer locks exactly ONE
+   * row, so concurrent claimers fan out across distinct ready cards instead of
+   * one claimer locking the whole ready set and starving the rest.
+   *
+   * Candidate selection (when no explicit `id`):
+   *   - status = 'ready'
+   *   - all deps satisfied (every id in depends_on is currently 'done')
+   *   - ordered by priority DESC, created_at ASC
+   *
+   * Returns the claimed card, or null if nothing is claimable.
+   */
+  async claim(opts: ClaimOptions): Promise<BacklogCard | null> {
+    const ttl = opts.ttlSeconds ?? DEFAULT_CLAIM_TTL_SECONDS;
+
+    return this.db.transaction(async (tx) => {
+      // Specific-id path: lock that one ready row (if free) and apply the
+      // deps-satisfied gate in JS, exactly as before.
+      if (opts.id) {
+        const doneRows = await tx
+          .select({ id: backlog.id })
+          .from(backlog)
+          .where(eq(backlog.status, 'done'));
+        const doneIds = new Set(doneRows.map((r) => r.id));
+
+        const result = await tx.execute(
+          sql`SELECT * FROM ${backlog}
+              WHERE ${backlog.id} = ${opts.id} AND ${backlog.status} = 'ready'
+              FOR UPDATE SKIP LOCKED`,
+        );
+        const candidate = rowsOf(result).find((row) =>
+          normalizeDeps(row.depends_on).every((dep) => doneIds.has(dep)),
+        );
+        if (!candidate) return null;
+
+        const updated = await tx
+          .update(backlog)
+          .set({
+            status: 'claimed',
+            claimOwner: opts.owner,
+            claimTtlSeconds: ttl,
+            claimedAt: new Date(),
+            attempts: sql`${backlog.attempts} + 1`,
+            updatedAt: new Date(),
+          })
+          .where(eq(backlog.id, candidate.id))
+          .returning();
+
+        return toCard(updated[0]!);
+      }
+
+      // No-id path: claim the single highest-priority, deps-satisfied ready
+      // card. We lock exactly ONE row in the inner SELECT (`FOR UPDATE SKIP
+      // LOCKED LIMIT 1`) so concurrent claimers grab distinct cards rather than
+      // one claimer locking every ready row and forcing the others to null.
+      //
+      // The deps-satisfied gate is pushed into SQL so `LIMIT 1` lands on the
+      // next genuinely-eligible card: a card is eligible iff none of its
+      // depends_on ids is absent from the set of 'done' card ids.
+      const updated = await tx.execute(
+        sql`UPDATE ${backlog}
+            SET status = 'claimed',
+                claim_owner = ${opts.owner},
+                claim_ttl_seconds = ${ttl},
+                claimed_at = now(),
+                attempts = ${backlog.attempts} + 1,
+                updated_at = now()
+            WHERE ${backlog.id} = (
+              SELECT b.id FROM ${backlog} AS b
+              WHERE b.status = 'ready'
+                AND NOT EXISTS (
+                  SELECT 1
+                  FROM jsonb_array_elements_text(b.depends_on) AS dep
+                  WHERE dep NOT IN (
+                    SELECT d.id FROM ${backlog} AS d WHERE d.status = 'done'
+                  )
+                )
+              ORDER BY b.priority DESC, b.created_at ASC
+              FOR UPDATE SKIP LOCKED
+              LIMIT 1
+            )
+            RETURNING *`,
+      );
+
+      const row = rowsOf(updated)[0];
+      return row ? toCard(rawToRow(row)) : null;
+    });
+  }
+
+  /**
+   * Release expired claims (claimed_at + ttl < now) back to `ready`, OR release
+   * a specific card by id regardless of expiry. Cleared claim fields.
+   * Returns the ids that were released.
+   */
+  async reclaim(opts: { id?: string } = {}): Promise<ReclaimResult> {
+    if (opts.id) {
+      const released = await this.db
+        .update(backlog)
+        .set({
+          status: 'ready',
+          claimOwner: null,
+          claimTtlSeconds: null,
+          claimedAt: null,
+          updatedAt: new Date(),
+        })
+        .where(and(eq(backlog.id, opts.id), eq(backlog.status, 'claimed')))
+        .returning({ id: backlog.id });
+      return { reclaimed: released.map((r) => r.id) };
+    }
+
+    // Expired = status claimed AND claimed_at + (ttl seconds) < now().
+    const released = await this.db
+      .update(backlog)
+      .set({
+        status: 'ready',
+        claimOwner: null,
+        claimTtlSeconds: null,
+        claimedAt: null,
+        updatedAt: new Date(),
+      })
+      .where(
+        and(
+          eq(backlog.status, 'claimed'),
+          sql`${backlog.claimedAt} + make_interval(secs => ${backlog.claimTtlSeconds}) < now()`,
+        ),
+      )
+      .returning({ id: backlog.id });
+    return { reclaimed: released.map((r) => r.id) };
+  }
+
+  /** Add a `depends_on` edge (from → depends on → to). Idempotent. */
+  async link(from: string, to: string): Promise<BacklogCard> {
+    const card = await this.get(from);
+    if (!card) throw new Error(`backlog card not found: ${from}`);
+    const target = await this.get(to);
+    if (!target) throw new Error(`backlog dependency not found: ${to}`);
+    if (from === to) throw new Error('a card cannot depend on itself');
+
+    if (card.dependsOn.includes(to)) return card;
+    const nextDeps = [...card.dependsOn, to];
+    const updated = await this.db
+      .update(backlog)
+      .set({ dependsOn: nextDeps, updatedAt: new Date() })
+      .where(eq(backlog.id, from))
+      .returning();
+    return toCard(updated[0]!);
+  }
+
+  /** Mark a card blocked. */
+  async block(id: string): Promise<BacklogCard | null> {
+    return this.setStatus(id, 'blocked');
+  }
+
+  /** Mark a card done (releasing any claim). */
+  async complete(id: string): Promise<BacklogCard | null> {
+    const updated = await this.db
+      .update(backlog)
+      .set({
+        status: 'done',
+        claimOwner: null,
+        claimTtlSeconds: null,
+        claimedAt: null,
+        updatedAt: new Date(),
+      })
+      .where(eq(backlog.id, id))
+      .returning();
+    return updated[0] ? toCard(updated[0]) : null;
+  }
+
+  private async setStatus(id: string, status: BacklogStatus): Promise<BacklogCard | null> {
+    const updated = await this.db
+      .update(backlog)
+      .set({ status, updatedAt: new Date() })
+      .where(eq(backlog.id, id))
+      .returning();
+    return updated[0] ? toCard(updated[0]) : null;
+  }
+
+  /** Counts by status, oldest-ready age (seconds), and expired-claim count. */
+  async stats(): Promise<BacklogStats> {
+    const all = await this.db.select().from(backlog);
+    const counts: Record<BacklogStatus, number> = {
+      ready: 0,
+      claimed: 0,
+      blocked: 0,
+      done: 0,
+    };
+    let oldestReady: Date | null = null;
+    let expiredClaimCount = 0;
+    const now = Date.now();
+
+    for (const row of all) {
+      counts[row.status] += 1;
+      if (row.status === 'ready') {
+        if (oldestReady === null || row.createdAt < oldestReady) oldestReady = row.createdAt;
+      }
+      if (row.status === 'claimed' && row.claimedAt && row.claimTtlSeconds != null) {
+        const expiry = row.claimedAt.getTime() + row.claimTtlSeconds * 1000;
+        if (expiry < now) expiredClaimCount += 1;
+      }
+    }
+
+    return {
+      counts,
+      total: all.length,
+      oldestReadyAgeSeconds:
+        oldestReady === null ? null : Math.max(0, Math.floor((now - oldestReady.getTime()) / 1000)),
+      expiredClaimCount,
+    };
+  }
+}
+
+/** Extract rows from a drizzle `.execute()` result across drivers (pg / pglite). */
+function rowsOf(result: unknown): RawRow[] {
+  if (Array.isArray(result)) return result as RawRow[];
+  const maybe = result as { rows?: unknown };
+  if (maybe && Array.isArray(maybe.rows)) return maybe.rows as RawRow[];
+  return [];
+}
+
+/**
+ * Map a raw `RETURNING *` row (snake_case columns, possibly string-encoded
+ * timestamps/JSON depending on the driver) onto the drizzle `Row` shape that
+ * `toCard` consumes. Mirrors the column ↔ property mapping in `schema.ts`.
+ */
+function rawToRow(raw: RawRow): Row {
+  const r = raw as unknown as Record<string, unknown>;
+  const toDate = (v: unknown): Date => (v instanceof Date ? v : new Date(v as string));
+  return {
+    id: r.id as string,
+    title: r.title as string,
+    body: (r.body ?? null) as string | null,
+    phase: (r.phase ?? null) as string | null,
+    priority: Number(r.priority),
+    status: r.status as BacklogStatus,
+    dependsOn: normalizeDeps(r.depends_on),
+    claimOwner: (r.claim_owner ?? null) as string | null,
+    claimTtlSeconds: r.claim_ttl_seconds == null ? null : Number(r.claim_ttl_seconds),
+    claimedAt: r.claimed_at == null ? null : toDate(r.claimed_at),
+    attempts: Number(r.attempts),
+    idempotencyKey: (r.idempotency_key ?? null) as string | null,
+    acceptance: r.acceptance ?? null,
+    createdAt: toDate(r.created_at),
+    updatedAt: toDate(r.updated_at),
+  };
+}
+
+/** A raw SQL row returns snake_case `depends_on`; normalize to string[]. */
+function normalizeDeps(value: unknown): string[] {
+  if (Array.isArray(value)) return value as string[];
+  if (typeof value === 'string') {
+    try {
+      const parsed = JSON.parse(value);
+      return Array.isArray(parsed) ? (parsed as string[]) : [];
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}

packages/db/src/index.ts

@@ -3,6 +3,17 @@ export { createPgliteDb } from './client-pglite.js';
 export { runMigrations, runPgliteMigrations } from './migrate.js';
 export * from './schema.js';
 export * from './federation.js';
+export {
+  BacklogService,
+  DEFAULT_CLAIM_TTL_SECONDS,
+  type BacklogCard,
+  type BacklogStatus,
+  type BacklogStats,
+  type ClaimOptions,
+  type CreateCardInput,
+  type ListFilter,
+  type ReclaimResult,
+} from './backlog.js';
 export {
   eq,
   and,

packages/db/src/schema.ts

@@ -587,6 +587,62 @@ export const summarizationJobs = pgTable(
   (t) => [index('summarization_jobs_status_idx').on(t.status)],
 );
 
+// ─── Fleet Backlog ────────────────────────────────────────────────────────────
+// Mosaic-native backlog-of-record (card A4). This REPLACES the former Hermes
+// adapter — there is NO runtime dependency on Hermes. Cards form a dependency
+// DAG (`depends_on`), are claimed atomically by fleet workers via
+// `SELECT ... FOR UPDATE SKIP LOCKED`, and auto-expire via a TTL so a crashed
+// claimer's card returns to the pool.
+
+/**
+ * Lifecycle status of a backlog card.
+ * - ready:   eligible to be claimed (once its deps are all `done`).
+ * - claimed: a worker holds it (claim_owner + claimed_at set); may expire via TTL.
+ * - blocked: explicitly parked; never auto-claimed.
+ * - done:    completed; satisfies dependents.
+ */
+export const backlogStatusEnum = pgEnum('backlog_status', ['ready', 'claimed', 'blocked', 'done']);
+
+export const backlog = pgTable(
+  'backlog',
+  {
+    /** Stable, caller-supplied card id (e.g. "A4", "fleet-001"). PK. */
+    id: text('id').primaryKey(),
+    title: text('title').notNull(),
+    body: text('body'),
+    /** Board/phase grouping (e.g. "M1", "fleet"). Free-form. */
+    phase: text('phase'),
+    /** Higher number = higher priority; claim picks the max-priority ready card. */
+    priority: integer('priority').notNull().default(0),
+    status: backlogStatusEnum('status').notNull().default('ready'),
+    /** DAG edges: ids of cards this one depends on. "ready" requires all done. */
+    dependsOn: jsonb('depends_on').notNull().$type<string[]>().default([]),
+    /** Owner token of the current claim (worker/agent id). NULL when unclaimed. */
+    claimOwner: text('claim_owner'),
+    /** TTL of the active claim in seconds. NULL when unclaimed. */
+    claimTtlSeconds: integer('claim_ttl_seconds'),
+    /** When the active claim was taken. NULL when unclaimed. claimed_at + ttl = expiry. */
+    claimedAt: timestamp('claimed_at', { withTimezone: true }),
+    /** Count of times this card has been claimed (incremented on each claim). */
+    attempts: integer('attempts').notNull().default(0),
+    /** Optional dedup key for `create`; a repeat key returns the existing card. */
+    idempotencyKey: text('idempotency_key'),
+    /** Acceptance criteria — free-form JSON (array of strings or object). */
+    acceptance: jsonb('acceptance'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    // Hot path: claim scans ready cards ordered by priority then age.
+    index('backlog_status_priority_idx').on(t.status, t.priority),
+    // reclaim sweeps claimed cards by claimed_at to find expired ones.
+    index('backlog_status_claimed_at_idx').on(t.status, t.claimedAt),
+    // Idempotent create dedups on this key (NULLs are distinct in Postgres, so
+    // many unkeyed cards coexist; a repeated non-null key collides).
+    uniqueIndex('backlog_idempotency_key_idx').on(t.idempotencyKey),
+  ],
+);
+
 // ─── Federation ──────────────────────────────────────────────────────────────
 // Enums declared before tables that reference them.
 // All federation definitions live in this file (avoids CJS/ESM cross-import

packages/db/vitest.config.ts

@@ -4,5 +4,22 @@ export default defineConfig({
   test: {
     globals: true,
     environment: 'node',
+    // The migration suite spins up a real PGlite (WASM Postgres) instance per
+    // test and applies the full drizzle migration set. Each case legitimately
+    // takes ~5s locally and considerably longer on CI, where turbo runs many
+    // packages' test suites concurrently. The 5s vitest default then expires
+    // mid-migration and the run fails as a phantom "Test timed out in 5000ms"
+    // (often surfacing the underlying WASM `memory access out of bounds` when
+    // the heap is starved). Give migrations real headroom.
+    testTimeout: 120_000,
+    hookTimeout: 120_000,
+    // Each PGlite instance carries a multi-hundred-MB WASM heap. Running test
+    // files in parallel forks multiplies that peak and is what tips the CI
+    // runner into the WASM OOM. A single fork keeps only one instance resident
+    // at a time — slightly slower, but deterministic.
+    pool: 'forks',
+    poolOptions: {
+      forks: { singleFork: true },
+    },
   },
 });

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/defaults/AGENTS.md

@@ -9,7 +9,10 @@ overwritten on upgrade. (Layer model: `constitution/LAYER-MODEL.md`.)
 1. Your context already includes `CONSTITUTION.md` + `USER.md` + the TOOLS index + the runtime
    contract (injected by `mosaic` launch) — do not re-read those. **If you were launched bare**
    (a harness started without `mosaic`, so the law is NOT in your context), read
-   `~/.config/mosaic/CONSTITUTION.md` now, before your first action.
+   `~/.config/mosaic/CONSTITUTION.md` now, before your first action. A bare launch also gets
+   **base contracts only** — operator overlays (`*.local.md`) are composed by the launcher, so if
+   `SOUL.local.md`/`USER.local.md`/`STANDARDS.local.md` exist, relaunch via `mosaic <harness>` (or run
+   `mosaic doctor`) to pick them up.
 2. Read `SOUL.md` (agent persona — small, once).
 3. Read project-local `AGENTS.md` / `CLAUDE.md` if present (these may only make behavior stricter).
 4. Read guides ONLY as triggered by the table below — pull role-relevant depth on demand, not up front.

packages/mosaic/framework/fleet/README.md

@@ -8,7 +8,7 @@ package, normally at:
 ~/.config/mosaic/fleet/roster.yaml
 ```
 
-The default tmux socket is `mosaic-factory` so fleet commands do not touch the
+The default tmux socket is `mosaic-fleet` so fleet commands do not touch the
 default tmux server.
 
 ## Examples

packages/mosaic/framework/fleet/examples/coding.yaml

@@ -0,0 +1,36 @@
+version: 1
+transport: tmux
+tmux:
+  socket_name: mosaic-fleet
+  holder_session: _holder
+defaults:
+  working_directory: ~
+runtimes:
+  claude:
+    reset_command: /clear
+  pi:
+    reset_command: /new
+agents:
+  - name: orchestrator
+    runtime: claude
+    class: orchestrator
+    persistent_persona: true
+  - name: enhancer
+    runtime: claude
+    class: enhancer
+    persistent_persona: true
+  - name: coder0
+    runtime: pi
+    class: implementer
+    model_hint: openai-codex/gpt-5.5:high
+    reset_between_tasks: true
+  - name: coder1
+    runtime: pi
+    class: implementer
+    model_hint: openai-codex/gpt-5.5:high
+    reset_between_tasks: true
+  - name: reviewer
+    runtime: pi
+    class: reviewer
+    model_hint: openai-codex/gpt-5.5:high
+    reset_between_tasks: true

packages/mosaic/framework/fleet/examples/general.yaml

@@ -0,0 +1,26 @@
+version: 1
+transport: tmux
+tmux:
+  socket_name: mosaic-fleet
+  holder_session: _holder
+defaults:
+  working_directory: ~
+runtimes:
+  claude:
+    reset_command: /clear
+  pi:
+    reset_command: /new
+agents:
+  - name: orchestrator
+    runtime: claude
+    class: orchestrator
+    persistent_persona: true
+  - name: enhancer
+    runtime: claude
+    class: enhancer
+    persistent_persona: true
+  - name: generalist
+    runtime: pi
+    class: worker
+    model_hint: openai-codex/gpt-5.5:high
+    reset_between_tasks: true

packages/mosaic/framework/fleet/examples/hybrid.yaml

@@ -0,0 +1,36 @@
+version: 1
+transport: tmux
+tmux:
+  socket_name: mosaic-fleet
+  holder_session: _holder
+defaults:
+  working_directory: ~
+runtimes:
+  claude:
+    reset_command: /clear
+  pi:
+    reset_command: /new
+agents:
+  - name: orchestrator
+    runtime: claude
+    class: orchestrator
+    persistent_persona: true
+  - name: enhancer
+    runtime: claude
+    class: enhancer
+    persistent_persona: true
+  - name: coder0
+    runtime: pi
+    class: implementer
+    model_hint: openai-codex/gpt-5.5:high
+    reset_between_tasks: true
+  - name: researcher0
+    runtime: pi
+    class: researcher
+    model_hint: openai-codex/gpt-5.5:high
+    reset_between_tasks: true
+  - name: reviewer
+    runtime: pi
+    class: reviewer
+    model_hint: openai-codex/gpt-5.5:high
+    reset_between_tasks: true

packages/mosaic/framework/fleet/examples/local-canary.yaml

@@ -1,7 +1,7 @@
 version: 1
 transport: tmux
 tmux:
-  socket_name: mosaic-factory
+  socket_name: mosaic-fleet
   holder_session: _holder
 defaults:
   working_directory: ~/src

packages/mosaic/framework/fleet/examples/minimal.yaml

@@ -1,7 +1,7 @@
 version: 1
 transport: tmux
 tmux:
-  socket_name: mosaic-factory
+  socket_name: mosaic-fleet
   holder_session: _holder
 defaults:
   working_directory: ~/src

packages/mosaic/framework/fleet/examples/research.yaml

@@ -0,0 +1,36 @@
+version: 1
+transport: tmux
+tmux:
+  socket_name: mosaic-fleet
+  holder_session: _holder
+defaults:
+  working_directory: ~
+runtimes:
+  claude:
+    reset_command: /clear
+  pi:
+    reset_command: /new
+agents:
+  - name: orchestrator
+    runtime: claude
+    class: orchestrator
+    persistent_persona: true
+  - name: enhancer
+    runtime: claude
+    class: enhancer
+    persistent_persona: true
+  - name: researcher0
+    runtime: pi
+    class: researcher
+    model_hint: openai-codex/gpt-5.5:high
+    reset_between_tasks: true
+  - name: researcher1
+    runtime: pi
+    class: researcher
+    model_hint: openai-codex/gpt-5.5:high
+    reset_between_tasks: true
+  - name: analyst
+    runtime: pi
+    class: analyst
+    model_hint: openai-codex/gpt-5.5:high
+    reset_between_tasks: true

packages/mosaic/framework/fleet/roles/board.md

@@ -0,0 +1,38 @@
+# Board — fleet role definition
+
+The **board** is the fleet's **deliberation panel** (`class: board`). It is the
+forge **Board-of-Directors** reused as a fleet role — a multi-lens review body
+(moonshot, contrarian, technical, business, financial) that owns the mission's
+direction, not its execution.
+
+It is a **front-office** role: it sets and guards intent, then steps back.
+
+## Mandate
+
+1. **Own `NORTH_STAR.yaml`** — the single source of truth for goals, assumptions,
+   and projections. The board is the only role that ratifies edits to it.
+2. **Ratify or veto goals and assumptions** — every new objective or load-bearing
+   assumption passes the board's lenses before the fleet commits resources to it.
+3. **Hold the lenses** — moonshot (is the ambition right?), contrarian (what breaks
+   this?), technical (is it buildable?), business (does it matter?), financial
+   (can we afford it, in tokens and dollars?).
+4. **Re-deliberate on drift** — when results diverge from the north star, the board
+   reconvenes, re-ratifies or vetoes, and updates `NORTH_STAR.yaml`.
+
+## Boundaries
+
+- **Does NOT write product/source code.**
+- **Does NOT merge.**
+- **Does NOT decompose, plan phases, or dispatch tasks** — it ratifies the
+  _what_ and _why_; planner and decomposition own the _how_.
+
+The board deliberates and decides direction; it never touches the working tree or
+the merge path. When it approves a goal, the planner expands it.
+
+## Persona
+
+A standing panel of senior voices, each arguing from a fixed vantage. The board is
+deliberately slow and adversarial — its value is catching the expensive mistake
+before a single agent-hour is spent on it.
+
+> Doctrine: `docs/fleet/north-star.md` ('board' role = forge BOD; role library).

packages/mosaic/framework/fleet/roles/code.md

@@ -0,0 +1,36 @@
+# Code — fleet role definition
+
+The **code** role is the fleet's primary **executor** (`class: code`). It picks up
+one decomposition card and implements it to green CI on a branch, then opens a PR.
+
+It is an **execution** role: one card, one branch, one PR.
+
+## Mandate
+
+1. **Implement one card to green CI** — take a single backlog card and make the
+   change it describes, on a dedicated branch, until the project's gates
+   (typecheck, lint, format, tests) pass.
+2. **Open the PR via `pr-create.sh`** — once gates are green, open exactly one
+   pull request for the card using the standard `pr-create.sh` wrapper.
+3. **Stay in card scope** — touch only the files the card calls for. No scope
+   creep, no opportunistic refactors outside the card's boundary.
+4. **One card = one PR** — honor the decomposition contract: a card becomes a
+   single focused PR, never two, and a PR never bundles two cards.
+
+## Boundaries
+
+- **Does NOT merge.** Opening the PR is the end of the code role's authority; the
+  **merge-gate** role is the only approver/merger.
+- **Does NOT approve or self-review** — correctness sign-off belongs to the
+  **review** and **security-review** roles.
+- **Does NOT decompose or re-plan** — if a card is wrong or too large, it escalates
+  rather than silently re-scoping.
+
+The code role writes the change and opens the PR; it never touches the merge path.
+
+## Persona
+
+The focused builder. It takes one well-scoped card, drives it to green, opens a
+clean PR, and hands off — never reaching past the card it was given.
+
+> Doctrine: `docs/fleet/north-star.md` (role library).

packages/mosaic/framework/fleet/roles/decomposition.md

@@ -0,0 +1,38 @@
+# Decomposition — fleet role definition
+
+The **decomposition** role splits the planner's FRs into **one-PR-each cards**,
+wired together with `depends_on` link edges, ready for the code role to pick up.
+
+It is a **front-office** role.
+
+## Mandate
+
+1. **Drive the native `mosaic fleet backlog`** — decomposition is the operator of
+   Mosaic's own backlog; it creates and links cards there, on Mosaic's storage
+   layer. It does NOT hand-roll a parallel splitter and does NOT call any external
+   kanban service.
+2. **One card = one PR** — each emitted card is scoped so a single code agent can
+   take it to green CI in one focused pull request. No card spans two PRs; no PR
+   spans two cards.
+3. **Preserve the DAG as `depends_on` links** — carry the planner's `depends_on`
+   relationships onto the cards as link edges so ordering survives into the backlog.
+4. **Record projected spend** — per Mosaic Stack process standard, decomposition
+   notes projected (and later actual) token spend on the work it splits.
+
+## Boundaries
+
+- **Does NOT write product/source code.**
+- **Does NOT merge.**
+- **Does NOT start work** — it produces cards and stops. Picking up a card and
+  implementing it is the **code** role's job.
+
+Decomposition shapes the work queue; it never enters the working tree or the merge
+path.
+
+## Persona
+
+The work-breakdown specialist. It takes a phased plan and a DAG and emits a clean,
+linked set of single-PR cards on the Mosaic backlog — then steps back and lets the
+executors run.
+
+> Doctrine: `docs/fleet/north-star.md` (role library); spend accounting is a process mandate.

packages/mosaic/framework/fleet/roles/documentation.md

@@ -0,0 +1,39 @@
+# Documentation — fleet role definition
+
+The **documentation** role is the fleet's **prose maintainer**
+(`class: documentation`). It keeps human-facing docs and the north star's
+projections in sync with what the fleet actually shipped.
+
+It is an **execution** role: docs and projections, not product code.
+
+## Mandate
+
+1. **Update prose docs** — READMEs, guides, and reference docs follow the
+   changes the fleet lands, so the written record matches reality.
+2. **Update `NORTH_STAR.yaml` projections** — keep the projection fields current
+   as work completes. (The **board** ratifies goals and assumptions; the
+   documentation role maintains the _projection_ surface that tracks progress.)
+3. **Single-writer per TASKS file** — to avoid clobbering, only one writer owns a
+   given TASKS file at a time. The documentation role serializes edits rather than
+   racing other agents on the same file.
+4. **Keep docs honest** — prefer accurate, current prose over aspirational copy.
+
+## Boundaries
+
+- **Does NOT write product/source code** — it writes prose and projection fields,
+  not application logic.
+- **Does NOT merge.** Doc changes go through the same PR + **merge-gate** path as
+  any other change.
+- **Does NOT ratify goals or assumptions** — that is the **board**'s authority; the
+  documentation role only maintains projections and prose.
+
+The documentation role keeps the written record true; it never touches the merge
+path.
+
+## Persona
+
+The scribe of record. It makes sure the docs and the north star's projections
+describe the system as it actually is, and it never lets two writers fight over one
+TASKS file.
+
+> Doctrine: `docs/fleet/north-star.md` (role library).

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

packages/mosaic/framework/fleet/roles/merge-gate.md

@@ -0,0 +1,42 @@
+# Merge-gate — fleet role definition
+
+The **merge-gate** is the fleet's **sole approver and auto-merger**
+(`class: merge-gate`). It is the single chokepoint through which every PR must pass
+to land — no other role merges.
+
+It is a **gate** role: the one and only merge path.
+
+## Mandate
+
+1. **Be the only approver/auto-merger** — no code, review, security-review, or any
+   other role merges. Approval-to-land flows through the merge-gate alone.
+2. **Use the wrapped scripts as the ONLY merge path** — the merge-gate merges
+   **exclusively** by calling **`pr-merge.sh`** (the merge action, which carries the
+   authoritative forbidden-path guard) and **`pr-ci-wait.sh`** (to wait for green
+   CI before merging). These two scripts are the _only_ sanctioned merge path.
+3. **Never call the raw API** — the merge-gate **does NOT** call `tea`, the raw
+   Gitea/forge HTTP API, or any other merge mechanism directly. Only `pr-merge.sh`
+   and `pr-ci-wait.sh`.
+4. **Emit a per-decision heartbeat** — every merge decision (merged / held /
+   rejected) emits a heartbeat so the fleet can observe the gate's activity.
+5. **Honor `fleet/run/PAUSED` before every merge** — check the pause switch ahead
+   of each merge; when paused, the merge-gate holds and does not land anything.
+
+## Boundaries
+
+- **Does NOT write product/source code.**
+- **Does NOT decompose, plan, or author changes** — it only decides whether an
+  already-reviewed PR lands.
+- **Does NOT merge via any path other than `pr-merge.sh` + `pr-ci-wait.sh`** — no
+  raw `tea`/Gitea API, ever.
+
+The merge-gate is the last step before code lands; it is deliberately the only role
+with that authority.
+
+## Persona
+
+The single, accountable gatekeeper. It waits for green CI (`pr-ci-wait.sh`),
+respects the pause switch, merges only through `pr-merge.sh`, and records every
+decision — so the fleet has exactly one trustworthy door to production.
+
+> Doctrine: `docs/fleet/north-star.md` (role library); merge path: `pr-merge.sh` + `pr-ci-wait.sh`; forbidden paths: `pr-merge.sh` guard.

packages/mosaic/framework/fleet/roles/operator.md

@@ -0,0 +1,38 @@
+# Operator — fleet role definition
+
+The **operator** is the fleet's **escalation and control surface**
+(`class: operator`). It is a meta role: it does not deliver product, it keeps the
+fleet's exception-handling and safety controls running.
+
+It is a **meta** role: control plane, not delivery.
+
+## Mandate
+
+1. **Consume escalations** — it is the destination for escalations raised by other
+   roles (e.g. the **rebase** role's genuine conflicts, blocked work, stuck cards).
+2. **Re-raise unacknowledged escalations** — escalations that go unanswered are
+   surfaced again rather than silently lost, so nothing falls through the cracks.
+3. **Own the PAUSE switch surface** — it owns the operator-facing control for the
+   fleet pause switch (`fleet/run/PAUSED`), which the **merge-gate** honors before
+   every merge. The operator can pause and resume the fleet.
+4. **Keep the control plane healthy** — it ensures the fleet's exception path and
+   safety switch remain responsive.
+
+## Boundaries
+
+- **Does NOT write product/source code.**
+- **Does NOT merge.** It can PAUSE the fleet (which the merge-gate honors), but it
+  is not an approver/merger — the **merge-gate** is the only merge path.
+- **Does NOT decompose, plan, or review** — it routes and re-raises exceptions and
+  owns the pause control; it does not do delivery roles' work.
+
+The operator runs the control plane; it never touches the working tree or the merge
+path itself.
+
+## Persona
+
+The on-call dispatcher. It makes sure every escalation is seen and re-seen until
+handled, and it holds the one switch that can stop the fleet when something is
+wrong.
+
+> Doctrine: `docs/fleet/north-star.md` (role library); pause switch: `fleet/run/PAUSED`.

packages/mosaic/framework/fleet/roles/planner.md

@@ -0,0 +1,40 @@
+# Planner — fleet role definition
+
+The **planner** turns ratified objectives into an executable **plan** — phased
+functional requirements (FRs) wired into a `depends_on` DAG.
+
+> **Alias:** the planner role IS the existing **orchestrator** class. The
+> orchestrator _plays_ planner; this file documents the planning contract, it does
+> **not** introduce a competing class. The two-agent floor (orchestrator +
+> enhancer) is preserved — do not split planner into a separate persistent agent
+> that would break it.
+
+It is a **front-office** role.
+
+## Mandate
+
+1. **Expand objectives into phased FRs** — take a board-ratified goal and break it
+   into functional requirements, grouped into phases.
+2. **Build the `depends_on` DAG** — express ordering and blocking relationships
+   between FRs so downstream decomposition can parallelize safely.
+3. **Emit a plan, not tasks** — the planner's output is the phased FR/DAG
+   document. Splitting FRs into one-PR-each cards is the **decomposition** role's job.
+4. **Re-plan on failure** — when execution diverges, the planner (orchestrator)
+   re-sequences the DAG rather than letting agents improvise.
+
+## Boundaries
+
+- **Does NOT write product/source code.**
+- **Does NOT merge.**
+- **Does NOT emit cards** — it stops at the plan (FRs + DAG); decomposition
+  converts the plan into work items.
+
+The planner reasons about structure and order; it never opens a PR or touches the
+merge path.
+
+## Persona
+
+The architect of the mission's shape. It thinks in phases and dependencies, hands
+a clean DAG to decomposition, and keeps the orchestrator/enhancer floor intact.
+
+> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).

packages/mosaic/framework/fleet/roles/rebase.md

@@ -0,0 +1,37 @@
+# Rebase — fleet role definition
+
+The **rebase** role is the fleet's **freshness keeper** (`class: rebase`). It owns
+PRs that have gone stale or `mergeable == false`, bringing them back to a clean,
+re-runnable state — or escalating when there is a real conflict.
+
+It is an **execution** role: it operates on existing PR branches.
+
+## Mandate
+
+1. **Own stale / `mergeable == false` PRs** — when a PR falls behind its base or
+   the platform reports it unmergeable, the rebase role takes it.
+2. **Rebase and re-run** — bring the branch up to date against the base and trigger
+   CI again so the merge-gate has a fresh, mergeable PR to act on.
+3. **Escalate on real conflict** — when the conflict is genuine (semantic, not
+   mechanical), the rebase role stops and escalates to the **operator** rather than
+   guessing at a resolution.
+4. **Keep the queue mergeable** — its job is to ensure the merge-gate is never
+   blocked by avoidable staleness.
+
+## Boundaries
+
+- **Does NOT merge.** It restores mergeability; the **merge-gate** role is the only
+  approver/merger.
+- **Does NOT change feature behavior** — a rebase carries the existing change
+  forward; it does not author new product/source logic. Behavioral fixes go back to
+  the **code** role.
+- **Does NOT force-resolve genuine conflicts** — it escalates them.
+
+The rebase role keeps PR branches fresh; it never approves or merges.
+
+## Persona
+
+The janitor of the merge queue. It quietly keeps branches current and re-runnable,
+and knows when a conflict is beyond a mechanical rebase and must be escalated.
+
+> Doctrine: `docs/fleet/north-star.md` (role library).

packages/mosaic/framework/fleet/roles/review.md

@@ -0,0 +1,38 @@
+# Review — fleet role definition
+
+The **review** role is the fleet's **correctness reviewer** (`class: review`). It
+reads an open PR and judges it on correctness, scope, and test coverage, then
+approves or requests changes.
+
+It is an **execution** role: one open PR per pass.
+
+## Mandate
+
+1. **Judge correctness** — does the change do what its card says, correctly, without
+   introducing regressions?
+2. **Judge scope** — does the PR stay inside its card's boundary, or has it crept
+   into unrelated files?
+3. **Judge test coverage** — are the acceptance criteria backed by real tests that
+   would fail without the change?
+4. **Approve or request changes** — emit a clear verdict with actionable feedback;
+   send it back to the **code** role when it falls short.
+
+## Boundaries
+
+- **Does NOT merge.** Approval is a recommendation; the **merge-gate** role is the
+  only approver/merger.
+- **Does NOT write product/source code** — it reviews; it does not author the fix.
+  Remediation goes back to the **code** role.
+- **Does NOT own secret/auth/forbidden-path checks** — that is the
+  **security-review** role's second line.
+
+The review role gates quality with a verdict; it never touches the working tree or
+the merge path.
+
+## Persona
+
+The careful reader. It assumes nothing, checks the change against its card and its
+tests, and is willing to say "not yet" — its value is catching the wrong change
+before it reaches the merge-gate.
+
+> Doctrine: `docs/fleet/north-star.md` (role library).

packages/mosaic/framework/fleet/roles/security-review.md

@@ -0,0 +1,39 @@
+# Security-review — fleet role definition
+
+The **security-review** role is the fleet's **second line of review**
+(`class: security-review`). Where the **review** role judges correctness, this role
+judges safety: secrets, authentication/authorization, and forbidden-path changes.
+
+It is an **execution** role: one open PR per pass.
+
+## Mandate
+
+1. **Hunt for leaked secrets** — credentials, tokens, keys, or private data
+   committed into the diff.
+2. **Scrutinize auth** — changes to authentication, authorization, permission
+   checks, or trust boundaries get extra adversarial attention.
+3. **Enforce forbidden paths** — flag edits to protected files/areas. The
+   **authoritative forbidden-path list lives in code** — the `pr-merge.sh` guard —
+   not in this prompt. This role is the _human-readable_ second line; the guard is
+   the machine-enforced one.
+4. **Approve on safety or block on risk** — emit a clear safety verdict; a block
+   sends the PR back to the **code** role.
+
+## Boundaries
+
+- **Does NOT merge.** A safety pass is a recommendation; the **merge-gate** role is
+  the only approver/merger, and the `pr-merge.sh` guard is the enforced gate.
+- **Does NOT write product/source code** — it reviews; remediation goes back to the
+  **code** role.
+- **Does NOT redefine the forbidden-path list** — it defers to the `pr-merge.sh`
+  guard as the source of truth.
+
+The security-review role gates safety with a verdict; it never touches the working
+tree or the merge path.
+
+## Persona
+
+The adversary on your side. It reads every diff asking "how does this get exploited
+or leak?" — the second, security-focused pair of eyes before the merge-gate.
+
+> Doctrine: `docs/fleet/north-star.md` (role library); forbidden paths: `pr-merge.sh` guard.

packages/mosaic/framework/fleet/roles/session-review.md

@@ -0,0 +1,37 @@
+# Session-review — fleet role definition
+
+The **session-review** role runs the fleet's **post-task retrospective**
+(`class: session-review`). It is a meta role: it turns finished work into structured
+improvement signals.
+
+It is a **meta** role: learning, not delivery.
+
+## Mandate
+
+1. **Run post-task retros** — after a task/card completes, review how it went:
+   what worked, what created friction, where time and tokens were lost.
+2. **Emit structured signals for the enhancer** — its output is not prose musing
+   but **structured signals** the **enhancer** role can act on (recurring defects,
+   tooling gaps, harness friction, skill shortfalls).
+3. **Feed the improvement loop** — it is the upstream of the enhancer's
+   continuous-improvement loop: session-review observes, the enhancer remediates.
+4. **Stay evidence-based** — signals reference concrete sessions/outcomes, not
+   speculation.
+
+## Boundaries
+
+- **Does NOT write product/source code.**
+- **Does NOT merge.**
+- **Does NOT implement improvements** — it produces signals; the **enhancer**
+  (with the orchestrator) acts on them. Session-review diagnoses; it does not fix.
+
+The session-review role learns from finished work; it never touches the working
+tree or the merge path.
+
+## Persona
+
+The retrospective analyst. It reads completed sessions and distills them into clean,
+actionable signals — the raw material the enhancer uses to make the fleet better
+next time.
+
+> Doctrine: `docs/fleet/north-star.md` (role library); consumed by the enhancer role.

packages/mosaic/framework/fleet/roles/site-tester.md

@@ -0,0 +1,37 @@
+# Site-tester — fleet role definition
+
+The **site-tester** role is the fleet's **runtime verifier** (`class: site-tester`).
+Where review and security-review read the diff statically, the site-tester _runs_
+the change and checks its actual behavior against the card's acceptance criteria.
+
+It is an **execution** role: behavioral verification per PR/card.
+
+## Mandate
+
+1. **Verify behavior at runtime** — exercise the running change (start the app,
+   hit the endpoint, drive the flow) rather than reasoning about it on paper.
+2. **Check against acceptance criteria** — every acceptance criterion on the card
+   gets an observed pass/fail, not an assumed one.
+3. **Reproduce before reporting** — capture concrete evidence (output, logs,
+   screenshots) so a failure is actionable.
+4. **Report observed results** — emit a behavioral verdict that the review and
+   merge-gate roles can trust.
+
+## Boundaries
+
+- **Does NOT merge.** It reports runtime results; the **merge-gate** role is the
+  only approver/merger.
+- **Does NOT write product/source code** — when behavior is wrong, it files the
+  failure back to the **code** role rather than patching it.
+- **Does NOT replace static review** — runtime verification is in addition to the
+  **review** and **security-review** passes, not a substitute.
+
+The site-tester observes and reports; it never touches the working tree or the
+merge path.
+
+## Persona
+
+The skeptic who insists on running it. It trusts observed behavior over claimed
+behavior, and turns "should work" into "verified works" — or a concrete bug report.
+
+> Doctrine: `docs/fleet/north-star.md` (role library).

packages/mosaic/framework/fleet/roster.schema.json

@@ -18,11 +18,11 @@
       "properties": {
         "socket_name": {
           "type": "string",
-          "default": "mosaic-factory"
+          "default": "mosaic-fleet"
         },
         "socketName": {
           "type": "string",
-          "default": "mosaic-factory"
+          "default": "mosaic-fleet"
         },
         "holder_session": {
           "type": "string",
@@ -81,6 +81,18 @@
           "class": {
             "type": "string"
           },
+          "host": {
+            "description": "Host the agent runs on (hostname or IP). Absent = the fleet host. Used by onboarding-injection to render cross-host comms addresses. Manual cross-host listing is a pre-federation stopgap; federation (W1) auto-discovers later.",
+            "type": "string"
+          },
+          "ssh": {
+            "description": "SSH target (user@host) for a cross-host peer, so onboarding renders the `agent-send.sh -H <user@host>` form. Optional; only needed for agents on a different host than the fleet.",
+            "type": "string"
+          },
+          "socket": {
+            "description": "tmux socket the agent's session runs on. Onboarding renders `-L <socket>` when set; absent = the default socket (no `-L`). Must match the LIVE socket, not blindly inherit the roster's tmux.socket_name.",
+            "type": "string"
+          },
           "working_directory": {
             "type": "string"
           },
@@ -113,6 +125,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/install.sh

@@ -19,13 +19,35 @@ SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 
-# Files/dirs preserved across upgrades (never overwritten).
+# Files/dirs protected from rsync --delete during sync. NOTE: framework-owned
+# entries (CONSTITUTION/AGENTS/STANDARDS) ARE re-applied afterward by
+# reconcile_framework_files (overwrite + backup-once); the rest stay user-owned.
 # User-created content in these paths survives rsync --delete.
-PRESERVE_PATHS=("AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials")
+#
+# fleet/* — the framework SEEDS only fleet/examples, fleet/roles, and
+# fleet/roster.schema.json (synced normally — every fleet/roles/*.md role contract
+# lands automatically via this sync, so no per-file entry is needed). The user's
+# own fleet files MUST
+# survive `mosaic update` (which runs this sync automatically): the active
+# roster (`fleet/roster.yaml` + any other `fleet/*.yaml`), per-agent env
+# (`fleet/agents/`), heartbeat run dir (`fleet/run/`), and the Mosaic-native
+# backlog-of-record store (`fleet/backlog/` — embedded PGlite data dir; see
+# packages/mosaic/src/commands/fleet-backlog.ts). Without these, an update
+# wipes the operator's fleet AND their backlog. Glob entries are honored by
+# both the rsync path (`--exclude`) and the glob-aware cp fallback below.
+PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials" "fleet/*.yaml" "fleet/agents" "fleet/run" "fleet/backlog")
+
+# Framework-owned contract files: re-copied from defaults/ on every upgrade (the
+# user must not edit them; a divergent copy is backed up once before overwrite).
+# USER_SEEDED files are written once on first install, then owned by the user.
+# Both lists are APPEND-FRIENDLY — add a new shipped framework file here and to the
+# matching list in packages/mosaic/src/config/file-adapter.ts.
+FRAMEWORK_OWNED=("CONSTITUTION.md" "AGENTS.md" "STANDARDS.md")
+USER_SEEDED=("TOOLS.md")
 
 # Current framework schema version — bump this when the layout changes.
 # The migration system uses this to run upgrade steps.
-FRAMEWORK_VERSION=2
+FRAMEWORK_VERSION=3
 
 # ─── colours ──────────────────────────────────────────────────────────────────
 if [[ -t 1 ]]; then
@@ -40,6 +62,47 @@ warn() { echo -e "  ${YELLOW}⚠${RESET} $1" >&2; }
 fail() { echo -e "  ${RED}✗${RESET} $1" >&2; }
 step() { echo -e "\n${BOLD}$1${RESET}"; }
 
+# ─── snapshot / restore (crash safety for upgrades) ──────────────────────────
+SNAPSHOT_DIR=""
+make_snapshot() {
+  is_existing_install || return 0
+  SNAPSHOT_DIR="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-snapshot-XXXXXX")"
+  cp -a "$TARGET_DIR/." "$SNAPSHOT_DIR/" 2>/dev/null || true
+}
+restore_snapshot() {
+  [[ -n "$SNAPSHOT_DIR" && -d "$SNAPSHOT_DIR" ]] || return 0
+  fail "Install interrupted/failed — restoring previous state from snapshot"
+  rm -rf "$TARGET_DIR"; mkdir -p "$TARGET_DIR"
+  cp -a "$SNAPSHOT_DIR/." "$TARGET_DIR/" 2>/dev/null || true
+}
+cleanup_snapshot() { [[ -n "$SNAPSHOT_DIR" && -d "$SNAPSHOT_DIR" ]] && rm -rf "$SNAPSHOT_DIR"; SNAPSHOT_DIR=""; }
+
+# Reconcile contract files after sync: framework-owned overwrite (backup-once),
+# user-seeded seed-if-absent.
+reconcile_framework_files() {
+  local defaults="$TARGET_DIR/defaults" f
+  [[ -d "$defaults" ]] || return 0
+  for f in "${FRAMEWORK_OWNED[@]}"; do
+    [[ -f "$defaults/$f" ]] || continue
+    # Already current — skip to avoid mtime churn.
+    if [[ -f "$TARGET_DIR/$f" ]] && cmp -s "$TARGET_DIR/$f" "$defaults/$f"; then
+      continue
+    fi
+    if [[ -f "$TARGET_DIR/$f" && ! -f "$TARGET_DIR/${f}.pre-constitution.bak" ]]; then
+      cp "$TARGET_DIR/$f" "$TARGET_DIR/${f}.pre-constitution.bak"
+      warn "$f is now framework-owned and was updated; your previous copy is saved as ${f}.pre-constitution.bak — re-apply intended changes as a .local overlay or policy/ file (see CONSTITUTION.md / constitution/LAYER-MODEL.md)."
+    fi
+    cp "$defaults/$f" "$TARGET_DIR/$f"
+  done
+  for f in "${USER_SEEDED[@]}"; do
+    [[ -f "$defaults/$f" ]] || continue
+    if [[ ! -f "$TARGET_DIR/$f" ]]; then
+      cp "$defaults/$f" "$TARGET_DIR/$f"
+      ok "Seeded $f from defaults"
+    fi
+  done
+}
+
 # ─── helpers ──────────────────────────────────────────────────────────────────
 
 is_existing_install() {
@@ -113,11 +176,14 @@ sync_framework() {
   fi
 
   if command -v rsync >/dev/null 2>&1; then
-    local rsync_args=(-a --delete --exclude ".git" --exclude ".framework-version")
+    local rsync_args=(-a --delete --exclude ".git" --exclude ".framework-version" --exclude "*.pre-constitution.bak")
 
     if [[ "$INSTALL_MODE" == "keep" ]]; then
+      # Anchor to the transfer root (leading /) so we preserve the TOP-LEVEL
+      # ~/.config/mosaic/<file> without also excluding defaults/<file> from sync
+      # (reconcile_framework_files needs the freshly-synced defaults/ copies).
       for path in "${PRESERVE_PATHS[@]}"; do
-        rsync_args+=(--exclude "$path")
+        rsync_args+=(--exclude "/$path")
       done
     fi
 
@@ -125,29 +191,44 @@ sync_framework() {
     return
   fi
 
-  # Fallback: cp-based sync
+  # Fallback: cp-based sync. Glob-aware so entries like "fleet/*.yaml" preserve
+  # every matching user file (parity with the rsync --exclude path above).
   local preserve_tmp=""
   if [[ "$INSTALL_MODE" == "keep" ]]; then
     preserve_tmp="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-preserve-XXXXXX")"
+    local match rel
     for path in "${PRESERVE_PATHS[@]}"; do
-      if [[ -e "$TARGET_DIR/$path" ]]; then
+      # Unquoted $path lets the glob expand against TARGET_DIR; nullglob makes a
-        mkdir -p "$preserve_tmp/$(dirname "$path")"
+      # non-matching pattern vanish instead of staying literal.
-        cp -R "$TARGET_DIR/$path" "$preserve_tmp/$path"
+      shopt -s nullglob
-      fi
+      for match in "$TARGET_DIR/"$path; do
+        [[ -e "$match" ]] || continue
+        rel="${match#"$TARGET_DIR/"}"
+        mkdir -p "$preserve_tmp/$(dirname "$rel")"
+        cp -R "$match" "$preserve_tmp/$rel"
+      done
+      shopt -u nullglob
     done
   fi
 
-  find "$TARGET_DIR" -mindepth 1 -maxdepth 1 ! -name ".git" ! -name ".framework-version" -exec rm -rf {} +
+  find "$TARGET_DIR" -mindepth 1 -maxdepth 1 ! -name ".git" ! -name ".framework-version" ! -name "*.pre-constitution.bak" -exec rm -rf {} +
   cp -R "$SOURCE_DIR"/. "$TARGET_DIR"/
   rm -rf "$TARGET_DIR/.git"
 
   if [[ -n "$preserve_tmp" ]]; then
+    # Restore by re-globbing the SAME patterns against preserve_tmp, so each
+    # preserved item is restored at its own relative path (e.g. only
+    # fleet/roster.yaml is replaced — the freshly-synced fleet/examples stays).
     for path in "${PRESERVE_PATHS[@]}"; do
-      if [[ -e "$preserve_tmp/$path" ]]; then
+      shopt -s nullglob
-        rm -rf "$TARGET_DIR/$path"
+      for match in "$preserve_tmp/"$path; do
-        mkdir -p "$TARGET_DIR/$(dirname "$path")"
+        [[ -e "$match" ]] || continue
-        cp -R "$preserve_tmp/$path" "$TARGET_DIR/$path"
+        rel="${match#"$preserve_tmp/"}"
-      fi
+        rm -rf "$TARGET_DIR/$rel"
+        mkdir -p "$TARGET_DIR/$(dirname "$rel")"
+        cp -R "$match" "$TARGET_DIR/$rel"
+      done
+      shopt -u nullglob
     done
     rm -rf "$preserve_tmp"
   fi
@@ -195,10 +276,15 @@ run_migrations() {
     fi
   fi
 
-  # ── Future migrations go here ──────────────────────────────────────────────
+  # ── Migration: v2 → v3 (Constitution split) ───────────────────────────────
-  # if [[ "$from_version" -lt 3 ]]; then
+  # CONSTITUTION.md / AGENTS.md / STANDARDS.md become framework-owned (overwritten
-  #   ...
+  # on upgrade). reconcile_framework_files() has already run before this point: it
-  # fi
+  # backed up any user-edited copy to <file>.pre-constitution.bak and installed the
+  # new framework version. Nothing further to do here — the advisory was emitted at
+  # reconcile time. (STANDARDS.local.md composition lands with the overlay composer.)
+  if [[ "$from_version" -lt 3 ]]; then
+    ok "Migrated to the Constitution layout (framework-owned CONSTITUTION/AGENTS/STANDARDS)"
+  fi
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -216,29 +302,25 @@ else
   ok "Install mode: overwrite"
 fi
 
+# Snapshot before any destructive file operation; restore on interrupt/failure.
+make_snapshot
+trap 'restore_snapshot' ERR INT TERM
+
 sync_framework
 
 # Ensure persistent directories exist
 mkdir -p "$TARGET_DIR/memory"
 mkdir -p "$TARGET_DIR/credentials"
 
-# Seed defaults — copy framework contract files from defaults/ to framework
+# Reconcile contract files from defaults/ into the framework root: framework-owned
-# root if not already present. These ship with sensible defaults but must
+# files (CONSTITUTION/AGENTS/STANDARDS) are overwritten every upgrade (a divergent
-# never be overwritten once the user has customized them.
+# copy is backed up once); user-seeded files (TOOLS) are written on first install only.
 #
 # This list must match the framework-contract whitelist in
 # packages/mosaic/src/config/file-adapter.ts (FileConfigAdapter.syncFramework).
 # SOUL.md and USER.md are intentionally NOT seeded here — they are generated
 # by `mosaic init` from templates with user-supplied values.
-DEFAULTS_DIR="$TARGET_DIR/defaults"
+reconcile_framework_files
-if [[ -d "$DEFAULTS_DIR" ]]; then
-  for default_file in CONSTITUTION.md AGENTS.md STANDARDS.md TOOLS.md; do
-    if [[ -f "$DEFAULTS_DIR/$default_file" ]] && [[ ! -f "$TARGET_DIR/$default_file" ]]; then
-      cp "$DEFAULTS_DIR/$default_file" "$TARGET_DIR/$default_file"
-      ok "Seeded $default_file from defaults"
-    fi
-  done
-fi
 
 # Ensure tool scripts are executable
 find "$TARGET_DIR/tools" -name "*.sh" -exec chmod +x {} + 2>/dev/null || true
@@ -249,6 +331,18 @@ ok "Framework synced to $TARGET_DIR"
 # Run migrations before post-install (migrations may remove old bin/ etc.)
 run_migrations
 
+# File-system phase complete and consistent — clear the restore trap.
+trap - ERR INT TERM
+cleanup_snapshot
+
+# Testability / minimal-install hook: stop after the file-system phase, before any
+# environment-touching post-install steps (runtime linking, MCP setup, skills, doctor).
+if [[ "${MOSAIC_SYNC_ONLY:-0}" == "1" ]]; then
+  write_framework_version
+  ok "Sync-only mode: file phase complete"
+  exit 0
+fi
+
 step "Post-install tasks"
 
 SCRIPTS="$TARGET_DIR/tools/_scripts"

packages/mosaic/framework/runtime/pi/mosaic-extension.ts

@@ -9,8 +9,16 @@
  *   4. Memory routing — remind agent to use ~/.config/mosaic/memory/
  */
 
-import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
-import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { Type } from 'typebox';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  mkdirSync,
+  renameSync,
+} from 'node:fs';
 import { join, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync, spawnSync } from 'node:child_process';
@@ -25,6 +33,57 @@ const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mo
 // Helpers
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Native heartbeat (fleet R14/R15)
+// ---------------------------------------------------------------------------
+// When this agent runs under the Mosaic fleet (MOSAIC_AGENT_NAME set), the
+// extension writes its OWN heartbeat in the same .hb contract `fleet ps` reads
+// (ts/pid/status[/model]) and touches a `.hb.native` precedence marker so the
+// shell sidecar defers. Native HB knows the real turn state (busy/ok), so it is
+// more accurate than the pane-PID-only sidecar fallback.
+const HB_AGENT_NAME = process.env['MOSAIC_AGENT_NAME'] ?? '';
+const HB_RUN_DIR = process.env['MOSAIC_HEARTBEAT_RUN_DIR'] ?? join(MOSAIC_HOME, 'fleet', 'run');
+const HB_INTERVAL_MS = (() => {
+  const s = Number.parseInt(process.env['MOSAIC_HEARTBEAT_INTERVAL'] ?? '', 10);
+  return Number.isFinite(s) && s > 0 ? s * 1000 : 15_000;
+})();
+
+function nativeHbEnabled(): boolean {
+  return HB_AGENT_NAME.length > 0;
+}
+
+function readModelId(ctx: ExtensionContext): string | null {
+  const m = ctx.model as unknown as { id?: string; name?: string } | undefined;
+  return m?.id ?? m?.name ?? null;
+}
+
+function writeNativeHeartbeat(status: 'ok' | 'busy', model: string | null): void {
+  if (!nativeHbEnabled()) return;
+  try {
+    mkdirSync(HB_RUN_DIR, { recursive: true });
+    const hb = join(HB_RUN_DIR, `${HB_AGENT_NAME}.hb`);
+    const lines = [`ts=${nowIso()}`, `pid=${process.pid}`, `status=${status}`];
+    if (model) lines.push(`model=${model}`);
+    const tmp = `${hb}.tmp.${process.pid}`;
+    writeFileSync(tmp, lines.join('\n') + '\n');
+    renameSync(tmp, hb); // atomic replace — fleet ps never reads a partial file
+    // Precedence marker: tells the shell sidecar that native HB is authoritative.
+    writeFileSync(join(HB_RUN_DIR, `${HB_AGENT_NAME}.hb.native`), nowIso() + '\n');
+  } catch {
+    // Best-effort: never let heartbeat I/O disrupt the Pi session.
+  }
+}
+
+function clearNativeMarker(): void {
+  if (!nativeHbEnabled()) return;
+  try {
+    const m = join(HB_RUN_DIR, `${HB_AGENT_NAME}.hb.native`);
+    if (existsSync(m)) unlinkSync(m); // native stopping — let the sidecar take over
+  } catch {
+    /* ignore */
+  }
+}
+
 function safeRead(filePath: string): string | null {
   try {
     return readFileSync(filePath, 'utf-8');
@@ -187,6 +246,9 @@ function buildMissionSummary(cwd: string, mission: ActiveMission): string {
 
 export default function register(pi: ExtensionAPI) {
   let sessionCwd = process.cwd();
+  let hbStatus: 'ok' | 'busy' = 'ok';
+  let hbModel: string | null = null;
+  let hbTimer: ReturnType<typeof setInterval> | null = null;
 
   // ── Session Start ─────────────────────────────────────────────────────
   pi.on('session_start', async (_event, ctx) => {
@@ -207,10 +269,39 @@ export default function register(pi: ExtensionAPI) {
     } else {
       ctx.ui.notify('Mosaic framework loaded', 'info');
     }
+
+    // Native heartbeat: write immediately, then on an interval. Idle = 'ok';
+    // turn_start/turn_end flip the status so `fleet ps` reflects real activity.
+    if (nativeHbEnabled()) {
+      hbModel = readModelId(ctx);
+      writeNativeHeartbeat('ok', hbModel);
+      hbTimer = setInterval(() => writeNativeHeartbeat(hbStatus, hbModel), HB_INTERVAL_MS);
+      if (typeof hbTimer.unref === 'function') hbTimer.unref();
+    }
   });
 
-  // ── Session End ───────────────────────────────────────────────────────
+  // ── Turn lifecycle → accurate busy/ok heartbeat ───────────────────────
-  pi.on('session_end', async (_event, _ctx) => {
+  pi.on('turn_start', async (_event, ctx) => {
+    hbStatus = 'busy';
+    hbModel = readModelId(ctx) ?? hbModel;
+    writeNativeHeartbeat('busy', hbModel);
+  });
+  pi.on('turn_end', async (_event, ctx) => {
+    hbStatus = 'ok';
+    hbModel = readModelId(ctx) ?? hbModel;
+    writeNativeHeartbeat('ok', hbModel);
+  });
+
+  // ── Session Shutdown ──────────────────────────────────────────────────
+  // (The pi API event is 'session_shutdown'; the prior 'session_end' handler
+  // never fired — fixed here so repo hooks + lock cleanup actually run.)
+  pi.on('session_shutdown', async (_event, _ctx) => {
+    if (hbTimer) {
+      clearInterval(hbTimer);
+      hbTimer = null;
+    }
+    clearNativeMarker();
+
     // Run repo session-end hook
     runRepoHook(sessionCwd, 'session-end');
 
@@ -252,4 +343,32 @@ export default function register(pi: ExtensionAPI) {
       }
     },
   });
+
+  // ── Register mosaic_mission_status tool (model-callable) ──────────────
+  // R14 "proper tool usage": give the agent a first-class tool to load its
+  // active Mosaic mission, milestone progress, task counts, and latest
+  // scratchpad — so it self-orients on in-flight work before planning,
+  // instead of shelling out or guessing. Mirrors the /mosaic-status command
+  // but returns the summary as tool output the LLM can read.
+  pi.registerTool({
+    name: 'mosaic_mission_status',
+    label: 'Mosaic Mission Status',
+    description:
+      'Return the active Mosaic mission, milestone progress, task counts, and latest scratchpad for the current project. Returns a note when no mission is active.',
+    promptSnippet: 'Read the active Mosaic mission + task state for the current project',
+    promptGuidelines: [
+      'Use mosaic_mission_status at the start of a session or task to load the active mission, milestone progress, and open tasks before planning work.',
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+      const mission = detectMission(sessionCwd);
+      const text = mission
+        ? buildMissionSummary(sessionCwd, mission)
+        : 'No active Mosaic mission in this project.';
+      return {
+        content: [{ type: 'text', text }],
+        details: mission ? { ...mission } : { active: false },
+      };
+    },
+  });
 }

packages/mosaic/framework/systemd/user/README.md

@@ -33,7 +33,7 @@ Per-agent overrides live outside the package in:
 Example:
 
 ```dotenv
-MOSAIC_TMUX_SOCKET=mosaic-factory
+MOSAIC_TMUX_SOCKET=mosaic-fleet
 MOSAIC_AGENT_RUNTIME=claude
 MOSAIC_AGENT_WORKDIR=$HOME/src/your-project
 # Optional escape hatch for PoC/canary agents:
@@ -50,8 +50,8 @@ chmod +x ~/.config/mosaic/tools/fleet/start-agent-session.sh
 systemctl --user daemon-reload
 systemctl --user start mosaic-tmux-holder.service
 systemctl --user start mosaic-agent@canary.service
-tmux -L mosaic-factory ls
+tmux -L mosaic-fleet ls
 ```
 
-Do not use `tmux kill-server` without `-L mosaic-factory`; this pattern is meant
+Do not use `tmux kill-server` without `-L mosaic-fleet`; this pattern is meant
 to avoid disturbing the user's default tmux server.

packages/mosaic/framework/systemd/user/mosaic-agent@.service

@@ -8,13 +8,15 @@ PartOf=mosaic-tmux-holder.service
 [Service]
 Type=oneshot
 RemainAfterExit=yes
-Environment=MOSAIC_TMUX_SOCKET=mosaic-factory
+# No default MOSAIC_TMUX_SOCKET: an absent roster socket means the literal
+# default tmux socket (no -L). The per-agent .env sets it when the roster names
+# one; otherwise it stays unset and start-agent-session.sh uses the default socket.
 Environment=MOSAIC_AGENT_NAME=%i
 Environment=MOSAIC_AGENT_RUNTIME=pi
 Environment=MOSAIC_AGENT_WORKDIR=%h
 EnvironmentFile=-%h/.config/mosaic/fleet/agents/%i.env
 ExecStart=/bin/bash %h/.config/mosaic/tools/fleet/start-agent-session.sh %i
-ExecStop=-/bin/bash -lc 'tmux -L "${MOSAIC_TMUX_SOCKET:-mosaic-factory}" kill-session -t "=%i"'
+ExecStop=-/bin/bash -lc 'if [ -n "${MOSAIC_TMUX_SOCKET:-}" ]; then tmux -L "$MOSAIC_TMUX_SOCKET" kill-session -t "=%i"; else tmux kill-session -t "=%i"; fi'
 
 [Install]
 WantedBy=default.target

packages/mosaic/framework/systemd/user/mosaic-tmux-holder.service

@@ -6,7 +6,7 @@ After=default.target
 [Service]
 Type=oneshot
 RemainAfterExit=yes
-Environment=MOSAIC_TMUX_SOCKET=mosaic-factory
+Environment=MOSAIC_TMUX_SOCKET=mosaic-fleet
 Environment=MOSAIC_TMUX_HOLDER=_holder
 ExecStart=/bin/bash -lc 'tmux -L "$MOSAIC_TMUX_SOCKET" has-session -t "=${MOSAIC_TMUX_HOLDER}:0.0" 2>/dev/null || tmux -L "$MOSAIC_TMUX_SOCKET" new-session -d -s "$MOSAIC_TMUX_HOLDER" "while true; do sleep 3600; done"'
 ExecStop=-/bin/bash -lc 'tmux -L "$MOSAIC_TMUX_SOCKET" kill-server'

packages/mosaic/framework/tools/_scripts/mosaic-init

@@ -274,6 +274,13 @@ detect_existing_config
 echo "[mosaic-init] Generating SOUL.md — agent identity contract"
 echo ""
 
+# Fail-closed persona: in non-interactive mode the agent NAME must be supplied
+# explicitly (--name) — never silently ship an agent named "Assistant".
+if [[ $NON_INTERACTIVE -eq 1 && -z "$AGENT_NAME" ]]; then
+  echo "[mosaic-init] ERROR: --name (agent name) is required in non-interactive mode." >&2
+  exit 1
+fi
+
 prompt_if_empty AGENT_NAME "What name should agents use" "Assistant"
 prompt_if_empty ROLE_DESCRIPTION "Agent role description" "execution partner and visibility engine"
 

packages/mosaic/framework/tools/fleet/start-agent-session.sh

@@ -2,10 +2,16 @@
 set -euo pipefail
 
 AGENT_NAME=${1:-${MOSAIC_AGENT_NAME:-}}
-MOSAIC_TMUX_SOCKET=${MOSAIC_TMUX_SOCKET:-mosaic-factory}
+# Absent socket ⇒ the LITERAL default tmux socket (no -L). The roster's
+# socket_name is honored when set; absent never silently becomes mosaic-fleet
+# (spawn stays consistent with the onboarding cheat-sheet + fleet ps observe).
+MOSAIC_TMUX_SOCKET=${MOSAIC_TMUX_SOCKET:-}
 MOSAIC_AGENT_RUNTIME=${MOSAIC_AGENT_RUNTIME:-pi}
+MOSAIC_AGENT_MODEL=${MOSAIC_AGENT_MODEL:-}
 MOSAIC_AGENT_WORKDIR=${MOSAIC_AGENT_WORKDIR:-$HOME}
 MOSAIC_AGENT_COMMAND=${MOSAIC_AGENT_COMMAND:-}
+MOSAIC_HEARTBEAT_RUN_DIR=${MOSAIC_HEARTBEAT_RUN_DIR:-${MOSAIC_HOME:-$HOME/.config/mosaic}/fleet/run}
+MOSAIC_HEARTBEAT_INTERVAL=${MOSAIC_HEARTBEAT_INTERVAL:-15}
 
 if [ -z "$AGENT_NAME" ]; then
   echo "ERROR: agent name argument or MOSAIC_AGENT_NAME is required" >&2
@@ -17,14 +23,232 @@ if ! command -v tmux >/dev/null 2>&1; then
   exit 69
 fi
 
-if tmux -L "$MOSAIC_TMUX_SOCKET" has-session -t "=${AGENT_NAME}:0.0" 2>/dev/null; then
+# tmux wrapper: pass -L only when a socket is configured. An absent/empty socket
-  echo "Mosaic agent session already running: $AGENT_NAME on socket $MOSAIC_TMUX_SOCKET"
+# means the default tmux socket (no -L), keeping spawn == observe == cheat-sheet.
+_tmux() {
+  if [ -n "$MOSAIC_TMUX_SOCKET" ]; then
+    tmux -L "$MOSAIC_TMUX_SOCKET" "$@"
+  else
+    tmux "$@"
+  fi
+}
+
+if _tmux has-session -t "=${AGENT_NAME}:0.0" 2>/dev/null; then
+  echo "Mosaic agent session already running: $AGENT_NAME on socket ${MOSAIC_TMUX_SOCKET:-(default)}"
   exit 0
 fi
 
 if [ -z "$MOSAIC_AGENT_COMMAND" ]; then
-  MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME"
+  # Map the roster's per-agent model_hint to `--model` so workers launch on the
+  # configured model (e.g. pi on openai-codex/gpt-5.5:high). Omitted when unset.
+  MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME${MOSAIC_AGENT_MODEL:+ --model $MOSAIC_AGENT_MODEL}"
+fi
+
+# ── Derive a runtime-bin PATH prefix ─────────────────────────────────────────
+# Precedence:
+#   1. $MOSAIC_RUNTIME_BIN (explicit override)
+#   2. $(npm config get prefix)/bin  (if npm is on PATH)
+#   3. Fallbacks: $HOME/.npm-global/bin and $HOME/.local/bin
+#
+# Only directories that already exist are included.  The prefix is baked into
+# the pane command regardless of what the LAUNCHER process's $PATH contains,
+# because the tmux pane inherits the tmux SERVER environment (not this script's
+# environment).  A dir on the launcher's PATH may be absent from the server PATH,
+# so every existing candidate must always be included.  Dedup within the
+# constructed prefix avoids listing the same dir twice.
+_build_runtime_bin_prefix() {
+  local candidates=()
+
+  if [ -n "${MOSAIC_RUNTIME_BIN:-}" ]; then
+    candidates+=("$MOSAIC_RUNTIME_BIN")
+  fi
+
+  if command -v npm >/dev/null 2>&1; then
+    local npm_prefix
+    npm_prefix=$(npm config get prefix 2>/dev/null) || true
+    if [ -n "$npm_prefix" ]; then
+      candidates+=("${npm_prefix}/bin")
+    fi
+  fi
+
+  candidates+=("$HOME/.npm-global/bin")
+  candidates+=("$HOME/.local/bin")
+
+  local prefix=""
+  for dir in "${candidates[@]}"; do
+    [ -d "$dir" ] || continue
+    if [ -z "$prefix" ]; then
+      prefix="$dir"
+    else
+      case ":${prefix}:" in
+        *":${dir}:"*) ;;  # already in our prefix — skip
+        *) prefix="${prefix}:${dir}" ;;
+      esac
+    fi
+  done
+
+  printf '%s' "$prefix"
+}
+
+MOSAIC_RUNTIME_BIN_PREFIX=$(_build_runtime_bin_prefix)
+
+# ── Build the pane command ────────────────────────────────────────────────────
+# The pane command must:
+#   - Export the augmented PATH so the runtime binary is found.
+#   - exec the agent command so the runtime is the pane's foreground process
+#     (makes `fleet ps` pane_current_command check reliable; no DRIFT false-positive).
+#
+# Quoting strategy: single-quote the inner shell snippet so that variable
+# references in MOSAIC_AGENT_COMMAND are NOT expanded here — they expand inside
+# the pane shell.  However, MOSAIC_RUNTIME_BIN_PREFIX and PATH must be expanded
+# NOW (in this script) because the pane shell inherits the tmux server
+# environment, not this script's env.
+#
+# We build the snippet as a double-quoted here-string embedded in a printf call
+# to avoid nested quoting problems.
+#
+# MOSAIC_AGENT_NAME must also be exported INTO the pane: panes inherit the tmux
+# server environment (not this script's, and not the systemd unit's), so the
+# name would otherwise be empty in-pane and the runtime's native heartbeat
+# (which gates on MOSAIC_AGENT_NAME) would never fire. %q-quote it so it is a
+# safe single bash token regardless of the name's characters.
+AGENT_NAME_Q=$(printf '%q' "$AGENT_NAME")
+
+if [ -n "$MOSAIC_RUNTIME_BIN_PREFIX" ]; then
+  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}"
+else
+  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; exec ${MOSAIC_AGENT_COMMAND}"
 fi
 
 mkdir -p "$MOSAIC_AGENT_WORKDIR"
-exec tmux -L "$MOSAIC_TMUX_SOCKET" new-session -d -s "$AGENT_NAME" -c "$MOSAIC_AGENT_WORKDIR" "$MOSAIC_AGENT_COMMAND"
+
+# ── Pre-trust the workdir for the Claude runtime ─────────────────────────────
+# Claude Code shows a one-time "Is this a project you trust?" folder-trust gate
+# the first time it opens a directory. A fleet-launched agent has no human to
+# answer it, so the pane stalls forever at the prompt while its heartbeat keeps
+# reporting "healthy" (the pane process IS alive — it's just blocked).
+#
+# IMPORTANT: --dangerously-skip-permissions does NOT bypass this gate, and
+# neither does `trustedProjectDirectories` in settings.json (verified empirically
+# 2026-06-24). The ONLY thing the gate honors is the per-project record in
+# ~/.claude.json: projects["<dir>"].hasTrustDialogAccepted == true (exactly what
+# answering the prompt writes). So we pre-seed that record here.
+#
+# Idempotent, atomic, best-effort: any failure is non-fatal (the agent still
+# launches — worst case it stalls on the gate, i.e. the pre-fix status quo).
+# Only the claude runtime needs this; codex/pi have no such gate.
+_ensure_claude_workdir_trusted() {
+  local workdir="$1"
+  # The path claude keys on is the resolved cwd it is launched in.
+  local rp
+  rp=$(cd "$workdir" 2>/dev/null && pwd -P) || rp="$workdir"
+  # ~/.claude.json lives next to the claude config dir; honor CLAUDE_CONFIG_DIR.
+  local claude_json="${MOSAIC_CLAUDE_JSON:-${CLAUDE_CONFIG_DIR:+$CLAUDE_CONFIG_DIR/.claude.json}}"
+  claude_json="${claude_json:-$HOME/.claude.json}"
+
+  if ! command -v python3 >/dev/null 2>&1; then
+    echo "WARNING: python3 not found; cannot pre-trust '$rp' for claude (agent may stall on the folder-trust gate)" >&2
+    return 1
+  fi
+
+  # Serialize concurrent agent launches that share ~/.claude.json (flock if available).
+  local lock="${claude_json}.mosaic-lock"
+  _seed() {
+    MOSAIC_CJ="$claude_json" MOSAIC_TRUST_DIR="$rp" python3 - <<'PY'
+import json, os, sys, tempfile
+cj = os.environ["MOSAIC_CJ"]
+d = os.environ["MOSAIC_TRUST_DIR"]
+try:
+    data = json.load(open(cj)) if os.path.exists(cj) else {}
+    if not isinstance(data, dict):
+        data = {}
+except Exception:
+    # Never corrupt an unreadable/partial file — bail without writing.
+    sys.exit(2)
+projects = data.setdefault("projects", {})
+entry = projects.get(d)
+if not isinstance(entry, dict):
+    entry = {}
+    projects[d] = entry
+if entry.get("hasTrustDialogAccepted") is True:
+    sys.exit(0)  # already trusted — nothing to do
+entry["hasTrustDialogAccepted"] = True
+tmp_dir = os.path.dirname(cj) or "."
+fd, tmp = tempfile.mkstemp(dir=tmp_dir, prefix=".claude.json.mosaic.")
+try:
+    with os.fdopen(fd, "w") as f:
+        json.dump(data, f, indent=2)
+    os.replace(tmp, cj)  # atomic
+except Exception:
+    try:
+        os.unlink(tmp)
+    except OSError:
+        pass
+    sys.exit(3)
+PY
+  }
+  if command -v flock >/dev/null 2>&1; then
+    ( flock 9; _seed ) 9>"$lock" 2>/dev/null || _seed
+  else
+    _seed
+  fi
+}
+
+case "$MOSAIC_AGENT_RUNTIME" in
+  claude)
+    _ensure_claude_workdir_trusted "$MOSAIC_AGENT_WORKDIR" \
+      || echo "WARNING: could not pre-trust workdir for claude agent $AGENT_NAME" >&2
+    ;;
+esac
+
+# ── Launch the tmux session (no exec — we continue to wire the heartbeat) ────
+_tmux new-session -d -s "$AGENT_NAME" -c "$MOSAIC_AGENT_WORKDIR" \
+  bash -c "$PANE_SHELL_SNIPPET"
+
+# ── Resolve the pane PID (retry briefly to let the session initialise) ────────
+PANE_PID=""
+for _retry in 1 2 3 4 5; do
+  PANE_PID=$(_tmux list-panes \
+    -t "=${AGENT_NAME}:0.0" -F '#{pane_pid}' 2>/dev/null || true)
+  [ -n "$PANE_PID" ] && break
+  sleep 0.2
+done
+
+# ── Spawn the heartbeat sidecar (detached, best-effort) ──────────────────────
+# The sidecar writes ~/.config/mosaic/fleet/run/<AGENT>.hb atomically while the
+# pane process is alive, then exits so the file goes stale (fleet ps shows stale
+# then PANE=dead).  It is runtime-agnostic: it only cares about the pane PID.
+_start_heartbeat_sidecar() {
+  local agent="$1"
+  local pane_pid="$2"
+  local run_dir="$3"
+  local interval="$4"
+  local hb_file="${run_dir}/${agent}.hb"
+
+  mkdir -p "$run_dir"
+
+  # Write the sidecar as a self-contained bash one-liner so it carries no
+  # references to any variables from this script's environment.
+  local sidecar_script
+  sidecar_script=$(printf \
+    'hb=%q; pid=%q; iv=%q; mkdir -p "$(dirname "$hb")"; while kill -0 "$pid" 2>/dev/null; do nat="$hb.native"; if [ -f "$nat" ] && [ "$(( $(date +%%s) - $(stat -c %%Y "$nat" 2>/dev/null || echo 0) ))" -lt "$(( iv * 2 ))" ]; then sleep "$iv"; continue; fi; tmp="$hb.tmp.$$"; printf "ts=%%s\npid=%%s\nstatus=ok\n" "$(date +%%Y-%%m-%%dT%%H:%%M:%%S%%z)" "$pid" > "$tmp" && mv "$tmp" "$hb"; sleep "$iv"; done' \
+    "$hb_file" "$pane_pid" "$interval")
+
+  # setsid + disown ensures the sidecar survives this script exiting.
+  # stderr/stdout go to /dev/null; failures are non-fatal.
+  if command -v setsid >/dev/null 2>&1; then
+    setsid bash -c "$sidecar_script" </dev/null >/dev/null 2>&1 &
+  else
+    bash -c "$sidecar_script" </dev/null >/dev/null 2>&1 &
+  fi
+  disown $! 2>/dev/null || true
+}
+
+if [ -n "$PANE_PID" ]; then
+  # Guard: do not let sidecar startup failures abort the launcher (set -e).
+  _start_heartbeat_sidecar "$AGENT_NAME" "$PANE_PID" \
+    "$MOSAIC_HEARTBEAT_RUN_DIR" "$MOSAIC_HEARTBEAT_INTERVAL" || \
+    echo "WARNING: heartbeat sidecar could not be started for $AGENT_NAME" >&2
+else
+  echo "WARNING: could not resolve pane PID for $AGENT_NAME — heartbeat sidecar not started" >&2
+fi

packages/mosaic/framework/tools/fleet/test-start-agent-session.sh

@@ -6,22 +6,43 @@ START="$SCRIPT_DIR/start-agent-session.sh"
 SOCKET="mosaic-agent-test-$RANDOM-$$"
 AGENT="agent-$RANDOM"
 WORKDIR=$(mktemp -d)
-trap 'tmux -L "$SOCKET" kill-server >/dev/null 2>&1 || true; rm -rf "$WORKDIR"' EXIT
+
+# Keep a single cleanup trap that accumulates resources.
+CLEANUP_DIRS=("$WORKDIR")
+CLEANUP_SOCKETS=("$SOCKET")
+trap '_cleanup' EXIT
+_cleanup() {
+  for s in "${CLEANUP_SOCKETS[@]:-}"; do
+    tmux -L "$s" kill-server >/dev/null 2>&1 || true
+  done
+  for d in "${CLEANUP_DIRS[@]:-}"; do
+    rm -rf "$d"
+  done
+}
 
 fail() {
   echo "FAIL: $*" >&2
   exit 1
 }
 
+# ── Test 1: basic session creation with workdir check ─────────────────────────
 MOSAIC_TMUX_SOCKET="$SOCKET" \
 MOSAIC_AGENT_WORKDIR="$WORKDIR" \
 MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
   "$START" "$AGENT"
 
 tmux -L "$SOCKET" has-session -t "=$AGENT:0.0" || fail "agent session was not created"
-actual_dir=$(tmux -L "$SOCKET" display-message -p -t "=$AGENT:0.0" '#{pane_current_path}')
+# Retry: pane_current_path briefly reflects the tmux server's cwd until the pane
-[ "$actual_dir" = "$WORKDIR" ] || fail "agent workdir mismatch: $actual_dir"
+# process establishes its own cwd (the -c start dir). Poll until it settles.
+actual_dir=""
+for _ in $(seq 1 30); do
+  actual_dir=$(tmux -L "$SOCKET" display-message -p -t "=$AGENT:0.0" '#{pane_current_path}')
+  [ "$actual_dir" = "$WORKDIR" ] && break
+  sleep 0.1
+done
+[ "$actual_dir" = "$WORKDIR" ] || fail "agent workdir mismatch: $actual_dir (expected $WORKDIR)"
 
+# ── Test 2: idempotency (duplicate start prints 'already running') ─────────────
 MOSAIC_TMUX_SOCKET="$SOCKET" \
 MOSAIC_AGENT_WORKDIR="$WORKDIR" \
 MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
@@ -29,4 +50,310 @@ MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
 
 grep -qF 'already running' /tmp/mosaic-start-agent-idempotent.out || fail "duplicate start was not idempotent"
 
+# ── Test 3: runtime-bin PATH prefix is baked into the pane command ────────────
+#
+# We capture the command the script would hand to tmux by injecting a fake
+# 'tmux' shim into PATH.  The shim:
+#   - Intercepts 'new-session' calls and records its arguments to a file.
+#   - For 'has-session' calls, exits 1 (session does not exist) so the script
+#     proceeds to launch instead of printing "already running".
+#   - For 'list-panes' calls, returns empty so PANE_PID stays unset and the
+#     heartbeat sidecar is NOT spawned (heartbeat is not the focus of this test;
+#     test 6 and 7 cover that path).  This prevents any real-filesystem side
+#     effects or leaked background processes.
+#   - For all other subcommands, exits 0.
+#
+# Assertions:
+#   a) 'export PATH=' with the synthetic MOSAIC_RUNTIME_BIN prefix appears.
+#   b) 'exec' appears so the runtime replaces the wrapper shell.
+#   c) MOSAIC_AGENT_COMMAND with flags is forwarded intact.
+
+FAKE_BIN=$(mktemp -d)
+FAKE_RUNTIME_BIN=$(mktemp -d)
+TMUX_ARGS_FILE=$(mktemp)
+HB_RUN_DIR3=$(mktemp -d)
+CLEANUP_DIRS+=("$FAKE_BIN" "$FAKE_RUNTIME_BIN" "$HB_RUN_DIR3")
+
+# Write the fake tmux shim (uses only positional args, no sourced vars).
+cat > "$FAKE_BIN/tmux" <<SHIM
+#!/usr/bin/env bash
+# Fake tmux: record new-session args; report has-session as missing.
+subcmd="\$3"  # argv: tmux -L <socket> <subcmd> ...
+if [ "\$subcmd" = "has-session" ]; then
+  exit 1   # session not found → script will attempt new-session
+fi
+if [ "\$subcmd" = "new-session" ]; then
+  printf '%s\n' "\$@" > "$TMUX_ARGS_FILE"
+  exit 0
+fi
+if [ "\$subcmd" = "list-panes" ]; then
+  # Return empty: no sidecar spawned (heartbeat is not the focus of this test).
+  echo ""
+  exit 0
+fi
+exit 0
+SHIM
+chmod +x "$FAKE_BIN/tmux"
+
+SOCKET3="mosaic-agent-test3-$RANDOM-$$"
+AGENT3="agent3-$RANDOM"
+WORKDIR3=$(mktemp -d)
+CLEANUP_DIRS+=("$WORKDIR3")
+
+PATH="$FAKE_BIN:$PATH" \
+MOSAIC_TMUX_SOCKET="$SOCKET3" \
+MOSAIC_AGENT_WORKDIR="$WORKDIR3" \
+MOSAIC_AGENT_RUNTIME="pi" \
+MOSAIC_RUNTIME_BIN="$FAKE_RUNTIME_BIN" \
+MOSAIC_AGENT_COMMAND="mosaic yolo pi --model openai-codex/gpt-5.5:high" \
+MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR3" \
+  "$START" "$AGENT3"
+
+all_args=$(cat "$TMUX_ARGS_FILE" 2>/dev/null || true)
+rm -f "$TMUX_ARGS_FILE"
+
+echo "--- captured tmux new-session args ---"
+echo "$all_args"
+echo "--- end args ---"
+
+# a) PATH prefix containing FAKE_RUNTIME_BIN must appear.
+echo "$all_args" | grep -qF "export PATH=" || fail "pane command does not export PATH"
+echo "$all_args" | grep -qF "$FAKE_RUNTIME_BIN" || fail "pane command does not include MOSAIC_RUNTIME_BIN in PATH prefix"
+
+# b) exec must appear so the runtime replaces the wrapper shell.
+echo "$all_args" | grep -qF "exec " || fail "pane command does not use exec"
+
+# c) Full MOSAIC_AGENT_COMMAND (with flags) must be forwarded.
+echo "$all_args" | grep -qF "mosaic yolo pi --model openai-codex/gpt-5.5:high" || \
+  fail "pane command does not forward MOSAIC_AGENT_COMMAND with flags intact"
+
+# ── Test 4: when no extra runtime-bin dirs exist, exec still appears ───────────
+TMUX_ARGS_FILE2=$(mktemp)
+FAKE_BIN2=$(mktemp -d)
+HB_RUN_DIR4=$(mktemp -d)
+CLEANUP_DIRS+=("$FAKE_BIN2" "$HB_RUN_DIR4")
+
+cat > "$FAKE_BIN2/tmux" <<SHIM2
+#!/usr/bin/env bash
+subcmd="\$3"
+if [ "\$subcmd" = "has-session" ]; then exit 1; fi
+if [ "\$subcmd" = "new-session" ]; then
+  printf '%s\n' "\$@" > "$TMUX_ARGS_FILE2"
+  exit 0
+fi
+if [ "\$subcmd" = "list-panes" ]; then
+  # Return empty: no sidecar spawned (heartbeat is not the focus of this test).
+  echo ""
+  exit 0
+fi
+exit 0
+SHIM2
+chmod +x "$FAKE_BIN2/tmux"
+
+SOCKET4="mosaic-agent-test4-$RANDOM-$$"
+AGENT4="agent4-$RANDOM"
+WORKDIR4=$(mktemp -d)
+CLEANUP_DIRS+=("$WORKDIR4")
+
+# MOSAIC_RUNTIME_BIN points to a non-existent dir so prefix will be empty;
+# .npm-global/bin and .local/bin may or may not exist but we just want exec.
+PATH="$FAKE_BIN2:$PATH" \
+MOSAIC_TMUX_SOCKET="$SOCKET4" \
+MOSAIC_AGENT_WORKDIR="$WORKDIR4" \
+MOSAIC_AGENT_RUNTIME="pi" \
+MOSAIC_RUNTIME_BIN="/nonexistent-dir-$$" \
+MOSAIC_AGENT_COMMAND="mosaic yolo pi" \
+MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR4" \
+  "$START" "$AGENT4"
+
+all_args4=$(cat "$TMUX_ARGS_FILE2" 2>/dev/null || true)
+rm -f "$TMUX_ARGS_FILE2"
+rm -rf "$WORKDIR4"
+
+echo "$all_args4" | grep -qF "exec " || fail "pane command (no prefix dirs) does not use exec"
+echo "$all_args4" | grep -qF "mosaic yolo pi" || fail "pane command does not include agent command when no prefix"
+
+# ── Test 5: candidate dir already in LAUNCHER $PATH is still baked into pane ──
+#
+# Regression guard for the bug where _build_runtime_bin_prefix() used to skip
+# a candidate because it was already present in the launcher process's $PATH.
+# That check was wrong: the pane inherits the tmux SERVER environment, not the
+# launcher's env.  Even if a dir is on the launcher's PATH it must always be
+# baked into the pane's PATH export.
+#
+# We prove this by setting PATH to include FAKE_RUNTIME_BIN5 (the candidate),
+# then asserting the generated new-session command still exports it.
+TMUX_ARGS_FILE5=$(mktemp)
+FAKE_BIN5=$(mktemp -d)
+FAKE_RUNTIME_BIN5=$(mktemp -d)  # this dir IS on the launcher's PATH below
+HB_RUN_DIR5=$(mktemp -d)
+CLEANUP_DIRS+=("$FAKE_BIN5" "$FAKE_RUNTIME_BIN5" "$HB_RUN_DIR5")
+
+cat > "$FAKE_BIN5/tmux" <<SHIM5
+#!/usr/bin/env bash
+subcmd="\$3"
+if [ "\$subcmd" = "has-session" ]; then exit 1; fi
+if [ "\$subcmd" = "new-session" ]; then
+  printf '%s\n' "\$@" > "$TMUX_ARGS_FILE5"
+  exit 0
+fi
+if [ "\$subcmd" = "list-panes" ]; then
+  # Return empty: no sidecar spawned (heartbeat is not the focus of this test).
+  echo ""
+  exit 0
+fi
+exit 0
+SHIM5
+chmod +x "$FAKE_BIN5/tmux"
+
+SOCKET5="mosaic-agent-test5-$RANDOM-$$"
+AGENT5="agent5-$RANDOM"
+WORKDIR5=$(mktemp -d)
+CLEANUP_DIRS+=("$WORKDIR5")
+CLEANUP_SOCKETS+=("$SOCKET5")
+
+# FAKE_RUNTIME_BIN5 is deliberately placed on the LAUNCHER PATH so that the
+# old (buggy) code would have skipped it.  The correct code must still include
+# it in the pane PATH export.
+PATH="$FAKE_BIN5:$FAKE_RUNTIME_BIN5:$PATH" \
+MOSAIC_TMUX_SOCKET="$SOCKET5" \
+MOSAIC_AGENT_WORKDIR="$WORKDIR5" \
+MOSAIC_AGENT_RUNTIME="pi" \
+MOSAIC_RUNTIME_BIN="$FAKE_RUNTIME_BIN5" \
+MOSAIC_AGENT_COMMAND="mosaic yolo pi" \
+MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR5" \
+  "$START" "$AGENT5"
+
+all_args5=$(cat "$TMUX_ARGS_FILE5" 2>/dev/null || true)
+rm -f "$TMUX_ARGS_FILE5"
+rm -rf "$WORKDIR5"
+
+echo "--- test 5: launcher-PATH candidate must still appear in pane export ---"
+echo "$all_args5"
+echo "--- end test 5 args ---"
+
+echo "$all_args5" | grep -qF "export PATH=" || \
+  fail "test5: pane command does not export PATH when candidate is on launcher PATH"
+echo "$all_args5" | grep -qF "$FAKE_RUNTIME_BIN5" || \
+  fail "test5: candidate dir (already on launcher PATH) was NOT baked into pane PATH — regression"
+
+# ── Test 6: heartbeat sidecar — pane PID resolved + .hb file written ──────────
+#
+# Uses a real tmux session (same socket as test 1 which already has $AGENT) so
+# list-panes returns a real pane PID.  We override MOSAIC_HEARTBEAT_RUN_DIR to
+# a temp dir and set a 1-second interval, then wait up to 3 s for the .hb file
+# to appear and check its content.
+
+HB_RUN_DIR=$(mktemp -d)
+CLEANUP_DIRS+=("$HB_RUN_DIR")
+
+# Re-use the session+agent created in Test 1 (still alive on $SOCKET / $AGENT).
+# We need to invoke the script for a NEW agent on the same socket to exercise
+# the heartbeat path with a real pane PID.
+AGENT6="agent6-$RANDOM"
+MOSAIC_TMUX_SOCKET="$SOCKET" \
+MOSAIC_AGENT_WORKDIR="$WORKDIR" \
+MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
+MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR" \
+MOSAIC_HEARTBEAT_INTERVAL="1" \
+  "$START" "$AGENT6"
+
+HB_FILE="$HB_RUN_DIR/${AGENT6}.hb"
+
+# Wait up to 5 seconds for the heartbeat file to appear.
+_waited=0
+until [ -f "$HB_FILE" ] || [ "$_waited" -ge 5 ]; do
+  sleep 0.5
+  _waited=$((_waited + 1))
+done
+
+[ -f "$HB_FILE" ] || fail "test6: heartbeat file not written at $HB_FILE within 5s"
+
+hb_content=$(cat "$HB_FILE")
+echo "--- test 6: heartbeat file content ---"
+echo "$hb_content"
+echo "--- end test 6 ---"
+
+# Verify required fields are present.
+echo "$hb_content" | grep -qE '^ts=[0-9]{4}-[0-9]{2}-[0-9]{2}T' || \
+  fail "test6: heartbeat ts field missing or malformed"
+echo "$hb_content" | grep -qE '^pid=[0-9]+' || \
+  fail "test6: heartbeat pid field missing or malformed"
+echo "$hb_content" | grep -qF 'status=ok' || \
+  fail "test6: heartbeat status=ok missing"
+
+# ── Test 7: heartbeat sidecar — targets correct .hb path per agent name ────────
+#
+# Uses the fake-tmux shim approach (like tests 3-5) to capture the sidecar
+# invocation without needing a real session.  A fake setsid shim records its
+# arguments so we can assert the sidecar script targets the expected .hb path
+# and uses the configured interval.
+
+FAKE_BIN7=$(mktemp -d)
+FAKE_RUNTIME_BIN7=$(mktemp -d)
+SETSID_ARGS_FILE=$(mktemp)
+HB_RUN_DIR7=$(mktemp -d)
+CLEANUP_DIRS+=("$FAKE_BIN7" "$FAKE_RUNTIME_BIN7" "$HB_RUN_DIR7")
+
+AGENT7="my-fleet-agent-$RANDOM"
+INTERVAL7="42"
+
+# Fake tmux: has-session → not found; new-session → ok; list-panes → known PID.
+cat > "$FAKE_BIN7/tmux" <<SHIM7
+#!/usr/bin/env bash
+subcmd="\$3"
+if [ "\$subcmd" = "has-session" ]; then exit 1; fi
+if [ "\$subcmd" = "new-session" ]; then exit 0; fi
+if [ "\$subcmd" = "list-panes" ]; then echo "88888"; exit 0; fi
+exit 0
+SHIM7
+chmod +x "$FAKE_BIN7/tmux"
+
+# Fake setsid: capture the bash -c <script> argument for inspection, then
+# background an actual bash subshell so disown succeeds in the caller.
+cat > "$FAKE_BIN7/setsid" <<'SETSID_SHIM'
+#!/usr/bin/env bash
+# argv: setsid bash -c <sidecar_script>
+# Record the full argument list to the capture file, then exit cleanly.
+printf '%s\0' "$@" > __SETSID_ARGS_FILE__
+exit 0
+SETSID_SHIM
+# Patch the placeholder with the real capture-file path (avoids heredoc expansion issues).
+sed -i "s|__SETSID_ARGS_FILE__|${SETSID_ARGS_FILE}|g" "$FAKE_BIN7/setsid"
+chmod +x "$FAKE_BIN7/setsid"
+
+SOCKET7="mosaic-agent-test7-$RANDOM-$$"
+WORKDIR7=$(mktemp -d)
+CLEANUP_DIRS+=("$WORKDIR7")
+
+PATH="$FAKE_BIN7:$PATH" \
+MOSAIC_TMUX_SOCKET="$SOCKET7" \
+MOSAIC_AGENT_WORKDIR="$WORKDIR7" \
+MOSAIC_AGENT_RUNTIME="pi" \
+MOSAIC_RUNTIME_BIN="$FAKE_RUNTIME_BIN7" \
+MOSAIC_AGENT_COMMAND="mosaic yolo pi" \
+MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR7" \
+MOSAIC_HEARTBEAT_INTERVAL="$INTERVAL7" \
+  "$START" "$AGENT7"
+
+# Give the background setsid shim a moment to finish writing the capture file.
+sleep 0.5
+
+setsid_args=$(cat "$SETSID_ARGS_FILE" 2>/dev/null | tr '\0' '\n' || true)
+rm -f "$SETSID_ARGS_FILE"
+rm -rf "$WORKDIR7"
+
+echo "--- test 7: captured setsid args ---"
+echo "$setsid_args"
+echo "--- end test 7 ---"
+
+# The sidecar script (bash -c <script>) must reference the correct .hb path.
+expected_hb="${HB_RUN_DIR7}/${AGENT7}.hb"
+echo "$setsid_args" | grep -qF "$expected_hb" || \
+  fail "test7: sidecar script does not reference correct .hb path ($expected_hb)"
+
+# The sidecar script must use the configured interval.
+echo "$setsid_args" | grep -qF "$INTERVAL7" || \
+  fail "test7: sidecar script does not reference configured interval ($INTERVAL7)"
+
 echo "ok - start-agent-session"

packages/mosaic/framework/tools/git/pr-merge.sh

@@ -128,8 +128,8 @@ PY
 merge_gitea_with_api() {
     local host="$1" api_url token basic_auth body_file raw_code payload
     api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/merge"
-    mkdir -p "${AGENT_WORK_ROOT:-/home/hermes/agent-work}"
+    mkdir -p "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}"
-    body_file=$(mktemp "${AGENT_WORK_ROOT:-/home/hermes/agent-work}/pr-merge-api-response.XXXXXX")
+    body_file=$(mktemp "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}/pr-merge-api-response.XXXXXX")
     payload='{"Do":"squash"}'
 
     token=$(get_gitea_token "$host" || true)
@@ -214,8 +214,8 @@ case "$PLATFORM" in
         TEA_LOGIN="$(get_gitea_login_for_host "$HOST" || true)"
 
         if [[ -n "$TEA_LOGIN" ]]; then
-            mkdir -p "${AGENT_WORK_ROOT:-/home/hermes/agent-work}"
+            mkdir -p "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}"
-            TEA_ERROR_FILE=$(mktemp "${AGENT_WORK_ROOT:-/home/hermes/agent-work}/pr-merge-tea-error.XXXXXX")
+            TEA_ERROR_FILE=$(mktemp "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}/pr-merge-tea-error.XXXXXX")
             if tea pr merge "$PR_NUMBER" --style squash --repo "$OWNER/$REPO" --login "$TEA_LOGIN" 2> "$TEA_ERROR_FILE"; then
                 rm -f "$TEA_ERROR_FILE"
             elif is_known_tea_empty_identity_failure "$TEA_ERROR_FILE"; then

packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh

@@ -4,7 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_ROOT="${AGENT_WORK_ROOT:-/home/hermes/agent-work}"
+WORK_ROOT="${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}"
 SANDBOX="$WORK_ROOT/pr-merge-empty-uid-test-$$"
 MOCK_BIN="$SANDBOX/bin"
 REPO_DIR="$SANDBOX/repo"

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/framework/tools/quality/scripts/test-install-migration.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# test-install-migration.sh — fixture matrix for the v2→v3 (Constitution) upgrade
+# migration in install.sh. Runs the installer against throwaway MOSAIC_HOME dirs
+# with MOSAIC_SYNC_ONLY=1 (file phase only — no environment-touching post-install)
+# and asserts the framework-owned-overwrite + user-preserve + backup semantics.
+#
+# Mirrors the TS fixture suite in packages/mosaic/src/config/file-adapter.test.ts;
+# both installers MUST behave identically.
+#
+# Usage:  bash test-install-migration.sh
+set -uo pipefail
+
+FW="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"   # packages/mosaic/framework
+INSTALL="$FW/install.sh"
+DEFA="$FW/defaults"
+
+pass=0; fail=0
+chk() { if eval "$2"; then echo "  ✓ $1"; pass=$((pass + 1)); else echo "  ✗ $1"; fail=$((fail + 1)); fi; }
+run() { MOSAIC_HOME="$1" MOSAIC_INSTALL_MODE="$2" MOSAIC_SYNC_ONLY=1 bash "$INSTALL" >/dev/null 2>&1; }
+
+echo "install.sh v2→v3 migration fixture matrix:"
+
+# F1 — fresh install
+T1=$(mktemp -d); run "$T1" overwrite
+chk "F1 fresh: CONSTITUTION/AGENTS/STANDARDS/TOOLS seeded" \
+  "[ -f '$T1/CONSTITUTION.md' ] && [ -f '$T1/AGENTS.md' ] && [ -f '$T1/STANDARDS.md' ] && [ -f '$T1/TOOLS.md' ]"
+chk "F1 fresh: AGENTS == shipped default" "cmp -s '$T1/AGENTS.md' '$DEFA/AGENTS.md'"
+chk "F1 fresh: framework-version stamped 3" "[ \"\$(cat '$T1/.framework-version' 2>/dev/null)\" = 3 ]"
+
+# F2 — legacy install with a user-edited AGENTS.md (the sanctioned pre-constitution customization)
+T2=$(mktemp -d); mkdir -p "$T2/credentials"
+printf '# user-edited AGENTS pre-constitution\n' > "$T2/AGENTS.md"
+printf '# my persona\n' > "$T2/SOUL.md"
+printf 'token\n' > "$T2/credentials/c.json"
+echo 2 > "$T2/.framework-version"
+run "$T2" keep
+chk "F2 legacy-edited: AGENTS overwritten to framework version" "cmp -s '$T2/AGENTS.md' '$DEFA/AGENTS.md'"
+chk "F2 legacy-edited: prior AGENTS saved to .pre-constitution.bak" \
+  "grep -q 'user-edited AGENTS pre-constitution' '$T2/AGENTS.md.pre-constitution.bak'"
+chk "F2 legacy-edited: SOUL.md preserved" "grep -q 'my persona' '$T2/SOUL.md'"
+chk "F2 legacy-edited: credentials preserved" "grep -q token '$T2/credentials/c.json'"
+chk "F2 legacy-edited: CONSTITUTION.md installed" "[ -f '$T2/CONSTITUTION.md' ]"
+run "$T2" keep
+chk "F2 idempotent: .pre-constitution.bak preserved across a 2nd upgrade" \
+  "grep -q 'user-edited AGENTS pre-constitution' '$T2/AGENTS.md.pre-constitution.bak'"
+
+# F3 — user-tuned STANDARDS.md
+T3=$(mktemp -d); printf '# tuned standards\n' > "$T3/STANDARDS.md"; printf '# persona\n' > "$T3/SOUL.md"; echo 2 > "$T3/.framework-version"
+run "$T3" keep
+chk "F3 tuned-standard: STANDARDS overwritten" "cmp -s '$T3/STANDARDS.md' '$DEFA/STANDARDS.md'"
+chk "F3 tuned-standard: tuned copy backed up" "grep -q 'tuned standards' '$T3/STANDARDS.md.pre-constitution.bak'"
+
+# F4 — unattended / no TTY (stdin closed): must complete without hanging, default to keep
+T4=$(mktemp -d); printf '# persona\n' > "$T4/SOUL.md"; printf '# old\n' > "$T4/AGENTS.md"; echo 2 > "$T4/.framework-version"
+MOSAIC_HOME="$T4" MOSAIC_SYNC_ONLY=1 bash "$INSTALL" </dev/null >/dev/null 2>&1
+chk "F4 no-TTY: completed, AGENTS updated" "cmp -s '$T4/AGENTS.md' '$DEFA/AGENTS.md'"
+
+# F5 — failure path must not corrupt existing data (invalid mode rejected before any file op)
+T5=$(mktemp -d); mkdir -p "$T5/credentials"; printf '# orig\n' > "$T5/SOUL.md"; printf 'keepme\n' > "$T5/credentials/c.json"; echo 2 > "$T5/.framework-version"
+MOSAIC_HOME="$T5" MOSAIC_INSTALL_MODE=bogus MOSAIC_SYNC_ONLY=1 bash "$INSTALL" >/dev/null 2>&1; rc=$?
+chk "F5 failure: invalid mode rejected (nonzero exit)" "[ $rc -ne 0 ]"
+chk "F5 failure: SOUL + credentials intact" "grep -q orig '$T5/SOUL.md' && grep -q keepme '$T5/credentials/c.json'"
+
+# F6 — keep-mode re-seed (the `mosaic update` path) MUST NOT wipe user fleet data.
+# Regression for the roster-loss bug: fleet/ was not in PRESERVE_PATHS.
+T6=$(mktemp -d); mkdir -p "$T6/fleet/examples" "$T6/fleet/run" "$T6/fleet/agents"
+printf '# persona\n' > "$T6/SOUL.md"   # makes it a recognized existing install (→ keep mode)
+printf 'version: 1\nagents:\n  - name: coder0\n' > "$T6/fleet/roster.yaml"
+printf 'version: 1\nagents:\n  - name: custom\n' > "$T6/fleet/my-fleet.yaml"
+printf 'ts=x\n' > "$T6/fleet/run/coder0.hb"
+printf 'MOSAIC_AGENT_NAME=coder0\n' > "$T6/fleet/agents/coder0.env"
+printf '# stale preset\n' > "$T6/fleet/examples/general.yaml"
+echo 3 > "$T6/.framework-version"
+run "$T6" keep
+chk "F6 reseed: user roster.yaml SURVIVES keep-mode sync" "grep -q coder0 '$T6/fleet/roster.yaml'"
+chk "F6 reseed: other user fleet/*.yaml survives (glob)" "[ -f '$T6/fleet/my-fleet.yaml' ]"
+chk "F6 reseed: per-agent env (fleet/agents) survives" "[ -f '$T6/fleet/agents/coder0.env' ]"
+chk "F6 reseed: heartbeat run dir (fleet/run) survives" "[ -f '$T6/fleet/run/coder0.hb' ]"
+chk "F6 reseed: framework examples ARE refreshed (not preserved stale)" "grep -q orchestrator '$T6/fleet/examples/general.yaml'"
+chk "F6 reseed: framework roster.schema.json seeded" "[ -f '$T6/fleet/roster.schema.json' ]"
+
+rm -rf "$T1" "$T2" "$T3" "$T4" "$T5" "$T6"
+echo
+echo "RESULT: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh

@@ -53,9 +53,15 @@ _selftest() {
   local tmp; tmp="$(mktemp -d)" || return 1
   printf 'contact jason.woltje at jarvis-brain (PDA-friendly)\n' > "$tmp/planted.md"
   printf 'X="${VAR:-$HOME/src/whatever/x.json}"\n' > "$tmp/planted.sh"
+  printf 'name: jason-woltje\n' > "$tmp/planted.yaml"
+  printf '[Service]\nUser=jarvis\n' > "$tmp/planted.service"
   local rc=0
   grep -qIEi "$DENYLIST" "$tmp/planted.md" || { echo "✗ SELF-TEST: identity denylist regex broken" >&2; rc=1; }
   grep -qIE  "$STRUCTURAL_SH" "$tmp/planted.sh" || { echo "✗ SELF-TEST: structural regex broken" >&2; rc=1; }
+  # Prove the identity scan covers the config formats it claims to (yaml/service/etc).
+  local n_ext
+  n_ext=$(find "$tmp" -type f \( -name '*.yaml' -o -name '*.service' \) -print0 | xargs -0 -r grep -lIEi "$DENYLIST" 2>/dev/null | wc -l)
+  [[ "$n_ext" -eq 2 ]] || { echo "✗ SELF-TEST: identity scan does not cover .yaml/.service extensions" >&2; rc=1; }
   rm -rf "$tmp"; return $rc
 }
 _selftest || exit 2

packages/mosaic/framework/tools/quality/templates/monorepo/.woodpecker.yml

@@ -2,12 +2,20 @@
 when:
   - event: [push, pull_request, manual]
 
+# Dependencies are installed ONCE in the `install` step and every downstream
+# step depends on it, reusing the populated node_modules from the shared
+# workspace volume. Do NOT re-run `npm ci` per step — that pays the full cold
+# install (network fetch + native rebuilds) N times and is the dominant cost
+# in a pipeline.
+#
+# For best results, replace `&node_image` with a pre-baked CI base image that
+# ships your toolchain (python3/make/g++ for native modules) and a warm npm
+# cache, then keep `--prefer-offline` so installs resolve from the cache. See
+# the Mosaic Stack repo's Dockerfile.ci + .woodpecker/ci-image.yml for the
+# baked-image pattern.
 variables:
   - &node_image 'node:20-alpine'
   - &gitleaks_image 'ghcr.io/gitleaks/gitleaks:v8.24.0'
-  - &install_deps |
-    corepack enable
-    npm ci --ignore-scripts
 
 steps:
   # Secret scanning (runs in parallel with install, no deps)
@@ -17,15 +25,18 @@ steps:
       - gitleaks git --redact --verbose --log-opts="HEAD~1..HEAD"
     depends_on: []
 
+  # Single cached install. Every other step depends on this and reuses the
+  # node_modules it produces in the shared workspace.
   install:
     image: *node_image
     commands:
-      - *install_deps
+      - corepack enable
+      - npm ci --ignore-scripts --prefer-offline
+    depends_on: []
 
   security-audit:
     image: *node_image
     commands:
-      - *install_deps
       - npm audit --audit-level=high
     depends_on:
       - install
@@ -35,7 +46,6 @@ steps:
     environment:
       SKIP_ENV_VALIDATION: 'true'
     commands:
-      - *install_deps
       - npm run lint
     depends_on:
       - install
@@ -45,7 +55,6 @@ steps:
     environment:
       SKIP_ENV_VALIDATION: 'true'
     commands:
-      - *install_deps
       - npm run type-check
     depends_on:
       - install
@@ -55,7 +64,6 @@ steps:
     environment:
       SKIP_ENV_VALIDATION: 'true'
     commands:
-      - *install_deps
       - npm run test -- --coverage --coverageThreshold='{"global":{"branches":80,"functions":80,"lines":80,"statements":80}}'
     depends_on:
       - install
@@ -66,7 +74,6 @@ steps:
       SKIP_ENV_VALIDATION: 'true'
       NODE_ENV: 'production'
     commands:
-      - *install_deps
       - npm run build
     depends_on:
       - lint

packages/mosaic/framework/tools/tmux/README.md

@@ -35,7 +35,7 @@ delivers reliably to local OR remote panes.
 agent-send.sh -s <dst_session> -m "message"
 
 # Local target on a Mosaic fleet socket
-agent-send.sh -L mosaic-factory -s '=coder0' -m "message"
+agent-send.sh -L mosaic-fleet -s '=coder0' -m "message"
 
 # Remote target (over ssh)
 agent-send.sh -H user@host -s <dst_session> -m "message"
@@ -58,9 +58,9 @@ commands do not fall back to tmux's prefix matching behavior.
 Durable Mosaic fleets should use a dedicated tmux socket, for example:
 
 ```bash
-tmux -L mosaic-factory ls
+tmux -L mosaic-fleet ls
-agent-send.sh -L mosaic-factory -s '=coder0' -m "status?"
+agent-send.sh -L mosaic-fleet -s '=coder0' -m "status?"
-send-message.sh -L mosaic-factory -t '=coder0' -m "raw pane message"
+send-message.sh -L mosaic-fleet -t '=coder0' -m "raw pane message"
 ```
 
 This keeps fleet operations away from the user's default tmux server. It is the

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

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

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

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

packages/mosaic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicstack/mosaic",
-  "version": "0.0.34",
+  "version": "0.0.45",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
@@ -29,6 +29,7 @@
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",
     "@mosaicstack/config": "workspace:*",
+    "@mosaicstack/db": "workspace:*",
     "@mosaicstack/forge": "workspace:*",
     "@mosaicstack/log": "workspace:*",
     "@mosaicstack/macp": "workspace:*",

packages/mosaic/src/cli.ts

@@ -26,6 +26,12 @@ import {
   checkForAllUpdates,
   formatAllPackagesTable,
   getInstallAllCommand,
+  runFrameworkReseed,
+  refreshActiveFleetUnits,
+  readRosterAgentNames,
+  buildRelaunchCommands,
+  checkFrameworkDrift,
+  FRAMEWORK_RESEED_PACKAGE,
 } from './runtime/update-checker.js';
 import { runWizard } from './wizard.js';
 import { ClackPrompter } from './prompter/clack-prompter.js';
@@ -404,10 +410,57 @@ 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');
 
+    // Re-seed the framework from the freshly-installed package, propagate shipped
+    // systemd unit fixes to the active units, and (opt-in) relaunch durable
+    // agents. Shared by the "packages updated" and the "framework drift" paths.
+    const reseedFramework = (reason: string): void => {
+      console.log(reason);
+      const reseed = runFrameworkReseed();
+      if (!reseed.ok) {
+        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)',
+        );
+        return;
+      }
+      console.log('✔ Framework re-seeded.');
+      // Propagate shipped systemd unit fixes to the ACTIVE units (re-seed only
+      // touches ~/.config/mosaic/systemd/user; systemd runs ~/.config/systemd/user).
+      const units = refreshActiveFleetUnits();
+      if (units.refreshed.length > 0) {
+        console.log(`✔ Refreshed ${units.refreshed.length} active systemd unit(s).`);
+      }
+      const agents = readRosterAgentNames();
+      if (agents.length === 0) return;
+      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>)',
+        );
+      }
+    };
+
     console.log('Checking for updates…');
     const results = checkForAllUpdates({ skipCache: true });
 
@@ -422,6 +475,18 @@ program
         process.exit(1);
       }
       console.log('\n✔ All packages up to date.');
+      // #642: the CLI may have been upgraded outside `mosaic update` (e.g. a
+      // direct `npm i -g`), leaving the framework files stale even though no
+      // package is reported outdated. Detect that via the framework version and
+      // re-seed so shipped launcher/runtime fixes still activate.
+      const drift = checkFrameworkDrift();
+      if (drift.drifted && opts.reseed !== false) {
+        reseedFramework(
+          `\nFramework drift detected (on-disk v${drift.installed} < bundled v${drift.bundled}) — ` +
+            'the CLI was updated outside `mosaic update`. Re-seeding framework files into ' +
+            '~/.config/mosaic (data-safe; keeps your edits)…',
+        );
+      }
       return;
     }
 
@@ -442,6 +507,22 @@ 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.
+    // Re-seed when the framework-bearing package itself updated OR the on-disk
+    // framework is older than the freshly-installed one (#642 — e.g. only
+    // sibling packages were outdated but the CLI was already ahead).
+    const mosaicUpdated = outdated.some(
+      (r: { package: string }) => r.package === FRAMEWORK_RESEED_PACKAGE,
+    );
+    const drift = checkFrameworkDrift();
+    if ((mosaicUpdated || drift.drifted) && opts.reseed !== false) {
+      reseedFramework(
+        '\nRe-seeding framework files into ~/.config/mosaic (data-safe; keeps your edits)…',
+      );
+    }
   });
 
 // ─── wizard ─────────────────────────────────────────────────────────────

packages/mosaic/src/commands/compose-contract.spec.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { composeContract } from './launch.js';
+
+/**
+ * Composer unit test (R7/R8/R9): asserts the launcher-composed runtime contract
+ *
+ *   - includes the per-tier anchors (CONSTITUTION / AGENTS / USER / runtime),
+ *   - keeps the CONSTITUTION block byte-equal to the on-disk file (Tier-3
+ *     byte-equality — the bare-launch fallback read must match what is injected),
+ *   - merges `*.local.md` operator overlays as deltas-by-value, and omits them
+ *     entirely when absent (base-only),
+ *   - selects the correct per-harness RUNTIME.md.
+ *
+ * `composeContract` takes `mosaicHome` as a param, so each test runs against an
+ * isolated fixture home. We also chdir to an empty temp cwd so the cwd-relative
+ * mission/PRD blocks contribute nothing (deterministic output).
+ */
+
+const CONSTITUTION = '# CONSTITUTION\n\nGATE-1: the non-negotiable law.\n';
+const AGENTS = '# Mosaic Agent Dispatcher\n\nLoad order + guide router.\n';
+const USER = '# operator\n\nName: Test Operator\n';
+const TOOLS = '# tools index\n';
+
+function makeHome(): { home: string; root: string } {
+  const root = mkdtempSync(join(tmpdir(), 'mosaic-compose-'));
+  const home = join(root, 'mosaic-home');
+  for (const h of ['claude', 'codex', 'opencode', 'pi']) {
+    mkdirSync(join(home, 'runtime', h), { recursive: true });
+    writeFileSync(join(home, 'runtime', h, 'RUNTIME.md'), `# ${h} runtime contract\n`);
+  }
+  writeFileSync(join(home, 'CONSTITUTION.md'), CONSTITUTION);
+  writeFileSync(join(home, 'AGENTS.md'), AGENTS);
+  writeFileSync(join(home, 'USER.md'), USER);
+  writeFileSync(join(home, 'TOOLS.md'), TOOLS);
+  return { home, root };
+}
+
+describe('composeContract — overlay composer', () => {
+  let fixture: ReturnType<typeof makeHome>;
+  let prevCwd: string;
+  let cwdDir: string;
+
+  beforeEach(() => {
+    fixture = makeHome();
+    prevCwd = process.cwd();
+    cwdDir = mkdtempSync(join(tmpdir(), 'mosaic-cwd-'));
+    process.chdir(cwdDir); // neutralize cwd-relative mission/PRD blocks
+  });
+
+  afterEach(() => {
+    process.chdir(prevCwd);
+    rmSync(fixture.root, { recursive: true, force: true });
+    rmSync(cwdDir, { recursive: true, force: true });
+  });
+
+  it('injects the fleet comms cheat-sheet for a spawned fleet agent (situational)', () => {
+    // A spawned agent has MOSAIC_AGENT_NAME set + is a member of the roster.
+    mkdirSync(join(fixture.home, 'fleet'), { recursive: true });
+    writeFileSync(
+      join(fixture.home, 'fleet', 'roster.yaml'),
+      [
+        'version: 1',
+        'transport: tmux',
+        'agents:',
+        '  - name: orchestrator',
+        '    runtime: claude',
+        '    class: orchestrator',
+        '  - name: enhancer',
+        '    runtime: claude',
+        '    class: enhancer',
+        '  - name: coder0-0',
+        '    runtime: claude',
+        '    class: implementer',
+        '    host: 10.1.10.37',
+        '    ssh: jwoltje@10.1.10.37',
+        '',
+      ].join('\n'),
+    );
+    const prev = process.env['MOSAIC_AGENT_NAME'];
+    try {
+      process.env['MOSAIC_AGENT_NAME'] = 'enhancer';
+      const out = composeContract('claude', fixture.home);
+      expect(out).toContain('# Fleet Comms');
+      expect(out).toMatch(/`\[[^\]]+:enhancer\]`/); // own [host:session] identity (host machine-dependent)
+      // local peer → no -H; cross-host peer → -H ssh
+      expect(out).toContain('-s orchestrator -m "…"');
+      expect(out).toContain('-H jwoltje@10.1.10.37 -s coder0-0 -m "…"');
+      expect(out).not.toContain('-H jwoltje@10.1.10.37 -s orchestrator'); // local stays local
+    } finally {
+      if (prev === undefined) delete process.env['MOSAIC_AGENT_NAME'];
+      else process.env['MOSAIC_AGENT_NAME'] = prev;
+    }
+  });
+
+  it('does NOT inject fleet comms when MOSAIC_AGENT_NAME is unset (non-fleet launch)', () => {
+    const prev = process.env['MOSAIC_AGENT_NAME'];
+    try {
+      delete process.env['MOSAIC_AGENT_NAME'];
+      expect(composeContract('claude', fixture.home)).not.toContain('# Fleet Comms');
+    } finally {
+      if (prev !== undefined) process.env['MOSAIC_AGENT_NAME'] = prev;
+    }
+  });
+
+  it('includes the per-tier anchors and the selected harness runtime', () => {
+    const out = composeContract('claude', fixture.home);
+    expect(out).toContain('GATE-1: the non-negotiable law.'); // L0
+    expect(out).toContain('Mosaic Agent Dispatcher'); // AGENTS
+    expect(out).toContain('# User Profile'); // USER header
+    expect(out).toContain('Name: Test Operator'); // USER body
+    expect(out).toContain('# Runtime-Specific Contract');
+    expect(out).toContain('# claude runtime contract');
+  });
+
+  it('keeps the CONSTITUTION block byte-equal to the on-disk file (Tier-3)', () => {
+    const out = composeContract('pi', fixture.home);
+    const onDisk = readFileSync(join(fixture.home, 'CONSTITUTION.md'), 'utf-8');
+    // The injected L0 must be a byte-equal substring of the composed blob, so a
+    // bare-launch fallback read of CONSTITUTION.md matches what was injected.
+    expect(out.includes(onDisk)).toBe(true);
+  });
+
+  it('is base-only when no *.local overlays exist', () => {
+    const out = composeContract('claude', fixture.home);
+    expect(out).not.toContain('# Operator Overlays');
+    expect(out).not.toContain('Operator Overlay (USER.local.md)');
+    expect(out).not.toContain('Persona Overlay');
+    expect(out).not.toContain('Standards Overlay');
+  });
+
+  it('merges USER.local.md directly under the operator profile', () => {
+    writeFileSync(join(fixture.home, 'USER.local.md'), 'Prefer terse status updates.\n');
+    const out = composeContract('claude', fixture.home);
+    expect(out).toContain('## Operator Overlay (USER.local.md)');
+    expect(out).toContain('Prefer terse status updates.');
+    // Overlay appears AFTER its base profile.
+    expect(out.indexOf('# User Profile')).toBeLessThan(
+      out.indexOf('## Operator Overlay (USER.local.md)'),
+    );
+  });
+
+  it('merges SOUL.local.md + STANDARDS.local.md as deltas in the Operator Overlays block', () => {
+    writeFileSync(join(fixture.home, 'SOUL.local.md'), 'Tone: dry and direct.\n');
+    writeFileSync(join(fixture.home, 'STANDARDS.local.md'), 'Require 90% coverage on auth code.\n');
+    const out = composeContract('claude', fixture.home);
+    expect(out).toContain('# Operator Overlays');
+    expect(out).toContain('## Persona Overlay (SOUL.local.md)');
+    expect(out).toContain('Tone: dry and direct.');
+    expect(out).toContain('## Standards Overlay (STANDARDS.local.md)');
+    expect(out).toContain('Require 90% coverage on auth code.');
+  });
+
+  it('ignores whitespace-only *.local overlays (no empty overlay section)', () => {
+    writeFileSync(join(fixture.home, 'SOUL.local.md'), '   \n\n');
+    const out = composeContract('claude', fixture.home);
+    expect(out).not.toContain('# Operator Overlays');
+  });
+
+  it('selects a different RUNTIME.md per harness', () => {
+    expect(composeContract('codex', fixture.home)).toContain('# codex runtime contract');
+    expect(composeContract('pi', fixture.home)).toContain('# pi runtime contract');
+    expect(composeContract('codex', fixture.home)).not.toContain('# pi runtime contract');
+  });
+});

packages/mosaic/src/commands/fleet-backlog.ts

@@ -0,0 +1,285 @@
+/**
+ * `mosaic fleet backlog <sub> --json` — Mosaic-native backlog of record.
+ *
+ * Mosaic OWNS this backlog end-to-end on its existing Postgres storage layer
+ * (`@mosaicstack/db`). It REPLACES the former Hermes adapter — there is NO
+ * runtime dependency on Hermes.
+ *
+ * Storage tier (the existing storage-layer convention, no new engine):
+ *   - default: embedded PGlite at <mosaicHome>/fleet/backlog (real Postgres
+ *     semantics, persisted on disk so the operator's backlog survives reboots
+ *     and `mosaic update` — see install.sh PRESERVE_PATHS).
+ *   - DATABASE_URL set: full server Postgres — same code, no change.
+ *
+ * Migrations run on first use so the `backlog` table always exists.
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import {
+  BacklogService,
+  DEFAULT_CLAIM_TTL_SECONDS,
+  type BacklogCard,
+  type DbHandle,
+} from '@mosaicstack/db';
+
+function defaultMosaicHome(): string {
+  return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
+}
+
+/** Resolve where the embedded PGlite backlog store lives (default tier). */
+export function defaultBacklogDataDir(mosaicHome = defaultMosaicHome()): string {
+  return join(mosaicHome, 'fleet', 'backlog');
+}
+
+/**
+ * Open a db handle for the backlog and ensure the schema exists.
+ *
+ * Tier detection mirrors the storage layer: DATABASE_URL => server Postgres
+ * (migrations applied via runMigrations); otherwise embedded PGlite at the
+ * fleet/backlog data dir (migrations applied via runPgliteMigrations).
+ */
+async function openBacklogDb(mosaicHome: string): Promise<DbHandle> {
+  const { createDb, createPgliteDb, runMigrations, runPgliteMigrations } =
+    await import('@mosaicstack/db');
+  const url = process.env['DATABASE_URL'];
+  if (url) {
+    await runMigrations(url);
+    return createDb(url);
+  }
+  const dataDir = process.env['PGLITE_DATA_DIR'] ?? defaultBacklogDataDir(mosaicHome);
+  // PGlite writes a file-backed store to dataDir but does not create missing
+  // parent directories (e.g. <mosaicHome>/fleet). Create them first. Skip for
+  // the in-memory pseudo-paths so a memory:// store never touches the fs.
+  if (!dataDir.startsWith('memory://') && dataDir !== ':memory:') {
+    await mkdir(dataDir, { recursive: true });
+  }
+  const handle = createPgliteDb(dataDir);
+  await runPgliteMigrations(handle);
+  return handle;
+}
+
+function parseDependsOn(value?: string): string[] {
+  if (!value) return [];
+  return value
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+function parseAcceptance(value?: string): unknown {
+  if (!value) return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    // Fall back to a list of newline/semicolon-separated criteria.
+    return value
+      .split(/[\n;]/)
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+  }
+}
+
+function printCard(card: BacklogCard | null, json?: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(card));
+    return;
+  }
+  if (!card) {
+    console.log('(none)');
+    return;
+  }
+  const deps = card.dependsOn.length ? card.dependsOn.join(',') : '-';
+  console.log(
+    `${card.id}\t[${card.status}]\tp=${card.priority}\tphase=${card.phase ?? '-'}\tdeps=${deps}\t${card.title}`,
+  );
+}
+
+function printCards(cards: BacklogCard[], json?: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(cards));
+    return;
+  }
+  if (cards.length === 0) {
+    console.log('(no cards)');
+    return;
+  }
+  for (const card of cards) printCard(card, false);
+}
+
+/**
+ * Register `backlog` under an existing `fleet` command.
+ * `mosaicHomeFor` resolves the active --mosaic-home (parent flag) at call time.
+ */
+export function registerFleetBacklogCommand(
+  fleetCmd: Command,
+  mosaicHomeFor: () => string,
+): Command {
+  const backlogCmd = fleetCmd
+    .command('backlog')
+    .description('Mosaic-native backlog of record (atomic claim + TTL, deps DAG)');
+
+  const withSvc = async <T>(fn: (svc: BacklogService) => Promise<T>): Promise<T> => {
+    const handle = await openBacklogDb(mosaicHomeFor());
+    try {
+      return await fn(new BacklogService(handle.db));
+    } finally {
+      await handle.close();
+    }
+  };
+
+  backlogCmd
+    .command('create')
+    .description('Create a backlog card (idempotency_key dedups)')
+    .requiredOption('--id <id>', 'Stable card id')
+    .requiredOption('--title <title>', 'Card title')
+    .option('--body <body>', 'Card body / description')
+    .option('--phase <phase>', 'Board/phase grouping')
+    .option('--priority <n>', 'Priority (higher = sooner)', (v) => parseInt(v, 10), 0)
+    .option('--depends-on <ids>', 'Comma-separated dependency card ids')
+    .option('--acceptance <json>', 'Acceptance criteria (JSON or ;/newline list)')
+    .option('--idempotency-key <key>', 'Dedup key; repeat returns the existing card')
+    .option('--json', 'Print JSON')
+    .action(
+      async (opts: {
+        id: string;
+        title: string;
+        body?: string;
+        phase?: string;
+        priority: number;
+        dependsOn?: string;
+        acceptance?: string;
+        idempotencyKey?: string;
+        json?: boolean;
+      }) => {
+        const card = await withSvc((svc) =>
+          svc.create({
+            id: opts.id,
+            title: opts.title,
+            body: opts.body ?? null,
+            phase: opts.phase ?? null,
+            priority: opts.priority,
+            dependsOn: parseDependsOn(opts.dependsOn),
+            acceptance: parseAcceptance(opts.acceptance),
+            idempotencyKey: opts.idempotencyKey ?? null,
+          }),
+        );
+        printCard(card, opts.json);
+      },
+    );
+
+  backlogCmd
+    .command('list')
+    .description('List cards (filters: --status, --phase, --ready-only)')
+    .option('--status <status>', 'Filter by status: ready|claimed|blocked|done')
+    .option('--phase <phase>', 'Filter by phase')
+    .option('--ready-only', 'Only cards that are ready AND have all deps done')
+    .option('--json', 'Print JSON')
+    .action(
+      async (opts: {
+        status?: BacklogCard['status'];
+        phase?: string;
+        readyOnly?: boolean;
+        json?: boolean;
+      }) => {
+        const cards = await withSvc((svc) =>
+          svc.list({
+            ...(opts.status ? { status: opts.status } : {}),
+            ...(opts.phase ? { phase: opts.phase } : {}),
+            ...(opts.readyOnly ? { readyOnly: true } : {}),
+          }),
+        );
+        printCards(cards, opts.json);
+      },
+    );
+
+  backlogCmd
+    .command('claim')
+    .description('Atomically claim the highest-priority ready card (FOR UPDATE SKIP LOCKED)')
+    .requiredOption('--owner <owner>', 'Claim owner (worker/agent id)')
+    .option(
+      '--ttl <sec>',
+      'Claim TTL in seconds',
+      (v) => parseInt(v, 10),
+      DEFAULT_CLAIM_TTL_SECONDS,
+    )
+    .option('--id <id>', 'Claim a specific card by id')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { owner: string; ttl: number; id?: string; json?: boolean }) => {
+      const card = await withSvc((svc) =>
+        svc.claim({ owner: opts.owner, ttlSeconds: opts.ttl, ...(opts.id ? { id: opts.id } : {}) }),
+      );
+      printCard(card, opts.json);
+      if (!card && !opts.json) process.exitCode = 0;
+    });
+
+  backlogCmd
+    .command('reclaim')
+    .description('Release expired claims back to ready (or a specific --id)')
+    .option('--id <id>', 'Release a specific card regardless of expiry')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { id?: string; json?: boolean }) => {
+      const result = await withSvc((svc) => svc.reclaim(opts.id ? { id: opts.id } : {}));
+      if (opts.json) {
+        console.log(JSON.stringify(result));
+      } else if (result.reclaimed.length === 0) {
+        console.log('(nothing to reclaim)');
+      } else {
+        console.log(`reclaimed: ${result.reclaimed.join(', ')}`);
+      }
+    });
+
+  backlogCmd
+    .command('link')
+    .description('Add a depends_on edge (--from depends on --to)')
+    .requiredOption('--from <id>', 'Card that gains the dependency')
+    .requiredOption('--to <id>', 'Card it now depends on')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { from: string; to: string; json?: boolean }) => {
+      const card = await withSvc((svc) => svc.link(opts.from, opts.to));
+      printCard(card, opts.json);
+    });
+
+  backlogCmd
+    .command('stats')
+    .description('Counts by status, oldest-ready age, expired-claim count')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { json?: boolean }) => {
+      const stats = await withSvc((svc) => svc.stats());
+      if (opts.json) {
+        console.log(JSON.stringify(stats));
+        return;
+      }
+      console.log(`total: ${stats.total}`);
+      console.log(
+        `ready=${stats.counts.ready} claimed=${stats.counts.claimed} ` +
+          `blocked=${stats.counts.blocked} done=${stats.counts.done}`,
+      );
+      console.log(`oldest-ready-age: ${stats.oldestReadyAgeSeconds ?? '-'}s`);
+      console.log(`expired-claims: ${stats.expiredClaimCount}`);
+    });
+
+  backlogCmd
+    .command('block')
+    .description('Mark a card blocked')
+    .requiredOption('--id <id>', 'Card id')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { id: string; json?: boolean }) => {
+      const card = await withSvc((svc) => svc.block(opts.id));
+      printCard(card, opts.json);
+    });
+
+  backlogCmd
+    .command('complete')
+    .description('Mark a card done')
+    .requiredOption('--id <id>', 'Card id')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { id: string; json?: boolean }) => {
+      const card = await withSvc((svc) => svc.complete(opts.id));
+      printCard(card, opts.json);
+    });
+
+  return backlogCmd;
+}

packages/mosaic/src/commands/fleet-north-star.spec.ts

@@ -0,0 +1,199 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  parseNorthStar,
+  renderNorthStarMarkdown,
+  resolveNorthStarPaths,
+  type NorthStar,
+} from './fleet.js';
+
+// Repo root resolved from this spec file: packages/mosaic/src/commands → up 4.
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
+const yamlPath = join(repoRoot, 'docs', 'fleet', 'NORTH_STAR.yaml');
+
+async function loadYamlText(): Promise<string> {
+  return readFile(yamlPath, 'utf8');
+}
+
+async function loadParsed(): Promise<NorthStar> {
+  return parseNorthStar(await loadYamlText());
+}
+
+describe('NORTH_STAR.yaml', () => {
+  it('parses to a typed object with the required top-level keys', async () => {
+    const ns = await loadParsed();
+    expect(ns.version).toBeTypeOf('number');
+    expect(ns.mission).toContain('self-driving Mosaic delivery fleet');
+    expect(ns.substrate.note).toBeTruthy();
+    expect(ns.standing_objectives.length).toBeGreaterThan(0);
+    expect(ns.success_criteria.length).toBeGreaterThan(0);
+    expect(ns.workstreams.length).toBeGreaterThan(0);
+    expect(ns.goals.length).toBeGreaterThan(0);
+    expect(ns.assumptions.length).toBeGreaterThan(0);
+    expect(ns.spend.advisory).toBe(true);
+  });
+
+  it('names the native Postgres storage layer and declares no Hermes runtime dependency', async () => {
+    const rawText = await loadYamlText();
+    const lower = rawText.toLowerCase();
+    expect(rawText).toContain('@mosaicstack/db');
+    expect(lower).toContain('postgres');
+    expect(lower).toContain('pglite');
+    // The doctrine explicitly disowns Hermes ("NOT Hermes"); the only mentions
+    // are negations. Assert there is no Hermes RUNTIME dependency: no hermes
+    // CLI/kanban invocation and no ~/.hermes storage reference.
+    expect(lower).not.toContain('hermes kanban');
+    expect(lower).not.toContain('~/.hermes');
+    expect(lower).not.toContain('hermes mcp');
+  });
+
+  it('declares all NS-1..NS-8 standing objectives', async () => {
+    const ns = await loadParsed();
+    const ids = ns.standing_objectives.map((o) => o.id);
+    for (let n = 1; n <= 8; n += 1) {
+      expect(ids).toContain(`NS-${n}`);
+    }
+  });
+
+  it('declares all AC-NS-1..AC-NS-5 success criteria', async () => {
+    const ns = await loadParsed();
+    const ids = ns.success_criteria.map((c) => c.id);
+    for (let n = 1; n <= 5; n += 1) {
+      expect(ids).toContain(`AC-NS-${n}`);
+    }
+  });
+
+  it('seeds the expected backlog goal ids', async () => {
+    const ns = await loadParsed();
+    const ids = ns.goals.map((g) => g.id);
+    expect(ids).toEqual(
+      expect.arrayContaining(['A1', 'A2', 'A3a', 'A3b', 'A4', 'B1', 'B2', 'B3a', 'B3b', 'G1']),
+    );
+  });
+
+  it('has a coherent depends_on DAG (every dependency references a known goal)', async () => {
+    const ns = await loadParsed();
+    const ids = new Set(ns.goals.map((g) => g.id));
+    for (const goal of ns.goals) {
+      for (const dep of goal.depends_on) {
+        expect(ids.has(dep)).toBe(true);
+      }
+      // No goal may depend on itself.
+      expect(goal.depends_on).not.toContain(goal.id);
+    }
+    // A1 is the root: no dependencies.
+    const a1 = ns.goals.find((g) => g.id === 'A1');
+    expect(a1?.depends_on).toEqual([]);
+  });
+
+  it('marks spend as advisory with a degrade-to-TTL note', async () => {
+    const ns = await loadParsed();
+    expect(ns.spend.advisory).toBe(true);
+    expect(ns.spend.note.toLowerCase()).toContain('ttl');
+  });
+});
+
+describe('renderNorthStarMarkdown', () => {
+  it('is a pure deterministic projection (round-trip stable)', async () => {
+    const ns = await loadParsed();
+    const first = renderNorthStarMarkdown(ns);
+    const second = renderNorthStarMarkdown(ns);
+    expect(first).toBe(second);
+    // Re-parsing the same YAML and re-rendering yields identical bytes.
+    const reparsed = parseNorthStar(await loadYamlText());
+    expect(renderNorthStarMarkdown(reparsed)).toBe(first);
+  });
+
+  it('matches the committed NORTH_STAR.md projection (regenerate if this fails)', async () => {
+    const ns = await loadParsed();
+    const rendered = `${renderNorthStarMarkdown(ns)}\n`;
+    const committed = await readFile(join(repoRoot, 'docs', 'fleet', 'NORTH_STAR.md'), 'utf8');
+    expect(rendered).toBe(committed);
+  });
+
+  it('projects mission, objectives, criteria, goals, assumptions, and spend', async () => {
+    const ns = await loadParsed();
+    const md = renderNorthStarMarkdown(ns);
+    expect(md).toContain('# Mosaic Fleet — NORTH STAR');
+    expect(md).toContain('## Mission');
+    expect(md).toContain('## Standing objectives');
+    expect(md).toContain('**NS-1**');
+    expect(md).toContain('**AC-NS-5**');
+    expect(md).toContain('## Goals (backlog projection)');
+    // Tables are column-padded (prettier-style); match the row id, not exact spacing.
+    expect(md).toMatch(/\| A1\s+\|/);
+    expect(md).toContain('## Assumptions (vetoable)');
+    expect(md).toContain('**advisory:** true');
+    // The banner disowns Hermes; the projection carries no Hermes runtime hook.
+    expect(md.toLowerCase()).not.toContain('hermes kanban');
+    expect(md.toLowerCase()).not.toContain('~/.hermes');
+  });
+
+  it('does no network or CLI work (pure functions; only the writer touches IO)', () => {
+    // parseNorthStar + renderNorthStarMarkdown take strings and return strings.
+    // Guard against accidental IO by asserting fetch/spawn are never invoked.
+    const fetchSpy = vi.spyOn(globalThis, 'fetch' as never).mockImplementation((() => {
+      throw new Error('network access is forbidden in the NORTH_STAR generator');
+    }) as never);
+    try {
+      const yaml = [
+        'version: 1',
+        'mission: m',
+        'substrate:',
+        '  note: n',
+        'standing_objectives:',
+        '  - { id: NS-1, text: t }',
+        'success_criteria:',
+        '  - { id: AC-NS-1, text: t }',
+        'workstreams:',
+        '  - { id: A, title: t }',
+        'goals:',
+        '  - { id: A1, title: t, phase: 1, priority: must-have, depends_on: [] }',
+        'assumptions:',
+        '  - { id: ASM-1, vetoable: true, text: t }',
+        'spend:',
+        '  advisory: true',
+        '  note: TTL',
+        '',
+      ].join('\n');
+      const ns = parseNorthStar(yaml);
+      const md = renderNorthStarMarkdown(ns);
+      expect(md).toContain('# Mosaic Fleet — NORTH STAR');
+      expect(fetchSpy).not.toHaveBeenCalled();
+    } finally {
+      fetchSpy.mockRestore();
+    }
+  });
+});
+
+describe('parseNorthStar validation', () => {
+  it('throws on a missing required key', () => {
+    expect(() => parseNorthStar('version: 1\n')).toThrow();
+  });
+
+  it('throws when spend.advisory is not a boolean', () => {
+    const yaml = [
+      'version: 1',
+      'mission: m',
+      'substrate: { note: n }',
+      'standing_objectives: [{ id: NS-1, text: t }]',
+      'success_criteria: [{ id: AC-NS-1, text: t }]',
+      'workstreams: [{ id: A, title: t }]',
+      'goals: [{ id: A1, title: t, phase: 1, priority: must-have, depends_on: [] }]',
+      'assumptions: [{ id: ASM-1, vetoable: true, text: t }]',
+      'spend: { advisory: maybe, note: TTL }',
+      '',
+    ].join('\n');
+    expect(() => parseNorthStar(yaml)).toThrow(/spend\.advisory/);
+  });
+});
+
+describe('resolveNorthStarPaths', () => {
+  it('resolves YAML + Markdown under docs/fleet from a given repo root', () => {
+    const paths = resolveNorthStarPaths('/repo');
+    expect(paths.yamlPath).toBe('/repo/docs/fleet/NORTH_STAR.yaml');
+    expect(paths.markdownPath).toBe('/repo/docs/fleet/NORTH_STAR.md');
+  });
+});

packages/mosaic/src/commands/launch.ts

@@ -19,6 +19,7 @@ import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import type { Command } from 'commander';
+import { readFleetCommsBlock } from '../fleet/comms-onboarding.js';
 
 const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
 
@@ -291,12 +292,23 @@ function buildPrdBlock(): string {
 
 // ─── Runtime prompt builder ──────────────────────────────────────────────────
 
-function buildRuntimePrompt(runtime: RuntimeName): string {
+/**
+ * Compose the full runtime contract for a harness: the resident-by-value core
+ * (CONSTITUTION + AGENTS + USER + TOOLS + runtime) plus operator overlays
+ * (`*.local.md` deltas), merged in precedence order so the model gets one
+ * pre-merged blob (DESIGN §3.2 / R7). Overlays are injected as deltas by value;
+ * base files keep their existing residency (USER injected; SOUL/STANDARDS are
+ * load-on-demand, so only their small `.local` deltas are injected here).
+ *
+ * `mosaicHome` is parameterized for testability; production callers use the
+ * module-level default.
+ */
+export function composeContract(runtime: RuntimeName, mosaicHome: string = MOSAIC_HOME): string {
   const runtimeContractPaths: Record<RuntimeName, string> = {
-    claude: join(MOSAIC_HOME, 'runtime', 'claude', 'RUNTIME.md'),
+    claude: join(mosaicHome, 'runtime', 'claude', 'RUNTIME.md'),
-    codex: join(MOSAIC_HOME, 'runtime', 'codex', 'RUNTIME.md'),
+    codex: join(mosaicHome, 'runtime', 'codex', 'RUNTIME.md'),
-    opencode: join(MOSAIC_HOME, 'runtime', 'opencode', 'RUNTIME.md'),
+    opencode: join(mosaicHome, 'runtime', 'opencode', 'RUNTIME.md'),
-    pi: join(MOSAIC_HOME, 'runtime', 'pi', 'RUNTIME.md'),
+    pi: join(mosaicHome, 'runtime', 'pi', 'RUNTIME.md'),
   };
 
   const runtimeFile = runtimeContractPaths[runtime];
@@ -331,27 +343,61 @@ For required push/merge/issue-close/release actions, execute without routine con
 `);
 
   // CONSTITUTION.md (L0 — the non-negotiable law; lead with it). Tolerant of
-  // pre-constitution installs that have not been re-seeded yet.
+  // pre-constitution installs that have not been re-seeded yet. Injected by
-  const constitution = readOptional(join(MOSAIC_HOME, 'CONSTITUTION.md'));
+  // value verbatim so the bare-launch fallback read is byte-equal (R8).
+  const constitution = readOptional(join(mosaicHome, 'CONSTITUTION.md'));
   if (constitution) parts.push(constitution);
 
   // AGENTS.md
-  parts.push(readFileSync(join(MOSAIC_HOME, 'AGENTS.md'), 'utf-8'));
+  parts.push(readFileSync(join(mosaicHome, 'AGENTS.md'), 'utf-8'));
 
-  // USER.md
+  // USER.md (+ USER.local.md operator overlay, appended directly under the
-  const user = readOptional(join(MOSAIC_HOME, 'USER.md'));
+  // profile its base owns).
+  const user = readOptional(join(mosaicHome, 'USER.md'));
   if (user) parts.push('\n\n# User Profile\n\n' + user);
+  const userLocal = readOptional(join(mosaicHome, 'USER.local.md'));
+  if (userLocal.trim()) {
+    parts.push('\n\n## Operator Overlay (USER.local.md)\n\n' + userLocal);
+  }
 
   // TOOLS.md
-  const tools = readOptional(join(MOSAIC_HOME, 'TOOLS.md'));
+  const tools = readOptional(join(mosaicHome, 'TOOLS.md'));
   if (tools) parts.push('\n\n# Machine Tools\n\n' + tools);
 
+  // Operator overlays whose base layers are load-on-demand (SOUL, STANDARDS):
+  // inject only the small `.local` delta by value so the customization reaches
+  // the model without re-injecting the full base prose (preserves the byte
+  // budget). Absent `.local` files → base-only, automatically (R7 §3.2).
+  const overlayBlocks: string[] = [];
+  const soulLocal = readOptional(join(mosaicHome, 'SOUL.local.md'));
+  if (soulLocal.trim()) {
+    overlayBlocks.push('## Persona Overlay (SOUL.local.md)\n\n' + soulLocal.trim());
+  }
+  const standardsLocal = readOptional(join(mosaicHome, 'STANDARDS.local.md'));
+  if (standardsLocal.trim()) {
+    overlayBlocks.push('## Standards Overlay (STANDARDS.local.md)\n\n' + standardsLocal.trim());
+  }
+  if (overlayBlocks.length > 0) {
+    parts.push('\n\n# Operator Overlays\n\n' + overlayBlocks.join('\n\n'));
+  }
+
   // Runtime-specific contract
   parts.push('\n\n# Runtime-Specific Contract\n\n' + readFileSync(runtimeFile, 'utf-8'));
 
+  // Fleet onboarding: when this is a spawned fleet agent (MOSAIC_AGENT_NAME set
+  // and present in the roster), inject a comms cheat-sheet + peer roster so it
+  // knows how to reach the orchestrator and its peers from its first turn.
+  const fleetComms = readFleetCommsBlock(mosaicHome, process.env['MOSAIC_AGENT_NAME']);
+  if (fleetComms) parts.push('\n\n' + fleetComms);
+
   return parts.join('\n');
 }
 
+/** @deprecated internal alias — use composeContract. Retained for call-site clarity. */
+function buildRuntimePrompt(runtime: RuntimeName): string {
+  return composeContract(runtime);
+}
+
 // ─── Session lock ────────────────────────────────────────────────────────────
 
 function writeSessionLock(runtime: string): void {
@@ -976,6 +1022,22 @@ export function registerLaunchCommands(program: Command): void {
     launchRuntime(runtime, extraArgs, yolo);
   });
 
+  // compose-contract — emit the composed runtime contract (base + operator
+  // overlays) for a harness to stdout, without launching. For inspection,
+  // `mosaic doctor`, diffing, and the composer test (R7).
+  program
+    .command('compose-contract <harness>')
+    .description('Print the composed runtime contract (base + *.local overlays) for a harness')
+    .action((harness: string) => {
+      const valid: RuntimeName[] = ['claude', 'codex', 'opencode', 'pi'];
+      if (!valid.includes(harness as RuntimeName)) {
+        console.error(`Unknown harness '${harness}'. Expected one of: ${valid.join(', ')}.`);
+        process.exitCode = 64;
+        return;
+      }
+      process.stdout.write(composeContract(harness as RuntimeName));
+    });
+
   // Coord (mission orchestrator)
   program
     .command('coord')

packages/mosaic/src/config/file-adapter.test.ts

@@ -99,11 +99,8 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => {
     );
   });
 
-  it('preserves existing contract files — never overwrites user customization', async () => {
+  it('overwrites framework-owned files (backup-once) but preserves user-seeded files', async () => {
-    // Also plant a root-level AGENTS.md in sourceDir so that `syncDirectory`
+    // Plant a root-level AGENTS.md in sourceDir so syncDirectory's preserve is exercised.
-    // itself (not just the seed loop) has something to try to overwrite.
-    // Without this, the test would silently pass even if preserve semantics
-    // were broken in syncDirectory.
     writeFileSync(join(fixture.sourceDir, 'AGENTS.md'), '# shipped AGENTS from source root\n');
 
     writeFileSync(join(fixture.mosaicHome, 'TOOLS.md'), '# user-customized TOOLS\n');
@@ -112,18 +109,74 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => {
     const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
     await adapter.syncFramework('keep');
 
+    // User-seeded TOOLS.md is preserved.
     expect(readFileSync(join(fixture.mosaicHome, 'TOOLS.md'), 'utf-8')).toBe(
       '# user-customized TOOLS\n',
     );
-    expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md'), 'utf-8')).toBe(
+    // Framework-owned AGENTS.md is overwritten from defaults/ ...
+    expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md'), 'utf-8')).toBe('# AGENTS default\n');
+    // ... and the user's prior copy is backed up exactly once.
+    expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md.pre-constitution.bak'), 'utf-8')).toBe(
       '# user-customized AGENTS\n',
     );
-    // And the missing contract file still gets seeded.
+    // Framework-owned STANDARDS.md (absent) gets installed.
     expect(readFileSync(join(fixture.mosaicHome, 'STANDARDS.md'), 'utf-8')).toContain(
       '# STANDARDS default',
     );
   });
 
+  it('backs up a divergent framework-owned file only once (idempotent across re-sync)', async () => {
+    writeFileSync(join(fixture.mosaicHome, 'AGENTS.md'), '# user-customized AGENTS\n');
+    const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
+
+    await adapter.syncFramework('keep'); // 1st: backup created, AGENTS overwritten
+    await adapter.syncFramework('keep'); // 2nd: AGENTS already == default, no new backup
+
+    expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md.pre-constitution.bak'), 'utf-8')).toBe(
+      '# user-customized AGENTS\n',
+    );
+  });
+
+  it('preserves SOUL.md and credentials through a framework-owned overwrite', async () => {
+    writeFileSync(join(fixture.mosaicHome, 'SOUL.md'), '# my persona\n');
+    writeFileSync(join(fixture.mosaicHome, 'AGENTS.md'), '# user-customized AGENTS\n');
+    mkdirSync(join(fixture.mosaicHome, 'credentials'), { recursive: true });
+    writeFileSync(join(fixture.mosaicHome, 'credentials', 'c.json'), 'token\n');
+
+    const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
+    await adapter.syncFramework('keep');
+
+    expect(readFileSync(join(fixture.mosaicHome, 'SOUL.md'), 'utf-8')).toBe('# my persona\n');
+    expect(readFileSync(join(fixture.mosaicHome, 'credentials', 'c.json'), 'utf-8')).toBe(
+      'token\n',
+    );
+    expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md'), 'utf-8')).toBe('# AGENTS default\n');
+  });
+
+  it('preserves user fleet data (roster.yaml, agents/, run/) through a keep-mode sync', async () => {
+    // Regression for the roster-loss bug (#631): user-authored fleet files must
+    // survive the framework re-seed that `mosaic update` runs.
+    mkdirSync(join(fixture.mosaicHome, 'fleet', 'run'), { recursive: true });
+    mkdirSync(join(fixture.mosaicHome, 'fleet', 'agents'), { recursive: true });
+    writeFileSync(join(fixture.mosaicHome, 'fleet', 'roster.yaml'), 'version: 1\nMINE\n');
+    writeFileSync(join(fixture.mosaicHome, 'fleet', 'run', 'a.hb'), 'ts=x\n');
+    writeFileSync(join(fixture.mosaicHome, 'fleet', 'agents', 'a.env'), 'X=1\n');
+    // The framework ships fleet/examples — it should still seed/refresh.
+    mkdirSync(join(fixture.sourceDir, 'fleet', 'examples'), { recursive: true });
+    writeFileSync(join(fixture.sourceDir, 'fleet', 'examples', 'general.yaml'), '# preset\n');
+
+    const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
+    await adapter.syncFramework('keep');
+
+    expect(readFileSync(join(fixture.mosaicHome, 'fleet', 'roster.yaml'), 'utf-8')).toBe(
+      'version: 1\nMINE\n',
+    );
+    expect(existsSync(join(fixture.mosaicHome, 'fleet', 'run', 'a.hb'))).toBe(true);
+    expect(existsSync(join(fixture.mosaicHome, 'fleet', 'agents', 'a.env'))).toBe(true);
+    // framework-owned fleet/examples is seeded
+    expect(existsSync(join(fixture.mosaicHome, 'fleet', 'examples', 'general.yaml'))).toBe(true);
+  });
+
   it('is a no-op for seeding when defaults/ dir does not exist', async () => {
     rmSync(fixture.defaultsDir, { recursive: true });
 

packages/mosaic/src/config/file-adapter.ts

@@ -13,12 +13,17 @@ import { join } from 'node:path';
  * This list must match the explicit seed loop in
  * packages/mosaic/framework/install.sh.
  */
-export const DEFAULT_SEED_FILES = [
+// Framework-owned contract files: re-copied from defaults/ on every upgrade (a
-  'CONSTITUTION.md',
+// divergent existing copy is backed up once to <file>.pre-constitution.bak first).
-  'AGENTS.md',
+// MUST match FRAMEWORK_OWNED in packages/mosaic/framework/install.sh (append-friendly).
-  'STANDARDS.md',
+export const FRAMEWORK_OWNED_FILES = ['CONSTITUTION.md', 'AGENTS.md', 'STANDARDS.md'] as const;
-  'TOOLS.md',
+
-] as const;
+// User-seeded contract files: written once on first install, then owned by the user.
+// MUST match USER_SEEDED in packages/mosaic/framework/install.sh.
+export const USER_SEEDED_FILES = ['TOOLS.md'] as const;
+
+// Union, retained for callers/tests that assert the full seed set on a fresh install.
+export const DEFAULT_SEED_FILES = [...FRAMEWORK_OWNED_FILES, ...USER_SEEDED_FILES] as const;
 import type { ConfigService, ConfigSection, ResolvedConfig } from './config-service.js';
 import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
 import { soulSchema, userSchema, toolsSchema } from './schemas.js';
@@ -159,6 +164,7 @@ export class FileConfigAdapter implements ConfigService {
     const preservePaths =
       action === 'keep' || action === 'reconfigure'
         ? [
+            'CONSTITUTION.md',
             'AGENTS.md',
             'SOUL.md',
             'USER.md',
@@ -167,6 +173,13 @@ export class FileConfigAdapter implements ConfigService {
             'memory',
             'sources',
             'credentials',
+            // User-authored fleet data MUST survive `mosaic update`'s re-seed.
+            // The framework seeds only fleet/examples + fleet/roles +
+            // fleet/roster.schema.json; the operator's roster, per-agent env, and
+            // heartbeat run dir stay user-owned. (Mirror of install.sh PRESERVE_PATHS.)
+            'fleet/*.yaml',
+            'fleet/agents',
+            'fleet/run',
           ]
         : [];
 
@@ -175,10 +188,10 @@ export class FileConfigAdapter implements ConfigService {
       excludeGit: true,
     });
 
-    // Copy framework-contract files (AGENTS.md, STANDARDS.md, TOOLS.md)
+    // Reconcile framework-contract files from framework/defaults/ into the mosaic
-    // from framework/defaults/ into the mosaic home root if they don't
+    // home root: framework-owned files (CONSTITUTION/AGENTS/STANDARDS) are overwritten
-    // exist yet. These are written on first install only and are never
+    // every upgrade (backup-once); user-seeded files (TOOLS) are written on first
-    // overwritten afterwards — the user may have customized them.
+    // install only. Mirrors reconcile_framework_files() in install.sh.
     //
     // SOUL.md and USER.md are deliberately NOT seeded here. They are
     // generated from templates by the soul/user wizard stages with
@@ -186,7 +199,22 @@ export class FileConfigAdapter implements ConfigService {
     // identity flow and leak placeholder content into the mosaic home.
     const defaultsDir = join(this.sourceDir, 'defaults');
     if (existsSync(defaultsDir)) {
-      for (const entry of DEFAULT_SEED_FILES) {
+      // Framework-owned: overwrite from defaults/ every sync; back up a divergent
+      // existing copy ONCE to <file>.pre-constitution.bak before the first overwrite.
+      for (const entry of FRAMEWORK_OWNED_FILES) {
+        const src = join(defaultsDir, entry);
+        const dest = join(this.mosaicHome, entry);
+        if (!existsSync(src) || !statSync(src).isFile()) continue;
+        // Already current — skip to avoid mtime churn.
+        if (existsSync(dest) && readFileSync(src).equals(readFileSync(dest))) continue;
+        const bak = `${dest}.pre-constitution.bak`;
+        if (existsSync(dest) && !existsSync(bak)) {
+          copyFileSync(dest, bak);
+        }
+        copyFileSync(src, dest);
+      }
+      // User-seeded: write only if absent.
+      for (const entry of USER_SEEDED_FILES) {
         const src = join(defaultsDir, entry);
         const dest = join(this.mosaicHome, entry);
         if (existsSync(dest)) continue;

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

@@ -0,0 +1,238 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  parseRosterAgents,
+  buildFleetCommsBlock,
+  renderPeerReach,
+  readFleetCommsBlock,
+  resolveCommsBlock,
+  type CommsPeer,
+} from './comms-onboarding.js';
+
+const ROSTER = [
+  'version: 1',
+  'transport: tmux',
+  'agents:',
+  '  - name: orchestrator',
+  '    runtime: claude',
+  '    class: orchestrator',
+  '  - name: enhancer',
+  '    runtime: claude',
+  '    class: enhancer',
+  '  - name: coder0',
+  '    runtime: pi',
+  '    class: implementer',
+  '  # a manually-listed cross-host peer (pre-federation stopgap)',
+  '  - name: coder0-0',
+  '    runtime: claude',
+  '    class: implementer',
+  '    host: 10.1.10.37',
+  '    ssh: jwoltje@10.1.10.37',
+  '',
+].join('\n');
+
+describe('parseRosterAgents', () => {
+  it('parses name + class + optional host/ssh', () => {
+    const peers = parseRosterAgents(ROSTER);
+    expect(peers.map((p) => p.name)).toEqual(['orchestrator', 'enhancer', 'coder0', 'coder0-0']);
+    expect(peers.find((p) => p.name === 'coder0')).toMatchObject({ className: 'implementer' });
+    expect(peers.find((p) => p.name === 'coder0-0')).toMatchObject({
+      className: 'implementer',
+      host: '10.1.10.37',
+      ssh: 'jwoltje@10.1.10.37',
+    });
+    // local agents have no host/ssh
+    expect(peers.find((p) => p.name === 'orchestrator')!.host).toBeUndefined();
+  });
+
+  it('parses an optional per-agent socket', () => {
+    const peers = parseRosterAgents(
+      ['agents:', '  - name: a', '    class: worker', '    socket: mosaic-fleet'].join('\n'),
+    );
+    expect(peers[0]).toMatchObject({ name: 'a', socket: 'mosaic-fleet' });
+  });
+
+  it('stops at the next top-level key', () => {
+    const peers = parseRosterAgents(
+      ['agents:', '  - name: a', '    class: worker', 'defaults:', '  working_directory: ~'].join(
+        '\n',
+      ),
+    );
+    expect(peers.map((p) => p.name)).toEqual(['a']);
+  });
+});
+
+describe('renderPeerReach — same-host vs cross-host', () => {
+  const send = '/home/u/.config/mosaic/tools/tmux/agent-send.sh';
+
+  it('renders the short form for a same-host peer', () => {
+    const peer: CommsPeer = { name: 'enhancer', className: 'enhancer' };
+    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(`${send} -s enhancer -m "…"`);
+  });
+
+  it('renders the -H form for a cross-host peer using ssh', () => {
+    const peer: CommsPeer = {
+      name: 'coder0-0',
+      className: 'implementer',
+      host: '10.1.10.37',
+      ssh: 'jwoltje@10.1.10.37',
+    };
+    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
+      `${send} -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`,
+    );
+  });
+
+  it('falls back to host when a cross-host peer has no ssh', () => {
+    const peer: CommsPeer = { name: 'x', className: 'worker', host: '10.0.0.9' };
+    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(`${send} -H 10.0.0.9 -s x -m "…"`);
+  });
+
+  it('treats a peer whose host equals the fleet host as same-host', () => {
+    const peer: CommsPeer = { name: 'y', className: 'worker', host: 'w-jarvis' };
+    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(`${send} -s y -m "…"`);
+  });
+
+  it('emits NO -L for an unset/default socket', () => {
+    const peer: CommsPeer = { name: 'lead', className: 'orchestrator' };
+    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(`${send} -s lead -m "…"`);
+  });
+
+  it('emits -L <socket> for a named socket', () => {
+    const peer: CommsPeer = { name: 'coder0', className: 'implementer', socket: 'mosaic-fleet' };
+    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
+      `${send} -L mosaic-fleet -s coder0 -m "…"`,
+    );
+  });
+
+  it('combines -L (named socket) and -H (cross-host) in order', () => {
+    const peer: CommsPeer = {
+      name: 'coder0-0',
+      className: 'implementer',
+      host: '10.1.10.37',
+      ssh: 'jwoltje@10.1.10.37',
+      socket: 'mosaic-fleet',
+    };
+    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
+      `${send} -L mosaic-fleet -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`,
+    );
+  });
+});
+
+describe('buildFleetCommsBlock', () => {
+  const send = '/h/.config/mosaic/tools/tmux/agent-send.sh';
+  const agents = parseRosterAgents(ROSTER);
+
+  it('excludes self, lists peers, flags the orchestrator, and emits both address forms', () => {
+    const block = buildFleetCommsBlock({
+      selfName: 'enhancer',
+      agents,
+      fleetHost: 'w-jarvis',
+      agentSendPath: send,
+    });
+    expect(block).toContain('# Fleet Comms');
+    expect(block).toContain('You are **enhancer**');
+    // criterion 1: agent's own [host:session] identity
+    expect(block).toContain('`[w-jarvis:enhancer]`');
+    // self excluded
+    expect(block).not.toMatch(/\|\s*enhancer\s*\|/);
+    // peers present
+    expect(block).toContain('| orchestrator |');
+    expect(block).toContain('point of contact');
+    // same-host peer short form
+    expect(block).toContain(`${send} -s coder0 -m "…"`);
+    // cross-host peer -H form + host annotation
+    expect(block).toContain(`${send} -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`);
+    expect(block).toContain('host `10.1.10.37`');
+    // conventions
+    expect(block).toContain('FLIP the preamble');
+    expect(block).toContain('ACCEPTED');
+  });
+
+  it('returns empty when the agent has no peers', () => {
+    expect(
+      buildFleetCommsBlock({
+        selfName: 'solo',
+        agents: [{ name: 'solo', className: 'orchestrator' }],
+        fleetHost: 'h',
+        agentSendPath: send,
+      }),
+    ).toBe('');
+  });
+});
+
+describe('readFleetCommsBlock — situational (the context a spawned agent gets)', () => {
+  let home: string;
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'mosaic-comms-'));
+    mkdirSync(join(home, 'fleet'), { recursive: true });
+    writeFileSync(join(home, 'fleet', 'roster.yaml'), ROSTER);
+  });
+  afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+  it('builds the cheat-sheet with correct peer addresses for a fleet member', () => {
+    const block = readFleetCommsBlock(home, 'orchestrator', 'w-jarvis');
+    expect(block).toContain('# Fleet Comms');
+    expect(block).toContain('| enhancer |');
+    expect(block).toContain(`${join(home, 'tools', 'tmux', 'agent-send.sh')} -s coder0 -m "…"`);
+    expect(block).toContain('-H jwoltje@10.1.10.37 -s coder0-0');
+    expect(block).not.toMatch(/\|\s*orchestrator\s*\|/); // self excluded
+  });
+
+  it('returns empty when MOSAIC_AGENT_NAME is unset, no roster, or agent not a member', () => {
+    expect(readFleetCommsBlock(home, undefined, 'w-jarvis')).toBe('');
+    expect(readFleetCommsBlock(home, 'stranger', 'w-jarvis')).toBe('');
+    expect(readFleetCommsBlock(mkdtempSync(join(tmpdir(), 'noroster-')), 'orchestrator')).toBe('');
+  });
+});
+
+describe('resolveCommsBlock — `mosaic fleet comms-block <role>` emitter semantics', () => {
+  // The emitter wraps readFleetCommsBlock but must NEVER print an empty string silently:
+  // an unknown role / missing roster has to fail loud (caller maps !ok → stderr + exit 1)
+  // so `mosaic fleet comms-block bogus` is a visible error, not a confusing no-op. The
+  // success path returns the block verbatim for `mosaic fleet comms-block <peer>` previews.
+  let home: string;
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'mosaic-commsblk-'));
+    mkdirSync(join(home, 'fleet'), { recursive: true });
+    writeFileSync(join(home, 'fleet', 'roster.yaml'), ROSTER);
+  });
+  afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+  it('returns ok + the cheat-sheet for a roster member', () => {
+    const res = resolveCommsBlock(home, 'orchestrator', 'w-jarvis');
+    expect(res.ok).toBe(true);
+    expect(res.output).toContain('# Fleet Comms');
+    expect(res.output).toContain('| enhancer |');
+    expect(res.error).toBeUndefined();
+  });
+
+  it('fails loud (not ok + error naming the role) for a non-member — never silently empty', () => {
+    const res = resolveCommsBlock(home, 'stranger', 'w-jarvis');
+    expect(res.ok).toBe(false);
+    expect(res.output).toBe('');
+    expect(res.error).toContain('stranger');
+  });
+
+  it('fails loud when no roster exists at the mosaic home', () => {
+    const noRoster = mkdtempSync(join(tmpdir(), 'mosaic-noroster-'));
+    const res = resolveCommsBlock(noRoster, 'orchestrator', 'w-jarvis');
+    expect(res.ok).toBe(false);
+    expect(res.error).toBeTruthy();
+    rmSync(noRoster, { recursive: true, force: true });
+  });
+
+  it('fails loud for a missing role argument', () => {
+    const res = resolveCommsBlock(home, undefined, 'w-jarvis');
+    expect(res.ok).toBe(false);
+    expect(res.error).toBeTruthy();
+  });
+
+  it('honors a host override so a peer can preview its own cross-host view', () => {
+    // coder0-0 viewing with its own host → its self-identity line uses that host.
+    const res = resolveCommsBlock(home, 'coder0-0', '10.1.10.37');
+    expect(res.ok).toBe(true);
+    expect(res.output).toContain('`[10.1.10.37:coder0-0]`');
+  });
+});

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

@@ -0,0 +1,226 @@
+/**
+ * Fleet onboarding-injection (#620).
+ *
+ * Fleet agents are born not knowing how to reach their peers — the root cause of
+ * a spawned agent's failed first send. When an agent boots via `mosaic yolo
+ * <runtime>` (→ composeContract → system prompt), we append a comms cheat-sheet
+ * + peer roster so it can talk to the orchestrator and other agents immediately.
+ *
+ * Cross-host aware: a peer may carry `host`/`ssh` (a deliberate pre-federation
+ * stopgap — manual cross-host listing; federation/W1 auto-discovers later), so a
+ * w-jarvis agent is born knowing the exact `-H` command to reach a dragon-lin
+ * peer. Same-host peers render the short form.
+ *
+ * Standalone (no fleet.ts import) to keep launch.ts's prompt path free of the
+ * heavy fleet command module. The roster is parsed leniently — the cheat-sheet
+ * is best-effort onboarding, never a hard dependency.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+
+export interface CommsPeer {
+  name: string;
+  /** Roster `class` (orchestrator | enhancer | implementer | worker | …). */
+  className: string;
+  /** Host the peer runs on; absent ⇒ the fleet host (same host). */
+  host?: string;
+  /** SSH target (user@host) for a cross-host peer; renders the `-H` form. */
+  ssh?: string;
+  /** tmux socket the peer's session lives on; absent ⇒ default socket (no `-L`). */
+  socket?: string;
+}
+
+/**
+ * Lenient parse of a fleet `roster.yaml` for agent name/class/host/ssh. Avoids a
+ * dependency on the full fleet roster parser; the format is `- name:` list items
+ * with `class:`/`host:`/`ssh:` siblings under `agents:`.
+ */
+export function parseRosterAgents(yamlText: string): CommsPeer[] {
+  const peers: CommsPeer[] = [];
+  let current: CommsPeer | null = null;
+  let inAgents = false;
+  const scalar = (line: string, key: string): string | null => {
+    const m = line.match(new RegExp(`^\\s*${key}:\\s*["']?([^"'#]+?)["']?\\s*$`));
+    return m ? (m[1] as string).trim() : null;
+  };
+  for (const rawLine of yamlText.split('\n')) {
+    const line = rawLine.replace(/\s+$/, '');
+    if (/^agents:\s*$/.test(line)) {
+      inAgents = true;
+      continue;
+    }
+    if (!inAgents) continue;
+    // A new top-level key (no leading space) ends the agents block.
+    if (/^\S/.test(line)) break;
+
+    const nameMatch = line.match(/^\s*-\s*name:\s*["']?([A-Za-z0-9._-]+)["']?\s*$/);
+    if (nameMatch) {
+      if (current) peers.push(current);
+      current = { name: nameMatch[1] as string, className: 'worker' };
+      continue;
+    }
+    if (!current) continue;
+    const cls = scalar(line, 'class');
+    if (cls) current.className = cls;
+    const host = scalar(line, 'host');
+    if (host) current.host = host;
+    const ssh = scalar(line, 'ssh');
+    if (ssh) current.ssh = ssh;
+    const socket = scalar(line, 'socket');
+    if (socket) current.socket = socket;
+  }
+  if (current) peers.push(current);
+  return peers;
+}
+
+export interface FleetCommsOptions {
+  /** This agent's name (it is excluded from its own peer list). */
+  selfName: string;
+  /** All roster agents (including self; filtered out internally). */
+  agents: CommsPeer[];
+  /** Host the fleet runs on (short hostname) — the same-host baseline. */
+  fleetHost: string;
+  /** Absolute path to agent-send.sh in this install. */
+  agentSendPath: string;
+}
+
+/** Is this peer on a different host than the fleet baseline? */
+function isRemote(peer: CommsPeer, fleetHost: string): boolean {
+  return peer.host !== undefined && peer.host !== fleetHost;
+}
+
+/**
+ * Render the exact agent-send command to reach a peer (session = agent name).
+ * Data-driven per peer: a named `socket` → `-L <socket>`; an unset socket → the
+ * default tmux socket (no `-L`). A cross-host peer adds `-H <ssh|host>`.
+ */
+export function renderPeerReach(peer: CommsPeer, fleetHost: string, agentSendPath: string): string {
+  const parts = [agentSendPath];
+  if (peer.socket) parts.push('-L', peer.socket); // unset ⇒ default socket, no -L
+  if (isRemote(peer, fleetHost)) parts.push('-H', peer.ssh ?? (peer.host as string));
+  parts.push('-s', peer.name, '-m', '"…"');
+  return parts.join(' ');
+}
+
+/**
+ * Build the `# Fleet Comms` onboarding block (pure markdown). Returns '' when
+ * the agent has no peers (a single-agent roster has no one to talk to).
+ */
+export function buildFleetCommsBlock(opts: FleetCommsOptions): string {
+  const peers = opts.agents.filter((a) => a.name !== opts.selfName);
+  if (peers.length === 0) return '';
+
+  const orchestrator = peers.find((p) => p.className === 'orchestrator');
+  const rows = peers
+    .map((p) => {
+      const where = isRemote(p, opts.fleetHost)
+        ? `${p.className} · host \`${p.host}\``
+        : p.className;
+      const role = p.className === 'orchestrator' ? `${where} ← point of contact` : where;
+      return `| ${p.name} | ${role} | \`${renderPeerReach(p, opts.fleetHost, opts.agentSendPath)}\` |`;
+    })
+    .join('\n');
+
+  const orchLine = orchestrator
+    ? `Your point of contact is **${orchestrator.name}** (the orchestrator) — route questions, ` +
+      `status, and decisions there.`
+    : `This fleet has no orchestrator in its roster; coordinate with your peers directly.`;
+
+  return `# Fleet Comms — reach your peers
+
+You are **${opts.selfName}** in this fleet. Your comms identity is \`[${opts.fleetHost}:${opts.selfName}]\` —
+that is the \`<src>\` other agents see and reply to. Reach other agents (durable tmux sessions) with the
+Mosaic comms tool at \`${opts.agentSendPath}\`. The **Reach** column below is the exact command per peer:
+same-host peers use the short form (no \`-H\`); cross-host peers include \`-H <user@host>\`.
+
+## Peers
+
+| Agent | Role | Reach (session = agent name) |
+| ----- | ---- | ---------------------------- |
+${rows}
+
+${orchLine}
+
+## Conventions
+
+- Every message carries a self-identifying preamble \`[<src_host>:<src_session> -> <dst_host>:<dst_session>]\` — \`agent-send.sh\` adds it automatically.
+- **To reply, FLIP the preamble:** address your reply to the sender's \`src\` (their host:session becomes your \`-s\`/\`-H\`).
+- \`agent-send.sh\` (a.k.a. \`agent send --verify\`) confirms the message was **ACCEPTED** at the destination prompt — not merely injected. Prefer it for anything that matters.`;
+}
+
+/**
+ * Read the fleet roster from `mosaicHome` and build the comms block for
+ * `selfName`. Returns '' when there is no roster, the agent is not in it, or
+ * there are no peers — onboarding is best-effort and never throws.
+ */
+export function readFleetCommsBlock(
+  mosaicHome: string,
+  selfName: string | undefined,
+  fleetHost: string = hostname().split('.')[0] || 'localhost',
+): string {
+  if (!selfName) return '';
+  const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
+  if (!existsSync(rosterPath)) return '';
+  let text: string;
+  try {
+    text = readFileSync(rosterPath, 'utf-8');
+  } catch {
+    return '';
+  }
+  const agents = parseRosterAgents(text);
+  if (!agents.some((a) => a.name === selfName)) return ''; // not a member of this fleet
+  return buildFleetCommsBlock({
+    selfName,
+    agents,
+    fleetHost,
+    agentSendPath: join(mosaicHome, 'tools', 'tmux', 'agent-send.sh'),
+  });
+}
+
+/** Result of resolving a comms-block emit request — see `mosaic fleet comms-block`. */
+export interface CommsBlockResult {
+  /** True when a cheat-sheet was produced; false maps to stderr + non-zero exit. */
+  ok: boolean;
+  /** The Fleet-Comms cheat-sheet (empty unless ok). */
+  output: string;
+  /** Operator-facing reason when !ok. */
+  error?: string;
+}
+
+/**
+ * Resolve the Fleet-Comms cheat-sheet for an explicit <role>, backing the
+ * `mosaic fleet comms-block <role>` command. Unlike readFleetCommsBlock — which
+ * returns '' on any miss so composeContract can no-op silently during a launch —
+ * this NEVER silently emits empty: an unknown role or missing roster yields
+ * ok:false + an operator-facing reason, so the CLI surfaces it (stderr + exit 1)
+ * rather than printing nothing. That makes it safe to preview any peer's view,
+ * e.g. `mosaic fleet comms-block coder0-0`.
+ */
+export function resolveCommsBlock(
+  mosaicHome: string,
+  role: string | undefined,
+  fleetHost?: string,
+): CommsBlockResult {
+  if (!role) {
+    return { ok: false, output: '', error: 'comms-block requires a <role> argument' };
+  }
+  const block = fleetHost
+    ? readFleetCommsBlock(mosaicHome, role, fleetHost)
+    : readFleetCommsBlock(mosaicHome, role);
+  if (!block) {
+    const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
+    return {
+      ok: false,
+      output: '',
+      error: existsSync(rosterPath)
+        ? `role "${role}" is not a member of the fleet roster at ${rosterPath}`
+        : `no fleet roster at ${rosterPath}`,
+    };
+  }
+  return { ok: true, output: block };
+}
+
+/** Default mosaic home (mirrors launch.ts), for callers that don't pass one. */
+export const DEFAULT_MOSAIC_HOME_FOR_COMMS = join(homedir(), '.config', 'mosaic');

packages/mosaic/src/fleet/connectors/matrix.spec.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  MatrixConnector,
+  buildMessageBody,
+  parseSyncResponse,
+  registerMatrixConnector,
+  type FetchLike,
+} from './matrix.js';
+import { createConnector, _resetConnectorRegistry } from './registry.js';
+import type { MatrixConnectorConfig } from './types.js';
+
+const CONFIG: MatrixConnectorConfig = {
+  homeserverUrl: 'https://matrix.internal/',
+  userId: '@mos:internal',
+  roomId: '!room:internal',
+};
+
+/** A fetch mock that returns queued responses and records calls. */
+function mockFetch(responses: Array<{ ok?: boolean; status?: number; body?: unknown }>): {
+  fetchImpl: FetchLike;
+  calls: Array<{ url: string; method?: string; body?: string }>;
+} {
+  const calls: Array<{ url: string; method?: string; body?: string }> = [];
+  let i = 0;
+  const fetchImpl: FetchLike = async (url, init) => {
+    calls.push({ url, method: init?.method, body: init?.body });
+    const r = responses[Math.min(i, responses.length - 1)] ?? {};
+    i += 1;
+    return {
+      ok: r.ok ?? true,
+      status: r.status ?? 200,
+      json: async () => r.body ?? {},
+      text: async () => JSON.stringify(r.body ?? {}),
+    };
+  };
+  return { fetchImpl, calls };
+}
+
+describe('buildMessageBody', () => {
+  it('builds an m.text event', () => {
+    expect(buildMessageBody({ text: 'hi' })).toEqual({ msgtype: 'm.text', body: 'hi' });
+  });
+  it('adds an m.thread relation when threadId is set', () => {
+    expect(buildMessageBody({ text: 'hi', threadId: '$evt' })).toEqual({
+      msgtype: 'm.text',
+      body: 'hi',
+      'm.relates_to': { rel_type: 'm.thread', event_id: '$evt' },
+    });
+  });
+});
+
+describe('parseSyncResponse', () => {
+  it('extracts operator messages and skips the orchestrator’s own echoes', () => {
+    const data = {
+      next_batch: 's2',
+      rooms: {
+        join: {
+          '!room:internal': {
+            timeline: {
+              events: [
+                {
+                  type: 'm.room.message',
+                  sender: '@jason:internal',
+                  origin_server_ts: 1_700_000_000_000,
+                  content: { body: 'status?' },
+                },
+                {
+                  type: 'm.room.message',
+                  sender: '@mos:internal', // self — skipped
+                  origin_server_ts: 1_700_000_001_000,
+                  content: { body: 'working on it' },
+                },
+                { type: 'm.reaction', sender: '@jason:internal', content: {} }, // non-message
+              ],
+            },
+          },
+        },
+      },
+    };
+    const msgs = parseSyncResponse(data, '!room:internal', '@mos:internal');
+    expect(msgs).toHaveLength(1);
+    expect(msgs[0]).toMatchObject({ text: 'status?', sender: '@jason:internal' });
+    expect(msgs[0]!.ts).toBe(new Date(1_700_000_000_000).toISOString());
+  });
+
+  it('carries threadId through thread-relments', () => {
+    const data = {
+      rooms: {
+        join: {
+          '!room:internal': {
+            timeline: {
+              events: [
+                {
+                  type: 'm.room.message',
+                  sender: '@jason:internal',
+                  origin_server_ts: 1,
+                  content: {
+                    body: 'in thread',
+                    'm.relates_to': { rel_type: 'm.thread', event_id: '$root' },
+                  },
+                },
+              ],
+            },
+          },
+        },
+      },
+    };
+    expect(parseSyncResponse(data, '!room:internal', '@mos:internal')[0]!.threadId).toBe('$root');
+  });
+
+  it('returns [] for an empty/foreign sync', () => {
+    expect(parseSyncResponse({}, '!room:internal', '@mos:internal')).toEqual([]);
+  });
+});
+
+describe('MatrixConnector', () => {
+  it('throws without an access token', () => {
+    expect(() => new MatrixConnector(CONFIG, { accessToken: '' })).toThrow(/access token/i);
+  });
+
+  it('send PUTs an m.text event and returns the event id', async () => {
+    const { fetchImpl, calls } = mockFetch([{ body: { event_id: '$abc' } }]);
+    const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
+    const res = await c.send({ text: 'pong' }, 1234);
+    expect(res).toEqual({ delivered: true, messageId: '$abc' });
+    expect(calls[0]!.method).toBe('PUT');
+    expect(calls[0]!.url).toContain(
+      '/_matrix/client/v3/rooms/!room%3Ainternal/send/m.room.message/mosaic-1234-1',
+    );
+    expect(JSON.parse(calls[0]!.body!)).toEqual({ msgtype: 'm.text', body: 'pong' });
+  });
+
+  it('send reports not-delivered on a non-2xx', async () => {
+    const { fetchImpl } = mockFetch([{ ok: false, status: 403 }]);
+    const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
+    const res = await c.send({ text: 'x' });
+    expect(res.delivered).toBe(false);
+    expect(res.error).toContain('403');
+  });
+
+  it('health reports reachable + authenticated when whoami matches', async () => {
+    const { fetchImpl } = mockFetch([
+      { body: { versions: ['v1.11'] } }, // /versions
+      { body: { user_id: '@mos:internal' } }, // /whoami
+    ]);
+    const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
+    const h = await c.health();
+    expect(h.reachable).toBe(true);
+    expect(h.authenticated).toBe(true);
+  });
+
+  it('health flags auth mismatch', async () => {
+    const { fetchImpl } = mockFetch([
+      { body: {} },
+      { body: { user_id: '@someone-else:internal' } },
+    ]);
+    const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
+    const h = await c.health();
+    expect(h.reachable).toBe(true);
+    expect(h.authenticated).toBe(false);
+  });
+
+  it('health reports unreachable when /versions fails', async () => {
+    const { fetchImpl } = mockFetch([{ ok: false, status: 502 }]);
+    const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
+    const h = await c.health();
+    expect(h.reachable).toBe(false);
+  });
+});
+
+describe('registerMatrixConnector', () => {
+  beforeEach(() => _resetConnectorRegistry());
+
+  it('registers a matrix factory createConnector can build', () => {
+    registerMatrixConnector({ MATRIX_ACCESS_TOKEN: 'tok' } as NodeJS.ProcessEnv);
+    const c = createConnector({ kind: 'matrix', matrix: CONFIG });
+    expect(c.kind).toBe('matrix');
+  });
+
+  it('the factory rejects config missing the matrix block', () => {
+    registerMatrixConnector({ MATRIX_ACCESS_TOKEN: 'tok' } as NodeJS.ProcessEnv);
+    expect(() => createConnector({ kind: 'matrix' })).toThrow(/missing the .matrix. block/i);
+  });
+});

packages/mosaic/src/fleet/connectors/matrix.ts

@@ -0,0 +1,246 @@
+/**
+ * Matrix connector (F4 Phase 2) — speaks the Matrix client-server API directly
+ * over HTTPS so it is homeserver-agnostic (Conduit default, Synapse alt). No
+ * SDK: a small injectable fetch keeps it dependency-light and unit-testable.
+ *
+ * The access token is supplied by the caller (from the environment —
+ * MATRIX_ACCESS_TOKEN — per the gateway secret pattern), never the roster.
+ */
+
+import {
+  type OrchestratorConnector,
+  type OutboundMessage,
+  type InboundMessage,
+  type SendResult,
+  type ConnectorHealth,
+  type MatrixConnectorConfig,
+  type Unsubscribe,
+} from './types.js';
+import { registerConnector } from './registry.js';
+
+/** Minimal fetch surface — avoids a lib.dom dependency and is trivial to mock. */
+export interface FetchLike {
+  (
+    url: string,
+    init?: { method?: string; headers?: Record<string, string>; body?: string },
+  ): Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+    text: () => Promise<string>;
+  }>;
+}
+
+export interface MatrixConnectorOptions {
+  accessToken: string;
+  /** Injectable fetch (defaults to global fetch). */
+  fetchImpl?: FetchLike;
+  /** Long-poll timeout for /sync, ms. */
+  syncTimeoutMs?: number;
+}
+
+/** Build the `m.room.message` event content, threading when a threadId is set. */
+export function buildMessageBody(message: OutboundMessage): Record<string, unknown> {
+  const content: Record<string, unknown> = {
+    msgtype: 'm.text',
+    body: message.text,
+  };
+  if (message.threadId) {
+    content['m.relates_to'] = { rel_type: 'm.thread', event_id: message.threadId };
+  }
+  return content;
+}
+
+/** Shape of the bits of a /sync response we consume. */
+interface SyncResponse {
+  next_batch?: string;
+  rooms?: {
+    join?: Record<
+      string,
+      {
+        timeline?: {
+          events?: Array<{
+            type?: string;
+            sender?: string;
+            origin_server_ts?: number;
+            content?: {
+              body?: string;
+              ['m.relates_to']?: { rel_type?: string; event_id?: string };
+            };
+          }>;
+        };
+      }
+    >;
+  };
+}
+
+/**
+ * Extract inbound operator messages from a /sync response for one room,
+ * skipping the orchestrator's own echoes. Pure — the testable core of receive.
+ */
+export function parseSyncResponse(
+  data: unknown,
+  roomId: string,
+  selfUserId: string,
+): InboundMessage[] {
+  const sync = data as SyncResponse;
+  const events = sync.rooms?.join?.[roomId]?.timeline?.events ?? [];
+  const out: InboundMessage[] = [];
+  for (const ev of events) {
+    if (ev.type !== 'm.room.message') continue;
+    if (!ev.sender || ev.sender === selfUserId) continue; // skip our own messages
+    const body = ev.content?.body;
+    if (typeof body !== 'string') continue;
+    const rel = ev.content?.['m.relates_to'];
+    out.push({
+      text: body,
+      sender: ev.sender,
+      ts: new Date(ev.origin_server_ts ?? 0).toISOString(),
+      ...(rel?.rel_type === 'm.thread' && rel.event_id ? { threadId: rel.event_id } : {}),
+    });
+  }
+  return out;
+}
+
+export class MatrixConnector implements OrchestratorConnector {
+  readonly kind = 'matrix' as const;
+  private readonly fetchImpl: FetchLike;
+  private readonly token: string;
+  private readonly syncTimeoutMs: number;
+  private txnCounter = 0;
+  private stopped = false;
+
+  constructor(
+    private readonly config: MatrixConnectorConfig,
+    opts: MatrixConnectorOptions,
+  ) {
+    this.token = opts.accessToken;
+    this.fetchImpl = opts.fetchImpl ?? (globalThis.fetch as unknown as FetchLike);
+    this.syncTimeoutMs = opts.syncTimeoutMs ?? 30_000;
+    if (!this.token) {
+      throw new Error('MatrixConnector requires an access token (set MATRIX_ACCESS_TOKEN).');
+    }
+  }
+
+  private url(path: string): string {
+    return `${this.config.homeserverUrl.replace(/\/$/, '')}${path}`;
+  }
+
+  private authHeaders(): Record<string, string> {
+    return { Authorization: `Bearer ${this.token}`, 'Content-Type': 'application/json' };
+  }
+
+  /** Monotonic, unique-per-instance transaction id for idempotent sends. */
+  private nextTxnId(nowMs: number): string {
+    this.txnCounter += 1;
+    return `mosaic-${nowMs}-${this.txnCounter}`;
+  }
+
+  async send(message: OutboundMessage, nowMs = Date.now()): Promise<SendResult> {
+    const txnId = this.nextTxnId(nowMs);
+    const path = `/_matrix/client/v3/rooms/${encodeURIComponent(
+      this.config.roomId,
+    )}/send/m.room.message/${encodeURIComponent(txnId)}`;
+    try {
+      const res = await this.fetchImpl(this.url(path), {
+        method: 'PUT',
+        headers: this.authHeaders(),
+        body: JSON.stringify(buildMessageBody(message)),
+      });
+      if (!res.ok) {
+        return { delivered: false, error: `Matrix send failed: HTTP ${res.status}` };
+      }
+      const json = (await res.json()) as { event_id?: string };
+      return { delivered: true, ...(json.event_id ? { messageId: json.event_id } : {}) };
+    } catch (err) {
+      return { delivered: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  subscribe(handler: (message: InboundMessage) => void): Unsubscribe {
+    this.stopped = false;
+    let since: string | undefined;
+    const loop = async (): Promise<void> => {
+      while (!this.stopped) {
+        try {
+          const q = new URLSearchParams({ timeout: String(this.syncTimeoutMs) });
+          if (since) q.set('since', since);
+          const res = await this.fetchImpl(this.url(`/_matrix/client/v3/sync?${q.toString()}`), {
+            method: 'GET',
+            headers: this.authHeaders(),
+          });
+          if (!res.ok) {
+            await this.backoff();
+            continue;
+          }
+          const data = await res.json();
+          since = (data as SyncResponse).next_batch ?? since;
+          for (const msg of parseSyncResponse(data, this.config.roomId, this.config.userId)) {
+            handler(msg);
+          }
+        } catch {
+          await this.backoff();
+        }
+      }
+    };
+    void loop();
+    return () => {
+      this.stopped = true;
+    };
+  }
+
+  private backoff(): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, 2_000));
+  }
+
+  async health(): Promise<ConnectorHealth> {
+    try {
+      const versions = await this.fetchImpl(this.url('/_matrix/client/versions'), {
+        method: 'GET',
+      });
+      if (!versions.ok) {
+        return {
+          reachable: false,
+          authenticated: false,
+          detail: `versions HTTP ${versions.status}`,
+        };
+      }
+      const who = await this.fetchImpl(this.url('/_matrix/client/v3/account/whoami'), {
+        method: 'GET',
+        headers: this.authHeaders(),
+      });
+      if (!who.ok) {
+        return { reachable: true, authenticated: false, detail: `whoami HTTP ${who.status}` };
+      }
+      const json = (await who.json()) as { user_id?: string };
+      const authenticated = json.user_id === this.config.userId;
+      return {
+        reachable: true,
+        authenticated,
+        lastSeen: new Date().toISOString(),
+        ...(authenticated
+          ? {}
+          : { detail: `whoami user ${json.user_id} != ${this.config.userId}` }),
+      };
+    } catch (err) {
+      return {
+        reachable: false,
+        authenticated: false,
+        detail: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+}
+
+/**
+ * Register the Matrix connector factory. The token is read from the environment
+ * (MATRIX_ACCESS_TOKEN) at build time, never the roster.
+ */
+export function registerMatrixConnector(env: NodeJS.ProcessEnv = process.env): void {
+  registerConnector('matrix', (config) => {
+    if (!config.matrix) {
+      throw new Error('Matrix connector config missing the `matrix` block (homeserver/user/room).');
+    }
+    return new MatrixConnector(config.matrix, { accessToken: env['MATRIX_ACCESS_TOKEN'] ?? '' });
+  });
+}

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