amicus 3.0.0 → 3.1.1

package/src/cli.js

@@ -18,6 +18,7 @@ const {
 } = require('./utils/validators');
 const { resolvePromptSource } = require('./utils/prompt-source');
 const { logger } = require('./utils/logger');
+const { GATEWAY_MODES } = require('./utils/model-descriptor');
 
 /**
  * Default values per spec §4.1
@@ -137,6 +138,7 @@ function isBooleanFlag(key) {
      'html',                 // council report: emit a self-contained HTML page
      'md',                   // council report: emit Markdown (default)
      'fix',                  // doctor: self-heal fixable checks in place (#56)
+     'strict',               // models --check: exit non-zero on curated per-gateway drift (#gwid Task 6)
    ];
   return booleanFlags.includes(key);
 }
@@ -245,6 +247,15 @@ function validateStartArgs(args) {
     }
   }
 
+  // Validate --gateway (if provided) — #61 Task 7.1. resolveGatewayMode()
+  // already treats any non-'direct'/'openrouter' string as a pass-through
+  // (effectively silent auto fallback), so this pre-flight check exists
+  // purely to catch typos with a clear error instead of letting them slip
+  // through unnoticed.
+  if (args.gateway !== undefined && !GATEWAY_MODES.includes(args.gateway)) {
+    return { valid: false, error: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` };
+  }
+
   // Validate MCP spec format (if provided)
   const mcpCheck = validateMcpSpec(args.mcp);
   if (!mcpCheck.valid) {
@@ -401,6 +412,7 @@ Options for 'start':
   --exclude-mcp <name>           Exclude specific MCP server (repeatable)
   --validate-model             (Deprecated: validation is on by default)
   --no-validate-model          Skip model-catalog validation before launch
+  --gateway <mode>             Routing: auto (direct-first), direct, or openrouter
   --position <pos>             Window position: right (default), left, center
 `,
   fanout: `
@@ -415,6 +427,7 @@ Options for 'fanout':
   --json                       Emit the wave result as stable JSON on stdout
   --max-cost <$>               Refuse the wave if the estimated total exceeds $ (soft ceiling)
   --no-cost-gate               Disable the budget gate (per-$/Mtok threshold + ceiling) for this run
+  --gateway <mode>              Routing: auto (direct-first), direct, or openrouter
   Shared per-leg knobs: --agent, --thinking, --timeout, --summary-length,
   --no-context, --context-*, --mcp*, --no-validate-model, --cwd
   Exit codes: 0 all legs complete, 2 partial, 1 none complete / hard failure
@@ -424,6 +437,9 @@ Options for 'models':
   --search <q>                 Filter by substring over model id and name
   --refresh                    Force-refresh the catalog from provider APIs
   --check                      Audit aliases against the catalog (exit = stale count)
+  --strict                     With --check: also exit non-zero on curated
+                               per-gateway drift (stale/divergent direct or
+                               openrouter forms). Informational without it.
   --json                       Machine-readable output
 `,
   list: `
@@ -456,6 +472,7 @@ Options for 'continue':
   <task_id>                    Required. Session to build on (positional)
   --prompt <text>              Required. Briefing for the new session
   --model <model>              Optional. Override the model (alias or provider/model)
+  --gateway <mode>             Routing when --model is given: auto (direct-first), direct, or openrouter
   --cwd <path>                 Project directory (default: cwd)
   --no-ui                      Run without GUI (autonomous mode)
   --json                       With --no-ui: emit the run result as stable JSON

package/src/mcp-server.js

@@ -4,7 +4,6 @@ const path = require('path');
 const { writeFileAtomic } = require('./utils/atomic-write');
 const { spawn } = require('child_process');
 const { getTools, getGuideText } = require('./mcp-tools');
-const { tryResolveModel } = require('./utils/config');
 const os = require('os');
 const { logger } = require('./utils/logger');
 const { safeSessionDir } = require('./utils/validators');
@@ -241,7 +240,7 @@ function spawnSidecarProcess(args, sessionDir) {
 /** Tool handler implementations */
 const handlers = {
   async amicus_start(input, project, mcpServer) {
-    // Validate all inputs before any session creation
+    // Validate non-model inputs (prompt/timeout/agent) before any session creation.
     const { validateStartInputs } = require('./utils/input-validators');
     const validation = validateStartInputs(input);
     if (!validation.valid) {
@@ -250,7 +249,40 @@ const handlers = {
         content: [{ type: 'text', text: JSON.stringify(validation.error) }],
       };
     }
-    const resolvedModel = validation.resolvedModel;
+
+    // Model routing (#61 Task 6.2): route through the gateway router for MCP
+    // parity with the CLI's resolveLaunchModel (start-helpers.js). Unlike the
+    // CLI, this handler must never process.exit — the MCP server is long-lived
+    // and serves many tool calls — so a routing failure returns a structured
+    // model_route_error response instead.
+    //
+    // Default resolution mirrors resolveLaunchModel: an omitted input.model
+    // falls back to the configured default before hitting the router, so
+    // "no model, no default" produces a clean invalid_descriptor structured
+    // error (via the router) rather than a crash. Shared with the CLI's
+    // resolveLaunchModel (start-helpers.js) via model-input-default.js.
+    const { resolveGatewayMode } = require('./utils/config');
+    const { resolveRouteForLaunch } = require('./utils/route-launch');
+    const { toStructuredError } = require('./utils/route-error');
+    const { resolveModelInputOrDefault } = require('./utils/model-input-default');
+
+    const modelInput = resolveModelInputOrDefault(input.model);
+    // input.gateway is now exposed by the MCP tool schema (#61 Task 7.2);
+    // resolveGatewayMode(undefined) falls back to config routing.prefer / 'auto'.
+    const routeResult = await resolveRouteForLaunch({
+      model: modelInput,
+      gatewayMode: resolveGatewayMode(input.gateway),
+      source: 'mcp',
+      allowSelection: false,
+      validateModel: true,
+    });
+    if (routeResult.kind !== 'resolved') {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(toStructuredError(routeResult)) }],
+      };
+    }
+    const resolvedModel = routeResult.executableId;
 
     const cwd = project || getProjectDir(input.project);
     const { generateTaskId } = require('./sidecar/start');
