copperhead 0.5.0 → 0.7.0

package/src/agent/recovery.ts

@@ -0,0 +1,162 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { Msg, Provider } from './types.js';
+
+/** Thrown when a single provider turn blows past its watchdog deadline. */
+export class TurnTimeoutError extends Error {
+  constructor(public readonly ms: number) {
+    super(`turn exceeded ${ms}ms without responding`);
+    this.name = 'TurnTimeoutError';
+  }
+}
+
+/**
+ * Race `fn()` against a deadline so a hung provider call cannot stall the run
+ * forever. On timeout, `onTimeout` runs (tear down the in-flight call, e.g.
+ * provider.close()) and the returned promise rejects with TurnTimeoutError; the
+ * caller decides whether to retry or fail. `ms <= 0` (or non-finite) disables the
+ * watchdog and just awaits `fn()`.
+ */
+export async function withTimeout<T>(
+  fn: () => Promise<T>,
+  ms: number,
+  onTimeout?: () => void | Promise<void>,
+): Promise<T> {
+  if (!Number.isFinite(ms) || ms <= 0) return fn();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      void Promise.resolve(onTimeout?.()).catch(() => {});
+      reject(new TurnTimeoutError(ms));
+    }, ms);
+  });
+  try {
+    return await Promise.race([fn(), timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export interface StageDiagnosis {
+  verdict: 'retry' | 'abort';
+  reason: string;
+  /** When retrying: concrete instructions to prepend to the next attempt. */
+  guidance?: string;
+  /** Tokens the diagnosis call itself spent, so the pipeline can fold them into
+   *  the stage's cost total (F6). Absent when the call threw before a response. */
+  usage?: { inputTokens: number; outputTokens: number };
+}
+
+/** Extract the first brace-balanced JSON object from text, tolerating quoting and
+ * escaping, and interpret it as a StageDiagnosis. Anything unparseable is treated
+ * as "abort" so an ambiguous diagnosis never loops the pipeline forever. */
+export function parseDiagnosis(text: string | null): StageDiagnosis {
+  if (!text) return { verdict: 'abort', reason: 'no diagnosis produced' };
+  const start = text.indexOf('{');
+  if (start >= 0) {
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = start; i < text.length; i++) {
+      const ch = text[i];
+      if (inStr) {
+        if (esc) esc = false;
+        else if (ch === '\\') esc = true;
+        else if (ch === '"') inStr = false;
+        continue;
+      }
+      if (ch === '"') inStr = true;
+      else if (ch === '{') depth++;
+      else if (ch === '}' && --depth === 0) {
+        try {
+          const o = JSON.parse(text.slice(start, i + 1)) as Partial<StageDiagnosis>;
+          const verdict = o.verdict === 'retry' ? 'retry' : 'abort';
+          return {
+            verdict,
+            reason: typeof o.reason === 'string' ? o.reason : 'no reason given',
+            ...(verdict === 'retry' && typeof o.guidance === 'string' && o.guidance.trim()
+              ? { guidance: o.guidance.trim() }
+              : {}),
+          };
+        } catch {
+          break;
+        }
+      }
+    }
+  }
+  return { verdict: 'abort', reason: 'diagnosis was not valid JSON' };
+}
+
+/** Compact, most-recent-last excerpt of a run's transcript for the diagnostician:
+ * the last assistant message and the last few tool results, truncated. */
+export async function transcriptExcerpt(transcriptDir: string, maxChars = 4000): Promise<string> {
+  const p = path.join(transcriptDir, 'transcript.jsonl');
+  if (!existsSync(p)) return '(no transcript)';
+  let lines: string[];
+  try {
+    lines = (await readFile(p, 'utf8')).trim().split('\n');
+  } catch {
+    return '(transcript unreadable)';
+  }
+  const parts: string[] = [];
+  for (const line of lines.slice(-12)) {
+    try {
+      const e = JSON.parse(line) as { type: string; data?: Record<string, unknown> };
+      if (e.type === 'assistant' && typeof e.data?.text === 'string' && e.data.text) {
+        parts.push(`[assistant] ${e.data.text}`);
+      } else if (e.type === 'tool') {
+        parts.push(`[${String(e.data?.name)}] ${String(e.data?.result ?? '').split('\n')[0]}`);
+      }
+    } catch {
+      /* skip */
+    }
+  }
+  const joined = parts.join('\n');
+  return joined.length > maxChars ? joined.slice(joined.length - maxChars) : joined;
+}
+
+/**
+ * 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
+ * pipeline runs on), so no extra credentials or config are needed. Any error or
+ * ambiguity resolves to "abort" — recovery must fail safe toward reporting to the
+ * human rather than looping.
+ */
+export async function diagnoseStageFailure(
+  provider: Provider,
+  input: {
+    stageName: string;
+    stageGoal: string;
+    failure: string;
+    excerpt: string;
+    attempt: number;
+    maxAttempts: number;
+  },
+): Promise<StageDiagnosis> {
+  const system =
+    'You are the recovery supervisor for an automated KiCad PCB-design pipeline. ' +
+    'A stage just failed or ended without meeting its completion contract. Judge whether ' +
+    'another automated attempt is likely to succeed, or whether a human should intervene. ' +
+    'Be decisive and terse.';
+  const user =
+    `Stage: ${input.stageName}\n` +
+    `Stage goal: ${input.stageGoal}\n` +
+    `Failure: ${input.failure}\n` +
+    `This was attempt ${input.attempt} of ${input.maxAttempts}.\n\n` +
+    `Recent transcript (most recent last):\n${input.excerpt}\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).';
+  const messages: Msg[] = [
+    { role: 'system', content: system },
+    { role: 'user', content: user },
+  ];
+  try {
+    const turn = await provider.chat(messages, []);
+    return { ...parseDiagnosis(turn.text), usage: turn.usage };
+  } catch (e) {
+    return { verdict: 'abort', reason: `diagnosis call failed: ${(e as Error).message}` };
+  }
+}

package/src/agent/render.ts

@@ -12,6 +12,14 @@ export interface ProgressRenderer {
   toolResult(name: string, firstLine: string): void;
   /** Busy text while a provider call is in flight; null when idle. */
   status(text: string | null): void;
+  /**
+   * Liveness signal emitted periodically while a provider turn is in flight
+   * (5.1): distinguishes a slow turn from a hung one. `elapsedMs` is time since
+   * this turn's provider call began; `streamedChars` is cumulative streamed
+   * output (0 when the provider doesn't stream — the elapsed time still tells
+   * the operator the turn is alive).
+   */
+  heartbeat(info: { elapsedMs: number; streamedChars: number }): void;
   /** Final outcome line; replaces the status line in interactive mode. */
   finish(line: string): void;
 }
@@ -41,6 +49,11 @@ export function plainRenderer(log: (line: string) => void): ProgressRenderer {
     turnStart: (turn, maxTurns, tokensIn, tokensOut) => log(turnMarker(turn, maxTurns, tokensIn, tokensOut)),
     toolResult: (name, firstLine) => log(`  [${name}] ${firstLine}`),
     status: () => {},
+    heartbeat: ({ elapsedMs, streamedChars }) =>
+      log(
+        `  … still working — ${fmtDuration(elapsedMs)} elapsed` +
+          (streamedChars ? `, ~${fmtTokens(streamedChars)} chars streamed` : ' (no output yet)'),
+      ),
     finish: (line) => log(line),
   };
 }
@@ -68,6 +81,7 @@ export class InteractiveRenderer implements ProgressRenderer {
   private maxTurns = 0;
   private tokensIn = 0;
   private tokensOut = 0;
+  private streamedChars = 0;
   private busy: string | null = null;
   private frame = 0;
   private timer: ReturnType<typeof setInterval> | null = null;
@@ -97,7 +111,11 @@ export class InteractiveRenderer implements ProgressRenderer {
       `${fmtTokens(this.tokensIn)} in / ${fmtTokens(this.tokensOut)} out`,
       fmtDuration(Date.now() - this.startMs),
     ];
-    if (this.busy) parts.push(this.busy);
+    if (this.busy) {
+      // Fold streamed-output volume into the busy segment so a large turn's
+      // status line visibly grows — a hung one stays frozen (5.1).
+      parts.push(this.streamedChars ? `${this.busy} ~${fmtTokens(this.streamedChars)} ch` : this.busy);
+    }
     const spinner = this.busy ? FRAMES[this.frame % FRAMES.length] : '·';
     const line = `${spinner} ${parts.join(' · ')}`;
     const width = this.out.columns ?? 80;
@@ -138,6 +156,7 @@ export class InteractiveRenderer implements ProgressRenderer {
     this.maxTurns = maxTurns;
     this.tokensIn = tokensIn;
     this.tokensOut = tokensOut;
+    this.streamedChars = 0; // per-turn: reset so last turn's volume doesn't linger
     this.ensureTimer();
     this.redraw();
   }
@@ -148,10 +167,18 @@ export class InteractiveRenderer implements ProgressRenderer {
 
   status(text: string | null): void {
     this.busy = text;
+    if (!text) this.streamedChars = 0; // turn's provider call ended
     if (text && !this.idle) this.ensureTimer();
     this.redraw();
   }
 
+  heartbeat({ streamedChars }: { elapsedMs: number; streamedChars: number }): void {
+    // The spinner timer already advances elapsed time in place; the heartbeat's
+    // job here is to fold in the latest streamed-output volume and redraw.
+    this.streamedChars = streamedChars;
+    this.redraw();
+  }
+
   finish(line: string): void {
     if (this.statusShown) this.out.write(CLEAR_LINE);
     this.out.write(line + '\n');

package/src/agent/response-cache.ts

@@ -0,0 +1,80 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { ChatOpts, Msg, Provider, ToolSchema, Turn } from './types.js';
+
+/**
+ * Wraps a provider so each turn's `(messages, tools) -> Turn` is written to disk
+ * and replayed on an identical later call. This makes the pipeline cheap and
+ * fast to recover: a stage that is retried after a transient failure (a timed-out
+ * turn, a crash, an auto-retry) replays the responses it already paid for, from
+ * turn 1 up to the point where the inputs first diverge, instead of re-calling
+ * the model. When a retry deliberately changes the prompt (e.g. diagnosis
+ * guidance is appended), the input hash changes and the model is called fresh —
+ * so caching never pins a run to a stale, failing response.
+ *
+ * Best-effort by construction: a cache miss or any I/O error falls through to the
+ * live provider, and a hit reports zero token usage (the real spend was zero).
+ * The key is a content hash of the full message history and the advertised tool
+ * names, so any change to the conversation or available tools is a fresh call.
+ */
+export class CachingProvider implements Provider {
+  readonly name: string;
+  private hits = 0;
+
+  /** Turns served from the on-disk cache so far (5.2: per-stage cache-hit%). */
+  get cacheHits(): number {
+    return this.hits;
+  }
+
+  constructor(
+    private readonly inner: Provider,
+    private readonly dir: string,
+    private readonly log?: (s: string) => void,
+    /** The concrete model id this run resolved to (e.g. `claude-code:opus`), used
+     *  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,
+  ) {
+    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) }))
+      .digest('hex');
+  }
+
+  async chat(messages: Msg[], tools: ToolSchema[], opts?: ChatOpts): Promise<Turn> {
+    const file = path.join(this.dir, `${this.keyFor(messages, tools)}.json`);
+    if (existsSync(file)) {
+      try {
+        const cached = JSON.parse(await readFile(file, 'utf8')) as Turn;
+        this.hits++;
+        this.log?.(`llm-cache: replayed a cached response (hit #${this.hits}, no tokens spent)`);
+        // Report zero usage: replaying a cached turn costs nothing.
+        return { ...cached, usage: { inputTokens: 0, outputTokens: 0 } };
+      } catch {
+        // corrupt/partial cache file — fall through and regenerate
+      }
+    }
+    const turn = await this.inner.chat(messages, tools, opts);
+    try {
+      await mkdir(this.dir, { recursive: true });
+      // Keep the cache out of git entirely (and out of failed-run stashes): a
+      // `*` .gitignore in the cache dir hides every entry, so the cache persists
+      // across runs without ever dirtying the tree.
+      const ignore = path.join(this.dir, '.gitignore');
+      if (!existsSync(ignore)) await writeFile(ignore, '*\n', 'utf8');
+      await writeFile(file, JSON.stringify(turn), 'utf8');
+    } catch {
+      // best-effort: caching must never break a run
+    }
+    return turn;
+  }
+
+  async close(): Promise<void> {
+    await this.inner.close?.();
+  }
+}

