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>

apps/gateway/src/admin/admin-health.controller.ts

@@ -1,11 +1,9 @@
-import { Controller, Get, Inject, Optional, UseGuards } from '@nestjs/common';
+import { Controller, Get, Inject, UseGuards } from '@nestjs/common';
 import { sql, type Db } from '@mosaicstack/db';
 import { createQueue } from '@mosaicstack/queue';
-import type { MosaicConfig } from '@mosaicstack/config';
 import { DB } from '../database/database.module.js';
 import { AgentService } from '../agent/agent.service.js';
 import { ProviderService } from '../agent/provider.service.js';
-import { MOSAIC_CONFIG } from '../config/config.module.js';
 import { AdminGuard } from './admin.guard.js';
 import type { HealthStatusDto, ServiceStatusDto } from './admin.dto.js';
 
@@ -16,9 +14,6 @@ export class AdminHealthController {
     @Inject(DB) private readonly db: Db,
     @Inject(AgentService) private readonly agentService: AgentService,
     @Inject(ProviderService) private readonly providerService: ProviderService,
-    @Optional()
-    @Inject(MOSAIC_CONFIG)
-    private readonly mosaicConfig: MosaicConfig | null,
   ) {}
 
   @Get()
@@ -60,14 +55,6 @@ export class AdminHealthController {
   }
 
   private async checkCache(): Promise<ServiceStatusDto> {
-    // On Local tier there is no Redis. The cache is intentionally absent, which
-    // is a healthy state for this tier — report 'ok' rather than opening a new
-    // ioredis connection on every admin health check (which would spam
-    // ECONNREFUSED and create/destroy a connection per request). latencyMs 0
-    // signals "no cache backend to measure" for this tier.
-    if (this.mosaicConfig?.queue?.type === 'local') {
-      return { status: 'ok', latencyMs: 0 };
-    }
     const start = Date.now();
     const handle = createQueue();
     try {

apps/gateway/src/commands/command-executor.service.ts

@@ -21,10 +21,7 @@ export class CommandExecutorService {
     @Inject(AgentService) private readonly agentService: AgentService,
     @Inject(SystemOverrideService) private readonly systemOverride: SystemOverrideService,
     @Inject(SessionGCService) private readonly sessionGC: SessionGCService,
-    // On Local tier COMMANDS_REDIS is null — provider login caching is skipped.
+    @Inject(COMMANDS_REDIS) private readonly redis: QueueHandle['redis'],
-    @Optional()
-    @Inject(COMMANDS_REDIS)
-    private readonly redis: QueueHandle['redis'] | null,
     @Inject(BRAIN) private readonly brain: Brain,
     @Optional()
     @Inject(forwardRef(() => ReloadService))
@@ -406,16 +403,14 @@ export class CommandExecutorService {
           };
         }
         const pollToken = crypto.randomUUID();
-        const pollKey = `mosaic:auth:poll:${pollToken}`;
+        const key = `mosaic:auth:poll:${pollToken}`;
-        if (this.redis) {
+        // Store pending state in Valkey (TTL 5 minutes)
-          // Store pending state in Valkey (TTL 5 minutes)
+        await this.redis.set(
-          await this.redis.set(
+          key,
-            pollKey,
+          JSON.stringify({ status: 'pending', provider: providerName, userId }),
-            JSON.stringify({ status: 'pending', provider: providerName, userId }),
+          'EX',
-            'EX',
+          300,
-            300,
+        );
-          );
-        }
         // In production this would construct an OAuth URL
         const loginUrl = `${process.env['MOSAIC_BASE_URL'] ?? 'http://localhost:3000'}/auth/provider/${providerName}?token=${pollToken}`;
         return {

apps/gateway/src/commands/commands.module.ts

@@ -1,7 +1,5 @@
-import { forwardRef, Inject, Module, Optional, type OnApplicationShutdown } from '@nestjs/common';
+import { forwardRef, Inject, Module, type OnApplicationShutdown } from '@nestjs/common';
 import { createQueue, type QueueHandle } from '@mosaicstack/queue';
-import type { MosaicConfig } from '@mosaicstack/config';
-import { MOSAIC_CONFIG } from '../config/config.module.js';
 import { ChatModule } from '../chat/chat.module.js';
 import { GCModule } from '../gc/gc.module.js';
 import { ReloadModule } from '../reload/reload.module.js';
@@ -16,17 +14,13 @@ const COMMANDS_QUEUE_HANDLE = 'COMMANDS_QUEUE_HANDLE';
   providers: [
     {
       provide: COMMANDS_QUEUE_HANDLE,
-      useFactory: (config: MosaicConfig | null): QueueHandle | null => {
+      useFactory: (): QueueHandle => {
-        // On Local tier there is no Redis — skip the ioredis connection.
-        // CommandExecutorService falls back to no-cache for /provider login on local.
-        if (config?.queue?.type === 'local') return null;
         return createQueue();
       },
-      inject: [MOSAIC_CONFIG],
     },
     {
       provide: COMMANDS_REDIS,
-      useFactory: (handle: QueueHandle | null) => handle?.redis ?? null,
+      useFactory: (handle: QueueHandle) => handle.redis,
       inject: [COMMANDS_QUEUE_HANDLE],
     },
     CommandRegistryService,
@@ -35,13 +29,9 @@ const COMMANDS_QUEUE_HANDLE = 'COMMANDS_QUEUE_HANDLE';
   exports: [CommandRegistryService, CommandExecutorService],
 })
 export class CommandsModule implements OnApplicationShutdown {
-  constructor(
+  constructor(@Inject(COMMANDS_QUEUE_HANDLE) private readonly handle: QueueHandle) {}
-    @Optional()
-    @Inject(COMMANDS_QUEUE_HANDLE)
-    private readonly handle: QueueHandle | null,
-  ) {}
 
   async onApplicationShutdown(): Promise<void> {
-    await this.handle?.close().catch(() => {});
+    await this.handle.close().catch(() => {});
   }
 }

apps/gateway/src/gc/gc.module.ts

@@ -1,7 +1,5 @@
-import { Module, type OnApplicationShutdown, Inject, Optional } from '@nestjs/common';
+import { Module, type OnApplicationShutdown, Inject } from '@nestjs/common';
 import { createQueue, type QueueHandle } from '@mosaicstack/queue';
-import type { MosaicConfig } from '@mosaicstack/config';
-import { MOSAIC_CONFIG } from '../config/config.module.js';
 import { SessionGCService } from './session-gc.service.js';
 import { REDIS } from './gc.tokens.js';
 
@@ -11,17 +9,13 @@ const GC_QUEUE_HANDLE = 'GC_QUEUE_HANDLE';
   providers: [
     {
       provide: GC_QUEUE_HANDLE,
-      useFactory: (config: MosaicConfig | null): QueueHandle | null => {
+      useFactory: (): QueueHandle => {
-        // On Local tier there is no Redis — skip the ioredis connection entirely.
-        // The Valkey GC sweep is a no-op on Local (no session keys stored there).
-        if (config?.queue?.type === 'local') return null;
         return createQueue();
       },
-      inject: [MOSAIC_CONFIG],
     },
     {
       provide: REDIS,
-      useFactory: (handle: QueueHandle | null) => handle?.redis ?? null,
+      useFactory: (handle: QueueHandle) => handle.redis,
       inject: [GC_QUEUE_HANDLE],
     },
     SessionGCService,
@@ -29,13 +23,9 @@ const GC_QUEUE_HANDLE = 'GC_QUEUE_HANDLE';
   exports: [SessionGCService],
 })
 export class GCModule implements OnApplicationShutdown {
-  constructor(
+  constructor(@Inject(GC_QUEUE_HANDLE) private readonly handle: QueueHandle) {}
-    @Optional()
-    @Inject(GC_QUEUE_HANDLE)
-    private readonly handle: QueueHandle | null,
-  ) {}
 
   async onApplicationShutdown(): Promise<void> {
-    await this.handle?.close().catch(() => {});
+    await this.handle.close().catch(() => {});
   }
 }

apps/gateway/src/gc/session-gc.service.ts

@@ -1,4 +1,4 @@
-import { Inject, Injectable, Logger, Optional, type OnModuleInit } from '@nestjs/common';
+import { Inject, Injectable, Logger, type OnModuleInit } from '@nestjs/common';
 import type { QueueHandle } from '@mosaicstack/queue';
 import type { LogService } from '@mosaicstack/log';
 import { LOG_SERVICE } from '../log/log.tokens.js';
@@ -32,21 +32,11 @@ export class SessionGCService implements OnModuleInit {
   private readonly logger = new Logger(SessionGCService.name);
 
   constructor(
-    // On Local tier there is no Redis — the GC module provides null for this token.
+    @Inject(REDIS) private readonly redis: QueueHandle['redis'],
-    // NOTE: if a future feature stores Redis-backed state on Local tier, this guard
-    // would silently skip GC for those keys. Revisit when that happens.
-    @Optional()
-    @Inject(REDIS)
-    private readonly redis: QueueHandle['redis'] | null,
     @Inject(LOG_SERVICE) private readonly logService: LogService,
   ) {}
 
   onModuleInit(): void {
-    if (!this.redis) {
-      // Local tier: no Valkey — skip cold-start GC entirely (correct no-op).
-      this.logger.log('SessionGCService: Valkey GC skipped on local tier (no Redis configured)');
-      return;
-    }
     // Fire-and-forget: run full GC asynchronously so it does not block the
     // NestJS bootstrap chain.  Cold-start GC typically takes 100–500 ms
     // depending on Valkey key count; deferring it removes that latency from
@@ -70,10 +60,8 @@ export class SessionGCService implements OnModuleInit {
    * Scan Valkey for all keys matching a pattern using SCAN (non-blocking).
    * KEYS is avoided because it blocks the Valkey event loop for the full scan
    * duration, which can cause latency spikes under production key volumes.
-   * Returns empty array when Redis is not available (Local tier).
    */
   private async scanKeys(pattern: string): Promise<string[]> {
-    if (!this.redis) return [];
     const collected: string[] = [];
     let cursor = '0';
     do {
@@ -90,14 +78,12 @@ export class SessionGCService implements OnModuleInit {
   async collect(sessionId: string): Promise<GCResult> {
     const result: GCResult = { sessionId, cleaned: {} };
 
-    // 1. Valkey: delete all session-scoped keys (skipped on Local tier)
+    // 1. Valkey: delete all session-scoped keys
-    if (this.redis) {
+    const pattern = `mosaic:session:${sessionId}:*`;
-      const pattern = `mosaic:session:${sessionId}:*`;
+    const valkeyKeys = await this.scanKeys(pattern);
-      const valkeyKeys = await this.scanKeys(pattern);
+    if (valkeyKeys.length > 0) {
-      if (valkeyKeys.length > 0) {
+      await this.redis.del(...valkeyKeys);
-        await this.redis.del(...valkeyKeys);
+      result.cleaned.valkeyKeys = valkeyKeys.length;
-        result.cleaned.valkeyKeys = valkeyKeys.length;
-      }
     }
 
     // 2. PG: demote hot-tier agent_logs for this session to warm
@@ -120,7 +106,6 @@ export class SessionGCService implements OnModuleInit {
     const cleaned: GCResult[] = [];
 
     // 1. Find all session-scoped Valkey keys (non-blocking SCAN)
-    // Returns empty on Local tier — no Valkey session keys exist there.
     const allSessionKeys = await this.scanKeys('mosaic:session:*');
 
     // Extract unique session IDs from keys
@@ -151,15 +136,11 @@ export class SessionGCService implements OnModuleInit {
    */
   async fullCollect(): Promise<FullGCResult> {
     const start = Date.now();
-    let valkeyKeysCount = 0;
 
-    if (this.redis) {
+    // 1. Valkey: delete ALL session-scoped keys (non-blocking SCAN)
-      // 1. Valkey: delete ALL session-scoped keys (non-blocking SCAN)
+    const sessionKeys = await this.scanKeys('mosaic:session:*');
-      const sessionKeys = await this.scanKeys('mosaic:session:*');
+    if (sessionKeys.length > 0) {
-      if (sessionKeys.length > 0) {
+      await this.redis.del(...sessionKeys);
-        await this.redis.del(...sessionKeys);
-      }
-      valkeyKeysCount = sessionKeys.length;
     }
 
     // 2. NOTE: channel keys are NOT collected on cold start
@@ -173,7 +154,7 @@ export class SessionGCService implements OnModuleInit {
     const jobsPurged = 0;
 
     return {
-      valkeyKeys: valkeyKeysCount,
+      valkeyKeys: sessionKeys.length,
       logsDemoted,
       jobsPurged,
       tempFilesRemoved: 0,

apps/gateway/src/log/cron.service.ts

@@ -19,7 +19,7 @@ import type { MosaicJobData } from '../queue/queue.service.js';
 @Injectable()
 export class CronService implements OnModuleInit, OnModuleDestroy {
   private readonly logger = new Logger(CronService.name);
-  private readonly registeredWorkers: Array<Worker<MosaicJobData>> = [];
+  private readonly registeredWorkers: Worker<MosaicJobData>[] = [];
 
   constructor(
     @Inject(SummarizationService) private readonly summarization: SummarizationService,
@@ -28,16 +28,6 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
   ) {}
 
   async onModuleInit(): Promise<void> {
-    // On Local tier BullMQ is disabled — skip all job scheduling.
-    // NOTE: this means summarization, tier management, and Valkey GC jobs do not
-    // run on Local installs. For a single-user local install this is acceptable.
-    // If periodic background work is needed on Local in the future, add a
-    // setInterval-based scheduler here.
-    if (!this.queueService.isEnabled()) {
-      this.logger.log('CronService: BullMQ disabled on local tier — no jobs will be scheduled');
-      return;
-    }
-
     const summarizationSchedule = process.env['SUMMARIZATION_CRON'] ?? '0 */6 * * *'; // every 6 hours
     const tierManagementSchedule = process.env['TIER_MANAGEMENT_CRON'] ?? '0 3 * * *'; // daily at 3am
     const gcSchedule = process.env['SESSION_GC_CRON'] ?? '0 4 * * *'; // daily at 4am
@@ -52,7 +42,7 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
     const summarizationWorker = this.queueService.registerWorker(QUEUE_SUMMARIZATION, async () => {
       await this.summarization.runSummarization();
     });
-    if (summarizationWorker) this.registeredWorkers.push(summarizationWorker);
+    this.registeredWorkers.push(summarizationWorker);
 
     // M6-005: Tier management repeatable job
     await this.queueService.addRepeatableJob(
@@ -64,14 +54,14 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
     const tierWorker = this.queueService.registerWorker(QUEUE_TIER_MANAGEMENT, async () => {
       await this.summarization.runTierManagement();
     });
-    if (tierWorker) this.registeredWorkers.push(tierWorker);
+    this.registeredWorkers.push(tierWorker);
 
     // M6-004: GC repeatable job
     await this.queueService.addRepeatableJob(QUEUE_GC, 'session-gc', {}, gcSchedule);
     const gcWorker = this.queueService.registerWorker(QUEUE_GC, async () => {
       await this.sessionGC.sweepOrphans();
     });
-    if (gcWorker) this.registeredWorkers.push(gcWorker);
+    this.registeredWorkers.push(gcWorker);
 
     this.logger.log(
       `BullMQ jobs scheduled: summarization="${summarizationSchedule}", tier="${tierManagementSchedule}", gc="${gcSchedule}"`,

apps/gateway/src/preferences/system-override.service.ts

@@ -1,7 +1,5 @@
-import { Inject, Injectable, Logger, Optional, type OnApplicationShutdown } from '@nestjs/common';
+import { Injectable, Logger } from '@nestjs/common';
 import { createQueue, type QueueHandle } from '@mosaicstack/queue';
-import type { MosaicConfig } from '@mosaicstack/config';
-import { MOSAIC_CONFIG } from '../config/config.module.js';
 
 const SESSION_SYSTEM_KEY = (sessionId: string) => `mosaic:session:${sessionId}:system`;
 const SESSION_SYSTEM_FRAGMENTS_KEY = (sessionId: string) =>
@@ -13,54 +11,16 @@ interface OverrideFragment {
   addedAt: number;
 }
 
-interface LocalOverrideEntry {
-  condensed: string;
-  fragments: OverrideFragment[];
-}
-
 @Injectable()
-export class SystemOverrideService implements OnApplicationShutdown {
+export class SystemOverrideService {
   private readonly logger = new Logger(SystemOverrideService.name);
-  private readonly handle: QueueHandle | null;
+  private readonly handle: QueueHandle;
-  /**
-   * In-memory fallback used on Local tier (no Redis).
-   * NOTE: state is ephemeral — lost on restart. For Local single-user installs
-   * this is acceptable; system overrides are re-applied at the next session.
-   * This is a deliberate behavior change from the Redis-backed 7-day TTL.
-   */
-  private readonly localStore = new Map<string, LocalOverrideEntry>();
 
-  constructor(
+  constructor() {
-    @Optional()
+    this.handle = createQueue();
-    @Inject(MOSAIC_CONFIG)
-    private readonly mosaicConfig: MosaicConfig | null,
-  ) {
-    if (this.mosaicConfig?.queue?.type === 'local') {
-      this.handle = null;
-    } else {
-      this.handle = createQueue();
-    }
-  }
-
-  async onApplicationShutdown(): Promise<void> {
-    // On non-local tiers the constructor opens an ioredis connection; close it
-    // on graceful shutdown to avoid leaking the handle (local tier is null).
-    await this.handle?.close().catch(() => {});
   }
 
   async set(sessionId: string, override: string): Promise<void> {
-    if (!this.handle) {
-      // Local tier: in-memory path
-      const entry = this.localStore.get(sessionId) ?? { condensed: '', fragments: [] };
-      entry.fragments.push({ text: override, addedAt: Date.now() });
-      entry.condensed = await this.condenseOverrides(entry.fragments.map((f) => f.text));
-      this.localStore.set(sessionId, entry);
-      this.logger.debug(
-        `Set system override for session ${sessionId} (local, ${entry.fragments.length} fragment(s))`,
-      );
-      return;
-    }
-
     // Load existing fragments
     const existing = await this.handle.redis.get(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId));
     const fragments: OverrideFragment[] = existing
@@ -90,17 +50,10 @@ export class SystemOverrideService implements OnApplicationShutdown {
   }
 
   async get(sessionId: string): Promise<string | null> {
-    if (!this.handle) {
-      return this.localStore.get(sessionId)?.condensed ?? null;
-    }
     return this.handle.redis.get(SESSION_SYSTEM_KEY(sessionId));
   }
 
   async renew(sessionId: string): Promise<void> {
-    if (!this.handle) {
-      // Local tier: no TTL to renew; entry persists until restart
-      return;
-    }
     const pipeline = this.handle.redis.pipeline();
     pipeline.expire(SESSION_SYSTEM_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS);
     pipeline.expire(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS);
@@ -108,11 +61,6 @@ export class SystemOverrideService implements OnApplicationShutdown {
   }
 
   async clear(sessionId: string): Promise<void> {
-    if (!this.handle) {
-      this.localStore.delete(sessionId);
-      this.logger.debug(`Cleared system override for session ${sessionId} (local)`);
-      return;
-    }
     await this.handle.redis.del(
       SESSION_SYSTEM_KEY(sessionId),
       SESSION_SYSTEM_FRAGMENTS_KEY(sessionId),

apps/gateway/src/queue/queue.service.ts

@@ -8,9 +8,7 @@ import {
 } from '@nestjs/common';
 import { Queue, Worker, type Job, type ConnectionOptions } from 'bullmq';
 import type { LogService } from '@mosaicstack/log';
-import type { MosaicConfig } from '@mosaicstack/config';
 import { LOG_SERVICE } from '../log/log.tokens.js';
-import { MOSAIC_CONFIG } from '../config/config.module.js';
 import type { JobDto, JobStatus } from './queue-admin.dto.js';
 
 // ---------------------------------------------------------------------------
@@ -110,42 +108,21 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
   private readonly connection: ConnectionOptions;
   private readonly queues = new Map<string, Queue<MosaicJobData>>();
   private readonly workers = new Map<string, Worker<MosaicJobData>>();
-  /** False on Local tier — BullMQ/Redis operations become no-ops. */
-  private readonly enabled: boolean;
 
   constructor(
     @Optional()
     @Inject(LOG_SERVICE)
     private readonly logService: LogService | null,
-    @Optional()
-    @Inject(MOSAIC_CONFIG)
-    private readonly mosaicConfig: MosaicConfig | null,
   ) {
-    this.enabled = this.mosaicConfig?.queue?.type !== 'local';
+    this.connection = getConnection();
-    this.connection = this.enabled
-      ? getConnection()
-      : ({ host: '127.0.0.1', port: 6380 } as ConnectionOptions);
-  }
-
-  /** Returns true when BullMQ/Redis is active (Standalone and Federated tiers). */
-  isEnabled(): boolean {
-    return this.enabled;
   }
 
   onModuleInit(): void {
-    if (this.enabled) {
+    this.logger.log('QueueService initialised (BullMQ)');
-      this.logger.log('QueueService initialised (BullMQ)');
-    } else {
-      this.logger.log(
-        'QueueService: BullMQ disabled for local tier — no Redis connections will be opened',
-      );
-    }
   }
 
   async onModuleDestroy(): Promise<void> {
-    if (this.enabled) {
+    await this.closeAll();
-      await this.closeAll();
-    }
   }
 
   // -------------------------------------------------------------------------
@@ -154,10 +131,8 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
 
   /**
    * Get or create a BullMQ Queue for the given queue name.
-   * Returns null on Local tier where BullMQ is disabled.
    */
-  getQueue<T extends MosaicJobData = MosaicJobData>(name: string): Queue<T> | null {
+  getQueue<T extends MosaicJobData = MosaicJobData>(name: string): Queue<T> {
-    if (!this.enabled) return null;
     let queue = this.queues.get(name) as Queue<T> | undefined;
     if (!queue) {
       queue = new Queue<T>(name, { connection: this.connection });
@@ -169,7 +144,6 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
   /**
    * Add a BullMQ repeatable job (cron-style).
    * Uses `jobId` as a deterministic key so duplicate registrations are idempotent.
-   * No-op on Local tier.
    */
   async addRepeatableJob<T extends MosaicJobData>(
     queueName: string,
@@ -177,13 +151,7 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
     data: T,
     cronExpression: string,
   ): Promise<void> {
-    if (!this.enabled) {
+    const queue = this.getQueue<T>(queueName);
-      this.logger.debug(
-        `Skipping repeatable job "${jobName}" on "${queueName}" (local tier — BullMQ disabled)`,
-      );
-      return;
-    }
-    const queue = this.getQueue<T>(queueName)!;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     await (queue as Queue<any>).add(jobName, data, {
       repeat: { pattern: cronExpression },
@@ -197,18 +165,8 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
   /**
    * Register a Worker for the given queue name with error handling and
    * exponential backoff.
-   * Returns null on Local tier where BullMQ is disabled.
    */
-  registerWorker<T extends MosaicJobData>(
+  registerWorker<T extends MosaicJobData>(queueName: string, handler: JobHandler<T>): Worker<T> {
-    queueName: string,
-    handler: JobHandler<T>,
-  ): Worker<T> | null {
-    if (!this.enabled) {
-      this.logger.debug(
-        `Skipping worker registration for "${queueName}" (local tier — BullMQ disabled)`,
-      );
-      return null;
-    }
     const worker = new Worker<T>(
       queueName,
       async (job) => {
@@ -265,12 +223,8 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
 
   /**
    * Return queue health statistics for all managed queues.
-   * Returns an empty healthy result on Local tier.
    */
   async getHealthStatus(): Promise<QueueHealthStatus> {
-    if (!this.enabled) {
-      return { queues: {}, healthy: true };
-    }
     const queues: QueueHealthStatus['queues'] = {};
     let healthy = true;
 
@@ -301,10 +255,8 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
   /**
    * List jobs across all managed queues, optionally filtered by status.
    * BullMQ jobs are fetched by state type from each queue.
-   * Returns empty array on Local tier.
    */
   async listJobs(status?: JobStatus): Promise<JobDto[]> {
-    if (!this.enabled) return [];
     const jobs: JobDto[] = [];
     const states: JobStatus[] = status
       ? [status]
@@ -331,10 +283,8 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
    * Retry a specific failed job by its BullMQ job ID (format: "queueName:id").
    * The caller passes "<queueName>__<jobId>" as the composite ID because BullMQ
    * job IDs are not globally unique — they are scoped to their queue.
-   * Returns an error on Local tier.
    */
   async retryJob(compositeId: string): Promise<{ ok: boolean; message: string }> {
-    if (!this.enabled) return { ok: false, message: 'BullMQ is disabled on local tier.' };
     const sep = compositeId.lastIndexOf('__');
     if (sep === -1) {
       return { ok: false, message: 'Invalid job id format. Expected "<queue>__<jobId>".' };
@@ -366,7 +316,6 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
    * Pause a queue by name.
    */
   async pauseQueue(name: string): Promise<{ ok: boolean; message: string }> {
-    if (!this.enabled) return { ok: false, message: 'BullMQ is disabled on local tier.' };
     const queue = this.queues.get(name);
     if (!queue) return { ok: false, message: `Queue "${name}" not found.` };
     await queue.pause();
@@ -378,7 +327,6 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
    * Resume a paused queue by name.
    */
   async resumeQueue(name: string): Promise<{ ok: boolean; message: string }> {
-    if (!this.enabled) return { ok: false, message: 'BullMQ is disabled on local tier.' };
     const queue = this.queues.get(name);
     if (!queue) return { ok: false, message: `Queue "${name}" not found.` };
     await queue.resume();

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",

packages/mosaic/__tests__/integration/unified-wizard.test.ts

@@ -69,8 +69,6 @@ describe('Unified wizard (runWizard with default skipGateway)', () => {
 
     const prompter = new HeadlessPrompter({
       'Installation mode': 'quick',
-      'Select your LLM provider': 'anthropic',
-      'Anthropic API key': 'sk-ant-api03-test',
       'What name should agents use?': 'TestBot',
       'Communication style': 'direct',
       'Your name': 'Tester',
@@ -105,8 +103,6 @@ describe('Unified wizard (runWizard with default skipGateway)', () => {
 
     const prompter = new HeadlessPrompter({
       'Installation mode': 'quick',
-      'Select your LLM provider': 'anthropic',
-      'Anthropic API key': 'sk-ant-api03-test',
       'What name should agents use?': 'TestBot',
       'Communication style': 'direct',
       'Your name': 'Tester',
@@ -129,8 +125,6 @@ describe('Unified wizard (runWizard with default skipGateway)', () => {
   it('respects skipGateway: true', async () => {
     const prompter = new HeadlessPrompter({
       'Installation mode': 'quick',
-      'Select your LLM provider': 'anthropic',
-      'Anthropic API key': 'sk-ant-api03-test',
       'What name should agents use?': 'TestBot',
       'Communication style': 'direct',
       'Your name': 'Tester',

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"

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)

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",

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,

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 });
-    }
-  });
-});

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;
-}

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

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

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;
 }
 

packages/mosaic/src/errors.ts

@@ -1,7 +1,7 @@
 export class WizardCancelledError extends Error {
   override name = 'WizardCancelledError';
-  constructor(message = 'Wizard cancelled by user') {
+  constructor() {
-    super(message);
+    super('Wizard cancelled by user');
   }
 }
 

packages/mosaic/src/stages/finalize.ts

@@ -207,16 +207,9 @@ export async function finalizeStage(
       : 'none selected'
     : `install failed — ${skillsResult.failureReason ?? 'unknown error'}`;
 
-  const providerConfigured =
-    state.providerType && state.providerType !== 'none' && state.providerKey;
-  const providerSummary = providerConfigured
-    ? `Provider: ${state.providerType} (configured)`
-    : 'Provider: NONE — agent has no brain';
-
   const summary: string[] = [
     `Agent: ${state.soul.agentName ?? 'Assistant'}`,
     `Style: ${state.soul.communicationStyle ?? 'direct'}`,
-    providerSummary,
     `Runtimes: ${state.runtimes.detected.join(', ') || 'none detected'}`,
     `Skills: ${skillsSummary}`,
     `Config: ${state.mosaicHome}`,
@@ -246,12 +239,5 @@ export async function finalizeStage(
 
   p.note(nextSteps.map((s, i) => `${(i + 1).toString()}. ${s}`).join('\n'), 'Next Steps');
 
-  if (!providerConfigured) {
+  p.outro('Mosaic is ready.');
-    p.warn(
-      'Installation complete, but no LLM provider is configured. ' +
-        'Run `mosaic wizard` or `mosaic gateway install` to add an API key before using the agent.',
-    );
-  } else {
-    p.outro('Mosaic is ready.');
-  }
 }

packages/mosaic/src/stages/gateway-config.ts

@@ -294,12 +294,7 @@ export async function gatewayConfigStage(
   }
 
   // Install the gateway npm package on first install or after failure.
-  // MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1 forces a skip even without opts.skipInstall:
+  if (!opts.skipInstall && !daemonRunning) {
-  // used by dev/offline installs where @mosaicstack/gateway is already present
-  // globally (e.g. a build-from-source `install.sh --dev`) and must not be
-  // overwritten by the registry @latest build.
-  const skipNpmInstall = opts.skipInstall || process.env['MOSAIC_GATEWAY_SKIP_NPM_INSTALL'] === '1';
-  if (!skipNpmInstall && !daemonRunning) {
     installGatewayPackage();
   }
 

packages/mosaic/src/stages/provider-setup.spec.ts

@@ -78,7 +78,7 @@ describe('providerSetupStage', () => {
     expect(state.providerType).toBe('none');
   });
 
-  it('prompts for provider then key in interactive mode', async () => {
+  it('prompts for key in interactive mode', async () => {
     delete process.env['MOSAIC_ASSUME_YES'];
     // Simulate a TTY
     const origIsTTY = process.stdin.isTTY;
@@ -86,13 +86,11 @@ describe('providerSetupStage', () => {
 
     const state = makeState();
     const p = buildPrompter({
-      select: vi.fn().mockResolvedValue('anthropic'),
       text: vi.fn().mockResolvedValue('sk-ant-api03-interactive'),
     });
 
     await providerSetupStage(p, state);
 
-    expect(p.select).toHaveBeenCalled();
     expect(p.text).toHaveBeenCalled();
     expect(state.providerKey).toBe('sk-ant-api03-interactive');
     expect(state.providerType).toBe('anthropic');
@@ -100,57 +98,20 @@ describe('providerSetupStage', () => {
     Object.defineProperty(process.stdin, 'isTTY', { value: origIsTTY, configurable: true });
   });
 
-  it('rejects empty and mismatched keys via the validate callback (Anthropic)', async () => {
+  it('handles empty key in interactive mode', async () => {
     delete process.env['MOSAIC_ASSUME_YES'];
     const origIsTTY = process.stdin.isTTY;
     Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
 
-    let capturedValidate: ((v: string) => string | void) | undefined;
     const state = makeState();
     const p = buildPrompter({
-      select: vi.fn().mockResolvedValue('anthropic'),
+      text: vi.fn().mockResolvedValue(''),
-      text: vi
-        .fn()
-        .mockImplementation(async (opts: { validate?: (v: string) => string | void }) => {
-          capturedValidate = opts.validate;
-          return 'sk-ant-api03-ok';
-        }),
     });
 
     await providerSetupStage(p, state);
 
-    expect(capturedValidate).toBeDefined();
+    expect(state.providerType).toBe('none');
-    expect(capturedValidate?.('')).toBe('API key is required');
+    expect(state.providerKey).toBeUndefined();
-    expect(capturedValidate?.('   ')).toBe('API key is required');
-    expect(capturedValidate?.('not-a-key')).toBe('Anthropic keys start with sk-ant-');
-    expect(capturedValidate?.('sk-ant-valid')).toBeUndefined();
-    expect(state.providerType).toBe('anthropic');
-
-    Object.defineProperty(process.stdin, 'isTTY', { value: origIsTTY, configurable: true });
-  });
-
-  it('rejects an Anthropic key when OpenAI is selected', async () => {
-    delete process.env['MOSAIC_ASSUME_YES'];
-    const origIsTTY = process.stdin.isTTY;
-    Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
-
-    let capturedValidate: ((v: string) => string | void) | undefined;
-    const state = makeState();
-    const p = buildPrompter({
-      select: vi.fn().mockResolvedValue('openai'),
-      text: vi
-        .fn()
-        .mockImplementation(async (opts: { validate?: (v: string) => string | void }) => {
-          capturedValidate = opts.validate;
-          return 'sk-proj-ok';
-        }),
-    });
-
-    await providerSetupStage(p, state);
-
-    expect(capturedValidate?.('sk-ant-api03-xyz')).toBe('OpenAI keys start with sk- (not sk-ant-)');
-    expect(capturedValidate?.('sk-proj-xyz')).toBeUndefined();
-    expect(state.providerType).toBe('openai');
 
     Object.defineProperty(process.stdin, 'isTTY', { value: origIsTTY, configurable: true });
   });

packages/mosaic/src/stages/provider-setup.ts

@@ -1,13 +1,12 @@
 import type { WizardPrompter } from '../prompter/interface.js';
 import type { WizardState } from '../types.js';
-import type { ProviderType } from '../types.js';
+import { detectProviderType } from '../constants.js';
 
 /**
- * Provider setup stage — collects the user's LLM API key and validates the
+ * Provider setup stage — collects the user's LLM API key and detects the
  * provider type from the key prefix.
  *
  * In headless mode, reads from `MOSAIC_ANTHROPIC_API_KEY` or `MOSAIC_OPENAI_API_KEY`.
- * Interactive mode requires the user to select a provider and enter a valid key.
  */
 export async function providerSetupStage(p: WizardPrompter, state: WizardState): Promise<void> {
   const isHeadless = process.env['MOSAIC_ASSUME_YES'] === '1' || !process.stdin.isTTY;
@@ -17,57 +16,39 @@ export async function providerSetupStage(p: WizardPrompter, state: WizardState):
     const openaiKey = process.env['MOSAIC_OPENAI_API_KEY'] ?? '';
     const key = anthropicKey || openaiKey;
     state.providerKey = key || undefined;
-    if (anthropicKey) {
+    state.providerType = detectProviderType(key);
-      state.providerType = 'anthropic';
-    } else if (openaiKey) {
-      state.providerType = 'openai';
-    } else {
-      state.providerType = 'none';
-      p.warn(
-        'No API key found (MOSAIC_ANTHROPIC_API_KEY / MOSAIC_OPENAI_API_KEY). ' +
-          'Run `mosaic gateway install` to configure a key before using the agent.',
-      );
-    }
     return;
   }
 
   p.separator();
   p.note(
     'Configure your LLM provider so the agent has a brain.\n' +
-      'Anthropic (Claude) and OpenAI are supported. You will need an API key to continue.',
+      'Anthropic (Claude) and OpenAI are supported.\n' +
+      'You can skip this and add a key later via `mosaic configure`.',
     'LLM Provider',
   );
 
-  const providerType = await p.select<ProviderType>({
-    message: 'Select your LLM provider',
-    options: [
-      { value: 'anthropic', label: 'Anthropic (Claude)', hint: 'Keys start with sk-ant-' },
-      { value: 'openai', label: 'OpenAI', hint: 'Keys start with sk-' },
-    ],
-    initialValue: 'anthropic',
-  });
-
   const key = await p.text({
-    message: providerType === 'anthropic' ? 'Anthropic API key' : 'OpenAI API key',
+    message: 'API key (paste your Anthropic or OpenAI key, or press Enter to skip)',
-    placeholder: providerType === 'anthropic' ? 'sk-ant-api03-...' : 'sk-...',
+    defaultValue: '',
-    validate: (value: string): string | void => {
+    placeholder: 'sk-ant-api03-... or sk-...',
-      if (!value || value.trim().length === 0) {
-        return 'API key is required';
-      }
-      const trimmed = value.trim();
-      if (providerType === 'anthropic' && !trimmed.startsWith('sk-ant-')) {
-        return 'Anthropic keys start with sk-ant-';
-      }
-      if (
-        providerType === 'openai' &&
-        (!trimmed.startsWith('sk-') || trimmed.startsWith('sk-ant-'))
-      ) {
-        return 'OpenAI keys start with sk- (not sk-ant-)';
-      }
-    },
   });
 
-  state.providerKey = key.trim();
+  if (key) {
-  state.providerType = providerType;
+    const provider = detectProviderType(key);
-  p.log(`Provider configured: ${providerType === 'anthropic' ? 'Anthropic (Claude)' : 'OpenAI'}`);
+    state.providerKey = key;
+    state.providerType = provider;
+
+    if (provider === 'anthropic') {
+      p.log('Detected provider: Anthropic (Claude)');
+    } else if (provider === 'openai') {
+      p.log('Detected provider: OpenAI');
+    } else {
+      p.log('Provider auto-detection failed. Key will be stored as ANTHROPIC_API_KEY.');
+      state.providerType = 'anthropic';
+    }
+  } else {
+    state.providerType = 'none';
+    p.log('No API key provided. You can add one later with `mosaic configure`.');
+  }
 }

packages/mosaic/src/stages/quick-start.ts

@@ -2,7 +2,6 @@ import type { WizardPrompter } from '../prompter/interface.js';
 import type { ConfigService } from '../config/config-service.js';
 import type { WizardState } from '../types.js';
 import { DEFAULTS } from '../constants.js';
-import { WizardCancelledError } from '../errors.js';
 import { providerSetupStage } from './provider-setup.js';
 import { runtimeSetupStage } from './runtime-setup.js';
 import { hooksPreviewStage } from './hooks-preview.js';
@@ -39,25 +38,6 @@ export async function quickStartPath(
   // 1. Provider setup (first question)
   await providerSetupStage(prompter, state);
 
-  // Belt-and-suspenders guard: ensure a provider key was set before proceeding.
-  // The interactive path in providerSetupStage always requires a key, so this
-  // guard is effectively unreachable interactively. The headless path may
-  // produce providerType='none' when no env var is present: there we warn (the
-  // operator can configure a key later via `mosaic gateway install`) and let
-  // the scripted install continue — finalize.ts will NOT print "Mosaic is
-  // ready" without a configured provider, so no false-green is possible.
-  if (state.providerType === 'none' || !state.providerKey) {
-    const headlessRun = process.env['MOSAIC_ASSUME_YES'] === '1' || !process.stdin.isTTY;
-    if (!headlessRun) {
-      prompter.warn(
-        'A provider API key is required to continue. ' +
-          'Set MOSAIC_ANTHROPIC_API_KEY or MOSAIC_OPENAI_API_KEY and run the wizard again, ' +
-          'or run `mosaic gateway install` to configure one after installation.',
-      );
-      throw new WizardCancelledError('No LLM provider configured');
-    }
-  }
-
   // Apply sensible defaults for everything else
   state.soul.agentName ??= 'Mosaic';
   state.soul.roleDescription ??= DEFAULTS.roleDescription;