copperhead 0.8.0 → 0.9.0

package/src/commands/create.ts

@@ -1,13 +1,13 @@
 import path from 'node:path';
 import { existsSync } from 'node:fs';
-import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { readFile, mkdir, writeFile, readdir } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
-import { loadConfig } from '../config.js';
+import { loadConfig, resolveCompatSettings } from '../config.js';
 import { bootstrapKicadProject } from '../kicad/bootstrap.js';
 import { exportSvg, runErc } from '../kicad/cli.js';
 import { listSymbols } from '../kicad/sexp.js';
 import { isDirty, commitAll, changedFiles } from '../util/git.js';
-import type { CopperheadConfig } from '../config.js';
+import type { CompatSettings, CopperheadConfig } from '../config.js';
 import { checkDrift } from '../memory/drift.js';
 import { runAgentLoop, makeProvider, type BudgetExhaustedStats } from '../agent/loop.js';
 import { diagnoseStageFailure, transcriptExcerpt, withTimeout, type StageDiagnosis } from '../agent/recovery.js';
@@ -55,22 +55,98 @@ async function docHasHeading(repoRoot: string, rel: string, word: string): Promi
   return re.test(await readFile(p, 'utf8'));
 }
 
+/**
+ * Returns true when a directory exists and contains at least one file
+ * matching the optional glob-style extension list (case-insensitive).
+ * No extension list = any file.
+ */
+async function dirHasFiles(dirPath: string, exts?: string[]): Promise<boolean> {
+  if (!existsSync(dirPath)) return false;
+  async function walk(dir: string): Promise<boolean> {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (await walk(path.join(dir, entry.name))) return true;
+      } else if (!exts || exts.some((e) => entry.name.toLowerCase().endsWith(e))) {
+        return true;
+      }
+    }
+    return false;
+  }
+  return walk(dirPath);
+}
+
 export const STAGES: Stage[] = [
   {
     name: 'spec-seed',
-    isComplete: (root, docs) => docHasHeading(root, path.join(docs, 'SPEC.md'), 'Budgets?'),
+    isComplete: async (root, docs) => {
+      // The init scaffold writes SPEC.md with a "## Budgets" heading and an
+      // HTML comment placeholder — that alone must not count as complete.
+      // Require the heading AND at least one non-comment, non-blank line
+      // of real budget content beneath it (a filled section vs. an empty placeholder).
+      const p = path.join(root, docs, 'SPEC.md');
+      if (!existsSync(p)) return false;
+      const text = await readFile(p, 'utf8');
+      const budgetsMatch = /^#{1,6}\s.*\bBudgets?\b/im.test(text);
+      if (!budgetsMatch) return false;
+      // Find the Budgets section and strip HTML comments (single or multi-line)
+      const afterBudgets = text.split(/^#{1,6}\s.*\bBudgets?\b/im)[1] ?? '';
+      const firstNewline = afterBudgets.indexOf('\n');
+      const afterHeadingLine = firstNewline >= 0 ? afterBudgets.slice(firstNewline + 1) : '';
+      const nextSection = afterHeadingLine.search(/^#{1,6}\s/m);
+      const section = nextSection >= 0 ? afterHeadingLine.slice(0, nextSection) : afterHeadingLine;
+      const cleanSection = section.replace(/<!--[\s\S]*?-->/g, '');
+      const realLines = cleanSection.split('\n').filter((l) => l.trim().length > 0);
+      return realLines.length > 0;
+    },
     prompt: (brief) =>
       `Stage 1 of the create pipeline: seed the requirements. From the product brief below, write docs/SPEC.md (what the device is, top-level constraints and budgets). Every budget you state must also be recorded with record_constraint. Anything the brief does not state: propose a sensible default and flag it ASSUMED. If an openspec/ workspace exists, also seed openspec/specs/ with per-capability requirements using Given/When/Then scenarios.\n\nBrief:\n${brief}`,
   },
   {
     name: 'architecture',
-    isComplete: (root, docs) => docExists(root, path.join(docs, 'SUBSYSTEMS.md')),
+    isComplete: async (root, docs) => {
+      // init scaffolds SUBSYSTEMS.md with boilerplate description text and auto-generated
+      // "## Sheet X" headings containing "- Ref: Value" symbol bullets.
+      // Require at least one level-2+ heading (## section) AND at least one real prose
+      // line beneath it (excluding boilerplate and auto-generated symbol bullets).
+      const p = path.join(root, docs, 'SUBSYSTEMS.md');
+      if (!existsSync(p)) return false;
+      const text = await readFile(p, 'utf8');
+      // Must have at least one level-2+ (##) section heading
+      if (!/^#{2,6}\s/m.test(text)) return false;
+      // Filter out headings, scaffold description, and auto-generated symbol bullets (- Ref: Value or - Ref?: Value)
+      const contentLines = text.split('\n').filter((l) => {
+        const trimmed = l.trim();
+        if (!trimmed || trimmed.startsWith('#')) return false;
+        if (trimmed.includes('Per-sheet values and reasoning')) return false;
+        if (/^-\s+(?:[A-Za-z]+\d+[A-Za-z]*|[A-Za-z]*\?):/.test(trimmed)) return false; // auto-generated refdes symbol bullet (e.g. - R1: 10k, - U?: ESP32, - ?: 10k)
+        return true;
+      });
+      return contentLines.length > 0;
+    },
     prompt: () =>
       'Stage 2: architecture. Write docs/SUBSYSTEMS.md: the block diagram in prose, one section per subsystem (power, MCU, connectivity, UI, ...), with the reasoning and key values for each. Respect every budget in SPEC.md.',
   },
   {
     name: 'part-selection',
-    isComplete: (root, docs) => docExists(root, path.join(docs, 'BOM.md')),
+    isComplete: async (root, docs) => {
+      // init scaffolds BOM.md with a table pre-filled with UNVERIFIED MPNs
+      // extracted from the schematic. Require at least one row whose MPN
+      // column is NOT the UNVERIFIED placeholder — i.e. a real part was chosen.
+      const p = path.join(root, docs, 'BOM.md');
+      if (!existsSync(p)) return false;
+      const text = await readFile(p, 'utf8');
+      // Find table rows (lines starting with |) that are not the header or separator
+      const rows = text.split('\n').filter(
+        (l) => l.startsWith('|') && !l.includes('---') && !l.toLowerCase().includes('refdes'),
+      );
+      if (!rows.length) return false;
+      // At least one row must have a non-UNVERIFIED MPN (4th column)
+      return rows.some((row) => {
+        const cols = row.split('|').map((c) => c.trim());
+        const mpn = cols[4] ?? ''; // 0=empty, 1=Refdes, 2=Value, 3=Footprint, 4=MPN
+        return mpn && !mpn.toUpperCase().startsWith('UNVERIFIED');
+      });
+    },
     prompt: () =>
       'Stage 3: part selection. Write docs/BOM.md with the fixed table format (| Refdes | Value | Footprint | MPN | Rationale |). Every MPN you introduce is flagged UNVERIFIED with a datasheet-verifiable justification. Check leakage/quiescent current of every part against the power budget. Run check_drift before finishing.',
   },
@@ -122,19 +198,37 @@ export const STAGES: Stage[] = [
   },
   {
     name: 'outputs',
-    isComplete: (root) => existsSync(path.join(root, 'outputs')),
+    isComplete: async (root) => {
+      // An empty outputs/ dir (e.g. from a failed export run) must not count
+      // as complete. Require at least one Gerber file (any .gbr variant).
+      return dirHasFiles(path.join(root, 'outputs'), ['.gbr', '.gtl', '.gbl', '.gbs', '.gbo', '.gbp', '.gbd', '.gto', '.gts', '.gml']);
+    },
     prompt: () =>
       'Stage 6: outputs package. Export into outputs/: gerbers+drill (JLC profile), DXF and STEP outline, SVG renders (export_svg), and an ordering BOM.csv generated from BOM.md (refdes, MPN, qty). Every export must succeed.',
   },
   {
     name: 'firmware',
-    isComplete: (root) => existsSync(path.join(root, 'firmware')),
+    isComplete: async (root) => {
+      // An empty firmware/ dir must not count. Require at least one source file.
+      return dirHasFiles(path.join(root, 'firmware'), ['.c', '.h', '.cpp', '.hpp', '.py', '.rs', '.ino', '.s']);
+    },
     prompt: () =>
       'Stage 7: firmware scaffold. Generate firmware/ for the chosen MCU HAL: pins.h generated from PINOUT.md (single source of truth), driver stubs, and one working happy path. If the vendor toolchain is available, the build must pass; if not, note "not compiled here" explicitly in DEVPLAN.md.',
   },
   {
     name: 'devplan',
-    isComplete: (root, docs) => docExists(root, path.join(docs, 'DEVPLAN.md')),
+    isComplete: async (root, docs) => {
+      // init does NOT scaffold DEVPLAN.md, but a blank file must not count.
+      // Require at least one ## section heading AND at least one content line.
+      const p = path.join(root, docs, 'DEVPLAN.md');
+      if (!existsSync(p)) return false;
+      const text = await readFile(p, 'utf8');
+      if (!/^#{1,6}\s/m.test(text)) return false;
+      const contentLines = text.split('\n').filter(
+        (l) => l.trim() && !l.trim().startsWith('#'),
+      );
+      return contentLines.length > 0;
+    },
     prompt: () =>
       'Stage 8: DEVPLAN.md. Write docs/DEVPLAN.md: bring-up steps in order, test points and what to meter first, risk list, and the prototype order plan.',
   },
@@ -284,10 +378,12 @@ async function diagnose(input: {
   transcriptDir: string;
   attempt: number;
   maxAttempts: number;
+  /** Compatible-endpoint settings, so a `compat` run can diagnose itself. */
+  compat?: CompatSettings | undefined;
 }): Promise<StageDiagnosis> {
   let provider: Provider | undefined;
   try {
-    provider = await makeProvider(input.model);
+    provider = await makeProvider(input.model, false, input.compat);
     const p = provider;
     const excerpt = await transcriptExcerpt(input.transcriptDir);
     return await withTimeout(
@@ -685,6 +781,7 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
       const diagnosis = await diagnose({
         model: opts.model,
         timeoutMs: config.turnTimeoutMs,
+        compat: resolveCompatSettings(config),
         stageName: stage.name,
         stageGoal: basePrompt,
         failure,

package/src/commands/doctor.ts

@@ -2,7 +2,16 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { DEFAULTS, loadConfig, resolveModel, type CopperheadConfig } from '../config.js';
+import {
+  DEFAULTS,
+  DEFAULT_API_KEY_ENV,
+  isLocalEndpoint,
+  loadConfig,
+  resolveCompatSettings,
+  resolveModel,
+  type CompatSettings,
+  type CopperheadConfig,
+} from '../config.js';
 import { kicadCliVersion } from '../kicad/cli.js';
 import { redactSecrets } from '../util/redact.js';
 
@@ -15,7 +24,7 @@ const execFileP = promisify(execFile);
  * at the model provider). Each probe fails soft: a missing tool is a reported
  * `fail`, never a thrown error, so `doctor` still prints the rest of the report.
  */
-export type DoctorStatus = 'ok' | 'fail' | 'info';
+export type DoctorStatus = 'ok' | 'fail' | 'warn' | 'info';
 
 export interface DoctorCheck {
   name: string;
@@ -97,7 +106,139 @@ async function gitCheck(probe: () => Promise<string>): Promise<DoctorCheck> {
  * Saved-login providers (codex, claude-code) need no key and can't be verified
  * offline, so they report `info` (which does not block `ok`).
  */
-export function checkCredential(model: string, env: NodeJS.ProcessEnv): DoctorCheck {
+export function checkCredential(
+  model: string,
+  env: NodeJS.ProcessEnv,
+  compat?: CompatSettings | undefined,
+): DoctorCheck {
+  // OpenAI-compatible endpoint: the credential lives in a variable the user
+  // names, and the endpoint is worth showing because it is the whole point of
+  // the route. A loopback endpoint (Ollama) needs no key at all (design D4).
+  if (model === 'compat' || model.startsWith('compat:')) {
+    const shownModel = redactSecrets(model);
+    const compatModel = model.startsWith('compat:') ? model.slice('compat:'.length) : undefined;
+    // Mirrors makeProvider (agent/loop.ts): bare `compat` has no valid default
+    // model, so it must fail here too, or doctor reports "ready" for a run
+    // that would fail on its very first turn.
+    if (!compatModel) {
+      return {
+        name: 'provider',
+        status: 'fail',
+        detail: `${shownModel} -> compat: ${model === 'compat:' ? 'empty' : 'missing'} model id`,
+        hint: 'use "compat:<model-id>"; a compatible endpoint has no default model to assume.',
+      };
+    }
+    const settings = compat ?? { apiKeyEnv: DEFAULT_API_KEY_ENV };
+    // Display only: some endpoints embed a credential in the URL itself (a
+    // query param, userinfo) — Gemini's compat endpoint does this with
+    // ?key=..., in a format redactSecrets' key-shape patterns don't cover.
+    // Drop the query and userinfo entirely rather than pattern-matching, so
+    // this holds regardless of what a given provider's key looks like.
+    // isLocalEndpoint() below still runs against the raw settings.baseURL,
+    // never this.
+    const where = (() => {
+      if (!settings.baseURL) return '(no baseURL configured)';
+      try {
+        const u = new URL(settings.baseURL);
+        return `${u.origin}${u.pathname}`;
+      } catch {
+        return redactSecrets(settings.baseURL);
+      }
+    })();
+    if (!settings.baseURL) {
+      return {
+        name: 'provider',
+        status: 'fail',
+        detail: `${shownModel} -> compat: no endpoint configured`,
+        hint: 'set COPPERHEAD_BASE_URL, or "baseURL" in .copperhead/config.json.',
+      };
+    }
+    if (isLocalEndpoint(settings.baseURL)) {
+      return {
+        name: 'provider',
+        status: 'ok',
+        detail: `${shownModel} -> compat: ${where} (local endpoint, no key required)`,
+      };
+    }
+    return env[settings.apiKeyEnv]
+      ? { name: 'provider', status: 'ok', detail: `${shownModel} -> compat: ${where} (${settings.apiKeyEnv} set)` }
+      : {
+          name: 'provider',
+          status: 'fail',
+          detail: `${shownModel} -> compat: ${where} (${settings.apiKeyEnv} not set)`,
+          hint: `export ${settings.apiKeyEnv}=... for that endpoint.`,
+        };
+  }
+  return checkKeyedCredential(model, env);
+}
+
+/**
+ * Hosts whose free tier may train on submitted prompts. Keyed on hostname
+ * rather than model name: hostnames are stable, model and tier names rot in
+ * months, so the tier detail belongs in docs (design D5). Never `fail` — a
+ * contributor deliberately using a free tier on a non-proprietary board is not
+ * misconfigured, so this must not make `doctor` exit non-zero.
+ */
+const TRAINING_RISK_HOSTS: Record<string, string> = {
+  'generativelanguage.googleapis.com': "Gemini's free tier may train on submitted prompts",
+  'openrouter.ai': 'OpenRouter `:free` models may route to providers that train on prompts',
+};
+
+/**
+ * True loopback only — unlike `isLocalEndpoint` (config.ts), this excludes
+ * `.local`/mDNS hostnames. `isLocalEndpoint`'s broader definition is correct
+ * for "does this need a credential" (many LAN-hosted servers skip auth), but
+ * wrong for the privacy bypass below: a request to `nas.local` genuinely
+ * leaves the machine onto the LAN to a different physical device, so "nothing
+ * leaves the machine" does not hold the way it does for real loopback.
+ */
+function isLoopbackHost(baseURL: string): boolean {
+  try {
+    const h = new URL(baseURL).hostname.toLowerCase();
+    return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h === '[::1]';
+  } catch {
+    return false;
+  }
+}
+
+/** A `warn` line when the configured endpoint's host is a documented training risk. */
+export function checkPromptPrivacy(model: string, compat?: CompatSettings | undefined): DoctorCheck | null {
+  if (model !== 'compat' && !model.startsWith('compat:')) return null;
+  if (!compat?.baseURL) return null;
+  // A true loopback endpoint has no third party to have a policy about:
+  // nothing leaves the machine, so "check the provider's terms" would be
+  // nonsensical. A LAN host (including .local) does not get this bypass.
+  if (isLoopbackHost(compat.baseURL)) return null;
+  let host: string;
+  try {
+    host = new URL(compat.baseURL).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+  const noPolicyOnRecord = (): DoctorCheck => ({
+    name: 'privacy',
+    status: 'info',
+    detail: `${host}: no known training-on-prompts policy on record (copperhead cannot verify this; check the provider's terms)`,
+  });
+  const risk = Object.entries(TRAINING_RISK_HOSTS).find(([h]) => host === h || host.endsWith(`.${h}`));
+  if (!risk) return noPolicyOnRecord();
+  // OpenRouter's documented risk is specific to its `:free`-suffixed models
+  // (their own wording), not the host as a whole. Warning on a fully paid
+  // OpenRouter model would be a false positive that undermines trust in the
+  // other, host-wide warnings (Gemini's applies to its whole free tier).
+  if (risk[0] === 'openrouter.ai') {
+    const compatModel = model.startsWith('compat:') ? model.slice('compat:'.length) : '';
+    if (!compatModel.endsWith(':free')) return noPolicyOnRecord();
+  }
+  return {
+    name: 'privacy',
+    status: 'warn',
+    detail: `${host}: ${risk[1]}`,
+    hint: 'PCB designs are often proprietary. Use a paid tier or a local endpoint for confidential work.',
+  };
+}
+
+function checkKeyedCredential(model: string, env: NodeJS.ProcessEnv): DoctorCheck {
   // A pasted API key can end up as the model value (--model sk-..., a stray
   // COPPERHEAD_MODEL); redact it before it reaches the report, same policy as
   // transcripts (AC-4.1). Routing below still uses the raw value.
@@ -152,16 +293,20 @@ function providerCheck(
 ): DoctorCheck {
   try {
     const { model } = resolveModel(flag, config, env);
-    return checkCredential(model, env);
+    return checkCredential(model, env, resolveCompatSettings(config, env));
   } catch (err) {
-    // resolveModel throws only when nothing selects a model at all. Its message
-    // starts with "no model configured: " — already this check's detail line —
-    // so keep only the remedy part for the hint.
+    // resolveModel throws for two distinct reasons: nothing selects a model at
+    // all ("no model configured: ..."), or two-plus credentials are present
+    // with nothing to break the tie ("ambiguous: ..."). Strip whichever prefix
+    // matched for the hint, and reflect which case it was in the detail so an
+    // ambiguous setup does not misreport as "nothing configured".
+    const message = (err as Error).message;
+    const ambiguous = message.startsWith('ambiguous:');
     return {
       name: 'provider',
       status: 'fail',
-      detail: 'no model configured',
-      hint: (err as Error).message.replace(/^no model configured:\s*/, ''),
+      detail: ambiguous ? 'ambiguous: multiple credentials, no model selected' : 'no model configured',
+      hint: message.replace(/^(no model configured|ambiguous):\s*/, ''),
     };
   }
 }
@@ -222,17 +367,31 @@ export async function runDoctor(opts: RunDoctorOptions): Promise<DoctorReport> {
             hint: 'check that it is a regular file (not a directory) and that you have permission to read it.',
           };
   }
+  // Resolving the model can fail (nothing configured); providerCheck reports
+  // that, and the compat-only checks simply do not apply in that case.
+  const compat = resolveCompatSettings(config, deps.env);
+  let resolvedModel: string | null = null;
+  try {
+    resolvedModel = resolveModel(opts.model, config, deps.env).model;
+  } catch {
+    resolvedModel = null;
+  }
   const checks: DoctorCheck[] = [
     nodeCheck(deps.nodeVersion),
     await kicadCheck(deps.kicadVersion),
     await gitCheck(deps.gitVersion),
     providerCheck(opts.model, config, deps.env),
-    configError ?? projectCheck(config, opts.repoRoot),
   ];
+  if (resolvedModel) {
+    const privacy = checkPromptPrivacy(resolvedModel, compat);
+    if (privacy) checks.push(privacy);
+  }
+  checks.push(configError ?? projectCheck(config, opts.repoRoot));
+  // `warn` and `info` never block: only a hard failure means "not ready".
   return { ok: checks.every((c) => c.status !== 'fail'), checks };
 }
 
-const TAG: Record<DoctorStatus, string> = { ok: '[ok]', fail: '[FAIL]', info: '[info]' };
+const TAG: Record<DoctorStatus, string> = { ok: '[ok]', fail: '[FAIL]', warn: '[warn]', info: '[info]' };
 const TAG_COL = 2; // leading indent
 const NAME_COL = TAG_COL + 7; // widest tag "[FAIL]" + one space
 const DETAIL_COL = NAME_COL + 10; // widest name "kicad-cli" + one space
@@ -242,7 +401,7 @@ const DETAIL_COL = NAME_COL + 10; // widest name "kicad-cli" + one space
 // tests see plain text. Colored text is padded before painting — escape codes
 // have zero display width but nonzero string length, so painting first would
 // break the column math.
-const ANSI: Record<DoctorStatus, string> = { ok: '32', fail: '31', info: '36' };
+const ANSI: Record<DoctorStatus, string> = { ok: '32', fail: '31', warn: '33', info: '36' };
 const DIM = '2';
 function paint(text: string, code: string, on: boolean): string {
   return on ? `\u001b[${code}m${text}\u001b[0m` : text;

package/src/config.ts

@@ -26,6 +26,18 @@ export interface CopperheadConfig {
   /** Cache each turn's LLM response to disk and replay it on identical inputs,
    * so retries/restarts reuse work already paid for. Default on. */
   llmCache: boolean;
+  /**
+   * Base URL of an OpenAI-compatible endpoint (Groq, OpenRouter, Gemini's
+   * compat endpoint, a local Ollama). Consulted only by the `compat`
+   * route (design D2), so a stray value never redirects a plain `gpt-5` run.
+   */
+  baseURL?: string;
+  /**
+   * Name of the environment variable holding the compat endpoint's key, e.g.
+   * `GROQ_API_KEY`. The *name*, never the key itself: credentials stay in the
+   * environment (AC-4.1).
+   */
+  apiKeyEnv?: string;
   /** Content hashes of generated docs, for init idempotency (AC-1.4). */
   generatedHashes?: Record<string, string>;
   /**
@@ -90,6 +102,8 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
         ? (raw.maxStageRetries as number)
         : DEFAULTS.maxStageRetries,
     llmCache: raw.llmCache !== false,
+    ...(typeof raw.baseURL === 'string' && raw.baseURL.trim() ? { baseURL: raw.baseURL.trim() } : {}),
+    ...(typeof raw.apiKeyEnv === 'string' && raw.apiKeyEnv.trim() ? { apiKeyEnv: raw.apiKeyEnv.trim() } : {}),
     ...(raw.generatedHashes ? { generatedHashes: raw.generatedHashes } : {}),
     ...(raw.origin === 'create' || raw.origin === 'init' ? { origin: raw.origin } : {}),
   };
@@ -140,9 +154,76 @@ export function resolveModel(flag: string | undefined, config: CopperheadConfig,
   if (flag) return { model: flag, source: 'flag' };
   if (env.COPPERHEAD_MODEL) return { model: env.COPPERHEAD_MODEL, source: 'env' };
   if (config.model) return { model: config.model, source: 'config' };
-  if (env.OPENAI_API_KEY) return { model: 'gpt-5', source: 'openai-key' };
-  if (env.ANTHROPIC_API_KEY) return { model: 'claude', source: 'anthropic-key' };
+  // Auto-fallback is only safe when exactly one credential is present: guessing
+  // is a convenience when there is nothing to guess wrong. With two or more
+  // keys set (a common dev setup once a compat endpoint's key sits alongside
+  // OPENAI_API_KEY/ANTHROPIC_API_KEY), silently favoring whichever is checked
+  // first can send a request to the wrong provider with no signal — including
+  // a paid one when a free key was what was actually intended. Refuse instead
+  // of guessing; the compat route itself is never a fallback candidate here,
+  // since it is opt-in only via an explicit `compat:` prefix (design D2).
+  const available: { keyVar: string; model: string; source: ModelSource }[] = [
+    ...(env.OPENAI_API_KEY ? [{ keyVar: 'OPENAI_API_KEY', model: 'gpt-5', source: 'openai-key' as const }] : []),
+    ...(env.ANTHROPIC_API_KEY ? [{ keyVar: 'ANTHROPIC_API_KEY', model: 'claude', source: 'anthropic-key' as const }] : []),
+  ];
+  if (available.length === 1) return { model: available[0]!.model, source: available[0]!.source };
+  if (available.length > 1) {
+    throw new Error(
+      `ambiguous: ${available.length} credentials found (${available.map((a) => a.keyVar).join(', ')}) and no model was ` +
+        'selected; pass --model, set COPPERHEAD_MODEL, or set "model" in .copperhead/config.json.',
+    );
+  }
   throw new Error(
     'no model configured: pass --model, set COPPERHEAD_MODEL, or export an API key; see https://docs.copperhead.sh/reference/configuration/',
   );
 }
+
+/** Where an OpenAI-compatible run points, and which variable holds its key. */
+export interface CompatSettings {
+  /** Endpoint base URL; undefined means the client's own default (OpenAI). */
+  baseURL?: string;
+  /** Name of the env var holding the key. Never the key itself. */
+  apiKeyEnv: string;
+}
+
+/** The credential variable used when nothing else is configured. */
+export const DEFAULT_API_KEY_ENV = 'OPENAI_API_KEY';
+
+/**
+ * Resolve the compatible-endpoint settings: environment wins over config, the
+ * same direction as `resolveModel`'s chain. These are *settings*, not a
+ * provider selector — only the `compat` route reads them (design D1/D2), so an
+ * exported COPPERHEAD_BASE_URL never silently redirects a `gpt-5` run.
+ */
+export function resolveCompatSettings(config: CopperheadConfig, env = process.env): CompatSettings {
+  const baseURL = env.COPPERHEAD_BASE_URL?.trim() || config.baseURL?.trim();
+  const apiKeyEnv = env.COPPERHEAD_API_KEY_ENV?.trim() || config.apiKeyEnv?.trim() || DEFAULT_API_KEY_ENV;
+  return { ...(baseURL ? { baseURL } : {}), apiKeyEnv };
+}
+
+/**
+ * True when a resolved model id routes through the `compat` provider (D1/D2).
+ * The single source of truth for that gate: `makeProvider` uses it to decide
+ * whether to consult `CompatSettings` at all, and the response cache (loop.ts)
+ * uses it to decide whether a run's cache key may depend on `baseURL` — a
+ * non-compat run (gpt-5, claude, ...) never reads COPPERHEAD_BASE_URL, so its
+ * cache key must not vary with it either, or every entry gets orphaned each
+ * time the endpoint used for unrelated compat testing changes.
+ */
+export function isCompatModel(model: string): boolean {
+  return model === 'compat' || model.startsWith('compat:');
+}
+
+/**
+ * True when the endpoint is loopback, i.e. a local server such as Ollama.
+ * Those need no credential (design D4); a remote endpoint always does.
+ */
+export function isLocalEndpoint(baseURL: string | undefined): boolean {
+  if (!baseURL) return false;
+  try {
+    const h = new URL(baseURL).hostname.toLowerCase();
+    return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h === '[::1]' || h.endsWith('.local');
+  } catch {
+    return false; // an unparseable URL is not a local endpoint; the run fails later with a clearer error
+  }
+}

package/src/kicad/cli.ts

@@ -4,7 +4,7 @@ import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { normalizeReport, type CheckReport } from './report.js';
-import { PreflightError } from '../util/preflight.js';
+import { PreflightError, isNotFoundError } from '../util/preflight.js';
 
 export class KicadCliMissingError extends PreflightError {
   constructor() {
@@ -109,7 +109,7 @@ function fallbackAfterMissing(): string {
 async function runKicad(args: string[], opts?: { reject?: boolean }): Promise<Awaited<ReturnType<typeof execa>>> {
   let bin = resolveKicadCli();
   let res = await execa(bin, args, { reject: false });
-  if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
+  if (res.failed && isNotFoundError(res)) {
     if (bin === 'kicad-cli') {
       bin = fallbackAfterMissing();
       res = await execa(bin, args, { reject: false });
@@ -117,10 +117,10 @@ async function runKicad(args: string[], opts?: { reject?: boolean }): Promise<Aw
       throw new KicadCliMissingError();
     }
   }
-  if (opts?.reject === false) return res;
-  if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
+  if (res.failed && isNotFoundError(res)) {
     throw new KicadCliMissingError();
   }
+  if (opts?.reject === false) return res;
   if (res.failed) {
     throw Object.assign(new Error(res.stderr || res.stdout || `kicad-cli exited ${res.exitCode}`), res);
   }
@@ -143,15 +143,8 @@ export function setKicadFallbackBinaries(paths?: readonly string[]): void {
 }
 
 export async function kicadCliVersion(): Promise<string> {
-  try {
-    const res = await runKicad(['version']);
-    return String(res.stdout ?? '').trim();
-  } catch (err) {
-    if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
-    // runKicad already maps PATH ENOENT → fallback → KicadCliMissingError
-    if (err instanceof KicadCliMissingError) throw err;
-    throw err;
-  }
+  const res = await runKicad(['version']);
+  return String(res.stdout ?? '').trim();
 }
 
 async function runCheck(
@@ -167,9 +160,6 @@ async function runCheck(
       [...sub, '--format', 'json', '--exit-code-violations', '--output', out, ...extraArgs, filePath],
       { reject: false },
     );
-    if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
-      throw new KicadCliMissingError();
-    }
     let raw: unknown;
     try {
       raw = JSON.parse(await readFile(out, 'utf8'));
@@ -218,7 +208,6 @@ export async function kicadLoadError(filePath: string): Promise<string | null> {
     : ['pcb', 'export', 'pos', '--output', path.join(dir, 'probe.pos'), filePath];
   try {
     const res = await runKicad(args, { reject: false });
-    if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
     if (res.exitCode === 0) return null;
     return [res.stderr, res.stdout].filter(Boolean).join('\n').trim() || `kicad-cli exited ${res.exitCode}`;
   } finally {
@@ -258,7 +247,6 @@ export async function exportFab(pcbPath: string, schPath: string | null, outDir:
       result.produced.push(job.artifact);
     } catch (err) {
       if (err instanceof KicadCliMissingError) throw err;
-      if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
       result.failed.push({ artifact: job.artifact, reason: String((err as ExecaError).stderr ?? (err as Error).message).slice(0, 200) });
     }
   }
@@ -275,7 +263,6 @@ export async function exportSvg(kind: 'sch' | 'pcb', filePath: string, outDir: s
     await runKicad(args);
   } catch (err) {
     if (err instanceof KicadCliMissingError) throw err;
-    if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
     throw err;
   }
   return outDir;