copperhead 0.3.0 → 0.5.0

package/src/agent/runmeta.ts

@@ -0,0 +1,198 @@
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { readFile, readdir } from 'node:fs/promises';
+import { loadConstraints } from '../memory/constraints.js';
+import { kicadCliVersion } from '../kicad/cli.js';
+import { branchName, headCommit, uncommittedCount } from '../util/git.js';
+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';
+  modelSource?: ModelSource;
+  version?: string;
+  kicadCliVersion?: string;
+  stage?: { name: string; index: number; total: number };
+  brief?: { path: string; sha256: string };
+}
+
+/**
+ * Everything a run needs to be self-describing (AC-8.1). Collected once,
+ * rendered onto three surfaces: run-start event, summary.md ## Environment,
+ * and the live CLI header. Probe failures are nulls, never errors (AC-8.3).
+ */
+export interface RunMeta {
+  request: string;
+  model: string;
+  provider: string;
+  modelSource: ModelSource | null;
+  runId: string;
+  startedAt: string;
+  command: 'do' | 'create' | 'sync' | null;
+  interactive: boolean;
+  stage: { name: string; index: number; total: number } | null;
+  brief: { path: string; sha256: string } | null;
+  versions: {
+    copperhead: string | null;
+    installPath: string | null;
+    kicadCli: string | null;
+    node: string;
+    platform: string;
+  };
+  config: {
+    schematic: string | null;
+    board: string | null;
+    docs: string;
+    maxTurns: number;
+    maxRepairCycles: number;
+    budgets: Record<string, number>;
+  };
+  git: {
+    commit: string | null;
+    branch: string | null;
+    dirty: boolean | null;
+    uncommittedFiles: number | null;
+    preCommitHookInstalled: boolean | null;
+  };
+  openConstraints: number | null;
+  priorRuns: number | null;
+}
+
+/** A metadata probe must never fail the run it describes (design D4). */
+async function probe<T>(fn: () => Promise<T> | T): Promise<T | null> {
+  try {
+    return await fn();
+  } catch {
+    return null;
+  }
+}
+
+function packageRoot(): string {
+  // src/agent/ and dist/agent/ both sit two levels below the package root.
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+function ownVersion(): string {
+  const { version } = createRequire(import.meta.url)('../../package.json') as { version: string };
+  return version;
+}
+
+export interface CollectRunMetaOptions {
+  repoRoot: string;
+  config: CopperheadConfig;
+  /** Effective turn budget for this run (flag override already applied). */
+  maxTurns: number;
+  runId: string;
+  request: string;
+  model: string;
+  provider: string;
+  interactive: boolean;
+  input?: RunMetaInput | undefined;
+}
+
+export async function collectRunMeta(opts: CollectRunMetaOptions): Promise<RunMeta> {
+  const { repoRoot, config, input } = opts;
+  const [copperhead, kicadCli, commit, branch, uncommitted, hook, openConstraints, priorRuns] = await Promise.all([
+    probe(() => input?.version ?? ownVersion()),
+    probe(() => input?.kicadCliVersion ?? kicadCliVersion()),
+    probe(() => headCommit(repoRoot)),
+    probe(() => branchName(repoRoot)),
+    probe(() => uncommittedCount(repoRoot)),
+    probe(async () => {
+      const hookText = await readFile(path.join(repoRoot, '.git', 'hooks', 'pre-commit'), 'utf8');
+      return hookText.includes('copperhead');
+    }).then((v) => v ?? false),
+    probe(async () => Object.keys(await loadConstraints(repoRoot)).length),
+    probe(async () => {
+      const entries = await readdir(path.join(repoRoot, '.copperhead', 'runs'));
+      return entries.filter((e) => e !== opts.runId).length;
+    }).then((v) => v ?? 0),
+  ]);
+
+  return {
+    request: opts.request,
+    model: opts.model,
+    provider: opts.provider,
+    modelSource: input?.modelSource ?? null,
+    runId: opts.runId,
+    startedAt: new Date().toISOString(),
+    command: input?.command ?? null,
+    interactive: opts.interactive,
+    stage: input?.stage ?? null,
+    brief: input?.brief ?? null,
+    versions: {
+      copperhead,
+      installPath: await probe(packageRoot),
+      kicadCli,
+      node: process.version,
+      platform: `${process.platform}-${process.arch}`,
+    },
+    config: {
+      schematic: config.schematic,
+      board: config.board,
+      docs: config.docs,
+      maxTurns: opts.maxTurns,
+      maxRepairCycles: config.maxRepairCycles,
+      budgets: config.budgets,
+    },
+    git: {
+      commit,
+      branch,
+      dirty: uncommitted === null ? null : uncommitted > 0,
+      uncommittedFiles: uncommitted,
+      preCommitHookInstalled: hook,
+    },
+    openConstraints,
+    priorRuns,
+  };
+}
+
+const unk = (v: string | null | undefined): string => v ?? 'unknown';
+
+/** ≤ 2 lines, printed before the first turn (AC-8.4). */
+export function renderCliHeader(meta: RunMeta): string[] {
+  const v = meta.versions;
+  const line1 = [
+    `copperhead v${unk(v.copperhead)}${v.installPath ? ` (${v.installPath})` : ''}`,
+    `kicad-cli ${unk(v.kicadCli)}`,
+    `node ${v.node}`,
+    v.platform,
+  ].join(' · ');
+
+  const repoState =
+    meta.git.dirty === null
+      ? 'unknown'
+      : meta.git.dirty
+        ? `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}`,
+  ].join(' · ');
+  return [line1, line2];
+}
+
+/** The `## Environment` section of summary.md; values mirror the run-start event (AC-8.4). */
+export function renderEnvironmentSection(meta: RunMeta): string[] {
+  const v = meta.versions;
+  const c = meta.config;
+  const g = meta.git;
+  return [
+    `## Environment`,
+    ``,
+    `- **Run:** ${meta.runId} · ${unk(meta.command)} · started ${meta.startedAt} · ${meta.interactive ? 'interactive' : 'autonomous'}`,
+    ...(meta.stage ? [`- **Stage:** ${meta.stage.name} (${meta.stage.index}/${meta.stage.total})`] : []),
+    ...(meta.brief ? [`- **Brief:** ${meta.brief.path} (sha256 ${meta.brief.sha256.slice(0, 12)}…)`] : []),
+    `- **Model:** ${meta.model} (${meta.provider}, via ${unk(meta.modelSource)})`,
+    `- **copperhead:** v${unk(v.copperhead)}${v.installPath ? ` at ${v.installPath}` : ''}`,
+    `- **Tooling:** kicad-cli ${unk(v.kicadCli)} · node ${v.node} · ${v.platform}`,
+    `- **Config:** schematic ${c.schematic ?? 'null'} · board ${c.board ?? 'null'} · docs ${c.docs} · maxTurns ${c.maxTurns} · maxRepairCycles ${c.maxRepairCycles} · budgets ${JSON.stringify(c.budgets)}`,
+    `- **Repo:** ${unk(g.branch)}@${g.commit ?? 'unknown'} · ${g.dirty === null ? 'unknown' : g.dirty ? `dirty (${g.uncommittedFiles} uncommitted)` : 'clean'} · pre-commit hook ${g.preCommitHookInstalled === null ? 'unknown' : g.preCommitHookInstalled ? 'installed' : 'absent'}`,
+    `- **Memory:** ${meta.openConstraints ?? 'unknown'} open constraint(s) · ${meta.priorRuns ?? 'unknown'} prior run(s)`,
+  ];
+}

