@aragon-agent/cli 0.6.32 → 0.6.34

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

package/dist/ui/scrollback/overflow-print.d.ts

@@ -0,0 +1,108 @@
+/**
+ * TOP GIVE-WAY - the row-level print plan of the native-scroll live region
+ * (tui-final-reply-truncated-unscrollable, plan A-prime / B3).
+ *
+ * THE DEFECT THIS ANSWERS. The region is the whole screen (`H = rows - 1`), so the box
+ * that holds the conversation is only `previewRows` tall (24 rows on a 30-row terminal),
+ * while the boundary that decides what may print into the terminal's scrollback is
+ * counted in ENTRIES (`liveTailMaxEntries`). A settled answer taller than the box is
+ * therefore inside the window, never printed, and clipped from the top by
+ * `justifyContent="flex-end"`. Native mode has no in-frame viewport - the wheel scrolls
+ * the terminal's scrollback - so the clipped rows exist nowhere the user can reach.
+ *
+ * The region cannot simply grow: a frame as tall as the terminal makes Ink write
+ * `clearTerminal` (which contains `ESC[3J`) and that erases the user's scrollback. So the
+ * only direction that keeps both promises is this one: the box keeps showing what it can,
+ * and the rows it hides are PRINTED into the scrollback, where the terminal's own scroll
+ * already reaches. Nothing on screen changes; the head of a long answer simply becomes
+ * readable one wheel turn up.
+ *
+ * WHAT THE PLAN GUARANTEES (the invariants the implementation batches are verified by):
+ *  I-B1 `printed(e) + visible(e) = rows(e)` and the two ranges are adjacent and disjoint,
+ *       so `scrollback + screen` covers every row exactly once (no gap, no duplicate).
+ *  I-B2 Only STABLE entries may print, and the FIRST unstable entry is a wall: nothing at
+ *       or after it is ever planned, even when a stable entry follows it (a `notice` after
+ *       a streaming answer is stable, and printing it here would put rows into the
+ *       scrollback out of conversation order, which is unrecoverable).
+ *  I-B3 The plan is ordered oldest-first and carries no gaps: the caller prints the
+ *       segments in the order given, so the scrollback keeps conversation order.
+ *  I-B4 It never plans a row that is still on screen: `hiddenRows` is measured against the
+ *       box height, and the box clips from the TOP only while it is bottom-anchored
+ *       (`tail-anchor.ts`), which the caller checks before printing anything.
+ *
+ * PURE: no Ink, no I/O, no clock, no `node:*`. That is why the caller injects the measured
+ * heights and the printed counts instead of this module measuring anything itself: the same
+ * arithmetic then drives a unit test with an arbitrary table instead of a screen.
+ */
+import type { Entry } from '../../agent/reducer.js';
+/** One entry of the tail window, as the planner needs it. */
+export interface OverflowWindowEntry {
+    entry: Entry;
+    /**
+     * Rows this entry occupies in the live region, measured at the SAME width the region
+     * draws it at (`previewCols`). An estimate is not good enough here: the plan decides how
+     * many rows are hidden, and a wrong count either duplicates a visible row or leaves one
+     * unreachable.
+     */
+    rows: number;
+    /** Leading rows of this entry already in the scrollback, `0` when none. */
+    printed: number;
+    /**
+     * `isEntryStable(entry, runActive, isTail)` for this entry - the caller's answer, because
+     * "is this the tail" is a property of the FULL list and the window is a filtered slice.
+     */
+    stable: boolean;
+}
+/** One run of rows to print: `[fromRow, toRow)` of `entry`'s own rows. */
+export interface OverflowSegment {
+    /** Index into the window the planner was given. */
+    index: number;
+    id: string;
+    /** First row to print, 0-based from the top of the entry. */
+    fromRow: number;
+    /** One past the last row to print. */
+    toRow: number;
+}
+export interface OverflowPlan {
+    /** Rows to hand to the writer, oldest entry first (I-B3). */
+    segments: readonly OverflowSegment[];
+    /** Rows the box hides above its top edge; `0` when the window fits. */
+    hiddenRows: number;
+    /** Measured height of the whole window, including entries past the wall. */
+    totalRows: number;
+}
+/**
+ * Which rows of the window the box is hiding, and how many of them are not printed yet.
+ *
+ * @param window The tail window, OLDEST FIRST, excluded entries already dropped.
+ * @param budgetRows Height of the box that shows the window (`band.previewRows`).
+ * @returns The print plan; `segments` is empty when nothing is hidden or when the first
+ * unstable entry sits at the top of the window (see I-B2).
+ */
+export declare function planOverflowPrint(window: readonly OverflowWindowEntry[], budgetRows: number): OverflowPlan;
+/**
+ * The row that marks a WIDTH CHANGE inside one entry's printed history.
+ *
+ * "Rows already printed" is a width-relative quantity: a line that took two rows at 80
+ * columns takes one at 120. Continuing to slice at the old index would skip content
+ * (`W1` breaks) or repeat it silently. So a width change prints this seam and restarts the
+ * entry at the new width: every row stays reachable, and the only cost is one bounded
+ * repetition of the rows above the seam (documented in the README).
+ */
+export declare function reflowSeamRow(printedRows: number, printedCols: number, cols: number): string;
+/** The single wording of the per-entry row cap, shared by the renderer and the pipeline. */
+export declare function elisionRow(hidden: number): string;
+/**
+ * Apply `maxRowsPerEntry` to the REMAINDER of one entry.
+ *
+ * The cap used to be a single "keep the first 399 rows, then say how many were dropped".
+ * That is still what a never-printed entry gets (`headRows === 0`), because it keeps the
+ * part of the answer the user has already scrolled past. An entry whose HEAD is already in
+ * the scrollback gets the opposite treatment on purpose: the notice goes FIRST and the LAST
+ * rows follow, because the tail is the part the reader is looking at on screen, and eliding
+ * it would delete the answer they just finished reading from their history.
+ *
+ * @param tail Rows still to print (`body.slice(fromRow)`).
+ * @param headRows Rows of this entry already printed.
+ */
+export declare function capPrintedRows(tail: readonly string[], headRows: number): readonly string[];

