amicus 4.9.2 → 4.9.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.9.2",
+  "version": "4.9.3",
   "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,88 @@
 All notable changes to Amicus are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [4.9.3] - 2026-08-28
+
+*Doctor stops vouching for things it never checked.*
+
+`doctor`'s `keys` row tested PRESENCE only, and `validateApiKey` was called at exactly two
+save-time sites — so a key that rotted after it was entered was never re-checked. On the
+reporting machine `doctor` printed a green row while the stored DeepSeek key returned 401 and
+the catalog served zero deepseek rows. Closing that gap surfaced a family of the same shape:
+several places reported health they had not established, and two of them were introduced by
+the fixes for the others. Every one is now the same rule — a check that did not complete says
+so, and only a definitive 401 is a verdict about a credential.
+
+### Added
+
+- **`outputBudget` (#218), opt-in, no default change.** Each council leg reserved
+  `max_tokens: 32000` regardless of the model's real ceiling, and OpenRouter validates that
+  RESERVATION against remaining credit *before* serving — so legs died in 2.2 s with zero
+  tokens and "You requested up to 32000 tokens, but can only afford 354". Set `outputBudget`
+  in `config.json` and each leg reserves `min(budget, that model's real ceiling)`; leave it
+  unset and every model is registered exactly as before. A new `maxOutputTokens` catalog field
+  (OpenRouter's `top_provider.max_completion_tokens`, present on 411 of 417 rows) supplies the
+  ceiling, and a model without one keeps the old behaviour rather than receiving a guess.
+  MEASURED in the pinned engine binary: `maxOutputTokens = Math.min(limit.output, 32000)`, so
+  this can only LOWER a reservation — a value at or above 32000 leaves it unchanged. It does
+  not address a reasoning-heavy leg spending its whole allowance and emitting nothing; that is
+  governed by reasoning effort, not by `max_tokens`, and no claim is made otherwise.
+
+### Fixed
+
+- **`doctor` re-validates stored API keys (#210).** New `key-auth` row probes every stored key
+  against its provider's own endpoint, in parallel — sequential 10 s timeouts would have added
+  ~50 s to every run. Only HTTP 401 fails the check; a timeout, DNS failure, 5xx or 429 warns,
+  because being offline is not a rotted key and a false error sends someone to re-enter a
+  working one. A stored key for a provider with no validation endpoint warns rather than
+  reporting ok — it cannot be probed, so the check cannot vouch for it.
+- **403 is no longer treated as a credential verdict.** Google returns 403 for "API not
+  enabled" and for quota; a WAF returns it for bot protection. It warns now, and `amicus key`
+  saves on it rather than refusing — as it does for 429 and 5xx. Only a definitive 401 blocks
+  a save, expressed as an allowlist so it cannot rot as new status codes appear.
+- **The OpenRouter credit row means CHECKED.** `checkOpenRouterCredit` resolves `warning: null`
+  for a healthy account, for a skipped probe, and for every failure alike — so the row rendered
+  "credit ok" for an account nobody had reached, concealing quota exhaustion behind a green
+  line. It now distinguishes all three.
+- **A key can no longer escape in an error message.** `https.get` can throw synchronously, and
+  the Google probe embeds the key in the URL as `?key=…` — so an error quoting that URL quoted
+  the key. Redaction happens at the source now, covering the raw, percent-encoded and
+  form-encoded spellings, which protects the two save-time call sites that have no handling of
+  their own: `electron/ipc-setup.js` returns the message to the renderer *and* logs it, and
+  `src/cli-handlers.js` awaits with no try/catch at all.
+- **`validateApiKey` honours its "always resolves" contract (#224).** `req.on('error')` covered
+  the connection phase only; an error once the response existed — a socket reset mid-body — was
+  an unhandled `'error'` event, which Node turns into a THROW rather than a rejection: the
+  promise never settled and the process died. Both functions in the module handle it now, and
+  the message coercion itself can no longer throw for a null-prototype object or one whose
+  `toString` throws.
+- **Diagnostics no longer make live authenticated requests outside the CLI.** Probes are opt-in,
+  enabled once by `bin/amicus.js`; a skipped probe is reported as unverified, never as healthy.
+  `AMICUS_NO_NETWORK_PROBES=1` forces them off.
+- **The setup wizard renders the aliases you actually have (#213).** The alias editor grouped
+  rows from a hardcoded list of alias NAMES and iterated that whitelist rather than your
+  aliases, so any alias whose name missed the list rendered nowhere — including the `lmstudio`
+  local-provider alias and every `free-*` alias the `councils.free` preset references. Grouping
+  derives from the alias's route vendor now. Measured against a real 33-alias config: 21
+  rendered before, 33 after, none dropped, none duplicated.
+- **A stale pin no longer looks like a recommendation (#211).** When nothing in the catalog
+  matched an alias's current value, the dropdown echoed that value back as a bare ungrouped
+  option — indistinguishable from a real offer, and observed presenting an id that exists on no
+  gateway above 13 genuine ones. It now sits in a labelled "Current — not found in catalog"
+  group. What gets saved is unchanged.
+- **Alias names and routes are HTML-escaped** in the wizard; a quote in an alias name broke the
+  row's `data-alias` attribute.
+
+### Changed
+
+- **CI: the macOS/node-24 jest-worker `SIGSEGV` mitigation switches levers.** A fifth
+  occurrence landed with the 512 MB idle ceiling in force, so per the rule recorded beside it
+  the lever changes rather than the number: `--maxWorkers=1` now caps concurrent worker heaps.
+  A "Runner capacity" step reports cpus/mem on every leg, which established what five previous
+  hit records had assumed — macOS runners have 3 vCPU and 8 GB against 4 vCPU and 17 GB
+  elsewhere, so `--maxWorkers=2` would have been the default spelled out and changed nothing.
+  That leg runs ~4m → 6.5m as a result.
+
 ## [4.9.2] - 2026-08-27
 
 *The instrument existed; nothing could read it.*

package/README.md

@@ -455,7 +455,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.9.2",
+  "version": "4.9.3",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/bin/amicus.js

@@ -16,6 +16,12 @@ if (!_nv.ok) { process.stderr.write(_nv.message + '\n'); process.exit(1); }
 const { loadCredentials } = require('../src/utils/env-loader');
 loadCredentials();
 
+// Diagnostics probe live provider endpoints with those keys. That is allowed
+// HERE and nowhere else: utils/live-probes.js defaults to off, so a module
+// required outside this CLI (a test, a script) can never spend them. A skipped
+// probe is reported as unverified, never as healthy — see live-probes.js.
+require('../src/utils/live-probes').enableLiveProbes();
+
 const { parseArgs, getUsage, getCommandNames } = require('../src/cli');
 const { handleSetup, handleAbort, handleUpdate, handleMcp, handleKey } = require('../src/cli-handlers');
 const { handleStart, handleFanout, handleRead } = require('../src/cli-handlers-run');

package/docs/configuration.md

@@ -49,6 +49,58 @@ for the pre-normalization failure mode and the manual fix if you've disabled the
 
 ---
 
+## Output budget (`outputBudget`)
+
+Each council leg reserves a `max_tokens` allowance before the model runs. Amicus previously handed
+OpenCode no per-model limit at all, so OpenCode's own fixed default — **32,000** — governed every
+leg regardless of the model's real ceiling.
+
+That reservation is not free. OpenRouter validates it against your remaining credit *before* serving,
+so a leg that would have emitted 800 tokens gets refused outright for asking to reserve 32,000:
+
+```
+This request requires more credits, or fewer max_tokens.
+You requested up to 32000 tokens, but can only afford 354
+```
+
+`outputBudget` lowers the reservation. Each model reserves `min(outputBudget, that model's real
+ceiling)`, so a small model keeps its own lower limit rather than being handed an over-ceiling value.
+
+| Setting | Values | Default | Effect |
+|---------|--------|---------|--------|
+| `outputBudget` (config.json, top-level) | positive integer | *unset* | Per-leg output reservation, clamped to each model's real ceiling. Unset means no limit is sent — OpenCode's 32,000 default applies, exactly as before. |
+
+Set it by hand-editing `~/.config/amicus/config.json`:
+
+```json
+{ "outputBudget": 8000 }
+```
+
+Two limits worth knowing before you set it:
+
+- **It can only lower the reservation, never raise it.** OpenCode computes
+  `Math.min(limit.output, 32000)`, so any value at or above 32,000 leaves the reservation itself
+  unchanged. Raising the ceiling past 32,000 needs OpenCode's own
+  `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` environment variable — a different lever that Amicus does
+  not set.
+
+  Setting a value ≥ 32,000 is **not** a complete no-op, though. Amicus still emits the `limit`
+  descriptor, which carries the model's context length alongside the output figure — and OpenCode
+  disables prompt compaction for any model whose context reads as `0`, which is what a model it does
+  not recognise otherwise gets. So a high budget leaves `max_tokens` alone while still restoring
+  compaction for those models. If you want neither effect, leave `outputBudget` unset.
+- **It needs a catalog that knows each model's ceiling.** Run `amicus models --refresh` after setting
+  it. Models whose ceiling is unknown — anything fetched before this field existed, and the direct
+  `openai` / `anthropic` / `google` / `deepseek` lists, which don't publish one — keep the old
+  behaviour rather than receiving a guessed limit.
+
+This addresses reservation *rejections*. It does **not** stop a reasoning-heavy model from spending
+its whole allowance on reasoning and emitting nothing — that is governed by reasoning effort
+(`--thinking`), not by `max_tokens`. Lowering the budget makes such a leg fail faster and cheaper; it
+does not make it produce output.
+
+---
+
 ## Routing
 
 `routing.prefer` in `config.json` sets the global default gateway policy; `--gateway` (CLI) or the

package/docs/usage.md

@@ -538,7 +538,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.9.2",
+  "version": "4.9.3",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
@@ -593,6 +593,7 @@ Runs every check below, in order, and prints a ✓/⚠/✗ line for each plus a
 | `node` | Node.js ≥ 22.12 | error |
 | `config-dir` | The resolved config directory | *(always ok)* |
 | `keys` | At least one cloud-vendor key configured | error |
+| `key-auth` **(#210)** | Every stored key is still accepted by its provider (skipped — reports `ok` — when no keys are stored) | error on a 401/403, warn when the probe can't reach the provider |
 | `default-model` | Your default model alias resolves | error |
 | `catalog` | Model-catalog cache present and within the 24h TTL | warn |
 | `aliases` | Your configured aliases still resolve against the catalog | warn |
@@ -609,6 +610,8 @@ Runs every check below, in order, and prints a ✓/⚠/✗ line for each plus a
 | `local-providers` **(v4.2)** | Every provider in `config.providers` is reachable | warn |
 | `project-root` | Your cwd looks like a real project, not an app/install dir | warn |
 
+**`key-auth`** re-validates stored keys against each provider's own endpoint, because `keys` above tests **presence** only — a key that rots *after* it was entered was previously never re-checked, so `doctor` could report ✓ while a provider returned 401 and the catalog silently served zero rows for it. All stored keys are probed in parallel (sequential 10s timeouts would add up to ~50s to every run). Only a **401/403** is treated as a definitive rejection and fails the check; a timeout, DNS/socket failure, 5xx or unexpected status is reported as `warn` — being offline is not a rotted key, and a false error would send you to re-enter a perfectly good one. Only provider names and a sanitized reason are ever printed; no key material or request URL reaches the output or the `--json` artifact.
+
 **`local-providers`** probes every configured local provider (2s timeout each) the same way `amicus provider test` does, and reports per-id reachability in one line, e.g. `ollama: 3 models @ http://127.0.0.1:11434/v1; my-vllm: unreachable @ http://127.0.0.1:8000/v1`. No providers configured at all is a plain `ok` ("none configured") — this check can never fail your doctor run outright, only warn: a napping `ollama serve` isn't treated as broken setup.
 
 `--fix` self-heals five of the checks above in place: reprovisions Electron, copies the OpenCode engine into a broken npx-cache install, removes a duplicate legacy MCP entry, sweeps orphaned session-index tmp files, and sweeps orphaned per-session metadata tmp files (both tmp sweeps only ones older than 60s). It does **not** start a local server for you — `local-providers` stays a warning until you start the server yourself.

package/electron/main.js

@@ -370,7 +370,19 @@ async function createSetupWindow() {
     }
   });
 
-  const html = buildSetupHTML({ client: CLIENT, quickPicks, shortlists });
+  // issue 213: render Step 3 from the user's EFFECTIVE aliases (defaults merged
+  // with config), not the 21 built-in defaults. Custom aliases used to get no
+  // row at all -- and the config arriving later over IPC could not add one,
+  // since applyAliasEditsToUI only rewrites rows that already exist. Its own
+  // try/catch: an unreadable config must cost the alias list, not the window.
+  let aliases;
+  try {
+    aliases = require('../src/utils/config').getEffectiveAliases();
+  } catch (_err) {
+    aliases = undefined;  // buildSetupHTML falls back to the defaults
+  }
+
+  const html = buildSetupHTML({ client: CLIENT, quickPicks, shortlists, aliases });
   mainWindow.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(html)}`);
   mainWindow.webContents.on('page-title-updated', (e) => e.preventDefault());
 
@@ -569,7 +581,18 @@ function createSettingsChildWindow() {
     }
   });
 
-  const html = buildSetupHTML({ client: CLIENT, quickPicks, shortlists });
+  // issue 213: mirror createSetupWindow -- Step 3 renders the user's EFFECTIVE
+  // aliases, not just the built-in defaults. getEffectiveAliases() reads the
+  // config file synchronously (loadConfig), so this keeps the "Settings must
+  // never trigger a network fetch / stay synchronous" property intact.
+  let aliases;
+  try {
+    aliases = require('../src/utils/config').getEffectiveAliases();
+  } catch (_err) {
+    aliases = undefined;  // buildSetupHTML falls back to the defaults
+  }
+
+  const html = buildSetupHTML({ client: CLIENT, quickPicks, shortlists, aliases });
   settingsWin.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(html)}`);
   settingsWin.webContents.on('page-title-updated', (e) => e.preventDefault());
 }

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

@@ -0,0 +1,161 @@
+/**
+ * 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.
+ *
+ * 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
+ * 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
+ */
+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()));
+}
+
+/**
+ * Heading for the client-side group that holds routes added during THIS
+ * wizard session. Exported so the inline script and the tests name the same
+ * string.
+ *
+ * Wording is deliberately non-committal about filing, but the reason is
+ * narrower than it once was. It used to be that Step 3 was built from
+ * getDefaultAliases(), so a custom alias had no row at all on reopen; that is
+ * fixed — electron/setup-ui.js now renders from the effective aliases, and a
+ * SAVED custom route is vendor-filed on the next open like any other.
+ *
+ * What the label still cannot promise is filing WITHIN this session: the page
+ * derives no vendors (issue 214 keeps routing policy server-side), so a route
+ * added here cannot move into its vendor group until the config round-trips.
+ * "this session" is exactly that scope.
+ */
+const NEW_ROUTES_GROUP_LABEL = 'New routes (this session)';
+
+module.exports = {
+  ALIAS_VENDOR_LABELS,
+  NEW_ROUTES_GROUP_LABEL,
+  aliasVendorOf,
+  vendorLabel,
+  groupAliases,
+};

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

