copperhead 0.8.1 → 0.10.0

package/src/agent/loop.ts

@@ -7,7 +7,16 @@ import { CachingProvider } from './response-cache.js';
 import { withTimeout, TurnTimeoutError } from './recovery.js';
 import { buildSystemPrompt } from './prompts.js';
 import { loadConstraints, reopenDeferredAffects } from '../memory/constraints.js';
-import { loadConfig, CONFIG_DIR, type CopperheadConfig } from '../config.js';
+import { isCreateProducedRepo, isEngineAuthoredSchematic } from '../kicad/fab.js';
+import {
+  loadConfig,
+  CONFIG_DIR,
+  DEFAULT_API_KEY_ENV,
+  resolveCompatSettings,
+  isCompatModel,
+  type CompatSettings,
+  type CopperheadConfig,
+} from '../config.js';
 import { Transcript, type ExitPath, type RunStats } from './transcript.js';
 import { collectRunMeta, renderCliHeader, type RunMeta, type RunMetaInput } from './runmeta.js';
 import { plainRenderer, fmtDuration, fmtTokens, type ProgressRenderer } from './render.js';
@@ -22,7 +31,6 @@ import { AnthropicProvider } from './providers/anthropic.js';
 import { CodexProvider } from './providers/codex.js';
 import { ClaudeCodeProvider } from './providers/claude-code.js';
 import { CursorProvider } from './providers/cursor.js';
