docs(fleet): record per-agent model switch in north star

Per-agent model selection (operator-configurable, webUI switch over the existing roster model_hint plumbing) recorded as a decision of record so it isn't lost. Also confirms orchestrator/enhancer run Claude Opus 4.8 in Claude Code; only workers run pi/gpt-5.5. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-24 13:05:26 -05:00
14 changed files with 5 additions and 1402 deletions
--- a/apps/gateway/src/federation/federation.module.ts
+++ b/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, FederationScopeService } from './server/index.js';
+import { FederationAuthGuard } from './server/index.js';
@Module({
  controllers: [EnrollmentController, FederationController],
@@ -17,7 +17,6 @@ import { FederationAuthGuard, FederationScopeService } from './server/index.js';
    GrantsService,
    FederationClientService,
    FederationAuthGuard,
    FederationScopeService,
  ],
  exports: [
    CaService,
@@ -25,7 +24,6 @@ import { FederationAuthGuard, FederationScopeService } from './server/index.js';
    GrantsService,
    FederationClientService,
    FederationAuthGuard,
    FederationScopeService,
  ],
 })
 export class FederationModule {}
--- a/apps/gateway/src/federation/server/tests/scope.service.spec.ts
+++ b/apps/gateway/src/federation/server/tests/scope.service.spec.ts
@@ -1,324 +0,0 @@
 /**
 * 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' },
      },
    });
  });
 });
--- a/apps/gateway/src/federation/server/index.ts
+++ b/apps/gateway/src/federation/server/index.ts
@@ -10,22 +10,4 @@
 */
 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';
--- a/apps/gateway/src/federation/server/scope.service.ts
+++ b/apps/gateway/src/federation/server/scope.service.ts
@@ -1,272 +0,0 @@
 /**
 * 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,
      },
    };
  }
 }
--- a/docs/scratchpads/462-fed-m3-04-scope-service.md
+++ b/docs/scratchpads/462-fed-m3-04-scope-service.md
@@ -1,60 +0,0 @@
 # 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.
--- a/packages/db/package.json
+++ b/packages/db/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@mosaicstack/db",
-  "version": "0.0.4",
+  "version": "0.0.3",
  "repository": {
    "type": "git",
    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
--- a/packages/mosaic/framework/tools/fleet/start-agent-session.sh
+++ b/packages/mosaic/framework/tools/fleet/start-agent-session.sh
@@ -114,21 +114,10 @@ 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 MOSAIC_AGENT_CLASS=${AGENT_CLASS_Q}; export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}"
+  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}"
 else
-  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export MOSAIC_AGENT_CLASS=${AGENT_CLASS_Q}; exec ${MOSAIC_AGENT_COMMAND}"
+  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; exec ${MOSAIC_AGENT_COMMAND}"
 fi
 mkdir -p "$MOSAIC_AGENT_WORKDIR"
--- a/packages/mosaic/framework/tools/fleet/test-start-agent-session.sh
+++ b/packages/mosaic/framework/tools/fleet/test-start-agent-session.sh
@@ -104,7 +104,6 @@ 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" \
@@ -128,18 +127,6 @@ 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)
--- a/packages/mosaic/package.json
+++ b/packages/mosaic/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@mosaicstack/mosaic",
-  "version": "0.0.48",
+  "version": "0.0.45",
  "repository": {
    "type": "git",
    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
--- a/packages/mosaic/src/commands/fleet-personas.ts
+++ b/packages/mosaic/src/commands/fleet-personas.ts
@@ -234,21 +234,6 @@ 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,
--- a/packages/mosaic/src/commands/fleet-provision.spec.ts
+++ b/packages/mosaic/src/commands/fleet-provision.spec.ts
@@ -1,270 +0,0 @@
 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 });
    }
  });
 });
--- a/packages/mosaic/src/commands/fleet-provision.ts
+++ b/packages/mosaic/src/commands/fleet-provision.ts
@@ -1,406 +0,0 @@
 /**
 * `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;
 }
--- a/packages/mosaic/src/commands/fleet.spec.ts
+++ b/packages/mosaic/src/commands/fleet.spec.ts
@@ -84,7 +84,6 @@ describe('registerFleetCommand', () => {
      'install-systemd',
      'persona',
      'profile',
      'provision',
      'ps',
      'remove',
      'restart',
--- a/packages/mosaic/src/commands/fleet.ts
+++ b/packages/mosaic/src/commands/fleet.ts
@@ -11,7 +11,6 @@ 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).
@@ -1721,10 +1720,6 @@ 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;
 }