@aragon-agent/cli 0.6.31 → 0.6.33

package/dist/ui/scrollback/tail-window.js

@@ -0,0 +1,73 @@
+/**
+ * The TAIL WINDOW of the native-scroll live region
+ * (tui-full-height-live-region D6 / D7, I-F8 / I-F9).
+ *
+ * WHAT CHANGED AND WHY. The region used to show only the entries the reducer had not
+ * finished writing (`entries.slice(settledCount)`), and everything settled was printed
+ * into the terminal's scrollback the moment it settled. Once the region is the WHOLE
+ * screen (`liveRows = rows - 1`), a printed row is pushed off the top by the very next
+ * frame, so "print on settle" would leave the user staring at a screen of blanks with
+ * only the unfinished cards on it. So the region now shows the last `K` PRINTABLE
+ * entries - settled or not - and an entry is printed when it LEAVES that window.
+ *
+ * The window is defined by ENTRY COUNT, never by measured height: a single entry taller
+ * than the region is clipped from the top by `justifyContent="flex-end"` and stays in
+ * the window until `K` further entries arrive (README, known limitation 2). Measuring
+ * heights here would need the offscreen renderer on every frame, which is the cost this
+ * module exists to avoid.
+ *
+ * PURE: no Ink, no I/O, no clock. `promote()` (the writer's only feeder) takes
+ * `printBoundary`'s result and keeps its own `printedIds` authority, so "printed is
+ * forward-only" (RV-7) is unchanged.
+ *
+ * PRINTABILITY != VISIBILITY. `isExcluded` entries (a non-terminal `service` card) never
+ * print and never take a slot in the window; an entry that is in the window may still be
+ * scrolled out of sight by a taller neighbour (README, known limitation 5). The second
+ * gap is disclosed by `/perf`'s `window=<start>/<n>`, not by a second measurement.
+ */
+import { isExcluded, settledCount } from './settled-boundary.js';
+/**
+ * The index of the first entry that is still on screen: count backwards up to
+ * `maxEntries` PRINTABLE entries. Everything before it has left the region and is the
+ * writer's business.
+ *
+ * `maxEntries <= 0` returns `entries.length` - an empty window, which is the old
+ * behaviour ("everything printable may print") and the reason the guard is written as
+ * an early return rather than as a loop bound.
+ */
+export function tailWindowStart(entries, maxEntries) {
+    const limit = Number.isFinite(maxEntries) ? Math.floor(maxEntries) : 0;
+    if (limit <= 0)
+        return entries.length;
+    let seen = 0;
+    for (let i = entries.length - 1; i >= 0; i -= 1) {
+        if (isExcluded(entries[i]))
+            continue;
+        seen += 1;
+        if (seen === limit)
+            return i;
+    }
+    // Fewer printable entries than the window holds: the whole conversation is on screen.
+    return 0;
+}
+/** `entries.slice(start)` with the entries that never print dropped. */
+export function selectTailWindow(entries, maxEntries) {
+    const start = tailWindowStart(entries, maxEntries);
+    return { start, entries: entries.slice(start).filter((entry) => !isExcluded(entry)) };
+}
+/**
+ * The print boundary: never print what the region is still showing.
+ *
+ * THIS IS THE ONLY PLACE THAT COMBINES "settled" WITH "in the window" (RV-P2-13), which
+ * is why the composition lives here instead of at the pump: `promote()` must keep
+ * receiving one number, and the two authorities it is derived from - `settledCount`
+ * (what may print at all) and `tailWindowStart` (what is still visible) - then cannot
+ * drift apart in a future edit.
+ *
+ * `settleAllEntries` is the OTHER authority, not a duplicate: it answers "what must be
+ * printed when the conversation is being torn down", while this answers "how far may
+ * this frame print".
+ */
+export function printBoundary(entries, runActive, maxEntries) {
+    return Math.min(settledCount(entries, runActive), tailWindowStart(entries, maxEntries));
+}

package/dist/ui/scrollback/use-scrollback-view.d.ts

