@aragon-agent/cli 0.6.31 → 0.6.33

package/dist/ui/scrollback/canvas.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Canvas arithmetic for native-scroll mode (tui-canvas-bottom-anchor §5.3).
+ *
+ * The defect this exists for: the bottom anchor of
+ * `tui-bottom-anchored-live-region` pinned the live region to the last two rows by
+ * prepending `pad` blank rows to the region's own block, so the blank space of a
+ * conversation that does not fill the screen sat BETWEEN the newest printed row and
+ * the composer. The user sees a reply that is not attached to the input box.
+ *
+ * The fix is a position change, not a value change: every row above the parked row
+ * becomes a CANVAS the writer owns, laid out top-down as `[gap][content][region]`.
+ * The blank space therefore lives ABOVE every visible content row, and the newest
+ * content row always touches the top row of the live region. The steady state is
+ * unchanged: `gap` equals the old `pad` row for row (the screen holds the same
+ * number of content rows either way).
+ *
+ * EVERYTHING HERE IS PURE: no I/O, no terminal, no clock, no `node:*` import. The
+ * writer's state machine decides which measurement is authoritative; this module
+ * only does the arithmetic, so the arithmetic can be property-tested over every
+ * combination instead of being sampled through a screen.
+ */
+/**
+ * How far the canvas may reach and how tall it may be, as far as anything measured.
+ *
+ * `pinned` carries BOTH numbers because they are not independent: the writer parks
+ * the cursor on the last row, so `top + capacity === rows - 1` at all times
+ * (invariant LB-3). Storing one and deriving the other is what makes an off-by-one
+ * invisible until a blank row lands in the scrollback.
+ */
+export type CanvasAnchor = {
+    kind: 'unknown';
+} | {
+    kind: 'pinned';
+    top: number;
+    capacity: number;
+};
+/** Nothing measured yet: the pre-canvas append path, byte for byte (I-A3 / I-A8). */
+export declare const UNKNOWN_CANVAS: CanvasAnchor;
+/** Where a `pinned` anchor came from; `/perf` reports it so a fallback is visible. */
+export type AnchorSource = 'probe' | 'fill' | 'none';
+export interface CanvasLayoutInput {
+    /** Rows the canvas may occupy, as measured (`rows - top`). */
+    capacity: number;
+    /** Canvas top row (0-based). */
+    top: number;
+    /** Content rows already on screen. */
+    heldRows: number;
+    /** Content rows arriving in this batch. */
+    statRows: number;
+    /** Height of the live region in this batch. */
+    frameRows: number;
+    /** 1 when the batch is a re-seed and starts with its own CRLF, else 0. */
+    lead: number;
+}
+/** The whole geometry of one batch, as pure numbers (never strings). */
+export interface CanvasLayout {
+    /** Content rows the canvas holds after this batch, i.e. after the trim. */
+    heldRows: number;
+    /** Blank rows above the content. Skipped with CUD, never written (I-B3). */
+    gap: number;
+    /** Rows this batch writes past the screen bottom; the terminal scrolls them away. */
+    scroll: number;
+    /** Content rows dropped from the head because they left the screen for good. */
+    dropped: number;
+    /** The canvas top after this batch. */
+    top: number;
+    /** The canvas height after this batch, which is the next erase distance. */
+    canvasRows: number;
+}
+/** The capacity above the parked row: `rows - 1`. Degrades to 0, never negative. */
+export declare function screenCapacity(rows: number | undefined): number;
+/**
+ * Clamp a measured "rows below the cursor" figure into `[0, rows - 1]`.
+ *
+ * `rows` unknown is treated as `0`: the caller is then exactly at the bottom, which
+ * is the conservative branch (no canvas to open up).
+ */
+export declare function clampSpaceBelow(spaceBelow: number, rows: number | undefined): number;
+/**
+ * A terminal that grew adds rows BELOW the cursor, so the capacity grows by the
+ * exact difference (D6). Shrinking is NOT handled here: it re-measures instead of
+ * guessing (D5), so a smaller value would only hide a lost measurement.
+ */
+export declare function applyResizeGrowth(capacity: number, rowsPrev: number, rowsNow: number): number;
+/**
+ * The layout of one batch.
+ *
+ * `heldRows` / `statRows` / `frameRows` are COUNTS, never strings, so this function
+ * can be property-tested over every combination without building a screen.
+ *
+ * TWO BRANCHES, and the difference is physical rather than cosmetic:
+ *  - FIT: the content plus the region fits the capacity, so the leftover becomes the
+ *    `gap` at the TOP of the canvas and nothing scrolls.
+ *  - SCROLL: the canvas cannot hold everything. The batch writes every content row
+ *    (the caller passes them untrimmed for exactly this reason), the terminal scrolls
+ *    `scroll` rows away, and the rows that leave are the oldest content rows plus the
+ *    host output above the canvas. `dropped` is how many content rows left.
+ */
+export declare function resolveCanvasLayout(input: CanvasLayoutInput): CanvasLayout;

