xiaotime 0.5.1 → 0.5.3

package/dist/ui_state.js

@@ -2,52 +2,36 @@
 /**
  * Session-UI state machine for the xiaotime dev CLI.
  *
- * SPRINT-CLI-STATE-MACHINE-1 (#6163 / closes #6127) shipped the original
- * state machine + raw-mode approval prompt. That fix eliminated the
- * defaults-to-N half of the "yy" double-echo bug but the visible-yy half
- * persisted because `readline.createInterface({ terminal: true })` attaches
- * its own keypress handler to stdin that echoes characters via its own
- * stdout writes; `rl.pause()` stops `line` events but does NOT detach that
- * echo path, and `setRawMode(true)` only suppresses kernel-level echo, not
- * readline's.
+ * SPRINT-CLI-STATE-MACHINE-1 (#6163 / closes #6127)
+ * SPRINT-CLI-APPROVAL-MENU-1 (#6509)
+ * SPRINT-CLI-INPUT-AND-TOOL-HARDENING-1 (#7299) PR2
+ * SPRINT-CLI-PASTE-MODE-4 — push-based paste interception.
  *
- * SPRINT-CLI-APPROVAL-MENU-1 (#6509) replaces `promptApproval`'s `[y/N]`
- * one-shot prompt with `promptApprovalMenu` — a three-option numbered menu
- * (Run / Run + allowlist / Reject + feedback). The rl is explicitly
- * **closed and recreated** around the menu render so its keypress echo
- * physically can't fire (the rl object is gone for the duration of the
- * menu). Persistent close listeners survive the recreation via
- * `onRlClose()` — callers that need a stable close hook register through
- * that instead of `getRl().on("close", ...)`.
+ *   Two strategies run together:
  *
- * SPRINT-CLI-INPUT-AND-TOOL-HARDENING-1 (#7299) PR2 closes a follow-up
- * leak in the above recreation path: Node's `rl.close()` doesn't reliably
- * detach the prior rl's keypress listener from stdin when raw mode was
- * toggled mid-cycle. Each surviving listener echoes keystrokes
- * independently, so N approval-menu cycles produced ~N+1 character
- * multiplication. `_makeRl` now strips leftover `keypress` listeners
- * before attaching a new rl — full rationale + rejected alternatives on
- * `_makeRl` below + in issue #7299 Decisions log (D4, D5).
+ *   1. Bracketed paste (ESC[200~ / ESC[201~) — the clean path. When the
+ *      terminal sends these markers the PasteTransform buffers everything
+ *      between them, collapses newlines, and emits a single block. Readline
+ *      never sees a raw newline, so it cannot auto-submit.
  *
- * The state machine has four states:
+ *   2. Rapid-chunk coalescing — the fallback. When bracketed paste mode is
+ *      not supported by the terminal (Termius, older SSH clients) chunks
+ *      arriving with gaps < RAPID_PASTE_GAP_MS are held in a buffer.
+ *      After RAPID_PASTE_IDLE_MS of silence the buffer is flushed as a
+ *      single block with internal newlines collapsed.
  *
- *   IDLE              — at the `you:` prompt, awaiting user input.
- *   GENERATING        — model is streaming tokens (or about to). Spinner.
- *   RUNNING_TOOL      — a server-side tool is running. Spinner.
- *   AWAITING_APPROVAL — user must navigate the approval menu for a
- *                       client-side tool. Main rl is closed; raw stdin
- *                       captures keystrokes.
+ *   Root-cause fix (PASTE-MODE-4): readline must NOT receive the
+ *   PasteTransform stream directly as `input` with `terminal: true`.
+ *   When readline sees a Transform as input in terminal mode it internally
+ *   calls readline.emitKeypressEvents() on that stream, which installs its
+ *   own `data` listener that fires keypress events — including \r/\n — before
+ *   our _transform() can intercept them.
  *
- * The WS handler in `ws.ts` is the sole driver. Transitions:
- *
- *   IDLE              -- user line received    -> GENERATING
- *   GENERATING        -- text_delta            -> GENERATING (refresh)
- *   GENERATING        -- tool_call (server)    -> RUNNING_TOOL
- *   GENERATING        -- tool_call (client+approval) -> AWAITING_APPROVAL
- *   AWAITING_APPROVAL -- menu selection        -> RUNNING_TOOL
- *   RUNNING_TOOL      -- tool_result sent      -> GENERATING
- *   GENERATING        -- message_stop          -> IDLE
- *   ANY               -- error                 -> IDLE
+ *   Solution: push-based forwarding. PasteTransform processes chunks from
+ *   stdin and pushes safe output into a PassThrough. Readline reads from the
+ *   PassThrough. readline.emitKeypressEvents() is called on the PassThrough,
+ *   which only ever sees already-safe data — newlines inside paste blocks have
+ *   already been collapsed to spaces.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -86,83 +70,208 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionUI = void 0;
+exports.SessionUI = exports.PasteTransform = void 0;
 const readline = __importStar(require("readline"));
+const stream_1 = require("stream");
 const chalk_1 = __importDefault(require("chalk"));
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 const SPINNER_INTERVAL_MS = 100;
-const ELAPSED_THRESHOLD_MS = 3000; // show elapsed time after this
+const ELAPSED_THRESHOLD_MS = 3000;
 const MENU_OPTIONS = [
     "Run",
     "Run and don't ask again",
     "Reject and tell Claude why",
 ];
 const MENU_HINT = "(1-3, ↑↓ Enter, Esc to reject)";
+const PASTE_START = "\x1b[200~";
+const PASTE_END = "\x1b[201~";
+const BPASTE_ENABLE = "\x1b[?2004h";
+const BPASTE_DISABLE = "\x1b[?2004l";
+// Rapid-chunk coalescing thresholds
+const RAPID_PASTE_GAP_MS = 30; // chunks arriving faster than this = paste burst
+const RAPID_PASTE_IDLE_MS = 60; // flush buffer after this much silence
+// ── PasteTransform ────────────────────────────────────────────────────────────
+// Processes raw stdin chunks. Two interception modes:
+//
+// Mode A — bracketed paste: ESC[200~ starts buffering, ESC[201~ flushes.
+// Mode B — rapid-chunk coalescing: bursts of chunks with gaps < RAPID_PASTE_GAP_MS
+//          are held and flushed as one block after RAPID_PASTE_IDLE_MS of silence.
+//
+// Output is pushed into a PassThrough (`sink`) which readline reads from.
+// Readline never touches this Transform directly — that prevents readline from
+// calling emitKeypressEvents() on us and bypassing our interception.
+class PasteTransform extends stream_1.Transform {
+    // Mode A
+    _inBracketedPaste = false;
+    _bracketedBuf = "";
+    // Mode B
+    _rapidBuf = "";
+    _lastChunkAt = 0;
+    _rapidTimer = null;
+    // The PassThrough that readline reads from
+    sink;
+    constructor() {
+        super();
+        this.sink = new stream_1.PassThrough();
+        // Forward our Transform output to the sink
+        this.pipe(this.sink);
+    }
+    _transform(chunk, _enc, cb) {
+        let s = chunk.toString();
+        // ── Mode A: bracketed paste ──────────────────────────────────────────────
+        if (s.includes(PASTE_START)) {
+            this._inBracketedPaste = true;
+            this._bracketedBuf = "";
+            s = s.replace(PASTE_START, "");
+        }
+        if (s.includes(PASTE_END)) {
+            this._inBracketedPaste = false;
+            const tail = s.replace(PASTE_END, "");
+            this._bracketedBuf += tail;
+            const safe = this._bracketedBuf.replace(/[\r\n]+/g, " ");
+            this._bracketedBuf = "";
+            this.push(Buffer.from(safe));
+            cb();
+            return;
+        }
+        if (this._inBracketedPaste) {
+            this._bracketedBuf += s;
+            cb();
+            return;
+        }
+        // ── Mode B: rapid-chunk coalescing ───────────────────────────────────────
+        const now = Date.now();
+        const gap = now - this._lastChunkAt;
+        this._lastChunkAt = now;
+        const hasNewline = /[\r\n]/.test(s);
+        const isBurst = gap < RAPID_PASTE_GAP_MS && this._rapidBuf.length > 0;
+        if (isBurst || (hasNewline && this._rapidBuf.length > 0)) {
+            this._rapidBuf += s;
+            this._scheduleRapidFlush();
+            cb();
+            return;
+        }
+        if (hasNewline && this._rapidBuf.length === 0) {
+            // A lone CR/LF is a deliberate Enter, not the first chunk of a paste.
+            // Pass it straight through so readline emits its `line` event and the
+            // prompt submits. Without this, the newline gets buffered and collapsed
+            // to a space by _scheduleRapidFlush, so readline never sees a line
+            // terminator and NO prompt ever submits. Only buffer + newline-strip
+            // when the chunk carries text alongside the newline (the first chunk of
+            // a fast, un-bracketed multi-line paste).
+            if (/^[\r\n]+$/.test(s)) {
+                this.push(chunk);
+                cb();
+                return;
+            }
+            this._rapidBuf += s;
+            this._scheduleRapidFlush();
+            cb();
+            return;
+        }
+        // Normal single keystroke — pass through immediately
+        this.push(chunk);
+        cb();
+    }
+    _scheduleRapidFlush() {
+        if (this._rapidTimer)
+            clearTimeout(this._rapidTimer);
+        this._rapidTimer = setTimeout(() => {
+            this._rapidTimer = null;
+            this._flushRapidBuf();
+        }, RAPID_PASTE_IDLE_MS);
+    }
+    // Flush the rapid-coalesce buffer to readline.
+    //
+    // Trailing-newline rule — fixes the "press Enter twice" bug on SSH clients
+    // (Termius, mosh) that batch a fast-typed line together with its Enter into a
+    // single read, e.g. "hey junior\r" arriving as ONE chunk. The old code
+    // collapsed EVERY newline — including that trailing \r — to a space, so
+    // readline never saw a line terminator: the first Enter silently did nothing
+    // and you had to hit Enter again.
+    //
+    //   - buffer ends in a newline AND the text before it has no internal newline
+    //     → a single typed line + Enter. Re-emit one \r so readline submits on the
+    //     first Enter.
+    //   - buffer has an internal newline (genuine multi-line paste) → collapse all
+    //     newlines to spaces and emit NO terminator, so the paste lands in the
+    //     input for review (unchanged behaviour).
+    _flushRapidBuf() {
+        if (!this._rapidBuf)
+            return;
+        const buf = this._rapidBuf;
+        this._rapidBuf = "";
+        const trailing = buf.match(/[\r\n]+$/);
+        const body = trailing ? buf.slice(0, trailing.index) : buf;
+        const isSingleLineEnter = trailing !== null && !/[\r\n]/.test(body);
+        if (isSingleLineEnter) {
+            this.push(Buffer.from(body + "\r"));
+        }
+        else {
+            this.push(Buffer.from(buf.replace(/[\r\n]+/g, " ")));
+        }
+    }
+    _flush(cb) {
+        if (this._rapidTimer) {
+            clearTimeout(this._rapidTimer);
+            this._rapidTimer = null;
+        }
+        const combined = this._bracketedBuf + this._rapidBuf;
+        if (combined) {
+            const safe = combined.replace(/[\r\n]+/g, " ");
+            this.push(Buffer.from(safe));
+        }
+        this._bracketedBuf = "";
+        this._rapidBuf = "";
+        cb();
+    }
+}
+exports.PasteTransform = PasteTransform;
 class SessionUI {
     state = "idle";
     spinnerTimer = null;
     spinnerFrame = 0;
     spinnerStartedAt = 0;
     spinnerLabel = "";
-    // True only while the spinner has written something to the line and
-    // we owe a clear. Set on first frame, cleared on stopSpinner. Lets
-    // text_delta callers know they need to clear the spinner line
-    // before printing the first token.
     spinnerLineDirty = false;
     rl;
     lineListener = null;
-    /**
-     * Close-listener callbacks that should survive rl recreations. The
-     * approval-menu path closes + recreates `rl` to physically detach
-     * readline's keypress echo. ws.ts registers its "Session paused"
-     * resume hint here so it stays attached across recreations.
-     */
     closeListeners = [];
