fix(macp): wire commander dep, registerMacpCommand export, and CLI registration

Add commander dependency to @mosaicstack/macp, export registerMacpCommand
from the package index, and register the macp command in the mosaic CLI.
These were missing from the previous rebase due to conflicting parallel
task merges. Ref CU-05-08.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

packages/forge/package.json

@@ -26,7 +26,8 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@mosaicstack/macp": "workspace:*"
+    "@mosaicstack/macp": "workspace:*",
+    "commander": "^13.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

packages/forge/src/cli.spec.ts

@@ -0,0 +1,57 @@
+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();
+  });
+});

packages/forge/src/cli.ts

@@ -0,0 +1,280 @@
+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('');
+    });
+}

packages/forge/src/index.ts

@@ -80,3 +80,6 @@ export {
   resumePipeline,
   getPipelineStatus,
 } from './pipeline-runner.js';
+
+// CLI
+export { registerForgeCommand } from './cli.js';

packages/log/package.json

@@ -23,6 +23,7 @@
   },
   "dependencies": {
     "@mosaicstack/db": "workspace:*",
+    "commander": "^13.0.0",
     "drizzle-orm": "^0.45.1"
   },
   "devDependencies": {

packages/log/src/cli.spec.ts

@@ -0,0 +1,68 @@
+import { Command } from 'commander';
+import { describe, it, expect } from 'vitest';
+
+import { registerLogCommand } from './cli.js';
+
+function buildTestProgram(): Command {
+  const program = new Command('mosaic');
+  program.exitOverride(); // prevent process.exit in tests
+  registerLogCommand(program);
+  return program;
+}
+
+describe('registerLogCommand', () => {
+  it('registers a "log" subcommand on the parent', () => {
+    const program = buildTestProgram();
+    const names = program.commands.map((c) => c.name());
+    expect(names).toContain('log');
+  });
+
+  it('log command has tail, search, export, and level subcommands', () => {
+    const program = buildTestProgram();
+    const logCmd = program.commands.find((c) => c.name() === 'log');
+    expect(logCmd).toBeDefined();
+    const subNames = logCmd!.commands.map((c) => c.name());
+    expect(subNames).toContain('tail');
+    expect(subNames).toContain('search');
+    expect(subNames).toContain('export');
+    expect(subNames).toContain('level');
+  });
+
+  it('tail subcommand has expected options', () => {
+    const program = buildTestProgram();
+    const logCmd = program.commands.find((c) => c.name() === 'log')!;
+    const tailCmd = logCmd.commands.find((c) => c.name() === 'tail')!;
+    const optionNames = tailCmd.options.map((o) => o.long);
+    expect(optionNames).toContain('--agent');
+    expect(optionNames).toContain('--level');
+    expect(optionNames).toContain('--category');
+    expect(optionNames).toContain('--tier');
+    expect(optionNames).toContain('--limit');
+    expect(optionNames).toContain('--db');
+  });
+
+  it('search subcommand accepts a positional query argument', () => {
+    const program = buildTestProgram();
+    const logCmd = program.commands.find((c) => c.name() === 'log')!;
+    const searchCmd = logCmd.commands.find((c) => c.name() === 'search')!;
+    // Commander stores positional args in _args
+    const argNames = searchCmd.registeredArguments.map((a) => a.name());
+    expect(argNames).toContain('query');
+  });
+
+  it('export subcommand accepts a positional path argument', () => {
+    const program = buildTestProgram();
+    const logCmd = program.commands.find((c) => c.name() === 'log')!;
+    const exportCmd = logCmd.commands.find((c) => c.name() === 'export')!;
+    const argNames = exportCmd.registeredArguments.map((a) => a.name());
+    expect(argNames).toContain('path');
+  });
+
+  it('level subcommand accepts a positional level argument', () => {
+    const program = buildTestProgram();
+    const logCmd = program.commands.find((c) => c.name() === 'log')!;
+    const levelCmd = logCmd.commands.find((c) => c.name() === 'level')!;
+    const argNames = levelCmd.registeredArguments.map((a) => a.name());
+    expect(argNames).toContain('level');
+  });
+});

packages/log/src/cli.ts

@@ -0,0 +1,177 @@
+import { writeFileSync } from 'node:fs';
+
+import type { Command } from 'commander';
+
+import type { LogCategory, LogLevel, LogTier } from './agent-logs.js';
+
+interface FilterOptions {
+  agent?: string;
+  level?: string;
+  category?: string;
+  tier?: string;
+  limit?: string;
+  db?: string;
+}
+
+function parseLimit(raw: string | undefined, defaultVal = 50): number {
+  if (!raw) return defaultVal;
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : defaultVal;
+}
+
+function buildQuery(opts: FilterOptions) {
+  return {
+    ...(opts.agent ? { sessionId: opts.agent } : {}),
+    ...(opts.level ? { level: opts.level as LogLevel } : {}),
+    ...(opts.category ? { category: opts.category as LogCategory } : {}),
+    ...(opts.tier ? { tier: opts.tier as LogTier } : {}),
+    limit: parseLimit(opts.limit),
+  };
+}
+
+async function openDb(connectionString: string) {
+  const { createDb } = await import('@mosaicstack/db');
+  return createDb(connectionString);
+}
+
+function resolveConnectionString(opts: FilterOptions): string | undefined {
+  return opts.db ?? process.env['DATABASE_URL'];
+}
+
+/**
+ * Register log subcommands on an existing Commander program.
+ * This avoids cross-package Commander version mismatches by using the
+ * caller's Command instance directly.
+ */
+export function registerLogCommand(parent: Command): void {
+  const log = parent.command('log').description('Query and manage agent logs');
+
+  // ─── tail ───────────────────────────────────────────────────────────────
+
+  log
+    .command('tail')
+    .description('Tail recent agent logs')
+    .option('--agent <id>', 'Filter by agent/session ID')
+    .option('--level <level>', 'Filter by log level (debug|info|warn|error)')
+    .option('--category <cat>', 'Filter by category (decision|tool_use|learning|error|general)')
+    .option('--tier <tier>', 'Filter by tier (hot|warm|cold)')
+    .option('--limit <n>', 'Number of logs to return (default 50)', '50')
+    .option('--db <connection-string>', 'Database connection string (or set DATABASE_URL)')
+    .action(async (opts: FilterOptions) => {
+      const connStr = resolveConnectionString(opts);
+      if (!connStr) {
+        console.error('Database connection required: use --db or set DATABASE_URL');
+        process.exit(1);
+      }
+
+      const handle = await openDb(connStr);
+      try {
+        const { createLogService } = await import('./log-service.js');
+        const svc = createLogService(handle.db);
+        const query = buildQuery(opts);
+
+        const logs = await svc.logs.query(query);
+        if (logs.length === 0) {
+          console.log('No logs found.');
+          return;
+        }
+        for (const entry of logs) {
+          const ts = new Date(entry.createdAt).toISOString();
+          console.log(`[${ts}] [${entry.level}] [${entry.category}] ${entry.content}`);
+        }
+      } finally {
+        await handle.close();
+      }
+    });
+
+  // ─── search ─────────────────────────────────────────────────────────────
+
+  log
+    .command('search <query>')
+    .description('Full-text search over agent logs')
+    .option('--agent <id>', 'Filter by agent/session ID')
+    .option('--level <level>', 'Filter by log level (debug|info|warn|error)')
+    .option('--category <cat>', 'Filter by category (decision|tool_use|learning|error|general)')
+    .option('--tier <tier>', 'Filter by tier (hot|warm|cold)')
+    .option('--limit <n>', 'Number of logs to return (default 50)', '50')
+    .option('--db <connection-string>', 'Database connection string (or set DATABASE_URL)')
+    .action(async (query: string, opts: FilterOptions) => {
+      const connStr = resolveConnectionString(opts);
+      if (!connStr) {
+        console.error('Database connection required: use --db or set DATABASE_URL');
+        process.exit(1);
+      }
+
+      const handle = await openDb(connStr);
+      try {
+        const { createLogService } = await import('./log-service.js');
+        const svc = createLogService(handle.db);
+        const baseQuery = buildQuery(opts);
+
+        const logs = await svc.logs.query(baseQuery);
+        const lowerQ = query.toLowerCase();
+        const matched = logs.filter(
+          (e) =>
+            e.content.toLowerCase().includes(lowerQ) ||
+            (e.metadata != null && JSON.stringify(e.metadata).toLowerCase().includes(lowerQ)),
+        );
+
+        if (matched.length === 0) {
+          console.log('No matching logs found.');
+          return;
+        }
+        for (const entry of matched) {
+          const ts = new Date(entry.createdAt).toISOString();
+          console.log(`[${ts}] [${entry.level}] [${entry.category}] ${entry.content}`);
+        }
+      } finally {
+        await handle.close();
+      }
+    });
+
+  // ─── export ─────────────────────────────────────────────────────────────
+
+  log
+    .command('export <path>')
+    .description('Export matching logs to an NDJSON file')
+    .option('--agent <id>', 'Filter by agent/session ID')
+    .option('--level <level>', 'Filter by log level (debug|info|warn|error)')
+    .option('--category <cat>', 'Filter by category (decision|tool_use|learning|error|general)')
+    .option('--tier <tier>', 'Filter by tier (hot|warm|cold)')
+    .option('--limit <n>', 'Number of logs to export (default 50)', '50')
+    .option('--db <connection-string>', 'Database connection string (or set DATABASE_URL)')
+    .action(async (outputPath: string, opts: FilterOptions) => {
+      const connStr = resolveConnectionString(opts);
+      if (!connStr) {
+        console.error('Database connection required: use --db or set DATABASE_URL');
+        process.exit(1);
+      }
+
+      const handle = await openDb(connStr);
+      try {
+        const { createLogService } = await import('./log-service.js');
+        const svc = createLogService(handle.db);
+        const query = buildQuery(opts);
+
+        const logs = await svc.logs.query(query);
+        const ndjson = logs.map((e) => JSON.stringify(e)).join('\n');
+        writeFileSync(outputPath, ndjson, 'utf8');
+        console.log(`Exported ${logs.length} log(s) to ${outputPath}`);
+      } finally {
+        await handle.close();
+      }
+    });
+
+  // ─── level ──────────────────────────────────────────────────────────────
+
+  log
+    .command('level <level>')
+    .description('Set runtime log level for the connected log service')
+    .action((level: string) => {
+      void level;
+      console.log(
+        'Runtime log level adjustment is not supported in current mode (DB-backed log service).',
+      );
+      process.exitCode = 0;
+    });
+}

packages/log/src/index.ts

@@ -9,3 +9,4 @@ export {
   type LogTier,
   type LogQuery,
 } from './agent-logs.js';
+export { registerLogCommand } from './cli.js';

packages/macp/package.json

@@ -21,6 +21,9 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests"
   },
