@aragon-agent/cli 0.6.33 → 0.6.35

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

@@ -1,6 +1,7 @@
 /**
  * `useScrollbackView` — the promotion pipeline of native-scroll mode
- * (tui-native-terminal-scroll §4.4 / §6.2, tui-full-height-live-region D3/D4/D7/D8).
+ * (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
@@ -12,8 +13,15 @@
  *     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,
+ *  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
@@ -27,20 +35,31 @@
  * 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.
  *
- * `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.
+ * 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.
+ *
+ * `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 { isLiveTeamCard } from '../team-status.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 } 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 {
@@ -63,34 +82,57 @@ 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, 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);
-    // 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,
+        entries, runActive, contentCols, previewCols: contentCols, expandedToolIds,
         options: { theme, caps, density, thinkingVisible, reducedMotion },
     });
     latest.current = {
-        entries, runActive, contentCols,
+        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 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.
@@ -99,6 +141,9 @@ export function useScrollbackView(args) {
     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);
@@ -110,38 +155,124 @@ 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]);
+        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.
@@ -160,24 +291,24 @@ export function useScrollbackView(args) {
     const flushUnprinted = useCallback((list) => {
         if (!bridge)
             return;
-        const renderer = ensureRenderer();
+        const known = [latest.current.contentCols, latest.current.previewCols];
+        const expanded = expandedIdsOf(latest.current.expandedToolIds);
         for (const entry of settleAllEntries(list)) {
-            if (printedIds.current.has(entry.id))
+            if (printed.current.get(entry.id)?.done === true)
                 continue;
-            enqueue(renderer.renderEntry(entry, printableBefore(list, list.indexOf(entry)), latest.current.contentCols), entry.id, entry.kind);
-            printedIds.current.add(entry.id);
+            printRemainder(list, list.indexOf(entry), latest.current.contentCols, known, expanded);
         }
-    }, [bridge, ensureRenderer, enqueue]);
+    }, [bridge, expandedIdsOf, printRemainder]);
     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
+        // forget what was printed. Clearing `printed` first would make the flush print
         // the whole conversation a second time.
         flushUnprinted(reset.captured);
-        printedIds.current = new Set();
+        printed.current = new Map();
         cursorRef.current = null;
         enqueue([reset.kind === 'clear' ? CLEARED_ROW : RESTORED_ROW], `reset:${Date.now()}`, 'notice');
     }, [enqueue, flushUnprinted]);
@@ -188,56 +319,109 @@ 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;
         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);
         // `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) {
+        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();
+            continueOnDrain();
+            return;
         }
+        // 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();
     };
-    useLayoutEffect(() => {
-        if (enabled && bridge)
-            schedulePump();
-    }, [enabled, bridge, entries, runActive, 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]);
     // --- 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
@@ -281,12 +465,88 @@ export function useScrollbackView(args) {
     }
     // 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: 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;
@@ -295,12 +555,35 @@ 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)
+        // A LIVE DISPATCH CARD IS REFUSED, NOT PRINTED (tui-subagent-double-roster A-2').
+        // `Ctrl+O` arrives mid-dispatch, `EntryView` suppresses this card, and a copy
+        // printed here would be a FROZEN SNAPSHOT of a card the roster is still rewriting -
+        // permanently in the scrollback, because printed is forever.
+        if (isLiveTeamCard(entry))
             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;
@@ -309,6 +592,10 @@ export function useScrollbackView(args) {
         pendingReset.current = { kind, captured: latest.current.entries };
     }, [enabled]);
     return {
-        budget, liveTailLines, tailEntries, windowStart, reprintExpanded, settleAll, notifyReset,
+        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,
     };
 }