+    _pasteTransform = null;
     constructor() {
         this.rl = this._makeRl();
+        process.on("exit", () => {
+            process.stdout.write(BPASTE_DISABLE);
+            process.stdout.write("\x1b[?25h"); // never leave the cursor hidden on exit
+        });
     }
-    /** Hand the underlying readline to callers that need it for cleanup. */
     getRl() {
         return this.rl;
     }
-    /**
-     * Register a callback to fire when the rl reports a non-suppressed
-     * `close` event (the only one users observe is Ctrl+C at the main
-     * prompt — close-during-approval is suppressed via removeAllListeners
-     * before `rl.close()`). Callbacks are re-attached on every rl
-     * recreation so they outlive `promptApprovalMenu`.
-     */
     onRlClose(listener) {
         this.closeListeners.push(listener);
         this.rl.on("close", listener);
     }
-    /** Set the explicit current state. Drives spinner start/stop. */
     setState(next) {
         if (next === this.state)
             return;
         const prev = this.state;
         this.state = next;
-        // Transition out of any spinner state.
         if (prev === "generating" || prev === "running_tool") {
             this.stopSpinner();
         }
-        // Transition in.
         if (next === "generating") {
             this.startSpinner("thinking");
         }
         else if (next === "running_tool") {
             this.startSpinner("running tool");
         }
-        // `awaiting_approval` / `idle` => no spinner. Approval-menu path
-        // takes over stdin in `promptApprovalMenu`.
     }
     getState() {
         return this.state;
     }
