@pi-archimedes/image-paste 2.8.0 → 2.9.1

package/README.md

@@ -47,9 +47,9 @@ New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0.
 
 ## Per-platform requirements
 
-- **Linux** — a graphical session (`DISPLAY` or `WAYLAND_DISPLAY`) and one of `wl-clipboard` (tried first on Wayland sessions), `xclip` (tried first on X11), or the `@mariozechner/clipboard` native module. Termux is not supported.
-- **macOS** — the only image reader on macOS is the `@mariozechner/clipboard` native module (no other CLI fallback); it ships inside the `pi-coding-agent` installation but must be importable from the extension's location, so if your Pi install's layout puts it out of resolution reach, a read reports the reader as unavailable — make the module resolvable beside the extension and `/reload`.
-- **Windows** — the `@mariozechner/clipboard` native module first, with a PowerShell fallback.
+- **Linux** — a graphical session (`DISPLAY` or `WAYLAND_DISPLAY`) and one of `wl-clipboard` (tried first on Wayland sessions), `xclip` (tried first on X11), or `@earendil-works/pi-tui` native clipboard bindings. Termux is not supported.
+- **macOS** — `@earendil-works/pi-tui` bundled native clipboard helper.
+- **Windows** — `@earendil-works/pi-tui` native clipboard helper first, with a PowerShell fallback.
 
 ## Settings
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/image-paste",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -19,15 +19,15 @@
     "./keybinding-offer": "./src/keybinding-offer.ts"
   },
   "dependencies": {
-    "@pi-archimedes/core": "2.8.0"
+    "@pi-archimedes/core": "2.9.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.1.0",
-    "@earendil-works/pi-tui": ">=0.1.0"
+    "@earendil-works/pi-coding-agent": ">=0.86.0",
+    "@earendil-works/pi-tui": ">=0.86.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.87.0",
+    "@earendil-works/pi-tui": "^0.87.0",
     "typescript": "^6.0.0"
   },
   "pi": {

package/src/clipboard.test.ts

@@ -0,0 +1,311 @@
+import { EventEmitter } from "node:events";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { mockGetImage, mockGetNativeClipboard, mockConvertToPng, mockSpawn, mockSpawnSync } = vi.hoisted(() => {
+  return {
+    mockGetImage: vi.fn(),
+    mockGetNativeClipboard: vi.fn(),
+    mockConvertToPng: vi.fn(),
+    mockSpawn: vi.fn(),
+    mockSpawnSync: vi.fn(),
+  };
+});
+
+vi.mock("@earendil-works/pi-tui", () => ({
+  getNativeClipboard: mockGetNativeClipboard,
+}));
+
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  convertToPng: mockConvertToPng,
+}));
+
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return {
+    ...actual,
+    spawn: mockSpawn,
+    spawnSync: mockSpawnSync,
+  };
+});
+
+import { readClipboardImage, readClipboardImageViaNativeModule } from "./clipboard.js";
+
+function createMockChildProcess(stdoutData = "", exitCode = 0) {
+  const child = new EventEmitter() as any;
+  child.stdout = new EventEmitter();
+  child.kill = vi.fn();
+  setTimeout(() => {
+    if (stdoutData) {
+      child.stdout.emit("data", Buffer.from(stdoutData));
+    }
+    child.emit("close", exitCode);
+  }, 5);
+  return child;
+}
+
+describe("readClipboardImage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("macOS path", () => {
+    it("returns PNG image when getNativeClipboard() returns PNG bytes", async () => {
+      const pngBytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+      mockGetImage.mockResolvedValue(pngBytes);
+      mockGetNativeClipboard.mockReturnValue({ getImage: mockGetImage });
+
+      const result = await readClipboardImage({ platform: "darwin", environment: {} });
+
+      expect(mockGetNativeClipboard).toHaveBeenCalled();
+      expect(mockGetImage).toHaveBeenCalled();
+      expect(result).toEqual({
+        bytes: pngBytes,
+        mimeType: "image/png",
+      });
+    });
+
+    it("returns null when getNativeClipboard() returns empty (null)", async () => {
+      mockGetImage.mockResolvedValue(null);
+      mockGetNativeClipboard.mockReturnValue({ getImage: mockGetImage });
+
+      const result = await readClipboardImage({ platform: "darwin", environment: {} });
+
+      expect(mockGetNativeClipboard).toHaveBeenCalled();
+      expect(mockGetImage).toHaveBeenCalled();
+      expect(result).toBeNull();
+    });
+
+    it("returns null when getNativeClipboard() returns empty Uint8Array", async () => {
+      mockGetImage.mockResolvedValue(new Uint8Array(0));
+      mockGetNativeClipboard.mockReturnValue({ getImage: mockGetImage });
+
+      const result = await readClipboardImage({ platform: "darwin", environment: {} });
+
+      expect(mockGetNativeClipboard).toHaveBeenCalled();
+      expect(mockGetImage).toHaveBeenCalled();
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("Windows path", () => {
+    it("converts BMP bytes to PNG via convertToPng and returns { bytes, mimeType }", async () => {
+      const bmpBytes = new Uint8Array([0x42, 0x4d, 0x10, 0x20, 0x30]);
+      mockGetImage.mockResolvedValue(bmpBytes);
+      mockGetNativeClipboard.mockReturnValue({ getImage: mockGetImage });
+
+      const pngBytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 1, 2, 3]);
+      const base64Png = Buffer.from(pngBytes).toString("base64");
+      mockConvertToPng.mockResolvedValue({ data: base64Png, mimeType: "image/png" });
+
+      const result = await readClipboardImage({ platform: "win32", environment: {} });
+
+      expect(mockGetNativeClipboard).toHaveBeenCalled();
+      expect(mockGetImage).toHaveBeenCalled();
+      expect(mockConvertToPng).toHaveBeenCalledWith(
+        Buffer.from(bmpBytes).toString("base64"),
+        "image/bmp",
+      );
+      expect(result).toEqual({
+        bytes: pngBytes,
+        mimeType: "image/png",
+      });
+      expect(mockSpawn).not.toHaveBeenCalled();
+    });
+
+    it("returns non-BMP bytes directly as image/png without convertToPng", async () => {
+      const pngBytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 1, 2, 3]);
+      mockGetImage.mockResolvedValue(pngBytes);
+      mockGetNativeClipboard.mockReturnValue({ getImage: mockGetImage });
+
+      const result = await readClipboardImage({ platform: "win32", environment: {} });
+
+      expect(mockConvertToPng).not.toHaveBeenCalled();
+      expect(result).toEqual({
+        bytes: pngBytes,
+        mimeType: "image/png",
+      });
+      expect(mockSpawn).not.toHaveBeenCalled();
+    });
+
+    it("falls back to PowerShell when convertToPng returns null", async () => {
+      const bmpBytes = new Uint8Array([0x42, 0x4d, 0x10, 0x20]);
+      mockGetImage.mockResolvedValue(bmpBytes);
+      mockGetNativeClipboard.mockReturnValue({ getImage: mockGetImage });
+      mockConvertToPng.mockResolvedValue(null);
+
+      const fallbackBytes = new Uint8Array([1, 2, 3, 4]);
+      mockSpawn.mockImplementation(() =>
+        createMockChildProcess(Buffer.from(fallbackBytes).toString("base64"), 0),
+      );
+
+      const result = await readClipboardImage({ platform: "win32", environment: {} });
+
+      expect(mockConvertToPng).toHaveBeenCalled();
+      expect(mockSpawn).toHaveBeenCalled();
+      expect(result).toEqual({
+        bytes: fallbackBytes,
+        mimeType: "image/png",
+      });
+    });
+
+    it("falls back to PowerShell when native.getImage() throws", async () => {
+      mockGetImage.mockRejectedValue(new Error("Native failure"));
+      mockGetNativeClipboard.mockReturnValue({ getImage: mockGetImage });
+
+      const fallbackBytes = new Uint8Array([5, 6, 7, 8]);
+      mockSpawn.mockImplementation(() =>
+        createMockChildProcess(Buffer.from(fallbackBytes).toString("base64"), 0),
+      );
+
+      const result = await readClipboardImage({ platform: "win32", environment: {} });
+
+      expect(mockSpawn).toHaveBeenCalled();
+      expect(result).toEqual({
+        bytes: fallbackBytes,
+        mimeType: "image/png",
+      });
+    });
+
+    it("falls back to PowerShell when getNativeClipboard() returns undefined", async () => {
+      mockGetNativeClipboard.mockReturnValue(undefined);
+
+      const fallbackBytes = new Uint8Array([9, 10, 11]);
+      mockSpawn.mockImplementation(() =>
+        createMockChildProcess(Buffer.from(fallbackBytes).toString("base64"), 0),
+      );
+
+      const result = await readClipboardImage({ platform: "win32", environment: {} });
+
+      expect(mockSpawn).toHaveBeenCalled();
+      expect(result).toEqual({
+        bytes: fallbackBytes,
+        mimeType: "image/png",
+      });
+    });
+
+    it("logs a console.warn when PowerShell stdout exceeds MAX_BUFFER_BYTES", async () => {
+      mockGetNativeClipboard.mockReturnValue(undefined);
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      const child = new EventEmitter() as any;
+      child.stdout = new EventEmitter();
+      child.kill = vi.fn();
+      mockSpawn.mockImplementation(() => {
+        setTimeout(() => {
+          child.stdout.emit("data", Buffer.alloc(50 * 1024 * 1024 + 1));
+          child.emit("close", 0);
+        }, 5);
+        return child;
+      });
+
+      const result = await readClipboardImage({ platform: "win32", environment: {} });
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[archimedes] Clipboard image exceeded maximum buffer size (50MB)",
+      );
+      expect(result).toBeNull();
+      warnSpy.mockRestore();
+    });
+  });
+
+  describe("Unavailable reader error messages", () => {
+    it("reports pi-tui native clipboard or CLI tools instead of @mariozechner/clipboard on darwin", async () => {
+      mockGetNativeClipboard.mockReturnValue(undefined);
+
+      await expect(
+        readClipboardImage({ platform: "darwin", environment: {} }),
+      ).rejects.toThrow(/@earendil-works\/pi-tui native clipboard or CLI tools/);
+    });
+
+    it("reports pi-tui native clipboard or CLI tools instead of @mariozechner/clipboard on win32", async () => {
+      mockGetNativeClipboard.mockReturnValue(undefined);
+      const child = new EventEmitter() as any;
+      child.stdout = new EventEmitter();
+      child.kill = vi.fn();
+      mockSpawn.mockImplementation(() => {
+        setTimeout(() => {
+          const err = new Error("Command not found") as NodeJS.ErrnoException;
+          err.code = "ENOENT";
+          child.emit("error", err);
+        }, 5);
+        return child;
+      });
+
+      await expect(
+        readClipboardImage({ platform: "win32", environment: {} }),
+      ).rejects.toThrow(/@earendil-works\/pi-tui native clipboard or CLI tools/);
+    });
+  });
+
+  describe("Linux paths", () => {
+    it("prefers Wayland (wl-paste attempted first) when WAYLAND_DISPLAY is set", async () => {
+      mockSpawnSync.mockImplementation((command: string, args: string[]) => {
+        if (command === "wl-paste" && args[0] === "--list-types") {
+          return { status: 0, stdout: Buffer.from("image/png\n"), error: undefined };
+        }
+        if (command === "wl-paste" && args[0] === "--type") {
+          return { status: 0, stdout: Buffer.from([1, 2, 3, 4]), error: undefined };
+        }
+        return { status: 1, stdout: Buffer.alloc(0), error: undefined };
+      });
+
+      const result = await readClipboardImage({
+        platform: "linux",
+        environment: { WAYLAND_DISPLAY: "wayland-0" },
+      });
+
+      expect(mockSpawnSync).toHaveBeenCalled();
+      expect(mockSpawnSync.mock.calls[0]![0]).toBe("wl-paste");
+      expect(result).toEqual({
+        bytes: new Uint8Array([1, 2, 3, 4]),
+        mimeType: "image/png",
+      });
+    });
+
+    it("prefers X11 (xclip attempted first) when DISPLAY is set without Wayland", async () => {
+      mockSpawnSync.mockImplementation((command: string, args: string[]) => {
+        if (command === "xclip" && args.includes("TARGETS")) {
+          return { status: 0, stdout: Buffer.from("image/png\n"), error: undefined };
+        }
+        if (command === "xclip" && args.includes("image/png")) {
+          return { status: 0, stdout: Buffer.from([5, 6, 7]), error: undefined };
+        }
+        return { status: 1, stdout: Buffer.alloc(0), error: undefined };
+      });
+
+      const result = await readClipboardImage({
+        platform: "linux",
+        environment: { DISPLAY: ":0" },
+      });
+
+      expect(mockSpawnSync).toHaveBeenCalled();
+      expect(mockSpawnSync.mock.calls[0]![0]).toBe("xclip");
+      expect(result).toEqual({
+        bytes: new Uint8Array([5, 6, 7]),
+        mimeType: "image/png",
+      });
+    });
+
+    it("throws appropriate graphical session error when DISPLAY and WAYLAND_DISPLAY are missing", async () => {
+      await expect(
+        readClipboardImage({ platform: "linux", environment: {} }),
+      ).rejects.toThrow(
+        "Clipboard image paste requires a graphical desktop session with DISPLAY or WAYLAND_DISPLAY.",
+      );
+    });
+
+    it("TERMUX_VERSION returns { available: false, image: null } from native module and null from readClipboardImage", async () => {
+      const nativeResult = await readClipboardImageViaNativeModule("linux", {
+        TERMUX_VERSION: "0.118.0",
+        DISPLAY: ":0",
+      });
+      expect(nativeResult).toEqual({ available: false, image: null });
+
+      const result = await readClipboardImage({
+        platform: "linux",
+        environment: { TERMUX_VERSION: "0.118.0", DISPLAY: ":0" },
+      });
+      expect(result).toBeNull();
+    });
+  });
+});

