@aragon-agent/cli 0.6.47 → 0.6.48

package/dist/ui/render-governor.js

@@ -1,78 +0,0 @@
-/**
- * Adaptive render governor (tui-render-performance L4 / R7). Pure, React-free.
- *
- * Neither the streaming coalescer nor Ink adapts when a frame overruns its
- * budget: the coalescer keeps its 33 ms timer, Ink keeps its 32 ms throttle, and
- * the event loop saturates. Renders then queue behind each other on Node's
- * single thread and KEYSTROKES QUEUE BEHIND THE RENDERS — which is what turns a
- * slow frame into an unresponsive terminal.
- *
- * The ladder is the safety net under L1/L2/L3, not a substitute for them: it
- * cannot make a frame cheaper, only rarer. Its job is to turn any residual
- * pathology from a freeze into a visibly slower but still interactive UI.
- *
- * I-L4-1 — the governor changes only HOW OFTEN the view updates. Never what is
- * dispatched, never the order, never the final state. `mergeDeltas` already
- * guarantees that a longer window is simply a larger merge and that any
- * non-delta action flushes the pending run first, so the same event sequence
- * must produce the same final `ViewState` at every rung
- * (`render-governor.test.ts`).
- */
-/** Coalescing intervals, in ms. Rung 0 is the pre-feature `COALESCE_MS`. */
-export const GOVERNOR_LADDER = [33, 50, 80, 125, 200, 320];
-/** Step up when a commit costs more than this fraction of the current interval. */
-export const GOVERNOR_UP_RATIO = 0.7;
-/**
- * Consecutive cheap frames required before stepping back down.
- *
- * Hysteresis, and it has to be asymmetric: stepping up on one expensive frame
- * and down on one cheap one would oscillate through the whole ladder while a
- * long answer streams past a couple of code blocks.
- */
-export const GOVERNOR_DOWN_STREAK = 8;
-export function initialGovernor() {
-    return { rung: 0, cheapStreak: 0 };
-}
-/** Highest rung reachable under `maxIntervalMs`. Always at least 0. */
-function topRung(maxIntervalMs) {
-    let top = 0;
-    for (let i = 1; i < GOVERNOR_LADDER.length; i += 1) {
-        if (GOVERNOR_LADDER[i] <= maxIntervalMs)
-            top = i;
-    }
-    return top;
-}
-/**
- * The coalescing interval for a state.
- *
- * Clamped to `maxIntervalMs` in BOTH directions: `maxRenderIntervalMs = 33`
- * flattens the ladder to one rung, which is the documented way to get the
- * pre-feature cadence without reaching for the kill switch.
- */
-export function intervalOf(state, maxIntervalMs) {
-    const ceiling = Number.isFinite(maxIntervalMs) ? maxIntervalMs : GOVERNOR_LADDER[0];
-    const rung = Math.min(Math.max(0, Math.floor(state.rung)), topRung(ceiling));
-    return Math.min(ceiling, GOVERNOR_LADDER[rung] ?? GOVERNOR_LADDER[0]);
-}
-/**
- * Fold one commit's cost into the ladder.
- *
- * `lastCommitMs` covers React reconciliation AND Ink's yoga layout, because Ink
- * computes layout in `onRender`, which React runs before layout effects. It does
- * NOT cover Ink's serialisation and the stdout write, which happen after. In
- * practice layout dominates, and the ladder's job is DIRECTION, not accuracy.
- */
-export function stepGovernor(state, lastCommitMs, maxIntervalMs) {
-    const top = topRung(Number.isFinite(maxIntervalMs) ? maxIntervalMs : GOVERNOR_LADDER[0]);
-    const rung = Math.min(Math.max(0, Math.floor(state.rung)), top);
-    const interval = intervalOf({ rung, cheapStreak: state.cheapStreak }, maxIntervalMs);
-    const cost = Number.isFinite(lastCommitMs) ? lastCommitMs : 0;
-    if (cost > interval * GOVERNOR_UP_RATIO) {
-        return { rung: Math.min(top, rung + 1), cheapStreak: 0 };
-    }
-    const streak = state.cheapStreak + 1;
-    if (streak >= GOVERNOR_DOWN_STREAK) {
-        return { rung: Math.max(0, rung - 1), cheapStreak: 0 };
-    }
-    return { rung, cheapStreak: streak };
-}

