test(#462): cover native RBAC personal scope intersection

apps/gateway/src/federation/federation.module.ts

@@ -6,7 +6,7 @@ import { EnrollmentService } from './enrollment.service.js';
 import { FederationController } from './federation.controller.js';
 import { GrantsService } from './grants.service.js';
 import { FederationClientService } from './client/index.js';
-import { FederationAuthGuard } from './server/index.js';
+import { FederationAuthGuard, FederationScopeService } from './server/index.js';
 
 @Module({
   controllers: [EnrollmentController, FederationController],
@@ -17,6 +17,7 @@ import { FederationAuthGuard } from './server/index.js';
     GrantsService,
     FederationClientService,
     FederationAuthGuard,
+    FederationScopeService,
   ],
   exports: [
     CaService,
@@ -24,6 +25,7 @@ import { FederationAuthGuard } from './server/index.js';
     GrantsService,
     FederationClientService,
     FederationAuthGuard,
+    FederationScopeService,
   ],
 })
 export class FederationModule {}

apps/gateway/src/federation/server/__tests__/scope.service.spec.ts

@@ -0,0 +1,324 @@
+/**
+ * Unit tests for FederationScopeService (FED-M3-04).
+ *
+ * Coverage:
+ *  - resource allowlist deny
+ *  - excluded resource deny
+ *  - invalid scope deny
+ *  - invalid requested limit deny
+ *  - native RBAC deny as subjectUserId
+ *  - scope/native filter intersection for personal and team rows
+ *  - native RBAC personal deny wins over scope include_personal allow/default
+ *  - max_rows_per_query cap
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { FederationScopeService, type FederationNativeRbacEvaluator } from '../scope.service.js';
+import type { FederationContext } from '../federation-context.js';
+
+const GRANT_ID = 'grant-1';
+const PEER_ID = 'peer-1';
+const SUBJECT_USER_ID = 'user-1';
+
+function makeContext(scope: Record<string, unknown>): FederationContext {
+  return {
+    grantId: GRANT_ID,
+    peerId: PEER_ID,
+    subjectUserId: SUBJECT_USER_ID,
+    scope,
+  };
+}
+
+function makeNativeRbac(
+  result: Awaited<ReturnType<FederationNativeRbacEvaluator['evaluateReadAccess']>>,
+): FederationNativeRbacEvaluator {
+  return {
+    evaluateReadAccess: vi.fn().mockResolvedValue(result),
+  };
+}
+
+describe('FederationScopeService', () => {
+  let service: FederationScopeService;
+
+  beforeEach(() => {
+    service = new FederationScopeService();
+  });
+
+  it('allows a granted resource and returns a capped query filter', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: ['team-1', 'team-2'] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['tasks'],
+        filters: { tasks: { include_teams: ['team-1', 'team-3'], include_personal: true } },
+        max_rows_per_query: 50,
+      }),
+      resource: 'tasks',
+      requestedLimit: 500,
+      nativeRbac,
+    });
+
+    expect(result).toEqual({
+      allowed: true,
+      filter: {
+        resource: 'tasks',
+        subjectUserId: SUBJECT_USER_ID,
+        includePersonal: true,
+        teamIds: ['team-1'],
+        limit: 50,
+        maxRowsPerQuery: 50,
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).toHaveBeenCalledWith({
+      grantId: GRANT_ID,
+      peerId: PEER_ID,
+      subjectUserId: SUBJECT_USER_ID,
+      resource: 'tasks',
+    });
+  });
+
+  it('defaults absent resource filters to native RBAC personal and team visibility', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['notes'], max_rows_per_query: 100 }),
+      resource: 'notes',
+      nativeRbac: makeNativeRbac({
+        allowed: true,
+        access: { includePersonal: true, teamIds: ['team-1', 'team-2'] },
+      }),
+    });
+
+    expect(result).toMatchObject({
+      allowed: true,
+      filter: {
+        includePersonal: true,
+        teamIds: ['team-1', 'team-2'],
+        limit: 100,
+      },
+    });
+  });
+
+  it('honors include_personal false even when native RBAC allows personal rows', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['memory'],
+        filters: { memory: { include_personal: false } },
+        max_rows_per_query: 25,
+      }),
+      resource: 'memory',
+      nativeRbac: makeNativeRbac({
+        allowed: true,
+        access: { includePersonal: true, teamIds: [] },
+      }),
+    });
+
+    expect(result).toMatchObject({
+      allowed: true,
+      filter: {
+        includePersonal: false,
+        teamIds: [],
+      },
+    });
+  });
+
+  it('does not leak personal rows when scope allows personal but native RBAC denies personal', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['tasks'],
+        filters: { tasks: { include_personal: true } },
+        max_rows_per_query: 25,
+      }),
+      resource: 'tasks',
+      nativeRbac: makeNativeRbac({
+        allowed: true,
+        access: { includePersonal: false, teamIds: ['team-1'] },
+      }),
+    });
+
+    expect(result).toMatchObject({
+      allowed: true,
+      filter: {
+        includePersonal: false,
+        teamIds: ['team-1'],
+      },
+    });
+  });
+
+  it('does not widen native RBAC when scope includes teams the user cannot access', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['tasks'],
+        filters: { tasks: { include_teams: ['team-2'], include_personal: false } },
+        max_rows_per_query: 25,
+      }),
+      resource: 'tasks',
+      nativeRbac: makeNativeRbac({
+        allowed: true,
+        access: { includePersonal: true, teamIds: ['team-1'] },
+      }),
+    });
+
+    expect(result).toMatchObject({
+      allowed: true,
+      filter: {
+        includePersonal: false,
+        teamIds: [],
+      },
+    });
+  });
+
+  it('denies invalid grant scope before RBAC evaluation', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: [], max_rows_per_query: 100 }),
+      resource: 'tasks',
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'invalid_scope',
+        stage: 'scope_parse',
+        statusCode: 400,
+        grantId: GRANT_ID,
+        subjectUserId: SUBJECT_USER_ID,
+        resource: 'tasks',
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies unsupported resource names before RBAC evaluation', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
+      resource: 'unknown_resource',
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'invalid_resource',
+        stage: 'resource_allowlist',
+        statusCode: 403,
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies resources explicitly present in excluded_resources before allowlist miss', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['tasks'],
+        excluded_resources: ['credentials'],
+        max_rows_per_query: 100,
+      }),
+      resource: 'credentials',
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'resource_excluded',
+        stage: 'resource_exclusion',
+        statusCode: 403,
+        resource: 'credentials',
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies supported resources that are not granted by scope', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
+      resource: 'notes',
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'resource_not_granted',
+        stage: 'resource_allowlist',
+        statusCode: 403,
+        resource: 'notes',
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies invalid requested row limits before RBAC evaluation', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
+      resource: 'tasks',
+      requestedLimit: 0,
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'invalid_limit',
+        stage: 'row_cap',
+        statusCode: 400,
+        details: { requestedLimit: 0 },
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies when native RBAC rejects subjectUserId access to the resource', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
+      resource: 'tasks',
+      nativeRbac: makeNativeRbac({
+        allowed: false,
+        reason: 'read:tasks denied',
+        details: { permission: 'tasks:read' },
+      }),
+    });
+
+    expect(result).toEqual({
+      allowed: false,
+      deny: {
+        code: 'native_rbac_denied',
+        stage: 'native_rbac',
+        statusCode: 403,
+        message: 'read:tasks denied',
+        grantId: GRANT_ID,
+        peerId: PEER_ID,
+        subjectUserId: SUBJECT_USER_ID,
+        resource: 'tasks',
+        details: { permission: 'tasks:read' },
+      },
+    });
+  });
+});

apps/gateway/src/federation/server/index.ts

@@ -10,4 +10,22 @@
  */
 
 export { FederationAuthGuard } from './federation-auth.guard.js';
