amicus 4.9.1 → 4.9.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.9.1",
+  "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,145 @@
 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.*
+
+Issue #202 deferred its retry-policy decision to evidence: "v4.9 W13 records per-leg
+time-to-first-token in `runStats`, so the next rev can derive this from observation instead of
+argument." That probe had never reported a value into any artifact CI uploads — `tally.js`'s
+hand-maintained allowlist stripped it one hop before `tally.json`. Reading it changed the
+diagnosis: first tokens on the CI egress are a continuous heavy tail (8.0 s to 384.2 s, no gap),
+not an upstream that accepts and never serves. This release fixes the instrument, then the
+kill switches that were set inside that tail.
+
+### Fixed
+
+- **`ttftMs` survives the runStats re-projection (#202).** `tally.js :: tally` re-projects every
+  row through a hand-maintained allowlist that never named the field, and `verdict.js` copies that
+  array verbatim — so the W13 probe emitted correctly into `tally-input.json` and was destroyed
+  before `tally.json` and `verdict.json`, the only artifacts CI uploads. MEASURED, run
+  33030485388: 11 of 12 rows carried it going in, 0 of 12 coming out. `tally.js` becomes the fifth
+  emit gate and the fourth importer of the shared `isMeasuredTtft` predicate. A drift pin now fails
+  for ANY future `buildRunStatsEntry` key the allowlist is not taught to carry.
+- **A zero-output leg now names its cause (#202).** `getSessionStatus` was called only inside
+  `if (mirror.output.length > 0)` — a gate a leg that produced nothing never satisfies — so the one
+  leg needing diagnosis was the only one that never asked. A bounded, non-throwing read now runs at
+  the two backstop firing sites (a living leg makes no extra call) and appends `busy` /`idle`/
+  `retry` with the upstream message. `busy` means provider-side, `idle` means engine-side, `retry`
+  names the cause; none is suppressed. Untrusted provider text is sanitized.
+- **Dead Stage-2 judge legs are announced (#202).** A dead judge leg still binds to its seat, so it
+  was neither `orphan` nor `unbound` and Stage 2 had no third case: it fell through into
+  `judgeResults` unremarked. Run 32956900910 shipped a four-column adjudication matrix that two of
+  its four judges never voted in, with no degrade recorded. New `stage2-judge` channel.
+- **B53 no longer kills healthy, billing legs.** `TOOL_CALL_STALL_MS` was 180 s, condemned by this
+  repo's own measurement — a real 190.6 s `task` call recorded in `headless.js`, taken on a
+  developer machine. That measurement had corrected its neighbour (the settle deferral) and left
+  its own subject alone. Now 300 s, with CI overriding to 480 s.
+- **The Stage-1 retry backstop no longer ties with the leg timeout.** `min(2 * backstop, legCap)`
+  made the deadlines equal whenever `2 * backstop >= legCap`; the backstop won only by the poll
+  loop's ordering. It now clamps strictly below, so a retry death keeps its named diagnosis
+  instead of degrading to a generic `timeout`.
+
+### Added
+
+- **`verdict.json` publishes `seatsReviewed {reviewed, of}`.** `deriveSeatLoss` returns null when
+  no `--critic` was requested, and CI requests none, so seat loss was structurally absent from
+  every CI verdict while a two-seat bench published a four-model street-cred table. Derived from
+  `runStats`, counting the bench roles `buildSeats` mints (`seat`, `critic`, `lens:<slug>`).
+  Surfaced in the check-run title and the sticky comment footer.
+
+### Changed
+
+- **A dead Stage-2 judge now degrades the run, so it exits 2.** Previously a half-adjudicated
+  verdict could exit 0. This changes CI signal: runs that passed before will now report degraded
+  when a judge dies.
+- **CI council caps.** Per-leg `--timeout` 10 -> 16 min and `timeout-minutes` 45 -> 75, to give the
+  tool-stall detector real reach (120 s -> 480 s of a leg). The job cap covers a worst case of
+  four leg caps; that figure is a floor, since Stage-2 repairs are serial.
+
 ## [4.9.1] - 2026-08-27
 
 *A silent provider failure, and the unservable model ids it produced.*

package/README.md

@@ -455,7 +455,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.9.1",
+  "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.1",
+  "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();
       });
     });
   }`;