package/dist/ui/run-metrics.d.ts

@@ -1,23 +0,0 @@
-/** UI-only metrics. Feed only the existing generation-guarded main subscription. */
-export interface RunMetrics {
-    runId: number;
-    startedAt: number | null;
-    endedAt: number | null;
-    outputTokens: number;
-    usageKnown: boolean;
-}
-export interface RunMetricsEvent {
-    type: string;
-    usage?: {
-        outputTokens?: number;
-    };
-}
-export interface RunMetricsProjection {
-    elapsedMs: number;
-    tokPerSec: number;
-    speedKnown: boolean;
-}
-export declare function createRunMetrics(): RunMetrics;
-export declare function freezeRunMetrics(state: RunMetrics, now: number): RunMetrics;
-export declare function updateRunMetrics(state: RunMetrics, event: RunMetricsEvent, now: number): RunMetrics;
-export declare function projectRunMetrics(state: RunMetrics, now: number): RunMetricsProjection;

package/dist/ui/run-metrics.js

@@ -1,27 +0,0 @@
-export function createRunMetrics() {
-    return { runId: 0, startedAt: null, endedAt: null, outputTokens: 0, usageKnown: false };
-}
-export function freezeRunMetrics(state, now) {
-    if (state.startedAt === null || state.endedAt !== null)
-        return state;
-    return { ...state, endedAt: Number.isFinite(now) ? Math.max(state.startedAt, now) : state.startedAt };
-}
-export function updateRunMetrics(state, event, now) {
-    if (event.type === 'agent_start')
-        return { ...createRunMetrics(), runId: state.runId + 1,
-            startedAt: Number.isFinite(now) ? now : 0 };
-    if (state.startedAt === null || state.endedAt !== null)
-        return state;
-    if (event.type === 'agent_end' || event.type === 'error')
-        return freezeRunMetrics(state, now);
-    const output = event.usage?.outputTokens;
-    if (event.type !== 'turn_end' || output === undefined || !Number.isFinite(output) || output < 0)
-        return state;
-    return { ...state, outputTokens: Math.min(Number.MAX_VALUE, state.outputTokens + output), usageKnown: true };
-}
-export function projectRunMetrics(state, now) {
-    const end = state.endedAt ?? (Number.isFinite(now) ? now : state.startedAt ?? 0);
-    const elapsedMs = state.startedAt === null ? 0 : Math.max(0, end - state.startedAt);
-    const speedKnown = state.startedAt !== null && state.endedAt === null && state.usageKnown && elapsedMs > 500;
-    return { elapsedMs, speedKnown, tokPerSec: speedKnown ? state.outputTokens / (elapsedMs / 1000) : 0 };
-}

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

