copperhead 0.7.0 → 0.8.0

package/dist/util/select.js

@@ -0,0 +1,172 @@
+/**
+ * Minimal arrow-key select menu for TTY prompts (no extra deps).
+ * Renders an in-place "dropdown" navigable with ↑/↓ + Enter.
+ */
+import { copper, dim } from '../agent/theme.js';
+const HIDE = '\x1b[?25l';
+const SHOW = '\x1b[?25h';
+const CLEAR_LINE = '\r\x1b[2K';
+function menuLines(title, items, index) {
+    const width = Math.max(...items.map((i) => i.label.length), 8);
+    return [
+        copper(`  ${title}`),
+        dim('  ↑/↓ move · Enter select · Esc cancel'),
+        '',
+        ...items.map((item, i) => {
+            const cursor = i === index ? copper('❯') : ' ';
+            const label = i === index ? copper(item.label.padEnd(width)) : dim(item.label.padEnd(width));
+            const desc = item.description ? dim(`  ${item.description}`) : '';
+            return `  ${cursor} ${label}${desc}`;
+        }),
+        '',
+    ];
+}
+async function* stdinKeys(input) {
+    // Listener-based on purpose: `for await` over a Readable destroys the
+    // stream when the consumer breaks out, which would kill stdin for
+    // whatever runs after the menu (e.g. the REPL's KeyReader).
+    const wasRaw = input.isRaw;
+    if (typeof input.setRawMode === 'function')
+        input.setRawMode(true);
+    input.resume();
+    input.setEncoding('utf8');
+    const queue = [];
+    let ended = false;
+    let notify = null;
+    const onData = (c) => {
+        queue.push(String(c));
+        notify?.();
+    };
+    const onEnd = () => {
+        ended = true;
+        notify?.();
+    };
+    input.on('data', onData);
+    input.on('end', onEnd);
+    try {
+        for (;;) {
+            while (queue.length) {
+                const s = queue.shift();
+                let i = 0;
+                while (i < s.length) {
+                    if (s[i] === '\x1b' && s[i + 1] === '[') {
+                        yield s.slice(i, i + 3);
+                        i += 3;
+                        continue;
+                    }
+                    // Lone Esc
+                    if (s[i] === '\x1b') {
+                        yield '\x1b';
+                        i += 1;
+                        continue;
+                    }
+                    yield s[i];
+                    i += 1;
+                }
+            }
+            if (ended)
+                return;
+            await new Promise((resolve) => {
+                notify = resolve;
+            });
+            notify = null;
+        }
+    }
+    finally {
+        input.off('data', onData);
+        input.off('end', onEnd);
+        input.pause();
+        if (typeof input.setRawMode === 'function')
+            input.setRawMode(wasRaw ?? false);
+    }
+}
+/** Model choices offered when no model is configured anywhere. */
+export const MODEL_CHOICES = [
+    { value: 'claude-code', label: 'claude-code', description: 'Claude Code CLI (saved login)' },
+    { value: 'codex', label: 'codex', description: 'Codex CLI (saved login)' },
+    { value: 'cursor', label: 'cursor', description: 'Cursor CLI (saved login)' },
+    { value: 'claude', label: 'claude', description: 'Anthropic API (needs ANTHROPIC_API_KEY)' },
+    { value: 'gpt-5', label: 'gpt-5', description: 'OpenAI API (needs OPENAI_API_KEY)' },
+];
+/**
+ * Interactive model picker for a TTY session with no configured model.
+ * Resolves to the chosen model id, or null if cancelled.
+ */
+export async function pickModel(opts = {}) {
+    return selectMenu({ title: 'Select a model for this session', items: MODEL_CHOICES, ...opts });
+}
+/**
+ * Show a selectable list. Resolves to the chosen value, or null if cancelled.
+ */
+export async function selectMenu(opts) {
+    const items = opts.items;
+    if (!items.length)
+        return null;
+    const input = opts.input ?? process.stdin;
+    const output = opts.output ?? process.stdout;
+    const title = opts.title ?? 'Select';
+    let index = 0;
+    let lineCount = 0;
+    const paint = () => {
+        const lines = menuLines(title, items, index);
+        if (lineCount > 0) {
+            // Move to the first line of the previous paint and rewrite in place.
+            output.write(`\x1b[${lineCount}A`);
+        }
+        output.write(HIDE);
+        for (const line of lines) {
+            output.write(CLEAR_LINE + line + '\n');
+        }
+        lineCount = lines.length;
+    };
+    const erase = () => {
+        if (lineCount <= 0) {
+            output.write(SHOW);
+            return;
+        }
+        output.write(`\x1b[${lineCount}A`);
+        for (let i = 0; i < lineCount; i++)
+            output.write(CLEAR_LINE + (i < lineCount - 1 ? '\n' : ''));
+        if (lineCount > 1)
+            output.write(`\x1b[${lineCount - 1}A`);
+        output.write('\r' + SHOW);
+        lineCount = 0;
+    };
+    paint();
+    const keys = opts.keys ?? stdinKeys(input);
+    try {
+        for await (const key of keys) {
+            if (key === '\x03' || key === '\x1b') {
+                erase();
+                return null;
+            }
+            if (key === '\r' || key === '\n') {
+                const chosen = items[index].value;
+                erase();
+                return chosen;
+            }
+            if (key === '\x1b[A' || key === 'k') {
+                index = (index - 1 + items.length) % items.length;
+                paint();
+                continue;
+            }
+            if (key === '\x1b[B' || key === 'j') {
+                index = (index + 1) % items.length;
+                paint();
+                continue;
+            }
+            if (key >= '1' && key <= '9') {
+                const n = Number(key) - 1;
+                if (n >= 0 && n < items.length) {
+                    index = n;
+                    paint();
+                }
+            }
+        }
+    }
+    finally {
+        erase();
+    }
+    return null;
+}
+//# sourceMappingURL=select.js.map

