amicus 4.9.7 → 4.10.0

package/src/sidecar/models.js

@@ -194,7 +194,7 @@ async function runCheck(args) {
   // empty namespace explains stale/absent aliases downstream, and staying
   // silent about it is the original defect.
   for (const f of providerFailures) { process.stdout.write(fmtProviderFailure(f) + '\n'); }
-  const driftLines = buildFallbackDriftReport(catalog);
+  const driftLines = buildFallbackDriftReport(catalogInfo);
   if (stale.length === 0 && drifted.length === 0) {
     process.stdout.write(`All aliases resolve to catalog models (${sources.length} checked).\n`);
   } else if (stale.length > 0) {
@@ -202,7 +202,11 @@ async function runCheck(args) {
       process.stdout.write(`STALE: ${s.alias} -> ${s.model} (${s.source})\n`);
       if (s.suggestions.length > 0) {
         process.stdout.write(`  candidates: ${s.suggestions.join(', ')}\n`);
-        process.stdout.write(`  fix: amicus setup --add-alias ${s.alias}=${s.suggestions[0]}\n`);
+        // #238 D4: a user-config row is reviewable in the picker; a shipped pin
+        // that went stale can only be pinned OVER until the next release.
+        process.stdout.write(s.source === 'user-config'
+          ? '  fix: amicus aliases --review\n'
+          : `  fix: amicus setup --add-alias ${s.alias}=${s.suggestions[0]}  (pins over the stale shipped default)\n`);
       } else {
         process.stdout.write('  no same-vendor candidates in catalog\n');
       }
@@ -210,7 +214,7 @@ async function runCheck(args) {
   }
   for (const dr of drifted) {
     process.stdout.write(`DRIFTED: ${dr.alias} -> ${dr.stored} (stored; current resolution: ${dr.current})\n`);
-    process.stdout.write(`  stored aliases don't follow catalog updates — refresh: amicus setup --add-alias ${dr.alias}=${dr.current}\n`);
+    process.stdout.write('  stored aliases don\'t follow catalog updates — review: amicus aliases --review\n');
   }
   if (driftLines.length > 0) {
     process.stdout.write('Pinned fallback drift:\n');
@@ -233,12 +237,21 @@ async function runCheck(args) {
 
 /**
  * Non-blocking drift report: pinned family fallbacks vs live resolution.
- * Empty catalog → [] (cannot check). Never affects the exit code.
- * @param {Array<{id:string}>} catalog
+ * Accepts a catalogInfo (`{models, providerFailures}`) or a bare models array
+ * (older callers). Empty catalog → [] (cannot check). #238 §5: when the
+ * openrouter namespace itself was REJECTED this run, the catalog is missing the
+ * rows that make a pin look current, and a drift line computed from it would
+ * propose a downgrade — so the report is empty for that catalog. Never affects
+ * the exit code.
+ * @param {{models: Array<{id:string}>, providerFailures?: Array<{provider:string}>}|Array<{id:string}>} catalogOrInfo
  * @returns {string[]} human-readable warning lines
  */
-function buildFallbackDriftReport(catalog) {
-  if (!catalog || catalog.length === 0) { return []; }
+function buildFallbackDriftReport(catalogOrInfo) {
+  const info = Array.isArray(catalogOrInfo) ? { models: catalogOrInfo } : (catalogOrInfo || { models: [] });
+  const catalog = info.models || [];
+  if (catalog.length === 0) { return []; }
+  const failures = Array.isArray(info.providerFailures) ? info.providerFailures : [];
+  if (failures.some(f => f && f.provider === 'openrouter')) { return []; }
   const lines = [];
   for (const f of getFamilies()) {
     const live = pickCurrent(catalog, 'openrouter/', f.vendorPath, f.idPattern);

package/src/sidecar/session-utils.js

@@ -20,8 +20,10 @@ const {
   resolveExistingSessionDir
 } = require('../session-manager');
 
-/** Standard heartbeat interval in milliseconds */
-const HEARTBEAT_INTERVAL = 15000;
+// HEARTBEAT_INTERVAL + createHeartbeat live in ./heartbeat (size-gate split:
+// this file was already at the 300-line ceiling — spec 2026-09-11 §4 PR 2).
+// Re-exported below so no caller changes.
+const { HEARTBEAT_INTERVAL, createHeartbeat } = require('./heartbeat');
 
 /** Session path utilities - eliminates magic strings across modules */
 const SessionPaths = {
@@ -122,38 +124,6 @@ function outputSummary(summary) {
   console.log(fenceSidecarOutput(summary));
 }
 
-/**
- * Create a heartbeat that writes status to stderr periodically.
- * When sessionDir is provided, includes message count and latest activity.
- *
- * @param {number} [interval=HEARTBEAT_INTERVAL] - Interval in milliseconds
- * @param {string} [sessionDir] - Session directory to read progress from
- * @returns {{ stop: () => void }}
- */
-function createHeartbeat(interval = HEARTBEAT_INTERVAL, sessionDir) {
-  const startTime = Date.now();
-  const intervalId = setInterval(() => {
-    const elapsed = Math.round((Date.now() - startTime) / 1000);
-    const mins = Math.floor(elapsed / 60);
-    const secs = elapsed % 60;
-    const ts = mins > 0 ? `${mins}m${secs}s` : `${secs}s`;
-
-    if (sessionDir) {
-      const { readProgress } = require('./progress');
-      const progress = readProgress(sessionDir);
-      process.stderr.write(`[amicus] ${ts} | ${progress.messages} messages | ${progress.latest}\n`);
-    } else {
-      process.stderr.write(`[amicus] still running... ${ts} elapsed\n`);
-    }
-  }, interval);
-
-  return {
-    stop() {
-      clearInterval(intervalId);
-    }
-  };
-}
-
 /**
  * Execute sidecar in either headless or interactive mode
  * Consolidates the if/else pattern duplicated across start, resume, continue
@@ -228,6 +198,7 @@ async function executeMode(options) {
  * @param {string} [options.client] - Client type (e.g. 'cowork', 'code-local')
  * @param {string} [options.systemPrompt] - System prompt to set on agent config (hidden from UI)
  * @param {string} [options.agentName] - Agent to set systemPrompt on (default: 'chat')
+ * @param {Object<string, object>} [options.agents] - Extra agents to register (council seat agents)
  * @param {string[]} [options.models] - Resolved executable id(s) actually launched on this
  *   server (#61 Task 4.6/7.3 sole-input invariant) — a multi-model shared server (fanout)
  *   has no single default `config.model`, so this registers ALL of them in provider.models
@@ -257,6 +228,8 @@ async function startOpenCodeServer(mcpConfig, options = {}) {
   if (options.models) { serverOptions.models = options.models; }
   if (options.systemPrompt) { serverOptions.systemPrompt = options.systemPrompt; }
   if (options.agentName) { serverOptions.agentName = options.agentName; }
+  // Spec 2026-09-11 §4: the council's two agents ride into buildServerOptions.
+  if (options.agents) { serverOptions.agents = options.agents; }
   // Explicit per-call override only. Unset is the normal case and is correct:
   // buildServerOptions resolves AMICUS_SERVER_START_TIMEOUT_MS / the platform
   // default downstream, so forwarding `undefined` here would change nothing.

package/src/sidecar/setup.js

@@ -42,7 +42,7 @@ function addAlias(name, modelString) {
 /**
  * Ensure a config exists with the chosen default model. Read-modify-write:
  * preserves every pre-existing top-level key (aliases, councils, …) and only
- * fills in the default + any missing default aliases. Never clobbers.
+ * fills in the default — aliases are left untouched (absence follows, #238 Q9).
  * @param {string} defaultModel - Default model alias or full model string
  * @returns {object} The resulting config object
  */
@@ -51,17 +51,12 @@ function createDefaultConfig(defaultModel) {
   const cfg = {
     ...existing,
     default: existing.default || defaultModel,
-    // Same restatement as the readline gate below (fix round 3, G-2): a spread
-    // into `{}` re-materialises Object.prototype. `saveConfig` rebuilds this
-    // into its own literal anyway, so this one is defense in depth rather than
-    // a measured hole — recorded as such rather than claimed as a fix.
-    aliases: { __proto__: null, ...getDefaultAliases(), ...(existing.aliases || {}) },
+    // #238 Q9: no seeding. A curated alias FOLLOWS the shipped pin by being
+    // ABSENT from config.aliases (D1); only what the user chose is written.
+    aliases: { __proto__: null, ...(existing.aliases || {}) },
   };
   saveConfig(cfg);
-  logger.info('Default config ensured', {
-    default: cfg.default,
-    aliasCount: Object.keys(cfg.aliases).length,
-  });
+  logger.info('Default config ensured', { default: cfg.default, aliasCount: Object.keys(cfg.aliases).length });
   return cfg;
 }
 
@@ -524,7 +519,8 @@ async function runReadlineSetup() {
       return;
     }
 
-    const { resolveQuickPicks, toLiveSeedAliases, toStorableRoute } = require('../utils/quick-picks');
+    const { resolveQuickPicks, toStorableRoute } = require('../utils/quick-picks');
+    const { stripGatewayPrefix } = require('../utils/curated-models');
     const picks = resolveQuickPicks(catalog);
 
     console.log('Choose your default model:');
@@ -545,7 +541,7 @@ async function runReadlineSetup() {
     }
 
     // Read-modify-write — never rebuild the alias table (no-clobber rule).
-    const cfg = loadConfig() || { aliases: toLiveSeedAliases({ models: catalog, providerFailures }) };
+    const cfg = loadConfig() || { aliases: {} };
     if (!cfg.aliases) { cfg.aliases = {}; }
     if (chosen.alias) {
       cfg.default = chosen.alias;
@@ -555,11 +551,16 @@ async function runReadlineSetup() {
       // pointing at that alias name is fine (the user's explicit overall-default
       // choice), but the alias's VALUE must stay the vendor phase's tier choice --
       // skip the curated-flagship upgrade so it isn't discarded.
+      // #238 Q9: write the chosen default's LIVE pick only when it differs
+      // from the shipped pin, and say so — a pin the user was told about.
+      // Otherwise leave the key alone: absent = follows (D1).
       if (pick && !chosen.noUpgrade && !vendorAliasesWritten.has(chosen.alias)) {
-        cfg.aliases[chosen.alias] = toStorableRoute(pick, { models: catalog, providerFailures });
-      } else if (cfg.aliases[chosen.alias] === undefined) {
-        const fallback = getDefaultAliases()[chosen.alias];
-        if (fallback !== undefined) { cfg.aliases[chosen.alias] = fallback; }
+        const live = toStorableRoute(pick, { models: catalog, providerFailures });
+        const shipped = getDefaultAliases()[chosen.alias];
+        if (live && stripGatewayPrefix(live) !== stripGatewayPrefix(shipped)) {
+          cfg.aliases[chosen.alias] = live;
+          console.log(`${chosen.alias} → ${live} (live flagship differs from the shipped ${shipped} — pinned)`);
+        }
       }
 
       // #138: offer the family -> model second level. `pick.vendorPath` is
@@ -608,7 +609,7 @@ async function runReadlineSetup() {
           const shortlist = buildModelShortlist(pick.vendorPath, {
             catalog,
             providerFailures,
-            recommendedId: cfg.aliases[chosen.alias],
+            recommendedId: cfg.aliases[chosen.alias] || getDefaultAliases()[chosen.alias],
           });
           const specific = await promptForVendorModel(
             askQuestion.bind(null, rl), console.log, shortlist, pick.vendorPath
@@ -626,7 +627,8 @@ async function runReadlineSetup() {
 
     console.log('');
     console.log(`Default model set to: ${cfg.default}`);
-    console.log(`Config saved (${Object.keys(cfg.aliases).length} aliases).`);
+    const pinned = Object.keys(cfg.aliases).length;
+    console.log(`Config saved (${pinned} pinned alias${pinned === 1 ? '' : 'es'}; the rest follow the shipped recommendations — amicus aliases).`);
     console.log(`Config path: ${path.join(getConfigDir(), 'config.json')}`);
 
     // C8: compact doctor summary, best-effort (see printDoctorFinale).

package/src/utils/agent-mapping.js

@@ -6,7 +6,7 @@
  * OpenCode Native Agents (https://opencode.ai/docs/agents/):
  *   - Chat: Reads auto, writes/bash ask permission (interactive default)
  *   - Build: Default primary agent with full tool access
- *   - Plan: Read-only agent for analysis and planning
+ *   - Plan: Analysis and planning without edits (reads, searches and shell allowed)
  *   - General: Full-access agent for research
  *   - Explore: Read-only agent for codebase exploration
  *

package/src/utils/alias-groups.js

@@ -0,0 +1,128 @@
+/**
+ * @module utils/alias-groups
+ * Vendor-derived alias grouping (issue 213). Moved VERBATIM out of
+ * `electron/setup-ui-alias-groups.js` (#238 PR1 fix wave F5): `src/` code
+ * (src/sidecar/aliases.js — the CLI `amicus aliases` list) must not require
+ * from `electron/`, a layering violation the whole-branch review caught.
+ * `electron/setup-ui-alias-groups.js` re-exports every symbol here so its
+ * own callers (setup-ui-aliases.js, setup-ui.js) and their tests keep
+ * working untouched.
+ *
+ * REUSE NOTE: the vendor parse is `vendorOf` from src/sidecar/fallback-chains.js
+ * — the existing primitive, imported, not re-implemented. It PARSES a vendor
+ * segment (it never emits an id that gets called), which is the same
+ * ban-exempt category as the other allowlisted `vendorOf` callers in
+ * .eslintrc.js. `groupModelsByFamily` (src/utils/model-fetcher.js) is
+ * deliberately NOT reused: it keys on `id.split('/')[0]`, so every
+ * `openrouter/...` alias would collapse into a single "OpenRouter" bucket —
+ * exactly the grouping this file exists to avoid. Its DISPLAY half
+ * (PROVIDER_FAMILY_NAMES) is reused below.
+ */
+
+'use strict';
+
+const { vendorOf } = require('../sidecar/fallback-chains');
+const { PROVIDER_FAMILY_NAMES, listDirectProviders } = require('./provider-registry');
+
+/**
+ * Display names for vendors seen in alias routes.
+ *
+ * DISPLAY ONLY — deliberately not folded into provider-registry's PROVIDERS,
+ * which is a *capability* registry (env var, direct-vs-gateway, live fetch).
+ * KNOWN_PROVIDERS / PROVIDER_ENV_MAP are derived from that list, so adding
+ * `z-ai` there would claim Amicus can hold a z-ai API key. The five real
+ * providers keep their single source of truth via PROVIDER_FAMILY_NAMES.
+ * Module-private: nothing outside this file requires it directly.
+ */
+const ALIAS_VENDOR_LABELS = {
+  ...PROVIDER_FAMILY_NAMES,
+  // Vendors reachable through the gateway (curated + commonly pinned)
+  'qwen': 'Qwen',
+  'mistralai': 'Mistral AI',
+  'z-ai': 'Z.AI',
+  'minimax': 'MiniMax',
+  'x-ai': 'xAI',
+  'moonshotai': 'Moonshot AI',
+  'bytedance-seed': 'ByteDance Seed',
+  'thinkingmachines': 'Thinking Machines',
+  'cognitivecomputations': 'Cognitive Computations',
+  'inclusionai': 'InclusionAI',
+  'nvidia': 'NVIDIA',
+  'cohere': 'Cohere',
+  'meta-llama': 'Meta Llama',
+  'nousresearch': 'Nous Research',
+  'perplexity': 'Perplexity',
+  'microsoft': 'Microsoft',
+  'ai21': 'AI21',
+  'amazon': 'Amazon',
+  // Local providers (src/utils/local-providers.js PRESETS / VALID_FLAVORS)
+  'ollama': 'Ollama',
+  'lmstudio': 'LM Studio',
+  'vllm': 'vLLM',
+};
+
+/**
+ * `some-new-vendor` -> `Some New Vendor`, so an unmapped vendor is not a raw slug.
+ * @param {string} vendor
+ * @returns {string}
+ */
+function titleCaseVendor(vendor) {
+  return String(vendor).split(/[-_]/).filter(Boolean)
+    .map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
+/**
+ * Vendor key for an alias route. Wraps the shared `vendorOf` with the two
+ * normalisations issue 213 flagged: case, and the leading `~` of a floating
+ * OpenRouter id (`openrouter/~z-ai/glm-latest` must not form a second group
+ * next to `z-ai`).
+ * @param {string} route @returns {string} '' when there is no usable route
+ */
+function aliasVendorOf(route) {
+  const v = vendorOf(route).toLowerCase();
+  return v.charAt(0) === '~' ? v.slice(1) : v;
+}
+
+/**
+ * Display label for a vendor key.
+ * hasOwnProperty, not a bare lookup: vendor is derived from a user-editable
+ * route, and `__proto__`/`constructor` would otherwise return prototype junk.
+ * @param {string} vendor @returns {string}
+ */
+function vendorLabel(vendor) {
+  if (!vendor) { return 'Other'; }
+  const hit = Object.prototype.hasOwnProperty.call(ALIAS_VENDOR_LABELS, vendor)
+    ? ALIAS_VENDOR_LABELS[vendor] : null;
+  return hit || titleCaseVendor(vendor);
+}
+
+/** Direct-route vendors render first; everything else sorts by label. @type {string[]} */
+const PREFERRED_VENDOR_ORDER = listDirectProviders();
+
+/**
+ * Bucket an alias map by route vendor.
+ * INVARIANT: every own key of `aliases` lands in exactly one returned group —
+ * there is no whitelist to miss, and the empty vendor is a real catch-all.
+ * Order within a group follows the config's own key order.
+ * @param {Object<string,string>} aliases
+ * @returns {Array<{vendor: string, label: string, keys: string[]}>}
+ */
+function groupAliases(aliases) {
+  const byVendor = new Map();
+  for (const key of Object.keys(aliases || {})) {
+    const vendor = aliasVendorOf(aliases[key]);
+    if (!byVendor.has(vendor)) { byVendor.set(vendor, []); }
+    byVendor.get(vendor).push(key);
+  }
+  const rank = (vendor) => {
+    if (!vendor) { return Number.MAX_SAFE_INTEGER; } // catch-all group last
+    const i = PREFERRED_VENDOR_ORDER.indexOf(vendor);
+    return i === -1 ? PREFERRED_VENDOR_ORDER.length : i;
+  };
+  return Array.from(byVendor.entries())
+    .map(([vendor, keys]) => ({ vendor, label: vendorLabel(vendor), keys }))
+    .sort((a, b) => rank(a.vendor) - rank(b.vendor) ||
+      a.label.toLowerCase().localeCompare(b.label.toLowerCase()));
+}
+
+module.exports = { groupAliases, aliasVendorOf, vendorLabel, titleCaseVendor, PREFERRED_VENDOR_ORDER };

package/src/utils/alias-proposals.js

@@ -0,0 +1,151 @@
+/**
+ * @module utils/alias-proposals
+ * The alias review ENGINE (#238 §2): pure, no I/O, no prompts. Turns
+ * (config.aliases, DEFAULT_ALIASES, catalogInfo, dismissed, retired, notable)
+ * into ONE proposal per alias (Q4), for the CLI picker and the Electron
+ * "Needs review" section to render and for their sinks to write.
+ *
+ * Only PINNED aliases propose (D1): a following alias resolves to the shipped
+ * pin and cannot drift. The §5 DISPLAY gate is applied here: candidates never
+ * come from a non-authoritative row or a rejected namespace, and a sibling
+ * (model-id-siblings.js) is always strictly newer. A stale pin's
+ * `replacement` candidates are ranked by similarity (not recency) and sit
+ * after `follow` for a curated alias. A replacement never repeats an id
+ * already listed as `follow`. The WRITE gate (a fresh catalog) is the
+ * renderer's, at accept time.
+ *
+ * Own keys only: a `__proto__`/`toString` alias is a custom row here as it is
+ * everywhere else in the alias tables.
+ *
+ * `retired` and `notable` are inputs `amicus aliases` does not supply yet:
+ * Phase 2 (`curated-pins.json`) ships the retirement data and Phase 4 the
+ * notable list (spec §7); the paths are built and tested here so they are
+ * not written twice, and are inert from the CLI until then (council r2, D3).
+ */
+
+'use strict';
+
+const { listAliasRows } = require('./alias-state');
+const { newestSibling } = require('./model-id-siblings');
+const { findStaleAliases, suggestReplacements } = require('./alias-audit');
+const { stripGatewayPrefix } = require('./curated-models');
+
+const own = (obj, key) => !!obj && Object.prototype.hasOwnProperty.call(obj, key);
+const providerOf = (id) => (typeof id === 'string' ? id.split('/')[0] : '');
+const sameModel = (a, b) => typeof a === 'string' && typeof b === 'string' && stripGatewayPrefix(a) === stripGatewayPrefix(b);
+
+/** §5 rules 1–2: rows a proposal may name. */
+function candidateRows(models, failures) {
+  return models.filter(m => m && typeof m.id === 'string' && m.authoritative !== false && !failures.has(providerOf(m.id)));
+}
+
+/**
+ * The §5 display gate's id set, exposed for the picker (#249 r1 R2): a typed
+ * "choose another" id that names a real catalog row must still fail if that
+ * row is a floor entry (`authoritative: false`) or sits in a rejected
+ * namespace -- the numbered menu would never have offered it as a candidate
+ * either. Reuses `candidateRows` so the two paths can never disagree.
+ * @param {{models?: Array, providerFailures?: Array}|null} catalogInfo
+ * @returns {string[]} ids of every row the §5 display gate allows as a candidate
+ */
+function gatedCatalogIds(catalogInfo) {
+  if (!catalogInfo || typeof catalogInfo !== 'object') { return []; }
+  const models = Array.isArray(catalogInfo.models) ? catalogInfo.models : [];
+  const rawFailures = catalogInfo.providerFailures;
+  const failures = new Set((Array.isArray(rawFailures) ? rawFailures : []).map(f => f && f.provider).filter(Boolean));
+  return candidateRows(models, failures).map(m => m.id);
+}
+
+function proposeForRow(r, ctx) {
+  if (r.state !== 'pinned' || own(ctx.retired, r.alias)) { return null; }
+  if (ctx.failures.has(providerOf(r.id))) { return null; }             // its namespace cannot be judged
+  // Staleness is judged against the RAW catalog on purpose (council r2,
+  // B1/D4): the §5 gate governs what is PROPOSED, not what is condemned --
+  // on a keyless machine the only Anthropic rows are the hardcoded floor,
+  // and judging liveness against the gated set would call every working
+  // Anthropic pin stale and propose a replacement for each. A floor row is
+  // not evidence the provider serves a model; it is not evidence it
+  // stopped, either.
+  const stale = findStaleAliases([{ alias: r.alias, model: r.id, source: 'user-config' }], ctx.models).length === 1;
+  const sibling = newestSibling(r.id, ctx.candidateIds);
+  // Order (fix round 1, Finding 3): sibling first, UNLESS it is the shipped
+  // model itself — `follow` already names that id, so listing it twice as
+  // both "newer-sibling" and "follow" would be a display duplicate. `follow`
+  // outranks similarity-ranked replacements: a human-curated shipped pin is
+  // a better answer than a same-vendor guess, and a sibling was already
+  // found (even if hidden here as identical to `follow`) means the
+  // structurally-aware comparator has already answered "what's newer" —
+  // replacements are only offered when that comparator found nothing at all.
+  const differs = r.curated && !sameModel(r.shipped, r.id);
+  // F2: a sibling identical to the shipped id is not a DISTINCT candidate (it
+  // never reaches `candidates` below), so it must not be named in `reasons`
+  // either — reasons describes what was actually offered, not every signal
+  // the engine looked at.
+  const siblingIsCandidate = !!sibling && !sameModel(sibling, r.shipped);
+  const reasons = [];
+  if (stale) { reasons.push('stale'); }
+  if (siblingIsCandidate) { reasons.push('newer-sibling'); }
+  if (differs) { reasons.push('differs-from-shipped'); }
+  if (reasons.length === 0) { return null; }
+  const candidates = [];
+  if (siblingIsCandidate) { candidates.push({ id: sibling, why: 'newer-sibling', evidence: {} }); }
+  if (differs) { candidates.push({ id: r.shipped, why: 'follow', evidence: {} }); }
+  if (stale && !sibling) {
+    // Fix round 2 (ruling: DEDUPE): a replacement never repeats an id
+    // already listed (in practice, `follow`'s) — the same id under two
+    // rationales reads as a picker bug. `suggestReplacements` still caps its
+    // OWN output at up to 3; dropping a duplicate here can leave fewer than
+    // 3, never more (no backfill).
+    const seen = new Set(candidates.map(c => c.id));
+    for (const id of suggestReplacements(r.id, ctx.candidates)) {
+      if (!seen.has(id)) { candidates.push({ id, why: 'replacement', evidence: {} }); }
+    }
+  }
+  const dismissKey = `${r.alias}@${candidates.length ? candidates[0].id : r.id}`;
+  if (own(ctx.dismissed, dismissKey)) { return null; }
+  return { alias: r.alias, state: 'pinned', current: r.id, shipped: r.shipped, curated: r.curated, reasons, candidates, dismissKey };
+}
+
+function proposeNotable(entry, ctx) {
+  if (!entry || typeof entry.id !== 'string' || typeof entry.suggestedAlias !== 'string') { return null; }
+  if (own(ctx.retired, entry.suggestedAlias) || !ctx.candidateIds.includes(entry.id)) { return null; }
+  // Fix round 1, Finding 1: a notable must not shadow an alias NAME that
+  // already exists (curated or user, pinned or following) — rule 10 checked
+  // only the model, not the name, so a notable naming an already-pinned or
+  // already-taken alias produced a second, conflicting proposal for the same
+  // name (an 'unmapped' one beside the real 'pinned'/'following' one, in the
+  // worst case sharing a dismissKey with it).
+  if (ctx.names.has(entry.suggestedAlias)) { return null; }
+  if (ctx.mapped.some(id => sameModel(id, entry.id))) { return null; }
+  const dismissKey = `${entry.suggestedAlias}@${entry.id}`;
+  if (own(ctx.dismissed, dismissKey)) { return null; }
+  return { alias: entry.suggestedAlias, state: 'unmapped', current: null, shipped: null, curated: false,
+    reasons: ['notable-unmapped'], candidates: [{ id: entry.id, why: 'notable', evidence: { note: entry.note || '' } }], dismissKey };
+}
+
+/**
+ * @param {{userAliases: object|null, defaults: object, catalogInfo: {models?: Array, providerFailures?: Array}|null,
+ *   retired?: object, notable?: Array<{id:string, suggestedAlias:string, note?:string}>, dismissed?: object}} input
+ * @returns {Array<object>} proposals — see the module docblock for the shape
+ */
+function buildAliasProposals({ userAliases, defaults, catalogInfo, retired = {}, notable = [], dismissed = {} }) {
+  const models = (catalogInfo && Array.isArray(catalogInfo.models)) ? catalogInfo.models : [];
+  if (models.length === 0 || !defaults) { return []; }
+  // Fix round 1, Finding 2 (rule 11 "never throws on odd input"): a truthy
+  // non-array providerFailures (e.g. `{}`) must not reach `.map`.
+  const rawFailures = catalogInfo.providerFailures;
+  const failures = new Set((Array.isArray(rawFailures) ? rawFailures : []).map(f => f && f.provider).filter(Boolean));
+  const candidates = candidateRows(models, failures);
+  const rows = listAliasRows(userAliases, defaults);
+  const ctx = {
+    models, failures, candidates, candidateIds: candidates.map(m => m.id),
+    retired: retired || {}, dismissed: dismissed || {},
+    mapped: rows.map(r => r.id), names: new Set(rows.map(r => r.alias)),
+  };
+  const out = [];
+  for (const r of rows) { const p = proposeForRow(r, ctx); if (p) { out.push(p); } }
+  for (const n of (Array.isArray(notable) ? notable : [])) { const p = proposeNotable(n, ctx); if (p) { out.push(p); } }
+  return out;
+}
+
+module.exports = { buildAliasProposals, gatedCatalogIds };

package/src/utils/alias-resolver.js

@@ -39,7 +39,7 @@ function autoRepairAlias(alias, config, defaultAliases, saveConfig) {
   }
   throw new Error(
     `Alias '${alias}' is configured but has no model value. ` +
-    `Fix with: amicus setup --add-alias ${alias}=provider/model`
+    `Fix with: amicus aliases --review, or amicus setup --add-alias ${alias}=provider/model`
   );
 }
 

package/src/utils/alias-state.js

@@ -0,0 +1,88 @@
+/**
+ * @module utils/alias-state
+ * Following-vs-pinned state for model aliases (#238 D1) and the normalization
+ * that keeps config.json truthful (D6).
+ *
+ * A curated alias FOLLOWS the shipped pin when its name is ABSENT from
+ * `config.aliases` — `config.js :: getEffectiveAliases` already merges
+ * `{...DEFAULT_ALIASES, ...userAliases}`, so absence resolves to the shipped
+ * id on every consumer. A present key is a PIN. Downgrade-safe in the narrow
+ * sense: an older amicus reads a normalized config without error and
+ * honours every present key (a pin) unchanged; the aliases that FOLLOW
+ * resolve to that older binary's shipped pins — following means tracking
+ * whichever binary runs.
+ *
+ * Normalization drops any key whose value equals the shipped default, with one
+ * Notice per key. It runs inside `saveConfig` (so every write converges) and on
+ * entry to `amicus aliases`. It is idempotent and never a startup write.
+ *
+ * Own keys only, everywhere: a `toString`/`constructor` name in a user
+ * config is a plain custom alias, never a curated one; a `__proto__` key
+ * gets no row at all — `saveConfig` can never persist it.
+ */
+
+'use strict';
+
+const own = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+
+/** @param {string} alias @param {object} defaults @returns {boolean} */
+function isCurated(alias, defaults) {
+  return !!defaults && typeof alias === 'string' && own(defaults, alias);
+}
+
+/**
+ * @param {object} aliases user `config.aliases`
+ * @param {object} defaults the shipped map (`DEFAULT_ALIASES`)
+ * @param {(line: string) => void} [notify] one call per removed key
+ * @returns {{aliases: object, removed: Array<{alias: string, id: string}>}}
+ */
+function normalizeAliases(aliases, defaults, notify) {
+  // Null-prototype (not plain `{}`): `out['__proto__'] = value` on a plain
+  // object hits the inherited accessor setter and is silently LOST -- the
+  // same footgun `saveConfig`'s pre-existing stripper documents for `cleaned`.
+  // Not reachable from `saveConfig` today (that stripper rejects `__proto__`
+  // before this function ever sees it), but this module is also entered
+  // directly from `amicus aliases` on raw config, so `out` must be safe on
+  // its own. `JSON.stringify` serializes a null-prototype object's own keys
+  // exactly like a plain one, so returning it as-is is safe for saveConfig.
+  const out = { __proto__: null };
+  const removed = [];
+  if (!aliases || typeof aliases !== 'object') { return { aliases: out, removed }; }
+  for (const [alias, value] of Object.entries(aliases)) {
+    if (typeof value === 'string' && isCurated(alias, defaults) && defaults[alias] === value) {
+      removed.push({ alias, id: value });
+      if (typeof notify === 'function') {
+        notify(`Notice: alias '${alias}' matches the shipped recommendation (${value}) — now following\n`);
+      }
+      continue;
+    }
+    out[alias] = value;
+  }
+  return { aliases: out, removed };
+}
+
+/**
+ * @param {object|null} userAliases
+ * @param {object} defaults
+ * @returns {Array<{alias:string,id:string,state:'following'|'pinned',curated:boolean,shipped:string|null}>}
+ */
+function listAliasRows(userAliases, defaults) {
+  const user = (userAliases && typeof userAliases === 'object') ? userAliases : {};
+  const rows = [];
+  for (const alias of Object.keys(defaults || {})) {
+    const pinned = own(user, alias) && typeof user[alias] === 'string';
+    rows.push({ alias, id: pinned ? user[alias] : defaults[alias], state: pinned ? 'pinned' : 'following',
+      curated: true, shipped: defaults[alias] });
+  }
+  for (const alias of Object.keys(user)) {
+    // #249 r1 R8b: '__proto__' can never be persisted (saveConfig's own
+    // stripper rejects it, config.js :: saveConfig) -- a row for it here
+    // would show state the user can never actually reach, so it gets no
+    // row and no proposal.
+    if (alias === '__proto__' || isCurated(alias, defaults) || typeof user[alias] !== 'string') { continue; }
+    rows.push({ alias, id: user[alias], state: 'pinned', curated: false, shipped: null });
+  }
+  return rows;
+}
+
+module.exports = { normalizeAliases, listAliasRows, isCurated };