package/dist/ui/scrollback/canvas.js

@@ -0,0 +1,113 @@
+/**
+ * Canvas arithmetic for native-scroll mode (tui-canvas-bottom-anchor §5.3).
+ *
+ * The defect this exists for: the bottom anchor of
+ * `tui-bottom-anchored-live-region` pinned the live region to the last two rows by
+ * prepending `pad` blank rows to the region's own block, so the blank space of a
+ * conversation that does not fill the screen sat BETWEEN the newest printed row and
+ * the composer. The user sees a reply that is not attached to the input box.
+ *
+ * The fix is a position change, not a value change: every row above the parked row
+ * becomes a CANVAS the writer owns, laid out top-down as `[gap][content][region]`.
+ * The blank space therefore lives ABOVE every visible content row, and the newest
+ * content row always touches the top row of the live region. The steady state is
+ * unchanged: `gap` equals the old `pad` row for row (the screen holds the same
+ * number of content rows either way).
+ *
+ * EVERYTHING HERE IS PURE: no I/O, no terminal, no clock, no `node:*` import. The
+ * writer's state machine decides which measurement is authoritative; this module
+ * only does the arithmetic, so the arithmetic can be property-tested over every
+ * combination instead of being sampled through a screen.
+ */
+/** Nothing measured yet: the pre-canvas append path, byte for byte (I-A3 / I-A8). */
+export const UNKNOWN_CANVAS = { kind: 'unknown' };
+/**
+ * `Math.floor` with the two answers a measurement must never produce collapsed onto
+ * `fallback`: `NaN` and `Infinity`. A `NaN` row count would make `Array(n)` throw and
+ * would turn `rows - 1 - n` into a lie, so a broken number degrades to "nothing".
+ */
+function whole(value, fallback) {
+    return Number.isFinite(value) ? Math.floor(value) : fallback;
+}
+/** The capacity above the parked row: `rows - 1`. Degrades to 0, never negative. */
+export function screenCapacity(rows) {
+    if (rows === undefined || !Number.isFinite(rows))
+        return 0;
+    return Math.max(0, Math.floor(rows) - 1);
+}
+/**
+ * Clamp a measured "rows below the cursor" figure into `[0, rows - 1]`.
+ *
+ * `rows` unknown is treated as `0`: the caller is then exactly at the bottom, which
+ * is the conservative branch (no canvas to open up).
+ */
+export function clampSpaceBelow(spaceBelow, rows) {
+    const upper = screenCapacity(rows);
+    const value = Number.isFinite(spaceBelow) ? Math.floor(spaceBelow) : 0;
+    return Math.min(upper, Math.max(0, value));
+}
+/**
+ * A terminal that grew adds rows BELOW the cursor, so the capacity grows by the
+ * exact difference (D6). Shrinking is NOT handled here: it re-measures instead of
+ * guessing (D5), so a smaller value would only hide a lost measurement.
+ */
+export function applyResizeGrowth(capacity, rowsPrev, rowsNow) {
+    // No capacity to grow: a broken number must not become a canvas by arithmetic.
+    if (!Number.isFinite(capacity))
+        return 0;
+    const base = Math.max(0, Math.floor(capacity));
+    const delta = Number.isFinite(rowsNow) && Number.isFinite(rowsPrev) ? rowsNow - rowsPrev : 0;
+    return base + Math.max(0, Math.floor(delta));
+}
+/**
+ * The layout of one batch.
+ *
+ * `heldRows` / `statRows` / `frameRows` are COUNTS, never strings, so this function
+ * can be property-tested over every combination without building a screen.
+ *
+ * TWO BRANCHES, and the difference is physical rather than cosmetic:
+ *  - FIT: the content plus the region fits the capacity, so the leftover becomes the
+ *    `gap` at the TOP of the canvas and nothing scrolls.
+ *  - SCROLL: the canvas cannot hold everything. The batch writes every content row
+ *    (the caller passes them untrimmed for exactly this reason), the terminal scrolls
+ *    `scroll` rows away, and the rows that leave are the oldest content rows plus the
+ *    host output above the canvas. `dropped` is how many content rows left.
+ */
+export function resolveCanvasLayout(input) {
+    // A re-seed writes its own leading CRLF, which eats one row of the space below the
+    // cursor and starts the canvas one row lower (P1-1 in the canvas model).
+    const lead = Math.max(0, whole(input.lead, 0));
+    const capacity = Math.max(0, whole(input.capacity, 0) - lead);
+    const held = Math.max(0, whole(input.heldRows, 0));
+    const stat = Math.max(0, whole(input.statRows, 0));
+    const frame = Math.max(0, whole(input.frameRows, 0));
+    const top = Math.max(0, whole(input.top, 0)) + lead;
+    const content = held + stat;
+    const need = content + frame;
+    if (need <= capacity) {
+        return {
+            heldRows: content,
+            gap: capacity - need,
+            scroll: 0,
+            dropped: 0,
+            top,
+            canvasRows: capacity,
+        };
+    }
+    const scroll = need - capacity;
+    // Rows above the canvas are the host's old output: they leave the screen first.
+    const hostUsed = Math.min(scroll, top);
+    const grown = capacity + hostUsed;
+    const dropped = Math.min(scroll - hostUsed, content);
+    const keptContent = content - dropped;
+    return {
+        heldRows: keptContent,
+        // Zero whenever anything scrolled, and that is what keeps blank rows out of the
+        // scrollback: a skipped gap is un-written cells, a scrolled one is a written row.
+        gap: Math.max(0, grown - keptContent - frame),
+        scroll,
+        dropped,
+        top: top - hostUsed,
+        canvasRows: grown,
+    };
+}

