amicus 4.1.1 → 4.2.0

package/src/cli-handlers-provider.js

@@ -0,0 +1,212 @@
+/**
+ * `amicus provider add|list|test|remove` (v4.2 §4.6): configure local /
+ * OpenAI-compatible providers (Ollama, LM Studio, vLLM, any OpenAI-compatible
+ * endpoint). Writes config.providers, stores bearer secrets in the 0600 .env
+ * (never in config), probes the endpoint, and runs the shared per-provider
+ * default picker on a reachable server. DI-injected (print/emitJson/warn/probe/
+ * readCache/runDefault) so it is unit-testable without a TTY or a live server;
+ * `--json` is fully non-interactive.
+ */
+'use strict';
+
+const {
+  PRESETS, RESERVED_IDS, ID_RE, validateProviderEntry, deriveKeyEnv, getLocalProviders,
+} = require('./utils/local-providers');
+
+function realDeps() {
+  return {
+    loadConfig: () => require('./utils/config').loadConfig(),
+    saveConfig: (c) => require('./utils/config').saveConfig(c),
+    // Bearer persistence: saveRawEnv writes an arbitrary env-var NAME to the 0600
+    // .env (re-exported from api-key-store). Named per the Task 10 DI contract.
+    saveApiKey: (env, val) => require('./utils/api-key-store').saveRawEnv(env, val),
+    // Bearer cleanup (post-Task-11-review flow-gap fix): removeRawEnv deletes an
+    // arbitrary env-var NAME line from the same .env. Named to mirror saveApiKey.
+    removeApiKey: (env) => require('./utils/api-key-store').removeRawEnv(env),
+    probe: (e, o) => require('./utils/local-probe').probeLocalProvider(e, o),
+    readCache: () => require('./utils/model-catalog').readCache(),
+    runDefault: (id, o) => require('./utils/provider-default-prompt').runProviderDefaultFlow(id, o),
+    print: (l) => process.stdout.write(`${l}\n`),
+    emitJson: (o) => process.stdout.write(`${JSON.stringify(o, null, 2)}\n`),
+    warn: (l) => process.stderr.write(`${l}\n`),
+  };
+}
+
+/** Exact-hostname loopback test (substring matching would pass 127.0.0.1.evil.com). */
+function isLoopbackUrl(baseURL) {
+  try {
+    return ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(new URL(baseURL).hostname);
+  } catch { return false; }
+}
+
+/** A bearer here would traverse the network in cleartext (plain http, non-loopback). */
+function isPlaintextRemote(baseURL) {
+  try { return new URL(baseURL).protocol === 'http:' && !isLoopbackUrl(baseURL); }
+  catch { return false; }
+}
+
+/** Build the entry from --preset or --url (+ optional bearer/pricing). */
+function entryFromArgs(id, args) {
+  // hasOwnProperty guard: args.preset is user input; a bare PRESETS[args.preset]
+  // for 'constructor' would walk the prototype chain (the recurring v4.2 bug class).
+  const preset = (args.preset && Object.prototype.hasOwnProperty.call(PRESETS, args.preset))
+    ? PRESETS[args.preset] : null;
+  const baseURL = args.url || (preset && preset.baseURL);
+  const flavor = (preset && preset.flavor) || 'generic';
+  // D15/M13: every PRESETS entry carries a baseURL, so this fires only when NEITHER
+  // flag was given, or when --preset named something unknown — distinguish the two.
+  if (!baseURL) {
+    return { error: args.preset && !preset
+      ? `unknown --preset '${args.preset}' (expected: ${Object.keys(PRESETS).join('|')})`
+      : 'a --preset or --url is required' };
+  }
+  const entry = { type: 'openai-compatible', baseURL, flavor };
+  if (args['pricing-in'] !== undefined || args['pricing-out'] !== undefined) {
+    entry.pricing = { prompt: Number(args['pricing-in']) || 0, completion: Number(args['pricing-out']) || 0 };
+  }
+  if (args['bearer-env']) { entry.apiKeyEnv = args['bearer-env']; }
+  else if (args.bearer) { entry.apiKeyEnv = deriveKeyEnv(id); }
+  return { entry, bearerValue: args.bearer };
+}
+
+/** Warn when the cached catalog already carries an `openrouter/<id>/` namespace (decision 5). */
+function shadowsGatewayNamespace(cache, id) {
+  return !!(cache && Array.isArray(cache.models) && cache.models.some(
+    (m) => m && typeof m.id === 'string' && m.id.startsWith(`openrouter/${id}/`)));
+}
+
+async function doAdd(id, args, d) {
+  // D7: the CLI owns id validation (validateProviderEntry is id-agnostic).
+  if (!ID_RE.test(id || '') || RESERVED_IDS.includes(id)) {
+    d.warn(`Invalid or reserved provider id: '${id}'.`); return 1;
+  }
+  const built = entryFromArgs(id, args);
+  if (built.error) { d.warn(built.error); return 1; }
+  const v = validateProviderEntry(built.entry); // enforces the http/https scheme allowlist
+  if (!v.ok) { d.warn(v.error); return 1; }
+  // Security (spec §4.10): a bearer over plain http to a non-loopback host is cleartext.
+  if (built.bearerValue && isPlaintextRemote(built.entry.baseURL)) {
+    d.warn('Warning: sending a bearer token over plain http:// to a non-loopback host transmits it in cleartext.');
+  }
+  if (shadowsGatewayNamespace(d.readCache(), id)) {
+    d.warn(`Note: '${id}' shadows an OpenRouter vendor namespace for bare model ids. ` +
+      `Use openrouter/${id}/... to reach OpenRouter.`);
+  }
+  // Persist the bearer FIRST so a rejected env-var name aborts before we write config.
+  // M12: saveRawEnv returns {success:false,error} WITHOUT throwing — mirror the
+  // direct-vendor path (cli-handlers.js:156) and bail before saveConfig.
+  if (built.entry.apiKeyEnv && built.bearerValue) {
+    const saved = d.saveApiKey(built.entry.apiKeyEnv, built.bearerValue);
+    if (saved && saved.success === false) { d.warn(saved.error); return 1; }
+  }
+  const config = d.loadConfig() || {};
+  config.providers = config.providers || {};
+  config.providers[id] = v.normalized;
+  // B7/D4: do NOT seed config.default here. A bare id is unresolvable by resolveModel
+  // unless config.aliases[id] exists, and only applyProviderDefault (via d.runDefault,
+  // on a successful probe) writes that pair (alias first, then default). Seeding it
+  // before the probe permanently breaks every later keyless start/fanout/continue.
+  d.saveConfig(config);
+  // Probe (best-effort; a failure never blocks the save — air-gap rule).
+  const probe = await d.probe({ ...v.normalized, id }, { timeoutMs: 2000, bearer: built.bearerValue });
+  if (probe.status === 'ok') {
+    d.print(`Added '${id}' — ${probe.models.length} model(s) found.`);
+    try {
+      const catalog = probe.models.map((mid) => ({ id: mid, pricing: v.normalized.pricing, local: true }));
+      const { summaryLine } = await d.runDefault(id, { interactive: false, catalog });
+      if (summaryLine) { d.print(summaryLine); }
+    } catch { /* picker is best-effort; a bug here must never fail an already-saved add */ }
+  } else {
+    d.warn(`Added '${id}' but the endpoint was unreachable — check the server and run \`amicus provider test ${id}\`.`);
+  }
+  if (args.json) { d.emitJson({ ok: true, id, reachable: probe.status === 'ok', models: probe.models }); }
+  return 0;
+}
+
+async function doTest(id, args, d) {
+  const map = getLocalProviders();
+  // hasOwnProperty guard (trap #6): map[id] for id==='constructor' is a proto walk.
+  if (!id || !Object.prototype.hasOwnProperty.call(map, id)) { d.warn(`No local provider '${id}'.`); return 1; }
+  const entry = map[id];
+  const bearer = entry.apiKeyEnv ? process.env[entry.apiKeyEnv] : undefined;
+  const probe = await d.probe(entry, { timeoutMs: 2000, bearer });
+  const ok = probe.status === 'ok';
+  // Never surface the Authorization header / token — only the boolean presence.
+  if (args.json) { d.emitJson({ ok, id, reachable: ok, models: probe.models, bearer: !!bearer }); }
+  else { d.print(ok ? `${id}: ${probe.models.length} model(s) @ ${entry.baseURL}` : `${id}: unreachable @ ${entry.baseURL}`); }
+  return ok ? 0 : 1;
+}
+
+function doList(args, d) {
+  const providers = Object.values(getLocalProviders()).map(
+    (e) => ({ id: e.id, baseURL: e.baseURL, flavor: e.flavor, bearer: !!e.apiKeyEnv }));
+  if (args.json) { d.emitJson({ providers }); }
+  else if (providers.length === 0) { d.print('No local providers configured. Add one: amicus provider add ollama --preset ollama'); }
+  else { for (const p of providers) { d.print(`${p.id}  ${p.baseURL}  [${p.flavor}]${p.bearer ? '  (bearer)' : ''}`); } }
+  return 0;
+}
+
+function doRemove(id, args, d) {
+  const config = d.loadConfig() || {};
+  const providers = config.providers || {};
+  // hasOwnProperty guards (trap #6): providers[id]/aliases[id] proto walks for 'constructor'.
+  if (!id || !Object.prototype.hasOwnProperty.call(providers, id)) { d.warn(`No local provider '${id}'.`); return 1; }
+  const entry = providers[id];
+  delete providers[id];
+  if (config.default === id) { delete config.default; }
+  if (config.aliases && Object.prototype.hasOwnProperty.call(config.aliases, id)) { delete config.aliases[id]; }
+  d.saveConfig(config);
+
+  // Flow-gap fix (post-Task-11-review): the old hint ("remove it with `amicus key
+  // <id> --remove`") pointed at a command that fails the instant the config entry
+  // above is gone -- isLocalProvider/getLocalProviders derive local-id status from
+  // config.providers on every call. Remove the bearer ourselves instead, UNLESS a
+  // sibling id still shares this apiKeyEnv via --bearer-env, in which case deleting
+  // the line would break that sibling. Iterate remaining OWN keys only (trap #6).
+  let bearerRemoved = false;
+  let sharedWith = null;
+  if (entry.apiKeyEnv) {
+    sharedWith = Object.keys(providers).find((otherId) => {
+      const other = providers[otherId];
+      return other && other.apiKeyEnv === entry.apiKeyEnv;
+    }) || null;
+    if (!sharedWith) {
+      d.removeApiKey(entry.apiKeyEnv);
+      bearerRemoved = true;
+    }
+  }
+
+  if (args.json) {
+    d.emitJson({ ok: true, removed: id, bearerRemoved });
+  } else if (bearerRemoved) {
+    d.print(`Removed '${id}' and its bearer '${entry.apiKeyEnv}'.`);
+  } else if (sharedWith) {
+    d.print(`Removed '${id}'. Kept '${entry.apiKeyEnv}' in .env — still used by provider '${sharedWith}'.`);
+  } else {
+    d.print(`Removed '${id}'.`);
+  }
+  return 0;
+}
+
+/**
+ * @param {object} args parsed CLI args (args._ = ['provider', <sub>, <id?>])
+ * @param {object} [deps] DI overrides (print/emitJson/warn/probe/readCache/...)
+ * @returns {Promise<number>} exit code
+ */
+async function handleProvider(args, deps = {}) {
+  const d = { ...realDeps(), ...deps };
+  const sub = args._[1];
+  const id = args._[2];
+  if (sub === 'add') { return doAdd(id, args, d); }
+  if (sub === 'test') { return doTest(id, args, d); }
+  if (sub === 'list') { return doList(args, d); }
+  if (sub === 'remove') { return doRemove(id, args, d); }
+  d.warn('Usage: amicus provider add|list|test|remove [--json]');
+  return 1;
+}
+
+// isLoopbackUrl/isPlaintextRemote are also reused by cli-handlers-key-local.js's
+// handleLocalKey (B2, whole-branch review) so the `amicus key <localId> <token>`
+// surface warns about cleartext bearer transmission with the SAME exact-hostname
+// check `provider add` uses here, instead of growing a second, divergent check.
+module.exports = { handleProvider, isLoopbackUrl, isPlaintextRemote };

