amicus 3.1.1 → 3.2.0

package/src/utils/model-tiers.js

@@ -0,0 +1,120 @@
+/**
+ * Per-vendor cost tiers (economy/balanced/frontier) + resolution against the
+ * live model catalog.
+ *
+ * Tier ordering: frontier = MOST expensive/capable, economy = CHEAPEST,
+ * balanced = the middle ground.
+ *
+ * Mirrors quick-picks.pickCurrent's "newest live-catalog id matching a
+ * pattern in a vendor namespace" approach rather than reinventing it: each
+ * tier's regex is matched over the model segment in BOTH the direct
+ * namespace (`<vendor>/<model>`) and the OpenRouter namespace
+ * (`openrouter/<vendor>/<model>`); the direct-namespace pick wins when both
+ * exist, since storage is direct-first (see gateway-router.js).
+ *
+ * Gateway-only vendors (no direct API integration — provider-registry
+ * `isDirectProvider` false) have no tier regexes here: OpenRouter is their
+ * only route, and curated-models' CARDLESS/family-fallback entries don't
+ * carry a per-alias match pattern the way FAMILIES does, so there is no
+ * live-catalog rule to reuse for them. All three tiers resolve to the same
+ * curated flagship — the static canonical pin `toDefaultAliases()` already
+ * maintains for that vendor's alias (the same pin `resolveQuickPicks` falls
+ * back to when live resolution is unavailable).
+ */
+
+'use strict';
+
+const { pickCurrent } = require('./quick-picks');
+const { isDirectProvider } = require('./provider-registry');
+const { toDefaultAliases, listCuratedRoutes } = require('./curated-models');
+
+/** Tier regex table: pattern matches the model segment after `<vendor>/` (or `openrouter/<vendor>/`). */
+const TIERS = {
+  anthropic: {
+    economy: /^claude-haiku-/,
+    balanced: /^claude-sonnet-/,
+    frontier: /^claude-opus-/,
+  },
+  openai: {
+    economy: /^gpt-[\d.]+-mini$/,
+    balanced: /^gpt-[\d.]+$/,
+    frontier: /^gpt-[\d.]+-pro$/,
+  },
+  google: {
+    economy: /^gemini-[\d.]+-flash-lite/,
+    balanced: /^gemini-[\d.]+-flash(?!-lite)/,
+    frontier: /^gemini-[\d.]+-pro/,
+  },
+  deepseek: {
+    economy: /^deepseek-v[\d.]+$/,
+    balanced: /^deepseek-v[\d.]+$/,
+    frontier: /^deepseek-v[\d.]+-pro$/,
+  },
+};
+
+/** Fallback preference order when the requested tier's pattern matches nothing. */
+const TIER_ORDER = ['economy', 'balanced', 'frontier'];
+
+/**
+ * vendor -> curated alias, for vendors with no direct integration and no
+ * TIERS entry. Built once from curated-models' OpenRouter-routed entries;
+ * the first alias found per vendor wins (e.g. 'qwen' over its
+ * 'qwen-coder'/'qwen-flash' siblings, since CARDLESS lists it first).
+ * @returns {Object<string,string>}
+ */
+function buildGatewayOnlyAliasMap() {
+  const map = {};
+  for (const { alias, provider, model } of listCuratedRoutes()) {
+    if (provider !== 'openrouter' || !model.startsWith('openrouter/')) { continue; }
+    const rest = model.slice('openrouter/'.length); // '<vendor>/<rest...>'
+    const slash = rest.indexOf('/');
+    const vendor = slash > 0 ? rest.slice(0, slash) : null;
+    if (!vendor || isDirectProvider(vendor) || TIERS[vendor] || map[vendor]) { continue; }
+    map[vendor] = alias;
+  }
+  return map;
+}
+
+const GATEWAY_ONLY_ALIAS = buildGatewayOnlyAliasMap();
+
+/** Newest catalog id matching `regex` under `vendor`; direct namespace preferred over OpenRouter's. */
+function pickForTier(catalog, vendor, regex) {
+  return pickCurrent(catalog, '', vendor, regex) || pickCurrent(catalog, 'openrouter/', vendor, regex);
+}
+
+/** True when the catalog has ANY row (any tier) under this vendor's namespace, in either gateway. */
+function vendorHasModels(catalog, vendor) {
+  return Boolean(pickForTier(catalog, vendor, /./));
+}
+
+/**
+ * @param {string} vendor
+ * @param {'economy'|'balanced'|'frontier'} tier
+ * @param {Array<{id:string}>} catalog
+ * @returns {string|null} current live-catalog full id for vendor+tier
+ *   (e.g. `anthropic/claude-sonnet-5`), or null when the vendor is unknown
+ *   or absent from the catalog.
+ */
+function resolveTier(vendor, tier, catalog) {
+  if (typeof vendor !== 'string' || !vendor) { return null; }
+  if (!TIER_ORDER.includes(tier)) { return null; }
+
+  const gatewayAlias = GATEWAY_ONLY_ALIAS[vendor];
+  if (gatewayAlias) { return toDefaultAliases()[gatewayAlias] || null; }
+
+  const table = TIERS[vendor];
+  if (!table) { return null; }
+
+  const direct = pickForTier(catalog, vendor, table[tier]);
+  if (direct) { return direct; }
+
+  if (!vendorHasModels(catalog, vendor)) { return null; }
+
+  for (const t of TIER_ORDER) {
+    const pick = pickForTier(catalog, vendor, table[t]);
+    if (pick) { return pick; }
+  }
+  return null;
+}
+
+module.exports = { TIERS, resolveTier };