@@ -1,23 +1,33 @@
 /**
  * `useScrollbackView` — the promotion pipeline of native-scroll mode
- * (tui-native-terminal-scroll §4.4 / §6.2).
+ * (tui-native-terminal-scroll §4.4 / §6.2, tui-full-height-live-region D3/D4/D7/D8).
  *
  * `App` calls it ALWAYS (hooks cannot be conditional); `enabled: false` makes every
  * effect a no-op and keeps `scrollMode: 'app'` byte-identical to the pre-feature
- * build (I-S9).
+ * build (I-S9 / I-F10).
  *
  * What it does when enabled:
- *  1. Prints the session header (and the opener for an empty session) once.
- *  2. On every entries change, promotes each newly SETTLED entry: renders it once
- *     through the offscreen renderer and enqueues the rows for the writer.
- *  3. Computes the live-region budget and the streaming preview rows for the shell.
+ *  1. On every entries change, promotes each entry that has LEFT THE TAIL WINDOW:
+ *     renders it once through the offscreen renderer and enqueues the rows for the
+ *     writer. Entries still on screen are never printed - at `H = rows - 1` a printed
+ *     row is pushed back off the top by the next frame, and a second copy in the
+ *     scrollback would be a duplicate the user meets by scrolling up (I-F8).
+ *  2. Computes the live-region budget, the window and the tail rows for the shell.
+ *  3. Flushes the window before either reset path (`/clear`, `--resume`) and on exit,
+ *     so "on screen but not printed yet" can never become "lost" (D8 / I-F12).
+ *
+ * THE HEADER AND THE OPENER ARE NOT PRINTED HERE ANY MORE (D3/D4). They are slots of
+ * `ScrollbackShell` now, rendered inside the region: `H = rows - 1` means any printed
+ * row is immediately scrolled off the screen, so printing the banner would be the same
+ * as not drawing it. Their `renderNode` path, the `startedRef` latch that kept their
+ * element identities stable, and the `printBanner()` call in `settleAll()` are gone.
  *
  * THE PROMOTION RUNS IN A MICROTASK, NOT IN THE EFFECT. The offscreen renderer is a
  * second Ink instance, and both instances share one React reconciler. A `rerender`
  * issued from inside the main tree's commit (a layout effect) is deferred until that
- * commit finishes, so its frame would not exist when the effect reads it. A
- * microtask runs after the commit has unwound, where the offscreen render is
- * synchronous again. Everything the pass needs is read from refs for that reason.
+ * commit finishes, so its frame would not exist when the effect reads it. A microtask
+ * runs after the commit has unwound, where the offscreen render is synchronous again.
+ * Everything the pass needs is read from refs for that reason.
  *
  * `printedIds` is the ONLY authority on "already printed" (RV-7). The cursor is just
  * a hint for where to resume scanning: entries leave the list by retain-ring
@@ -25,7 +35,6 @@
  * cards), so an id-keyed cursor can dangle, and then the only correct answer is to
  * rescan and let `printedIds` skip.
  */
-import React from 'react';
 import type { Entry } from '../../agent/reducer.js';
 import type { TermCapabilities } from '../capabilities.js';
 import type { DensityMode } from '../density.js';
