amicus 3.0.0 → 3.1.0

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.

package/src/utils/config.js

@@ -8,7 +8,8 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const { applyDirectApiFallback, autoRepairAlias } = require('./alias-resolver');
+const { autoRepairAlias } = require('./alias-resolver');
+const { isDirectProvider } = require('./provider-registry');
 
 /** Default model alias map — derived from the curated-models single source (F5) */
 const { toDefaultAliases } = require('./curated-models');
@@ -111,7 +112,9 @@ function resolveModel(modelArg) {
       if (!resolved || resolved === 'null') {
         return autoRepairAlias(modelArg, config, DEFAULT_ALIASES, saveConfig);
       }
-      return applyDirectApiFallback(resolved);
+      // Router (route-launch.js / gateway-router.js, #61) owns the
+      // direct-vs-OpenRouter decision now — return the stored id verbatim.
+      return resolved;
     }
 
     // Unknown alias
@@ -140,7 +143,8 @@ function resolveModel(modelArg) {
     if (!resolved || resolved === 'null') {
       return autoRepairAlias(defaultValue, config, DEFAULT_ALIASES, saveConfig);
     }
-    return applyDirectApiFallback(resolved);
+    // Router owns the direct-vs-OpenRouter decision now — return verbatim.
+    return resolved;
   }
 
   // Default alias not found anywhere
@@ -235,16 +239,42 @@ function tryResolveModel(modelArg) {
   }
 }
 
-/** Build OpenCode provider.models config from sidecar aliases.
+/** Build OpenCode provider.models config from sidecar aliases, plus the
+ * actually-resolved launch route(s). The alias-derived entries let the UI
+ * model picker show every configured model (single source of truth for the
+ * picker); resolvedRoutes ensures the id OpenCode is ACTUALLY told to launch
+ * (config.model) is always registered under its correct provider, even when
+ * an alias maps to a different provider for the same model (e.g. an alias
+ * stores `openrouter/openai/gpt-5.5` but the router resolves DIRECT to
+ * `openai/gpt-5.5` — without this, only `openrouter` would be registered,
+ * mismatching config.model).
+ *
+ * Catalog broadening (#61 whole-branch review, FIX 1): a resolvedRoutes entry
+ * only covers the route(s) resolved AT SERVER-CREATION TIME. A long-lived,
+ * multi-session server (the MCP shared server, `utils/shared-server.js`) is
+ * created ONCE via `sharedServer.ensureServer()` and then serves MANY
+ * sessions over its lifetime, each of which independently asks the gateway
+ * router (direct-first policy) to route the SAME bare alias — some sessions
+ * land DIRECT, others land on OpenRouter, depending on which keys happen to
+ * be configured when each session starts. Since the shared server's
+ * `provider.models` is fixed at creation and never rebuilt per-session,
+ * threading only that first session's resolved id is insufficient. So for
+ * every alias that resolves to a BARE direct-capable-vendor id (post-#61
+ * default aliases are bare, e.g. `openai/gpt-5.5`), this ALSO registers the
+ * `openrouter/<vendor>/<model>` form — broadening the catalog to cover BOTH
+ * routes the router might pick, regardless of which session created the
+ * server. This does NOT change what the alias itself resolves to (still
+ * bare, still direct-first) — it only widens what's pre-registered.
+ * @param {string[]} [resolvedRoutes] executable model id(s) actually launched
  * @returns {object} e.g. { openrouter: { models: { "x-ai/grok-4.3": {}, ... } } } */