package/dist/ui/scrollback/cursor-probe.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Cursor-position probe — the one measurement the bottom anchor cannot do without
+ * (tui-bottom-anchored-live-region §4.4 / §6.3).
+ *
+ * WHY IT EXISTS. "How many rows are left below the cursor" cannot be derived from
+ * anything the process already knows: `CUD` clamps silently at the last row and
+ * reports nothing, and the only other way to reach the bottom is to print `rows - 1`
+ * newlines, which scrolls the user's screen. `ESC[6n` asks instead of guessing, and
+ * every target terminal answers it — Windows Terminal, conhost through ConPTY, tmux,
+ * screen, xterm/vte/alacritty/kitty/wezterm/foot/ghostty, the VS Code terminal and an
+ * SSH session's far end.
+ *
+ * WHAT IT DOES NOT DO:
+ *  - It does not touch raw mode. Raising raw is the HOST's job and must happen BEFORE
+ *    the query (P0-1 / I-A10): in canonical mode the reply is line-buffered until a
+ *    newline and the terminal ECHOES it as `^[[12;1R` onto the screen, so the probe
+ *    would time out forever on Linux/macOS while printing garbage.
+ *  - It does not consume input. The filter ahead of Ink owns every byte; this module
+ *    is a second `'data'` listener that never `pause()`s, `read()`s or `unshift()`s
+ *    (D5 / R2).
+ *  - It does not retry. One query, one bounded wait, then the caller degrades.
+ *
+ * FAILURE IS NORMAL, NOT AN ERROR: a terminal that never answers is a terminal that
+ * gets the one-off screen fill instead (rung 2 of the ladder). Nothing here throws,
+ * and nothing here can keep the process alive: the timer is `unref()`ed and the
+ * listener is always removed.
+ */
+export interface CursorProbeOptions {
+    /** The REAL stdin — not the filter's PassThrough, and not Ink's stream. */
+    stdin: NodeJS.ReadStream;
+    stdout: NodeJS.WriteStream;
+    /** Terminal height, read at answer time so a mid-wait resize is not fatal. */
+    rows: () => number | undefined;
+    /** Overrides `SCROLLBACK_LIMITS.anchorProbeTimeoutMs` (tests). */
+    timeoutMs?: number;
+    /**
+     * Keep the event loop alive while waiting for the answer.
+     *
+     * THE STARTUP PROBE MUST SET THIS, and the reason is measured rather than
+     * theoretical: an `unref()`ed timer is invisible to the event loop, so on a session
+     * where nothing is referenced yet — stdin already at EOF, a piped stdin, a console
+     * whose reader is paused — the process can exit BEFORE the first frame is ever
+     * drawn. `screen.test.ts`'s subprocess probe caught exactly that: exit code 0,
+     * `ESC[6n` on screen and no application at all.
+     *
+     * Background re-probes keep the default (`false`): a teardown must never be
+     * delayed, and by then the UI itself is holding the loop.
+     */
+    holdProcess?: boolean;
+}
+/**
+ * Arm or disarm the switch. `true` is permanent for the process: there is no
+ * legitimate reason to probe after the screen has been handed back.
+ */
+export declare function setAnchorProbeDisabled(value: boolean): void;
+/** Test hook — the switch is process-wide by design, so tests must reset it. */
+export declare function resetAnchorProbeForTests(): void;
+/**
+ * Ask the terminal where the cursor is and return the rows left below it
+ * (`0` = already on the last row). Returns `null` for every failure mode:
+ *
+ * | Situation                        | Result                          |
+ * |----------------------------------|---------------------------------|
+ * | switches off / not a TTY / rows unknown | `null`, synchronously, zero bytes |
+ * | terminal answers                 | `rows - 1 - (row - 1)`          |
+ * | timeout (`anchorProbeTimeoutMs`) | `null`, timer and listener removed |
+ * | concurrent call                  | the same promise; one query only |
+ * | `stdout.write` throws            | `null`                          |
+ * | a late reply after the timeout   | ignored here; the filter strips it |
+ */
+export declare function probeAnchorSpaceBelow(o: CursorProbeOptions): Promise<number | null>;

