@aragon-agent/cli 0.6.32 → 0.6.34

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

@@ -1,27 +1,33 @@
 /**
  * Height and column budget of the native-scroll PANEL BAND
- * (release-gate-and-native-panels §6.2).
+ * (release-gate-and-native-panels §6.2, tui-full-height-live-region D5).
  *
  * Native scroll mode drops the fixed frame, so it used to drop the panels with it:
  * the TODO rail lived in `AppShell`'s middle band and the subagent roster in the
  * viewport footer, and neither is rendered once `ScrollbackShell` takes over. The
- * band is the replacement - one row pool shared by the roster (`TeamPanel`), the
- * streaming tail and the rail (`TodoPanel`), sitting directly above the composer.
+ * band is the replacement - one row pool shared by the roster (`TeamPanel`), the tail
+ * and the rail (`TodoPanel`), sitting directly above the composer.
+ *
+ * `fill` IS THE FEATURE (D5). In `fill` mode the band takes the WHOLE pool:
+ * `bandRows = remaining`, `railRows = bandRows` (so the rail spans every row the user
+ * can see) and `previewRows = bandRows - teamRows` (so the tail column ends against
+ * the composer). Before `fill`, the band asked for "just enough" rows and every row it
+ * did not ask for became the canvas `gap` - the blank band between the result and the
+ * running card that this feature removes.
  *
  * PURE: no Ink, no clock, no terminal, no config read. Every invariant below is
  * therefore established BY CONSTRUCTION for all input combinations and can be
- * enumerated by a property test (AC-9..AC-14, AC-31):
+ * enumerated by a property test (AC-9..AC-14, AC-34, AC-F3/F4):
  *
  *  - `bandRows <= remaining` and therefore `liveRows <= rows - 1` (I-4). Ink writes
  *    `clearTerminal` - which contains `ESC[3J`, erasing the user's scrollback - as
- *    soon as a frame is as tall as the terminal; that one row is the difference
- *    between a tidy region and data loss.
+ *    soon as a frame is as tall as the terminal.
  *  - `previewCols + railCols === contentCols`, always (AC-10). The rail is a column
  *    INSIDE the region, so the preview loses exactly the columns the rail takes and
  *    nothing else (I-5: printing keeps the full `contentCols`).
  *  - `teamRows > 0` leaves room for the rail plus one preview row (AC-12).
- *  - `previewRows <= previewCap`, so the structural caps
- *    `maxLiveTailRows` / `liveTailRowShare` keep binding (I-10).
+ *  - `fill` mode: `bandRows === remaining`, `railRows === bandRows` when the rail is
+ *    visible, and `teamRows + previewRows === bandRows`.
  *
  * THERE IS EXACTLY ONE CALL SITE: `buildScrollbackBudget` (I-8). This module is
  * exported so it can be tested, not so a second caller can allocate rows of its own
@@ -42,18 +48,14 @@ export type BandReason =
  | 'short';
 export interface LiveBandInput {
     /**
-     * `buildFrameBudget().viewportRows + headerRows`: every row the band may use.
-     * Computed once by `buildScrollbackBudget`; callers must not re-derive it.
+     * `buildFrameBudget().viewportRows`: every row the band may use (the pool). Computed
+     * once by `buildScrollbackBudget`; callers must not re-derive it.
      */
     remaining: number;
     /** `cols - 1`: width of the whole band. `previewCols` is derived from it. */
     contentCols: number;
     /** `todoRailWidth(contentCols)`; `layout/rail.ts` stays the width authority. */
     railCols: number;
-    /** The existing two caps combined: `min(maxLiveTailRows, floor(rows * share))`. */
-    previewCap: number;
-    /** Plain-text rows `buildLivePreview` wants (the measuring authority is unchanged). */
-    previewWanted: number;
     /** `state.todos.items.length` (0 = no active plan). */
     itemCount: number;
     /** `cfg.todo.panel`. */
