@aragon-agent/cli 0.6.33 → 0.6.34

package/dist/commands/perf.d.ts

@@ -84,6 +84,16 @@ export interface BandPerf {
      */
     windowStart: number;
     windowEntries: number;
+    /**
+     * Rows the TOP GIVE-WAY has printed for entries that are still inside the window.
+     *
+     * `window=` says what the region holds; `head=` says how much of it the region could
+     * not show and therefore gave back to the terminal scrollback
+     * (tui-final-reply-truncated-unscrollable). Zero is the healthy answer for a
+     * conversation that always fits; a growing number means the box is smaller than the
+     * reply, which is exactly the state that used to be unrecoverable.
+     */
+    headRows: number;
 }
 /**
  * Why the right-edge scrollbar is or is not usable, in one record

package/dist/commands/perf.js

@@ -139,7 +139,7 @@ function formatBandLine(band) {
         `tail=${band.previewRows} pool=${band.bandRows} ` +
         `cols=${band.contentCols}/${band.previewCols} ` +
         `reason=${band.reason} held=${band.heldRailRows}/${band.heldTeamRows} ` +
-        `window=${band.windowStart}/${band.windowEntries}`;
+        `window=${band.windowStart}/${band.windowEntries} head=${band.headRows}`;
 }
 /**
  * Format a snapshot as the seven-line block documented in §5.4 (plus the scrollbar

package/dist/ui/App.js

@@ -2102,12 +2102,30 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             // `ctrl+o log` hint, the keystroke would silently expand AN OLDER TOOL
             // CARD, and nothing would error. The terminal one-row record is skipped -
             // it has nothing to reveal, and expanding it would consume the press.
-            const last = [...stateRef.current.entries]
+            //
+            // TWO TIERS, AND THE ORDER IS THE WHOLE FIX (tui-final-reply-truncated-
+            // unscrollable B1). The closed list above answers "which card is this key for",
+            // and it must keep answering it EXACTLY as before: a settled answer is almost
+            // always the newest entry, so adding `assistant` to THIS filter would take the
+            // press away from the tool card the user just watched finish. Only when no card
+            // is asking for the key does it fall through to the Agent's last answer - which
+            // is the escape hatch `docs/plans/tui-full-height-live-region/spec.md` §13
+            // (known limitation 2) already promised and never wired up.
+            const entries = stateRef.current.entries;
+            const card = [...entries]
                 .reverse()
                 .find((e) => e.kind === 'tool' ||
                 e.kind === 'team' ||
                 e.kind === 'compaction' ||
                 (e.kind === 'service' && !e.terminal));
+            // NATIVE MODE ONLY. The fallback exists because native mode cannot scroll inside the
+            // frame - the answer's head is reachable only if it is printed. Full-screen mode has a
+            // viewport that already reaches it, and it has no `expanded` rendering for an answer,
+            // so falling through there would consume the press and show nothing.
+            const answer = card === undefined && native
+                ? [...entries].reverse().find((e) => e.kind === 'assistant' && !e.streaming)
+                : undefined;
+            const last = card ?? answer;
             // Native mode cannot rewrite what is already printed, so it PRINTS an expanded
             // copy as a new block instead of toggling the old one (spec 4.7).
             if (last && native) {
@@ -2339,6 +2357,10 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
         itemCount: state.todos?.items.length ?? 0,
         panelEnabled: cfg.todo.panel,
         teamRowsNatural: teamLayout.rowCount,
+        // The top give-way measures a window entry's height, and an expanded tool card is a
+        // different height from a collapsed one - a forgotten value would print rows the region
+        // is not drawing.
+        expandedToolIds: state.expandedToolIds,
     });
     scrollbackViewRef.current = scrollbackView;
     // The two hooks `cli.tsx` calls from OUTSIDE React: the exit summary (every exit
@@ -2436,9 +2458,11 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
                 contentCols: nativeBudget.contentCols,
                 // The tail window, joined here because it belongs to the VIEW pipeline rather
                 // than to the band: `window=<start>/<n>` is what makes the visible-vs-printed
-                // gap observable (known limitation 5).
+                // gap observable (known limitation 5), and `head=` counts the rows the top
+                // give-way printed for it, so the mechanism is never invisible.
                 windowStart: scrollbackView.windowStart,
                 windowEntries: scrollbackView.tailEntries.length,
+                headRows: scrollbackView.headRows,
             }
             : null,
         // A getter: the bridge's `frameReady` and geometry change outside React renders.
@@ -2584,7 +2608,7 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             // fallback for a frame with no preview rows. The WHOLE list is passed: the window
             // belongs to `tail-window.ts`, and `prev` must come from the same list.
             tail: nativeBudget.band.previewRows > 0
-                ? (_jsx(LiveTail, { entries: state.entries, maxEntries: SCROLLBACK_LIMITS.liveTailMaxEntries, rows: nativeBudget.band.previewRows, cols: nativeBudget.previewCols, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: viewReducedMotion, density: cfg.density, nowSec: nowSec, theme: theme, caps: caps }))
+                ? (_jsx(LiveTail, { entries: state.entries, maxEntries: SCROLLBACK_LIMITS.liveTailMaxEntries, rows: nativeBudget.band.previewRows, cols: nativeBudget.previewCols, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: viewReducedMotion, density: cfg.density, nowSec: nowSec, theme: theme, caps: caps, measuredRows: scrollbackView.measuredTailRows }))
                 : undefined, team: nativeTeam, rail: nativeRail, composer: composer, status: statusNode, details: detailsNode, placeholder: _jsxs(Text, { wrap: "truncate", color: theme.noticeWarn, children: [glyphs.warn, " Terminal too small - needs at least 40 columns and 12 rows."] }), theme: theme }));
     }
     return (_jsx(AppShell, { inactive: tooSmall, placeholder: _jsxs(Text, { wrap: "truncate", color: theme.noticeWarn, children: [glyphs.warn, " Terminal too small - needs at least 40 columns and 12 rows."] }), rows: rows, cols: cols, header: header, viewport: viewport, viewportRows: frameBudget.viewportRows, composer: composer, composerSlotRows: frameBudget.composerSlotRows, statusRows: frameBudget.statusRows, details: detailsNode, status: statusNode }));

package/dist/ui/ScrollbackShell.d.ts

@@ -29,20 +29,30 @@
  * content would make the region taller than `budget.liveRows`, and a frame as tall as
  * the terminal makes Ink erase the user's scrollback.
  *
- * TWO SLOTS ARE NOT BOTTOM-ALIGNED, AND ONLY TWO (D3 / D4 / I-F7):
+ * THE BAND'S PREVIEW BOX IS TOP-ALIGNED; THE OTHER SLOTS ARE FIXED
+ * (D3 / D4 / I-F7; tui-first-reply-bottom-aligned, plan A-prime):
  *  - `header` is the fixed 1-row slot at the very top. It is NOT printed into the
  *    scrollback any more: at `H = rows - 1` any printed row is pushed off the screen by
  *    the next frame, so "print the header" would mean "the header is never visible".
- *  - `opener` is the empty-session card, and it is the one thing inside the band that is
- *    TOP-aligned: a 12-row card bottom-aligned in a 24-row column would leave 12 blank
- *    rows in the upper half of the screen - the original defect, still inside the
- *    region, where the `gap` assertion could not see it. `opener` and `tail` are
- *    mutually exclusive by construction (`App` keys them off `entries.length === 0`),
- *    and they share one box because two boxes would be one more height to get wrong.
+ *  - the band's preview box is TOP-aligned unconditionally, which is why the alignment is
+ *    no longer a function of `opener`. `opener` is a 12-row card in a 24-row column, so
+ *    bottom-aligning it left 12 blank rows in the upper half of the screen - the original
+ *    defect, still inside the region, where the `gap` assertion could not see it
+ *    (RV-P0-1). `tail` had the same shape for a short conversation: four rows pressed
+ *    against the composer with every unused row ABOVE them, which is the defect plan
+ *    A-prime fixes. `tail` therefore decides its own alignment one level down
+ *    (`scrollback/tail-anchor.ts`): top while its content fits, and the old `flex-end`
+ *    only on the frames where the content overflows and the newest row must stay visible.
+ *    `opener` and `tail` share this box because two boxes would be one more height to
+ *    get wrong, and they are mutually exclusive by construction (`App` keys them off
+ *    `entries.length === 0`).
  *
  * `liveTailLines` STAYS. It is the plain-text fallback for the frames where the real
  * tail is not mounted (and the floor of the measurement path); `tail` wins when both
- * are given, so the two can never be drawn on top of each other.
+ * are given, so the two can never be drawn on top of each other. It is sliced to
+ * `budget.liveTailRows` below, which is the same number as `band.previewRows`: that slice
+ * is what makes the unconditional `flex-start` safe here, because a fallback taller than
+ * the box would clip its NEWEST line - the one direction this box must never clip.
  */
 import React from 'react';
 import type { Theme } from './theme.js';
