@aragon-agent/cli 0.6.33 → 0.6.35

package/dist/ui/overlays/model-profile-state.js

@@ -41,10 +41,38 @@ export function createModelProfileState(draft) {
     return { draft: copy, page: 'root', role: 'main', returnPage: 'manager',
         bindNew: false, dirty: false };
 }
+/** The kits whose three slots name `id`, for the delete confirmation (D-9). */
+export function kitsUsingProfile(profiles, id) {
+    return (profiles?.kits ?? []).filter((kit) => kit.mainProfileId === id
+        || kit.fastProfileId === id
+        || (kit.subagent.model === 'profile' && kit.subagent.modelProfileId === id));
+}
+/**
+ * Drop `slot` from the session kit (§4.3 row 2 / AC-38).
+ *
+ * THE DRAFT IS NARROWED HERE, NOT ONLY AT SAVE TIME. `releasedSlots` already
+ * strips the same slot from the transaction before it commits, but the ROOT PAGE
+ * paints the kit's effective value for every HELD slot - so without this line a
+ * user picks a profile and the row keeps showing the one they just replaced,
+ * which is the most confusing thing a settings screen can do. Releasing the last
+ * slot ends the kit: `held: []` is not a state any surface can render.
+ */
+function releaseHeldSlot(draft, slot) {
+    const current = draft.sessionKit;
+    if (!current || !current.held.includes(slot))
+        return draft;
+    const held = current.held.filter((item) => item !== slot);
+    return { ...draft, sessionKit: held.length ? { id: current.id, held } : null };
+}
 /** Describe references using text so ASCII and no-color modes remain usable. */
 export function profileUsers(profiles, id, subagentProfileId) {
+    // THE KITS ARE REFERENCES TOO (D-9 / RV-P2-6): "Main + kit "Deep work"" is what
+    // makes the confirmation honest, because deleting this entry also deletes that
+    // kit. The empty case must stay empty - a leading ` + ` is what a naive
+    // `join` after an unconditional push produces.
     return [profiles?.mainId === id ? 'Main' : '', profiles?.fastId === id ? 'Fast' : '',
-        subagentProfileId === id ? 'Subagent' : '']
+        subagentProfileId === id ? 'Subagent' : '',
+        ...kitsUsingProfile(profiles, id).map((kit) => `kit "${kit.name}"`)]
         .filter(Boolean).join(' + ');
 }
 /**
@@ -155,14 +183,27 @@ export function modelProfileReducer(state, action) {
                         ? { model: 'fast', modelProfileId: null }
                         : { model: 'profile', modelProfileId: action.id };
                 return { ...state, page: 'root', dirty: true, error: undefined,
-                    draft: { ...state.draft, patch: { ...state.draft.patch, team } } };
+                    draft: releaseHeldSlot({ ...state.draft,
+                        patch: { ...state.draft.patch, team } }, 'subagent') };
             }
+            // `'binding'` NEVER REACHES THIS REDUCER: a kit slot's choice is applied
+            // by `kitReducer` (`kit-main` / `kit-fast`), because the value belongs to
+            // an editor draft rather than to a `${role}Id` library key. Returning the
+            // state unchanged is the honest answer to an impossible action.
+            if (action.role === 'binding')
+                return state;
             return { ...state, page: 'root', dirty: true, error: undefined,
-                draft: { ...state.draft, profiles: { ...library, [`${action.role}Id`]: action.id },
-                    activateRoles: [...new Set([...state.draft.activateRoles, action.role])] } };
+                draft: releaseHeldSlot({ ...state.draft,
+                    profiles: { ...library, [`${action.role}Id`]: action.id },
+                    activateRoles: [...new Set([...state.draft.activateRoles, action.role])] }, action.role) };
         }
         case 'edit': return { ...state, editor: createProfileEditor(action.profile), page: 'editor',
-            returnPage: state.page === 'picker' ? 'picker' : 'manager',
+            // A PROFILE BORN IN A KIT SLOT RETURNS TO THAT SLOT (§4.5): the picker's
+            // `Create profile` action is the only way to invent one and it is offered on
+            // the kit's slot chooser - landing in the profile MANAGER there would
+            // abandon the half-built kit behind a page the user never asked for.
+            returnPage: state.page === 'picker' || state.page === 'kit-slot'
+                ? state.page : 'manager',
             bindNew: action.bindNew ?? false, error: undefined };
         case 'editor-field': return editField(state, action);
         case 'retain-key': return state.editor?.original.apiKey ? { ...state,
@@ -206,17 +247,29 @@ export function modelProfileReducer(state, action) {
             // when it named THIS entry. `removeModelProfile`'s throw stays as the
             // bottom-line defense - the UI has already unbound, so it cannot fire
             // on this path.
+            //
+            // AND THE KITS GO WITH IT (agent-model-kits D-9 / I-8): a kit naming a
+            // deleted profile can neither be applied nor repaired from any screen, so
+            // leaving it behind would be leaving a permanent error. The confirmation
+            // page has already named them, so this is the action the user agreed to.
+            const doomed = kitsUsingProfile(library, id);
+            const defaultKitKept = doomed.some((kit) => kit.id === (library.defaultKitId ?? null))
+                ? null : library.defaultKitId;
+            const sessionReleased = doomed.some((kit) => kit.id === state.draft.sessionKit?.id)
+                ? null : state.draft.sessionKit;
             const profiles = {
                 ...library,
                 mainId: library.mainId === id ? null : library.mainId,
                 fastId: library.fastId === id ? null : library.fastId,
                 entries: library.entries.filter((entry) => entry.id !== id),
+                kits: (library.kits ?? []).filter((kit) => !doomed.includes(kit)),
+                defaultKitId: defaultKitKept,
             };
             const teamReset = draftSubagentProfileId(state.draft) === id
                 ? { team: { model: 'main', modelProfileId: null } }
                 : {};
             return { ...state, page: 'manager', dirty: true,
-                draft: { ...state.draft, profiles,
+                draft: { ...state.draft, profiles, sessionKit: sessionReleased,
                     patch: { ...state.draft.patch, ...teamReset } },
                 deleteId: undefined, deleteUsers: undefined,
                 // No orphan editor for a deleted entry (3.7).

package/dist/ui/scrollback/LiveTail.d.ts

@@ -4,8 +4,8 @@
  *
  * WHY THIS FILE EXISTS. Native scroll mode cannot print an entry until it settles, so
  * the live region used to show `buildLivePreview`'s plain-text projection - and for a
- * running dispatch that projection is four grey rows saying `Team: 2/4 running`. That
- * is the "simple look" the feature was opened for. A text-only region can never fix
+ * running dispatch that projection was four grey rows saying `Team: 2/4 running`. It
+ * was the "simple look" the feature was opened for. A text-only region can never fix
  * it, which is why the region's content type changed from `readonly string[]` to a
  * fixed-height box that can hold components.
  *
@@ -16,7 +16,7 @@
  * frame; the region therefore holds the last `SCROLLBACK_LIMITS.liveTailMaxEntries`
  * PRINTABLE entries, settled or not, and an entry is printed when it LEAVES that window.
  * The window is `tail-window.ts`'s definition; this component only slides it over the
- * list and lets the fixed-height box clip from the top.
+ * list and lets the fixed-height box clip from the top when it overflows.
  *
  * IT RENDERS `EntryView` AND NOTHING ELSE. The mapping from an entry to its component
  * (`assistant` / `tool` / `team` / `todo` / service cards, notice frames, the `null`
@@ -26,12 +26,39 @@
  * left rail glyph and the transcript's would keep it, and the two halves of one screen
  * would disagree about the same entry.
  *
- * `justifyContent="flex-end"` PLUS `overflow="hidden"` IS CORRECTNESS, NOT STYLE: when
- * the content is taller than the budget the rows that get clipped are the OLDEST ones,
- * so the newest line always sits against the composer - the same promise
- * `scrollback/canvas.ts` makes about the live tail. (`ScrollbackShell` flips this to
- * `flex-start` for the empty-session opener, which is the one frame where the content
- * must hug the HEADER instead; it never renders this component.)
+ * TOP-ANCHORED WHILE THE CONTENT FITS, BOTTOM-ANCHORED WHEN IT DOES NOT
+ * (tui-first-reply-bottom-aligned, plan A-prime). A constant `flex-end` is what a user
+ * reports as "the first reply shows up at the bottom": the box is always the whole pool,
+ * so a four-row first turn was pushed against the composer and every unused row sat ABOVE
+ * the conversation. `tailAnchor` therefore sums the estimated height of exactly the
+ * entries this frame renders and asks for `flex-start` while they fit - the conversation
+ * is then written downwards from under the header, the way a terminal writes.
+ *
+ * THE OVERFLOW FRAME STAYS `flex-end`, AND THAT IS THE OTHER HALF OF THE FIX.
+ * `flex-start` PLUS `overflow="hidden"` clips the NEWEST rows (Ink's clip rectangle is
+ * the box's own `[top, top + height]`), and a streaming entry can never be printed into
+ * the scrollback to make up for it (`settled-boundary.ts` holds it unstable, and printed
+ * rows are permanent). `flex-end` clips the OLDEST rows instead, which is the promise
+ * `scrollback/canvas.ts` makes about the live tail: the newest line always sits against
+ * the composer. Those clipped rows are what `overflow-print.ts` prints, which is why the
+ * branch has to be `bottom` before anything is printed - and why `measuredRows` exists.
+ *
+ * THE SWITCH COSTS ONE DOWNWARD MOVE ON A STREAMING FRAME, AND IT IS NOT FREE. The two
+ * branches are only pixel-identical where the content EXACTLY fills the box, and the
+ * estimate cannot know that: `estimateEntryRows` charges every entry a separation row while
+ * `density.ts::separationRows` only draws one above a `user` entry, so the frame that
+ * flips is still a few rows short of the box and the block drops by those rows once -
+ * three on a 30-row terminal (the margin plus that over-count) - before it starts
+ * scrolling up a row per line. Accepted and pinned by
+ * `scrollback-first-reply-anchor.test.tsx`: anchoring to the top until the content
+ * really fills the box is exactly the frame that clips the newest row, and measuring the
+ * box every frame is the cost plan A-prime exists to avoid.
+ *
+ * A SETTLED WINDOW IS MEASURED ANYWAY, so the move is exact there (`measuredRows`).
+ * `use-scrollback-view.ts` has to measure the window to decide what the box hides, and
+ * `resolveTailAnchor` lets that measurement decide the anchor: `flex-end` exactly when the
+ * content is taller than the box. So the glitch above survives only on frames where no
+ * measurement exists yet - every streaming frame, i.e. exactly the case the pin covers.
  *
  * BOUNDED: at most `SCROLLBACK_LIMITS.liveTailMaxEntries` component instances per frame
  * (I-10). That is what keeps the per-frame cost the same order as the full-screen live
@@ -62,6 +89,13 @@ export interface LiveTailProps {
     nowSec?: number;
     theme: Theme;
     caps: TermCapabilities;
+    /**
+     * Measured height of exactly the entries this frame renders, when the owner of the
+     * measurement (`use-scrollback-view.ts`) has it. It decides the anchor INSTEAD of the
+     * estimate - see `resolveTailAnchor`. `undefined` on every frame without a full
+     * measurement, which is every streaming frame: the estimate then decides, as before.
+     */
+    measuredRows?: number;
 }
 export interface TailEntry {
     entry: Entry;
@@ -76,4 +110,4 @@ export interface TailEntry {
  * separation row the transcript shows above the same card.
  */
 export declare function selectTailEntries(entries: readonly Entry[], maxEntries: number): readonly TailEntry[];
-export declare function LiveTail({ entries, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, }: LiveTailProps): React.ReactElement;
+export declare function LiveTail({ entries, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, measuredRows, }: LiveTailProps): React.ReactElement;

package/dist/ui/scrollback/LiveTail.js

@@ -1,8 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Box } from 'ink';
 import { EntryView, nowSecFor } from '../Transcript.js';
+import { estimateEntryRows } from '../layout/virtual-window.js';
 import { SCROLLBACK_LIMITS } from './limits.js';
-import { isExcluded } from './settled-boundary.js';
+import { isSlotless } from './tail-window.js';
+import { resolveTailAnchor } from './tail-anchor.js';
 /**
  * The last `maxEntries` printable entries, each with its predecessor.
  *
@@ -11,7 +13,12 @@ import { isExcluded } from './settled-boundary.js';
  * separation row the transcript shows above the same card.
  */
 export function selectTailEntries(entries, maxEntries) {
-    const printable = entries.filter((entry) => !isExcluded(entry));
+    // A LIVE DISPATCH CARD TAKES NO SLOT (tui-subagent-double-roster A-2): the roster
+    // draws it and `EntryView` returns null for it, so the window must not spend one of
+    // its slots on an entry that is not on screen. `isSlotless` is `tail-window.ts`'s
+    // predicate - the one `selectTailWindow` and the print pump apply - so the box and
+    // `planOverflowPrint` cannot drift into different windows.
+    const printable = entries.filter((entry) => !isSlotless(entry));
     const limit = Number.isFinite(maxEntries) ? Math.max(0, Math.floor(maxEntries)) : 0;
     if (limit === 0)
         return [];
@@ -25,8 +32,17 @@ export function selectTailEntries(entries, maxEntries) {
     }
     return selected;
 }
-export function LiveTail({ entries, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, }) {
+export function LiveTail({ entries, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, measuredRows, }) {
     const limited = Math.min(maxEntries, SCROLLBACK_LIMITS.liveTailMaxEntries);
     const selected = selectTailEntries(entries, limited);
-    return (_jsx(Box, { flexDirection: "column", height: rows, width: cols, justifyContent: "flex-end", flexShrink: 0, overflow: "hidden", children: selected.map(({ entry, prev }) => (_jsx(EntryView, { entry: entry, prev: prev, expanded: expandedToolIds[entry.id] === true, thinkingVisible: thinkingVisible, reducedMotion: reducedMotion, density: density, nowSec: nowSecFor(entry, nowSec), theme: theme, caps: caps }, entry.id))) }));
+    // `estimateEntryRows` is the estimate the transcript's virtual window already uses, so
+    // the anchor can never disagree with the height the rest of the interface plans for.
+    const estimateRows = (entry) => estimateEntryRows(entry, cols, density, expandedToolIds[entry.id] === true, thinkingVisible);
+    const anchor = resolveTailAnchor({
+        entries: selected.map((tailEntry) => tailEntry.entry),
+        budgetRows: rows,
+        rowOf: estimateRows,
+        measuredRows,
+    });
+    return (_jsx(Box, { flexDirection: "column", height: rows, width: cols, justifyContent: anchor === 'top' ? 'flex-start' : 'flex-end', flexShrink: 0, overflow: "hidden", children: selected.map(({ entry, prev }) => (_jsx(EntryView, { entry: entry, prev: prev, expanded: expandedToolIds[entry.id] === true, thinkingVisible: thinkingVisible, reducedMotion: reducedMotion, density: density, nowSec: nowSecFor(entry, nowSec), theme: theme, caps: caps }, entry.id))) }));
 }

package/dist/ui/scrollback/limits.d.ts

@@ -39,6 +39,22 @@ export declare const SCROLLBACK_LIMITS: {
      * blank band between the result and the running card.
      */
     readonly liveTailMaxEntries: 10;
+    /**
+     * Safety margin the live tail asks for before it anchors its content to the TOP of
+     * the region (tui-first-reply-bottom-aligned, plan A-prime; the decision itself is
+     * `tail-anchor.ts`).
+     *
+     * 2 is DERIVED, not a preference. The anchor is decided from
+     * `layout/virtual-window.ts::estimateEntryRows`, which charges one separation row per
+     * entry and counts RAW markdown lines - so it UNDER-estimates a `#` heading (which
+     * also draws an `hrule`) and a code block (whose rail narrows the text by two columns,
+     * making long lines wrap). Inside a virtual window that error self-corrects when the
+     * entry is measured; the live region has no measurement pass, so the same error would
+     * decide which rows get CLIPPED - and `flex-start` clips the NEWEST rows.
+     * The margin must therefore always stay on the `bottom` side: a needless fallback
+     * costs one stacked frame, an early anchor hides the text the user is waiting for.
+     */
+    readonly tailAnchorSlackRows: 2;
     /**
      * Rows the rail needs before the band will show it: `TODO_LIMITS.panelMinRows + 1`.
      *

package/dist/ui/scrollback/limits.js

@@ -39,6 +39,22 @@ export const SCROLLBACK_LIMITS = {
      * blank band between the result and the running card.
      */
     liveTailMaxEntries: 10,
+    /**
+     * Safety margin the live tail asks for before it anchors its content to the TOP of
+     * the region (tui-first-reply-bottom-aligned, plan A-prime; the decision itself is
+     * `tail-anchor.ts`).
+     *
+     * 2 is DERIVED, not a preference. The anchor is decided from
+     * `layout/virtual-window.ts::estimateEntryRows`, which charges one separation row per
+     * entry and counts RAW markdown lines - so it UNDER-estimates a `#` heading (which
+     * also draws an `hrule`) and a code block (whose rail narrows the text by two columns,
+     * making long lines wrap). Inside a virtual window that error self-corrects when the
+     * entry is measured; the live region has no measurement pass, so the same error would
+     * decide which rows get CLIPPED - and `flex-start` clips the NEWEST rows.
+     * The margin must therefore always stay on the `bottom` side: a needless fallback
+     * costs one stacked frame, an early anchor hides the text the user is waiting for.
+     */
+    tailAnchorSlackRows: 2,
     /**
      * Rows the rail needs before the band will show it: `TODO_LIMITS.panelMinRows + 1`.
      *

package/dist/ui/scrollback/live-preview.js

@@ -20,6 +20,7 @@
 import { clampLiveText } from '../live-clamp.js';
 import { wrapToRows } from '../layout/wrap-rows.js';
 import { isExcluded } from './settled-boundary.js';
+import { isLiveTeamCard, outcomePhrase, rosterCounts } from '../team-status.js';
 import { clipLine } from './writer-shapes.js';
 const MAX_TEAM_RUN_ROWS = 3;
 const TOOL_LIVE_ROWS = 6;
@@ -56,8 +57,10 @@ function toolRows(entry, cols) {
     return out;
 }
 function teamRows(entry, cols) {
-    const running = entry.runs.filter((run) => !['queued', 'done', 'failed', 'aborted'].includes(run.phase)).length;
-    const out = [fit(`Team: ${running}/${entry.runs.length} running`, cols)];
+    // ONLY A SETTLED CARD REACHES HERE (the live one projects nothing, below), so the
+    // outcome phrase - `team-status.ts`'s own sentence - replaces an always-zero fraction.
+    const counts = rosterCounts(entry.runs);
+    const out = [fit(`Team: ${outcomePhrase(counts)}`, cols)];
     for (const run of entry.runs.slice(0, MAX_TEAM_RUN_ROWS)) {
         out.push(fit(`  ${run.label} ${run.phase}`, cols));
     }
@@ -71,7 +74,11 @@ function entryRows(entry, input) {
         case 'tool':
             return toolRows(entry, cols);
         case 'team':
-            return teamRows(entry, cols);
+            // THE LIVE DISPATCH HAS ONE SURFACE (tui-subagent-double-roster A-2): this
+            // projection is the text fallback for the same slot `LiveTail` fills, so a
+            // `Team: n/m running` line here would be the second live block again, one level
+            // down. A settled card still projects normally.
+            return isLiveTeamCard(entry) ? [] : teamRows(entry, cols);
         case 'todo':
             return [fit(`Todo: ${entry.doneCount}/${entry.total}`, cols)];
         case 'compaction':

package/dist/ui/scrollback/overflow-print.d.ts

@@ -0,0 +1,108 @@
+/**
+ * TOP GIVE-WAY - the row-level print plan of the native-scroll live region
+ * (tui-final-reply-truncated-unscrollable, plan A-prime / B3).
+ *
+ * THE DEFECT THIS ANSWERS. The region is the whole screen (`H = rows - 1`), so the box
+ * that holds the conversation is only `previewRows` tall (24 rows on a 30-row terminal),
+ * while the boundary that decides what may print into the terminal's scrollback is
+ * counted in ENTRIES (`liveTailMaxEntries`). A settled answer taller than the box is
+ * therefore inside the window, never printed, and clipped from the top by
+ * `justifyContent="flex-end"`. Native mode has no in-frame viewport - the wheel scrolls
+ * the terminal's scrollback - so the clipped rows exist nowhere the user can reach.
+ *
+ * The region cannot simply grow: a frame as tall as the terminal makes Ink write
+ * `clearTerminal` (which contains `ESC[3J`) and that erases the user's scrollback. So the
+ * only direction that keeps both promises is this one: the box keeps showing what it can,
+ * and the rows it hides are PRINTED into the scrollback, where the terminal's own scroll
+ * already reaches. Nothing on screen changes; the head of a long answer simply becomes
+ * readable one wheel turn up.
+ *
+ * WHAT THE PLAN GUARANTEES (the invariants the implementation batches are verified by):
+ *  I-B1 `printed(e) + visible(e) = rows(e)` and the two ranges are adjacent and disjoint,
+ *       so `scrollback + screen` covers every row exactly once (no gap, no duplicate).
+ *  I-B2 Only STABLE entries may print, and the FIRST unstable entry is a wall: nothing at
+ *       or after it is ever planned, even when a stable entry follows it (a `notice` after
+ *       a streaming answer is stable, and printing it here would put rows into the
+ *       scrollback out of conversation order, which is unrecoverable).
+ *  I-B3 The plan is ordered oldest-first and carries no gaps: the caller prints the
+ *       segments in the order given, so the scrollback keeps conversation order.
+ *  I-B4 It never plans a row that is still on screen: `hiddenRows` is measured against the
+ *       box height, and the box clips from the TOP only while it is bottom-anchored
+ *       (`tail-anchor.ts`), which the caller checks before printing anything.
+ *
+ * PURE: no Ink, no I/O, no clock, no `node:*`. That is why the caller injects the measured
+ * heights and the printed counts instead of this module measuring anything itself: the same
+ * arithmetic then drives a unit test with an arbitrary table instead of a screen.
+ */
+import type { Entry } from '../../agent/reducer.js';
+/** One entry of the tail window, as the planner needs it. */
+export interface OverflowWindowEntry {
+    entry: Entry;
+    /**
+     * Rows this entry occupies in the live region, measured at the SAME width the region
+     * draws it at (`previewCols`). An estimate is not good enough here: the plan decides how
+     * many rows are hidden, and a wrong count either duplicates a visible row or leaves one
+     * unreachable.
+     */
+    rows: number;
+    /** Leading rows of this entry already in the scrollback, `0` when none. */
+    printed: number;
+    /**
+     * `isEntryStable(entry, runActive, isTail)` for this entry - the caller's answer, because
+     * "is this the tail" is a property of the FULL list and the window is a filtered slice.
+     */
+    stable: boolean;
+}
+/** One run of rows to print: `[fromRow, toRow)` of `entry`'s own rows. */
+export interface OverflowSegment {
+    /** Index into the window the planner was given. */
+    index: number;
+    id: string;
+    /** First row to print, 0-based from the top of the entry. */
+    fromRow: number;
+    /** One past the last row to print. */
+    toRow: number;
+}
+export interface OverflowPlan {
+    /** Rows to hand to the writer, oldest entry first (I-B3). */
+    segments: readonly OverflowSegment[];
+    /** Rows the box hides above its top edge; `0` when the window fits. */
+    hiddenRows: number;
+    /** Measured height of the whole window, including entries past the wall. */
+    totalRows: number;
+}
+/**
+ * Which rows of the window the box is hiding, and how many of them are not printed yet.
+ *
+ * @param window The tail window, OLDEST FIRST, excluded entries already dropped.
+ * @param budgetRows Height of the box that shows the window (`band.previewRows`).
+ * @returns The print plan; `segments` is empty when nothing is hidden or when the first
+ * unstable entry sits at the top of the window (see I-B2).
+ */
+export declare function planOverflowPrint(window: readonly OverflowWindowEntry[], budgetRows: number): OverflowPlan;
+/**
+ * The row that marks a WIDTH CHANGE inside one entry's printed history.
+ *
+ * "Rows already printed" is a width-relative quantity: a line that took two rows at 80
+ * columns takes one at 120. Continuing to slice at the old index would skip content
+ * (`W1` breaks) or repeat it silently. So a width change prints this seam and restarts the
+ * entry at the new width: every row stays reachable, and the only cost is one bounded
+ * repetition of the rows above the seam (documented in the README).
+ */
+export declare function reflowSeamRow(printedRows: number, printedCols: number, cols: number): string;
+/** The single wording of the per-entry row cap, shared by the renderer and the pipeline. */
+export declare function elisionRow(hidden: number): string;
+/**
+ * Apply `maxRowsPerEntry` to the REMAINDER of one entry.
+ *
+ * The cap used to be a single "keep the first 399 rows, then say how many were dropped".
+ * That is still what a never-printed entry gets (`headRows === 0`), because it keeps the
+ * part of the answer the user has already scrolled past. An entry whose HEAD is already in
+ * the scrollback gets the opposite treatment on purpose: the notice goes FIRST and the LAST
+ * rows follow, because the tail is the part the reader is looking at on screen, and eliding
+ * it would delete the answer they just finished reading from their history.
+ *
+ * @param tail Rows still to print (`body.slice(fromRow)`).
+ * @param headRows Rows of this entry already printed.
+ */
+export declare function capPrintedRows(tail: readonly string[], headRows: number): readonly string[];

package/dist/ui/scrollback/overflow-print.js

@@ -0,0 +1,120 @@
+/**
+ * TOP GIVE-WAY - the row-level print plan of the native-scroll live region
+ * (tui-final-reply-truncated-unscrollable, plan A-prime / B3).
+ *
+ * THE DEFECT THIS ANSWERS. The region is the whole screen (`H = rows - 1`), so the box
+ * that holds the conversation is only `previewRows` tall (24 rows on a 30-row terminal),
+ * while the boundary that decides what may print into the terminal's scrollback is
+ * counted in ENTRIES (`liveTailMaxEntries`). A settled answer taller than the box is
+ * therefore inside the window, never printed, and clipped from the top by
+ * `justifyContent="flex-end"`. Native mode has no in-frame viewport - the wheel scrolls
+ * the terminal's scrollback - so the clipped rows exist nowhere the user can reach.
+ *
+ * The region cannot simply grow: a frame as tall as the terminal makes Ink write
+ * `clearTerminal` (which contains `ESC[3J`) and that erases the user's scrollback. So the
+ * only direction that keeps both promises is this one: the box keeps showing what it can,
+ * and the rows it hides are PRINTED into the scrollback, where the terminal's own scroll
+ * already reaches. Nothing on screen changes; the head of a long answer simply becomes
+ * readable one wheel turn up.
+ *
+ * WHAT THE PLAN GUARANTEES (the invariants the implementation batches are verified by):
+ *  I-B1 `printed(e) + visible(e) = rows(e)` and the two ranges are adjacent and disjoint,
+ *       so `scrollback + screen` covers every row exactly once (no gap, no duplicate).
+ *  I-B2 Only STABLE entries may print, and the FIRST unstable entry is a wall: nothing at
+ *       or after it is ever planned, even when a stable entry follows it (a `notice` after
+ *       a streaming answer is stable, and printing it here would put rows into the
+ *       scrollback out of conversation order, which is unrecoverable).
+ *  I-B3 The plan is ordered oldest-first and carries no gaps: the caller prints the
+ *       segments in the order given, so the scrollback keeps conversation order.
+ *  I-B4 It never plans a row that is still on screen: `hiddenRows` is measured against the
+ *       box height, and the box clips from the TOP only while it is bottom-anchored
+ *       (`tail-anchor.ts`), which the caller checks before printing anything.
+ *
+ * PURE: no Ink, no I/O, no clock, no `node:*`. That is why the caller injects the measured
+ * heights and the printed counts instead of this module measuring anything itself: the same
+ * arithmetic then drives a unit test with an arbitrary table instead of a screen.
+ */
+import { SCROLLBACK_LIMITS } from './limits.js';
+function wholeRows(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+/**
+ * Which rows of the window the box is hiding, and how many of them are not printed yet.
+ *
+ * @param window The tail window, OLDEST FIRST, excluded entries already dropped.
+ * @param budgetRows Height of the box that shows the window (`band.previewRows`).
+ * @returns The print plan; `segments` is empty when nothing is hidden or when the first
+ * unstable entry sits at the top of the window (see I-B2).
+ */
+export function planOverflowPrint(window, budgetRows) {
+    const totalRows = window.reduce((sum, item) => sum + wholeRows(item.rows), 0);
+    // Rows past the wall are on screen too (the box is one box), so they count towards the
+    // height - they are simply never printable themselves.
+    const hiddenRows = Math.max(0, totalRows - wholeRows(budgetRows));
+    if (hiddenRows === 0)
+        return { segments: [], hiddenRows, totalRows };
+    const segments = [];
+    let offset = 0;
+    for (const [index, item] of window.entries()) {
+        // I-B2 - the wall. Nothing at or after the first unstable entry may print, and because
+        // the loop walks in order, "at or after" needs nothing more than a `break`.
+        if (!item.stable)
+            break;
+        // Every row from here down is visible: the box clips exactly `hiddenRows` rows off the
+        // top, so once the accumulated offset reaches it the plan is complete.
+        if (offset >= hiddenRows)
+            break;
+        const hiddenOfEntry = Math.min(wholeRows(item.rows), hiddenRows - offset);
+        const printed = wholeRows(item.printed);
+        if (hiddenOfEntry > printed) {
+            segments.push({ index, id: item.entry.id, fromRow: printed, toRow: hiddenOfEntry });
+        }
+        offset += wholeRows(item.rows);
+    }
+    return { segments, hiddenRows, totalRows };
+}
+/**
+ * The row that marks a WIDTH CHANGE inside one entry's printed history.
+ *
+ * "Rows already printed" is a width-relative quantity: a line that took two rows at 80
+ * columns takes one at 120. Continuing to slice at the old index would skip content
+ * (`W1` breaks) or repeat it silently. So a width change prints this seam and restarts the
+ * entry at the new width: every row stays reachable, and the only cost is one bounded
+ * repetition of the rows above the seam (documented in the README).
+ */
+export function reflowSeamRow(printedRows, printedCols, cols) {
+    return `[-- reflowed to ${cols} columns; ${printedRows} row(s) above were printed at ` +
+        `${printedCols} columns --]`;
+}
+/** The single wording of the per-entry row cap, shared by the renderer and the pipeline. */
+export function elisionRow(hidden) {
+    return `[+${hidden} rows not printed - scrollback entry cap]`;
+}
+/**
+ * Apply `maxRowsPerEntry` to the REMAINDER of one entry.
+ *
+ * The cap used to be a single "keep the first 399 rows, then say how many were dropped".
+ * That is still what a never-printed entry gets (`headRows === 0`), because it keeps the
+ * part of the answer the user has already scrolled past. An entry whose HEAD is already in
+ * the scrollback gets the opposite treatment on purpose: the notice goes FIRST and the LAST
+ * rows follow, because the tail is the part the reader is looking at on screen, and eliding
+ * it would delete the answer they just finished reading from their history.
+ *
+ * @param tail Rows still to print (`body.slice(fromRow)`).
+ * @param headRows Rows of this entry already printed.
+ */
+export function capPrintedRows(tail, headRows) {
+    const cap = SCROLLBACK_LIMITS.maxRowsPerEntry;
+    const printed = wholeRows(headRows);
+    if (printed + tail.length <= cap)
+        return tail;
+    if (printed === 0) {
+        const keep = Math.max(0, cap - 1);
+        return [...tail.slice(0, keep), elisionRow(tail.length - keep)];
+    }
+    // One row is spent on the notice itself.
+    const keep = Math.max(0, cap - printed - 1);
+    if (keep === 0)
+        return [elisionRow(tail.length)];
+    return [elisionRow(tail.length - keep), ...tail.slice(tail.length - keep)];
+}

package/dist/ui/scrollback/renderer.d.ts

@@ -23,8 +23,18 @@ export interface EntryRenderOptions {
     reducedMotion: boolean;
 }
 export interface EntryRenderer {
-    /** Rows for one entry at `cols` columns; `[]` when it renders as nothing. */
+    /** Rows for one entry at `cols` columns, capped at `maxRowsPerEntry`; `[]` when it renders as nothing. */
     renderEntry(entry: Entry, prev: Entry | undefined, cols: number, expanded?: boolean): string[];
+    /**
+     * The SAME rows, UNCAPPED.
+     *
+     * "Top give-way" (`overflow-print.ts`) slices one entry across two print passes, so it
+     * needs the real row count and the real rows: `capRows` truncates before returning, and a
+     * row budget computed from a truncated array puts the cut in the wrong place (a 800-row
+     * answer would compute its cut on 400 rows and print rows the screen is still showing).
+     * The cap is applied by the caller, once, where it knows how many rows are already printed.
+     */
+    renderEntryRows(entry: Entry, prev: Entry | undefined, cols: number, expanded?: boolean): string[];
     /** Rows for an arbitrary node (the startup header and opener). */
     renderNode(node: React.ReactNode, cols: number): string[];
     /** Options for LATER renders; already printed rows never change. */