copperhead 0.6.0 → 0.7.0

package/dist/util/git.js

@@ -1,9 +1,43 @@
 import { execa } from 'execa';
-import { cp, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { PreflightError } from './preflight.js';
+/**
+ * Paths copperhead must keep out of `git add -A`. KiCad ≥9 writes a
+ * git-backed local-history directory (`.history/`, complete with its own nested
+ * `.git`) into the project the first time kicad-cli touches it. Left untracked,
+ * that nested repo has an unborn HEAD, so a plain `git add -A` in the parent
+ * aborts with `error: '.history/' does not have a commit checked out` (exit
+ * 128) — which fails the commit at the end of every KiCad-touching stage
+ * (schematic, layout, outputs). Ignoring it is both correct (local history is
+ * never a project artifact) and the fix for that abort. Kept as a list so other
+ * KiCad transients can join it if they surface.
+ */
+const GIT_ADD_EXCLUDES = ['.history/'];
+/**
+ * Ensure the repo's root .gitignore lists each entry, appending only the
+ * missing ones. Idempotent and best-effort: a failure here must never block a
+ * commit, so it swallows its own errors. Run before any `git add -A` so a
+ * git-backed KiCad `.history/` (or similar nested repo) is skipped instead of
+ * aborting the add.
+ */
+export async function ensureIgnored(repo, entries) {
+    try {
+        const p = path.join(repo, '.gitignore');
+        const text = existsSync(p) ? await readFile(p, 'utf8') : '';
+        const present = new Set(text.split('\n').map((l) => l.trim()));
+        const missing = entries.filter((e) => !present.has(e));
+        if (!missing.length)
+            return;
+        const prefix = text.length && !text.endsWith('\n') ? '\n' : '';
+        await writeFile(p, text + prefix + missing.join('\n') + '\n', 'utf8');
+    }
+    catch {
+        // best-effort: .gitignore maintenance must never be the thing that fails a run
+    }
+}
 async function git(repo, args) {
     const { stdout } = await execa('git', args, { cwd: repo });
     return stdout.trim();
@@ -130,6 +164,7 @@ export async function preserveFailedRun(repo, runId) {
     try {
         if (!(await isDirty(repo)))
             return null;
+        await ensureIgnored(repo, GIT_ADD_EXCLUDES);
         // Never leave the audit trail staged: a staged-but-not-in-HEAD path is
         // deleted by restore()'s `reset --hard`, which silently defeats its
         // `clean -e .copperhead/runs` protection (that flag only spares untracked
@@ -162,6 +197,7 @@ export async function uncommittedCount(repo) {
     return status ? status.split('\n').length : 0;
 }
 export async function commitAll(repo, message) {
+    await ensureIgnored(repo, GIT_ADD_EXCLUDES);
     await git(repo, ['add', '-A']);
     await git(repo, ['commit', '-m', message]);
     return git(repo, ['rev-parse', 'HEAD']);

package/dist/util/git.js.map

@@ -1 +1 @@
-{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/util/git.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/util/git.ts"],"names":[],"mappings":"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"}

package/dist/util/preflight.js

@@ -1,3 +1,4 @@
+import { statfs } from 'node:fs/promises';
 /**
  * A run-blocking environment failure. Distinct from a mid-run error: nothing
  * has been written yet, so the message alone is the whole user experience.
@@ -21,4 +22,40 @@ export function formatPreflightFailure(reason, why, remedy) {
     const steps = remedy.map((step, i) => `  ${i + 1}. ${step}`);
     return [reason, '', `why it failed: ${why}`, 'to fix:', ...steps].join('\n');
 }
+/** Default minimum free space to start a run: 2 GiB. A create run emits gerbers,
+ *  STEP, SVG renders and KiCad local history; 2 GiB is comfortably above a
+ *  single board's output while still catching a nearly-full disk. */
+export const DEFAULT_MIN_FREE_BYTES = 2 * 1024 * 1024 * 1024;
+const gib = (n) => `${(n / 1024 / 1024 / 1024).toFixed(1)} GiB`;
+/**
+ * Free bytes available to this (unprivileged) user on the filesystem holding
+ * `dir`, or null when the platform/Node build cannot report it — callers treat
+ * null as "unknown" and skip the check rather than blocking a legitimate run.
+ */
+export async function freeDiskBytes(dir) {
+    try {
+        const fs = await statfs(dir);
+        return fs.bavail * fs.bsize;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Refuse to start when free disk is below `minFreeBytes` (4.1). A long run can
+ * fill the disk mid-stage — gerbers/STEP/SVG plus unbounded KiCad local history
+ * — and then fail with an opaque `ENOSPC` after doing real, expensive work. A
+ * preflight fails fast with an actionable message instead. An unknown reading
+ * (unsupported platform) skips the check.
+ */
+export async function assertDiskSpace(dir, minFreeBytes = DEFAULT_MIN_FREE_BYTES) {
+    const free = await freeDiskBytes(dir);
+    if (free === null || free >= minFreeBytes)
+        return;
+    throw new PreflightError(`not enough free disk space to start (${gib(free)} available, ${gib(minFreeBytes)} required)`, 'a create run writes fabrication outputs and KiCad local history and can fill the disk mid-stage, failing with an opaque ENOSPC only after doing real work', [
+        'free up space on the volume holding this repo',
+        'or lower the threshold with COPPERHEAD_MIN_FREE_MB (e.g. COPPERHEAD_MIN_FREE_MB=500)',
+        'then re-run',
+    ]);
+}
 //# sourceMappingURL=preflight.js.map

package/dist/util/preflight.js.map

@@ -1 +1 @@
-{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../../src/util/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAE5B;IACA;IACA;IAHX,YACW,MAAc,EACd,GAAW,EACX,MAAgB;QAEzB,KAAK,CAAC,sBAAsB,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;QAJ1C,WAAM,GAAN,MAAM,CAAQ;QACd,QAAG,GAAH,GAAG,CAAQ;QACX,WAAM,GAAN,MAAM,CAAU;QAGzB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,GAAW,EAAE,MAAgB;IAClF,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,MAAM,EAAE,EAAE,EAAE,kBAAkB,GAAG,EAAE,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/E,CAAC"}
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../../src/util/preflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAE5B;IACA;IACA;IAHX,YACW,MAAc,EACd,GAAW,EACX,MAAgB;QAEzB,KAAK,CAAC,sBAAsB,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;QAJ1C,WAAM,GAAN,MAAM,CAAQ;QACd,QAAG,GAAH,GAAG,CAAQ;QACX,WAAM,GAAN,MAAM,CAAU;QAGzB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,GAAW,EAAE,MAAgB;IAClF,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,MAAM,EAAE,EAAE,EAAE,kBAAkB,GAAG,EAAE,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/E,CAAC;AAED;;qEAEqE;AACrE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE7D,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;AAEhF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW;IAC7C,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,OAAO,EAAE,CAAC,MAAM,GAAG,EAAE,CAAC,KAAK,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW,EAAE,YAAY,GAAG,sBAAsB;IACtF,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,IAAI,YAAY;QAAE,OAAO;IAClD,MAAM,IAAI,cAAc,CACtB,wCAAwC,GAAG,CAAC,IAAI,CAAC,eAAe,GAAG,CAAC,YAAY,CAAC,YAAY,EAC7F,2JAA2J,EAC3J;QACE,+CAA+C;QAC/C,sFAAsF;QACtF,aAAa;KACd,CACF,CAAC;AACJ,CAAC"}

package/dist/util/retry.js

@@ -3,6 +3,29 @@ export function isRateLimit(err) {
         ?? err?.statusCode;
     return status === 429;
 }
+/**
+ * Detect a saved-login SESSION / USAGE limit (claude-code, codex), distinct from
+ * an HTTP 429 rate limit and from a code bug (2.4, I13). It is not a transient
+ * blip to back off on: it names its own reset time and clears only then. Because
+ * every completed turn is already in `.copperhead/llm-cache/`, re-running after
+ * the reset replays them at ~0 tokens and resumes in place — so the right
+ * handling is a schedulable pause with the reset time surfaced, not a bare
+ * "provider error". Returns the parsed reset time (verbatim) or null when the
+ * error is not a session/usage limit.
+ */
+export function sessionLimit(err) {
+    const status = err?.status
+        ?? err?.statusCode;
+    if (status === 429)
+        return null; // a real rate limit: handled by backoff, not a pause
+    const msg = err?.message ?? '';
+    if (!/(session|usage|weekly)\s+limit|hit your .*limit|reached your usage|limit .*reset/i.test(msg)) {
+        return null;
+    }
+    // "resets 1:40pm", "resets at 1:40 pm", "reset at 13:40" — capture the clock text.
+    const reset = msg.match(/reset[s]?(?:\s+at)?\s+([0-9]{1,2}(?::[0-9]{2})?\s*(?:am|pm)?)/i);
+    return { resetsAt: reset?.[1]?.trim() ?? null };
+}
 /** Exponential backoff ×N for rate limits (SPEC §4.5). */
 export async function withRetry(fn, opts = {}) {
     const retries = opts.retries ?? 3;

package/dist/util/retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/util/retry.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,MAAM,MAAM,GAAI,GAAgD,EAAE,MAAM;WAClE,GAA+B,EAAE,UAAU,CAAC;IAClD,OAAO,MAAM,KAAK,GAAG,CAAC;AACxB,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,EAAoB,EAAE,OAAkB,EAAE;IAC3E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;IACnC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5E,IAAI,OAAgB,CAAC;IACrB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,GAAG,GAAG,CAAC;YACd,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK,OAAO;gBAAE,MAAM,GAAG,CAAC;YACxD,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;YACjC,MAAM,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IACD,MAAM,OAAO,CAAC;AAChB,CAAC"}
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/util/retry.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,MAAM,MAAM,GAAI,GAAgD,EAAE,MAAM;WAClE,GAA+B,EAAE,UAAU,CAAC;IAClD,OAAO,MAAM,KAAK,GAAG,CAAC;AACxB,CAAC;AAQD;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,MAAM,GAAI,GAAgD,EAAE,MAAM;WAClE,GAA+B,EAAE,UAAU,CAAC;IAClD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC,CAAC,qDAAqD;IACtF,MAAM,GAAG,GAAI,GAAa,EAAE,OAAO,IAAI,EAAE,CAAC;IAC1C,IAAI,CAAC,mFAAmF,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnG,OAAO,IAAI,CAAC;IACd,CAAC;IACD,mFAAmF;IACnF,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,gEAAgE,CAAC,CAAC;IAC1F,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC;AAClD,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,EAAoB,EAAE,OAAkB,EAAE;IAC3E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;IACnC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5E,IAAI,OAAgB,CAAC;IACrB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,GAAG,GAAG,CAAC;YACd,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK,OAAO;gBAAE,MAAM,GAAG,CAAC;YACxD,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;YACjC,MAAM,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IACD,MAAM,OAAO,CAAC;AAChB,CAAC"}

package/dist/util/tmp.js

@@ -0,0 +1,119 @@
+import { readdir, stat, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+/** Newest local-history entries to keep when capping `.history/` (see
+ *  pruneHistoryDir). Enough to preserve a useful recovery window, bounded enough
+ *  that the dir cannot grow without limit across a long run. */
+export const DEFAULT_HISTORY_KEEP = 200;
+/**
+ * Cap the growth of a repo's `.history/` directory (4.1). KiCad (and editor
+ * local-history) rewrite a snapshot on every project touch, so across a long
+ * run `.history/` grows without bound and was a contributor to the disk-fill
+ * halt (I8). It is gitignored, so its contents are disposable: keep the newest
+ * `keepNewest` files by mtime and remove the rest. Recursive (local history
+ * mirrors the workspace tree), best-effort (every error is swallowed — pruning
+ * housekeeping must never fail a run), and a no-op when the dir is absent or
+ * already under the cap. Returns the number of files removed.
+ */
+export async function pruneHistoryDir(repoRoot, keepNewest = DEFAULT_HISTORY_KEEP) {
+    const root = path.join(repoRoot, '.history');
+    const files = [];
+    const walk = async (dir) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable dir — skip it
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                await walk(full);
+            }
+            else if (e.isFile()) {
+                try {
+                    const st = await stat(full);
+                    files.push({ full, mtimeMs: st.mtimeMs });
+                }
+                catch {
+                    // stat race — skip this file
+                }
+            }
+        }
+    };
+    await walk(root);
+    if (files.length <= keepNewest)
+        return 0;
+    files.sort((a, b) => b.mtimeMs - a.mtimeMs); // newest first
+    let removed = 0;
+    for (const f of files.slice(keepNewest)) {
+        try {
+            await rm(f.full, { force: true });
+            removed++;
+        }
+        catch {
+            // permission/race — leave it, keep pruning the rest
+        }
+    }
+    return removed;
+}
+/**
+ * Every scratch dir copperhead makes under the OS temp dir shares this prefix:
+ * kicad-cli ERC/DRC (`copperhead-`), the KiCad edit probe (`copperhead-validate-`),
+ * the failed-run backup (`copperhead-runs-`), and the provider working dirs
+ * (`copperhead-cc-`, `copperhead-codex-`). Each site removes its own dir in a
+ * `finally`, but a watchdog SIGKILL of the process tree or a hard abort skips
+ * that cleanup, so stale dirs accumulate across runs and can eventually fill the
+ * disk (I8). A prefix match lets one sweep reclaim all of them.
+ */
+export const TEMP_PREFIX = 'copperhead-';
+/** Default staleness cutoff for the startup sweep: 2h. Safe even for multi-hour
+ * runs (10-min turns × per-stage retries × 8 stages): a live run's only
+ * long-lived scratch dir is the provider's reused cwd, which is `utimes`-touched
+ * every turn (ClaudeCodeProvider.ensureCwd), so its mtime never goes stale while
+ * the process is alive; per-call kicad-cli dirs are removed within a turn. A dir
+ * older than this therefore belongs to a dead run, and the window is short enough
+ * that such a leak is reclaimed on the very next invocation. */
+export const DEFAULT_STALE_MS = 2 * 60 * 60 * 1000;
+/**
+ * Remove leaked `copperhead-*` scratch dirs left in the OS temp dir by earlier
+ * runs whose `finally` cleanup was skipped (watchdog kill / hard abort). Only
+ * dirs whose mtime is older than `maxAgeMs` are removed, so a concurrent run's
+ * fresh scratch dirs are never touched. Best-effort: every error is swallowed
+ * (a temp dir we can't stat or remove is not worth failing a run over), and the
+ * function returns the paths it removed so a caller can log the reclaim.
+ *
+ * `now` is injected so the behaviour is deterministically testable; callers pass
+ * `Date.now()`.
+ */
+export async function sweepStaleTempDirs(now, maxAgeMs = DEFAULT_STALE_MS) {
+    const root = tmpdir();
+    const removed = [];
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        return removed; // no temp dir / not readable — nothing to sweep
+    }
+    for (const name of entries) {
+        if (!name.startsWith(TEMP_PREFIX))
+            continue;
+        const full = path.join(root, name);
+        try {
+            const st = await stat(full);
+            if (!st.isDirectory())
+                continue;
+            if (now - st.mtimeMs < maxAgeMs)
+                continue; // too fresh: could be a live run
+            await rm(full, { recursive: true, force: true });
+            removed.push(full);
+        }
+        catch {
+            // stat/rm race or permission issue — skip this entry, keep sweeping.
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=tmp.js.map

package/dist/util/tmp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmp.js","sourceRoot":"","sources":["../../src/util/tmp.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copperhead",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Cursor for circuit boards: an AI agent that designs, documents, and validates real PCBs on KiCad repositories",
   "license": "Apache-2.0",
   "author": "Animesh Chouhan <animeshchouhan@outlook.com>",

package/src/agent/loop.ts

@@ -3,15 +3,17 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { execa } from 'execa';
 import type { Msg, Provider, Turn } from './types.js';
 import { availableTools, dispatchTool, type RunContext } from './tools.js';
+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, type CopperheadConfig } from '../config.js';
+import { loadConfig, CONFIG_DIR, 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';
 import { ObligationsLedger } from './ledger.js';
 import { gitPreflight, isDirty, snapshot, restore, commitAll, changedFiles, preserveFailedRun } from '../util/git.js';
-import { withRetry, isRateLimit } from '../util/retry.js';
+import { withRetry, isRateLimit, sessionLimit } from '../util/retry.js';
 import { openspecArchive } from '../openspec/cli.js';
 import { existsSync } from 'node:fs';
 import { OpenAIProvider } from './providers/openai.js';
@@ -63,9 +65,14 @@ export interface RunResult {
   transcriptDir: string;
   filesTouched: string[];
   commit: string | null;
+  /** Cost/telemetry for this run. Surfaced by the create pipeline's per-stage
+   *  cost table (5.2) so the expensive stages are obvious across runs. */
+  stats: RunStats;
+  /** Number of turns served from the on-disk response cache (5.2). */
+  cacheHits: number;
 }
 
-export async function makeProvider(model: string): Promise<Provider> {
+export async function makeProvider(model: string, sessionResume = false): Promise<Provider> {
   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>"');
@@ -91,7 +98,7 @@ export async function makeProvider(model: string): Promise<Provider> {
     if (claudeCodeModel === '') {
       throw new Error('claude-code model override cannot be empty; use "claude-code" or "claude-code:<model-id>"');
     }
-    return new ClaudeCodeProvider(claudeCodeModel);
+    return new ClaudeCodeProvider(claudeCodeModel, undefined, undefined, sessionResume);
   }
   if (model === 'claude' || model.startsWith('claude')) {
     return new AnthropicProvider(model === 'claude' ? undefined : model);
@@ -198,8 +205,23 @@ async function runWithMemory(
     finishRequest: null,
   };
 
-  let provider = opts.provider ?? (await makeProvider(opts.model));
+  // Session resume for claude-code (1.1) is only correct when the response cache
+  // is off: the cache replays turns a resumed session never saw. So enable 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));
+  // 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);
+  }
   providers.add(provider);
+  // Held separately from `provider` (which is reassigned on failover) so the
+  // final cache-hit count survives a mid-run provider switch (5.2).
+  const cachingProvider = provider instanceof CachingProvider ? provider : null;
+  const cacheHits = (): number => cachingProvider?.cacheHits ?? 0;
 
   // Deterministic, LLM-free metadata block: collected once, rendered onto all
   // three surfaces (run-start event, summary ## Environment, CLI header) so
@@ -277,6 +299,8 @@ async function runWithMemory(
   const perTurn: { turn: number; in: number; out: number }[] = [];
   let plan: string | null = null;
   let nudges = 0;
+  let turnTimeouts = 0;
+  const maxTurnTimeouts = 3;
 
   const stats = (exitPath: ExitPath): RunStats => ({
     exitPath,
@@ -356,6 +380,8 @@ async function runWithMemory(
       transcriptDir: transcript.dir,
       filesTouched: [],
       commit: null,
+      stats: runStats,
+      cacheHits: cacheHits(),
     };
   };
 
@@ -388,15 +414,64 @@ async function runWithMemory(
       await transcript.event('budget-extended', { extraTurns: extra, budget, ...exhaustStats });
       log(`turn budget extended by ${extra} (now ${budget})`);
     }
+    // Advertise EVERY tool each turn; dispatchTool enforces the edit-unlock gate
+    // live at call time. Hiding locked edit tools from the turn catalog meant a
+    // model that unlocked (validate_change) and edited in the SAME reply had its
+    // edit silently dropped in parsing — the call named a tool the turn had not
+    // advertised, so it was treated as prose, executed nothing, and returned no
+    // error. The model then "verified" against an unchanged file (an empty
+    // schematic even passes ERC) and finished believing it had succeeded.
+    // Structural lock (SPEC.md §1.3 invariant 1): the edit tools stay OUT of the
+    // advertised list until a proposal validates (`editsUnlocked`), so the model
+    // is gated by omission, not by prompt text. `dispatchTool` re-checks the same
+    // `availableTools(ctx)` live, so this is defense in depth. A premature edit is
+    // simply not offered; once `validate_change` unlocks, the next turn advertises
+    // the edit tools. (Earlier this advertised every tool to let a same-turn
+    // propose→validate→edit batch through, but that traded the spec's structural
+    // guarantee for one saved turn — not worth it.)
     const tools = availableTools(ctx).map((t) => t.schema);
     r.turnStart(turn + 1, maxTurns, tokensIn, tokensOut);
     r.status('thinking');
     let res: Turn;
+    // Liveness heartbeat (5.1): a large-output turn can legitimately run several
+    // minutes, which is otherwise indistinguishable from a hung subprocess until
+    // the watchdog fires. Emit a periodic elapsed/streamed signal so an operator
+    // can tell the two apart. Fires only after the first interval, so quick turns
+    // stay silent; `unref` keeps it from holding the event loop open.
+    const turnStartMs = Date.now();
+    let streamedChars = 0;
+    const heartbeat =
+      config.heartbeatMs > 0
+        ? setInterval(
+            () => r.heartbeat({ elapsedMs: Date.now() - turnStartMs, streamedChars }),
+            config.heartbeatMs,
+          )
+        : null;
+    heartbeat?.unref?.();
     try {
-      res = await withRetry(() => provider.chat(messages, tools), {
-        onRetry: (attempt) => log(`rate limited; retry ${attempt}`),
-      });
+      res = await withRetry(
+        () =>
+          withTimeout(
+            () => provider.chat(messages, tools, { onStream: (chars) => (streamedChars = chars) }),
+            config.turnTimeoutMs,
+            () => provider.close?.(),
+          ),
+        { onRetry: (attempt) => log(`rate limited; retry ${attempt}`) },
+      );
     } catch (err) {
+      if (err instanceof TurnTimeoutError) {
+        // A hung provider turn: the watchdog aborted the in-flight call and tore
+        // down its subprocess. Retry the same turn a bounded number of times
+        // before giving up, so a transient hang self-heals instead of stalling
+        // the run forever.
+        if (turnTimeouts++ < maxTurnTimeouts) {
+          log(`turn exceeded ${config.turnTimeoutMs}ms; aborted the hung call and retrying (${turnTimeouts}/${maxTurnTimeouts})`);
+          await transcript.event('turn-timeout', { ms: config.turnTimeoutMs, attempt: turnTimeouts });
+          turn--;
+          continue;
+        }
+        return fail(`provider turns timed out ${turnTimeouts}× (>${config.turnTimeoutMs}ms each)`, 'provider-error');
+      }
       if (isRateLimit(err)) {
         const fallback = otherProvider(provider);
         if (fallback) {
@@ -408,11 +483,34 @@ async function runWithMemory(
           continue;
         }
       }
+      // A saved-login session/usage limit is not a code bug and not a 429 (2.4,
+      // I13): it names its own reset time and clears only then, and every turn
+      // so far is already in the llm-cache — so re-running after the reset
+      // replays them at ~0 tokens and resumes in place. Surface it as its own
+      // exit path with the reset time and the resume instruction, rather than a
+      // bare "provider error" the operator would read as a failure to debug.
+      const limit = sessionLimit(err);
+      if (limit) {
+        const when = limit.resetsAt ? ` (resets ${limit.resetsAt})` : '';
+        await transcript.event('session-limit', { resetsAt: limit.resetsAt, provider: provider.name });
+        return fail(
+          `${provider.name} session/usage limit reached${when} — this is a schedulable pause, not a bug. ` +
+            `Wait for the reset, then re-run the same command: completed turns replay from the cache at ~0 tokens and the run resumes where it left off.`,
+          'session-limit',
+        );
+      }
       return fail(`provider error: ${(err as Error).message}`, 'provider-error');
     } finally {
+      if (heartbeat) clearInterval(heartbeat);
       r.status(null);
     }
     turnsUsed = turn + 1;
+    // A productive turn resets the timeout budget: maxTurnTimeouts is meant to
+    // catch a turn that is genuinely, repeatedly stuck — not to cap the total
+    // number of slow-but-recoverable turns across a whole stage. Without this a
+    // long stage that merely has a few independent slow turns accumulates
+    // timeouts and hard-fails even though every one of them recovered.
+    turnTimeouts = 0;
     tokensIn += res.usage.inputTokens;
     tokensOut += res.usage.outputTokens;
     perTurn.push({ turn: turn + 1, in: res.usage.inputTokens, out: res.usage.outputTokens });
@@ -432,7 +530,9 @@ async function runWithMemory(
       if (nudges++ >= 2) return fail('model stopped calling tools without finishing', 'stalled');
       messages.push({
         role: 'user',
-        content: 'Continue using tools, or call finish({outcome, summary}) to end the run.',
+        // A near-miss malformed tool call (#I10) gets a specific steer to re-emit
+        // it; an ordinary tool-less turn gets the generic continue prompt.
+        content: res.nudge ?? 'Continue using tools, or call finish({outcome, summary}) to end the run.',
       });
       continue;
     }
@@ -502,6 +602,8 @@ async function runWithMemory(
           transcriptDir: transcript.dir,
           filesTouched: [],
           commit: null,
+          stats: runStats,
+          cacheHits: cacheHits(),
         };
       }
 
@@ -547,16 +649,32 @@ async function runWithMemory(
           transcriptDir: transcript.dir,
           filesTouched: files,
           commit: null,
+          stats: runStats,
+          cacheHits: cacheHits(),
         };
       }
 
-      await appendChangelog(repoRoot, config, {
-        changeId: ctx.changeId,
-        request: opts.request,
-        files,
-        verification,
-      });
-      ctx.ledger.clear('changelog');
+      // Bookkeeping must never cost the verified design its commit (2.1): the
+      // KiCad work passed its ERC/DRC gates, so a failure appending the changelog
+      // (a plain CHANGELOG.md read+write) is a warning, not a rollback. It stays
+      // before commitAll so, on the normal path, the entry lands in the run's
+      // single commit and a zero-edit "done" run still has something to commit;
+      // if it throws, the design is committed without a changelog line rather
+      // than sent through fail()'s rollback. The other bookkeeping — the openspec
+      // archive — is already post-commit and non-fatal below.
+      try {
+        await appendChangelog(repoRoot, config, {
+          changeId: ctx.changeId,
+          request: opts.request,
+          files,
+          verification,
+        });
+        ctx.ledger.clear('changelog');
+      } catch (err) {
+        const message = (err as Error).message;
+        log(`warning: changelog append failed (${message}); committing the verified design without a changelog entry`);
+        await transcript.event('changelog-append-failed', { error: message });
+      }
 
       const commitMsg = `copperhead: ${opts.request}\n\n${summary}\n\nVerification: ${verification}`;
       // A git failure here (e.g. `git add -A` exiting 128 on an embedded repo)
@@ -619,6 +737,8 @@ async function runWithMemory(
         transcriptDir: transcript.dir,
         filesTouched: files,
         commit,
+        stats: runStats,
+        cacheHits: cacheHits(),
       };
     }
   }

package/src/agent/prompts.ts

@@ -23,7 +23,8 @@ const WORKFLOW = `Workflow for every 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.
 
-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.`;
+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.`;
 
 export async function buildSystemPrompt(
   repoRoot: string,