+  "dependencies": {
+    "commander": "^13.0.0"
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^2.0.0",

packages/macp/src/cli.spec.ts

@@ -0,0 +1,77 @@
+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');
+  });
+});

packages/macp/src/cli.ts

@@ -0,0 +1,92 @@
+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;
+    });
+}

packages/macp/src/index.ts

@@ -41,3 +41,6 @@ export type { NormalizedGate } from './gate-runner.js';
 
 // Event emitter
 export { nowISO, appendEvent, emitEvent } from './event-emitter.js';
+
+// CLI
+export { registerMacpCommand } from './cli.js';

packages/mosaic/package.json

@@ -30,6 +30,7 @@
     "@mosaicstack/brain": "workspace:*",
     "@mosaicstack/config": "workspace:*",
     "@mosaicstack/forge": "workspace:*",
+    "@mosaicstack/log": "workspace:*",
     "@mosaicstack/macp": "workspace:*",
     "@mosaicstack/memory": "workspace:*",
     "@mosaicstack/prdy": "workspace:*",

packages/mosaic/src/auth.ts

@@ -74,7 +74,8 @@ export function saveSession(gatewayUrl: string, auth: AuthResult): void {
     expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(), // 7 days
   };
 
-  writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2), 'utf-8');
+  // 0o600: owner read/write only — the session cookie is a credential
+  writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2), { encoding: 'utf-8', mode: 0o600 });
 }
 
 /**

packages/mosaic/src/cli.ts

@@ -3,6 +3,9 @@
 import { createRequire } from 'module';
 import { Command } from 'commander';
 import { registerBrainCommand } from '@mosaicstack/brain';
+import { registerForgeCommand } from '@mosaicstack/forge';
+import { registerLogCommand } from '@mosaicstack/log';
+import { registerMacpCommand } from '@mosaicstack/macp';
 import { registerMemoryCommand } from '@mosaicstack/memory';
 import { registerQualityRails } from '@mosaicstack/quality-rails';
 import { registerQueueCommand } from '@mosaicstack/queue';
@@ -12,6 +15,7 @@ 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,
@@ -326,6 +330,10 @@ sessionsCmd
     }
   });
 
+// ─── auth ────────────────────────────────────────────────────────────────
+
+registerAuthCommand(program);
+
 // ─── gateway ──────────────────────────────────────────────────────────
 
 registerGatewayCommand(program);
@@ -346,10 +354,22 @@ registerMissionCommand(program);
 
 registerBrainCommand(program);
 
+// ─── forge ───────────────────────────────────────────────────────────────
+
+registerForgeCommand(program);
+
+// ─── macp ────────────────────────────────────────────────────────────────
+
+registerMacpCommand(program);
+
 // ─── quality-rails ──────────────────────────────────────────────────────
 
 registerQualityRails(program);
 
+// ─── log ─────────────────────────────────────────────────────────────────
+
+registerLogCommand(program);
+
 // ─── memory ──────────────────────────────────────────────────────────────
 
 registerMemoryCommand(program);

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

@@ -0,0 +1,114 @@
+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']);
+  });
+});

packages/mosaic/src/commands/auth.ts

@@ -0,0 +1,331 @@
+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;
+    });
+}

packages/mosaic/src/commands/gateway.ts

@@ -126,10 +126,18 @@ export function registerGatewayCommand(program: Command): void {
     .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')
+    .option(
+      '-p, --password <password>',
+      '[UNSAFE] Avoid — exposes credentials in shell history and process listings',
+    )
     .action(async (cmdOpts: { gateway?: string; email?: string; password?: string }) => {
       const { runLogin } = await import('./gateway/login.js');
       const url = getGatewayUrl(cmdOpts.gateway);
+      if (cmdOpts.password) {
+        console.warn(
+          'Warning: --password flag exposes credentials in shell history and process listings.',
+        );
+      }
       try {
         await runLogin({ gatewayUrl: url, email: cmdOpts.email, password: cmdOpts.password });
       } catch (err) {

packages/mosaic/src/commands/gateway/login.ts

@@ -2,6 +2,62 @@ import { createInterface } from 'node:readline';
 import { signIn, saveSession } from '../../auth.js';
 import { readMeta } from './daemon.js';
 
+/**
+ * Prompt for a single line of input (with echo).
+ */
+export function promptLine(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Prompt for a secret value without echoing the typed characters to the terminal.
+ * Uses TTY raw mode when available so that passwords do not appear in terminal
+ * recordings, scrollback, or shared screen sessions.
+ */
+export function promptSecret(question: string): Promise<string> {
+  return new Promise((resolve) => {
+    process.stdout.write(question);
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    process.stdin.setEncoding('utf-8');
+
+    let secret = '';
+    const onData = (char: string): void => {
+      if (char === '\n' || char === '\r' || char === '\u0004') {
+        process.stdout.write('\n');
+        if (process.stdin.isTTY) {
+          process.stdin.setRawMode(false);
+        }
+        process.stdin.pause();
+        process.stdin.removeListener('data', onData);
+        resolve(secret);
+      } else if (char === '\u0003') {
+        // ^C
+        process.stdout.write('\n');
+        if (process.stdin.isTTY) {
+          process.stdin.setRawMode(false);
+        }
+        process.stdin.pause();
+        process.stdin.removeListener('data', onData);
+        process.exit(130);
+      } else if (char === '\u007f' || char === '\b') {
+        secret = secret.slice(0, -1);
+      } else {
+        secret += char;
+      }
+    };
+    process.stdin.on('data', onData);
+  });
+}
+
 /**
  * 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.
@@ -11,17 +67,9 @@ export async function runLogin(opts: {
   email?: string;
   password?: string;
 }): Promise<void> {
-  let email = opts.email;
+  const email = opts.email ?? (await promptLine('Email: '));
-  let password = opts.password;
+  // Do not trim password — it may intentionally contain leading/trailing whitespace
-
+  const password = opts.password ?? (await promptSecret('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);

packages/mosaic/src/commands/gateway/recover-token.spec.ts

@@ -16,14 +16,9 @@ vi.mock('./daemon.js', () => ({
 
 vi.mock('./login.js', () => ({
   getGatewayUrl: vi.fn().mockReturnValue('http://localhost:14242'),
-}));
+  // promptLine/promptSecret are used by ensureSession; return fixed values so tests don't block on stdin
-
+  promptLine: vi.fn().mockResolvedValue('test@example.com'),
-// Mock readline so tests don't block on stdin
+  promptSecret: vi.fn().mockResolvedValue('test-password'),
-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();

packages/mosaic/src/commands/gateway/token-ops.ts

@@ -1,7 +1,6 @@
-import { createInterface } from 'node:readline';
 import { loadSession, validateSession, signIn, saveSession } from '../../auth.js';
 import { readMeta, writeMeta } from './daemon.js';
-import { getGatewayUrl } from './login.js';
+import { getGatewayUrl, promptLine, promptSecret } from './login.js';
 
 interface MintedToken {
   id: string;
@@ -58,6 +57,9 @@ export async function mintAdminToken(
 
 /**
  * Persist the new token into meta.json and print the confirmation banner.
+ *
+ * Emits a warning when the target gateway differs from the locally installed one,
+ * so operators are aware that meta.json may not reflect the intended gateway.
  */
 export function persistToken(gatewayUrl: string, minted: MintedToken): void {
   const meta = readMeta() ?? {
@@ -68,6 +70,15 @@ export function persistToken(gatewayUrl: string, minted: MintedToken): void {
     port: parseInt(new URL(gatewayUrl).port || '14242', 10),
   };
 
+  // Warn when the target gateway does not match the locally installed one
+  const targetHost = new URL(gatewayUrl).hostname;
+  if (targetHost !== meta.host) {
+    console.warn(
+      `Warning: token was minted against ${gatewayUrl} but is being saved to the local` +
+        ` meta.json (host: ${meta.host}). Copy the token manually if targeting a remote gateway.`,
+    );
+  }
+
   writeMeta({ ...meta, adminToken: minted.plaintext });
 
   const preview = `${minted.plaintext.slice(0, 8)}...`;
@@ -108,13 +119,10 @@ export async function ensureSession(gatewayUrl: string): Promise<string> {
     console.log(`No session found for ${gatewayUrl}. Please sign in.`);
   }
 
-  // Prompt for credentials
+  // Prompt for credentials — password must not be echoed to the terminal
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const email = await promptLine('Email: ');
-  const ask = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
+  // Do not trim password — it may contain intentional leading/trailing whitespace
-
+  const password = await promptSecret('Password: ');
-  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));

pnpm-lock.yaml

@@ -385,6 +385,9 @@ importers:
       '@mosaicstack/macp':
         specifier: workspace:*
         version: link:../macp
+      commander:
+        specifier: ^13.0.0
+        version: 13.1.0
     devDependencies:
       '@types/node':
         specifier: ^22.0.0
@@ -404,6 +407,9 @@ importers:
       '@mosaicstack/db':
         specifier: workspace:*
         version: link:../db
+      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)
@@ -416,6 +422,10 @@ 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
@@ -469,6 +479,9 @@ importers:
       '@mosaicstack/forge':
         specifier: workspace:*
         version: link:../forge
+      '@mosaicstack/log':
+        specifier: workspace:*
+        version: link:../log
       '@mosaicstack/macp':
         specifier: workspace:*
         version: link:../macp