+export { FederationScopeService } from './scope.service.js';
 export type { FederationContext } from './federation-context.js';
+export type {
+  FederationNativeRbacAccess,
+  FederationNativeRbacAllowedResult,
+  FederationNativeRbacDeniedResult,
+  FederationNativeRbacEvaluator,
+  FederationNativeRbacRequest,
+  FederationNativeRbacResult,
+  FederationScopeAllowedResult,
+  FederationScopeDeniedResult,
+  FederationScopeDenyCode,
+  FederationScopeDenyDetails,
+  FederationScopeDenyReason,
+  FederationScopeDenyStage,
+  FederationScopeEvaluationInput,
+  FederationScopeEvaluationResult,
+  FederationScopeQueryFilter,
+} from './scope.service.js';

apps/gateway/src/federation/server/scope.service.ts

@@ -0,0 +1,272 @@
+/**
+ * FederationScopeService — M3 server-side scope enforcement pipeline.
+ *
+ * Pure trust-boundary service: it validates the grant scope, asks an injected
+ * native RBAC evaluator what the subject user can read locally, intersects that
+ * answer with the federation scope filters, and returns a query filter for the
+ * verb controllers. The service performs no DB calls directly.
+ */
+
+import { Injectable } from '@nestjs/common';
+import {
+  FEDERATION_RESOURCE_VALUES,
+  type FederationResource,
+  FederationScopeError,
+  parseFederationScope,
+} from '../scope-schema.js';
+import type { FederationContext } from './federation-context.js';
+
+const federationResourceSet: ReadonlySet<string> = new Set<string>(FEDERATION_RESOURCE_VALUES);
+
+export type FederationScopeDenyStage =
+  | 'scope_parse'
+  | 'resource_allowlist'
+  | 'resource_exclusion'
+  | 'native_rbac'
+  | 'row_cap';
+
+export type FederationScopeDenyCode =
+  | 'invalid_scope'
+  | 'invalid_resource'
+  | 'resource_not_granted'
+  | 'resource_excluded'
+  | 'native_rbac_denied'
+  | 'invalid_limit';
+
+export type FederationScopeDenyStatus = 400 | 403;
+
+export interface FederationScopeDenyDetails {
+  readonly [key: string]: string | number | boolean | readonly string[];
+}
+
+export interface FederationScopeDenyReason {
+  readonly code: FederationScopeDenyCode;
+  readonly stage: FederationScopeDenyStage;
+  readonly statusCode: FederationScopeDenyStatus;
+  readonly message: string;
+  readonly grantId: string;
+  readonly peerId: string;
+  readonly subjectUserId: string;
+  readonly resource: string;
+  readonly details?: FederationScopeDenyDetails;
+}
+
+export interface FederationNativeRbacRequest {
+  readonly grantId: string;
+  readonly peerId: string;
+  readonly subjectUserId: string;
+  readonly resource: FederationResource;
+}
+
+export interface FederationNativeRbacAccess {
+  /** Whether this user may read personal rows for this resource. */
+  readonly includePersonal: boolean;
+
+  /** Team IDs this user may read for this resource under native RBAC. */
+  readonly teamIds: readonly string[];
+}
+
+export interface FederationNativeRbacAllowedResult {
+  readonly allowed: true;
+  readonly access: FederationNativeRbacAccess;
+}
+
+export interface FederationNativeRbacDeniedResult {
+  readonly allowed: false;
+  readonly reason?: string;
+  readonly details?: FederationScopeDenyDetails;
+}
+
+export type FederationNativeRbacResult =
+  | FederationNativeRbacAllowedResult
+  | FederationNativeRbacDeniedResult;
+
+export interface FederationNativeRbacEvaluator {
+  evaluateReadAccess(request: FederationNativeRbacRequest): Promise<FederationNativeRbacResult>;
+}
+
+export interface FederationScopeEvaluationInput {
+  readonly context: FederationContext;
+  readonly resource: string;
+  readonly requestedLimit?: number;
+  readonly nativeRbac: FederationNativeRbacEvaluator;
+}
+
+export interface FederationScopeQueryFilter {
+  readonly resource: FederationResource;
+  readonly subjectUserId: string;
+  readonly includePersonal: boolean;
+  readonly teamIds: readonly string[];
+  readonly limit: number;
+  readonly maxRowsPerQuery: number;
+}
+
+export interface FederationScopeAllowedResult {
+  readonly allowed: true;
+  readonly filter: FederationScopeQueryFilter;
+}
+
+export interface FederationScopeDeniedResult {
+  readonly allowed: false;
+  readonly deny: FederationScopeDenyReason;
+}
+
+export type FederationScopeEvaluationResult =
+  | FederationScopeAllowedResult
+  | FederationScopeDeniedResult;
+
+function isFederationResource(resource: string): resource is FederationResource {
+  return federationResourceSet.has(resource);
+}
+
+function uniqueStrings(values: readonly string[]): readonly string[] {
+  return Array.from(new Set<string>(values));
+}
+
+function intersectTeamIds(
+  nativeTeamIds: readonly string[],
+  scopedTeamIds: readonly string[] | undefined,
+): readonly string[] {
+  const uniqueNativeTeamIds = uniqueStrings(nativeTeamIds);
+
+  if (scopedTeamIds === undefined) {
+    return uniqueNativeTeamIds;
+  }
+
+  const nativeSet = new Set<string>(uniqueNativeTeamIds);
+  return uniqueStrings(scopedTeamIds).filter((teamId: string): boolean => nativeSet.has(teamId));
+}
+
+function makeDenyReason(params: {
+  readonly code: FederationScopeDenyCode;
+  readonly stage: FederationScopeDenyStage;
+  readonly statusCode?: FederationScopeDenyStatus;
+  readonly message: string;
+  readonly context: FederationContext;
+  readonly resource: string;
+  readonly details?: FederationScopeDenyDetails;
+}): FederationScopeDeniedResult {
+  return {
+    allowed: false,
+    deny: {
+      code: params.code,
+      stage: params.stage,
+      statusCode: params.statusCode ?? 403,
+      message: params.message,
+      grantId: params.context.grantId,
+      peerId: params.context.peerId,
+      subjectUserId: params.context.subjectUserId,
+      resource: params.resource,
+      ...(params.details !== undefined ? { details: params.details } : {}),
+    },
+  };
+}
+
+@Injectable()
+export class FederationScopeService {
+  async evaluateAccess(
+    input: FederationScopeEvaluationInput,
+  ): Promise<FederationScopeEvaluationResult> {
+    const { context, resource, requestedLimit, nativeRbac } = input;
+
+    let scope: ReturnType<typeof parseFederationScope>;
+    try {
+      scope = parseFederationScope(context.scope);
+    } catch (error: unknown) {
+      const message =
+        error instanceof FederationScopeError
+          ? 'Federation grant scope is invalid'
+          : 'Federation grant scope could not be parsed';
+      const details = error instanceof Error ? { reason: error.message } : undefined;
+      return makeDenyReason({
+        code: 'invalid_scope',
+        stage: 'scope_parse',
+        statusCode: 400,
+        message,
+        context,
+        resource,
+        ...(details !== undefined ? { details } : {}),
+      });
+    }
+
+    if (!isFederationResource(resource)) {
+      return makeDenyReason({
+        code: 'invalid_resource',
+        stage: 'resource_allowlist',
+        message: 'Requested federation resource is not supported',
+        context,
+        resource,
+        details: { supportedResources: FEDERATION_RESOURCE_VALUES },
+      });
+    }
+
+    if (scope.excluded_resources.includes(resource)) {
+      return makeDenyReason({
+        code: 'resource_excluded',
+        stage: 'resource_exclusion',
+        message: 'Requested federation resource is explicitly excluded by grant scope',
+        context,
+        resource,
+      });
+    }
+
+    if (!scope.resources.includes(resource)) {
+      return makeDenyReason({
+        code: 'resource_not_granted',
+        stage: 'resource_allowlist',
+        message: 'Requested federation resource is not granted by scope',
+        context,
+        resource,
+        details: { grantedResources: scope.resources },
+      });
+    }
+
+    if (requestedLimit !== undefined && (!Number.isInteger(requestedLimit) || requestedLimit < 1)) {
+      return makeDenyReason({
+        code: 'invalid_limit',
+        stage: 'row_cap',
+        statusCode: 400,
+        message: 'Requested row limit must be a positive integer',
+        context,
+        resource,
+        details: { requestedLimit },
+      });
+    }
+
+    const nativeResult = await nativeRbac.evaluateReadAccess({
+      grantId: context.grantId,
+      peerId: context.peerId,
+      subjectUserId: context.subjectUserId,
+      resource,
+    });
+
+    if (!nativeResult.allowed) {
+      return makeDenyReason({
+        code: 'native_rbac_denied',
+        stage: 'native_rbac',
+        message: nativeResult.reason ?? 'Subject user is not allowed to read this resource',
+        context,
+        resource,
+        ...(nativeResult.details !== undefined ? { details: nativeResult.details } : {}),
+      });
+    }
+
+    const scopeFilter = scope.filters?.[resource];
+    const includePersonal =
+      Boolean(scopeFilter?.include_personal ?? true) && nativeResult.access.includePersonal;
+    const teamIds = intersectTeamIds(nativeResult.access.teamIds, scopeFilter?.include_teams);
+    const limit = Math.min(requestedLimit ?? scope.max_rows_per_query, scope.max_rows_per_query);
+
+    return {
+      allowed: true,
+      filter: {
+        resource,
+        subjectUserId: context.subjectUserId,
+        includePersonal,
+        teamIds,
+        limit,
+        maxRowsPerQuery: scope.max_rows_per_query,
+      },
+    };
+  }
+}

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

