amicus 4.9.2 → 4.9.4

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.4",
   "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/schemas/model-catalog.schema.json

@@ -14,6 +14,7 @@
     "count": { "type": "number" },
     "models": { "type": "array", "items": { "type": "object" } },
     "lastRefreshAttempt": { "type": ["number", "null"] },
-    "lastRefreshError": { "type": ["string", "null"] }
+    "lastRefreshError": { "type": ["string", "null"] },
+    "ceilingEnrichment": { "type": ["object", "null"] }
   }
 }

package/schemas/run.schema.json

@@ -24,6 +24,19 @@
     "usage": { "type": ["object", "null"] },
     "pack": { "type": "object" },
     "tag": { "type": "string" },
+    "finish": {
+      "type": "string",
+      "description": "#218 PR 3, optional. The engine's finish reason for the leg's last assistant message ('stop', 'length', 'tool-calls', …), copied verbatim from the assistant message's `finish`. EMIT-WHEN-SET like `ttftMs`: absent means the engine recorded none (the message never finalized, or an older engine). 'length' means the provider stopped at the max_tokens reservation — with answer text that is a cut review (announced as a Note on the `output-truncated` channel); without, the leg is status 'error' with an `OUTPUT_LENGTH:` reason."
+    },
+    "variant": {
+      "type": "string",
+      "description": "#218 PR 4, optional. The effort level amicus SENT as the engine's `variant` prompt field for this leg, after checking the engine's own declaration for the model (/config/providers). EMIT-WHEN-SENT: absent means no --thinking was requested, or the request was refused before anything was sent (then `status` is 'error' and `error` starts VARIANT_UNDECLARED or VARIANT_OVER_BUDGET — prefixed `Session setup failed: ` on an interactive `amicus start`). Not the engine's own `variant` echo, which it records even for a level it dropped (probe F3/M7). A leg whose no-output backstop fired before the prompt send resolved carries no `variant` even though one went out — the send result never arrived, so the record cannot claim it."
+    },
+    "variantUnverified": {
+      "type": "boolean",
+      "enum": [true],
+      "description": "#218 PR 4, optional, emit-when-true. The variant was sent to a model the engine's catalogue did not know within the wait (its row carries none of the cells a catalogue fills — no display name, family, release date, pricing or capabilities — only the descriptor amicus registered: a model newer than the engine's bundled catalogue before its startup refresh landed, or a custom/local model): the engine applied it only if it learned the model before building the request, and dropped it silently otherwise; amicus cannot tell which."
+    },
     "ttftMs": {
       "type": "integer",
       "minimum": 0,

package/skills/sidecar/SKILL.md

@@ -236,14 +236,7 @@ amicus start \
 - `--context-turns <N>`: Max conversation turns to include (default: 50)
 - `--context-since <duration>`: Time filter for context (e.g., `2h`, `30m`, `1d`). Overrides `--context-turns`.
 - `--context-max-tokens <N>`: Max context size (default: 80000)
-- `--thinking <level>`: Model thinking/reasoning effort level:
-  - `none` - No extended thinking
-  - `minimal` - Minimal thinking (may be adjusted if unsupported by model)
-  - `low` - Low thinking effort
-  - `medium` - Medium thinking effort (default)
-  - `high` - High thinking effort
-  - `xhigh` - Extra high thinking effort
-  Note: If the model doesn't support the specified level, it will be automatically adjusted.
+- `--thinking <level>`: Reasoning effort — `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (the levels the curated routes declare between them). Omit it for the provider's own default effort (nothing is sent then). A level the model does not declare is refused before anything is sent (`VARIANT_UNDECLARED`, naming the declared set); a declared level whose thinking budget would push the reservation over `outputBudget` on the direct Anthropic route is refused too (`VARIANT_OVER_BUDGET`); a model the engine's catalogue does not know in time is sent the level unverified (`variantUnverified: true` on the record). Nothing is adjusted.
 - `--summary-length <length>`: Summary verbosity:
   - `brief` - Concise summary
   - `normal` - Standard summary (default)

package/src/cli-handlers-doctor.js

@@ -14,9 +14,12 @@ const electronMcpCheck = require('./utils/doctor-electron-mcp-check');
 const localProvidersCheck = require('./utils/doctor-local-providers-check');
 // v4.6.2 PR1 (spec §4) — the 'anthropic-base-url' check body.
 const baseUrlCheck = require('./utils/doctor-base-url-check');
+const outputBudgetCheck = require('./utils/doctor-output-budget-check'); // #218 PR 2 — the 'output-budget' row.
 // B3 (council review of PR 198, issue 195) — the 'aliases' check body,
 // including its --fix repair of fabricated bare ids. Same split rationale.
 const aliasCheck = require('./utils/doctor-alias-check');
+const creditCheck = require('./utils/doctor-credit-check');
+const keyAuthCheck = require('./utils/doctor-key-auth-check'); // #210 — 'keys' tests presence only; this re-validates.
 
 const { DEFAULT_MAX_AGE_MS: MAX_CATALOG_AGE_MS } = require('./utils/model-catalog'); // 24h — single source
 
@@ -32,7 +35,8 @@ function realDeps() {
     nodeVersion: process.version,
     readApiKeys: () => require('./utils/api-key-store').readApiKeys(),
     readApiKeyValues: () => require('./utils/api-key-store').readApiKeyValues(),
-    checkOpenRouterCredit: (key) => require('./utils/api-key-validation').checkOpenRouterCredit(key),
+    checkOpenRouterCredit: (key) => keyAuthCheck.probeOpenRouterCredit(key), // #210 — same gate as validateApiKey
+    validateApiKey: (p, k) => keyAuthCheck.probeApiKey(p, k), // #210
     getCwd: () => process.cwd(),
     readProjectMarkers: (dir) => {
       const exists = (name) => { try { return fs.existsSync(path.join(dir, name)); } catch (_e) { return false; } };
@@ -42,6 +46,7 @@ function realDeps() {
     resolveModel: () => require('./utils/config').resolveModel(),
     readCache: () => require('./utils/model-catalog').readCache(),
     collectAliasSources: () => require('./utils/alias-audit').collectAliasSources(),
+    readOutputBudgetRaw: () => (require('./utils/config').loadConfig() || {}).outputBudget, // #218 PR 2: as stored, so a malformed value is echoed
     findStaleAliases: (s, c) => require('./utils/alias-audit').findStaleAliases(s, c),
     findDriftedStoredAliases: (s, c) => require('./utils/alias-audit').findDriftedStoredAliases(s, c),
     // B3: the narrow fabricated-bare-id repair class (pure detection) + the
@@ -141,6 +146,7 @@ async function runDoctorChecks(depsOverride = {}) {
       : { id: 'keys', name: 'API keys', status: 'error', message: 'no provider keys configured', hint: 'amicus key <provider> <key>  (or run: amicus setup)' };
   }));
 
+  checks.push(await guardAsync('key-auth', 'API key auth', () => keyAuthCheck.evaluateKeyAuth(d))); // #210
   checks.push((() => {
     try {
       const model = d.resolveModel();
@@ -167,6 +173,7 @@ async function runDoctorChecks(depsOverride = {}) {
   // utils/doctor-alias-check.js for the check body and utils/alias-audit.js's
   // findFabricatedAliasRepairs for the detection rule.
   checks.push(guard('aliases', 'Model aliases', () => aliasCheck.evaluateAliasesCheck(d)));
+  checks.push(guard('output-budget', 'Output budget', () => outputBudgetCheck.evaluateOutputBudget(d))); // #218 PR 2
 
   checks.push(guard('anthropic-base-url', 'ANTHROPIC_BASE_URL',
     () => baseUrlCheck.evaluateAnthropicBaseUrl(d)));
@@ -211,21 +218,10 @@ async function runDoctorChecks(depsOverride = {}) {
 
   checks.push(guard('session-metadata-tmp', 'Session metadata tmp files', () => metaSweep.evaluateSessionMetadataTmpSweep(d)));
 
-  // #43: OpenRouter credit/free-tier — warns (never errors); skipped when no key.
-  checks.push(await guardAsync('openrouter-credit', 'OpenRouter credit', async () => {
-    const values = d.readApiKeyValues() || {};
-    const key = values.openrouter;
-    if (!key) {
-      return { id: 'openrouter-credit', name: 'OpenRouter credit', status: 'ok', message: 'no OpenRouter key — skipped', hint: null };
-    }
-    // Reuses the #38 non-blocking probe; resolves warning:null on any failure.
-    const res = (await d.checkOpenRouterCredit(key)) || {};
-    if (res.warning) {
-      return { id: 'openrouter-credit', name: 'OpenRouter credit', status: 'warn', message: res.warning, hint: 'Add credit at openrouter.ai/credits, or build a free council (amicus setup → option 2).' };
-    }
-    const remaining = (typeof res.limitRemaining === 'number') ? ` ($${res.limitRemaining} remaining)` : '';
-    return { id: 'openrouter-credit', name: 'OpenRouter credit', status: 'ok', message: `credit ok${remaining}`, hint: null };
-  }));
+  // #43: OpenRouter credit/free-tier — warns (never errors); skipped when no
+  // key. Body in utils/doctor-credit-check.js (same split as the others).
+  checks.push(await guardAsync('openrouter-credit', 'OpenRouter credit',
+    () => creditCheck.evaluateOpenRouterCredit(d)));
 
   // v4.2 §4.7 C8: configured local / OpenAI-compatible providers (Ollama, LM
   // Studio, vLLM, generic) — reachability only; warn, never error (a napping

package/src/cli-handlers-fanout.js

@@ -8,7 +8,7 @@
 
 'use strict';
 
-const { validateTaskId, validateTag } = require('./utils/validators');
+const { validateTaskId, validateTag, validateThinkingLevel } = require('./utils/validators');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
 const { GATEWAY_MODES } = require('./utils/model-descriptor');
 const { applyTemplateForArgs } = require('./cli-template-args');
@@ -54,6 +54,15 @@ async function handleFanout(args) {
     process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` }));
   }
 
