@causyne/agent 1.10.18 → 1.10.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causyne/agent",
-  "version": "1.10.18",
+  "version": "1.10.19",
   "description": "Agentic AI for software, tools, and computer workflows",
   "main": "bin/causyne.js",
   "type": "module",

package/src/tui/banner.js

@@ -1,203 +1,402 @@
-// The banner: the wordmark, and the first thing a new user is invited to ask.
-//
-// This lives in its own module because it is written ONCE, straight into the
-// user's real terminal history, before anything else runs — the same shape
-// openclaw uses (src/cli/banner.ts emitCliBanner: art first, metadata line
-// underneath) and opencode's entry splash, whose own comment calls these
-// "scrollback snapshots ... immutable terminal history once committed".
-//
-// Nothing here repaints. Nothing here clears. See UX-01 in .agents/rules.json.
-//
-// Pure Node over theme.js and text.js. No dependency, no shell.
-
-import { paint, bold, dim, GLYPHS, HAS_UNICODE } from './theme.js';
-import { visibleWidth, truncate, padEnd, shortenHome } from './text.js';
-
-// Painted through the theme rather than with a hardcoded \x1b[1m\x1b[36m, so it
-// still obeys NO_COLOR and still degrades on a terminal without box-drawing.
-const WORDMARK = [
-  ' ████   ███  █   █  ████ █   █ █   █ █████',
-  '█      █   █ █   █ █      █ █  ██  █ █    ',
-  '█      █████ █   █  ███    █   █ █ █ ████ ',
-  '█      █   █ █   █     █   █   █  ██ █    ',
-  ' ████  █   █  ███  ████    █   █   █ █████'
-];
-
-// A compact terminal rendering of the six-part Causyne aperture. The shape is
-// sampled from the canonical SVG rather than invented as a second logo. Its
-// upper-right blade carries the signal green; the other blades use the neutral
-// brand ink. Each row remains ordinary terminal text and degrades to #/+ ASCII.
-const LOGO_SEGMENTS = [
-  [['ink', '   ███▓']],
-  [['ink', ' ▓███'], ['accent', '███'], ['ink', '▓']],
-  [['ink', '▓███ ▓▓'], ['accent', '██'], ['ink', '▓']],
-  [['ink', '▓██   ▓██▓']],
-  [['ink', '▓███▓ ███▓']],
-  [['ink', ' ███████▓']],
-  [['ink', '   ▓███']]
-];
-
-function logoRows(unicode) {
-  return LOGO_SEGMENTS.map((segments) => segments.map(([role, text]) => {
-    const rendered = unicode
-      ? text
-      : text.replace(/[█▓]/g, role === 'accent' ? '+' : '#');
-    return paint(role, rendered);
-  }).join(''));
-}
-
-function brandArt(width, unicode) {
-  if (!unicode || width < 64) {
-    const logo = logoRows(false);
-    logo[2] = `${padEnd(logo[2], 12)}${bold(paint('ink', 'CAUSYNE AGENT'))}`;
-    return logo;
-  }
-
-  const logo = logoRows(true);
-  return logo.map((line, index) => {
-    const word = WORDMARK[index - 1];
-    return word === undefined
-      ? line
-      : `${padEnd(line, 10)}   ${paint('ink', word)}`;
-  });
-}
-
 /**
- * The banner rows.
+ * Canonical Causyne Agent terminal identity: aperture, pixel wordmark, status,
+ * and adaptive fallbacks. TypeScript is the source; the repository build emits
+ * the readable ESM file imported by the CLI.
  *
- * `unicode` is overridable so both branches can actually be tested — under
- * `node --test` there is no TTY, so HAS_UNICODE is false and the block art would
- * never be exercised at all.
+ * Environment: NO_COLOR, CAUSYNE_NO_COLOR, FORCE_COLOR=1|2|3,
+ * CAUSYNE_ASCII=1 (7-bit only), and CAUSYNE_NO_ANIM=1.
  */
-export function wordmark(width = 80, { unicode = HAS_UNICODE } = {}) {
-  const rows = brandArt(width, unicode);
-  rows.push('');
-  rows.push(dim('Causyne Agent'));
-  return rows;
+import { homedir } from 'node:os';
+export const TAGLINE = 'From intention to meaningful progress.';
+// ---- Logo -----------------------------------------------------------------------------------------------
+// One character = one "pixel". A terminal cell holds two stacked pixels (drawn with the half blocks ▀ ▄ █).
+// '.' is empty, 0-5 is the blade id. Blade 0 is the lime one (top-right); ids run clockwise.
+const LOGO_L = [
+    '......................',
+    '.........5555.........',
+    '.......555555.........',
+    '.....5555555.0000.....',
+    '....5555555.0000000...',
+    '...5555555.000000000..',
+    '....55555.00000000000.',
+    '.44.5555.......000000.',
+    '.444.55...........000.',
+    '.444..5........111..0.',
+    '.4444..........11111..',
+    '.4444...........11111.',
+    '.44444...........1111.',
+    '.444444..........1111.',
+    '..44444........2..111.',
+    '......4........22.111.',
+    '.3333.........222..11.',
+    '.33333333333.22222.11.',
+    '..333333333.2222222...',
+    '....333333.2222222....',
+    '.....3333.2222222.....',
+    '.........222222.......',
+    '.........2222.........',
+    '......................',
+];
+const LOGO_S = [
+    '..................',
+    '.......555........',
+    '.....55555..0.....',
+    '...555555.00000...',
+    '...55555.0000000..',
+    '.4.5555..00000000.',
+    '.44.55.......0000.',
+    '.44.55......1...0.',
+    '.444........1111..',
+    '.444.........1111.',
+    '.4444.........111.',
+    '.44444........111.',
+    '...444......22.11.',
+    '.33.........22.11.',
+    '.333333333.2222.1.',
+    '..3333333.22222...',
+    '...33333.222222...',
+    '.....33.22222.....',
+    '........222.......',
+    '..................',
+];
+// ---- Wordmark: pixel fonts ('#' = lit pixel). CAUSYNE is 6x7, AGENT is 5x5. The A has no crossbar, like the brand wordmark.
+const F7 = {
+    C: ['.####.', '#....#', '#.....', '#.....', '#.....', '#....#', '.####.'],
+    A: ['..##..', '.#..#.', '.#..#.', '#....#', '#....#', '#....#', '#....#'],
+    U: ['#....#', '#....#', '#....#', '#....#', '#....#', '#....#', '.####.'],
+    S: ['.#####', '#.....', '#.....', '.####.', '.....#', '.....#', '#####.'],
+    Y: ['#....#', '.#..#.', '..##..', '..##..', '..##..', '..##..', '..##..'],
+    N: ['#....#', '##...#', '#.#..#', '#..#.#', '#...##', '#....#', '#....#'],
+    E: ['######', '#.....', '#.....', '####..', '#.....', '#.....', '######'],
+};
+const F5 = {
+    A: ['..#..', '.#.#.', '.#.#.', '#...#', '#...#'],
+    G: ['.####', '#....', '#.###', '#...#', '.###.'],
+    E: ['#####', '#....', '###..', '#....', '#####'],
+    N: ['#...#', '##..#', '#.#.#', '#..##', '#...#'],
+    T: ['#####', '..#..', '..#..', '..#..', '..#..'],
+};
+// ---- Colour ---------------------------------------------------------------------------------------------
+const ESC = '\x1b[';
+const RESET = ESC + '0m';
+const PAL = { lime: [182, 224, 111], gray: [95, 102, 114], white: [244, 246, 248], dim: [140, 148, 160] };
+const C16 = { lime: 92, gray: 90, white: 97, dim: 90 };
+const STRONG = { lime: true, white: true, gray: false, dim: false };
+const LV = [0, 95, 135, 175, 215, 255];
+const FORCE = { '0': 'none', false: 'none', '1': '16', true: '16', '2': '256', '3': 'truecolor' };
+function to256(c) {
+    const [r, g, b] = c;
+    const near = (v) => LV.reduce((bi, x, i) => (Math.abs(x - v) < Math.abs((LV[bi] ?? 0) - v) ? i : bi), 0);
+    const ri = near(r), gi = near(g), bi = near(b), cube = 16 + 36 * ri + 6 * gi + bi;
+    const gl = Math.max(0, Math.min(23, Math.round(((r + g + b) / 3 - 8) / 10))), gv = 8 + 10 * gl;
+    const dc = (r - (LV[ri] ?? 0)) ** 2 + (g - (LV[gi] ?? 0)) ** 2 + (b - (LV[bi] ?? 0)) ** 2;
+    const dg = (r - gv) ** 2 + (g - gv) ** 2 + (b - gv) ** 2;
+    return dg < dc ? 232 + gl : cube;
+}
+function fgCode(k, d) {
+    const rgb = PAL[k];
+    return d === 'truecolor' ? `38;2;${rgb.join(';')}` : d === '256' ? `38;5;${to256(rgb)}` : String(C16[k]);
+}
+function bgCode(k, d) {
+    const rgb = PAL[k];
+    return d === 'truecolor' ? `48;2;${rgb.join(';')}` : d === '256' ? `48;5;${to256(rgb)}` : String(C16[k] + 10);
+}
+// ---- Capability detection -------------------------------------------------------------------------------
+function pickVariant(c) {
+    if (c.width < 44 || c.height < 14)
+        return 'mini';
+    if (c.width < 80 || c.height < 24 || !c.unicode)
+        return 'compact';
+    return 'full';
+}
+export function detect(o = {}, stream = process.stdout) {
+    const env = process.env, tty = Boolean(stream.isTTY);
+    const width = o.width || stream.columns || 80, height = o.height || stream.rows || 24;
+    const want = o.color;
+    let color;
+    if (want === true)
+        color = 'truecolor';
+    else if (want === false)
+        color = 'none';
+    else if (want !== undefined && want !== 'auto')
+        color = want;
+    else {
+        const f = env['FORCE_COLOR'];
+        if (f !== undefined && f !== '')
+            color = FORCE[f] ?? '16';
+        else if (env['NO_COLOR'] || env['CAUSYNE_NO_COLOR'] === '1')
+            color = 'none';
+        else if (!tty || env['TERM'] === 'dumb')
+            color = 'none';
+        else {
+            const d = stream.getColorDepth?.() ?? 4;
+            color = /truecolor|24bit/i.test(env['COLORTERM'] ?? '') || d >= 24 ? 'truecolor' : d >= 8 ? '256' : d >= 4 ? '16' : 'none';
+        }
+    }
+    let unicode = o.unicode;
+    if (unicode === undefined) {
+        const loc = env['LC_ALL'] || env['LC_CTYPE'] || env['LANG'] || '', ascii = env['CAUSYNE_ASCII'];
+        unicode = !(ascii && ascii !== '0') && !(process.platform !== 'win32' && loc !== '' && !/utf-?8/i.test(loc));
+    }
+    const caps = { tty, width, height, color, unicode, variant: 'full' };
+    caps.variant = o.variant && o.variant !== 'auto' ? o.variant : pickVariant(caps);
+    return caps;
+}
+// ---- Pixel canvas -> terminal cells ---------------------------------------------------------------------
+const blank = (w, h) => Array.from({ length: h }, () => Array(w).fill(null));
+function blit(dst, src, x, y) {
+    src.forEach((row, j) => row.forEach((k, i) => { const d = dst[y + j]; if (d && k)
+        d[x + i] = k; }));
+}
+const pixLogo = (g, active) => g.map((r) => [...r].map((ch) => (ch === '.' ? null : Number(ch) === active ? 'lime' : 'gray')));
+function pixText(str, font, h, gap, key) {
+    const rows = Array.from({ length: h }, () => []);
+    [...str].forEach((ch, i) => {
+        const glyph = font[ch];
+        if (!glyph)
+            return;
+        rows.forEach((row, y) => {
+            if (i)
+                for (let k = 0; k < gap; k++)
+                    row.push(null);
+            for (const c of glyph[y] ?? '')
+                row.push(c === '#' ? key : null);
+        });
+    });
+    return rows;
+}
+function cells(px, caps) {
+    const { color, unicode } = caps, lines = [];
+    for (let y = 0; y < px.length; y += 2) {
+        const top = px[y] ?? [], bot = px[y + 1] ?? [], w = Math.max(top.length, bot.length);
+        let s = '', fg = null, bg = null;
+        for (let x = 0; x < w; x++) {
+            const t = top[x] ?? null, b = bot[x] ?? null;
+            let ch = ' ', f = null, g = null;
+            if (t || b) {
+                if (unicode) {
+                    if (color === 'none')
+                        ch = t && b ? ((t && STRONG[t]) || (b && STRONG[b]) ? '█' : '▒') : t ? '▀' : '▄';
+                    else if (t === b) {
+                        ch = '█';
+                        f = t;
+                    }
+                    else if (!b) {
+                        ch = '▀';
+                        f = t;
+                    }
+                    else if (!t) {
+                        ch = '▄';
+                        f = b;
+                    }
+                    else {
+                        ch = '▀';
+                        f = t;
+                        g = b;
+                    }
+                }
+                else {
+                    const k = (t && STRONG[t] ? t : null) || (b && STRONG[b] ? b : null) || t || b, st = k ? STRONG[k] : false;
+                    ch = t && b ? (st ? '@' : '%') : t ? (st ? "'" : '"') : st ? '.' : ',';
+                    f = color === 'none' ? null : k;
+                }
+            }
+            if (color !== 'none') {
+                if (g !== bg) {
+                    s += ESC + (g ? bgCode(g, color) : '49') + 'm';
+                    bg = g;
+                }
+                if (f && f !== fg) {
+                    s += ESC + fgCode(f, color) + 'm';
+                    fg = f;
+                }
+            }
+            s += ch;
+        }
+        if (fg || bg)
+            s += RESET;
+        lines.push(s);
+    }
+    return lines;
+}
+function txt(str, key, caps, maxw, bold) {
+    if (maxw !== undefined && str.length > maxw)
+        str = str.slice(0, Math.max(0, maxw - 1)) + (caps.unicode ? '…' : '~');
+    if (caps.color === 'none')
+        return str;
+    return ESC + (bold ? '1;' : '') + fgCode(key, caps.color) + 'm' + str + RESET;
+}
+// ---- Status line ----------------------------------------------------------------------------------------
+function shortPath(p, maxw) {
+    const home = homedir();
+    if (home && (p === home || p.startsWith(home + '/') || p.startsWith(home + '\\')))
+        p = '~' + p.slice(home.length);
+    if (p.length <= maxw)
+        return p;
+    return (maxw > 4 ? '...' : '') + p.slice(p.length - Math.max(1, maxw - 3));
+}
+function statusLine(info, maxw, unicode) {
+    const sep = unicode ? '  ·  ' : '  |  ';
+    const parts = [info.version ? 'v' + String(info.version).replace(/^v/, '') : '', [info.provider, info.model].filter(Boolean).join('/'), info.mode ?? '', info.cwd ?? ''].filter(Boolean);
+    const fits = () => parts.join(sep).length <= maxw;
+    if (!fits() && info.cwd) {
+        const others = parts.slice(0, -1).join(sep).length + (parts.length > 1 ? sep.length : 0);
+        parts[parts.length - 1] = shortPath(info.cwd, Math.max(8, maxw - others));
+    }
+    while (!fits() && parts.length > 1)
+        parts.pop();
+    return parts.join(sep);
+}
+// ---- Layouts --------------------------------------------------------------------------------------------
+function layoutFull(caps, info, active) {
+    const R = LOGO_L.length / 2, logo = cells(pixLogo(LOGO_L, active), caps), gap = '   ';
+    const right = blank(48, R * 2);
+    blit(right, pixText('CAUSYNE', F7, 7, 1, 'white'), 0, 2); // rows 1-4
+    blit(right, pixText('AGENT', F5, 5, 2, 'lime'), 0, 12); // rows 6-8
+    // Keep the metadata inside the wordmark's 48-pixel measure. Letting a long
+    // workspace consume every spare terminal column made the mark look detached
+    // from its own status line and prevented the prompt from widening once a
+    // session began.
+    const maxw = Math.min(48, caps.width - 2 - (LOGO_L[0]?.length ?? 0) - gap.length);
+    return cells(right, caps).map((tail, r) => {
+        if (r === R - 2)
+            tail = txt(TAGLINE, 'dim', caps, maxw);
+        if (r === R - 1)
+            tail = txt(statusLine(info, maxw, caps.unicode), 'dim', caps, maxw);
+        return ' ' + (logo[r] ?? '') + gap + tail;
+    });
+}
+function layoutCompact(caps, info, active) {
+    const logo = cells(pixLogo(LOGO_S, active), caps), gap = '   ';
+    const maxw = Math.max(10, caps.width - 2 - (LOGO_S[0]?.length ?? 0) - gap.length), wide = maxw >= 24;
+    return logo.map((l, r) => {
+        let tail = '';
+        if (r === 3)
+            tail = txt(wide ? 'C A U S Y N E' : 'CAUSYNE', 'white', caps, undefined, true) + txt(wide ? '  A G E N T' : ' AGENT', 'lime', caps, undefined, true);
+        else if (r === 4)
+            tail = txt(TAGLINE, 'dim', caps, maxw);
+        else if (r === 6)
+            tail = txt(statusLine(info, maxw, caps.unicode), 'dim', caps, maxw);
+        return ' ' + l + (tail ? gap + tail : '');
+    });
+}
+function layoutMini(caps, info) {
+    const ver = info.version ? '  v' + String(info.version).replace(/^v/, '') : '';
+    let line = txt(caps.unicode ? '■' : '#', 'lime', caps) + ' ' + txt('CAUSYNE', 'white', caps, undefined, true) + txt(' AGENT', 'lime', caps, undefined, true);
+    if (ver && 'x CAUSYNE AGENT'.length + ver.length <= caps.width - 2)
+        line += txt(ver, 'dim', caps);
+    return [' ' + line];
+}
+// ---- Public API -----------------------------------------------------------------------------------------
+/** Returns the banner as a string (no trailing newline). */
+export function renderBanner(o = {}, stream = process.stdout) {
+    const caps = detect(o, stream), active = o.active ?? 0;
+    if (caps.variant === 'full' && !caps.unicode)
+        caps.variant = 'compact';
+    const lines = caps.variant === 'mini' ? layoutMini(caps, o) : caps.variant === 'compact' ? layoutCompact(caps, o, active) : layoutFull(caps, o, active);
+    return lines.join('\n');
 }
-
-/**
- * The session header: the wordmark and the session facts, SIDE BY SIDE.
- *
- * This used to be three stacked blocks — six rows of art, then a blank, then a
- * bordered panel of four label/value rows, then two separate hint lines. Nineteen
- * rows of chrome before the user could type a character, on a surface whose whole
- * job is to get out of the way.
- *
- * Neither reference does that. claude-code sets its art in the left column with
- * the version, model, plan and directory stacked beside it — three rows, one
- * block. opencode puts the logo alone and the facts in the prompt box. The
- * common property is that the identity and the facts are ONE object, not a
- * sequence of them.
- *
- * Falls back to stacking when the terminal cannot hold both columns, because a
- * header that wraps is worse than a header that is tall.
- */
-export function sessionBanner(info = {}, width = 80, { unicode = HAS_UNICODE } = {}) {
-  let art = brandArt(width, unicode);
-  let artWidth = Math.max(...art.map(visibleWidth));
-
-  const facts = [];
-  if (info.version) facts.push([bold(paint('accent', 'Causyne')), dim(info.version)]);
-  const model = info.model || 'no model configured';
-  facts.push([paint('ink', model), info.provider ? dim(providerLabel(info.provider)) : '']);
-  const mode = [info.autonomyMode ? `mode ${info.autonomyMode}` : '', info.tier ? `tier ${info.tier}` : '']
-    .filter(Boolean).join(`  ${GLYPHS.dot}  `);
-  if (mode) facts.push([dim(mode), '']);
-  if (info.workspace) facts.push([dim(shortenHome(info.workspace)), '']);
-
-  const GAP = 4;
-  // The spare column is the same one the stacked branch below already reserves
-  // (`width - 1`). Without it a full-width fact row lands in the terminal's
-  // deferred-wrap state: the cursor sits past the last column, and the next
-  // write decides whether that becomes a wrap. Measured on an 80-column pty,
-  // the workspace row came back at exactly 80 while every other row was 79.
-  let room = width - artWidth - GAP - 1;
-
-  // A coloured 80-column terminal can render the full block wordmark, but it
-  // leaves too little room for the session facts beside it. Stacking those
-  // facts made startup 16 rows tall and overflowed short terminals. Prefer the
-  // compact ASCII aperture in that case: identity and facts remain one object,
-  // and the first prompt still fits without scrolling the banner away.
-  if (room < 24 && unicode && width >= 64) {
-    art = brandArt(width, false);
-    artWidth = Math.max(...art.map(visibleWidth));
-    room = width - artWidth - GAP - 1;
-  }
-
-  // Not enough width for two columns: stack, rather than wrap either one.
-  if (room < 24) {
-    return art
-      .concat([''], facts.map(([left, right]) =>
-        truncate(right ? `${left}  ${right}` : left, width - 1, GLYPHS.ellipsis)));
-  }
-
-  const rows = [];
-  const height = Math.max(art.length, facts.length);
-  for (let index = 0; index < height; index++) {
-    const artLine = art[index] === undefined ? '' : art[index];
-    const fact = facts[index];
-    const left = padEnd(artLine, artWidth) + ' '.repeat(GAP);
-    if (!fact) { rows.push(artLine); continue; }
-    const [primary, secondary] = fact;
-    const text = secondary ? `${primary}  ${secondary}` : primary;
-    rows.push(left + truncate(text, room, GLYPHS.ellipsis));
-  }
-  return rows;
-}
-
 /**
- * Display the provider the way the user wrote it, normalised for casing only.
- *
- * Causyne is BYOK: the provider is whatever the user configured, and nothing here
- * may assume or default to one. A config saying `Gemini` and one saying `gemini`
- * are the same provider and must read the same.
+ * Preserve the TUI's established banner API while rendering the canonical
+ * aperture and wordmark above. The returned rows are ordinary terminal history;
+ * callers decide when to write them and never need to repaint the screen.
  */
+export function wordmark(width = 80, options = {}) {
+    return renderBanner({ ...options, width, height: options.height ?? 24 }, process.stdout).split('\n');
+}
+/** A single display spelling for configured providers. */
 export function providerLabel(provider) {
-  const raw = String(provider || '').trim();
-  if (!raw) return '';
-  const KNOWN = {
-    openai: 'OpenAI', anthropic: 'Anthropic', gemini: 'Gemini', ollama: 'Ollama',
-    deepseek: 'DeepSeek', dashscope: 'DashScope', 'dashscope-byok': 'DashScope',
-    qwen: 'Qwen', xai: 'xAI', grok: 'xAI', moonshot: 'Moonshot', kimi: 'Moonshot',
-    muse: 'Meta', meta: 'Meta',
-    'openai-compatible': 'OpenAI-compatible'
-  };
-  return KNOWN[raw.toLowerCase()] || raw;
-}
-
-// What to ask, for the person who has just opened this for the first time.
-//
-// `ask anything` is an invitation, not an example — it tells a new user nothing
-// about what this agent can actually be asked to do. Both references show a
-// concrete prompt instead (opencode seeds a random one per launch from
-// routes/home.tsx). One is picked per session so the hint does not churn while
-// the user is reading it.
+    const raw = String(provider ?? '').trim();
+    if (!raw)
+        return '';
+    const known = {
+        openai: 'OpenAI', anthropic: 'Anthropic', gemini: 'Gemini', ollama: 'Ollama',
+        deepseek: 'DeepSeek', dashscope: 'DashScope', 'dashscope-byok': 'DashScope',
+        qwen: 'Qwen', xai: 'xAI', grok: 'xAI', moonshot: 'Moonshot', kimi: 'Moonshot',
+        muse: 'Meta', meta: 'Meta', 'openai-compatible': 'OpenAI-compatible'
+    };
+    return known[raw.toLowerCase()] ?? raw;
+}
+function sessionInfo(info) {
+    const provider = providerLabel(info.provider);
+    const modeParts = [
+        info.autonomyMode ? `mode ${info.autonomyMode}` : info.mode,
+        info.tier ? `tier ${info.tier}` : undefined
+    ].filter((part) => Boolean(part));
+    return {
+        ...(info.version ? { version: info.version } : {}),
+        ...(provider ? { provider } : {}),
+        ...(info.model ? { model: info.model } : {}),
+        ...(modeParts.length ? { mode: modeParts.join(' / ') } : {}),
+        ...(info.workspace || info.cwd ? { cwd: info.workspace ?? info.cwd } : {})
+    };
+}
+/** Render the adaptive session identity block used by ChatRenderer. */
+export function sessionBanner(info = {}, width = 80, options = {}) {
+    const height = options.height ?? process.stdout.rows ?? 24;
+    // The chat surface also needs room for its input band and hint row. The
+    // standalone renderer keeps the source design's 80x24 full-banner threshold,
+    // while the integrated session header chooses the same artwork at a size that
+    // cannot push the first prompt off short terminals.
+    const variant = height < 22 || width < 44
+        ? 'mini'
+        : width < 96 || height < 28 || options.unicode === false
+            ? 'compact'
+            : 'full';
+    return renderBanner({
+        ...sessionInfo(info),
+        ...options,
+        variant,
+        width,
+        height
+    }, process.stdout).split('\n');
+}
+/** Prints the banner. Returns false (prints nothing) when stdout is not a TTY, unless `force` is set. */
+export function printBanner(o = {}, stream = process.stdout) {
+    if (!stream.isTTY && !o.force)
+        return false;
+    stream.write(renderBanner(o, stream) + '\n');
+    return true;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Optional standalone boot animation. The main chat TUI deliberately writes once to preserve scrollback. */
+export async function animateBanner(o = {}, stream = process.stdout) {
+    const caps = detect(o, stream), env = process.env;
+    if (!stream.isTTY || caps.color === 'none' || !caps.unicode || caps.variant === 'mini' || o.animate === false || env['CI'] || env['CAUSYNE_NO_ANIM'] || env['TERM'] === 'dumb')
+        return printBanner(o, stream);
+    const frames = [0, 1, 2, 3, 4, 5, 0].map((active) => renderBanner({ ...o, active }, stream).split('\n'));
+    const first = frames[0] ?? [], count = first.length, show = () => { stream.write('\x1b[?25h'); };
+    process.once('exit', show);
+    try {
+        stream.write('\x1b[?25l' + first.join('\n') + '\n');
+        for (const frame of frames.slice(1)) {
+            await sleep(o.frameMs ?? 70);
+            stream.write(`\x1b[${count}A` + frame.map((line) => line + '\x1b[K').join('\n') + '\n');
+        }
+    }
+    finally {
+        show();
+        process.removeListener('exit', show);
+    }
+    return true;
+}
 export const EXAMPLES = [
-  'summarise what changed in this repo today',
-  'find every TODO left in src/ and group them by file',
-  'explain what this project does and how it is wired',
-  'run the tests and tell me what broke',
-  'review my last commit for anything risky'
+    'summarise what changed in this repo today',
+    'find every TODO left in src/ and group them by file',
+    'explain what this project does and how it is wired',
+    'run the tests and tell me what broke',
+    'review my last commit for anything risky'
 ];
-
-/** One example, chosen per session rather than per keystroke. */
+/** One example, chosen once per session rather than once per keystroke. */
 export function pickExample() {
-  return EXAMPLES[Math.floor(Math.random() * EXAMPLES.length)];
+    return EXAMPLES[Math.floor(Math.random() * EXAMPLES.length)] ?? EXAMPLES[0];
 }
-
-/**
- * Join hint fragments, dropping the least important until the line fits.
- *
- * Same policy as the footer: a hint clipped mid-word reads as a bug, so drop
- * whole fragments rather than truncate one, and fall back entirely when even a
- * single fragment will not fit.
- */
+/** Drop complete hint fragments until the remaining line fits. */
 export function fitHints(parts, width, fallback) {
-  const separator = `  ${GLYPHS.dot}  `;
-  const kept = parts.slice();
-  while (kept.length > 1 && visibleWidth(kept.join(separator)) > width) kept.pop();
-  const line = kept.join(separator);
-  // A narrow terminal must not get `try "review my last commit for anything r`.
-  return visibleWidth(line) <= width ? line : fallback;
+    const separator = '  ·  ';
+    const kept = parts.slice();
+    while (kept.length > 1 && kept.join(separator).length > width)
+        kept.pop();
+    const line = kept.join(separator);
+    return line.length <= width ? line : fallback;
 }

package/src/tui/banner.ts

@@ -0,0 +1,407 @@
+/**
+ * Canonical Causyne Agent terminal identity: aperture, pixel wordmark, status,
+ * and adaptive fallbacks. TypeScript is the source; the repository build emits
+ * the readable ESM file imported by the CLI.
+ *
+ * Environment: NO_COLOR, CAUSYNE_NO_COLOR, FORCE_COLOR=1|2|3,
+ * CAUSYNE_ASCII=1 (7-bit only), and CAUSYNE_NO_ANIM=1.
+ */
+import { homedir } from 'node:os';
+
+export type ColorMode = 'truecolor' | '256' | '16' | 'none';
+export type Variant = 'full' | 'compact' | 'mini';
+
+export interface BannerInfo {
+  version?: string;
+  provider?: string;
+  model?: string;
+  mode?: string;
+  cwd?: string;
+  autonomyMode?: string;
+  tier?: string;
+  workspace?: string;
+}
+export interface BannerOptions extends BannerInfo {
+  /** 'auto' picks from the terminal size: full >= 80x24, compact >= 44 cols, otherwise mini. */
+  variant?: Variant | 'auto';
+  /** 'auto' honours NO_COLOR / FORCE_COLOR / TTY / COLORTERM. */
+  color?: ColorMode | 'auto' | boolean;
+  unicode?: boolean; width?: number; height?: number;
+  /** Which blade is lime (0-5, clockwise from top-right). Used by the boot animation. */
+  active?: number;
+  animate?: boolean; frameMs?: number;
+  /** Print even when stdout is not a TTY. */
+  force?: boolean;
+}
+export interface TermStream { isTTY?: boolean; columns?: number; rows?: number; getColorDepth?: () => number; write(chunk: string): unknown }
+export interface Caps { tty: boolean; width: number; height: number; color: ColorMode; unicode: boolean; variant: Variant }
+
+type Key = 'lime' | 'gray' | 'white' | 'dim';
+type Px = Key | null;
+type Canvas = Px[][];
+type Font = Record<string, readonly string[]>;
+type RGB = readonly [number, number, number];
+
+export const TAGLINE = 'From intention to meaningful progress.';
+
+// ---- Logo -----------------------------------------------------------------------------------------------
+// One character = one "pixel". A terminal cell holds two stacked pixels (drawn with the half blocks ▀ ▄ █).
+// '.' is empty, 0-5 is the blade id. Blade 0 is the lime one (top-right); ids run clockwise.
+const LOGO_L: readonly string[] = [
+  '......................',
+  '.........5555.........',
+  '.......555555.........',
+  '.....5555555.0000.....',
+  '....5555555.0000000...',
+  '...5555555.000000000..',
+  '....55555.00000000000.',
+  '.44.5555.......000000.',
+  '.444.55...........000.',
+  '.444..5........111..0.',
+  '.4444..........11111..',
+  '.4444...........11111.',
+  '.44444...........1111.',
+  '.444444..........1111.',
+  '..44444........2..111.',
+  '......4........22.111.',
+  '.3333.........222..11.',
+  '.33333333333.22222.11.',
+  '..333333333.2222222...',
+  '....333333.2222222....',
+  '.....3333.2222222.....',
+  '.........222222.......',
+  '.........2222.........',
+  '......................',
+];
+const LOGO_S: readonly string[] = [
+  '..................',
+  '.......555........',
+  '.....55555..0.....',
+  '...555555.00000...',
+  '...55555.0000000..',
+  '.4.5555..00000000.',
+  '.44.55.......0000.',
+  '.44.55......1...0.',
+  '.444........1111..',
+  '.444.........1111.',
+  '.4444.........111.',
+  '.44444........111.',
+  '...444......22.11.',
+  '.33.........22.11.',
+  '.333333333.2222.1.',
+  '..3333333.22222...',
+  '...33333.222222...',
+  '.....33.22222.....',
+  '........222.......',
+  '..................',
+];
+
+// ---- Wordmark: pixel fonts ('#' = lit pixel). CAUSYNE is 6x7, AGENT is 5x5. The A has no crossbar, like the brand wordmark.
+const F7: Font = {
+  C: ['.####.', '#....#', '#.....', '#.....', '#.....', '#....#', '.####.'],
+  A: ['..##..', '.#..#.', '.#..#.', '#....#', '#....#', '#....#', '#....#'],
+  U: ['#....#', '#....#', '#....#', '#....#', '#....#', '#....#', '.####.'],
+  S: ['.#####', '#.....', '#.....', '.####.', '.....#', '.....#', '#####.'],
+  Y: ['#....#', '.#..#.', '..##..', '..##..', '..##..', '..##..', '..##..'],
+  N: ['#....#', '##...#', '#.#..#', '#..#.#', '#...##', '#....#', '#....#'],
+  E: ['######', '#.....', '#.....', '####..', '#.....', '#.....', '######'],
+};
+const F5: Font = {
+  A: ['..#..', '.#.#.', '.#.#.', '#...#', '#...#'],
+  G: ['.####', '#....', '#.###', '#...#', '.###.'],
+  E: ['#####', '#....', '###..', '#....', '#####'],
+  N: ['#...#', '##..#', '#.#.#', '#..##', '#...#'],
+  T: ['#####', '..#..', '..#..', '..#..', '..#..'],
+};
+
+// ---- Colour ---------------------------------------------------------------------------------------------
+const ESC = '\x1b[';
+const RESET = ESC + '0m';
+const PAL: Record<Key, RGB> = { lime: [182, 224, 111], gray: [95, 102, 114], white: [244, 246, 248], dim: [140, 148, 160] };
+const C16: Record<Key, number> = { lime: 92, gray: 90, white: 97, dim: 90 };
+const STRONG: Record<Key, boolean> = { lime: true, white: true, gray: false, dim: false };
+const LV = [0, 95, 135, 175, 215, 255] as const;
+const FORCE: Record<string, ColorMode> = { '0': 'none', false: 'none', '1': '16', true: '16', '2': '256', '3': 'truecolor' };
+
+function to256(c: RGB): number {
+  const [r, g, b] = c;
+  const near = (v: number): number => LV.reduce<number>((bi, x, i) => (Math.abs(x - v) < Math.abs((LV[bi] ?? 0) - v) ? i : bi), 0);
+  const ri = near(r), gi = near(g), bi = near(b), cube = 16 + 36 * ri + 6 * gi + bi;
+  const gl = Math.max(0, Math.min(23, Math.round(((r + g + b) / 3 - 8) / 10))), gv = 8 + 10 * gl;
+  const dc = (r - (LV[ri] ?? 0)) ** 2 + (g - (LV[gi] ?? 0)) ** 2 + (b - (LV[bi] ?? 0)) ** 2;
+  const dg = (r - gv) ** 2 + (g - gv) ** 2 + (b - gv) ** 2;
+  return dg < dc ? 232 + gl : cube;
+}
+function fgCode(k: Key, d: ColorMode): string {
+  const rgb = PAL[k];
+  return d === 'truecolor' ? `38;2;${rgb.join(';')}` : d === '256' ? `38;5;${to256(rgb)}` : String(C16[k]);
+}
+function bgCode(k: Key, d: ColorMode): string {
+  const rgb = PAL[k];
+  return d === 'truecolor' ? `48;2;${rgb.join(';')}` : d === '256' ? `48;5;${to256(rgb)}` : String(C16[k] + 10);
+}
+
+// ---- Capability detection -------------------------------------------------------------------------------
+function pickVariant(c: Pick<Caps, 'width' | 'height' | 'unicode'>): Variant {
+  if (c.width < 44 || c.height < 14) return 'mini';
+  if (c.width < 80 || c.height < 24 || !c.unicode) return 'compact';
+  return 'full';
+}
+export function detect(o: BannerOptions = {}, stream: TermStream = process.stdout): Caps {
+  const env = process.env, tty = Boolean(stream.isTTY);
+  const width = o.width || stream.columns || 80, height = o.height || stream.rows || 24;
+  const want = o.color;
+  let color: ColorMode;
+  if (want === true) color = 'truecolor';
+  else if (want === false) color = 'none';
+  else if (want !== undefined && want !== 'auto') color = want;
+  else {
+    const f = env['FORCE_COLOR'];
+    if (f !== undefined && f !== '') color = FORCE[f] ?? '16';
+    else if (env['NO_COLOR'] || env['CAUSYNE_NO_COLOR'] === '1') color = 'none';
+    else if (!tty || env['TERM'] === 'dumb') color = 'none';
+    else {
+      const d = stream.getColorDepth?.() ?? 4;
+      color = /truecolor|24bit/i.test(env['COLORTERM'] ?? '') || d >= 24 ? 'truecolor' : d >= 8 ? '256' : d >= 4 ? '16' : 'none';
+    }
+  }
+  let unicode = o.unicode;
+  if (unicode === undefined) {
+    const loc = env['LC_ALL'] || env['LC_CTYPE'] || env['LANG'] || '', ascii = env['CAUSYNE_ASCII'];
+    unicode = !(ascii && ascii !== '0') && !(process.platform !== 'win32' && loc !== '' && !/utf-?8/i.test(loc));
+  }
+  const caps: Caps = { tty, width, height, color, unicode, variant: 'full' };
+  caps.variant = o.variant && o.variant !== 'auto' ? o.variant : pickVariant(caps);
+  return caps;
+}
+
+// ---- Pixel canvas -> terminal cells ---------------------------------------------------------------------
+const blank = (w: number, h: number): Canvas => Array.from({ length: h }, () => Array<Px>(w).fill(null));
+function blit(dst: Canvas, src: Canvas, x: number, y: number): void {
+  src.forEach((row, j) => row.forEach((k, i) => { const d = dst[y + j]; if (d && k) d[x + i] = k; }));
+}
+const pixLogo = (g: readonly string[], active: number): Canvas => g.map((r) => [...r].map((ch): Px => (ch === '.' ? null : Number(ch) === active ? 'lime' : 'gray')));
+function pixText(str: string, font: Font, h: number, gap: number, key: Key): Canvas {
+  const rows: Canvas = Array.from({ length: h }, () => []);
+  [...str].forEach((ch, i) => {
+    const glyph = font[ch];
+    if (!glyph) return;
+    rows.forEach((row, y) => {
+      if (i) for (let k = 0; k < gap; k++) row.push(null);
+      for (const c of glyph[y] ?? '') row.push(c === '#' ? key : null);
+    });
+  });
+  return rows;
+}
+function cells(px: Canvas, caps: Caps): string[] {
+  const { color, unicode } = caps, lines: string[] = [];
+  for (let y = 0; y < px.length; y += 2) {
+    const top = px[y] ?? [], bot = px[y + 1] ?? [], w = Math.max(top.length, bot.length);
+    let s = '', fg: Key | null = null, bg: Key | null = null;
+    for (let x = 0; x < w; x++) {
+      const t = top[x] ?? null, b = bot[x] ?? null;
+      let ch = ' ', f: Key | null = null, g: Key | null = null;
+      if (t || b) {
+        if (unicode) {
+          if (color === 'none') ch = t && b ? ((t && STRONG[t]) || (b && STRONG[b]) ? '█' : '▒') : t ? '▀' : '▄';
+          else if (t === b) { ch = '█'; f = t; }
+          else if (!b) { ch = '▀'; f = t; }
+          else if (!t) { ch = '▄'; f = b; }
+          else { ch = '▀'; f = t; g = b; }
+        } else {
+          const k: Key | null = (t && STRONG[t] ? t : null) || (b && STRONG[b] ? b : null) || t || b, st = k ? STRONG[k] : false;
+          ch = t && b ? (st ? '@' : '%') : t ? (st ? "'" : '"') : st ? '.' : ',';
+          f = color === 'none' ? null : k;
+        }
+      }
+      if (color !== 'none') {
+        if (g !== bg) { s += ESC + (g ? bgCode(g, color) : '49') + 'm'; bg = g; }
+        if (f && f !== fg) { s += ESC + fgCode(f, color) + 'm'; fg = f; }
+      }
+      s += ch;
+    }
+    if (fg || bg) s += RESET;
+    lines.push(s);
+  }
+  return lines;
+}
+function txt(str: string, key: Key, caps: Caps, maxw?: number, bold?: boolean): string {
+  if (maxw !== undefined && str.length > maxw) str = str.slice(0, Math.max(0, maxw - 1)) + (caps.unicode ? '…' : '~');
+  if (caps.color === 'none') return str;
+  return ESC + (bold ? '1;' : '') + fgCode(key, caps.color) + 'm' + str + RESET;
+}
+
+// ---- Status line ----------------------------------------------------------------------------------------
+function shortPath(p: string, maxw: number): string {
+  const home = homedir();
+  if (home && (p === home || p.startsWith(home + '/') || p.startsWith(home + '\\'))) p = '~' + p.slice(home.length);
+  if (p.length <= maxw) return p;
+  return (maxw > 4 ? '...' : '') + p.slice(p.length - Math.max(1, maxw - 3));
+}
+function statusLine(info: BannerInfo, maxw: number, unicode: boolean): string {
+  const sep = unicode ? '  ·  ' : '  |  ';
+  const parts = [info.version ? 'v' + String(info.version).replace(/^v/, '') : '', [info.provider, info.model].filter(Boolean).join('/'), info.mode ?? '', info.cwd ?? ''].filter(Boolean);
+  const fits = (): boolean => parts.join(sep).length <= maxw;
+  if (!fits() && info.cwd) {
+    const others = parts.slice(0, -1).join(sep).length + (parts.length > 1 ? sep.length : 0);
+    parts[parts.length - 1] = shortPath(info.cwd, Math.max(8, maxw - others));
+  }
+  while (!fits() && parts.length > 1) parts.pop();
+  return parts.join(sep);
+}
+
+// ---- Layouts --------------------------------------------------------------------------------------------
+function layoutFull(caps: Caps, info: BannerInfo, active: number): string[] {
+  const R = LOGO_L.length / 2, logo = cells(pixLogo(LOGO_L, active), caps), gap = '   ';
+  const right = blank(48, R * 2);
+  blit(right, pixText('CAUSYNE', F7, 7, 1, 'white'), 0, 2); // rows 1-4
+  blit(right, pixText('AGENT', F5, 5, 2, 'lime'), 0, 12); // rows 6-8
+  // Keep the metadata inside the wordmark's 48-pixel measure. Letting a long
+  // workspace consume every spare terminal column made the mark look detached
+  // from its own status line and prevented the prompt from widening once a
+  // session began.
+  const maxw = Math.min(48, caps.width - 2 - (LOGO_L[0]?.length ?? 0) - gap.length);
+  return cells(right, caps).map((tail, r) => {
+    if (r === R - 2) tail = txt(TAGLINE, 'dim', caps, maxw);
+    if (r === R - 1) tail = txt(statusLine(info, maxw, caps.unicode), 'dim', caps, maxw);
+    return ' ' + (logo[r] ?? '') + gap + tail;
+  });
+}
+function layoutCompact(caps: Caps, info: BannerInfo, active: number): string[] {
+  const logo = cells(pixLogo(LOGO_S, active), caps), gap = '   ';
+  const maxw = Math.max(10, caps.width - 2 - (LOGO_S[0]?.length ?? 0) - gap.length), wide = maxw >= 24;
+  return logo.map((l, r) => {
+    let tail = '';
+    if (r === 3) tail = txt(wide ? 'C A U S Y N E' : 'CAUSYNE', 'white', caps, undefined, true) + txt(wide ? '  A G E N T' : ' AGENT', 'lime', caps, undefined, true);
+    else if (r === 4) tail = txt(TAGLINE, 'dim', caps, maxw);
+    else if (r === 6) tail = txt(statusLine(info, maxw, caps.unicode), 'dim', caps, maxw);
+    return ' ' + l + (tail ? gap + tail : '');
+  });
+}
+function layoutMini(caps: Caps, info: BannerInfo): string[] {
+  const ver = info.version ? '  v' + String(info.version).replace(/^v/, '') : '';
+  let line = txt(caps.unicode ? '■' : '#', 'lime', caps) + ' ' + txt('CAUSYNE', 'white', caps, undefined, true) + txt(' AGENT', 'lime', caps, undefined, true);
+  if (ver && 'x CAUSYNE AGENT'.length + ver.length <= caps.width - 2) line += txt(ver, 'dim', caps);
+  return [' ' + line];
+}
+
+// ---- Public API -----------------------------------------------------------------------------------------
+/** Returns the banner as a string (no trailing newline). */
+export function renderBanner(o: BannerOptions = {}, stream: TermStream = process.stdout): string {
+  const caps = detect(o, stream), active = o.active ?? 0;
+  if (caps.variant === 'full' && !caps.unicode) caps.variant = 'compact';
+  const lines = caps.variant === 'mini' ? layoutMini(caps, o) : caps.variant === 'compact' ? layoutCompact(caps, o, active) : layoutFull(caps, o, active);
+  return lines.join('\n');
+}
+
+/**
+ * Preserve the TUI's established banner API while rendering the canonical
+ * aperture and wordmark above. The returned rows are ordinary terminal history;
+ * callers decide when to write them and never need to repaint the screen.
+ */
+export function wordmark(width = 80, options: Pick<BannerOptions, 'unicode' | 'color' | 'height'> = {}): string[] {
+  return renderBanner({ ...options, width, height: options.height ?? 24 }, process.stdout).split('\n');
+}
+
+/** A single display spelling for configured providers. */
+export function providerLabel(provider: unknown): string {
+  const raw = String(provider ?? '').trim();
+  if (!raw) return '';
+  const known: Record<string, string> = {
+    openai: 'OpenAI', anthropic: 'Anthropic', gemini: 'Gemini', ollama: 'Ollama',
+    deepseek: 'DeepSeek', dashscope: 'DashScope', 'dashscope-byok': 'DashScope',
+    qwen: 'Qwen', xai: 'xAI', grok: 'xAI', moonshot: 'Moonshot', kimi: 'Moonshot',
+    muse: 'Meta', meta: 'Meta', 'openai-compatible': 'OpenAI-compatible'
+  };
+  return known[raw.toLowerCase()] ?? raw;
+}
+
+function sessionInfo(info: BannerInfo): BannerInfo {
+  const provider = providerLabel(info.provider);
+  const modeParts = [
+    info.autonomyMode ? `mode ${info.autonomyMode}` : info.mode,
+    info.tier ? `tier ${info.tier}` : undefined
+  ].filter((part): part is string => Boolean(part));
+  return {
+    ...(info.version ? { version: info.version } : {}),
+    ...(provider ? { provider } : {}),
+    ...(info.model ? { model: info.model } : {}),
+    ...(modeParts.length ? { mode: modeParts.join(' / ') } : {}),
+    ...(info.workspace || info.cwd ? { cwd: info.workspace ?? info.cwd } : {})
+  };
+}
+
+/** Render the adaptive session identity block used by ChatRenderer. */
+export function sessionBanner(
+  info: BannerInfo = {},
+  width = 80,
+  options: Pick<BannerOptions, 'unicode' | 'color' | 'height'> = {}
+): string[] {
+  const height = options.height ?? process.stdout.rows ?? 24;
+  // The chat surface also needs room for its input band and hint row. The
+  // standalone renderer keeps the source design's 80x24 full-banner threshold,
+  // while the integrated session header chooses the same artwork at a size that
+  // cannot push the first prompt off short terminals.
+  const variant: Variant = height < 22 || width < 44
+    ? 'mini'
+    : width < 96 || height < 28 || options.unicode === false
+      ? 'compact'
+      : 'full';
+  return renderBanner({
+    ...sessionInfo(info),
+    ...options,
+    variant,
+    width,
+    height
+  }, process.stdout).split('\n');
+}
+
+/** Prints the banner. Returns false (prints nothing) when stdout is not a TTY, unless `force` is set. */
+export function printBanner(o: BannerOptions = {}, stream: TermStream = process.stdout): boolean {
+  if (!stream.isTTY && !o.force) return false;
+  stream.write(renderBanner(o, stream) + '\n');
+  return true;
+}
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Optional standalone boot animation. The main chat TUI deliberately writes once to preserve scrollback. */
+export async function animateBanner(o: BannerOptions = {}, stream: TermStream = process.stdout): Promise<boolean> {
+  const caps = detect(o, stream), env = process.env;
+  if (!stream.isTTY || caps.color === 'none' || !caps.unicode || caps.variant === 'mini' || o.animate === false || env['CI'] || env['CAUSYNE_NO_ANIM'] || env['TERM'] === 'dumb') return printBanner(o, stream);
+  const frames = [0, 1, 2, 3, 4, 5, 0].map((active) => renderBanner({ ...o, active }, stream).split('\n'));
+  const first = frames[0] ?? [], count = first.length, show = (): void => { stream.write('\x1b[?25h'); };
+  process.once('exit', show);
+  try {
+    stream.write('\x1b[?25l' + first.join('\n') + '\n');
+    for (const frame of frames.slice(1)) {
+      await sleep(o.frameMs ?? 70);
+      stream.write(`\x1b[${count}A` + frame.map((line) => line + '\x1b[K').join('\n') + '\n');
+    }
+  } finally {
+    show();
+    process.removeListener('exit', show);
+  }
+  return true;
+}
+
+export const EXAMPLES = [
+  'summarise what changed in this repo today',
+  'find every TODO left in src/ and group them by file',
+  'explain what this project does and how it is wired',
+  'run the tests and tell me what broke',
+  'review my last commit for anything risky'
+] as const;
+
+/** One example, chosen once per session rather than once per keystroke. */
+export function pickExample(): string {
+  return EXAMPLES[Math.floor(Math.random() * EXAMPLES.length)] ?? EXAMPLES[0];
+}
+
+/** Drop complete hint fragments until the remaining line fits. */
+export function fitHints(parts: string[], width: number, fallback: string): string {
+  const separator = '  ·  ';
+  const kept = parts.slice();
+  while (kept.length > 1 && kept.join(separator).length > width) kept.pop();
+  const line = kept.join(separator);
+  return line.length <= width ? line : fallback;
+}

package/src/tui/chatRenderer.js

@@ -384,7 +384,7 @@ export class ChatRenderer {
     // nineteen rows of chrome before the user could type. Both references open
     // in eight or fewer, with the identity and the facts as a single object.
     this.write();
-    for (const row of sessionBanner(info, width)) this.write(row);
+    for (const row of sessionBanner(info, width, { height: this.out?.rows })) this.write(row);
     this.write();
 
     const hints = [