copperhead 0.5.0 → 0.7.0

package/src/util/preflight.ts

@@ -1,3 +1,5 @@
+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.
@@ -20,3 +22,45 @@ export function formatPreflightFailure(reason: string, why: string, remedy: stri
   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: number): string => `${(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: string): Promise<number | null> {
+  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: string, minFreeBytes = DEFAULT_MIN_FREE_BYTES): Promise<void> {
+  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',
+    ],
+  );
+}

package/src/util/retry.ts

@@ -12,6 +12,35 @@ export function isRateLimit(err: unknown): boolean {
   return status === 429;
 }
 
+export interface SessionLimit {
+  /** The reset moment exactly as the provider stated it (e.g. "1:40pm"), or null
+   *  when the message named a limit but no parseable time. */
+  resetsAt: string | null;
+}
+
+/**
+ * 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: unknown): SessionLimit | null {
+  const status = (err as { status?: number; statusCode?: number })?.status
+    ?? (err as { statusCode?: number })?.statusCode;
+  if (status === 429) return null; // a real rate limit: handled by backoff, not a pause
+  const msg = (err as Error)?.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<T>(fn: () => Promise<T>, opts: RetryOpts = {}): Promise<T> {
   const retries = opts.retries ?? 3;

package/src/util/tmp.ts

@@ -0,0 +1,113 @@
+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: string, keepNewest = DEFAULT_HISTORY_KEEP): Promise<number> {
+  const root = path.join(repoRoot, '.history');
+  const files: Array<{ full: string; mtimeMs: number }> = [];
+  const walk = async (dir: string): Promise<void> => {
+    let entries: Array<{ name: string; isDirectory(): boolean; isFile(): boolean }>;
+    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: number, maxAgeMs = DEFAULT_STALE_MS): Promise<string[]> {
+  const root = tmpdir();
+  const removed: string[] = [];
+  let entries: string[];
+  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;
+}