feat(mosaic): add top-level mosaic config command (CU-04-04, CU-04-05)

Adds `mosaic config` command tree with five subcommands (show, get, set, edit, path) backed by ConfigService; adds minimal get/set/path/readAll primitives to ConfigService + FileConfigAdapter. Includes Vitest tests. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-05 00:22:30 -05:00
24 changed files with 7 additions and 2149 deletions
--- a/packages/forge/package.json
+++ b/packages/forge/package.json
@@ -26,8 +26,7 @@
    "test": "vitest run --passWithNoTests"
  },
  "dependencies": {
-    "@mosaicstack/macp": "workspace:*",
+    "@mosaicstack/macp": "workspace:*"
    "commander": "^13.0.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
--- a/packages/forge/src/cli.spec.ts
+++ b/packages/forge/src/cli.spec.ts
@@ -1,57 +0,0 @@
 import { Command } from 'commander';
 import { describe, expect, it } from 'vitest';
 import { registerForgeCommand } from './cli.js';
 describe('registerForgeCommand', () => {
  it('registers a "forge" command on the parent program', () => {
    const program = new Command();
    registerForgeCommand(program);
    const forgeCmd = program.commands.find((c) => c.name() === 'forge');
    expect(forgeCmd).toBeDefined();
  });
  it('registers the four required subcommands under forge', () => {
    const program = new Command();
    registerForgeCommand(program);
    const forgeCmd = program.commands.find((c) => c.name() === 'forge');
    expect(forgeCmd).toBeDefined();
    const subNames = forgeCmd!.commands.map((c) => c.name());
    expect(subNames).toContain('run');
    expect(subNames).toContain('status');
    expect(subNames).toContain('resume');
    expect(subNames).toContain('personas');
  });
  it('registers "personas list" as a subcommand of "forge personas"', () => {
    const program = new Command();
    registerForgeCommand(program);
    const forgeCmd = program.commands.find((c) => c.name() === 'forge');
    const personasCmd = forgeCmd!.commands.find((c) => c.name() === 'personas');
    expect(personasCmd).toBeDefined();
    const personasSubNames = personasCmd!.commands.map((c) => c.name());
    expect(personasSubNames).toContain('list');
  });
  it('does not modify the parent program name or description', () => {
    const program = new Command('mosaic');
    program.description('Mosaic Stack CLI');
    registerForgeCommand(program);
    expect(program.name()).toBe('mosaic');
    expect(program.description()).toBe('Mosaic Stack CLI');
  });
  it('can be called multiple times without throwing', () => {
    const program = new Command();
    expect(() => {
      registerForgeCommand(program);
    }).not.toThrow();
  });
 });
--- a/packages/forge/src/cli.ts
+++ b/packages/forge/src/cli.ts
@@ -1,280 +0,0 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import type { Command } from 'commander';
 import { classifyBrief } from './brief-classifier.js';
 import { STAGE_LABELS, STAGE_SEQUENCE } from './constants.js';
 import { getEffectivePersonas, loadBoardPersonas } from './persona-loader.js';
 import { generateRunId, getPipelineStatus, loadManifest, runPipeline } from './pipeline-runner.js';
 import type { PipelineOptions, RunManifest, TaskExecutor } from './types.js';
 // ---------------------------------------------------------------------------
 // Stub executor — used when no real executor is wired at CLI invocation time.
 // ---------------------------------------------------------------------------
 const stubExecutor: TaskExecutor = {
  async submitTask(task) {
    console.log(`  [forge] stage submitted: ${task.id} (${task.title})`);
  },
  async waitForCompletion(taskId, _timeoutMs) {
    console.log(`  [forge] stage complete:  ${taskId}`);
    return {
      task_id: taskId,
      status: 'completed' as const,
      completed_at: new Date().toISOString(),
      exit_code: 0,
      gate_results: [],
    };
  },
  async getTaskStatus(_taskId) {
    return 'completed' as const;
  },
 };
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 function formatDuration(startedAt?: string, completedAt?: string): string {
  if (!startedAt || !completedAt) return '-';
  const ms = new Date(completedAt).getTime() - new Date(startedAt).getTime();
  const secs = Math.round(ms / 1000);
  return secs < 60 ? `${secs}s` : `${Math.floor(secs / 60)}m${secs % 60}s`;
 }
 function printManifestTable(manifest: RunManifest): void {
  console.log(`\nRun ID : ${manifest.runId}`);
  console.log(`Status : ${manifest.status}`);
  console.log(`Brief  : ${manifest.brief}`);
  console.log(`Class  : ${manifest.briefClass} (${manifest.classSource})`);
  console.log(`Updated: ${manifest.updatedAt}`);
  console.log('');
  console.log('Stage'.padEnd(22) + 'Status'.padEnd(14) + 'Duration');
  console.log('-'.repeat(50));
  for (const stage of STAGE_SEQUENCE) {
    const s = manifest.stages[stage];
    if (!s) continue;
    const label = (STAGE_LABELS[stage] ?? stage).padEnd(22);
    const status = s.status.padEnd(14);
    const dur = formatDuration(s.startedAt, s.completedAt);
    console.log(`${label}${status}${dur}`);
  }
  console.log('');
 }
 function resolveRunDir(runId: string, projectRoot?: string): string {
  const root = projectRoot ?? process.cwd();
  return path.join(root, '.forge', 'runs', runId);
 }
 function listRecentRuns(projectRoot?: string): void {
  const root = projectRoot ?? process.cwd();
  const runsDir = path.join(root, '.forge', 'runs');
  if (!fs.existsSync(runsDir)) {
    console.log('No runs found. Run `mosaic forge run` to start a pipeline.');
    return;
  }
  const entries = fs
    .readdirSync(runsDir)
    .filter((name) => fs.statSync(path.join(runsDir, name)).isDirectory())
    .sort()
    .reverse()
    .slice(0, 10);
  if (entries.length === 0) {
    console.log('No runs found.');
    return;
  }
  console.log('\nRecent runs:');
  console.log('Run ID'.padEnd(22) + 'Status'.padEnd(14) + 'Brief');
  console.log('-'.repeat(70));
  for (const runId of entries) {
    const runDir = path.join(runsDir, runId);
    try {
      const manifest = loadManifest(runDir);
      const status = manifest.status.padEnd(14);
      const brief = path.basename(manifest.brief);
      console.log(`${runId.padEnd(22)}${status}${brief}`);
    } catch {
      console.log(`${runId.padEnd(22)}${'(unreadable)'.padEnd(14)}`);
    }
  }
  console.log('');
 }
 // ---------------------------------------------------------------------------
 // Register function
 // ---------------------------------------------------------------------------
 /**
 * Register forge subcommands on an existing Commander program.
 * Mirrors the pattern used by registerQualityRails in @mosaicstack/quality-rails.
 */
 export function registerForgeCommand(parent: Command): void {
  const forge = parent.command('forge').description('Run and manage Forge pipelines');
  // ── forge run ────────────────────────────────────────────────────────────
  forge
    .command('run')
    .description('Run a Forge pipeline from a brief markdown file')
    .requiredOption('--brief <path>', 'Path to the brief markdown file')
    .option('--run-id <id>', 'Override the auto-generated run ID')
    .option('--resume', 'Resume an existing run instead of starting a new one', false)
    .option('--config <path>', 'Path to forge config file (.forge/config.yaml)')
    .option('--codebase <path>', 'Codebase root to pass to the pipeline', process.cwd())
    .option('--dry-run', 'Print planned stages without executing', false)
    .action(
      async (opts: {
        brief: string;
        runId?: string;
        resume: boolean;
        config?: string;
        codebase: string;
        dryRun: boolean;
      }) => {
        const briefPath = path.resolve(opts.brief);
        if (!fs.existsSync(briefPath)) {
          console.error(`[forge] brief not found: ${briefPath}`);
          process.exitCode = 1;
          return;
        }
        const briefContent = fs.readFileSync(briefPath, 'utf-8');
        const briefClass = classifyBrief(briefContent);
        const projectRoot = opts.codebase;
        if (opts.resume) {
          const runId = opts.runId ?? generateRunId();
          const runDir = resolveRunDir(runId, projectRoot);
          console.log(`[forge] resuming run: ${runId}`);
          const { resumePipeline } = await import('./pipeline-runner.js');
          const result = await resumePipeline(runDir, stubExecutor);
          console.log(`[forge] pipeline complete: ${result.runId}`);
          return;
        }
        const pipelineOptions: PipelineOptions = {
          briefClass,
          codebase: projectRoot,
          dryRun: opts.dryRun,
          executor: stubExecutor,
        };
        if (opts.dryRun) {
          const { stagesForClass } = await import('./brief-classifier.js');
          const stages = stagesForClass(briefClass);
          console.log(`[forge] dry-run — brief class: ${briefClass}`);
          console.log('[forge] planned stages:');
          for (const stage of stages) {
            console.log(`  - ${stage}  (${STAGE_LABELS[stage] ?? stage})`);
          }
          return;
        }
        console.log(`[forge] starting pipeline for brief: ${briefPath}`);
        console.log(`[forge] classified as: ${briefClass}`);
        try {
          const result = await runPipeline(briefPath, projectRoot, pipelineOptions);
          console.log(`[forge] pipeline complete: ${result.runId}`);
          console.log(`[forge] run directory: ${result.runDir}`);
        } catch (err) {
          console.error(
            `[forge] pipeline failed: ${err instanceof Error ? err.message : String(err)}`,
          );
          process.exitCode = 1;
        }
      },
    );
  // ── forge status ─────────────────────────────────────────────────────────
  forge
    .command('status [runId]')
    .description('Show the status of a pipeline run (omit runId to list recent runs)')
    .option('--project <path>', 'Project root (defaults to cwd)', process.cwd())
    .action(async (runId: string | undefined, opts: { project: string }) => {
      if (!runId) {
        listRecentRuns(opts.project);
        return;
      }
      const runDir = resolveRunDir(runId, opts.project);
      try {
        const manifest = getPipelineStatus(runDir);
        printManifestTable(manifest);
      } catch (err) {
        console.error(
          `[forge] could not load run "${runId}": ${err instanceof Error ? err.message : String(err)}`,
        );
        process.exitCode = 1;
      }
    });
  // ── forge resume ─────────────────────────────────────────────────────────
  forge
    .command('resume <runId>')
    .description('Resume a stopped or failed pipeline run')
    .option('--project <path>', 'Project root (defaults to cwd)', process.cwd())
    .action(async (runId: string, opts: { project: string }) => {
      const runDir = resolveRunDir(runId, opts.project);
      if (!fs.existsSync(runDir)) {
        console.error(`[forge] run not found: ${runDir}`);
        process.exitCode = 1;
        return;
      }
      console.log(`[forge] resuming run: ${runId}`);
      try {
        const { resumePipeline } = await import('./pipeline-runner.js');
        const result = await resumePipeline(runDir, stubExecutor);
        console.log(`[forge] pipeline complete: ${result.runId}`);
        console.log(`[forge] run directory: ${result.runDir}`);
      } catch (err) {
        console.error(`[forge] resume failed: ${err instanceof Error ? err.message : String(err)}`);
        process.exitCode = 1;
      }
    });
  // ── forge personas ────────────────────────────────────────────────────────
  const personas = forge.command('personas').description('Manage Forge board personas');
  personas
    .command('list')
    .description('List configured board personas')
    .option(
      '--project <path>',
      'Project root for persona overrides (defaults to cwd)',
      process.cwd(),
    )
    .option('--board-dir <path>', 'Override the board agents directory')
    .action((opts: { project: string; boardDir?: string }) => {
      const effectivePersonas = opts.boardDir
        ? loadBoardPersonas(opts.boardDir)
        : getEffectivePersonas(opts.project);
      if (effectivePersonas.length === 0) {
        console.log('[forge] no board personas configured.');
        return;
      }
      console.log(`\nBoard personas (${effectivePersonas.length}):\n`);
      console.log('Slug'.padEnd(24) + 'Name');
      console.log('-'.repeat(50));
      for (const p of effectivePersonas) {
        console.log(`${p.slug.padEnd(24)}${p.name}`);
      }
      console.log('');
    });
 }
--- a/packages/forge/src/index.ts
+++ b/packages/forge/src/index.ts
@@ -80,6 +80,3 @@ export {
  resumePipeline,
  getPipelineStatus,
 } from './pipeline-runner.js';
 // CLI
 export { registerForgeCommand } from './cli.js';
--- a/packages/memory/package.json
+++ b/packages/memory/package.json
@@ -25,7 +25,6 @@
    "@mosaicstack/db": "workspace:*",
    "@mosaicstack/storage": "workspace:*",
    "@mosaicstack/types": "workspace:*",
    "commander": "^13.0.0",
    "drizzle-orm": "^0.45.1"
  },
  "devDependencies": {
--- a/packages/memory/src/cli.spec.ts
+++ b/packages/memory/src/cli.spec.ts
@@ -1,63 +0,0 @@
 import { describe, it, expect } from 'vitest';
 import { Command } from 'commander';
 import { registerMemoryCommand } from './cli.js';
 /**
 * Smoke test — only verifies command wiring.
 * Does NOT open a database connection.
 */
 describe('registerMemoryCommand', () => {
  function buildProgram(): Command {
    const program = new Command('mosaic');
    program.exitOverride(); // prevent process.exit during tests
    registerMemoryCommand(program);
    return program;
  }
  it('registers a "memory" subcommand', () => {
    const program = buildProgram();
    const memory = program.commands.find((c) => c.name() === 'memory');
    expect(memory).toBeDefined();
  });
  it('registers "memory search"', () => {
    const program = buildProgram();
    const memory = program.commands.find((c) => c.name() === 'memory')!;
    const search = memory.commands.find((c) => c.name() === 'search');
    expect(search).toBeDefined();
  });
  it('registers "memory stats"', () => {
    const program = buildProgram();
    const memory = program.commands.find((c) => c.name() === 'memory')!;
    const stats = memory.commands.find((c) => c.name() === 'stats');
    expect(stats).toBeDefined();
  });
  it('registers "memory insights list"', () => {
    const program = buildProgram();
    const memory = program.commands.find((c) => c.name() === 'memory')!;
    const insights = memory.commands.find((c) => c.name() === 'insights');
    expect(insights).toBeDefined();
    const list = insights!.commands.find((c) => c.name() === 'list');
    expect(list).toBeDefined();
  });
  it('registers "memory preferences list"', () => {
    const program = buildProgram();
    const memory = program.commands.find((c) => c.name() === 'memory')!;
    const preferences = memory.commands.find((c) => c.name() === 'preferences');
    expect(preferences).toBeDefined();
    const list = preferences!.commands.find((c) => c.name() === 'list');
    expect(list).toBeDefined();
  });
  it('"memory search" has --limit and --agent options', () => {
    const program = buildProgram();
    const memory = program.commands.find((c) => c.name() === 'memory')!;
    const search = memory.commands.find((c) => c.name() === 'search')!;
    const optNames = search.options.map((o) => o.long);
    expect(optNames).toContain('--limit');
    expect(optNames).toContain('--agent');
  });
 });
--- a/packages/memory/src/cli.ts
+++ b/packages/memory/src/cli.ts
@@ -1,179 +0,0 @@
 import type { Command } from 'commander';
 import type { MemoryAdapter } from './types.js';
 /**
 * Build and return a connected MemoryAdapter from a connection string or
 * the MEMORY_DB_URL / DATABASE_URL environment variable.
 *
 * For pgvector (postgres://...) the connection string is injected into
 * DATABASE_URL so that PgVectorAdapter's internal createDb() picks it up.
 *
 * Throws with a human-readable message if no connection info is available.
 */
 async function resolveAdapter(dbOption: string | undefined): Promise<MemoryAdapter> {
  const connStr = dbOption ?? process.env['MEMORY_DB_URL'] ?? process.env['DATABASE_URL'];
  if (!connStr) {
    throw new Error(
      'No database connection string provided. ' +
        'Pass --db <connection-string> or set MEMORY_DB_URL / DATABASE_URL.',
    );
  }
  // Lazy imports so the module loads cleanly without a live DB during smoke tests.
  const { createMemoryAdapter, registerMemoryAdapter } = await import('./factory.js');
  if (connStr.startsWith('postgres') || connStr.startsWith('pg')) {
    // PgVectorAdapter reads DATABASE_URL via createDb() — inject it here.
    process.env['DATABASE_URL'] = connStr;
    const { PgVectorAdapter } = await import('./adapters/pgvector.js');
    registerMemoryAdapter('pgvector', (cfg) => new PgVectorAdapter(cfg as never));
    return createMemoryAdapter({ type: 'pgvector' });
  }
  // Keyword adapter backed by pglite storage; treat connStr as a data directory.
  const { KeywordAdapter } = await import('./adapters/keyword.js');
  const { createStorageAdapter, registerStorageAdapter } = await import('@mosaicstack/storage');
  const { PgliteAdapter } = await import('@mosaicstack/storage');
  registerStorageAdapter('pglite', (cfg) => new PgliteAdapter(cfg as never));
  const storage = createStorageAdapter({ type: 'pglite', dataDir: connStr });
  registerMemoryAdapter('keyword', (cfg) => new KeywordAdapter(cfg as never));
  return createMemoryAdapter({ type: 'keyword', storage });
 }
 /**
 * Register `memory` subcommands on an existing Commander program.
 * Follows the registerQualityRails pattern from @mosaicstack/quality-rails.
 */
 export function registerMemoryCommand(parent: Command): void {
  const memory = parent.command('memory').description('Inspect and query the Mosaic memory layer');
  // ── memory search <query> ──────────────────────────────────────────────
  memory
    .command('search <query>')
    .description('Semantic search over insights')
    .option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
    .option('--limit <n>', 'Maximum number of results', '10')
    .option('--agent <id>', 'Filter by agent / user ID')
    .action(async (query: string, opts: { db?: string; limit: string; agent?: string }) => {
      let adapter: MemoryAdapter | undefined;
      try {
        adapter = await resolveAdapter(opts.db);
        const limit = parseInt(opts.limit, 10);
        const userId = opts.agent ?? 'system';
        const results = await adapter.searchInsights(userId, query, { limit });
        if (results.length === 0) {
          console.log('No insights found.');
        } else {
          for (const r of results) {
            console.log(`[${r.id}] (score=${r.score.toFixed(3)}) ${r.content}`);
          }
        }
      } catch (err) {
        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
        process.exitCode = 1;
      } finally {
        await adapter?.close();
      }
    });
  // ── memory stats ──────────────────────────────────────────────────────
  memory
    .command('stats')
    .description('Print memory tier info: adapter type, insight count, preference count')
    .option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
    .option('--agent <id>', 'User / agent ID scope for counts', 'system')
    .action(async (opts: { db?: string; agent: string }) => {
      let adapter: MemoryAdapter | undefined;
      try {
        adapter = await resolveAdapter(opts.db);
        const adapterType = adapter.name;
        const insightCount = await adapter
          .searchInsights(opts.agent, '', { limit: 100000 })
          .then((r) => r.length)
          .catch(() => -1);
        const prefCount = await adapter
          .listPreferences(opts.agent)
          .then((r) => r.length)
          .catch(() => -1);
        console.log(`adapter:     ${adapterType}`);
        console.log(`insights:    ${insightCount === -1 ? 'unavailable' : String(insightCount)}`);
        console.log(`preferences: ${prefCount === -1 ? 'unavailable' : String(prefCount)}`);
      } catch (err) {
        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
        process.exitCode = 1;
      } finally {
        await adapter?.close();
      }
    });
  // ── memory insights ───────────────────────────────────────────────────
  const insightsCmd = memory.command('insights').description('Manage insights');
  insightsCmd
    .command('list')
    .description('List recent insights')
    .option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
    .option('--limit <n>', 'Maximum number of results', '20')
    .option('--agent <id>', 'User / agent ID scope', 'system')
    .action(async (opts: { db?: string; limit: string; agent: string }) => {
      let adapter: MemoryAdapter | undefined;
      try {
        adapter = await resolveAdapter(opts.db);
        const limit = parseInt(opts.limit, 10);
        const results = await adapter.searchInsights(opts.agent, '', { limit });
        if (results.length === 0) {
          console.log('No insights found.');
        } else {
          for (const r of results) {
            console.log(`[${r.id}] ${r.content}`);
          }
        }
      } catch (err) {
        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
        process.exitCode = 1;
      } finally {
        await adapter?.close();
      }
    });
  // ── memory preferences ────────────────────────────────────────────────
  const prefsCmd = memory.command('preferences').description('Manage stored preferences');
  prefsCmd
    .command('list')
    .description('List stored preferences')
    .option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
    .option('--agent <id>', 'User / agent ID scope', 'system')
    .option('--category <cat>', 'Filter by category')
    .action(async (opts: { db?: string; agent: string; category?: string }) => {
      let adapter: MemoryAdapter | undefined;
      try {
        adapter = await resolveAdapter(opts.db);
        const prefs = await adapter.listPreferences(opts.agent, opts.category);
        if (prefs.length === 0) {
          console.log('No preferences found.');
        } else {
          for (const p of prefs) {
            console.log(`[${p.category}] ${p.key} = ${JSON.stringify(p.value)}`);
          }
        }
      } catch (err) {
        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
        process.exitCode = 1;
      } finally {
        await adapter?.close();
      }
    });
 }
--- a/packages/memory/src/index.ts
+++ b/packages/memory/src/index.ts
@@ -1,5 +1,4 @@
 export { createMemory, type Memory } from './memory.js';
 export { registerMemoryCommand } from './cli.js';
 export {
  createPreferencesRepo,
  type PreferencesRepo,
--- a/packages/mosaic/package.json
+++ b/packages/mosaic/package.json
@@ -31,10 +31,8 @@
    "@mosaicstack/config": "workspace:*",
    "@mosaicstack/forge": "workspace:*",
    "@mosaicstack/macp": "workspace:*",
    "@mosaicstack/memory": "workspace:*",
    "@mosaicstack/prdy": "workspace:*",
    "@mosaicstack/quality-rails": "workspace:*",
    "@mosaicstack/queue": "workspace:*",
    "@mosaicstack/types": "workspace:*",
    "@clack/prompts": "^0.9.1",
    "commander": "^13.0.0",
--- a/packages/mosaic/src/cli.ts
+++ b/packages/mosaic/src/cli.ts
@@ -3,16 +3,12 @@
 import { createRequire } from 'module';
 import { Command } from 'commander';
 import { registerBrainCommand } from '@mosaicstack/brain';
 import { registerForgeCommand } from '@mosaicstack/forge';
 import { registerMemoryCommand } from '@mosaicstack/memory';
 import { registerQualityRails } from '@mosaicstack/quality-rails';
 import { registerQueueCommand } from '@mosaicstack/queue';
 import { registerAgentCommand } from './commands/agent.js';
 import { registerConfigCommand } from './commands/config.js';
 import { registerMissionCommand } from './commands/mission.js';
 // prdy is registered via launch.ts
 import { registerLaunchCommands } from './commands/launch.js';
 import { registerAuthCommand } from './commands/auth.js';
 import { registerGatewayCommand } from './commands/gateway.js';
 import {
  backgroundUpdateCheck,
@@ -327,10 +323,6 @@ sessionsCmd
    }
  });
 // ─── auth ────────────────────────────────────────────────────────────────
 registerAuthCommand(program);
 // ─── gateway ──────────────────────────────────────────────────────────
 registerGatewayCommand(program);
