@aragon-agent/cli 0.6.29 → 0.6.31

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

@@ -0,0 +1,263 @@
+/**
+ * `useScrollbackView` — the promotion pipeline of native-scroll mode
+ * (tui-native-terminal-scroll §4.4 / §6.2).
+ *
+ * `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).
+ *
+ * What it does when enabled:
+ *  1. Prints the session header (and the opener for an empty session) once.
+ *  2. On every entries change, promotes each newly SETTLED entry: renders it once
+ *     through the offscreen renderer and enqueues the rows for the writer.
+ *  3. Computes the live-region budget and the streaming preview rows for the shell.
+ *
+ * THE PROMOTION RUNS IN A MICROTASK, NOT IN THE EFFECT. The offscreen renderer is a
+ * second Ink instance, and both instances share one React reconciler. A `rerender`
+ * issued from inside the main tree's commit (a layout effect) is deferred until that
+ * commit finishes, so its frame would not exist when the effect reads it. A
+ * microtask runs after the commit has unwound, where the offscreen render is
+ * synchronous again. Everything the pass needs is read from refs for that reason.
+ *
+ * `printedIds` is the ONLY authority on "already printed" (RV-7). The cursor is just
+ * a hint for where to resume scanning: entries leave the list by retain-ring
+ * trimming AND by reducer deletion (empty settled assistants, abandoned tool
+ * cards), so an id-keyed cursor can dangle, and then the only correct answer is to
+ * rescan and let `printedIds` skip.
+ */
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import { buildScrollbackBudget } from './budget.js';
+import { buildLivePreview } from './live-preview.js';
+import { SCROLLBACK_LIMITS } from './limits.js';
+import { createEntryRenderer } from './renderer.js';
+import { isExcluded, settleAllEntries, settledCount } from './settled-boundary.js';
+export function createScrollbackBridge(parts) {
+    return {
+        writer: parts.writer,
+        drain: parts.drain,
+        requestFlush: parts.requestFlush ?? (() => undefined),
+        settleAllNow: () => undefined,
+        getSummaryRows: () => [],
+        onGuardTrip: null,
+    };
+}
+const CLEARED_ROW = '---- conversation cleared ----';
+const RESTORED_ROW = '---- session restored ----';
+function printableBefore(entries, index) {
+    for (let i = index - 1; i >= 0; i -= 1) {
+        if (!isExcluded(entries[i]))
+            return entries[i];
+    }
+    return undefined;
+}
+/**
+ * Ids leave `entries` by retain-ring trimming and never come back (ids are unique
+ * per session), so `printedIds` is trimmed to the live list once it grows well past
+ * it. Only ids still present can be re-evaluated, so dropping the rest is lossless.
+ */
+function pruneEntryIds(printed, entries) {
+    if (printed.size <= Math.max(2000, entries.length * 3))
+        return;
+    const live = new Set(entries.map((entry) => entry.id));
+    for (const id of printed)
+        if (!live.has(id))
+            printed.delete(id);
+}
+export function useScrollbackView(args) {
+    const { enabled, bridge, entries, runActive, theme, caps, density, thinkingVisible, reducedMotion, rows, cols, headerNode, openerNode, overlayOpen, draftRows, popupRows, statusExpanded, forceInactive = false, } = args;
+    const contentCols = Math.max(1, cols - 1);
+    const startedRef = useRef(false);
+    // Everything the asynchronous pass reads travels here, refreshed on every render.
+    const latest = useRef({
+        entries, runActive, contentCols, headerNode, openerNode,
+        options: { theme, caps, density, thinkingVisible, reducedMotion },
+    });
+    latest.current = {
+        entries, runActive, contentCols,
+        // The banner nodes only matter until the banner is printed; afterwards keep the
+        // old references so a changing element identity is not mistaken for new input.
+        headerNode: startedRef.current ? latest.current.headerNode : headerNode,
+        openerNode: startedRef.current ? latest.current.openerNode : openerNode,
+        options: { theme, caps, density, thinkingVisible, reducedMotion },
+    };
+    const rendererRef = useRef(null);
+    const printedIds = useRef(new Set());
+    /** A resume hint only (RV-7): the id of the last entry the previous pass covered. */
+    const cursorRef = useRef(null);
+    const pendingReset = useRef(null);
+    const heldTailRows = useRef(0);
+    const pumpQueued = useRef(false);
+    const mountedRef = useRef(true);
+    const ensureRenderer = useCallback(() => {
+        if (!rendererRef.current)
+            rendererRef.current = createEntryRenderer(latest.current.options);
+        rendererRef.current.setOptions(latest.current.options);
+        return rendererRef.current;
+    }, []);
+    const enqueue = useCallback((rowsToPrint, id, kind) => {
+        if (rowsToPrint.length === 0 || !bridge)
+            return;
+        bridge.drain.enqueue(rowsToPrint, { id, kind });
+    }, [bridge]);
+    /** Promote `list[start..end)`; returns true when it stopped early because the feed is full. */
+    const promote = useCallback((list, end, limit) => {
+        const renderer = ensureRenderer();
+        let start = 0;
+        const cursor = cursorRef.current;
+        if (cursor && list[cursor.index]?.id === cursor.id)
+            start = cursor.index + 1;
+        let promoted = 0;
+        let lastIndex = start - 1;
+        const remember = () => {
+            cursorRef.current = lastIndex >= 0 ? { id: list[lastIndex].id, index: lastIndex } : null;
+        };
+        for (let i = start; i < end; i += 1) {
+            const entry = list[i];
+            if (isExcluded(entry) || printedIds.current.has(entry.id)) {
+                lastIndex = i;
+                continue;
+            }
+            if (promoted >= limit) {
+                remember();
+                return true;
+            }
+            const rowsToPrint = renderer.renderEntry(entry, printableBefore(list, i), latest.current.contentCols);
+            enqueue(rowsToPrint, entry.id, entry.kind);
+            // A rendered-to-nothing entry is registered too, or it would be retried forever.
+            printedIds.current.add(entry.id);
+            promoted += 1;
+            lastIndex = i;
+        }
+        remember();
+        return false;
+    }, [ensureRenderer, enqueue]);
+    const printBanner = useCallback(() => {
+        if (startedRef.current)
+            return;
+        startedRef.current = true;
+        const renderer = ensureRenderer();
+        const { headerNode: header, openerNode: opener, contentCols: width } = latest.current;
+        enqueue(renderer.renderNode(header, width), 'startup:header', 'header');
+        if (opener)
+            enqueue(renderer.renderNode(opener, width), 'startup:opener', 'opener');
+    }, [ensureRenderer, enqueue]);
+    const applyPendingReset = useCallback(() => {
+        const reset = pendingReset.current;
+        if (!reset || latest.current.entries === reset.captured)
+            return;
+        pendingReset.current = null;
+        printedIds.current = new Set();
+        cursorRef.current = null;
+        enqueue([reset.kind === 'clear' ? CLEARED_ROW : RESTORED_ROW], `reset:${Date.now()}`, 'notice');
+    }, [enqueue]);
+    const pumpRef = useRef(() => undefined);
+    const schedulePump = useCallback(() => {
+        if (pumpQueued.current)
+            return;
+        pumpQueued.current = true;
+        queueMicrotask(() => pumpRef.current());
+    }, []);
+    /** The promotion pass. Runs in a microtask (see the file header). */
+    pumpRef.current = () => {
+        pumpQueued.current = false;
+        if (!mountedRef.current || !bridge)
+            return;
+        printBanner();
+        applyPendingReset();
+        const { entries: list, runActive: active } = latest.current;
+        const limit = Math.max(1, SCROLLBACK_LIMITS.feedCapacity - bridge.drain.pendingEntries() - 1);
+        const more = promote(list, settledCount(list, active), limit);
+        pruneEntryIds(printedIds.current, list);
+        if (more) {
+            // Continue once the writer has consumed what is queued (a restored transcript
+            // longer than the feed is promoted in waves rather than folded into a marker).
+            bridge.drain.onDrained = () => {
+                bridge.drain.onDrained = null;
+                schedulePump();
+            };
+            bridge.requestFlush();
+        }
+    };
+    useLayoutEffect(() => {
+        if (enabled && bridge)
+            schedulePump();
+    }, [enabled, bridge, entries, runActive, schedulePump]);
+    const settleAll = useCallback(() => {
+        if (!bridge)
+            return;
+        const list = latest.current.entries;
+        const renderer = ensureRenderer();
+        printBanner();
+        // Shutdown must not leave anything behind, so no per-pass limit.
+        for (const entry of settleAllEntries(list)) {
+            if (printedIds.current.has(entry.id))
+                continue;
+            enqueue(renderer.renderEntry(entry, printableBefore(list, list.indexOf(entry)), latest.current.contentCols), entry.id, entry.kind);
+            printedIds.current.add(entry.id);
+        }
+    }, [bridge, ensureRenderer, printBanner, enqueue]);
+    // Shutdown hook for the exit paths. `restore()` runs it AFTER the tree is gone
+    // (normal exit) or while it is alive (signal), so it renders synchronously and then
+    // releases the offscreen instance. The unmount cleanup deliberately renders nothing:
+    // it runs inside the main tree's commit, where an offscreen render is deferred.
+    const settleAllRef = useRef(settleAll);
+    settleAllRef.current = settleAll;
+    useEffect(() => {
+        mountedRef.current = true;
+        if (!enabled || !bridge)
+            return undefined;
+        bridge.settleAllNow = () => {
+            try {
+                settleAllRef.current();
+            }
+            finally {
+                rendererRef.current?.dispose();
+                rendererRef.current = null;
+            }
+        };
+        return () => { mountedRef.current = false; };
+    }, [enabled, bridge]);
+    // --- Live region budget and streaming preview. ---------------------------
+    const boundary = useMemo(() => settledCount(entries, runActive), [entries, runActive]);
+    const unsettled = useMemo(() => entries.slice(boundary).filter((entry) => !isExcluded(entry)), [entries, boundary]);
+    const wanted = enabled
+        ? buildLivePreview({
+            unsettled, cols: contentCols, rows: SCROLLBACK_LIMITS.maxLiveTailRows, thinkingVisible,
+        }).length
+        : 0;
+    // D11 · the preview height only grows while anything is unsettled, then resets.
+    heldTailRows.current = unsettled.length === 0 ? 0 : Math.max(heldTailRows.current, wanted);
+    const budget = useMemo(() => enabled
+        ? buildScrollbackBudget({
+            rows, cols, draftRows, popupRows, statusExpanded, overlayOpen,
+            liveTailWanted: heldTailRows.current, forceInactive,
+        })
+        : null, 
+    // `heldTailRows.current` is read at memo time; `wanted` is what moves it.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [enabled, rows, cols, draftRows, popupRows, statusExpanded, overlayOpen, wanted,
+        unsettled.length, forceInactive]);
+    const liveTailLines = useMemo(() => enabled && budget && budget.liveTailRows > 0
+        ? buildLivePreview({ unsettled, cols: contentCols, rows: budget.liveTailRows, thinkingVisible })
+        : [], [enabled, budget, unsettled, contentCols, thinkingVisible]);
+    const reprintExpanded = useCallback((entryId) => {
+        if (!enabled || !bridge)
+            return false;
+        const list = latest.current.entries;
+        const index = list.findIndex((entry) => entry.id === entryId);
+        if (index < 0)
+            return false;
+        const entry = list[index];
+        const body = ensureRenderer().renderEntry(entry, undefined, latest.current.contentCols, true);
+        if (body.length === 0)
+            return false;
+        enqueue([`-- expanded: ${entry.kind === 'tool' ? entry.name : entry.kind} --`, ...body], `expanded:${entryId}:${Date.now()}`, entry.kind);
+        return true;
+    }, [enabled, bridge, ensureRenderer, enqueue]);
+    const notifyReset = useCallback((kind) => {
+        if (!enabled)
+            return;
+        pendingReset.current = { kind, captured: latest.current.entries };
+    }, [enabled]);
+    return { budget, liveTailLines, reprintExpanded, settleAll, notifyReset };
+}

