copperhead 0.3.0 → 0.4.0

package/src/agent/transcript.ts

@@ -1,6 +1,31 @@
 import { appendFile, mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { redactSecrets } from '../util/redact.js';
+import { renderEnvironmentSection, type RunMeta } from './runmeta.js';
+import { fmtDuration, fmtTokens } from './render.js';
+
+/** How a run terminated — the single most-queried triage fact (AC-8.5). */
+export type ExitPath =
+  | 'done'
+  | 'refused'
+  | 'turn-budget-exhausted'
+  | 'repair-cycles-exhausted'
+  | 'commit-failed'
+  | 'provider-error'
+  | 'stalled';
+
+/** Post-run addenda recorded at every terminal branch (AC-8.5). */
+export interface RunStats {
+  exitPath: ExitPath;
+  turnsUsed: number;
+  maxTurns: number;
+  repairCyclesUsed: number;
+  maxRepairCycles: number;
+  tokensIn: number;
+  tokensOut: number;
+  perTurn: { turn: number; in: number; out: number }[];
+  durationMs: number;
+}
 
 export interface RunSummaryData {
   request: string;
@@ -15,6 +40,23 @@ export interface RunSummaryData {
   outcome: 'success' | 'failure' | 'aborted';
   openObligations: string | null;
   detail?: string;
+  env?: RunMeta;
+  stats?: RunStats;
+}
+
+function renderRunStats(s: RunStats): string[] {
+  return [
+    `## Run stats`,
+    ``,
+    `- **Exit path:** ${s.exitPath}`,
+    `- **Turns:** ${s.turnsUsed} / ${s.maxTurns}`,
+    `- **Repair cycles:** ${s.repairCyclesUsed} / ${s.maxRepairCycles}`,
+    `- **Tokens:** ${fmtTokens(s.tokensIn)} in / ${fmtTokens(s.tokensOut)} out`,
+    `- **Duration:** ${fmtDuration(s.durationMs)}`,
+    ...(s.perTurn.length
+      ? [`- **Per turn:** ${s.perTurn.map((t) => `${t.turn}: ${t.in}/${t.out}`).join(' · ')}`]
+      : []),
+  ];
 }
 
 /**
@@ -38,6 +80,10 @@ export class Transcript {
 
   async event(type: string, data: unknown): Promise<void> {
     const line = redactSecrets(JSON.stringify({ ts: new Date().toISOString(), type, data }));
+    // The audit trail must survive anything that happens to the working tree
+    // mid-run (a rollback path once deleted this directory); losing an event
+    // is acceptable, crashing the run to report one is not.
+    await mkdir(this.dir, { recursive: true });
     await appendFile(this.jsonlPath, line + '\n', 'utf8');
   }
 
@@ -50,6 +96,8 @@ export class Transcript {
       `- **OpenSpec change:** ${s.changeId ?? 'n/a'}`,
       `- **Tokens:** ${s.tokensIn} in / ${s.tokensOut} out`,
       ``,
+      ...(s.env ? [...renderEnvironmentSection(s.env), ``] : []),
+      ...(s.stats ? [...renderRunStats(s.stats), ``] : []),
       `## Plan`,
       ``,
       s.plan ?? '(no plan recorded)',
@@ -72,6 +120,7 @@ export class Transcript {
     }
     if (s.detail) lines.push('', '## Detail', '', s.detail);
     const out = path.join(this.dir, 'summary.md');
+    await mkdir(this.dir, { recursive: true });
     await writeFile(out, redactSecrets(lines.join('\n') + '\n'), 'utf8');
     return out;
   }

package/src/cli.ts

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { createInterface } from 'node:readline/promises';
 import { loadConfig, resolveModel } from './config.js';
 import { runInit, InitError } from './memory/scaffold.js';
 import { runCheck } from './commands/check.js';
 import { syncVerify, syncResolve, formatSyncReport } from './commands/sync.js';
 import { runCreate } from './commands/create.js';
-import { runAgentLoop } from './agent/loop.js';
+import { runAgentLoop, type BudgetExhaustedStats } from './agent/loop.js';
+import { makeRenderer } from './agent/render.js';
 import { kicadCliVersion } from './kicad/cli.js';
 import { loadEnvFile } from './util/env.js';
 
@@ -17,6 +19,12 @@ import { loadEnvFile } from './util/env.js';
 // A real environment variable always beats the file.
 loadEnvFile(process.cwd());
 
+// Single source of truth for the version. Both src/cli.ts (via tsx) and
+// dist/cli.js sit one level below the package root, so the path holds either
+// way, and a release can never ship a version string that disagrees with the
+// package it was published as.
+const { version } = createRequire(import.meta.url)('../package.json') as { version: string };
+
 const program = new Command();
 
 const repoOf = (opts: { repo?: string }): string => path.resolve(opts.repo ?? process.cwd());
@@ -28,12 +36,32 @@ async function confirmTty(question: string): Promise<boolean> {
   return /^y(es)?$/i.test(answer.trim());
 }
 
+/**
+ * Attended runs get a decision point instead of a rollback when the turn
+ * budget runs out (issue #15). Non-TTY (CI, pipes) keeps fail-and-restore.
+ */
+function budgetContinuePrompt(): ((stats: BudgetExhaustedStats) => Promise<number>) | undefined {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return undefined;
+  return async (stats) => {
+    // ceil of the ORIGINAL budget (design D1), so repeat extensions offer the
+    // same increment instead of escalating with the extended turn count.
+    const extra = Math.ceil(stats.maxTurns / 2);
+    const k = (n: number) => `${(n / 1000).toFixed(1)}k`;
+    const q = `Turn budget exhausted (${stats.turnsUsed} turns, ${k(stats.tokensIn)} in / ${k(stats.tokensOut)} out, ${stats.filesTouched.length} file(s) touched, ${stats.openObligations} open obligation(s)). Continue with ${extra} more turns?`;
+    return (await confirmTty(q)) ? extra : 0;
+  };
+}
+
 program
   .name('copperhead')
   .description('Cursor for circuit boards: an AI agent for real KiCad repositories')
-  .version('0.1.0')
+  .version(version)
   .option('--repo <path>', 'target repository (default: cwd)')
-  .option('--json', 'machine-readable output');
+  .option('--json', 'machine-readable output')
+  .option('--plain', 'plain log-style output (no interactive status line)');
+
+const rendererOf = () =>
+  makeRenderer({ json: Boolean(program.opts().json), plain: Boolean(program.opts().plain) });
 
 program
   .command('init')
@@ -101,9 +129,10 @@ program
     ) => {
       const repo = repoOf(program.opts());
       try {
-        await kicadCliVersion();
+        const kicadVer = await kicadCliVersion();
         const config = await loadConfig(repo);
-        const model = resolveModel(opts.model, config);
+        const { model, source } = resolveModel(opts.model, config);
+        const continuePrompt = budgetContinuePrompt();
         const res = await runAgentLoop({
           repoRoot: repo,
           request,
@@ -113,6 +142,9 @@ program
           dryRun: opts.dryRun ?? false,
           interactive: opts.interactive ?? false,
           confirm: confirmTty,
+          ...(continuePrompt ? { onBudgetExhausted: continuePrompt } : {}),
+          renderer: rendererOf(),
+          meta: { command: 'do', modelSource: source, version, kicadCliVersion: kicadVer },
         });
         if (program.opts().json) console.log(JSON.stringify(res, null, 2));
         process.exit(res.outcome === 'failure' ? 1 : 0);
@@ -131,7 +163,7 @@ program
   .action(async (opts: { model?: string; dryRun?: boolean }) => {
     const repo = repoOf(program.opts());
     try {
-      await kicadCliVersion();
+      const kicadVer = await kicadCliVersion();
       const report = await syncVerify(repo);
       const json = Boolean(program.opts().json);
       if (json) console.log(JSON.stringify(report, null, 2));
@@ -147,8 +179,11 @@ program
         process.exit(0);
       }
       const config = await loadConfig(repo);
-      const model = resolveModel(opts.model, config);
-      const res = await syncResolve(repo, report, model, json ? () => {} : (s) => console.log(s));
+      const { model, source } = resolveModel(opts.model, config);
+      const res = await syncResolve(repo, report, model, json ? () => {} : (s) => console.log(s), {
+        renderer: rendererOf(),
+        meta: { command: 'sync', modelSource: source, version, kicadCliVersion: kicadVer },
+      });
       process.exit(res.ok ? 0 : 1);
     } catch (err) {
       console.error((err as Error).message);
@@ -165,15 +200,19 @@ program
   .action(async (opts: { brief: string; model?: string; interactive?: boolean }) => {
     const repo = repoOf(program.opts());
     try {
-      await kicadCliVersion();
+      const kicadVer = await kicadCliVersion();
       const config = await loadConfig(repo);
-      const model = resolveModel(opts.model, config);
+      const { model, source } = resolveModel(opts.model, config);
+      const continuePrompt = budgetContinuePrompt();
       const res = await runCreate({
         repoRoot: repo,
         briefPath: opts.brief,
         model,
         interactive: opts.interactive ?? false,
+        ...(continuePrompt ? { onBudgetExhausted: continuePrompt } : {}),
         log: (s) => console.log(s),
+        renderer: rendererOf(),
+        meta: { command: 'create', modelSource: source, version, kicadCliVersion: kicadVer },
       });
       process.exit(res.ok ? 0 : 1);
     } catch (err) {

package/src/commands/check.ts

@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs';
 import { loadConfig } from '../config.js';
 import { runErc, runDrc } from '../kicad/cli.js';
 import { formatViolations, type CheckReport } from '../kicad/report.js';
-import { checkDrift, type DriftMismatch } from '../memory/drift.js';
+import { checkDrift, emptySchematicWarning, type DriftMismatch } from '../memory/drift.js';
 import { loadConstraints, checkForbiddenPins, type ConstraintViolation } from '../memory/constraints.js';
 import { pinNets } from '../kicad/sexp.js';
 import { openspecValidate } from '../openspec/cli.js';
@@ -16,7 +16,7 @@ export interface CheckResult {
   ok: boolean;
   erc: { ok: boolean; violations: number } | null;
   drc: { ok: boolean; violations: number } | null;
-  drift: { ok: boolean; mismatches: DriftMismatch[] };
+  drift: { ok: boolean; mismatches: DriftMismatch[]; warning?: string };
   openspec: { ok: boolean; detail: string } | null;
   constraints: { ok: boolean; violations: ConstraintViolation[] };
 }
@@ -41,9 +41,15 @@ export async function runCheck(repoRoot: string, log: (s: string) => void): Prom
   }
 
   let drift: DriftMismatch[] = [];
+  let driftWarning: string | null = null;
   if (config.schematic && existsSync(path.join(repoRoot, config.schematic))) {
     drift = await checkDrift(repoRoot, config.docs, config.schematic);
     log(drift.length === 0 ? 'drift ✓' : drift.map((m) => `drift: ${m.doc} claims "${m.claim}" but actual is "${m.actual}"`).join('\n'));
+    // Informational, never a failure: the zero-symbol drift exemption is for
+    // bootstrap, but an established repo that lost its schematic content
+    // deserves a visible note rather than a silent green.
+    driftWarning = await emptySchematicWarning(repoRoot, config.docs, config.schematic);
+    if (driftWarning) log(`drift warning: ${driftWarning}`);
   }
 
   let openspec: { ok: boolean; detail: string } | null = null;
@@ -78,7 +84,7 @@ export async function runCheck(repoRoot: string, log: (s: string) => void): Prom
     ok,
     erc: erc ? { ok: erc.ok, violations: erc.violations.length } : null,
     drc: drc ? { ok: drc.ok, violations: drc.violations.length } : null,
-    drift: { ok: drift.length === 0, mismatches: drift },
+    drift: { ok: drift.length === 0, mismatches: drift, ...(driftWarning ? { warning: driftWarning } : {}) },
     openspec,
     constraints: { ok: constraintViolations.length === 0, violations: constraintViolations },
   };

package/src/commands/create.ts

@@ -1,8 +1,13 @@
 import path from 'node:path';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { loadConfig } from '../config.js';
-import { runAgentLoop } from '../agent/loop.js';
+import { listSymbols } from '../kicad/sexp.js';
+import { checkDrift } from '../memory/drift.js';
+import { runAgentLoop, type BudgetExhaustedStats } from '../agent/loop.js';
+import type { RunMetaInput } from '../agent/runmeta.js';
+import type { ProgressRenderer } from '../agent/render.js';
 import { openspecInit } from '../openspec/cli.js';
 import { runCheck } from './check.js';
 
@@ -51,14 +56,36 @@ export const STAGES: Stage[] = [
     name: 'schematic',
     isComplete: async (root) => {
       const config = await loadConfig(root);
-      return !!config.schematic && existsSync(path.join(root, config.schematic));
+      if (!config.schematic) return false;
+      const p = path.join(root, config.schematic);
+      if (!existsSync(p)) return false;
+      // Mere file existence is not completion: bootstrapping leaves a blank
+      // sheet on disk (a hand-scaffolded project, or the future fix for #19),
+      // and skipping this stage over a blank sheet cascades — layout and
+      // outputs then run against nothing. The stage's contract is "build the
+      // schematic from BOM.md", so completion means symbols exist AND the
+      // BOM/PINOUT tables agree with them (drift-clean); anything less keeps
+      // the stage active on the next resume so partial capture continues.
+      if (!(await listSymbols(p)).length) return false;
+      return (await checkDrift(root, config.docs, config.schematic)).length === 0;
     },
     prompt: () =>
       'Stage 4: schematic. Build the schematic sheet by sheet from BOM.md and SUBSYSTEMS.md. After each sheet, run run_erc and fix violations before moving on. Same net names and refdes everywhere. Update PINOUT.md as you assign pins; check the strapping table first.',
   },
   {
     name: 'layout-draft',
-    isComplete: (root, docs) => docHasContent(root, path.join(docs, 'LAYOUT.md'), '## Draft quality'),
+    isComplete: async (root, docs) => {
+      // The LAYOUT.md marker alone is not enough: `copperhead init` scaffolds
+      // LAYOUT.md with the literal "## Draft quality" heading, so an init-ed
+      // repo would skip this stage without a single footprint placed. Require
+      // a board with at least one footprint on it as well.
+      const config = await loadConfig(root);
+      if (!config.board) return false;
+      const p = path.join(root, config.board);
+      if (!existsSync(p)) return false;
+      if (!(await readFile(p, 'utf8')).includes('(footprint')) return false;
+      return docHasContent(root, path.join(docs, 'LAYOUT.md'), '## Draft quality');
+    },
     prompt: () =>
       'Stage 5: first-draft layout. Rule-driven placement written as real coordinates: connectors on edges, decoupling at IC pins, ESD at connectors, keepouts honored. Route power and short critical nets; leave the rest as ratsnest. Every routed net must pass run_drc. Then write the "## Draft quality" section in LAYOUT.md: exactly what is fine and what a human or specialist tool should redo. Non-optimal is acceptable; unlabeled non-optimal is not.',
   },
@@ -87,22 +114,31 @@ export interface CreateOptions {
   briefPath: string;
   model: string;
   interactive?: boolean;
+  /** Forwarded to each stage's run (attended continue-on-exhaustion prompt). */
+  onBudgetExhausted?: (stats: BudgetExhaustedStats) => Promise<number>;
   log: (s: string) => void;
+  renderer?: ProgressRenderer;
+  /** Command-level metadata; stage and brief identity are filled in per stage. */
+  meta?: Omit<RunMetaInput, 'stage' | 'brief'>;
 }
 
 export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; completed: string[] }> {
   const brief = await readFile(path.resolve(opts.briefPath), 'utf8');
+  // Hashed from the content already in hand: a brief edited mid-pipeline shows
+  // up as a different sha256 in the next stage's metadata (AC-8.1).
+  const briefMeta = { path: opts.briefPath, sha256: createHash('sha256').update(brief).digest('hex') };
   const config = await loadConfig(opts.repoRoot);
   await openspecInit(opts.repoRoot);
   const completed: string[] = [];
 
-  for (const stage of STAGES) {
+  for (const [i, stage] of STAGES.entries()) {
     if (await stage.isComplete(opts.repoRoot, config.docs)) {
       opts.log(`stage ${stage.name}: already complete (resuming past it)`);
       completed.push(stage.name);
       continue;
     }
     opts.log(`stage ${stage.name}: running`);
+    const stageTurns = config.stageMaxTurns?.[stage.name];
     const res = await runAgentLoop({
       repoRoot: opts.repoRoot,
       model: opts.model,
@@ -110,12 +146,33 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
       stagePrompt: stage.prompt(brief),
       interactive: opts.interactive ?? false,
       allowDirty: true, // stages build on each other's uncommitted state within the pipeline
+      ...(stageTurns !== undefined ? { maxTurns: stageTurns } : {}),
+      ...(opts.onBudgetExhausted ? { onBudgetExhausted: opts.onBudgetExhausted } : {}),
       log: opts.log,
+      ...(opts.renderer ? { renderer: opts.renderer } : {}),
+      meta: {
+        ...opts.meta,
+        command: 'create',
+        stage: { name: stage.name, index: i + 1, total: STAGES.length },
+        brief: briefMeta,
+      },
     });
     if (res.outcome !== 'success') {
       opts.log(`stage ${stage.name} did not complete (${res.outcome}); re-run copperhead create to resume here`);
       return { ok: false, completed };
     }
+    // A successful run is not the same as a completed stage: an agent can
+    // finish "done" with all gates green having only planned the work (seen
+    // with the schematic stage: one header edit, ERC "clean" on an empty
+    // sheet). Advancing anyway lets every later stage run against a design
+    // that isn't there, so hold the pipeline until this stage's repo-state
+    // contract is actually met.
+    if (!(await stage.isComplete(opts.repoRoot, config.docs))) {
+      opts.log(
+        `stage ${stage.name}: run succeeded but the stage contract is not met yet (partial work committed); re-run copperhead create to continue this stage`,
+      );
+      return { ok: false, completed };
+    }
     completed.push(stage.name);
   }
 

package/src/commands/sync.ts

@@ -7,6 +7,8 @@ import { loadConstraints, checkForbiddenPins } from '../memory/constraints.js';
 import { pinNets } from '../kicad/sexp.js';
 import { openspecValidate } from '../openspec/cli.js';
 import { runAgentLoop } from '../agent/loop.js';
+import type { RunMetaInput } from '../agent/runmeta.js';
+import type { ProgressRenderer } from '../agent/render.js';
 
 /**
  * `copperhead sync` (design D14): deterministic verify phase, then an optional
@@ -169,6 +171,7 @@ export async function syncResolve(
   report: SyncReport,
   model: string,
   log: (s: string) => void,
+  extras?: { renderer?: ProgressRenderer; meta?: RunMetaInput },
 ): Promise<{ ok: boolean }> {
   const reportText = formatSyncReport(report);
   const res = await runAgentLoop({
@@ -177,6 +180,8 @@ export async function syncResolve(
     request: 'resolve design-state inconsistencies found by copperhead sync',
     stagePrompt: `You are resolving drift found by the deterministic sync verifier. The inconsistency report is below. Truth precedence: the KiCad files are ground truth for as-built facts (fix the docs to match); openspec specs and SPEC.md budgets are ground truth for requirements. Do NOT touch anything listed as a requirement violation; those are for the human. Apply each proposed resolution, verify, and finish.\n\n${reportText}`,
     log,
+    ...(extras?.renderer ? { renderer: extras.renderer } : {}),
+    ...(extras?.meta ? { meta: extras.meta } : {}),
   });
   return { ok: res.outcome === 'success' };
 }

package/src/config.ts

@@ -8,6 +8,8 @@ export interface CopperheadConfig {
   docs: string;
   model: string | null;
   maxTurns: number;
+  /** Per-stage overrides for the create pipeline, keyed by stage name. */
+  stageMaxTurns?: Record<string, number>;
   maxRepairCycles: number;
   budgets: Record<string, number>;
   /** Content hashes of generated docs, for init idempotency (AC-1.4). */
@@ -34,20 +36,36 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
     return { schematic: null, board: null, ...DEFAULTS };
   }
   const raw = JSON.parse(await readFile(p, 'utf8')) as Partial<CopperheadConfig>;
+  // A zero/negative/non-integer stage budget would exhaust the stage on turn 0;
+  // drop such entries rather than let a config typo stall the pipeline.
+  const stageMaxTurns = Object.fromEntries(
+    Object.entries(raw.stageMaxTurns ?? {}).filter(([, v]) => Number.isInteger(v) && v > 0),
+  );
   return {
     schematic: raw.schematic ?? null,
     board: raw.board ?? null,
     docs: raw.docs ?? DEFAULTS.docs,
     model: raw.model ?? null,
     maxTurns: raw.maxTurns ?? DEFAULTS.maxTurns,
+    ...(Object.keys(stageMaxTurns).length ? { stageMaxTurns } : {}),
     maxRepairCycles: raw.maxRepairCycles ?? DEFAULTS.maxRepairCycles,
     budgets: raw.budgets ?? {},
     ...(raw.generatedHashes ? { generatedHashes: raw.generatedHashes } : {}),
   };
 }
 
+/** Which level of the model-selection precedence chain won. */
+export type ModelSource = 'flag' | 'env' | 'config' | 'openai-key' | 'anthropic-key';
+
+export interface ResolvedModel {
+  model: string;
+  source: ModelSource;
+}
+
 /**
  * Model selection precedence: flag > COPPERHEAD_MODEL > config > available key.
+ * The winning source is returned alongside the model so run metadata can
+ * record why a run used the model it did (AC-8.1/8.2).
  *
  * Accepted values (same set for `--model`, COPPERHEAD_MODEL, and `model` in
  * .copperhead/config.json):
@@ -65,12 +83,12 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
  * there. The chosen provider must have its key set: ANTHROPIC_API_KEY for
  * `claude*`, OPENAI_API_KEY otherwise.
  */
-export function resolveModel(flag: string | undefined, config: CopperheadConfig, env = process.env): string {
-  if (flag) return flag;
-  if (env.COPPERHEAD_MODEL) return env.COPPERHEAD_MODEL;
-  if (config.model) return config.model;
-  if (env.OPENAI_API_KEY) return 'gpt-5';
-  if (env.ANTHROPIC_API_KEY) return 'claude';
+export function resolveModel(flag: string | undefined, config: CopperheadConfig, env = process.env): ResolvedModel {
+  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' };
   throw new Error(
     'no model configured: pass --model, set COPPERHEAD_MODEL, set model in .copperhead/config.json, or provide OPENAI_API_KEY/ANTHROPIC_API_KEY',
   );

package/src/kicad/cli.ts

@@ -3,11 +3,18 @@ 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';
 
-export class KicadCliMissingError extends Error {
+export class KicadCliMissingError extends PreflightError {
   constructor() {
     super(
-      'kicad-cli not found on PATH. Install KiCad ≥ 8 (https://www.kicad.org/download/) and ensure kicad-cli is available.',
+      'kicad-cli not found on PATH',
+      'copperhead verifies every mutation with kicad-cli ERC/DRC; without it no edit can be checked, so no run can start',
+      [
+        'install KiCad ≥ 8: https://www.kicad.org/download/',
+        'ensure the kicad-cli binary is on PATH (on macOS it ships inside KiCad.app/Contents/MacOS)',
+        'confirm with "kicad-cli version", then rerun',
+      ],
     );
     this.name = 'KicadCliMissingError';
   }
@@ -32,16 +39,27 @@ async function runCheck(
   const out = path.join(dir, `${kind}.json`);
   const sub = kind === 'erc' ? ['sch', 'erc'] : ['pcb', 'drc'];
   try {
-    await execa(
+    const res = await execa(
       'kicad-cli',
       [...sub, '--format', 'json', '--exit-code-violations', '--output', out, ...extraArgs, filePath],
       { reject: false },
-    ).then((res) => {
-      if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
-        throw new KicadCliMissingError();
-      }
-    });
-    const raw = JSON.parse(await readFile(out, 'utf8'));
+    );
+    if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
+      throw new KicadCliMissingError();
+    }
+    let raw: unknown;
+    try {
+      raw = JSON.parse(await readFile(out, 'utf8'));
+    } catch {
+      // No report on disk means kicad-cli bailed before checking — usually the
+      // design file itself failed to load (syntax/schema corruption). The
+      // raw readFile ENOENT told the agent nothing actionable; kicad-cli's
+      // own output at least names the failure.
+      const detail = [res.stderr, res.stdout].filter(Boolean).join('\n').trim();
+      throw new Error(
+        `kicad-cli ${kind} produced no report — the ${kind === 'erc' ? 'schematic' : 'board'} file likely fails to load in KiCad. kicad-cli output: ${detail || '(none)'}`,
+      );
+    }
     return normalizeReport(raw, kind);
   } finally {
     await rm(dir, { recursive: true, force: true });
@@ -52,6 +70,39 @@ export function runErc(schPath: string): Promise<CheckReport> {
   return runCheck('erc', schPath);
 }
 
+/**
+ * Cheap loadability probe for a KiCad file: asks kicad-cli for a throwaway
+ * export and reports the failure text if the file won't load. Text edits on
+ * s-expression sources can silently corrupt the file; catching that at edit
+ * time (with KiCad's own error) beats an opaque failure at ERC/DRC time.
+ * Returns null when the file loads.
+ */
+/**
+ * Only schematics and boards have a cheap standalone load probe. Project
+ * files and symbol/footprint libraries do not: feeding them to a sch/pcb
+ * export "probe" would reject perfectly good files.
+ */
+export function isProbeableKicadFile(p: string): boolean {
+  return /\.kicad_(sch|pcb)$/.test(p);
+}
+
+export async function kicadLoadError(filePath: string): Promise<string | null> {
+  if (!isProbeableKicadFile(filePath)) return null;
+  const isSch = filePath.endsWith('.kicad_sch');
+  const dir = await mkdtemp(path.join(tmpdir(), 'copperhead-validate-'));
+  const args = isSch
+    ? ['sch', 'export', 'netlist', '--output', path.join(dir, 'probe.net'), filePath]
+    : ['pcb', 'export', 'pos', '--output', path.join(dir, 'probe.pos'), filePath];
+  try {
+    const res = await execa('kicad-cli', 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 {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
 export function runDrc(pcbPath: string): Promise<CheckReport> {
   return runCheck('drc', pcbPath);
 }