@aragon-agent/cli 0.6.3 → 0.6.4

package/dist/config/schema.d.ts

@@ -599,6 +599,48 @@ export declare const DEFAULT_COMPACTION_CONFIG: CompactionConfig;
  * gives `warnThreshold` a range of `[0.4, 0.45]`.
  */
 export declare function clampCompactionConfig(raw: unknown): CompactionConfig;
+export interface BashConfig {
+    /**
+     * Register `bash_output` / `bash_kill`, honour `background`, splice the prompt
+     * block, render the chip. Default TRUE.
+     *
+     * READ ONCE AT CONSTRUCTION, the `team.enabled` / `todo.enabled` /
+     * `fast.enabled` rule.
+     *
+     * IT GOVERNS *SERVICES*, NEVER *INTERRUPTIBILITY* (I-2 / D-9). `Esc`/`Esc`,
+     * the foreground child registry and `forceStop()` are unconditional, because
+     * "bash always settles" and "Esc twice always works" are promised
+     * unconditionally — a user who turned background services off has not asked
+     * for a less interruptible agent.
+     */
+    background: boolean;
+    /**
+     * Let the classifier decide when the model did not say. Default TRUE.
+     *
+     * RESOLVES TO `false` WITHOUT AN INTERACTIVE VIEW (D-15 / P1-8), and that is
+     * decided at the tool layer rather than here: the value on disk is the user's
+     * preference, and headless has no card, no `/bg` and no user to keep a service
+     * alive, so the rescue would be a surprise instead. An explicit
+     * `background: true` is still honoured there — that one the model asked for.
+     */
+    autoBackground: boolean;
+    /** How long a background launch may block the turn before returning. */
+    startupSettleMs: number;
+    /** How long a service may stay `starting` before it is called `running`. */
+    readyTimeoutMs: number;
+}
+export declare const DEFAULT_BASH_CONFIG: BashConfig;
+/**
+ * THE single gate for every bash-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * for the reason those record: hardening only the read path leaves a bad value
+ * on disk that reverts to the default on every launch, which presents to the
+ * user as "my setting won't stick".
+ *
+ * CLAMPED, NEVER REJECTED — the discipline every other key in this file follows.
+ * A garbage `startupSettleMs` resolves to 4000 and throws nothing.
+ */
+export declare function clampBashConfig(raw: unknown): BashConfig;
 /**
  * Parse `0.9`, `90%` or `90` into a ratio, or `null` when it is neither.
  *
@@ -702,6 +744,16 @@ export interface PersistedConfig {
      * written at all, so `false` is byte-identical to a pre-feature session.
      */
     mouseSelect: boolean;
+    /**
+     * Recognise pasted text and collapse a large paste into a placeholder
+     * (tui-paste-handling D-10 / section 7.3).
+     *
+     * A PLAIN BOOLEAN and the ONLY user-facing key this feature adds: the collapse
+     * threshold and every size bound are structural and live in `input/limits.ts`
+     * / `ui/composer-limits.ts`. A tunable threshold is a preference nobody has
+     * asked for; a kill switch is what a bug report needs.
+     */
+    paste: boolean;
     /** Idle ms before a paused viewport returns to the newest line; `0` disables. */
     scrollResumeMs: number;
     /** Start every session in PLAN mode (plan-mode §4.4). */
