copperhead 0.10.0 → 0.11.0

package/src/capabilities/helpers.ts

@@ -0,0 +1,37 @@
+import { isKicadFile } from '../util/paths.js';
+import type { RunContext } from '../agent/context.js';
+
+export const str = (args: Record<string, unknown>, key: string): string => {
+  const v = args[key];
+  if (typeof v !== 'string' || v === '') throw new Error(`missing required string arg "${key}"`);
+  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").`;
+}
+
+export function markTouched(ctx: RunContext, rel: string): void {
+  ctx.filesTouched.add(rel);
+  if (isKicadFile(rel)) {
+    ctx.ledger.onKicadEdit(rel);
+    if (rel.endsWith('.kicad_sch')) ctx.lastErc = null;
+    if (rel.endsWith('.kicad_pcb')) ctx.lastDrc = null;
+  } else if (rel.endsWith('.md')) {
+    ctx.ledger.onDocEdit(rel);
+  }
+}

package/src/capabilities/index.ts

@@ -0,0 +1,53 @@
+import { outcomeResult, textResult, type ViewHint } from '../agent/envelope.js';
+import { defineTool, type CatalogEntry, type CatalogTool } from './define.js';
+import { HANDLERS } from './handlers.js';
+import generateReport from './skills/generate-report.js';
+
+export type { CatalogEntry, CatalogSkill, CatalogTool } from './define.js';
+export { defineTool, defineSkill } from './define.js';
+
+const HINT: Record<string, ViewHint> = {
+  read_file: 'query',
+  search: 'query',
+  list_symbols: 'query',
+  list_nets: 'query',
+  propose_change: 'mutation',
+  validate_change: 'diagnostic',
+  edit_file: 'mutation',
+  write_file: 'mutation',
+  run_erc: 'diagnostic',
+  search_symbols: 'query',
+  symbol_pins: 'query',
+  verify_symbols: 'diagnostic',
+  draft_schematic: 'mutation',
+  score_schematic: 'diagnostic',
+  check_legibility: 'diagnostic',
+  run_drc: 'diagnostic',
+  export_svg: 'export',
+  export_outputs: 'export',
+  check_drift: 'diagnostic',
+  record_constraint: 'mutation',
+  resolve_affected: 'mutation',
+  record_decision: 'mutation',
+  finish: 'diagnostic',
+};
+
+function wrap(def: (typeof HANDLERS)[number]): CatalogTool {
+  const viewHint = HINT[def.schema.name];
+  if (!viewHint) throw new Error(`missing viewHint for ${def.schema.name}`);
+  return defineTool({
+    schema: def.schema,
+    version: 1,
+    viewHint,
+    gate: def.requiresUnlock ? (ctx) => ctx.editsUnlocked : () => true,
+    handler: async (ctx, args) => {
+      const result = await def.handler(ctx, args);
+      return typeof result === 'string'
+        ? textResult(result, viewHint)
+        : outcomeResult(result.text, result.ok, viewHint);
+    },
+  });
+}
+
+/** Tools from HANDLERS + every skill module imported below (conformance checks skills/). */
+export const catalog: CatalogEntry[] = [...HANDLERS.map(wrap), generateReport];

package/src/capabilities/skills/generate-report.ts

