@aragon-agent/cli 0.6.28 → 0.6.31

package/dist/cli.js

@@ -29,7 +29,7 @@ import { COMPACTION_CONFIG_SET_KEYS, FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS,
 import { attachAgentEvents, attachTeamEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
 import { getLogger } from './logging/logger.js';
 import { runLogsCommand } from './logging/cli-commands.js';
-import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampContextWindow, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, isAutoToken, parseMaxTokensInput, DEFAULT_MAX_RENDER_INTERVAL_MS, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SCROLL_RESUME_MS, DEFAULT_SKILLS_CONFIG, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from './config/schema.js';
+import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampContextWindow, clampMaxRenderInterval, clampScrollMode, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, isAutoToken, parseMaxTokensInput, DEFAULT_MAX_RENDER_INTERVAL_MS, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SCROLL_MODE, DEFAULT_SCROLL_RESUME_MS, DEFAULT_SKILLS_CONFIG, DEFAULT_TRANSCRIPT_RETAIN, DEFAULT_TRANSCRIPT_WINDOW, } from './config/schema.js';
 import { makeGetApiKey } from './config/load.js';
 import { AgentController, DENY_ALL_APPROVAL } from './agent/controller.js';
 import { runSkillsCommand } from './skills/cli-commands.js';
@@ -49,13 +49,17 @@ import { createBranchLauncher } from './session/branch-launch.js';
 import { EMPTY_USAGE_TOTAL } from './agent/reducer.js';
 import { createFrameDiffer } from './ui/frame-differ.js';
 import { wrapStdoutForFrames } from './ui/stdout-frame-writer.js';
-import { setFrameStatsProvider } from './commands/perf.js';
+import { setFrameStatsProvider, setScrollbackStatsProvider } from './commands/perf.js';
 import { tryCreateStdinFilter } from './input/stdin-filter.js';
 import { enableKeyboardEnhancement, NOOP_KEYBOARD_ENHANCEMENT, } from './input/keyboard-enhancement.js';
 import { createScrollbarBridge } from './ui/scrollbar-controller.js';
 import { createPointerRouter } from './input/pointer-router.js';
 import { createFrameObserver } from './ui/frame-observer.js';
-import { enterAltScreen, writeExitTranscript } from './ui/screen.js';
+import { enterAltScreen, enterNativeScreen, writeExitTranscript, } from './ui/screen.js';
+import { resolveTerminalPlan } from './ui/terminal-plan.js';
+import { createScrollbackDrain } from './ui/scrollback/drain.js';
+import { createScrollbackWriter } from './ui/scrollback/scrollback-writer.js';
+import { createScrollbackBridge, } from './ui/scrollback/use-scrollback-view.js';
 import { supportsWindowsVtInput } from './ui/win-vt-input.js';
 import { forceWindowsVtInput } from './ui/win-vt-force.js';
 import { readExitSnapshot } from './ui/exit-snapshot.js';
@@ -88,6 +92,19 @@ function readVersion() {
     }
 }
 const VERSION = readVersion();