-import { openSynapMemory, type RunRecord, type SynapMemory } from '../memory/synap.js';
 
 /** What the user sees at the moment they decide whether to keep going. */
 export interface BudgetExhaustedStats {
@@ -74,7 +82,43 @@ export interface RunResult {
   cacheHits: number;
 }
 
-export async function makeProvider(model: string, sessionResume = false): Promise<Provider> {
+export async function makeProvider(
+  model: string,
+  sessionResume = false,
+  compat?: CompatSettings | undefined,
+): Promise<Provider> {
+  // OpenAI-compatible endpoint (Groq, OpenRouter, Gemini compat, local
+  // Ollama). An explicit `compat` prefix is the opt-in: nothing else
+  // consults baseURL, so a stray COPPERHEAD_BASE_URL cannot redirect a keyed
+  // `gpt-5` run to a third party (design D2).
+  if (isCompatModel(model)) {
+    const compatModel = model.startsWith('compat:') ? model.slice('compat:'.length) : undefined;
+    if (compatModel === '') {
+      throw new Error('compat model override cannot be empty; use "compat:<model-id>"');
+    }
+    const settings = compat ?? { apiKeyEnv: DEFAULT_API_KEY_ENV };
+    // Bare `compat` (no id) has no valid default: unlike gpt-5/claude, a
+    // compatible endpoint serves whatever models its host chooses, so there is
+    // no id that is ever correct to assume. Falling through here would build a
+    // provider that silently sends the literal string "gpt-5" (OpenAIProvider's
+    // own default) to a host that almost certainly does not serve it.
+    if (!compatModel) {
+      throw new Error(
+        settings.baseURL
+          ? `compat requires a model id; use "compat:<model-id>" (endpoint ${settings.baseURL} is configured, but has no default model)`
+          : 'compat requires a model id and an endpoint; use "compat:<model-id>" and set baseURL (COPPERHEAD_BASE_URL or .copperhead/config.json)',
+      );
+    }
+    if (!settings.baseURL) {
+      throw new Error(
+        `compat:${compatModel} requires an endpoint; set baseURL (COPPERHEAD_BASE_URL or "baseURL" in .copperhead/config.json) — without one this would silently fall back to the real OpenAI API.`,
+      );
+    }
+    return new OpenAIProvider(compatModel, {
+      baseURL: settings.baseURL,
+      apiKeyEnv: settings.apiKeyEnv,
+    });
+  }
   if (model === 'codex' || model.startsWith('codex:')) {
     const codexModel = model.startsWith('codex:') ? model.slice('codex:'.length) : undefined;
     if (codexModel === '') throw new Error('codex model override cannot be empty; use "codex" or "codex:<model-id>"');
@@ -158,16 +202,10 @@ async function appendChangelog(
   await writeFile(p, lines.join('\n'), 'utf8');
 }
 
-/**
- * Owns the Synap session for one run. The bridge is a subprocess, so the
- * shutdown in `finally` is what lets the CLI exit; without it the process
- * hangs after a successful run.
- */
 export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
-  const memory = await openSynapMemory({ repoRoot: opts.repoRoot, log: opts.log });
   const providers = new Set<Provider>();
   try {
-    return await runWithMemory(opts, memory, providers);
+    return await runWithProviders(opts, providers);
   } finally {
     for (const provider of providers) {
       try {
@@ -176,15 +214,10 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
         opts.log?.(`warning: ${provider.name} provider cleanup failed (${(err as Error).message})`);
       }
     }
-    await memory?.close();
   }
 }
 
-async function runWithMemory(
-  opts: RunOptions,
-  memory: SynapMemory | null,
-  providers: Set<Provider>,
-): Promise<RunResult> {
+async function runWithProviders(opts: RunOptions, providers: Set<Provider>): Promise<RunResult> {
   const r = opts.renderer ?? plainRenderer(opts.log ?? ((l: string) => console.log(l)));
   const log = (l: string): void => r.log(l);
   const repoRoot = opts.repoRoot;
@@ -196,11 +229,28 @@ async function runWithMemory(
 
   const transcript = new Transcript(repoRoot);
   await transcript.init();
+  // Legibility gates finish only where copperhead authored the sheet; a
+  // hand-drawn repo gets findings as information, never as a wedge (C6).
+  // Both conditions matter: the create-origin marker scopes the gate to repos
+  // this tool produced, and the generator stamp scopes it to sheets copperhead
+  // still owns. A human taking the sheet over in KiCad re-saves it under
+  // KiCad's generator, and from then on the gate must not defend a drawing
+  // the engine can no longer regenerate. A create repo whose schematic is not
+  // yet scaffolded keeps the gate: the sheet stage 4 will produce is
+  // copperhead-authored by construction.
+  let gateLegibility = isCreateProducedRepo(config);
+  if (gateLegibility && config.schematic) {
+    try {
+      gateLegibility = isEngineAuthoredSchematic(await readFile(path.join(repoRoot, config.schematic), 'utf8'));
+    } catch {
+      // schematic configured but absent (pre-scaffold): keep the gate
+    }
+  }
   const ctx: RunContext = {
     repoRoot,
     config,
     transcript,
-    ledger: new ObligationsLedger(),
+    ledger: new ObligationsLedger(gateLegibility),
     runId: path.basename(transcript.dir),
     interactive: opts.interactive ?? false,
     confirm: opts.confirm ?? (async () => true),
@@ -210,6 +260,8 @@ async function runWithMemory(
     filesTouched: new Set(),
     decisions: [],
     lastErc: null,
+    lastLegibility: null,
+    lastScore: null,
     lastDrc: null,
     repairCycles: 0,
     finishRequest: null,
@@ -220,12 +272,24 @@ async function runWithMemory(
   // it only when the env flag is set AND config.llmCache is disabled — the same
   // condition under which we skip the CachingProvider wrap below.
   const sessionResume = process.env.COPPERHEAD_CC_SESSION_RESUME === '1' && !config.llmCache;
-  let provider = opts.provider ?? (await makeProvider(opts.model, sessionResume));
+  const compatSettings = resolveCompatSettings(config);
+  let provider = opts.provider ?? (await makeProvider(opts.model, sessionResume, compatSettings));
   // Cache every turn's response so a retried/restarted stage replays what it
   // already paid for instead of re-calling the model (repo-scoped, cross-run).
   // Skip an injected provider (tests drive scripted providers directly).
   if (config.llmCache && !opts.provider) {
-    provider = new CachingProvider(provider, path.join(repoRoot, CONFIG_DIR, 'llm-cache'), log, opts.model);
+    // Mirrors makeProvider's own gate above (D2/AC-3.16): COPPERHEAD_BASE_URL
+    // is consulted only for the explicit `compat:` route, so a gpt-5/claude
+    // run's cache key must not vary with a variable that run never reads —
+    // otherwise every non-compat cache entry gets orphaned each time the
+    // endpoint used for compat testing changes.
+    provider = new CachingProvider(
+      provider,
+      path.join(repoRoot, CONFIG_DIR, 'llm-cache'),
+      log,
+      opts.model,
+      isCompatModel(opts.model) ? compatSettings.baseURL : undefined,
+    );
   }
   providers.add(provider);
   // Held separately from `provider` (which is reassigned on failover) so the
@@ -272,37 +336,12 @@ async function runWithMemory(
       ...reopened.map((r) => `- ${r.key} affects ${r.item}`),
     ].join('\n');
   }
-  // Cross-run memory is appended after the repo's own docs and constraints so
-  // that the in-repo sources of truth are what the model reads first.
-  const recalled = memory ? await memory.recall(opts.request) : null;
-  if (recalled) {
-    await transcript.event('synap-recall', { chars: recalled.length });
-    log('recalled prior context from Synap memory');
-  }
-  const system = recalled ? `${basePrompt}\n\n${recalled}` : basePrompt;
   const messages: Msg[] = [
-    { role: 'system', content: system },
+    { role: 'system', content: basePrompt },
     { role: 'user', content: opts.stagePrompt ? `${opts.stagePrompt}\n\nRequest: ${opts.request}` : opts.request },
   ];
   await transcript.event('run-start', meta);
 
-  /**
-   * A memory write that fails is reported rather than swallowed, but it does
-   * not change the run's outcome: discarding a verified commit because a
-   * third-party write failed would be the worse trade.
-   */
-  const remember = async (run: RunRecord): Promise<void> => {
-    if (!memory) return;
-    try {
-      await memory.record(run);
-      await transcript.event('synap-record', { outcome: run.outcome });
-    } catch (err) {
-      const message = (err as Error).message;
-      log(`warning: Synap memory write failed (${message}); this run was not recorded`);
-      await transcript.event('synap-record-failed', { error: message });
-    }
-  };
-
   let tokensIn = 0;
   let tokensOut = 0;
   let turnsUsed = 0;
@@ -360,6 +399,8 @@ async function runWithMemory(
       filesTouched: [...ctx.filesTouched],
       ercResult: ctx.lastErc ? (ctx.lastErc.ok ? 'clean' : `${ctx.lastErc.violations.length} violations`) : null,
       drcResult: ctx.lastDrc ? (ctx.lastDrc.ok ? 'clean' : `${ctx.lastDrc.violations.length} violations`) : null,
+      legibilityResult: ctx.lastLegibility ? `${ctx.lastLegibility.error} error, ${ctx.lastLegibility.advisory} advisory` : null,
+      scoreResult: ctx.lastScore !== null ? `${ctx.lastScore}/100` : null,
       decisions: ctx.decisions,
       tokensIn,
       tokensOut,
@@ -592,17 +633,6 @@ async function runWithMemory(
           env: meta,
           stats: runStats,
         });
-        // Refusals are the most valuable thing to remember: they encode a budget
-        // or constraint that this user's designs keep running into.
-        await remember({
-          request: opts.request,
-          outcome: 'refused',
-          summary,
-          changeId: ctx.changeId,
-          filesTouched: [],
-          decisions: ctx.decisions,
-          verification: 'n/a (refused before verification)',
-        });
         log(`refused: ${summary}`);
         r.finish(outcomeLine(runStats));
         return {
@@ -721,6 +751,8 @@ async function runWithMemory(
         filesTouched: files,
         ercResult: ctx.lastErc ? (ctx.lastErc.ok ? 'clean' : 'FAILING') : 'not run',
         drcResult: ctx.lastDrc ? (ctx.lastDrc.ok ? 'clean' : 'FAILING') : 'not run',
+        legibilityResult: ctx.lastLegibility ? `${ctx.lastLegibility.error} error, ${ctx.lastLegibility.advisory} advisory` : null,
+        scoreResult: ctx.lastScore !== null ? `${ctx.lastScore}/100` : null,
         decisions: ctx.decisions,
         tokensIn,
         tokensOut,
@@ -729,15 +761,6 @@ async function runWithMemory(
         env: meta,
         stats: runStats,
       });
-      await remember({
-        request: opts.request,
-        outcome: 'success',
-        summary,
-        changeId: ctx.changeId,
-        filesTouched: files,
-        decisions: ctx.decisions,
-        verification,
-      });
       log(`committed ${commit.slice(0, 10)} (${files.length} file(s))`);
       r.finish(outcomeLine(runStats, `committed ${commit.slice(0, 10)}`));
       return {

package/src/agent/prompts.ts

@@ -19,9 +19,10 @@ const WORKFLOW = `Workflow for every run:
 2. Call propose_change with a change id (kebab-case), why, what changes, and tasks. Then call validate_change. Edit tools (edit_file, write_file) unlock only after validation passes.
 3. Make the edits. Use the exact same net names and refdes everywhere. For .kicad_sch/.kicad_pcb use edit_file with unique anchors from the actual file text (read the file first). For renaming a net or refdes across a file, one edit_file call with replace_all: true beats many small edits.
 4. Run run_erc after schematic edits (and run_drc after board edits). If violations: read them, fix, re-run.
-5. Run check_drift; update any doc that references a changed value/part/pin in the same run.
-6. Record every non-trivial decision with record_decision, and every stated/assumed/discovered constraint with record_constraint.
-7. Call finish with outcome "done" when everything is verified, or outcome "refuse" (citing the violated budget/constraint) if the request should not be done. finish will list any unmet obligations; resolve them and call it again.
+5. After schematic edits also run check_legibility and reconcile every error-severity finding (advisories inform, they do not block). An electrically correct sheet that reads badly is not done: finish refuses while error findings are outstanding, the same way it refuses on a failing ERC.
+6. Run check_drift; update any doc that references a changed value/part/pin in the same run.
+7. Record every non-trivial decision with record_decision, and every stated/assumed/discovered constraint with record_constraint.
+8. Call finish with outcome "done" when everything is verified, or outcome "refuse" (citing the violated budget/constraint) if the request should not be done. finish will list any unmet obligations; resolve them and call it again.
 
 Turns are the scarce resource, not tool calls: the run has a hard turn budget, and every tool call in one reply executes in the same turn. When calls are independent — multiple record_constraint or resolve_affected calls (use resolutions: [...] to clear a backlog in one call), several read_file calls — issue them together in a single reply instead of one per turn.
 Always send a populated \`args\` object that matches the tool's JSON Schema (e.g. read_file needs {"path": "..."}). Never open a stage with an empty-args call to probe a tool — it only returns an error and burns a whole turn.`;

package/src/agent/providers/openai.ts

@@ -1,18 +1,52 @@
+import { DEFAULT_API_KEY_ENV, isLocalEndpoint } from '../../config.js';
 import type { ChatOpts, Msg, Provider, ToolSchema, Turn, ToolCall } from '../types.js';
 
+/** Pointing the provider at an OpenAI-compatible endpoint (design D1). */
+export interface OpenAIProviderOptions {
+  /** Endpoint base URL; omitted means the client's own default (OpenAI). */
+  baseURL?: string | undefined;
+  /** Name of the env var holding the key. Never the key itself. */
+  apiKeyEnv?: string | undefined;
+}
+
 export class OpenAIProvider implements Provider {
-  readonly name = 'openai';
+  readonly name: string;
+  private readonly apiKey: string | undefined;
+  private readonly baseURL: string | undefined;
 
   constructor(
     private readonly model = 'gpt-5',
-    private readonly apiKey = process.env.OPENAI_API_KEY,
+    opts: OpenAIProviderOptions = {},
+    env: NodeJS.ProcessEnv = process.env,
   ) {
-    if (!this.apiKey) throw new Error('OPENAI_API_KEY is not set');
+    // Credentials are always resolved through a named env var, never accepted
+    // as a literal value: the one way to supply a key keeps application code
+    // from ever holding one directly (mirrors AC-4.1 elsewhere). Tests inject
+    // fake values through the `env` argument, not through opts.
+    const keyEnv = opts.apiKeyEnv ?? DEFAULT_API_KEY_ENV;
+    this.baseURL = opts.baseURL;
+    // A compat endpoint must be structurally ineligible for the paid
+    // OpenAI/Anthropic failover in otherProvider() (loop.ts) — it is not
+    // OpenAI, and a rate limit there must never silently redirect a run the
+    // user deliberately pointed elsewhere to someone else's paid API.
+    this.name = this.baseURL ? 'openai-compat' : 'openai';
+    this.apiKey = env[keyEnv];
+    // A loopback endpoint (Ollama) serves the same API with no credential, and
+    // it is the one backend that is both free and fully local — requiring a
+    // dummy key there would be a papercut on the most useful config (D4).
+    if (!this.apiKey && !isLocalEndpoint(this.baseURL)) {
+      throw new Error(`${keyEnv} is not set`);
+    }
   }
 
   async chat(messages: Msg[], tools: ToolSchema[], opts: ChatOpts = {}): Promise<Turn> {
     const { default: OpenAI } = await import('openai');
-    const client = new OpenAI({ apiKey: this.apiKey });
+    const client = new OpenAI({
+      // A local endpoint may legitimately have no key, but the client still
+      // wants a non-empty string, so send a placeholder it will never check.
+      apiKey: this.apiKey ?? 'no-key-required',
+      ...(this.baseURL ? { baseURL: this.baseURL } : {}),
+    });
     const res = await client.chat.completions.create({
       model: this.model,
       max_completion_tokens: opts.maxTokens ?? 8192,

package/src/agent/providers/tool-protocol.ts

@@ -85,9 +85,14 @@ export interface ParsedToolTurn {
  * split so only an inner `{args}` with no `tool` key balanced), not the tool
  * being broken. Returns a one-line steer to re-emit it, or undefined when the
  * absence of a call is genuine (plain prose, no tool named).
+ *
+ * Also covers the mirror case (I18): well-formed JSON naming a tool that is NOT in
+ * the catalog — withheld by the edit lock, or invented. That call is correctly not
+ * dispatched, but it must not be silent either.
  */
 function detectMalformedCall(text: string, catalog: Set<string>): string | undefined {
   const re = /"tool"\s*:\s*"([^"]+)"/g;
+  const offCatalog: string[] = [];
   let m: RegExpExecArray | null;
   while ((m = re.exec(text)) !== null) {
     const name = m[1]!;
@@ -98,6 +103,23 @@ function detectMalformedCall(text: string, catalog: Set<string>): string | undef
         'Re-emit it as exactly one complete JSON object: {"tool": "...", "args": { ... }}.'
       );
     }
+    if (!offCatalog.includes(name)) offCatalog.push(name);
+  }
+  // A well-formed call naming a tool the turn did not advertise — a locked edit or
+  // drafting tool before propose_change/validate_change, or an invented name.
+  // `toToolCall` is right to refuse it (the lock is structural, D2), but dropping it
+  // to prose tells the model NOTHING, and it fills that silence: fabricating the
+  // result it never got (I15), or concluding the engine is absent from the build and
+  // refusing the stage outright (I18). Withholding the tool is the invariant; hiding
+  // the reason never was, so name it and print the real catalog.
+  if (offCatalog.length) {
+    const named = offCatalog.map((n) => `"${n}"`).join(', ');
+    return (
+      `No call ran: ${named} ${offCatalog.length > 1 ? 'are' : 'is'} not in this turn's tool ` +
+      'catalog. Edit and drafting tools are withheld until a proposal validates — call ' +
+      'propose_change, then validate_change, and they appear. Do not conclude a tool is ' +
+      `missing from the build. Available this turn: ${[...catalog].join(', ')}.`
+    );
   }
   return undefined;
 }

package/src/agent/recovery.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import type { Msg, Provider } from './types.js';
+import { resolveLibrarySymbol, searchInstalledSymbols, symbolSearchDirs, listInstalledLibraries } from '../kicad/symlib.js';
 
 /** Thrown when a single provider turn blows past its watchdog deadline. */
 export class TurnTimeoutError extends Error {
@@ -116,6 +117,91 @@ export async function transcriptExcerpt(transcriptDir: string, maxChars = 4000):
   return joined.length > maxChars ? joined.slice(joined.length - maxChars) : joined;
 }
 
+/**
+ * Deterministically re-probe every lib_id named in a failure narrative against
+ * the installed libraries, so the diagnostician judges symbol-availability
+ * claims from machine facts instead of the agent's prose. An agent that has
+ * been dead-ended by wrong library nicknames concludes — and records — that
+ * whole libraries are absent when they are installed; a refusal built on that
+ * premise reads exactly like a genuine environmental gap, and the one thing
+ * that distinguishes them is re-checking the named lib_ids, which costs no
+ * LLM turn. Never throws; on any probe error it reports what it could.
+ */
+export async function symbolAvailabilityFacts(text: string, dirs?: string[], cap = 8): Promise<string> {
+  const ids: string[] = [];
+  // A library nickname is its `.kicad_sym` filename stem, so it can carry `-`
+  // and `.` as well as `_` (`Custom-Parts`, `MyCorp.RF`) — a nickname the regex
+  // truncates is probed as the wrong lib_id and reported absent, which is the
+  // false negative this whole fact block exists to prevent. Separators are
+  // interior only, so a trailing sentence period is not swallowed.
+  for (const m of text.matchAll(/\b([A-Za-z0-9_](?:[A-Za-z0-9_.-]*[A-Za-z0-9_])?):([A-Za-z0-9][A-Za-z0-9_.+-]*)/g)) {
+    const lib = m[1]!;
+    const name = m[2]!;
+    // Require letters on both sides: drops file:line refs ("create.ts:311"),
+    // times and bare numbers. Engine-generated power symbols are not library
+    // facts.
+    if (!/[A-Za-z]/.test(lib) || !/[A-Za-z]/.test(name) || lib === 'copperhead_power') continue;
+    const libId = `${lib}:${name}`;
+    if (!ids.includes(libId)) ids.push(libId);
+  }
+  if (!ids.length) return '';
+  // Collection is unbounded but probing is capped, so a probe-heavy transcript
+  // stays cheap. The overflow is named rather than dropped: the supervisor is
+  // told these facts are ground truth, and silently probing 8 of 30 lib_ids
+  // would let it read "unprobed" as "absent".
+  const probed = ids.slice(0, cap);
+  const unprobed = ids.slice(cap);
+  let searchDirs: string[];
+  try {
+    searchDirs = dirs ?? (await symbolSearchDirs());
+  } catch {
+    return '';
+  }
+  if (!searchDirs.length) return '';
+  // A directory with no readable library means nothing was checked: emitting
+  // "not installed" lines as ground truth from that state is the exact false
+  // absence this block exists to prevent (same guard as bomSymbolDossier).
+  if (!(await listInstalledLibraries(searchDirs)).size) return '';
+  const lines: string[] = [];
+  for (const libId of probed) {
+    const name = libId.slice(libId.indexOf(':') + 1);
+    try {
+      const r = await resolveLibrarySymbol(libId, searchDirs);
+      if (r.status === 'ok') {
+        lines.push(`- ${libId}: RESOLVES on this machine (${r.pins.length} pins)`);
+      } else if (r.status === 'found-elsewhere') {
+        // The resolver already located the part under another lib_id; saying
+        // "not installed" here would be the exact false absence claim this
+        // block exists to prevent.
+        lines.push(`- ${libId}: not at that lib_id, but installed as: ${r.libIds.slice(0, 4).join(', ')}`);
+      } else {
+        const elsewhere = await searchInstalledSymbols(name, searchDirs, 4);
+        const inThat =
+          r.status === 'no-symbol' && r.candidates.length
+            ? ` (closest in that library: ${r.candidates.slice(0, 4).join(', ')})`
+            : '';
+        const where = elsewhere.length
+          ? `; installed as: ${elsewhere.join(', ')}`
+          : `; no installed symbol matches "${name}" in any library`;
+        lines.push(
+          r.status === 'no-symbol'
+            ? `- ${libId}: not in that library${inThat}${where}`
+            : `- ${libId}: no library of that nickname is installed${where}`,
+        );
+      }
+    } catch {
+      // a single unreadable library must not sink the fact block
+    }
+  }
+  if (!lines.length) return '';
+  if (unprobed.length) {
+    lines.push(
+      `- NOT RE-PROBED (probe limit ${cap}): ${unprobed.join(', ')} — these were named in the text but not checked, so nothing above says whether they exist.`,
+    );
+  }
+  return lines.join('\n');
+}
+
 /**
  * Ask the model whether a failed/incomplete stage is worth retrying, and if so
  * how. Uses a fresh, tool-less provider turn (the same saved-login backend the
@@ -132,6 +218,9 @@ export async function diagnoseStageFailure(
     excerpt: string;
     attempt: number;
     maxAttempts: number;
+    /** Deterministic re-probe results for lib_ids named in the failure/excerpt
+     *  (`symbolAvailabilityFacts`); authoritative over the transcript's claims. */
+    symbolFacts?: string;
   },
 ): Promise<StageDiagnosis> {
   const system =
@@ -145,10 +234,14 @@ export async function diagnoseStageFailure(
     `Failure: ${input.failure}\n` +
     `This was attempt ${input.attempt} of ${input.maxAttempts}.\n\n` +
     `Recent transcript (most recent last):\n${input.excerpt}\n\n` +
+    (input.symbolFacts
+      ? `Machine-verified symbol facts — a deterministic re-probe of the lib_ids named above, run just now against this machine's installed KiCad libraries. Each line reported below is ground truth and overrides anything the transcript claims about that symbol's availability. Coverage may be partial: a lib_id listed as NOT RE-PROBED, or absent from this block entirely, is unknown, never confirmed absent.\n${input.symbolFacts}\n\n`
+      : '') +
     'Reply with ONLY a JSON object, no prose:\n' +
     '{"verdict":"retry"|"abort","reason":"<one sentence>","guidance":"<if retry: concrete, specific instructions to prepend to the next attempt so it avoids this failure; otherwise empty>"}\n' +
     '- "retry" if the failure looks transient or fixable with clearer instructions (a dropped or locked tool call, an empty/no-op edit, a skipped step, a timeout, a formatting slip).\n' +
-    '- "abort" if repeating the same attempt will not help and a human should look (missing inputs, a genuine dead-end, or the same failure already seen on a prior attempt).';
+    '- "abort" if repeating the same attempt will not help and a human should look (missing inputs, a genuine dead-end, or the same failure already seen on a prior attempt).\n' +
+    '- an agent\'s claim that a symbol or library is absent is NOT evidence: agents dead-ended by wrong library nicknames routinely conclude whole libraries are missing. If the machine-verified facts contradict the failure\'s premise (a cited-absent lib_id RESOLVES, or the part is installed under another library), the verdict is "retry", with guidance quoting the correct lib_ids.';
   const messages: Msg[] = [
     { role: 'system', content: system },
     { role: 'user', content: user },

package/src/agent/response-cache.ts

@@ -36,13 +36,29 @@ export class CachingProvider implements Provider {
      *  in the cache key so switching model on the same repo does not replay the
      *  other model's cached turns (F6). Falls back to the provider family name. */
     private readonly modelId?: string,
+    /** The compat endpoint's base URL, if any. A model id like `compat:llama-3.1-8b-instant`
+     *  is not unique across hosts (Groq, OpenRouter, etc. all serve overlapping model
+     *  ids), so the endpoint must be part of the key too, or two different hosts
+     *  serving "the same" model id would share cached turns. */
+    private readonly baseURL?: string,
   ) {
     this.name = inner.name;
   }
 
   private keyFor(messages: Msg[], tools: ToolSchema[]): string {
     return createHash('sha256')
-      .update(JSON.stringify({ model: this.modelId ?? this.name, messages, tools: tools.map((t) => t.name) }))
+      .update(
+        JSON.stringify({
+          model: this.modelId ?? this.name,
+          // Omitted rather than `?? null` when unset: a non-compat run's key
+          // must stay byte-identical to what it hashed before baseURL existed
+          // (F6/D2), or every pre-existing cache entry — not just compat ones —
+          // is orphaned on the first run after upgrade.
+          ...(this.baseURL ? { baseURL: this.baseURL } : {}),
+          messages,
+          tools: tools.map((t) => t.name),
+        }),
+      )
       .digest('hex');
   }