@aragon-agent/cli 0.6.31 → 0.6.33

package/dist/ui/screen.d.ts

@@ -74,6 +74,15 @@ export declare function enterAltScreen(stdout: NodeJS.WriteStream | undefined, o
 export interface NativeScreenOptions {
     /** Same discipline as `AltScreenOptions.bracketedPaste`: a filter that consumes it exists. */
     readonly bracketedPaste?: boolean;
+    /**
+     * Line feeds to write BEFORE anything else, so the first batch starts from the
+     * bottom row of the screen (tui-bottom-anchored-live-region D4 rung 2).
+     *
+     * `cli.tsx` passes `rows - 1` when the cursor probe could not measure the
+     * position, and `0` when it did. Filling on a measured terminal would undo the
+     * measurement — and cost the page-flip this feature exists to avoid.
+     */
+    readonly anchorFillRows?: number;
 }
 /**
  * Native-scroll mode's counterpart of `enterAltScreen` (tui-native-terminal-scroll
@@ -81,10 +90,14 @@ export interface NativeScreenOptions {
  * the conversation lands in the terminal's own scrollback; there is no alternate
  * screen, no mouse reporting and no DEC 1007 save/restore.
  *
- * The only mode it touches is DEC 2004 (bracketed paste), which changes how input
- * is encoded and has nothing to do with scrolling. Returns the SAME `ScreenHandle`
- * shape, so the four idempotent restore paths in `cli.tsx` need not know which mode
- * is running. A non-TTY stdout is a hard no-op, like `enterAltScreen`.
+ * The only modes it touches are DEC 2004 (bracketed paste), which changes how input
+ * is encoded and has nothing to do with scrolling, and — when the bottom anchor could
+ * not be measured — the one-off fill that puts the cursor on the last row. Returns the
+ * SAME `ScreenHandle` shape, so the four idempotent restore paths in `cli.tsx` need not
+ * know which mode is running. A non-TTY stdout is a hard no-op, like `enterAltScreen`.
+ *
+ * ORDER IS LOAD-BEARING: the fill goes FIRST. Written after `?2004h` it would be the
+ * same bytes, but written after any content it would scroll that content away.
  */
 export declare function enterNativeScreen(stdout: NodeJS.WriteStream | undefined, options?: NativeScreenOptions): ScreenHandle;
 /**

package/dist/ui/screen.js

@@ -11,6 +11,7 @@
  * Hoisting it into `buildProgram()` / `parseAsync` would push `\x1b[?1049h`
  * into `aragon -p "…" > out.txt`, `aragon config set`, and `aragon --version`.
  */
+import { fillBytes } from './scrollback/writer-shapes.js';
 const ENTER_ALT = '\x1b[?1049h';
 const LEAVE_ALT = '\x1b[?1049l';
 const CURSOR_HOME = '\x1b[H';
@@ -187,17 +188,24 @@ export function enterAltScreen(stdout, options = { mouse: false }) {
  * the conversation lands in the terminal's own scrollback; there is no alternate
  * screen, no mouse reporting and no DEC 1007 save/restore.
  *
- * The only mode it touches is DEC 2004 (bracketed paste), which changes how input
- * is encoded and has nothing to do with scrolling. Returns the SAME `ScreenHandle`
- * shape, so the four idempotent restore paths in `cli.tsx` need not know which mode
- * is running. A non-TTY stdout is a hard no-op, like `enterAltScreen`.
+ * The only modes it touches are DEC 2004 (bracketed paste), which changes how input
+ * is encoded and has nothing to do with scrolling, and — when the bottom anchor could
+ * not be measured — the one-off fill that puts the cursor on the last row. Returns the
+ * SAME `ScreenHandle` shape, so the four idempotent restore paths in `cli.tsx` need not
+ * know which mode is running. A non-TTY stdout is a hard no-op, like `enterAltScreen`.
+ *
+ * ORDER IS LOAD-BEARING: the fill goes FIRST. Written after `?2004h` it would be the
+ * same bytes, but written after any content it would scroll that content away.
  */
 export function enterNativeScreen(stdout, options = {}) {
     if (!stdout || !stdout.isTTY || typeof stdout.write !== 'function')
         return NOOP_HANDLE;
     const bracketedPaste = options.bracketedPaste === true;
-    if (bracketedPaste)
-        safeWrite(stdout, ENABLE_BRACKETED_PASTE);
+    const fillRows = Math.max(0, Math.floor(options.anchorFillRows ?? 0));
+    const head = (fillRows > 0 ? fillBytes(fillRows) : '') +
+        (bracketedPaste ? ENABLE_BRACKETED_PASTE : '');
+    if (head.length > 0)
+        safeWrite(stdout, head);
     let restored = false;
     return {
         restore() {

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

@@ -0,0 +1,79 @@
+/**
+ * LiveTail - the band's TAIL WINDOW, rendered with the real entry components
+ * (release-gate-and-native-panels §6.5, tui-full-height-live-region D6).
+ *
+ * WHY THIS FILE EXISTS. Native scroll mode cannot print an entry until it settles, so
+ * the live region used to show `buildLivePreview`'s plain-text projection - and for a
+ * running dispatch that projection is four grey rows saying `Team: 2/4 running`. That
+ * is the "simple look" the feature was opened for. A text-only region can never fix
+ * it, which is why the region's content type changed from `readonly string[]` to a
+ * fixed-height box that can hold components.
+ *
+ * IT SHOWS THE CONVERSATION, NOT JUST THE UNFINISHED PART (D6/D7). The input used to be
+ * `entries.slice(settledCount)` - the entries the reducer had not finished writing -
+ * because everything settled was printed into the scrollback immediately. Now the region
+ * is the whole screen, `H = rows - 1`, so a printed row is pushed off the top by the next
+ * 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.
+ *
+ * IT RENDERS `EntryView` AND NOTHING ELSE. The mapping from an entry to its component
+ * (`assistant` / `tool` / `team` / `todo` / service cards, notice frames, the `null`
+ * cases) lives in `Transcript.tsx` exactly once, together with `EntryFrame`'s gutter,
+ * the separation rows, the per-entry `nowSecFor` clock and the memo comparator. A
+ * second enumeration here would be a copy that drifts: the band's cards would lose the
+ * 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.)
+ *
+ * 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
+ * tail; growing it makes the cost grow linearly because this box has no windowing.
+ */
+import React from 'react';
+import type { Entry } from '../../agent/reducer.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { DensityMode } from '../density.js';
+import type { Theme } from '../theme.js';
+export interface LiveTailProps {
+    /**
+     * The whole entry list (settled and unfinished alike); the window is taken here.
+     * Callers must not pre-slice it: `prev` has to come from the same list the transcript
+     * draws, or the top card of the band loses the separator row it has upstairs.
+     */
+    entries: readonly Entry[];
+    /** Render only the last N entries; the box clips the older ones from the top. */
+    maxEntries: number;
+    /** Fixed height: the root box's `height`. The content never decides it (I-4). */
+    rows: number;
+    /** `budget.previewCols` - the width left after the rail took its column (I-5). */
+    cols: number;
+    expandedToolIds: Record<string, true>;
+    thinkingVisible: boolean;
+    reducedMotion: boolean;
+    density: DensityMode;
+    nowSec?: number;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export interface TailEntry {
+    entry: Entry;
+    /** The entry before it in the passed list: `EntryView` decides the separator from it. */
+    prev: Entry | undefined;
+}
+/**
+ * The last `maxEntries` printable entries, each with its predecessor.
+ *
+ * `prev` must come from the same COMPLETE list rather than from the truncated slice, or
+ * the first rendered entry would look like the head of the conversation and drop the
+ * 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;

package/dist/ui/scrollback/LiveTail.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from 'ink';
+import { EntryView, nowSecFor } from '../Transcript.js';
+import { SCROLLBACK_LIMITS } from './limits.js';
+import { isExcluded } from './settled-boundary.js';
+/**
+ * The last `maxEntries` printable entries, each with its predecessor.
+ *
+ * `prev` must come from the same COMPLETE list rather than from the truncated slice, or
+ * the first rendered entry would look like the head of the conversation and drop the
+ * separation row the transcript shows above the same card.
+ */
+export function selectTailEntries(entries, maxEntries) {
+    const printable = entries.filter((entry) => !isExcluded(entry));
+    const limit = Number.isFinite(maxEntries) ? Math.max(0, Math.floor(maxEntries)) : 0;
+    if (limit === 0)
+        return [];
+    const start = Math.max(0, printable.length - limit);
+    const selected = [];
+    for (let index = start; index < printable.length; index += 1) {
+        selected.push({
+            entry: printable[index],
+            prev: index > 0 ? printable[index - 1] : undefined,
+        });
+    }
+    return selected;
+}
+export function LiveTail({ entries, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, }) {
+    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))) }));
+}

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

