amicus 3.0.0 → 3.1.1

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).
@@ -45,7 +47,7 @@ const FAMILIES = [
     idPattern: /^claude-opus-[\d.-]+$/,
     directProviders: ['anthropic'],
     fallback: { openrouter: 'openrouter/anthropic/claude-opus-4.8',
-                anthropic: 'anthropic/claude-opus-4-6' } },
+                anthropic: 'anthropic/claude-opus-4-8' } },
   { alias: 'deepseek', label: 'DeepSeek flagship', blurb: 'open-source',
     vendorPath: 'deepseek',
     idPattern: /^deepseek-v[\d.]+(-pro)?$/,
@@ -62,9 +64,13 @@ const CARDLESS = [
   { alias: 'gpt-pro', routes: { openrouter: 'openrouter/openai/gpt-5.5-pro' } },
   // codex: newest codex-specific model on OpenRouter (verified 2026-06-09).
   { alias: 'codex', routes: { openrouter: 'openrouter/openai/gpt-5.3-codex' } },
-  { alias: 'claude', routes: { openrouter: 'openrouter/anthropic/claude-sonnet-4.6' } },
-  { alias: 'sonnet', routes: { openrouter: 'openrouter/anthropic/claude-sonnet-4.6' } },
-  { alias: 'haiku', routes: { openrouter: 'openrouter/anthropic/claude-haiku-4.5' } },
+  { alias: 'claude', routes: { openrouter: 'openrouter/anthropic/claude-sonnet-5',
+                                anthropic: 'anthropic/claude-sonnet-5' } },
+  { alias: 'sonnet', routes: { openrouter: 'openrouter/anthropic/claude-sonnet-5',
+                                anthropic: 'anthropic/claude-sonnet-5' } },
+  { alias: 'haiku', routes: { openrouter: 'openrouter/anthropic/claude-haiku-4.5',
+                              anthropic: 'anthropic/claude-haiku-4-5-20251001' } },
+  { alias: 'fable', routes: { openrouter: 'openrouter/anthropic/claude-fable-5' } },
   { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.7-max' } },
   { alias: 'qwen-coder', routes: { openrouter: 'openrouter/qwen/qwen3-coder-next' } },
   { alias: 'qwen-flash', routes: { openrouter: 'openrouter/qwen/qwen3.6-flash' } },
@@ -91,15 +97,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 +155,62 @@ function listCuratedRoutes() {
   return out;
 }
 
-module.exports = { getFamilies, toDefaultAliases, listCuratedRoutes };
+/**
+ * Vendors whose direct-API ids differ from OpenRouter's (dot vs. dash
+ * versioning, distinct model names, etc.). NEVER derive a direct form for
+ * these — derivation would emit the wrong (dot) id, or invent a direct id
+ * for a model that is OpenRouter-only today (e.g. fable).
+ */
+const DIVERGENT_VENDORS = new Set(['anthropic']);
+
+/**
+ * @param {string} orRoute e.g. 'openrouter/anthropic/claude-sonnet-5'
+ * @returns {string} the vendor segment, e.g. 'anthropic'
+ */
+function vendorOf(orRoute) {
+  const rest = orRoute.slice('openrouter/'.length);
+  return rest.slice(0, rest.indexOf('/'));
+}
+
+/**
+ * @param {string} vendorPath
+ * @param {Object<string,string>} obj a family.fallback or cardless.routes map
+ * @returns {string|undefined} the direct-API executable id, or undefined
+ * when no direct form is available for this alias.
+ */
+function directFormFor(vendorPath, obj) {
+  if (obj[vendorPath]) { return obj[vendorPath]; } // explicit, authored, current direct id
+  if (DIVERGENT_VENDORS.has(vendorPath)) { return undefined; } // no explicit form + divergent → omit
+  const bare = toCanonicalDefault(obj.openrouter); // safe only when ids are identical across gateways
+  return bare !== obj.openrouter ? bare : undefined; // gateway-only vendor → undefined
+}
+
+/**
+ * @param {string} vendorPath
+ * @param {Object<string,string>} obj a family.fallback or cardless.routes map
+ * @returns {{direct?: string, openrouter: string}}
+ */
+function gatewayRoutesFor(vendorPath, obj) {
+  const routes = { openrouter: obj.openrouter };
+  const direct = directFormFor(vendorPath, obj);
+  if (direct) { routes.direct = direct; }
+  return routes;
+}
+
+/**
+ * @returns {Object<string,{direct?: string, openrouter: string}>} alias →
+ * per-gateway executable ids. Unlike `toDefaultAliases` (a single pinned
+ * string per alias, used for display/`config.default`), this carries BOTH
+ * gateway-native forms so the router (Task 3) can route direct-first
+ * without corrupting divergent-vendor ids (e.g. Anthropic's dash format).
+ */
+function toGatewayRoutes() {
+  const out = {};
+  for (const f of FAMILIES) { out[f.alias] = gatewayRoutesFor(f.vendorPath, f.fallback); }
+  for (const e of CARDLESS) { out[e.alias] = gatewayRoutesFor(vendorOf(e.routes.openrouter), e.routes); }
+  return out;
+}
+
+module.exports = {
+  getFamilies, toDefaultAliases, toCanonicalDefault, listCuratedRoutes, toGatewayRoutes
+};

package/src/utils/gateway-route-audit.js

@@ -0,0 +1,103 @@
+/**
+ * Per-gateway-form audit for curated DEFAULT aliases (Task 6, #gwid).
+ *
+ * Complements the flat alias-audit.js (which audits the single pinned string
+ * per alias from `toDefaultAliases()`/`listCuratedRoutes()`): this audits
+ * BOTH gateway-native forms from `curated-models.toGatewayRoutes()` against
+ * the live catalog.
+ *
+ *   - STALE      a stored form's id is absent from its namespace.
+ *   - DIVERGENT  a direct-capable vendor's alias is missing a `direct` form
+ *                the catalog can now confirm ('divergent-missing'), or its
+ *                stored `direct` form no longer matches what the catalog
+ *                pairs ('divergent-mismatch').
+ *
+ * Never reports against data it cannot trust: a direct namespace the process
+ * has no key for is skipped, not flagged --
+ *   - STALE relies on classifyModel(), whose 'unknown' already covers this
+ *     (empty namespace, or every row a non-authoritative floor-fallback).
+ *   - DIVERGENT additionally re-checks `authoritative` itself, because
+ *     pairAcrossGateways() (Task 5) is a pure string matcher that has no
+ *     concept of authoritative vs. floor-fallback rows -- left unguarded, it
+ *     would happily "confirm" a direct pairing against the hardcoded
+ *     Anthropic offline floor (e.g. matching a dated id like
+ *     claude-haiku-4-5-20251001 to the floor's undated claude-haiku-4-5) and
+ *     report a false mismatch with no key present at all.
+ *
+ * Consumed by `amicus models --check` (Task 6); `--strict` gates the exit
+ * code on these findings.
+ */
+
+'use strict';
+
+const { toGatewayRoutes } = require('./curated-models');
+const { classifyModel } = require('./model-classification');
+const { pairAcrossGateways } = require('./gateway-route-catalog');
+const { isDirectProvider } = require('./provider-registry');
+
+const OR_PREFIX = 'openrouter/';
+
+/** @param {string} orId e.g. 'openrouter/anthropic/claude-sonnet-5' @returns {string|null} vendor segment */
+function vendorOf(orId) {
+  if (typeof orId !== 'string' || !orId.startsWith(OR_PREFIX)) { return null; }
+  const rest = orId.slice(OR_PREFIX.length);
+  const i = rest.indexOf('/');
+  return i > 0 ? rest.slice(0, i) : null;
+}
+
+/**
+ * Bare model segment for pairAcrossGateways' versionToken -- Task-5's locked
+ * calling convention: strip BOTH the `openrouter/` and `<vendor>/` prefixes
+ * before calling, never pass the route string verbatim.
+ * @param {string} orId @param {string} vendor @returns {string|null}
+ */
+function bareSegment(orId, vendor) {
+  const prefix = `${OR_PREFIX}${vendor}/`;
+  return typeof orId === 'string' && orId.startsWith(prefix) ? orId.slice(prefix.length) : null;
+}
+
+/** @returns {boolean} true only when `id` names a live-fetched (not floor-fallback) catalog row */
+function isAuthoritative(catalogInfo, id) {
+  const models = (catalogInfo && Array.isArray(catalogInfo.models)) ? catalogInfo.models : [];
+  const row = models.find(m => m && m.id === id);
+  return !!row && row.authoritative !== false;
+}
+
+/**
+ * @param {{models: Array<{id:string, authoritative?: boolean}>, lastRefreshError?: string|null}} catalogInfo
+ * @returns {Array<{alias:string, gateway:'direct'|'openrouter',
+ *   kind:'stale'|'divergent-missing'|'divergent-mismatch', model:string, expected?:string}>}
+ */
+function auditGatewayRoutes(catalogInfo) {
+  const routes = toGatewayRoutes();
+  const findings = [];
+
+  for (const [alias, forms] of Object.entries(routes)) {
+    for (const gateway of ['direct', 'openrouter']) {
+      const id = forms[gateway];
+      if (!id) { continue; }
+      if (classifyModel(id, gateway, catalogInfo) === 'invalid') {
+        findings.push({ alias, gateway, kind: 'stale', model: id });
+      }
+    }
+
+    const vendor = vendorOf(forms.openrouter);
+    if (!vendor || !isDirectProvider(vendor)) { continue; } // gateway-only vendor: no direct route ever possible
+    const token = bareSegment(forms.openrouter, vendor);
+    if (!token) { continue; }
+    const paired = pairAcrossGateways(vendor, token, catalogInfo); // Task-5 contract: bare segment only
+    if (!paired.direct || !isAuthoritative(catalogInfo, paired.direct)) { continue; } // unconfirmed -- never guess
+
+    if (!forms.direct) {
+      findings.push({ alias, gateway: 'direct', kind: 'divergent-missing', model: paired.direct });
+    } else if (forms.direct !== paired.direct) {
+      findings.push({
+        alias, gateway: 'direct', kind: 'divergent-mismatch', model: forms.direct, expected: paired.direct
+      });
+    }
+  }
+
+  return findings;
+}
+
+module.exports = { auditGatewayRoutes };

package/src/utils/gateway-route-catalog.js

@@ -0,0 +1,92 @@
+/**
+ * Conservative cross-gateway catalog pairing helper (Task 5, #gwid).
+ *
+ * The same model has a different id per gateway namespace: direct
+ * `anthropic/claude-opus-4-8` (dashes, sometimes a trailing date suffix)
+ * vs. OpenRouter `openrouter/anthropic/claude-opus-4.8` (dots). This module
+ * pairs the two rows for a given vendor + version token, using a normalized
+ * comparison key ONLY to decide whether two catalog rows refer to the same
+ * model -- it never derives, transforms, or invents an id. Every id this
+ * module returns is copied verbatim from `catalogInfo.models[].id`.
+ *
+ * Used ONLY by `amicus models --check` (Task 6) to audit/refresh the curated
+ * per-gateway route map -- NOT on any launch hot path. Correctness-when-
+ * uncertain matters more than cleverness here: when a namespace has zero or
+ * more than one plausible match, that side is OMITTED rather than guessed.
+ *
+ * Pure function: no I/O, no network, no catalog fetch.
+ */
+
+'use strict';
+
+const OPENROUTER_PREFIX = 'openrouter/';
+/** Trailing 8-digit date suffix (e.g. '-20251001'), comparison-only. */
+const TRAILING_DATE_RE = /-\d{8}$/;
+
+/**
+ * Normalize a catalog id or a caller-supplied version token into a
+ * comparison-only key: strip a leading `openrouter/`, strip a leading
+ * `<vendor>/`, lowercase, unify '.'/'-' separators (dots become dashes), and
+ * drop a trailing 8-digit date suffix. The result is NEVER returned to
+ * callers -- it exists solely to decide whether two strings name the same
+ * model.
+ * @param {string} raw
+ * @param {string} vendor
+ * @returns {string|null} normalized key, or null when `raw` isn't a string
+ */
+function normalizeKey(raw, vendor) {
+  if (typeof raw !== 'string' || raw.length === 0) { return null; }
+  let s = raw;
+  if (s.startsWith(OPENROUTER_PREFIX)) { s = s.slice(OPENROUTER_PREFIX.length); }
+  const vendorPrefix = `${vendor}/`;
+  if (s.startsWith(vendorPrefix)) { s = s.slice(vendorPrefix.length); }
+  s = s.toLowerCase().replace(/\./g, '-');
+  s = s.replace(TRAILING_DATE_RE, '');
+  return s;
+}
+
+/**
+ * Find, in `catalogInfo.models`, the direct-namespace id and the
+ * OpenRouter-namespace id that both correspond to the model named by
+ * `versionToken` for `vendor`.
+ *
+ * Matching is conservative: a side is only included when EXACTLY ONE row in
+ * that namespace normalizes to the same key as `versionToken`. Zero matches
+ * or more than one plausible match (ambiguous) both result in that side
+ * being omitted -- never a guessed/fuzzy pick.
+ *
+ * @param {string} vendor e.g. 'anthropic'
+ * @param {string} versionToken e.g. 'claude-opus-4-8' or 'claude-opus-4.8'
+ * @param {{models: Array<{id: string}>}} catalogInfo
+ * @returns {{direct?: string, openrouter?: string}} verbatim catalog ids only
+ */
+function pairAcrossGateways(vendor, versionToken, catalogInfo) {
+  const models = (catalogInfo && Array.isArray(catalogInfo.models)) ? catalogInfo.models : [];
+  const targetKey = normalizeKey(versionToken, vendor);
+  const result = {};
+  if (targetKey === null) { return result; }
+
+  const directPrefix = `${vendor}/`;
+  const openrouterPrefix = `${OPENROUTER_PREFIX}${vendor}/`;
+
+  const directMatches = [];
+  const openrouterMatches = [];
+
+  for (const row of models) {
+    if (!row || typeof row.id !== 'string') { continue; }
+    const id = row.id;
+    if (id.startsWith(openrouterPrefix)) {
+      if (normalizeKey(id, vendor) === targetKey) { openrouterMatches.push(id); }
+    } else if (id.startsWith(directPrefix)) {
+      if (normalizeKey(id, vendor) === targetKey) { directMatches.push(id); }
+    }
+  }
+
+  // Exactly one candidate required per side -- ambiguity (>1) is treated the
+  // same as absence (0): omit rather than guess.
+  if (directMatches.length === 1) { result.direct = directMatches[0]; }
+  if (openrouterMatches.length === 1) { result.openrouter = openrouterMatches[0]; }
+  return result;
+}
+
+module.exports = { pairAcrossGateways };

package/src/utils/gateway-router.js

@@ -0,0 +1,131 @@
+/**
+ * Pure gateway router (#61). Decides direct vs OpenRouter for a request using
+ * only injected state (keys, catalogInfo, gatewayMode) — no I/O. Returns a
+ * RouteResult (resolved | selection_required | error). Wired into live launch
+ * paths via route-launch.js's resolveRouteForLaunch (start-helpers.js,
+ * mcp-server.js, sidecar/fanout-validate.js).
+ */
+'use strict';
+
+const { resolved, routeError, selectionRequired, parseDescriptor } = require('./model-descriptor');
+const { classifyModel } = require('./model-classification');
+const { isDirectProvider } = require('./provider-registry');
+
+/** Build the executable id for a gateway. */
+function executableFor(gateway, vendor, model) {
+  return gateway === 'openrouter' ? `openrouter/${vendor}/${model}` : `${vendor}/${model}`;
+}
+
+/**
+ * Catalog gate: returns { ok:true, notice? } to proceed, or { ok:false, result }
+ * carrying a selection_required/error to return to the caller.
+ */
+function catalogGate({ id, gateway, req }) {
+  if (req.validateModel === false) {
+    return { ok: true, notice: 'Model availability not validated (--no-validate-model).' };
+  }
+  const verdict = classifyModel(id, gateway, req.catalogInfo);
+  if (verdict === 'valid') { return { ok: true }; }
+  if (verdict === 'unknown') {
+    return { ok: true, notice: `Model '${id}' is unverified against the ${gateway} catalog; attempting anyway.` };
+  }
+  // invalid
+  if (req.allowSelection) {
+    return { ok: false, result: selectionRequired({ requested: req.descriptor.raw, suggestions: [] }) };
+  }
+  return { ok: false, result: routeError({ requested: req.descriptor.raw, reason: 'model_not_found',
+    preferredGateway: gateway, suggestions: [] }) };
+}
+
+/**
+ * True when the given gateway is usable for this request: either the caller
+ * didn't supply per-gateway ids at all (back-compat: nothing to check), or it
+ * did and this specific gateway has a form in it.
+ */
+function hasForm(req, gateway) {
+  return !req.gatewayIds || req.gatewayIds[gateway] !== undefined;
+}
+
+/** Resolve to a concrete gateway after the catalog gate passes. */
+function finish(gateway, vendor, model, req) {
+  const id = (req.gatewayIds && req.gatewayIds[gateway]) || executableFor(gateway, vendor, model);
+  const gate = catalogGate({ id, gateway, req });
+  if (!gate.ok) { return gate.result; }
+  return resolved({ model: id, gateway, executableId: id,
+    provenance: { source: req.source, requested: req.descriptor.raw, gatewayMode: req.gatewayMode }, notice: gate.notice });
+}
+
+/**
+ * @param {object} req see Task 5 Interfaces
+ * @returns RouteResult
+ */
+function resolveRoute(req) {
+  // 1. Normalize: req.descriptor may arrive as a parsed Descriptor object or a
+  // raw canonical/OR-literal id string. Only canonical/openrouter-literal kinds
+  // are routable; alias/invalid/garbage descriptors are rejected right here,
+  // before any branch below touches vendor/model. All downstream code reads
+  // from the normalized `d` (via the cloned `rq`), never from req.descriptor.
+  let d = req.descriptor;
+  if (typeof d === 'string') {
+    d = parseDescriptor(d, { aliases: {} });
+  }
+  if (!d || (d.kind !== 'canonical' && d.kind !== 'openrouter-literal')) {
+    const requested = d ? d.raw : (typeof req.descriptor === 'string' ? req.descriptor : String(req && req.descriptor));
+    return routeError({ requested, reason: 'invalid_descriptor', preferredGateway: req.gatewayMode, suggestions: [] });
+  }
+  const rq = { ...req, descriptor: d };
+  const vendor = d.vendor;
+  const model = d.model;
+
+  // 2. Explicit conflict: force-OR literal vs --gateway direct
+  if (d.isExplicitOpenRouter && rq.gatewayMode === 'direct') {
+    return routeError({ requested: d.raw, reason: 'gateway_conflict', preferredGateway: 'direct', suggestions: [] });
+  }
+  // 3. Explicit OR literal
+  if (d.isExplicitOpenRouter) {
+    if (!rq.keys.openrouter) {
+      return routeError({ requested: d.raw, reason: 'no_openrouter_key', preferredGateway: 'openrouter', suggestions: [] });
+    }
+    return finish('openrouter', vendor, model, rq);
+  }
+  // 4. Gateway-only vendor (no direct integration)
+  if (!isDirectProvider(vendor)) {
+    if (rq.gatewayMode === 'direct') {
+      return routeError({ requested: d.raw, reason: 'no_direct_integration', preferredGateway: 'direct', suggestions: [] });
+    }
+    if (!rq.keys.openrouter) {
+      return routeError({ requested: d.raw, reason: 'no_openrouter_key', preferredGateway: 'openrouter', suggestions: [] });
+    }
+    return finish('openrouter', vendor, model, rq);
+  }
+  // 5. Explicit --gateway openrouter
+  if (rq.gatewayMode === 'openrouter') {
+    if (!rq.keys.openrouter) {
+      return routeError({ requested: d.raw, reason: 'no_openrouter_key', preferredGateway: 'openrouter', suggestions: [] });
+    }
+    if (!hasForm(rq, 'openrouter')) {
+      return routeError({ requested: d.raw, reason: 'openrouter_unavailable', preferredGateway: 'openrouter', suggestions: [] });
+    }
+    return finish('openrouter', vendor, model, rq);
+  }
+  // 6. Explicit --gateway direct
+  if (rq.gatewayMode === 'direct') {
+    if (!rq.keys[vendor]) {
+      return routeError({ requested: d.raw, reason: 'no_direct_key', preferredGateway: 'direct', suggestions: [] });
+    }
+    if (!hasForm(rq, 'direct')) {
+      return routeError({ requested: d.raw, reason: 'direct_unavailable', preferredGateway: 'direct', suggestions: [] });
+    }
+    return finish('direct', vendor, model, rq);
+  }
+  // 7. auto (direct-first)
+  if (rq.keys[vendor] && hasForm(rq, 'direct')) {
+    return finish('direct', vendor, model, rq);
+  }
+  if (rq.keys.openrouter && hasForm(rq, 'openrouter')) {
+    return finish('openrouter', vendor, model, rq);
+  }
+  return routeError({ requested: d.raw, reason: 'no_key_for_vendor', preferredGateway: 'direct', suggestions: [] });
+}
+
+module.exports = { resolveRoute };

package/src/utils/input-validators.js

@@ -3,7 +3,8 @@
 /**
  * @module input-validators
  * MCP input validation with structured error responses.
- * Composes validators from validators.js and adds model resolution.
+ * Composes validators from validators.js for prompt/timeout/agent checks.
+ * Model resolution/routing lives in mcp-server.js (#61 Task 6.2), not here.
  */
 
 // Lazy require to avoid circular dependency (validators.js re-exports from here)
@@ -13,26 +14,15 @@ function getValidators() {
   return _validators;
 }
 
-/**
- * Find candidates that start with the input or vice versa.
- * @param {string} input
- * @param {string[]} candidates
- * @returns {string[]} Up to 3 matching candidates
- */
-function findSimilar(input, candidates) {
-  if (!input) { return []; }
-  const lower = input.toLowerCase();
-  return candidates.filter(c => {
-    const cl = c.toLowerCase();
-    return cl.startsWith(lower) || lower.startsWith(cl);
-  }).slice(0, 3);
-}
-
 /**
  * Validate sidecar_start inputs before session creation.
- * Composes existing validators and adds model resolution.
+ * Composes existing validators for prompt/timeout/agent. Model resolution is
+ * NOT this function's concern (#61 Task 6.2): it is routed separately by the
+ * mcp-server.js amicus_start handler via resolveRouteForLaunch, so a routing
+ * failure can be rendered as a structured `model_route_error` (parity with the
+ * CLI's resolveLaunchModel) rather than the `validation_error` shape below.
  * @param {Object} input - Raw MCP tool input
- * @returns {{ valid: true, resolvedModel: string } | { valid: false, error: Object }}
+ * @returns {{ valid: true } | { valid: false, error: Object }}
  */
 function validateStartInputs(input) {
   // 1. Prompt
@@ -49,27 +39,7 @@ function validateStartInputs(input) {
     };
   }
 
-  // 2. Model: resolve alias to full provider/model string
-  const { tryResolveModel, getEffectiveAliases } = require('./config');
-  const { model: resolved, error: modelError } = tryResolveModel(input.model);
-  if (modelError) {
-    const aliases = Object.keys(getEffectiveAliases());
-    const suggestions = findSimilar(input.model, aliases);
-    return {
-      valid: false,
-      error: {
-        type: 'validation_error',
-        field: 'model',
-        message: input.model
-          ? `Model '${input.model}' not found. ${modelError}`
-          : `No model specified and no default configured. ${modelError}`,
-        suggestions,
-        available: aliases,
-      },
-    };
-  }
-
-  // 3. Timeout: positive number, max 60 minutes
+  // 2. Timeout: positive number, max 60 minutes
   if (input.timeout !== undefined) {
     const t = Number(input.timeout);
     if (isNaN(t) || t <= 0) {
@@ -94,7 +64,7 @@ function validateStartInputs(input) {
     }
   }
 
-  // 4. Agent + headless compatibility
+  // 3. Agent + headless compatibility
   // Note: MCP Zod schema defaults agent to 'Chat'. The handler auto-converts
   // Chat to Build for headless mode (line ~92 in mcp-server.js). Only reject
   // if the user explicitly set agent to Chat with noUi (not the Zod default).
@@ -121,7 +91,7 @@ function validateStartInputs(input) {
     }
   }
 
-  return { valid: true, resolvedModel: resolved };
+  return { valid: true };
 }
 
 /**
@@ -175,4 +145,4 @@ function suggestCommand(input, candidates, maxDistance = 2, maxSuggestions = 3)
     .map(({ c }) => c);
 }
 
-module.exports = { validateStartInputs, findSimilar, levenshteinDistance, suggestCommand };
+module.exports = { validateStartInputs, levenshteinDistance, suggestCommand };

package/src/utils/model-classification.js

@@ -0,0 +1,65 @@
+/**
+ * Tri-state catalog classification (#61).
+ * Turns the combined catalog + refresh outcome into valid|invalid|unknown for a
+ * (model, gateway) pair. `unknown` NEVER rejects a route — it preserves the
+ * existing "empty catalog cannot validate, never block a launch" contract.
+ *
+ * Namespace matching is scoped PER-VENDOR, not by a flat openrouter/direct
+ * split. The combined catalog always contains a hardcoded Anthropic floor, so
+ * a flat "direct" namespace is never empty even when a specific vendor's rows
+ * were never fetched (e.g. that provider's /models call was stale or failed).
+ * Matching per-vendor means a missing vendor's rows correctly yield `unknown`
+ * instead of being masked by the always-present floor rows of another vendor.
+ *
+ * - gateway === 'direct': vendor = id.split('/')[0]; namespace prefix is
+ *   `${vendor}/`, restricted to rows NOT under `openrouter/`.
+ * - gateway === 'openrouter': id looks like `openrouter/<vendor>/<model>`, so
+ *   vendor = id.split('/')[1]; namespace prefix is `openrouter/${vendor}/`.
+ *
+ * Non-authoritative rows (`authoritative: false`, e.g. the hardcoded Anthropic
+ * floor-fallback tagged by model-fetcher.js when a keyed live fetch fails or no
+ * key is present — see fetchModelsFromProvider('anthropic', key)) cannot assert
+ * absence either: if EVERY row in the matched namespace is non-authoritative and
+ * the exact id is not among them, a miss returns `unknown`, not `invalid` — the
+ * floor is a stale/synthesized list, not a confirmed model roster, so it must
+ * never hard-block a launch (#61 4.3). A namespace containing at least one
+ * authoritative (live-fetched) row still yields `invalid` on a genuine miss.
+ *
+ * Pure: the caller passes catalogInfo (from model-catalog.getCatalogInfo()).
+ * @param {string} id       exact model id as the user gave it
+ * @param {'direct'|'openrouter'} gateway  which namespace to match against
+ * @param {{models: Array<{id:string, authoritative?: boolean}>, lastRefreshError?: string|null}} catalogInfo
+ * @returns {'valid'|'invalid'|'unknown'}
+ */
+function classifyModel(id, gateway, catalogInfo) {
+  const models = (catalogInfo && Array.isArray(catalogInfo.models)) ? catalogInfo.models : [];
+  if (models.length === 0) { return 'unknown'; }
+
+  const idParts = typeof id === 'string' ? id.split('/') : [];
+  const isOpenRouter = gateway === 'openrouter';
+  const vendor = isOpenRouter ? idParts[1] : idParts[0];
+  const nsPrefix = isOpenRouter ? `openrouter/${vendor}/` : `${vendor}/`;
+
+  const inNamespace = (mid) => {
+    if (typeof mid !== 'string' || !mid.startsWith(nsPrefix)) { return false; }
+    return isOpenRouter ? true : !mid.startsWith('openrouter/');
+  };
+  const namespaceRows = models.filter(m => m && typeof m.id === 'string' && inNamespace(m.id));
+
+  // No rows for this vendor's namespace -> we cannot assert absence (e.g. that
+  // provider's key is absent so its rows were never fetched, or a partial
+  // refresh). Unknown — never block on a namespace we couldn't populate.
+  if (namespaceRows.length === 0) { return 'unknown'; }
+
+  const present = namespaceRows.some(m => m.id === id);
+  if (present) { return 'valid'; }
+
+  // Every matched row is a non-authoritative floor-fallback row (never live-
+  // fetched) -> a miss cannot be trusted as a confirmed absence. Never block.
+  const allNonAuthoritative = namespaceRows.every(m => m.authoritative === false);
+  if (allNonAuthoritative) { return 'unknown'; }
+
+  return 'invalid';
+}
+
+module.exports = { classifyModel };