package/src/agent/tools.ts

@@ -6,6 +6,7 @@ import { resolveInRepo, isKicadFile } from '../util/paths.js';
 import { runErc, runDrc, exportSvg, exportFab, kicadLoadError, isProbeableKicadFile } from '../kicad/cli.js';
 import { formatViolations, type CheckReport } from '../kicad/report.js';
 import { listSymbols, listNets } from '../kicad/sexp.js';
+import { verifySchematicSymbols } from '../kicad/symlib.js';
 import { checkDrift } from '../memory/drift.js';
 import { saveConstraint, classifyAffectsTarget, affectsTargetExists } from '../memory/constraints.js';
 import { openspecValidate } from '../openspec/cli.js';
@@ -52,6 +53,24 @@ const str = (args: Record<string, unknown>, key: string): string => {
   return v;
 };
 
+// U+FFFD (the Unicode replacement character) is what a byte sequence becomes
+// when UTF-8 decoding fails — most often a multibyte glyph (Ω, µ, ±, °) split
+// across a streaming chunk boundary and decoded per-chunk upstream in the
+// provider SDK (I2). It never appears in a legitimately authored PCB doc, so
+// its presence in a content-bearing tool arg means the value arrived corrupted.
+// Reject the call before it lands on disk so the model re-emits; the corruption
+// is nondeterministic (it depends on where a chunk boundary fell), so the retry
+// almost always comes through clean — far cheaper than shipping a mangled value
+// like "5.1kΩ" → "5.1k�" into DECISIONS.md and only noticing on review.
+const REPLACEMENT_CHAR = '�';
+export function corruptionError(fields: Record<string, unknown>): string | null {
+  const bad = Object.entries(fields)
+    .filter(([, v]) => typeof v === 'string' && v.includes(REPLACEMENT_CHAR))
+    .map(([k]) => k);
+  if (!bad.length) return null;
+  return `rejected: the ${bad.join(', ')} value contains U+FFFD (�), the replacement character that signals a UTF-8 decoding error — a special character (e.g. Ω, µ, ±, °) was likely mangled in transit. Re-send this exact call with the intended character written correctly, or spell it in ASCII (e.g. "ohm", "uF", "+/-", "deg").`;
+}
+
 function markTouched(ctx: RunContext, rel: string): void {
   ctx.filesTouched.add(rel);
   if (isKicadFile(rel)) {
@@ -202,7 +221,7 @@ export const TOOLS: ToolDef[] = [
     schema: {
       name: 'edit_file',
       description:
-        'Exact-match anchored replace in an existing file. The anchor must be unique; widen it with surrounding lines if not. For renames, pass replace_all: true to replace every occurrence in one call.',
+        'Exact-match anchored replace in an existing file. Requires a validated change proposal first (call propose_change then validate_change to unlock edits; both may be in the same reply, before this call). The anchor must be unique; widen it with surrounding lines if not. For renames, pass replace_all: true to replace every occurrence in one call.',
       parameters: {
         type: 'object',
         properties: {
@@ -216,6 +235,8 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: true,
     handler: async (ctx, args) => {
+      const corrupt = corruptionError({ new_string: args.new_string });
+      if (corrupt) return corrupt;
       const rel = str(args, 'path');
       const abs = resolveInRepo(ctx.repoRoot, rel);
       // Text edits can corrupt an s-expression file in ways the editor cannot
@@ -256,7 +277,8 @@ export const TOOLS: ToolDef[] = [
   {
     schema: {
       name: 'write_file',
-      description: 'Create a new file (docs, outputs). Refuses to overwrite anything or to create KiCad files.',
+      description:
+        'Create a new file (docs, outputs). Requires a validated change proposal first (propose_change then validate_change to unlock edits). Refuses to overwrite anything or to create KiCad files.',
       parameters: {
         type: 'object',
         properties: { path: { type: 'string' }, content: { type: 'string' } },
@@ -265,6 +287,8 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: true,
     handler: async (ctx, args) => {
+      const corrupt = corruptionError({ content: args.content });
+      if (corrupt) return corrupt;
       const rel = str(args, 'path');
       const res = await toolWriteFile(ctx.repoRoot, rel, args.content as string);
       markTouched(ctx, rel);
@@ -281,11 +305,43 @@ export const TOOLS: ToolDef[] = [
     handler: async (ctx) => {
       if (!ctx.config.schematic)
         return 'no schematic configured; ERC does not apply yet — skip it until a schematic exists and is set in .copperhead/config.json';
-      const report = await runErc(path.join(ctx.repoRoot, ctx.config.schematic));
+      const schPath = path.join(ctx.repoRoot, ctx.config.schematic);
+      const report = await runErc(schPath);
       ctx.lastErc = report;
       if (report.ok) ctx.ledger.clear('erc');
       else ctx.repairCycles++;
-      return formatViolations(report);
+      const out = formatViolations(report);
+      // A zero-symbol schematic passes ERC with 0 violations — a false green
+      // (3.2) that lets a premature finish look verified (an empty sheet also
+      // passes drift). The stage contract already requires symbols>0, but a bare
+      // "ERC clean" on the empty starting sheet still misleads the model, so warn
+      // here too: no gate should read as satisfied by the empty starting state.
+      if (report.ok && !(await listSymbols(schPath)).length) {
+        return `${out}\nwarning: ERC is clean but the schematic has ZERO symbols — an empty sheet always passes ERC, so this is NOT a verified design. Capture the parts from BOM.md (and re-run run_erc) before calling finish.`;
+      }
+      return out;
+    },
+  },
+  {
+    schema: {
+      name: 'verify_symbols',
+      description:
+        "Cross-check every lib_symbols entry in the schematic against the KiCad symbol library installed on this machine. Reports pins that diverge from the real part (wrong count, name, or electrical type) and lib_ids that do not exist in the current KiCad version (with the closest real names). ERC cannot catch these — a symbol whose lib_id claims to be a canonical part but whose pins are wrong passes ERC while being wrong. Run this after capturing symbols and reconcile every finding.",
+      parameters: { type: 'object', properties: {}, required: [] },
+    },
+    requiresUnlock: false,
+    handler: async (ctx) => {
+      if (!ctx.config.schematic)
+        return 'no schematic configured; verify_symbols does not apply yet';
+      const { findings, checked, skipped } = await verifySchematicSymbols(
+        path.join(ctx.repoRoot, ctx.config.schematic),
+      );
+      if (!findings.length) {
+        return `verify_symbols: ${checked} symbol(s) match the installed KiCad library. No divergences.`;
+      }
+      const lines = findings.map((f) => `  - [${f.kind}] ${f.detail}`);
+      const mismatches = findings.filter((f) => f.kind !== 'no-library').length;
+      return `verify_symbols: ${checked} verified, ${skipped} unverifiable (library not installed), ${mismatches} issue(s) to reconcile:\n${lines.join('\n')}`;
     },
   },
   {
@@ -514,6 +570,8 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: true,
     handler: async (ctx, args) => {
+      const corrupt = corruptionError({ decision: args.decision, rationale: args.rationale, affects: args.affects });
+      if (corrupt) return corrupt;
       const decision = str(args, 'decision');
       const rationale = str(args, 'rationale');
       const affects = (args.affects as string | undefined) ?? '';

package/src/agent/transcript.ts

@@ -12,6 +12,7 @@ export type ExitPath =
   | 'repair-cycles-exhausted'
   | 'commit-failed'
   | 'provider-error'
+  | 'session-limit'
   | 'stalled';
 
 /** Post-run addenda recorded at every terminal branch (AC-8.5). */

package/src/agent/types.ts

@@ -8,6 +8,7 @@ export interface ToolCall {
   id: string;
   name: string;
   args: Record<string, unknown>;
+  extra?: Record<string, unknown>;
 }
 
 export type Msg =
@@ -20,10 +21,27 @@ export interface Turn {
   text: string | null;
   toolCalls: ToolCall[];
   usage: { inputTokens: number; outputTokens: number };
+  /**
+   * A one-line steer for a turn that produced NO tool call but clearly *intended*
+   * one — e.g. a fenced ```json block that names a real tool yet fails to parse
+   * (unbalanced braces). The loop surfaces it in place of the generic
+   * "continue using tools" nudge so the model fixes the malformed call instead of
+   * misreading the silence as a broken tool (#I10). Providers that can't detect
+   * a near-miss simply never set it.
+   */
+  nudge?: string;
 }
 
 export interface ChatOpts {
   maxTokens?: number;
+  /**
+   * Liveness callback for the loop's heartbeat (5.1). A streaming provider calls
+   * it as output arrives, passing the cumulative streamed-output length in chars,
+   * so a slow turn can be told apart from a hung one. Providers that don't stream
+   * simply never call it (the heartbeat still reports elapsed time). Never used
+   * for billing — real token usage is reported once, on the returned Turn.
+   */
+  onStream?: (streamedChars: number) => void;
 }
 
 export interface Provider {

package/src/cli.ts

@@ -8,6 +8,14 @@ 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 {
+  runExportBom,
+  parseSupplier,
+  parseBoards,
+  parseSpares,
+  ExportError,
+} from './commands/export.js';
+import { DEFAULT_BOARDS, DEFAULT_SPARES } from './kicad/bom-export.js';
 import { runAgentLoop, type BudgetExhaustedStats } from './agent/loop.js';
 import { makeRenderer } from './agent/render.js';
 import { kicadCliVersion } from './kicad/cli.js';
@@ -117,7 +125,7 @@ program
   .command('do')
   .description('the core loop: propose, edit, verify, propagate, commit')
   .argument('<request>', 'the change request in natural language')
-  .option('--model <model>', 'codex | gpt-5 | claude (or a provider-specific model id)')
+  .option('--model <model>', 'codex | gpt-5 | claude | claude-code (or a provider-specific model id)')
   .option('--max-turns <n>', 'turn budget for this run')
   .option('--allow-dirty', 'allow a dirty tree (snapshot via git stash create)')
   .option('--dry-run', 'propose the diff, write nothing')
@@ -195,7 +203,7 @@ program
   .command('create')
   .description('Mode A: full pipeline from a product brief to the output package')
   .requiredOption('--brief <file>', 'product brief (markdown)')
-  .option('--model <model>', 'codex | gpt-5 | claude')
+  .option('--model <model>', 'codex | gpt-5 | claude | claude-code (or a provider-specific model id)')
   .option('--interactive', 're-enable the human gates (spec approval, pre-export)')
   .action(async (opts: { brief: string; model?: string; interactive?: boolean }) => {
     const repo = repoOf(program.opts());
@@ -221,6 +229,48 @@ program
     }
   });
 
+const exportCmd = program
+  .command('export')
+  .description('emit supplier-ready files from repo state (deterministic; no LLM, no network)');
+
+exportCmd
+  .command('bom')
+  .description('write a supplier-format BOM (jlcpcb | digikey | mouser) from docs/BOM.md')
+  .requiredOption('--supplier <name>', 'jlcpcb | digikey | mouser')
+  .option('--boards <n>', 'number of boards to order', String(DEFAULT_BOARDS))
+  .option('--spares <percent>', 'spare parts percentage', String(DEFAULT_SPARES))
+  .option('--include-unverified', 'include UNVERIFIED rows that carry an MPN (never MPN-less rows)')
+  .action(async (opts: { supplier: string; boards: string; spares: string; includeUnverified?: boolean }) => {
+    const repo = repoOf(program.opts());
+    const json = Boolean(program.opts().json);
+    try {
+      const supplier = parseSupplier(opts.supplier);
+      const boards = parseBoards(opts.boards);
+      const spares = parseSpares(opts.spares);
+      const res = await runExportBom({
+        repoRoot: repo,
+        supplier,
+        boards,
+        spares,
+        includeUnverified: opts.includeUnverified ?? false,
+      });
+      // Warnings go to stderr so a `> file` redirect of stdout stays clean and
+      // the excluded-rows report is still seen.
+      for (const w of res.warnings) console.error(w);
+      if (json) {
+        console.log(JSON.stringify(res, null, 2));
+      } else {
+        console.log(`wrote ${res.outPath} (${res.included.length} part(s), ${res.excluded.length} excluded)`);
+      }
+      process.exit(0);
+    } catch (err) {
+      // ExportError carries an actionable message (bad flag, missing BOM, drift);
+      // anything else is unexpected. Both exit non-zero with no stack trace.
+      console.error(err instanceof ExportError ? err.message : (err as Error).message);
+      process.exit(1);
+    }
+  });
+
 program.parseAsync().catch((err: Error) => {
   console.error(err.message);
   process.exit(1);