-    /** Wait for one line of user input on the main rl. */
     promptLine() {
         return new Promise((resolve) => {
-            // Drop any previous one-shot listener that didn't fire.
             if (this.lineListener) {
                 this.rl.off("line", this.lineListener);
             }
@@ -174,49 +283,12 @@ class SessionUI {
             this.rl.once("line", listener);
         });
     }
-    /**
-     * Three-option numbered approval menu. Replaces the pre-#6509
-     * `[y/N]` one-shot prompt.
-     *
-     * Visual:
-     *   ❯ 1. Run
-     *     2. Run and don't ask again
-     *     3. Reject and tell Claude why
-     *     (1-3, ↑↓ Enter, Esc to reject)
-     *
-     * Controls:
-     *   - Number key 1/2/3       — one-shot select
-     *   - Arrow Up/Down          — move focus
-     *   - Enter                  — select focused
-     *   - Esc                    — equivalent to option 3 (reject)
-     *   - Ctrl+C                 — reject + propagate SIGINT (cancels session)
-     *
-     * The rl is closed before the menu render and recreated after. This
-     * physically removes readline's keypress echo from stdin for the
-     * duration of the menu — the bug fix the #6163 patch attempted via
-     * `rl.pause()` (which only stops `line` events, not the keypress
-     * echo). Persistent close listeners are stashed in
-     * `this.closeListeners` and re-attached on recreate; the close event
-     * triggered by THIS close() is suppressed via removeAllListeners
-     * before the call so it doesn't fire the "Session paused" hint.
-     *
-     * For option 3, after the menu resolves the recreated rl prompts
-     * once for a free-form rejection reason (line-mode). Empty input is
-     * allowed.
-     *
-     * The returned `allowlistRequested: true` (option 2) is a signal to
-     * the caller — PR2 wires it to write the pattern to
-     * `~/.xiaotime/settings.json`. PR1 callers may ignore it.
-     */
     async promptApprovalMenu(toolHeader) {
         this.setState("awaiting_approval");
+        this._destroyPasteTransform();
         if (toolHeader) {
             process.stdout.write(toolHeader);
         }
-        // Recreate the rl in `finally` so it ALWAYS lands — even if the
-        // no-TTY bail-out fires inside `_renderMenuAndGetSelection`. The
-        // next `promptLine` call needs a live rl regardless of how the
-        // menu resolved.
         let selectedIdx;
         try {
             selectedIdx = await this._renderMenuAndGetSelection();
@@ -224,9 +296,6 @@ class SessionUI {
         finally {
             this.rl = this._makeRl();
         }
-        // -1 → bail-out from `_renderMenuAndGetSelection` because stdin is
-        // not a TTY (CI / piped invocation / test runner). Skip the
-        // rejection-reason readline prompt because nothing would feed it.
         if (selectedIdx === -1) {
             return { approved: false, rejectReason: "(no TTY)" };
         }
@@ -238,82 +307,54 @@ class SessionUI {
             process.stdout.write(chalk_1.default.green("  ✓ Approved (allowlist requested)\n"));
             return { approved: true, allowlistRequested: true };
         }
-        // selectedIdx === 2 — rejection. Prompt for free-form reason via
-        // the recreated rl (line-mode, single line, empty allowed).
         process.stdout.write(chalk_1.default.yellow("  Reason (Enter to send empty): "));
         const reason = await new Promise((resolve) => {
             this.rl.once("line", (line) => resolve(line.trim()));
         });
         return { approved: false, rejectReason: reason };
     }
-    // ── Menu internals ───────────────────────────────────────────────
+    // ── PasteTransform lifecycle ──────────────────────────────────────────────
+    _destroyPasteTransform() {
+        if (this._pasteTransform) {
+            process.stdin.unpipe(this._pasteTransform);
+            this._pasteTransform.destroy();
+            this._pasteTransform = null;
+        }
+    }
+    // ── rl factory ───────────────────────────────────────────────────────────
     _makeRl() {
-        // SPRINT-CLI-INPUT-AND-TOOL-HARDENING-1 (#7299) PR2 — strip
-        // leftover keypress listeners on stdin before attaching a new rl.
-        //
-        // Background: `readline.createInterface({ terminal: true })`
-        // attaches its own keypress handler to `process.stdin` via
-        // `emitKeypressEvents` (Node internals). `rl.close()` is documented
-        // to detach that handler, but in practice — when a prior menu
-        // cycle toggled stdin between raw and cooked mode — Node's cleanup
-        // doesn't always run, leaving the prior rl's keypress listener
-        // attached. Each subsequent `_makeRl` call (post-#6509 happens
-        // once per approval-required tool call) adds another listener;
-        // every active listener independently echoes each keystroke
-        // through readline's `_ttyWrite`. N leaked listeners = N+1 echo
-        // on every key.
-        //
-        // Stephan observed 6-8x character multiplication after a session
-        // with several approval-menu cycles 2026-05-25 — directly traced
-        // to this accumulation. The fix is to strip "keypress" listeners
-        // explicitly before each recreate; readline's `createInterface`
-        // re-bootstraps `emitKeypressEvents` on the next call, so we
-        // don't lose the keypress-event infrastructure.
-        //
-        // Rejected alternatives — see #7299 Decisions D4: (B) switching
-        // to `terminal: false` post-menu (would need two rl modes), and
-        // (C) not recreating at all (reverts to the pre-#6509 double-echo
-        // bug). A is surgical + asserted by
-        // `ui_state_listener_lifecycle.test.ts`.
-        //
-        // `end` / `error` are stripped for the same reason — each
-        // `createInterface({ terminal: true })` registers one of each on
-        // stdin. `resize` is stripped on STDOUT, not stdin (readline
-        // attaches the resize handler to the output stream for terminal
-        // width tracking — verified empirically against Node 22). Without
-        // these explicit cleanups the listener counts cross Node's default
-        // MaxListeners (10) after ~11 recreations and log
-        // MaxListenersExceededWarning to stderr. They don't produce
-        // visible character echo (only keypress does) but they're the
-        // same root-cause leak and a one-line fix to include.
         process.stdin.removeAllListeners("keypress");
         process.stdin.removeAllListeners("end");
         process.stdin.removeAllListeners("error");
         process.stdout.removeAllListeners("resize");
+        process.stdout.write(BPASTE_ENABLE);
+        // Create PasteTransform, pipe stdin through it.
+        // Readline reads from pt.sink (a PassThrough) — NOT from the Transform
+        // directly. This prevents readline from calling emitKeypressEvents() on
+        // the transform, which would bypass our paste interception.
+        this._destroyPasteTransform();
+        const pt = new PasteTransform();
+        this._pasteTransform = pt;
+        process.stdin.pipe(pt);
         const rl = readline.createInterface({
-            input: process.stdin,
+            input: pt.sink, // readline reads from the safe PassThrough sink
             output: process.stdout,
             terminal: true,
         });
         for (const l of this.closeListeners) {
             rl.on("close", l);
         }
+        rl.on("close", () => {
+            process.stdout.write(BPASTE_DISABLE);
+            this._destroyPasteTransform();
+        });
         return rl;
     }
+    // ── Menu internals ────────────────────────────────────────────────────────
     async _renderMenuAndGetSelection() {
-        // Suppress the close-listener side effects for this internal
-        // close — we don't want the "Session paused" hint firing
-        // mid-approval. Stash the listeners on this.closeListeners so
-        // _makeRl can re-attach them after the menu resolves.
         this.rl.removeAllListeners("close");
         this.rl.close();
         const stdin = process.stdin;
-        // Bail BEFORE rendering the menu if stdin isn't a TTY. setRawMode
-        // can silently no-op on non-TTY stdin in some environments
-        // (vitest, piped invocation) — in that case the data listener
-        // would attach but never receive bytes, hanging the caller
-        // indefinitely. -1 sentinel tells promptApprovalMenu to skip the
-        // rejection-reason prompt (which would also hang).
         if (!stdin.isTTY) {
             process.stdout.write(chalk_1.default.red("Rejected (no TTY)\n"));
             return -1;
@@ -323,20 +364,12 @@ class SessionUI {
             stdin.setRawMode(true);
         }
         catch {
-            // Belt + suspenders — isTTY guard above should cover this, but a
-            // mid-session TTY loss could surface here.
             process.stdout.write(chalk_1.default.red("Rejected (no TTY)\n"));
             return -1;
         }
         stdin.resume();
         let focusedIdx = 0;
         this._renderMenu(focusedIdx);
-        // #6532 CR-r1: function-level finally guarantees onData removal +
-        // setRawMode restore even if the Promise body throws or the
-        // process is signalled. The previous design relied on every
-        // `finish()` call doing the cleanup, leaving leak windows when
-        // onData itself threw or when an awaiter rejected without
-        // routing through finish().
         let onData = null;
         try {
             return await new Promise((resolve, reject) => {
@@ -347,29 +380,18 @@ class SessionUI {
                 onData = (chunk) => {
                     try {
                         const s = chunk.toString();
-                        // Ctrl+C → reject + propagate SIGINT so the WS handler's
-                        // close path runs and the session ends cleanly.
                         if (s.includes("\x03")) {
                             finish(2);
                             process.kill(process.pid, "SIGINT");
                             return;
                         }
-                        // Allowlisted escape-prefixed sequences. Esc alone (no
-                        // `[`) → option 3 (reject). Arrow up/down rotate focus.
-                        // Any OTHER `\x1b`-prefixed input is explicitly rejected
-                        // (logged to stderr at debug level + ignored) per #6532
-                        // CR-r1: previously such sequences silently no-op'd,
-                        // which is currently safe due to the no-echo policy but
-                        // would become a terminal-injection vector if a future
-                        // diagnostic change started echoing unknown input.
                         if (s.charCodeAt(0) === 0x1b) {
                             if (s === "\x1b") {
                                 finish(2);
                                 return;
                             }
                             if (s === "\x1b[A") {
-                                focusedIdx =
-                                    (focusedIdx - 1 + MENU_OPTIONS.length) % MENU_OPTIONS.length;
+                                focusedIdx = (focusedIdx - 1 + MENU_OPTIONS.length) % MENU_OPTIONS.length;
                                 this._rerenderMenu(focusedIdx);
                                 return;
                             }
@@ -378,27 +400,20 @@ class SessionUI {
                                 this._rerenderMenu(focusedIdx);
                                 return;
                             }
-                            // Unrecognized escape sequence — log + ignore. Use the
-                            // hex form so a malicious paste of bell/CSI bytes is
-                            // not re-rendered through stderr.
                             const hex = Array.from(chunk)
                                 .map((b) => b.toString(16).padStart(2, "0"))
                                 .join(" ");
                             process.stderr.write(chalk_1.default.dim(`\n[approval-menu] ignored unrecognized escape: ${hex}\n`));
                             return;
                         }
-                        // Number-key one-shot selectors.
                         if (s === "1" || s === "2" || s === "3") {
                             finish(Number(s) - 1);
                             return;
                         }
-                        // Enter on focused row.
                         if (s === "\r" || s === "\n") {
                             finish(focusedIdx);
                             return;
                         }
-                        // Anything else — ignore. No echo, no bounce. The visible
-                        // menu stays put so the user can try again.
                     }
                     catch (err) {
                         reject(err);
@@ -408,18 +423,14 @@ class SessionUI {
             });
         }
         finally {
-            if (onData) {
+            if (onData)
                 stdin.removeListener("data", onData);
-            }
             try {
                 stdin.setRawMode(wasRaw);
             }
-            catch {
-                /* setRawMode can throw if stdin lost its TTY mid-session. */
-            }
+            catch { /* TTY lost mid-session */ }
         }
     }
-    /** Total lines the menu occupies: one per option + one hint line. */
     _menuLineCount() {
         return MENU_OPTIONS.length + 1;
     }
@@ -432,7 +443,6 @@ class SessionUI {
         process.stdout.write(chalk_1.default.dim(`  ${MENU_HINT}\n`));
     }
     _rerenderMenu(focusedIdx) {
-        // Move cursor up to top of menu, clear each line, redraw.
         const lines = this._menuLineCount();
         process.stdout.write(`\x1b[${lines}A`);
         for (let i = 0; i < MENU_OPTIONS.length; i++) {
@@ -452,19 +462,19 @@ class SessionUI {
             if (i < lines - 1)
                 process.stdout.write("\n");
         }
-        // Cursor left at start of the (now-cleared) first menu line so
-        // the post-selection echo lands there cleanly.
         process.stdout.write(`\x1b[${lines - 1}A\r`);
     }
-    // ── Spinner internals ────────────────────────────────────────────
+    // ── Spinner internals ─────────────────────────────────────────────────────
     startSpinner(label) {
         this.spinnerLabel = label;
         this.spinnerFrame = 0;
         this.spinnerStartedAt = Date.now();
         this.spinnerLineDirty = false;
+        // Hide the terminal cursor while the spinner animates. Without this the
+        // blinking hardware cursor jumps column-0 ↔ end on every \r repaint, which
+        // reads as a cursor "rapidly disappearing" next to the thinking label.
+        process.stdout.write("\x1b[?25l");
         this.spinnerTimer = setInterval(() => this.renderSpinnerFrame(), SPINNER_INTERVAL_MS);
-        // Render the first frame immediately so there's no perceptible
-        // delay between state-set and visible feedback.
         this.renderSpinnerFrame();
     }
     renderSpinnerFrame() {
@@ -473,10 +483,6 @@ class SessionUI {
         const elapsedStr = elapsed >= ELAPSED_THRESHOLD_MS
             ? chalk_1.default.dim(` (${Math.floor(elapsed / 1000)}s)`)
             : "";
-        // Clear-to-end-of-line (`\x1b[K`) after the spinner content
-        // rather than trailing spaces — robust against terminals where
-        // the last frame was longer than the current one (the trailing
-        // spaces approach left orphaned chars on shrinking labels).
         process.stdout.write(`\r${chalk_1.default.cyan(frame)} ${chalk_1.default.dim(this.spinnerLabel)}${elapsedStr}\x1b[K`);
         this.spinnerLineDirty = true;
         this.spinnerFrame++;
@@ -487,15 +493,11 @@ class SessionUI {
             this.spinnerTimer = null;
         }
         if (this.spinnerLineDirty) {
-            // Clear the spinner line so the next print doesn't overlap.
             process.stdout.write("\r\x1b[K");
             this.spinnerLineDirty = false;
         }
+        process.stdout.write("\x1b[?25h"); // restore cursor hidden by startSpinner
     }
-    /** Called by the text_delta renderer the first time a real model
-     * token arrives during a `generating` state. Clears the spinner so
-     * the token prints cleanly, but leaves the state at `generating`
-     * (token streaming continues without re-spinning). */
     onFirstToken() {
         if (this.spinnerLineDirty) {
             process.stdout.write("\r\x1b[K");
@@ -505,6 +507,7 @@ class SessionUI {
             clearInterval(this.spinnerTimer);
             this.spinnerTimer = null;
         }
+        process.stdout.write("\x1b[?25h"); // restore cursor hidden by startSpinner
     }
 }
 exports.SessionUI = SessionUI;