@aragon-agent/cli 0.6.46 → 0.6.48

package/dist/ui/scrollback/settled-boundary.d.ts

@@ -1,42 +0,0 @@
-/**
- * Settled boundary — which transcript entries may be PRINTED
- * (tui-native-terminal-scroll §4.4).
- *
- * Printed rows live in the host terminal's scrollback and can never be rewritten
- * ("printed is forever"). So the only entries that may be printed are the ones the
- * reducer will NEVER write to again. This module derives that from the reducer's
- * real write set, one exhaustive `switch` per entry kind. Adding an `Entry` kind is
- * a compile error here (`never`), which is the whole point; widening the write set
- * of an EXISTING kind is not caught by the compiler, so `agent/reducer.ts` carries
- * a pointer comment beside the `Entry` union and the unit tests pin each row.
- *
- * Three rules that are easy to "simplify" wrongly:
- *  - A tool is stable only when `done` or `error`. `pending` is NOT stable: the
- *    card is created at `pending` and `toolCallDelta` keeps rewriting `argsRaw`
- *    while the model streams its arguments (RV-1).
- *  - A trailing `Context length exceeded` error notice is NOT stable while a run is
- *    active: `compactionStart` rewrites it in place into an info notice (RV-4).
- *  - A non-terminal `service` card is neither printed nor a wall (RV-3). It is
- *    rewritten for the whole session; the one-row `terminal: true` record the
- *    reducer appends at the end is an ordinary stable entry and carries the news.
- */
-import type { Entry } from '../../agent/reducer.js';
-/** Never printed and never a wall: rewritten for the whole session (RV-3). */
-export declare function isExcluded(entry: Entry): boolean;
-/** True when the reducer will never write to `entry` again. */
-export declare function isEntryStable(entry: Entry, runActive: boolean, isTail: boolean): boolean;
-/**
- * Length of the printable PREFIX of `entries`.
- *
- * The first unstable (non-excluded) entry is a wall: everything before it may
- * print, nothing after it may, which keeps scrollback order equal to conversation
- * order (I-S3). Excluded entries are skipped, so a long-lived service card never
- * blocks the conversation behind it.
- */
-export declare function settledCount(entries: readonly Entry[], runActive: boolean): number;
-/**
- * Everything printable at shutdown: all entries except those that never settle
- * (`queued`, non-terminal services). The last answer must not be lost to a
- * boundary that was waiting for a frame that will never come.
- */
-export declare function settleAllEntries(entries: readonly Entry[]): Entry[];

package/dist/ui/scrollback/settled-boundary.js