package/dist/ui/scrollback/cursor-probe.js

@@ -0,0 +1,133 @@
+/**
+ * Cursor-position probe — the one measurement the bottom anchor cannot do without
+ * (tui-bottom-anchored-live-region §4.4 / §6.3).
+ *
+ * WHY IT EXISTS. "How many rows are left below the cursor" cannot be derived from
+ * anything the process already knows: `CUD` clamps silently at the last row and
+ * reports nothing, and the only other way to reach the bottom is to print `rows - 1`
+ * newlines, which scrolls the user's screen. `ESC[6n` asks instead of guessing, and
+ * every target terminal answers it — Windows Terminal, conhost through ConPTY, tmux,
+ * screen, xterm/vte/alacritty/kitty/wezterm/foot/ghostty, the VS Code terminal and an
+ * SSH session's far end.
+ *
+ * WHAT IT DOES NOT DO:
+ *  - It does not touch raw mode. Raising raw is the HOST's job and must happen BEFORE
+ *    the query (P0-1 / I-A10): in canonical mode the reply is line-buffered until a
+ *    newline and the terminal ECHOES it as `^[[12;1R` onto the screen, so the probe
+ *    would time out forever on Linux/macOS while printing garbage.
+ *  - It does not consume input. The filter ahead of Ink owns every byte; this module
+ *    is a second `'data'` listener that never `pause()`s, `read()`s or `unshift()`s
+ *    (D5 / R2).
+ *  - It does not retry. One query, one bounded wait, then the caller degrades.
+ *
+ * FAILURE IS NORMAL, NOT AN ERROR: a terminal that never answers is a terminal that
+ * gets the one-off screen fill instead (rung 2 of the ladder). Nothing here throws,
+ * and nothing here can keep the process alive: the timer is `unref()`ed and the
+ * listener is always removed.
+ */
+import { SCROLLBACK_LIMITS } from './limits.js';
+import { formatCursorReportQuery, spaceBelowFromReport, splitCursorReports, } from '../../input/cursor-report.js';
+/** Longest acceptable report prefix we buffer before giving up on the chunk. */
+const MAX_BUFFER_CHARS = 64;
+/**
+ * THE DEATH SWITCH (I-A9 / P1-6).
+ *
+ * Once the session is over — `finalizeNativeScreen()`, `disposeFrameWriter()`, a
+ * disposed filter, the process `exit` hook — a query must never reach the terminal
+ * again. It would be written at a terminal already handed back to the shell, where
+ * nothing strips the reply, and the user's prompt would gain a literal `^[[12;1R`.
+ * The flag lives at module level because `cli.tsx`'s four exit paths converge on one
+ * call and must not each own a copy of the state.
+ */
+let disabled = false;
+/** Single-flight: a drag can ask twice inside one settle window. */
+let inFlight = null;
+/**
+ * Arm or disarm the switch. `true` is permanent for the process: there is no
+ * legitimate reason to probe after the screen has been handed back.
+ */
+export function setAnchorProbeDisabled(value) {
+    disabled = value;
+    if (value)
+        inFlight = null;
+}
+/** Test hook — the switch is process-wide by design, so tests must reset it. */
+export function resetAnchorProbeForTests() {
+    disabled = false;
+    inFlight = null;
+}
+/**
+ * Ask the terminal where the cursor is and return the rows left below it
+ * (`0` = already on the last row). Returns `null` for every failure mode:
+ *
+ * | Situation                        | Result                          |
+ * |----------------------------------|---------------------------------|
+ * | switches off / not a TTY / rows unknown | `null`, synchronously, zero bytes |
+ * | terminal answers                 | `rows - 1 - (row - 1)`          |
+ * | timeout (`anchorProbeTimeoutMs`) | `null`, timer and listener removed |
+ * | concurrent call                  | the same promise; one query only |
+ * | `stdout.write` throws            | `null`                          |
+ * | a late reply after the timeout   | ignored here; the filter strips it |
+ */
+export function probeAnchorSpaceBelow(o) {
+    if (disabled)
+        return Promise.resolve(null);
+    if (!o.stdin.isTTY || !o.stdout.isTTY)
+        return Promise.resolve(null);
+    if (inFlight)
+        return inFlight;
+    const rowsNow = o.rows();
+    if (rowsNow === undefined || !Number.isFinite(rowsNow) || rowsNow < 1) {
+        return Promise.resolve(null);
+    }
+    const promise = new Promise((resolve) => {
+        const timeoutMs = o.timeoutMs ?? SCROLLBACK_LIMITS.anchorProbeTimeoutMs;
+        let buffer = '';
+        let settled = false;
+        let timer = null;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            o.stdin.removeListener('data', onData);
+            resolve(value);
+        };
+        function onData(chunk) {
+            if (settled)
+                return;
+            buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+            if (buffer.length > MAX_BUFFER_CHARS)
+                buffer = buffer.slice(-MAX_BUFFER_CHARS);
+            const split = splitCursorReports(buffer);
+            const report = split.reports[0];
+            if (!report)
+                return;
+            finish(spaceBelowFromReport(report, o.rows() ?? undefined));
+        }
+        try {
+            o.stdout.write(formatCursorReportQuery());
+        }
+        catch {
+            // A closed or broken stdout is an ordinary failure, not a crash on startup.
+            finish(null);
+            return;
+        }
+        o.stdin.on('data', onData);
+        timer = setTimeout(() => finish(null), Math.max(1, Math.floor(timeoutMs)));
+        // `unref()` by default (see `holdProcess`), so a stray re-probe can never keep a
+        // teardown alive. The startup probe opts back in: there it is the ONLY thing
+        // holding the loop, and losing the session to save 150 ms is not a trade.
+        if (!o.holdProcess)
+            timer.unref?.();
+    });
+    inFlight = promise;
+    void promise.then(() => {
+        if (inFlight === promise)
+            inFlight = null;
+    });
+    return promise;
+}

