amicus 4.8.0 → 4.9.0

package/src/utils/engine-skew-records.js

@@ -0,0 +1,146 @@
+/**
+ * @module utils/engine-skew-records
+ * Server identity and the bounded store of standing engine-skew records.
+ *
+ * EXTRACTED from src/utils/engine-skew.js (v4.9 W10 round 2), which owns the
+ * comparison, the announcement and the remedy text and had reached the 300-line
+ * gate. Everything here answers one question instead — WHICH SERVER is this,
+ * and what was last observed about it — and that is where the round-2 findings
+ * on identity collapse (A3), the shared unknown bucket (B3) and unbounded growth
+ * (B7) all landed. `engine-skew.js` re-exports the public half, so callers and
+ * tests keep one import site.
+ *
+ * BEST-EFFORT, like its parent: an identity read on a diagnostic path must not
+ * be able to fail a session create, so nothing here throws.
+ */
+
+'use strict';
+
+/**
+ * The standing skew records: server identity -> `{server, installed}`, holding
+ * the LAST comparison observed for that server (see noteSessionVersion). Not a
+ * single process-wide slot (W10 round-1 review A3+B3): one slot stamped the
+ * first skew ever seen onto every later failure, including failures of an
+ * unrelated server and failures after the skew was fixed mid-run.
+ */
+const _skewByServer = new Map();
+
+/** The key used when the client cannot name its server. Distinct from every
+ *  real base URL, so an unidentified server borrows no one else's record. */
+const UNKNOWN_SERVER_KEY = '<unknown server>';
+
+/**
+ * How many servers the map remembers (round-2 review B7). This is
+ * process-lifetime state on a path that runs once per session create — every
+ * fanout leg, every council seat, for as long as an MCP server stays up — and
+ * its key is a server URL, which an operator controls. 32 is far past any real
+ * topology (production talks to ONE spawned server per process) while still
+ * being a bound rather than a hope.
+ */
+const MAX_SKEW_SERVERS = 32;
+
+/**
+ * The identity of the server this client talks to — its base URL, normalized to
+ * an origin AND path.
+ *
+ * MEASURED 2026-08-25 against this checkout's `@opencode-ai/sdk`, not read off
+ * the types: `createOpencodeClient({ baseUrl })` returns an object whose only
+ * non-namespace key is `_client`, and `client._client.getConfig()` answers
+ * `{bodySerializer, headers, parseAs, querySerializer, baseUrl, fetch}` — the
+ * `baseUrl` being exactly the string passed in, and `undefined` when none was.
+ * That is the SMALLEST honest key available at session-create time: no round
+ * trip, no new SDK call, and in production `startServer` always builds the
+ * client from one spawned server's own `sdkServer.url`, so distinct servers get
+ * distinct ports and distinct keys. It is an identity, not proof of identity —
+ * two amicus processes that spawn servers on the same port at different times
+ * would collide — which is why every record is also refreshed on each create.
+ *
+ * THE PATH IS PART OF THE KEY (round-2 review A3). `new URL(raw).origin` alone
+ * collapses two distinct servers onto one record whenever they share an origin
+ * — a reverse proxy at `…:8080/engine-a` and `…:8080/engine-b`, and MEASURED
+ * 2026-08-26, EVERY opaque-origin URL: `new URL('unix:///tmp/a.sock').origin`
+ * and its `b.sock` twin are both the literal string `"null"`. A shared record
+ * is precisely what per-server keying exists to prevent. Amicus's own topology
+ * cannot reach it today — `startServer` is the only production client builder
+ * and always passes one spawned server's `http://127.0.0.1:<port>` — but the
+ * external/shared-server case in engine-skew.js's SCOPE paragraph can, and
+ * keeping the path costs one expression.
+ *
+ * `_client` is the SDK's own internal handle and the ONLY route to that value
+ * (measured: the client's other keys are all resource namespaces). If a future
+ * SDK renames it, this returns UNKNOWN_SERVER_KEY and every server shares one
+ * bucket again. That bucket is genuinely degraded, not merely coarser: under it
+ * a record can be attributed to the wrong server AND cleared by the wrong one.
+ * `noteSessionVersion` clears from it anyway, on purpose — its docblock records
+ * the measurement behind that ruling.
+ *
+ * @param {object} [client] - the SDK client, or nothing
+ * @returns {string} origin + path, the raw value if it will not parse, else
+ *   UNKNOWN_SERVER_KEY. Never throws: an identity read on a diagnostic path
+ *   must not be able to fail a session create.
+ */
+function serverKeyForClient(client) {
+  let raw;
+  try {
+    raw = client && client._client && typeof client._client.getConfig === 'function'
+      ? client._client.getConfig().baseUrl
+      : undefined;
+  } catch (_e) {
+    return UNKNOWN_SERVER_KEY;
+  }
+  if (typeof raw !== 'string' || !raw.trim()) { return UNKNOWN_SERVER_KEY; }
+  try {
+    const url = new URL(raw);
+    return `${url.origin}${url.pathname}`.replace(/\/+$/, '') || url.origin;
+  } catch (_e) { return raw.trim(); }
+}
+
+/** The record standing against one KEY, or undefined. */
+function skewForKey(key) {
+  return _skewByServer.get(key);
+}
+
+/** Record a skew as the most RECENTLY seen, evicting the least recent past the
+ *  bound. Re-inserting on every observation is what makes "recent" mean last
+ *  observed rather than first seen. */
+function rememberSkew(key, skew) {
+  _skewByServer.delete(key);
+  _skewByServer.set(key, skew);
+  while (_skewByServer.size > MAX_SKEW_SERVERS) {
+    _skewByServer.delete(_skewByServer.keys().next().value);
+  }
+}
+
+/** Drop one server's record — a retraction, or "an older engine answers here
+ *  now". Safe on a key that was never recorded. */
+function forgetSkew(key) {
+  _skewByServer.delete(key);
+}
+
+/**
+ * The standing skew record for ONE server, or null.
+ *
+ * A caller with no client gets the UNKNOWN key's record — never another
+ * server's. Reading is defensive but cannot meaningfully throw.
+ * @param {object} [client] - the SDK client whose server is being asked about
+ * @returns {{server: string, installed: string}|null}
+ */
+function currentEngineSkew(client) {
+  try { return _skewByServer.get(serverKeyForClient(client)) || null; } catch (_e) { return null; }
+}
+
+/** Test-only: forget every standing record. */
+function _resetSkewRecords() {
+  _skewByServer.clear();
+}
+
+module.exports = {
+  serverKeyForClient,
+  currentEngineSkew,
+  skewForKey,
+  rememberSkew,
+  forgetSkew,
+  UNKNOWN_SERVER_KEY,
+  MAX_SKEW_SERVERS,
+  _resetSkewRecords,
+};

