fix(fleet): export MOSAIC_AGENT_CLASS into the agent pane so personas inject

A3a/A3b ship a per-agent persona contract that the launcher composes from
process.env.MOSAIC_AGENT_CLASS (compose-contract -> readPersonaContractBlock,
launch.js). generateAgentEnv already writes MOSAIC_AGENT_CLASS to
agents/<name>.env, but start-agent-session.sh only re-exported
MOSAIC_AGENT_NAME into the pane snippet — never the class.

The pane inherits the tmux SERVER environment, not this script's env nor the
systemd unit's EnvironmentFile, so the class set in the .env was invisible
in-pane. The launcher then saw an undefined class and silently injected NO
persona contract: every fleet agent came up class-less while `fleet ps`
reported healthy. The comms block kept working only because it keys on
MOSAIC_AGENT_NAME (which IS re-exported).

Fix: re-export MOSAIC_AGENT_CLASS into PANE_SHELL_SNIPPET exactly as
MOSAIC_AGENT_NAME, %q-quoted (empty/unset class -> '' is a harmless no-op,
matching readPersonaContractBlock's empty-class contract). Verified live: a
relaunched agent now carries MOSAIC_AGENT_CLASS in its pane env and the
matching `# Persona Contract (<class>)` block in its composed prompt.

Adds a regression guard to test-start-agent-session.sh asserting the pane
snippet exports both MOSAIC_AGENT_NAME and the per-agent MOSAIC_AGENT_CLASS.

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

docs/fleet/NORTH_STAR.md

@@ -7,7 +7,7 @@
 
 ## Mission
 
-A self-driving Mosaic delivery fleet that 24/7 unattended converts a machine-readable goal set into merged, CI-green, budget-bounded change — looping plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN native backlog/dispatch engine.
+A self-driving Mosaic system that 24/7 unattended converts a machine-readable goal set into merged, CI-green, budget-bounded change — looping plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN native backlog/dispatch engine. Mosaic is general-purpose: the user declares the system type they want (software delivery, personal assistant, research, business/operations, …) and the orchestrator provisions the matching persona roster and structure; the delivery fleet is one profile among many.
 
 ## Substrate
 
@@ -23,6 +23,7 @@ The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's
 - **NS-6** — Context cleared between tasks for ephemeral runners (reset_between_tasks); persona+mission re-injected per task.
 - **NS-7** — Meta-loop (session-review + enhancer) continuously proposes small fleet-improvement PRs.
 - **NS-8** — Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored before every dispatch and every merge.
+- **NS-9** — Mosaic is a general-purpose multi-agent system: the user declares the SYSTEM TYPE to run (e.g. software delivery, personal assistant, research, business/operations) and the orchestrator provisions the matching persona roster and org structure from a cross-domain baseline persona library; the delivery/coding fleet is one profile among many.
 
 ## Success criteria
 
@@ -31,38 +32,46 @@ The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's
 - **AC-NS-3** — No PR merges with failure/error/no-status/timeout CI, and none bypass pr-merge.sh.
 - **AC-NS-4** — TTL is enforced on claims; token caps remain advisory until a real meter exists.
 - **AC-NS-5** — Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
+- **AC-NS-6** — A user can declare a system type and the fleet provisions the matching persona roster + topology from the baseline library, with no code change.
+- **AC-NS-7** — A user-customized persona (edited or added via the orchestrator) survives `mosaic update`: baseline reseed never clobbers user overrides.
 
 ## Workstreams
 
-| id  | title                                                            |
-| --- | ---------------------------------------------------------------- |
-| A   | Substrate — Mosaic Backlog on native Postgres storage service    |
-| B   | Supervisor — movement guarantee, two-agent floor, dispatch/claim |
-| C   | Planner — goal decomposition into independently-shippable cards  |
-| D   | Merge-gate — single approver, pr-merge.sh after CI wait          |
-| E   | Meta-loop — session-review + enhancer improvement PRs            |
-| F   | Safety-rails — TTL claims, advisory spend, PAUSE kill-switch     |
+| id  | title                                                                                                       |
+| --- | ----------------------------------------------------------------------------------------------------------- |
+| A   | Substrate — Mosaic Backlog on native Postgres storage service                                               |
+| B   | Supervisor — movement guarantee, two-agent floor, dispatch/claim                                            |
+| C   | Planner — goal decomposition into independently-shippable cards                                             |
+| D   | Merge-gate — single approver, pr-merge.sh after CI wait                                                     |
+| E   | Meta-loop — session-review + enhancer improvement PRs                                                       |
+| F   | Safety-rails — TTL claims, advisory spend, PAUSE kill-switch                                                |
+| H   | Personas & system profiles — cross-domain library, system-type provisioning, update-surviving customization |
 
 ## Goals (backlog projection)
 
-| id  | title                                                                  | phase | priority    | depends_on |
-| --- | ---------------------------------------------------------------------- | ----- | ----------- | ---------- |
-| A1  | Machine-readable NORTH_STAR.yaml + Markdown projection                 | 1     | must-have   | —          |
-| A2  | Mosaic Backlog schema + storage-service card store (drizzle/PGlite)    | 1     | must-have   | A1         |
-| A3a | Card lifecycle — create/claim/release with stable ids + depends_on DAG | 1     | must-have   | A2         |
-| A3b | TTL-bounded claim enforcement (wall-clock) on cards                    | 1     | must-have   | A3a        |
-| A4  | Advisory spend projection per card (degrades to TTL, no real meter)    | 1     | should-have | A3a        |
-| B1  | Supervisor tick — readiness scan, two-agent-floor health check         | 2     | must-have   | A3a        |
-| B2  | Native dispatch/claim — assign ready dependency-satisfied work         | 2     | must-have   | A3b, B1    |
-| B3a | Planner decompose — goal added to YAML → cards                         | 2     | must-have   | A2, B1     |
-| B3b | Replan request on empty backlog; escalate on no-decompose              | 2     | should-have | B3a        |
-| G1  | PAUSE kill-switch + merge-gate honored before dispatch and merge       | 2     | must-have   | B2         |
+| id  | title                                                                                                                                             | phase | priority    | depends_on |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ----------- | ---------- |
+| A1  | Machine-readable NORTH_STAR.yaml + Markdown projection                                                                                            | 1     | must-have   | —          |
+| A2  | Mosaic Backlog schema + storage-service card store (drizzle/PGlite)                                                                               | 1     | must-have   | A1         |
+| A3a | Card lifecycle — create/claim/release with stable ids + depends_on DAG                                                                            | 1     | must-have   | A2         |
+| A3b | TTL-bounded claim enforcement (wall-clock) on cards                                                                                               | 1     | must-have   | A3a        |
+| A4  | Advisory spend projection per card (degrades to TTL, no real meter)                                                                               | 1     | should-have | A3a        |
+| B1  | Supervisor tick — readiness scan, two-agent-floor health check                                                                                    | 2     | must-have   | A3a        |
+| B2  | Native dispatch/claim — assign ready dependency-satisfied work                                                                                    | 2     | must-have   | A3b, B1    |
+| B3a | Planner decompose — goal added to YAML → cards                                                                                                    | 2     | must-have   | A2, B1     |
+| B3b | Replan request on empty backlog; escalate on no-decompose                                                                                         | 2     | should-have | B3a        |
+| G1  | PAUSE kill-switch + merge-gate honored before dispatch and merge                                                                                  | 2     | must-have   | B2         |
+| H1  | Cross-domain baseline persona library (exec, marketing, ops, research, assistant + engineering roles)                                             | 1     | must-have   | A1         |
+| H2  | System-type profiles — declarative mapping of system type to persona roster + topology                                                            | 2     | must-have   | H1         |
+| H3  | System-type provisioning — user declares type; orchestrator instantiates the matching roster + structure                                          | 2     | must-have   | H2         |
+| H4  | Update-surviving persona customization — ad-hoc edits/additions persisted in a PRESERVE-protected override layer (baseline merged with overrides) | 2     | must-have   | H1         |
 
 ## Assumptions (vetoable)
 
 - **ASM-1** (vetoable) — The Mosaic Backlog on the native Postgres storage service is the backlog of record.
 - **ASM-2** (vetoable) — Claude gate roles have no native busy status, so readiness = pane-idle + heartbeat.
 - **ASM-3** (vetoable) — Two-agent floor = 1 orchestrator + >=1 enhancer.
+- **ASM-4** (vetoable) — Baseline personas ship in framework/fleet/roles/ (reseeded on update); user overrides live in a separate PRESERVE_PATHS-protected layer and win on merge.
 
 ## Spend
 

docs/fleet/NORTH_STAR.yaml

@@ -12,10 +12,13 @@
 version: 1
 
 mission: >-
-  A self-driving Mosaic delivery fleet that 24/7 unattended converts a
-  machine-readable goal set into merged, CI-green, budget-bounded change —
-  looping plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN
-  native backlog/dispatch engine.
+  A self-driving Mosaic system that 24/7 unattended converts a machine-readable
+  goal set into merged, CI-green, budget-bounded change — looping
+  plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN native
+  backlog/dispatch engine. Mosaic is general-purpose: the user declares the
+  system type they want (software delivery, personal assistant, research,
+  business/operations, …) and the orchestrator provisions the matching persona
+  roster and structure; the delivery fleet is one profile among many.
 
 substrate:
   note: >-
@@ -59,6 +62,13 @@ standing_objectives:
     text: >-
       Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored
       before every dispatch and every merge.
+  - id: NS-9
+    text: >-
+      Mosaic is a general-purpose multi-agent system: the user declares the
+      SYSTEM TYPE to run (e.g. software delivery, personal assistant, research,
+      business/operations) and the orchestrator provisions the matching persona
+      roster and org structure from a cross-domain baseline persona library; the
+      delivery/coding fleet is one profile among many.
 
 success_criteria:
   - id: AC-NS-1
@@ -80,6 +90,14 @@ success_criteria:
   - id: AC-NS-5
     text: >-
       Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
+  - id: AC-NS-6
+    text: >-
+      A user can declare a system type and the fleet provisions the matching
+      persona roster + topology from the baseline library, with no code change.
+  - id: AC-NS-7
+    text: >-
+      A user-customized persona (edited or added via the orchestrator) survives
+      `mosaic update`: baseline reseed never clobbers user overrides.
 
 workstreams:
   - id: A
@@ -94,6 +112,8 @@ workstreams:
     title: Meta-loop — session-review + enhancer improvement PRs
   - id: F
     title: Safety-rails — TTL claims, advisory spend, PAUSE kill-switch
+  - id: H
+    title: Personas & system profiles — cross-domain library, system-type provisioning, update-surviving customization
 
 goals:
   - id: A1
@@ -146,6 +166,26 @@ goals:
     phase: 2
     priority: must-have
     depends_on: [B2]
+  - id: H1
+    title: Cross-domain baseline persona library (exec, marketing, ops, research, assistant + engineering roles)
+    phase: 1
+    priority: must-have
+    depends_on: [A1]
+  - id: H2
+    title: System-type profiles — declarative mapping of system type to persona roster + topology
+    phase: 2
+    priority: must-have
+    depends_on: [H1]
+  - id: H3
+    title: System-type provisioning — user declares type; orchestrator instantiates the matching roster + structure
+    phase: 2
+    priority: must-have
+    depends_on: [H2]
+  - id: H4
+    title: Update-surviving persona customization — ad-hoc edits/additions persisted in a PRESERVE-protected override layer (baseline merged with overrides)
+    phase: 2
+    priority: must-have
+    depends_on: [H1]
 
 assumptions:
   - id: ASM-1
@@ -161,6 +201,12 @@ assumptions:
   - id: ASM-3
     vetoable: true
     text: 'Two-agent floor = 1 orchestrator + >=1 enhancer.'
+  - id: ASM-4
+    vetoable: true
+    text: >-
+      Baseline personas ship in framework/fleet/roles/ (reseeded on update);
+      user overrides live in a separate PRESERVE_PATHS-protected layer and win
+      on merge.
 
 spend:
   advisory: true

docs/fleet/north-star.md

@@ -353,6 +353,25 @@ re-evaluate if isolation or write-volume demands it.
 - **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.
 
+## Decisions of record (2026-06-24, with Jason)
+
+- **Per-agent model switch (operator-configurable, NOT a global lock):** model selection is
+  **per-agent**, never a host-global pin. Claude sessions MUST NOT be locked to a single model in
+  `~/.claude/settings.json`; each agent chooses its model independently. The plumbing already exists —
+  roster `model_hint` → `MOSAIC_AGENT_MODEL` → `start-agent-session.sh` appends `--model <hint>` to that
+  agent's harness (claude or pi); settable today via `mosaic fleet add|edit <agent> --model <hint>`.
+  **North-star target:** surface this as a **per-agent model switch in the webUI** (with CLI/TUI parity
+  per MVP-X1) — read the roster, expose a per-agent model dropdown, write `model_hint` back, and restart
+  that one agent to apply. Unset = inherit the harness default. This **composes with** the budget
+  downgrade ladder (opus → sonnet → haiku, then Claude → Codex): the operator sets the per-agent model
+  _intent/ceiling_; budget pacing may downgrade within policy. Tracked as a Fleet `TASKS.md` entry under
+  the Phase-5 webUI surface.
+- **Orchestrator runtime (confirmed live):** the **orchestrator and enhancer run Claude Opus 4.8 in the
+  Claude Code harness**; only workers (coder/reviewer) run pi/gpt-5.5. Consistent with the 2026-06-20
+  "Claude reserved for Claude Code only" decision (the orchestrator runs _in_ Claude Code, not an
+  alternate Claude harness). Pi/gpt-5.5 as the orchestrator is permitted **only if proven** at least as
+  satisfactory; absent that proof, the orchestrator stays on Claude Opus 4.8.
+
 ## Future enhancements (north-star, post-MVP — not on the MVP track)
 
 - **Mosaic Claude Discord Plugin** — a first-party Mosaic Discord connector that properly

packages/db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicstack/db",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",

packages/mosaic/framework/fleet/profiles/business.yaml

@@ -0,0 +1,30 @@
+id: business
+title: Business (Company-in-a-Box)
+description: >-
+  A full company org: the CEO sets direction, the COO and CFO run execution and
+  finance, and the functional leads (product, marketing, sales, operations,
+  customer success) plus a small engineering slice deliver the work. reports_to
+  encodes the org chart.
+lead: ceo
+floor:
+  - ceo
+roster:
+  - class: ceo
+  - class: coo
+    reports_to: ceo
+  - class: cfo
+    reports_to: ceo
+  - class: product-manager
+    reports_to: coo
+  - class: marketing-lead
+    reports_to: coo
+  - class: sales-lead
+    reports_to: coo
+  - class: operations-manager
+    reports_to: coo
+  - class: customer-success-manager
+    reports_to: coo
+  - class: code
+    reports_to: product-manager
+  - class: review
+    reports_to: product-manager

packages/mosaic/framework/fleet/profiles/marketing.yaml

@@ -0,0 +1,25 @@
+id: marketing
+title: Marketing
+description: >-
+  A marketing org that owns strategy, content, channels, and growth. The
+  marketing-lead sets strategy and budget and runs a roster of content, copy,
+  SEO, social, brand, growth, and UX specialists.
+lead: marketing-lead
+floor:
+  - marketing-lead
+roster:
+  - class: marketing-lead
+  - class: content-strategist
+    reports_to: marketing-lead
+  - class: copywriter
+    reports_to: content-strategist
+  - class: seo-specialist
+    reports_to: marketing-lead
+  - class: social-media-manager
+    reports_to: content-strategist
+  - class: brand-strategist
+    reports_to: marketing-lead
+  - class: growth-marketer
+    reports_to: marketing-lead
+  - class: ux-designer
+    reports_to: marketing-lead

packages/mosaic/framework/fleet/profiles/personal-assistant.yaml

@@ -0,0 +1,19 @@
+id: personal-assistant
+title: Personal Assistant
+description: >-
+  A personal-logistics fleet for one principal: handles errands, reminders,
+  calendar, inbox triage, and ad-hoc lookups. The personal-assistant leads and
+  delegates scheduling, inbox triage, and research to specialist seats.
+lead: personal-assistant
+floor:
+  - personal-assistant
+roster:
+  - class: personal-assistant
+  - class: executive-assistant
+    reports_to: personal-assistant
+  - class: scheduler
+    reports_to: executive-assistant
+  - class: inbox-manager
+    reports_to: personal-assistant
+  - class: researcher
+    reports_to: personal-assistant

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

@@ -0,0 +1,24 @@
+id: research
+title: Research
+description: >-
+  A research fleet that decomposes a question, gathers and analyzes evidence, and
+  synthesizes cited findings. The lead-researcher owns the agenda and assigns
+  individual questions to researchers and the analytics seats.
+lead: lead-researcher
+floor:
+  - lead-researcher
+roster:
+  - class: lead-researcher
+  - class: researcher
+    reports_to: lead-researcher
+    multiplicity: 2
+  - class: data-analyst
+    reports_to: lead-researcher
+  - class: data-scientist
+    reports_to: lead-researcher
+  - class: market-analyst
+    reports_to: lead-researcher
+  - class: documentation
+    reports_to: lead-researcher
+  - class: review
+    reports_to: lead-researcher

packages/mosaic/framework/fleet/profiles/software-delivery.yaml

@@ -0,0 +1,75 @@
+# Mosaic system-type profile — SCHEMA REFERENCE
+# ---------------------------------------------------------------------------
+# A profile is a DECLARATIVE mapping from a "system type" to a persona roster
+# plus its org topology. Profiles are DATA: drop a new <id>.yaml here and the
+# loader/CLI pick it up with no code change (North Star NS-9 / AC-NS-6).
+#
+# Every persona referenced below (lead, floor[], roster[].class, roster[].reports_to)
+# MUST resolve to a real persona in the library. The loader validates this against
+# the role contracts in ../roles/*.md (see LIBRARY.md for the grouped index).
+#
+# Schema (this file documents every key; other profiles omit the comments):
+#
+#   id:           kebab-case system-type id — MUST equal the filename stem.
+#   title:        human-readable name.
+#   description:  one paragraph — what this system does.
+#   lead:         persona class that coordinates the roster (the orchestrating seat).
+#   floor:        persistent minimum roster that must stay staffed (list of classes).
+#   roster:       the full default roster. Each entry:
+#                   - class:        persona class (MUST resolve to a role file).
+#                     reports_to:   optional — the class this seat reports to
+#                                   (encodes org topology). Omit for the lead.
+#                                   MUST resolve to a class present in this roster.
+#                     multiplicity: optional int (default 1) — e.g. 2 coders.
+#   notes:        optional free text.
+# ---------------------------------------------------------------------------
+id: software-delivery
+title: Software Delivery
+description: >-
+  The engineering fleet that turns ratified objectives into shipped, reviewed,
+  merged code. The lead (orchestrator) runs the supervisor loop and dispatches
+  ready work; it hands goal-decomposition to the planner, which plans phased FRs
+  into a depends_on DAG, decomposition splits them into one-PR-each cards, coders
+  execute to green CI, and review / security-review / site-tester / merge-gate
+  guard the merge. This mirrors today's coding fleet.
+# NOTE: the lead seat is the dedicated "orchestrator" — the always-on coordinator
+# that runs the supervisor tick, dispatches ready work, and routes PRs to the
+# merge-gate while holding only lean coordination state. The planner is now a
+# distinct seat (heavy goal-decomposition context) that reports to the
+# orchestrator. The two-agent floor is orchestrator + enhancer.
+lead: orchestrator
+floor:
+  - orchestrator
+  - enhancer
+roster:
+  - class: orchestrator
+  - class: board
+    reports_to: orchestrator
+  - class: planner
+    reports_to: orchestrator
+  - class: decomposition
+    reports_to: planner
+  - class: code
+    reports_to: decomposition
+    multiplicity: 2
+  - class: review
+    reports_to: orchestrator
+  - class: security-review
+    reports_to: review
+  - class: site-tester
+    reports_to: review
+  - class: documentation
+    reports_to: orchestrator
+  - class: merge-gate
+    reports_to: orchestrator
+  - class: rebase
+    reports_to: merge-gate
+  - class: operator
+    reports_to: orchestrator
+  - class: session-review
+    reports_to: orchestrator
+  - class: enhancer
+    reports_to: orchestrator
+notes: >-
+  Two-agent floor (orchestrator + enhancer) is always staffed; every other seat is
+  added on demand.

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

@@ -19,6 +19,7 @@ their intro so tooling can group them.
 
 | Persona         | Purpose                                                                        |
 | --------------- | ------------------------------------------------------------------------------ |
+| orchestrator    | Always-on coordinator — runs the supervisor loop, dispatches ready work        |
 | board           | Multi-lens deliberation panel; owns the mission's direction, not its execution |
 | planner         | Turns ratified objectives into a phased FR plan wired into a `depends_on` DAG  |
 | decomposition   | Splits FRs into one-PR-each cards wired with `depends_on` edges                |

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

@@ -0,0 +1,46 @@
+# Orchestrator — fleet role definition
+
+The **orchestrator** is one half of the fleet's two-agent floor: every fleet runs,
+at minimum, an **orchestrator** and an **enhancer**. The orchestrator is the
+fleet's **always-on coordinator and dispatcher** (`class: orchestrator`,
+`persistent_persona: true`) — it owns fleet _movement_, not the work itself.
+
+It is a **core, always-on** agent, not an ephemeral per-lane worker.
+
+## Mandate
+
+1. **Run the supervisor tick** — perform the readiness scan each loop and keep the
+   two-agent floor (orchestrator + enhancer) healthy, restoring it the moment it
+   drops below the floor.
+2. **Dispatch ready work** — pick up cards whose `depends_on` edges are satisfied
+   and assign them via the backlog/claim, so no idle agent sits while ready work
+   exists.
+3. **Delegate decomposition, don't do it** — hand goal-decomposition work to the
+   **planner**, which it coordinates; the orchestrator tracks the resulting plan
+   but does not author the DAG itself.
+4. **Route PRs to the merge-gate** — push reviewed, ready-to-land PRs at the
+   **merge-gate** (the only merge path); it never approves or merges itself.
+5. **Interface with the operator/user** — be the fleet's coordination surface,
+   relaying status and accepting direction, while holding only coordination state.
+6. **Keep the loop turning** — re-dispatch on completion or failure so the fleet
+   keeps moving rather than stalling.
+
+## Boundaries
+
+- **Does NOT decompose goals into the DAG/cards** — that is the **planner**'s lane,
+  which the orchestrator dispatches to.
+- **Does NOT write product/source code** (coders), **review** (review), or
+  **approve merges itself** (merge-gate).
+- **Does NOT carry deep per-task context** — it delegates and tracks, keeping its
+  own context lean so the coordination loop stays fast.
+
+The orchestrator moves work; it never holds the heavy planning or execution
+context that the seats it dispatches to carry.
+
+## Persona
+
+A lean, decisive coordinator. It thinks in readiness and throughput, dispatches the
+next ready card the instant a dependency clears, and never lets an idle agent sit
+while ready work exists — keeping its own context minimal so the loop never slows.
+
+> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).

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

