@aragon-agent/cli 0.6.32 → 0.6.34

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

@@ -1,36 +1,65 @@
 /**
  * `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,
+ * tui-final-reply-truncated-unscrollable A-prime).
  *
  * `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. Gives way at the TOP (tui-final-reply-truncated-unscrollable). The window is still
+ *     counted in ENTRIES, so a settled answer taller than the box used to sit inside the
+ *     window forever, clipped by `justifyContent="flex-end"`, in a mode whose wheel only
+ *     scrolls the terminal's scrollback: the clipped rows existed nowhere the user could
+ *     reach. The rows the box hides are now measured (`overflow-print.ts`) and printed, so
+ *     `scrollback + screen` covers every row exactly once. Screen unchanged, reachability
+ *     fixed.
+ *  3. Computes the live-region budget, the window and the tail rows for the shell.
+ *  4. 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.
+ *
+ * THE PASS READS THE COMMITTED FRAME, NOT THE LATEST RENDER. `latest` is refreshed during
+ * render, so it can be a frame ahead of the screen; `committed` is written by a layout
+ * effect and therefore describes exactly the frame the user is looking at. With
+ * entry-granular bookkeeping the difference was harmless (printing was idempotent per
+ * entry); with ROW-granular bookkeeping it would slice this frame's picture with another
+ * frame's row numbers, and the result is a duplicate or a hole.
  *
- * `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
- * trimming AND by reducer deletion (empty settled assistants, abandoned tool
- * cards), so an id-keyed cursor can dangle, and then the only correct answer is to
- * rescan and let `printedIds` skip.
+ * `printed` is the ONLY authority on "already printed" (RV-7): a `Map` from entry id to
+ * the leading rows already handed to the writer, and the width they were measured at. The
+ * cursor is just a hint for where to resume scanning: entries leave the list by retain-ring
+ * trimming AND by reducer deletion (empty settled assistants, abandoned tool cards), so an
+ * id-keyed cursor can dangle, and then the only correct answer is to rescan and let
+ * `printed` skip.
  */
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useReducer, useRef } from 'react';
+import { estimateEntryRows } from '../layout/virtual-window.js';
 import { buildScrollbackBudget } from './budget.js';
 import { buildLivePreview } from './live-preview.js';
 import { SCROLLBACK_LIMITS } from './limits.js';
+import { capPrintedRows, planOverflowPrint, reflowSeamRow, } from './overflow-print.js';
 import { createEntryRenderer } from './renderer.js';