@@ -6,12 +6,21 @@
  * Extracted from setup-ui.js to keep file sizes under 300 lines.
  */
 
+const { NEW_ROUTES_GROUP_LABEL } = require('./setup-ui-alias-groups');
+
 /**
  * Build the alias editor JS for inline inclusion in the wizard script
  * @returns {string} JavaScript source (no <script> tags)
  */
 function buildAliasScript() {
+  // This script runs in the wizard PAGE and cannot require(), so anything it
+  // shares with the Node builders is either serialised in as DATA (the group
+  // heading below) or not shared at all. The vendor grouping rule is the
+  // latter, on purpose: see the SHARED-WITH-THE-BROWSER note in
+  // setup-ui-alias-groups.js and the issue 214 guard in tests/setup-ui.test.js.
   return `
+  var NEW_ROUTES_GROUP_LABEL = ${JSON.stringify(NEW_ROUTES_GROUP_LABEL)};
+
   // Alias editor: search
   var aliasSearchInput = $('alias-search');
   if (aliasSearchInput) {
@@ -86,15 +95,68 @@ function buildAliasScript() {
         }
       });
     }
-    // If current value not in options, add it
+    // issue 211: the current value is echoed back only because NOTHING in the
+    // catalog matched it -- it is not an offer. Rendered bare it read as the
+    // one first-class option Amicus recommends (a delisted id outranking 13
+    // real ones). Same string, honest framing: its own labelled optgroup.
     if (currentValue && !select.querySelector('option[value="' + CSS.escape(currentValue) + '"]')) {
+      var customGroup = document.createElement('optgroup');
+      customGroup.label = 'Current \\u2014 not found in catalog';
       var custom = document.createElement('option');
       custom.value = currentValue; custom.textContent = currentValue; custom.selected = true;
-      select.insertBefore(custom, select.firstChild);
+      customGroup.appendChild(custom);
+      select.insertBefore(customGroup, select.firstChild);
     }
     return select;
   }
 
+  // issue 213: a new custom route used to be appended as an ungrouped sibling
+  // of every <details>, so it rendered below the last group with no heading at
+  // all. It now goes into its own clearly-labelled group. Vendor filing is the
+  // SERVER's job (setup-ui-alias-groups.js) -- deriving a vendor here would
+  // mean shipping gateway-prefix stripping back into the page, which is what
+  // issue 214 removed.
+  function placeRowInNewRoutesGroup(row) {
+    var editor = document.querySelector('.alias-editor');
+    if (!editor) { return; }
+    var group = editor.querySelector('.alias-group[data-new-routes]');
+    if (!group) {
+      group = document.createElement('details');
+      group.className = 'alias-group';
+      group.setAttribute('data-new-routes', '1');
+      var summary = document.createElement('summary');
+      var labelEl = document.createElement('span');
+      labelEl.textContent = NEW_ROUTES_GROUP_LABEL + ' ';
+      var countEl = document.createElement('span');
+      countEl.className = 'alias-count';
+      summary.appendChild(labelEl); summary.appendChild(countEl);
+      group.appendChild(summary);
+      editor.insertBefore(group, $('alias-add-btn'));
+    }
+    group.appendChild(row);
+    group.open = true;
+    refreshAliasCounts();
+  }
+
+  // Server-rendered counts are static; keep them true after add/remove/delete.
+  //
+  // Counts EXCLUDE .alias-deleted (council finding A3, PR 221). Deleting a
+  // server-rendered row marks it rather than removing it, so counting every
+  // .alias-row left the heading claiming rows the user had just struck out.
+  // groupAliases can never EMIT an empty group, but a server group can still be
+  // emptied here by deleting its last row -- it then honestly reads "(0)"
+  // rather than vanishing, because a struck-out row is still on screen and its
+  // deletion is not committed until Finish. Only the client-created new-routes
+  // group is dropped at zero: its rows are removed outright, so zero means gone.
+  function refreshAliasCounts() {
+    document.querySelectorAll('.alias-group').forEach(function(g) {
+      var rows = g.querySelectorAll('.alias-row:not(.alias-deleted)').length;
+      if (rows === 0 && g.hasAttribute('data-new-routes')) { g.remove(); return; }
+      var countEl = g.querySelector('.alias-count');
+      if (countEl) { countEl.textContent = '(' + rows + ')'; }
+    });
+  }
+
   // Alias editor: inline edit
   document.addEventListener('click', function(e) {
     var nameSpan = e.target.closest('.alias-name');
@@ -164,6 +226,10 @@ function buildAliasScript() {
     } else {
       delete aliasEdits[alias];
     }
+    // A3: this handler owns SERVER-rendered rows, whose group heading carries a
+    // count baked in at render time. Without this the heading kept counting a
+    // row the user had just struck out.
+    refreshAliasCounts();
   });
 
   // Alias editor: add custom shortcut
@@ -186,8 +252,7 @@ function buildAliasScript() {
       row.appendChild(arrow);
       row.appendChild(modelSelect);
       row.appendChild(delBtn);
-      var editor = document.querySelector('.alias-editor');
-      if (editor) { editor.insertBefore(row, addBtn); }
+      placeRowInNewRoutesGroup(row);
       nameInput.focus();
       function commitNew() {
         var n = nameInput.value.trim();
@@ -210,6 +275,7 @@ function buildAliasScript() {
         var a = row.getAttribute('data-alias');
         if (a) { delete aliasEdits[a]; }
         row.remove();
+        refreshAliasCounts();
       });
     });
   }`;

package/electron/setup-ui-aliases.js

@@ -5,42 +5,46 @@
  * delete, and add functionality for the setup wizard Step 3.
  */
 
-/** Grouping metadata for the 21 default aliases */
-const ALIAS_GROUPS = [
-  { name: 'Gemini', keys: ['gemini', 'gemini-pro'] },
-  { name: 'GPT', keys: ['gpt', 'gpt-pro', 'codex'] },
-  { name: 'Claude', keys: ['claude', 'sonnet', 'opus', 'haiku', 'fable'] },
-  { name: 'DeepSeek', keys: ['deepseek'] },
-  { name: 'Qwen', keys: ['qwen', 'qwen-coder', 'qwen-flash'] },
-  { name: 'Mistral', keys: ['mistral'] },
-  { name: 'Other', keys: ['glm', 'minimax', 'grok', 'kimi', 'seed', 'inkling'] },
-];
+const { groupAliases } = require('./setup-ui-alias-groups');
+
+/** Attribute/text-safe rendering of user-controlled alias names and routes. */
+function esc(value) {
+  return String(value === undefined || value === null ? '' : value)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
 
 /**
  * Build the HTML fragment for the alias editor section
+ *
+ * Issue 213: groups are derived from each alias's ROUTE VENDOR
+ * (setup-ui-alias-groups.js), not from a hardcoded list of alias names, so
+ * EVERY alias in `aliases` renders exactly once -- the old whitelist silently
+ * dropped any name it did not list (12 of 25 in a real config).
+ *
  * @param {Object<string,string>} aliases - Map of alias name to model string
  * @returns {string} HTML fragment with search, groups, rows, and add button
  */
 function buildAliasEditorHTML(aliases) {
   const searchInput = '<input type="text" id="alias-search" class="alias-search" placeholder="Search aliases..." autocomplete="off" spellcheck="false">';
 
-  const groups = ALIAS_GROUPS.map(group => {
+  const groups = groupAliases(aliases).map(group => {
     const rows = group.keys
-      .filter(key => aliases[key] !== undefined)
       .map(key => {
         const model = aliases[key];
-        return `<div class="alias-row" data-alias="${key}">` +
-          `<span class="alias-name">${key}</span>` +
+        return `<div class="alias-row" data-alias="${esc(key)}">` +
+          `<span class="alias-name">${esc(key)}</span>` +
           '<span class="alias-arrow">\u2192</span>' +
-          `<span class="alias-model">${model}</span>` +
-          `<button class="alias-delete" data-alias="${key}">\u00d7</button>` +
+          `<span class="alias-model">${esc(model)}</span>` +
+          `<button class="alias-delete" data-alias="${esc(key)}">\u00d7</button>` +
           '</div>';
       }).join('\n        ');
 
-    const count = group.keys.filter(key => aliases[key] !== undefined).length;
-
-    return `<details class="alias-group">
-        <summary>${group.name} <span class="alias-count">(${count})</span></summary>
+    // data-vendor records WHICH vendor a group holds, for tests and for anyone
+    // inspecting the page. The client does not read it to place rows -- see the
+    // SHARED-WITH-THE-BROWSER note in setup-ui-alias-groups.js.
+    return `<details class="alias-group" data-vendor="${esc(group.vendor)}">
+        <summary>${esc(group.label)} <span class="alias-count">(${group.keys.length})</span></summary>
         ${rows}
       </details>`;
   }).join('\n      ');
@@ -82,4 +86,4 @@ function buildAliasEditorHTML(aliases) {
     </div>`;
 }
 
-module.exports = { ALIAS_GROUPS, buildAliasEditorHTML };
+module.exports = { buildAliasEditorHTML };

package/electron/setup-ui.js

@@ -22,12 +22,22 @@ const { PROVIDER_FAMILY_NAMES } = require('../src/utils/model-fetcher');
  * @param {Object<string,object>} [options.shortlists] - issue 138: per-alias vendor
  *   shortlist from buildModelShortlist(), passed through to buildModelStepHTML
  *   for the model-level <select>. Defaults to {} (no drill-down rendered).
+ * @param {Object<string,string>} [options.aliases] - issue 213: the alias map Step 3
+ *   renders. Callers pass getEffectiveAliases() (defaults MERGED with the user's
+ *   config); the default here stays getDefaultAliases() so an omitted option is
+ *   the old behaviour exactly. This is the second half of issue 213: fixing
+ *   buildAliasEditorHTML's grouping guarantees "every alias passed in renders
+ *   exactly once", but the app was only ever passing the 21 built-in defaults,
+ *   so a user's custom aliases had no row at all. The config that arrives later
+ *   over IPC cannot repair that -- applyAliasEditsToUI only rewrites the model
+ *   text of rows that ALREADY exist (`if (!row) { return; }`).
  */
 function buildSetupHTML(options = {}) {
   const {
     client = 'code-local',
     quickPicks = resolveQuickPicks([]),          // pinned fallbacks when not provided
     shortlists = {},
+    aliases = getDefaultAliases(),               // issue 213
   } = options;
   // Council A1 (PR 215): a pick reaching the page WITHOUT canonicalRoutes makes
   // pickRouteFor fall back to the raw openrouter/... route, which this codebase
@@ -42,7 +52,7 @@ function buildSetupHTML(options = {}) {
   const brandName = getBrandName(client);
   const keysHtml = buildKeysStepHTML(PROVIDERS);
   const modelHtml = buildModelStepHTML(picks, undefined, undefined, shortlists);
-  const aliasHtml = buildAliasEditorHTML(getDefaultAliases());
+  const aliasHtml = buildAliasEditorHTML(aliases);
   const css = buildWizardCSS();
   const providersJson = JSON.stringify(PROVIDERS);
   const modelChoicesJson = JSON.stringify(picks);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.9.2",
+  "version": "4.9.3",
   "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": [