@aragon-agent/cli 0.6.29 → 0.6.32

package/dist/ui/entries/ServiceCard.js

@@ -81,8 +81,19 @@ function statusClause(props, dot) {
         const took = readyAt === undefined ? '' : `${dot}${formatDuration(readyAt - startedAt)}`;
         return `ready${took}`;
     }
-    if (status === 'running')
-        return 'running';
+    // A LIVE JOB SHOWS ITS ELAPSED TIME (D-8), because a task's whole story is
+    // "how long has this been going". The number comes from the transcript's 1 Hz
+    // `nowSec`; without it the card falls back to the spawn time and reads `0ms`,
+    // which is honest about never having been ticked rather than wrong about it.
+    if (status === 'running') {
+        // NO CLOCK, NO FIGURE. Falling back to `startedAt` would print `0ms` on every
+        // settled frame, which reads as "it just started" - a wrong number rather than
+        // an absent one.
+        if (props.nowSec === undefined)
+            return 'running';
+        const elapsed = Math.max(0, props.nowSec * 1000 - startedAt);
+        return `running${dot}${formatDuration(elapsed)}`;
+    }
     if (status === 'starting')
         return 'starting';
     const lived = endedAt === undefined ? '' : `${dot}${formatDuration(endedAt - startedAt)}`;
@@ -92,20 +103,44 @@ function statusClause(props, dot) {
         return `failed${lived}`;
     return `exited${exitCode === null ? '' : ` code ${exitCode}`}${lived}`;
 }
+/**
+ * The progress row, or `undefined` when there is nothing to draw.
+ *
+ * STALLED OUTRANKS PROGRESS: "no output for 6m" is the more urgent of the two
+ * facts, and drawing both would cost a second row the height estimator does not
+ * know about. The `no output` figure needs `nowSec`; without it the badge is
+ * omitted rather than printed with a wrong number.
+ */
+function progressRow(props) {
+    if (props.stalled === true) {
+        if (props.nowSec === undefined || props.lastOutputAt === undefined) {
+            return { text: 'no output', stalled: true };
+        }
+        const quiet = Math.max(0, props.nowSec * 1000 - props.lastOutputAt);
+        return { text: `no output ${formatDuration(quiet)}`, stalled: true };
+    }
+    if (props.progress)
+        return { text: props.progress, stalled: false };
+    return undefined;
+}
 function ServiceCardImpl(props) {
     const { serviceId, command, url, rows, expanded, terminal, theme, caps } = props;
     const glyphs = pickGlyphs(caps);
     const color = serviceCardColor(props, theme);
     const dot = `  ${glyphs.midDot}  `;
     const clause = statusClause(props, dot);
+    // THE NOUN, NOT THE KIND: `task t1` and `service s1` are the same component
+    // drawing two kinds of job, and every id keeps its existing prefix (I-2).
+    const noun = props.jobKind === 'task' ? 'task' : 'service';
     // THE TERMINAL RECORD IS ONE ROW, ALWAYS. It is a SECOND event at a SECOND
     // time — the only thing `<Static>` permits once the live card is printed — so
     // it names what happened and nothing else (D-11).
     if (terminal) {
-        return (_jsx(Box, { flexDirection: "row", children: _jsxs(Text, { color: color, wrap: "truncate", children: ["service ", serviceId, " ", clause, props.killIncomplete ? ' (may have left a detached child)' : ''] }) }));
+        return (_jsx(Box, { flexDirection: "row", children: _jsxs(Text, { color: color, wrap: "truncate", children: [noun, " ", serviceId, " ", clause, props.killIncomplete ? ' (may have left a detached child)' : ''] }) }));
     }
     const shown = rows.slice(-(expanded ? EXPANDED_TAIL_ROWS : COLLAPSED_TAIL_ROWS));
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { color: theme.accent, bold: true, children: ["service ", serviceId] }), _jsxs(Text, { color: theme.muted, wrap: "truncate", children: ['  ', command] }), _jsxs(Text, { color: color, wrap: "truncate", children: [dot, clause] })] }), url !== undefined && (_jsxs(Box, { flexDirection: "row", flexShrink: 0, paddingLeft: 1, children: [_jsx(Text, { color: theme.primary, children: url }), _jsxs(Text, { color: theme.muted, children: [dot, "ctrl+c stop", dot, "ctrl+o log"] })] })), shown.length > 0 && (_jsx(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, ...railBorderProps(glyphs.railVertical, theme.border), children: shown.map((line, index) => (_jsx(Text, { color: theme.muted, wrap: "truncate", children: line }, index))) }))] }));
+    const progress = progressRow(props);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { color: theme.accent, bold: true, children: [noun, " ", serviceId] }), _jsxs(Text, { color: theme.muted, wrap: "truncate", children: ['  ', command] }), _jsxs(Text, { color: color, wrap: "truncate", children: [dot, clause] })] }), progress !== undefined && (_jsx(Box, { flexDirection: "row", flexShrink: 0, paddingLeft: 1, children: _jsx(Text, { color: progress.stalled ? theme.noticeWarn : theme.muted, wrap: "truncate", children: progress.stalled ? progress.text : `[progress] ${progress.text}` }) })), url !== undefined && (_jsxs(Box, { flexDirection: "row", flexShrink: 0, paddingLeft: 1, children: [_jsx(Text, { color: theme.primary, children: url }), _jsxs(Text, { color: theme.muted, children: [dot, "ctrl+c stop", dot, "ctrl+o log"] })] })), shown.length > 0 && (_jsx(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, ...railBorderProps(glyphs.railVertical, theme.border), children: shown.map((line, index) => (_jsx(Text, { color: theme.muted, wrap: "truncate", children: line }, index))) }))] }));
 }
 /**
  * `React.memo` with the DEFAULT comparator (tui-render-performance L2 / R3).

package/dist/ui/frame-differ.d.ts

@@ -150,5 +150,17 @@ export interface FrameDiffer {
      * appears one frame later instead of never.
      */
     repaint(): string;