@@ -1,63 +0,0 @@
-/** Compatibility planner for former composer run rows. The current UI uses
- * status-layout.ts and interaction-hints.ts; keep this pure API for existing callers.
- */
-import type { StatusLayoutInput } from './layout/status-layout.js';
-/** Shared activity facts; omitted phase fields retain the legacy phrase behavior. */
-export interface RunActivity {
-    phase?: StatusLayoutInput['phase'];
-    outcome?: StatusLayoutInput['runOutcome'];
-    activeTool?: StatusLayoutInput['activeTool'];
-    /** Epoch ms the current run began - the phrase sequence's seed. */
-    startedAt: number;
-    /** `Date.now() - startedAt`, already computed by App's 200 ms ticker. */
-    elapsedMs: number;
-    /** The RAW config flag, never the widened one (single-spinner D-5). */
-    reducedMotion: boolean;
-    /** The tool currently in flight, if any. */
-    runningTool?: string;
-    /** A context compaction is in flight; outranks the tool name and the phrase. */
-    compacting?: boolean;
-    /**
-     * A BOUNDED WAIT IS IN FLIGHT (long-task-jobs §4.9).
-     *
-     * `Running job_wait` is a TOOL NAME; `Waiting on t3 (up to 30s)` is a STATE, and
-     * the state is what answers the user's two questions - what is it waiting for,
-     * and how long may that take. `elapsedSeconds`, when present (extended-job-wait),
-     * turns the sentence into a running clock - the 1 Hz transcript tick already
-     * causes that render, so no timer is added.
-     */
-    wait?: {
-        jobId: string;
-        upToSeconds: number;
-        elapsedSeconds?: number;
-    };
-}
-export interface RunRowPlanInput {
-    /** Width of the row's container (the composer's content columns). */
-    cols: number;
-    /** Spinner + space + label, in display columns (the label's natural width). */
-    labelCols: number;
-    /** Display width of each hint clause, most urgent first. */
-    hintClauseCols: readonly number[];
-    /** Display width of the separator between clauses (` · ` or ` - `). */
-    separatorCols: number;
-    /** Display width of the right-aligned mode chip; 0 = no chip. */
-    chipCols: number;
-}
-export interface RunRowPlan {
-    /** Columns the label may occupy; below its natural width it is ellipsized. */
-    labelCols: number;
-    /** How many leading clauses to show; 0 = none (defensive tier only). */
-    hintClauses: number;
-    /** Whether the chip fits after everything else. */
-    chip: boolean;
-}
-/** One leading space, matching the idle hint row's `'  '` indent. */
-export declare const RUN_ROW_LEAD = 1;
-/** Narrowest the label may be squeezed before a clause is dropped instead. */
-export declare const RUN_ROW_MIN_LABEL_COLS = 10;
-/** `steer` and `interrupt`: always whole while the row is enabled. */
-export declare const RUN_ROW_REQUIRED_CLAUSES = 2;
-/** Space kept between the last clause and the chip. */
-export declare const RUN_ROW_CHIP_GAP = 2;
-export declare function planRunRow(input: RunRowPlanInput): RunRowPlan;

package/dist/ui/run-status-row.js

@@ -1,54 +0,0 @@
-/** Compatibility planner for former composer run rows. The current UI uses
- * status-layout.ts and interaction-hints.ts; keep this pure API for existing callers.
- */
-/** One leading space, matching the idle hint row's `'  '` indent. */
-export const RUN_ROW_LEAD = 1;
-/** Narrowest the label may be squeezed before a clause is dropped instead. */
-export const RUN_ROW_MIN_LABEL_COLS = 10;
-/** `steer` and `interrupt`: always whole while the row is enabled. */
-export const RUN_ROW_REQUIRED_CLAUSES = 2;
-/** Space kept between the last clause and the chip. */
-export const RUN_ROW_CHIP_GAP = 2;
-/** Non-finite or negative widths collapse to 0 so no input can make the plan throw. */
-function width(value) {
-    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
-}
-/** Width of the first `count` clauses joined by `separator`. */
-function clausesWidth(clauses, count, separator) {
-    if (count <= 0)
-        return 0;
-    let total = separator * (count - 1);
-    for (let i = 0; i < count; i += 1)
-        total += clauses[i] ?? 0;
-    return total;
-}
-export function planRunRow(input) {
-    const inner = Math.max(0, width(input.cols) - RUN_ROW_LEAD);
-    const natural = width(input.labelCols);
-    const separator = width(input.separatorCols);
-    const chipCols = width(input.chipCols);
-    const clauses = input.hintClauseCols.map(width);
-    const total = clauses.length;
-    const labelOnly = {
-        labelCols: Math.min(natural, inner), hintClauses: 0, chip: false,
-    };
-    if (total < RUN_ROW_REQUIRED_CLAUSES)
-        return labelOnly;
-    // Tier 1: everything fits; the chip is the first thing to go.
-    const everything = natural + separator + clausesWidth(clauses, total, separator);
-    if (everything <= inner) {
-        const chip = chipCols > 0 && everything + RUN_ROW_CHIP_GAP + chipCols <= inner;
-        return { labelCols: natural, hintClauses: total, chip };
-    }
-    // Tier 2: drop clauses from the tail, but never below the required two; only the
-    // label may be squeezed (down to its minimum) to make the remaining clauses fit.
-    for (let kept = total - 1; kept >= RUN_ROW_REQUIRED_CLAUSES; kept -= 1) {
-        const available = inner - separator - clausesWidth(clauses, kept, separator);
-        if (available >= RUN_ROW_MIN_LABEL_COLS) {
-            return { labelCols: Math.min(natural, available), hintClauses: kept, chip: false };
-        }
-    }
-    // Tier 3 (defensive, below ~40 columns): the label alone. The status bar's own
-    // `Esc x2 interrupt` carries the urgent hint at this width.
-    return labelOnly;
-}