docs/scratchpads/462-fed-m3-04-scope-service.md

@@ -0,0 +1,60 @@
+# Scratchpad — FED-M3-04 Scope Service
+
+## Objective
+
+Implement `apps/gateway/src/federation/server/scope.service.ts` for the M3 inbound federation scope-enforcement pipeline.
+
+## Scope / Constraints
+
+- Task: FED-M3-04, issue #462.
+- Branch: `feat/federation-m3-scope-service` from `origin/main` @ 0.0.48.
+- Pure service: no direct DB access; native RBAC/data access is injected per evaluation call.
+- Reuse `parseFederationScope` from M2-03.
+- Workers do not edit `docs/federation/TASKS.md` per repo AGENTS.md.
+
+## Acceptance Criteria
+
+1. Resource allowlist and `excluded_resources` enforced.
+2. Native RBAC evaluated as `subjectUserId` through an injected evaluator.
+3. Scope filter intersection supports `include_teams` and `include_personal` without widening native RBAC.
+4. `max_rows_per_query` caps requested limits.
+5. Service returns `{ allowed: true, filter }` or a structured deny reason usable by M4 audit.
+6. Unit tests cover every deny path.
+
+## Plan
+
+1. Inspect existing federation scope/schema/auth guard contracts.
+2. Add pure `FederationScopeService` plus typed result/filter/deny interfaces.
+3. Add focused unit tests for happy paths, filter intersection, row cap, and deny paths.
+4. Export/register service for future verb controllers.
+5. Run situational tests, baseline gates, code review, then PR.
+
+## Budget
+
+- Provided model tier: sonnet.
+- Estimate from task row: 10K tokens.
+- Working cap assumption: keep implementation focused to FED-M3-04 surfaces only.
+
+## Progress
+
+- Intake complete; dirty base worktree avoided by creating isolated worktree at `/home/jarvis/src/mosaic-mono-v1-fed-m3-04`.
+- Project PRD and federation task spec reviewed.
+- Added `FederationScopeService` with structured allow/deny result types and injected native RBAC evaluator contract.
+- Added unit coverage for happy path, row cap, filter intersection, and every deny path.
+- Exported/registered the service for upcoming M3 verb controllers.
+
+## Verification Evidence
+
+- `pnpm --filter @mosaicstack/gateway test -- src/federation/server/__tests__/scope.service.spec.ts` — pass (10 tests before review update; 11 tests after adding include_personal no-leak coverage).
+- `pnpm build` — pass (23 successful tasks).
+- `pnpm typecheck` — pass (41 successful tasks; re-run after review update).
+- `pnpm lint` — pass (23 successful tasks; re-run after review update).
+- `pnpm format:check` — pass (re-run after review update).
+- `pnpm test` — pass after starting local `postgres`/`valkey` and running `pnpm --filter @mosaicstack/db db:push` for the DB-backed cross-user isolation suite (41 successful tasks; gateway 477 passed / 11 skipped).
+- Code review: `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings.
+- Security review: `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — risk none, 0 findings.
+
+## Risks / Blockers
+
+- Issue #462 is already closed in provider output; likely milestone tracking mismatch. Will still reference #462 in PR body unless orchestrator redirects.
+- Local full-test setup required `docker compose up -d postgres valkey` + `db:push`; containers were stopped with `docker compose down` after verification.

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/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.48",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",

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