+    /**
+     * The stream was resized. Optional (tui-native-terminal-scroll §5.1): the
+     * full-screen differ does not implement it and is invalidated instead, which is
+     * its existing behaviour; the scrollback writer keeps its cache for a reflow
+     * estimate.
+     */
+    onResize?(): void;
+    /**
+     * An own write that moves neither a cell nor the cursor (OSC 52 copy). Optional
+     * for the same reason: absent, the write invalidates the cache as before.
+     */
+    cursorNeutralWrite?(): void;
 }
 export declare function createFrameDiffer(options: FrameDifferOptions): FrameDiffer;

package/dist/ui/layout/status-layout.d.ts

@@ -15,6 +15,18 @@ export interface StatusLayoutInput {
         name: string;
         toolCallId: string;
     } | null;
+    /**
+     * A bounded wait in flight (long-task-jobs §4.9).
+     *
+     * PRESENT ONLY WHILE `job_wait` IS THE ACTIVE TOOL, and it REPLACES the
+     * `Running job_wait` label rather than joining it: "Waiting on t3 (up to 30s)"
+     * is the state the user asked about (what, and how long at most), while the
+     * tool name is an implementation detail of how the runtime is waiting.
+     */
+    wait?: {
+        jobId: string;
+        upToSeconds: number;
+    };
     runOutcome?: 'none' | 'ended' | 'interrupted' | 'failed';
     spinner?: string;
     waitingForConfirmation?: boolean;