@@ -1,109 +0,0 @@
-/**
- * Settled boundary — which transcript entries may be PRINTED
- * (tui-native-terminal-scroll §4.4).
- *
- * Printed rows live in the host terminal's scrollback and can never be rewritten
- * ("printed is forever"). So the only entries that may be printed are the ones the
- * reducer will NEVER write to again. This module derives that from the reducer's
- * real write set, one exhaustive `switch` per entry kind. Adding an `Entry` kind is
- * a compile error here (`never`), which is the whole point; widening the write set
- * of an EXISTING kind is not caught by the compiler, so `agent/reducer.ts` carries
- * a pointer comment beside the `Entry` union and the unit tests pin each row.
- *
- * Three rules that are easy to "simplify" wrongly:
- *  - A tool is stable only when `done` or `error`. `pending` is NOT stable: the
- *    card is created at `pending` and `toolCallDelta` keeps rewriting `argsRaw`
- *    while the model streams its arguments (RV-1).
- *  - A trailing `Context length exceeded` error notice is NOT stable while a run is
- *    active: `compactionStart` rewrites it in place into an info notice (RV-4).
- *  - A non-terminal `service` card is neither printed nor a wall (RV-3). It is
- *    rewritten for the whole session; the one-row `terminal: true` record the
- *    reducer appends at the end is an ordinary stable entry and carries the news.
- */
-import { CONTEXT_OVERFLOW_NOTICE_PREFIX } from '../../agent/reducer.js';
-/** Kinds the reducer may still rewrite while a run is active, so a tail one is held. */
-const MUTABLE_TAIL_KINDS = new Set([
-    'assistant', 'tool', 'compaction', 'todo', 'team', 'fast', 'retry', 'queued',
-]);
-/** Never printed and never a wall: rewritten for the whole session (RV-3). */
-export function isExcluded(entry) {
-    return entry.kind === 'service' && entry.terminal !== true;
-}
-/** True when the reducer will never write to `entry` again. */
-export function isEntryStable(entry, runActive, isTail) {
-    switch (entry.kind) {
-        case 'user':
-            return true;
-        case 'notice':
-            return !(runActive &&
-                isTail &&
-                entry.level === 'error' &&
-                entry.text.startsWith(CONTEXT_OVERFLOW_NOTICE_PREFIX));
-        case 'assistant':
-            return !entry.streaming;
-        case 'tool':
-            return entry.status === 'done' || entry.status === 'error';
-        case 'compaction':
-            return entry.live !== true;
-        case 'todo':
-            return entry.live === false;
-        case 'team':
-            return entry.active === false;
-        case 'fast':
-            return entry.live === false;
-        case 'retry':
-            return (entry.phase === 'recovered' ||
-                entry.phase === 'exhausted' ||
-                entry.phase === 'interrupted');
-        case 'queued':
-            // Rewritten in place into a `user` entry by the matching receipt.
-            return false;
-        case 'service':
-            // Only the terminal record is ever a candidate; `isExcluded` filters the rest.
-            return entry.terminal === true;
-        case 'governance':
-            // A settlement card is appended once, already complete.
-            return true;
-        default: {
-            const exhaustive = entry;
-            return exhaustive;
-        }
-    }
-}
-/**
- * Length of the printable PREFIX of `entries`.
- *
- * The first unstable (non-excluded) entry is a wall: everything before it may
- * print, nothing after it may, which keeps scrollback order equal to conversation
- * order (I-S3). Excluded entries are skipped, so a long-lived service card never
- * blocks the conversation behind it.
- */
-export function settledCount(entries, runActive) {
-    const last = entries.length - 1;
-    let count = entries.length;
-    for (let i = 0; i < entries.length; i += 1) {
-        const entry = entries[i];
-        if (isExcluded(entry))
-            continue;
-        if (!isEntryStable(entry, runActive, i === last)) {
-            count = i;
-            break;
-        }
-    }
-    // Hold a mutable TAIL while a run is active, but only a mutable one: a `user` or
-    // `notice` at the tail prints immediately (a submitted message must appear at once).
-    if (runActive && count === entries.length && count > 0) {
-        const tail = entries[last];
-        if (!isExcluded(tail) && MUTABLE_TAIL_KINDS.has(tail.kind))
-            return last;
-    }
-    return count;
-}
-/**
- * Everything printable at shutdown: all entries except those that never settle
- * (`queued`, non-terminal services). The last answer must not be lost to a
- * boundary that was waiting for a frame that will never come.
- */
-export function settleAllEntries(entries) {
-    return entries.filter((entry) => entry.kind !== 'queued' && !isExcluded(entry));
-}

package/dist/ui/scrollback/tail-anchor.d.ts

