acuvo-code 0.6.3 → 0.6.5

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 **122 files — 120 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 122 files and 79553 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

@@ -143,6 +143,23 @@ const asker = createAsker();
  * word "compaction" to stop paying for a transcript they cannot see.
  */
 import { runDoctor, formatDoctor } from '../lib/doctor.mjs';
+
+/**
+ * The package version, readable from anywhere in this file.
+ *
+ * ⚠️ THE LOCAL `pkgVersion` IS DECLARED 300 LINES BELOW ITS FIRST USE and is a
+ * `const`, so reaching for it earlier is a temporal-dead-zone ReferenceError
+ * rather than an undefined — which is how `--render-report` crashed the moment
+ * it was wired in. A second reader is the small fix; hoisting the const would
+ * move a declaration other code depends on being late.
+ */
+function readPkgVersion() {
+  try {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+  } catch {
+    return '';
+  }
+}
 /**
  * ── ⭐ SHELL COMPLETION — built, tested, and reachable from nothing until now ──
  * `lib/completion.mjs` is 509 lines that generate bash, zsh and fish scripts
@@ -309,6 +326,7 @@ const LIFECYCLE_USAGE = [
    * sentence changed.
    */
   '  --doctor              Say what is actually working here: key, model chain, media',
+  '  --render-report       Print how this terminal draws the opening screen, to paste back',
   '                        endpoints, which tools would be offered, git. Every dark or',
   '                        broken line names the exact variable that fixes it. Exits 0',
   '                        when nothing is broken. ⚠️ It VERIFIES over the network: your',
@@ -351,7 +369,7 @@ const VALUED_LIFECYCLE_FLAGS = new Map([
 function extractLifecycleFlags(argv) {
   const flags = {
     sessions: false, resume: null, continueLatest: false, save: true, audit: true,
-    doctor: false, replay: null, diff: null, only: null, design: null,
+    doctor: false, renderReport: false, replay: null, diff: null, only: null, design: null,
     login: false, loginToken: null, logout: false, whoami: false,
   };
   const rest = [];
@@ -359,6 +377,13 @@ function extractLifecycleFlags(argv) {
     const arg = argv[i];
     if (arg === '--sessions') { flags.sessions = true; continue; }
     if (arg === '--doctor') { flags.doctor = true; continue; }
+    /**
+     * ⭐ THE INSTRUMENT FOR A SCREEN I CANNOT SEE. Five reports, four fixes,
+     * and every one reasoned from bytes that render perfectly on my machine.
+     * This prints the facts that decide the layout so the next round is
+     * arithmetic instead of inference.
+     */
+    if (arg === '--render-report' || arg === '--render') { flags.renderReport = true; continue; }
     if (arg === '--logout') { flags.logout = true; continue; }
     if (arg === '--whoami') { flags.whoami = true; continue; }
     /**
@@ -1185,6 +1210,22 @@ ${formatBoard(listed)}
     return EXIT_OK;
   }
 
+  /**
+   * ⚠️ BEFORE `--doctor`, AND BEFORE ANYTHING THAT PRINTS. This report is about
+   * how the terminal DRAWS, so nothing may have written to the screen ahead of
+   * it — a banner above the ruler would be measuring a screen we had already
+   * disturbed.
+   */
+  if (life.renderReport) {
+    const { renderReport, formatRenderReport } = await import('../lib/render-report.mjs');
+    const rep = await renderReport({ input: process.stdin, output: process.stdout, env: process.env, version: readPkgVersion() });
+    if (opts.json) process.stdout.write(`${JSON.stringify(rep, null, 2)}
+`);
+    else process.stdout.write(`${formatRenderReport(rep)}
+`);
+    return EXIT_OK;
+  }
+
   if (life.doctor) {
     const report = await runDoctor({ root, allowRun: opts.allowRun, maxRounds: opts.maxRounds, skipNetwork: opts.offline === true });
     if (opts.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
@@ -1489,6 +1530,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 +1581,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/lib/render-report.mjs

@@ -0,0 +1,136 @@
+/**
+ * ── ⭐⭐⭐ STOP GUESSING AT SOMEBODY ELSE'S SCREEN ───────────────────────────
+ *
+ * Roman has now reported this screen wrong five times: "not opening as a
+ * typable terminal", "you have to scroll down", "now it's just the box,
+ * everything else is gone", "I can't even see our logo, it doesn't fit", and
+ * "CLI structure is still cooked, it's not loading like our Claude reference."
+ *
+ * ⚠️ FIVE REPORTS, FOUR FIXES, AND I HAVE NEVER ONCE SEEN THE THING I AM
+ * FIXING. Every attempt was reasoned from byte sequences that render perfectly
+ * here, and the only instrument that has ever caught a defect was him opening a
+ * terminal and describing it in words. That is a slow, lossy channel, and after
+ * four rounds it is plainly not converging.
+ *
+ * ⭐ SO THIS IS THE INSTRUMENT. One command prints every fact that determines
+ * how the opening screen draws — the emulator's identity, its real size, the
+ * MEASURED cell width of the glyphs the logo is built from, which layout that
+ * selects, and then the banner itself under a column ruler. Paste it back and
+ * the diagnosis is arithmetic instead of inference.
+ *
+ * ⚠️ IT PRINTS FACTS, NOT A VERDICT. A report that says "looks fine to me" when
+ * the user is staring at a broken screen is worse than no report — it argues
+ * with them. Every line here is something observed, and where nothing could be
+ * observed it says so.
+ */
+
+import { openingScreen } from './banner.mjs';
+import { measureCellWidth, bannerStyle } from './glyph-width.mjs';
+
+/** The environment variables that actually change how this draws. */
+const RELEVANT_ENV = [
+  'TERM', 'TERM_PROGRAM', 'TERM_PROGRAM_VERSION', 'COLORTERM',
+  'WT_SESSION', 'ConEmuANSI', 'SESSIONNAME',
+  'NO_COLOR', 'FORCE_COLOR', 'CI',
+  'ACUVO_BANNER', 'ACUVO_PIN', 'LANG', 'LC_ALL',
+];
+
+/**
+ * Gather everything, measuring what can be measured.
+ *
+ * @param {object} o
+ * @param {NodeJS.ReadStream} o.input
+ * @param {NodeJS.WriteStream} o.output
+ * @param {Record<string,string|undefined>} [o.env]
+ * @param {string} [o.version]
+ */
+export async function renderReport({ input, output, env = process.env, version = '' }) {
+  /**
+   * ⚠️ MEASURED, NOT ASSUMED — and the ASCII fallback glyphs are measured too.
+   * If a terminal renders `/` or `\` at anything other than one cell we would
+   * want to know, because the "safe" fallback would not be safe either and the
+   * whole strategy needs rethinking rather than another patch.
+   */
+  const block = await measureCellWidth({ glyph: '█', input, output });
+  const slash = await measureCellWidth({ glyph: '/', input, output });
+
+  const style = bannerStyle({ cellWidth: block, env });
+
+  return {
+    columns: output?.columns ?? null,
+    rows: output?.rows ?? null,
+    isTTY: Boolean(output?.isTTY),
+    stdinIsTTY: Boolean(input?.isTTY),
+    blockCellWidth: block,
+    asciiCellWidth: slash,
+    style,
+    env: Object.fromEntries(RELEVANT_ENV.map((k) => [k, env[k] ?? null])),
+    version,
+  };
+}
+
+/** A ruler that makes an off-by-N obvious at a glance. */
+export function ruler(width) {
+  const w = Math.max(1, Math.min(400, Number(width) || 80));
+  let out = '';
+  for (let i = 1; i <= w; i += 1) {
+    out += i % 10 === 0 ? String((i / 10) % 10) : i % 5 === 0 ? '+' : '.';
+  }
+  return out;
+}
+
+/**
+ * Render the report as text safe to paste into a chat.
+ *
+ * ⚠️ NO COLOUR ANYWHERE IN THIS OUTPUT. It exists to be copied into a message,
+ * and escape codes pasted into a chat window arrive as visual noise that hides
+ * the very alignment the report is about.
+ */
+export function formatRenderReport(r) {
+  const say = (v) => (v === null || v === undefined ? 'unknown' : String(v));
+  const lines = [];
+
+  lines.push('ACUVO RENDER REPORT' + (r.version ? `  ${r.version}` : ''));
+  lines.push('');
+  lines.push(`terminal size      ${say(r.columns)} x ${say(r.rows)}`);
+  lines.push(`stdout is a TTY    ${r.isTTY}`);
+  lines.push(`stdin is a TTY     ${r.stdinIsTTY}`);
+  lines.push('');
+
+  /**
+   * ⭐ THE TWO LINES THE WHOLE INVESTIGATION TURNS ON. A block width of 2 means
+   * the half-block logo CANNOT be drawn correctly here, and no amount of layout
+   * work will fix it — the answer is the ASCII mark. A width of 1 rules that
+   * out entirely and points the search somewhere else.
+   */
+  lines.push(`block glyph width  ${say(r.blockCellWidth)} cell(s)   <- 1 = safe, 2 = the logo tears`);
+  lines.push(`ascii glyph width  ${say(r.asciiCellWidth)} cell(s)   <- must be 1, or the fallback is unsafe too`);
+  lines.push(`chosen mark        ${r.style}`);
+  lines.push('');
+
+  const envLines = Object.entries(r.env).filter(([, v]) => v !== null);
+  lines.push(envLines.length ? 'environment' : 'environment        (none of the relevant variables are set)');
+  for (const [k, v] of envLines) lines.push(`  ${k.padEnd(20)} ${v}`);
+  lines.push('');
+
+  const width = r.columns ?? 80;
+  lines.push(`ruler (${width} columns) — the banner below must never reach the end of this line:`);
+  lines.push(ruler(width));
+  lines.push('');
+  lines.push(openingScreen({
+    version: r.version || '0.0.0',
+    workspace: 'C:/example/workspace',
+    model: 'Acuvo Flash 1',
+    billing: 'Acuvo account',
+    canRun: 'read + write + shell',
+    interactive: true,
+    style: r.style,
+    columns: r.columns,
+  }));
+  lines.push(ruler(width));
+  lines.push('');
+  lines.push('If the mark above looks torn or the rows do not line up, paste this whole');
+  lines.push('report back. Every number needed to diagnose it is in here.');
+
+  return lines.join('\n');
+}

package/package.json

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