@@ -77,7 +89,7 @@ export interface StatusLinePlan {
 export declare function cleanStatusText(text: string): string;
 export declare function statusField(id: string, text: string, tone?: StatusField['tone']): StatusField;
 export declare function statusLinePlan(fields: readonly StatusField[], separator?: string): StatusLinePlan;
-export declare function phaseLabels(input: Pick<StatusLayoutInput, 'phase' | 'activeTool' | 'runOutcome' | 'waitingForConfirmation' | 'stopping' | 'compacting' | 'retryActive'>): readonly [string, string];
+export declare function phaseLabels(input: Pick<StatusLayoutInput, 'phase' | 'activeTool' | 'runOutcome' | 'waitingForConfirmation' | 'stopping' | 'compacting' | 'retryActive' | 'wait'>): readonly [string, string];
 export declare function validContext(context: ContextUsageSnapshot): boolean;
 export declare function shortDuration(ms: number): string;
 /** Every field survives each width rung; only the redraw carrier is outside this plan. */

package/dist/ui/layout/status-layout.js

@@ -25,6 +25,16 @@ export function phaseLabels(input) {
         return copy.compacting;
     if (input.retryActive)
         return copy.retrying;
+    // A WAIT OUTRANKS THE TOOL NAME (long-task-jobs AC-28): `Running job_wait`
+    // answers "which tool", `Waiting on t3 (up to 30s)` answers "what am I waiting
+    // for and how long may it take", which is the question a user staring at a
+    // quiet terminal actually has. Both forms carry it - the short rung is
+    // truncated by width, not reworded.
+    if (input.wait) {
+        const label = `Waiting on ${cleanStatusText(input.wait.jobId)} ` +
+            `(up to ${Math.max(0, Math.round(input.wait.upToSeconds))}s)`;
+        return [label, label];
+    }
     if (input.activeTool)
         return [copy.tool[0], copy.tool[1] + ' ' + cleanStatusText(input.activeTool.name)];
     if (input.phase === 'idle' && input.runOutcome && input.runOutcome !== 'none')

package/dist/ui/layout/virtual-window.js

@@ -218,6 +218,13 @@ const TOOL_LIVE_TAIL_ROWS = 8;
 const SERVICE_COLLAPSED_TAIL_ROWS = 2;
 /** Tail rows an EXPANDED `ServiceCard` draws; the snapshot cap (8). */
 const SERVICE_EXPANDED_TAIL_ROWS = 8;
+/**
+ * The progress row the live `ServiceCard` draws when `progress` or `stalled` is
+ * set (long-task-jobs §4.9), duplicated as the number `1` for the same reason as
+ * the two constants above: `virtual-window.ts` counts lines, `ServiceCard.tsx`
+ * draws them, and the pairing is kept by a test (AC-27) rather than by an import.
+ */
+const SERVICE_PROGRESS_ROWS = 1;
 /**
  * Pure UPPER-BOUND estimate of an entry's height, used until a real measurement
  * exists.
@@ -358,7 +365,13 @@ export function estimateEntryRows(entry, cols, density, expanded, thinkingVisibl
             const tail = expanded
                 ? Math.min(entry.rows.length, SERVICE_EXPANDED_TAIL_ROWS)
                 : Math.min(entry.rows.length, SERVICE_COLLAPSED_TAIL_ROWS);
-            return separation + 1 + url + tail;
+            // THE PROGRESS ROW IS ONE MORE LINE (long-task-jobs AC-27), and it is only
+            // ever one because `ServiceCard` draws it with `wrap="truncate"` and the
+            // supervisor clips it to `PROC_LIMITS.waitProgressChars`. A `stalled` badge
+            // REPLACES it rather than adding to it - the two can never both be drawn,
+            // so this stays a single term.
+            const progress = entry.progress || entry.stalled ? SERVICE_PROGRESS_ROWS : 0;
+            return separation + 1 + progress + url + tail;
         }
         default:
             return separation + 1;

package/dist/ui/overlays/HelpOverlay.d.ts

@@ -14,4 +14,4 @@ import React from 'react';
 import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
 /** Build the overlay's rows. Exported so `app.test.tsx` can count them. */
-export declare function helpRows(theme: Theme, caps: TermCapabilities): React.ReactElement[];
+export declare function helpRows(theme: Theme, caps: TermCapabilities, native?: boolean): React.ReactElement[];

package/dist/ui/overlays/HelpOverlay.js

@@ -2,7 +2,25 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Text } from 'ink';
 import { pickGlyphs } from '../glyphs.js';
 const KEY_PAD = 24;
-function keyRows(times) {
+/**
+ * Rows that only make sense when the APPLICATION scrolls and selects. In native
+ * scroll mode (tui-native-terminal-scroll §4.7) the terminal does both, so they are
+ * dropped and one honest row replaces them.
+ */
+const APP_SCROLL_ROWS = new Set([
+    'Shift+Up / Shift+Down', 'Wheel', 'Shift+Wheel', 'Drag right edge', '^N',
+    'Drag text (left button)', 'Ctrl+C (with a selection)',
+]);
+function keyRows(times, native = false) {
+    const all = allKeyRows(times);
+    if (!native)
+        return all;
+    return all
+        .filter(([key]) => !APP_SCROLL_ROWS.has(key))
+        .map(([key, description]) => key === 'PgUp / PgDn' ? [key, 'Page through an open overlay'] : [key, description])
+        .concat([['Scroll', 'Use your terminal (wheel, Shift+PgUp, scrollbar, search)']]);
+}
+function allKeyRows(times) {
     return [
         ['Enter', 'Submit (idle) / queue steering (running); re-pins to the newest output'],
         ['Alt+Enter / Shift+Enter', 'Newline when supported; the host may intercept either binding'],
@@ -133,13 +151,13 @@ const FAST_ROWS = [
     ['<fast_review>', 'An automated second opinion from the fast model - advice, not the user'],
 ];
 /** Build the overlay's rows. Exported so `app.test.tsx` can count them. */
-export function helpRows(theme, caps) {
+export function helpRows(theme, caps, native = false) {
     const glyphs = pickGlyphs(caps);
     const rows = [];
     const section = (title) => (_jsx(Text, { wrap: "truncate", color: theme.accent, bold: true, children: title }, `s-${title}`));
     const pair = (k, d) => (_jsxs(Text, { wrap: "truncate", children: [_jsx(Text, { color: theme.primary, children: k.padEnd(KEY_PAD) }), _jsx(Text, { color: theme.muted, children: d })] }, `r-${k}`));
     rows.push(section('Keybindings'));
-    for (const [k, d] of keyRows(glyphs.times))
+    for (const [k, d] of keyRows(glyphs.times, native))
         rows.push(pair(k, d));
     rows.push(section('Slash commands'));
     for (const [c, d] of COMMANDS)

package/dist/ui/run-status-row.d.ts

@@ -17,6 +17,18 @@ export interface RunActivity {
     runningTool?: string;
     /** A context compaction is in flight; outranks the tool name and the phrase. */
     compacting?: boolean;
+    /**
+     * A BOUNDED WAIT IS IN FLIGHT (long-task-jobs §4.9).
+     *
+     * `Running job_wait` is a TOOL NAME; `Waiting on t3 (up to 30s)` is a STATE, and
+     * the state is what answers the user's two questions - what is it waiting for,
+     * and how long may that take. No countdown: a ticking number would need its own
+     * re-render, and the sentence is already complete.
+     */
+    wait?: {
+        jobId: string;
+        upToSeconds: number;
+    };
 }
 export interface RunRowPlanInput {
     /** Width of the row's container (the composer's content columns). */

package/dist/ui/screen.d.ts

@@ -71,6 +71,35 @@ export interface AltScreenOptions {
  * CI) — writing screen-control sequences into a redirected file corrupts it.
  */
 export declare function enterAltScreen(stdout: NodeJS.WriteStream | undefined, options?: AltScreenOptions): ScreenHandle;
+export interface NativeScreenOptions {
+    /** Same discipline as `AltScreenOptions.bracketedPaste`: a filter that consumes it exists. */
+    readonly bracketedPaste?: boolean;
+    /**
+     * Line feeds to write BEFORE anything else, so the first batch starts from the
+     * bottom row of the screen (tui-bottom-anchored-live-region D4 rung 2).
+     *
+     * `cli.tsx` passes `rows - 1` when the cursor probe could not measure the
+     * position, and `0` when it did. Filling on a measured terminal would undo the
+     * measurement — and cost the page-flip this feature exists to avoid.
+     */
+    readonly anchorFillRows?: number;
+}
+/**
+ * Native-scroll mode's counterpart of `enterAltScreen` (tui-native-terminal-scroll
+ * §4.8 / D6): it deliberately does almost nothing. The main buffer stays in use so
+ * the conversation lands in the terminal's own scrollback; there is no alternate
+ * screen, no mouse reporting and no DEC 1007 save/restore.
+ *
+ * The only modes it touches are DEC 2004 (bracketed paste), which changes how input
+ * is encoded and has nothing to do with scrolling, and — when the bottom anchor could
+ * not be measured — the one-off fill that puts the cursor on the last row. Returns the
+ * SAME `ScreenHandle` shape, so the four idempotent restore paths in `cli.tsx` need not
+ * know which mode is running. A non-TTY stdout is a hard no-op, like `enterAltScreen`.
+ *
+ * ORDER IS LOAD-BEARING: the fill goes FIRST. Written after `?2004h` it would be the
+ * same bytes, but written after any content it would scroll that content away.
+ */
+export declare function enterNativeScreen(stdout: NodeJS.WriteStream | undefined, options?: NativeScreenOptions): ScreenHandle;
 /**
  * Replay the session summary into the normal buffer after `restore()`, so the
  * conversation does not evaporate along with the alternate screen.

package/dist/ui/screen.js

@@ -11,6 +11,7 @@
  * Hoisting it into `buildProgram()` / `parseAsync` would push `\x1b[?1049h`
  * into `aragon -p "…" > out.txt`, `aragon config set`, and `aragon --version`.
  */
+import { fillBytes } from './scrollback/writer-shapes.js';
 const ENTER_ALT = '\x1b[?1049h';
 const LEAVE_ALT = '\x1b[?1049l';
 const CURSOR_HOME = '\x1b[H';
@@ -181,6 +182,45 @@ export function enterAltScreen(stdout, options = { mouse: false }) {
         setMouseCapture,
     };
 }
+/**
+ * Native-scroll mode's counterpart of `enterAltScreen` (tui-native-terminal-scroll
+ * §4.8 / D6): it deliberately does almost nothing. The main buffer stays in use so
+ * the conversation lands in the terminal's own scrollback; there is no alternate
+ * screen, no mouse reporting and no DEC 1007 save/restore.
+ *
+ * The only modes it touches are DEC 2004 (bracketed paste), which changes how input
+ * is encoded and has nothing to do with scrolling, and — when the bottom anchor could
+ * not be measured — the one-off fill that puts the cursor on the last row. Returns the
+ * SAME `ScreenHandle` shape, so the four idempotent restore paths in `cli.tsx` need not
+ * know which mode is running. A non-TTY stdout is a hard no-op, like `enterAltScreen`.
+ *
+ * ORDER IS LOAD-BEARING: the fill goes FIRST. Written after `?2004h` it would be the
+ * same bytes, but written after any content it would scroll that content away.
+ */
+export function enterNativeScreen(stdout, options = {}) {
+    if (!stdout || !stdout.isTTY || typeof stdout.write !== 'function')
+        return NOOP_HANDLE;
+    const bracketedPaste = options.bracketedPaste === true;
+    const fillRows = Math.max(0, Math.floor(options.anchorFillRows ?? 0));
+    const head = (fillRows > 0 ? fillBytes(fillRows) : '') +
+        (bracketedPaste ? ENABLE_BRACKETED_PASTE : '');
+    if (head.length > 0)
+        safeWrite(stdout, head);
+    let restored = false;
+    return {
+        restore() {
+            if (restored)
+                return;
+            restored = true;
+            // 2004 is FORCED off rather than saved/restored, for the reason recorded at
+            // `DISABLE_BRACKETED_PASTE`. The cursor is shown again because Ink's
+            // log-update hides it and a signal kill never gives it back.
+            safeWrite(stdout, (bracketedPaste ? DISABLE_BRACKETED_PASTE : '') + SHOW_CURSOR);
+        },
+        // No mouse reporting in this mode: nothing to hand back or take again.
+        setMouseCapture() { },
+    };
+}
 /**
  * Replay the session summary into the normal buffer after `restore()`, so the
  * conversation does not evaporate along with the alternate screen.

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

@@ -0,0 +1,64 @@
+/**
+ * LiveTail - the band's UNFINISHED tail, rendered with the real entry components
+ * (release-gate-and-native-panels §6.5).
+ *
+ * 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
+ * it, which is why the region's content type changed from `readonly string[]` to a
+ * fixed-height box that can hold components.
+ *
+ * IT RENDERS `EntryView` AND NOTHING ELSE. The mapping from an entry to its component
+ * (`assistant` / `tool` / `team` / `todo` / service cards, notice frames, the `null`
+ * cases) lives in `Transcript.tsx` exactly once, together with `EntryFrame`'s gutter,
+ * the separation rows, the per-entry `nowSecFor` clock and the memo comparator. A
+ * second enumeration here would be a copy that drifts: the band's cards would lose the
+ * 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.
+ *
+ * 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
+ * tail; growing it makes the cost grow linearly because this box has no windowing.
+ */
+import React from 'react';
+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';
+export interface LiveTailProps {
+    /** `entries.slice(settledCount).filter(isExcluded === false)`: the same input as `buildLivePreview`. */
+    unsettled: readonly Entry[];
+    /** Render only the last N entries; the box clips the older ones from the top. */
+    maxEntries: number;
+    /** Fixed height: the root box's `height`. The content never decides it (I-4). */
+    rows: number;
+    /** `budget.previewCols` - the width left after the rail took its column (I-5). */
+    cols: number;
+    expandedToolIds: Record<string, true>;
+    thinkingVisible: boolean;
+    reducedMotion: boolean;
+    density: DensityMode;
+    nowSec?: number;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export interface TailEntry {
+    entry: Entry;
+    /** The entry before it in the FULL list: `EntryView` uses it to decide the separator. */
+    prev: Entry | undefined;
+}
+/**
+ * The last `maxEntries` entries, each with its predecessor.
+ *
+ * `prev` must come from the COMPLETE unsettled list rather than from the truncated
+ * slice, or the first rendered entry would look like the head of the conversation and
+ * drop the separation row the transcript shows above the same card.
+ */
+export declare function selectTailEntries(unsettled: readonly Entry[], maxEntries: number): readonly TailEntry[];
+export declare function LiveTail({ unsettled, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, }: LiveTailProps): React.ReactElement;

package/dist/ui/scrollback/LiveTail.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from 'ink';
+import { EntryView, nowSecFor } from '../Transcript.js';
+import { SCROLLBACK_LIMITS } from './limits.js';
+/**
+ * The last `maxEntries` entries, each with its predecessor.
+ *
+ * `prev` must come from the COMPLETE unsettled list rather than from the truncated
+ * slice, or the first rendered entry would look like the head of the conversation and
+ * drop the separation row the transcript shows above the same card.
+ */
+export function selectTailEntries(unsettled, maxEntries) {
+    const limit = Number.isFinite(maxEntries) ? Math.max(0, Math.floor(maxEntries)) : 0;
+    if (limit === 0)
+        return [];
+    const start = Math.max(0, unsettled.length - limit);
+    const selected = [];
+    for (let index = start; index < unsettled.length; index += 1) {
+        selected.push({ entry: unsettled[index], prev: index > 0 ? unsettled[index - 1] : undefined });
+    }
+    return selected;
+}
+export function LiveTail({ unsettled, maxEntries, rows, cols, expandedToolIds, thinkingVisible, reducedMotion, density, nowSec, theme, caps, }) {
+    const limited = Math.min(maxEntries, SCROLLBACK_LIMITS.liveTailMaxEntries);
+    const selected = selectTailEntries(unsettled, 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))) }));
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Height and column budget of the native-scroll PANEL BAND
+ * (release-gate-and-native-panels §6.2).
+ *
+ * Native scroll mode drops the fixed frame, so it used to drop the panels with it:
+ * the TODO rail lived in `AppShell`'s middle band and the subagent roster in the
+ * viewport footer, and neither is rendered once `ScrollbackShell` takes over. The
+ * band is the replacement - one row pool shared by the roster (`TeamPanel`), the
+ * streaming tail and the rail (`TodoPanel`), sitting directly above the composer.
+ *
+ * PURE: no Ink, no clock, no terminal, no config read. Every invariant below is
+ * therefore established BY CONSTRUCTION for all input combinations and can be
+ * enumerated by a property test (AC-9..AC-14, AC-31):
+ *
+ *  - `bandRows <= remaining` and therefore `liveRows <= rows - 1` (I-4). Ink writes
+ *    `clearTerminal` - which contains `ESC[3J`, erasing the user's scrollback - as
+ *    soon as a frame is as tall as the terminal; that one row is the difference
+ *    between a tidy region and data loss.
+ *  - `previewCols + railCols === contentCols`, always (AC-10). The rail is a column
+ *    INSIDE the region, so the preview loses exactly the columns the rail takes and
+ *    nothing else (I-5: printing keeps the full `contentCols`).
+ *  - `teamRows > 0` leaves room for the rail plus one preview row (AC-12).
+ *  - `previewRows <= previewCap`, so the structural caps
+ *    `maxLiveTailRows` / `liveTailRowShare` keep binding (I-10).
+ *
+ * THERE IS EXACTLY ONE CALL SITE: `buildScrollbackBudget` (I-8). This module is
+ * exported so it can be tested, not so a second caller can allocate rows of its own
+ * - `remaining` is computed there, and a second copy of it is a second authority.
+ */
+export type BandReason = 
+/** Both panels are on screen. */
+'visible'
+/** No active plan: no rail. Same name and meaning as `TodoRailLayout`'s `'empty'`. */
+ | 'empty'
+/** `cfg.todo.panel === false`. */
+ | 'disabled'
+/** An overlay is open: the band yields to it. */
+ | 'overlay'
+/** `todoRailWidth(contentCols) === 0` (terminal narrower than 76 columns). */
+ | 'narrow'
+/** The remaining rows cannot hold `panelMinRows` for the rail. */
+ | 'short';
+export interface LiveBandInput {
+    /**
+     * `buildFrameBudget().viewportRows + headerRows`: every row the band may use.
+     * Computed once by `buildScrollbackBudget`; callers must not re-derive it.
+     */
+    remaining: number;
+    /** `cols - 1`: width of the whole band. `previewCols` is derived from it. */
+    contentCols: number;
+    /** `todoRailWidth(contentCols)`; `layout/rail.ts` stays the width authority. */
+    railCols: number;
+    /** The existing two caps combined: `min(maxLiveTailRows, floor(rows * share))`. */
+    previewCap: number;
+    /** Plain-text rows `buildLivePreview` wants (the measuring authority is unchanged). */
+    previewWanted: number;
+    /** `state.todos.items.length` (0 = no active plan). */
+    itemCount: number;
+    /** `cfg.todo.panel`. */
+    panelEnabled: boolean;
+    overlayOpen: boolean;
+    /** `buildTeamPanelLayout().rowCount`; 0 when there is nothing to show. */
+    teamRowsNatural: number;
+    /** Hysteresis: the rail rows the previous frame already used. */
+    heldRailRows: number;
+    /** Hysteresis: the roster rows the previous frame already used. */
+    heldTeamRows: number;
+}
+export interface LiveBand {
+    reason: BandReason;
+    /** Band height: `teamRows + previewRows`, or `remaining` for an overlay. */
+    bandRows: number;
+    teamRows: number;
+    previewRows: number;
+    /** Row budget of the rail: the whole band (the rail spans it). 0 when hidden. */
+    railRows: number;
+    /** The input `railCols` when visible, 0 when hidden (`/perf` reads `rail=0x0`). */
+    railCols: number;
+    /** `max(0, contentCols - railCols)`; always sums with `railCols` to `contentCols`. */
+    previewCols: number;
+    /** Hysteresis output, fed back on the next frame. */
+    heldRailRows: number;
+    heldTeamRows: number;
+}
+/**
+ * Allocate the band. THE ORDER OF THE STEPS IS THE SPECIFICATION - reordering them
+ * changes the priority between "what this run is doing" (rail + roster) and "the
+ * words arriving right now" (preview), which is a product decision, not a detail.
+ *
+ * 0. Normalise every numeric input (`NaN` / `Infinity` / negatives become 0).
+ * 1. An open overlay takes the whole pool (the band would otherwise double-count it).
+ * 2. Seat the roster first, but never at the cost of the rail plus one preview row:
+ *    a dispatch is transient, the plan is the shape of the turn, both must fit.
+ * 3. Decide the rail's visibility, in the same reason order as `buildTodoRailLayout`.
+ * 4. RESERVE the rail's rows (`panelFullRows` floor - the 3-5 row compact form cannot
+ *    show which item is running, and the band reaches 6 rows far more often than the
+ *    full-screen rail does). A reservation, not the final value: see step 6.
+ * 5. The preview takes what is left, clamped by `previewCap`.
+ * 6. `bandRows = max(railReserved, teamRows + previewRows)`: with no unsettled
+ *    content `previewRows` is 0, yet the rail must still be there (the user is
+ *    reading a result and still needs the list).
+ * 7. Columns: the input `contentCols` is the only width authority.
+ * 8. Hand the late-arriving values (the hysteresis) back out for the next frame.
+ */
+export declare function buildLiveBand(input: LiveBandInput): LiveBand;

package/dist/ui/scrollback/band.js

@@ -0,0 +1,109 @@
+/**
+ * Height and column budget of the native-scroll PANEL BAND
+ * (release-gate-and-native-panels §6.2).
+ *
+ * Native scroll mode drops the fixed frame, so it used to drop the panels with it:
+ * the TODO rail lived in `AppShell`'s middle band and the subagent roster in the
+ * viewport footer, and neither is rendered once `ScrollbackShell` takes over. The
+ * band is the replacement - one row pool shared by the roster (`TeamPanel`), the
+ * streaming tail and the rail (`TodoPanel`), sitting directly above the composer.
+ *
+ * PURE: no Ink, no clock, no terminal, no config read. Every invariant below is
+ * therefore established BY CONSTRUCTION for all input combinations and can be
+ * enumerated by a property test (AC-9..AC-14, AC-31):
+ *
+ *  - `bandRows <= remaining` and therefore `liveRows <= rows - 1` (I-4). Ink writes
+ *    `clearTerminal` - which contains `ESC[3J`, erasing the user's scrollback - as
+ *    soon as a frame is as tall as the terminal; that one row is the difference
+ *    between a tidy region and data loss.
+ *  - `previewCols + railCols === contentCols`, always (AC-10). The rail is a column
+ *    INSIDE the region, so the preview loses exactly the columns the rail takes and
+ *    nothing else (I-5: printing keeps the full `contentCols`).
+ *  - `teamRows > 0` leaves room for the rail plus one preview row (AC-12).
+ *  - `previewRows <= previewCap`, so the structural caps
+ *    `maxLiveTailRows` / `liveTailRowShare` keep binding (I-10).
+ *
+ * THERE IS EXACTLY ONE CALL SITE: `buildScrollbackBudget` (I-8). This module is
+ * exported so it can be tested, not so a second caller can allocate rows of its own
+ * - `remaining` is computed there, and a second copy of it is a second authority.
+ */
+import { TODO_LIMITS } from '../../todo/limits.js';
+import { SCROLLBACK_LIMITS } from './limits.js';
+/** Invalid geometry becomes zero, exactly like `layout/team-panel.ts::nonNegativeInt`. */
+function nonNegativeInt(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+/**
+ * Allocate the band. THE ORDER OF THE STEPS IS THE SPECIFICATION - reordering them
+ * changes the priority between "what this run is doing" (rail + roster) and "the
+ * words arriving right now" (preview), which is a product decision, not a detail.
+ *
+ * 0. Normalise every numeric input (`NaN` / `Infinity` / negatives become 0).
+ * 1. An open overlay takes the whole pool (the band would otherwise double-count it).
+ * 2. Seat the roster first, but never at the cost of the rail plus one preview row:
+ *    a dispatch is transient, the plan is the shape of the turn, both must fit.
+ * 3. Decide the rail's visibility, in the same reason order as `buildTodoRailLayout`.
+ * 4. RESERVE the rail's rows (`panelFullRows` floor - the 3-5 row compact form cannot
+ *    show which item is running, and the band reaches 6 rows far more often than the
+ *    full-screen rail does). A reservation, not the final value: see step 6.
+ * 5. The preview takes what is left, clamped by `previewCap`.
+ * 6. `bandRows = max(railReserved, teamRows + previewRows)`: with no unsettled
+ *    content `previewRows` is 0, yet the rail must still be there (the user is
+ *    reading a result and still needs the list).
+ * 7. Columns: the input `contentCols` is the only width authority.
+ * 8. Hand the late-arriving values (the hysteresis) back out for the next frame.
+ */
+export function buildLiveBand(input) {
+    const remaining = nonNegativeInt(input.remaining);
+    const contentCols = nonNegativeInt(input.contentCols);
+    const railCols = nonNegativeInt(input.railCols);
+    const previewCap = nonNegativeInt(input.previewCap);
+    const previewWanted = nonNegativeInt(input.previewWanted);
+    const itemCount = nonNegativeInt(input.itemCount);
+    const teamRowsNatural = nonNegativeInt(input.teamRowsNatural);
+    const heldRailRows = nonNegativeInt(input.heldRailRows);
+    const heldTeamRows = nonNegativeInt(input.heldTeamRows);
+    if (input.overlayOpen) {
+        return {
+            reason: 'overlay', bandRows: remaining, teamRows: 0, previewRows: 0,
+            railRows: 0, railCols: 0, previewCols: contentCols, heldRailRows: 0, heldTeamRows: 0,
+        };
+    }
+    const teamCeiling = Math.min(teamRowsNatural, Math.max(0, remaining - TODO_LIMITS.panelMinRows - 1));
+    // THE ROSTER IS SEATED AT ITS NATURAL (CLAMPED) HEIGHT, NOT AT THE REMEMBERED ONE.
+    // Seeding from `heldTeamRows` deadlocks the panel: a fresh dispatch starts with no
+    // memory, so frame one would seat zero rows, remember zero, and no later frame could
+    // ever seat the roster - the panel this feature exists to restore would never appear
+    // (found while implementing; recorded as IF-1 in the spec). The memory below only
+    // ever ADDS height back after a squeeze; it never withholds it.
+    const teamRows = teamCeiling;
+    const reason = !input.panelEnabled ? 'disabled'
+        : itemCount === 0 ? 'empty'
+            : railCols === 0 ? 'narrow'
+                : remaining - teamRows < SCROLLBACK_LIMITS.railBandMinRows ? 'short'
+                    : 'visible';
+    const railVisible = reason === 'visible';
+    const railReserved = railVisible
+        ? Math.min(Math.max(heldRailRows, TODO_LIMITS.panelFullRows), Math.max(0, remaining - teamRows - 1))
+        : 0;
+    const previewRows = Math.min(previewWanted, previewCap, Math.max(0, remaining - teamRows - railReserved));
+    const bandRows = Math.max(railReserved, teamRows + previewRows);
+    const railRows = railVisible ? bandRows : 0;
+    const railColsOut = railVisible ? railCols : 0;
+    return {
+        reason,
+        bandRows,
+        teamRows,
+        previewRows,
+        railRows,
+        railCols: railColsOut,
+        previewCols: Math.max(0, contentCols - railColsOut),
+        // MONOTONE MEMORY, NOT A SHRINKING ONE (I-6). A rail that collapsed to zero rows
+        // because the terminal shrank for two frames would otherwise come back four rows
+        // shorter and the band would visibly jump on every resize wobble. The RESET points
+        // (an emptied plan, a finished dispatch, a resize) live in the one place that owns
+        // the lifecycle, `use-scrollback-view.ts`; this function only remembers.
+        heldRailRows: Math.max(heldRailRows, railRows),
+        heldTeamRows: Math.max(heldTeamRows, teamRows),
+    };
+}