@aragon-agent/cli 0.6.32 → 0.6.33

package/CHANGELOG.md

@@ -121,6 +121,25 @@ were written.
 
 ### Fixed
 
+- **The native-scroll screen is filled edge to edge, with no blank band anywhere.**
+  Three complaints, one cause: the live region was only as tall as the panel band
+  asked for, and every row it did not ask for became the canvas `gap` - blank rows
+  drawn *above* the content. So the app appeared to start halfway down the terminal,
+  a long blank band sat between a finished result and the card that was still running,
+  and the `TODO` rail stopped six rows or so above the input box. The region is now
+  the whole screen (`rows - 1`, the same height the full-screen layout uses): the
+  header is its first row, the input box and status line are its last two, the band
+  takes every row in between (`bandRows = pool`), so the rail spans the full height
+  above the composer and the tail column ends against it. The `gap` is 0 by
+  construction, not by tuning, and the scrollback writer is unchanged - `[gap][held]
+  [region]` collapses to `[region]` at that height. Two consequences worth knowing:
+  the region now shows the last ten entries of the conversation instead of only the
+  unfinished ones, and an entry is printed into your scrollback when it leaves that
+  window (so nothing is ever in both places at once); `/clear`, `--resume` and exit
+  flush the window first, which is why nothing visible is lost. The empty-session card
+  is drawn against the header rather than the input box, and `/perf` grew the three
+  numbers that make this self-checking: `top <n>` on the `mode native` line, plus
+  `pool=` and `window=<start>/<n>` on the `band:` line.
 - **The TODO rail and the subagent roster are back in the default (native) scroll
   mode.** Printing the conversation into the terminal's own scrollback took the two
   panels with it: the rail lived in the full-screen layout's middle band and the

package/README.md

@@ -782,11 +782,12 @@ near-identical added ones.
 ### Native scroll mode (default)
 
 The conversation lives in **your terminal's own scrollback**, exactly like the output
-of any other command. Finished messages are printed once, above a small *live
-region* at the bottom of the screen (the streaming preview, the input box and the
-status line). Scrolling, selecting and searching are your terminal's job, on every
-platform: PowerShell, `cmd`, Windows Terminal, VS Code, `bash`, `zsh`, `tmux`,
-iTerm2, Terminal.app, gnome-terminal and friends.
+of any other command. The *live region* fills the screen - header on the first row,
+input box and status line on the last two, the tail of the conversation in between -
+and an entry is printed into the scrollback once it leaves that region. Scrolling,
+selecting and searching are your terminal's job, on every platform: PowerShell,
+`cmd`, Windows Terminal, VS Code, `bash`, `zsh`, `tmux`, iTerm2, Terminal.app,
+gnome-terminal and friends.
 
 - **Wheel, scrollbar, `Shift+PgUp` / `Shift+PgDn`, touchpad inertia** — the terminal's.
   `aragon` does not enter the alternate screen and does not turn on mouse reporting,
@@ -801,11 +802,15 @@ iTerm2, Terminal.app, gnome-terminal and friends.
   time, usage, and the `aragon --resume <id>` line) instead of replaying the
   transcript, because the transcript is already in your scrollback — `exitTranscript`
   is ignored in this mode.
-- **While a reply streams**, the last few lines show in the live region; when the
-  message is final it is printed in its formatted shape and the preview disappears
-  (a small, intentional "settle" jump). Scrolling up to read earlier output while a
-  reply streams is safe; how the viewport behaves when new output arrives is your
-  terminal's own "scroll on output" setting.
+- **While a reply streams**, it is drawn in the live region with the real cards (a
+  running `tool` or `team` card looks exactly like the full-screen one). The region
+  holds the last ten entries of the conversation, settled or not, and an entry is
+  printed into your scrollback when it LEAVES that window - so what is on the screen
+  and what you scroll up to are two disjoint halves of one conversation, never the
+  same paragraph twice. Scrolling up to read earlier output while a reply streams is
+  safe; how the viewport behaves when new output arrives is your terminal's own
+  "scroll on output" setting. A message you have just sent is therefore on the screen
+  only: it reaches the scrollback when ten newer entries push it out, or when you exit.
 - **Printed rows are final once they leave the screen.** A row that has scrolled into
   your scrollback is never rewritten, and it is wrapped to the width at which it was
   printed, so a later window resize does not re-wrap it. The rows still *on* the screen