package/src/utils/engine-skew.js

@@ -0,0 +1,300 @@
+/**
+ * @module utils/engine-skew
+ * Runtime detection of an opencode ENGINE version skew: server vs installed.
+ *
+ * The version the server we are actually talking to reports, against the engine
+ * sitting in THIS install's node_modules.
+ *
+ * WHY (#133, piece 3). The outage was one engine version (npx cache, 1.17.3)
+ * serving every MCP session while another (global install, 1.18.15) served the
+ * CLI, both writing one shared SQLite file — so every MCP prompt died before a
+ * model was ever called. `amicus doctor` printed ZERO errors throughout: its
+ * skew check (`doctor-engine-check.js`) compares npx-cache copies against the
+ * GLOBAL install and says nothing about the copy the running process actually
+ * loaded. MEASURED here 2026-08-25: that baseline sees global 1.18.15 vs npx
+ * 1.18.15 and reports clean, while the running checkout loads engine **1.2.20**
+ * — a live instance of #133's own class, invisible to the check built for it.
+ * Hence a RUNTIME comparison with no global baseline.
+ *
+ * SCOPE, stated honestly (W10 review F2): this handshake fires when the server
+ * answering this process was started by a DIFFERENT install (shared or external
+ * server, PATH-hoisted binary). In #133's literal recorded topology the npx copy
+ * spawned its OWN engine — server and installed versions were EQUAL on that
+ * side, the skew being against a global install neither loads — so THIS check
+ * stays silent there; the engine-log excerpt (piece 2) names that case instead,
+ * by quoting the SQLiteError itself.
+ *
+ * MEASURED, not reasoned from types (2026-08-25, against a locally spawned
+ * engine): `client.session.create({})` returns `data = {directory,id,projectID,
+ * slug,time,title,version}` and `data.version` was `"1.2.20"` — byte-identical
+ * to this checkout's `node_modules/opencode-ai/package.json`. `Session.version`
+ * IS the engine's own version, so the two sides are directly comparable.
+ *
+ * SHAPE. `src/opencode-client.js :: createSession` pushes the observed version
+ * here together with its client (it discarded both before); this module owns
+ * the comparison, the announcement and the remedy text, while
+ * `./engine-skew-records.js` owns the server identity and the standing record —
+ * one per SERVER, refreshed on every create — that `src/headless.js` appends to
+ * a leg's death report. That keeps the client's return type a plain session-id
+ * string (measured: all three production callers — `headless.js`,
+ * `mcp-server.js`, `sidecar/interactive.js` — assign it straight to one).
+ *
+ * EVERYTHING HERE IS BEST-EFFORT: a diagnosis must never become the failure it
+ * reports on. Every path returns null/undefined rather than throwing.
+ */
+
+'use strict';
+
+const path = require('path');
+const {
+  serverKeyForClient, currentEngineSkew, skewForKey, rememberSkew, forgetSkew,
+  UNKNOWN_SERVER_KEY, MAX_SKEW_SERVERS, _resetSkewRecords,
+} = require('./engine-skew-records');
+// The SAME sanitizer the log excerpt uses (round-3 reviews B1+C2). A server's
+// reported version is third-party text on its way to a terminal and to MCP,
+// exactly like an engine log line; one implementation, one dialect.
+const { collapseExcerpt } = require('./text-sanitize');
+
+/** How much of a server-reported version is ever rendered. Real versions are
+ *  semver-shaped; past this it is not a version, it is a payload. */
+const MAX_VERSION_CHARS = 32;
+
+/** One version string, safe to paste into a one-line notice or an error message:
+ *  no ANSI, no control bytes, no bidi reordering, no newline that could forge a
+ *  second `[amicus] ` line, never longer than the cap. */
+const safeVersion = (value) => collapseExcerpt(value, MAX_VERSION_CHARS);
+
+/** Memo for the installed-version disk read (see installedEngineVersion). */
+let _installedRead = false;
+let _installedCache;
+/** Whether the "cannot name this server" notice has already been printed. */
+let _identityNoticeSent = false;
+
+/** Test-only: clear the standing records, the read memo and the notice latch. */
+function _resetEngineSkew() {
+  _resetSkewRecords();
+  _installedRead = false;
+  _installedCache = undefined;
+  _identityNoticeSent = false;
+}
+
+/**
+ * Read the engine version out of the RUNNING install's node_modules.
+ *
+ * Roots come from `path-setup.js :: opencodeRoots()` with no argument — the same
+ * resolver `engine-ensure`/`hasOpencodeBinary` use to decide whether THIS
+ * process's engine binary exists, so "the engine we would run" and "the engine
+ * we version-check" are the same by construction.
+ *
+ * Reading `opencode-ai`'s own package.json (rather than anything next to the
+ * binary) mirrors `engine-install-scan.js :: defaultReadEngineVersion`, whose
+ * docblock records why: a faithful proxy, because opencode-ai exact-pins all 12
+ * platform sub-packages and the binary's own directory has no package.json on
+ * POSIX at all.
+ * @param {object} [deps]
+ * @param {object} [deps.fs] - fs module seam (readFileSync)
+ * @param {string[]} [deps.roots] - node_modules roots seam
+ * @returns {string|undefined} undefined on every miss path
+ */
+function defaultReadInstalledEngineVersion(deps = {}) {
+  const fs = deps.fs || require('fs');
+  const roots = deps.roots || require('./path-setup').opencodeRoots();
+  for (const root of roots) {
+    try {
+      const raw = fs.readFileSync(path.join(root, 'opencode-ai', 'package.json'), 'utf-8');
+      const v = JSON.parse(raw).version;
+      if (v) { return String(v); }
+    } catch (_e) { /* try the next root */ }
+  }
+  return undefined;
+}
+
+/**
+ * The installed engine version, read at most ONCE per process.
+ *
+ * node_modules cannot change under a live process, and this is consulted on
+ * every session create (every fanout leg, every council seat) — a per-session
+ * stat of two roots would be pure waste. The memo is cleared only by
+ * `_resetEngineSkew()`, so a test that swaps seams must reset between cases;
+ * production has exactly one call path and never does.
+ * @param {object} [deps] - defaultReadInstalledEngineVersion seams, plus:
+ * @param {() => (string|undefined)} [deps.readInstalledVersion] - reader seam
+ * @returns {string|undefined}
+ */
+function installedEngineVersion(deps = {}) {
+  if (!_installedRead) {
+    _installedRead = true;
+    try {
+      _installedCache = deps.readInstalledVersion
+        ? deps.readInstalledVersion()
+        : defaultReadInstalledEngineVersion(deps);
+    } catch (_e) {
+      _installedCache = undefined;
+    }
+  }
+  return _installedCache;
+}
+
+/**
+ * The default sink for BOTH one-time notices here — skew, and identity loss.
+ * Written to stderr, NOT through `logger.warn`.
+ *
+ * MEASURED: `utils/logger.js :: getCurrentLevel` defaults `LOG_LEVEL` to
+ * `'error'`, so `logger.warn` is filtered out on every default install — a
+ * self-diagnosis routed there would be silent exactly where it matters. stderr
+ * with an `[amicus] ` prefix is the house pattern for notices the user must see
+ * (`mcp-server.js`'s update notice, `engine-ensure.js`'s self-heal) and is safe
+ * under MCP stdio, where stdout carries the protocol.
+ * @param {string} msg
+ */
+function defaultNotify(msg) {
+  try { process.stderr.write(`[amicus] ${msg}\n`); } catch (_e) { /* EPIPE at shutdown */ }
+}
+
+/**
+ * The announcement text. Names both versions (the whole point — #133 cost 30
+ * minutes because nothing printed the two numbers side by side) and then the
+ * action that ends it: make the two copies the same version.
+ *
+ * It deliberately does NOT say "see amicus doctor" (W10 round-1 review B1).
+ * Doctor's skew check is structurally blind to THIS skew — the module docblock
+ * above records the measurement — so pointing there would spend the user's next
+ * five minutes on a check that reports clean by construction.
+ *
+ * BOTH VERSIONS ARE SANITIZED (round-3 reviews B1+C2). `server` is whatever the
+ * server chose to say, and it landed verbatim on stderr: an escape sequence, a
+ * bidi override or a newline could recolour the terminal, reverse the sentence,
+ * or forge a second `[amicus] ` line under our prefix. `installed` goes through
+ * it too — also file content, and one rule beats two.
+ * @param {{server: string, installed: string}} skew
+ * @returns {string} one line
+ */
+function formatSkewWarning({ server, installed }) {
+  return `engine version skew: server ${safeVersion(server)} ≠ installed ${safeVersion(installed)} — `
+    + 'MCP and CLI may be running different engines; update whichever copy is behind '
+    + '(`npm i -g amicus`, or re-run the failing surface\'s installer). '
+    + '`amicus doctor` cannot see this skew: its baseline compares npx against global, '
+    + 'not the server actually answering.';
+}
+
+/**
+ * The clause appended to an enriched failure message. EMPTY when there is no
+ * standing skew, so every message that would not have carried it is
+ * byte-identical to what it was before this module existed.
+ *
+ * Sanitized on the same terms as the notice, and for a sharper reason: this
+ * clause rides out through MCP into whatever renders a leg's death report.
+ * @param {{server: string, installed: string}|null} [skew]
+ * @returns {string}
+ */
+function formatSkewSuffix(skew) {
+  if (!skew) { return ''; }
+  return ` (engine skew: server ${safeVersion(skew.server)} ≠ installed ${safeVersion(skew.installed)})`;
+}
+
+/**
+ * Say so, ONCE, when a client was handed to us and we could not name its server.
+ *
+ * Round-3 review C1(a). `serverKeyForClient` reads `client._client.getConfig()`,
+ * a PRIVATE SDK handle and the only route to the base URL. If a future SDK
+ * renames it, that read returns UNKNOWN_SERVER_KEY, every server in the process
+ * silently shares one degraded bucket — where a record can be attributed to the
+ * wrong server AND cleared by the wrong one — and nothing says so. That is the
+ * correct-but-silent degrade the product principle rates as bad as a crash.
+ *
+ * A CLIENT WAS PROVIDED is the whole trigger: the caller had a server to name
+ * and we could not name it. No client at all is not a shape change — it is a
+ * caller that never claimed to have one — so `currentEngineSkew`, whose callers
+ * legitimately ask "any skew here?" with nothing in hand, does not raise it.
+ * Once per process: this runs on every create, and a wave of dead legs must not
+ * each print it. (b) is the other half — a CI shape pin over a REAL SDK client,
+ * in tests/utils/engine-skew.test.js.
+ */
+function noteIdentityLoss(key, deps) {
+  if (_identityNoticeSent || !deps.client || key !== UNKNOWN_SERVER_KEY) { return; }
+  _identityNoticeSent = true;
+  const notify = deps.notify || defaultNotify;
+  try {
+    notify('server identity unavailable — skew attribution is process-wide; '
+      + 'SDK shape may have changed');
+  } catch (_e) { /* best-effort, exactly like the skew notice */ }
+}
+
+/**
+ * Record a server-reported session version as the LAST comparison for that
+ * server, announcing a mismatch the first time that server shows it.
+ *
+ * REFRESHED ON EVERY CREATE, not written once (W10 round-1 review A3+B3): a
+ * matching version RETRACTS a standing skew for that server, so a mid-run fix
+ * stops being reported; a different mismatch REPLACES it, the newer observation
+ * being the true one. Records are per server identity, so a skewed server's
+ * clause never rides out on an unrelated server's death report.
+ *
+ * A version-less create CLEARS that server's record (round-2 review B4).
+ * Absence of the field means an older SDK or engine is answering — not evidence
+ * of SKEW, but evidence that what the record describes is no longer what is on
+ * that URL. Unknown beats stale: it announces nothing and returns null, exactly
+ * like a match. An unreadable INSTALLED version is different — with one side of
+ * the comparison missing there is no observation at all, so it touches nothing.
+ *
+ * BOTH CLEARS APPLY UNDER `UNKNOWN_SERVER_KEY` TOO, deliberately (round-2
+ * review B3, which proposed the opposite). Under that shared bucket a clear can
+ * be wrong — server B's healthy create can delete server A's real skew — so the
+ * rule was re-derived against "never attribute a skew to a server that does not
+ * have it" and MEASURED over A skewed, B healthy, A fixed, A regresses:
+ *   retract       → B dies clean, A-after-fix dies clean, A's regression is
+ *                   re-recorded on its very next create
+ *   never retract → B wears A's skew, A wears its own stale skew after the fix,
+ *                   and NOTHING can ever clear either
+ * Retraction's error is self-healing (this runs on EVERY create); the other is a
+ * wrong attribution no later observation can undo. The bucket stays genuinely
+ * degraded — see `noteIdentityLoss` above, which now says so out loud.
+ *
+ * The notice repeats only when the record CHANGES: the skewed leg of a 20-seat
+ * wave must not print 20 identical lines.
+ * @param {string|undefined} serverVersion - `Session.version` from the create response
+ * @param {object} [deps] - installedEngineVersion seams, plus:
+ * @param {object} [deps.client] - the SDK client, for the server identity
+ * @param {(msg: string) => void} [deps.notify] - notice sink seam
+ * @returns {{server: string, installed: string}|null} that server's record
+ */
+function noteSessionVersion(serverVersion, deps = {}) {
+  const key = serverKeyForClient(deps.client);
+  noteIdentityLoss(key, deps);
+  if (typeof serverVersion !== 'string' || !serverVersion) {
+    forgetSkew(key); // an older engine answers here NOW — unknown beats stale
+    return null;
+  }
+  const installed = installedEngineVersion(deps);
+  if (typeof installed !== 'string' || !installed) { return null; }
+  if (serverVersion === installed) {
+    forgetSkew(key); // the two agree NOW — any older mismatch is stale
+    return null;
+  }
+
+  const prior = skewForKey(key);
+  const skew = { server: serverVersion, installed };
+  // Record BEFORE announcing: a notifier that throws must not cost us the
+  // enrichment clause too.
+  rememberSkew(key, skew);
+  if (prior && prior.server === skew.server && prior.installed === skew.installed) { return skew; }
+  const notify = deps.notify || defaultNotify;
+  try { notify(formatSkewWarning(skew)); } catch (_e) { /* best-effort */ }
+  return skew;
+}
+
+// Ordered so the FUNCTIONS this module is used for come first: the generated
+// `Key Exports` cell in CLAUDE.md keeps five names and renders each as `name()`,
+// so a constant in that window reads as a function it is not (round-2 B8).
+module.exports = {
+  noteSessionVersion,
+  currentEngineSkew,
+  serverKeyForClient,
+  formatSkewWarning,
+  formatSkewSuffix,
+  installedEngineVersion,
+  defaultReadInstalledEngineVersion,
+  UNKNOWN_SERVER_KEY,
+  MAX_SKEW_SERVERS,
+  _resetEngineSkew,
+};