package/dist/util/select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.js","sourceRoot":"","sources":["../../src/util/select.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copperhead",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Cursor for circuit boards: an AI agent that designs, documents, and validates real PCBs on KiCad repositories",
   "license": "Apache-2.0",
   "author": "Animesh Chouhan <animeshchouhan@outlook.com>",
@@ -48,6 +48,7 @@
     "prepublishOnly": "npm run typecheck && npm run build",
     "dev": "tsx src/cli.ts",
     "demo:simple": "bash scripts/demo-simple.sh",
+    "demo:ui": "tsx scripts/ui-demo.ts",
     "lint:md": "markdownlint-cli2 \"**/*.md\" \"#node_modules/**\" \"#**/node_modules/**\" \"#dist/**\" \"#**/dist/**\" \"#docs/.astro/**\" \"#demo-runs/**\" \"#.copperhead/runs/**\" \"#_site/**\"",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -72,7 +73,7 @@
   "devDependencies": {
     "@openai/codex-sdk": "^0.144.6",
     "@types/node": "^22.13.10",
-    "markdownlint-cli2": "0.22.0",
+    "markdownlint-cli2": "0.23.2",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
     "vitest": "^3.0.8"

package/src/agent/animate.ts

@@ -0,0 +1,90 @@
+/**
+ * Subtle TTY motion for attended copperhead chrome. Disabled when color is
+ * off, stdout is not a TTY, CI=1, or COPPERHEAD_NO_ANIM=1.
+ */
+
+import { copper, isColorEnabled } from './theme.js';
+
+export function prefersAnimation(): boolean {
+  return (
+    isColorEnabled() &&
+    Boolean(process.stdout.isTTY) &&
+    !process.env.CI &&
+    !process.env.COPPERHEAD_NO_ANIM
+  );
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+const HIDE = '\x1b[?25l';
+const SHOW = '\x1b[?25h';
+
+/** Growing fiducial frames (3 rows), converging on the block mark. Exported for tests. */
+export function fiducialBootFrames(): string[][] {
+  return [
+    ['         ', '    ██   ', '         '],
+    ['   ▗▄▄▖  ', '   █  █  ', '   ▝▀▀▘  '],
+    ['   ▄▟▙▄  ', '  ██  ██ ', '   ▀▜▛▀  '],
+    ['   ▄▟▙▄  ', ' ███  ███', '   ▀▜▛▀  '],
+  ].map((frame) => frame.map((row) => copper(row)));
+}
+
+/**
+ * Pulse the fiducial mark in place over the already-rendered banner (rows
+ * `topRow..topRow+2`, column 1). The full screen loads first; this animates
+ * after, two grow cycles ending on the final mark. Frames are constant
+ * width so they overwrite each other without clearing the banner text
+ * beside them. Deliberately avoids DECSC/DECRC: the dock owns that slot for
+ * its caret-parking protocol; the caller repaints the dock afterwards to
+ * restore the caret.
+ */
+export async function animateMarkAt(
+  out: NodeJS.WriteStream,
+  topRow: number,
+  opts?: { slow?: boolean },
+): Promise<void> {
+  if (!prefersAnimation()) return;
+  const frames = fiducialBootFrames();
+  const frameMs = opts?.slow ? 110 : 45;
+  const holdMs = opts?.slow ? 220 : 90;
+  try {
+    for (let cycle = 0; cycle < 2; cycle++) {
+      for (const frame of frames) {
+        let seq = HIDE;
+        frame.forEach((row, i) => {
+          seq += `\x1b[${topRow + i};1H${row}`;
+        });
+        out.write(seq);
+        await sleep(frameMs);
+      }
+    }
+    await sleep(holdMs);
+  } finally {
+    // Never leave the terminal with a hidden cursor, even if a write or
+    // sleep throws mid-animation.
+    out.write(SHOW);
+  }
+}
+
+/** Copper horizontal rule (PCB-trace vibe). */
+export function traceRule(width = 32): string {
+  return copper('  ' + '─'.repeat(Math.max(8, Math.min(width, 48))));
+}
+
+/** Cascade lines (help / demo sections). Instant when animation is off. */
+export async function staggerWrite(
+  lines: string[],
+  write: (line: string) => void,
+  delayMs = 12,
+): Promise<void> {
+  if (!prefersAnimation()) {
+    for (const line of lines) write(line);
+    return;
+  }
+  for (const line of lines) {
+    write(line);
+    await sleep(delayMs);
+  }
+}

package/src/agent/box.ts

@@ -0,0 +1,99 @@
+/**
+ * Box-drawing primitives for the bottom-docked REPL chrome: input box,
+ * status bar, and notice callouts. All width math ignores SGR sequences so
+ * colored segments never break padding or wrap accounting.
+ */
+
+import { copper, err, isColorEnabled, ruleDim, warn } from './theme.js';
+
+const SGR = /\x1b\[[0-9;]*m/g;
+
+/** Visible width ignoring SGR color codes. */
+export function visibleWidth(s: string): number {
+  return s.replace(SGR, '').length;
+}
+
+/** Inverse video (synthetic caret / hover); no-op when color is off. */
+export function inverse(s: string): string {
+  if (!isColorEnabled() || s === '') return s;
+  return `\x1b[7m${s}\x1b[0m`;
+}
+
+/** A run of plain text with an optional style applied after slicing. */
+export interface Span {
+  text: string;
+  paint?: (s: string) => string;
+}
+
+/**
+ * Wrap styled spans into lines no wider than `width`. Styling is applied per
+ * slice, so a span can be cut at a wrap boundary without leaking SGR state.
+ */
+export function wrapSpans(spans: Span[], width: number): string[] {
+  const w = Math.max(1, width);
+  const lines: string[] = [];
+  let cur = '';
+  let curLen = 0;
+  for (const span of spans) {
+    let text = span.text;
+    while (text.length) {
+      const take = text.slice(0, w - curLen);
+      cur += span.paint ? span.paint(take) : take;
+      curLen += take.length;
+      text = text.slice(take.length);
+      if (curLen >= w) {
+        lines.push(cur);
+        cur = '';
+        curLen = 0;
+      }
+    }
+  }
+  if (cur !== '' || !lines.length) lines.push(cur);
+  return lines;
+}
+
+/** Full-width horizontal rule (the input-area separators), #888888. */
+export function rule(width: number): string {
+  return ruleDim('─'.repeat(Math.max(1, width)));
+}
+
+/** Truncate to a visible width, keeping SGR sequences intact and closed. */
+export function truncateVisible(s: string, width: number): string {
+  if (visibleWidth(s) <= width) return s;
+  let out = '';
+  let vis = 0;
+  let i = 0;
+  let hadSgr = false;
+  while (i < s.length && vis < width) {
+    if (s[i] === '\x1b') {
+      const m = /^\x1b\[[0-9;]*m/.exec(s.slice(i));
+      if (m) {
+        out += m[0];
+        hadSgr = true;
+        i += m[0].length;
+        continue;
+      }
+    }
+    out += s[i];
+    vis++;
+    i++;
+  }
+  return out + (hadSgr ? '\x1b[0m' : '');
+}
+
+/** One status line with a left- and a right-justified half. */
+export function statusBar(left: string, right: string, width: number): string {
+  const w = Math.max(8, width);
+  const l = visibleWidth(left);
+  const r = visibleWidth(right);
+  // Too narrow for both: the hints matter more than the meta.
+  if (l + r + 2 > w) return truncateVisible(left, w);
+  return left + ' '.repeat(w - l - r) + right;
+}
+
+/** Notice block: thin colored left bar + title + dim body (banner callouts). */
+export function callout(kind: 'info' | 'warn' | 'err', title: string, body: string[]): string[] {
+  const paintBar = kind === 'err' ? err : kind === 'warn' ? warn : copper;
+  const bar = paintBar(' ▎');
+  return [`${bar} ${paintBar(title)}`, ...body.map((b) => `${bar} ${b}`)];
+}

package/src/agent/dock-renderer.ts

@@ -0,0 +1,181 @@
+/**
+ * REPL-session renderer: the single owner of the bottom dock during agent
+ * turns. Durable output (tool lines, turn markers, the outcome) flows into
+ * the content region through `emit`, which the REPL also records as
+ * scrollable history; the live observability line (spinner, turn, tokens,
+ * elapsed, busy text) is painted inside the dock, pinned to the bottom of
+ * the screen no matter how much output scrolls above it.
+ */
+
+import { rule, statusBar } from './box.js';
+import { copper, dim, styleOutcome, toolLine, warn } from './theme.js';
+import { fmtDuration, fmtTokens, turnMarker, type ProgressRenderer } from './render.js';
+import type { TerminalDock } from '../util/dock.js';
+
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+/** Claude Code-style working words, board-shop edition. One per turn. */
+const WORKING = [
+  'Routing',
+  'Etching',
+  'Reflowing',
+  'Soldering',
+  'Drilling',
+  'Plating',
+  'Probing',
+  'Fluxing',
+  'Tinning',
+  'Laminating',
+  'Silkscreening',
+  'Panelizing',
+];
+
+/** Fixed word-slot width: longest word plus the static dots. */
+const WORD_SLOT = Math.max(...WORKING.map((w) => w.length)) + 3;
+
+export class DockRenderer implements ProgressRenderer {
+  private turn = 0;
+  private maxTurns = 0;
+  private tokensIn = 0;
+  private tokensOut = 0;
+  private streamedChars = 0;
+  private busy: string | null = null;
+  private frame = 0;
+  private runSeed = 0;
+  private startMs = Date.now();
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    private readonly dock: TerminalDock,
+    /** Durable line sink: content region + session history. */
+    private readonly emit: (line: string) => void,
+    /** Dock chrome around the status row (meta right, bottom hints). */
+    private readonly chrome: () => { meta: string | null; hints: string | null },
+  ) {}
+
+  log(line: string): void {
+    this.emit(line);
+  }
+
+  toolResult(name: string, firstLine: string): void {
+    this.emit(toolLine(name, firstLine));
+  }
+
+  private turnStartMs = Date.now();
+
+  turnStart(turn: number, maxTurns: number, tokensIn: number, tokensOut: number): void {
+    if (turn === 1) {
+      this.startMs = Date.now();
+      this.runSeed++;
+    }
+    this.turnStartMs = Date.now();
+    this.turn = turn;
+    this.maxTurns = maxTurns;
+    this.tokensIn = tokensIn;
+    this.tokensOut = tokensOut;
+    this.emit(dim(turnMarker(turn, maxTurns, tokensIn, tokensOut)));
+    this.arm();
+    this.paint();
+  }
+
+  status(text: string | null): void {
+    this.busy = text;
+    if (text === null) this.streamedChars = 0;
+    this.paint();
+  }
+
+  heartbeat(info: { elapsedMs: number; streamedChars: number }): void {
+    this.streamedChars = info.streamedChars;
+    this.paint();
+  }
+
+  finish(line: string): void {
+    this.disarm();
+    this.busy = null;
+    this.emit(styleOutcome(line));
+    // The next prompt's renderDock() takes the dock back over.
+  }
+
+  /** Currently displayed working word; morphs letter by letter on change. */
+  private shownWord = '';
+  private targetWord = '';
+  /** -1 = settled; otherwise progress through erase-then-type transition. */
+  private morph = -1;
+
+  private arm(): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      this.frame++;
+      // Sweep three positions per tick: a full word crossfade in under a second.
+      if (this.morph >= 0) this.morph += 3;
+      this.paint();
+    }, 120);
+    this.timer.unref?.();
+  }
+
+  private disarm(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  /** Pinned observability row painted inside the dock (same layout as the prompt). */
+  private paint(): void {
+    const w = Math.max(10, this.dock.cols() - 1);
+    const spinner = copper(FRAMES[this.frame % FRAMES.length]!);
+    // Claude Code-style working word, board-shop themed: rotates every ~6s
+    // while a turn runs, with a shimmering highlight sweeping the letters.
+    // A word change morphs letter by letter: the old word is erased into
+    // `_` slots left to right, then the new word types over them.
+    const wordIdx =
+      (this.runSeed + this.turn + Math.floor((Date.now() - this.turnStartMs) / 6000)) %
+      WORKING.length;
+    const target = WORKING[wordIdx]!;
+    if (this.shownWord === '') this.shownWord = target;
+    if (target !== this.targetWord) {
+      this.targetWord = target;
+      if (target !== this.shownWord) this.morph = 0;
+    }
+    let text = `${this.shownWord}...`;
+    if (this.morph >= 0) {
+      // Single left-to-right sweep over the whole dotted string (dots
+      // included): each position flips old char -> `_` -> new char, so the
+      // words cross-fade character by character.
+      const oldS = `${this.shownWord}...`;
+      const newS = `${this.targetWord}...`;
+      const width = Math.max(oldS.length, newS.length);
+      const k = this.morph;
+      if (k >= width) {
+        this.shownWord = this.targetWord;
+        this.morph = -1;
+        text = `${this.shownWord}...`;
+      } else {
+        let out = '';
+        for (let i = 0; i < width; i++) {
+          out += i < k ? (newS[i] ?? ' ') : i === k ? '_' : (oldS[i] ?? ' ');
+        }
+        text = out.trimEnd();
+      }
+    }
+    // Fixed-width slot (longest word + dots) so the stats after it never
+    // shift; dots and morph slots share the word's copper.
+    const word = copper(text.padEnd(WORD_SLOT));
+    const parts = [
+      dim(`turn ${this.turn}/${this.maxTurns}`),
+      dim(`${fmtTokens(this.tokensIn)} in / ${fmtTokens(this.tokensOut)} out`),
+      dim(fmtDuration(Date.now() - this.startMs)),
+    ];
+    if (this.busy) {
+      parts.push(
+        warn(this.streamedChars ? `${this.busy} ~${fmtTokens(this.streamedChars)} ch` : this.busy),
+      );
+    }
+    const { meta, hints } = this.chrome();
+    this.dock.set([
+      ...(meta ? [statusBar('', `${meta} `, w)] : []),
+      rule(w),
+      statusBar(`${spinner} ${word}`, `${parts.join(dim(' · '))} `, w),
+      rule(w),
+      ...(hints ? [statusBar(`  ${hints}`, '', w)] : []),
+    ]);
+  }
+}

package/src/agent/logo.ts

@@ -0,0 +1,23 @@
+/**
+ * Terminal block-art mark derived from the website logo
+ * (docs/public/favicon.svg and docs.copperhead.sh): a via with a square
+ * drilled hole and long copper tracks routed out of both sides, copper
+ * #b87333 on dark. (`scripts/gen-logo.mjs` renders the exact favicon
+ * geometry at any size for reference.)
+ */
+
+import { copper } from './theme.js';
+
+/** 3-row quadrant-block via with long tracks; rows are equal width. */
+export function fiducialMark(): string[] {
+  return [
+    '   ▄▟▙▄  ',
+    ' ███  ███',
+    '   ▀▜▛▀  ',
+  ];
+}
+
+/** The mark painted in brand copper. */
+export function fiducialLines(): string[] {
+  return fiducialMark().map((line) => copper(line));
+}

package/src/agent/loop.ts

@@ -11,6 +11,7 @@ import { loadConfig, CONFIG_DIR, type CopperheadConfig } from '../config.js';
 import { Transcript, type ExitPath, type RunStats } from './transcript.js';
 import { collectRunMeta, renderCliHeader, type RunMeta, type RunMetaInput } from './runmeta.js';
 import { plainRenderer, fmtDuration, fmtTokens, type ProgressRenderer } from './render.js';
+import { styleHeaderLines } from './theme.js';
 import { ObligationsLedger } from './ledger.js';
 import { gitPreflight, isDirty, snapshot, restore, commitAll, changedFiles, preserveFailedRun } from '../util/git.js';
 import { withRetry, isRateLimit, sessionLimit } from '../util/retry.js';
@@ -20,6 +21,7 @@ import { OpenAIProvider } from './providers/openai.js';
 import { AnthropicProvider } from './providers/anthropic.js';
 import { CodexProvider } from './providers/codex.js';
 import { ClaudeCodeProvider } from './providers/claude-code.js';
+import { CursorProvider } from './providers/cursor.js';
 import { openSynapMemory, type RunRecord, type SynapMemory } from '../memory/synap.js';
 
 /** What the user sees at the moment they decide whether to keep going. */
@@ -100,6 +102,14 @@ export async function makeProvider(model: string, sessionResume = false): Promis
     }
     return new ClaudeCodeProvider(claudeCodeModel, undefined, undefined, sessionResume);
   }
