@aragon-agent/cli 0.6.29 → 0.6.32

package/dist/cli.js

@@ -25,11 +25,11 @@ import { formatMigrationNotice, migrateLegacyState } from './config/migrate-lega
 import { formatHomeMigrationNotice, migrateToHome } from './config/migrate-home.js';
 import { migrateStateOutOfConfig } from './config/migrate-state-out-of-config.js';
 import { runHistoryCommand } from './config/history-commands.js';
-import { COMPACTION_CONFIG_SET_KEYS, FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS, RETRY_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, UPDATE_CONFIG_SET_KEYS, applyCompactionConfigSet, applyFastConfigSet, applyLogConfigSet, applyRetryConfigSet, applyTeamConfigSet, applyUpdateConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
+import { COMPACTION_CONFIG_SET_KEYS, FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS, RETRY_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, JOBS_CONFIG_SET_KEYS, UPDATE_CONFIG_SET_KEYS, applyCompactionConfigSet, applyFastConfigSet, applyLogConfigSet, applyRetryConfigSet, applyTeamConfigSet, applyJobsConfigSet, applyUpdateConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
 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,19 @@ 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 { SCROLLBACK_LIMITS } from './ui/scrollback/limits.js';
+import { createScrollbackWriter } from './ui/scrollback/scrollback-writer.js';
+import { probeAnchorSpaceBelow, setAnchorProbeDisabled } from './ui/scrollback/cursor-probe.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 +94,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 +205,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
@@ -393,8 +414,16 @@ function forceVtInputForThisConsole() {
  * "…" > out.txt`, `aragon config set`, and `aragon --version`, because the
  * interactive and headless paths are disjoint branches: `runInteractive()`
  * renders Ink, `runOneShot()` goes to `runHeadless()`, which never does.
+ *
+ * `async` FOR EXACTLY ONE `await` (tui-bottom-anchored-live-region P1-3): the
+ * cursor-position probe before the first frame. Both call sites are inside async
+ * Commander actions and use `void runInteractive(...)` — the session's lifetime is
+ * owned by `waitUntilExit()` and the four idempotent restore paths, never by the
+ * caller, so nothing awaits it. The `await` sits before the FIRST `stdout.write`
+ * and between it and `render()` there is no other suspension point, so making the
+ * function async introduces no new interleaving.
  */
-function runInteractive(flags, extras = {}) {
+async function runInteractive(flags, extras = {}) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         process.stderr.write('Interactive UI requires a TTY. Use -p "<prompt>", exec, or config list / config set.\n');
         process.exitCode = 2;
@@ -431,8 +460,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 +544,41 @@ 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 = () => {
+        // FIRST, before any bytes: the anchor probe must go quiet here (P1-6). A settle
+        // timer that survived this point would write `ESC[6n` at a terminal already handed
+        // back to the shell and nobody would strip the reply.
+        killAnchorProbe();
+        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 +619,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 +650,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,11 +663,16 @@ 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)
+        ? tryCreateStdinFilter(process.stdin, {
+            mouse: wantMouse,
+            paste: wantPaste,
+            enhancedKeys: wantEnhancedKeys,
+            // TOLD, never derived (I-A8): a native session strips the terminal's
+            // answer to `ESC[6n`, an `app` session is byte-identical to before.
+            cursorReport: plan.differ === 'scrollback',
+        }, (reason) => logger.warn('cli', 'stdin_filter_failed', { reason }), pasteBridge)
         : null;
     /**
      * THE ONE EXPRESSION EVERY MOUSE SITE READS (I-11 / D-17).
@@ -602,11 +686,140 @@ function runInteractive(flags, extras = {}) {
     const pasteOn = wantPaste && filter !== null;
     /** Same discipline: the translation runs only when a filter fronts Ink. */
     const enhancedKeysOn = wantEnhancedKeys && filter !== null;
-    const disposeStdinFilter = () => filter?.dispose();
+    // --- The bottom anchor's measurement pipeline (tui-bottom-anchored-live-region).
+    //
+    // Three pieces of host state, and every one of them exists to close a specific
+    // failure mode the writer cannot close by itself:
+    //
+    //  `anchorProbeDead` — I-A9 / P1-6. After `finalizeNativeScreen()`,
+    //    `disposeFrameWriter()`, `filter.dispose()` and the process `exit` hook, a
+    //    query must never be written again: it would hit a terminal already handed
+    //    back to the shell, where nothing strips the reply and the user's prompt gains
+    //    a literal `^[[12;1R`.
+    //  `anchorReprobeQueued` — P0-3. `invalidate()` is called from inside the writer's
+    //    `transform`, i.e. inside Ink's own `stdout.write`, so the request is pushed out
+    //    with `setImmediate` and everything inside that window is coalesced into one
+    //    query instead of becoming a probe storm on every foreign write.
+    //  `anchorReprobeTimer` — the 200 ms settle window (§4.6). A drag fires dozens of
+    //    resize events; one CPR each would fight the input channel for bandwidth and
+    //    make the region jitter.
+    let anchorProbeDead = false;
+    let anchorReprobeQueued = false;
+    let anchorReprobeTimer = null;
+    /** Stop measuring for the rest of the process. Idempotent; safe from any exit path. */
+    function killAnchorProbe() {
+        anchorProbeDead = true;
+        anchorReprobeQueued = false;
+        if (anchorReprobeTimer) {
+            clearTimeout(anchorReprobeTimer);
+            anchorReprobeTimer = null;
+        }
+        // The module-level switch is what makes a probe that is already in flight, or one
+        // whose timer fires during teardown, write zero bytes.
+        setAnchorProbeDisabled(true);
+    }
+    /** Ask for one measurement soon; coalesced, deferred out of Ink's write, and dead-safe. */
+    function requestAnchorProbe() {
+        if (anchorProbeDead || anchorReprobeQueued)
+            return;
+        anchorReprobeQueued = true;
+        setImmediate(() => {
+            anchorReprobeQueued = false;
+            if (anchorProbeDead)
+                return;
+            if (anchorReprobeTimer)
+                clearTimeout(anchorReprobeTimer);
+            anchorReprobeTimer = setTimeout(() => {
+                anchorReprobeTimer = null;
+                void runAnchorProbe();
+            }, SCROLLBACK_LIMITS.anchorReprobeDelayMs);
+            anchorReprobeTimer.unref?.();
+        });
+    }
+    /**
+     * One query, then consume the answer. Never throws and never fails the session: a
+     * terminal that does not answer simply keeps whatever anchor it had.
+     */
+    async function runAnchorProbe() {
+        const bridge = scrollbackBridge;
+        if (anchorProbeDead || !bridge || !filter)
+            return;
+        filter.setExpectingCursorReport(true);
+        let spaceBelow = null;
+        try {
+            spaceBelow = await probeAnchorSpaceBelow({
+                stdin: process.stdin,
+                stdout: process.stdout,
+                rows: () => process.stdout.rows,
+            });
+        }
+        catch (error) {
+            logger.warn('cli', 'scroll_anchor_probe_failed', {
+                rows: process.stdout.rows ?? null, reason: String(error),
+            });
+        }
+        finally {
+            filter.setExpectingCursorReport(false);
+        }
+        if (anchorProbeDead || spaceBelow === null)
+            return;
+        // `setAnchorSpaceBelow` records the re-probe count; the repaint is deferred for
+        // the same reason `requestRepaint` is (this can run while Ink is writing).
+        bridge.writer.setAnchorSpaceBelow(spaceBelow, 'probe');
+        logger.info('cli', 'scroll_anchor', {
+            source: 'probe', spaceBelow, rows: process.stdout.rows ?? null,
+        });
+        setImmediate(() => {
+            if (!anchorProbeDead)
+                frameWriter?.repaint();
+        });
+    }
+    /**
+     * THE ORDER HERE IS THE MECHANISM (P0-1 / I-A10). In canonical mode a terminal's
+     * reply to `ESC[6n` is line-buffered until a newline AND echoed, so the probe would
+     * time out on every Linux/macOS session while printing `^[[12;1R` on the screen.
+     * Raising raw first is also the direction `forceVtInputForThisConsole()` already
+     * goes (it raises the mode before Ink's own `setRawMode(true)` so libuv does not
+     * rewrite the console mode); a second raise is a no-op on both platforms.
+     *
+     * `false` means "no probe", never "no session": the caller falls back to the fill.
+     */
+    function raiseRawModeForProbe() {
+        if (typeof process.stdin.setRawMode !== 'function')
+            return false;
+        try {
+            process.stdin.setRawMode(true);
+        }
+        catch (error) {
+            logger.warn('cli', 'scroll_anchor_probe_failed', {
+                rows: process.stdout.rows ?? null, reason: `raw mode: ${String(error)}`,
+            });
+            return false;
+        }
+        // Ink lowers raw mode on unmount, which is the normal restore. A kill, a closed
+        // window or a crash never unmounts, so the same restore `forceVtInputForThisConsole`
+        // registers is registered here too; it is idempotent and cheap.
+        process.on('exit', () => {
+            try {
+                process.stdin.setRawMode(false);
+            }
+            catch {
+                /* Stream already torn down - nothing left to restore. */
+            }
+        });
+        return true;
+    }
+    const disposeStdinFilter = () => {
+        // Before the filter goes away: a probe settle timer must not fire into a stream
+        // nobody is stripping any more.
+        killAnchorProbe();
+        filter?.dispose();
+    };
     // --- Drag-select (tui-selection-and-scroll-follow §4.4). ------------------
     //
     // 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 +831,100 @@ 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()); },
+            // `invalidate()` calls this from inside `transform` (geometry lost), so the
+            // deferral is not optional here either (P0-3). The host coalesces it into one
+            // query per settle window and stops it for good once the screen is handed back.
+            requestAnchorProbe,
+        });
+        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();
+        // Same switch as `finalizeNativeScreen`: this is one of the four teardown paths.
+        killAnchorProbe();
+        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();
@@ -699,6 +953,49 @@ function runInteractive(flags, extras = {}) {
             vtInputSupported,
         })
         : NOOP_KEYBOARD_ENHANCEMENT;
+    // --- Measure the bottom of the screen, THEN build the first frame (§4.4 / §8.1).
+    //
+    // ORDER, ALL OF IT LOAD-BEARING:
+    //  1. the filter exists (it is the only thing that strips the reply — D5);
+    //  2. raw mode is raised BEFORE the query (P0-1 / I-A10);
+    //  3. the probe is awaited, and any failure is `null`;
+    //  4. `enterNativeScreen` writes the one-off fill only when the probe failed;
+    //  5. the measurement is handed to the writer before the first batch.
+    //
+    // This is the only `await` in the whole startup path and it is bounded by
+    // `anchorProbeTimeoutMs` (150 ms), which only a terminal that cannot answer pays.
+    let anchorSpaceBelow = null;
+    if (native && filter && scrollbackBridge) {
+        if (raiseRawModeForProbe()) {
+            filter.setExpectingCursorReport(true);
+            try {
+                anchorSpaceBelow = await probeAnchorSpaceBelow({
+                    stdin: process.stdin,
+                    stdout: process.stdout,
+                    rows: () => process.stdout.rows,
+                    // The first frame is waiting on this: hold the event loop, or a session with
+                    // nothing else referenced yet can exit before it draws anything.
+                    holdProcess: true,
+                });
+            }
+            catch (error) {
+                // The probe never throws by contract; this is the belt to that braces, and it
+                // must not be able to fail the launch.
+                logger.warn('cli', 'scroll_anchor_probe_failed', {
+                    rows: process.stdout.rows ?? null, reason: String(error),
+                });
+                anchorSpaceBelow = null;
+            }
+            finally {
+                filter.setExpectingCursorReport(false);
+            }
+        }
+        logger.info('cli', anchorSpaceBelow === null ? 'scroll_anchor_probe_failed' : 'scroll_anchor', {
+            source: anchorSpaceBelow === null ? 'fill' : 'probe',
+            spaceBelow: anchorSpaceBelow,
+            rows: process.stdout.rows ?? null,
+        });
+    }
     {
         // `mouse` here means "a mouse-parsing filter is installed", NOT "the user
         // wants mouse support" — see `AltScreenOptions`. `screen.ts` must never
@@ -710,17 +1007,31 @@ 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). DEC 2004, plus the
+            // one-off fill when the cursor could not be measured — before anything else,
+            // so the rows it scrolls away are the shell's, never this session's.
+            : enterNativeScreen(process.stdout, {
+                bracketedPaste: pasteOn,
+                anchorFillRows: anchorSpaceBelow === null && scrollbackBridge
+                    ? Math.max(0, (process.stdout.rows ?? 24) - 1)
+                    : 0,
+            });
+        // The measurement reaches the writer BEFORE the first batch, so frame one is
+        // already pinned. `fill` says "we know where the bottom is because we went there".
+        scrollbackBridge?.writer.setAnchorSpaceBelow(anchorSpaceBelow ?? 0, anchorSpaceBelow === null ? 'fill' : 'probe');
         // 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 +1149,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 +1177,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 +1186,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 +1267,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 +1474,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.
@@ -1218,6 +1535,11 @@ const CONFIG_SET_KEYS = new Set([
     // a script at all: `config list` enumerates the section dynamically and so
     // shows these keys whether they are here or not, while `config set` does not.
     ...COMPACTION_CONFIG_SET_KEYS,
+    // `jobs.*` keys are handled by `applyJobsConfigSet`, same reasoning again — and
+    // this spread is exactly why `JOBS_CONFIG_SET_KEYS ⊆ CONFIG_SET_KEYS` needs its
+    // own assertion: the static guard in `config.test.ts` matches LITERAL keys in
+    // this file, so a spread set is invisible to it (RV-P2-8).
+    ...JOBS_CONFIG_SET_KEYS,
 ]);
 /**
  * `aragon config set maxTokens <n|auto|default>`.
@@ -1357,6 +1679,17 @@ function runConfigSetValue(key, value) {
         process.stdout.write(`Set ${key} = ${String(merged.compaction[field])}\n`);
         return;
     }
+    const jobsPatch = applyJobsConfigSet(key, value);
+    if (jobsPatch) {
+        // Echoed from the STORED value, so `config set jobs.waitSeconds 1` prints 5
+        // and `jobs.waitSeconds 9999` prints 60 — the rule every section above
+        // states. It matters here too: `waitSeconds` is ALSO converged against the
+        // tool ceiling by I-4, so the stored value is the only honest answer.
+        const merged = updatePersistedConfig(jobsPatch);
+        const field = key.slice('jobs.'.length);
+        process.stdout.write(`Set ${key} = ${String(merged.jobs[field])}\n`);
+        return;
+    }
     const patch = {};
     switch (key) {
         case 'provider':
@@ -1401,6 +1734,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 +2126,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')
@@ -1822,14 +2159,14 @@ function buildProgram() {
             }
             return;
         }
-        runInteractive(flags, { initialPrompt: prompt });
+        void runInteractive(flags, { initialPrompt: prompt });
     });
     // aragon config [set <key> <value> | path]
     const configCmd = program
         .command('config')
         .description('Open the settings screen')
         .action(() => {
-        runInteractive(toFlags(program.opts()), { initialOverlay: 'settings' });
+        void runInteractive(toFlags(program.opts()), { initialOverlay: 'settings' });
     });
     configCmd
         .command('set <key> <value>')