amicus 4.1.2 → 4.2.0

package/src/utils/api-key-store.js

@@ -6,6 +6,12 @@ const fs = require('fs');
 const path = require('path');
 const { validateApiKey, validateOpenRouterKey, VALIDATION_ENDPOINTS } = require('./api-key-validation');
 const { PROVIDER_ENV_MAP } = require('./provider-registry');
+// v4.2 (B2/D3): the .env line-merge logic lives once in env-raw-store.js. saveApiKey/
+// removeApiKey below reuse it via upsertEnvLine/deleteEnvLine; saveRawEnv/removeRawEnv
+// (arbitrary-name local-provider bearer writes) are re-exported so every documented
+// `require('./api-key-store').saveRawEnv` call site keeps working. No load-time cycle:
+// env-raw-store requires THIS module only lazily, inside its functions.
+const { saveRawEnv, removeRawEnv, upsertEnvLine, deleteEnvLine } = require('./env-raw-store');
 
 /** Legacy key names that have been renamed (old -> new) */
 const LEGACY_KEY_NAMES = {
@@ -143,47 +149,10 @@ function saveApiKey(provider, key) {
   if (!envVar) {
     return { success: false, error: `Unknown provider: ${provider}` };
   }
-
-  const envPath = getEnvPath();
-  const envDir = path.dirname(envPath);
-  fs.mkdirSync(envDir, { recursive: true });
-
-  // Read existing .env content, preserving comments and other lines
-  let lines = [];
-  try {
-    if (fs.existsSync(envPath)) {
-      const content = fs.readFileSync(envPath, 'utf-8');
-      lines = content.split('\n');
-    }
-  } catch (_err) {
-    // Start fresh
-  }
-
-  // Find and replace the line for this env var, or append
-  let found = false;
-  for (let i = 0; i < lines.length; i++) {
-    const trimmed = lines[i].trim();
-    if (trimmed.startsWith(envVar + '=')) {
-      lines[i] = `${envVar}=${key}`;
-      found = true;
-      break;
-    }
-  }
-  if (!found) {
-    // Remove trailing empty lines before appending
-    while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
-      lines.pop();
-    }
-    lines.push(`${envVar}=${key}`);
-  }
-
-  // Write with trailing newline
-  const output = lines.join('\n') + '\n';
-  fs.writeFileSync(envPath, output, { mode: 0o600 });
-
+  // Shared merge helper (preserves comments/other lines, dedups, 0600, trailing NL).
+  upsertEnvLine(getEnvPath(), envVar, key);
   // Also set process.env so the key is immediately available
   process.env[envVar] = key;
-
   return { success: true };
 }
 
@@ -194,29 +163,8 @@ function removeApiKey(provider) {
     return { success: false, error: `Unknown provider: ${provider}` };
   }
 
-  const envPath = getEnvPath();
-  try {
-    if (!fs.existsSync(envPath)) {
-      const { checkAuthJson } = require('./auth-json');
-      delete process.env[envVar];
-      return { success: true, alsoInAuthJson: checkAuthJson(provider) };
-    }
-    const content = fs.readFileSync(envPath, 'utf-8');
-    const lines = content.split('\n').filter(line => {
-      return !line.trim().startsWith(envVar + '=');
-    });
-
-    // Remove trailing empty lines
-    while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
-      lines.pop();
-    }
-
-    const output = lines.length > 0 ? lines.join('\n') + '\n' : '';
-    fs.writeFileSync(envPath, output, { mode: 0o600 });
-  } catch (_err) {
-    // Ignore
-  }
-
+  // Shared merge helper (no-op when the file is absent; preserves other lines, 0600).
+  deleteEnvLine(getEnvPath(), envVar);
   delete process.env[envVar];
 
   // Check if key also exists in auth.json (caller decides whether to clean)
