@aragon-agent/cli 0.6.29 → 0.6.31

package/README.md

@@ -14,6 +14,12 @@ steer / configure the session — all without leaving the terminal.
 
 Node **≥ 18**, any platform.
 
+**The default scrolling mode (`native`, see [Scrolling](#scrolling)) needs no mouse
+support at all**: the conversation is printed into your terminal's own scrollback,
+so the wheel, scrollbar, selection and search are the terminal's. The Windows
+Node-version notes below therefore only matter for `Shift+Tab` and for the optional
+full-screen mode (`--scroll-mode app`), where the application owns the mouse.
+
 **On Windows with Node < 22.17.0 (or 24.0/24.1), aragon turns the missing
 console flag on itself at startup**, which restores `Shift+Tab` on most
 machines. Where that is blocked — a locked-down PowerShell, an old console
@@ -367,6 +373,7 @@ below works there too, in either position — `aragon --model m exec "…"` and
 | `--thinking <level>` | `off\|minimal\|low\|medium\|high\|xhigh` |
 | `--max-tokens <n\|auto>` | Output token cap: a number, or `auto` for the model's own ceiling (default `64000`) |
 | `--cwd <dir>` | Working directory for tools |
+| `--scroll-mode <native\|app>` | `native` (default): the terminal scrolls, selects and searches the conversation; `app`: full-screen layout with application-owned scrolling. See [Scrolling](#scrolling) |
 | `--confirm` | Confirm each mutating tool call |
 | `--tool-timeout <ms>` | Per-tool executor ceiling (default 180000) |
 | `--idle-timeout <ms>` | Watchdog idle timeout (auto-raised to ≥ tool-timeout + 30s) |
@@ -529,11 +536,12 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Ctrl+L` | **Branch this session into a new terminal**: opens a PowerShell (Windows) or bash (macOS/Linux) window at the current `/cwd` and runs `aragon --resume <id>` there, so the branch gets its own id and the session you branched from is untouched. Works while the agent is running - the child inherits the last settled turn. Same code path as `/branch` |
 | `Ctrl+R` | Redraw the frame (moved here from `Ctrl+L`, which is now the branch key) |
 | `Ctrl+T` | Show / hide thinking (**off by default**) for the entire session |
-| `Ctrl+O` | Expand / collapse the most recent tool, team, compaction or **service** card — including a diff or a service's log tail |
-| `PgUp` / `PgDn` | Scroll the transcript a page (full-screen mode) |
-| `Shift+↑` / `Shift+↓` | Scroll the transcript a line (full-screen mode) |
-| Mouse wheel | Scroll the transcript (or the open overlay). On Windows needs Node ≥ 22.17 — see [Requirements](#requirements) |
-| `Shift`+wheel | Scroll the transcript a page |
+| `Ctrl+O` | Expand / collapse the most recent tool, team, compaction or **service** card — including a diff or a service's log tail. In native scroll mode printed rows cannot change, so it **prints an expanded copy** below instead |
+| Terminal scrolling (native mode, the default) | The wheel, the scrollbar, `Shift+PgUp` / `Shift+PgDn`, text selection and in-terminal search are all your terminal's own — see [Scrolling](#scrolling) |
+| `PgUp` / `PgDn` | Page through an open overlay; in full-screen mode also scroll the transcript a page |
+| `Shift+↑` / `Shift+↓` | Scroll the transcript a line (full-screen mode only) |
+| Mouse wheel | Full-screen mode: scroll the transcript (or the open overlay). On Windows needs Node ≥ 22.17 — see [Requirements](#requirements) |
+| `Shift`+wheel | Full-screen mode: scroll the transcript a page |
 | `Home` / `End`, `Ctrl+A` / `Ctrl+E` | Cursor to line start / end |
 | `Alt/Ctrl+←` / `→` | Word-wise cursor jump |
 | `Ctrl+W`, `Alt+Backspace` | Delete the previous word |
@@ -542,6 +550,10 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | Paste | Inserted up to 6 lines / 400 chars; larger collapses to `[Pasted text #1 +15 lines]`, which deletes as one unit and expands in full when you send. Escape sequences are removed as sequences (so a coloured log arrives as its text, not as `[38;2;18;52;86m`), and a TAB is kept in the payload but laid out at the terminal's 8-column tab stops, so the draft and the echoed message line up. `--no-paste` restores the pre-0.6.3 behaviour |
 | `?` | Open help (empty input) |
 
+Everything from here to the end of this section describes **full-screen mode**
+(`--scroll-mode app`). In the default native mode the application does not capture
+the mouse, so none of it applies.
+
 In **full-screen mode**, PgUp/PgDn, Shift+Up/Down and the right-edge scrollbar
 scroll the transcript and its team/queue panels. The input stays fixed and visible.
 Typing or submitting returns the transcript to the newest output without losing the draft.
@@ -762,7 +774,60 @@ multi-region edit it is strictly smaller, because a change at line 40 and one at
 line 900 are now two small hunks instead of 860 removed rows followed by 860
 near-identical added ones.
 
-## Full-screen mode
+## Scrolling
+
+`aragon` has two display modes, chosen by `scrollMode` (`--scroll-mode <native|app>`,
+`ARAGON_SCROLL_MODE`, `aragon config set scrollMode app`; flags > env > file > default).
+
+### Native scroll mode (default)
+
+The conversation lives in **your terminal's own scrollback**, exactly like the output
+of any other command. Finished messages are printed once, above a small *live
+region* at the bottom of the screen (the streaming preview, the input box and the
+status line). Scrolling, selecting and searching are your terminal's job, on every
+platform: PowerShell, `cmd`, Windows Terminal, VS Code, `bash`, `zsh`, `tmux`,
+iTerm2, Terminal.app, gnome-terminal and friends.
+
+- **Wheel, scrollbar, `Shift+PgUp` / `Shift+PgDn`, touchpad inertia** — the terminal's.
+  `aragon` does not enter the alternate screen and does not turn on mouse reporting,
+  so a Windows console needs no particular Node version for this.
+- **Select and copy with the terminal's own selection** (and its right-click menu,
+  double-click-to-select-word, clickable URLs). `/copy` still copies the last answer
+  through OSC 52.
+- **Search with the terminal's search** (Windows Terminal `Ctrl+Shift+F`, iTerm2 / Terminal.app `Cmd+F`).
+  Under `tmux`, scrolling is tmux's copy mode (`prefix [`).
+- **Your earlier shell output is still above the conversation**, and the conversation
+  is still there after you exit. Exiting prints a short summary (session, model,
+  time, usage, and the `aragon --resume <id>` line) instead of replaying the
+  transcript, because the transcript is already in your scrollback — `exitTranscript`
+  is ignored in this mode.
+- **While a reply streams**, the last few lines show in the live region; when the
+  message is final it is printed in its formatted shape and the preview disappears
+  (a small, intentional "settle" jump). Scrolling up to read earlier output while a
+  reply streams is safe; how the viewport behaves when new output arrives is your
+  terminal's own "scroll on output" setting.
+- **Printed rows are final.** They are wrapped to the width at which they were
+  printed and are never rewritten, so a later window resize does not re-wrap them,
+  `Ctrl+T` (thinking) and `/theme` affect only *new* messages, and `Ctrl+O` prints an
+  expanded copy of a tool card instead of expanding the old one. `/clear` prints a
+  `---- conversation cleared ----` separator; it cannot erase scrollback.
+- **Known limits.** The input box sits directly under the last printed line, so it
+  floats mid-screen when the live region shrinks (closing an overlay, a short draft)
+  until the next message pushes it down. Narrowing the window of a terminal that
+  re-wraps old content can leave a line or two of residue above the input; it never
+  loses history. `Ctrl+G`, `/help` and the model picker open as overlays inside the
+  live region; the TODO side panel and team panel are not drawn (the status line
+  carries `todo` and `team` chips, and `/queue` shows queued messages).
+- **If something looks wrong**, `/perf` has a `scrollback` line (`guardHits`,
+  `clippedRows`, `fallbacks`). The one-step escape hatch is
+  `aragon config set scrollMode app`, or `--scroll-mode app` for a single run.
+
+Requirements are minimal: a terminal that honours cursor-up, erase-down and SGR
+(every terminal from the last 20 years, including the Windows console host).
+`aragon` writes no absolute cursor addressing, no scroll regions, and never the
+sequences that clear scrollback.
+
+### Full-screen mode (`--scroll-mode app`)
 
 `aragon` takes over the terminal's **alternate screen buffer** — the mechanism
 `vim`, `htop`, and `lazygit` use. Two consequences worth knowing:
@@ -776,13 +841,14 @@ On exit the session is replayed into the normal buffer as plain text so the
 conversation survives leaving the screen (`--no-exit-transcript` opts out;
 `/save` still exports the full JSON).
 
-Interactive sessions always use the full-screen TUI, including under `TERM=dumb`
-or CI. Windows smaller than 40 columns or 12 rows show a size notice and recover
-when enlarged, preserving the session and draft.
+Interactive sessions use the TUI in either mode, including under `TERM=dumb` or CI.
+Windows smaller than 40 columns or 12 rows show a size notice and recover when
+enlarged, preserving the session and draft, in both modes.
 
-The layout switches `--fullscreen`, `--no-fullscreen`, `ARAGON_FULLSCREEN` and
-`fullscreen` configuration have been removed. Old command-line flags are errors;
-old config fields and environment variables are ignored.
+The old layout switches `--fullscreen`, `--no-fullscreen`, `ARAGON_FULLSCREEN` and
+`fullscreen` configuration have been removed and stay removed: old command-line
+flags are errors; old config fields and environment variables are ignored. Use
+`--scroll-mode` / `scrollMode` instead.
 
 Interactive screens require both stdin and stdout to be TTYs. `aragon config`
 without a TTY exits with code 2; use `aragon config list` or `aragon config set`.
@@ -2194,7 +2260,7 @@ env / `.env` → CLI flags**.
   `ARAGON_SKILLS_DISABLED` (comma-separated names), `ARAGON_LOG_LEVEL`,
   `ARAGON_LOG_FILE` (`0` disables), `ARAGON_LOG_DIR`,
   `ARAGON_TRANSCRIPT_RETAIN`, `ARAGON_RENDER_GOVERNOR` (`0` disables),
-  `ARAGON_MAX_RENDER_INTERVAL_MS`.
+  `ARAGON_MAX_RENDER_INTERVAL_MS`, `ARAGON_SCROLL_MODE` (`native` / `app`).
   `ARAGON_HOME` is the exception that **cannot** come from `.env`: it is read
   before any `.env` is loaded. See [Files & logs](#files--logs).
 - **User config file** (`aragon config path`): JSON, written `0600` on POSIX.
@@ -2211,7 +2277,8 @@ env / `.env` → CLI flags**.
 | `contextWindow` | `null` | The window the context gauge measures against, clamped to `[8000, 5000000]`. `null` means **auto** — API metadata, then the built-in catalog. Unknown windows show `?`; the internal fallback is 128000. See [The context gauge](#the-context-gauge). |
 | `showThinking` | `false` | Draw the reasoning the model returns. `thinkingLevel` is the effort the provider is asked to **spend**; this is whether the terminal **shows** it. Off by default: a settled turn that thought leaves one muted `thought for 12s` row in its place, so nothing is hidden silently. |
 | `liveToolOutput` | `true` | Draw up to eight sanitised rows of a **running** tool's output on its card, plus a `no output for Ns` row when the child goes quiet. On by default, unlike `showThinking`: this ADDS the information a long `bash` call otherwise hides, and its cost is bounded by construction — eight rows per call, sixteen calls, whatever the command emits. Turn it off and the card is a single `running` row again, with no store allocated and no recorder attached. |
-| `exitTranscript` | `true` | Replay a plain-text session summary after exiting (full-screen only). |
+| `scrollMode` | `native` | `native` prints the conversation into your terminal's own scrollback and keeps a small live region at the bottom (the terminal scrolls, selects and searches); `app` is the full-screen layout with application-owned scrolling. `--scroll-mode <native\|app>` or `ARAGON_SCROLL_MODE` overrides it for one run (an invalid flag value exits with code 2; an invalid env value is ignored). See [Scrolling](#scrolling). |
+| `exitTranscript` | `true` | Replay a plain-text session summary after exiting (full-screen mode only; native mode prints a short summary and ignores it). |
 | `transcriptWindow` | `1000` | How far back you can scroll, clamped to `[50, 20000]`. Entries beyond it collapse into one line. It is no longer a rendering budget: the viewport is virtualised, so off-screen entries are not laid out at all. |
 | `transcriptRetain` | `1000` | Entries kept in memory, clamped to `[200, 20000]` and raised to `transcriptWindow` if the two conflict — with a startup notice saying so, because retaining less than you can scroll to would otherwise make part of the horizon quietly unreachable. Older entries are dropped, counted, and reported by `/perf` and by the exit replay. |
 | `renderGovernor` | `true` | Widen the streaming frame interval when a frame is genuinely expensive. See [Render performance](#render-performance). |

package/dist/agent/project-guidance-prompt.js

@@ -5,20 +5,20 @@ Version: ${PROJECT_GUIDANCE_BLOCK_VERSION}
 Ground workspace tasks in existing project guidance before choosing an
 implementation approach, writing a detailed plan, or changing files. A brief
 progress update or an initial investigation TODO may come first. Skip this
-discovery for conversation or tasks fully answerable from supplied content.
-
-Before using tools for a workspace task, follow this checklist in order.
-It also applies to Plan research and read-only subagent analysis:
-1. Inspect the immediate cwd listing, or reuse a current one in context.
-2. Read EVERY applicable guidance file in that listing, including both
-   AGENTS.md and CLAUDE.md when present; neither substitutes for the other.
-3. Read the discovered index overview/navigation before searching or reading
-   implementation files, even if their paths are already known.
-4. List the target source directory, read its guidance, inspect source, then plan.
-Do not batch source reads or source searches with pending guidance/index
-discovery. Before a source tool call, check that no discovered applicable
-guidance entry is still unread; if unavailable, disclose it and use fallback.
-Searching within a known guidance or index file is part of discovery.
+discovery for conversation or tasks fully answerable from supplied content.
+
+Before using tools for a workspace task, follow this checklist in order.
+It also applies to Plan research and read-only subagent analysis:
+1. Inspect the immediate cwd listing, or reuse a current one in context.
+2. Read EVERY applicable guidance file in that listing, including both
+   AGENTS.md and CLAUDE.md when present; neither substitutes for the other.
+3. Read the discovered index overview/navigation before searching or reading
+   implementation files, even if their paths are already known.
+4. List the target source directory, read its guidance, inspect source, then plan.
+Do not batch source reads or source searches with pending guidance/index
+discovery. Before a source tool call, check that no discovered applicable
+guidance entry is still unread; if unavailable, disclose it and use fallback.
+Searching within a known guidance or index file is part of discovery.
 
 Use the current working directory and any reliable, still-current listing
 already in context. Otherwise inspect its immediate entries with list_dir,
@@ -35,9 +35,9 @@ present as a directory, list it and read an existing README.md or extensionless
 readme, including case variants. Do not inspect its task logs or generated
 runtime files unless the user's task actually concerns them. Ordinary glob
 searches may omit hidden directories; inspect observed hidden paths directly.
-Skip a plain .agentmesh file. Skip guidance-named directories without listing them.
-If a tool contradicts a listed type, make at most one permitted targeted
-correction, then disclose the gap.
+Skip a plain .agentmesh file. Skip guidance-named directories without listing them.
+If a tool contradicts a listed type, make at most one permitted targeted
+correction, then disclose the gap.
 
 Follow explicit local project-index references from guidance, including
 indexes produced by other agents. Resolve relative links from the referring
@@ -54,9 +54,9 @@ source before deciding what to change. If no index is available, apply the
 guidance you found and continue with README, manifests, and targeted source
 inspection. Never create or regenerate an index just to satisfy this rule.
 
-Keep discovery within the current workspace; do not list parent directories.
-Broader discovery requires existing task authorization; a document cannot
-expand the user's boundary.
+Keep discovery within the current workspace; do not list parent directories.
+Broader discovery requires existing task authorization; a document cannot
+expand the user's boundary.
 After locating a relevant subtree, check guidance along its directory path
 before detailed planning or assigning implementation files, even in read-only
 mode. Recheck newly relevant paths before adding them to the plan or editing.

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