amicus 2.2.0 → 3.1.0

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/electron-install.js

@@ -146,7 +146,7 @@ function cacheRootFor(env = process.env) {
  * @returns {Promise<void>}
  */
 async function controlledProvision({
-  electronDir, platform, arch, version, downloadArtifact, extract, fs, env = process.env,
+  electronDir, platform, arch, version, downloadArtifact, extract, fs, env = process.env, downloadMs = 480000,
 }) {
   const zip = await downloadArtifact({
     version,
@@ -155,11 +155,7 @@ async function controlledProvision({
     cacheRoot: cacheRootFor(env),
     platform,
     arch,
-    checksums: undefined,
-    // Bound the fetch so a stalled/blocked network aborts (got v11 timeouts:
-    // socket = inactivity, request = total) instead of hanging the repair —
-    // a hung-then-killed download is what orphaned the single-flight lock.
-    downloadOptions: { timeout: { socket: 60000, request: 480000 } },
+    downloadOptions: { signal: AbortSignal.timeout(downloadMs) }, // 5.x native fetch: bound stalled downloads, free the lock
   });
   await extractFromCache({ zip, electronDir, platform, extract, fs });
 }
@@ -214,7 +210,11 @@ async function repairElectron({
   const spawn = deps.spawn || ((cmd, args, o) => spawnSync(cmd, args, { ...o, timeout: timeoutMs || 480000 }));
   const findZip = deps.cachedZip || ((o) => cachedZip(o));
   const acquireLock = deps.acquireLock || ((o) => acquireRepairLock({ ...o, fs }));
-  const downloadArtifact = deps.downloadArtifact || require('@electron/get').downloadArtifact;
+  // Lazy: import the ESM-only @electron/get only on the network path, so cacheOnly
+  // repairs and injected mocks stay parseable under Jest (which can't import() ESM).
+  const resolveDownloadArtifact = deps.downloadArtifact
+    ? async () => deps.downloadArtifact
+    : async () => (await import('@electron/get')).downloadArtifact;
 
   if (!version) {
     try {
@@ -268,8 +268,9 @@ async function repairElectron({
     // download that produced no usable exe is a FAILURE (no false success; #53).
     let controlledExtracted = false;
     try {
+      const downloadArtifact = await resolveDownloadArtifact();
       await controlledProvision({
-        electronDir, platform, arch, version, downloadArtifact, extract, fs, env: process.env,
+        electronDir, platform, arch, version, downloadArtifact, extract, fs, env: process.env, downloadMs: timeoutMs,
       });
       controlledExtracted = true; // download + extract returned without throwing
     } catch {

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

package/src/sidecar/fanout.js

@@ -13,23 +13,11 @@
 const fs = require('fs');
 const path = require('path');
 const { logger } = require('../utils/logger');
-const { runLeg } = require('./fanout-leg');
+const { runLeg, buildRoutingFailureLeg } = require('./fanout-leg');
+const { parseModelsList, DEFAULT_MAX_LEGS, validateFanoutModels } = require('./fanout-validate');
 const { ERROR_CODES } = require('../utils/error-doc');
 const { writeFileAtomic } = require('../utils/atomic-write');
 
-/** 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
@@ -40,53 +28,6 @@ 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)', 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 { tryResolveModel } = require('../utils/config');
-  const { validateApiKey } = require('../utils/validators');
-  const { validateAgainstCatalog } = require('../utils/model-validator');
-  const { lookupPricing } = require('../utils/pricing');
-  const legs = [];
-  for (const modelInput of raw) {
-    const resolved = tryResolveModel(modelInput);
-    if (resolved.error) {
-      return { error: `Error: model '${modelInput}': ${resolved.error}`, code: 'BAD_MODEL' };
-    }
-    let model = resolved.model;
-    const keyCheck = validateApiKey(model);
-    if (!keyCheck.valid) {
-      return { error: keyCheck.error, code: 'MISSING_KEY' };
-    }
-    if (!opts.noValidateModel) {
-      const alias = modelInput.includes('/') ? undefined : modelInput;
-      try {
-        model = await validateAgainstCatalog(model, alias);
-      } catch (err) {
-        return { error: err.message, code: 'BAD_MODEL' };
-      }
-    }
-    legs.push({ modelInput, model, pricing: lookupPricing(model) });
-  }
-  return { legs };
-}
-
 /**
  * Write/merge wave metadata (preserves fields an MCP pre-spawn handler wrote).
  * Abort-wins: once existing status is 'aborted', a patch cannot demote it back
@@ -114,7 +55,9 @@ function writeWaveMetadata(waveDir, patch) {
  *   thinking?, timeout? (minutes), summaryLength?, includeContext?, sessionId?,
  *   coworkProcess? (#10: Cowork parent-session pin, forwarded to buildContext),
  *   contextTurns?, contextSince?, contextMaxTokens?, mcp?, mcpConfig?, noMcp?,
- *   excludeMcp?, noValidateModel?, json?, client?, quiet? (suppress stdout — tests)
+ *   excludeMcp?, noValidateModel?, gatewayMode? (#61 Task 7.3: --gateway merged
+ *   with routing.prefer, applied per leg), json?, client?, quiet? (suppress
+ *   stdout — tests)
  * @returns {Promise<{wave: object, exitCode: number}>} Never rejects for leg errors.
  */
 async function runFanout(options) {
@@ -158,19 +101,33 @@ async function runFanout(options) {
     return { wave: null, errorDoc: { code, message }, exitCode: 1 };
   };
 
-  // 1. Fail-fast validation
-  const validated = await validateFanoutModels(options.models, { noValidateModel: options.noValidateModel });
+  // 1. Fail-fast validation (list-level only — see validateFanoutModels).
+  // Per-leg routing is resolved here too (#61 Task 7.3): a leg that fails to
+  // route is NOT a wave-level failure — it comes back `ok:false` and still
+  // occupies its slot in `legs`, so sibling legs launch normally (step 6).
+  const validated = await validateFanoutModels(options.models, {
+    noValidateModel: options.noValidateModel,
+    gatewayMode: options.gatewayMode,
+  });
   if (validated.error) { return failPre(validated.code || 'BAD_ARGS', validated.error); }
   const legs = validated.legs;
+  const okLegs = legs.filter(l => l.ok);
+  // FIX 2 (#61 whole-branch review): a leg's migration notice has no CLI
+  // stderr to land on (fanout is one process resolving many legs, not one
+  // launch) — surface it on the wave doc instead, deduped in case two legs
+  // for the same vendor happen to both migrate (only the first ever fires
+  // since markMigrationNotified is one-shot per vendor, but dedupe defensively).
+  const notices = [...new Set(legs.map(l => l.notice).filter(Boolean))];
 
-  // 1b. Budget gate (pre-creation; refuse before spending)
+  // 1b. Budget gate (pre-creation; refuse before spending). Only legs that
+  // will actually run cost anything — a leg that never routed never spends.
   if (!options.noCostGate) {
     const { checkBudget, formatBudgetError } = require('./budget');
     const { loadConfig } = require('../utils/config');
     const cfg = loadConfig() || {};
     const maxCostPerMtok = options.maxCostPerMtok !== undefined ? options.maxCostPerMtok : cfg.maxCostPerMtok;
     const promptChars = (options.promptMeta && options.promptMeta.chars) || (options.prompt ? options.prompt.length : 0);
-    const budget = checkBudget(legs, { maxCostPerMtok, maxCost: options.maxCost !== null && options.maxCost !== undefined ? options.maxCost : cfg.maxCost, promptChars });
+    const budget = checkBudget(okLegs, { maxCostPerMtok, maxCost: options.maxCost !== null && options.maxCost !== undefined ? options.maxCost : cfg.maxCost, promptChars });
     if (!budget.ok) {
       return failPre(ERROR_CODES.BUDGET_EXCEEDED, 'Error: budget gate refused the wave', formatBudgetError(budget));
     }
@@ -184,12 +141,32 @@ async function runFanout(options) {
   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,
+    models: legs.map(l => (l.ok ? l.model : l.modelInput)), legs: legIds,
     briefing: String(options.prompt).slice(0, 200),
     promptMeta: options.promptMeta || null,
     pid: process.pid, project, createdAt,
   });
 
+  // 2b. All legs failed to route (#61 perf): no leg will ever touch the
+  // shared server, so starting one (and immediately tearing it down) is pure
+  // waste. Short-circuit straight to the same routing-failure wave the
+  // normal path would eventually produce — same per-leg docs
+  // (buildRoutingFailureLeg), same aggregation (buildWaveResult /
+  // waveStatusFromLegs via the default status param), same exit-code mapping
+  // (waveExitCode) — just without the server round-trip.
+  if (okLegs.length === 0) {
+    const legDocs = legs.map((leg, i) => buildRoutingFailureLeg({ leg, legId: legIds[i], waveId, quiet: options.quiet }));
+    const completedAt = new Date().toISOString();
+    const wave = buildWaveResult({
+      waveId, legs: legDocs, promptMeta: options.promptMeta || null, createdAt, completedAt, notices,
+    });
+    const wavePath = path.join(waveDir, 'wave.json');
+    writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });
+    writeWaveMetadata(waveDir, { status: wave.status, completedAt });
+    emit(wave);
+    return { wave, exitCode: waveExitCode(wave.status) };
+  }
+
   // 3. Context + prompts built ONCE (model-independent)
   const context = options.includeContext !== false
     ? buildContext(project, options.sessionId || 'current', {
@@ -207,14 +184,18 @@ async function runFanout(options) {
     options.prompt, context, project, true, options.agent || 'build', options.summaryLength, options.client, foldNonce
   );
 
-  // 4. One shared OpenCode server
+  // 4. One shared OpenCode server. Sole-input invariant (#61 Task 4.6/7.3):
+  // register EVERY leg's actually-resolved executable id in provider.models,
+  // not just the alias-derived defaults, so a leg whose router decision
+  // diverges from its alias (e.g. alias stores openrouter/... but the router
+  // picked direct) still matches what the leg is actually told to launch.
   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));
+    ({ client, server } = await startOpenCodeServer(mcpServers, { models: okLegs.map(l => l.model) }));
   } catch (err) {
     writeWaveMetadata(waveDir, { status: 'error', reason: err.message, completedAt: new Date().toISOString() });
     return errorWave(waveId, `Failed to start server: ${err.message}`);
@@ -244,7 +225,11 @@ async function runFanout(options) {
     },
   });
 
-  // 6. Launch all legs concurrently (runLeg never rejects)
+  // 6. Launch all ROUTABLE legs concurrently (runLeg never rejects). A leg
+  // that failed to route (leg.ok === false) never touches the shared server —
+  // it resolves immediately to an error run document (buildRoutingFailureLeg)
+  // in its own slot, so it fails only itself, never the sibling legs or the
+  // whole wave (#61 Task 7.3).
   const heartbeat = options.quiet
     ? { stop() {} }
     : createWaveHeartbeat(
@@ -255,12 +240,15 @@ async function runFanout(options) {
   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,
-      foldNonce,
-    })));
+    legDocs = await Promise.all(legs.map((leg, i) => (leg.ok
+      ? runLeg({
+          leg, legId: legIds[i], waveId, project, systemPrompt, userMessage,
+          timeoutMs, agent: options.agent, client, server,
+          summaryLength: options.summaryLength, reasoning, quiet: options.quiet,
+          foldNonce,
+        })
+      : Promise.resolve(buildRoutingFailureLeg({ leg, legId: legIds[i], waveId, quiet: options.quiet }))
+    )));
   } finally {
     heartbeat.stop();
     uninstallSignals();
@@ -271,7 +259,7 @@ async function runFanout(options) {
   const completedAt = new Date().toISOString();
   const wave = buildWaveResult({
     waveId, legs: legDocs, promptMeta: options.promptMeta || null, createdAt, completedAt,
-    status: signalled ? 'aborted' : null,
+    status: signalled ? 'aborted' : null, notices,
   });
   const wavePath = path.join(waveDir, 'wave.json');
   writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });

package/src/sidecar/session-utils.js

@@ -224,6 +224,11 @@ async function executeMode(options) {
  * @param {string} [options.client] - Client type (e.g. 'cowork', 'code-local')
  * @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')
+ * @param {string[]} [options.models] - Resolved executable id(s) actually launched on this
+ *   server (#61 Task 4.6/7.3 sole-input invariant) — a multi-model shared server (fanout)
+ *   has no single default `config.model`, so this registers ALL of them in provider.models
+ *   instead. Additive alongside the single-model `options.model` path used by owned-server
+ *   callers (start/continue); see opencode-client.js's buildServerOptions.
  * @returns {Promise<{client: object, server: object}>}
  * @throws {Error} If server fails to start or health check fails
  */
@@ -244,6 +249,7 @@ async function startOpenCodeServer(mcpConfig, options = {}) {
   const serverOptions = { port };
   if (mcpConfig) { serverOptions.mcp = mcpConfig; }
   if (options.client) { serverOptions.client = options.client; }
+  if (options.models) { serverOptions.models = options.models; }
   if (options.systemPrompt) { serverOptions.systemPrompt = options.systemPrompt; }
   if (options.agentName) { serverOptions.agentName = options.agentName; }
 

package/src/sidecar/setup.js

@@ -288,6 +288,7 @@ async function runReadlineSetup() {
 
     const { getCatalog } = require('../utils/model-catalog');
     const { resolveQuickPicks, toLiveSeedAliases } = require('../utils/quick-picks');
+    const { toCanonicalDefault } = require('../utils/curated-models');
     let catalog = [];
     try { catalog = await getCatalog(); } catch (_err) { /* offline: pinned */ }
     const picks = resolveQuickPicks(catalog);
@@ -316,7 +317,7 @@ async function runReadlineSetup() {
       cfg.default = chosen.alias;
       const pick = picks.find(p => p.alias === chosen.alias);
       if (pick && !chosen.noUpgrade) {
-        cfg.aliases[chosen.alias] = pick.routes.openrouter || Object.values(pick.routes)[0];
+        cfg.aliases[chosen.alias] = toCanonicalDefault(pick.routes.openrouter || Object.values(pick.routes)[0]);
       } else if (cfg.aliases[chosen.alias] === undefined) {
         const fallback = getDefaultAliases()[chosen.alias];
         if (fallback !== undefined) { cfg.aliases[chosen.alias] = fallback; }

package/src/utils/alias-resolver.js

@@ -1,41 +1,13 @@
 /**
  * Alias Resolver Utilities
  *
- * Handles alias auto-repair and direct API fallback logic,
- * extracted from config.js to keep it under the 300-line limit.
+ * Handles alias auto-repair, extracted from config.js to keep it under the
+ * 300-line limit. The direct-vs-OpenRouter gateway decision that used to live
+ * here (applyDirectApiFallback, a prefix-stripping heuristic) is now owned
+ * end-to-end by the gateway router (route-launch.js / gateway-router.js,
+ * #61) on every launch path — this module no longer makes that call.
  */
 
-const { PROVIDER_ENV_MAP, readApiKeyValues } = require('./api-key-store');
-const { logger } = require('./logger');
-
-/**
- * Strip openrouter/ prefix when direct provider API key is available
- * but OPENROUTER_API_KEY is not.
- * @param {string} model - Full model identifier
- * @returns {string} Model with or without openrouter/ prefix
- */
-function applyDirectApiFallback(model) {
-  if (!model.startsWith('openrouter/')) {
-    return model;
-  }
-  const persistedKeys = readApiKeyValues();
-  if (process.env.OPENROUTER_API_KEY || persistedKeys.openrouter) {
-    return model;
-  }
-  const direct = model.slice('openrouter/'.length);
-  const provider = direct.split('/')[0];
-  const envVar = PROVIDER_ENV_MAP[provider];
-  if (envVar && (process.env[envVar] || persistedKeys[provider])) {
-    logger.warn({ msg: 'Using direct provider API (OPENROUTER_API_KEY not set)', original: model, resolved: direct });
-    process.stderr.write(
-      `Notice: Using direct ${provider} API (OPENROUTER_API_KEY not set). ` +
-      'Model availability is validated automatically; pass --no-validate-model to skip.\n'
-    );
-    return direct;
-  }
-  return model;
-}
-
 /**
  * Auto-repair a null alias by falling back to DEFAULT_ALIASES.
  * Updates config on disk and warns to stderr.
@@ -63,7 +35,7 @@ function autoRepairAlias(alias, config, defaultAliases, saveConfig) {
         );
       }
     }
-    return applyDirectApiFallback(defaultModel);
+    return defaultModel;
   }
   throw new Error(
     `Alias '${alias}' is configured but has no model value. ` +
@@ -72,6 +44,5 @@ function autoRepairAlias(alias, config, defaultAliases, saveConfig) {
 }
 
 module.exports = {
-  applyDirectApiFallback,
   autoRepairAlias,
 };

package/src/utils/api-key-store.js

@@ -5,15 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { validateApiKey, validateOpenRouterKey, VALIDATION_ENDPOINTS } = require('./api-key-validation');
-
-/** Maps provider IDs to environment variable names */
-const PROVIDER_ENV_MAP = {
-  openrouter: 'OPENROUTER_API_KEY',
-  google: 'GOOGLE_GENERATIVE_AI_API_KEY',
-  openai: 'OPENAI_API_KEY',
-  anthropic: 'ANTHROPIC_API_KEY',
-  deepseek: 'DEEPSEEK_API_KEY'
-};
+const { PROVIDER_ENV_MAP } = require('./provider-registry');
 
 /** Legacy key names that have been renamed (old -> new) */
 const LEGACY_KEY_NAMES = {

package/src/utils/auth-json.js

@@ -50,7 +50,7 @@ function resolveAuthJsonPath(env = process.env) {
 const AUTH_JSON_PATH = resolveAuthJsonPath();
 
 /** Known provider IDs that map to sidecar's PROVIDER_ENV_MAP */
-const KNOWN_PROVIDERS = ['openrouter', 'google', 'openai', 'anthropic', 'deepseek'];
+const { KNOWN_PROVIDERS } = require('./provider-registry');
 
 /**
  * Extract key value from an auth.json provider entry.