amicus 1.0.0

package/src/sidecar/fanout-output.js

@@ -0,0 +1,46 @@
+// src/sidecar/fanout-output.js
+'use strict';
+
+/**
+ * @module fanout-output
+ * Human-readable rendering of a wave document (the non-JSON default for
+ * `amicus fanout` stdout and `amicus read <waveId>`).
+ */
+
+/** Format ms as "1m5s" / "42s". */
+function fmtDuration(ms) {
+  if (ms === null || ms === undefined) { return '-'; }
+  const s = Math.round(ms / 1000);
+  const m = Math.floor(s / 60);
+  return m > 0 ? `${m}m${s % 60}s` : `${s}s`;
+}
+
+/**
+ * Render a wave document for humans: per-leg sections in order, then a footer.
+ * @param {object} wave - Wave document (result-schema shape)
+ * @returns {string}
+ */
+function formatWaveHuman(wave) {
+  const lines = [];
+  for (const leg of wave.legs) {
+    const label = leg.modelInput || leg.model || leg.taskId;
+    lines.push(`${'─'.repeat(8)} ${label} (${leg.taskId}) ${'─'.repeat(8)}`);
+    if (leg.summary && leg.summary.trim()) {
+      lines.push(leg.summary.trim());
+    } else {
+      lines.push(`(no output) [${leg.status}${leg.error ? `: ${leg.error}` : ''}]`);
+    }
+    lines.push('');
+  }
+  if (wave.error) { lines.push(`Error: ${wave.error}`); }
+  lines.push('─'.repeat(40));
+  const counts = wave.counts || { complete: '?', total: '?' };
+  lines.push(`Wave ${wave.waveId}: ${wave.status} — ${counts.complete}/${counts.total} complete in ${fmtDuration(wave.durationMs)}`);
+  for (const leg of wave.legs) {
+    const label = leg.modelInput || leg.model || leg.taskId;
+    lines.push(`  ${leg.taskId}  ${String(label).padEnd(12)} ${String(leg.status).padEnd(9)} ${fmtDuration(leg.durationMs)}`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = { formatWaveHuman, fmtDuration };

package/src/sidecar/fanout.js

@@ -0,0 +1,236 @@
+// src/sidecar/fanout.js
+'use strict';
+
+/**
+ * @module fanout
+ * F4 council-native fan-out: run N models on the same prompt concurrently on
+ * ONE shared OpenCode server (runHeadless external-server mode). Each leg is
+ * an ordinary session (parentWave metadata); results aggregate into a wave
+ * document persisted as wave.json in the wave session dir.
+ * Spec: docs/superpowers/specs/2026-06-09-f4-fanout-json-design.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logger } = require('../utils/logger');
+const { runLeg } = require('./fanout-leg');
+
+/** Default max legs per wave (env-overridable). */
+const DEFAULT_MAX_LEGS = 10;
+
+/**
+ * Split a --models value into trimmed, non-empty entries (duplicates allowed).
+ * @param {string|boolean|undefined} modelsArg
+ * @returns {string[]}
+ */
+function parseModelsList(modelsArg) {
+  if (typeof modelsArg !== 'string') { return []; }
+  return modelsArg.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/**
+ * Derive leg task IDs: <waveId>-1 .. <waveId>-N (matches TASK_ID_PATTERN).
+ * @param {string} waveId
+ * @param {number} count
+ * @returns {string[]}
+ */
+function deriveLegIds(waveId, count) {
+  return Array.from({ length: count }, (_, i) => `${waveId}-${i + 1}`);
+}
+
+/**
+ * Fail-fast validation of the whole model list BEFORE any leg launches:
+ * alias resolution, API-key presence, live-catalog validation (F3 machinery).
+ * @param {string} modelsArg - Raw --models value
+ * @param {{noValidateModel?: boolean}} [opts]
+ * @returns {Promise<{legs: Array<{modelInput: string, model: string}>} | {error: string}>}
+ */
+async function validateFanoutModels(modelsArg, opts = {}) {
+  const raw = parseModelsList(modelsArg);
+  if (raw.length === 0) {
+    return { error: 'Error: --models requires a comma-separated list (e.g. gemini,gpt,deepseek)' };
+  }
+  // Invalid or non-positive AMICUS_FANOUT_MAX_LEGS (0, negative, garbage) falls back to the default.
+  const envCap = Number(process.env.AMICUS_FANOUT_MAX_LEGS);
+  const maxLegs = (Number.isInteger(envCap) && envCap > 0) ? envCap : DEFAULT_MAX_LEGS;
+  if (raw.length > maxLegs) {
+    return { error: `Error: --models exceeds the fan-out cap of ${maxLegs} legs (set AMICUS_FANOUT_MAX_LEGS to raise)` };
+  }
+
+  const { tryResolveModel } = require('../utils/config');
+  const { validateApiKey } = require('../utils/validators');
+  const { validateAgainstCatalog } = require('../utils/model-validator');
+  const legs = [];
+  for (const modelInput of raw) {
+    const resolved = tryResolveModel(modelInput);
+    if (resolved.error) {
+      return { error: `Error: model '${modelInput}': ${resolved.error}` };
+    }
+    let model = resolved.model;
+    const keyCheck = validateApiKey(model);
+    if (!keyCheck.valid) {
+      return { error: keyCheck.error };
+    }
+    if (!opts.noValidateModel) {
+      const alias = modelInput.includes('/') ? undefined : modelInput;
+      try {
+        model = await validateAgainstCatalog(model, alias);
+      } catch (err) {
+        return { error: err.message };
+      }
+    }
+    legs.push({ modelInput, model });
+  }
+  return { legs };
+}
+
+/** Write/merge wave metadata (preserves fields an MCP pre-spawn handler wrote). */
+function writeWaveMetadata(waveDir, patch) {
+  const metaPath = path.join(waveDir, 'metadata.json');
+  let existing = {};
+  if (fs.existsSync(metaPath)) {
+    try { existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch { /* corrupt → rewrite */ }
+  }
+  const merged = { ...existing, ...patch };
+  fs.writeFileSync(metaPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
+  return merged;
+}
+
+/**
+ * Run a fan-out wave. Spec §4.3.
+ * @param {object} options - models, prompt, promptMeta, waveId?, project, agent?,
+ *   thinking?, timeout? (minutes), summaryLength?, includeContext?, sessionId?,
+ *   contextTurns?, contextSince?, contextMaxTokens?, mcp?, mcpConfig?, noMcp?,
+ *   excludeMcp?, noValidateModel?, json?, client?, quiet? (suppress stdout — tests)
+ * @returns {Promise<{wave: object, exitCode: number}>} Never rejects for leg errors.
+ */
+async function runFanout(options) {
+  const { buildWaveResult, waveExitCode } = require('../utils/result-schema');
+  const { generateTaskId, buildMcpConfig } = require('./start');
+  const { startOpenCodeServer, createHeartbeat, HEARTBEAT_INTERVAL } = require('./session-utils');
+  const { buildContext } = require('./context-builder');
+  const { buildPrompts } = require('../prompt-builder');
+  const { installSignalAbort, markAborted } = require('../utils/session-abort');
+  const { getSessionDir } = require('../session-manager');
+
+  const project = options.project || process.cwd();
+  const createdAt = new Date().toISOString();
+  const emit = (doc) => {
+    if (options.quiet) { return; }
+    if (options.json) {
+      console.log(JSON.stringify(doc, null, 2));
+    } else {
+      const { formatWaveHuman } = require('./fanout-output');
+      console.log(formatWaveHuman(doc));
+    }
+  };
+  const errorWave = (waveId, message) => {
+    const doc = buildWaveResult({ waveId: waveId || null, legs: [], promptMeta: options.promptMeta || null, createdAt, completedAt: new Date().toISOString(), status: 'error' });
+    doc.error = message;
+    emit(doc);
+    return { wave: doc, exitCode: 1 };
+  };
+
+  // 1. Fail-fast validation
+  const validated = await validateFanoutModels(options.models, { noValidateModel: options.noValidateModel });
+  if (validated.error) { return errorWave(options.waveId, validated.error); }
+  const legs = validated.legs;
+
+  // 2. Wave record
+  const waveId = options.waveId || generateTaskId();
+  const legIds = deriveLegIds(waveId, legs.length);
+  const waveDir = getSessionDir(project, waveId);
+  fs.mkdirSync(waveDir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(path.join(waveDir, 'briefing.md'), options.prompt, { mode: 0o600 });
+  writeWaveMetadata(waveDir, {
+    taskId: waveId, type: 'wave', status: 'running', mode: 'headless',
+    models: legs.map(l => l.model), legs: legIds,
+    briefing: String(options.prompt).slice(0, 200),
+    promptMeta: options.promptMeta || null,
+    pid: process.pid, project, createdAt,
+  });
+
+  // 3. Context + prompts built ONCE (model-independent)
+  const context = options.includeContext !== false
+    ? buildContext(project, options.sessionId || 'current', {
+        contextTurns: options.contextTurns, contextSince: options.contextSince,
+        contextMaxTokens: options.contextMaxTokens, client: options.client,
+      })
+    : '[Context excluded by caller - briefing is self-contained]';
+  const { system: systemPrompt, userMessage } = buildPrompts(
+    options.prompt, context, project, true, options.agent || 'build', options.summaryLength, options.client
+  );
+
+  // 4. One shared OpenCode server
+  const mcpServers = buildMcpConfig({
+    mcp: options.mcp, mcpConfig: options.mcpConfig, clientType: options.client,
+    noMcp: options.noMcp, excludeMcp: options.excludeMcp,
+  });
+  let client, server;
+  try {
+    ({ client, server } = await startOpenCodeServer(mcpServers));
+  } catch (err) {
+    writeWaveMetadata(waveDir, { status: 'error', reason: err.message, completedAt: new Date().toISOString() });
+    return errorWave(waveId, `Failed to start server: ${err.message}`);
+  }
+  if (server.goPid) { writeWaveMetadata(waveDir, { goPid: server.goPid }); }
+
+  // 5. Signal abort: mark wave + all legs aborted, close the server, then let
+  // NORMAL control flow finalize — legs see their abort marker within one poll
+  // (~2s) and settle, so step 7 still writes wave.json and emits a parseable
+  // aborted document. An unref'd force-exit watchdog backstops a wedged leg.
+  const legDirs = legIds.map(id => getSessionDir(project, id));
+  let signalled = null;
+  const uninstallSignals = installSignalAbort({
+    onAbort: (signal) => {
+      const code = signal === 'SIGINT' ? 130 : 143;
+      if (signalled) { process.exit(code); } // second signal: exit NOW
+      signalled = signal;
+      logger.warn('Signal received — aborting wave', { waveId, signal });
+      markAborted(waveDir, signal);
+      for (const dir of legDirs) { markAborted(dir, signal); }
+      try { server.close(); } catch { /* best-effort */ }
+      const { armExitWatchdog } = require('../utils/lifecycle');
+      armExitWatchdog(code, 10000, { log: (m, meta) => logger.debug(m, meta) });
+    },
+  });
+
+  // 6. Launch all legs concurrently (runLeg never rejects)
+  const heartbeat = options.quiet ? { stop() {} } : createHeartbeat(HEARTBEAT_INTERVAL);
+  const timeoutMs = (options.timeout || 15) * 60 * 1000;
+  const reasoning = options.thinking ? { effort: options.thinking } : undefined;
+  let legDocs;
+  try {
+    legDocs = await Promise.all(legs.map((leg, i) => runLeg({
+      leg, legId: legIds[i], waveId, project, systemPrompt, userMessage,
+      timeoutMs, agent: options.agent, client, server,
+      summaryLength: options.summaryLength, reasoning, quiet: options.quiet,
+    })));
+  } finally {
+    heartbeat.stop();
+    uninstallSignals();
+    try { server.close(); } catch { /* already closed on signal */ }
+  }
+
+  // 7. Aggregate, persist (atomic: tmp + rename), finalize, emit
+  const completedAt = new Date().toISOString();
+  const wave = buildWaveResult({
+    waveId, legs: legDocs, promptMeta: options.promptMeta || null, createdAt, completedAt,
+    status: signalled ? 'aborted' : null,
+  });
+  const wavePath = path.join(waveDir, 'wave.json');
+  const waveTmp = `${wavePath}.tmp`;
+  fs.writeFileSync(waveTmp, JSON.stringify(wave, null, 2), { mode: 0o600 });
+  fs.renameSync(waveTmp, wavePath);
+  writeWaveMetadata(waveDir, { status: wave.status, completedAt });
+  emit(wave);
+  const exitCode = signalled
+    ? (signalled === 'SIGINT' ? 130 : 143)
+    : waveExitCode(wave.status);
+  return { wave, exitCode };
+}
+
+module.exports = {
+  parseModelsList, deriveLegIds, validateFanoutModels, DEFAULT_MAX_LEGS,
+  runFanout, runLeg, writeWaveMetadata,
+};

package/src/sidecar/interactive.js

@@ -0,0 +1,217 @@
+/**
+ * Sidecar Interactive Mode - Electron GUI session management
+ * Extracted from start.js for file size compliance (< 300 lines).
+ */
+
+const path = require('path');
+const { spawn } = require('child_process');
+
+const { startOpenCodeServer } = require('./session-utils');
+const { createSession, sendPromptAsync } = require('../opencode-client');
+const { mapAgentToOpenCode } = require('../utils/agent-mapping');
+const { logger } = require('../utils/logger');
+const { getCompatEnv } = require('../utils/env-compat');
+
+/** Get the Electron binary path via require('electron').
+ *  Works in all install contexts (global, local, npx hoisted).
+ *  @returns {string|null} Full path to Electron binary, or null if not installed */
+function getElectronPath() {
+  try {
+    return require('electron');
+  } catch {
+    return null;
+  }
+}
+
+/** Check if Electron is available (lazy loading guard) */
+function checkElectronAvailable() {
+  return getElectronPath() !== null;
+}
+
+/** Build environment variables for Electron process */
+function buildElectronEnv(taskId, model, project, nodeModulesBin, existingPath, options = {}) {
+  const { agent, isResume, conversation, mcp, client, windowPosition } = options;
+  const env = {
+    ...process.env,
+    PATH: `${nodeModulesBin}${path.delimiter}${existingPath}`,
+    AMICUS_TASK_ID: taskId,
+    AMICUS_MODEL: model,
+    SIDECAR_PROJECT: project
+  };
+
+  if (client) { env.AMICUS_CLIENT = client; }
+  if (windowPosition) { env.AMICUS_WINDOW_POSITION = windowPosition; }
+
+  if (agent) {
+    const agentConfig = mapAgentToOpenCode(agent);
+    env.SIDECAR_AGENT = agentConfig.agent;
+    if (agentConfig.permissions) { env.SIDECAR_PERMISSIONS = agentConfig.permissions; }
+  }
+
+  if (isResume) {
+    env.SIDECAR_RESUME = 'true';
+    if (conversation) { env.SIDECAR_CONVERSATION = conversation; }
+  }
+
+  if (mcp) { env.SIDECAR_MCP_CONFIG = JSON.stringify(mcp); }
+
+  return env;
+}
+
+/** Handle Electron process stdout/stderr and exit */
+function handleElectronProcess(electronProcess, taskId, resolve) {
+  let stdout = '';
+
+  electronProcess.stdout.on('data', (data) => { stdout += data.toString(); });
+
+  electronProcess.stderr.on('data', (data) => {
+    data.toString().trim().split('\n').filter(l => l.trim())
+      .forEach(line => logger.debug('Electron', { output: line.trim() }));
+  });
+
+  electronProcess.on('error', (error) => {
+    logger.error('Electron process error', { error: error.message });
+    resolve({
+      summary: '', completed: false, timedOut: false, taskId,
+      error: `Failed to start Electron: ${error.message}`
+    });
+  });
+
+  electronProcess.on('close', (code) => {
+    logger.debug('Electron closed', { code, stdoutLength: stdout.length });
+    resolve({
+      summary: stdout.trim() || 'Session ended without summary.',
+      completed: code === 0, timedOut: false, taskId, exitCode: code
+    });
+  });
+}
+
+/** Run sidecar in interactive mode (Electron GUI) */
+async function runInteractive(model, systemPrompt, userMessage, taskId, project, options = {}) {
+  if (!checkElectronAvailable()) {
+    logger.error('Electron not installed — interactive mode unavailable');
+    return {
+      summary: '', completed: false, timedOut: false, taskId,
+      error: 'Interactive mode requires electron. Install with: npm install -g amicus (or use --no-ui for headless mode)'
+    };
+  }
+
+  const { agent, isResume, conversation, mcp, reasoning, opencodeSessionId, client } = options;
+
+  // Start OpenCode server with system prompt baked into agent config.
+  // Agent config prompts are hidden from the UI, unlike promptAsync's system field.
+  const agentConfig = mapAgentToOpenCode(agent);
+  let ocClient, server;
+  try {
+    const result = await startOpenCodeServer(mcp, {
+      client, systemPrompt, agentName: agentConfig.agent
+    });
+    ocClient = result.client;
+    server = result.server;
+  } catch (error) {
+    logger.error('Failed to start OpenCode server', { error: error.message });
+    return {
+      summary: '', completed: false, timedOut: false, taskId,
+      error: `Failed to start server: ${error.message}`
+    };
+  }
+
+  // Create or reconnect to session
+  let sessionId;
+  try {
+    if (isResume && opencodeSessionId) {
+      // Resume: reconnect to existing OpenCode session
+      sessionId = opencodeSessionId;
+      logger.info('Reconnecting to existing session', { sessionId });
+    } else {
+      // New session: create and send initial prompt
+      sessionId = await createSession(ocClient);
+
+      // System prompt is set on agent config (hidden from UI).
+      // Do NOT pass system here — promptAsync's system field is visible in the UI.
+      const promptOptions = {
+        model,
+        parts: [{ type: 'text', text: userMessage }]
+      };
+
+      // Always set agent — defaults to 'chat' when not specified
+      promptOptions.agent = agentConfig.agent;
+      if (reasoning) { promptOptions.reasoning = reasoning; }
+
+      await sendPromptAsync(ocClient, sessionId, promptOptions);
+    }
+    logger.debug('Interactive session ready', { sessionId, isResume: !!isResume });
+  } catch (error) {
+    server.close();
+    return {
+      summary: '', completed: false, timedOut: false, taskId,
+      error: `Session setup failed: ${error.message}`
+    };
+  }
+
+  const serverPort = new URL(server.url).port;
+
+  // Start idle watchdog for interactive mode (60-min default timeout)
+  const { IdleWatchdog } = require('../utils/idle-watchdog');
+  const watchdog = new IdleWatchdog({
+    mode: 'interactive',
+    onTimeout: () => {
+      logger.info('Interactive idle timeout - shutting down', { taskId });
+    },
+  }).start();
+
+  return new Promise((resolve, _reject) => {
+    const electronPath = getElectronPath();
+    const mainPath = path.join(__dirname, '..', '..', 'electron', 'main.js');
+
+    const nodeModulesBin = path.join(__dirname, '..', '..', 'node_modules', '.bin');
+    const existingPath = process.env.PATH || '';
+    const env = buildElectronEnv(
+      taskId, model, project, nodeModulesBin, existingPath,
+      { agent, isResume, conversation, mcp, client }
+    );
+
+    // Pass OpenCode server info to Electron
+    env.AMICUS_OPENCODE_PORT = serverPort;
+    env.AMICUS_SESSION_ID = sessionId;
+
+    const debugPort = getCompatEnv('DEBUG_PORT') || '9222';
+    logger.debug('Launching Electron', { taskId, model, debugPort, serverPort, sessionId });
+
+    const electronProcess = spawn(electronPath, [
+      `--remote-debugging-port=${debugPort}`,
+      mainPath
+    ], { cwd: project, env, stdio: ['ignore', 'pipe', 'pipe'] });
+
+    // Touch watchdog on Electron stdout activity
+    electronProcess.stdout.on('data', () => {
+      watchdog.touch();
+    });
+
+    // Update watchdog onTimeout now that electronProcess is available
+    watchdog.onTimeout = () => {
+      logger.info('Interactive idle timeout - shutting down', { taskId });
+      if (!electronProcess.killed) {
+        electronProcess.kill('SIGTERM');
+      }
+    };
+
+    // Clean up server when Electron exits
+    const originalResolve = resolve;
+    handleElectronProcess(electronProcess, taskId, (result) => {
+      watchdog.cancel();
+      server.close();
+      logger.debug('OpenCode server closed after Electron exit');
+      result.opencodeSessionId = sessionId;
+      originalResolve(result);
+    });
+  });
+}
+
+module.exports = {
+  getElectronPath,
+  checkElectronAvailable,
+  buildElectronEnv,
+  handleElectronProcess,
+  runInteractive
+};

package/src/sidecar/models.js

@@ -0,0 +1,135 @@
+/**
+ * `amicus models` (F5) — list/search the catalog, refresh it, audit aliases.
+ *
+ *   amicus models                  list (curated aliases marked)
+ *   amicus models --search <q>     substring filter over id+name
+ *   amicus models --refresh        force-refresh the cache
+ *   amicus models --check          stale-alias audit (exit = stale count, max 100)
+ *   --json on all of the above     versioned documents (result-schema)
+ *
+ * Returns an exit code; bin/amicus.js plumbs it like fanout's.
+ */
+
+'use strict';
+
+const { getCatalogInfo, refreshCatalog, catalogPath } = require('../utils/model-catalog');
+const { collectAliasSources, findStaleAliases, suggestReplacements } = require('../utils/alias-audit');
+const { buildCatalogDoc, buildAuditDoc } = require('../utils/result-schema');
+
+const CHECK_EXIT_CAP = 100;
+
+/** '0.000003' per token → '3.00' per Mtok; '—' when unknown */
+function perMtok(perToken) {
+  if (perToken === null || perToken === undefined) { return '—'; }
+  const n = Number(perToken);
+  return Number.isNaN(n) ? '—' : (n * 1e6).toFixed(2);
+}
+
+function fmtRow(m, aliasesById) {
+  const alias = aliasesById.get(m.id);
+  const aliasCol = alias ? `[${alias}] ` : '';
+  const ctx = m.contextLength ?? '—';
+  const pIn = perMtok(m.pricing && m.pricing.prompt);
+  const pOut = perMtok(m.pricing && m.pricing.completion);
+  return `${aliasCol}${m.id}\n    ${m.name}  ctx ${ctx}  $/Mtok in ${pIn} out ${pOut}`;
+}
+
+/** alias marks: id → comma-joined alias names (defaults only — the curated view) */
+function aliasMarks() {
+  const { getDefaultAliases } = require('../utils/config');
+  const map = new Map();
+  for (const [alias, model] of Object.entries(getDefaultAliases())) {
+    map.set(model, map.has(model) ? `${map.get(model)},${alias}` : alias);
+  }
+  return map;
+}
+
+async function runList(args) {
+  const { models, fetchedAt } = await getCatalogInfo();
+  const q = typeof args.search === 'string' ? args.search.toLowerCase() : null;
+  const filtered = q
+    ? models.filter(m => m.id.toLowerCase().includes(q) || m.name.toLowerCase().includes(q))
+    : models;
+  if (args.json) {
+    process.stdout.write(JSON.stringify(buildCatalogDoc({
+      models: filtered, fetchedAt, search: q
+    }), null, 2) + '\n');
+    return 0;
+  }
+  const marks = aliasMarks();
+  // Curated (alias-marked) rows first, then the rest.
+  const curated = filtered.filter(m => marks.has(m.id));
+  const rest = filtered.filter(m => !marks.has(m.id));
+  for (const m of [...curated, ...rest]) {
+    process.stdout.write(fmtRow(m, marks) + '\n');
+  }
+  const when = fetchedAt ? new Date(fetchedAt).toISOString() : 'never';
+  process.stdout.write(`(${filtered.length} models, catalog fetched ${when})\n`);
+  if (filtered.length === 0 && models.length === 0) {
+    process.stdout.write('Catalog unavailable (offline or first run) — try: amicus models --refresh\n');
+  }
+  return 0;
+}
+
+async function runRefresh(args) {
+  const models = await refreshCatalog();
+  if (args.json) {
+    process.stdout.write(JSON.stringify(buildCatalogDoc({
+      models, fetchedAt: models.length > 0 ? Date.now() : null, refreshed: true
+    }), null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(`Refreshed catalog: ${models.length} models.\n`);
+  process.stdout.write(`Cache: ${catalogPath()}\n`);
+  return 0;
+}
+
+async function runCheck(args) {
+  const { models: catalog } = await getCatalogInfo();
+  if (!catalog || catalog.length === 0) {
+    if (args.json) {
+      process.stdout.write(JSON.stringify(buildAuditDoc({
+        stale: [], catalogAvailable: false
+      }), null, 2) + '\n');
+    } else {
+      process.stdout.write('Catalog unavailable (offline or no providers reachable); cannot check.\n');
+    }
+    return 0;
+  }
+  const sources = collectAliasSources();
+  const stale = findStaleAliases(sources, catalog)
+    .map(s => ({ ...s, suggestions: suggestReplacements(s.model, catalog) }));
+  if (args.json) {
+    process.stdout.write(JSON.stringify(buildAuditDoc({
+      stale, catalogAvailable: true
+    }), null, 2) + '\n');
+    return Math.min(stale.length, CHECK_EXIT_CAP);
+  }
+  if (stale.length === 0) {
+    process.stdout.write(`All aliases resolve to catalog models (${sources.length} checked).\n`);
+    return 0;
+  }
+  for (const s of stale) {
+    process.stdout.write(`STALE: ${s.alias} -> ${s.model} (${s.source})\n`);
+    if (s.suggestions.length > 0) {
+      process.stdout.write(`  candidates: ${s.suggestions.join(', ')}\n`);
+      process.stdout.write(`  fix: amicus setup --add-alias ${s.alias}=${s.suggestions[0]}\n`);
+    } else {
+      process.stdout.write('  no same-vendor candidates in catalog\n');
+    }
+  }
+  return Math.min(stale.length, CHECK_EXIT_CAP);
+}
+
+/** @param {object} args parsed CLI args @returns {Promise<number>} exit code */
+async function handleModels(args) {
+  if (args.search === true) {
+    process.stderr.write('Error: --search requires a value\n');
+    return 1;
+  }
+  if (args.refresh) { return runRefresh(args); }
+  if (args.check) { return runCheck(args); }
+  return runList(args);
+}
+
+module.exports = { handleModels };