copperhead 0.6.0 → 0.8.0

package/dist/util/retry.js

@@ -3,6 +3,29 @@ export function isRateLimit(err) {
         ?? err?.statusCode;
     return status === 429;
 }
+/**
+ * Detect a saved-login SESSION / USAGE limit (claude-code, codex), distinct from
+ * an HTTP 429 rate limit and from a code bug (2.4, I13). It is not a transient
+ * blip to back off on: it names its own reset time and clears only then. Because
+ * every completed turn is already in `.copperhead/llm-cache/`, re-running after
+ * the reset replays them at ~0 tokens and resumes in place — so the right
+ * handling is a schedulable pause with the reset time surfaced, not a bare
+ * "provider error". Returns the parsed reset time (verbatim) or null when the
+ * error is not a session/usage limit.
+ */
+export function sessionLimit(err) {
+    const status = err?.status
+        ?? err?.statusCode;
+    if (status === 429)
+        return null; // a real rate limit: handled by backoff, not a pause
+    const msg = err?.message ?? '';
+    if (!/(session|usage|weekly)\s+limit|hit your .*limit|reached your usage|limit .*reset/i.test(msg)) {
+        return null;
+    }
+    // "resets 1:40pm", "resets at 1:40 pm", "reset at 13:40" — capture the clock text.
+    const reset = msg.match(/reset[s]?(?:\s+at)?\s+([0-9]{1,2}(?::[0-9]{2})?\s*(?:am|pm)?)/i);
+    return { resetsAt: reset?.[1]?.trim() ?? null };
+}
 /** Exponential backoff ×N for rate limits (SPEC §4.5). */
 export async function withRetry(fn, opts = {}) {
     const retries = opts.retries ?? 3;

package/dist/util/retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/util/retry.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,MAAM,MAAM,GAAI,GAAgD,EAAE,MAAM;WAClE,GAA+B,EAAE,UAAU,CAAC;IAClD,OAAO,MAAM,KAAK,GAAG,CAAC;AACxB,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,EAAoB,EAAE,OAAkB,EAAE;IAC3E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;IACnC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5E,IAAI,OAAgB,CAAC;IACrB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,GAAG,GAAG,CAAC;YACd,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK,OAAO;gBAAE,MAAM,GAAG,CAAC;YACxD,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;YACjC,MAAM,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IACD,MAAM,OAAO,CAAC;AAChB,CAAC"}
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/util/retry.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,MAAM,MAAM,GAAI,GAAgD,EAAE,MAAM;WAClE,GAA+B,EAAE,UAAU,CAAC;IAClD,OAAO,MAAM,KAAK,GAAG,CAAC;AACxB,CAAC;AAQD;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,MAAM,GAAI,GAAgD,EAAE,MAAM;WAClE,GAA+B,EAAE,UAAU,CAAC;IAClD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC,CAAC,qDAAqD;IACtF,MAAM,GAAG,GAAI,GAAa,EAAE,OAAO,IAAI,EAAE,CAAC;IAC1C,IAAI,CAAC,mFAAmF,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnG,OAAO,IAAI,CAAC;IACd,CAAC;IACD,mFAAmF;IACnF,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,gEAAgE,CAAC,CAAC;IAC1F,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC;AAClD,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,EAAoB,EAAE,OAAkB,EAAE;IAC3E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;IACnC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5E,IAAI,OAAgB,CAAC;IACrB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,GAAG,GAAG,CAAC;YACd,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK,OAAO;gBAAE,MAAM,GAAG,CAAC;YACxD,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;YACjC,MAAM,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IACD,MAAM,OAAO,CAAC;AAChB,CAAC"}

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/dist/util/tmp.js

@@ -0,0 +1,119 @@
+import { readdir, stat, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+/** Newest local-history entries to keep when capping `.history/` (see
+ *  pruneHistoryDir). Enough to preserve a useful recovery window, bounded enough
+ *  that the dir cannot grow without limit across a long run. */
+export const DEFAULT_HISTORY_KEEP = 200;
+/**
+ * Cap the growth of a repo's `.history/` directory (4.1). KiCad (and editor
+ * local-history) rewrite a snapshot on every project touch, so across a long
+ * run `.history/` grows without bound and was a contributor to the disk-fill
+ * halt (I8). It is gitignored, so its contents are disposable: keep the newest
+ * `keepNewest` files by mtime and remove the rest. Recursive (local history
+ * mirrors the workspace tree), best-effort (every error is swallowed — pruning
+ * housekeeping must never fail a run), and a no-op when the dir is absent or
+ * already under the cap. Returns the number of files removed.
+ */
+export async function pruneHistoryDir(repoRoot, keepNewest = DEFAULT_HISTORY_KEEP) {
+    const root = path.join(repoRoot, '.history');
+    const files = [];
+    const walk = async (dir) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable dir — skip it
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                await walk(full);
+            }
+            else if (e.isFile()) {
+                try {
+                    const st = await stat(full);
+                    files.push({ full, mtimeMs: st.mtimeMs });
+                }
+                catch {
+                    // stat race — skip this file
+                }
+            }
+        }
+    };
+    await walk(root);
+    if (files.length <= keepNewest)
+        return 0;
+    files.sort((a, b) => b.mtimeMs - a.mtimeMs); // newest first
+    let removed = 0;
+    for (const f of files.slice(keepNewest)) {
+        try {
+            await rm(f.full, { force: true });
+            removed++;
+        }
+        catch {
+            // permission/race — leave it, keep pruning the rest
+        }
+    }
+    return removed;
+}
+/**
+ * Every scratch dir copperhead makes under the OS temp dir shares this prefix:
+ * kicad-cli ERC/DRC (`copperhead-`), the KiCad edit probe (`copperhead-validate-`),
+ * the failed-run backup (`copperhead-runs-`), and the provider working dirs
+ * (`copperhead-cc-`, `copperhead-codex-`). Each site removes its own dir in a
+ * `finally`, but a watchdog SIGKILL of the process tree or a hard abort skips
+ * that cleanup, so stale dirs accumulate across runs and can eventually fill the
+ * disk (I8). A prefix match lets one sweep reclaim all of them.
+ */
+export const TEMP_PREFIX = 'copperhead-';
+/** Default staleness cutoff for the startup sweep: 2h. Safe even for multi-hour
+ * runs (10-min turns × per-stage retries × 8 stages): a live run's only
+ * long-lived scratch dir is the provider's reused cwd, which is `utimes`-touched
+ * every turn (ClaudeCodeProvider.ensureCwd), so its mtime never goes stale while
+ * the process is alive; per-call kicad-cli dirs are removed within a turn. A dir
+ * older than this therefore belongs to a dead run, and the window is short enough
+ * that such a leak is reclaimed on the very next invocation. */
+export const DEFAULT_STALE_MS = 2 * 60 * 60 * 1000;
+/**
+ * Remove leaked `copperhead-*` scratch dirs left in the OS temp dir by earlier
+ * runs whose `finally` cleanup was skipped (watchdog kill / hard abort). Only
+ * dirs whose mtime is older than `maxAgeMs` are removed, so a concurrent run's
+ * fresh scratch dirs are never touched. Best-effort: every error is swallowed
+ * (a temp dir we can't stat or remove is not worth failing a run over), and the
+ * function returns the paths it removed so a caller can log the reclaim.
+ *
+ * `now` is injected so the behaviour is deterministically testable; callers pass
+ * `Date.now()`.
+ */
+export async function sweepStaleTempDirs(now, maxAgeMs = DEFAULT_STALE_MS) {
+    const root = tmpdir();
+    const removed = [];
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        return removed; // no temp dir / not readable — nothing to sweep
+    }
+    for (const name of entries) {
+        if (!name.startsWith(TEMP_PREFIX))
+            continue;
+        const full = path.join(root, name);
+        try {
+            const st = await stat(full);
+            if (!st.isDirectory())
+                continue;
+            if (now - st.mtimeMs < maxAgeMs)
+                continue; // too fresh: could be a live run
+            await rm(full, { recursive: true, force: true });
+            removed.push(full);
+        }
+        catch {
+            // stat/rm race or permission issue — skip this entry, keep sweeping.
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=tmp.js.map

package/dist/util/tmp.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copperhead",
-  "version": "0.6.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}`)];
+}