@pi-archimedes/image-paste 2.10.4 → 2.11.0

package/src/paste-dispatch.test.ts

@@ -0,0 +1,516 @@
+import { describe, expect, it, vi } from "vitest";
+import { Editor, type EditorTheme, type TUI } from "@earendil-works/pi-tui";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// The three clipboard readers are the seam: the dispatch under test decides
+// *which* of them wins, and the real ones would shell out to wl-paste / xclip
+// and open the X11 display during a unit test. `isImageFilePath` stays real —
+// the no-double-attach case asserts its premise, so mocking it would be
+// circular.
+const { mockReadClipboardImage, mockReadClipboardFilePaths, mockReadClipboardText } = vi.hoisted(() => ({
+  mockReadClipboardImage: vi.fn(),
+  mockReadClipboardFilePaths: vi.fn(),
+  mockReadClipboardText: vi.fn(),
+}));
+
+vi.mock("./clipboard.js", async (importOriginal) => {
+  const real = await importOriginal<typeof import("./clipboard.js")>();
+  return {
+    ...real,
+    readClipboardImage: mockReadClipboardImage,
+    readClipboardFilePaths: mockReadClipboardFilePaths,
+    readClipboardText: mockReadClipboardText,
+  };
+});
+
+import { createImageQueue, dispatchClipboardPaste, type ImageQueue } from "./index.js";
+import { isImageFilePath } from "./clipboard.js";
+
+// ── The editor is real, not a stub ──────────────────────────────────────────
+//
+// `ctx.ui.pasteToEditor` is pi's bracketed-paste wiring verbatim
+// (interactive-mode.js:2075: `this.editor.handleInput("\x1b[200~" + text +
+// "\x1b[201~")`) and `getEditorText` is :2077 (`getExpandedText?.() ??
+// getText()`), so the assertions below read the text a real pi-tui `Editor`
+// ends up holding — including the editor's own paste handling (its leading
+// space for `/`-leading pastes, its large-paste collapse marker), not a
+// hand-written approximation of it. Only the renderer is faked: `Editor`
+// touches `tui.requestRender()` and `tui.terminal.rows` and nothing else on
+// this path.
+interface Harness {
+  ctx: ExtensionContext;
+  queue: ImageQueue;
+  editor: Editor;
+  inserted: string[];
+  /** Drafts the editor submitted (Enter) — a clipboard must never cause one. */
+  submitted: string[];
+  notifications: Array<[string, string | undefined]>;
+}
+
+function createHarness(options?: { editorText?: string }): Harness {
+  const editor = new Editor(
+    { requestRender: () => {}, terminal: { rows: 40, cols: 120 } } as unknown as TUI,
+    { borderColor: (s: string) => s, selectList: {} } as unknown as EditorTheme,
+  );
+  const submitted: string[] = [];
+  editor.onSubmit = (text: string) => {
+    submitted.push(text);
+  };
+  if (options?.editorText) {
+    editor.setText(options.editorText);
+  }
+
+  const inserted: string[] = [];
+  const notifications: Array<[string, string | undefined]> = [];
+  const ctx = {
+    hasUI: true,
+    ui: {
+      pasteToEditor: (text: string) => {
+        inserted.push(text);
+        editor.handleInput(`\x1b[200~${text}\x1b[201~`);
+      },
+      getEditorText: () => editor.getExpandedText?.() ?? editor.getText(),
+      notify: (message: string, type?: "info" | "warning" | "error") => {
+        notifications.push([message, type]);
+      },
+    },
+  } as unknown as ExtensionContext;
+
+  return { ctx, queue: createImageQueue(), editor, inserted, submitted, notifications };
+}
+
+function editorText(h: Harness): string {
+  return h.editor.getExpandedText?.() ?? h.editor.getText();
+}
+
+const PNG = { bytes: new Uint8Array([0x89, 0x50, 0x4e, 0x47]), mimeType: "image/png" };
+
+describe("dispatchClipboardPaste: precedence image → file paths → text", () => {
+  it("attaches the image and never consults the path reader when both are on the clipboard", async () => {
+    const h = createHarness();
+    mockReadClipboardImage.mockResolvedValue(PNG);
+    mockReadClipboardFilePaths.mockResolvedValue(["/tmp/also-on-clipboard.txt"]);
+    mockReadClipboardText.mockResolvedValue("also text");
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // The image branch wins *first*: the path reader is not even reached.
+    // This is the whole point of diverging from pi's native order, so the
+    // assertion is on the call, not just on the visible outcome.
+    expect(mockReadClipboardFilePaths).not.toHaveBeenCalled();
+    expect(mockReadClipboardText).not.toHaveBeenCalled();
+    expect(h.inserted).toEqual(["[Image #1] "]);
+    expect(h.notifications).toEqual([["Image attached from clipboard.", "info"]]);
+    expect(h.queue.images).toHaveLength(1);
+    expect(editorText(h)).toBe("[Image #1] ");
+  });
+
+  it("inserts clipboard file paths with pi's spacing when there is no image", async () => {
+    const h = createHarness({ editorText: "look at" });
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(["/tmp/report.pdf"]);
+    mockReadClipboardText.mockResolvedValue("ignored text");
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // pi: character before the cursor is non-whitespace → one leading space;
+    // nothing after it → no trailing space (interactive-mode.js:2507-2511).
+    expect(h.inserted).toEqual([" /tmp/report.pdf"]);
+    expect(editorText(h)).toBe("look at /tmp/report.pdf");
+    expect(h.notifications).toEqual([]);
+    expect(h.queue.images).toHaveLength(0);
+  });
+
+  it("inserts clipboard text when there is neither an image nor file paths", async () => {
+    const h = createHarness({ editorText: "summarise " });
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(null);
+    mockReadClipboardText.mockResolvedValue("the pasted paragraph");
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    expect(h.inserted).toEqual(["the pasted paragraph"]);
+    expect(editorText(h)).toBe("summarise the pasted paragraph");
+    expect(h.notifications).toEqual([]);
+  });
+
+  it("adds no leading space when the draft ends in a newline (the cursor is on a fresh line)", async () => {
+    const h = createHarness({ editorText: "look at\n" });
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(["/tmp/report.pdf"]);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // pi reads the cursor's own line, and that line is empty (:2506-2509), so
+    // the path lands bare on the second line — asserted against the real
+    // editor, which is what actually splits the paste across lines.
+    expect(h.inserted).toEqual(["/tmp/report.pdf"]);
+    expect(editorText(h)).toBe("look at\n/tmp/report.pdf");
+  });
+
+  it("inserts nothing and notifies nothing when the clipboard holds nothing (pi is silent here)", async () => {
+    const h = createHarness();
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(null);
+    mockReadClipboardText.mockResolvedValue(null);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    expect(h.inserted).toEqual([]);
+    expect(h.notifications).toEqual([]);
+  });
+
+  it("still pastes text when the image reader cannot run at all (no reader is not an empty clipboard)", async () => {
+    const h = createHarness();
+    mockReadClipboardImage.mockRejectedValue(
+      new Error("Clipboard image paste requires a graphical desktop session with DISPLAY or WAYLAND_DISPLAY."),
+    );
+    mockReadClipboardFilePaths.mockResolvedValue(null);
+    mockReadClipboardText.mockResolvedValue("text from a headless session");
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    expect(h.inserted).toEqual(["text from a headless session"]);
+    expect(h.notifications).toEqual([]);
+  });
+
+  it("reports the reader failure when nothing else was on the clipboard", async () => {
+    const h = createHarness();
+    mockReadClipboardImage.mockRejectedValue(new Error("no clipboard reader available"));
+    mockReadClipboardFilePaths.mockResolvedValue(null);
+    mockReadClipboardText.mockResolvedValue(null);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    expect(h.inserted).toEqual([]);
+    expect(h.notifications).toEqual([["Clipboard paste failed: no clipboard reader available", "warning"]]);
+  });
+
+  it("keeps the size limit as a hard stop: an oversized image does not fall through to paths", async () => {
+    const h = createHarness();
+    mockReadClipboardImage.mockResolvedValue({
+      bytes: new Uint8Array(20 * 1024 * 1024 + 1),
+      mimeType: "image/png",
+    });
+    mockReadClipboardFilePaths.mockResolvedValue(["/tmp/report.pdf"]);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    expect(h.inserted).toEqual([]);
+    expect(h.notifications[0]?.[0]).toMatch(/Image too large/);
+    expect(h.notifications[0]?.[1]).toBe("warning");
+  });
+});
+
+describe("dispatchClipboardPaste: pi's path branch details", () => {
+  it("refuses a path containing control characters instead of inserting it", async () => {
+    const h = createHarness();
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(["/tmp/ok.txt", "/tmp/bad\nname.txt"]);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // interactive-mode.js:2501-2503 throws rather than inserting; the user
+    // gets the failure, the editor gets nothing.
+    expect(h.inserted).toEqual([]);
+    expect(h.notifications).toEqual([
+      ["Clipboard paste failed: Clipboard file path contains control characters", "warning"],
+    ]);
+  });
+
+  it("inserts a copied image file as path text and attaches nothing (one branch per keypress)", async () => {
+    // Premise, from this package's own predicate: the path IS an image path.
+    expect(isImageFilePath("/tmp/screenshot.png")).toBe(true);
+
+    const h = createHarness();
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(["/tmp/screenshot.png"]);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // Intended behaviour (ADR 0030: the path branch matches pi): a file
+    // copied in the file manager is a *path* on the clipboard, not image
+    // bytes, so it is inserted as text and never read off disk. Because
+    // exactly one branch runs per keypress, a path can never be attached as
+    // well — nothing double-attaches, and the queue stays empty.
+    expect(h.inserted).toEqual(["/tmp/screenshot.png"]);
+    expect(editorText(h)).toBe("/tmp/screenshot.png");
+    expect(h.queue.images).toHaveLength(0);
+    expect(h.queue.markers).toHaveLength(0);
+    expect(h.notifications).toEqual([]);
+  });
+
+  it("joins a multi-path clipboard with newlines and keeps pi's surrounding spaces", async () => {
+    const h = createHarness({ editorText: "compare" });
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(["/tmp/one.txt", "/tmp/two.txt", "/tmp/three.txt"]);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    expect(h.inserted).toEqual([" /tmp/one.txt\n/tmp/two.txt\n/tmp/three.txt"]);
+    expect(editorText(h)).toBe("compare /tmp/one.txt\n/tmp/two.txt\n/tmp/three.txt");
+  });
+
+  it("quotes and space-joins paths when the draft is a bash command (pi's isBashMode branch)", async () => {
+    const h = createHarness({ editorText: "!ls " });
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(["/tmp/a file.txt", "/tmp/plain.txt"]);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // interactive-mode.js:2504 quotes each path when the draft starts with "!"
+    // and joins with spaces, so the shell sees two arguments.
+    expect(h.inserted).toEqual(["'/tmp/a file.txt' /tmp/plain.txt"]);
+    expect(editorText(h)).toBe("!ls '/tmp/a file.txt' /tmp/plain.txt");
+  });
+
+  it("pins what a large multi-path clipboard looks like: the editor's own paste collapse", async () => {
+    // The one place where the available insertion mechanism differs from pi's.
+    // pi writes `${leading}${paths}${trailing}` with insertTextAtCursor, which
+    // it does not expose to extensions; `ctx.ui.pasteToEditor` is a bracketed
+    // paste, and pi-tui's editor collapses a paste of more than 10 lines or
+    // 1000 characters to a marker (components/editor.js:1094-1109). Measured,
+    // not assumed: 12 paths render as `compare [paste #1 +12 lines]` and
+    // `getExpandedText()` — what pi submits — returns all twelve paths, so the
+    // draft the model receives is identical to pi's and only the display text
+    // differs. 5 paths, under the threshold, are inserted literally.
+    const h = createHarness({ editorText: "compare " });
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(
+      Array.from({ length: 12 }, (_unused, index) => `/tmp/path-${index}.txt`),
+    );
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // No leading space: the draft ends in whitespace, so pi's rule adds none.
+    expect(h.inserted).toHaveLength(1);
+    expect(h.inserted[0]).toMatch(/^\/tmp\/path-0\.txt\n/);
+    expect(h.editor.getText()).toBe("compare [paste #1 +12 lines]");
+    expect(editorText(h)).toBe(`compare ${h.inserted.join("")}`);
+  });
+
+  it("inserts a five-path clipboard literally, under the editor's collapse threshold", async () => {
+    const h = createHarness({ editorText: "a" });
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(["/tmp/p0.txt", "/tmp/p1.txt", "/tmp/p2.txt", "/tmp/p3.txt", "/tmp/p4.txt"]);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    expect(editorText(h)).toBe("a /tmp/p0.txt\n/tmp/p1.txt\n/tmp/p2.txt\n/tmp/p3.txt\n/tmp/p4.txt");
+  });
+
+  it("pins the known cursor limitation: the extension API exposes no cursor, so a mid-line paste loses pi's trailing space", async () => {
+    // A live check, and the honest record of the gap: `ExtensionUIContext`
+    // offers pasteToEditor / getEditorText / setEditorText and no cursor
+    // accessor (dist/core/extensions/types.d.ts:132-137), so the spacing rule
+    // can only be computed against the end of the draft. Here the cursor sits
+    // mid-line (after "alph"), where pi would also add a trailing space; we
+    // cannot see it and produce the run-on "x.txta" where pi produces
+    // "x.txt a". The rule itself is exact — see buildPathInsertion's
+    // cursor-mid-line case in clipboard.test.ts, which passes the cursor.
+    const h = createHarness({ editorText: "alpha" });
+    // "alpha" typed one character at a time leaves the cursor after the "a";
+    // move it back one grapheme so the paste lands mid-line.
+    h.editor.handleInput("\x1b[D");
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(["/tmp/x.txt"]);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    expect(h.inserted).toEqual([" /tmp/x.txt"]);
+    expect(editorText(h)).toBe("alph /tmp/x.txta");
+  });
+});
+
+describe("dispatchClipboardPaste: clipboard text that is not plain text", () => {
+  // The text branch hands the clipboard to `ctx.ui.pasteToEditor`, which is
+  // pi's bracketed-paste wiring (`editor.handleInput("\x1b[200~" + text +
+  // "\x1b[201~")`, interactive-mode.js:2075). pi-tui ends a paste at the first
+  // `\x1b[201~` it finds and re-feeds the remainder of the chunk to
+  // `handleInput` (components/editor.js:569-590), so an escape byte that came
+  // *from the clipboard* ends the paste early — and the tail of the clipboard
+  // is lost or reinterpreted. pi's own text branch cannot lose it: it writes
+  // bytes with `insertTextAtCursor` (:2528). These cases pin what the
+  // available insert route does with the payloads that difference separates.
+  const withText = (text: string): void => {
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(null);
+    mockReadClipboardText.mockResolvedValue(text);
+  };
+
+  it("keeps the whole clipboard when it carries a paste-framing escape sequence", async () => {
+    const h = createHarness();
+    withText("hi\u001b[201~!echo pwned\r");
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // Measured without the fix: the draft ended up as "hi\n" — everything
+    // after the escape byte was swallowed by the paste-boundary break, which
+    // pi does not do for the same clipboard.
+    const draft = editorText(h);
+    expect(draft).toContain("hi");
+    expect(draft).toContain("echo pwned");
+    expect(draft).not.toContain("\u001b");
+    // And the break must not reach the editor as a keystroke: the draft is
+    // inserted, never submitted.
+    expect(h.submitted).toEqual([]);
+    expect(h.notifications).toEqual([]);
+  });
+
+  it("keeps the visible text of a payload with a bare escape byte", async () => {
+    const h = createHarness();
+    withText("hi\u001b[31mred");
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // The escape byte goes (pi keeps it raw — it can, we cannot); no other
+    // character is lost, and the parameter tail stays as the plain text it is.
+    expect(editorText(h)).toBe("hi[31mred");
+    expect(h.submitted).toEqual([]);
+  });
+
+  it("drops NUL and BEL the way a terminal paste does, and inserts the rest", async () => {
+    const h = createHarness();
+    withText("hi\u0000wo\u0007");
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // pi-tui's own paste filter removes characters below 0x20 except \n
+    // (components/editor.js:1070-1074), so the buffer is clean without the
+    // dispatch having to pre-filter — the divergence from pi here is that pi
+    // stores the raw bytes ("hi\u0000wo\u0007") and we do not.
+    expect(editorText(h)).toBe("hiwo");
+    expect(h.editor.getText()).not.toMatch(/[\u0000-\u0008\u000b-\u001f]/);
+  });
+
+  it("normalises CRLF and a trailing CR to newlines, as pi's insert route does", async () => {
+    const h = createHarness();
+    withText("a\r\nb\r");
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // normalizeText in pi-tui (components/editor.js:953-955) is shared by both
+    // insert routes, so the two agree here: measured "a\nb\n" either way.
+    expect(editorText(h)).toBe("a\nb\n");
+  });
+
+  it("keeps a trailing newline rather than trimming it, as pi does", async () => {
+    const h = createHarness({ editorText: "summarise " });
+    withText("hello\n");
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // pi inserts the clipboard verbatim (:2528) and a trailing newline from
+    // xclip/xsel (no --no-newline in pi's candidate for X11) is part of it.
+    expect(editorText(h)).toBe("summarise hello\n");
+  });
+
+  it("collapses a 1MB clipboard to the editor's paste marker and submits the whole thing", async () => {
+    const h = createHarness();
+    const oneMb = "line of text\n".repeat(80_000); // ~1.04 MB
+    withText(oneMb);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    // The draft shows the marker; what pi submits is the expanded text, so no
+    // character is lost — measured against the same payload through pi's
+    // insertTextAtCursor route, which holds it inline instead.
+    expect(h.editor.getText()).toMatch(/^\[paste #1 \+\d+ lines\]$/);
+    expect(editorText(h)).toBe(oneMb);
+    expect(h.submitted).toEqual([]);
+  });
+});
+
+describe("dispatchClipboardPaste: screen-mode independence", () => {
+  // The paste path is screen-mode independent because it never holds or
+  // touches a renderer: the only surfaces it uses are the three screen-safe
+  // extension UI methods. This is the mechanical statement of that claim —
+  // anything reaching for `tui`, an overlay or a component fails it, and the
+  // suite-wide renderer-hoarding guard (core/src/screen-mode-discipline.test.ts)
+  // covers the stored-reference half.
+  //
+  // What is under test is what the dispatch *reads*, so `ctx.ui` is replaced
+  // with a Proxy that records every property access and throws on any name
+  // outside the allow-list. (An earlier version asserted `Object.keys(ctx.ui)`
+  // — the shape of this harness, which the dispatch cannot widen, so a dispatch
+  // that started calling `ctx.ui.setWidget` passed it. Greptile on PR #123;
+  // the mutation `(ctx.ui as …).setStatus?.("k", "v")` in the dispatch turns
+  // these red and left that assertion green.)
+  const SCREEN_SAFE_SURFACES = ["getEditorText", "notify", "pasteToEditor"];
+
+  /** Replace `h.ctx.ui` with a recorder/guard and return the access log. */
+  function guardUiSurfaces(h: Harness): string[] {
+    const accessed: string[] = [];
+    const inner = h.ctx.ui as unknown as Record<string, unknown>;
+    (h.ctx as unknown as { ui: unknown }).ui = new Proxy(inner, {
+      get(target, property: string | symbol): unknown {
+        if (typeof property !== "string") return undefined;
+        accessed.push(property);
+        if (!SCREEN_SAFE_SURFACES.includes(property)) {
+          throw new Error(`ctx.ui.${property} is not a screen-safe surface`);
+        }
+        return target[property];
+      },
+    });
+    return accessed;
+  }
+
+  function surfacesUsed(accessed: string[]): string[] {
+    return [...new Set(accessed)].sort();
+  }
+
+  function assertNoGuardTrip(h: Harness): void {
+    // A tripped guard is swallowed by the dispatch's own catch and reported as
+    // a paste failure, so a clean run is part of the assertion.
+    expect(h.notifications.filter(([message]) => message.startsWith("Clipboard paste failed"))).toEqual([]);
+  }
+
+  it("reads only pasteToEditor and notify on the image branch", async () => {
+    const h = createHarness();
+    const accessed = guardUiSurfaces(h);
+    mockReadClipboardImage.mockResolvedValue(PNG);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    expect(surfacesUsed(accessed)).toEqual(["notify", "pasteToEditor"]);
+    assertNoGuardTrip(h);
+  });
+
+  it("reads only getEditorText and pasteToEditor on the file-path branch", async () => {
+    const h = createHarness({ editorText: "compare" });
+    const accessed = guardUiSurfaces(h);
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(["/tmp/one.txt"]);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    expect(surfacesUsed(accessed)).toEqual(["getEditorText", "pasteToEditor"]);
+    assertNoGuardTrip(h);
+  });
+
+  it("reads only pasteToEditor on the text branch", async () => {
+    const h = createHarness();
+    const accessed = guardUiSurfaces(h);
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(null);
+    mockReadClipboardText.mockResolvedValue("plain text");
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    expect(surfacesUsed(accessed)).toEqual(["pasteToEditor"]);
+    assertNoGuardTrip(h);
+  });
+
+  it("reads no UI surface at all when the clipboard holds nothing", async () => {
+    const h = createHarness();
+    const accessed = guardUiSurfaces(h);
+    mockReadClipboardImage.mockResolvedValue(null);
+    mockReadClipboardFilePaths.mockResolvedValue(null);
+    mockReadClipboardText.mockResolvedValue(null);
+
+    await dispatchClipboardPaste(h.ctx, h.queue);
+
+    expect(accessed).toEqual([]);
+    assertNoGuardTrip(h);
+  });
+});

package/src/paste-mutex.test.ts

@@ -0,0 +1,165 @@
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+// The mutex lives in the shortcut handler in `index.ts` and the readers live in
+// `clipboard.ts`, so this file deliberately mocks *neither*: the real dispatch
+// runs against a faked clipboard helper and a faked command runner, which is the
+// only way to ask the question that matters to a user — does `ctrl+v` come back?
+const { mockGetNativeClipboard, mockSpawnSync } = vi.hoisted(() => ({
+  mockGetNativeClipboard: vi.fn(),
+  mockSpawnSync: vi.fn(),
+}));
+
+vi.mock("@earendil-works/pi-tui", async (importOriginal) => {
+  const real = await importOriginal<typeof import("@earendil-works/pi-tui")>();
+  return { ...real, getNativeClipboard: mockGetNativeClipboard };
+});
+
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return { ...actual, spawnSync: mockSpawnSync };
+});
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { initImagePasteSession, registerImagePaste } from "./index.js";
+import { NATIVE_READ_TIMEOUT_MS } from "./clipboard.js";
+
+/** Every CLI candidate is missing, so the native helper is the only reader. */
+function noCLITools(): void {
+  mockSpawnSync.mockImplementation((_command: string, _args: string[]) => {
+    const error = Object.assign(new Error("spawnSync ENOENT"), { code: "ENOENT" });
+    return { error, status: null, signal: null, stdout: Buffer.alloc(0), stderr: Buffer.alloc(0) };
+  });
+}
+
+interface Harness {
+  ctx: ExtensionContext;
+  press: () => Promise<void>;
+  inserted: string[];
+  notifications: Array<[string, string | undefined]>;
+}
+
+function createHarness(): Harness {
+  const inserted: string[] = [];
+  const notifications: Array<[string, string | undefined]> = [];
+  const ctx = {
+    hasUI: true,
+    ui: {
+      pasteToEditor: (text: string) => {
+        inserted.push(text);
+      },
+      getEditorText: () => "",
+      notify: (message: string, type?: "info" | "warning" | "error") => {
+        notifications.push([message, type]);
+      },
+    },
+  } as unknown as ExtensionContext;
+
+  const handlers = new Map<string, (context: ExtensionContext) => Promise<void>>();
+  const pi = {
+    registerMessageRenderer: () => {},
+    registerShortcut: (key: string, options: { handler: (context: ExtensionContext) => Promise<void> }) => {
+      handlers.set(key, options.handler);
+    },
+    on: () => {},
+  } as unknown as ExtensionAPI;
+
+  registerImagePaste(pi);
+  initImagePasteSession(ctx);
+  const pressKey = handlers.get("ctrl+v")!;
+  return { ctx, press: () => pressKey(ctx), inserted, notifications };
+}
+
+/** A helper whose every read is started and never answered. */
+function hangingHelper(): {
+  getImage: () => Promise<Uint8Array>;
+  getText: () => Promise<string>;
+  getFilePaths: () => Promise<string[]>;
+} {
+  return {
+    getImage: () => new Promise<Uint8Array>(() => {}),
+    getText: () => new Promise<string>(() => {}),
+    getFilePaths: () => new Promise<string[]>(() => {}),
+  };
+}
+
+describe("the ctrl+v mutex against a clipboard that never answers", () => {
+  const savedWayland = process.env.WAYLAND_DISPLAY;
+  const savedDisplay = process.env.DISPLAY;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    noCLITools();
+    // A graphical session, so the readers are attempted rather than skipped.
+    process.env.WAYLAND_DISPLAY = "wayland-1";
+    delete process.env.DISPLAY;
+  });
+
+  afterAll(() => {
+    process.env.WAYLAND_DISPLAY = savedWayland;
+    process.env.DISPLAY = savedDisplay;
+  });
+
+  it("settles the keypress and releases the key when the helper never answers", async () => {
+    vi.useFakeTimers();
+    try {
+      mockGetNativeClipboard.mockReturnValue(hangingHelper());
+      const h = createHarness();
+
+      const press = h.press();
+      // Nothing to wait for but our own deadline.
+      await vi.advanceTimersByTimeAsync(NATIVE_READ_TIMEOUT_MS / 2);
+      expect(h.inserted).toEqual([]);
+
+      // The user presses again while the first read is still outstanding: the
+      // mutex is allowed to swallow this one, but not forever.
+      const whileBusy = h.press();
+      await vi.advanceTimersByTimeAsync(NATIVE_READ_TIMEOUT_MS / 2);
+      await whileBusy;
+      expect(h.inserted).toEqual([]);
+
+      await vi.advanceTimersByTimeAsync(NATIVE_READ_TIMEOUT_MS * 3);
+      // RED without a deadline on the native read: this await never finishes,
+      // the promise stays pending, and every later press is dropped by the
+      // `_pasting` mutex — `ctrl+v` is dead until the session restarts, with no
+      // message saying so (measured live: first press still pending after
+      // 7.1 s, both later presses silently swallowed, nothing notified).
+      await expect(press).resolves.toBeUndefined();
+
+      // And the key works again: the next press reaches the readers.
+      mockGetNativeClipboard.mockReturnValue({
+        getImage: async () => null,
+        getText: async () => "text after the hang",
+        getFilePaths: async () => undefined,
+      });
+      await h.press();
+      expect(h.inserted).toEqual(["text after the hang"]);
+    } finally {
+      vi.useRealTimers();
+    }
+  }, 30_000);
+
+  it("reports a bounded failure rather than silence when the image read times out and nothing else answers", async () => {
+    vi.useFakeTimers();
+    try {
+      mockGetNativeClipboard.mockReturnValue(hangingHelper());
+      const h = createHarness();
+
+      const press = h.press();
+      await vi.advanceTimersByTimeAsync(NATIVE_READ_TIMEOUT_MS * 3);
+      await press;
+
+      // pi's dispatcher would have sat in that call forever; ours finishes.
+      // A helper that never answers is a failed read, not an empty clipboard,
+      // so the user hears about it — and hears something truer than "install a
+      // clipboard reader", which is what the missing-reader path says.
+      expect(h.inserted).toEqual([]);
+      expect(h.notifications).toHaveLength(1);
+      expect(h.notifications[0]?.[0]).toMatch(/timed out/i);
+      expect(h.notifications[0]?.[0]).not.toMatch(/No Linux clipboard image reader/);
+      expect(h.notifications[0]?.[1]).toBe("warning");
+    } finally {
+      vi.useRealTimers();
+    }
+  }, 30_000);
+});