package/src/clipboard.ts

@@ -1,11 +1,11 @@
 import { spawn, spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
-import type { ClipboardImage } from "./types.js";
+import { convertToPng } from "@earendil-works/pi-coding-agent";
+import { getNativeClipboard } from "@earendil-works/pi-tui";
 
-const require = createRequire(import.meta.url);
+import type { ClipboardImage } from "./types.js";
 
 const LIST_TYPES_TIMEOUT_MS = 1000;
 const READ_TIMEOUT_MS = 5000;
@@ -18,25 +18,13 @@ const SUPPORTED_IMAGE_MIME_TYPES = [
   "image/bmp",
 ] as const;
 
-let cachedClipboardModule: ClipboardModule | null | undefined;
-
-/** Reset the clipboard module cache — allows retry after install. */
-export function resetClipboardModuleCache(): void {
-  cachedClipboardModule = undefined;
-}
-
-interface ClipboardModule {
-  hasImage: () => boolean;
-  getImageBinary: () => Promise<Array<number> | Uint8Array>;
-}
-
 interface CommandResult {
   ok: boolean;
   stdout: Buffer;
   missingCommand: boolean;
 }
 
-interface ClipboardReadResult {
+export interface ClipboardReadResult {
   available: boolean;
   image: ClipboardImage | null;
 }
@@ -74,54 +62,53 @@ function selectPreferredImageMimeType(mimeTypes: readonly string[]): string | nu
   return firstImage?.raw ?? null;
 }
 
-function loadClipboardModule(
-  platform: NodeJS.Platform = process.platform,
-  environment: NodeJS.ProcessEnv = process.env,
-): ClipboardModule | null {
-  if (cachedClipboardModule !== undefined) {
-    return cachedClipboardModule;
-  }
-
-  if (environment.TERMUX_VERSION || !hasGraphicalSession(platform, environment)) {
-    cachedClipboardModule = null;
-    return cachedClipboardModule;
-  }
-
-  try {
-    cachedClipboardModule = require("@mariozechner/clipboard") as ClipboardModule;
-  } catch {
-    cachedClipboardModule = null;
-  }
-
-  return cachedClipboardModule;
-}
-
-async function readClipboardImageViaNativeModule(
+export async function readClipboardImageViaNativeModule(
   platform: NodeJS.Platform,
   environment: NodeJS.ProcessEnv,
 ): Promise<ClipboardReadResult> {
-  const clipboard = loadClipboardModule(platform, environment);
-  if (!clipboard) {
+  if (environment.TERMUX_VERSION || !hasGraphicalSession(platform, environment)) {
     return { available: false, image: null };
   }
 
-  if (!clipboard.hasImage()) {
-    return { available: true, image: null };
-  }
+  try {
+    const native = getNativeClipboard();
+    if (!native) {
+      return { available: false, image: null };
+    }
 
-  const imageData = await clipboard.getImageBinary();
-  if (!imageData || imageData.length === 0) {
-    return { available: true, image: null };
-  }
+    const bytes = await native.getImage();
+    if (!bytes || bytes.length === 0) {
+      return { available: true, image: null };
+    }
 
-  const bytes = imageData instanceof Uint8Array ? imageData : Uint8Array.from(imageData);
-  return {
-    available: true,
-    image: {
-      bytes,
-      mimeType: "image/png",
-    },
-  };
+    const rawBytes = bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes);
+
+    if (platform === "win32") {
+      if (rawBytes.length >= 2 && rawBytes[0] === 0x42 && rawBytes[1] === 0x4d) {
+        const png = await convertToPng(Buffer.from(rawBytes).toString("base64"), "image/bmp");
+        if (png) {
+          return {
+            available: true,
+            image: {
+              bytes: Uint8Array.from(Buffer.from(png.data, "base64")),
+              mimeType: png.mimeType,
+            },
+          };
+        }
+        return { available: false, image: null };
+      }
+    }
+
+    return {
+      available: true,
+      image: {
+        bytes: rawBytes,
+        mimeType: "image/png",
+      },
+    };
+  } catch {
+    return { available: false, image: null };
+  }
 }
 
 function runCommand(
@@ -209,7 +196,10 @@ try {
     let exceededMaxBuffer = false;
     child.stdout?.on("data", (data: Buffer) => {
       if (stdout.length + data.length > MAX_BUFFER_BYTES) {
-        exceededMaxBuffer = true;
+        if (!exceededMaxBuffer) {
+          exceededMaxBuffer = true;
+          console.warn("[archimedes] Clipboard image exceeded maximum buffer size (50MB)");
+        }
         return;
       }
       stdout += data.toString("utf8");
@@ -345,11 +335,11 @@ function readClipboardImageViaXclip(): ClipboardReadResult {
 function getUnavailableReaderMessage(platform: NodeJS.Platform): string {
   switch (platform) {
     case "linux":
-      return "No Linux clipboard image reader is available. Install wl-clipboard or xclip, or ensure @mariozechner/clipboard is installed.";
+      return "No Linux clipboard image reader is available. Install wl-clipboard or xclip, or ensure @earendil-works/pi-tui native clipboard or CLI tools are available.";
     case "darwin":
-      return "No macOS clipboard image reader is available. Ensure @mariozechner/clipboard is installed.";
+      return "No macOS clipboard image reader is available. Ensure @earendil-works/pi-tui native clipboard or CLI tools are available.";
     case "win32":
-      return "No Windows clipboard image reader is available. Ensure PowerShell is available or @mariozechner/clipboard is installed.";
+      return "No Windows clipboard image reader is available. Ensure PowerShell is available or @earendil-works/pi-tui native clipboard or CLI tools are available.";
     default:
       return `Clipboard image paste is not supported on platform: ${platform}`;
   }

package/src/keybinding-offer.test.ts

@@ -174,7 +174,11 @@ describe("offerKeybindingFix — gate matrix", () => {
       if (outcome === "yes") confirm.mockResolvedValue(true);
       else confirm.mockResolvedValue(false); // no + cancel: confirm resolves false
 
-      await offerKeybindingFix(ctx);
+      // All matrix rows use a base-shape ctx (no reload), so the offer
+      // resolves `false` — the `true` contract is covered by the
+      // auto-reload branch tests below.
+      const result = await offerKeybindingFix(ctx);
+      expect(result).toBe(false);
 
       const shouldAsk =
         enabled === true &&
@@ -251,7 +255,8 @@ describe("flag write preserves existing settings", () => {
     });
     const { ctx, confirm } = makeCtx("tui");
     confirm.mockResolvedValue(outcome === "yes");
-    await offerKeybindingFix(ctx);
+    // Base-shape ctx (no reload) → resolves `false` on both outcomes.
+    expect(await offerKeybindingFix(ctx)).toBe(false);
   }
 
   it("yes: snippet file written; other archimedes.imagePaste keys survive the flag set", async () => {
@@ -291,7 +296,8 @@ describe("file write throws → flag stays false (self-heals next session)", ()
     const { ctx, confirm, notify } = makeCtx("tui");
     confirm.mockResolvedValue(true);
 
-    await expect(offerKeybindingFix(ctx)).resolves.toBeUndefined();
+    // Write failed → the offer never reloaded → `false`.
+    await expect(offerKeybindingFix(ctx)).resolves.toBe(false);
 
     expect(confirm).toHaveBeenCalledTimes(1);
     expect(fs.existsSync(keybindingsPath())).toBe(false);
@@ -316,7 +322,8 @@ describe("flag write throws → notify, no crash (file write already succeeded)"
     const { ctx, confirm, notify } = makeCtx("tui");
     confirm.mockResolvedValue(true);
 
-    await expect(offerKeybindingFix(ctx)).resolves.toBeUndefined();
+    // Base-shape ctx (no reload) → `false`, even though the file was written.
+    await expect(offerKeybindingFix(ctx)).resolves.toBe(false);
 
     // The file write strictly precedes the flag set and survived:
     expect(fs.readFileSync(keybindingsPath(), "utf-8")).toBe(SNIPPET);
@@ -343,7 +350,9 @@ describe("accept with base-shape ctx (no reload)", () => {
     const { ctx, confirm, notify } = makeCtx("tui");
     confirm.mockResolvedValue(true);
 
-    await expect(offerKeybindingFix(ctx)).resolves.toBeUndefined();
+    // No reload on this ctx → the user is told to run /reload manually,
+    // so the offer did NOT trigger a reload → `false`.
+    await expect(offerKeybindingFix(ctx)).resolves.toBe(false);
 
     // File written with the exact snippet
     expect(fs.readFileSync(keybindingsPath(), "utf-8")).toBe(SNIPPET);
@@ -390,8 +399,10 @@ describe("auto-reload branch (future Pi with reload on the event ctx)", () => {
       if ((args[0] as string) === CREATED_NOTIFY) order.push("notify");
     });
 
-    await offerKeybindingFix(ctx);
+    const result = await offerKeybindingFix(ctx);
 
+    // The successful accept + reload() path resolves `true`
+    expect(result).toBe(true);
     // reload called exactly once
     expect(reload).toHaveBeenCalledTimes(1);
     // flag was already set when reload ran
@@ -411,14 +422,15 @@ describe("auto-reload branch (future Pi with reload on the event ctx)", () => {
   it("no path: reload NOT called", async () => {
     const { ctx, confirm, reload } = makeCtx("tui", { withReload: true });
     confirm.mockResolvedValue(false);
-    await offerKeybindingFix(ctx);
+    // Decline: no reload → `false`.
+    expect(await offerKeybindingFix(ctx)).toBe(false);
     expect(reload).not.toHaveBeenCalled();
   });
 
   it("cancel (resolves false) path: reload NOT called", async () => {
     const { ctx, confirm, reload } = makeCtx("tui", { withReload: true });
     confirm.mockResolvedValue(false); // Esc/timeout: same as no
-    await offerKeybindingFix(ctx);
+    expect(await offerKeybindingFix(ctx)).toBe(false);
     expect(reload).not.toHaveBeenCalled();
   });
 
@@ -427,7 +439,7 @@ describe("auto-reload branch (future Pi with reload on the event ctx)", () => {
     fs.mkdirSync(tmpPath(), { recursive: true });
     const { ctx, confirm, reload } = makeCtx("tui", { withReload: true });
     confirm.mockResolvedValue(true);
-    await offerKeybindingFix(ctx);
+    expect(await offerKeybindingFix(ctx)).toBe(false);
     expect(reload).not.toHaveBeenCalled();
   });
 
@@ -450,16 +462,19 @@ describe("auto-reload branch (future Pi with reload on the event ctx)", () => {
 
     const { ctx, confirm, reload } = makeCtx("tui", { withReload: true });
     confirm.mockResolvedValue(true);
-    await offerKeybindingFix(ctx);
+    expect(await offerKeybindingFix(ctx)).toBe(false);
     expect(reload).not.toHaveBeenCalled();
   });
 
-  it("reload rejects: offer still resolves, flag persisted, file present, CREATED_NOTIFY emitted", async () => {
+  it("reload rejects: offer still resolves (false), flag persisted, file present, CREATED_NOTIFY emitted", async () => {
     const { ctx, confirm, notify, reload } = makeCtx("tui", { withReload: true });
     confirm.mockResolvedValue(true);
     reload!.mockRejectedValue(new Error("Reload failed"));
 
-    await expect(offerKeybindingFix(ctx)).resolves.toBeUndefined();
+    // The reload FAILED: the TUI shows its own "Reload failed" status and the
+    // session continues on the (still-valid) ctx, so the offer reports `false`
+    // — the onboarding still runs on this session.
+    await expect(offerKeybindingFix(ctx)).resolves.toBe(false);
 
     // File must have been written
     expect(fs.readFileSync(keybindingsPath(), "utf-8")).toBe(SNIPPET);
@@ -502,7 +517,8 @@ describe("concurrent creation is never clobbered", () => {
     const { ctx, confirm, notify } = makeCtx("tui");
     confirm.mockResolvedValue(true);
 
-    await expect(offerKeybindingFix(ctx)).resolves.toBeUndefined();
+    // The offer ended before the reload step → `false`.
+    await expect(offerKeybindingFix(ctx)).resolves.toBe(false);
 
     // The concurrently created file is never clobbered by the snippet
     expect(fs.readFileSync(keybindingsPath(), "utf-8")).toBe(CONCURRENT_CONTENT);

package/src/keybinding-offer.ts

@@ -75,8 +75,19 @@ function markPromptDone(ctx: ExtensionContext): void {
  * tears down). This counts as a decline — the flag is set and the offer will
  * not appear again. To reset it, delete `archimedes.imagePaste.keybindingsPromptDone`
  * from `~/.pi/agent/settings.json`.
+ *
+ * **Return contract:** resolves `true` iff the offer triggered a successful
+ * `ctx.reload()` (the successful-accept path on a ctx that exposes `reload()`
+ * and the reload completed). Every other outcome — the gates (1–4), decline,
+ * a failed file write, the file-exists race, a base-shape ctx without
+ * `reload` (manual /reload hint), and a reload that itself failed (the TUI
+ * shows its own "Reload failed" and the session continues on the still-valid
+ * ctx) — resolves `false`. The meta factory uses this to sequence the
+ * first-run flows: if `true`, the reloaded session runs the flow again (where
+ * the offer is a no-op — keybindings.json now exists), so it skips the
+ * onboarding on the now-stale ctx.
  */
-export async function offerKeybindingFix(ctx: ExtensionContext): Promise<void> {
+export async function offerKeybindingFix(ctx: ExtensionContext): Promise<boolean> {
   // Gate 1: extension on.
   // NOTE: reading archimedes.imagePaste.enabled in-package is a sanctioned
   // exception to the AGENTS.md "Plugin on/off" rule and ADR 0012 — this
@@ -84,24 +95,24 @@ export async function offerKeybindingFix(ctx: ExtensionContext): Promise<void> {
   // registration, so there is no registration gate to catch it here.
   // See docs/decisions/0012-plugin-gate-in-package-namespace.md § Exception.
   if (!isConfigEnabled(NAMESPACE)) {
-    return;
+    return false;
   }
 
   // Gate 2: interactive TUI only. Deliberate: the flag is NOT consumed in
   // non-TUI modes, so a later TUI session still gets the offer.
   if (ctx.mode !== "tui") {
-    return;
+    return false;
   }
 
   // Gate 3: not yet consumed
   if (loadConfig<PromptConfig>(NAMESPACE, { ...PROMPT_DEFAULTS }).keybindingsPromptDone === true) {
-    return;
+    return false;
   }
 
   // Gate 4: file absent — never merge into or rewrite an existing user file
   const keybindingsPath = join(getAgentDir(), "keybindings.json");
   if (existsSync(keybindingsPath)) {
-    return;
+    return false;
   }
 
   // Gate 5: ask (confirm signature is TITLE first — docs/extensions.md:165)
@@ -111,7 +122,7 @@ export async function offerKeybindingFix(ctx: ExtensionContext): Promise<void> {
   // as decline): set the flag and do nothing else.
   if (!confirmed) {
     markPromptDone(ctx);
-    return;
+    return false;
   }
 
   // Yes: write the file atomically (tmp + rename) — strictly BEFORE the flag
@@ -130,7 +141,7 @@ export async function offerKeybindingFix(ctx: ExtensionContext): Promise<void> {
         // ignore
       }
       markPromptDone(ctx);
-      return;
+      return false;
     }
     renameSync(tmpPath, keybindingsPath);
   } catch (error) {
@@ -145,7 +156,7 @@ export async function offerKeybindingFix(ctx: ExtensionContext): Promise<void> {
       `Could not create keybindings.json: ${messageOf(error)}`,
       "warning",
     );
-    return;
+    return false;
   }
 
   // File written successfully → THEN set the flag (deliberately after the
@@ -170,11 +181,18 @@ export async function offerKeybindingFix(ctx: ExtensionContext): Promise<void> {
     ctx.ui.notify(CREATED_NOTIFY, "info");
     try {
       await reload();
+      // The reload completed: the reloaded session runs the flow again (where
+      // the offer is a no-op — keybindings.json now exists), so report that a
+      // reload was triggered and the caller can skip the onboarding on this
+      // now-stale ctx.
+      return true;
     } catch {
       // Swallowed on purpose: the TUI shows its own "Reload failed" status;
-      // the offer never throws.
+      // the offer never throws. The reload FAILED, so the session continues on
+      // the still-valid ctx → report `false` (the onboarding still runs).
+      return false;
     }
-  } else {
-    ctx.ui.notify(CREATED_RELOAD_HINT, "info");
   }
+  ctx.ui.notify(CREATED_RELOAD_HINT, "info");
+  return false;
 }