@@ -0,0 +1,114 @@
+/**
+ * Height and column budget of the native-scroll PANEL BAND
+ * (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 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-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.
+ *  - `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).
+ *  - `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
+ * - `remaining` is computed there, and a second copy of it is a second authority.
+ */
+export type BandReason = 
+/** Both panels are on screen. */
+'visible'
+/** No active plan: no rail. Same name and meaning as `TodoRailLayout`'s `'empty'`. */
+ | 'empty'
+/** `cfg.todo.panel === false`. */
+ | 'disabled'
+/** An overlay is open: the band yields to it. */
+ | 'overlay'
+/** `todoRailWidth(contentCols) === 0` (terminal narrower than 76 columns). */
+ | 'narrow'
+/** The remaining rows cannot hold `panelMinRows` for the rail. */
+ | 'short';
+export interface LiveBandInput {
+    /**
+     * `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;
+    /** `state.todos.items.length` (0 = no active plan). */
+    itemCount: number;
+    /** `cfg.todo.panel`. */
+    panelEnabled: boolean;
+    overlayOpen: boolean;
+    /** `buildTeamPanelLayout().rowCount`; 0 when there is nothing to show. */
+    teamRowsNatural: number;
+    /** Hysteresis: the rail rows the previous frame already used. */
+    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: `remaining` in `fill` mode, `teamRows + previewRows` otherwise. */
+    bandRows: number;
+    teamRows: number;
+    previewRows: number;
+    /** Row budget of the rail: the whole band (the rail spans it). 0 when hidden. */
+    railRows: number;
+    /** The input `railCols` when visible, 0 when hidden (`/perf` reads `rail=0x0`). */
+    railCols: number;
+    /** `max(0, contentCols - railCols)`; always sums with `railCols` to `contentCols`. */
+    previewCols: number;
+    /** Hysteresis output, fed back on the next frame. */
+    heldRailRows: number;
+    heldTeamRows: number;
+}
+/**
+ * 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" (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 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 - 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.
+ */
+export declare function buildLiveBand(input: LiveBandInput): LiveBand;