@@ -726,6 +778,8 @@ export interface PersistedConfig {
     update: UpdateConfig;
     /** Context compaction. The NINTH nested object; scalars only (see CompactionConfig). */
     compaction: CompactionConfig;
+    /** Background services. The TENTH nested object; scalars only (see BashConfig). */
+    bash: BashConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -866,6 +920,17 @@ export interface CliConfig {
      * `config list`, and never reach a single one of them.
      */
     mouseSelect: boolean;
+    /**
+     * Whether this session recognises pastes at all.
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `mouseSelect` above records: `runInteractive` reads `config.paste` -- where
+     * `config` is a `CliConfig` -- to decide the filter's `paste` feature, the
+     * `?2004h` write and the `PasteBridge`. A key added to the persisted shape
+     * alone would round-trip through `config set`, appear in `config list`, and
+     * reach none of them.
+     */
+    paste: boolean;
     /** Idle ms before a paused viewport returns to the newest line; `0` disables. */
     scrollResumeMs: number;
     /**
@@ -959,6 +1024,26 @@ export interface CliConfig {
      * reach either of them.
      */
     compaction: CompactionConfig;
+    /**
+     * Resolved background-service settings (background-service-supervision §5.4).
+     *
+     * `background` here decides whether `bash`'s schema carries a `background`
+     * property, whether `bash_output` / `bash_kill` are REGISTERED and whether
+     * `<background_services>` is spliced — all three at construction, and none of
+     * them undoable, the `team.enabled` / `todo.enabled` / `fast.enabled` rule.
+     * The other three keys are read LIVE.
+     *
+     * IT DOES NOT GATE THE INTERRUPT LADDER (I-2 / D-9). `ProcSupervisor` is
+     * constructed unconditionally, because `Esc`/`Esc` and the foreground registry
+     * are what make G2 and G3 true and those are promised whatever this says.
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason every
+     * section above records: the controller and `bash` read `config.bash`, where
+     * `config` is a `CliConfig`, so a key added to the persisted shape alone would
+     * round-trip through `config set`, appear in `config list` — and never reach
+     * either of them.
+     */
+    bash: BashConfig;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *

package/dist/config/schema.js

@@ -777,6 +777,33 @@ export function clampCompactionConfig(raw) {
         archive: bool(src.archive, DEFAULT_COMPACTION_CONFIG.archive),
     };
 }
+export const DEFAULT_BASH_CONFIG = {
+    background: true,
+    autoBackground: true,
+    startupSettleMs: 4000,
+    readyTimeoutMs: 60_000,
+};
+const STARTUP_SETTLE_RANGE = { min: 500, max: 30_000 };
+const READY_TIMEOUT_RANGE = { min: 5_000, max: 600_000 };
+/**
+ * THE single gate for every bash-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * for the reason those record: hardening only the read path leaves a bad value
+ * on disk that reverts to the default on every launch, which presents to the
+ * user as "my setting won't stick".
+ *
+ * CLAMPED, NEVER REJECTED — the discipline every other key in this file follows.
+ * A garbage `startupSettleMs` resolves to 4000 and throws nothing.
+ */
+export function clampBashConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    return {
+        background: bool(src.background, DEFAULT_BASH_CONFIG.background),
+        autoBackground: bool(src.autoBackground, DEFAULT_BASH_CONFIG.autoBackground),
+        startupSettleMs: clampInt(src.startupSettleMs, DEFAULT_BASH_CONFIG.startupSettleMs, STARTUP_SETTLE_RANGE),
+        readyTimeoutMs: clampInt(src.readyTimeoutMs, DEFAULT_BASH_CONFIG.readyTimeoutMs, READY_TIMEOUT_RANGE),
+    };
+}
 /**
  * Parse `0.9`, `90%` or `90` into a ratio, or `null` when it is neither.
  *
@@ -833,6 +860,7 @@ export const DEFAULT_CONFIG = {
     hints: true,
     mouse: true,
     mouseSelect: DEFAULT_MOUSE_SELECT,
+    paste: true,
     scrollResumeMs: DEFAULT_SCROLL_RESUME_MS,
     planModeDefault: false,
     planModeMaxAskRounds: DEFAULT_PLAN_MAX_ASK_ROUNDS,
@@ -865,6 +893,11 @@ export const DEFAULT_CONFIG = {
     // arrive OFF for every existing user, which is the one direction this
     // particular default must never fail in.
     compaction: DEFAULT_COMPACTION_CONFIG,
+    // And one section later again, for the fifth time. `bash.background` is `true`
+    // by default, so a `config.json` predating this feature resolving it to
+    // `undefined` would arrive with background services OFF for every existing
+    // user — the same direction the compaction line above must never fail in.
+    bash: DEFAULT_BASH_CONFIG,
 };
 /**
  * Runtime state that used to be stored in `config.json` by mistake

package/dist/config/store.js

@@ -14,7 +14,7 @@ import { dirname } from 'node:path';
 import process from 'node:process';
 import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
-import { CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
+import { clampBashConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
 /**
  * Normalize `maxTokens` for both directions of the config file.
  *
@@ -148,6 +148,20 @@ export function loadPersistedConfig() {
             ...DEFAULT_CONFIG.compaction,
             ...(partial.compaction ?? {}),
         }),
+        // `bash` is the tenth. Same one-level rule, same merge — and the READ half
+        // supplies a whole section to every user whose `config.json` predates
+        // background services, which is all of them. Without it
+        // `config.bash.background` reads `undefined`, which is FALSY, so a feature
+        // that is `true` by default would arrive off for every existing user.
+        //
+        // A SIBLING OF `compaction`, NOT A KEY INSIDE ITS ARGUMENT. Nesting it one
+        // level too deep type-checks — `...DEFAULT_CONFIG` above already supplies a
+        // `bash`, so nothing is missing from the return type — and hands
+        // `clampCompactionConfig` a key it drops on the floor. The section then
+        // reaches callers straight off the shallow `...partial` spread: unclamped,
+        // and NOT merged over the defaults, which is verbatim the failure the
+        // paragraph above says this line prevents.
+        bash: clampBashConfig({ ...DEFAULT_CONFIG.bash, ...(partial.bash ?? {}) }),
     };
 }
 /**
@@ -224,6 +238,12 @@ export function updatePersistedConfig(patch) {
         // OFF finds it back on tomorrow — a feature that spends money on their behalf
         // re-enabling itself because they nudged a threshold.
         compaction: clampCompactionConfig({ ...current.compaction, ...(patch.compaction ?? {}) }),
+        // The tenth section, and the fifth time this file records the same trap.
+        // A patch carrying only `{ bash: { autoBackground: false } }` — turning the
+        // CLASSIFIER off — would, without this line, be spread shallowly over the
+        // top level and write `background` absent, silently unregistering
+        // `bash_output` / `bash_kill` from the next launch onward.
+        bash: clampBashConfig({ ...current.bash, ...(patch.bash ?? {}) }),
     };
     writeConfigFile(merged);
     return merged;

package/dist/input/limits.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Structural bounds for paste handling (tui-paste-handling D-10 / section 8).
+ *
+ * THESE ARE STRUCTURAL, NOT POLICY. The package convention recorded in
+ * `.claude-index/index.md` is that `limits.ts` carries the numbers an
+ * implementation needs to stay bounded, while `config/schema.ts` carries the
+ * preferences a user is allowed to have. The only user-facing key this feature
+ * adds is the boolean `paste`; a tunable collapse threshold is a preference
+ * nobody has asked for, and a kill switch is what a bug report actually needs.
+ *
+ * The two framing constants below are the only bytes that cross from the stdin
+ * filter into the composer, so they are load-bearing in a way a threshold is
+ * not: see `PASTE_OPEN`.
+ */
+/**
+ * Ceiling on ONE paste. Above it the body is dropped and the user is told,
+ * never truncated (D-11): a truncated paste loses data and looks like success.
+ */
+export declare const PASTE_MAX_BYTES: number;
+/** Ceiling on every live payload in one draft, summed. Above it a paste is refused. */
+export declare const PASTE_DRAFT_MAX_BYTES: number;
+/** Ceiling on collapsed blocks in one draft. Above it a paste is refused. */
+export declare const PASTE_MAX_BLOCKS = 32;
+/**
+ * Tier 2's single-line rule: a chunk of at least this many printable characters
+ * with no line break is a paste.
+ *
+ * Safe because coalescing a keyboard burst into 25 characters inside one
+ * event-loop turn needs roughly 1 500 WPM. It is a statement about what a
+ * KEYBOARD can emit, not about what text looks like.
+ */
+export declare const PASTE_MIN_BURST_CHARS = 25;
+/** Tier 2 coalescing window. Ordinary typing never opens it, so never pays it. */
+export declare const PASTE_BURST_MS = 15;
+/**
+ * How long an unterminated Tier 1 body is held before it is force-flushed.
+ *
+ * I-4: an unterminated `\x1b[200~` must never be able to wedge keyboard input,
+ * which is the rule `MAX_PENDING_MOUSE_CHARS` already encodes for mouse reports.
+ */
+export declare const PASTE_ASSEMBLY_MAX_MS = 2000;
+/**
+ * The inline frame the filter writes into the stream Ink reads (D-3 / I-5).
+ *
+ * ON THE SAME STREAM, NOT A SIDE CHANNEL. `wrapper.write(text)` is delivered
+ * asynchronously; a synchronous side-channel emit would apply the paste BEFORE
+ * text that preceded it in the same chunk. Framing preserves order by
+ * construction.
+ *
+ * NUL is the delimiter because no terminal delivers it for any key, and because
+ * `sanitisePaste` strips every NUL out of every payload -- so a payload can
+ * never forge a frame boundary.
+ */
+export declare const PASTE_OPEN = "\0[";
+export declare const PASTE_CLOSE = "\0]";
+/**
+ * The one channel from the stdin filter to `App`'s notice dispatch (P1-3 / I-15).
+ *
+ * The filter is constructed in `cli.tsx` BEFORE `render()`, so it has no
+ * `dispatch`. Its only other outlet is the logger, and a limit that writes only
+ * to a log file is indistinguishable -- from the user's chair -- from a paste
+ * that silently did nothing, which is exactly what D-11 exists to rule out.
+ *
+ * Same late-bound shape as `selectionBridge` / `updateBridge` / `terminalBridge`:
+ * `cli.tsx` creates the object, `App` assigns `notify` on mount and clears it on
+ * unmount, and the filter calls `bridge.notify?.(...)`.
+ */
+export interface PasteBridge {
+    notify: ((level: 'warn' | 'error', text: string) => void) | null;
+}
+/** Human-readable byte size for the refusal toast (`4.1 MB`, `812.0 KB`, `7 B`). */
+export declare function formatPasteSize(bytes: number): string;

