feat(mosaic): gateway token recovery via BetterAuth cookie (CU-03-03..07)

Add mosaic gateway login subcommand with meta.json URL default, config rotate-token and recover-token subcommands for admin token minting via BetterAuth session cookie, fix the bootstrapFirstUser dead-end when admin exists but no token is on file, and add Vitest tests for all new flows. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-05 00:23:08 -05:00
22 changed files with 721 additions and 1119 deletions
--- a/packages/macp/package.json
+++ b/packages/macp/package.json
@@ -21,9 +21,6 @@
    "typecheck": "tsc --noEmit",
    "test": "vitest run --passWithNoTests"
  },
  "dependencies": {
    "commander": "^13.0.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "@vitest/coverage-v8": "^2.0.0",
--- a/packages/macp/src/cli.spec.ts
+++ b/packages/macp/src/cli.spec.ts
@@ -1,77 +0,0 @@
 import { describe, it, expect } from 'vitest';
 import { Command } from 'commander';
 import { registerMacpCommand } from './cli.js';
 describe('registerMacpCommand', () => {
  function buildProgram(): Command {
    const program = new Command();
    program.exitOverride(); // prevent process.exit in tests
    registerMacpCommand(program);
    return program;
  }
  it('registers a "macp" command on the parent', () => {
    const program = buildProgram();
    const macpCmd = program.commands.find((c) => c.name() === 'macp');
    expect(macpCmd).toBeDefined();
  });
  it('registers "macp tasks" subcommand group', () => {
    const program = buildProgram();
    const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
    const tasksCmd = macpCmd.commands.find((c) => c.name() === 'tasks');
    expect(tasksCmd).toBeDefined();
  });
  it('registers "macp tasks list" subcommand with --status and --type flags', () => {
    const program = buildProgram();
    const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
    const tasksCmd = macpCmd.commands.find((c) => c.name() === 'tasks')!;
    const listCmd = tasksCmd.commands.find((c) => c.name() === 'list');
    expect(listCmd).toBeDefined();
    const optionNames = listCmd!.options.map((o) => o.long);
    expect(optionNames).toContain('--status');
    expect(optionNames).toContain('--type');
  });
  it('registers "macp submit" subcommand', () => {
    const program = buildProgram();
    const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
    const submitCmd = macpCmd.commands.find((c) => c.name() === 'submit');
    expect(submitCmd).toBeDefined();
  });
  it('registers "macp gate" subcommand with --fail-on flag', () => {
    const program = buildProgram();
    const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
    const gateCmd = macpCmd.commands.find((c) => c.name() === 'gate');
    expect(gateCmd).toBeDefined();
    const optionNames = gateCmd!.options.map((o) => o.long);
    expect(optionNames).toContain('--fail-on');
  });
  it('registers "macp events" subcommand group', () => {
    const program = buildProgram();
    const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
    const eventsCmd = macpCmd.commands.find((c) => c.name() === 'events');
    expect(eventsCmd).toBeDefined();
  });
  it('registers "macp events tail" subcommand', () => {
    const program = buildProgram();
    const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
    const eventsCmd = macpCmd.commands.find((c) => c.name() === 'events')!;
    const tailCmd = eventsCmd.commands.find((c) => c.name() === 'tail');
    expect(tailCmd).toBeDefined();
  });
  it('has all required top-level subcommands', () => {
    const program = buildProgram();
    const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
    const topLevel = macpCmd.commands.map((c) => c.name());
    expect(topLevel).toContain('tasks');
    expect(topLevel).toContain('submit');
    expect(topLevel).toContain('gate');
    expect(topLevel).toContain('events');
  });
 });
--- a/packages/macp/src/cli.ts
+++ b/packages/macp/src/cli.ts
@@ -1,92 +0,0 @@
 import type { Command } from 'commander';
 /**
 * Register macp subcommands on an existing Commander program.
 * This avoids cross-package Commander version mismatches by using the
 * caller's Command instance directly.
 */
 export function registerMacpCommand(parent: Command): void {
  const macp = parent.command('macp').description('MACP task and gate management');
  // ─── tasks ───────────────────────────────────────────────────────────────
  const tasks = macp.command('tasks').description('Manage MACP tasks');
  tasks
    .command('list')
    .description('List MACP tasks')
    .option(
      '--status <status>',
      'Filter by task status (pending|running|gated|completed|failed|escalated)',
    )
    .option(
      '--type <type>',
      'Filter by task type (coding|deploy|research|review|documentation|infrastructure)',
    )
    .action((opts: { status?: string; type?: string }) => {
      // not yet wired — task persistence layer is not present in @mosaicstack/macp
      console.log('[macp] tasks list: not yet wired — use macp package programmatically');
      if (opts.status) {
        console.log(`  status filter: ${opts.status}`);
      }
      if (opts.type) {
        console.log(`  type filter: ${opts.type}`);
      }
      process.exitCode = 0;
    });
  // ─── submit ──────────────────────────────────────────────────────────────
  macp
    .command('submit <path>')
    .description('Submit a task from a JSON/YAML spec file')
    .action((specPath: string) => {
      // not yet wired — task submission requires a running MACP server
      console.log('[macp] submit: not yet wired — use macp package programmatically');
      console.log(`  spec path: ${specPath}`);
      console.log('  task id:   (unavailable — no MACP server connected)');
      console.log('  status:    (unavailable — no MACP server connected)');
      process.exitCode = 0;
    });
  // ─── gate ────────────────────────────────────────────────────────────────
  macp
    .command('gate <spec>')
    .description('Run a gate from a spec string or file path (wraps runGate/runGates)')
    .option('--fail-on <mode>', 'Gate fail-on mode: ai|fail|both|none', 'fail')
    .option('--cwd <path>', 'Working directory for gate execution', process.cwd())
    .option('--log <path>', 'Path to write gate log output', '/tmp/macp-gate.log')
    .option('--timeout <seconds>', 'Gate timeout in seconds', '60')
    .action((spec: string, opts: { failOn: string; cwd: string; log: string; timeout: string }) => {
      // not yet wired — gate execution requires a task context and event sink
      console.log('[macp] gate: not yet wired — use macp package programmatically');
      console.log(`  spec:     ${spec}`);
      console.log(`  fail-on:  ${opts.failOn}`);
      console.log(`  cwd:      ${opts.cwd}`);
      console.log(`  log:      ${opts.log}`);
      console.log(`  timeout:  ${opts.timeout}s`);
      process.exitCode = 0;
    });
  // ─── events ──────────────────────────────────────────────────────────────
  const events = macp.command('events').description('Stream MACP events');
  events
    .command('tail')
    .description('Tail MACP events from the event log (wraps event emitter)')
    .option('--file <path>', 'Path to the MACP events NDJSON file')
    .option('--follow', 'Follow the file for new events (like tail -f)')
    .action((opts: { file?: string; follow?: boolean }) => {
      // not yet wired — event streaming requires a live event source
      console.log('[macp] events tail: not yet wired — use macp package programmatically');
      if (opts.file) {
        console.log(`  file:   ${opts.file}`);
      }
      if (opts.follow) {
        console.log('  mode:   follow');
      }
      process.exitCode = 0;
    });
 }
--- a/packages/macp/src/index.ts
+++ b/packages/macp/src/index.ts
@@ -41,6 +41,3 @@ export type { NormalizedGate } from './gate-runner.js';
 // Event emitter
 export { nowISO, appendEvent, emitEvent } from './event-emitter.js';
 // CLI
 export { registerMacpCommand } from './cli.js';
--- a/packages/mosaic/package.json
+++ b/packages/mosaic/package.json
@@ -33,7 +33,6 @@
    "@mosaicstack/macp": "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,11 +3,8 @@
 import { createRequire } from 'module';
 import { Command } from 'commander';
 import { registerBrainCommand } from '@mosaicstack/brain';
 import { registerMacpCommand } from '@mosaicstack/macp';
 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';
@@ -333,10 +330,6 @@ registerGatewayCommand(program);
 registerAgentCommand(program);
 // ─── config ────────────────────────────────────────────────────────────
 registerConfigCommand(program);
 // ─── mission ───────────────────────────────────────────────────────────
 registerMissionCommand(program);
@@ -345,18 +338,10 @@ registerMissionCommand(program);
 registerBrainCommand(program);
 // ─── macp ────────────────────────────────────────────────────────────────
 registerMacpCommand(program);
 // ─── quality-rails ──────────────────────────────────────────────────────
 registerQualityRails(program);
 // ─── queue ───────────────────────────────────────────────────────────────
 registerQueueCommand(program);
 // ─── update ─────────────────────────────────────────────────────────────
 program
--- a/packages/mosaic/src/commands/config.spec.ts
+++ b/packages/mosaic/src/commands/config.spec.ts
@@ -1,289 +0,0 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { Command } from 'commander';
 import { registerConfigCommand } from './config.js';
 // ── helpers ──────────────────────────────────────────────────────────────────
 /** Build a fresh Command tree with the config command registered. */
 function buildProgram(): Command {
  const program = new Command();
  program.exitOverride(); // prevent process.exit during tests
  registerConfigCommand(program);
  return program;
 }
 /** Locate the 'config' command registered on the root program. */
 function getConfigCmd(program: Command): Command {
  const found = program.commands.find((c) => c.name() === 'config');
  if (!found) throw new Error('config command not found');
  return found;
 }
 // ── subcommand registration ───────────────────────────────────────────────────
 describe('registerConfigCommand', () => {
  it('registers a "config" command on the program', () => {
    const program = buildProgram();
    const names = program.commands.map((c) => c.name());
    expect(names).toContain('config');
  });
  it('registers exactly the five required subcommands', () => {
    const program = buildProgram();
    const config = getConfigCmd(program);
    const subs = config.commands.map((c) => c.name()).sort();
    expect(subs).toEqual(['edit', 'get', 'path', 'set', 'show']);
  });
 });
 // ── mock config service ───────────────────────────────────────────────────────
 const mockSoul = {
  agentName: 'TestBot',
  roleDescription: 'test role',
  communicationStyle: 'direct' as const,
 };
 const mockUser = { userName: 'Tester', pronouns: 'they/them', timezone: 'UTC' };
 const mockTools = { credentialsLocation: '/dev/null' };
 const mockSvc = {
  readSoul: vi.fn().mockResolvedValue(mockSoul),
  readUser: vi.fn().mockResolvedValue(mockUser),
  readTools: vi.fn().mockResolvedValue(mockTools),
  writeSoul: vi.fn().mockResolvedValue(undefined),
  writeUser: vi.fn().mockResolvedValue(undefined),
  writeTools: vi.fn().mockResolvedValue(undefined),
  syncFramework: vi.fn().mockResolvedValue(undefined),
  readAll: vi.fn().mockResolvedValue({ soul: mockSoul, user: mockUser, tools: mockTools }),
  getValue: vi.fn().mockResolvedValue('TestBot'),
  setValue: vi.fn().mockResolvedValue('OldBot'),
  getConfigPath: vi
    .fn()
    .mockImplementation((section?: string) =>
      section
        ? `/home/user/.config/mosaic/${section.toUpperCase()}.md`
        : '/home/user/.config/mosaic',
    ),
  isInitialized: vi.fn().mockReturnValue(true),
 };
 // Mock the config-service module so commands use our mock.
 vi.mock('../config/config-service.js', () => ({
  createConfigService: vi.fn(() => mockSvc),
 }));
 // Also mock child_process for the edit command.
 vi.mock('node:child_process', () => ({
  spawnSync: vi.fn().mockReturnValue({ status: 0, error: undefined }),
 }));
 // ── config show ───────────────────────────────────────────────────────────────
 describe('config show', () => {
  let consoleSpy: ReturnType<typeof vi.spyOn>;
  beforeEach(() => {
    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
    vi.clearAllMocks();
    mockSvc.isInitialized.mockReturnValue(true);
    mockSvc.readAll.mockResolvedValue({ soul: mockSoul, user: mockUser, tools: mockTools });
  });
  afterEach(() => {
    consoleSpy.mockRestore();
  });
  it('calls readAll() and prints a table by default', async () => {
    const program = buildProgram();
    await program.parseAsync(['node', 'mosaic', 'config', 'show']);
    expect(mockSvc.readAll).toHaveBeenCalledOnce();
    // Should have printed something
    expect(consoleSpy).toHaveBeenCalled();
  });
  it('prints JSON when --format json is passed', async () => {
    const program = buildProgram();
    await program.parseAsync(['node', 'mosaic', 'config', 'show', '--format', 'json']);
    expect(mockSvc.readAll).toHaveBeenCalledOnce();
    // Verify JSON was logged
    const allOutput = consoleSpy.mock.calls.map((c) => c[0] as string).join('\n');
    expect(allOutput).toContain('"agentName"');
  });
 });
 // ── config get ────────────────────────────────────────────────────────────────
 describe('config get', () => {
  let consoleSpy: ReturnType<typeof vi.spyOn>;
  beforeEach(() => {
    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
    vi.clearAllMocks();
    mockSvc.isInitialized.mockReturnValue(true);
    mockSvc.getValue.mockResolvedValue('TestBot');
  });
  afterEach(() => {
    consoleSpy.mockRestore();
  });
  it('delegates to getValue() with the provided key', async () => {
    const program = buildProgram();
    await program.parseAsync(['node', 'mosaic', 'config', 'get', 'soul.agentName']);
    expect(mockSvc.getValue).toHaveBeenCalledWith('soul.agentName');
  });
  it('prints the returned value', async () => {
    const program = buildProgram();
    await program.parseAsync(['node', 'mosaic', 'config', 'get', 'soul.agentName']);
    expect(consoleSpy).toHaveBeenCalledWith('TestBot');
  });
 });
 // ── config set ────────────────────────────────────────────────────────────────
 describe('config set', () => {
  let consoleSpy: ReturnType<typeof vi.spyOn>;
  beforeEach(() => {
    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
    vi.clearAllMocks();
    mockSvc.isInitialized.mockReturnValue(true);
    mockSvc.setValue.mockResolvedValue('OldBot');
  });
  afterEach(() => {
    consoleSpy.mockRestore();
  });
  it('delegates to setValue() with key and value', async () => {
    const program = buildProgram();
    await program.parseAsync(['node', 'mosaic', 'config', 'set', 'soul.agentName', 'NewBot']);
    expect(mockSvc.setValue).toHaveBeenCalledWith('soul.agentName', 'NewBot');
  });
  it('prints old and new values', async () => {
    const program = buildProgram();
    await program.parseAsync(['node', 'mosaic', 'config', 'set', 'soul.agentName', 'NewBot']);
    const output = consoleSpy.mock.calls.map((c) => c[0] as string).join('\n');
    expect(output).toContain('OldBot');
    expect(output).toContain('NewBot');
  });
 });
 // ── config path ───────────────────────────────────────────────────────────────
 describe('config path', () => {
  let consoleSpy: ReturnType<typeof vi.spyOn>;
  beforeEach(() => {
    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
    vi.clearAllMocks();
    mockSvc.getConfigPath.mockImplementation((section?: string) =>
      section
        ? `/home/user/.config/mosaic/${section.toUpperCase()}.md`
        : '/home/user/.config/mosaic',
    );
  });
  afterEach(() => {
    consoleSpy.mockRestore();
  });
  it('prints the mosaicHome directory when no section is specified', async () => {
    const program = buildProgram();
    await program.parseAsync(['node', 'mosaic', 'config', 'path']);
    expect(mockSvc.getConfigPath).toHaveBeenCalledWith();
    expect(consoleSpy).toHaveBeenCalledWith('/home/user/.config/mosaic');
  });
  it('prints the section file path when --section is given', async () => {
    const program = buildProgram();
    await program.parseAsync(['node', 'mosaic', 'config', 'path', '--section', 'soul']);
    expect(mockSvc.getConfigPath).toHaveBeenCalledWith('soul');
    expect(consoleSpy).toHaveBeenCalledWith('/home/user/.config/mosaic/SOUL.md');
  });
 });
 // ── config edit ───────────────────────────────────────────────────────────────
 describe('config edit', () => {
  let consoleSpy: ReturnType<typeof vi.spyOn>;
  let spawnSyncMock: ReturnType<typeof vi.fn>;
  beforeEach(async () => {
    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
    vi.clearAllMocks();
    mockSvc.isInitialized.mockReturnValue(true);
    mockSvc.readAll.mockResolvedValue({ soul: mockSoul, user: mockUser, tools: mockTools });
    mockSvc.getConfigPath.mockImplementation((section?: string) =>
      section
        ? `/home/user/.config/mosaic/${section.toUpperCase()}.md`
        : '/home/user/.config/mosaic',
    );
    // Re-import to get the mock reference
    const cp = await import('node:child_process');
    spawnSyncMock = cp.spawnSync as ReturnType<typeof vi.fn>;
    spawnSyncMock.mockReturnValue({ status: 0, error: undefined });
  });
  afterEach(() => {
    consoleSpy.mockRestore();
  });
  it('calls spawnSync with the editor binary and config path', async () => {
    process.env['EDITOR'] = 'nano';
    const program = buildProgram();
    await program.parseAsync(['node', 'mosaic', 'config', 'edit']);
    expect(spawnSyncMock).toHaveBeenCalledWith(
      'nano',
      ['/home/user/.config/mosaic'],
      expect.objectContaining({ stdio: 'inherit' }),
    );
    delete process.env['EDITOR'];
  });
  it('falls back to "vi" when EDITOR is not set', async () => {
    delete process.env['EDITOR'];
    const program = buildProgram();
    await program.parseAsync(['node', 'mosaic', 'config', 'edit']);
    expect(spawnSyncMock).toHaveBeenCalledWith('vi', expect.any(Array), expect.any(Object));
  });
  it('opens the section-specific file when --section is provided', async () => {
    process.env['EDITOR'] = 'code';
    const program = buildProgram();
    await program.parseAsync(['node', 'mosaic', 'config', 'edit', '--section', 'soul']);
    expect(spawnSyncMock).toHaveBeenCalledWith(
      'code',
      ['/home/user/.config/mosaic/SOUL.md'],
      expect.any(Object),
    );
    delete process.env['EDITOR'];
  });
 });
 // ── not-initialized guard ────────────────────────────────────────────────────
 describe('not-initialized guard', () => {
  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
  beforeEach(() => {
    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
    vi.clearAllMocks();
    mockSvc.isInitialized.mockReturnValue(false);
  });
  afterEach(() => {
    consoleErrorSpy.mockRestore();
    mockSvc.isInitialized.mockReturnValue(true);
  });
  it('prints a helpful message when config is missing (show)', async () => {
    const program = buildProgram();
    // process.exit is intercepted; catch the resulting error from exitOverride
    await expect(program.parseAsync(['node', 'mosaic', 'config', 'show'])).rejects.toThrow();
    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('mosaic wizard'));
  });
 });
