fix(installer): require provider in quick-start (#1) + local-tier gateway Redis gate (#2)

Bug #1 — quick-start wizard let users skip the LLM provider/API key yet
reported "Mosaic is ready". provider-setup now requires an interactive
provider select + a validated key; quick-start guards the headless path;
finalize won't print "Mosaic is ready" without a configured provider;
removed references to the non-existent `mosaic configure` command.

Bug #2 — the "local" storage tier still opened ioredis/BullMQ
connections at bootstrap (ECONNREFUSED, gateway never healthy). Every
Redis consumer (queue.service, gc.module, session-gc.service,
commands.module, command-executor.service, system-override.service,
cron.service, admin-health.controller) is now tier-aware and degrades
gracefully on local tier. Standalone/Federated unaffected. Also fixed a
pre-existing SystemOverrideService ioredis handle leak (added shutdown hook).

Refs #675

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMoEx7hfdFGjUiCHuN1RRi

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

@@ -69,6 +69,8 @@ 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',
@@ -103,6 +105,8 @@ 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',
@@ -125,6 +129,8 @@ 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/src/errors.ts

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

packages/mosaic/src/stages/finalize.ts

@@ -207,9 +207,16 @@ 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}`,
@@ -239,5 +246,12 @@ export async function finalizeStage(
 
   p.note(nextSteps.map((s, i) => `${(i + 1).toString()}. ${s}`).join('\n'), 'Next Steps');
 
-  p.outro('Mosaic is ready.');
+  if (!providerConfigured) {
+    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/provider-setup.spec.ts

@@ -78,7 +78,7 @@ describe('providerSetupStage', () => {
     expect(state.providerType).toBe('none');
   });
 
-  it('prompts for key in interactive mode', async () => {
+  it('prompts for provider then key in interactive mode', async () => {
     delete process.env['MOSAIC_ASSUME_YES'];
     // Simulate a TTY
     const origIsTTY = process.stdin.isTTY;
@@ -86,11 +86,13 @@ 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');
@@ -98,20 +100,57 @@ describe('providerSetupStage', () => {
     Object.defineProperty(process.stdin, 'isTTY', { value: origIsTTY, configurable: true });
   });
 
-  it('handles empty key in interactive mode', async () => {
+  it('rejects empty and mismatched keys via the validate callback (Anthropic)', 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({
-      text: vi.fn().mockResolvedValue(''),
+      select: vi.fn().mockResolvedValue('anthropic'),
+      text: vi
+        .fn()
+        .mockImplementation(async (opts: { validate?: (v: string) => string | void }) => {
+          capturedValidate = opts.validate;
+          return 'sk-ant-api03-ok';
+        }),
     });
 
     await providerSetupStage(p, state);
 
-    expect(state.providerType).toBe('none');
-    expect(state.providerKey).toBeUndefined();
+    expect(capturedValidate).toBeDefined();
+    expect(capturedValidate?.('')).toBe('API key is required');
+    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,12 +1,13 @@
 import type { WizardPrompter } from '../prompter/interface.js';
 import type { WizardState } from '../types.js';
-import { detectProviderType } from '../constants.js';
+import type { ProviderType } from '../types.js';
 
 /**
- * Provider setup stage — collects the user's LLM API key and detects the
+ * Provider setup stage — collects the user's LLM API key and validates 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;
@@ -16,39 +17,57 @@ export async function providerSetupStage(p: WizardPrompter, state: WizardState):
     const openaiKey = process.env['MOSAIC_OPENAI_API_KEY'] ?? '';
     const key = anthropicKey || openaiKey;
     state.providerKey = key || undefined;
-    state.providerType = detectProviderType(key);
+    if (anthropicKey) {
+      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.\n' +
-      'You can skip this and add a key later via `mosaic configure`.',
+      'Anthropic (Claude) and OpenAI are supported. You will need an API key to continue.',
     'LLM Provider',
   );
 
-  const key = await p.text({
-    message: 'API key (paste your Anthropic or OpenAI key, or press Enter to skip)',
-    defaultValue: '',
-    placeholder: 'sk-ant-api03-... or sk-...',
+  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',
   });
 
-  if (key) {
-    const provider = detectProviderType(key);
-    state.providerKey = key;
-    state.providerType = provider;
+  const key = await p.text({
+    message: providerType === 'anthropic' ? 'Anthropic API key' : 'OpenAI API key',
+    placeholder: providerType === 'anthropic' ? 'sk-ant-api03-...' : 'sk-...',
+    validate: (value: string): string | void => {
+      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-)';
+      }
+    },
+  });
 
-    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`.');
-  }
+  state.providerKey = key.trim();
+  state.providerType = providerType;
+  p.log(`Provider configured: ${providerType === 'anthropic' ? 'Anthropic (Claude)' : 'OpenAI'}`);
 }

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

@@ -2,6 +2,7 @@ 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';
@@ -38,6 +39,25 @@ 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;