ucode-agent 1.15.0 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucode-agent",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "ucode - a terminal coding agent that reads, edits and runs your code, on NVIDIA and Cohere models.",
   "type": "module",
   "main": "ucode.js",

package/src/ui/activity.js

@@ -1,203 +1,203 @@
-/**
- * activity.js — what the status row shows while ucode is working.
- *
- * A long turn is minutes of the agent doing things the user did not type and
- * cannot see coming. The status row is the one place that says it is still
- * going, so it has to look alive at a glance without asking to be read: a
- * spinner that turns, a soft band of light passing across the label, the
- * step count ticking up, and the time the turn has taken so far.
- *
- * Everything here is a pure function of the text and the clock, so it can be
- * tested without a terminal and painted at any frame rate.
- */
-
-import chalk, { Chalk } from 'chalk';
-import { dim, sky, theme, clip, SPINNER } from './theme.js';
-
-/** One painter per colour level, so a test can ask for truecolour on a pipe. */
-const painters = new Map();
-const painter = (level) => {
-  if (!painters.has(level)) painters.set(level, new Chalk({ level }));
-  return painters.get(level);
-};
-
-/** One frame every 85ms — just under twelve a second, smooth without being busy. */
-export const FRAME_MS = 85;
-
-/**
- * A duration as a person says it: 0.4s, 14s, 2m 04s, 1h 07m.
- *
- * Seconds are zero-padded once there are minutes, so the text after the timer
- * does not shift sideways every time the seconds roll from 9 to 10.
- */
-export function formatDuration(ms) {
-  const value = Math.max(0, Number(ms) || 0);
-  if (value < 1000) return `${(value / 1000).toFixed(1)}s`;
-  const total = Math.floor(value / 1000);
-  if (total < 60) return `${total}s`;
-  const minutes = Math.floor(total / 60);
-  if (minutes < 60) return `${minutes}m ${String(total % 60).padStart(2, '0')}s`;
-  return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, '0')}m`;
-}
-
-// ---------------------------------------------------------------------------
-// The shimmer
-// ---------------------------------------------------------------------------
-
-/**
- * The two ends of the shimmer, both blue. The resting colour is muted enough
- * to read as secondary text beside the model name; the peak is almost white,
- * so the band reads as light passing over the words rather than a second
- * colour arriving.
- */
-const REST_RGB = [0x7a, 0x96, 0xc8];
-const PEAK_RGB = [0xe6, 0xf0, 0xff];
-
-/** Half the width of the band of light, in characters. */
-const BAND = 3;
-
-/** How fast the band travels, in characters a second. */
-const SPEED = 24;
-
-/** Characters' worth of dark between one pass and the next. */
-const PAUSE = 18;
-
-/** Brightness steps. Neighbouring letters that land on the same step share one escape code. */
-const STEPS = 8;
-
-const mix = (a, b, k) => a.map((v, i) => Math.round(v + (b[i] - v) * k));
-
-/**
- * The text with a soft band of light passing across it, left to right, then a
- * short rest, then again.
- *
- * `t` is milliseconds on any clock; the band's position is a function of it,
- * so a slow frame skips ahead rather than slowing the sweep down.
- *
- * Needs 256 colours or more. With 16 there are no in-between blues to fade
- * through, and a band that jumps between two colours reads as flicker rather
- * than light — so below that the label is simply dim, and never moves.
- */
-export function shimmer(text, t, { level = chalk.level } = {}) {
-  const s = String(text ?? '');
-  if (!s || level < 2) return dim(s);
-
-  const cycle = s.length + BAND * 2 + PAUSE;
-  const centre = ((Math.max(0, t) / 1000) * SPEED) % cycle - BAND;
-
-  let out = '';
-  let run = '';
-  let runStep = -1;
-  const flush = () => {
-    if (!run) return;
-    const [r, g, b] = mix(REST_RGB, PEAK_RGB, runStep / STEPS);
-    out += painter(level).rgb(r, g, b)(run);
-    run = '';
-  };
-
-  for (let i = 0; i < s.length; i++) {
-    const distance = Math.abs(i - centre);
-    // A cosine falloff: brightest at the centre, fading smoothly to nothing
-    // at the edge of the band, so the light has no hard edge to it.
-    const k = distance < BAND ? (Math.cos((Math.PI * distance) / BAND) + 1) / 2 : 0;
-    const step = Math.round(k * STEPS);
-    if (step !== runStep) { flush(); runStep = step; }
-    run += s[i];
-  }
-  flush();
-  return out;
-}
-
-/**
- * The spinner glyph for a frame, breathing slowly between two blues.
- *
- * The pulse is slow — a little over a second a breath — so it reads as the
- * glyph being alive rather than as a blink.
- */
-export function spinnerGlyph(frame, t, { level = chalk.level } = {}) {
-  const glyph = SPINNER[((frame % SPINNER.length) + SPINNER.length) % SPINNER.length];
-  if (level < 2) return theme.blue(glyph);
-  const k = (Math.sin((Math.max(0, t) / 1300) * Math.PI * 2) + 1) / 2;
-  const [r, g, b] = mix([0x4d, 0x8d, 0xff], [0x9f, 0xc6, 0xff], k);
-  return painter(level).rgb(r, g, b)(glyph);
-}
-
-// ---------------------------------------------------------------------------
-// Fitting it into the room there is
-// ---------------------------------------------------------------------------
-
-/** Shorter than this, a label is a stub that says nothing, so it goes entirely. */
-const MIN_LABEL = 10;
-
-/**
- * The middle of the status row, fitted to `room` columns.
- *
- * Parts, in the order they are given up when the terminal is too narrow for
- * all of them:
- *
- *   1. the "esc to stop" hint     — useful once, known after that
- *   2. the end of the label        — clipped with an ellipsis, down to a stub
- *   3. the step count
- *   4. the label itself
- *   5. the elapsed time
- *
- * The spinner is the last thing standing: even with a single column left the
- * row still shows that something is happening.
- *
- * `meta` is a list of { text, paint, keep } — keep marks the one that survives
- * the longest (the timer). `paint` colours the label, which is where the
- * shimmer comes in.
- */
-export function fitActivity({ glyph, label = '', meta = [], hint = '', paint = dim }, room) {
-  if (room < 1) return '';
-  const items = meta.filter((m) => m && m.text);
-  const kept = items.filter((m) => m.keep);
-  const text = String(label ?? '');
-
-  const width = (labelLen, list, withHint) =>
-    1 +
-    (labelLen ? 1 + labelLen : 0) +
-    (list.length ? (labelLen ? 3 : 1) + list.map((m) => m.text).join(' · ').length : 0) +
-    (withHint && hint ? 2 + hint.length : 0);
-
-  const build = (labelText, list, withHint) => {
-    let out = glyph;
-    if (labelText) out += ` ${paint(labelText)}`;
-    if (list.length) {
-      out += labelText ? dim(' · ') : ' ';
-      out += list.map((m) => (m.paint ?? dim)(m.text)).join(dim(' · '));
-    }
-    if (withHint && hint) out += `  ${dim(hint)}`;
-    return out;
-  };
-
-  if (text) {
-    if (width(text.length, items, true) <= room) return build(text, items, true);
-    if (width(text.length, items, false) <= room) return build(text, items, false);
-    for (const list of [items, kept]) {
-      const labelRoom = room - width(0, list, false) - 1 - (list.length ? 2 : 0);
-      if (labelRoom >= MIN_LABEL) return build(clip(text, labelRoom), list, false);
-    }
-  }
-  for (const list of [items, kept, []]) {
-    if (width(0, list, false) <= room) return build('', list, false);
-  }
-  return glyph;
-}
-
-/**
- * The line a finished turn leaves in the transcript: "✓ Done in 6m 12s · 25 steps".
- *
- * Green for the tick, because green means done and nothing else in this
- * theme; the rest dim, because it is a footnote to the answer above it rather
- * than something to read first.
- */
-export function doneLine(ms, steps) {
-  const count = steps > 0 ? ` · ${steps} step${steps === 1 ? '' : 's'}` : '';
-  return `${theme.ok('✓')} ${dim(`Done in ${formatDuration(ms)}${count}`)}`;
-}
-
-/** The step count, brighter for a moment right after it goes up. */
-export function stepPaint(justMoved) {
-  return justMoved ? sky : dim;
-}
+/**
+ * activity.js — what the status row shows while ucode is working.
+ *
+ * A long turn is minutes of the agent doing things the user did not type and
+ * cannot see coming. The status row is the one place that says it is still
+ * going, so it has to look alive at a glance without asking to be read: a
+ * spinner that turns, a soft band of light passing across the label, the
+ * step count ticking up, and the time the turn has taken so far.
+ *
+ * Everything here is a pure function of the text and the clock, so it can be
+ * tested without a terminal and painted at any frame rate.
+ */
+
+import chalk, { Chalk } from 'chalk';
+import { dim, sky, theme, clip, SPINNER } from './theme.js';
+
+/** One painter per colour level, so a test can ask for truecolour on a pipe. */
+const painters = new Map();
+const painter = (level) => {
+  if (!painters.has(level)) painters.set(level, new Chalk({ level }));
+  return painters.get(level);
+};
+
+/** One frame every 85ms — just under twelve a second, smooth without being busy. */
+export const FRAME_MS = 85;
+
+/**
+ * A duration as a person says it: 0.4s, 14s, 2m 04s, 1h 07m.
+ *
+ * Seconds are zero-padded once there are minutes, so the text after the timer
+ * does not shift sideways every time the seconds roll from 9 to 10.
+ */
+export function formatDuration(ms) {
+  const value = Math.max(0, Number(ms) || 0);
+  if (value < 1000) return `${(value / 1000).toFixed(1)}s`;
+  const total = Math.floor(value / 1000);
+  if (total < 60) return `${total}s`;
+  const minutes = Math.floor(total / 60);
+  if (minutes < 60) return `${minutes}m ${String(total % 60).padStart(2, '0')}s`;
+  return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, '0')}m`;
+}
+
+// ---------------------------------------------------------------------------
+// The shimmer
+// ---------------------------------------------------------------------------
+
+/**
+ * The two ends of the shimmer, both blue. The resting colour is muted enough
+ * to read as secondary text beside the model name; the peak is almost white,
+ * so the band reads as light passing over the words rather than a second
+ * colour arriving.
+ */
+const REST_RGB = [0x7a, 0x96, 0xc8];
+const PEAK_RGB = [0xe6, 0xf0, 0xff];
+
+/** Half the width of the band of light, in characters. */
+const BAND = 3;
+
+/** How fast the band travels, in characters a second. */
+const SPEED = 46;
+
+/** Characters' worth of dark between one pass and the next. */
+const PAUSE = 10;
+
+/** Brightness steps. Neighbouring letters that land on the same step share one escape code. */
+const STEPS = 8;
+
+const mix = (a, b, k) => a.map((v, i) => Math.round(v + (b[i] - v) * k));
+
+/**
+ * The text with a soft band of light passing across it, left to right, then a
+ * short rest, then again.
+ *
+ * `t` is milliseconds on any clock; the band's position is a function of it,
+ * so a slow frame skips ahead rather than slowing the sweep down.
+ *
+ * Needs 256 colours or more. With 16 there are no in-between blues to fade
+ * through, and a band that jumps between two colours reads as flicker rather
+ * than light — so below that the label is simply dim, and never moves.
+ */
+export function shimmer(text, t, { level = chalk.level } = {}) {
+  const s = String(text ?? '');
+  if (!s || level < 2) return dim(s);
+
+  const cycle = s.length + BAND * 2 + PAUSE;
+  const centre = ((Math.max(0, t) / 1000) * SPEED) % cycle - BAND;
+
+  let out = '';
+  let run = '';
+  let runStep = -1;
+  const flush = () => {
+    if (!run) return;
+    const [r, g, b] = mix(REST_RGB, PEAK_RGB, runStep / STEPS);
+    out += painter(level).rgb(r, g, b)(run);
+    run = '';
+  };
+
+  for (let i = 0; i < s.length; i++) {
+    const distance = Math.abs(i - centre);
+    // A cosine falloff: brightest at the centre, fading smoothly to nothing
+    // at the edge of the band, so the light has no hard edge to it.
+    const k = distance < BAND ? (Math.cos((Math.PI * distance) / BAND) + 1) / 2 : 0;
+    const step = Math.round(k * STEPS);
+    if (step !== runStep) { flush(); runStep = step; }
+    run += s[i];
+  }
+  flush();
+  return out;
+}
+
+/**
+ * The spinner glyph for a frame, breathing slowly between two blues.
+ *
+ * The pulse is slow — a little over a second a breath — so it reads as the
+ * glyph being alive rather than as a blink.
+ */
+export function spinnerGlyph(frame, t, { level = chalk.level } = {}) {
+  const glyph = SPINNER[((frame % SPINNER.length) + SPINNER.length) % SPINNER.length];
+  if (level < 2) return theme.blue(glyph);
+  const k = (Math.sin((Math.max(0, t) / 1300) * Math.PI * 2) + 1) / 2;
+  const [r, g, b] = mix([0x4d, 0x8d, 0xff], [0x9f, 0xc6, 0xff], k);
+  return painter(level).rgb(r, g, b)(glyph);
+}
+
+// ---------------------------------------------------------------------------
+// Fitting it into the room there is
+// ---------------------------------------------------------------------------
+
+/** Shorter than this, a label is a stub that says nothing, so it goes entirely. */
+const MIN_LABEL = 10;
+
+/**
+ * The middle of the status row, fitted to `room` columns.
+ *
+ * Parts, in the order they are given up when the terminal is too narrow for
+ * all of them:
+ *
+ *   1. the "esc to stop" hint     — useful once, known after that
+ *   2. the end of the label        — clipped with an ellipsis, down to a stub
+ *   3. the step count
+ *   4. the label itself
+ *   5. the elapsed time
+ *
+ * The spinner is the last thing standing: even with a single column left the
+ * row still shows that something is happening.
+ *
+ * `meta` is a list of { text, paint, keep } — keep marks the one that survives
+ * the longest (the timer). `paint` colours the label, which is where the
+ * shimmer comes in.
+ */
+export function fitActivity({ glyph, label = '', meta = [], hint = '', paint = dim }, room) {
+  if (room < 1) return '';
+  const items = meta.filter((m) => m && m.text);
+  const kept = items.filter((m) => m.keep);
+  const text = String(label ?? '');
+
+  const width = (labelLen, list, withHint) =>
+    1 +
+    (labelLen ? 1 + labelLen : 0) +
+    (list.length ? (labelLen ? 3 : 1) + list.map((m) => m.text).join(' · ').length : 0) +
+    (withHint && hint ? 2 + hint.length : 0);
+
+  const build = (labelText, list, withHint) => {
+    let out = glyph;
+    if (labelText) out += ` ${paint(labelText)}`;
+    if (list.length) {
+      out += labelText ? dim(' · ') : ' ';
+      out += list.map((m) => (m.paint ?? dim)(m.text)).join(dim(' · '));
+    }
+    if (withHint && hint) out += `  ${dim(hint)}`;
+    return out;
+  };
+
+  if (text) {
+    if (width(text.length, items, true) <= room) return build(text, items, true);
+    if (width(text.length, items, false) <= room) return build(text, items, false);
+    for (const list of [items, kept]) {
+      const labelRoom = room - width(0, list, false) - 1 - (list.length ? 2 : 0);
+      if (labelRoom >= MIN_LABEL) return build(clip(text, labelRoom), list, false);
+    }
+  }
+  for (const list of [items, kept, []]) {
+    if (width(0, list, false) <= room) return build('', list, false);
+  }
+  return glyph;
+}
+
+/**
+ * The line a finished turn leaves in the transcript: "✓ Done in 6m 12s · 25 steps".
+ *
+ * Green for the tick, because green means done and nothing else in this
+ * theme; the rest dim, because it is a footnote to the answer above it rather
+ * than something to read first.
+ */
+export function doneLine(ms, steps) {
+  const count = steps > 0 ? ` · ${steps} step${steps === 1 ? '' : 's'}` : '';
+  return `${theme.ok('✓')} ${dim(`Done in ${formatDuration(ms)}${count}`)}`;
+}
+
+/** The step count, brighter for a moment right after it goes up. */
+export function stepPaint(justMoved) {
+  return justMoved ? sky : dim;
+}