@@ -351,22 +343,10 @@ registerMissionCommand(program);
 registerBrainCommand(program);
 // ─── forge ───────────────────────────────────────────────────────────────
 registerForgeCommand(program);
 // ─── quality-rails ──────────────────────────────────────────────────────
 registerQualityRails(program);
 // ─── memory ──────────────────────────────────────────────────────────────
 registerMemoryCommand(program);
 // ─── queue ───────────────────────────────────────────────────────────────
 registerQueueCommand(program);
 // ─── update ─────────────────────────────────────────────────────────────
 program
--- a/packages/mosaic/src/commands/auth.spec.ts
+++ b/packages/mosaic/src/commands/auth.spec.ts
@@ -1,114 +0,0 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { Command } from 'commander';
 // ─── Mocks ──────────────────────────────────────────────────────────────────
 // These mocks prevent any real disk/network access during tests.
 vi.mock('./gateway/login.js', () => ({
  getGatewayUrl: vi.fn().mockReturnValue('http://localhost:14242'),
 }));
 vi.mock('./gateway/token-ops.js', () => ({
  requireSession: vi.fn().mockResolvedValue('better-auth.session_token=test'),
 }));
 // Global fetch is never called in smoke tests (no actions invoked).
 import { registerAuthCommand } from './auth.js';
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 function buildTestProgram(): Command {
  const program = new Command('mosaic').exitOverride();
  registerAuthCommand(program);
  return program;
 }
 function findCommand(program: Command, ...path: string[]): Command | undefined {
  let current: Command = program;
  for (const name of path) {
    const found = current.commands.find((c) => c.name() === name);
    if (!found) return undefined;
    current = found;
  }
  return current;
 }
 // ─── Tests ───────────────────────────────────────────────────────────────────
 describe('registerAuthCommand', () => {
  let program: Command;
  beforeEach(() => {
    vi.clearAllMocks();
    program = buildTestProgram();
  });
  it('registers the top-level auth command', () => {
    const authCmd = findCommand(program, 'auth');
    expect(authCmd).toBeDefined();
    expect(authCmd?.name()).toBe('auth');
  });
  describe('auth users', () => {
    it('registers the users subcommand', () => {
      const usersCmd = findCommand(program, 'auth', 'users');
      expect(usersCmd).toBeDefined();
    });
    it('registers users list with --limit flag', () => {
      const listCmd = findCommand(program, 'auth', 'users', 'list');
      expect(listCmd).toBeDefined();
      const limitOpt = listCmd?.options.find((o) => o.long === '--limit');
      expect(limitOpt).toBeDefined();
    });
    it('registers users create', () => {
      const createCmd = findCommand(program, 'auth', 'users', 'create');
      expect(createCmd).toBeDefined();
    });
    it('registers users delete with --yes flag', () => {
      const deleteCmd = findCommand(program, 'auth', 'users', 'delete');
      expect(deleteCmd).toBeDefined();
      const yesOpt = deleteCmd?.options.find((o) => o.long === '--yes');
      expect(yesOpt).toBeDefined();
    });
  });
  describe('auth sso', () => {
    it('registers the sso subcommand', () => {
      const ssoCmd = findCommand(program, 'auth', 'sso');
      expect(ssoCmd).toBeDefined();
    });
    it('registers sso list', () => {
      const listCmd = findCommand(program, 'auth', 'sso', 'list');
      expect(listCmd).toBeDefined();
    });
    it('registers sso test', () => {
      const testCmd = findCommand(program, 'auth', 'sso', 'test');
      expect(testCmd).toBeDefined();
    });
  });
  describe('auth sessions', () => {
    it('registers the sessions subcommand', () => {
      const sessCmd = findCommand(program, 'auth', 'sessions');
      expect(sessCmd).toBeDefined();
    });
    it('registers sessions list', () => {
      const listCmd = findCommand(program, 'auth', 'sessions', 'list');
      expect(listCmd).toBeDefined();
    });
  });
  it('all top-level auth subcommand names are correct', () => {
    const authCmd = findCommand(program, 'auth');
    expect(authCmd).toBeDefined();
    const names = authCmd!.commands.map((c) => c.name()).sort();
    expect(names).toEqual(['sessions', 'sso', 'users']);
  });
 });
