acuvo-code 0.5.0 → 0.5.1

package/lib/chat.mjs

@@ -425,6 +425,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,447 @@
-/**
- * ── ⭐⭐⭐ 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, 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, 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.
+   */
+  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 = '› ', 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 = 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 };
+}

package/package.json

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