@@ -60,8 +70,8 @@ export interface ScrollbackShellProps {
     /** Plain preview rows: the fallback when `tail` is absent (and what `/perf` counts). */
     liveTailLines: readonly string[];
     /**
-     * The empty-session card. Mutually exclusive with `tail`, TOP-aligned, and the only
-     * thing in this shell that is not bottom-aligned or a fixed slot (RV-P0-1).
+     * The empty-session card. Mutually exclusive with `tail`, TOP-aligned like the rest of
+     * the band's preview box (RV-P0-1).
      */
     opener?: React.ReactNode;
     /** Real components for the tail window (`LiveTail`). */

package/dist/ui/ScrollbackShell.js

@@ -6,13 +6,14 @@ export function ScrollbackShell({ budget, header, overlay, liveTailLines, opener
         return (_jsx(Box, { flexDirection: "column", height: budget.liveRows, width: width, overflow: "hidden", flexShrink: 0, children: budget.liveRows > 0 ? placeholder : null }));
     }
     const band = budget.band;
-    // `opener ?? tail ?? lines` is ONE slot, not three: whichever is mounted decides the
-    // alignment of the box, so the two can never both be drawn and fight for the height.
+    // `opener ?? tail ?? lines` is ONE slot, not three: they are mutually exclusive, so
+    // the two can never both be drawn and fight for the height. This box's alignment is
+    // fixed (`flex-start`); `tail` alone may fall back to `flex-end` when it overflows.
     const leftColumn = opener ?? tail;
     const tailLines = liveTailLines.slice(-budget.liveTailRows);
     // The overlay and the band are alternatives, not siblings: the band reports
     // `bandRows = remaining` for an overlay frame, so drawing both would double the
     // region's height and take the frame to the terminal height (the `ESC[3J` case).
-    const top = band.reason === 'overlay' ? (_jsx(Box, { flexDirection: "column", height: budget.overlayRows, flexShrink: 0, overflow: "hidden", children: overlay })) : band.bandRows > 0 ? (_jsxs(Box, { flexDirection: "row", height: band.bandRows, flexShrink: 0, overflow: "hidden", children: [_jsxs(Box, { flexDirection: "column", width: budget.previewCols, flexShrink: 0, overflow: "hidden", children: [band.teamRows > 0 && (_jsx(Box, { height: band.teamRows, flexShrink: 0, overflow: "hidden", children: team })), band.previewRows > 0 && (_jsx(Box, { flexDirection: "column", height: band.previewRows, flexShrink: 0, justifyContent: opener ? 'flex-start' : 'flex-end', overflow: "hidden", children: leftColumn ?? tailLines.map((line, index) => (_jsx(Text, { wrap: "truncate", color: theme.muted, children: line }, index))) }))] }), band.railRows > 0 && (_jsx(Box, { height: band.railRows, width: band.railCols, flexShrink: 0, overflow: "hidden", children: rail }))] })) : null;
+    const top = band.reason === 'overlay' ? (_jsx(Box, { flexDirection: "column", height: budget.overlayRows, flexShrink: 0, overflow: "hidden", children: overlay })) : band.bandRows > 0 ? (_jsxs(Box, { flexDirection: "row", height: band.bandRows, flexShrink: 0, overflow: "hidden", children: [_jsxs(Box, { flexDirection: "column", width: budget.previewCols, flexShrink: 0, overflow: "hidden", children: [band.teamRows > 0 && (_jsx(Box, { height: band.teamRows, flexShrink: 0, overflow: "hidden", children: team })), band.previewRows > 0 && (_jsx(Box, { flexDirection: "column", height: band.previewRows, flexShrink: 0, justifyContent: "flex-start", overflow: "hidden", children: leftColumn ?? tailLines.map((line, index) => (_jsx(Text, { wrap: "truncate", color: theme.muted, children: line }, index))) }))] }), band.railRows > 0 && (_jsx(Box, { height: band.railRows, width: band.railCols, flexShrink: 0, overflow: "hidden", children: rail }))] })) : null;
     return (_jsxs(Box, { flexDirection: "column", height: budget.liveRows, width: width, overflow: "hidden", flexShrink: 0, children: [budget.headerRows > 0 && (_jsx(Box, { height: budget.headerRows, flexShrink: 0, overflow: "hidden", children: header })), top, _jsx(Box, { flexDirection: "column", height: budget.composerSlotRows, justifyContent: "flex-end", flexShrink: 0, overflow: "hidden", children: composer }), _jsx(Box, { height: budget.statusRows > 0 ? 1 : 0, flexShrink: 0, overflow: "hidden", children: status }), budget.statusRows === 2 && (_jsx(Box, { height: 1, flexShrink: 0, overflow: "hidden", children: details }))] }));
 }

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

@@ -16,7 +16,7 @@
  * frame; the region therefore holds the last `SCROLLBACK_LIMITS.liveTailMaxEntries`
  * PRINTABLE entries, settled or not, and an entry is printed when it LEAVES that window.
  * The window is `tail-window.ts`'s definition; this component only slides it over the
- * list and lets the fixed-height box clip from the top.
+ * list and lets the fixed-height box clip from the top when it overflows.
  *
  * IT RENDERS `EntryView` AND NOTHING ELSE. The mapping from an entry to its component
  * (`assistant` / `tool` / `team` / `todo` / service cards, notice frames, the `null`
@@ -26,12 +26,39 @@
  * left rail glyph and the transcript's would keep it, and the two halves of one screen
  * would disagree about the same entry.
  *
- * `justifyContent="flex-end"` PLUS `overflow="hidden"` IS CORRECTNESS, NOT STYLE: when
- * the content is taller than the budget the rows that get clipped are the OLDEST ones,
- * so the newest line always sits against the composer - the same promise
- * `scrollback/canvas.ts` makes about the live tail. (`ScrollbackShell` flips this to
- * `flex-start` for the empty-session opener, which is the one frame where the content
- * must hug the HEADER instead; it never renders this component.)
+ * TOP-ANCHORED WHILE THE CONTENT FITS, BOTTOM-ANCHORED WHEN IT DOES NOT
+ * (tui-first-reply-bottom-aligned, plan A-prime). A constant `flex-end` is what a user
+ * reports as "the first reply shows up at the bottom": the box is always the whole pool,
+ * so a four-row first turn was pushed against the composer and every unused row sat ABOVE
+ * the conversation. `tailAnchor` therefore sums the estimated height of exactly the
+ * entries this frame renders and asks for `flex-start` while they fit - the conversation
+ * is then written downwards from under the header, the way a terminal writes.
+ *
+ * THE OVERFLOW FRAME STAYS `flex-end`, AND THAT IS THE OTHER HALF OF THE FIX.
+ * `flex-start` PLUS `overflow="hidden"` clips the NEWEST rows (Ink's clip rectangle is
+ * the box's own `[top, top + height]`), and a streaming entry can never be printed into
+ * the scrollback to make up for it (`settled-boundary.ts` holds it unstable, and printed
+ * rows are permanent). `flex-end` clips the OLDEST rows instead, which is the promise
+ * `scrollback/canvas.ts` makes about the live tail: the newest line always sits against
+ * the composer. Those clipped rows are what `overflow-print.ts` prints, which is why the
+ * branch has to be `bottom` before anything is printed - and why `measuredRows` exists.
+ *
+ * THE SWITCH COSTS ONE DOWNWARD MOVE ON A STREAMING FRAME, AND IT IS NOT FREE. The two
+ * branches are only pixel-identical where the content EXACTLY fills the box, and the
+ * estimate cannot know that: `estimateEntryRows` charges every entry a separation row while
+ * `density.ts::separationRows` only draws one above a `user` entry, so the frame that
+ * flips is still a few rows short of the box and the block drops by those rows once -
+ * three on a 30-row terminal (the margin plus that over-count) - before it starts
+ * scrolling up a row per line. Accepted and pinned by
+ * `scrollback-first-reply-anchor.test.tsx`: anchoring to the top until the content
+ * really fills the box is exactly the frame that clips the newest row, and measuring the
+ * box every frame is the cost plan A-prime exists to avoid.
+ *
+ * A SETTLED WINDOW IS MEASURED ANYWAY, so the move is exact there (`measuredRows`).
+ * `use-scrollback-view.ts` has to measure the window to decide what the box hides, and
+ * `resolveTailAnchor` lets that measurement decide the anchor: `flex-end` exactly when the
+ * content is taller than the box. So the glitch above survives only on frames where no
+ * measurement exists yet - every streaming frame, i.e. exactly the case the pin covers.
  *
  * BOUNDED: at most `SCROLLBACK_LIMITS.liveTailMaxEntries` component instances per frame
  * (I-10). That is what keeps the per-frame cost the same order as the full-screen live
@@ -62,6 +89,13 @@ export interface LiveTailProps {
     nowSec?: number;
     theme: Theme;
     caps: TermCapabilities;
+    /**
+     * Measured height of exactly the entries this frame renders, when the owner of the
+     * measurement (`use-scrollback-view.ts`) has it. It decides the anchor INSTEAD of the
+     * estimate - see `resolveTailAnchor`. `undefined` on every frame without a full
+     * measurement, which is every streaming frame: the estimate then decides, as before.
+     */
+    measuredRows?: number;
 }
 export interface TailEntry {
     entry: Entry;
@@ -76,4 +110,4 @@ export interface TailEntry {
  * separation row the transcript shows above the same card.
  */
 export declare function selectTailEntries(entries: readonly Entry[], maxEntries: number): readonly TailEntry[];
-export declare function LiveTail({ entries, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, }: LiveTailProps): React.ReactElement;
+export declare function LiveTail({ entries, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, measuredRows, }: LiveTailProps): React.ReactElement;

package/dist/ui/scrollback/LiveTail.js

@@ -1,8 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Box } from 'ink';
 import { EntryView, nowSecFor } from '../Transcript.js';
+import { estimateEntryRows } from '../layout/virtual-window.js';
 import { SCROLLBACK_LIMITS } from './limits.js';
 import { isExcluded } from './settled-boundary.js';
+import { resolveTailAnchor } from './tail-anchor.js';
 /**
  * The last `maxEntries` printable entries, each with its predecessor.
  *
@@ -25,8 +27,17 @@ export function selectTailEntries(entries, maxEntries) {
     }
     return selected;
 }
-export function LiveTail({ entries, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, }) {
+export function LiveTail({ entries, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, measuredRows, }) {
     const limited = Math.min(maxEntries, SCROLLBACK_LIMITS.liveTailMaxEntries);
     const selected = selectTailEntries(entries, limited);
-    return (_jsx(Box, { flexDirection: "column", height: rows, width: cols, justifyContent: "flex-end", flexShrink: 0, overflow: "hidden", children: selected.map(({ entry, prev }) => (_jsx(EntryView, { entry: entry, prev: prev, expanded: expandedToolIds[entry.id] === true, thinkingVisible: thinkingVisible, reducedMotion: reducedMotion, density: density, nowSec: nowSecFor(entry, nowSec), theme: theme, caps: caps }, entry.id))) }));
+    // `estimateEntryRows` is the estimate the transcript's virtual window already uses, so
+    // the anchor can never disagree with the height the rest of the interface plans for.
+    const estimateRows = (entry) => estimateEntryRows(entry, cols, density, expandedToolIds[entry.id] === true, thinkingVisible);
+    const anchor = resolveTailAnchor({
+        entries: selected.map((tailEntry) => tailEntry.entry),
+        budgetRows: rows,
+        rowOf: estimateRows,
+        measuredRows,
+    });
+    return (_jsx(Box, { flexDirection: "column", height: rows, width: cols, justifyContent: anchor === 'top' ? 'flex-start' : 'flex-end', flexShrink: 0, overflow: "hidden", children: selected.map(({ entry, prev }) => (_jsx(EntryView, { entry: entry, prev: prev, expanded: expandedToolIds[entry.id] === true, thinkingVisible: thinkingVisible, reducedMotion: reducedMotion, density: density, nowSec: nowSecFor(entry, nowSec), theme: theme, caps: caps }, entry.id))) }));
 }

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

@@ -39,6 +39,22 @@ export declare const SCROLLBACK_LIMITS: {
      * blank band between the result and the running card.
      */
     readonly liveTailMaxEntries: 10;
+    /**
+     * Safety margin the live tail asks for before it anchors its content to the TOP of
+     * the region (tui-first-reply-bottom-aligned, plan A-prime; the decision itself is
+     * `tail-anchor.ts`).
+     *
+     * 2 is DERIVED, not a preference. The anchor is decided from
+     * `layout/virtual-window.ts::estimateEntryRows`, which charges one separation row per
+     * entry and counts RAW markdown lines - so it UNDER-estimates a `#` heading (which
+     * also draws an `hrule`) and a code block (whose rail narrows the text by two columns,
+     * making long lines wrap). Inside a virtual window that error self-corrects when the
+     * entry is measured; the live region has no measurement pass, so the same error would
+     * decide which rows get CLIPPED - and `flex-start` clips the NEWEST rows.
+     * The margin must therefore always stay on the `bottom` side: a needless fallback
+     * costs one stacked frame, an early anchor hides the text the user is waiting for.
+     */
+    readonly tailAnchorSlackRows: 2;
     /**
      * Rows the rail needs before the band will show it: `TODO_LIMITS.panelMinRows + 1`.
      *

package/dist/ui/scrollback/limits.js

@@ -39,6 +39,22 @@ export const SCROLLBACK_LIMITS = {
      * blank band between the result and the running card.
      */
     liveTailMaxEntries: 10,
+    /**
+     * Safety margin the live tail asks for before it anchors its content to the TOP of
+     * the region (tui-first-reply-bottom-aligned, plan A-prime; the decision itself is
+     * `tail-anchor.ts`).
+     *
+     * 2 is DERIVED, not a preference. The anchor is decided from
+     * `layout/virtual-window.ts::estimateEntryRows`, which charges one separation row per
+     * entry and counts RAW markdown lines - so it UNDER-estimates a `#` heading (which
+     * also draws an `hrule`) and a code block (whose rail narrows the text by two columns,
+     * making long lines wrap). Inside a virtual window that error self-corrects when the
+     * entry is measured; the live region has no measurement pass, so the same error would
+     * decide which rows get CLIPPED - and `flex-start` clips the NEWEST rows.
+     * The margin must therefore always stay on the `bottom` side: a needless fallback
+     * costs one stacked frame, an early anchor hides the text the user is waiting for.
+     */
+    tailAnchorSlackRows: 2,
     /**
      * Rows the rail needs before the band will show it: `TODO_LIMITS.panelMinRows + 1`.
      *

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. */