amicus 2.2.0 → 3.1.0

package/src/utils/model-input-default.js

@@ -0,0 +1,32 @@
+'use strict';
+
+/**
+ * @module model-input-default
+ * Shared "no --model given" default-lookup, extracted so it lives in exactly
+ * one place (#61 Task 6.2 review follow-up): both the CLI's resolveLaunchModel
+ * (start-helpers.js) and the MCP amicus_start handler (mcp-server.js) need to
+ * fall back to the configured default before handing a model off to
+ * resolveRouteForLaunch — without it, an omitted model reaches
+ * resolveRouteForLaunch as undefined -> parseDescriptor(undefined) -> an
+ * `invalid` descriptor, breaking the common "no --model" launch case.
+ * A leaf module (no other src/ module requires/mocks it), so introducing it
+ * doesn't reshape any existing jest.doMock('../src/utils/route-launch', ...)
+ * or jest.doMock('../src/utils/config', ...) call shape.
+ */
+
+/**
+ * Resolve the raw model input for a launch: an explicit value (including one
+ * a caller may have already normalized) passes through unchanged; otherwise
+ * falls back to the configured default.
+ * @param {string|null|undefined} inputModel
+ * @returns {string|undefined} inputModel as-is, the configured default, or
+ *   undefined if neither exists (the caller decides how to report that).
+ */
+function resolveModelInputOrDefault(inputModel) {
+  if (inputModel !== undefined && inputModel !== null) { return inputModel; }
+  const { loadConfig } = require('./config');
+  const cfg = loadConfig();
+  return (cfg && cfg.default) ? cfg.default : undefined;
+}
+
+module.exports = { resolveModelInputOrDefault };

package/src/utils/model-validator.js

@@ -7,10 +7,7 @@
  */
 
 const readline = require('readline');
-const { fetchModelsFromProvider } = require('./model-fetcher');
-const { readApiKeyValues } = require('./api-key-store');
 const { loadConfig, saveConfig, getConfigPath } = require('./config');