package/src/cli-handlers.js

@@ -10,6 +10,9 @@
 // handleAbort moved to src/cli-handlers-abort.js (B21-rest: --json branch
 // needed headroom this file didn't have). Re-exported below for compatibility.
 const { handleAbort } = require('./cli-handlers-abort');
+// handleKey's local-provider branch (v4.2 Task 11) lives in its own module for
+// the same reason — this file had no headroom left for the new bearer flow.
+const { handleLocalKey, formatLocalKeyList } = require('./cli-handlers-key-local');
 
 /**
  * Handle 'amicus setup' command
@@ -100,10 +103,15 @@ async function handleMcp() {
 /**
  * Handle 'amicus key' command
  * Lists, saves, or removes API keys for a provider without opening the Electron wizard.
+ * Local (openai-compatible) providers are config-defined (local-providers.js)
+ * rather than in PROVIDER_ENV_MAP, so they're handled by handleLocalKey — a
+ * bearer probe/store flow, not the VALIDATION_ENDPOINTS ping the 5 direct
+ * vendors use.
  */
 async function handleKey(args) {
-  const { readApiKeys, readApiKeyHints, saveApiKey, removeApiKey, PROVIDER_ENV_MAP } = require('./utils/api-key-store');
+  const { readApiKeys, readApiKeyHints, saveApiKey, removeApiKey, loadEnvEntries, PROVIDER_ENV_MAP } = require('./utils/api-key-store');
   const { validateApiKey } = require('./utils/api-key-validation');
+  const { getLocalProviders } = require('./utils/local-providers');
 
   const provider = args._[1];
   const keyArg = args._[2];
@@ -119,12 +127,32 @@ async function handleKey(args) {
       const status = configured[p] ? `✓  ${hints[p]}` : '✗  not set';
       console.log(`  ${p.padEnd(12)} ${status}`);
     }
+    const localProviders = getLocalProviders();
+    if (Object.keys(localProviders).length > 0) {
+      for (const line of formatLocalKeyList(localProviders, loadEnvEntries())) { console.log(line); }
+    }
     console.log('');
     return;
   }
 
