From dd09a383f191d68c8a702c1f48593b162667b3a3 Mon Sep 17 00:00:00 2001
From: DDT <141296842+Hugo-DDT@users.noreply.github.com>
Date: Tue, 27 Oct 2026 12:06:45 +0000
Subject: [PATCH 1/2] fix: stop desktop dead-key doubling and bracket Ctrl+V
 paste

KeyCode 229 recovery forwarded a composed character that xterm had
already delivered, so a desktop dead-key backtick arrived twice.
create() now attaches only when the primary pointer is coarse.

Ctrl+V text paste went through terminal.paste(), which drops the
CSI 200~/201~ markers after a replay clears xterm's DECSET 2004
mirror. Plain text is now a hand-built bracketed frame on the
session input path.

Fixes #716

Co-authored-by: DDT <1786035110@qq.com>
---
 docs/architecture-invariants.md               |   2 +-
 src/web/CLAUDE.md                             |   4 +-
 src/web/public/image-input.js                 |  60 +++++++++--
 .../public/terminal-keycode229-recovery.js    |  20 ++++
 src/web/public/terminal-tile.js               |   7 +-
 src/web/public/terminal-ui.js                 |   1 +
 test/image-paste-trap.test.ts                 | 102 ++++++++++++++++--
 ...rminal-keycode229-recovery.browser.test.ts |  35 ++++++
 test/terminal-keycode229-recovery.test.ts     |  46 +++++++-
 test/terminal-tile-input.test.ts              |  19 ++++
 10 files changed, 274 insertions(+), 22 deletions(-)

