@aragon-agent/cli 0.6.3 → 0.6.4

package/dist/ui/layout/budget.d.ts

@@ -30,11 +30,26 @@ export interface ChromeBudget {
     /** Brand bar. Constant 1 in full-screen — this is what makes A-3 hold. */
     header: number;
     toast: number;
-    /** Round border (2) + input row (1), plus the hint row when it fits. */
+    /**
+     * Round border (2) + the DRAFT's own rows, plus the hint row when it fits.
+     *
+     * The draft term used to be the constant 1 that the `3` / `4` below encode.
+     * That constant is what made a pasted 200-line draft draw the transcript 197
+     * rows shorter than every consumer of `viewportRows` believed -- the trap
+     * `BottomStatusRow.tsx:5-27` already documents at 1/200th the magnitude.
+     */
     composer: number;
     status: number;
 }
-export declare function chromeBudget(rows: number): ChromeBudget;
+/**
+ * The composer's draft rows, clamped to what this terminal height allows.
+ *
+ * Exported so the reporter and the budget clamp with ONE function: I-8 requires
+ * the rendered row count and the number handed to `viewportRows` to be the same
+ * number, and two clamps are how they stop being.
+ */
+export declare function clampDraftRows(rows: number, draftRows: number): number;
+export declare function chromeBudget(rows: number, draftRows?: number): ChromeBudget;
 /**
  * Rows available to the viewport at a given terminal height.
  *
@@ -42,8 +57,21 @@ export declare function chromeBudget(rows: number): ChromeBudget;
  * that argument is the guarantee that the first submitted message cannot make
  * the layout jump (A-4). Do not add it back.
  *
- * Non-decreasing in `rows`: the one step where chrome grows (the hint row at
- * `HINT_MIN_ROWS`) coincides with `rows` growing by one, so the net change is 0
- * rather than -1.
+ * `draftRows` IS NOT THAT ARGUMENT, and the distinction is the whole of D-12.
+ * A-4 forbids making the budget depend on TRANSCRIPT content, so that the first
+ * submitted message cannot move the layout. `draftRows` depends only on what the
+ * user is typing right now, and its whole purpose is that the jump is ALREADY
+ * HAPPENING -- Yoga takes the rows out of the transcript whether or not this
+ * function was told. `App` adds the hysteresis (grow now, shrink one tick later)
+ * that keeps it from becoming per-keystroke jitter.
+ *
+ * It DEFAULTS TO 1, i.e. to the constant this function used to assume, so every
+ * pre-existing caller and every pre-existing assertion is byte-identical -- and
+ * `viewportRows.length` stays 1, because a parameter with a default does not
+ * count toward it.
+ *
+ * Non-decreasing in `rows` at a fixed `draftRows = 1`: the one step where chrome
+ * grows (the hint row at `HINT_MIN_ROWS`) coincides with `rows` growing by one,
+ * so the net change is 0 rather than -1.
  */
-export declare function viewportRows(rows: number): number;
+export declare function viewportRows(rows: number, draftRows?: number): number;

package/dist/ui/layout/budget.js

@@ -24,14 +24,26 @@
  * make this comment a true-sounding statement about a row that is gone (AC-12,
  * and the `wheel-scrolls-transcript-only` RV-3 lesson).
  */
+import { draftMaxRows } from '../composer-limits.js';
 import { frameHeight, MIN_FULLSCREEN_ROWS } from './frame.js';
 /** Below this many rows the composer's hint line is dropped to buy back a row. */
 export const HINT_MIN_ROWS = 20;