package/dist/ui/scrollback/band.js

@@ -0,0 +1,130 @@
+/**
+ * Height and column budget of the native-scroll PANEL BAND
+ * (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 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-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.
+ *  - `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).
+ *  - `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
+ * - `remaining` is computed there, and a second copy of it is a second authority.
+ */
+import { TODO_LIMITS } from '../../todo/limits.js';
+import { SCROLLBACK_LIMITS } from './limits.js';
+/** Invalid geometry becomes zero, exactly like `layout/team-panel.ts::nonNegativeInt`. */
+function nonNegativeInt(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+/**
+ * Allocate the band. THE ORDER OF THE STEPS IS THE SPECIFICATION - reordering them
+ * changes the priority between "what this run is doing" (rail + roster) and "the
+ * words arriving right now" (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 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 - 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.
+ */
+export function buildLiveBand(input) {
+    const remaining = nonNegativeInt(input.remaining);
+    const contentCols = nonNegativeInt(input.contentCols);
+    const railCols = nonNegativeInt(input.railCols);
+    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,
+            railRows: 0, railCols: 0, previewCols: contentCols, heldRailRows: 0, heldTeamRows: 0,
+        };
+    }
+    const teamCeiling = Math.min(teamRowsNatural, Math.max(0, remaining - TODO_LIMITS.panelMinRows - 1));
+    // THE ROSTER IS SEATED AT ITS NATURAL (CLAMPED) HEIGHT, NOT AT THE REMEMBERED ONE.
+    // Seeding from `heldTeamRows` deadlocks the panel: a fresh dispatch starts with no
+    // memory, so frame one would seat zero rows, remember zero, and no later frame could
+    // ever seat the roster - the panel this feature exists to restore would never appear
+    // (found while implementing; recorded as IF-1 in the spec). The memory below only
+    // ever ADDS height back after a squeeze; it never withholds it.
+    //
+    // 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'
+            : railCols === 0 ? 'narrow'
+                : remaining - teamRows < SCROLLBACK_LIMITS.railBandMinRows ? 'short'
+                    : 'visible';
+    const railVisible = reason === 'visible';
+    // 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 = 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 {
+        reason,
+        bandRows,
+        teamRows,
+        previewRows,
+        railRows,
+        railCols: railColsOut,
+        previewCols: Math.max(0, contentCols - railColsOut),
+        // MONOTONE MEMORY, NOT A SHRINKING ONE (I-6). A rail that collapsed to zero rows
+        // because the terminal shrank for two frames would otherwise come back four rows
+        // shorter and the band would visibly jump on every resize wobble. The RESET points
+        // (an emptied plan, a finished dispatch, a resize) live in the one place that owns
+        // the lifecycle, `use-scrollback-view.ts`; this function only remembers.
+        heldRailRows: Math.max(heldRailRows, railRows),
+        heldTeamRows: Math.max(heldTeamRows, teamRows),
+    };
+}

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