@@ -0,0 +1,25 @@
+import { defineSkill } from '../define.js';
+
+export default defineSkill({
+  schema: {
+    name: 'generate_report',
+    description:
+      'Read-only report of the current design: ERC, DRC (if a board exists), drift, nets, and an optional SVG path. Does not edit files.',
+    parameters: {
+      type: 'object',
+      properties: { scope: { type: 'string', enum: ['power', 'all'], description: 'Report scope (default all)' } },
+      required: [],
+    },
+  },
+  version: 1,
+  viewHint: 'diagnostic',
+  tools: ['read_file', 'search', 'list_nets', 'run_erc', 'run_drc', 'export_svg', 'check_drift'],
+  maxTurns: 8,
+  prompt: (_ctx, args) => `You are generating a read-only design report (scope: ${args.scope === 'power' ? 'power' : 'all'}).
+Call the available tools to gather ERC, DRC (only if a board is configured; otherwise skip), drift, and the net list. Optionally export an SVG of the schematic.
+Do not edit any file. Do not call finish. When you have those results, stop calling tools.`,
+  isComplete: (ctx) =>
+    (!ctx.config.schematic || ctx.lastErc !== null) &&
+    (!ctx.config.board || ctx.lastDrc !== null) &&
+    (!ctx.config.schematic || ctx.lastDrift != null),
+});

package/src/cli.ts

@@ -226,13 +226,19 @@ const scoreGroup = program
 scoreGroup
   .command('schematic')
   .description('legibility and layout score for the schematic')