--- a/packages/mosaic/src/commands/config.ts
+++ b/packages/mosaic/src/commands/config.ts
@@ -1,206 +0,0 @@
 import { spawnSync } from 'node:child_process';
 import type { Command } from 'commander';
 import { createConfigService } from '../config/config-service.js';
 import { DEFAULT_MOSAIC_HOME } from '../constants.js';
 /**
 * Resolve mosaicHome from the MOSAIC_HOME env var or the default constant.
 */
 function getMosaicHome(): string {
  return process.env['MOSAIC_HOME'] ?? DEFAULT_MOSAIC_HOME;
 }
 /**
 * Guard: print an error and exit(1) if config has not been initialised.
 */
 function assertInitialized(svc: ReturnType<typeof createConfigService>): void {
  if (!svc.isInitialized()) {
    console.error('No config found — run `mosaic wizard` first.');
    process.exit(1);
  }
 }
 /**
 * Flatten a nested object into dotted-key rows for table display.
 */
 function flattenConfig(obj: Record<string, unknown>, prefix = ''): Array<[string, string]> {
  const rows: Array<[string, string]> = [];
  for (const [k, v] of Object.entries(obj)) {
    const key = prefix ? `${prefix}.${k}` : k;
    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
      rows.push(...flattenConfig(v as Record<string, unknown>, key));
    } else {
      rows.push([key, v === undefined || v === null ? '' : String(v)]);
    }
  }
  return rows;
 }
 /**
 * Print rows as a padded ASCII table.
 */
 function printTable(rows: Array<[string, string]>): void {
  if (rows.length === 0) {
    console.log('(no config values)');
    return;
  }
  const maxKey = Math.max(...rows.map(([k]) => k.length));
  const header = `${'Key'.padEnd(maxKey)}  Value`;
  const divider = '-'.repeat(header.length);
  console.log(header);
  console.log(divider);
  for (const [k, v] of rows) {
    console.log(`${k.padEnd(maxKey)}  ${v}`);
  }
 }
 export function registerConfigCommand(program: Command): void {
  const cmd = program
    .command('config')
    .description('Manage Mosaic framework configuration')
    .configureHelp({ sortSubcommands: true });
  // ── config show ─────────────────────────────────────────────────────────
  cmd
    .command('show')
    .description('Print the current resolved config')
    .option('-f, --format <format>', 'Output format: table or json', 'table')
    .action(async (opts: { format: string }) => {
      const mosaicHome = getMosaicHome();
      const svc = createConfigService(mosaicHome, mosaicHome);
      assertInitialized(svc);
      const config = await svc.readAll();
      if (opts.format === 'json') {
        console.log(JSON.stringify(config, null, 2));
        return;
      }
      // Default: table
      const rows = flattenConfig(config as unknown as Record<string, unknown>);
      printTable(rows);
    });
  // ── config get <key> ────────────────────────────────────────────────────
  cmd
    .command('get <key>')
    .description('Print a single config value (supports dotted keys, e.g. soul.agentName)')
    .action(async (key: string) => {
      const mosaicHome = getMosaicHome();
      const svc = createConfigService(mosaicHome, mosaicHome);
      assertInitialized(svc);
      const value = await svc.getValue(key);
      if (value === undefined) {
        console.error(`Key "${key}" not found.`);
        process.exit(1);
      }
      if (typeof value === 'object') {
        console.log(JSON.stringify(value, null, 2));
      } else {
        console.log(String(value));
      }
    });
  // ── config set <key> <value> ────────────────────────────────────────────
  cmd
    .command('set <key> <value>')
    .description(
      'Set a config value and persist (supports dotted keys, e.g. soul.agentName "Jarvis")',
    )
    .action(async (key: string, value: string) => {
      const mosaicHome = getMosaicHome();
      const svc = createConfigService(mosaicHome, mosaicHome);
      assertInitialized(svc);
      let previous: unknown;
      try {
        previous = await svc.setValue(key, value);
      } catch (err) {
        console.error(err instanceof Error ? err.message : String(err));
        process.exit(1);
      }
      const prevStr = previous === undefined ? '(unset)' : String(previous);
      console.log(`${key}`);
      console.log(`  old: ${prevStr}`);
      console.log(`  new: ${value}`);
    });
  // ── config edit ─────────────────────────────────────────────────────────
  cmd
    .command('edit')
    .description('Open the config directory in $EDITOR (or vi)')
    .option('-s, --section <section>', 'Open a specific section file: soul | user | tools')
    .action(async (opts: { section?: string }) => {
      const mosaicHome = getMosaicHome();
      const svc = createConfigService(mosaicHome, mosaicHome);
      assertInitialized(svc);
      const editor = process.env['EDITOR'] ?? 'vi';
      let targetPath: string;
      if (opts.section) {
        const validSections = ['soul', 'user', 'tools'] as const;
        if (!validSections.includes(opts.section as (typeof validSections)[number])) {
          console.error(`Invalid section "${opts.section}". Choose: soul, user, tools`);
          process.exit(1);
        }
        targetPath = svc.getConfigPath(opts.section as 'soul' | 'user' | 'tools');
      } else {
        targetPath = svc.getConfigPath();
      }
      const result = spawnSync(editor, [targetPath], { stdio: 'inherit' });
      if (result.error) {
        console.error(`Failed to open editor: ${result.error.message}`);
        process.exit(1);
      }
      if (result.status !== 0) {
        console.error(`Editor exited with code ${String(result.status ?? 1)}`);
        process.exit(result.status ?? 1);
      }
      // Re-read after edit and report any issues
      try {
        await svc.readAll();
        console.log('Config looks valid.');
      } catch (err) {
        console.error('Warning: config may have validation issues:');
        console.error(err instanceof Error ? err.message : String(err));
        process.exit(1);
      }
    });
  // ── config path ─────────────────────────────────────────────────────────
  cmd
    .command('path')
    .description('Print the active config directory path (for scripting)')
    .option(
      '-s, --section <section>',
      'Print path for a specific section file: soul | user | tools',
    )
    .action(async (opts: { section?: string }) => {
      const mosaicHome = getMosaicHome();
      const svc = createConfigService(mosaicHome, mosaicHome);
      if (opts.section) {
        const validSections = ['soul', 'user', 'tools'] as const;
        if (!validSections.includes(opts.section as (typeof validSections)[number])) {
          console.error(`Invalid section "${opts.section}". Choose: soul, user, tools`);
          process.exit(1);
        }
        console.log(svc.getConfigPath(opts.section as 'soul' | 'user' | 'tools'));
      } else {
        console.log(svc.getConfigPath());
      }
    });
 }