-  // Validate provider
-  if (!PROVIDER_ENV_MAP[provider]) {
+  // Local providers (Ollama/LM Studio/vLLM/any OpenAI-compatible endpoint) are
+  // config-defined, not in PROVIDER_ENV_MAP — branch BEFORE the direct-vendor
+  // check below. hasOwnProperty guard (recurring v4.2 bug class): a provider
+  // literally named 'constructor' is a valid, non-reserved id (ID_RE/
+  // RESERVED_IDS in local-providers.js) and must resolve to its real entry,
+  // not the inherited Object.prototype.constructor.
+  const localProviders = getLocalProviders();
+  if (Object.prototype.hasOwnProperty.call(localProviders, provider)) {
+    return handleLocalKey(localProviders[provider], provider, args);
+  }
+
+  // Validate provider. hasOwnProperty guard (same prototype-chain bug class the
+  // local-provider branch above guards against): a bare PROVIDER_ENV_MAP[provider]
+  // for provider === 'constructor' reads the inherited Object.prototype.constructor
+  // (the Object function — truthy), which would wrongly treat an UNCONFIGURED
+  // 'constructor' as a known direct vendor and crash later in validateApiKey
+  // instead of reporting Unknown provider (caught by this task's own test suite).
+  if (!Object.prototype.hasOwnProperty.call(PROVIDER_ENV_MAP, provider)) {
     console.error(`Error: Unknown provider "${provider}". Known providers: ${Object.keys(PROVIDER_ENV_MAP).join(', ')}`);
     process.exit(1);
   }

package/src/cli.js

@@ -141,6 +141,8 @@ function isBooleanFlag(key) {
      'fix',                  // doctor: self-heal fixable checks in place (#56)
      'strict',               // models --check: exit non-zero on curated per-gateway drift (#gwid Task 6)
      'render',               // council verdict: also refresh report.html next to the decided verdict
+     'claude',               // init: register for Claude Code only (Task 15)
+     'desktop',              // init: register for Claude Desktop only (Task 15)
    ];
   return booleanFlags.includes(key);
 }