@@ -1,24 +1,54 @@
 /**
- * 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 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
+ * `liveRows <= rows - 1` depend on two numbers happening to agree instead of on the
+ * construction that proves it.
  */
+import { type LiveBand, type LiveBandInput } from './band.js';
 import { type FrameBudgetInput } from '../layout/budget.js';
+/**
+ * Everything the band needs that this module derives for itself: `remaining`,
+ * `contentCols`, `railCols`, `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' | '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;
+    /**
+     * REQUIRED, not optional (the same rule `TeamPanel`'s header records as D-13). An
+     * optional band would mean "forgot to pass it" renders silently without panels -
+     * exactly the defect this feature exists to remove - while a required field is a
+     * compile error at the one place that forgets.
+     */
+    band: ScrollbackBandInput;
 }
 export interface ScrollbackBudget {
     rows: number;
@@ -27,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;
@@ -34,10 +70,15 @@ export interface ScrollbackBudget {
     popupRows: number;
     popupMaxHeight: number;
     overlayRows: number;
+    /** Tail rows: the band's left column below the roster (`= band.previewRows`). */
     liveTailRows: number;
-    /** Rows above the composer: overlay or preview. */
+    /** Rows above the composer: `= band.bandRows = remaining`. */
     topRows: number;
-    /** Total live-region height; what Ink renders. */
+    /** 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;
 }
 export declare function buildScrollbackBudget(input: ScrollbackBudgetInput): ScrollbackBudget;

package/dist/ui/scrollback/budget.js

@@ -1,44 +1,93 @@
 /**
- * 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 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
+ * `liveRows <= rows - 1` depend on two numbers happening to agree instead of on the
+ * construction that proves it.
  */
+import { buildLiveBand } from './band.js';
 import { buildFrameBudget } from '../layout/budget.js';
-import { SCROLLBACK_LIMITS } from './limits.js';
+import { todoRailWidth } from '../layout/rail.js';
+/**
+ * The band of a frame that shows no content at all (below the 40x12 floor, or after
+ * the writer's tall-frame guard tripped). It is a REAL value rather than `undefined`
+ * because `/perf` and the render tests must be able to read the reason on exactly the
+ * frames where something went wrong (I-14 / AC-23).
+ */
+function degradedBand(contentCols) {
+    return {
+        reason: 'short', bandRows: 0, teamRows: 0, previewRows: 0,
+        railRows: 0, railCols: 0, previewCols: contentCols, heldRailRows: 0, heldTeamRows: 0,
+    };
+}
 export function buildScrollbackBudget(input) {
     const base = buildFrameBudget(input);
     const contentCols = Math.max(1, base.cols - 1);
     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,
         };
     }
-    // The full-screen frame spends one row on the header; here it joins the pool.
-    const remaining = Math.max(0, base.viewportRows + base.headerRows);
-    const overlayRows = input.overlayOpen ? remaining : 0;
-    const tailCap = Math.min(SCROLLBACK_LIMITS.maxLiveTailRows, Math.floor(base.rows * SCROLLBACK_LIMITS.liveTailRowShare));
-    const liveTailRows = input.overlayOpen
-        ? 0
-        : Math.max(0, Math.min(Math.floor(input.liveTailWanted), remaining, tailCap));
-    const topRows = overlayRows + liveTailRows;
-    const liveRows = topRows + base.composerSlotRows + base.statusRows;
+    // 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),
+        // 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.
+        overlayOpen: input.overlayOpen,
+    });
+    const overlayRows = band.reason === 'overlay' ? band.bandRows : 0;
+    const liveTailRows = band.previewRows;
+    const topRows = band.bandRows;
     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,
     };
 }