@aragon-agent/cli 0.6.32 → 0.6.34

package/dist/cli.js

@@ -901,6 +901,10 @@ async function runInteractive(flags, extras = {}) {
         const { writer } = scrollbackBridge;
         setScrollbackStatsProvider(() => ({
             ...writer.scrollbackStats(), regionRows: writer.regionRows(),
+            // The canvas top is already published by `anchorStats()`; `/perf` needs it on the
+            // mode line to explain a region that does not start on row 0 (tui-full-height-
+            // live-region §5.8). Read per call, never cached: `/perf` shows THIS frame.
+            anchorTop: writer.anchorStats().top,
         }));
     }
     // The observer only serves the full-screen scrollbar geometry; native has none.

package/dist/commands/perf.d.ts

@@ -59,14 +59,41 @@ export interface PerfSnapshot {
  */
 export interface BandPerf {
     reason: 'visible' | 'empty' | 'disabled' | 'overlay' | 'narrow' | 'short';
+    /**
+     * The band's height. In the full-height region this IS the pool
+     * (`tui-full-height-live-region` D5), which is why `/perf` prints one `pool=` number
+     * rather than two fields that can only ever be equal.
+     */
+    bandRows: number;
     railRows: number;
     railCols: number;
     teamRows: number;
+    /** The tail column: the rows between the roster and the composer. */
     previewRows: number;
     contentCols: number;
     previewCols: number;
     heldRailRows: number;
     heldTeamRows: number;
+    /**
+     * The tail window: first visible entry index and how many entries are in it.
+     *
+     * The ONLY number that makes "what is on screen" and "what has been printed"
+     * comparable. A long answer can push earlier entries out of sight while they are
+     * still inside the window, so they are neither visible nor printed yet; the readout
+     * turns that disclosed gap (known limitation 5) into a number instead of a guess.
+     */
+    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
@@ -136,8 +163,14 @@ export interface ScrollbackPerf {
     anchorCanvasRows: number;
     /** Content rows inside that canvas — how much of the conversation is on screen. */
     anchorHeldRows: number;
-    /** Blank rows above the content. Non-zero is expected on a short conversation. */
+    /** Blank rows above the content. Zero by construction in the full-height region. */
     anchorGapRows: number;
+    /**
+     * Canvas top row (0-based). 0 means the canvas starts on the terminal's first row and
+     * is the direct answer to "why does the app start halfway down the screen" - the one
+     * number that used to be missing from this block.
+     */
+    anchorTop: number;
     /** Rows this session pushed into the terminal's own scrollback. */
     anchorScrollRows: number;
     /** Times the geometry was dropped on purpose (column change, shrink, geometry lost). */

package/dist/commands/perf.js

@@ -136,8 +136,10 @@ function formatBandLine(band) {
     if (!band)
         return 'band       n/a (full-screen layout)';
     return `band       rail=${band.railRows}x${band.railCols} team=${band.teamRows} ` +
-        `preview=${band.previewRows} cols=${band.contentCols}/${band.previewCols} ` +
-        `reason=${band.reason} held=${band.heldRailRows}/${band.heldTeamRows}`;
+        `tail=${band.previewRows} pool=${band.bandRows} ` +
+        `cols=${band.contentCols}/${band.previewCols} ` +
+        `reason=${band.reason} held=${band.heldRailRows}/${band.heldTeamRows} ` +
+        `window=${band.windowStart}/${band.windowEntries} head=${band.headRows}`;
 }
 /**
  * Format a snapshot as the seven-line block documented in §5.4 (plus the scrollbar
@@ -149,6 +151,11 @@ export function formatPerfReport(snap) {
     const eco = snap.rung > 0 ? '  -  eco' : '';
     const governor = snap.governorEnabled ? '' : '  -  governor off';
     const native = snap.mode === 'native';
+    // The canvas top lives in the writer's counters, not in the snapshot: it is the direct
+    // explanation for "the app starts halfway down", so it belongs on the mode line next
+    // to the region height. `n/a` rather than 0 when no writer is attached, because 0 is a
+    // real and healthy answer.
+    const anchor = native ? scrollbackStats?.() ?? null : null;
     const scrollbar = native
         ? ['scrollbar  n/a (native scroll)']
         : snap.scrollbar ? [formatScrollbarLine(snap.scrollbar)] : [];
@@ -163,7 +170,8 @@ export function formatPerfReport(snap) {
             `hl ${caches.highlightEntries} (${mb(caches.highlightBytes)})  -  ` +
             `lines ${caches.lineEntries}`,
         native
-            ? `mode       native  -  live region ${snap.viewportRows} rows`
+            ? `mode       native  -  live region ${snap.viewportRows} rows  -  ` +
+                `top ${anchor ? anchor.anchorTop : 'n/a'}`
             : `mode       ${snap.mode}  -  viewport ${snap.viewportRows} rows  -  offset ${snap.offset}`,
         formatBandLine(snap.band),
         formatWriterLine(),

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) {
@@ -2293,9 +2311,17 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
         pending: state.pendingSteering, columns: baseRail.contentCols, terminalRows: rows,
         availableRows: Math.max(0, viewportBudget - composerBaseRows - 1), paused: !running,
     }), [state.pendingSteering, baseRail.contentCols, rows, viewportBudget, composerBaseRows, running]);
+    // THE POOL, NOT THE VIEWPORT MINUS A QUEUE THAT IS NOT DRAWN
+    // (tui-full-height-live-region RV-P1-3). `QueuePanel` only mounts in the full-screen
+    // layout, so native mode used to reserve rows for a card nobody paints. And it MUST be
+    // `viewportBudget` rather than `nativeBudget.band.*`: `viewportRows === remaining` by
+    // construction, and reading the band back here would close a loop with `teamRows`
+    // (AC-34, asserted textually by `live-band.test.ts`).
     const teamLayout = buildTeamPanelLayout({
         snapshot: state.team, terminalRows: rows,
-        availableRows: Math.max(0, viewportBudget - composerBaseRows - queueLayout.rows - 1),
+        availableRows: native
+            ? Math.max(0, viewportBudget - 1)
+            : Math.max(0, viewportBudget - composerBaseRows - queueLayout.rows - 1),
     });
     const railLayout = buildTodoRailLayout({
         cols: cols - 1, panelEnabled: cfg.todo.panel, overlayOpen: false,
@@ -2315,14 +2341,14 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     // an inert hook is what keeps `scrollMode: 'app'` byte-identical (I-S9).
     const viewCols = native ? Math.max(1, cols - 1) : cols;
     const header = (_jsx(Header, { columns: viewCols, statusExpanded: statusExpanded, scrolledLines: scrolledLines, overlayOpen: overlay !== null, cwd: controller.getCwd(), provider: cfg.provider, model: cfg.model, hasKey: hasKey, variant: pickHeaderVariant(cols), theme: theme, caps: caps }));
-    // The wordmark + getting-started card now live INSIDE the viewport, as its
-    // first block of content, so they scroll away instead of being yanked out of
-    // the header the moment the first message lands.
-    const opener = empty ? (_jsx(SessionOpener, { variant: pickOpenerVariant(native ? Math.max(0, rows - 8) : viewportBudget, native ? viewCols : contentCols), version: version, cwd: controller.getCwd(), hasKey: hasKey, viewportRows: native ? Math.max(0, rows - 8) : viewportBudget, theme: theme, caps: caps })) : null;
+    // The header and the opener are SLOTS OF THE SHELL, not printed bytes (D3/D4): at
+    // `H = rows - 1` a printed row is pushed off the screen by the very next frame, so
+    // `printBanner()` was a way of making the banner invisible. Neither is passed here.
+    // The opener node is built below, because its height now comes from the native band.
     const scrollbackView = useScrollbackView({
         enabled: native, bridge: scrollback, entries: state.entries, runActive: running,
         theme, caps, density: cfg.density, thinkingVisible: state.thinkingVisible,
-        reducedMotion, rows, cols, headerNode: header, openerNode: opener,
+        reducedMotion, rows, cols,
         overlayOpen: overlay !== null, draftRows, popupRows: overlay ? 0 : popupRows,
         statusExpanded, forceInactive: native && guardTripped,
         // The band's inputs. `teamRowsNatural` is the roster layout computed above, so the
@@ -2331,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
@@ -2352,6 +2382,14 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     }, [native, scrollback, controller, glyphs]);
     useEffect(() => { setGuardTripped(false); }, [rows, cols]);
     const nativeBudget = native ? scrollbackView.budget : null;
+    // THE EMPTY-SESSION CARD, ONE NODE FOR BOTH MODES (D4 / RV-P0-1). The wordmark and the
+    // getting-started card are the first block of content in `app` mode (they scroll away
+    // with the transcript) and the shell's `opener` slot in native mode. Its height used to
+    // be a `rows - 8` guess in native mode; the honest input is the band's own pool, which
+    // is why this node is built after `nativeBudget`.
+    const openerRows = nativeBudget ? nativeBudget.band.bandRows : viewportBudget;
+    const openerCols = nativeBudget ? nativeBudget.previewCols : contentCols;
+    const opener = empty ? (_jsx(SessionOpener, { variant: pickOpenerVariant(openerRows, openerCols), version: version, cwd: controller.getCwd(), hasKey: hasKey, viewportRows: openerRows, theme: theme, caps: caps })) : null;
     const overlayMaxRows = nativeBudget ? nativeBudget.overlayRows : viewportBudget;
     const overlayNode = overlay === 'queue' ? (_jsx(QueueOverlay, { pending: state.pendingSteering, cols: viewCols, maxRows: overlayMaxRows, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps })) : overlay === 'help' ? (_jsx(OverlayFrame, { title: "Help", hint: `Esc close ${glyphs.midDot} PgUp/PgDn scroll`, maxRows: overlayMaxRows, cols: viewCols, rows: helpRows(theme, caps, native), scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps })) : overlay === 'model' ? (_jsx(ModelPicker, { isActive: !tooSmall, registry: controller.getModelRegistry(), currentProvider: cfg.provider, currentModel: cfg.model, maxRows: overlayMaxRows, cols: viewCols, theme: theme, caps: caps, onSelect: handleModelSelect })) : overlay === 'settings' ? (_jsx(SettingsScreen, { isActive: !tooSmall, initial: {
             provider: cfg.provider,
@@ -2415,7 +2453,17 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
         // `null` outside native mode, and `/perf` prints `n/a` for it: a band row of
         // zeroes in full-screen mode would read like a panel that failed to show.
         band: nativeBudget
-            ? { ...nativeBudget.band, contentCols: nativeBudget.contentCols }
+            ? {
+                ...nativeBudget.band,
+                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), 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.
         get scrollbar() {
@@ -2552,11 +2600,15 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             }
             : {}) }));
     if (nativeBudget) {
-        return (_jsx(ScrollbackShell, { budget: nativeBudget, overlay: overlayNode, liveTailLines: scrollbackView.liveTailLines, 
-            // Real components for the unfinished tail (I-7); the plain rows above stay as
-            // the fallback for a frame with no preview rows.
+        // THE OPENER IS MOUNTED ON THE SHELL'S TOP-ALIGNED SLOT (D4 / RV-P0-1): it is sized
+        // from the band's pool above, and bottom-aligning it would reproduce the reported
+        // "blank upper half" INSIDE the region, where the canvas `gap` assertion cannot see it.
+        return (_jsx(ScrollbackShell, { budget: nativeBudget, header: header, overlay: overlayNode, liveTailLines: scrollbackView.liveTailLines, ...(opener ? { opener } : {}), 
+            // Real components for the tail window (I-7); the plain rows above stay as the
+            // 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, { unsettled: scrollbackView.unsettledEntries, 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

@@ -1,14 +1,17 @@
 /**
- * ScrollbackShell — the bounded LIVE REGION of native-scroll mode
- * (tui-native-terminal-scroll §4.6).
+ * ScrollbackShell — the LIVE REGION of native-scroll mode
+ * (tui-native-terminal-scroll §4.6, tui-full-height-live-region D3/D4).
  *
- * The full-screen `AppShell` fills the whole terminal; this shell is only as tall as
- * `budget.liveRows` (the root box height IS that number: giving it the frame height
- * would make the "small region" a whole screen again, and Ink would then repaint a
- * screenful per frame). Everything settled has already been printed into the
- * terminal's own scrollback above it.
+ * THE REGION IS THE SCREEN. The root box is `budget.liveRows` tall, and that number is
+ * `rows - 1` - the whole area above the writer's parked row. It used to be only as tall
+ * as the panel band asked for, and every row it did not ask for became the canvas
+ * `gap`: blank rows ABOVE the content, which is what a user reports as "the app starts
+ * halfway down the terminal" and as "a big blank between the result and the running
+ * card". `H = rows - 1` is also the ONLY height that both fills the screen and keeps Ink
+ * off its `clearTerminal` branch (that branch fires at `outputHeight >= rows` and
+ * contains `ESC[3J`, which erases the user's scrollback).
  *
- * Top to bottom: [overlay | panel band][composer][status][details].
+ * Top to bottom: [header][overlay | panel band][composer][status][details].
  *
  * THE PANEL BAND IS THE PART NATIVE MODE WAS MISSING
  * (release-gate-and-native-panels §6.1). A fixed frame can put a rail beside the
@@ -18,28 +21,60 @@
  *   +---------------------------------------------+-----------------+
  *   | team roster      (height = band.teamRows)    | TODO rail       |
  *   +---------------------------------------------+ (height =       |
- *   | unfinished tail  (height = band.previewRows) |  band.railRows) |
+ *   | tail window      (height = band.previewRows) |  band.railRows) |
  *   +---------------------------------------------+-----------------+
  *
  * Every box in it has an explicit `height` and `width` plus `overflow="hidden"`, and
  * that is a correctness requirement rather than tidiness: a box that grows with its
  * content would make the region taller than `budget.liveRows`, and a frame as tall as
- * the terminal makes Ink erase the user's scrollback (I-4).
+ * the terminal makes Ink erase the user's scrollback.
+ *
+ * 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".
+ *  - 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';
 import type { ScrollbackBudget } from './scrollback/budget.js';
 export interface ScrollbackShellProps {
     budget: ScrollbackBudget;
+    /**
+     * REQUIRED: the one-row slot at the top of the region, `budget.headerRows` tall.
+     * Required rather than optional for the reason `budget` and `band` are - a frame
+     * that forgot it would render a header-less screen with nothing to catch it.
+     */
+    header: React.ReactNode;
     /** Shown instead of the band when an overlay is open. */
     overlay: React.ReactNode | null;
     /** Plain preview rows: the fallback when `tail` is absent (and what `/perf` counts). */
     liveTailLines: readonly string[];
-    /** Real components for the unfinished tail (`LiveTail`). */
+    /**
+     * 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`). */
     tail?: React.ReactNode;
     /** The subagent roster, drawn at the top of the band's left column. */
     team?: React.ReactNode;
@@ -51,4 +86,4 @@ export interface ScrollbackShellProps {
     placeholder: React.ReactNode;
     theme: Theme;
 }
-export declare function ScrollbackShell({ budget, overlay, liveTailLines, tail, team, rail, composer, status, details, placeholder, theme, }: ScrollbackShellProps): React.ReactElement;
+export declare function ScrollbackShell({ budget, header, overlay, liveTailLines, opener, tail, team, rail, composer, status, details, placeholder, theme, }: ScrollbackShellProps): React.ReactElement;

package/dist/ui/ScrollbackShell.js

@@ -1,15 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
-export function ScrollbackShell({ budget, overlay, liveTailLines, tail, team, rail, composer, status, details, placeholder, theme, }) {
+export function ScrollbackShell({ budget, header, overlay, liveTailLines, opener, tail, team, rail, composer, status, details, placeholder, theme, }) {
     const width = budget.contentCols;
     if (budget.inactive) {
         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: 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: "flex-end", overflow: "hidden", children: tail ?? 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: [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 }))] }));