@@ -814,15 +819,16 @@ iTerm2, Terminal.app, gnome-terminal and friends.
   (thinking) and `/theme` affect only *new* messages, and `Ctrl+O` prints an
   expanded copy of a tool card instead of expanding the old one. `/clear` prints a
   `---- conversation cleared ----` separator; it cannot erase scrollback.
-- **The reply always touches the input box.** The input box and status line sit on the
-  **last two rows of the terminal** at all times, and the newest printed line sits
-  directly above them: the blank space of a conversation that has not filled the screen
-  is *above the conversation*, never between the reply and the composer. Three things
-  are still true. A terminal that cannot be measured (`/perf` shows `anchor bottom via
-  fill`, or `none` when the probe is unavailable) is filled to the bottom once at
-  startup, which scrolls your screen up by a page — that one-off flip is the price of
-  pinning without a cursor query. Making the window narrower or shorter drops the
-  geometry until the next measurement (a couple of hundred milliseconds) instead of
+- **The interface fills the terminal.** The header is the first row of the screen, the
+  input box and status line are the last two, and everything between them belongs to
+  the conversation: the newest line always touches the input box, so the blank space of
+  a conversation that has not filled the screen sits at the *top of the region* - never
+  between the reply and the composer, and never as a band above the app itself. Three
+  things are still true. A terminal that cannot be measured (`/perf` shows `anchor
+  bottom via fill`, or `none` when the probe is unavailable) is filled to the bottom
+  once at startup, which scrolls your screen up by a page — that one-off flip is the
+  price of pinning without a cursor query. Making the window narrower or shorter drops
+  the geometry until the next measurement (a couple of hundred milliseconds) instead of
   guessing: new output parks under the last printed line until the composer pins itself
   again, and old content is neither re-wrapped nor redrawn. `Ctrl+G`, `/help` and the
   model picker open as overlays inside the live region, and they take the whole top of
@@ -831,21 +837,28 @@ iTerm2, Terminal.app, gnome-terminal and friends.
   puts a `TODO d/t` column on the right of the band - markers, index, the running
   item's `activeForm`, an overflow marker and the gauge - and a running dispatch puts
   the `team` roster above the reply, one row per subagent with its activity and
-  elapsed time. The unfinished tail underneath them is drawn with the same cards the
-  full-screen mode uses, so a running tool or team card looks identical in both modes.
-  The band is bounded (the preview shares the terminal height with the composer, the
-  status line and the rail) and the printed conversation above it always keeps the
-  full width. Below 76 columns there is no room for the rail and the status line's
-  `todo` chip takes over; `/perf`'s `band:` line says which of the six reasons applied.
+  elapsed time. The tail underneath them is drawn with the same cards the full-screen
+  mode uses, so a running tool or team card looks identical in both modes. The band
+  takes **every row between the header and the composer**: the rail spans the full
+  height above the input box instead of stopping partway down, the tail column ends
+  against the composer, and the printed conversation above always keeps the full width.
+  Below 76 columns there is no room for the rail and the status line's `todo` chip
+  takes over; `/perf`'s `band:` line says which of the six reasons applied.
 - **If something looks wrong**, `/perf` has a `scrollback` line (`guardHits`,
   `clippedRows`, `fallbacks`, and the geometry: `region`/`canvas`/`content`/`gap` rows,
   `anchor bottom via probe|fill|none`, `scrolled` rows, `anchor resets`, `reprobes`).