@@ -232,6 +180,8 @@ module.exports = {
   readApiKeyValues,
   saveApiKey,
   removeApiKey,
+  saveRawEnv,
+  removeRawEnv,
   validateApiKey,
   validateOpenRouterKey,
   PROVIDER_ENV_MAP,

package/src/utils/claude-register.js

@@ -0,0 +1,267 @@
+/**
+ * @module claude-register
+ * Registration core for amicus: skill install (chat skill + LLM Council),
+ * MCP server registration in Claude Code / Claude Desktop, and legacy MCP
+ * migration. Extracted from scripts/postinstall.js (Task 15, v4.2 §4.8/C2) so
+ * the SAME core can run at `npm install` time (via postinstall.js, now a
+ * thin re-exporting consumer of this module) AND on demand via `amicus init`
+ * (src/cli-handlers-init.js) — e.g. after a failed postinstall, a
+ * plugin-channel / --ignore-scripts install, or to repair deleted ~/.claude
+ * state.
+ *
+ * Behavior is byte-identical to the pre-extraction scripts/postinstall.js,
+ * with one deliberate exception (M18): registerClaudeCode/registerClaudeDesktop
+ * now RETURN their 'added'|'updated'|'unchanged' status instead of computing
+ * it and discarding it, so callers (amicus init) get real per-step status.
+ * scripts/postinstall.js's own callers ignore the return value, so this is
+ * behavior-safe for postinstall's "byte-identical" claim.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+
+// B13: sibling of this file under src/utils/ — was '../src/utils/mcp-self-identity'
+// when this code lived in scripts/postinstall.js.
+const { isAmicusMcpConfig } = require('./mcp-self-identity');
+
+// B13: this file now lives at src/utils/, two levels below the repo root
+// (scripts/ was only one level below) — both source paths need an extra '..'.
+const SKILL_SOURCE = path.join(__dirname, '..', '..', 'skills', 'sidecar', 'SKILL.md');
+const COUNCIL_SOURCE_DIR = path.join(__dirname, '..', '..', 'skills', 'second-opinion');
+
+/** Council files + per-file install semantics: SKILL/COUNCIL-DESIGN/SEAT-BRIEFS are
+ * product code (overwrite on update, so upgrades keep them in sync with the package);
+ * MODEL-NOTES is user data — its reviewer-reliability table evolves per-run, so it is
+ * seeded once and never clobbered. */
+const COUNCIL_FILES = [
+  { file: 'SKILL.md', mode: 'overwrite' },
+  { file: 'COUNCIL-DESIGN.md', mode: 'overwrite' },
+  { file: 'SEAT-BRIEFS.md', mode: 'overwrite' },
+  { file: 'MANUAL-ORCHESTRATION.md', mode: 'overwrite' },
+  { file: 'MODEL-NOTES.md', mode: 'if-missing' },
+];
+
+function skillsRoot() {
+  return path.join(os.homedir(), '.claude', 'skills');
+}
+
+const MCP_CONFIG = { command: 'npx', args: ['-y', 'amicus@latest', 'mcp'] };
+
+/**
+ * Add or update an MCP server in a JSON config file.
+ *
+ * Refreshes command/args on every install/upgrade. If the EXISTING entry at
+ * this key is already amicus-shaped (per isAmicusMcpConfig — Phase 1's single
+ * source of truth for "this is amicus"), we MERGE instead of overwrite: the
+ * user's `env` (and any other extra keys, e.g. a future `cwd`) survive the
+ * refresh. Without this, `npm i -g amicus` silently wiped
+ * "env": {"AMICUS_LEGACY_ALIASES":"1"} — the exact opt-in escape hatch Phase 4
+ * tells users to add — on every upgrade.
+ *
+ * A NON-amicus-shaped entry at this key is overwritten as before: 'amicus' is
+ * a reserved registration name, so a foreign entry there is reclaimed rather
+ * than merged with.
+ *
+ * @param {string} configPath - Path to the JSON config file
+ * @param {string} name - MCP server name
+ * @param {object} config - MCP server config object
+ * @returns {string} 'added', 'updated', or 'unchanged'
+ */
+function addMcpToConfigFile(configPath, name, config) {
+  let existing = {};
+  try {
+    existing = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch {
+    // File doesn't exist or invalid JSON — start fresh
+  }
+
+  if (!existing.mcpServers) { existing.mcpServers = {}; }
+
+  const prev = existing.mcpServers[name];
+  const nextConfig = (prev && isAmicusMcpConfig(prev)) ? { ...prev, ...config } : config;
+  const status = !prev ? 'added' : JSON.stringify(prev) !== JSON.stringify(nextConfig) ? 'updated' : 'unchanged';
+
+  existing.mcpServers[name] = nextConfig;
+  if (status !== 'unchanged') {
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); }
+    fs.writeFileSync(configPath, JSON.stringify(existing, null, 2), { mode: 0o600 });
+  }
+  return status;
+}
+
+/** Install the chat skill to ~/.claude/skills/sidecar/ */
+function installSkill() {
+  try {
+    const destDir = path.join(skillsRoot(), 'sidecar');
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.copyFileSync(SKILL_SOURCE, path.join(destDir, 'SKILL.md'));
+    console.log('[amicus] Chat skill installed to ~/.claude/skills/sidecar/');
+  } catch (err) {
+    console.error(`[amicus] Warning: Could not install chat skill: ${err.message}`);
+  }
+}
+
+/** Install the LLM Council skill to ~/.claude/skills/second-opinion/ */
+function installCouncilSkill(sourceDir = COUNCIL_SOURCE_DIR) {
+  const destDir = path.join(skillsRoot(), 'second-opinion');
+  try {
+    fs.mkdirSync(destDir, { recursive: true });
+  } catch (err) {
+    console.error(`[amicus] Warning: Could not create council skill dir: ${err.message}`);
+    return;
+  }
+  let failed = 0;
+  for (const { file, mode } of COUNCIL_FILES) {
+    try {
+      const dest = path.join(destDir, file);
+      if (mode === 'if-missing' && fs.existsSync(dest)) { continue; }
+      fs.copyFileSync(path.join(sourceDir, file), dest);
+    } catch (err) {
+      failed++;
+      console.error(`[amicus] Warning: Could not install council file ${file}: ${err.message}`);
+    }
+  }
+  if (failed === COUNCIL_FILES.length) {
+    console.error('[amicus] Warning: Council skill NOT installed (all files failed — see warnings above).');
+  } else if (failed > 0) {
+    console.log(`[amicus] Council skill partially installed (${failed}/${COUNCIL_FILES.length} files failed — see warnings above).`);
+  } else {
+    console.log('[amicus] Council skill installed to ~/.claude/skills/second-opinion/');
+  }
+}
+
+/**
+ * Read the previous 'amicus' entry from ~/.claude.json, if any — used by the
+ * CLI add-json path to merge env the same way the file-fallback path does.
+ * Never throws: a missing/unreadable file just means "no previous entry".
+ * @returns {object|undefined}
+ */
+function readPrevClaudeCodeAmicusEntry() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf-8'));
+    return parsed && parsed.mcpServers ? parsed.mcpServers.amicus : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Register MCP server in Claude Code config.
+ * @returns {'added'|'updated'|'unchanged'} the registration status (M18: both
+ *   branches now report a real status instead of discarding it).
+ */
+function registerClaudeCode() {
+  // Try the CLI first
+  try {
+    // Merge the PREVIOUS registration's env into the add-json payload — same
+    // merge semantics as addMcpToConfigFile's file-fallback path (`{ ...prev,
+    // ...config }`: prev env keys survive, canonical MCP_CONFIG keys win on
+    // collision). Without this, a user's custom env (API key, AMICUS_* tuning
+    // knobs) on the old registration was silently dropped whenever the
+    // `claude` CLI was present, because the CLI path built its JSON payload
+    // from the bare MCP_CONFIG and delegated overwrite semantics to the
+    // claude binary — which has no idea about the user's previous entry.
+    const prev = readPrevClaudeCodeAmicusEntry();
+    const nextConfig = (prev && isAmicusMcpConfig(prev)) ? { ...prev, ...MCP_CONFIG } : MCP_CONFIG;
+    // M18: the same status formula addMcpToConfigFile uses, computed from
+    // data already in hand. The `claude` CLI itself reports no status, but we
+    // know exactly what it is about to write (nextConfig) vs what was there
+    // before (prev) — add-json writes to the SAME key the file-fallback path
+    // below would, so this is the truth, not a guess.
+    const status = !prev ? 'added' : JSON.stringify(prev) !== JSON.stringify(nextConfig) ? 'updated' : 'unchanged';
+    const mcpJson = JSON.stringify(nextConfig);
+    execFileSync('claude', ['mcp', 'add-json', 'amicus', mcpJson, '--scope', 'user'], {
+      stdio: 'pipe',
+      timeout: 10000,
+    });
+    console.log('[amicus] MCP registered in Claude Code (via CLI).');
+
+    return status;
+  } catch {
+    // CLI not available or failed — fall back to file edit
+  }
+
+  // Fallback: direct file edit
+  const claudeConfigPath = path.join(os.homedir(), '.claude.json');
+  const status = addMcpToConfigFile(claudeConfigPath, 'amicus', MCP_CONFIG);
+  if (status === 'added') {
+    console.log('[amicus] MCP registered in Claude Code (~/.claude.json).');
+  } else if (status === 'updated') {
+    console.log('[amicus] MCP config updated in Claude Code (~/.claude.json).');
+  } else {
+    console.log('[amicus] MCP already registered in Claude Code.');
+  }
+  return status;
+}
+
+/**
+ * Register MCP server in Claude Desktop / Cowork config.
+ * @returns {'added'|'updated'|'unchanged'} the registration status (M18: was
+ *   computed and used for the console.log branch below, then discarded).
+ */
+function registerClaudeDesktop() {
+  let configDir;
+  if (process.platform === 'darwin') {
+    configDir = path.join(os.homedir(), 'Library', 'Application Support', 'Claude');
+  } else if (process.platform === 'win32') {
+    configDir = path.join(process.env.APPDATA || '', 'Claude');
+  } else {
+    configDir = path.join(os.homedir(), '.config', 'claude');
+  }
+
+  const configPath = path.join(configDir, 'claude_desktop_config.json');
+  const status = addMcpToConfigFile(configPath, 'amicus', MCP_CONFIG);
+  if (status === 'added') {
+    console.log('[amicus] MCP registered in Claude Desktop.');
+  } else if (status === 'updated') {
+    console.log('[amicus] MCP config updated in Claude Desktop.');
+  } else {
+    console.log('[amicus] MCP already registered in Claude Desktop.');
+  }
+  return status;
+}
+
+/**
+ * One-shot migration: drop the duplicate legacy 'sidecar' MCP entry that
+ * pre-1.8 postinstalls registered alongside 'amicus' (same server twice —
+ * doubled the client-visible tool list). Only removes an entry whose command
+ * is an amicus MCP invocation; a customized 'sidecar' entry is left alone.
+ * Covers both files the three legacy registration paths wrote to:
+ * ~/.claude.json (CLI + file fallback) and claude_desktop_config.json.
+ * Never throws (postinstall must always exit 0).
+ */
+function migrateLegacyMcp(deps = {}) {
+  try {
+    // B13: sibling of this file under src/utils/ — was
+    // '../src/utils/legacy-mcp-migration' when this lived in scripts/postinstall.js.
+    const impl = deps.migrateLegacySidecar
+      || require('./legacy-mcp-migration').migrateLegacySidecar;
+    for (const r of impl()) {
+      if (r.result === 'removed') {
+        console.log(`[amicus] Removed duplicate legacy 'sidecar' MCP entry from ${r.target} (same server — kept as 'amicus').`);
+      } else if (r.result === 'customized') {
+        console.log(`[amicus] Kept custom 'sidecar' MCP entry in ${r.target} (does not point at amicus).`);
+      } else if (r.result === 'write-failed') {
+        console.warn(`[amicus] Warning: could not remove the legacy 'sidecar' MCP entry from ${r.target} — run: amicus doctor --fix`);
+      }
+    }
+  } catch (err) {
+    console.warn(`[amicus] Warning: legacy MCP cleanup skipped: ${err && err.message}`);
+  }
+}
+
+module.exports = {
+  MCP_CONFIG,
+  addMcpToConfigFile,
+  installSkill,
+  installCouncilSkill,
+  readPrevClaudeCodeAmicusEntry,
+  registerClaudeCode,
+  registerClaudeDesktop,
+  migrateLegacyMcp,
+  COUNCIL_FILES,
+};