+    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

@@ -1,6 +1,6 @@
 /**
- * LiveTail - the band's UNFINISHED tail, rendered with the real entry components
- * (release-gate-and-native-panels §6.5).
+ * 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
@@ -9,6 +9,15 @@
  * 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 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`
  * cases) lives in `Transcript.tsx` exactly once, together with `EntryFrame`'s gutter,
@@ -17,10 +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.
+ * 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
@@ -32,8 +70,12 @@ import type { TermCapabilities } from '../capabilities.js';
 import type { DensityMode } from '../density.js';
 import type { Theme } from '../theme.js';
 export interface LiveTailProps {
-    /** `entries.slice(settledCount).filter(isExcluded === false)`: the same input as `buildLivePreview`. */
-    unsettled: readonly Entry[];
+    /**
+     * 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). */
@@ -47,18 +89,25 @@ 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;
-    /** The entry before it in the FULL list: `EntryView` uses it to decide the separator. */
+    /** The entry before it in the passed list: `EntryView` decides the separator from it. */
     prev: Entry | undefined;
 }
 /**
- * The last `maxEntries` entries, each with its predecessor.
+ * The last `maxEntries` printable entries, each with its predecessor.
  *
- * `prev` must come from the COMPLETE unsettled 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.
+ * `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(unsettled: readonly Entry[], maxEntries: number): readonly TailEntry[];
-export declare function LiveTail({ unsettled, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, }: LiveTailProps): React.ReactElement;
+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, measuredRows, }: LiveTailProps): React.ReactElement;

package/dist/ui/scrollback/LiveTail.js

@@ -1,27 +1,43 @@
 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` entries, each with its predecessor.
+ * The last `maxEntries` printable entries, each with its predecessor.
  *
- * `prev` must come from the COMPLETE unsettled 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.
+ * `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(unsettled, maxEntries) {
+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, unsettled.length - limit);
+    const start = Math.max(0, printable.length - limit);
     const selected = [];
-    for (let index = start; index < unsettled.length; index += 1) {
-        selected.push({ entry: unsettled[index], prev: index > 0 ? unsettled[index - 1] : undefined });
+    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({ unsettled, 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(unsettled, 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))) }));
+    const selected = selectTailEntries(entries, limited);
+    // `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))) }));
 }