-  .action(async () => {
+  .option('--file <path>', 'score this .kicad_sch instead of the configured schematic (any sheet, no repo needed)')
+  .action(async (opts: { file?: string }) => {
     const repo = repoOf(program.opts());
     const json = Boolean(program.opts().json);
     try {
       const { loadConfig } = await import('./config.js');
       const { scoreSchematic, formatScore } = await import('./kicad/score.js');
       const path = await import('node:path');
+      if (opts.file) {
+        const report = await scoreSchematic(path.resolve(opts.file), { docsDir: null });
+        console.log(json ? JSON.stringify(report, null, 2) : formatScore(report));
+        process.exit(0);
+      }
       const config = await loadConfig(repo);
       if (!config.schematic) {
         console.error('no schematic configured in .copperhead/config.json');
@@ -311,6 +317,60 @@ program
     },
   );
 
+const skillCmd = program.command('skill').description('run a registered skill (nested tool loop; no git commit)');
+
+skillCmd
+  .command('list')
+  .description('list registered skills (LLM-free, network-free)')
+  .action(async () => {
+    const repo = repoOf(program.opts());
+    try {
+      const { listSkills } = await import('./commands/skill.js');
+      const skills = await listSkills(repo);
+      if (program.opts().json) console.log(JSON.stringify(skills, null, 2));
+      else {
+        for (const s of skills) {
+          console.log(`${s.available ? '·' : '×'} ${s.name.replaceAll('_', '-')}  ${s.description.split('\n')[0]}`);
+        }
+      }
+      process.exit(0);
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
+
+skillCmd
+  .command('run')
+  .description('run a skill by name (generate-report)')
+  .argument('<name>', 'skill name (kebab or underscore)')
+  .option('--model <model>', 'codex | cursor | gpt-5 | claude | claude-code | compat:<id>')
+  .option('--scope <scope>', 'generate-report scope: power | all', 'all')
+  .action(async (name: string, opts: { model?: string; scope?: string }) => {
+    const repo = repoOf(program.opts());
+    const json = Boolean(program.opts().json);
+    // `process.exit` skips pending finally blocks, so the provider close has to
+    // finish before the exit call — hence the code is carried out, not exited on.
+    let code = 1;
+    try {
+      const { runSkillCli, providerForSkillRun } = await import('./commands/skill.js');
+      const { provider } = await providerForSkillRun(repo, opts.model);
+      const res = await runSkillCli({
+        repoRoot: repo,
+        name,
+        args: { scope: opts.scope === 'power' ? 'power' : 'all' },
+        provider,
+        json,
+      });
+      console.log(res.text);
+      code = res.code;
+    } catch (err) {
+      console.error((err as Error).message);
+      code = 1;
+    }
+    process.exit(code);
+  });
+
 program
   .command('sync')
   .description('verify the whole design state for inconsistencies and resolve drift')
@@ -347,6 +407,29 @@ program
     }
   });
 
+program
+  .command('mcp')
+  .description('EXPERIMENTAL: serve the gated pipeline to MCP hosts over stdio (unstable surface)')
+  // `--repo` is also a global flag, but a host config reads as
+  // `args: ["mcp", "--repo", "/path"]`, so the command accepts it locally too.
+  .option('--repo <path>', 'target repository (default: cwd)')
+  .action(async (opts: { repo?: string }) => {
+    const repo = repoOf(opts.repo ? { repo: opts.repo } : program.opts());
+    try {
+      // Imported lazily, like `skill`: the MCP SDK and zod are a ~150ms load
+      // that every other command — including the pre-commit `check` — would
+      // otherwise pay, and a resolution failure here would take down the whole
+      // CLI rather than just this command.
+      const { startMcpServer } = await import('./mcp/server.js');
+      // Never returns until the host closes stdio. Nothing is printed to
+      // stdout here or anywhere downstream: it carries JSON-RPC alone.
+      await startMcpServer({ repoRoot: repo });
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('demo')
   .description('tour of what copperhead does, or run the USB-C breakout create pipeline')

package/src/commands/create.ts

@@ -239,7 +239,7 @@ export const STAGES: Stage[] = [
       return true;
     },
     prompt: () =>
-      'Stage 4: schematic. An empty KiCad project has already been scaffolded and wired into .copperhead/config.json. You author INTENT, never geometry: write the netlist-intent IR and call draft_schematic — the deterministic engine computes every coordinate, wire, label, power symbol, and group box, and the sheet it draws satisfies the drafting standard by construction (captioned group boxes per SUBSYSTEMS.md subsystem, left-to-right flow, rails up and grounds down, net labels between groups, filled title block). The IR (schematic.intent.json) is JSON: {"version": 1, "parts": [{"ref", "libId", "value", "footprint", "group"}], "nets": [{"name", "pins": ["REF.PIN", …], "kind"?}], "noConnect": ["REF.PIN", …], "hints"?: {"groupOrder"?, "paper"?, "date"?}}. Build it from BOM.md (same refdes and values — validation cross-checks and refuses mismatches) and SUBSYSTEMS.md (every non-power part names one subsystem heading as its group). Use exact canonical KiCad lib_ids (e.g. Device:R) and REAL pin numbers from the library: the pin dossier below (when present) already lists every BOM part\'s installed symbol and its real pins — work from it and from symbol_pins rather than reading .kicad_sym files, and validation lists a part\'s actual pins when you name one that does not exist. Declare every deliberately unused pin in noConnect; power rails are recognized from pin types automatically (override with "kind" only when the inference is wrong — the draft report lists every net\'s resolved class). Pass the full IR as intent_json to draft_schematic; the report embeds the legibility findings and the score for the fresh sheet. To repair ANY finding (ERC, legibility, validation), fix the IR and call draft_schematic again — edit_file is refused on the drafted sheet. Text-collision findings scale with TEXT LENGTH: a net label, part value, or SUBSYSTEMS heading that is shorter draws a smaller box, so renaming a colliding net (and updating PINOUT.md) or tightening a long heading is a real repair lever; paper size and declaration order are not (placement is grid-derived). When the draft is clean run run_erc and check_drift, update PINOUT.md to match the IR\'s pin assignments, and finish.',
+      'Stage 4: schematic. An empty KiCad project has already been scaffolded and wired into .copperhead/config.json. You author INTENT, never geometry: write the netlist-intent IR and call draft_schematic — the deterministic engine computes every coordinate, wire, label, power symbol, and group box, and the sheet it draws satisfies the drafting standard by construction (captioned group boxes per SUBSYSTEMS.md subsystem, left-to-right flow, rails up and grounds down, net labels between groups, filled title block). The IR (schematic.intent.json) is JSON: {"version": 1, "parts": [{"ref", "libId", "value", "footprint", "group"}], "nets": [{"name", "pins": ["REF.PIN", …], "kind"?}], "noConnect": ["REF.PIN", …], "hints"?: {"groupOrder"?, "paper"?, "date"?}}. Build it from BOM.md (same refdes and values — validation cross-checks and refuses mismatches) and SUBSYSTEMS.md (every non-power part names one subsystem heading as its group). Use exact canonical KiCad lib_ids (e.g. Device:R) and REAL pin numbers from the library: the pin dossier below (when present) already lists every BOM part\'s installed symbol and its real pins — work from it and from symbol_pins rather than reading .kicad_sym files, and validation lists a part\'s actual pins when you name one that does not exist. Name nets as a reader expects: a bus or interface shares a prefix (I2S_BCLK, I2S_DIN, I2S_LRCLK; SPI_…; BTN_…) so the drawing colours the family together, differential pairs end in +/- or P/N, and part values carry their unit (F, H, R). Declare every deliberately unused pin in noConnect; power rails are recognized from pin types automatically (override with "kind" only when the inference is wrong — the draft report lists every net\'s resolved class). Pass the full IR as intent_json to draft_schematic; the report embeds the legibility findings and the score for the fresh sheet. To repair ANY finding (ERC, legibility, validation), fix the IR and call draft_schematic again — edit_file is refused on the drafted sheet. Text-collision findings scale with TEXT LENGTH: a net label, part value, or SUBSYSTEMS heading that is shorter draws a smaller box, so renaming a colliding net (and updating PINOUT.md) or tightening a long heading is a real repair lever; paper size and declaration order are not (placement is grid-derived). When the draft is clean run run_erc and check_drift, update PINOUT.md to match the IR\'s pin assignments, and finish.',
   },
   {
     name: 'layout-draft',
@@ -905,9 +905,12 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
       // 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 the completion contract is the real gate.
+      // The run's own reason rides along: the diagnosis transcript excerpt holds
+      // only assistant text and tool results, so without it a hung call or a turn
+      // stopped at the hard cap reaches the diagnosis as a bare "provider-error".
       const failure =
         res.outcome !== 'success'
-          ? `the run ended as "${res.outcome}" (${res.exitPath})`
+          ? `the run ended as "${res.outcome}" (${res.exitPath})${res.summary ? `: ${res.summary}` : ''}`
           : !(await stage.isComplete(opts.repoRoot, config.docs))
             ? await contractGapDetail(stage.name, opts.repoRoot, config)
             : null;

package/src/commands/doctor.ts

@@ -13,7 +13,7 @@ import {
   type CompatSettings,
   type CopperheadConfig,
 } from '../config.js';
-import { kicadCliVersion } from '../kicad/cli.js';
+import { kicadCliVersion, MIN_KICAD_MAJOR } from '../kicad/cli.js';
 import { redactSecrets } from '../util/redact.js';
 import { isNotFoundError } from '../util/preflight.js';
 
@@ -85,15 +85,46 @@ function nodeCheck(version: string): DoctorCheck {
   };
 }
 
+// MIN_KICAD_MAJOR (imported from kicad/cli.ts) enforces the minimum supported KiCad version for ERC/DRC.
+// Behaviour note: kicadCheck() returns status: 'fail' (exit non-zero) for any
+// kicad-cli version below this threshold, and for output that contains no
+// parseable N.N version token. This is intentional user-visible behaviour and
+// is NOT a no-op hint correction: users on KiCad 7 will see doctor fail where
+// it previously succeeded. The gate mirrors the README's stated requirement and
+// follows the same pattern as MIN_NODE_MAJOR above.
+
 async function kicadCheck(probe: () => Promise<string>): Promise<DoctorCheck> {
   try {
-    return { name: 'kicad-cli', status: 'ok', detail: await probe() };
+    const raw = await probe();
+    // Anchored match: require a version-shaped token at the start of a line so
+    // an incidental N.N elsewhere in stdout (e.g. "OpenGL 3.2 unsupported")
+    // does not shadow the real KiCad version. The `m` flag makes ^ match
+    // line-starts within a multi-line string.
+    const match = raw.match(/(?:^|\n)\s*(?:kicad-cli\s+)?v?(\d+)\.\d+/m);
+    const major = match ? Number(match[1]) : NaN;
+    if (!Number.isFinite(major)) {
+      return {
+        name: 'kicad-cli',
+        status: 'fail',
+        detail: raw || 'could not parse version',
+        hint: `copperhead needs KiCad >= ${MIN_KICAD_MAJOR}; install or configure a compatible kicad-cli.`,
+      };
+    }
+    if (major < MIN_KICAD_MAJOR) {
+      return {
+        name: 'kicad-cli',
+        status: 'fail',
+        detail: `${raw} (< ${MIN_KICAD_MAJOR})`,
+        hint: `copperhead needs KiCad >= ${MIN_KICAD_MAJOR}; upgrade KiCad (https://www.kicad.org/download/).`,
+      };
+    }
+    return { name: 'kicad-cli', status: 'ok', detail: raw };
   } catch {
     return {
       name: 'kicad-cli',
       status: 'fail',
       detail: 'not found on PATH',
-      hint: 'install KiCad >= 9 (bundles kicad-cli); ERC/DRC gates need it.',
+      hint: 'install KiCad >= 8 (bundles kicad-cli); ERC/DRC gates need it.',
     };
   }
 }

package/src/commands/skill.ts

@@ -0,0 +1,127 @@
+import { loadConfig, resolveModel } from '../config.js';
+import { flatten, type ToolResult } from '../agent/envelope.js';
+import { makeProvider } from '../agent/loop.js';
+import { dispatchToolResult, registry, type RunContext } from '../agent/tools.js';
+import type { Provider } from '../agent/types.js';
+import { Transcript } from '../agent/transcript.js';
+import { ObligationsLedger } from '../agent/ledger.js';
+
+export class SkillCliError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SkillCliError';
+  }
+}
+
+export function catalogNameFromCli(name: string): string {
+  return name.replace(/-/g, '_');
+}
+
+export async function listSkills(repoRoot: string): Promise<{ name: string; available: boolean; description: string }[]> {
+  const ctx = await minimalCtx(repoRoot, false);
+  const listed = new Set(registry.list(ctx).map((e) => e.name));
+  return registry.skills().map((s) => ({
+    name: s.name,
+    available: listed.has(s.name),
+    description: s.schema.description,
+  }));
+}
+
+export async function runSkill(opts: {
+  repoRoot: string;
+  name: string;
+  args?: Record<string, unknown>;
+  provider: Provider;
+}): Promise<ToolResult> {
+  const catalogName = catalogNameFromCli(opts.name);
+  const entry = registry.get(catalogName);
+  if (!entry || entry.kind !== 'skill') throw new SkillCliError(`unknown skill "${opts.name}"`);
+  const ctx = await minimalCtx(opts.repoRoot);
+  if (!registry.list(ctx).some((e) => e.name === catalogName)) {
+    throw new SkillCliError(`skill "${opts.name}" is not available in this repo`);
+  }
+  return dispatchToolResult(ctx, entry.name, opts.args ?? {}, { provider: opts.provider });
+}
+
+export async function providerForSkillRun(repoRoot: string, modelFlag?: string): Promise<{ provider: Provider; model: string }> {
+  const config = await loadConfig(repoRoot);
+  try {
+    const { model } = resolveModel(modelFlag, config);
+    return { provider: await makeProvider(model), model };
+  } catch (err) {
+    const msg = (err as Error).message;
+    throw new SkillCliError(
+      msg.includes('no model') || msg.includes('API_KEY') || msg.includes('configured')
+        ? `${msg} — skill run needs OPENAI_API_KEY, ANTHROPIC_API_KEY, or --model for a saved-login provider (codex, claude-code, cursor).`
+        : msg,
+    );
+  }
+}
+
+export function formatSkillEnvelope(result: ToolResult, json: boolean): string {
+  if (json) return JSON.stringify(result, null, 2);
+  const body = flatten(result);
+  return result.ok ? body : `error: ${body}`;
+}
+
+/**
+ * One skill run plus the provider's lifecycle. A saved-login provider owns a
+ * `mkdtemp` working directory (and, on some backends, an in-flight subprocess);
+ * `runAgentLoop` closes it in a `finally` because leaving it behind orphans the
+ * process and fills the disk (I8). `skill run` has no agent loop to inherit that
+ * from, so the close lives here — around the throw path too, since an unknown or
+ * unavailable skill must not leak the provider it already built. Returns the text
+ * to print and the exit code, so the CLI's only job is `console.log` + `exit`.
+ */
+export async function runSkillCli(opts: {
+  repoRoot: string;
+  name: string;
+  args?: Record<string, unknown>;
+  provider: Provider;
+  json: boolean;
+  warn?: (line: string) => void;
+}): Promise<{ text: string; code: number }> {
+  try {
+    const result = await runSkill({
+      repoRoot: opts.repoRoot,
+      name: opts.name,
+      ...(opts.args ? { args: opts.args } : {}),
+      provider: opts.provider,
+    });
+    return { text: formatSkillEnvelope(result, opts.json), code: result.ok ? 0 : 1 };
+  } finally {
+    try {
+      await opts.provider.close?.();
+    } catch (err) {
+      (opts.warn ?? ((l: string) => console.error(l)))(
+        `warning: ${opts.provider.name} provider cleanup failed (${(err as Error).message})`,
+      );
+    }
+  }
+}
+
+async function minimalCtx(repoRoot: string, initializeTranscript = true): Promise<RunContext> {
+  const transcript = new Transcript(repoRoot);
+  if (initializeTranscript) await transcript.init();
+  return {
+    repoRoot,
+    config: await loadConfig(repoRoot),
+    transcript,
+    ledger: new ObligationsLedger(),
+    runId: 'skill',
+    interactive: false,
+    confirm: async () => true,
+    editsUnlocked: false,
+    changeId: null,
+    proposalValidated: false,
+    filesTouched: new Set(),
+    decisions: [],
+    lastErc: null,
+    lastDrc: null,
+    lastLegibility: null,
+    lastScore: null,
+    lastDrift: null,
+    repairCycles: 0,
+    finishRequest: null,
+  };
+}

package/src/commands/sync.ts

@@ -6,7 +6,7 @@ import { checkDrift } from '../memory/drift.js';
 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 { runAgentLoop, type RunResult } from '../agent/loop.js';
 import type { RunMetaInput } from '../agent/runmeta.js';
 import type { ProgressRenderer } from '../agent/render.js';
 
@@ -172,7 +172,7 @@ export async function syncResolve(
   model: string,
   log: (s: string) => void,
   extras?: { renderer?: ProgressRenderer; meta?: RunMetaInput },
-): Promise<{ ok: boolean }> {
+): Promise<{ ok: boolean; run: RunResult }> {
   const reportText = formatSyncReport(report);
   const res = await runAgentLoop({
     repoRoot,
@@ -183,5 +183,7 @@ export async function syncResolve(
     ...(extras?.renderer ? { renderer: extras.renderer } : {}),
     ...(extras?.meta ? { meta: extras.meta } : {}),
   });
-  return { ok: res.outcome === 'success' };
+  // The full RunResult travels with the verdict so a non-CLI caller (the MCP
+  // server) can report the transcript path and files touched the way `do` does.
+  return { ok: res.outcome === 'success', run: res };
 }

package/src/config.ts

@@ -35,9 +35,20 @@ export interface CopperheadConfig {
   stageMaxTurns?: Record<string, number>;
   maxRepairCycles: number;
   budgets: Record<string, number>;
-  /** Per-turn watchdog (ms). A provider turn exceeding this is aborted and
-   * retried, so a hung call can't stall the run forever. <=0 disables it. */
+  /** Per-turn inactivity watchdog (ms). A provider turn that goes this long
+   * without a response or any streamed progress is treated as hung: aborted and
+   * retried, so a hung call can't stall the run forever. A streaming provider
+   * restarts it on every progress event, so a long turn that keeps producing
+   * output is not killed; a provider that reports no progress gets it as a
+   * whole-turn deadline. <=0 disables it. */
   turnTimeoutMs: number;
+  /** Hard cap (ms) on one provider turn that is producing output, however much
+   * progress it reports. A turn that hits it is too large, not hung, so it fails
+   * without a retry: resending the identical request would only run into the cap
+   * again. It is never shorter than turnTimeoutMs, and a turn that has reported
+   * no progress is judged by turnTimeoutMs alone. <=0 disables it; when unset it
+   * defaults to 3600000, or to disabled when turnTimeoutMs is disabled. */
+  turnMaxMs: number;
   /** How often (ms) to emit a liveness heartbeat while a provider turn is in
    * flight, so a slow large-output turn is distinguishable from a hung one
    * (5.1). Fires only after the first interval, so quick turns stay silent.
@@ -79,13 +90,17 @@ export const DEFAULTS: Omit<CopperheadConfig, 'schematic' | 'board'> = {
   maxTurns: 40,
   maxRepairCycles: 5,
   budgets: {},
-  // 10 min. A single large capture turn (a full lib_symbols + instances edit,
-  // ~40k output tokens) on the claude-code provider legitimately runs several
-  // minutes; the old 5-min deadline killed those mid-flight and, because the
-  // watchdog budget is spent per stage, could fail a stage that was only slow,
-  // not hung. 10 min clears the largest observed turns while still catching a
-  // genuinely stuck subprocess.
+  // 10 min without a response or progress. A single large capture turn (a full
+  // lib_symbols + instances edit, ~40k output tokens) on the claude-code
+  // provider legitimately runs several minutes; the old 5-min whole-turn
+  // deadline killed those mid-flight. Some turns run past 10 min too, so the
+  // deadline restarts on every streamed progress event: it bounds a silent
+  // stretch, not the turn's length. A provider that cannot stream still gets it
+  // as a whole-turn deadline, so no turn that finished in time before times out now.
   turnTimeoutMs: 600000,
+  // 60 min: the backstop for a turn that keeps streaming. Far past the largest
+  // observed turns, while a runaway generation still ends in bounded time.
+  turnMaxMs: 3600000,
   // 30s: within one interval an operator knows a turn is alive, and a full
   // 10-min turn emits ~20 lines — enough to distinguish slow from hung without
   // flooding the log. Quick turns (< 30s) emit nothing.
@@ -119,6 +134,15 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
     maxRepairCycles: raw.maxRepairCycles ?? DEFAULTS.maxRepairCycles,
     budgets: raw.budgets ?? {},
     turnTimeoutMs: typeof raw.turnTimeoutMs === 'number' ? raw.turnTimeoutMs : DEFAULTS.turnTimeoutMs,
+    // A repo that switched the turn watchdog off gets no default cap either:
+    // before the cap existed that meant no deadline at all, and a default must
+    // not quietly bring one back. An explicit turnMaxMs still applies.
+    turnMaxMs:
+      typeof raw.turnMaxMs === 'number'
+        ? raw.turnMaxMs
+        : typeof raw.turnTimeoutMs === 'number' && raw.turnTimeoutMs <= 0
+          ? 0
+          : DEFAULTS.turnMaxMs,
     heartbeatMs: typeof raw.heartbeatMs === 'number' ? raw.heartbeatMs : DEFAULTS.heartbeatMs,
     maxStageRetries:
       Number.isInteger(raw.maxStageRetries) && (raw.maxStageRetries as number) >= 0