ucode-agent 1.28.1 → 1.29.0

package/README.md

@@ -19,32 +19,37 @@ corner:
   ╭──────────────────────────────────────────────────────────────────────────────╮
   │ › Ask anything…                                                              │
   │                                                                              │
-  │ ◆ Build · North Mini Code                                                 0% │
+  │  BUILD   North Mini Code                                                  0% │
   ╰──────────────────────────────────────────────────────────────────────────────╯
 
+   try   build me a landing page for a coffee shop
+         explain what this project does and how it fits together
+         add a dark mode toggle that remembers the choice
 
-                                                                            v1.2.0
+
+                                                                           v1.29.0
 ```
 
-and once you are talking, each message you send is boxed in the same blue as
-the input, so your own words are easy to find in a long session:
+A light crosses the wordmark once as it opens, and the three lines under the box
+are there so an empty screen has something to say. Once you are talking, each
+message you send is marked down its left edge in the same blue as the input, so
+your own words are easy to find in a long session — and each step the agent
+takes carries the shape of the work: a hollow diamond to look, a filled one to
+change, an arrow to run.
 
 ```
-╭──────────────────────────────────────────────────────────────────────────────────╮
-│ › build a notes dashboard                                                        │
-╰──────────────────────────────────────────────────────────────────────────────────╯
-● Writing index.html
-  └ created · 148 lines
-       1 + <!doctype html>
-       2 + <html lang="en">
-         … 146 more lines
-● Running npm run dev
-  └ ready · http://localhost:3000 · PID 4812
+▌ build a notes dashboard
+
+◇ Read 3 files
+◆ Writing index.html +148 -0
+▸ Running npm run dev
+
+The dashboard is at http://localhost:3000, and `npm run dev` brings it back up.
 
 ╭──────────────────────────────────────────────────────────────────────────────────╮
 │ › now add a dark mode toggle                                                     │
 │                                                                                  │
-│ ◆ Build · North Mini Code                                                     4% │
+│  BUILD   North Mini Code                                                      4% │
 ╰──────────────────────────────────────────────────────────────────────────────────╯
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucode-agent",
-  "version": "1.28.1",
+  "version": "1.29.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/core/git.js

