@aragon-agent/cli 0.5.1 → 0.5.3

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, clampLogConfig, clampSkillsConfig, } from './schema.js';
+import { CONFIG_VERSION, DEFAULT_CONFIG, clampLogConfig, clampSkillsConfig, clampTeamConfig, stripLegacyStateKeys, } from './schema.js';
 // Re-exported so the many existing importers of `store.js` keep working; the
 // definitions live in `app-paths.ts` because they are pure path arithmetic.
 export { getConfigPath, getSessionsDir };
@@ -82,19 +82,24 @@ export function writeConfigFile(config) {
  * Unlike `readConfigFile`, this always returns a complete `PersistedConfig`.
  */
 export function loadPersistedConfig() {
-    const partial = readConfigFile().config ?? {};
+    // STRIP BEFORE THE SPREAD, not after. `partial` is the raw file, so any
+    // `promptHistory` / `submitCount` / `mouseNoticeSeen` / `recentModels` left
+    // on disk would otherwise ride the spread into `merged` and be written back
+    // out by `updatePersistedConfig` — the "I deleted it and it grew back" bug
+    // that `stripLegacyStateKeys` exists to make impossible (§4.5).
+    const partial = stripLegacyStateKeys(readConfigFile().config ?? {});
     return {
         ...DEFAULT_CONFIG,
         ...partial,
         version: CONFIG_VERSION,
         apiKeys: { ...DEFAULT_CONFIG.apiKeys, ...(partial.apiKeys ?? {}) },
-        recentModels: partial.recentModels ?? [],
-        promptHistory: partial.promptHistory ?? [],
         // `skills` is the second nested object in this file and needs the same
         // treatment `apiKeys` gets — see the note on updatePersistedConfig below.
         skills: clampSkillsConfig({ ...DEFAULT_CONFIG.skills, ...(partial.skills ?? {}) }),
         // `log` is the third. Same one-level rule, same merge.
         log: clampLogConfig({ ...DEFAULT_CONFIG.log, ...(partial.log ?? {}) }),
+        // `team` is the fourth. Same one-level rule, same merge.
+        team: clampTeamConfig({ ...DEFAULT_CONFIG.team, ...(partial.team ?? {}) }),
     };
 }
 /**
@@ -132,6 +137,10 @@ export function updatePersistedConfig(patch) {
         // replace the whole section and quietly revert `maxFiles`, `previewChars`
         // and — worst of all — `redactSecrets`.
         log: clampLogConfig({ ...current.log, ...(patch.log ?? {}) }),
+        // The fourth section, and it needs the merge for the same reason: `/team max
+        // 4` sends `{ team: { maxSubagents: 4 } }`, which a shallow spread would
+        // turn into "changing the fan-out width silently reverted every timeout".
+        team: clampTeamConfig({ ...current.team, ...(patch.team ?? {}) }),
     };
     writeConfigFile(merged);
     return merged;

package/dist/config/ui-state.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `<home>/state.json` — UI bookkeeping (config-state-separation §4.4).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHAT MAY LIVE HERE: UI bookkeeping SCALARS. Counters, and "has this one-shot
+ * notice been shown" flags. NOTHING ELSE.
+ *
+ * Anything carrying user content, and anything that grows with usage, opens its
+ * own file. This rule is not a preference — it is the entire reason this module
+ * exists. `config.json` became a place where a prompt-by-prompt transcript sat
+ * next to the API key precisely because nobody had written a rule like this
+ * down, and a file called `state.json` is the most inviting drawer in the
+ * codebase (Q-4 / RV-8).
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * Nothing here is a preference: none of these fields has a flag, an env var or
+ * a `config set` key, and none of them should ever get one. Losing the file
+ * costs a composer hint reappearing once.
+ *
+ * FAILURE POLICY (C2): never throws, exactly like `prompt-history.ts` and
+ * `skills/usage.ts`. Writes are immediate rather than debounced (D-7) — the
+ * file is one small object, and a debounce would add a flush-on-exit obligation
+ * whose failure mode is the counter silently not sticking.
+ *
+ * NOT the same thing as `migrate-legacy-state.ts`, despite the shared word:
+ * that one is the 0.4.x legacy-to-current brand migration and has nothing to do
+ * with this file.
+ */
+export declare const UI_STATE_FILENAME = "state.json";
+export declare const UI_STATE_SCHEMA = 1;
+export interface UiState {
+    schema: number;
+    /** Lifetime submit count; drives the composer hint fade (`HINT_FADE_AFTER`). */
+    submitCount: number;
+    /** Whether the one-shot "hold Shift to select text" notice has been shown. */
+    mouseNoticeSeen: boolean;
+}
+/** Read the state, caching it for the life of the process. Never throws. */
+export declare function loadUiState(): UiState;
+export declare function readSubmitCount(): number;
+/** Increment, persist, and return the new value. */
+export declare function bumpSubmitCount(): number;
+export declare function getMouseNoticeSeen(): boolean;
+export declare function setMouseNoticeSeen(seen: boolean): void;
+/**
+ * Migration-only: fill in fields that are still at their default, and never
+ * overwrite a value already here. A second import — after a half-finished
+ * migration retries — must not walk the counter backwards.
+ */
+export declare function importLegacyUiState(patch: Partial<Pick<UiState, 'submitCount' | 'mouseNoticeSeen'>>): void;
+/** Test-only: forget the cached state. */
+export declare function resetUiStateForTests(): void;

package/dist/config/ui-state.js

@@ -0,0 +1,149 @@
+/**
+ * `<home>/state.json` — UI bookkeeping (config-state-separation §4.4).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHAT MAY LIVE HERE: UI bookkeeping SCALARS. Counters, and "has this one-shot
+ * notice been shown" flags. NOTHING ELSE.
+ *
+ * Anything carrying user content, and anything that grows with usage, opens its
+ * own file. This rule is not a preference — it is the entire reason this module
+ * exists. `config.json` became a place where a prompt-by-prompt transcript sat
+ * next to the API key precisely because nobody had written a rule like this
+ * down, and a file called `state.json` is the most inviting drawer in the
+ * codebase (Q-4 / RV-8).
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * Nothing here is a preference: none of these fields has a flag, an env var or
+ * a `config set` key, and none of them should ever get one. Losing the file
+ * costs a composer hint reappearing once.
+ *
+ * FAILURE POLICY (C2): never throws, exactly like `prompt-history.ts` and
+ * `skills/usage.ts`. Writes are immediate rather than debounced (D-7) — the
+ * file is one small object, and a debounce would add a flush-on-exit obligation
+ * whose failure mode is the counter silently not sticking.
+ *
+ * NOT the same thing as `migrate-legacy-state.ts`, despite the shared word:
+ * that one is the 0.4.x legacy-to-current brand migration and has nothing to do
+ * with this file.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import process from 'node:process';
+import { getHomeRoot, getUiStatePath } from './app-paths.js';
+export const UI_STATE_FILENAME = 'state.json';
+export const UI_STATE_SCHEMA = 1;
+const DEFAULT_UI_STATE = {
+    schema: UI_STATE_SCHEMA,
+    submitCount: 0,
+    mouseNoticeSeen: false,
+};
+let memory = null;
+function coerceCount(value) {
+    const n = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_UI_STATE.submitCount;
+    return Math.floor(n);
+}
+/**
+ * Per-field tolerance: one nonsense value must not take the other field with
+ * it. A wrong SCHEMA is different — the shape is no longer known, so the whole
+ * object falls back (the rule `skills/usage.ts` already follows).
+ */
+function readFromDisk() {
+    const path = getUiStatePath();
+    if (!existsSync(path))
+        return { ...DEFAULT_UI_STATE };
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return { ...DEFAULT_UI_STATE };
+        if (parsed.schema !== UI_STATE_SCHEMA)
+            return { ...DEFAULT_UI_STATE };
+        return {
+            schema: UI_STATE_SCHEMA,
+            submitCount: coerceCount(parsed.submitCount),
+            mouseNoticeSeen: typeof parsed.mouseNoticeSeen === 'boolean'
+                ? parsed.mouseNoticeSeen
+                : DEFAULT_UI_STATE.mouseNoticeSeen,
+        };
+    }
+    catch {
+        return { ...DEFAULT_UI_STATE };
+    }
+}
+/** Read the state, caching it for the life of the process. Never throws. */
+export function loadUiState() {
+    if (memory === null)
+        memory = readFromDisk();
+    return memory;
+}
+/**
+ * Atomic write: temp file, rename, re-chmod.
+ *
+ * `mkdirSync` first for the reason spelled out in `prompt-history.ts`: `<home>`
+ * is not guaranteed to exist, and without it the counter would silently never
+ * persist on a fresh install that also turned file logging off (RV-2).
+ * The `chmodSync` matches `store.ts` — rename does not preserve mode on every
+ * platform (RV-6).
+ */
+function writeToDisk(state) {
+    const path = getUiStatePath();
+    const tmp = `${path}.tmp-${process.pid}`;
+    try {
+        mkdirSync(getHomeRoot(), { recursive: true });
+        writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+        renameSync(tmp, path);
+        if (process.platform !== 'win32')
+            chmodSync(path, 0o600);
+    }
+    catch {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // Nothing further to try; the value simply stays in memory (C2).
+        }
+    }
+}
+function update(patch) {
+    const next = { ...loadUiState(), ...patch, schema: UI_STATE_SCHEMA };
+    memory = next;
+    writeToDisk(next);
+    return next;
+}
+export function readSubmitCount() {
+    return loadUiState().submitCount;
+}
+/** Increment, persist, and return the new value. */
+export function bumpSubmitCount() {
+    return update({ submitCount: readSubmitCount() + 1 }).submitCount;
+}
+export function getMouseNoticeSeen() {
+    return loadUiState().mouseNoticeSeen;
+}
+export function setMouseNoticeSeen(seen) {
+    update({ mouseNoticeSeen: seen });
+}
+/**
+ * Migration-only: fill in fields that are still at their default, and never
+ * overwrite a value already here. A second import — after a half-finished
+ * migration retries — must not walk the counter backwards.
+ */
+export function importLegacyUiState(patch) {
+    const current = loadUiState();
+    const next = {};
+    if (patch.submitCount !== undefined &&
+        current.submitCount === DEFAULT_UI_STATE.submitCount) {
+        next.submitCount = coerceCount(patch.submitCount);
+    }
+    if (patch.mouseNoticeSeen !== undefined &&
+        current.mouseNoticeSeen === DEFAULT_UI_STATE.mouseNoticeSeen) {
+        next.mouseNoticeSeen = patch.mouseNoticeSeen === true;
+    }
+    if (Object.keys(next).length === 0)
+        return;
+    update(next);
+}
+/** Test-only: forget the cached state. */
+export function resetUiStateForTests() {
+    memory = null;
+}