package/src/utils/provider-default-picker.js

@@ -0,0 +1,234 @@
+/**
+ * Provider-default picker core (Part 2, Task 4).
+ *
+ * Builds the priced, tier-preselected choice list a vendor's model picker
+ * (CLI/Electron/readline, later tasks) renders. This module is PURE and
+ * transport-agnostic: the catalog is always injected by the caller, and it
+ * never imports a renderer's formatting helper (e.g. Electron's `fmtPrice`)
+ * -- `pricePerMInput` is returned as a raw number; each surface formats it.
+ *
+ * The one documented impurity: when `tier` is omitted, `getCostTier()` reads
+ * the user's persisted config (Task 1). Callers that need full purity can
+ * always pass `tier` explicitly to skip that read entirely.
+ */
+
+'use strict';
+
+const { resolveTier } = require('./model-tiers');
+const { getCostTier, loadConfig, saveConfig } = require('./config');
+const { pairAcrossGateways } = require('./gateway-route-catalog');
+const { toCanonicalDefault, DIVERGENT_VENDORS } = require('./curated-models');
+
+/**
+ * @param {{pricing?: {prompt?: string|number|null}|null}|null|undefined} orRow
+ *   the OpenRouter-namespace catalog row paired to a logical model, if any.
+ * @returns {number|null} `pricing.prompt * 1e6` ($/M input tokens), or null
+ *   when there is no priced OpenRouter twin.
+ */
+function pricePerMInputFrom(orRow) {
+  if (!orRow || !orRow.pricing || orRow.pricing.prompt === null || orRow.pricing.prompt === undefined) {
+    return null;
+  }
+  const n = Number(orRow.pricing.prompt);
+  return Number.isFinite(n) ? n * 1e6 : null;
+}
+
+/**
+ * Every catalog row belonging to `vendor`, in either namespace (direct
+ * `<vendor>/<model>` or OpenRouter `openrouter/<vendor>/<model>`).
+ * @param {Array<{id:string}>} catalog
+ * @param {string} vendor
+ * @returns {Array<{id:string}>}
+ */
+function vendorRowsIn(catalog, vendor) {
+  const directPrefix = `${vendor}/`;
+  const orPrefix = `openrouter/${vendor}/`;
+  return catalog.filter(r => r && typeof r.id === 'string' &&
+    (r.id.startsWith(directPrefix) || r.id.startsWith(orPrefix)));
+}
+
+/**
+ * Choose the verbatim catalog id a single catalog `row` should surface as in
+ * the picker -- NEVER fabricates an id.
+ *
+ * A direct-namespace row always keeps its own (real, direct-callable) id,
+ * regardless of what `pairAcrossGateways` could resolve for it -- this is
+ * what keeps BOTH direct rows around when two direct ids are ambiguous to
+ * `pairAcrossGateways` (e.g. a bare alias and a dated pinned snapshot that
+ * normalize to the same key): each is still a real, distinct, callable id
+ * and must not be dropped or silently merged.
+ *
+ * An OpenRouter-namespace row is collapsed onto a direct id only when
+ * `pairAcrossGateways` found exactly one (unambiguous) direct twin -- that's
+ * a real catalog id, safe to reuse for dedup. Otherwise: for
+ * `DIVERGENT_VENDORS` (direct ids don't share a string form with
+ * OpenRouter's -- e.g. anthropic's dash-vs-dot versioning), the row keeps
+ * its OpenRouter-prefixed id as-is; stripping the prefix would fabricate a
+ * non-direct-callable dot-form id no row actually carries. Non-divergent
+ * vendors keep the pre-existing strip via `toCanonicalDefault`, which is
+ * safe because their direct and OpenRouter ids are identical once the
+ * `openrouter/<vendor>/` prefix is removed (mirrors curated-models.js's
+ * `directFormFor` policy).
+ * @param {string} vendor
+ * @param {boolean} isDirect whether `row.id` is itself a direct-namespace id
+ * @param {{id:string}} row
+ * @param {{direct?:string, openrouter?:string}} paired
+ * @returns {string|null}
+ */
+function chooseRowId(vendor, isDirect, row, paired) {
+  if (isDirect) { return row.id; }
+  if (paired.direct) { return paired.direct; }
+  if (!paired.openrouter) { return null; }
+  return DIVERGENT_VENDORS.has(vendor) ? paired.openrouter : toCanonicalDefault(paired.openrouter);
+}
+
+/**
+ * Dedupe `vendor`'s catalog rows across gateways into one row per logical
+ * model, reusing `pairAcrossGateways` (never re-deriving the pairing logic).
+ * Every row id is verbatim from the catalog (see `chooseRowId`) -- never
+ * fabricated, and a direct row is never dropped even when its OpenRouter
+ * twin is ambiguous.
+ * @param {Array<{id:string,name:string,contextLength:(number|null)}>} catalog
+ * @param {string} vendor
+ * @returns {Array<{id:string,name:string,contextLength:(number|null),pricePerMInput:(number|null),isPreselected:boolean}>}
+ */
+function buildRows(catalog, vendor) {
+  const byId = new Map(catalog.filter(r => r && typeof r.id === 'string').map(r => [r.id, r]));
+  const catalogInfo = { models: catalog };
+  const directPrefix = `${vendor}/`;
+  const orPrefix = `openrouter/${vendor}/`;
+
+  const rows = [];
+  const seenIds = new Set();
+
+  for (const row of vendorRowsIn(catalog, vendor)) {
+    const isDirect = row.id.startsWith(directPrefix);
+    const token = isDirect ? row.id.slice(directPrefix.length) : row.id.slice(orPrefix.length);
+    const paired = pairAcrossGateways(vendor, token, catalogInfo);
+    const chosenId = chooseRowId(vendor, isDirect, row, paired);
+    if (!chosenId || seenIds.has(chosenId)) { continue; }
+    seenIds.add(chosenId);
+
+    const orRow = paired.openrouter ? byId.get(paired.openrouter) : null;
+    const sourceRow = isDirect ? row : ((paired.direct && byId.get(paired.direct)) || orRow || row);
+
+    rows.push({
+      id: chosenId,
+      name: sourceRow.name,
+      contextLength: (sourceRow.contextLength === undefined ? null : sourceRow.contextLength),
+      pricePerMInput: pricePerMInputFrom(orRow),
+      isPreselected: false,
+    });
+  }
+  return rows;
+}
+
+/**
+ * Canonicalize `resolveTier`'s verbatim catalog-id output the same way row
+ * ids are built (`chooseRowId`), so it can be matched against `rows`
+ * exactly. `resolveTier` already prefers a real direct id when one matches
+ * the tier pattern (`model-tiers.js`'s `pickForTier` tries the direct
+ * namespace first), so this only has an effect when it fell back to an
+ * OpenRouter id (no matching direct-namespace row at all). For
+ * `DIVERGENT_VENDORS`, that OpenRouter id must stay OpenRouter-prefixed --
+ * stripping it would fabricate a non-direct-callable dot-form id that no row
+ * carries. Non-divergent vendors keep the pre-existing strip, safe because
+ * their direct and OpenRouter ids are identical once the prefix is removed.
+ * @param {string} vendor
+ * @param {string|null} resolved verbatim catalog id from `resolveTier`, or null
+ * @returns {string|null}
+ */
+function canonicalizeResolved(vendor, resolved) {
+  if (!resolved) { return null; }
+  return DIVERGENT_VENDORS.has(vendor) ? resolved : toCanonicalDefault(resolved);
+}
+
+/**
+ * Decide which row (by id) should be preselected.
+ * Primary: `resolveTier(vendor, tier, catalog)`, canonicalized the same way
+ * row ids are (direct-first) so it can match a row exactly. Falls back to
+ * the cheapest priced row, then the first row, whenever the primary result
+ * is null OR (defensively) doesn't correspond to any built row.
+ * @param {string} vendor
+ * @param {string|undefined} tier
+ * @param {Array<{id:string}>} catalog
+ * @param {Array<{id:string,pricePerMInput:(number|null)}>} rows non-empty
+ * @returns {string} a row id from `rows`
+ */
+function computePreselectedId(vendor, tier, catalog, rows) {
+  const effectiveTier = tier || getCostTier();
+  const resolved = resolveTier(vendor, effectiveTier, catalog);
+  const canonical = canonicalizeResolved(vendor, resolved);
+  if (canonical && rows.some(r => r.id === canonical)) { return canonical; }
+
+  const priced = rows.filter(r => r.pricePerMInput !== null);
+  if (priced.length > 0) {
+    return priced.reduce((cheapest, r) => (r.pricePerMInput < cheapest.pricePerMInput ? r : cheapest)).id;
+  }
+  return rows[0].id;
+}
+
+/** Preselected first; then price ascending; null prices last. Stable otherwise. */
+function compareRows(a, b) {
+  if (a.isPreselected !== b.isPreselected) { return a.isPreselected ? -1 : 1; }
+  if (a.pricePerMInput === null && b.pricePerMInput === null) { return 0; }
+  if (a.pricePerMInput === null) { return 1; }
+  if (b.pricePerMInput === null) { return -1; }
+  return a.pricePerMInput - b.pricePerMInput;
+}
+
+/**
+ * Build the choice list for a vendor's model picker.
+ * @param {string} vendor e.g. 'anthropic'
+ * @param {{catalog?: Array<{id:string,name:string,contextLength:(number|null),pricing:(object|null)}>, tier?: string}} [options]
+ * @returns {{preselectedId: (string|null), rows: Array<{id:string,name:string,contextLength:(number|null),pricePerMInput:(number|null),isPreselected:boolean}>}}
+ */
+function buildProviderDefaultChoices(vendor, options = {}) {
+  if (typeof vendor !== 'string' || !vendor) { return { preselectedId: null, rows: [] }; }
+
+  const catalog = Array.isArray(options.catalog) ? options.catalog : [];
+  const rows = buildRows(catalog, vendor);
+  if (rows.length === 0) { return { preselectedId: null, rows: [] }; }
+
+  const preselectedId = computePreselectedId(vendor, options.tier, catalog, rows);
+  for (const r of rows) { r.isPreselected = r.id === preselectedId; }
+  rows.sort(compareRows);
+
+  return { preselectedId, rows };
+}
+
+/**
+ * Apply a picker choice: store the vendor-named alias and (optionally) seed
+ * `config.default` on first use. Read-modify-write, NO-CLOBBER -- preserves
+ * an already-set `config.default` and every other existing alias/key.
+ *
+ * `chosenId` is a verbatim catalog id straight from `buildProviderDefaultChoices`
+ * (via `chooseRowId`/`computePreselectedId`): a real direct id, or -- for a
+ * `DIVERGENT_VENDORS` vendor with no direct twin -- an `openrouter/`-prefixed
+ * id. **Never** run `toCanonicalDefault` on a divergent vendor's id: that
+ * would strip the `openrouter/` prefix and fabricate a non-direct-callable
+ * dot-form id no row actually carries (the exact bug just fixed in Task 4's
+ * `chooseRowId`/`canonicalizeResolved`). Non-divergent vendors' direct and
+ * OpenRouter ids are identical once the prefix is stripped, so
+ * `toCanonicalDefault` is safe there.
+ * @param {string} vendor e.g. 'anthropic'
+ * @param {string} chosenId verbatim catalog id from the picker
+ * @param {{seedDefaultIfAbsent?: boolean}} [options]
+ * @returns {{alias: string, setAsDefault: boolean}}
+ */
+function applyProviderDefault(vendor, chosenId, { seedDefaultIfAbsent = true } = {}) {
+  const storedId = DIVERGENT_VENDORS.has(vendor) ? chosenId : toCanonicalDefault(chosenId);
+
+  const config = loadConfig() || {};
+  if (!config.aliases || typeof config.aliases !== 'object') { config.aliases = {}; }
+  config.aliases[vendor] = storedId;
+
+  const hasDefault = typeof config.default === 'string' && config.default.trim().length > 0;
+  const setAsDefault = seedDefaultIfAbsent && !hasDefault;
+  if (setAsDefault) { config.default = vendor; }
+
+  saveConfig(config);
+  return { alias: vendor, setAsDefault };
+}
+
+module.exports = { buildProviderDefaultChoices, applyProviderDefault };