package/dist/ui/scrollback/writer-shapes.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Byte shapes of the native-scroll writer (tui-native-terminal-scroll §4.3 /
+ * Appendix A). Stateless string assembly only — the state machine that decides
+ * WHICH shape to emit lives in `scrollback-writer.ts`.
+ *
+ * THE WHITELIST (I-S5 / I-S6). Every byte produced here is drawn from: SGR, CUU,
+ * CUD, CR, CRLF, ED0, EL0, DEC 2026 and DECTCEM. There is no absolute CUP, no
+ * scroll region, no `CSI S/T`, no `ED2/ED3`. Relative addressing is what makes the
+ * geometry independent of the terminal scrolling underneath it (spec appendix B).
+ *
+ * Each row is `SGR0 · text · SGR0`: the leading reset stops one row's style leaking
+ * into the next, and the trailing one stops a background-colour-erase terminal from
+ * painting the following ED0/EL0 in the row's last colour.
+ */
+export declare const SGR0 = "\u001B[0m";
+/** First write of a session: the cursor is already on a fresh line at column 0. */
+export declare function seedBytes(input: {
+    lines: readonly string[];
+    statics: readonly string[];
+    sync: boolean;
+    /** After a foreign write the cursor may sit mid-line; start on a new one (RV-11). */
+    reseed: boolean;
+}): string;
+/** Erase exactly the previous live region, print static rows, redraw the region. */
+export declare function fullBytes(input: {
+    lines: readonly string[];
+    statics: readonly string[];
+    /** Rows between the region top and the parked cursor. */
+    eraseUp: number;
+    sync: boolean;
+}): string;
+/** Same height, no static rows: rewrite only the rows that changed. `''` if none did. */
+export declare function diffBytes(input: {
+    lines: readonly string[];
+    prev: readonly string[];
+    sync: boolean;
+}): string;
+/**
+ * Exit: erase the live region, flush leftover static rows, print the summary.
+ * `eraseUp < 0` means the geometry is unknown (a foreign write intervened), in
+ * which case the only safe move is to start on a fresh line and erase nothing.
+ */
+export declare function finalizeBytes(input: {
+    eraseUp: number;
+    statics: readonly string[];
+    summary: readonly string[];
+}): string;
+/**
+ * Cut a row to `maxCols` DISPLAY columns (I-S13), keeping SGR / OSC 8 intact.
+ *
+ * Returns the input unchanged (same reference) when it already fits, which is the
+ * overwhelmingly common case. Width is measured the way Ink measures it
+ * (`string-width` over the ANSI-stripped text): that is the number Ink used to
+ * wrap, so a disagreement with the terminal is the only way a row can exceed it.
+ */
+export declare function clipLine(line: string, maxCols: number): {
+    text: string;
+    clipped: boolean;
+};
+/** Rows the previous region occupies after the terminal re-flowed it to `cols` (§4.10). */
+export declare function estimateReflowRows(lines: readonly string[], cols: number): number;