--- a/packages/mosaic/src/commands/auth.ts
+++ b/packages/mosaic/src/commands/auth.ts
@@ -1,331 +0,0 @@
 import type { Command } from 'commander';
 import { getGatewayUrl } from './gateway/login.js';
 import { requireSession } from './gateway/token-ops.js';
 // ─── Types ───────────────────────────────────────────────────────────────────
 interface UserDto {
  id: string;
  name: string;
  email: string;
  role: string;
  banned: boolean;
  banReason: string | null;
  createdAt: string;
  updatedAt: string;
 }
 interface UserListDto {
  users: UserDto[];
  total: number;
 }
 // ─── HTTP helpers ────────────────────────────────────────────────────────────
 async function adminGet<T>(gatewayUrl: string, cookie: string, path: string): Promise<T> {
  let res: Response;
  try {
    res = await fetch(`${gatewayUrl}${path}`, {
      headers: { Cookie: cookie, Origin: gatewayUrl },
    });
  } catch (err) {
    console.error(
      `Could not reach gateway at ${gatewayUrl}: ${err instanceof Error ? err.message : String(err)}`,
    );
    process.exit(1);
  }
  if (res.status === 401 || res.status === 403) {
    console.error(`Session rejected by the gateway (${res.status.toString()}).`);
    console.error('Run: mosaic gateway login');
    process.exit(2);
  }
  if (!res.ok) {
    const body = await res.text().catch(() => '');
    console.error(`Gateway returned error (${res.status.toString()}): ${body.slice(0, 200)}`);
    process.exit(3);
  }
  return res.json() as Promise<T>;
 }
 async function adminPost<T>(
  gatewayUrl: string,
  cookie: string,
  path: string,
  body: unknown,
 ): Promise<T> {
  let res: Response;
  try {
    res = await fetch(`${gatewayUrl}${path}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Cookie: cookie,
        Origin: gatewayUrl,
      },
      body: JSON.stringify(body),
    });
  } catch (err) {
    console.error(
      `Could not reach gateway at ${gatewayUrl}: ${err instanceof Error ? err.message : String(err)}`,
    );
    process.exit(1);
  }
  if (res.status === 401 || res.status === 403) {
    console.error(`Session rejected by the gateway (${res.status.toString()}).`);
    console.error('Run: mosaic gateway login');
    process.exit(2);
  }
  if (!res.ok) {
    const body = await res.text().catch(() => '');
    console.error(`Gateway returned error (${res.status.toString()}): ${body.slice(0, 200)}`);
    process.exit(3);
  }
  return res.json() as Promise<T>;
 }
 async function adminDelete(gatewayUrl: string, cookie: string, path: string): Promise<void> {
  let res: Response;
  try {
    res = await fetch(`${gatewayUrl}${path}`, {
      method: 'DELETE',
      headers: { Cookie: cookie, Origin: gatewayUrl },
    });
  } catch (err) {
    console.error(
      `Could not reach gateway at ${gatewayUrl}: ${err instanceof Error ? err.message : String(err)}`,
    );
    process.exit(1);
  }
  if (res.status === 401 || res.status === 403) {
    console.error(`Session rejected by the gateway (${res.status.toString()}).`);
    console.error('Run: mosaic gateway login');
    process.exit(2);
  }
  if (!res.ok && res.status !== 204) {
    const body = await res.text().catch(() => '');
    console.error(`Gateway returned error (${res.status.toString()}): ${body.slice(0, 200)}`);
    process.exit(3);
  }
 }
 // ─── Formatters ──────────────────────────────────────────────────────────────
 function printUser(u: UserDto): void {
  console.log(`  ID:        ${u.id}`);
  console.log(`  Name:      ${u.name}`);
  console.log(`  Email:     ${u.email}`);
  console.log(`  Role:      ${u.role}`);
  console.log(`  Banned:    ${u.banned ? `yes (${u.banReason ?? 'no reason'})` : 'no'}`);
  console.log(`  Created:   ${new Date(u.createdAt).toLocaleString()}`);
  console.log('');
 }
 // ─── Register function ───────────────────────────────────────────────────────
 /**
 * Register `mosaic auth` subcommands on an existing Commander program.
 *
 * Location rationale: placed in packages/mosaic rather than packages/auth because
 * the CLI needs session helpers (loadSession, validateSession, requireSession)
 * and gateway URL resolution (getGatewayUrl) that live in packages/mosaic.
 * Keeping packages/auth as a pure server-side library avoids adding commander
 * and CLI tooling as dependencies there.
 */
 export function registerAuthCommand(parent: Command): void {
  const auth = parent
    .command('auth')
    .description('Manage gateway authentication, users, SSO providers, and sessions')
    .configureHelp({ sortSubcommands: true })
    .action(() => {
      auth.outputHelp();
    });
  // ─── users ──────────────────────────────────────────────────────────────
  const users = auth
    .command('users')
    .description('Manage gateway users')
    .configureHelp({ sortSubcommands: true })
    .action(() => {
      users.outputHelp();
    });
  users
    .command('list')
    .description('List all users on the gateway')
    .option('-g, --gateway <url>', 'Gateway URL')
    .option('-l, --limit <n>', 'Maximum number of users to display', '100')
    .action(async (opts: { gateway?: string; limit: string }) => {
      const url = getGatewayUrl(opts.gateway);
      const cookie = await requireSession(url);
      const limit = parseInt(opts.limit, 10);
      const result = await adminGet<UserListDto>(url, cookie, '/api/admin/users');
      const subset = result.users.slice(0, limit);
      if (subset.length === 0) {
        console.log('No users found.');
        return;
      }
      console.log(`Users (${subset.length.toString()} of ${result.total.toString()}):\n`);
      for (const u of subset) {
        printUser(u);
      }
    });
  users
    .command('create')
    .description('Create a new gateway user (interactive prompts)')
    .option('-g, --gateway <url>', 'Gateway URL')
    .action(async (opts: { gateway?: string }) => {
      const url = getGatewayUrl(opts.gateway);
      const cookie = await requireSession(url);
      const {
        text,
        password: clackPassword,
        select,
        intro,
        outro,
        isCancel,
      } = await import('@clack/prompts');
      intro('Create a new Mosaic gateway user');
      const name = await text({ message: 'Full name:', placeholder: 'Jane Doe' });
      if (isCancel(name)) {
        outro('Cancelled.');
        process.exit(0);
      }
      const email = await text({ message: 'Email:', placeholder: 'jane@example.com' });
      if (isCancel(email)) {
        outro('Cancelled.');
        process.exit(0);
      }
      const pw = await clackPassword({ message: 'Password:' });
      if (isCancel(pw)) {
        outro('Cancelled.');
        process.exit(0);
      }
      const role = await select({
        message: 'Role:',
        options: [
          { value: 'member', label: 'member' },
          { value: 'admin', label: 'admin' },
        ],
      });
      if (isCancel(role)) {
        outro('Cancelled.');
        process.exit(0);
      }
      const created = await adminPost<UserDto>(url, cookie, '/api/admin/users', {
        name: name as string,
        email: email as string,
        password: pw as string,
        role: role as string,
      });
      outro(`User created: ${created.email} (${created.id})`);
    });
  users
    .command('delete <id>')
    .description('Delete a gateway user by ID')
    .option('-g, --gateway <url>', 'Gateway URL')
    .option('-y, --yes', 'Skip confirmation prompt')
    .action(async (id: string, opts: { gateway?: string; yes?: boolean }) => {
      const url = getGatewayUrl(opts.gateway);
      const cookie = await requireSession(url);
      if (!opts.yes) {
        const { confirm, isCancel } = await import('@clack/prompts');
        const confirmed = await confirm({
          message: `Delete user ${id}? This cannot be undone.`,
        });
        if (isCancel(confirmed) || !confirmed) {
          console.log('Aborted.');
          process.exit(0);
        }
      }
      await adminDelete(url, cookie, `/api/admin/users/${id}`);
      console.log(`User ${id} deleted.`);
    });
  // ─── sso ────────────────────────────────────────────────────────────────
  const sso = auth
    .command('sso')
    .description('Manage SSO provider configuration')
    .configureHelp({ sortSubcommands: true })
    .action(() => {
      sso.outputHelp();
    });
  sso
    .command('list')
    .description('List configured SSO providers (reads gateway discovery endpoint if available)')
    .option('-g, --gateway <url>', 'Gateway URL')
    .action(async (opts: { gateway?: string }) => {
      // The admin SSO discovery endpoint is not yet wired server-side.
      // The buildSsoDiscovery helper in @mosaicstack/auth reads env-vars on the
      // server; there is no GET /api/admin/sso endpoint in apps/gateway/src/admin/.
      // Stub until a gateway admin route is wired.
      console.log(
        'not yet wired — admin endpoint missing (GET /api/admin/sso not implemented server-side)',
      );
      console.log(
        'Hint: SSO providers are configured via environment variables (AUTHENTIK_*, WORKOS_*, KEYCLOAK_*).',
      );
      // Suppress unused variable warning
      void opts;
    });
  sso
    .command('test <provider>')
    .description('Smoke-test a configured SSO provider')
    .option('-g, --gateway <url>', 'Gateway URL')
    .action(async (provider: string, opts: { gateway?: string }) => {
      // No server-side SSO smoke-test endpoint exists yet.
      console.log(
        `not yet wired — admin endpoint missing (POST /api/admin/sso/${provider}/test not implemented server-side)`,
      );
      void opts;
    });
  // ─── sessions ────────────────────────────────────────────────────────────
  const authSessions = auth
    .command('sessions')
    .description('Manage BetterAuth user sessions stored on the gateway')
    .configureHelp({ sortSubcommands: true })
    .action(() => {
      authSessions.outputHelp();
    });
  authSessions
    .command('list')
    .description('List active user sessions')
    .option('-g, --gateway <url>', 'Gateway URL')
    .action(async (opts: { gateway?: string }) => {
      // No GET /api/admin/auth-sessions endpoint exists in apps/gateway/src/admin/.
      // Stub until a gateway admin route is wired.
      console.log(
        'not yet wired — admin endpoint missing (GET /api/admin/auth-sessions not implemented server-side)',
      );
      void opts;
    });
 }
--- a/packages/mosaic/src/commands/gateway.ts
+++ b/packages/mosaic/src/commands/gateway.ts
@@ -6,7 +6,6 @@ import {
  stopDaemon,
  waitForHealth,
 } from './gateway/daemon.js';
 import { getGatewayUrl } from './gateway/login.js';
 interface GatewayParentOpts {
  host: string;
@@ -120,28 +119,9 @@ export function registerGatewayCommand(program: Command): void {
      await runStatus(opts);
    });
  // ─── login ──────────────────────────────────────────────────────────────
  gw.command('login')
    .description('Sign in to the gateway (defaults to URL from meta.json)')
    .option('-g, --gateway <url>', 'Gateway URL (overrides meta.json)')
    .option('-e, --email <email>', 'Email address')
    .option('-p, --password <password>', 'Password')
    .action(async (cmdOpts: { gateway?: string; email?: string; password?: string }) => {
      const { runLogin } = await import('./gateway/login.js');
      const url = getGatewayUrl(cmdOpts.gateway);
      try {
        await runLogin({ gatewayUrl: url, email: cmdOpts.email, password: cmdOpts.password });
      } catch (err) {
        console.error(err instanceof Error ? err.message : String(err));
        process.exit(1);
      }
    });
  // ─── config ─────────────────────────────────────────────────────────────
-  const configCmd = gw
+  gw.command('config')
    .command('config')
    .description('View or modify gateway configuration')
    .option('--set <KEY=VALUE>', 'Set a configuration value')
    .option('--unset <KEY>', 'Remove a configuration key')
@@ -151,24 +131,6 @@ export function registerGatewayCommand(program: Command): void {
      await runConfig(cmdOpts);
    });
  configCmd
    .command('rotate-token')
    .description('Mint a new admin token using the stored BetterAuth session')
    .option('-g, --gateway <url>', 'Gateway URL (overrides meta.json)')
    .action(async (cmdOpts: { gateway?: string }) => {
      const { runRotateToken } = await import('./gateway/token-ops.js');
      await runRotateToken(cmdOpts.gateway);
    });
  configCmd
    .command('recover-token')
    .description('Recover an admin token — prompts for login if no valid session exists')
    .option('-g, --gateway <url>', 'Gateway URL (overrides meta.json)')
    .action(async (cmdOpts: { gateway?: string }) => {
      const { runRecoverToken } = await import('./gateway/token-ops.js');
      await runRecoverToken(cmdOpts.gateway);
    });
  // ─── logs ───────────────────────────────────────────────────────────────
  gw.command('logs')
--- a/packages/mosaic/src/commands/gateway/install.ts
+++ b/packages/mosaic/src/commands/gateway/install.ts
@@ -388,32 +388,10 @@ async function bootstrapFirstUser(
    if (!status.needsSetup) {
      if (meta.adminToken) {
        console.log('Admin user already exists (token on file).');
-        return;
+      } else {
        console.log('Admin user already exists — skipping setup.');
        console.log('(No admin token on file — sign in via the web UI to manage tokens.)');
      }
      // Admin user exists but no token — offer inline recovery when interactive.
      console.log('Admin user already exists but no admin token is on file.');
      if (process.stdin.isTTY) {
        const answer = (await prompt(rl, 'Run token recovery now? [Y/n] ')).trim().toLowerCase();
        if (answer === '' || answer === 'y' || answer === 'yes') {
          console.log();
          try {
            const { ensureSession, mintAdminToken, persistToken } = await import('./token-ops.js');
            const cookie = await ensureSession(baseUrl);
            const label = `CLI recovery token (${new Date().toISOString().slice(0, 16).replace('T', ' ')})`;
            const minted = await mintAdminToken(baseUrl, cookie, label);
            persistToken(baseUrl, minted);
          } catch (err) {
            console.error(
              `Token recovery failed: ${err instanceof Error ? err.message : String(err)}`,
            );
          }
          return;
        }
      }
      console.log('No admin token on file. Run: mosaic gateway config recover-token');
      return;
    }
  } catch {
--- a/packages/mosaic/src/commands/gateway/login.spec.ts
+++ b/packages/mosaic/src/commands/gateway/login.spec.ts
@@ -1,87 +0,0 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 // Mock auth module
 vi.mock('../../auth.js', () => ({
  signIn: vi.fn(),
  saveSession: vi.fn(),
 }));
 // Mock daemon to avoid file-system reads
 vi.mock('./daemon.js', () => ({
  readMeta: vi.fn().mockReturnValue({
    host: 'localhost',
    port: 14242,
    version: '1.0.0',
    installedAt: '',
    entryPoint: '',
  }),
 }));
 import { runLogin, getGatewayUrl } from './login.js';
 import { signIn, saveSession } from '../../auth.js';
 import { readMeta } from './daemon.js';
 const mockSignIn = vi.mocked(signIn);
 const mockSaveSession = vi.mocked(saveSession);
 const mockReadMeta = vi.mocked(readMeta);
 describe('getGatewayUrl', () => {
  it('returns override URL when provided', () => {
    expect(getGatewayUrl('http://my-gateway:9999')).toBe('http://my-gateway:9999');
  });
  it('builds URL from meta.json when no override given', () => {
    mockReadMeta.mockReturnValueOnce({
      host: 'myhost',
      port: 8080,
      version: '1.0.0',
      installedAt: '',
      entryPoint: '',
    });
    expect(getGatewayUrl()).toBe('http://myhost:8080');
  });
  it('falls back to default when meta is null', () => {
    mockReadMeta.mockReturnValueOnce(null);
    expect(getGatewayUrl()).toBe('http://localhost:14242');
  });
 });
 describe('runLogin', () => {
  const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
  beforeEach(() => {
    vi.clearAllMocks();
  });
  it('calls signIn and saveSession on success', async () => {
    const fakeAuth = {
      cookie: 'better-auth.session_token=abc',
      userId: 'u1',
      email: 'admin@test.com',
    };
    mockSignIn.mockResolvedValueOnce(fakeAuth);
    await runLogin({
      gatewayUrl: 'http://localhost:14242',
      email: 'admin@test.com',
      password: 'password123',
    });
    expect(mockSignIn).toHaveBeenCalledWith(
      'http://localhost:14242',
      'admin@test.com',
      'password123',
    );
    expect(mockSaveSession).toHaveBeenCalledWith('http://localhost:14242', fakeAuth);
    expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('admin@test.com'));
  });
  it('propagates signIn errors', async () => {
    mockSignIn.mockRejectedValueOnce(new Error('Sign-in failed (401): invalid credentials'));
    await expect(
      runLogin({ gatewayUrl: 'http://localhost:14242', email: 'bad@test.com', password: 'wrong' }),
    ).rejects.toThrow('Sign-in failed (401)');
  });
 });
--- a/packages/mosaic/src/commands/gateway/login.ts
+++ b/packages/mosaic/src/commands/gateway/login.ts
@@ -1,39 +0,0 @@
 import { createInterface } from 'node:readline';
 import { signIn, saveSession } from '../../auth.js';
 import { readMeta } from './daemon.js';
 /**
 * Shared login helper used by both `mosaic login` and `mosaic gateway login`.
 * Prompts for email/password if not supplied, signs in, and persists the session.
 */
 export async function runLogin(opts: {
  gatewayUrl: string;
  email?: string;
  password?: string;
 }): Promise<void> {
  let email = opts.email;
  let password = opts.password;
  if (!email || !password) {
    const rl = createInterface({ input: process.stdin, output: process.stdout });
    const ask = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
    if (!email) email = await ask('Email: ');
    if (!password) password = await ask('Password: ');
    rl.close();
  }
  const auth = await signIn(opts.gatewayUrl, email, password);
  saveSession(opts.gatewayUrl, auth);
  console.log(`Signed in as ${auth.email} (${opts.gatewayUrl})`);
 }
 /**
 * Derive the gateway base URL from meta.json with a fallback.
 */
 export function getGatewayUrl(overrideUrl?: string): string {
  if (overrideUrl) return overrideUrl;
  const meta = readMeta();
  if (meta) return `http://${meta.host}:${meta.port.toString()}`;
  return 'http://localhost:14242';
 }
--- a/packages/mosaic/src/commands/gateway/recover-token.spec.ts
+++ b/packages/mosaic/src/commands/gateway/recover-token.spec.ts
@@ -1,176 +0,0 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 // ─── Mocks ──────────────────────────────────────────────────────────────────
 vi.mock('../../auth.js', () => ({
  loadSession: vi.fn(),
  validateSession: vi.fn(),
  signIn: vi.fn(),
  saveSession: vi.fn(),
 }));
 vi.mock('./daemon.js', () => ({
  readMeta: vi.fn(),
  writeMeta: vi.fn(),
 }));
 vi.mock('./login.js', () => ({
  getGatewayUrl: vi.fn().mockReturnValue('http://localhost:14242'),
 }));
 // Mock readline so tests don't block on stdin
 vi.mock('node:readline', () => ({
  createInterface: vi.fn().mockReturnValue({
    question: vi.fn((_q: string, cb: (a: string) => void) => cb('test-input')),
    close: vi.fn(),
  }),
 }));
 const mockFetch = vi.fn();
 vi.stubGlobal('fetch', mockFetch);
 import { runRecoverToken, ensureSession } from './token-ops.js';
 import { loadSession, validateSession, signIn, saveSession } from '../../auth.js';
 import { readMeta, writeMeta } from './daemon.js';
 const mockLoadSession = vi.mocked(loadSession);
 const mockValidateSession = vi.mocked(validateSession);
 const mockSignIn = vi.mocked(signIn);
 const mockSaveSession = vi.mocked(saveSession);
 const mockReadMeta = vi.mocked(readMeta);
 const mockWriteMeta = vi.mocked(writeMeta);
 const baseUrl = 'http://localhost:14242';
 const fakeCookie = 'better-auth.session_token=sess123';
 const fakeToken = {
  id: 'tok-1',
  label: 'CLI recovery token (2026-04-04 12:00)',
  plaintext: 'abcdef1234567890',
 };
 const fakeMeta = {
  version: '1.0.0',
  installedAt: '',
  entryPoint: '',
  host: 'localhost',
  port: 14242,
 };
 describe('ensureSession', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    vi.spyOn(console, 'log').mockImplementation(() => {});
  });
  it('returns cookie from stored session when valid', async () => {
    mockLoadSession.mockReturnValueOnce({ cookie: fakeCookie, userId: 'u1', email: 'a@b.com' });
    mockValidateSession.mockResolvedValueOnce(true);
    const cookie = await ensureSession(baseUrl);
    expect(cookie).toBe(fakeCookie);
    expect(mockSignIn).not.toHaveBeenCalled();
  });
  it('prompts for credentials and signs in when stored session is invalid', async () => {
    mockLoadSession.mockReturnValueOnce({ cookie: 'old-cookie', userId: 'u1', email: 'a@b.com' });
    mockValidateSession.mockResolvedValueOnce(false);
    const newAuth = { cookie: fakeCookie, userId: 'u2', email: 'a@b.com' };
    mockSignIn.mockResolvedValueOnce(newAuth);
    const cookie = await ensureSession(baseUrl);
    expect(cookie).toBe(fakeCookie);
    expect(mockSaveSession).toHaveBeenCalledWith(baseUrl, newAuth);
  });
  it('prompts for credentials when no session exists', async () => {
    mockLoadSession.mockReturnValueOnce(null);
    const newAuth = { cookie: fakeCookie, userId: 'u2', email: 'a@b.com' };
    mockSignIn.mockResolvedValueOnce(newAuth);
    const cookie = await ensureSession(baseUrl);
    expect(cookie).toBe(fakeCookie);
    expect(mockSignIn).toHaveBeenCalled();
  });
  it('exits non-zero when signIn fails', async () => {
    mockLoadSession.mockReturnValueOnce(null);
    mockSignIn.mockRejectedValueOnce(new Error('Sign-in failed (401): bad creds'));
    const processExitSpy = vi
      .spyOn(process, 'exit')
      .mockImplementation((_code?: number | string | null | undefined) => {
        throw new Error(`process.exit(${String(_code)})`);
      });
    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    await expect(ensureSession(baseUrl)).rejects.toThrow('process.exit(2)');
    expect(processExitSpy).toHaveBeenCalledWith(2);
    processExitSpy.mockRestore();
    consoleErrorSpy.mockRestore();
  });
 });
 describe('runRecoverToken', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    vi.spyOn(console, 'log').mockImplementation(() => {});
    vi.spyOn(console, 'error').mockImplementation(() => {});
  });
  it('prompts for login, mints a token, and persists it when no session exists', async () => {
    mockLoadSession.mockReturnValueOnce(null);
    const newAuth = { cookie: fakeCookie, userId: 'u2', email: 'admin@test.com' };
    mockSignIn.mockResolvedValueOnce(newAuth);
    mockReadMeta.mockReturnValue(fakeMeta);
    mockFetch.mockResolvedValueOnce({
      ok: true,
      status: 200,
      json: async () => fakeToken,
    });
    await runRecoverToken();
    expect(mockSignIn).toHaveBeenCalled();
    expect(mockFetch).toHaveBeenCalledWith(
      `${baseUrl}/api/admin/tokens`,
      expect.objectContaining({ method: 'POST' }),
    );
    expect(mockWriteMeta).toHaveBeenCalledWith(
      expect.objectContaining({ adminToken: fakeToken.plaintext }),
    );
  });
  it('skips login when a valid session exists and mints a recovery token', async () => {
    mockLoadSession.mockReturnValueOnce({ cookie: fakeCookie, userId: 'u1', email: 'a@b.com' });
    mockValidateSession.mockResolvedValueOnce(true);
    mockReadMeta.mockReturnValue(fakeMeta);
    mockFetch.mockResolvedValueOnce({
      ok: true,
      status: 200,
      json: async () => fakeToken,
    });
    await runRecoverToken();
    expect(mockSignIn).not.toHaveBeenCalled();
    expect(mockWriteMeta).toHaveBeenCalledWith(
      expect.objectContaining({ adminToken: fakeToken.plaintext }),
    );
  });
  it('uses label containing "recovery token"', async () => {
    mockLoadSession.mockReturnValueOnce({ cookie: fakeCookie, userId: 'u1', email: 'a@b.com' });
    mockValidateSession.mockResolvedValueOnce(true);
    mockReadMeta.mockReturnValue(fakeMeta);
    mockFetch.mockResolvedValueOnce({
      ok: true,
      status: 200,
      json: async () => fakeToken,
    });
    await runRecoverToken();
    const call = mockFetch.mock.calls[0] as [string, RequestInit];
    const body = JSON.parse(call[1].body as string) as { label: string };
    expect(body.label).toMatch(/CLI recovery token/);
  });
 });