package/src/utils/provider-default-prompt.js

@@ -0,0 +1,118 @@
+/**
+ * Provider-default prompt flow (Part 2, Task 6/7 shared helper).
+ *
+ * Wraps the transport-agnostic picker core (`provider-default-picker.js`) in
+ * a single reusable flow that both the CLI (`amicus key`, Task 6) and the
+ * readline setup wizard (Task 7) call after a provider's API key is saved:
+ * build the priced choice list, either prompt for a selection (interactive)
+ * or silently take the tier-preselected id (non-interactive), then apply it.
+ *
+ * Transport-agnostic by injection: `ask` (a `(prompt: string) => Promise<string>`
+ * readline reader) and `print` (a `(line: string) => void` line writer) are
+ * both passed in by the caller, so this module is unit-testable without a
+ * real TTY and never imports `readline`/`console` itself.
+ */
+
+'use strict';
+
+const { buildProviderDefaultChoices, applyProviderDefault } = require('./provider-default-picker');
+const { isDirectProvider } = require('./provider-registry');
+
+/** Format a $/M-input price for display; `null`/`undefined` -> 'n/a'. @param {number|null|undefined} pricePerMInput */
+function formatPrice(pricePerMInput) {
+  return (pricePerMInput === null || pricePerMInput === undefined)
+    ? 'n/a'
+    : `$${pricePerMInput.toFixed(2)}/M in`;
+}
+
+/** One numbered display line for a single choice row. @param {object} row @param {number} index 1-based */
+function formatRow(row, index) {
+  const ctx = (row.contextLength === null || row.contextLength === undefined) ? '' : ` · ctx ${row.contextLength}`;
+  const recommended = row.isPreselected ? '  (recommended)' : '';
+  return `  ${index}) ${row.name}${ctx} · ${formatPrice(row.pricePerMInput)}${recommended}`;
+}
+
+/**
+ * Read one selection line, re-prompting once on an invalid non-empty entry
+ * before falling back to the preselected id. Empty input (bare Enter) always
+ * accepts the preselected id immediately, no re-prompt.
+ * @param {(prompt: string) => Promise<string>} ask
+ * @param {(line: string) => void} print
+ * @param {{preselectedId: string, rows: Array<{id: string}>}} choices
+ * @returns {Promise<string>}
+ */
+async function promptForChoice(ask, print, choices) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const answer = (await ask(`Pick a number (1-${choices.rows.length}, Enter for recommended): `) || '').trim();
+    if (answer === '') { return choices.preselectedId; }
+    if (/^\d+$/.test(answer)) {
+      const num = Number.parseInt(answer, 10);
+      if (num >= 1 && num <= choices.rows.length) {
+        return choices.rows[num - 1].id;
+      }
+    }
+    if (attempt === 0) { print(`Invalid choice: "${answer}".`); }
+  }
+  return choices.preselectedId;
+}
+
+/**
+ * Run the per-provider default-model flow: build choices, resolve a pick
+ * (prompted or silent), apply it, and hand back a one-line summary for the
+ * caller to print. Never throws for an empty/offline catalog -- callers
+ * should still wrap this in a try/catch (a picker bug must never abort an
+ * already-successful key save).
+ *
+ * Gateway providers (e.g. `openrouter`) are a graceful no-op: `openrouter` is
+ * the GATEWAY, not a model vendor, so `buildProviderDefaultChoices` would
+ * match every OR-namespaced catalog row, "recommended" would be arbitrary,
+ * and writing `aliases.openrouter = "<some vendor>/<model>"` would be
+ * nonsensical. Per-provider defaults only make sense for DIRECT model
+ * vendors (`provider-registry.isDirectProvider`) -- no choices are built, no
+ * alias is written, and `config.default` is never seeded for a gateway.
+ * @param {string} provider vendor name, e.g. 'anthropic'
+ * @param {{interactive?: boolean, ask?: (prompt: string) => Promise<string>,
+ *   catalog?: Array<object>, print?: (line: string) => void}} [options]
+ * @returns {Promise<{chosenId: (string|null), setAsDefault: boolean, summaryLine: string}>}
+ */
+async function runProviderDefaultFlow(provider, options = {}) {
+  const { interactive = false, ask } = options;
+  const catalog = Array.isArray(options.catalog) ? options.catalog : [];
+  const print = typeof options.print === 'function' ? options.print : () => {};
+
+  if (!isDirectProvider(provider)) {
+    return {
+      chosenId: null,
+      setAsDefault: false,
+      summaryLine: 'Per-provider defaults apply to direct provider keys (openai/anthropic/google/deepseek) -- ' +
+        'models routed via OpenRouter use your overall default.',
+    };
+  }
+
+  const choices = buildProviderDefaultChoices(provider, { catalog });
+  if (!choices.rows || choices.rows.length === 0) {
+    return {
+      chosenId: null,
+      setAsDefault: false,
+      summaryLine: `Couldn't reach the model catalog for ${provider} — no default set. ` +
+        `Run \`amicus key ${provider}\` again later.`,
+    };
+  }
+
+  let chosenId = choices.preselectedId;
+  if (interactive && typeof ask === 'function') {
+    print('');
+    print(`Pick a default model for ${provider}:`);
+    choices.rows.forEach((row, i) => print(formatRow(row, i + 1)));
+    print('');
+    chosenId = await promptForChoice(ask, print, choices);
+  }
+
+  const { setAsDefault } = applyProviderDefault(provider, chosenId, { seedDefaultIfAbsent: true });
+  const summaryLine = `\`amicus start --model ${provider}\` → ${chosenId}` +
+    (setAsDefault ? ', set as your default model' : '');
+
+  return { chosenId, setAsDefault, summaryLine };
+}
+
+module.exports = { runProviderDefaultFlow, formatPrice, formatRow };