package/dist/ui/screen.d.ts

@@ -1,107 +0,0 @@
-/**
- * Alternate screen buffer take-over (spec §4.4).
- *
- * Why the alt-screen and not a clear: `\x1b[3J` destroys the user's scrollback
- * (their build log, their stack trace) — an unacceptable side effect for a
- * developer tool. The alt-screen is non-destructive: the main buffer is covered,
- * not erased, and comes back untouched on exit. It also parks the cursor at
- * (1,1), which gives the frame accounting in §4.2 a deterministic origin.
- *
- * CALL SITE IS LOAD-BEARING: only `cli.tsx::runInteractive()` may call this.
- * Hoisting it into `buildProgram()` / `parseAsync` would push `\x1b[?1049h`
- * into `aragon -p "…" > out.txt`, `aragon config set`, and `aragon --version`.
- */
-export interface ScreenHandle {
-    /** Leave the alternate screen. Idempotent — safe from every exit path. */
-    restore(): void;
-    /**
-     * Hand the mouse back to the terminal for this session, or take it again
-     * (tui-selection-and-scroll-follow §4.4.6 / G3). A no-op when this session
-     * never had a filter, and idempotent in both directions.
-     *
-     * This is the honest answer to "a user who wants their terminal's own
-     * selection", and it is reversible in one command instead of a restart plus a
-     * config edit (D-9).
-     */
-    setMouseCapture(on: boolean): void;
-}
-export interface AltScreenOptions {
-    /**
-     * TRUE MEANS "A MOUSE FILTER IS ALREADY INSTALLED", NOT "THE USER WANTS MOUSE
-     * SUPPORT" (invariant I-8).
-     *
-     * This module must never derive the value from config, env or platform.
-     * Enabling reporting without a filter in front of Ink does not degrade the
-     * feature — it types `[<0;12;5M` into the user's message on every click and
-     * every notch, which is strictly worse than the bug the feature fixes. The
-     * only caller is `cli.tsx::runInteractive`, and it passes `filter !== null`.
-     */
-    readonly mouse: boolean;
-    /**
-     * Whether to request motion reporting (`?1002h`) alongside the two modes
-     * above — i.e. whether drag-select is on for this session.
-     *
-     * SAME "ALREADY DECIDED ELSEWHERE" DISCIPLINE AS `mouse`: this module must
-     * never derive it from config. `cli.tsx` passes
-     * `mouseOn`, after the filter and VT capability have been resolved.
-     *
-     * Optional, defaulting to `false`, so every pre-existing caller and every
-     * pre-existing test emits exactly the bytes it emitted before (AC-8 / T-34).
-     */
-    readonly motion?: boolean;
-    /**
-     * TRUE MEANS "A FILTER THAT CONSUMES `\x1b[200~` IS ALREADY INSTALLED", NOT
-     * "the user wants paste support" — the same discipline `mouse` carries (I-1 /
-     * I-8).
-     *
-     * Enabling DEC 2004 without a filter in front of Ink does not degrade the
-     * feature: it types `[200~` and `[201~` into the user's message on EVERY paste,
-     * which is strictly worse than the bug being fixed. `cli.tsx` passes
-     * `pasteOn && mode === 'fullscreen'`, and NOT `filter !== null && config.paste`
-     * — after the gate widened, the handle no longer answers any question except
-     * "is a stream wrapped?" (D-17 / I-11).
-     *
-     * Optional, defaulting to `false`, so every pre-existing caller and every
-     * pre-existing assertion emits exactly the bytes it emitted before.
-     */
-    readonly bracketedPaste?: boolean;
-}
-/**
- * Enter the alternate screen. A non-TTY stdout is a hard no-op (tests, pipes,
- * CI) — writing screen-control sequences into a redirected file corrupts it.
- */
-export declare function enterAltScreen(stdout: NodeJS.WriteStream | undefined, options?: AltScreenOptions): ScreenHandle;
-export interface NativeScreenOptions {
-    /** Same discipline as `AltScreenOptions.bracketedPaste`: a filter that consumes it exists. */
-    readonly bracketedPaste?: boolean;
-    /**
-     * Line feeds to write BEFORE anything else, so the first batch starts from the
-     * bottom row of the screen (tui-bottom-anchored-live-region D4 rung 2).
-     *
-     * `cli.tsx` passes `rows - 1` when the cursor probe could not measure the
-     * position, and `0` when it did. Filling on a measured terminal would undo the
-     * measurement — and cost the page-flip this feature exists to avoid.
-     */
-    readonly anchorFillRows?: number;
-}
-/**
- * Native-scroll mode's counterpart of `enterAltScreen` (tui-native-terminal-scroll
- * §4.8 / D6): it deliberately does almost nothing. The main buffer stays in use so
- * the conversation lands in the terminal's own scrollback; there is no alternate
- * screen, no mouse reporting and no DEC 1007 save/restore.
- *
- * The only modes it touches are DEC 2004 (bracketed paste), which changes how input
- * is encoded and has nothing to do with scrolling, and — when the bottom anchor could
- * not be measured — the one-off fill that puts the cursor on the last row. Returns the
- * SAME `ScreenHandle` shape, so the four idempotent restore paths in `cli.tsx` need not
- * know which mode is running. A non-TTY stdout is a hard no-op, like `enterAltScreen`.
- *
- * ORDER IS LOAD-BEARING: the fill goes FIRST. Written after `?2004h` it would be the
- * same bytes, but written after any content it would scroll that content away.
- */
-export declare function enterNativeScreen(stdout: NodeJS.WriteStream | undefined, options?: NativeScreenOptions): ScreenHandle;
-/**
- * Replay the session summary into the normal buffer after `restore()`, so the
- * conversation does not evaporate along with the alternate screen.
- */
-export declare function writeExitTranscript(stdout: NodeJS.WriteStream | undefined, text: string): void;