package/dist/ui/scrollback/overflow-print.js

@@ -0,0 +1,120 @@
+/**
+ * TOP GIVE-WAY - the row-level print plan of the native-scroll live region
+ * (tui-final-reply-truncated-unscrollable, plan A-prime / B3).
+ *
+ * THE DEFECT THIS ANSWERS. The region is the whole screen (`H = rows - 1`), so the box
+ * that holds the conversation is only `previewRows` tall (24 rows on a 30-row terminal),
+ * while the boundary that decides what may print into the terminal's scrollback is
+ * counted in ENTRIES (`liveTailMaxEntries`). A settled answer taller than the box is
+ * therefore inside the window, never printed, and clipped from the top by
+ * `justifyContent="flex-end"`. Native mode has no in-frame viewport - the wheel scrolls
+ * the terminal's scrollback - so the clipped rows exist nowhere the user can reach.
+ *
+ * The region cannot simply grow: a frame as tall as the terminal makes Ink write
+ * `clearTerminal` (which contains `ESC[3J`) and that erases the user's scrollback. So the
+ * only direction that keeps both promises is this one: the box keeps showing what it can,
+ * and the rows it hides are PRINTED into the scrollback, where the terminal's own scroll
+ * already reaches. Nothing on screen changes; the head of a long answer simply becomes
+ * readable one wheel turn up.
+ *
+ * WHAT THE PLAN GUARANTEES (the invariants the implementation batches are verified by):
+ *  I-B1 `printed(e) + visible(e) = rows(e)` and the two ranges are adjacent and disjoint,
+ *       so `scrollback + screen` covers every row exactly once (no gap, no duplicate).
+ *  I-B2 Only STABLE entries may print, and the FIRST unstable entry is a wall: nothing at
+ *       or after it is ever planned, even when a stable entry follows it (a `notice` after
+ *       a streaming answer is stable, and printing it here would put rows into the
+ *       scrollback out of conversation order, which is unrecoverable).
+ *  I-B3 The plan is ordered oldest-first and carries no gaps: the caller prints the
+ *       segments in the order given, so the scrollback keeps conversation order.
+ *  I-B4 It never plans a row that is still on screen: `hiddenRows` is measured against the
+ *       box height, and the box clips from the TOP only while it is bottom-anchored
+ *       (`tail-anchor.ts`), which the caller checks before printing anything.
+ *
+ * PURE: no Ink, no I/O, no clock, no `node:*`. That is why the caller injects the measured
+ * heights and the printed counts instead of this module measuring anything itself: the same
+ * arithmetic then drives a unit test with an arbitrary table instead of a screen.
+ */
+import { SCROLLBACK_LIMITS } from './limits.js';
+function wholeRows(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+/**
+ * Which rows of the window the box is hiding, and how many of them are not printed yet.
+ *
+ * @param window The tail window, OLDEST FIRST, excluded entries already dropped.
+ * @param budgetRows Height of the box that shows the window (`band.previewRows`).
+ * @returns The print plan; `segments` is empty when nothing is hidden or when the first
+ * unstable entry sits at the top of the window (see I-B2).
+ */
+export function planOverflowPrint(window, budgetRows) {
+    const totalRows = window.reduce((sum, item) => sum + wholeRows(item.rows), 0);
+    // Rows past the wall are on screen too (the box is one box), so they count towards the
+    // height - they are simply never printable themselves.
+    const hiddenRows = Math.max(0, totalRows - wholeRows(budgetRows));
+    if (hiddenRows === 0)
+        return { segments: [], hiddenRows, totalRows };
+    const segments = [];
+    let offset = 0;
+    for (const [index, item] of window.entries()) {
+        // I-B2 - the wall. Nothing at or after the first unstable entry may print, and because
+        // the loop walks in order, "at or after" needs nothing more than a `break`.
+        if (!item.stable)
+            break;
+        // Every row from here down is visible: the box clips exactly `hiddenRows` rows off the
+        // top, so once the accumulated offset reaches it the plan is complete.
+        if (offset >= hiddenRows)
+            break;
+        const hiddenOfEntry = Math.min(wholeRows(item.rows), hiddenRows - offset);
+        const printed = wholeRows(item.printed);
+        if (hiddenOfEntry > printed) {
+            segments.push({ index, id: item.entry.id, fromRow: printed, toRow: hiddenOfEntry });
+        }
+        offset += wholeRows(item.rows);
+    }
+    return { segments, hiddenRows, totalRows };
+}
+/**
+ * The row that marks a WIDTH CHANGE inside one entry's printed history.
+ *
+ * "Rows already printed" is a width-relative quantity: a line that took two rows at 80
+ * columns takes one at 120. Continuing to slice at the old index would skip content
+ * (`W1` breaks) or repeat it silently. So a width change prints this seam and restarts the
+ * entry at the new width: every row stays reachable, and the only cost is one bounded
+ * repetition of the rows above the seam (documented in the README).
+ */
+export function reflowSeamRow(printedRows, printedCols, cols) {
+    return `[-- reflowed to ${cols} columns; ${printedRows} row(s) above were printed at ` +
+        `${printedCols} columns --]`;
+}
+/** The single wording of the per-entry row cap, shared by the renderer and the pipeline. */
+export function elisionRow(hidden) {
+    return `[+${hidden} rows not printed - scrollback entry cap]`;
+}
+/**
+ * Apply `maxRowsPerEntry` to the REMAINDER of one entry.
+ *
+ * The cap used to be a single "keep the first 399 rows, then say how many were dropped".
+ * That is still what a never-printed entry gets (`headRows === 0`), because it keeps the
+ * part of the answer the user has already scrolled past. An entry whose HEAD is already in
+ * the scrollback gets the opposite treatment on purpose: the notice goes FIRST and the LAST
+ * rows follow, because the tail is the part the reader is looking at on screen, and eliding
+ * it would delete the answer they just finished reading from their history.
+ *
+ * @param tail Rows still to print (`body.slice(fromRow)`).
+ * @param headRows Rows of this entry already printed.
+ */
+export function capPrintedRows(tail, headRows) {
+    const cap = SCROLLBACK_LIMITS.maxRowsPerEntry;
+    const printed = wholeRows(headRows);
+    if (printed + tail.length <= cap)
+        return tail;
+    if (printed === 0) {
+        const keep = Math.max(0, cap - 1);
+        return [...tail.slice(0, keep), elisionRow(tail.length - keep)];
+    }
+    // One row is spent on the notice itself.
+    const keep = Math.max(0, cap - printed - 1);
+    if (keep === 0)
+        return [elisionRow(tail.length)];
+    return [elisionRow(tail.length - keep), ...tail.slice(tail.length - keep)];
+}

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

@@ -23,8 +23,18 @@ export interface EntryRenderOptions {
     reducedMotion: boolean;
 }
 export interface EntryRenderer {
-    /** Rows for one entry at `cols` columns; `[]` when it renders as nothing. */
+    /** Rows for one entry at `cols` columns, capped at `maxRowsPerEntry`; `[]` when it renders as nothing. */
     renderEntry(entry: Entry, prev: Entry | undefined, cols: number, expanded?: boolean): string[];
+    /**
+     * The SAME rows, UNCAPPED.
+     *
+     * "Top give-way" (`overflow-print.ts`) slices one entry across two print passes, so it
+     * needs the real row count and the real rows: `capRows` truncates before returning, and a
+     * row budget computed from a truncated array puts the cut in the wrong place (a 800-row
+     * answer would compute its cut on 400 rows and print rows the screen is still showing).
+     * The cap is applied by the caller, once, where it knows how many rows are already printed.
+     */
+    renderEntryRows(entry: Entry, prev: Entry | undefined, cols: number, expanded?: boolean): string[];
     /** Rows for an arbitrary node (the startup header and opener). */
     renderNode(node: React.ReactNode, cols: number): string[];
     /** Options for LATER renders; already printed rows never change. */

package/dist/ui/scrollback/renderer.js

@@ -17,6 +17,7 @@ import { Box, render } from 'ink';
 import { EntryView } from '../Transcript.js';
 import { getLogger } from '../../logging/logger.js';
 import { SCROLLBACK_LIMITS } from './limits.js';
+import { elisionRow } from './overflow-print.js';
 /**
  * Catches a throwing entry INSIDE the offscreen tree.
  *
@@ -76,30 +77,52 @@ function trimTrailingBlank(rows) {
 }
 export function createEntryRenderer(initial) {
     let options = initial;
-    let offscreen = null;
+    /**
+     * Resident offscreen instances, keyed by width.
+     *
+     * TWO SLOTS, NOT ONE. Ink reads `columns` once, at creation, so a width change needs a new
+     * instance - but a width change happens WITHIN one promotion pass as soon as the plan
+     * measures at the box width (`previewCols`) and prints at `contentCols`, and a single slot
+     * would then dispose and rebuild a complete Ink root on every such frame. Two slots cover
+     * both widths of the current geometry; a third width (an actual resize) evicts the oldest.
+     */
+    const slots = new Map();
+    const MAX_SLOTS = 2;
     let elidedRows = 0;
     let failures = 0;
     let guardKey = 0;
-    const dispose = () => {
-        if (!offscreen)
+    const disposeSlot = (cols) => {
+        const target = slots.get(cols);
+        if (!target)
             return;
-        const current = offscreen;
-        offscreen = null;
+        slots.delete(cols);
         try {
-            current.instance.unmount();
-            current.instance.cleanup();
+            target.instance.unmount();
+            target.instance.cleanup();
         }
         catch {
             // Tearing down a fake stream must never throw into an exit path.
         }
     };
+    const dispose = () => {
+        for (const cols of [...slots.keys()])
+            disposeSlot(cols);
+    };
     /** Ink reads `columns` once, at creation, so a width change rebuilds the instance. */
     const ensure = (cols) => {
-        if (offscreen && offscreen.cols === cols)
-            return offscreen;
-        dispose();
-        offscreen = createOffscreen(cols);
-        return offscreen;
+        const resident = slots.get(cols);
+        if (resident) {
+            // Refresh the recency order so the OTHER width is the eviction candidate.
+            slots.delete(cols);
+            slots.set(cols, resident);
+            return resident;
+        }
+        const evictable = [...slots.keys()][0];
+        if (evictable !== undefined && slots.size >= MAX_SLOTS)
+            disposeSlot(evictable);
+        const created = createOffscreen(cols);
+        slots.set(cols, created);
+        return created;
     };
     const capRows = (rows) => {
         const cap = SCROLLBACK_LIMITS.maxRowsPerEntry;
@@ -107,9 +130,9 @@ export function createEntryRenderer(initial) {
             return rows;
         const hidden = rows.length - (cap - 1);
         elidedRows += hidden;
-        return [...rows.slice(0, cap - 1), `[+${hidden} rows not printed - scrollback entry cap]`];
+        return [...rows.slice(0, cap - 1), elisionRow(hidden)];
     };
-    const renderNode = (node, cols) => {
+    const renderFrame = (node, cols) => {
         const target = ensure(Math.max(1, Math.floor(cols)));
         target.last.value = null;
         target.failure.error = NO_FAILURE;
@@ -122,27 +145,32 @@ export function createEntryRenderer(initial) {
             throw failure;
         if (frame === null)
             throw new Error('offscreen Ink instance produced no frame');
-        return capRows(trimTrailingBlank(frame.split('\n')));
+        return trimTrailingBlank(frame.split('\n'));
     };
     const failureRow = (label) => {
         failures += 1;
         return [`[aragon] ${label} could not be rendered`];
     };
+    const entryFrame = (entry, prev, cols, expanded) => renderFrame(_jsx(EntryView, { entry: entry, prev: prev, expanded: expanded, thinkingVisible: options.thinkingVisible, reducedMotion: options.reducedMotion, density: options.density, theme: options.theme, caps: options.caps }), cols);
+    const renderEntryRows = (entry, prev, cols, expanded = false) => {
+        try {
+            return entryFrame(entry, prev, cols, expanded);
+        }
+        catch (error) {
+            getLogger().warn('cli', 'entry_render_failed', {
+                id: entry.id, kind: entry.kind, error: String(error),
+            });
+            return failureRow(`entry ${entry.id} (${entry.kind})`);
+        }
+    };
     return {
         renderEntry(entry, prev, cols, expanded = false) {
-            try {
-                return renderNode(_jsx(EntryView, { entry: entry, prev: prev, expanded: expanded, thinkingVisible: options.thinkingVisible, reducedMotion: options.reducedMotion, density: options.density, theme: options.theme, caps: options.caps }), cols);
-            }
-            catch (error) {
-                getLogger().warn('cli', 'entry_render_failed', {
-                    id: entry.id, kind: entry.kind, error: String(error),
-                });
-                return failureRow(`entry ${entry.id} (${entry.kind})`);
-            }
+            return capRows(renderEntryRows(entry, prev, cols, expanded));
         },
+        renderEntryRows,
         renderNode(node, cols) {
             try {
-                return renderNode(node, cols);
+                return capRows(renderFrame(node, cols));
             }
             catch (error) {
                 getLogger().warn('cli', 'node_render_failed', { error: String(error) });

package/dist/ui/scrollback/tail-anchor.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Where the live tail sits inside the band's preview box
+ * (tui-first-reply-bottom-aligned, plan A-prime).
+ *
+ * THE DEFECT THIS ANSWERS. The box is always the whole pool (`band.previewRows`, 24 rows
+ * on a 30-row terminal) while a first turn is four rows tall. A constant
+ * `justifyContent="flex-end"` therefore pushed those four rows against the composer and
+ * left every unused row ABOVE the conversation - the "the first reply starts at the
+ * bottom of the screen" report. The answer is conditional anchoring: top while the
+ * content fits, so the conversation is written downwards from under the header.
+ *
+ * WHY THE FALLBACK IS `bottom` AND NOT THE OTHER WAY ROUND. `flex-start` inside an
+ * `overflow="hidden"` box clips the NEWEST rows (Ink's clip rectangle is the box's
+ * `[top, top + height]`), and a streaming entry is never printable
+ * (`settled-boundary.ts` holds it unstable, and "printed is forever"). Overflowing to
+ * `flex-start` would hide the text the user is waiting for; overflowing to `flex-end`
+ * hides the oldest rows, which the tail window prints on its way out.
+ *
+ * THE THRESHOLD CARRIES A MARGIN. `rowOf` is an ESTIMATE, and the one available
+ * (`layout/virtual-window.ts::estimateEntryRows`) under-counts a `#` heading and a code
+ * block. The margin in `SCROLLBACK_LIMITS.tailAnchorSlackRows` absorbs that error on the
+ * `bottom` side, the only direction that cannot clip something new.
+ *
+ * PURE: no Ink, no I/O, no clock, and deliberately no import of `virtual-window.ts` (its
+ * import graph reaches a `.tsx` gutter). The row height is injected, so this stays three
+ * parameters and a unit test can drive it with any table it likes.
+ */
+import type { Entry } from '../../agent/reducer.js';
+/** `top` = content grows down from the header; `bottom` = newest row hugs the composer. */
+export type TailAnchor = 'top' | 'bottom';
+/**
+ * Which alignment the live tail should use for the entries it is about to render.
+ *
+ * @param entries The entries THIS FRAME renders (already windowed by `selectTailEntries`;
+ * summing the whole conversation would make every session past the entry cap overflow and
+ * anchor to the bottom forever).
+ * @param budgetRows Height of the box that will clip them, in rows.
+ * @param rowOf Estimated height of one entry, including its separation row.
+ * @returns `top` when the estimates plus `tailAnchorSlackRows` fit in `budgetRows`,
+ * `bottom` otherwise (and for the first entry that does not fit, so the loop stops early).
+ */
+export declare function tailAnchor(entries: readonly Entry[], budgetRows: number, rowOf: (entry: Entry) => number): TailAnchor;
+/**
+ * The anchor this frame really uses: MEASURED when the measurement exists, estimated
+ * otherwise.
+ *
+ * WHY A MEASURED ANSWER WINS (tui-final-reply-truncated-unscrollable). The estimate is an
+ * upper bound that charges a separation row this renderer may not draw, so it can claim the
+ * content overflows while it actually fits (the block sits at the bottom of a half-empty
+ * box - the very complaint `tui-first-reply-bottom-aligned` answered) and it under-counts a
+ * heading or a wrapped code block, so it can claim the content fits while the box is really
+ * clipping. The second error is the expensive one now: "top give-way" only prints while the
+ * box is bottom-anchored (that is the branch that clips the TOP), so a wrongly top-anchored
+ * box would clip the newest rows and print the oldest ones - the wrong half, twice.
+ *
+ * A measured total is available only when every window entry is stable AND already measured
+ * at the current geometry (`use-scrollback-view.ts` keeps that cache), which is exactly the
+ * frame on which a print decision is being made. Every other frame - streaming, resize,
+ * first sight of a new entry - falls back to the estimate, unchanged.
+ *
+ * @param measuredRows Measured height of the same entries, or `undefined` when unknown.
+ */
+export declare function resolveTailAnchor(input: {
+    entries: readonly Entry[];
+    budgetRows: number;
+    rowOf: (entry: Entry) => number;
+    measuredRows: number | undefined;
+}): TailAnchor;

package/dist/ui/scrollback/tail-anchor.js

@@ -0,0 +1,77 @@
+/**
+ * Where the live tail sits inside the band's preview box
+ * (tui-first-reply-bottom-aligned, plan A-prime).
+ *
+ * THE DEFECT THIS ANSWERS. The box is always the whole pool (`band.previewRows`, 24 rows
+ * on a 30-row terminal) while a first turn is four rows tall. A constant
+ * `justifyContent="flex-end"` therefore pushed those four rows against the composer and
+ * left every unused row ABOVE the conversation - the "the first reply starts at the
+ * bottom of the screen" report. The answer is conditional anchoring: top while the
+ * content fits, so the conversation is written downwards from under the header.
+ *
+ * WHY THE FALLBACK IS `bottom` AND NOT THE OTHER WAY ROUND. `flex-start` inside an
+ * `overflow="hidden"` box clips the NEWEST rows (Ink's clip rectangle is the box's
+ * `[top, top + height]`), and a streaming entry is never printable
+ * (`settled-boundary.ts` holds it unstable, and "printed is forever"). Overflowing to
+ * `flex-start` would hide the text the user is waiting for; overflowing to `flex-end`
+ * hides the oldest rows, which the tail window prints on its way out.
+ *
+ * THE THRESHOLD CARRIES A MARGIN. `rowOf` is an ESTIMATE, and the one available
+ * (`layout/virtual-window.ts::estimateEntryRows`) under-counts a `#` heading and a code
+ * block. The margin in `SCROLLBACK_LIMITS.tailAnchorSlackRows` absorbs that error on the
+ * `bottom` side, the only direction that cannot clip something new.
+ *
+ * PURE: no Ink, no I/O, no clock, and deliberately no import of `virtual-window.ts` (its
+ * import graph reaches a `.tsx` gutter). The row height is injected, so this stays three
+ * parameters and a unit test can drive it with any table it likes.
+ */
+import { SCROLLBACK_LIMITS } from './limits.js';
+/**
+ * Which alignment the live tail should use for the entries it is about to render.
+ *
+ * @param entries The entries THIS FRAME renders (already windowed by `selectTailEntries`;
+ * summing the whole conversation would make every session past the entry cap overflow and
+ * anchor to the bottom forever).
+ * @param budgetRows Height of the box that will clip them, in rows.
+ * @param rowOf Estimated height of one entry, including its separation row.
+ * @returns `top` when the estimates plus `tailAnchorSlackRows` fit in `budgetRows`,
+ * `bottom` otherwise (and for the first entry that does not fit, so the loop stops early).
+ */
+export function tailAnchor(entries, budgetRows, rowOf) {
+    const budget = Number.isFinite(budgetRows) ? Math.max(0, Math.floor(budgetRows)) : 0;
+    let rows = 0;
+    for (const entry of entries) {
+        rows += Math.max(0, rowOf(entry));
+        if (rows + SCROLLBACK_LIMITS.tailAnchorSlackRows > budget)
+            return 'bottom';
+    }
+    return 'top';
+}
+/**
+ * The anchor this frame really uses: MEASURED when the measurement exists, estimated
+ * otherwise.
+ *
+ * WHY A MEASURED ANSWER WINS (tui-final-reply-truncated-unscrollable). The estimate is an
+ * upper bound that charges a separation row this renderer may not draw, so it can claim the
+ * content overflows while it actually fits (the block sits at the bottom of a half-empty
+ * box - the very complaint `tui-first-reply-bottom-aligned` answered) and it under-counts a
+ * heading or a wrapped code block, so it can claim the content fits while the box is really
+ * clipping. The second error is the expensive one now: "top give-way" only prints while the
+ * box is bottom-anchored (that is the branch that clips the TOP), so a wrongly top-anchored
+ * box would clip the newest rows and print the oldest ones - the wrong half, twice.
+ *
+ * A measured total is available only when every window entry is stable AND already measured
+ * at the current geometry (`use-scrollback-view.ts` keeps that cache), which is exactly the
+ * frame on which a print decision is being made. Every other frame - streaming, resize,
+ * first sight of a new entry - falls back to the estimate, unchanged.
+ *
+ * @param measuredRows Measured height of the same entries, or `undefined` when unknown.
+ */
+export function resolveTailAnchor(input) {
+    const { entries, budgetRows, rowOf, measuredRows } = input;
+    if (measuredRows === undefined || !Number.isFinite(measuredRows)) {
+        return tailAnchor(entries, budgetRows, rowOf);
+    }
+    const budget = Number.isFinite(budgetRows) ? Math.max(0, Math.floor(budgetRows)) : 0;
+    return measuredRows > budget ? 'bottom' : 'top';
+}

package/dist/ui/scrollback/tail-window.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The TAIL WINDOW of the native-scroll live region
+ * (tui-full-height-live-region D6 / D7, I-F8 / I-F9).
+ *
+ * WHAT CHANGED AND WHY. The region used to show only the entries the reducer had not
+ * finished writing (`entries.slice(settledCount)`), and everything settled was printed
+ * into the terminal's scrollback the moment it settled. Once the region is the WHOLE
+ * screen (`liveRows = rows - 1`), a printed row is pushed off the top by the very next
+ * frame, so "print on settle" would leave the user staring at a screen of blanks with
+ * only the unfinished cards on it. So the region now shows the last `K` PRINTABLE
+ * entries - settled or not - and an entry is printed when it LEAVES that window.
+ *
+ * The window is defined by ENTRY COUNT, never by measured height; what a single entry
+ * taller than the region used to do is the whole subject of
+ * `overflow-print.ts` (tui-final-reply-truncated-unscrollable). The box still clips it
+ * from the top with `justifyContent="flex-end"`, but the rows it hides are now PRINTED
+ * into the terminal's scrollback, where the wheel already reaches, instead of waiting for
+ * `K` further entries (README, known limitation 2 - rewritten by that fix).
+ *
+ * PURE: no Ink, no I/O, no clock. `promote()` (the writer's only feeder) takes
+ * `printBoundary`'s result and keeps its own `printed` authority, so "printed is
+ * forward-only" (RV-7) is unchanged.
+ *
+ * PRINTABILITY != VISIBILITY. `isExcluded` entries (a non-terminal `service` card) never
+ * print and never take a slot in the window; an entry that is in the window may still be
+ * scrolled out of sight by a taller neighbour. That second gap is what the row-level plan
+ * closes, and `/perf`'s `window=<start>/<n> head=<rows>` is how it stays observable.
+ */
+import type { Entry } from '../../agent/reducer.js';
+export interface TailWindow {
+    /** First index of the window inside the full entry list. */
+    start: number;
+    /** Entries inside the window, oldest first (excluded entries already dropped). */
+    entries: readonly Entry[];
+}
+/**
+ * The index of the first entry that is still on screen: count backwards up to
+ * `maxEntries` PRINTABLE entries. Everything before it has left the region and is the
+ * writer's business.
+ *
+ * `maxEntries <= 0` returns `entries.length` - an empty window, which is the old
+ * behaviour ("everything printable may print") and the reason the guard is written as
+ * an early return rather than as a loop bound.
+ */
+export declare function tailWindowStart(entries: readonly Entry[], maxEntries: number): number;
+/** `entries.slice(start)` with the entries that never print dropped. */
+export declare function selectTailWindow(entries: readonly Entry[], maxEntries: number): TailWindow;
+/**
+ * The print boundary: never print what the region is still showing.
+ *
+ * THIS IS THE ONLY PLACE THAT COMBINES "settled" WITH "in the window" (RV-P2-13), which
+ * is why the composition lives here instead of at the pump: `promote()` must keep
+ * receiving one number, and the two authorities it is derived from - `settledCount`
+ * (what may print at all) and `tailWindowStart` (what is still visible) - then cannot
+ * drift apart in a future edit.
+ *
+ * `settleAllEntries` is the OTHER authority, not a duplicate: it answers "what must be
+ * printed when the conversation is being torn down", while this answers "how far may
+ * this frame print".
+ */
+export declare function printBoundary(entries: readonly Entry[], runActive: boolean, maxEntries: number): number;