package/src/agent/tools.ts

@@ -1,13 +1,13 @@
 import path from 'node:path';
-import { writeFile, mkdir, appendFile } from 'node:fs/promises';
+import { writeFile, mkdir, appendFile, readFile } from 'node:fs/promises';
 import type { ToolSchema } from './types.js';
 import { toolReadFile, toolWriteFile, toolEditFile, toolSearch } from './filetools.js';
 import { resolveInRepo, isKicadFile } from '../util/paths.js';
-import { runErc, runDrc, exportSvg, exportFab } from '../kicad/cli.js';
+import { runErc, runDrc, exportSvg, exportFab, kicadLoadError, isProbeableKicadFile } from '../kicad/cli.js';
 import { formatViolations, type CheckReport } from '../kicad/report.js';
 import { listSymbols, listNets } from '../kicad/sexp.js';
 import { checkDrift } from '../memory/drift.js';
-import { saveConstraint } from '../memory/constraints.js';
+import { saveConstraint, classifyAffectsTarget, affectsTargetExists } from '../memory/constraints.js';
 import { openspecValidate } from '../openspec/cli.js';
 import { existsSync } from 'node:fs';
 import type { CopperheadConfig } from '../config.js';
@@ -99,7 +99,11 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: false,
     handler: async (ctx, args) => {
-      const matches = await toolSearch(ctx.repoRoot, str(args, 'pattern'), args.glob as string | undefined);
+      const pattern = args.pattern;
+      if (typeof pattern !== 'string' || pattern.trim() === '') {
+        return 'error: search requires a non-empty regex in "pattern" (narrow by file with "glob", e.g. {"pattern": "GPIO", "glob": "**/*.md"}); to list files, use a broad pattern like "." with a glob';
+      }
+      const matches = await toolSearch(ctx.repoRoot, pattern, args.glob as string | undefined);
       if (!matches.length) return 'no matches';
       return matches.map((m) => `${m.file}:${m.line}: ${m.text}`).join('\n');
     },