-  A `band:` line reports the panel band - `rail=<rows>x<cols> team=<rows>`
-  `preview=<rows> cols=<contentCols>/<previewCols> reason=<visible|empty|disabled|`
-  `narrow|short|overlay> held=<rail>/<team>` - which is the only place that says why a
-  panel is not on screen.
-  `gap` is the blank space above the content, `canvas` is the canvas height including
-  the live region, and `scrolled` counts the rows that have moved into your scrollback.
+  The `mode native` line carries `top <n>`, the canvas's first screen row. A `band:`
+  line reports the panel band - `rail=<rows>x<cols> team=<rows> tail=<rows>
+  pool=<rows> cols=<contentCols>/<previewCols> reason=<visible|empty|disabled|`
+  `narrow|short|overlay> held=<rail>/<team> window=<start>/<n>` - which is the only
+  place that says why a panel is not on screen.
+  `gap` is the blank space above the content and is **always 0** now (the region is the
+  whole screen), `canvas` is the canvas height including the live region, `pool` is the
+  band's height (the rows between the header and the composer) and `window=<start>/<n>`
+  is the tail window: the first entry on screen and how many entries it holds. That
+  number is the honest answer to "why is a message I can see not in my scrollback yet"
+  - the region shows ten entries, and an entry is printed when it leaves them.
+  `scrolled` counts the rows that have moved into your scrollback.
   The one-step escape hatch is `aragon config set scrollMode app`, or `--scroll-mode
   app` for a single run.
 

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,31 @@ 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;
 }
 /**
  * Why the right-edge scrollbar is or is not usable, in one record
@@ -136,8 +153,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}`;
 }
 /**
  * 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

@@ -2293,9 +2293,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 +2323,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
@@ -2352,6 +2360,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 +2431,15 @@ 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).
+                windowStart: scrollbackView.windowStart,
+                windowEntries: scrollbackView.tailEntries.length,
+            }
             : null,
         // A getter: the bridge's `frameReady` and geometry change outside React renders.
         get scrollbar() {
@@ -2552,11 +2576,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 }))
                 : 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,13 +21,24 @@
  *   +---------------------------------------------+-----------------+
  *   | 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.
+ *
+ * TWO SLOTS ARE NOT BOTTOM-ALIGNED, AND ONLY TWO (D3 / D4 / I-F7):
+ *  - `header` is the fixed 1-row slot at the very top. It is NOT printed into the
+ *    scrollback any more: at `H = rows - 1` any printed row is pushed off the screen by
+ *    the next frame, so "print the header" would mean "the header is never visible".
+ *  - `opener` is the empty-session card, and it is the one thing inside the band that is
+ *    TOP-aligned: a 12-row card bottom-aligned in a 24-row column would leave 12 blank
+ *    rows in the upper half of the screen - the original defect, still inside the
+ *    region, where the `gap` assertion could not see it. `opener` and `tail` are
+ *    mutually exclusive by construction (`App` keys them off `entries.length === 0`),
+ *    and they share one box because two boxes would be one more height to get wrong.
  *
  * `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
@@ -35,11 +49,22 @@ 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, and the only
+     * thing in this shell that is not bottom-aligned or a fixed slot (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 +76,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,18 @@
 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: whichever is mounted decides the
+    // alignment of the box, so the two can never both be drawn and fight for the height.
+    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: opener ? 'flex-start' : 'flex-end', overflow: "hidden", children: leftColumn ?? tailLines.map((line, index) => (_jsx(Text, { wrap: "truncate", color: theme.muted, children: line }, index))) }))] }), band.railRows > 0 && (_jsx(Box, { height: band.railRows, width: band.railCols, flexShrink: 0, overflow: "hidden", children: rail }))] })) : null;
+    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.
+ *
  * 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,
@@ -20,7 +29,9 @@
  * `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.
+ * `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
@@ -32,8 +43,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). */
@@ -50,15 +65,15 @@ export interface LiveTailProps {
 }
 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, }: LiveTailProps): React.ReactElement;

package/dist/ui/scrollback/LiveTail.js

@@ -2,26 +2,31 @@ 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` 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, }) {
     const limited = Math.min(maxEntries, SCROLLBACK_LIMITS.liveTailMaxEntries);
-    const selected = selectTailEntries(unsettled, limited);
+    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))) }));
 }