-import { isExcluded, settleAllEntries, settledCount } from './settled-boundary.js';
+import { isEntryStable, isExcluded, settleAllEntries } from './settled-boundary.js';
+import { resolveTailAnchor } from './tail-anchor.js';
+import { printBoundary, selectTailWindow } from './tail-window.js';
 export function createScrollbackBridge(parts) {
     return {
         writer: parts.writer,
@@ -52,48 +81,68 @@ function printableBefore(entries, index) {
 }
 /**
  * Ids leave `entries` by retain-ring trimming and never come back (ids are unique
- * per session), so `printedIds` is trimmed to the live list once it grows well past
+ * per session), so both row maps are trimmed to the live list once they grow well past
  * it. Only ids still present can be re-evaluated, so dropping the rest is lossless.
  */
-function pruneEntryIds(printed, entries) {
-    if (printed.size <= Math.max(2000, entries.length * 3))
+function pruneEntryIds(entries, printed, heights) {
+    const bound = Math.max(2000, entries.length * 3);
+    if (printed.size <= bound && heights.size <= bound)
         return;
     const live = new Set(entries.map((entry) => entry.id));
-    for (const id of printed)
+    for (const id of [...printed.keys()])
         if (!live.has(id))
             printed.delete(id);
+    // Height keys are `id|cols|expanded|thinking`; only the id part decides liveness.
+    for (const key of [...heights.keys()]) {
+        if (!live.has(key.slice(0, key.indexOf('|'))))
+            heights.delete(key);
+    }
+}
+/** The word the expanded-copy header uses for one entry kind. */
+function expandedLabel(entry) {
+    if (entry.kind === 'tool')
+        return entry.name;
+    // The escape hatch exists for the Agent's ANSWER (known limitation 2 promised it), so the
+    // header says what the user pressed Ctrl+O for instead of the internal kind name.
+    if (entry.kind === 'assistant')
+        return 'answer';
+    return entry.kind;
 }
 export function useScrollbackView(args) {
-    const { enabled, bridge, entries, runActive, theme, caps, density, thinkingVisible, reducedMotion, rows, cols, headerNode, openerNode, overlayOpen, draftRows, popupRows, statusExpanded, forceInactive = false, itemCount, panelEnabled, teamRowsNatural, } = args;
+    const { enabled, bridge, entries, runActive, theme, caps, density, thinkingVisible, reducedMotion, rows, cols, overlayOpen, draftRows, popupRows, statusExpanded, forceInactive = false, itemCount, panelEnabled, teamRowsNatural, expandedToolIds, } = args;
     const contentCols = Math.max(1, cols - 1);
-    const startedRef = useRef(false);
-    // Everything the asynchronous pass reads travels here, refreshed on every render.
+    // Everything the asynchronous EXIT and RESET paths read travels here, refreshed on every
+    // render (see `committed` for why the promotion pass does not read it).
     const latest = useRef({
-        entries, runActive, contentCols, headerNode, openerNode,
+        entries, runActive, contentCols, previewCols: contentCols, expandedToolIds,
         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,
+        entries, runActive, contentCols, previewCols: latest.current.previewCols, expandedToolIds,
         options: { theme, caps, density, thinkingVisible, reducedMotion },
     };
     const rendererRef = useRef(null);
-    const printedIds = useRef(new Set());
+    /** THE authority on "already printed" (RV-7), per entry and per row. */
+    const printed = useRef(new Map());
+    /** Measured heights, `id|cols|expanded|thinking` -> rows. Only STABLE entries are stored. */
+    const heights = useRef(new Map());
     /** 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). Same lifecycle and same
-    // reason as `heldTailRows`: 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 headRowsRef = useRef(0);
+    /** Guards the "measure, then re-render so the anchor can use it" nudge against a loop. */
+    const nudgedRef = useRef(null);
+    // 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 committed = useRef(null);
+    /** Bumped when a measurement has to reach `LiveTail` before the next pass may print. */
+    const [measureEpoch, bumpMeasureEpoch] = useReducer((n) => n + 1, 0);
     const ensureRenderer = useCallback(() => {
         if (!rendererRef.current)
             rendererRef.current = createEntryRenderer(latest.current.options);
@@ -105,57 +154,163 @@ export function useScrollbackView(args) {
             return;
         bridge.drain.enqueue(rowsToPrint, { id, kind });
     }, [bridge]);
-    /** Promote `list[start..end)`; returns true when it stopped early because the feed is full. */
-    const promote = useCallback((list, end, limit) => {
-        const renderer = ensureRenderer();
+    const heightKey = useCallback((entry, colsNow, expanded) => `${entry.id}|${colsNow}|${expanded ? 1 : 0}|${thinkingVisible ? 1 : 0}`, [thinkingVisible]);
+    /** Rows of one entry at `colsNow`, measured once per (id, cols, flags) and cached. */
+    const measure = useCallback((entry, prev, colsNow, expanded) => {
+        const key = heightKey(entry, colsNow, expanded);
+        const cached = heights.current.get(key);
+        if (cached !== undefined)
+            return cached;
+        const measured = ensureRenderer().renderEntryRows(entry, prev, colsNow, expanded).length;
+        heights.current.set(key, measured);
+        return measured;
+    }, [ensureRenderer, heightKey]);
+    /**
+     * Which width the REMAINDER of an entry must be printed at.
+     *
+     * Row numbers are width-relative, so a recorded width that this frame still legitimately
+     * renders at is the only width whose row numbers can be trusted (`known`); anything else
+     * is a reflow, and the caller starts over behind a seam row.
+     */
+    const resolvePrintWidth = useCallback((state, wanted, known) => {
+        if (!state || state.cols === wanted)
+            return wanted;
+        return known.includes(state.cols) ? state.cols : wanted;
+    }, []);
+    /**
+     * Print everything of `list[index]` that is not in the scrollback yet, in ONE go.
+     *
+     * The entry has left the region, so all of it may print; what is left is the remainder
+     * behind the rows the top give-way already printed (`printed.rows`). A width change makes
+     * those row numbers meaningless, so it prints a seam and starts over - a bounded
+     * repetition instead of a hole.
+     */
+    const printRemainder = useCallback((list, index, wantedCols, known, expanded) => {
+        const entry = list[index];
+        const state = printed.current.get(entry.id);
+        if (state?.done)
+            return;
+        const width = resolvePrintWidth(state, wantedCols, known);
+        const restart = state !== undefined && state.cols !== width;
+        const from = restart ? 0 : state?.rows ?? 0;
+        const body = ensureRenderer().renderEntryRows(entry, printableBefore(list, index), width, expanded.includes(entry.id));
+        const seam = restart ? reflowSeamRow(state.rows, state.cols, width) : null;
+        const tail = body.slice(from);
+        const capped = capPrintedRows(tail, from);
+        enqueue(seam === null ? capped : [seam, ...capped], entry.id, entry.kind);
+        printed.current.set(entry.id, { rows: body.length, cols: width, done: true });
+    }, [enqueue, ensureRenderer, resolvePrintWidth]);
+    /** Expanded ids of a frame, as a list so a callback does not depend on the object. */
+    const expandedIdsOf = useCallback((ids) => Object.keys(ids).filter((id) => ids[id] === true), []);
+    /** The window as full-list indices (excluded entries already dropped), oldest first. */
+    const windowItemsOf = useCallback((frame, start) => {
+        const items = [];
+        for (let i = start; i < frame.entries.length; i += 1) {
+            const entry = frame.entries[i];
+            if (!isExcluded(entry))
+                items.push({ index: i, entry });
+        }
+        return items;
+    }, []);
+    /**
+     * The window's measured rows, or `undefined` when the measurement cannot be trusted.
+     *
+     * TWO conditions, both structural rather than defensive. Every entry must be STABLE: an
+     * entry the reducer may still rewrite has a height that changes, and printing part of it
+     * would put a version of the answer into the scrollback that can never be corrected. And
+     * the caller has already checked that the wall does not sit before the window: rows
+     * behind an unprintable entry would land out of conversation order (I-S3), which is the
+     * one mistake an append-only medium cannot take back.
+     */
+    const measureWindow = useCallback((frame, items) => {
+        const last = frame.entries.length - 1;
+        for (const item of items) {
+            if (!isEntryStable(item.entry, frame.runActive, item.index === last))
+                return undefined;
+        }
+        const expanded = expandedIdsOf(frame.expandedToolIds);
+        return items.map((item) => {
+            const state = printed.current.get(item.entry.id);
+            const comparable = state !== undefined && state.cols === frame.previewCols && !state.done;
+            return {
+                entry: item.entry,
+                rows: measure(item.entry, printableBefore(frame.entries, item.index), frame.previewCols, expanded.includes(item.entry.id)),
+                printed: comparable ? state.rows : 0,
+                stable: true,
+            };
+        });
+    }, [expandedIdsOf, measure]);
+    /** Promote `list[start..end)`; reports when it stopped early because the feed is full. */
+    const promote = useCallback((frame, end, limit, known) => {
+        const list = frame.entries;
+        const expanded = expandedIdsOf(frame.expandedToolIds);
         let start = 0;
         const cursor = cursorRef.current;
         if (cursor && list[cursor.index]?.id === cursor.id)
             start = cursor.index + 1;
-        let promoted = 0;
+        let used = 0;
         let lastIndex = start - 1;
         const remember = () => {
             cursorRef.current = lastIndex >= 0 ? { id: list[lastIndex].id, index: lastIndex } : null;
         };
         for (let i = start; i < end; i += 1) {
             const entry = list[i];
-            if (isExcluded(entry) || printedIds.current.has(entry.id)) {
+            // A partially printed entry is NOT finished: it is processed until `done`, so a row
+            // range the give-way left behind is still picked up here (P-5).
+            if (isExcluded(entry) || printed.current.get(entry.id)?.done === true) {
                 lastIndex = i;
                 continue;
             }
-            if (promoted >= limit) {
+            if (used >= limit) {
                 remember();
-                return true;
+                return { limited: true, used };
             }
-            const rowsToPrint = renderer.renderEntry(entry, printableBefore(list, i), latest.current.contentCols);
-            enqueue(rowsToPrint, entry.id, entry.kind);
-            // A rendered-to-nothing entry is registered too, or it would be retried forever.
-            printedIds.current.add(entry.id);
-            promoted += 1;
+            printRemainder(list, i, frame.contentCols, known, expanded);
+            used += 1;
             lastIndex = i;
         }
         remember();
-        return false;
-    }, [ensureRenderer, enqueue]);
-    const printBanner = useCallback(() => {
-        if (startedRef.current)
+        return { limited: false, used };
+    }, [expandedIdsOf, printRemainder]);
+    /**
+     * 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]);
+        const known = [latest.current.contentCols, latest.current.previewCols];
+        const expanded = expandedIdsOf(latest.current.expandedToolIds);
+        for (const entry of settleAllEntries(list)) {
+            if (printed.current.get(entry.id)?.done === true)
+                continue;
+            printRemainder(list, list.indexOf(entry), latest.current.contentCols, known, expanded);
+        }
+    }, [bridge, expandedIdsOf, printRemainder]);
     const applyPendingReset = useCallback(() => {
         const reset = pendingReset.current;
         if (!reset || latest.current.entries === reset.captured)
             return;
         pendingReset.current = null;
-        printedIds.current = new Set();
+        // ORDER IS THE CONTRACT (AC-F16): flush the OLD list, then the separator, then
+        // forget what was printed. Clearing `printed` first would make the flush print
+        // the whole conversation a second time.
+        flushUnprinted(reset.captured);
+        printed.current = new Map();
         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)
@@ -163,76 +318,117 @@ export function useScrollbackView(args) {
         pumpQueued.current = true;
         queueMicrotask(() => pumpRef.current());
     }, []);
+    const continueOnDrain = useCallback(() => {
+        if (!bridge)
+            return;
+        bridge.drain.onDrained = () => {
+            bridge.drain.onDrained = null;
+            schedulePump();
+        };
+        bridge.requestFlush();
+    }, [bridge, schedulePump]);
+    /**
+     * TOP GIVE-WAY: print the rows the box hides, when it hides them from the TOP.
+     *
+     * The order of the two decisions is not cosmetic. `frame.anchor` is what the SCREEN is
+     * doing; `planOverflowPrint` answers what is off it. Printing while the frame is
+     * `top`-anchored would print the rows the user is looking at (Ink clips the BOTTOM in that
+     * branch) and leave the ones they cannot see - a duplicate and a hole at once. So a frame
+     * whose anchor the measurement contradicts is nudged once and the print waits for the
+     * frame that agrees.
+     *
+     * @returns How many segments were enqueued.
+     */
+    const printOverflow = useCallback((frame, allowance) => {
+        if (frame.tailRows <= 0)
+            return 0;
+        const maxEntries = SCROLLBACK_LIMITS.liveTailMaxEntries;
+        const { start } = selectTailWindow(frame.entries, maxEntries);
+        // The wall before the window is still a wall: the give-way would print rows that come
+        // after an unprintable entry (I-S3 / A12).
+        if (printBoundary(frame.entries, frame.runActive, maxEntries) < start)
+            return 0;
+        const items = windowItemsOf(frame, start);
+        if (items.length === 0)
+            return 0;
+        const measured = measureWindow(frame, items);
+        if (!measured)
+            return 0;
+        const total = measured.reduce((sum, item) => sum + item.rows, 0);
+        if (frame.measuredRows !== total) {
+            // `LiveTail` anchored this frame from an estimate (or from an older measurement).
+            // Hand it the number, once per distinct picture, and print on the frame that agrees.
+            const nudgeKey = `${start}|${items.length}|${total}`;
+            if (nudgedRef.current !== nudgeKey) {
+                nudgedRef.current = nudgeKey;
+                bumpMeasureEpoch();
+            }
+        }
+        if (frame.anchor !== 'bottom')
+            return 0;
+        const plan = planOverflowPrint(measured, frame.tailRows);
+        const expanded = expandedIdsOf(frame.expandedToolIds);
+        let used = 0;
+        for (const segment of plan.segments) {
+            if (used >= allowance) {
+                continueOnDrain();
+                return used;
+            }
+            const item = measured[segment.index];
+            const state = printed.current.get(item.entry.id);
+            // The segment's row numbers live in the box's index space, so the rows must be
+            // rendered and printed at that width; a stale recorded width restarts behind a seam.
+            const restart = state !== undefined && state.cols !== frame.previewCols;
+            const from = restart ? 0 : state?.rows ?? 0;
+            const body = ensureRenderer().renderEntryRows(item.entry, printableBefore(frame.entries, items[segment.index].index), frame.previewCols, expanded.includes(item.entry.id));
+            const slice = body.slice(from, Math.max(from, segment.toRow));
+            const out = capPrintedRows(slice, from);
+            const seam = restart ? reflowSeamRow(state.rows, state.cols, frame.previewCols) : null;
+            enqueue(seam === null ? out : [seam, ...out], item.entry.id, item.entry.kind);
+            const capped = out.length !== slice.length;
+            const finished = capped || segment.toRow >= item.rows;
+            printed.current.set(item.entry.id, {
+                rows: finished ? item.rows : segment.toRow,
+                cols: frame.previewCols,
+                done: finished,
+            });
+            headRowsRef.current += out.length;
+            used += 1;
+        }
+        return used;
+    }, [continueOnDrain, enqueue, ensureRenderer, expandedIdsOf, measureWindow, windowItemsOf]);
     /** The promotion pass. Runs in a microtask (see the file header). */
     pumpRef.current = () => {
         pumpQueued.current = false;
-        if (!mountedRef.current || !bridge)
+        const frame = committed.current;
+        if (!mountedRef.current || !bridge || !frame)
             return;
-        printBanner();
         applyPendingReset();
-        const { entries: list, runActive: active } = latest.current;
+        const known = [frame.contentCols, frame.previewCols];
         const limit = Math.max(1, SCROLLBACK_LIMITS.feedCapacity - bridge.drain.pendingEntries() - 1);
-        const more = promote(list, settledCount(list, active), limit);
-        pruneEntryIds(printedIds.current, list);
-        if (more) {
+        // `printBoundary` = min(settled, window start): the region keeps what it shows.
+        const end = printBoundary(frame.entries, frame.runActive, SCROLLBACK_LIMITS.liveTailMaxEntries);
+        const promoted = promote(frame, end, limit, known);
+        pruneEntryIds(frame.entries, printed.current, heights.current);
+        if (promoted.limited) {
             // Continue once the writer has consumed what is queued (a restored transcript
             // longer than the feed is promoted in waves rather than folded into a marker).
-            bridge.drain.onDrained = () => {
-                bridge.drain.onDrained = null;
-                schedulePump();
-            };
-            bridge.requestFlush();
-        }
-    };
-    useLayoutEffect(() => {
-        if (enabled && bridge)
-            schedulePump();
-    }, [enabled, bridge, entries, runActive, schedulePump]);
-    const settleAll = useCallback(() => {
-        if (!bridge)
+            continueOnDrain();
             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]);
-    // 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:
-    // it runs inside the main tree's commit, where an offscreen render is deferred.
-    const settleAllRef = useRef(settleAll);
-    settleAllRef.current = settleAll;
-    useEffect(() => {
-        mountedRef.current = true;
-        if (!enabled || !bridge)
-            return undefined;
-        bridge.settleAllNow = () => {
-            try {
-                settleAllRef.current();
-            }
-            finally {
-                rendererRef.current?.dispose();
-                rendererRef.current = null;
-            }
-        };
-        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);
+        // ORDER: everything that has left the window is older than everything in it, so the
+        // give-way only ever runs in a pass that promoted everything it had to.
+        if (printOverflow(frame, Math.max(0, limit - promoted.used)) > 0)
+            bridge.requestFlush();
+    };
+    // --- 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`).
@@ -248,29 +444,108 @@ export function useScrollbackView(args) {
     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` and the two band refs are read at memo time; `wanted`,
-    // `itemCount` and `teamRowsNatural` are what move them. ONE memo, deliberately:
-    // a second one depending on the first would render the previous frame's band.
+    // 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, itemCount, panelEnabled, teamRowsNatural]);
+    [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 preview gives up the rail's columns (I-5).
+    // Print keeps `contentCols`; only the live tail gives up the rail's columns (I-5).
     const previewCols = budget ? budget.previewCols : contentCols;
+    const tailRows = budget ? budget.liveTailRows : 0;
+    // `previewCols` is only known after the budget, so the copy above carries the PREVIOUS
+    // frame's value; this line hands the exit and reset paths the current one. The promotion
+    // pass does not read it - it reads `committed`, written below.
+    latest.current.previewCols = previewCols;
+    const lastIndex = entries.length - 1;
+    const indexById = useMemo(() => new Map(entries.map((entry, index) => [entry.id, index])), [entries]);
+    /**
+     * The window's measured height, when every entry in it is stable AND already measured at
+     * this geometry. This is the number `LiveTail` anchors with, and the number the pump
+     * compares itself against, so both agree about which frame the user is looking at.
+     */
+    const measuredTailRows = useMemo(() => {
+        if (!enabled || tailRows <= 0 || tailEntries.length === 0)
+            return undefined;
+        let total = 0;
+        for (const entry of tailEntries) {
+            if (!isEntryStable(entry, runActive, indexById.get(entry.id) === lastIndex)) {
+                return undefined;
+            }
+            const cached = heights.current.get(heightKey(entry, previewCols, expandedToolIds[entry.id] === true));
+            if (cached === undefined)
+                return undefined;
+            total += cached;
+        }
+        return total;
+        // `heights` is a ref and `measureEpoch` is what fills it; every OTHER dependency is an
+        // input of the cache key, so a stale answer is impossible.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [enabled, tailRows, tailEntries, runActive, indexById, lastIndex, previewCols,
+        expandedToolIds, thinkingVisible, measureEpoch, heightKey]);
+    const anchor = resolveTailAnchor({
+        entries: tailEntries,
+        budgetRows: tailRows,
+        rowOf: (entry) => estimateEntryRows(entry, previewCols, density, expandedToolIds[entry.id] === true, thinkingVisible),
+        measuredRows: measuredTailRows,
+    });
     const liveTailLines = useMemo(() => enabled && budget && budget.liveTailRows > 0
-        ? buildLivePreview({ unsettled, cols: previewCols, rows: budget.liveTailRows, thinkingVisible })
-        : [], [enabled, budget, unsettled, previewCols, thinkingVisible]);
+        ? buildLivePreview({
+            unsettled: tailEntries, cols: previewCols, rows: budget.liveTailRows,
+            thinkingVisible,
+        })
+        : [], [enabled, budget, tailEntries, previewCols, thinkingVisible]);
+    // THE COMMIT HOOK. Every commit records the frame the screen is showing, so the microtask
+    // pass can never slice this frame's picture with another frame's numbers. It is the last
+    // layout effect in this hook on purpose: everything above is render-time state.
+    useLayoutEffect(() => {
+        committed.current = {
+            entries, runActive, contentCols, previewCols, tailRows, anchor, measuredRows: measuredTailRows,
+            expandedToolIds,
+        };
+    });
+    // Only a content change (or a measurement that must reach `LiveTail`) needs a pass; a
+    // resize is the writer's business, exactly as before.
+    useLayoutEffect(() => {
+        if (enabled && bridge)
+            schedulePump();
+    }, [enabled, bridge, entries, runActive, measureEpoch, schedulePump]);
+    const settleAll = useCallback(() => {
+        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:
+    // it runs inside the main tree's commit, where an offscreen render is deferred.
+    const settleAllRef = useRef(settleAll);
+    settleAllRef.current = settleAll;
+    useEffect(() => {
+        mountedRef.current = true;
+        if (!enabled || !bridge)
+            return undefined;
+        bridge.settleAllNow = () => {
+            try {
+                settleAllRef.current();
+            }
+            finally {
+                rendererRef.current?.dispose();
+                rendererRef.current = null;
+            }
+        };
+        return () => { mountedRef.current = false; };
+    }, [enabled, bridge]);
     const reprintExpanded = useCallback((entryId) => {
         if (!enabled || !bridge)
             return false;
@@ -279,16 +554,41 @@ export function useScrollbackView(args) {
         if (index < 0)
             return false;
         const entry = list[index];
-        const body = ensureRenderer().renderEntry(entry, undefined, latest.current.contentCols, true);
-        if (body.length === 0)
-            return false;
-        enqueue([`-- expanded: ${entry.kind === 'tool' ? entry.name : entry.kind} --`, ...body], `expanded:${entryId}:${Date.now()}`, entry.kind);
+        // THE COPY IS RENDERED IN A MICROTASK, NOT IN THE KEY HANDLER THAT ASKED FOR IT.
+        // `Ctrl+O` arrives on the stdin stream, and an offscreen render issued from there is
+        // SCHEDULED rather than flushed - the reconciler sees a pending update, the frame the
+        // caller reads back is still empty, and the copy degrades to
+        // `[aragon] entry ... could not be rendered`. A microtask runs after the input handler
+        // has unwound, where the offscreen render is synchronous again: the same rule the
+        // promotion pass follows (see the file header). The answer is therefore "this entry
+        // exists and a copy is on its way", which is what the caller's toast needs.
+        //
+        // THE ID IS STABLE ON PURPOSE. `expanded:<entryId>` makes the copy greppable and keeps
+        // the key purely user-driven; it is not a dedupe key, because the drain is a FIFO that
+        // never coalesces, so a second press prints a second copy - the behaviour the tool cards
+        // have always had, and the reason the stable id is safe to use here.
+        queueMicrotask(() => {
+            if (!mountedRef.current || !bridge)
+                return;
+            const body = ensureRenderer().renderEntry(entry, undefined, latest.current.contentCols, true);
+            if (body.length === 0)
+                return;
+            enqueue([`-- expanded: ${expandedLabel(entry)} --`, ...body], `expanded:${entryId}`, entry.kind);
+        });
         return true;
-    }, [enabled, bridge, ensureRenderer, enqueue]);
+    }, [bridge, enabled, enqueue, ensureRenderer]);
     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, unsettledEntries: unsettled, reprintExpanded, settleAll, notifyReset };
+    return {
+        budget, liveTailLines, tailEntries, windowStart, measuredTailRows,
+        // A GETTER, like `perfRef`'s `scrollbar`: the counter moves in a microtask, so a value
+        // captured at render time would report the frame BEFORE the one `/perf` is asked about.
+        get headRows() { return headRowsRef.current; },
+        reprintExpanded, settleAll, notifyReset,
+    };
 }