amicus 3.0.0 → 3.1.0

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,
+};

package/src/utils/route-launch.js

@@ -0,0 +1,179 @@
+/**
+ * Route-launch views (#61 gateway routing integration, Task 4.2).
+ *
+ * Additive, read-only helpers consumed by Task 4.4's resolveRouteForLaunch
+ * (not wired into any launch path yet). Pure-ish: all I/O goes through the
+ * stubbable api-key-store / auth-json / model-catalog modules.
+ */
+'use strict';
+
+const { readApiKeys } = require('./api-key-store');
+const { readAuthJsonKeys } = require('./auth-json');
+const { KNOWN_PROVIDERS } = require('./provider-registry');
+
+/**
+ * Per-provider key presence across BOTH sources: env/.env (readApiKeys) and
+ * OpenCode's auth.json (readAuthJsonKeys). True if either source has a key
+ * for that provider (Foundation carry-forward, Decision 5).
+ * @returns {Object<string,boolean>} map of provider id -> key present
+ */
+function buildLaunchKeys() {
+  const env = readApiKeys(); // {openrouter:bool, google:bool, openai:bool, anthropic:bool, deepseek:bool}
+  const authKeys = readAuthJsonKeys(); // {provider:string,...} (only providers with keys)
+  const out = {};
+  for (const p of KNOWN_PROVIDERS) {
+    out[p] = !!env[p] || !!authKeys[p];
+  }
+  return out;
+}
+
+/**
+ * Thin wrapper over model-catalog.getCatalogInfo() for route-resolution
+ * callers that only need the models list and the last-refresh error, not the
+ * full cache metadata. Never throws: a catalog error resolves to an empty
+ * list with a sentinel error string.
+ * @returns {Promise<{models: Array, lastRefreshError: string|null}>}
+ */
+async function getRouteCatalogInfo() {
+  // Lazy-required so jest.doMock('./model-catalog', ...) can intercept it
+  // per-test, matching the pattern model-catalog.js itself uses for its deps.
+  const { getCatalogInfo } = require('./model-catalog');
+  try {
+    const info = await getCatalogInfo();
+    return { models: info.models || [], lastRefreshError: info.lastRefreshError || null };
+  } catch {
+    return { models: [], lastRefreshError: 'catalog-unavailable' };
+  }
+}
+
+/** Module version stamped onto `resolved` results' provenance (carry-forward). */
+const ROUTE_VERSION = 1;
+
+/**
+ * Build up to ~6 labeled alternatives for a `selection_required` RouteResult
+ * (#61 Task 6.3, spec Decision 10). Pure: reads only the already-parsed
+ * descriptor plus the live keys/catalogInfo the caller already assembled.
+ *
+ * Two categories, in order:
+ *  1. The SAME model via OpenRouter — only when an OpenRouter key is present
+ *     AND the OR-namespaced id (`openrouter/<vendor>/<model>`) is actually
+ *     present in the catalog (never suggest an id we can't confirm exists).
+ *  2. Up to 5 OTHER models in the same direct vendor namespace (ids starting
+ *     `<vendor>/`, excluding the requested id itself and excluding any
+ *     `openrouter/`-prefixed rows, which share the `<vendor>/` prefix check
+ *     only when vendor === 'openrouter' and are filtered out defensively).
+ *
+ * @param {{vendor?: string, model?: string}} descriptor parsed Descriptor for
+ *   the request that produced the selection_required (canonical or
+ *   openrouter-literal — both carry vendor/model)
+ * @param {Object<string,boolean>} keys per-provider key-presence map (buildLaunchKeys() shape)
+ * @param {{models: Array<{id:string}>}} catalogInfo
+ * @returns {Array<{model:string, gateway:string, note:string}>}
+ */
+function buildSuggestions(descriptor, keys, catalogInfo) {
+  const suggestions = [];
+  const vendor = descriptor && descriptor.vendor;
+  const model = descriptor && descriptor.model;
+  if (!vendor || !model) { return suggestions; }
+
+  const models = (catalogInfo && Array.isArray(catalogInfo.models)) ? catalogInfo.models : [];
+  const requestedDirectId = `${vendor}/${model}`;
+
+  if (keys && keys.openrouter) {
+    const orId = `openrouter/${vendor}/${model}`;
+    if (models.some(m => m && m.id === orId)) {
+      suggestions.push({ model: orId, gateway: 'openrouter', note: 'same model via OpenRouter' });
+    }
+  }
+
+  const nsPrefix = `${vendor}/`;
+  const sameVendor = models.filter(m =>
+    m && typeof m.id === 'string' &&
+    m.id.startsWith(nsPrefix) &&
+    !m.id.startsWith('openrouter/') &&
+    m.id !== requestedDirectId
+  ).slice(0, 5);
+  for (const m of sameVendor) {
+    suggestions.push({ model: m.id, gateway: 'direct', note: `${vendor} model` });
+  }
+
+  return suggestions.slice(0, 6);
+}
+
+/**
+ * One-time per-vendor notice when auto-routing migrates a both-key holder off
+ * OpenRouter onto direct (#61 Task 5.1 — visible-migration guarantee: never
+ * silent). Advisory only — never changes the routing decision, and a failed
+ * persist (markMigrationNotified is itself best-effort) never blocks the
+ * launch. Fires only when ALL of these hold:
+ *  - the result actually resolved to gateway 'direct'
+ *  - the caller did NOT explicitly force a gateway (gatewayMode === 'auto');
+ *    an explicit --gateway direct means the user chose direct, no notice
+ *  - the descriptor is not itself an explicit `openrouter/...` literal
+ *  - the user holds an OpenRouter key (otherwise nothing is being migrated
+ *    FROM)
+ *  - this vendor hasn't already been notified (getRoutingConfig().migration_notified)
+ * @param {{result:object, descriptor:object, gatewayMode:string, keys:object}} args
+ * @returns {object} the (possibly mutated) result
+ */
+function maybeMigrationNotice({ result, descriptor, gatewayMode, keys }) {
+  if (result.kind !== 'resolved' || result.gateway !== 'direct') { return result; }
+  if (gatewayMode !== 'auto') { return result; }
+  if (descriptor.isExplicitOpenRouter) { return result; }
+  if (!keys.openrouter) { return result; }
+  try {
+    // Lazy-required so jest.doMock('./config', ...) can intercept it per-test.
+    const { getRoutingConfig, markMigrationNotified } = require('./config');
+    if (getRoutingConfig().migration_notified[descriptor.vendor]) { return result; }
+    const notice = `Routing ${descriptor.vendor} via direct API (previously OpenRouter). ` +
+      'Set routing.prefer: "openrouter" (or use --gateway openrouter) to restore.';
+    result.notice = result.notice ? `${result.notice} ${notice}` : notice;
+    markMigrationNotified(descriptor.vendor);
+  } catch (_err) {
+    // Advisory only: never let a lookup/persist failure change the routing
+    // decision or block the launch.
+  }
+  return result;
+}
+
+/**
+ * Bridge: alias -> descriptor -> resolveRoute (Task 4.4).
+ * Resolves a raw model string to a Descriptor — if it is a known no-slash
+ * alias (per getEffectiveAliases()), its concrete id is parsed instead, so an
+ * alias pointing at an `openrouter/...` value is treated as an explicit,
+ * force-OR literal while an alias pointing at a bare `vendor/model` is
+ * policy-routed like any other canonical id. Assembles live key/catalog state
+ * and delegates the actual decision to the pure gateway-router. Additive:
+ * not wired into any launch path yet.
+ * @param {{model:string, gatewayMode:string, source:string, allowSelection?:boolean, validateModel?:boolean}} opts
+ * @returns {Promise<object>} RouteResult (resolved | selection_required | error)
+ */
+async function resolveRouteForLaunch({ model, gatewayMode, source, allowSelection, validateModel }) {
+  // Lazy-required so jest.doMock('./config' | './model-descriptor' | './gateway-router', ...)
+  // can intercept them per-test, matching the pattern already used above for model-catalog.
+  const { getEffectiveAliases } = require('./config');
+  const { parseDescriptor } = require('./model-descriptor');
+  const { resolveRoute } = require('./gateway-router');
+  const aliases = getEffectiveAliases();
+  const concrete = (typeof model === 'string' && !model.includes('/') && aliases[model]) ? aliases[model] : model;
+  const descriptor = parseDescriptor(concrete, { aliases });
+  const keys = buildLaunchKeys();
+  // Skip the catalog fetch entirely under --no-validate-model: gateway-router's
+  // catalogGate short-circuits to { ok:true } as soon as validateModel === false,
+  // never consulting catalogInfo, so fetching it here would be wasted
+  // latency/network (and can hit the network on a cold cache) for no benefit.
+  // Strict === false (not just falsy) so this stays in lockstep with catalogGate's
+  // own `=== false` guard: any other value (incl. an omitted flag) still fetches,
+  // so a caller can never skip the fetch while the gate still classifies against it.
+  const catalogInfo = validateModel === false ? { models: [], lastRefreshError: null } : await getRouteCatalogInfo();
+  let result = resolveRoute({ descriptor, source, gatewayMode, allowSelection, validateModel, keys, catalogInfo });
+  if (result.kind === 'resolved') {
+    result.provenance = { ...result.provenance, resolutionVersion: ROUTE_VERSION };
+    result = maybeMigrationNotice({ result, descriptor, gatewayMode, keys });
+  } else if (result.kind === 'selection_required') {
+    result.suggestions = buildSuggestions(descriptor, keys, catalogInfo);
+  }
+  return result;
+}
+
+module.exports = { buildLaunchKeys, getRouteCatalogInfo, resolveRouteForLaunch, buildSuggestions, ROUTE_VERSION };