@aragon-agent/cli 0.6.31 → 0.6.32

package/dist/ui/scrollback/band.js

@@ -0,0 +1,109 @@
+/**
+ * Height and column budget of the native-scroll PANEL BAND
+ * (release-gate-and-native-panels §6.2).
+ *
+ * Native scroll mode drops the fixed frame, so it used to drop the panels with it:
+ * the TODO rail lived in `AppShell`'s middle band and the subagent roster in the
+ * viewport footer, and neither is rendered once `ScrollbackShell` takes over. The
+ * band is the replacement - one row pool shared by the roster (`TeamPanel`), the
+ * streaming tail and the rail (`TodoPanel`), sitting directly above the composer.
+ *
+ * PURE: no Ink, no clock, no terminal, no config read. Every invariant below is
+ * therefore established BY CONSTRUCTION for all input combinations and can be
+ * enumerated by a property test (AC-9..AC-14, AC-31):
+ *
+ *  - `bandRows <= remaining` and therefore `liveRows <= rows - 1` (I-4). Ink writes
+ *    `clearTerminal` - which contains `ESC[3J`, erasing the user's scrollback - as
+ *    soon as a frame is as tall as the terminal; that one row is the difference
+ *    between a tidy region and data loss.
+ *  - `previewCols + railCols === contentCols`, always (AC-10). The rail is a column
+ *    INSIDE the region, so the preview loses exactly the columns the rail takes and
+ *    nothing else (I-5: printing keeps the full `contentCols`).
+ *  - `teamRows > 0` leaves room for the rail plus one preview row (AC-12).
+ *  - `previewRows <= previewCap`, so the structural caps
+ *    `maxLiveTailRows` / `liveTailRowShare` keep binding (I-10).
+ *
+ * THERE IS EXACTLY ONE CALL SITE: `buildScrollbackBudget` (I-8). This module is
+ * exported so it can be tested, not so a second caller can allocate rows of its own
+ * - `remaining` is computed there, and a second copy of it is a second authority.
+ */
+import { TODO_LIMITS } from '../../todo/limits.js';
+import { SCROLLBACK_LIMITS } from './limits.js';
+/** Invalid geometry becomes zero, exactly like `layout/team-panel.ts::nonNegativeInt`. */
+function nonNegativeInt(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+/**
+ * Allocate the band. THE ORDER OF THE STEPS IS THE SPECIFICATION - reordering them
+ * changes the priority between "what this run is doing" (rail + roster) and "the
+ * words arriving right now" (preview), which is a product decision, not a detail.
+ *
+ * 0. Normalise every numeric input (`NaN` / `Infinity` / negatives become 0).
+ * 1. An open overlay takes the whole pool (the band would otherwise double-count it).
+ * 2. Seat the roster first, but never at the cost of the rail plus one preview row:
+ *    a dispatch is transient, the plan is the shape of the turn, both must fit.
+ * 3. Decide the rail's visibility, in the same reason order as `buildTodoRailLayout`.
+ * 4. RESERVE the rail's rows (`panelFullRows` floor - the 3-5 row compact form cannot
+ *    show which item is running, and the band reaches 6 rows far more often than the
+ *    full-screen rail does). A reservation, not the final value: see step 6.
+ * 5. The preview takes what is left, clamped by `previewCap`.
+ * 6. `bandRows = max(railReserved, teamRows + previewRows)`: with no unsettled
+ *    content `previewRows` is 0, yet the rail must still be there (the user is
+ *    reading a result and still needs the list).
+ * 7. Columns: the input `contentCols` is the only width authority.
+ * 8. Hand the late-arriving values (the hysteresis) back out for the next frame.
+ */
+export function buildLiveBand(input) {
+    const remaining = nonNegativeInt(input.remaining);
+    const contentCols = nonNegativeInt(input.contentCols);
+    const railCols = nonNegativeInt(input.railCols);
+    const previewCap = nonNegativeInt(input.previewCap);
+    const previewWanted = nonNegativeInt(input.previewWanted);
+    const itemCount = nonNegativeInt(input.itemCount);
+    const teamRowsNatural = nonNegativeInt(input.teamRowsNatural);
+    const heldRailRows = nonNegativeInt(input.heldRailRows);
+    const heldTeamRows = nonNegativeInt(input.heldTeamRows);
+    if (input.overlayOpen) {
+        return {
+            reason: 'overlay', bandRows: remaining, teamRows: 0, previewRows: 0,
+            railRows: 0, railCols: 0, previewCols: contentCols, heldRailRows: 0, heldTeamRows: 0,
+        };
+    }
+    const teamCeiling = Math.min(teamRowsNatural, Math.max(0, remaining - TODO_LIMITS.panelMinRows - 1));
+    // THE ROSTER IS SEATED AT ITS NATURAL (CLAMPED) HEIGHT, NOT AT THE REMEMBERED ONE.
+    // Seeding from `heldTeamRows` deadlocks the panel: a fresh dispatch starts with no
+    // memory, so frame one would seat zero rows, remember zero, and no later frame could
+    // ever seat the roster - the panel this feature exists to restore would never appear
+    // (found while implementing; recorded as IF-1 in the spec). The memory below only
+    // ever ADDS height back after a squeeze; it never withholds it.
+    const teamRows = teamCeiling;
+    const reason = !input.panelEnabled ? 'disabled'
+        : itemCount === 0 ? 'empty'
+            : railCols === 0 ? 'narrow'
+                : remaining - teamRows < SCROLLBACK_LIMITS.railBandMinRows ? 'short'
+                    : 'visible';
+    const railVisible = reason === 'visible';
+    const railReserved = railVisible
+        ? Math.min(Math.max(heldRailRows, TODO_LIMITS.panelFullRows), Math.max(0, remaining - teamRows - 1))
+        : 0;
+    const previewRows = Math.min(previewWanted, previewCap, Math.max(0, remaining - teamRows - railReserved));
+    const bandRows = Math.max(railReserved, teamRows + previewRows);
+    const railRows = railVisible ? bandRows : 0;
+    const railColsOut = railVisible ? railCols : 0;
+    return {
+        reason,
+        bandRows,
+        teamRows,
+        previewRows,
+        railRows,
+        railCols: railColsOut,
+        previewCols: Math.max(0, contentCols - railColsOut),
+        // MONOTONE MEMORY, NOT A SHRINKING ONE (I-6). A rail that collapsed to zero rows
+        // because the terminal shrank for two frames would otherwise come back four rows
+        // shorter and the band would visibly jump on every resize wobble. The RESET points
+        // (an emptied plan, a finished dispatch, a resize) live in the one place that owns
+        // the lifecycle, `use-scrollback-view.ts`; this function only remembers.
+        heldRailRows: Math.max(heldRailRows, railRows),
+        heldTeamRows: Math.max(heldTeamRows, teamRows),
+    };
+}

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

@@ -10,15 +10,37 @@
  * The composer, popup and status rows come from the SAME `buildFrameBudget` the
  * full-screen layout uses, so the two modes cannot disagree about how tall the
  * editor is. What differs is the top: there is no header, so the row it would
- * occupy joins the pool shared by the overlay and the streaming preview.
+ * occupy joins the pool shared by the overlay, the panel band and the streaming
+ * preview.
+ *
+ * THIS IS THE ONLY CALL SITE OF `buildLiveBand` (I-8). `remaining` is computed here
+ * once and handed to the band; an `App` that computed its own copy would make
+ * `liveRows <= rows - 1` depend on two numbers happening to agree instead of on the
+ * construction that proves it.
  */
+import { type LiveBand, type LiveBandInput } from './band.js';
 import { type FrameBudgetInput } from '../layout/budget.js';
+/**
+ * Everything the band needs that this module derives for itself: `remaining`,
+ * `contentCols`, `railCols`, `previewCap` and `previewWanted` are computed below, and
+ * `overlayOpen` is taken from `ScrollbackBudgetInput` so the two can never disagree.
+ * The caller supplies only the facts it alone knows (plan, panel switch, roster size,
+ * hysteresis), never a number this module is supposed to own (I-8).
+ */
+export type ScrollbackBandInput = Omit<LiveBandInput, 'remaining' | 'contentCols' | 'railCols' | 'previewCap' | 'previewWanted' | 'overlayOpen'>;
 export interface ScrollbackBudgetInput extends FrameBudgetInput {
     overlayOpen: boolean;
     /** Preview rows the content would like; the budget grants what fits. */
     liveTailWanted: number;
     /** The writer tripped its tall-frame guard: degrade to the placeholder until a resize. */
     forceInactive?: boolean;
+    /**
+     * REQUIRED, not optional (the same rule `TeamPanel`'s header records as D-13). An
+     * optional band would mean "forgot to pass it" renders silently without panels -
+     * exactly the defect this feature exists to remove - while a required field is a
+     * compile error at the one place that forgets.
+     */
+    band: ScrollbackBandInput;
 }
 export interface ScrollbackBudget {
     rows: number;
@@ -34,10 +56,17 @@ export interface ScrollbackBudget {
     popupRows: number;
     popupMaxHeight: number;
     overlayRows: number;
+    /** Preview rows: the band's projection, 0 while an overlay is open. */
     liveTailRows: number;
-    /** Rows above the composer: overlay or preview. */
+    /** Rows above the composer: `= band.bandRows` (the identity below is unchanged). */
     topRows: number;
-    /** Total live-region height; what Ink renders. */
+    /** Total live-region height; what Ink renders (`topRows + composer + status`). */
     liveRows: number;
+    /** Height and column allocation of the panel band; the single authority is `band.ts`. */
+    band: LiveBand;
+    /** Preview/tail width: `contentCols - railCols`. Printing keeps `contentCols`. */
+    previewCols: number;
+    /** Rows the preview wanted before any clipping (feeds hysteresis and `/perf`). */
+    previewWanted: number;
 }
 export declare function buildScrollbackBudget(input: ScrollbackBudgetInput): ScrollbackBudget;

package/dist/ui/scrollback/budget.js

@@ -10,29 +10,65 @@
  * The composer, popup and status rows come from the SAME `buildFrameBudget` the
  * full-screen layout uses, so the two modes cannot disagree about how tall the
  * editor is. What differs is the top: there is no header, so the row it would
- * occupy joins the pool shared by the overlay and the streaming preview.
+ * occupy joins the pool shared by the overlay, the panel band and the streaming
+ * preview.
+ *
+ * THIS IS THE ONLY CALL SITE OF `buildLiveBand` (I-8). `remaining` is computed here
+ * once and handed to the band; an `App` that computed its own copy would make
+ * `liveRows <= rows - 1` depend on two numbers happening to agree instead of on the
+ * construction that proves it.
  */
+import { buildLiveBand } from './band.js';
 import { buildFrameBudget } from '../layout/budget.js';
+import { todoRailWidth } from '../layout/rail.js';
 import { SCROLLBACK_LIMITS } from './limits.js';
+/**
+ * The band of a frame that shows no content at all (below the 40x12 floor, or after
+ * the writer's tall-frame guard tripped). It is a REAL value rather than `undefined`
+ * because `/perf` and the render tests must be able to read the reason on exactly the
+ * frames where something went wrong (I-14 / AC-23).
+ */
+function degradedBand(contentCols) {
+    return {
+        reason: 'short', bandRows: 0, teamRows: 0, previewRows: 0,
+        railRows: 0, railCols: 0, previewCols: contentCols, heldRailRows: 0, heldTeamRows: 0,
+    };
+}
 export function buildScrollbackBudget(input) {
     const base = buildFrameBudget(input);
     const contentCols = Math.max(1, base.cols - 1);
+    // `liveTailWanted` comes from a measurement, but a caller that never measured passes
+    // `undefined`/`NaN`; normalising here keeps `NaN` out of `/perf` and out of the band.
+    const previewWanted = Number.isFinite(input.liveTailWanted)
+        ? Math.max(0, Math.floor(input.liveTailWanted))
+        : 0;
     if (base.inactive || input.forceInactive === true) {
         return {
             rows: base.rows, cols: base.cols, contentCols, inactive: true, statusRows: 0,
             composerRows: 0, composerSlotRows: 0, composerCols: base.composerCols, popupRows: 0,
             popupMaxHeight: 0, overlayRows: 0, liveTailRows: 0, topRows: 0,
             liveRows: Math.max(0, Math.min(1, base.rows - 1)),
+            band: degradedBand(contentCols), previewCols: contentCols, previewWanted,
         };
     }
     // The full-screen frame spends one row on the header; here it joins the pool.
     const remaining = Math.max(0, base.viewportRows + base.headerRows);
-    const overlayRows = input.overlayOpen ? remaining : 0;
     const tailCap = Math.min(SCROLLBACK_LIMITS.maxLiveTailRows, Math.floor(base.rows * SCROLLBACK_LIMITS.liveTailRowShare));
-    const liveTailRows = input.overlayOpen
-        ? 0
-        : Math.max(0, Math.min(Math.floor(input.liveTailWanted), remaining, tailCap));
-    const topRows = overlayRows + liveTailRows;
+    const band = buildLiveBand({
+        ...input.band,
+        remaining,
+        contentCols,
+        railCols: todoRailWidth(contentCols),
+        previewCap: tailCap,
+        previewWanted,
+        // Taken from THIS input, never from `input.band`: an overlay that the frame knows
+        // about but the band did not would draw no overlay at all, and the shell keys the
+        // overlay's rows off the band.
+        overlayOpen: input.overlayOpen,
+    });
+    const overlayRows = band.reason === 'overlay' ? band.bandRows : 0;
+    const liveTailRows = band.previewRows;
+    const topRows = band.bandRows;
     const liveRows = topRows + base.composerSlotRows + base.statusRows;
     return {
         rows: base.rows, cols: base.cols, contentCols, inactive: false,
@@ -40,5 +76,6 @@ export function buildScrollbackBudget(input) {
         composerSlotRows: base.composerSlotRows, composerCols: base.composerCols,
         popupRows: base.popupRows, popupMaxHeight: base.popupMaxHeight, overlayRows,
         liveTailRows, topRows, liveRows,
+        band, previewCols: band.previewCols, previewWanted,
     };
 }

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;
+}