@@ -375,8 +377,10 @@ Commands:
     <provider> <apikey>      Validate and save a key
     <provider> --remove      Remove a saved key
     (no args)                List all configured providers
+  provider    Add/list/test/remove local OpenAI-compatible providers (--json)
   update      Update to latest version
   mcp         Start MCP server (stdio transport)
+  init        Re-run skill install + MCP registration on demand [--claude] [--desktop] [--json]
 `;
 
 // Per-command option blocks, keyed by the invoked subcommand. Insertion order
@@ -555,10 +559,27 @@ Usage for 'key':
   key <provider> <apikey>      Validate and save a key
   key <provider> --remove      Remove a saved key
   key                          List all configured providers
+`,
+  provider: `
+Options for 'provider':
+  provider add <id> --preset ollama|lmstudio|vllm   Add a local server from a preset
+  provider add <id> --url <baseURL> [--bearer-env VAR | --bearer <token>]
+                    [--pricing-in <$/tok> --pricing-out <$/tok>]
+  provider list | test <id> | remove <id>           Manage local providers (all support --json)
+  Local providers run at $0 through Ollama / LM Studio / vLLM / any OpenAI-compatible endpoint.
 `,
   mcp: `
 Usage for 'mcp':
   mcp                          Start the MCP server (stdio transport)
+`,
+  init: `
+Options for 'init':
+  --claude                     Register for Claude Code only (skip Claude Desktop)
+  --desktop                    Register for Claude Desktop only (skip Claude Code)
+  --json                       Emit per-step status as JSON
+  Runs skill install + MCP registration on demand (for plugin-channel /
+  --ignore-scripts installs, a failed postinstall, or repairing deleted
+  ~/.claude state). No flags registers both Claude Code and Claude Desktop.
 `
 };
 

