amicus 4.9.8 → 4.10.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.9.8",
+  "version": "4.10.0",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "author": {
     "name": "Christian Wagner"

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 All notable changes to Amicus are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [4.10.0] - 2026-09-14
+
+### Added
+
+- **`amicus aliases`** — your model aliases as a standing command: `following` (the shipped
+  pin, moves with releases) vs `pinned` (yours), grouped by vendor; `--review` walks every
+  proposal in a numbered picker (accept a newer same-tier sibling, follow the shipped pin,
+  choose another catalog id, skip, or never ask again — no copy-paste); `--json` for scripts.
+  Without a terminal `--review` prints the list, says it is interactive, and exits 1;
+  `--unpin <name>` removes a pin (a curated name goes back to following, a custom name is
+  deleted); refuses instead when `name` is also your (non-curated) `config.default`, so a
+  delete can never leave the default dangling on a key that no longer resolves — pick a new
+  default first. The sibling comparator behind "newer same-tier sibling" (and shared with the
+  CI alias-pin drift gate, `scripts/check-ci-alias-pins.js`) never reads a size/variant token
+  glued to a number (`20b`, `8x22b`) as a version, so a differently-sized variant is never
+  offered as a sibling of another. (#238, #249)
+
+### Changed
+
+- **A curated alias follows the shipped pin unless you pin it.** A name absent from
+  `config.aliases` resolves to the pin amicus ships (this is how the merge always worked);
+  a present key is a pin. On save, a key equal to the shipped pin is dropped with a Notice —
+  every alias still resolves to the same id it did before. The setup wizard no longer seeds
+  the 21 curated ids; it pins only the default you chose, and only when its live flagship
+  differs from the shipped pin, and says so. (#238 D1/D6/Q9)
+- **The drift report cannot propose a downgrade.** `models --check`'s family fallback-drift
+  line ignores non-authoritative catalog rows and is silent when the OpenRouter namespace was
+  rejected this run. (#238 §5)
+- The `--add-alias` copy-paste hints in `models --check`, model validation and alias repair now
+  point at `amicus aliases --review` where the alias is reviewable there. (#238 D4)
+
 ## [4.9.8] - 2026-09-13
 
 ### Changed

package/README.md

@@ -419,6 +419,7 @@ When you don't need a full council — just one other model's take — fork a co
 | `amicus status <id>` | One-shot status for a session or fan-out wave (human or `--json`; `--wave <id>` alternative spelling). |
 | `amicus watch <id>` | Live-render a fan-out wave, council run, or session from any terminal until it finishes — in-place table on a TTY, `--plain` milestone lines, or `--json` NDJSON; exit code maps the terminal state. `--ui` opens the [Council Workspace](./docs/council.md#council-workspace-gui) window instead (interactive-only, no `--json`). |
 | `amicus models` | List, search, refresh the catalog, or audit aliases. |
+| `amicus aliases` | Your model aliases — following / pinned; `--review` walks the update proposals, `--unpin <name>` removes a pin, `--json` for scripts. |
 | `amicus doctor` | Diagnose your setup — keys, default model, catalog, aliases, OpenCode binary, Electron, skills, MCP registration, OpenRouter credit (`--json`; `--fix` self-heals what it can). |
 | `amicus spend` | Cross-run cost rollup from the spend ledger, with per-run attribution — total + per-model spend, tokens, and source mix, most-expensive first (`--wave`/`--council`/`--project`/`--model`/`--op`/`--failed` filter it, `--group-by` buckets it, `--since 7d` windows it; `--json` for a versioned doc; shows remaining OpenRouter credit when a key is configured). |
 | `amicus key` | Manage API keys non-interactively: `amicus key <provider> <key>` saves after live validation; `--remove`; bare `amicus key` lists providers. |
@@ -455,7 +456,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.9.8",
+  "version": "4.10.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/bin/amicus.js

@@ -165,6 +165,11 @@ async function main() {
         exitCode = await handleModels(args);
         break;
       }
+      case 'aliases': {
+        const { handleAliases } = require('../src/sidecar/aliases');
+        exitCode = await handleAliases(args);
+        break;
+      }
       case 'council': {
         const { handleCouncil } = require('../src/cli-handlers-council');
         exitCode = await handleCouncil(args);

package/docs/ROADMAP.md

@@ -13,13 +13,14 @@ lives under **Backlog (tracked, not scheduled)** with everything else that is re
 Nothing about the content changed and no judgment about its value is implied; only its status. When
 an org buyer and the org to support them exist, it earns a number then.
 
-Amicus is at **v4.9.8** (2026-09-13). Each 4.x rev below leads with the benefit, not the
-plumbing; the patch releases since v4.9.0 carry no section of their own, because each corrected a
+Amicus is at **v4.10.0** (2026-09-14). Each 4.x rev below leads with the benefit, not the
+plumbing; the v4.9.x patch releases carry no section of their own, because each corrected a
 defect rather than adding scope — where one added a surface (v4.9.4's `--thinking` refusals and
 `output-budget` doctor row, v4.9.5's Electron digest gate, v4.9.6's artifact custody, v4.9.7's dual name-table rescue boundary, v4.9.8's per-run seat tool allowlist and its unverified/refused seat census) it did so to
-make an existing promise true, not to widen it. See `CHANGELOG.md` for what each one contained.
+make an existing promise true, not to widen it. v4.10.0 adds a surface (`amicus aliases`) and so
+gets a section. See `CHANGELOG.md` for what each one contained.
 
-**Status:** v4.0 through **v4.9.0** have **shipped**, plus the v4.9.1–v4.9.8 patch releases —
+**Status:** v4.0 through **v4.10.0** have **shipped**, plus the v4.9.1–v4.9.8 patch releases —
 everything on this page is a record of what landed, not a plan. Composition — the scope that
 carried the number v4.6 here until the degrade-announcement-invariant milestone took the v4.6.0
 release (2026-08-02) — is now an unscheduled candidate for the next rev, tabled in its own section
@@ -447,6 +448,33 @@ a verdict about a review that never happened.
 > to do* — announcing losses, counting money, attributing seats. v4.9 changes what a council can be
 > asked for in the first place, which is a different kind of rev and is scoped as one.
 
+## v4.10 — "Your aliases follow the pins" *(follow-or-pin aliases — #238 Phase 1)* — ✅ SHIPPED v4.10.0, 2026-09-14
+**Benefit:** a curated alias tracks the pin amicus ships until you deliberately pin it, and
+`amicus aliases` shows which is which and walks every worthwhile change in a numbered picker —
+no more copy-pasting `--add-alias` lines out of `models --check`.
+
+- **★ `amicus aliases`** — every alias as `following` (the shipped pin, moves with releases) or
+  `pinned` (yours), grouped by vendor; `--review` proposes one change per pinned alias (a strictly
+  newer same-tier sibling, the shipped pin, a same-vendor replacement for an id gone from the
+  catalog) and accepts, skips or dismisses it in place; `--json` for scripts; `--unpin <name>`
+  removes a pin (a curated name goes back to following, a custom name is deleted, the alias your
+  default points at is refused). **Closes the user half of #238** *(L)*
+- **Absence is follow** — a name absent from `config.aliases` resolves to the shipped pin, a
+  present key is a pin, and a key equal to the shipped pin is dropped on save with a Notice; the
+  setup wizard stops seeding the 21 curated ids and pins only the default you chose, and only when
+  its live flagship differs from the shipped one *(M)*
+- **The drift report cannot propose a downgrade** — `models --check`'s fallback-drift line ignores
+  non-authoritative catalog rows and is silent when the OpenRouter namespace was rejected *(S)*
+- **The sibling comparator is tier-safe** — lifted out of the CI alias-pin drift gate and shared
+  with it; a size or variant token glued to a number (`20b`, `8x22b`, `4o`) is never read as a
+  version, so a differently-sized model is never offered as a "newer" sibling *(S)*
+> Why here: the two council rounds on #249 (16 + 13 findings) shaped the release — the typed
+> shipped id follows without a catalog, the comparator's size rule, the `--unpin` default guard
+> and the terminal-escape sanitizer on every alias surface all came out of them. Phases 2–4 of
+> the #238 design (owner mode with `curated-pins.json`, the Electron "Needs review" section, the
+> quiet update notice) are unscheduled; the spec that scopes them ships in the repo under
+> `docs/superpowers/specs/`.
+
 ## Backlog (tracked, not scheduled)
 
 ### Enterprise-readiness *(unscheduled — gated on funding / cofounder)*

package/docs/architecture-map.md

@@ -106,6 +106,11 @@ src/
 ├── prompts/
 │   └── cowork-agent-prompt.js  # Cowork Agent Prompt
 ├── sidecar/
+│   ├── aliases-review-gate.js  # Pure §5-gate helpers for `amicus aliases --review` (#249 r1 R2/R3), split
+│   ├── aliases-review-prompt.js  # The real-readline prompt for `amicus aliases --review`, split out of
+│   ├── aliases-review-render.js  # Pure, side-effect-free screen text for `amicus aliases --review` (#238 §4),
+│   ├── aliases-review.js  # `amicus aliases --review` (#238 §4): a numbered readline picker over the
+│   ├── aliases.js  # `amicus aliases` (#238 D4) — the user's alias map as a standing command.
 │   ├── budget.js
 │   ├── child-sessions.js
 │   ├── context-builder.js  # Context Builder Module
@@ -185,9 +190,13 @@ src/
 │   ├── activity-poller.js
 │   ├── agent-mapping.js  # Agent Mapping Module
 │   ├── alias-audit.js  # Alias Audit (F5) — report + suggest for most classes; doctor --fix auto-repairs one narrow, mechanically-unambiguous class (B3).
+│   ├── alias-groups.js  # Vendor-derived alias grouping (issue 213). Moved VERBATIM out of
+│   ├── alias-proposals.js  # The alias review ENGINE (#238 §2): pure, no I/O, no prompts. Turns
 │   ├── alias-resolver.js  # Alias Resolver Utilities
 │   ├── alias-shadow-writer.js  # The alias-shadow notice's WRITE half: say it without ever sinking the run.
 │   ├── alias-shadow.js  # Alias-shadow self-diagnosis — name a local alias that repoints a curated one.
+│   ├── alias-state.js  # Following-vs-pinned state for model aliases (#238 D1) and the normalization
+│   ├── alias-store.js  # The write sinks the alias review flow needs beyond `setup.js :: addAlias`
 │   ├── api-key-store.js  # API Key Store — reading, saving, and validating API keys.
 │   ├── api-key-validation.js  # API Key Validation — test API keys against provider endpoints.
 │   ├── atomic-write.js  # Atomic file write helper.
@@ -252,6 +261,7 @@ src/
 │   ├── model-classification.js  # Tri-state catalog classification (#61).
 │   ├── model-descriptor.js  # Model-descriptor grammar + RouteResult factories (#61).
 │   ├── model-fetcher.js  # Model Fetcher
+│   ├── model-id-siblings.js  # The tier-safe sibling comparator (#238 D7). A sibling shares a pin's vendor
 │   ├── model-input-default.js
 │   ├── model-output-limit.js  # Issue #218 — the per-model `limit` descriptor amicus hands opencode.
 │   ├── model-shortlist.js  # Vendor model shortlist (#138) -- the family -> model second level.
@@ -573,6 +583,11 @@ evals/
 | `pack/pack-store.js` |  | `packsDir()`, `canonicalHash()`, `resolvePackRef()`, `readPack()`, `writePack()` |
 | `pack/pack-validate.js` |  | `validatePack()`, `KIND_OPTIONS()`, `KINDS()` |
 | `prompts/cowork-agent-prompt.js` | Cowork Agent Prompt | `buildCoworkAgentPrompt()` |
+| `sidecar/aliases-review-gate.js` | Pure §5-gate helpers for `amicus aliases --review` (#249 r1 R2/R3), split | `classifyTypedId()`, `notInCatalogLine()`, `notVerifiedLine()`, `staleCatalogBanner()` |
+| `sidecar/aliases-review-prompt.js` | The real-readline prompt for `amicus aliases --review`, split out of | `createPrompt()` |
+| `sidecar/aliases-review-render.js` | Pure, side-effect-free screen text for `amicus aliases --review` (#238 §4), | `ageLabel()`, `menuFor()`, `menuLineText()`, `renderScreen()`, `refreshingCatalogLine()` |
+| `sidecar/aliases-review.js` | `amicus aliases --review` (#238 §4): a numbered readline picker over the | `runReview()` |
+| `sidecar/aliases.js` | `amicus aliases` (#238 D4) — the user's alias map as a standing command. | `handleAliases()`, `collectAliasView()`, `renderAliasList()`, `buildAliasesDoc()`, `loadDeps()` |
 | `sidecar/budget.js` |  | `checkBudget()`, `formatBudgetError()`, `DEFAULT_MAX_COST_PER_MTOK()`, `ASSUMED_OUTPUT_TOKENS()` |
 | `sidecar/child-sessions.js` |  | `collectSubtreeUsage()`, `subtreeIsUnknown()`, `SUBTREE_MAX_DEPTH()`, `SUBTREE_MAX_SESSIONS()` |
 | `sidecar/context-builder.js` | Context Builder Module | `buildContext()`, `parseDuration()`, `resolveSessionFile()`, `applyContextFilters()`, `findCoworkSession()` |
@@ -650,9 +665,13 @@ evals/
 | `utils/activity-poller.js` |  | `createActivityPoller()`, `killIfAlive()` |
 | `utils/agent-mapping.js` | Agent Mapping Module | `PRIMARY_AGENTS()`, `OPENCODE_AGENTS()`, `HEADLESS_SAFE_AGENTS()`, `mapAgentToOpenCode()`, `isValidAgent()` |
 | `utils/alias-audit.js` | Alias Audit (F5) — report + suggest for most classes; doctor --fix auto-repairs one narrow, mechanically-unambiguous class (B3). | `collectAliasSources()`, `findStaleAliases()`, `findDriftedStoredAliases()`, `suggestReplacements()`, `findFabricatedAliasRepairs()` |
+| `utils/alias-groups.js` | Vendor-derived alias grouping (issue 213). Moved VERBATIM out of | `groupAliases()`, `aliasVendorOf()`, `vendorLabel()`, `titleCaseVendor()`, `PREFERRED_VENDOR_ORDER()` |
+| `utils/alias-proposals.js` | The alias review ENGINE (#238 §2): pure, no I/O, no prompts. Turns | `buildAliasProposals()`, `gatedCatalogIds()` |
 | `utils/alias-resolver.js` | Alias Resolver Utilities | `autoRepairAlias()` |
 | `utils/alias-shadow-writer.js` | The alias-shadow notice's WRITE half: say it without ever sinking the run. | `safeWrite()`, `armStream()`, `writeNoticeToStderr()` |
 | `utils/alias-shadow.js` | Alias-shadow self-diagnosis — name a local alias that repoints a curated one. | `findAliasShadows()`, `formatAliasShadow()`, `noteAliasShadows()`, `auditAliasShadows()` |
+| `utils/alias-state.js` | Following-vs-pinned state for model aliases (#238 D1) and the normalization | `normalizeAliases()`, `listAliasRows()`, `isCurated()` |
+| `utils/alias-store.js` | The write sinks the alias review flow needs beyond `setup.js :: addAlias` | `removeAlias()`, `readDismissals()`, `recordDismissal()` |
 | `utils/api-key-store.js` | API Key Store — reading, saving, and validating API keys. | `getEnvPath()`, `loadEnvEntries()`, `readApiKeys()`, `readApiKeyHints()`, `readApiKeyValues()` |
 | `utils/api-key-validation.js` | API Key Validation — test API keys against provider endpoints. | `validateApiKey()`, `redactSecret()`, `validateOpenRouterKey()`, `checkOpenRouterCredit()`, `OPENROUTER_NO_CREDIT_WARNING()` |
 | `utils/atomic-write.js` | Atomic file write helper. | `writeFileAtomic()` |
@@ -717,6 +736,7 @@ evals/
 | `utils/model-classification.js` | Tri-state catalog classification (#61). | `classifyModel()` |
 | `utils/model-descriptor.js` | Model-descriptor grammar + RouteResult factories (#61). | `GATEWAY_MODES()`, `parseDescriptor()`, `resolved()`, `selectionRequired()`, `routeError()` |
 | `utils/model-fetcher.js` | Model Fetcher | `fetchModelsFromProvider()`, `fetchAllModels()`, `fetchAllModelsDetailed()`, `fetchModelsFromProviderDetailed()`, `providersToFetch()` |
+| `utils/model-id-siblings.js` | The tier-safe sibling comparator (#238 D7). A sibling shares a pin's vendor | `parsePin()`, `compareVersions()`, `newestSibling()` |
 | `utils/model-input-default.js` |  | `resolveModelInputOrDefault()` |
 | `utils/model-output-limit.js` | Issue #218 — the per-model `limit` descriptor amicus hands opencode. | `normalizeOutputBudget()`, `buildLimitLookup()`, `computeModelLimit()`, `positiveCount()` |
 | `utils/model-shortlist.js` | Vendor model shortlist (#138) -- the family -> model second level. | `buildModelShortlist()`, `compareShortlistRows()`, `SHORTLIST_LIMIT()` |
@@ -736,7 +756,7 @@ evals/
 | `utils/provider-default-picker.js` | Provider-default picker core (Part 2, Task 4). | `buildProviderDefaultChoices()`, `applyProviderDefault()`, `pricePerMInputFrom()`, `directFormIfSafe()`, `directFormIfProven()` |
 | `utils/provider-default-prompt.js` | Provider-default prompt flow (Part 2, Task 6/7 shared helper). | `runProviderDefaultFlow()`, `formatPrice()`, `formatRow()` |
 | `utils/provider-registry.js` | Provider-capability registry — the single source of truth for provider | `PROVIDERS()`, `getProvider()`, `isDirectProvider()`, `listDirectProviders()`, `PROVIDER_ENV_MAP()` |
-| `utils/quick-picks.js` | Quick-pick resolution (wizard Step 2) — resolves each curated family to | `compareIdsDesc()`, `canonicalRoutesFor()`, `pickCurrent()`, `resolveQuickPicks()`, `toLiveSeedAliases()` |
+| `utils/quick-picks.js` | Quick-pick resolution (wizard Step 2) — resolves each curated family to | `compareIdsDesc()`, `canonicalRoutesFor()`, `pickCurrent()`, `resolveQuickPicks()`, `toStorableRoute()` |
 | `utils/read-slice.js` | Byte-bounded slicing for amicus_read (15a.3 / B17). | `sliceForRead()`, `READ_CAP_BYTES()` |
 | `utils/remediation-hints.js` |  |  |
 | `utils/result-schema-rebuild.js` |  | `buildRunResultFromSession()`, `buildWaveResultFromSession()` |
@@ -757,7 +777,7 @@ evals/
 | `utils/shared-server.js` |  | `SharedServerManager()` |
 | `utils/spend-ledger.js` |  | `appendSpend()`, `readSpendRows()`, `SPEND_LEDGER_FILE()`, `SPEND_LEDGER_SCHEMA_VERSION()` |
 | `utils/start-helpers.js` | Start Command Helpers | `resolveLaunchModel()`, `deriveAlias()`, `maybeOfferProviderDefaults()` |
-| `utils/text-sanitize.js` | One third-party string, safe to render: no escapes, no bidi, one short line. | `collapseExcerpt()`, `MAX_EXCERPT_CHARS()` |
+| `utils/text-sanitize.js` | One third-party string, safe to render: no escapes, no bidi, one short line. | `collapseExcerpt()`, `MAX_EXCERPT_CHARS()`, `safeFragment()`, `MAX_FRAGMENT_CHARS()` |
 | `utils/thinking-validators.js` | Thinking Level Validators | `VARIANT_LEVELS()`, `validateThinkingLevel()` |
 | `utils/ttft.js` | The one honesty predicate for the time-to-first-token probe (v4.9 W13). | `isMeasuredTtft()` |
 | `utils/untrusted-fence.js` | Untrusted sidecar output fence. | `fenceSidecarOutput()`, `defangOutboundFenceTags()`, `OUTBOUND_FENCE_TAGS()` |

package/docs/configuration.md

@@ -540,7 +540,7 @@ amicus models --check && echo "aliases ok"
 
 ## Model Aliases
 
-Aliases are short names that resolve to full provider-prefixed model IDs. `amicus setup` seeds a curated default set (e.g. `gemini`, `gpt`, `opus`, `deepseek`) to the bare canonical form for direct-capable vendors. You add or override aliases with:
+Aliases are short names that resolve to full provider-prefixed model IDs. Amicus ships a curated set (`gemini`, `gpt`, `opus`, `deepseek`, `claude`, `glm`, …) that resolves to the pins the package ships — an alias you have not pinned FOLLOWS those pins and moves with each release. `amicus setup` no longer copies them into your config; it pins only the default alias you chose, and only when its live flagship differs from the shipped pin. See `amicus aliases` for what resolves on your machine. You add or override aliases with:
 
 ```bash
 amicus setup --add-alias fast=google/gemini-3.1-flash-lite-preview
@@ -671,14 +671,14 @@ level includes everything above it.
   // Default alias, resolved via `aliases` below when --model is omitted.
   "default": "gemini",
 
-  // Short name -> full model id. Bare `provider/model` (canonical) routes direct-first;
-  // `amicus setup` seeds direct-capable vendors this way automatically.
-  // `amicus setup --add-alias name=provider/model` adds more.
+  // Short name -> full model id, for the aliases YOU pinned. A curated alias
+  // (gemini, gpt, opus, …) that is ABSENT here FOLLOWS the pin amicus ships and
+  // moves with each release; a present key is pinned and reviewable with
+  // `amicus aliases --review`. A key equal to the shipped pin is dropped on save
+  // (with a Notice) — it is the same as following.
   "aliases": {
-    "gemini": "google/gemini-3-pro-preview",
-    "gpt": "openai/gpt-5",
-    "opus": "anthropic/claude-opus-4",
-    "deepseek": "deepseek/deepseek-v3"
+    "glm": "openrouter/z-ai/glm-5.4",
+    "fast": "google/gemini-3.6-flash-lite"
   },
 
   // Named council member lists, e.g. seeded by the Free OpenRouter council
@@ -700,6 +700,12 @@ level includes everything above it.
     "tier_onboarded": true
   },
 
+  // Written by `amicus aliases --review`'s "never ask again" — keyed
+  // `alias@proposedId`; hand-delete a key here to be asked again.
+  "aliasReview": {
+    "dismissed": { "glm@openrouter/z-ai/glm-5.4": "2026-09-14T00:00:00.000Z" }
+  },
+
   // User-defined local / OpenAI-compatible providers (v4.2) — written by
   // `amicus provider add`, or hand-edited. id -> normalized entry; `pricing`
   // defaults to {prompt: 0, completion: 0} (the $0 tier) when omitted.

package/docs/usage.md

@@ -21,6 +21,8 @@ amicus abort --all [--json]
 # Setup & maintenance
 amicus setup                              # Full wizard: keys, default model, aliases
 amicus setup --api-keys                   # Open just the API-key step
+amicus aliases                      # your aliases: following (shipped pin) / pinned (yours)
+amicus aliases --review             # walk the proposals — no copy-paste
 amicus setup --add-alias fast=google/gemini-3.1-flash-lite-preview  # bare canonical, direct-first
 amicus models                             # List the live catalog
 amicus models --search gemini             # Filter by substring
@@ -397,7 +399,24 @@ direct namespace while the OpenRouter route still serves — a gateway-only rout
 no direct sibling is a routing choice, not staleness. Deliberately gateway-only
 entries (e.g. `gpt-pro`) are annotated as such and are never offered a retarget.
 
-**Drifted aliases.** `--check` (and the `doctor` aliases row) also flags **`DRIFTED:`** stored aliases — a stored alias whose target is still catalog-listed but no longer matches any route its family currently resolves to (the v4.6.1 `gemini` release-gate class, where `doctor` stayed green while the model behind it had moved on). Each drift line prints the exact `amicus setup --add-alias <alias>=<current>` refresh command. Drift is informational only by default and does not change the exit code — pass `--strict` alongside `--check` to make curated per-gateway drift (stale or divergent direct/OpenRouter forms) exit non-zero too.
+### Aliases: following vs pinned
+
+A curated alias (`gemini`, `gpt`, `opus`, `deepseek`, …) absent from `config.aliases` **follows** the pin Amicus ships and moves to the new target on every release; a present key **pins** it to that exact id and makes it reviewable.
+
+```bash
+amicus aliases            # every alias: following (shipped pin) / pinned (yours), by vendor
+amicus aliases --review   # walk outdated pins in a numbered picker — no copy-paste
+amicus aliases --unpin <name>   # remove a pin: a curated name goes back to following, a custom name is deleted
+amicus aliases --json     # the same document, for scripts
+```
+
+`--review` offers, per outdated pin: accept a newer same-tier sibling, follow the shipped pin again, choose another catalog id, skip, or never ask again for that pairing — it needs a terminal (without one it prints the list and exits 1). Picking "follow the shipped pin" removes the key from `config.aliases`, and typing that SAME shipped id into "choose another" follows too — unconditionally, whether or not the catalog carries it or is fresh, since it is the same `follow` action either way. A newer same-tier sibling is judged by vendor path, prefix and suffix around the version number; a size or variant token glued to a number (`20b`, `8x22b`) is never read as part of that version, so a differently-sized variant of a model is never offered as a "newer" sibling of it. `amicus setup` no longer seeds all 21 curated ids — it pins only the default alias you chose, and only when its live flagship differs from the shipped pin, and says so.
+
+Accepting a catalog-vouched id needs a catalog fresher than 24 hours — the picker refreshes it inline first (an authenticated model-list call to each provider you hold a key for, the same call `amicus models --refresh` makes); `follow` never needs the catalog.
+
+`--unpin <name>` refuses instead of writing when `name` is also your `config.default` and is not a curated alias — deleting it would leave the default pointing at a key that no longer resolves, so pick a new default first (`amicus setup`) or unpin a different alias. A curated default is unaffected: it keeps resolving from the shipped table after the unpin, same as any other curated unpin.
+
+**Drifted aliases.** `--check` (and the `doctor` aliases row) also flags **`DRIFTED:`** stored aliases — a stored alias whose target is still catalog-listed but no longer matches any route its family currently resolves to (the v4.6.1 `gemini` release-gate class, where `doctor` stayed green while the model behind it had moved on). Each drift line points at `amicus aliases --review`. Drift is informational only by default and does not change the exit code — pass `--strict` alongside `--check` to make curated per-gateway drift (stale or divergent direct/OpenRouter forms) exit non-zero too.
 
 **Live probe (`--check --live`).** Presence in the catalog is not proof of service — a stored alias can point at a model id the catalog still lists but the provider has quietly stopped serving (the v4.6.1 `gemini` incident). `--check` alone can't see that; `--live` can, by actually asking. Scope is **stored aliases only** (`amicus setup --add-alias`) — curated defaults follow the catalog by construction and have no "was it actually served" question for a live probe to answer. **This spends real money — one tiny leg per stored alias** — every probed alias gets one ordinary engine leg on a single quiet fan-out wave, with a real session dir and a real spend-ledger row, exactly as if you'd run it yourself.
 
@@ -417,7 +436,7 @@ Each stored alias resolves to one of three outcomes:
 
 **Validation on launch.** `start` and `fanout` validate the model against the catalog before launching. For an explicit `--model` on `continue`/`resume` this is **blocking** (a typo'd model fails fast with suggestions); for a model *inherited* from a prior session it's **advisory**. Skip it any time with `--no-validate-model`, or fix the catalog with `amicus models --refresh`.
 
-**Aliases are a curated seed, not a fixed list.** `amicus setup` seeds a curated set of short aliases (e.g. `gemini`, `gpt`, `opus`, `deepseek`), and you add or override them with `amicus setup --add-alias name=provider/model`. To see exactly what resolves on *your* machine, run `amicus models` — that is the source of truth.
+**Curated aliases follow the shipped pins unless you pin them.** The curated aliases (`gemini`, `gpt`, `opus`, …) are shipped and follow the package's pins unless you pin them — pin one, or add an entirely new one, with `amicus setup --add-alias name=provider/model`. To see exactly what resolves on *your* machine, run `amicus aliases` — that is the source of truth.
 
 **Full-id passthrough.** You can always bypass aliases and name a model directly. Bare `provider/model` is the canonical, policy-routed form; `openrouter/provider/model` is an explicit override. See [Routing](../README.md#routing) for the full explanation — summary:
 
@@ -542,7 +561,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.9.8",
+  "version": "4.10.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/electron/ipc-setup.js

@@ -176,21 +176,18 @@ function registerSetupHandlers(getMainWindow, { ipcMain = require('electron').ip
   });
 
   // Read-modify-write: never rewrite an alias the renderer didn't send.
-  // aliasWrites values: string = set, null = delete. First run seeds live.
+  // aliasWrites values: string = set, null = delete. First run starts from
+  // an empty alias map (issue 238 Q9).
   // councilPicks (optional): when length >= 2, seeds the free council via seedFreeCouncil.
   ipcMain.handle('sidecar:save-config', async (_event, defaultModel, aliasWrites, councilPicks) => {
     try {
       const { loadConfig, saveConfig } = require('../src/utils/config');
       let cfg = loadConfig();
       if (!cfg) {
-        const { toLiveSeedAliases } = require('../src/utils/quick-picks');
-        // issue 214: getCatalogInfo, not getCatalog -- toLiveSeedAliases PERSISTS
-        // these routes, so it must see which namespaces were rejected.
-        let catalogInfo = { models: [] };
-        try {
-          catalogInfo = await require('../src/utils/model-catalog').getCatalogInfo();
-        } catch (_err) { /* offline: pinned seeds */ }
-        cfg = { aliases: toLiveSeedAliases(catalogInfo) };
+        // issue 238 Q9: nothing is seeded — a curated alias follows the
+        // shipped pin by being absent (D1). Only the renderer's explicit
+        // writes land.
+        cfg = { aliases: {} };
       }
       if (!cfg.aliases) { cfg.aliases = {}; }
       if (defaultModel) { cfg.default = defaultModel; }

package/electron/setup-ui-alias-groups.js

@@ -1,138 +1,42 @@
 /**
  * Setup UI - Alias grouping rule (issue 213)
  *
- * The Step 3 alias editor used to bucket rows with a hardcoded list of alias
- * NAMES, and `Other` was itself a fixed key list rather than a catch-all — so
- * any alias whose name was not on the list (a local-provider route, a `free-*`
- * council member, a case variant like `GLM`) rendered nowhere at all.
+ * The grouping rule itself (groupAliases / aliasVendorOf / vendorLabel /
+ * titleCaseVendor / PREFERRED_VENDOR_ORDER) now lives in
+ * src/utils/alias-groups.js (issue 238 PR1 fix wave F5): `src/sidecar/aliases.js`
+ * (the CLI `amicus aliases` list) needed the same grouping, and `src/`
+ * requiring from `electron/` is a layering violation the whole-branch review
+ * caught. This file re-exports exactly those five symbols -- groupAliases,
+ * aliasVendorOf, vendorLabel, titleCaseVendor, PREFERRED_VENDOR_ORDER -- so
+ * electron/setup-ui-aliases.js, electron/setup-ui-alias-script.js and every
+ * existing test keep working untouched, and keeps its own genuinely UI-only
+ * export (NEW_ROUTES_GROUP_LABEL) defined here. `ALIAS_VENDOR_LABELS` (the
+ * vendor -> display-name table `vendorLabel` looks up) stayed
+ * module-private to alias-groups.js -- it is not one of the five and
+ * nothing imports it directly (issue 249 review round 1, finding D2).
  *
- * Grouping is now derived from the alias's ROUTE VENDOR, which every alias has.
- *
- * 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.
- *
- * SHARED-WITH-THE-BROWSER NOTE — deliberately NOT shared. The wizard's inline
- * script cannot `require`, so the browser could only get this rule as a copy:
- * hand-written (silent divergence — a 3-segment direct id like `a/b/c` already
- * splits differently under the two obvious spellings) or serialised from the
- * source below (which would put `slice('openrouter/'.length)` back into the
+ * SHARED-WITH-THE-BROWSER NOTE (still applies to the grouping rule, wherever
+ * it lives) — deliberately NOT shared. The wizard's inline script cannot
+ * `require`, so the browser could only get this rule as a copy: hand-written
+ * (silent divergence — a 3-segment direct id like `a/b/c` already splits
+ * differently under the two obvious spellings) or serialised from the
+ * source (which would put `slice('openrouter/'.length)` back into the
  * page). The page carrying its own gateway-prefix strip is the exact shape
  * issue 214 removed and that tests/setup-ui.test.js still guards
  * ("ships no routing policy to the page: ... no prefix derivation"), because
  * that copy is how a direct id gets fabricated for a namespace that never
  * served it.
  *
- * So there is ONE grouping rule and it lives here, server-side. The client
- * (setup-ui-alias-script.js) never derives a vendor: a route added during the
- * session goes into its own clearly-labelled "New routes" group, and vendor
- * filing happens when the server next renders the editor.
- */
-
-const { vendorOf } = require('../src/sidecar/fallback-chains');
-const { PROVIDER_FAMILY_NAMES, listDirectProviders } = require('../src/utils/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.
- */
-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. */
-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
+ * So there is ONE grouping rule and it lives server-side (now in
+ * src/utils/alias-groups.js). The client (setup-ui-alias-script.js) never
+ * derives a vendor: a route added during the session goes into its own
+ * clearly-labelled "New routes" group, and vendor filing happens when the
+ * server next renders the editor.
  */
-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. */
-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()));
-}
+const {
+  groupAliases, aliasVendorOf, vendorLabel, titleCaseVendor, PREFERRED_VENDOR_ORDER,
+} = require('../src/utils/alias-groups');
 
 /**
  * Heading for the client-side group that holds routes added during THIS
@@ -153,9 +57,10 @@ function groupAliases(aliases) {
 const NEW_ROUTES_GROUP_LABEL = 'New routes (this session)';
 
 module.exports = {
-  ALIAS_VENDOR_LABELS,
   NEW_ROUTES_GROUP_LABEL,
   aliasVendorOf,
   vendorLabel,
   groupAliases,
+  titleCaseVendor,
+  PREFERRED_VENDOR_ORDER,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.9.8",
+  "version": "4.10.0",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [

package/src/cli-handlers.js

@@ -47,7 +47,14 @@ async function handleSetup(args) {
       process.exit(1);
     }
     addAlias(name, model);
-    console.log(`Alias '${name}' added: ${model}`);
+    // Minor (#238 D1 vocabulary): writing the shipped id verbatim is the
+    // same as never having pinned at all -- say so, not "added".
+    const { getDefaultAliases } = require('./utils/config');
+    if (getDefaultAliases()[name] === model) {
+      console.log(`Alias '${name}' now follows the shipped recommendation (${model})`);
+    } else {
+      console.log(`Alias '${name}' added: ${model}`);
+    }
     // F5: warn (never block) when the model is absent from a checkable catalog.
     try {
       const { getCatalog } = require('./utils/model-catalog');

package/src/cli.js

@@ -154,6 +154,7 @@ const BOOLEAN_FLAGS = [
      'fix',                  // doctor: self-heal fixable checks in place (#56)
      'strict',               // models --check: exit non-zero on curated per-gateway drift (#gwid Task 6)
      'live',                 // models --check: opt-in probe of stored aliases with real engine legs (v4.6.2 PR3, spec §6)
+     'review',               // aliases: interactive picker over the review proposals (#238 D4)
      'render',               // council verdict: also refresh report.html next to the decided verdict
      'claude',               // init: register for Claude Code only (Task 15)
      'desktop',              // init: register for Claude Desktop only (Task 15)
@@ -391,6 +392,7 @@ Commands:
   continue    New session building on previous
   read        Output session summary/conversation
   models      List/search the model catalog, refresh it, audit aliases
+  aliases     Your model aliases — following / pinned (--review walks the proposals)
   council run <briefing.md> (--models a,b,c | --council <name>)   Headless council: reviews → cross-review → tally → chair → verdict
   council tally <input.json> [--json]   Tally council findings → tiers/street-cred
   council stats [--json]                Reviewer-reliability from the ledger
@@ -511,6 +513,15 @@ Options for 'models':
                                engine leg (spends) — served / accepted-but-silent /
                                error. Requires --check.
   --json                       Machine-readable output
+`,
+  aliases: `
+Options for 'aliases':
+  --review                     Interactive picker: accept, choose, skip or dismiss each
+                               proposal (stale pin, newer sibling, differs from the
+                               shipped pin). Needs a terminal.
+  --unpin <alias>              Remove a pin: a curated name goes back to following, a
+                               custom name is deleted
+  --json                       Machine-readable document (aliases + proposals)
 `,
   list: `
 Options for 'list':