@@ -68,23 +77,33 @@ export interface UseScrollbackViewArgs {
     /** Terminal size. */
     rows: number;
     cols: number;
-    /** Printed first, once. */
-    headerNode: React.ReactNode;
-    /** Printed after the header for an empty session. */
-    openerNode: React.ReactNode | null;
     overlayOpen: boolean;
     draftRows: number;
     popupRows: number;
     statusExpanded: boolean;
     /** Degrade the region to the placeholder (the writer's tall-frame guard tripped). */
     forceInactive?: boolean;
+    /** `state.todos.items.length` - 0 means there is no plan, so the rail has no work to show. */
+    itemCount: number;
+    /** `cfg.todo.panel`: the user can switch the rail off entirely. */
+    panelEnabled: boolean;
+    /** `buildTeamPanelLayout().rowCount`; 0 when nothing is dispatched. */
+    teamRowsNatural: number;
 }
 export interface ScrollbackView {
     budget: ScrollbackBudget | null;
     liveTailLines: string[];
+    /**
+     * The entries the region is showing, in order (excluded kinds already dropped).
+     * `windowStart` is their index in the full list - together they are what `/perf`
+     * reports as `window=<start>/<n>`, the number that makes the "visible vs printable"
+     * gap observable instead of a guess (known limitation 5).
+     */
+    tailEntries: readonly Entry[];
+    windowStart: number;
     /** Print a fresh EXPANDED copy of an entry; false when it cannot be found / rendered. */
     reprintExpanded(entryId: string): boolean;
-    /** Promote everything printable now (shutdown). */
+    /** Promote everything still unprinted (shutdown) - `flushUnprinted(latest entries)`. */
     settleAll(): void;
     /** Called by `App`'s dispatch wrapper BEFORE a reset action reaches the reducer. */
     notifyReset(kind: ScrollbackResetKind): void;

package/dist/ui/scrollback/use-scrollback-view.js

@@ -1,23 +1,33 @@
 /**
  * `useScrollbackView` — the promotion pipeline of native-scroll mode
- * (tui-native-terminal-scroll §4.4 / §6.2).
+ * (tui-native-terminal-scroll §4.4 / §6.2, tui-full-height-live-region D3/D4/D7/D8).
  *
  * `App` calls it ALWAYS (hooks cannot be conditional); `enabled: false` makes every
  * effect a no-op and keeps `scrollMode: 'app'` byte-identical to the pre-feature
- * build (I-S9).
+ * build (I-S9 / I-F10).
  *
  * What it does when enabled:
- *  1. Prints the session header (and the opener for an empty session) once.
- *  2. On every entries change, promotes each newly SETTLED entry: renders it once
- *     through the offscreen renderer and enqueues the rows for the writer.
- *  3. Computes the live-region budget and the streaming preview rows for the shell.
+ *  1. On every entries change, promotes each entry that has LEFT THE TAIL WINDOW:
+ *     renders it once through the offscreen renderer and enqueues the rows for the
+ *     writer. Entries still on screen are never printed - at `H = rows - 1` a printed
+ *     row is pushed back off the top by the next frame, and a second copy in the
+ *     scrollback would be a duplicate the user meets by scrolling up (I-F8).
+ *  2. Computes the live-region budget, the window and the tail rows for the shell.
+ *  3. Flushes the window before either reset path (`/clear`, `--resume`) and on exit,
+ *     so "on screen but not printed yet" can never become "lost" (D8 / I-F12).
+ *
+ * THE HEADER AND THE OPENER ARE NOT PRINTED HERE ANY MORE (D3/D4). They are slots of
+ * `ScrollbackShell` now, rendered inside the region: `H = rows - 1` means any printed
+ * row is immediately scrolled off the screen, so printing the banner would be the same
+ * as not drawing it. Their `renderNode` path, the `startedRef` latch that kept their
+ * element identities stable, and the `printBanner()` call in `settleAll()` are gone.
  *
  * THE PROMOTION RUNS IN A MICROTASK, NOT IN THE EFFECT. The offscreen renderer is a
  * second Ink instance, and both instances share one React reconciler. A `rerender`
  * issued from inside the main tree's commit (a layout effect) is deferred until that
- * commit finishes, so its frame would not exist when the effect reads it. A
- * microtask runs after the commit has unwound, where the offscreen render is
- * synchronous again. Everything the pass needs is read from refs for that reason.
+ * commit finishes, so its frame would not exist when the effect reads it. A microtask
+ * runs after the commit has unwound, where the offscreen render is synchronous again.
+ * Everything the pass needs is read from refs for that reason.
  *
  * `printedIds` is the ONLY authority on "already printed" (RV-7). The cursor is just
  * a hint for where to resume scanning: entries leave the list by retain-ring
@@ -30,7 +40,8 @@ import { buildScrollbackBudget } from './budget.js';
 import { buildLivePreview } from './live-preview.js';
 import { SCROLLBACK_LIMITS } from './limits.js';
 import { createEntryRenderer } from './renderer.js';
-import { isExcluded, settleAllEntries, settledCount } from './settled-boundary.js';
+import { isExcluded, settleAllEntries } from './settled-boundary.js';
+import { printBoundary, selectTailWindow } from './tail-window.js';
 export function createScrollbackBridge(parts) {
     return {
         writer: parts.writer,
@@ -64,20 +75,15 @@ function pruneEntryIds(printed, entries) {
             printed.delete(id);
 }
 export function useScrollbackView(args) {
-    const { enabled, bridge, entries, runActive, theme, caps, density, thinkingVisible, reducedMotion, rows, cols, headerNode, openerNode, overlayOpen, draftRows, popupRows, statusExpanded, forceInactive = false, } = args;
+    const { enabled, bridge, entries, runActive, theme, caps, density, thinkingVisible, reducedMotion, rows, cols, overlayOpen, draftRows, popupRows, statusExpanded, forceInactive = false, itemCount, panelEnabled, teamRowsNatural, } = args;
     const contentCols = Math.max(1, cols - 1);
-    const startedRef = useRef(false);
     // Everything the asynchronous pass reads travels here, refreshed on every render.
     const latest = useRef({
-        entries, runActive, contentCols, headerNode, openerNode,
+        entries, runActive, contentCols,
         options: { theme, caps, density, thinkingVisible, reducedMotion },
     });
     latest.current = {
         entries, runActive, contentCols,
-        // The banner nodes only matter until the banner is printed; afterwards keep the
-        // old references so a changing element identity is not mistaken for new input.
-        headerNode: startedRef.current ? latest.current.headerNode : headerNode,
-        openerNode: startedRef.current ? latest.current.openerNode : openerNode,
         options: { theme, caps, density, thinkingVisible, reducedMotion },
     };
     const rendererRef = useRef(null);
@@ -85,7 +91,12 @@ export function useScrollbackView(args) {
     /** A resume hint only (RV-7): the id of the last entry the previous pass covered. */
     const cursorRef = useRef(null);
     const pendingReset = useRef(null);
-    const heldTailRows = useRef(0);
+    // Band hysteresis (release-gate-and-native-panels §6.7): the writer re-lays out the
+    // canvas on every batch, so a band that shrank for two frames would make everything
+    // above the composer jump.
+    const heldRailRows = useRef(0);
+    const heldTeamRows = useRef(0);
+    const heldGeometry = useRef({ rows, cols });
     const pumpQueued = useRef(false);
     const mountedRef = useRef(true);
     const ensureRenderer = useCallback(() => {
@@ -131,25 +142,45 @@ export function useScrollbackView(args) {
         remember();
         return false;
     }, [ensureRenderer, enqueue]);
-    const printBanner = useCallback(() => {
-        if (startedRef.current)
+    /**
+     * THE ONE PRINT LOOP (RV-P0-2 / RV-P2-12): every not-yet-printed entry of `list`,
+     * oldest first, with no per-pass limit.
+     *
+     * `list` is a PARAMETER on purpose. `applyPendingReset` must pass `reset.captured` -
+     * the snapshot taken BEFORE the reducer reset - because by the time the microtask
+     * runs, `latest.current.entries` is already the NEW list and flushing that would
+     * print zero rows: the entries that only ever existed on screen would vanish with
+     * the reset. That is real data loss, not a cosmetic gap.
+     *
+     * `settleAllEntries` is the exit path's authority (everything that can ever print,
+     * including an entry still streaming at this instant - printed is forever, and the
+     * conversation is being destroyed right now, so a snapshot beats a hole). The drain
+     * is FIFO, so the ORDER of the calls below is the order on screen.
+     */
+    const flushUnprinted = useCallback((list) => {
+        if (!bridge)
             return;
-        startedRef.current = true;
         const renderer = ensureRenderer();
-        const { headerNode: header, openerNode: opener, contentCols: width } = latest.current;
-        enqueue(renderer.renderNode(header, width), 'startup:header', 'header');
-        if (opener)
-            enqueue(renderer.renderNode(opener, width), 'startup:opener', 'opener');
-    }, [ensureRenderer, enqueue]);
+        for (const entry of settleAllEntries(list)) {
+            if (printedIds.current.has(entry.id))
+                continue;
+            enqueue(renderer.renderEntry(entry, printableBefore(list, list.indexOf(entry)), latest.current.contentCols), entry.id, entry.kind);
+            printedIds.current.add(entry.id);
+        }
+    }, [bridge, ensureRenderer, enqueue]);
     const applyPendingReset = useCallback(() => {
         const reset = pendingReset.current;
         if (!reset || latest.current.entries === reset.captured)
             return;
         pendingReset.current = null;
+        // ORDER IS THE CONTRACT (AC-F16): flush the OLD list, then the separator, then
+        // forget what was printed. Clearing `printedIds` first would make the flush print
+        // the whole conversation a second time.
+        flushUnprinted(reset.captured);
         printedIds.current = new Set();
         cursorRef.current = null;
         enqueue([reset.kind === 'clear' ? CLEARED_ROW : RESTORED_ROW], `reset:${Date.now()}`, 'notice');
-    }, [enqueue]);
+    }, [enqueue, flushUnprinted]);
     const pumpRef = useRef(() => undefined);
     const schedulePump = useCallback(() => {
         if (pumpQueued.current)
@@ -162,11 +193,12 @@ export function useScrollbackView(args) {
         pumpQueued.current = false;
         if (!mountedRef.current || !bridge)
             return;
-        printBanner();
         applyPendingReset();
         const { entries: list, runActive: active } = latest.current;
         const limit = Math.max(1, SCROLLBACK_LIMITS.feedCapacity - bridge.drain.pendingEntries() - 1);
-        const more = promote(list, settledCount(list, active), limit);
+        // `printBoundary` = min(settled, window start): the region keeps what it shows.
+        const end = printBoundary(list, active, SCROLLBACK_LIMITS.liveTailMaxEntries);
+        const more = promote(list, end, limit);
         pruneEntryIds(printedIds.current, list);
         if (more) {
             // Continue once the writer has consumed what is queued (a restored transcript
@@ -183,19 +215,8 @@ export function useScrollbackView(args) {
             schedulePump();
     }, [enabled, bridge, entries, runActive, schedulePump]);
     const settleAll = useCallback(() => {
-        if (!bridge)
-            return;
-        const list = latest.current.entries;
-        const renderer = ensureRenderer();
-        printBanner();
-        // Shutdown must not leave anything behind, so no per-pass limit.
-        for (const entry of settleAllEntries(list)) {
-            if (printedIds.current.has(entry.id))
-                continue;
-            enqueue(renderer.renderEntry(entry, printableBefore(list, list.indexOf(entry)), latest.current.contentCols), entry.id, entry.kind);
-            printedIds.current.add(entry.id);
-        }
-    }, [bridge, ensureRenderer, printBanner, enqueue]);
+        flushUnprinted(latest.current.entries);
+    }, [flushUnprinted]);
     // Shutdown hook for the exit paths. `restore()` runs it AFTER the tree is gone
     // (normal exit) or while it is alive (signal), so it renders synchronously and then
     // releases the offscreen instance. The unmount cleanup deliberately renders nothing:
@@ -217,29 +238,55 @@ export function useScrollbackView(args) {
         };
         return () => { mountedRef.current = false; };
     }, [enabled, bridge]);