package/dist/ui/scrollback/writer-shapes.js

@@ -0,0 +1,114 @@
+/**
+ * Byte shapes of the native-scroll writer (tui-native-terminal-scroll §4.3 /
+ * Appendix A). Stateless string assembly only — the state machine that decides
+ * WHICH shape to emit lives in `scrollback-writer.ts`.
+ *
+ * THE WHITELIST (I-S5 / I-S6). Every byte produced here is drawn from: SGR, CUU,
+ * CUD, CR, CRLF, ED0, EL0, DEC 2026 and DECTCEM. There is no absolute CUP, no
+ * scroll region, no `CSI S/T`, no `ED2/ED3`. Relative addressing is what makes the
+ * geometry independent of the terminal scrolling underneath it (spec appendix B).
+ *
+ * Each row is `SGR0 · text · SGR0`: the leading reset stops one row's style leaking
+ * into the next, and the trailing one stops a background-colour-erase terminal from
+ * painting the following ED0/EL0 in the row's last colour.
+ */
+import stringWidth from 'string-width';
+import stripAnsi from 'strip-ansi';
+const CSI = '\x1b[';
+export const SGR0 = `${CSI}0m`;
+const ED0 = `${CSI}J`;
+const EL0 = `${CSI}K`;
+const SYNC_BEGIN = `${CSI}?2026h`;
+const SYNC_END = `${CSI}?2026l`;
+const SHOW_CURSOR = `${CSI}?25h`;
+const OSC8_CLOSE = '\x1b]8;;\x07';
+const up = (n) => (n > 0 ? `${CSI}${n}A` : '');
+const down = (n) => (n > 0 ? `${CSI}${n}B` : '');
+const row = (text) => SGR0 + text + SGR0 + '\r\n';
+const rows = (list) => list.map(row).join('');
+const wrapSync = (payload, sync) => sync ? SYNC_BEGIN + payload + SYNC_END : payload;
+/** First write of a session: the cursor is already on a fresh line at column 0. */
+export function seedBytes(input) {
+    const lead = input.reseed ? '\r\n' : '';
+    return wrapSync(lead + '\r' + SGR0 + rows(input.statics) + rows(input.lines), input.sync);
+}
+/** Erase exactly the previous live region, print static rows, redraw the region. */
+export function fullBytes(input) {
+    return wrapSync(up(input.eraseUp) + '\r' + SGR0 + ED0 + rows(input.statics) + rows(input.lines), input.sync);
+}
+/** Same height, no static rows: rewrite only the rows that changed. `''` if none did. */
+export function diffBytes(input) {
+    const { lines, prev } = input;
+    const height = lines.length;
+    let out = '';
+    let cursor = -1;
+    for (let i = 0; i < height; i += 1) {
+        if (lines[i] === prev[i])
+            continue;
+        // Paint, THEN clear the tail: never ESC[2K first, which would blank the row
+        // the user is looking at for the instant between the two writes.
+        out += (cursor < 0 ? up(height - i) : down(i - cursor)) + '\r' + SGR0 + lines[i] + SGR0 + EL0;
+        cursor = i;
+    }
+    if (cursor < 0)
+        return '';
+    // Park on the row below the region, column 0 (I-S4).
+    return wrapSync(out + down(height - cursor) + '\r', input.sync);
+}
+/**
+ * Exit: erase the live region, flush leftover static rows, print the summary.
+ * `eraseUp < 0` means the geometry is unknown (a foreign write intervened), in
+ * which case the only safe move is to start on a fresh line and erase nothing.
+ */
+export function finalizeBytes(input) {
+    const head = input.eraseUp < 0 ? '\r\n' : up(input.eraseUp) + '\r' + SGR0 + ED0;
+    return head + rows(input.statics) + rows(input.summary) + SHOW_CURSOR;
+}
+const ESCAPE = /(\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\))/;
+const segmenter = typeof Intl !== 'undefined' && 'Segmenter' in Intl
+    ? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+    : null;
+function graphemes(text) {
+    return segmenter ? Array.from(segmenter.segment(text), (part) => part.segment) : Array.from(text);
+}
+/**
+ * Cut a row to `maxCols` DISPLAY columns (I-S13), keeping SGR / OSC 8 intact.
+ *
+ * Returns the input unchanged (same reference) when it already fits, which is the
+ * overwhelmingly common case. Width is measured the way Ink measures it
+ * (`string-width` over the ANSI-stripped text): that is the number Ink used to
+ * wrap, so a disagreement with the terminal is the only way a row can exceed it.
+ */
+export function clipLine(line, maxCols) {
+    if (maxCols < 1)
+        return { text: '', clipped: line.length > 0 };
+    if (stringWidth(stripAnsi(line)) <= maxCols)
+        return { text: line, clipped: false };
+    let out = '';
+    let width = 0;
+    let linkOpen = false;
+    for (const part of line.split(ESCAPE)) {
+        if (part.startsWith('\x1b')) {
+            out += part;
+            if (part.startsWith('\x1b]8;'))
+                linkOpen = !/^\x1b\]8;[^;]*;(?:\x07|\x1b\\)$/.test(part);
+            continue;
+        }
+        for (const glyph of graphemes(part)) {
+            const glyphWidth = stringWidth(glyph);
+            if (width + glyphWidth > maxCols)
+                return { text: out + SGR0 + (linkOpen ? OSC8_CLOSE : ''), clipped: true };
+            out += glyph;
+            width += glyphWidth;
+        }
+    }
+    return { text: out, clipped: false };
+}
+/** Rows the previous region occupies after the terminal re-flowed it to `cols` (§4.10). */
+export function estimateReflowRows(lines, cols) {
+    const width = Math.max(1, cols);
+    let total = 0;
+    for (const line of lines)
+        total += Math.max(1, Math.ceil(stringWidth(stripAnsi(line)) / width));
+    return total;
+}