package/dist/input/mouse-events.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Mouse-report parser (mouse-wheel-region-routing §5.1) — pure, stream-free.
+ *
+ * The alternate screen has no native scrollback, so every modern terminal turns
+ * on DEC private mode 1007 (*alternate scroll*) and translates each wheel notch
+ * into a burst of arrow keys. Arrow keys carry NO POINTER POSITION, which is
+ * why region routing is impossible from that channel and why the CLI asks for
+ * real SGR mouse reporting instead (`\x1b[?1000h\x1b[?1006h`).
+ *
+ * Asking for it is only half the job. Ink 5.2.1 has no mouse branch at all:
+ * `parse-keypress.js` fails to match `\x1b[<64;40;12M`, `use-input.js` strips
+ * the leading ESC, and `PromptInput`'s `isControlSeq` guard passes the
+ * remainder (`[` is 0x5B, >= 0x20) straight into `insert()`. So an unfiltered
+ * mouse report is not ignored — it is TYPED INTO THE USER'S MESSAGE. This
+ * module exists so `stdin-mouse-filter.ts` can remove every byte of every
+ * report before Ink ever sees the chunk (invariant I-1).
+ *
+ * Non-wheel reports (press / release / drag) are recognized and DISCARDED
+ * rather than passed through, for the same reason.
+ */
+export interface WheelEvent {
+    readonly kind: 'wheel';
+    readonly dir: 'up' | 'down';
+    /** 1-based terminal column, as reported. */
+    readonly x: number;
+    /** 1-based terminal row, as reported. */
+    readonly y: number;
+    readonly shift: boolean;
+    readonly alt: boolean;
+    readonly ctrl: boolean;
+}
+export interface MouseSplit {
+    /** Wheel events, in arrival order. Non-wheel reports are dropped, not returned. */
+    readonly events: WheelEvent[];
+    /** Everything that was not a mouse report — forward this to Ink verbatim. */
+    readonly text: string;
+    /** Trailing strict prefix of a possible report; feed it back in with the next chunk. */
+    readonly pending: string;
+}
+/**
+ * Ceiling on the held-back tail. A malformed sequence that looks like a prefix
+ * forever must never be able to wedge input: past this length the tail is
+ * flushed as ordinary text and parsing resumes from the next byte.
+ */
+export declare const MAX_PENDING_MOUSE_CHARS = 32;
+/**
+ * True when `s` is a PROPER prefix of a possible mouse report (never a full
+ * one). Nothing a keyboard produces matches beyond `\x1b` and `\x1b[`, which is
+ * why the filter's flush timer is a rare path rather than a latency tax on
+ * typing: ordinary text and pasted blocks contain no `\x1b[<`.
+ */
+export declare function isMousePrefix(s: string): boolean;
+/**
+ * Split a decoded stdin chunk into wheel events, passthrough text, and a
+ * trailing prefix to carry into the next chunk.
+ *
+ * The caller is expected to feed `pending + nextChunk` back in; ConPTY does
+ * split writes mid-sequence, and a report torn across two chunks would
+ * otherwise leak its tail into the composer (R-6).
+ */
+export declare function splitMouseEvents(buffer: string): MouseSplit;