package/dist/ui/scrollback/limits.d.ts

@@ -18,8 +18,65 @@ export declare const SCROLLBACK_LIMITS: {
     readonly guardTripCount: 3;
     /** Session summary rows printed on exit. */
     readonly exitSummaryMaxRows: 4;
-    /** Streaming preview rows, absolute cap. */
-    readonly maxLiveTailRows: 12;
-    /** ... and as a share of the terminal height. */
-    readonly liveTailRowShare: 0.4;
+    /**
+     * Entries the region may hold on screen at once
+     * (tui-full-height-live-region D6; the WINDOW is defined by I-F8 and computed in
+     * `tail-window.ts`).
+     *
+     * 10 is DERIVED, not a preference. The band's left column is the whole pool
+     * (`pool = rows - 1 - header - composer - status`, i.e. 24 rows on a 30-row
+     * terminal) and one entry occupies about 2.4 rows, so a window of 4 would leave
+     * the column half empty - the blank band this feature removes. It stays in the
+     * per-frame COST class the old value of 4 was measured in: `EntryView` is
+     * memoised and only the streaming entry re-renders, so this bounds component
+     * instances, not per-frame work.
+     *
+     * There is deliberately NO companion row cap any more (retired: the old
+     * `maxLiveTailRows` / `liveTailRowShare` pair). The rows a tail may take are
+     * `band.previewRows` - the whole left column - and "the region can never be
+     * taller than the screen" is `liveRows === rows - 1`'s job (I-F5), not a second
+     * number's. Those two caps disagreed with the pool, and that disagreement WAS the
+     * blank band between the result and the running card.
+     */
+    readonly liveTailMaxEntries: 10;
+    /**
+     * Rows the rail needs before the band will show it: `TODO_LIMITS.panelMinRows + 1`.
+     *
+     * The `+ 1` is not decoration - the rail takes its rows from the same pool as one
+     * preview row, and a band that seats the rail but no preview loses the streaming
+     * answer entirely (band.ts step 3 / AC-12).
+     */
+    readonly railBandMinRows: 4;
+    /**
+     * How long the cursor-position probe waits for `ESC[<row>;<col>R`.
+     *
+     * A STRUCTURAL CAP, not a preference (tui-bottom-anchored-live-region §4.4): it
+     * bounds "how much startup latency a terminal that does not answer may cost". The
+     * round trip is under 5 ms locally and under 60 ms over SSH, so 150 ms is
+     * generous, and the probe runs once per session — never per frame, never per
+     * keystroke. Anything longer and a terminal without CPR support would pay it on
+     * every launch.
+     */
+    readonly anchorProbeTimeoutMs: 150;
+    /**
+     * Settle window before re-measuring the cursor after a resize.
+     *
+     * A STRUCTURAL CAP for the same reason: a drag fires dozens of resize events, and
+     * one CPR per event would both flood the input channel and make the region jitter.
+     * 200 ms is below the point a user perceives as "the input box is stuck".
+     */
+    readonly anchorReprobeDelayMs: 200;
+    /**
+     * Structural ceiling on the height of a STARTING canvas.
+     *
+     * It bounds the bytes a batch may write and the rows the content cache may hold on
+     * an extreme terminal (`rows` 3000). Two limits on how it may be applied, both
+     * arithmetic rather than taste:
+     *  - the rows a canvas leaves unused do not disappear, they stay above it as the
+     *    permanent region, so a smaller starting canvas never loses content;
+     *  - it must NEVER clip a live canvas. A canvas that has overflowed and scrolled
+     *    grows to `rows - 1`, and shrinking one back would make the next erase reach
+     *    above its own top: host output erased, every visible row printed twice.
+     */
+    readonly maxCanvasRows: 200;
 };