@@ -1,71 +0,0 @@
-/**
- * Where the live tail sits inside the band's preview box
- * (tui-first-reply-bottom-aligned, plan A-prime).
- *
- * THE DEFECT THIS ANSWERS. The box is always the whole pool (`band.previewRows`, 24 rows
- * on a 30-row terminal) while a first turn is four rows tall. A constant
- * `justifyContent="flex-end"` therefore pushed those four rows against the composer and
- * left every unused row ABOVE the conversation - the "the first reply starts at the
- * bottom of the screen" report. The answer is conditional anchoring: top while the
- * content fits, so the conversation is written downwards from the region's top row
- * (`tui-header-leaks-into-scrollback` took the identity row off that row and put it
- * below the composer, so the first line of the band is now the first line of the screen).
- *
- * WHY THE FALLBACK IS `bottom` AND NOT THE OTHER WAY ROUND. `flex-start` inside an
- * `overflow="hidden"` box clips the NEWEST rows (Ink's clip rectangle is the box's
- * `[top, top + height]`), and a streaming entry is never printable
- * (`settled-boundary.ts` holds it unstable, and "printed is forever"). Overflowing to
- * `flex-start` would hide the text the user is waiting for; overflowing to `flex-end`
- * hides the oldest rows, which the tail window prints on its way out.
- *
- * THE THRESHOLD CARRIES A MARGIN. `rowOf` is an ESTIMATE, and the one available
- * (`layout/virtual-window.ts::estimateEntryRows`) under-counts a `#` heading and a code
- * block. The margin in `SCROLLBACK_LIMITS.tailAnchorSlackRows` absorbs that error on the
- * `bottom` side, the only direction that cannot clip something new.
- *
- * PURE: no Ink, no I/O, no clock, and deliberately no import of `virtual-window.ts` (its
- * import graph reaches a `.tsx` gutter). The row height is injected, so this stays three
- * parameters and a unit test can drive it with any table it likes.
- */
-import type { Entry } from '../../agent/reducer.js';
-/** `top` = content grows down from the region's top row; `bottom` = newest row hugs the
- *  composer. */
-export type TailAnchor = 'top' | 'bottom';
-/**
- * Which alignment the live tail should use for the entries it is about to render.
- *
- * @param entries The entries THIS FRAME renders (already windowed by `selectTailEntries`;
- * summing the whole conversation would make every session past the entry cap overflow and
- * anchor to the bottom forever).
- * @param budgetRows Height of the box that will clip them, in rows.
- * @param rowOf Estimated height of one entry, including its separation row.
- * @returns `top` when the estimates plus `tailAnchorSlackRows` fit in `budgetRows`,
- * `bottom` otherwise (and for the first entry that does not fit, so the loop stops early).
- */
-export declare function tailAnchor(entries: readonly Entry[], budgetRows: number, rowOf: (entry: Entry) => number): TailAnchor;
-/**
- * The anchor this frame really uses: MEASURED when the measurement exists, estimated
- * otherwise.
- *
- * WHY A MEASURED ANSWER WINS (tui-final-reply-truncated-unscrollable). The estimate is an
- * upper bound that charges a separation row this renderer may not draw, so it can claim the
- * content overflows while it actually fits (the block sits at the bottom of a half-empty
- * box - the very complaint `tui-first-reply-bottom-aligned` answered) and it under-counts a
- * heading or a wrapped code block, so it can claim the content fits while the box is really
- * clipping. The second error is the expensive one now: "top give-way" only prints while the
- * box is bottom-anchored (that is the branch that clips the TOP), so a wrongly top-anchored
- * box would clip the newest rows and print the oldest ones - the wrong half, twice.
- *
- * A measured total is available only when every window entry is stable AND already measured
- * at the current geometry (`use-scrollback-view.ts` keeps that cache), which is exactly the
- * frame on which a print decision is being made. Every other frame - streaming, resize,
- * first sight of a new entry - falls back to the estimate, unchanged.
- *
- * @param measuredRows Measured height of the same entries, or `undefined` when unknown.
- */
-export declare function resolveTailAnchor(input: {
-    entries: readonly Entry[];
-    budgetRows: number;
-    rowOf: (entry: Entry) => number;
-    measuredRows: number | undefined;
-}): TailAnchor;

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

@@ -1,79 +0,0 @@
-/**
- * Where the live tail sits inside the band's preview box
- * (tui-first-reply-bottom-aligned, plan A-prime).
- *
- * THE DEFECT THIS ANSWERS. The box is always the whole pool (`band.previewRows`, 24 rows
- * on a 30-row terminal) while a first turn is four rows tall. A constant
- * `justifyContent="flex-end"` therefore pushed those four rows against the composer and
- * left every unused row ABOVE the conversation - the "the first reply starts at the
- * bottom of the screen" report. The answer is conditional anchoring: top while the
- * content fits, so the conversation is written downwards from the region's top row
- * (`tui-header-leaks-into-scrollback` took the identity row off that row and put it
- * below the composer, so the first line of the band is now the first line of the screen).
- *
- * WHY THE FALLBACK IS `bottom` AND NOT THE OTHER WAY ROUND. `flex-start` inside an
- * `overflow="hidden"` box clips the NEWEST rows (Ink's clip rectangle is the box's
- * `[top, top + height]`), and a streaming entry is never printable
- * (`settled-boundary.ts` holds it unstable, and "printed is forever"). Overflowing to
- * `flex-start` would hide the text the user is waiting for; overflowing to `flex-end`
- * hides the oldest rows, which the tail window prints on its way out.
- *
- * THE THRESHOLD CARRIES A MARGIN. `rowOf` is an ESTIMATE, and the one available
- * (`layout/virtual-window.ts::estimateEntryRows`) under-counts a `#` heading and a code
- * block. The margin in `SCROLLBACK_LIMITS.tailAnchorSlackRows` absorbs that error on the
- * `bottom` side, the only direction that cannot clip something new.
- *
- * PURE: no Ink, no I/O, no clock, and deliberately no import of `virtual-window.ts` (its
- * import graph reaches a `.tsx` gutter). The row height is injected, so this stays three
- * parameters and a unit test can drive it with any table it likes.
- */
-import { SCROLLBACK_LIMITS } from './limits.js';
-/**
- * Which alignment the live tail should use for the entries it is about to render.
- *
- * @param entries The entries THIS FRAME renders (already windowed by `selectTailEntries`;
- * summing the whole conversation would make every session past the entry cap overflow and
- * anchor to the bottom forever).
- * @param budgetRows Height of the box that will clip them, in rows.
- * @param rowOf Estimated height of one entry, including its separation row.
- * @returns `top` when the estimates plus `tailAnchorSlackRows` fit in `budgetRows`,
- * `bottom` otherwise (and for the first entry that does not fit, so the loop stops early).
- */
-export function tailAnchor(entries, budgetRows, rowOf) {
-    const budget = Number.isFinite(budgetRows) ? Math.max(0, Math.floor(budgetRows)) : 0;
-    let rows = 0;
-    for (const entry of entries) {
-        rows += Math.max(0, rowOf(entry));
-        if (rows + SCROLLBACK_LIMITS.tailAnchorSlackRows > budget)
-            return 'bottom';
-    }
-    return 'top';
-}
-/**
- * The anchor this frame really uses: MEASURED when the measurement exists, estimated
- * otherwise.
- *
- * WHY A MEASURED ANSWER WINS (tui-final-reply-truncated-unscrollable). The estimate is an
- * upper bound that charges a separation row this renderer may not draw, so it can claim the
- * content overflows while it actually fits (the block sits at the bottom of a half-empty
- * box - the very complaint `tui-first-reply-bottom-aligned` answered) and it under-counts a
- * heading or a wrapped code block, so it can claim the content fits while the box is really
- * clipping. The second error is the expensive one now: "top give-way" only prints while the
- * box is bottom-anchored (that is the branch that clips the TOP), so a wrongly top-anchored
- * box would clip the newest rows and print the oldest ones - the wrong half, twice.
- *
- * A measured total is available only when every window entry is stable AND already measured
- * at the current geometry (`use-scrollback-view.ts` keeps that cache), which is exactly the
- * frame on which a print decision is being made. Every other frame - streaming, resize,
- * first sight of a new entry - falls back to the estimate, unchanged.
- *
- * @param measuredRows Measured height of the same entries, or `undefined` when unknown.
- */
-export function resolveTailAnchor(input) {
-    const { entries, budgetRows, rowOf, measuredRows } = input;
-    if (measuredRows === undefined || !Number.isFinite(measuredRows)) {
-        return tailAnchor(entries, budgetRows, rowOf);
-    }
-    const budget = Number.isFinite(budgetRows) ? Math.max(0, Math.floor(budgetRows)) : 0;
-    return measuredRows > budget ? 'bottom' : 'top';
-}

