@cruxy/cli 1.11.0 → 1.11.1

package/README.md

@@ -219,6 +219,7 @@ once. Reduced motion is also implied by screen-reader mode.
 | Variable              | Effect                                                                         |
 | --------------------- | ------------------------------------------------------------------------------ |
 | `CRUXY_NO_ALT_SCREEN` | Keep the full-screen TUI in the normal buffer instead of the alternate screen. |
+| `CRUXY_NO_MOUSE`      | Leave the mouse to the terminal — the wheel scrolls the window, not the pane.  |
 
 By default the TUI runs on the terminal's alternate screen — the second buffer
 `less` and `vim` use. Leaving it restores the normal buffer byte for byte, so
@@ -237,6 +238,17 @@ prefer your shell to keep the frame. It changes nothing else about the TUI, and
 it is ignored where the TUI does not run at all (a pipe, a screen reader,
 `TERM=dumb`).
 
+### The mouse
+
+While the TUI is active it turns mouse reporting on, so the wheel scrolls the
+conversation (or the selected view) the way Page Up and Page Down do, instead
+of scrolling the terminal window over a buffer that has no scrollback. The
+trade is the one `less` and `vim` make: **native text selection needs Shift
+(Option in Terminal.app) while the TUI is active.** If you select text
+constantly, set `CRUXY_NO_MOUSE=1` — the wheel goes back to the terminal, and
+nothing else about the TUI changes. It is implied off wherever the alternate
+screen is off, because the two are turned on and released as one.
+
 However cruxy exits — quit, `kill -TERM`, a hangup when the window closes, an
 uncaught error — the terminal is handed back: the frame erased, the cursor
 shown, the alternate screen left.

package/dist/agent/context.js