--- a/packages/mosaic/src/commands/gateway/rotate-token.spec.ts
+++ b/packages/mosaic/src/commands/gateway/rotate-token.spec.ts
@@ -1,205 +0,0 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 // ─── Mocks ──────────────────────────────────────────────────────────────────
 vi.mock('../../auth.js', () => ({
  loadSession: vi.fn(),
  validateSession: vi.fn(),
  signIn: vi.fn(),
  saveSession: vi.fn(),
 }));
 vi.mock('./daemon.js', () => ({
  readMeta: vi.fn(),
  writeMeta: vi.fn(),
 }));
 vi.mock('./login.js', () => ({
  getGatewayUrl: vi.fn().mockReturnValue('http://localhost:14242'),
 }));
 // Mock global fetch
 const mockFetch = vi.fn();
 vi.stubGlobal('fetch', mockFetch);
 import { runRotateToken, mintAdminToken, persistToken } from './token-ops.js';
 import { loadSession, validateSession } from '../../auth.js';
 import { readMeta, writeMeta } from './daemon.js';
 const mockLoadSession = vi.mocked(loadSession);
 const mockValidateSession = vi.mocked(validateSession);
 const mockReadMeta = vi.mocked(readMeta);
 const mockWriteMeta = vi.mocked(writeMeta);
 const baseUrl = 'http://localhost:14242';
 const fakeCookie = 'better-auth.session_token=sess123';
 const fakeToken = {
  id: 'tok-1',
  label: 'CLI rotated token (2026-04-04)',
  plaintext: 'abcdef1234567890',
 };
 const fakeMeta = {
  version: '1.0.0',
  installedAt: '',
  entryPoint: '',
  host: 'localhost',
  port: 14242,
 };
 describe('mintAdminToken', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });
  it('calls the admin tokens endpoint with the session cookie and returns the token', async () => {
    mockFetch.mockResolvedValueOnce({
      ok: true,
      status: 200,
      json: async () => fakeToken,
    });
    const result = await mintAdminToken(baseUrl, fakeCookie, fakeToken.label);
    expect(mockFetch).toHaveBeenCalledWith(
      `${baseUrl}/api/admin/tokens`,
      expect.objectContaining({
        method: 'POST',
        headers: expect.objectContaining({ Cookie: fakeCookie }),
      }),
    );
    expect(result).toEqual(fakeToken);
  });
  it('exits 2 on 401 from the server', async () => {
    mockFetch.mockResolvedValueOnce({ ok: false, status: 401, text: async () => 'Unauthorized' });
    const processExitSpy = vi
      .spyOn(process, 'exit')
      .mockImplementation((_code?: number | string | null | undefined) => {
        throw new Error(`process.exit(${String(_code)})`);
      });
    await expect(mintAdminToken(baseUrl, fakeCookie, 'label')).rejects.toThrow('process.exit(2)');
    expect(processExitSpy).toHaveBeenCalledWith(2);
    processExitSpy.mockRestore();
  });
  it('exits 2 on 403 from the server', async () => {
    mockFetch.mockResolvedValueOnce({ ok: false, status: 403, text: async () => 'Forbidden' });
    const processExitSpy = vi
      .spyOn(process, 'exit')
      .mockImplementation((_code?: number | string | null | undefined) => {
        throw new Error(`process.exit(${String(_code)})`);
      });
    await expect(mintAdminToken(baseUrl, fakeCookie, 'label')).rejects.toThrow('process.exit(2)');
    expect(processExitSpy).toHaveBeenCalledWith(2);
    processExitSpy.mockRestore();
  });
  it('exits 3 on other non-ok status', async () => {
    mockFetch.mockResolvedValueOnce({ ok: false, status: 500, text: async () => 'Internal Error' });
    const processExitSpy = vi
      .spyOn(process, 'exit')
      .mockImplementation((_code?: number | string | null | undefined) => {
        throw new Error(`process.exit(${String(_code)})`);
      });
    await expect(mintAdminToken(baseUrl, fakeCookie, 'label')).rejects.toThrow('process.exit(3)');
    expect(processExitSpy).toHaveBeenCalledWith(3);
    processExitSpy.mockRestore();
  });
  it('exits 1 on network error', async () => {
    mockFetch.mockRejectedValueOnce(new Error('connection refused'));
    const processExitSpy = vi
      .spyOn(process, 'exit')
      .mockImplementation((_code?: number | string | null | undefined) => {
        throw new Error(`process.exit(${String(_code)})`);
      });
    await expect(mintAdminToken(baseUrl, fakeCookie, 'label')).rejects.toThrow('process.exit(1)');
    expect(processExitSpy).toHaveBeenCalledWith(1);
    processExitSpy.mockRestore();
  });
 });
 describe('persistToken', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });
  it('writes the new token to meta.json', () => {
    mockReadMeta.mockReturnValueOnce(fakeMeta);
    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
    persistToken(baseUrl, fakeToken);
    expect(mockWriteMeta).toHaveBeenCalledWith(
      expect.objectContaining({ adminToken: fakeToken.plaintext }),
    );
    consoleSpy.mockRestore();
  });
  it('prints a masked preview of the token', () => {
    mockReadMeta.mockReturnValueOnce(fakeMeta);
    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
    persistToken(baseUrl, fakeToken);
    const allOutput = consoleSpy.mock.calls.map((c) => c.join(' ')).join('\n');
    expect(allOutput).toContain('abcdef12...');
    consoleSpy.mockRestore();
  });
 });
 describe('runRotateToken', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    vi.spyOn(console, 'error').mockImplementation(() => {});
    vi.spyOn(console, 'log').mockImplementation(() => {});
  });
  it('exits 2 when there is no stored session', async () => {
    mockLoadSession.mockReturnValueOnce(null);
    const processExitSpy = vi
      .spyOn(process, 'exit')
      .mockImplementation((_code?: number | string | null | undefined) => {
        throw new Error(`process.exit(${String(_code)})`);
      });
    await expect(runRotateToken()).rejects.toThrow('process.exit(2)');
    expect(processExitSpy).toHaveBeenCalledWith(2);
    processExitSpy.mockRestore();
  });
  it('exits 2 when session is invalid', async () => {
    mockLoadSession.mockReturnValueOnce({ cookie: fakeCookie, userId: 'u1', email: 'a@b.com' });
    mockValidateSession.mockResolvedValueOnce(false);
    const processExitSpy = vi
      .spyOn(process, 'exit')
      .mockImplementation((_code?: number | string | null | undefined) => {
        throw new Error(`process.exit(${String(_code)})`);
      });
    await expect(runRotateToken()).rejects.toThrow('process.exit(2)');
    expect(processExitSpy).toHaveBeenCalledWith(2);
    processExitSpy.mockRestore();
  });
  it('mints and persists a new token when session is valid', async () => {
    mockLoadSession.mockReturnValueOnce({ cookie: fakeCookie, userId: 'u1', email: 'a@b.com' });
    mockValidateSession.mockResolvedValueOnce(true);
    mockReadMeta.mockReturnValue(fakeMeta);
    mockFetch.mockResolvedValueOnce({
      ok: true,
      status: 200,
      json: async () => fakeToken,
    });
    await runRotateToken();
    expect(mockWriteMeta).toHaveBeenCalledWith(
      expect.objectContaining({ adminToken: fakeToken.plaintext }),
    );
  });
 });