-const { logger } = require('./logger');
 
 /**
  * Normalize a model ID to include the provider prefix.
@@ -33,54 +30,6 @@ const ALIAS_SEARCH_TERMS = {
   'deepseek': 'deepseek',
 };
 
-/**
- * Validate a direct-API fallback model exists on the provider.
- * Returns silently if valid. On failure: prompts (interactive) or throws (headless).
- *
- * @param {string} resolvedModel - e.g. 'google/gemini-3.1-flash-lite-preview'
- * @param {string} alias - Original alias name (e.g. 'gemini')
- * @param {object} [options]
- * @param {boolean} [options.headless] - If true, throw instead of prompting
- * @returns {Promise<string>} Confirmed model string
- */
-async function validateDirectModel(resolvedModel, alias, options = {}) {
-  const parts = resolvedModel.split('/');
-  if (parts.length < 2) { return resolvedModel; }
-
-  const provider = parts[0];
-  const modelId = parts.slice(1).join('/');
-
-  const keys = readApiKeyValues();
-  const providerKey = keys[provider];
-  if (!providerKey) { return resolvedModel; }
-
-  let models;
-  try {
-    models = await fetchModelsFromProvider(provider, providerKey);
-  } catch (err) {
-    logger.debug({ msg: 'Model fetch failed, skipping validation', error: err.message });
-    return resolvedModel;
-  }
-
-  if (!models || models.length === 0) { return resolvedModel; }
-
-  const found = models.some(m => m.id === resolvedModel || m.id === modelId);
-  if (found) { return resolvedModel; }
-
-  const relevant = filterRelevantModels(models, alias);
-
-  if (options.headless || !process.stdin.isTTY) {
-    const list = relevant.slice(0, 10).map(m => `  ${normalizeModelId(provider, m.id)}`).join('\n');
-    throw new Error(
-      `Model '${modelId}' not found on ${provider} API.\n` +
-      `Available models:\n${list}\n` +
-      `Fix with: amicus setup --add-alias ${alias}=${relevant[0] ? normalizeModelId(provider, relevant[0].id) : 'provider/model'}`
-    );
-  }
-
-  return promptModelSelection(relevant, alias, provider, modelId);
-}
-
 /**
  * Filter models to those relevant to the alias
  * @param {Array<{id: string, name: string}>} models
@@ -101,54 +50,83 @@ function filterRelevantModels(models, alias) {
   return filtered.slice(0, 15);
 }
 
-/** Interactive prompt — ask user to pick from available models */
-async function promptModelSelection(models, alias, provider, failedModelId) {
-  process.stderr.write(`\n  Model '${failedModelId}' not found on ${provider} API.\n`);
-  process.stderr.write('  Available models:\n');
-  models.forEach((m, i) => {
-    const label = (m.name && m.name !== m.id) ? `${m.name} (${m.id})` : m.id;
-    process.stderr.write(`    ${i + 1}. ${label}\n`);
+/**
+ * Interactive alternatives picker for a direct-model miss (#61 Task 6.3, spec
+ * Decision 10). Presents `selectionResult.suggestions` (built upstream by
+ * route-launch.js's buildSuggestions) as a labeled numbered menu and lets the
+ * user pick one, or cancel. Uses the same readline + persist pattern (same
+ * save-with-malformed-config guard) as other model pickers in this module,
+ * adapted to the `{model, gateway, note}` suggestion shape instead of
+ * provider `{id, name}` rows.
+ *
+ * Never auto-selects — even a single suggestion still requires an explicit
+ * pick. Cancellation (empty input, an out-of-range number, or no suggestions
+ * to offer) always throws; the caller (resolveLaunchModel) is expected to
+ * catch and translate that into a "cancelled" stderr message + exit(1).
+ *
+ * @param {{requested: string, suggestions: Array<{model:string, gateway:string, note?:string}>}} selectionResult
+ * @param {string|undefined} alias - alias to persist the choice under, if any
+ * @returns {Promise<{model: string, gateway: string}>}
+ */
+async function promptRouteSelection(selectionResult, alias) {
+  const suggestions = (selectionResult && Array.isArray(selectionResult.suggestions))
+    ? selectionResult.suggestions : [];
+  const requested = selectionResult && selectionResult.requested;
+
+  process.stderr.write(`\n  Model '${requested}' isn't available on the direct API.\n`);
+
+  if (suggestions.length === 0) {
+    process.stderr.write('  No alternatives available.\n\n');
+    throw new Error('Model selection cancelled.');
+  }
+
+  process.stderr.write('  Alternatives:\n');
+  suggestions.forEach((s, i) => {
+    const note = s && s.note ? ` — ${s.note}` : '';
+    process.stderr.write(`    ${i + 1}. ${s && s.model}  [${s && s.gateway}]${note}\n`);
   });
   process.stderr.write('\n');
 
   const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
 
   const answer = await new Promise(resolve => {
-    rl.question(`  Select a model (1-${models.length}) or press Enter to cancel: `, resolve);
+    rl.question(`  Select (1-${suggestions.length}) or Enter to cancel: `, resolve);
   });
   rl.close();
 
   const idx = parseInt(answer, 10) - 1;
-  if (isNaN(idx) || idx < 0 || idx >= models.length) {
+  if (isNaN(idx) || idx < 0 || idx >= suggestions.length) {
     throw new Error('Model selection cancelled.');
   }
 
-  const selected = models[idx];
-  const newModel = normalizeModelId(provider, selected.id);
-
-  let config = loadConfig();
-  if (!config) {
-    const fs = require('fs');
-    const configPath = getConfigPath();
-    if (fs.existsSync(configPath)) {
-      throw new Error(
-        `Cannot save model selection: config file at ${configPath} is malformed. ` +
-        'Fix it manually or run \'amicus setup\'.'
-      );
+  const chosen = suggestions[idx];
+  const newModel = chosen.model;
+
+  if (alias) {
+    let config = loadConfig();
+    if (!config) {
+      const fs = require('fs');
+      const configPath = getConfigPath();
+      if (fs.existsSync(configPath)) {
+        throw new Error(
+          `Cannot save model selection: config file at ${configPath} is malformed. ` +
+          'Fix it manually or run \'amicus setup\'.'
+        );
+      }
+      config = {};
+    }
+    if (!config.aliases) { config.aliases = {}; }
+    config.aliases[alias] = newModel;
+    try {
+      saveConfig(config);
+      process.stderr.write(`  Saved: ${alias} -> ${newModel}\n`);
+    } catch (err) {
+      process.stderr.write(`  Warning: Could not save selection (${err.message}). Using for this session only.\n`);
     }
-    config = {};
-  }
-  if (!config.aliases) { config.aliases = {}; }
-  config.aliases[alias] = newModel;
-  try {
-    saveConfig(config);
-    process.stderr.write(`  Saved: ${alias} → ${newModel}\n`);
-  } catch (err) {
-    process.stderr.write(`  Warning: Could not save selection (${err.message}). Using for this session only.\n`);
   }
-  process.stderr.write(`  (To change later: amicus setup --add-alias ${alias}=...)\n\n`);
+  process.stderr.write('\n');
 
-  return newModel;
+  return { model: newModel, gateway: chosen.gateway };
 }
 
 /**
@@ -204,4 +182,10 @@ async function warnIfNotInCatalog(model) {
   }
 }
 
-module.exports = { validateDirectModel, filterRelevantModels, normalizeModelId, validateAgainstCatalog, warnIfNotInCatalog };
+module.exports = {
+  filterRelevantModels,
+  normalizeModelId,
+  validateAgainstCatalog,
+  warnIfNotInCatalog,
+  promptRouteSelection,
+};

package/src/utils/node-version-guard.js

@@ -0,0 +1,16 @@
+'use strict';
+const MIN_NODE = '22.12.0';
+
+/** @param {string} current @param {string} min @returns {{ok:boolean,message:string|null}} */
+function checkNodeVersion(current, min = MIN_NODE) {
+  const c = current.replace(/^v/, '').split('.').map(Number);
+  const m = min.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((c[i] || 0) > (m[i] || 0)) { return { ok: true, message: null }; }
+    if ((c[i] || 0) < (m[i] || 0)) {
+      return { ok: false, message: `Amicus 3.0 requires Node >=${min}; you are on ${current.replace(/^v/, '')}. Upgrade Node and retry.` };
+    }
+  }
+  return { ok: true, message: null };
+}
+module.exports = { checkNodeVersion, MIN_NODE };

package/src/utils/provider-registry.js

@@ -0,0 +1,57 @@
+/**
+ * Provider-capability registry — the single source of truth for provider
+ * identity, credentials, direct-vs-gateway role, and display names.
+ * The historical maps (PROVIDER_ENV_MAP, PROVIDER_KEY_MAP, KNOWN_PROVIDERS,
+ * PROVIDER_FAMILY_NAMES) are DERIVED from PROVIDERS below so they can never
+ * drift apart again. Leaf module: requires nothing internal (no circular deps).
+ */
+'use strict';
+
+/**
+ * @typedef {Object} ProviderDescriptor
+ * @property {string} id            provider id (namespace)
+ * @property {string} envVar        env var holding the key
+ * @property {string} keyDisplayName human name used in missing-key errors
+ * @property {string} familyName    short name used for optgroup grouping
+ * @property {boolean} direct        can be a DIRECT route target (false for the gateway)
+ * @property {boolean} gateway       is the OpenRouter gateway itself
+ * @property {boolean} hasLiveFetch  has a live GET /models endpoint
+ * @property {string} authJsonKey    key used in OpenCode auth.json
+ */
+
+/** @type {ProviderDescriptor[]} */
+const PROVIDERS = [
+  { id: 'openrouter', envVar: 'OPENROUTER_API_KEY',            keyDisplayName: 'OpenRouter',    familyName: 'OpenRouter', direct: false, gateway: true,  hasLiveFetch: true,  authJsonKey: 'openrouter' },
+  { id: 'google',     envVar: 'GOOGLE_GENERATIVE_AI_API_KEY', keyDisplayName: 'Google Gemini', familyName: 'Google',     direct: true,  gateway: false, hasLiveFetch: true,  authJsonKey: 'google' },
+  { id: 'openai',     envVar: 'OPENAI_API_KEY',               keyDisplayName: 'OpenAI',        familyName: 'OpenAI',     direct: true,  gateway: false, hasLiveFetch: true,  authJsonKey: 'openai' },
+  { id: 'anthropic',  envVar: 'ANTHROPIC_API_KEY',            keyDisplayName: 'Anthropic',     familyName: 'Anthropic',  direct: true,  gateway: false, hasLiveFetch: true,  authJsonKey: 'anthropic' },
+  { id: 'deepseek',   envVar: 'DEEPSEEK_API_KEY',             keyDisplayName: 'DeepSeek',      familyName: 'DeepSeek',   direct: true,  gateway: false, hasLiveFetch: true,  authJsonKey: 'deepseek' },
+];
+
+const _byId = new Map(PROVIDERS.map(p => [p.id, p]));
+
+/** @param {string} id @returns {ProviderDescriptor|undefined} */
+function getProvider(id) { return _byId.get(id); }
+
+/** @param {string} id @returns {boolean} true only for direct-route vendors (never the gateway) */
+function isDirectProvider(id) { const p = _byId.get(id); return !!p && p.direct; }
+
+/** @returns {string[]} ids of direct-route vendors (excludes openrouter) */
+function listDirectProviders() { return PROVIDERS.filter(p => p.direct).map(p => p.id); }
+
+// --- Derived compatibility maps (do not hand-edit; edit PROVIDERS above) ---
+const PROVIDER_ENV_MAP = Object.fromEntries(PROVIDERS.map(p => [p.id, p.envVar]));
+const PROVIDER_KEY_MAP = Object.fromEntries(PROVIDERS.map(p => [p.id, { key: p.envVar, name: p.keyDisplayName }]));
+const KNOWN_PROVIDERS = PROVIDERS.map(p => p.id);
+const PROVIDER_FAMILY_NAMES = Object.fromEntries(PROVIDERS.map(p => [p.id, p.familyName]));
+
+module.exports = {
+  PROVIDERS,
+  getProvider,
+  isDirectProvider,
+  listDirectProviders,
+  PROVIDER_ENV_MAP,
+  PROVIDER_KEY_MAP,
+  KNOWN_PROVIDERS,
+  PROVIDER_FAMILY_NAMES,
+};

package/src/utils/quick-picks.js

@@ -10,7 +10,7 @@
 
 'use strict';
 
-const { getFamilies, toDefaultAliases } = require('./curated-models');
+const { getFamilies, toDefaultAliases, toCanonicalDefault } = require('./curated-models');
 
 const MARKER_RE = /(-preview|-exp|-beta|-latest|:free)+$/;
 
@@ -67,13 +67,21 @@ function resolveQuickPicks(catalog) {
 
 /**
  * Seed map for fresh configs: static defaults overlaid with live family
- * openrouter routes (cardless aliases stay pinned).
+ * routes (cardless aliases stay pinned). The overlaid route is run through
+ * `toCanonicalDefault` so a direct-capable vendor (e.g. google, openai)
+ * lands as bare `vendor/model` (direct-first via the gateway router)
+ * instead of the raw `openrouter/<vendor>/<rest>` pick — otherwise a fresh
+ * `amicus setup` with a live catalog would silently defeat the direct-first
+ * default `toDefaultAliases()` establishes. Gateway-only vendors are
+ * returned unchanged by `toCanonicalDefault`.
  * @returns {Object<string,string>}
  */
 function toLiveSeedAliases(catalog) {
   const seeds = toDefaultAliases();
   for (const r of resolveQuickPicks(catalog || [])) {
-    if (r.source === 'live' && r.routes.openrouter) { seeds[r.alias] = r.routes.openrouter; }
+    if (r.source === 'live' && r.routes.openrouter) {
+      seeds[r.alias] = toCanonicalDefault(r.routes.openrouter);
+    }
   }
   return seeds;
 }

package/src/utils/result-schema-rebuild.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * @module result-schema-rebuild
+ * Rebuild run/wave documents from persisted session directories (as opposed to
+ * `result-schema.js`'s builders, which assemble a document from in-memory
+ * state right after a run/wave finishes). Split out of result-schema.js to
+ * stay under the 300-line size gate (#61 whole-branch review housekeeping) —
+ * re-exported from result-schema.js so every existing caller's import path is
+ * unaffected.
+ *
+ * `buildRunResult`/`buildWaveResult` are required LAZILY inside each function
+ * body (not at module load time) so this file can depend on result-schema.js
+ * without a circular-require ordering hazard: result-schema.js requires this
+ * module too (to re-export these two functions), and a top-level require here
+ * would see result-schema.js's exports mid-assembly (see result-schema.js's
+ * module doc for why abort-result.js already avoids the same trap).
+ */
+
+/**
+ * Rebuild a run document from a persisted session directory.
+ * @param {string} project - Project dir
+ * @param {string} taskId
+ * @returns {object} run document
+ * @throws {Error} if the session does not exist or metadata.json is missing/corrupt
+ */
+function buildRunResultFromSession(project, taskId) {
+  const fs = require('fs');
+  const path = require('path');
+  const { resolveExistingSessionDir } = require('../session-manager');
+  const { buildRunResult } = require('./result-schema');
+  const sessionDir = resolveExistingSessionDir(project, taskId);
+  const metaPath = path.join(sessionDir, 'metadata.json');
+  if (!fs.existsSync(metaPath)) {
+    throw new Error(`Session ${taskId} not found`);
+  }
+  let metadata;
+  try {
+    metadata = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Session ${taskId}: metadata is corrupt (${err.message})`);
+  }
+  const summaryPath = path.join(sessionDir, 'summary.md');
+  const summary = fs.existsSync(summaryPath) ? fs.readFileSync(summaryPath, 'utf-8') : null;
+  return buildRunResult({ taskId, metadata, summary, sessionDir });
+}
+
+/**
+ * Rebuild a wave document. Prefers the stored wave.json (written atomically at
+ * fanout exit); falls back to a live rebuild from leg sessions (e.g. after a
+ * hard kill of the fanout process).
+ * @param {string} project
+ * @param {string} waveId
+ * @returns {object} wave document
+ * @throws {Error} if the wave session does not exist or metadata.json is missing/corrupt
+ */
+function buildWaveResultFromSession(project, waveId) {
+  const fs = require('fs');
+  const path = require('path');
+  const { resolveExistingSessionDir } = require('../session-manager');
+  const { buildRunResult, buildWaveResult } = require('./result-schema');
+  const waveDir = resolveExistingSessionDir(project, waveId);
+  const wavePath = path.join(waveDir, 'wave.json');
+  if (fs.existsSync(wavePath)) {
+    try {
+      return JSON.parse(fs.readFileSync(wavePath, 'utf-8'));
+    } catch {
+      // Corrupt wave.json (e.g. hard-kill mid-write) — fall through to live rebuild
+    }
+  }
+  const metaPath = path.join(waveDir, 'metadata.json');
+  if (!fs.existsSync(metaPath)) {
+    throw new Error(`Wave ${waveId} not found`);
+  }
+  let meta;
+  try {
+    meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Wave ${waveId}: metadata is corrupt (${err.message})`);
+  }
+  const legs = (meta.legs || []).map((legId) => {
+    try { return buildRunResultFromSession(project, legId); }
+    catch (err) {
+      const { logger } = require('./logger');
+      logger.warn('Failed to rebuild leg session; using unknown stub', { legId, error: err.message });
+      return buildRunResult({ taskId: legId, metadata: { status: 'unknown', parentWave: waveId } });
+    }
+  });
+  return buildWaveResult({
+    waveId,
+    legs,
+    promptMeta: meta.promptMeta || null,
+    createdAt: meta.createdAt || null,
+    completedAt: meta.completedAt || null,
+  });
+}
+
+module.exports = { buildRunResultFromSession, buildWaveResultFromSession };

package/src/utils/result-schema.js

@@ -121,9 +121,10 @@ function waveExitCode(waveStatus) {
  * @param {string|null} [opts.createdAt]
  * @param {string|null} [opts.completedAt]
  * @param {string|null} [opts.status] - Override (e.g. 'aborted' on signal); default aggregates legs
+ * @param {string[]} [opts.notices] - Advisory per-leg migration notices (#61 FIX 2); never affects status/exitCode.
  * @returns {object} wave document
  */
-function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null }) {
+function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null, notices = [] }) {
   const { sumWaveUsage } = require('./pricing');
   // Named buckets only (see "COUNTS REMAINDER RULE" above). 'crashed' and
   // 'idle-timeout' legs are intentionally NOT bucketed — they land in `total`
@@ -149,84 +150,13 @@ function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = nul
     completedAt,
     durationMs,
     usage: sumWaveUsage(legs),
+    notices: Array.isArray(notices) ? notices.filter(Boolean) : [],
   };
 }
 
-/**
- * Rebuild a run document from a persisted session directory.
- * @param {string} project - Project dir
- * @param {string} taskId
- * @returns {object} run document
- * @throws {Error} if the session does not exist or metadata.json is missing/corrupt
- */
-function buildRunResultFromSession(project, taskId) {
-  const fs = require('fs');
-  const path = require('path');
-  const { resolveExistingSessionDir } = require('../session-manager');
-  const sessionDir = resolveExistingSessionDir(project, taskId);
-  const metaPath = path.join(sessionDir, 'metadata.json');
-  if (!fs.existsSync(metaPath)) {
-    throw new Error(`Session ${taskId} not found`);
-  }
-  let metadata;
-  try {
-    metadata = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-  } catch (err) {
-    throw new Error(`Session ${taskId}: metadata is corrupt (${err.message})`);
-  }
-  const summaryPath = path.join(sessionDir, 'summary.md');
-  const summary = fs.existsSync(summaryPath) ? fs.readFileSync(summaryPath, 'utf-8') : null;
-  return buildRunResult({ taskId, metadata, summary, sessionDir });
-}
-
-/**
- * Rebuild a wave document. Prefers the stored wave.json (written atomically at
- * fanout exit); falls back to a live rebuild from leg sessions (e.g. after a
- * hard kill of the fanout process).
- * @param {string} project
- * @param {string} waveId
- * @returns {object} wave document
- * @throws {Error} if the wave session does not exist or metadata.json is missing/corrupt
- */
-function buildWaveResultFromSession(project, waveId) {
-  const fs = require('fs');
-  const path = require('path');
-  const { resolveExistingSessionDir } = require('../session-manager');
-  const waveDir = resolveExistingSessionDir(project, waveId);
-  const wavePath = path.join(waveDir, 'wave.json');
-  if (fs.existsSync(wavePath)) {
-    try {
-      return JSON.parse(fs.readFileSync(wavePath, 'utf-8'));
-    } catch {
-      // Corrupt wave.json (e.g. hard-kill mid-write) — fall through to live rebuild
-    }
-  }
-  const metaPath = path.join(waveDir, 'metadata.json');
-  if (!fs.existsSync(metaPath)) {
-    throw new Error(`Wave ${waveId} not found`);
-  }
-  let meta;
-  try {
-    meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-  } catch (err) {
-    throw new Error(`Wave ${waveId}: metadata is corrupt (${err.message})`);
-  }
-  const legs = (meta.legs || []).map((legId) => {
-    try { return buildRunResultFromSession(project, legId); }
-    catch (err) {
-      const { logger } = require('./logger');
-      logger.warn('Failed to rebuild leg session; using unknown stub', { legId, error: err.message });
-      return buildRunResult({ taskId: legId, metadata: { status: 'unknown', parentWave: waveId } });
-    }
-  });
-  return buildWaveResult({
-    waveId,
-    legs,
-    promptMeta: meta.promptMeta || null,
-    createdAt: meta.createdAt || null,
-    completedAt: meta.completedAt || null,
-  });
-}
+// buildRunResultFromSession/buildWaveResultFromSession live in
+// ./result-schema-rebuild.js (size-gate split); re-exported below.
+const { buildRunResultFromSession, buildWaveResultFromSession } = require('./result-schema-rebuild');
 
 /**
  * Build a model-catalog document (`models [--search] [--refresh] --json`).

package/src/utils/route-error.js

@@ -0,0 +1,137 @@
+/**
+ * @module route-error
+ * Shared renderer (#61 Task 6.1): turns a router RouteResult — an error or a
+ * selection_required — into the two surfaces that need to explain it:
+ *   - `toStructuredError` -> the MCP-facing structured object
+ *   - `toCliMessage`      -> a human stderr string for the CLI
+ *
+ * Pure module: no I/O, no requires of launch modules (cli.js/headless.js/
+ * mcp-server.js/etc). Additive only — not imported by any launch path yet;
+ * wiring is a later task in the #61 Integration plan.
+ *
+ * Router error shape (src/utils/model-descriptor.js `routeError()`):
+ *   {kind:'error', type:'model_route_error', field, requested, reason,
+ *    preferredGateway, suggestions}
+ * Selection shape (`selectionRequired()`):
+ *   {kind:'selection_required', requested, suggestions}
+ *
+ * The router's error `reason` is a closed set of 7 values (ROUTE_ERROR_REASONS
+ * below). A `selection_required` result has no `reason` of its own — it is
+ * synthesized here as SELECTION_REQUIRED_REASON, kept in the same documented
+ * REASON_TEXT map rather than invented ad hoc, so callers can treat every
+ * rendered structured error the same way regardless of which RouteResult
+ * produced it.
+ */
+'use strict';
+
+/** The closed set of reasons a router `error` result can carry. */
+const ROUTE_ERROR_REASONS = Object.freeze([
+  'gateway_conflict',
+  'no_openrouter_key',
+  'no_direct_integration',
+  'no_direct_key',
+  'no_key_for_vendor',
+  'model_not_found',
+  'invalid_descriptor',
+]);
+
+/**
+ * Synthesized reason for a `selection_required` RouteResult. Deliberately
+ * distinct from 'model_not_found': the model wasn't missing, it was ambiguous
+ * (multiple catalog candidates) and the router is asking the caller to pick.
+ */
+const SELECTION_REQUIRED_REASON = 'selection_required';
+
+/** One-line, non-technical explanation of what went wrong, keyed by reason. */
+const REASON_TEXT = Object.freeze({
+  gateway_conflict: 'This model must go through OpenRouter, but --gateway direct was forced.',
+  no_openrouter_key: 'No OpenRouter API key is configured.',
+  no_direct_integration: 'This vendor has no direct API integration.',
+  no_direct_key: "No API key is configured for this vendor's direct API.",
+  no_key_for_vendor: 'No API key was found for this vendor via any gateway.',
+  model_not_found: 'The requested model was not found in the catalog.',
+  invalid_descriptor: 'The model identifier could not be parsed.',
+  [SELECTION_REQUIRED_REASON]: 'Multiple models match your request; a specific one must be selected.',
+});
+
+/** Copy-paste fix guidance appended after the REASON_TEXT sentence. */
+const FIX_HINTS = Object.freeze({
+  gateway_conflict: "An openrouter/... model can't be forced with --gateway direct.",
+  no_openrouter_key: 'Set OPENROUTER_API_KEY, or use --gateway direct.',
+  no_direct_integration: 'This vendor has no direct integration; drop --gateway direct.',
+  no_direct_key: 'Add a key with `amicus key <vendor> <key>`, or use --gateway openrouter.',
+  no_key_for_vendor: 'Add a provider key or an OpenRouter key.',
+  model_not_found: 'Run `amicus models --refresh`, or pass --no-validate-model.',
+  invalid_descriptor: 'Use a vendor/model id or a configured alias.',
+  [SELECTION_REQUIRED_REASON]: 'Pick one of the suggestions below, or narrow the model id.',
+});
+
+/** @returns {Array} suggestions normalized to an array. */
+function normalizeSuggestions(suggestions) {
+  return Array.isArray(suggestions) ? suggestions : [];
+}
+
+/**
+ * Render a router RouteResult (error or selection_required) into the
+ * MCP-facing structured object. Pass-through/normalize for an `error` result;
+ * synthesized for a `selection_required` result.
+ * @param {object} result a RouteResult with kind 'error' or 'selection_required'
+ * @returns {{type:'model_route_error', field:string, requested:*, reason:string,
+ *   preferredGateway:(string|null), suggestions:Array}}
+ */
+function toStructuredError(result) {
+  const r = result || {};
+  if (r.kind === 'selection_required') {
+    return {
+      type: 'model_route_error',
+      field: 'model',
+      requested: r.requested,
+      reason: SELECTION_REQUIRED_REASON,
+      preferredGateway: null,
+      suggestions: normalizeSuggestions(r.suggestions),
+    };
+  }
+  // Router `error` result (kind:'error'): pass through/normalize.
+  return {
+    type: 'model_route_error',
+    field: r.field || 'model',
+    requested: r.requested,
+    reason: r.reason,
+    preferredGateway: r.preferredGateway || null,
+    suggestions: normalizeSuggestions(r.suggestions),
+  };
+}
+
+/**
+ * Render a router RouteResult into a human stderr message: the reason's
+ * one-line explanation, an optional "Did you mean" suggestion list, and a
+ * fix hint.
+ * @param {object} result a RouteResult with kind 'error' or 'selection_required'
+ * @returns {string}
+ */
+function toCliMessage(result) {
+  const err = toStructuredError(result);
+  const sentence = REASON_TEXT[err.reason] || `Model routing error (${err.reason}).`;
+  const lines = [err.requested ? `${sentence} (requested "${err.requested}")` : sentence];
+
+  if (err.suggestions.length > 0) {
+    lines.push('Did you mean:');
+    for (const s of err.suggestions) {
+      const note = s && s.note ? ` — ${s.note}` : '';
+      lines.push(`  - ${s && s.model} (${s && s.gateway})${note}`);
+    }
+  }
+
+  const hint = FIX_HINTS[err.reason];
+  if (hint) { lines.push(hint); }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  toStructuredError,
+  toCliMessage,
+  REASON_TEXT,
+  ROUTE_ERROR_REASONS,
+  SELECTION_REQUIRED_REASON,
+};