@@ -268,7 +300,9 @@ const handlers = {
     const briefingPath = path.join(sessionDir, 'briefing.md');
     const detectedClient = detectClient(mcpServer);
     const args = ['start', '--prompt-file', briefingPath, '--task-id', taskId, '--client', detectedClient];
-    if (resolvedModel) { args.push('--model', resolvedModel); }
+    // resolvedModel is always defined here — a routing failure already
+    // returned above — and is the router's executableId, not the raw alias.
+    args.push('--model', resolvedModel);
     const agent = (input.noUi && (!input.agent || input.agent.toLowerCase() === 'chat'))
       ? 'build' : input.agent;
     if (agent) { args.push('--agent', agent); }
@@ -296,7 +330,8 @@ const handlers = {
         const { runHeadless } = require('./headless');
         const { generateFoldNonce } = require('./utils/fold-marker');
         const { finalizeHeadlessResult } = require('./sidecar/session-finalize');
-        // resolvedModel is already available from validateStartInputs() above
+        // resolvedModel (the router's executableId) is already available from
+        // the model-routing step above
 
         // #47: the shared OpenCode server is shared across projects, so the
         // session must be created scoped to the resolved project directory
@@ -441,7 +476,15 @@ const handlers = {
           taskId, status: 'running', mode: 'headless',
           message: 'Amicus started in headless mode. Use amicus_status to check progress.',
         });
-        return { content: [{ type: 'text', text: body }, { type: 'text', text: HEADLESS_START_REMINDER }] };
+        // FIX 2 (#61 whole-branch review): surface the router's one-shot
+        // migration notice here too — resolveRouteForLaunch already burned
+        // the migration_notified flag for this vendor when it built
+        // routeResult above, so this is the only chance to show it on the
+        // shared-server path (no CLI stderr exists for an MCP caller).
+        const sharedServerContent = [{ type: 'text', text: body }];
+        if (routeResult.notice) { sharedServerContent.push({ type: 'text', text: routeResult.notice }); }
+        sharedServerContent.push({ type: 'text', text: HEADLESS_START_REMINDER });
+        return { content: sharedServerContent };
       } catch (err) {
         logger.warn('Shared server path failed, falling back to spawn', { error: err.message });
         // Clean up partial shared server state before falling through
@@ -490,10 +533,16 @@ const handlers = {
         'Then wait for the user to tell you. Use amicus_read to get results once they confirm.';
 
     const body = JSON.stringify({ taskId, status: 'running', mode, message });
+    // FIX 2 (#61 whole-branch review): the spawn path never touches stderr of
+    // the CLI child that will do the routing print — this handler already
+    // resolved the route in-process above, so surface its notice here.
+    const spawnContent = [{ type: 'text', text: body }];
+    if (routeResult.notice) { spawnContent.push({ type: 'text', text: routeResult.notice }); }
     if (isHeadless) {
-      return { content: [{ type: 'text', text: body }, { type: 'text', text: HEADLESS_START_REMINDER }] };
+      spawnContent.push({ type: 'text', text: HEADLESS_START_REMINDER });
+      return { content: spawnContent };
     }
-    return textResult(body);
+    return { content: spawnContent };
   },
 
   async amicus_status(input, project) {
@@ -795,11 +844,37 @@ const handlers = {
   },
 
   async amicus_continue(input, project, mcpServer) {
+    // Model routing parity with amicus_start (#61 whole-branch review FIX 3,
+    // Task 6.2 follow-up): an explicit --model on continue used to be
+    // pre-checked only with the legacy tryResolveModel (alias-existence-only),
+    // so an unroutable model (e.g. a gateway-only vendor with no OpenRouter
+    // key) spawned a child that then died opaquely trying to launch it.
+    // Route it through the SAME gateway router amicus_start uses instead, and
+    // return the same structured model_route_error on failure — never spawn.
+    // The no-`--model` inherit-prior-session-model path is UNCHANGED: nothing
+    // below runs, and handleContinue reuses the prior concrete model verbatim.
+    let resolvedModel;
     if (input.model) {
-      const modelCheck = tryResolveModel(input.model);
-      if (modelCheck.error) {
-        return textResult(modelCheck.error, true);
+      const { resolveGatewayMode } = require('./utils/config');
+      const { resolveRouteForLaunch } = require('./utils/route-launch');
+      const { toStructuredError } = require('./utils/route-error');
+      const { resolveModelInputOrDefault } = require('./utils/model-input-default');
+
+      const modelInput = resolveModelInputOrDefault(input.model);
+      const routeResult = await resolveRouteForLaunch({
+        model: modelInput,
+        gatewayMode: resolveGatewayMode(input.gateway),
+        source: 'mcp',
+        allowSelection: false,
+        validateModel: true,
+      });
+      if (routeResult.kind !== 'resolved') {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify(toStructuredError(routeResult)) }],
+        };
       }
+      resolvedModel = routeResult.executableId;
     }
 
     const cwd = project || getProjectDir(input.project);
@@ -814,7 +889,15 @@ const handlers = {
     const briefingPath = path.join(sessionDir, 'briefing.md');
     const args = ['continue', input.taskId, '--prompt-file', briefingPath,
       '--task-id', newTaskId, '--client', detectClient(mcpServer), '--cwd', cwd];
-    if (input.model) { args.push('--model', input.model); }
+    // resolvedModel is the router's executableId (never the raw alias) — a
+    // routing failure already returned above, so this is only reached when
+    // input.model was absent (resolvedModel stays undefined) or resolved.
+    if (resolvedModel) { args.push('--model', resolvedModel); }
+    // #61 Task 7.3: forward the caller's gateway preference to the spawned
+    // CLI child too — handleContinue still does its OWN routing (it's the
+    // one wiring --model/--gateway into a resolved session), this just keeps
+    // the child's own resolution consistent with what was already decided.
+    if (input.gateway) { args.push('--gateway', input.gateway); }
     if (input.noUi) { args.push('--no-ui', '--agent', 'build'); }
     if (input.timeout) { args.push('--timeout', String(input.timeout)); }
     if (input.contextTurns)     { args.push('--context-turns', String(input.contextTurns)); }
@@ -955,6 +1038,10 @@ const handlers = {
     ];
     const agent = input.agent || 'Build';
     args.push('--agent', agent);
+    // #61 Task 7.3: forward the caller's gateway preference to the spawned
+    // CLI child, which routes each leg's model (piece 2) — unlike
+    // amicus_start, this handler never resolves any leg's route itself.
+    if (input.gateway) { args.push('--gateway', input.gateway); }
     if (input.thinking)      { args.push('--thinking', input.thinking); }
     if (input.timeout)       { args.push('--timeout', String(input.timeout)); }
     if (input.summaryLength) { args.push('--summary-length', input.summaryLength); }

package/src/mcp-tools.js

@@ -10,6 +10,7 @@
 const { z } = require('zod');
 const { formatAliasNames } = require('./utils/config');
 const { READ_CAP_BYTES } = require('./utils/read-slice');
+const { GATEWAY_MODES } = require('./utils/model-descriptor');
 
 /** Zod pattern for safe task IDs (alphanumeric, hyphens, underscores only) */
 const safeTaskId = z.string().regex(
@@ -55,9 +56,15 @@ function getTools() {
       ' Pass includeContext: false when the briefing is fully self-contained.',
     inputSchema: {
       model: safeModel.optional().describe(
-        `Short alias (${aliasNames}) or full provider/model ID. ` +
+        `Short alias (${aliasNames}) or full model ID ` +
+        '(bare provider/model is canonical and routes direct-first, e.g. anthropic/claude-opus-4.8; ' +
+        'openrouter/provider/model forces OpenRouter). ' +
         'If omitted, uses the configured default. Call amicus_guide to see all aliases.'
       ),
+      gateway: z.enum(GATEWAY_MODES).optional().describe(
+        'Routing preference: auto (direct-first, default), direct (require a ' +
+        'direct provider key), or openrouter (force OpenRouter).'
+      ),
       prompt: z.string().describe(
         'Detailed task briefing. Include: objective, background, ' +
         'files of interest, success criteria.'
@@ -251,7 +258,13 @@ function getTools() {
         'New task description for the continuation.'
       ),
       model: safeModel.optional().describe(
-        `Override model — short alias (${aliasNames}) or full provider/model ID. Defaults to the original session's model.`
+        `Override model — short alias (${aliasNames}) or full model ID. Bare provider/model routes ` +
+        'direct-first (canonical); openrouter/provider/model forces OpenRouter. Defaults to the ' +
+        "original session's model."
+      ),
+      gateway: z.enum(GATEWAY_MODES).optional().describe(
+        'Routing preference: auto (direct-first, default), direct (require a ' +
+        'direct provider key), or openrouter (force OpenRouter).'
       ),
       noUi: z.boolean().optional().default(false).describe(
         'Run headless. Default false (opens Electron window).'
@@ -308,13 +321,19 @@ function getTools() {
       'inside). Each leg is also an ordinary session readable by taskId.',
     inputSchema: {
       models: z.array(safeModel).min(1).max(10).optional().describe(
-        `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full provider/model IDs. Duplicates allowed. Omit when using 'council'.`
+        `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full model IDs — ` +
+        'bare provider/model routes direct-first (canonical), openrouter/provider/model forces ' +
+        "OpenRouter. Duplicates allowed. Omit when using 'council'."
       ),
       council: z.string().optional().describe(
         "Run a saved council, or a built-in bench ('free', 'budget', 'frontier'), instead of 'models'. " +
         "Expands to the council's members; a saved council of the same name shadows a built-in. " +
         'Mutually exclusive with \'models\'.'
       ),
+      gateway: z.enum(GATEWAY_MODES).optional().describe(
+        'Routing preference: auto (direct-first, default), direct (require a ' +
+        'direct provider key), or openrouter (force OpenRouter).'
+      ),
       prompt: z.string().describe(
         'The briefing sent to every model. Self-contained briefings work best (set includeContext false).'
       ),
@@ -492,7 +511,10 @@ Include: Objective, Background, Files of interest, Success criteria, Constraints
 |-------|-------|
 ${aliasRows}
 
-Or use full IDs in provider/model format (e.g., openrouter/provider/model-id).
+Or use a full model ID. Bare \`provider/model\` (e.g. anthropic/claude-opus-4.8) is the canonical,
+policy-routed form — it routes direct-first (your direct provider key if configured, else
+OpenRouter). \`openrouter/provider/model\` is an explicit override that forces OpenRouter. The
+\`gateway\` param (or \`routing.prefer\` in config.json) controls this per call or globally.
 Run amicus_setup to configure defaults and add custom aliases.
 
 ## Session Matching

package/src/opencode-client.js

@@ -400,6 +400,10 @@ async function getSessionStatus(client, sessionId, directory) {
  * @param {AbortSignal} [options.signal] - Abort signal to stop server
  * @param {object} [options.mcp] - MCP server configurations
  * @param {string} [options.model] - Default model
+ * @param {string[]} [options.models] - Resolved executable id(s) actually launched (#61 Task
+ *   4.6/7.3 sole-input invariant) — a multi-model shared server (fanout) has no single
+ *   default model, so ALL of them register in provider.models via this instead of `model`.
+ *   Takes precedence over the `options.model` single-id fallback when non-empty.
  * @param {string} [options.client] - Client type ('cowork', 'code-local', etc.)
  * @param {string} [options.systemPrompt] - System prompt to set on agent config (hidden from UI)
  * @param {string} [options.agentName] - Agent to set systemPrompt on (default: 'chat')
@@ -473,9 +477,17 @@ function buildServerOptions(options = {}) {
   }
 
   // Sync sidecar aliases into OpenCode's provider.models so the UI
-  // model picker shows all configured models (single source of truth).
+  // model picker shows all configured models (single source of truth),
+  // and register the actually-resolved launch route's provider so it
+  // always matches config.model (the "sole input" invariant — see #61).
+  // A multi-model shared server (fanout, #61 Task 7.3) has no single
+  // config.model — options.models carries EVERY leg's resolved id instead,
+  // and takes precedence over the single-id options.model fallback.
   const { buildProviderModels } = require('./utils/config');
-  config.provider = buildProviderModels();
+  const resolvedForProvider = (Array.isArray(options.models) && options.models.length)
+    ? options.models
+    : (options.model ? [options.model] : []);
+  config.provider = buildProviderModels(resolvedForProvider);
 
   // Register custom 'chat' agent: reads auto-approved, writes/bash require permission
   const chatAgent = {
@@ -605,6 +617,10 @@ function buildServerHandle(sdkServer, deps = {}) {
  * @param {AbortSignal} [options.signal] - Abort signal to stop server
  * @param {object} [options.mcp] - MCP server configurations
  * @param {string} [options.model] - Default model
+ * @param {string[]} [options.models] - Resolved executable id(s) actually launched (#61 Task
+ *   4.6/7.3 sole-input invariant) — a multi-model shared server (fanout) has no single
+ *   default model, so ALL of them register in provider.models via this instead of `model`.
+ *   Takes precedence over the `options.model` single-id fallback when non-empty.
  * @param {string} [options.client] - Client type ('cowork', 'code-local', etc.)
  * @returns {Promise<{client: object, server: {url: string, close: Function}}>}
  */

package/src/sidecar/continue.js

@@ -88,7 +88,7 @@ Build on the previous sidecar's findings. The user wants to continue or extend t
 
 /** Create session metadata for continuation */
 function createContinueSessionMetadata(taskId, project, options, oldTaskId) {
-  const { model, briefing, headless, agent } = options;
+  const { model, briefing, headless, agent, gateway, resolutionVersion } = options;
 
   const sessionDir = SessionPaths.sessionDir(project, taskId);
   fs.mkdirSync(sessionDir, { recursive: true });
@@ -104,6 +104,12 @@ function createContinueSessionMetadata(taskId, project, options, oldTaskId) {
     createdAt: new Date().toISOString(),
     continuesFrom: oldTaskId
   };
+  // #61 Task 5.2 (best-effort provenance): only present when THIS continue
+  // call freshly routed an explicit --model through the gateway router — the
+  // no-model inherit path never re-resolves, so gateway/resolutionVersion
+  // stay undefined there and are simply omitted (never written as `undefined`).
+  if (gateway !== undefined) { metadata.gateway = gateway; }
+  if (resolutionVersion !== undefined) { metadata.resolutionVersion = resolutionVersion; }
 
   writeFileAtomic(SessionPaths.metadataFile(sessionDir), JSON.stringify(metadata, null, 2));
 
@@ -123,7 +129,8 @@ async function continueSidecar(options) {
     headless = false,
     timeout = 15,
     agent,
-    mcp, mcpConfig, client, noMcp, excludeMcp, json = false
+    mcp, mcpConfig, client, noMcp, excludeMcp, json = false,
+    gateway, resolutionVersion, // #61 Task 5.2 (best-effort provenance)
   } = options;
 
   // Load previous session data
@@ -168,7 +175,7 @@ async function continueSidecar(options) {
   logger.info('New continuation task', { newTaskId, oldTaskId });
 
   const sessionDir = createContinueSessionMetadata(newTaskId, project, {
-    model, briefing, headless, agent: effectiveAgent
+    model, briefing, headless, agent: effectiveAgent, gateway, resolutionVersion,
   }, oldTaskId);
 
   // Lock the NEW continuation session dir too — not just the previous one — so a

package/src/sidecar/fanout-leg.js

@@ -35,6 +35,31 @@ function writeLegPatch(legDir, patch) {
   return merged;
 }
 
+/**
+ * Synthesize an error run document for a leg whose MODEL never routed (#61
+ * Task 7.3) — the gateway router returned `error` (or, in principle,
+ * `selection_required`) for this leg's requested model before any session was
+ * created, so there is nothing to run. Mirrors the shape runLeg's own catch
+ * branch already produces for "setup threw before the session dir existed":
+ * no legDir, no summary, an `error` status — this never touches the shared
+ * server or the Promise.all in runFanout, so it can never sink a sibling leg.
+ * @param {{leg: {modelInput: string, routeResult: object}, legId: string,
+ *   waveId: string, quiet?: boolean}} args
+ * @returns {object} run document (status 'error')
+ */
+function buildRoutingFailureLeg({ leg, legId, waveId, quiet }) {
+  const { toCliMessage } = require('../utils/route-error');
+  const { buildRunResult } = require('../utils/result-schema');
+  const message = toCliMessage(leg.routeResult);
+  if (!quiet) {
+    process.stderr.write(`[fanout] leg ${legId} (${leg.modelInput}): error (routing)\n`);
+  }
+  return buildRunResult({
+    taskId: legId, metadata: {}, result: { error: message, completed: false },
+    summary: null, modelInput: leg.modelInput, sessionDir: null, waveId,
+  });
+}
+
 /**
  * Run one leg end-to-end: session record → runHeadless (shared server) →
  * leg finalize. Never throws — always resolves to a run document.
@@ -129,4 +154,4 @@ async function runLeg({ leg, legId, waveId, project, systemPrompt, userMessage,
   });
 }
 
-module.exports = { legStatusFromResult, writeLegPatch, runLeg };
+module.exports = { legStatusFromResult, writeLegPatch, runLeg, buildRoutingFailureLeg };

package/src/sidecar/fanout-output.js

@@ -32,6 +32,11 @@ function formatWaveHuman(wave) {
     lines.push('');
   }
   if (wave.error) { lines.push(`Error: ${wave.error}`); }
+  // #61 whole-branch review FIX 2: advisory per-leg migration notices (no
+  // routing effect) surfaced here since fanout has no CLI-single stderr path.
+  if (Array.isArray(wave.notices) && wave.notices.length) {
+    for (const notice of wave.notices) { lines.push(`Notice: ${notice}`); }
+  }
   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)}`);

package/src/sidecar/fanout-validate.js

@@ -0,0 +1,81 @@
+// src/sidecar/fanout-validate.js
+'use strict';
+
+/**
+ * @module fanout-validate
+ * Fan-out --models parsing + per-leg gateway routing. Split out of fanout.js
+ * (#61 Task 7.3) to keep both files under the 300-line size gate — this
+ * module owns everything about turning a raw --models string into resolved
+ * (or per-leg-failed) legs; fanout.js owns running the wave itself.
+ */
+
+/** 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);
+}
+
+/**
+ * Resolve + gate every requested model through the gateway router (#61 Task
+ * 7.3), one leg at a time. Unlike the pre-#61 fail-fast validator, an
+ * individual leg's routing failure does NOT abort the whole wave: it comes
+ * back with `ok:false` and the router's RouteResult attached, so runFanout
+ * can synthesize a failed leg document (buildRoutingFailureLeg) while sibling
+ * legs still launch normally. Only whole-list problems — an empty list or
+ * exceeding the leg-count cap — remain wave-level fatal and are returned as
+ * a top-level `{error, code}` (nothing to route yet at that point).
+ * @param {string} modelsArg - Raw --models value
+ * @param {{noValidateModel?: boolean, gatewayMode?: string}} [opts]
+ * @returns {Promise<{legs: Array<{modelInput: string, ok: boolean, model?: string,
+ *   pricing?: object, gateway?: string, provenance?: object, routeResult?: object}>}
+ *   | {error: string, code: 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)', code: 'BAD_ARGS' };
+  }
+  // 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)`, code: 'BAD_ARGS' };
+  }
+
+  const { resolveRouteForLaunch } = require('../utils/route-launch');
+  const { lookupPricing } = require('../utils/pricing');
+  const validateModel = !opts.noValidateModel;
+  const gatewayMode = opts.gatewayMode || 'auto';
+  const legs = [];
+  for (const modelInput of raw) {
+    const routeResult = await resolveRouteForLaunch({
+      model: modelInput, gatewayMode, source: 'cli', allowSelection: false, validateModel,
+    });
+    if (routeResult.kind === 'resolved') {
+      legs.push({
+        modelInput, ok: true, model: routeResult.executableId,
+        pricing: lookupPricing(routeResult.executableId),
+        gateway: routeResult.gateway, provenance: routeResult.provenance,
+        // FIX 2 (#61 whole-branch review): resolveRouteForLaunch already
+        // burned the one-shot migration_notified flag for this vendor when it
+        // built routeResult — carry the notice out so runFanout can surface
+        // it on the wave doc (fanout had no other path to show it).
+        notice: routeResult.notice || null,
+      });
+    } else {
+      // 'error' (headless: allowSelection false, so the router never hands
+      // back 'selection_required' here — see gateway-router.js's catalogGate).
+      legs.push({ modelInput, ok: false, routeResult });
+    }
+  }
+  return { legs };
+}
+
+module.exports = { parseModelsList, DEFAULT_MAX_LEGS, validateFanoutModels };