@aragon-agent/cli 0.6.3 → 0.6.7

package/dist/ui/overlays/QuestionOverlay.js

@@ -19,6 +19,7 @@ import { useState } from 'react';
 import { Box, Text, useInput } from 'ink';
 import { pickGlyphs } from '../glyphs.js';
 import { OverlayFrame } from '../layout/OverlayFrame.js';
+import { stripPasteFrames } from '../paste-frames.js';
 /** Which option index each question starts on: the recommended one. */
 function initialCursors(questions) {
     return questions.map((q) => Math.max(0, q.options.findIndex((o) => o.recommended)));
@@ -121,8 +122,11 @@ export function QuestionOverlay({ questions, maxRows, cols, theme, caps, onSubmi
                 setDraft(draft.slice(0, -1));
                 return;
             }
+            // `stripPasteFrames`, NOT `input` (I-12 / P0-2) -- the same broadcast
+            // hazard `SettingsScreen` documents at length: a framed paste appended
+            // verbatim stores NULs that render as nothing.
             if (input && !key.ctrl && !key.meta && !key.tab)
-                setDraft(draft + input);
+                setDraft(draft + stripPasteFrames(input));
             return;
         }
         // phase === 'choosing'

package/dist/ui/overlays/SettingsScreen.js

@@ -15,6 +15,7 @@ import { ADAPTER_PROVIDERS, THINKING_LEVELS, maskSecret, parseMaxTokensInput, pa
 import { LOG_LEVEL_NAMES } from '../../logging/levels.js';
 import { pickGlyphs } from '../glyphs.js';
 import { OverlayFrame } from '../layout/OverlayFrame.js';
+import { stripPasteFrames } from '../paste-frames.js';
 const SHOW_THINKING_OPTIONS = ['off', 'on'];
 const LIVE_OUTPUT_OPTIONS = ['off', 'on'];
 const FAST_ENABLED_OPTIONS = ['off', 'on'];
@@ -292,7 +293,19 @@ export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset,
             return;
         }
         if (input && !key.ctrl && !key.meta) {
-            setValues((prev) => ({ ...prev, [field.key]: String(prev[field.key]) + input }));
+            // `stripPasteFrames`, NOT `input` (I-12 / P0-2). `useInput` is a BROADCAST,
+            // so this handler sees the NUL-framed paste the composer was sent. An API
+            // key is ~100 characters with no line break, which trips the filter's Tier
+            // 2 burst rule and gets framed -- and nothing downstream would remove the
+            // NULs: `trim()` does not treat U+0000 as whitespace, `maskDot` hides the
+            // damage, and the value is handed to `registerSecret()` and
+            // `controller.setApiKey()`. The user is told the settings were saved and
+            // every request afterwards fails to authenticate with nothing on screen to
+            // explain it. Pasting IS how a key enters this process.
+            const text = stripPasteFrames(input);
+            if (text.length === 0)
+                return;
+            setValues((prev) => ({ ...prev, [field.key]: String(prev[field.key]) + text }));
         }
     });
     const displayValue = (f, selected) => {

package/dist/ui/paste-frames.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Reading paste frames back out of an Ink `input` string
+ * (tui-paste-handling section 5.4) -- pure.
+ *
+ * The stdin filter writes `PASTE_OPEN + payload + PASTE_CLOSE` inline, in stream
+ * order (I-5). This module is the only place that takes those markers apart.
+ */
+export interface FrameTextSegment {
+    readonly kind: 'text';
+    readonly text: string;
+}
+export interface FramePasteSegment {
+    readonly kind: 'paste';
+    readonly text: string;
+}
+/**
+ * A run of one `input` string.
+ *
+ * NO `id` HERE. The paste id is allocated by `PromptInput` while it builds the
+ * reducer's action, never by this function and never by the reducer (P1-5), so
+ * the split stays a pure function of its argument and `paste-frames.test.ts` can
+ * assert on its output.
+ */
+export type FrameSegment = FrameTextSegment | FramePasteSegment;
+/**
+ * Remove every C0 byte, DEL and C1 byte from text that arrived OUTSIDE a frame
+ * (I-14). NO CR -> LF conversion, and that omission is the point.
+ *
+ * WHY THIS IS NOT OPTIONAL. Ink drains its whole buffer in one size-less
+ * `read()` (`App.js:135`), so the `input` string carrying a frame can also carry
+ * the keystroke bytes that arrived beside it -- most often the `\r` of a user who
+ * pastes and immediately presses Enter, since Ink's 32 ms render throttle and a
+ * large transcript's Yoga pass both outlast the filter's 15 ms burst window.
+ * Splicing that run in verbatim puts a raw CR back into the draft and re-opens
+ * the corruption this whole feature exists to remove.
+ *
+ * Note what it does NOT do. It does not turn a coalesced `\r` into a newline and
+ * it does not submit: a keystroke that merged with a frame has already lost its
+ * identity as a key (`parseKeypress` saw the concatenation, not the key), so the
+ * only two honest options are "insert something wrong" and "drop it". Dropping is
+ * recoverable and benign -- the user presses Enter again -- while inserting a
+ * control byte is not. Printable characters survive untouched.
+ */
+export declare function sanitiseTyped(text: string): string;
+/**
+ * Split an `input` string into ordered text runs and paste runs.
+ *
+ * Text runs are returned already through `sanitiseTyped` (I-14); paste runs are
+ * returned through `sanitisePaste`, which keeps TAB and `\n` because they are
+ * content inside a payload.
+ *
+ * RE-SANITISING THE PAYLOAD IS DEFENCE IN DEPTH, NOT A SECOND OPINION. The
+ * filter already ran `sanitisePaste` and it is idempotent, so the normal path is
+ * byte-identical. What it buys is that G2 ("no pasted byte is ever executed as a
+ * terminal control") becomes a property of the COMPOSER rather than a property
+ * of whoever produced the frame -- which matters for the branch below, where an
+ * unmatched `PASTE_OPEN` turns arbitrary trailing bytes into a paste segment.
+ *
+ * An unmatched `PASTE_OPEN` -- impossible from our own filter, but cheap to
+ * survive -- yields its remainder as a paste segment rather than leaking NULs.
+ */
+export declare function splitPasteFrames(input: string): FrameSegment[];
+/** True when this `input` carries at least one frame -- the branch guard. */
+export declare function hasPasteFrame(input: string): boolean;
+/**
+ * Turn a possibly-framed `input` into plain text for a consumer that has no
+ * paste model of its own: unwrap the frames, keep the payload, drop the markers,
+ * and run BOTH halves through `sanitiseTyped`.
+ *
+ * ANY `useInput` CONSUMER THAT APPENDS `input` TO A STRING MUST CALL THIS (I-12),
+ * and the list is pinned by a source scan rather than by review discipline
+ * because the failure is invisible: NUL renders as nothing.
+ *
+ * `useInput` is a BROADCAST -- `use-input.js` re-emits every chunk to every
+ * mounted handler -- so `SettingsScreen` and `QuestionOverlay` see the frame the
+ * composer was sent. An API key is ~100 characters with no line break, which trips
+ * Tier 2's burst rule and gets framed; nothing downstream removes the NULs
+ * (`String.prototype.trim()` does not treat U+0000 as whitespace), the field is
+ * rendered through `maskDot` so the damage is invisible, and the value is handed
+ * to `registerSecret()` and `controller.setApiKey()`. The user is told the
+ * settings were saved and every request afterwards fails to authenticate with
+ * nothing on screen to explain it.
+ *
+ * This is strictly better than v0.6.3 for both consumers: a pasted key carrying a
+ * stray CR or an ANSI sequence is now cleaned rather than stored raw.
+ */
+export declare function stripPasteFrames(input: string): string;

package/dist/ui/paste-frames.js

@@ -0,0 +1,112 @@
+/**
+ * Reading paste frames back out of an Ink `input` string
+ * (tui-paste-handling section 5.4) -- pure.
+ *
+ * The stdin filter writes `PASTE_OPEN + payload + PASTE_CLOSE` inline, in stream
+ * order (I-5). This module is the only place that takes those markers apart.
+ */
+import { PASTE_CLOSE, PASTE_OPEN } from '../input/limits.js';
+import { sanitisePaste } from '../input/paste-parse.js';
+/**
+ * Remove every C0 byte, DEL and C1 byte from text that arrived OUTSIDE a frame
+ * (I-14). NO CR -> LF conversion, and that omission is the point.
+ *
+ * WHY THIS IS NOT OPTIONAL. Ink drains its whole buffer in one size-less
+ * `read()` (`App.js:135`), so the `input` string carrying a frame can also carry
+ * the keystroke bytes that arrived beside it -- most often the `\r` of a user who
+ * pastes and immediately presses Enter, since Ink's 32 ms render throttle and a
+ * large transcript's Yoga pass both outlast the filter's 15 ms burst window.
+ * Splicing that run in verbatim puts a raw CR back into the draft and re-opens
+ * the corruption this whole feature exists to remove.
+ *
+ * Note what it does NOT do. It does not turn a coalesced `\r` into a newline and
+ * it does not submit: a keystroke that merged with a frame has already lost its
+ * identity as a key (`parseKeypress` saw the concatenation, not the key), so the
+ * only two honest options are "insert something wrong" and "drop it". Dropping is
+ * recoverable and benign -- the user presses Enter again -- while inserting a
+ * control byte is not. Printable characters survive untouched.
+ */
+export function sanitiseTyped(text) {
+    return text.replace(/[\u0000-\u001F\u007F-\u009F]/g, '');
+}
+/**
+ * Split an `input` string into ordered text runs and paste runs.
+ *
+ * Text runs are returned already through `sanitiseTyped` (I-14); paste runs are
+ * returned through `sanitisePaste`, which keeps TAB and `\n` because they are
+ * content inside a payload.
+ *
+ * RE-SANITISING THE PAYLOAD IS DEFENCE IN DEPTH, NOT A SECOND OPINION. The
+ * filter already ran `sanitisePaste` and it is idempotent, so the normal path is
+ * byte-identical. What it buys is that G2 ("no pasted byte is ever executed as a
+ * terminal control") becomes a property of the COMPOSER rather than a property
+ * of whoever produced the frame -- which matters for the branch below, where an
+ * unmatched `PASTE_OPEN` turns arbitrary trailing bytes into a paste segment.
+ *
+ * An unmatched `PASTE_OPEN` -- impossible from our own filter, but cheap to
+ * survive -- yields its remainder as a paste segment rather than leaking NULs.
+ */
+export function splitPasteFrames(input) {
+    const segments = [];
+    const pushText = (raw) => {
+        const text = sanitiseTyped(raw);
+        if (text.length > 0)
+            segments.push({ kind: 'text', text });
+    };
+    const pushPaste = (raw) => {
+        const text = sanitisePaste(raw);
+        if (text.length > 0)
+            segments.push({ kind: 'paste', text });
+    };
+    let i = 0;
+    while (i < input.length) {
+        const open = input.indexOf(PASTE_OPEN, i);
+        if (open === -1) {
+            pushText(input.slice(i));
+            break;
+        }
+        pushText(input.slice(i, open));
+        const bodyStart = open + PASTE_OPEN.length;
+        const close = input.indexOf(PASTE_CLOSE, bodyStart);
+        if (close === -1) {
+            pushPaste(input.slice(bodyStart));
+            break;
+        }
+        pushPaste(input.slice(bodyStart, close));
+        i = close + PASTE_CLOSE.length;
+    }
+    return segments;
+}
+/** True when this `input` carries at least one frame -- the branch guard. */
+export function hasPasteFrame(input) {
+    return input.includes(PASTE_OPEN);
+}
+/**
+ * Turn a possibly-framed `input` into plain text for a consumer that has no
+ * paste model of its own: unwrap the frames, keep the payload, drop the markers,
+ * and run BOTH halves through `sanitiseTyped`.
+ *
+ * ANY `useInput` CONSUMER THAT APPENDS `input` TO A STRING MUST CALL THIS (I-12),
+ * and the list is pinned by a source scan rather than by review discipline
+ * because the failure is invisible: NUL renders as nothing.
+ *
+ * `useInput` is a BROADCAST -- `use-input.js` re-emits every chunk to every
+ * mounted handler -- so `SettingsScreen` and `QuestionOverlay` see the frame the
+ * composer was sent. An API key is ~100 characters with no line break, which trips
+ * Tier 2's burst rule and gets framed; nothing downstream removes the NULs
+ * (`String.prototype.trim()` does not treat U+0000 as whitespace), the field is
+ * rendered through `maskDot` so the damage is invisible, and the value is handed
+ * to `registerSecret()` and `controller.setApiKey()`. The user is told the
+ * settings were saved and every request afterwards fails to authenticate with
+ * nothing on screen to explain it.
+ *
+ * This is strictly better than v0.6.3 for both consumers: a pasted key carrying a
+ * stray CR or an ANSI sequence is now cleaned rather than stored raw.
+ */
+export function stripPasteFrames(input) {
+    if (!hasPasteFrame(input))
+        return sanitiseTyped(input);
+    return splitPasteFrames(input)
+        .map((segment) => (segment.kind === 'paste' ? sanitiseTyped(segment.text) : segment.text))
+        .join('');
+}

package/dist/ui/paste-tokens.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The paste token vocabulary (tui-paste-handling section 5.3) -- pure. No Ink,
+ * no React, no I/O.
+ *
+ * A large paste is replaced IN THE BUFFER by a display token,
+ * `[Pasted text #1 +15 lines]`, and its payload is held beside the buffer in the
+ * editor's `pastes` map until the message is sent (D-7). An inline token rather
+ * than an out-of-band attachment is what lets the user place a paste relative to
+ * their own words -- "explain this: [Pasted text #1 +218 lines] -- why does it
+ * retry?" -- which is also the shape the requirement's example asks for.
+ *
+ * The token is ATOMIC FOR EDITING and NOT for cursor movement (D-8). Delete and
+ * kill ranges snap outward to cover a whole token and the caret snaps out before
+ * an insert, which removes every realistic way to corrupt one; arrows still step
+ * by character, because re-deriving `moveVertical`, `home`/`end` and word jumps
+ * around a synthetic unit buys a correctness the user cannot notice.
+ */
+export interface PasteRecord {
+    readonly id: number;
+    /** The sanitised payload, byte-for-byte what `expandPastes` sends. */
+    readonly text: string;
+    readonly lines: number;
+    readonly chars: number;
+}
+/**
+ * A FACTORY, NOT A SHARED CONSTANT (P2-2).
+ *
+ * A module-level `/g` RegExp carries `lastIndex` between calls, so `re.test(x)`
+ * returns false on every second call with the same input -- a bug that presents
+ * as "token detection works, then randomly does not". Callers must use
+ * `matchAll` or `replace` (both safe) on a FRESH instance; nothing in this module
+ * may call `.test()` or `.exec()` on a `/g` regex it did not just create.
+ *
+ * Strict, anchored to its own literal shape, ASCII-only. Group 1 is the id.
+ */
+export declare function pasteTokenRe(): RegExp;
+export declare function allocatePasteId(): number;
+/** Test-only reset. Never called from application code. */
+export declare function resetPasteIdsForTest(): void;
+export declare function makePasteRecord(id: number, text: string): PasteRecord;
+/**
+ * `[Pasted text #3 +218 lines]`, or `[Pasted text #4 +1204 chars]` for a paste
+ * that is one very long line.
+ *
+ * "+1 lines" is not a sentence, and for a one-liner the number the user cares
+ * about is its length rather than its line count.
+ */
+export declare function formatPasteToken(record: PasteRecord): string;
+/** Above EITHER inline bound the paste is collapsed into a token (G3 / G4). */
+export declare function shouldCollapse(text: string): boolean;
+interface TokenSpan {
+    readonly start: number;
+    readonly end: number;
+    readonly id: number;
+}
+/** Every token in the buffer, in order. */
+export declare function tokenSpans(buffer: string): TokenSpan[];
+/** The token containing or touching `index`, or `null`. */
+export declare function tokenAt(buffer: string, index: number): TokenSpan | null;
+/**
+ * Move a caret that landed STRICTLY INSIDE a token to its nearer edge (D-8).
+ *
+ * An index at either edge, or outside every token, is returned unchanged -- so
+ * this is a no-op on a buffer with no tokens, which is every buffer today.
+ */
+export declare function snapOutOfToken(buffer: string, cursor: number): number;
+/**
+ * Grow `[from, to)` so it covers every token it partially overlaps (G5).
+ *
+ * This is what makes `Backspace` immediately after `...lines]` remove the whole
+ * token in ONE keystroke, and what stops `Ctrl+W` / `Ctrl+U` / `Ctrl+K` leaving
+ * half a token -- and therefore an unparseable label -- behind.
+ */
+export declare function expandRangeOverTokens(buffer: string, from: number, to: number): {
+    from: number;
+    to: number;
+};
+/**
+ * Replace every token whose id is present in `pastes`; leave the rest verbatim.
+ *
+ * A user who literally TYPES `[Pasted text #3 +9 lines]` while paste #3 exists in
+ * the same draft will have it expanded. That is bounded (ids are per process, the
+ * map is per draft) and harmless (they get text that is already in their own
+ * draft), and the alternative -- an unguessable nonce in the label -- would trade
+ * a case nobody hits for a label nobody can read.
+ */
+export declare function expandPastes(buffer: string, pastes: ReadonlyMap<number, PasteRecord>): string;
+/** Ids still referenced by the buffer -- the input to I-7's prune. */
+export declare function referencedIds(buffer: string): Set<number>;
+export {};

package/dist/ui/paste-tokens.js

@@ -0,0 +1,147 @@
+/**
+ * The paste token vocabulary (tui-paste-handling section 5.3) -- pure. No Ink,
+ * no React, no I/O.
+ *
+ * A large paste is replaced IN THE BUFFER by a display token,
+ * `[Pasted text #1 +15 lines]`, and its payload is held beside the buffer in the
+ * editor's `pastes` map until the message is sent (D-7). An inline token rather
+ * than an out-of-band attachment is what lets the user place a paste relative to
+ * their own words -- "explain this: [Pasted text #1 +218 lines] -- why does it
+ * retry?" -- which is also the shape the requirement's example asks for.
+ *
+ * The token is ATOMIC FOR EDITING and NOT for cursor movement (D-8). Delete and
+ * kill ranges snap outward to cover a whole token and the caret snaps out before
+ * an insert, which removes every realistic way to corrupt one; arrows still step
+ * by character, because re-deriving `moveVertical`, `home`/`end` and word jumps
+ * around a synthetic unit buys a correctness the user cannot notice.
+ */
+import { PASTE_INLINE_MAX_CHARS, PASTE_INLINE_MAX_LINES } from './composer-limits.js';
+/**
+ * A FACTORY, NOT A SHARED CONSTANT (P2-2).
+ *
+ * A module-level `/g` RegExp carries `lastIndex` between calls, so `re.test(x)`
+ * returns false on every second call with the same input -- a bug that presents
+ * as "token detection works, then randomly does not". Callers must use
+ * `matchAll` or `replace` (both safe) on a FRESH instance; nothing in this module
+ * may call `.test()` or `.exec()` on a `/g` regex it did not just create.
+ *
+ * Strict, anchored to its own literal shape, ASCII-only. Group 1 is the id.
+ */
+export function pasteTokenRe() {
+    return /\[Pasted text #(\d+) \+\d+ (?:lines|chars)\]/g;
+}
+/**
+ * The process-monotonic id counter (D-14).
+ *
+ * CALLED FROM THE COMPONENT, NEVER FROM THE REDUCER (P1-5). React is explicitly
+ * allowed to run a reducer more than once for one action -- eager evaluation in
+ * `dispatchSetState`, base-queue replay after a bailout, StrictMode double
+ * invocation -- and a counter mutated inside one would skip ids and produce two
+ * states that differ in the token TEXT, not merely in identity. Allocating in the
+ * handler also makes the rendered token deterministic for a unit test.
+ *
+ * Monotonic for the PROCESS rather than per draft, so two drafts never show `#1`
+ * for different content in one session.
+ */
+let nextPasteId = 1;
+export function allocatePasteId() {
+    const id = nextPasteId;
+    nextPasteId += 1;
+    return id;
+}
+/** Test-only reset. Never called from application code. */
+export function resetPasteIdsForTest() {
+    nextPasteId = 1;
+}
+export function makePasteRecord(id, text) {
+    return { id, text, lines: text.split('\n').length, chars: [...text].length };
+}
+/**
+ * `[Pasted text #3 +218 lines]`, or `[Pasted text #4 +1204 chars]` for a paste
+ * that is one very long line.
+ *
+ * "+1 lines" is not a sentence, and for a one-liner the number the user cares
+ * about is its length rather than its line count.
+ */
+export function formatPasteToken(record) {
+    return record.lines > 1
+        ? `[Pasted text #${record.id} +${record.lines} lines]`
+        : `[Pasted text #${record.id} +${record.chars} chars]`;
+}
+/** Above EITHER inline bound the paste is collapsed into a token (G3 / G4). */
+export function shouldCollapse(text) {
+    return text.split('\n').length > PASTE_INLINE_MAX_LINES || [...text].length > PASTE_INLINE_MAX_CHARS;
+}
+/** Every token in the buffer, in order. */
+export function tokenSpans(buffer) {
+    const spans = [];
+    for (const m of buffer.matchAll(pasteTokenRe())) {
+        const start = m.index ?? 0;
+        spans.push({ start, end: start + m[0].length, id: Number(m[1]) });
+    }
+    return spans;
+}
+/** The token containing or touching `index`, or `null`. */
+export function tokenAt(buffer, index) {
+    for (const span of tokenSpans(buffer)) {
+        if (index >= span.start && index <= span.end)
+            return span;
+    }
+    return null;
+}
+/**
+ * Move a caret that landed STRICTLY INSIDE a token to its nearer edge (D-8).
+ *
+ * An index at either edge, or outside every token, is returned unchanged -- so
+ * this is a no-op on a buffer with no tokens, which is every buffer today.
+ */
+export function snapOutOfToken(buffer, cursor) {
+    for (const span of tokenSpans(buffer)) {
+        if (cursor <= span.start || cursor >= span.end)
+            continue;
+        return cursor - span.start <= span.end - cursor ? span.start : span.end;
+    }
+    return cursor;
+}
+/**
+ * Grow `[from, to)` so it covers every token it partially overlaps (G5).
+ *
+ * This is what makes `Backspace` immediately after `...lines]` remove the whole
+ * token in ONE keystroke, and what stops `Ctrl+W` / `Ctrl+U` / `Ctrl+K` leaving
+ * half a token -- and therefore an unparseable label -- behind.
+ */
+export function expandRangeOverTokens(buffer, from, to) {
+    let lo = Math.min(from, to);
+    let hi = Math.max(from, to);
+    for (const span of tokenSpans(buffer)) {
+        if (span.start < hi && lo < span.end) {
+            lo = Math.min(lo, span.start);
+            hi = Math.max(hi, span.end);
+        }
+    }
+    return { from: lo, to: hi };
+}
+/**
+ * Replace every token whose id is present in `pastes`; leave the rest verbatim.
+ *
+ * A user who literally TYPES `[Pasted text #3 +9 lines]` while paste #3 exists in
+ * the same draft will have it expanded. That is bounded (ids are per process, the
+ * map is per draft) and harmless (they get text that is already in their own
+ * draft), and the alternative -- an unguessable nonce in the label -- would trade
+ * a case nobody hits for a label nobody can read.
+ */
+export function expandPastes(buffer, pastes) {
+    if (pastes.size === 0)
+        return buffer;
+    return buffer.replace(pasteTokenRe(), (match, idText) => {
+        const record = pastes.get(Number(idText));
+        return record ? record.text : match;
+    });
+}
+/** Ids still referenced by the buffer -- the input to I-7's prune. */
+export function referencedIds(buffer) {
+    const ids = new Set();
+    for (const m of buffer.matchAll(pasteTokenRe()))
+        ids.add(Number(m[1]));
+    return ids;
+}

package/dist/ui/screen.d.ts

@@ -49,6 +49,22 @@ export interface AltScreenOptions {
      * 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,

package/dist/ui/screen.js

@@ -55,6 +55,32 @@ const disableMouse = (motion) => `\x1b[?1006l${motion ? '\x1b[?1002l' : ''}\x1b[
  */
 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 {
@@ -73,7 +99,12 @@ export function enterAltScreen(stdout, options = { mouse: false }) {
         return NOOP_HANDLE;
     const mouse = options.mouse === true;
     const motion = options.motion === true;
-    safeWrite(stdout, ENTER_ALT + CLEAR_VISIBLE + CURSOR_HOME + (mouse ? enableMouse(motion) : SAVE_ALT_SCROLL_OFF));
+    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).
      *
@@ -93,6 +124,12 @@ export function enterAltScreen(stdout, options = { mouse: false }) {
      */
     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.
@@ -134,7 +171,13 @@ export function enterAltScreen(stdout, options = { mouse: false }) {
             // 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.
-            const tail = (captured ? disableMouse(motion) : '') + (savedAltScroll ? RESTORE_ALT_SCROLL : '');
+            //
+            // 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,

package/dist/ui/selection/selection-controller.d.ts

@@ -27,7 +27,7 @@
  *    same `decorate` call. What you see is what you get by construction, rather
  *    than by a staleness check that can be wrong.
  */
-import type { MouseSource } from '../../input/stdin-mouse-filter.js';
+import type { MouseSource } from '../../input/stdin-filter.js';
 import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
 import type { CopyVia } from '../clipboard.js';