package/src/utils/config.js

@@ -240,6 +240,17 @@ function tryResolveModel(modelArg) {
   }
 }
 
+/**
+ * Request timeout (ms) for local (@ai-sdk/openai-compatible) provider blocks.
+ * opencode's default HTTP request timeout is too short for cold local
+ * inference: prefilling a large agent prompt (~26k tokens) on a cold local
+ * model can exceed it, killing the request during prefill before any stream
+ * data arrives -- opencode never creates the assistant message, and the
+ * caller polls out its own much longer timeout waiting for a response that
+ * will never come. 300000ms (5 minutes) covers cold-start prefill headroom.
+ */
+const LOCAL_REQUEST_TIMEOUT_MS = 300000;
+
 /** Build OpenCode provider.models config from sidecar aliases, plus the
  * actually-resolved launch route(s). The alias-derived entries let the UI
  * model picker show every configured model (single source of truth for the
@@ -289,7 +300,16 @@ function buildProviderModels(resolvedRoutes = []) {
     const providerID = parts[0];
     const modelID = parts.slice(1).join('/');
 
-    if (!providers[providerID]) {
+    // providerID is an unvalidated vendor segment split off a user-supplied
+    // model string (alias or resolved route). A bare `!providers[providerID]`
+    // check walks the prototype chain, so a vendor literally named
+    // 'constructor' (a valid, non-reserved local-provider id — see
+    // local-providers.js's ID_RE/RESERVED_IDS) reads the inherited
+    // Object.prototype.constructor (truthy), skips the init below, and the
+    // next line throws on the resulting undefined. Same bug class already
+    // fixed in gateway-router.js (19aade4) and local-providers.js +
+    // route-suggestions.js (2cba73b).
+    if (!Object.prototype.hasOwnProperty.call(providers, providerID)) {
       providers[providerID] = { models: {} };
     }
     providers[providerID].models[modelID] = {};
@@ -324,6 +344,31 @@ function buildProviderModels(resolvedRoutes = []) {
     addRoute(resolved);
   }
 
+  // v4.2 §4.3: for every provider id that is a configured LOCAL provider AND was
+  // registered by the loops above, attach the OpenCode openai-compatible block.
+  // {env:VAR} interpolation keeps key material out of the config object.
+  const { getLocalProviders } = require('./local-providers');
+  const localAll = getLocalProviders();
+  for (const [id, block] of Object.entries(providers)) {
+    // Guarded the same way as the accumulator init above: `localAll` is a
+    // plain {} when no local providers are configured, so a bare
+    // `localAll[id]` for id === 'constructor' would read the inherited
+    // Object.prototype.constructor (truthy) and fabricate a fake local block
+    // for a vendor that isn't actually configured as local.
+    const entry = Object.prototype.hasOwnProperty.call(localAll, id) ? localAll[id] : undefined;
+    if (!entry) { continue; }
+    block.npm = '@ai-sdk/openai-compatible';
+    block.name = entry.name || id;
+    block.options = {
+      baseURL: entry.baseURL,
+      // @ai-sdk/openai-compatible wants a non-empty apiKey string even for
+      // servers that don't require auth (Ollama/LM Studio/llama.cpp ignore
+      // it) -- an omitted apiKey is not the same as an accepted empty one.
+      apiKey: entry.apiKeyEnv ? `{env:${entry.apiKeyEnv}}` : 'not-needed',
+      timeout: LOCAL_REQUEST_TIMEOUT_MS,
+    };
+  }
+
   return providers;
 }
 
@@ -383,11 +428,18 @@ function resolveCouncilMembers(name, catalog = []) {
   }
   const aliases = getEffectiveAliases();
   const known = new Set((Array.isArray(catalog) ? catalog : []).map(m => m && m.id).filter(Boolean));
+  const { isLocalProvider } = require('./local-providers');
   const models = [];
   const dropped = [];
   for (const member of members) {
     const id = member.includes('/') ? member : aliases[member];
     if (!id) { dropped.push(member); continue; }                 // alias no longer resolves
+    const vendor = typeof id === 'string' ? id.split('/')[0] : '';
+    // v4.2 §4.4: a local server may simply have been off at the last catalog
+    // refresh — that is "unknown", not "delisted". Never drop a local-vendor
+    // member on catalog absence; the leg itself fails pre-flight with the
+    // actionable local_endpoint_unreachable error if the server is truly down.
+    if (isLocalProvider(vendor)) { models.push(member); continue; }
     if (known.size > 0 && !known.has(id)) { dropped.push(member); continue; } // delisted model
     models.push(member);
   }

package/src/utils/doctor-local-providers-check.js

@@ -0,0 +1,62 @@
+/**
+ * @module doctor-local-providers-check
+ * The `local-providers` doctor check (v4.2 §4.7 C8), split out of
+ * src/cli-handlers-doctor.js to keep that file under the 300-line size gate
+ * (mirrors doctor-mcp-checks.js / doctor-engine-check.js).
+ *
+ * Reachability is WARN-never-ERROR (parity with the electron and
+ * openrouter-credit checks): a configured-but-unreachable local server (e.g.
+ * `ollama serve` simply not running) is informational, not a doctor failure
+ * that flips `amicus doctor`'s exit code. No configured local providers at
+ * all is a plain 'ok' ("none configured"), never a warning.
+ *
+ * Each configured provider is probed once, bounded by probeLocalProvider's
+ * own timeout (2s here) -- doctor never introduces an unbounded wait, no
+ * matter how many local providers are configured.
+ */
+
+'use strict';
+
+/**
+ * @param {{getLocalProviders: () => Object<string, {id:string, baseURL:string, flavor?:string, apiKeyEnv?:string}>, probeLocalProvider: (entry:object, opts:{timeoutMs:number, bearer?:string}) => Promise<{status:'ok'|'unreachable', models:string[]}>}} d
+ * @returns {Promise<{id:string, name:string, status:string, message:string, hint:?string}>}
+ */
+async function evaluateLocalProviders(d) {
+  const id = 'local-providers';
+  const name = 'Local providers';
+  const map = d.getLocalProviders();
+  // Object.keys (never `for..in` / `map.hasOwnProperty`) -- local-providers.js
+  // stamps entries on via a plain `out[id] = ...` assignment, so a provider id
+  // like 'constructor' is a real OWN property that shadows the inherited one;
+  // Object.keys + bracket access below resolves it correctly either way.
+  const ids = Object.keys(map);
+  if (ids.length === 0) {
+    return { id, name, status: 'ok', message: 'none configured', hint: null };
+  }
+
+  const parts = [];
+  let anyDown = false;
+  for (const providerId of ids) {
+    const entry = map[providerId];
+    const bearer = entry.apiKeyEnv ? process.env[entry.apiKeyEnv] : undefined;
+    const probe = await d.probeLocalProvider(entry, { timeoutMs: 2000, bearer });
+    if (probe.status === 'ok') {
+      parts.push(`${providerId}: ${probe.models.length} models @ ${entry.baseURL}`);
+    } else {
+      anyDown = true;
+      parts.push(`${providerId}: unreachable @ ${entry.baseURL}`);
+    }
+  }
+
+  // WARN, never ERROR (parity with electron/openrouter-credit -- a napping
+  // local server must not fail CI).
+  const flavorHint = ids.map((i) => map[i].flavor).find((f) => f === 'lmstudio')
+    ? 'Start the LM Studio server (Developer → Start Server), or `ollama serve`.'
+    : 'Start the local server, e.g. `ollama serve`.';
+
+  return anyDown
+    ? { id, name, status: 'warn', message: parts.join('; '), hint: flavorHint }
+    : { id, name, status: 'ok', message: parts.join('; '), hint: null };
+}
+
+module.exports = { evaluateLocalProviders };