+/**
+ * `--scroll-mode` is the one flag validated at parse time (tui-native-terminal-scroll
+ * §6.1): a typo must be an exit-2 sentence, not a silent fallback to the default.
+ */
+function parseScrollModeFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    const mode = clampScrollMode(raw, DEFAULT_SCROLL_MODE);
+    if (mode === raw.trim().toLowerCase())
+        return mode;
+    process.stderr.write(`Invalid --scroll-mode "${raw}" (expected native or app).\n`);
+    process.exit(2);
+}
 function toFlags(opts) {
     return {
         provider: opts.provider,
@@ -186,6 +203,8 @@ function toFlags(opts) {
         // user whose terminal renders the diffed frame wrongly, and a user who has
         // been told to pass it and sees no change has no next move.
         diffRender: opts.diffRender,
+        // Third site for `--scroll-mode`, the same trap the sentence above records.
+        scrollMode: parseScrollModeFlag(opts.scrollMode),
         syncOutput: opts.syncOutput,
         // Site three of three for `--update` / `--no-update` — SEVEN features, one
         // trap (`mouse` P1-2, `team` P1-4, `todo` C-9, render L4, retry, fast, now
@@ -431,8 +450,10 @@ function runInteractive(flags, extras = {}) {
     const config = controller.getConfig();
     const caps = resolveTuiCapabilities({}, config.color);
     const logger = getLogger();
+    const scrollMode = config.scrollMode ?? DEFAULT_SCROLL_MODE;
     logger.info('cli', 'run_interactive', {
-        mode: 'fullscreen', provider: config.provider, model: config.model,
+        mode: scrollMode === 'native' ? 'native' : 'fullscreen',
+        provider: config.provider, model: config.model,
         unicode: caps.unicode, colorLevel: caps.colorLevel,
     });
     attachAgentEvents(logger, controller);
@@ -513,6 +534,37 @@ function runInteractive(flags, extras = {}) {
     };
     let screen = null;
     let replayed = false;
+    /**
+     * Native-scroll exit, shared by EVERY restore path (normal exit, `process.on
+     * ('exit')`, the signal terminator, the crash handler, `failInteractive`).
+     * Idempotent: the writer's `finalize` returns `''` the second time.
+     *
+     * Order (RV-9): publish the last unsettled entries to the feed, take the summary
+     * (lazily, and a failure only costs the summary), then write the finalize bytes
+     * through the REAL stdout. After `finalize` the writer swallows every Ink write,
+     * so it does not matter whether Ink has unmounted yet; callers must not add an
+     * asynchronous wait for it.
+     */
+    const finalizeNativeScreen = () => {
+        const bridge = scrollbackBridge;
+        if (!bridge)
+            return;
+        try {
+            bridge.settleAllNow();
+        }
+        catch { /* the feed keeps whatever was queued */ }
+        let summary = [];
+        try {
+            summary = bridge.getSummaryRows();
+        }
+        catch { /* degrade to no summary */ }
+        try {
+            const bytes = bridge.writer.finalize(summary);
+            if (bytes.length > 0)
+                process.stdout.write(bytes);
+        }
+        catch { /* a closed stdout must never turn into a crash on the exit path */ }
+    };
     // --- Mouse wheel region routing (mouse-wheel-region-routing §4.2). -------
     //
     // BUILD THE FILTER FIRST, THEN ENABLE REPORTING. The order is invariant I-8
@@ -553,10 +605,23 @@ function runInteractive(flags, extras = {}) {
     // a console this process just repaired.
     const vtInputByNode = supportsWindowsVtInput(process.platform, process.versions.node);
     const vtInputSupported = vtInputByNode || forceVtInputForThisConsole();
-    const wantMouse = config.mouse &&
-        !!process.stdout.isTTY &&
-        !!process.stdin.isTTY &&
-        vtInputSupported;
+    // THE ONE DECISION POINT for screen mode, mouse, paste, key enhancement and the
+    // frame writer (tui-native-terminal-scroll D10). In `app` mode every field below
+    // is the pre-feature expression term for term (`terminal-plan.test.ts` pins it).
+    const plan = resolveTerminalPlan({
+        scrollMode,
+        configMouse: config.mouse,
+        configMouseSelect: config.mouseSelect,
+        configPaste: config.paste,
+        configKeyboardEnhancement: config.keyboardEnhancement,
+        configDiffRender: config.diffRender,
+        stdinIsTTY: !!process.stdin.isTTY,
+        stdoutIsTTY: !!process.stdout.isTTY,
+        platform: process.platform,
+        vtInputSupported,
+    });
+    const native = plan.scrollMode === 'native';
+    const wantMouse = plan.mouseReporting;
     // --- Paste handling (tui-paste-handling section 5.1.1 / D-13 / D-17). ----
     //
     // THE GATE IS WIDER THAN THE MOUSE'S, AND `paste` DEFAULTS TO TRUE. Paste
@@ -571,7 +636,7 @@ function runInteractive(flags, extras = {}) {
     // would flip true: `?1000h`/`?1006h`/`?1002h` written, terminal selection taken
     // away (the ONLY reason anyone passes `--no-mouse`), and a startup notice
     // advising the user about a mode they just disabled.
-    const wantPaste = config.paste && !!process.stdin.isTTY;
+    const wantPaste = plan.bracketedPaste;
     const pasteBridge = { notify: null };
     // --- Keyboard enhancement (Shift+Enter newline). --------------------------
     //
@@ -584,9 +649,7 @@ function runInteractive(flags, extras = {}) {
     // Elsewhere the push is kitty disambiguate + modifyOtherKeys, which a
     // terminal that implements neither ignores (verified byte-identical on
     // conhost), so no capability gate is possible or needed there.
-    const wantEnhancedKeys = config.keyboardEnhancement &&
-        !!process.stdin.isTTY &&
-        (process.platform !== 'win32' || vtInputSupported);
+    const wantEnhancedKeys = plan.enhancedKeys;
     const filter = process.stdin.isTTY
         ? tryCreateStdinFilter(process.stdin, { mouse: wantMouse, paste: wantPaste, enhancedKeys: wantEnhancedKeys }, (reason) => logger.warn('cli', 'stdin_filter_failed', { reason }), pasteBridge)
         : null;
@@ -607,6 +670,7 @@ function runInteractive(flags, extras = {}) {
     //
     // Selection owns its controller, decoration and notice. Button motion follows
     // mouseOn independently so --no-mouse-select still permits scrollbar dragging.
+    // `mouseOn` is already false in native mode, so this needs no `plan.dragSelect` term.
     const wantSelect = mouseOn && config.mouseSelect;
     let mouseCaptured = mouseOn;
     const scrollbar = createScrollbarBridge(() => mouseCaptured);
@@ -618,59 +682,94 @@ function runInteractive(flags, extras = {}) {
         onCopied: null,
         requestRedraw: null,
     };
-    const frameWriter = config.diffRender
-        ? wrapStdoutForFrames(process.stdout, createFrameDiffer({
+    // Native scroll: a drain + writer pair replaces the full-screen differ. The bridge
+    // is the only object shared with the React tree (tui-native-terminal-scroll §6.2).
+    let scrollbackBridge;
+    if (plan.differ === 'scrollback') {
+        const drain = createScrollbackDrain();
+        const writer = createScrollbackWriter({
             sync: config.syncOutput && process.env.TERM !== 'dumb',
             rows: () => process.stdout.rows,
-            // Rows that fill the line skip `CSI K` so the scrollbar's last column
-            // is not erased on pending-wrap terminals (frame-differ I-4).
             cols: () => process.stdout.columns,
-            // The console bridge (`App.tsx`, full-screen only) turns this into
-            // `dispatch({type:'notice', level:'warn'})`, which is the only legal
-            // user-visible channel with the TUI mounted — a direct write would
-            // itself be the foreign write being reported. Latched on the 0->1
-            // edge inside the differ: a notice per fallback would be a repaint
-            // storm triggered by a repaint problem (§5.6).
+            fullEveryFrame: plan.fullEveryFrame,
+            drain,
             onFirstFallback: () => console.warn(FRAME_FALLBACK_NOTICE),
-            // ABSENT ENTIRELY without drag-select, not a no-op function: the
-            // differ's identity path then allocates nothing and copies nothing,
-            // which is what makes `mouseSelect: false` a statement about the code
-            // rather than about how cheap an empty function is.
-            ...(wantSelect
-                ? {
-                    decorate: (lines) => selectionBridge.controller?.decorate(lines) ?? lines,
-                    // P1-7: a pass-through frame writes the RAW Ink frame verbatim,
-                    // so the highlight is wiped off the terminal while the
-                    // controller still believes it is painted. Deferred out of the
-                    // current stack because this fires from inside `transform`,
-                    // which is inside Ink's own `stdout.write`.
-                    onInvalidate: () => {
-                        const controller = selectionBridge.controller;
-                        if (controller)
-                            setImmediate(() => controller.clear());
-                    },
-                }
-                : {}),
-        }))
-        : null;
+            onGuardTrip: () => scrollbackBridge?.onGuardTrip?.(),
+            // Deferred: static rows can be queued from inside a React commit, and the
+            // repaint writes to the stream Ink is in the middle of writing to.
+            requestRepaint: () => { setImmediate(() => frameWriter?.repaint()); },
+        });
+        scrollbackBridge = createScrollbackBridge({
+            writer, drain, requestFlush: () => { setImmediate(() => frameWriter?.repaint()); },
+        });
+    }
+    const frameWriter = scrollbackBridge
+        ? wrapStdoutForFrames(process.stdout, scrollbackBridge.writer)
+        : plan.differ === 'fullscreen'
+            ? wrapStdoutForFrames(process.stdout, createFrameDiffer({
+                sync: config.syncOutput && process.env.TERM !== 'dumb',
+                rows: () => process.stdout.rows,
+                // Rows that fill the line skip `CSI K` so the scrollbar's last column
+                // is not erased on pending-wrap terminals (frame-differ I-4).
+                cols: () => process.stdout.columns,
+                // The console bridge (`App.tsx`, full-screen only) turns this into
+                // `dispatch({type:'notice', level:'warn'})`, which is the only legal
+                // user-visible channel with the TUI mounted — a direct write would
+                // itself be the foreign write being reported. Latched on the 0->1
+                // edge inside the differ: a notice per fallback would be a repaint
+                // storm triggered by a repaint problem (§5.6).
+                onFirstFallback: () => console.warn(FRAME_FALLBACK_NOTICE),
+                // ABSENT ENTIRELY without drag-select, not a no-op function: the
+                // differ's identity path then allocates nothing and copies nothing,
+                // which is what makes `mouseSelect: false` a statement about the code
+                // rather than about how cheap an empty function is.
+                ...(wantSelect
+                    ? {
+                        decorate: (lines) => selectionBridge.controller?.decorate(lines) ?? lines,
+                        // P1-7: a pass-through frame writes the RAW Ink frame verbatim,
+                        // so the highlight is wiped off the terminal while the
+                        // controller still believes it is painted. Deferred out of the
+                        // current stack because this fires from inside `transform`,
+                        // which is inside Ink's own `stdout.write`.
+                        onInvalidate: () => {
+                            const controller = selectionBridge.controller;
+                            if (controller)
+                                setImmediate(() => controller.clear());
+                        },
+                    }
+                    : {}),
+            }))
+            : null;
     // `null` when no writer was built, so `/perf` can say "diff render off" rather
     // than printing zeroes that read like a writer doing nothing (§5.4).
     if (frameWriter)
         setFrameStatsProvider(frameWriter.stats);
-    const frameObserver = createFrameObserver({
-        stdout: frameWriter?.stdout ?? process.stdout, terminal: process.stdout, scrollbar,
-    });
+    if (scrollbackBridge) {
+        const { writer } = scrollbackBridge;
+        setScrollbackStatsProvider(() => ({
+            ...writer.scrollbackStats(), regionRows: writer.regionRows(),
+        }));
+    }
+    // The observer only serves the full-screen scrollbar geometry; native has none.
+    const frameObserver = native
+        ? null
+        : createFrameObserver({
+            stdout: frameWriter?.stdout ?? process.stdout, terminal: process.stdout, scrollbar,
+        });
     const disposeFrameWriter = () => {
-        frameObserver.dispose();
+        frameObserver?.dispose();
         pointerRouter?.dispose();
         scrollbar.controller?.dispose();
         if (!frameWriter)
             return;
         setFrameStatsProvider(null);
+        setScrollbackStatsProvider(null);
         frameWriter.dispose();
     };
     const replayTranscript = () => {
-        if (replayed || !config.exitTranscript)
+        // Native mode never replays: the conversation is already in the scrollback, and
+        // a replay would print it twice (D9).
+        if (replayed || !config.exitTranscript || native)
             return;
         replayed = true;
         const snapshot = readExitSnapshot();
@@ -710,17 +809,21 @@ function runInteractive(flags, extras = {}) {
         // paste at its default `true` still builds a filter, and passing the handle
         // here would write `?1000h` at a user who disabled the mouse precisely to
         // keep their terminal's own selection.
-        screen = enterAltScreen(process.stdout, {
-            mouse: mouseOn,
-            motion: mouseOn,
-            bracketedPaste: pasteOn,
-        });
+        screen = plan.altScreen
+            ? enterAltScreen(process.stdout, {
+                mouse: mouseOn,
+                motion: mouseOn,
+                bracketedPaste: pasteOn,
+            })
+            // Native scroll: no alternate screen, no mouse (D6). Only DEC 2004.
+            : enterNativeScreen(process.stdout, { bracketedPaste: pasteOn });
         // Input-encoding modes unwind FIRST, for the same reason the mouse
         // reporting does inside `screen.restore()`: the terminal must stop
         // sending enhanced encodings before anything else tears the reader
         // down, or a keystroke taken in that instant survives into the shell.
         const restore = () => {
             keyboardEnhancement.restore();
+            finalizeNativeScreen();
             screen?.restore();
         };
         // Four idempotent restore paths (§4.4). The signal hook is NOT redundant:
@@ -838,7 +941,8 @@ function runInteractive(flags, extras = {}) {
         interactiveClosed = true;
         logger.error('cli', 'render_failed', { error: String(error) });
         for (const cleanup of [
-            () => screen?.restore(), disposeSelection, disposeStdinFilter, disposeFrameWriter,
+            finalizeNativeScreen, () => screen?.restore(), disposeSelection, disposeStdinFilter,
+            disposeFrameWriter,
             () => controller.abort(), () => controller.dispose(), () => updateService?.dispose(),
             () => { process.stdin.pause(); process.stdin.unref?.(); },
         ]) {
@@ -865,7 +969,7 @@ function runInteractive(flags, extras = {}) {
             vtInputWarning: vtInputSupported ? undefined : { nodeVersion: process.versions.node }, updateBridge: updateEligible ? updateBridge : undefined, 
             // Absent when nothing can refuse a paste, so a `--no-paste` tree is
             // byte-identical to a build without this feature.
-            pasteBridge: pasteOn ? pasteBridge : undefined, terminal: terminalBridge, session: identity, sessionBridge: sessionBridge, ...(startup.initialEntries.length > 0 ? { initialEntries: startup.initialEntries } : {}), ...(startup.notice ? { sessionNotice: startup.notice } : {}) }), 
+            pasteBridge: pasteOn ? pasteBridge : undefined, terminal: terminalBridge, ...(scrollbackBridge ? { scrollMode: plan.scrollMode, scrollback: scrollbackBridge } : {}), session: identity, sessionBridge: sessionBridge, ...(startup.initialEntries.length > 0 ? { initialEntries: startup.initialEntries } : {}), ...(startup.notice ? { sessionNotice: startup.notice } : {}) }), 
         // Full-screen owns console.* itself (I-4): Ink's patchConsole writes
         // straight to stdout and permanently shifts the fixed frame's accounting.
         {
@@ -874,7 +978,7 @@ function runInteractive(flags, extras = {}) {
             // I-5: with mouse support off the REAL stdin is handed over unwrapped, so
             // every existing path is provably unchanged.
             stdin: filter?.stdin ?? process.stdin,
-            stdout: frameObserver.stdout,
+            stdout: frameObserver?.stdout ?? frameWriter?.stdout ?? process.stdout,
         }, caps);
     }
     catch (error) {
@@ -955,6 +1059,9 @@ function runInteractive(flags, extras = {}) {
         // Also cover a successful immediate exit when launched via dist/cli.js,
         // which bypasses the launcher's code-zero boot-guard backstop.
         markBootHealthy(VERSION);
+        // Native scroll: finalize BEFORE the screen handle (the writer erases the live
+        // region and prints the summary; the handle then shows the cursor again).
+        finalizeNativeScreen();
         screen?.restore();
         // BEFORE `disposeStdinFilter()`, which clears the listener set it subscribed to,
         // and after `restore()` for the reason that call records: the terminal must
@@ -1159,6 +1266,8 @@ const CONFIG_SET_KEYS = new Set([
     // tui-input-flicker-fix §5.1. Listed here AND cased in the switch below, for
     // the reason `transcriptRetain` records three lines up.
     'diffRender',
+    // tui-native-terminal-scroll. Listed here AND cased in the switch below.
+    'scrollMode',
     'syncOutput',
     // Without these two, `density` and `hints` would be settable only as one-shot
     // flags and never persist -- inconsistent with every other config field.
@@ -1401,6 +1510,9 @@ function runConfigSetValue(key, value) {
         case 'diffRender':
             patch.diffRender = value === 'true' || value === '1';
             break;
+        case 'scrollMode':
+            patch.scrollMode = clampScrollMode(value, DEFAULT_SCROLL_MODE);
+            break;
         case 'syncOutput':
             patch.syncOutput = value === 'true' || value === '1';
             break;
@@ -1790,6 +1902,7 @@ function buildProgram() {
         // one documented escape hatch for a mis-rendering terminal into a no-op.
         .option('--diff-render', 'Repaint only changed rows (default, full-screen only)')
         .option('--no-diff-render', 'Repaint the whole frame every time (pre-fix behavior)')
+        .option('--scroll-mode <mode>', 'Scrolling: native (terminal scrollback, default) or app (full-screen)')
         .option('--sync-output', 'Ask the terminal to present each repaint atomically (the default)')
         .option('--no-sync-output', 'Do not emit DEC 2026 begin/end synchronized update')
         .option('--no-color', 'Disable ANSI color')

package/dist/commands/builtins.js

@@ -1122,6 +1122,10 @@ const COMMANDS = [
         name: 'mouse',
         description: 'Release the mouse to the terminal, or take it back',
         run: (ctx) => {
+            if (ctx.nativeScroll) {
+                ctx.notify('info', 'Mouse capture is not used in native scroll mode; your terminal handles scrolling and selection.');
+                return;
+            }
             const port = ctx.mouse;
             if (!port) {
                 // Inline mode, `--no-mouse`, a non-TTY, or a console that cannot deliver

package/dist/commands/perf.d.ts

@@ -34,7 +34,8 @@ export interface PerfSnapshot {
     heightsEstimated: number;
     cols: number;
     /** Geometry. */
-    mode: 'fullscreen';
+    mode: 'fullscreen' | 'native';
+    /** Full-screen: the transcript viewport. Native: the live region height. */
     viewportRows: number;
     offset: number;
     /** Right-edge scrollbar diagnostics; read lazily so it reflects the live bridge. */
@@ -74,6 +75,29 @@ export declare function setPerfResetHook(fn: (() => void) | null): void;
 /** Called by `cli.tsx` after building the writer. Passing `null` detaches. */
 export declare function setFrameStatsProvider(fn: (() => FrameWriterStats) | null): void;
 export declare function readFrameStats(): FrameWriterStats | null;
+/**
+ * Native-scroll writer counters (tui-native-terminal-scroll §5.1). A third
+ * module-level slot for the reason the one above records: the writer lives outside
+ * React. `guardHitsOutsideResize > 0` on a session with no resize is the defect
+ * signal (a live region reached the terminal height); `clippedRows > 0` means Ink
+ * and the terminal disagreed about a character's width (I-S13).
+ */
+export interface ScrollbackPerf {
+    regionRows: number;
+    framesSeed: number;
+    framesDiff: number;
+    framesFull: number;
+    staticRowsWritten: number;
+    elidedEntries: number;
+    guardHits: number;
+    guardHitsOutsideResize: number;
+    clippedRows: number;
+    fallbacks: number;
+    resizes: number;
+    repaints: number;
+}
+/** Called by `cli.tsx` in native mode. Passing `null` detaches. */
+export declare function setScrollbackStatsProvider(fn: (() => ScrollbackPerf) | null): void;
 /** Format a snapshot as the six-line block documented in §5.4 (plus the scrollbar line). */
 export declare function formatPerfReport(snap: PerfSnapshot): string;
 export declare const perfCommand: SlashCommand;

package/dist/commands/perf.js

@@ -68,6 +68,24 @@ export function setFrameStatsProvider(fn) {
 export function readFrameStats() {
     return frameStats ? frameStats() : null;
 }
+let scrollbackStats = null;
+/** Called by `cli.tsx` in native mode. Passing `null` detaches. */
+export function setScrollbackStatsProvider(fn) {
+    scrollbackStats = fn;
+}
+function formatScrollbackLine() {
+    const stats = scrollbackStats?.();
+    if (!stats)
+        return [];
+    return [
+        `scrollback region ${stats.regionRows} rows  -  batches seed ${stats.framesSeed}, ` +
+            `diff ${stats.framesDiff}, full ${stats.framesFull}, repaint ${stats.repaints}  -  ` +
+            `static rows ${stats.staticRowsWritten}  -  elided ${stats.elidedEntries}`,
+        `           guardHits ${stats.guardHits} (outside resize ${stats.guardHitsOutsideResize})  -  ` +
+            `clippedRows ${stats.clippedRows}  -  fallbacks ${stats.fallbacks}  -  ` +
+            `resizes ${stats.resizes}`,
+    ];
+}
 function mb(bytes) {
     return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
 }
@@ -107,7 +125,10 @@ export function formatPerfReport(snap) {
     const caches = renderCacheStats();
     const eco = snap.rung > 0 ? '  -  eco' : '';
     const governor = snap.governorEnabled ? '' : '  -  governor off';
-    const scrollbar = snap.scrollbar ? [formatScrollbarLine(snap.scrollbar)] : [];
+    const native = snap.mode === 'native';
+    const scrollbar = native
+        ? ['scrollbar  n/a (native scroll)']
+        : snap.scrollbar ? [formatScrollbarLine(snap.scrollbar)] : [];
     return [
         `render     rung ${snap.rung}  -  interval ${snap.intervalMs}ms  -  last commit ` +
             `${Math.round(snap.lastCommitMs)}ms${eco}${governor}`,
@@ -118,8 +139,11 @@ export function formatPerfReport(snap) {
         `caches     md ${caches.markdownEntries} (${mb(caches.markdownBytes)})  -  ` +
             `hl ${caches.highlightEntries} (${mb(caches.highlightBytes)})  -  ` +
             `lines ${caches.lineEntries}`,
-        `mode       ${snap.mode}  -  viewport ${snap.viewportRows} rows  -  offset ${snap.offset}`,
+        native
+            ? `mode       native  -  live region ${snap.viewportRows} rows`
+            : `mode       ${snap.mode}  -  viewport ${snap.viewportRows} rows  -  offset ${snap.offset}`,
         formatWriterLine(),
+        ...formatScrollbackLine(),
         ...scrollbar,
     ].join('\n');
 }

package/dist/commands/registry.d.ts

@@ -100,6 +100,12 @@ export interface CommandContext {
      * missing, which is the same reason `update` above it is optional.
      */
     mouse?: MouseCommandPort;
+    /**
+     * True in native-scroll mode (tui-native-terminal-scroll): the terminal owns
+     * scrolling and selection, so there is no capture to toggle. Lets `/mouse` say so
+     * instead of the generic "not captured" answer.
+     */
+    nativeScroll?: boolean;
     /**
      * The foreign-write door, for `/copy`'s OSC 52 half (§4.4.5).
      *

package/dist/config/env.js

@@ -392,6 +392,10 @@ export function readEnvConfig() {
         partial.diffRender =
             diffRender === '1' || diffRender === 'true' || diffRender === 'on' || diffRender === 'yes';
     }
+    // Invalid values are ignored, like every other ARAGON_* key.
+    const scrollMode = process.env.ARAGON_SCROLL_MODE?.trim().toLowerCase();
+    if (scrollMode === 'native' || scrollMode === 'app')
+        partial.scrollMode = scrollMode;
     const syncOutput = process.env.ARAGON_SYNC_OUTPUT?.trim().toLowerCase();
     if (syncOutput !== undefined && syncOutput.length > 0) {
         partial.syncOutput =

package/dist/config/load.d.ts

@@ -5,7 +5,7 @@
  * layers, `idleTimeout` is re-derived to be strictly ≥ `toolTimeout` so a
  * legitimately long single tool run can never be watchdog-killed.
  */
-import { type CliConfig } from './schema.js';
+import { type CliConfig, type ScrollMode } from './schema.js';
 import type { ModelRole } from './model-profiles.js';
 export interface CliFlags {
     provider?: string;
@@ -149,6 +149,8 @@ export interface CliFlags {
      * all — i.e. the documented escape hatch would quietly un-set itself.
      */
     diffRender?: boolean;
+    /** `--scroll-mode <native|app>`; already validated by `cli.tsx` (exit 2 on junk). */
+    scrollMode?: ScrollMode;
     /** `--sync-output` ⇒ true, `--no-sync-output` ⇒ false, absent ⇒ undefined (§5.2). */
     syncOutput?: boolean;
     /**

package/dist/config/load.js

@@ -6,7 +6,7 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampContextWindow, clampMaxTokens, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, legacyTeamCeilingPatch, parseThresholdInput, } from './schema.js';
+import { DEFAULT_CONFIG, DEFAULT_SCROLL_MODE, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampContextWindow, clampMaxTokens, clampMaxRenderInterval, clampScrollMode, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, legacyTeamCeilingPatch, parseThresholdInput, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile, updatePersistedConfig } from './store.js';
 import { projectModelProfiles, resolveModelProfileState, resolveModelRoleKey, } from './model-profile-resolution.js';
@@ -334,6 +334,16 @@ function resolveDiffRender(flags, env, file) {
         return file.diffRender;
     return DEFAULT_CONFIG.diffRender;
 }
+/** flags > env > file > default, like `resolveDiffRender` (tui-native-terminal-scroll §6.1). */
+function resolveScrollMode(flags, env, file) {
+    if (flags.scrollMode !== undefined)
+        return flags.scrollMode;
+    if (env.scrollMode !== undefined)
+        return env.scrollMode;
+    if (file.scrollMode !== undefined)
+        return clampScrollMode(file.scrollMode, DEFAULT_SCROLL_MODE);
+    return DEFAULT_SCROLL_MODE;
+}
 /** Same ladder for the DEC 2026 envelope (§5.1). */
 function resolveSyncOutput(flags, env, file) {
     if (flags.syncOutput !== undefined)
@@ -638,6 +648,7 @@ export function loadConfig(flags = {}, options = {}) {
         renderGovernor: resolveRenderGovernor(flags, env.partial, file),
         maxRenderIntervalMs: clampMaxRenderInterval(pick(flags.maxRenderInterval, env.partial.maxRenderIntervalMs, file.maxRenderIntervalMs), DEFAULT_CONFIG.maxRenderIntervalMs),
         diffRender: resolveDiffRender(flags, env.partial, file),
+        scrollMode: resolveScrollMode(flags, env.partial, file),
         syncOutput: resolveSyncOutput(flags, env.partial, file),
         confirmTools,
         toolTimeoutMs,

package/dist/config/schema.d.ts

@@ -39,6 +39,17 @@ export declare function isThemeName(v: unknown): v is ThemeName;
  * and would not match `clampThinkingLevel` / `clampTranscriptWindow`.
  */
 export declare function clampTheme(v: unknown, fallback: ThemeName): ThemeName;
+export declare const SCROLL_MODES: readonly ["native", "app"];
+/**
+ * How the interactive TUI scrolls (tui-native-terminal-scroll D1).
+ *
+ * `native` prints settled conversation into the host terminal's own scrollback and
+ * keeps only a bounded live region on screen; `app` is the original full-screen
+ * alternate-screen layout with application-owned scrolling.
+ */
+export type ScrollMode = (typeof SCROLL_MODES)[number];
+export declare const DEFAULT_SCROLL_MODE: ScrollMode;
+export declare function clampScrollMode(v: unknown, fallback: ScrollMode): ScrollMode;
 export declare const DENSITY_MODES: readonly ["comfortable", "compact"];
 export type DensityMode = (typeof DENSITY_MODES)[number];
 export declare function clampDensity(v: unknown, fallback: DensityMode): DensityMode;
@@ -864,6 +875,8 @@ export interface PersistedConfig {
     maxRenderIntervalMs: number;
     /** Repaint only the frame rows that changed (tui-input-flicker-fix §5.1). */
     diffRender: boolean;
+    /** Native terminal scrolling vs the full-screen app layout (tui-native-terminal-scroll D1). */
+    scrollMode: ScrollMode;
     /** Wrap each repaint batch in DEC 2026 synchronized update (§5.1). */
     syncOutput: boolean;
     confirmTools: boolean;
@@ -1068,6 +1081,20 @@ export interface CliConfig {
      * with no compile error and no runtime error.
      */
     diffRender: boolean;
+    /**
+     * Native terminal scrolling vs the full-screen app layout
+     * (tui-native-terminal-scroll D1).
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `diffRender` above records: `runInteractive` reads `config.scrollMode`, where
+     * `config` is a `CliConfig`, so a key added to the persisted shape alone would
+     * round-trip through `config set` and never reach the screen plan.
+     *
+     * OPTIONAL ON THIS SHAPE ONLY so the many hand-built `CliConfig` fixtures in the
+     * test suite stay valid without edits (I-S9); `loadConfig` always sets it and
+     * the one reader (`runInteractive`) falls back to `DEFAULT_SCROLL_MODE`.
+     */
+    scrollMode?: ScrollMode;
     /** Wrap each repaint batch in DEC 2026 synchronized update (§5.1). */
     syncOutput: boolean;
     confirmTools: boolean;

package/dist/config/schema.js

@@ -69,6 +69,14 @@ export function clampTheme(v, fallback) {
 // ---------------------------------------------------------------------------
 // Density / hints (v0.4.0)
 // ---------------------------------------------------------------------------
+export const SCROLL_MODES = ['native', 'app'];
+export const DEFAULT_SCROLL_MODE = 'native';
+export function clampScrollMode(v, fallback) {
+    if (typeof v !== 'string')
+        return fallback;
+    const normalized = v.trim().toLowerCase();
+    return normalized === 'native' || normalized === 'app' ? normalized : fallback;
+}
 export const DENSITY_MODES = ['comfortable', 'compact'];
 export function clampDensity(v, fallback) {
     return v === 'comfortable' || v === 'compact' ? v : fallback;
@@ -970,6 +978,7 @@ export const DEFAULT_CONFIG = {
     renderGovernor: DEFAULT_RENDER_GOVERNOR,
     maxRenderIntervalMs: DEFAULT_MAX_RENDER_INTERVAL_MS,
     diffRender: DEFAULT_DIFF_RENDER,
+    scrollMode: DEFAULT_SCROLL_MODE,
     syncOutput: DEFAULT_SYNC_OUTPUT,
     confirmTools: false,
     toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,