@mmmbuto/nexuscrew 0.9.75 → 0.9.77

package/lib/fleet/model-discovery.js

@@ -44,7 +44,9 @@ const CACHE_VERSION = 1;
 const MAX_SHOW_CALLS = 32;      // Ollama /api/show: only listed ids the caller asked about
 const ANTHROPIC_MAX_PAGES = 5;  // pagination safety bound
 const ANTHROPIC_VERSION = '2023-06-01';
-const MODEL_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+// Bracketed markers such as `[1m]` are part of the model id the fleet file
+// accepts; they are kept intact and never stripped for a basename match.
+const MODEL_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:/\[\]-]{0,127}$/;
 const ENGINE_KEY_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
 const MERGE_FIELDS = Object.freeze(['contextWindow', 'maxTokens', 'tools', 'vision', 'reasoning', 'deprecated']);
 
@@ -59,11 +61,21 @@ function collectorDefaultTtlMs(collector) {
 
 // Sanitized failure: fixed reason strings only. The raw fetch error can embed
 // the request URL; the key lives in headers — neither may surface here.
+// The optional `attempt` object adds the FIXED facts of the request that
+// failed (numeric HTTP status, error category, whether the credential header
+// was applied). Internal diagnostics for the fallback chain: they ride
+// DiscoveryError and the layer results, never a route response — the public
+// face stays the sanitized `reason` above.
 class DiscoveryError extends Error {
-  constructor(reason) {
+  constructor(reason, attempt = null) {
     super(`model discovery: ${reason}`);
     this.name = 'DiscoveryError';
     this.reason = reason;
+    if (attempt && typeof attempt === 'object') {
+      if (Number.isSafeInteger(attempt.status)) this.status = attempt.status;
+      if (typeof attempt.category === 'string') this.category = attempt.category;
+      if (typeof attempt.credentialSent === 'boolean') this.credentialSent = attempt.credentialSent;
+    }
   }
 }
 
@@ -114,6 +126,10 @@ async function httpJson(url, {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   const isAbort = (error) => !!(error && (error.name === 'AbortError' || error.code === 'ABORT_ERR'));
+  // Direct transport: the credential header is applied exactly when a key is
+  // valued (pinned by tests with a header-capturing fake fetch) — that is what
+  // `credentialSent` reports on every failure below.
+  const credentialSent = !!apiKey;
   try {
     const headers = { accept: 'application/json' };
     if (body !== undefined) headers['content-type'] = 'application/json';
@@ -134,23 +150,27 @@ async function httpJson(url, {
         ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
       });
     } catch (error) {
-      throw new DiscoveryError(isAbort(error) ? `timeout after ${timeoutMs}ms` : 'network error');
+      throw new DiscoveryError(isAbort(error) ? `timeout after ${timeoutMs}ms` : 'network error', {
+        category: isAbort(error) ? 'timeout' : 'network', credentialSent,
+      });
     }
     // Minimal fakes (and some SDK shims) carry `ok` without `status`: honor
     // `ok === true` as 200, mirroring the previous discoverOllamaModels check.
     const okFlag = !!(response && typeof response === 'object' && response.ok === true);
     const status = response && typeof response.status === 'number' ? response.status : (okFlag ? 200 : 0);
-    if (!(status >= 200 && status < 300)) throw new DiscoveryError(`HTTP ${status}`);
+    if (!(status >= 200 && status < 300)) throw new DiscoveryError(`HTTP ${status}`, { status, category: 'http', credentialSent });
     let parsed;
     try {
       parsed = await response.json();
     } catch (error) {
       // The timer is still armed here: an abort while reading the body is the
       // deadline expiring again, not a malformed payload.
-      throw new DiscoveryError(isAbort(error) ? `timeout after ${timeoutMs}ms` : 'invalid JSON response');
+      throw new DiscoveryError(isAbort(error) ? `timeout after ${timeoutMs}ms` : 'invalid JSON response', {
+        category: isAbort(error) ? 'timeout' : 'invalid-response', credentialSent,
+      });
     }
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      throw new DiscoveryError('unexpected response shape');
+      throw new DiscoveryError('unexpected response shape', { category: 'invalid-response', credentialSent });
     }
     return parsed;
   } finally {
@@ -418,9 +438,10 @@ function writePublicCatalogCache(home, fetchedAt, catalog) {
 
 // --- Public catalog mapping --------------------------------------------------
 // Engine provider -> catalog provider id, as an explicit, TESTED table: no
-// inference. Unlisted providers (local runtimes, login accounts, custom
-// gateways on unknown hosts) get NO public layer at all — a missing mapping
-// means no data, never a guess.
+// inference. The mapping decides the FIRST lookup namespace (the most
+// pertinent one for that endpoint); every provider — local runtimes, custom
+// gateways on unknown hosts included — can still be enriched by the by-id
+// fallback below, which never guesses a namespace: it matches ids only.
 
 const PUBLIC_CATALOG_PROVIDER_IDS = Object.freeze({
   zai: 'zai',
@@ -462,28 +483,225 @@ function publicCatalogProviderId({ provider, baseUrl } = {}) {
   return PUBLIC_CATALOG_HOSTS[host] || null;
 }
 
-// Candidate catalog ids for one API model id, best first: exact, case-folded,
-// one "vendor/" prefix dropped, then each of those without a ":cloud"/"-cloud"
-// suffix. Context-variant markers like "[1m]" are deliberately NOT stripped:
-// inheriting the base model's limits would import wrong numbers.
-function publicCatalogIdCandidates(apiId) {
-  const out = [];
-  const push = (v) => { if (v && !out.includes(v)) out.push(v); };
+// --- Public catalog by-id fallback --------------------------------------------
+// Resolution per model id, in tiers. A tier's candidates are ALL the entries
+// of that tier — never the first in Object.keys order — and the first tier
+// (strongest first) that has candidates wins: weaker tiers are never
+// consulted afterwards, so a conflict among the winning tier's candidates
+// cannot be dodged by descending, and the snapshot's provider/key order
+// cannot change the outcome.
+//
+//   1. mapped: the namespace of the engine's EXPLICIT provider/host mapping.
+//      A field present here is never replaced by global consensus.
+//   2. vendor: the namespace of a vendor prefix recognized by the explicit
+//      table below, with the prefix removed for this resolution only. Any
+//      other first segment is NOT a vendor and is never stripped.
+//   3. global exact → 4. global case-folded → 5. global ":cloud"/"-cloud"
+//      suffix stripped. Tags, versions, quantizations and "[1m]" markers are
+//      never removed; the row keeps its original API id.
+//
+// Within the winning tier the agreement is per normalized field: a value
+// enters when at least one valid value exists and all valid values are equal;
+// absent/invalid values abstain (they are neither false nor zero), `false` is
+// a value, and a disagreement leaves the field absent (counted, bounded).
+
+// Vendor prefixes recognized for the namespace tier. Explicit and tested: a
+// first segment not in this table is not a vendor, and is never stripped. The
+// values are catalog provider ids, mirroring PUBLIC_CATALOG_PROVIDER_IDS.
+const PUBLIC_CATALOG_VENDOR_IDS = Object.freeze({
+  zai: 'zai',
+  'z-ai': 'zai',
+  anthropic: 'anthropic',
+  openai: 'openai',
+  deepseek: 'deepseek',
+  openrouter: 'openrouter',
+  nvidia: 'nvidia',
+  xai: 'xai',
+  'ollama-cloud': 'ollama-cloud',
+  'opencode-go': 'opencode-go',
+});
+const PUBLIC_CATALOG_VENDOR_IDS_FOLDED = new Map(
+  Object.entries(PUBLIC_CATALOG_VENDOR_IDS).map(([k, v]) => [k.toLowerCase(), v])
+);
+
+function publicCatalogVendorProviderId(prefix) {
+  const p = String(prefix || '');
+  return PUBLIC_CATALOG_VENDOR_IDS[p] || PUBLIC_CATALOG_VENDOR_IDS_FOLDED.get(p.toLowerCase()) || null;
+}
+
+// `z-ai/glm-5.3` -> { providerId: 'zai', rest: 'glm-5.3' }. Only the FIRST
+// segment is considered, and only when the explicit table recognizes it.
+function publicCatalogVendorSplit(apiId) {
   const id = String(apiId || '');
-  push(id);
-  push(id.toLowerCase());
   const slash = id.indexOf('/');
-  if (slash > 0 && slash < id.length - 1) {
-    push(id.slice(slash + 1));
-    push(id.slice(slash + 1).toLowerCase());
+  if (slash <= 0 || slash >= id.length - 1) return null;
+  const providerId = publicCatalogVendorProviderId(id.slice(0, slash));
+  return providerId ? { providerId, rest: id.slice(slash + 1) } : null;
+}
+
+function stripCloudSuffix(id) { return id.replace(/(?::cloud|-cloud)$/, ''); }
+
+// Index over one snapshot object, reused across rows and engines, never
+// persisted: a plain WeakMap keyed by the catalog object itself, so each
+// actual snapshot (including one read with noCache) has its own index and a
+// dropped snapshot drops its index with it. Built once per snapshot, not per
+// row.
+const publicCatalogIndexes = new WeakMap();
+
+function publicCatalogIndex(catalog) {
+  if (!catalog || typeof catalog !== 'object' || Array.isArray(catalog)) return null;
+  const cached = publicCatalogIndexes.get(catalog);
+  if (cached) return cached;
+  const providers = new Map();  // providerId -> { exact: Map(key->entry), folded: Map(lc->[entry]) }
+  const globalExact = new Map(); // key -> [entry]
+  const globalFolded = new Map(); // lc(key) -> [entry]
+  for (const [providerId, provider] of Object.entries(catalog)) {
+    if (!provider || typeof provider !== 'object' || Array.isArray(provider)) continue;
+    const models = provider.models && typeof provider.models === 'object' && !Array.isArray(provider.models)
+      ? provider.models : null;
+    if (!models) continue;
+    const exact = new Map();
+    const folded = new Map();
+    for (const [key, model] of Object.entries(models)) {
+      if (!model || typeof model !== 'object' || Array.isArray(model)) continue;
+      const entry = { provider: providerId, key, fields: normalizePublicCatalogModel(key, model) };
+      exact.set(key, entry);
+      const lc = key.toLowerCase();
+      if (folded.has(lc)) folded.get(lc).push(entry); else folded.set(lc, [entry]);
+      if (globalExact.has(key)) globalExact.get(key).push(entry); else globalExact.set(key, [entry]);
+      if (globalFolded.has(lc)) globalFolded.get(lc).push(entry); else globalFolded.set(lc, [entry]);
+    }
+    providers.set(providerId, { exact, folded });
   }
-  for (const base of [...out]) {
-    const stripped = base.replace(/(?::cloud|-cloud)$/, '');
-    if (stripped !== base) { push(stripped); push(stripped.toLowerCase()); }
+  const index = { providers, globalExact, globalFolded };
+  publicCatalogIndexes.set(catalog, index);
+  return index;
+}
+
+// First non-empty tier (exact -> case-folded -> cloud-suffix stripped) within
+// one provider namespace; ALL candidates of that tier, deduplicated.
+function publicCatalogNamespaceCandidates(index, providerId, apiId) {
+  const ns = index.providers.get(providerId);
+  if (!ns) return [];
+  const id = String(apiId || '');
+  const out = [];
+  const seen = new Set();
+  const add = (entries) => {
+    for (const entry of entries || []) if (!seen.has(entry)) { seen.add(entry); out.push(entry); }
+  };
+  const exact = ns.exact.get(id);
+  if (exact) return [exact];
+  add(ns.folded.get(id.toLowerCase()));
+  if (out.length) return out;
+  const stripped = stripCloudSuffix(id);
+  if (stripped !== id) {
+    const sExact = ns.exact.get(stripped);
+    if (sExact) return [sExact];
+    add(ns.folded.get(stripped.toLowerCase()));
   }
   return out;
 }
 
+// Same tier ladder across every provider of the snapshot.
+function publicCatalogGlobalCandidates(index, apiId) {
+  const id = String(apiId || '');
+  const out = [];
+  const seen = new Set();
+  const add = (entries) => {
+    for (const entry of entries || []) if (!seen.has(entry)) { seen.add(entry); out.push(entry); }
+  };
+  const exact = index.globalExact.get(id);
+  if (exact) { add(exact); return out; }
+  add(index.globalFolded.get(id.toLowerCase()));
+  if (out.length) return out;
+  const stripped = stripCloudSuffix(id);
+  if (stripped !== id) {
+    const sExact = index.globalExact.get(stripped);
+    if (sExact) { add(sExact); return out; }
+    add(index.globalFolded.get(stripped.toLowerCase()));
+  }
+  return out;
+}
+
+// Per-field agreement among one tier's candidates, restricted to `allowed`
+// fields (null = all fields). Absent/invalid values abstain; a disagreement
+// is a conflict and leaves the field absent.
+function publicCatalogAgreement(entries, allowed) {
+  const values = {};
+  const conflictFields = [];
+  let noData = 0;
+  for (const field of MERGE_FIELDS) {
+    if (allowed && !allowed.has(field)) continue;
+    const vals = [];
+    for (const entry of entries) {
+      const v = entry.fields[field];
+      if (v !== undefined) vals.push(v);
+    }
+    if (!vals.length) { noData += 1; continue; }
+    if (vals.every((v) => v === vals[0])) values[field] = vals[0];
+    else conflictFields.push(field);
+  }
+  return { values, conflictFields, noData };
+}
+
+function resolvePublicCatalogRow(index, mappedProviderId, apiId) {
+  const fields = {};
+  const blocked = new Set();
+  // Tier 1: the mapped namespace of the engine's actual provider. Fields
+  // present here stay; a field this tier disagrees on is blocked — a weaker
+  // tier must not be used to dodge the conflict.
+  if (mappedProviderId) {
+    const entries = publicCatalogNamespaceCandidates(index, mappedProviderId, apiId);
+    if (entries.length) {
+      const agg = publicCatalogAgreement(entries, null);
+      Object.assign(fields, agg.values);
+      for (const f of agg.conflictFields) blocked.add(f);
+    }
+  }
+  const allowed = new Set(MERGE_FIELDS.filter((f) => fields[f] === undefined && !blocked.has(f)));
+  // The mapped tier's conflicts are diagnostics too: a field blocked here is
+  // never consulted again, so counting it here and the fallback's own
+  // conflicts later cannot count the same field twice.
+  const stats = { matched: false, enriched: false, conflicts: blocked.size, noData: 0 };
+  if (!allowed.size) return { fields, stats };
+  // By-id ladder: a recognized vendor namespace first, then the global tiers.
+  // The first step with candidates wins; weaker steps are never consulted.
+  const split = publicCatalogVendorSplit(apiId);
+  let entries = split ? publicCatalogNamespaceCandidates(index, split.providerId, split.rest) : [];
+  if (!entries.length) entries = publicCatalogGlobalCandidates(index, apiId);
+  if (!entries.length) return { fields, stats };
+  stats.matched = true;
+  const agg = publicCatalogAgreement(entries, allowed);
+  Object.assign(fields, agg.values);
+  stats.conflicts = blocked.size + agg.conflictFields.length;
+  stats.noData = agg.noData;
+  stats.enriched = Object.keys(agg.values).length > 0;
+  return { fields, stats };
+}
+
+// Records plus bounded by-id counters for a set of proposal ids. Records keep
+// the API id unchanged, so they merge onto the engine's own listing; ids that
+// resolve to nothing produce no record — the model keeps whatever the other
+// layers say. The public layer never adds a model to the proposal.
+function resolvePublicCatalogRecords(catalog, mappedProviderId, modelIds) {
+  const records = [];
+  const byId = { rows: 0, enriched: 0, conflicts: 0, noData: 0 };
+  const index = publicCatalogIndex(catalog);
+  if (!index) return { records, byId };
+  const seen = new Set();
+  for (const apiId of Array.isArray(modelIds) ? modelIds : []) {
+    if (typeof apiId !== 'string' || !apiId || seen.has(apiId)) continue;
+    seen.add(apiId);
+    const { fields, stats } = resolvePublicCatalogRow(index, mappedProviderId, apiId);
+    if (stats.matched) byId.rows += 1;
+    if (stats.enriched) byId.enriched += 1;
+    byId.conflicts += stats.conflicts;
+    byId.noData += stats.noData;
+    if (Object.keys(fields).length) records.push({ id: apiId, ...fields });
+  }
+  return { records, byId };
+}
+
 // One normalized record per MATCHING api id. The record keeps the API id, so
 // it merges onto the engine's own listing; catalog fields map as:
 // limit.context -> contextWindow, limit.output -> maxTokens, tool_call ->
@@ -502,33 +720,9 @@ function normalizePublicCatalogModel(id, m) {
   return out;
 }
 
+// Backward-compatible shape: the resolved records alone.
 function publicCatalogRecords(catalog, providerId, modelIds) {
-  const provider = catalog && typeof catalog === 'object' && !Array.isArray(catalog) ? catalog[providerId] : null;
-  const models = provider && typeof provider === 'object' && !Array.isArray(provider)
-    && provider.models && typeof provider.models === 'object' && !Array.isArray(provider.models)
-    ? provider.models : null;
-  if (!models) return [];
-  const lcIndex = new Map();
-  for (const key of Object.keys(models)) {
-    const lc = key.toLowerCase();
-    if (!lcIndex.has(lc)) lcIndex.set(lc, key);
-  }
-  const out = [];
-  const seen = new Set();
-  for (const apiId of Array.isArray(modelIds) ? modelIds : []) {
-    if (typeof apiId !== 'string' || !apiId || seen.has(apiId)) continue;
-    seen.add(apiId);
-    let entry = null;
-    for (const cand of publicCatalogIdCandidates(apiId)) {
-      const hit = Object.prototype.hasOwnProperty.call(models, cand)
-        ? models[cand]
-        : (lcIndex.has(cand.toLowerCase()) ? models[lcIndex.get(cand.toLowerCase())] : null);
-      if (hit && typeof hit === 'object' && !Array.isArray(hit)) { entry = hit; break; }
-    }
-    // No match -> no record: the model keeps whatever the other layers say.
-    if (entry) out.push(normalizePublicCatalogModel(apiId, entry));
-  }
-  return out;
+  return resolvePublicCatalogRecords(catalog, providerId, modelIds).records;
 }
 
 // --- Precedence merge -------------------------------------------------------
@@ -630,13 +824,24 @@ function createModelDiscovery({ fetchImpl: defaultFetchImpl = globalThis.fetch,
       apiModels = await collectors[collector]({ baseUrl, apiKey, fetchImpl, timeoutMs, detailIds });
     } catch (error) {
       const reason = error instanceof DiscoveryError ? error.reason : 'discovery failed';
+      // Attempt metadata of the failed request rides the fallback so the
+      // caller can diagnose WHAT rejected the listing (fixed status/category,
+      // credential applied or not). Ephemeral only: nothing here is cached.
+      const failed = error instanceof DiscoveryError && typeof error.credentialSent === 'boolean'
+        ? {
+          ...(Number.isSafeInteger(error.status) ? { status: error.status } : {}),
+          ...(typeof error.category === 'string' ? { category: error.category } : {}),
+          credentialSent: error.credentialSent,
+        }
+        : null;
       if (cached) {
         return {
           status: 'cache', fetchedAt: cached.fetchedAt, stale: true, error: reason,
+          ...(failed ? { attempt: failed } : {}),
           apiModels: cached.models.map((m) => ({ ...m })),
         };
       }
-      return { status: 'backup', fetchedAt: 0, stale: false, error: reason, apiModels: [] };
+      return { status: 'backup', fetchedAt: 0, stale: false, error: reason, ...(failed ? { attempt: failed } : {}), apiModels: [] };
     }
     const fetchedAt = now();
     // Il delta degli spariti si calcola SOLO su una lettura vera: la risposta
@@ -654,6 +859,9 @@ function createModelDiscovery({ fetchImpl: defaultFetchImpl = globalThis.fetch,
     }
     return {
       status: 'api', fetchedAt, stale: false, error: '',
+      // The listing request went out: whether it carried the credential is
+      // what separates an anonymous success from an authenticated one.
+      attempt: { credentialSent: !!apiKey },
       apiModels: apiModels.map((m) => ({ ...m })),
       ...(disappeared.length ? { disappeared } : {}),
     };
@@ -713,25 +921,34 @@ function createModelDiscovery({ fetchImpl: defaultFetchImpl = globalThis.fetch,
     return { status: 'api', fetchedAt, stale: false, error: '', catalog };
   }
 
-  // Public layer for one engine: map the provider, snapshot the catalog (its
-  // own TTL, cache and fallback), then normalize records for the ids the
-  // engine already knows from the user/api/backup layers. The public catalog
-  // COMPLETES fields; it never adds models to the proposal. An unmapped
-  // provider skips the network entirely.
-  async function resolvePublicCatalogLayer(opts, apiModels, userModels, backupModels) {
+  // Public layer for one engine: resolve the provider mapping, snapshot the
+  // catalog (its own TTL, cache and fallback), then enrich the ids the
+  // engine's proposal already carries — from the mapped namespace first, and
+  // for the fields still absent (or without a mapping at all) by id across
+  // the whole snapshot: custom gateways and local endpoints included. The
+  // public catalog COMPLETES fields; it never adds models to the proposal.
+  // Nothing about the engine's endpoint (model names, URLs, keys) is ever
+  // sent to the catalog: the fetch is the one fixed public snapshot URL,
+  // keyless. With no id to enrich the snapshot is not fetched at all.
+  async function resolvePublicCatalogLayer(opts, apiModels, userModels, backupModels, knownIds) {
     const config = opts.publicCatalog && typeof opts.publicCatalog === 'object' ? opts.publicCatalog : {};
     const providerId = publicCatalogProviderId(config);
-    if (!providerId) {
-      return { providerId: null, records: [], summary: { providerId: null, status: 'skipped', records: 0 } };
-    }
     const ids = [];
     const seen = new Set();
+    const pushId = (id) => { if (id && !seen.has(id)) { seen.add(id); ids.push(id); } };
     for (const list of [userModels, apiModels, backupModels]) {
       for (const m of Array.isArray(list) ? list : []) {
-        const id = m && typeof m.id === 'string' ? m.id : null;
-        if (id && !seen.has(id)) { seen.add(id); ids.push(id); }
+        pushId(m && typeof m.id === 'string' ? m.id : null);
       }
     }
+    // Known-gone ids stay in the proposal as bare rows: they are enrichable
+    // like any other id already present.
+    for (const id of Array.isArray(knownIds) ? knownIds : []) {
+      pushId(typeof id === 'string' ? id : null);
+    }
+    if (!ids.length) {
+      return { providerId, records: [], summary: { providerId, status: 'skipped', records: 0 } };
+    }
     // `noCache` is ONE contract on BOTH layers: a forced refresh that skips
     // the engine cache skips the public snapshot too. The engine-level flag
     // reaches the snapshot unless the publicCatalog config overrides it.
@@ -749,12 +966,16 @@ function createModelDiscovery({ fetchImpl: defaultFetchImpl = globalThis.fetch,
         summary: { providerId, status: snapshot.status, error: snapshot.error, records: 0 },
       };
     }
-    const records = publicCatalogRecords(snapshot.catalog, providerId, ids);
+    const { records, byId } = resolvePublicCatalogRecords(snapshot.catalog, providerId, ids);
     return {
       providerId, records,
       summary: {
         providerId, status: snapshot.status, fetchedAt: snapshot.fetchedAt,
         stale: snapshot.stale, error: snapshot.error, records: records.length,
+        // Additive, bounded by-id counters (consumed by the view layer):
+        // rows matched by id, rows that received at least one field, fields
+        // blocked by disagreement, fields with no data among the candidates.
+        byId: { rows: byId.rows, enriched: byId.enriched, conflicts: byId.conflicts, noData: byId.noData },
       },
     };
   }
@@ -767,22 +988,37 @@ function createModelDiscovery({ fetchImpl: defaultFetchImpl = globalThis.fetch,
   async function discoverEngine(opts = {}) {
     const {
       userModels = [], backupModels = [], publicCatalogModels, publicCatalog,
-      cap = DISCOVERY_PROPOSAL_CAP,
+      cap = DISCOVERY_PROPOSAL_CAP, apiAvailable = true, knownIds = [],
     } = opts;
-    const layer = await fetchEngineModels(opts);
+    // An engine with no listing endpoint still has ids worth enriching: the
+    // declared models and the profile backup. There is no API layer at all —
+    // not a fake collector and not a fake fetch — so the merge runs with the
+    // API explicitly unavailable and never claims an API answer.
+    const layer = apiAvailable
+      ? await fetchEngineModels(opts)
+      : { status: 'unsupported', fetchedAt: 0, apiModels: [], stale: false, error: '', disappeared: [] };
     let publicModels = Array.isArray(publicCatalogModels) ? publicCatalogModels : [];
     let publicLayer = null;
+    // Ids that are known from configuration but are not a user declaration
+    // (for example the engine's own active model). They join the public layer
+    // as bare ids: they can be enriched, never invented with values, and they
+    // stay after the declared ids in the proposal order.
+    const configuredIds = (Array.isArray(knownIds) ? knownIds : [])
+      .filter((id) => typeof id === 'string' && id);
+    const knownLayerIds = [...(layer.disappeared || []), ...configuredIds];
     if (!Array.isArray(publicCatalogModels) && publicCatalog) {
-      publicLayer = await resolvePublicCatalogLayer(opts, layer.apiModels, userModels, backupModels);
+      publicLayer = await resolvePublicCatalogLayer(
+        opts, layer.apiModels, userModels, backupModels, knownLayerIds
+      );
       publicModels = publicLayer.records;
     }
-    const apiKnown = layer.status !== 'backup';
+    const apiKnown = apiAvailable && layer.status !== 'backup';
     const models = mergeModelRecords({
       userModels,
       apiModels: layer.apiModels,
       publicCatalogModels: publicModels,
       backupModels,
-      knownModels: (layer.disappeared || []).map((id) => ({ id })),
+      knownModels: knownLayerIds.map((id) => ({ id })),
       apiKnown,
       fetchedAt: layer.fetchedAt || now(),
       cap,
@@ -808,7 +1044,9 @@ module.exports = {
   PUBLIC_CATALOG_URL,
   PUBLIC_CATALOG_TTL_MS,
   publicCatalogProviderId,
-  publicCatalogIdCandidates,
+  publicCatalogVendorProviderId,
+  publicCatalogVendorSplit,
+  resolvePublicCatalogRecords,
   publicCatalogRecords,
   DISCOVERY_PROPOSAL_CAP,
   DEFAULT_TIMEOUT_MS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.9.75",
+  "version": "0.9.77",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {