acuvo-code 0.5.0 → 0.5.2

package/ENTERPRISE.md

@@ -189,7 +189,7 @@ 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
-`bin/` — about 78245 lines**, with **237 test files** beside them (counted 2026-08-22).
+`bin/` — about 78328 lines**, with **237 test files** beside them (counted 2026-08-22).
 
 ⭐ **AND THE 108 WENT STALE IN THE MOST INSTRUCTIVE WAY POSSIBLE: THREE OF THE FILES IT
 MISSED WERE REACHABLE FROM NOTHING.** `wiring-reach.test.mjs` was naming
@@ -203,7 +203,7 @@ exactly the kind of number this section warns about.
 allowlist also carries **`test/`, `ENTERPRISE.md` and `ROADMAP.md`**, and the published
 tarball is **265 files, 5.1 MB unpacked — 182 of them tests against 98 of `lib/`.** That is
 deliberate, not drift (commit `ed08f2710`, *"ship the tests, and add CI that would have
-caught the false green"*): a document that invites you to audit 76736 lines and then ships
+caught the false green"*): a document that invites you to audit 78328 lines and then ships
 you the source without the tests is asking to be taken on trust, which is the one thing this
 file refuses to ask for. ⭐ **Run them yourself: `npm test` inside the installed package.**
 The stale sentence is the more interesting failure — it under-claimed, so nobody would ever
@@ -892,8 +892,8 @@ 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 116 files and 76736 lines,
-  and there is no `node_modules` behind it. (Counted 2026-08-20 from
+- ⭐ **Zero dependencies.** The entire auditable surface is 120 files and 78328 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
   count that fails the build is the only kind that stays true — this one has now caught its own

package/lib/chat.mjs

@@ -353,7 +353,14 @@ export async function runChat({
    * quits) has to arrive here too, or the escape hatch is a single-use one.
    */
   if (rl) rl.on('SIGINT', () => { onInterrupt(); });
-  if (banner) output.write(`${banner}\n`);
+  /**
+   * ⚠️⚠️ THE BANNER IS DEFERRED UNTIL AFTER THE PIN, AND THE ORDER IS NOT
+   * COSMETIC. `pinRegion` CLEARS the screen so the transcript starts at the top
+   * of a clean one — printed before that, the banner is erased by the very
+   * thing meant to sit beneath it, which is exactly what a screenshot showed:
+   * a banner cut in half with the conversation crammed at the bottom.
+   */
+  const writeBanner = () => { if (banner) output.write(`${banner}\n`); };
   // ⚠️ `/help` IS ADVERTISED IN THE ONE LINE EVERY SESSION PRINTS. A command
   // surface nobody is told about is the same defect item 14 closed for `--help`:
   // the feature worked and nothing a stranger would read mentioned it.
@@ -398,6 +405,13 @@ export async function runChat({
     process.once('SIGTERM', releasePin);
   }
 
+  /**
+   * ⭐ NOW the banner, at the top of a screen the pin has just cleared, with the
+   * conversation free to grow downward beneath it — which is the direction every
+   * scrollback in existence runs.
+   */
+  writeBanner();
+
   try {
     for (;;) {
       /**
@@ -425,6 +439,7 @@ export async function runChat({
       if (interactive) {
         output.write('\n');
         const got = await readBoxedLine({
+          atRow: pin.enabled ? pin.bottom + 1 : 0,
           input,
           output,
           history: typed,

package/lib/input-box.mjs

@@ -1,409 +1,477 @@
-/**
- * ── ⭐⭐⭐ A PERSISTENT INPUT BOX, BECAUSE READLINE CANNOT DRAW ONE ──────────
- *
- * Roman, repeatedly: *"the box that I am typing in right now needs to be real."*
- *
- * ── ⚠️⚠️ WHY READLINE WAS NEVER GOING TO WORK, MEASURED ─────────────────────
- *
- * Pre-drawing a four-sided box and asking `readline.question()` to type inside
- * it produces this on the very first keystroke:
- *
- *     \x1b[1G\x1b[0J
- *
- * Column 1, then **clear to end of screen**. Readline owns everything from the
- * cursor down and erases it to redraw the line — so the bottom border and the
- * right edge are gone before the user has typed a second character. No amount of
- * re-drawing wins that fight; it repaints on every key.
- *
- * ⭐ SO THE ANSWER IS TO OWN THE RENDER. This is a small raw-mode line editor:
- * it reads keys, keeps the buffer, and paints three lines itself. That is what
- * every terminal app with a real input box does, and it is why they can have one.
- *
- * ── ⚠️ WHAT IT MUST NOT LOSE ────────────────────────────────────────────────
- *
- * A half-built line editor is WORSE than a plain prompt: backspace that does
- * nothing, or an arrow key that prints `^[[D`, makes the tool feel broken in a
- * way `› ` never did. So the keys people actually use are all handled —
- * backspace, delete, left/right, home/end, word-left/right, history up/down,
- * Ctrl-C, Ctrl-D, Ctrl-U/K/W — and each is tested.
- */
-
-const ESC = '\x1b';
-const CSI = `${ESC}[`;
-
-/** Keys that are not text. Kept as one table so the handler stays readable. */
-const KEY = Object.freeze({
-  ENTER: '\r',
-  NEWLINE: '\n',
-  BACKSPACE: '\x7f',
-  BACKSPACE_ALT: '\b',
-  CTRL_C: '\x03',
-  CTRL_D: '\x04',
-  CTRL_U: '\x15',
-  CTRL_K: '\x0b',
-  CTRL_W: '\x17',
-  CTRL_A: '\x01',
-  CTRL_E: '\x05',
-});
-
-/**
- * Visible width of a string, ignoring ANSI. Deliberately simple: this package
- * has no dependencies and a full grapheme/east-asian-width implementation is a
- * library. It is correct for the ASCII and box characters we draw, and errs by
- * over-counting a wide glyph rather than under — which wraps early rather than
- * overflowing the border.
- */
-export function visibleWidth(s) {
-  return String(s ?? '').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '').length;
-}
-
-/**
- * Render the three lines of the box for a given buffer.
- *
- * Exported so the layout can be asserted without a terminal — the render and
- * the key handling are separately testable, which is the only way a thing like
- * this stays correct.
- *
- * @returns {{lines: string[], cursorColumn: number}} 1-based cursor column
- */
-export function renderBox({ value = '', cursor = 0, columns = 80, prompt = '› ' } = {}) {
-  /**
-   * ── ⚠️ FULL WIDTH. THE 100-COLUMN CAP WAS WRONG AND IT LOOKED WRONG ────────
-   *
-   * Roman, from a screenshot: *"ours isn't the entire width."* In a ~200-column
-   * terminal a 100-column box reads as a half-finished element rather than as a
-   * deliberate measure — it is the input, and the input should be as wide as the
-   * place you are typing.
-   *
-   * ⚠️ `columns - 1`, NOT `columns`. A box drawn to the very last column makes
-   * many terminals wrap to the next row the moment the final border character is
-   * written, which pushes everything down by one and breaks the cursor
-   * arithmetic for the rest of the session.
-   */
-  const width = Math.max(20, columns - 1);
-  const inner = width - 2;
-  const promptWidth = visibleWidth(prompt);
-
-  /**
-   * ⚠️ THE VIEW SCROLLS, THE BUFFER DOES NOT. A long line must not wrap — a
-   * wrapped line pushes the bottom border down and the box stops being a box.
-   * So the buffer is windowed around the cursor and the border stays put, which
-   * is what every real input does.
-   */
-  const room = inner - promptWidth - 1;
-  let start = 0;
-  if (cursor > room) start = cursor - room;
-  const shown = value.slice(start, start + room);
-
-  const body = `${prompt}${shown}`;
-  const pad = ' '.repeat(Math.max(0, inner - visibleWidth(body)));
-
-  return {
-    lines: [
-      `╭${'─'.repeat(width - 2)}╮`,
-      `│${body}${pad}│`,
-      `╰${'─'.repeat(width - 2)}╯`,
-    ],
-    // 1-based: the │, then the prompt, then however far into the shown text.
-    cursorColumn: 1 + 1 + promptWidth + (cursor - start),
-  };
-}
-
-/**
- * Apply one keypress to the editor state.
- *
- * ⚠️ PURE, AND THAT IS THE WHOLE POINT. Every key can be tested without a TTY,
- * without timing, and without a terminal to inspect afterwards. The half of this
- * module that touches the terminal does nothing but paint what this returns.
- *
- * @returns {{value, cursor, historyIndex, done?: 'submit'|'cancel'|'eof'}}
- */
-export function applyKey(state, key) {
-  const { value, cursor, history = [], historyIndex = history.length } = state;
-  /**
-   * ⚠️ `history` IS CARRIED THROUGH, AND ITS ABSENCE WAS A REAL BUG. The first
-   * version returned only `{value, cursor, historyIndex}` — so the history array
-   * was dropped by the FIRST keystroke, and pressing Up afterwards silently did
-   * nothing. It looked like the history feature was unimplemented rather than
-   * like state was being lost, which is exactly the kind of bug a pure function
-   * makes visible and a stateful one hides.
-   */
-  const keep = (over = {}) => ({ value, cursor, history, historyIndex, draft: state.draft, ...over });
-
-  if (key === KEY.ENTER || key === KEY.NEWLINE) return keep({ done: 'submit' });
-  if (key === KEY.CTRL_C) return keep({ done: 'cancel' });
-  /**
-   * ⚠️ Ctrl-D IS EOF ONLY ON AN EMPTY LINE. On a line with text it is
-   * forward-delete — collapsing the two would exit the session when someone
-   * meant to delete a character, which is a data-loss-shaped surprise.
-   */
-  if (key === KEY.CTRL_D) {
-    if (value.length === 0) return keep({ done: 'eof' });
-    return keep({ value: value.slice(0, cursor) + value.slice(cursor + 1) });
-  }
-
-  if (key === KEY.BACKSPACE || key === KEY.BACKSPACE_ALT) {
-    if (cursor === 0) return keep();
-    return keep({ value: value.slice(0, cursor - 1) + value.slice(cursor), cursor: cursor - 1 });
-  }
-
-  if (key === KEY.CTRL_U) return keep({ value: value.slice(cursor), cursor: 0 });
-  if (key === KEY.CTRL_K) return keep({ value: value.slice(0, cursor) });
-  if (key === KEY.CTRL_A) return keep({ cursor: 0 });
-  if (key === KEY.CTRL_E) return keep({ cursor: value.length });
-
-  if (key === KEY.CTRL_W) {
-    const upto = value.slice(0, cursor);
-    const cut = upto.replace(/\s*\S+$/, '');
-    return keep({ value: cut + value.slice(cursor), cursor: cut.length });
-  }
-
-  // Arrows and Home/End arrive as escape sequences.
-  if (key === `${CSI}D`) return keep({ cursor: Math.max(0, cursor - 1) });
-  if (key === `${CSI}C`) return keep({ cursor: Math.min(value.length, cursor + 1) });
-  if (key === `${CSI}H` || key === `${CSI}1~`) return keep({ cursor: 0 });
-  if (key === `${CSI}F` || key === `${CSI}4~`) return keep({ cursor: value.length });
-  if (key === `${CSI}3~`) return keep({ value: value.slice(0, cursor) + value.slice(cursor + 1) });
-
-  /**
-   * History. ⚠️ The index may sit one PAST the end — that position is "the line
-   * I was typing", so walking up and back down returns what you had rather than
-   * silently eating it.
-   */
-  if (key === `${CSI}A`) {
-    if (historyIndex === 0 || history.length === 0) return keep();
-    const i = historyIndex - 1;
-    /**
-     * ⚠️ THE DRAFT IS SAVED ON THE WAY UP. Leaving it behind means a half-typed
-     * line is destroyed by a single Up press — the user glances at what they ran
-     * before, comes back, and their sentence is gone. Losing typed input to a
-     * navigation key is the least forgivable bug a line editor can have.
-     */
-    const draft = historyIndex === history.length ? value : state.draft;
-    return keep({ value: history[i], cursor: history[i].length, historyIndex: i, draft });
-  }
-  if (key === `${CSI}B`) {
-    if (historyIndex >= history.length) return keep({ draft: state.draft });
-    const i = historyIndex + 1;
-    const next = i === history.length ? (state.draft ?? '') : history[i];
-    return keep({ value: next, cursor: next.length, historyIndex: i, draft: state.draft });
-  }
-
-  /**
-   * ⚠️ EVERYTHING ELSE CONTROL-SHAPED IS DROPPED, NOT INSERTED. An unhandled
-   * escape sequence typed into the buffer shows the user `^[[5~` and looks like
-   * the tool is broken — the one impression a new line editor cannot afford.
-   */
-  if (key.startsWith(ESC)) return keep();
-  if (key.length === 1 && key < ' ') return keep();
-
-  return keep({ value: value.slice(0, cursor) + key + value.slice(cursor), cursor: cursor + key.length });
-}
-
-/**
- * Split a raw chunk into keys. A paste arrives as one chunk and an arrow key as
- * three bytes, so neither "one byte per key" nor "one chunk per key" is right.
- */
-export function splitKeys(chunk) {
-  const s = String(chunk);
-  const keys = [];
-  for (let i = 0; i < s.length; i += 1) {
-    if (s[i] === ESC) {
-      const m = /^\x1b\[[0-9;]*[A-Za-z~]/.exec(s.slice(i));
-      if (m) { keys.push(m[0]); i += m[0].length - 1; continue; }
-    }
-    keys.push(s[i]);
-  }
-  return keys;
-}
-
-/**
- * Draw the box and park the cursor inside it.
- *
- * ⚠️ THE CURSOR IS HIDDEN WHILE PAINTING. Without it, the cursor visibly darts
- * to the end of each border as it is written — which reads as a flicker and is
- * the difference between a rendered box and a drawn one.
- */
-export function paint(output, state, { first = false } = {}) {
-  const { lines, cursorColumn } = renderBox(state);
-
-  /**
-   * ── ⚠️⚠️ THE CURSOR MATH, AND MY FIRST VERSION ATE THE SCREEN ──────────────
-   *
-   * Roman: *"it moves upwards every time you type a character then deletes the
-   * design you did."* Exactly right, and the arithmetic says why.
-   *
-   * After a paint the cursor rests on the INPUT line — line 2 of 3, not below
-   * the box. The first version began each repaint with `ESC[3A`, which is where
-   * it would be if the cursor were below. From line 2, moving up 3 lands ONE
-   * LINE ABOVE the top border — and the `ESC[0J` that follows clears from there
-   * to the bottom of the screen. So every keystroke crept upward and erased
-   * another line of the banner.
-   *
-   * ⭐ THE INVARIANT, WRITTEN DOWN BECAUSE IT IS THE WHOLE FUNCTION: this
-   * routine ENTERS with the cursor on the input line and LEAVES it there. So a
-   * repaint moves up exactly ONE line to reach the top border, and the final
-   * reposition moves up exactly one from the last line written.
-   *
-   *   ╭────────╮   <- line 1   ESC[1A from the input line reaches here
-   *   │› …      │   <- line 2   cursor lives here, in and out
-   *   ╰────────╯   <- line 3   cursor is here after writing; ESC[1A returns
-   *
-   * ⚠️ NO TRAILING NEWLINE. Writing one after the last border scrolls the
-   * viewport when the box is at the bottom of the screen, and every subsequent
-   * `up` is then off by a row for the rest of the session.
-   */
-  const home = first ? '' : `\r${CSI}1A`;
-  output.write(
-    `${CSI}?25l${home}${CSI}0J${lines.join('\n')}` +
-    `${CSI}1A\r${CSI}${cursorColumn}G${CSI}?25h`,
-  );
-}
-
-/**
- * ── ⭐⭐⭐ THE ONLY PART THAT TOUCHES A TERMINAL ─────────────────────────────
- *
- * Reads one line inside the box. Everything decision-shaped lives in `applyKey`
- * and `renderBox`, which are pure and fully tested; this function does nothing
- * but move bytes and paint what they return.
- *
- * @returns {Promise<{value: string|null, reason: 'submit'|'cancel'|'eof'}>}
- */
-export function readBoxedLine({ input, output, history = [], onInterrupt = null, prompt = '› ' }) {
-  return new Promise((resolve) => {
-    let state = { value: '', cursor: 0, history, historyIndex: history.length, draft: '' };
-    const columns = () => output.columns ?? process.stdout.columns ?? 80;
-
-    /**
-     * ⚠️ RAW MODE IS RESTORED ON EVERY EXIT PATH, INCLUDING THE UNHAPPY ONES.
-     * A process that leaves the terminal in raw mode hands the user a shell with
-     * no echo and no line editing — they have to type `reset` blind. That is the
-     * single worst thing a CLI can do to somebody's session.
-     */
-    let finished = false;
-    const finish = (value, reason) => {
-      if (finished) return;
-      finished = true;
-      input.off('data', onData);
-      input.off('end', onEnd);
-      try { input.setRawMode?.(false); } catch { /* not a TTY any more */ }
-      /**
-       * ── ⚠️⚠️ MOVE BELOW THE BOX BEFORE ANYTHING ELSE WRITES ─────────────────
-       *
-       * Seen in a screenshot: an MCP warning printed straight ON TOP of the
-       * bottom border, which was left visible only where the message was
-       * shorter than the box.
-       *
-       * The cursor rests on the INPUT line — line 2 of 3. A bare `\n` moves it
-       * to line 3, which IS the bottom border, so the very next thing anyone
-       * writes overwrites it. Down one FIRST, then a newline, so the cursor
-       * lands on fresh ground below a box that stays intact.
-       */
-      output.write(`${CSI}1B\n`);
-      resolve({ value, reason });
-    };
-
-    const onEnd = () => finish(null, 'eof');
-
-    const onData = (chunk) => {
-      for (const key of splitKeys(chunk)) {
-        const next = applyKey(state, key);
-        if (next.done === 'submit') {
-          state = next;
-          // Repaint once so the committed line is what stays on screen.
-          paint(output, { ...state, columns: columns() });
-          return finish(state.value, 'submit');
-        }
-        if (next.done === 'cancel') {
-          /**
-           * ⚠️ Ctrl-C ON A NON-EMPTY LINE CLEARS IT; on an empty one it means
-           * "stop". Anything else makes the first Ctrl-C — the one people press
-           * to abandon a sentence — quit the whole session.
-           */
-          /**
-           * ⚠️⚠️ Ctrl-C NEVER ENDS THE READ — it clears the line and hands the
-           * event on. The first version finished with `cancel` on an empty line,
-           * which ended the session on the FIRST press: there was then no prompt
-           * for a second Ctrl-C to arrive at, so the "press again to quit"
-           * escape hatch could never fire. `onInterrupt` owns that decision (see
-           * `interrupt.mjs`), and it can only own it if it keeps being called.
-           *
-           * ⭐ It is also what every shell does: Ctrl-C gives you a fresh line.
-           * Quitting is `exit`, or Ctrl-D on an empty one.
-           */
-          state = { ...state, value: '', cursor: 0, historyIndex: history.length, draft: '' };
-          onInterrupt?.();
-          paint(output, { ...state, columns: columns() });
-          continue;
-        }
-        if (next.done === 'eof') return finish(null, 'eof');
-        state = next;
-        paint(output, { ...state, columns: columns() });
-      }
-    };
-
-    try { input.setRawMode?.(true); } catch { /* not a TTY */ }
-    input.resume?.();
-    paint(output, { ...state, columns: columns() }, { first: true });
-    input.on('data', onData);
-    input.once('end', onEnd);
-  });
-}
-
-/**
- * ── ⭐⭐⭐ PINNING THE BOX TO THE BOTTOM OF THE SCREEN ───────────────────────
- *
- * Roman: *"we need that prompt box stuck down the bottom, it is professional."*
- *
- * A terminal can be told to scroll only PART of itself. `ESC[{top};{bottom}r`
- * sets the scrolling region; everything printed scrolls inside it, and the rows
- * below are left alone. Reserve the last three and the box never moves while
- * output flows past above it.
- *
- * ── ⚠️⚠️ THE PART THAT MUST NEVER BE GOT WRONG ──────────────────────────────
- *
- * A process that exits WITHOUT releasing the region leaves the user with a
- * terminal that scrolls inside a box forever, fixable only by typing `reset`
- * blind. That is the same class of harm as leaving raw mode on, and it must be
- * released on every path out — normal exit, Ctrl-C, SIGTERM, and an uncaught
- * throw. `release()` is idempotent and safe to call from all of them.
- *
- * ⚠️ AND IT IS OPT-IN. A reserved region is a claim on somebody's whole screen;
- * off a TTY, in CI, under a pipe or with ACUVO_NO_PIN=1 it is never set.
- */
-export function pinRegion(output, { rows = 3, env = process.env } = {}) {
-  const height = output?.rows ?? process.stdout?.rows ?? 0;
-  const enabled = Boolean(output?.isTTY)
-    && height > rows + 4
-    && String(env.ACUVO_NO_PIN ?? '') !== '1'
-    && String(env.CI ?? '').toLowerCase() !== 'true';
-
-  if (!enabled) return { enabled: false, release() {}, rows: 0, bottom: 0 };
-
-  const bottom = height - rows;
-  let released = false;
-
-  /**
-   * ⚠️ THE CURSOR IS PARKED INSIDE THE SCROLL REGION BEFORE ANYTHING PRINTS.
-   * Setting a region moves the cursor to home (1,1) on most terminals, so
-   * without this the next line of output lands at the TOP of the screen and the
-   * transcript reads backwards.
-   */
-  output.write(`${CSI}1;${bottom}r${CSI}${bottom};1H`);
-
-  const release = () => {
-    if (released) return;
-    released = true;
-    /**
-     * ⚠️ `ESC[r` WITH NO ARGUMENTS RESETS TO THE FULL SCREEN. Then the cursor is
-     * moved below the reserved rows so the shell prompt does not land on top of
-     * our box — an exit that leaves the terminal technically correct and
-     * visually broken is still a bad exit.
-     */
-    try {
-      output.write(`${CSI}r${CSI}${height};1H\n`);
-    } catch { /* the stream may already be gone on a hard exit */ }
-  };
-
-  return { enabled: true, release, rows, bottom };
-}
+/**
+ * ── ⭐⭐⭐ A PERSISTENT INPUT BOX, BECAUSE READLINE CANNOT DRAW ONE ──────────
+ *
+ * Roman, repeatedly: *"the box that I am typing in right now needs to be real."*
+ *
+ * ── ⚠️⚠️ WHY READLINE WAS NEVER GOING TO WORK, MEASURED ─────────────────────
+ *
+ * Pre-drawing a four-sided box and asking `readline.question()` to type inside
+ * it produces this on the very first keystroke:
+ *
+ *     \x1b[1G\x1b[0J
+ *
+ * Column 1, then **clear to end of screen**. Readline owns everything from the
+ * cursor down and erases it to redraw the line — so the bottom border and the
+ * right edge are gone before the user has typed a second character. No amount of
+ * re-drawing wins that fight; it repaints on every key.
+ *
+ * ⭐ SO THE ANSWER IS TO OWN THE RENDER. This is a small raw-mode line editor:
+ * it reads keys, keeps the buffer, and paints three lines itself. That is what
+ * every terminal app with a real input box does, and it is why they can have one.
+ *
+ * ── ⚠️ WHAT IT MUST NOT LOSE ────────────────────────────────────────────────
+ *
+ * A half-built line editor is WORSE than a plain prompt: backspace that does
+ * nothing, or an arrow key that prints `^[[D`, makes the tool feel broken in a
+ * way `› ` never did. So the keys people actually use are all handled —
+ * backspace, delete, left/right, home/end, word-left/right, history up/down,
+ * Ctrl-C, Ctrl-D, Ctrl-U/K/W — and each is tested.
+ */
+
+const ESC = '\x1b';
+const CSI = `${ESC}[`;
+
+/** Keys that are not text. Kept as one table so the handler stays readable. */
+const KEY = Object.freeze({
+  ENTER: '\r',
+  NEWLINE: '\n',
+  BACKSPACE: '\x7f',
+  BACKSPACE_ALT: '\b',
+  CTRL_C: '\x03',
+  CTRL_D: '\x04',
+  CTRL_U: '\x15',
+  CTRL_K: '\x0b',
+  CTRL_W: '\x17',
+  CTRL_A: '\x01',
+  CTRL_E: '\x05',
+});
+
+/**
+ * Visible width of a string, ignoring ANSI. Deliberately simple: this package
+ * has no dependencies and a full grapheme/east-asian-width implementation is a
+ * library. It is correct for the ASCII and box characters we draw, and errs by
+ * over-counting a wide glyph rather than under — which wraps early rather than
+ * overflowing the border.
+ */
+export function visibleWidth(s) {
+  return String(s ?? '').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '').length;
+}
+
+/**
+ * Render the three lines of the box for a given buffer.
+ *
+ * Exported so the layout can be asserted without a terminal — the render and
+ * the key handling are separately testable, which is the only way a thing like
+ * this stays correct.
+ *
+ * @returns {{lines: string[], cursorColumn: number}} 1-based cursor column
+ */
+export function renderBox({ value = '', cursor = 0, columns = 80, prompt = '› ' } = {}) {
+  /**
+   * ── ⚠️ FULL WIDTH. THE 100-COLUMN CAP WAS WRONG AND IT LOOKED WRONG ────────
+   *
+   * Roman, from a screenshot: *"ours isn't the entire width."* In a ~200-column
+   * terminal a 100-column box reads as a half-finished element rather than as a
+   * deliberate measure — it is the input, and the input should be as wide as the
+   * place you are typing.
+   *
+   * ⚠️ `columns - 1`, NOT `columns`. A box drawn to the very last column makes
+   * many terminals wrap to the next row the moment the final border character is
+   * written, which pushes everything down by one and breaks the cursor
+   * arithmetic for the rest of the session.
+   */
+  const width = Math.max(20, columns - 1);
+  const inner = width - 2;
+  const promptWidth = visibleWidth(prompt);
+
+  /**
+   * ⚠️ THE VIEW SCROLLS, THE BUFFER DOES NOT. A long line must not wrap — a
+   * wrapped line pushes the bottom border down and the box stops being a box.
+   * So the buffer is windowed around the cursor and the border stays put, which
+   * is what every real input does.
+   */
+  const room = inner - promptWidth - 1;
+  let start = 0;
+  if (cursor > room) start = cursor - room;
+  const shown = value.slice(start, start + room);
+
+  const body = `${prompt}${shown}`;
+  const pad = ' '.repeat(Math.max(0, width - visibleWidth(body)));
+
+  /**
+   * ── ⚠️⚠️ A RULE AND A PROMPT — NOT A BOX. THE SCREENSHOT SETTLED IT ─────────
+   *
+   * I built a four-sided box because Roman said "copy Claude's box exactly", and
+   * a screenshot of the real thing shows there IS no box: a horizontal rule
+   * across the full width, then `❯ ` beneath it. The submitted line gets a
+   * subtle highlight bar rather than a border.
+   *
+   * ⭐ AND THE RULE IS WHY IT LOOKS SETTLED RATHER THAN DRAWN. Two borders and
+   * two side walls make the input an object floating in the terminal; one rule
+   * makes it the bottom of the page. Roman: *"ours is organised weirdly."*
+   *
+   * ⚠️ Two rows, not three — so the reserved region shrinks with it and the
+   * transcript gets a row back.
+   */
+  return {
+    lines: [
+      '─'.repeat(width),
+      `${body}${pad}`,
+    ],
+    // 1-based, and there is no left border to skip any more.
+    cursorColumn: 1 + promptWidth + (cursor - start),
+  };
+}
+
+/**
+ * Apply one keypress to the editor state.
+ *
+ * ⚠️ PURE, AND THAT IS THE WHOLE POINT. Every key can be tested without a TTY,
+ * without timing, and without a terminal to inspect afterwards. The half of this
+ * module that touches the terminal does nothing but paint what this returns.
+ *
+ * @returns {{value, cursor, historyIndex, done?: 'submit'|'cancel'|'eof'}}
+ */
+export function applyKey(state, key) {
+  const { value, cursor, history = [], historyIndex = history.length } = state;
+  /**
+   * ⚠️ `history` IS CARRIED THROUGH, AND ITS ABSENCE WAS A REAL BUG. The first
+   * version returned only `{value, cursor, historyIndex}` — so the history array
+   * was dropped by the FIRST keystroke, and pressing Up afterwards silently did
+   * nothing. It looked like the history feature was unimplemented rather than
+   * like state was being lost, which is exactly the kind of bug a pure function
+   * makes visible and a stateful one hides.
+   */
+  const keep = (over = {}) => ({ value, cursor, history, historyIndex, draft: state.draft, ...over });
+
+  if (key === KEY.ENTER || key === KEY.NEWLINE) return keep({ done: 'submit' });
+  if (key === KEY.CTRL_C) return keep({ done: 'cancel' });
+  /**
+   * ⚠️ Ctrl-D IS EOF ONLY ON AN EMPTY LINE. On a line with text it is
+   * forward-delete — collapsing the two would exit the session when someone
+   * meant to delete a character, which is a data-loss-shaped surprise.
+   */
+  if (key === KEY.CTRL_D) {
+    if (value.length === 0) return keep({ done: 'eof' });
+    return keep({ value: value.slice(0, cursor) + value.slice(cursor + 1) });
+  }
+
+  if (key === KEY.BACKSPACE || key === KEY.BACKSPACE_ALT) {
+    if (cursor === 0) return keep();
+    return keep({ value: value.slice(0, cursor - 1) + value.slice(cursor), cursor: cursor - 1 });
+  }
+
+  if (key === KEY.CTRL_U) return keep({ value: value.slice(cursor), cursor: 0 });
+  if (key === KEY.CTRL_K) return keep({ value: value.slice(0, cursor) });
+  if (key === KEY.CTRL_A) return keep({ cursor: 0 });
+  if (key === KEY.CTRL_E) return keep({ cursor: value.length });
+
+  if (key === KEY.CTRL_W) {
+    const upto = value.slice(0, cursor);
+    const cut = upto.replace(/\s*\S+$/, '');
+    return keep({ value: cut + value.slice(cursor), cursor: cut.length });
+  }
+
+  // Arrows and Home/End arrive as escape sequences.
+  if (key === `${CSI}D`) return keep({ cursor: Math.max(0, cursor - 1) });
+  if (key === `${CSI}C`) return keep({ cursor: Math.min(value.length, cursor + 1) });
+  if (key === `${CSI}H` || key === `${CSI}1~`) return keep({ cursor: 0 });
+  if (key === `${CSI}F` || key === `${CSI}4~`) return keep({ cursor: value.length });
+  if (key === `${CSI}3~`) return keep({ value: value.slice(0, cursor) + value.slice(cursor + 1) });
+
+  /**
+   * History. ⚠️ The index may sit one PAST the end — that position is "the line
+   * I was typing", so walking up and back down returns what you had rather than
+   * silently eating it.
+   */
+  if (key === `${CSI}A`) {
+    if (historyIndex === 0 || history.length === 0) return keep();
+    const i = historyIndex - 1;
+    /**
+     * ⚠️ THE DRAFT IS SAVED ON THE WAY UP. Leaving it behind means a half-typed
+     * line is destroyed by a single Up press — the user glances at what they ran
+     * before, comes back, and their sentence is gone. Losing typed input to a
+     * navigation key is the least forgivable bug a line editor can have.
+     */
+    const draft = historyIndex === history.length ? value : state.draft;
+    return keep({ value: history[i], cursor: history[i].length, historyIndex: i, draft });
+  }
+  if (key === `${CSI}B`) {
+    if (historyIndex >= history.length) return keep({ draft: state.draft });
+    const i = historyIndex + 1;
+    const next = i === history.length ? (state.draft ?? '') : history[i];
+    return keep({ value: next, cursor: next.length, historyIndex: i, draft: state.draft });
+  }
+
+  /**
+   * ⚠️ EVERYTHING ELSE CONTROL-SHAPED IS DROPPED, NOT INSERTED. An unhandled
+   * escape sequence typed into the buffer shows the user `^[[5~` and looks like
+   * the tool is broken — the one impression a new line editor cannot afford.
+   */
+  if (key.startsWith(ESC)) return keep();
+  if (key.length === 1 && key < ' ') return keep();
+
+  return keep({ value: value.slice(0, cursor) + key + value.slice(cursor), cursor: cursor + key.length });
+}
+
+/**
+ * Split a raw chunk into keys. A paste arrives as one chunk and an arrow key as
+ * three bytes, so neither "one byte per key" nor "one chunk per key" is right.
+ */
+export function splitKeys(chunk) {
+  const s = String(chunk);
+  const keys = [];
+  for (let i = 0; i < s.length; i += 1) {
+    if (s[i] === ESC) {
+      const m = /^\x1b\[[0-9;]*[A-Za-z~]/.exec(s.slice(i));
+      if (m) { keys.push(m[0]); i += m[0].length - 1; continue; }
+    }
+    keys.push(s[i]);
+  }
+  return keys;
+}
+
+/**
+ * Draw the box and park the cursor inside it.
+ *
+ * ⚠️ THE CURSOR IS HIDDEN WHILE PAINTING. Without it, the cursor visibly darts
+ * to the end of each border as it is written — which reads as a flicker and is
+ * the difference between a rendered box and a drawn one.
+ */
+export function paint(output, state, { first = false, atRow = 0 } = {}) {
+  const { lines, cursorColumn } = renderBox(state);
+
+  /**
+   * ── ⭐⭐⭐ PINNED: DRAW AT AN ABSOLUTE ROW, NOT WHEREVER THE CURSOR IS ───────
+   *
+   * Roman, from a screenshot: *"the text is going underneath instead of above,
+   * and it makes a new box."* Two boxes on screen, output between them.
+   *
+   * The cause: `pinRegion` reserved the bottom rows but this function still drew
+   * RELATIVE to the cursor. So the box was painted inline, scrolled away with
+   * the transcript, and the next turn painted a fresh one lower down — the
+   * reserved rows sat empty while the box wandered.
+   *
+   * ⭐ When pinned, the box has a FIXED HOME. `ESC[{row};1H` puts it there every
+   * time, so output scrolling above it cannot move it and no second box can
+   * exist.
+   */
+  if (atRow > 0) {
+    const rows = lines.map((l, i) => `${CSI}${atRow + i};1H${CSI}2K${l}`).join('');
+    output.write(`${CSI}?25l${rows}${CSI}${atRow + 1};${cursorColumn}H${CSI}?25h`);
+    return;
+  }
+
+  /**
+   * ── ⚠️⚠️ THE CURSOR MATH, AND MY FIRST VERSION ATE THE SCREEN ──────────────
+   *
+   * Roman: *"it moves upwards every time you type a character then deletes the
+   * design you did."* Exactly right, and the arithmetic says why.
+   *
+   * After a paint the cursor rests on the INPUT line — line 2 of 3, not below
+   * the box. The first version began each repaint with `ESC[3A`, which is where
+   * it would be if the cursor were below. From line 2, moving up 3 lands ONE
+   * LINE ABOVE the top border — and the `ESC[0J` that follows clears from there
+   * to the bottom of the screen. So every keystroke crept upward and erased
+   * another line of the banner.
+   *
+   * ⭐ THE INVARIANT, WRITTEN DOWN BECAUSE IT IS THE WHOLE FUNCTION: this
+   * routine ENTERS with the cursor on the input line and LEAVES it there. So a
+   * repaint moves up exactly ONE line to reach the top border, and the final
+   * reposition moves up exactly one from the last line written.
+   *
+   *   ╭────────╮   <- line 1   ESC[1A from the input line reaches here
+   *   │› …      │   <- line 2   cursor lives here, in and out
+   *   ╰────────╯   <- line 3   cursor is here after writing; ESC[1A returns
+   *
+   * ⚠️ NO TRAILING NEWLINE. Writing one after the last border scrolls the
+   * viewport when the box is at the bottom of the screen, and every subsequent
+   * `up` is then off by a row for the rest of the session.
+   */
+  /**
+   * ⚠️ THE ROW MATH FOLLOWS THE ROW COUNT, and it changed when the box became a
+   * rule. With TWO rows the cursor already ends on the prompt line after the
+   * write, so there is no reposition to make — the old `ESC[1A` was correct for
+   * three rows and would now land on the RULE, one row too high, which is the
+   * same off-by-one that walked the box up the screen before.
+   */
+  const home = first ? '' : `\r${CSI}${lines.length - 1}A`;
+  output.write(
+    `${CSI}?25l${home}${CSI}0J${lines.join('\n')}` +
+    `\r${CSI}${cursorColumn}G${CSI}?25h`,
+  );
+}
+
+/**
+ * ── ⭐⭐⭐ THE ONLY PART THAT TOUCHES A TERMINAL ─────────────────────────────
+ *
+ * Reads one line inside the box. Everything decision-shaped lives in `applyKey`
+ * and `renderBox`, which are pure and fully tested; this function does nothing
+ * but move bytes and paint what they return.
+ *
+ * @returns {Promise<{value: string|null, reason: 'submit'|'cancel'|'eof'}>}
+ */
+export function readBoxedLine({ input, output, history = [], onInterrupt = null, prompt = '› ', atRow = 0 }) {
+  return new Promise((resolve) => {
+    let state = { value: '', cursor: 0, history, historyIndex: history.length, draft: '' };
+    const columns = () => output.columns ?? process.stdout.columns ?? 80;
+
+    /**
+     * ⚠️ RAW MODE IS RESTORED ON EVERY EXIT PATH, INCLUDING THE UNHAPPY ONES.
+     * A process that leaves the terminal in raw mode hands the user a shell with
+     * no echo and no line editing — they have to type `reset` blind. That is the
+     * single worst thing a CLI can do to somebody's session.
+     */
+    let finished = false;
+    const finish = (value, reason) => {
+      if (finished) return;
+      finished = true;
+      input.off('data', onData);
+      input.off('end', onEnd);
+      try { input.setRawMode?.(false); } catch { /* not a TTY any more */ }
+      if (atRow > 0) {
+        /**
+         * ── ⭐⭐⭐ PINNED: THE BOX STAYS, THE ANSWER GOES ABOVE IT ─────────────
+         *
+         * Roman, from a screenshot: *"the text is going underneath instead of
+         * above, and it makes a new box."*
+         *
+         * With a reserved region the box has a permanent home in the bottom
+         * rows. What the user typed belongs in the TRANSCRIPT, so it is echoed
+         * into the scrolling area and the box is repainted empty — one box,
+         * always in the same place, with history flowing upward past it.
+         *
+         * ⚠️ The cursor is left at the bottom of the SCROLL REGION, so whatever
+         * prints next (the reply, an MCP warning, anything) lands above the box
+         * instead of on top of it.
+         */
+        output.write(`${CSI}${atRow - 1};1H\n${prompt}${value ?? ''}\n`);
+        paint(output, { value: '', cursor: 0, columns: output.columns ?? 80 }, { atRow });
+        output.write(`${CSI}${atRow - 1};1H`);
+      } else {
+        /**
+         * ── ⚠️⚠️ UNPINNED: MOVE BELOW THE BOX BEFORE ANYTHING ELSE WRITES ────
+         *
+         * Seen in an earlier screenshot: an MCP warning printed straight ON TOP
+         * of the bottom border. The cursor rests on the INPUT line — line 2 of 3
+         * — so a bare `\n` lands it on the border row and the next write
+         * destroys it. Down one FIRST, then a newline.
+         */
+        output.write(`${CSI}1B\n`);
+      }
+      resolve({ value, reason });
+    };
+
+    const onEnd = () => finish(null, 'eof');
+
+    const onData = (chunk) => {
+      for (const key of splitKeys(chunk)) {
+        const next = applyKey(state, key);
+        if (next.done === 'submit') {
+          state = next;
+          // Repaint once so the committed line is what stays on screen.
+          paint(output, { ...state, columns: columns() }, { atRow });
+          return finish(state.value, 'submit');
+        }
+        if (next.done === 'cancel') {
+          /**
+           * ⚠️ Ctrl-C ON A NON-EMPTY LINE CLEARS IT; on an empty one it means
+           * "stop". Anything else makes the first Ctrl-C — the one people press
+           * to abandon a sentence — quit the whole session.
+           */
+          /**
+           * ⚠️⚠️ Ctrl-C NEVER ENDS THE READ — it clears the line and hands the
+           * event on. The first version finished with `cancel` on an empty line,
+           * which ended the session on the FIRST press: there was then no prompt
+           * for a second Ctrl-C to arrive at, so the "press again to quit"
+           * escape hatch could never fire. `onInterrupt` owns that decision (see
+           * `interrupt.mjs`), and it can only own it if it keeps being called.
+           *
+           * ⭐ It is also what every shell does: Ctrl-C gives you a fresh line.
+           * Quitting is `exit`, or Ctrl-D on an empty one.
+           */
+          state = { ...state, value: '', cursor: 0, historyIndex: history.length, draft: '' };
+          onInterrupt?.();
+          paint(output, { ...state, columns: columns() }, { atRow });
+          continue;
+        }
+        if (next.done === 'eof') return finish(null, 'eof');
+        state = next;
+        paint(output, { ...state, columns: columns() }, { atRow });
+      }
+    };
+
+    try { input.setRawMode?.(true); } catch { /* not a TTY */ }
+    input.resume?.();
+    paint(output, { ...state, columns: columns() }, { first: true, atRow });
+    input.on('data', onData);
+    input.once('end', onEnd);
+  });
+}
+
+/**
+ * ── ⭐⭐⭐ PINNING THE BOX TO THE BOTTOM OF THE SCREEN ───────────────────────
+ *
+ * Roman: *"we need that prompt box stuck down the bottom, it is professional."*
+ *
+ * A terminal can be told to scroll only PART of itself. `ESC[{top};{bottom}r`
+ * sets the scrolling region; everything printed scrolls inside it, and the rows
+ * below are left alone. Reserve the last three and the box never moves while
+ * output flows past above it.
+ *
+ * ── ⚠️⚠️ THE PART THAT MUST NEVER BE GOT WRONG ──────────────────────────────
+ *
+ * A process that exits WITHOUT releasing the region leaves the user with a
+ * terminal that scrolls inside a box forever, fixable only by typing `reset`
+ * blind. That is the same class of harm as leaving raw mode on, and it must be
+ * released on every path out — normal exit, Ctrl-C, SIGTERM, and an uncaught
+ * throw. `release()` is idempotent and safe to call from all of them.
+ *
+ * ⚠️ AND IT IS OPT-IN. A reserved region is a claim on somebody's whole screen;
+ * off a TTY, in CI, under a pipe or with ACUVO_NO_PIN=1 it is never set.
+ */
+export function pinRegion(output, { rows = 2, env = process.env } = {}) {
+  const height = output?.rows ?? process.stdout?.rows ?? 0;
+  const enabled = Boolean(output?.isTTY)
+    && height > rows + 4
+    && String(env.ACUVO_NO_PIN ?? '') !== '1'
+    && String(env.CI ?? '').toLowerCase() !== 'true';
+
+  if (!enabled) return { enabled: false, release() {}, rows: 0, bottom: 0 };
+
+  const bottom = height - rows;
+  let released = false;
+
+  /**
+   * ── ⚠️⚠️ CLEAR, THEN START AT THE TOP. MY FIRST VERSION STARTED AT THE BOTTOM ─
+   *
+   * Roman, from a screenshot: the banner was cut in half with a huge empty gap
+   * beneath it and the conversation crammed at the bottom of the screen.
+   *
+   * The cause: this parked the cursor at the BOTTOM of the region, so the first
+   * line printed on the last usable row and everything after it scrolled. A
+   * terminal fills downward — the transcript has to START at the top and grow
+   * toward the input, which is what every scrollback in existence does.
+   *
+   * ⚠️ AND THE SCREEN IS CLEARED FIRST. Whatever the shell left behind would
+   * otherwise sit inside our region and scroll along with the session, so the
+   * banner would never be at the top of anything.
+   */
+  output.write(`${CSI}2J${CSI}1;${bottom}r${CSI}1;1H`);
+
+  const release = () => {
+    if (released) return;
+    released = true;
+    /**
+     * ⚠️ `ESC[r` WITH NO ARGUMENTS RESETS TO THE FULL SCREEN. Then the cursor is
+     * moved below the reserved rows so the shell prompt does not land on top of
+     * our box — an exit that leaves the terminal technically correct and
+     * visually broken is still a bad exit.
+     */
+    try {
+      output.write(`${CSI}r${CSI}${height};1H\n`);
+    } catch { /* the stream may already be gone on a hard exit */ }
+  };
+
+  return { enabled: true, release, rows, bottom };
+}

package/package.json

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