+  // #218 PR 4 whole-branch review (VCMD-2): the same vocabulary check `start` runs in
+  // validateStartArgs (cli.js) — fanout never did, so a typo (or a pack's) reached sendPrompt:
+  // sent unverified to an unknown model, a per-leg VARIANT_UNDECLARED after the spawn on a
+  // known one. Named mutant "FANOUTTHINKINGUNCHECKED" (tests/fanout-cli.test.js): drop this block.
+  const thinkingCheck = validateThinkingLevel(args.thinking);
+  if (!thinkingCheck.valid) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: thinkingCheck.error }));
+  }
+
   const { resolvePromptSource } = require('./utils/prompt-source');
   let promptRes;
   if (args.prompt !== undefined || args['prompt-file'] !== undefined || args.template === undefined) {

package/src/cli-handlers-resume-continue.js

@@ -32,6 +32,21 @@ async function handleResume(args) {
       message: 'Error: --tag is not supported on resume — the tag is inherited from the parent session',
     }));
   }
+  // #218 PR 4, council #235 r1 (D6): the same silently-ignored-flag shape as --tag
+  // above. `--thinking` parses on every command because getKnownFlags()
+  // (utils/known-flags.js) scrapes the whole usage string and start's block declares
+  // it (cli.js), this handler never reads it, and validateStartArgs — PR 4's
+  // vocabulary check — runs only on `start` (cli-handlers-run.js), so even
+  // `--thinking bogus` used to exit 0 here having done nothing. Before PR 4 the level
+  // reached nothing on any path (probe F1) and the commands behaved alike by accident;
+  // it is the engine's `variant` on start/fanout now. Named mutant
+  // "RESUMETHINKINGSILENT" (tests/cli-handlers-resume-continue.test.js): drop this guard.
+  if (args.thinking !== undefined) {
+    process.exit(failJson(useJson, {
+      code: ERROR_CODES.BAD_ARGS,
+      message: 'Error: --thinking is not supported on resume — the level belongs to the run that started the session, and resume reopens that session',
+    }));
+  }
   const taskId = requireValidTaskId(args, useJson, 'resume', 'Usage: amicus resume <task_id>');
   requireNoUiForJson(args, useJson);
 