@@ -3,11 +3,11 @@
 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.
+> **Reports to the orchestrator.** The planner is the goal-decomposition seat that
+> the **orchestrator** dispatches planning work to; it carries the heavy
+> goal-decomposition context, while the orchestrator holds only the lean
+> coordination state. The two-agent floor is **orchestrator + enhancer** — the
+> planner is added on demand, not part of the floor.
 
 It is a **front-office** role.
 
@@ -19,8 +19,8 @@ It is a **front-office** role.
    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.
+4. **Re-plan on failure** — when execution diverges, the planner re-sequences the
+   DAG rather than letting agents improvise.
 
 ## Boundaries
 
@@ -35,6 +35,7 @@ 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.
+a clean DAG to decomposition, and reports its plan back to the orchestrator that
+dispatched it.
 
 > Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).

packages/mosaic/framework/install.sh

@@ -24,9 +24,11 @@ INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 # reconcile_framework_files (overwrite + backup-once); the rest stay user-owned.
 # User-created content in these paths survives rsync --delete.
 #
-# fleet/* — the framework SEEDS only fleet/examples, fleet/roles, and
+# fleet/* — the framework SEEDS fleet/examples, fleet/roles, fleet/profiles, 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
+# and fleet/profiles/*.yaml system-type profile lands automatically via this sync,
+# so no per-file entry is needed; the preserved "fleet/*.yaml" glob is anchored to
+# the top level only and does NOT shadow fleet/profiles/*.yaml). 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
@@ -35,7 +37,14 @@ INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 # packages/mosaic/src/commands/fleet-backlog.ts). Without these, an update
 # wipes the operator's fleet AND their backlog. Glob entries are honored by
 # both the rsync path (`--exclude`) and the glob-aware cp fallback below.
-PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials" "fleet/*.yaml" "fleet/agents" "fleet/run" "fleet/backlog")
+#
+# fleet/roles.local — the persona OVERRIDE layer (H4). Baseline personas in
+# fleet/roles/ are reseeded normally on every update (delivering new baseline
+# personas), so any local edit there would be clobbered. User customizations
+# and user-ADDED personas instead live in fleet/roles.local/ and MUST survive
+# `mosaic update` — they win over the baseline on merge (AC-NS-7; see
+# packages/mosaic/src/commands/fleet-personas.ts).
+PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials" "fleet/*.yaml" "fleet/agents" "fleet/run" "fleet/backlog" "fleet/roles.local")
 
 # 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).

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

@@ -114,10 +114,21 @@ MOSAIC_RUNTIME_BIN_PREFIX=$(_build_runtime_bin_prefix)
 # safe single bash token regardless of the name's characters.
 AGENT_NAME_Q=$(printf '%q' "$AGENT_NAME")
 
+# MOSAIC_AGENT_CLASS must ALSO be exported INTO the pane, for the same reason as
+# MOSAIC_AGENT_NAME above: the pane inherits the tmux SERVER environment (not this
+# script's env, and not the systemd unit's EnvironmentFile), so the per-agent class
+# written to agents/<name>.env would otherwise be invisible in-pane. The launcher
+# composes the persona contract from process.env.MOSAIC_AGENT_CLASS at launch
+# (compose-contract -> readPersonaContractBlock); without this export it sees an
+# undefined class and silently injects NO persona contract. %q-quote it so it is a
+# safe single bash token; an empty/unset class %q-quotes to '' and is a harmless
+# no-op downstream (readPersonaContractBlock returns '' for an empty class).
+AGENT_CLASS_Q=$(printf '%q' "${MOSAIC_AGENT_CLASS:-}")
+
 if [ -n "$MOSAIC_RUNTIME_BIN_PREFIX" ]; then
-  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}"
+  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export MOSAIC_AGENT_CLASS=${AGENT_CLASS_Q}; export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}"
 else
-  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; exec ${MOSAIC_AGENT_COMMAND}"
+  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export MOSAIC_AGENT_CLASS=${AGENT_CLASS_Q}; exec ${MOSAIC_AGENT_COMMAND}"
 fi
 
 mkdir -p "$MOSAIC_AGENT_WORKDIR"

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

@@ -104,6 +104,7 @@ PATH="$FAKE_BIN:$PATH" \
 MOSAIC_TMUX_SOCKET="$SOCKET3" \
 MOSAIC_AGENT_WORKDIR="$WORKDIR3" \
 MOSAIC_AGENT_RUNTIME="pi" \
+MOSAIC_AGENT_CLASS="code" \
 MOSAIC_RUNTIME_BIN="$FAKE_RUNTIME_BIN" \
 MOSAIC_AGENT_COMMAND="mosaic yolo pi --model openai-codex/gpt-5.5:high" \
 MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR3" \
@@ -127,6 +128,18 @@ echo "$all_args" | grep -qF "exec " || fail "pane command does not use exec"
 echo "$all_args" | grep -qF "mosaic yolo pi --model openai-codex/gpt-5.5:high" || \
   fail "pane command does not forward MOSAIC_AGENT_COMMAND with flags intact"
 
+# d) MOSAIC_AGENT_NAME and the per-agent MOSAIC_AGENT_CLASS must BOTH be exported
+#    INTO the pane. The pane inherits the tmux SERVER environment (not this
+#    script's env, nor the systemd unit's EnvironmentFile), so any per-agent var
+#    the launcher needs in-pane must be re-exported in the snippet. CLASS is
+#    load-bearing: the launcher composes the persona contract from
+#    process.env.MOSAIC_AGENT_CLASS, so a missing export silently drops the
+#    persona (regression guard for the A3a pane-propagation gap).
+echo "$all_args" | grep -qF "export MOSAIC_AGENT_NAME=" || \
+  fail "pane command does not export MOSAIC_AGENT_NAME into the pane"
+echo "$all_args" | grep -qF "export MOSAIC_AGENT_CLASS=code" || \
+  fail "pane command does not export MOSAIC_AGENT_CLASS into the pane (persona would silently drop)"
+
 # ── Test 4: when no extra runtime-bin dirs exist, exec still appears ───────────
 TMUX_ARGS_FILE2=$(mktemp)
 FAKE_BIN2=$(mktemp -d)

packages/mosaic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicstack/mosaic",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",

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

@@ -164,4 +164,89 @@ describe('composeContract — overlay composer', () => {
     expect(composeContract('pi', fixture.home)).toContain('# pi runtime contract');
     expect(composeContract('codex', fixture.home)).not.toContain('# pi runtime contract');
   });
+
+  // ── Persona contract injection (A3b) ──────────────────────────────────────
+  // composeContract reads MOSAIC_AGENT_CLASS and injects the resolved persona
+  // (override-aware). Save/restore the env so these tests don't leak state.
+  describe('persona contract (A3b)', () => {
+    let prevClass: string | undefined;
+
+    beforeEach(() => {
+      prevClass = process.env['MOSAIC_AGENT_CLASS'];
+    });
+
+    afterEach(() => {
+      if (prevClass === undefined) delete process.env['MOSAIC_AGENT_CLASS'];
+      else process.env['MOSAIC_AGENT_CLASS'] = prevClass;
+    });
+
+    const seedBaseline = (klass: string, body: string): void => {
+      mkdirSync(join(fixture.home, 'fleet', 'roles'), { recursive: true });
+      writeFileSync(join(fixture.home, 'fleet', 'roles', `${klass}.md`), body);
+    };
+    const seedOverride = (klass: string, body: string): void => {
+      mkdirSync(join(fixture.home, 'fleet', 'roles.local'), { recursive: true });
+      writeFileSync(join(fixture.home, 'fleet', 'roles.local', `${klass}.md`), body);
+    };
+
+    it('injects the baseline persona when MOSAIC_AGENT_CLASS is set and a role file exists', () => {
+      seedBaseline('coder', '# Coder\n\n(`class: coder`)\n\nBASELINE-MANDATE: ship the lane.\n');
+      process.env['MOSAIC_AGENT_CLASS'] = 'coder';
+      const out = composeContract('claude', fixture.home);
+      expect(out).toContain('# Persona Contract (coder)');
+      expect(out).toContain('BASELINE-MANDATE');
+    });
+
+    it('OVERRIDE WINS at launch: roles.local persona is injected over baseline (AC-NS-7)', () => {
+      seedBaseline('coder', '# Coder\n\n(`class: coder`)\n\nBASELINE-MANDATE.\n');
+      seedOverride('coder', '# Coder (override)\n\n(`class: coder`)\n\nOVERRIDE-MANDATE.\n');
+      process.env['MOSAIC_AGENT_CLASS'] = 'coder';
+      const out = composeContract('claude', fixture.home);
+      expect(out).toContain('# Persona Contract (coder)');
+      expect(out).toContain('OVERRIDE-MANDATE');
+      expect(out).not.toContain('BASELINE-MANDATE');
+    });
+
+    it('does NOT inject a persona when MOSAIC_AGENT_CLASS is unset', () => {
+      seedBaseline('coder', '# Coder\n\n(`class: coder`)\n\nBASELINE-MANDATE.\n');
+      delete process.env['MOSAIC_AGENT_CLASS'];
+      const out = composeContract('claude', fixture.home);
+      expect(out).not.toContain('# Persona Contract');
+    });
+
+    it('does NOT inject (no throw) when MOSAIC_AGENT_CLASS names an unknown class', () => {
+      seedBaseline('coder', '# Coder\n\n(`class: coder`)\n\nBASELINE-MANDATE.\n');
+      process.env['MOSAIC_AGENT_CLASS'] = 'nonexistent';
+      expect(() => composeContract('claude', fixture.home)).not.toThrow();
+      expect(composeContract('claude', fixture.home)).not.toContain('# Persona Contract');
+    });
+
+    it('places the persona contract BEFORE the fleet comms block (identity, then peers)', () => {
+      seedBaseline('enhancer', '# Enhancer\n\n(`class: enhancer`)\n\nIMPROVE.\n');
+      mkdirSync(join(fixture.home, 'fleet'), { recursive: true });
+      writeFileSync(
+        join(fixture.home, 'fleet', 'roster.yaml'),
+        [
+          'agents:',
+          '  - name: orchestrator',
+          '    class: orchestrator',
+          '  - name: enhancer',
+          '    class: enhancer',
+          '',
+        ].join('\n'),
+      );
+      const prevName = process.env['MOSAIC_AGENT_NAME'];
+      try {
+        process.env['MOSAIC_AGENT_CLASS'] = 'enhancer';
+        process.env['MOSAIC_AGENT_NAME'] = 'enhancer';
+        const out = composeContract('claude', fixture.home);
+        expect(out).toContain('# Persona Contract (enhancer)');
+        expect(out).toContain('# Fleet Comms');
+        expect(out.indexOf('# Persona Contract')).toBeLessThan(out.indexOf('# Fleet Comms'));
+      } finally {
+        if (prevName === undefined) delete process.env['MOSAIC_AGENT_NAME'];
+        else process.env['MOSAIC_AGENT_NAME'] = prevName;
+      }
+    });
+  });
 });

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

@@ -25,7 +25,8 @@ describe('NORTH_STAR.yaml', () => {
   it('parses to a typed object with the required top-level keys', async () => {
     const ns = await loadParsed();
     expect(ns.version).toBeTypeOf('number');
-    expect(ns.mission).toContain('self-driving Mosaic delivery fleet');
+    expect(ns.mission).toContain('self-driving Mosaic system');
+    expect(ns.mission).toContain('Mosaic is general-purpose');
     expect(ns.substrate.note).toBeTruthy();
     expect(ns.standing_objectives.length).toBeGreaterThan(0);
     expect(ns.success_criteria.length).toBeGreaterThan(0);

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

@@ -0,0 +1,210 @@
+import { cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  extractClassesFromDir,
+  listPersonaClasses,
+  personaStatus,
+  resolvePersona,
+} from './fleet-personas.js';
+import { loadProfiles, validateProfile, type FleetProfile } from './fleet-profiles.js';
+
+// The real, committed library: packages/mosaic/src/commands -> framework/fleet.
+const frameworkFleet = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'framework',
+  'fleet',
+);
+const realRolesDir = join(frameworkFleet, 'roles');
+
+let tmp: string;
+let rolesDir: string;
+let overrideDir: string;
+
+// A minimal baseline persona file with an inline `class:` + `domain:` marker.
+function baselinePersona(klass: string, domain: string, marker = 'BASELINE'): string {
+  return `# ${klass} — fleet role definition
+
+The **${klass}** is the ${marker} definition (\`class: ${klass}\`, \`domain: ${domain}\`).
+`;
+}
+
+function overridePersona(klass: string, domain: string, marker = 'OVERRIDE'): string {
+  return `# ${klass} — fleet role definition (override)
+
+The **${klass}** is the ${marker} definition (\`class: ${klass}\`, \`domain: ${domain}\`).
+`;
+}
+
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), 'h4-personas-'));
+  rolesDir = join(tmp, 'roles');
+  overrideDir = join(tmp, 'roles.local');
+  await mkdir(rolesDir, { recursive: true });
+  // Seed two baseline personas. (No override dir yet — created per test.)
+  await writeFile(join(rolesDir, 'ceo.md'), baselinePersona('ceo', 'executive'), 'utf8');
+  await writeFile(join(rolesDir, 'code.md'), baselinePersona('code', 'engineering'), 'utf8');
+});
+
+afterEach(async () => {
+  await rm(tmp, { recursive: true, force: true });
+});
+
+describe('extractClassesFromDir (shared extraction)', () => {
+  it('records class + domain from inline markers and degrades on missing dir', async () => {
+    const base = await extractClassesFromDir(rolesDir);
+    expect(base.classes.has('ceo')).toBe(true);
+    expect(base.byClass.get('ceo')?.domain).toBe('executive');
+    const missing = await extractClassesFromDir(join(tmp, 'nope'));
+    expect(missing.classes.size).toBe(0);
+  });
+});
+
+describe('resolvePersona — override wins', () => {
+  it('resolves to the override when a class exists in BOTH layers', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(join(overrideDir, 'ceo.md'), overridePersona('ceo', 'executive'), 'utf8');
+
+    const resolved = await resolvePersona('ceo', { rolesDir, overrideDir });
+    expect(resolved?.layer).toBe('override');
+    expect(resolved?.content).toContain('OVERRIDE');
+    expect(resolved?.file).toBe(join(overrideDir, 'ceo.md'));
+  });
+
+  it('resolves to the baseline when no override exists', async () => {
+    const resolved = await resolvePersona('code', { rolesDir, overrideDir });
+    expect(resolved?.layer).toBe('baseline');
+    expect(resolved?.content).toContain('BASELINE');
+  });
+
+  it('returns null for an unknown class', async () => {
+    expect(await resolvePersona('does-not-exist', { rolesDir, overrideDir })).toBeNull();
+  });
+});
+
+describe('custom add — override-only class', () => {
+  it('a class present only in roles.local/ appears in listPersonaClasses and resolves', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'mascot.md'),
+      overridePersona('mascot', 'fun', 'CUSTOM'),
+      'utf8',
+    );
+
+    const classes = await listPersonaClasses({ rolesDir, overrideDir });
+    expect(classes.has('mascot')).toBe(true);
+    // Baseline classes are still present (union).
+    expect(classes.has('ceo')).toBe(true);
+
+    const resolved = await resolvePersona('mascot', { rolesDir, overrideDir });
+    expect(resolved?.layer).toBe('override');
+    expect(resolved?.content).toContain('CUSTOM');
+  });
+});
+
+describe('personaStatus classification', () => {
+  it('classifies baseline / overridden / custom correctly', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    // ceo: overridden (both). code: baseline (only base). mascot: custom (only override).
+    await writeFile(join(overrideDir, 'ceo.md'), overridePersona('ceo', 'executive'), 'utf8');
+    await writeFile(join(overrideDir, 'mascot.md'), overridePersona('mascot', 'fun'), 'utf8');
+
+    const status = await personaStatus({ rolesDir, overrideDir });
+    const byClass = new Map(status.map((s) => [s.klass, s]));
+    expect(byClass.get('ceo')?.status).toBe('overridden');
+    expect(byClass.get('code')?.status).toBe('baseline');
+    expect(byClass.get('mascot')?.status).toBe('custom');
+    // Domain surfaced.
+    expect(byClass.get('ceo')?.domain).toBe('executive');
+  });
+});
+
+describe('AC-NS-7 — update-survival simulation', () => {
+  it('override and custom-added class survive a baseline reseed', async () => {
+    // 1. User customizes ceo and adds a brand-new persona in the override layer.
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(join(overrideDir, 'ceo.md'), overridePersona('ceo', 'executive'), 'utf8');
+    await writeFile(
+      join(overrideDir, 'mascot.md'),
+      overridePersona('mascot', 'fun', 'CUSTOM'),
+      'utf8',
+    );
+
+    // 2. Simulate `mosaic update`: REPLACE the baseline roles/ entirely (as the
+    //    framework reseed/rsync does), leaving roles.local/ untouched. The reseed
+    //    even ships a NEW baseline ceo and adds a brand-new baseline persona.
+    await rm(rolesDir, { recursive: true, force: true });
+    await mkdir(rolesDir, { recursive: true });
+    await writeFile(
+      join(rolesDir, 'ceo.md'),
+      baselinePersona('ceo', 'executive', 'RESEEDED-BASELINE'),
+      'utf8',
+    );
+    await writeFile(join(rolesDir, 'code.md'), baselinePersona('code', 'engineering'), 'utf8');
+    await writeFile(join(rolesDir, 'new-role.md'), baselinePersona('new-role', 'ops'), 'utf8');
+
+    // 3. The override STILL wins (was not clobbered by the reseed).
+    const ceo = await resolvePersona('ceo', { rolesDir, overrideDir });
+    expect(ceo?.layer).toBe('override');
+    expect(ceo?.content).toContain('OVERRIDE');
+    expect(ceo?.content).not.toContain('RESEEDED-BASELINE');
+
+    // 4. The custom-added class still exists and resolves.
+    const mascot = await resolvePersona('mascot', { rolesDir, overrideDir });
+    expect(mascot?.layer).toBe('override');
+    expect(mascot?.content).toContain('CUSTOM');
+
+    // 5. New baseline personas from the reseed are now visible too.
+    const classes = await listPersonaClasses({ rolesDir, overrideDir });
+    expect(classes.has('new-role')).toBe(true);
+    expect(classes.has('mascot')).toBe(true);
+  });
+});
+
+describe('fleet-profiles validation accepts a custom (override-only) persona', () => {
+  it('a profile referencing an override-only class validates', async () => {
+    // Build a profiles dir + roles using the REAL library plus a custom persona.
+    const profilesDir = join(tmp, 'profiles');
+    const customRolesDir = join(tmp, 'real-roles');
+    const customOverrideDir = join(tmp, 'real-roles.local');
+    await mkdir(profilesDir, { recursive: true });
+    await cp(realRolesDir, customRolesDir, { recursive: true });
+    await mkdir(customOverrideDir, { recursive: true });
+    await writeFile(join(customOverrideDir, 'mascot.md'), overridePersona('mascot', 'fun'), 'utf8');
+
+    // A profile whose roster references the custom (override-only) persona.
+    const profileYaml = [
+      'id: custom-team',
+      'title: Custom Team',
+      'description: A team that uses a user-added persona.',
+      'lead: ceo',
+      'floor:',
+      '  - ceo',
+      'roster:',
+      '  - class: ceo',
+      '  - class: mascot',
+      '    reports_to: ceo',
+    ].join('\n');
+    await writeFile(join(profilesDir, 'custom-team.yaml'), profileYaml, 'utf8');
+
+    // Override-aware loadProfiles must accept it (would throw if mascot unknown).
+    const profiles = await loadProfiles({
+      profilesDir,
+      rolesDir: customRolesDir,
+      overrideDir: customOverrideDir,
+    });
+    const team = profiles.find((p: FleetProfile) => p.id === 'custom-team');
+    expect(team).toBeDefined();
+
+    // And direct validation against the union confirms zero problems.
+    const validClasses = await listPersonaClasses({
+      rolesDir: customRolesDir,
+      overrideDir: customOverrideDir,
+    });
+    expect(validateProfile(team as FleetProfile, validClasses)).toEqual([]);
+  });
+});

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

@@ -0,0 +1,497 @@
+/**
+ * Persona override layer + resolver (North Star H4).
+ *
+ * Baseline personas are markdown role contracts seeded by the framework into
+ *   <mosaicHome>/fleet/roles/*.md
+ * They are RESEEDED on every `mosaic update` (so new baseline personas ship to
+ * existing installs). That reseed is exactly what would clobber any local edit,
+ * so user customizations must NOT live in roles/.
+ *
+ * The override layer is a sibling directory:
+ *   <mosaicHome>/fleet/roles.local/*.md
+ * It is PRESERVE-protected in install.sh (see PRESERVE_PATHS "fleet/roles.local"),
+ * so `mosaic update` never deletes it while roles/ keeps reseeding. An override
+ * file WINS over the baseline of the same class, and an override file may ADD an
+ * entirely new class that has no baseline at all. This delivers AC-NS-7: a
+ * user-customized persona survives `mosaic update`.
+ *
+ * Class identity is encoded INLINE in the role prose, not as YAML frontmatter:
+ *   (`class: ceo`, `domain: executive`)
+ * The marker value may wrap across a newline. A few engineering personas carry
+ * no marker at all and are identified by filename (e.g. planner -> orchestrator).
+ *
+ * The class-extraction logic here is the SINGLE SOURCE OF TRUTH for "what
+ * persona classes exist"; fleet-profiles.ts imports it (DRY) so a profile roster
+ * can reference a customized or user-added persona.
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import type { Command } from 'commander';
+
+function defaultMosaicHome(): string {
+  return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
+}
+
+/** Baseline persona role contracts (reseeded on update). */
+export function defaultRolesDir(mosaicHome = defaultMosaicHome()): string {
+  return join(mosaicHome, 'fleet', 'roles');
+}
+
+/** PRESERVE-protected override layer (survives update; wins on merge). */
+export function defaultOverrideDir(mosaicHome = defaultMosaicHome()): string {
+  return join(mosaicHome, 'fleet', 'roles.local');
+}
+
+/**
+ * Match a `class: X` marker even when the value wrapped onto the next line.
+ * Allow surrounding backtick(s); the value is a single kebab-case token.
+ * Shared by every caller so the definition of "a class marker" lives once.
+ */
+const CLASS_MARKER = /`?class:\s*\n?\s*([a-z][a-z0-9-]*)`?/g;
+/** Optional `domain: Y` marker that travels alongside the class in the prose. */
+const DOMAIN_MARKER = /`?domain:\s*\n?\s*([a-z][a-z0-9-]*)`?/;
+/** LIBRARY.md persona rows: the first table cell is the persona name. */
+const LIBRARY_ROW = /^\|\s*([a-z][a-z0-9-]*)\s*\|/gm;
+
+/** Where a resolved persona's definition came from. */
+export type PersonaLayer = 'baseline' | 'override';
+
+/** One discovered persona file (a single role contract on disk). */
+export interface PersonaFile {
+  klass: string;
+  /** The markdown file the class was found in. */
+  file: string;
+  domain?: string;
+}
+
+/** The set of persona classes a directory of role contracts defines. */
+export interface DirClasses {
+  /** Every class name the dir contributes (markers + filenames + LIBRARY rows). */
+  classes: Set<string>;
+  /** For classes whose file carries a marker, the file + domain that defined it. */
+  byClass: Map<string, PersonaFile>;
+}
+
+/**
+ * Scan one directory of role contracts and extract the persona classes it
+ * defines. THIS is the shared extraction both fleet-personas and fleet-profiles
+ * rely on. Sources, unioned (each needed — see module doc):
+ *   1. inline `class: X` markers in roles/*.md (primary; may wrap a newline),
+ *   2. persona-name cells from LIBRARY.md index tables,
+ *   3. the role filename stem (covers marker-less alias docs like planner).
+ *
+ * Missing dir / unreadable files degrade gracefully to whatever was found.
+ * `byClass` records the defining file+domain for marker-bearing classes so the
+ * resolver can map a class back to its file; filename-only and LIBRARY-only
+ * classes still appear in `classes` for membership checks.
+ */
+export async function extractClassesFromDir(dir: string): Promise<DirClasses> {
+  const acc: DirClasses = { classes: new Set<string>(), byClass: new Map<string, PersonaFile>() };
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return acc;
+  }
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.md')) continue;
+    let text: string;
+    try {
+      text = await readFile(join(dir, entry), 'utf8');
+    } catch {
+      continue;
+    }
+    accumulateEntry(acc, dir, entry, text);
+  }
+  return acc;
+}
+
+/**
+ * Synchronous twin of {@link extractClassesFromDir}. Identical extraction
+ * semantics (same markers, same union of marker/filename/LIBRARY sources) on
+ * sync fs, for the synchronous launch-time prompt path (composeContract) which
+ * cannot await. Missing dir / unreadable files degrade gracefully.
+ */
+export function extractClassesFromDirSync(dir: string): DirClasses {
+  const acc: DirClasses = { classes: new Set<string>(), byClass: new Map<string, PersonaFile>() };
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return acc;
+  }
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.md')) continue;
+    let text: string;
+    try {
+      text = readFileSync(join(dir, entry), 'utf8');
+    } catch {
+      continue;
+    }
+    accumulateEntry(acc, dir, entry, text);
+  }
+  return acc;
+}
+
+/**
+ * Apply the class-extraction rules for ONE role file's text into `acc`. Pure
+ * over already-read content, so the async and sync directory scanners share a
+ * single definition of "what classes a file contributes" (DRY — no semantic
+ * drift between the launch-time and command-time paths).
+ */
+function accumulateEntry(acc: DirClasses, dir: string, entry: string, text: string): void {
+  const { classes, byClass } = acc;
+  if (entry === 'LIBRARY.md') {
+    for (const m of text.matchAll(LIBRARY_ROW)) {
+      const name = m[1];
+      if (name && name !== 'persona') classes.add(name);
+    }
+    return;
+  }
+  // The filename stem is itself a valid class (covers marker-less alias docs).
+  const stem = basename(entry, '.md');
+  classes.add(stem);
+  const domainMatch = DOMAIN_MARKER.exec(text);
+  const domain = domainMatch?.[1];
+  let markedClassForFile: string | undefined;
+  for (const m of text.matchAll(CLASS_MARKER)) {
+    const klass = m[1];
+    if (!klass) continue;
+    classes.add(klass);
+    // Record the FIRST marker as the file's defining class (the prose names
+    // the persona's own class up top; later mentions reference siblings).
+    if (!markedClassForFile) {
+      markedClassForFile = klass;
+      byClass.set(klass, { klass, file: join(dir, entry), ...(domain ? { domain } : {}) });
+    }
+  }
+  // A marker-less file still maps its stem to itself (no domain known).
+  if (!markedClassForFile && !byClass.has(stem)) {
+    byClass.set(stem, { klass: stem, file: join(dir, entry) });
+  }
+}
+
+export interface PersonaDirs {
+  /** Baseline roles dir. Defaults to <mosaicHome>/fleet/roles. */
+  rolesDir?: string;
+  /** Override dir. Defaults to <mosaicHome>/fleet/roles.local. */
+  overrideDir?: string;
+  mosaicHome?: string;
+}
+
+function resolveDirs(opts: PersonaDirs): { rolesDir: string; overrideDir: string } {
+  const mosaicHome = opts.mosaicHome ?? defaultMosaicHome();
+  return {
+    rolesDir: opts.rolesDir ?? defaultRolesDir(mosaicHome),
+    overrideDir: opts.overrideDir ?? defaultOverrideDir(mosaicHome),
+  };
+}
+
+/**
+ * UNION of baseline classes and override classes. Overrides may ADD entirely new
+ * classes not present in the baseline, so callers (e.g. profile roster
+ * validation) treat a user-added persona as a real class.
+ */
+export async function listPersonaClasses(opts: PersonaDirs = {}): Promise<Set<string>> {
+  const { rolesDir, overrideDir } = resolveDirs(opts);
+  const [base, over] = await Promise.all([
+    extractClassesFromDir(rolesDir),
+    extractClassesFromDir(overrideDir),
+  ]);
+  const union = new Set<string>(base.classes);
+  for (const c of over.classes) union.add(c);
+  return union;
+}
+
+export type PersonaStatus = 'baseline' | 'overridden' | 'custom';
+
+export interface PersonaResolution {
+  klass: string;
+  layer: PersonaLayer;
+  /** The file the resolved persona was read from (override wins). */
+  file: string;
+  content: string;
+  domain?: string;
+}
+
+/**
+ * Resolve a persona class to its winning definition: the override file if
+ * roles.local/ defines that class, else the baseline. Match by inline `class:`
+ * marker first, then by filename stem (roles.local/<klass>.md) as a fallback.
+ * Returns null if neither layer defines the class.
+ */
+export async function resolvePersona(
+  klass: string,
+  opts: PersonaDirs = {},
+): Promise<PersonaResolution | null> {
+  const { rolesDir, overrideDir } = resolveDirs(opts);
+  const [base, over] = await Promise.all([
+    extractClassesFromDir(rolesDir),
+    extractClassesFromDir(overrideDir),
+  ]);
+
+  const fromLayer = async (
+    dir: string,
+    extracted: DirClasses,
+    layer: PersonaLayer,
+  ): Promise<PersonaResolution | null> => {
+    // Prefer the marker-defined file; fall back to the filename stem.
+    let pf = extracted.byClass.get(klass);
+    if (!pf) {
+      const byName = join(dir, `${klass}.md`);
+      if (!extracted.classes.has(klass)) return null;
+      // Class known only via filename/LIBRARY: read the stem file if present.
+      try {
+        const content = await readFile(byName, 'utf8');
+        const dm = DOMAIN_MARKER.exec(content);
+        return { klass, layer, file: byName, content, ...(dm?.[1] ? { domain: dm[1] } : {}) };
+      } catch {
+        return null;
+      }
+    }
+    try {
+      const content = await readFile(pf.file, 'utf8');
+      return { klass, layer, file: pf.file, content, ...(pf.domain ? { domain: pf.domain } : {}) };
+    } catch {
+      return null;
+    }
+  };
+
+  return (
+    (await fromLayer(overrideDir, over, 'override')) ??
+    (await fromLayer(rolesDir, base, 'baseline'))
+  );
+}
+
+/**
+ * Synchronous twin of {@link resolvePersona} — same override-wins precedence
+ * (roles.local/ beats roles/, by marker first then filename stem), returning
+ * null if neither layer defines the class. Exists for the synchronous launch
+ * prompt path (composeContract → readPersonaContractBlock) which cannot await.
+ * Keeping it here, beside the async resolver, keeps the resolution semantics in
+ * one module so the launch-time and command-time resolutions never diverge.
+ */
+export function resolvePersonaSync(
+  klass: string,
+  opts: PersonaDirs = {},
+): PersonaResolution | null {
+  const { rolesDir, overrideDir } = resolveDirs(opts);
+  const base = extractClassesFromDirSync(rolesDir);
+  const over = extractClassesFromDirSync(overrideDir);
+
+  const fromLayer = (
+    dir: string,
+    extracted: DirClasses,
+    layer: PersonaLayer,
+  ): PersonaResolution | null => {
+    // Prefer the marker-defined file; fall back to the filename stem.
+    const pf = extracted.byClass.get(klass);
+    if (!pf) {
+      if (!extracted.classes.has(klass)) return null;
+      const byName = join(dir, `${klass}.md`);
+      try {
+        const content = readFileSync(byName, 'utf8');
+        const dm = DOMAIN_MARKER.exec(content);
+        return { klass, layer, file: byName, content, ...(dm?.[1] ? { domain: dm[1] } : {}) };
+      } catch {
+        return null;
+      }
+    }
+    try {
+      const content = readFileSync(pf.file, 'utf8');
+      return { klass, layer, file: pf.file, content, ...(pf.domain ? { domain: pf.domain } : {}) };
+    } catch {
+      return null;
+    }
+  };
+
+  return fromLayer(overrideDir, over, 'override') ?? fromLayer(rolesDir, base, 'baseline');
+}
+
+export interface PersonaStatusEntry {
+  klass: string;
+  status: PersonaStatus;
+  domain?: string;
+}
+
+/**
+ * Classify every known class:
+ *   - baseline   — present only in roles/
+ *   - overridden — present in BOTH roles/ and roles.local/ (override wins)
+ *   - custom     — present only in roles.local/ (user-added)
+ * Domain is taken from the WINNING layer (override domain wins if present).
+ */
+export async function personaStatus(opts: PersonaDirs = {}): Promise<PersonaStatusEntry[]> {
+  const { rolesDir, overrideDir } = resolveDirs(opts);
+  const [base, over] = await Promise.all([
+    extractClassesFromDir(rolesDir),
+    extractClassesFromDir(overrideDir),
+  ]);
+
+  const all = new Set<string>([...base.classes, ...over.classes]);
+  const domainOf = (extracted: DirClasses, klass: string): string | undefined =>
+    extracted.byClass.get(klass)?.domain;
+
+  const entries: PersonaStatusEntry[] = [];
+  for (const klass of all) {
+    const inBase = base.classes.has(klass);
+    const inOver = over.classes.has(klass);
+    const status: PersonaStatus = inOver ? (inBase ? 'overridden' : 'custom') : 'baseline';
+    const domain = (inOver ? domainOf(over, klass) : undefined) ?? domainOf(base, klass);
+    entries.push({ klass, status, ...(domain ? { domain } : {}) });
+  }
+  entries.sort((a, b) => a.klass.localeCompare(b.klass));
+  return entries;
+}
+
+// ─── CLI: `mosaic fleet persona <list|show|customize>` ───────────────────────
+
+function printPersonaList(entries: PersonaStatusEntry[]): void {
+  if (entries.length === 0) {
+    console.log('(no personas)');
+    return;
+  }
+  for (const e of entries) {
+    console.log(`${e.klass}\t[${e.status}]\tdomain=${e.domain ?? '-'}`);
+  }
+}
+
+/** Minimal override scaffold for a brand-new (no-baseline) class. */
+function scaffoldOverride(klass: string): string {
+  return `# ${klass} — fleet role definition (override)
+
+The **${klass}** persona (\`class: ${klass}\`) is a user-defined override that
+lives in the PRESERVE-protected \`fleet/roles.local/\` layer and survives
+\`mosaic update\`. Edit this file to define the persona's mandate and boundaries.
+
+## Mandate
+
+1. (describe what this persona owns)
+
+## Boundaries
+
+- (describe what this persona does NOT do)
+`;
+}
+
+/**
+ * Register `persona` under an existing `fleet` command. `mosaicHomeFor` resolves
+ * the active --mosaic-home (parent flag) at call time, mirroring the backlog and
+ * profile subcommand wiring.
+ */
+export function registerFleetPersonaCommand(
+  fleetCmd: Command,
+  mosaicHomeFor: () => string,
+): Command {
+  const personaCmd = fleetCmd
+    .command('persona')
+    .description('Update-surviving persona overrides: baseline ⊕ roles.local layer (H4)');
+
+  personaCmd
+    .command('list')
+    .description('List every persona class with its status (baseline/overridden/custom) and domain')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { json?: boolean }) => {
+      try {
+        const entries = await personaStatus({ mosaicHome: mosaicHomeFor() });
+        if (opts.json) {
+          console.log(JSON.stringify(entries));
+          return;
+        }
+        printPersonaList(entries);
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  personaCmd
+    .command('show <class>')
+    .description('Show the RESOLVED persona (override wins) and which layer it came from')
+    .option('--json', 'Print JSON')
+    .action(async (klass: string, opts: { json?: boolean }) => {
+      try {
+        const resolved = await resolvePersona(klass, { mosaicHome: mosaicHomeFor() });
+        if (!resolved) {
+          process.stderr.write(`Unknown persona class "${klass}"\n`);
+          process.exitCode = 1;
+          return;
+        }
+        if (opts.json) {
+          console.log(JSON.stringify(resolved));
+          return;
+        }
+        console.log(`# class: ${resolved.klass}`);
+        console.log(`# layer: ${resolved.layer}`);
+        console.log(`# domain: ${resolved.domain ?? '-'}`);
+        console.log(`# file: ${resolved.file}`);
+        console.log('');
+        console.log(resolved.content);
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  personaCmd
+    .command('customize <class>')
+    .description(
+      'Copy the baseline persona into fleet/roles.local/ to edit (override layer). ' +
+        '--new scaffolds a brand-new persona with no baseline.',
+    )
+    .option('--new', 'Scaffold a minimal override for a brand-new class (no baseline required)')
+    .action(async (klass: string, opts: { new?: boolean }) => {
+      try {
+        const { mkdir, writeFile, copyFile, access } = await import('node:fs/promises');
+        const { constants } = await import('node:fs');
+        const mosaicHome = mosaicHomeFor();
+        const rolesDir = defaultRolesDir(mosaicHome);
+        const overrideDir = defaultOverrideDir(mosaicHome);
+        const target = join(overrideDir, `${klass}.md`);
+
+        await mkdir(overrideDir, { recursive: true });
+
+        // Do not clobber an existing override.
+        try {
+          await access(target, constants.F_OK);
+          console.log(`Override already exists, not clobbering: ${target}`);
+          return;
+        } catch {
+          // not present — proceed
+        }
+
+        if (opts.new) {
+          await writeFile(target, scaffoldOverride(klass), 'utf8');
+          console.log(`Scaffolded new persona override: ${target}`);
+          return;
+        }
+
+        // Copy the baseline. Prefer the marker-defining file; fall back to stem.
+        const base = await extractClassesFromDir(rolesDir);
+        const pf = base.byClass.get(klass);
+        const source = pf?.file ?? join(rolesDir, `${klass}.md`);
+        try {
+          await access(source, constants.F_OK);
+        } catch {
+          process.stderr.write(
+            `No baseline persona "${klass}" to copy. Use --new to scaffold one.\n`,
+          );
+          process.exitCode = 1;
+          return;
+        }
+        await copyFile(source, target);
+        console.log(`Copied baseline persona to override layer: ${target}`);
+        console.log('Edit it there; it wins over the baseline and survives `mosaic update`.');
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  return personaCmd;
+}

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

@@ -0,0 +1,226 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  listPersonaClasses,
+  loadProfile,
+  loadProfiles,
+  parseProfile,
+  validateProfile,
+  type FleetProfile,
+} from './fleet-profiles.js';
+
+// The real, committed library: packages/mosaic/src/commands -> framework/fleet.
+const frameworkFleet = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'framework',
+  'fleet',
+);
+const rolesDir = join(frameworkFleet, 'roles');
+const profilesDir = join(frameworkFleet, 'profiles');
+
+const realLib = { rolesDir, profilesDir };
+
+const EXPECTED_IDS = [
+  'business',
+  'marketing',
+  'personal-assistant',
+  'research',
+  'software-delivery',
+];
+
+describe('listPersonaClasses (real role library)', () => {
+  it('extracts inline `class:` markers from the role contracts', async () => {
+    const classes = await listPersonaClasses(rolesDir);
+    // Personas that carry an inline `class: X` marker.
+    expect(classes.has('code')).toBe(true);
+    expect(classes.has('marketing-lead')).toBe(true);
+    expect(classes.has('ceo')).toBe(true);
+    // support-agent's marker wraps across a newline — must still resolve.
+    expect(classes.has('support-agent')).toBe(true);
+  });
+
+  it('covers marker-less engineering personas via filename + LIBRARY index', async () => {
+    const classes = await listPersonaClasses(rolesDir);
+    // planner/decomposition have a role file but no inline marker — they resolve
+    // from the filename + LIBRARY.md row.
+    expect(classes.has('planner')).toBe(true);
+    expect(classes.has('decomposition')).toBe(true);
+    // The dedicated orchestrator persona resolves (inline marker + filename + row).
+    expect(classes.has('orchestrator')).toBe(true);
+  });
+
+  it('returns an empty set for a missing roles dir (graceful)', async () => {
+    const classes = await listPersonaClasses(join(tmpdir(), 'definitely-missing-roles-xyz'));
+    expect(classes.size).toBe(0);
+  });
+});
+
+describe('baseline profiles (real library)', () => {
+  it('loads exactly the five baseline profiles, sorted by id', async () => {
+    const profiles = await loadProfiles(realLib);
+    expect(profiles.map((p) => p.id)).toEqual(EXPECTED_IDS);
+  });
+
+  it('every referenced class resolves against the real role library (drift guard)', async () => {
+    // This is the key test: it fails if a profile drifts from the persona library.
+    const profiles = await loadProfiles(realLib);
+    const validClasses = await listPersonaClasses(rolesDir);
+    for (const profile of profiles) {
+      expect(validateProfile(profile, validClasses)).toEqual([]);
+    }
+  });
+
+  it('software-delivery has the expected lead, floor, and roster shape', async () => {
+    const profile = await loadProfile('software-delivery', realLib);
+    expect(profile.lead).toBe('orchestrator');
+    expect(profile.floor).toEqual(['orchestrator', 'enhancer']);
+    const code = profile.roster.find((r) => r.class === 'code');
+    expect(code?.multiplicity).toBe(2);
+    expect(code?.reportsTo).toBe('decomposition');
+    // The dedicated orchestrator is the lead seat (no reports_to); the planner is
+    // now a distinct seat that reports to it.
+    const orchestrator = profile.roster.find((r) => r.class === 'orchestrator');
+    expect(orchestrator?.reportsTo).toBeUndefined();
+    const planner = profile.roster.find((r) => r.class === 'planner');
+    expect(planner?.reportsTo).toBe('orchestrator');
+  });
+
+  it('loadProfile throws on an unknown id', async () => {
+    await expect(loadProfile('does-not-exist', realLib)).rejects.toThrow(/Unknown profile/);
+  });
+});
+
+describe('parseProfile', () => {
+  it('defaults multiplicity to 1 and omits reports_to for the lead', () => {
+    const yaml = [
+      'id: x',
+      'title: X',
+      'description: a system',
+      'lead: ceo',
+      'floor: [ceo]',
+      'roster:',
+      '  - class: ceo',
+      '  - class: code',
+      '    reports_to: ceo',
+      '    multiplicity: 3',
+      '',
+    ].join('\n');
+    const profile = parseProfile(yaml);
+    expect(profile.roster[0]).toEqual({ class: 'ceo', multiplicity: 1 });
+    expect(profile.roster[1]).toEqual({ class: 'code', reportsTo: 'ceo', multiplicity: 3 });
+  });
+
+  it('rejects a profile whose id mismatches its filename', () => {
+    expect(() =>
+      parseProfile(
+        'id: other\ntitle: T\ndescription: d\nlead: ceo\nroster: [{class: ceo}]\n',
+        'expected',
+      ),
+    ).toThrow(/does not match its filename/);
+  });
+
+  it('rejects a non-integer multiplicity', () => {
+    const yaml =
+      'id: x\ntitle: T\ndescription: d\nlead: ceo\nroster:\n  - class: ceo\n    multiplicity: 1.5\n';
+    expect(() => parseProfile(yaml)).toThrow(/multiplicity/);
+  });
+});
+
+describe('validateProfile', () => {
+  const valid = new Set(['ceo', 'coo', 'code']);
+
+  it('passes a well-formed profile', () => {
+    const profile: FleetProfile = {
+      id: 'x',
+      title: 'X',
+      description: 'd',
+      lead: 'ceo',
+      floor: ['ceo'],
+      roster: [
+        { class: 'ceo', multiplicity: 1 },
+        { class: 'coo', reportsTo: 'ceo', multiplicity: 1 },
+      ],
+    };
+    expect(validateProfile(profile, valid)).toEqual([]);
+  });
+
+  it('rejects an unknown roster class', () => {
+    const profile: FleetProfile = {
+      id: 'x',
+      title: 'X',
+      description: 'd',
+      lead: 'ceo',
+      floor: [],
+      roster: [{ class: 'not-a-real-persona', multiplicity: 1 }],
+    };
+    const problems = validateProfile(profile, valid);
+    expect(problems.some((p) => /not-a-real-persona.*not a known persona class/.test(p))).toBe(
+      true,
+    );
+  });
+
+  it('rejects a reports_to that names a class absent from the roster', () => {
+    const profile: FleetProfile = {
+      id: 'x',
+      title: 'X',
+      description: 'd',
+      lead: 'ceo',
+      floor: [],
+      roster: [{ class: 'code', reportsTo: 'coo', multiplicity: 1 }], // coo valid but not in roster
+    };
+    const problems = validateProfile(profile, valid);
+    expect(problems.some((p) => /reports_to.*not present in this roster/.test(p))).toBe(true);
+  });
+
+  it('rejects a reports_to that is not a known persona class at all', () => {
+    const profile: FleetProfile = {
+      id: 'x',
+      title: 'X',
+      description: 'd',
+      lead: 'ceo',
+      floor: [],
+      roster: [
+        { class: 'ceo', multiplicity: 1 },
+        { class: 'code', reportsTo: 'ghost', multiplicity: 1 },
+      ],
+    };
+    const problems = validateProfile(profile, valid);
+    expect(problems.some((p) => /ghost.*not a known persona class/.test(p))).toBe(true);
+  });
+});
+
+describe('loadProfiles with a temp override dir', () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'mosaic-profiles-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('throws when a profile references an unknown class (validated against real roles)', async () => {
+    await writeFile(
+      join(dir, 'bad.yaml'),
+      'id: bad\ntitle: Bad\ndescription: d\nlead: nope-not-real\nroster:\n  - class: nope-not-real\n',
+    );
+    await expect(loadProfiles({ profilesDir: dir, rolesDir })).rejects.toThrow(
+      /is invalid|not a known persona class/,
+    );
+  });
+
+  it('throws on duplicate profile ids across files', async () => {
+    const body = 'title: Dup\ndescription: d\nlead: ceo\nroster:\n  - class: ceo\n';
+    // Same declared id in two differently-named files -> id mismatches filename
+    // first; use matching filenames+id to force the duplicate-id path instead.
+    await writeFile(join(dir, 'dup.yaml'), `id: dup\n${body}`);
+    await writeFile(join(dir, 'dup.yml'), `id: dup\n${body}`);
+    await expect(loadProfiles({ profilesDir: dir, rolesDir })).rejects.toThrow(
+      /Duplicate profile id/,
+    );
+  });
+});

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

@@ -0,0 +1,364 @@
+/**
+ * `mosaic fleet profile <list|show>` — system-type profiles (North Star H2).
+ *
+ * A profile is a DECLARATIVE mapping from a "system type" (software-delivery,
+ * personal-assistant, research, business, marketing, …) to a persona roster plus
+ * its org topology. Profiles are DATA, seeded from the framework like roles:
+ *   framework/fleet/profiles/*.yaml  ->  <mosaicHome>/fleet/profiles/*.yaml
+ * so an operator declares a system type and gets the matching roster from the
+ * baseline library with NO code change (NS-9 / AC-NS-6).
+ *
+ * This module loads, parses, and VALIDATES those yaml files. Validation guards
+ * roster/library drift: every persona class a profile references MUST resolve to
+ * a real persona in the role library. Because the library encodes class identity
+ * INLINE in prose (e.g. `` (`class: marketing-lead`) ``) — not YAML frontmatter —
+ * and a few engineering personas (planner/decomposition) carry no marker at all,
+ * the set of valid classes is the UNION of three signals:
+ *   1. inline `` `class: X` `` markers scanned from roles/*.md,
+ *   2. the persona rows in roles/LIBRARY.md (the authoritative index),
+ *   3. the role filenames themselves (roles/<class>.md).
+ * See `listPersonaClasses`.
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import type { Command } from 'commander';
+import YAML from 'yaml';
+import {
+  defaultOverrideDir,
+  extractClassesFromDir,
+  listPersonaClasses as listOverrideAwarePersonaClasses,
+} from './fleet-personas.js';
+
+function defaultMosaicHome(): string {
+  return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
+}
+
+/** Directory holding the seeded profile yaml files. */
+export function defaultProfilesDir(mosaicHome = defaultMosaicHome()): string {
+  return join(mosaicHome, 'fleet', 'profiles');
+}
+
+/** Directory holding the persona role contracts. */
+export function defaultRolesDir(mosaicHome = defaultMosaicHome()): string {
+  return join(mosaicHome, 'fleet', 'roles');
+}
+
+export interface ProfileRosterEntry {
+  class: string;
+  reportsTo?: string;
+  multiplicity: number;
+}
+
+export interface FleetProfile {
+  id: string;
+  title: string;
+  description: string;
+  lead: string;
+  floor: string[];
+  roster: ProfileRosterEntry[];
+  notes?: string;
+}
+
+/**
+ * Extract the set of valid persona classes from a single baseline role dir.
+ *
+ * Thin wrapper over the shared {@link extractClassesFromDir} in fleet-personas.ts
+ * — the single source of truth for "what classes exist" (DRY). Kept as a
+ * baseline-only, positional-`rolesDir` helper for backward compatibility; the
+ * override-aware union (baseline ⊕ roles.local) used by roster validation is
+ * {@link listPersonaClassesWithOverrides} below.
+ */
+export async function listPersonaClasses(rolesDir = defaultRolesDir()): Promise<Set<string>> {
+  return (await extractClassesFromDir(rolesDir)).classes;
+}
+
+/**
+ * Override-aware valid-class set: baseline roles/ ⊕ override roles.local/. A
+ * profile may legitimately reference a user-customized OR user-ADDED persona, so
+ * roster validation resolves against this union (H4). Delegates to the shared
+ * fleet-personas resolver.
+ */
+export async function listPersonaClassesWithOverrides(
+  rolesDir: string,
+  overrideDir: string,
+): Promise<Set<string>> {
+  return listOverrideAwarePersonaClasses({ rolesDir, overrideDir });
+}
+
+function asString(value: unknown, ctx: string): string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`profile ${ctx} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+/**
+ * Parse raw yaml text into a typed FleetProfile. Pure (no IO). Throws a
+ * descriptive error on a malformed profile so the loader/CLI fail loudly.
+ * `sourceId` (typically the filename stem) is used only for error messages and
+ * to validate that the declared `id` matches the file it came from.
+ */
+export function parseProfile(rawText: string, sourceId?: string): FleetProfile {
+  const parsed = YAML.parse(rawText) as Record<string, unknown> | null;
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error(`profile ${sourceId ?? '<?>'} did not parse to a mapping`);
+  }
+
+  const id = asString(parsed['id'], `${sourceId ?? '<?>'}.id`);
+  if (sourceId && id !== sourceId) {
+    throw new Error(`profile id "${id}" does not match its filename "${sourceId}"`);
+  }
+
+  const rawFloor = parsed['floor'] ?? [];
+  if (!Array.isArray(rawFloor)) {
+    throw new Error(`profile ${id}.floor must be an array`);
+  }
+  const floor = rawFloor.map((c, i) => asString(c, `${id}.floor[${i}]`));
+
+  const rawRoster = parsed['roster'];
+  if (!Array.isArray(rawRoster) || rawRoster.length === 0) {
+    throw new Error(`profile ${id}.roster must be a non-empty array`);
+  }
+  const roster: ProfileRosterEntry[] = rawRoster.map((row, i) => {
+    const r = row as Record<string, unknown>;
+    const cls = asString(r?.['class'], `${id}.roster[${i}].class`);
+    const multRaw = r?.['multiplicity'];
+    let multiplicity = 1;
+    if (multRaw !== undefined && multRaw !== null) {
+      if (typeof multRaw !== 'number' || !Number.isInteger(multRaw) || multRaw < 1) {
+        throw new Error(`profile ${id}.roster[${i}].multiplicity must be a positive integer`);
+      }
+      multiplicity = multRaw;
+    }
+    const entry: ProfileRosterEntry = { class: cls, multiplicity };
+    const reportsTo = r?.['reports_to'];
+    if (reportsTo !== undefined && reportsTo !== null) {
+      entry.reportsTo = asString(reportsTo, `${id}.roster[${i}].reports_to`);
+    }
+    return entry;
+  });
+
+  const profile: FleetProfile = {
+    id,
+    title: asString(parsed['title'], `${id}.title`),
+    description: asString(parsed['description'], `${id}.description`),
+    lead: asString(parsed['lead'], `${id}.lead`),
+    floor,
+    roster,
+  };
+  const notes = parsed['notes'];
+  if (notes !== undefined && notes !== null) {
+    profile.notes = asString(notes, `${id}.notes`);
+  }
+  return profile;
+}
+
+/**
+ * Validate a profile against the set of valid persona classes and its own roster.
+ * Returns the list of problems (empty when valid) rather than throwing, so the
+ * loader can aggregate errors across many profiles.
+ *
+ * Checks:
+ *   - lead resolves to a real persona class.
+ *   - every floor[] entry resolves.
+ *   - every roster[].class resolves.
+ *   - every roster[].reports_to resolves AND names a class present in THIS roster
+ *     (topology edges must point at a seat that exists in the profile).
+ * Cycle detection in the reports_to graph is intentionally out of scope.
+ */
+export function validateProfile(profile: FleetProfile, validClasses: Set<string>): string[] {
+  const problems: string[] = [];
+  const rosterClasses = new Set(profile.roster.map((r) => r.class));
+
+  if (!validClasses.has(profile.lead)) {
+    problems.push(`lead "${profile.lead}" is not a known persona class`);
+  }
+  for (const f of profile.floor) {
+    if (!validClasses.has(f)) {
+      problems.push(`floor entry "${f}" is not a known persona class`);
+    }
+  }
+  for (const entry of profile.roster) {
+    if (!validClasses.has(entry.class)) {
+      problems.push(`roster class "${entry.class}" is not a known persona class`);
+    }
+    if (entry.reportsTo !== undefined) {
+      if (!validClasses.has(entry.reportsTo)) {
+        problems.push(
+          `roster "${entry.class}" reports_to "${entry.reportsTo}" is not a known persona class`,
+        );
+      } else if (!rosterClasses.has(entry.reportsTo)) {
+        problems.push(
+          `roster "${entry.class}" reports_to "${entry.reportsTo}" which is not present in this roster`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+export interface LoadProfilesOptions {
+  /** Override the profiles dir (tests). Defaults to <mosaicHome>/fleet/profiles. */
+  profilesDir?: string;
+  /** Override the roles dir (tests). Defaults to <mosaicHome>/fleet/roles. */
+  rolesDir?: string;
+  /** Persona override dir (tests). Defaults to <mosaicHome>/fleet/roles.local. */
+  overrideDir?: string;
+  mosaicHome?: string;
+}
+
+function resolveDirs(opts: LoadProfilesOptions): {
+  profilesDir: string;
+  rolesDir: string;
+  overrideDir: string;
+} {
+  const mosaicHome = opts.mosaicHome ?? defaultMosaicHome();
+  return {
+    profilesDir: opts.profilesDir ?? defaultProfilesDir(mosaicHome),
+    rolesDir: opts.rolesDir ?? defaultRolesDir(mosaicHome),
+    overrideDir: opts.overrideDir ?? defaultOverrideDir(mosaicHome),
+  };
+}
+
+/**
+ * Load, parse, and validate every profile yaml in the profiles dir. Throws if
+ * any profile is malformed, references an unknown class, or duplicates an id.
+ * Profiles are returned sorted by id for deterministic output.
+ */
+export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise<FleetProfile[]> {
+  const { profilesDir, rolesDir, overrideDir } = resolveDirs(opts);
+  let files: string[];
+  try {
+    files = (await readdir(profilesDir)).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'));
+  } catch {
+    throw new Error(`No fleet profiles directory at ${profilesDir}`);
+  }
+  files.sort();
+
+  // Override-aware: a profile may reference a user-customized or user-ADDED
+  // persona living in the roles.local/ layer (H4), so validate against the
+  // baseline ⊕ override union, not the baseline alone.
+  const validClasses = await listPersonaClassesWithOverrides(rolesDir, overrideDir);
+  const profiles: FleetProfile[] = [];
+  const seen = new Map<string, string>();
+
+  for (const file of files) {
+    const sourceId = basename(file, file.endsWith('.yaml') ? '.yaml' : '.yml');
+    const rawText = await readFile(join(profilesDir, file), 'utf8');
+    const profile = parseProfile(rawText, sourceId);
+
+    const prior = seen.get(profile.id);
+    if (prior) {
+      throw new Error(`Duplicate profile id "${profile.id}" in ${file} and ${prior}`);
+    }
+    seen.set(profile.id, file);
+
+    const problems = validateProfile(profile, validClasses);
+    if (problems.length > 0) {
+      throw new Error(`Profile ${file} is invalid:\n  - ${problems.join('\n  - ')}`);
+    }
+    profiles.push(profile);
+  }
+  return profiles;
+}
+
+/** Load and validate a single profile by id. Throws if not found. */
+export async function loadProfile(
+  id: string,
+  opts: LoadProfilesOptions = {},
+): Promise<FleetProfile> {
+  const profiles = await loadProfiles(opts);
+  const match = profiles.find((p) => p.id === id);
+  if (!match) {
+    const known = profiles.map((p) => p.id).join(', ') || '(none)';
+    throw new Error(`Unknown profile "${id}". Known profiles: ${known}`);
+  }
+  return match;
+}
+
+/** Total seat count of a roster, honoring multiplicity. */
+function rosterSize(profile: FleetProfile): number {
+  return profile.roster.reduce((sum, entry) => sum + entry.multiplicity, 0);
+}
+
+function printProfileList(profiles: FleetProfile[]): void {
+  if (profiles.length === 0) {
+    console.log('(no profiles)');
+    return;
+  }
+  for (const p of profiles) {
+    console.log(`${p.id}\t${p.title}\tlead=${p.lead}\troster=${rosterSize(p)}`);
+  }
+}
+
+function printProfileShow(profile: FleetProfile): void {
+  console.log(`${profile.id} — ${profile.title}`);
+  console.log(profile.description);
+  console.log('');
+  console.log(`lead: ${profile.lead}`);
+  console.log(`floor: ${profile.floor.join(', ') || '-'}`);
+  console.log(`roster (${rosterSize(profile)} seat(s)):`);
+  for (const entry of profile.roster) {
+    const reports = entry.reportsTo ? ` reports_to=${entry.reportsTo}` : '';
+    const mult = entry.multiplicity > 1 ? ` x${entry.multiplicity}` : '';
+    console.log(`  - ${entry.class}${mult}${reports}`);
+  }
+  if (profile.notes) {
+    console.log('');
+    console.log(`notes: ${profile.notes}`);
+  }
+}
+
+/**
+ * Register `profile` under an existing `fleet` command. `mosaicHomeFor` resolves
+ * the active --mosaic-home (parent flag) at call time, matching the backlog
+ * subcommand wiring. Validation errors exit non-zero with a readable message.
+ */
+export function registerFleetProfileCommand(
+  fleetCmd: Command,
+  mosaicHomeFor: () => string,
+): Command {
+  const profileCmd = fleetCmd
+    .command('profile')
+    .description('System-type profiles: declarative persona roster + topology (H2)');
+
+  profileCmd
+    .command('list')
+    .description('List available system-type profiles (id, title, lead, roster size)')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { json?: boolean }) => {
+      try {
+        const profiles = await loadProfiles({ mosaicHome: mosaicHomeFor() });
+        if (opts.json) {
+          console.log(JSON.stringify(profiles));
+          return;
+        }
+        printProfileList(profiles);
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  profileCmd
+    .command('show <id>')
+    .description('Show a profile: full roster with reports_to/multiplicity, floor, lead')
+    .option('--json', 'Print JSON')
+    .action(async (id: string, opts: { json?: boolean }) => {
+      try {
+        const profile = await loadProfile(id, { mosaicHome: mosaicHomeFor() });
+        if (opts.json) {
+          console.log(JSON.stringify(profile));
+          return;
+        }
+        printProfileShow(profile);
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  return profileCmd;
+}

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

@@ -82,6 +82,8 @@ describe('registerFleetCommand', () => {
       'init',
       'install',
       'install-systemd',
+      'persona',
+      'profile',
       'ps',
       'remove',
       'restart',
@@ -92,6 +94,28 @@ describe('registerFleetCommand', () => {
     ]);
   });
 
+  it('registers the profile subcommand with list and show', () => {
+    const program = buildProgram();
+    const fleet = program.commands.find((command) => command.name() === 'fleet');
+    const profile = fleet!.commands.find((command) => command.name() === 'profile');
+
+    expect(profile).toBeDefined();
+    expect(profile!.commands.map((command) => command.name()).sort()).toEqual(['list', 'show']);
+  });
+
+  it('registers the persona subcommand with list, show, and customize', () => {
+    const program = buildProgram();
+    const fleet = program.commands.find((command) => command.name() === 'fleet');
+    const persona = fleet!.commands.find((command) => command.name() === 'persona');
+
+    expect(persona).toBeDefined();
+    expect(persona!.commands.map((command) => command.name()).sort()).toEqual([
+      'customize',
+      'list',
+      'show',
+    ]);
+  });
+
   it('registers the backlog subcommand with its operations', () => {
     const program = buildProgram();
     const fleet = program.commands.find((command) => command.name() === 'fleet');
@@ -222,6 +246,8 @@ describe('fleet roster parsing', () => {
     expect(generateAgentEnv(roster, getRosterAgent(roster, 'coder0'))).toBe(
       [
         'MOSAIC_AGENT_NAME=coder0',
+        // Reflects the roster's non-default `class: implementer` (A3a).
+        'MOSAIC_AGENT_CLASS=implementer',
         'MOSAIC_AGENT_RUNTIME=codex',
         'MOSAIC_AGENT_MODEL=',
         'MOSAIC_AGENT_WORKDIR=/srv/mosaic',
@@ -231,6 +257,40 @@ describe('fleet roster parsing', () => {
     );
   });
 
+  it('emits MOSAIC_AGENT_CLASS=worker for an agent that declares no class', async () => {
+    cleanup = await tempDir();
+    const rosterPath = join(cleanup, 'roster.json');
+    await writeFile(
+      rosterPath,
+      JSON.stringify({
+        version: 1,
+        transport: 'tmux',
+        agents: [{ name: 'coder0', runtime: 'codex' }],
+      }),
+    );
+    const roster = await loadFleetRoster(rosterPath);
+    expect(generateAgentEnv(roster, getRosterAgent(roster, 'coder0'))).toContain(
+      'MOSAIC_AGENT_CLASS=worker\n',
+    );
+  });
+
+  it('shell-escapes MOSAIC_AGENT_CLASS so a launcher reads it verbatim', async () => {
+    cleanup = await tempDir();
+    const rosterPath = join(cleanup, 'roster.json');
+    await writeFile(
+      rosterPath,
+      JSON.stringify({
+        version: 1,
+        transport: 'tmux',
+        agents: [{ name: 'coder0', runtime: 'codex', class: 'orchestrator' }],
+      }),
+    );
+    const roster = await loadFleetRoster(rosterPath);
+    expect(generateAgentEnv(roster, getRosterAgent(roster, 'coder0'))).toContain(
+      'MOSAIC_AGENT_CLASS=orchestrator\n',
+    );
+  });
+
   it('preserves site-owned agent EnvironmentFile overrides while refreshing roster keys', () => {
     const generated = [
       'MOSAIC_AGENT_NAME=coder0',
@@ -262,6 +322,28 @@ describe('fleet roster parsing', () => {
     );
   });
 
+  it('updates (does not duplicate) MOSAIC_AGENT_CLASS on re-launch', () => {
+    const generated = [
+      'MOSAIC_AGENT_NAME=coder0',
+      'MOSAIC_AGENT_CLASS=orchestrator',
+      'MOSAIC_AGENT_RUNTIME=codex',
+      '',
+    ].join('\n');
+    const existing = [
+      'MOSAIC_AGENT_NAME=coder0',
+      'MOSAIC_AGENT_CLASS=worker',
+      'MOSAIC_AGENT_RUNTIME=codex',
+      '',
+    ].join('\n');
+
+    const merged = mergeAgentEnv(generated, existing);
+    // mergeAgentEnv keys by VAR name, so the regenerated CLASS wins and there is
+    // exactly one MOSAIC_AGENT_CLASS line (no stale worker value left behind).
+    expect(merged).toContain('MOSAIC_AGENT_CLASS=orchestrator');
+    expect(merged).not.toContain('MOSAIC_AGENT_CLASS=worker');
+    expect(merged.match(/^MOSAIC_AGENT_CLASS=/gm)).toHaveLength(1);
+  });
+
   it('rejects unknown roster fields instead of silently defaulting', async () => {
     cleanup = await tempDir();
     const rosterPath = join(cleanup, 'roster.yaml');

packages/mosaic/src/commands/fleet.ts

@@ -9,6 +9,8 @@ import type { Command } from 'commander';
 import YAML from 'yaml';
 import { resolveCommsBlock } from '../fleet/comms-onboarding.js';
 import { registerFleetBacklogCommand } from './fleet-backlog.js';
+import { registerFleetPersonaCommand } from './fleet-personas.js';
+import { registerFleetProfileCommand } from './fleet-profiles.js';
 
 /**
  * A function that spawns a command with inherited stdio (TTY passthrough).
@@ -488,6 +490,9 @@ export function generateAgentEnv(roster: FleetRoster, agent: FleetAgent): string
   const workingDirectory = agent.workingDirectory ?? roster.defaults.workingDirectory;
   return [
     `MOSAIC_AGENT_NAME=${shellEnvValue(agent.name)}`,
+    // Per-agent class → start-agent-session.sh / launcher reads this to inject the
+    // matching persona contract for the agent's class (default `worker`).
+    `MOSAIC_AGENT_CLASS=${shellEnvValue(agent.className)}`,
     `MOSAIC_AGENT_RUNTIME=${shellEnvValue(agent.runtime)}`,
     // Per-agent model hint → start-agent-session.sh appends `--model <hint>` to
     // the `mosaic yolo` launch so workers run on the roster's model (e.g. pi on
@@ -1706,6 +1711,15 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
   // fleet/ directory as the roster and heartbeats.
   registerFleetBacklogCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
 
+  // System-type profiles (H2): declarative persona roster + topology, resolved
+  // from <mosaicHome>/fleet/profiles/*.yaml using the same --mosaic-home flag.
+  registerFleetProfileCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
+
+  // Update-surviving persona overrides (H4): baseline fleet/roles/ ⊕ the
+  // PRESERVE-protected fleet/roles.local/ override layer, resolved via the same
+  // --mosaic-home flag.
+  registerFleetPersonaCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
+
   return cmd;
 }
 

packages/mosaic/src/commands/launch.ts

@@ -20,6 +20,7 @@ import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import type { Command } from 'commander';
 import { readFleetCommsBlock } from '../fleet/comms-onboarding.js';
+import { readPersonaContractBlock } from '../fleet/persona-contract.js';
 
 const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
 
@@ -384,6 +385,16 @@ For required push/merge/issue-close/release actions, execute without routine con
   // Runtime-specific contract
   parts.push('\n\n# Runtime-Specific Contract\n\n' + readFileSync(runtimeFile, 'utf-8'));
 
+  // Persona contract (A3b): when this agent was spawned with a class
+  // (MOSAIC_AGENT_CLASS, exported into the pane env by A3a), inject its resolved
+  // role contract so its identity (mandate + boundaries) is resident from the
+  // first turn. Override-aware via the persona resolver: a user-customized
+  // persona in fleet/roles.local/ wins over the baseline (AC-NS-7 launch proof).
+  // Placed BEFORE fleet comms: identity first, then how-to-reach-peers. No-ops
+  // silently when the class is unset/unknown (mirrors the comms block).
+  const persona = readPersonaContractBlock(mosaicHome, process.env['MOSAIC_AGENT_CLASS']);
+  if (persona) parts.push('\n\n' + persona);
+
   // Fleet onboarding: when this is a spawned fleet agent (MOSAIC_AGENT_NAME set
   // and present in the roster), inject a comms cheat-sheet + peer roster so it
   // knows how to reach the orchestrator and its peers from its first turn.

packages/mosaic/src/fleet/persona-contract.spec.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readPersonaContractBlock } from './persona-contract.js';
+
+/**
+ * Persona-contract launch injection (A3b). Asserts the override-aware resolver
+ * is wired so a customized persona in roles.local/ wins at launch (AC-NS-7), and
+ * that any miss (unset/empty/unknown class, missing file) no-ops silently —
+ * never throws — mirroring readFleetCommsBlock's tolerant contract.
+ */
+
+const BASELINE_CODER = `# Coder — fleet role definition
+
+The **coder** persona (\`class: coder\`, \`domain: engineering\`).
+
+## Mandate
+
+BASELINE-MANDATE: implement the assigned lane.
+`;
+
+const OVERRIDE_CODER = `# Coder — fleet role definition (override)
+
+The **coder** persona (\`class: coder\`).
+
+## Mandate
+
+OVERRIDE-MANDATE: implement the assigned lane, the user's way.
+`;
+
+function makeHome(): string {
+  const root = mkdtempSync(join(tmpdir(), 'mosaic-persona-'));
+  return join(root, 'mosaic-home');
+}
+
+function seedBaseline(home: string, klass: string, body: string): void {
+  const dir = join(home, 'fleet', 'roles');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${klass}.md`), body);
+}
+
+function seedOverride(home: string, klass: string, body: string): void {
+  const dir = join(home, 'fleet', 'roles.local');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${klass}.md`), body);
+}
+
+describe('readPersonaContractBlock — launch-time persona injection (A3b)', () => {
+  let home: string;
+
+  beforeEach(() => {
+    home = makeHome();
+  });
+
+  afterEach(() => {
+    // root is the parent of mosaic-home
+    rmSync(join(home, '..'), { recursive: true, force: true });
+  });
+
+  it('injects the baseline persona when the class has a fleet/roles/<class>.md', () => {
+    seedBaseline(home, 'coder', BASELINE_CODER);
+    const block = readPersonaContractBlock(home, 'coder');
+    expect(block).toContain('# Persona Contract (coder)');
+    expect(block).toContain('BASELINE-MANDATE');
+    expect(block).toContain('baseline `fleet/roles/` layer');
+  });
+
+  it('OVERRIDE WINS: roles.local/<class>.md content is injected over the baseline (AC-NS-7)', () => {
+    seedBaseline(home, 'coder', BASELINE_CODER);
+    seedOverride(home, 'coder', OVERRIDE_CODER);
+    const block = readPersonaContractBlock(home, 'coder');
+    expect(block).toContain('# Persona Contract (coder)');
+    expect(block).toContain('OVERRIDE-MANDATE'); // override body present
+    expect(block).not.toContain('BASELINE-MANDATE'); // baseline NOT used
+    expect(block).toContain('roles.local'); // layer note names the override layer
+  });
+
+  it('injects an override-only (user-added) persona with no baseline at all', () => {
+    seedOverride(home, 'reviewer', '# Reviewer\n\n(`class: reviewer`)\n\nCUSTOM-ROLE.\n');
+    const block = readPersonaContractBlock(home, 'reviewer');
+    expect(block).toContain('# Persona Contract (reviewer)');
+    expect(block).toContain('CUSTOM-ROLE');
+  });
+
+  it('no-ops (empty string) when the class is undefined', () => {
+    seedBaseline(home, 'coder', BASELINE_CODER);
+    expect(readPersonaContractBlock(home, undefined)).toBe('');
+  });
+
+  it('no-ops (empty string) when the class is empty/whitespace', () => {
+    seedBaseline(home, 'coder', BASELINE_CODER);
+    expect(readPersonaContractBlock(home, '')).toBe('');
+    expect(readPersonaContractBlock(home, '   ')).toBe('');
+  });
+
+  it('no-ops (empty string) for an unknown class with no role file', () => {
+    seedBaseline(home, 'coder', BASELINE_CODER);
+    expect(readPersonaContractBlock(home, 'nonexistent')).toBe('');
+  });
+
+  it('no-ops (empty string, no throw) when no roles directories exist at all', () => {
+    expect(() => readPersonaContractBlock(home, 'coder')).not.toThrow();
+    expect(readPersonaContractBlock(home, 'coder')).toBe('');
+  });
+});

packages/mosaic/src/fleet/persona-contract.ts

@@ -0,0 +1,63 @@
+/**
+ * Persona-contract injection at launch (North Star A3b).
+ *
+ * A spawned fleet agent should boot already knowing WHO it is: its class's role
+ * contract (mandate + boundaries). The companion goal A3a exports the agent's
+ * resolved class into the pane env as `MOSAIC_AGENT_CLASS`; here we read that
+ * class at launch (composeContract → system prompt) and inject the resolved
+ * persona contract so the identity is resident from the agent's first turn.
+ *
+ * OVERRIDE-AWARE: resolution goes through fleet-personas' resolver, so a
+ * user-customized persona in the PRESERVE-protected `fleet/roles.local/` layer
+ * WINS over the baseline `fleet/roles/` of the same class. That is the
+ * launch-time proof of AC-NS-7 — a customized persona actually reaches the model
+ * when the agent boots, not just in `mosaic fleet persona show`.
+ *
+ * Tolerant by contract (mirrors readFleetCommsBlock): an empty/missing class, an
+ * unknown class, or a missing role file all yield '' so the launcher no-ops
+ * silently. This MUST never throw during launch.
+ *
+ * Standalone module (no fleet.ts import) to keep launch.ts's prompt path free of
+ * the heavy fleet command module; it depends only on the lightweight persona
+ * resolver.
+ */
+
+import {
+  resolvePersonaSync,
+  defaultRolesDir,
+  defaultOverrideDir,
+} from '../commands/fleet-personas.js';
+
+/**
+ * Resolve `klass`'s persona contract (override-aware) and render it as a
+ * clearly-delimited launch block. Returns '' on any miss (falsy class, unknown
+ * class, missing/unreadable file) so composeContract can push it unconditionally
+ * and have it no-op silently. Never throws.
+ */
+export function readPersonaContractBlock(mosaicHome: string, klass: string | undefined): string {
+  if (!klass || !klass.trim()) return '';
+  let resolved: ReturnType<typeof resolvePersonaSync>;
+  try {
+    resolved = resolvePersonaSync(klass.trim(), {
+      rolesDir: defaultRolesDir(mosaicHome),
+      overrideDir: defaultOverrideDir(mosaicHome),
+    });
+  } catch {
+    // Best-effort onboarding: a resolver hiccup must not abort the launch.
+    return '';
+  }
+  if (!resolved) return '';
+
+  const layerNote =
+    resolved.layer === 'override'
+      ? '_(resolved from the `fleet/roles.local/` override layer — wins over baseline)_'
+      : '_(resolved from the baseline `fleet/roles/` layer)_';
+
+  return `# Persona Contract (${resolved.klass})
+
+${layerNote}
+
+You are operating as the **${resolved.klass}** persona. The role contract below is your identity — its mandate and boundaries govern what you own and what you must not do for this assignment.
+
+${resolved.content.trim()}`;
+}