fix(install): preserve user fleet data on re-seed + refresh active units (#631)

CRITICAL data-loss in the routine update path. `mosaic update` auto-runs
install.sh keep-mode sync (#610); the rsync --delete honored PRESERVE_PATHS but
fleet/ was not listed, so the sync WIPED ~/.config/mosaic/fleet/roster.yaml (and
fleet/run, fleet/agents). Any user running `mosaic update` lost their fleet.

PRIMARY (data-loss):
- install.sh PRESERVE_PATHS += fleet/*.yaml, fleet/agents, fleet/run. The
  framework still SEEDS fleet/examples + fleet/roles + fleet/roster.schema.json
  (synced); the operator's roster, custom rosters, per-agent env, and heartbeat
  run dir are preserved.
- Made the cp (no-rsync) fallback GLOB-AWARE so fleet/*.yaml is preserved there
  too; fixed the restore to re-glob per pattern (restores only the user file,
  not the freshly-synced fleet/ dir).
- file-adapter.ts (TS installer): mirrored the preserve list for dual-installer
  parity. (syncDirectory is copy-only — never --delete — so it never had the
  bug; this is parity + belt-and-suspenders.)

SECONDARY (stale active units):
- refreshActiveFleetUnits(): the re-seed updates ~/.config/mosaic/systemd/user
  but systemd runs ~/.config/systemd/user, so shipped unit fixes (#627) did not
  take effect after update. `mosaic update` now copies the fresh mosaic-*.service
  → the active dir + daemon-reload (best-effort, only when a fleet is installed).

Verified: bash F6 fixture (roster/custom-yaml/agents/run survive + examples
refreshed + schema seeded), 20/20 migration matrix; TS file-adapter keep-mode
test; 2 refreshActiveFleetUnits unit tests. tsc/eslint/prettier/sanitize clean.

Refs #631

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83

.gitignore

@@ -15,10 +15,3 @@ 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,5 +1 @@
 @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

@@ -1,40 +0,0 @@
-# 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,9 +1,5 @@
-# &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 'git.mosaicstack.dev/mosaicstack/stack/ci-base:latest'
+  - &node_image 'node:22-alpine'
   - &enable_pnpm 'corepack enable'
 
 when:
@@ -19,9 +15,8 @@ steps:
     image: *node_image
     commands:
       - corepack enable
-      # python3/make/g++ are baked into ci-base; --prefer-offline resolves from
-      # the baked pnpm store.
-      - pnpm install --frozen-lockfile --prefer-offline
+      - apk add --no-cache python3 make g++
+      - pnpm install --frozen-lockfile
 
   # Blocking gate: public framework package must contain no operator-specific
   # personal data or private $HOME defaults. Runs early (no node_modules needed).
@@ -69,7 +64,8 @@ steps:
       DATABASE_URL: postgresql://mosaic:mosaic@ci-postgres:5432/mosaic
     commands:
       - *enable_pnpm
-      # postgresql-client (pg_isready) is baked into ci-base.
+      # Install postgresql-client for pg_isready
+      - 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,9 +2,7 @@
 # Runs only on main branch push/tag
 
 variables:
-  # 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'
+  - &node_image 'node:22-alpine'
   - &enable_pnpm 'corepack enable'
   # Heavy kaniko image builds (~25 min) — gate them so a merge that only touches
   # the npm-only CLI (@mosaicstack/mosaic) or docs does NOT rebuild the platform
@@ -33,8 +31,7 @@ steps:
     image: *node_image
     commands:
       - corepack enable
-      # Resolve from the baked pnpm store instead of a cold network fetch.
-      - pnpm install --frozen-lockfile --prefer-offline
+      - pnpm install --frozen-lockfile
 
   build:
     image: *node_image

Dockerfile.ci

@@ -1,45 +0,0 @@
-# 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

@@ -79,14 +79,6 @@ Active workstream is **W1 — Federation v1**. Workers should:
 
 - 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/fleet/FLEET-LAUNCH.md

@@ -1,114 +0,0 @@
-# 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/PRD.md

@@ -7,10 +7,10 @@
 
 ## Problem
 
-The durable tmux fleet runs on the isolated `mosaic-fleet` socket. That isolation
+The durable tmux fleet runs on the isolated `mosaic-factory` 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`).
+(`systemctl --user`), tmux (`-L mosaic-factory`), 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.
@@ -56,7 +56,7 @@ observability and no safe way to watch a session.
 
 ## Acceptance criteria
 
-- `mosaic fleet ps` shows all 5 live sessions on `mosaic-fleet` with correct
+- `mosaic fleet ps` shows all 5 live sessions on `mosaic-factory` 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`.
@@ -72,7 +72,7 @@ observability and no safe way to watch a session.
 - 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,
+- Situational: run against the live `mosaic-factory` fleet; capture `fleet ps` output,
   a kill-and-detect cycle, a read-only `watch`, and a `send --verify` pass/fail pair.
 
 ## Known limitations

docs/fleet/TASKS.md

@@ -8,11 +8,11 @@
 > 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-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-factory; 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                                                                                  |

docs/fleet/north-star.md

@@ -56,21 +56,13 @@ The Fleet inherits — does not re-invent — the MVP's hard requirements:
 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)
 
@@ -121,67 +113,6 @@ Every artifact, starting Phase 2, MUST:
 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                                                                                           |
@@ -196,83 +127,15 @@ authorization**. (Also feeds the budgeting workstream, not only this doc.)
 > (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 |
+| 4 — Unified definition | one agent schema in gateway; `mosaic agent --new` → materialized per-tenant session; uid-tenant provisioning                                 | planned |
+| 5 — Control plane      | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity                                    | planned |
 
 ## Decisions of record (2026-06-20, with Jason)
 
@@ -301,57 +164,6 @@ re-evaluate if isolation or write-volume demands it.
 - **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)
 
@@ -361,16 +173,6 @@ re-evaluate if isolation or write-volume demands it.
   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)
 
@@ -382,30 +184,3 @@ re-evaluate if isolation or write-volume demands it.
 - `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-fleet`; the commands do
+isolated tmux socket. The default socket is `mosaic-factory`; 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-fleet`.
+uses the tmux send tools with `-L mosaic-factory`.
 
 `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-fleet ls
+tmux -L mosaic-factory 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-fleet ls` shows `_holder` and roster agent sessions.
+- `tmux -L mosaic-factory 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-fleet ls` or exact `has-session` checks.
+  with `tmux -L mosaic-factory 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-fleet kill-server
+tmux -L mosaic-factory 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-fleet`
+- canary verification on named tmux socket `mosaic-factory`
 
 ## 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-fleet`.
+- CLI can start/stop/status/verify a canary fleet using `mosaic-factory`.
 - `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/633-comms-block-runbook.md

@@ -1,54 +0,0 @@
-# #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/fleet-observability-phase2.md

@@ -31,7 +31,7 @@ with a second agent on `dragon-lin`.
 ## 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`,
+  `mosaic-factory`: `_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`
@@ -56,7 +56,7 @@ with a second agent on `dragon-lin`.
   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.
+  mosaic-factory — 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

docs/scratchpads/fleet-standup-fixes.md

@@ -11,14 +11,14 @@
 ## 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).
+  `Environment=MOSAIC_TMUX_SOCKET=mosaic-factory` + `ExecStop ${…:-mosaic-factory}`; start-agent-session
+  defaulted `:-mosaic-factory`. All fixed → absent socket = '' = default tmux socket (no -L).
 - `socketArgs(name)` helper → `name ? ['-L', name] : []`; replaced all ~15 -L render sites in fleet.ts.
 - shellEnvValue('') now emits a **bare** `VAR=` (not `''`) — unambiguous empty in systemd EnvironmentFile
   (a quoted '' could become a literal socket named "''").
 - start-agent-session.sh: `_tmux` wrapper passes -L only when socket set; mosaic-agent@.service: dropped the
   socket default + conditional ExecStop. So spawn == observe == onboarding cheat-sheet.
-- CONTAINMENT: all 6 shipped presets set socket_name: mosaic-fleet explicitly → unaffected; only
+- CONTAINMENT: all 6 shipped presets set socket_name: mosaic-factory explicitly → unaffected; only
   socket-less rosters (the PoC) get default-socket behavior. DEFAULT_SOCKET_NAME exported for explicit use.
 
 ## Verification

docs/scratchpads/h1-heartbeat-readiness.md

@@ -1,66 +0,0 @@
-# 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

@@ -1,53 +0,0 @@
-# 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

@@ -1,70 +0,0 @@
-# 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

@@ -1,19 +0,0 @@
-# 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.

eslint.config.mjs

@@ -28,7 +28,6 @@ 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/vitest.config.ts

@@ -4,22 +4,5 @@ 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/fleet/README.md

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

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

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

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

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

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

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

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

@@ -1,7 +1,7 @@
 version: 1
 transport: tmux
 tmux:
-  socket_name: mosaic-fleet
+  socket_name: mosaic-factory
   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-fleet
+  socket_name: mosaic-factory
   holder_session: _holder
 defaults:
   working_directory: ~/src

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

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

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

@@ -1,38 +0,0 @@
-# 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

@@ -1,36 +0,0 @@
-# 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

@@ -1,38 +0,0 @@
-# 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

@@ -1,39 +0,0 @@
-# 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/merge-gate.md

@@ -1,42 +0,0 @@
-# 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

@@ -1,38 +0,0 @@
-# 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

@@ -1,40 +0,0 @@
-# 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

@@ -1,37 +0,0 @@
-# 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

@@ -1,38 +0,0 @@
-# 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

@@ -1,39 +0,0 @@
-# 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

@@ -1,37 +0,0 @@
-# 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

@@ -1,37 +0,0 @@
-# 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-fleet"
+          "default": "mosaic-factory"
         },
         "socketName": {
           "type": "string",
-          "default": "mosaic-fleet"
+          "default": "mosaic-factory"
         },
         "holder_session": {
           "type": "string",

packages/mosaic/framework/install.sh

@@ -25,9 +25,7 @@ INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 # User-created content in these paths survives rsync --delete.
 #
 # 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
+# fleet/roster.schema.json (synced normally). The user's own fleet files MUST
 # survive `mosaic update` (which runs this sync automatically): the active
 # roster (`fleet/roster.yaml` + any other `fleet/*.yaml`), per-agent env
 # (`fleet/agents/`), and heartbeat run dir (`fleet/run/`). Without these, an

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-fleet
+MOSAIC_TMUX_SOCKET=mosaic-factory
 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-fleet ls
+tmux -L mosaic-factory ls
 ```
 
-Do not use `tmux kill-server` without `-L mosaic-fleet`; this pattern is meant
+Do not use `tmux kill-server` without `-L mosaic-factory`; this pattern is meant
 to avoid disturbing the user's default tmux server.

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-fleet
+Environment=MOSAIC_TMUX_SOCKET=mosaic-factory
 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/fleet/start-agent-session.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 AGENT_NAME=${1:-${MOSAIC_AGENT_NAME:-}}
 # Absent socket ⇒ the LITERAL default tmux socket (no -L). The roster's
-# socket_name is honored when set; absent never silently becomes mosaic-fleet
+# socket_name is honored when set; absent never silently becomes mosaic-factory
 # (spawn stays consistent with the onboarding cheat-sheet + fleet ps observe).
 MOSAIC_TMUX_SOCKET=${MOSAIC_TMUX_SOCKET:-}
 MOSAIC_AGENT_RUNTIME=${MOSAIC_AGENT_RUNTIME:-pi}
@@ -122,85 +122,6 @@ fi
 
 mkdir -p "$MOSAIC_AGENT_WORKDIR"
 
-# ── 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"

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:-/tmp}/mosaic/agent-work}"
-    body_file=$(mktemp "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}/pr-merge-api-response.XXXXXX")
+    mkdir -p "${AGENT_WORK_ROOT:-/home/hermes/agent-work}"
+    body_file=$(mktemp "${AGENT_WORK_ROOT:-/home/hermes/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:-/tmp}/mosaic/agent-work}"
-            TEA_ERROR_FILE=$(mktemp "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}/pr-merge-tea-error.XXXXXX")
+            mkdir -p "${AGENT_WORK_ROOT:-/home/hermes/agent-work}"
+            TEA_ERROR_FILE=$(mktemp "${AGENT_WORK_ROOT:-/home/hermes/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:-/tmp}/mosaic/agent-work}"
+WORK_ROOT="${AGENT_WORK_ROOT:-/home/hermes/agent-work}"
 SANDBOX="$WORK_ROOT/pr-merge-empty-uid-test-$$"
 MOCK_BIN="$SANDBOX/bin"
 REPO_DIR="$SANDBOX/repo"

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

@@ -2,20 +2,12 @@
 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)
@@ -25,18 +17,15 @@ 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:
-      - corepack enable
-      - npm ci --ignore-scripts --prefer-offline
-    depends_on: []
+      - *install_deps
 
   security-audit:
     image: *node_image
     commands:
+      - *install_deps
       - npm audit --audit-level=high
     depends_on:
       - install
@@ -46,6 +35,7 @@ steps:
     environment:
       SKIP_ENV_VALIDATION: 'true'
     commands:
+      - *install_deps
       - npm run lint
     depends_on:
       - install
@@ -55,6 +45,7 @@ steps:
     environment:
       SKIP_ENV_VALIDATION: 'true'
     commands:
+      - *install_deps
       - npm run type-check
     depends_on:
       - install
@@ -64,6 +55,7 @@ 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
@@ -74,6 +66,7 @@ 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-fleet -s '=coder0' -m "message"
+agent-send.sh -L mosaic-factory -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-fleet ls
-agent-send.sh -L mosaic-fleet -s '=coder0' -m "status?"
-send-message.sh -L mosaic-fleet -t '=coder0' -m "raw pane message"
+tmux -L mosaic-factory ls
+agent-send.sh -L mosaic-factory -s '=coder0' -m "status?"
+send-message.sh -L mosaic-factory -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,10 +12,6 @@
 #   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
@@ -30,7 +26,6 @@
 #   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
@@ -41,61 +36,27 @@
 #                   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 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[@]}"}
+SENDER="$SELF_DIR/send-message.sh"
 
 DST_SESSION=""; SSH_TARGET=""; DST_HOST=""; MSG=""; FILE=""; SOCKET_NAME=""
-SRC_LABEL=""; RETRIES=2; VERBOSE=0; CLASS=""
-usage() { sed -n '2,/^set -uo pipefail/{/^set -uo pipefail/d;p}' "$0"; exit "${1:-3}"; }
+SRC_LABEL=""; RETRIES=2; VERBOSE=0
+usage() { sed -n '2,44p' "$0"; exit "${1:-3}"; }
 
-while getopts "L:s:H:n:m:f:S:r:C:vh" o; do
+while getopts "L:s:H:n:m:f:S:r: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
@@ -103,17 +64,6 @@ 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)
@@ -140,7 +90,7 @@ if [ -z "$DST_HOST" ]; then
   fi
 fi
 
-PREAMBLE="[${SRC_LABEL} -> ${DST_HOST}:${DST_SESSION}${CLASS_TOKEN}]"
+PREAMBLE="[${SRC_LABEL} -> ${DST_HOST}:${DST_SESSION}]"
 FULL="${PREAMBLE} ${MSG}"
 B64=$(printf '%s' "$FULL" | base64 -w0)
 

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

@@ -1,97 +0,0 @@
-#!/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.44",
+  "version": "0.0.40",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",

packages/mosaic/src/cli.ts

@@ -30,7 +30,6 @@ import {
   refreshActiveFleetUnits,
   readRosterAgentNames,
   buildRelaunchCommands,
-  checkFrameworkDrift,
   FRAMEWORK_RESEED_PACKAGE,
 } from './runtime/update-checker.js';
 import { runWizard } from './wizard.js';
@@ -419,48 +418,6 @@ program
     // 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 });
 
@@ -475,18 +432,6 @@ 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;
     }
 
@@ -511,17 +456,52 @@ program
     // 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).
+    // Only when the framework-bearing package itself updated.
     const mosaicUpdated = outdated.some(
       (r: { package: string }) => r.package === FRAMEWORK_RESEED_PACKAGE,
     );
-    const drift = checkFrameworkDrift();
-    if ((mosaicUpdated || drift.drifted) && opts.reseed !== false) {
-      reseedFramework(
+    if (mosaicUpdated && opts.reseed !== false) {
+      console.log(
         '\nRe-seeding framework files into ~/.config/mosaic (data-safe; keeps your edits)…',
       );
+      const reseed = runFrameworkReseed();
+      if (reseed.ok) {
+        console.log('✔ Framework re-seeded.');
+        // Propagate shipped systemd unit fixes to the ACTIVE units (re-seed only
+        // touches ~/.config/mosaic/systemd/user; systemd runs ~/.config/systemd/user).
+        const units = refreshActiveFleetUnits();
+        if (units.refreshed.length > 0) {
+          console.log(`✔ Refreshed ${units.refreshed.length} active systemd unit(s).`);
+        }
+        const agents = readRosterAgentNames();
+        if (agents.length > 0) {
+          if (opts.relaunch) {
+            console.log(
+              `\nRelaunching ${agents.length} fleet agent(s) to pick up the new runtime…`,
+            );
+            for (const restart of buildRelaunchCommands(agents)) {
+              try {
+                execSync(restart.join(' '), { stdio: 'inherit', timeout: 30_000 });
+              } catch {
+                console.error(`  ⚠ failed to restart agent — run: ${restart.join(' ')}`);
+              }
+            }
+            console.log('✔ Agents relaunched.');
+          } else {
+            console.log(
+              `\nℹ ${agents.length} fleet agent(s) are still running the previous runtime. ` +
+                'Restart them to activate the update:\n    mosaic update --relaunch   ' +
+                '(or: mosaic fleet restart <agent>)',
+            );
+          }
+        }
+      } else {
+        console.error(
+          `\n⚠ Framework re-seed skipped: ${reseed.reason ?? 'unknown'}.\n` +
+            '  Activate manually: bash "$(npm root -g)/@mosaicstack/mosaic/framework/install.sh" ' +
+            '(MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep)',
+        );
+      }
     }
   });
 

packages/mosaic/src/commands/fleet.spec.ts

@@ -19,20 +19,17 @@ import {
   buildSystemdShowCommand,
   buildTmuxListPanesCommand,
   buildTmuxListSessionsCommand,
-  classifyReadiness,
   classifySendResult,
   countOrchestrators,
   countEnhancers,
   detectDrift,
   enableFleetUnits,
   FLEET_PROFILES,
-  HEARTBEAT_IDLE_THRESHOLD_SECONDS,
   generateAgentEnv,
   getDefaultOperatorSourceLabel,
   getDefaultTenantAndHost,
   getRosterAgent,
   heartbeatPath,
-  idleThresholdSeconds,
   isSendAccepted,
   loadFleetRoster,
   mergeAgentEnv,
@@ -98,7 +95,6 @@ describe('registerFleetCommand', () => {
     expect(agent).toBeDefined();
     expect(agent!.options.map((option) => option.long)).toContain('--list');
     expect(agent!.commands.map((command) => command.name()).sort()).toEqual([
-      'comms-block',
       'reset',
       'roster',
       'send',
@@ -136,14 +132,14 @@ describe('fleet roster parsing', () => {
 
     const roster = await loadFleetRoster(rosterPath);
 
-    expect(roster.tmux.socketName).toBe(''); // absent ⇒ default socket (no -L), not mosaic-fleet
+    expect(roster.tmux.socketName).toBe(''); // absent ⇒ default socket (no -L), not mosaic-factory
     expect(roster.tmux.holderSession).toBe('_holder');
     expect(roster.agents).toHaveLength(1);
     expect(getRosterAgent(roster, 'canary-pi').runtime).toBe('pi');
   });
 
   it('socketArgs: named socket → -L <name>; empty → no -L (default socket)', () => {
-    expect(socketArgs('mosaic-fleet')).toEqual(['-L', 'mosaic-fleet']);
+    expect(socketArgs('mosaic-factory')).toEqual(['-L', 'mosaic-factory']);
     expect(socketArgs('')).toEqual([]);
   });
 
@@ -156,14 +152,14 @@ describe('fleet roster parsing', () => {
         'version: 1',
         'transport: tmux',
         'tmux:',
-        '  socket_name: mosaic-fleet',
+        '  socket_name: mosaic-factory',
         'agents:',
         '  - name: canary-pi',
         '    runtime: pi',
       ].join('\n'),
     );
     const roster = await loadFleetRoster(rosterPath);
-    expect(roster.tmux.socketName).toBe('mosaic-fleet');
+    expect(roster.tmux.socketName).toBe('mosaic-factory');
     expect(buildTmuxListSessionsCommand(roster.tmux.socketName)).toContain('-L');
   });
 
@@ -193,7 +189,7 @@ describe('fleet roster parsing', () => {
       JSON.stringify({
         version: 1,
         transport: 'tmux',
-        tmux: { socket_name: 'mosaic-fleet' },
+        tmux: { socket_name: 'mosaic-factory' },
         defaults: { working_directory: '/srv/mosaic' },
         agents: [{ name: 'coder0', runtime: 'codex', class: 'implementer' }],
       }),
@@ -206,7 +202,7 @@ describe('fleet roster parsing', () => {
         'MOSAIC_AGENT_RUNTIME=codex',
         'MOSAIC_AGENT_MODEL=',
         'MOSAIC_AGENT_WORKDIR=/srv/mosaic',
-        'MOSAIC_TMUX_SOCKET=mosaic-fleet',
+        'MOSAIC_TMUX_SOCKET=mosaic-factory',
         '',
       ].join('\n'),
     );
@@ -217,7 +213,7 @@ describe('fleet roster parsing', () => {
       'MOSAIC_AGENT_NAME=coder0',
       'MOSAIC_AGENT_RUNTIME=codex',
       'MOSAIC_AGENT_WORKDIR=/srv/new',
-      'MOSAIC_TMUX_SOCKET=mosaic-fleet',
+      'MOSAIC_TMUX_SOCKET=mosaic-factory',
       '',
     ].join('\n');
     const existing = [
@@ -235,7 +231,7 @@ describe('fleet roster parsing', () => {
         'MOSAIC_AGENT_NAME=coder0',
         'MOSAIC_AGENT_RUNTIME=codex',
         'MOSAIC_AGENT_WORKDIR=/srv/new',
-        'MOSAIC_TMUX_SOCKET=mosaic-fleet',
+        'MOSAIC_TMUX_SOCKET=mosaic-factory',
         'MOSAIC_AGENT_COMMAND=/home/jarvis/.config/mosaic/fleet/canary.sh',
         '# site note',
         '',
@@ -328,7 +324,7 @@ describe('fleet roster parsing', () => {
     const localCanary = await loadFleetRoster(join(examplesDir, 'local-canary.yaml'));
 
     expect(minimal.agents.map((agent) => agent.name)).toEqual(['canary-pi']);
-    expect(localCanary.tmux.socketName).toBe('mosaic-fleet');
+    expect(localCanary.tmux.socketName).toBe('mosaic-factory');
     expect(localCanary.agents.map((agent) => agent.name)).toEqual(['lead', 'coder0', 'reviewer0']);
     expect(localCanaryText).not.toMatch(/usc|ultron|secrev/i);
   });
@@ -353,11 +349,11 @@ describe('fleet command construction', () => {
   it('builds socket-scoped agent send commands', () => {
     const paths = resolveFleetPaths('/home/test/.config/mosaic');
     expect(
-      buildAgentSendCommand(paths, 'coder0', 'hello', 'mosaic-fleet', 'operator:mosaic-cli'),
+      buildAgentSendCommand(paths, 'coder0', 'hello', 'mosaic-factory', 'operator:mosaic-cli'),
     ).toEqual([
       '/home/test/.config/mosaic/tools/tmux/agent-send.sh',
       '-L',
-      'mosaic-fleet',
+      'mosaic-factory',
       '-S',
       'operator:mosaic-cli',
       '-s',
@@ -845,15 +841,15 @@ describe('fleet ps — command construction', () => {
   });
 
   it('builds exact tmux list-panes command with the correct format string', () => {
-    expect(buildTmuxListPanesCommand('canary-pi', 'mosaic-fleet')).toEqual([
+    expect(buildTmuxListPanesCommand('canary-pi', 'mosaic-factory')).toEqual([
       'tmux',
       '-L',
-      'mosaic-fleet',
+      'mosaic-factory',
       'list-panes',
       '-t',
       '=canary-pi:0.0',
       '-F',
-      '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity} #{window_activity} #{session_activity}',
+      '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity}',
     ]);
   });
 
@@ -936,125 +932,6 @@ describe('fleet ps — heartbeat parsing', () => {
   });
 });
 
-describe('fleet ps — readiness thresholds', () => {
-  const savedIdle = process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD;
-
-  afterEach(() => {
-    if (savedIdle === undefined) delete process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD;
-    else process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD = savedIdle;
-  });
-
-  it('uses the default activity threshold when env is unset', () => {
-    delete process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD;
-
-    expect(idleThresholdSeconds()).toBe(HEARTBEAT_IDLE_THRESHOLD_SECONDS);
-  });
-
-  it('honors a positive integer activity threshold from env', () => {
-    process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD = '120';
-
-    expect(idleThresholdSeconds()).toBe(120);
-  });
-
-  it('falls back to the default for invalid activity thresholds', () => {
-    process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD = '0';
-
-    expect(idleThresholdSeconds()).toBe(HEARTBEAT_IDLE_THRESHOLD_SECONDS);
-  });
-});
-
-describe('fleet ps — readiness classification', () => {
-  const thresholds = { idleThresholdSeconds: 300 };
-
-  it('reports dead when the pane is not alive', () => {
-    expect(
-      classifyReadiness(
-        { paneAlive: false, hbHealth: 'healthy', hbStatus: 'busy', idleSeconds: 0 },
-        thresholds,
-      ),
-    ).toBe('dead');
-  });
-
-  it('reports unknown when heartbeat health is unknown', () => {
-    expect(
-      classifyReadiness(
-        { paneAlive: true, hbHealth: 'unknown', hbStatus: null, idleSeconds: 0 },
-        thresholds,
-      ),
-    ).toBe('unknown');
-  });
-
-  it('reports stale when heartbeat health is stale', () => {
-    expect(
-      classifyReadiness(
-        { paneAlive: true, hbHealth: 'stale', hbStatus: 'busy', idleSeconds: 1_000 },
-        thresholds,
-      ),
-    ).toBe('stale');
-  });
-
-  it('reports working when heartbeat status is busy, even after the activity threshold', () => {
-    expect(
-      classifyReadiness(
-        { paneAlive: true, hbHealth: 'healthy', hbStatus: 'busy', idleSeconds: 2_000 },
-        thresholds,
-      ),
-    ).toBe('working');
-  });
-
-  it('reports working when pane idle seconds are null', () => {
-    expect(
-      classifyReadiness(
-        { paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok', idleSeconds: null },
-        thresholds,
-      ),
-    ).toBe('working');
-  });
-
-  it('reports working when pane idle seconds are undefined', () => {
-    expect(
-      classifyReadiness({ paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok' }, thresholds),
-    ).toBe('working');
-  });
-
-  it('reports working when pane idle seconds are non-finite', () => {
-    expect(
-      classifyReadiness(
-        { paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok', idleSeconds: Number.NaN },
-        thresholds,
-      ),
-    ).toBe('working');
-  });
-
-  it('reports available at the activity threshold boundary', () => {
-    expect(
-      classifyReadiness(
-        { paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok', idleSeconds: 300 },
-        thresholds,
-      ),
-    ).toBe('available');
-  });
-
-  it('reports working below the activity threshold', () => {
-    expect(
-      classifyReadiness(
-        { paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok', idleSeconds: 299 },
-        thresholds,
-      ),
-    ).toBe('working');
-  });
-
-  it('reports very long idle as available, not stuck', () => {
-    const readiness = classifyReadiness(
-      { paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok', idleSeconds: 100_000 },
-      thresholds,
-    );
-
-    expect(readiness).toBe('available');
-    expect(readiness).not.toBe('stuck');
-  });
-});
-
 describe('fleet ps — systemd show parsing', () => {
   it('parses ActiveState, SubState, UnitFileState from systemctl show output', () => {
     const output = 'ActiveState=active\nSubState=running\nUnitFileState=enabled\n';
@@ -1075,11 +952,9 @@ describe('fleet ps — systemd show parsing', () => {
 describe('fleet ps — tmux list-panes parsing', () => {
   const NOW_MS = 1_700_000_000_000;
 
-  it('uses pane_activity when present', () => {
-    const paneActivityEpoch = Math.floor((NOW_MS - 30_000) / 1000); // 30s ago
-    const windowActivityEpoch = Math.floor((NOW_MS - 60_000) / 1000); // 60s ago
-    const sessionActivityEpoch = Math.floor((NOW_MS - 90_000) / 1000); // 90s ago
-    const output = `12345 claude 0 ${paneActivityEpoch} ${windowActivityEpoch} ${sessionActivityEpoch}\n`;
+  it('parses alive pane with pid, command, and idle time', () => {
+    const activityEpoch = Math.floor((NOW_MS - 30_000) / 1000); // 30s ago
+    const output = `12345 claude 0 ${activityEpoch}\n`;
     const result = parseTmuxListPanes(output, NOW_MS);
     expect(result.pid).toBe(12345);
     expect(result.command).toBe('claude');
@@ -1087,45 +962,8 @@ describe('fleet ps — tmux list-panes parsing', () => {
     expect(result.idleSeconds).toBe(30);
   });
 
-  it('uses window_activity when pane_activity is empty', () => {
-    const windowActivityEpoch = Math.floor((NOW_MS - 45_000) / 1000); // 45s ago
-    const sessionActivityEpoch = Math.floor((NOW_MS - 90_000) / 1000); // 90s ago
-    const output = `12345 node 0  ${windowActivityEpoch} ${sessionActivityEpoch}\n`;
-    expect(output).toContain('0  '); // empty pane_activity preserves index alignment
-    const result = parseTmuxListPanes(output, NOW_MS);
-    expect(result.pid).toBe(12345);
-    expect(result.command).toBe('node');
-    expect(result.dead).toBe(false);
-    expect(result.idleSeconds).toBe(45);
-  });
-
-  it('uses session_activity when pane_activity and window_activity are empty', () => {
-    const sessionActivityEpoch = Math.floor((NOW_MS - 75_000) / 1000); // 75s ago
-    const output = `12345 node 0   ${sessionActivityEpoch}\n`;
-    const result = parseTmuxListPanes(output, NOW_MS);
-    expect(result.idleSeconds).toBe(75);
-  });
-
-  it('reports null idleSeconds when all activity sources are empty', () => {
-    const output = '12345 node 0   \n';
-    const result = parseTmuxListPanes(output, NOW_MS);
-    expect(result.idleSeconds).toBeNull();
-  });
-
-  it('computes exact idle seconds from now minus epoch seconds', () => {
-    const activityEpoch = 1_699_999_877;
-    const result = parseTmuxListPanes(`12345 claude 0 ${activityEpoch} 0 0\n`, NOW_MS);
-    expect(result.idleSeconds).toBe(123);
-  });
-
-  it('clamps future activity epochs to 0 idle seconds', () => {
-    const futureActivityEpoch = Math.floor((NOW_MS + 30_000) / 1000);
-    const result = parseTmuxListPanes(`12345 claude 0 ${futureActivityEpoch} 0 0\n`, NOW_MS);
-    expect(result.idleSeconds).toBe(0);
-  });
-
   it('reports dead pane when pane_dead=1', () => {
-    const output = `0 bash 1 0 0 0\n`;
+    const output = `0 bash 1 0\n`;
     const result = parseTmuxListPanes(output, NOW_MS);
     expect(result.dead).toBe(true);
   });
@@ -1329,7 +1167,7 @@ describe('fleet install — auto-enable units for boot-survival', () => {
     const minimalRoster: FleetRoster = {
       version: 1,
       transport: 'tmux',
-      tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
+      tmux: { socketName: 'mosaic-factory', holderSession: '_holder' },
       defaults: { workingDirectory: '~/src' },
       runtimes: { codex: { resetCommand: '/clear' } },
       agents: [{ name: 'coder0', runtime: 'codex', className: 'worker' }],
@@ -1351,7 +1189,7 @@ describe('fleet install — auto-enable units for boot-survival', () => {
     const minimalRoster: FleetRoster = {
       version: 1,
       transport: 'tmux',
-      tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
+      tmux: { socketName: 'mosaic-factory', holderSession: '_holder' },
       defaults: { workingDirectory: '~/src' },
       runtimes: { codex: { resetCommand: '/clear' } },
       agents: [{ name: 'coder0', runtime: 'codex', className: 'worker' }],
@@ -1378,7 +1216,7 @@ describe('fleet install — auto-enable units for boot-survival', () => {
     const minimalRoster: FleetRoster = {
       version: 1,
       transport: 'tmux',
-      tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
+      tmux: { socketName: 'mosaic-factory', holderSession: '_holder' },
       defaults: { workingDirectory: '~/src' },
       runtimes: { codex: { resetCommand: '/clear' } },
       agents: [{ name: 'coder0', runtime: 'codex', className: 'worker' }],
@@ -1485,9 +1323,8 @@ describe('fleet ps — JSON output shape (FR-6)', () => {
     // boot-enable warning: active + disabled
     expect(row.bootEnableWarning).toBe(true);
 
-    // heartbeat missing → unknown readiness preserves existing display semantics
+    // heartbeat missing → unknown
     expect(row.heartbeat.health).toBe('unknown');
-    expect(row.readiness).toBe('unknown');
 
     expect(row.name).toBe('canary-pi');
     expect(row.runtime).toBe('pi');
@@ -1549,94 +1386,12 @@ describe('fleet ps — command sequences issued', () => {
   });
 });
 
-describe('fleet ps — readiness table output', () => {
-  it('renders available in HB column without idle/stuck alarm flags', async () => {
-    const home = await mkdtemp(join(tmpdir(), 'mosaic-fleet-'));
-    const rosterPath = join(home, 'fleet', 'roster.yaml');
-    const runDir = join(home, 'fleet', 'run');
-    await mkdir(runDir, { recursive: true });
-    await writeFile(
-      rosterPath,
-      [
-        'version: 1',
-        'transport: tmux',
-        'agents:',
-        '  - name: working-agent',
-        '    runtime: pi',
-        '  - name: available-agent',
-        '    runtime: pi',
-      ].join('\n'),
-    );
-
-    const nowMs = 1_700_000_000_000;
-    const workingActivityEpoch = Math.floor((nowMs - 2_000) / 1000);
-    const availableActivityEpoch = Math.floor((nowMs - 40_000) / 1000);
-    const hbTs = new Date(nowMs - 1_000).toISOString();
-    await writeFile(join(runDir, 'working-agent.hb'), `ts=${hbTs}\npid=111\nstatus=ok\n`);
-    await writeFile(join(runDir, 'available-agent.hb'), `ts=${hbTs}\npid=222\nstatus=ok\n`);
-
-    const savedIdle = process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD;
-    process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD = '5';
-
-    const dateNow = vi.spyOn(Date, 'now').mockReturnValue(nowMs);
-    const runner: CommandRunner = async (command, args) => {
-      const full = [command, ...args].join(' ');
-      if (full.includes('list-sessions')) {
-        return { stdout: 'working-agent\navailable-agent\n', stderr: '', exitCode: 0 };
-      }
-      if (full.includes('=working-agent:0.0')) {
-        return { stdout: `111 pi 0 ${workingActivityEpoch}\n`, stderr: '', exitCode: 0 };
-      }
-      if (full.includes('=available-agent:0.0')) {
-        return { stdout: `222 pi 0 ${availableActivityEpoch}\n`, stderr: '', exitCode: 0 };
-      }
-      if (full.includes('systemctl') && full.includes('show')) {
-        return {
-          stdout: 'ActiveState=active\nSubState=running\nUnitFileState=enabled\n',
-          stderr: '',
-          exitCode: 0,
-        };
-      }
-      return { stdout: '', stderr: '', exitCode: 0 };
-    };
-
-    const lines: string[] = [];
-    const origLog = console.log;
-    console.log = (msg: string) => {
-      lines.push(msg);
-    };
-
-    const program = new Command();
-    program.exitOverride();
-    registerFleetCommand(program, { runner, mosaicHome: home });
-
-    try {
-      await program.parseAsync(['node', 'mosaic', 'fleet', 'ps']);
-    } finally {
-      console.log = origLog;
-      dateNow.mockRestore();
-      if (savedIdle === undefined) delete process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD;
-      else process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD = savedIdle;
-      await rm(home, { recursive: true, force: true });
-    }
-
-    const workingLine = lines.find((line) => line.includes('working-agent'));
-    const availableLine = lines.find((line) => line.includes('available-agent'));
-    expect(workingLine).toBeDefined();
-    expect(workingLine).toContain('1s/working');
-    expect(availableLine).toBeDefined();
-    expect(availableLine).toContain('1s/available');
-    expect(availableLine).not.toMatch(/\bIDLE\b/);
-    expect(availableLine).not.toMatch(/\bSTUCK\b/);
-  });
-});
-
 describe('buildTmuxListSessionsCommand', () => {
   it('builds exact list-sessions command with session_name format', () => {
-    expect(buildTmuxListSessionsCommand('mosaic-fleet')).toEqual([
+    expect(buildTmuxListSessionsCommand('mosaic-factory')).toEqual([
       'tmux',
       '-L',
-      'mosaic-fleet',
+      'mosaic-factory',
       'list-sessions',
       '-F',
       '#{session_name}',
@@ -1758,7 +1513,6 @@ describe('fleet ps — unmanaged socket sessions', () => {
 
     // driftFlag must be false for unmanaged (no roster runtime to compare)
     expect(unmanagedRow.driftFlag).toBe(false);
-    expect(unmanagedRow.readiness).toBe('unknown');
   });
 
   it('shows UNMANAGED flag in table output for unmanaged sessions', async () => {
@@ -1888,11 +1642,11 @@ describe('fleet ps — unmanaged socket sessions', () => {
 describe('agent watch', () => {
   it('builds exact grouped-viewer creation command', () => {
     expect(
-      buildAgentWatchCreateViewerCommand('canary-pi', 'canary-pi-watch-123', 'mosaic-fleet'),
+      buildAgentWatchCreateViewerCommand('canary-pi', 'canary-pi-watch-123', 'mosaic-factory'),
     ).toEqual([
       'tmux',
       '-L',
-      'mosaic-fleet',
+      'mosaic-factory',
       'new-session',
       '-d',
       '-t',
@@ -1903,10 +1657,10 @@ describe('agent watch', () => {
   });
 
   it('builds exact viewer attach command (read-only)', () => {
-    expect(buildAgentWatchAttachCommand('canary-pi-watch-123', 'mosaic-fleet')).toEqual([
+    expect(buildAgentWatchAttachCommand('canary-pi-watch-123', 'mosaic-factory')).toEqual([
       'tmux',
       '-L',
-      'mosaic-fleet',
+      'mosaic-factory',
       'attach',
       '-r',
       '-t',
@@ -1915,10 +1669,10 @@ describe('agent watch', () => {
   });
 
   it('builds exact viewer kill command', () => {
-    expect(buildAgentWatchKillViewerCommand('canary-pi-watch-123', 'mosaic-fleet')).toEqual([
+    expect(buildAgentWatchKillViewerCommand('canary-pi-watch-123', 'mosaic-factory')).toEqual([
       'tmux',
       '-L',
-      'mosaic-fleet',
+      'mosaic-factory',
       'kill-session',
       '-t',
       'canary-pi-watch-123',
@@ -2015,10 +1769,10 @@ describe('agent watch', () => {
 
 describe('agent send --verify', () => {
   it('builds exact verify capture-pane command', () => {
-    expect(buildAgentVerifyAcceptedCommand('canary-pi', 'mosaic-fleet', 5)).toEqual([
+    expect(buildAgentVerifyAcceptedCommand('canary-pi', 'mosaic-factory', 5)).toEqual([
       'tmux',
       '-L',
-      'mosaic-fleet',
+      'mosaic-factory',
       'capture-pane',
       '-t',
       '=canary-pi:0.0',
@@ -2730,7 +2484,7 @@ describe('fleet add/remove — pure helpers', () => {
   const baseRoster: FleetRoster = {
     version: 1,
     transport: 'tmux',
-    tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
+    tmux: { socketName: 'mosaic-factory', holderSession: '_holder' },
     defaults: { workingDirectory: '~/src' },
     runtimes: { codex: { resetCommand: '/clear' } },
     agents: [
@@ -2856,7 +2610,7 @@ describe('fleet add/remove — pure helpers', () => {
       await writeFile(rosterPath, yaml);
       const loaded = await loadFleetRoster(rosterPath);
       expect(loaded.agents.map((a) => a.name)).toEqual(['orchestrator', 'coder0']);
-      expect(loaded.tmux.socketName).toBe('mosaic-fleet');
+      expect(loaded.tmux.socketName).toBe('mosaic-factory');
       expect(loaded.agents[0]!.className).toBe('orchestrator');
     } finally {
       await rm(dir, { recursive: true, force: true });

packages/mosaic/src/commands/fleet.ts

@@ -7,7 +7,6 @@ import { spawn } from 'node:child_process';
 import * as readline from 'node:readline';
 import type { Command } from 'commander';
 import YAML from 'yaml';
-import { resolveCommsBlock } from '../fleet/comms-onboarding.js';
 
 /**
  * A function that spawns a command with inherited stdio (TTY passthrough).
@@ -123,7 +122,7 @@ type FleetServiceAction = 'start' | 'stop' | 'restart' | 'status';
  * rosters/callers that explicitly want isolation; it is NO LONGER the silent
  * fallback for a socket-less roster (that now resolves to the default socket).
  */
-export const DEFAULT_SOCKET_NAME = 'mosaic-fleet';
+export const DEFAULT_SOCKET_NAME = 'mosaic-factory';
 const DEFAULT_HOLDER_SESSION = '_holder';
 const DEFAULT_WORKING_DIRECTORY = '~/src';
 
@@ -131,7 +130,7 @@ const DEFAULT_WORKING_DIRECTORY = '~/src';
  * tmux `-L` args for a socket name. An empty/absent socket ⇒ the LITERAL default
  * tmux socket (no `-L`), so spawn, observe (`fleet ps`/watch), and the onboarding
  * cheat-sheet all agree. A named socket ⇒ `-L <name>`. `DEFAULT_SOCKET_NAME`
- * remains a constant for callers that explicitly want mosaic-fleet; it is no
+ * remains a constant for callers that explicitly want mosaic-factory; it is no
  * longer the silent fallback for a socket-less roster.
  */
 export function socketArgs(socketName: string): string[] {
@@ -394,7 +393,6 @@ export function buildAgentTailCommand(agentName: string, lines: number, socketNa
 // ---------------------------------------------------------------------------
 
 export const HEARTBEAT_INTERVAL_MS = 15_000;
-export const HEARTBEAT_IDLE_THRESHOLD_SECONDS = 300;
 
 /**
  * Heartbeat interval in ms, honoring MOSAIC_HEARTBEAT_INTERVAL (seconds) so the
@@ -405,57 +403,8 @@ export function heartbeatIntervalMs(): number {
   const sec = Number.parseInt(process.env.MOSAIC_HEARTBEAT_INTERVAL ?? '', 10);
   return Number.isFinite(sec) && sec > 0 ? sec * 1000 : HEARTBEAT_INTERVAL_MS;
 }
-
-/** Activity threshold in seconds, honoring MOSAIC_HEARTBEAT_IDLE_THRESHOLD. */
-export function idleThresholdSeconds(): number {
-  const sec = Number.parseInt(process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD ?? '', 10);
-  return Number.isFinite(sec) && sec > 0 ? sec : HEARTBEAT_IDLE_THRESHOLD_SECONDS;
-}
 export const HEARTBEAT_HEALTHY_MULTIPLIER = 3;
 
-export type ReadinessState = 'working' | 'available' | 'stuck' | 'stale' | 'dead' | 'unknown';
-
-export interface ReadinessSignals {
-  paneAlive: boolean;
-  hbHealth: 'healthy' | 'stale' | 'unknown';
-  hbStatus: 'ok' | 'busy' | null;
-  idleSeconds: number | null;
-}
-
-export interface ReadinessThresholds {
-  idleThresholdSeconds: number;
-}
-
-/**
- * Classify whether an agent is progressing based on already-parsed heartbeat/tmux signals.
- * Best-effort and runtime-agnostic: it never probes, never throws, and preserves existing
- * unknown/stale behavior when heartbeat data is absent or old.
- */
-export function classifyReadiness(
-  signals: Partial<ReadinessSignals> | null | undefined,
-  thresholds: Partial<ReadinessThresholds> | null | undefined = {},
-): ReadinessState {
-  try {
-    if (signals?.paneAlive !== true) return 'dead';
-    if (signals.hbHealth === 'unknown' || signals.hbHealth === undefined) return 'unknown';
-    if (signals.hbHealth === 'stale') return 'stale';
-    if (signals.hbStatus === 'busy') return 'working';
-    if (signals.idleSeconds === null || signals.idleSeconds === undefined) return 'working';
-
-    const idleSeconds = Number.isFinite(signals.idleSeconds) ? signals.idleSeconds : null;
-    if (idleSeconds === null) return 'working';
-
-    const idleThreshold = Number.isFinite(thresholds?.idleThresholdSeconds)
-      ? Number(thresholds?.idleThresholdSeconds)
-      : idleThresholdSeconds();
-    // Follow-up: stuck pending per-agent assignment awareness: assigned task + idle past threshold => stuck.
-    if (idleSeconds >= idleThreshold) return 'available';
-    return 'working';
-  } catch {
-    return 'unknown';
-  }
-}
-
 export interface HeartbeatInfo {
   ts: Date | null;
   pid: number | null;
@@ -479,7 +428,6 @@ export interface AgentPsRow {
   paneCommand: string | null;
   idleSeconds: number | null;
   heartbeat: HeartbeatInfo;
-  readiness: ReadinessState;
   /** roster runtime !== actual pane command */
   driftFlag: boolean;
   /** active but UnitFileState=disabled */
@@ -512,7 +460,7 @@ export function buildSystemdShowCommand(agentName: string): string[] {
 
 /**
  * Returns the tmux list-panes command for an agent pane.
- * Format: `#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity} #{window_activity} #{session_activity}`
+ * Format: `#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity}`
  */
 export function buildTmuxListPanesCommand(agentName: string, socketName = ''): string[] {
   return [
@@ -522,7 +470,7 @@ export function buildTmuxListPanesCommand(agentName: string, socketName = ''): s
     '-t',
     `=${agentName}:0.0`,
     '-F',
-    '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity} #{window_activity} #{session_activity}',
+    '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity}',
   ];
 }
 
@@ -622,8 +570,8 @@ export function parseSystemdShow(output: string): {
 }
 
 /**
- * Parse the output of `tmux list-panes -F '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity} #{window_activity} #{session_activity}'`
- * Activity fields are Unix epoch timestamps (seconds), ordered most precise to coarsest.
+ * Parse the output of `tmux list-panes -F '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity}'`
+ * pane_activity is a Unix epoch timestamp (seconds).
  */
 export function parseTmuxListPanes(
   output: string,
@@ -633,17 +581,15 @@ export function parseTmuxListPanes(
   if (!line) {
     return { pid: null, command: null, dead: true, idleSeconds: null };
   }
-  // format: <pid> <command> <dead(0|1)> <pane_activity> <window_activity> <session_activity>
+  // format: <pid> <command> <dead(0|1)> <activity_epoch>
   const parts = line.split(' ');
   const pid = parts[0] ? (Number.isFinite(Number(parts[0])) ? Number(parts[0]) : null) : null;
   const command = parts[1] ?? null;
   const dead = parts[2] === '1';
-  const activityEpoch = parts
-    .slice(3, 6)
-    .map((part) => (part ? Number(part) : NaN))
-    .find((epoch) => Number.isFinite(epoch) && epoch > 0);
-  const idleSeconds = activityEpoch
-    ? Math.max(0, Math.floor((nowMs - activityEpoch * 1000) / 1000))
+  const activityEpoch = parts[3] ? Number(parts[3]) : NaN;
+  const idleSeconds =
+    Number.isFinite(activityEpoch) && activityEpoch > 0
+      ? Math.floor((nowMs - activityEpoch * 1000) / 1000)
       : null;
   return { pid, command, dead, idleSeconds };
 }
@@ -1075,9 +1021,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
       const nowMs = Date.now();
 
       const rows: AgentPsRow[] = [];
-      const readinessThresholds = {
-        idleThresholdSeconds: idleThresholdSeconds(),
-      };
 
       // Build the set of roster agent names for quick lookup when filtering socket sessions.
       const rosterAgentNames = new Set(roster.agents.map((a) => a.name));
@@ -1108,17 +1051,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
         const bootEnableWarning =
           sysInfo.ActiveState === 'active' && sysInfo.UnitFileState === 'disabled';
 
-        const paneAlive = !paneInfo.dead;
-        const readiness = classifyReadiness(
-          {
-            paneAlive,
-            hbHealth: hb.health,
-            hbStatus: hb.status,
-            idleSeconds: paneInfo.idleSeconds,
-          },
-          readinessThresholds,
-        );
-
         rows.push({
           name: agent.name,
           tenant_id,
@@ -1126,12 +1058,11 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
           runtime: agent.runtime,
           systemdActive: sysInfo.ActiveState,
           systemdEnabled: sysInfo.UnitFileState,
-          paneAlive,
+          paneAlive: !paneInfo.dead,
           panePid: paneInfo.pid,
           paneCommand: paneInfo.command,
           idleSeconds: paneInfo.idleSeconds,
           heartbeat: hb,
-          readiness,
           driftFlag,
           bootEnableWarning,
           managed: true,
@@ -1178,17 +1109,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
             const bootEnableWarning =
               sysInfo.ActiveState === 'active' && sysInfo.UnitFileState === 'disabled';
 
-            const paneAlive = !paneInfo.dead;
-            const readiness = classifyReadiness(
-              {
-                paneAlive,
-                hbHealth: hb.health,
-                hbStatus: hb.status,
-                idleSeconds: paneInfo.idleSeconds,
-              },
-              readinessThresholds,
-            );
-
             rows.push({
               name: sessionName,
               tenant_id,
@@ -1197,12 +1117,11 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
               runtime: 'unknown',
               systemdActive: sysInfo.ActiveState,
               systemdEnabled: sysInfo.UnitFileState,
-              paneAlive,
+              paneAlive: !paneInfo.dead,
               panePid: paneInfo.pid,
               paneCommand: paneInfo.command,
               idleSeconds: paneInfo.idleSeconds,
               heartbeat: hb,
-              readiness,
               // No roster runtime to compare — drift is not meaningful for unmanaged sessions
               driftFlag: false,
               bootEnableWarning,
@@ -1244,7 +1163,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
         const idle = row.idleSeconds !== null ? `${row.idleSeconds}s` : '-';
         const hbAge =
           row.heartbeat.ageMs !== null
-            ? `${Math.round(row.heartbeat.ageMs / 1000)}s/${row.readiness}`
+            ? `${Math.round(row.heartbeat.ageMs / 1000)}s/${row.heartbeat.health}`
             : `unknown`;
         const model = row.heartbeat.model ?? '-';
         const flags: string[] = [];
@@ -1440,23 +1359,6 @@ export function registerFleetAgentCommands(
       }
     });
 
-  agentCommand
-    .command('comms-block <role>')
-    .description(
-      "Print the Fleet Comms cheat-sheet for a roster role (preview a peer's peer-reach view)",
-    )
-    .option('--host <host>', 'Override the fleet host (preview a cross-host peer view)')
-    .action((role: string, opts: { host?: string }) => {
-      const mosaicHome = resolveMosaicHomeFromCommand(agentCommand, deps.mosaicHome);
-      const res = resolveCommsBlock(mosaicHome, role, opts.host);
-      if (!res.ok) {
-        console.error(`[mosaic] comms-block: ${res.error}`);
-        process.exitCode = 1;
-        return;
-      }
-      console.log(res.output);
-    });
-
   agentCommand
     .command('status [agent]')
     .description('Show tmux status for the local fleet or one agent')
@@ -1787,7 +1689,7 @@ function normalizeRoster(raw: RawFleetRoster): FleetRoster {
     transport: 'tmux',
     tmux: {
       // Absent socket_name ⇒ '' (the literal default tmux socket, no -L) — NOT
-      // mosaic-fleet. Shipped presets set socket_name explicitly, so they are
+      // mosaic-factory. Shipped presets set socket_name explicitly, so they are
       // unaffected; only socket-less rosters get default-socket behavior.
       socketName: stringValue(
         raw.tmux?.socket_name ?? raw.tmux?.socketName,

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

@@ -7,7 +7,6 @@ import {
   buildFleetCommsBlock,
   renderPeerReach,
   readFleetCommsBlock,
-  resolveCommsBlock,
   type CommsPeer,
 } from './comms-onboarding.js';
 
@@ -49,9 +48,9 @@ describe('parseRosterAgents', () => {
 
   it('parses an optional per-agent socket', () => {
     const peers = parseRosterAgents(
-      ['agents:', '  - name: a', '    class: worker', '    socket: mosaic-fleet'].join('\n'),
+      ['agents:', '  - name: a', '    class: worker', '    socket: mosaic-factory'].join('\n'),
     );
-    expect(peers[0]).toMatchObject({ name: 'a', socket: 'mosaic-fleet' });
+    expect(peers[0]).toMatchObject({ name: 'a', socket: 'mosaic-factory' });
   });
 
   it('stops at the next top-level key', () => {
@@ -100,9 +99,9 @@ describe('renderPeerReach — same-host vs cross-host', () => {
   });
 
   it('emits -L <socket> for a named socket', () => {
-    const peer: CommsPeer = { name: 'coder0', className: 'implementer', socket: 'mosaic-fleet' };
+    const peer: CommsPeer = { name: 'coder0', className: 'implementer', socket: 'mosaic-factory' };
     expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
-      `${send} -L mosaic-fleet -s coder0 -m "…"`,
+      `${send} -L mosaic-factory -s coder0 -m "…"`,
     );
   });
 
@@ -112,10 +111,10 @@ describe('renderPeerReach — same-host vs cross-host', () => {
       className: 'implementer',
       host: '10.1.10.37',
       ssh: 'jwoltje@10.1.10.37',
-      socket: 'mosaic-fleet',
+      socket: 'mosaic-factory',
     };
     expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
-      `${send} -L mosaic-fleet -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`,
+      `${send} -L mosaic-factory -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`,
     );
   });
 });
@@ -186,53 +185,3 @@ describe('readFleetCommsBlock — situational (the context a spawned agent gets)
     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

@@ -179,48 +179,5 @@ export function readFleetCommsBlock(
   });
 }
 
-/** 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/runtime/update-checker.reseed.spec.ts

@@ -8,9 +8,6 @@ import {
   readRosterAgentNames,
   runFrameworkReseed,
   refreshActiveFleetUnits,
-  readInstalledFrameworkVersion,
-  readBundledFrameworkVersion,
-  checkFrameworkDrift,
 } from './update-checker.js';
 import { existsSync, readFileSync } from 'node:fs';
 
@@ -126,73 +123,3 @@ describe('refreshActiveFleetUnits', () => {
     expect(existsSync(join(configHome, 'systemd', 'user', 'mosaic-agent@.service'))).toBe(false);
   });
 });
-
-/**
- * #642: re-seed when the on-disk framework is older than the bundled one even
- * if no package is reported outdated (CLI upgraded outside `mosaic update`).
- */
-describe('framework drift detection', () => {
-  let home: string; // stand-in for ~/.config/mosaic
-  let fw: string; // stand-in for the bundled framework root
-
-  beforeEach(() => {
-    const root = mkdtempSync(join(tmpdir(), 'mosaic-drift-'));
-    home = join(root, 'mosaic');
-    fw = join(root, 'framework');
-    mkdirSync(home, { recursive: true });
-    mkdirSync(fw, { recursive: true });
-  });
-  afterEach(() => {
-    rmSync(join(home, '..'), { recursive: true, force: true });
-  });
-
-  const writeInstalled = (v: string) => writeFileSync(join(home, '.framework-version'), v);
-  const writeBundled = (v: string) =>
-    writeFileSync(join(fw, 'install.sh'), `#!/usr/bin/env bash\nFRAMEWORK_VERSION=${v}\n`);
-
-  describe('readInstalledFrameworkVersion', () => {
-    it('returns undefined when the version file is absent', () => {
-      expect(readInstalledFrameworkVersion(home)).toBeUndefined();
-    });
-    it('parses the integer (tolerating surrounding whitespace)', () => {
-      writeInstalled('  3\n');
-      expect(readInstalledFrameworkVersion(home)).toBe(3);
-    });
-    it('returns undefined for non-numeric content', () => {
-      writeInstalled('not-a-number\n');
-      expect(readInstalledFrameworkVersion(home)).toBeUndefined();
-    });
-  });
-
-  describe('readBundledFrameworkVersion', () => {
-    it('returns undefined when install.sh is absent', () => {
-      expect(readBundledFrameworkVersion(fw)).toBeUndefined();
-    });
-    it('parses FRAMEWORK_VERSION=<n> from install.sh', () => {
-      writeBundled('4');
-      expect(readBundledFrameworkVersion(fw)).toBe(4);
-    });
-  });
-
-  describe('checkFrameworkDrift', () => {
-    it('reports drift when on-disk is older than bundled', () => {
-      writeInstalled('3');
-      writeBundled('4');
-      expect(checkFrameworkDrift(home, fw)).toEqual({ drifted: true, installed: 3, bundled: 4 });
-    });
-    it('no drift when versions match', () => {
-      writeInstalled('4');
-      writeBundled('4');
-      expect(checkFrameworkDrift(home, fw)).toMatchObject({ drifted: false });
-    });
-    it('no drift when on-disk is newer than bundled', () => {
-      writeInstalled('5');
-      writeBundled('4');
-      expect(checkFrameworkDrift(home, fw)).toMatchObject({ drifted: false });
-    });
-    it('no drift (conservative) when a version cannot be read', () => {
-      writeBundled('4'); // installed version file missing
-      expect(checkFrameworkDrift(home, fw)).toMatchObject({ drifted: false, bundled: 4 });
-    });
-  });
-});

packages/mosaic/src/runtime/update-checker.ts

@@ -521,75 +521,6 @@ export function runFrameworkReseed(
   }
 }
 
-// ─── Framework drift detection (#642) ────────────────────────────────────────
-//
-// `mosaic update` only re-seeds the framework when the @mosaicstack/mosaic
-// package itself is upgraded *within that command*. When the CLI is upgraded
-// some OTHER way — a direct `npm i -g @mosaicstack/mosaic`, or an upgrade run
-// where only sibling packages were outdated — the framework files in
-// ~/.config/mosaic stay stale and shipped launcher/runtime fixes never
-// activate. Comparing the on-disk framework schema version against the version
-// bundled in the installed package detects exactly that situation.
-
-/** Read the framework schema version recorded on disk (~/.config/mosaic/.framework-version). */
-export function readInstalledFrameworkVersion(
-  mosaicHome = join(homedir(), '.config', 'mosaic'),
-): number | undefined {
-  const vf = join(mosaicHome, '.framework-version');
-  if (!existsSync(vf)) return undefined;
-  try {
-    const n = parseInt(readFileSync(vf, 'utf-8').trim(), 10);
-    return Number.isFinite(n) ? n : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Read the framework schema version shipped in the installed package by parsing
- * `FRAMEWORK_VERSION=<n>` out of the bundled install.sh (the authoritative
- * source the installer writes to .framework-version).
- */
-export function readBundledFrameworkVersion(
-  frameworkRoot = resolveBundledFrameworkRoot(),
-): number | undefined {
-  const installer = join(frameworkRoot, 'install.sh');
-  if (!existsSync(installer)) return undefined;
-  try {
-    const m = readFileSync(installer, 'utf-8').match(/^\s*FRAMEWORK_VERSION=(\d+)/m);
-    const raw = m?.[1];
-    if (!raw) return undefined;
-    const n = parseInt(raw, 10);
-    return Number.isFinite(n) ? n : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-export interface FrameworkDrift {
-  /** True only when both versions are known AND the on-disk one is older. */
-  drifted: boolean;
-  installed?: number;
-  bundled?: number;
-}
-
-/**
- * Detect whether the on-disk framework is older than the framework bundled in
- * the installed CLI (#642). Conservative: if either version can't be read the
- * result is no-drift, so a missing/unreadable version file never triggers an
- * unexpected re-seed.
- */
-export function checkFrameworkDrift(
-  mosaicHome = join(homedir(), '.config', 'mosaic'),
-  frameworkRoot = resolveBundledFrameworkRoot(),
-): FrameworkDrift {
-  const installed = readInstalledFrameworkVersion(mosaicHome);
-  const bundled = readBundledFrameworkVersion(frameworkRoot);
-  const drifted =
-    typeof installed === 'number' && typeof bundled === 'number' && installed < bundled;
-  return { drifted, installed, bundled };
-}
-
 /**
  * Best-effort parse of the fleet roster for agent names (used to relaunch
  * durable agents after a re-seed). Returns [] when no roster exists.