ci: switch pipelines to pre-baked ci-base image (consumer) [Phase 1b]

Consumer half of the Woodpecker CI cache work (#634). Re-scoped from the original combined change: the image recipe (Dockerfile.ci, ci-image.yml) now lives in the producer PR #637. This branch only flips the consumers. - ci.yml / publish.yml: pull git.mosaicstack.dev/mosaicstack/stack/ci-base :latest for the install step and resolve from the baked pnpm store via --prefer-offline (drops the per-run apk add + cold network fetch). - framework monorepo template: single cached install instead of npm ci per step, so scaffolded repos inherit the fix. B2 fix (blocker): pin store-dir in root .npmrc to /root/.local/share/pnpm/store — the exact path Dockerfile.ci warms — so the pipeline install actually consumes the baked store instead of repopulating a fresh one. The existing @mosaicstack registry line is preserved. BLOCKED ON: PR #637 merge + a manual ci-image prime of ci-base:latest on main. Until the image is primed this branch's CI is red (it pulls an image that does not exist yet). Do not merge until a green re-run after priming. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
fix(install): preserve user fleet data on re-seed + refresh active units (CRITICAL) (#632 )
2026-06-22 16:50:39 -05:00 · 2026-06-22 21:38:09 +00:00 · 2026-06-22 21:08:43 +00:00 · 2026-06-22 21:08:41 +00:00 · 2026-06-22 19:49:45 +00:00
36 changed files with 597 additions and 128 deletions
--- a/.npmrc
+++ b/.npmrc
@@ -1 +1,5 @@
@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/
+# Pin the pnpm store to the same path the ci-base image warms (Dockerfile.ci),
+# so the pipeline `pnpm install --prefer-offline` consumes the baked store
+# instead of repopulating a fresh one.
+store-dir=/root/.local/share/pnpm/store
--- a/.woodpecker/ci.yml
+++ b/.woodpecker/ci.yml
@@ -1,5 +1,9 @@
+# &node_image is the pre-baked CI base built by .woodpecker/ci-image.yml:
+# node:22-alpine + python3/make/g++/postgresql-client + pnpm + a warm pnpm
+# store. The install step resolves from the baked store (--prefer-offline)
+# instead of paying a ~731s cold fetch + native compile every run.
 variables:
-  - &node_image 'node:22-alpine'
+  - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:latest'
  - &enable_pnpm 'corepack enable'

 when:
@@ -15,8 +19,9 @@ steps:
    image: *node_image
    commands:
      - corepack enable
-      - apk add --no-cache python3 make g++
-      - pnpm install --frozen-lockfile
+      # python3/make/g++ are baked into ci-base; --prefer-offline resolves from
+      # the baked pnpm store.
+      - pnpm install --frozen-lockfile --prefer-offline

  # Blocking gate: public framework package must contain no operator-specific
  # personal data or private $HOME defaults. Runs early (no node_modules needed).
@@ -64,8 +69,7 @@ steps:
      DATABASE_URL: postgresql://mosaic:mosaic@ci-postgres:5432/mosaic
    commands:
      - *enable_pnpm
-      # Install postgresql-client for pg_isready
-      - apk add --no-cache postgresql-client
+      # postgresql-client (pg_isready) is baked into ci-base.
      # Wait up to 60s for CI postgres to be ready; fail fast if it never comes up.
      - |
        ready=0
--- a/.woodpecker/publish.yml
+++ b/.woodpecker/publish.yml
@@ -2,7 +2,9 @@
 # Runs only on main branch push/tag

 variables:
-  - &node_image 'node:22-alpine'
+  # Pre-baked CI base (see .woodpecker/ci-image.yml): node:22-alpine +
+  # toolchain + warm pnpm store. Kills the second cold install publish pays.
+  - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:latest'
  - &enable_pnpm 'corepack enable'
  # Heavy kaniko image builds (~25 min) — gate them so a merge that only touches
  # the npm-only CLI (@mosaicstack/mosaic) or docs does NOT rebuild the platform
@@ -31,7 +33,8 @@ steps:
    image: *node_image
    commands:
      - corepack enable
-      - pnpm install --frozen-lockfile
+      # Resolve from the baked pnpm store instead of a cold network fetch.
+      - pnpm install --frozen-lockfile --prefer-offline

  build:
    image: *node_image
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -78,3 +78,11 @@ Active workstream is **W1 — Federation v1**. Workers should:
 ## Fleet stand-up fixes — model_hint→--model + socket-default trap (#626) — feat/fleet-standup-fixes

 - Status: implemented + tested. FIX1 model_hint→MOSAIC_AGENT_MODEL→--model. FIX2 absent socket = default tmux socket (no -L) across parse/spawn/systemd-unit/observe (socketArgs helper, bare-empty shellEnvValue, conditional -L). 158 fleet tests green; shipped presets unaffected (explicit socket_name). Detail: scratchpads/fleet-standup-fixes.md.
+
+## north-star doctrine consolidation — doc PR — feat/north-star-doctrine
+
+- Status: applied Mos's consolidated merge-map to docs/fleet/north-star.md (budget governance + control plane/central register + 200k cap + delegation + unified-identity Fleet + role-based naming + tmux security + drift re-captures). Doctrine only; #622/#623/#625/#628 out-of-scope. Conflict checklist green. Detail: scratchpads/north-star-doctrine.md.
+
+## #631 — re-seed preserves user fleet data (CRITICAL) — fix/631-reseed-preserves-fleet-data
+
+- Status: implemented + tested. PRIMARY: install.sh PRESERVE_PATHS += fleet/\*.yaml + fleet/agents + fleet/run (glob-aware cp-fallback); TS parity. SECONDARY: refreshActiveFleetUnits propagates unit fixes to ~/.config/systemd/user on mosaic update. bash F6 + TS + unit tests green. Detail: scratchpads/631-reseed-preserves-fleet.md.
--- a/docs/fleet/PRD.md
+++ b/docs/fleet/PRD.md
@@ -7,10 +7,10 @@

 ## Problem

-The durable tmux fleet runs on the isolated `mosaic-factory` socket. That isolation
+The durable tmux fleet runs on the isolated `mosaic-fleet` socket. That isolation
 (which protects the operator's default tmux) makes the fleet **invisible** to default
 tooling, and truth is split across three planes no single command joins — systemd
-(`systemctl --user`), tmux (`-L mosaic-factory`), and the process tree (`pstree`).
+(`systemctl --user`), tmux (`-L mosaic-fleet`), and the process tree (`pstree`).
 `agent tail` (`capture-pane`) returns **blank for full-screen TUIs**, and `agent send`
 confirms only keystroke injection, not acceptance. Net: the operator has near-zero
 observability and no safe way to watch a session.
@@ -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-factory` with correct
+- `mosaic fleet ps` shows all 5 live sessions on `mosaic-fleet` with correct
  pane/pid/idle and flags the dogfood **drift** (`canary-pi` runtime=pi but pane runs
  `dogfood-agent.py`) and the **boot-enable** gap (active but disabled).
 - Killing one agent's pane flips its row to dead/stale within one `interval`.
@@ -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-factory` fleet; capture `fleet ps` output,
+- Situational: run against the live `mosaic-fleet` fleet; capture `fleet ps` output,
  a kill-and-detect cycle, a read-only `watch`, and a `send --verify` pass/fail pair.

 ## Known limitations
--- a/docs/fleet/TASKS.md
+++ b/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-factory; 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-fleet; caught canary-pi DRIFT + BOOT-ENABLE. Polish: idleSeconds parse returns null |
 | FLEET-OBS-004 | done        | `mosaic agent watch <name>` — read-only join (no resize, no keystrokes)                                            | FLEET-OBS-000         | worker      | —   | `attach -r`; verb wired                                                                                                     |
 | FLEET-OBS-005 | done        | `mosaic agent send --verify` — delivery/acceptance receipt                                                         | FLEET-OBS-000         | worker      | —   | --verify flag; draft-heuristic verify                                                                                       |
 | FLEET-OBS-006 | done        | CLI specs for ps/watch/send-verify (tenant+host shape, command construction)                                       | FLEET-OBS-003,004,005 | worker      | —   | 62 tests green (31 new); re-verified by lead                                                                                |
--- a/docs/fleet/north-star.md
+++ b/docs/fleet/north-star.md
@@ -56,13 +56,21 @@ 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)

@@ -113,6 +121,67 @@ 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                                                                                           |
@@ -127,15 +196,83 @@ Every artifact, starting Phase 2, MUST:
 > (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                                 | planned |
-| 5 — Control plane      | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity                                    | planned |
+| 4 — Unified definition | one agent schema in gateway; `mosaic agent --new` → materialized per-tenant session; uid-tenant provisioning; **`fleet` schema migration + `forge-exec` TaskExecutor adapter (forge → `agent-send.sh`)** | planned |
+| 5 — Control plane      | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity; **central register live (spend ledger, docs-as-projections, multi-host Kanban)**              | planned |

 ## Decisions of record (2026-06-20, with Jason)

@@ -164,6 +301,57 @@ Every artifact, starting Phase 2, MUST:
 - **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)

@@ -173,6 +361,16 @@ Every artifact, starting Phase 2, MUST:
  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)

@@ -184,3 +382,30 @@ Every artifact, starting Phase 2, MUST:
 - `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.
--- a/docs/guides/fleet-local-canary.md
+++ b/docs/guides/fleet-local-canary.md
@@ -1,7 +1,7 @@
 # Local Fleet Canary

 The local fleet canary runs a small tmux-backed Mosaic agent fleet on an
-isolated tmux socket. The default socket is `mosaic-factory`; the commands do
+isolated tmux socket. The default socket is `mosaic-fleet`; the commands do
 not use or stop the default tmux server.

 ## Files
@@ -67,7 +67,7 @@ mosaic agent tail canary-pi -n 80

 These commands read the roster and target the configured tmux socket. The
 generated systemd agent services use `start-agent-session.sh`; message delivery
-uses the tmux send tools with `-L mosaic-factory`.
+uses the tmux send tools with `-L mosaic-fleet`.

 `mosaic agent send` is operator-origin traffic unless a caller explicitly says
 otherwise. The CLI always passes a deterministic source label to
@@ -82,7 +82,7 @@ impersonating a known handoff lane. The lower-level inter-agent wrapper
 Use these checks before expanding the roster:

 ```bash
-tmux -L mosaic-factory ls
+tmux -L mosaic-fleet ls
 tmux ls
 mosaic fleet verify
 systemctl --user status mosaic-tmux-holder.service
@@ -90,7 +90,7 @@ systemctl --user status mosaic-tmux-holder.service

 Expected results:

- `tmux -L mosaic-factory ls` shows `_holder` and roster agent sessions.
+- `tmux -L mosaic-fleet ls` shows `_holder` and roster agent sessions.
 - `tmux ls` shows only the default tmux server sessions and is not changed by
  fleet start/stop operations.
 - `mosaic fleet verify` checks exact session targets on the isolated socket.
@@ -108,7 +108,7 @@ Run this checklist before cutting or dogfooding a fleet release:
  repeated `start` against the named socket; verify the default tmux server is
  unchanged.
 - Liveness verification: run `mosaic fleet verify` and confirm roster sessions
-  with `tmux -L mosaic-factory ls` or exact `has-session` checks.
+  with `tmux -L mosaic-fleet ls` or exact `has-session` checks.
 - Package dry-run: run `npm pack --dry-run --json` from `packages/mosaic` and
  confirm `framework/fleet`, `framework/systemd/user`,
  `framework/tools/fleet`, and `framework/tools/tmux` assets are included.
@@ -140,5 +140,5 @@ This rollback leaves the default tmux server untouched. If a canary session is
 still present after service stop, remove only the isolated socket server:

 ```bash
-tmux -L mosaic-factory kill-server
+tmux -L mosaic-fleet kill-server
 ```
--- a/docs/scratchpads/2026-06-20-fleet-cli-local-canary.md
+++ b/docs/scratchpads/2026-06-20-fleet-cli-local-canary.md
@@ -17,7 +17,7 @@ Implement enough product surface to use the fleet locally:
 - roster schema and examples
 - local canary docs and rollback instructions
 - tests for CLI behavior where practical
- canary verification on named tmux socket `mosaic-factory`
+- canary verification on named tmux socket `mosaic-fleet`

 ## Non-goals

@@ -30,7 +30,7 @@ Implement enough product surface to use the fleet locally:

 - CLI can initialize a minimal roster outside product defaults.
 - CLI can install user systemd units and fleet helper scripts to a configurable Mosaic home.
- CLI can start/stop/status/verify a canary fleet using `mosaic-factory`.
+- CLI can start/stop/status/verify a canary fleet using `mosaic-fleet`.
 - `mosaic agent send` uses existing named-socket/exact-target tmux tooling.
 - `mosaic agent reset` targets only the named agent session on the named socket.
 - Verification proves default tmux sessions remain untouched.
--- a/docs/scratchpads/631-reseed-preserves-fleet.md
+++ b/docs/scratchpads/631-reseed-preserves-fleet.md
@@ -0,0 +1,32 @@
+# #631 — re-seed must preserve user fleet data (CRITICAL data-loss)
+
+- **Issue:** #631 · **Branch:** `fix/631-reseed-preserves-fleet-data`
+
+## Root cause
+
+`mosaic update` auto-runs `install.sh` keep-mode sync (#610). install.sh's rsync `--delete` (keep mode)
+honored PRESERVE_PATHS, but `fleet/` wasn't listed → the sync WIPED `~/.config/mosaic/fleet/roster.yaml`
+(+ run/, agents/). Any user running `mosaic update` lost their roster. (overwrite mode wipes by design;
+the live loss was keep mode.)
+
+## Fix (PRIMARY)
+
+- install.sh PRESERVE_PATHS += `fleet/*.yaml`, `fleet/agents`, `fleet/run` — the framework still SEEDS
+  fleet/examples + fleet/roles + fleet/roster.schema.json (synced), but user files survive.
+- Made the cp-fallback (no-rsync) GLOB-AWARE so `fleet/*.yaml` preserves every user roster there too;
+  fixed the restore to re-glob per-pattern (so only the user file is restored, not the whole fleet/ dir).
+- file-adapter.ts (TS installer): mirrored the preserve list for parity. (TS syncDirectory is copy-only,
+  never --delete, so it never had the bug — belt-and-suspenders + parity.)
+
+## Fix (SECONDARY)
+
+- `refreshActiveFleetUnits()` (update-checker.ts): the re-seed updates ~/.config/mosaic/systemd/user but
+  systemd runs ~/.config/systemd/user, so unit fixes (#627) didn't take effect. After the re-seed,
+  `mosaic update` now copies the fresh mosaic-\*.service → the active dir + daemon-reload (best-effort,
+  only when a fleet is already installed). Wired into the cli.ts update flow.
+
+## Verification
+
+- bash F6 fixture (6 checks: roster/custom-yaml/agents/run survive + examples refreshed + schema seeded);
+  20/20 migration matrix green. TS file-adapter test (roster/run/agents survive keep sync). 2 unit tests
+  for refreshActiveFleetUnits. tsc/eslint/prettier/sanitize clean.
--- a/docs/scratchpads/fleet-observability-phase2.md
+++ b/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-factory`: `_holder`, `canary-pi`, `dogfood-coder`, `dogfood-orchestrator`,
+  `mosaic-fleet`: `_holder`, `canary-pi`, `dogfood-coder`, `dogfood-orchestrator`,
  `dogfood-reviewer`. All panes run `~/.config/mosaic/fleet/dogfood-agent.py` (stub),
  including `canary-pi` (roster says runtime=pi → **drift**).
 - Holder + `mosaic-agent@*` units are `active (exited)` but `UnitFileState=disabled`
@@ -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-factory — correctly flagged canary-pi DRIFT + BOOT-ENABLE, tenant_id+host in JSON.
+  mosaic-fleet — correctly flagged canary-pi DRIFT + BOOT-ENABLE, tenant_id+host in JSON.
  Heartbeat responder added to dogfood-agent.py (FLEET-OBS-002) — `fleet ps` HB now
  `healthy` for all 4 agents.
 - Coordination: dual-engine-reviewed (Claude+Codex) and merged framework PRs #572
--- a/docs/scratchpads/fleet-standup-fixes.md
+++ b/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-factory` + `ExecStop ${…:-mosaic-factory}`; start-agent-session
-  defaulted `:-mosaic-factory`. All fixed → absent socket = '' = default tmux socket (no -L).
+  `Environment=MOSAIC_TMUX_SOCKET=mosaic-fleet` + `ExecStop ${…:-mosaic-fleet}`; start-agent-session
+  defaulted `:-mosaic-fleet`. All fixed → absent socket = '' = default tmux socket (no -L).
 - `socketArgs(name)` helper → `name ? ['-L', name] : []`; replaced all ~15 -L render sites in fleet.ts.
 - shellEnvValue('') now emits a **bare** `VAR=` (not `''`) — unambiguous empty in systemd EnvironmentFile
  (a quoted '' could become a literal socket named "''").
 - start-agent-session.sh: `_tmux` wrapper passes -L only when socket set; mosaic-agent@.service: dropped the
  socket default + conditional ExecStop. So spawn == observe == onboarding cheat-sheet.
- CONTAINMENT: all 6 shipped presets set socket_name: mosaic-factory explicitly → unaffected; only
+- CONTAINMENT: all 6 shipped presets set socket_name: mosaic-fleet explicitly → unaffected; only
  socket-less rosters (the PoC) get default-socket behavior. DEFAULT_SOCKET_NAME exported for explicit use.

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

-The default tmux socket is `mosaic-factory` so fleet commands do not touch the
+The default tmux socket is `mosaic-fleet` so fleet commands do not touch the
 default tmux server.

 ## Examples
--- a/packages/mosaic/framework/fleet/examples/coding.yaml
+++ b/packages/mosaic/framework/fleet/examples/coding.yaml
@@ -1,7 +1,7 @@
 version: 1
 transport: tmux
 tmux:
-  socket_name: mosaic-factory
+  socket_name: mosaic-fleet
  holder_session: _holder
 defaults:
  working_directory: ~
--- a/packages/mosaic/framework/fleet/examples/general.yaml
+++ b/packages/mosaic/framework/fleet/examples/general.yaml
@@ -1,7 +1,7 @@
 version: 1
 transport: tmux
 tmux:
-  socket_name: mosaic-factory
+  socket_name: mosaic-fleet
  holder_session: _holder
 defaults:
  working_directory: ~
--- a/packages/mosaic/framework/fleet/examples/hybrid.yaml
+++ b/packages/mosaic/framework/fleet/examples/hybrid.yaml
@@ -1,7 +1,7 @@
 version: 1
 transport: tmux
 tmux:
-  socket_name: mosaic-factory
+  socket_name: mosaic-fleet
  holder_session: _holder
 defaults:
  working_directory: ~
--- a/packages/mosaic/framework/fleet/examples/local-canary.yaml
+++ b/packages/mosaic/framework/fleet/examples/local-canary.yaml
@@ -1,7 +1,7 @@
 version: 1
 transport: tmux
 tmux:
-  socket_name: mosaic-factory
+  socket_name: mosaic-fleet
  holder_session: _holder
 defaults:
  working_directory: ~/src
--- a/packages/mosaic/framework/fleet/examples/minimal.yaml
+++ b/packages/mosaic/framework/fleet/examples/minimal.yaml
@@ -1,7 +1,7 @@
 version: 1
 transport: tmux
 tmux:
-  socket_name: mosaic-factory
+  socket_name: mosaic-fleet
  holder_session: _holder
 defaults:
  working_directory: ~/src
--- a/packages/mosaic/framework/fleet/examples/research.yaml
+++ b/packages/mosaic/framework/fleet/examples/research.yaml
@@ -1,7 +1,7 @@
 version: 1
 transport: tmux
 tmux:
-  socket_name: mosaic-factory
+  socket_name: mosaic-fleet
  holder_session: _holder
 defaults:
  working_directory: ~
--- a/packages/mosaic/framework/fleet/roster.schema.json
+++ b/packages/mosaic/framework/fleet/roster.schema.json
@@ -18,11 +18,11 @@
      "properties": {
        "socket_name": {
          "type": "string",
-          "default": "mosaic-factory"
+          "default": "mosaic-fleet"
        },
        "socketName": {
          "type": "string",
-          "default": "mosaic-factory"
+          "default": "mosaic-fleet"
        },
        "holder_session": {
          "type": "string",
--- a/packages/mosaic/framework/install.sh
+++ b/packages/mosaic/framework/install.sh
@@ -23,7 +23,15 @@ INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 # entries (CONSTITUTION/AGENTS/STANDARDS) ARE re-applied afterward by
 # reconcile_framework_files (overwrite + backup-once); the rest stay user-owned.
 # User-created content in these paths survives rsync --delete.
-PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials")
+#
+# fleet/* — the framework SEEDS only fleet/examples, fleet/roles, and
+# fleet/roster.schema.json (synced normally). 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
+# update wipes the operator's fleet. Glob entries are honored by both the rsync
+# path (`--exclude`) and the glob-aware cp fallback below.
+PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials" "fleet/*.yaml" "fleet/agents" "fleet/run")

 # Framework-owned contract files: re-copied from defaults/ on every upgrade (the
 # user must not edit them; a divergent copy is backed up once before overwrite).
@@ -179,15 +187,23 @@ sync_framework() {
    return
  fi

-  # Fallback: cp-based sync
+  # Fallback: cp-based sync. Glob-aware so entries like "fleet/*.yaml" preserve
+  # every matching user file (parity with the rsync --exclude path above).
  local preserve_tmp=""
  if [[ "$INSTALL_MODE" == "keep" ]]; then
    preserve_tmp="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-preserve-XXXXXX")"
+    local match rel
    for path in "${PRESERVE_PATHS[@]}"; do
-      if [[ -e "$TARGET_DIR/$path" ]]; then
-        mkdir -p "$preserve_tmp/$(dirname "$path")"
-        cp -R "$TARGET_DIR/$path" "$preserve_tmp/$path"
-      fi
+      # Unquoted $path lets the glob expand against TARGET_DIR; nullglob makes a
+      # non-matching pattern vanish instead of staying literal.
+      shopt -s nullglob
+      for match in "$TARGET_DIR/"$path; do
+        [[ -e "$match" ]] || continue
+        rel="${match#"$TARGET_DIR/"}"
+        mkdir -p "$preserve_tmp/$(dirname "$rel")"
+        cp -R "$match" "$preserve_tmp/$rel"
+      done
+      shopt -u nullglob
    done
  fi

@@ -196,12 +212,19 @@ sync_framework() {
  rm -rf "$TARGET_DIR/.git"

  if [[ -n "$preserve_tmp" ]]; then
+    # Restore by re-globbing the SAME patterns against preserve_tmp, so each
+    # preserved item is restored at its own relative path (e.g. only
+    # fleet/roster.yaml is replaced — the freshly-synced fleet/examples stays).
    for path in "${PRESERVE_PATHS[@]}"; do
-      if [[ -e "$preserve_tmp/$path" ]]; then
-        rm -rf "$TARGET_DIR/$path"
-        mkdir -p "$TARGET_DIR/$(dirname "$path")"
-        cp -R "$preserve_tmp/$path" "$TARGET_DIR/$path"
-      fi
+      shopt -s nullglob
+      for match in "$preserve_tmp/"$path; do
+        [[ -e "$match" ]] || continue
+        rel="${match#"$preserve_tmp/"}"
+        rm -rf "$TARGET_DIR/$rel"
+        mkdir -p "$TARGET_DIR/$(dirname "$rel")"
+        cp -R "$match" "$TARGET_DIR/$rel"
+      done
+      shopt -u nullglob
    done
    rm -rf "$preserve_tmp"
  fi
--- a/packages/mosaic/framework/systemd/user/README.md
+++ b/packages/mosaic/framework/systemd/user/README.md
@@ -33,7 +33,7 @@ Per-agent overrides live outside the package in:
 Example:

 ```dotenv
-MOSAIC_TMUX_SOCKET=mosaic-factory
+MOSAIC_TMUX_SOCKET=mosaic-fleet
 MOSAIC_AGENT_RUNTIME=claude
 MOSAIC_AGENT_WORKDIR=$HOME/src/your-project
 # Optional escape hatch for PoC/canary agents:
@@ -50,8 +50,8 @@ chmod +x ~/.config/mosaic/tools/fleet/start-agent-session.sh
 systemctl --user daemon-reload
 systemctl --user start mosaic-tmux-holder.service
 systemctl --user start mosaic-agent@canary.service
-tmux -L mosaic-factory ls
+tmux -L mosaic-fleet ls
 ```

-Do not use `tmux kill-server` without `-L mosaic-factory`; this pattern is meant
+Do not use `tmux kill-server` without `-L mosaic-fleet`; this pattern is meant
 to avoid disturbing the user's default tmux server.
--- a/packages/mosaic/framework/systemd/user/mosaic-tmux-holder.service
+++ b/packages/mosaic/framework/systemd/user/mosaic-tmux-holder.service
@@ -6,7 +6,7 @@ After=default.target
 [Service]
 Type=oneshot
 RemainAfterExit=yes
-Environment=MOSAIC_TMUX_SOCKET=mosaic-factory
+Environment=MOSAIC_TMUX_SOCKET=mosaic-fleet
 Environment=MOSAIC_TMUX_HOLDER=_holder
 ExecStart=/bin/bash -lc 'tmux -L "$MOSAIC_TMUX_SOCKET" has-session -t "=${MOSAIC_TMUX_HOLDER}:0.0" 2>/dev/null || tmux -L "$MOSAIC_TMUX_SOCKET" new-session -d -s "$MOSAIC_TMUX_HOLDER" "while true; do sleep 3600; done"'
 ExecStop=-/bin/bash -lc 'tmux -L "$MOSAIC_TMUX_SOCKET" kill-server'
--- a/packages/mosaic/framework/tools/fleet/start-agent-session.sh
+++ b/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-factory
+# socket_name is honored when set; absent never silently becomes mosaic-fleet
 # (spawn stays consistent with the onboarding cheat-sheet + fleet ps observe).
 MOSAIC_TMUX_SOCKET=${MOSAIC_TMUX_SOCKET:-}
 MOSAIC_AGENT_RUNTIME=${MOSAIC_AGENT_RUNTIME:-pi}
--- a/packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
+++ b/packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
@@ -61,7 +61,25 @@ MOSAIC_HOME="$T5" MOSAIC_INSTALL_MODE=bogus MOSAIC_SYNC_ONLY=1 bash "$INSTALL" >
 chk "F5 failure: invalid mode rejected (nonzero exit)" "[ $rc -ne 0 ]"
 chk "F5 failure: SOUL + credentials intact" "grep -q orig '$T5/SOUL.md' && grep -q keepme '$T5/credentials/c.json'"

-rm -rf "$T1" "$T2" "$T3" "$T4" "$T5"
+# F6 — keep-mode re-seed (the `mosaic update` path) MUST NOT wipe user fleet data.
+# Regression for the roster-loss bug: fleet/ was not in PRESERVE_PATHS.
+T6=$(mktemp -d); mkdir -p "$T6/fleet/examples" "$T6/fleet/run" "$T6/fleet/agents"
+printf '# persona\n' > "$T6/SOUL.md"   # makes it a recognized existing install (→ keep mode)
+printf 'version: 1\nagents:\n  - name: coder0\n' > "$T6/fleet/roster.yaml"
+printf 'version: 1\nagents:\n  - name: custom\n' > "$T6/fleet/my-fleet.yaml"
+printf 'ts=x\n' > "$T6/fleet/run/coder0.hb"
+printf 'MOSAIC_AGENT_NAME=coder0\n' > "$T6/fleet/agents/coder0.env"
+printf '# stale preset\n' > "$T6/fleet/examples/general.yaml"
+echo 3 > "$T6/.framework-version"
+run "$T6" keep
+chk "F6 reseed: user roster.yaml SURVIVES keep-mode sync" "grep -q coder0 '$T6/fleet/roster.yaml'"
+chk "F6 reseed: other user fleet/*.yaml survives (glob)" "[ -f '$T6/fleet/my-fleet.yaml' ]"
+chk "F6 reseed: per-agent env (fleet/agents) survives" "[ -f '$T6/fleet/agents/coder0.env' ]"
+chk "F6 reseed: heartbeat run dir (fleet/run) survives" "[ -f '$T6/fleet/run/coder0.hb' ]"
+chk "F6 reseed: framework examples ARE refreshed (not preserved stale)" "grep -q orchestrator '$T6/fleet/examples/general.yaml'"
+chk "F6 reseed: framework roster.schema.json seeded" "[ -f '$T6/fleet/roster.schema.json' ]"
+
+rm -rf "$T1" "$T2" "$T3" "$T4" "$T5" "$T6"
 echo
 echo "RESULT: $pass passed, $fail failed"
 [ "$fail" -eq 0 ]
--- a/packages/mosaic/framework/tools/quality/templates/monorepo/.woodpecker.yml
+++ b/packages/mosaic/framework/tools/quality/templates/monorepo/.woodpecker.yml
@@ -2,12 +2,20 @@
 when:
  - event: [push, pull_request, manual]

+# Dependencies are installed ONCE in the `install` step and every downstream
+# step depends on it, reusing the populated node_modules from the shared
+# workspace volume. Do NOT re-run `npm ci` per step — that pays the full cold
+# install (network fetch + native rebuilds) N times and is the dominant cost
+# in a pipeline.
+#
+# For best results, replace `&node_image` with a pre-baked CI base image that
+# ships your toolchain (python3/make/g++ for native modules) and a warm npm
+# cache, then keep `--prefer-offline` so installs resolve from the cache. See
+# the Mosaic Stack repo's Dockerfile.ci + .woodpecker/ci-image.yml for the
+# baked-image pattern.
 variables:
  - &node_image 'node:20-alpine'
  - &gitleaks_image 'ghcr.io/gitleaks/gitleaks:v8.24.0'
-  - &install_deps |
-    corepack enable
-    npm ci --ignore-scripts

 steps:
  # Secret scanning (runs in parallel with install, no deps)
@@ -17,15 +25,18 @@ steps:
      - gitleaks git --redact --verbose --log-opts="HEAD~1..HEAD"
    depends_on: []

+  # Single cached install. Every other step depends on this and reuses the
+  # node_modules it produces in the shared workspace.
  install:
    image: *node_image
    commands:
-      - *install_deps
+      - corepack enable
+      - npm ci --ignore-scripts --prefer-offline
+    depends_on: []

  security-audit:
    image: *node_image
    commands:
-      - *install_deps
      - npm audit --audit-level=high
    depends_on:
      - install
@@ -35,7 +46,6 @@ steps:
    environment:
      SKIP_ENV_VALIDATION: 'true'
    commands:
-      - *install_deps
      - npm run lint
    depends_on:
      - install
@@ -45,7 +55,6 @@ steps:
    environment:
      SKIP_ENV_VALIDATION: 'true'
    commands:
-      - *install_deps
      - npm run type-check
    depends_on:
      - install
@@ -55,7 +64,6 @@ steps:
    environment:
      SKIP_ENV_VALIDATION: 'true'
    commands:
-      - *install_deps
      - npm run test -- --coverage --coverageThreshold='{"global":{"branches":80,"functions":80,"lines":80,"statements":80}}'
    depends_on:
      - install
@@ -66,7 +74,6 @@ steps:
      SKIP_ENV_VALIDATION: 'true'
      NODE_ENV: 'production'
    commands:
-      - *install_deps
      - npm run build
    depends_on:
      - lint
--- a/packages/mosaic/framework/tools/tmux/README.md
+++ b/packages/mosaic/framework/tools/tmux/README.md
@@ -35,7 +35,7 @@ delivers reliably to local OR remote panes.
 agent-send.sh -s <dst_session> -m "message"

 # Local target on a Mosaic fleet socket
-agent-send.sh -L mosaic-factory -s '=coder0' -m "message"
+agent-send.sh -L mosaic-fleet -s '=coder0' -m "message"

 # Remote target (over ssh)
 agent-send.sh -H user@host -s <dst_session> -m "message"
@@ -58,9 +58,9 @@ commands do not fall back to tmux's prefix matching behavior.
 Durable Mosaic fleets should use a dedicated tmux socket, for example:

 ```bash
-tmux -L mosaic-factory ls
-agent-send.sh -L mosaic-factory -s '=coder0' -m "status?"
-send-message.sh -L mosaic-factory -t '=coder0' -m "raw pane message"
+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"
 ```

 This keeps fleet operations away from the user's default tmux server. It is the
--- a/packages/mosaic/src/cli.ts
+++ b/packages/mosaic/src/cli.ts
@@ -27,6 +27,7 @@ import {
  formatAllPackagesTable,
  getInstallAllCommand,
  runFrameworkReseed,
+  refreshActiveFleetUnits,
  readRosterAgentNames,
  buildRelaunchCommands,
  FRAMEWORK_RESEED_PACKAGE,
@@ -466,6 +467,12 @@ program
      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) {
--- a/packages/mosaic/src/commands/fleet.spec.ts
+++ b/packages/mosaic/src/commands/fleet.spec.ts
@@ -132,14 +132,14 @@ describe('fleet roster parsing', () => {

    const roster = await loadFleetRoster(rosterPath);

-    expect(roster.tmux.socketName).toBe(''); // absent ⇒ default socket (no -L), not mosaic-factory
+    expect(roster.tmux.socketName).toBe(''); // absent ⇒ default socket (no -L), not mosaic-fleet
    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-factory')).toEqual(['-L', 'mosaic-factory']);
+    expect(socketArgs('mosaic-fleet')).toEqual(['-L', 'mosaic-fleet']);
    expect(socketArgs('')).toEqual([]);
  });

@@ -152,14 +152,14 @@ describe('fleet roster parsing', () => {
        'version: 1',
        'transport: tmux',
        'tmux:',
-        '  socket_name: mosaic-factory',
+        '  socket_name: mosaic-fleet',
        'agents:',
        '  - name: canary-pi',
        '    runtime: pi',
      ].join('\n'),
    );
    const roster = await loadFleetRoster(rosterPath);
-    expect(roster.tmux.socketName).toBe('mosaic-factory');
+    expect(roster.tmux.socketName).toBe('mosaic-fleet');
    expect(buildTmuxListSessionsCommand(roster.tmux.socketName)).toContain('-L');
  });

@@ -189,7 +189,7 @@ describe('fleet roster parsing', () => {
      JSON.stringify({
        version: 1,
        transport: 'tmux',
-        tmux: { socket_name: 'mosaic-factory' },
+        tmux: { socket_name: 'mosaic-fleet' },
        defaults: { working_directory: '/srv/mosaic' },
        agents: [{ name: 'coder0', runtime: 'codex', class: 'implementer' }],
      }),
@@ -202,7 +202,7 @@ describe('fleet roster parsing', () => {
        'MOSAIC_AGENT_RUNTIME=codex',
        'MOSAIC_AGENT_MODEL=',
        'MOSAIC_AGENT_WORKDIR=/srv/mosaic',
-        'MOSAIC_TMUX_SOCKET=mosaic-factory',
+        'MOSAIC_TMUX_SOCKET=mosaic-fleet',
        '',
      ].join('\n'),
    );
@@ -213,7 +213,7 @@ describe('fleet roster parsing', () => {
      'MOSAIC_AGENT_NAME=coder0',
      'MOSAIC_AGENT_RUNTIME=codex',
      'MOSAIC_AGENT_WORKDIR=/srv/new',
-      'MOSAIC_TMUX_SOCKET=mosaic-factory',
+      'MOSAIC_TMUX_SOCKET=mosaic-fleet',
      '',
    ].join('\n');
    const existing = [
@@ -231,7 +231,7 @@ describe('fleet roster parsing', () => {
        'MOSAIC_AGENT_NAME=coder0',
        'MOSAIC_AGENT_RUNTIME=codex',
        'MOSAIC_AGENT_WORKDIR=/srv/new',
-        'MOSAIC_TMUX_SOCKET=mosaic-factory',
+        'MOSAIC_TMUX_SOCKET=mosaic-fleet',
        'MOSAIC_AGENT_COMMAND=/home/jarvis/.config/mosaic/fleet/canary.sh',
        '# site note',
        '',
@@ -324,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-factory');
+    expect(localCanary.tmux.socketName).toBe('mosaic-fleet');
    expect(localCanary.agents.map((agent) => agent.name)).toEqual(['lead', 'coder0', 'reviewer0']);
    expect(localCanaryText).not.toMatch(/usc|ultron|secrev/i);
  });
@@ -349,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-factory', 'operator:mosaic-cli'),
+      buildAgentSendCommand(paths, 'coder0', 'hello', 'mosaic-fleet', 'operator:mosaic-cli'),
    ).toEqual([
      '/home/test/.config/mosaic/tools/tmux/agent-send.sh',
      '-L',
-      'mosaic-factory',
+      'mosaic-fleet',
      '-S',
      'operator:mosaic-cli',
      '-s',
@@ -841,10 +841,10 @@ describe('fleet ps — command construction', () => {
  });

  it('builds exact tmux list-panes command with the correct format string', () => {
-    expect(buildTmuxListPanesCommand('canary-pi', 'mosaic-factory')).toEqual([
+    expect(buildTmuxListPanesCommand('canary-pi', 'mosaic-fleet')).toEqual([
      'tmux',
      '-L',
-      'mosaic-factory',
+      'mosaic-fleet',
      'list-panes',
      '-t',
      '=canary-pi:0.0',
@@ -1167,7 +1167,7 @@ describe('fleet install — auto-enable units for boot-survival', () => {
    const minimalRoster: FleetRoster = {
      version: 1,
      transport: 'tmux',
-      tmux: { socketName: 'mosaic-factory', holderSession: '_holder' },
+      tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
      defaults: { workingDirectory: '~/src' },
      runtimes: { codex: { resetCommand: '/clear' } },
      agents: [{ name: 'coder0', runtime: 'codex', className: 'worker' }],
@@ -1189,7 +1189,7 @@ describe('fleet install — auto-enable units for boot-survival', () => {
    const minimalRoster: FleetRoster = {
      version: 1,
      transport: 'tmux',
-      tmux: { socketName: 'mosaic-factory', holderSession: '_holder' },
+      tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
      defaults: { workingDirectory: '~/src' },
      runtimes: { codex: { resetCommand: '/clear' } },
      agents: [{ name: 'coder0', runtime: 'codex', className: 'worker' }],
@@ -1216,7 +1216,7 @@ describe('fleet install — auto-enable units for boot-survival', () => {
    const minimalRoster: FleetRoster = {
      version: 1,
      transport: 'tmux',
-      tmux: { socketName: 'mosaic-factory', holderSession: '_holder' },
+      tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
      defaults: { workingDirectory: '~/src' },
      runtimes: { codex: { resetCommand: '/clear' } },
      agents: [{ name: 'coder0', runtime: 'codex', className: 'worker' }],
@@ -1388,10 +1388,10 @@ describe('fleet ps — command sequences issued', () => {

 describe('buildTmuxListSessionsCommand', () => {
  it('builds exact list-sessions command with session_name format', () => {
-    expect(buildTmuxListSessionsCommand('mosaic-factory')).toEqual([
+    expect(buildTmuxListSessionsCommand('mosaic-fleet')).toEqual([
      'tmux',
      '-L',
-      'mosaic-factory',
+      'mosaic-fleet',
      'list-sessions',
      '-F',
      '#{session_name}',
@@ -1642,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-factory'),
+      buildAgentWatchCreateViewerCommand('canary-pi', 'canary-pi-watch-123', 'mosaic-fleet'),
    ).toEqual([
      'tmux',
      '-L',
-      'mosaic-factory',
+      'mosaic-fleet',
      'new-session',
      '-d',
      '-t',
@@ -1657,10 +1657,10 @@ describe('agent watch', () => {
  });

  it('builds exact viewer attach command (read-only)', () => {
-    expect(buildAgentWatchAttachCommand('canary-pi-watch-123', 'mosaic-factory')).toEqual([
+    expect(buildAgentWatchAttachCommand('canary-pi-watch-123', 'mosaic-fleet')).toEqual([
      'tmux',
      '-L',
-      'mosaic-factory',
+      'mosaic-fleet',
      'attach',
      '-r',
      '-t',
@@ -1669,10 +1669,10 @@ describe('agent watch', () => {
  });

  it('builds exact viewer kill command', () => {
-    expect(buildAgentWatchKillViewerCommand('canary-pi-watch-123', 'mosaic-factory')).toEqual([
+    expect(buildAgentWatchKillViewerCommand('canary-pi-watch-123', 'mosaic-fleet')).toEqual([
      'tmux',
      '-L',
-      'mosaic-factory',
+      'mosaic-fleet',
      'kill-session',
      '-t',
      'canary-pi-watch-123',
@@ -1769,10 +1769,10 @@ describe('agent watch', () => {

 describe('agent send --verify', () => {
  it('builds exact verify capture-pane command', () => {
-    expect(buildAgentVerifyAcceptedCommand('canary-pi', 'mosaic-factory', 5)).toEqual([
+    expect(buildAgentVerifyAcceptedCommand('canary-pi', 'mosaic-fleet', 5)).toEqual([
      'tmux',
      '-L',
-      'mosaic-factory',
+      'mosaic-fleet',
      'capture-pane',
      '-t',
      '=canary-pi:0.0',
@@ -2484,7 +2484,7 @@ describe('fleet add/remove — pure helpers', () => {
  const baseRoster: FleetRoster = {
    version: 1,
    transport: 'tmux',
-    tmux: { socketName: 'mosaic-factory', holderSession: '_holder' },
+    tmux: { socketName: 'mosaic-fleet', holderSession: '_holder' },
    defaults: { workingDirectory: '~/src' },
    runtimes: { codex: { resetCommand: '/clear' } },
    agents: [
@@ -2610,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-factory');
+      expect(loaded.tmux.socketName).toBe('mosaic-fleet');
      expect(loaded.agents[0]!.className).toBe('orchestrator');
    } finally {
      await rm(dir, { recursive: true, force: true });
--- a/packages/mosaic/src/commands/fleet.ts
+++ b/packages/mosaic/src/commands/fleet.ts
@@ -122,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-factory';
+export const DEFAULT_SOCKET_NAME = 'mosaic-fleet';
 const DEFAULT_HOLDER_SESSION = '_holder';
 const DEFAULT_WORKING_DIRECTORY = '~/src';

@@ -130,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-factory; it is no
+ * remains a constant for callers that explicitly want mosaic-fleet; it is no
 * longer the silent fallback for a socket-less roster.
 */
 export function socketArgs(socketName: string): string[] {
@@ -1689,7 +1689,7 @@ function normalizeRoster(raw: RawFleetRoster): FleetRoster {
    transport: 'tmux',
    tmux: {
      // Absent socket_name ⇒ '' (the literal default tmux socket, no -L) — NOT
-      // mosaic-factory. Shipped presets set socket_name explicitly, so they are
+      // mosaic-fleet. 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,
--- a/packages/mosaic/src/config/file-adapter.test.ts
+++ b/packages/mosaic/src/config/file-adapter.test.ts
@@ -153,6 +153,30 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => {
    expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md'), 'utf-8')).toBe('# AGENTS default\n');
  });

+  it('preserves user fleet data (roster.yaml, agents/, run/) through a keep-mode sync', async () => {
+    // Regression for the roster-loss bug (#631): user-authored fleet files must
+    // survive the framework re-seed that `mosaic update` runs.
+    mkdirSync(join(fixture.mosaicHome, 'fleet', 'run'), { recursive: true });
+    mkdirSync(join(fixture.mosaicHome, 'fleet', 'agents'), { recursive: true });
+    writeFileSync(join(fixture.mosaicHome, 'fleet', 'roster.yaml'), 'version: 1\nMINE\n');
+    writeFileSync(join(fixture.mosaicHome, 'fleet', 'run', 'a.hb'), 'ts=x\n');
+    writeFileSync(join(fixture.mosaicHome, 'fleet', 'agents', 'a.env'), 'X=1\n');
+    // The framework ships fleet/examples — it should still seed/refresh.
+    mkdirSync(join(fixture.sourceDir, 'fleet', 'examples'), { recursive: true });
+    writeFileSync(join(fixture.sourceDir, 'fleet', 'examples', 'general.yaml'), '# preset\n');
+
+    const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
+    await adapter.syncFramework('keep');
+
+    expect(readFileSync(join(fixture.mosaicHome, 'fleet', 'roster.yaml'), 'utf-8')).toBe(
+      'version: 1\nMINE\n',
+    );
+    expect(existsSync(join(fixture.mosaicHome, 'fleet', 'run', 'a.hb'))).toBe(true);
+    expect(existsSync(join(fixture.mosaicHome, 'fleet', 'agents', 'a.env'))).toBe(true);
+    // framework-owned fleet/examples is seeded
+    expect(existsSync(join(fixture.mosaicHome, 'fleet', 'examples', 'general.yaml'))).toBe(true);
+  });
+
  it('is a no-op for seeding when defaults/ dir does not exist', async () => {
    rmSync(fixture.defaultsDir, { recursive: true });

--- a/packages/mosaic/src/config/file-adapter.ts
+++ b/packages/mosaic/src/config/file-adapter.ts
@@ -173,6 +173,13 @@ export class FileConfigAdapter implements ConfigService {
            'memory',
            'sources',
            'credentials',
+            // User-authored fleet data MUST survive `mosaic update`'s re-seed.
+            // The framework seeds only fleet/examples + fleet/roles +
+            // fleet/roster.schema.json; the operator's roster, per-agent env, and
+            // heartbeat run dir stay user-owned. (Mirror of install.sh PRESERVE_PATHS.)
+            'fleet/*.yaml',
+            'fleet/agents',
+            'fleet/run',
          ]
        : [];

--- a/packages/mosaic/src/fleet/comms-onboarding.spec.ts
+++ b/packages/mosaic/src/fleet/comms-onboarding.spec.ts
@@ -48,9 +48,9 @@ describe('parseRosterAgents', () => {

  it('parses an optional per-agent socket', () => {
    const peers = parseRosterAgents(
-      ['agents:', '  - name: a', '    class: worker', '    socket: mosaic-factory'].join('\n'),
+      ['agents:', '  - name: a', '    class: worker', '    socket: mosaic-fleet'].join('\n'),
    );
-    expect(peers[0]).toMatchObject({ name: 'a', socket: 'mosaic-factory' });
+    expect(peers[0]).toMatchObject({ name: 'a', socket: 'mosaic-fleet' });
  });

  it('stops at the next top-level key', () => {
@@ -99,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-factory' };
+    const peer: CommsPeer = { name: 'coder0', className: 'implementer', socket: 'mosaic-fleet' };
    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
-      `${send} -L mosaic-factory -s coder0 -m "…"`,
+      `${send} -L mosaic-fleet -s coder0 -m "…"`,
    );
  });

@@ -111,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-factory',
+      socket: 'mosaic-fleet',
    };
    expect(renderPeerReach(peer, 'w-jarvis', send)).toBe(
-      `${send} -L mosaic-factory -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`,
+      `${send} -L mosaic-fleet -H jwoltje@10.1.10.37 -s coder0-0 -m "…"`,
    );
  });
 });
--- a/packages/mosaic/src/runtime/update-checker.reseed.spec.ts
+++ b/packages/mosaic/src/runtime/update-checker.reseed.spec.ts
@@ -7,7 +7,9 @@ import {
  buildRelaunchCommands,
  readRosterAgentNames,
  runFrameworkReseed,
+  refreshActiveFleetUnits,
 } from './update-checker.js';
+import { existsSync, readFileSync } from 'node:fs';

 /**
 * F3-m3 / R13: `mosaic update` re-seeds the framework + (opt-in) relaunches
@@ -83,3 +85,41 @@ describe('runFrameworkReseed', () => {
    rmSync(missing, { recursive: true, force: true });
  });
 });
+
+describe('refreshActiveFleetUnits', () => {
+  let root: string;
+  let mosaicHome: string;
+  let configHome: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'mosaic-units-'));
+    mosaicHome = join(root, 'mosaic');
+    configHome = join(root, 'config');
+    mkdirSync(join(mosaicHome, 'systemd', 'user'), { recursive: true });
+    mkdirSync(join(configHome, 'systemd', 'user'), { recursive: true });
+    // Freshly re-seeded units (new content).
+    writeFileSync(join(mosaicHome, 'systemd', 'user', 'mosaic-agent@.service'), 'NEW\n');
+    writeFileSync(join(mosaicHome, 'systemd', 'user', 'mosaic-tmux-holder.service'), 'NEW\n');
+  });
+  afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+  it('refreshes active units when a fleet is already installed', () => {
+    // Active dir already carries mosaic units (stale) → fleet is installed.
+    writeFileSync(join(configHome, 'systemd', 'user', 'mosaic-agent@.service'), 'OLD\n');
+    const res = refreshActiveFleetUnits(mosaicHome, {
+      XDG_CONFIG_HOME: configHome,
+    } as NodeJS.ProcessEnv);
+    expect(res.refreshed).toContain('mosaic-agent@.service');
+    expect(
+      readFileSync(join(configHome, 'systemd', 'user', 'mosaic-agent@.service'), 'utf-8'),
+    ).toBe('NEW\n');
+  });
+
+  it('is a no-op when no fleet is installed (active dir has no mosaic units)', () => {
+    const res = refreshActiveFleetUnits(mosaicHome, {
+      XDG_CONFIG_HOME: configHome,
+    } as NodeJS.ProcessEnv);
+    expect(res.refreshed).toEqual([]);
+    expect(existsSync(join(configHome, 'systemd', 'user', 'mosaic-agent@.service'))).toBe(false);
+  });
+});
--- a/packages/mosaic/src/runtime/update-checker.ts
+++ b/packages/mosaic/src/runtime/update-checker.ts
@@ -14,7 +14,14 @@
 */

 import { execSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  copyFileSync,
+} from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -536,6 +543,47 @@ export function readRosterAgentNames(mosaicHome = join(homedir(), '.config', 'mo
  return names;
 }

+/**
+ * Refresh the ACTIVE systemd user units from the freshly re-seeded copies.
+ *
+ * The re-seed updates `~/.config/mosaic/systemd/user/*.service`, but the units
+ * systemd actually runs live at `~/.config/systemd/user/`. Without this copy,
+ * shipped unit fixes (e.g. the socket-env change) never take effect after
+ * `mosaic update` until `mosaic fleet install` is re-run. Best-effort + scoped:
+ * only refreshes when a fleet is already installed (the active dir already
+ * carries `mosaic-*` units), so non-fleet hosts are untouched.
+ */
+export function refreshActiveFleetUnits(
+  mosaicHome = join(homedir(), '.config', 'mosaic'),
+  env: NodeJS.ProcessEnv = process.env,
+): { refreshed: string[]; ok: boolean; reason?: string } {
+  const src = join(mosaicHome, 'systemd', 'user');
+  const configHome = env['XDG_CONFIG_HOME'] ?? join(homedir(), '.config');
+  const dest = join(configHome, 'systemd', 'user');
+  if (!existsSync(src)) return { refreshed: [], ok: true };
+  // Only refresh when a fleet is already installed (active dir has mosaic units).
+  const fleetInstalled =
+    existsSync(dest) &&
+    readdirSync(dest).some((f) => f.startsWith('mosaic-') && f.endsWith('.service'));
+  if (!fleetInstalled) return { refreshed: [], ok: true };
+  const units = readdirSync(src).filter((f) => f.startsWith('mosaic-') && f.endsWith('.service'));
+  const refreshed: string[] = [];
+  for (const unit of units) {
+    try {
+      copyFileSync(join(src, unit), join(dest, unit));
+      refreshed.push(unit);
+    } catch {
+      // best-effort per unit
+    }
+  }
+  try {
+    execSync('systemctl --user daemon-reload', { stdio: 'ignore', timeout: 15_000 });
+  } catch {
+    // non-systemd host or no session bus — non-fatal
+  }
+  return { refreshed, ok: true };
+}
+
 /** Build the per-agent systemd relaunch commands (drain+relaunch via restart). */
 export function buildRelaunchCommands(agentNames: string[]): string[][] {
  return agentNames.map((name) => [
Author	SHA1	Message	Date
Jarvis	9da71bd861	ci: switch pipelines to pre-baked ci-base image (consumer) [Phase 1b] Some checks failed ci/woodpecker/push/ci Pipeline failed Details ci/woodpecker/pr/ci Pipeline was successful Details Consumer half of the Woodpecker CI cache work (#634). Re-scoped from the original combined change: the image recipe (Dockerfile.ci, ci-image.yml) now lives in the producer PR #637. This branch only flips the consumers. - ci.yml / publish.yml: pull git.mosaicstack.dev/mosaicstack/stack/ci-base :latest for the install step and resolve from the baked pnpm store via --prefer-offline (drops the per-run apk add + cold network fetch). - framework monorepo template: single cached install instead of npm ci per step, so scaffolded repos inherit the fix. B2 fix (blocker): pin store-dir in root .npmrc to /root/.local/share/pnpm/store — the exact path Dockerfile.ci warms — so the pipeline install actually consumes the baked store instead of repopulating a fresh one. The existing @mosaicstack registry line is preserved. BLOCKED ON: PR #637 merge + a manual ci-image prime of ci-base:latest on main. Until the image is primed this branch's CI is red (it pulls an image that does not exist yet). Do not merge until a green re-run after priming. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-22 16:50:39 -05:00
Jason Woltje	bf2a6745c8	fix(install): preserve user fleet data on re-seed + refresh active units (CRITICAL) (#632 ) All checks were successful ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>	2026-06-22 21:38:09 +00:00
Jason Woltje	d539d61e0e	refactor(fleet): rename tmux socket mosaic-factory → mosaic-fleet (#630 ) All checks were successful ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>	2026-06-22 21:08:43 +00:00
Jason Woltje	3f69d45334	docs(fleet): consolidate north-star doctrine (budget + control plane + identity) (#629 ) Some checks failed ci/woodpecker/push/publish Pipeline was canceled Details ci/woodpecker/push/ci Pipeline was canceled Details Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>	2026-06-22 21:08:41 +00:00
jason.woltje	e2336bb0ca	chore(release): mosaic CLI 0.0.40 (#624 ) All checks were successful ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details	2026-06-22 19:49:45 +00:00