package/src/sidecar/setup-local.js

@@ -0,0 +1,75 @@
+/**
+ * The readline setup wizard's local / self-hosted provider add step (v4.2 §4.6, Task 12).
+ *
+ * Split out of setup.js per RULING D14: setup.js is 516 lines and sits on
+ * check-file-sizes.js's exclude list (grandfathered — the gate can never flag
+ * further growth there), so this extraction is unconditional, not gated on a
+ * line-count check.
+ *
+ * Collects an id + preset (or a custom base URL) and delegates EVERY write to
+ * handleProvider(['provider', 'add', id], deps) (RULING D7), so the wizard and
+ * `amicus provider add` cannot drift apart: id-format + RESERVED_IDS
+ * validation, the plaintext-bearer warning, the shadow-namespace warning, the
+ * 2s reachability probe, and the shared per-provider default picker all come
+ * from that single path. handleProvider's own probe-success branch calls
+ * runProviderDefaultFlow non-interactively (no extra readline prompts here)
+ * and, per D4, remains the sole writer of config.default — this module never
+ * seeds it directly.
+ *
+ * Transport-agnostic by injection (mirrors provider-default-prompt.js): `ask`
+ * and `print` are passed in by the caller rather than imported, because
+ * setup.js defines neither as a bare identifier (B8) — its real idiom is the
+ * module-level `askQuestion(rl, prompt)` plus bare `console.log`. Taking them
+ * as parameters keeps this module callable without a TTY.
+ *
+ * Guarded end-to-end (house best-effort rule, mirrors provisionElectron /
+ * maybeMigrationNotice): any failure — a rejected probe, a validation error,
+ * a thrown handleProvider — is swallowed here. This optional wizard step must
+ * never abort the rest of `amicus setup`.
+ */
+
+'use strict';
+
+const { PRESETS } = require('../utils/local-providers');
+
+/**
+ * @param {(question: string) => Promise<string>} ask reads one line of input
+ * @param {(line: string) => void} print writes one line of output
+ * @param {object} [deps] forwarded verbatim to handleProvider (tests inject
+ *   `probe`/`loadConfig`/`saveConfig`/etc.; production passes {} so
+ *   handleProvider's own realDeps() perform the real I/O)
+ * @returns {Promise<void>}
+ */
+async function addLocalProviderInteractive(ask, print, deps = {}) {
+  try {
+    const id = (await ask('Provider id (e.g. lmstudio, ollama, mylab): ')).trim();
+    if (!id) { return; }
+
+    const presetKey = (await ask('Preset? [ollama / lmstudio / vllm / none]: ')).trim().toLowerCase();
+    const args = { _: ['provider', 'add', id] };
+    // hasOwnProperty guard (trap #6/#8): a bare PRESETS[presetKey] for
+    // presetKey === 'constructor' would read the inherited
+    // Object.prototype.constructor (truthy) and wrongly skip the URL prompt
+    // below — the same recurring v4.2 bug class already guarded in
+    // cli-handlers-provider.js's entryFromArgs and local-providers.js.
+    if (Object.prototype.hasOwnProperty.call(PRESETS, presetKey)) {
+      args.preset = presetKey;
+    } else {
+      // D15: every preset already carries a baseURL, so a URL prompt is only
+      // needed for 'none' / a blank / an unrecognized preset name.
+      args.url = (await ask('Base URL (e.g. http://127.0.0.1:11434/v1): ')).trim();
+    }
+
+    // D7: one call performs id/format validation + save + probe + the shared
+    // default picker, and prints its own "Added '<id>' — N model(s) found."
+    // / unreachable message through the injected print/warn — both point at
+    // the same callback so nothing silently goes to realDeps' stderr instead
+    // of the wizard's own output stream.
+    const { handleProvider } = require('../cli-handlers-provider');
+    await handleProvider(args, { print, warn: print, ...deps });
+  } catch (_err) {
+    // Best-effort: a bug in this optional wizard step must never abort setup.
+  }
+}
+
+module.exports = { addLocalProviderInteractive };