package/dist/ui/scrollback/tail-window.d.ts

@@ -1,73 +0,0 @@
-/**
- * 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; what a single entry
- * taller than the region used to do is the whole subject of
- * `overflow-print.ts` (tui-final-reply-truncated-unscrollable). The box still clips it
- * from the top with `justifyContent="flex-end"`, but the rows it hides are now PRINTED
- * into the terminal's scrollback, where the wheel already reaches, instead of waiting for
- * `K` further entries (README, known limitation 2 - rewritten by that fix).
- *
- * PURE: no Ink, no I/O, no clock. `promote()` (the writer's only feeder) takes
- * `printBoundary`'s result and keeps its own `printed` 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. That second gap is what the row-level plan
- * closes, and `/perf`'s `window=<start>/<n> head=<rows>` is how it stays observable.
- */
-import type { Entry } from '../../agent/reducer.js';
-/**
- * Entries that take NO slot in the window: they neither print nor take a row.
- *
- * A LIVE DISPATCH CARD JOINS THE NON-TERMINAL SERVICE CARD HERE
- * (tui-subagent-double-roster A-2'): the roster draws the live dispatch and the
- * transcript draws nothing, so the window must not spend one of its slots on an
- * entry that is not on screen. THE PRINT PUMP AND THE BOX MUST AGREE ABOUT SLOTS:
- * so both window functions below skip it, and `LiveTail.selectTailEntries` - the
- * window function the box renders - imports this one instead of spelling the
- * composition out a second time.
- */
-export declare function isSlotless(entry: Entry): boolean;
-export interface TailWindow {
-    /** First index of the window inside the full entry list. */
-    start: number;
-    /** Entries inside the window, oldest first (excluded entries already dropped). */
-    entries: readonly Entry[];
-}
-/**
- * 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 declare function tailWindowStart(entries: readonly Entry[], maxEntries: number): number;
-/** `entries.slice(start)` with the entries that never print dropped. */
-export declare function selectTailWindow(entries: readonly Entry[], maxEntries: number): TailWindow;
-/**
- * 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 declare function printBoundary(entries: readonly Entry[], runActive: boolean, maxEntries: number): number;

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

@@ -1,89 +0,0 @@
-/**
- * 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; what a single entry
- * taller than the region used to do is the whole subject of
- * `overflow-print.ts` (tui-final-reply-truncated-unscrollable). The box still clips it
- * from the top with `justifyContent="flex-end"`, but the rows it hides are now PRINTED
- * into the terminal's scrollback, where the wheel already reaches, instead of waiting for
- * `K` further entries (README, known limitation 2 - rewritten by that fix).
- *
- * PURE: no Ink, no I/O, no clock. `promote()` (the writer's only feeder) takes
- * `printBoundary`'s result and keeps its own `printed` 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. That second gap is what the row-level plan
- * closes, and `/perf`'s `window=<start>/<n> head=<rows>` is how it stays observable.
- */
-import { isExcluded, settledCount } from './settled-boundary.js';
-import { isLiveTeamCard } from '../team-status.js';
-/**
- * Entries that take NO slot in the window: they neither print nor take a row.
- *
- * A LIVE DISPATCH CARD JOINS THE NON-TERMINAL SERVICE CARD HERE
- * (tui-subagent-double-roster A-2'): the roster draws the live dispatch and the
- * transcript draws nothing, so the window must not spend one of its slots on an
- * entry that is not on screen. THE PRINT PUMP AND THE BOX MUST AGREE ABOUT SLOTS:
- * so both window functions below skip it, and `LiveTail.selectTailEntries` - the
- * window function the box renders - imports this one instead of spelling the
- * composition out a second time.
- */
-export function isSlotless(entry) {
-    return isExcluded(entry) || isLiveTeamCard(entry);
-}
-/**
- * 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 (isSlotless(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) => !isSlotless(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,139 +0,0 @@
-/**
- * `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-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 / I-F10).
- *
- * What it does when enabled:
- *  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.
- *
- * 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 type { Entry } from '../../agent/reducer.js';
-import type { TermCapabilities } from '../capabilities.js';
-import type { DensityMode } from '../density.js';
-import type { Theme } from '../theme.js';
-import { type ScrollbackBudget } from './budget.js';
-import type { ScrollbackDrain } from './drain.js';
-import type { ScrollbackWriter } from './scrollback-writer.js';
-/** The channel between `cli.tsx` (which owns the stream) and the React tree. */
-export interface ScrollbackBridge {
-    writer: ScrollbackWriter;
-    drain: ScrollbackDrain;
-    /** Installed by `cli.tsx`: schedule `writer.repaint()` soon. */
-    requestFlush: () => void;
-    /**
-     * Installed by the hook on mount (reads the latest entries through a ref).
-     * `restore()` calls it on every exit path; it is idempotent through `printed`
-     * and it releases the offscreen renderer when done.
-     */
-    settleAllNow: () => void;
-    /** Installed by `App`; at most `exitSummaryMaxRows` rows. Wrapped in try/catch by the caller. */
-    getSummaryRows: () => readonly string[];
-    /** Installed by `App`: the writer swallowed repeated tall frames (degrade to the placeholder). */
-    onGuardTrip: (() => void) | null;
-}
-export declare function createScrollbackBridge(parts: Pick<ScrollbackBridge, 'writer' | 'drain'> & {
-    requestFlush?: () => void;
-}): ScrollbackBridge;
-export type ScrollbackResetKind = 'clear' | 'restore';
-export interface UseScrollbackViewArgs {
-    /** `scrollMode === 'native'`. */
-    enabled: boolean;
-    bridge: ScrollbackBridge | undefined;
-    entries: readonly Entry[];
-    runActive: boolean;
-    theme: Theme;
-    caps: TermCapabilities;
-    density: DensityMode;
-    thinkingVisible: boolean;
-    reducedMotion: boolean;
-    /** Terminal size. */
-    rows: number;
-    cols: number;
-    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;
-    /**
-     * `state.expandedToolIds` - REQUIRED, because the height of a window entry depends on it
-     * and a forgotten value would measure an expansion the region is not drawing.
-     */
-    expandedToolIds: Record<string, true>;
-}
-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;
-    /**
-     * Measured height of `tailEntries`, once every one of them is stable AND measured at the
-     * current geometry; `undefined` otherwise. `LiveTail` prefers it over the estimate - see
-     * `tail-anchor.ts::resolveTailAnchor` for why the measured answer has to win.
-     */
-    measuredTailRows: number | undefined;
-    /** Rows the top give-way has printed this session; `/perf`'s `head=`. */
-    headRows: number;
-    /** Print a fresh EXPANDED copy of an entry; false when it cannot be found / rendered. */
-    reprintExpanded(entryId: string): boolean;
-    /** 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;
-}
-export declare function useScrollbackView(args: UseScrollbackViewArgs): ScrollbackView;