package/src/utils/route-launch.js

@@ -149,28 +149,107 @@ function maybeMigrationNotice({ result, descriptor, gatewayMode, keys }) {
   return result;
 }
 
+/**
+ * Comparison-only key for a gateway-native id: strip a leading `openrouter/`
+ * prefix, lowercase, unify dot/dash separators. Lets a divergent vendor's
+ * dash-form direct id, dot-form OpenRouter id, and a stale/reformatted
+ * variant (e.g. toDefaultAliases()'s dotted default) collapse to one key
+ * when they name the same model. Never used to construct/emit an id.
+ * @param {string} id @returns {string|null}
+ */
+function normalizeForModelIndex(id) {
+  if (typeof id !== 'string' || !id) { return null; }
+  const rest = id.startsWith('openrouter/') ? id.slice('openrouter/'.length) : id;
+  return rest.toLowerCase().replace(/\./g, '-');
+}
+
+/**
+ * By-model index of every curated route pair (Task 3 Part 2 / spec D2): each
+ * `{direct?, openrouter}` pair from toGatewayRoutes() is indexed under the
+ * normalized form of BOTH its values, so a lookup BY RESOLVED MODEL (not
+ * alias name) finds the pair regardless of which alias produced it or which
+ * gateway-native form the caller's id is in.
+ * @returns {Object<string,{direct?:string, openrouter?:string}>}
+ */
+function buildGatewayRoutesByModel() {
+  const { toGatewayRoutes } = require('./curated-models');
+  const byModel = {};
+  for (const pair of Object.values(toGatewayRoutes())) {
+    const directKey = normalizeForModelIndex(pair.direct);
+    const orKey = normalizeForModelIndex(pair.openrouter);
+    if (directKey) { byModel[directKey] = pair; }
+    if (orKey) { byModel[orKey] = pair; }
+  }
+  return byModel;
+}
+
+/**
+ * @param {string} resolvedId direct (`vendor/model`) or OR-prefixed
+ *   (`openrouter/vendor/model`) gateway-native id
+ * @returns {{vendor:string, bareModel:string}|null}
+ */
+function splitVendorAndModel(resolvedId) {
+  if (typeof resolvedId !== 'string') { return null; }
+  const rest = resolvedId.startsWith('openrouter/') ? resolvedId.slice('openrouter/'.length) : resolvedId;
+  const idx = rest.indexOf('/');
+  if (idx <= 0 || idx === rest.length - 1) { return null; }
+  return { vendor: rest.slice(0, idx), bareModel: rest.slice(idx + 1) };
+}
+
+/**
+ * Resolve `{direct?, openrouter?}` for `resolvedId`, for ANY alias — curated
+ * default, user override, or vendor alias (Task 3 Part 2 / spec D2; retires
+ * Part 1's curated-default-NAME-only guard). Two-step:
+ *  1. By-model curated lookup (buildGatewayRoutesByModel()) — covers curated
+ *     defaults byte-identically to Part 1, plus any alias resolving to the
+ *     same underlying curated model.
+ *  2. Catalog pairing fallback: for a DIVERGENT vendor not covered by (1),
+ *     ask the live catalog (gateway-route-catalog's pairAcrossGateways,
+ *     Task 5) to pair the two forms. Non-divergent vendors skip this — their
+ *     ids already match across gateways, so `executableFor`'s fallback is
+ *     already correct with no gatewayIds.
+ * FAIL-OPEN: any miss/malformed-input/thrown-error resolves to `undefined`
+ * (no gatewayIds) — never raises, never blocks a launch.
+ * @param {string} resolvedId @param {{models: Array}} catalogInfo
+ * @returns {{direct?:string, openrouter?:string}|undefined}
+ */
+function resolveGatewayIdsByModel(resolvedId, catalogInfo) {
+  try {
+    const key = normalizeForModelIndex(resolvedId);
+    const byModel = key ? buildGatewayRoutesByModel() : null;
+    if (byModel && byModel[key]) { return byModel[key]; }
+
+    const split = splitVendorAndModel(resolvedId);
+    if (!split) { return undefined; }
+    const { DIVERGENT_VENDORS } = require('./curated-models');
+    if (!DIVERGENT_VENDORS.has(split.vendor)) { return undefined; }
+
+    const { pairAcrossGateways } = require('./gateway-route-catalog');
+    const paired = pairAcrossGateways(split.vendor, split.bareModel, catalogInfo);
+    return (paired && (paired.direct || paired.openrouter)) ? paired : undefined;
+  } catch (_err) {
+    return undefined; // fail-open: a lookup error must never block the launch.
+  }
+}
+
 /**
  * Bridge: alias -> descriptor -> resolveRoute (Task 4.4; gatewayIds bridging
- * Task 3 of #61's gateway-correct-model-ids fix).
- * 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.
+ * Task 3, generalized by-model in Part 2 Task 3 / spec D2).
+ * Resolves a raw model string to a Descriptor — a known no-slash alias (per
+ * getEffectiveAliases()) has its concrete id parsed instead, so an alias
+ * pointing at an `openrouter/...` value is an explicit force-OR literal
+ * while one pointing at a bare `vendor/model` is policy-routed normally.
  *
- * When the alias is UNMODIFIED from its curated default (effective value ===
- * getDefaultAliases()[alias]), this also looks up curated-models'
- * toGatewayRoutes()[alias] and threads it through as `gatewayIds`, and parses
- * the descriptor from the gateway-native direct form (falling back to the
- * openrouter form) rather than the single pinned alias string — the pinned
- * string can be the wrong per-gateway form for divergent vendors (e.g.
- * Anthropic's dash ids vs. OpenRouter's dot ids), so `toGatewayRoutes()` is
- * the source of truth for actually-correct ids. A USER OVERRIDE (the
- * effective alias differs from the curated default) or an alias with no
- * curated route map intentionally skips all of this: no gatewayIds, and the
- * user's own alias string is parsed as before — we must never impose curated
- * Anthropic-style ids onto a target the user chose themselves. Full-id /
- * non-alias inputs are likewise unaffected (no gatewayIds).
+ * For ANY alias, the resolved concrete id is looked up BY MODEL via
+ * resolveGatewayIdsByModel() and threaded through as `gatewayIds` — the
+ * descriptor is then re-parsed from the gateway-native form (not the raw
+ * alias string, which can be the wrong per-gateway form for a divergent
+ * vendor, e.g. Anthropic's dash vs. OpenRouter's dot ids). Preserves Part
+ * 1's force-OR contract: an alias whose ORIGINAL value is an explicit
+ * `openrouter/...` literal prefers `gatewayIds.openrouter` (else falls back
+ * to that original value); any other alias value prefers `gatewayIds.direct`
+ * (else `.openrouter`) as before. Uncovered models get no gatewayIds
+ * (fail-open); full-id/non-alias inputs are unaffected.
  *
  * Assembles live key/catalog state and delegates the actual decision to the
  * pure gateway-router. Wired into start-helpers.js, mcp-server.js, and
@@ -179,33 +258,34 @@ function maybeMigrationNotice({ result, descriptor, gatewayMode, keys }) {
  * @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' | './curated-models', ...)
+  // 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, getDefaultAliases } = require('./config');
+  const { getEffectiveAliases } = require('./config');
   const { parseDescriptor } = require('./model-descriptor');
   const { resolveRoute } = require('./gateway-router');
-  const { toGatewayRoutes } = require('./curated-models');
   const aliases = getEffectiveAliases();
   const isAlias = typeof model === 'string' && !model.includes('/') && !!aliases[model];
   let concrete = isAlias ? aliases[model] : model;
+  const keys = buildLaunchKeys();
+  // Skip the catalog fetch entirely under --no-validate-model (catalogGate
+  // short-circuits without consulting catalogInfo when validateModel===false,
+  // so fetching would be wasted network/latency). Moved up from after
+  // descriptor parsing because the catalog-pairing fallback below needs it;
+  // otherwise independent of the descriptor/alias, so no other effect.
+  const catalogInfo = validateModel === false ? { models: [], lastRefreshError: null } : await getRouteCatalogInfo();
   let gatewayIds;
-  if (isAlias && aliases[model] === getDefaultAliases()[model]) {
-    const routes = toGatewayRoutes()[model];
-    if (routes) {
-      gatewayIds = routes;
-      concrete = routes.direct || routes.openrouter;
+  if (isAlias) {
+    const originalConcrete = concrete; // pre-gatewayIds alias value; may itself be an explicit `openrouter/...` literal
+    gatewayIds = resolveGatewayIdsByModel(concrete, catalogInfo);
+    if (gatewayIds) {
+      // Force-OR contract (Part 1): an explicit openrouter/... alias value
+      // stays on OpenRouter; only a bare vendor/model value prefers direct.
+      concrete = originalConcrete.startsWith('openrouter/')
+        ? (gatewayIds.openrouter || originalConcrete)
+        : (gatewayIds.direct || gatewayIds.openrouter);
     }
   }
   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, gatewayIds });
   if (result.kind === 'resolved') {
     result.provenance = { ...result.provenance, resolutionVersion: ROUTE_VERSION };