package/dist/ui/scrollback/limits.js

@@ -18,8 +18,65 @@ export const SCROLLBACK_LIMITS = {
     guardTripCount: 3,
     /** Session summary rows printed on exit. */
     exitSummaryMaxRows: 4,
-    /** Streaming preview rows, absolute cap. */
-    maxLiveTailRows: 12,
-    /** ... and as a share of the terminal height. */
-    liveTailRowShare: 0.4,
+    /**
+     * Entries the region may hold on screen at once
+     * (tui-full-height-live-region D6; the WINDOW is defined by I-F8 and computed in
+     * `tail-window.ts`).
+     *
+     * 10 is DERIVED, not a preference. The band's left column is the whole pool
+     * (`pool = rows - 1 - header - composer - status`, i.e. 24 rows on a 30-row
+     * terminal) and one entry occupies about 2.4 rows, so a window of 4 would leave
+     * the column half empty - the blank band this feature removes. It stays in the
+     * per-frame COST class the old value of 4 was measured in: `EntryView` is
+     * memoised and only the streaming entry re-renders, so this bounds component
+     * instances, not per-frame work.
+     *
+     * There is deliberately NO companion row cap any more (retired: the old
+     * `maxLiveTailRows` / `liveTailRowShare` pair). The rows a tail may take are
+     * `band.previewRows` - the whole left column - and "the region can never be
+     * taller than the screen" is `liveRows === rows - 1`'s job (I-F5), not a second
+     * number's. Those two caps disagreed with the pool, and that disagreement WAS the
+     * blank band between the result and the running card.
+     */
+    liveTailMaxEntries: 10,
+    /**
+     * Rows the rail needs before the band will show it: `TODO_LIMITS.panelMinRows + 1`.
+     *
+     * The `+ 1` is not decoration - the rail takes its rows from the same pool as one
+     * preview row, and a band that seats the rail but no preview loses the streaming
+     * answer entirely (band.ts step 3 / AC-12).
+     */
+    railBandMinRows: 4,
+    /**
+     * How long the cursor-position probe waits for `ESC[<row>;<col>R`.
+     *
+     * A STRUCTURAL CAP, not a preference (tui-bottom-anchored-live-region §4.4): it
+     * bounds "how much startup latency a terminal that does not answer may cost". The
+     * round trip is under 5 ms locally and under 60 ms over SSH, so 150 ms is
+     * generous, and the probe runs once per session — never per frame, never per
+     * keystroke. Anything longer and a terminal without CPR support would pay it on
+     * every launch.
+     */
+    anchorProbeTimeoutMs: 150,
+    /**
+     * Settle window before re-measuring the cursor after a resize.
+     *
+     * A STRUCTURAL CAP for the same reason: a drag fires dozens of resize events, and
+     * one CPR per event would both flood the input channel and make the region jitter.
+     * 200 ms is below the point a user perceives as "the input box is stuck".
+     */
+    anchorReprobeDelayMs: 200,
+    /**
+     * Structural ceiling on the height of a STARTING canvas.
+     *
+     * It bounds the bytes a batch may write and the rows the content cache may hold on
+     * an extreme terminal (`rows` 3000). Two limits on how it may be applied, both
+     * arithmetic rather than taste:
+     *  - the rows a canvas leaves unused do not disappear, they stay above it as the
+     *    permanent region, so a smaller starting canvas never loses content;
+     *  - it must NEVER clip a live canvas. A canvas that has overflowed and scrolled
+     *    grows to `rows - 1`, and shrinking one back would make the next erase reach
+     *    above its own top: host output erased, every visible row printed twice.
+     */
+    maxCanvasRows: 200,
 };