package/dist/input/mouse-events.js

@@ -0,0 +1,153 @@
+/**
+ * Mouse-report parser (mouse-wheel-region-routing §5.1) — pure, stream-free.
+ *
+ * The alternate screen has no native scrollback, so every modern terminal turns
+ * on DEC private mode 1007 (*alternate scroll*) and translates each wheel notch
+ * into a burst of arrow keys. Arrow keys carry NO POINTER POSITION, which is
+ * why region routing is impossible from that channel and why the CLI asks for
+ * real SGR mouse reporting instead (`\x1b[?1000h\x1b[?1006h`).
+ *
+ * Asking for it is only half the job. Ink 5.2.1 has no mouse branch at all:
+ * `parse-keypress.js` fails to match `\x1b[<64;40;12M`, `use-input.js` strips
+ * the leading ESC, and `PromptInput`'s `isControlSeq` guard passes the
+ * remainder (`[` is 0x5B, >= 0x20) straight into `insert()`. So an unfiltered
+ * mouse report is not ignored — it is TYPED INTO THE USER'S MESSAGE. This
+ * module exists so `stdin-mouse-filter.ts` can remove every byte of every
+ * report before Ink ever sees the chunk (invariant I-1).
+ *
+ * Non-wheel reports (press / release / drag) are recognized and DISCARDED
+ * rather than passed through, for the same reason.
+ */
+/**
+ * Ceiling on the held-back tail. A malformed sequence that looks like a prefix
+ * forever must never be able to wedge input: past this length the tail is
+ * flushed as ordinary text and parsing resumes from the next byte.
+ */
+export const MAX_PENDING_MOUSE_CHARS = 32;
+const ESC = '\x1b';
+/** `\x1b[<b;x;yM` (press) or `…m` (release) — the only form we request. */
+const SGR_REPORT = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])/;
+/** A strict prefix of an SGR report: `\x1b[<` plus digits and semicolons. */
+const SGR_PREFIX = /^\x1b\[<[\d;]*$/;
+/**
+ * True when `s` is a PROPER prefix of a possible mouse report (never a full
+ * one). Nothing a keyboard produces matches beyond `\x1b` and `\x1b[`, which is
+ * why the filter's flush timer is a rare path rather than a latency tax on
+ * typing: ordinary text and pasted blocks contain no `\x1b[<`.
+ */
+export function isMousePrefix(s) {
+    return /^\x1B(\[(<[\d;]*|M[\s\S]{0,2})?)?$/.test(s);
+}
+/**
+ * Decode an SGR button byte into a wheel event, or `null` when the report is
+ * not a wheel notch we act on.
+ *
+ * THE ORDER OF THESE TESTS IS THE SPECIFICATION, not a presentation choice.
+ * Button 66 (wheel-left) has `b & 1 === 0` and would decode as `'up'`, so the
+ * horizontal test has to precede the direction decode.
+ */
+function decodeWheel(b, x, y, final) {
+    // 1. Not a wheel report at all (press / release / drag) — consume, emit nothing.
+    if ((b & 64) === 0)
+        return null;
+    // 2. Horizontal wheel (66 = left, 67 = right). Consumed and dropped (non-goal).
+    if ((b & 3) >= 2)
+        return null;
+    // 3. Wheel buttons are press-only; a terminal that ever sent a release for one
+    //    must not produce a second step for the same physical notch.
+    if (final !== 'M')
+        return null;
+    return {
+        kind: 'wheel',
+        dir: (b & 1) === 1 ? 'down' : 'up',
+        x,
+        y,
+        shift: (b & 4) !== 0,
+        alt: (b & 8) !== 0,
+        ctrl: (b & 16) !== 0,
+    };
+}
+/**
+ * X10 legacy reports (`\x1b[M` + three chars, each `code - 32`).
+ *
+ * We never request this encoding — `?1006h` is over a decade old and every
+ * terminal that implements `?1000` implements it — but a terminal that ignored
+ * the SGR request would fall back to it, and a leaked `\x1b[M` + garbage is
+ * exactly the draft corruption I-1 exists to prevent. So it is consumed
+ * unconditionally; the coordinates are only trusted when all three bytes are
+ * plausible, because `setEncoding('utf8')` mangles raw bytes above 0x7F.
+ */
+function matchX10(s) {
+    if (s.length < 6)
+        return { kind: 'partial' };
+    const codes = [s.charCodeAt(3), s.charCodeAt(4), s.charCodeAt(5)];
+    if (codes.some((c) => c < 32 || c > 255))
+        return { kind: 'complete', length: 6, event: null };
+    const [b, x, y] = codes;
+    return { kind: 'complete', length: 6, event: decodeWheel(b - 32, x - 32, y - 32, 'M') };
+}
+/** Classify the escape sequence starting at `s[0] === ESC`. */
+function matchReport(s) {
+    if (s.length === 1)
+        return { kind: 'partial' }; // lone ESC so far
+    if (s[1] !== '[')
+        return { kind: 'none' };
+    if (s.length === 2)
+        return { kind: 'partial' }; // `\x1b[`
+    if (s[2] === '<') {
+        const m = SGR_REPORT.exec(s);
+        if (m) {
+            const b = Number(m[1]);
+            const x = Number(m[2]);
+            const y = Number(m[3]);
+            return { kind: 'complete', length: m[0].length, event: decodeWheel(b, x, y, m[4]) };
+        }
+        return SGR_PREFIX.test(s) ? { kind: 'partial' } : { kind: 'none' };
+    }
+    if (s[2] === 'M')
+        return matchX10(s);
+    return { kind: 'none' };
+}
+/**
+ * Split a decoded stdin chunk into wheel events, passthrough text, and a
+ * trailing prefix to carry into the next chunk.
+ *
+ * The caller is expected to feed `pending + nextChunk` back in; ConPTY does
+ * split writes mid-sequence, and a report torn across two chunks would
+ * otherwise leak its tail into the composer (R-6).
+ */
+export function splitMouseEvents(buffer) {
+    const events = [];
+    let text = '';
+    let i = 0;
+    while (i < buffer.length) {
+        const esc = buffer.indexOf(ESC, i);
+        if (esc === -1) {
+            text += buffer.slice(i);
+            return { events, text, pending: '' };
+        }
+        text += buffer.slice(i, esc);
+        const rest = buffer.slice(esc);
+        const m = matchReport(rest);
+        if (m.kind === 'complete') {
+            if (m.event)
+                events.push(m.event);
+            i = esc + m.length;
+            continue;
+        }
+        if (m.kind === 'partial') {
+            // A tail that never resolves must not hold input hostage: past the
+            // ceiling it is ordinary text, and parsing continues after the ESC.
+            if (rest.length > MAX_PENDING_MOUSE_CHARS) {
+                text += rest;
+                return { events, text, pending: '' };
+            }
+            return { events, text, pending: rest };
+        }
+        // Not a mouse report — an arrow key, a paste, anything. Emit the ESC and
+        // resume scanning after it so the rest of the sequence reaches Ink intact.
+        text += ESC;
+        i = esc + 1;
+    }
+    return { events, text, pending: '' };
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Stdin mouse filter (mouse-wheel-region-routing §4.2 / §5.2).
+ *
+ * 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, and writes the remainder into a
+ * `PassThrough` that carries the surface Ink requires.
+ *
+ * ORDERING IS AN INVARIANT, NOT A CONVENTION (I-8). The caller must build this
+ * filter BEFORE anything writes `\x1b[?1000h`. Reporting enabled while Ink
+ * still holds the raw stream does not degrade the feature — it types
+ * `[<0;12;5M` into the user's message on every click, which is strictly worse
+ * than the bug this feature fixes. `cli.tsx::runInteractive` is the only caller
+ * and passes `filter !== null` to `enterAltScreen`.
+ */
+import { type WheelEvent } from './mouse-events.js';
+export interface MouseSource {
+    /** Returns an unsubscribe function. Multiple subscribers are allowed. */
+    subscribe(listener: (event: WheelEvent) => void): () => void;
+}
+export interface MouseFilter {
+    /** Hand this to Ink: `render(<App/>, { stdin: filter.stdin })`. */
+    readonly stdin: NodeJS.ReadStream;
+    readonly source: MouseSource;
+    /** Idempotent. Detaches from the real stdin and clears the flush timer (I-7). */
+    dispose(): void;
+}
+export declare function createMouseFilter(real: NodeJS.ReadStream): MouseFilter;
+/**
+ * Build a filter, or `null` if construction throws.
+ *
+ * The `null` return is the whole point (P0-1): `enterAltScreen` derives whether
+ * to enable mouse reporting from `filter !== null`, so a construction failure
+ * degrades to "the wheel is inert" — a supported, tested rung of the fail-safe
+ * ladder — rather than leaving reporting on with no filter in front of Ink.
+ */
+export declare function tryCreateMouseFilter(real: NodeJS.ReadStream, onError?: (reason: string) => void): MouseFilter | null;

package/dist/input/stdin-mouse-filter.js

@@ -0,0 +1,153 @@
+/**
+ * Stdin mouse filter (mouse-wheel-region-routing §4.2 / §5.2).
+ *
+ * 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, and writes the remainder into a
+ * `PassThrough` that carries the surface Ink requires.
+ *
+ * ORDERING IS AN INVARIANT, NOT A CONVENTION (I-8). The caller must build this
+ * filter BEFORE anything writes `\x1b[?1000h`. Reporting enabled while Ink
+ * still holds the raw stream does not degrade the feature — it types
+ * `[<0;12;5M` into the user's message on every click, which is strictly worse
+ * than the bug this feature fixes. `cli.tsx::runInteractive` is the only caller
+ * and passes `filter !== null` to `enterAltScreen`.
+ */
+import { PassThrough } from 'node:stream';
+import { splitMouseEvents } from './mouse-events.js';
+/**
+ * How long a possible-prefix tail is held before being flushed as text.
+ *
+ * This is what stops a lone `\x1b` — the Esc key, which aborts a run — from
+ * being held hostage waiting for a `[` that will never arrive. Worst-case Esc
+ * latency becomes 12 ms, and only for the keystroke that is literally a bare
+ * ESC; every other key resolves `isMousePrefix` to false immediately.
+ */
+const PENDING_FLUSH_MS = 12;
+/** Assign a method onto the PassThrough without widening its public type. */
+function define(target, name, value) {
+    Object.defineProperty(target, name, { value, writable: true, configurable: true });
+}
+export function createMouseFilter(real) {
+    const wrapper = new PassThrough();
+    const listeners = new Set();
+    let pending = '';
+    let flushTimer = null;
+    let disposed = false;
+    // --- The surface Ink reads off the stream it is handed. ------------------
+    // `isRawModeSupported()` reads `props.stdin.isTTY` (App.js:34), so this has
+    // to be a DELEGATING GETTER rather than a snapshot: a stdin that is not a TTY
+    // must still report so through the wrapper, or Ink throws instead of falling
+    // back.
+    Object.defineProperty(wrapper, 'isTTY', {
+        get: () => real.isTTY,
+        configurable: true,
+    });
+    define(wrapper, 'setRawMode', (mode) => {
+        real.setRawMode?.(mode);
+        return wrapper;
+    });
+    define(wrapper, 'ref', () => {
+        real.ref?.();
+        return wrapper;
+    });
+    define(wrapper, 'unref', () => {
+        real.unref?.();
+        return wrapper;
+    });
+    const emit = (event) => {
+        for (const listener of [...listeners])
+            listener(event);
+    };
+    const clearFlushTimer = () => {
+        if (!flushTimer)
+            return;
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    };
+    const flushPending = () => {
+        clearFlushTimer();
+        if (pending.length === 0 || disposed)
+            return;
+        const text = pending;
+        pending = '';
+        wrapper.write(text);
+    };
+    const onData = (chunk) => {
+        if (disposed)
+            return;
+        clearFlushTimer();
+        const decoded = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        const split = splitMouseEvents(pending + decoded);
+        pending = split.pending;
+        if (split.text.length > 0)
+            wrapper.write(split.text);
+        for (const event of split.events)
+            emit(event);
+        if (pending.length > 0) {
+            // `.unref()` so a held tail can never keep the process alive on its own.
+            flushTimer = setTimeout(flushPending, PENDING_FLUSH_MS);
+            flushTimer.unref?.();
+        }
+    };
+    // P2-7: a closed stdin must still terminate Ink's reader, or it waits forever
+    // on a stream that will never produce another byte.
+    const onEnd = () => {
+        flushPending();
+        if (!wrapper.writableEnded)
+            wrapper.end();
+    };
+    // `setEncoding('utf8')` on the REAL stream so Node's StringDecoder handles
+    // multi-byte boundaries for us — the parser works on characters, and a UTF-8
+    // sequence split across two chunks would otherwise become two mojibake
+    // characters before it ever reached `splitMouseEvents`.
+    real.setEncoding?.('utf8');
+    real.on('data', onData);
+    real.once('end', onEnd);
+    real.once('close', onEnd);
+    return {
+        stdin: wrapper,
+        source: {
+            subscribe(listener) {
+                listeners.add(listener);
+                return () => listeners.delete(listener);
+            },
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            clearFlushTimer();
+            real.removeListener('data', onData);
+            real.removeListener('end', onEnd);
+            real.removeListener('close', onEnd);
+            listeners.clear();
+            // I-7: a live `'data'` listener on stdin keeps the event loop alive, and
+            // `aragon` would hang on exit instead of returning to the shell.
+            real.pause?.();
+            real.unref?.();
+        },
+    };
+}
+/**
+ * Build a filter, or `null` if construction throws.
+ *
+ * The `null` return is the whole point (P0-1): `enterAltScreen` derives whether
+ * to enable mouse reporting from `filter !== null`, so a construction failure
+ * degrades to "the wheel is inert" — a supported, tested rung of the fail-safe
+ * ladder — rather than leaving reporting on with no filter in front of Ink.
+ */
+export function tryCreateMouseFilter(real, onError) {
+    try {
+        return createMouseFilter(real);
+    }
+    catch (err) {
+        onError?.(err instanceof Error ? err.message : String(err));
+        return null;
+    }
+}