-    // --- Live region budget and streaming preview. ---------------------------
-    const boundary = useMemo(() => settledCount(entries, runActive), [entries, runActive]);
-    const unsettled = useMemo(() => entries.slice(boundary).filter((entry) => !isExcluded(entry)), [entries, boundary]);
-    const wanted = enabled
-        ? buildLivePreview({
-            unsettled, cols: contentCols, rows: SCROLLBACK_LIMITS.maxLiveTailRows, thinkingVisible,
-        }).length
-        : 0;
-    // D11 · the preview height only grows while anything is unsettled, then resets.
-    heldTailRows.current = unsettled.length === 0 ? 0 : Math.max(heldTailRows.current, wanted);
+    // --- Live region budget and the tail window. ------------------------------
+    // The window is the last K printable entries, settled or not (D6/D7). `slice` +
+    // `tailWindowStart` is `tail-window.ts`'s definition, and `printBoundary` uses the
+    // same start - so "what is on screen" and "what is withheld from the writer" cannot
+    // disagree about where the boundary is.
+    const window = useMemo(() => selectTailWindow(entries, SCROLLBACK_LIMITS.liveTailMaxEntries), [entries]);
+    const tailEntries = window.entries;
+    const windowStart = window.start;
+    // The band's hysteresis has exactly THREE reset points and no others: the plan
+    // emptied, the dispatch finished, or the geometry changed (a new size is a new
+    // measurement - the same treatment `App` gives `guardTripped`).
+    if (heldGeometry.current.rows !== rows || heldGeometry.current.cols !== cols) {
+        heldGeometry.current = { rows, cols };
+        heldRailRows.current = 0;
+        heldTeamRows.current = 0;
+    }
+    if (itemCount === 0)
+        heldRailRows.current = 0;
+    if (teamRowsNatural === 0)
+        heldTeamRows.current = 0;
     const budget = useMemo(() => enabled
         ? buildScrollbackBudget({
             rows, cols, draftRows, popupRows, statusExpanded, overlayOpen,
-            liveTailWanted: heldTailRows.current, forceInactive,
+            forceInactive,
+            band: {
+                itemCount, panelEnabled, teamRowsNatural,
+                heldRailRows: heldRailRows.current, heldTeamRows: heldTeamRows.current,
+            },
         })
         : null, 
-    // `heldTailRows.current` is read at memo time; `wanted` is what moves it.
+    // The two band refs are read at memo time; `itemCount` and `teamRowsNatural` are
+    // what move them. The budget no longer depends on CONTENT at all (the band fills the
+    // pool, D5), so nothing about the transcript belongs in this dependency list.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [enabled, rows, cols, draftRows, popupRows, statusExpanded, overlayOpen, wanted,
-        unsettled.length, forceInactive]);
+    [enabled, rows, cols, draftRows, popupRows, statusExpanded, overlayOpen,
+        forceInactive, itemCount, panelEnabled, teamRowsNatural]);
+    if (budget) {
+        // Monotone memory, fed back into the memo above on the next frame.
+        heldRailRows.current = budget.band.heldRailRows;
+        heldTeamRows.current = budget.band.heldTeamRows;
+    }
+    // Print keeps `contentCols`; only the live tail gives up the rail's columns (I-5).
+    const previewCols = budget ? budget.previewCols : contentCols;
     const liveTailLines = useMemo(() => enabled && budget && budget.liveTailRows > 0
-        ? buildLivePreview({ unsettled, cols: contentCols, rows: budget.liveTailRows, thinkingVisible })
-        : [], [enabled, budget, unsettled, contentCols, thinkingVisible]);
+        ? buildLivePreview({
+            unsettled: tailEntries, cols: previewCols, rows: budget.liveTailRows,
+            thinkingVisible,
+        })
+        : [], [enabled, budget, tailEntries, previewCols, thinkingVisible]);
     const reprintExpanded = useCallback((entryId) => {
         if (!enabled || !bridge)
             return false;
@@ -257,7 +304,11 @@ export function useScrollbackView(args) {
     const notifyReset = useCallback((kind) => {
         if (!enabled)
             return;
+        // The PRE-reset snapshot: see `flushUnprinted`'s note on why this cannot be read
+        // from `latest` when the microtask finally runs.
         pendingReset.current = { kind, captured: latest.current.entries };
     }, [enabled]);
-    return { budget, liveTailLines, reprintExpanded, settleAll, notifyReset };
+    return {
+        budget, liveTailLines, tailEntries, windowStart, reprintExpanded, settleAll, notifyReset,
+    };
 }

package/dist/ui/scrollback/writer-shapes.d.ts

@@ -21,6 +21,60 @@ export declare function seedBytes(input: {
     /** After a foreign write the cursor may sit mid-line; start on a new one (RV-11). */
     reseed: boolean;
 }): string;
+/**
+ * CUD(n): move down n rows WITHOUT writing a single cell.
+ *
+ * This is how the canvas spends its `gap` (D3). A blank row that is never written
+ * cannot be pushed into the scrollback by a later overflow, which is the whole
+ * reason the gap is not a run of `\r\n` (I-B3). The sequence is already whitelisted
+ * (`diffBytes` uses it to step between changed rows); this is the same CUD used to
+ * skip empty space instead.
+ */
+export declare function skipRows(rows: number): string;
+/**
+ * First canvas batch (or the first one after a reset): the screen below the cursor
+ * is assumed empty, so there is nothing to erase — only `[gap][content][region]` to
+ * write, ending with the cursor parked on the last row.
+ */
+export declare function canvasSeedBytes(input: {
+    /**
+     * Rows to descend from the cursor to the canvas top, when the canvas is shorter
+     * than the space measured below the cursor.
+     *
+     * Non-zero only on a terminal taller than the start-of-canvas cap: the canvas then
+     * begins BELOW the cursor, and a seed that started writing at the cursor would park
+     * the region low and leave the top of the canvas empty for the whole session.
+     */
+    downToTop: number;
+    /** Blank rows to skip before the first content row. */
+    gap: number;
+    /** Content rows, already clipped, oldest first. */
+    held: readonly string[];
+    /** The live region. */
+    lines: readonly string[];
+    sync: boolean;
+    /** After a foreign write the cursor may sit mid-line; start on a new one. */
+    reseed: boolean;
+}): string;
+/**
+ * Redraw the whole canvas: erase the previous one, then write `[gap][content][region]`.
+ *
+ * ORDER IS SEMANTICS: `ED0`, then the gap, then the content, then the region. Moving
+ * the gap after the content puts the blank space back between the reply and the
+ * composer, which is the exact defect this feature fixes (M1 in the spec).
+ *
+ * `held` is the FULL content sequence, not the part that will still be on screen: the
+ * rows that do not fit are supposed to leave through the bottom, and the terminal can
+ * only scroll away what it was given.
+ */
+export declare function canvasBytes(input: {
+    /** Previous canvas height: the erase distance. */
+    eraseUp: number;
+    gap: number;
+    held: readonly string[];
+    lines: readonly string[];
+    sync: boolean;
+}): string;
 /** Erase exactly the previous live region, print static rows, redraw the region. */
 export declare function fullBytes(input: {
     lines: readonly string[];
@@ -29,6 +83,20 @@ export declare function fullBytes(input: {
     eraseUp: number;
     sync: boolean;
 }): string;
+/**
+ * Fill the screen down to the LAST row before the first batch (D4 rung 2 / §4.3).
+ *
+ * This is the fallback for a terminal that never answers `ESC[6n`: from any row, a
+ * run of `rows - 1` line feeds is guaranteed to leave the cursor on the bottom row
+ * (extra feeds only scroll, which is why the count is the caller's business). It is
+ * written ONCE, before anything else, so the rows it scrolls away are the host's old
+ * output — which is still in the scrollback — and never this session's content.
+ *
+ * The argument is the NUMBER OF LINE FEEDS, not the terminal height: `cli.tsx` passes
+ * `rows - 1`. Naming it after the height instead made the caller subtract twice and
+ * left the cursor one row short of the bottom.
+ */
+export declare function fillBytes(count: number): string;
 /** Same height, no static rows: rewrite only the rows that changed. `''` if none did. */
 export declare function diffBytes(input: {
     lines: readonly string[];
@@ -57,5 +125,3 @@ export declare function clipLine(line: string, maxCols: number): {
     text: string;
     clipped: boolean;
 };
-/** Rows the previous region occupies after the terminal re-flowed it to `cols` (§4.10). */
-export declare function estimateReflowRows(lines: readonly string[], cols: number): number;

package/dist/ui/scrollback/writer-shapes.js

@@ -32,10 +32,63 @@ export function seedBytes(input) {
     const lead = input.reseed ? '\r\n' : '';
     return wrapSync(lead + '\r' + SGR0 + rows(input.statics) + rows(input.lines), input.sync);
 }
+/**
+ * CUD(n): move down n rows WITHOUT writing a single cell.
+ *
+ * This is how the canvas spends its `gap` (D3). A blank row that is never written
+ * cannot be pushed into the scrollback by a later overflow, which is the whole
+ * reason the gap is not a run of `\r\n` (I-B3). The sequence is already whitelisted
+ * (`diffBytes` uses it to step between changed rows); this is the same CUD used to
+ * skip empty space instead.
+ */
+export function skipRows(rows) {
+    return down(Math.max(0, Math.floor(Number.isFinite(rows) ? rows : 0)));
+}
+/**
+ * First canvas batch (or the first one after a reset): the screen below the cursor
+ * is assumed empty, so there is nothing to erase — only `[gap][content][region]` to
+ * write, ending with the cursor parked on the last row.
+ */
+export function canvasSeedBytes(input) {
+    const lead = input.reseed ? '\r\n' : '';
+    const skip = skipRows(input.downToTop) + skipRows(input.gap);
+    return wrapSync(lead + '\r' + SGR0 + skip + rows(input.held) + rows(input.lines), input.sync);
+}
+/**
+ * Redraw the whole canvas: erase the previous one, then write `[gap][content][region]`.
+ *
+ * ORDER IS SEMANTICS: `ED0`, then the gap, then the content, then the region. Moving
+ * the gap after the content puts the blank space back between the reply and the
+ * composer, which is the exact defect this feature fixes (M1 in the spec).
+ *
+ * `held` is the FULL content sequence, not the part that will still be on screen: the
+ * rows that do not fit are supposed to leave through the bottom, and the terminal can
+ * only scroll away what it was given.
+ */
+export function canvasBytes(input) {
+    return wrapSync(up(input.eraseUp) + '\r' + SGR0 + ED0 + skipRows(input.gap) +
+        rows(input.held) + rows(input.lines), input.sync);
+}
 /** Erase exactly the previous live region, print static rows, redraw the region. */
 export function fullBytes(input) {
     return wrapSync(up(input.eraseUp) + '\r' + SGR0 + ED0 + rows(input.statics) + rows(input.lines), input.sync);
 }
+/**
+ * Fill the screen down to the LAST row before the first batch (D4 rung 2 / §4.3).
+ *
+ * This is the fallback for a terminal that never answers `ESC[6n`: from any row, a
+ * run of `rows - 1` line feeds is guaranteed to leave the cursor on the bottom row
+ * (extra feeds only scroll, which is why the count is the caller's business). It is
+ * written ONCE, before anything else, so the rows it scrolls away are the host's old
+ * output — which is still in the scrollback — and never this session's content.
+ *
+ * The argument is the NUMBER OF LINE FEEDS, not the terminal height: `cli.tsx` passes
+ * `rows - 1`. Naming it after the height instead made the caller subtract twice and
+ * left the cursor one row short of the bottom.
+ */
+export function fillBytes(count) {
+    return '\r\n'.repeat(Math.max(0, Math.floor(count)));
+}
 /** Same height, no static rows: rewrite only the rows that changed. `''` if none did. */
 export function diffBytes(input) {
     const { lines, prev } = input;
@@ -104,11 +157,3 @@ export function clipLine(line, maxCols) {
     }
     return { text: out, clipped: false };
 }
-/** Rows the previous region occupies after the terminal re-flowed it to `cols` (§4.10). */
-export function estimateReflowRows(lines, cols) {
-    const width = Math.max(1, cols);
-    let total = 0;
-    for (const line of lines)
-        total += Math.max(1, Math.ceil(stringWidth(stripAnsi(line)) / width));
-    return total;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.6.31",
+  "version": "0.6.33",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -56,7 +56,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.43",
+    "@aragon-agent/core": "^0.2.45",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",
@@ -76,6 +76,6 @@
     "@types/react": "^18.3.0",
     "ink-testing-library": "^4.0.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "vitest": "4.1.9"
   }
 }