diff --git a/docs/architecture-invariants.md b/docs/architecture-invariants.md
index d4484540f..d8e4c1bc5 100644
--- a/docs/architecture-invariants.md
+++ b/docs/architecture-invariants.md
@@ -817,7 +817,7 @@ Feedback is silent on success except ONCE per page load (a feature that works by
 
 ### Terminal paste (Ctrl+V)
 
-**The Ctrl+V paste trap consumes exactly ONE paste event.** `_handleImagePaste()` (image-input.js) appends a hidden `contenteditable` div, focuses it, and reads the clipboard out of the paste event that lands there. An image becomes an upload whose saved path is typed into the session; text goes through `terminal.paste()`, so the bracketed-paste markers survive. Two independent routes deliver that event for one keypress, and a browser may fire both:
+**The Ctrl+V paste trap consumes exactly ONE paste event.** `_handleImagePaste()` (image-input.js) appends a hidden `contenteditable` div, focuses it, and reads the clipboard out of the paste event that lands there. An image becomes an upload whose saved path is typed into the session; plain text is a hand-built bracketed paste (`\x1b[200~` … `\x1b[201~`, nested markers stripped, newlines as `\r`) on the session input path (`_deliverBracketedPaste`). `terminal.paste()` only emits those markers while xterm's DECSET 2004 mirror is on, and a terminal replay clears that mirror (#716), so Ctrl+V builds the frame itself, the same way the mobile composer does. When the local-echo overlay owns that session's prompt, the unsent prefix is flushed first and the frame follows on a delay, which is the onData bracketed-paste ordering (#219). Two independent routes deliver that event for one keypress, and a browser may fire both:
 
 1. **`document.execCommand('paste')`**, which the function calls itself. ⚠️ Its return value proves nothing about whether it fired. Firefox dispatches a trusted `paste` event carrying the real clipboard and still returns `false`, because the trap cancels the event and the command therefore never completes. Chromium refuses the command outright and dispatches nothing.
 2. **The keydown's own default action.** The `Ctrl+V` branch in `attachCustomKeyEventHandler` returns `false`, which stops xterm from evaluating the key into `^V` but does not cancel the DOM event, for the same reason rule 1 of smart copy above spells out. `trap.focus()` has already run by then, so the browser sends its own paste to the trap as well.
diff --git a/src/web/CLAUDE.md b/src/web/CLAUDE.md
index e2c9cd1ed..c6090e222 100644
--- a/src/web/CLAUDE.md
+++ b/src/web/CLAUDE.md
@@ -20,7 +20,7 @@
 
 **OSC 52 clipboard** (`_installOsc52Clipboard`, terminal-ui.js; main terminal + every `TerminalTile`): a program in the PTY (Claude Code's `/copy`, tmux yanks, vim) sets the browser clipboard with `ESC ] 52`. ⚠️ Writes only: a `52;?` read query is always refused, never answered. ⚠️ A replay must never copy: `chunkedTerminalWrite` strips every OSC 52 (`OSC52_STRIP_RE`, constants.js) because xterm parses after `_isLoadingBuffer` is cleared, so the flag alone does not hold; a tile gates on its own `_bufferLoading`, which does. ⚠️ One copy arrives up to three times (Claude's own OSC 52, `tmux load-buffer -w`, set-clipboard forwarding), so identical text within `OSC52_DEDUPE_MS` is dropped. ⚠️ Every tab on the session receives it; only the focused one opens the manual-copy fallback. ⚠️ Restore prior focus after `_copyText` (its execCommand fallback focuses a temp textarea). Tests: `test/terminal-osc52-clipboard.test.ts` (replays drive the real `chunkedTerminalWrite` over `@xterm/headless`).
 
-**Ctrl+V paste trap** (`image-input.js`): `Ctrl+V` routes through `_handleImagePaste()`, which focuses a hidden `contenteditable` trap and reads the clipboard from the paste event landing there; images upload and their paths are typed in, text goes through `terminal.paste()` so bracketed-paste markers survive. ⚠️ **The trap must consume exactly ONE paste event** (Firefox delivers two per keypress: the `execCommand('paste')` event and the keydown's default action); the one-shot flag lives on the trap, never on a browser check. ⚠️ Do not remove the `execCommand('paste')` call: on some mobile engines it is the only route into the trap, and the trap is the only place image blobs are read. Tests: `test/image-paste-trap.test.ts`. → [architecture-invariants#terminal-paste-ctrlv](../../docs/architecture-invariants.md#terminal-paste-ctrlv)
+**Ctrl+V paste trap** (`image-input.js`): `Ctrl+V` routes through `_handleImagePaste()`, which focuses a hidden `contenteditable` trap and reads the clipboard from the paste event landing there; images upload and their paths are typed in, plain text is a hand-built bracketed paste on the session input path (`_deliverBracketedPaste`: strip nested 200/201 markers, newlines to `\r`, wrap CSI 200~/201~) because `terminal.paste()` drops those markers after a replay clears xterm's DECSET 2004 mirror (#716). When local echo owns the prompt, flush the unsent prefix first and delay the frame (#219). ⚠️ **The trap must consume exactly ONE paste event** (Firefox delivers two per keypress: the `execCommand('paste')` event and the keydown's default action); the one-shot flag lives on the trap, never on a browser check. ⚠️ Do not remove the `execCommand('paste')` call: on some mobile engines it is the only route into the trap, and the trap is the only place image blobs are read. Tests: `test/image-paste-trap.test.ts`. → [architecture-invariants#terminal-paste-ctrlv](../../docs/architecture-invariants.md#terminal-paste-ctrlv)
 
 **File Viewer text view: rendered markdown + Lines/Wrap toggles** (`_renderFilePreviewText()` in panels-ui.js): a `.md`/`.markdown` opens RENDERED by default with an `MD` pill back to source; the plain-text view has `Lines` (CSS-counter gutter) and `Wrap` toggles. ⚠️ ONE markdown pipeline: the viewer calls `_renderMarkdown(text, { breaks: false })` (marked + the DOMPurify allowlist, the Response Viewer's; chat keeps the default `breaks: true`, a file must not turn every hard wrap into a `<br>`) and binds the Response Viewer's click delegate (`_bindResponseViewerInteractions`) on the preview body for code-copy buttons and path links; never a second parser or handler. ⚠️ The document is built inside a `<template>` (a detached div with `innerHTML` set starts fetching every `<img src>` before the rewrite), then `_rebaseFilePreviewMarkdownRefs()` points relative images at the workspace-confined `file-raw` under the document's directory and root-relative ones under the workspace root (never a widened route; a failed load degrades to alt text), after `decodeURIComponent`ing the ref and dropping `?query`/`#fragment` (marked percent-encodes destinations, and the route encodes again), and turns workspace links into `a.rv-path` carrying `data-session-id` for the delegate (the linkifier's absolute paths get it too), stripping the `target` marked gave them. ⚠️ A preview opened by attachment id under a bare file name (attachment cards, history drawer: the registry keeps no relative path) has no directory, so its workspace refs degrade (images to alt text, links to their text), never resolve against the workspace root. ⚠️ The container carries `data-i18n-skip` or the translator rewrites the document's prose. ⚠️ Toggles are per-device localStorage keys (`codeman:filePreview*`), never `SettingsUpdateSchema`; Lines/Wrap are class flips on the ONE `<pre>`, with rules scoped `.file-preview-body > pre.file-preview-text` so they never leak into the document's code blocks. Markdown fetches `lines=10000` (the route ceiling), other text keeps 500. ⚠️ `md`/`markdown` are IN `FILE_PREVIEW_EXTENSIONS` (owner decision 2026-10-13): a markdown path clicked or tapped in the TERMINAL (main pane, grid tiles and split Pane B share `registerFilePathLinkProvider`) opens this rendered view like every other surface, never the streaming log viewer; other in-workspace text keeps the tail viewer (live follow). The terminal pattern links `.markdown` and `.htm` too. Tests: `test/file-preview-markdown.test.ts`. → [architecture-invariants#file-viewer-text-view-rendered-markdown-and-text-toggles](../../docs/architecture-invariants.md#file-viewer-text-view-rendered-markdown-and-text-toggles)
 
@@ -30,7 +30,7 @@
 
 ## Frontend modules and UI subsystems
 
-Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order is the `<script>` order in `index.html` (each module's `@loadorder` tag mirrors it). `i18n.js` translates static + newly inserted application DOM while skipping terminal/response/file/user-name surfaces; `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData). `terminal-keycode229-recovery.js` forwards a committed `input` event that xterm's `_inputEvent` guard drops (Chrome-on-Android soft keyboards send `composed: true` after a keydown), and only when xterm emitted no canonical data for that keystroke. ⚠️ **That decision is settled at the NEXT keydown as well as on its own zero-delay timer** (#441): the drain runs from xterm's custom key handler, which fires BEFORE xterm processes that key, so a soft keyboard that commits the last character and sends Enter in one InputConnection transaction puts the character on the wire ahead of the `\r`. On the timer alone that character is not merely late, it is LOST: xterm emits the `\r` first and bumps the canonical counter past the candidate's snapshot, so the candidate stands down (measured, `hell\r` where the user typed `hello`). The edit-based diff described below is settled first at that keydown, so the drain decides with the evidence the timer had and Enter's textarea clear cannot turn the pending line into DELs. Ordering is pinned by `test/terminal-keycode229-recovery.browser.test.ts`, which the CI gate does NOT run. The same module replaces xterm's `_handleAnyTextareaChanges` (an append-only `newValue.replace(oldValue, '')` diff) with an edit-based one, so an Android autocorrect on space (delete + insert) reaches the PTY once instead of duplicating the line; ⚠️ that diff is settled at the NEXT keydown, before xterm handles that key, because xterm clears the textarea for Enter and a pending diff would then send one DEL per character ahead of the submitted line (except a composition xterm finalizes synchronously at that key, which stays xterm's). ⚠️ Every xterm that takes keyboard input wires its OWN controller from this module: the primary pane (terminal-ui.js `initTerminal()`) and each `TerminalTile` (terminal-tile.js `_createKeyCode229Recovery()`, so every grid tile and the split's Pane B, which a wide Android tablet reaches), each on its own textarea, composition helper and session; in both, `handleKeyEvent` must run ABOVE the custom key handler's keyCode-229 early return, and `notifyCanonicalData` sits in the onData lambda, never in the send path the recovered bytes also take. `mobile-ime-preview.js` (iOS WebKit only) paints the text an IME is composing: an iOS IME commit is routed into the local-echo overlay through the ordinary printable/paste branch and then `_transferMobileImeCommitToLocalEcho`, and without local echo the preview clears only on output parsed AFTER the commit (or its 2 s fallback). ⚠️ It watches keydown in the capture phase on `terminal.element`, never on the textarea, because xterm finalizes the composition and emits the commit in its own capture listener on the textarea.
+Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order is the `<script>` order in `index.html` (each module's `@loadorder` tag mirrors it). `i18n.js` translates static + newly inserted application DOM while skipping terminal/response/file/user-name surfaces; `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData). `terminal-keycode229-recovery.js` forwards a committed `input` event that xterm's `_inputEvent` guard drops (Chrome-on-Android soft keyboards send `composed: true` after a keydown), and only when xterm emitted no canonical data for that keystroke. ⚠️ **That decision is settled at the NEXT keydown as well as on its own zero-delay timer** (#441): the drain runs from xterm's custom key handler, which fires BEFORE xterm processes that key, so a soft keyboard that commits the last character and sends Enter in one InputConnection transaction puts the character on the wire ahead of the `\r`. On the timer alone that character is not merely late, it is LOST: xterm emits the `\r` first and bumps the canonical counter past the candidate's snapshot, so the candidate stands down (measured, `hell\r` where the user typed `hello`). The edit-based diff described below is settled first at that keydown, so the drain decides with the evidence the timer had and Enter's textarea clear cannot turn the pending line into DELs. Ordering is pinned by `test/terminal-keycode229-recovery.browser.test.ts`, which the CI gate does NOT run. The same module replaces xterm's `_handleAnyTextareaChanges` (an append-only `newValue.replace(oldValue, '')` diff) with an edit-based one, so an Android autocorrect on space (delete + insert) reaches the PTY once instead of duplicating the line; ⚠️ that diff is settled at the NEXT keydown, before xterm handles that key, because xterm clears the textarea for Enter and a pending diff would then send one DEL per character ahead of the submitted line (except a composition xterm finalizes synchronously at that key, which stays xterm's). ⚠️ Every xterm that takes keyboard input wires its OWN controller from this module (`create()` returns null unless `matchMedia('(pointer: coarse)')` matches, so a desktop dead key is not forwarded twice, #716): the primary pane (terminal-ui.js `initTerminal()`) and each `TerminalTile` (terminal-tile.js `_createKeyCode229Recovery()`, so every grid tile and the split's Pane B, which a wide Android tablet reaches), each on its own textarea, composition helper and session; in both, `handleKeyEvent` must run ABOVE the custom key handler's keyCode-229 early return, and `notifyCanonicalData` sits in the onData lambda, never in the send path the recovered bytes also take. `mobile-ime-preview.js` (iOS WebKit only) paints the text an IME is composing: an iOS IME commit is routed into the local-echo overlay through the ordinary printable/paste branch and then `_transferMobileImeCommitToLocalEcho`, and without local echo the preview clears only on output parsed AFTER the commit (or its 2 s fallback). ⚠️ It watches keydown in the capture phase on `terminal.element`, never on the textarea, because xterm finalizes the composition and emits the commit in its own capture listener on the textarea.
 
 **Entrance animations** (`entrance-animations.js`, all OFF by default): opt-in animations for tabs, terminal, windows, connection lines and tile-grid tiles, chosen via `data-tab-anim` / `data-term-anim` / `data-win-anim` / `data-line-anim` / `data-tile-anim` on `<html>`; the default `legacy` theme short-circuits every hook (tiles keep the grid's own `settle`). ⚠️ Tabs and lines are destroyed mid-animation on re-render, so re-apply to the fresh element by id with a negative `animation-delay` (resume, never restart). ⚠️ Terminal-pane styles may animate only transform / opacity / clip-path (anything else resizes the PTY via FitAddon); `blur` is the ONE sanctioned `filter` exception, do not generalise it. ⚠️ Line glow lives in `--line-glow` so blur keyframes interpolate. Every animation setting lives in App Settings → **Animations** (`#settings-animations`); put new ones there. ⚠️ Tiles are OFF by default (Animations → Tile Animations, default `settle` = the grid's own fade, no screen beat); a theme only presets it. A tile's FRAME animates transform/opacity only (six at once, no filter) with `tile-enter*`/`tile-leave*` keyframe names (what the mount and the still copy listen for); its SCREEN replays the pane style on `.tile-body.term-enter`; a reload's restore always settles. Persisted per-device in `codeman:*Anim` localStorage keys, never in `SettingsUpdateSchema`; lab at `?animlab=1`. Test: `test/entrance-animations.test.ts`. → [architecture-invariants#entrance-animations](../../docs/architecture-invariants.md#entrance-animations)
 
diff --git a/src/web/public/image-input.js b/src/web/public/image-input.js
index a0ec33c32..d2d5fd603 100644
--- a/src/web/public/image-input.js
+++ b/src/web/public/image-input.js
@@ -244,14 +244,14 @@ Object.assign(CodemanApp.prototype, {
 
       if (imageFiles.length > 0) {
         self._uploadAndInsertImages(imageFiles, { sessionId: sessionId });
-      } else {
-        // No image -- route text through xterm's paste() so bracketed-paste
-        // markers (CSI 200~ ... CSI 201~) survive when the inner application
-        // has enabled bracketed-paste mode (Claude Code does). Sending text
-        // via raw sendInput() strips those markers and makes pasted input
-        // indistinguishable from typed input, weakening the CLI's
-        // prompt-injection defenses.
-        if (text && terminal) terminal.paste(text);
+      } else if (text) {
+        // No image. xterm's paste() emits CSI 200~/201~ only while its DECSET
+        // 2004 mirror is on, and a terminal replay clears that mirror, so the
+        // markers never arrive and a copied newline submits (#716). Build the
+        // frame here, the same bytes keyboard-accessory.js sends, and deliver
+        // it on the session input path. Do not useMux: the mux fallback strips
+        // every \r, which is the line separator inside the frame.
+        self._deliverBracketedPaste(sessionId, text);
       }
     });
 
@@ -260,6 +260,50 @@ Object.assign(CodemanApp.prototype, {
     document.execCommand('paste');
   },
 
+  /**
+   * Plain-text Ctrl+V as one bracketed paste on the session-bound input path.
+   * Mirrors keyboard-accessory.js `_sendBracketedPaste`: drop nested 200/201
+   * markers (a clipboard carrying ESC[201~ would end the bracket early), map
+   * newlines to CR (what xterm's prepareTextForTerminal did), wrap with
+   * CSI 200~ / CSI 201~. The composer's length cap is not applied here;
+   * `_sendInputAsync` already splits a large paste and refuses one past its
+   * own ceiling.
+   *
+   * When the local-echo overlay owns this session's prompt, flush its unsent
+   * text first and delay the frame. That is the onData bracketed-paste branch
+   * (#219): Codex drops bytes that share a PTY read with a bracketed paste,
+   * and the typed prefix has to land ahead of the block.
+   */
+  _deliverBracketedPaste(sessionId, text) {
+    if (!sessionId || typeof text !== 'string' || text === '' || typeof this._sendInputAsync !== 'function') return;
+    try {
+      this._predictiveEcho?.clearPredictions?.();
+    } catch {
+      // Predictions are visual only.
+    }
+    const pasteText = text.replace(/\x1b\[20[01]~/g, '').replace(/\r?\n/g, '\r');
+    const framed = `\x1b[200~${pasteText}\x1b[201~`;
+    const echoOwns =
+      this.activeSessionId === sessionId &&
+      this._localEchoEnabled &&
+      this._localEchoOverlay &&
+      !this._echoPassthroughSessions?.has?.(sessionId) &&
+      !this._tilesOwnTerminal?.() &&
+      typeof this._flushLocalEchoPending === 'function';
+    if (echoOwns) {
+      const hadPending = !!this._localEchoOverlay.pendingText;
+      this._flushLocalEchoPending();
+      if (hadPending) {
+        const prefix = this._pendingInput || '';
+        this._pendingInput = '';
+        if (prefix) this._sendInputAsync(sessionId, prefix);
+        setTimeout(() => this._sendInputAsync(sessionId, framed), 80);
+        return;
+      }
+    }
+    this._sendInputAsync(sessionId, framed);
+  },
+
   /** What a pick or a paste may upload: 'image', 'video' for the camera roll's
    *  clips (the server streams those to disk under their own cap), 'document'
    *  for the office and text files the server admits, else null. The one filter
diff --git a/src/web/public/terminal-keycode229-recovery.js b/src/web/public/terminal-keycode229-recovery.js
index 22e44cbac..43d84ddb9 100644
--- a/src/web/public/terminal-keycode229-recovery.js
+++ b/src/web/public/terminal-keycode229-recovery.js
@@ -7,6 +7,13 @@
  * that guard, so xterm returns without emitting and the committed character is
  * silently dropped.
  *
+ * ⚠ Desktop fine pointers must not run this (#716). xterm already forwards the
+ * composed character, and a second forward doubles a dead-key backtick.
+ * `create()` returns null unless `matchMedia('(pointer: coarse)')` matches, so
+ * soft keyboards keep the recovery and a desktop does not attach it. A missing
+ * or throwing `matchMedia` stands down: a missed recovery is acceptable, a
+ * duplicated keystroke is not.
+ *
  * ⚠ The gap is NARROWER than "keyCode 229", and assuming otherwise produces a
  * controller that looks useful while doing nothing. For a keydown that really
  * does report `keyCode: 229`, xterm ALREADY self-rescues: `CompositionHelper
@@ -64,7 +71,20 @@
     return { deleted: a.length - prefix, inserted: b.slice(prefix).join('') };
   }
 
+  /**
+   * Touch / coarse pointer only. See the file header: on a fine pointer this
+   * forward runs on top of xterm's own composition handling.
+   */
+  function isCoarsePointer() {
+    try {
+      return global.matchMedia?.('(pointer: coarse)')?.matches === true;
+    } catch {
+      return false;
+    }
+  }
+
   function create(options) {
+    if (!isCoarsePointer()) return null;
     const textarea = options?.textarea;
     const emitRecovered = options?.emitRecovered;
     if (!textarea?.addEventListener || !textarea?.removeEventListener || typeof emitRecovered !== 'function') {
diff --git a/src/web/public/terminal-tile.js b/src/web/public/terminal-tile.js
index e08e26f6c..ba24ec51d 100644
--- a/src/web/public/terminal-tile.js
+++ b/src/web/public/terminal-tile.js
@@ -646,9 +646,10 @@
     // Recovered text goes straight to _onTerminalData(), never through xterm's
     // onData, so it is not counted as xterm's own (see connect()'s onData).
     // Created after terminal.open(): xterm's capture `input` listener on the
-    // textarea is registered there, and must run before the controller's. No
-    // device or mode gate, as in the primary pane: with a hardware keyboard it
-    // costs one assignment per keydown. A failure leaves xterm's own handling.
+    // textarea is registered there, and must run before the controller's.
+    // create() returns null on a fine pointer (#716): the recovery is for soft
+    // keyboards, and on a desktop it delivers a dead-key character twice.
+    // A failure leaves xterm's own handling.
     _createKeyCode229Recovery() {
       this._destroyKeyCode229Recovery();
       if (!this.terminal) return;
diff --git a/src/web/public/terminal-ui.js b/src/web/public/terminal-ui.js
index deb704af4..0a37bc46e 100644
--- a/src/web/public/terminal-ui.js
+++ b/src/web/public/terminal-ui.js
@@ -2108,6 +2108,7 @@ Object.assign(CodemanApp.prototype, {
     // Twin: TerminalTile (terminal-tile.js _createKeyCode229Recovery and its
     // connect() key handler and onData) wires its own controller the same way
     // for every grid tile and the split's Pane B; keep the two in step.
+    // create() returns null unless the primary pointer is coarse (#716).
     try {
       this._keyCode229Recovery = window.CodemanKeyCode229Recovery?.create?.({
         textarea: this.terminal.textarea,
diff --git a/test/image-paste-trap.test.ts b/test/image-paste-trap.test.ts
index 93370ae3e..238a0d4c2 100644
--- a/test/image-paste-trap.test.ts
+++ b/test/image-paste-trap.test.ts
@@ -33,11 +33,20 @@ interface FakeTrap {
   addEventListener: (ev: string, fn: TrapListener) => void;
 }
 
+interface SentInput {
+  sessionId: string;
+  data: string;
+}
+
 interface Harness {
   /** Fire a paste event on the trap the last _handleImagePaste() call created. */
   firePaste: (payload: { text?: string; images?: string[] }) => void;
   /** Text handed to xterm's terminal.paste(), one entry per call. */
   pastedText: string[];
+  /** Frames handed to _sendInputAsync(), in order. */
+  sentInputs: SentInput[];
+  /** How many times predictive-echo predictions were cleared. */
+  predictionsCleared: () => number;
   /** Image batches handed to _uploadAndInsertImages(), one entry per call. */
   uploadedBatches: Array<Array<{ type: string }>>;
   /** Messages handed to showToast(), one entry per call. */
@@ -47,7 +56,14 @@ interface Harness {
   runTimers: () => void;
 }
 
-function loadPasteHarness(): Harness {
+interface PasteHarnessOptions {
+  /** Session the paste trap is aimed at. Defaults to the active session. */
+  sessionId?: string;
+  /** Unsent overlay text. Enables the local-echo flush path when set. */
+  localEchoPending?: string;
+}
+
+function loadPasteHarness(options: PasteHarnessOptions = {}): Harness {
   const traps: FakeTrap[] = [];
   const listeners: TrapListener[] = [];
   const attached = new Set<FakeTrap>();
@@ -99,20 +115,51 @@ function loadPasteHarness(): Harness {
   const CodemanApp = vm.runInContext('CodemanApp', context) as new () => Record<string, unknown>;
 
   const pastedText: string[] = [];
+  const sentInputs: SentInput[] = [];
   const uploadedBatches: Array<Array<{ type: string }>> = [];
+  let predictionsCleared = 0;
   const app = new CodemanApp();
   app.activeSessionId = 'session-1';
+  // Replay leaves xterm's DECSET 2004 mirror off. Text must still go out bracketed,
+  // and must not ask terminal.paste() to consult that mirror (#716).
   app.terminal = {
     paste: (text: string) => pastedText.push(text),
     focus: () => {},
+    modes: { bracketedPasteMode: false },
   };
+  app._sendInputAsync = (sessionId: string, data: string) => {
+    sentInputs.push({ sessionId, data });
+  };
+  app._predictiveEcho = { clearPredictions: () => { predictionsCleared += 1; } };
   app._uploadAndInsertImages = (files: Array<{ type: string }>) => {
     uploadedBatches.push(Array.from(files));
   };
+  if (options.localEchoPending !== undefined) {
+    app._localEchoEnabled = true;
+    app._pendingInput = '';
+    app._localEchoOverlay = {
+      pendingText: options.localEchoPending,
+      clear() {
+        this.pendingText = '';
+      },
+      suppressBufferDetection() {},
+    };
+    app._flushedOffsets = new Map();
+    app._flushedTexts = new Map();
+    app._flushLocalEchoPending = function (this: Record<string, any>) {
+      const pending = this._localEchoOverlay?.pendingText || '';
+      this._localEchoOverlay.clear();
+      this._localEchoOverlay.suppressBufferDetection();
+      this._flushedOffsets?.delete(this.activeSessionId);
+      this._flushedTexts?.delete(this.activeSessionId);
+      if (pending) this._pendingInput += pending;
+    };
+  }
   const toasts: string[] = [];
   app.showToast = (message: string) => toasts.push(message);
 
-  (app._handleImagePaste as () => void).call(app);
+  const target = options.sessionId ? { terminal: app.terminal, sessionId: options.sessionId } : undefined;
+  (app._handleImagePaste as (t?: object) => void).call(app, target);
 
   return {
     firePaste({ text = '', images = [] }) {
@@ -128,6 +175,8 @@ function loadPasteHarness(): Harness {
       for (const fn of listeners) fn(event);
     },
     pastedText,
+    sentInputs,
+    predictionsCleared: () => predictionsCleared,
     uploadedBatches,
     toasts,
     attachedTraps: () => attached.size,
@@ -154,12 +203,50 @@ function loadImageInputApp() {
 }
 
 describe('Ctrl+V paste trap', () => {
-  it('sends clipboard text to the terminal once for a single paste event', () => {
+  it('sends clipboard text once as a bracketed paste, not through xterm paste()', () => {
     const h = loadPasteHarness();
 
     h.firePaste({ text: 'hello world' });
 
-    expect(h.pastedText).toEqual(['hello world']);
+    // terminal.paste() would drop the markers: the harness mirror is off, which
+    // is what a replay leaves behind.
+    expect(h.pastedText).toEqual([]);
+    expect(h.sentInputs).toEqual([{ sessionId: 'session-1', data: '\x1b[200~hello world\x1b[201~' }]);
+    expect(h.predictionsCleared()).toBe(1);
+  });
+
+  it('brackets a multi-line paste and strips nested paste markers', () => {
+    const h = loadPasteHarness();
+
+    h.firePaste({ text: 'line one\nline two\r\n\x1b[200~nested\x1b[201~\n' });
+
+    expect(h.pastedText).toEqual([]);
+    expect(h.sentInputs).toEqual([
+      { sessionId: 'session-1', data: '\x1b[200~line one\rline two\rnested\r\x1b[201~' },
+    ]);
+  });
+
+  it('addresses the bracketed paste to the pane that received Ctrl+V', () => {
+    const h = loadPasteHarness({ sessionId: 'pane-b' });
+
+    h.firePaste({ text: 'into pane b' });
+
+    expect(h.sentInputs).toEqual([{ sessionId: 'pane-b', data: '\x1b[200~into pane b\x1b[201~' }]);
+    expect(h.pastedText).toEqual([]);
+  });
+
+  it('flushes unsent local-echo text ahead of the bracketed paste', () => {
+    const h = loadPasteHarness({ localEchoPending: 'hi' });
+
+    h.firePaste({ text: 'world\n' });
+
+    expect(h.sentInputs).toEqual([{ sessionId: 'session-1', data: 'hi' }]);
+    h.runTimers();
+    expect(h.sentInputs).toEqual([
+      { sessionId: 'session-1', data: 'hi' },
+      { sessionId: 'session-1', data: '\x1b[200~world\r\x1b[201~' },
+    ]);
+    expect(h.pastedText).toEqual([]);
   });
 
   it('ignores a second paste event for the same Ctrl+V', () => {
@@ -170,7 +257,8 @@ describe('Ctrl+V paste trap', () => {
     h.firePaste({ text: 'hello world' });
     h.firePaste({ text: 'hello world' });
 
-    expect(h.pastedText).toEqual(['hello world']);
+    expect(h.sentInputs).toEqual([{ sessionId: 'session-1', data: '\x1b[200~hello world\x1b[201~' }]);
+    expect(h.pastedText).toEqual([]);
   });
 
   it('uploads a pasted image once when the trap sees two paste events', () => {
@@ -182,6 +270,7 @@ describe('Ctrl+V paste trap', () => {
     expect(h.uploadedBatches).toHaveLength(1);
     expect(h.uploadedBatches[0]).toEqual([{ type: 'image/png' }]);
     expect(h.pastedText).toEqual([]);
+    expect(h.sentInputs).toEqual([]);
   });
 
   it('a paste mixing an image with a refused file uploads the image and says what it skipped', () => {
@@ -199,7 +288,8 @@ describe('Ctrl+V paste trap', () => {
     // Copying from a document can carry both: the text is what the user gets.
     h.firePaste({ text: 'echo hi', images: ['application/x-sh'] });
 
-    expect(h.pastedText).toEqual(['echo hi']);
+    expect(h.sentInputs).toEqual([{ sessionId: 'session-1', data: '\x1b[200~echo hi\x1b[201~' }]);
+    expect(h.pastedText).toEqual([]);
     expect(h.uploadedBatches).toEqual([]);
     expect(h.toasts).toEqual([]);
   });
diff --git a/test/terminal-keycode229-recovery.browser.test.ts b/test/terminal-keycode229-recovery.browser.test.ts
index c17186b10..e0883b651 100644
--- a/test/terminal-keycode229-recovery.browser.test.ts
+++ b/test/terminal-keycode229-recovery.browser.test.ts
@@ -40,6 +40,29 @@ describe('orphaned terminal input recovery wiring', () => {
     baseUrl = `http://localhost:${server.boundPort}`;
     browser = await chromium.launch({ headless: true });
     page = await browser.newPage();
+    // Headless Chromium is a fine pointer, and create() then returns null (#716).
+    // The recovery cases below are the soft-keyboard path, so this page reports
+    // a coarse pointer. Other media queries stay native.
+    await page.addInitScript(() => {
+      const native = window.matchMedia.bind(window);
+      window.matchMedia = (query: string) => {
+        if (query === '(pointer: coarse)') {
+          return {
+            matches: true,
+            media: query,
+            onchange: null,
+            addListener() {},
+            removeListener() {},
+            addEventListener() {},
+            removeEventListener() {},
+            dispatchEvent() {
+              return false;
+            },
+          };
+        }
+        return native(query);
+      };
+    });
     await page.goto(baseUrl, { waitUntil: 'domcontentloaded' });
     await page.waitForFunction(() => (window as any).app?.terminal, null, { timeout: 30000 });
     await page.waitForFunction(() => (window as any).app?._keyCode229Recovery, null, { timeout: 30000 });
@@ -50,6 +73,18 @@ describe('orphaned terminal input recovery wiring', () => {
     if (server) await server.stop();
   }, 60000);
 
+  it('does not install recovery when the primary pointer is fine', async () => {
+    const fine = await browser.newPage();
+    try {
+      await fine.goto(baseUrl, { waitUntil: 'domcontentloaded' });
+      await fine.waitForFunction(() => (window as any).app?.terminal?.textarea, null, { timeout: 30000 });
+      const installed = await fine.evaluate(() => (window as any).app?._keyCode229Recovery ?? null);
+      expect(installed).toBeNull();
+    } finally {
+      await fine.close();
+    }
+  });
+
   /**
    * Drive one keystroke through the real textarea and report what reached the
    * PTY send path. `dispatchInput` mirrors GBoard: a keydown with no usable key
diff --git a/test/terminal-keycode229-recovery.test.ts b/test/terminal-keycode229-recovery.test.ts
index 777fc0d76..57bb72ccb 100644
--- a/test/terminal-keycode229-recovery.test.ts
+++ b/test/terminal-keycode229-recovery.test.ts
@@ -46,9 +46,19 @@ function inputEvent(data: string, overrides: Record<string, unknown> = {}) {
   return { data, inputType: 'insertText', isComposing: false, ...overrides };
 }
 
-function harness({ screenReader = false } = {}) {
+function harness({ screenReader = false, coarse = true, matchMedia = true } = {}) {
   const source = readFileSync(new URL('../src/web/public/terminal-keycode229-recovery.js', import.meta.url), 'utf8');
   const exposed: Record<string, any> = {};
+  if (matchMedia) {
+    // create() attaches only for a coarse pointer (#716). The recovery cases
+    // below are the soft-keyboard behaviour, so they opt in. A fine pointer
+    // (or no matchMedia at all) must get null and no listeners.
+    exposed.matchMedia = (query: string) => ({
+      matches: query === '(pointer: coarse)' && coarse,
+      addEventListener() {},
+      removeEventListener() {},
+    });
+  }
   vm.runInNewContext(source, { window: exposed, globalThis: exposed }, { filename: 'terminal-keycode229-recovery.js' });
 
   const textarea = makeTextarea();
@@ -111,6 +121,31 @@ function loadTerminalInput() {
 }
 
 describe('orphaned terminal input recovery', () => {
+  it('does not attach on a fine pointer, so a desktop dead key is not forwarded twice', () => {
+    const h = harness({ coarse: false });
+    expect(h.controller).toBeNull();
+    expect(h.textarea.listenerCount()).toBe(0);
+    expect(h.textarea.registrations()).toEqual([]);
+  });
+
+  it('does not attach when matchMedia is missing', () => {
+    // Fail closed. Treating "unknown" as coarse would put the recovery back on
+    // a desktop whose matchMedia threw, which is the doubled backtick.
+    const h = harness({ matchMedia: false });
+    expect(h.controller).toBeNull();
+    expect(h.textarea.listenerCount()).toBe(0);
+  });
+
+  it('still recovers a dropped insertText on a coarse pointer', () => {
+    const h = harness({ coarse: true });
+    h.keydown();
+    h.input('`');
+    expect(h.emitted).toEqual([]);
+    h.flushTimers();
+    expect(h.emitted).toEqual(['`']);
+    expect(h.textarea.listenerCount()).toBeGreaterThan(0);
+  });
+
   it('forwards the committed text when xterm stayed silent', () => {
     const h = harness();
     h.keydown();
@@ -432,7 +467,14 @@ describe('terminal-ui wiring: what counts as "xterm spoke for this keystroke"',
  */
 function editSyncHarness() {
   const source = readFileSync(new URL('../src/web/public/terminal-keycode229-recovery.js', import.meta.url), 'utf8');
-  const exposed: Record<string, any> = {};
+  const exposed: Record<string, any> = {
+    // Autocorrect recovery is the coarse-pointer (soft keyboard) path.
+    matchMedia: (query: string) => ({
+      matches: query === '(pointer: coarse)',
+      addEventListener() {},
+      removeEventListener() {},
+    }),
+  };
   vm.runInNewContext(source, { window: exposed, globalThis: exposed }, { filename: 'terminal-keycode229-recovery.js' });
 
   const textarea = Object.assign(makeTextarea(), { value: '' });
diff --git a/test/terminal-tile-input.test.ts b/test/terminal-tile-input.test.ts
index a670228c4..4df588d3f 100644
--- a/test/terminal-tile-input.test.ts
+++ b/test/terminal-tile-input.test.ts
@@ -48,6 +48,17 @@ function loadContext() {
     // would run against no controller at all.
     setTimeout: (fn: () => void, ms?: number) => globalThis.setTimeout(fn, ms),
     clearTimeout: (id: ReturnType<typeof setTimeout>) => globalThis.clearTimeout(id),
+    // The real controller attaches only for a coarse pointer (#716). Tile tests
+    // that exercise soft-keyboard recovery opt in; a test sets this false to
+    // prove a desktop fine pointer installs nothing.
+    __coarsePointer: true,
+    matchMedia(query: string) {
+      return {
+        matches: query === '(pointer: coarse)' && windowStub.__coarsePointer !== false,
+        addEventListener() {},
+        removeEventListener() {},
+      };
+    },
   };
   const context = vm.createContext({
     console: { ...console, log: vi.fn(), debug: vi.fn() },
@@ -151,6 +162,7 @@ afterEach(() => {
 });
 
 beforeEach(() => {
+  windowStub.__coarsePointer = true;
   FakeTerminal.coreFactory = null;
   FakeFit.proposed = { cols: 80, rows: 24 };
   FakeSocket.instances = [];
@@ -1183,6 +1195,13 @@ function lineOf(frames: Array<{ d?: string }>) {
 type ControllerTile = Tile & { _keyCode229Recovery: unknown };
 
 describe("TerminalTile wires the primary pane's soft-keyboard controller (#441, #541)", () => {
+  it('does not install the controller on a fine pointer', async () => {
+    windowStub.__coarsePointer = false;
+    const { tile, term } = await connectTile(makeApp());
+    expect((tile as ControllerTile)._keyCode229Recovery).toBeNull();
+    expect(term.textareaListeners).toEqual([]);
+  });
+
   it("installs on THIS tile's composition helper and textarea, and destroy() restores xterm's own", async () => {
     const helpers = withCompositionHelpers();
     const { tile, term } = await connectTile(makeApp());

From 6f820ca9908e33ff9afa6867a3406f6bb60111f1 Mon Sep 17 00:00:00 2001
From: DDT <141296842+Hugo-DDT@users.noreply.github.com>
Date: Wed, 28 Oct 2026 07:09:35 +0000
Subject: [PATCH 2/2] fix: deliver Ctrl+V paste through terminal.input

Hand the bracketed frame to the target terminal with input() so onData
scrolls to the bottom, clears the selection, and delivers the bytes.
The paste trap no longer writes the frame itself.

Fixes #716

Co-authored-by: DDT <1786035110@qq.com>
---
 docs/architecture-invariants.md  |   2 +-
 src/web/CLAUDE.md                |   2 +-
 src/web/public/image-input.js    |  62 ++++--------------
 src/web/public/terminal-tile.js  |   7 +-
 test/image-paste-trap.test.ts    | 106 +++++++++++++++++++++++--------
 test/terminal-tile-input.test.ts |  21 ++++++
 6 files changed, 120 insertions(+), 80 deletions(-)

diff --git a/docs/architecture-invariants.md b/docs/architecture-invariants.md
index d8e4c1bc5..ae7250502 100644
--- a/docs/architecture-invariants.md
+++ b/docs/architecture-invariants.md
@@ -817,7 +817,7 @@ Feedback is silent on success except ONCE per page load (a feature that works by
 
 ### Terminal paste (Ctrl+V)
 
-**The Ctrl+V paste trap consumes exactly ONE paste event.** `_handleImagePaste()` (image-input.js) appends a hidden `contenteditable` div, focuses it, and reads the clipboard out of the paste event that lands there. An image becomes an upload whose saved path is typed into the session; plain text is a hand-built bracketed paste (`\x1b[200~` … `\x1b[201~`, nested markers stripped, newlines as `\r`) on the session input path (`_deliverBracketedPaste`). `terminal.paste()` only emits those markers while xterm's DECSET 2004 mirror is on, and a terminal replay clears that mirror (#716), so Ctrl+V builds the frame itself, the same way the mobile composer does. When the local-echo overlay owns that session's prompt, the unsent prefix is flushed first and the frame follows on a delay, which is the onData bracketed-paste ordering (#219). Two independent routes deliver that event for one keypress, and a browser may fire both:
+**The Ctrl+V paste trap consumes exactly ONE paste event.** `_handleImagePaste()` (image-input.js) appends a hidden `contenteditable` div, focuses it, and reads the clipboard out of the paste event that lands there. An image becomes an upload whose saved path is typed into the session; plain text is a Codeman-built bracketed paste (`\x1b[200~` … `\x1b[201~`, nested markers stripped, newlines as `\r`) handed to that pane's terminal via `terminal.input(framed)`. `terminal.paste()` only emits those markers while xterm's DECSET 2004 mirror is on, and a terminal replay clears that mirror (#716), so Ctrl+V builds the frame itself. `input()` fires onData as user input, which scrolls to the bottom and clears the selection. The main pane's onData bracketed-paste branch and a tile's `_onTerminalData` deliver the frame, which is where the local-echo flush and the delayed write live (#219). A frame wrapped in CSI 200~/201~ does not match the query-reply or mouse-report filters. The terminal is refocused; the paste is not written into the xterm buffer. Two independent routes deliver that event for one keypress, and a browser may fire both:
 
 1. **`document.execCommand('paste')`**, which the function calls itself. ⚠️ Its return value proves nothing about whether it fired. Firefox dispatches a trusted `paste` event carrying the real clipboard and still returns `false`, because the trap cancels the event and the command therefore never completes. Chromium refuses the command outright and dispatches nothing.
 2. **The keydown's own default action.** The `Ctrl+V` branch in `attachCustomKeyEventHandler` returns `false`, which stops xterm from evaluating the key into `^V` but does not cancel the DOM event, for the same reason rule 1 of smart copy above spells out. `trap.focus()` has already run by then, so the browser sends its own paste to the trap as well.
diff --git a/src/web/CLAUDE.md b/src/web/CLAUDE.md
index c6090e222..b6aae1ebe 100644
--- a/src/web/CLAUDE.md
+++ b/src/web/CLAUDE.md
@@ -20,7 +20,7 @@
 
 **OSC 52 clipboard** (`_installOsc52Clipboard`, terminal-ui.js; main terminal + every `TerminalTile`): a program in the PTY (Claude Code's `/copy`, tmux yanks, vim) sets the browser clipboard with `ESC ] 52`. ⚠️ Writes only: a `52;?` read query is always refused, never answered. ⚠️ A replay must never copy: `chunkedTerminalWrite` strips every OSC 52 (`OSC52_STRIP_RE`, constants.js) because xterm parses after `_isLoadingBuffer` is cleared, so the flag alone does not hold; a tile gates on its own `_bufferLoading`, which does. ⚠️ One copy arrives up to three times (Claude's own OSC 52, `tmux load-buffer -w`, set-clipboard forwarding), so identical text within `OSC52_DEDUPE_MS` is dropped. ⚠️ Every tab on the session receives it; only the focused one opens the manual-copy fallback. ⚠️ Restore prior focus after `_copyText` (its execCommand fallback focuses a temp textarea). Tests: `test/terminal-osc52-clipboard.test.ts` (replays drive the real `chunkedTerminalWrite` over `@xterm/headless`).
 
-**Ctrl+V paste trap** (`image-input.js`): `Ctrl+V` routes through `_handleImagePaste()`, which focuses a hidden `contenteditable` trap and reads the clipboard from the paste event landing there; images upload and their paths are typed in, plain text is a hand-built bracketed paste on the session input path (`_deliverBracketedPaste`: strip nested 200/201 markers, newlines to `\r`, wrap CSI 200~/201~) because `terminal.paste()` drops those markers after a replay clears xterm's DECSET 2004 mirror (#716). When local echo owns the prompt, flush the unsent prefix first and delay the frame (#219). ⚠️ **The trap must consume exactly ONE paste event** (Firefox delivers two per keypress: the `execCommand('paste')` event and the keydown's default action); the one-shot flag lives on the trap, never on a browser check. ⚠️ Do not remove the `execCommand('paste')` call: on some mobile engines it is the only route into the trap, and the trap is the only place image blobs are read. Tests: `test/image-paste-trap.test.ts`. → [architecture-invariants#terminal-paste-ctrlv](../../docs/architecture-invariants.md#terminal-paste-ctrlv)
+**Ctrl+V paste trap** (`image-input.js`): `Ctrl+V` routes through `_handleImagePaste()`, which focuses a hidden `contenteditable` trap and reads the clipboard from the paste event landing there; images upload and their paths are typed in, plain text is a Codeman-built bracketed paste handed to that pane's terminal via `terminal.input(framed)` (strip nested 200/201 markers, newlines to `\r`, wrap CSI 200~/201~) because `terminal.paste()` drops those markers after a replay clears xterm's DECSET 2004 mirror (#716). `input()` fires onData as user input, so the main pane's bracketed-paste branch and a tile's `_onTerminalData` deliver the frame, including the local-echo flush (#219). The terminal is only refocused. ⚠️ **The trap must consume exactly ONE paste event** (Firefox delivers two per keypress: the `execCommand('paste')` event and the keydown's default action); the one-shot flag lives on the trap, never on a browser check. ⚠️ Do not remove the `execCommand('paste')` call: on some mobile engines it is the only route into the trap, and the trap is the only place image blobs are read. Tests: `test/image-paste-trap.test.ts`. → [architecture-invariants#terminal-paste-ctrlv](../../docs/architecture-invariants.md#terminal-paste-ctrlv)
 
 **File Viewer text view: rendered markdown + Lines/Wrap toggles** (`_renderFilePreviewText()` in panels-ui.js): a `.md`/`.markdown` opens RENDERED by default with an `MD` pill back to source; the plain-text view has `Lines` (CSS-counter gutter) and `Wrap` toggles. ⚠️ ONE markdown pipeline: the viewer calls `_renderMarkdown(text, { breaks: false })` (marked + the DOMPurify allowlist, the Response Viewer's; chat keeps the default `breaks: true`, a file must not turn every hard wrap into a `<br>`) and binds the Response Viewer's click delegate (`_bindResponseViewerInteractions`) on the preview body for code-copy buttons and path links; never a second parser or handler. ⚠️ The document is built inside a `<template>` (a detached div with `innerHTML` set starts fetching every `<img src>` before the rewrite), then `_rebaseFilePreviewMarkdownRefs()` points relative images at the workspace-confined `file-raw` under the document's directory and root-relative ones under the workspace root (never a widened route; a failed load degrades to alt text), after `decodeURIComponent`ing the ref and dropping `?query`/`#fragment` (marked percent-encodes destinations, and the route encodes again), and turns workspace links into `a.rv-path` carrying `data-session-id` for the delegate (the linkifier's absolute paths get it too), stripping the `target` marked gave them. ⚠️ A preview opened by attachment id under a bare file name (attachment cards, history drawer: the registry keeps no relative path) has no directory, so its workspace refs degrade (images to alt text, links to their text), never resolve against the workspace root. ⚠️ The container carries `data-i18n-skip` or the translator rewrites the document's prose. ⚠️ Toggles are per-device localStorage keys (`codeman:filePreview*`), never `SettingsUpdateSchema`; Lines/Wrap are class flips on the ONE `<pre>`, with rules scoped `.file-preview-body > pre.file-preview-text` so they never leak into the document's code blocks. Markdown fetches `lines=10000` (the route ceiling), other text keeps 500. ⚠️ `md`/`markdown` are IN `FILE_PREVIEW_EXTENSIONS` (owner decision 2026-10-13): a markdown path clicked or tapped in the TERMINAL (main pane, grid tiles and split Pane B share `registerFilePathLinkProvider`) opens this rendered view like every other surface, never the streaming log viewer; other in-workspace text keeps the tail viewer (live follow). The terminal pattern links `.markdown` and `.htm` too. Tests: `test/file-preview-markdown.test.ts`. → [architecture-invariants#file-viewer-text-view-rendered-markdown-and-text-toggles](../../docs/architecture-invariants.md#file-viewer-text-view-rendered-markdown-and-text-toggles)
 
diff --git a/src/web/public/image-input.js b/src/web/public/image-input.js
index d2d5fd603..58bf68cef 100644
--- a/src/web/public/image-input.js
+++ b/src/web/public/image-input.js
@@ -193,7 +193,10 @@ Object.assign(CodemanApp.prototype, {
   // the result for images. Works on plain HTTP (no Clipboard API needed).
   // `target` names the terminal the Ctrl+V came from and its session; both
   // default to the primary pane. A second terminal (the split pane) passes its
-  // own, so text pastes into THAT xterm and images upload to THAT session.
+  // own. Images upload to THAT session. Plain text goes to that pane's session
+  // as a Codeman-built bracketed-paste frame: the terminal is only refocused
+  // and receives input(framed). onData delivers the frame; it is not written
+  // into the xterm buffer.
   _handleImagePaste(target = {}) {
     const self = this;
     const terminal = target.terminal || this.terminal;
@@ -244,14 +247,17 @@ Object.assign(CodemanApp.prototype, {
 
       if (imageFiles.length > 0) {
         self._uploadAndInsertImages(imageFiles, { sessionId: sessionId });
-      } else if (text) {
+      } else if (text && terminal) {
         // No image. xterm's paste() emits CSI 200~/201~ only while its DECSET
         // 2004 mirror is on, and a terminal replay clears that mirror, so the
         // markers never arrive and a copied newline submits (#716). Build the
-        // frame here, the same bytes keyboard-accessory.js sends, and deliver
-        // it on the session input path. Do not useMux: the mux fallback strips
-        // every \r, which is the line separator inside the frame.
-        self._deliverBracketedPaste(sessionId, text);
+        // frame here and hand it to this terminal through input(). That fires
+        // onData as user input (scroll to the bottom, clear the selection).
+        // The main pane's bracketed-paste branch and a tile's _onTerminalData
+        // deliver it, including the local-echo flush (#219). Do not also write
+        // the frame from here.
+        const body = text.replace(/\x1b\[20[01]~/g, '').replace(/\r?\n/g, '\r');
+        terminal.input(`\x1b[200~${body}\x1b[201~`);
       }
     });
 
@@ -260,50 +266,6 @@ Object.assign(CodemanApp.prototype, {
     document.execCommand('paste');
   },
 
-  /**
-   * Plain-text Ctrl+V as one bracketed paste on the session-bound input path.
-   * Mirrors keyboard-accessory.js `_sendBracketedPaste`: drop nested 200/201
-   * markers (a clipboard carrying ESC[201~ would end the bracket early), map
-   * newlines to CR (what xterm's prepareTextForTerminal did), wrap with
-   * CSI 200~ / CSI 201~. The composer's length cap is not applied here;
-   * `_sendInputAsync` already splits a large paste and refuses one past its
-   * own ceiling.
-   *
-   * When the local-echo overlay owns this session's prompt, flush its unsent
-   * text first and delay the frame. That is the onData bracketed-paste branch
-   * (#219): Codex drops bytes that share a PTY read with a bracketed paste,
-   * and the typed prefix has to land ahead of the block.
-   */
-  _deliverBracketedPaste(sessionId, text) {
-    if (!sessionId || typeof text !== 'string' || text === '' || typeof this._sendInputAsync !== 'function') return;
-    try {
-      this._predictiveEcho?.clearPredictions?.();
-    } catch {
-      // Predictions are visual only.
-    }
-    const pasteText = text.replace(/\x1b\[20[01]~/g, '').replace(/\r?\n/g, '\r');
-    const framed = `\x1b[200~${pasteText}\x1b[201~`;
-    const echoOwns =
-      this.activeSessionId === sessionId &&
-      this._localEchoEnabled &&
-      this._localEchoOverlay &&
-      !this._echoPassthroughSessions?.has?.(sessionId) &&
-      !this._tilesOwnTerminal?.() &&
-      typeof this._flushLocalEchoPending === 'function';
-    if (echoOwns) {
-      const hadPending = !!this._localEchoOverlay.pendingText;
-      this._flushLocalEchoPending();
-      if (hadPending) {
-        const prefix = this._pendingInput || '';
-        this._pendingInput = '';
-        if (prefix) this._sendInputAsync(sessionId, prefix);
-        setTimeout(() => this._sendInputAsync(sessionId, framed), 80);
-        return;
-      }
-    }
-    this._sendInputAsync(sessionId, framed);
-  },
-
   /** What a pick or a paste may upload: 'image', 'video' for the camera roll's
    *  clips (the server streams those to disk under their own cap), 'document'
    *  for the office and text files the server admits, else null. The one filter
diff --git a/src/web/public/terminal-tile.js b/src/web/public/terminal-tile.js
index ba24ec51d..a069eeee7 100644
--- a/src/web/public/terminal-tile.js
+++ b/src/web/public/terminal-tile.js
@@ -344,9 +344,10 @@
         if (global.app?.tileShortcutFor?.(ev)) return false;
         // Ctrl+V / Cmd+V: the primary pane's paste trap, aimed at THIS pane, so
         // a pasted image uploads to this pane's session and its path is typed
-        // here, and pasted text goes into this xterm with its bracketed-paste
-        // markers intact. Mirrors terminal-ui.js's own Ctrl+V gate; without it
-        // xterm's default only ever pasted text.
+        // here. Plain text goes to this pane's session as a Codeman-built
+        // bracketed-paste frame; this terminal is only refocused and receives
+        // input(framed), which onData delivers. Mirrors terminal-ui.js's own
+        // Ctrl+V gate; without it xterm's default only ever pasted text.
         if ((ev.ctrlKey || ev.metaKey) && ev.key === 'v' && ev.type === 'keydown') {
           global.app?._handleImagePaste?.({ terminal: this.terminal, sessionId: this.sessionId });
           return false;
diff --git a/test/image-paste-trap.test.ts b/test/image-paste-trap.test.ts
index 238a0d4c2..e1aaf32e9 100644
--- a/test/image-paste-trap.test.ts
+++ b/test/image-paste-trap.test.ts
@@ -38,15 +38,25 @@ interface SentInput {
   data: string;
 }
 
+interface TargetTerminal {
+  input: (data: string) => void;
+  paste?: (text: string) => void;
+  focus?: () => void;
+}
+
 interface Harness {
   /** Fire a paste event on the trap the last _handleImagePaste() call created. */
   firePaste: (payload: { text?: string; images?: string[] }) => void;
   /** Text handed to xterm's terminal.paste(), one entry per call. */
   pastedText: string[];
-  /** Frames handed to _sendInputAsync(), in order. */
+  /** Frames handed to the primary terminal's input(), one entry per call. */
+  inputted: string[];
+  /** Frames handed to _sendInputAsync(), in order. The trap must not deliver text this way. */
   sentInputs: SentInput[];
-  /** How many times predictive-echo predictions were cleared. */
+  /** How many times predictive-echo predictions were cleared by the trap. */
   predictionsCleared: () => number;
+  /** Unsent overlay text still held after the paste. Empty when local echo was not set up. */
+  pendingEcho: () => string;
   /** Image batches handed to _uploadAndInsertImages(), one entry per call. */
   uploadedBatches: Array<Array<{ type: string }>>;
   /** Messages handed to showToast(), one entry per call. */
@@ -59,8 +69,10 @@ interface Harness {
 interface PasteHarnessOptions {
   /** Session the paste trap is aimed at. Defaults to the active session. */
   sessionId?: string;
-  /** Unsent overlay text. Enables the local-echo flush path when set. */
+  /** Unsent overlay text. The trap must leave this for onData to flush. */
   localEchoPending?: string;
+  /** Terminal the Ctrl+V came from, when it is not the primary pane. */
+  terminal?: TargetTerminal;
 }
 
 function loadPasteHarness(options: PasteHarnessOptions = {}): Harness {
@@ -115,30 +127,44 @@ function loadPasteHarness(options: PasteHarnessOptions = {}): Harness {
   const CodemanApp = vm.runInContext('CodemanApp', context) as new () => Record<string, unknown>;
 
   const pastedText: string[] = [];
+  const inputted: string[] = [];
   const sentInputs: SentInput[] = [];
   const uploadedBatches: Array<Array<{ type: string }>> = [];
   let predictionsCleared = 0;
+  let pendingEcho = '';
   const app = new CodemanApp();
   app.activeSessionId = 'session-1';
   // Replay leaves xterm's DECSET 2004 mirror off. Text must still go out bracketed,
-  // and must not ask terminal.paste() to consult that mirror (#716).
+  // and must not ask terminal.paste() to consult that mirror (#716). input() is
+  // what a real xterm fires onData from, with wasUserInput (scroll + clear selection).
   app.terminal = {
     paste: (text: string) => pastedText.push(text),
+    input: (data: string) => inputted.push(data),
     focus: () => {},
     modes: { bracketedPasteMode: false },
   };
   app._sendInputAsync = (sessionId: string, data: string) => {
     sentInputs.push({ sessionId, data });
   };
-  app._predictiveEcho = { clearPredictions: () => { predictionsCleared += 1; } };
+  app._predictiveEcho = {
+    clearPredictions: () => {
+      predictionsCleared += 1;
+    },
+  };
   app._uploadAndInsertImages = (files: Array<{ type: string }>) => {
     uploadedBatches.push(Array.from(files));
   };
   if (options.localEchoPending !== undefined) {
+    pendingEcho = options.localEchoPending;
     app._localEchoEnabled = true;
     app._pendingInput = '';
     app._localEchoOverlay = {
-      pendingText: options.localEchoPending,
+      get pendingText() {
+        return pendingEcho;
+      },
+      set pendingText(value: string) {
+        pendingEcho = value;
+      },
       clear() {
         this.pendingText = '';
       },
@@ -158,7 +184,10 @@ function loadPasteHarness(options: PasteHarnessOptions = {}): Harness {
   const toasts: string[] = [];
   app.showToast = (message: string) => toasts.push(message);
 
-  const target = options.sessionId ? { terminal: app.terminal, sessionId: options.sessionId } : undefined;
+  const target =
+    options.sessionId || options.terminal
+      ? { terminal: options.terminal ?? app.terminal, sessionId: options.sessionId || 'session-1' }
+      : undefined;
   (app._handleImagePaste as (t?: object) => void).call(app, target);
 
   return {
@@ -175,8 +204,10 @@ function loadPasteHarness(options: PasteHarnessOptions = {}): Harness {
       for (const fn of listeners) fn(event);
     },
     pastedText,
+    inputted,
     sentInputs,
     predictionsCleared: () => predictionsCleared,
+    pendingEcho: () => pendingEcho,
     uploadedBatches,
     toasts,
     attachedTraps: () => attached.size,
@@ -203,16 +234,19 @@ function loadImageInputApp() {
 }
 
 describe('Ctrl+V paste trap', () => {
-  it('sends clipboard text once as a bracketed paste, not through xterm paste()', () => {
+  it('hands clipboard text to terminal.input as one bracketed paste, not through paste() or the session path', () => {
     const h = loadPasteHarness();
 
     h.firePaste({ text: 'hello world' });
 
     // terminal.paste() would drop the markers: the harness mirror is off, which
-    // is what a replay leaves behind.
+    // is what a replay leaves behind. input() is the public entry that fires
+    // onData with wasUserInput, so the pane scrolls and the selection clears.
+    // Delivery belongs to that onData handler, not a second write from here.
     expect(h.pastedText).toEqual([]);
-    expect(h.sentInputs).toEqual([{ sessionId: 'session-1', data: '\x1b[200~hello world\x1b[201~' }]);
-    expect(h.predictionsCleared()).toBe(1);
+    expect(h.inputted).toEqual(['\x1b[200~hello world\x1b[201~']);
+    expect(h.sentInputs).toEqual([]);
+    expect(h.predictionsCleared()).toBe(0);
   });
 
   it('brackets a multi-line paste and strips nested paste markers', () => {
@@ -221,31 +255,51 @@ describe('Ctrl+V paste trap', () => {
     h.firePaste({ text: 'line one\nline two\r\n\x1b[200~nested\x1b[201~\n' });
 
     expect(h.pastedText).toEqual([]);
-    expect(h.sentInputs).toEqual([
-      { sessionId: 'session-1', data: '\x1b[200~line one\rline two\rnested\r\x1b[201~' },
-    ]);
+    expect(h.inputted).toEqual(['\x1b[200~line one\rline two\rnested\r\x1b[201~']);
+    expect(h.sentInputs).toEqual([]);
   });
 
   it('addresses the bracketed paste to the pane that received Ctrl+V', () => {
-    const h = loadPasteHarness({ sessionId: 'pane-b' });
+    const paneInputs: string[] = [];
+    const pane: TargetTerminal = {
+      input: (data) => paneInputs.push(data),
+      paste: () => {
+        throw new Error('paste() must not run');
+      },
+      focus: () => {},
+    };
+    const h = loadPasteHarness({ sessionId: 'pane-b', terminal: pane });
 
     h.firePaste({ text: 'into pane b' });
 
-    expect(h.sentInputs).toEqual([{ sessionId: 'pane-b', data: '\x1b[200~into pane b\x1b[201~' }]);
+    expect(paneInputs).toEqual(['\x1b[200~into pane b\x1b[201~']);
+    expect(h.inputted).toEqual([]);
+    expect(h.sentInputs).toEqual([]);
     expect(h.pastedText).toEqual([]);
   });
 
-  it('flushes unsent local-echo text ahead of the bracketed paste', () => {
+  it('leaves unsent local-echo text for onData, instead of flushing it itself', () => {
     const h = loadPasteHarness({ localEchoPending: 'hi' });
 
     h.firePaste({ text: 'world\n' });
-
-    expect(h.sentInputs).toEqual([{ sessionId: 'session-1', data: 'hi' }]);
     h.runTimers();
-    expect(h.sentInputs).toEqual([
-      { sessionId: 'session-1', data: 'hi' },
-      { sessionId: 'session-1', data: '\x1b[200~world\r\x1b[201~' },
-    ]);
+
+    // terminal.input() fires the main pane's onData, whose bracketed-paste
+    // branch flushes the overlay and delays the frame (#219). Flushing here
+    // as well would put the prefix on the wire twice.
+    expect(h.pendingEcho()).toBe('hi');
+    expect(h.inputted).toEqual(['\x1b[200~world\r\x1b[201~']);
+    expect(h.sentInputs).toEqual([]);
+    expect(h.pastedText).toEqual([]);
+  });
+
+  it('keeps a clipboard that looks like a query reply or a mouse report inside the frame', () => {
+    const h = loadPasteHarness();
+
+    h.firePaste({ text: '\x1b[?1;2c\n\x1b[<0;10;5M\n\x1b[I' });
+
+    expect(h.inputted).toEqual(['\x1b[200~\x1b[?1;2c\r\x1b[<0;10;5M\r\x1b[I\x1b[201~']);
+    expect(h.sentInputs).toEqual([]);
     expect(h.pastedText).toEqual([]);
   });
 
@@ -257,7 +311,8 @@ describe('Ctrl+V paste trap', () => {
     h.firePaste({ text: 'hello world' });
     h.firePaste({ text: 'hello world' });
 
-    expect(h.sentInputs).toEqual([{ sessionId: 'session-1', data: '\x1b[200~hello world\x1b[201~' }]);
+    expect(h.inputted).toEqual(['\x1b[200~hello world\x1b[201~']);
+    expect(h.sentInputs).toEqual([]);
     expect(h.pastedText).toEqual([]);
   });
 
@@ -288,7 +343,8 @@ describe('Ctrl+V paste trap', () => {
     // Copying from a document can carry both: the text is what the user gets.
     h.firePaste({ text: 'echo hi', images: ['application/x-sh'] });
 
-    expect(h.sentInputs).toEqual([{ sessionId: 'session-1', data: '\x1b[200~echo hi\x1b[201~' }]);
+    expect(h.inputted).toEqual(['\x1b[200~echo hi\x1b[201~']);
+    expect(h.sentInputs).toEqual([]);
     expect(h.pastedText).toEqual([]);
     expect(h.uploadedBatches).toEqual([]);
     expect(h.toasts).toEqual([]);
diff --git a/test/terminal-tile-input.test.ts b/test/terminal-tile-input.test.ts
index 4df588d3f..649997137 100644
--- a/test/terminal-tile-input.test.ts
+++ b/test/terminal-tile-input.test.ts
@@ -282,6 +282,27 @@ describe('what xterm generates never enters the durable queue', () => {
     expect(ws.inputFrames()).toEqual([{ t: 'i', d: '\x1b[I' }]);
     expect(app._pendingDeliveries.get('s-tile')).toBeUndefined();
   });
+
+  it('queues a Ctrl+V bracketed-paste frame on the durable path', async () => {
+    // image-input.js hands this shape to terminal.input(). onData must not
+    // drop it as a query reply or send it once as a mouse/focus report: the
+    // same two predicates gate the primary pane before its bracketed-paste branch.
+    const app = makeApp();
+    const { ws, term } = await connectTile(app);
+    ws.open();
+    const input = windowStub.CodemanTerminalInput as {
+      shouldSuppressTerminalQueryResponse(data: string): boolean;
+      isTerminalFocusOrMouseReport(data: string): boolean;
+    };
+    const framed = '\x1b[200~line one\r\x1b[?1;2c\r\x1b[<0;10;5M\r\x1b[I\x1b[201~';
+
+    expect(input.shouldSuppressTerminalQueryResponse(framed)).toBe(false);
+    expect(input.isTerminalFocusOrMouseReport(framed)).toBe(false);
+    term.type(framed);
+
+    expect(ws.inputFrames().map((f) => [f.d, f.seq, f.cid])).toEqual([[framed, 1, 'c-test']]);
+    expect(app._pendingDeliveries.get('s-tile')?.map((r) => r.data)).toEqual([framed]);
+  });
 });
 
 describe('TerminalTile leaves the input-socket map', () => {