package/src/utils/doctor-summary.js

@@ -0,0 +1,33 @@
+/**
+ * @module doctor-summary
+ * Compact doctor summary (v4.2 §4.7 C8). All-ok -> one line; otherwise the
+ * non-ok lines + counts + a pointer to the full command. Shared by the setup
+ * wizard finale (src/sidecar/setup.js) and, next, `amicus init` (Task 15) --
+ * kept in its own leaf module (rather than inside cli-handlers-doctor.js) so
+ * both callers can require it without pulling in the doctor check machinery,
+ * and so cli-handlers-doctor.js stays under the 300-line size gate.
+ */
+
+'use strict';
+
+/**
+ * @param {Array<{status:string,name?:string,id?:string,message?:string}>} checks
+ * @returns {string}
+ */
+function summarizeDoctor(checks) {
+  const list = Array.isArray(checks) ? checks : [];
+  const nonOk = list.filter((c) => c && c.status !== 'ok');
+  if (nonOk.length === 0) {
+    return `doctor: all ${list.length} checks pass`;
+  }
+  const errors = nonOk.filter((c) => c.status === 'error').length;
+  const warns = nonOk.filter((c) => c.status === 'warn').length;
+  const lines = nonOk.map((c) => {
+    const marker = c.status === 'error' ? '✗' : '⚠';
+    return `  ${marker} ${c.name || c.id}: ${c.message || ''}`.trimEnd();
+  });
+  lines.push(`${errors} error(s), ${warns} warning(s) — run \`amicus doctor\` for details`);
+  return lines.join('\n');
+}
+
+module.exports = { summarizeDoctor };

package/src/utils/env-loader.js

@@ -48,6 +48,19 @@ function loadCredentials() {
       logger.info(`Loaded ${envVar} from auth.json`);
     }
   }
+
+  // v4.2: project each configured local-provider apiKeyEnv from amicus .env into
+  // process.env (same never-overwrite rule) so the engine's {env:VAR} finds it.
+  try {
+    const { getLocalProviders } = require('./local-providers');
+    const fileEntries = loadEnvEntries();
+    for (const entry of Object.values(getLocalProviders())) {
+      if (entry.apiKeyEnv && !process.env[entry.apiKeyEnv]) {
+        const v = fileEntries.get(entry.apiKeyEnv);
+        if (v && v.length > 0) { process.env[entry.apiKeyEnv] = v; logger.info(`Loaded ${entry.apiKeyEnv} from amicus .env`); }
+      }
+    }
+  } catch (_err) { /* best-effort: a bad providers block must never break credential load */ }
 }
 
 module.exports = { loadCredentials };