package/src/ui/screen.js

@@ -39,7 +39,7 @@ import chalk from 'chalk';
 import {
   theme, blue, sky, deep, dim, edge, ADDED, REMOVED, BANNER, BANNER_WIDTH, SPINNER,
   boxTop, boxBottom, boxRow, visLen, padVis, clip, wrapAnsi,
-  shortenPath, asLabel, ensureColour, planLine, bare, narration, narrationMark, groupKind, groupLabel, groupTarget, runLine, planRows } from './theme.js';
+  shortenPath, asLabel, ensureColour, planLine, bare, narration, narrationMark, groupKind, groupLabel, groupTarget, runLine, planRows, withoutCodeBlocks } from './theme.js';
 import { FRAME_MS, fitActivity, shimmer, spinnerGlyph, formatDuration, doneLine, stepPaint } from './activity.js';
 import { renderer, render, polish } from './markdown.js';
 import { VERSION } from '../core/version.js';
@@ -101,7 +101,10 @@ const title = (t) => `${ESC}]0;${t}\x07`;
  * Fixed rows below the header: the gap under it, the gap above the input box,
  * the input box's two borders, the blank row inside it, and the status row.
  */
-const CHROME_BELOW = 6;
+const CHROME_BELOW = 8;
+
+/** How long one sentence of reasoning holds the line before the next takes it. */
+const THOUGHT_HOLD_MS = 1100;
 
 /** The wordmark only earns its place with room for the facts column beside it. */
 const WORDMARK_NEEDS = BANNER_WIDTH + 30;