@@ -65,10 +67,18 @@ export interface LiveBandInput {
     heldRailRows: number;
     /** Hysteresis: the roster rows the previous frame already used. */
     heldTeamRows: number;
+    /**
+     * The band takes the whole pool (native mode: always true, set by the budget).
+     *
+     * A plain boolean rather than "absence of a cap" because the difference is semantic:
+     * with `fill` the allocation is INDEPENDENT of the content (which is what makes the
+     * region the screen), while without it the band is sized to what it has to show.
+     */
+    fill: boolean;
 }
 export interface LiveBand {
     reason: BandReason;
-    /** Band height: `teamRows + previewRows`, or `remaining` for an overlay. */
+    /** Band height: `remaining` in `fill` mode, `teamRows + previewRows` otherwise. */
     bandRows: number;
     teamRows: number;
     previewRows: number;
@@ -85,20 +95,19 @@ export interface LiveBand {
 /**
  * Allocate the band. THE ORDER OF THE STEPS IS THE SPECIFICATION - reordering them
  * changes the priority between "what this run is doing" (rail + roster) and "the
- * words arriving right now" (preview), which is a product decision, not a detail.
+ * words arriving right now" (tail), which is a product decision, not a detail.
  *
  * 0. Normalise every numeric input (`NaN` / `Infinity` / negatives become 0).
  * 1. An open overlay takes the whole pool (the band would otherwise double-count it).
- * 2. Seat the roster first, but never at the cost of the rail plus one preview row:
+ * 2. Seat the roster first, but never at the cost of the rail plus one tail row:
  *    a dispatch is transient, the plan is the shape of the turn, both must fit.
  * 3. Decide the rail's visibility, in the same reason order as `buildTodoRailLayout`.
- * 4. RESERVE the rail's rows (`panelFullRows` floor - the 3-5 row compact form cannot
- *    show which item is running, and the band reaches 6 rows far more often than the
- *    full-screen rail does). A reservation, not the final value: see step 6.
- * 5. The preview takes what is left, clamped by `previewCap`.
- * 6. `bandRows = max(railReserved, teamRows + previewRows)`: with no unsettled
- *    content `previewRows` is 0, yet the rail must still be there (the user is
- *    reading a result and still needs the list).
+ * 4. RESERVE the rail's rows - only when the band is NOT filling. `fill` derives
+ *    `railRows` from `bandRows` in step 7, so the reservation has no consumer there.
+ * 5. The tail takes what is left: the whole column in `fill` mode, `previewWanted`
+ *    clamped by the pool otherwise.
+ * 6. `bandRows`: the pool in `fill` mode, `max(railReserved, teamRows + previewRows)`
+ *    otherwise (where a rail must still be there with no tail rows).
  * 7. Columns: the input `contentCols` is the only width authority.
  * 8. Hand the late-arriving values (the hysteresis) back out for the next frame.
  */

package/dist/ui/scrollback/band.js

@@ -1,27 +1,33 @@
 /**
  * Height and column budget of the native-scroll PANEL BAND
- * (release-gate-and-native-panels §6.2).
+ * (release-gate-and-native-panels §6.2, tui-full-height-live-region D5).
  *
  * Native scroll mode drops the fixed frame, so it used to drop the panels with it:
  * the TODO rail lived in `AppShell`'s middle band and the subagent roster in the
  * viewport footer, and neither is rendered once `ScrollbackShell` takes over. The
- * band is the replacement - one row pool shared by the roster (`TeamPanel`), the
- * streaming tail and the rail (`TodoPanel`), sitting directly above the composer.
+ * band is the replacement - one row pool shared by the roster (`TeamPanel`), the tail
+ * and the rail (`TodoPanel`), sitting directly above the composer.
+ *
+ * `fill` IS THE FEATURE (D5). In `fill` mode the band takes the WHOLE pool:
+ * `bandRows = remaining`, `railRows = bandRows` (so the rail spans every row the user
+ * can see) and `previewRows = bandRows - teamRows` (so the tail column ends against
+ * the composer). Before `fill`, the band asked for "just enough" rows and every row it
+ * did not ask for became the canvas `gap` - the blank band between the result and the
+ * running card that this feature removes.
  *
  * PURE: no Ink, no clock, no terminal, no config read. Every invariant below is
  * therefore established BY CONSTRUCTION for all input combinations and can be
- * enumerated by a property test (AC-9..AC-14, AC-31):
+ * enumerated by a property test (AC-9..AC-14, AC-34, AC-F3/F4):
  *
  *  - `bandRows <= remaining` and therefore `liveRows <= rows - 1` (I-4). Ink writes
  *    `clearTerminal` - which contains `ESC[3J`, erasing the user's scrollback - as
- *    soon as a frame is as tall as the terminal; that one row is the difference
- *    between a tidy region and data loss.
+ *    soon as a frame is as tall as the terminal.
  *  - `previewCols + railCols === contentCols`, always (AC-10). The rail is a column
  *    INSIDE the region, so the preview loses exactly the columns the rail takes and
  *    nothing else (I-5: printing keeps the full `contentCols`).
  *  - `teamRows > 0` leaves room for the rail plus one preview row (AC-12).
- *  - `previewRows <= previewCap`, so the structural caps
- *    `maxLiveTailRows` / `liveTailRowShare` keep binding (I-10).
+ *  - `fill` mode: `bandRows === remaining`, `railRows === bandRows` when the rail is
+ *    visible, and `teamRows + previewRows === bandRows`.
  *
  * THERE IS EXACTLY ONE CALL SITE: `buildScrollbackBudget` (I-8). This module is
  * exported so it can be tested, not so a second caller can allocate rows of its own
@@ -36,20 +42,19 @@ function nonNegativeInt(value) {
 /**
  * Allocate the band. THE ORDER OF THE STEPS IS THE SPECIFICATION - reordering them
  * changes the priority between "what this run is doing" (rail + roster) and "the
- * words arriving right now" (preview), which is a product decision, not a detail.
+ * words arriving right now" (tail), which is a product decision, not a detail.
  *
  * 0. Normalise every numeric input (`NaN` / `Infinity` / negatives become 0).
  * 1. An open overlay takes the whole pool (the band would otherwise double-count it).
- * 2. Seat the roster first, but never at the cost of the rail plus one preview row:
+ * 2. Seat the roster first, but never at the cost of the rail plus one tail row:
  *    a dispatch is transient, the plan is the shape of the turn, both must fit.
  * 3. Decide the rail's visibility, in the same reason order as `buildTodoRailLayout`.
- * 4. RESERVE the rail's rows (`panelFullRows` floor - the 3-5 row compact form cannot
- *    show which item is running, and the band reaches 6 rows far more often than the
- *    full-screen rail does). A reservation, not the final value: see step 6.
- * 5. The preview takes what is left, clamped by `previewCap`.
- * 6. `bandRows = max(railReserved, teamRows + previewRows)`: with no unsettled
- *    content `previewRows` is 0, yet the rail must still be there (the user is
- *    reading a result and still needs the list).
+ * 4. RESERVE the rail's rows - only when the band is NOT filling. `fill` derives
+ *    `railRows` from `bandRows` in step 7, so the reservation has no consumer there.
+ * 5. The tail takes what is left: the whole column in `fill` mode, `previewWanted`
+ *    clamped by the pool otherwise.
+ * 6. `bandRows`: the pool in `fill` mode, `max(railReserved, teamRows + previewRows)`
+ *    otherwise (where a rail must still be there with no tail rows).
  * 7. Columns: the input `contentCols` is the only width authority.
  * 8. Hand the late-arriving values (the hysteresis) back out for the next frame.
  */
@@ -57,12 +62,11 @@ export function buildLiveBand(input) {
     const remaining = nonNegativeInt(input.remaining);
     const contentCols = nonNegativeInt(input.contentCols);
     const railCols = nonNegativeInt(input.railCols);
-    const previewCap = nonNegativeInt(input.previewCap);
-    const previewWanted = nonNegativeInt(input.previewWanted);
     const itemCount = nonNegativeInt(input.itemCount);
     const teamRowsNatural = nonNegativeInt(input.teamRowsNatural);
     const heldRailRows = nonNegativeInt(input.heldRailRows);
     const heldTeamRows = nonNegativeInt(input.heldTeamRows);
+    const fill = input.fill === true;
     if (input.overlayOpen) {
         return {
             reason: 'overlay', bandRows: remaining, teamRows: 0, previewRows: 0,
@@ -76,6 +80,14 @@ export function buildLiveBand(input) {
     // ever seat the roster - the panel this feature exists to restore would never appear
     // (found while implementing; recorded as IF-1 in the spec). The memory below only
     // ever ADDS height back after a squeeze; it never withholds it.
+    //
+    // THE FLOOR SURVIVES `fill` ON PURPOSE (spec §5.3.2; RV-P2-5, recorded as not changed
+    // back). It holds 4 rows back from the roster even when the rail is not drawn, which
+    // looks like waste in `fill` mode - but it is the vetted `AC-12` behaviour, and
+    // `TodoPanel`'s 3-5 row compact form needs those rows to name the running item. The
+    // only visible cost is 4 blank rows at the TOP of the left column (the tail still
+    // ends against the composer), which is not one of the three reported defects; changing
+    // it here would reopen a different feature in the same commit.
     const teamRows = teamCeiling;
     const reason = !input.panelEnabled ? 'disabled'
         : itemCount === 0 ? 'empty'
@@ -83,11 +95,20 @@ export function buildLiveBand(input) {
                 : remaining - teamRows < SCROLLBACK_LIMITS.railBandMinRows ? 'short'
                     : 'visible';
     const railVisible = reason === 'visible';
-    const railReserved = railVisible
+    // NO CONSUMER IN `fill` MODE (step 7 derives `railRows` from `bandRows`); kept as the
+    // documented historical formula so the non-fill allocation stays readable and a future
+    // caller that does not fill cannot silently lose the rail's reservation.
+    const railReserved = railVisible && !fill
         ? Math.min(Math.max(heldRailRows, TODO_LIMITS.panelFullRows), Math.max(0, remaining - teamRows - 1))
         : 0;
-    const previewRows = Math.min(previewWanted, previewCap, Math.max(0, remaining - teamRows - railReserved));
-    const bandRows = Math.max(railReserved, teamRows + previewRows);
+    const previewRows = fill
+        ? Math.max(0, remaining - teamRows)
+        // Non-fill: the tail takes what the rail's reservation leaves. The two row caps that
+        // used to clamp this line (`previewCap` / `previewWanted`) are RETIRED (D9) - they
+        // were the only inputs that made this branch differ from `fill`, so a non-fill caller
+        // now gets the pool too. The branch stays as the named expression of the older policy.
+        : Math.max(0, remaining - teamRows - railReserved);
+    const bandRows = fill ? remaining : Math.max(railReserved, teamRows + previewRows);
     const railRows = railVisible ? bandRows : 0;
     const railColsOut = railVisible ? railCols : 0;
     return {

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

@@ -1,17 +1,26 @@
 /**
- * Height budget of the native-scroll LIVE REGION (tui-native-terminal-scroll §4.6).
+ * Height budget of the native-scroll LIVE REGION
+ * (tui-native-terminal-scroll §4.6, tui-full-height-live-region D1/D3/D5).
  *
  * 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.
+ * as a frame is as tall as the terminal. This feature takes I-S1's ONE row of margin
+ * and nothing else: `liveRows === rows - 1` exactly, which is why the frame-height
+ * guard (I-F13 / AC-F17) exists - there is no slack left to absorb a stray row.
+ *
+ * THE REGION IS THE SCREEN. The region used to be only as tall as the band asked for,
+ * and every row it did not ask for became `gap` - blank rows ABOVE the content, which
+ * is what the user reported as "the app starts halfway down the screen" and as "a big
+ * blank between the result and the running card". The band now takes the whole pool
+ * (`fill`), so the region is `[header][band][composer][status]` top to bottom and
+ * `gap` cannot exist: `resolveCanvasLayout` is given `frameRows === capacity` and
+ * derives `gap = 0` (see the spec's §5.5 proof, which is why the writer needs no
+ * change at all).
  *
  * 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.
+ * editor is. What differs is the top: the header is a real slot here (D3), and the
+ * row it occupies is spent from the region, not from the printed transcript.
  *
  * 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
@@ -22,16 +31,15 @@ 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).
+ * `contentCols`, `railCols`, `overlayOpen` and `fill` are computed below - `fill` is
+ * NOT part of the caller's input (I-8: the budget decides it, and "the band fills the
+ * pool" is not a preference an `App` may hold). The caller supplies only the facts it
+ * alone knows (plan, panel switch, roster size, hysteresis), never a number this
+ * module is supposed to own.
  */
-export type ScrollbackBandInput = Omit<LiveBandInput, 'remaining' | 'contentCols' | 'railCols' | 'previewCap' | 'previewWanted' | 'overlayOpen'>;
+export type ScrollbackBandInput = Omit<LiveBandInput, 'remaining' | 'contentCols' | 'railCols' | 'overlayOpen' | 'fill'>;
 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;
     /**
@@ -49,6 +57,12 @@ export interface ScrollbackBudget {
     contentCols: number;
     /** Terminal below the 40x12 floor: the region is a one-row placeholder. */
     inactive: boolean;
+    /**
+     * The header slot, a real row inside the region (D3). 0 on a degraded frame: the
+     * placeholder draws no header, and reporting 1 there would break the row identity
+     * (I-F4) on exactly the frames `/perf` is read to explain.
+     */
+    headerRows: number;
     statusRows: 0 | 1 | 2;
     composerRows: number;
     composerSlotRows: number;
@@ -56,17 +70,15 @@ export interface ScrollbackBudget {
     popupRows: number;
     popupMaxHeight: number;
     overlayRows: number;
-    /** Preview rows: the band's projection, 0 while an overlay is open. */
+    /** Tail rows: the band's left column below the roster (`= band.previewRows`). */
     liveTailRows: number;
-    /** Rows above the composer: `= band.bandRows` (the identity below is unchanged). */
+    /** Rows above the composer: `= band.bandRows = remaining`. */
     topRows: number;
-    /** Total live-region height; what Ink renders (`topRows + composer + status`). */
+    /** Total live-region height: `rows - 1`, the whole screen above the parked row. */
     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

@@ -1,17 +1,26 @@
 /**
- * Height budget of the native-scroll LIVE REGION (tui-native-terminal-scroll §4.6).
+ * Height budget of the native-scroll LIVE REGION
+ * (tui-native-terminal-scroll §4.6, tui-full-height-live-region D1/D3/D5).
  *
  * 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.
+ * as a frame is as tall as the terminal. This feature takes I-S1's ONE row of margin
+ * and nothing else: `liveRows === rows - 1` exactly, which is why the frame-height
+ * guard (I-F13 / AC-F17) exists - there is no slack left to absorb a stray row.
+ *
+ * THE REGION IS THE SCREEN. The region used to be only as tall as the band asked for,
+ * and every row it did not ask for became `gap` - blank rows ABOVE the content, which
+ * is what the user reported as "the app starts halfway down the screen" and as "a big
+ * blank between the result and the running card". The band now takes the whole pool
+ * (`fill`), so the region is `[header][band][composer][status]` top to bottom and
+ * `gap` cannot exist: `resolveCanvasLayout` is given `frameRows === capacity` and
+ * derives `gap = 0` (see the spec's §5.5 proof, which is why the writer needs no
+ * change at all).
  *
  * 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.
+ * editor is. What differs is the top: the header is a real slot here (D3), and the
+ * row it occupies is spent from the region, not from the printed transcript.
  *
  * 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
@@ -21,7 +30,6 @@
 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`
@@ -37,30 +45,35 @@ function degradedBand(contentCols) {
 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,
+            rows: base.rows, cols: base.cols, contentCols, inactive: true, headerRows: 0,
+            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,
+            band: degradedBand(contentCols), previewCols: contentCols,
         };
     }
-    // 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));
+    // D1 · H = C. `frameRows` is `rows - 1` by construction (`layout/budget.ts`), so the
+    // region ends exactly on the row above the writer's parked cursor.
+    const headerRows = 1;
+    const liveRows = Math.max(1, base.frameRows);
+    // The whole pool: everything between the header and the status line. Two independent
+    // derivations put its floor at 1, so `max(0, ...)` is defensive only:
+    //  1. `composerSlotRows = 2 + clampDraftRows(rows, draftRows)` and
+    //     `draftMaxRows(rows) = max(1, min(6, floor(rows / 4)))`, so on the narrowest
+    //     full-screen frame (`rows = 12`) `remaining >= 11 - 1 - 5 - 1 = 4`;
+    //  2. with the completion menu at its maximum, `popupMaxHeight` already subtracts
+    //     this same pair of rows, so `remaining = popupMaxHeight + 1 - popupRows >= 1`.
+    const remaining = Math.max(0, liveRows - headerRows - base.composerSlotRows - base.statusRows);
     const band = buildLiveBand({
         ...input.band,
         remaining,
         contentCols,
         railCols: todoRailWidth(contentCols),
-        previewCap: tailCap,
-        previewWanted,
+        // The band fills the pool: no row of the region is left blank, which is the whole
+        // point of the feature (D5). Taken from HERE, never from `input.band`.
+        fill: true,
         // 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.
@@ -69,13 +82,12 @@ export function buildScrollbackBudget(input) {
     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,
+        rows: base.rows, cols: base.cols, contentCols, inactive: false, headerRows,
         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,
+        band, previewCols: band.previewCols,
     };
 }

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

@@ -18,19 +18,43 @@ export declare const SCROLLBACK_LIMITS: {
     readonly guardTripCount: 3;
     /** Session summary rows printed on exit. */
     readonly exitSummaryMaxRows: 4;
-    /** Streaming preview rows, absolute cap. */
-    readonly maxLiveTailRows: 12;
-    /** ... and as a share of the terminal height. */
-    readonly liveTailRowShare: 0.4;
     /**
-     * Live-region `EntryView` instances per frame (release-gate-and-native-panels §6.5).
+     * Entries the region may hold on screen at once
+     * (tui-full-height-live-region D6; the WINDOW is defined by I-F8 and computed in
+     * `tail-window.ts`).
      *
-     * A STRUCTURAL CAP of the same kind as `maxLiveTailRows`: a screenful is at most 12
-     * rows plus 4 component instances, so the band costs the same order of magnitude as
-     * the full-screen live tail and the render governor and every `memo` boundary keep
-     * working. Raising it makes the per-frame cost grow linearly with no windowing.
+     * 10 is DERIVED, not a preference. The band's left column is the whole pool
+     * (`pool = rows - 1 - header - composer - status`, i.e. 24 rows on a 30-row
+     * terminal) and one entry occupies about 2.4 rows, so a window of 4 would leave
+     * the column half empty - the blank band this feature removes. It stays in the
+     * per-frame COST class the old value of 4 was measured in: `EntryView` is
+     * memoised and only the streaming entry re-renders, so this bounds component
+     * instances, not per-frame work.
+     *
+     * There is deliberately NO companion row cap any more (retired: the old
+     * `maxLiveTailRows` / `liveTailRowShare` pair). The rows a tail may take are
+     * `band.previewRows` - the whole left column - and "the region can never be
+     * taller than the screen" is `liveRows === rows - 1`'s job (I-F5), not a second
+     * number's. Those two caps disagreed with the pool, and that disagreement WAS the
+     * blank band between the result and the running card.
+     */
+    readonly liveTailMaxEntries: 10;
+    /**
+     * 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 liveTailMaxEntries: 4;
+    readonly tailAnchorSlackRows: 2;
     /**
      * Rows the rail needs before the band will show it: `TODO_LIMITS.panelMinRows + 1`.
      *

package/dist/ui/scrollback/limits.js

@@ -18,19 +18,43 @@ export const SCROLLBACK_LIMITS = {
     guardTripCount: 3,
     /** Session summary rows printed on exit. */
     exitSummaryMaxRows: 4,
-    /** Streaming preview rows, absolute cap. */
-    maxLiveTailRows: 12,
-    /** ... and as a share of the terminal height. */
-    liveTailRowShare: 0.4,
     /**
-     * Live-region `EntryView` instances per frame (release-gate-and-native-panels §6.5).
+     * Entries the region may hold on screen at once
+     * (tui-full-height-live-region D6; the WINDOW is defined by I-F8 and computed in
+     * `tail-window.ts`).
      *
-     * A STRUCTURAL CAP of the same kind as `maxLiveTailRows`: a screenful is at most 12
-     * rows plus 4 component instances, so the band costs the same order of magnitude as
-     * the full-screen live tail and the render governor and every `memo` boundary keep
-     * working. Raising it makes the per-frame cost grow linearly with no windowing.
+     * 10 is DERIVED, not a preference. The band's left column is the whole pool
+     * (`pool = rows - 1 - header - composer - status`, i.e. 24 rows on a 30-row
+     * terminal) and one entry occupies about 2.4 rows, so a window of 4 would leave
+     * the column half empty - the blank band this feature removes. It stays in the
+     * per-frame COST class the old value of 4 was measured in: `EntryView` is
+     * memoised and only the streaming entry re-renders, so this bounds component
+     * instances, not per-frame work.
+     *
+     * There is deliberately NO companion row cap any more (retired: the old
+     * `maxLiveTailRows` / `liveTailRowShare` pair). The rows a tail may take are
+     * `band.previewRows` - the whole left column - and "the region can never be
+     * taller than the screen" is `liveRows === rows - 1`'s job (I-F5), not a second
+     * number's. Those two caps disagreed with the pool, and that disagreement WAS the
+     * blank band between the result and the running card.
+     */
+    liveTailMaxEntries: 10,
+    /**
+     * 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.
      */
-    liveTailMaxEntries: 4,
+    tailAnchorSlackRows: 2,
     /**
      * Rows the rail needs before the band will show it: `TODO_LIMITS.panelMinRows + 1`.
      *

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

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