@@ -234,6 +234,21 @@ export async function resolvePersona(
     extractClassesFromDir(rolesDir),
     extractClassesFromDir(overrideDir),
   ]);
+  return resolvePersonaFrom(klass, { rolesDir, overrideDir, base, over });
+}
+
+/**
+ * Resolve a single class against ALREADY-EXTRACTED layer maps. Callers that
+ * resolve many classes against the same two directories (e.g. provisioning a
+ * full roster) should {@link extractClassesFromDir} each dir ONCE and reuse the
+ * result here, rather than paying a full directory re-scan per class. Precedence
+ * is identical to {@link resolvePersona}: override layer wins, then baseline.
+ */
+export async function resolvePersonaFrom(
+  klass: string,
+  layers: { rolesDir: string; overrideDir: string; base: DirClasses; over: DirClasses },
+): Promise<PersonaResolution | null> {
+  const { rolesDir, overrideDir, base, over } = layers;
 
   const fromLayer = async (
     dir: string,

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

@@ -0,0 +1,270 @@
+import { access, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { loadFleetRoster } from './fleet.js';
+import { generateRoster, runProvision } from './fleet-provision.js';
+import { loadProfile } from './fleet-profiles.js';
+
+// These are INTEGRATION tests: each exercises real filesystem I/O — scanning the
+// committed framework/fleet persona library, rendering YAML, writing to a temp
+// mosaicHome, and round-tripping through the real roster parser. On a heavily
+// contended CI runner (the whole monorepo's suites run in parallel) that genuine
+// I/O can exceed vitest's 5s default even though it completes in ~400ms locally.
+// Give the legitimately I/O-bound work generous headroom so CI is deterministic.
+vi.setConfig({ testTimeout: 30_000 });
+
+// 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');
+
+/** A fresh temp mosaicHome whose fleet/ dir is empty (for write-path tests). */
+async function freshMosaicHome(): Promise<string> {
+  const home = await mkdtemp(join(tmpdir(), 'mosaic-provision-'));
+  await mkdir(join(home, 'fleet'), { recursive: true });
+  return home;
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe('provision software-delivery (floor, default)', () => {
+  it('materializes only the floor seats with correct flags + valid scaffold', async () => {
+    const profile = await loadProfile('software-delivery', { profilesDir, rolesDir });
+    const { seats, yaml } = await generateRoster(profile, { profilesDir, rolesDir });
+
+    // Floor is orchestrator + enhancer.
+    expect(seats.map((s) => s.name).sort()).toEqual(['enhancer', 'orchestrator']);
+    const orch = seats.find((s) => s.name === 'orchestrator');
+    const enh = seats.find((s) => s.name === 'enhancer');
+    // RULE 2: floor + lead get persistent_persona.
+    expect(orch?.persistentPersona).toBe(true);
+    expect(enh?.persistentPersona).toBe(true);
+    // RULE 3: floor/lead do NOT reset between tasks.
+    expect(orch?.resetBetweenTasks).toBeUndefined();
+    expect(enh?.resetBetweenTasks).toBeUndefined();
+    // RULE 4: default runtime claude.
+    expect(orch?.runtime).toBe('claude');
+
+    // Scaffold round-trips through the real parser.
+    expect(yaml).toContain('version: 1');
+    expect(yaml).toContain('transport: tmux');
+    expect(yaml).toContain('socket_name: mosaic-fleet');
+  });
+});
+
+describe('provision --full', () => {
+  it('expands the entire roster, including multiplicity, deterministically', async () => {
+    const profile = await loadProfile('software-delivery', { profilesDir, rolesDir });
+    const { seats } = await generateRoster(profile, { full: true, profilesDir, rolesDir });
+
+    const names = seats.map((s) => s.name);
+    // code multiplicity 2 -> code0/code1 (RULE 1).
+    expect(names).toContain('code0');
+    expect(names).toContain('code1');
+    expect(names).not.toContain('code');
+    // Singleton seats keep the bare class name.
+    expect(names).toContain('planner');
+    expect(names).toContain('merge-gate');
+
+    // Deterministic ordering: profile roster order, multiplicity expanded inline.
+    const codeIdx0 = names.indexOf('code0');
+    expect(names[codeIdx0 + 1]).toBe('code1');
+
+    // RULE 3: a non-floor, non-lead execution seat resets between tasks.
+    const code0 = seats.find((s) => s.name === 'code0');
+    expect(code0?.resetBetweenTasks).toBe(true);
+    expect(code0?.persistentPersona).toBeUndefined();
+
+    // Seat count == sum of multiplicities.
+    const expected = profile.roster.reduce((n, e) => n + e.multiplicity, 0);
+    expect(seats.length).toBe(expected);
+  });
+});
+
+describe('generated roster round-trips through the real parser', () => {
+  it('feeds generated YAML back through loadFleetRoster (key correctness proof)', async () => {
+    const home = await freshMosaicHome();
+    try {
+      const result = await runProvision('software-delivery', {
+        mosaicHome: home,
+        profilesDir,
+        rolesDir,
+        full: true,
+        write: true,
+      });
+      expect(result.wrote).toBe(join(home, 'fleet', 'roster.yaml'));
+
+      const parsed = await loadFleetRoster(result.wrote!);
+      // It parses with no error and carries every seat.
+      const profile = await loadProfile('software-delivery', { profilesDir, rolesDir });
+      const expected = profile.roster.reduce((n, e) => n + e.multiplicity, 0);
+      expect(parsed.agents.length).toBe(expected);
+      // Classes survive the round-trip.
+      expect(parsed.agents.some((a) => a.className === 'orchestrator')).toBe(true);
+      expect(parsed.agents.filter((a) => a.className === 'code').length).toBe(2);
+      // reports_to must NOT have been emitted (parser rejects unknown keys).
+      expect(result.yaml).not.toContain('reports_to');
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('override-aware persona validation', () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'mosaic-provision-ov-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('resolves a user-added (roles.local-only) persona without a false unresolved error', async () => {
+    const overrideDir = join(dir, 'roles.local');
+    const customProfilesDir = join(dir, 'profiles');
+    await mkdir(overrideDir, { recursive: true });
+    await mkdir(customProfilesDir, { recursive: true });
+    // A brand-new class that exists ONLY in roles.local.
+    await writeFile(
+      join(overrideDir, 'widget-maker.md'),
+      '# widget-maker\n\nThe widget-maker persona (`class: widget-maker`).\n',
+    );
+    await writeFile(
+      join(customProfilesDir, 'custom.yaml'),
+      [
+        'id: custom',
+        'title: Custom',
+        'description: a custom system',
+        'lead: widget-maker',
+        'floor: [widget-maker]',
+        'roster:',
+        '  - class: widget-maker',
+        '',
+      ].join('\n'),
+    );
+
+    const result = await runProvision('custom', {
+      mosaicHome: dir,
+      profilesDir: customProfilesDir,
+      // Point baseline rolesDir at a missing dir so resolution depends on override.
+      rolesDir: join(dir, 'no-baseline'),
+      overrideDir,
+    });
+    expect(result.yaml).toContain('class: widget-maker');
+    // It resolved from the override layer.
+    // (generateRoster records personaLayer; the seat is present.)
+    expect(result.summary).toContain('persona=override');
+  });
+
+  it('FAILS with a clear message when a profile references a bogus class', async () => {
+    const customProfilesDir = join(dir, 'profiles');
+    await mkdir(customProfilesDir, { recursive: true });
+    await writeFile(
+      join(customProfilesDir, 'bogus.yaml'),
+      [
+        'id: bogus',
+        'title: Bogus',
+        'description: bad system',
+        'lead: orchestrator',
+        'floor: [orchestrator]',
+        'roster:',
+        '  - class: orchestrator',
+        '  - class: not-a-real-persona-xyz',
+        '    reports_to: orchestrator',
+        '',
+      ].join('\n'),
+    );
+    await expect(
+      runProvision('bogus', {
+        mosaicHome: dir,
+        profilesDir: customProfilesDir,
+        rolesDir,
+        overrideDir: join(dir, 'roles.local'),
+      }),
+    ).rejects.toThrow(/not-a-real-persona-xyz|not a known persona class/);
+  });
+});
+
+describe('--write protection', () => {
+  it('refuses to clobber an existing roster.yaml without --force', async () => {
+    const home = await freshMosaicHome();
+    try {
+      const rosterPath = join(home, 'fleet', 'roster.yaml');
+      await writeFile(rosterPath, 'version: 1\n# operator customizations\n');
+      await expect(
+        runProvision('software-delivery', { mosaicHome: home, profilesDir, rolesDir, write: true }),
+      ).rejects.toThrow(/Refusing to overwrite/);
+      // The original file is untouched.
+      const { readFile } = await import('node:fs/promises');
+      expect(await readFile(rosterPath, 'utf8')).toContain('operator customizations');
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  it('--write --force overwrites an existing roster', async () => {
+    const home = await freshMosaicHome();
+    try {
+      const rosterPath = join(home, 'fleet', 'roster.yaml');
+      await writeFile(rosterPath, 'version: 1\n# old\n');
+      const result = await runProvision('software-delivery', {
+        mosaicHome: home,
+        profilesDir,
+        rolesDir,
+        write: true,
+        force: true,
+      });
+      expect(result.wrote).toBe(rosterPath);
+      const parsed = await loadFleetRoster(rosterPath);
+      expect(parsed.agents.length).toBeGreaterThan(0);
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  it('--write to a fresh mosaicHome creates the roster file', async () => {
+    const home = await freshMosaicHome();
+    try {
+      const result = await runProvision('software-delivery', {
+        mosaicHome: home,
+        profilesDir,
+        rolesDir,
+        write: true,
+      });
+      expect(await fileExists(result.wrote!)).toBe(true);
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  it('dry run (no --write) writes nothing', async () => {
+    const home = await freshMosaicHome();
+    try {
+      const result = await runProvision('software-delivery', {
+        mosaicHome: home,
+        profilesDir,
+        rolesDir,
+      });
+      expect(result.wrote).toBeUndefined();
+      expect(await fileExists(join(home, 'fleet', 'roster.yaml'))).toBe(false);
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -0,0 +1,406 @@
+/**
+ * `mosaic fleet provision --profile <id>` — turn a declared SYSTEM TYPE (a
+ * profile) into a concrete fleet roster (North Star H3).
+ *
+ * A profile (fleet/profiles/<id>.yaml) is a DECLARATIVE mapping from a system
+ * type to a persona roster + org topology (H2). This command MATERIALIZES that
+ * declaration into the concrete `roster.yaml` shape the live fleet consumes — the
+ * same shape `fleet.ts` parses (version/transport/tmux/defaults/runtimes/agents).
+ *
+ * DRY-RUN-FIRST + REVIEWABLE: with no --write it prints the roster it WOULD
+ * generate plus a topology summary and writes nothing. --write persists it, and
+ * REFUSES to clobber an existing roster.yaml without --force (protects operator
+ * customizations).
+ *
+ * DRY: profile parsing/validation is reused wholesale from fleet-profiles.ts
+ * (loadProfile/validateProfile) and persona resolution from fleet-personas.ts
+ * (resolvePersona, override-aware). This module owns ONLY the profile→roster
+ * generation policy, documented inline below so each default is reviewable.
+ */
+
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import type { Command } from 'commander';
+import YAML from 'yaml';
+import {
+  loadProfile,
+  validateProfile,
+  type FleetProfile,
+  type ProfileRosterEntry,
+  defaultProfilesDir,
+  defaultRolesDir,
+  listPersonaClassesWithOverrides,
+} from './fleet-profiles.js';
+import {
+  defaultOverrideDir,
+  extractClassesFromDir,
+  resolvePersonaFrom,
+  type PersonaLayer,
+} from './fleet-personas.js';
+
+function defaultMosaicHome(): string {
+  return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
+}
+
+// ---------------------------------------------------------------------------
+// GENERATION RULES — each default below is intentionally simple and documented
+// so a reviewer can ratify or override the policy. See the PR body for the open
+// runtime-per-class question (RULE 4).
+// ---------------------------------------------------------------------------
+
+/**
+ * RULE 4 — Runtime assignment policy (THE one open design question).
+ *
+ * Default: EVERY seat → `runtime: claude`. Claude runs every persona, so it is
+ * the safe universal default and guarantees a structurally-valid, launchable
+ * roster regardless of how the policy ultimately lands. We deliberately do NOT
+ * hardcode pi / gpt-5.5 per class here. The live roster today runs coders on
+ * pi + openai-codex/gpt-5.5:high — whether provisioning should encode a
+ * class→runtime/model map (and WHERE: the profile schema vs a separate
+ * runtime-policy file) is flagged in the PR body for ratification.
+ *
+ * Centralized so changing the policy is a ONE-edit change. If a future profile
+ * entry (or persona) declares a runtime/model preference, honor it here; until
+ * then everything defaults to claude.
+ */
+export const DEFAULT_RUNTIME = 'claude';
+
+/** Result of applying the runtime policy to one seat. */
+interface RuntimeChoice {
+  runtime: string;
+  modelHint?: string;
+}
+
+/**
+ * The single centralized runtime-policy function. Today it returns the universal
+ * `claude` default for every seat. To encode a class→runtime/model map later,
+ * edit ONLY this function (and/or extend the profile schema and read it here).
+ */
+export function resolveSeatRuntime(
+  _klass: string,
+  _isFloor: boolean,
+  _isLead: boolean,
+): RuntimeChoice {
+  return { runtime: DEFAULT_RUNTIME };
+}
+
+/** One generated seat, fully resolved for emission + topology display. */
+export interface GeneratedSeat {
+  name: string;
+  className: string;
+  runtime: string;
+  modelHint?: string;
+  persistentPersona?: boolean;
+  resetBetweenTasks?: boolean;
+  /** Topology edge from the profile (NOT emitted to roster.yaml — see RULE 6). */
+  reportsTo?: string;
+  /** Which persona layer the class resolved from (baseline/override). */
+  personaLayer: PersonaLayer;
+}
+
+export interface GenerateRosterResult {
+  seats: GeneratedSeat[];
+  /** The roster.yaml text (parser-valid, drop-in). */
+  yaml: string;
+}
+
+export interface ProvisionOptions {
+  /** Materialize the entire profile roster (multiplicity expanded). */
+  full?: boolean;
+  mosaicHome?: string;
+  /** Test overrides — mirror fleet-profiles LoadProfilesOptions. */
+  profilesDir?: string;
+  rolesDir?: string;
+  overrideDir?: string;
+}
+
+function resolveDirs(opts: ProvisionOptions): {
+  mosaicHome: string;
+  profilesDir: string;
+  rolesDir: string;
+  overrideDir: string;
+} {
+  const mosaicHome = opts.mosaicHome ?? defaultMosaicHome();
+  return {
+    mosaicHome,
+    profilesDir: opts.profilesDir ?? defaultProfilesDir(mosaicHome),
+    rolesDir: opts.rolesDir ?? defaultRolesDir(mosaicHome),
+    overrideDir: opts.overrideDir ?? defaultOverrideDir(mosaicHome),
+  };
+}
+
+/**
+ * RULE 1 — Seat naming. multiplicity 1 → name = class (e.g. `planner`).
+ * multiplicity N>1 → `<class>0`,`<class>1`,… (e.g. `code` ×2 → code0/code1).
+ * Names are deterministic, following profile roster order.
+ */
+function seatNames(entry: ProfileRosterEntry): string[] {
+  if (entry.multiplicity <= 1) return [entry.class];
+  return Array.from({ length: entry.multiplicity }, (_, i) => `${entry.class}${i}`);
+}
+
+/**
+ * Generate the concrete seats + roster.yaml for a validated profile.
+ *
+ * Seat selection:
+ *   --full  → the ENTIRE profile roster, multiplicity expanded.
+ *   default → ONLY the `floor` classes (the always-staffed minimum), matching
+ *             the profile note "two-agent floor always staffed; every other seat
+ *             added on demand."
+ *
+ * Per-seat flags:
+ *   RULE 2 persistent_persona: true for floor classes AND the lead; else omitted.
+ *   RULE 3 reset_between_tasks: true for non-floor, non-lead execution seats;
+ *           floor/lead omit it (mirrors today's coders resetting while the
+ *           orchestrator/enhancer do not).
+ *   RULE 4 runtime: via resolveSeatRuntime (defaults claude).
+ *   RULE 6 reports_to: tracked on the seat for the topology summary but NOT
+ *           emitted to roster.yaml — the fleet.ts parser rejects unknown agent
+ *           keys, so writing reports_to would break round-trip. Confirmed against
+ *           normalizeAgent's allow-list in fleet.ts.
+ *
+ * Persona resolution: every emitted class is resolved override-aware via
+ * resolvePersona so we can (a) record the layer for the summary and (b) refuse
+ * to emit a roster that references a nonexistent persona.
+ */
+export async function generateRoster(
+  profile: FleetProfile,
+  opts: ProvisionOptions,
+): Promise<GenerateRosterResult> {
+  const { rolesDir, overrideDir } = resolveDirs(opts);
+  const floor = new Set(profile.floor);
+  const lead = profile.lead;
+
+  const selected: ProfileRosterEntry[] = opts.full
+    ? profile.roster
+    : profile.roster.filter((e) => floor.has(e.class));
+
+  // Scan the persona directories ONCE, then resolve every roster entry against
+  // the in-memory maps. resolvePersona() would otherwise re-scan both dirs per
+  // entry — O(entries × files) redundant reads that push --full provisioning
+  // past the test timeout on slow/contended filesystems.
+  const [base, over] = await Promise.all([
+    extractClassesFromDir(rolesDir),
+    extractClassesFromDir(overrideDir),
+  ]);
+
+  const seats: GeneratedSeat[] = [];
+  for (const entry of selected) {
+    const isFloor = floor.has(entry.class);
+    const isLead = entry.class === lead;
+
+    const resolved = await resolvePersonaFrom(entry.class, { rolesDir, overrideDir, base, over });
+    if (!resolved) {
+      // Defensive: validateProfile already guards this, but a class can resolve
+      // for membership yet have no readable file. Fail loudly rather than emit a
+      // roster pointing at a persona we cannot load.
+      throw new Error(
+        `Cannot provision: roster class "${entry.class}" does not resolve to a readable persona.`,
+      );
+    }
+
+    const runtimeChoice = resolveSeatRuntime(entry.class, isFloor, isLead);
+    for (const name of seatNames(entry)) {
+      const seat: GeneratedSeat = {
+        name,
+        className: entry.class,
+        runtime: runtimeChoice.runtime,
+        personaLayer: resolved.layer,
+      };
+      if (runtimeChoice.modelHint) seat.modelHint = runtimeChoice.modelHint;
+      if (isFloor || isLead) seat.persistentPersona = true;
+      if (!isFloor && !isLead) seat.resetBetweenTasks = true;
+      if (entry.reportsTo) seat.reportsTo = entry.reportsTo;
+      seats.push(seat);
+    }
+  }
+
+  if (seats.length === 0) {
+    throw new Error(
+      `Profile "${profile.id}" produced no seats. ` +
+        (opts.full ? 'Its roster is empty.' : 'No floor seats are defined — try --full.'),
+    );
+  }
+
+  return { seats, yaml: renderRosterYaml(seats) };
+}
+
+/**
+ * RULE 5 — Standard roster scaffolding. We emit the same generic, non-personal
+ * scaffold the committed example presets use (socket_name: mosaic-fleet,
+ * holder_session: _holder, working_directory: ~, claude + pi runtimes) so the
+ * output is a drop-in valid roster. No operator-personal data is copied.
+ *
+ * Built via the `yaml` lib (same serializer the parser uses) so the result
+ * round-trips. reports_to is intentionally NOT included on agents (RULE 6).
+ */
+function renderRosterYaml(seats: GeneratedSeat[]): string {
+  const agents = seats.map((s) => {
+    const a: Record<string, unknown> = {
+      name: s.name,
+      runtime: s.runtime,
+      class: s.className,
+    };
+    if (s.persistentPersona) a['persistent_persona'] = true;
+    if (s.modelHint) a['model_hint'] = s.modelHint;
+    if (s.resetBetweenTasks) a['reset_between_tasks'] = true;
+    return a;
+  });
+
+  const doc = {
+    version: 1,
+    transport: 'tmux',
+    tmux: { socket_name: 'mosaic-fleet', holder_session: '_holder' },
+    defaults: { working_directory: '~' },
+    runtimes: {
+      claude: { reset_command: '/clear' },
+      pi: { reset_command: '/new' },
+    },
+    agents,
+  };
+
+  return YAML.stringify(doc);
+}
+
+// ---------------------------------------------------------------------------
+// Validation — reuse fleet-profiles.validateProfile (override-aware classes) and
+// name any unresolved class clearly. Never generate a roster referencing a
+// nonexistent persona.
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate the profile against the override-aware persona library. Throws with a
+ * clear, class-naming message if any referenced class is unresolved.
+ */
+export async function validateProfileForProvision(
+  profile: FleetProfile,
+  opts: ProvisionOptions,
+): Promise<void> {
+  const { rolesDir, overrideDir } = resolveDirs(opts);
+  const validClasses = await listPersonaClassesWithOverrides(rolesDir, overrideDir);
+  const problems = validateProfile(profile, validClasses);
+  if (problems.length > 0) {
+    throw new Error(
+      `Profile "${profile.id}" is invalid; cannot provision:\n  - ${problems.join('\n  - ')}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Topology summary (printed in dry-run and after write).
+// ---------------------------------------------------------------------------
+
+function formatTopologySummary(seats: GeneratedSeat[]): string {
+  const lines: string[] = [];
+  lines.push(`Topology (${seats.length} seat(s)):`);
+  for (const s of seats) {
+    const reports = s.reportsTo ? `reports_to=${s.reportsTo}` : 'reports_to=- (lead)';
+    lines.push(
+      `  - ${s.name}\tclass=${s.className}\truntime=${s.runtime}\t${reports}\tpersona=${s.personaLayer}`,
+    );
+  }
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// CLI wiring — mirror registerFleetProfileCommand / registerFleetPersonaCommand.
+// ---------------------------------------------------------------------------
+
+export interface ProvisionRunResult {
+  yaml: string;
+  summary: string;
+  wrote?: string;
+}
+
+/**
+ * Core provision flow shared by the CLI: load + validate the profile, generate
+ * the roster, optionally write it. Returns the artifacts for printing/testing.
+ */
+export async function runProvision(
+  profileId: string,
+  opts: ProvisionOptions & { write?: boolean; force?: boolean },
+): Promise<ProvisionRunResult> {
+  const dirs = resolveDirs(opts);
+  const profile = await loadProfile(profileId, {
+    mosaicHome: dirs.mosaicHome,
+    profilesDir: dirs.profilesDir,
+    rolesDir: dirs.rolesDir,
+    overrideDir: dirs.overrideDir,
+  });
+  // loadProfile already validates, but re-run with our explicit error wording so
+  // an unresolved class is named clearly even if invoked directly.
+  await validateProfileForProvision(profile, opts);
+
+  const { seats, yaml } = await generateRoster(profile, opts);
+  const summary = formatTopologySummary(seats);
+
+  if (!opts.write) {
+    return { yaml, summary };
+  }
+
+  const rosterPath = join(dirs.mosaicHome, 'fleet', 'roster.yaml');
+  if (!opts.force) {
+    let exists = false;
+    try {
+      await access(rosterPath, constants.F_OK);
+      exists = true;
+    } catch {
+      exists = false;
+    }
+    if (exists) {
+      throw new Error(
+        `Refusing to overwrite existing roster: ${rosterPath}. ` +
+          `Pass --force to overwrite, or edit it by hand.`,
+      );
+    }
+  }
+  await mkdir(dirname(rosterPath), { recursive: true });
+  await writeFile(rosterPath, yaml, 'utf8');
+  return { yaml, summary, wrote: rosterPath };
+}
+
+/**
+ * Register `provision` under an existing `fleet` command. `mosaicHomeFor`
+ * resolves the active --mosaic-home (parent flag) at call time, exactly like the
+ * profile/persona/backlog subcommands.
+ */
+export function registerFleetProvisionCommand(
+  fleetCmd: Command,
+  mosaicHomeFor: () => string,
+): Command {
+  const provisionCmd = fleetCmd
+    .command('provision')
+    .description('Materialize a roster.yaml from a system-type profile (H3). DRY-RUN by default.')
+    .requiredOption('--profile <id>', 'System-type profile id to provision')
+    .option('--full', 'Materialize the entire profile roster (default: floor seats only)')
+    .option('--write', 'Write the generated roster to <mosaicHome>/fleet/roster.yaml')
+    .option('--force', 'Overwrite an existing roster.yaml (requires --write)')
+    .action(async (opts: { profile: string; full?: boolean; write?: boolean; force?: boolean }) => {
+      try {
+        const result = await runProvision(opts.profile, {
+          mosaicHome: mosaicHomeFor(),
+          full: opts.full,
+          write: opts.write,
+          force: opts.force,
+        });
+        if (result.wrote) {
+          console.log(`Wrote roster: ${result.wrote}`);
+          console.log('');
+          console.log(result.summary);
+        } else {
+          // DRY RUN: print the roster it WOULD generate + topology, write nothing.
+          console.log('# DRY RUN — no files written. Re-run with --write to persist.');
+          console.log(result.yaml.trimEnd());
+          console.log('');
+          console.log(result.summary);
+        }
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  return provisionCmd;
+}

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

@@ -84,6 +84,7 @@ describe('registerFleetCommand', () => {
       'install-systemd',
       'persona',
       'profile',
+      'provision',
       'ps',
       'remove',
       'restart',

packages/mosaic/src/commands/fleet.ts

@@ -11,6 +11,7 @@ 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';
+import { registerFleetProvisionCommand } from './fleet-provision.js';
 
 /**
  * A function that spawns a command with inherited stdio (TTY passthrough).
@@ -1720,6 +1721,10 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
   // --mosaic-home flag.
   registerFleetPersonaCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
 
+  // Provisioning (H3): materialize a concrete roster.yaml from a system-type
+  // profile. DRY-RUN by default; --write persists under the same --mosaic-home.
+  registerFleetProvisionCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
+
   return cmd;
 }