-function buildProviderModels() {
+function buildProviderModels(resolvedRoutes = []) {
   const aliases = getEffectiveAliases();
   const providers = {};
 
-  for (const fullModel of Object.values(aliases)) {
-    if (!fullModel || typeof fullModel !== 'string') { continue; }
+  const addRoute = (fullModel) => {
+    if (!fullModel || typeof fullModel !== 'string') { return; }
     const parts = fullModel.split('/');
-    if (parts.length < 2) { continue; }
+    if (parts.length < 2) { return; }
 
     const providerID = parts[0];
     const modelID = parts.slice(1).join('/');
@@ -253,16 +283,28 @@ function buildProviderModels() {
       providers[providerID] = { models: {} };
     }
     providers[providerID].models[modelID] = {};
+  };
+
+  for (const fullModel of Object.values(aliases)) {
+    addRoute(fullModel);
+
+    // Broaden: a bare direct-capable-vendor route also gets an OpenRouter
+    // mirror registered (see catalog-broadening note above). Gateway-only
+    // aliases (already `openrouter/...`, e.g. grok/qwen/x-ai) are untouched —
+    // OpenRouter is their only possible route anyway, already covered above.
+    if (typeof fullModel === 'string' && !fullModel.startsWith('openrouter/')) {
+      const vendor = fullModel.split('/')[0];
+      if (isDirectProvider(vendor)) {
+        addRoute(`openrouter/${fullModel}`);
+      }
+    }
   }
 
-  return providers;
-}
+  for (const resolved of resolvedRoutes) {
+    addRoute(resolved);
+  }
 
-/** Detect if direct API fallback was applied during alias resolution */
-function detectFallback(alias, resolvedModel) {
-  if (!alias || alias.includes('/')) { return false; }
-  const val = getEffectiveAliases()[alias];
-  return !!(val && val.startsWith('openrouter/') && !resolvedModel.startsWith('openrouter/'));
+  return providers;
 }
 
 /** @returns {Object<string,string[]>} the councils map (empty if none) */
@@ -339,6 +381,44 @@ function resolveCouncilMembers(name, catalog = []) {
   return { models, dropped };
 }
 
+/** @returns {{prefer:'direct'|'openrouter', migration_notified:Object}} routing config with defaults */
+function getRoutingConfig() {
+  const config = loadConfig() || {};
+  const r = (config.routing && typeof config.routing === 'object') ? config.routing : {};
+  const prefer = r.prefer === 'openrouter' ? 'openrouter' : 'direct';
+  const migration_notified = (r.migration_notified && typeof r.migration_notified === 'object') ? r.migration_notified : {};
+  return { prefer, migration_notified };
+}
+
+/** Merge --gateway (perCall) with routing.prefer into a router gatewayMode.
+ * @param {string|undefined} perCall 'auto'|'direct'|'openrouter'|undefined
+ * @returns {'auto'|'direct'|'openrouter'} */
+function resolveGatewayMode(perCall) {
+  if (perCall && perCall !== 'auto') { return perCall; }
+  const { prefer } = getRoutingConfig();
+  return prefer === 'openrouter' ? 'openrouter' : 'auto';
+}
+
+/**
+ * Persist the one-time direct-migration notice flag for a vendor (#61 Task
+ * 5.1 — visible-migration guarantee). Best-effort: swallows any saveConfig
+ * failure so a persistence hiccup never breaks the launch that triggered it.
+ * @param {string} vendor
+ */
+function markMigrationNotified(vendor) {
+  try {
+    const config = loadConfig() || {};
+    if (!config.routing || typeof config.routing !== 'object') { config.routing = {}; }
+    if (!config.routing.migration_notified || typeof config.routing.migration_notified !== 'object') {
+      config.routing.migration_notified = {};
+    }
+    config.routing.migration_notified[vendor] = true;
+    saveConfig(config);
+  } catch (_err) {
+    // best-effort: never fail the launch over a persistence error
+  }
+}
+
 module.exports = {
   getConfigDir,
   getConfigPath,
@@ -346,7 +426,6 @@ module.exports = {
   saveConfig,
   getDefaultAliases,
   resolveModel,
-  detectFallback,
   computeConfigHash,
   buildAliasTable,
   checkConfigChanged,
@@ -358,4 +437,7 @@ module.exports = {
   getCouncil,
   getCouncilWithSource,
   resolveCouncilMembers,
+  getRoutingConfig,
+  resolveGatewayMode,
+  markMigrationNotified,
 };

package/src/utils/curated-models.js

@@ -12,6 +12,8 @@
 
 'use strict';
 
+const { isDirectProvider } = require('./provider-registry');
+
 /**
  * Wizard quick-pick families. `idPattern` matches the model segment after
  * `<vendorPath>/` (openrouter ns) or `<provider>/` (direct ns).
@@ -91,15 +93,42 @@ function getFamilies() {
 }
 
 /**
- * @returns {Object<string,string>} alias → pinned route (openrouter first). STATIC — runtime-safe.
+ * Direct-first canonicalization for a pinned `openrouter/<vendor>/<rest>`
+ * route: when `<vendor>` has a direct integration (provider-registry
+ * `isDirectProvider`), strip the `openrouter/` prefix so the resulting bare
+ * `<vendor>/<rest>` id is policy-routed by the gateway router (direct when a
+ * direct key exists, OpenRouter otherwise). Gateway-only vendors (no direct
+ * integration — e.g. qwen, x-ai, z-ai, mistralai, minimax, moonshotai,
+ * bytedance-seed) are returned unchanged, since OpenRouter is their only
+ * route anyway. Non-openrouter routes (already bare, or malformed) pass
+ * through unchanged.
+ * @param {string} route
+ * @returns {string}
+ */
+function toCanonicalDefault(route) {
+  if (typeof route === 'string' && route.startsWith('openrouter/')) {
+    const rest = route.slice('openrouter/'.length); // '<vendor>/<rest...>'
+    const slashIdx = rest.indexOf('/');
+    const vendor = slashIdx > 0 ? rest.slice(0, slashIdx) : null;
+    if (vendor && isDirectProvider(vendor)) { return rest; }
+  }
+  return route;
+}
+
+/**
+ * @returns {Object<string,string>} alias → pinned route, direct-first for
+ * direct-capable vendors (bare `vendor/model`), openrouter-prefixed for
+ * gateway-only vendors. STATIC — runtime-safe.
  */
 function toDefaultAliases() {
   const out = {};
   for (const f of FAMILIES) {
-    out[f.alias] = f.fallback.openrouter || Object.values(f.fallback)[0];
+    const route = f.fallback.openrouter || Object.values(f.fallback)[0];
+    out[f.alias] = toCanonicalDefault(route);
   }
   for (const e of CARDLESS) {
-    out[e.alias] = e.routes.openrouter || Object.values(e.routes)[0];
+    const route = e.routes.openrouter || Object.values(e.routes)[0];
+    out[e.alias] = toCanonicalDefault(route);
   }
   return out;
 }
@@ -122,4 +151,4 @@ function listCuratedRoutes() {
   return out;
 }
 
-module.exports = { getFamilies, toDefaultAliases, listCuratedRoutes };
+module.exports = { getFamilies, toDefaultAliases, toCanonicalDefault, listCuratedRoutes };