copperhead 0.3.0 → 0.5.0

package/NOTICE

@@ -0,0 +1,5 @@
+copperhead
+Copyright 2026 Chouhan Industries
+
+This product includes software developed at Chouhan Industries
+(https://github.com/chouhanindustries/copperhead).

package/README.md

@@ -1,8 +1,18 @@
-# copperhead
+<p align="center">
+  <a href="https://copperhead.sh"><img src="https://raw.githubusercontent.com/chouhanindustries/copperhead/main/docs/branding/lockup-transparent.png" alt="copperhead" width="440"></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/copperhead"><img src="https://img.shields.io/npm/v/copperhead?color=b87333" alt="npm"></a>
+  <a href="https://github.com/chouhanindustries/copperhead/actions/workflows/ci.yml"><img src="https://github.com/chouhanindustries/copperhead/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/copperhead?color=15181c" alt="license"></a>
+</p>
 
 **Cursor for circuit boards.** An AI agent that designs, documents, and validates real PCBs from a prompt, working directly on existing KiCad repositories.
 
-> **Status: early (v0.1).** Phase 1 is implemented and the CLI runs. The [technical specification](openspec/specs/SPEC.md) is the source of truth; expect the surface to move before 1.0.
+> **Status: early.** Phase 1 is implemented and the CLI runs. The [technical specification](openspec/specs/SPEC.md) is the source of truth; expect the surface to move before 1.0.
+
+Full documentation lives at [docs.copperhead.sh](https://docs.copperhead.sh).
 
 ## What it is
 
@@ -13,6 +23,47 @@ An AI product-development agent for hardware: from a product brief to manufactur
 
 It reads and edits real `.kicad_sch` / `.kicad_pcb` files (s-expression text), maintains markdown design docs as memory, propagates every change across all artifacts that reference it, and verifies its own work by running `kicad-cli` ERC/DRC until the checks pass.
 
+## Install
+
+```bash
+npm install -g copperhead   # or: npx copperhead check
+```
+
+### Requirements
+
+- Node.js ≥ 20
+- [KiCad](https://www.kicad.org/) ≥ 8 with `kicad-cli` on PATH
+- One model backend: a locally installed, ChatGPT-authenticated [Codex CLI](https://learn.chatgpt.com/docs/codex/cli), or `ANTHROPIC_API_KEY`/`OPENAI_API_KEY` in the environment. `check` never calls an LLM.
+
+## Quick start
+
+In an existing KiCad repository:
+
+```bash
+export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY
+copperhead init                # scaffold docs/ from the schematic; idempotent
+copperhead do "add reverse-polarity protection on VIN"
+copperhead check               # ERC + DRC + doc drift; no LLM, CI-safe
+```
+
+Starting from nothing instead? Write a product brief and run `copperhead create --brief brief.md`. The [examples/](examples/) directory has ready-made briefs sorted by difficulty, plus a note on which one is designed to fail.
+
+### Use your existing Codex login
+
+No model API key is needed when Codex CLI is already authenticated:
+
+```bash
+npm install -g @openai/codex-sdk   # optional adapter, loaded only for --model codex
+codex login status
+copperhead do "rename net KEY_DAH to KEY_DASH" --model codex
+```
+
+Plain `codex` follows your Codex model configuration. Use `codex:<model-id>` for an explicit model. If the executable is not on `PATH`, set `COPPERHEAD_CODEX_PATH=/absolute/path/to/codex`.
+The optional SDK also installs a compatible launcher; for a global install, use
+`COPPERHEAD_CODEX_PATH="$(npm root -g)/@openai/codex/bin/codex.js"` as a fallback.
+
+Codex's read-only sandbox prevents native writes but does not confine native reads. Copperhead instructs Codex not to use its own filesystem tools, but the CLI can technically read files such as `.env`. Codex also keeps session logs under `~/.codex/sessions/`; those files are outside Copperhead's transcript-redaction boundary and should be protected according to your local data-retention policy.
+
 ## How it works
 
 It's a loop, and it looks a lot like pair-programming, except the codebase is a circuit board.
@@ -51,21 +102,28 @@ Nothing is a black box: decisions land in an append-only `docs/DECISIONS.md`, ev
 - **Not a new editor.** No walled garden; your KiCad install remains the editor.
 - **Not the engineer of record.** A human signs off; the agent never claims a design is fab-ready beyond "ERC/DRC clean".
 
-## Install
+## Simple demo
+
+From a checkout of this repo, run the smallest create-pipeline demo with the USB-C power breakout brief:
 
 ```bash
-npm install -g copperhead   # or: npx copperhead check
+npm run demo:simple
 ```
 
-### Requirements
+The script creates or resumes a git repo at `demo-runs/usb-c-breakout/` and runs:
 
-- Node.js ≥ 20
-- [KiCad](https://www.kicad.org/) ≥ 8 with `kicad-cli` on PATH
-- An OpenAI or Anthropic API key (env var only), except for `check`, which never calls an LLM
+```bash
+copperhead create --brief examples/simple/usb-c-breakout.md
+```
+
+Pass normal create flags after `--`, for example `npm run demo:simple -- --model claude`.
+If a stage fails, rerun the same command; the demo repo keeps a baseline commit and ignores run transcripts so retries start from the last committed design state.
+
+More briefs, including medium and hard tiers, live in [examples/](examples/).
 
 ## Maturity
 
-Honest read of where v0.1 stands, so you can calibrate before pointing this at a board you care about:
+Honest read of where the current release stands, so you can calibrate before pointing this at a board you care about:
 
 - **Solid.** `init` and `check`/`verify` are deterministic, LLM-free, and covered by the offline test suite against a real KiCad fixture: scaffolding, ERC/DRC, the s-expression reader, drift detection, and fab export all run green in CI.
 - **Implemented, not yet proven.** The agent loop (`do`, `sync --resolve`, `create`) is complete and structurally gated, but its acceptance tests need a live model and have not been observed passing end to end. Expect rough edges.
@@ -75,8 +133,13 @@ Honest read of where v0.1 stands, so you can calibrate before pointing this at a
 
 The entire tool (agent core, prompts, tools) is public under Apache-2.0, built on an open stack (KiCad, kicad-cli, [OpenSpec](https://github.com/Fission-AI/OpenSpec)). Everything it produces is plain markdown and JSON in your own repo: no proprietary formats, no lock-in. This is a Chouhan Industries project, and the same commitment that puts every hardware schematic in public applies to the tool that designs them.
 
+## Contributing
+
+Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md) for setup and workflow. Note that your first pull request requires signing the [Contributor License Agreement](.github/cla/CLA.md); a bot posts instructions on the PR and signing is a one-time comment.
+
 ## Project layout
 
+- [`AGENTS.md`](AGENTS.md): repository instructions loaded automatically by Codex and compatible coding agents; [`CLAUDE.md`](CLAUDE.md) provides the corresponding Claude Code guidance
 - [`src/`](src/): CLI ([`cli.ts`](src/cli.ts), [`commands/`](src/commands/)), the provider-agnostic agent loop ([`agent/`](src/agent/)), the `kicad-cli` wrapper and s-expression reader ([`kicad/`](src/kicad/)), and doc/constraint memory ([`memory/`](src/memory/))
 - [`test/`](test/): offline suite plus [`fixtures/`](test/fixtures/), a tiny known-good KiCad project
 - [`openspec/specs/SPEC.md`](openspec/specs/SPEC.md): the full technical specification, including binary acceptance criteria

package/dist/agent/ledger.js

@@ -5,8 +5,15 @@ export class ObligationsLedger {
             this.open.push({ kind, detail, openedBy });
         }
     }
+    /** Returns true if at least one obligation was actually removed. */
     clear(kind, detail) {
+        const before = this.open.length;
         this.open = this.open.filter((o) => !(o.kind === kind && (detail === undefined || o.detail === detail)));
+        return this.open.length < before;
+    }
+    /** Open obligations of one kind, for building corrective tool errors. */
+    openOfKind(kind) {
+        return this.open.filter((o) => o.kind === kind);
     }
     /** A KiCad edit re-opens verification obligations even if previously cleared. */
     onKicadEdit(file) {

package/dist/agent/ledger.js.map

@@ -1 +1 @@
-{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/agent/ledger.ts"],"names":[],"mappings":"AAoBA,MAAM,OAAO,iBAAiB;IACpB,IAAI,GAAiB,EAAE,CAAC;IAEhC,GAAG,CAAC,IAAoB,EAAE,MAAc,EAAE,QAAgB;QACxD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,EAAE,CAAC;YACnE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAoB,EAAE,MAAe;QACzC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAC1B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAC3E,CAAC;IACJ,CAAC;IAED,iFAAiF;IACjF,WAAW,CAAC,IAAY;QACtB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,qCAAqC,EAAE,IAAI,CAAC,CAAC;QAC7D,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,iCAAiC,EAAE,IAAI,CAAC,CAAC;QAC1F,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,8CAA8C,EAAE,IAAI,CAAC,CAAC;QACxE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,iCAAiC,EAAE,IAAI,CAAC,CAAC;IACjE,CAAC;IAED,SAAS,CAAC,IAAY;QACpB,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,4CAA4C,EAAE,IAAI,CAAC,CAAC;IACxE,CAAC;IAED,kBAAkB,CAAC,aAAqB,EAAE,OAAiB;QACzD,IAAI,CAAC,GAAG,CAAC,uBAAuB,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC;QAChE,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,GAAG,aAAa,YAAY,IAAI,EAAE,EAAE,aAAa,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;IAED,UAAU,CAAC,OAAe;QACxB,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,QAAQ;QACN,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,gCAAgC,CAAC;QAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,eAAe,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChG,CAAC;CACF"}
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/agent/ledger.ts"],"names":[],"mappings":"AAoBA,MAAM,OAAO,iBAAiB;IACpB,IAAI,GAAiB,EAAE,CAAC;IAEhC,GAAG,CAAC,IAAoB,EAAE,MAAc,EAAE,QAAgB;QACxD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,EAAE,CAAC;YACnE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,KAAK,CAAC,IAAoB,EAAE,MAAe;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAC1B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAC3E,CAAC;QACF,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACnC,CAAC;IAED,yEAAyE;IACzE,UAAU,CAAC,IAAoB;QAC7B,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,iFAAiF;IACjF,WAAW,CAAC,IAAY;QACtB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,qCAAqC,EAAE,IAAI,CAAC,CAAC;QAC7D,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,iCAAiC,EAAE,IAAI,CAAC,CAAC;QAC1F,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,8CAA8C,EAAE,IAAI,CAAC,CAAC;QACxE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,iCAAiC,EAAE,IAAI,CAAC,CAAC;IACjE,CAAC;IAED,SAAS,CAAC,IAAY;QACpB,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,4CAA4C,EAAE,IAAI,CAAC,CAAC;IACxE,CAAC;IAED,kBAAkB,CAAC,aAAqB,EAAE,OAAiB;QACzD,IAAI,CAAC,GAAG,CAAC,uBAAuB,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC;QAChE,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,GAAG,aAAa,YAAY,IAAI,EAAE,EAAE,aAAa,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;IAED,UAAU,CAAC,OAAe;QACxB,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,QAAQ;QACN,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,gCAAgC,CAAC;QAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,eAAe,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChG,CAAC;CACF"}

package/dist/agent/loop.js

@@ -3,17 +3,36 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { execa } from 'execa';
 import { availableTools, dispatchTool } from './tools.js';
 import { buildSystemPrompt } from './prompts.js';
-import { loadConstraints } from '../memory/constraints.js';
+import { loadConstraints, reopenDeferredAffects } from '../memory/constraints.js';
 import { loadConfig } from '../config.js';
 import { Transcript } from './transcript.js';
+import { collectRunMeta, renderCliHeader } from './runmeta.js';
+import { plainRenderer, fmtDuration, fmtTokens } from './render.js';
 import { ObligationsLedger } from './ledger.js';
-import { isDirty, isGitRepo, snapshot, restore, commitAll, changedFiles } from '../util/git.js';
+import { gitPreflight, isDirty, snapshot, restore, commitAll, changedFiles, preserveFailedRun } from '../util/git.js';
 import { withRetry, isRateLimit } from '../util/retry.js';
 import { openspecArchive } from '../openspec/cli.js';
 import { existsSync } from 'node:fs';
 import { OpenAIProvider } from './providers/openai.js';
 import { AnthropicProvider } from './providers/anthropic.js';
-export function makeProvider(model) {
+import { CodexProvider } from './providers/codex.js';
+import { openSynapMemory } from '../memory/synap.js';
+export async function makeProvider(model) {
+    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>"');
+        const { Codex } = await import('@openai/codex-sdk').catch((err) => {
+            throw new Error('Codex provider requires the optional @openai/codex-sdk package; install it alongside Copperhead before using --model codex', { cause: err });
+        });
+        return new CodexProvider({
+            ...(codexModel ? { model: codexModel } : {}),
+            client: new Codex({
+                // Use the user's installed CLI and its saved login rather than a model API key.
+                codexPathOverride: process.env.COPPERHEAD_CODEX_PATH || 'codex',
+            }),
+        });
+    }
     if (model === 'claude' || model.startsWith('claude')) {
         return new AnthropicProvider(model === 'claude' ? undefined : model);
     }
@@ -56,17 +75,36 @@ async function appendChangelog(repoRoot, config, entry) {
     lines.splice(insertAt, 0, ...block.split('\n').slice(1), '');
     await writeFile(p, lines.join('\n'), 'utf8');
 }
+/**
+ * Owns the Synap session for one run. The bridge is a subprocess, so the
+ * shutdown in `finally` is what lets the CLI exit; without it the process
+ * hangs after a successful run.
+ */
 export async function runAgentLoop(opts) {
-    const log = opts.log ?? ((l) => console.log(l));
+    const memory = await openSynapMemory({ repoRoot: opts.repoRoot, log: opts.log });
+    const providers = new Set();
+    try {
+        return await runWithMemory(opts, memory, providers);
+    }
+    finally {
+        for (const provider of providers) {
+            try {
+                await provider.close?.();
+            }
+            catch (err) {
+                opts.log?.(`warning: ${provider.name} provider cleanup failed (${err.message})`);
+            }
+        }
+        await memory?.close();
+    }
+}
+async function runWithMemory(opts, memory, providers) {
+    const r = opts.renderer ?? plainRenderer(opts.log ?? ((l) => console.log(l)));
+    const log = (l) => r.log(l);
     const repoRoot = opts.repoRoot;
     const config = await loadConfig(repoRoot);
     const maxTurns = opts.maxTurns ?? config.maxTurns;
-    if (!(await isGitRepo(repoRoot))) {
-        throw new Error('not a git repository; copperhead requires git for snapshots and rollback');
-    }
-    if ((await isDirty(repoRoot)) && !opts.allowDirty) {
-        throw new Error('working tree is dirty; commit your changes or pass --allow-dirty (snapshots via git stash create)');
-    }
+    await gitPreflight(repoRoot, { allowDirty: opts.allowDirty ?? false });
     const snap = await snapshot(repoRoot);
     const transcript = new Transcript(repoRoot);
     await transcript.init();
@@ -88,21 +126,123 @@ export async function runAgentLoop(opts) {
         repairCycles: 0,
         finishRequest: null,
     };
-    let provider = makeProvider(opts.model);
+    let provider = opts.provider ?? (await makeProvider(opts.model));
+    providers.add(provider);
+    // Deterministic, LLM-free metadata block: collected once, rendered onto all
+    // three surfaces (run-start event, summary ## Environment, CLI header) so
+    // they can never disagree (design D1, AC-8.1/8.4).
+    const startMs = Date.now();
+    const meta = await collectRunMeta({
+        repoRoot,
+        config,
+        maxTurns,
+        runId: path.basename(transcript.dir),
+        request: opts.request,
+        model: opts.model,
+        provider: provider.name,
+        interactive: opts.interactive ?? false,
+        input: opts.meta,
+    });
+    for (const line of renderCliHeader(meta))
+        log(line);
+    // Revisit obligations deferred while their artifact didn't exist re-open now
+    // if it does (must run before loadConstraints so the prompt sees the updated
+    // registry). They land in this run's fresh ledger, so finish gates on them.
+    const reopened = await reopenDeferredAffects(repoRoot, config, (key, item) => ctx.ledger.add('affects-revisit', `${key} affects ${item}`, key));
+    if (reopened.length) {
+        await transcript.event('deferred-affects-reopened', { reopened });
+        log(`re-opened ${reopened.length} deferred constraint revisit obligation(s)`);
+    }
     const constraints = await loadConstraints(repoRoot);
-    const system = await buildSystemPrompt(repoRoot, config, constraints);
+    let basePrompt = await buildSystemPrompt(repoRoot, config, constraints);
+    if (reopened.length) {
+        basePrompt += [
+            '',
+            '',
+            '## Reopened constraint revisits',
+            '',
+            'These constraints were recorded before their target artifact existed; the artifact now exists.',
+            'Revisit each against the design and close it with resolve_affected (batch the calls):',
+            ...reopened.map((r) => `- ${r.key} affects ${r.item}`),
+        ].join('\n');
+    }
+    // Cross-run memory is appended after the repo's own docs and constraints so
+    // that the in-repo sources of truth are what the model reads first.
+    const recalled = memory ? await memory.recall(opts.request) : null;
+    if (recalled) {
+        await transcript.event('synap-recall', { chars: recalled.length });
+        log('recalled prior context from Synap memory');
+    }
+    const system = recalled ? `${basePrompt}\n\n${recalled}` : basePrompt;
     const messages = [
         { role: 'system', content: system },
         { role: 'user', content: opts.stagePrompt ? `${opts.stagePrompt}\n\nRequest: ${opts.request}` : opts.request },
     ];
-    await transcript.event('run-start', { request: opts.request, model: opts.model, provider: provider.name });
+    await transcript.event('run-start', meta);
+    /**
+     * A memory write that fails is reported rather than swallowed, but it does
+     * not change the run's outcome: discarding a verified commit because a
+     * third-party write failed would be the worse trade.
+     */
+    const remember = async (run) => {
+        if (!memory)
+            return;
+        try {
+            await memory.record(run);
+            await transcript.event('synap-record', { outcome: run.outcome });
+        }
+        catch (err) {
+            const message = err.message;
+            log(`warning: Synap memory write failed (${message}); this run was not recorded`);
+            await transcript.event('synap-record-failed', { error: message });
+        }
+    };
     let tokensIn = 0;
     let tokensOut = 0;
+    let turnsUsed = 0;
+    const perTurn = [];
     let plan = null;
     let nudges = 0;
-    const fail = async (reason) => {
-        await transcript.event('run-failed', { reason });
-        await restore(repoRoot, snap);
+    const stats = (exitPath) => ({
+        exitPath,
+        turnsUsed,
+        maxTurns,
+        repairCyclesUsed: ctx.repairCycles,
+        maxRepairCycles: config.maxRepairCycles,
+        tokensIn,
+        tokensOut,
+        perTurn,
+        durationMs: Date.now() - startMs,
+    });
+    /** One outcome line, printed last at every terminal branch (AC-8.5). */
+    const outcomeLine = (s, extra) => [
+        s.exitPath,
+        ctx.lastErc ? `ERC ${ctx.lastErc.ok ? 'clean' : 'failing'}` : 'ERC not run',
+        ...(ctx.lastDrc ? [`DRC ${ctx.lastDrc.ok ? 'clean' : 'failing'}`] : []),
+        ...(extra ? [extra] : []),
+        fmtDuration(s.durationMs),
+        `${fmtTokens(s.tokensIn)} in / ${fmtTokens(s.tokensOut)} out`,
+    ].join(' · ');
+    const fail = async (reason, exitPath) => {
+        await transcript.event('run-failed', { reason, exitPath });
+        // Preserve the touched work as a stash entry before the rollback destroys
+        // it, so a budget-exhaustion (or any) failure is recoverable (issue #15).
+        const preserved = await preserveFailedRun(repoRoot, ctx.runId);
+        if (preserved)
+            await transcript.event('work-preserved', { stash: preserved });
+        // The rollback itself can fail (git in a bad state). That must not become
+        // an unhandled throw that skips run-end and summary.md — the summary is
+        // most valuable exactly when the tree is left in an unknown state.
+        let restoreError = null;
+        try {
+            await restore(repoRoot, snap);
+        }
+        catch (err) {
+            restoreError = err.message;
+            await transcript.event('restore-failed', { error: restoreError });
+        }
+        const runStats = stats(exitPath);
+        await transcript.event('run-end', runStats);
         const summaryPath = await transcript.writeSummary({
             request: opts.request,
             changeId: ctx.changeId,
@@ -115,22 +255,66 @@ export async function runAgentLoop(opts) {
             tokensOut,
             outcome: 'failure',
             openObligations: ctx.ledger.isClear ? null : ctx.ledger.describe(),
-            detail: reason,
+            detail: restoreError ? `${reason}\n\nROLLBACK FAILED: ${restoreError} — the working tree may be in a partial state; inspect it with git status/git diff before rerunning` : reason,
+            env: meta,
+            stats: runStats,
         });
         log(`run failed: ${reason}`);
-        log(`working tree restored to pre-run snapshot`);
+        if (restoreError) {
+            log(`WARNING: rollback failed (${restoreError}); the working tree may be in a partial state`);
+        }
+        else {
+            log(`working tree restored to pre-run snapshot`);
+        }
+        if (preserved) {
+            log(`failed work preserved: git stash entry "copperhead failed run ${ctx.runId}" (${preserved.slice(0, 10)}); recover with \`git stash apply\`, discard with \`git stash drop\``);
+        }
         log(`transcript: ${transcript.jsonlPath}`);
         log(`summary: ${summaryPath}`);
+        r.finish(outcomeLine(runStats));
         return {
             outcome: 'failure',
+            exitPath,
             summary: reason,
             transcriptDir: transcript.dir,
             filesTouched: [],
             commit: null,
         };
     };
-    for (let turn = 0; turn < maxTurns; turn++) {
+    let budget = maxTurns;
+    for (let turn = 0;; turn++) {
+        if (turn >= budget) {
+            // Budget exhausted. In an attended run this is a user decision made with
+            // the cost visible, not an unconditional rollback (issue #15).
+            const exhaustStats = {
+                maxTurns,
+                turnsUsed: turn,
+                tokensIn,
+                tokensOut,
+                filesTouched: [...ctx.filesTouched],
+                openObligations: ctx.ledger.openObligations.length,
+            };
+            let extra = 0;
+            if (opts.onBudgetExhausted) {
+                try {
+                    extra = Math.floor(await opts.onBudgetExhausted(exhaustStats));
+                }
+                catch {
+                    // A broken prompt (stdin closed mid-question, dying terminal) must
+                    // read as "declined" and take the preserve-and-restore path below,
+                    // not propagate past it and skip the rollback entirely.
+                    extra = 0;
+                }
+            }
+            if (!Number.isFinite(extra) || extra <= 0)
+                break;
+            budget += extra;
+            await transcript.event('budget-extended', { extraTurns: extra, budget, ...exhaustStats });
+            log(`turn budget extended by ${extra} (now ${budget})`);
+        }
         const tools = availableTools(ctx).map((t) => t.schema);
+        r.turnStart(turn + 1, maxTurns, tokensIn, tokensOut);
+        r.status('thinking');
         let res;
         try {
             res = await withRetry(() => provider.chat(messages, tools), {
@@ -144,14 +328,20 @@ export async function runAgentLoop(opts) {
                     log(`failing over ${provider.name} → ${fallback.name}`);
                     await transcript.event('provider-failover', { from: provider.name, to: fallback.name });
                     provider = fallback;
+                    providers.add(provider);
                     turn--;
                     continue;
                 }
             }
-            return fail(`provider error: ${err.message}`);
+            return fail(`provider error: ${err.message}`, 'provider-error');
         }
+        finally {
+            r.status(null);
+        }
+        turnsUsed = turn + 1;
         tokensIn += res.usage.inputTokens;
         tokensOut += res.usage.outputTokens;
+        perTurn.push({ turn: turn + 1, in: res.usage.inputTokens, out: res.usage.outputTokens });
         await transcript.event('assistant', { text: res.text, toolCalls: res.toolCalls });
         if (res.text) {
             if (!plan)
@@ -160,28 +350,33 @@ export async function runAgentLoop(opts) {
         }
         messages.push({ role: 'assistant', content: res.text, toolCalls: res.toolCalls });
         if (!res.toolCalls.length) {
+            // Only *consecutive* tool-less turns are a stall. Providers emit the
+            // occasional empty completion mid-run (observed live: three empties
+            // spread across 31 productive turns); a cumulative counter turns those
+            // into a full rollback of an otherwise-converging run.
             if (nudges++ >= 2)
-                return fail('model stopped calling tools without finishing');
+                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.',
             });
             continue;
         }
+        nudges = 0;
         for (const call of res.toolCalls) {
             const result = await dispatchTool(ctx, call.name, call.args);
             await transcript.event('tool', { name: call.name, args: call.args, result });
-            log(`  [${call.name}] ${result.split('\n')[0]}`);
+            r.toolResult(call.name, result.split('\n')[0] ?? '');
             messages.push({ role: 'tool', toolCallId: call.id, content: result });
         }
         if (ctx.repairCycles > config.maxRepairCycles) {
-            return fail(`repair cycles exhausted (${config.maxRepairCycles}); violations persist`);
+            return fail(`repair cycles exhausted (${config.maxRepairCycles}); violations persist`, 'repair-cycles-exhausted');
         }
-        const remaining = maxTurns - turn - 1;
+        const remaining = budget - turn - 1;
         if (remaining === 5 && !ctx.finishRequest) {
             messages.push({
                 role: 'user',
-                content: 'Only 5 turns remain. Converge now: finish the minimal correct edit set, run run_erc (and run_drc if the board changed), run check_drift, then call finish.',
+                content: 'Only 5 turns remain. Converge now: finish the minimal correct edit set, run run_erc (and run_drc if the board changed), run check_drift, then call finish. Batch independent tool calls in a single response (e.g. all resolve_affected calls at once) instead of one per turn.',
             });
         }
         if (ctx.finishRequest) {
@@ -190,6 +385,8 @@ export async function runAgentLoop(opts) {
             if (outcome === 'refuse') {
                 await restore(repoRoot, snap);
                 await transcript.event('run-refused', { summary });
+                const runStats = stats('refused');
+                await transcript.event('run-end', runStats);
                 await transcript.writeSummary({
                     request: opts.request,
                     changeId: ctx.changeId,
@@ -203,9 +400,30 @@ export async function runAgentLoop(opts) {
                     outcome: 'aborted',
                     openObligations: null,
                     detail: `REFUSED: ${summary}`,
+                    env: meta,
+                    stats: runStats,
+                });
+                // Refusals are the most valuable thing to remember: they encode a budget
+                // or constraint that this user's designs keep running into.
+                await remember({
+                    request: opts.request,
+                    outcome: 'refused',
+                    summary,
+                    changeId: ctx.changeId,
+                    filesTouched: [],
+                    decisions: ctx.decisions,
+                    verification: 'n/a (refused before verification)',
                 });
                 log(`refused: ${summary}`);
-                return { outcome: 'refused', summary, transcriptDir: transcript.dir, filesTouched: [], commit: null };
+                r.finish(outcomeLine(runStats));
+                return {
+                    outcome: 'refused',
+                    exitPath: 'refused',
+                    summary,
+                    transcriptDir: transcript.dir,
+                    filesTouched: [],
+                    commit: null,
+                };
             }
             const verification = [
                 ctx.lastErc ? `ERC ${ctx.lastErc.ok ? 'clean' : 'FAILING'}` : 'ERC not required',
@@ -223,6 +441,8 @@ export async function runAgentLoop(opts) {
                 if (untracked)
                     log(`new files:\n${untracked}`);
                 await restore(repoRoot, snap);
+                const runStats = stats('done');
+                await transcript.event('run-end', runStats);
                 await transcript.writeSummary({
                     request: opts.request,
                     changeId: ctx.changeId,
@@ -236,8 +456,18 @@ export async function runAgentLoop(opts) {
                     outcome: 'success',
                     openObligations: null,
                     detail: 'dry run: changes reverted',
+                    env: meta,
+                    stats: runStats,
                 });
-                return { outcome: 'success', summary, transcriptDir: transcript.dir, filesTouched: files, commit: null };
+                r.finish(outcomeLine(runStats, 'dry run: changes reverted'));
+                return {
+                    outcome: 'success',
+                    exitPath: 'done',
+                    summary,
+                    transcriptDir: transcript.dir,
+                    filesTouched: files,
+                    commit: null,
+                };
             }
             await appendChangelog(repoRoot, config, {
                 changeId: ctx.changeId,
@@ -247,15 +477,35 @@ export async function runAgentLoop(opts) {
             });
             ctx.ledger.clear('changelog');
             const commitMsg = `copperhead: ${opts.request}\n\n${summary}\n\nVerification: ${verification}`;
-            const commit = await commitAll(repoRoot, commitMsg);
+            // A git failure here (e.g. `git add -A` exiting 128 on an embedded repo)
+            // must land in summary.md as an outcome, not escape as a stack trace
+            // (AC-8.6): roll back per the snapshot contract and report commit-failed.
+            let commit;
+            try {
+                commit = await commitAll(repoRoot, commitMsg);
+            }
+            catch (err) {
+                return fail(`commit failed: ${err.message}`, 'commit-failed');
+            }
             if (ctx.changeId && existsSync(path.join(repoRoot, 'openspec', 'config.yaml'))) {
-                const arch = await openspecArchive(repoRoot, ctx.changeId);
-                await transcript.event('openspec-archive', { changeId: ctx.changeId, ok: arch.ok });
-                if (arch.ok && (await isDirty(repoRoot))) {
-                    await commitAll(repoRoot, `copperhead: archive change ${ctx.changeId}`);
+                // The verified commit already exists; discarding it because archive
+                // housekeeping failed would be the worse trade, so this is a warning.
+                try {
+                    const arch = await openspecArchive(repoRoot, ctx.changeId);
+                    await transcript.event('openspec-archive', { changeId: ctx.changeId, ok: arch.ok });
+                    if (arch.ok && (await isDirty(repoRoot))) {
+                        await commitAll(repoRoot, `copperhead: archive change ${ctx.changeId}`);
+                    }
+                }
+                catch (err) {
+                    const message = err.message;
+                    log(`warning: openspec archive failed (${message}); the run commit itself succeeded`);
+                    await transcript.event('openspec-archive-failed', { changeId: ctx.changeId, error: message });
                 }
             }
             await transcript.event('run-committed', { commit, files });
+            const runStats = stats('done');
+            await transcript.event('run-end', runStats);
             await transcript.writeSummary({
                 request: opts.request,
                 changeId: ctx.changeId,
@@ -268,12 +518,31 @@ export async function runAgentLoop(opts) {
                 tokensOut,
                 outcome: 'success',
                 openObligations: null,
+                env: meta,
+                stats: runStats,
+            });
+            await remember({
+                request: opts.request,
+                outcome: 'success',
+                summary,
+                changeId: ctx.changeId,
+                filesTouched: files,
+                decisions: ctx.decisions,
+                verification,
             });
             log(`committed ${commit.slice(0, 10)} (${files.length} file(s))`);
-            return { outcome: 'success', summary, transcriptDir: transcript.dir, filesTouched: files, commit };
+            r.finish(outcomeLine(runStats, `committed ${commit.slice(0, 10)}`));
+            return {
+                outcome: 'success',
+                exitPath: 'done',
+                summary,
+                transcriptDir: transcript.dir,
+                filesTouched: files,
+                commit,
+            };
         }
     }
     const filesAfter = await changedFiles(repoRoot, snap.head);
-    return fail(`turn budget exhausted (${maxTurns} turns, ${filesAfter.length} files touched but unverified)`);
+    return fail(`turn budget exhausted (${budget} turns, ${filesAfter.length} files touched but unverified)`, 'turn-budget-exhausted');
 }
 //# sourceMappingURL=loop.js.map