package/dist/ui/screen.js

@@ -1,234 +0,0 @@
-/**
- * Alternate screen buffer take-over (spec §4.4).
- *
- * Why the alt-screen and not a clear: `\x1b[3J` destroys the user's scrollback
- * (their build log, their stack trace) — an unacceptable side effect for a
- * developer tool. The alt-screen is non-destructive: the main buffer is covered,
- * not erased, and comes back untouched on exit. It also parks the cursor at
- * (1,1), which gives the frame accounting in §4.2 a deterministic origin.
- *
- * CALL SITE IS LOAD-BEARING: only `cli.tsx::runInteractive()` may call this.
- * Hoisting it into `buildProgram()` / `parseAsync` would push `\x1b[?1049h`
- * into `aragon -p "…" > out.txt`, `aragon config set`, and `aragon --version`.
- */
-import { fillBytes } from './scrollback/writer-shapes.js';
-const ENTER_ALT = '\x1b[?1049h';
-const LEAVE_ALT = '\x1b[?1049l';
-const CURSOR_HOME = '\x1b[H';
-const CLEAR_VISIBLE = '\x1b[2J';
-/** Ink's log-update hides the cursor; a signal kill never gives it back. */
-const SHOW_CURSOR = '\x1b[?25h';
-/**
- * `?1000` is NORMAL TRACKING (press / release), the minimum mode that reports
- * wheel buttons; `?1006` selects SGR encoding so coordinates arrive as decimal
- * text rather than raw bytes above 0x7F that `setEncoding('utf8')` would mangle.
- *
- * `?1002` is BUTTON-EVENT TRACKING: motion is reported ONLY WHILE A BUTTON IS
- * HELD, which both scrollbar dragging and text selection need and costs exactly zero reports while the
- * pointer is idle. This comment used to lump it together with `?1003` and
- * dismiss both as "floods stdin on every pointer move" — true of `?1003`
- * (any-event), false of `?1002`, and the sentence had to go in the same commit
- * that started asking for it or it would stand as a documented reason not to
- * (AC-11 / D-10).
- *
- * Motion is enabled with mouse reporting, independently of text selection.
- * Disabling selection must still allow scrollbar gestures. The enable/disable
- * sequences remain paired for both values of this resolved capability.
- */
-const enableMouse = (motion) => `\x1b[?1000h${motion ? '\x1b[?1002h' : ''}\x1b[?1006h`;
-const disableMouse = (motion) => `\x1b[?1006l${motion ? '\x1b[?1002l' : ''}\x1b[?1000l`;
-/**
- * Alternate scroll (DEC private mode 1007) is what turns a wheel notch into a
- * burst of arrow keys, which `PromptInput` reads as prompt-history recall. With
- * mouse reporting ON we do not touch it at all: 1007 is defined to translate
- * the wheel only while no application is tracking the mouse, so `?1000h`
- * already suppresses it and a second mutation of shared state buys nothing.
- *
- * With mouse reporting OFF we turn it off so the wheel is INERT rather than
- * destructive — the fallback rung of the fail-safe ladder. But 1007 is GLOBAL
- * TERMINAL STATE THIS APP DOES NOT OWN, so it is SAVED and RESTORED (XTSAVE /
- * XTRESTORE) rather than force-set on the way out: a user who deliberately
- * disabled alternate scroll in their terminal config must not have it switched
- * back on by running `aragon --no-mouse` once. A terminal implementing neither
- * sequence ignores both, so the fallback is no worse than writing nothing.
- */
-const SAVE_ALT_SCROLL_OFF = '\x1b[?1007s\x1b[?1007l';
-const RESTORE_ALT_SCROLL = '\x1b[?1007r';
-/**
- * Bracketed paste (DEC private mode 2004) — the terminal wraps a paste in
- * `\x1b[200~` / `\x1b[201~`, which makes Tier 1 detection EXACT rather than a
- * heuristic on chunk shape (tui-paste-handling D-6 / L2).
- *
- * WHY THIS IS FORCED OFF ON EXIT RATHER THAN SAVED AND RESTORED (P1-8). DEC 1007
- * above is the same class of state — global, not ours — and gets the OPPOSITE
- * treatment, so the asymmetry has to be written down or the next reader will
- * "fix" the inconsistency:
- *
- *  - `\x1b[?2004r` on a terminal that does not implement XTSAVE is a NO-OP, which
- *    leaves 2004 ON. A shell that does not itself speak bracketed paste then
- *    shows a literal `[200~` on every paste until the user runs `reset` — the
- *    exact I-1 failure, arriving from the restore path.
- *  - Forcing `?2004l` has no such failure mode. Every shell that DOES use
- *    bracketed paste (bash >= 4.4 readline, zsh ZLE, fish, PSReadLine) re-arms it
- *    when it draws its next prompt, so the state the user sees after `aragon`
- *    exits is the state they had. Every shell that does not use it was already
- *    off.
- *
- * So: 1007 is saved because getting it wrong silently changes a preference; 2004
- * is forced because getting it wrong visibly breaks pasting, and the forced value
- * is the one every consumer re-establishes for itself.
- */
-const ENABLE_BRACKETED_PASTE = '\x1b[?2004h';
-const DISABLE_BRACKETED_PASTE = '\x1b[?2004l';
-const NOOP_HANDLE = { restore() { }, setMouseCapture() { } };
-function safeWrite(stdout, data) {
-    try {
-        stdout.write(data);
-    }
-    catch {
-        // A closed/broken stdout must never turn into a crash on the exit path.
-    }
-}
-/**
- * Enter the alternate screen. A non-TTY stdout is a hard no-op (tests, pipes,
- * CI) — writing screen-control sequences into a redirected file corrupts it.
- */
-export function enterAltScreen(stdout, options = { mouse: false }) {
-    if (!stdout || !stdout.isTTY || typeof stdout.write !== 'function')
-        return NOOP_HANDLE;
-    const mouse = options.mouse === true;
-    const motion = options.motion === true;
-    const bracketedPaste = options.bracketedPaste === true;
-    safeWrite(stdout, ENTER_ALT +
-        CLEAR_VISIBLE +
-        CURSOR_HOME +
-        (mouse ? enableMouse(motion) : SAVE_ALT_SCROLL_OFF) +
-        (bracketedPaste ? ENABLE_BRACKETED_PASTE : ''));
-    /**
-     * THE CURRENT capture state, not the one the session started in (I-10).
-     *
-     * `restore()` used to close over the immutable `mouse` boolean. After
-     * `/mouse` exists that boolean is no longer the truth, and the exit path is
-     * the one place where being wrong leaves the user's shell broken until they
-     * run `reset`.
-     */
-    let captured = mouse;
-    /**
-     * Whether OUR `XTSAVE` of DEC 1007 is outstanding.
-     *
-     * `XTSAVE` HAS ONE SLOT PER MODE, so the save and the restore must stay
-     * STRICTLY PAIRED: an `off` that saved while our own disable was already in
-     * effect would save OUR value, and the following restore would hand the user
-     * back a preference that was never theirs — permanently.
-     */
-    let savedAltScroll = mouse ? false : true;
-    const setMouseCapture = (on) => {
-        // IT MUST NOT TOUCH DEC 2004 (I-16 / P2-7). `/mouse off` releases the
-        // pointer; it says nothing about pasting, and a user who turns the mouse off
-        // mid-session to select text with their terminal must not silently lose Tier
-        // 1 detection as well. The two modes are written by different call sites and
-        // unwound by different flags in `restore()`.
-        //
-        // A session that never installed a filter has nothing to release, and
-        // enabling reporting without one types `[<0;12;5M` into the user's message
-        // on every click (I-8). It stays a no-op in both directions.
-        if (!mouse || on === captured)
-            return;
-        captured = on;
-        if (on) {
-            // Alternate scroll goes back to the user's own preference BEFORE reporting
-            // resumes, so the two never overlap in the "both disabled" state.
-            safeWrite(stdout, (savedAltScroll ? RESTORE_ALT_SCROLL : '') + enableMouse(motion));
-            savedAltScroll = false;
-            return;
-        }
-        // DEC 1007 IS THE HALF THAT MUST NOT BE DROPPED (P1-1). With reporting off,
-        // alternate scroll turns every wheel notch back into a burst of arrow keys,
-        // which `PromptInput` reads as prompt-history recall — replacing the user's
-        // draft with an old prompt. A `/mouse off` that wrote only the mouse
-        // sequences would hand that defect back on request, in the one command whose
-        // entire purpose is to make things better. Saved rather than force-set, so a
-        // user who deliberately disabled alternate scroll keeps their choice.
-        safeWrite(stdout, disableMouse(motion) + SAVE_ALT_SCROLL_OFF);
-        savedAltScroll = true;
-    };
-    let restored = false;
-    return {
-        restore() {
-            if (restored)
-                return;
-            restored = true;
-            // Mouse reporting is disabled BEFORE leaving the alternate screen (I-2).
-            // This handle is what all four exit paths converge on — `process.on
-            // ('exit')`, the crash handler's `setScreenRestore`, the signal
-            // terminator, and `waitUntilExit()` — which is why the sequences live
-            // here and not in `App.tsx`, a component that is on none of them.
-            // Leaving reporting on prints `[<0;12;5M` in the user's shell on every
-            // click, forever, until they run `reset`.
-            //
-            // IT UNWINDS THE CURRENT STATE (I-10): `captured` and `savedAltScroll` are
-            // read here rather than the startup `mouse` flag, so a session that ran
-            // `/mouse off` exits with exactly one outstanding save restored and
-            // nothing left reporting.
-            //
-            // DEC 2004 IS UNWOUND FROM THE STARTUP FLAG, not from a runtime one, and
-            // that is deliberate: `setMouseCapture` never touches it (I-16), so this
-            // session either enabled it at entry or never did.
-            const tail = (captured ? disableMouse(motion) : '') +
-                (bracketedPaste ? DISABLE_BRACKETED_PASTE : '') +
-                (savedAltScroll ? RESTORE_ALT_SCROLL : '');
-            safeWrite(stdout, tail + SHOW_CURSOR + LEAVE_ALT);
-        },
-        setMouseCapture,
-    };
-}
-/**
- * Native-scroll mode's counterpart of `enterAltScreen` (tui-native-terminal-scroll
- * §4.8 / D6): it deliberately does almost nothing. The main buffer stays in use so
- * the conversation lands in the terminal's own scrollback; there is no alternate
- * screen, no mouse reporting and no DEC 1007 save/restore.
- *
- * The only modes it touches are DEC 2004 (bracketed paste), which changes how input
- * is encoded and has nothing to do with scrolling, and — when the bottom anchor could
- * not be measured — the one-off fill that puts the cursor on the last row. Returns the
- * SAME `ScreenHandle` shape, so the four idempotent restore paths in `cli.tsx` need not
- * know which mode is running. A non-TTY stdout is a hard no-op, like `enterAltScreen`.
- *
- * ORDER IS LOAD-BEARING: the fill goes FIRST. Written after `?2004h` it would be the
- * same bytes, but written after any content it would scroll that content away.
- */
-export function enterNativeScreen(stdout, options = {}) {
-    if (!stdout || !stdout.isTTY || typeof stdout.write !== 'function')
-        return NOOP_HANDLE;
-    const bracketedPaste = options.bracketedPaste === true;
-    const fillRows = Math.max(0, Math.floor(options.anchorFillRows ?? 0));
-    const head = (fillRows > 0 ? fillBytes(fillRows) : '') +
-        (bracketedPaste ? ENABLE_BRACKETED_PASTE : '');
-    if (head.length > 0)
-        safeWrite(stdout, head);
-    let restored = false;
-    return {
-        restore() {
-            if (restored)
-                return;
-            restored = true;
-            // 2004 is FORCED off rather than saved/restored, for the reason recorded at
-            // `DISABLE_BRACKETED_PASTE`. The cursor is shown again because Ink's
-            // log-update hides it and a signal kill never gives it back.
-            safeWrite(stdout, (bracketedPaste ? DISABLE_BRACKETED_PASTE : '') + SHOW_CURSOR);
-        },
-        // No mouse reporting in this mode: nothing to hand back or take again.
-        setMouseCapture() { },
-    };
-}
-/**
- * Replay the session summary into the normal buffer after `restore()`, so the
- * conversation does not evaporate along with the alternate screen.
- */
-export function writeExitTranscript(stdout, text) {
-    if (!stdout || typeof stdout.write !== 'function')
-        return;
-    if (text.length === 0)
-        return;
-    safeWrite(stdout, text.endsWith('\n') ? text : `${text}\n`);
-}