package/dist/ui/stdout-frame-writer.js

@@ -97,7 +97,14 @@ export function wrapStdoutForFrames(stdout, differ) {
         }
         return writeReal(out, encoding, cb);
     };
-    const onResize = () => differ.invalidate();
+    // Optional differ hooks keep the full-screen path byte-identical: a differ that
+    // does not implement them is invalidated exactly as before.
+    const onResize = () => {
+        if (differ.onResize)
+            differ.onResize();
+        else
+            differ.invalidate();
+    };
     stdout.on('resize', onResize);
     let disposed = false;
     const proxy = new Proxy(stdout, {
@@ -130,7 +137,10 @@ export function wrapStdoutForFrames(stdout, differ) {
             return true;
         },
         writeForeign(text) {
-            differ.invalidate();
+            if (differ.cursorNeutralWrite)
+                differ.cursorNeutralWrite();
+            else
+                differ.invalidate();
             if (disposed || text.length === 0)
                 return;
             writeReal(text);

package/dist/ui/terminal-plan.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Terminal plan — the ONE decision point for how the interactive TUI occupies the
+ * terminal (tui-native-terminal-scroll §4.1 / D10).
+ *
+ * `cli.tsx::runInteractive` used to derive `wantMouse`, `mouseOn`, `wantSelect`,
+ * `pasteOn` and `enhancedKeysOn` inline, each with its own comment about why the
+ * others must agree. Adding a second screen mode multiplies that surface, so the
+ * agreement is computed here, once, and the call site only READS the result.
+ *
+ * PURE: no I/O, no `process` access, so every row of the rules below is a table
+ * test with plain literals.
+ *
+ * I-S9 · `app` reproduces the pre-feature expressions term for term. The
+ * regression test diffs this function against a verbatim copy of those
+ * expressions, because "the same by inspection" is how mouse and paste drifted
+ * apart the last time.
+ */
+import type { ScrollMode } from '../config/schema.js';
+export type { ScrollMode } from '../config/schema.js';
+export interface TerminalPlanInput {
+    /** The resolved `scrollMode` config value. */
+    scrollMode: ScrollMode;
+    configMouse: boolean;
+    configMouseSelect: boolean;
+    configPaste: boolean;
+    configKeyboardEnhancement: boolean;
+    configDiffRender: boolean;
+    stdinIsTTY: boolean;
+    stdoutIsTTY: boolean;
+    platform: NodeJS.Platform;
+    /** Measured on win32 (`forceVtInputForThisConsole`); irrelevant elsewhere. */
+    vtInputSupported: boolean;
+}
+export interface TerminalPlan {
+    scrollMode: ScrollMode;
+    /** `app`: enter the alternate screen. `native`: never. */
+    altScreen: boolean;
+    /** Whether the terminal is asked for SGR mouse reports (and a mouse filter is wanted). */
+    mouseReporting: boolean;
+    /** Application-drawn drag selection. Always `false` in native mode (the terminal selects). */
+    dragSelect: boolean;
+    bracketedPaste: boolean;
+    enhancedKeys: boolean;
+    /**
+     * Which frame writer fronts Ink's stdout. `native` ALWAYS needs the scrollback
+     * writer, even with `diffRender` off: static rows are injected through it.
+     */
+    differ: 'fullscreen' | 'scrollback' | 'none';
+    /** Native + `diffRender:false` — every frame rewrites the whole live region. */
+    fullEveryFrame: boolean;
+}
+export declare function resolveTerminalPlan(input: TerminalPlanInput): TerminalPlan;

package/dist/ui/terminal-plan.js

@@ -0,0 +1,49 @@
+/**
+ * Terminal plan — the ONE decision point for how the interactive TUI occupies the
+ * terminal (tui-native-terminal-scroll §4.1 / D10).
+ *
+ * `cli.tsx::runInteractive` used to derive `wantMouse`, `mouseOn`, `wantSelect`,
+ * `pasteOn` and `enhancedKeysOn` inline, each with its own comment about why the
+ * others must agree. Adding a second screen mode multiplies that surface, so the
+ * agreement is computed here, once, and the call site only READS the result.
+ *
+ * PURE: no I/O, no `process` access, so every row of the rules below is a table
+ * test with plain literals.
+ *
+ * I-S9 · `app` reproduces the pre-feature expressions term for term. The
+ * regression test diffs this function against a verbatim copy of those
+ * expressions, because "the same by inspection" is how mouse and paste drifted
+ * apart the last time.
+ */
+export function resolveTerminalPlan(input) {
+    const bothTty = input.stdinIsTTY && input.stdoutIsTTY;
+    // Paste and keyboard enhancement ride the stdin filter and say nothing about
+    // scrolling, so the two modes agree on them (rule 3).
+    const bracketedPaste = input.configPaste && input.stdinIsTTY;
+    const enhancedKeys = input.configKeyboardEnhancement &&
+        input.stdinIsTTY &&
+        (input.platform !== 'win32' || input.vtInputSupported);
+    if (input.scrollMode === 'native') {
+        return {
+            scrollMode: 'native',
+            altScreen: false,
+            mouseReporting: false,
+            dragSelect: false,
+            bracketedPaste,
+            enhancedKeys,
+            differ: 'scrollback',
+            fullEveryFrame: !input.configDiffRender,
+        };
+    }
+    const mouseReporting = input.configMouse && bothTty && input.vtInputSupported;
+    return {
+        scrollMode: 'app',
+        altScreen: true,
+        mouseReporting,
+        dragSelect: mouseReporting && input.configMouseSelect,
+        bracketedPaste,
+        enhancedKeys,
+        differ: input.configDiffRender ? 'fullscreen' : 'none',
+        fullEveryFrame: false,
+    };
+}

package/dist/ui/transcript-text.d.ts

@@ -26,5 +26,16 @@ export interface TranscriptTextOptions {
      */
     droppedEntries?: number;
 }
+/**
+ * The three figures every session summary carries: turns, tokens, cost.
+ *
+ * One implementation for the exit replay and the native-scroll exit summary
+ * (tui-native-terminal-scroll §4.8), so the two can never disagree.
+ */
+export declare function formatSessionStats(entries: readonly Entry[], usageTotal: UsageTotal, g: Pick<Glyphs, 'arrowUp' | 'arrowDown'>): {
+    turns: string;
+    tokens: string;
+    cost: string;
+};
 /** Render the whole session (summary line + entries) as plain text. */
 export declare function renderTranscriptText(entries: Entry[], opts: TranscriptTextOptions): string;

package/dist/ui/transcript-text.js

@@ -198,21 +198,35 @@ function renderEntry(entry, glyphs) {
             return [];
     }
 }
-/** Render the whole session (summary line + entries) as plain text. */
-export function renderTranscriptText(entries, opts) {
+/**
+ * The three figures every session summary carries: turns, tokens, cost.
+ *
+ * One implementation for the exit replay and the native-scroll exit summary
+ * (tui-native-terminal-scroll §4.8), so the two can never disagree.
+ */
+export function formatSessionStats(entries, usageTotal, g) {
     const turns = entries.filter((e) => e.kind === 'user').length;
-    const g = opts.glyphs;
     // THE SAME PROMPT-SIDE TOTAL THE STATUS BAR SHOWS (context-usage-gauge-accuracy
     // §3.6). This line is what a user compares against the bar they were watching a
     // second earlier, so a different unit here would look like the exit summary
     // losing tokens.
-    const tokens = `${formatTokens(promptTokensOf(opts.usageTotal))}${g.arrowUp} ${formatTokens(opts.usageTotal.outputTokens)}${g.arrowDown}`;
+    const tokens = `${formatTokens(promptTokensOf(usageTotal))}${g.arrowUp} ${formatTokens(usageTotal.outputTokens)}${g.arrowDown}`;
+    return {
+        turns: `${turns} ${turns === 1 ? 'turn' : 'turns'}`,
+        tokens,
+        cost: formatCost(usageTotal.costUsd),
+    };
+}
+/** Render the whole session (summary line + entries) as plain text. */
+export function renderTranscriptText(entries, opts) {
+    const g = opts.glyphs;
+    const stats = formatSessionStats(entries, opts.usageTotal, g);
     const summary = [
         'aragon',
         `${opts.provider}:${opts.model}`,
-        `${turns} ${turns === 1 ? 'turn' : 'turns'}`,
-        tokens,
-        formatCost(opts.usageTotal.costUsd),
+        stats.turns,
+        stats.tokens,
+        stats.cost,
         formatDuration(Math.max(0, opts.elapsedMs)),
     ].join(` ${g.midDot} `);
     const max = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;

package/dist/ui/use-startup-notices.d.ts

@@ -53,6 +53,17 @@ export interface RetainNoticeOptions {
     requested: number;
     resolved: number;
 }
+/**
+ * The revision of the native-scroll notice a user must have seen for it to stay
+ * quiet (`state.json::scrollModeNoticeVersion`). BUMP IT WHENEVER THE ADVICE
+ * CHANGES, never for a rewording (tui-native-terminal-scroll D12).
+ */
+export declare const SCROLL_MODE_NOTICE_VERSION = 1;
+export declare function scrollModeNoticeText(): string;
+export interface ScrollModeNoticeOptions {
+    /** Record that `SCROLL_MODE_NOTICE_VERSION` was shown (`state.json`). */
+    onSeen: () => void;
+}
 export interface MouseNoticeOptions {
     /**
      * Whether reporting is ACTUALLY in effect: a filter was installed AND the
@@ -98,4 +109,4 @@ export interface VtInputNoticeOptions {
      */
     onSeen: () => void;
 }
-export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions, retainNotice?: RetainNoticeOptions, vtInputNotice?: VtInputNoticeOptions): void;
+export declare function useStartupNotices(dispatch: (action: ViewAction) => void, mouseNotice?: MouseNoticeOptions, retainNotice?: RetainNoticeOptions, vtInputNotice?: VtInputNoticeOptions, scrollModeNotice?: ScrollModeNoticeOptions): void;