copperhead 0.6.0 → 0.8.0

package/src/agent/providers/tool-protocol.ts

@@ -0,0 +1,212 @@
+import type { Msg, ToolCall, ToolSchema } from '../types.js';
+
+export function renderToolProtocol(tools: ToolSchema[]): string {
+  if (!tools.length) return '';
+  const lines = [
+    '# Tool protocol',
+    '',
+    'You are the reasoning half of a tool-driven workflow; you cannot run anything yourself.',
+    'To take an action, reply with EXACTLY ONE JSON object and nothing else, wrapped in a',
+    '```json fenced code block:',
+    '',
+    '```json',
+    '{"tool": "<tool_name>", "args": { ... }}',
+    '```',
+    '',
+    'Use only the tools listed below, with `args` matching the tool\'s JSON Schema. If you have',
+    'no tool to call and only want to say something, reply with plain prose and no JSON block.',
+    '',
+    '## Available tools',
+  ];
+  for (const t of tools) {
+    lines.push(
+      '',
+      `### ${t.name}`,
+      t.description,
+      `Parameters (JSON Schema): ${JSON.stringify(t.parameters)}`,
+    );
+  }
+  return lines.join('\n');
+}
+
+/** Delta prompt for a resumed CLI session: new user lines and tool results only. */
+export function renderDelta(messages: Msg[], from: number): string {
+  const idToName = new Map<string, string>();
+  for (const m of messages) {
+    if (m.role === 'assistant') for (const call of m.toolCalls ?? []) idToName.set(call.id, call.name);
+  }
+  const parts: string[] = [];
+  for (const m of messages.slice(Math.max(0, from))) {
+    if (m.role === 'user') {
+      parts.push(`[user]\n${m.content}`);
+    } else if (m.role === 'tool') {
+      const name = idToName.get(m.toolCallId) ?? m.toolCallId;
+      parts.push(`[result of ${name}]\n${m.content}`);
+    }
+  }
+  return parts.join('\n\n');
+}
+
+export function renderConversation(messages: Msg[]): string {
+  const idToName = new Map<string, string>();
+  const parts: string[] = [];
+  for (const m of messages) {
+    if (m.role === 'system') continue;
+    if (m.role === 'user') {
+      parts.push(`[user]\n${m.content}`);
+    } else if (m.role === 'assistant') {
+      if (m.content) parts.push(`[assistant]\n${m.content}`);
+      for (const call of m.toolCalls ?? []) {
+        idToName.set(call.id, call.name);
+        parts.push(
+          `[assistant tool call]\n\`\`\`json\n${JSON.stringify({ tool: call.name, args: call.args })}\n\`\`\``,
+        );
+      }
+    } else {
+      const name = idToName.get(m.toolCallId) ?? m.toolCallId;
+      parts.push(`[result of ${name}]\n${m.content}`);
+    }
+  }
+  return parts.join('\n\n');
+}
+
+export interface ParsedToolTurn {
+  text: string | null;
+  toolCalls: ToolCall[];
+  nudge?: string;
+}
+
+/**
+ * Detect a malformed-but-intended tool call in a turn that dispatched none
+ * (#I10). The signature is machine-recognizable: the text contains
+ * `"tool":"<name>"` naming a tool in the current catalog, yet nothing parsed.
+ * That is the exact case where the tolerant extractor's silence misleads the
+ * model — the JSON was near-miss malformed (a brace short, or the outer object
+ * split so only an inner `{args}` with no `tool` key balanced), not the tool
+ * being broken. Returns a one-line steer to re-emit it, or undefined when the
+ * absence of a call is genuine (plain prose, no tool named).
+ */
+function detectMalformedCall(text: string, catalog: Set<string>): string | undefined {
+  const re = /"tool"\s*:\s*"([^"]+)"/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) {
+    const name = m[1]!;
+    if (catalog.has(name)) {
+      return (
+        `A tool call for "${name}" looks malformed — it named the tool but did not parse as ` +
+        'valid JSON (likely unbalanced braces or a missing closing brace), so no call ran. ' +
+        'Re-emit it as exactly one complete JSON object: {"tool": "...", "args": { ... }}.'
+      );
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Extract tool-call JSON from the model's reply. Tolerant by design (D1):
+ * unparseable output is returned as plain text with no tool calls rather than
+ * throwing, so a non-conforming turn degrades to the loop's stall/nudge path.
+ * A parsed block only counts as a tool call when its name is in the current
+ * turn's catalog (`availableTools(ctx)`): a hallucinated or locked tool name is
+ * left as prose so the loop nudges, rather than dispatching a bogus call.
+ */
+export function parseToolCalls(
+  text: string | null,
+  nextId: () => string,
+  catalog: Set<string>,
+): ParsedToolTurn {
+  if (!text) return { text: null, toolCalls: [] };
+  const toolCalls: ToolCall[] = [];
+  const matched: Array<[number, number]> = [];
+
+  // Extract tool calls by scanning for complete JSON objects, NOT by matching
+  // ``` fences. A tool call's `content`/`args` can hold a full markdown doc that
+  // itself contains ``` code fences; a fence regex truncates the JSON at the
+  // first inner fence, JSON.parse fails, and the call is silently dropped (the
+  // model then assumes it wrote a file it never did). The brace scan is
+  // string-aware, so braces and backticks inside JSON string values are ignored.
+  let searchFrom = 0;
+  while (searchFrom < text.length) {
+    const braceAt = text.indexOf('{', searchFrom);
+    if (braceAt < 0) break;
+    const span = scanJsonObject(text, braceAt);
+    if (!span) {
+      // Unbalanced '{' (stray brace in prose): retry from the next candidate so
+      // one bad brace can't hide a well-formed call later in the reply.
+      searchFrom = braceAt + 1;
+      continue;
+    }
+    const call = toToolCall(text.slice(span.start, span.end), nextId, catalog);
+    if (call) {
+      toolCalls.push(call);
+      matched.push([span.start, span.end]);
+    }
+    searchFrom = span.end;
+  }
+
+  if (!toolCalls.length) {
+    // No call dispatched — but did the model clearly *intend* one? A fenced
+    // ```json block that names a catalog tool yet produced zero calls is a
+    // malformed near-miss (unbalanced braces, a missing `}`, or an inner object
+    // with no `tool` key). Silently dropping it gives the model no signal, so it
+    // misreads "no result" as "this tool is broken" and can bake that false
+    // conclusion into a committed summary (#I10). Surface a nudge instead.
+    return { text: text.trim() ? text : null, toolCalls, nudge: detectMalformedCall(text, catalog) };
+  }
+
+  // Prose is whatever survives once the tool-call objects (and any now-empty
+  // ```json fences around them) are removed.
+  let prose = '';
+  let cursor = 0;
+  for (const [start, end] of matched) {
+    prose += text.slice(cursor, start);
+    cursor = end;
+  }
+  prose += text.slice(cursor);
+  prose = prose.replace(/```(?:json)?\s*```/gi, '').replace(/```(?:json)?\s*$/gi, '').trim();
+  return { text: prose.length ? prose : null, toolCalls };
+}
+
+/**
+ * Find the first complete, brace-balanced JSON object at or after `from`,
+ * respecting JSON string quoting/escaping so braces or backticks inside string
+ * values do not end the scan. Returns its `[start, end)` bounds or null.
+ */
+function scanJsonObject(text: string, from: number): { start: number; end: number } | null {
+  const start = text.indexOf('{', from);
+  if (start < 0) return null;
+  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) return { start, end: i + 1 };
+  }
+  return null;
+}
+
+function toToolCall(raw: string | undefined, nextId: () => string, catalog: Set<string>): ToolCall | null {
+  if (!raw) return null;
+  let obj: unknown;
+  try {
+    obj = JSON.parse(raw.trim());
+  } catch {
+    return null;
+  }
+  if (!obj || typeof obj !== 'object') return null;
+  const rec = obj as Record<string, unknown>;
+  if (typeof rec.tool !== 'string') return null;
+  // Only accept names the turn actually advertised. An empty catalog means the
+  // turn offered no tools, so nothing parses as a call.
+  if (!catalog.has(rec.tool)) return null;
+  const args = rec.args && typeof rec.args === 'object' ? (rec.args as Record<string, unknown>) : {};
+  return { id: nextId(), name: rec.tool, args };
+}

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

@@ -3,8 +3,13 @@
  * once at startup: interactive (TTY, no --json/--plain) pins a status line to
  * the bottom of the terminal and redraws it in place; plain emits line-oriented
  * output with zero ANSI escapes — the mode CI, pipes, and tests see.
+ *
+ * Interactive mode adds subtle SGR chrome (copper accent, dim secondary text).
+ * Plain mode never emits color (AC-8.9).
  */
 
+import { copper, dim, setColorEnabled, styleOutcome, toolLine, warn } from './theme.js';
+
 export interface ProgressRenderer {
   log(line: string): void;
   /** Called at the start of each turn with cumulative token totals so far. */
@@ -12,6 +17,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 +54,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 +86,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;
@@ -92,16 +111,29 @@ export class InteractiveRenderer implements ProgressRenderer {
   }
 
   private statusText(): string {
-    const parts = [
-      `turn ${this.turn}/${this.maxTurns}`,
-      `${fmtTokens(this.tokensIn)} in / ${fmtTokens(this.tokensOut)} out`,
-      fmtDuration(Date.now() - this.startMs),
-    ];
-    if (this.busy) parts.push(this.busy);
-    const spinner = this.busy ? FRAMES[this.frame % FRAMES.length] : '·';
-    const line = `${spinner} ${parts.join(' · ')}`;
+    // Raw (uncolored) segments once; both the colored line and the
+    // narrow-terminal fallback are assembled from these.
+    const spinner = this.busy ? FRAMES[this.frame % FRAMES.length]! : '·';
+    const turn = `turn ${this.turn}/${this.maxTurns}`;
+    const tokens = `${fmtTokens(this.tokensIn)} in / ${fmtTokens(this.tokensOut)} out`;
+    const elapsed = fmtDuration(Date.now() - this.startMs);
+    // Fold streamed-output volume into the busy segment so a large turn's
+    // status line visibly grows — a hung one stays frozen (5.1).
+    const busy = this.busy
+      ? this.streamedChars
+        ? `${this.busy} ~${fmtTokens(this.streamedChars)} ch`
+        : this.busy
+      : undefined;
+    const parts = [turn, dim(tokens), dim(elapsed), ...(busy ? [warn(busy)] : [])];
+    const line = `${this.busy ? copper(spinner) : dim(spinner)} ${parts.join(dim(' · '))}`;
+    // Truncate by visible length roughly: strip SGR when measuring so color
+    // codes don't eat the column budget and clip the readable text early.
     const width = this.out.columns ?? 80;
-    return line.length > width ? line.slice(0, width - 1) : line;
+    const visible = line.replace(/\x1b\[[0-9;]*m/g, '');
+    if (visible.length <= width) return line;
+    // Fall back to an uncolored truncated line when the terminal is too narrow.
+    const plain = [spinner, turn, tokens, elapsed, ...(busy ? [busy] : [])].join(' · ');
+    return plain.length > width ? plain.slice(0, width - 1) : plain;
   }
 
   private redraw(): void {
@@ -138,23 +170,32 @@ 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();
   }
 
   toolResult(name: string, firstLine: string): void {
-    this.log(`  [${name}] ${firstLine}`);
+    this.log(toolLine(name, firstLine));
   }
 
   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');
+    this.out.write(styleOutcome(line) + '\n');
     this.suspend();
   }
 
@@ -188,7 +229,10 @@ export class InteractiveRenderer implements ProgressRenderer {
  * (AC-2.4): the only thing a --json invocation writes to stdout is its JSON.
  */
 export function makeRenderer(opts: { json: boolean; plain: boolean }): ProgressRenderer {
+  const interactive = !opts.json && !opts.plain && Boolean(process.stdout.isTTY);
+  // Color tracks the interactive path so --plain / pipes stay zero-ANSI (AC-8.9).
+  setColorEnabled(interactive && !process.env.NO_COLOR);
   if (opts.json) return plainRenderer((line) => console.error(line));
-  if (!opts.plain && process.stdout.isTTY) return new InteractiveRenderer();
+  if (interactive) return new InteractiveRenderer();
   return plainRenderer((line) => console.log(line));
 }

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/runmeta.ts

@@ -9,7 +9,7 @@ import type { CopperheadConfig, ModelSource } from '../config.js';
 
 /** Caller-supplied run identity: facts the loop cannot probe for itself. */
 export interface RunMetaInput {
-  command?: 'do' | 'create' | 'sync';
+  command?: 'do' | 'create' | 'sync' | 'repl';
   modelSource?: ModelSource;
   version?: string;
   kicadCliVersion?: string;
@@ -29,7 +29,7 @@ export interface RunMeta {
   modelSource: ModelSource | null;
   runId: string;
   startedAt: string;
-  command: 'do' | 'create' | 'sync' | null;
+  command: 'do' | 'create' | 'sync' | 'repl' | null;
   interactive: boolean;
   stage: { name: string; index: number; total: number } | null;
   brief: { path: string; sha256: string } | null;
@@ -150,14 +150,14 @@ export async function collectRunMeta(opts: CollectRunMetaOptions): Promise<RunMe
 
 const unk = (v: string | null | undefined): string => v ?? 'unknown';
 
-/** ≤ 2 lines, printed before the first turn (AC-8.4). */
+/** ≤ 2 lines, printed before the first turn (AC-8.4).
+ *  Live header stays compact: install path / platform live in summary.md only. */
 export function renderCliHeader(meta: RunMeta): string[] {
   const v = meta.versions;
   const line1 = [
-    `copperhead v${unk(v.copperhead)}${v.installPath ? ` (${v.installPath})` : ''}`,
+    `copperhead v${unk(v.copperhead)}`,
     `kicad-cli ${unk(v.kicadCli)}`,
     `node ${v.node}`,
-    v.platform,
   ].join(' · ');
 
   const repoState =
@@ -167,12 +167,11 @@ export function renderCliHeader(meta: RunMeta): string[] {
         ? `dirty(${meta.git.uncommittedFiles})`
         : 'clean';
   const line2 = [
-    `run ${meta.runId}`,
     unk(meta.command),
     ...(meta.stage ? [`stage ${meta.stage.name} (${meta.stage.index}/${meta.stage.total})`] : []),
     `model ${meta.model} (${meta.provider}, via ${unk(meta.modelSource)})`,
     `turns ≤${meta.config.maxTurns}`,
-    `repo ${unk(meta.git.branch)}@${meta.git.commit?.slice(0, 7) ?? 'unknown'} ${repoState}`,
+    `${unk(meta.git.branch)}@${meta.git.commit?.slice(0, 7) ?? 'unknown'} ${repoState}`,
   ].join(' · ');
   return [line1, line2];
 }