package/src/sidecar/setup.js

@@ -144,6 +144,20 @@ async function launchWizard() {
   return launchSetupWindow();
 }
 
+/**
+ * Local / self-hosted provider add step for the readline wizard (v4.2 §4.6,
+ * Task 12). Thin re-export -- RULING D14 keeps the real implementation out of
+ * this file (516 lines, grandfathered on check-file-sizes.js's exclude list).
+ * Owning module: ./setup-local.
+ * @param {(question: string) => Promise<string>} ask
+ * @param {(line: string) => void} print
+ * @param {object} [deps]
+ * @returns {Promise<void>}
+ */
+function addLocalProviderInteractive(ask, print, deps) {
+  return require('./setup-local').addLocalProviderInteractive(ask, print, deps);
+}
+
 /**
  * Standalone API key setup — launches the Electron window directly
  * Used by `sidecar setup --api-keys`
@@ -191,6 +205,11 @@ async function seedCatalog(print) {
  *   (`runReadlineSetup` already fetches one for the per-provider phase) --
  *   reused as-is to avoid a second `getCatalog()` round trip. Falls back to
  *   fetching its own when omitted (e.g. direct unit-test callers).
+ * @returns {Promise<boolean>} true when the branch actually seeded a council
+ *   (a completed setup -- the caller then prints the C8 doctor finale, Finding
+ *   2 post-review); false when it aborted early (no OPENROUTER_API_KEY, or
+ *   fewer than 2 models picked) -- parity with the invalid-choice branch,
+ *   which also configured nothing and so also gets no finale.
  */
 async function runFreeCouncilBranch(rl, catalogArg) {
   const keys = detectApiKeys();
@@ -198,7 +217,7 @@ async function runFreeCouncilBranch(rl, catalogArg) {
     console.log('');
     console.log('A free council needs OPENROUTER_API_KEY (free models route only through OpenRouter).');
     console.log('Set OPENROUTER_API_KEY and re-run: amicus setup. No changes made.');
-    return;
+    return false;
   }
   const { listFreeModels, suggestFreeCouncil, PINNED_FREE_MODELS } = require('../utils/free-models');
   let catalog = [];
@@ -232,7 +251,7 @@ async function runFreeCouncilBranch(rl, catalogArg) {
   }
   if (pickIds.length < 2) {
     console.log('A council needs at least 2 models. No changes made.');
-    return;
+    return false;
   }
   const { council } = seedFreeCouncil(pickIds);
   await seedCatalog();
@@ -243,6 +262,7 @@ async function runFreeCouncilBranch(rl, catalogArg) {
   console.log('');
   console.log('Heads up (free tier): rate-limited & quality-variable; some models 404');
   console.log('unless you enable data-sharing at openrouter.ai/settings/privacy.');
+  return true;
 }
 
 /**
@@ -293,6 +313,35 @@ async function runProviderDefaultPickers(rl, foundKeys, catalog) {
   return written;
 }
 
+/**
+ * C8 (v4.2 §4.7) -- print the compact doctor summary at the wizard's finale.
+ * Shared by runReadlineSetup and the Electron-success path of
+ * runInteractiveSetup. Best-effort / guarded: a doctor bug (or a check that
+ * throws) must never abort setup or change its outcome -- setup has already
+ * done its job by the time this runs, so a failure here is swallowed.
+ *
+ * Injectable (post-review hardening, M14-class fix): `deps.runDoctorChecks`
+ * lets tests replace the real doctor directly instead of relying on jest's
+ * module-mock resolution coincidentally intercepting this function's own
+ * lazy require (see tests/sidecar/setup.test.js's `cli-handlers-doctor`
+ * mock, added for exactly this reason). Every production call site
+ * (runReadlineSetup / runInteractiveSetup) calls this with no args, so the
+ * default -- the real, network-probing runDoctorChecks -- is always what
+ * actually ships.
+ * @param {{runDoctorChecks?: () => Promise<Array<object>>}} [deps]
+ */
+async function printDoctorFinale(deps = {}) {
+  try {
+    const runDoctorChecks = deps.runDoctorChecks || require('../cli-handlers-doctor').runDoctorChecks;
+    const { summarizeDoctor } = require('../utils/doctor-summary');
+    const checks = await runDoctorChecks();
+    console.log('');
+    console.log(summarizeDoctor(checks));
+  } catch (err) {
+    logger.debug('Doctor finale skipped', { error: err.message });
+  }
+}
+
 /**
  * Run the readline-based setup wizard (headless fallback)
  *
@@ -302,6 +351,7 @@ async function runProviderDefaultPickers(rl, foundKeys, catalog) {
  * 3. Mode selection (standard or free council)
  * 4. Default model selection from live quick-picks (read-modify-write, no clobber)
  * 5. Config file save
+ * 6. C8: a compact `amicus doctor` summary, best-effort
  */
 async function runReadlineSetup() {
   const rl = readline.createInterface({
@@ -328,6 +378,17 @@ async function runReadlineSetup() {
       console.log('Set OPENROUTER_API_KEY to get started, or run: amicus setup');
       console.log(`Not sure what's wrong? ${runDoctor}`);
     }
+    // Local / self-hosted providers (v4.2 §4.6) already configured (e.g. via a
+    // prior `amicus provider add`) are listed alongside detected keys. Guarded:
+    // getLocalProviders() is documented never-fatal, but a listing step must
+    // not be able to block setup even if that contract is ever violated.
+    try {
+      const { getLocalProviders } = require('../utils/local-providers');
+      const localIds = Object.keys(getLocalProviders());
+      if (localIds.length > 0) {
+        console.log(`Local providers configured: ${localIds.join(', ')}`);
+      }
+    } catch (_err) { /* best-effort: never block setup over this listing */ }
     console.log('');
 
     // #38 — non-blocking zero-credit / free-tier OpenRouter warning. Never
@@ -346,15 +407,38 @@ async function runReadlineSetup() {
     // it never clobbers a vendor alias this phase just wrote (Fix 2).
     const vendorAliasesWritten = await runProviderDefaultPickers(rl, foundKeys, catalog);
 
+    // Task 12 (v4.2 §4.6): offer to add a local / self-hosted server. Pinned
+    // insertion point -- after the per-provider pickers, before the mode
+    // prompt, so all provider configuration stays grouped ahead of the
+    // standard/free-council branch. Guarded (house best-effort rule, mirrors
+    // provisionElectron/maybeMigrationNotice): addLocalProviderInteractive
+    // already swallows its own errors, but this optional step must not be
+    // able to abort the wizard even if that inner guard is ever weakened.
+    try {
+      const wantLocal = await askQuestion(rl,
+        'Add a local / self-hosted server (Ollama, LM Studio, vLLM)? (y/N): ');
+      if (wantLocal.toLowerCase() === 'y' || wantLocal.toLowerCase() === 'yes') {
+        await addLocalProviderInteractive((q) => askQuestion(rl, q), console.log, {});
+      }
+    } catch (err) {
+      logger.debug('Local-provider wizard step skipped', { error: err.message });
+    }
+
     const mode = await askQuestion(rl,
       'Setup mode — 1) Standard (pick a default model)  2) Free OpenRouter council: ');
     if (mode === '2') {
-      await runFreeCouncilBranch(rl, catalog);
+      const completed = await runFreeCouncilBranch(rl, catalog);
+      if (completed) {
+        // C8 (Finding 2, post-review): parity with the standard path below --
+        // a completed free-council setup gets the doctor finale too. An
+        // aborted attempt (no key / <2 picks) configured nothing, so -- like
+        // the invalid-choice branch just below -- it gets none.
+        await printDoctorFinale();
+      }
       return;
     }
 
-    const { resolveQuickPicks, toLiveSeedAliases } = require('../utils/quick-picks');
-    const { toCanonicalDefault } = require('../utils/curated-models');
+    const { resolveQuickPicks, toLiveSeedAliases, toStorableRoute } = require('../utils/quick-picks');
     const picks = resolveQuickPicks(catalog);
 
     console.log('Choose your default model:');
@@ -386,7 +470,7 @@ async function runReadlineSetup() {
       // choice), but the alias's VALUE must stay the vendor phase's tier choice --
       // skip the curated-flagship upgrade so it isn't discarded.
       if (pick && !chosen.noUpgrade && !vendorAliasesWritten.has(chosen.alias)) {
-        cfg.aliases[chosen.alias] = toCanonicalDefault(pick.routes.openrouter || Object.values(pick.routes)[0]);
+        cfg.aliases[chosen.alias] = toStorableRoute(pick);
       } else if (cfg.aliases[chosen.alias] === undefined) {
         const fallback = getDefaultAliases()[chosen.alias];
         if (fallback !== undefined) { cfg.aliases[chosen.alias] = fallback; }
@@ -401,6 +485,9 @@ async function runReadlineSetup() {
     console.log(`Default model set to: ${cfg.default}`);
     console.log(`Config saved (${Object.keys(cfg.aliases).length} aliases).`);
     console.log(`Config path: ${path.join(getConfigDir(), 'config.json')}`);
+
+    // C8: compact doctor summary, best-effort (see printDoctorFinale).
+    await printDoctorFinale();
   } finally {
     rl.close();
   }
@@ -439,6 +526,13 @@ async function runInteractiveSetup() {
       if (keyLabel) { console.log(keyLabel); }
       if (modelLabel) { console.log(modelLabel); }
       console.log(`Config: ${configPath}`);
+
+      // C8: compact doctor summary, best-effort (see printDoctorFinale).
+      // runReadlineSetup prints its own further down -- only the Electron
+      // success path needs it added here explicitly; the fallback below
+      // delegates to runReadlineSetup and inherits its finale, so adding it
+      // here too would double-print.
+      await printDoctorFinale();
       return;
     }
   } catch (err) {
@@ -504,6 +598,7 @@ function seedFreeCouncil(pickIds) {
 
 module.exports = {
   addAlias,
+  addLocalProviderInteractive,
   createDefaultConfig,
   deriveFreeAlias,
   detectApiKeys,