-export function chromeBudget(rows) {
+/**
+ * The composer's draft rows, clamped to what this terminal height allows.
+ *
+ * Exported so the reporter and the budget clamp with ONE function: I-8 requires
+ * the rendered row count and the number handed to `viewportRows` to be the same
+ * number, and two clamps are how they stop being.
+ */
+export function clampDraftRows(rows, draftRows) {
+    const wanted = Number.isFinite(draftRows) ? Math.floor(draftRows) : 1;
+    return Math.max(1, Math.min(wanted, draftMaxRows(rows)));
+}
+export function chromeBudget(rows, draftRows = 1) {
     return {
         header: 1,
         toast: 1,
-        composer: rows >= HINT_MIN_ROWS ? 4 : 3,
+        composer: 2 + clampDraftRows(rows, draftRows) + (rows >= HINT_MIN_ROWS ? 1 : 0),
         status: 1,
     };
 }
@@ -42,13 +54,26 @@ export function chromeBudget(rows) {
  * that argument is the guarantee that the first submitted message cannot make
  * the layout jump (A-4). Do not add it back.
  *
- * Non-decreasing in `rows`: the one step where chrome grows (the hint row at
- * `HINT_MIN_ROWS`) coincides with `rows` growing by one, so the net change is 0
- * rather than -1.
+ * `draftRows` IS NOT THAT ARGUMENT, and the distinction is the whole of D-12.
+ * A-4 forbids making the budget depend on TRANSCRIPT content, so that the first
+ * submitted message cannot move the layout. `draftRows` depends only on what the
+ * user is typing right now, and its whole purpose is that the jump is ALREADY
+ * HAPPENING -- Yoga takes the rows out of the transcript whether or not this
+ * function was told. `App` adds the hysteresis (grow now, shrink one tick later)
+ * that keeps it from becoming per-keystroke jitter.
+ *
+ * It DEFAULTS TO 1, i.e. to the constant this function used to assume, so every
+ * pre-existing caller and every pre-existing assertion is byte-identical -- and
+ * `viewportRows.length` stays 1, because a parameter with a default does not
+ * count toward it.
+ *
+ * Non-decreasing in `rows` at a fixed `draftRows = 1`: the one step where chrome
+ * grows (the hint row at `HINT_MIN_ROWS`) coincides with `rows` growing by one,
+ * so the net change is 0 rather than -1.
  */
-export function viewportRows(rows) {
+export function viewportRows(rows, draftRows = 1) {
     if (!Number.isFinite(rows) || rows < MIN_FULLSCREEN_ROWS)
         return 0;
-    const c = chromeBudget(rows);
+    const c = chromeBudget(rows, draftRows);
     return Math.max(0, frameHeight(rows) - c.header - c.toast - c.composer - c.status);
 }

package/dist/ui/layout/virtual-window.js

@@ -35,6 +35,7 @@
 import { FAST_LIMITS } from '../../fast/limits.js';
 import { COMPACTION_LIMITS } from '../../compaction/limits.js';
 import { GUTTER_WIDTH } from './Gutter.js';
+import { USER_ENTRY_MAX_ROWS } from '../composer-limits.js';
 export const VIRTUAL_LIMITS = {
     /**
      * Entries kept mounted on each side of the visible band.
@@ -123,6 +124,22 @@ export function entryRevision(entry) {
          */
         case 'compaction':
             return `c${entry.live ? 1 : 0}.${entry.summary?.length ?? 0}.${entry.mode}.${entry.applied ? 1 : 0}`;
+        /**
+         * `rowsSeen`, AND NEVER `rows.length` (background-service-supervision P0-3).
+         *
+         * The service tail is a FIXED-SIZE RING: it evicts its oldest row while
+         * appending a new one, so the joined length is unchanged while the content is
+         * not. That is verbatim the NON-APPEND mutation I-L3-1 above says must extend
+         * the revision, and it is the same trap — and the same fix — as the `tool`
+         * branch's `liveSeq` two cases up. A length term would go on matching while
+         * the card changed underneath it, and the card would freeze at a stale height
+         * AND a stale rendered subtree with nothing anywhere reporting it.
+         *
+         * `status` and the presence of a URL are in because both change the rows the
+         * card draws; `exitCode` is in because the terminal row names it.
+         */
+        case 'service':
+            return `v${entry.status}.${entry.rowsSeen}.${entry.url ? 1 : 0}.${entry.exitCode ?? -1}.${entry.terminal ? 1 : 0}`;
         default:
             return 'x';
     }
@@ -164,6 +181,10 @@ const TOOL_COLLAPSED_LINES = 8;
 const DIFF_COLLAPSED_LINES = 12;
 /** Live tail rows in `ToolCard`; duplicated as a NUMBER, for the same reason. */
 const TOOL_LIVE_TAIL_ROWS = 8;
+/** Tail rows a COLLAPSED `ServiceCard` draws; duplicated for the same reason. */
+const SERVICE_COLLAPSED_TAIL_ROWS = 2;
+/** Tail rows an EXPANDED `ServiceCard` draws; the snapshot cap (8). */
+const SERVICE_EXPANDED_TAIL_ROWS = 8;
 /**
  * Pure UPPER-BOUND estimate of an entry's height, used until a real measurement
  * exists.
@@ -181,7 +202,14 @@ export function estimateEntryRows(entry, cols, density, expanded, thinkingVisibl
     const separation = density === 'comfortable' ? 1 : 0;
     switch (entry.kind) {
         case 'user':
-            return separation + wrappedRows(entry.text, usable);
+            // MIRRORS `UserEntry`'s RENDER CAP (+1 for the `... +N more lines` tail).
+            // THESE TWO NUMBERS ARE ONE NUMBER (I-13). Capping the renderer alone
+            // would leave this function believing a 5 000-line message is 5 000 rows
+            // tall -- and unlike an ordinary over-estimate that failure does NOT
+            // self-correct: this file's own note above records that "an entry
+            // estimated at 400 rows is exactly the one that never gets mounted", and
+            // an unmounted entry is never measured.
+            return (separation + Math.min(wrappedRows(entry.text, usable), USER_ENTRY_MAX_ROWS + 1));
         case 'notice':
             return separation + wrappedRows(entry.text, usable);
         case 'assistant': {
@@ -277,6 +305,28 @@ export function estimateEntryRows(entry, cols, density, expanded, thinkingVisibl
             const footer = lines > body || (expanded && lines > COMPACTION_LIMITS.cardTextRows) ? 1 : 0;
             return separation + 1 + 1 + body + footer;
         }
+        /**
+         * THE THIRD SWITCH, and adding the case to only one of this file's two
+         * yields a transcript whose scroll arithmetic disagrees with what it drew —
+         * drift rather than an error (P0-3 / RV-13). Both `default` branches swallow
+         * an unknown kind silently, and `virtual-window.test.ts` hand-enumerates
+         * kinds, so neither omission turns anything red on its own.
+         *
+         * A terminal record is exactly one row. A live card is the status row, the
+         * URL row when there is one, and the tail — counted, not wrapped, which is
+         * legitimate only because every row is `wrap="truncate"` AND clipped at
+         * `LIVE_ROW_MAX_CHARS` on the way into the ring, the same coupling the
+         * `tool` branch above records for itself.
+         */
+        case 'service': {
+            if (entry.terminal)
+                return separation + 1;
+            const url = entry.url ? 1 : 0;
+            const tail = expanded
+                ? Math.min(entry.rows.length, SERVICE_EXPANDED_TAIL_ROWS)
+                : Math.min(entry.rows.length, SERVICE_COLLAPSED_TAIL_ROWS);
+            return separation + 1 + url + tail;
+        }
         default:
             return separation + 1;
     }

package/dist/ui/overlays/HelpOverlay.js

@@ -26,6 +26,9 @@ function keyRows(times) {
         // startup notice is the other place, and it scrolls away.
         ['Drag (left button)', 'Select text on screen; releasing copies it'],
         ['Up / Down', 'Prompt history (empty input)'],
+        // Pasting is the one affordance here with no key of its own, so the only
+        // place a user can learn what happened to their 218 lines is this row.
+        ['Paste', 'Inserted as-is up to 6 lines; larger becomes [Pasted text #N] (--no-paste)'],
     ];
 }
 const COMMANDS = [

package/dist/ui/overlays/PlanReviewOverlay.js

@@ -27,6 +27,7 @@ import { Text, useInput } from 'ink';
 import { pickGlyphs } from '../glyphs.js';
 import { OverlayFrame } from '../layout/OverlayFrame.js';
 import { wrapToRows } from '../layout/wrap-rows.js';
+import { stripPasteFrames } from '../paste-frames.js';
 /** The frame's border plus its one-column padding on each side. */
 const FRAME_CHROME_COLS = 4;
 export function PlanReviewOverlay({ plan, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onVerdict, }) {
@@ -55,8 +56,15 @@ export function PlanReviewOverlay({ plan, maxRows, cols, scrollOffset, onScrollC
                 setFeedback(feedback.slice(0, -1));
                 return;
             }
-            if (input && !key.ctrl && !key.meta && !key.tab)
-                setFeedback(feedback + input);
+            // `stripPasteFrames`, NOT `input` (I-12 / P0-2). This is the THIRD consumer
+            // that appends `input` to a string; the design's table listed it as
+            // "key-driven only, inert", which was true of the version that had no
+            // free-text field. Revision feedback is exactly the kind of thing a user
+            // pastes — a failing test, a stack trace — and a framed paste appended
+            // verbatim would put NULs into text the model then reads.
+            if (input && !key.ctrl && !key.meta && !key.tab) {
+                setFeedback(feedback + stripPasteFrames(input));
+            }
             return;
         }
         if (input === 'a' || input === 'A')

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 {};