+  // Saved-login Cursor Agent CLI (`agent login`). Matched as its own namespace.
+  if (model === 'cursor' || model.startsWith('cursor:')) {
+    const cursorModel = model.startsWith('cursor:') ? model.slice('cursor:'.length) : undefined;
+    if (cursorModel === '') {
+      throw new Error('cursor model override cannot be empty; use "cursor" or "cursor:<model-id>"');
+    }
+    return new CursorProvider(cursorModel, undefined, sessionResume);
+  }
   if (model === 'claude' || model.startsWith('claude')) {
     return new AnthropicProvider(model === 'claude' ? undefined : model);
   }
@@ -108,7 +118,7 @@ export async function makeProvider(model: string, sessionResume = false): Promis
 
 function otherProvider(current: Provider): Provider | null {
   // Only the two keyed providers fail over to each other. A rate-limited
-  // 'claude-code' run returns null here (no silent fallback to a paid API).
+  // 'claude-code' or 'cursor' run returns null here (no silent fallback to a paid API).
   if (current.name === 'openai' && process.env.ANTHROPIC_API_KEY) return new AnthropicProvider();
   if (current.name === 'anthropic' && process.env.OPENAI_API_KEY) return new OpenAIProvider();
   return null;
@@ -205,9 +215,9 @@ async function runWithMemory(
     finishRequest: null,
   };
 
-  // Session resume for claude-code (1.1) is only correct when the response cache
-  // is off: the cache replays turns a resumed session never saw. So enable it
-  // only when the env flag is set AND config.llmCache is disabled — the same
+  // Session resume for claude-code / cursor is only correct when the response
+  // cache is off: the cache replays turns a resumed session never saw. So enable
+  // it only when the env flag is set AND config.llmCache is disabled — the same
   // condition under which we skip the CachingProvider wrap below.
   const sessionResume = process.env.COPPERHEAD_CC_SESSION_RESUME === '1' && !config.llmCache;
   let provider = opts.provider ?? (await makeProvider(opts.model, sessionResume));
@@ -238,7 +248,7 @@ async function runWithMemory(
     interactive: opts.interactive ?? false,
     input: opts.meta,
   });
-  for (const line of renderCliHeader(meta)) log(line);
+  for (const line of styleHeaderLines(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.