@@ -213,6 +217,14 @@ export const TOOLS: ToolDef[] = [
     requiresUnlock: true,
     handler: async (ctx, args) => {
       const rel = str(args, 'path');
+      const abs = resolveInRepo(ctx.repoRoot, rel);
+      // Text edits can corrupt an s-expression file in ways the editor cannot
+      // see; a corrupted file then fails every later ERC/DRC with an opaque
+      // error. Validate loadability with KiCad itself and roll the edit back
+      // rather than letting the file drift unusable. Only schematics and
+      // boards are probeable; .kicad_pro/.kicad_sym/.kicad_mod edits must not
+      // be probed (a sch/pcb probe rejects them wholesale).
+      const before = isProbeableKicadFile(rel) ? await readFile(abs, 'utf8') : null;
       const res = await toolEditFile(
         ctx.repoRoot,
         rel,
@@ -220,6 +232,23 @@ export const TOOLS: ToolDef[] = [
         args.new_string as string,
         args.replace_all === true,
       );
+      if (before !== null) {
+        const loadErr = await kicadLoadError(abs);
+        if (loadErr) {
+          const after = await readFile(abs, 'utf8');
+          await writeFile(abs, before, 'utf8');
+          if (await kicadLoadError(abs)) {
+            // The file was already unloadable before this edit. Reverting
+            // would deadlock incremental repair (every partial fix undone
+            // unless one edit fixes the whole file), so keep the edit and
+            // keep the pressure on with the probe output.
+            await writeFile(abs, after, 'utf8');
+            markTouched(ctx, rel);
+            return `${res}\nnote: ${rel} was already unloadable before this edit, so the edit is KEPT. Keep repairing until it loads. kicad-cli says:\n${loadErr}`;
+          }
+          return `edit REVERTED: it would make ${rel} unloadable in KiCad. kicad-cli says:\n${loadErr}\nRe-read the surrounding file text and make a smaller, syntactically complete edit.`;
+        }
+      }
       markTouched(ctx, rel);
       return res;
     },
@@ -250,7 +279,8 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: false,
     handler: async (ctx) => {
-      if (!ctx.config.schematic) return 'no schematic configured';
+      if (!ctx.config.schematic)
+        return 'no schematic configured; ERC does not apply yet — skip it until a schematic exists and is set in .copperhead/config.json';
       const report = await runErc(path.join(ctx.repoRoot, ctx.config.schematic));
       ctx.lastErc = report;
       if (report.ok) ctx.ledger.clear('erc');
@@ -266,7 +296,8 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: false,
     handler: async (ctx) => {
-      if (!ctx.config.board) return 'no board configured';
+      if (!ctx.config.board)
+        return 'no board configured; DRC does not apply yet — skip it until a board exists and is set in .copperhead/config.json';
       const report = await runDrc(path.join(ctx.repoRoot, ctx.config.board));
       ctx.lastDrc = report;
       if (report.ok) ctx.ledger.clear('drc');
@@ -325,7 +356,16 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: false,
     handler: async (ctx) => {
-      if (!ctx.config.schematic) return 'no schematic configured';
+      // No schematic yet means there is nothing for the docs to drift against,
+      // so the obligation is vacuously satisfied and must be cleared. Returning
+      // without clearing deadlocks every docs-only stage of the create pipeline
+      // (spec-seed, architecture, part-selection all run before the schematic
+      // exists): a doc edit opens the drift obligation, this is the only tool
+      // that clears it, and finish refuses while any obligation is open.
+      if (!ctx.config.schematic) {
+        ctx.ledger.clear('drift');
+        return 'no schematic configured; drift vacuously clean';
+      }
       const mismatches = await checkDrift(ctx.repoRoot, ctx.config.docs, ctx.config.schematic);
       if (!mismatches.length) {
         ctx.ledger.clear('drift');
@@ -357,6 +397,19 @@ export const TOOLS: ToolDef[] = [
     handler: async (ctx, args) => {
       const key = str(args, 'key');
       const affects = (args.affects as string[]) ?? [];
+      // An affects item whose target artifact is not built yet (no schematic or
+      // board configured, no BOM.md) has nothing to revisit; opening an
+      // obligation now only forces a ceremonial "not yet created" resolution.
+      // Defer it in the registry instead — reopenDeferredAffects re-opens it at
+      // the start of the first run where the artifact exists, which is when the
+      // revisit actually means something.
+      const deferred: string[] = [];
+      const openNow: string[] = [];
+      for (const item of affects) {
+        const target = classifyAffectsTarget(item);
+        if (target && !affectsTargetExists(target, ctx.repoRoot, ctx.config)) deferred.push(item);
+        else openNow.push(item);
+      }
       await saveConstraint(ctx.repoRoot, key, {
         ...(args.min !== undefined ? { min: args.min as number } : {}),
         ...(args.max !== undefined ? { max: args.max as number } : {}),
@@ -364,33 +417,84 @@ export const TOOLS: ToolDef[] = [
         ...(args.value !== undefined ? { value: args.value as string } : {}),
         source: str(args, 'source'),
         affects,
+        ...(deferred.length ? { deferred } : {}),
       });
-      ctx.ledger.onConstraintChange(key, affects);
+      ctx.ledger.onConstraintChange(key, openNow);
       ctx.ledger.clear('constraint-dual-write', key);
-      return `constraint ${key} recorded; revisit obligations opened for: ${affects.join(', ') || '(none)'}`;
+      const parts = [`constraint ${key} recorded`];
+      parts.push(`revisit obligations opened for: ${openNow.join(', ') || '(none)'}`);
+      if (deferred.length) {
+        parts.push(
+          `deferred until the target artifact exists (no resolve_affected needed now): ${deferred.join(', ')}`,
+        );
+      }
+      return parts.join('; ');
     },
   },
   {
     schema: {
       name: 'resolve_affected',
       description:
-        'Explicitly resolve an affects-revisit obligation: state whether the affected item changed or why no change is needed.',
+        'Explicitly resolve affects-revisit obligations: state whether each affected item changed or why no change is needed. Pass resolutions[] to clear many in one call, or the single constraint_key/item/resolution form.',
       parameters: {
         type: 'object',
         properties: {
           constraint_key: { type: 'string' },
           item: { type: 'string' },
           resolution: { type: 'string', description: '"changed: ..." or "no change needed: <reason>"' },
+          resolutions: {
+            type: 'array',
+            description: 'batch form: resolve many obligations in one call',
+            items: {
+              type: 'object',
+              properties: {
+                constraint_key: { type: 'string' },
+                item: { type: 'string' },
+                resolution: { type: 'string' },
+              },
+              required: ['constraint_key', 'item', 'resolution'],
+            },
+          },
         },
-        required: ['constraint_key', 'item', 'resolution'],
+        required: [],
       },
     },
     requiresUnlock: true,
     handler: async (ctx, args) => {
-      const detail = `${str(args, 'constraint_key')} affects ${str(args, 'item')}`;
-      ctx.ledger.clear('affects-revisit', detail);
-      ctx.decisions.push(`[affects] ${detail}: ${str(args, 'resolution')}`);
-      return `resolved: ${detail}`;
+      // An item that matches nothing must not read as success: the model would
+      // move on believing the obligation closed, and only find out at finish.
+      const resolveOne = (constraintKey: string, item: string, resolution: string): string => {
+        const detail = `${constraintKey} affects ${item}`;
+        if (!ctx.ledger.clear('affects-revisit', detail)) {
+          const open = ctx.ledger.openOfKind('affects-revisit');
+          if (!open.length) return `error: no open affects-revisit obligation matches "${detail}"`;
+          return [
+            `error: no open affects-revisit obligation matches "${detail}".`,
+            'Match these exactly:',
+            ...open.map((o) => `  - ${o.detail}`),
+          ].join('\n');
+        }
+        ctx.decisions.push(`[affects] ${detail}: ${resolution}`);
+        return `resolved: ${detail}`;
+      };
+
+      const batch = args.resolutions;
+      if (Array.isArray(batch) && batch.length) {
+        // Entries resolve independently: one bad key must not waste the call.
+        return batch
+          .map((entry, i) => {
+            const e = entry as Record<string, unknown>;
+            if (typeof e?.constraint_key !== 'string' || typeof e?.item !== 'string' || typeof e?.resolution !== 'string') {
+              return `error: resolutions[${i}] needs string constraint_key, item, and resolution`;
+            }
+            return resolveOne(e.constraint_key, e.item, e.resolution);
+          })
+          .join('\n');
+      }
+      if (typeof args.constraint_key === 'string' && typeof args.item === 'string' && typeof args.resolution === 'string') {
+        return resolveOne(args.constraint_key, args.item, args.resolution);
+      }
+      return 'error: pass either resolutions: [{constraint_key, item, resolution}, ...] or the single form constraint_key + item + resolution';
     },
   },
   {

package/src/agent/transcript.ts

@@ -1,6 +1,31 @@
 import { appendFile, mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { redactSecrets } from '../util/redact.js';
+import { renderEnvironmentSection, type RunMeta } from './runmeta.js';
+import { fmtDuration, fmtTokens } from './render.js';
+
+/** How a run terminated — the single most-queried triage fact (AC-8.5). */
+export type ExitPath =
+  | 'done'
+  | 'refused'
+  | 'turn-budget-exhausted'
+  | 'repair-cycles-exhausted'
+  | 'commit-failed'
+  | 'provider-error'
+  | 'stalled';
+
+/** Post-run addenda recorded at every terminal branch (AC-8.5). */
+export interface RunStats {
+  exitPath: ExitPath;
+  turnsUsed: number;
+  maxTurns: number;
+  repairCyclesUsed: number;
+  maxRepairCycles: number;
+  tokensIn: number;
+  tokensOut: number;
+  perTurn: { turn: number; in: number; out: number }[];
+  durationMs: number;
+}
 
 export interface RunSummaryData {
   request: string;
@@ -15,6 +40,23 @@ export interface RunSummaryData {
   outcome: 'success' | 'failure' | 'aborted';
   openObligations: string | null;
   detail?: string;
+  env?: RunMeta;
+  stats?: RunStats;
+}
+
+function renderRunStats(s: RunStats): string[] {
+  return [
+    `## Run stats`,
+    ``,
+    `- **Exit path:** ${s.exitPath}`,
+    `- **Turns:** ${s.turnsUsed} / ${s.maxTurns}`,
+    `- **Repair cycles:** ${s.repairCyclesUsed} / ${s.maxRepairCycles}`,
+    `- **Tokens:** ${fmtTokens(s.tokensIn)} in / ${fmtTokens(s.tokensOut)} out`,
+    `- **Duration:** ${fmtDuration(s.durationMs)}`,
+    ...(s.perTurn.length
+      ? [`- **Per turn:** ${s.perTurn.map((t) => `${t.turn}: ${t.in}/${t.out}`).join(' · ')}`]
+      : []),
+  ];
 }
 
 /**
@@ -38,6 +80,10 @@ export class Transcript {
 
   async event(type: string, data: unknown): Promise<void> {
     const line = redactSecrets(JSON.stringify({ ts: new Date().toISOString(), type, data }));
+    // The audit trail must survive anything that happens to the working tree
+    // mid-run (a rollback path once deleted this directory); losing an event
+    // is acceptable, crashing the run to report one is not.
+    await mkdir(this.dir, { recursive: true });
     await appendFile(this.jsonlPath, line + '\n', 'utf8');
   }
 
@@ -50,6 +96,8 @@ export class Transcript {
       `- **OpenSpec change:** ${s.changeId ?? 'n/a'}`,
       `- **Tokens:** ${s.tokensIn} in / ${s.tokensOut} out`,
       ``,
+      ...(s.env ? [...renderEnvironmentSection(s.env), ``] : []),
+      ...(s.stats ? [...renderRunStats(s.stats), ``] : []),
       `## Plan`,
       ``,
       s.plan ?? '(no plan recorded)',
@@ -72,6 +120,7 @@ export class Transcript {
     }
     if (s.detail) lines.push('', '## Detail', '', s.detail);
     const out = path.join(this.dir, 'summary.md');
+    await mkdir(this.dir, { recursive: true });
     await writeFile(out, redactSecrets(lines.join('\n') + '\n'), 'utf8');
     return out;
   }

package/src/agent/types.ts

@@ -29,4 +29,5 @@ export interface ChatOpts {
 export interface Provider {
   readonly name: string;
   chat(messages: Msg[], tools: ToolSchema[], opts?: ChatOpts): Promise<Turn>;
+  close?(): Promise<void>;
 }

package/src/cli.ts

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { createInterface } from 'node:readline/promises';
 import { loadConfig, resolveModel } from './config.js';
 import { runInit, InitError } from './memory/scaffold.js';
 import { runCheck } from './commands/check.js';
 import { syncVerify, syncResolve, formatSyncReport } from './commands/sync.js';
 import { runCreate } from './commands/create.js';
-import { runAgentLoop } from './agent/loop.js';
+import { runAgentLoop, type BudgetExhaustedStats } from './agent/loop.js';
+import { makeRenderer } from './agent/render.js';
 import { kicadCliVersion } from './kicad/cli.js';
 import { loadEnvFile } from './util/env.js';
 
@@ -17,6 +19,12 @@ import { loadEnvFile } from './util/env.js';
 // A real environment variable always beats the file.
 loadEnvFile(process.cwd());
 
+// Single source of truth for the version. Both src/cli.ts (via tsx) and
+// dist/cli.js sit one level below the package root, so the path holds either
+// way, and a release can never ship a version string that disagrees with the
+// package it was published as.
+const { version } = createRequire(import.meta.url)('../package.json') as { version: string };
+
 const program = new Command();
 
 const repoOf = (opts: { repo?: string }): string => path.resolve(opts.repo ?? process.cwd());
@@ -28,12 +36,32 @@ async function confirmTty(question: string): Promise<boolean> {
   return /^y(es)?$/i.test(answer.trim());
 }
 
+/**
+ * Attended runs get a decision point instead of a rollback when the turn
+ * budget runs out (issue #15). Non-TTY (CI, pipes) keeps fail-and-restore.
+ */
+function budgetContinuePrompt(): ((stats: BudgetExhaustedStats) => Promise<number>) | undefined {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return undefined;
+  return async (stats) => {
+    // ceil of the ORIGINAL budget (design D1), so repeat extensions offer the
+    // same increment instead of escalating with the extended turn count.
+    const extra = Math.ceil(stats.maxTurns / 2);
+    const k = (n: number) => `${(n / 1000).toFixed(1)}k`;
+    const q = `Turn budget exhausted (${stats.turnsUsed} turns, ${k(stats.tokensIn)} in / ${k(stats.tokensOut)} out, ${stats.filesTouched.length} file(s) touched, ${stats.openObligations} open obligation(s)). Continue with ${extra} more turns?`;
+    return (await confirmTty(q)) ? extra : 0;
+  };
+}
+
 program
   .name('copperhead')
   .description('Cursor for circuit boards: an AI agent for real KiCad repositories')
-  .version('0.1.0')
+  .version(version)
   .option('--repo <path>', 'target repository (default: cwd)')
-  .option('--json', 'machine-readable output');
+  .option('--json', 'machine-readable output')
+  .option('--plain', 'plain log-style output (no interactive status line)');
+
+const rendererOf = () =>
+  makeRenderer({ json: Boolean(program.opts().json), plain: Boolean(program.opts().plain) });
 
 program
   .command('init')
@@ -89,7 +117,7 @@ program
   .command('do')
   .description('the core loop: propose, edit, verify, propagate, commit')
   .argument('<request>', 'the change request in natural language')
-  .option('--model <model>', 'gpt-5 | claude (or a full model id)')
+  .option('--model <model>', 'codex | gpt-5 | claude (or a provider-specific model id)')
   .option('--max-turns <n>', 'turn budget for this run')
   .option('--allow-dirty', 'allow a dirty tree (snapshot via git stash create)')
   .option('--dry-run', 'propose the diff, write nothing')
@@ -101,9 +129,10 @@ program
     ) => {
       const repo = repoOf(program.opts());
       try {
-        await kicadCliVersion();
+        const kicadVer = await kicadCliVersion();
         const config = await loadConfig(repo);
-        const model = resolveModel(opts.model, config);
+        const { model, source } = resolveModel(opts.model, config);
+        const continuePrompt = budgetContinuePrompt();
         const res = await runAgentLoop({
           repoRoot: repo,
           request,
@@ -113,6 +142,9 @@ program
           dryRun: opts.dryRun ?? false,
           interactive: opts.interactive ?? false,
           confirm: confirmTty,
+          ...(continuePrompt ? { onBudgetExhausted: continuePrompt } : {}),
+          renderer: rendererOf(),
+          meta: { command: 'do', modelSource: source, version, kicadCliVersion: kicadVer },
         });
         if (program.opts().json) console.log(JSON.stringify(res, null, 2));
         process.exit(res.outcome === 'failure' ? 1 : 0);
@@ -131,7 +163,7 @@ program
   .action(async (opts: { model?: string; dryRun?: boolean }) => {
     const repo = repoOf(program.opts());
     try {
-      await kicadCliVersion();
+      const kicadVer = await kicadCliVersion();
       const report = await syncVerify(repo);
       const json = Boolean(program.opts().json);
       if (json) console.log(JSON.stringify(report, null, 2));
@@ -147,8 +179,11 @@ program
         process.exit(0);
       }
       const config = await loadConfig(repo);
-      const model = resolveModel(opts.model, config);
-      const res = await syncResolve(repo, report, model, json ? () => {} : (s) => console.log(s));
+      const { model, source } = resolveModel(opts.model, config);
+      const res = await syncResolve(repo, report, model, json ? () => {} : (s) => console.log(s), {
+        renderer: rendererOf(),
+        meta: { command: 'sync', modelSource: source, version, kicadCliVersion: kicadVer },
+      });
       process.exit(res.ok ? 0 : 1);
     } catch (err) {
       console.error((err as Error).message);
@@ -160,20 +195,24 @@ program
   .command('create')
   .description('Mode A: full pipeline from a product brief to the output package')
   .requiredOption('--brief <file>', 'product brief (markdown)')
-  .option('--model <model>', 'gpt-5 | claude')
+  .option('--model <model>', 'codex | gpt-5 | claude')
   .option('--interactive', 're-enable the human gates (spec approval, pre-export)')
   .action(async (opts: { brief: string; model?: string; interactive?: boolean }) => {
     const repo = repoOf(program.opts());
     try {
-      await kicadCliVersion();
+      const kicadVer = await kicadCliVersion();
       const config = await loadConfig(repo);
-      const model = resolveModel(opts.model, config);
+      const { model, source } = resolveModel(opts.model, config);
+      const continuePrompt = budgetContinuePrompt();
       const res = await runCreate({
         repoRoot: repo,
         briefPath: opts.brief,
         model,
         interactive: opts.interactive ?? false,
+        ...(continuePrompt ? { onBudgetExhausted: continuePrompt } : {}),
         log: (s) => console.log(s),
+        renderer: rendererOf(),
+        meta: { command: 'create', modelSource: source, version, kicadCliVersion: kicadVer },
       });
       process.exit(res.ok ? 0 : 1);
     } catch (err) {