package/src/utils/gateway-router.js

@@ -10,6 +10,7 @@
 const { resolved, routeError, selectionRequired, parseDescriptor } = require('./model-descriptor');
 const { classifyModel } = require('./model-classification');
 const { isDirectProvider } = require('./provider-registry');
+const HINTS = require('./remediation-hints');
 
 /** Build the executable id for a gateway. */
 function executableFor(gateway, vendor, model) {
@@ -86,8 +87,15 @@ function catalogGate({ id, gateway, req }) {
   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: [] }) };
+  const e = routeError({ requested: req.descriptor.raw, reason: 'model_not_found',
+    preferredGateway: gateway, suggestions: [] });
+  // B2 (V16): a bare id invalid on direct whose openrouter/ twin IS catalog-
+  // confirmed is exactly doctor's repairable fabricated-alias class — point at
+  // the repair. Hint only; reason and shape unchanged.
+  if (gateway === 'direct' && classifyModel(`openrouter/${id}`, 'openrouter', req.catalogInfo) === 'valid') {
+    e.hint = HINTS.repairFabricatedAlias;
+  }
+  return { ok: false, result: e };
 }
 
 /**

package/src/utils/model-canonicalization.js

@@ -0,0 +1,64 @@
+/**
+ * Direct-first id canonicalization, guarded by `classifyModel`
+ * (model-classification.js). Extracted out of `provider-default-picker.js`
+ * (issue 195 follow-up, F1/B4 -- council review of PR 198) purely to keep
+ * that file under the 300-line size gate; the two function bodies below are
+ * an unmodified move, not a rewrite.
+ *
+ * Two call sites, same predicate (`classifyModel`), opposite defaults --
+ * named separately on purpose so neither behavior can be reached by
+ * accident (e.g. forgetting to pass an option):
+ *
+ * - `directFormIfSafe` -- LIST-BUILDING (`chooseRowId`/`canonicalizeResolved`
+ *   in provider-default-picker.js, building the picker's row list). With no
+ *   catalog evidence either way, a bare policy-routed id is a reasonable
+ *   GUESS to offer: optimistic, strips the `openrouter/` prefix unless
+ *   `classifyModel` can prove the bare form `invalid`.
+ * - `directFormIfProven` -- PERSISTENCE (`applyProviderDefault`, writing
+ *   `config.aliases[vendor]`). By the time an id is persisted, the caller
+ *   has already handed in whatever prefix it decided on -- that prefix IS
+ *   the user's choice, carrying information an empty or absent catalog does
+ *   not contradict. Strips only on POSITIVE evidence (`classifyModel`
+ *   returns `valid`, i.e. the bare id is an actual catalog row); anything
+ *   else -- `unknown` (including a failed/absent catalog fetch, which is
+ *   exactly the case that used to silently re-fabricate the id issue 195
+ *   fixed) or `invalid` -- preserves the id exactly as given.
+ *
+ * Both gate `DIVERGENT_VENDORS` FIRST and internally, always returning the
+ * input unchanged for one of those vendors (dot vs. dash direct ids, e.g.
+ * anthropic) -- a caller cannot reach the optimistic OR the proven strip for
+ * a divergent vendor by forgetting to check the set itself.
+ */
+
+'use strict';
+
+const { toCanonicalDefault, DIVERGENT_VENDORS } = require('./curated-models');
+const { classifyModel } = require('./model-classification');
+
+/**
+ * @param {string} vendor
+ * @param {string} orId an `openrouter/<vendor>/<rest>` id (or already-bare)
+ * @param {{models: Array<{id:string, authoritative?: boolean}>}} catalogInfo
+ * @returns {string} the bare direct id when not proven invalid, else `orId` unchanged
+ */
+function directFormIfSafe(vendor, orId, catalogInfo) {
+  if (DIVERGENT_VENDORS.has(vendor)) { return orId; }
+  const bare = toCanonicalDefault(orId);
+  if (bare === orId) { return orId; } // gateway-only vendor -- no direct integration at all
+  return classifyModel(bare, 'direct', catalogInfo) === 'invalid' ? orId : bare;
+}
+
+/**
+ * @param {string} vendor
+ * @param {string} orId an `openrouter/<vendor>/<rest>` id (or already-bare)
+ * @param {{models: Array<{id:string, authoritative?: boolean}>}} catalogInfo
+ * @returns {string} the bare direct id only when PROVEN valid, else `orId` unchanged
+ */
+function directFormIfProven(vendor, orId, catalogInfo) {
+  if (DIVERGENT_VENDORS.has(vendor)) { return orId; }
+  const bare = toCanonicalDefault(orId);
+  if (bare === orId) { return orId; }
+  return classifyModel(bare, 'direct', catalogInfo) === 'valid' ? bare : orId;
+}
+
+module.exports = { directFormIfSafe, directFormIfProven };