--- a/packages/mosaic/src/commands/gateway/token-ops.ts
+++ b/packages/mosaic/src/commands/gateway/token-ops.ts
@@ -1,149 +0,0 @@
 import { createInterface } from 'node:readline';
 import { loadSession, validateSession, signIn, saveSession } from '../../auth.js';
 import { readMeta, writeMeta } from './daemon.js';
 import { getGatewayUrl } from './login.js';
 interface MintedToken {
  id: string;
  label: string;
  plaintext: string;
 }
 /**
 * Call POST /api/admin/tokens with the session cookie and return the minted token.
 * Exits the process on network or auth errors.
 */
 export async function mintAdminToken(
  gatewayUrl: string,
  cookie: string,
  label: string,
 ): Promise<MintedToken> {
  let res: Response;
  try {
    res = await fetch(`${gatewayUrl}/api/admin/tokens`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Cookie: cookie,
        Origin: gatewayUrl,
      },
      body: JSON.stringify({ label, scope: 'admin' }),
    });
  } catch (err) {
    console.error(
      `Could not reach gateway at ${gatewayUrl}: ${err instanceof Error ? err.message : String(err)}`,
    );
    process.exit(1);
  }
  if (res.status === 401 || res.status === 403) {
    console.error(
      `Session rejected by the gateway (${res.status.toString()}) — your session may be expired.`,
    );
    console.error('Run: mosaic gateway login');
    process.exit(2);
  }
  if (!res.ok) {
    const body = await res.text().catch(() => '');
    console.error(
      `Gateway rejected token creation (${res.status.toString()}): ${body.slice(0, 200)}`,
    );
    process.exit(3);
  }
  const data = (await res.json()) as { id: string; label: string; plaintext: string };
  return { id: data.id, label: data.label, plaintext: data.plaintext };
 }
 /**
 * Persist the new token into meta.json and print the confirmation banner.
 */
 export function persistToken(gatewayUrl: string, minted: MintedToken): void {
  const meta = readMeta() ?? {
    version: 'unknown',
    installedAt: new Date().toISOString(),
    entryPoint: '',
    host: new URL(gatewayUrl).hostname,
    port: parseInt(new URL(gatewayUrl).port || '14242', 10),
  };
  writeMeta({ ...meta, adminToken: minted.plaintext });
  const preview = `${minted.plaintext.slice(0, 8)}...`;
  console.log();
  console.log(`Token minted:  ${minted.label}`);
  console.log(`Preview:       ${preview}`);
  console.log('Token saved to meta.json. Use it with admin endpoints.');
 }
 /**
 * Require a valid session for the given gateway URL.
 * Returns the session cookie or exits if not authenticated.
 */
 export async function requireSession(gatewayUrl: string): Promise<string> {
  const session = loadSession(gatewayUrl);
  if (session) {
    const valid = await validateSession(gatewayUrl, session.cookie);
    if (valid) return session.cookie;
  }
  console.error('Not signed in or session expired.');
  console.error('Run: mosaic gateway login');
  process.exit(2);
 }
 /**
 * Ensure a valid session for the gateway, prompting for credentials if needed.
 * On sign-in failure, prints the error and exits non-zero.
 * Returns the session cookie.
 */
 export async function ensureSession(gatewayUrl: string): Promise<string> {
  // Try the stored session first
  const session = loadSession(gatewayUrl);
  if (session) {
    const valid = await validateSession(gatewayUrl, session.cookie);
    if (valid) return session.cookie;
    console.log('Stored session is invalid or expired. Please sign in again.');
  } else {
    console.log(`No session found for ${gatewayUrl}. Please sign in.`);
  }
  // Prompt for credentials
  const rl = createInterface({ input: process.stdin, output: process.stdout });
  const ask = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
  const email = (await ask('Email: ')).trim();
  const password = (await ask('Password: ')).trim();
  rl.close();
  const auth = await signIn(gatewayUrl, email, password).catch((err: unknown) => {
    console.error(err instanceof Error ? err.message : String(err));
    process.exit(2);
  });
  saveSession(gatewayUrl, auth);
  console.log(`Signed in as ${auth.email}`);
  return auth.cookie;
 }
 /**
 * `mosaic gateway config rotate-token` — requires an existing valid session.
 */
 export async function runRotateToken(gatewayUrl?: string): Promise<void> {
  const url = getGatewayUrl(gatewayUrl);
  const cookie = await requireSession(url);
  const label = `CLI rotated token (${new Date().toISOString().slice(0, 10)})`;
  const minted = await mintAdminToken(url, cookie, label);
  persistToken(url, minted);
 }
 /**
 * `mosaic gateway config recover-token` — prompts for login if no session exists.
 */
 export async function runRecoverToken(gatewayUrl?: string): Promise<void> {
  const url = getGatewayUrl(gatewayUrl);
  const cookie = await ensureSession(url);
  const label = `CLI recovery token (${new Date().toISOString().slice(0, 16).replace('T', ' ')})`;
  const minted = await mintAdminToken(url, cookie, label);
  persistToken(url, minted);
 }
--- a/packages/queue/package.json
+++ b/packages/queue/package.json
@@ -22,7 +22,6 @@
  },
  "dependencies": {
    "@mosaicstack/types": "workspace:*",
    "commander": "^13.0.0",
    "ioredis": "^5.10.0"
  },
  "devDependencies": {
--- a/packages/queue/src/cli.spec.ts
+++ b/packages/queue/src/cli.spec.ts
@@ -1,62 +0,0 @@
 import { describe, it, expect } from 'vitest';
 import { Command } from 'commander';
 import { registerQueueCommand } from './cli.js';
 describe('registerQueueCommand', () => {
  function buildProgram(): Command {
    const program = new Command('mosaic');
    registerQueueCommand(program);
    return program;
  }
  it('registers a "queue" subcommand', () => {
    const program = buildProgram();
    const queueCmd = program.commands.find((c) => c.name() === 'queue');
    expect(queueCmd).toBeDefined();
  });
  it('queue has list, stats, pause, resume, jobs, drain subcommands', () => {
    const program = buildProgram();
    const queueCmd = program.commands.find((c) => c.name() === 'queue');
    expect(queueCmd).toBeDefined();
    const names = queueCmd!.commands.map((c) => c.name());
    expect(names).toContain('list');
    expect(names).toContain('stats');
    expect(names).toContain('pause');
    expect(names).toContain('resume');
    expect(names).toContain('jobs');
    expect(names).toContain('drain');
  });
  it('jobs subcommand has a "tail" subcommand', () => {
    const program = buildProgram();
    const queueCmd = program.commands.find((c) => c.name() === 'queue');
    const jobsCmd = queueCmd!.commands.find((c) => c.name() === 'jobs');
    expect(jobsCmd).toBeDefined();
    const tailCmd = jobsCmd!.commands.find((c) => c.name() === 'tail');
    expect(tailCmd).toBeDefined();
  });
  it('drain has a --yes option', () => {
    const program = buildProgram();
    const queueCmd = program.commands.find((c) => c.name() === 'queue');
    const drainCmd = queueCmd!.commands.find((c) => c.name() === 'drain');
    expect(drainCmd).toBeDefined();
    const optionNames = drainCmd!.options.map((o) => o.long);
    expect(optionNames).toContain('--yes');
  });
  it('stats accepts an optional [name] argument', () => {
    const program = buildProgram();
    const queueCmd = program.commands.find((c) => c.name() === 'queue');
    const statsCmd = queueCmd!.commands.find((c) => c.name() === 'stats');
    expect(statsCmd).toBeDefined();
    // Should not throw when called without argument
    const args = statsCmd!.registeredArguments;
    expect(args.length).toBe(1);
    expect(args[0]!.required).toBe(false);
  });
 });
--- a/packages/queue/src/cli.ts
+++ b/packages/queue/src/cli.ts
@@ -1,248 +0,0 @@
 import type { Command } from 'commander';
 import { createLocalAdapter } from './adapters/local.js';
 import type { QueueConfig } from './types.js';
 /** Resolve adapter type from env; defaults to 'local'. */
 function resolveAdapterType(): 'bullmq' | 'local' {
  const t = process.env['QUEUE_ADAPTER'] ?? 'local';
  return t === 'bullmq' ? 'bullmq' : 'local';
 }
 function resolveConfig(): QueueConfig {
  const type = resolveAdapterType();
  if (type === 'bullmq') {
    return { type: 'bullmq', url: process.env['VALKEY_URL'] };
  }
  return { type: 'local', dataDir: process.env['QUEUE_DATA_DIR'] };
 }
 const BULLMQ_ONLY_MSG =
  'not supported by local adapter — use the bullmq tier for this (set QUEUE_ADAPTER=bullmq)';
 /**
 * Register queue subcommands on an existing Commander program.
 * Follows the same pattern as registerQualityRails in @mosaicstack/quality-rails.
 */
 export function registerQueueCommand(parent: Command): void {
  buildQueueCommand(parent.command('queue').description('Manage Mosaic job queues'));
 }
 function buildQueueCommand(queue: Command): void {
  // ─── list ──────────────────────────────────────────────────────────────
  queue
    .command('list')
    .description('List all queues known to the configured adapter')
    .action(async () => {
      const config = resolveConfig();
      if (config.type === 'local') {
        const adapter = createLocalAdapter(config);
        // Local adapter tracks queues in its internal Map; we expose them by
        // listing JSON files in the data dir.
        const { readdirSync } = await import('node:fs');
        const { existsSync } = await import('node:fs');
        const dataDir = config.dataDir ?? '.mosaic/queue';
        if (!existsSync(dataDir)) {
          console.log('No queues found (data dir does not exist yet).');
          await adapter.close();
          return;
        }
        const files = readdirSync(dataDir).filter((f: string) => f.endsWith('.json'));
        if (files.length === 0) {
          console.log('No queues found.');
        } else {
          console.log('Queues (local adapter):');
          for (const f of files) {
            console.log(`  - ${f.slice(0, -5)}`);
          }
        }
        await adapter.close();
        return;
      }
      // bullmq — not enough info to enumerate queues without a BullMQ Board
      console.log(BULLMQ_ONLY_MSG);
      process.exit(0);
    });
  // ─── stats ─────────────────────────────────────────────────────────────
  queue
    .command('stats [name]')
    .description('Show stats for a queue (or all queues)')
    .action(async (name?: string) => {
      const config = resolveConfig();
      if (config.type === 'local') {
        const adapter = createLocalAdapter(config);
        const { readdirSync } = await import('node:fs');
        const { existsSync } = await import('node:fs');
        const dataDir = config.dataDir ?? '.mosaic/queue';
        let names: string[] = [];
        if (name) {
          names = [name];
        } else {
          if (existsSync(dataDir)) {
            names = readdirSync(dataDir)
              .filter((f: string) => f.endsWith('.json'))
              .map((f: string) => f.slice(0, -5));
          }
        }
        if (names.length === 0) {
          console.log('No queues found.');
          await adapter.close();
          return;
        }
        for (const queueName of names) {
          const len = await adapter.length(queueName);
          console.log(`Queue: ${queueName}`);
          console.log(`  waiting:   ${len}`);
          console.log(`  active:    0 (local adapter — no active tracking)`);
          console.log(`  completed: 0 (local adapter — no completed tracking)`);
          console.log(`  failed:    0 (local adapter — no failed tracking)`);
          console.log(`  delayed:   0 (local adapter — no delayed tracking)`);
        }
        await adapter.close();
        return;
      }
      // bullmq
      console.log(BULLMQ_ONLY_MSG);
      process.exit(0);
    });
  // ─── pause ─────────────────────────────────────────────────────────────
  queue
    .command('pause <name>')
    .description('Pause job processing for a queue')
    .action(async (_name: string) => {
      const config = resolveConfig();
      if (config.type === 'local') {
        console.log(BULLMQ_ONLY_MSG);
        process.exit(0);
        return;
      }
      console.log(BULLMQ_ONLY_MSG);
      process.exit(0);
    });
  // ─── resume ────────────────────────────────────────────────────────────
  queue
    .command('resume <name>')
    .description('Resume job processing for a queue')
    .action(async (_name: string) => {
      const config = resolveConfig();
      if (config.type === 'local') {
        console.log(BULLMQ_ONLY_MSG);
        process.exit(0);
        return;
      }
      console.log(BULLMQ_ONLY_MSG);
      process.exit(0);
    });
  // ─── jobs tail ─────────────────────────────────────────────────────────
  const jobs = queue.command('jobs').description('Job-level operations');
  jobs
    .command('tail [name]')
    .description('Stream new jobs as they arrive (poll-based)')
    .option('--interval <ms>', 'Poll interval in ms', '2000')
    .action(async (name: string | undefined, opts: { interval: string }) => {
      const config = resolveConfig();
      const pollMs = parseInt(opts.interval, 10);
      if (config.type === 'local') {
        const adapter = createLocalAdapter(config);
        const { existsSync, readdirSync } = await import('node:fs');
        const dataDir = config.dataDir ?? '.mosaic/queue';
        let names: string[] = [];
        if (name) {
          names = [name];
        } else {
          if (existsSync(dataDir)) {
            names = readdirSync(dataDir)
              .filter((f: string) => f.endsWith('.json'))
              .map((f: string) => f.slice(0, -5));
          }
        }
        if (names.length === 0) {
          console.log('No queues to tail.');
          await adapter.close();
          return;
        }
        console.log(`Tailing queues: ${names.join(', ')} (Ctrl-C to stop)`);
        const lastLen = new Map<string, number>();
        for (const qn of names) {
          lastLen.set(qn, await adapter.length(qn));
        }
        const timer = setInterval(async () => {
          for (const qn of names) {
            const len = await adapter.length(qn);
            const prev = lastLen.get(qn) ?? 0;
            if (len > prev) {
              console.log(
                `[${new Date().toISOString()}] ${qn}: ${len - prev} new job(s) (total: ${len})`,
              );
            }
            lastLen.set(qn, len);
          }
        }, pollMs);
        process.on('SIGINT', async () => {
          clearInterval(timer);
          await adapter.close();
          process.exit(0);
        });
        return;
      }
      // bullmq — use subscribe on the channel
      console.log(BULLMQ_ONLY_MSG);
      process.exit(0);
    });
  // ─── drain ─────────────────────────────────────────────────────────────
  queue
    .command('drain <name>')
    .description('Drain all pending jobs from a queue')
    .option('--yes', 'Skip confirmation prompt')
    .action(async (name: string, opts: { yes?: boolean }) => {
      if (!opts.yes) {
        console.error(
          `WARNING: This will remove all pending jobs from queue "${name}". Re-run with --yes to confirm.`,
        );
        process.exit(1);
        return;
      }
      const config = resolveConfig();
      if (config.type === 'local') {
        const adapter = createLocalAdapter(config);
        let removed = 0;
        while ((await adapter.length(name)) > 0) {
          await adapter.dequeue(name);
          removed++;
        }
        console.log(`Drained ${removed} job(s) from queue "${name}".`);
        await adapter.close();
        return;
      }
      console.log(BULLMQ_ONLY_MSG);
      process.exit(0);
    });
 }
--- a/packages/queue/src/index.ts
+++ b/packages/queue/src/index.ts
@@ -11,7 +11,6 @@ export { type QueueAdapter, type QueueConfig as QueueAdapterConfig } from './typ
 export { createQueueAdapter, registerQueueAdapter } from './factory.js';
 export { createBullMQAdapter } from './adapters/bullmq.js';
 export { createLocalAdapter } from './adapters/local.js';
 export { registerQueueCommand } from './cli.js';
 import { registerQueueAdapter } from './factory.js';
 import { createBullMQAdapter } from './adapters/bullmq.js';
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -385,9 +385,6 @@ importers:
      '@mosaicstack/macp':
        specifier: workspace:*
        version: link:../macp
      commander:
        specifier: ^13.0.0
        version: 13.1.0
    devDependencies:
      '@types/node':
        specifier: ^22.0.0
@@ -444,9 +441,6 @@ importers:
      '@mosaicstack/types':
        specifier: workspace:*
        version: link:../types
      commander:
        specifier: ^13.0.0
        version: 13.1.0
      drizzle-orm:
        specifier: ^0.45.1
        version: 0.45.1(@electric-sql/pglite@0.2.17)(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.15.6)(better-sqlite3@12.8.0)(kysely@0.28.11)(postgres@3.4.8)
@@ -475,18 +469,12 @@ importers:
      '@mosaicstack/macp':
        specifier: workspace:*
        version: link:../macp
      '@mosaicstack/memory':
        specifier: workspace:*
        version: link:../memory
      '@mosaicstack/prdy':
        specifier: workspace:*
        version: link:../prdy
      '@mosaicstack/quality-rails':
        specifier: workspace:*
        version: link:../quality-rails
      '@mosaicstack/queue':
        specifier: workspace:*
        version: link:../queue
      '@mosaicstack/types':
        specifier: workspace:*
        version: link:../types
@@ -583,9 +571,6 @@ importers:
      '@mosaicstack/types':
        specifier: workspace:*
        version: link:../types
      commander:
        specifier: ^13.0.0
        version: 13.1.0
      ioredis:
        specifier: ^5.10.0
        version: 5.10.0
@@ -655,10 +640,10 @@ importers:
    dependencies:
      '@mariozechner/pi-agent-core':
        specifier: ^0.63.1
-        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
+        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
      '@mariozechner/pi-ai':
        specifier: ^0.63.1
-        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
+        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
      '@sinclair/typebox':
        specifier: ^0.34.41
        version: 0.34.48
@@ -7033,12 +7018,6 @@ snapshots:
      '@jridgewell/gen-mapping': 0.3.13
      '@jridgewell/trace-mapping': 0.3.31
  '@anthropic-ai/sdk@0.73.0(zod@3.25.76)':
    dependencies:
      json-schema-to-ts: 3.1.1
    optionalDependencies:
      zod: 3.25.76
  '@anthropic-ai/sdk@0.73.0(zod@4.3.6)':
    dependencies:
      json-schema-to-ts: 3.1.1
@@ -8380,18 +8359,6 @@ snapshots:
      - ws
      - zod
  '@mariozechner/pi-agent-core@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)':
    dependencies:
      '@mariozechner/pi-ai': 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
    transitivePeerDependencies:
      - '@modelcontextprotocol/sdk'
      - aws-crt
      - bufferutil
      - supports-color
      - utf-8-validate
      - ws
      - zod
  '@mariozechner/pi-agent-core@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)':
    dependencies:
      '@mariozechner/pi-ai': 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
@@ -8440,30 +8407,6 @@ snapshots:
      - ws
      - zod
  '@mariozechner/pi-ai@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)':
    dependencies:
      '@anthropic-ai/sdk': 0.73.0(zod@3.25.76)
      '@aws-sdk/client-bedrock-runtime': 3.1008.0
      '@google/genai': 1.45.0(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))
      '@mistralai/mistralai': 1.14.1
      '@sinclair/typebox': 0.34.48
      ajv: 8.18.0
      ajv-formats: 3.0.1(ajv@8.18.0)
      chalk: 5.6.2
      openai: 6.26.0(ws@8.20.0)(zod@3.25.76)
      partial-json: 0.1.7
      proxy-agent: 6.5.0
      undici: 7.24.3
      zod-to-json-schema: 3.25.1(zod@3.25.76)
    transitivePeerDependencies:
      - '@modelcontextprotocol/sdk'
      - aws-crt
      - bufferutil
      - supports-color
      - utf-8-validate
      - ws
      - zod
  '@mariozechner/pi-ai@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)':
    dependencies:
      '@anthropic-ai/sdk': 0.73.0(zod@4.3.6)
@@ -12839,11 +12782,6 @@ snapshots:
    dependencies:
      mimic-function: 5.0.1
  openai@6.26.0(ws@8.20.0)(zod@3.25.76):
    optionalDependencies:
      ws: 8.20.0
      zod: 3.25.76
  openai@6.26.0(ws@8.20.0)(zod@4.3.6):
    optionalDependencies:
      ws: 8.20.0