package/dist/input/limits.js

@@ -0,0 +1,63 @@
+/**
+ * Structural bounds for paste handling (tui-paste-handling D-10 / section 8).
+ *
+ * THESE ARE STRUCTURAL, NOT POLICY. The package convention recorded in
+ * `.claude-index/index.md` is that `limits.ts` carries the numbers an
+ * implementation needs to stay bounded, while `config/schema.ts` carries the
+ * preferences a user is allowed to have. The only user-facing key this feature
+ * adds is the boolean `paste`; a tunable collapse threshold is a preference
+ * nobody has asked for, and a kill switch is what a bug report actually needs.
+ *
+ * The two framing constants below are the only bytes that cross from the stdin
+ * filter into the composer, so they are load-bearing in a way a threshold is
+ * not: see `PASTE_OPEN`.
+ */
+/**
+ * Ceiling on ONE paste. Above it the body is dropped and the user is told,
+ * never truncated (D-11): a truncated paste loses data and looks like success.
+ */
+export const PASTE_MAX_BYTES = 2 * 1024 * 1024;
+/** Ceiling on every live payload in one draft, summed. Above it a paste is refused. */
+export const PASTE_DRAFT_MAX_BYTES = 8 * 1024 * 1024;
+/** Ceiling on collapsed blocks in one draft. Above it a paste is refused. */
+export const PASTE_MAX_BLOCKS = 32;
+/**
+ * Tier 2's single-line rule: a chunk of at least this many printable characters
+ * with no line break is a paste.
+ *
+ * Safe because coalescing a keyboard burst into 25 characters inside one
+ * event-loop turn needs roughly 1 500 WPM. It is a statement about what a
+ * KEYBOARD can emit, not about what text looks like.
+ */
+export const PASTE_MIN_BURST_CHARS = 25;
+/** Tier 2 coalescing window. Ordinary typing never opens it, so never pays it. */
+export const PASTE_BURST_MS = 15;
+/**
+ * How long an unterminated Tier 1 body is held before it is force-flushed.
+ *
+ * I-4: an unterminated `\x1b[200~` must never be able to wedge keyboard input,
+ * which is the rule `MAX_PENDING_MOUSE_CHARS` already encodes for mouse reports.
+ */
+export const PASTE_ASSEMBLY_MAX_MS = 2_000;
+/**
+ * The inline frame the filter writes into the stream Ink reads (D-3 / I-5).
+ *
+ * ON THE SAME STREAM, NOT A SIDE CHANNEL. `wrapper.write(text)` is delivered
+ * asynchronously; a synchronous side-channel emit would apply the paste BEFORE
+ * text that preceded it in the same chunk. Framing preserves order by
+ * construction.
+ *
+ * NUL is the delimiter because no terminal delivers it for any key, and because
+ * `sanitisePaste` strips every NUL out of every payload -- so a payload can
+ * never forge a frame boundary.
+ */
+export const PASTE_OPEN = '\u0000[';
+export const PASTE_CLOSE = '\u0000]';
+/** Human-readable byte size for the refusal toast (`4.1 MB`, `812.0 KB`, `7 B`). */
+export function formatPasteSize(bytes) {
+    if (bytes >= 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    if (bytes >= 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${bytes} B`;
+}

package/dist/input/paste-parse.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Paste recognition primitives (tui-paste-handling section 5.1) -- pure,
+ * stream-free, no timers.
+ *
+ * WHY THIS LIVES BELOW INK. `ink/build/components/App.js:131-138` reads stdin on
+ * `'readable'` and emits each chunk as one `'input'` event;
+ * `parse-keypress.js:145-148` maps the exact string `'\r'` to `name: 'return'`,
+ * which `PromptInput` reads as "send the message". A 15-line paste on a Windows
+ * console routinely arrives as a dozen chunks that are exactly `"\r"`, and each
+ * one SUBMITS THE DRAFT AS IT STOOD. No component-level heuristic can undo a
+ * `key.return` that has already fired, so recognition has to happen on the byte
+ * stream, in front of Ink -- the same lesson `mouse-events.ts` records.
+ *
+ * Two tiers feed one framing (D-4). Tier 1 is bracketed paste and is exact;
+ * Tier 2 is a heuristic on chunk SHAPE for the terminals that ignore
+ * `DECSET 2004`. Both are about what a keyboard can physically emit.
+ */
+/** `DECSET 2004` wraps a paste in these two markers. */
+export declare const PASTE_BEGIN_MARK = "\u001B[200~";
+export declare const PASTE_END_MARK = "\u001B[201~";
+/** The longest tail worth holding back while a marker might still complete. */
+export declare const PASTE_MARK_LENGTH: number;
+/**
+ * True when `s` is a PROPER prefix of either paste marker (never a whole one).
+ *
+ * Both markers are held, in every mode, whether or not THIS process enabled DEC
+ * 2004 (I-16): the user's shell, `tmux` or a wrapper script may have left it on,
+ * and an unconsumed marker is a literal `[200~` typed into the draft -- the
+ * exact failure the feature exists to prevent.
+ */
+export declare function isPastePrefix(s: string): boolean;
+/**
+ * Length of the trailing run of `text` that is a proper prefix of a paste
+ * marker, or 0. Shortest match wins, so only the bytes that could still become a
+ * marker are held back.
+ */
+export declare function trailingPastePrefixLength(text: string): number;
+/**
+ * Tier 2: is this chunk a paste, or keystrokes?
+ *
+ * The PRIMARY rule -- "longer than one character AND contains a line break" --
+ * is exactly the shape defect A needs, so the two coincide: any chunk that could
+ * submit the draft by accident is classified as a paste. A lone `\r` is the
+ * Enter key and stays `'keys'`.
+ *
+ * The SECONDARY rule needs `PASTE_MIN_BURST_CHARS` printable characters in one
+ * chunk. It excludes chunks carrying any C0 byte but TAB, which is what keeps an
+ * arrow-key burst (`\x1b[B\x1b[B...`, and every wheel notch translated by
+ * alternate scroll) out of the paste path.
+ */
+export declare function classifyChunk(text: string, minBurstChars?: number): 'paste' | 'keys';
+/**
+ * Make a payload safe to put in a buffer and draw through `<Text>` (G2).
+ *
+ * 1. CRLF and lone CR both become exactly ONE `\n` -- terminals send CR for a
+ *    newline in pasted text, and a lone LF is dropped by Ink's key parser
+ *    entirely, so both have to be normalised here or a pasted line break either
+ *    submits the message or silently vanishes.
+ * 2. Every C0 byte except `\n` and `\t` is removed. Ink writes `<Text>` children
+ *    to the terminal without escaping anything, so a surviving `\r` overwrites
+ *    the row it is drawn on and a surviving `\x1b` repaints the frame's colours.
+ * 3. DEL and every C1 byte (U+0080..U+009F) go too, and that is NOT padding:
+ *    U+009B is the single-byte CSI and U+0085 is NEL, and a terminal that decodes
+ *    them acts on them exactly as it acts on `\x1b[`. A file pasted out of a
+ *    non-UTF-8 editor walks straight through a "strip C0" rule.
+ * 4. TAB is KEPT. Indentation is content, and it is what the model receives.
+ *
+ * Applied to PAYLOAD ONLY, never to keystrokes, so `Ctrl+A` and Escape keep
+ * working. Non-ASCII text (CJK, emoji) is untouched.
+ */
+export declare function sanitisePaste(raw: string): string;

package/dist/input/paste-parse.js

@@ -0,0 +1,95 @@
+/**
+ * Paste recognition primitives (tui-paste-handling section 5.1) -- pure,
+ * stream-free, no timers.
+ *
+ * WHY THIS LIVES BELOW INK. `ink/build/components/App.js:131-138` reads stdin on
+ * `'readable'` and emits each chunk as one `'input'` event;
+ * `parse-keypress.js:145-148` maps the exact string `'\r'` to `name: 'return'`,
+ * which `PromptInput` reads as "send the message". A 15-line paste on a Windows
+ * console routinely arrives as a dozen chunks that are exactly `"\r"`, and each
+ * one SUBMITS THE DRAFT AS IT STOOD. No component-level heuristic can undo a
+ * `key.return` that has already fired, so recognition has to happen on the byte
+ * stream, in front of Ink -- the same lesson `mouse-events.ts` records.
+ *
+ * Two tiers feed one framing (D-4). Tier 1 is bracketed paste and is exact;
+ * Tier 2 is a heuristic on chunk SHAPE for the terminals that ignore
+ * `DECSET 2004`. Both are about what a keyboard can physically emit.
+ */
+import { PASTE_MIN_BURST_CHARS } from './limits.js';
+/** `DECSET 2004` wraps a paste in these two markers. */
+export const PASTE_BEGIN_MARK = '\x1b[200~';
+export const PASTE_END_MARK = '\x1b[201~';
+/** The longest tail worth holding back while a marker might still complete. */
+export const PASTE_MARK_LENGTH = PASTE_BEGIN_MARK.length;
+/**
+ * True when `s` is a PROPER prefix of either paste marker (never a whole one).
+ *
+ * Both markers are held, in every mode, whether or not THIS process enabled DEC
+ * 2004 (I-16): the user's shell, `tmux` or a wrapper script may have left it on,
+ * and an unconsumed marker is a literal `[200~` typed into the draft -- the
+ * exact failure the feature exists to prevent.
+ */
+export function isPastePrefix(s) {
+    if (s.length === 0 || s.length >= PASTE_MARK_LENGTH)
+        return false;
+    return PASTE_BEGIN_MARK.startsWith(s) || PASTE_END_MARK.startsWith(s);
+}
+/**
+ * Length of the trailing run of `text` that is a proper prefix of a paste
+ * marker, or 0. Shortest match wins, so only the bytes that could still become a
+ * marker are held back.
+ */
+export function trailingPastePrefixLength(text) {
+    const max = Math.min(text.length, PASTE_MARK_LENGTH - 1);
+    for (let k = 1; k <= max; k += 1) {
+        if (isPastePrefix(text.slice(text.length - k)))
+            return k;
+    }
+    return 0;
+}
+/** Any C0 control byte other than TAB -- ESC, BEL, NUL, CR, LF included. */
+const HAS_CONTROL_EXCEPT_TAB = /[\u0000-\u0008\u000A-\u001F]/;
+/**
+ * Tier 2: is this chunk a paste, or keystrokes?
+ *
+ * The PRIMARY rule -- "longer than one character AND contains a line break" --
+ * is exactly the shape defect A needs, so the two coincide: any chunk that could
+ * submit the draft by accident is classified as a paste. A lone `\r` is the
+ * Enter key and stays `'keys'`.
+ *
+ * The SECONDARY rule needs `PASTE_MIN_BURST_CHARS` printable characters in one
+ * chunk. It excludes chunks carrying any C0 byte but TAB, which is what keeps an
+ * arrow-key burst (`\x1b[B\x1b[B...`, and every wheel notch translated by
+ * alternate scroll) out of the paste path.
+ */
+export function classifyChunk(text, minBurstChars = PASTE_MIN_BURST_CHARS) {
+    if (text.length > 1 && /[\r\n]/.test(text))
+        return 'paste';
+    if (text.length >= minBurstChars && !HAS_CONTROL_EXCEPT_TAB.test(text))
+        return 'paste';
+    return 'keys';
+}
+/**
+ * Make a payload safe to put in a buffer and draw through `<Text>` (G2).
+ *
+ * 1. CRLF and lone CR both become exactly ONE `\n` -- terminals send CR for a
+ *    newline in pasted text, and a lone LF is dropped by Ink's key parser
+ *    entirely, so both have to be normalised here or a pasted line break either
+ *    submits the message or silently vanishes.
+ * 2. Every C0 byte except `\n` and `\t` is removed. Ink writes `<Text>` children
+ *    to the terminal without escaping anything, so a surviving `\r` overwrites
+ *    the row it is drawn on and a surviving `\x1b` repaints the frame's colours.
+ * 3. DEL and every C1 byte (U+0080..U+009F) go too, and that is NOT padding:
+ *    U+009B is the single-byte CSI and U+0085 is NEL, and a terminal that decodes
+ *    them acts on them exactly as it acts on `\x1b[`. A file pasted out of a
+ *    non-UTF-8 editor walks straight through a "strip C0" rule.
+ * 4. TAB is KEPT. Indentation is content, and it is what the model receives.
+ *
+ * Applied to PAYLOAD ONLY, never to keystrokes, so `Ctrl+A` and Escape keep
+ * working. Non-ASCII text (CJK, emoji) is untouched.
+ */
+export function sanitisePaste(raw) {
+    return raw
+        .replace(/\r\n?/g, '\n')
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '');
+}

package/dist/input/stdin-filter.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Stdin filter (mouse-wheel-region-routing section 4.2 / 5.2, extended by
+ * tui-paste-handling section 5.1).
+ *
+ * WHY A WRAPPER AND NOT A SECOND LISTENER. Ink 5.2.1 owns stdin in a way that
+ * forbids a second reader: `components/App.js` calls `setEncoding('utf8')`,
+ * `ref()`, `setRawMode(true)`, subscribes to `'readable'` and drains with
+ * `read()`. Attaching our own `'data'` listener to the same `process.stdin`
+ * would switch the stream into flowing mode and RACE Ink's `read()` for chunks
+ * -- some keystrokes would reach Ink, some would not, non-deterministically
+ * (D-3). So the filter REPLACES the stream Ink is given: it reads the real
+ * stdin, strips every mouse report, frames every paste, and writes the
+ * remainder into a `PassThrough` that carries the surface Ink requires.
+ *
+ * ONE CHANNEL, NOT TWO, AND THAT NOW COVERS PASTES AS WELL (D-2 / D-3). A second
+ * chained filter would need a second `PassThrough` and would reopen the ordering
+ * hazard this note closes; a side-channel paste emit would apply the payload
+ * BEFORE text that preceded it in the same chunk, because `wrapper.write` is
+ * asynchronous and a synchronous emit is not. The paste therefore travels
+ * INLINE, wrapped in `PASTE_OPEN` / `PASTE_CLOSE` (I-5).
+ *
+ * ORDERING IS AN INVARIANT, NOT A CONVENTION (I-8). The caller must build this
+ * filter BEFORE anything writes `\x1b[?1000h` or `\x1b[?2004h`. Reporting or
+ * bracketed paste enabled while Ink still holds the raw stream does not degrade
+ * the feature -- it types `[<0;12;5M` or `[200~` into the user's message, which
+ * is strictly worse than the bug being fixed.
+ *
+ * THE HANDLE ANSWERS EXACTLY ONE QUESTION: "is a stream wrapped?" (I-11 / D-17).
+ * It stopped being the answer to "is the mouse on?" the moment paste could build
+ * a filter on its own -- `paste` defaults to `true`, so `aragon --no-mouse`
+ * builds one. `cli.tsx` reads its own `mouseOn` / `pasteOn` booleans; this module
+ * is told which features it is running and never derives them.
+ */
+import { type MouseEvent } from './mouse-events.js';
+import { type PasteBridge } from './limits.js';
+export interface MouseSource {
+    /**
+     * Returns an unsubscribe function. Multiple subscribers are allowed -- the
+     * wheel router and (since tui-selection-and-scroll-follow) the selection
+     * controller both take this one channel, and each ignores the kinds it does
+     * not own.
+     *
+     * With `features.mouse` false the channel exists and stays SILENT forever, so
+     * a subscriber written against it does not have to know which features are on.
+     */
+    subscribe(listener: (event: MouseEvent) => void): () => void;
+}
+/**
+ * Which stream-level features this filter is running.
+ *
+ * TOLD, NEVER DERIVED (D-17 / P0-1). With `{ mouse: false, paste: true }` no
+ * `MouseEvent` is ever emitted and `splitMouseEvents` is not called at all: a
+ * `--no-mouse` session never wrote `?1000h`, so no real report can arrive, and
+ * running the parser anyway could only ever EAT pasted bytes that happen to look
+ * like one. With `{ mouse: true, paste: false }` this is byte-for-byte the
+ * v0.6.3 mouse filter.
+ */
+export interface StdinFilterFeatures {
+    /** Parse and strip SGR / X10 mouse reports, and emit `MouseEvent`s. */
+    readonly mouse: boolean;
+    /** Recognise pastes and deliver them framed. */
+    readonly paste: boolean;
+}
+export interface StdinFilter {
+    /** Hand this to Ink: `render(<App/>, { stdin: filter.stdin })`. */
+    readonly stdin: NodeJS.ReadStream;
+    readonly source: MouseSource;
+    /** Idempotent. Detaches from the real stdin and clears every timer (I-7). */
+    dispose(): void;
+}
+export declare function createStdinFilter(real: NodeJS.ReadStream, features: StdinFilterFeatures, bridge?: PasteBridge, onWarn?: (reason: string) => void): StdinFilter;
+/**
+ * Build a filter, or `null` if construction throws.
+ *
+ * The `null` return is the whole point (P0-1): a construction failure must
+ * degrade to "the wheel is inert and pastes are keystrokes" -- a supported,
+ * tested rung of the fail-safe ladder -- rather than leaving `?1000h` or `?2004h`
+ * on with no filter in front of Ink. `cli.tsx` derives BOTH `mouseOn` and
+ * `pasteOn` from the returned handle for exactly that reason.
+ */
+export declare function tryCreateStdinFilter(real: NodeJS.ReadStream, features: StdinFilterFeatures, onError?: (reason: string) => void, bridge?: PasteBridge): StdinFilter | null;