@@ -41,6 +41,11 @@ export function readContext(messages, budget) {
     // reserve covers the system prompt and tool schemas that `estimateTokens`
     // never sees, and omitting it here would under-report by ~4.5k tokens and let
     // the panel read "comfortable" while the seam was about to compact.
+    //
+    // It is an ALLOWANCE, not a measurement, and every renderer of `used` has
+    // to be able to say so — hence `reserve` travels with the reading. It is
+    // fixed by config: it does not grow when CRUXY.md, recalled memory, LSP,
+    // web or MCP tool schemas grow the actual request.
     const used = estimateTokens(messages) + budget.reserveTokens;
     const total = budget.maxTokens;
     return {
@@ -48,6 +53,7 @@ export function readContext(messages, budget) {
         total,
         fraction: total <= 0 ? 1 : Math.min(1, Math.max(0, used / total)),
         compactAt: Math.round(budget.compactThreshold * total),
+        reserve: budget.reserveTokens,
     };
 }
 /**

package/dist/cli/session-commands.js

@@ -63,6 +63,10 @@ export async function dispatchCommand(input, ctx) {
         return { kind: "exit" };
     if (trimmed === "/clear") {
         session.clear();
+        // The screen too, where the shell owns one. A history reset that left the
+        // old transcript on screen above its own confirmation read as a reset that
+        // had not happened — the context WAS empty; only the screen said otherwise.
+        out.clear?.();
         out.print(t.muted("history cleared"));
         return { kind: "handled" };
     }

package/dist/components/input.js

@@ -75,7 +75,7 @@ export async function readSingleKey(stdin = process.stdin) {
     const keys = createKeyReader(stdin);
     keys.begin();
     try {
-        const key = await keys.read();
+        const key = await readAnswerKey(keys);
         switch (key.kind) {
             case "char":
                 return key.char;
@@ -89,6 +89,23 @@ export async function readSingleKey(stdin = process.stdin) {
         keys.restore();
     }
 }
+/**
+ * The next key that can be an ANSWER — a wheel notch is not one.
+ *
+ * Every single-key prompt maps "anything unmapped" to the safe default (deny,
+ * cancel, no). That is right for an arrow or a function key, and wrong for the
+ * mouse wheel: with mouse reporting on (the TUI turns it on), a reader who
+ * scrolls back to check what a prompt is about would answer it "no" by doing
+ * so. The wheel is a scroll, never a reply, so it is skipped here and the
+ * prompt keeps waiting.
+ */
+export async function readAnswerKey(keys) {
+    for (;;) {
+        const key = await keys.read();
+        if (key.kind !== "wheel-up" && key.kind !== "wheel-down")
+            return key;
+    }
+}
 /** The real environment: frames to stderr, keys from stdin, caps from stderr. */
 export function defaultComponentIO() {
     // Detection resolves both axes (stderr for output, stdin for input) and their

package/dist/components/keys.js

@@ -26,6 +26,22 @@ const CBT = 0x5a;
  * not rejected, so these are matched on the leading number instead.
  */
 const TILDE = 0x7e;
+/**
+ * The two mouse encodings a terminal can answer `?1000h` with.
+ *
+ * SGR (`?1006h`, the one the TUI asks for) sends `ESC [ < Cb ; Cx ; Cy M` for
+ * a press and `… m` for a release, all in printable ASCII. A terminal that does
+ * not know SGR falls back to X10: `ESC [ M` followed by THREE RAW BYTES
+ * (button+32, column+32, row+32). The X10 form has to be recognised even though
+ * it is never requested, because the alternative is worse than an unmapped key:
+ * the generic CSI rule below would stop at the `M`, and the three bytes after
+ * it — printable, by construction — would land in the input line as text.
+ */
+const SGR_MOUSE_INTRO = 0x3c; // <
+const X10_MOUSE_FINAL = 0x4d; // M
+/** Bit 6 of the button code marks a wheel event; bit 0 says which way. */
+const MOUSE_WHEEL_FLAG = 64;
+const X10_MOUSE_PAYLOAD = 3;
 /** Leading `~`-sequence parameter → key. `ESC [ 5 ~` / `ESC [ 6 ~`. */
 const TILDES = {
     5: "page-up",
@@ -43,9 +59,10 @@ const ARROWS = {
  * keys per chunk; all are returned in order.
  *
  * Escape handling is deliberately simple: `ESC [ A..D` decodes to an arrow,
- * `ESC [ … Z` decodes to Shift+Tab, any other CSI sequence (`ESC [ …final`) is
- * swallowed whole (unmapped keys must not leak garbage chars into a query), and
- * a lone ESC decodes to `escape`. Terminals send arrow sequences atomically in practice; a sequence
+ * `ESC [ … Z` decodes to Shift+Tab, a mouse report (SGR `ESC [ < … M`, or X10
+ * `ESC [ M` + 3 bytes) decodes to a wheel notch or to nothing, any other CSI
+ * sequence (`ESC [ …final`) is swallowed whole (unmapped keys must not leak
+ * garbage chars into a query), and a lone ESC decodes to `escape`. Terminals send arrow sequences atomically in practice; a sequence
  * split across chunks degrades to `escape` + literal chars, which is safe
  * (escape cancels).
  */
@@ -56,12 +73,44 @@ export function decodeKeys(chunk) {
         const byte = buf[i];
         if (byte === ESC) {
             if (buf[i + 1] === 0x5b /* [ */) {
+                // X10 mouse: `ESC [ M` plus three raw payload bytes. Consumed as one
+                // unit BEFORE the generic CSI walk, which would otherwise treat `M` as
+                // the final byte and hand the payload to the printable branch.
+                if (buf[i + 2] === X10_MOUSE_FINAL) {
+                    const end = i + 3 + X10_MOUSE_PAYLOAD;
+                    if (end <= buf.length) {
+                        const wheel = mouseWheel(buf[i + 3] - 32);
+                        if (wheel)
+                            keys.push({ kind: wheel });
+                        i = end;
+                        continue;
+                    }
+                    // Truncated at the chunk boundary: the same degradation as any other
+                    // partial CSI — escape, and drop the tail.
+                    keys.push({ kind: "escape" });
+                    i = buf.length;
+                    continue;
+                }
                 // CSI: consume parameter/intermediate bytes (0x20–0x3f) up to the
                 // final byte (0x40–0x7e); map arrows, swallow everything else.
                 let j = i + 2;
                 while (j < buf.length && buf[j] >= 0x20 && buf[j] <= 0x3f)
                     j++;
                 if (j < buf.length) {
+                    if (buf[i + 2] === SGR_MOUSE_INTRO) {
+                        // SGR mouse: `ESC [ < Cb ; Cx ; Cy M|m`. Only the button code is
+                        // read — the wheel has no position — and a press is the only edge
+                        // a wheel has, so `m` (release) never maps to anything.
+                        let cb = 0;
+                        for (let k = i + 3; k < j && buf[k] >= 0x30 && buf[k] <= 0x39; k++) {
+                            cb = cb * 10 + (buf[k] - 0x30);
+                        }
+                        const wheel = buf[j] === X10_MOUSE_FINAL ? mouseWheel(cb) : null;
+                        if (wheel)
+                            keys.push({ kind: wheel });
+                        i = j + 1;
+                        continue;
+                    }
                     if (buf[j] === CBT) {
                         // Shift+Tab, in BOTH its forms: bare `ESC [ Z`, and the
                         // parameterized `ESC [ 1 ; 2 Z` some terminals send when a modifier
@@ -165,3 +214,17 @@ export function decodeKeys(chunk) {
     }
     return keys;
 }
+/**
+ * A mouse button code → the wheel direction it encodes, or null for any other
+ * mouse event. Modifier bits (shift 4, meta 8, ctrl 16) are masked off so a
+ * wheel with a modifier held still scrolls; the low two bits pick the direction.
+ */
+function mouseWheel(button) {
+    if ((button & MOUSE_WHEEL_FLAG) === 0)
+        return null;
+    return (button & 3) === 0
+        ? "wheel-up"
+        : (button & 3) === 1
+            ? "wheel-down"
+            : null;
+}

package/dist/config/schema.js

@@ -133,7 +133,14 @@ export const ContextConfigSchema = z
      * sees — the system prompt and every tool's JSON schema — added to the
      * measured history before the threshold test so the trigger reflects the
      * real request size, not just the visible messages. Roughly the size of
-     * the built system prompt plus the default tool catalogue today.
+     * the built system prompt plus the default tool catalogue today (about
+     * 3.7k measured for the prompt and 14 tool schemas).
+     *
+     * An ALLOWANCE, not a measurement — the context panel and `/context` say
+     * so. It is the same number on every turn, so it does not track the parts
+     * of a request that vary: CRUXY.md, recalled memory, LSP context, web
+     * results and MCP tool schemas all make the real request larger without
+     * moving it. Raise it if a project carries a lot of those.
      */
     reserveTokens: z.number().int().nonnegative().default(4500),
     /** Most-recent messages always kept verbatim (a floor; the cut rounds up to

package/dist/render/context-view.js

@@ -26,7 +26,11 @@ import { fit } from "./layout.js";
  *
  * The reserve is shown as its own row rather than folded into a total. It is
  * part of `used`, it is present in no message, and a breakdown that omitted it
- * would leave several thousand tokens looking unexplained.
+ * would leave several thousand tokens looking unexplained. It is labelled an
+ * ALLOWANCE (cli#4): a fixed config value standing in for the system prompt and
+ * tool schemas, not a measurement of them — and the row under it names the two
+ * ways the figure is actually inaccurate, so nobody has to discover them by
+ * being compacted early.
  */
 /** `~34k`, `~900` — the leading tilde is not decoration. See the module note. */
 function approx(n) {
@@ -68,8 +72,13 @@ export function contextReportLines(report, t, width = Infinity) {
     }
     // Named separately because it is real, unavoidable, and in no message — the
     // one part of the figure a user cannot shrink by pruning the conversation.
-    lines.push(`  ${"reserve".padEnd(13)} ${approx(report.reserveTokens).padStart(7)} ` +
-        t.muted("       system prompt + tool schemas"));
+    // And named as what it is: a fixed allowance, not a count. The two lines
+    // after it are the honest footnote — what the allowance does not track, and
+    // what the denominator is not.
+    lines.push(`  ${"allowance".padEnd(13)} ${approx(report.reserveTokens).padStart(7)} ` +
+        t.muted("       system prompt + tool schemas (a fixed setting, not measured)"));
+    lines.push(t.muted("  the allowance does not grow with CRUXY.md, memory, LSP, web or MCP schemas,"));
+    lines.push(t.muted("  and the budget is context.maxTokens — a config heuristic, not a limit read from the served tier"));
     // ── the biggest single messages ───────────────────────────────────────────
     if (report.largest.length > 0) {
         lines.push("");

package/dist/render/index.js

@@ -8,7 +8,7 @@ import { TtyRenderer } from "./tty-renderer.js";
 import { TuiRenderer } from "../tui/renderer.js";
 import { GitStatusCache } from "../tui/git-status.js";
 import { ToolVersions } from "../tui/tool-versions.js";
-import { supportsTui, usesAltScreen } from "../tui/supports.js";
+import { supportsTui, usesAltScreen, usesMouse } from "../tui/supports.js";
 export { detectCapabilities, detectReducedMotion, resolveColumns, resolveRows, DEFAULT_COLUMNS, DEFAULT_ROWS, } from "./capabilities.js";
 export { attachResize, processResizeSignal, } from "./resize.js";
 export { fit, fitMiddle, reflow, stripAnsi, visibleWidth, kvStack, MIN_VALUE_COLS, } from "./layout.js";
@@ -58,6 +58,7 @@ export function createRenderer(out = process.stdout, err = process.stderr, env =
             // for a direct construction and wrong here: an injected env exists
             // precisely so a caller can describe a terminal that is not this one.
             altScreen: usesAltScreen(caps, env),
+            mouse: usesMouse(caps, env),
         });
     }
     return caps.cursor

package/dist/tui/app.js

@@ -3,13 +3,14 @@ import { completeLine } from "../components/autocomplete.js";
 import { SHARED_COMMANDS, SHARED_HELP, announceMode, dispatchCommand, } from "../cli/session-commands.js";
 import { TUI_ONLY_COMMANDS } from "../cli/command-catalog.js";
 import { selectList } from "../components/select.js";
-import { viewLabel, viewOrder } from "./views.js";
+import { CONVERSATION_VIEW, viewLabel, viewOrder } from "./views.js";
 import { canOverlay, createKeyLease, createOverlayIO, } from "./overlay.js";
 import { ModeRing } from "./mode-ring.js";
 import { openPalette } from "./palette.js";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
 import { CLOSABLE_PANELS, columnOf, RAIL_PANELS, } from "./layout.js";
 import { COLUMN_LABELS, PANEL_LABELS } from "./panels.js";
+import { WHEEL_LINES } from "./renderer.js";
 /**
  * The TUI's input loop (P1) — the piece that replaces `repl.ts`'s readline
  * loop. It owns exactly two things: the edit buffer and command dispatch.
@@ -59,7 +60,10 @@ const HELP = [
     "  Ctrl+K           open the command palette",
     "  Ctrl+B           focus the sidebar nav (arrows switch view, Esc leaves)",
     "  Shift+Tab        cycle mode (manual · auto-approve · plan · full-auto)",
-    "  PgUp / PgDn      scroll the pane; Esc returns to the live view",
+    "  PgUp / PgDn      scroll the pane (the mouse wheel does too; to select",
+    "                   text hold Shift — Option in Terminal.app — or set",
+    "                   CRUXY_NO_MOUSE=1 to give the wheel back to the terminal)",
+    "  Esc              back to the live view, then back to the conversation",
     "  Ctrl+D           leave cruxy",
 ];
 /**
@@ -177,6 +181,10 @@ async function readLine(keys, renderer, hooks) {
                     // answering into a pane they cannot see is the one case where holding
                     // still is wrong.
                     renderer.scrollToLive();
+                    // And clears the last command's output from under a view (cli#7b):
+                    // what this line produces must not stack beneath what the last one
+                    // did. It is all still in the conversation.
+                    renderer.dismissNotices();
                     paint();
                     return text;
                 }
@@ -282,12 +290,23 @@ async function readLine(keys, renderer, hooks) {
                     // schedules its own repaint for the rows that did.
                     renderer.scrollPage(key.kind === "page-up" ? 1 : -1);
                     break;
+                case "wheel-up":
+                case "wheel-down":
+                    // The mouse wheel (cli#1) is the same scroll at a finer grain. It
+                    // only arrives because the renderer turned mouse reporting on; the
+                    // terminal would otherwise have scrolled its own window (Terminal.app)
+                    // or sent arrows this loop ignores (iTerm2).
+                    renderer.scrollBy(key.kind === "wheel-up" ? WHEEL_LINES : -WHEEL_LINES);
+                    break;
                 case "escape":
-                    // Esc leaves the scrolled view — a mode needs a visible exit, and the
-                    // notice names this key. It stays inert at the live tail rather than
-                    // being claimed unconditionally, so the binding remains free for
-                    // whatever a later track wants Esc to mean when nothing is scrolled.
-                    renderer.scrollToLive();
+                    // Esc peels one layer (cli#7b): out of scrollback first — a mode
+                    // needs a visible exit, and the notice names this key — and, at the
+                    // live tail, out of a view and back to the conversation. Two presses
+                    // from anywhere reach the home position; each one is a step the
+                    // screen can show. Inert at the conversation's live tail, so the
+                    // binding stays free for whatever a later track wants it to mean.
+                    if (!renderer.scrollToLive())
+                        renderer.setView(CONVERSATION_VIEW);
                     break;
                 case "ctrl-b":
                     // Take the keyboard to the sidebar nav (P7 track 2). Refused when the
@@ -485,6 +504,10 @@ export async function runTui(session, renderer, opts = {}) {
         print: (line = "") => renderer.println(line),
         theme: renderer.theme,
         fit: (line) => line,
+        // `/clear` (cli#2): the TUI owns its scrollback, so a cleared history is
+        // also a cleared screen. The REPL has no equivalent — its transcript is the
+        // terminal's own scrollback, which is not the CLI's to erase.
+        clear: () => renderer.clearScrollback(),
     };
     // The mode ring (Q5). The chip follows every press; the session is told once,
     // when the presses stop — see `mode-ring.ts` for why passing through a mode is

package/dist/tui/approval-overlay.js

@@ -1,3 +1,4 @@
+import { readAnswerKey } from "../components/input.js";
 import { themeForColor } from "../theme/index.js";
 /**
  * The approval prompt as an in-viewport modal (P5 track 2).
@@ -88,7 +89,9 @@ export function createOverlayPromptIO(surface, lease, color) {
             paint();
         },
         async readKey() {
-            const key = await read(keys);
+            // A wheel notch scrolls the conversation behind the drawer; it is not an
+            // answer, and mapping it to "" would deny the action being asked about.
+            const key = keys === null ? await read(keys) : await readAnswerKey(keys);
             return keyToChar(key);
         },
         /**

package/dist/tui/layout.js

@@ -124,6 +124,28 @@ export function fitBlock(lines, rows, width) {
         out.push(" ".repeat(Math.max(0, width)));
     return out;
 }
+/**
+ * Take the FIRST `rows` lines of a block and pad it to exactly that many rows —
+ * the mirror of {@link fitBlock}, for a column whose top is the part that must
+ * survive.
+ *
+ * The sidebar is that column (cli#7a). It opens with the view nav: a heading
+ * and one row per view, fixed-height, and NAVIGABLE — Ctrl+B puts the keyboard
+ * on it, and the arrows move a pointer down its rows. `fitBlock`'s tail rule
+ * applied to that column ate the heading and the first four view rows at 30
+ * rows, which left Ctrl+B moving a pointer the screen never showed. Nothing
+ * at the bottom of the sidebar is worth that: the session list below the nav
+ * is composed to its own budget by the renderer (see `sidebarLines`), so what
+ * reaches here already fits, and when it does not — a terminal too short for
+ * the nav itself — the rows to lose are the last ones, not the first.
+ */
+export function fitHead(lines, rows, width) {
+    const head = lines.length > rows ? lines.slice(0, Math.max(0, rows)) : lines;
+    const out = head.map((l) => padTo(l, width));
+    while (out.length < rows)
+        out.push(" ".repeat(Math.max(0, width)));
+    return out;
+}
 /**
  * Window `rows` lines out of a block, `offset` display lines up from the end
  * (P7 track 1). `offset === 0` is the tail view {@link fitBlock} gives, and the
@@ -293,8 +315,10 @@ export function composeScreen(vm, width, height, open, theme) {
     const drawer = fitOverlay(vm.overlay ?? [], overlayRows(height));
     const columnRows = Math.max(1, rows - drawer.length);
     const columns = [];
+    // HEAD-fitted, not tail: the sidebar is a nav over a list, and the nav is the
+    // part that has to be on screen — see `fitHead`. `main` stays a tail view.
     if (budget.sidebar > 0)
-        columns.push(fitBlock(vm.sidebar, columnRows, budget.sidebar));
+        columns.push(fitHead(vm.sidebar, columnRows, budget.sidebar));
     columns.push(fitBlock(vm.main, columnRows, budget.main));
     if (budget.rail > 0)
         columns.push(fitBlock(vm.rail, columnRows, budget.rail));

package/dist/tui/panels.js

@@ -50,22 +50,44 @@ function title(text, theme) {
  * The column is narrow (18 columns), so each session takes two lines: its short
  * id and age, then its title. The layout truncates per line, which keeps the id
  * — the part you would type into `--resume` — always fully visible.
+ *
+ * `rows` is the HEIGHT budget (cli#7a), and the list is fitted to it here the
+ * way `stackPanels` fits the rail: whole sessions, newest first, and a count of
+ * what did not fit rather than a session cut in half or silently absent. The
+ * list sits under the view nav, which is fixed-height and keyboard-driven, so
+ * it is the list that yields — and because it is newest-first, the rows to
+ * yield are at the END. The old tail-fit lost the nav heading and the newest
+ * sessions at once, which is the wrong end of both blocks.
  */
-export function sidebarLines(theme, sessions = [], activeSessionId, now = Date.now()) {
+export function sidebarLines(theme, sessions = [], activeSessionId, now = Date.now(), rows = Infinity) {
+    if (rows <= 0)
+        return [];
     const lines = title("sessions", theme);
     if (sessions.length === 0) {
         lines.push(theme.muted("no saved sessions"));
         lines.push(theme.muted("for this project yet."));
-        return lines;
+        return lines.slice(0, rows);
     }
-    for (const s of sessions) {
+    // Rows left for sessions after the title. Each session costs two, and when
+    // not all fit, one row is charged for the notice BEFORE deciding how many do
+    // — reserving it afterwards could evict a session just counted as shown.
+    const room = Math.max(0, rows - lines.length);
+    const fitsWhole = sessions.length * 2 <= room;
+    const shown = fitsWhole
+        ? sessions.length
+        : Math.max(0, Math.floor((room - 1) / 2));
+    for (const s of sessions.slice(0, shown)) {
         const active = s.sessionId === activeSessionId;
         const mark = active ? theme.accent(theme.glyph.pointer) : " ";
         const head = `${mark} ${shortId(s.sessionId)} ${relativeAge(s.updatedAt, now)}`;
         lines.push(active ? theme.strong(head) : head);
         lines.push(theme.muted(`  ${s.title}`));
     }
-    return lines;
+    if (!fitsWhole && room > 0) {
+        const hidden = sessions.length - shown;
+        lines.push(theme.muted(`${theme.glyph.ellipsis}${hidden} more session${hidden === 1 ? "" : "s"}`));
+    }
+    return lines.slice(0, rows);
 }
 /** A panel with no state yet: says so, rather than inventing a plausible value. */
 function pending(theme) {
@@ -236,19 +258,35 @@ function shortTokens(n) {
  *
  * The compaction threshold is shown because it is the only actionable thing
  * here: it says when the CLI will start folding history away.
+ *
+ * THE ALLOWANCE IS NAMED (cli#4). `used` includes `context.reserveTokens` — a
+ * fixed 4,500 by default — because the compaction seam adds it, and the panel
+ * must measure what the seam measures. But shown as a bare figure it read as
+ * consumption: an empty session opened at "~5k / 100k", as if something had
+ * already been spent. Nothing had. The constant is a fair size for what it
+ * stands in for (the system prompt plus the default tool catalogue measure
+ * about 3.7k), and it is an ALLOWANCE, not a reading: it does not move when
+ * CRUXY.md, memory recall, LSP, web or MCP schemas make the real request
+ * larger. The second row says so, in the room a 24-column strip has.
  */
 export function contextPanelLines(theme, reading) {
     if (reading === undefined) {
         return [theme.muted(`measuring${theme.glyph.ellipsis}`)];
     }
-    const { used, total, compactAt } = reading;
+    const { used, total, compactAt, reserve } = reading;
     const figure = `~${shortTokens(used)} / ${shortTokens(total)} budget`;
     // Past the threshold the next turn compacts, which is worth flagging — but as
     // a statement of what happens next, not as an alarm about a guessed number.
     // Compared on `used`, not the clamped fraction: the clamp is for display, and
     // a history that has overrun the budget must not compare as merely "at" it.
     const style = used >= compactAt ? theme.warning : theme.strong;
-    return [style(figure), theme.muted(`compacts at ${shortTokens(compactAt)}`)];
+    return [
+        style(figure),
+        ...(reserve === undefined || reserve <= 0
+            ? []
+            : [theme.muted(`incl. ~${shortTokens(reserve)} allowance`)]),
+        theme.muted(`compacts at ${shortTokens(compactAt)}`),
+    ];
 }
 /** The opening lines of the main column, before any turn has run. */
 export function mainWelcome(theme, hint) {

package/dist/tui/renderer.js

@@ -13,7 +13,8 @@ import { CONVERSATION_VIEW, cycleView, navLines, } from "./views.js";
 import { contextPanelLines, gitPanelLines, headerModel, mainWelcome, modelPanelLines, railBlocks, sidebarLines, toolsPanelLines, } from "./panels.js";
 import { limitsPanelLines } from "./limits-panel.js";
 import { installScreenGuard, } from "./restore.js";
-import { usesAltScreen } from "./supports.js";
+import { usesAltScreen, usesMouse } from "./supports.js";
+import { logger } from "../utils/logger.js";
 /**
  * The full-viewport renderer (P1) — the fourth {@link StreamRenderer}, and the
  * only one that owns the whole screen rather than a single managed line.
@@ -46,8 +47,31 @@ import { usesAltScreen } from "./supports.js";
  * `renderInput`): the real cursor parks wherever the last painted row ended,
  * which is a second, wrong caret blinking somewhere in the frame.
  */
-const ENTER_ALT_SCREEN = "\x1b[?1049h\x1b[?25l";
-const LEAVE_ALT_SCREEN = "\x1b[?25h\x1b[?1049l";
+export const ENTER_ALT_SCREEN = "\x1b[?1049h\x1b[?25l";
+export const LEAVE_ALT_SCREEN = "\x1b[?25h\x1b[?1049l";
+/**
+ * Mouse reporting on and off (cli#1): `?1000h` (button events) in the
+ * `?1006h` (SGR) encoding, and the inverse in reverse order.
+ *
+ * Without it the terminal handles the wheel itself, and on the alternate
+ * screen that means one of two wrong things: Terminal.app scrolls the WINDOW
+ * over a buffer that has no scrollback, and iTerm2 translates each notch into
+ * arrow keys, which `app.ts` deliberately leaves inert. With it, a notch
+ * arrives as a key the loop can map onto the scroll Page Up already has.
+ *
+ * WRITTEN IN THE SAME BYTES as the alternate-screen pair — appended to the
+ * enter, prepended to the leave — and nowhere else, because of what it costs
+ * when left on: a terminal in mouse-reporting mode after the process is gone
+ * turns every click into escape bytes at the shell prompt. That pair is what
+ * the restore guard replays on a signal, so the mouse is released on exactly
+ * the paths the screen is.
+ *
+ * The known trade is that native text selection needs the terminal's modifier
+ * (Shift, or Option in Terminal.app) while the TUI is up — the trade `less` and
+ * `vim` make. `CRUXY_NO_MOUSE` opts out of just this (see `usesMouse`).
+ */
+export const MOUSE_ON = "\x1b[?1000h\x1b[?1006h";
+export const MOUSE_OFF = "\x1b[?1006l\x1b[?1000l";
 /** Coalescing window for repaints (~30fps). */
 export const PAINT_INTERVAL_MS = 33;
 /**
@@ -82,6 +106,19 @@ export const VIEW_PULSE_MS = 500;
 export const SCROLLBACK_LINES = 1_000;
 /** Lines a Page Up/Down keeps in common across the jump, so context survives. */
 export const SCROLL_PAGE_OVERLAP = 2;
+/**
+ * Display lines one wheel notch scrolls (cli#1). Three is what most terminals
+ * and pagers move per notch; a whole page per notch would make the wheel a
+ * coarser Page Up rather than the fine control it is everywhere else.
+ */
+export const WHEEL_LINES = 3;
+/**
+ * The most rows a view gives up to command output pinned beneath it (cli#7b),
+ * as a fraction of the pane. Half: the view stays readable, and `/help` — the
+ * longest thing this carries — still shows most of itself, with the notice row
+ * saying where the rest is.
+ */
+export const NOTICE_ROWS_FRACTION = 0.5;
 export class TuiRenderer {
     caps;
     theme;
@@ -95,6 +132,8 @@ export class TuiRenderer {
     guard;
     /** Whether this renderer took the alternate screen and owes the inverse. */
     altScreen;
+    /** Whether it turned mouse reporting on with it, and owes that inverse too. */
+    mouse;
     /** Lines the opening banner occupies — the buffer's contents at construction. */
     openingLines;
     /** Logical lines committed since construction, INCLUDING ones rolled off. */
@@ -130,6 +169,15 @@ export class TuiRenderer {
     views = [];
     /** Which view owns the main column. Always a real id — see {@link setView}. */
     selectedView = CONVERSATION_VIEW;
+    /**
+     * App-authored lines printed while a view other than the conversation owned
+     * the main column (cli#7b), pinned under that view until the user moves on.
+     * Every one of them is ALSO in the scrollback: this is a second showing, not
+     * a second home. Empty whenever the conversation is selected.
+     */
+    notices = [];
+    /** Hands the console back to the logger; see the constructor. */
+    releaseLogger = null;
     /** Whether the sidebar nav holds the keyboard rather than the input line. */
     sidebarFocused = false;
     /** Working-tree state for the git panel (P4 track 2); absent → panel unwired. */
@@ -205,8 +253,9 @@ export class TuiRenderer {
         // The inverse is owed from this line onward, which is why track 1 landed
         // first: `close()` is not the only way out of this constructor's reach.
         this.altScreen = opts.altScreen ?? usesAltScreen(caps);
+        this.mouse = this.altScreen && (opts.mouse ?? usesMouse(caps));
         if (this.altScreen)
-            out.write(ENTER_ALT_SCREEN);
+            out.write(ENTER_ALT_SCREEN + (this.mouse ? MOUSE_ON : ""));
         // ABSOLUTE rows (Q4 track 2). This renderer owns the viewport outright, so
         // it has no reason to infer where its rows are from where the cursor was
         // left — and every reason not to. A frame this tall repaints thirty times a
@@ -216,6 +265,16 @@ export class TuiRenderer {
         this.frame = createFrame((text) => this.out.write(text), caps, {
             absolute: true,
         });
+        // THE LOGGER WRITES INTO THIS FRAME from here on (cli#1, the second
+        // contributor). Both standard streams are this terminal, and a diagnostic
+        // written to stderr while the frame owns every row lands inside it: the
+        // retention notice at boot did, and a hook's or an MCP server's warning
+        // mid-turn does. Routed through `println` they are conversation lines —
+        // visible, scrollable, and pinned under a view like any other command
+        // output — instead of bytes the next repaint erases. Released with the
+        // screen, in `releaseScreen`, so the exit path's own prints reach the
+        // normal buffer.
+        this.releaseLogger = logger.capture((_channel, text) => this.println(text));
         // Installed here, not in `close()`'s vicinity, because the window it covers
         // opens with the first paint: from this line on there is a shell on screen
         // that only this object knows how to take down.
@@ -414,9 +473,24 @@ export class TuiRenderer {
             return true;
         this.selectedView = id;
         this.scrollOffset = 0;
+        // Notices belong to the view they were pinned under. Leaving it — for the
+        // conversation, which holds them all anyway, or for another view — drops
+        // them, so a "showing git" cannot follow the user onto the tasks pane.
+        this.notices = [];
         this.schedulePaint();
         return true;
     }
+    /**
+     * Drop the command output pinned under the selected view (cli#7b). The app
+     * calls this when a line is submitted: the user has moved on, and the next
+     * command's output must not stack under the last one's.
+     */
+    dismissNotices() {
+        if (this.closed || this.notices.length === 0)
+            return;
+        this.notices = [];
+        this.schedulePaint();
+    }
     /** Move `steps` around the view ring and select what lands. */
     cycleView(steps) {
         const next = cycleView(this.selectedView, this.views, steps);
@@ -561,11 +635,42 @@ export class TuiRenderer {
     overlayWidth() {
         return this.viewportWidth();
     }
-    /** Append an app-authored line to the conversation (help text, command replies). */
+    /**
+     * Append an app-authored line to the conversation (help text, command
+     * replies, a routed diagnostic).
+     *
+     * WHILE A VIEW HIDES THE CONVERSATION the line is also pinned under that view
+     * (cli#7b). Before this, `/help`, `/view`'s listing, a Tab completion's
+     * suggestions and the "showing …" confirmation all went into a buffer the
+     * screen was not showing, and the command read as having done nothing. The
+     * conversation stays the record; the view keeps the column; the line is
+     * simply shown where the user is looking.
+     */
     println(line = "") {
         if (this.closed)
             return;
         this.pushLines([line]);
+        if (this.selectedView !== CONVERSATION_VIEW)
+            this.notices.push(line);
+        this.schedulePaint();
+    }
+    /**
+     * Empty the scrollback (cli#2) — the visible half of `/clear`.
+     *
+     * `Session.clear` empties the history the model sees and the log records the
+     * event, and both were always right. What stayed wrong was the screen: the
+     * whole transcript remained above a muted "history cleared", so a reset that
+     * had worked read as one that had not. The buffer goes, the partial line
+     * goes, the scroll position goes; `committed` stays, because the exit tail's
+     * "N earlier lines" counts what was ever shown, and these were.
+     */
+    clearScrollback() {
+        if (this.closed)
+            return;
+        this.buffer = [];
+        this.partial = "";
+        this.notices = [];
+        this.scrollOffset = 0;
         this.schedulePaint();
     }
     // ── StreamRenderer ────────────────────────────────────────────────────────
@@ -880,12 +985,16 @@ export class TuiRenderer {
      * handed over.
      */
     releaseScreen() {
+        // The console comes back first, so anything the exit path logs after this
+        // line reaches the terminal rather than a renderer that is closing.
+        this.releaseLogger?.();
+        this.releaseLogger = null;
         this.closed = true;
         this.frame.clear();
         // The exact inverse of the constructor's pair, and the last bytes this
         // renderer ever writes to the managed screen.
         if (this.altScreen)
-            this.out.write(LEAVE_ALT_SCREEN);
+            this.out.write((this.mouse ? MOUSE_OFF : "") + LEAVE_ALT_SCREEN);
     }
     /**
      * Echo the tail of the conversation into the normal buffer (Q4 track 3).
@@ -1306,10 +1415,21 @@ export class TuiRenderer {
         // A view's lines are reflowed here rather than trusted at `mainCols`: the
         // contract asks a view to lay out to the width it is given, and reflow makes
         // that a courtesy rather than a rule it can break the grid by ignoring.
+        //
+        // Command output pinned under a view (cli#7b) rides the same rule the plan
+        // checklist does under the conversation: appended, so the column's tail
+        // rule keeps it on screen, and capped so it cannot evict the view. When the
+        // cap cuts it, the first pinned row says how much is above and where it
+        // all is — the conversation, one Esc away. Absent while scrolled, like the
+        // plan, so a reader holding history still is not moved by it.
+        const notices = active === undefined || scrolled ? [] : this.noticeBlock(rows, mainCols);
         const body = active !== undefined
-            ? active
-                .lines(this.theme, mainCols)
-                .flatMap((line) => (line === "" ? [""] : reflow(line, mainCols)))
+            ? [
+                ...active
+                    .lines(this.theme, mainCols)
+                    .flatMap((line) => (line === "" ? [""] : reflow(line, mainCols))),
+                ...(notices.length === 0 ? [] : ["", ...notices]),
+            ]
             : plan.length === 0
                 ? wrapped
                 : [...wrapped, "", ...plan];
@@ -1337,11 +1457,13 @@ export class TuiRenderer {
             // one because they answer different questions — "where am I" and "what
             // else have I run" — and because the sessions list is destined to become
             // a view of its own, at which point this reduces to the nav.
-            sidebar: [
-                ...navLines(this.theme, this.views, this.selectedView, this.sidebarFocused),
-                "",
-                ...sidebarLines(this.theme, this.sessions, this.activeSessionId),
-            ],
+            //
+            // Composed to the row budget HERE (cli#7a), the way the rail is: the nav
+            // takes what it needs, the list gets what is left. Handing the layout an
+            // over-long column and letting its tail rule cut it was what removed the
+            // nav heading and the first view rows at 30 rows — and with them the
+            // pointer Ctrl+B was moving.
+            sidebar: this.sidebarBlock(rows),
             main,
             rail: stacked.lines,
             status: this.statusLine(width),
@@ -1349,6 +1471,57 @@ export class TuiRenderer {
             overlay: drawer,
         };
     }
+    /**
+     * The sidebar column, fitted to `rows` (cli#7a): the nav whole, then the
+     * session list in whatever remains, with one blank row between them when
+     * there is room for both. The nav is never cut here — `fitHead` in the
+     * layout trims it only on a terminal too short to hold it at all.
+     */
+    sidebarBlock(rows) {
+        const nav = navLines(this.theme, this.views, this.selectedView, this.sidebarFocused);
+        const remaining = rows - nav.length - 1;
+        if (remaining <= 0)
+            return nav;
+        return [
+            ...nav,
+            "",
+            ...sidebarLines(this.theme, this.sessions, this.activeSessionId, Date.now(), remaining),
+        ];
+    }
+    /**
+     * The pinned command output for the selected view, wrapped at the column
+     * width and capped at {@link NOTICE_ROWS_FRACTION} of the pane. The cap
+     * keeps the NEWEST rows — the most recent command's output is the one just
+     * asked for — and charges its first row to say what was cut.
+     */
+    noticeBlock(rows, cols) {
+        if (this.notices.length === 0)
+            return [];
+        const wrapped = [];
+        for (const line of this.notices) {
+            if (line === "")
+                wrapped.push("");
+            else
+                wrapped.push(...reflow(line, cols));
+        }
+        const cap = Math.max(1, Math.floor(rows * NOTICE_ROWS_FRACTION));
+        if (wrapped.length <= cap)
+            return wrapped;
+        const shown = Math.max(0, cap - 1);
+        const hidden = wrapped.length - shown;
+        return [
+            noticeOverflow(hidden, this.theme),
+            ...wrapped.slice(wrapped.length - shown),
+        ];
+    }
+}
+/**
+ * The heading row a pinned-notice block spends when it cannot show every line.
+ * Short enough to survive the narrowest main column (36 at 80 wide with both
+ * side columns up): a marker truncated mid-word would not name the way out.
+ */
+function noticeOverflow(hidden, theme) {
+    return theme.muted(`${theme.glyph.ellipsis}${hidden} more above${theme.sep}Esc to see all`);
 }
 /** Row-wise equality for overlay content — `null` and `[]` both mean "no drawer". */
 function sameLines(a, b) {

package/dist/tui/supports.js

@@ -40,3 +40,18 @@ export function supportsTui(caps) {
 export function usesAltScreen(caps, env = process.env) {
     return supportsTui(caps) && !isSet(env.CRUXY_NO_ALT_SCREEN);
 }
+/**
+ * Whether the TUI turns MOUSE REPORTING on (cli#1), so the wheel scrolls the
+ * pane instead of the terminal's window.
+ *
+ * Gated on {@link usesAltScreen}: the mouse is enabled and released in the
+ * same byte pair as the alternate screen, and there is no pair to ride without
+ * it. `CRUXY_NO_MOUSE` opts out on its own, same set-and-non-empty rule,
+ * because reporting has a cost the alternate screen does not: while it is on,
+ * native text selection needs the terminal's modifier (Shift, or Option in
+ * Terminal.app). Someone who selects text constantly can turn the wheel off
+ * without giving up the TUI.
+ */
+export function usesMouse(caps, env = process.env) {
+    return usesAltScreen(caps, env) && !isSet(env.CRUXY_NO_MOUSE);
+}

package/dist/utils/logger.js

@@ -1,3 +1,4 @@
+import { format } from "node:util";
 import { shouldUseColor } from "../errors/format.js";
 import { themeForColor } from "../theme/index.js";
 export const LOG_LEVELS = ["debug", "info", "warn", "error", "silent"];
@@ -12,6 +13,48 @@ class Logger {
     level = "info";
     /** Diagnostics go to stderr, so the theme resolves against stderr's color. */
     theme = themeForColor(shouldUseColor(process.stderr));
+    /** The surface that currently owns the terminal, or null for the console. */
+    sink = null;
+    /**
+     * Route every line through `sink` instead of the console, until the returned
+     * release is called.
+     *
+     * This exists for the full-screen TUI. While it is up, the frame owns every
+     * row of the terminal and BOTH standard streams point at that same terminal —
+     * so a `warn` written to stderr does not go "to the side", it lands inside
+     * the frame at wherever the cursor was parked, and the next repaint erases
+     * it. The retention notice at boot, a hook's announcement and an MCP server's
+     * failure mid-turn all did exactly that. The renderer installs itself here
+     * for as long as it holds the screen and hands the console back when it
+     * releases it, on the clean path and the signal path alike.
+     *
+     * The level filter still applies: a captured `debug` is dropped at the
+     * default level just as an uncaptured one is. Only the destination changes.
+     *
+     * The release is a no-op once a later capture has replaced this one, so two
+     * surfaces releasing out of order cannot strand the console.
+     */
+    capture(sink) {
+        this.sink = sink;
+        return () => {
+            if (this.sink === sink)
+                this.sink = null;
+        };
+    }
+    /** Whether a surface has captured the streams. */
+    captured() {
+        return this.sink !== null;
+    }
+    emit(channel, args) {
+        if (this.sink !== null) {
+            this.sink(channel, format(...args));
+            return;
+        }
+        if (channel === "print")
+            console.log(...args);
+        else
+            console.error(...args);
+    }
     setLevel(level) {
         this.level = level;
     }
@@ -23,23 +66,26 @@ class Logger {
     }
     debug(...args) {
         if (this.enabled("debug"))
-            console.error(this.theme.muted("debug"), ...args);
+            this.emit("debug", [this.theme.muted("debug"), ...args]);
     }
     info(...args) {
         if (this.enabled("info"))
-            console.error(...args);
+            this.emit("info", args);
     }
     warn(...args) {
         if (this.enabled("warn"))
-            console.error(this.theme.warning("warn"), ...args);
+            this.emit("warn", [this.theme.warning("warn"), ...args]);
     }
     error(...args) {
         if (this.enabled("error"))
-            console.error(this.theme.danger("error"), ...args);
+            this.emit("error", [this.theme.danger("error"), ...args]);
     }
-    /** Primary user-facing output — always written to stdout. */
+    /**
+     * Primary user-facing output — stdout, or the capturing surface while one
+     * holds the screen (stdout IS that screen).
+     */
     print(...args) {
-        console.log(...args);
+        this.emit("print", args);
     }
 }
 export const logger = new Logger();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "1.11.0",
+  "version": "1.11.1",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {