acuvo-code 0.6.3 → 0.6.4

package/ENTERPRISE.md

@@ -188,7 +188,7 @@ copy, but it *is* a place a process starts, and this is a list of those. Six and
 are the numbers to quote. Counting is the first thing a reviewer does.
 
 ⚠️ **This said "18 shipped files", then "41", then "90", then "101", then "108", and every
-one went stale in turn.** The package ships **120 files — 118 in `lib/`, 2 in
+one went stale in turn.** The package ships **121 files — 119 in `lib/`, 2 in
 `bin/` — about 78511 lines**, with **238 test files** beside them (counted 2026-08-22).
 
 ⭐ **AND THE 108 WENT STALE IN THE MOST INSTRUCTIVE WAY POSSIBLE: THREE OF THE FILES IT
@@ -892,7 +892,7 @@ For completeness, the properties none of them offers:
   (`lib/media.mjs`), and generates imagery with no configuration and no account
   (`lib/imagegen.mjs`) — critiqued before it is accepted, and reported as unreviewed when
   no critic is available.
-- ⭐ **Zero dependencies.** The entire auditable surface is 120 files and 78511 lines,
+- ⭐ **Zero dependencies.** The entire auditable surface is 121 files and 79376 lines,
   and there is no `node_modules` behind it. (Counted 2026-08-22 from
   `lib/*.mjs` + `bin/*.mjs`; `test/docs-truth.test.mjs` fails the build if this number
   drifts, which is why it went 18 → 41 → 46 → 52 → 53 → 57 → 60 → 61 → 62 → 65 → 66 → 69 → 70 → 71 → 72 → 73 → 80 → 84 → 90 → 100 → 101 → 102 → 103 → 107 → 108 → 111 as modules landed (111 = the three that were WRITTEN and imported by nothing — `python.mjs`, `cache-floor.mjs`, `plan-coherence.mjs`; 108 = `warm-provider.mjs`, which keeps a session on the upstream that holds its prompt cache; 107 = `login.mjs`, the command that stores an Acuvo credential — until it existed, `writeAccount` was called by nothing and every user fell through to BYOK). ⚠️ Two of those three landed on this count while remaining UNREACHABLE, which is the sharpest illustration this document has that a file count is a claim about bytes, never about capability. ⭐ A

package/bin/acuvo.mjs

@@ -1489,6 +1489,28 @@ ${formatBoard(listed)}
    * chat loop owns the invitation, and neither should own both.
    */
   const { openingScreen } = await import('../lib/banner.mjs');
+  /**
+   * ── ⭐⭐⭐ ASK THE TERMINAL, DO NOT ASSUME IT ────────────────────────────────
+   *
+   * The half-block mark is only correct if this terminal renders ▀ ▄ █ at ONE
+   * cell. They are East-Asian-Ambiguous, so that is a property of the font and
+   * the emulator, not of the character — and where they come out double-width
+   * the mark TEARS: the padding spaces stay narrow while the blocks do not, so
+   * every row shifts by a different amount and the right-hand column is pushed
+   * off the screen.
+   *
+   * ⚠️ THIS IS THE FOURTH ATTEMPT AT THIS SCREEN AND THE FIRST THAT MEASURES.
+   * The previous three reasoned from byte sequences that were correct on my
+   * machine and wrong on Roman's, which is the only machine that counts.
+   * `measureCellWidth` prints the glyph and asks the terminal where the cursor
+   * landed — not an inference about fonts, the terminal describing itself.
+   * Unknown falls back to the ASCII mark: a plainer logo on a capable terminal
+   * costs a little beauty, torn blocks on an incapable one cost a first
+   * impression.
+   */
+  const { measureCellWidth, bannerStyle } = await import('../lib/glyph-width.mjs');
+  const cellWidth = await measureCellWidth({ input: process.stdin, output: process.stdout });
+  const bannerLook = bannerStyle({ cellWidth, env: process.env });
   /**
    * ── ⭐⭐ THE BRAND NAME, NOT THE VENDOR'S ────────────────────────────────────
    *
@@ -1518,6 +1540,14 @@ ${formatBoard(listed)}
      * site.
      */
     paint: createPainter(colourEnabled()),
+    style: bannerLook,
+    /**
+     * ⚠️ THE REAL WIDTH, NOT A CONSTANT. The banner used to build to a fixed
+     * 80 columns and never ask, so in any narrower terminal — a split pane, a
+     * side panel — every row wrapped. `columns` is undefined off a TTY, which
+     * the banner reads as "assume 80": right for a pipe, wrong for nothing.
+     */
+    columns: process.stdout.columns ?? null,
   });
   if (opts.json) process.stderr.write(banner);
   else process.stdout.write(banner);

package/lib/banner.mjs

@@ -1,155 +1,255 @@
-/**
- * ── ⭐⭐⭐ WHAT YOU SEE WHEN YOU TYPE `acuvo` ────────────────────────────────
- *
- * Roman, 2026-08-22, having typed it: *"it's not opening as a typable terminal,
- * with acuvo logo top left and details up top etc, like how claude code opens.
- * have you actually designed the page?"* — and then: *"no we want OUR logo"*.
- *
- * So this is the real mark, not letters spelling the name. It is
- * `console/public/brand/acuvo-mark.png` — the angular A — resampled to
- * half-blocks at 14x14 and embedded as text.
- *
- * ── ⚠️ WHY IT IS EMBEDDED RATHER THAN DECODED AT RUNTIME ────────────────────
- *
- * This package has ZERO dependencies, deliberately, and Node cannot decode a
- * PNG without one. Converting at build time and pasting the result keeps that
- * promise and costs nothing at startup. If the mark ever changes, re-run the
- * conversion — the logo is DERIVED from the brand asset, not drawn by hand, so
- * it stays honest to it.
- *
- * ── ⚠️ THE CONSTRAINTS, WHICH ARE NOT PREFERENCES ───────────────────────────
- *
- * · **Half-block glyphs only** (▀ ▄ █). Braille and box-drawing render as tofu
- *   in cmd.exe and in many CI log viewers, and a logo that renders as question
- *   marks is worse than no logo — on the exact platform this is developed on.
- * · **No colour escapes here.** The caller owns colour and honours NO_COLOR; a
- *   module that hard-codes them emits garbage the moment output is piped.
- * · **Every line under 80 columns.** The narrowest terminal in real use is 80,
- *   and a wrapped banner does not read as dense, it reads as broken.
- *
- * ⭐ A NOTE ON DOING BETTER: `lib/terminal-graphics.mjs` can send a real PNG
- * inline on Kitty and iTerm2. It is deliberately NOT used here — Windows
- * Terminal speaks neither protocol, so the block art is what most users would
- * see anyway, and one rendering that is the same everywhere beats two that
- * disagree.
- */
-
-/**
- * The Acuvo mark, resampled from the brand PNG. Seven rows: tall enough to be
- * the mark rather than a smudge, short enough for something run forty times a
- * day rather than opened once.
- */
-const MARK = [
-  '      ▄█',
-  '     ▄███',
-  '    ▄█▀▀██',
-  '   ▄█▀  ▀██',
-  '  ▄█▀ ██ ▀██',
-  ' ▄████▀▀█████',
-  '█▀      █▀  ▀█',
-];
-
-const MARK_WIDTH = Math.max(...MARK.map((l) => l.length));
-const GUTTER = 2;
-export const MAX_BANNER_COLUMNS = 80;
-
-/** Columns left for the detail rows once the mark and gutter are placed. */
-const TEXT_COLUMNS = MAX_BANNER_COLUMNS - MARK_WIDTH - GUTTER;
-
-/**
- * Build the opening screen: mark on the left, facts on the right.
- *
- * @param {object} o
- * @param {string} o.version
- * @param {string} o.workspace   already shortened by the caller
- * @param {string} o.model
- * @param {string} o.billing     who this run will charge
- * @param {string} o.canRun      what it may execute, or that it may not
- * @param {boolean} [o.interactive] whether a prompt follows
- * @returns {string}
- */
-export function openingScreen({ version, workspace, model, billing, canRun, interactive = false, paint = null }) {
-  /**
-   * ── ⭐ THE MARK IS BRAND GREEN, AND ONLY THE MARK ────────────────────────────
-   *
-   * Roman: *"can you colour our logo green in the terminal?"* #C8E91E, sampled
-   * from the brand PNG rather than picked by eye.
-   *
-   * ⚠️ THE PAINTER IS INJECTED, NOT IMPORTED. The caller already decided whether
-   * this stream can take colour — it owns NO_COLOR, FORCE_COLOR, TERM=dumb and
-   * TTY detection. A module that reaches for colour itself will eventually
-   * disagree with that decision and write escapes into somebody's redirected
-   * file.
-   *
-   * ⚠️ AND ONLY THE LOGO. Colouring the detail rows would make the one line that
-   * must be read as a warning — `billing: YOUR OWN OpenRouter key` — compete
-   * with decoration.
-   */
-  const brand = paint?.brand ?? ((s) => s);
-  /**
-   * ── ⚠️⚠️ ELIDED, BECAUSE THE VALUES ARE NOT OURS ────────────────────────────
-   *
-   * Every value arrives at runtime: a deep monorepo path, a long model id, the
-   * shell-mode warning. The first version assumed they would be short and its
-   * own test caught it wrapping at 80 columns on ordinary inputs.
-   *
-   * ⭐ ELIDED IN THE MIDDLE, NOT THE END. The informative parts of a path are
-   * the drive and the leaf; chopping the tail leaves
-   * `C:\Users\somebody\Projects\a-`, which identifies nothing. Same for a model
-   * id, where the family is at the front and the variant at the back.
-   */
-  const room = TEXT_COLUMNS - 11;
-  const fit = (v) => {
-    const s = String(v ?? '');
-    if (s.length <= room) return s;
-    const head = Math.ceil((room - 1) / 2);
-    return `${s.slice(0, head)}…${s.slice(s.length - (room - 1 - head))}`;
-  };
-
-  const right = [
-    `ACUVO CODE${version ? `  ${version}` : ''}`,
-    '',
-    `workspace  ${fit(workspace)}`,
-    `model      ${fit(model)}`,
-    `billing    ${fit(billing)}`,
-    `can run    ${fit(canRun)}`,
-    '',
-  ];
-
-  /**
-   * ⚠️ THE TWO COLUMNS ARE ZIPPED, NOT CONCATENATED, and the row counts are
-   * allowed to differ — whichever is shorter simply runs out. Assuming they
-   * match would break the layout the first time a row is added to either side.
-   */
-  const rows = Math.max(MARK.length, right.length);
-  const lines = [''];
-  for (let i = 0; i < rows; i += 1) {
-    const text = right[i] ?? '';
-    /**
-     * ⚠️ PADDED FIRST, PAINTED SECOND — escape codes have no width, so padding a
-     * coloured string aligns the text against invisible bytes and the whole
-     * right-hand column drifts.
-     *
-     * ⚠️⚠️ AND PADDED ONLY WHEN SOMETHING FOLLOWS. On a mark-only row the
-     * padding sits INSIDE the colour, before the reset, where the `trimEnd`
-     * below cannot reach it — so the coloured banner carried trailing
-     * whitespace the plain one did not. Invisible, but it means colour changed
-     * the layout, which is exactly what the guard forbids.
-     */
-    const rawMark = MARK[i] ?? '';
-    const padded = text ? rawMark.padEnd(MARK_WIDTH + GUTTER) : rawMark;
-    const mark = MARK[i] ? brand(padded) : padded;
-    lines.push(`${mark}${text}`.trimEnd());
-  }
-  lines.push('');
-
-  /**
-   * ⚠️ ONLY WHEN A PROMPT ACTUALLY FOLLOWS. Printing "type what you want done"
-   * above a one-shot run that has already been given its task is an instruction
-   * for something the user cannot do, on the screen of a thing already working.
-   */
-  if (interactive) {
-    lines.push('  Type what you want done.   /help for commands  ·  exit to leave', '');
-  }
-  return lines.join('\n');
-}
+/**
+ * ── ⭐⭐⭐ WHAT YOU SEE WHEN YOU TYPE `acuvo` ────────────────────────────────
+ *
+ * Roman, 2026-08-22, having typed it: *"it's not opening as a typable terminal,
+ * with acuvo logo top left and details up top etc, like how claude code opens.
+ * have you actually designed the page?"* — and then: *"no we want OUR logo"*.
+ *
+ * So this is the real mark, not letters spelling the name. It is
+ * `console/public/brand/acuvo-mark.png` — the angular A — resampled to
+ * half-blocks at 14x14 and embedded as text.
+ *
+ * ── ⚠️ WHY IT IS EMBEDDED RATHER THAN DECODED AT RUNTIME ────────────────────
+ *
+ * This package has ZERO dependencies, deliberately, and Node cannot decode a
+ * PNG without one. Converting at build time and pasting the result keeps that
+ * promise and costs nothing at startup. If the mark ever changes, re-run the
+ * conversion — the logo is DERIVED from the brand asset, not drawn by hand, so
+ * it stays honest to it.
+ *
+ * ── ⚠️ THE CONSTRAINTS, WHICH ARE NOT PREFERENCES ───────────────────────────
+ *
+ * · **Half-block glyphs only** (▀ ▄ █). Braille and box-drawing render as tofu
+ *   in cmd.exe and in many CI log viewers, and a logo that renders as question
+ *   marks is worse than no logo — on the exact platform this is developed on.
+ * · **No colour escapes here.** The caller owns colour and honours NO_COLOR; a
+ *   module that hard-codes them emits garbage the moment output is piped.
+ * · **Every line under 80 columns.** The narrowest terminal in real use is 80,
+ *   and a wrapped banner does not read as dense, it reads as broken.
+ *
+ * ⭐ A NOTE ON DOING BETTER: `lib/terminal-graphics.mjs` can send a real PNG
+ * inline on Kitty and iTerm2. It is deliberately NOT used here — Windows
+ * Terminal speaks neither protocol, so the block art is what most users would
+ * see anyway, and one rendering that is the same everywhere beats two that
+ * disagree.
+ */
+
+/**
+ * The Acuvo mark, resampled from the brand PNG. Seven rows: tall enough to be
+ * the mark rather than a smudge, short enough for something run forty times a
+ * day rather than opened once.
+ */
+const MARK = [
+  '      ▄█',
+  '     ▄███',
+  '    ▄█▀▀██',
+  '   ▄█▀  ▀██',
+  '  ▄█▀ ██ ▀██',
+  ' ▄████▀▀█████',
+  '█▀      █▀  ▀█',
+];
+
+/**
+ * ── ⭐⭐⭐ THE SAME MARK, IN CHARACTERS NOTHING CAN STRETCH ─────────────────
+ *
+ * Every glyph here is ASCII, so it is width-1 by definition in every terminal,
+ * every font, every locale. No ambiguity class, nothing to measure, nothing to
+ * get wrong.
+ *
+ * ⚠️ THIS IS NOT "NO LOGO" — that distinction matters. Roman asked for OUR
+ * mark and then asked again when he got letters spelling the name. The fallback
+ * for a terminal that cannot draw half-blocks must therefore still BE the
+ * angular A, drawn a different way, rather than a wordmark standing in for it.
+ * A degraded logo is a logo; a text substitute is a missing one.
+ */
+const MARK_ASCII = [
+  '     /\\',
+  '    /  \\',
+  '   / /\\ \\',
+  '  / /  \\ \\',
+  ' / /____\\ \\',
+  '/_/      \\_\\',
+];
+
+const GUTTER = 2;
+
+/**
+ * The widest the banner may ever be when the terminal will not say how wide it
+ * is. Kept at 80 because that is the narrowest terminal in real use, so a
+ * banner built to it fits everywhere.
+ */
+export const MAX_BANNER_COLUMNS = 80;
+
+/** Below this the two-column layout stops being a layout and starts being a mess. */
+const MIN_TEXT_COLUMNS = 30;
+
+/**
+ * Build the opening screen: mark on the left, facts on the right.
+ *
+ * @param {object} o
+ * @param {string} o.version
+ * @param {string} o.workspace   already shortened by the caller
+ * @param {string} o.model
+ * @param {string} o.billing     who this run will charge
+ * @param {string} o.canRun      what it may execute, or that it may not
+ * @param {boolean} [o.interactive] whether a prompt follows
+ * @param {'blocks'|'text'} [o.style] which mark to draw — see `lib/glyph-width.mjs`
+ * @param {number} [o.columns]   the real terminal width, when it is known
+ * @returns {string}
+ */
+export function openingScreen({
+  version, workspace, model, billing, canRun,
+  interactive = false, paint = null, style = 'blocks', columns = null,
+}) {
+  const brand = paint?.brand ?? ((s) => s);
+
+  /**
+   * ── ⚠️⚠️ THE WIDTH IS THE TERMINAL'S, NOT A CONSTANT ──────────────────
+   *
+   * This used to build to a fixed 80 columns and never ask. Every line it
+   * produced was under 80 and it looked immaculate — in an 80-column terminal.
+   * In a narrower one, which is what a side panel or a split pane is, every
+   * single row wraps, and a wrapped banner does not read as dense. It reads as
+   * broken software, which is the first thing a new user sees.
+   *
+   * `- 1` because a line that exactly fills the width wraps on some terminals
+   * and not others, and the difference is not worth one column.
+   */
+  const width = Math.max(20, Math.min(MAX_BANNER_COLUMNS, (columns ?? MAX_BANNER_COLUMNS) - 1));
+
+  const mark = style === 'text' ? MARK_ASCII : MARK;
+  const markWidth = Math.max(...mark.map((l) => l.length));
+
+  /**
+   * ⭐ THREE LAYOUTS, CHOSEN BY WHAT ACTUALLY FITS — never by a platform guess.
+   * Side by side when there is room for both; mark above the facts when there
+   * is room for the mark alone; facts only when there is not. The last one is
+   * rare and it still has to be right, because a 24-column terminal is somebody
+   * on a phone over SSH and they deserve a legible screen, not a torn one.
+   */
+  const sideBySide = width >= markWidth + GUTTER + MIN_TEXT_COLUMNS;
+  const textColumns = sideBySide ? width - markWidth - GUTTER : width;
+
+  /**
+   * ⚠️ ELIDED IN THE MIDDLE, NOT THE END. The informative parts of a path are
+   * the drive and the leaf; chopping the tail leaves `C:\Users\somebody\Projects\a-`,
+   * which identifies nothing. Same for a model id, where the family is at the
+   * front and the variant at the back.
+   */
+  const room = Math.max(8, textColumns - 11);
+  const fit = (v) => {
+    const s = String(v ?? '');
+    if (s.length <= room) return s;
+    const head = Math.ceil((room - 1) / 2);
+    return `${s.slice(0, head)}…${s.slice(s.length - (room - 1 - head))}`;
+  };
+
+  const right = [
+    `ACUVO CODE${version ? `  ${version}` : ''}`,
+    '',
+    `workspace  ${fit(workspace)}`,
+    `model      ${fit(model)}`,
+    `billing    ${fit(billing)}`,
+    `can run    ${fit(canRun)}`,
+    '',
+  ];
+
+  const lines = [''];
+
+  if (sideBySide) {
+    /**
+     * ⚠️ THE TWO COLUMNS ARE ZIPPED, NOT CONCATENATED, and the row counts are
+     * allowed to differ — whichever is shorter simply runs out.
+     */
+    const rows = Math.max(mark.length, right.length);
+    for (let i = 0; i < rows; i += 1) {
+      const text = right[i] ?? '';
+      /**
+       * ⚠️ PADDED FIRST, PAINTED SECOND — escape codes have no width, so padding
+       * a coloured string aligns text against invisible bytes and the whole
+       * right-hand column drifts.
+       *
+       * ⚠️⚠️ AND PADDED ONLY WHEN SOMETHING FOLLOWS. On a mark-only row the
+       * padding sits INSIDE the colour, before the reset, where `trimEnd`
+       * cannot reach it — so the coloured banner carried trailing whitespace the
+       * plain one did not. Invisible, but it means colour changed the layout.
+       */
+      const raw = mark[i] ?? '';
+      const padded = text ? raw.padEnd(markWidth + GUTTER) : raw;
+      lines.push(`${mark[i] ? brand(padded) : padded}${text}`.trimEnd());
+    }
+  } else {
+    const roomForMark = width >= markWidth;
+    if (roomForMark) {
+      for (const row of mark) lines.push(brand(row));
+      lines.push('');
+    }
+    for (const text of right) lines.push(text.trimEnd());
+  }
+
+  lines.push('');
+
+  /**
+   * ⚠️ ONLY WHEN A PROMPT ACTUALLY FOLLOWS. Printing "type what you want done"
+   * above a one-shot run that has already been given its task is an instruction
+   * for something the user cannot do.
+   *
+   * ⭐ And it is SHORTENED rather than wrapped when the terminal is narrow. A
+   * hint that wraps onto a second line looks like an error message.
+   */
+  if (interactive) {
+    /**
+     * ⭐ SHORTENED IN STAGES, NEVER TRUNCATED. A clamp would cut "leave" to
+     * "leav", and a hint with a word chopped in half does not read as a
+     * compact hint — it reads as a rendering bug, which is precisely the
+     * impression this screen keeps making.
+     */
+    const hints = [
+      '  Type what you want done.   /help for commands  ·  exit to leave',
+      '  /help for commands  ·  exit to leave',
+      '  /help  ·  exit',
+    ];
+    lines.push(hints.find((h) => h.length <= width) ?? hints[hints.length - 1], '');
+  }
+
+  /**
+   * ⚠️⚠️ THE LAST WORD ON WIDTH, AND IT IS NOT A BELT-AND-BRACES CHECK.
+   * Everything above reasons about `.length`, which counts CODE UNITS, while a
+   * terminal counts CELLS — and the whole reason this file was rewritten is that
+   * those two disagree. This clamp is measured on the painted string with the
+   * escapes discounted, so a mark that turns out wider than advertised is
+   * truncated rather than allowed to wrap and tear the layout.
+   */
+  return lines.map((l) => clampToWidth(l, width)).join('\n');
+}
+
+/** Visible length, ignoring ANSI escapes — they occupy no cells. */
+function visibleLength(s) {
+  return String(s).replace(/\[[0-9;]*m/g, '').length;
+}
+
+/**
+ * Cut a possibly-coloured string to `width` visible cells, keeping the escapes
+ * balanced so a truncation cannot leak colour into the rest of the screen.
+ */
+function clampToWidth(s, width) {
+  if (visibleLength(s) <= width) return s;
+  let out = '';
+  let seen = 0;
+  const re = /(\[[0-9;]*m)|([\s\S])/g;
+  let m;
+  while ((m = re.exec(s)) !== null) {
+    if (m[1]) { out += m[1]; continue; }
+    if (seen >= width) break;
+    out += m[2];
+    seen += 1;
+  }
+  /**
+   * ⚠️ ONLY RE-CLOSE A STRING THAT WAS ACTUALLY COLOURED. Appending a reset
+   * unconditionally puts four bytes on the end of every truncated PLAIN line —
+   * harmless on a terminal, and garbage the moment output is piped to a file or
+   * a CI log, which is the one place this module has already been told never to
+   * write escapes.
+   */
+  return out.includes('') ? `${out}` : out;
+}

package/lib/glyph-width.mjs

@@ -0,0 +1,169 @@
+/**
+ * ── ⭐⭐⭐ ASK THE TERMINAL HOW WIDE A GLYPH ACTUALLY IS ─────────────────────
+ *
+ * Roman, 2026-08-22, third report on the same screen: *"acuvo cli still is
+ * structured wrong, I can't even see our logo, and the words etc, like it
+ * doesn't fit."*
+ *
+ * ── ⚠️ WHY THE BANNER CAN BE CORRECT AND STILL SHATTER ──────────────────────
+ *
+ * The mark is built from half-block glyphs (▀ ▄ █, U+2580–U+2588). Unicode
+ * classifies them as **East Asian Ambiguous**, which means their width is not a
+ * property of the character — it is a property of the terminal and the font. A
+ * terminal that renders them at TWO cells turns a 14-column mark into 28
+ * columns, while the SPACES padding each row stay at one. The art does not get
+ * uniformly wider; it tears, every row by a different amount, and the right-hand
+ * column is shoved off the screen. That is exactly "I can't even see our logo,
+ * and the words don't fit", and it is invisible from any machine where the font
+ * happens to render them narrow — including mine, where the banner measures a
+ * tidy 72 columns and looks perfect.
+ *
+ * ⭐ SO STOP GUESSING AND MEASURE. Print the glyph, ask the terminal where the
+ * cursor ended up (`ESC[6n`, the DSR cursor-position report from ECMA-48), and
+ * subtract. The answer is not an inference about fonts or platforms; it is the
+ * terminal reporting its own behaviour. This is what every serious TUI does for
+ * emoji and CJK, and it is the only instrument that works from here — three
+ * previous attempts at this screen were reasoned from byte sequences and all
+ * three were wrong on the one machine that mattered.
+ *
+ * ── ⚠️ AND IT MUST FAIL SAFE, BECAUSE IT TOUCHES THE SCREEN ─────────────────
+ *
+ * The probe writes a character and reads a reply. If the terminal never answers
+ * — a dumb TERM, a pipe, a CI log, an editor's embedded console that swallows
+ * DSR — it must give up quickly, erase what it wrote, restore raw mode exactly
+ * as it found it, and return `null` for "unknown". A diagnostic that hangs the
+ * program it is diagnosing, or that leaves the terminal in raw mode after a
+ * failure, is worse than the bug.
+ */
+
+/** The DSR request: "report the cursor position". */
+const CURSOR_QUERY = '\x1b[6n';
+
+/**
+ * Parse a cursor-position report, `ESC [ row ; col R`.
+ *
+ * ⚠️ SCANS FOR THE PATTERN RATHER THAN ANCHORING AT THE START. The reply can
+ * arrive glued to whatever else the user typed — a keystroke that landed during
+ * the round trip sits in the same chunk — and an anchored match would discard a
+ * perfectly good measurement because somebody pressed a key.
+ *
+ * @param {string} buf
+ * @returns {{ row: number, col: number } | null}
+ */
+export function parseCursorReport(buf) {
+  const m = /\x1b\[(\d+);(\d+)R/.exec(String(buf ?? ''));
+  if (!m) return null;
+  const row = Number(m[1]);
+  const col = Number(m[2]);
+  if (!Number.isFinite(row) || !Number.isFinite(col) || col < 1) return null;
+  return { row, col };
+}
+
+/**
+ * Anything left over once the report is removed — the user's keystrokes.
+ *
+ * ⚠️ THEY MUST BE HANDED BACK, NOT DROPPED. A character typed while the probe
+ * was in flight belongs to the program, and eating it makes the very first
+ * keystroke of a session vanish at random.
+ *
+ * @param {string} buf
+ * @returns {string}
+ */
+export function residualInput(buf) {
+  return String(buf ?? '').replace(/\x1b\[\d+;\d+R/, '');
+}
+
+/**
+ * How many cells the terminal gives `glyph`.
+ *
+ * @param {object} o
+ * @param {string} [o.glyph]        the character to measure
+ * @param {NodeJS.ReadStream} o.input
+ * @param {NodeJS.WriteStream} o.output
+ * @param {number} [o.timeoutMs]
+ * @returns {Promise<number|null>} 1, 2, … or null when the terminal did not say
+ */
+export async function measureCellWidth({ glyph = '█', input, output, timeoutMs = 200 } = {}) {
+  if (!input?.isTTY || !output?.isTTY || typeof input.setRawMode !== 'function') return null;
+
+  const wasRaw = input.isRaw === true;
+  let done = false;
+  let buffered = '';
+
+  return new Promise((resolve) => {
+    /**
+     * ⚠️ ONE EXIT PATH, AND IT ALWAYS CLEANS UP. Every way out of this — a
+     * reply, a timeout, a stream error — goes through here, because a probe
+     * that returns early on the happy path and leaks a listener on the sad one
+     * is how a CLI ends up with a terminal stuck in raw mode after a hiccup.
+     */
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      input.removeListener('data', onData);
+      try {
+        // Erase the probe glyph and put the cursor back at the start of the line.
+        output.write('\r\x1b[2K');
+      } catch { /* the stream went away; nothing to clean */ }
+      try {
+        if (!wasRaw) input.setRawMode(false);
+      } catch { /* likewise */ }
+      // Give any keystrokes that arrived during the probe back to the program.
+      const rest = residualInput(buffered);
+      if (rest) input.unshift?.(rest);
+      resolve(value);
+    };
+
+    const onData = (chunk) => {
+      buffered += String(chunk);
+      const report = parseCursorReport(buffered);
+      if (!report) return;
+      /**
+       * The cursor started at column 1, so the glyph consumed `col - 1` cells.
+       * Guarded because a terminal that answers nonsense should read as unknown
+       * rather than as a plausible-looking wrong number.
+       */
+      const cells = report.col - 1;
+      finish(cells >= 1 && cells <= 4 ? cells : null);
+    };
+
+    const timer = setTimeout(() => finish(null), timeoutMs);
+
+    try {
+      if (!wasRaw) input.setRawMode(true);
+      input.on('data', onData);
+      // `\r` first: measure from a known column, not from wherever we happened to be.
+      output.write(`\r${glyph}${CURSOR_QUERY}`);
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+/**
+ * The decision the banner actually needs, with every override that matters.
+ *
+ * ⚠️ AN EXPLICIT SETTING OUTRANKS THE MEASUREMENT, ALWAYS. Detection is very
+ * good and will still be wrong somewhere, and when it is, the user must have a
+ * way to say so that does not require them to file a bug and wait for a
+ * release. `ACUVO_BANNER=text` (or `blocks`) is that way.
+ *
+ * ⚠️ AND UNKNOWN FALLS BACK TO **TEXT**, not to blocks. The two errors are not
+ * symmetric: choosing text on a terminal that could have drawn the mark costs a
+ * little beauty, while choosing blocks on a terminal that cannot costs the user
+ * a screen of torn garbage as their first impression of the product. This is
+ * the mistake that has now been reported three times, so the default leans away
+ * from it.
+ *
+ * @param {object} o
+ * @param {number|null} o.cellWidth  measured, or null
+ * @param {Record<string,string|undefined>} [o.env]
+ * @returns {'blocks'|'text'}
+ */
+export function bannerStyle({ cellWidth, env = {} }) {
+  const forced = String(env.ACUVO_BANNER ?? '').toLowerCase();
+  if (forced === 'text' || forced === 'ascii') return 'text';
+  if (forced === 'blocks' || forced === 'art') return 'blocks';
+  return cellWidth === 1 ? 'blocks' : 'text';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acuvo-code",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Acuvo Code — the terminal client for the Acuvo capability registry. Zero dependencies, by design.",
   "type": "module",
   "bin": {