--- a/packages/mosaic/src/commands/gateway.ts
+++ b/packages/mosaic/src/commands/gateway.ts
@@ -6,6 +6,7 @@ import {
  stopDaemon,
  waitForHealth,
 } from './gateway/daemon.js';
 import { getGatewayUrl } from './gateway/login.js';
 interface GatewayParentOpts {
  host: string;
@@ -119,9 +120,28 @@ 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 ─────────────────────────────────────────────────────────────
-  gw.command('config')
+  const configCmd = gw
    .command('config')
    .description('View or modify gateway configuration')
    .option('--set <KEY=VALUE>', 'Set a configuration value')
    .option('--unset <KEY>', 'Remove a configuration key')
@@ -131,6 +151,24 @@ 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,10 +388,32 @@ async function bootstrapFirstUser(
    if (!status.needsSetup) {
      if (meta.adminToken) {
        console.log('Admin user already exists (token on file).');
-      } else {
+        return;
        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
@@ -0,0 +1,87 @@
 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
@@ -0,0 +1,39 @@
 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
@@ -0,0 +1,176 @@
 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
@@ -0,0 +1,205 @@
 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
@@ -0,0 +1,149 @@
 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/mosaic/src/config/config-service.ts
+++ b/packages/mosaic/src/config/config-service.ts
@@ -1,16 +1,6 @@
 import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
 import { FileConfigAdapter } from './file-adapter.js';
 /** Supported top-level config sections for dotted-key access. */
 export type ConfigSection = 'soul' | 'user' | 'tools';
 /** A resolved view of all config sections, keyed by section name. */
 export interface ResolvedConfig {
  soul: SoulConfig;
  user: UserConfig;
  tools: ToolsConfig;
 }
 /**
 * ConfigService interface — abstracts config read/write operations.
 * Currently backed by FileConfigAdapter (writes .md files from templates).
@@ -26,35 +16,6 @@ export interface ConfigService {
  writeTools(config: ToolsConfig): Promise<void>;
  syncFramework(action: InstallAction): Promise<void>;
  /**
   * Return the resolved (merged) config across all sections.
   */
  readAll(): Promise<ResolvedConfig>;
  /**
   * Read a single value by dotted key (e.g. "soul.agentName").
   * Returns undefined if the key doesn't exist.
   */
  getValue(dottedKey: string): Promise<unknown>;
  /**
   * Set a single value by dotted key (e.g. "soul.agentName") and persist.
   * Returns the previous value (or undefined).
   */
  setValue(dottedKey: string, value: string): Promise<unknown>;
  /**
   * Return the filesystem path for a given config section file.
   * When no section is provided, returns the mosaicHome directory.
   */
  getConfigPath(section?: ConfigSection): string;
  /**
   * Returns true if the mosaicHome directory exists and at least one
   * config file (SOUL.md, USER.md, TOOLS.md) is present.
   */
  isInitialized(): boolean;
 }
 export function createConfigService(mosaicHome: string, sourceDir: string): ConfigService {
--- a/packages/mosaic/src/config/file-adapter.ts
+++ b/packages/mosaic/src/config/file-adapter.ts
@@ -1,6 +1,6 @@
 import { readFileSync, existsSync, readdirSync, statSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
-import type { ConfigService, ConfigSection, ResolvedConfig } from './config-service.js';
+import type { ConfigService } from './config-service.js';
 import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
 import { soulSchema, userSchema, toolsSchema } from './schemas.js';
 import { renderTemplate } from '../template/engine.js';
@@ -159,73 +159,6 @@ export class FileConfigAdapter implements ConfigService {
    }
  }
  async readAll(): Promise<ResolvedConfig> {
    const [soul, user, tools] = await Promise.all([
      this.readSoul(),
      this.readUser(),
      this.readTools(),
    ]);
    return { soul, user, tools };
  }
  async getValue(dottedKey: string): Promise<unknown> {
    const parts = dottedKey.split('.');
    const section = parts[0] ?? '';
    const field = parts.slice(1).join('.');
    const config = await this.readAll();
    if (!this.isValidSection(section)) return undefined;
    const sectionData = config[section as ConfigSection] as Record<string, unknown>;
    return field ? sectionData[field] : sectionData;
  }
  async setValue(dottedKey: string, value: string): Promise<unknown> {
    const parts = dottedKey.split('.');
    const section = parts[0] ?? '';
    const field = parts.slice(1).join('.');
    if (!this.isValidSection(section) || !field) {
      throw new Error(
        `Invalid key "${dottedKey}". Use format <section>.<field> (e.g. soul.agentName).`,
      );
    }
    const previous = await this.getValue(dottedKey);
    if (section === 'soul') {
      const current = await this.readSoul();
      await this.writeSoul({ ...current, [field]: value });
    } else if (section === 'user') {
      const current = await this.readUser();
      await this.writeUser({ ...current, [field]: value });
    } else {
      const current = await this.readTools();
      await this.writeTools({ ...current, [field]: value });
    }
    return previous;
  }
  getConfigPath(section?: ConfigSection): string {
    if (!section) return this.mosaicHome;
    const fileMap: Record<ConfigSection, string> = {
      soul: join(this.mosaicHome, 'SOUL.md'),
      user: join(this.mosaicHome, 'USER.md'),
      tools: join(this.mosaicHome, 'TOOLS.md'),
    };
    return fileMap[section];
  }
  isInitialized(): boolean {
    return (
      existsSync(join(this.mosaicHome, 'SOUL.md')) ||
      existsSync(join(this.mosaicHome, 'USER.md')) ||
      existsSync(join(this.mosaicHome, 'TOOLS.md'))
    );
  }
  private isValidSection(s: string): s is ConfigSection {
    return s === 'soul' || s === 'user' || s === 'tools';
  }
  /**
   * Look for template in source dir first, then mosaic home.
   */
--- 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
@@ -416,10 +416,6 @@ importers:
        version: 2.1.9(@types/node@24.12.0)(jsdom@29.0.0(@noble/hashes@2.0.1))(lightningcss@1.31.1)
  packages/macp:
    dependencies:
      commander:
        specifier: ^13.0.0
        version: 13.1.0
    devDependencies:
      '@types/node':
        specifier: ^22.0.0
@@ -479,9 +475,6 @@ importers:
      '@mosaicstack/quality-rails':
        specifier: workspace:*
        version: link:../quality-rails
      '@mosaicstack/queue':
        specifier: workspace:*
        version: link:../queue
      '@mosaicstack/types':
        specifier: workspace:*
        version: link:../types
@@ -578,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