@@ -71,6 +86,16 @@ async function handleContinue(args) {
       message: 'Error: --tag is not supported on continue — the tag is inherited from the parent session',
     }));
   }
+  // #218 PR 4, council #235 r1 (D6): same rationale as handleResume above — the flag
+  // parses here, is read by nobody, and is not even vocabulary-checked. A continuation
+  // is a NEW session, so a level for it belongs on the `start` that opens one. Named
+  // mutant "CONTINUETHINKINGSILENT" (tests/cli-handlers-resume-continue.test.js).
+  if (args.thinking !== undefined) {
+    process.exit(failJson(useJson, {
+      code: ERROR_CODES.BAD_ARGS,
+      message: 'Error: --thinking is not supported on continue — the level belongs to the run that starts a session; use `amicus start --thinking <level>` to open one with a level',
+    }));
+  }
   const taskId = requireValidTaskId(args, useJson, 'continue', 'Usage: amicus continue <task_id> --prompt "..."');
 
   // BL-1: accept --prompt-file (XOR --prompt) so the MCP handler can pass a long

package/src/cli-handlers.js

@@ -176,7 +176,23 @@ async function handleKey(args) {
 
   console.log(`Validating ${provider} key...`);
   const validation = await validateApiKey(provider, keyArg);
-  if (!validation.valid) {
+  // 401 is the only status that means "this credential is not accepted".
+  // Everything else — 403 (disabled API, quota, region/bot block), 429, any
+  // 5xx, a 404 from a moved endpoint, a Cloudflare 52x during an origin
+  // outage, or no status at all because the machine is offline — says
+  // something about the REQUEST, not the key. Refusing to save on those is
+  // the false ALARM the doctor classifier stopped raising.
+  //
+  // ⚠️ An ALLOWLIST of what blocks, deliberately. This was a blocklist of
+  // what does NOT block, which left every unenumerated status falling through
+  // to process.exit(1) while the comment above it claimed only 401 blocked —
+  // the code and the narrative disagreed, and the narrative was the nicer of
+  // the two. An allowlist cannot rot as new status codes appear.
+  const BLOCKS_SAVE = new Set([401]);
+  if (!validation.valid && !BLOCKS_SAVE.has(validation.status)) {
+    console.warn(`Warning: ${validation.error}`);
+    console.warn('Saving the key anyway — run `amicus doctor` to re-check it later.');
+  } else if (!validation.valid) {
     console.error(`Error: ${validation.error}`);
     process.exit(1);
   }

package/src/cli.js

@@ -326,16 +326,13 @@ function validateStartArgs(args) {
     return { valid: false, error: `Error: --summary-length must be one of: ${validSummaryLengths.join(', ')}` };
   }
 
-  // Validate thinking effort level (if provided), with model-specific support check
-  const thinkingCheck = validateThinkingLevel(args.thinking, args.model);
+  // Validate the thinking level's VOCABULARY (#218 PR 4). Whether the model
+  // declares it is checked against the engine's own catalogue at send time
+  // (opencode-client.js :: sendPrompt); nothing is adjusted here any more.
+  const thinkingCheck = validateThinkingLevel(args.thinking);
   if (!thinkingCheck.valid) {
     return thinkingCheck;
   }
-  // If model doesn't support the level, adjust it and warn
-  if (thinkingCheck.warning) {
-    logger.warn('Thinking level adjusted', { warning: thinkingCheck.warning, adjustedLevel: thinkingCheck.adjustedLevel });
-    args.thinking = thinkingCheck.adjustedLevel;
-  }
 
   // Validate API key is present for the model's provider
   const apiKeyCheck = validateApiKey(args.model);
@@ -444,7 +441,7 @@ Options for 'start':
   --context-since <duration>   Time filter (e.g., 2h). Overrides turns.
    --context-max-tokens <N>     Max context tokens (default: 80000)
    --summary-length <length>    Summary verbosity: brief, normal (default), verbose
-   --thinking <level>           Reasoning effort: none, minimal, low, medium, high, xhigh
+   --thinking <level>           Reasoning effort: none, minimal, low, medium, high, xhigh, max (omit for the provider's default)
    --mcp <spec>                 Add MCP server. Formats:
                                 - name=url (remote server)
                                 - name=command (local server)