@@ -252,7 +255,7 @@ export class Screen {
     if (!text?.trim()) return;
     this.endRun();
     this.add('');
-    this.add(render(this.md, text));
+    this.add(render(this.md, withoutCodeBlocks(text)));
     this.add('');
     this.render();
   }
@@ -392,10 +395,17 @@ export class Screen {
     if (this.run) this.paintRun({ live: false });
   }
 
-  toolFailed(summary) {
-    // A failure is never folded away.
+  /**
+   * Something went wrong, and the model is the one who can do anything about it.
+   *
+   * A red line of machinery — a failed edit, a command that exited non-zero —
+   * reads as the tool being broken, when almost always it is a step the model
+   * corrects on its own a second later. It goes to the model; the screen stays
+   * for what is being built. Whatever is genuinely unrecoverable surfaces as
+   * the model saying so in words, which is the form worth reading.
+   */
+  toolFailed() {
     this.endRun();
-    this.push(`${dim('  └ ')}${theme.error(summary)}`);
   }
 
   /**
@@ -550,11 +560,21 @@ export class Screen {
 
     this.thought = ((this.thought ?? '') + text).slice(-2000);
     // The last sentence it has finished, or what it has written of the next.
-    const parts = this.thought.split(/(?<=[.!?])\s+/).filter((p) => p.trim());
+    const parts = this.thought.split(/(?<=[.!?])\s+|(?<=[.!?])(?=[A-Z])/).filter((p) => p.trim());
     const latest = (parts[parts.length - 1] ?? '').replace(/\s+/g, ' ').trim();
     if (!latest) return;
 
-    const line = `  ${shimmer(clip(latest, Math.max(20, this.width() - 6)), this.tick * FRAME_MS)}`;
+    // A sentence that is replaced the instant the next one arrives cannot be
+    // read — it flashes. Each one holds the line for long enough to take in,
+    // and whatever arrived meanwhile shows when its turn comes.
+    const now = Date.now();
+    if (latest !== this.shownThought) {
+      if (this.shownThought !== undefined && now - (this.shownAt ?? 0) < THOUGHT_HOLD_MS) return;
+      this.shownThought = latest;
+      this.shownAt = now;
+    }
+
+    const line = `  ${shimmer(clip(this.shownThought, Math.max(20, this.width() - 6)), this.tick * FRAME_MS)}`;
     if (this.thinkAt === undefined || this.lines[this.thinkAt] === undefined) {
       this.thinkAt = this.lines.length;
       this.push(line);
@@ -580,6 +600,8 @@ export class Screen {
       this.render();
     }
     this.thought = '';
+    this.shownThought = undefined;
+    this.shownAt = undefined;
     this.thoughtSince = undefined;
   }
 
@@ -1338,6 +1360,8 @@ export class Screen {
       // reads as part of the input rather than as the answer above it.
       '',
       ...this.inputBox(),
+      '',
+      '',
     ];
 
     // The cursor is hidden for the duration of the paint. Without this it is

package/src/ui/theme.js

@@ -1,378 +1,399 @@
-/**
- * theme.js — colour, boxes, and the string maths that keeps a terminal frame
- * from tearing.
- *
- * Everything visual comes from here so the whole interface can be re-tinted by
- * editing one block. ucode is blue: a single hue, three steps of it, and
- * nothing else decorative. Red, amber and green are reserved — they mean
- * failed, careful, and done, and they never appear for any other reason.
- */
-
-import chalk from 'chalk';
-
-// One hue, three weights. Anything that needs a fourth is asking for emphasis
-// it has not earned.
-export const blue = chalk.hex('#4d8dff');   // structure: borders, the caret, the wordmark
-export const sky = chalk.hex('#8fbcff');    // secondary: labels that still matter
-export const deep = chalk.hex('#2f6fe0');   // pressed, quiet, behind
-export const dim = chalk.dim;
-
-/**
- * The input box's own edge: the same blue, drawn bold.
- *
- * The input is the one thing on screen you act on, so it is the one box that
- * gets the heavier line. Bold box-drawing renders brighter, and in most
- * terminal fonts visibly thicker, which is enough to separate "where you type"
- * from "what you are reading" without a second colour.
- */
-export const edge = chalk.hex('#4d8dff').bold;
-
-/**
- * The colour level to use for a stream, or null to leave chalk's guess alone.
- *
- * chalk decides from the environment, and some environments lie: TERM=dumb
- * from an embedding shell, or a wrapper that strips COLORTERM. The result is a
- * UI with every colour silently gone — a grey box where a blue one was drawn.
- *
- * The full-screen interface already depends on a terminal that understands VT
- * sequences — it switches to the alternate screen and moves the cursor — and
- * any terminal that handles those handles colour. So when that interface is
- * running, the guess is overruled. NO_COLOR is still honoured, because that
- * one is a person's explicit choice rather than an environment's accident.
- */
-export function colourLevel(stream, env = process.env, current = chalk.level) {
-  if ('NO_COLOR' in env) return null;
-  if (!stream?.isTTY) return null;
-  if (current >= 2) return null;
-  return env.COLORTERM === 'truecolor' || env.COLORTERM === '24bit' || process.platform === 'win32' ? 3 : 2;
-}
-
-export function ensureColour(stream) {
-  const level = colourLevel(stream);
-  if (level !== null) chalk.level = level;
-}
-
-export const theme = {
-  blue,
-  sky,
-  deep,
-  dim,
-  text: chalk.white,
-  error: chalk.red,
-  warn: chalk.hex('#e0a030'),
-  ok: chalk.hex('#3fb950'),
-};
-
-/** Tints for a diff: enough colour to scan, dim enough to read code through. */
-export const ADDED = chalk.bgHex('#0e2a1a').hex('#7ee2a8');
-export const REMOVED = chalk.bgHex('#331319').hex('#f2939c');
-
-export const BANNER = [
-  '██╗   ██╗ ██████╗ ██████╗ ██████╗ ███████╗',
-  '██║   ██║██╔════╝██╔═══██╗██╔══██╗██╔════╝',
-  '██║   ██║██║     ██║   ██║██║  ██║█████╗  ',
-  '██║   ██║██║     ██║   ██║██║  ██║██╔══╝  ',
-  '╚██████╔╝╚██████╗╚██████╔╝██████╔╝███████╗',
-  ' ╚═════╝  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝',
-];
-
-export const BANNER_WIDTH = Math.max(...BANNER.map((r) => r.length));
-
-/** The spinner. Braille dots, because they animate in place without jitter. */
-export const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-
-// ---------------------------------------------------------------------------
-// Boxes
-// ---------------------------------------------------------------------------
-
-export const BOX = {
-  topLeft: '╭', topRight: '╮', bottomLeft: '╰', bottomRight: '╯',
-  h: '─', v: '│',
-};
-
-export const boxTop = (width, paint = blue) =>
-  paint(BOX.topLeft + BOX.h.repeat(Math.max(0, width - 2)) + BOX.topRight);
-
-export const boxBottom = (width, paint = blue) =>
-  paint(BOX.bottomLeft + BOX.h.repeat(Math.max(0, width - 2)) + BOX.bottomRight);
-
-/** One row inside a box, padded so the right border lands in the same column. */
-export const boxRow = (content, width, paint = blue) =>
-  paint(BOX.v) + padVis(content, Math.max(0, width - 2)) + paint(BOX.v);
-
-// ---------------------------------------------------------------------------
-// Widths, with escape codes discounted
-// ---------------------------------------------------------------------------
-
-/** The string with its colour codes stripped — what the terminal actually shows. */
-export const bare = (s) => String(s).replace(/\x1b\[[0-9;]*m/g, '');
-export const visLen = (s) => bare(s).length;
-
-/** The first `width` visible characters, with escape sequences left intact. */
-export function sliceVis(s, width) {
-  let out = '';
-  let seen = 0;
-  for (let i = 0; i < s.length; i++) {
-    if (s[i] === '\x1b') {
-      const m = /^\x1b\[[0-9;]*m/.exec(s.slice(i));
-      if (m) { out += m[0]; i += m[0].length - 1; continue; }
-    }
-    if (seen >= width) break;
-    out += s[i];
-    seen++;
-  }
-  return out;
-}
-
-/** Pad or hard-cut a possibly-coloured string to an exact visible width. */
-export function padVis(s, width) {
-  const len = visLen(s);
-  if (len === width) return s;
-  if (len < width) return s + ' '.repeat(width - len);
-  return `${sliceVis(s, width)}\x1b[0m`;
-}
-
-export function clip(text, max) {
-  const s = String(text ?? '');
-  if (max <= 1) return '';
-  return s.length > max ? `${s.slice(0, max - 1)}…` : s;
-}
-
-/**
- * Word-wrap text that may already be coloured.
- *
- * Escape sequences have no width, and whichever styles are open at a break get
- * reopened on the next line — otherwise a wrapped sentence loses its colour
- * halfway through.
- */
-export function wrapAnsi(text, width) {
-  if (width < 4) return [text];
-
-  const lines = [];
-  let line = '';
-  let seen = 0;
-  let open = '';
-  let lastSpace = -1;
-  let lastSpaceSeen = 0;
-
-  const flush = (upto = null) => {
-    if (upto === null) {
-      lines.push(line);
-      line = open;
-      seen = 0;
-    } else {
-      lines.push(line.slice(0, upto));
-      const carry = line.slice(upto).replace(/^ +/, '');
-      line = open + carry;
-      seen = visLen(carry);
-    }
-    lastSpace = -1;
-  };
-
-  for (let i = 0; i < text.length; i++) {
-    if (text[i] === '\x1b') {
-      const m = /^\x1b\[[0-9;]*m/.exec(text.slice(i));
-      if (m) {
-        line += m[0];
-        open = m[0] === '\x1b[0m' ? '' : open + m[0];
-        i += m[0].length - 1;
-        continue;
-      }
-    }
-    if (text[i] === ' ') { lastSpace = line.length; lastSpaceSeen = seen; }
-    line += text[i];
-    seen++;
-    if (seen >= width) {
-      // Break at a word boundary unless that would leave a stub behind.
-      if (lastSpace > 0 && lastSpaceSeen > width * 0.4) flush(lastSpace);
-      else flush();
-    }
-  }
-
-  if (visLen(line)) lines.push(line);
-  return lines.length ? lines : [''];
-}
-
-// ---------------------------------------------------------------------------
-// Small formatters
-// ---------------------------------------------------------------------------
-
-export function formatTokens(n) {
-  if (!n) return '0';
-  if (n < 1000) return String(n);
-  if (n < 1_000_000) return `${(n / 1000).toFixed(n < 10_000 ? 1 : 0)}k`;
-  return `${(n / 1_000_000).toFixed(1)}M`;
-}
-
-export function today() {
-  return new Date().toLocaleDateString('en-GB', { day: 'numeric', month: 'short', year: 'numeric' });
-}
-
-/** Shorten a path for display: home becomes ~, a long middle collapses. */
-export function shortenPath(p, max = 40) {
-  let out = String(p);
-  const home = process.env.USERPROFILE || process.env.HOME || '';
-  if (home && out.startsWith(home)) out = `~${out.slice(home.length)}`;
-  if (out.length <= max) return out;
-
-  const parts = out.split(/[\\/]/);
-  if (parts.length <= 3) return `…${out.slice(-(max - 1))}`;
-  const sep = out.includes('\\') ? '\\' : '/';
-  return `${parts[0]}${sep}…${sep}${parts.slice(-2).join(sep)}`;
-}
-
-export function relativeTime(iso) {
-  if (!iso) return 'unknown';
-  const then = new Date(iso).getTime();
-  if (Number.isNaN(then)) return 'unknown';
-
-  const secs = Math.max(0, Math.round((Date.now() - then) / 1000));
-  if (secs < 60) return 'just now';
-  const mins = Math.round(secs / 60);
-  if (mins < 60) return `${mins}m ago`;
-  const hours = Math.round(mins / 60);
-  if (hours < 24) return `${hours}h ago`;
-  const days = Math.round(hours / 24);
-  return days < 30 ? `${days}d ago` : new Date(iso).toISOString().slice(0, 10);
-}
-
-/**
- * Trim a trailing full stop off a live status line.
- *
- * "Listing src" is a label on work in progress. "Listing src." is a sentence,
- * and a sentence that ends while the thing it describes is still happening
- * reads as finished when it is not. Models add the full stop by habit; this
- * takes it back off.
- *
- * Only after a word, though. A dot that follows a space is the whole point of
- * the line — "Listing ." names the current directory — and trimming that turns
- * a label into a fragment.
- */
-export function asLabel(text) {
-  return String(text ?? '')
-    .trim()
-    .replace(/\s+/g, ' ')
-    // A trailing stop, from a model's sentence or a tool's own output
-    // ("Building…", "Completing…"), is noise on a one-line label. A dot that
-    // is the argument itself — "Listing ." — is not, so a word has to come
-    // before it.
-    .replace(/(?<=[\w)\]"'`])[.。…]+$/, '');
-}
-
-/**
- * The model's checklist, as one short line — done ticked, the current item
- * marked, the rest dim — so progress is visible without taking over the screen.
- */
-/**
- * The plan, as a block rather than a sentence.
- *
- * Six steps joined with separators made one line far wider than any terminal,
- * so it wrapped — and a wrapped checklist has its ticks in the middle of the
- * text, which is unreadable. Down the page each step keeps its own row, its
- * mark stays in the left column, and the eye can find the one in progress
- * without reading any of the others.
- *
- * Returns the rows; the caller pushes them.
- */
-export function planRows(items) {
-  const list = (Array.isArray(items) ? items : []).slice(0, 8);
-  if (!list.length) return [];
-  const done = list.filter((i) => i?.done).length;
-  const current = list.findIndex((i) => !i?.done);
-
-  const rows = [`  ${sky(`plan ${done}/${list.length}`)}`];
-  list.forEach((item, i) => {
-    const text = clip(String(item?.text ?? '').trim(), 64);
-    if (item?.done) rows.push(`    ${theme.ok('✓')} ${dim(text)}`);
-    else if (i === current) rows.push(`    ${blue('▸')} ${chalk.white(text)}`);
-    else rows.push(`    ${dim('○')} ${dim(text)}`);
-  });
-  return rows;
-}
-
-/** Kept for the plain interface, which has one line to work with. */
-export function planLine(items) {
-  const list = (Array.isArray(items) ? items : []).slice(0, 6);
-  if (!list.length) return '';
-  const done = list.filter((i) => i?.done).length;
-  const current = list.findIndex((i) => !i?.done);
-  const now = current === -1 ? 'done' : clip(String(list[current]?.text ?? '').trim(), 40);
-  return `  ${sky(`plan ${done}/${list.length}`)}  ${chalk.white(now)}`;
-}
-
-/**
- * Narration: what the agent is doing, as opposed to what it has to say.
- *
- * These lines are scaffolding — "Reading screen.js", "Checking types". They
- * are worth seeing and not worth reading, and at full strength they compete
- * with the answer, which is the thing the user is actually here for. A
- * terminal has no smaller size to set, so the only axis available is weight:
- * faint, and a step down in colour. The answer stays at full strength and
- * wins the page by contrast rather than by shouting.
- */
-export const narration = (text) => chalk.dim(text);
-
-/** The bullet beside a narration line: present, not loud. */
-export const narrationMark = () => chalk.dim(deep('●'));
-
-/**
- * How a run of the same kind of step reads once it is over.
- *
- * While it happens, "Running npm test" is the useful thing to show. Once
- * three of them have happened, three near-identical lines are just noise
- * between the reader and the answer, so they fold into one: "Ran 3 commands".
- * The present tense belongs to the thing happening now; the past tense to the
- * summary of what did.
- */
-const GROUPS = {
-  Running: ['Ran', 'command', 'commands'],
-  Reading: ['Read', 'file', 'files'],
-  Searching: ['Searched', 'time', 'times'],
-  Finding: ['Found', 'pattern', 'patterns'],
-  Listing: ['Listed', 'directory', 'directories'],
-  Writing: ['Wrote', 'file', 'files'],
-  Editing: ['Edited', 'file', 'files'],
-  Checking: ['Checked', 'thing', 'things'],
-  Looking: ['Looked up', 'name', 'names'],
-  Asking: ['Asked about', 'name', 'names'],
-  Mapping: ['Mapped', 'folder', 'folders'],
-  Adding: ['Added', 'block', 'blocks'],
-  Renaming: ['Renamed', 'name', 'names'],
-};
-
-/** The first word of a label, which is what decides whether two steps match. */
-export const groupKind = (label) => String(label ?? '').trim().split(/\s+/)[0] ?? '';
-
-/** One line standing in for `count` steps that all began with the same word. */
-export function groupLabel(label, count) {
-  if (count <= 1) return String(label ?? '');
-  const g = GROUPS[groupKind(label)];
-  if (!g) return `${label} (+${count - 1} more)`;
-  const [past, one, many] = g;
-  return `${past} ${count} ${count === 1 ? one : many}`;
-}
-
-/** The part of a label after its opening word: the file or command it is about. */
-export const groupTarget = (label) => String(label ?? '').trim().split(/\s+/).slice(1).join(' ');
-
-/**
- * One narration line, standing for everything that happened under it.
- *
- * The transcript is a record of what was done, not a copy of what was
- * written. A 539-line file printed into it buries the answer and tells the
- * reader nothing they could not get from the file itself, so a change is its
- * two numbers. Several steps on one file stay one line naming that file;
- * several files become a count.
- */
-export function runLine({ label, count = 1, targets = [], added = 0, removed = 0 }) {
-  const counts = added || removed
-    ? ` ${chalk.hex('#3fb950')(`+${added}`)} ${chalk.hex('#f2939c')(`-${removed}`)}`
-    : '';
-  if (count <= 1) return `${label}${counts}`;
-
-  const g = GROUPS[groupKind(label)];
-  const unique = [...new Set(targets.filter(Boolean))];
-  if (g && unique.length === 1) return `${g[0]} ${unique[0]}${counts}`;
-  if (!g) return `${label} (+${count - 1} more)${counts}`;
-  return `${g[0]} ${count} ${count === 1 ? g[1] : g[2]}${counts}`;
-}
+/**
+ * theme.js — colour, boxes, and the string maths that keeps a terminal frame
+ * from tearing.
+ *
+ * Everything visual comes from here so the whole interface can be re-tinted by
+ * editing one block. ucode is blue: a single hue, three steps of it, and
+ * nothing else decorative. Red, amber and green are reserved — they mean
+ * failed, careful, and done, and they never appear for any other reason.
+ */
+
+import chalk from 'chalk';
+
+// One hue, three weights. Anything that needs a fourth is asking for emphasis
+// it has not earned.
+export const blue = chalk.hex('#4d8dff');   // structure: borders, the caret, the wordmark
+export const sky = chalk.hex('#8fbcff');    // secondary: labels that still matter
+export const deep = chalk.hex('#2f6fe0');   // pressed, quiet, behind
+export const dim = chalk.dim;
+
+/**
+ * The input box's own edge: the same blue, drawn bold.
+ *
+ * The input is the one thing on screen you act on, so it is the one box that
+ * gets the heavier line. Bold box-drawing renders brighter, and in most
+ * terminal fonts visibly thicker, which is enough to separate "where you type"
+ * from "what you are reading" without a second colour.
+ */
+export const edge = chalk.hex('#4d8dff').bold;
+
+/**
+ * The colour level to use for a stream, or null to leave chalk's guess alone.
+ *
+ * chalk decides from the environment, and some environments lie: TERM=dumb
+ * from an embedding shell, or a wrapper that strips COLORTERM. The result is a
+ * UI with every colour silently gone — a grey box where a blue one was drawn.
+ *
+ * The full-screen interface already depends on a terminal that understands VT
+ * sequences — it switches to the alternate screen and moves the cursor — and
+ * any terminal that handles those handles colour. So when that interface is
+ * running, the guess is overruled. NO_COLOR is still honoured, because that
+ * one is a person's explicit choice rather than an environment's accident.
+ */
+export function colourLevel(stream, env = process.env, current = chalk.level) {
+  if ('NO_COLOR' in env) return null;
+  if (!stream?.isTTY) return null;
+  if (current >= 2) return null;
+  return env.COLORTERM === 'truecolor' || env.COLORTERM === '24bit' || process.platform === 'win32' ? 3 : 2;
+}
+
+export function ensureColour(stream) {
+  const level = colourLevel(stream);
+  if (level !== null) chalk.level = level;
+}
+
+export const theme = {
+  blue,
+  sky,
+  deep,
+  dim,
+  text: chalk.white,
+  error: chalk.red,
+  warn: chalk.hex('#e0a030'),
+  ok: chalk.hex('#3fb950'),
+};
+
+/** Tints for a diff: enough colour to scan, dim enough to read code through. */
+export const ADDED = chalk.bgHex('#0e2a1a').hex('#7ee2a8');
+export const REMOVED = chalk.bgHex('#331319').hex('#f2939c');
+
+export const BANNER = [
+  '██╗   ██╗ ██████╗ ██████╗ ██████╗ ███████╗',
+  '██║   ██║██╔════╝██╔═══██╗██╔══██╗██╔════╝',
+  '██║   ██║██║     ██║   ██║██║  ██║█████╗  ',
+  '██║   ██║██║     ██║   ██║██║  ██║██╔══╝  ',
+  '╚██████╔╝╚██████╗╚██████╔╝██████╔╝███████╗',
+  ' ╚═════╝  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝',
+];
+
+export const BANNER_WIDTH = Math.max(...BANNER.map((r) => r.length));
+
+/** The spinner. Braille dots, because they animate in place without jitter. */
+export const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+// ---------------------------------------------------------------------------
+// Boxes
+// ---------------------------------------------------------------------------
+
+export const BOX = {
+  topLeft: '╭', topRight: '╮', bottomLeft: '╰', bottomRight: '╯',
+  h: '─', v: '│',
+};
+
+export const boxTop = (width, paint = blue) =>
+  paint(BOX.topLeft + BOX.h.repeat(Math.max(0, width - 2)) + BOX.topRight);
+
+export const boxBottom = (width, paint = blue) =>
+  paint(BOX.bottomLeft + BOX.h.repeat(Math.max(0, width - 2)) + BOX.bottomRight);
+
+/** One row inside a box, padded so the right border lands in the same column. */
+export const boxRow = (content, width, paint = blue) =>
+  paint(BOX.v) + padVis(content, Math.max(0, width - 2)) + paint(BOX.v);
+
+// ---------------------------------------------------------------------------
+// Widths, with escape codes discounted
+// ---------------------------------------------------------------------------
+
+/** The string with its colour codes stripped — what the terminal actually shows. */
+export const bare = (s) => String(s).replace(/\x1b\[[0-9;]*m/g, '');
+export const visLen = (s) => bare(s).length;
+
+/** The first `width` visible characters, with escape sequences left intact. */
+export function sliceVis(s, width) {
+  let out = '';
+  let seen = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '\x1b') {
+      const m = /^\x1b\[[0-9;]*m/.exec(s.slice(i));
+      if (m) { out += m[0]; i += m[0].length - 1; continue; }
+    }
+    if (seen >= width) break;
+    out += s[i];
+    seen++;
+  }
+  return out;
+}
+
+/** Pad or hard-cut a possibly-coloured string to an exact visible width. */
+export function padVis(s, width) {
+  const len = visLen(s);
+  if (len === width) return s;
+  if (len < width) return s + ' '.repeat(width - len);
+  return `${sliceVis(s, width)}\x1b[0m`;
+}
+
+export function clip(text, max) {
+  const s = String(text ?? '');
+  if (max <= 1) return '';
+  return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
+/**
+ * Word-wrap text that may already be coloured.
+ *
+ * Escape sequences have no width, and whichever styles are open at a break get
+ * reopened on the next line — otherwise a wrapped sentence loses its colour
+ * halfway through.
+ */
+export function wrapAnsi(text, width) {
+  if (width < 4) return [text];
+
+  const lines = [];
+  let line = '';
+  let seen = 0;
+  let open = '';
+  let lastSpace = -1;
+  let lastSpaceSeen = 0;
+
+  const flush = (upto = null) => {
+    if (upto === null) {
+      lines.push(line);
+      line = open;
+      seen = 0;
+    } else {
+      lines.push(line.slice(0, upto));
+      const carry = line.slice(upto).replace(/^ +/, '');
+      line = open + carry;
+      seen = visLen(carry);
+    }
+    lastSpace = -1;
+  };
+
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '\x1b') {
+      const m = /^\x1b\[[0-9;]*m/.exec(text.slice(i));
+      if (m) {
+        line += m[0];
+        open = m[0] === '\x1b[0m' ? '' : open + m[0];
+        i += m[0].length - 1;
+        continue;
+      }
+    }
+    if (text[i] === ' ') { lastSpace = line.length; lastSpaceSeen = seen; }
+    line += text[i];
+    seen++;
+    if (seen >= width) {
+      // Break at a word boundary unless that would leave a stub behind.
+      if (lastSpace > 0 && lastSpaceSeen > width * 0.4) flush(lastSpace);
+      else flush();
+    }
+  }
+
+  if (visLen(line)) lines.push(line);
+  return lines.length ? lines : [''];
+}
+
+// ---------------------------------------------------------------------------
+// Small formatters
+// ---------------------------------------------------------------------------
+
+export function formatTokens(n) {
+  if (!n) return '0';
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return `${(n / 1000).toFixed(n < 10_000 ? 1 : 0)}k`;
+  return `${(n / 1_000_000).toFixed(1)}M`;
+}
+
+export function today() {
+  return new Date().toLocaleDateString('en-GB', { day: 'numeric', month: 'short', year: 'numeric' });
+}
+
+/** Shorten a path for display: home becomes ~, a long middle collapses. */
+export function shortenPath(p, max = 40) {
+  let out = String(p);
+  const home = process.env.USERPROFILE || process.env.HOME || '';
+  if (home && out.startsWith(home)) out = `~${out.slice(home.length)}`;
+  if (out.length <= max) return out;
+
+  const parts = out.split(/[\\/]/);
+  if (parts.length <= 3) return `…${out.slice(-(max - 1))}`;
+  const sep = out.includes('\\') ? '\\' : '/';
+  return `${parts[0]}${sep}…${sep}${parts.slice(-2).join(sep)}`;
+}
+
+export function relativeTime(iso) {
+  if (!iso) return 'unknown';
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return 'unknown';
+
+  const secs = Math.max(0, Math.round((Date.now() - then) / 1000));
+  if (secs < 60) return 'just now';
+  const mins = Math.round(secs / 60);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.round(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.round(hours / 24);
+  return days < 30 ? `${days}d ago` : new Date(iso).toISOString().slice(0, 10);
+}
+
+/**
+ * Trim a trailing full stop off a live status line.
+ *
+ * "Listing src" is a label on work in progress. "Listing src." is a sentence,
+ * and a sentence that ends while the thing it describes is still happening
+ * reads as finished when it is not. Models add the full stop by habit; this
+ * takes it back off.
+ *
+ * Only after a word, though. A dot that follows a space is the whole point of
+ * the line — "Listing ." names the current directory — and trimming that turns
+ * a label into a fragment.
+ */
+export function asLabel(text) {
+  return String(text ?? '')
+    .trim()
+    .replace(/\s+/g, ' ')
+    // A trailing stop, from a model's sentence or a tool's own output
+    // ("Building…", "Completing…"), is noise on a one-line label. A dot that
+    // is the argument itself — "Listing ." — is not, so a word has to come
+    // before it.
+    .replace(/(?<=[\w)\]"'`])[.。…]+$/, '');
+}
+
+/**
+ * The model's checklist, as one short line — done ticked, the current item
+ * marked, the rest dim — so progress is visible without taking over the screen.
+ */
+/**
+ * The plan, as a block rather than a sentence.
+ *
+ * Six steps joined with separators made one line far wider than any terminal,
+ * so it wrapped — and a wrapped checklist has its ticks in the middle of the
+ * text, which is unreadable. Down the page each step keeps its own row, its
+ * mark stays in the left column, and the eye can find the one in progress
+ * without reading any of the others.
+ *
+ * Returns the rows; the caller pushes them.
+ */
+export function planRows(items) {
+  const list = (Array.isArray(items) ? items : []).slice(0, 8);
+  if (!list.length) return [];
+  const done = list.filter((i) => i?.done).length;
+  const current = list.findIndex((i) => !i?.done);
+
+  const rows = [`  ${sky(`plan ${done}/${list.length}`)}`];
+  list.forEach((item, i) => {
+    const text = clip(String(item?.text ?? '').trim(), 64);
+    if (item?.done) rows.push(`    ${theme.ok('✓')} ${dim(text)}`);
+    else if (i === current) rows.push(`    ${blue('▸')} ${chalk.white(text)}`);
+    else rows.push(`    ${dim('○')} ${dim(text)}`);
+  });
+  return rows;
+}
+
+/** Kept for the plain interface, which has one line to work with. */
+export function planLine(items) {
+  const list = (Array.isArray(items) ? items : []).slice(0, 6);
+  if (!list.length) return '';
+  const done = list.filter((i) => i?.done).length;
+  const current = list.findIndex((i) => !i?.done);
+  const now = current === -1 ? 'done' : clip(String(list[current]?.text ?? '').trim(), 40);
+  return `  ${sky(`plan ${done}/${list.length}`)}  ${chalk.white(now)}`;
+}
+
+/**
+ * Narration: what the agent is doing, as opposed to what it has to say.
+ *
+ * These lines are scaffolding — "Reading screen.js", "Checking types". They
+ * are worth seeing and not worth reading, and at full strength they compete
+ * with the answer, which is the thing the user is actually here for. A
+ * terminal has no smaller size to set, so the only axis available is weight:
+ * faint, and a step down in colour. The answer stays at full strength and
+ * wins the page by contrast rather than by shouting.
+ */
+export const narration = (text) => chalk.dim(text);
+
+/** The bullet beside a narration line: present, not loud. */
+export const narrationMark = () => chalk.dim(deep('●'));
+
+/**
+ * How a run of the same kind of step reads once it is over.
+ *
+ * While it happens, "Running npm test" is the useful thing to show. Once
+ * three of them have happened, three near-identical lines are just noise
+ * between the reader and the answer, so they fold into one: "Ran 3 commands".
+ * The present tense belongs to the thing happening now; the past tense to the
+ * summary of what did.
+ */
+const GROUPS = {
+  Running: ['Ran', 'command', 'commands'],
+  Reading: ['Read', 'file', 'files'],
+  Searching: ['Searched', 'time', 'times'],
+  Finding: ['Found', 'pattern', 'patterns'],
+  Listing: ['Listed', 'directory', 'directories'],
+  Writing: ['Wrote', 'file', 'files'],
+  Editing: ['Edited', 'file', 'files'],
+  Checking: ['Checked', 'thing', 'things'],
+  Looking: ['Looked up', 'name', 'names'],
+  Asking: ['Asked about', 'name', 'names'],
+  Mapping: ['Mapped', 'folder', 'folders'],
+  Adding: ['Added', 'block', 'blocks'],
+  Renaming: ['Renamed', 'name', 'names'],
+};
+
+/** The first word of a label, which is what decides whether two steps match. */
+export const groupKind = (label) => String(label ?? '').trim().split(/\s+/)[0] ?? '';
+
+/** One line standing in for `count` steps that all began with the same word. */
+export function groupLabel(label, count) {
+  if (count <= 1) return String(label ?? '');
+  const g = GROUPS[groupKind(label)];
+  if (!g) return `${label} (+${count - 1} more)`;
+  const [past, one, many] = g;
+  return `${past} ${count} ${count === 1 ? one : many}`;
+}
+
+/** The part of a label after its opening word: the file or command it is about. */
+export const groupTarget = (label) => String(label ?? '').trim().split(/\s+/).slice(1).join(' ');
+
+/**
+ * One narration line, standing for everything that happened under it.
+ *
+ * The transcript is a record of what was done, not a copy of what was
+ * written. A 539-line file printed into it buries the answer and tells the
+ * reader nothing they could not get from the file itself, so a change is its
+ * two numbers. Several steps on one file stay one line naming that file;
+ * several files become a count.
+ */
+export function runLine({ label, count = 1, targets = [], added = 0, removed = 0 }) {
+  const counts = added || removed
+    ? ` ${chalk.hex('#3fb950')(`+${added}`)} ${chalk.hex('#f2939c')(`-${removed}`)}`
+    : '';
+  if (count <= 1) return `${label}${counts}`;
+
+  const g = GROUPS[groupKind(label)];
+  const unique = [...new Set(targets.filter(Boolean))];
+  if (g && unique.length === 1) return `${g[0]} ${unique[0]}${counts}`;
+  if (!g) return `${label} (+${count - 1} more)${counts}`;
+  return `${g[0]} ${count} ${count === 1 ? g[1] : g[2]}${counts}`;
+}
+
+/**
+ * The reply, with any pasted code taken out of it.
+ *
+ * The model is asked not to paste code into its answer, and mostly does not.
+ * When it does, a fenced block of forty lines pushes the two sentences worth
+ * reading off the screen — and the code is already in the file it just wrote.
+ * A fence becomes a note of what it was, and the prose stays.
+ *
+ * A short block is left alone: three lines showing a command to run, or the
+ * one line that changed, is the kind of thing worth having in the answer.
+ */
+export function withoutCodeBlocks(text, keepLines = 4) {
+  const FENCE = /```([A-Za-z0-9+-]*)\n([\s\S]*?)```/g;
+  return String(text ?? '').replace(FENCE, (all, lang, body) => {
+    const lines = body.replace(/\n+$/, '').split('\n');
+    if (lines.length <= keepLines) return all;
+    const what = lang ? `${lang} ` : '';
+    return `_[${lines.length} lines of ${what}code — it is in the file, not worth repeating here]_`;
+  });
+}