@aragon-agent/cli 0.6.29 → 0.6.32

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

@@ -0,0 +1,72 @@
+/**
+ * Height budget of the native-scroll LIVE REGION (tui-native-terminal-scroll §4.6).
+ *
+ * I-S1 · `liveRows <= max(0, rows - 1)` for every input. Ink writes
+ * `clearTerminal` (which contains `ESC[3J`, erasing the user's scrollback) as soon
+ * as a frame is as tall as the terminal; a one-row margin is the only thing between
+ * a tidy region and data loss, so it is established by construction here and
+ * enumerated by a property test rather than trusted.
+ *
+ * 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, 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;
+    cols: number;
+    /** Width everything is rendered and printed at (`cols - 1`, D5). */
+    contentCols: number;
+    /** Terminal below the 40x12 floor: the region is a one-row placeholder. */
+    inactive: boolean;
+    statusRows: 0 | 1 | 2;
+    composerRows: number;
+    composerSlotRows: number;
+    composerCols: number;
+    popupRows: number;
+    popupMaxHeight: number;
+    overlayRows: number;
+    /** Preview rows: the band's projection, 0 while an overlay is open. */
+    liveTailRows: number;
+    /** Rows above the composer: `= band.bandRows` (the identity below is unchanged). */
+    topRows: number;
+    /** 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

@@ -0,0 +1,81 @@
+/**
+ * Height budget of the native-scroll LIVE REGION (tui-native-terminal-scroll §4.6).
+ *
+ * I-S1 · `liveRows <= max(0, rows - 1)` for every input. Ink writes
+ * `clearTerminal` (which contains `ESC[3J`, erasing the user's scrollback) as soon
+ * as a frame is as tall as the terminal; a one-row margin is the only thing between
+ * a tidy region and data loss, so it is established by construction here and
+ * enumerated by a property test rather than trusted.
+ *
+ * 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, 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 tailCap = Math.min(SCROLLBACK_LIMITS.maxLiveTailRows, Math.floor(base.rows * SCROLLBACK_LIMITS.liveTailRowShare));
+    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,
+        statusRows: base.statusRows, composerRows: base.composerRows,
+        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;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Static-row feed — the queue between the promotion pipeline (which decides an
+ * entry is final) and the scrollback writer (which prints it)
+ * (tui-native-terminal-scroll §4.3 "feed").
+ *
+ * FIFO, bounded. When the writer falls behind and the queue overflows, the OLDEST
+ * pending entries are folded into one ASCII marker and counted: a visible, counted
+ * omission, never a silent one (I-S2). Entries are taken as whole blocks and never
+ * split, so a batch boundary can never land inside one entry's rows.
+ */
+export interface EntryRef {
+    id: string;
+    kind: string;
+}
+export interface ScrollbackDrain {
+    enqueue(rows: readonly string[], meta: EntryRef): void;
+    takeAll(): readonly string[];
+    /** Whole entries only; always takes at least one when anything is pending. */
+    takeUpTo(maxRows: number): readonly string[];
+    /** Rows waiting, including a pending overflow marker. */
+    pending(): number;
+    /** Whole entries waiting (the overflow marker is not an entry). */
+    pendingEntries(): number;
+    /** Entries folded away by overflow, cumulative. */
+    elided(): number;
+    onEnqueue: (() => void) | null;
+    onDrained: (() => void) | null;
+}
+export declare function overflowMarker(count: number): string;
+export declare function createScrollbackDrain(options?: {
+    capacity?: number;
+}): ScrollbackDrain;

package/dist/ui/scrollback/drain.js

@@ -0,0 +1,64 @@
+/**
+ * Static-row feed — the queue between the promotion pipeline (which decides an
+ * entry is final) and the scrollback writer (which prints it)
+ * (tui-native-terminal-scroll §4.3 "feed").
+ *
+ * FIFO, bounded. When the writer falls behind and the queue overflows, the OLDEST
+ * pending entries are folded into one ASCII marker and counted: a visible, counted
+ * omission, never a silent one (I-S2). Entries are taken as whole blocks and never
+ * split, so a batch boundary can never land inside one entry's rows.
+ */
+import { SCROLLBACK_LIMITS } from './limits.js';
+export function overflowMarker(count) {
+    return `[${count} earlier ${count === 1 ? 'entry' : 'entries'} not printed - scrollback feed overflow]`;
+}
+export function createScrollbackDrain(options = {}) {
+    const capacity = Math.max(1, options.capacity ?? SCROLLBACK_LIMITS.feedCapacity);
+    const queue = [];
+    /** Entries folded since the marker was last printed. */
+    let foldedPending = 0;
+    let foldedTotal = 0;
+    const markerRows = () => (foldedPending > 0 ? 1 : 0);
+    const takeWhile = (fits) => {
+        const out = [];
+        if (foldedPending > 0) {
+            out.push(overflowMarker(foldedPending));
+            foldedPending = 0;
+        }
+        while (queue.length > 0) {
+            const next = queue[0];
+            // Always take the first entry, however tall: a block taller than the cap
+            // still has to print, and the writer splits at ENTRY boundaries only.
+            if (out.length > 0 && !fits(out.length, next.rows.length))
+                break;
+            queue.shift();
+            for (const row of next.rows)
+                out.push(row);
+        }
+        return out;
+    };
+    const drained = (taken) => {
+        if (taken.length > 0)
+            drain.onDrained?.();
+        return taken;
+    };
+    const drain = {
+        onEnqueue: null,
+        onDrained: null,
+        enqueue(rows, meta) {
+            queue.push({ id: meta.id, kind: meta.kind, rows });
+            while (queue.length > capacity) {
+                queue.shift();
+                foldedPending += 1;
+                foldedTotal += 1;
+            }
+            drain.onEnqueue?.();
+        },
+        takeAll: () => drained(takeWhile(() => true)),
+        takeUpTo: (maxRows) => drained(takeWhile((taken, next) => taken + next <= maxRows)),
+        pending: () => queue.reduce((sum, entry) => sum + entry.rows.length, markerRows()),
+        pendingEntries: () => queue.length,
+        elided: () => foldedTotal,
+    };
+    return drain;
+}