package/dist/ui/scrollback/live-preview.d.ts

@@ -1,18 +1,28 @@
 /**
- * Streaming preview rows for the native-scroll live region
- * (tui-native-terminal-scroll §4.6).
+ * Plain-text fallback rows for the native-scroll live region
+ * (tui-native-terminal-scroll §4.6, tui-full-height-live-region RV-P2-7).
  *
- * Entries that are not yet final cannot be printed, but the user must still see the
- * answer arrive. This builds a few PLAIN-TEXT rows from the unsettled tail of the
- * transcript; the shell colours them uniformly (`theme.muted`). The preview is a
- * visual buffer only: when an entry settles it is printed in its real, formatted
- * shape and the preview rows disappear (the "settle jump", documented in the README).
+ * THE REAL TAIL IS `LiveTail`, NOT THIS. Native mode draws the region's tail with the
+ * actual entry components, so these rows are only the fallback for a frame that mounts
+ * no component there (and the floor of the measurement path). They are kept rather than
+ * deleted because the render tests use them to assert exactly that frame, and because
+ * `<= 24 wrapToRows` calls per frame is far below the cost of the components it stands
+ * in for.
+ *
+ * The input is the TAIL WINDOW (`selectTailWindow`), settled entries included: at
+ * `H = rows - 1` the region shows the last K entries of the conversation, so a
+ * projection built only from the unfinished ones would disagree with the screen.
+ * The field keeps its historical name `unsettled` because it is still "the entries the
+ * region is showing", and renaming it would touch the preview tests for no behaviour.
  *
  * PURE: no Ink, no theme, no I/O. Every returned row fits `cols` display columns.
  */
 import type { Entry } from '../../agent/reducer.js';
 export interface LivePreviewInput {
-    /** `entries.slice(settledCount)` — may include excluded entries; they are skipped. */
+    /**
+     * The entries to project, oldest first - the tail window in native mode. May include
+     * excluded entries; they are skipped.
+     */
     unsettled: readonly Entry[];
     /** Content width (`cols - 1`). */
     cols: number;
@@ -22,5 +32,3 @@ export interface LivePreviewInput {
 }
 /** The last `rows` preview rows, oldest first. `[]` when `rows <= 0`. */
 export declare function buildLivePreview(input: LivePreviewInput): string[];
-/** How many preview rows the unsettled entries would like, before budget clamping. */
-export declare function wantedPreviewRows(input: Omit<LivePreviewInput, 'rows'>, cap: number): number;

package/dist/ui/scrollback/live-preview.js

@@ -1,12 +1,19 @@
 /**
- * Streaming preview rows for the native-scroll live region
- * (tui-native-terminal-scroll §4.6).
+ * Plain-text fallback rows for the native-scroll live region
+ * (tui-native-terminal-scroll §4.6, tui-full-height-live-region RV-P2-7).
  *
- * Entries that are not yet final cannot be printed, but the user must still see the
- * answer arrive. This builds a few PLAIN-TEXT rows from the unsettled tail of the
- * transcript; the shell colours them uniformly (`theme.muted`). The preview is a
- * visual buffer only: when an entry settles it is printed in its real, formatted
- * shape and the preview rows disappear (the "settle jump", documented in the README).
+ * THE REAL TAIL IS `LiveTail`, NOT THIS. Native mode draws the region's tail with the
+ * actual entry components, so these rows are only the fallback for a frame that mounts
+ * no component there (and the floor of the measurement path). They are kept rather than
+ * deleted because the render tests use them to assert exactly that frame, and because
+ * `<= 24 wrapToRows` calls per frame is far below the cost of the components it stands
+ * in for.
+ *
+ * The input is the TAIL WINDOW (`selectTailWindow`), settled entries included: at
+ * `H = rows - 1` the region shows the last K entries of the conversation, so a
+ * projection built only from the unfinished ones would disagree with the screen.
+ * The field keeps its historical name `unsettled` because it is still "the entries the
+ * region is showing", and renaming it would touch the preview tests for no behaviour.
  *
  * PURE: no Ink, no theme, no I/O. Every returned row fits `cols` display columns.
  */
@@ -100,7 +107,3 @@ export function buildLivePreview(input) {
     }
     return all.slice(-rows);
 }
-/** How many preview rows the unsettled entries would like, before budget clamping. */
-export function wantedPreviewRows(input, cap) {
-    return buildLivePreview({ ...input, rows: cap }).length;
-}