copperhead 0.6.0 → 0.7.0

package/src/agent/providers/claude-code.ts

@@ -1,4 +1,4 @@
-import { mkdtemp, rm } from 'node:fs/promises';
+import { mkdtemp, rm, utimes } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import type { ChatOpts, Msg, Provider, ToolCall, ToolSchema, Turn } from '../types.js';
@@ -51,6 +51,16 @@ export interface QueryOptions {
   cwd?: string;
   env?: Record<string, string | undefined>;
   maxTurns?: number;
+  /** Aborting this controller stops the query and tears down the `claude`
+   * subprocess it spawned (Agent SDK `Options.abortController`). Used so the
+   * watchdog's `close()` on a hung turn kills the process instead of orphaning
+   * it (2.2/4.1) — a stranded subprocess keeps writing to its temp cwd and, with
+   * KiCad local history, was a source of the disk-fill halt (I8). */
+  abortController?: AbortController;
+  /** Resume a prior SDK session by id so the subprocess reconstructs earlier
+   * turns itself instead of us re-sending the whole conversation each turn (1.1,
+   * `Options.resume`). Only set in the opt-in session-resume mode. */
+  resume?: string;
 }
 export interface QueryArgs {
   prompt: string;
@@ -59,6 +69,7 @@ export interface QueryArgs {
 export interface QueryMessage {
   type: string;
   subtype?: string;
+  session_id?: string;
   message?: { content?: Array<{ type: string; text?: string }> };
   usage?: { input_tokens?: number; output_tokens?: number };
 }
@@ -93,17 +104,35 @@ export class ClaudeCodeProvider implements Provider {
   readonly name = 'claude-code';
   private callSeq = 0;
   private cwdPromise?: Promise<string>;
+  /** In-flight query aborters, so close() (called by the turn watchdog on a
+   * hung turn) can tear down the live subprocess, not just delete its cwd. */
+  private readonly inFlight = new Set<AbortController>();
+  /** Session-resume state (1.1). `sessionId` is the last session the SDK reported;
+   * `sentCount` is how many `messages` we have already handed it, so a resumed
+   * turn sends only the delta. Unused unless `sessionResume` is on. */
+  private sessionId?: string;
+  private sentCount = 0;
 
   constructor(
     private readonly model?: string,
     private readonly injectedQuery?: QueryLike,
     private readonly importSdk: ImportLike = (specifier) => import(specifier),
+    /**
+     * Opt-in: resume one SDK session across turns and send only new messages,
+     * instead of flattening and re-sending the entire conversation every turn
+     * (1.1). Cuts the ~quadratic history re-send that dominates long-stage cost.
+     * OFF by default and deliberately mutually exclusive with the response cache:
+     * the cache replays turns the resumed session never saw, so mixing them would
+     * desync the session. `makeProvider` enables it only when the cache is off.
+     */
+    private readonly sessionResume = false,
   ) {}
 
-  // `_opts.maxTokens` is intentionally ignored: the Agent SDK drives the Claude
-  // Code subprocess and exposes no per-call max-tokens knob. loop.ts calls
-  // chat() without opts today; noted so a future opts pass is not a surprise.
-  async chat(messages: Msg[], tools: ToolSchema[], _opts: ChatOpts = {}): Promise<Turn> {
+  // `opts.maxTokens` is intentionally ignored: the Agent SDK drives the Claude
+  // Code subprocess and exposes no per-call max-tokens knob. `opts.onStream` is
+  // honored: this provider streams, so it reports cumulative streamed-text length
+  // as blocks arrive, which the loop turns into a liveness heartbeat (5.1).
+  async chat(messages: Msg[], tools: ToolSchema[], opts: ChatOpts = {}): Promise<Turn> {
     const query = await this.resolveQuery();
 
     const system = messages
@@ -111,19 +140,28 @@ export class ClaudeCodeProvider implements Provider {
       .map((m) => m.content)
       .join('\n\n');
     const systemPrompt = [system, renderToolProtocol(tools)].filter(Boolean).join('\n\n');
-    const prompt = renderConversation(messages);
+    // Session-resume mode (1.1): once the SDK has given us a session id, resume it
+    // and send only the messages added since our last turn — the subprocess still
+    // holds the earlier conversation, so re-sending it would just re-bill it. The
+    // first turn (no session id yet) sends the full flattened history as usual.
+    const resume = this.sessionResume ? this.sessionId : undefined;
+    const prompt = resume ? renderDelta(messages, this.sentCount) : renderConversation(messages);
     const catalog = new Set(tools.map((t) => t.name));
     const cwd = await this.ensureCwd();
 
     let text: string | null = null;
     let inputTokens = 0;
     let outputTokens = 0;
+    // One aborter per turn: close() aborts it to kill a hung subprocess.
+    const aborter = new AbortController();
+    this.inFlight.add(aborter);
     try {
       for await (const msg of query({
         prompt,
         options: {
           systemPrompt,
           ...(this.model ? { model: this.model } : {}),
+          abortController: aborter,
           // Layered "the SDK executes nothing" defense (D1/D5):
           //  1. `tools: []` disables ALL built-in tools (Agent SDK 0.3.x docs:
           //     "[] (empty array) - Disable all built-in tools").
@@ -134,6 +172,7 @@ export class ClaudeCodeProvider implements Provider {
           //  4. The tool_use tripwire below fails the run loudly if one is
           //     emitted anyway. Any single layer failing is caught by the next.
           tools: [],
+          ...(resume ? { resume } : {}),
           disallowedTools: DISALLOWED_BUILTINS,
           canUseTool: async (toolName) => ({
             behavior: 'deny',
@@ -153,6 +192,9 @@ export class ClaudeCodeProvider implements Provider {
           for (const block of msg.message?.content ?? []) {
             if (block.type === 'text' && block.text) {
               text = (text ?? '') + block.text;
+              // Report progress so the loop's heartbeat shows this turn is alive
+              // and streaming, not hung, during a multi-minute large-output turn.
+              opts.onStream?.(text.length);
             } else if (block.type === 'tool_use') {
               // Load-bearing invariant (D1): the SDK must execute nothing, so it
               // must never emit a tool_use block. If it does, `tools: []` was not
@@ -169,6 +211,9 @@ export class ClaudeCodeProvider implements Provider {
           if (typeof msg.usage?.input_tokens === 'number') inputTokens = msg.usage.input_tokens;
           if (typeof msg.usage?.output_tokens === 'number') outputTokens = msg.usage.output_tokens;
         }
+        // The session id can arrive on any message (init/system/result); keep the
+        // latest so the next turn can resume it (1.1). No-op unless resume is on.
+        if (this.sessionResume && typeof msg.session_id === 'string') this.sessionId = msg.session_id;
       }
     } catch (err) {
       // Auth failures get an actionable message (non-retryable); everything else
@@ -177,15 +222,40 @@ export class ClaudeCodeProvider implements Provider {
       // distinct `name` makes otherProvider() return null for us.
       if (isAuthError(err)) throw new Error(authHint((err as Error).message));
       throw err;
+    } finally {
+      this.inFlight.delete(aborter);
     }
 
+    // Only advance the high-water mark on a turn that completed: a thrown turn
+    // (rate limit, timeout) is retried, and must re-send the same delta so no
+    // message is lost from the resumed session (1.1).
+    if (this.sessionResume) this.sentCount = messages.length;
+
     const parsed = parseToolCalls(text, () => `cc-${++this.callSeq}`, catalog);
-    return { text: parsed.text, toolCalls: parsed.toolCalls, usage: { inputTokens, outputTokens } };
+    return {
+      text: parsed.text,
+      toolCalls: parsed.toolCalls,
+      usage: { inputTokens, outputTokens },
+      nudge: parsed.nudge,
+    };
   }
 
-  /** Remove the scratch cwd. loop.ts calls this on every provider in a finally,
-   * so the one temp dir this instance created does not leak past the run. */
+  /** Tear down in-flight work and remove the scratch cwd. Called by the turn
+   * watchdog on a hung turn (via withTimeout's onTimeout) AND once per run in a
+   * finally. Aborting first kills the `claude` subprocess a hung turn spawned —
+   * without it the process is orphaned and keeps writing to its temp cwd, which
+   * (with KiCad local history) was a source of the disk-fill halt (2.2/4.1, I8).
+   * A leftover empty dir in the OS tmpdir is harmless; the startup sweep reclaims
+   * any that a hard SIGKILL bypassed this cleanup for. */
   async close(): Promise<void> {
+    for (const aborter of this.inFlight) {
+      try {
+        aborter.abort();
+      } catch {
+        // best effort: a controller that already settled throws nothing useful
+      }
+    }
+    this.inFlight.clear();
     const pending = this.cwdPromise;
     this.cwdPromise = undefined;
     if (!pending) return;
@@ -199,9 +269,17 @@ export class ClaudeCodeProvider implements Provider {
   /** One isolated scratch cwd per provider instance, created once and reused
    * across turns so a long run does not leak a temp dir per turn. Even with
    * tools disabled this guarantees the SDK has no path into the repo (D5). */
-  private ensureCwd(): Promise<string> {
+  private async ensureCwd(): Promise<string> {
     if (!this.cwdPromise) this.cwdPromise = mkdtemp(path.join(os.tmpdir(), 'copperhead-cc-'));
-    return this.cwdPromise;
+    const cwd = await this.cwdPromise;
+    // Keep this reused scratch dir's mtime fresh on every turn. It is the only
+    // long-lived temp dir a run holds (kicad-cli dirs are per-call), so a
+    // multi-hour run would otherwise leave it with a stale mtime and a concurrent
+    // run's startup sweep (sweepStaleTempDirs, age-gated) could delete it out from
+    // under the live process (F4). Best-effort: a touch failure is harmless.
+    const now = new Date();
+    await utimes(cwd, now, now).catch(() => {});
+    return cwd;
   }
 
   private async resolveQuery(): Promise<QueryLike> {
@@ -265,6 +343,32 @@ function renderToolProtocol(tools: ToolSchema[]): string {
   return lines.join('\n');
 }
 
+/**
+ * The prompt for a *resumed* turn (1.1): only the messages added since the last
+ * turn we sent, and only the ones the resumed session does not already hold. The
+ * subprocess already has every prior turn plus its own assistant replies, so we
+ * send just the new user nudges and tool results — that delta is what advances
+ * the conversation. Falls back to the full render (via the caller) when there is
+ * no session yet.
+ */
+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}`);
+    }
+    // assistant/system messages are already in the resumed session — skip them.
+  }
+  return parts.join('\n\n');
+}
+
 function renderConversation(messages: Msg[]): string {
   const idToName = new Map<string, string>();
   const parts: string[] = [];
@@ -291,6 +395,33 @@ function renderConversation(messages: Msg[]): string {
 interface Parsed {
   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;
 }
 
 /**
@@ -304,28 +435,80 @@ interface Parsed {
 function parseToolCalls(text: string | null, nextId: () => string, catalog: Set<string>): Parsed {
   if (!text) return { text: null, toolCalls: [] };
   const toolCalls: ToolCall[] = [];
-  let prose = text;
+  const matched: Array<[number, number]> = [];
 
-  const fence = /```(?:json)?\s*([\s\S]*?)```/gi;
-  let match: RegExpExecArray | null;
-  const consumed: string[] = [];
-  while ((match = fence.exec(text)) !== null) {
-    const call = toToolCall(match[1], nextId, catalog);
+  // 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);
-      consumed.push(match[0]);
+      matched.push([span.start, span.end]);
     }
+    searchFrom = span.end;
   }
-  for (const block of consumed) prose = prose.replace(block, '');
 
-  // No fenced tool block: maybe the whole reply is a bare JSON object.
   if (!toolCalls.length) {
-    const call = toToolCall(text, nextId, catalog);
-    if (call) return { text: null, toolCalls: [call] };
+    // 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 };
+}
 
-  const trimmed = prose.trim();
-  return { text: trimmed.length ? trimmed : 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 {

package/src/agent/recovery.ts

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

package/src/agent/render.ts

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

package/src/agent/response-cache.ts

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