@@ -0,0 +1,65 @@
+/**
+ * git.js — which branch you are on, read off the disk rather than shelled out.
+ *
+ * The header wants one word. Spawning `git` to get it would cost a process at
+ * startup and fail differently on every machine, where `.git/HEAD` is a single
+ * line in a documented format that has not changed in twenty years.
+ */
+
+import { readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+/** `ref: refs/heads/main` → `main`; a bare sha → its first seven characters. */
+export function parseHead(text) {
+  const head = String(text ?? '').trim();
+  if (!head) return '';
+  const ref = /^ref:\s*refs\/heads\/(.+)$/.exec(head);
+  if (ref) return ref[1];
+  // A detached head is the commit itself, which is worth saying as such.
+  return /^[0-9a-f]{7,40}$/i.test(head) ? head.slice(0, 7) : '';
+}
+
+/**
+ * The repository directory for a folder, walking up until one is found.
+ *
+ * In a worktree or a submodule `.git` is a file pointing elsewhere, so the
+ * pointer is followed — otherwise every worktree would report no branch.
+ */
+function repoDir(start) {
+  let dir = path.resolve(start);
+  for (let up = 0; up < 40; up++) {
+    const dot = path.join(dir, '.git');
+    try {
+      const stat = statSync(dot);
+      if (stat.isDirectory()) return dot;
+      if (stat.isFile()) {
+        const link = /^gitdir:\s*(.+)$/m.exec(readFileSync(dot, 'utf8'));
+        if (link) return path.resolve(dir, link[1].trim());
+        return '';
+      }
+    } catch {
+      // Not here; keep walking up.
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return '';
+    dir = parent;
+  }
+  return '';
+}
+
+/**
+ * The branch name for a folder, or '' when it is not a repository.
+ *
+ * Never throws. A header that cannot be drawn because a permission check
+ * failed on a folder above the project would be a worse bug than a missing
+ * word, so every failure here is the same as "not a repository".
+ */
+export function gitBranch(cwd) {
+  try {
+    const dir = repoDir(cwd);
+    if (!dir) return '';
+    return parseHead(readFileSync(path.join(dir, 'HEAD'), 'utf8'));
+  } catch {
+    return '';
+  }
+}

package/src/ui/activity.js

@@ -1,206 +1,259 @@
-/**
- * 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, { ok = true } = {}) {
-  // The step count is bookkeeping: it tells the reader nothing about whether
-  // the thing they asked for exists. /stats has it for anyone who wants it.
-  void steps;
-  if (!ok) return `${theme.warn('!')} ${dim(`Stopped after ${formatDuration(ms)} without finishing`)}`;
-  return `${theme.ok('✓')} ${dim(`Done in ${formatDuration(ms)}`)}`;
-}
-
-/** 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, bannerRGB, bannerPaint } 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 wordmark with a light passing across it, once, at launch.
+ *
+ * The first thing anyone sees of a program is the half second before they can
+ * type, and ucode was spending it showing a finished picture. A band of light
+ * crossing the mark left to right in that same half second costs nothing, is
+ * over before it can annoy anyone, and is the difference between a logo that
+ * was printed and one that arrived.
+ *
+ * Every row is swept from the same clock, so the light is a vertical bar
+ * travelling across the whole wordmark rather than six separate glints. It
+ * blends out of the row's own gradient colour, not out of a flat blue, so the
+ * moment it passes the mark is exactly what it will look like at rest.
+ *
+ * Below 256 colours there are no in-between shades to fade through, so the
+ * mark is simply drawn finished — a two-colour "sweep" is a flicker.
+ */
+export const SWEEP_MS = 620;
+
+/** Half the width of the travelling band, in characters. */
+const SWEEP_BAND = 7;
+
+export function bannerSweep(line, row, rows, elapsed, { level = chalk.level } = {}) {
+  const text = String(line ?? '');
+  const rest = bannerRGB(row, rows);
+  const progress = SWEEP_MS > 0 ? elapsed / SWEEP_MS : 1;
+  if (level < 2 || !text || progress >= 1 || progress < 0) return bannerPaint(row, rows)(text);
+
+  // The centre starts off the left edge and ends off the right, so the band
+  // enters and leaves rather than appearing in the middle of the letters.
+  const centre = progress * (text.length + SWEEP_BAND * 2) - SWEEP_BAND;
+
+  let out = '';
+  let run = '';
+  let runStep = -1;
+  const flush = () => {
+    if (!run) return;
+    const [r, g, b] = mix(rest, PEAK_RGB, runStep / STEPS);
+    out += painter(level).rgb(r, g, b)(run);
+    run = '';
+  };
+
+  for (let i = 0; i < text.length; i++) {
+    const distance = Math.abs(i - centre);
+    const k = distance < SWEEP_BAND ? (Math.cos((Math.PI * distance) / SWEEP_BAND) + 1) / 2 : 0;
+    const step = Math.round(k * STEPS);
+    if (step !== runStep) { flush(); runStep = step; }
+    run += text[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, { ok = true } = {}) {
+  // The step count is bookkeeping: it tells the reader nothing about whether
+  // the thing they asked for exists. /stats has it for anyone who wants it.
+  void steps;
+  if (!ok) return `${theme.warn('!')} ${dim(`Stopped after ${formatDuration(ms)} without finishing`)}`;
+  return `${theme.ok('✓')} ${dim(`Done in ${formatDuration(ms)}`)}`;
+}
+
+/** The step count, brighter for a moment right after it goes up. */
+export function stepPaint(justMoved) {
+  return justMoved ? sky : dim;
+}

package/src/ui/plain.js

@@ -13,7 +13,7 @@ import readline from 'node:readline';
 import chalk from 'chalk';
 import {
   theme, blue, sky, dim, boxTop, boxBottom, boxRow,
-  BANNER, BANNER_WIDTH, SPINNER, clip, shortenPath, asLabel, padVis, visLen, planLine, bannerPaint,
+  BANNER, BANNER_WIDTH, SPINNER, clip, shortenPath, asLabel, padVis, visLen, planLine, bannerPaint, modeChip, narrationMark, groupKind,
   tidyReply, trimAnswer,
 } from './theme.js';
 import { formatDuration, doneLine } from './activity.js';
@@ -132,8 +132,8 @@ export class Plain {
   /** The same three facts the full screen shows, on the row under the header. */
   statusRow() {
     const inner = this.width() - 2;
-    const chip = this.mode === 'plan' ? `${sky('◇')} ${sky('Plan')}` : `${blue('◆')} ${blue('Build')}`;
-    const left = ` ${chip} ${dim('·')} ${chalk.white(this.model || '—')}`;
+    const chip = modeChip(this.mode);
+    const left = ` ${chip}  ${chalk.white(this.model || '—')}`;
     const percent = Math.round(this.percent ?? 0);
     const right = `${percent >= 75 ? theme.warn(`${percent}%`) : dim(`${percent}%`)} `;
     const pad = Math.max(1, inner - visLen(left) - visLen(right));
@@ -142,7 +142,7 @@ export class Plain {
 
   toolCall(label) {
     this.stopSpinner();
-    this.output.write(`${blue('●')} ${asLabel(label)}\n`);
+    this.output.write(`${narrationMark(groupKind(label))} ${asLabel(label)}\n`);
   }
 
   plan(items) {

package/src/ui/screen.js

@@ -40,8 +40,9 @@ 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, tidyReply, trimAnswer,
-  bannerPaint, RAIL } from './theme.js';
-import { FRAME_MS, fitActivity, shimmer, spinnerGlyph, formatDuration, doneLine, stepPaint } from './activity.js';
+  bannerPaint, RAIL, modeChip } from './theme.js';
+import { FRAME_MS, fitActivity, shimmer, spinnerGlyph, formatDuration, doneLine, stepPaint, bannerSweep, SWEEP_MS } from './activity.js';
+import { gitBranch } from '../core/git.js';
 import { renderer, render, polish } from './markdown.js';
 import { VERSION } from '../core/version.js';
 
@@ -129,6 +130,28 @@ const WORKING_HINT = 'Working… type to queue your next message';
 const WORKING_HINT_SHORT = 'Working…';
 const WORKING_HINT_NEEDS = WORKING_HINT.length + 8;
 
+/**
+ * Three things to try, under the box, on a screen with nothing on it yet.
+ *
+ * A wordmark over an empty field is handsome and tells you nothing you can act
+ * on — the first thing a new user has to do is guess what this accepts. Three
+ * greyed lines answer that in one glance, and they say something about the
+ * range of it too: build something new, understand something that exists,
+ * change something small. They are dim, and they are gone the moment anything
+ * is on the screen.
+ */
+const SUGGESTIONS = [
+  'build me a landing page for a coffee shop',
+  'explain what this project does and how it fits together',
+  'add a dark mode toggle that remembers the choice',
+];
+
+/** The width of the `try` label, so the three lines share one left edge. */
+const SUGGEST_LABEL = 6;
+
+/** Rows the suggestions occupy under the box: one of air, then the three. */
+const SUGGEST_ROWS = SUGGESTIONS.length + 1;
+
 export class Screen {
   constructor({ cwd, input = process.stdin, output = process.stdout } = {}) {
     this.cwd = cwd;
@@ -160,7 +183,10 @@ export class Screen {
     this.paintedBusy = false;  // whose turn the frame on screen was drawn for
     this.activity = null; // the turn in flight: when it began, how many steps
     this.tick = 0;        // animation frames painted, for the spinner
+    this.intro = 0;       // when the launch sweep began, 0 once it is over
+    this.introTimer = null;
     this.pendingPrompt = null;
+    this.facts.branch = gitBranch(cwd);
 
     this.cols = output.columns || 80;
     this.rows = output.rows || 24;
@@ -186,10 +212,39 @@ export class Screen {
     this.output.on('resize', this.onResize);
 
     this.render();
+    this.startIntro();
+  }
+
+  /**
+   * The light that crosses the wordmark once, at launch.
+   *
+   * Half a second, on the start screen only, and abandoned the instant there is
+   * anything else to look at. Below 256 colours there are no shades to fade
+   * through, so it is skipped rather than flickered.
+   */
+  startIntro() {
+    if (!this.output.isTTY || chalk.level < 2 || !this.welcoming()) return;
+    this.intro = Date.now();
+    this.introTimer = setInterval(() => {
+      if (this.closed || !this.welcoming() || Date.now() - this.intro >= SWEEP_MS) this.stopIntro();
+      else this.render();
+    }, FRAME_MS);
+    this.introTimer.unref?.();
+  }
+
+  stopIntro() {
+    if (this.introTimer) clearInterval(this.introTimer);
+    this.introTimer = null;
+    if (!this.intro) return;
+    this.intro = 0;
+    if (!this.closed) this.render();
   }
 
   stop() {
     this.activity = null;
+    if (this.introTimer) clearInterval(this.introTimer);
+    this.introTimer = null;
+    this.intro = 0;
     this.stopSpinner();
     this.stopTimer();
     this.output.off?.('resize', this.onResize);
@@ -361,7 +416,7 @@ export class Screen {
         kind, count: 1, at: 0, label: clean,
         targets: [groupTarget(clean)], added: 0, removed: 0,
       };
-      this.push(`${narrationMark()} ${runLine(fresh)}`);
+      this.push(`${narrationMark(kind)} ${runLine(fresh)}`);
       fresh.at = this.lines.length - 1;
       this.run = fresh;
       this.segment.set(kind, fresh);
@@ -402,7 +457,7 @@ export class Screen {
    */
   paintRun() {
     if (!this.run) return;
-    this.lines[this.run.at] = `${narrationMark()} ${runLine(this.run)}`;
+    this.lines[this.run.at] = `${narrationMark(this.run.kind)} ${runLine(this.run)}`;
     this.render();
   }
 
@@ -628,6 +683,7 @@ export class Screen {
 
   /** Same shape as the plain UI's header(), so the loop needs no branch. */
   header({ cwd, model, used, limit, title: sessionTitle }) {
+    if (cwd && cwd !== this.facts.cwd) this.facts.branch = gitBranch(cwd);
     this.setFacts({
       cwd,
       model,
@@ -662,30 +718,46 @@ export class Screen {
 
     // Two spaces of padding, the wordmark, a gap, then the facts column.
     //
-    // Only what you cannot work out by looking: where you are, and how to get
-    // help. How full the window is belongs on the status row next to the model
-    // it describes, and the session title is already the terminal's own window
-    // title — repeating either here is a second place to keep in sync for no
-    // reader who needed it.
+    // Only what you cannot work out by looking, and never what the status row
+    // already carries: the model and how full the window is live down there,
+    // next to each other, and a second copy up here would be a second place to
+    // keep in sync for no reader who needed it. What is left is where you are,
+    // which branch that is on, which build you are running, and the two keys
+    // worth knowing before you have typed anything.
+    //
+    // Every row has something on it. Three blank rows and a credit floating
+    // under them read as a column that was meant to be filled and was not.
     const room = Math.max(8, inner - BANNER_WIDTH - 6);
+    const value = (v) => clip(String(v), Math.max(4, room - 10));
+    const branch = this.facts.branch;
     const facts = [
-      ['dir', shortenPath(this.facts.cwd ?? this.cwd, room - 9)],
-      ['keys', '/help · esc interrupts'],
-      ['', ''],
-      ['', ''],
+      ['dir', value(shortenPath(this.facts.cwd ?? this.cwd, room - 10))],
+      branch ? ['branch', value(branch)] : ['', ''],
+      VERSION ? ['version', value(this.facts.update ? `${VERSION} → ${this.facts.update} next start` : VERSION)] : ['', ''],
       ['', ''],
+      ['keys', value('/help · esc interrupts · ctrl+b plan')],
       ['', 'made with ❤️ by om dixit'],
     ];
 
     const rows = BANNER.map((art, i) => {
-      const [label, value] = facts[i] ?? ['', ''];
+      const [label, text] = facts[i] ?? ['', ''];
       const right = label
-        ? `${dim(label.padEnd(9))}${chalk.white(clip(value, room - 9))}`
-        : (value ? dim(value) : '');
+        ? `${dim(label.padEnd(10))}${chalk.white(text)}`
+        : (text ? dim(text) : '');
       return `  ${bannerPaint(i)(art)}   ${right}`;
     });
 
-    return [boxTop(width), ...rows.map((r) => boxRow(r, width)), boxBottom(width)];
+    // The frame is lit the way the wordmark inside it is: brightest along the
+    // top rule, settling to deep at the bottom. Eight rows of box for six of
+    // banner, so the borders take the two ends of the same ramp and the box
+    // reads as one object with a light above it rather than as a rule someone
+    // drew around a picture.
+    const depth = BANNER.length + 2;
+    return [
+      boxTop(width, bannerPaint(0, depth)),
+      ...rows.map((r, i) => boxRow(r, width, bannerPaint(i + 1, depth))),
+      boxBottom(width, bannerPaint(depth - 1, depth)),
+    ];
   }
 
   // -- input box -----------------------------------------------------------
@@ -809,7 +881,7 @@ export class Screen {
   // -- status row ----------------------------------------------------------
 
   modeChip() {
-    return this.mode === 'plan' ? `${sky('◇')} ${sky('Plan')}` : `${blue('◆')} ${blue('Build')}`;
+    return modeChip(this.mode);
   }
 
   /**
@@ -837,7 +909,7 @@ export class Screen {
   statusRow(width = this.width()) {
     const inner = width - 2;             // the space between the two borders
     const chip = this.modeChip();
-    const left = ` ${chip} ${dim('·')} ${chalk.white(this.model || '—')}`;
+    const left = ` ${chip}  ${chalk.white(this.model || '—')}`;
     const right = `${this.percentChip()} `;
 
     // Where a click on the bottom row still counts as hitting the mode chip.
@@ -1457,10 +1529,12 @@ export class Screen {
     const big = cols >= BANNER_WIDTH + 4 && this.rows >= 18;
     const art = big ? BANNER : ['u c o d e'];
     const inputRows = this.inputLines(boxWidth - 4).rows.length;
-    const block = art.length + 2 + inputRows + 4;          // wordmark, gap, box
+    const boxRows = inputRows + 4;                         // borders, typed rows, gap, status
+    const suggest = this.rows >= boxRows + art.length + SUGGEST_ROWS + 6;
+    const block = art.length + 2 + boxRows + (suggest ? SUGGEST_ROWS : 0);
     // A touch above true centre reads as centred; exact centre looks low.
     const top = Math.max(0, Math.floor((this.rows - block) / 2) - 1);
-    return { cols, boxWidth, left, big, art, inputRows, top, boxTop: top + art.length + 2 };
+    return { cols, boxWidth, left, big, art, inputRows, boxRows, suggest, top, boxTop: top + art.length + 2 };
   }
 
   renderWelcome() {
@@ -1471,9 +1545,12 @@ export class Screen {
     // rows. Across the rows rather than along them — a name split down its
     // middle reads as two words, where a name that fades downward reads as
     // one object with a light on it.
+    const elapsed = this.intro ? Date.now() - this.intro : Infinity;
     g.art.forEach((line, i) => {
       const pad = ' '.repeat(Math.max(0, Math.floor((g.cols - line.length) / 2)));
-      frame[g.top + i] = pad + (g.big ? bannerPaint(i, g.art.length)(line) : blue.bold(line));
+      frame[g.top + i] = pad + (g.big
+        ? bannerSweep(line, i, g.art.length, elapsed)
+        : blue.bold(line));
     });
 
     const indent = ' '.repeat(g.left);
@@ -1481,6 +1558,15 @@ export class Screen {
       frame[g.boxTop + i] = indent + row;
     });
 
+    // Three things to try, aligned with the text inside the box above them.
+    if (g.suggest) {
+      const at = g.boxTop + g.boxRows + 1;
+      SUGGESTIONS.forEach((text, i) => {
+        const label = i === 0 ? 'try'.padEnd(SUGGEST_LABEL) : ' '.repeat(SUGGEST_LABEL);
+        frame[at + i] = `${indent} ${dim(sky(label))}${dim(clip(text, Math.max(8, g.boxWidth - SUGGEST_LABEL - 2)))}`;
+      });
+    }
+
     // The version, in the corner, and nothing else on the screen.
     if (VERSION) {
       const tag = dim(this.facts.update ? `v${VERSION} · v${this.facts.update} installed, starts next time` : `v${VERSION}`);

package/src/ui/theme.js

@@ -90,12 +90,13 @@ export const BANNER_WIDTH = Math.max(...BANNER.map((r) => r.length));
 const GRADIENT_TOP = [0x8f, 0xbc, 0xff];      // sky, at the crown
 const GRADIENT_BOTTOM = [0x2f, 0x6f, 0xe0];   // deep, in the shadow
 
-export function bannerPaint(row, rows = BANNER.length) {
+export function bannerRGB(row, rows = BANNER.length) {
   const t = rows > 1 ? Math.min(1, Math.max(0, row / (rows - 1))) : 0;
-  const hex = GRADIENT_TOP
-    .map((from, i) => Math.round(from + (GRADIENT_BOTTOM[i] - from) * t))
-    .map((v) => v.toString(16).padStart(2, '0'))
-    .join('');
+  return GRADIENT_TOP.map((from, i) => Math.round(from + (GRADIENT_BOTTOM[i] - from) * t));
+}
+
+export function bannerPaint(row, rows = BANNER.length) {
+  const hex = bannerRGB(row, rows).map((v) => v.toString(16).padStart(2, '0')).join('');
   return chalk.hex(`#${hex}`);
 }
 
@@ -108,6 +109,24 @@ export function bannerPaint(row, rows = BANNER.length) {
  */
 export const RAIL = '▌';
 
+/**
+ * Which mode is live, as a filled pill.
+ *
+ * A glyph and a word is a label; a block of colour with the word knocked out
+ * of it is a control, and the mode is the one thing on the status row you can
+ * actually change. Build is the solid blue — it may edit and run. Plan is the
+ * same shape muted, because a read-only mode should not look armed.
+ *
+ * Small enough not to be the background painting that was taken out of here
+ * once: it is the width of the word, the way a diff's tint is the width of the
+ * line it marks.
+ */
+export const BUILD_CHIP = chalk.bgHex('#4d8dff').hex('#0b1220').bold;
+export const PLAN_CHIP = chalk.bgHex('#24344f').hex('#8fbcff').bold;
+
+export const modeChip = (mode) =>
+  mode === 'plan' ? PLAN_CHIP(' PLAN ') : BUILD_CHIP(' BUILD ');
+
 /** The spinner. Braille dots, because they animate in place without jitter. */
 export const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 
@@ -361,8 +380,32 @@ export function planLine(items) {
  */
 export const narration = (text) => chalk.dim(text);
 
-/** The bullet beside a narration line: present, not loud. */
-export const narrationMark = () => chalk.dim(deep('●'));
+/**
+ * The bullet beside a narration line: present, not loud.
+ *
+ * Three shapes rather than one dot repeated. Every step drawn identically made
+ * a long transcript a column of the same mark forty times over, which reads as
+ * output rather than as work — and the shape is free, where a fourth colour
+ * would not be. A diamond is hollow when the agent is only looking at
+ * something and filled when it changes it, and a run of a command points
+ * forward. Anything unmapped keeps the original dot.
+ *
+ * All of them stay dim: the glyph carries the kind, the weight still says this
+ * is scaffolding and the answer below is the thing to read.
+ */
+const MARKS = {
+  Reading: ['◇', deep], Listing: ['◇', deep], Looking: ['◇', deep],
+  Asking: ['◇', deep], Mapping: ['◇', deep], Searching: ['◇', deep],
+  Finding: ['◇', deep],
+  Writing: ['◆', blue], Editing: ['◆', blue], Adding: ['◆', blue],
+  Renaming: ['◆', blue],
+  Running: ['▸', sky], Checking: ['▸', sky],
+};
+
+export const narrationMark = (kind) => {
+  const [glyph, paint] = MARKS[kind] ?? ['●', deep];
+  return chalk.dim(paint(glyph));
+};
 
 /**
  * The file or command a step is about, lit so the line can be scanned.