package/src/utils/model-catalog.js

@@ -152,4 +152,4 @@ async function getCatalogInfo(opts = {}) {
   };
 }
 
-module.exports = { getCatalog, refreshCatalog, catalogPath, getCatalogInfo, readCache, CATALOG_SCHEMA_VERSION };
+module.exports = { getCatalog, refreshCatalog, catalogPath, getCatalogInfo, readCache, CATALOG_SCHEMA_VERSION, DEFAULT_MAX_AGE_MS };

package/src/utils/model-shortlist.js

@@ -0,0 +1,100 @@
+/**
+ * Vendor model shortlist (#138) -- the family -> model second level.
+ *
+ * Turns a vendor's deduped, priced picker rows into a
+ * `{suggested, rest}` split so a surface can show a short list without
+ * hiding anything: the GUI renders both groups in one <select>, readline
+ * prints `suggested` and offers `a` to print `rest` too.
+ *
+ * PURE and transport-agnostic, exactly like `provider-default-picker.js`:
+ * the catalog is always injected, and nothing here formats for a renderer.
+ *
+ * Why the caller supplies `recommendedId`: the picker's own preselect is
+ * COST-TIER driven (`computePreselectedId`), which disagrees with the
+ * wizard card's family flagship -- for DeepSeek, `v3.2` vs `v4-pro`.
+ * Owner ruling (#138, 2026-08-24) is that the flagship wins, so that
+ * opening the drill-down and accepting is a guaranteed no-op. The tier
+ * preselect remains the fallback when the flagship matches no row.
+ */
+
+'use strict';
+
+const { buildProviderDefaultChoices } = require('./provider-default-picker');
+const { pairAcrossGateways } = require('./gateway-route-catalog');
+
+/** Rows shown before the "all models" group. */
+const SHORTLIST_LIMIT = 8;
+
+/**
+ * Both gateway spellings of a row id, so a surface can honour an explicit
+ * "via OpenRouter" choice for a drilled-down model. NEVER derives one form
+ * from the other -- `pairAcrossGateways` reads real catalog rows, which is
+ * the only safe move for DIVERGENT_VENDORS (anthropic's direct and
+ * OpenRouter ids are different strings, not differently prefixed).
+ * @param {string} vendor
+ * @param {string} id verbatim picker row id
+ * @param {Array<{id:string}>} catalog
+ * @returns {{directId: (string|null), openrouterId: (string|null)}}
+ */
+function routeFormsFor(vendor, id, catalog) {
+  const token = id.replace(/^openrouter\//, '').replace(`${vendor}/`, '');
+  const paired = pairAcrossGateways(vendor, token, { models: catalog });
+  return {
+    directId: paired.direct || null,
+    openrouterId: paired.openrouter || null,
+  };
+}
+
+/**
+ * Recommended-first, then price-ascending, nulls last -- the same order
+ * `provider-default-picker.js`'s `compareRows` already establishes, so the
+ * drill-down reads like the picker the user may already have seen.
+ */
+function compareShortlistRows(a, b) {
+  if (a.isRecommended !== b.isRecommended) { return a.isRecommended ? -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;
+}
+
+/**
+ * @param {string} vendor e.g. 'deepseek'
+ * @param {{catalog?: Array<object>, recommendedId?: string, limit?: number}} [options]
+ * @returns {{recommendedId: (string|null), suggested: Array<object>,
+ *   rest: Array<object>, total: number}}
+ */
+function buildModelShortlist(vendor, options = {}) {
+  const catalog = Array.isArray(options.catalog) ? options.catalog : [];
+  const limit = Number.isInteger(options.limit) && options.limit > 0
+    ? options.limit : SHORTLIST_LIMIT;
+
+  const { preselectedId, rows } = buildProviderDefaultChoices(vendor, { catalog });
+  if (!rows || rows.length === 0) {
+    return { recommendedId: null, suggested: [], rest: [], total: 0 };
+  }
+
+  // Owner ruling: the family flagship wins when it names a real row;
+  // otherwise keep the picker's tier preselect rather than inventing one.
+  const wanted = options.recommendedId;
+  const recommendedId = (wanted && rows.some(r => r.id === wanted)) ? wanted : preselectedId;
+
+  const annotated = rows.map(r => Object.assign({
+    id: r.id,
+    name: r.name,
+    contextLength: r.contextLength,
+    pricePerMInput: r.pricePerMInput,
+    isRecommended: r.id === recommendedId,
+  }, routeFormsFor(vendor, r.id, catalog)));
+
+  annotated.sort(compareShortlistRows);
+
+  return {
+    recommendedId,
+    suggested: annotated.slice(0, limit),
+    rest: annotated.slice(limit),
+    total: annotated.length,
+  };
+}
+
+module.exports = { buildModelShortlist, compareShortlistRows, SHORTLIST_LIMIT };