amicus 4.7.1 → 4.8.1

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-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 };

package/src/utils/no-output-backstop.js

@@ -20,7 +20,7 @@
 
 const { envNumber } = require('./env-num');
 
-const DEFAULT_NO_OUTPUT_BACKSTOP_MS = 120000;
+const DEFAULT_NO_OUTPUT_BACKSTOP_MS = 300000;
 
 /** @param {object} [env] test seam; defaults to process.env */
 function resolveNoOutputBackstopMs(env) {

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

@@ -17,8 +17,11 @@
 const { resolveTier } = require('./model-tiers');
 const { getCostTier, loadConfig, saveConfig } = require('./config');
 const { pairAcrossGateways } = require('./gateway-route-catalog');
-const { toCanonicalDefault, DIVERGENT_VENDORS } = require('./curated-models');
 const { isLocalProvider } = require('./local-providers');
+// directFormIfSafe (list-building) / directFormIfProven (persistence): see
+// model-canonicalization.js's module docstring for why these are two
+// separately-named functions rather than one with an optional mode.
+const { directFormIfSafe, directFormIfProven } = require('./model-canonicalization');
 
 /**
  * @param {{pricing?: {prompt?: string|number|null}|null}|null|undefined} orRow
@@ -49,8 +52,10 @@ function vendorRowsIn(catalog, vendor) {
 }
 
 /**
- * Choose the verbatim catalog id a single catalog `row` should surface as in
- * the picker -- NEVER fabricates an id.
+ * Choose the id a single catalog `row` should surface as in the picker.
+ * Prefers a real, verbatim catalog id; only SYNTHESISES one (delegating to
+ * `directFormIfSafe`, model-canonicalization.js -- see its module docstring
+ * for the guard) for a non-divergent vendor with no direct twin at all.
  *
  * A direct-namespace row always keeps its own (real, direct-callable) id,
  * regardless of what `pairAcrossGateways` could resolve for it -- this is
@@ -60,35 +65,55 @@ function vendorRowsIn(catalog, vendor) {
  * 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
+ * `pairAcrossGateways` found exactly one (unambiguous) direct twin. 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).
+ * OpenRouter's, e.g. anthropic's dash-vs-dot versioning), the row keeps its
+ * OpenRouter-prefixed id as-is -- `directFormIfSafe` gates that set FIRST
+ * and internally (model-canonicalization.js), so stripping is never even
+ * attempted on their ids, which is not a string-safe operation.
  * @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
+ * @param {{models: Array<{id:string, authoritative?: boolean}>}} catalogInfo
  * @returns {string|null}
  */
-function chooseRowId(vendor, isDirect, row, paired) {
+function chooseRowId(vendor, isDirect, row, paired, catalogInfo) {
   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);
+  return directFormIfSafe(vendor, paired.openrouter, catalogInfo);
 }
 
 /**
  * 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.
+ * A direct row is never dropped even when its OpenRouter twin is ambiguous.
+ *
+ * Row ids are verbatim catalog ids whenever a real row carries them: a
+ * direct row keeps its own id, and an OpenRouter row collapses onto a
+ * direct twin only when `pairAcrossGateways` found exactly one. For a
+ * NON-divergent vendor with no direct twin at all, `chooseRowId` derives
+ * the bare form via `directFormIfSafe` -- SYNTHESISED, not verbatim, only
+ * when the vendor's namespace can't prove it invalid (issue 195). Measured
+ * 2026-08-24 against a real 601-row catalog: all 14 `deepseek` rows derive
+ * this way (empty namespace); `google` (19/69) and `openai` (51/175) rows
+ * used to derive the same unconditional way despite a populated,
+ * authoritative namespace omitting that specific id, and now stay
+ * OpenRouter-prefixed instead. Once a bare id IS synthesized (the deepseek
+ * case), it is safe for routing, but not for the reason an earlier version
+ * of this comment claimed: a bare id is NOT failure-routed direct-first-
+ * with-OpenRouter-fallback. gateway-router.js's auto-mode step 7 is
+ * `if (rq.keys[vendor] && hasForm(rq, 'direct'))`, and `hasForm` is
+ * `!req.gatewayIds || req.gatewayIds[gateway] !== undefined` -- a bare id
+ * carries no `gatewayIds` at all, so `hasForm(rq, 'direct')` is VACUOUSLY
+ * true on this path; the only real gate is `rq.keys[vendor]`. The fallback
+ * to OpenRouter is therefore KEY-ABSENCE-driven (no key for `vendor`), not
+ * a check that the direct form actually resolves -- that check only fires
+ * on the ALIAS path, where `gatewayIds` IS attached and `hasForm` can
+ * genuinely be false. It is not a catalog-confirmed direct id either way,
+ * and callers that need that distinction should consult
+ * `curated-models.js`'s `directFormProvenance()`.
  * @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}>}
@@ -109,7 +134,7 @@ function buildRows(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);
+    const chosenId = chooseRowId(vendor, isDirect, row, paired, catalogInfo);
     if (!chosenId || seenIds.has(chosenId)) { continue; }
     seenIds.add(chosenId);
 
@@ -124,7 +149,7 @@ function buildRows(catalog, vendor) {
     // pricing (`sourceRow`, which for a local/direct row IS the catalog row
     // itself) instead. Gated on `isLocal`, NOT on "no OpenRouter twin", so a
     // direct (non-local) row with no twin still renders `pricePerMInput:
-    // null` (tests/provider-default-picker.test.js:59, pinned).
+    // null` (tests/provider-default-picker.test.js:60, pinned).
     const localPrice = isLocal ? pricePerMInputFrom(sourceRow) : null;
 
     rows.push({
@@ -140,22 +165,22 @@ function buildRows(catalog, vendor) {
 
 /**
  * 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.
+ * ids are built (`chooseRowId`/`directFormIfSafe`), so it matches `rows`
+ * exactly. Only matters when `resolveTier` fell back to an OpenRouter id (no
+ * matching direct-namespace row for the tier). `directFormIfSafe` gates
+ * `DIVERGENT_VENDORS` itself and keeps that id OpenRouter-prefixed;
+ * non-divergent vendors go through the same `classifyModel`-guarded strip
+ * `chooseRowId` uses (issue 195) -- an unconditional strip here would
+ * produce a canonical id `rows` no longer carries whenever `directFormIfSafe`
+ * kept the row itself OpenRouter-prefixed, defeating the match below.
  * @param {string} vendor
  * @param {string|null} resolved verbatim catalog id from `resolveTier`, or null
+ * @param {{models: Array<{id:string, authoritative?: boolean}>}} catalogInfo
  * @returns {string|null}
  */
-function canonicalizeResolved(vendor, resolved) {
+function canonicalizeResolved(vendor, resolved, catalogInfo) {
   if (!resolved) { return null; }
-  return DIVERGENT_VENDORS.has(vendor) ? resolved : toCanonicalDefault(resolved);
+  return directFormIfSafe(vendor, resolved, catalogInfo);
 }
 
 /**
@@ -173,7 +198,9 @@ function canonicalizeResolved(vendor, resolved) {
 function computePreselectedId(vendor, tier, catalog, rows) {
   const effectiveTier = tier || getCostTier();
   const resolved = resolveTier(vendor, effectiveTier, catalog);
-  const canonical = canonicalizeResolved(vendor, resolved);
+  // F2 (B5): guard the same way applyProviderDefault does, so classifyModel
+  // never sees a non-array `models` regardless of what a caller passes.
+  const canonical = canonicalizeResolved(vendor, resolved, { models: Array.isArray(catalog) ? catalog : [] });
   if (canonical && rows.some(r => r.id === canonical)) { return canonical; }
 
   const priced = rows.filter(r => r.pricePerMInput !== null);
@@ -217,22 +244,35 @@ function buildProviderDefaultChoices(vendor, options = {}) {
  * `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.
+ * `chosenId` comes straight from `buildProviderDefaultChoices`: a real
+ * direct id; an `openrouter/`-prefixed id (`DIVERGENT_VENDORS`, or -- since
+ * issue 195 -- a non-divergent vendor whose bare form would classify
+ * `invalid`); or a bare id already SYNTHESISED via `directFormIfSafe`. By
+ * the time this function runs, `chosenId`'s prefix (or lack of one) IS the
+ * decision -- PERSISTENCE therefore uses `directFormIfProven`, not
+ * `directFormIfSafe`: it strips the `openrouter/` prefix only on POSITIVE
+ * evidence (`classifyModel` returns `valid` -- the bare id is an actual
+ * catalog row), never merely because the catalog couldn't disprove it.
+ *
+ * This matters because `directFormIfSafe`'s optimistic default is correct
+ * for LIST-BUILDING (an empty/absent catalog can't assert absence, so a
+ * bare guess is reasonable to offer) but wrong here: a catalog fetch that
+ * failed or came back empty (`catalog` omitted, or `[]`) must never be read
+ * as license to fabricate a direct id `chooseRowId` never actually offered
+ * -- that reintroduces the exact bug issue 195 fixed, silently, on every
+ * degraded fetch. `directFormIfProven` preserves `chosenId` verbatim
+ * whenever the catalog can't prove the bare form valid, so an empty/absent
+ * `catalog` option is inert (no canonicalization at all), not a fallback to
+ * the old unconditional strip.
  * @param {string} vendor e.g. 'anthropic'
- * @param {string} chosenId verbatim catalog id from the picker
- * @param {{seedDefaultIfAbsent?: boolean}} [options]
+ * @param {string} chosenId id from the picker (see above -- not always
+ *   catalog-verbatim)
+ * @param {{seedDefaultIfAbsent?: boolean, catalog?: Array<{id:string}>}} [options]
  * @returns {{alias: string, setAsDefault: boolean}}
  */
-function applyProviderDefault(vendor, chosenId, { seedDefaultIfAbsent = true } = {}) {
-  const storedId = DIVERGENT_VENDORS.has(vendor) ? chosenId : toCanonicalDefault(chosenId);
+function applyProviderDefault(vendor, chosenId, { seedDefaultIfAbsent = true, catalog } = {}) {
+  const catalogInfo = { models: Array.isArray(catalog) ? catalog : [] };
+  const storedId = directFormIfProven(vendor, chosenId, catalogInfo);
 
   const config = loadConfig() || {};
   if (!config.aliases || typeof config.aliases !== 'object') { config.aliases = {}; }
@@ -246,4 +286,12 @@ function applyProviderDefault(vendor, chosenId, { seedDefaultIfAbsent = true } =
   return { alias: vendor, setAsDefault };
 }
 
-module.exports = { buildProviderDefaultChoices, applyProviderDefault, pricePerMInputFrom };
+// directFormIfSafe/directFormIfProven are re-exported (not just used
+// internally) so a caller that wants the canonicalization primitives
+// directly doesn't need to know they now live in model-canonicalization.js
+// -- see tests/model-canonicalization.test.js for the identity pin proving
+// this is a re-export, not a second, divergeable copy.
+module.exports = {
+  buildProviderDefaultChoices, applyProviderDefault, pricePerMInputFrom,
+  directFormIfSafe, directFormIfProven,
+};

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

@@ -111,7 +111,7 @@ async function runProviderDefaultFlow(provider, options = {}) {
     chosenId = await promptForChoice(ask, print, choices);
   }
 
-  const { setAsDefault } = applyProviderDefault(provider, chosenId, { seedDefaultIfAbsent: true });
+  const { setAsDefault } = applyProviderDefault(provider, chosenId, { seedDefaultIfAbsent: true, catalog });
   const summaryLine = `\`amicus start --model ${provider}\` → ${chosenId}` +
     (setAsDefault ? ', set as your default model' : '');
 

package/src/utils/quick-picks.js

@@ -79,8 +79,8 @@ function resolveQuickPicks(catalog) {
  * Stripping the prefix there fabricates an id the direct API rejects, which
  * `amicus doctor` then reports as a stale alias. The row's own direct route is
  * used verbatim, falling back to the intact `openrouter/` form when the
- * catalog offered no direct pick. Mirrors the guard already used at
- * `provider-default-picker.js:82,143,220`.
+ * catalog offered no direct pick. Mirrors the DIVERGENT_VENDORS-first guard
+ * `model-canonicalization.js :: directFormIfSafe` uses internally.
  * @param {{vendorPath?:string, routes?:Object<string,string>}} pick
  * @returns {string|undefined}
  */

package/src/utils/remediation-hints.js

@@ -130,6 +130,43 @@ const REMEDIATION_HINTS = Object.freeze({
    */
   sweepSessionMetadataTmp:
     'amicus doctor --fix  (sweeps orphaned .metadata.json.*.tmp files left by an interrupted write)',
+
+  /**
+   * Stale sessions-index.json entries (R16): session-index.js :: recordSession
+   * never removes a row, so a project that is deleted, renamed or moved
+   * leaves its taskId -> path entries behind forever, and every
+   * recordSession call pays for rewriting the WHOLE index — the per-start
+   * cost grows with total sessions ever, not live ones. `doctor --fix`
+   * removes only entries whose project path no longer exists on disk
+   * (liveness, never age — R16-2): a five-year-old entry for a project that
+   * still exists is left alone.
+   */
+  pruneSessionIndex:
+    'amicus doctor --fix  (removes sessions-index.json entries whose project no longer exists on disk — liveness-based, never by age)',
+
+  /**
+   * Fabricated bare alias (B3, council review of PR 198 / issue 195): v4.8.0
+   * could persist a `<vendor>/<model>` id no catalog row carries. `doctor
+   * --fix` rewrites ONLY the narrow, mechanically-unambiguous class -- an
+   * alias that classifies `invalid` on the `direct` gateway AND has an
+   * unambiguous OpenRouter twin (`pairAcrossGateways`, alias-audit.js's
+   * `findFabricatedAliasRepairs`) -- to that twin. Every other stale/drifted
+   * alias (typo, retired model, user-invented id) is left for `amicus
+   * models --check` instead, never guessed at.
+   */
+  repairFabricatedAlias:
+    'amicus doctor --fix  (rewrites a fabricated bare alias to its catalog-confirmed OpenRouter id — safe only for the narrow class doctor can prove; use `amicus models --check` for anything else)',
+
+  /**
+   * A3 (council review of PR 198): same repairable class as
+   * `repairFabricatedAlias` above, but the cached catalog `evaluateAliasesCheck`
+   * would repair FROM is itself stale (older than doctor's own `catalog`
+   * check's freshness window) -- a stale catalog can be missing rows that
+   * would make a "fabricated" id look repairable when it is merely unfetched,
+   * so the repair declines rather than write on unverified evidence.
+   */
+  repairFabricatedAliasStaleCatalog:
+    'amicus models --refresh, then amicus doctor --fix  (the alias looks fabricated but the cached catalog is stale — refresh it first so the repair rests on current data, not a possibly-incomplete snapshot)',
 });
 
 module.exports = REMEDIATION_HINTS;